toolroll 0.9.104 → 0.9.105

package/dist/evidence.js

@@ -1,18 +1,3 @@
-/**
- * Evidence: what actually happened, captured by the machine (§4, §7).
- *
- * The agent does not choose what counts as evidence — a diff the agent could
- * fabricate is a screenshot of a different crime scene. At park time the
- * builder captures the working state itself, relative to the base revision
- * stamped before the agent spent anything, and records how each capture was
- * made, whether it is complete, and what it hashes to. A truncated capture
- * says truncated; a failed capture stores the failure. Presenting either as
- * the whole story is the one dishonesty this module exists to rule out.
- *
- * Files live under the evidence root — outside every worktree, so an agent
- * cannot pre-write them — created exclusively (`wx`) with mode 0600. The
- * store holds keys relative to that root, never absolute paths.
- */
 import { createHash, randomBytes } from "node:crypto";
 import { closeSync, existsSync, constants, fstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join, sep } from "node:path";
@@ -24,66 +9,31 @@ import { parseProof, PROOF_LIMITS } from "./proof.js";
 import { HANDOFF_VERSION, readHandoffArtifact } from "./contracts/handoff.js";
 import { encodeBaseTreeSnapshot, parseBaseTreeSnapshot } from "./peek.js";
 import { noLazyFetch } from "./teardown-git.js";
-/** The park mailbox pattern. Each run's actual name carries a nonce; see `mailboxName`. */
 export const MAILBOX_PREFIX = "STANDING-ORDERS-PARK-";
-/** The terminal handoff: how every non-parking attempt says how it ended. */
 export const HANDOFF_PREFIX = "STANDING-ORDERS-DONE-";
-/** The planner's terminal handoff: the proposed scope and the plan document. */
 export const PLAN_PREFIX = "STANDING-ORDERS-PLAN-";
-/** The reviewer's former comment mailbox (v29–evidence-review-v1): the
- * reviewer now replies in its final message and writes nothing, but the
- * pattern stays recognized so a sweep still cleans up a stray file this
- * name left by an older build. */
 export const REVIEW_PREFIX = "STANDING-ORDERS-REVIEW-";
-/** The scout's terminal handoff (v34): the report, its only deliverable. */
 export const REPORT_PREFIX = "STANDING-ORDERS-REPORT-";
-/** The build's proof manifest (Priority 2): optional, and read only after
- * the handoff — a completed attempt's proof, never a parking or failure
- * artifact. */
 export const PROOF_PREFIX = "STANDING-ORDERS-PROOF-";
 export const RUBRIC_PREFIX = "STANDING-ORDERS-RUBRIC-";
-/** The running build's atomic milestone checkpoint (adaptive execution
- * plans): overwritten in place — a temp name, then a rename — rather than
- * created once and unlinked, since progress is reported many times across
- * one attempt. Read, never consumed, by the pulse and by settlement. */
 export const PROGRESS_PREFIX = "STANDING-ORDERS-PROGRESS-";
-/** The running build's bounded, evidence-linked plan-revision proposal
- * (adaptive execution plans): a terminal file like park or proof, written
- * at most once, read once at settlement. */
 export const PROPOSAL_PREFIX = "STANDING-ORDERS-PROPOSAL-";
-/** The running build's steering mailbox: a FOLDER, not a file. The pulse
- * writes each operator note into it as NNN.json (a temp name, then a
- * rename); the agent acknowledges a note by moving it into `handled/`. */
 export const STEER_PREFIX = "STANDING-ORDERS-STEER-";
-/** The running build's status file (Agents board): JSON lines the agent appends
- * (working, needs-decision, blocked, done), read forward by the pulse. */
 export const STATUS_PREFIX = "STANDING-ORDERS-STATUS-";
 export const MAILBOX_SUFFIX = ".json";
-/** v105: left in a run's evidence folder when the retention setting removed its files (retention.ts). */
 export const RETENTION_NOTE = "REMOVED-BY-RETENTION";
-/** Bounds on a claimed screenshot file's own bytes — independent of the
- * proof manifest's byte cap, since these are binary images, not JSON. */
 export const SCREENSHOT_BYTE_CAP = 5 * 1024 * 1024;
-/** Check evidence lives in the run's evidence, never on the branch: images a
- * build adds under this folder are left out of its commit. */
 export const WORKTREE_EVIDENCE_DIR = "evidence/";
 const IMAGE_PATH = /\.(?:png|jpe?g|gif|webp|bmp|ico|tiff?|avif|heic)$/i;
 const BINARY_PATH = /\.(?:pdf|zip|gz|tgz|tar|7z|woff2?|ttf|otf|eot|mp4|mov|webm|mp3|wav|sqlite3?|db|wasm|bin|jar|exe|dll|so|dylib)$/i;
 export function isImagePath(path) { return IMAGE_PATH.test(path); }
