muse-crew 0.17.1 → 0.17.3

package/lib/chore-tick.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+// lib/chore-tick.js — the tick worker's ferry for worker-layer Chore claims
+// (sandbox exit, cutover piece, 2026-09-26).
+//
+// The tick worker invokes this once per worker-chore claim per tick:
+//   node lib/chore-tick.js --crew-home H --task-id T --tick-seq N [options]
+//   node lib/chore-tick.js --crew-home H --task-id T --tick-seq N --session S [options]
+//
+// It sequences the driver and the spawn bridge in-process (no shell), so
+// the NEED_SPAWN request JSON never crosses a shell-quoting boundary.
+// The one act it cannot do — spawning the agent — stays with the tick
+// worker (an LLM runtime capability), via the "spawn" action.
+//
+// Stdout carries EXACTLY ONE JSON line; all logs go to stderr.
+// Actions:
+//   {"action":"spawn","spawn":{prompt,cwd,env,timeout_ms,session_path,key,attempt_n,row_id},...}
+//       — spawn-step pre succeeded. The tick worker spawns ONE subagent
+//         with the packet, records child+outcome into the session file,
+//         then re-invokes this script with --session.
+//   {"action":"wait","reason":..,...}
+//       — a spawn is in flight (or the frame budget ran out). Stop; the
+//         next tick re-invokes. Never a failure.
+//   {"action":"done","outcome":..,...}
+//       — the driver reached a terminal outcome. The driver already wrote
+//         the task state.
+//   {"action":"error","reason":..}
+//       — transport failure (unparseable driver frame). Log and stop; the
+//         next tick retries. Exit code is 1.
+//
+// With --session S: runs `spawn-step.js post --session S` first (settles
+// the spawn the tick worker just completed), then continues driving.
+// Every post outcome is safe to drive through: closed, already_closed,
+// kill_unverified, and post errors all resolve via the driver's next
+// derivation (advance, or WAIT on the still-running row).
+//
+// A spawn-step pre refusal (DUPLICATE_RUNNING, ATTEMPTS_EXHAUSTED,
+// TRANSPORT_BUDGET_EXHAUSTED, BOUNDS_REJECTED) is NOT an error: the
+// ledger now reflects the refusal and the driver's next derivation
+// resolves it (WAIT or DONE/failed). It counts against the frame budget.
+//
+// Frame budget (--max-frames, default 20): bounds the in-tick drive loop.
+// Exhaustion emits action "wait" (never "done"/"failed") — the next tick
+// resumes. Budgets end the tick's participation, never the task.
+//
+// Concurrency: the driver is safe to re-invoke any time (STANDBY→WAIT on
+// a running spawn; claim-as-gate STAND_DOWN on a lost race). The tick
+// worker must not invoke this twice concurrently for the same task.
+//
+// No wall-clock reads and no randomness in decision paths (G3).
+
+import { execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LIB_DIR = dirname(fileURLToPath(import.meta.url));
+const CHORE_RUN = join(LIB_DIR, "chore-run.js");
+const SPAWN_STEP = join(LIB_DIR, "spawn-step.js");
+
+const DEFAULT_MAX_FRAMES = 20;
+
+// Permanent spawn-pre refusal codes (2026-09-26): the refusal fires before
+// any spawn-ledger row is opened, so the ledger cannot reflect it and the
+// next derivation would emit an identical NEED_SPAWN forever. On these
+// codes the ferry re-drives the driver ONCE with --pre-refusal so the
+// driver terminates (PARK for BOUNDS_REJECTED, FAILED for the budget
+// codes) through the normal closeout. DUPLICATE_RUNNING is the legitimate
+// re-drive case and keeps the old behavior. Must match
+// TERMINAL_REFUSAL_CODES in lib/chore-run.js.
+const TERMINAL_REFUSAL_CODES = [
+  "BOUNDS_REJECTED",
+  "ATTEMPTS_EXHAUSTED",
+  "TRANSPORT_BUDGET_EXHAUSTED",
+];
+
+const USAGE = [
+  "Usage: node lib/chore-tick.js --crew-home <dir> --task-id <id> --tick-seq <n> [options]",
+  "",
+  "Tick ferry for one worker-layer Chore claim: drives chore-run.js and the",
+  "spawn bridge, emitting exactly one JSON action on stdout (spawn | wait |",
+  "done | error). The tick worker performs the agent spawn on \"spawn\" and",
+  "re-invokes with --session; on \"wait\"/\"done\" it stops for this tick.",
+  "",
+  "Required:",
+  "  --crew-home <dir>   crew home directory",
+  "  --task-id <id>      task to drive",
+  "  --tick-seq <n>      owning tick sequence (positive integer)",
+  "",
+  "Options:",
+  "  --session <path>        settle this spawn session first (spawn-step post), then drive",
+  "  --max-frames <n>        drive-loop bound before yielding wait (default 20)",
+  "  --project-id <id>       expected project (forwarded to the driver)",
+  "  --visual-protocol       visual protocol available (forwarded)",
+  "  --no-visual-protocol    visual protocol unavailable (forwarded)",
+  "  --resolved-workflow <w> workflow name (forwarded; defaults to the task's)",
+  "  --workflow-was-null     the dispatcher did not specify a workflow",
+  "  --help                  print this usage",
+].join("\n");
+
+// --help is answered on stdout with exit 0 BEFORE required-argument parsing
+// (lib/AGENTS.md shebang⇔CLI contract).
+const RAW_ARGS = process.argv.slice(2);
+if (RAW_ARGS.indexOf("--help") !== -1 || RAW_ARGS.indexOf("-h") !== -1) {
+  process.stdout.write(USAGE + "\n");
+  process.exit(0);
+}
+
+function log(message) {
+  process.stderr.write("[chore-tick] " + String(message) + "\n");
+}
+
+function printJson(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+function errText(e) {
+  return (e && e.message) || String(e);
+}
+
+function parseArgs(argv) {
+  const o = {
+    crewHome: null, taskId: null, tickSeq: null, session: null,
+    maxFrames: DEFAULT_MAX_FRAMES, projectId: null, visualProtocol: null,
+    resolvedWorkflow: null, workflowWasNull: false, preRefusal: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--crew-home") o.crewHome = argv[++i];
+    else if (a === "--task-id") o.taskId = argv[++i];
+    else if (a === "--tick-seq") o.tickSeq = argv[++i];
+    else if (a === "--session") o.session = argv[++i];
+    else if (a === "--max-frames") o.maxFrames = argv[++i];
+    else if (a === "--project-id") o.projectId = argv[++i];
+    else if (a === "--visual-protocol") o.visualProtocol = true;
+    else if (a === "--no-visual-protocol") o.visualProtocol = false;
+    else if (a === "--resolved-workflow") o.resolvedWorkflow = argv[++i];
+    else if (a === "--workflow-was-null") o.workflowWasNull = true;
+    else throw new Error("unknown argument: " + a);
+  }
+  if (!o.crewHome) throw new Error("--crew-home is required");
+  if (!o.taskId) throw new Error("--task-id is required");
+  if (!/^[1-9][0-9]*$/.test(String(o.tickSeq || ""))) {
+    throw new Error("--tick-seq must be a positive integer");
+  }
+  if (!/^[1-9][0-9]*$/.test(String(o.maxFrames))) {
+    throw new Error("--max-frames must be a positive integer");
+  }
+  o.maxFrames = parseInt(o.maxFrames, 10);
+  return o;
+}
+
+// Run a node script with argv (no shell). Returns {ok, stdout} — ok
+// reflects the exit code, but callers parse stdout regardless: both
+// chore-run.js and spawn-step.js print structured JSON on failure paths.
+function runNode(script, args) {
+  try {
+    const stdout = execFileSync("node", [script].concat(args), {
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    return { ok: true, stdout: stdout };
+  } catch (e) {
+    return {
+      ok: false,
+      stdout: (e.stdout || "").toString(),
+      stderr: (e.stderr || "").toString(),
+      code: e.status,
+    };
+  }
+}
+
+function parseJsonLine(text) {
+  const line = String(text || "").trim().split("\n").pop() || "";
+  if (!line) return { ok: false, reason: "empty stdout" };
+  try {
+    return { ok: true, value: JSON.parse(line) };
+  } catch (e) {
+    return { ok: false, reason: "unparseable stdout: " + errText(e) };
+  }
+}
+
+function choreRunArgv(o) {
+  const a = ["--crew-home", o.crewHome, "--task-id", o.taskId, "--tick-seq", String(o.tickSeq)];
+  if (o.projectId) a.push("--project-id", o.projectId);
+  if (o.visualProtocol === true) a.push("--visual-protocol");
+  if (o.visualProtocol === false) a.push("--no-visual-protocol");
+  if (o.resolvedWorkflow) a.push("--resolved-workflow", o.resolvedWorkflow);
+  if (o.workflowWasNull) a.push("--workflow-was-null");
+  if (o.preRefusal) a.push("--pre-refusal", o.preRefusal);
+  return a;
+}
+
+// One driver invocation. Returns {frame} or {error}. A parseable frame is
+// used even when the driver exited non-zero (its fail-closed contract
+// still emits the one JSON frame on catastrophic failure).
+function driveOnce(o) {
+  const r = runNode(CHORE_RUN, choreRunArgv(o));
+  const p = parseJsonLine(r.stdout);
+  if (!p.ok) {
+    return { error: "chore-run produced no parseable frame (" + p.reason + ")" +
+      (r.stderr ? "; stderr: " + r.stderr.slice(0, 300) : "") };
+  }
+  const frame = p.value;
+  if (!frame || (frame.type !== "NEED_SPAWN" && frame.type !== "WAIT" && frame.type !== "DONE")) {
+    return { error: "chore-run emitted unknown frame type: " + JSON.stringify(frame).slice(0, 200) };
+  }
+  return { frame: frame };
+}
+
+// Settle a completed spawn session, then let the driver re-derive.
+// Every post outcome is safe to drive through.
+function settleSession(o) {
+  const r = runNode(SPAWN_STEP, ["post", "--session", o.session]);
+  const p = parseJsonLine(r.stdout);
+  if (p.ok && p.value) {
+    const v = p.value;
+    log("post: closed=" + v.closed + (v.reason ? " reason=" + v.reason : "") +
+      (v.row_id ? " row=" + v.row_id : "") + (v.outcome ? " outcome=" + v.outcome : ""));
+  } else {
+    log("post produced no parseable result; driving anyway (" + p.reason + ")" +
+      (r.stderr ? "; stderr: " + r.stderr.slice(0, 200) : ""));
+  }
+}
+
+function main() {
+  let o;
+  try {
+    o = parseArgs(RAW_ARGS);
+  } catch (e) {
+    process.stderr.write(USAGE + "\n\nError: " + errText(e) + "\n");
+    process.exit(2);
+  }
+
+  if (o.session) settleSession(o);
+
+  for (let i = 0; i < o.maxFrames; i++) {
+    const d = driveOnce(o);
+    if (d.error) {
+      log(d.error);
+      printJson({ action: "error", reason: d.error, task_id: o.taskId });
+      process.exit(1);
+    }
+    const frame = d.frame;
+    if (frame.type === "NEED_SPAWN") {
+      const pre = runNode(SPAWN_STEP, ["pre", "--request", JSON.stringify(frame.request || {})]);
+      if (pre.ok) {
+        const p = parseJsonLine(pre.stdout);
+        if (p.ok && p.value && p.value.session_path) {
+          printJson({ action: "spawn", spawn: p.value, task_id: o.taskId });
+          process.exit(0);
+        }
+        log("spawn pre exited 0 with unparseable packet; re-driving");
+        continue;
+      }
+      // Pre refused (or crashed): transient refusals (DUPLICATE_RUNNING — a
+      // spawn is in flight) re-drive so the next derivation resolves to
+      // WAIT; the ledger reflects those. Permanent refusals fire before any
+      // ledger row opens, so re-driving blindly would loop forever — report
+      // the code back to the driver once via --pre-refusal and let it
+      // terminate through the normal closeout. Counts as a frame either way.
+      const ep = parseJsonLine(pre.stdout);
+      const code = (ep.ok && ep.value && ep.value.error && ep.value.error.code) || "pre_failed";
+      if (TERMINAL_REFUSAL_CODES.indexOf(code) !== -1) {
+        log("spawn pre refused (" + code + "); terminal — informing driver");
+        o.preRefusal = code;
+      } else {
+        log("spawn pre refused (" + code + "); re-driving");
+      }
+      continue;
+    }
+    if (frame.type === "WAIT") {
+      printJson({
+        action: "wait", reason: frame.reason || null, phase: frame.phase || null,
+        key: frame.key || null, task_id: o.taskId,
+      });
+      process.exit(0);
+    }
+    // DONE
+    printJson({
+      action: "done", outcome: frame.outcome, task_id: o.taskId,
+      phase: frame.phase || null, reason: frame.reason || null,
+    });
+    process.exit(0);
+  }
+  log("frame budget (" + o.maxFrames + ") exhausted; yielding wait");
+  printJson({ action: "wait", reason: "frame-budget-exhausted", task_id: o.taskId });
+  process.exit(0);
+}
+
+main();

package/lib/compare-dispatch-shadow.js

@@ -21,11 +21,20 @@
 // evidence, not a false alarm.
 //
 // Usage: node compare-dispatch-shadow.js --crew-home <path>
-// Prints one of SHADOW_MATCH / SHADOW_DIVERGE / SHADOW_UNPAIRED /
-// SHADOW_NO_EVIDENCE and appends the verdict to
-// $CREW_HOME/.dispatch-shadow-verdicts.jsonl. Exit 0 on a verdict (even a
-// diverge — divergence is evidence, not a failure); exit 2 on usage or IO
-// errors.
+// Prints per-shadow SHADOW_MATCH / SHADOW_DIVERGE / SHADOW_UNPAIRED /
+// SHADOW_PENDING lines plus a SHADOW_SUMMARY; SHADOW_NO_EVIDENCE when no
+// shadow lines exist yet, SHADOW_CURRENT when every shadow already has a
+// verdict. Appends verdicts to $CREW_HOME/.dispatch-shadow-verdicts.jsonl.
+// Exit 0 on a verdict (even a diverge — divergence is evidence, not a
+// failure); exit 2 on usage or IO errors.
+//
+// Retryability: a shadow with no matching decision is left PENDING (no
+// verdict written) unless the authoritative dispatcher has provably moved
+// past its tick — i.e. a decision exists with tick_seq greater than the
+// wanted one. Each tick's dispatcher appends exactly one tick-release line
+// and then writes its decision synchronously, so a later decision proves
+// the missing one will never be written. Pending shadows are retried on
+// every later run; only provably-dead ticks become terminal UNPAIRED.
 
 import { readFileSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
@@ -104,15 +113,31 @@ if (pending.length === 0) {
   process.exit(0);
 }
 
-let matched = 0, diverged = 0, unpaired = 0;
+let matched = 0, diverged = 0, unpaired = 0, pendingCount = 0;
+// The authoritative dispatcher appends one tick-release line and then writes
+// its decision synchronously in the same step, so decision tick_seqs advance
+// monotonically and each tick gets exactly one decision write. A decision
+// with tick_seq past a shadow's wanted tick therefore proves the missing
+// decision will never be written: the owning tick already spent its single
+// write. (The release-line append and the decision write are adjacent in one
+// process; a >15min stall between them — the only out-of-order path — would
+// cost one sample, not correctness.)
+const maxDecisionTickSeq = decisions.reduce((m, d) => Math.max(m, d.tick_seq || 0), 0);
 for (const shadow of pending) {
   const wantTickSeq = (shadow.tick_seq_before || 0) + 1;
   const decision = decisions.find((d) => d.tick_seq === wantTickSeq);
 
   if (!decision) {
-    emit({ verdict: "unpaired", shadow_seq: shadow.seq, want_tick_seq: wantTickSeq });
-    console.log(`SHADOW_UNPAIRED shadow_seq=${shadow.seq} want_tick_seq=${wantTickSeq} (authoritative decision not yet written)`);
-    unpaired++;
+    if (maxDecisionTickSeq > wantTickSeq) {
+      emit({ verdict: "unpaired", shadow_seq: shadow.seq, want_tick_seq: wantTickSeq });
+      console.log(`SHADOW_UNPAIRED shadow_seq=${shadow.seq} want_tick_seq=${wantTickSeq} (authoritative dispatcher advanced to tick_seq=${maxDecisionTickSeq} without writing this decision)`);
+      unpaired++;
+    } else {
+      // The authoritative decision simply hasn't been written yet — no
+      // verdict, the shadow stays pending and a later run retries.
+      console.log(`SHADOW_PENDING shadow_seq=${shadow.seq} want_tick_seq=${wantTickSeq} (authoritative decision not yet written; retrying next run)`);
+      pendingCount++;
+    }
     continue;
   }
 
@@ -146,5 +171,5 @@ for (const shadow of pending) {
     diverged++;
   }
 }
-console.log(`SHADOW_SUMMARY matched=${matched} diverged=${diverged} unpaired=${unpaired}`);
+console.log(`SHADOW_SUMMARY matched=${matched} diverged=${diverged} unpaired=${unpaired} pending=${pendingCount}`);
 process.exit(0);

package/lib/crew-api.js

@@ -38,6 +38,57 @@ import { classifySurface } from "./classify-surface.js";
 // of crew-api.js is pinned in the workflows' pinLifecycle (PIN_BASENAMES),
 // mechanically verified by tests/pin-closure.test.js.
 import { matchTerminalPublishNote, TERMINAL_NOTE_MEANINGS, assertWritablePublishNote, assertCodeWritablePublishNote } from "./publish-note-vocabulary.js";
+// Spawn-ledger vocabularies (sandbox exit, chore pilot Piece 2, 2026-09-26):
+// the closed spawn kinds, terminal outcome vocabulary, attempt caps, and
+// transport-budget constants. These are INLINED, not imported, deliberately:
+// crew-api.js may only carry runtime-relative dependencies listed in the
+// workflows' PIN_BASENAMES (mechanically verified by tests/pin-closure.test.js),
+// and the workflow files are frozen — a new pin entry cannot be added.
+// The vocabularies are frozen by design (DESIGN-chore-pilot.md §1), so the
+// inline copy cannot drift; lib/chore/spawn-vocab.js remains the canonical
+// source for the bridge CLIs (lib/spawn-step.js, lib/reap-spawns.js).
+const SPAWN_KINDS = Object.freeze([
+  "work-agent",
+  "verdict-reask",
+  "evidence-gatherer",
+]);
+const CLOSED_OUTCOMES = Object.freeze([
+  "completed",
+  "synthetic",
+  "transport_timeout",
+  "transport_error",
+  "transport_empty",
+  "transport_parse",
+  "killed_confirmed",
+  "killed_by_reaper",
+  "orphaned_unkillable",
+  "orphaned_unverified",
+  "transport_failed",
+]);
+function isClosedOutcome(outcome) {
+  return typeof outcome === "string" && CLOSED_OUTCOMES.includes(outcome);
+}
+const TRANSPORT_FAILURE_OUTCOMES = Object.freeze([
+  "transport_timeout",
+  "transport_error",
+  "transport_empty",
+  "transport_parse",
+  "killed_confirmed",
+  "killed_by_reaper",
+  "orphaned_unkillable",
+  "orphaned_unverified",
+  "transport_failed",
+]);
+function isTransportFailureOutcome(outcome) {
+  return typeof outcome === "string" && TRANSPORT_FAILURE_OUTCOMES.includes(outcome);
+}
+const MAX_ATTEMPTS = Object.freeze({
+  "work-agent": 3,
+  "verdict-reask": 2,
+  "evidence-gatherer": 3,
+});
+const TRANSPORT_BUDGET_CAP = 5;
+const REAP_MARGIN_MS = 5 * 60 * 1000;
 
 // ---------------------------------------------------------------------------
 // Errors
@@ -272,6 +323,52 @@ function openDb(crewHome) {
     const schema = readFileSync(SCHEMA_PATH, "utf8");
     db.exec(schema);
   } else {
+    // Migration: worker_runs spawn-ledger columns (sandbox exit, chore
+    // pilot Piece 2, 2026-09-26). MUST run before db.exec(schema) below:
+    // schema.sql declares worker_runs_spawn_key_idx, and the schema exec
+    // would fail with "no such column: spawn_key" on a pre-migration
+    // database (hit live on the 0.17.2 -> ce305e9 cell upgrade, 2026-09-26).
+    // The production spawn wrapper (lib/spawn-step.js pre/post) opens and
+    // closes one worker_runs row per creative spawn (work-agent,
+    // verdict-reask, evidence-gatherer); the Step-0 reaper
+    // (lib/reap-spawns.js) derives reapability from these columns. Additive
+    // and NULL for pre-existing rows (the dispatcher rows); the 3-state
+    // status CHECK is unchanged — terminal kill states live in the result
+    // JSON's closed outcome vocabulary, never as new statuses. attempt_n
+    // is derived by count, never stored. Same idempotent PRAGMA-check
+    // pattern; never rebuilds the live table.
+    // Skip when the table doesn't exist yet (a partial/legacy database):
+    // the schema exec below creates it with all columns.
+    const workerRunsExists = db.prepare(
+      "SELECT 1 FROM sqlite_master WHERE type='table' AND name='worker_runs'"
+    ).get();
+    if (workerRunsExists) {
+    const workerRunCols = db.prepare("PRAGMA table_info(worker_runs)").all();
+    const workerRunColNames = new Set(workerRunCols.map((c) => c.name));
+    const spawnLedgerMigration = [
+      ["spawn_key", "TEXT"],
+      ["owner_tick_seq", "INTEGER"],
+      // SQLite forbids cross-column CHECKs on ADD COLUMN; the single-column
+      // form below references only the new column (same shape as the
+      // park_reason migration above).
+      ["kind", "TEXT CHECK (kind IS NULL OR kind IN ('work-agent','verdict-reask','evidence-gatherer'))"],
+      ["timeout_ms", "INTEGER"],
+      ["result", "TEXT"],
+    ];
+    for (const [colName, colType] of spawnLedgerMigration) {
+      if (!workerRunColNames.has(colName)) {
+        try {
+          db.exec(`ALTER TABLE worker_runs ADD COLUMN ${colName} ${colType}`);
+        } catch (e) {
+          // Another process may have added it concurrently; ignore duplicate-column errors.
+          if (!/duplicate column name/i.test(e.message)) throw e;
+        }
+      }
+    }
+    // The fresh schema declares worker_runs_spawn_key_idx; existing
+    // databases need it too. IF NOT EXISTS keeps the migration idempotent.
+    db.exec(`CREATE INDEX IF NOT EXISTS worker_runs_spawn_key_idx ON worker_runs (spawn_key)`);
+    }
     // Idempotent: CREATE TABLE IF NOT EXISTS covers upgrades that only add.
     const schema = readFileSync(SCHEMA_PATH, "utf8");
     db.exec(schema);
@@ -1349,6 +1446,182 @@ commands["record-worker-run"] = (db, args) => {
   return { ok: true, id: args.id, status };
 };
 
+// get-worker-run: read-only lookup of the latest worker-layer run row for
+// a task+phase (kind IS NULL — spawn-ledger rows are excluded). The chore
+// driver uses it to reuse its run-telemetry row across invocations instead
+// of opening one row per tick; a stale running row left by a killed driver
+// is reused and closed by the next invocation.
+commands["get-worker-run"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  if (!args.phase) throw usageError("phase is required.");
+  const row = db.prepare(
+    `SELECT id, task_id, phase, status, started_at, ended_at, error
+     FROM worker_runs WHERE task_id = ? AND phase = ? AND kind IS NULL
+     ORDER BY id DESC LIMIT 1`
+  ).get(args.task_id, args.phase);
+  if (!row) throw notFound("no worker run for task " + args.task_id + " phase " + args.phase + ".");
+  return { ok: true, row };
+};
+
+// Spawn ledger (sandbox exit, chore pilot Piece 2, 2026-09-26). The
+// production spawn wrapper (lib/spawn-step.js pre/post) and the Step-0
+// reaper (lib/reap-spawns.js) keep one worker_runs row per creative spawn.
+// Crew state stays behind this API: writers never touch the DB directly.
+//
+// assess-spawn-pre: read-only pre-flight for spawn-step pre — the
+// duplicate-running guard (M2), the derived attempt_n (F5: 1 + count of
+// terminal rows for task/phase/kind), and the consecutive
+// transport-failure budget for the task. Returns
+// { duplicate_running, attempt_n, max_attempts, transport_failures,
+//   budget_cap }. The caller enforces the caps; this command only reports.
+commands["assess-spawn-pre"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  if (!args.phase) throw usageError("phase is required.");
+  if (!args.kind) throw usageError("kind is required.");
+  if (!SPAWN_KINDS.includes(args.kind)) throw usageError("unknown spawn kind: " + args.kind);
+  if (!args.spawn_key) throw usageError("spawn_key is required.");
+  const dup = db.prepare(
+    "SELECT id FROM worker_runs WHERE spawn_key = ? AND status = 'running' LIMIT 1"
+  ).get(args.spawn_key);
+  const attemptCount = db.prepare(
+    `SELECT COUNT(*) AS n FROM worker_runs
+     WHERE task_id = ? AND phase = ? AND kind = ? AND status != 'running'`
+  ).get(args.task_id, args.phase, args.kind).n;
+  // Consecutive transport failures for the task, newest first: count
+  // transport-failure outcomes until a completed non-transport row resets.
+  // Running rows are in-flight, not terminal — skipped, not counted.
+  // A failed row with an unrecognized outcome counts (fail-closed: an
+  // unknown outcome is a bug, and the safe direction parks the task).
+  const history = db.prepare(
+    `SELECT status, result FROM worker_runs
+     WHERE task_id = ? AND kind IS NOT NULL AND status != 'running'
+     ORDER BY id DESC`
+  ).all(args.task_id);
+  let transportFailures = 0;
+  for (const row of history) {
+    let outcome = null;
+    try {
+      const parsed = row.result ? JSON.parse(row.result) : null;
+      outcome = parsed && typeof parsed.outcome === "string" ? parsed.outcome : null;
+    } catch (e) {
+      outcome = null;
+    }
+    if (row.status === "completed" && !isTransportFailureOutcome(outcome)) break;
+    if (isTransportFailureOutcome(outcome)) {
+      transportFailures++;
+      continue;
+    }
+    if (row.status === "failed") {
+      // Failed with a non-transport outcome (e.g. a reask row closed
+      // completed-but-unrecovered is 'completed'; a genuinely unknown
+      // failed outcome is a bug) — count fail-closed, except the
+      // verdict-reask terminal failures which are explicitly counted.
+      transportFailures++;
+      continue;
+    }
+    // Completed with a transport outcome (should not happen — completed
+    // rows carry completed/synthetic) — count it; the writer is buggy.
+    transportFailures++;
+  }
+  return {
+    ok: true,
+    duplicate_running: !!dup,
+    duplicate_row_id: dup ? dup.id : null,
+    attempt_n: attemptCount + 1,
+    max_attempts: MAX_ATTEMPTS[args.kind],
+    transport_failures: transportFailures,
+    budget_cap: TRANSPORT_BUDGET_CAP,
+  };
+};
+
+// record-spawn-open: opens the ledger row. Validates the frozen kind and
+// re-checks the duplicate-running guard inside the same call (race safety:
+// two pres for the same key cannot both open). Returns { ok, id } or
+// { refused: "duplicate_running", row_id }.
+commands["record-spawn-open"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  if (!args.phase) throw usageError("phase is required.");
+  if (!args.spawn_key) throw usageError("spawn_key is required.");
+  if (!SPAWN_KINDS.includes(args.kind)) throw usageError("unknown spawn kind: " + args.kind);
+  if (!Number.isInteger(args.owner_tick_seq) || args.owner_tick_seq <= 0) {
+    throw usageError("owner_tick_seq must be a positive integer.");
+  }
+  if (!Number.isInteger(args.timeout_ms) || args.timeout_ms <= 0) {
+    throw usageError("timeout_ms must be a positive integer.");
+  }
+  const dup = db.prepare(
+    "SELECT id FROM worker_runs WHERE spawn_key = ? AND status = 'running' LIMIT 1"
+  ).get(args.spawn_key);
+  if (dup) return { ok: false, refused: "duplicate_running", row_id: dup.id };
+  const row = db.prepare(
+    `INSERT INTO worker_runs (task_id, phase, executor, status, spawn_key, owner_tick_seq, kind, timeout_ms)
+     VALUES (?, ?, 'worker', 'running', ?, ?, ?, ?) RETURNING id`
+  ).get(args.task_id, args.phase, args.spawn_key, args.owner_tick_seq, args.kind, args.timeout_ms);
+  return { ok: true, id: row.id, status: "running" };
+};
+
+// record-spawn-close: closes the ledger row with the typed result. The
+// closed outcome vocabulary is enforced here fail-closed (K3: both writers
+// go through this command, and validate before calling). Terminal rows are
+// immutable — a close against an already-terminal row is a reported no-op.
+commands["record-spawn-close"] = (db, args) => {
+  if (args.id === undefined || args.id === null) throw usageError("id is required to close a spawn row.");
+  if (!["completed", "failed"].includes(args.status)) {
+    throw usageError("status must be completed or failed.");
+  }
+  let outcome = null;
+  let resultJson = null;
+  if (args.result !== undefined && args.result !== null) {
+    const resultObj = typeof args.result === "string" ? JSON.parse(args.result) : args.result;
+    outcome = resultObj && typeof resultObj.outcome === "string" ? resultObj.outcome : null;
+    if (!isClosedOutcome(outcome)) {
+      throw usageError("result.outcome must be in the closed outcome vocabulary; got: " + outcome);
+    }
+    resultJson = JSON.stringify(resultObj);
+  } else {
+    throw usageError("result (with a closed-vocabulary outcome) is required to close a spawn row.");
+  }
+  const result = db.prepare(
+    `UPDATE worker_runs SET status = ?, error = ?, result = ?, ended_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+     WHERE id = ? AND status = 'running'`
+  ).run(args.status, args.error || null, resultJson, args.id);
+  if (result.changes === 0) return { ok: true, noop: true };
+  return { ok: true, id: args.id, status: args.status, outcome };
+};
+
+// list-reapable-spawns: the Step-0 reaper's candidate set — rows still
+// 'running' past timeout_ms + REAP_MARGIN_MS. (The design's owner_ended_at
+// fast path needs a ticks table that does not exist; the timeout clause
+// alone is correct and fail-closed — reaping is deferred, never early.)
+commands["list-reapable-spawns"] = (db, args) => {
+  const marginMs = Number.isInteger(args.reap_margin_ms) && args.reap_margin_ms >= 0
+    ? args.reap_margin_ms
+    : REAP_MARGIN_MS;
+  const rows = db.prepare(
+    `SELECT id, task_id, phase, spawn_key, owner_tick_seq, kind, timeout_ms, started_at
+     FROM worker_runs
+     WHERE status = 'running' AND kind IS NOT NULL
+       AND (julianday('now') - julianday(started_at)) * 86400000 > timeout_ms + ?
+     ORDER BY id`
+  ).all(marginMs);
+  return { ok: true, spawns: rows, reap_margin_ms: marginMs };
+};
+
+// get-spawn-row: fetch one ledger row by id or spawn_key (spawn-step post
+// locates the row for the session's key; the reaper reads rows it reaps).
+commands["get-spawn-row"] = (db, args) => {
+  let row = null;
+  if (args.id !== undefined && args.id !== null) {
+    row = db.prepare("SELECT * FROM worker_runs WHERE id = ?").get(args.id);
+  } else if (args.spawn_key) {
+    row = db.prepare("SELECT * FROM worker_runs WHERE spawn_key = ? ORDER BY id DESC LIMIT 1").get(args.spawn_key);
+  } else {
+    throw usageError("id or spawn_key is required.");
+  }
+  if (!row) throw notFound("spawn row not found.");
+  return { ok: true, row };
+};
+
 commands["get-run-timeline"] = (db, args) => {
   if (!args.run_id && !args.task_id) throw usageError("run_id or task_id is required.");
   let runs;