harness-dispatch 0.8.0 → 0.10.0

package/dist/bin.js

@@ -2,7 +2,8 @@
 /**
  * harness-dispatch CLI entrypoint.
  */
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+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";
@@ -12,9 +13,11 @@ import { AUTO_DETECT_COMMANDS, loadConfig, resolveConfigPath } from "./config.js
 import { LeaderboardCache } from "./leaderboard.js";
 import { VERSION } from "./version.js";
 import { commandAvailable } from "./dispatchers/shared/which-available.js";
-import { inspectClientEntries } from "./mcp-clients.js";
+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";
@@ -22,9 +25,9 @@ import { buildStatus, buildUsage, renderStatusText, renderUsageText } from "./st
 import { startHttpServer } from "./http/server.js";
 import { billingIsBlocked, buildRouteBilling } from "./billing.js";
 import { effectiveSafetyProfile } from "./safety.js";
-import { configToYaml } from "./configure-yaml.js";
-import { devLaunchCommand, planClientWrites, removeClientEntry, writeClientEntry, } from "./client-register.js";
-import { stateRoot } from "./state-dir.js";
+import { configToYaml, isUneditedGenerated, stampGenerated } from "./configure-yaml.js";
+import { desiredEntry, devLaunchCommand, launchCommand, planClientWrites, removeClientEntry, writeClientEntry, } from "./client-register.js";
+import { stateRoot, userConfigPath } from "./state-dir.js";
 async function buildRuntime(configPath) {
     const config = await loadConfig(configPath);
     const dispatchers = await buildDispatchers(config);
@@ -35,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:",
@@ -78,30 +94,68 @@ 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 config = await loadConfig(configPath, { allowMissing: true });
+    const target = configPath ?? userConfigPath();
+    // A file configure wrote and nobody edited is regenerated from a fresh
+    // detection rather than loaded: loading it would make it authoritative and
+    // hide the harness installed since — the reason the user is re-running.
+    // Anything else on disk is the user's, loaded so its settings migrate, and
+    // guarded below. See stampGenerated for the natural-order story.
+    const existing = existsSync(target) ? await fs.readFile(target, "utf-8") : undefined;
+    const regenerate = existing !== undefined && isUneditedGenerated(existing);
+    const config = await loadConfig(regenerate ? undefined : configPath, { allowMissing: true });
     const routeCount = Object.keys(config.services).length;
     if (opts.print) {
         // Preview goes to a terminal and, routinely, into a bug report — a
         // 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;
     }
     const yamlText = configToYaml(config, { redactLiterals: false });
-    process.stdout.write(`Detected ${routeCount} harness route${routeCount === 1 ? "" : "s"}.\n`);
+    // "Detected" is only true when detection ran. Over an edited file that lists
+    // its own routes it does not (the file is authoritative), and an acceptance
+    // pass measured `configure --yes --force` printing "Detected 1 harness route"
+    // with a second harness on PATH that never appeared in the output.
+    const plural = routeCount === 1 ? "" : "s";
+    process.stdout.write(config.detectionRan === false
+        ? `${routeCount} route${plural} from ${path.resolve(configPath ?? target)} — detection did not run, ` +
+            "because this file lists its own routes. To merge harnesses installed since, add " +
+            "`detect: true` to it; to start over from a fresh detection, delete it first.\n"
+        : `Detected ${routeCount} harness route${plural}.\n`);
     for (const [name, svc] of Object.entries(config.services)) {
         process.stdout.write(`- ${name}: harness=${svc.harness ?? name} billing=${buildRouteBilling(svc).kind} safety=${effectiveSafetyProfile(svc)} model=${svc.model ?? svc.leaderboardModel ?? "unknown"}\n`);
     }
@@ -120,7 +174,10 @@ async function cmdConfigure(configPath, explicitConfigPath, opts) {
             process.stdout.write(`- ${warning}\n`);
         }
     }