-/** Images and other files that are never read as text, judged by name alone. */
 export function isBinaryAssetPath(path) { return IMAGE_PATH.test(path) || BINARY_PATH.test(path); }
-/** Bytes each kind may store. Originals can be any size; the record says what was cut. */
-/** Bound one captured stream to `cap` bytes keeping its beginning and, mostly,
- * its end: a test runner's summary and failure list come last, and that is
- * what a reviewer or a repair needs to read. */
 export const SHORTENED_MARKER = "\n… output shortened; ending follows …\n";
 export function boundStreamHeadTail(value, cap, headShare = 0.2) {
     const bytes = Buffer.from(value, "utf8");
     if (bytes.length <= cap)
         return value;
     const marker = Buffer.from(SHORTENED_MARKER, "utf8");
-    // A cut inside a multi-byte character decodes as U+FFFD (three bytes);
-    // leave room for one at each edge so the result never exceeds the cap.
     const room = Math.max(0, cap - marker.length - 8);
     const head = Math.floor(room * headShare);
     const tail = room - head;
@@ -96,53 +46,27 @@ export const EVIDENCE_CAPS = {
     plan: TEXT_LIMITS.planDocumentBytes,
     "terminal-diff": 256 * 1024,
     "diff-stat": 32 * 1024,
-    // The enveloped base snapshot (live peek): 20k entries of path+sha+size.
     "base-tree": 4 * 1024 * 1024,
     handoff: 32 * 1024,
     "revision-brief": 64 * 1024,
     report: REPORT_LIMITS.payload,
     proof: PROOF_LIMITS.payload,
-    // Six bounded streams (three attempts × stdout/stderr) plus the summary.
     "check-log": 160 * 1024,
     screenshot: SCREENSHOT_BYTE_CAP,
     "structured-output": 64 * 1024,
-    // The planner's recorded source is bounded BEFORE it is written (the
-    // planner-source cap IS this value), so a stored record is never a
-    // truncated one: what the record holds is exactly what the planner read.
     "plan-contract": 128 * 1024,
-    // The inherited review-context inventory (v51): structured JSON that is
-    // never byte-truncated — the capture sheds whole items against its own
-    // aggregate content limit (REVIEW_CONTEXT_LIMITS) and this cap only has
-    // to hold the JSON-escaped form of that bounded content plus provenance.
     "review-context": 200 * 1024 * 1024,
 };
-/**
- * The bound a writer may seal a kind at with storeEvidence's `cap`, above its default: a release check's sealed report and
- * inventory (check-report.ts CHECK_ARTIFACT_CAP, 256 KiB). Readers accept exactly what writers may seal: 0.9.77 sealed
- * reports up to 256 KiB but read structured output back only to 64 KiB, so every full report over that (~85 KiB for a
- * 585-file suite) read as "no longer verifies" and the release's check as unavailable.
- */
 export const SEALED_EVIDENCE_CAPS = { "structured-output": 256 * 1024 };
-/** The most a stored artifact of this kind may hold: its default cap, or the larger bound a sealed payload may use. */
 export function evidenceReadCap(kind) {
     return Math.max(EVIDENCE_CAPS[kind], SEALED_EVIDENCE_CAPS[kind] ?? 0);
 }
 export function evidenceRoot(home) {
-    // Same continuity rule as the database: evidence recorded under an older
-    // name keeps verifying until a new-name root exists.
     return namedPath(home, ["evidence"], { dot: true });
 }
-/**
- * Unpredictable per attempt, so nothing on disk before this build can already
- * be the mailbox: a stale file, however it got there, simply has the wrong
- * name. The agent learns the name from its brief and nowhere else.
- */
 export function mailboxName() {
     return `${MAILBOX_PREFIX}${randomBytes(8).toString("hex")}${MAILBOX_SUFFIX}`;
 }
-/** Every protocol file the sweep must never let an old attempt leave behind.
- * The pre-rename NIGHTORDERS- prefix stays recognized here — a worktree cut
- * down before 2026-08-13 may still hold one, and cleanup has no vintage. */
 export function looksLikeProtocolFile(name) {
     if (looksLikeSteerFolder(name) || looksLikeStatusFile(name))
         return true;
@@ -159,13 +83,9 @@ export function looksLikeProtocolFile(name) {
         name.startsWith("NIGHTORDERS-")) &&
         name.endsWith(MAILBOX_SUFFIX));
 }
