harness-dispatch 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -4,7 +4,566 @@ Notable changes per release. Format follows [Keep a Changelog](https://keepachan
 this project uses [semantic versioning](https://semver.org/spec/v2.0.0.html) and is
 pre-1.0, so minor versions can carry behaviour changes.
 
-## [Unreleased]
+## [0.10.0] — 2026-09-06
+
+### Added
+
+- **`doctor` says whether jobs will actually run detached.** A missing
+  `dist/job-runner.js` is not an error — it is the signal to run jobs
+  in-process, which is right for an unbuilt checkout and wrong everywhere
+  else, because the concurrency cap is enforced by the supervisor pool. So the
+  bound that exists because of a measured out-of-memory crash silently stopped
+  applying, with one line on stderr at dispatch time and nothing checking it.
+  This check FAILS rather than warns, so `doctor` now exits 1 in an unbuilt
+  checkout where it previously exited 0.
+
+- **Locks left by a process that is gone are swept before each job starts.**
+  Such a lock was always reclaimable, but only when something contended for
+  that same directory — and nothing contends for a path you dispatched against
+  once and moved on from, so its file stayed indefinitely. An unreadable lock
+  is given the same grace the acquire path gives it, rather than being deleted
+  on sight: `wx` creation leaves a real empty-file window, and losing that race
+  would delete a live holder's lock.
+
+- **Empty supervisor spawn logs are cleaned up.** Keeping a crash log is
+  deliberate — a supervisor that died is the one that left a stale heartbeat,
+  and its output is the only explanation. An empty one explains nothing, and
+  the liveness check reads that directory on every drain. Measured before this:
+  129 files over three weeks, six bytes each.
+
+### Fixed
+
+- **`usage` with no routes explained itself.** It printed a bare header, which
+  reads as a broken command — the one thing it does not mean. It now says
+  there are no routes and names both ways to get one.
+
+- **`--json` is honoured when a command fails, not only when it succeeds.** A
+  bad `--config` made `doctor --json` print a sentence, so anything parsing the
+  output got a parse error instead of the reason. Four shapes bypassed the
+  envelope entirely — an unknown command, `auth` with no subcommand, `dispatch`
+  with no prompt, and the `--json=true` spelling — and the first printed the
+  help block to stdout, so `harness-dispatch frobnicate --json | jq` was fed
+  usage text. Errors stay on stderr; without `--json` the plain line is
+  unchanged.
+
+- **README:** the quick start told a new user to run `doctor --live` as step
+  three of installing without saying it contacts providers and spends quota.
+  The `configure` section was one 180-word block covering four separate
+  concerns; it is split under headings, and `configure` is now described as
+  optional where someone deciding whether to run it will see it.
+
+### Fixed
+
+- The "already applied" answer is given from one place. Both branches that
+  can reach it built the message separately and had to say the same thing by
+  hand — and it is the message a caller reads to decide whether their work
+  landed, so the two drifting apart is the exact confusion the second branch
+  was added to fix.
+
+- Five deeply nested blocks were flattened into named helpers: a rule
+  dispatch table written as a switch inside a loop, the stdout line
+  reassembly, two JSON-shape readers, an SSE frame reader, and the
+  steal-a-stale-lock path with its two nested try/catch blocks. Each is
+  behaviour-preserving and each removes a level that had nothing to do with
+  the logic underneath it.
+
+- Housekeeping the audit listed and nothing had got to: CI built the whole
+  project twice on every leg of every run (the explicit step plus the one
+  inside `npm test`); `doctor` ran its state-directory probe twice, creating
+  and deleting a file each time, to fill two fields from the same answer; an
+  alias renamed a function to itself; and 28 blank lines left behind by
+  earlier extractions are gone.
+
+- Four assertions that could not fail for the reason their test claimed.
+  `job_status` on an unknown job asserted only that *something* threw, which
+  a schema rejection also satisfies — so "a well-formed id for a job that is
+  gone" was untested. The traversal and near-miss-action refusals had the
+  same hole: both passed on "No such job", which every id in that file
+  produces, leaving the thing under test unchecked. And a parser test
+  asserted only that a normal OpenAI body did not throw, which is equally
+  true of a parser that dropped the request on the floor; it now checks the
+  request survived.
+
+- The endpoint dispatcher's two request paths share one prologue. The URL,
+  headers, timeout timer, abort wiring and fetch-error mapping were written
+  out twice and kept in step by hand — which is not a theoretical risk here:
+  the credential leak fixed in the entry above existed in both copies, and
+  the file's own header records the same shape happening before. What stays
+  a parameter is the one thing that genuinely differs, the `stream` flag and
+  its Accept header, now pinned by tests asserting what each path puts on
+  the wire. Collapsing that too is what "just drain the stream" would do,
+  and it would change every buffered endpoint request against a third-party
+  gateway.
+
+- **SECURITY, structural: configured credentials are removed where text leaves
+  the process, instead of at each place a message is built.** Six consecutive
+  reviews found the same defect — a credential reaching a caller, a log file or
+  an agent's context — and six fixes closed the path that reviewer had found.
+  Each fix was correct and each was incomplete: four of the six were "the fix
+  landed in one branch and the sibling beside it kept leaking", twice inside a
+  single file, and one round shipped a comment asserting every branch was
+  covered while one was not.
+
+  Sites were the wrong unit. There is no bounded list of places a string can be
+  built, and ordinary feature work adds more without their author having any
+  reason to think about credentials. The set of ways text LEAVES is bounded:
+  JSON for a tool result or an HTTP response, the dispatch log, job files on
+  disk, and the terminal. Those are now the places redaction happens, and the
+  secrets are derived from the loaded config rather than named per call site —
+  including the `api_keys:` block, whose entries are keyed by route name and so
+  matched no credential-looking key name, and a credential embedded in a
+  `base_url` path, which host redaction preserves by design.
+
+  Also fixed with it: `configure --print` emitted `base_url` in full while
+  redacting the api_key two lines below and printing a note implying the whole
+  preview was sanitised.
+
+  The guarantee is pinned two ways, because one of them does not reach far
+  enough and saying otherwise was itself an overclaim. Four sinks are proven
+  behaviourally: a credential of every shape a config can hold is planted, the
+  sink is driven for real, and removing its redaction fails that sink's case
+  and no other. The remaining eight have no reachable input that carries a
+  credential today — something upstream already removed it — so a behavioural
+  case for them could not fail, and inventing one would be a test passing for
+  the wrong reason. They are covered instead by an inventory that fails if the
+  redaction call disappears, which is the real risk for a guard.
+
+  An earlier version of this entry claimed all of them were proven
+  behaviourally. A verification pass sabotaged all nine call sites one at a
+  time and found five shipped green.
+
+  The first version of that test did not do this. It called the redactor on the
+  rendered output before asserting, so it proved the redactor works on a string
+  — never in doubt — and could not fail for a sink that forgot to call it. An
+  acceptance pass established that by reading, and found an unredacted
+  server-sent-event path shipping under a green suite in the same breath. The
+  streamed and buffered forms of one request behaved differently: the same
+  credential was removed from the buffered response and returned verbatim in
+  the stream.
+
+- **The redaction registry no longer treats every `${VAR}` as a credential.**
+  It was keyed off the record of resolved environment references, which covers
+  every `${VAR}` in the file — and `${VAR}` is documented as legal in any
+  string value. So `model: ${MY_MODEL}` made that model name a process-wide
+  redaction target, and `status` reported `model=<redacted>`. A harness answer
+  mentioning it would have been mangled the same way, silently, which is worse
+  than the disclosure being guarded against: wrong work product delivered as if
+  it were right. Collection now reads the fields that hold credentials.
+
+  For the same reason, a long segment in a `base_url` path is no longer assumed
+  to be a secret — that guess made an Azure deployment name
+  (`.../deployments/gpt-4-turbo-preview`) a redaction target. A path segment
+  cannot be told from a credential by inspection, so the config now says so and
+  names the route, and the user moves it to `api_key:` where it is removable by
+  value.
+
+- **SECURITY: a CLI harness quoting its own api key had it passed through to
+  the caller and into `logs/dispatches.jsonl`.** A CLI route is handed its
+  credential in an environment variable, and a harness reporting an auth
+  failure can print it back; nothing removed it. Reproduced end to end with a
+  stub harness writing `auth error: rejected key <key>` to stderr — it arrived
+  verbatim in the terminal and in the log.
+
+  Reaching it needs `api_key:` on a CLI route, which reclassifies the route as
+  metered and is then blocked by billing policy until the user explicitly opts
+  in — so it is narrower than the endpoint leaks beside it, and it is the same
+  disclosure once opted in.
+
+  The scrub wraps the dispatcher's whole event stream rather than each result
+  site. That is the point of it: this class has now been found five times, and
+  four were a fix landing in one branch while the sibling beside it kept
+  leaking. `#runStream` has five result sites plus the chunk events, and a
+  sixth added later would silently miss a per-site scrub. Chunks are scrubbed
+  too, since they become `partialOutput` and `stdout.log` on disk. A route with
+  no key — every subscription CLI — is untouched and pays nothing.
+
+- **SECURITY: an endpoint that echoed your API key back in its error body
+  had it passed straight through to the caller and into
+  `logs/dispatches.jsonl`.** Both request paths build `HTTP <status>:
+  <message>` from the response body and neither scrubbed it, while the
+  network-error paths beside them always had. So a key in the base URL's
+  query string — a documented way to configure an endpoint, and how Gemini's
+  is written — came back verbatim whenever the endpoint quoted the request
+  URL in its own 4xx body. Found by writing the test the audit said was
+  missing: scrubbing had been proven at the unit and never once from the
+  dispatcher, which is the only place it can actually leak.
+
+  It took three attempts to close, and the first two both shipped a claim
+  wider than their code. The `HTTP <status>` pair was fixed first and
+  declared the class closed; the two `describeUnusableBody` paths beside it
+  — a 200 carrying an HTML error page, which is what a gateway returns —
+  still quoted 300 raw characters of the body back. Fixing those came with
+  an assertion that every branch was covered; the mid-stream SSE `error`
+  event was not, and that is the likeliest shape of all of them, because a
+  200 with `text/event-stream` carrying an error object is how these
+  endpoints report an auth failure once the stream is open, and jobs only
+  ever stream.
+
+  Separately, the scrubber only ever removed credential-bearing parts of the
+  base URL. Every endpoint in this project's own config authenticates with an
+  `Authorization` or `x-api-key` header, so the configured key was not in the
+  URL at all and survived on every path, including the two fixed first.
+
+  All seven branches that can return an endpoint's own text now scrub, each
+  is pinned by its own test, and the code comment enumerates them rather than
+  asserting completeness — an enumeration can be checked against the file and
+  a claim of completeness is what failed twice here.
+
+- **The CLI dispatcher is now tested against a real process, not only
+  through a mock — and production no longer contains the mock detector.**
+  `stream-subprocess.ts` carried a branch in PRODUCTION that detected a
+  vitest mock on `runSubprocess` and synthesised one stdout chunk from a
+  buffered result, under a comment claiming this still exercised the
+  streaming path. It exercised it nowhere: every dispatcher suite mocked
+  `runSubprocess`, so every dispatcher suite ran the adapter. Four behaviours
+  had no test at all: a JSONL event split across two reads, a timeout that
+  really kills the child, an abort reaching a running process, and stdout
+  arriving as events during the run rather than one lump at the end. All four
+  now run against `node -e`.
+
+  The adapter has since moved into the test suite, where a suite that wants
+  it opts in by mocking the function the dispatchers actually call. Nothing
+  in `src/` now branches on being under test.
+
+- **`doctor` names a route that has never once succeeded.** The circuit
+  breaker is about RECENT failure and forgets after its cooldown, so a route
+  that is simply dead — a host that no longer resolves, a revoked key — keeps
+  being selected, keeps failing, and keeps falling back, indefinitely. On the
+  maintainer's own machine a local endpoint sat at 8 calls and 0 successes
+  while being the preferred route for `review`, so every review dispatch paid
+  for one doomed attempt first. The counts were in `usage` all along, and
+  nobody reads `usage` when things merely feel slow. Advisory, never a
+  failure: a route needs at least five calls before it is judged, because a
+  laptop that was asleep is not a broken endpoint.
+
+- Three of the six MCP tools were asserted to exist and never invoked.
+  `cancel_job`, `retry_job` and `workspace` had tests for the functions
+  underneath but nothing exercising the layer that parses a caller's
+  arguments and shapes the reply — where a schema change or a renamed field
+  breaks an orchestrator without failing anything. Now driven through the
+  real tool path, including the refusals that matter: a traversal attempt in
+  a job id, and a near-miss `action` on the one verb that is irreversible.
+
+- The workspace lock's heartbeat guard is pinned. A holder that freezes past
+  the stale window is legitimately stolen from, and its heartbeat must stop
+  writing — otherwise it destroys the new owner's claim and, worse, convinces
+  its own `release()` that it still holds the lock, deleting it out from
+  under whoever now owns it. The guard was there and uncovered; removing it
+  now fails a test that names exactly that.
+
+- **`max_concurrent_runs: 0` lifts the cap without also removing the
+  supervisor pool.** It used to short-circuit the slot queue and the pool
+  entirely, so every job got its own detached runner — measured under load at
+  8 concurrent dispatches becoming 8 runner processes at ~76 MB each, which
+  is the per-job wrapper cost the pool exists to remove, on the memory-bound
+  machine the cap exists for in the first place. Uncapped now means uncapped
+  *jobs*, with the process count still bounded by the pool. The cap is
+  represented as `null` rather than `0` or `Infinity`, because both of those
+  were wrong somewhere: `0` read as "bypass everything", and `Infinity` broke
+  pool sizing, which divides by the limit and so asked for zero supervisors.
+
+  The README and the source comment went on describing the old behaviour for
+  a further nine commits, steering users away from the setting for a reason
+  that had stopped being true. Both now say what the code does.
+
+- The contract every shipped harness owes — a missing CLI, a non-zero exit, a
+  model override, a timeout, id and availability — is asserted once per
+  harness from one table instead of being written out in four per-harness
+  files. There is no per-harness dispatcher class to begin with: each built-in
+  harness is the generic CLI dispatcher driven by a protocol block in
+  `config.default.yaml`, so those were never really four different questions.
+  They had already drifted apart, which is the argument for the table: three
+  of the four checked that nothing was even resolved before the failure, one
+  did not. A preset added to the shipped config with no row now fails a
+  completeness check. What stays per harness is what genuinely differs —
+  Codex's JSONL extraction and `--cd` handling, Cursor's workspace default and
+  Retry-After parsing, Antigravity's live streaming and safety-flag mapping,
+  Claude Code's raw-stdout fallback.
+
+- **The job store is five modules instead of one 1,600-line file**, and two
+  runtime imports that existed to dodge an import cycle are gone. The cycle
+  was real but avoidable: `config-hot-reload.ts` imported
+  `setJobRetentionDays` from the `jobs.ts` barrel rather than from
+  `jobs/store.ts`, where it is defined. Pointing it at the definition removed
+  the cycle, and the second dynamic import was guarding a cycle that never
+  existed. `jobs.ts` is now a 32-line barrel, so every consumer keeps its
+  import path.
+
+  The move surfaced a defect worth naming: `resolveRunnerPath()` resolves
+  against its own module's location, so moving it one directory deeper made
+  both its candidates miss. Returning nothing is not an error there — it is
+  the signal to run the job **in-process**, so every dispatch quietly stopped
+  being detached and the concurrency cap stopped applying, with nothing
+  failing until the job-concurrency tests ran. Fixed, with the trap written
+  down at the function.
+
+- **The tests are typechecked, and the gate enforces it.** Clearing the 125
+  errors that surfaced turned up two things a reader would have taken at face
+  value. `RetryOutcome` never declared `droppedModel` — a field `retry_job`
+  sets and the MCP tool description documents, invisible to any typed caller
+  because the object is built with a conditional spread, which TypeScript
+  does not excess-property check. And five router fixtures scored a route
+  whose billing surface was `"vendor_cli"`, a value in no union and no
+  config: they were measuring a shape that cannot occur. A test helper also
+  returned `Record<string, never>`, which made every assertion against a
+  config file it had just written unable to fail.
+
+- **The test suite's `implements Dispatcher` claims are true now, and there
+  is a way to check them.** `tsconfig.json` sets `rootDir: src` so it can
+  emit, which means a test file cannot be in the same program — so the tests
+  were never typechecked, and four stub classes declared they implemented an
+  interface while omitting a required method. That is not academic: it has
+  now cost two runtime failures that a compiler would have caught instantly,
+  one of them a stub that would have crashed the moment the router stopped
+  preferring the buffered path. The stubs implement it, with a body that
+  throws — stronger than absence, because a buffered entry point that
+  accidentally streams now fails loudly instead of passing quietly. A new
+  `tsconfig.test.json` typechecks tests against src; `npm run typecheck:tests`
+  runs it. It reported 52 remaining pre-existing errors when it landed and was
+  deliberately kept out of `npm run check` until they were cleared — which
+  happened later in this same release, so as shipped the gate runs it and it
+  is clean. An acceptance pass caught this paragraph still describing the
+  interim state, two entries above one saying the opposite.
+
+- **"A shipped harness preset" now has a module.** It was a protocol block
+  in YAML, loaded and parsed inside `config.ts`, interpreted by the generic
+  CLI dispatcher, read again by the dispatcher factory, and asserted by four
+  per-harness test files — so every change to a built-in harness touched all
+  of them. A co-change check over 300 commits reported exactly that: ten
+  files moving together across six directories, one concept with nowhere to
+  live. `src/harness-presets.ts` is where it lives now, and every importer
+  names it. `config.ts` is 184 lines smaller and no longer parses the
+  shipped file it also consumes.
+
+- **The leaderboard fetch stopped introducing itself as version 0.4.** Its
+  `User-Agent` was a hardcoded string, still saying 0.4 at 0.9 — so the one
+  host this tool ever contacts had been told a version that was wrong for
+  five releases. It is built from `VERSION` now. The reason it survived is
+  worth recording: a test asserted the literal `"harness-dispatch/0.4 …"`,
+  so the suite was holding the stale claim in place rather than catching it.
+  That assertion now compares against the real version.
+
+- A note returned to the CALLER carried a git commit hash
+  (`… this was per-process until 304a1b5`), which means nothing to anyone
+  reading a dispatch response. Removed, along with a second hash in a
+  comment and a reference to a line number in a file the symbol had since
+  moved out of.
+
+- The HTTP surface's context-file limit is imported from the MCP surface
+  rather than copied. It was a second `= 64` under a comment reading
+  "mirrors MAX_CONTEXT_FILES in mcp/tools.ts — the two surfaces must
+  agree": the constant does not live in that file, and a comment cannot
+  make two numbers agree. The module was already importing its sibling
+  constant from the right place.
+
+- `explicitOptsFromHints` is gone. It was exported for nobody: it existed
+  because the HTTP fanout path built dispatch options by naming fields
+  inline and dropped two, and that path now enforces route policy earlier
+  and passes hints wholesale — which is what the deleted function's own
+  docblock argued for.
+
+- **The landing page no longer describes a different product.** It listed
+  three MCP tools where six are registered and one resource where there are
+  two; its setup block ran `configure` without `--yes`, which writes
+  nothing, and then showed `doctor --live` output using three strings the
+  tool has never printed; its MCP snippet omitted `--config`, the form the
+  tool itself warns silently falls back to shipped defaults and ignores your
+  config file; it claimed "the one outbound call is a public leaderboard
+  GET" when that fetch is opt-in and off by default; and its worked example
+  showed a job id the API cannot produce. The sample output is now copied
+  from a real run.
+
+- `package.json`'s `homepage` pointed at a GitHub Pages URL that returns
+  404 — the deploy workflow is manual-only and has never been run — so the
+  link npm shows on the package page was broken. It now points at the
+  README. The site's own spec records that the page is not live and what to
+  do about it.
+
+- **An abandoned job no longer blames the wrong process.** Its error read
+  "The dispatch server that started this job exited before the run finished",
+  and a load test produced that message verbatim while the server was up and
+  still serving requests — one supervisor had been killed. The status file
+  this is derived from records a heartbeat and nothing about who was holding
+  it, so naming a culprit was always a guess, and it sent anyone debugging to
+  the wrong process. It now says what is known: the job stopped reporting,
+  the process running it is gone, the partial output is on disk, and
+  `retry_job` re-runs the same task.
+
+- `max_concurrent_runs: 0` is documented as what it is. README said it
+  "removes the bound"; measured under load, it also takes the supervisor
+  pool out of the path, so every job gets its own runner process at ~76 MB —
+  the per-job cost the pool exists to remove, on the memory-bound machine
+  the cap exists for. Routing the unbounded case through the pool would be
+  better and is not done here: the pool sizes itself by dividing the limit,
+  so an infinite one provisions zero supervisors, and getting that right
+  needs its own load run rather than a guess.
+
+- **The shipped harness defaults are read through the same field table as
+  everything else**, closing a silent drop that was already live. Route
+  settings resolve through one shared table so that a key works on `clis:`,
+  `endpoints:` and the legacy `services:` at once — but the parser for the
+  shipped defaults still hand-wrote its own list, and had drifted:
+  `thinking_level` on a built-in harness entry was parsed by nobody, while
+  the table reads that very field as the fallback for every user route of
+  that harness. Exactly the silent-drop shape the table exists to retire,
+  one layer underneath it. A row added to the table now reaches the defaults
+  layer too, instead of needing to be remembered in a fourth place.
+
+- **The two workspace policies no longer keep separate copies of the guards
+  that protect a recursive delete**, and those guards are now tested on
+  Windows, where the attack they exist for was originally measured. `copy`
+  and `git_worktree` each had their own prune function and their own
+  create-and-verify sequence, ~55 and ~30 lines, identical but for a git
+  root. That duplication is why the symlink class took four releases to
+  close: each fix landed in one copy, shipped as done, and the next review
+  found the other still exploitable. The comment left behind said "whenever
+  one of these gets a guard, check the other in the same edit" — a process
+  rule standing in for a shared function, which now exists.
+
+  The tests that cover those guards were skipped on Windows because an
+  unprivileged `symlink(..., "dir")` fails there. A junction does not, and
+  `lstat` reports one as a symbolic link, so the code under test sees what
+  it sees on POSIX. Two of the six skips are gone.
+
+  Three deliberate breakages that the suite previously did NOT catch — the
+  sweep's name check removed, the verify-before-prune ordering reversed, and
+  the symlink refusal removed — now each fail their own test. The gap was
+  that the destructive path only runs past the 24-hour retention window and
+  no test aged anything, so the delete never happened and the guards were
+  never asked. Two new tests age a directory on purpose.
+
+- **A patch-building path no input could reach has been removed, along with
+  the ~800-line test suite guarding it.** When a `copy` job had no recorded
+  changed-file list, the patch was built by diffing the whole original
+  directory against the whole workspace — a comparison that reports every
+  excluded directory as deleted, so ~170 lines of path normalisation and
+  section filtering existed to make its output safe to apply. The field it
+  falls back from has been recorded since 2026-07-13 and an isolated
+  workspace is pruned after a day, so no run reaching this code could still
+  exist; its own comment still described the copy as living inside the
+  project, which stopped being true in 0.7.0. Such a job is now refused with
+  the path to its workspace, matching what the `git_worktree` branch beside
+  it already did. Two tests that had been passing only because their fixture
+  omitted the field now run against the current path, and one of them turns
+  out to pin something real: discard refuses to destroy unapplied work, a
+  guard the old fixture never triggered.
+
+- **Dead imports and locals can no longer accumulate unnoticed.** The
+  compiler was not asked about them, and 38 had built up across twelve
+  files: three whole import declarations nothing read, a function nobody
+  called, a parameter threaded through a signature after the code that used
+  it was fixed, and two catch blocks computing a message they discarded.
+  Individually harmless; in bulk they are what makes a reader unable to tell
+  what is load-bearing. All 38 removed, and `noUnusedLocals` /
+  `noUnusedParameters` are now on, so the next one fails the build rather
+  than joining the pile.
+
+- **The router had two implementations of every dispatch path, and its own
+  header said otherwise.** `route()`/`routeTo()` and `stream()`/`streamTo()`
+  were separate selection-and-fallback loops, with a second copy of the
+  workspace-policy wrapper beside them — about 250 lines that had to stay in
+  step and did not. The file's header claimed the buffered methods were
+  "reimplemented on top of the streaming primitives", which is what made the
+  drift invisible: the timeout rule ended up written four times, and only the
+  `route()` copy was covered by a test, while background jobs and every HTTP
+  request run on the streaming pair. The buffered methods now drain the same
+  loop. One thing is still chosen per entry point, and only one: whether the
+  dispatcher is asked through `dispatch()` or `stream()` — an endpoint route
+  keeps its non-streaming request, which sets `stream: false` on the wire, so
+  no live traffic changes shape. Behaviour is otherwise unchanged; 123 lines
+  are gone.
+
+- **An empty `HARNESS_DISPATCH_STATE_DIR` sent every state path to the
+  current directory.** The lookup used `??`, which treats an empty string as
+  a real value — and an empty value is what a launcher or shell produces
+  when it forwards a variable that is not set. The state root became `""`,
+  so config, jobs, breaker state, quota counters and logs all resolved
+  against wherever the process happened to start: the cwd-dependent bug this
+  module's own comment says was fixed. A relative value is now anchored too,
+  so a job runner spawned with a different working directory cannot read a
+  different state root than the server that spawned it.
+
+- **`doctor` no longer reports a Codex that is installed but not logged in
+  as logged in** when its CLI prints usage text and exits 0, which is what a
+  build without the `login status` subcommand does. Exit code and output
+  must now agree. Also, the login probe's synchronous spawn-failure path
+  bypassed its own settled guard.
+
+- `doctor`'s `config` line now distinguishes a file that defines no routes
+  from one that defines routes AND asks for detection with `detect: true`.
+  It reported the former for both, which reads as though the file were being
+  ignored.
+
+- **The plugin's `/setup` command no longer walks users into a config that
+  removes every CLI harness.** It told them to write `disabled:`,
+  `overrides:` and `endpoints:` together — and a config carrying
+  `endpoints:` is authoritative, so detection switches off, the two tuning
+  keys apply to nothing, and Claude Code, Codex, Cursor and Antigravity all
+  vanish from the route table. That is not hypothetical: the maintainer's
+  own config had this shape, and no dispatch on that machine could reach a
+  CLI harness for four days after 0.9.0 shipped the authoritative rule. The
+  command now states the rule up front, points at `configure --yes` first,
+  offers two valid shapes (`detect: true` plus `endpoints:`, or a fully
+  explicit `clis:`), and ends by reading the two `doctor` lines that report
+  the mistake. Also corrected in the plugin: the "not yet published" note
+  (0.9.0 is on npm), the config-resolution order (it omitted `./config.yaml`
+  and the state-dir variable), the claim that `hints.model` is unvalidated,
+  and the command list, which omitted `/setup`.
+- **Two rules that a user depends on were passing while broken.** An audit
+  broke fifteen guards on purpose to see which the suite would catch; these
+  are the two that got through. First, "a per-call `timeoutMs` beats the
+  service's configured default" is written out four times in `router.ts`,
+  once per entry point, and only the `route()` copy was tested — while
+  background jobs and every HTTP request go through `stream()`/`streamTo()`,
+  so the copies that carry real traffic were unpinned. Second, the HTTP
+  bearer check was only ever tested with the header MISSING: a server that
+  accepted any `Bearer` value at all passed every test in its own file, and
+  token rotation on a running server was never exercised. Both now have
+  table-driven tests covering every entry point and every authenticated
+  route, including a wrong token of the same length, an empty one, and one
+  without the scheme. No behaviour changed; the tests are what changed.
+
+- README corrected in nine places found by an audit against the code: the
+  Configure section described a verification step and an interactive
+  choice of harnesses, model priority and safety profile that do not exist;
+  Claude Code billing was still described as date-aware when the code
+  classifies it as plan usage unconditionally; the CLI list omitted the
+  public `dispatch` command while calling `route` the hidden one (it is the
+  alias); the endpoint-mode example used the legacy `services:` format
+  without saying so, which silently drops `clis:` routes when pasted into a
+  modern config; two different default timeouts were stated (60 minutes is
+  right for every MCP and HTTP dispatch); `job_status` with no id was said
+  to return every job (it returns the twenty newest); `configure`'s target
+  omitted that a `./config.yaml` still wins; `usage listModels` was said to
+  fetch live when a declared list is returned as-is; and a duplicated
+  endpoint line.
+
+- **`configure` no longer regenerates away a comment you put above its
+  header, and no longer counts a stripped final newline as an edit.** The
+  unedited check accepted any comment lines above the fingerprint, so a
+  `# note to self` at the top of the file was overwritten without a word;
+  meanwhile an editor that drops the trailing newline made the file count
+  as edited and forced `--force`. Only the exact header may sit above the
+  fingerprint now, and trailing whitespace is ignored when fingerprinting.
+  (Twenty-fifth acceptance pass, finding 4.)
+
+- **`doctor` names a harness on PATH that an authoritative config leaves
+  out.** A config listing its own routes is authoritative, so a harness
+  installed afterwards is simply absent — and `routes` said "1 ready
+  route(s)" with a second CLI installed and no hint; the PATH hint only
+  appeared at zero routes. It now adds "Installed but not in this config:
+  claude — add `detect: true` to <file> to merge them, or a clis: entry".
+  (Finding 5.)
+
+- **`--config` at the boundary.** A directory produced a raw `EISDIR` that
+  named no path; it now says which path is a directory. `--config=` (empty)
+  silently auto-detected and reported the routes as loaded "from" the
+  current directory; it is now the same usage error as a missing value. An
+  empty or routes-free config file was reported as the source of routes
+  that detection had found; doctor's `config` line now says they were
+  auto-detected and that the file defines no routes of its own. (Finding 3;
+  its remaining half — a load failure printing text under `--json` — is fixed
+  further down this same release.)
 
 ## [0.9.0] — 2026-09-02