harness-dispatch 0.7.9 → 0.9.0

package/dist/bin.js

@@ -2,15 +2,18 @@
 /**
  * harness-dispatch CLI entrypoint.
  */
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { ensureHttpToken, maskToken, readHttpToken, rotateHttpToken, tokenPath } from "./auth.js";
 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 { 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 { initObservability } from "./observability/index.js";
@@ -20,8 +23,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 { 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);
@@ -39,6 +43,8 @@ function printUsage() {
         "Usage:",
         "  harness-dispatch                         Start stdio MCP.",
         "  harness-dispatch configure [--print]     Detect and prepare harness config.",
+        "  harness-dispatch connect                 Register this server with the MCP clients you have.",
+        "  harness-dispatch connect --remove        Take the entry back out again.",
         "  harness-dispatch doctor [--json]         Check install, config, auth, and routes.",
         "  harness-dispatch doctor --live           Run one routed probe when billing policy allows it.",
         "  harness-dispatch doctor --live --allow-paid  Run a live probe through paid/unknown routes.",
@@ -46,6 +52,7 @@ function printUsage() {
         "  harness-dispatch status --watch          Re-render status every --interval ms.",
         "  harness-dispatch usage [--json]          Show per-route call counts, quota, and billing kind.",
         "  harness-dispatch serve [--port 3333]     Serve MCP at /mcp and REST at /v1/*.",
+        '  harness-dispatch dispatch "<prompt>"     Route one task and print the result.',
         "  harness-dispatch auth show               Print the HTTP bearer token.",
         "  harness-dispatch auth rotate             Rotate the HTTP bearer token.",
         "",
@@ -58,7 +65,15 @@ function printUsage() {
         "  --print               configure: print generated config YAML without writing it.",
         "  --yes                 configure: write config.yaml instead of only previewing it.",
         "  --force               configure: overwrite an existing config file.",
+        "  --clients <ids>       connect: comma-separated client ids, instead of prompting.",
+        "  --no-clients          configure: skip the offer to register with clients.",
+        "  --remove              connect: remove the entry rather than write it.",
+        "  --dev                 connect: point clients at THIS checkout's build, not the package.",
         "  --allow-paid          Allow doctor --live to probe paid or unknown-paid routes.",
+        "  --service <id>        dispatch: run exactly this route, no fallback to others.",
+        "  --safety <profile>    dispatch: read_only | workspace_edit | full_auto.",
+        "  --task-type <type>    dispatch: execute | plan | review | local.",
+        "  --no-fallback         dispatch: do not retry on another route if the first fails.",
         "  -h, --help            Show help.",
         "  -v, --version         Print the version and exit.",
         "",
@@ -67,7 +82,15 @@ function printUsage() {
 async function cmdConfigure(configPath, explicitConfigPath, 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
@@ -87,7 +110,16 @@ async function cmdConfigure(configPath, explicitConfigPath, opts) {
         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`);
     }
@@ -106,7 +138,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");
@@ -119,28 +154,266 @@ 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");
         return 1;
     }
-    await fs.writeFile(target, yamlText, "utf-8");
+    // 0600, because this file can contain a LITERAL api_key: `apiKeyForYaml`
+    // deliberately preserves one rather than replacing it with a `${VAR}`
+    // reference, so `configure` can write a real credential to disk. It was
+    // written with default permissions — 0644 under a typical umask — in a
+    // module family that is careful everywhere else (leaderboard 0600, state dir
+    // 0700, client-register carries the original file's mode). Found by an
+    // acceptance pass from reading, POSIX-only and not reproduced on Windows,
+    // where the mode is ignored.
+    //
+    // 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.
+    // 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("MCP snippet (uses an absolute --config path so it resolves correctly no matter what\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
+    // reading a different config, all silently. Offer to do it instead.
+    if (!opts.noClients) {
+        process.stdout.write("\n");
+        return cmdConnect(configPath, {
+            clients: opts.clients,
+            remove: false,
+            yes: false,
+            force: false,
+            // Setup registers the installed package. A checkout entry is a
+            // deliberate choice made by someone who knows they have a checkout, not
+            // something to infer during first-run setup.
+            dev: false,
+        });
+    }
+    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");
-    process.stdout.write(JSON.stringify({
-        mcpServers: {
-            "harness-dispatch": {
-                command: "harness-dispatch",
-                args: ["--config", absoluteTarget],
-            },
-        },
-    }, null, 2) + "\n");
+    // 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;
 }
+/** The entry, in the shape a client's config file wants it pasted. */
+function printMcpSnippet(entry) {
+    if (entry === undefined)
+        return;
+    process.stdout.write(JSON.stringify({ mcpServers: { "harness-dispatch": entry } }, null, 2) + "\n");
+}
+/**
+ * Register this server with the MCP clients on this machine — the last step of
+ * setup, which used to be "paste this snippet somewhere".
+ *
+ * Interactive when a human is at a terminal, flag-driven otherwise. A prompt
+ * that blocks is right in front of a person and wrong in CI, so with no TTY
+ * and no `--clients` this reports what it WOULD do and writes nothing, rather
+ * than hanging or guessing.
+ */
+async function cmdConnect(configPath, opts) {
+    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" +
+            "command exists to prevent.\n");
+        return 1;
+    }
+    // `import.meta.url` is this running file — dist/bin.js for an installed or
+    // built copy. "The build you are running now" is the only honest answer to
+    // which checkout --dev means, and it needs no flag value to get wrong.
+    const selfPath = fileURLToPath(import.meta.url);
+    const plans = planClientWrites(target, opts.dev ? { command: devLaunchCommand(selfPath) } : {});
+    if (opts.dev && !opts.remove) {
+        process.stdout.write(`Development entry: clients will launch ${selfPath} directly.\n` +
+            "That is an absolute path — it stops working, silently, if this directory is\n" +
+            "renamed or deleted. `harness-dispatch doctor` fails when that happens.\n\n");
+    }
+    const known = new Set(plans.map((p) => p.id));
+    const requested = opts.clients
+        ?.split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const unknown = requested?.filter((id) => !known.has(id)) ?? [];
+    if (unknown.length > 0) {
+        process.stderr.write(`connect: unknown client${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. ` +
+            `Known: ${[...known].join(", ")}.\n`);
+        return 1;
+    }
+    const installed = plans.filter((p) => p.state !== "absent");
+    if (installed.length === 0) {
+        process.stdout.write("No MCP clients found on this machine (looked for Claude Code and Cursor).\n" +
+            "Nothing to register. Add this to whichever client you use, then re-run\n" +
+            "`harness-dispatch connect` if you install one of the two above:\n");
+        // Setup has to end with something you can act on. Without this, a machine
+        // with no client detected got a cheerful "nothing to do" and no way to
+        // finish wiring anything up — the snippet was the ONLY output this replaced.
+        printMcpSnippet(plans[0]?.desired);
+        return 0;
+    }
+    if (!opts.remove) {
+        // Stated once, up front, rather than only inside the diff for entries that
+        // happen to differ. What gets written should not be something you can only
+        // learn from a client being in a particular state.
+        process.stdout.write(`Entry to write: ${JSON.stringify(plans[0].desired)}\n\n`);
+    }
+    process.stdout.write(`${opts.remove ? "Removing from" : "Registering with"} clients:\n`);
+    for (const p of installed) {
+        process.stdout.write(`  ${p.client.padEnd(12)} ${p.file}  (${describeState(p.state, opts.remove)})\n`);
+        if (p.state === "differs") {
+            process.stdout.write(`    currently: ${JSON.stringify(summariseEntry(p.current))}\n`);
+        }
+    }
+    const chosen = requested
+        ? installed.filter((p) => requested.includes(p.id))
+        : await chooseInteractively(installed, opts);
+    // Consent to replace a HAND-EDITED entry comes from ANSWERING the
+    // interactive prompt, which shows the difference first, or from --force.
+    //
+    // Neither `--clients` nor `--yes` counts. `--clients` says which client, not
+    // "overwrite whatever I put there"; `--yes` skips the question rather than
+    // answering it. The first version of this gate accepted "no client named" as
+    // consent, which let `--yes` through — the same class it was written to
+    // close, one flag over.
+    const prompted = requested === undefined && !opts.yes && process.stdin.isTTY === true;
+    const consented = opts.force || prompted;
+    if (chosen === undefined) {
+        process.stdout.write("Nothing written.\n");
+        return 0;
+    }
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    let failed = false;
+    let wrote = false;
+    for (const plan of chosen) {
+        const outcome = opts.remove
+            ? await removeClientEntry(plan, { stamp, force: opts.force })
+            : await writeClientEntry(plan, { stamp, consented });
+        if (outcome.action === "written") {
+            wrote = true;
+            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`);
+        }
+        else {
+            failed = true;
+            process.stderr.write(`Skipped ${outcome.client}: ${outcome.reason}\n`);
+        }
+    }
+    // Only when something actually changed. Telling someone to restart an
+    // application after a run that wrote nothing is advice with no cause.
+    if (wrote && !failed) {
+        process.stdout.write(`\nRestart the client(s) so they pick up the ${opts.remove ? "removal" : "new server"}.\n`);
+    }
+    return failed ? 1 : 0;
+}
+/**
+ * The listing describes state from the point of view of what is about to
+ * happen. Under `--remove`, "already registered correctly" describes the entry
+ * accurately and reads as nonsense under the heading "Removing from clients",
+ * where the same state means "this is the one that will go".
+ */
+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",
+            differs: "has an entry we did not write — left alone unless --force",
+        }[state];
+    }
+    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",
+        differs: "has a DIFFERENT entry",
+    }[state];
+}
+/** An entry's shape without its `env`, which holds live API keys on real machines. */
+function summariseEntry(entry) {
+    if (!entry || typeof entry !== "object")
+        return entry;
+    const { env: _hidden, ...rest } = entry;
+    return rest;
+}
+/**
+ * Ask, when there is someone to ask.
+ *
+ * Returns undefined for "write nothing". An entry that already differs is the
+ * case that most needs a human: on the machine this was written for, the
+ * differing entry was the WORKING one.
+ */
+async function chooseInteractively(plans, opts) {
+    // 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.
+    //
+    // The consent gate added for `--clients` treated "no client named" as
+    // "consented", and `--yes` takes that path — so an acceptance pass measured
+    // `connect --yes` overwriting a hand-edited entry with no prompt and no
+    // --force, exit 0, while the same flags on `--remove` correctly refused.
+    // "Do not ask me" is not the same answer as "yes, replace what I wrote".
+    if (opts.yes)
+        return actionable;
+    if (!process.stdin.isTTY) {
+        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");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`\nApply to ${actionable.length} client(s)? [y/N] `))
+            .trim()
+            .toLowerCase();
+        return answer === "y" || answer === "yes" ? actionable : undefined;
+    }
+    finally {
+        rl.close();
+    }
+}
 async function cmdStatus(configPath, opts) {
     const runtime = await buildRuntime(configPath);
     const render = async () => {
@@ -230,8 +503,67 @@ 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
+                    ? ` from ${path.resolve(configPath)}`
+                    : " (no config file found; shipped defaults with auto-detected harnesses)"),
         },
+        // This one DOES fail, unlike the advisory git check below.
+        //
+        // A client entry naming a path that is not there is not a preference or a
+        // missing optional tool — there is no setup in which it is intended. And
+        // it is invisible from the client side: one that cannot spawn its server
+        // simply has no tools, which looks identical to never having installed
+        // anything. On this maintainer's machine that state survived a repo rename
+        // by months, silently, along with a hook pointing at the same dead
+        // directory.
+        //
+        // Not-configured is NOT a failure: a machine with no client entry gets
+        // "not registered with any client", ok. Only a broken one fails.
+        (() => {
+            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: 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 {
+                name: "mcp-clients",
+                ok: broken.length === 0,
+                detail: broken.length === 0
+                    ? entries.map((e) => `${e.client}: ${e.entry} resolves`).join("; ")
+                    : broken
+                        .map((e) => 
+                    // "references", not "launches ... from": missingPaths
+                    // holds any path the entry names that is not there, and
+                    // that is routinely the `--config` argument rather than
+                    // the launch binary. An acceptance pass found the message
+                    // reaching the right conclusion by the wrong description —
+                    // a missing explicit --config does make the CLI exit 1,
+                    // but it is not where the client launches from.
+                    `${e.client} (${e.file}) references a path that does not exist: ` +
+                        `${e.missingPaths.join(", ")} (entry: ${e.entry}) — that client has been ` +
+                        "getting NO tools from this server, silently. `harness-dispatch connect` " +
+                        "rewrites the entry.")
+                        .join(" | "),
+            };
+        })(),
         // Not required to dispatch — reported, never a hard fail.
         //
         // The `workspace` tool shells out to git for diff/apply, so without it a
@@ -267,6 +599,19 @@ async function cmdDoctor(configPath, opts) {
                 ? runtime.config.configWarnings.join(" | ")
                 : "no unrecognized config entries",
         },
+        {
+            // Saved state that could not be read, which is NOT a config problem and
+            // so never reached this list: `doctor` read `configWarnings` directly
+            // and stayed silent about an unreadable breaker record or usage counters
+            // that are not reaching disk. Two acceptance passes recorded that
+            // silence as an open item; `status` grew a "State problems" heading and
+            // `doctor` did not follow.
+            name: "saved-state",
+            ok: (status.stateWarnings?.length ?? 0) === 0,
+            detail: status.stateWarnings && status.stateWarnings.length > 0
+                ? status.stateWarnings.join(" | ")
+                : "readable",
+        },
         {
             name: "routes",
             ok: status.ready.length > 0,
@@ -297,6 +642,29 @@ 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");
+    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,
@@ -393,18 +761,50 @@ async function cmdAuth(action) {
             return 1;
     }
 }
-async function cmdRouteAlias(prompt, configPath) {
+/**
+ * One dispatch from the command line — the CLI half of the `dispatch` MCP
+ * tool, named to match it (`route` stays as an alias).
+ *
+ * It took flags because it had none and that made it unusable for the one job
+ * it is most needed for. An acceptance pass has to exercise the build IN THE
+ * WORKING TREE; the MCP tool runs in whatever server process is already
+ * connected, which is a different artifact from a different moment. So the CLI
+ * is the honest path there — and it hardcoded taskType "execute" with two
+ * fallbacks, meaning a pass asking for one read-only call on one route could
+ * silently get an execute-profile run on up to three. The first acceptance
+ * pass to attempt a live dispatch wrote its own Node script against dist/
+ * rather than use this, which is the tell.
+ */
+async function cmdDispatch(prompt, configPath, opts) {
     if (!prompt) {
-        process.stderr.write('route: missing prompt. Usage: route "<prompt>"\n');
+        process.stderr.write('dispatch: missing prompt. Usage: dispatch [--service <id>] [--safety <profile>]\n' +
+            '          [--task-type <type>] [--no-fallback] [--json] "<prompt>"\n');
         return 1;
     }
     const runtime = await buildRuntime(configPath);
-    const { result, decision } = await runtime.router.route(prompt, [], process.cwd(), {
-        hints: { taskType: "execute" },
-        maxFallbacks: 2,
-    });
+    const hints = { taskType: opts.taskType ?? "execute" };
+    if (opts.safetyProfile !== undefined)
+        hints.safetyProfile = opts.safetyProfile;
+    // A named service goes through routeTo, which is what "run exactly this
+    // route" means — not route() with a hint, which can still fall elsewhere.
+    const { result, decision } = opts.service
+        ? await runtime.router.routeTo(opts.service, prompt, [], process.cwd(), {
+            ...(opts.safetyProfile !== undefined ? { safetyProfile: opts.safetyProfile } : {}),
+            ...(opts.taskType !== undefined ? { taskType: opts.taskType } : {}),
+        })
+        : await runtime.router.route(prompt, [], process.cwd(), {
+            hints,
+            maxFallbacks: opts.noFallback ? 0 : 2,
+        });
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({ result, routing: decision ?? null }, null, 2)}\n`);
+        return result.success ? 0 : 1;
+    }
     if (decision) {
-        process.stderr.write(`route: ${decision.service} (${decision.reason})\n`);
+        const beat = decision.candidates?.length
+            ? ` [${decision.candidates.map((c) => `${c.route} ${c.score}`).join(", ")}]`
+            : "";
+        process.stderr.write(`dispatch: ${decision.service} (${decision.reason})${beat}\n`);
     }
     process.stdout.write(result.output);
     if (!result.output.endsWith("\n"))
@@ -415,6 +815,24 @@ async function cmdRouteAlias(prompt, configPath) {
     }
     return 0;
 }
+const SAFETY_PROFILES = ["read_only", "workspace_edit", "full_auto"];
+const TASK_TYPES = ["execute", "plan", "review", "local"];
+/**
+ * An enum-valued flag: rejected by name when it is not one of the listed
+ * values, never silently dropped to a default.
+ *
+ * `--safety read_onlyy` dropping to workspace_edit would hand a delegate MORE
+ * access than the caller asked for — the same failure the MCP and HTTP
+ * surfaces were both hardened against, and the reason `hints` is strict there.
+ */
+function enumFlag(value, allowed, flag) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "string" && allowed.includes(value)) {
+        return value;
+    }
+    throw new UsageError(`${flag}: invalid value ${JSON.stringify(value)}. Valid: ${allowed.join(", ")}.`);
+}
 function parsePositiveInt(value, fallback) {
     if (typeof value !== "string")
         return fallback;
@@ -463,6 +881,14 @@ export async function main(argv) {
             yes: { type: "boolean" },
             force: { type: "boolean" },
             http: { type: "string" },
+            service: { type: "string" },
+            safety: { type: "string" },
+            "task-type": { type: "string" },
+            "no-fallback": { type: "boolean" },
+            clients: { type: "string" },
+            "no-clients": { type: "boolean" },
+            remove: { type: "boolean" },
+            dev: { type: "boolean" },
         },
         allowPositionals: true,
         strict: false,
@@ -475,6 +901,8 @@ export async function main(argv) {
     const knownFlags = new Set([
         "help", "version", "config", "json", "live", "allow-paid", "watch", "interval",
         "port", "host", "print", "yes", "force", "http",
+        "service", "safety", "task-type", "no-fallback",
+        "clients", "no-clients", "remove", "dev",
     ]);
     const unknownFlags = Object.keys(values).filter((k) => !knownFlags.has(k));
     if (unknownFlags.length > 0) {
@@ -531,6 +959,16 @@ export async function main(argv) {
                 print: Boolean(values.print),
                 yes: Boolean(values.yes),
                 force: Boolean(values.force),
+                noClients: Boolean(values["no-clients"]),
+                clients: typeof values.clients === "string" ? values.clients : undefined,
+            });
+        case "connect":
+            return cmdConnect(configPath, {
+                clients: typeof values.clients === "string" ? values.clients : undefined,
+                remove: Boolean(values.remove),
+                yes: Boolean(values.yes),
+                force: Boolean(values.force),
+                dev: Boolean(values.dev),
             });
         case "doctor":
             return cmdDoctor(configPath, {
@@ -552,8 +990,21 @@ export async function main(argv) {
             return cmdServe(configPath, serveOpts(values));
         case "auth":
             return cmdAuth(rest[0]);
-        case "route":
-            return cmdRouteAlias(rest.join(" ").trim(), configPath);
+        // `route` kept as an alias: it was the name for two years of history, and
+        // `dispatch` matches the MCP tool that does the same thing. Same pattern
+        // as status/dashboard/list-services above.
+        case "dispatch":
+        case "route": {
+            const safety = enumFlag(values.safety, SAFETY_PROFILES, "--safety");
+            const taskType = enumFlag(values["task-type"], TASK_TYPES, "--task-type");
+            return cmdDispatch(rest.join(" ").trim(), configPath, {
+                ...(typeof values.service === "string" ? { service: values.service } : {}),
+                ...(safety !== undefined ? { safetyProfile: safety } : {}),
+                ...(taskType !== undefined ? { taskType } : {}),
+                noFallback: Boolean(values["no-fallback"]),
+                json: Boolean(values.json),
+            });
+        }
         case "mcp":
             if (values.http !== undefined) {
                 return cmdServe(configPath, serveOpts({ port: values.http, host: values.host }));
@@ -565,11 +1016,58 @@ export async function main(argv) {
             return 1;
     }
 }
-const entrypoint = typeof process !== "undefined" && Array.isArray(process.argv) ? process.argv[1] : "";
-if (entrypoint && (entrypoint.endsWith("bin.ts") || entrypoint.endsWith("bin.js"))) {
+/**
+ * End the process with `code`, letting the event loop drain first.
+ *
+ * `process.exit(code)` tears the loop down mid-flight, and on Windows that
+ * aborts: `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), src\win * async.c` and an exit status of 127, which every shell reads as "command not
+ * found". It fired AFTER a correct answer had been printed, so the work was
+ * done and the report of it was a crash.
+ *
+ * Reproduced 3/3 across three acceptance passes, and confirmed here: two
+ * endpoint routes, the first answering 200 with an unusable body and the
+ * second succeeding. The fallback is what makes it two in-flight HTTP
+ * connections; `--no-fallback` and a refused connection both exited 1 cleanly,
+ * which is why it looked intermittent. Setting `exitCode` instead removes it,
+ * measured on the same probe.
+ *
+ * The force-exit is the safety net `process.exit` was providing: if something
+ * still holds the loop open after a grace window, leave anyway rather than
+ * hanging a CLI. It is `unref`d, so it does not itself keep the process alive
+ * — every command measured here exits in under a second without it firing.
+ */
+const EXIT_DRAIN_GRACE_MS = 3000;
+function finish(code) {
+    process.exitCode = code;
+    const bail = setTimeout(() => {
+        process.exit(code);
+    }, EXIT_DRAIN_GRACE_MS);
+    bail.unref();
+}
+// 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) => {
-        process.exit(code);
+        finish(code);
     })
         .catch((err) => {
         // A CLI user gets one actionable line, not a stack trace. Every Error is