harness-dispatch 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -6,6 +6,518 @@ pre-1.0, so minor versions can carry behaviour changes.
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-09-02
+
+### Changed (breaking)
+
+- **A config file that defines routes is now authoritative about them.**
+  Auto-detection used to run unconditionally, so a file with `clis:` or
+  `endpoints:` entries ADDED to the installed harnesses rather than replacing
+  them, and only `disabled:` — naming every route, including ones you might
+  not know existed — subtracted.
+
+  That default caught three acceptance passes in a row despite explicit
+  warnings, and caught this project's own test suite: one test dispatched to
+  the real Claude Code CLI on every `npm test` and every CI run, under a
+  comment asserting it could not reach a route. It also decayed — adding
+  support for a new harness would auto-add it to every existing config, so a
+  `disabled:` list written today quietly stopped isolating tomorrow.
+
+  The legacy `services:` format has always behaved this way, so the two shapes
+  now agree rather than this being a new rule.
+
+  **What changes for you.** A config that has a `clis:` or `endpoints:` key
+  gets exactly the routes listed under it — including `clis: []`, which means
+  no CLI routes. Add `detect: true` to keep the old behaviour. A config
+  mentioning NEITHER key — one carrying only `overrides:`, `disabled:` or
+  settings — still auto-detects, because a file cannot be authoritative about
+  routes it does not describe; it now says so in a warning. `detect: false`
+  turns detection off outright.
+
+  Note that `disabled:` and `overrides:` tune AUTO-DETECTION, so they do
+  nothing in a config that lists its own routes — remove the entry instead.
+  The config the README tells you to copy said the opposite of this until it
+  was corrected in the same release; check yours if you wrote it from that.
+
+### Fixed
+
+- **Re-running `configure` after installing a harness no longer needs
+  `--force`.** The natural first-run order — install this tool, configure,
+  find out a harness is needed, install one, configure again — was refused
+  at the last step: "already exists ... --force". And had the first run found
+  anything, the re-run would have loaded that file as authoritative and not
+  detected the new harness at all. `configure` now stamps what it writes
+  with a fingerprint; a re-run that finds its own unedited output regenerates
+  it from a fresh detection, and says so. A file that has been edited, or
+  that configure did not write, is still loaded (so its settings migrate)
+  and still refused without `--force` — and since such a file lists its own
+  routes, `--force` regenerates it from the file, not from a detection. It
+  used to print "Detected N harness routes" there anyway; an acceptance pass
+  measured that line with a second harness on PATH that never appeared. It
+  now says detection did not run and how to merge (`detect: true`). The
+  non-interactive hint at the end of `configure --yes` also told the user to
+  pass `--yes`, which they just had; it now names `connect`. Seen on the
+  cold-install walk.
+
+- **`connect` now registers with a Claude Code that has never been opened.**
+  A client counted as installed only if its config file existed, and Claude
+  Code writes `~/.claude.json` on its first interactive launch — so a user who
+  installed Claude Code and this tool together was told "No MCP clients found
+  on this machine" with `claude` on PATH, handed JSON to paste by hand, and
+  `claude mcp list` stayed empty. A client whose command is on PATH now counts
+  as installed; when its file is missing, `connect` creates it holding only
+  our entry (0600), which Claude Code accepts as a user-scope registration.
+  Doctor's `mcp-clients` line names the installed-but-unregistered client
+  instead of a generic "not registered". Seen on the cold-install walk.
+
+- **`configure` writes its config where every later command can find it.**
+  It wrote `./config.yaml` into whatever directory it was run from, and
+  lookup stopped at the current directory, so a config written from `~` was
+  invisible to `doctor` or `dispatch` run inside a project — "0 configured
+  route(s)", no hint why — while the MCP client, handed the absolute path,
+  saw it fine. The default target is now the state directory
+  (`~/.harness-dispatch/config.yaml`, or under `HARNESS_DISPATCH_STATE_DIR`),
+  lookup falls back to that file after `./config.yaml` (a per-project file
+  still wins), `connect` looks in the same place, and doctor's `config` line
+  names the file it loaded. `--config` and `HARNESS_DISPATCH_CONFIG` are
+  unchanged. Seen on the cold-install walk, where a run from `/` produced
+  `/config.yaml`.
+
+- **`doctor` now notices a Codex that is installed but not logged in.** A
+  ready route meant "the CLI is on PATH", so a never-logged-in Codex passed
+  routes, billing and safety, and the first dispatch failed with a raw OpenAI
+  `401 Unauthorized ... Missing bearer` that never mentioned `codex login`.
+  A new `harness-login` check asks `codex login status` and fails with the
+  command to run when it answers "Not logged in". The CLI is asked rather
+  than its credential file read, because Codex accepts a ChatGPT login or an
+  API key and honours its own home directory, and only its own answer is
+  right in every case. Any answer other than a definite "Not logged in" —
+  an older Codex without the subcommand, a spawn failure — is reported as
+  undetermined and does not fail the install. Codex only: the other
+  harnesses have no equivalent subcommand this tool has verified.
+
+- **The installed command did nothing on Linux and macOS.** `npm install -g`
+  puts `harness-dispatch` on PATH as a symlink to `dist/bin.js`, and node
+  hands that unresolved link path to the program, so a run-if-entrypoint guard
+  that only looked for a filename ending in `bin.js` decided it was being
+  imported, ran nothing, and exited 0. Every documented command — `configure`,
+  `doctor`, `connect`, `dispatch`, even `--help` — printed nothing and reported
+  success on every non-Windows `npm install -g` or `npx` since the first
+  release. Windows was unaffected only because npm's `.cmd` shim passes the
+  real file path. The guard now also accepts an invoked path that resolves to
+  this file. Found by walking the README's three install steps in a clean
+  container, which nothing before had done: every prior walk ran `node
+  dist/bin.js` on this Windows machine.
+
+- **SECURITY: workspace paths are now built and verified rather than checked
+  and trusted.** Four consecutive releases patched a guard that inspected a
+  path STRING and then let every later write re-resolve it, and each patch was
+  found incomplete by the next review: it followed the link it was checking,
+  then covered one of the two isolation policies, then only the last path
+  segment, then stopped one directory short of the one the release notes named
+  — and was silently inert altogether if the workspaces setting had a trailing
+  slash or a `..` in it. Validating once also left the rest of the dispatch
+  trusting the result, so swapping a directory for a link mid-copy redirected
+  it.
+
+  Every directory from the anchor down is now created by this tool with a
+  non-recursive `mkdir`, which cannot traverse a link it did not make, and the
+  verified path is returned and used instead of being re-derived. Destructive
+  operations re-verify immediately before acting. The symlink refusal now
+  applies on Windows too, where junctions need no privileges and were being
+  followed.
+
+  Verified as two separate users on Linux across every shape reported: a link
+  at the workspace root, at the base, at the base's parent, and with the
+  setting spelled with a trailing slash or `..` — all refused, with nothing
+  written into the attacker's directory. Legitimate use is unaffected,
+  including a symlinked temp directory, which is normal on macOS.
+
+- **A delegated "run the tests" task no longer blocks its own route.** The
+  rate-limit phrase check ran against the whole transcript with no filter, so
+  this project's own test output — which names rate limits in test titles —
+  flagged as a real limiter, tripping the breaker for 300 seconds and
+  recording a rate limit that never happened. It is now checked per line and
+  past the same filter the numeric check uses.
+
+- **Real limiter messages that were being missed now register**, including
+  Anthropic's `rate_limit_error` and OpenAI's "You exceeded your current
+  quota" wording. A missed limit is the worse direction: the router keeps
+  hammering a route that has already said stop.
+
+- A metered route that declares it cannot bill you is no longer told to allow
+  paid usage. The previous release put that advice in a branch such a route
+  never reaches, so it worked for local routes only.
+
+- The claims checker now also scans MCP resource descriptions, every
+  route-refusal message, the rendered status body and the CLI's own help text
+  — surfaces a user or agent reads that it could not see.
+
+- **SECURITY: the workspace symlink guard covered one of the two isolation
+  policies.** The previous release applied the `lstat` refusal, the
+  guard-before-prune ordering and the sweep's name check to `copy` only.
+  `git_worktree` kept all three defects, so the identical attack still
+  destroyed data — reproduced as two real users: `copy` refused, `git_worktree`
+  deleted the victim's directory and raised the guard's error afterwards. The
+  entry claiming the class was closed was true for one policy and false for the
+  other. The test shipped with it passed `policy: "copy"` only, so the suite
+  stayed green over a live vulnerability; it now runs against both.
+
+- **The same guard only checked the last path segment.** `<tmp>/harness-dispatch`
+  and `<tmp>/harness-dispatch/workspaces` are fixed names under a
+  world-writable directory and were never examined, so a link planted one or
+  two levels up redirected the whole copy into an attacker's tree. Every
+  segment from the workspaces base down is now checked for links and ownership.
+
+- **A rate-limit regression from the previous release.** The filter added to
+  stop false positives discarded any line containing "should", which threw away
+  real limiter messages — a missed 429 means the router keeps hammering an
+  exhausted route. Two other patterns in that filter could never match at all.
+
+- **A free local route is no longer told it can bill you, with a fix that does
+  nothing.** A route with a declared kind and `paid_usage_possible: false` is
+  blocked when its `billing_confidence` is `unknown` — deliberate — but was
+  shown "route can incur paid usage" beside `paid=no` and advised to set a
+  field it already had. It now names the real cause and a remedy that works.
+
+- The `usage` tool description and README told agents that `service` and
+  `models` are unvalidated. Both throw on an unknown route id. The same wrong
+  sentence was corrected in the plugin skill one release earlier and missed
+  here — `scripts/check-claims.mjs` could not see tool descriptions at all, and
+  now does.
+
+- `scripts/fetch_benchmarks.py` no longer replaces good benchmark data with its
+  bundled fallback when the network fails. It swallowed every exception,
+  returned an empty set, wrote it out and exited 0 — turning a transient outage
+  into a permanent downgrade of the file that ships in the package.
+
+- An env-var reference embedded in a larger value (`base_url:
+  https://${HOST}/v1`) is now stripped from spawned CLI environments. The
+  sanitizer anchored to whole-string matches, so a key inside a longer string
+  stayed visible — the exact leak it was written to close, one string shape
+  over.
+
+- `OPERATIONS.md` described streamed fanout wrongly (its arms DO create jobs,
+  and are not aborted on disconnect), `safety.ts` claimed every shipped harness
+  defines all three safety profiles (`cursor_cli` declares one),
+  `ux-walkthrough.md` called `discard` the only destructive operation (the
+  retention sweep is the one that deleted files), and two module headers said
+  three tools where six are registered.
+
+- **SECURITY: a `copy` dispatch could delete files outside its workspace.**
+  The ownership guard used `stat`, which follows symlinks, so it compared the
+  uid of whatever a link POINTED AT rather than the link's own — and on a
+  shared machine the workspace path is predictable, so another local user can
+  plant one. Worse, the retention sweep that deletes aged workspaces ran
+  BEFORE the guard and had no ownership, marker or name check of its own.
+  Reproduced end to end in a container: a victim's directory chmod'd, the
+  project copied into it, and their files removed. All three now fixed —
+  `lstat` with symlinks refused outright, the guard runs before anything
+  destructive, and the sweep only deletes directories matching the name shape
+  this tool generates. The previous release's entry claiming a foreign-owned
+  root was "refused outright" was false against exactly this attack.
+
+- **Non-ASCII output was being corrupted.** Every stdout chunk was decoded on
+  its own, so a character split across two reads became replacement
+  characters — accented text, CJK, emoji, box-drawing. This is the path every
+  job uses, so it reached partial output, saved logs and delivered results,
+  and was invisible to anyone working in English.
+
+- **An aborted streaming request now stops the run.** Nothing connected the
+  client disconnect to the dispatch, so an abandoned stream ran to completion,
+  spending quota — and being the one path with no job record, it could not be
+  cancelled either. On a CLI route that meant an agent still editing files for
+  a caller that had gone.
+
+- **HTTP fanout with no eligible route now refuses** instead of answering 200
+  with an empty list. CI and cron read 200 as success; the MCP surface already
+  refused the identical request by name.
+
+- A configured `timeout_ms` now covers reading an endpoint's response body,
+  not just its headers — the same defect as the leaderboard timeout fixed last
+  release, in the path the router uses for its primary route.
+
+- Endpoint credentials can no longer leak through streaming error text: undici
+  embeds the request URL, and this branch returned it unscrubbed while its
+  sibling scrubbed it deliberately.
+
+- A rate-limit false positive no longer trips the breaker on text ABOUT a 429
+  — a line number, or a test assertion the delegate ran. One flag blocks a
+  route for 300 seconds and records a limit that never happened.
+
+- Config hot-reload now notices a config whose timestamp moves BACKWARDS
+  (restored from a backup, `cp -p`, extracted from an archive), and documents
+  the two cases where it does nothing at all.
+
+- The MCP snippet `configure` prints is now the entry `connect` actually
+  writes. Pasting the documented snippet then running `connect` was answered
+  "has an entry we did not write" — the tool called its own output
+  hand-edited and refused to update or remove it.
+
+- The chained-context omission notice named the wrong jobs when a job id
+  repeated, listing ones whose output was directly above it.
+
+- **An existing `copy` workspace directory is now actually secured.** The
+  previous release set 0700 with `mkdir`'s `mode` option, which applies only to
+  directories it CREATES — so everyone who had used `copy` before kept a
+  world-readable root holding a full copy of their source, and the entry
+  claiming otherwise was wrong. Measured on Linux: 0755 before, 0755 after. An
+  explicit chmod fixes them. A root owned by ANOTHER user is now refused
+  outright rather than copied into: the path is deterministic inside a shared
+  temp directory, so on the multi-user machine this guard exists for, someone
+  else can create it first.
+
+- **A half-dead leaderboard endpoint no longer hangs every dispatch.** The 8s
+  timeout was cancelled as soon as response headers arrived, leaving the body
+  read unbounded — measured still pending after 15s. Quality scores are awaited
+  per routing candidate, so this stalled routing indefinitely. Off by default,
+  which is why it was not worse.
+
+- **The HTTP server no longer leaks an MCP server per rejected request.** A
+  request carrying an unknown session id is answered 400 without initialising,
+  so nothing ever closed the server built for it in advance — five such
+  requests left five alive until shutdown. Sessions are also expired after 30
+  minutes idle: nothing removed them before except an explicit HTTP DELETE,
+  which the standard client never sends, so a clean shutdown left its session
+  resident forever.
+
+- **`retry_job` on an abandoned job no longer races the original.** Its guard
+  read the derived status while the claim path reads the raw status file, so a
+  supervisor could pick up the original while the retry ran — the exact outcome
+  the command's own error text says it prevents. The original is now marked
+  cancelled.
+
+- **Chained context says what it left out.** Jobs past the character budget
+  were dropped with no header and no note, contradicting the contract stated in
+  the same file. The docblock also claimed oldest entries truncate first, which
+  was never true — the last ones go.
+
+- The `copy` size refusal named the parent of your project rather than the
+  workspace holding the work, and the `force` flag's description still promised
+  an uncommitted-changes refusal that only exists inside a git repository.
+
+- **`configure` no longer deletes `detect: false`.** That key is the only
+  setting that isolates a machine from its installed paid CLIs, and it had no
+  field on the internal config object, so regenerating a file silently dropped
+  it. Measured: `detect: false` plus `max_concurrent_runs: 2` came back as the
+  latter alone, and reloading it with all four harness CLIs present produced
+  four routes on real subscriptions — under a "Wrote" message. A bare
+  `detect: false` regenerated as an empty document, where even the
+  "this config defines no routes" warning is suppressed, because its trigger
+  requires a non-empty file. `detect` now round-trips, and is written only when
+  the file stated it — carrying the resolved value would stamp `detect: true`
+  into every config that merely omitted it.
+
+- **`connect --remove` now removes the entry.** Without `--clients` it printed
+  "our entry is here — will be removed", exited 0, and left the file
+  byte-identical. The chooser filtered out plans whose entry already matches —
+  correct when registering, and exactly backwards when removing, where a
+  matching entry is the one being removed. `--clients` bypassed that function
+  and always worked; the broken form is the one documented in README and
+  OPERATIONS.md. A hand-edited entry is still refused without `--force`, and
+  now exits non-zero rather than reporting success for work it did not do.
+  This command had no test coverage at all; it does now.
+
+- **The test suite can no longer reach a real route.** Test setup already
+  sandboxed the log, state and jobs directories — where the suite WRITES — but
+  not config, which is what it DISCOVERS. A test that loaded config without
+  naming a file or stubbing detection picked up whatever the developer's
+  machine offers. Measured while closing this: on the maintainer's machine
+  that is the repo's own `config.yaml`, yielding four API routes with real
+  keys; on a machine with the CLIs installed it is the harness fleet, on real
+  subscriptions. One boundary test really did dispatch to Claude Code on every
+  CI run once. Setup now pins `HARNESS_DISPATCH_CONFIG` at a `detect: false`
+  sandbox, so an un-stubbed load gets an empty route table; a test wanting
+  routes passes its own path, which still wins.
+
+- **An orphaned job can be cancelled again — when it is still able to run.**
+  There are two kinds: one written to disk when the server exits before a
+  queued job starts (genuinely terminal), and one DERIVED from a stale
+  heartbeat while the file still says `queued`. The second is not inert — a
+  supervisor reclaims it once the dead owner's claim ages out — and `cancel`
+  answered "had already finished; nothing to cancel" about work that could
+  still start, leaving no way to stop it. It now settles the status itself,
+  since an orphaned job has no runner to notice a marker. The written kind
+  still reports nothing to cancel.
+
+- **A `copy` workspace of many files can no longer build an unbounded patch.**
+  The per-file diff was already bounded; the concatenation of those files was
+  not, so files each under the limit still summed past it. Both limits now
+  explain themselves — the worktree path used to surface the cap as
+  `stdout maxBuffer length exceeded`, which says nothing about patches or
+  about the work still being safe on disk.
+
+- **Isolated workspaces are created 0700**, like the state and job
+  directories. A `copy` workspace holds a full copy of your source and the
+  default base is in the shared temp directory, so on a multi-user POSIX
+  machine it was readable by everyone. No effect on Windows.
+
+- **Chained context says which project it came from.** `contextJobs` inlines
+  any job from the machine-wide store with no working-directory scoping, so a
+  job from one project could be pulled into a dispatch for another with
+  nothing indicating it. Disclosed rather than blocked: chaining across
+  projects is legitimate and the caller passes the id explicitly — what was
+  missing is that nobody could see it happen.
+
+- **Dead supervisor heartbeats are swept.** A killed supervisor's file stopped
+  being counted but stayed forever, and the liveness check reads every file on
+  every drain. The sweep is limited to heartbeats: the crash log beside them
+  exists to explain the very supervisor that died.
+
+- `workspace apply`'s description no longer claims a refusal it cannot always
+  make: the uncommitted-changes check needs a git repository. Outside one,
+  only the per-file check applies — a file the patch touches is still
+  refused, unrelated edits cannot be seen.
+
+- A `timeout_ms` or token-cap warning no longer claims routing reads the
+  field. Routing does not; the range branch was fixed for this and the
+  not-a-number branch beside it was not.
+
+- **Usage counters are no longer silently lost when two dispatches finish at
+  once.** `withFileLock` runs its critical section unlocked after a 2s
+  timeout — deliberate, and still right for the circuit breaker, which has
+  nothing to fall back on. It was wrong for the quota counters, which keep a
+  pending delta and clear it only on success: an unserialised write landed,
+  the delta was cleared as though serialised, and the process actually holding
+  the lock then overwrote the file with a value computed before that write
+  existed. Reproduced against the built artifact: five recorded calls gone,
+  no error. The counters now defer instead, and the delta lands on the next
+  result. A busy moment is no longer reported as "counters not reaching
+  disk" — they are delayed, not lost, and saying otherwise makes a working
+  system look broken.
+
+- **A route knocked out by a 429 no longer reports `tripped: true,
+  failures: 0`.** `trip()` set the cooldown without counting the failure, so
+  `usage` — the surface an orchestrator is told to consult before delegating
+  — showed a contradiction that reads as a bookkeeping bug rather than a real
+  trip.
+
+- **Discarding a workspace whose directory is already gone now clears the
+  registration git is still holding.** The early return skipped the block that
+  removes a worktree through git, so a workspace pruned by retention or
+  deleted by hand left `.git/worktrees/<name>` in the user's repo
+  permanently — the exact outcome `discardWorkspace`'s own documentation says
+  it exists to prevent. Reproduced: `git worktree list` still showing the path
+  as `prunable` after discard reported success.
+
+- **An orphaned or cancelled job now hands back its partial work through the
+  tool an orchestrator actually calls.** The progress was on disk and
+  `getAsyncJob` read it, but `job_status` answered `output: ""`: orphaned and
+  cancelled count as terminal, and the poll response attached `partialOutput`
+  only on the NOT-terminal branch. So a commit titled "an orphaned job hands
+  back its progress" was correct in the module it edited and had no effect at
+  the surface a caller touches — verified at the function, not at the tool.
+  The crash path (a `failed` status with no result) was losing its output the
+  same way. The HTTP surface already salvaged this; MCP now matches it, and
+  the answer says the output is PARTIAL so salvage is not read as a result.
+
+- **A gitignored file the agent wrote is no longer reported as applied while
+  being left behind.** Under `git_worktree`, the patch came from `git add -A
+  -N`, which obeys `.gitignore`, while the changed-file list came from a
+  filesystem fingerprint, which does not. A job that wrote a `.env` or any
+  ignored file got `applied: true` naming it, with the file absent from the
+  patch and from the project. It compounded: the already-applied guard needs
+  every recorded change present, so it never fired, and the next apply refused
+  with "changed since dispatch" — blaming the caller for the first apply's own
+  writes, the misleading refusal an earlier fix had removed. The paths already
+  recorded as changed are now force-added, which also makes `git_worktree`
+  agree with `copy`, whose per-file patch always carried them.
+
+- **`clis: []` now isolates a config, which is what the previous release said
+  it did.** Authoritativeness keyed off a NON-EMPTY list, so the most explicit
+  way to write "no CLI routes" still loaded every harness on the machine —
+  the exact failure the change was written for, described in its own comment
+  in the past tense while remaining true. Presence of `clis:`/`endpoints:` is
+  now what makes a config authoritative, empty or not. A config that mentions
+  neither still auto-detects, unchanged.
+
+- **An infinite or NaN route field is no longer accepted, and the warning
+  about it is no longer false.** The new range check covered negative values
+  but not `.inf`, `.nan`, or `1e999` (which YAML types as a string, and
+  `Number()` overflows to `Infinity`). Two paths were wrong: `1e999` produced
+  no warning at all, and `tier: -.inf, weight: .inf` loaded as
+  `-Infinity`/`Infinity` — ahead of every tier, above every score —
+  underneath a warning reading "IGNORED, and the built-in default applies
+  instead". A message asserting the opposite of what happened is worse than
+  the silence it replaced. Warnings also now name the value the operator
+  actually wrote (`JSON.stringify(Infinity)` is `null`, so they reported
+  `tier is null` for a file saying `-.inf`), and explain the right mechanism
+  per field rather than describing routing for `timeout_ms`.
+
+- **`configure` no longer generates a config that fails its own `doctor`.**
+  It carried `disabled:` forward alongside the `clis:` it generates; in an
+  authoritative config that control does nothing, so `doctor` reported it had
+  no effect and exited 1. The disabled route is already absent from the
+  generated list, so the name was saying nothing. It is still emitted for a
+  generated config that lists no routes, where it does the work.
+
+- **A `clis:` or `endpoints:` written as a mapping instead of a list now
+  says so.** The entries vanished, the config counted as defining no routes,
+  detection ran, and someone trying to name their own routes silently got
+  every installed paid harness instead — under a warning claiming their
+  config defined no routes, which contradicted the file in front of them.
+
+- Legacy `services:` configs now get the same top-level key warnings as the
+  modern shape. That path returned before the check ran, so `policy: copy`
+  warned twice in one format and not at all in the other.
+
+- **A negative `tier`, `weight` or `cli_capability` no longer hands a route
+  every dispatch.** These were type-checked but never range-checked, and
+  routing multiplies `weight` and `cli_capability` into the score while
+  ordering `tier` ascending — so a negative pair does not demote a route, it
+  promotes it past every legitimate one. An acceptance pass measured
+  `tier: -5, weight: -100, cli_capability: -3` scoring 299.8 against a normal
+  route's 0.88, from a tier sorting ahead of them all, with no warning
+  anywhere. Out-of-range values are now reported and ignored, so the built-in
+  default applies — the same outcome an unreadable value already got. Upper
+  bounds were deliberately not added: `cli_capability: 1.1` ships in this
+  repo's own default config as real tuning, and the defect is sign, not
+  magnitude.
+
+- Top-level `policy:` and `workspace_policy:` now say they have no effect.
+  Both were allow-listed and read nowhere — and both ARE valid per-route keys,
+  which is what makes the top-level spelling easy to write: it looks like a
+  global default for the per-route setting, and there is no such default. An
+  isolation control that silently does nothing is the failure the config
+  validator exists to prevent. The per-route keys are unaffected.
+
+- An `execute` task can no longer be routed to an HTTP endpoint. An endpoint
+  has no agent loop, no file access and no shell — PRODUCT.md states this as
+  design rather than gap — but an undeclared capability defaults to 1.0 and no
+  endpoint example declares any, so endpoints scored PERFECT for execute. An
+  acceptance pass measured a `--task-type execute` dispatch routed to an
+  endpoint, returning prose with exit 0: execution reported as succeeded when
+  none happened. It surfaced exactly when the CLI routes were busy or tripped,
+  which is the case a caller is least able to check.
+
+  Refused outright rather than scored low, on both counts deliberately: a score
+  of 0 still leaves a route selectable when it is the only candidate — the
+  failing case itself — and a declared capability must not override it, the
+  same rule as the safety-flag check. Endpoints remain full members of the mix
+  for plan, review and second opinions.
+
+- An orphaned job now hands back the progress it saved. When a supervisor dies
+  there is no result, but its output is on disk in `stdout.partial.log` — and
+  the orphan branch returned above the code that reads it, so the response was
+  empty while the trail sat there. Chaining had the same gap, reporting "no
+  result available" for a job whose partial output was recoverable; it now
+  carries that output, labelled INCOMPLETE. PRODUCT.md names losing this trail
+  as the defining failure: "a wasted attempt with no trail".
+
+- HTTP fanout arms are now job-backed, like the MCP surface has always been.
+  They called `routeTo` directly, so an arm's work existed only inside the
+  request — no job directory, no manifest, no partial log. Killing the client
+  or the server mid-fanout lost every arm's output with nothing on disk to
+  salvage, which is the failure PRODUCT.md names as defining, on one of two
+  surfaces.
+
+  The response shape is unchanged: arms are awaited and the same rows are
+  returned, so an OpenAI-compatible client sees exactly what it saw before.
+  Each row additionally carries the arm's `jobId`, which is what makes salvage
+  possible. This was briefly recorded here as deferred "because it changes what
+  a client receives" — that was wrong, and re-reading the MCP path showed why:
+  durability and the response contract are independent.
+
 ## [0.8.0] — 2026-08-31
 
 ### Added
