harness-dispatch 0.9.0 → 0.10.0

package/README.md

@@ -63,28 +63,47 @@ found one.
 ```bash
 npm install -g harness-dispatch
 harness-dispatch configure --yes
-harness-dispatch doctor --live
+harness-dispatch doctor
 ```
 
+`doctor` checks your install, config, auth and routes without contacting any
+provider. Add `--live` when you want it to prove a dispatch really works end to
+end — that one sends a real request through an eligible route and spends
+whatever quota that route bills against, so it is a deliberate step rather than
+part of setup. `configure` is optional too: the tool auto-detects installed
+harnesses and runs without a `config.yaml` at all. Write one when you want to
+pin routes, add an endpoint, or change a default.
+
 `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. 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, 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`.
+tool's own state directory (`~/.harness-dispatch/`, or `HARNESS_DISPATCH_STATE_DIR`)
+— unless a `config.yaml` already exists in the current directory or
+`HARNESS_DISPATCH_CONFIG` is set, in which case that file is the target.
+
+Without `--yes` it previews and writes nothing.
+
+**Registering with your MCP clients.** After writing, `configure` offers to
+register this server with each client it finds (Claude Code, Cursor), showing
+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.
+
+**Re-running it.** A file `configure` wrote and you have not edited is
+regenerated, 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 when that happens; add `detect: true` to the
+file to merge newly installed harnesses in.
+
+**What `doctor` checks.** The whole chain: binary, config load, harness
+detection, auth and billing classification, route readiness, whether
+`dist/job-runner.js` is present (without it jobs run in-process and the
+concurrency cap does not apply), and for a Codex route it 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 through an eligible route, so you see a
+completion before wiring anything into your agent — that one spends quota, and
+it never touches paid or unknown-billing routes unless you pass `--allow-paid`.
 
 Your Claude Code / Codex / Cursor subscriptions run by default with no opt-in;
 `configure` tells you if anything is blocked and why.
@@ -390,14 +409,16 @@ harness-dispatch status --json           # structured route metadata
 harness-dispatch status --watch          # live status refresh
 harness-dispatch usage                   # per-route call counts, quota, billing kind
 harness-dispatch usage --json            # structured usage metadata
+harness-dispatch dispatch "<prompt>"     # route one task and print the result
+harness-dispatch dispatch "<prompt>" --service codex_cli --safety read_only --task-type review --no-fallback --json
 harness-dispatch serve --port 3333       # /mcp and /v1/* over local HTTP
 harness-dispatch auth show               # print HTTP bearer token
 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`, `route <prompt>` runs a one-off
-routed dispatch, and `mcp --http <port>` maps to `serve`.
+`dashboard` and `list-services` map to `status`, `route <prompt>` is an alias of
+`dispatch`, and `mcp --http <port>` maps to `serve`.
 They are not part of the public vocabulary and may be removed without a major
 version bump.
 
@@ -412,7 +433,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. `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. |
+| `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 get that `openai_compatible` route's model catalog instead of (or alongside) the summary: the route's declared `models:` list when it has one, otherwise a live `GET /models` from the endpoint. |
 
 `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
