harness-dispatch 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,152 @@
+# Changelog
+
+Notable changes per release. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+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.6.0] — 2026-08-21
+
+The job lifecycle is complete: start, watch, **stop**, **retry**, and **resolve the
+isolated result**. Every verb was exercised against real harness CLIs rather than
+fakes. The MCP surface grows from three tools to six.
+
+### Added
+
+- **`retry_job`** — run a finished job's task again from its own record: the same
+  prompt the delegate actually saw (context preamble included), 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. Returns a new jobId; the original is untouched, and retrying a
+  still-running job is refused so two attempts cannot race on one directory.
+- **Token totals in `usage`** — `inputTokens` and `outputTokens` per route, summed
+  from what harnesses actually report. Deliberately not money: subscription CLIs have
+  no per-call price, and pricing tokens would mean shipping a rate card that goes
+  stale silently. Zero means the harness reported nothing, not that nothing was spent.
+- **`workspace`** — inspect, keep or discard the isolated result of a job. `copy` and
+  `git_worktree` dispatches already ran the agent in isolation and never touched your
+  project, but there was no way to see the actual change, no way to keep it, and no
+  cleanup but by hand — so isolated runs were effectively write-only. `action: "diff"`
+  returns the real patch, `"apply"` applies it to your project (refusing when the
+  project has uncommitted changes, because the patch was built against a clean base),
+  and `"discard"` removes the workspace. The patch is always written to the job
+  directory, so applying it by hand is available even when the automatic path declines.
+- **`resource_weight`** on a route — the concurrency bound now counts CAPACITY, not
+  jobs. `max_concurrent_runs` priced an HTTP call to a local endpoint the same as a
+  whole Claude Code process, so four cheap endpoint calls could lock out a real
+  dispatch. Defaults to 1.0 for CLI routes and 0.1 for endpoints; with every weight at
+  1.0 the arithmetic is exactly the old count, so existing configs are unchanged.
+- **`cancel_job`** — stop a dispatch you already started. Until now the product could
+  start a 60-minute detached run and offer no way to stop it, so a misdirected agent
+  kept spending subscription quota and editing a workspace until it finished or timed
+  out. A queued job stops outright; a running one tears down within about a second,
+  killing the agent CLI and its child processes. Two things it does not do: it does
+  not revert files the agent already changed, and it does not count as a route
+  failure — the caller changing their mind says nothing about whether the route works.
+
+### Changed
+
+- All three route shapes (`clis:`, `endpoints:`, `services:`) resolve their shared
+  settings through one table instead of three hand-written lists. This retires the
+  class of bug that produced five separate silent drops, where a correctly spelled,
+  correctly valued setting was read by one route shape and ignored by another. A
+  legacy `services:` entry naming a harness now also inherits that harness's
+  `leaderboard_model` and `thinking_level`, which it previously lost.
+- `HARNESS_DISPATCH_CONFIG` pointing at a file that does not exist is now reported by
+  the server instead of being silently replaced with auto-detected defaults.
+- `install-codex.mjs --config` resolves to an absolute path and is checked at install
+  time. A relative path used to be stored as written and resolved later against a
+  different working directory, which silently meant "no config".
+
+### Removed
+
+- The unused dashboard renderer (`renderDashboard`, `DashboardState`). Nothing in the
+  product called it; the `dashboard` CLI alias maps to `status` and is unaffected.
+
+### Fixed
+
+- Copying a live working directory survives a file disappearing mid-copy. A working
+  directory is being written to while it is read — an editor saving, a build watcher
+  cleaning, another fanout arm — and any of those used to fail the whole dispatch with
+  a raw ENOENT. A vanished file is now skipped and named in the workspace notes; a
+  permission error or a full disk still fails loudly.
+- Workspace copies ask the filesystem for a copy-on-write reflink
+  (`COPYFILE_FICLONE`), which makes a clone near-instant and allocation-free on APFS,
+  Btrfs/XFS and ReFS/Dev Drive, and falls back to an ordinary copy everywhere else.
+- `workspace` on a `copy` job no longer emits a spurious deletion of the file it is
+  editing, and no longer refuses to apply because of its own scratch directory. The
+  workspace lives inside the project, which broke both.
+- Live agent smoke tests no longer write circuit-breaker state into the real install,
+  so a smoke failure cannot block a healthy route for real dispatches.
+
+## [0.5.0] — 2026-08-20
+
+Published to npm on 2026-08-21, with a signed provenance attestation from GitHub
+Actions. Anyone on 0.4.0 should upgrade: that release writes resolved API keys into
+`configure` output and can destroy a hand-written config.
+
+### Security
+
+- `configure` no longer writes resolved API keys into its output. Keys that came from
+  a `${VAR}` reference round-trip as that reference; a literal key is redacted in
+  `--print` (which people paste into bug reports) and preserved on disk.
+- A dispatch asking for a lower safety profile can no longer be silently ignored. The
+  keys that grant or restrict access are rejected by name when misplaced, on the MCP
+  surface that actually ships — a previous guard existed only on a code path nothing
+  called.
+- Symlinks can no longer carry an agent out of an isolated (`copy`) workspace.
+- Endpoint hostnames are redacted from status output.
+
+### Added
+
+- Chain delegated work: pass `contextJobs` and an earlier job's prompt and output are
+  rendered into the new prompt directly, without routing them through the orchestrator's
+  own context.
+- `max_concurrent_runs` (default 4) bounds how many agent CLIs run at once,
+  machine-wide. Extra dispatches queue and start as slots free; nothing is rejected.
+- A route's capability floor can vary by requested safety profile, which lets Cursor
+  serve read-only work on Windows instead of being skipped entirely.
+- `usage` reports per-route call counts, quota, billing kind and breaker state,
+  including work done by detached job runners in other processes.
+
+### Changed
+
+- Arena ELO scoring is opt-in (`leaderboard: { enabled: true }`). Routing defaults to
+  the tier and weight you configured rather than a benchmark maintained elsewhere.
+- Rate-limited calls are counted separately from failures, so a busy route does not
+  accumulate a permanent record of being unreliable.
+- `retention: { jobs_days: 0 }` means keep forever, and a running job with a live
+  heartbeat is never pruned.
+
+### Fixed
+
+- Nothing is lost to a timeout. Every dispatch runs as a detached background job that
+  survives a client timeout, a server restart, and the MCP call's own deadline.
+- `workspace_policy: shared_locked` serializes across all processes, not just within
+  one. Stale-lock takeover is atomic, so two dispatches can no longer both decide a
+  lock is free and edit the same directory.
+- Circuit-breaker cooldowns and failure decay survive process boundaries and upgrades;
+  `status` and `dispatch` no longer disagree about whether a route is available.
+- The OpenAI-compatible HTTP endpoint is backed by a persisted job, so a client that
+  times out mid-run can still retrieve the result.
+- A rate limit is detected from HTTP status context rather than any occurrence of the
+  digits 429 in an agent's output, which used to block healthy routes.
+- Bad input gets one actionable line instead of a stack trace or a silent default —
+  a missing `--config`, a malformed YAML file, an unknown route id, a typo'd setting.
+- `configure --yes --force` no longer deletes harnesses the user added.
+- On macOS and Linux, timing out an agent CLI also stops the shells and test runners
+  it spawned.
+
+## [0.4.0] — 2026-07-25
+
+First release under the `harness-dispatch` name (previously `harness-router`). Bumped
+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.6.0...HEAD
+[0.6.0]: https://github.com/fstubner/harness-dispatch/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/fstubner/harness-dispatch/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/fstubner/harness-dispatch/releases/tag/v0.4.0

