@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/scripts/phase0-exit-gate.mjs

@@ -52,6 +52,8 @@ import { join } from "path";
 import { homedir } from "os";
 import { pathToFileURL } from "url";
 
+import { gatesActive } from "../lib/unattended.mjs";
+
 const FIGMA_URL = /figma\.com\/(design|make|file)\//i;
 
 /** Fields that can carry the user's original request text. */
@@ -106,9 +108,11 @@ export function inputTextOf(state) {
  *
  * @param {object|null} state - parsed agent-state.json, or null when absent
  * @param {string} extraInput - input text supplied on the command line
+ * @param {{env?: Record<string, string|undefined>}} [opts] - the environment; with
+ *   state.autopilot it decides autopilot mode (lib/unattended.mjs, gatesActive)
  * @returns {{ok: boolean, failures: string[], taskType: string|undefined, figmaSeen: boolean}}
  */
-export function evaluate(state, extraInput = "") {
+export function evaluate(state, extraInput = "", { env = process.env } = {}) {
   const failures = [];
 
   if (state === null) {
@@ -188,7 +192,9 @@ export function evaluate(state, extraInput = "") {
         `branch the user chose from one the run picked and announced.`,
     );
   }
-  const isAutopilot = state.autopilot === true;
+  // Autopilot mode is the launcher's MULTI_AGENT_UNATTENDED or the run's own
+  // `autopilot: true` (a terminal /multi-agent:autopilot run), lib/unattended.mjs.
+  const isAutopilot = gatesActive(state, env);
   const AUTOPILOT_ONLY_SOURCES = ["remembered", "default", "derived"];
   if (!isAutopilot && AUTOPILOT_ONLY_SOURCES.includes(branchSource)) {
     failures.push(
@@ -255,8 +261,9 @@ export function evaluate(state, extraInput = "") {
   // whether anyone decided: `false` is both "the user chose a worktree" and
   // "nothing asked and the default stood". Same shape as baseBranchSource, and
   // the same reason - an autopilot run resolves it rather than asking, so
-  // `autopilot` is a legal source there and nowhere else.
-  const WORKSPACE_SOURCES = ["asked", "command", "autopilot"];
+  // `autopilot` is a legal source there and nowhere else. `request` is a
+  // launch request that answered the picker before the run started.
+  const WORKSPACE_SOURCES = ["asked", "command", "autopilot", "request"];
   const workspaceSource =
     typeof state.workspaceSource === "string" ? state.workspaceSource.trim() : "";
   if (!WORKSPACE_SOURCES.includes(workspaceSource)) {
@@ -274,6 +281,17 @@ export function evaluate(state, extraInput = "") {
     );
   }
 
+  // A request is validated before Phase 0 applies it, and local under autopilot
+  // is one of the answers it rejects. The gate holds the outcome to the same
+  // rule, so a state that reached this point some other way still stops here.
+  if (isAutopilot && state.localMode === true) {
+    failures.push(
+      `localMode=true on an autopilot run (workspaceSource="${workspaceSource || "<unset>"}"). ` +
+        `An unattended run always gets a worktree; a launch request asking for local under ` +
+        `autopilot is rejected by launch-request.mjs, never applied.`,
+    );
+  }
+
   // Step 2b's dev-context picker writes siblings[], empty included. The empty array is
   // the record that it ran; absent, a multi-repo task silently became a single-repo one
   // and Phase 4's parity cross-check lost its fourth counterpart source.

package/pipeline/scripts/phone-devices.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * @file phone-devices.mjs  -  enrol, list and revoke the phones allowed to
+ * reach the phone routes of contract-server.mjs, and switch phone launch on or
+ * off.
+ *
+ * Enrolment is local on purpose: there is no HTTP route that adds a device,
+ * so reaching the server is never enough to be let into it. A device is its
+ * Ed25519 public key plus the scopes it may use. The private key stays on the
+ * phone; this file never sees it and refuses a PEM block that holds one.
+ *
+ *   read    GET /v1/phone/runs, GET /v1/phone/runs/{id}
+ *   answer  POST /v1/phone/runs/{id}/answer
+ *   launch  POST /v1/phone/launch, and only while `launch on` is set
+ *
+ * The registry is <autopilot root>/phone/devices.json (0600, directory 0700;
+ * phone-devices.schema.json). An unattended run may not change it: every
+ * subcommand but `list` refuses under MULTI_AGENT_UNATTENDED=1, and the guard
+ * blocks the same subcommands by name (unattended-policy.json).
+ *
+ * Usage:
+ *   node phone-devices.mjs add --name <name> --public-key <base64url | PEM> --scopes read[,answer][,launch]
+ *   node phone-devices.mjs add --name <name> --public-key-file <path.pem> --scopes ...
+ *   node phone-devices.mjs list [--json]
+ *   node phone-devices.mjs revoke <device-id>
+ *   node phone-devices.mjs launch on|off
+ *
+ * Output: `add` prints {id, name, fingerprint, scopes}; `list --json` prints
+ * {launchEnabled, devices[]} without keys.
+ * Exit: 0 done, 1 refused (unknown device, already revoked), 2 usage,
+ * 3 unattended.
+ *
+ * @module pipeline/scripts/phone-devices
+ */
+
+import { readFileSync } from "node:fs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { isUnattended } from "../lib/unattended.mjs";
+import {
+  DEVICE_ID,
+  SCOPES,
+  fingerprint,
+  newDeviceId,
+  parsePublicKey,
+  readRegistry,
+  registryPath,
+  writeRegistry,
+} from "./_phone-auth.mjs";
+
+const NAME = /^[\p{L}\p{N} ._'-]{1,64}$/u;
+const USAGE =
+  "usage: phone-devices.mjs add --name <name> --public-key <key> | --public-key-file <pem> --scopes <read,answer,launch>\n" +
+  "       phone-devices.mjs list [--json] | revoke <device-id> | launch on|off\n";
+
+class Usage extends Error {}
+
+function options(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const value = () => {
+      const v = argv[++i];
+      if (v === undefined) throw new Usage(`${a} needs a value`);
+      return v;
+    };
+    if (a === "--name") out.name = value();
+    else if (a === "--public-key") out.key = value();
+    else if (a === "--public-key-file") out.keyFile = value();
+    else if (a === "--scopes") out.scopes = value();
+    else if (a === "--json") out.json = true;
+    else out.rest = [...(out.rest ?? []), a];
+  }
+  return out;
+}
+
+function registryForWrite() {
+  const reg = readRegistry();
+  if (reg.insecure) {
+    throw new Error(
+      `${registryPath()} is ${reg.insecure === "registry-insecure" ? "writable by other users" : "unreadable"}; fix or remove it first`,
+    );
+  }
+  return reg;
+}
+
+function add(o) {
+  if (!o.name || !NAME.test(o.name))
+    throw new Usage("--name is 1 to 64 letters, digits, spaces or ._'-");
+  if (Boolean(o.key) === Boolean(o.keyFile))
+    throw new Usage("give one of --public-key or --public-key-file");
+  const scopes = String(o.scopes ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (!scopes.length) throw new Usage(`--scopes is one or more of ${SCOPES.join(", ")}`);
+  const unknown = scopes.filter((s) => !SCOPES.includes(s));
+  if (unknown.length)
+    throw new Usage(`unknown scope ${unknown.join(", ")}; known: ${SCOPES.join(", ")}`);
+  let publicKey;
+  try {
+    publicKey = parsePublicKey(o.key ?? readFileSync(o.keyFile, "utf8"));
+  } catch (err) {
+    throw new Usage(`--public-key: ${err.message}`);
+  }
+  const reg = registryForWrite();
+  if (reg.devices.some((d) => d.publicKey === publicKey && !d.revokedAt)) {
+    throw new Usage("that key is already enrolled");
+  }
+  const device = {
+    id: newDeviceId(),
+    name: o.name,
+    publicKey,
+    scopes: SCOPES.filter((s) => scopes.includes(s)),
+    addedAt: new Date().toISOString(),
+    revokedAt: null,
+  };
+  writeRegistry({ ...reg, devices: [...reg.devices, device] });
+  return {
+    id: device.id,
+    name: device.name,
+    fingerprint: fingerprint(publicKey),
+    scopes: device.scopes,
+  };
+}
+
+function list() {
+  const reg = readRegistry();
+  return {
+    launchEnabled: reg.launchEnabled,
+    ...(reg.insecure ? { problem: reg.insecure } : {}),
+    devices: reg.devices.map((d) => ({
+      id: d.id,
+      name: d.name,
+      fingerprint: fingerprint(d.publicKey),
+      scopes: d.scopes,
+      addedAt: d.addedAt,
+      revokedAt: d.revokedAt ?? null,
+    })),
+  };
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  let o;
+  try {
+    o = options(rest);
+  } catch (err) {
+    process.stderr.write(`phone-devices: ${err.message}\n${USAGE}`);
+    return 2;
+  }
+  if (!["add", "list", "revoke", "launch"].includes(cmd)) {
+    process.stderr.write(USAGE);
+    return 2;
+  }
+  if (cmd !== "list" && isUnattended()) {
+    process.stderr.write(
+      "phone-devices: an unattended run may not change which devices reach this machine\n",
+    );
+    return 3;
+  }
+  try {
+    if (cmd === "add") {
+      if (o.rest?.length) throw new Usage(`unknown argument ${o.rest[0]}`);
+      process.stdout.write(JSON.stringify(add(o)) + "\n");
+      return 0;
+    }
+    if (cmd === "list") {
+      const out = list();
+      if (o.json) {
+        process.stdout.write(JSON.stringify(out) + "\n");
+        return 0;
+      }
+      const lines = [`launch: ${out.launchEnabled ? "on" : "off"}`];
+      if (out.problem) lines.push(`problem: ${out.problem}`);
+      for (const d of out.devices) {
+        lines.push(
+          `${d.id}  ${d.fingerprint}  ${d.scopes.join(",").padEnd(18)}  ${d.revokedAt ? `revoked ${d.revokedAt}` : "active"}  ${d.name}`,
+        );
+      }
+      process.stdout.write(lines.join("\n") + "\n");
+      return 0;
+    }
+    if (cmd === "revoke") {
+      const id = o.rest?.[0];
+      if (!id || o.rest.length !== 1 || !DEVICE_ID.test(id))
+        throw new Usage("revoke takes one device id");
+      const reg = registryForWrite();
+      const d = reg.devices.find((x) => x.id === id);
+      if (!d) {
+        process.stderr.write(`phone-devices: no device ${id}\n`);
+        return 1;
+      }
+      if (d.revokedAt) {
+        process.stderr.write(`phone-devices: ${id} was revoked at ${d.revokedAt}\n`);
+        return 1;
+      }
+      d.revokedAt = new Date().toISOString();
+      writeRegistry(reg);
+      process.stdout.write(JSON.stringify({ id, revokedAt: d.revokedAt }) + "\n");
+      return 0;
+    }
+    const v = o.rest?.[0];
+    if (o.rest?.length !== 1 || (v !== "on" && v !== "off"))
+      throw new Usage("launch takes on or off");
+    const reg = registryForWrite();
+    writeRegistry({ ...reg, launchEnabled: v === "on" });
+    process.stdout.write(JSON.stringify({ launchEnabled: v === "on" }) + "\n");
+    return 0;
+  } catch (err) {
+    if (err instanceof Usage) {
+      process.stderr.write(`phone-devices: ${err.message}\n${USAGE}`);
+      return 2;
+    }
+    process.stderr.write(`phone-devices: ${err.message}\n`);
+    return 1;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("phone-devices", () => {
+    process.exitCode = main(process.argv.slice(2));
+  });
+}

package/pipeline/scripts/plan-coverage-gate.mjs

@@ -23,15 +23,40 @@
 // `in_progress` is the gap this exists to catch: not "we decided not to do it"
 // but "nobody noticed it was still open".
 //
+// With no plan todos (prefs.global.planTodos off) there is no step list to
+// audit. An attended run reports that as not-applicable.
+//
+// While the quality gates are active (lib/unattended.mjs, gatesActive) Phase 1
+// always writes plan todos, and a run with no todos falls back to the analysis
+// Section 14 `Add new` rows, the one promise every analysed plan carries. With
+// neither, a run that had a Plan phase (`state.analysis.docStatus` recorded, or
+// `state.phases["1"]` entered) is a gap: it planned work and left nothing to
+// check it against. Only a run with no Plan phase, the pipeline tail, is
+// not-applicable. Those verdicts are appended to state.gates[] as
+// `plan-coverage`.
+//
 // Usage:
 //   plan-coverage-gate.mjs --state <agent-state.json> [--analysis <doc.md>] [--root <dir>] [--json]
 //   plan-coverage-gate.mjs --todos <plan-todos.json> [--analysis <doc.md>] [--root <dir>] [--json]
 //
-// Exit codes: 0 clean, 1 coverage gap, 2 usage / parse error.
+// --analysis-from-state adds one --analysis per entry of the state's
+// analysis.docPath[] (one per platform), and --json-out <file> writes the --json
+// result to that file instead of stdout. Together they make the Phase 4 step
+// one command, with no shell array built from jq output.
+//
+// Exit codes, gates active: 0 clean, 1 coverage gap (a zero-step plan and a
+// planned run with no coverage source included), 2 not-applicable (no Plan
+// phase), 3 usage or unreadable input.
+// Attended: 0 clean, 1 gap, 2 everything else - not-applicable (verdict
+// `not-applicable` in --json), a zero-step plan (verdict `unusable`), usage or
+// unreadable input (no verdict). Phase 4 reads only exit 2 with verdict
+// `not-applicable` as not-applicable.
 
-import { readFileSync, existsSync, writeFileSync } from "node:fs";
-import { join, isAbsolute } from "node:path";
-import { pathToFileURL } from "node:url";
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, isAbsolute } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { gateContext, recordQuietly } from "./gate-ledger.mjs";
 
 export function auditTodos(todos) {
   const gaps = [];
@@ -90,9 +115,48 @@ function readJson(path) {
   return JSON.parse(readFileSync(path, "utf8"));
 }
 
-const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isMain) {
-  const args = process.argv.slice(2);
+/**
+ * Promised files across every analysis document.
+ * @returns {{rows: string[], missing: string[], verdict: string}}
+ */
+function auditFiles(analysisPaths, root) {
+  const allRows = [];
+  const docsWithoutSection = [];
+  for (const docPath of analysisPaths) {
+    const rows = filesToAdd(readFileSync(docPath, "utf8"));
+    if (rows === null) docsWithoutSection.push(docPath);
+    else allRows.push(...rows);
+  }
+  const rows = [...new Set(allRows)];
+  const missing = rows.filter((p) => !existsSync(isAbsolute(p) ? p : join(root, p)));
+  const docNote = docsWithoutSection.length
+    ? `; ${docsWithoutSection.length} doc(s) carried no Section 14`
+    : "";
+  const verdict = rows.length
+    ? `${rows.length - missing.length}/${rows.length} promised files present across ${analysisPaths.length} doc(s)${docNote}`
+    : `no Section 14 rows in ${analysisPaths.length} doc(s)${docNote}`;
+  return { rows, missing, verdict };
+}
+
+/**
+ * Did this run have a Plan phase? Phase 1 Step 4 always records
+ * `analysis.docStatus`; the phase tracker records `phases["1"]`.
+ *
+ * @param {object|null} state
+ * @returns {boolean}
+ */
+export function planPhaseRan(state) {
+  if (!state || typeof state !== "object" || state.mode === "analysis") return false;
+  const p1 = state.phases?.["1"];
+  if (p1 && typeof p1 === "object" && p1.status && !["pending", "skipped"].includes(p1.status)) {
+    return true;
+  }
+  return typeof state.analysis?.docStatus === "string";
+}
+
+const LEDGER = { clean: "pass", gap: "fail", unusable: "fail", "not-applicable": "not-applicable" };
+
+async function main(args) {
   const flag = (name) => {
     const i = args.indexOf(name);
     return i === -1 ? undefined : args[i + 1];
@@ -117,86 +181,150 @@ if (isMain) {
         "Fails when a plan step never reached a terminal status, when a skip or",
         "failure carries no reason, or when an analysis Section 14 `Add new` file",
         "is missing from the tree. Run before Phase 4 commit.",
+        "Exit: 0 clean, 1 gap, 2 not-applicable, 3 usage or unreadable input.",
         "",
       ].join("\n"),
     );
-    process.exit(args.includes("--help") ? 0 : 2);
+    return args.includes("--help") ? 0 : 2;
   }
 
   const statePath = flag("--state");
   const todosPath = flag("--todos");
   const analysisPaths = flagAll("--analysis");
+  if (statePath && args.includes("--analysis-from-state")) {
+    try {
+      const docs = readJson(statePath)?.analysis?.docPath;
+      if (Array.isArray(docs)) {
+        analysisPaths.push(...docs.filter((d) => typeof d === "string" && d !== ""));
+      }
+    } catch {
+      /* an unreadable state is reported below, where the plan is read */
+    }
+  }
   const root = flag("--root") ?? process.cwd();
-  const asJson = args.includes("--json");
+  const jsonOut = flag("--json-out");
+  const asJson = args.includes("--json") || jsonOut !== undefined;
+  const writeJson = (obj) => {
+    const text = `${JSON.stringify(obj, null, 2)}\n`;
+    if (jsonOut === undefined) {
+      writeFileSync(1, text);
+      return;
+    }
+    mkdirSync(dirname(jsonOut), { recursive: true });
+    writeFileSync(jsonOut, text);
+  };
+  // The quality gates run for an unattended run and for a run in autopilot
+  // mode (lib/unattended.mjs, gatesActive); neither has a person to ask.
+  const gatesOn = gateContext({ statePath: statePath ?? null, repo: root }).active;
+  // Attended runs keep the base exit contract: every non-verdict is exit 2.
+  const UNREADABLE = gatesOn ? 3 : 2;
+  const ZERO_STEPS = gatesOn ? 1 : 2;
+
+  const finish = async (code, result, detail = {}) => {
+    if (gatesOn) {
+      await recordQuietly(
+        "plan-coverage",
+        LEDGER[result.verdict] ?? "fail",
+        { verdict: result.verdict, ...detail },
+        { repo: root, statePath: statePath ?? null },
+      );
+    }
+    return code;
+  };
 
   if (!statePath && !todosPath) {
     process.stderr.write("plan-coverage-gate: pass --state or --todos\n");
-    process.exit(2);
+    return UNREADABLE;
   }
 
   let todos;
+  let state = null;
   try {
     if (todosPath) {
       const parsed = readJson(todosPath);
       todos = parsed?.todos ?? parsed;
     } else {
-      const state = readJson(statePath);
+      state = readJson(statePath);
       todos = state?.plan?.todos ?? state?.plan?.todoList?.todos ?? null;
     }
   } catch (e) {
     process.stderr.write(`plan-coverage-gate: cannot read the plan: ${e.message}\n`);
-    process.exit(2);
+    return finish(UNREADABLE, { verdict: "unusable" }, { reason: `unreadable plan: ${e.message}` });
   }
 
-  // No plan at all is not a pass, and neither is an empty one: a Phase 2 that
-  // produced no steps, or a state whose todos got cleared, would otherwise read
-  // as "0/0 accounted for" and let the commit through. A mode with no Phase 2
-  // (analysis) is expected to skip this gate explicitly rather than let it
-  // report clean.
-  if (!Array.isArray(todos) || todos.length === 0) {
-    const msg = Array.isArray(todos)
-      ? "the plan has zero steps - that is an unusable plan, not a clean one; skip this gate explicitly for modes with no Phase 2"
-      : "no plan todos found - if this mode has no Phase 2, skip this gate explicitly";
-    // fd 1 synchronously, then exit. This sits in `if (isMain)` at module scope,
-    // not in a function, so there is nothing to return from - and a
-    // process.stdout.write followed by process.exit() loses the verdict when
-    // stdout is a pipe.
-    if (asJson)
-      writeFileSync(1, `${JSON.stringify({ verdict: "unusable", reason: msg }, null, 2)}\n`);
-    else process.stderr.write(`plan-coverage-gate: ${msg}\n`);
-    process.exit(2);
+  let files = null;
+  if (analysisPaths.length) {
+    try {
+      files = auditFiles(analysisPaths, root);
+    } catch (e) {
+      process.stderr.write(`plan-coverage-gate: cannot read the analysis doc: ${e.message}\n`);
+      return finish(
+        UNREADABLE,
+        { verdict: "unusable" },
+        { reason: `unreadable analysis: ${e.message}` },
+      );
+    }
   }
 
-  const { gaps, accounted } = auditTodos(todos);
-
-  let missingFiles = [];
-  let filesVerdict;
-  if (analysisPaths.length) {
-    const allRows = [];
-    const docsWithoutSection = [];
-    for (const docPath of analysisPaths) {
-      let rows = null;
-      try {
-        rows = filesToAdd(readFileSync(docPath, "utf8"));
-      } catch (e) {
-        process.stderr.write(`plan-coverage-gate: cannot read the analysis doc: ${e.message}\n`);
-        process.exit(2);
-      }
-      if (rows === null) docsWithoutSection.push(docPath);
-      else allRows.push(...rows);
+  // No step list. Attended: nothing to audit. Unattended: the promised files
+  // are the coverage source when there are any.
+  if (!Array.isArray(todos)) {
+    if (gatesOn && files && files.rows.length) {
+      const failed = files.missing.length > 0;
+      const result = {
+        verdict: failed ? "gap" : "clean",
+        source: "analysis-section-14",
+        todos: { total: 0, accounted: 0, gaps: [] },
+        filesToAdd: { verdict: files.verdict, missing: files.missing },
+      };
+      if (asJson) writeJson(result);
+      else if (failed) {
+        writeFileSync(
+          2,
+          `${[
+            `plan coverage (from analysis Section 14, no plan todos): ${files.missing.length} missing file(s)`,
+            ...files.missing.map((f) => `  missing file promised by analysis Section 14: ${f}`),
+          ].join("\n")}\n`,
+        );
+      } else writeFileSync(1, `plan coverage (from analysis Section 14): ${files.verdict}\n`);
+      return finish(failed ? 1 : 0, result, {
+        source: result.source,
+        missing: files.missing.length,
+      });
     }
-    const unique = [...new Set(allRows)];
-    missingFiles = unique.filter((p) => !existsSync(isAbsolute(p) ? p : join(root, p)));
-    const docNote = docsWithoutSection.length
-      ? `; ${docsWithoutSection.length} doc(s) carried no Section 14`
-      : "";
-    filesVerdict = unique.length
-      ? `${unique.length - missingFiles.length}/${unique.length} promised files present across ${analysisPaths.length} doc(s)${docNote}`
-      : `no Section 14 rows in ${analysisPaths.length} doc(s)${docNote}`;
-  } else {
-    filesVerdict = "skipped (no --analysis given)";
+    if (gatesOn && planPhaseRan(state)) {
+      const reason =
+        "the run had a Plan phase and left no plan todos and no analysis Section 14 `Add new` row to check it against";
+      const result = { verdict: "gap", reason, todos: { total: 0, accounted: 0, gaps: [] } };
+      if (asJson) writeJson(result);
+      else process.stderr.write(`plan-coverage-gate: ${reason}\n`);
+      return finish(1, result, { reason });
+    }
+    const reason = gatesOn
+      ? "no Plan phase in this run, so no plan todos and no analysis Section 14 row to cover"
+      : "no plan todos found - this mode has no step list to audit";
+    const result = { verdict: "not-applicable", reason };
+    // fd 1 synchronously: process.exit() follows, and a pipe would keep only
+    // what fit in its buffer.
+    if (asJson) writeJson(result);
+    else process.stderr.write(`plan-coverage-gate: not-applicable: ${reason}\n`);
+    return finish(2, result, { reason });
   }
 
+  // An empty step list is not a clean one: a Phase 2 that produced no steps, or
+  // a state whose todos got cleared, would otherwise read as "0/0 accounted for"
+  // and let the commit through.
+  if (todos.length === 0) {
+    const reason = "the plan has zero steps - that is an unusable plan, not a clean one";
+    if (asJson) writeJson({ verdict: "unusable", reason });
+    else process.stderr.write(`plan-coverage-gate: ${reason}\n`);
+    return finish(ZERO_STEPS, { verdict: "unusable" }, { reason });
+  }
+
+  const { gaps, accounted } = auditTodos(todos);
+  const missingFiles = files ? files.missing : [];
+  const filesVerdict = files ? files.verdict : "skipped (no --analysis given)";
+
   const failed = gaps.length > 0 || missingFiles.length > 0;
   const result = {
     verdict: failed ? "gap" : "clean",
@@ -204,21 +332,27 @@ if (isMain) {
     filesToAdd: { verdict: filesVerdict, missing: missingFiles },
   };
 
+  // Same rule as above: every verdict goes to its fd synchronously.
   if (asJson) {
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    writeJson(result);
   } else if (failed) {
-    process.stderr.write(
-      `plan coverage: ${gaps.length} unaccounted step(s), ${missingFiles.length} missing file(s)\n`,
-    );
-    for (const g of gaps) process.stderr.write(`  ${g.id} [${g.status}] ${g.task} - ${g.why}\n`);
-    for (const f of missingFiles)
-      process.stderr.write(`  missing file promised by analysis Section 14: ${f}\n`);
-    process.stderr.write(`  files-to-add: ${filesVerdict}\n`);
+    const lines = [
+      `plan coverage: ${gaps.length} unaccounted step(s), ${missingFiles.length} missing file(s)`,
+      ...gaps.map((g) => `  ${g.id} [${g.status}] ${g.task} - ${g.why}`),
+      ...missingFiles.map((f) => `  missing file promised by analysis Section 14: ${f}`),
+      `  files-to-add: ${filesVerdict}`,
+    ];
+    writeFileSync(2, `${lines.join("\n")}\n`);
   } else {
     // spec-kit's rule: a clean pass says one line and writes nothing.
-    process.stdout.write(
+    writeFileSync(
+      1,
       `plan coverage: ${accounted.length}/${todos.length} steps accounted for; files-to-add: ${filesVerdict}\n`,
     );
   }
-  process.exit(failed ? 1 : 0);
+  return finish(failed ? 1 : 0, result, { gaps: gaps.length, missing: missingFiles.length });
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
 }