-/** A steering mailbox folder, or anything in it, as a directory listing or
- * `git status` names it: an untracked folder is reported with a trailing
- * slash, or file by file where a repository shows every untracked file. */
 export function looksLikeSteerFolder(name) {
     return /^STANDING-ORDERS-STEER-[0-9a-f]{16}(?:\/.*)?$/.test(name);
 }
-/** An agent status file (Agents board), by its exact nonce-shaped name. */
 export function looksLikeStatusFile(name) {
     return /^STANDING-ORDERS-STATUS-[0-9a-f]{16}\.jsonl$/.test(name);
 }
@@ -181,8 +101,6 @@ export function handoffName() {
 export function planFileName() {
     return `${PLAN_PREFIX}${randomBytes(8).toString("hex")}${MAILBOX_SUFFIX}`;
 }
-/** The build's optional proof manifest (Priority 2), named exactly like
- * every other protocol file — a nonce the agent learns only from its brief. */
 export function proofFileName() {
     return `${PROOF_PREFIX}${randomBytes(8).toString("hex")}${MAILBOX_SUFFIX}`;
 }
@@ -198,18 +116,9 @@ export function progressFileName() {
 export function proposalFileName() {
     return `${PROPOSAL_PREFIX}${randomBytes(8).toString("hex")}${MAILBOX_SUFFIX}`;
 }
-/**
- * Read a mailbox without following anything: the path must be a regular file,
- * opened O_NOFOLLOW and measured through its own descriptor — an agent that
- * made the pathname a symlink or FIFO gets a refusal, not a runner reading an
- * unrelated local file into web-visible evidence.
- */
 export function readMailbox(path, cap = LIMITS.payload) {
     let fd;
     try {
-        // O_NONBLOCK matters before the type check: opening a FIFO read-only can
-        // otherwise wait forever for a writer, outside every provider timeout.
-        // Once the descriptor is open we still accept regular files only.
         fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
     }
     catch (error) {
@@ -228,10 +137,6 @@ export function readMailbox(path, cap = LIMITS.payload) {
             return { ok: false, missing: false, problem: "the mailbox is not a regular file" };
         }
         if (stat.size > cap) {
-            // Oversize is invalid protocol, but it is still emitted evidence.
-            // Capture only the bounded prefix from this already no-follow-opened
-            // descriptor and carry the exact observed size so callers can retain
-            // an honest, capped artifact without allocating attacker-sized input.
             const prefix = Buffer.alloc(cap);
             let offset = 0;
             while (offset < prefix.length) {
@@ -262,7 +167,6 @@ export function readMailbox(path, cap = LIMITS.payload) {
         closeSync(fd);
     }
 }
-/** Each image a report names, matched to the screenshot evidence its own run stored with the same sha256. */
 export function reportShotsOf(artifacts, root, run, images) {
     const pruned = existsSync(join(root, String(run), RETENTION_NOTE));
     return images.map(image => {
@@ -289,8 +193,6 @@ export function readVerifiedReport(store, root, taskRef) {
         return { ok: false, run: artifact.run, problem: "the stored report is not a report this build can read" };
     return { ok: true, run: artifact.run, report: parsed.report, shots: reportShotsOf(store.artifactsFor(artifact.run), root, artifact.run, parsed.report.images) };
 }
-/** Verifies this run's proof bytes and format. A handoff that relies on a
- * revision's ancestors must also recheck its saved review-context custody. */
 export function readVerifiedProofForRun(store, root, runId) {
     const artifact = store.artifactsFor(runId).find(one => one.kind === "proof") ?? null;
     if (artifact === null)
@@ -309,13 +211,6 @@ export function readVerifiedProofForRun(store, root, runId) {
         return { ok: false, run: runId, problem: "the stored proof is not a proof this build can read" };
     return { ok: true, run: runId, proof: parsed.proof };
 }
-/**
- * The PNG and JPEG magic bytes — the only two formats a screenshot may
- * claim to be (scope: "no arbitrary binary evidence beyond bounded
- * PNG/JPEG screenshots"). Sniffed from the bytes themselves, never from a
- * claimed extension: an extension is a string an agent chose, a signature
- * is not.
- */
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff]);
 export function sniffImageKind(bytes) {
@@ -325,9 +220,6 @@ export function sniffImageKind(bytes) {
         return "jpeg";
     return null;
 }
-/** Whether bytes claimed as a screenshot actually are a bounded PNG or
- * JPEG — the one check standing between a claimed path and stored,
- * immutable image evidence. */
 export function validateScreenshotBytes(bytes) {
     if (bytes.length === 0)
         return { ok: false, problem: "the file is empty" };
@@ -339,30 +231,10 @@ export function validateScreenshotBytes(bytes) {
         return { ok: false, problem: "the file is not a PNG or JPEG (checked by signature, not extension)" };
     return { ok: true, kind };
 }
-/**
- * Pixel dimensions read straight from the format's own header — never
- * decoded, never trusting a claimed size (v39, screenshot evidence:
- * "meaningful byte size and at least 320 by 200 dimensions"). `null` when
- * the bytes are a valid signature but the header could not be read (a
- * genuinely corrupt or truncated file) — the caller treats that the same
- * as failing the size floor, never as passing it.
- *
- * PNG: the IHDR chunk is fixed at bytes 8-25 for every valid PNG — width
- * and height are the two big-endian uint32s right after it starts.
- *
- * JPEG: scan markers from byte 2. Every marker except the two without a
- * payload (SOI 0xD8, EOI 0xD9) and the RST markers (0xD0-0xD7) carries a
- * two-byte big-endian length; the SOF markers (0xC0-0xCF, excluding the
- * DHT/JPG/DAC markers 0xC4/0xC8/0xCC, which share the range but are not
- * frame headers) hold precision(1) + height(2) + width(2) right after
- * that length field.
- */
 export function imageDimensions(bytes, kind) {
     if (kind === "png") {
         if (bytes.length < 26)
             return null;
-        // Bytes 12-15 must literally spell IHDR, or this is not a PNG this
-        // reader understands well enough to trust the offsets that follow.
         if (bytes.toString("ascii", 12, 16) !== "IHDR")
             return null;
         const width = bytes.readUInt32BE(16);
@@ -371,21 +243,19 @@ export function imageDimensions(bytes, kind) {
             return null;
         return { width, height };
     }
-    // JPEG: walk markers looking for a Start Of Frame.
     let offset = 2;
     const SOF_MARKERS = new Set([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]);
     while (offset + 1 < bytes.length) {
         if (bytes[offset] !== 0xff)
-            return null; // not a marker boundary — malformed
+            return null;
         let marker = bytes[offset + 1];
         offset += 2;
-        // Fill bytes (0xFF padding) between markers.
         while (marker === 0xff && offset < bytes.length) {
             marker = bytes[offset];
             offset += 1;
         }
         if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7))
-            continue; // no payload
+            continue;
         if (offset + 1 >= bytes.length)
             return null;
         const length = bytes.readUInt16BE(offset);
@@ -399,24 +269,14 @@ export function imageDimensions(bytes, kind) {
             return { width, height };
         }
         if (marker === 0xda)
-            return null; // Start Of Scan — image data follows, no SOF was found first
+            return null;
         offset += length;
     }
     return null;
 }
-/**
- * Write one evidence file and record it. The row is written through the
- * store the caller passed — inside whatever transaction the caller holds.
- */
 export function storeEvidence(store, root, runId, kind, name, content, capture, now, options = {}) {
-    // `cap`: a sealed structured payload with its own documented bound (a release check's report: 256 KiB), never above what
-    // a reader of this kind accepts (evidenceReadCap): a record written larger would never verify again.
     const cap = options.cap === undefined ? EVIDENCE_CAPS[kind] : Math.min(options.cap, evidenceReadCap(kind));
     const stored = content.subarray(0, cap);
-    // Some callers that deliberately summarize/bound a source before storage
-    // may still report its true original size. This keeps `truncated` honest
-    // even when the already-bounded representation fits beneath this layer's
-    // cap (for example a three-attempt verification log).
     const bytesOriginal = Math.max(content.length, options.sourceBytesOriginal ?? content.length);
     const key = writeEvidenceFile(root, runId, name, stored);
     return store.saveArtifact({
@@ -432,31 +292,9 @@ export function storeEvidence(store, root, runId, kind, name, content, capture,
         ...(options.captureStatus === undefined ? {} : { captureStatus: options.captureStatus }),
     }, now);
 }
-/**
- * Read an artifact's bytes back, believing nothing until it is proved on the
- * descriptor actually read (§7's honesty, applied to serving). The record's
- * key must be a normalized relative path; the resolved path must live under
- * the root; the open refuses symlinks; the size and hash checks run against
- * the same descriptor the bytes come from — so a pathname swapped between a
- * check and the read buys an attacker nothing. Only a buffer whose SHA-256
- * matches the row is ever returned: unverified bytes never leave this
- * function, which is what lets a caller stream with a clear conscience.
- * Success proves stored-byte integrity only. Callers must independently
- * decide whether a shortened representation or failed capture is usable;
- * a verified failure log is still a failure, not successful evidence.
- */
-// Recovery uses this read boundary for retained receipts and handoffs: inspecting
-// bytes must never reseal a missing artifact or turn a saved failure into a pass.
 export function readVerifiedArtifact(root, artifact) {
     return withArtifactFile(root, artifact, readAndHash);
 }
-/**
- * Whether an artifact's bytes still verify, without returning them. Status
- * sweeps ask this of every artifact of every run, so a file proved earlier and
- * not touched since (same artifact row, device, inode, size, mtime and ctime
- * on the descriptor just opened) costs an fstat, not a re-read and SHA-256.
- * Every path check still runs on each call; a changed or new file is hashed.
- */
 export function verifyArtifact(root, artifact) {
     return withArtifactFile(root, artifact, (fd, stat, memoKey) => {
         if (VERIFIED_FILES.get(memoKey) === fileIdentity(artifact, stat))
@@ -465,11 +303,9 @@ export function verifyArtifact(root, artifact) {
         return read.ok ? { ok: true } : read;
     });
 }
-/** Files proved by an earlier read, keyed by artifact and resolved path. Bounded; the oldest proof is forgotten first. */
 const VERIFIED_FILES = new Map();
 const VERIFIED_FILES_LIMIT = 20_000;
 const fileIdentity = (artifact, stat) => [artifact.sha256, artifact.bytesStored, stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
-/** The checks both readers share, on the descriptor `use` then reads. */
 function withArtifactFile(root, artifact, use) {
     const segments = artifact.key.split("/");
     const wellFormed = segments.length > 0 &&
@@ -477,7 +313,6 @@ function withArtifactFile(root, artifact, use) {
             segment !== "." &&
             segment !== ".." &&
             !segment.includes("\\") &&
-            // eslint-disable-next-line no-control-regex
             !/[\u0000-\u001f\u007f:]/.test(segment));
     if (!wellFormed)
         return { ok: false, problem: "the key is not a normalized relative path" };
@@ -518,7 +353,6 @@ function withArtifactFile(root, artifact, use) {
         closeSync(fd);
     }
 }
-/** Read the whole file from the open descriptor; only bytes matching the row's SHA-256 leave, and only they are remembered as proved. */
 function readAndHash(fd, stat, memoKey, artifact) {
     VERIFIED_FILES.delete(memoKey);
     const buffer = Buffer.alloc(artifact.bytesStored);
@@ -540,22 +374,12 @@ function readAndHash(fd, stat, memoKey, artifact) {
     VERIFIED_FILES.set(memoKey, fileIdentity(artifact, stat));
     return { ok: true, content: buffer };
 }
-/** The file alone, no row — quarantines use this; they belong to no live run. */
 export function writeEvidenceFile(root, runId, name, content) {
     const dir = join(root, String(runId));
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     writeFileSync(join(dir, name), content, { flag: "wx", mode: 0o600 });
     return `${runId}/${name}`;
 }
-/**
- * Sweep every park-shaped file out of a worktree before the agent runs.
- *
- * A mailbox left by a cut-down attempt is never ingested as a decision — the
- * lease that could have vouched for it is gone — but its bytes may still say
- * what the agent meant, so what can be read safely is kept under quarantine
- * in the current run's evidence directory. What cannot be read safely (a
- * symlink, a FIFO, something oversized) is removed unread.
- */
 export function quarantineMailboxes(worktree, root, runId) {
     let entries;
     try {
@@ -569,17 +393,12 @@ export function quarantineMailboxes(worktree, root, runId) {
         if (!looksLikeProtocolFile(name))
             continue;
         const path = join(worktree, name);
-        // An earlier attempt's steering folder holds copies of notes the
-        // database already keeps: removed whole (a symlink is removed, never
-        // followed), never quarantined. So is its status file: the database
-        // already read every line it will ever need.
         if (looksLikeSteerFolder(name) || looksLikeStatusFile(name)) {
             try {
                 rmSync(path, { recursive: true, force: true });
                 swept.push(name);
             }
             catch {
-                // Its name carries an old nonce; nothing reads it again.
             }
             continue;
         }
@@ -590,7 +409,6 @@ export function quarantineMailboxes(worktree, root, runId) {
                     writeEvidenceFile(root, runId, `quarantine-${randomBytes(4).toString("hex")}-${name}`, read.raw);
                 }
                 catch {
-                    // Quarantine is best-effort; removal below is not.
                 }
             }
         }
@@ -599,19 +417,10 @@ export function quarantineMailboxes(worktree, root, runId) {
             swept.push(name);
         }
         catch {
-            // A mailbox that cannot be removed will fail the freshness check at
-            // ingestion anyway: it does not carry this attempt's nonce.
         }
     }
     return swept;
 }
-/**
- * Capture the park's evidence: the complete working state against the base
- * revision, and the porcelain inventory that names what the diff cannot —
- * untracked and staged files included. External diff drivers and textconv
- * are disabled by name: both run repository-configured commands, and this
- * capture must not execute anything the agent may have just written.
- */
 export async function captureParkEvidence(store, git, worktree, baseRevision, root, runId, now) {
     const captures = [
         {
@@ -631,22 +440,12 @@ export async function captureParkEvidence(store, git, worktree, baseRevision, ro
     for (const { kind, name, args } of captures) {
         const result = await git("git", args, { cwd: worktree });
         const command = `git ${args.filter(a => a !== "--no-optional-locks").join(" ")} (exit ${result.code})`;
-        // A failed capture is stored as the failure it is — stderr under the
-        // same key, labeled by its exit code — never silently skipped, because
-        // "no diff shown" and "diff capture failed" read very differently at 7am.
         const content = Buffer.from(result.code === 0 ? result.stdout : result.stderr, "utf8");
         ids.push(storeEvidence(store, root, runId, kind, name, content, command, now));
     }
     return ids;
 }
 const DIFF_STAT_FILE_LIMIT = 400;
-/**
- * Parse `git diff --numstat -z` output. NUL-delimited, so filenames are never
- * guessed out of patch headers (Codex roadmap review, scope cut A.3): plain
- * entries are one token "adds\tdels\tpath"; renames are "adds\tdels\t" with
- * the two paths as the following tokens. Binary files carry "-" counts,
- * recorded as null — never coerced to zero.
- */
 export function parseNumstat(raw, base, head) {
     const tokens = raw.split("\u0000").filter(token => token.length > 0);
     const files = [];
@@ -657,7 +456,7 @@ export function parseNumstat(raw, base, head) {
         const token = tokens[i];
         const parts = token.split("\t");
         if (parts.length < 3)
-            continue; // not a numstat entry this parser knows
+            continue;
         const adds = parts[0] === "-" ? null : Number(parts[0]);
         const dels = parts[1] === "-" ? null : Number(parts[1]);
         if ((adds !== null && !Number.isFinite(adds)) || (dels !== null && !Number.isFinite(dels)))
@@ -665,7 +464,6 @@ export function parseNumstat(raw, base, head) {
         let path = parts.slice(2).join("\t");
         let renamedFrom;
         if (path === "") {
-            // Rename: the next two tokens are the old and new paths.
             renamedFrom = tokens[i + 1];
             path = tokens[i + 2] ?? "";
             i += 2;
@@ -691,26 +489,12 @@ export function parseNumstat(raw, base, head) {
         filesTruncated: kept.length < files.length,
     };
 }
-/**
- * Write the handoff artifact (M6.10): the machine's own statement of where
- * a finished run left the world — workspace identity, exact base and head,
- * which answered decisions the brief carried, and a freshness stamp a
- * successor can PROVE against the branch before spending a token on stale
- * context. This is what makes a cold takeover context-bearing rather than
- * repo-only; a provider session is memory, not a freshness proof.
- */
 export function storeHandoffArtifact(store, root, payload, now) {
     const read = readHandoffArtifact({ version: HANDOFF_VERSION, ...payload });
     if (!read.ok)
         throw new Error(`The handoff does not match its contract: ${read.issues.map(issue => issue.line).join("; ")}`);
     return storeEvidence(store, root, payload.runId, "handoff", "handoff.json", Buffer.from(JSON.stringify(read.value, null, 2), "utf8"), "machine-authored handoff (exit 0)", now);
 }
-/**
- * High-confidence secret shapes ONLY (audit IV-7): a detector that cries
- * wolf trains people to approve wolves. Each pattern is a format no
- * ordinary source line matches by accident; generic "password=" shapes
- * are deliberately absent — test fixtures would drown the signal.
- */
 export const SECRET_PATTERNS = [
     { name: "private-key", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
     { name: "aws-access-key", pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
@@ -718,7 +502,6 @@ export const SECRET_PATTERNS = [
     { name: "slack-token", pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
     { name: "npm-auth-token", pattern: /_authToken\s*=\s*[^\s$][^\s]*/ },
     { name: "openai-key", pattern: /\bsk-[A-Za-z0-9_-]{32,}\b/ },
-    // v99: the other keys a team pastes most.
     { name: "stripe-key", pattern: /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{24,}\b|\bwhsec_[A-Za-z0-9]{24,}\b/ },
     { name: "google-api-key", pattern: /\bAIza[0-9A-Za-z_-]{35}\b/ },
     { name: "gitlab-token", pattern: /\bglpat-[A-Za-z0-9_-]{20,}\b/ },
@@ -726,7 +509,6 @@ export const SECRET_PATTERNS = [
     { name: "discord-bot-token", pattern: /\b[MN][A-Za-z\d]{23,25}\.[\w-]{6}\.[\w-]{27,}\b/ },
     { name: "password-in-url", pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:[^\s:@/]{3,}@[^\s/]/i },
 ];
-/** Scan text line by line; every hit names its pattern and line. */
 export function scanForSecrets(text) {
     const hits = [];
     const lines = text.split("\n");
@@ -740,8 +522,6 @@ export function scanForSecrets(text) {
     }
     return hits;
 }
-/** Hosts the DNS standards reserve for examples and loopback (RFC 2606,
- * RFC 6761): a URL with a password on one of these reaches nothing real. */
 function reservedHost(host) {
     const name = host.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
     if (name === "127.0.0.1" || name === "::1")
@@ -750,7 +530,6 @@ function reservedHost(host) {
         return true;
     return /(?:^|\.)(?:example|test|invalid|localhost)$/.test(name);
 }
-/** Mostly one character, e.g. "sk-" and forty a's: a fixture, not a key. */
 function repeatedFiller(value) {
     const longest = value.split(/[^A-Za-z0-9]+/).reduce((best, part) => (part.length > best.length ? part : best), "");
     if (longest.length < 8)
@@ -760,11 +539,6 @@ function repeatedFiller(value) {
         counts.set(char, (counts.get(char) ?? 0) + 1);
     return Math.max(...counts.values()) * 2 > longest.length;
 }
-/**
- * Whether one matched secret shape is a documented or reserved placeholder:
- * anything spelling EXAMPLE (AWS's own AKIAIOSFODNN7EXAMPLE), a password on
- * a reserved example host, or a value that is mostly one repeated character.
- */
 export function isPlaceholderSecret(name, line, match) {
     if (name === "private-key")
         return false;
@@ -776,7 +550,6 @@ export function isPlaceholderSecret(name, line, match) {
     const password = /:([^\s:@/]+)@[^@]*$/.exec(match[0])?.[1] ?? "";
     return reservedHost(host) || repeatedFiller(password);
 }
-/** The first secret shape on a line that is not a placeholder, if any. */
 function realSecretShape(line) {
     for (const { name, pattern } of SECRET_PATTERNS) {
         for (const match of line.matchAll(new RegExp(pattern.source, `${pattern.flags}g`))) {
@@ -786,11 +559,6 @@ function realSecretShape(line) {
     }
     return null;
 }
-/**
- * Scan a unified diff for secrets it commits: only added lines count —
- * removing a line cannot commit a secret, and context lines were already
- * there — and documented or reserved placeholders are not secrets.
- */
 export function scanPatchForSecrets(patch) {
     const hits = [];
     const lines = patch.split("\n");
@@ -826,8 +594,6 @@ export function scanPatchForSecrets(patch) {
     }
     return hits;
 }
-/** The alert for a candidate head with a flagged added line: where each
- * hit is and what to do, without repeating the value. */
 export function secretAlert(hits, runId) {
     const shown = hits.slice(0, 5).map(hit => `${hit.file}:${hit.fileLine} (${hit.name})`);
     const more = hits.length > shown.length ? `, and ${hits.length - shown.length} more` : "";
@@ -838,7 +604,6 @@ export function secretAlert(hits, runId) {
             `If this is a real key, rotate it and rewrite the branch. If it's a test value, assemble it at run time.`,
     };
 }
-/** Replace every hit line with a marker naming what was found — the display copy holds no secret. */
 export function redactSecretLines(text, hits) {
     const flagged = new Map(hits.map(hit => [hit.line, hit.name]));
     return text
@@ -849,12 +614,6 @@ export function redactSecretLines(text, hits) {
     })
         .join("\n");
 }
-/**
- * Fit a DiffStat under its cap by shedding FILES, never bytes (audit C-4):
- * a structured artifact cut mid-token is not a smaller stat, it is no stat.
- * Aggregate counts always survive; the file list shrinks until the encoded
- * JSON fits, and filesTruncated says so.
- */
 export function budgetedStatJson(stat) {
     const cap = EVIDENCE_CAPS["diff-stat"];
     let files = stat.files;
@@ -870,27 +629,10 @@ export function budgetedStatJson(stat) {
         files = files.slice(0, Math.floor(files.length / 2));
     }
 }
-/**
- * Capture the TERMINAL diff — the immutable base→head patch of a run that
- * committed, taken before its worktree is released (M5.3; the Codex scope
- * cut is the spec). Two artifacts: the bounded plain patch, and a
- * machine-parsed stat whose filenames came NUL-delimited from git, never
- * from patch headers. Same execution posture as the park capture: external
- * diff drivers and textconv disabled by name, because this must not run
- * anything the agent may have just written. A no-change run stores the
- * explicit zero-stat rather than storing nothing — "no diff" and "capture
- * failed" have to read differently.
- */
 export async function captureTerminalDiff(store, git, worktree, base, head, root, runId, now) {
     const patchArgs = ["--no-optional-locks", "diff", "--no-ext-diff", "--no-textconv", "--no-color", base, head];
     const patch = await git("git", patchArgs, { cwd: worktree });
     const patchCommand = `git ${patchArgs.filter(a => a !== "--no-optional-locks").join(" ")} (exit ${patch.code})`;
-    // The secret scan (audit IV-7): a committed credential must not gain a
-    // SECOND durable, console-served copy. Hit lines are redacted in the
-    // stored artifact, the row says redacted, a page names the branch — and
-    // the publication gate refuses to push a redacted run's branch anywhere.
-    // Only lines the diff adds count, and the alert is one per candidate head:
-    // every gate over the same head would otherwise repeat it.
     const rawPatch = patch.code === 0 ? patch.stdout : patch.stderr;
     const hits = patch.code === 0 ? scanPatchForSecrets(rawPatch) : [];
     const patchContent = Buffer.from(hits.length > 0 ? redactSecretLines(rawPatch, hits) : rawPatch, "utf8");
@@ -919,21 +661,7 @@ export async function captureTerminalDiff(store, git, worktree, base, head, root
     });
     return { diffId, statId };
 }
-/**
- * The live peek's base snapshot (live-peek v3 §1), captured in the same
- * pre-spawn window that computed `base` itself — one `ls-tree` against the
- * project clone (NEVER a worktree), lazy-fetch and replace-refs disabled
- * on argv, the child's environment reduced to an allowlist that contains
- * no GIT_* at all. The parsed listing is round-tripped through the strict
- * snapshot codec: any entry the codec refuses — including paths the UTF-8
- * decode mangled into U+FFFD — refuses the WHOLE snapshot, recorded as a
- * failed capture. Integrity class: the database's own, claimed as nothing
- * more (round-3 finding 42).
- */
 export async function captureBaseTree(store, git, repoRoot, repo, base, root, runId, now) {
-    // Fail-soft throughout: a snapshot that cannot capture disables the live
-    // peek for this run and NOTHING else — the build must proceed untouched,
-    // and an invalid run refuses later at the invocation gateway, typed.
     try {
         return await captureBaseTreeInner(store, git, repoRoot, repo, base, root, runId, now);
     }
@@ -943,8 +671,6 @@ export async function captureBaseTree(store, git, repoRoot, repo, base, root, ru
 }
 async function captureBaseTreeInner(store, git, repoRoot, repo, base, root, runId, now) {
     const args = [...noLazyFetch(), "-c", "protocol.allow=never", "--no-replace-objects", "--no-optional-locks", "ls-tree", "-r", "-l", "-z", base];
-    // `git` is the builder's hardened checkout git (a frozen view): on a git without --no-lazy-fetch it refuses a partial
-    // clone from the same config it runs with (teardown-git.ts lazyFetchSetting).
     const listed = await git("git", args, { cwd: repoRoot, envAllowlist: ["PATH", "HOME"] });
     const command = `git ls-tree -r -l -z ${base} (exit ${listed.code})`;
     const refuse = () => {
@@ -959,7 +685,6 @@ async function captureBaseTreeInner(store, git, repoRoot, repo, base, root, runI
     for (const record of listed.stdout.split("\u0000")) {
         if (record === "")
             continue;
-        // "<mode> <type> <sha> <size>\t<path>" — size is "-" for gitlinks.
         const tab = record.indexOf("\t");
         if (tab < 0)
             return refuse();
@@ -974,7 +699,6 @@ async function captureBaseTreeInner(store, git, repoRoot, repo, base, root, runI
             return refuse();
     }
     const encoded = encodeBaseTreeSnapshot({ repo, run: runId, base, entries });
-    // The strict codec is the gate: what it cannot re-read, nothing stores.
     if (parseBaseTreeSnapshot(encoded) === null)
         return refuse();
     storeEvidence(store, root, runId, "base-tree", "base-tree.json", Buffer.from(encoded, "utf8"), command, now, {