toolroll 0.5.0

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "toolroll",
+  "version": "0.5.0",
+  "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/browser-build.mjs && node scripts/postbuild.mjs",
+    "test": "vitest run",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.browser.json",
+    "certify:provider": "npm run build && node scripts/provider-canary.mjs",
+    "certify:recovery": "npm run build && node scripts/recovery-canary.mjs",
+    "certify:crash": "npm run build && node scripts/crash-canary.mjs",
+    "certify:pilot": "npm run build && node scripts/pilot.mjs",
+    "prepublishOnly": "npm run typecheck && npm run build",
+    "nul-scan": "node scripts/nul-scan.mjs",
+    "proof-preflight": "node scripts/proof-preflight.mjs",
+    "fixture:v47": "node scripts/derive-v47-fixture.mjs",
+    "build:desktop": "node scripts/build-desktop.mjs",
+    "certify:restart": "npm run build && node scripts/restart-certification.mjs",
+    "certify:launchd": "npm run build && node scripts/launchd-certification.mjs",
+    "test:native-containment": "vitest run src/containment-native.test.ts src/containment.test.ts",
+    "build:browser": "node scripts/browser-build.mjs",
+    "e2e:flows": "npm run build && node scripts/flows-e2e.mjs",
+    "e2e:app": "npm run build && node scripts/app-e2e.mjs",
+    "e2e:app:parallel": "npm run build && node scripts/e2e-parallel.mjs scripts/app-e2e.mjs",
+    "e2e": "npm run build && node scripts/flows-e2e.mjs && node scripts/app-e2e.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ap9000/toolroll.git"
+  },
+  "keywords": [
+    "agents",
+    "orchestration",
+    "claude-code",
+    "codex",
+    "git-worktree",
+    "ai-agents",
+    "autonomous-agents",
+    "agent-orchestration",
+    "control-plane",
+    "cli",
+    "task-queue",
+    "llm",
+    "openrouter",
+    "telegram",
+    "unattended"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/ap9000/toolroll/issues"
+  },
+  "homepage": "https://github.com/ap9000/toolroll#readme",
+  "bin": {
+    "toolroll": "dist/bin.js",
+    "standing-orders": "dist/bin.js"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "4.3.3",
+    "@types/mailparser": "3.4.6",
+    "@types/node": "26.2.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "esbuild": "0.28.2",
+    "happy-dom": "20.12.0",
+    "tailwindcss": "4.3.3",
+    "tsx": "4.23.12",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "files": [
+    "dist",
+    "scripts/provider-canary.mjs",
+    "scripts/canary-assertions.mjs",
+    "scripts/recovery-canary.mjs",
+    "scripts/crash-canary.mjs",
+    "scripts/fixtures/crash-process.mjs",
+    "scripts/pilot.mjs",
+    "scripts/fixtures/pilot-scenarios.mjs",
+    "scripts/proof-preflight.mjs",
+    "scripts/restart-certification.mjs",
+    "scripts/launchd-certification.mjs",
+    "scripts/fixtures/restart-service.mjs",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "dependencies": {
+    "@radix-ui/react-collapsible": "1.1.20",
+    "@radix-ui/react-dialog": "1.1.23",
+    "@radix-ui/react-dropdown-menu": "2.1.24",
+    "@radix-ui/react-label": "2.1.15",
+    "@radix-ui/react-radio-group": "1.4.7",
+    "@radix-ui/react-select": "2.3.7",
+    "@radix-ui/react-separator": "1.1.15",
+    "@radix-ui/react-slot": "1.3.3",
+    "@radix-ui/react-switch": "1.3.7",
+    "@radix-ui/react-tabs": "1.1.21",
+    "@radix-ui/react-tooltip": "1.2.16",
+    "@slack/socket-mode": "3.0.1",
+    "@xyflow/react": "12.11.6",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "discord.js": "14.27.0",
+    "imapflow": "2.0.6",
+    "lucide-react": "1.47.0",
+    "mailparser": "3.9.28",
+    "nodemailer": "10.0.10",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "sonner": "2.0.8",
+    "tailwind-merge": "3.7.0",
+    "typescript-parser": "npm:typescript@6.0.3",
+    "use-stick-to-bottom": "1.1.6",
+    "yaml": "2.9.1"
+  }
+}

package/scripts/canary-assertions.mjs

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import { writeFileSync } from "node:fs";
+
+/** Disposable certification projects use the same scoped lead and public CLI
+ * as a real agent. The token stays in a private file, outside the certificate. */
+export async function createFixtureLead(cli, { repo, auth, tokenFile }) {
+  const created = await cli(["coordinator", "mint", "certification-lead", "--repo", repo, ...auth]);
+  assert.equal(typeof created.token, "string", "missing scoped lead credential");
+  writeFileSync(tokenFile, created.token, { mode: 0o600, flag: "wx" });
+  return tokenFile;
+}
+
+export function assertReadyAssignment(assignment, expected = {}) {
+  assert.equal(assignment?.state, "ready-to-check", "finished work must be Ready for its lead");
+  assert(assignment.receipt, "the exact saved result is missing");
+  assert.match(assignment.receipt.digest, /^[a-f0-9]{64}$/, "the result has no exact receipt");
+  assert.equal(assignment.receipt.checks.status, "passed", "the approved project check did not pass");
+  assert.equal(assignment.receipt.checks.exitCode, 0);
+  if (expected.head !== undefined) assert.equal(assignment.receipt.head, expected.head, "wrong candidate");
+  if (expected.runId !== undefined) assert.equal(assignment.receipt.runId, expected.runId, "wrong result");
+}
+
+/** Call only after the fixture's actual output and changes were inspected.
+ * Completing a receipt must retain check outcomes and cannot execute work. */
+export async function completeFixtureAssignment(cli, task, tokenFile, expected = {}) {
+  const auth = ["--token-file", tokenFile];
+  await cli(["assignment", "claim", task, ...auth]);
+  const ready = (await cli(["assignment", "show", task, ...auth])).result;
+  assertReadyAssignment(ready, expected);
+  const before = await cli(["task", "show", task]);
+  const complete = (await cli(["assignment", "check", task, "--digest", ready.receipt.digest, ...auth])).result;
+  assert.equal(complete.state, "complete");
+  assert.equal(complete.completion.digest, ready.receipt.digest);
+  assert.deepEqual(complete.receipt, ready.receipt, "completion changed the saved work or checks");
+  const repeated = (await cli(["assignment", "check", task, "--digest", ready.receipt.digest, ...auth])).result;
+  assert.deepEqual(repeated.completion, complete.completion, "repeated completion was not idempotent");
+  const after = await cli(["task", "show", task]);
+  assert.deepEqual(after.runs, before.runs, "marking Complete executed or rewrote a run");
+  assert.deepEqual(after.proofMatrix, before.proofMatrix, "marking Complete rewrote assessment history");
+  assert.equal(after.proofVerdict, before.proofVerdict, "marking Complete changed check/assessment outcome");
+  return { state: complete.state, runId: complete.receipt.runId, head: complete.receipt.head, checks: complete.receipt.checks, digest: complete.receipt.digest };
+}

package/scripts/crash-canary.mjs

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+/** Kill actual CLI workers at real process barriers; no clock injection or model calls.
+ * Recovery retains the original work, then exposes Ready for explicit lead completion. */
+import assert from "node:assert/strict";
+import { spawn, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, mkdtempSync, realpathSync, readdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { DatabaseSync } from "node:sqlite";
+import { createFixtureLead, completeFixtureAssignment } from "./canary-assertions.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const fixture = join(root, "scripts/fixtures/crash-process.mjs");
+const bin = join(root, "dist/bin.js");
+const stages = ["planning", "setup", "building", "after-commit", "verification"];
+let selected = stages;
+let rounds = 1;
+let concurrency = 6;
+let stopBeforeCrash = false;
+let autoApprove = false;
+let output = resolve("output/certification/crash.json");
+for (let i = 2; i < process.argv.length; i++) {
+  const arg = process.argv[i];
+  if (arg === "--stage") selected = [process.argv[++i]];
+  else if (arg === "--rounds") rounds = Number(process.argv[++i]);
+  else if (arg === "--concurrency") concurrency = Number(process.argv[++i]);
+  else if (arg === "--stop-before-crash") stopBeforeCrash = true;
+  else if (arg === "--auto-approve") autoApprove = true;
+  else if (arg === "--output") output = resolve(process.argv[++i]);
+  else if (arg === "--help") { console.log("npm run certify:crash -- [--stage planning|setup|building|after-commit|verification] [--auto-approve (planning only)] [--stop-before-crash (building only)] [--rounds 1] [--concurrency 6] [--output file]"); process.exit(0); }
+  else throw new Error(`unknown argument ${arg}`);
+}
+assert(process.platform !== "win32", "SIGKILL fixture requires macOS or Linux; physical Windows remains a separate gate");
+assert(selected.every(stage => stages.includes(stage)) && Number.isInteger(rounds) && rounds >= 1 && rounds <= 20, "invalid stages/rounds");
+assert(Number.isInteger(concurrency) && concurrency >= 1 && concurrency <= 20, "concurrency is 1..20");
+assert(!stopBeforeCrash || selected.length === 1 && selected[0] === "building", "--stop-before-crash requires --stage building");
+assert(!autoApprove || selected.length === 1 && selected[0] === "planning", "--auto-approve requires --stage planning");
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const base = realpathSync(mkdtempSync(join(tmpdir(), "standing-orders-crash-canary-")));
+const gitBinary = execFileSync("/bin/sh", ["-c", "command -v git"], { encoding: "utf8" }).trim();
+const revision = execFileSync(gitBinary, ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+const hash = () => {
+  const h = createHash("sha256");
+  const visit = path => { for (const name of readdirSync(path, { withFileTypes: true }).sort((a,b) => a.name.localeCompare(b.name))) {
+    const p = join(path, name.name); if (name.isDirectory()) visit(p); else h.update(p.slice(root.length)).update(readFileSync(p));
+  }};
+  visit(join(root, "dist"));
+  for (const file of ["scripts/crash-canary.mjs", "scripts/fixtures/crash-process.mjs", "scripts/canary-assertions.mjs", "package.json"]) h.update(file).update(readFileSync(join(root, file)));
+  return h.digest("hex");
+};
+const runtime = hash();
+const started = Date.now();
+const cases = [];
+const children = new Set();
+const alive = pid => { try { process.kill(pid, 0); return true; } catch { return false; } };
+function start(args, options) {
+  const child = spawn(process.execPath, [bin, ...args], { ...options, stdio: ["ignore", "pipe", "pipe"] });
+  children.add(child);
+  let stdout = "", stderr = "";
+  child.stdout.on("data", c => { stdout += c; }); child.stderr.on("data", c => { stderr += c; });
+  const done = new Promise((resolvePromise, reject) => { child.on("error", reject); child.on("close", (code, signal) => { children.delete(child); resolvePromise({ code, signal, stdout, stderr }); }); });
+  return { child, done };
+}
+async function until(predicate, ms, label) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { const value = predicate(); if (value) return value; await sleep(25); }
+  throw new Error(`timed out waiting for ${label}`);
+}
+async function one(stage, round) {
+  const dir = join(base, `${stage}-${round}`); mkdirSync(dir);
+  const repo = join(dir, "repo"), control = join(dir, "control"), tools = join(dir, "bin"), home = join(dir, "home");
+  for (const path of [repo, control, tools, home]) mkdirSync(path);
+  const db = join(dir, "orders.db"), pool = join(dir, "pool");
+  const quote = s => "'" + s.replaceAll("'", "'\\''") + "'";
+  // The approved commands are short wrappers in the control directory: a
+  // proof's check ref is capped at 300 bytes, and the literal node + fixture
+  // + control path exceeds that from a long checkout. `exec` keeps the
+  // fixture's own pid as the checkpoint process.
+  const wrapper = (name, kind) => {
+    const path = join(tools, name);
+    writeFileSync(path, `#!/bin/sh\nexec ${quote(process.execPath)} ${quote(fixture)} ${kind} ${quote(control)} "$@"\n`);
+    chmodSync(path, 0o700);
+    return quote(path);
+  };
+  const check = wrapper("check", "check");
+  const acceptance = [
+    { id: "c1", statement: "The result file contains recovered and a newline.", evidence: ["changed-path"] },
+    { id: "c2", statement: "The approved check passes.", evidence: ["check"] },
+  ];
+  writeFileSync(join(control, "config.json"), JSON.stringify({ stage, check, git: gitBinary, acceptance }));
+  for (const kind of ["claude", "git"]) {
+    const path = join(tools, kind);
+    writeFileSync(path, `#!${process.execPath}\nprocess.env.SO_CRASH_KIND=${JSON.stringify(kind)}; await import(${JSON.stringify(fixture)});\n`);
+    chmodSync(path, 0o700);
+  }
+  const env = { PATH: `${tools}:${process.env.PATH}`, HOME: home, XDG_CONFIG_HOME: join(home, ".config"), TMPDIR: dir, SO_CRASH_CONTROL: control, NO_COLOR: "1" };
+  const opts = { cwd: repo, env };
+  const git = args => execFileSync(gitBinary, args, { cwd: repo, env, encoding: "utf8" }).trim();
+  git(["init", "-q", "-b", "main"]); git(["config", "user.email", "fixture@example.invalid"]); git(["config", "user.name", "Crash Fixture"]);
+  writeFileSync(join(repo, "README.md"), "Disposable crash fixture.\n"); git(["add", "."]); git(["commit", "-qm", "seed"]);
+  const cli = async (args, accepted = [0]) => {
+    const result = await start([...args, "--db", db, "--json"], opts).done;
+    assert(accepted.includes(result.code), `${args.slice(0,2).join(" ")}: ${result.stdout} ${result.stderr}`);
+    return JSON.parse(result.stdout);
+  };
+  const rows = sql => { const c = new DatabaseSync(db, { readOnly: true }); try { return c.prepare(sql).all(); } finally { c.close(); } };
+  const events = () => existsSync(join(control,"events.jsonl")) ? readFileSync(join(control,"events.jsonl"),"utf8").trim().split("\n").filter(Boolean).map(x => JSON.parse(x)) : [];
+  const record = { stage, round, passed: false, checks: {}, retainedAt: dir };
+  let worker, successor, checkpoint;
+  try {
+    await cli(["approver", "add", "fixture", "--password", "fixture-only-password"]);
+    const auth = ["--as", "fixture", "--token", "fixture-only-password"];
+    const registered = await cli(["runner", "register", "worker", "--repo", repo, ...auth]);
+    writeFileSync(join(control,"token"), registered.token, { mode: 0o600 });
+    for (const phase of ["plan", "build", "repair"]) await cli(["config", "set", phase, "--provider", "claude", "--model", "fixture", ...auth]);
+    await cli(["verify", "set", "--repo", repo, "--command", check, "--timeout-seconds", "240", "--yes", ...auth]);
+    if (stage === "setup") await cli(["setup", "set", "--repo", repo, "--command", wrapper("setup", "setup"), "--timeout-seconds", "240", "--yes", ...auth]);
+    await cli(["task", "add", "Write result.txt containing recovered and a newline.", "--id", "work", "--repo", repo]);
+    if (stage === "planning") {
+      if (autoApprove) {
+        await cli(["mode", "set", "--repo", repo, "--name", "standard", "--days", "1", "--auto-approve", "true", "--plan-auto", ...auth]);
+        await cli(["task", "scope", "work", "--goal", "Write the result and verify it.", "--not", "No publication.", "--touches", "result.txt", "--acceptance", acceptance.map(c => `${c.statement}|${c.evidence.join(",")}`).join(";")]);
+        const filed = await cli(["task", "show", "work"]);
+        assert.equal(filed.scope.approvedAt, null);
+        record.checks.filedScopeDigest = filed.scope.digest;
+      }
+      const requested = await cli(["task", "plan", "work", "--provider", "claude", "--model", "fixture", ...auth]);
+      if (autoApprove) assert.equal(requested.autoPlan, true);
+    } else {
+      await cli(["task", "scope", "work", "--goal", "Write the result and verify it.", "--acceptance", acceptance.map(c => `${c.statement}|${c.evidence.join(",")}`).join(";")]);
+      const preview = await cli(["task", "show", "work"]);
+      await cli(["task", "approve", "work", "--yes", "--digest", preview.scope.digest, ...auth]);
+    }
+    const workerArgs = ["watch", "--runner", "worker", "--token-file", join(control,"token"), "--repo", repo, "--pool", pool, "--tick-every", "200", "--reconcile-every", "500", "--bridge-every", "3600000", "--stop-grace", "1000", "--db", db, "--json"];
+    worker = start([...workerArgs, "--for", "180000"], opts);
+    worker.done.then(result => writeFileSync(join(control,"worker-result.json"), JSON.stringify(result)));
+    checkpoint = await until(() => existsSync(join(control,"checkpoint.json")) && JSON.parse(readFileSync(join(control,"checkpoint.json"),"utf8")), 25000, `${stage} checkpoint`);
+    record.checks.checkpoint = checkpoint;
+    record.checks.preCrashRuns = rows("SELECT id,role,phase,outcome FROM run");
+    if (["after-commit", "verification"].includes(stage)) record.checks.committedBeforeCrash = execFileSync(gitBinary, ["rev-parse", "HEAD"], { cwd: checkpoint.cwd, encoding: "utf8" }).trim();
+    if (stopBeforeCrash) {
+      // Freeze only the known worker handle: the independent provider keeps
+      // writing, while the public CLI can save stop intent in SQLite. The
+      // worker cannot observe or act on the stop before the deliberate crash.
+      worker.child.kill("SIGSTOP");
+      const target = record.checks.preCrashRuns.find(run => run.role === "builder" && run.outcome === null);
+      assert(target, "no exact builder attempt at checkpoint");
+      record.checks.stopTarget = target.id;
+      await cli(["task", "stop", "work", "--run", String(target.id), ...auth]);
+      assert.equal(rows("SELECT settled_at FROM run_stop")[0]?.settled_at, null, "an unobserved stop was already called settled");
+    }
+    worker.child.kill("SIGKILL");
+    const killed = await worker.done;
+    assert.equal(killed.signal, "SIGKILL");
+    record.checks.workerKilled = true;
+    record.checks.childSurvived = alive(checkpoint.pid);
+    assert(record.checks.childSurvived, "external checkpoint process did not survive the worker");
+    if (stage === "after-commit") writeFileSync(join(control,"released"), "commit subprocess already finished its write\n");
+    const lease = rows("SELECT expires_at FROM watch_lease")[0];
+    const busy = await start([...workerArgs, "--for", "100"], opts).done;
+    assert.equal(JSON.parse(busy.stdout).reason, "watch-busy");
+    record.checks.beforeExpiry = "refused";
+    console.log(`${stage}/${round}: worker killed; waiting for its real watch lease to expire`);
+    while (Date.now() <= Date.parse(lease.expires_at) + 100) await sleep(Math.min(1000, Date.parse(lease.expires_at) + 110 - Date.now()));
+    // Leave the external process alive during takeover: expiry must never
+    // by itself grant a second writer access to that checkout.
+    successor = start([...workerArgs, "--for", "800"], opts);
+    const probe = await Promise.race([successor.done, sleep(6000).then(() => null)]);
+    if (probe === null) { successor.child.kill("SIGTERM"); await successor.done; }
+    writeFileSync(join(control,"takeover-result.json"), JSON.stringify(await successor.done));
+    record.checks.overlappingWriters = events().filter(e => e.name === "overlapping-writer");
+    if (stopBeforeCrash) {
+      assert(alive(checkpoint.pid), "orphan must remain live while testing recovery");
+      assert.equal(rows("SELECT settled_at FROM run_stop")[0]?.settled_at, null, "dead worker was mistaken for dead provider");
+      const refused = await cli(["task", "resume", "work", "--run", String(record.checks.stopTarget), ...auth], [3]);
+      assert.equal(refused.ok, false, "resume admitted work over the live orphan");
+      record.checks.resumeWhileOrphanLives = refused.reason;
+      assert.equal(rows("SELECT resumed_at FROM run_stop")[0]?.resumed_at, null);
+    }
+    writeFileSync(join(control,"released"), "release fixture process\n");
+    await until(() => !alive(checkpoint.pid), 5000, `${stage} external process exit`);
+    const before = await cli(["task", "show", "work"]);
+    record.checks.afterTakeover = { state: before.task.state, dispatch: before.dispatch, runs: before.runs.map(r => ({ id:r.id,role:r.role,outcome:r.outcome,reason:r.reason })) };
+    if (stopBeforeCrash) {
+      // A normal recovery pass can now establish quiescence. Only the
+      // operator's subsequent exact-attempt resume clears the stop hold.
+      writeFileSync(join(control,"quiescent-recovery.json"), JSON.stringify(await start([...workerArgs, "--for", "800"], opts).done));
+      await cli(["task", "resume", "work", "--run", String(record.checks.stopTarget), ...auth]);
+      assert.notEqual(rows("SELECT resumed_at FROM run_stop")[0]?.resumed_at, null);
+    }
+    writeFileSync(join(control,"recovery-result.json"), JSON.stringify(await start([...workerArgs, "--for", autoApprove ? "15000" : "2500"], opts).done));
+    let after = await cli(["task", "show", "work"]);
+    const runsBeforeDuplicate = rows("SELECT id FROM run ORDER BY id");
+    const duplicate = await cli(["tick", "--runner", "worker", "--token", registered.token, "--repo", repo, "--pool", pool], [3]);
+    assert.equal(duplicate.reason, stage === "planning" && !autoApprove ? "nothing-dispatched" : "empty");
+    assert.deepEqual(rows("SELECT id FROM run ORDER BY id"), runsBeforeDuplicate);
+    record.checks.duplicateDispatch = stage === "planning" && !autoApprove ? "refused-unapproved" : "refused-empty";
+    if (autoApprove) {
+      assert.equal(after.scope.digest, record.checks.filedScopeDigest);
+      assert.equal(after.scope.approvedDigest, record.checks.filedScopeDigest);
+      assert.equal(after.scope.approvalBasis, "mode");
+      assert.equal(after.task.state, "done");
+      const approvals = rows("SELECT action,outcome FROM action_ledger WHERE action='plan auto-approval'");
+      assert.deepEqual(approvals.map(row => row.outcome), ["approved"]);
+      record.checks.autoApproval = { approvals, humanActionsAfterPlanningStarted: 0, criteria: after.proofMatrix };
+    }
+    record.checks.final = { state: after.task.state, scope: !!after.scope, proof: after.proofVerdict, dispatch: after.dispatch,
+      runs: after.runs.map(r => ({ id:r.id, role:r.role, outcome:r.outcome, reason:r.reason, parent:r.parentRun, head:r.headRevision })) };
+    record.checks.events = events();
+    record.checks.openRuns = rows("SELECT id,role FROM run WHERE outcome IS NULL");
+    const failures = [];
+    if (record.checks.overlappingWriters.length) failures.push("a successor provider started while an earlier writer still lived");
+    if (record.checks.openRuns.length) failures.push("interrupted runs remain open after restart");
+    if (stage === "planning" && !after.scope) failures.push("the interrupted planning request did not resume");
+    if (stage !== "planning" && after.task.state !== "done") failures.push("the preserved draft/commit did not finish");
+    if (stage !== "planning" || autoApprove) {
+      const finalHead = execFileSync(gitBinary, ["rev-parse", "standing-orders/work"], { cwd: repo, encoding: "utf8" }).trim();
+      assert.equal(execFileSync(gitBinary, ["show", `${finalHead}:result.txt`], { cwd: repo, encoding: "utf8" }), "recovered\n");
+      assert.equal(events().filter(e => e.name === "commit").length, 1, "recovery must not create a duplicate commit");
+      if (record.checks.committedBeforeCrash) assert.equal(finalHead, record.checks.committedBeforeCrash, "recovery must retain the original commit");
+      record.checks.finalHead = finalHead;
+      const build = after.runs.find(run => run.role === "builder" && run.headRevision === finalHead && run.outcome !== null);
+      assert(build, "the retained candidate has no finished builder");
+      const leadFile = await createFixtureLead(cli, { repo, auth, tokenFile: join(control, "lead.token") });
+      record.checks.completion = await completeFixtureAssignment(cli, "work", leadFile, { head: finalHead, runId: build.id });
+      assert.equal(after.runs.filter(run => run.role === "reviewer").length, 0, "recovery started a retired reviewer");
+    }
+    record.failures = failures;
+    record.passed = failures.length === 0;
+  } catch (error) { record.error = error.stack; }
+  finally {
+    writeFileSync(join(control,"released"), "fixture cleanup\n");
+    for (const handle of [worker,successor]) if (handle && handle.child.exitCode === null && handle.child.signalCode === null) { handle.child.kill("SIGKILL"); await handle.done; }
+    if (checkpoint && alive(checkpoint.pid)) { try { process.kill(checkpoint.pid,"SIGKILL"); } catch {} }
+    writeFileSync(join(dir,"result.json"), JSON.stringify(record,null,2));
+  }
+  cases.push(record);
+  console.log(`${stage}/${round}: ${record.passed ? "PASS" : "FAIL"} ${record.failures?.join("; ") ?? record.error?.split("\n")[0] ?? ""}`);
+}
+const pending = Array.from({ length: rounds }, (_, i) => selected.map(stage => ({ stage, round: i + 1 }))).flat();
+await Promise.all(Array.from({ length: Math.min(concurrency, pending.length) }, async () => {
+  while (pending.length) { const next = pending.shift(); await one(next.stage, next.round); }
+}));
+const certificate = { version:1, passed: cases.every(c=>c.passed) && hash()===runtime, sourceCommit:revision, runtimeSha256:runtime, runtimeUnchanged:hash()===runtime,
+  stopBeforeCrash, autoApprove,
+  platform:process.platform, node:process.versions.node, durationSeconds:(Date.now()-started)/1000, cases, retainedAt:base,
+  scope:"Actual public-CLI watch processes killed with SIGKILL at deterministic planning, setup, build, commit and verification checkpoints; normal 90-second lease expiry; real git, SQLite, subprocesses and successor watch. Ready work is explicitly inspected and marked Complete without another provider run or rewriting checks. Provider responses are fixtures, not model calls.",
+  exclusions:["real-provider recovery", "Windows", "reboot", "detached descendants", "power-loss filesystem durability"] };
+mkdirSync(dirname(output), { recursive:true }); writeFileSync(output, JSON.stringify(certificate,null,2)+"\n");
+console.log(`Certificate: ${output}`);
+if (!certificate.passed) process.exitCode=1;

package/scripts/fixtures/crash-process.mjs

@@ -0,0 +1,74 @@
+/** Deterministic external processes for the real CLI crash harness. Never calls a model. */
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+const kind = process.env.SO_CRASH_KIND ?? process.argv[2];
+const control = process.env.SO_CRASH_CONTROL ?? process.argv[3];
+if (!control) throw new Error("This process only runs inside a crash fixture.");
+const config = JSON.parse(readFileSync(join(control, "config.json"), "utf8"));
+const event = (name, data = {}) => appendFileSync(join(control, "events.jsonl"), JSON.stringify({ name, pid: process.pid, at: Date.now(), cwd: process.cwd(), ...data }) + "\n");
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const alive = pid => { try { process.kill(pid, 0); return true; } catch { return false; } };
+const checkpoint = async (stage, writer = false) => {
+  if (stage !== config.stage || existsSync(join(control, "released"))) return;
+  writeFileSync(join(control, "checkpoint.json"), JSON.stringify({ stage, pid: process.pid, cwd: process.cwd(), at: Date.now() }));
+  while (!existsSync(join(control, "released"))) {
+    if (writer) writeFileSync(join(process.cwd(), "result.txt"), "recovered\n");
+    await sleep(25);
+  }
+};
+if (kind === "git") {
+  const args = process.argv.slice(2);
+  const result = spawnSync(config.git, args, { stdio: "inherit" });
+  if (result.error) throw result.error;
+  if (result.status === 0 && args[0] === "commit") {
+    event("commit");
+    await checkpoint("after-commit");
+  }
+  process.exit(result.status ?? 1);
+}
+if (kind === "check" || kind === "setup") {
+  event(`${kind}-start`);
+  await checkpoint(kind === "check" ? "verification" : "setup", true);
+  if (kind === "check" && readFileSync("result.txt", "utf8") !== "recovered\n") process.exit(1);
+  event(`${kind}-end`);
+  console.log("fixture check passed");
+  process.exit(0);
+}
+const args = process.argv.slice(2);
+if (args.includes("--version")) { console.log("crash-fixture (not a real provider)"); process.exit(0); }
+const prompt = args[args.indexOf("-p") + 1] ?? "";
+const session = args.includes("--resume") ? args[args.indexOf("--resume") + 1] : randomUUID();
+const output = event => console.log(JSON.stringify(event));
+output({ type: "system", subtype: "init", session_id: session });
+const speak = value => output({ type: "result", subtype: "success", is_error: false, session_id: session, result: typeof value === "string" ? value : JSON.stringify(value), num_turns: 1 });
+const phase = /STANDING-ORDERS-DONE-[a-f0-9]{16}\.json/.test(prompt) ? "build" : "plan";
+const initial = existsSync(join(control, "checkpoint.json")) ? JSON.parse(readFileSync(join(control, "checkpoint.json"), "utf8")) : null;
+if (["build", "plan"].includes(phase) && initial !== null && initial.pid !== process.pid && !existsSync(join(control, "released")) && alive(initial.pid)) {
+  event("overlapping-writer", { original: initial.pid, stage: initial.stage });
+}
+event("provider-start", { phase, session });
+if (phase === "plan") {
+  await checkpoint("planning");
+  const file = /STANDING-ORDERS-PLAN-[a-f0-9]{16}\.json/.exec(prompt)?.[0];
+  if (!file) throw new Error("Missing plan nonce");
+  writeFileSync(file, JSON.stringify({ goal: "Write the result and verify it.", outOfScope: "No publication.", touches: ["result.txt"], acceptance: config.acceptance,
+    plan: "## Approach\nWrite the result.\n## Milestones\n- Write result.txt.\n## Dependencies\n- None.\n## Risks\n- Interrupted work.\n## Proof\n- c1: Inspect result.txt.\n- c2: Run the approved check." }));
+  speak("Plan prepared.");
+} else {
+  const path = "result.txt";
+  const existed = existsSync(path);
+  if (!existed) writeFileSync(path, "recovered\n");
+  await checkpoint("building", true);
+  const rubricFile = /STANDING-ORDERS-RUBRIC-[a-f0-9]{16}\.json/.exec(prompt)?.[0];
+  const rubric = JSON.parse(readFileSync(rubricFile, "utf8"));
+  const proofFile = /STANDING-ORDERS-PROOF-[a-f0-9]{16}\.json/.exec(prompt)?.[0];
+  const doneFile = /STANDING-ORDERS-DONE-[a-f0-9]{16}\.json/.exec(prompt)?.[0];
+  const tracked = spawnSync(config.git, ["ls-files", "--error-unmatch", path], { encoding: "utf8" }).status === 0;
+  writeFileSync(proofFile, JSON.stringify({ version: 1, criteria: rubric.map(one => ({ id: one.id, statement: one.statement, verdict: "met", how: "Fixture result and approved check.", evidence: one.evidence.map(kind => ({ kind, ref: kind === "check" ? config.check : path })) })), checks: [{ command: config.check, exitCode: 0, summary: "Fixture expectation; the worker independently runs this command." }], changed: [path], screenshots: [], caveats: [] }));
+  writeFileSync(doneFile, JSON.stringify({ version: 2, status: existed && tracked ? "no-change" : "completed", conclusion: "The requested result is present.", changes: ["result.txt contains recovered."], verification: [], followUps: [] }));
+  speak("Fixture finished.");
+}
+event("provider-end", { phase });

package/scripts/fixtures/pilot-scenarios.mjs

@@ -0,0 +1,85 @@
+/** Fixed, reproducible pilot assignments. Verification files are outside the allowed change set. */
+export const scenarioIds = ['pagination', 'dedupe', 'catalog', 'endpoint', 'dependency-format', 'dependency-sort', 'revision-csv', 'revision-config', 'ui-filter', 'ui-form'];
+const prelude = `import assert from 'node:assert/strict';\n`;
+const success = `\nconsole.log('PASS: every specified behavior and edge case was checked');\n`;
+export function scenario(id, playwright) {
+  const cases = {
+    pagination: {
+      category: 'backend bug', paths: ['paginate.js'],
+      goal: 'Fix paginate(items, offset, limit): offset defaults to 0 and limit defaults to 10, zero limit returns [], clamp negative offset to zero, return a slice without mutating items.',
+      files: { 'paginate.js': 'export const paginate = (items, offset, limit) => items.splice(offset || 0, limit || 10);\n' },
+      check: `import {paginate} from './paginate.js'; const a=[1,2,3,4]; assert.deepEqual(paginate(a,1,2),[2,3]); assert.deepEqual(a,[1,2,3,4]); assert.deepEqual(paginate(a,0,0),[]); assert.deepEqual(paginate(a,-2,2),[1,2]); assert.deepEqual(paginate(a),a); assert.deepEqual(paginate(a,9,2),[]);`,
+    },
+    dedupe: {
+      category: 'backend bug', paths: ['dedupe.js'],
+      goal: 'Fix dedupe(rows): keep the first row for each exact id, preserve first-occurrence order, distinguish numeric and string ids, return a new array and never mutate input.',
+      files: { 'dedupe.js': 'export const dedupe = rows => Object.values(Object.fromEntries(rows.map(r => [r.id,r])));\n' },
+      check: `import {dedupe} from './dedupe.js'; const rows=[{id:2,v:'a'},{id:1,v:'b'},{id:2,v:'c'},{id:'2',v:'d'}]; const before=JSON.stringify(rows); assert.deepEqual(dedupe(rows),[rows[0],rows[1],rows[3]]); assert.equal(JSON.stringify(rows),before); assert.notEqual(dedupe(rows),rows); assert.deepEqual(dedupe([]),[]);`,
+    },
+    catalog: {
+      category: 'multiple files', paths: ['slug.js', 'catalog.js'],
+      goal: 'Add slug.js exporting slug(text), trimming/lowercasing ASCII text and collapsing runs of non-alphanumeric characters to one hyphen, with no edge hyphens. Add catalog.js exporting catalog(titles), returning {title,slug} records and rejecting duplicate resulting slugs with an Error.',
+      files: {},
+      check: `import {slug} from './slug.js'; import {catalog} from './catalog.js'; assert.equal(slug('  Red & Blue!! '),'red-blue'); assert.equal(slug('---'),''); assert.deepEqual(catalog(['Red Book','Blue']),[{title:'Red Book',slug:'red-book'},{title:'Blue',slug:'blue'}]); assert.throws(()=>catalog(['Red Book','RED BOOK'])); assert.deepEqual(catalog([]),[]);`,
+    },
+    endpoint: {
+      category: 'multiple files', paths: ['validate.js', 'endpoint.js'],
+      goal: 'Add validate.js exporting validName(value), true only for nonempty trimmed strings of at most 20 characters. Add endpoint.js exporting createItem(body), returning {status:400,body:{error:"invalid name"}} for an absent or invalid name, otherwise {status:201,body:{name:trimmedName}}. Accept a missing or null body without throwing.',
+      files: {},
+      check: `import {validName} from './validate.js'; import {createItem} from './endpoint.js'; assert.equal(validName(' a '),true); for(const x of ['', ' ', 2, null, 'a'.repeat(21)]) assert.equal(validName(x),false); for(const x of [undefined,null,{}, {name:3}]) assert.deepEqual(createItem(x),{status:400,body:{error:'invalid name'}}); assert.deepEqual(createItem({name:'  hello '}),{status:201,body:{name:'hello'}});`,
+    },
+    'dependency-format': {
+      category: 'dependency setup', paths: ['receipt.js'], dependency: true,
+      goal: 'Fix receipt(cents) in receipt.js to use the installed pilot-kit formatCents helper and return "Total: $12.34" for 1234, "Total: $0.00" for 0, and "Total: -$0.25" for -25. Dependency setup is already approved; do not change package or vendor files.',
+      files: { 'receipt.js': "export const receipt = cents => 'Total: $' + cents;\n" },
+      check: `import {receipt} from './receipt.js'; assert.equal(receipt(1234),'Total: $12.34'); assert.equal(receipt(0),'Total: $0.00'); assert.equal(receipt(-25),'Total: -$0.25');`,
+    },
+    'dependency-sort': {
+      category: 'dependency setup', paths: ['sort.js'], dependency: true,
+      goal: 'Fix sortNames(names) in sort.js to use the installed pilot-kit naturalCompare helper, sorting names with numeric ordering into a new array without mutating input. Dependency setup is already approved; do not change package or vendor files.',
+      files: { 'sort.js': 'export const sortNames = names => names.sort();\n' },
+      check: `import {sortNames} from './sort.js'; const a=['file10','file2','file1']; assert.deepEqual(sortNames(a),['file1','file2','file10']); assert.deepEqual(a,['file10','file2','file1']); assert.deepEqual(sortNames([]),[]);`,
+    },
+    'revision-csv': {
+      category: 'revision of existing behavior', paths: ['csv.js'],
+      goal: 'Revise csv(rows) to support comma, quote, and newline characters in fields. Quote such fields and double embedded quotes. Join records with CRLF and append a final CRLF for nonempty input. Preserve the csv export; empty rows input returns an empty string.',
+      files: { 'csv.js': "export const csv = rows => rows.map(r=>r.join(',')).join('\\n');\n" },
+      check: `import {csv} from './csv.js'; assert.equal(csv([]),''); assert.equal(csv([['a','b']]),'a,b\\r\\n'); assert.equal(csv([['a,b','say "hi"','x\\ny']]),'"a,b","say ""hi""","x\\ny"\\r\\n'); assert.equal(csv([[0,'']]),'0,\\r\\n');`,
+    },
+    'revision-config': {
+      category: 'revision of existing behavior', paths: ['config.js'],
+      goal: 'Revise mergeConfig(base, overrides): shallow copy base, apply defined overrides including 0 and false, delete keys whose override is null, ignore undefined overrides, and never mutate either argument. Retain the mergeConfig export.',
+      files: { 'config.js': 'export const mergeConfig = (base, overrides) => Object.assign(base,overrides);\n' },
+      check: `import {mergeConfig} from './config.js'; const a={port:80,debug:true,host:'x',keep:1}; const b={port:0,debug:false,host:null,keep:undefined}; assert.deepEqual(mergeConfig(a,b),{port:0,debug:false,keep:1}); assert.deepEqual(a,{port:80,debug:true,host:'x',keep:1}); assert.equal(b.host,null); assert.deepEqual(mergeConfig({},{}),{});`,
+    },
+    'ui-filter': {
+      category: 'UI flow', paths: ['index.html'], ui: true,
+      goal: 'Implement an accessible responsive catalog filter in index.html. Show a heading Catalog, an input named Filter, and a list with Apples, Bananas, Cherries. Filter case-insensitively as the user types, show "No matches" for an empty result, and restore all items when cleared. Fit a 390px mobile viewport without horizontal overflow. Use the provided check to capture desktop and mobile PNG evidence; run it before writing proof and cite output/playwright/desktop.png and mobile.png.',
+      files: { 'index.html': '<!doctype html><meta name="viewport" content="width=device-width,initial-scale=1"><title>Catalog</title><h1>Catalog</h1><p>Filter not implemented.</p>\n' },
+      interaction: `const filter=page.getByRole('textbox',{name:'Filter',exact:true}); await filter.fill('AN'); await expectText(['Bananas']); await filter.fill('zzz'); await page.getByText('No matches',{exact:true}).waitFor(); await filter.fill(''); await expectText(['Apples','Bananas','Cherries']);`,
+    },
+    'ui-form': {
+      category: 'UI flow', paths: ['index.html'], ui: true,
+      goal: 'Implement a responsive accessible task form in index.html. Heading Tasks, input named New task, button Add task, and a list of added tasks. Trim submitted text, reject blank submissions with "Enter a task", clear input after success, and give each added task a checkbox labelled by its text. Fit a 390px mobile viewport without overflow. Use the provided check to capture desktop and mobile PNG evidence; run it before writing proof and cite output/playwright/desktop.png and mobile.png.',
+      files: { 'index.html': '<!doctype html><meta name="viewport" content="width=device-width,initial-scale=1"><title>Tasks</title><h1>Tasks</h1><p>Task form not implemented.</p>\n' },
+      interaction: `const input=page.getByRole('textbox',{name:'New task',exact:true}); const add=page.getByRole('button',{name:'Add task',exact:true}); await input.fill('   '); await add.click(); await page.getByText('Enter a task',{exact:true}).waitFor(); await input.fill('  Buy milk  '); await add.click(); assert.equal(await input.inputValue(),''); const done=page.getByRole('checkbox',{name:'Buy milk',exact:true}); await done.check(); assert.equal(await done.isChecked(),true); await done.uncheck(); assert.equal(await done.isChecked(),false);`,
+    },
+  };
+  const spec=cases[id]; if(!spec) throw new Error('unknown scenario '+id);
+  spec.id=id;
+  spec.files={ 'package.json': JSON.stringify({name:'standing-orders-pilot',private:true,type:'module',scripts:{test:'node verify.mjs'},...(spec.dependency?{dependencies:{'pilot-kit':'file:vendor/pilot-kit'}}:{})},null,2)+'\n', '.gitignore':'node_modules/\noutput/\n', 'README.md':'# Disposable unattended pilot\n\nRun npm test. Only the requested implementation files may change.\n', ...spec.files };
+  if(spec.dependency) {
+    spec.files['vendor/pilot-kit/package.json']=JSON.stringify({name:'pilot-kit',version:'1.0.0',type:'module',exports:'./index.js'})+'\n';
+    spec.files['vendor/pilot-kit/index.js']=`export const formatCents = n => (n < 0 ? '-$' : '$') + (Math.abs(n)/100).toFixed(2);\nexport const naturalCompare = (a,b) => a.localeCompare(b, 'en', {numeric:true});\n`;
+  }
+  if(spec.ui) {
+    if(!playwright) throw new Error('UI pilot needs --playwright pointing to an installed playwright/index.mjs');
+    spec.check=`import {chromium} from ${JSON.stringify(playwright)}; import {mkdir,readFile} from 'node:fs/promises'; import {createServer} from 'node:http';
+const server=createServer(async (_req,res)=>{res.setHeader('Content-Type','text/html');res.end(await readFile('index.html'));}); await new Promise(r=>server.listen(0,'127.0.0.1',r));
+const browser=await chromium.launch({headless:true}); try { const page=await browser.newPage(); const expectText=async expected=>assert.deepEqual((await page.getByRole('listitem').allTextContents()).map(x=>x.trim()),expected); await mkdir('output/playwright',{recursive:true});
+for(const [name,width,height] of [['desktop',1280,800],['mobile',390,844]]) { await page.setViewportSize({width,height}); await page.goto('http://127.0.0.1:'+server.address().port); ${spec.interaction} assert.equal(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth),true); await page.screenshot({path:'output/playwright/'+name+'.png',fullPage:true}); console.log('PASS '+name+' interaction and '+width+'x'+height+' viewport; screenshot output/playwright/'+name+'.png'); }
+} finally {await browser.close(); await new Promise(r=>server.close(r));}`;
+  }
+  spec.files['verify.mjs']=prelude+spec.check+success;
+  return spec;
+}

package/scripts/fixtures/restart-service.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * The disposable service the launchd certificate supervises: beats a
+ * heartbeat file every 200 ms with its pid and a per-incarnation id, exits
+ * 0 when told to (the "unexpected clean exit" the supervisor must relaunch
+ * after), and otherwise lives until killed. No network, no database.
+ */
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+
+const dir = process.env["SO_CERT_STATE"];
+if (dir === undefined) { console.error("SO_CERT_STATE is required"); process.exit(2); }
+const incarnation = randomUUID();
+mkdirSync(join(dir, "writers"), { recursive: true });
+const beat = () => {
+  writeFileSync(join(dir, "heartbeat.json"), JSON.stringify({ pid: process.pid, incarnation, at: Date.now() }));
+  writeFileSync(join(dir, "writers", `${process.pid}-${incarnation}`), String(Date.now()));
+};
+beat();
+setInterval(() => {
+  beat();
+  if (existsSync(join(dir, "exit-now"))) {
+    try { unlinkSync(join(dir, "exit-now")); } catch { /* raced */ }
+    process.exit(0);
+  }
+}, 200);