@@ -467,8 +488,8 @@ For fanout (each route that outlives the grace window returns its own `jobId`):
 ```
 
 Checking and listing (`job_status`): `{"jobId": "job-..."}` returns status plus
-`partialOutput` or the final `result`; `{}` (no `jobId`) returns every known background
-dispatch. On `dispatch`, force pure async with `"graceSeconds": 0`, or force a specific
+`partialOutput` or the final `result`; `{}` (no `jobId`) returns the 20 most recent
+background dispatches, newest first, plus an `omitted` count when there are more. On `dispatch`, force pure async with `"graceSeconds": 0`, or force a specific
 backend with a top-level `"service"` (single mode only). Nothing is lost by checking
 late — everything persists under `~/.harness-dispatch/jobs/<jobId>/`.
 
@@ -501,7 +522,6 @@ Endpoints:
 - `GET /v1/usage` — per-route call counts, quota, billing kind, and breaker state only
 - `GET /v1/models` — OpenAI-style model list; each entry's `id` is a route id you can
   pass as `model` in `/v1/chat/completions`
-- `POST /v1/chat/completions`
 
 HTTP uses the bearer token from `harness-dispatch auth show`. The same token protects
 MCP-over-HTTP and `/v1/*`.
@@ -562,15 +582,13 @@ endpoints:
     wire_protocol: openai_chat_completions
 ```
 
-Example Codex harness-native local route:
+Example Codex harness-native local route, as a `clis:` entry (the same shape
+`configure` writes; everything not set here comes from the shipped `codex` defaults):
 
 ```yaml
-services:
-  codex_ollama:
-    enabled: true
-    type: cli
+clis:
+  - name: codex_ollama
     harness: codex
-    command: codex
     model: qwen3-coder:latest
     endpoint_mode: harness_native_endpoint
     endpoint_provider: ollama
@@ -580,23 +598,32 @@ services:
     tier: 3
     weight: 0.75
     cli_capability: 1.0
-    timeout_ms: 900000  # optional; overrides the dispatcher's default (10 min for CLIs)
+    timeout_ms: 900000  # optional; overrides the 60-minute job default (10 min applies only to the CLI `dispatch` command and `doctor --live`)
     capabilities:
       execute: 0.8
       plan: 0.7
       review: 0.7
 ```
 
+The older top-level `services:` format still loads, but it is a separate format:
+a file that uses it has its `clis:`/`endpoints:` ignored with a warning, so do not
+mix the two.
+
 ## Configure
 
-`configure` is the main setup flow:
+`configure` is the main setup flow. It does four things, in order, and prompts for
+nothing except the final registration:
+
+1. Detect installed harness CLIs on PATH (or load the existing config, when there
+   is one it did not write itself — see the note on re-runs under Install).
+2. Print every route with its billing classification and effective safety
+   profile, and say which routes are blocked until you opt in to paid usage.
+3. Write the config YAML (`--yes`; without it, nothing is written).
+4. Offer to register with each MCP client it finds, or print the snippet
+   (`--no-clients`).
 
-1. Detect installed harnesses.
-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 config YAML.
-6. Connect selected MCP agents or print snippets.
+There is no interactive choice of harnesses, model priority or safety profile:
+edit the written file for those.
 
 The current command is conservative: it prints detected routes by default and writes
 only when explicitly asked with `--yes`.
@@ -653,9 +680,9 @@ that boundary.
 
 Provider notes:
 
-- Claude Code `claude -p` is treated date-aware: before June 15, 2026 it is classified
-  as plan usage; from June 15, 2026 it is classified as Agent SDK credits with possible
-  overage.
+- Claude Code `claude -p` is classified as included plan usage. Anthropic announced a
+  separate Agent SDK credit pool for it (2026-06-15) and paused that change before it
+  took effect; the classification will move only if the split actually ships.
 - Codex CLI/SDK uses the official Codex product surface unless a route is explicitly
   configured with an API key, in which case it is API billing.
 - Cursor Agent CLI is classified as included usage with possible on-demand continuation.
@@ -696,7 +723,11 @@ 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.
+Change it with `max_concurrent_runs: N` in `config.yaml`. `0` lifts the cap —
+jobs no longer queue for a slot — while still running them through the
+supervisor pool, so runner processes stay bounded at 4 however many jobs are in
+flight. Memory then scales with the harnesses you actually launch rather than
+with a per-job wrapper.
 
 Prompts and outputs flow only to the harnesses/endpoints you configured. **The
 router makes no other network call by default.**

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AASA,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAS5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CASjD;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAOvD;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAKvD;AAyBD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,mBAAmB,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAClD,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB,OAAO,CAOT;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG/C"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAQA,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAS5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CASjD;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAOvD;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAKvD;AAyBD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,mBAAmB,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAClD,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB,OAAO,CAOT;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG/C"}

package/dist/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/bin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;GAEG;AA+iCH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgK1D"}
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;GAEG;AA4qCH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA4K1D"}

package/dist/bin.js

@@ -3,6 +3,7 @@
  * harness-dispatch CLI entrypoint.
  */
 import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { installOutputRedaction } from "./redaction.js";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -16,6 +17,7 @@ import { codexLoginState } from "./dispatchers/shared/harness-login.js";
 import { clientConfigLocations, inspectClientEntries } from "./mcp-clients.js";
 import { buildDispatchers } from "./mcp/dispatcher-factory.js";
 import { startMcpServer } from "./mcp/server.js";
