The switch that was connected to nothing
A configuration option that the schema accepted, the docs described, the types exported — and that nothing read. The agent started, produced nothing, and reported success.
The worst bug we found in the sandbox this year did not crash anything. It did not throw, log a warning, fail a test, or show up in an error rate. It ran, returned zero, and told us everything was fine.
The configuration had an option for how a prompt reaches the agent: as a command-line argument, on standard input, or written to a file. The third one was accepted by the schema. It was in the exported types, so it was public API. It appeared in the config documentation.
Nothing implemented it.
Setting it did not fail validation. It did not warn. It reached a switch statement in the runtime that had a case for it — an empty one, with a break. The agent was spawned with no prompt at all, did nothing useful because it had been asked nothing, exited cleanly, and the run was recorded as a success.
The other one
While we were removing that, we found its sibling. The project config had a timeout_minutes field. The init wizard scaffolded it into every new project. The up command read it and converted it from minutes into milliseconds.
Then it put the result down and walked away. Nothing ever read the converted value. Every project on disk carried a timeout that had never once stopped anything.
That one is almost funnier, because there was more code. Somebody wrote a unit conversion for a number that was never used. The conversion probably had a test.
Why this class of bug survives
A crash is loud, has a stack trace, and gets fixed on Tuesday. A dead knob is silent, and the silence is actively misleading in three directions at once.
The user believes they configured something. They set a timeout, so runs are bounded. They chose file delivery, so the prompt is in a file. Their mental model of the system is now wrong, and nothing will correct it.
The tests pass, because a test for "does the config parse" passes beautifully for a field nobody reads. There was a test asserting the schema accepted "file". It did. That test was protecting the bug.
And the next person to read the code sees a case in a switch and a conversion from minutes to milliseconds and reasonably concludes the feature exists.
What we changed
For the dead delivery mode: removed it from the schema entirely. A config asking for it now fails at parse time with a message naming the two modes that work. That is a breaking change for anyone who had set it — and it should be, because those people were getting an agent with no prompt and being told it worked. Failing loudly now is strictly better than the silence they had.
For the timeout: wired it up. It is the project's idle timeout, and it now does exactly what its name has been claiming for months.
The rule we took from it is short. A configuration option must either do something or not exist. If you cannot implement it today, do not accept it today. A schema is a promise, and a promise you do not keep is worse than one you never made — because the person who trusted it has stopped watching.
Go and look
If you maintain a tool with a configuration file, this is worth an hour. Take every option your schema accepts and find the line that reads it. Not the line that parses it, validates it, normalises it, or converts its units — the line that acts on it.
Some of them will not have one.