@@ -1444,7 +1956,8 @@ the MCP surface to three tools: `dispatch`, `job_status`, `usage`.
 Known issues in this release, fixed in 0.5.0: `configure` writes resolved API keys into
 its output, and `configure --yes --force` can delete user-added harnesses.
 
-[Unreleased]: https://github.com/fstubner/harness-dispatch/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/fstubner/harness-dispatch/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/fstubner/harness-dispatch/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/fstubner/harness-dispatch/compare/v0.7.9...v0.8.0
 [0.7.9]: https://github.com/fstubner/harness-dispatch/compare/v0.7.8...v0.7.9
 [0.7.8]: https://github.com/fstubner/harness-dispatch/compare/v0.7.7...v0.7.8

package/README.md

@@ -66,15 +66,23 @@ harness-dispatch configure --yes
 harness-dispatch doctor --live
 ```
 
-`configure --yes` detects installed harnesses, writes `config.yaml`, and then
+`configure --yes` detects installed harnesses, writes `config.yaml` into the
+tool's own state directory (`~/.harness-dispatch/`, or `HARNESS_DISPATCH_STATE_DIR`),
+and then
 offers to register this server with each MCP client it finds (Claude Code,
 Cursor) — showing you what it would write, and what is already there, before
 changing anything. `--no-clients` skips the offer and prints a snippet to paste
 instead; `harness-dispatch connect` does the same registration later on its own,
 and `connect --remove` undoes it. Without
-`--yes` configure previews and writes nothing. `doctor` then checks the whole chain:
+`--yes` configure previews and writes nothing. Re-running it regenerates a file it
+wrote and you have not edited, so installing a harness later is just `configure --yes`
+again; a file you have changed is refused without `--force`, and because such a file
+lists its own routes, even `--force` regenerates it from the file rather than from a
+fresh detection (it says so; add `detect: true` to the file to merge new harnesses). `doctor` then checks the whole chain:
 binary, config load, harness detection, auth and billing classification, route
-readiness. `--live` goes further and routes one tiny real prompt, so you see a
+readiness, and for a Codex route asks `codex login status` whether the CLI is
+logged in (the other harnesses have no equivalent this tool has verified, so
+their login state is not checked). `--live` goes further and routes one tiny real prompt, so you see a
 completion before wiring anything into your agent. The live probe never touches paid or
 unknown-billing routes unless you pass `--allow-paid`.
 
@@ -211,6 +219,8 @@ Adding a harness that isn't auto-detected — a second Codex route pinned to a s
 model, or a local/hosted OpenAI-compatible endpoint — is a few lines:
 
 ```yaml
