toolroll 0.9.103 → 0.9.105

package/dist/release-carry.js

@@ -1,24 +1,3 @@
-/**
- * One approval per release (docs/plans/release-once.md, part 1): which later commits carry a person's release approval,
- * and the proof that one does.
- *
- * A later commit carries only when every change since the approved commit is tests, docs or the changelog (CARRY_RULES,
- * each commit against its parent and the whole range), within the limits, under the stricter of the sealed and the
- * current policy — AND the production build is byte-for-byte the approved one. The proof runs in this order and nothing
- * from the candidate runs until the read-only preflight passed:
- *
- *   1. an idempotent retry first (a carry already written for this commit, still standing, is returned as it is);
- *   2. the read-only preflight over objects hashed here (commit-extract.ts) and the live authority (scope.ts
- *      liveReleaseOf) — ancestry through the current tip, no merges, the rules, the limits, the grant and access;
- *   3. both sides built inside the fence with no network, installed from the lockfile with no scripts, and their output
- *      digested as untrusted (process group gone, lstat, O_NOFOLLOW, regular files only, contained paths);
- *   4. one BEGIN IMMEDIATE transaction that proves every mutable fact again and writes the carry (store.ts
- *      carryReleaseApproval).
- *
- * The limits keep a carried change small enough to review; they are not a security boundary. Authority decisions here
- * read only Toolroll's records and verified objects. (Coverage, in release-recheck.ts, trusts test code by Alex's
- * explicit decision; nothing here does.)
- */
 import { prepareProtectedStorage, storageRefusalOf } from "./protected-storage.js";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, constants, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, writeFileSync } from "node:fs";
@@ -38,45 +17,30 @@ import { proxyEnv, startEgressProxy } from "./egress.js";
 import { liveReleaseOf } from "./scope.js";
 import { UNSANDBOXED_CARRY_ACTION, carriesUnsandboxed } from "./release-authority.js";
 import { carryReleaseApproval, releaseAuthority, releaseCarryTo, sealAnchorArtifact, taskCheckStamp, } from "./store.js";
-// ------------------------------------------------------------------ the rules
-/** The journey scripts: tests, by Alex's decision (they carry). */
 export const JOURNEY_SCRIPTS = Object.freeze(["scripts/app-e2e.mjs", "scripts/flows-e2e.mjs"]);
-/** What carries (version 1). Everything else asks again — including every other `test/**` or `scripts/**` file (the
- * harness, what it imports, helpers and fixtures), so no harness file can slip in under a class. */
 export const CARRY_RULES = Object.freeze({
     version: CARRY_RULES_VERSION,
     classes: Object.freeze([
         { name: "unit tests", matches: (path) => /^src\/.+\.test\.ts$/.test(path) },
         { name: "journey scripts", matches: (path) => JOURNEY_SCRIPTS.includes(path) },
-        // Rules read the normalized, lower-case path (rulePath).
         { name: "changelog", matches: (path) => path === "changelog.md" },
-        // An allowlist (security review): Markdown under docs/, and the root README. Never any other .md anywhere.
         { name: "docs", matches: (path) => (path.startsWith("docs/") && path.endsWith(".md")) || path === "readme.md" },
     ]),
-    /** Never carry, even when a class above matches them. */
     never: Object.freeze([
-        // Agent instructions and policy, anywhere, whatever the case.
         { why: "it's an agent or security policy file", matches: (path) => /(^|\/)(AGENTS|CLAUDE|GEMINI|SECURITY)\.md$/i.test(path) },
-        // Agent and CI configuration folders, anywhere: they steer agents and checks.
         { why: "it configures agents or CI", matches: (path) => /(^|\/)\.(claude|codex|gemini|cursor|github)(\/|$)/i.test(path) },
-        // Docs agents are told to follow (AGENTS.md names the testing guide; plans are the input documents tasks build
-        // from). Nothing under docs/ is read by the product itself: its guides are compiled into src/guides.ts.
         { why: "agents follow it as instructions", matches: (path) => /^docs\/plans\//.test(path) || path === "docs/testing.md" },
         { why: "it's part of the test harness, a helper or a fixture", matches: (path) => path.startsWith("test/") },
         { why: "it's part of the test harness", matches: (path) => path.startsWith("scripts/") && !JOURNEY_SCRIPTS.includes(path) },
         { why: "it's part of the test harness", matches: (path) => /(^|\/)vitest\.config\.[cm]?[jt]s$/.test(path) },
     ]),
 });
-/** The limits (Alex, 2026-10-25): 400 changed lines and 20 files after the approval, 800 lines of churn. */
 export const CARRY_LIMITS = Object.freeze({ lines: 400, files: 20, churn: 800 });
-/** "Ask for every release commit": a project setting, newest choice wins (a ledger row each); off by default. */
 export const ASK_EVERY_COMMIT_ACTION = "release carrying changed";
 export function asksEveryReleaseCommit(store, repo) {
     const row = store.handle.prepare("SELECT outcome FROM action_ledger WHERE repo = ? AND action = ? ORDER BY id DESC LIMIT 1").get(repo, ASK_EVERY_COMMIT_ACTION);
     return row !== undefined && row["outcome"] === "ask";
 }
-/** Set "Carry release approvals when checks aren't sandboxed". `by` is who set it; turning it on is only ever called
- * after a person's own proof (release-cli.ts). */
 export function setUnsandboxedCarry(store, repo, on, by, now) {
     store.recordAction({ at: now.toISOString(), actor: by, repo, taskId: null, runId: null, action: UNSANDBOXED_CARRY_ACTION, outcome: on ? "on" : "off", source: "request",
         detail: on ? "Carry release approvals when checks aren't sandboxed: later test-only commits run outside the sandbox without being shown first" : "Release approvals carry only when checks are sandboxed" });
@@ -85,7 +49,6 @@ export function setAskEveryReleaseCommit(store, repo, ask, by, now) {
     store.recordAction({ at: now.toISOString(), actor: by, repo, taskId: null, runId: null, action: ASK_EVERY_COMMIT_ACTION, outcome: ask ? "ask" : "carry", source: "request",
         detail: ask ? "Ask for every release commit" : "Later test-only commits ship under the release approval" });
 }
-/** The effective policy now: the runtime rules, the project's protected paths and the limits. */
 export function effectivePolicy(store, repo, options = {}) {
     const rules = store.approvalRules(repo);
     return {
@@ -94,8 +57,6 @@ export function effectivePolicy(store, repo, options = {}) {
         unsandboxedCarry: carriesUnsandboxed(store, repo),
     };
 }
-/** The stricter of two policies: what either protects asks again, the lower limit wins, either one's "ask" asks. Null
- * when either is a policy this runtime doesn't know (then nothing carries). */
 export function stricterOf(a, b) {
     if (a === null || b === null || !readReleasePolicy(a).ok || !readReleasePolicy(b).ok)
         return null;
@@ -103,26 +64,13 @@ export function stricterOf(a, b) {
         version: 1, rules: CARRY_RULES_VERSION, carry: a.carry && b.carry, protectProject: a.protectProject || b.protectProject,
         protectedPaths: [...new Set([...a.protectedPaths, ...b.protectedPaths])].sort(),
         limits: { lines: Math.min(a.limits.lines, b.limits.lines), files: Math.min(a.limits.files, b.limits.files), churn: Math.min(a.limits.churn, b.limits.churn) },
-        // Carrying when checks aren't sandboxed only while both allow it: turning it on later never widens an approval.
         unsandboxedCarry: a.unsandboxedCarry === true && b.unsandboxedCarry === true,
     };
 }
-/**
- * A path as the rules compare it: lower case (a case-insensitive file system reads docs/Plans as docs/plans), each part
- * without the trailing dots and spaces Windows drops, and no empty or `.` parts (a verified tree never holds them, but
- * the rules don't rely on that).
- */
 export function rulePath(path) {
     return path.toLowerCase().split("/").map(part => part.replace(/[. ]+$/, "")).filter(part => part !== "" && part !== ".").join("/");
 }
-/** Tests by the rules' classes: what the existing-test rule holds still. */
 const carriedTest = (normal) => CARRY_RULES.classes.some(one => (one.name === "unit tests" || one.name === "journey scripts") && one.matches(normal));
-/**
- * Why one changed path doesn't carry, in words, or null when it does. Every rule reads the normalized path. `fresh`: the
- * paths that didn't exist at the approved commit. A test that was there stays exactly as it was (H4): new tests go in new
- * files. Only "unchanged" holds up, since `vi.mock` hoists and a top-level hook reaches every case above it, so an
- * appended line can disarm what it follows.
- */
 export function changeRefusal(change, policy, fresh = new Set()) {
     const path = change.path;
     const normal = rulePath(path);
@@ -148,12 +96,6 @@ export function changeRefusal(change, policy, fresh = new Set()) {
         return `${path} changes an existing test, and new tests go in a new file`;
     return null;
 }
-// ------------------------------------------------------------------ release terms
-/**
- * A release scope's terms, from the plane's own records: the project's repository, the approved commit and its
- * verified tree, the effective policy, the live release check grant and the check access (only the fence), and the
- * expiry. Null with why when the release can't carry at all (it then asks for every commit, as before).
- */
 export function releaseTermsFor(store, input) {
     const gitDir = projectGitDir(input.repo);
     if (gitDir === null)
@@ -166,8 +108,6 @@ export function releaseTermsFor(store, input) {
         return { ok: false, why: "the project has no approved release check" };
     const access = store.projectCheckAccess(input.repo);
     const policy = effectivePolicy(store, input.repo, { noCarry: input.noCarry ?? false });
-    // Checks outside the sandbox carry only with the project's "Carry release approvals when checks aren't sandboxed" on,
-    // sealed here: turning it on after this approval never carries for it.
     if (access !== "sandboxed" && policy.unsandboxedCarry !== true) {
         return { ok: false, why: "the project's checks run outside the sandbox, so later commits always ask again (unless “Carry release approvals when checks aren't sandboxed” is on)" };
     }
@@ -178,13 +118,6 @@ export function releaseTermsFor(store, input) {
             expiresAt: new Date(input.now.getTime() + 3 * 24 * 60 * 60_000).toISOString(),
         } };
 }
-/**
- * A release check's purpose (docs/plans/pipeline-speed.md, P0), for a release whose terms can't be made (its checks run
- * outside the sandbox, or carrying is off): from the plane's own records — the project's repository, the approved commit
- * and its verified tree, the live release check grant and the check access. It never carries a later commit; it marks
- * this exact candidate as a release's check (strict report rules, no CI stand-in, the plane's own rerun after confirmed
- * infrastructure on the same candidate under the same approval). Null with why when even that can't be read.
- */
 export function releaseCheckPurposeFor(store, input) {
     const gitDir = projectGitDir(input.repo);
     if (gitDir === null)
@@ -200,10 +133,6 @@ export function releaseCheckPurposeFor(store, input) {
             approvedSha: input.candidate, approvedTree: commit.value.tree, grant: { id: grant.id, digest: grant.digest }, access: store.projectCheckAccess(input.repo),
         } };
 }
-/**
- * Step 2, read-only: nothing from the candidate is installed, built or run here. Objects come from the project's own
- * Git directory as Toolroll records it, hashed here; the authority is read live.
- */
 export function preflightCarry(store, input) {
     const refuse = (reason, message, path) => ({ ok: false, reason, message, ...(path === undefined ? {} : { path }) });
     const a = releaseAuthority(store, input.authority);
@@ -220,11 +149,9 @@ export function preflightCarry(store, input) {
         return refuse("authority", "This Toolroll doesn't know the release's carry rules; update Toolroll first.");
     if (!policy.carry)
         return refuse("rules", "This project asks for every release commit.");
-    // Checks outside the sandbox (at the approval or now): only when the sealed setting and the current one both allow it.
     if ((a.accessDigest !== "sandboxed" || store.projectCheckAccess(a.repo) !== "sandboxed") && policy.unsandboxedCarry !== true) {
         return refuse("rules", "This project's checks run outside the sandbox, and carrying release approvals then wasn't on when this release was approved, or is off now.");
     }
-    // A carry leans on the check the release already had: it must be shown to have stayed within what was approved (H2).
     const ran = taskCheckStamp(store, a.repo, a.tipTask);
     const unshown = ran === null ? null : stampRefusal(ran.reading, checkAccessOf(a.accessDigest));
     if (unshown !== null)
@@ -245,7 +172,6 @@ export function preflightCarry(store, input) {
     const merge = chain.find(one => one.parents.length !== 1);
     if (merge !== undefined)
         return refuse("shape", `${merge.id.slice(0, 7)} is a merge commit; a carried change is plain commits.`);
-    // Each commit against its parent, oldest first.
     const ordered = [...chain].reverse();
     const treeOf = new Map([[a.approvedSha, a.approvedTree]]);
     for (const commit of ordered)
@@ -276,8 +202,6 @@ export function preflightCarry(store, input) {
         if (why !== null)
             return refuse("rules", `Since the approval: ${why}.`, change.path);
     }
-    // No new test may reach into another (H4). Read from the verified tree, never from a checkout.
-    // By the rules' own classifier, so everything that carries as a test is read (a new journey script too).
     const newTests = whole.value.filter(one => one.kind === "added" && carriedTest(rulePath(one.path))).map(one => one.path);
     const added = newTests.length === 0 ? null : verifiedBlobs(gitDir, chain[0].tree, newTests);
     if (added !== null && !added.ok)
@@ -298,14 +222,11 @@ export function preflightCarry(store, input) {
     return { ok: true, plan: { authority: a, to: input.to, toTree: chain[0].tree, commits, changedLines, files: whole.value.length, churn, policy,
             currentPolicyDigest: releasePolicyDigest(effectivePolicy(store, a.repo)) } };
 }
-/** The default build runner: the OS fence, writes only where named, and no network — its only way out is a proxy of its
- * own that allows no host. No fence on this machine, no build. */
 export function fencedBuildRunner(store) {
     return async (file, args, options) => {
         if (!macosFenceAvailable() && !linuxFenceAvailable()) {
             return { code: 1, stdout: "", stderr: "This machine can't confine the build (no macOS sandbox, no working bubblewrap), so it didn't run.\n", timedOut: false, notFound: false };
         }
-        // The storage check, awaited off this thread (protected-storage.ts); its words are the build's when it can't finish.
         let storage;
         try {
             storage = await prepareProtectedStorage();
@@ -335,7 +256,6 @@ const realScanIO = () => ({
     procIdentity: pid => {
         const status = readFileSync(`/proc/${pid}/status`, "utf8");
         const uids = /^Uid:\s+(\d+)\s+(\d+)/m.exec(status);
-        // The command name (field 2) is in parentheses and may hold spaces or parentheses: fields count from the last ")".
         const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
         const start = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19]);
         if (uids === null || !Number.isSafeInteger(start))
@@ -377,7 +297,6 @@ const realScanIO = () => ({
             text = execFileSync("ps", ["-o", "pid=,uid=,stat=,lstart=", "-p", pids.join(",")], { encoding: "utf8", env: { ...process.env, LC_ALL: "C", TZ: "UTC" }, timeout: 20_000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
         }
         catch (error) {
-            // ps exits 1 when some of the pids are gone; what it printed is the rest. Anything else: no answer.
             const e = error;
             if (e.status !== 1 || e.signal != null)
                 return null;
@@ -401,16 +320,6 @@ const realScanIO = () => ({
         return error.code === "ESRCH";
     } },
 });
-/**
- * Pids whose working folder is inside `root` (lsof on macOS, /proc on Linux), or null when that can't be shown (the
- * caller refuses: nothing is digested unless it is shown that no writer remains). A process is passed over only when
- * it is gone, or provably runs as another user than the build; one of the build's own user that can't be read refuses.
- *
- * On Linux a fenced build can't leave one at all: the sandbox runtime starts every launch in a PID namespace of its own
- * (bwrap --unshare-pid, --die-with-parent), and when the build's process ends the kernel kills everything left in that
- * namespace, a detached or new-session child included, before the launch returns. The scan is the check for whatever
- * runs outside such a namespace (an unfenced runner) and the proof on macOS, where Seatbelt has no PID namespace.
- */
 export function processesInside(root, since, io = realScanIO()) {
     const inside = (cwd) => cwd === root || cwd.startsWith(`${root}/`);
     const code = (error) => error?.code;
@@ -435,8 +344,6 @@ export function processesInside(root, since, io = realScanIO()) {
                     continue;
                 if (code(error) !== "EACCES" && code(error) !== "EPERM")
                     return null;
-                // Unreadable: passed over only when it is gone by now, provably runs as another user (neither its real nor its
-                // effective uid is the build's), or provably started before the build did (so the build didn't start it).
                 let who;
                 try {
                     who = io.procIdentity(name);
@@ -448,7 +355,6 @@ export function processesInside(root, since, io = realScanIO()) {
                 }
                 if (io.uid >= 0 && !who.uids.includes(io.uid))
                     continue;
-                // A whole second earlier than the build began: tick rounding can't make the build's own child look older.
                 if (since?.ticks != null && who.startTicks < since.ticks.ticks - since.ticks.hz)
                     continue;
                 return null;
@@ -458,12 +364,10 @@ export function processesInside(root, since, io = realScanIO()) {
         }
         return found;
     }
-    // macOS: every process of the build's user, listed first; then lsof's cwd for each.
     const listed = io.processes();
     if (listed === null)
         return null;
     const out = io.lsof();
-    // lsof exits 1 when it couldn't read some process; anything else (a signal, a timeout, an overflow) is no listing.
     const complete = out.status === 0 && out.signal === null && out.code === null;
     const partial = out.status === 1 && out.signal === null && out.code !== "ETIMEDOUT" && out.code !== "ENOBUFS" && !/maxBuffer/i.test(out.code ?? "");
     if (!complete && !partial)
@@ -479,9 +383,6 @@ export function processesInside(root, since, io = realScanIO()) {
                 found.push(pid);
         }
     }
-    // A process of the build's own user whose folder lsof couldn't read refuses, unless a second look shows it gone, a
-    // zombie (it has ended: it holds no folder and writes nothing), another user's, or started a whole second before the
-    // build began (so the build didn't start it).
     const unread = listed.filter(one => one.uid === io.uid && one.pid !== io.pid && !one.zombie && !read.has(one.pid) && !io.gone(one.pid)).map(one => one.pid);
     if (unread.length > 0) {
         const again = io.describe(unread);
@@ -498,13 +399,7 @@ export function processesInside(root, since, io = realScanIO()) {
     }
     return [...new Set(found)];
 }
-/** Files left out of the artifact digest and listed as doc changes instead. */
 export const ARTIFACT_EXCLUDED = Object.freeze(["CHANGELOG.md", "README.md"]);
-/**
- * The digest of one built tree's production artifacts, read as untrusted: every entry walked with lstat, opened with
- * O_NOFOLLOW and checked again on the descriptor; only regular files inside `root` count; a symlink, a special file or a
- * path that escapes refuses. Each entry records path, mode and sha256.
- */
 export function digestTree(root, paths) {
     const realRoot = realpathSync(root);
     const entries = [];
@@ -523,7 +418,6 @@ export function digestTree(root, paths) {
             return { ok: false, message: `${path} is a symlink; the build's output has to be plain files.` };
         if (!stat.isFile())
             return { ok: false, message: `${path} isn't a regular file.` };
-        // Every folder on the way is a real folder inside the root.
         if (!realpathSync(join(full, "..")).startsWith(realRoot))
             return { ok: false, message: `${path} escapes the build folder.` };
         let fd;
@@ -546,8 +440,6 @@ export function digestTree(root, paths) {
     }
     return { ok: true, digest: createHash("sha256").update(JSON.stringify(entries)).digest("hex"), entries: entries.length };
 }
-/** Every regular entry under a folder (relative paths), walked with lstat; anything else is listed as is, so the
- * digest refuses it. */
 function walk(root, prefix) {
     const out = [];
     let names;
@@ -567,23 +459,15 @@ function walk(root, prefix) {
     }
     return out;
 }
-/**
- * Step 3 for one commit: extract it (verified objects, regular files only) into a fresh folder, install from its
- * lockfile with no scripts and no network (npm checks every package against the lockfile's integrity hash), build it,
- * list what `npm pack` would ship, wait until nothing runs from the folder any more, and digest dist/ plus the packed
- * files twice — a difference means something is still writing, and refuses.
- */
 export async function artifactDigest(gitDir, sha, runner, options = {}) {
     const timeoutMs = options.timeoutMs ?? 20 * 60_000;
     const dir = realpathSync(mkdtempSync(join(checkLaunchRoot(), "so-carry-")));
-    // When the build began (Linux: ticks since boot): an unreadable process that started before it isn't the build's.
     const scan = realScanIO();
     const began = { ms: Date.now(), ticks: scan.platform === "linux" ? scan.nowTicks() : null };
     try {
         const src = join(dir, "src"), tmp = join(dir, "tmp");
         mkdirSync(src);
         mkdirSync(tmp, { mode: 0o700 });
-        // npm reads no user or global config of the person's or the commit's: two empty files of this build's own.
         writeFileSync(join(tmp, "user.npmrc"), "");
         writeFileSync(join(tmp, "global.npmrc"), "");
         const extracted = extractCommit(gitDir, sha, src);
@@ -604,7 +488,6 @@ export async function artifactDigest(gitDir, sha, runner, options = {}) {
         const built = await step("The build", ["run", "build"]);
         if (built !== null)
             return { ok: false, message: built };
-        // Listing what would ship touches no dependency: it gets an empty cache of its own.
         const listing = await runner("npm", ["pack", "--dry-run", "--json", "--ignore-scripts"], { cwd: src, env: { ...env, npm_config_cache: join(tmp, "pack-cache") }, writable: [tmp], timeoutMs });
         if (listing.code !== 0)
             return { ok: false, message: `Listing the packed files failed: ${listing.stderr.trim().split("\n").slice(-2).join(" ")}` };
@@ -616,8 +499,6 @@ export async function artifactDigest(gitDir, sha, runner, options = {}) {
         catch {
             return { ok: false, message: "The packed file list couldn't be read." };
         }
-        // The build's process group is gone; anything still running from the folder (a background writer) refuses.
-        // A process caught mid-exit or mid-exec can't be read for a moment: the scan is asked again before it refuses.
         let left = processesInside(dir, began, scan);
         for (let again = 0; left === null && again < 2; again++) {
             await new Promise(resolve => setTimeout(resolve, 250));
@@ -643,16 +524,9 @@ export async function artifactDigest(gitDir, sha, runner, options = {}) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
-// ------------------------------------------------------------------ the proof
-/** The release task's id for a commit (release.ts gateTaskId's naming). */
 export const carriedTaskId = (version, sha) => `release-${version.replace(/[^0-9A-Za-z.-]/g, "-")}-${sha.slice(0, 7)}`;
-/**
- * Carry a person's release approval to commit `to`, or say exactly why not. The lead may ask; only these rules decide.
- * A refusal seals nothing and writes no row.
- */
 export async function proveCarry(store, input) {
     const requestId = input.requestId ?? randomUUID();
-    // 1. The idempotent retry first, before any compare-and-swap: a lost answer is retried without a refusal.
     const a0 = releaseAuthority(store, input.authority);
     if (a0 === null)
         return { ok: false, reason: "authority", message: `No release ${input.authority}.` };
@@ -663,7 +537,6 @@ export async function proveCarry(store, input) {
             return { ok: true, taskId: existing.taskId, carry: existing, retried: true };
         return { ok: false, reason: "authority", message: `The carry to ${input.to.slice(0, 7)} doesn't stand any more: ${live.applies && !live.ok ? live.why : "it isn't part of the release"}.` };
     }
-    // 2. Read-only preflight: any refusal stops here, before anything is installed or built.
     const pre = preflightCarry(store, { authority: input.authority, to: input.to, epoch: input.epoch ?? null, now: input.now });
     if (!pre.ok)
         return pre;
@@ -672,8 +545,6 @@ export async function proveCarry(store, input) {
     if (gitDir === null)
         return { ok: false, reason: "build", message: "The project's Git directory can't be read." };
     const runner = input.runner ?? fencedBuildRunner(store);
-    // 3. Both sides built. The anchor's own digest is built once (the person's seal authorized running that approved
-    // commit) and sealed into the authority record; until it exists nothing carries.
     let anchorDigest = plan.authority.artifactDigest;
     if (anchorDigest === null) {
         const anchor = await artifactDigest(gitDir, plan.authority.approvedSha, runner);
@@ -689,7 +560,6 @@ export async function proveCarry(store, input) {
         return { ok: false, reason: "build", message: `${input.to.slice(0, 7)} couldn't be built: ${candidate.message}` };
     if (candidate.digest !== anchorDigest)
         return { ok: false, reason: "artifact", message: `The production build of ${input.to.slice(0, 7)} differs from the approved one, so this commit needs approval.` };
-    // 4. One transaction: every mutable check again, then the writes.
     const after = releaseAuthority(store, plan.authority.id);
     const written = carryReleaseApproval(store, {
         authority: after.id, expectRev: after.rev, expectTip: plan.authority.tipSha, to: input.to, toTree: plan.toTree, requestId, artifactDigest: candidate.digest,
@@ -709,7 +579,6 @@ export async function proveCarry(store, input) {
         return { ok: false, reason: "stale", message: written.why };
     return { ok: true, taskId: written.taskId, carry: written.carry, retried: false };
 }
-/** The runtime that proved a carry: this package's version and where it runs from. */
 function runtimeIdentity() {
     try {
         const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -719,7 +588,6 @@ function runtimeIdentity() {
         return "toolroll unknown";
     }
 }
-/** The words a refused carry ends with: the commit, the path and the rule, and that a person approves it instead. */
 export function carryRefusalWords(refusal, to) {
     return `${to.slice(0, 7)} needs approval: ${refusal.message}`;
 }

package/dist/release-ci-hold.js

@@ -1,15 +1,5 @@
-/**
- * A release filed while its pull request's CI was still running (pipeline-speed.md D2) waits for CI before anyone but
- * the automatic road may approve it (Codex review round 1, finding 4): `release-auto.ts holdApprovalForCi` records the
- * hold before the task is filed, and only the plane's own reading of exact-head CI passing lifts it
- * (`liftCiHold`). The newest row for the task wins; the hold names the candidate commit it waits on.
- * Since Alex's decision of 2026-10-29 (a person may approve during CI) the coordinator records a "CI still running"
- * note instead (below); a hold an older coordinator placed still holds until lifted.
- */
 export const RELEASE_CI_HELD_ACTION = "release approval waits for CI";
 export const RELEASE_CI_PASSED_ACTION = "release approval CI passed";
-/** The candidate whose CI a release task's approval waits for, or null when nothing holds it. Fail closed: a hold row
- * whose candidate can't be read still holds. */
 export function releaseCiHoldOf(store, taskId) {
     const row = store.handle.prepare("SELECT action, detail FROM action_ledger WHERE task_id = ? AND action IN (?, ?) ORDER BY id DESC LIMIT 1")
         .get(taskId, RELEASE_CI_HELD_ACTION, RELEASE_CI_PASSED_ACTION);
@@ -18,21 +8,12 @@ export function releaseCiHoldOf(store, taskId) {
     const detail = typeof row["detail"] === "string" ? row["detail"] : "";
     return { candidate: /^[0-9a-f]{40}$/.test(detail) ? detail : null };
 }
-/** Why a person can't approve a release waiting for CI yet, in words. */
 export function releaseCiHoldWords(hold) {
     const commit = hold.candidate === null ? "this release's commit" : hold.candidate.slice(0, 7);
     return `GitHub CI is still running on ${commit}. This release can be approved once every pull request check passes; \`toolroll release\` asks you then.`;
 }
-/**
- * A person's release asks for approval while its pull request's CI still runs (Alex, 2026-10-29; pipeline-speed.md,
- * "Decision: a person's release asks during CI"). This row never holds approval: it lets the approval card say so, until
- * the plane reads exact-head CI passing (`liftCiHold` records RELEASE_CI_PASSED_ACTION, which ends it as it ends a
- * hold). Deployment gates and operation issuance also refuse while it remains, so a direct deploy cannot bypass
- * the coordinator's CI wait. Its absence is not a CI pass: the coordinator still reads exact-head checks itself.
- */
 export const RELEASE_CI_RUNNING_ACTION = "release asked while CI runs";
 export const RELEASE_CI_RUNNING_WORDS = "GitHub's checks are still running; nothing deploys until they pass.";
-/** The candidate whose CI was still running when the release task was filed, or null once the plane read it passing. */
 export function releaseCiRunningOf(store, taskId) {
     const row = store.handle.prepare("SELECT action, detail FROM action_ledger WHERE task_id = ? AND action IN (?, ?) ORDER BY id DESC LIMIT 1")
         .get(taskId, RELEASE_CI_RUNNING_ACTION, RELEASE_CI_PASSED_ACTION);
@@ -41,7 +22,6 @@ export function releaseCiRunningOf(store, taskId) {
     const detail = typeof row["detail"] === "string" ? row["detail"] : "";
     return { candidate: /^[0-9a-f]{40}$/.test(detail) ? detail : null };
 }
-/** Record that the release task is filed while CI runs on `candidate` (before the task exists). Idempotent. */
 export function noteCiRunning(store, input) {
     if (!/^[0-9a-f]{40}$/.test(input.candidate))
         throw new Error("a CI note needs the exact candidate commit");