package/README.md

@@ -1,97 +1,190 @@
 # harness-dispatch
 
-Delegate coding tasks to the agent CLIs you already pay for. harness-dispatch is a
-local MCP server that turns the coding harnesses on your machine (Claude Code,
-Codex, Cursor Agent, Antigravity CLI) and any local or remote API endpoint into
-tools any AI can call — routing each task to the best-fit agent, spending the
-flat-rate subscription quota you already own first. Routes with no billing backstop
-at all — a raw metered API key, or unknown billing — stay blocked until you opt in.
-
-Exposing harnesses as explicit tools is more reliable than telling an agent to shell
-out to another CLI: models are trained on tool calling, so they actually use tools
-they are given. And it routes whole tasks, not API requests — each harness keeps its
-own scaffolding, test loop, and codebase context; there's no proxy in between. Long
-tasks run as async jobs: start one, get an id back immediately, check for partial
-output, collect the result when it finishes. Runs execute in a detached runner
-process, so nothing is lost to a client timeout — or to the server itself
-restarting mid-run.
-(There is no Gemini CLI dispatcher; Google discontinued that CLI's backend in
-mid-2026, and Antigravity CLI is its replacement.)
-
-**What this does on your machine**, stated plainly before you install it: it spawns the
-CLI subprocesses above with your prompts, which can read and write files under the
-`workingDir` you pass it (this is the point — it's a coding agent router) and, depending
-on the workspace/safety policy in effect, run shell commands via those CLIs. Running
-`serve` additionally binds a local HTTP port (loopback by default, bearer-token gated —
-see [HTTP Surface](#http-surface) before pointing `--host` anywhere else). Nothing here
-is unusual for a coding-agent tool, but it's worth having in one place rather than
-inferred from separate sections.
-
-**A configured harness runs automatically** — nothing extra to switch on. If that
-harness's account has paid/overage billing enabled on the *provider's* side (Cursor's
-on-demand billing, Claude's usage credits, Codex's flexible credits, a raw metered API
-key, etc.), harness-dispatch will use it too — it does not detect or prevent provider-side
-billing state. It only blocks a route by default when there's no provider-side backstop
-at all (a raw metered API key, or unknown billing), until you set `allow_paid_usage: true`
-on it. See [Adding a harness](#adding-a-harness) for the config, and `status --json` /
-`status`'s `note:` lines for a given route's billing classification.
-
-## Requirements
-
-- Node.js `>=24.15.0`
-- At least one configured harness or OpenAI-compatible endpoint
+**Route whole coding tasks — not API requests — to the agent CLIs you already pay for.**
+
+Each harness keeps its own scaffolding, test loop, and codebase index. There's no
+proxy in between and nothing is re-implemented: Claude Code stays Claude Code. One
+orchestrating agent picks the right one per task and spends your flat-rate
+subscription quota before anything metered.
+
+It's a local MCP server, so the harnesses on your machine (Claude Code, Codex,
+Cursor Agent, Antigravity CLI, plus any local or remote OpenAI-compatible endpoint)
+become tools any AI can call. Exposing them as real tools beats asking an agent to
+shell out to another CLI: models are trained on tool calling, so they actually use
+the tools they're given. (No Gemini CLI: Google discontinued that CLI's backend in
+mid-2026, and Antigravity CLI replaced it.)
+
+## What it looks like
+
+Your agent calls one tool:
+
+```json
+{
+  "prompt": "Port the retry logic in src/net/ to the new backoff helper, then run the tests.",
+  "workingDir": "/path/to/project",
+  "hints": { "taskType": "execute" }
+}
+```
+
+Quick tasks come straight back:
+
+```json
+{
+  "mode": "single",
+  "completed": true,
+  "success": true,
+  "route": "codex_cli",
+  "model": "gpt-5.6-terra",
+  "output": "Ported 4 call sites to withBackoff(); 118 tests pass.",
+  "durationMs": 47210,
+  "routing": { "tier": 1, "taskType": "execute", "reason": "tier 1 best (3 available)" }
+}
+```
+
+Slow ones hand back a `jobId` after 25 seconds instead, and keep running:
+
+```json
+{ "mode": "single", "completed": false, "jobId": "job-1786977316001-b49d1232" }
+```
+
+Carry on working, then call `job_status` with that id for a live output tail or the
+finished result. The run lives in a detached process, so **nothing is lost to a client
+timeout — or to the server itself restarting mid-run.**
 
 ## Install
 
+Needs Node.js `>=22.22.2` (so current LTS works) and at least one harness or endpoint.
+
 ```bash
 npm install -g harness-dispatch
 harness-dispatch configure --yes
 harness-dispatch doctor --live
 ```
 
-`configure --yes` detects installed harnesses and writes `config.yaml`.
-Without `--yes` it only previews what it would detect and writes nothing —
-useful to check first, but not a substitute for the real run above. `doctor`
-then verifies the install end-to-end: binary + config load, harness
-detection, auth/billing classification, and route readiness. `--live` goes one
-step further and routes a single tiny prompt through the best eligible route so
-you see a real completion before wiring the server into your agent. The live
-probe respects billing policy — it never touches paid or unknown-billing routes
-unless you pass `--allow-paid`.
-
-Your Claude Code / Codex / Cursor subscriptions run by default, no opt-in needed
-— `configure`'s output tells you if anything's blocked and why. See
-[Adding a harness](#adding-a-harness) below for the config and the paid-usage note.
-
-> This project was renamed from `harness-router` to `harness-dispatch` — the npm
-> package, CLI command, env var prefix (`HARNESS_DISPATCH_*`), and MCP resource URIs
-> (`harness-dispatch://status`) all changed together. If you have an older install,
-> `npm uninstall -g harness-router && npm install -g harness-dispatch` and update any
-> `mcpServers`/`claude_desktop_config.json` entry to invoke `harness-dispatch`, not the
-> old command. Two older packages predate this rename and are no longer maintained:
-> `harness-router` (`0.3.2` on the registry) and the separately-published
-> `harness-router-mcp` (`0.2.0`) — both lack `usage`, `/v1/models`, `/v1/usage`,
-> Antigravity support, and every fix described in this README. Note that `npx -y
-> harness-dispatch` (used by the plugin's fallback launch path, see
-> [plugin/README.md](./plugin/README.md)) resolves to whatever is currently on the npm
-> registry, which can lag behind a local clone's `dist/`. Run `npm ls -g harness-dispatch`
-> to check which version is actually installed.
-
-You can also run without a global install:
+`configure --yes` detects installed harnesses and writes `config.yaml`; without
+`--yes` it previews and writes nothing. `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
+completion before wiring anything into your agent. The live probe never touches paid or
+unknown-billing routes unless you pass `--allow-paid`.
 
-```bash
-npx harness-dispatch configure
-```
+Your Claude Code / Codex / Cursor subscriptions run by default with no opt-in;
+`configure` tells you if anything is blocked and why.
+
+No global install needed either: `npx harness-dispatch configure`.
 
 ### Plugin install (Claude Code / Claude Desktop / Codex)
 
 The `plugin/` directory packages the MCP server plus a delegation skill and
 `/route` + `/jobs` commands for one-step installs — see
-[plugin/README.md](./plugin/README.md). Claude Code:
+[plugin/README.md](https://github.com/fstubner/harness-dispatch/blob/main/plugin/README.md)
+(absolute link on purpose: `plugin/` is not shipped in the npm tarball, so a
+relative link is dead on npmjs.com). Claude Code:
 `/plugin marketplace add <repo path or URL>` then
 `/plugin install harness-dispatch@harness-dispatch`. Codex:
 `node plugin/scripts/install-codex.mjs`.
 
+## What it does on your machine
+
+Stated plainly, up front, rather than left to be inferred:
+
+- It **spawns the CLIs above as subprocesses** with your prompts.
+- Those CLIs **read and write files** under the `workingDir` you pass (that's the
+  point of the tool) and **run shell commands**, depending on the workspace and
+  safety policy in effect.
+- At most **4 agent CLIs run at once**; extra dispatches queue and start as slots
+  free. Tune with `max_concurrent_runs`.
+- `serve` additionally binds a local HTTP port: loopback only by default,
+  bearer-token gated. Read [HTTP Surface](#http-surface) before pointing `--host`
+  anywhere else.
+
+None of this is unusual for a coding-agent tool. It's here in one place so you can
+decide before installing rather than after.
+
+## Billing, and what it can't promise
+
+**A configured harness runs automatically**, with nothing to switch on. Routes that
+have no billing backstop at all, meaning a raw metered API key or billing it can't
+classify, stay blocked until you set `allow_paid_usage: true` on them.
+
+The honest limit: if a harness's account already has paid or overage billing switched
+on at the **provider** (Cursor on-demand, Claude usage credits, Codex flexible
+credits), harness-dispatch will spend that too. It cannot see or change provider-side
+billing state. What it does is refuse routes where *no* provider-side ceiling exists
+at all.
+
+Run `status` (or `status --json`) for any route's billing classification; the `note:`
+lines spell out the reasoning per route.
+
+<details>
+<summary>Renamed from <code>harness-router</code> — upgrade notes</summary>
+
+The npm package, CLI command, env var prefix (`HARNESS_DISPATCH_*`), and MCP resource
+URIs (`harness-dispatch://status`) all changed together. From an older install:
+`npm uninstall -g harness-router && npm install -g harness-dispatch`, then update any
+`mcpServers` / `claude_desktop_config.json` entry to invoke `harness-dispatch`.
+
+Two packages predate the rename and are unmaintained: `harness-router` (`0.3.2`) and
+the separately-published `harness-router-mcp` (`0.2.0`). Both lack `usage`,
+`/v1/models`, `/v1/usage`, Antigravity support, and every fix described here.
+
+`npx -y harness-dispatch`, the plugin's fallback launch path, resolves to whatever
+is currently on the npm registry, which can lag a local clone's `dist/`. Check with
+`npm ls -g harness-dispatch`.
+
+</details>
+
+## Safety profiles, and Cursor on Windows
+
+A caller asks for one of three profiles, and each is a limit rather than a
+capability:
+
+| Profile | Means |
+|---|---|
+| `read_only` | Look, don't touch |
+| `workspace_edit` | Edit files in the workspace, no arbitrary shell |
+| `full_auto` | Edit files and run shell |
+
+A route declares the floor it actually runs at (`effective_safety`), and is
+skipped when that floor exceeds what was asked for. A route is never quietly
+given more access than the caller requested.
+
+`cursor_cli` is the interesting case, because its capability differs by mode:
+
+- `read_only` uses `--mode plan`, which is genuinely read-only (verified: asked
+  to create one file and overwrite another, it did neither).
+- `full_auto` uses print mode, which edits and runs shell.
+- `workspace_edit` is **skipped on Windows**. Cursor's print mode grants write
+  and shell together, and `--sandbox enabled` — the flag that would constrain
+  shell while allowing edits — is macOS/Linux only. There is no edit-without-shell
+  mode to route to, so claiming that level would mean handing shell access to a
+  caller who explicitly asked not to have it.
+
+Cursor still edits code on Windows. Ask for `full_auto`.
+
+### Overriding it
+
+If you accept that Cursor's editing mode carries shell access and you want it
+to serve `workspace_edit` anyway, declare the floor yourself in `config.yaml` —
+your value replaces the shipped default:
+
+```yaml
+clis:
+  - name: cursor_cli
+    harness: cursor
+    command: cursor-agent
+    effective_safety:
+      read_only: read_only
+      workspace_edit: workspace_edit   # you are accepting shell access here
+      full_auto: full_auto
+```
+
+That is a deliberate local decision, not a bug workaround: the shipped default
+is conservative because the tool cannot verify what a given `cursor-agent`
+build will do. On macOS and Linux the better route is `--sandbox enabled`,
+which constrains shell for real — untested here, so it is not shipped on by
+default.
+
 ## Adding a harness
 
 `config.yaml` is entirely optional. There is no separate hidden defaults format —
@@ -264,17 +357,21 @@ harness-dispatch auth rotate             # rotate HTTP bearer token
 ```
 
 Hidden compatibility aliases currently map old alpha commands to the new surface:
-`dashboard` and `list-services` map to `status`, and `mcp --http <port>` maps to `serve`.
-They are not part of the public v0.4.0 vocabulary.
+`dashboard` and `list-services` map to `status`, `route <prompt>` runs a one-off
+routed dispatch, and `mcp --http <port>` maps to `serve`.
+They are not part of the public v0.6.0 vocabulary.
 
 ## MCP Surface
 
-`tools/list` returns three tools:
+`tools/list` returns six tools:
 
 | Tool | Purpose |
 | --- | --- |
 | `dispatch` | Always starts new routed coding work — one task to the best-fit harness, or a fanout to several for independent opinions. Every call runs as a background job from the first moment: a fast task returns its full result inline (`completed: true`), a slow one returns `completed: false` plus a `jobId` to check on. Nothing is ever lost to a timeout — including the MCP call's own. |
 | `job_status` | Checks work started by `dispatch`. Pass the `jobId` it returned to get a `partialOutput` tail while running and the full `result` once done; omit `jobId` to list recent background dispatches (compact, newest first). |
+| `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. 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. |
 
 `workingDir` is effectively required when starting work: if you omit it, the task runs
@@ -379,11 +476,18 @@ curl http://127.0.0.1:3333/v1/chat/completions \
 The REST surface is OpenAI-compatible enough for local clients that can speak
 `/v1/chat/completions`. The `model` field is treated as a routing/model hint.
 
+Non-streaming completions are backed by the same persisted job pipeline as the
+MCP `dispatch` tool: the reply carries `harness_dispatch.jobId`, and the same id
+is sent early as an `x-harness-dispatch-job-id` response header. If your client
+times out mid-run (curl defaults, CI step limits), the run still finishes and
+the result persists — recover it with the `job_status` MCP tool or by reading
+`~/.harness-dispatch/jobs/<jobId>/output/`.
+
 ## Endpoint Modes
 
-Harness Router supports two local/custom endpoint patterns:
+harness-dispatch supports two local/custom endpoint patterns:
 
-- `direct_openai_compatible`: Harness Router calls an OpenAI-compatible
+- `direct_openai_compatible`: harness-dispatch calls an OpenAI-compatible
   `/v1/chat/completions` endpoint directly. This is the right mode for Ollama,
   LM Studio, vLLM, LiteLLM, and private local HTTP model servers.
 - `harness_native_endpoint`: a downstream CLI keeps its agent scaffold but is
@@ -435,7 +539,7 @@ services:
 2. Verify configured routes without spending quota where possible.
 3. Classify auth and billing so paid or unknown-paid routes are not selected by accident.
 4. Choose routed harnesses, model priority, and safety profile.
-5. Write v0.4 config YAML.
+5. Write config YAML.
 6. Connect selected MCP agents or print snippets.
 
 The current command is conservative: it prints detected routes by default and writes
@@ -454,8 +558,10 @@ shape. Each route includes:
 - tier and model metadata
 - quota score and local call count
 - circuit breaker state — a tripped route's remaining cooldown is persisted to disk
-  (`~/.harness-dispatch/breaker_state.json`), so a server restart mid-cooldown still
-  excludes that route instead of retrying an exhausted one with a clean slate
+  (one file per route under `~/.harness-dispatch/breaker_state/`), so a server
+  restart mid-cooldown still excludes that route instead of retrying an exhausted
+  one with a clean slate; a pre-0.5 single-blob `breaker_state.json` is migrated
+  automatically on first read
 - skip reason when a route is disabled, unavailable, paid-blocked, unknown-billing,
   safety-incompatible, or circuit-broken
 - token limits when known
@@ -470,7 +576,9 @@ Workspace policy:
 
 - `shared`: run directly in the caller's `workingDir`.
 - `shared_locked`: run directly in `workingDir`, but serialize write-capable
-  dispatches for the same directory inside one router process.
+  dispatches for the same directory across ALL processes — concurrent dispatches
+  from separate server instances and detached job runners queue on a heartbeated
+  cross-process lock rather than editing the directory at the same time.
 - `copy`: copy the project into `.harness-dispatch/workspaces/...`, run the agent
   there, and return the isolated workspace path plus changed-file metadata.
 - `git_worktree`: create a detached git worktree for the route and return the
@@ -520,12 +628,49 @@ size-capped via single-file rotation, and never sent anywhere. Job artifacts
 `~/.harness-dispatch/jobs/<jobId>/` and are pruned after 7 days of inactivity by
 default — set `retention: { jobs_days: N }` in `config.yaml` (or
 `HARNESS_DISPATCH_JOB_MAX_AGE_MS` for a millisecond override) to change that
-window.
+window. `0` means keep forever, and a running or queued job with a live
+heartbeat is never pruned regardless of the window.
+
+At most **4 agent CLIs run at once**, machine-wide. Dispatches past that limit
+wait in `queued` and start as slots free — you still get a `jobId` back
+immediately and nothing is rejected or lost, only delayed. The bound exists
+because agent CLIs are heavyweight processes, not fan-outable HTTP calls: a
+measured burst of 13 concurrent runs exhausted memory and failed half of them.
+Change it with `max_concurrent_runs: N` in `config.yaml`; `0` removes the bound.
+
+Prompts and outputs flow only to the harnesses/endpoints you configured. **The
+router makes no other network call by default.**
+
+Routes rank on the `tier` and `weight` you set. Optionally, public Arena ELO
+benchmark data can inform ranking and derive tiers automatically:
+
+```yaml
+leaderboard:
+  enabled: true    # default false
+```
+
+Turning it on adds one GET to `api.wulong.dev` per process, refreshed daily.
+It sends nothing about you or your prompts. It is off by default because a
+benchmark maintained elsewhere should not quietly reorder the subscriptions
+you are paying for, and because a routing tool should not need the network to
+decide which of your local CLIs to run.
+
+## Chaining delegated work
+
+Pass the jobIds of earlier dispatches as `contextJobs` and their prompts and
+outputs are rendered into the new prompt directly:
+
+```json
+{ "prompt": "Now write the migration.", "contextJobs": ["job-1786977300001-0f0aaaaa"] }
+```
+
+Without it, chaining means reading the first job's output into your own context
+and re-summarising it into the second prompt — which spends the context that
+delegating was meant to save, and loses detail in the retelling.
 
-Prompts and outputs otherwise flow only to the harnesses/endpoints you
-configured. The router's only network call by default is the leaderboard
-refresh — a GET of public Arena ELO benchmark data from `api.wulong.dev` used
-for route scoring; it sends nothing about you or your prompts.
+Injected context is capped (24k characters total, 8k per job, 16 jobs) so it
+cannot crowd out the task itself, and a referenced job that is missing or still
+running is reported in the preamble rather than silently dropped.
 
 ## Development