toolroll 0.9.103 → 0.9.105

package/dist/demo.js

@@ -1,28 +1,3 @@
-/**
- * `toolroll demo` (adoption track, step 4) — a seeded, throwaway
- * sandbox: ninety seconds from npx to seeing the product mid-flight, with
- * zero real repos, zero agents, zero spend.
- *
- * The honesty contract (Codex adoption review, findings 8 and 9):
- *
- *   - The database is stamped `demo` BEFORE any row exists — an append-only
- *     installation fact with no unset API. Every spending or external-effect
- *     command (tick, watch, build, publish, reconcile, daemon, bridge,
- *     intake) fails closed on the stamp, so a kept sandbox
- *     can never be mistaken for real work by a worker pointed at it later.
- *     The console banner is decoration; the fence is enforcement.
- *   - The seeded history is SYNTHETIC and does not pretend otherwise: runs
- *     are written with the same permissive store methods the test suite
- *     uses, inside a database that can never join operational history,
- *     because nothing that computes provider success or spends quota will
- *     open it (the fence again).
- *   - The throwaway password goes to the terminal and to a mode-0600 file
- *     inside the sandbox — NEVER into the --json envelope, a URL, or the
- *     database.
- *
- * Everything lives under one mkdtemp directory: database, evidence,
- * "repos". Ctrl-C tears it down; --keep preserves it (still fenced).
- */
 import { execFileSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -43,8 +18,6 @@ import { parseExecutionPlanDocument, milestonesOf } from "./plan.js";
 import { maybeTriggerRepair } from "./dispose.js";
 import { deflateSync } from "node:zlib";
 import { FLOW_TEMPLATES } from "./flows.js";
-// The demo demonstrates a CONFIGURED install: routing is named once, the
-// way `config set build` would, so approvals bind it like production.
 const DEMO_PROFILE = {
     provider: "claude",
     model: "sonnet",
@@ -52,18 +25,12 @@ const DEMO_PROFILE = {
     maxTurns: 1_000, repairMaxTurns: 4, timeoutSeconds: 1_200, timeoutKind: "idle", repairTimeoutSeconds: 300,
     repairModel: "inherit",
 };
-/** The exact route authority a demo run presents at admission (v48 authority repair): the
- * store dictates nothing, so every routed row here presents the sealed (or,
- * for a planner, the working) leg exactly as a real dispatch would. */
 function presentedRoute(store, taskRef, role, spend = { provider: "claude", model: null }) {
-    // A task with no scope presents the bare word `legacy` for the exact
-    // pair it spends as (atomic authority closure) — nothing opens unstamped.
     const authority = store.routeAuthorityFor(taskRef, role) ?? store.routeAuthorityFor(taskRef, role, spend);
     if (authority === null || !authority.ok)
         throw new Error(`demo seed: ${authority === null ? "no task" : authority.problem}`);
     return { route: authority.stamp };
 }
-/** A believable patch for the finished run's review card. */
 const DEMO_PATCH = `diff --git a/src/payout.ts b/src/payout.ts
 index 3f1c2aa..9e07b41 100644
 --- a/src/payout.ts
@@ -85,8 +52,6 @@ index 11aa0b2..c44d1f7 100644
 +    expect(settle(1005, 0.031)).toBe(31.16);
 +  });
 `;
-/** A demo run's handoff artifact: the run's own identity around the story's conclusion and lists, written through
- * the handoff schema like a real one. */
 function demoHandoffBytes(store, runId, told) {
     const run = store.getRun(runId);
     const head = run.headRevision ?? run.baseRevision ?? "0".repeat(40);
@@ -111,8 +76,6 @@ const DEMO_HANDOFF = {
     followUps: [],
     decisionsIncorporated: [],
 };
-/** The failed demo build: it took the flag out of settlement and config, but
- * not out of the admin override, and its own report says so. */
 const DEMO_FAILED_PATCH = `diff --git a/src/payout.ts b/src/payout.ts
 index 7c1d2e3..5a1f0c7 100644
 --- a/src/payout.ts
@@ -161,10 +124,6 @@ const DEMO_FAILED_PROOF = {
     caveats: ["c1: src/admin/overrides.ts still reads LEGACY_PAYOUT for the per-merchant override toggle, so one reference remains."],
     screenshots: [],
 };
-/** The evidence bundle's own manifest (Acceptance Contract v2 demo): the
- * seeded sandbox answers its OWN signed rubric by exact id, with typed
- * evidence references — the same shape a real builder writes — so a
- * fresh install sees the finished feature end to end, not a stub. */
 const DEMO_PROOF = {
     version: 1,
     criteria: [
@@ -189,8 +148,6 @@ const DEMO_PROOF = {
     ],
     checks: [{ command: "npm test", exitCode: 0, summary: "214 tests passed, including the new rounding boundary cases." }],
     changed: ["src/payout.ts", "src/payout.test.ts"],
-    // One declared caveat, so the review cockpit's "caveats" row shows a real
-    // agent-declared concern in the sandbox rather than only its empty state.
     caveats: ["The dashboard screenshot was captured against the ledger fixtures, not production data."],
     screenshots: [{ path: "evidence/payout-dashboard.png", caption: "Payout dashboard after the fix — totals match the ledger." }],
 };
@@ -214,13 +171,6 @@ const DEMO_COPY_HANDOFF = {
     followUps: [],
     decisionsIncorporated: [],
 };
-/** A criterion whose only required evidence is `manual-review` (Acceptance
- * Contract v2, review finding): no check, no screenshot, nothing a machine
- * can resolve on its own — a human has to read the copy and say it is
- * good. The seeded verdict below is computed by the REAL adjudicate(),
- * so the sandbox proves the fix live: this build reads "needs
- * verification", never "verified" or "attested", until an operator uses
- * the same "accept anyway" act a short/refuted proof already offers. */
 const DEMO_COPY_PROOF = {
     version: 1,
     criteria: [
@@ -254,9 +204,6 @@ const DEMO_EXECUTION_PLAN = [
     "- c1 — run the logger and dashboard fixture checks and review the rendered JSON lines.",
     "",
 ].join("\n");
-/** Adaptive execution plans (v44): the "building" demo task's revision 1,
- * the planner's original plan before the running build's own evidence
- * revised it. */
 const DEMO_BUILDING_PLAN_V1 = [
     "## Approach",
     "Add a per-endpoint token-bucket limiter and enforce it before dispatch, reusing the existing webhook queue.",
@@ -273,10 +220,6 @@ const DEMO_BUILDING_PLAN_V1 = [
     "- c1 — load-test one slow and one healthy endpoint together.",
     "",
 ].join("\n");
-/** Revision 2: a prior builder attempt found the named dependency was
- * false (the queue has no stable per-endpoint key) and filed a bounded,
- * evidence-linked, plan-only revision — auto-applied, no operator wait,
- * exactly what c3/c4's plan-only path resumes without another approval. */
 const DEMO_BUILDING_PLAN_V2 = [
     "## Approach",
     "Derive a stable per-endpoint key from the normalized webhook URL host, since the queue has none; add a per-endpoint token-bucket limiter keyed on it and enforce it before dispatch.",
@@ -297,22 +240,12 @@ const DEMO_BUILDING_PLAN_V2 = [
 ].join("\n");
 const DEMO_BUILDING_REVISION_REASON = "The webhook queue has no stable per-endpoint key (src/webhooks/queue.ts) — the planned limiter needed one, so this revision derives it from the normalized URL host instead.";
 const DEMO_BUILDING_REVISION_EVIDENCE = "src/webhooks/queue.ts";
-/**
- * A minimal, real, uncompressed-per-scanline PNG encoder — no image
- * library, just IHDR + one zlib-deflated IDAT + IEND. Used only to give
- * the demo's screenshot evidence REAL, non-placeholder dimensions and
- * byte size (Acceptance Contract v2: a screenshot criterion needs a real
- * file of at least 320×200 and meaningful bytes to verify) without
- * shipping a binary asset for a run nobody actually captured.
- */
 function encodeDemoPng(width, height, rgb) {
-    // A faint vertical gradient so the file is not one repeated byte —
-    // "meaningful", not merely large.
     const stride = width * 3;
     const raw = Buffer.alloc((stride + 1) * height);
     for (let y = 0; y < height; y++) {
         const rowStart = y * (stride + 1);
-        raw[rowStart] = 0; // filter: none
+        raw[rowStart] = 0;
         const shade = Math.round((y / Math.max(1, height - 1)) * 40);
         for (let x = 0; x < width; x++) {
             const p = rowStart + 1 + x * 3;
@@ -323,7 +256,6 @@ function encodeDemoPng(width, height, rgb) {
     }
     return pngOf(width, height, raw);
 }
-/** IHDR + one zlib-deflated IDAT + IEND around filtered RGB scanlines. */
 function pngOf(width, height, raw) {
     const crcTable = Array.from({ length: 256 }, (_, n) => {
         let c = n;
@@ -348,8 +280,8 @@ function pngOf(width, height, raw) {
     const ihdr = Buffer.alloc(13);
     ihdr.writeUInt32BE(width, 0);
     ihdr.writeUInt32BE(height, 4);
-    ihdr[8] = 8; // bit depth
-    ihdr[9] = 2; // color type: RGB
+    ihdr[8] = 8;
+    ihdr[9] = 2;
     const idat = deflateSync(raw);
     return Buffer.concat([
         Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
@@ -358,14 +290,7 @@ function pngOf(width, height, raw) {
         chunk("IEND", Buffer.alloc(0)),
     ]);
 }
-/** A real 640×400 PNG — comfortably past the 320×200 / meaningful-byte-size
- * floor a screenshot criterion needs to verify. */
 const DEMO_SCREENSHOT_PNG = encodeDemoPng(640, 400, [16, 24, 32]);
-/**
- * Seed a believable fleet mid-flight. The store MUST already carry the
- * demo stamp — this function refuses to seed an unfenced database, so no
- * caller can accidentally write synthetic history somewhere real.
- */
 export function seedDemo(store, repos, evidenceRoot, now) {
     if (!store.isDemo()) {
         throw new Error("seedDemo refuses an unfenced database — stamp it demo first");
@@ -376,21 +301,11 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         throw new Error(`demo approver: ${added.reason}`);
     const token = password;
     const hoursAgo = (hours) => new Date(now.getTime() - hours * 3_600_000);
-    // Configure the install before filing any task, exactly as a normal first
-    // run does. Every seeded scope can then be approved from the demo instead
-    // of inheriting an artificial "model not set" blocker.
     store.setPhaseConfig("installation", "build", "claude", "sonnet", "demo", now);
-    // Approvals bind EXACT routing for every phase (v47): the planner and
-    // reviewer name their models too, or no scope could file.
     store.setPhaseConfig("installation", "plan", "claude", "sonnet", "demo", now);
     store.setPhaseConfig("installation", "review", "claude", "sonnet", "demo", now);
-    // The strong tier (v47): the named agents high-risk, strict, screenshot-
-    // proof, and automerge routes reach for — configured, never inferred.
     store.setPhaseTierConfig("installation", "build", "strong", "claude", "opus", "demo", now);
     store.setPhaseTierConfig("installation", "review", "strong", "codex", "gpt-5-codex", "demo", now);
-    // The demo's builder goes through the REAL claim machinery, and the claim
-    // primitive proves identity and repo binding in-transaction — so the demo
-    // runner is registered like a real one, bound to both demo repos.
     const nightShift = register(store, {
         name: "night-shift-1",
         host: "demo",
@@ -398,9 +313,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         repos: [repos.api, repos.web],
         now: hoursAgo(30),
     });
-    // What the demo machine observed about each provider without spending
-    // (v47): claude installed but unproven (no non-spending login check),
-    // codex logged in, openrouter without a key, gemini not installed.
     store.recordProviderReadiness("night-shift-1", [
         { provider: "claude", state: "unknown", reason: "installed (claude 2.1.0); no non-spending login check exists — a real run is the proof", probe: "version" },
         { provider: "codex", state: "ready", reason: "installed (codex 0.62.0); logged in as demo@standing-orders.dev", probe: "identity" },
@@ -416,13 +328,8 @@ export function seedDemo(store, repos, evidenceRoot, now) {
             throw new Error(`seed task ${id}: ${made.reason}`);
         return made.id;
     };
-    // --- needs-you: an approval waiting -----------------------------------
     const planned = task("rotate-log-format", "Rotate the request-log format to JSON lines", repos.web, "Switch the request logger to JSON lines so the collector stops parsing free text. Keep the human console formatter for local dev. Migrate the two dashboards that grep the old format.");
     const plannedRef = store.refFor("built-in", planned).id;
-    // An explainable route (v47): the operator sized the change large and
-    // overrode the reviewer, so the ceremony shows a recommended leg, a
-    // strong-tier leg, and an overridden leg side by side, with the runner's
-    // readiness per provider.
     store.editTaskRoute(plannedRef, { by: "demo", authenticate: () => ({ ok: true }), size: { size: "large", risky: false } }, hoursAgo(3.5));
     store.editTaskRoute(plannedRef, { by: "demo", authenticate: () => ({ ok: true }), override: { phase: "review", provider: "claude", model: "opus" } }, hoursAgo(3.2));
     store.setPlanState(plannedRef, "drafted");
@@ -438,10 +345,7 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     });
     storeEvidence(store, evidenceRoot, plannerRun, "plan", "plan.md", Buffer.from(DEMO_EXECUTION_PLAN, "utf8"), "planner handoff (verified tree) [demo: synthetic]", hoursAgo(2.8));
     store.finishRun(plannerRun, { outcome: "built", reason: "plan-drafted", now: hoursAgo(2.8) });
-    // --- needs-you: a blocking decision -----------------------------------
     const asking = task("choose-retry-policy", "Choose the webhook retry policy", repos.api, "Give outbound webhooks a bounded retry policy with dead-lettering.");
-    // The build that parked this question ran under an approval (v48: a
-    // routed task opens no run without its sealed route).
     approve(store, asking, "demo", hoursAgo(3), store.getScope(asking)?.digest ?? "", token);
     const askingRun = store.startRun({
         taskRef: store.refFor("built-in", asking).id,
@@ -473,7 +377,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         ],
         recommendation: "exp",
     }, hoursAgo(1));
-    // --- building now ------------------------------------------------------
     const building = task("harden-webhook-retries", "Harden webhook delivery against slow consumers", repos.api, "Add per-endpoint concurrency caps and timeout budgets to webhook delivery.");
     const proposedBuilding = propose(store, {
         profile: DEMO_PROFILE,
@@ -488,11 +391,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     });
     approve(store, building, "demo", hoursAgo(20), proposedBuilding.digest, token);
     const buildingRef = store.refFor("built-in", building).id;
-    // Adaptive execution plans (v44): the planner's revision 1, and a prior
-    // builder attempt that found a stated dependency false and filed a
-    // bounded, evidence-linked, plan-only revision — auto-applied, no
-    // operator wait (c3, c4's plan-only path). The CURRENT live build below
-    // resumes under revision 2, exactly as a real fresh claim would.
     const buildingPlannerRun = store.startRun({
         taskRef: buildingRef,
         leaseId: "demo-lease-plan-2",
@@ -533,8 +431,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     }, hoursAgo(1.6));
     store.setRunPlanRevision(buildingPriorRun, buildingRev2Id, "demo-authority-digest-unchanged");
     store.finishRun(buildingPriorRun, { outcome: "refused", reason: "plan-revised", now: hoursAgo(1.6) });
-    // The board's "building" lane keys off a live claim — take one through
-    // the real claim machinery so the card wears worker and lease honestly.
     const liveClaim = acquire(store, buildingRef, "night-shift-1", {
         now: hoursAgo(0.4),
         token: nightShift.token,
@@ -542,7 +438,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     });
     const liveRun = store.startRun({
         taskRef: buildingRef,
-        // The claim's own lease, so the build reads as live: the run the task's current claim owns.
         leaseId: liveClaim.ok ? liveClaim.claim.leaseId : "demo-lease-live",
         runner: "night-shift-1",
         branch: `toolroll/${building}`,
@@ -552,8 +447,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     });
     store.setRunPlanRevision(liveRun, buildingRev2Id, "demo-authority-digest-unchanged");
     {
-        // Mixed milestone states (c1, c2): completed, in progress, blocked, and
-        // pending all shown at once on the live build's own checkpoint.
         const buildingRev2Parsed = parseExecutionPlanDocument(DEMO_BUILDING_PLAN_V2);
         if (!buildingRev2Parsed.ok)
             throw new Error("demo building revision 2 plan is malformed");
@@ -572,7 +465,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     }
     store.setRunPhase(liveRun, "agent-running");
     store.setTaskState(building, "running", hoursAgo(0.4));
-    // --- done recently: a finished run with a reviewable terminal diff ----
     const done = task("fix-payout-rounding", "Fix the payout rounding drift", repos.api, "Find and fix the half-cent drift in payout settlement; prove it with ledger-fixture tests.");
     const doneProposed = propose(store, {
         profile: DEMO_PROFILE,
@@ -587,9 +479,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         now: hoursAgo(27),
     });
     approve(store, done, "demo", hoursAgo(26), doneProposed.digest, token);
-    // Route provenance (v47): the demo's finished build names the exact
-    // agent it spent as, under the route its approval sealed — the same
-    // stamp a real admission writes.
     const doneRoute = store.approvedRouteOf(done);
     const doneRun = store.startRun({
         taskRef: store.refFor("built-in", done).id,
@@ -618,17 +507,9 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     };
     storeEvidence(store, evidenceRoot, doneRun, "diff-stat", "diff-stat.json", budgetedStatJson(stat), "parsed from git diff --numstat -z [demo: synthetic]", hoursAgo(8.5));
     storeEvidence(store, evidenceRoot, doneRun, "handoff", "handoff.json", demoHandoffBytes(store, doneRun, DEMO_HANDOFF), "composed at completion [demo: synthetic]", hoursAgo(8.4));
-    // The evidence bundle (Priority 2): a validated proof, its claimed
-    // screenshot stored as immutable image evidence, the plane's own re-run
-    // check, and the closed verdict — computed once, exactly as the real
-    // builder would leave it, so a fresh install sees the finished feature.
     storeEvidence(store, evidenceRoot, doneRun, "proof", "proof.json", Buffer.from(JSON.stringify(DEMO_PROOF, null, 2), "utf8"), "agent-authored proof (validated, re-serialized) [demo: synthetic]", hoursAgo(8.4));
     storeEvidence(store, evidenceRoot, doneRun, "screenshot", "screenshot-demo.png", DEMO_SCREENSHOT_PNG, "agent-claimed screenshot at evidence/payout-dashboard.png (validated png) [demo: synthetic]", hoursAgo(8.4));
     storeEvidence(store, evidenceRoot, doneRun, "check-log", "check-log.txt", Buffer.from(`$ npm test\n(exit 0)\n\n--- stdout ---\n214 tests passed.\n\n--- stderr ---\n`, "utf8"), `sh -c "npm test" (exit 0) [demo: synthetic]`, hoursAgo(8.4));
-    // The verdict AND the criterion-to-evidence matrix are computed by the
-    // real adjudicate() — same function, same rules the builder runs —
-    // never hand-authored, so the seeded sandbox shows exactly what the
-    // feature actually renders, dimensions read from the real PNG above.
     const demoProofParse = parseProof(JSON.stringify(DEMO_PROOF));
     const demoPngDims = imageDimensions(DEMO_SCREENSHOT_PNG, "png");
     const demoAdjudicated = adjudicate({
@@ -646,7 +527,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     store.finishRun(doneRun, { outcome: "built", committed: true, now: hoursAgo(8.4) });
     store.setTaskState(done, "done", hoursAgo(8.4));
     store.addRunNote(doneRun, "demo", "Reviewed the diff — the fixture numbers check out. Shipping.", hoursAgo(3));
-    // --- attention: a failed attempt --------------------------------------
     const failed = task("retire-legacy-flag", "Retire the legacy payout feature flag", repos.api, "Remove LEGACY_PAYOUT and every branch behind it.");
     const failedProposed = propose(store, {
         profile: DEMO_PROFILE,
@@ -667,10 +547,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         now: hoursAgo(6),
         ...presentedRoute(store, store.refFor("built-in", failed).id, "builder"),
     });
-    // What the failed build left: its saved changes, its report and the
-    // machine's reading of them. It removed the flag from settlement but left
-    // the admin override reading it, and said so in its own note — so the
-    // signed requirement is missed, and the task card can name it.
     store.stampRun(failedRun, { baseRevision: "4b825dc642cb6eb9a060e54bf8d69288fbee4904", scopeDigest: failedProposed.digest });
     store.recordOutcomeFacts(failedRun, { headRevision: "5a1f0c7e2b9d4e6f8a0b1c2d3e4f5a6b7c8d9e0f" });
     storeEvidence(store, evidenceRoot, failedRun, "terminal-diff", "terminal-diff.patch", Buffer.from(DEMO_FAILED_PATCH, "utf8"), "git diff --no-ext-diff --no-textconv --no-color 4b825dc6..HEAD (exit 0) [demo: synthetic]", hoursAgo(5.6));
@@ -701,12 +577,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         now: hoursAgo(5.5),
     });
     store.setTaskState(failed, "failed", hoursAgo(5.5));
-    // --- attention: needs verification (manual-review, unaccepted) --------
-    // Acceptance Contract v2's own review finding, made visible: a signed
-    // rubric can require a human's eyes ("manual-review" evidence), and
-    // that alone must cap the build below verified/attested until an
-    // operator explicitly accepts it — the SAME "accept anyway" act a
-    // short/refuted proof already uses, never a new mechanism.
     const copyReview = task("confirm-empty-state-copy", "Confirm the new inbox empty-state copy reads well", repos.web, "Rewrite the inbox's empty-state copy so it explains why nothing is there yet.");
     const copyReviewProposed = propose(store, {
         profile: DEMO_PROFILE,
@@ -763,12 +633,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     store.saveProofVerdict(copyReviewRun, copyReviewAdjudicated.verdict, copyReviewAdjudicated.reasons, hoursAgo(3.5), copyReviewAdjudicated.matrix);
     store.finishRun(copyReviewRun, { outcome: "built", committed: true, now: hoursAgo(3.5) });
     store.setTaskState(copyReview, "done", hoursAgo(3.5));
-    // --- reviewed + repaired: an independent reviewer contradicts a signed
-    // criterion, and the bounded repair loop drafts one unapproved fix
-    // (evidence-review-v1) — every step through the REAL functions the tick
-    // itself runs: adjudicate(), addReviewerComments/ingestCriterionReviews
-    // (the same fold reviewPass performs), and maybeTriggerRepair. Nothing
-    // here hand-authors a verdict or a chain row.
     const reviewed = task("guard-payout-limiter", "Guard the payout limiter against concurrent settlement", repos.api, "Add a per-account concurrency guard so two settlements never race the same payout limiter.");
     const reviewedProposed = propose(store, {
         profile: DEMO_PROFILE,
@@ -810,10 +674,7 @@ export function seedDemo(store, repos, evidenceRoot, now) {
    return settle(cents, currentRate(accountId));
  }
 `;
-    const reviewedDiffArtifact = storeEvidence(store, evidenceRoot, reviewedRun, "terminal-diff", "terminal-diff.patch", Buffer.from(DEMO_REPAIR_PATCH, "utf8"), "git diff --no-ext-diff --no-textconv --no-color 4b825dc6..HEAD (exit 0) [demo: synthetic]", hoursAgo(4.6), 
-    // The seeded capture says its exit 0 in a typed verdict too: the real
-    // review door reads THIS, and it refuses a diff with no verdict.
-    { captureStatus: "ok" });
+    const reviewedDiffArtifact = storeEvidence(store, evidenceRoot, reviewedRun, "terminal-diff", "terminal-diff.patch", Buffer.from(DEMO_REPAIR_PATCH, "utf8"), "git diff --no-ext-diff --no-textconv --no-color 4b825dc6..HEAD (exit 0) [demo: synthetic]", hoursAgo(4.6), { captureStatus: "ok" });
     const reviewedStat = {
         schema: 1,
         base: "4b825dc642cb6eb9a060e54bf8d69288fbee4904",
@@ -854,8 +715,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         screenshots: [],
     };
     const reviewedProofArtifact = storeEvidence(store, evidenceRoot, reviewedRun, "proof", "proof.json", Buffer.from(JSON.stringify(DEMO_REPAIR_PROOF, null, 2), "utf8"), "agent-authored proof (validated, re-serialized) [demo: synthetic]", hoursAgo(4.5));
-    // The verdict, computed by the real adjudicate() — the proof's OWN
-    // self-declared "met" reads clean until the independent reviewer looks.
     const reviewedProofParse = parseProof(JSON.stringify(DEMO_REPAIR_PROOF));
     const reviewedAdjudicated = adjudicate({
         proofArtifactPresent: true,
@@ -871,15 +730,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     store.saveProofVerdict(reviewedRun, reviewedAdjudicated.verdict, reviewedAdjudicated.reasons, hoursAgo(4.4), reviewedAdjudicated.matrix);
     store.finishRun(reviewedRun, { outcome: "built", committed: true, now: hoursAgo(4.4) });
     store.setTaskState(reviewed, "done", hoursAgo(4.4));
-    // The independent reviewer: a real reviewer run, its comments AND its
-    // criterion judgement ingested through the SAME atomic store method
-    // reviewPass itself calls (ingestReview) — the fold is the real
-    // foldReview, never a hand-authored verdict, and the bindings are the
-    // real scope digest and proof artifact this run actually carries.
-    // The review is asked for through the real door and answered through
-    // the real admission (raw authority repair): the reviewer run consumes
-    // the open request inside its own insert, exactly as the review pass
-    // does — a reviewer row opens no other way.
     const reviewAsked = store.requestReview(reviewedRun, "alex", hoursAgo(3.95));
     if (!reviewAsked.ok)
         throw new Error(`demo: the seeded review could not be requested (${reviewAsked.reason})`);
@@ -933,22 +783,16 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     }, hoursAgo(3.9));
     if (folded === null)
         throw new Error("seed reviewed+repaired: the fold produced nothing");
-    // The bounded repair loop's own trigger — the SAME function the tick
-    // calls after a review pass settles a verdict. No mode is signed, so
-    // the draft it composes waits unapproved, exactly as the default road
-    // promises.
     const repairTrigger = maybeTriggerRepair(store, repos.api, evidenceRoot, reviewedRun, folded.verdict, hoursAgo(3.9));
     if (repairTrigger.kind !== "drafted") {
         throw new Error(`seed reviewed+repaired: expected a draft, got ${repairTrigger.kind}`);
     }
-    // --- waiting: a repairable terminal dependency and a hold ---------------
     task("design-tokens", "Extract the design tokens package", repos.web);
     task("ship-dark-mode", "Ship dark mode", repos.web);
     store.addEdge("ship-dark-mode", "design-tokens", {});
     store.cancelTask("design-tokens", hoursAgo(10), "the token package was superseded");
     const held = task("migrate-billing", "Migrate billing exports to the new vendor", repos.api);
     store.hold(store.refFor("built-in", held).id, "waiting on the vendor sandbox account", null, hoursAgo(12));
-    // --- a scheduled flow, waiting for someone to turn its schedule on -----
     const nightly = createScheduledFlow(store, {
         repo: realpathSync(repos.api), name: "Nightly dependency refresh", stem: "nightly-deps", schedule: "daily:03:30", by: "demo",
         terms: {
@@ -960,7 +804,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     }, hoursAgo(70));
     if (!nightly.ok)
         throw new Error(`seed scheduled flow: ${nightly.message}`);
-    // --- the outer loop: an opened PR with observed checks ----------------
     const pub = store.createPublicationIntent({
         run: doneRun,
         taskRef: store.refFor("built-in", done).id,
@@ -978,8 +821,6 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     seedDemoFlows(store, repos.web, now);
     return { login: { name: "demo", password }, repos: [repos.api, repos.web] };
 }
-/** Two tiny real repositories, so repo-bound surfaces have something true
- * to point at. git is optional here — a plain directory still demos. */
 export function makeDemoRepos(root) {
     const make = (name, files) => {
         const dir = join(root, name);
@@ -998,7 +839,6 @@ export function makeDemoRepos(root) {
             });
         }
         catch {
-            // No git on PATH: a plain directory still serves the demo.
         }
         return dir;
     };
@@ -1015,19 +855,10 @@ export function makeDemoRepos(root) {
         }),
     };
 }
-/** The sandbox: one directory holding everything, stamped before seeding. */
-/**
- * Two flows mid-flight (v88), so the canvas has something to show on a first
- * look: a support desk Jev has sorted, and customer replies Claude drafted —
- * one waiting for the demo person's decision. Every decision and draft is
- * written as the real steps write them; nothing runs, and nothing spends.
- */
 function seedDemoFlows(store, folder, now) {
-    // Projects are known by their real path (macOS's /var is /private/var): the Flows page matches on it.
     const repo = realpathSync(folder);
     const at = (minutes) => new Date(now.getTime() - minutes * 60_000);
     const template = (id) => JSON.stringify(FLOW_TEMPLATES.find(one => one.id === id).definition);
-    // Cards arrive where their flow starts; a step's run is recorded, then the card moves where it said.
     const step = (card, stage, kind, when, result, output, extra = {}) => {
         store.claimFlowStep({ card, entry: store.getFlowCard(card).entry, stage, kind, script: null, scriptVersion: null }, when);
         store.finishFlowStep(card, store.getFlowCard(card).entry, { state: "passed", result, durationMs: kind === "sort" ? 180 : 4200, ...extra }, when);
@@ -1069,12 +900,10 @@ export function createDemoSandbox(now) {
     const sandbox = mkdtempSync(join(tmpdir(), "toolroll-demo-"));
     const repos = makeDemoRepos(sandbox);
     const store = openStore(join(sandbox, "orders.db"));
-    // The stamp precedes every row — a half-seeded sandbox is still fenced.
     store.recordInstallationFact("demo", "1", now);
     const evidenceRoot = join(sandbox, "evidence");
     mkdirSync(evidenceRoot, { recursive: true });
     const seed = seedDemo(store, repos, evidenceRoot, now);
-    // v105: the plans' windows as Claude and Codex last said them, and a project budget (Tasks shows them as tiles).
     const later = (hours) => new Date(now.getTime() + hours * 3_600_000).toISOString();
     store.recordProviderLimits({ provider: "claude", plan: null, windows: [
             { window: "five_hour", usedPercent: 48, windowMinutes: 300, resetsAt: later(2.2), reached: false },
@@ -1196,7 +1025,6 @@ const DEMO_PLANS = {
         ],
     },
 };
-/** The files each plan changes, as they stand before the change. */
 function demoLeadFiles(project) {
     const files = {};
     for (const plan of Object.values(DEMO_PLANS)) {
@@ -1208,7 +1036,6 @@ function demoLeadFiles(project) {
     }
     return files;
 }
-/** The scripted lead's choice: a plan named by the request's words, else the default. */
 export function pickDemoPlan(text) {
     const words = text.toLowerCase();
     if (/\b(tests?|flaky|flake|spec|ci)\b/.test(words))
@@ -1221,7 +1048,6 @@ export function pickDemoPlan(text) {
         return DEMO_PLANS.bug;
     return DEMO_PLANS.default;
 }
-/** A unified diff of one small file, one hunk, from a longest-common-subsequence walk. */
 function unifiedDiff(file) {
     const split = (text) => (text === null ? [] : text.replace(/\n$/, "").split("\n"));
     const a = split(file.before);
@@ -1258,7 +1084,6 @@ function unifiedDiff(file) {
         : `diff --git a/${file.path} b/${file.path}\n--- a/${file.path}\n+++ b/${file.path}\n@@ -1,${a.length} +1,${b.length} @@\n`;
     return { patch: `${head}${lines.join("\n")}\n`, additions, deletions };
 }
-/** A plain mock of the screen the plan's screenshot shows: a header, rows and one coloured result mark. */
 function demoScreenshot(accent) {
     const width = 960;
     const height = 600;
@@ -1294,12 +1119,6 @@ function encodePngPixels(width, height, pixels) {
 }
 const DEMO_STAGES = ["planning", "building", "checking"];
 const DEMO_MAX_EXCHANGES = 40;
-/**
- * The scripted lead. `stepMs` is one beat: planning takes one, building two
- * (one per progress line), checks one, so a build lands Ready in four beats.
- * State advances on a timer AND whenever someone reads, so a page and the
- * Tasks list agree without anyone polling.
- */
 export function createDemoLead(input) {
     const { store, repos, evidenceRoot, approver, token } = input;
     if (!store.isDemo())
@@ -1311,8 +1130,6 @@ export function createDemoLead(input) {
     let changes = 0;
     let nextId = 1;
     const touched = () => { changes++; };
-    // The scripted crew is a registered builder, so Tasks reads a demo build
-    // as a live claim on a connected builder — registered on first use only.
     const CREW = "demo-crew";
     let crewToken = null;
     const crewSeen = (at) => {
@@ -1342,21 +1159,18 @@ export function createDemoLead(input) {
                 return id;
         }
     };
-    /** Each stage's store facts, written once, in order. False when the stage can't start (its task was closed). */
     const enterStage = (exchange, stage, at) => {
         const plan = exchange.plan;
         const taskId = exchange.taskId;
         const ref = store.refFor("built-in", taskId).id;
         if (stage === 1) {
             const repo = repoOf(plan);
-            // The project check the result reports, approved before the attempt starts — as `verify set` would.
             const command = store.liveVerifyCommand(store.refById(ref)?.repo ?? repo);
             if (command === null || command.command !== DEMO_CHECK_COMMAND) {
                 store.setVerifyCommand({ repo: store.refById(ref)?.repo ?? repo, command: DEMO_CHECK_COMMAND, timeoutMs: 120_000, approvedBy: approver }, at);
             }
             const route = store.approvedRouteOf(taskId);
             const claimed = acquire(store, ref, CREW, { now: at, token: crewSeen(at), ttlMs: 10 * 60_000 });
-            // A task closed meanwhile (cancelled, say) is not built: no run starts and the story stops here.
             if (!claimed.ok && (claimed.reason === "closed" || claimed.reason === "no-task"))
                 return false;
             const leaseId = claimed.ok ? claimed.claim.leaseId : `demo-lease-${taskId}`;
@@ -1453,7 +1267,6 @@ export function createDemoLead(input) {
             if (exchange.state !== "working" || exchange.approvedAt === null)
                 continue;
             const beats = Math.floor((now.getTime() - exchange.approvedAt) / stepMs);
-            // planning: beat 0; building: beats 1–2; checks: beat 3; Ready: beat 4.
             const target = beats >= 4 ? 3 : beats >= 3 ? 2 : beats >= 1 ? 1 : 0;
             const current = exchange.stage === null ? -1 : DEMO_STAGES.indexOf(exchange.stage);
             for (let stage = current + 1; stage <= target; stage++) {
@@ -1487,7 +1300,7 @@ export function createDemoLead(input) {
                 try {
                     advance(clock());
                 }
-                catch { /* the next beat or background pass advances it again */ }
+                catch { }
             }, beat * stepMs + 20);
             timer.unref();
             timers.add(timer);
@@ -1495,8 +1308,6 @@ export function createDemoLead(input) {
         void exchange;
     };
     return {
-        // Reads only (docs/plans/get-side-effects.md): the beat timers, the console's background pass and the person's own
-        // acts move the story on, never a page visit.
         exchanges: () => list,
         version: () => changes,
         ask(text, now) {

package/dist/deploy-gate.js

@@ -1,17 +1,9 @@
-/**
- * The deployment gate, in the runtime that is releasing (docs/plans/approval-policy.md §1.7): whether a candidate run
- * may be deployed at all — a person approved its scope, its exact result passed the approved check and was marked
- * complete, and nothing still blocks it. `toolroll release` asks this BEFORE it starts anything from the candidate's
- * checkout, so the candidate's own scripts never decide their own deployment. (scripts/deploy-candidate.mjs keeps the
- * same checks for the deployment script, proven again there with the installed runtime's modules.)
- */
 import { assignmentOf } from "./assignment.js";
 import { liveReleaseOf, personApprovalOf, releaseApprovalOf } from "./scope.js";
 import { verificationEvidence } from "./verification-evidence.js";
 import { refArchived } from "./task-archive.js";
 import { releaseCiRunningOf } from "./release-ci-hold.js";
 import { nightlyDebtHold } from "./nightly-github.js";
-/** Whether run `runId` is a deployable candidate now, read only from the plane's records and this runtime's code. */
 export function deploymentGate(store, input) {
     const refuse = (message) => ({ ok: false, message });
     const run = store.getRun(input.runId);
@@ -20,9 +12,6 @@ export function deploymentGate(store, input) {
     const head = run?.headRevision ?? null;
     if (run === null || ref === null || head === null)
         return refuse(`Run ${input.runId} is not a built candidate.`);
-    // `task regate` reruns the approved check on the last built commit and records no-change: a candidate only for that commit.
-    // A prepared candidate's build records a commit of its own holding exactly the candidate's tree; its rerun under the same
-    // signed scope is the same check of that commit (the digest is held to the approved one below).
     const built = store.runsFor(run.taskRef).find(one => one.id < input.runId && one.role === "builder" && one.outcome === "built");
     const regated = run.outcome === "no-change" && built?.headRevision === head &&
         (scope?.candidate === head || ((scope?.candidate ?? null) !== null && built.scopeDigest === run.scopeDigest));
@@ -30,23 +19,15 @@ export function deploymentGate(store, input) {
         return refuse(`Run ${input.runId} is not a built candidate at ${head.slice(0, 7)}.`);
     if (scope === null || scope.approvedDigest !== scope.digest || scope.digest !== run.scopeDigest)
         return refuse("The run's signed scope is no longer the approved one.");
-    // A put-away task (v145, task-tidy.md) deploys nothing: restore it first.
     if (refArchived(store, run.taskRef))
         return refuse("This task is put away. Restore it before deploying.");
-    // A person may approve during CI, including a release without carry terms. Every deployment road must wait
-    // for the plane's exact-head observation, not only the release coordinator's polling loop.
     if (releaseCiRunningOf(store, ref.externalId) !== null)
         return refuse("This release still waits for GitHub CI. Resume it with `toolroll release`.");
-    // One approval per release (release-once.md): a release's task deploys only while its authority stands for it — the
-    // live predicate proves the anchor's person approval (a carried commit's own seal is never a person's). Any other task
-    // needs a person's approval of its own.
     const release = liveReleaseOf(store, ref.externalId, "deploy", input.now);
     if (release.applies && !release.ok)
         return refuse(`This release can't deploy: ${release.why}.`);
     const anchorPerson = release.applies && release.ok
         ? (input.releaseFlow === true ? releaseApprovalOf(store, release.authority.anchorTask, input.now) : personApprovalOf(store, release.authority.anchorTask)) : null;
-    // GitHub's nightly lane debt (nightly-github.ts) holds every deploy of the project, a person's approval or not,
-    // unless this exact candidate re-ran that lane after the failure and passed (an exemption read at the boundary).
     if (ref.repo !== null) {
         const nightly = nightlyDebtHold(store, { repo: ref.repo, taskId: ref.externalId, candidate: scope?.candidate ?? head, phase: "deploy", release: release.applies, now: input.now });
         if (nightly !== null)
@@ -67,7 +48,6 @@ export function deploymentGate(store, input) {
     }
     const live = ref.repo === null ? null : store.liveVerifyCommand(ref.repo);
     const result = gate["result"];
-    // A release check's coverage (receipt version 3): partial or identity-removed never deploys, whatever the exit.
     if (gate["coverage"] !== undefined && gate["coverage"] !== "full" && gate["coverage"] !== "composed")
         return refuse(`The release check didn't cover this candidate (${String(gate["coverage"])}).`);
     const command = gate["command"];