+import { resolveRunnerPath } from "./jobs.js";
 import { initObservability } from "./observability/index.js";
 import { QuotaCache } from "./quota.js";
 import { Router } from "./router.js";
@@ -36,8 +38,21 @@ async function buildRuntime(configPath) {
     const router = new Router(config, quota, dispatchers, leaderboard);
     return { config, dispatchers, quota, leaderboard, router };
 }
-function printUsage() {
-    process.stdout.write([
+/**
+ * Did this invocation ask for machine-readable output?
+ *
+ * Read from raw argv rather than the parsed flags because the two callers are
+ * the unknown-command branch and the top-level error handler, both of which
+ * run where parsing has either not happened or already failed. `--json=true`
+ * counts: an acceptance pass measured that spelling getting JSON on success
+ * and plain text on failure, which is the inconsistency the envelope exists to
+ * remove.
+ */
+function wantsJsonOutput() {
+    return process.argv.slice(2).some((a) => a === "--json" || a.startsWith("--json="));
+}
+function printUsage(stream = process.stdout) {
+    stream.write([
         "harness-dispatch",
         "",
         "Usage:",
@@ -79,7 +94,7 @@ function printUsage() {
         "",
     ].join("\n"));
 }
-async function cmdConfigure(configPath, explicitConfigPath, opts) {
+async function cmdConfigure(configPath, opts) {
     // configure's --config names where it will WRITE, so a path that does not
     // exist yet is the normal first-run case, not a typo.
     const target = configPath ?? userConfigPath();
@@ -97,15 +112,36 @@ async function cmdConfigure(configPath, explicitConfigPath, opts) {
         // literal key with no ${VAR} to restore is redacted rather than echoed.
         const preview = configToYaml(config, { redactLiterals: true });
         process.stdout.write(preview);
-        const redacted = Object.values(config.services).some((svc) => svc.apiKey !== undefined &&
+        const keyRedacted = Object.values(config.services).some((svc) => svc.apiKey !== undefined &&
             svc.apiKey !== "" &&
             config.envRefs?.get(svc.apiKey) === undefined &&
             config.apiKeyRefs?.get(svc.name) === undefined);
-        if (redacted) {
-            process.stderr.write("note: one or more api_key values are literals in the source config and were " +
-                "replaced with ${ENV_VAR} placeholders in this preview. Move them to " +
-                "environment variables — this output is not a drop-in replacement for that file " +
-                "until you do.\n");
+        // The note used to speak only for the api_key while the base_url beside it
+        // was printed whole, so a preview containing a URL password carried a
+        // sentence implying it had been sanitised. It now names what it did.
+        const urlRedacted = Object.values(config.services).some((svc) => {
+            if (svc.baseUrl === undefined || svc.baseUrl === "")
+                return false;
+            if (config.envRefs?.get(svc.baseUrl) !== undefined)
+                return false;
+            try {
+                const url = new URL(svc.baseUrl);
+                return (url.password !== "" || url.username !== "" || [...url.searchParams.keys()].length > 0);
+            }
+            catch {
+                return true;
+            }
+        });
+        if (keyRedacted || urlRedacted) {
+            const what = [
+                keyRedacted ? "api_key values" : undefined,
+                urlRedacted ? "credential-bearing parts of base_url" : undefined,
+            ]
+                .filter(Boolean)
+                .join(" and ");
+            process.stderr.write(`note: ${what} are literals in the source config and were redacted in this ` +
+                "preview. Move them to environment variables — this output is not a drop-in " +
+                "replacement for that file until you do.\n");
         }
         return 0;
     }
@@ -492,6 +528,13 @@ async function cmdDoctor(configPath, opts) {
     const nodeOk = (nodeMajor ?? 0) > 22 ||
         ((nodeMajor ?? 0) === 22 &&
             ((nodeMinor ?? 0) > 22 || ((nodeMinor ?? 0) === 22 && (nodePatch ?? 0) >= 2)));
+    const configuredCommands = new Set(status.routes
+        .map((route) => route.command)
+        .filter((command) => typeof command === "string")
+        .map((command) => path.basename(command).replace(/\.(cmd|exe)$/i, "")));
+    const unconfiguredHarnesses = runtime.config.detectionRan === false
+        ? Object.values(AUTO_DETECT_COMMANDS).filter((command) => commandAvailable(command) && !configuredCommands.has(command))
+        : [];
     const checks = [
         {
             name: "node",
@@ -507,9 +550,17 @@ async function cmdDoctor(configPath, opts) {
             // question: `configure` run from one directory and `doctor` from
             // another used to load different things and neither said so.
             detail: `${Object.keys(runtime.config.services).length} configured route(s)` +
-                (configPath !== undefined
-                    ? ` from ${path.resolve(configPath)}`
-                    : " (no config file found; shipped defaults with auto-detected harnesses)"),
+                (configPath === undefined
+                    ? " (no config file found; shipped defaults with auto-detected harnesses)"
+                    : runtime.config.detectionRan === false
+                        ? ` from ${path.resolve(configPath)}`
+                        : // Detection ran. Two different reasons, and saying the wrong one
+                            // is confusing: a file may define no routes at all, or it may
+                            // define some AND ask for detection with `detect: true`. The
+                            // first version reported the former for both.
+                            (runtime.config.detect === true
+                                ? ` from ${path.resolve(configPath)} plus auto-detected harnesses (detect: true)`
+                                : ` auto-detected — ${path.resolve(configPath)} defines no routes of its own`)),
         },
         // This one DOES fail, unlike the advisory git check below.
         //
@@ -618,11 +669,22 @@ async function cmdDoctor(configPath, opts) {
             // When nothing is ready, say what was looked for. "0 ready route(s)" on
             // its own leaves a new user with no idea whether the tool is broken or
             // simply has nothing to route to, and no hint what to install.
-            detail: status.ready.length > 0
-                ? `${status.ready.length} ready route(s)`
+            detail: (status.ready.length > 0
+                ? // Trailing period so this reads as a sentence when the
+                    // installed-but-unconfigured note is appended after it.
+                    `${status.ready.length} ready route(s).`
                 : `0 ready route(s). Looked for these harness CLIs on PATH: ` +
                     `${Object.values(AUTO_DETECT_COMMANDS).join(", ")}. ` +
-                    `Install one, or add a route to config.yaml (endpoints: need no CLI).`,
+                    `Install one, or add a route to config.yaml (endpoints: need no CLI).`) +
+                // A config that lists its own routes is authoritative, so a harness
+                // installed later is simply absent — and this line said "1 ready
+                // route(s)" with a second CLI on PATH and no hint. The hint about PATH
+                // above only fired at zero routes.
+                (unconfiguredHarnesses.length > 0
+                    ? ` Installed but not in this config: ${unconfiguredHarnesses.join(", ")} — add ` +
+                        `\`detect: true\` to ${configPath !== undefined ? path.resolve(configPath) : "the config"} ` +
+                        `to merge them, or a clis: entry for each.`
+                    : ""),
         },
         {
             // Nothing checked this, so an unwritable state directory surfaced only
@@ -630,8 +692,27 @@ async function cmdDoctor(configPath, opts) {
             // run finished" — a false cause, 90s after the work had actually
             // succeeded.
             name: "state-dir",
-            ok: stateDirWritable().ok,
-            detail: stateDirWritable().detail,
+            // Called ONCE: each call creates and deletes a probe file, and this
+            // asked the same question twice to fill two fields.
+            ...stateDirWritable(),
+        },
+        {
+            // Whether dispatches will actually be detached.
+            //
+            // `resolveRunnerPath()` returning undefined is not an error — it is the
+            // signal to run the job IN-PROCESS, which is right for an unbuilt
+            // checkout and wrong everywhere else: the concurrency cap is enforced by
+            // the supervisor pool, so in-process mode silently removes the bound
+            // that exists because of a measured OOM. It prints one line on stderr at
+            // dispatch time and nothing checked it, so "am I actually capped?" had
+            // no answer. An audit noticed; this is that answer.
+            name: "job-runner",
+            ok: resolveRunnerPath() !== undefined,
+            detail: resolveRunnerPath() !== undefined
+                ? "found; jobs run detached and the concurrency cap applies"
+                : "dist/job-runner.js not found — jobs will run IN-PROCESS, which " +
+                    "removes the max_concurrent_runs cap and does not survive a server " +
+                    "restart. Run `npm run build`, or reinstall the package.",
         },
         {
             name: "http-auth",
@@ -652,6 +733,40 @@ async function cmdDoctor(configPath, opts) {
     const codexRoutes = status.routes.filter((route) => status.ready.includes(route.id) && route.harness === "codex" && route.command);
     const loginStates = await Promise.all(codexRoutes.map(async (route) => ({ route, state: await codexLoginState(route.command) })));
     const loggedOut = loginStates.filter((entry) => entry.state === "logged_out");
+    // A route that has NEVER succeeded is worth saying out loud.
+    //
+    // The breaker is about recent failure and forgets after its cooldown, so a
+    // route that is simply dead — a host that no longer resolves, a key that was
+    // revoked — keeps being selected, failing, and falling back, forever. On the
+    // maintainer's own machine a local endpoint sat at 8 calls and 0 successes
+    // while being tier-3-preferred for `review`, so every review dispatch paid
+    // for one doomed attempt before falling back. Nothing reported it: `usage`
+    // showed the counts and nobody reads `usage` when things merely feel slow.
+    //
+    // Advisory, never a failure: a fresh install has no calls at all, and a
+    // route can legitimately fail its first few (a laptop that was asleep). The
+    // threshold is about having enough evidence to be worth mentioning, not
+    // about being sure.
+    const NEVER_SUCCEEDED_MIN_CALLS = 5;
+    const deadRoutes = status.routes
+        .filter((route) => status.ready.includes(route.id))
+        .map((route) => ({
+        id: route.id,
+        calls: route.quota.localCallCount ?? 0,
+        successes: route.quota.localSuccessCount ?? 0,
+    }))
+        .filter((r) => r.calls >= NEVER_SUCCEEDED_MIN_CALLS && r.successes === 0);
+    checks.push({
+        name: "route-health",
+        ok: true,
+        detail: deadRoutes.length === 0
+            ? "no ready route has failed every call it has been given"
+            : deadRoutes
+                .map((r) => `${r.id} has never succeeded (${r.calls} calls, 0 successes) — it is still ` +
+                `being selected and failing, so every dispatch it wins costs an attempt ` +
+                `before falling back. Check the endpoint or credential, or disable it.`)
+                .join(" | "),
+    });
     checks.push({
         name: "harness-login",
         ok: loggedOut.length === 0,
@@ -757,8 +872,10 @@ async function cmdAuth(action) {
             return 0;
         }
         default:
-            process.stderr.write("auth: expected show or rotate\n");
-            return 1;
+            // Thrown, not written: the top-level handler is the one place that
+            // knows whether --json was asked for. Written here it bypassed the
+            // envelope, so `auth --json` reported failure as a bare sentence.
+            throw new UsageError("auth: expected show or rotate");
     }
 }
 /**
@@ -777,9 +894,8 @@ async function cmdAuth(action) {
  */
 async function cmdDispatch(prompt, configPath, opts) {
     if (!prompt) {
-        process.stderr.write('dispatch: missing prompt. Usage: dispatch [--service <id>] [--safety <profile>]\n' +
-            '          [--task-type <type>] [--no-fallback] [--json] "<prompt>"\n');
-        return 1;
+        throw new UsageError('dispatch: missing prompt. Usage: dispatch [--service <id>] [--safety <profile>] ' +
+            '[--task-type <type>] [--no-fallback] [--json] "<prompt>"');
     }
     const runtime = await buildRuntime(configPath);
     const hints = { taskType: opts.taskType ?? "execute" };
@@ -864,6 +980,9 @@ function serveOpts(values) {
     return out;
 }
 export async function main(argv) {
+    // Terminal output is a sink; see src/redaction.ts. Installed before any
+    // config is loaded, which is fine — the registry is consulted per write.
+    installOutputRedaction();
     const { values, positionals } = parseArgs({
         args: argv,
         options: {
@@ -929,7 +1048,10 @@ export async function main(argv) {
     const [command, ...rest] = positionals;
     // `--config` with no value: parseArgs yields boolean true, which reached
     // path.join and threw ERR_INVALID_ARG_TYPE as a raw Node stack trace.
-    if (values.config !== undefined && typeof values.config !== "string") {
+    // `--config=` (empty) is the same mistake with a string type: it resolved to
+    // "", loadConfig treated it as no path, and doctor reported the auto-detected
+    // routes as loaded "from" the current directory.
+    if (values.config !== undefined && (typeof values.config !== "string" || values.config === "")) {
         throw new UsageError("--config needs a path, e.g. --config ./config.yaml");
     }
     const explicitConfigPath = values.config;
@@ -955,7 +1077,7 @@ export async function main(argv) {
     }
     switch (command) {
         case "configure":
-            return cmdConfigure(configPath, explicitConfigPath, {
+            return cmdConfigure(configPath, {
                 print: Boolean(values.print),
                 yes: Boolean(values.yes),
                 force: Boolean(values.force),
@@ -1011,9 +1133,16 @@ export async function main(argv) {
             }
             return main(configPath !== undefined ? ["--config", configPath] : []);
         default:
-            process.stderr.write(`unknown command: ${command}\n`);
-            printUsage();
-            return 1;
+            // Usage goes to STDERR here, not stdout. An unknown command is an
+            // error, and printing the help block on stdout meant
+            // `harness-dispatch frobnicate --json | jq` got the usage text as
+            // its input — the exact pipe the --json envelope keeps parseable.
+            // Suppressed under --json: the caller asked for machine-readable
+            // output, and a help block ahead of the envelope makes stderr
+            // unparseable in the same way stdout was.
+            if (!wantsJsonOutput())
+                printUsage(process.stderr);
+            throw new UsageError(`unknown command: ${command}`);
     }
 }
 /**
@@ -1077,8 +1206,16 @@ if (isThisFile(entrypoint)) {
         // reliable way to tell "bug" from "bad input" by class here. Only a
         // non-Error throw (a genuine programming error) keeps its stack.
         if (err instanceof UsageError || err instanceof Error) {
-            process.stderr.write(`harness-dispatch: ${err.message}
-`);
+            // `--json` is a promise about the SHAPE of this command's output, and
+            // it was kept only on the success path: a bad --config made
+            // `doctor --json` print a sentence, so anything parsing the output got
+            // a parse error instead of the reason. The message is the same; only
+            // the envelope follows what was asked for. Errors still go to stderr,
+            // so a caller reading stdout for results is unaffected either way.
+            const wantsJson = wantsJsonOutput();
+            process.stderr.write(wantsJson
+                ? `${JSON.stringify({ ok: false, error: err.message }, null, 2)}\n`
+                : `harness-dispatch: ${err.message}\n`);
             process.exit(1);
         }
         throw err;