faberun 0.19.2 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {

package/src/campaign/watch.mjs

@@ -0,0 +1,197 @@
+/**
+ * `campaign watch --wake`: the loop that turns a campaign's own records into
+ * the lines an operator is woken with, and the single-watcher lock that keeps
+ * two of them from doubling every wake.
+ *
+ * Separate from `cli/campaign.mjs` because that file owns argv, dispatch and
+ * usage for the campaign verb, and this is neither: it is a long-running
+ * supervisor with a poll interval, an idle policy, a durable dedupe through
+ * the inbox, and a lock with its own staleness rule. `cli/campaign.mjs` keeps
+ * the thin `watch` operation that reads the flags and calls in here.
+ */
+import { closeSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { lockStale, pidAlive, processStartToken, readLock } from "../run/lock.mjs";
+import { readCampaign } from "./record.mjs";
+import { notifyQueueFor } from "../engine/notify-queue.mjs";
+import { appendInbox, readInbox, wakeCapabilityNotice } from "../notify/index.mjs";
+import { errorCode, readJsonTolerant } from "../util.mjs";
+
+/** How often the watcher re-reads the campaign when the operator named no interval. */
+export const DEFAULT_WAKE_POLL_MS = 30_000;
+
+/** How long without a material event before the watcher reports the campaign idle. */
+const WAKE_IDLE_AFTER_MS = 20 * 60_000;
+
+const TERMINAL_NODE_STATUSES = new Set(["done", "no-op", "blocked", "failed", "exhausted", "stalled", "canceled", "cancelled"]);
+const ATTENTION_NODE_STATUSES = new Set(["failed", "exhausted", "stalled", "canceled", "cancelled"]);
+
+/**
+ * The watcher loop. Each line is announced through `notify`, which by default
+ * records it in `<runs-dir>/inbox.jsonl` and delivers it to the campaign's
+ * `notify.jsonl`; the inbox is both the durable record and the dedupe, so a
+ * line already recorded is never re-sent. The injectable seams exist so a
+ * test can drive the loop deterministically.
+ *
+ * @param {string} campaignPath
+ * @param {string} runsDir
+ * @param {{pollMs?: number, once?: boolean, now?: () => number, sleep?: (ms: number) => Promise<void>, emit?: (line: string) => void, notify?: (event: {type: string, campaignId: string, dedupeKey: string, summary: string, runId?: string|null, nodeId?: string|null, status?: string|null, errorCode?: string|null}) => Promise<void>|void, lock?: {release: () => void}}} [options]
+ * @returns {Promise<void>}
+ */
+export async function watchCampaignWake(campaignPath, runsDir, options = {}) {
+  const pollMs = options.pollMs ?? DEFAULT_WAKE_POLL_MS;
+  const now = options.now ?? (() => Date.now());
+  const sleep = options.sleep ?? ((ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms)));
+  const emit = options.emit ?? ((line) => process.stdout.write(`${line}\n`));
+  const notify = options.notify ?? ((event) => notifyQueueFor(campaignPath).enqueue({
+    type: "attention",
+    campaignId: event.campaignId,
+    dedupeKey: event.dedupeKey,
+    summary: event.summary,
+    runId: event.runId ?? null,
+    nodeId: event.nodeId ?? null,
+    status: event.status ?? null,
+    errorCode: event.errorCode ?? null,
+  }));
+  const seen = new Set(readInbox(runsDir).map((entry) => entry.dedupeKey));
+  const lock = options.lock ?? acquireWatchLock(campaignPath);
+  emit(wakeCapabilityNotice());
+  /** @type {Map<string, string>} */
+  const runSignatures = new Map();
+  let lastActiveAt = now();
+  let first = true;
+  try {
+    for (;;) {
+      const campaign = readCampaign(campaignPath);
+      if (campaign.status !== "active") {
+        emit(`campaign-watch: ${campaign.id} is ${campaign.status}; stopping`);
+        return;
+      }
+      /**
+       * Persist first, deliver second: the inbox entry is the durable dedupe,
+       * so a restart or a second watcher skips a line already recorded even
+       * when delivery is injected.
+       *
+       * @param {string} dedupeKey @param {string} summary @param {{runId?: string|null, nodeId?: string|null, status?: string|null, errorCode?: string|null}} [extra]
+       */
+      const announce = async (dedupeKey, summary, extra = {}) => {
+        if (seen.has(dedupeKey)) return;
+        seen.add(dedupeKey);
+        const appended = appendInbox(runsDir, { type: "attention", campaignId: campaign.id, dedupeKey, summary, ...extra });
+        if (!appended.appended) return;
+        emit(summary);
+        await notify({ type: "attention", campaignId: campaign.id, dedupeKey, summary, ...extra });
+      };
+      let anyActive = false;
+      for (const runId of campaign.linkedRunIds) {
+        const status = /** @type {Record<string, any>|null} */ (readJsonTolerant(join(runsDir, runId, "status.json")));
+        if (!status || !Array.isArray(status.nodes)) continue;
+        const terminal = status.nodes.every((/** @type {any} */ node) => TERMINAL_NODE_STATUSES.has(String(node.status)));
+        const signature = status.nodes.map((/** @type {any} */ node) => `${node.id}:${node.status}:${node.errorCode ?? ""}`).join("|");
+        const previous = runSignatures.get(runId);
+        runSignatures.set(runId, signature);
+        if (!terminal) {
+          anyActive = true;
+          const runLock = readLock(join(runsDir, runId));
+          const stale = !runLock || /** @type {{invalid?: true}} */ (runLock).invalid || lockStale(runLock);
+          if (stale && !first) {
+            await announce(`stale:${runId}`, `campaign-watch: ${runId} has non-terminal nodes but no live controller; resume it`, { runId });
+          }
+        }
+        if (!first && previous !== signature) {
+          for (const node of status.nodes) {
+            const attention = ATTENTION_NODE_STATUSES.has(String(node.status))
+              || (node.status === "blocked" && !(Array.isArray(node.blockedBy) && node.blockedBy.length > 0));
+            if (attention) {
+              const key = `node:${runId}:${node.id}:${node.status}:${node.errorCode ?? ""}`;
+              await announce(
+                key,
+                `campaign-watch: ${runId} node ${node.id} ${node.status}${node.errorCode ? ` [${node.errorCode}]` : ""}${node.note ? ` ${node.note}` : ""}`,
+                { runId, nodeId: String(node.id), status: String(node.status), errorCode: node.errorCode ?? null },
+              );
+            }
+          }
+        }
+        if (terminal) {
+          await announce(`terminal:${runId}`, `campaign-watch: ${runId} terminal · ${status.summary ?? ""}`, { runId });
+        }
+      }
+      const nowMs = now();
+      if (anyActive) lastActiveAt = nowMs;
+      else if (!first && nowMs - lastActiveAt >= WAKE_IDLE_AFTER_MS) {
+        const key = `idle:${Math.floor((nowMs - lastActiveAt) / WAKE_IDLE_AFTER_MS)}`;
+        await announce(key, `campaign-watch: ${campaign.id} active but no run has been active for ${Math.round((nowMs - lastActiveAt) / 60_000)} min; dispatch the next step`);
+      }
+      first = false;
+      if (options.once === true) return;
+      await sleep(pollMs);
+    }
+  } finally {
+    lock.release();
+  }
+}
+
+const WATCH_LOCK_FILE = "watch.lock";
+
+/**
+ * A durable campaign-watch lock, one watcher per campaign across processes.
+ * A live holder is never taken over; a dead or recycled pid's lock is stale
+ * and is replaced, so a restart after a crash is not blocked. The same
+ * liveness rule as the controller lock: a pid is dead only when the probe
+ * proves it.
+ *
+ * @param {string} campaignPath
+ * @returns {{pid: number, processStartToken: string|null, startedAt: string, release: () => void}}
+ */
+export function acquireWatchLock(campaignPath) {
+  const path = join(campaignPath, WATCH_LOCK_FILE);
+  /** @type {{pid?: number, processStartToken?: string|null, startedAt?: string}} */
+  let occupant = {};
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const record = { pid: process.pid, processStartToken: processStartToken(process.pid), startedAt: new Date().toISOString() };
+    try {
+      const fd = openSync(path, "wx", 0o600);
+      try {
+        writeSync(fd, JSON.stringify(record));
+      } finally {
+        closeSync(fd);
+      }
+      return {
+        ...record,
+        release() {
+          try {
+            unlinkSync(path);
+          } catch (error) {
+            if (errorCode(error) !== "ENOENT") throw error;
+          }
+        },
+      };
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") throw error;
+    }
+    try {
+      occupant = /** @type {{pid?: number, processStartToken?: string|null}} */ (JSON.parse(readFileSync(path, "utf8")));
+    } catch {
+      occupant = {};
+    }
+    if (!watchLockStale(occupant)) {
+      throw new Error(`campaign watch is already running (pid ${occupant.pid})`);
+    }
+    try {
+      unlinkSync(path);
+    } catch (error) {
+      if (errorCode(error) !== "ENOENT") throw error;
+    }
+  }
+  throw new Error("campaign watch lock contention did not settle");
+}
+
+/**
+ * @param {{pid?: number, processStartToken?: string|null}} occupant
+ * @returns {boolean}
+ */
+function watchLockStale(occupant) {
+  if (typeof occupant.pid !== "number") return true;
+  if (!pidAlive(occupant.pid)) return true;
+  return Boolean(occupant.processStartToken) && processStartToken(occupant.pid) !== occupant.processStartToken;
+}