+detect: true            # keep auto-detected harnesses as well; see below
+
 clis:
   - name: codex_sol
     harness: codex        # picks the dispatcher: claude_code | codex | cursor | antigravity_cli | generic
@@ -224,6 +234,21 @@ endpoints:
     tier: 3
 ```
 
+**`detect: true` is doing real work there.** A config that lists any `clis:` or
+`endpoints:` is authoritative: it gets exactly the routes it names, and nothing is
+auto-detected alongside them. Without that line, the snippet above does not *add*
+`codex_sol` and `ollama` to your installed harnesses — it replaces them, and
+`claude_code_cli`, `codex_cli`, `cursor_cli` and `antigravity_cli` are gone.
+
+Which one you want depends on the goal:
+
+| You want | Write |
+|---|---|
+| My routes *plus* whatever is installed | `detect: true` alongside your entries |
+| Exactly the routes I list, nothing else | just the entries (the default) |
+| Nothing but auto-detection, minus a route | no `clis:`/`endpoints:`, plus `disabled: [name]` |
+| No routes at all | `detect: false` |
+
 See the shipped [`config.default.yaml`](config.default.yaml) for the full field
 reference (capability weights, tiers, escalation, workspace policy, and more) — copy
 it to your own `config.yaml` and edit, or run `harness-dispatch configure` to generate
@@ -387,7 +412,7 @@ version bump.
 | `cancel_job` | Stops work started by `dispatch` — a wrong turn, a wrong directory, a superseded run. A job still waiting for a slot stops outright; a running one tears down within about a second (poll `job_status` to see it land), killing the agent CLI and its children. Files it already changed are **not** reverted, and a cancelled run is not counted as a route failure. |
 | `retry_job` | Re-runs a finished job's task from its own record — same prompt (as the delegate saw it), files, working directory, hints and workspace policy. Pass `service` to send the retry to a different route, which is the usual reason to retry: the task was fine and the route was not — the original's model is left behind when the new route does not declare it, reported as `droppedModel`. Returns a new jobId; the original is untouched. |
 | `workspace` | For a job that ran with `workspacePolicy: "copy"` or `"git_worktree"`, the agent's changes live in an isolated workspace and were **never** applied to your project. `action: "diff"` returns the real patch; `"apply"` applies it (refusing when your project has uncommitted changes, since the patch was built against a clean base — `force: true` overrides); `"discard"` deletes the workspace. The full patch is always written to the job directory, so `git apply` by hand is available either way. |
-| `usage` | Per-route call counts, quota, billing kind, and breaker state — check this before passing an unfamiliar `hints.model`/`service`/`models` value, since those are not validated. Pass `listModels: <route id>` to fetch that `openai_compatible` route's live `GET /models` catalog instead of (or alongside) the summary. |
+| `usage` | Per-route call counts, quota, billing kind, and breaker state — check this before passing an unfamiliar `hints.model`/`service`/`models` value. `service` and `models` are validated — an unknown route id is rejected, naming the valid ones — while `hints.model` is forwarded to the picked harness as-is, so a wrong model name fails at the harness instead. Pass `listModels: <route id>` to fetch that `openai_compatible` route's live `GET /models` catalog instead of (or alongside) the summary. |
 
 `workingDir` is effectively required when starting work: if you omit it, the task runs
 in the router server's own process directory instead of your project, and the response

package/config.default.yaml

@@ -11,7 +11,15 @@
 # actually installed. To customize, copy this file to config.yaml in your
 # own project and edit — or run `harness-dispatch configure` to generate a
 # starting point instead. Same schema, same parser, no special cases either
-# way. Add a new entry and it's a route; delete one and auto-detection may re-add it — use `disabled:` to suppress a route for good.
+# way. Add a new entry and it's a route.
+#
+# A config that lists any `clis:` or `endpoints:` is AUTHORITATIVE: it gets
+# exactly the routes it names, and nothing is auto-detected alongside them.
+# So deleting an entry from your own config.yaml removes that route, full
+# stop — `disabled:` is not needed for it, and has no effect in such a file.
+# `disabled:` applies only to a config that names no routes of its own and is
+# therefore still relying on auto-detection. Add `detect: true` if you want
+# both: your entries AND whatever is installed.
 #
 # Route selection scores each entry by task fit:
 #   capabilities[task_type] x leaderboard ELO x cli_capability x quota x weight
@@ -197,8 +205,16 @@ clis:
     surface: cursor_agent_cli
     auth_source: product_login
     billing_kind: included_usage_then_on_demand
-    # Cursor hard-stops at the plan's included pool unless on-demand billing is
-    # enabled in Settings -> Billing -> Spending — set true here if you did.
+    # Cursor stops at the plan's included pool unless you have turned on
+    # on-demand usage in Settings -> Billing -> Spending. Set true here if you
+    # did — and note the second half, which the earlier wording ("hard-stops")
+    # missed: once on-demand IS on, overage is billed in ARREARS at the end of
+    # the cycle, and Cursor's own docs recommend setting a spend limit because
+    # without one there is no cap. So this route is the one subscription in the
+    # shipped set whose overage is not prepaid, which is why the `true` here is
+    # a bigger statement than it looks. Checked against Cursor's 2026 pricing
+    # documentation on 2026-08-31; NOT live-verified, because doing so means
+    # exhausting a real included pool.
     paid_usage_possible: false
     # Capability floor, per requested profile. cursor-agent's capability really
     # does differ by mode, so a single value cannot describe it: