harness-dispatch 0.7.9 → 0.8.0

package/dist/bin.js

@@ -5,12 +5,14 @@
 import { existsSync, mkdirSync, 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 { inspectClientEntries } from "./mcp-clients.js";
 import { buildDispatchers } from "./mcp/dispatcher-factory.js";
 import { startMcpServer } from "./mcp/server.js";
 import { initObservability } from "./observability/index.js";
@@ -21,6 +23,7 @@ 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";
 async function buildRuntime(configPath) {
     const config = await loadConfig(configPath);
@@ -39,6 +42,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 +51,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 +64,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.",
         "",
@@ -125,22 +139,224 @@ async function cmdConfigure(configPath, explicitConfigPath, opts) {
             "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.
+    await fs.writeFile(target, 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" +
+    // 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");
+    printMcpSnippet({ command: "harness-dispatch", args: ["--config", absoluteTarget] });
+    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 ?? "config.yaml");
+    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} (backup: ${outcome.backupPath})\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",
+            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",
+        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) {
+    const actionable = plans.filter((p) => 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("\nNot a terminal, so nothing was written. Re-run with --clients " +
+            `${actionable.map((p) => p.id).join(",")} (or --yes) to apply.\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 () => {
@@ -232,6 +448,50 @@ async function cmdDoctor(configPath, opts) {
             ok: Object.keys(runtime.config.services).length > 0,
             detail: `${Object.keys(runtime.config.services).length} configured route(s)`,
         },
+        // 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) {
+                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",
+                };
+            }
+            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 +527,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,
@@ -393,18 +666,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 +720,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 +786,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 +806,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 +864,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 +895,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 +921,39 @@ export async function main(argv) {
             return 1;
     }
 }
+/**
+ * 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();
+}
 const entrypoint = typeof process !== "undefined" && Array.isArray(process.argv) ? process.argv[1] : "";
 if (entrypoint && (entrypoint.endsWith("bin.ts") || entrypoint.endsWith("bin.js"))) {
     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