package/src/cli/campaign.mjs

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { closeSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { parseArgs as parseFlags } from "node:util";
 import {
@@ -11,25 +11,19 @@ import {
   resolveCampaign,
 } from "../campaign/index.mjs";
 import { addContract, replaceContract } from "./campaign-contract.mjs";
-import { lockStale, pidAlive, processStartToken, readLock } from "../run/lock.mjs";
 import { runsRoot } from "../run/paths.mjs";
 import { syncAgentSignal } from "../repo/signal.mjs";
 import { acknowledgeJournalEvent, appendJournal, appendSeatAllowanceEvent, readJournal, watchJournal } from "../campaign/journal.mjs";
 import { driveCampaignChain } from "../campaign/chain.mjs";
 import { unparkCampaign } from "../campaign/unpark.mjs";
 import { readCampaign } from "../campaign/record.mjs";
-import { notifyQueueFor } from "../engine/notify-queue.mjs";
-import { appendInbox, readInbox, wakeCapabilityNotice } from "../notify/index.mjs";
+import { DEFAULT_WAKE_POLL_MS, watchCampaignWake } from "../campaign/watch.mjs";
 import { allowanceEventFields, sampleAllowance } from "../seat/allowance.mjs";
 import { detectOperatorHarness } from "../seat/harnesses.mjs";
 import { detachArgv, detachSelf, waitForBootstrap } from "./launch.mjs";
-import { errorCode, readJsonTolerant } from "../util.mjs";
+import { readJsonTolerant } from "../util.mjs";
 
 const SYNC_OUTPUT_MAX_BYTES = 8000;
-const DEFAULT_WAKE_POLL_MS = 30_000;
-const WAKE_IDLE_AFTER_MS = 20 * 60_000;
-const TERMINAL_NODE_STATUSES = new Set(["done", "no-op", "blocked", "failed", "exhausted", "stalled", "canceled", "cancelled"]);
-const ATTENTION_NODE_STATUSES = new Set(["failed", "exhausted", "stalled", "canceled", "cancelled"]);
 
 const NOTE_KINDS = new Set([
   "intent",
@@ -159,177 +153,6 @@ async function watch(campaignId, values) {
   await watchCampaignWake(path, runsDir, { pollMs, once: values.once === true });
 }
 
-/**
- * The watcher loop. Each line is announced through `notify`, which by default
- * records it in `<runs-dir>/inbox.jsonl` and delivers it to the campaign's
- * `notify.jsonl`; the inbox is both the durable record and the dedupe, so a
- * line already recorded is never re-sent. The injectable seams exist so a
- * test can drive the loop deterministically.
- *
- * @param {string} campaignPath
- * @param {string} runsDir
- * @param {{pollMs?: number, once?: boolean, now?: () => number, sleep?: (ms: number) => Promise<void>, emit?: (line: string) => void, notify?: (event: {type: string, campaignId: string, dedupeKey: string, summary: string, runId?: string|null, nodeId?: string|null, status?: string|null, errorCode?: string|null}) => Promise<void>|void, lock?: {release: () => void}}} [options]
- * @returns {Promise<void>}
- */
-export async function watchCampaignWake(campaignPath, runsDir, options = {}) {
-  const pollMs = options.pollMs ?? DEFAULT_WAKE_POLL_MS;
-  const now = options.now ?? (() => Date.now());
-  const sleep = options.sleep ?? ((ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms)));
-  const emit = options.emit ?? ((line) => process.stdout.write(`${line}\n`));
-  const notify = options.notify ?? ((event) => notifyQueueFor(campaignPath).enqueue({
-    type: "attention",
-    campaignId: event.campaignId,
-    dedupeKey: event.dedupeKey,
-    summary: event.summary,
-    runId: event.runId ?? null,
-    nodeId: event.nodeId ?? null,
-    status: event.status ?? null,
-    errorCode: event.errorCode ?? null,
-  }));
-  const seen = new Set(readInbox(runsDir).map((entry) => entry.dedupeKey));
-  const lock = options.lock ?? acquireWatchLock(campaignPath);
-  emit(wakeCapabilityNotice());
-  /** @type {Map<string, string>} */
-  const runSignatures = new Map();
-  let lastActiveAt = now();
-  let first = true;
-  try {
-    for (;;) {
-      const campaign = readCampaign(campaignPath);
-      if (campaign.status !== "active") {
-        emit(`campaign-watch: ${campaign.id} is ${campaign.status}; stopping`);
-        return;
-      }
-      /**
-       * Persist first, deliver second: the inbox entry is the durable dedupe,
-       * so a restart or a second watcher skips a line already recorded even
-       * when delivery is injected.
-       *
-       * @param {string} dedupeKey @param {string} summary @param {{runId?: string|null, nodeId?: string|null, status?: string|null, errorCode?: string|null}} [extra]
-       */
-      const announce = async (dedupeKey, summary, extra = {}) => {
-        if (seen.has(dedupeKey)) return;
-        seen.add(dedupeKey);
-        const appended = appendInbox(runsDir, { type: "attention", campaignId: campaign.id, dedupeKey, summary, ...extra });
-        if (!appended.appended) return;
-        emit(summary);
-        await notify({ type: "attention", campaignId: campaign.id, dedupeKey, summary, ...extra });
-      };
-      let anyActive = false;
-      for (const runId of campaign.linkedRunIds) {
-        const status = /** @type {Record<string, any>|null} */ (readJsonTolerant(join(runsDir, runId, "status.json")));
-        if (!status || !Array.isArray(status.nodes)) continue;
-        const terminal = status.nodes.every((/** @type {any} */ node) => TERMINAL_NODE_STATUSES.has(String(node.status)));
-        const signature = status.nodes.map((/** @type {any} */ node) => `${node.id}:${node.status}:${node.errorCode ?? ""}`).join("|");
-        const previous = runSignatures.get(runId);
-        runSignatures.set(runId, signature);
-        if (!terminal) {
-          anyActive = true;
-          const runLock = readLock(join(runsDir, runId));
-          const stale = !runLock || /** @type {{invalid?: true}} */ (runLock).invalid || lockStale(runLock);
-          if (stale && !first) {
-            await announce(`stale:${runId}`, `campaign-watch: ${runId} has non-terminal nodes but no live controller; resume it`, { runId });
-          }
-        }
-        if (!first && previous !== signature) {
-          for (const node of status.nodes) {
-            const attention = ATTENTION_NODE_STATUSES.has(String(node.status))
-              || (node.status === "blocked" && !(Array.isArray(node.blockedBy) && node.blockedBy.length > 0));
-            if (attention) {
-              const key = `node:${runId}:${node.id}:${node.status}:${node.errorCode ?? ""}`;
-              await announce(
-                key,
-                `campaign-watch: ${runId} node ${node.id} ${node.status}${node.errorCode ? ` [${node.errorCode}]` : ""}${node.note ? ` ${node.note}` : ""}`,
-                { runId, nodeId: String(node.id), status: String(node.status), errorCode: node.errorCode ?? null },
-              );
-            }
-          }
-        }
-        if (terminal) {
-          await announce(`terminal:${runId}`, `campaign-watch: ${runId} terminal · ${status.summary ?? ""}`, { runId });
-        }
-      }
-      const nowMs = now();
-      if (anyActive) lastActiveAt = nowMs;
-      else if (!first && nowMs - lastActiveAt >= WAKE_IDLE_AFTER_MS) {
-        const key = `idle:${Math.floor((nowMs - lastActiveAt) / WAKE_IDLE_AFTER_MS)}`;
-        await announce(key, `campaign-watch: ${campaign.id} active but no run has been active for ${Math.round((nowMs - lastActiveAt) / 60_000)} min; dispatch the next step`);
-      }
-      first = false;
-      if (options.once === true) return;
-      await sleep(pollMs);
-    }
-  } finally {
-    lock.release();
-  }
-}
-
-const WATCH_LOCK_FILE = "watch.lock";
-
-/**
- * A durable campaign-watch lock, one watcher per campaign across processes.
- * A live holder is never taken over; a dead or recycled pid's lock is stale
- * and is replaced, so a restart after a crash is not blocked. The same
- * liveness rule as the controller lock: a pid is dead only when the probe
- * proves it.
- *
- * @param {string} campaignPath
- * @returns {{pid: number, processStartToken: string|null, startedAt: string, release: () => void}}
- */
-export function acquireWatchLock(campaignPath) {
-  const path = join(campaignPath, WATCH_LOCK_FILE);
-  /** @type {{pid?: number, processStartToken?: string|null, startedAt?: string}} */
-  let occupant = {};
-  for (let attempt = 0; attempt < 20; attempt += 1) {
-    const record = { pid: process.pid, processStartToken: processStartToken(process.pid), startedAt: new Date().toISOString() };
-    try {
-      const fd = openSync(path, "wx", 0o600);
-      try {
-        writeSync(fd, JSON.stringify(record));
-      } finally {
-        closeSync(fd);
-      }
-      return {
-        ...record,
-        release() {
-          try {
-            unlinkSync(path);
-          } catch (error) {
-            if (errorCode(error) !== "ENOENT") throw error;
-          }
-        },
-      };
-    } catch (error) {
-      if (errorCode(error) !== "EEXIST") throw error;
-    }
-    try {
-      occupant = /** @type {{pid?: number, processStartToken?: string|null}} */ (JSON.parse(readFileSync(path, "utf8")));
-    } catch {
-      occupant = {};
-    }
-    if (!watchLockStale(occupant)) {
-      throw new Error(`campaign watch is already running (pid ${occupant.pid})`);
-    }
-    try {
-      unlinkSync(path);
-    } catch (error) {
-      if (errorCode(error) !== "ENOENT") throw error;
-    }
-  }
-  throw new Error("campaign watch lock contention did not settle");
-}
-
-/**
- * @param {{pid?: number, processStartToken?: string|null}} occupant
- * @returns {boolean}
- */
-function watchLockStale(occupant) {
-  if (typeof occupant.pid !== "number") return true;
-  if (!pidAlive(occupant.pid)) return true;
-  return Boolean(occupant.processStartToken) && processStartToken(occupant.pid) !== occupant.processStartToken;
-}
-
-
 /**
  * @param {string} campaignId
  * @param {CliValues} values
@@ -467,9 +290,38 @@ function close(campaignId, values) {
   renderHandoff(path, runsDir);
   process.stdout.write(`[campaign] ${closed.campaign.id} closed\n`);
   process.stdout.write(`[campaign] ledger · docs/campaigns/${closed.campaign.id}/ledger · ${closed.ledgerFiles.length} files\n`);
+  reportRequirementClosure(closed.campaign.requirements ?? []);
   if (syncAgentSignal(runsDir)) process.stdout.write(`[campaign] AGENTS.md signal updated\n`);
 }
 
+/**
+ * Say out loud what the close just wrote, and what it measured.
+ *
+ * The record is a correlation between the requirement ids a linked run's
+ * contract declared and the node snapshots that reached `done` carrying them.
+ * It reads the run directory and never the branch, so a requirement the
+ * operator delivered by hand -- because its node blocked, which happens --
+ * lands in the record as `open` while the work is on main. Measured
+ * 2026-09-22 on `availability-is-verified-not-assumed`: R4 read `open` with
+ * an empty `nodes` array and was merged in `a6a5d43`.
+ *
+ * Nothing printed this before, so the only way to meet the closure was to
+ * open the JSON, where `open` reads as "not delivered" instead of "no node of
+ * this campaign proved it". Naming the measurement is the whole fix: a close
+ * cannot know what it did not run.
+ *
+ * @param {import("../campaign/index.mjs").RequirementClosure[]} requirements
+ */
+function reportRequirementClosure(requirements) {
+  if (requirements.length === 0) return;
+  const open = requirements.filter((entry) => entry.status !== "covered");
+  const covered = requirements.length - open.length;
+  process.stdout.write(`[campaign] requirements · ${covered}/${requirements.length} carried by a node that reached done\n`);
+  if (open.length === 0) return;
+  process.stdout.write(`[campaign] no done node carried ${open.map((entry) => entry.requirementId).join(", ")}\n`);
+  process.stdout.write("[campaign] closure reads node snapshots, never the branch: a requirement delivered outside a node reads open here\n");
+}
+
 /**
  * `campaign supervise <id>` (also spelled `supervise campaign <id>`): the
  * idempotent re-invocation that drives the manifest. It takes the campaign's

package/src/cli/launch.mjs

@@ -55,8 +55,14 @@ export function detachSelf(command, target, extraArgs = []) {
  * exactly as for every detached controller: a foreground launcher is the only
  * moment an operator is present.
  *
+ * `stdio` overrides the discarded default for a caller that has somewhere
+ * durable to put the child's output. A detached *run* wants the default: its
+ * bootstrap record is the channel, and a controller's real output belongs in
+ * the run directory. A detached *plan* has no bootstrap record, so discarding
+ * its stdio discarded the only account of why it died.
+ *
  * @param {string[]} argv
- * @param {{nonce?: string, env?: NodeJS.ProcessEnv}} [options]
+ * @param {{nonce?: string, env?: NodeJS.ProcessEnv, stdio?: import("node:child_process").StdioOptions}} [options]
  * @returns {DetachedChild}
  */
 export function detachArgv(argv, options = {}) {
@@ -74,7 +80,7 @@ export function detachArgv(argv, options = {}) {
     // pending forever. There it also means DETACHED_PROCESS: no console
     // window, which is what "ignore" stdio already implies.
     detached: true,
-    stdio: "ignore",
+    stdio: options.stdio ?? "ignore",
   }));
   child.unref();
   child.bootstrapNonce = nonce;

package/src/cli/plan.mjs

@@ -16,6 +16,7 @@ import { colorLevel, statusToken } from "./brand.mjs";
 import { delay } from "../util.mjs";
 import { runPlanningPipeline } from "../plan/pipeline.mjs";
 import { campaignTree, runDirectory } from "../run/paths.mjs";
+import { readCampaign } from "../campaign/record.mjs";
 
 /** How often a foreground `plan` polls a launched stage's run directory. */
 const DEFAULT_POLL_MS = 1_000;
@@ -125,7 +126,7 @@ export function loadVerificationSuites(path) {
 
 /**
  * @param {string} target
- * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, runtimes?: string, verification?: string, package?: string, detach?: boolean, json?: boolean}} values
+ * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, runtimes?: string, verification?: string, package?: string, "targeted-fix"?: boolean, detach?: boolean, json?: boolean}} values
  * @returns {Promise<void>}
  */
 export async function planCli(target, values) {
@@ -151,7 +152,14 @@ export async function planCli(target, values) {
     if (typeof values.runtimes === "string" && values.runtimes) argv.push("--runtimes", resolve(values.runtimes));
     if (typeof values.verification === "string" && values.verification) argv.push("--verification", resolve(values.verification));
     if (packageMode !== "implementation") argv.push("--package", packageMode);
+    if (values["targeted-fix"] === true) argv.push("--targeted-fix");
     const failurePath = planBootstrapFailurePath(process.cwd(), campaignId, phase);
+    // Read the campaign before creating anything: the failure record lives
+    // inside the campaign tree, so a typo in --campaign would otherwise leave
+    // a campaign directory with no record in it for `discoverCampaigns` to
+    // find. The child reads it too; this is the launcher refusing what it can
+    // see for itself rather than detaching into a certain failure.
+    readCampaign(campaignTree(process.cwd(), campaignId));
     mkdirSync(dirname(failurePath), { recursive: true });
     rmSync(failurePath, { force: true });
     const child = detachArgv(argv);
@@ -188,6 +196,7 @@ export async function planCli(target, values) {
       runtimeDefaults,
       runtimes,
       verification,
+      targetedFix: values["targeted-fix"] === true,
       packageMode,
       launch: async (contractPath, contract) => {
         const child = detachSelf("run", contractPath);

package/src/cli.mjs

@@ -124,6 +124,7 @@ export const COMMAND_OPTIONS = {
     runtimes: { type: "string" },
     verification: { type: "string" },
     package: { type: "string" },
+    "targeted-fix": { type: "boolean" },
     detach: { type: "boolean" },
     json: { type: "boolean" },
   },

package/src/contract/verification.mjs

@@ -8,7 +8,18 @@ export const VERIFICATION_LIMITS = Object.freeze({
   stderrBytes: 16 * 1024,
   maxCommands: 32,
   maxRepeat: 8,
-  maxTimeoutSec: 600,
+  // A verification command may declare up to half an hour. It was 600s, which
+  // is below this repository's own suite: measured 2026-09-22, `npm test`
+  // takes 434-473s at the default parallelism on the author's machine and 650s
+  // on a Windows CI runner, and `node --test --test-concurrency=1 test/engine/`
+  // -- the way a packet's verification actually runs it -- takes 1035-1058s.
+  // So the one command that proves the engine could not be declared at all,
+  // and a packet author's way out was `--test-name-pattern`, which exits 0
+  // when it matches nothing (see AGENTS.md). A cap that pushes authors toward
+  // a proof that certifies nothing is worse than a longer runaway. The node's
+  // own wall clock (`contract.timeoutSec`, 2400s by default) still bounds the
+  // attempt above this.
+  maxTimeoutSec: 1_800,
   stateStdoutBytes: 2 * 1024,
   stateCommands: 16,
   stateAttempts: 4,

package/src/engine/dispatch.mjs

@@ -34,7 +34,7 @@ import { invocationCost, invocationUsage } from "../run/usage.mjs";
 import { logPaths, startProcess } from "./process.mjs";
 import { readBoundedTail } from "./transcript.mjs";
 import { mkdirSync, statSync } from "node:fs";
-import { READ_BYTE_LIMIT, READ_LINE_LIMIT, normalizeProviderResult } from "../harnesses/index.mjs";
+import { READ_BYTE_LIMIT, READ_LINE_LIMIT, harnessCapabilities, normalizeProviderResult } from "../harnesses/index.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
 import { judgeReaskInstruction, reviewMode } from "../contract/review-modes.mjs";
 import { routeRuntimeForState, runtimeSnapshot } from "./failover.mjs";
@@ -153,12 +153,19 @@ function workerToolPolicy(runtime, node, workspace) {
  * @returns {import("../harnesses/index.mjs").CommandOptions}
  */
 function invocationCommandOptions(contract, node, state, runtime, phasePlan, runDir, lock, extra = {}) {
+  // A harness that streams its stdout proves liveness through the event
+  // monitor; a buffered one (zcode's `--json` writes only at exit) has one
+  // live surface left, its own log stream, and the adapter decides whether
+  // this dir means anything to it. Streaming harnesses get none: their log
+  // dir would be dead weight the engine never watches.
+  const streaming = harnessCapabilities(runtime).streamsOutput === true;
   return {
     ...extra,
     continuationId: runtime.capabilities.continuation === true ? phasePlan.continuationId : null,
     // The attempt's request ceiling. An adapter that can enforce it natively
     // takes it as a flag; the monitor enforces it for every streaming harness.
     maxTurns: node.maxTurns ?? contract.maxTurns,
+    logDir: streaming ? null : join(runDir, "logs", `${node.id}.${state.attempt}.provider`),
   };
 }
 /**

package/src/engine/gate.mjs

@@ -25,7 +25,8 @@
  * It also exits when the release file's directory is gone (measured
  * 2026-09-16: gate processes from a prior day's test runs, spawned into a
  * temp directory the failed test never cleaned up, were still alive and
- * waiting for a release file that could now never appear).
+ * waiting for a release file that could now never appear), and it keeps
+ * asking both of those questions after the provider starts, not only before.
  */
 import { existsSync, readFileSync, statSync, openSync, closeSync, readSync, writeSync } from "node:fs";
 import { dirname } from "node:path";
@@ -186,11 +187,32 @@ function releaseDirectoryGone() {
   return !existsSync(dirname(releasePath));
 }
 
+/**
+ * How often the gate re-asks its two liveness questions once the provider is
+ * running. Before release the tick below asks them every 10ms, because it is
+ * also polling for the release file; after release it used to stop asking
+ * entirely, leaving the provider's own exit as the gate's only remaining
+ * liveness check. A controller that died without cleaning up, or a run
+ * directory deleted underneath a live attempt, therefore left the provider
+ * running with nobody watching -- the stranded-process shape ADR 0010
+ * describes, in the one window the pre-release check does not cover.
+ *
+ * A second, not ten milliseconds: this watches a provider that runs for
+ * minutes, and three syscalls a second is the whole cost of never stranding
+ * one.
+ */
+const WATCHDOG_INTERVAL_MS = 1_000;
+
 const timer = setInterval(() => {
   if (!parentAlive()) { clearInterval(timer); stopProvider(); return; }
   if (releaseDirectoryGone()) { clearInterval(timer); stopProvider(); return; }
   if (!existsSync(releasePath)) return;
   clearInterval(timer);
+  const watchdog = setInterval(() => {
+    if (parentAlive() && !releaseDirectoryGone()) return;
+    clearInterval(watchdog);
+    stopProvider();
+  }, WATCHDOG_INTERVAL_MS);
   const stdoutFd = openSync(config.stdoutPath, "wx", 0o600);
   const stderrFd = openSync(config.stderrPath, "wx", 0o600);
   const invocation = spawnInvocation(config.executable, config.args, { cwd: config.cwd });
@@ -207,6 +229,7 @@ const timer = setInterval(() => {
   }
   provider.once("error", () => process.exitCode = 127);
   provider.once("close", (code) => {
+    clearInterval(watchdog);
     capLog(config.stdoutPath, config.harness === "codex");
     capLog(config.stderrPath);
     process.exit(code ?? 1);

package/src/engine/lifecycle.mjs

@@ -147,8 +147,19 @@ export function terminalErrorCode(state) {
  * `turn_limit` is here and not among the timeout codes below: a turn the CLI
  * stopped itself at `--max-turns` exits cleanly with no seal yet, and the
  * next dispatch seals its worktree as it does for any previous attempt.
+ *
+ * `incomplete_stream` is a stream that ended before its terminal envelope --
+ * Claude with no `result`, codex with no `turn.completed`, dsh with neither
+ * terminal record (`harnesses/protocol.mjs`). That is the provider's transport
+ * dying mid-turn, not the run's own doing, so it is the same class as
+ * `provider_error` and earns the same one retry. It was absent, and a worker
+ * whose provider dropped its connection parked on the first attempt while a
+ * worker whose provider returned an error envelope got a second one -- the
+ * harsher treatment for the less informative failure. The judge role is
+ * unaffected: `engine/settle-judge.mjs` routes this code to its own bounded
+ * re-ask before anything parks.
  */
-export const AUTO_RETRY_CODES = new Set(["judge_unavailable", "provider_error", "stall_timeout", "wall_clock_timeout", "turn_limit"]);
+export const AUTO_RETRY_CODES = new Set(["judge_unavailable", "provider_error", "incomplete_stream", "stall_timeout", "wall_clock_timeout", "turn_limit"]);
 
 /**
  * Timeout codes earn their automatic retry only when phase 5b sealed work

package/src/engine/process.mjs

@@ -7,7 +7,7 @@
  * a judge decides, or when a run is done. That separation is the point: a stuck
  * provider is killed by the same code whatever it was asked to do.
  */
-import { boundedRegion, monitorInvocation } from "./transcript.mjs";
+import { boundedRegion, latestLogWriteMs, monitorInvocation } from "./transcript.mjs";
 import { closeSync, existsSync, fsyncSync, openSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { errorCode, errorMessage } from "../util.mjs";
@@ -36,7 +36,7 @@ import { killTarget } from "../host/platform.mjs";
 /** @typedef {{prompt: string|null, stdout: string, stderr: string}} PathSet */
 /** @typedef {{id: string, pid: number, processGroupId: number|null, processStartToken: string|null, harness: string, runtimeId: string|null, runtimeFingerprint?: string, revision?: number, phase: string, promptPath: string|null, stdoutPath: string, stderrPath: string, startedAt: string, deadlineAt: string|null, updatedAt: string, closedAt: string|null, exitCode: number|null, signal: string|null, status: "active"|"closed"|"terminated", executable: string, snapshotPath?: string, usage?: Usage, usageEstimated?: boolean, costUsd?: number|null, costProvenance?: "priced", runId?: string, campaignId?: string, nodeId?: string, attempt?: number, workspace?: string, worktreeBranch?: string|null, worktreeBaseSha?: string|null, planPhase?: string, role?: "worker"|"judge", model?: string, reasoning?: string|null, sandbox?: string|null, continuationId?: string|null, continuationMode?: "fresh"|"reuse"|"rotate", session?: import("../harnesses/session-metrics.mjs").SessionLedger|null}} Invocation */
 /** @typedef {{pid: number|null, processGroupId?: number|null, processStartToken?: string|null}} InvocationProbe */
-/** @typedef {{child: ChildProcess, contract: ValidatedContract, node: ValidatedNode, state: NodeSnapshot, runtime: HarnessRuntime & {id: string|null}, cwd: string, paths: PathSet, phase: string, invocation: Invocation, startedAt: string, startedTicks: bigint, progressTicks: bigint, lastOutputAt: number, closed: boolean, exitCode: number|null, signal: string|null, spawnError: Error|null, terminating: Promise<void>|null, gateConfigPath: string, gateReleasePath: string, scopeBaseline?: unknown, scopeChecked?: boolean, scopeViolation?: boolean, resultMaterialization?: boolean, recoveryBaseline?: unknown, observeTimer?: ReturnType<typeof setInterval>, monitorOffset?: number, monitorParser?: import("../harnesses/session-metrics.mjs").SessionMetricsParser, lastEventCount?: number, lastMonitorOffset?: number, observedOnce?: boolean, turnCapWarned?: boolean, onClose?: (invocation: Invocation) => void, onInvocationUpdate?: (invocation: Invocation) => void, onProgress?: (state: NodeSnapshot) => void}} Job */
+/** @typedef {{child: ChildProcess, contract: ValidatedContract, node: ValidatedNode, state: NodeSnapshot, runtime: HarnessRuntime & {id: string|null}, cwd: string, paths: PathSet, phase: string, invocation: Invocation, startedAt: string, startedTicks: bigint, progressTicks: bigint, lastOutputAt: number, closed: boolean, exitCode: number|null, signal: string|null, spawnError: Error|null, terminating: Promise<void>|null, gateConfigPath: string, gateReleasePath: string, logDir?: string|null, scopeBaseline?: unknown, scopeChecked?: boolean, scopeViolation?: boolean, resultMaterialization?: boolean, recoveryBaseline?: unknown, observeTimer?: ReturnType<typeof setInterval>, monitorOffset?: number, monitorParser?: import("../harnesses/session-metrics.mjs").SessionMetricsParser, lastEventCount?: number, lastMonitorOffset?: number, lastLogWriteMs?: number, observedOnce?: boolean, turnCapWarned?: boolean, onClose?: (invocation: Invocation) => void, onInvocationUpdate?: (invocation: Invocation) => void, onProgress?: (state: NodeSnapshot) => void}} Job */
 /** @typedef {{graceMs?: number, killGraceMs?: number, escalate?: boolean, runDir?: string, kill?: (pid: number, signal: string|number) => unknown, child?: ChildProcess|null}} TerminateOptions */
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -48,6 +48,16 @@ const GATE_PATH = join(HERE, "gate.mjs");
  */
 export function startProcess({ contract, node, state, runtime, prompt, paths, phase, workspace = contract.cwd, commandOptions = {}, onInvocation, onInvocationUpdate, onProgress }) {
   const command = providerCommand(runtime, prompt, commandOptions);
+  // The engine offers a log dir to every non-streaming harness; only an
+  // adapter that wants one creates it (zcode does, inside `command()` above,
+  // which has already run). Taking the offer is therefore observable, and the
+  // stall detector must key on the adapter's answer rather than on the
+  // engine's offer: `exec-jsonl` and `replay` are non-streaming too, declare
+  // no `stallTimeoutSec`, and were deliberately not stall-tracked at all. A
+  // path they never write to would otherwise have made them tracked against a
+  // log that stays empty forever -- measured 2026-09-22 against the contract
+  // default of 300s, a healthy exec-jsonl worker was killed as stalled.
+  const logDir = commandOptions.logDir && existsSync(commandOptions.logDir) ? commandOptions.logDir : null;
   if (paths.prompt) writeFileSync(paths.prompt, prompt, { flag: "wx", mode: 0o600 });
   const gateConfigPath = `${paths.prompt}.gate.json`;
   const gateReleasePath = `${paths.prompt}.gate.release`;
@@ -125,6 +135,7 @@ export function startProcess({ contract, node, state, runtime, prompt, paths, ph
     terminating: null,
     gateConfigPath,
     gateReleasePath,
+    logDir,
     onInvocationUpdate,
     onProgress,
   };
@@ -433,11 +444,13 @@ export async function detectStalls(contract, running, onTimeout, onProgress, onB
     // calling tools is alive even when it writes no workspace file, and a
     // buffered harness (zcode's `--json`) writes its whole transcript only at
     // exit, so its mtime proves nothing. A harness that never streams is
-    // stall-tracked only when its runtime declares its own threshold; otherwise
-    // the wall clock above is the only budget it is held to.
+    // stall-tracked through its provider log dir when its adapter keeps one
+    // (zcode points the CLI's `ZCODE_LOG_DIR` at it), through a runtime that
+    // declares its own threshold, or by neither — the wall clock above is
+    // then the only budget it is held to.
     const streaming = harnessCapabilities(job.runtime).streamsOutput;
     const declaredStall = typeof (/** @type {{stallTimeoutSec?: unknown}} */ (job.runtime)?.stallTimeoutSec) === "number";
-    if (!streaming && !declaredStall) continue;
+    if (!streaming && !declaredStall && !job.logDir) continue;
     const stallTimeoutSec = stallTimeoutSecFor(job.runtime, contract);
     if (streaming) {
       const monitored = monitorInvocation(job);
@@ -499,9 +512,24 @@ export async function detectStalls(contract, running, onTimeout, onProgress, onB
         await onTimeout(job, "exhausted", limit);
         continue;
       }
-    } else if (job.observedOnce !== true) {
-      job.progressTicks = now;
-      job.lastOutputAt = Date.now();
+    } else {
+      // The buffered-harness liveness signal: the CLI's log stream appending
+      // inside the attempt's log dir. An mtime that advances past the newest
+      // one this loop has seen is a write, and a write is progress — the same
+      // lower-bound discipline as the polling fixtures: it can only delay a
+      // stall verdict, never prove speed.
+      if (job.logDir) {
+        const written = latestLogWriteMs(job.logDir);
+        if (written > (job.lastLogWriteMs ?? 0)) {
+          job.lastLogWriteMs = written;
+          job.progressTicks = now;
+          job.lastOutputAt = Date.now();
+        }
+      }
+      if (job.observedOnce !== true) {
+        job.progressTicks = now;
+        job.lastOutputAt = Date.now();
+      }
     }
     job.observedOnce = true;
     if (elapsedSeconds(job.progressTicks, now) < stallTimeoutSec) continue;

package/src/engine/transcript.mjs

@@ -6,10 +6,11 @@
  * because reading the log never touches the process, and because process.mjs
  * crossed the 800-line ceiling carrying both jobs.
  */
-import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+import { closeSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";
 import { Buffer } from "node:buffer";
 import { SessionMetricsParser } from "../harnesses/session-metrics.mjs";
 import { errorCode } from "../util.mjs";
+import { join } from "node:path";
 
 /** @typedef {import("./process.mjs").Job} Job */
 
@@ -143,3 +144,44 @@ function dropPartialLogLine(value) {
   const newline = String(value).indexOf("\n");
   return newline < 0 ? "" : String(value).slice(newline + 1);
 }
+
+/**
+ * Newest write inside the attempt's provider log dir, 0 when nothing is there
+ * yet. The CLI lays its session logs out as files (it may nest a directory),
+ * so the scan walks three levels and reads only mtimes — never contents,
+ * which is the monitor's job for streaming harnesses and nobody else's.
+ * Every stat failure is an ordinary not-yet: a dir with nothing readable in
+ * it proves no liveness, which is exactly the right answer.
+ *
+ * Cheap enough to run on every tick: measured 2026-09-22 on macOS, a dir of
+ * 250 files across two levels scans in 0.80 ms, against the 1000 ms default
+ * `pollIntervalMs` — so the cost is under a tenth of a percent of one job's
+ * poll, and the scan reads no bytes.
+ *
+ * @param {string} dir
+ * @param {number} [depth]
+ * @returns {number}
+ */
+export function latestLogWriteMs(dir, depth = 0) {
+  let newest = 0;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (depth < 3) newest = Math.max(newest, latestLogWriteMs(path, depth + 1));
+      continue;
+    }
+    try {
+      newest = Math.max(newest, statSync(path).mtimeMs);
+    } catch {
+      // Raced a rotation or a permission change: this entry proves nothing,
+      // the rest of the scan still does.
+    }
+  }
+  return newest;
+}

package/src/harnesses/index.mjs

@@ -95,7 +95,7 @@ export const READ_LINE_LIMIT = 1500;
  */
 export const READ_BYTE_LIMIT = 32 * 1024;
 
-/** @typedef {{schema?: object, schemaPath?: string, continuationId?: string|null, toolPolicy?: ToolPolicy, env?: Record<string, string>, maxTurns?: number}} CommandOptions */
+/** @typedef {{schema?: object, schemaPath?: string, continuationId?: string|null, toolPolicy?: ToolPolicy, env?: Record<string, string>, maxTurns?: number, logDir?: string|null}} CommandOptions */
 
 /** @typedef {{preferStructured?: boolean, exitCode?: number|null, signal?: string|null, stderr?: string}} NormalizeOptions */
 

package/src/harnesses/zcode/index.mjs

@@ -1,4 +1,4 @@
-import { accessSync, chmodSync, constants, existsSync, lstatSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { normalizeZcodeResult, parseVersion } from "../protocol.mjs";
@@ -20,6 +20,20 @@ const ZCODE_MACOS_BUNDLE = Object.freeze({
   cli: "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
 });
 
+/**
+ * Linux install layouts: an Electron `.deb`/`.rpm` unpacks the app under
+ * `/opt/<App>` (some packagers use `/usr/lib/<app>`) with the same
+ * `resources/` shape the macOS bundle has. None of these is documented by the
+ * vendor — `docs/harnesses/zcode-cli.md` records only the macOS layout — so the
+ * list is a probe, and `FABERUN_ZCODE_APP_DIR` names an install this list
+ * does not know.
+ */
+const ZCODE_LINUX_BUNDLES = Object.freeze([
+  { electron: "/opt/ZCode/zcode", cli: "/opt/ZCode/resources/glm/zcode.cjs" },
+  { electron: "/opt/zcode/zcode", cli: "/opt/zcode/resources/glm/zcode.cjs" },
+  { electron: "/usr/lib/zcode/zcode", cli: "/usr/lib/zcode/resources/glm/zcode.cjs" },
+]);
+
 /** Provider id in the ZCODE_MODEL target; it also derives the auth env var name. */
 const ZCODE_DEFAULT_PROVIDER = "glm";
 
@@ -68,7 +82,9 @@ export const zcodeHarness = {
     // once at exit: a live worker node was killed at 420s stall_timeout with
     // its stdout/stderr at zero bytes, while a completed 1m26s invocation's
     // log held its full 26 lines only once the process exited. Stall
-    // detection must not watch this harness's stdout/stderr mtime.
+    // detection must not watch this harness's stdout/stderr mtime. Liveness
+    // comes from the CLI's own log stream instead — see `command()`'s
+    // ZCODE_LOG_DIR wiring, which the engine's stall clock watches.
     streamsOutput: false,
     // Unmeasured: no run has proven whether zcode's sandbox can signal child
     // processes or read the process table.
@@ -134,6 +150,19 @@ export const zcodeHarness = {
     // resolves (e.g. GLM_API_KEY); an unresolved token is omitted, not blanked.
     const apiKeyVar = providerApiKeyVar(provider);
     if (token !== null && apiKeyVar !== null) env[apiKeyVar] = token;
+    // The one live surface a buffered harness has: the CLI's own log stream.
+    // `--json` writes stdout only at exit, but `ZCODE_LOG_DIR` in `json`
+    // format receives session events as they happen, so the engine's stall
+    // clock can watch the log dir instead of holding the attempt to the wall
+    // clock alone. The engine supplies one dir per attempt (see
+    // `invocationCommandOptions`); the adapter creates it and points the CLI
+    // at it, and console logging stays off so stderr stays a pure error path.
+    if (options.logDir) {
+      mkdirSync(options.logDir, { recursive: true });
+      env.ZCODE_LOG_DIR = options.logDir;
+      env.ZCODE_LOG_FORMAT = "json";
+      env.ZCODE_LOG_CONSOLE = "false";
+    }
     return { executable: this.executable(runtime), args, promptTransport: "argv", input: null, env };
   },
 
@@ -187,8 +216,8 @@ export function ensureZcodeAvailable(options = {}) {
     const env = options.env ?? process.env;
     const pathDirs = options.pathDirs ?? (env.PATH ?? "").split(delimiter).filter(Boolean);
     if (resolvesOnPath(pathDirs, ZCODE_BIN_NAME)) return;
-    const bundle = options.bundle ?? ZCODE_MACOS_BUNDLE;
-    if (!existsSync(bundle.electron) || !existsSync(bundle.cli)) return;
+    const bundle = options.bundle ?? zcodeBundle(env);
+    if (!bundle || !existsSync(bundle.electron) || !existsSync(bundle.cli)) return;
     const body = zcodeShim(bundle);
     for (const dir of shimDirs(options.home ?? homedir())) {
       if (!pathDirs.includes(dir)) continue;
@@ -200,6 +229,22 @@ export function ensureZcodeAvailable(options = {}) {
   }
 }
 
+/**
+ * The bundle this host has, if any: an explicit `FABERUN_ZCODE_APP_DIR`
+ * override, the macOS app path on darwin, or the first probed Linux layout
+ * whose two paths both exist. A host with none gets null — the same "not
+ * installed" answer every probe below returns.
+ *
+ * @param {Record<string, string|undefined>} env
+ * @returns {{electron: string, cli: string}|null}
+ */
+function zcodeBundle(env) {
+  const appDir = env.FABERUN_ZCODE_APP_DIR;
+  if (appDir) return { electron: join(appDir, "zcode"), cli: join(appDir, "resources", "glm", "zcode.cjs") };
+  if (process.platform === "darwin") return ZCODE_MACOS_BUNDLE;
+  return ZCODE_LINUX_BUNDLES.find((bundle) => existsSync(bundle.electron) && existsSync(bundle.cli)) ?? null;
+}
+
 /**
  * The shim body. It runs the bundle through the app's own Electron binary as
  * node because the CLI mis-handles its response path under a system node

package/src/plan/pipeline.mjs

@@ -82,13 +82,17 @@ export const DEFAULT_NODE_BUDGET_MS = 600_000;
 const APPROVE_BELOW_VALUES = new Set(["standard", "high", "none"]);
 
 /**
- * @param {{specPath: string, campaignId: string, phase: string, cwd?: string, reviewRounds?: number, approveBelow?: ApproveBelow, runtimeDefaults?: {worker?: string, judge?: string}, runtimes: Record<string, JsonObject>, verification?: VerificationSuites, packageMode?: import("./sizing.mjs").PackageMode, launch: LaunchFn, wait: WaitFn, ask?: AskFn}} options
+ * @param {{specPath: string, campaignId: string, phase: string, cwd?: string, reviewRounds?: number, approveBelow?: ApproveBelow, runtimeDefaults?: {worker?: string, judge?: string}, runtimes: Record<string, JsonObject>, verification?: VerificationSuites, packageMode?: import("./sizing.mjs").PackageMode, targetedFix?: boolean, launch: LaunchFn, wait: WaitFn, ask?: AskFn}} options
+ *   `targetedFix` allows a plan with a single node. Sizing refuses one by
+ *   default because a phase that decomposes into one node is usually a plan
+ *   that was never decomposed; a targeted fix is the case where one node is
+ *   the honest answer, and the operator says so.
  * @returns {Promise<FrozenPipelineResult|ContestedPipelineResult>}
  */
 export async function runPlanningPipeline(options) {
   const {
     specPath, campaignId, phase, runtimes, launch, wait,
-    reviewRounds = 2, runtimeDefaults = {}, verification = {},
+    reviewRounds = 2, runtimeDefaults = {}, verification = {}, targetedFix = false,
   } = options;
   const ask = options.ask ?? askPlanningRuntimes;
   // Implementation work is sized by what it writes; exploratory work -- an
@@ -258,7 +262,7 @@ export async function runPlanningPipeline(options) {
     stage = "sizing";
     const sizing = applySizingRules(
       { nodes: currentPlan.nodes.map(toSizingNode), justification: currentPlan.justification },
-      { nodeBudgetMs: DEFAULT_NODE_BUDGET_MS, facts: repoFacts, minWriteFiles: MIN_WRITE_FILES, turnCeiling: DEFAULT_MAX_TURNS, packageMode, readVolume: (path) => fileLineCount(join(cwd, path)) },
+      { nodeBudgetMs: DEFAULT_NODE_BUDGET_MS, facts: repoFacts, minWriteFiles: MIN_WRITE_FILES, turnCeiling: DEFAULT_MAX_TURNS, packageMode, readVolume: (path) => fileLineCount(join(cwd, path)), targetedFix },
     );
     stage = "routing";
     const routing = resolveRuntimes(sizing.plan.nodes, {