toolroll 0.5.0

package/scripts/provider-canary.mjs

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+/**
+ * A real-provider release canary.
+ *
+ * This deliberately drives the public CLI rather than importing builder
+ * internals: the disposable repository must cross the same registration,
+ * planning, approval, worktree, provider, commit, verification, and evidence
+ * boundaries as a person's task. It never pushes or opens a pull request.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { mkdir, mkdtemp, readFile, readdir, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createFixtureLead, completeFixtureAssignment } from "./canary-assertions.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const bin = join(root, "dist", "bin.js");
+const TASK_ID = "provider-canary";
+
+function usage() {
+  return [
+    "Real-provider Never Stuck canary",
+    "",
+    "  npm run certify:provider -- --provider claude --model sonnet",
+    "  npm run certify:provider -- --provider codex --model gpt-5.6-sol",
+    "",
+    "Options:",
+    "  --provider claude|codex|gemini|openrouter   CLI transport to exercise",
+    "  --model <model>           exact model sealed into plan and build",
+    "  --output <file>           write the final JSON certificate",
+    "  --auto-approve            sign an unchanged-plan policy",
+    "  --keep                    keep the disposable repo and evidence",
+    "  --json                    print only the final JSON certificate",
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const result = { provider: null, model: null, output: null, keep: false, autoApprove: false, json: false, help: false };
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === "--keep") result.keep = true;
+    else if (arg === "--auto-approve") result.autoApprove = true;
+    else if (arg === "--json") result.json = true;
+    else if (arg === "--help" || arg === "-h") result.help = true;
+    else if (["--provider", "--model", "--output"].includes(arg)) {
+      const value = argv[++index];
+      if (value === undefined || value.startsWith("--")) throw new Error(`${arg} needs a value`);
+      result[arg.slice(2)] = value;
+    } else throw new Error(`unknown option ${arg}`);
+  }
+  if (result.help) return result;
+  if (!["claude", "codex", "gemini", "openrouter"].includes(result.provider)) {
+    throw new Error("--provider is claude, codex, gemini or openrouter");
+  }
+  if (typeof result.model !== "string" || result.model.trim() === "") {
+    throw new Error("--model is required because task approvals seal exact routing");
+  }
+  return result;
+}
+
+function run(file, args, options = {}) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(file, args, {
+      cwd: options.cwd ?? root,
+      env: options.env ?? process.env,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", chunk => { stdout += chunk; });
+    child.stderr.on("data", chunk => { stderr += chunk; });
+    child.on("error", reject);
+    child.on("close", code => resolvePromise({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
+function parseEnvelope(answer, label, acceptedCodes = [0]) {
+  let envelope = null;
+  try {
+    envelope = JSON.parse(answer.stdout.trim());
+  } catch {
+    // The thrown diagnostic below includes the bounded raw answer.
+  }
+  if (!acceptedCodes.includes(answer.code) || envelope === null || typeof envelope !== "object") {
+    const details = [
+      `${label} failed (exit ${answer.code})`,
+      answer.stderr.trim(),
+      answer.stdout.trim(),
+    ].filter(Boolean).join("\n").slice(0, 8_000);
+    throw new Error(details);
+  }
+  return envelope;
+}
+
+/** The executable bytes and source identity tested by this run. Each CLI
+ * boundary rechecks them; an in-place build cannot silently change the
+ * implementation halfway through a successful certificate. */
+async function runtimeIdentity() {
+  const hash = createHash("sha256");
+  async function hashDirectory(directory, prefix) {
+    const entries = (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const relative = `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) await hashDirectory(join(directory, entry.name), relative);
+      else if (entry.isFile()) hash.update(relative).update("\0").update(await readFile(join(directory, entry.name))).update("\0");
+      else throw new Error(`unexpected runtime entry ${relative}`);
+    }
+  }
+  await hashDirectory(join(root, "dist"), "dist");
+  for (const file of ["package.json", "scripts/provider-canary.mjs", "scripts/canary-assertions.mjs", "scripts/proof-preflight.mjs"]) {
+    hash.update(file).update("\0").update(await readFile(join(root, file))).update("\0");
+  }
+  const revision = await run("git", ["rev-parse", "HEAD"]);
+  const changes = await run("git", ["status", "--porcelain", "--untracked-files=no"]);
+  return { sha256: hash.digest("hex"), sourceCommit: revision.code === 0 ? revision.stdout.trim() : null,
+    trackedChanges: changes.code === 0 ? changes.stdout.trim() !== "" : null };
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${usage()}\n`);
+    process.exitCode = 2;
+    return;
+  }
+  if (options.help) {
+    process.stdout.write(`${usage()}\n`);
+    return;
+  }
+
+  const startedAt = new Date();
+  const base = await realpath(await mkdtemp(join(tmpdir(), "standing-orders-provider-canary-")));
+  const repo = join(base, "repo");
+  const db = join(base, "orders.db");
+  const pool = join(base, "worktrees");
+  const password = `canary-${randomUUID()}`;
+  const common = ["--db", db, "--json"];
+  let passed = false;
+  let runtime = null;
+  const steps = [];
+  const assertRuntime = async () => {
+    if (runtime !== null && JSON.stringify(await runtimeIdentity()) !== JSON.stringify(runtime)) {
+      throw new Error("the Toolroll runtime changed during the canary; rerun against one fixed build");
+    }
+  };
+
+  const note = message => {
+    if (!options.json) process.stdout.write(`${message}\n`);
+    else process.stderr.write(`${message}\n`);
+  };
+  const cli = async (label, args, acceptedCodes = [0]) => {
+    await assertRuntime();
+    note(`  ${label}`);
+    const started = Date.now();
+    const answer = await run(process.execPath, [bin, ...args, ...common]);
+    steps.push({ label, durationMs: Date.now() - started, exitCode: answer.code });
+    return parseEnvelope(answer, label, acceptedCodes);
+  };
+  const git = async (...args) => {
+    const answer = await run("git", args, { cwd: repo });
+    if (answer.code !== 0) throw new Error(`git ${args.join(" ")} failed\n${answer.stderr}`);
+    return answer.stdout.trim();
+  };
+
+  let certificate;
+  try {
+    runtime = await runtimeIdentity();
+    note(`Certifying ${options.provider} · ${options.model} through the real workflow`);
+    await mkdir(repo, { recursive: true });
+    await git("init", "-q", "-b", "main");
+    await git("config", "user.email", "canary@standing-orders.local");
+    await git("config", "user.name", "Toolroll Canary");
+    await writeFile(
+      join(repo, "package.json"),
+      `${JSON.stringify({ name: "standing-orders-provider-canary", private: true, type: "module", scripts: { test: "node --test" } }, null, 2)}\n`,
+    );
+    await writeFile(join(repo, "README.md"), "# Toolroll provider canary\n\nThis repository is disposable.\n");
+    await git("add", ".");
+    await git("commit", "-qm", "seed provider canary");
+    const baseSha = await git("rev-parse", "HEAD");
+
+    await cli("create the isolated approver", ["approver", "add", "canary", "--password", password]);
+    const registered = await cli("register a repository-bound worker", [
+      "runner", "register", "canary-worker", "--repo", repo,
+      "--as", "canary", "--token", password,
+    ]);
+    const runnerToken = registered.token;
+    if (typeof runnerToken !== "string" || runnerToken === "") throw new Error("runner registration returned no token");
+
+    for (const phase of ["plan", "build", "repair"]) {
+      const provider = options.provider;
+      const model = options.model;
+      await cli(`route ${phase} to ${provider}`, [
+        "config", "set", phase,
+        "--provider", provider,
+        "--model", model,
+        "--as", "canary", "--token", password,
+      ]);
+    }
+    await cli("approve the repository verification command", [
+      "verify", "set", "--repo", repo,
+      "--command", "node --test", "--timeout-seconds", "120", "--yes",
+      "--as", "canary", "--token", password,
+    ]);
+
+    const title = [
+      `Add canary.txt: exactly "standing-orders ${options.provider} canary passed" plus newline.`,
+      "Add canary.test.js using node:test.",
+      "Only these files; no questions; acceptance evidence: check and changed-path only.",
+    ].join(" ");
+    await cli("file the task", ["task", "add", title, "--id", TASK_ID, "--repo", repo]);
+    let filedDigest = null;
+    if (options.autoApprove) {
+      await cli("sign bounded unchanged-plan approval", [
+        "mode", "set", "--repo", repo, "--name", "standard", "--days", "1",
+        "--auto-approve", "true", "--plan-auto", "--as", "canary", "--token", password,
+      ]);
+      await cli("file the fixed contract without approving its scope", [
+        "task", "scope", TASK_ID, "--goal", title, "--not", "No other files and no publication.",
+        "--touches", "canary.txt,canary.test.js",
+        "--acceptance", `canary.txt contains exactly standing-orders ${options.provider} canary passed followed by one newline.|changed-path;canary.test.js uses node:test to verify the exact file bytes and the approved node --test command passes.|check,changed-path`,
+      ]);
+      const filed = await cli("retain the exact filed contract digest", ["task", "show", TASK_ID]);
+      filedDigest = filed.scope?.digest;
+      if (typeof filedDigest !== "string" || filed.scope.approvedAt != null) throw new Error("fixed contract was missing or prematurely approved");
+    }
+    const requested = await cli("request a repository-aware plan", [
+      "task", "plan", TASK_ID,
+      "--provider", options.provider, "--model", options.model,
+      "--as", "canary", "--token", password,
+    ]);
+    if (options.autoApprove && requested.autoPlan !== true) throw new Error("the exact filed plan was not pre-authorized");
+    const planned = await cli("run the planning pass", [
+      "tick", "--runner", "canary-worker", "--token", runnerToken,
+      "--repo", repo, "--pool", pool,
+    ]);
+    if (!Array.isArray(planned.dispatched) || !planned.dispatched.some(item => item?.outcome === "planned")) {
+      throw new Error(`planner did not produce a scope: ${JSON.stringify(planned)}`);
+    }
+
+    const afterPlan = await cli("read the drafted scope", ["task", "show", TASK_ID]);
+    const digest = afterPlan.scope?.digest;
+    if (typeof digest !== "string" || digest === "") throw new Error("the planning pass produced no approvable scope");
+    if (!Array.isArray(afterPlan.scope?.acceptance) || afterPlan.scope.acceptance.length === 0) {
+      throw new Error("the planning pass produced no acceptance criteria");
+    }
+    if (options.autoApprove) {
+      if (digest !== filedDigest || afterPlan.scope.approvedDigest !== digest || afterPlan.scope.approvalBasis !== "mode") {
+        throw new Error("the unchanged plan did not receive the exact signed mode approval");
+      }
+    } else await cli("approve the exact planned scope", [
+      "task", "approve", TASK_ID, "--yes", "--digest", digest,
+      "--as", "canary", "--token", password,
+    ]);
+
+    const built = await cli("run the build and evidence pass", [
+      "tick", "--runner", "canary-worker", "--token", runnerToken,
+      "--repo", repo, "--pool", pool,
+    ]);
+    if (!Array.isArray(built.dispatched) || !built.dispatched.some(item => item?.outcome === "built")) {
+      throw new Error(`builder did not complete the task: ${JSON.stringify(built)}`);
+    }
+
+    let final = await cli("read the terminal task and proof", ["task", "show", TASK_ID]);
+    if (final.task?.state !== "done") throw new Error(`task ended ${String(final.task?.state ?? "without a state")}`);
+    const buildRun = Array.isArray(final.runs)
+      ? final.runs.find(runRow => runRow?.role === "builder" && runRow?.outcome === "built")
+      : null;
+    if (buildRun === null || buildRun === undefined || typeof buildRun.branch !== "string") {
+      throw new Error("no completed builder run named its branch");
+    }
+    const branchSha = await git("rev-parse", buildRun.branch);
+    if (branchSha === baseSha) throw new Error("the build branch did not advance");
+    const canaryText = await git("show", `${buildRun.branch}:canary.txt`);
+    const expectedText = `standing-orders ${options.provider} canary passed`;
+    if (canaryText !== expectedText) throw new Error(`canary.txt contained ${JSON.stringify(canaryText)}`);
+    await git("show", `${buildRun.branch}:canary.test.js`);
+    const changed = (await git("diff", "--name-only", baseSha, branchSha)).split("\n").filter(Boolean).sort();
+    if (JSON.stringify(changed) !== JSON.stringify(["canary.test.js", "canary.txt"])) {
+      throw new Error(`the canary changed unexpected paths: ${JSON.stringify(changed)}`);
+    }
+
+    const leadFile = await createFixtureLead(args => cli("scope the fixture lead", args), {
+      repo, auth: ["--as", "canary", "--token", password], tokenFile: join(base, "lead.token"),
+    });
+    const completion = await completeFixtureAssignment(args => cli("inspect and handle saved result", args), TASK_ID, leadFile, { head: branchSha, runId: buildRun.id });
+
+    const duplicate = await cli("prove the completed task cannot dispatch twice", [
+      "tick", "--runner", "canary-worker", "--token", runnerToken,
+      "--repo", repo, "--pool", pool,
+    ], [3]);
+    if (duplicate.reason !== "empty") throw new Error(`duplicate pass was not empty: ${JSON.stringify(duplicate)}`);
+    if (await git("rev-parse", "main") !== baseSha) throw new Error("the default branch changed");
+    if (Number(await git("rev-list", "--count", `${baseSha}..${branchSha}`)) !== 1) throw new Error("expected exactly one work commit");
+    await assertRuntime();
+
+    const providerRun = final.runs.find(runRow => runRow?.provider === options.provider && runRow?.providerStartedAt != null);
+    certificate = {
+      version: 3,
+      passed: true,
+      provider: options.provider,
+      model: options.model,
+      startedAt: startedAt.toISOString(),
+      finishedAt: new Date().toISOString(),
+      durationSeconds: Math.round((Date.now() - startedAt.getTime()) / 1000),
+      platform: process.platform,
+      architecture: process.arch,
+      node: process.versions.node,
+      runtime,
+      steps,
+      workflow: {
+        registration: "passed",
+        planning: "passed",
+        approval: options.autoApprove ? "unchanged-plan-under-signed-mode" : "passed",
+        humanActionsAfterPlanningStarted: options.autoApprove ? 0 : 1,
+        filedScopeDigest: filedDigest,
+        worktreeBuild: "passed",
+        commit: branchSha,
+        verificationCommand: "node --test",
+        proofVerdict: final.proofVerdict,
+        criterionMatrix: final.proofMatrix,
+        leadCompletion: completion,
+        duplicateDispatch: "refused-empty",
+      },
+      providerRun: providerRun == null ? null : {
+        run: providerRun.id,
+        role: providerRun.role,
+        version: providerRun.providerVersion,
+        tokensIn: providerRun.tokensIn,
+        tokensOut: providerRun.tokensOut,
+        costUsd: providerRun.costUsd,
+      },
+      runs: final.runs.map(one => ({ id: one.id, role: one.role, parentRun: one.parentRun,
+        provider: one.provider, model: one.model, version: one.providerVersion, outcome: one.outcome,
+        startedAt: one.startedAt, providerStartedAt: one.providerStartedAt, firstByteAt: one.firstByteAt, finishedAt: one.finishedAt,
+      })),
+      retainedAt: options.keep ? base : null,
+      note: "This canary never pushed or opened a pull request.",
+    };
+    passed = true;
+  } catch (error) {
+    certificate = {
+      version: 3,
+      passed: false,
+      provider: options.provider,
+      model: options.model,
+      startedAt: startedAt.toISOString(),
+      finishedAt: new Date().toISOString(),
+      durationSeconds: Math.round((Date.now() - startedAt.getTime()) / 1000),
+      platform: process.platform,
+      architecture: process.arch,
+      node: process.versions.node,
+      runtime,
+      steps,
+      retainedAt: base,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    if (options.output !== null) {
+      const output = resolve(options.output);
+      await mkdir(dirname(output), { recursive: true });
+      await writeFile(output, `${JSON.stringify(certificate, null, 2)}\n`);
+    }
+    if (passed && !options.keep) await rm(base, { recursive: true, force: true });
+  }
+
+  process.stdout.write(`${JSON.stringify(certificate, null, 2)}\n`);
+  if (!passed) process.exitCode = 1;
+}
+
+await main();

package/scripts/recovery-canary.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/** Repeated real-process occupancy and draft-preservation checks. No model calls. */
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { mkdtemp, mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+let rounds = 100;
+let output = resolve("output/certification/recovery.json");
+let keep = false;
+const usage = "npm run certify:recovery -- [--rounds 100] [--output <file>] [--keep]";
+for (let index = 2; index < process.argv.length; index++) {
+  const arg = process.argv[index];
+  if (arg === "--help") { console.log(usage); process.exit(0); }
+  else if (arg === "--keep") keep = true;
+  else if (arg === "--rounds" || arg === "--output") {
+    const value = process.argv[++index];
+    if (value === undefined || value.startsWith("--")) throw new Error(`${arg} needs a value; ${usage}`);
+    if (arg === "--rounds") rounds = Number(value);
+    else output = resolve(value);
+  } else throw new Error(`unknown option ${arg}; ${usage}`);
+}
+assert(Number.isSafeInteger(rounds) && rounds > 0 && rounds <= 1000, "rounds must be an integer from 1 to 1000");
+const { openStore } = await import(pathToFileURL(join(root, "dist/store.js")));
+const { register, recoverDead, DEFAULT_LIVENESS_MS } = await import(pathToFileURL(join(root, "dist/runner.js")));
+const { acquire, completeFenced } = await import(pathToFileURL(join(root, "dist/claim.js")));
+const { WorktreePool } = await import(pathToFileURL(join(root, "dist/worktree.js")));
+const { run } = await import(pathToFileURL(join(root, "dist/exec.js")));
+const { HANDOFF_PREFIX } = await import(pathToFileURL(join(root, "dist/evidence.js")));
+
+const base = await realpath(await mkdtemp(join(tmpdir(), "standing-orders-recovery-canary-")));
+const started = Date.now();
+const cases = [];
+let failure = null;
+const git = async (repo, args) => {
+  const result = await run("git", args, { cwd: repo, timeoutMs: 10000 });
+  assert.equal(result.code, 0, result.stderr);
+  return result.stdout.trim();
+};
+const revision = await git(root, ["rev-parse", "HEAD"]);
+try {
+  for (let index = 0; index < rounds; index++) {
+    const round = join(base, String(index));
+    const repo = join(round, "repo");
+    await mkdir(repo, { recursive: true });
+    await git(repo, ["init", "-q", "-b", "main"]);
+    await git(repo, ["config", "user.email", "canary@standing-orders.local"]);
+    await git(repo, ["config", "user.name", "Recovery Canary"]);
+    await writeFile(join(repo, "README.md"), "disposable recovery fixture\n");
+    await git(repo, ["add", "."]);
+    await git(repo, ["commit", "-qm", "seed"]);
+    const store = openStore(join(round, "orders.db"));
+    let writer = null;
+    let exited = null;
+    try {
+      const now = new Date();
+      const expired = new Date(now.getTime() + DEFAULT_LIVENESS_MS + 1000);
+      const old = register(store, { name: "old", host: "fixture", repos: [repo], now });
+      store.createTask({ id: "work", title: "preserve an interrupted draft" }, now);
+      const ref = store.refFor("built-in", "work").id;
+      store.placeTask(ref, repo);
+      const claim = acquire(store, ref, "old", { token: old.token, now, newLeaseId: () => "old-lease" });
+      assert.equal(claim.ok, true);
+      store.setTaskState("work", "running", now);
+      const pool = new WorktreePool(store, { root: join(round, "pool") });
+      const leased = await pool.lease({ repo, branch: "draft", base: "main", runner: "old", taskRef: ref, now });
+      assert.equal(leased.ok, true, leased.message);
+      const path = leased.worktree.path;
+      const runId = store.startRun({ taskRef: ref, runner: "old", leaseId: "old-lease", branch: "draft", worktree: path, now,
+        route: { routeDigest: "legacy", phase: "build", provider: "claude", model: null, chosen: "legacy" } });
+      const scenario = ["partial-draft", "completed-handoff", "committed-with-late-writer"][index % 3];
+      if (scenario === "completed-handoff") {
+        await writeFile(join(path, `${HANDOFF_PREFIX}0123456789abcdef.json`), JSON.stringify({ version: 1, status: "completed", conclusion: "A finished draft before control-plane interruption." }));
+      }
+      if (scenario === "committed-with-late-writer") {
+        await writeFile(join(path, "finished.txt"), "a commit already exists\n");
+        await git(path, ["add", "finished.txt"]);
+        await git(path, ["commit", "-qm", "finished work before interruption"]);
+      }
+      const head = await git(path, ["rev-parse", "HEAD"]);
+      // A real live process keeps writing after the controller's liveness
+      // expires. The clock injection is deliberate: this is an occupancy
+      // fence canary, not a claim to have killed the entire product worker.
+      writer = spawn(process.execPath, ["-e", "const fs=require('node:fs');let n=0;const write=()=>fs.writeFileSync('draft.txt','preserved '+(++n)+'\\n');write();console.log('ready');setInterval(write,10)"],
+        { cwd: path, stdio: ["ignore", "pipe", "ignore"] });
+      exited = once(writer, "exit");
+      await once(writer.stdout, "data");
+      assert.equal(pool.markProviderOccupancy(path, "old", writer.pid), true);
+      const recovered = recoverDead(store, expired);
+      assert.equal(store.getRun(runId).outcome, "failed");
+      assert.equal(store.getRun(runId).reason, "interrupted");
+      assert.deepEqual(recovered[0].requeued, ["work"]);
+      const next = register(store, { name: "next", host: "fixture", repos: [repo], now: expired });
+      const successor = acquire(store, ref, "next", { token: next.token, now: expired, newLeaseId: () => "new-lease" });
+      assert.equal(successor.ok, true);
+      const request = { repo, branch: "draft", runner: "next", taskRef: ref, now: expired, reclaim: { evidenceRoot: join(round, "evidence") } };
+      const blocked = await pool.lease(request);
+      assert.equal(blocked.ok, false);
+      assert.equal(blocked.reason, "in-use");
+      assert.equal(completeFenced(store, "old-lease", "done", expired).ok, false);
+      assert.notEqual(store.getTask("work").state, "done");
+      writer.kill("SIGKILL");
+      await exited;
+      writer = null;
+      const draft = await readFile(join(path, "draft.txt"), "utf8");
+      const resumed = await pool.lease(request);
+      assert.equal(resumed.ok, true, resumed.message);
+      assert.equal(resumed.resumedFromRun, runId);
+      assert.equal(resumed.recoveryKind, scenario === "completed-handoff" ? "completed" : "partial");
+      assert.equal(await readFile(join(path, "draft.txt"), "utf8"), draft);
+      assert.equal(await git(path, ["rev-parse", "HEAD"]), head);
+      assert((await readFile(resumed.reclaimed, "utf8")).includes(draft.trim()));
+      assert.equal(completeFenced(store, "new-lease", "failed", expired).ok, true);
+      await pool.release(path, expired);
+      cases.push({ round: index + 1, scenario, passed: true, oldCompletion: "fenced", liveWriter: "refused-reuse", draft: "preserved", commit: "preserved" });
+    } finally {
+      if (writer !== null) { writer.kill("SIGKILL"); await exited.catch(() => {}); }
+      store.close();
+    }
+    if ((index + 1) % 10 === 0) process.stdout.write(`${index + 1}/${rounds} recovery cases passed\n`);
+  }
+} catch (error) { failure = error instanceof Error ? error.stack : String(error); }
+const certificate = { version: 1, passed: failure === null, sourceCommit: revision, platform: process.platform, node: process.versions.node,
+  roundsRequested: rounds, roundsPassed: cases.length, durationSeconds: (Date.now() - started) / 1000,
+  scope: "Real writer processes with injected controller liveness expiry: no reuse while the writer is alive; stale completion fenced; draft, handoff and existing commit preserved after writer exit.",
+  exclusions: ["actual controller crash at every transition", "process trees with detached descendants", "Windows reboot", "provider session resume", "interrupted verification receipt reuse"],
+  cases, error: failure, retainedAt: failure === null && !keep ? null : base };
+await mkdir(dirname(output), { recursive: true });
+await writeFile(output, JSON.stringify(certificate, null, 2) + "\n");
+if (failure === null && !keep) await rm(base, { recursive: true, force: true });
+if (failure !== null) { process.stderr.write(failure + "\n"); process.exitCode = 1; }

package/scripts/restart-certification.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * Restart certification (docs/PROCESS_CONTAINMENT_PLAN.md, acceptance 7).
+ *
+ *   npm run certify:restart -- baseline --db <orders.db> [--label <service label>] [--output <file>]
+ *   npm run certify:restart -- verify   --db <orders.db> --baseline <file> [--label <label>] [--expect reboot|login|either] [--output <file>]
+ *
+ * `baseline` records the OS boot identity, the runtime, the installed
+ * service's state, the containment status and the database's live custody
+ * (pending stops, open runs, running tasks, open witnesses) — names and
+ * timestamps only, never a credential. A person then logs out and in, or
+ * reboots, THEMSELVES: this tool never does, and never restarts a service.
+ * `verify` compares the same database afterwards: whether the boot really
+ * changed (the kernel's own token), whether the service is a working
+ * controller (running AND a fresh heartbeat), whether what the old boot
+ * left pending settled by the controller's own rules, and whether the
+ * tasks that were running moved on. Its exit code is the verdict; its
+ * output carries the exact limits of what a pass proves.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const usage = "npm run certify:restart -- baseline|verify --db <file> [--label <label>] [--baseline <file>] [--expect reboot|login|either] [--output <file>] [--runner <name>] [--task <id>] [--no-recover]";
+const [mode, ...rest] = process.argv.slice(2);
+if (mode === undefined || mode === "--help" || (mode !== "baseline" && mode !== "verify")) { console.log(usage); process.exit(mode === "--help" ? 0 : 2); }
+const options = { db: undefined, label: undefined, baseline: undefined, expect: "either", output: undefined, recover: true, runner: undefined, tasks: [] };
+for (let index = 0; index < rest.length; index++) {
+  const arg = rest[index];
+  if (arg === "--no-recover") { options.recover = false; continue; }
+  const value = rest[++index];
+  if (value === undefined || value.startsWith("--")) throw new Error(`${arg} needs a value; ${usage}`);
+  if (arg === "--runner") options.runner = value;
+  else if (arg === "--task") options.tasks.push(value);
+  else if (arg === "--db") options.db = resolve(value);
+  else if (arg === "--label") options.label = value;
+  else if (arg === "--baseline") options.baseline = resolve(value);
+  else if (arg === "--expect") options.expect = value;
+  else if (arg === "--output") options.output = resolve(value);
+  else throw new Error(`unknown option ${arg}; ${usage}`);
+}
+if (options.db === undefined || !existsSync(options.db)) throw new Error(`--db must name an existing database; ${usage}`);
+if (!["reboot", "login", "either"].includes(options.expect)) throw new Error(`--expect is reboot, login or either; ${usage}`);
+
+const { openStoreNoMigrate } = await import(pathToFileURL(resolve(root, "dist/store.js")));
+const { installedServiceDefinition } = await import(pathToFileURL(resolve(root, "dist/daemon.js")));
+const { run } = await import(pathToFileURL(resolve(root, "dist/exec.js")));
+const { recordRestartBaseline, verifyRestartRecovery, assertNoSecret } = await import(pathToFileURL(resolve(root, "dist/restart-certification.js")));
+
+// The certificate NEVER migrates a database: a live controller's file is
+// opened exactly as it is, and a file this build cannot read is refused.
+const opened = openStoreNoMigrate(options.db);
+if (!opened.ok) throw new Error(opened.message);
+const store = opened.store;
+try {
+  const service = options.label === undefined ? undefined : (() => {
+    const definition = installedServiceDefinition({ label: options.label, configDir: dirname(options.db) });
+    if (definition === null) throw new Error(`no installed unit found for ${options.label} — the service view needs the unit file on disk`);
+    return { definition, run };
+  })();
+  // Secrets that might sit beside the database: never in the output.
+  const secrets = [];
+  for (const name of ["runner-token", "telegram-token"]) {
+    const file = resolve(dirname(options.db), name);
+    if (existsSync(file)) secrets.push(readFileSync(file, "utf8").trim());
+  }
+  if (mode === "baseline") {
+    const baseline = await recordRestartBaseline({ store, ...(options.runner ? { runnerName: options.runner } : {}), completionTasks: options.tasks, ...(service === undefined ? {} : { service }) });
+    const json = JSON.stringify(baseline, null, 2);
+    assertNoSecret(json, secrets);
+    const output = options.output ?? resolve("output/certification/restart-baseline.json");
+    mkdirSync(dirname(output), { recursive: true });
+    writeFileSync(output, `${json}\n`);
+    console.log(`baseline recorded at ${output}`);
+    console.log(`  host ${baseline.host} · boot ${baseline.boot.id ?? `unknown (${baseline.boot.problem})`} · node ${baseline.runtime.nodeVersion} · schema v${baseline.database.schemaVersion}`);
+    console.log(`  service ${baseline.service === null ? "(none named; pass --label)" : `${baseline.service.label}: ${baseline.service.detail}`}`);
+    console.log(`  custody: ${baseline.database.pendingStops.length} pending stop(s), ${baseline.database.openRuns.length} open run(s), ${baseline.database.runningTasks.length} running task(s), ${baseline.database.witnesses.length} open witness(es)`);
+    console.log("  now log out and in, or reboot — this tool does neither — then run verify against the same database.");
+    for (const limit of baseline.limits) console.log(`  limit: ${limit}`);
+    process.exit(0);
+  }
+  if (options.baseline === undefined || !existsSync(options.baseline)) throw new Error(`verify needs --baseline <file>; ${usage}`);
+  const baseline = JSON.parse(readFileSync(options.baseline, "utf8"));
+  const verified = await verifyRestartRecovery({ store, baseline, expect: options.expect, recover: options.recover, ...(service === undefined ? {} : { service }) });
+  const json = JSON.stringify(verified, null, 2);
+  assertNoSecret(json, secrets);
+  const output = options.output ?? resolve("output/certification/restart-verification.json");
+  mkdirSync(dirname(output), { recursive: true });
+  writeFileSync(output, `${json}\n`);
+  console.log(`${verified.ok ? "PASS" : "FAIL"} — restart certification (${verified.expectation}); boot ${verified.bootChanged === null ? "unknown" : verified.bootChanged ? "changed" : "unchanged"}`);
+  for (const check of verified.checks) console.log(`  ${check.ok ? "ok  " : "FAIL"} ${check.name}: ${check.detail}`);
+  console.log(`  written to ${output}`);
+  for (const limit of verified.limits) console.log(`  limit: ${limit}`);
+  process.exit(verified.ok ? 0 : 1);
+} finally {
+  store.close();
+}