-    const target = configPath ?? "config.yaml";
+    if (regenerate) {
+        process.stdout.write(`\n${path.resolve(target)} is unedited configure output — ` +
+            `${opts.yes ? "regenerating it from this detection" : "--yes will regenerate it from this detection"}.\n`);
+    }
     if (!opts.yes) {
         process.stdout.write(`\nNo files written. Re-run with --yes to write ${target}, or use --print to inspect YAML.\n`);
         process.stdout.write("After writing config, connect agents by adding the harness-dispatch MCP snippet to the agent you use.\n");
@@ -133,7 +190,7 @@ async function cmdConfigure(configPath, explicitConfigPath, opts) {
     // you to pass --config, which is exactly what disabled it. Overwriting a
     // hand-written config is not recoverable, so it now takes an explicit
     // --force rather than an accident of which flag you happened to use.
-    if (existsSync(target) && !opts.force) {
+    if (existsSync(target) && !opts.force && !regenerate) {
         process.stderr.write(`configure: ${target} already exists and would be overwritten.\n` +
             "Use --print to inspect the generated YAML, --config <other-path> to write\n" +
             "elsewhere, or --force to overwrite it deliberately.\n");
@@ -151,9 +208,12 @@ async function cmdConfigure(configPath, explicitConfigPath, opts) {
     // Applied on create only: `writeFile`'s mode does not change an existing
     // file's permissions, so re-running `configure` will not silently tighten a
     // file the user deliberately made group-readable.
-    await fs.writeFile(target, yamlText, { encoding: "utf-8", mode: 0o600 });
+    // The default target lives in the state directory, which a first run has
+    // not created yet. Same mode the rest of the state dir gets.
+    await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    await fs.writeFile(target, stampGenerated(yamlText), { encoding: "utf-8", mode: 0o600 });
     const absoluteTarget = path.resolve(target);
-    process.stdout.write(`Wrote ${target}.\n`);
+    process.stdout.write(`Wrote ${absoluteTarget}.\n`);
     // The last step of setup used to be "here is some JSON, paste it somewhere".
     // Nobody owned the result, and the paths in it later moved — which is how one
     // machine ended up running a dead entry, a dead hook, and a third client
@@ -174,7 +234,16 @@ async function cmdConfigure(configPath, explicitConfigPath, opts) {
     process.stdout.write("\nMCP snippet (uses an absolute --config path so it resolves correctly no matter what\n" +
         "directory the MCP client launches from — a relative path or none at all silently\n" +
         "falls back to the shipped defaults, ignoring every edit you make to this file):\n");
-    printMcpSnippet({ command: "harness-dispatch", args: ["--config", absoluteTarget] });
+    // The SAME entry `connect` writes, built by the same function.
+    //
+    // This printed a hardcoded `harness-dispatch --config <path>` while connect
+    // writes whatever `launchCommand()` resolves to — `npx -y harness-dispatch
+    // --config <path>` without a global install. So pasting the snippet this
+    // command prints and then running `connect --remove` was answered "has an
+    // entry we did not write — left alone unless --force", and exit 1. The tool
+    // called its own documented output hand-edited, and blocked both update and
+    // removal on the manual-install path it had just recommended.
+    printMcpSnippet(desiredEntry(absoluteTarget, launchCommand()));
     process.stdout.write("Or let `harness-dispatch connect` write it for you.\n");
     return 0;
 }
@@ -194,7 +263,7 @@ function printMcpSnippet(entry) {
  * than hanging or guessing.
  */
 async function cmdConnect(configPath, opts) {
-    const target = path.resolve(configPath ?? "config.yaml");
+    const target = path.resolve(configPath ?? userConfigPath());
     if (!existsSync(target) && !opts.remove) {
         process.stderr.write(`connect: no config at ${target}. Run \`harness-dispatch configure --yes\` first —\n` +
             "a client entry pointing at a config that does not exist is the failure this\n" +
@@ -272,7 +341,8 @@ async function cmdConnect(configPath, opts) {
             : await writeClientEntry(plan, { stamp, consented });
         if (outcome.action === "written") {
             wrote = true;
-            process.stdout.write(`${opts.remove ? "Removed from" : "Wrote"} ${outcome.client} (backup: ${outcome.backupPath})\n`);
+            process.stdout.write(`${opts.remove ? "Removed from" : "Wrote"} ${outcome.client} ` +
+                `(${outcome.backupPath !== undefined ? `backup: ${outcome.backupPath}` : `created ${outcome.file}`})\n`);
         }
         else if (outcome.action === "unchanged") {
             process.stdout.write(`${outcome.client}: ${opts.remove ? "no entry of ours to remove" : "already correct"}, nothing changed.\n`);
@@ -299,6 +369,7 @@ function describeState(state, removing) {
     if (removing) {
         return {
             absent: "not installed",
+            "missing-file": "installed, no config file yet — nothing to remove",
             unreadable: "config does not parse — will be left alone",
             "missing-entry": "no entry of ours to remove",
             matches: "our entry is here — will be removed",
@@ -307,6 +378,7 @@ function describeState(state, removing) {
     }
     return {
         absent: "not installed",
+        "missing-file": "installed, no config file yet — one will be created",
         unreadable: "config does not parse — will be left alone",
         "missing-entry": "no harness-dispatch entry yet",
         matches: "already registered correctly",
@@ -328,7 +400,24 @@ function summariseEntry(entry) {
  * differing entry was the WORKING one.
  */
 async function chooseInteractively(plans, opts) {
-    const actionable = plans.filter((p) => p.state !== "matches" && p.state !== "unreadable");
+    // What counts as actionable INVERTS under --remove.
+    //
+    // Registering: `matches` means the entry is already what we would write, so
+    // there is nothing to do. Removing: `matches` is exactly the entry being
+    // removed, so filtering it out left nothing actionable — and the command
+    // printed "our entry is here — will be removed", exited 0, and changed
+    // nothing. Reproduced byte-for-byte: same md5 before and after.
+    //
+    // Only the bare form was affected, because `--clients` bypasses this
+    // function entirely. That is the form README documents twice and
+    // OPERATIONS.md once, and no test covered this command at all.
+    // Stated as what IS actionable rather than what is not: the states are
+    // absent / unreadable / missing-entry / matches / differs, and under
+    // --remove only the two that actually hold an entry qualify. Written as a
+    // negation, `absent` (no config file at all) slipped through.
+    const actionable = plans.filter((p) => opts.remove === true
+        ? p.state === "matches" || p.state === "differs"
+        : p.state !== "matches" && p.state !== "unreadable");
     if (actionable.length === 0)
         return [];
     // `--yes` skips the question; it does NOT answer it.
@@ -341,8 +430,12 @@ async function chooseInteractively(plans, opts) {
     if (opts.yes)
         return actionable;
     if (!process.stdin.isTTY) {
-        process.stdout.write("\nNot a terminal, so nothing was written. Re-run with --clients " +
-            `${actionable.map((p) => p.id).join(",")} (or --yes) to apply.\n`);
+        process.stdout.write(
+        // Names the command, not just the flags: this is reached from
+        // `configure --yes` too, where "or --yes" told the user to pass the flag
+        // they had already passed.
+        "\nNot a terminal, so nothing was written. Run `harness-dispatch connect --clients " +
+            `${actionable.map((p) => p.id).join(",")}\` (or \`connect --yes\`) to register.\n`);
         return undefined;
     }
     const { createInterface } = await import("node:readline/promises");
@@ -435,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",
@@ -446,7 +546,21 @@ async function cmdDoctor(configPath, opts) {
         {
             name: "config",
             ok: Object.keys(runtime.config.services).length > 0,
-            detail: `${Object.keys(runtime.config.services).length} configured route(s)`,
+            // Names the file, because "which config is this looking at" was the
+            // 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
+                    ? " (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.
         //
@@ -464,11 +578,20 @@ async function cmdDoctor(configPath, opts) {
             const entries = inspectClientEntries();
             const broken = entries.filter((e) => e.missingPaths.length > 0);
             if (entries.length === 0) {
+                // Name the client that IS here, so "not registered" reads as the
+                // next step rather than as "nothing to register with".
+                const present = clientConfigLocations()
+                    .filter((c) => c.commands.some((cmd) => commandAvailable(cmd)))
+                    .map((c) => c.client);
                 return {
                     name: "mcp-clients",
                     ok: true,
-                    detail: "not registered with any MCP client this tool knows how to read " +
-                        "(Claude Code, Cursor) — run `harness-dispatch connect` to register it",
+                    detail: present.length > 0
+                        ? `${present.join(", ")} installed but harness-dispatch is not registered with it — ` +
+                            "run `harness-dispatch connect`"
+                        : "not registered with any MCP client this tool knows how to read " +
+                            "(Claude Code, Cursor), and none is installed — run `harness-dispatch connect` " +
+                            "after installing one",
                 };
             }
             return {
@@ -546,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
@@ -558,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",
@@ -570,6 +723,63 @@ async function cmdDoctor(configPath, opts) {
         },
     ];
     const blocked = status.skippedRoutes.filter((skip) => skip.code === "paid_blocked" || skip.code === "unknown_billing");
+    // A ready route is one whose CLI is on PATH. That said nothing about whether
+    // the CLI could actually make a request: an installed, never-logged-in Codex
+    // passed routes, billing and safety, and the first dispatch then failed with
+    // a raw OpenAI 401 that never mentioned `codex login`. The cold-install walk
+    // in acceptance/0.8.0.md is where that was seen. The CLI is asked directly
+    // (see harness-login.ts for why not the credential file), and only a
+    // definite "not logged in" fails the check.
+    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,
+        detail: loginStates.length === 0
+            ? "no ready route has a login state this tool knows how to ask for (Codex only, today)"
+            : loggedOut.length > 0
+                ? `${loggedOut.map((entry) => entry.route.id).join(", ")}: codex reports "Not logged in" — ` +
+                    "run `codex login` (or `codex login --with-api-key`), or every dispatch to it fails " +
+                    "with 401 Unauthorized from OpenAI"
+                : loginStates
+                    .map((entry) => `${entry.route.id}: ${entry.state === "logged_in" ? "logged in" : "could not determine (codex login status gave no answer)"}`)
+                    .join("; "),
+    });
     checks.push({
         name: "billing-policy",
         ok: true,
@@ -662,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");
     }
 }
 /**
@@ -682,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" };
@@ -769,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: {
@@ -834,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;
@@ -860,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),
@@ -916,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}`);
     }
 }
 /**
@@ -949,8 +1173,27 @@ function finish(code) {
     }, EXIT_DRAIN_GRACE_MS);
     bail.unref();
 }
-const entrypoint = typeof process !== "undefined" && Array.isArray(process.argv) ? process.argv[1] : "";
-if (entrypoint && (entrypoint.endsWith("bin.ts") || entrypoint.endsWith("bin.js"))) {
+// Run main() only when this file is the process entrypoint, not when a test
+// imports it. `argv[1]` is the path the user invoked, which is NOT this file
+// when npm installed the command as a symlink (`/usr/local/bin/harness-dispatch`
+// on Linux and macOS): node does not resolve it, so a name check alone
+// silently ran nothing there and exited 0 — every documented command was a
+// no-op for every non-Windows `npm install -g` user through 0.8.0. Windows
+// never hit it because npm's .cmd shim passes the real dist/bin.js path.
+const entrypoint = typeof process !== "undefined" && Array.isArray(process.argv) ? (process.argv[1] ?? "") : "";
+function isThisFile(invoked) {
+    if (!invoked)
+        return false;
+    if (invoked.endsWith("bin.ts") || invoked.endsWith("bin.js"))
+        return true;
+    try {
+        return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isThisFile(entrypoint)) {
     void main(process.argv.slice(2))
         .then((code) => {
         finish(code);
@@ -963,8 +1206,16 @@ if (entrypoint && (entrypoint.endsWith("bin.ts") || entrypoint.endsWith("bin.js"
         // 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;