toolroll 0.5.0

package/dist/evidence-pack.js

@@ -0,0 +1,258 @@
+/**
+ * v103: a change's evidence pack. It is everything an auditor asks about one
+ * piece of work, in one place: who asked for it, the exact terms and who
+ * approved them (under which rules), which agents ran and what they cost,
+ * what changed, the checks, who marked it complete, where it was published,
+ * and every ledger entry about it with its seal. JSON for tools; the same
+ * facts as a printable page for people.
+ *
+ * Each ledger entry carries its seal (`prev`, `hash`), so anyone can
+ * recompute it; the chain report and the latest checkpoint tie those
+ * entries to the whole ledger.
+ */
+import { createHash } from "node:crypto";
+import { rulesWords } from "./approval-policy.js";
+import { assignmentOf } from "./assignment.js";
+import { projectName } from "./project.js";
+import { changedFilesOf } from "./result-completion.js";
+export const EVIDENCE_PACK_FORMAT = "standing-orders/evidence-pack/v1";
+/** How to recheck one entry's seal, for whoever reads the JSON. */
+export const SEAL_RECIPE = 'hash = sha256(prev + "\\n" + JSON.stringify([id, at, actor, repo, taskId, runId, action, outcome, source, detail]))';
+/** A pack carries up to this many of the task's own entries, and the newest this many requests made about it. */
+const MAX_ENTRIES = 5000;
+const MAX_REQUESTS = 500;
+/** The pack for one task (the whole family: the task and every revision), as `who` may see it. null when they can't. */
+export function evidencePack(store, taskId, access, who, now, evidenceRoot, checked) {
+    const family = store.taskFamilyOf(taskId, access.repos, access.principal === "operator" && access.includeUnplaced === true);
+    if (family === null)
+        return null;
+    const chain = checked ?? store.ledgerChain();
+    const repo = family.root.repo;
+    const versions = family.versions.map(version => {
+        const scope = store.getScope(version.id);
+        const history = store.scopeHistory(version.id);
+        const runs = store.runsFor(version.refId).map(run => {
+            const artifacts = store.artifactsFor(run.id);
+            const diff = artifacts.find(one => one.kind === "diff");
+            const proof = store.proofVerdictFor(run.id);
+            const publication = store.publicationForRun(run.id);
+            const builds = run.role === "builder" || run.role === "repair";
+            return {
+                id: run.id, role: run.role, agent: run.provider, model: run.model, outcome: run.outcome, reason: run.reason,
+                base: run.baseRevision, head: run.headRevision, startedAt: run.startedAt, finishedAt: run.finishedAt,
+                tokensIn: run.tokensIn, tokensOut: run.tokensOut, costUsd: run.costUsd,
+                changedFiles: builds && artifacts.some(one => one.kind === "diff-stat") ? changedFilesOf(store, run.id, evidenceRoot) : builds ? null : [],
+                diff: diff === undefined ? null : { sha256: diff.sha256, bytes: diff.bytesOriginal, complete: !diff.truncated && !diff.redacted },
+                proof: proof === null ? null : { verdict: proof.verdict, decidedAt: proof.decidedAt, reasons: proof.reasons },
+                publication: publication === null ? null : { repo: publication.githubRepo, branch: publication.head, commit: publication.headSha, state: publication.state,
+                    pr: publication.prNumber, url: publication.prUrl, remoteState: publication.remoteState, checks: publication.lastCheckState },
+            };
+        });
+        return {
+            id: version.id, title: version.title, state: version.state, filedAt: version.createdAt, filedBy: store.taskFiler(version.id),
+            scope: scope === null ? null : {
+                goal: scope.goal, outOfScope: scope.outOfScope, touches: scope.touches, acceptance: scope.acceptance.map(one => ({ id: one.id, statement: one.statement })),
+                budgetUsd: scope.budgetMicrousd === null ? null : scope.budgetMicrousd / 1_000_000, digest: scope.digest,
+                approved: scope.approvedBy === null || scope.approvedAt === null || scope.approvedDigest === null ? null
+                    : { by: scope.approvedBy, at: scope.approvedAt, digest: scope.approvedDigest, basis: scope.approvalBasis === "mode" ? "mode" : "person", current: scope.approvedDigest === scope.digest },
+                writtenBy: history.authors,
+                approvals: history.votes,
+            },
+            runs,
+        };
+    });
+    const assignment = assignmentOf(store, family.current.id, now, access, evidenceRoot);
+    const receipt = assignment?.receipt ?? null;
+    const runIds = versions.flatMap(version => version.runs.map(run => run.id));
+    const { entries, truncated } = store.taskLedgerEntries({ taskIds: family.versions.map(version => version.id), runIds }, { entries: MAX_ENTRIES, requests: MAX_REQUESTS });
+    const allRuns = versions.flatMap(version => version.runs);
+    const sum = (pick) => allRuns.reduce((total, run) => total + (pick(run) ?? 0), 0);
+    const latest = store.ledgerCheckpoints(1)[0] ?? null;
+    const rules = repo === null ? null : store.approvalRules(repo);
+    const body = {
+        format: EVIDENCE_PACK_FORMAT,
+        generatedAt: now.toISOString(),
+        generatedBy: who,
+        task: { id: family.root.id, title: family.current.title, state: family.current.state, repo, project: repo === null ? null : projectName(repo), filedAt: family.root.createdAt },
+        rules: repo === null || rules === null ? null : {
+            now: rulesWords(rules),
+            changes: store.actionLedger({ repos: [repo], source: "policy", limit: 101 }).filter(one => one.action === "approval rules changed").reverse()
+                .map(one => ({ id: one.id, at: one.at, by: one.actor, change: one.detail })),
+        },
+        versions,
+        result: receipt === null ? null : {
+            runId: receipt.runId, base: receipt.base, head: receipt.head, kind: receipt.completionKind,
+            checks: { status: receipt.checks.status, command: receipt.checks.command, exitCode: receipt.checks.exitCode, detail: receipt.checks.detail },
+            completedBy: assignment?.completion?.actor ?? null, completedAt: assignment?.completion?.at ?? null, caveats: receipt.caveats,
+            publication: assignment?.publication ?? null,
+        },
+        totals: { runs: allRuns.length, costUsd: Math.round(sum(run => run.costUsd) * 1e6) / 1e6, tokensIn: sum(run => run.tokensIn), tokensOut: sum(run => run.tokensOut) },
+        ledger: {
+            entries,
+            truncated,
+            chain: { ok: chain.ok, entries: chain.entries, through: chain.through, head: chain.head, problem: chain.problem?.what ?? null, checkedAt: chain.checkedAt },
+            checkpoint: latest === null ? null : { through: latest.through, hash: latest.hash, at: latest.at },
+            recipe: SEAL_RECIPE,
+        },
+    };
+    return { ...body, digest: packDigest(body) };
+}
+export function packDigest(body) {
+    return createHash("sha256").update(JSON.stringify(body), "utf8").digest("hex");
+}
+/** A day as the export takes it (YYYY-MM-DD, UTC), or null. */
+export function exportDay(value) {
+    if (value === null || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return null;
+    const day = new Date(`${value}T00:00:00.000Z`);
+    return Number.isNaN(day.getTime()) || day.toISOString().slice(0, 10) !== value ? null : day.toISOString();
+}
+const EXPORT_ENTRIES = 100_000;
+/** Entries per piece of an export: small enough that a slow, steady reader finishes each well inside the server's minute. */
+const EXPORT_PAGE = 250;
+const EXPORT_PACKS = 200;
+/** Every ledger entry in [from, to) that `who` may read, sealed, with a pack for each task they name: one JSON
+ * document (a `LedgerExport`), a piece at a time (a page of entries, or one pack), so an export never holds
+ * the whole range at once. */
+export function* ledgerExportChunks(store, range, scope, access, who, now, evidenceRoot) {
+    // An export is the record someone takes away: the whole chain is walked for it (or was, within the last minute).
+    const chain = store.ledgerChain({ full: true, fresh: 60_000 });
+    const latest = store.ledgerCheckpoints(1)[0] ?? null;
+    const head = {
+        format: "standing-orders/ledger-export/v1", generatedAt: now.toISOString(), generatedBy: who, from: range.from, to: range.to,
+        chain: { ok: chain.ok, entries: chain.entries, through: chain.through, head: chain.head, problem: chain.problem?.what ?? null, checkedAt: chain.checkedAt },
+        checkpoint: latest === null ? null : { through: latest.through, hash: latest.hash, at: latest.at }, recipe: SEAL_RECIPE,
+    };
+    yield `${JSON.stringify(head).slice(0, -1)},"entries":[`;
+    const named = [];
+    const seen = new Set();
+    let after = 0, written = 0, moreEntries = false;
+    for (;;) {
+        const page = store.sealedLedgerEntries({ ...range, repos: scope.repos, instance: scope.instance, after, limit: EXPORT_PAGE });
+        const kept = page.slice(0, Math.min(EXPORT_PAGE, EXPORT_ENTRIES - written));
+        if (kept.length > 0)
+            yield `${written === 0 ? "" : ","}${kept.map(one => JSON.stringify(one)).join(",")}`;
+        written += kept.length;
+        for (const one of kept)
+            if (one.taskId !== null && !seen.has(one.taskId)) {
+                seen.add(one.taskId);
+                named.push(one.taskId);
+            }
+        if (page.length <= EXPORT_PAGE)
+            break;
+        if (written >= EXPORT_ENTRIES) {
+            moreEntries = true;
+            break;
+        }
+        after = kept.at(-1).id;
+    }
+    yield `],"packs":[`;
+    const packed = new Set();
+    let packs = 0, morePacks = false;
+    for (const taskId of named) {
+        if (packed.has(taskId))
+            continue;
+        const family = store.taskFamilyOf(taskId, access.repos, access.principal === "operator" && access.includeUnplaced === true);
+        if (family === null || packed.has(family.root.id)) {
+            packed.add(taskId);
+            continue;
+        }
+        for (const version of family.versions)
+            packed.add(version.id);
+        packed.add(family.root.id);
+        if (packs === EXPORT_PACKS) {
+            morePacks = true;
+            break;
+        }
+        const pack = evidencePack(store, family.root.id, access, who, now, evidenceRoot, chain);
+        if (pack === null)
+            continue;
+        yield `${packs === 0 ? "" : ","}${JSON.stringify(pack)}`;
+        packs++;
+    }
+    yield `],"truncated":${JSON.stringify({ entries: moreEntries, packs: morePacks })}}`;
+}
+// ---- The printable page -----------------------------------------------------
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const when = (at) => at === null ? "—" : `${e(at.slice(0, 16).replace("T", " "))} UTC`;
+const short = (hash) => hash === null ? "—" : `<code title="${e(hash)}">${e(hash.slice(0, 12))}</code>`;
+const usd = (value) => value === null ? "—" : `$${value.toFixed(value < 1 ? 4 : 2)}`;
+/** Only a web address links; anything else (a stored value that isn't one) is shown as text. */
+const link = (url) => /^https:\/\/[^\s"'<>]+$/.test(url) ? `<a href="${e(url)}">${e(url)}</a>` : e(url);
+const filer = (who) => who === null || who.name === null ? "automation" : who.kind === "person" ? e(who.name) : `${e(who.name)} (${e(who.kind)})`;
+export const EVIDENCE_PACK_CSS = `.evidence-pack{max-width:960px;min-width:0}.evidence-pack h1{margin:0}.evidence-pack h2{font-size:.9375rem;margin:24px 0 8px}.evidence-pack h3{font-size:.875rem;margin:16px 0 6px}` +
+    `.evidence-head{display:flex;justify-content:space-between;gap:12px;flex-wrap:wrap;align-items:baseline}.evidence-pack dl{display:grid;grid-template-columns:minmax(120px,180px) minmax(0,1fr);gap:4px 16px;margin:0}` +
+    `.evidence-pack dt{color:var(--muted-foreground);font-size:.8125rem}.evidence-pack dd{margin:0;min-width:0;overflow-wrap:anywhere}.evidence-pack table{width:100%;border-collapse:collapse;font-size:.8125rem}` +
+    `.evidence-pack th,.evidence-pack td{text-align:left;padding:5px 8px 5px 0;border-bottom:1px solid var(--border);vertical-align:top;overflow-wrap:anywhere}.evidence-pack th{font-weight:500;color:var(--muted-foreground)}` +
+    `.evidence-pack code{font-family:var(--font-mono);font-size:.75rem}.evidence-pack .files{margin:4px 0 0;padding-left:18px;font-family:var(--font-mono);font-size:.75rem}.evidence-pack .criteria{margin:0;padding-left:18px}.evidence-chain{font-size:.8125rem;margin:8px 0 0}` +
+    `.evidence-chain.ok strong{color:var(--success)}.evidence-table{overflow-x:auto}.evidence-foot{margin-top:24px;font-size:.75rem;color:var(--muted-foreground);overflow-wrap:anywhere}` +
+    `@media(max-width:600px){.evidence-pack dl{grid-template-columns:minmax(0,1fr)}.evidence-pack dd{margin-bottom:6px}}` +
+    `@media print{.side,.tabbar,.mobile-top,.scope-bar,.banner,.evidence-actions{display:none!important}body,.app,.content,.detail,main{background:#fff!important;color:#000!important;margin:0!important;padding:0!important;box-shadow:none!important;border:0!important}` +
+    `.evidence-pack{max-width:none}.evidence-pack section{break-inside:avoid-page}.evidence-pack a{color:#000;text-decoration:none}}`;
+/** The pack as a page: the same facts, in the order an auditor reads them. No script. */
+export function evidencePackHtml(pack) {
+    const task = pack.task;
+    const chain = pack.ledger.chain.ok
+        ? `<p class="evidence-chain ok" data-evidence-chain="ok"><strong>Ledger chain verified</strong> · ${pack.ledger.chain.entries} entries · head ${short(pack.ledger.chain.head)}${pack.ledger.chain.checkedAt === null ? "" : ` · checked in full ${when(pack.ledger.chain.checkedAt)}`}${pack.ledger.checkpoint === null ? "" : ` · last checkpoint at entry #${pack.ledger.checkpoint.through}`}</p>`
+        : `<p class="evidence-chain problem" role="alert" data-evidence-chain="broken"><strong>Ledger chain broken</strong> · ${e(pack.ledger.chain.problem)}</p>`;
+    const versions = pack.versions.map((version, index) => {
+        const scope = version.scope;
+        const approved = scope?.approved ?? null;
+        const approvals = scope === null ? [] : scope.approvals.filter(one => one.digest === (approved?.digest ?? scope.digest));
+        const rows = [
+            ["Filed", `${when(version.filedAt)} by ${filer(version.filedBy)}`],
+            ...(scope === null ? [["Scope", "None written"]] : [
+                ["Goal", e(scope.goal)],
+                ...(scope.touches.length ? [["Touches", scope.touches.map(e).join(", ")]] : []),
+                ...(scope.acceptance.length ? [["Acceptance", `<ol class="criteria">${scope.acceptance.map(one => `<li>${e(one.statement)}</li>`).join("")}</ol>`]] : []),
+                ...(scope.writtenBy.length ? [["Scope written by", [...new Set(scope.writtenBy.map(one => one.author))].map(e).join(", ")]] : []),
+                ["Approved", approved === null ? "Not approved" : `${e(approved.by)}${approved.basis === "mode" ? " (operating mode)" : ""} · ${when(approved.at)}${approved.current ? "" : " · the scope changed after this"}`],
+                ...(approvals.length > 1 ? [["Approvals", approvals.map(one => `${e(one.approver)} · ${when(one.at)}`).join("<br>")]] : []),
+                ["Scope digest", short(scope.digest)],
+            ]),
+        ];
+        const runs = version.runs.length === 0 ? `<p class="meta">No agent ran.</p>` :
+            `<div class="evidence-table"><table><thead><tr><th>Run</th><th>Role</th><th>Agent</th><th>Outcome</th><th>Cost</th><th>Finished</th><th>Commit</th></tr></thead><tbody>` +
+                version.runs.map(run => `<tr><td><a href="/r/${run.id}">#${run.id}</a></td><td>${e(run.role)}</td><td>${e(run.agent)}${run.model ? ` · ${e(run.model)}` : ""}</td><td>${e(run.outcome ?? "running")}</td><td>${usd(run.costUsd)}</td><td>${when(run.finishedAt)}</td><td>${short(run.head)}</td></tr>`).join("") +
+                `</tbody></table></div>`;
+        const changes = version.runs.filter(run => run.role === "builder" || run.role === "repair").map(run => `<p class="meta">Run #${run.id}${run.diff === null ? "" : ` · diff ${short(run.diff.sha256)}${run.diff.complete ? "" : " (partial)"}`}</p>` +
+            (run.changedFiles === null ? `<p class="meta">Its changed files couldn't be read.</p>` : run.changedFiles.length === 0 ? `<p class="meta">No files changed.</p>` : `<ul class="files">${run.changedFiles.map(file => `<li>${e(file)}</li>`).join("")}</ul>`)).join("");
+        return `<section data-evidence-version="${e(version.id)}"><h2>${pack.versions.length > 1 ? `${index === 0 ? "Request" : `Revision ${index}`} · ` : "Request and approval · "}${e(version.id)}</h2><dl>${rows.map(([label, value]) => `<dt>${label}</dt><dd>${value}</dd>`).join("")}</dl>` +
+            `<h3>Agents</h3>${runs}${changes === "" ? "" : `<h3>Changes</h3>${changes}`}</section>`;
+    }).join("");
+    const result = pack.result;
+    const outcome = result === null ? `<section><h2>Result</h2><p class="meta">No finished result yet.</p></section>` :
+        `<section data-evidence-result><h2>Result</h2><dl>` +
+            `<dt>Checks</dt><dd>${e(result.checks.detail)}${result.checks.command ? ` <code>${e(result.checks.command)}</code>` : ""}</dd>` +
+            `<dt>Marked complete</dt><dd>${result.completedBy === null ? "Not yet" : `${e(result.completedBy)} · ${when(result.completedAt)}`}</dd>` +
+            `<dt>Published</dt><dd>${result.publication === null ? "Not published" : `${e(result.publication.state)}${result.publication.prUrl ? ` · ${link(result.publication.prUrl)}` : ""}${result.publication.remoteState ? ` · ${e(result.publication.remoteState.toLowerCase())}` : ""}`}</dd>` +
+            `<dt>Commit</dt><dd>${short(result.base)} → ${short(result.head)}</dd>` +
+            (result.caveats.length ? `<dt>Caveats</dt><dd>${result.caveats.map(e).join("<br>")}</dd>` : "") +
+            `</dl></section>`;
+    const decisions = pack.ledger.entries.filter(one => one.source !== "request");
+    const requests = pack.ledger.entries.length - decisions.length;
+    const askedWords = `${requests} ${requests === 1 ? "request" : "requests"} made through the console (accepted or refused)`;
+    const ledger = `<section><h2>Ledger</h2>${decisions.length === 0 ? `<p class="meta">No entries.</p>` :
+        `<div class="evidence-table"><table><thead><tr><th>#</th><th>Time</th><th>Who</th><th>What</th><th>Outcome</th><th>Seal</th></tr></thead><tbody>` +
+            decisions.map(one => `<tr data-ledger-id="${one.id}"><td>${one.id}</td><td>${when(one.at)}</td><td>${e(one.actor)}</td><td>${e(one.action)}${one.detail ? `<br><span class="meta">${e(one.detail)}</span>` : ""}</td><td>${e(one.outcome)}</td><td>${short(one.seal?.hash ?? null)}</td></tr>`).join("") +
+            `</tbody></table></div>`}${requests > 0 ? `<p class="meta">Plus ${askedWords}, listed in the JSON.</p>` : ""}${pack.ledger.truncated ? `<p class="meta">This pack holds ${decisions.length} of the task's entries and the newest ${requests} requests; the ledger export has the rest.</p>` : ""}</section>`;
+    const cost = pack.totals.runs === 0 ? "None ran" : `${pack.totals.runs} ${pack.totals.runs === 1 ? "run" : "runs"} · ${usd(pack.totals.costUsd)}`;
+    // The rules as they stand, and each change to them (the approval above was under whichever applied then).
+    const rules = pack.rules === null ? "None" : `${e(pack.rules.now)}${pack.rules.changes.length === 0 ? "" :
+        `<ul class="criteria">${pack.rules.changes.slice(-5).map(one => `<li class="meta">${when(one.at)} · ${e(one.by)}: ${e(one.change)}</li>`).join("")}</ul>`}`;
+    return `<article class="evidence-pack" data-evidence-pack="${e(task.id)}">` +
+        `<div class="evidence-head"><h1>Evidence pack</h1><p class="evidence-actions"><a href="/t/${encodeURIComponent(task.id)}/evidence?format=json" download>Download JSON</a> · <a href="/t/${encodeURIComponent(task.id)}">Back to task</a></p></div>` +
+        `<p><strong>${e(task.title)}</strong></p>` +
+        `<dl><dt>Task</dt><dd>${e(task.id)}${task.project === null ? "" : ` · ${e(task.project)}`} · ${e(task.state)}</dd>` +
+        `<dt>Approval rules</dt><dd>${rules}</dd><dt>Agents</dt><dd>${cost}</dd>` +
+        `<dt>Prepared</dt><dd>${when(pack.generatedAt)} for ${e(pack.generatedBy)}</dd></dl>${chain}` +
+        versions + outcome + ledger +
+        `<p class="evidence-foot">Pack digest <code>${e(pack.digest)}</code>. Each ledger entry's seal can be rechecked from the JSON: ${e(pack.ledger.recipe)}.</p></article>`;
+}
+/** The page as a file on its own (the CLI's --html): the same facts with just enough style to print. */
+export function standaloneEvidenceHtml(pack) {
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Evidence pack · ${e(pack.task.id)}</title>` +
+        `<style>:root{--muted-foreground:#5c5c5c;--border:#dedede;--success:#1a7f37;--font-mono:ui-monospace,SFMono-Regular,Menlo,monospace}` +
+        `body{font:14px/1.5 system-ui,-apple-system,sans-serif;margin:32px auto;padding:0 16px;max-width:960px;color:#171717;background:#fff}.meta{color:var(--muted-foreground);font-size:.8125rem}.evidence-actions{display:none}` +
+        EVIDENCE_PACK_CSS + `</style></head><body>${evidencePackHtml(pack)}</body></html>\n`;
+}

package/dist/evidence.d.ts

@@ -0,0 +1,345 @@
+/**
+ * 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 { type ParsedReport } from "./scout-report.js";
+import { type ParsedProof } from "./proof.js";
+import type { Artifact, Store } from "./store.js";
+import type { ExecResult } from "./exec.js";
+/** The park mailbox pattern. Each run's actual name carries a nonce; see `mailboxName`. */
+export declare const MAILBOX_PREFIX = "STANDING-ORDERS-PARK-";
+/** The terminal handoff: how every non-parking attempt says how it ended. */
+export declare const HANDOFF_PREFIX = "STANDING-ORDERS-DONE-";
+/** The planner's terminal handoff: the proposed scope and the plan document. */
+export declare 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 declare const REVIEW_PREFIX = "STANDING-ORDERS-REVIEW-";
+/** The scout's terminal handoff (v34): the report, its only deliverable. */
+export declare 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 declare const PROOF_PREFIX = "STANDING-ORDERS-PROOF-";
+export declare 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 declare 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 declare const PROPOSAL_PREFIX = "STANDING-ORDERS-PROPOSAL-";
+export declare const MAILBOX_SUFFIX = ".json";
+/** v105: left in a run's evidence folder when the retention setting removed its files (retention.ts). */
+export declare 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 declare const SCREENSHOT_BYTE_CAP: number;
+/** 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 declare const SHORTENED_MARKER = "\n\u2026 output shortened; ending follows \u2026\n";
+export declare function boundStreamHeadTail(value: string, cap: number, headShare?: number): string;
+export declare const EVIDENCE_CAPS: Record<Artifact["kind"], number>;
+export declare function evidenceRoot(home: string): string;
+/**
+ * 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 declare function mailboxName(): string;
+export declare function looksLikeMailbox(name: string): boolean;
+/** 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 declare function looksLikeProtocolFile(name: string): boolean;
+export declare function handoffName(): string;
+export declare function planFileName(): string;
+/** 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 declare function proofFileName(): string;
+export declare function rubricFileName(): string;
+export declare function reportFileName(): string;
+export declare function progressFileName(): string;
+export declare function proposalFileName(): string;
+/**
+ * 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 declare function readMailbox(path: string, cap?: number): {
+    ok: true;
+    raw: Buffer;
+} | {
+    ok: false;
+    problem: string;
+    missing: boolean;
+    raw?: Buffer;
+    bytesOriginal?: number;
+};
+/** A scout's report as a surface reads it (mate arc §10): the newest
+ * scout run's artifact, VERIFIED before a byte is parsed, then parsed with
+ * the same 422 rule that admitted it. null = no report; a problem names
+ * why an existing artifact cannot be shown rather than showing nothing. */
+export type ReportView = {
+    ok: true;
+    run: number;
+    report: ParsedReport;
+} | {
+    ok: false;
+    run: number;
+    problem: string;
+};
+export declare function readVerifiedReport(store: Store, root: string, taskRef: number): ReportView | null;
+/** A build's proof, read the same verified way as a scout's report — but
+ * keyed by RUN, not task: unlike a scout's report (the task's one rolling
+ * deliverable), a proof belongs to the one attempt whose page is showing
+ * it. null = no proof artifact for this run; a problem names why an
+ * existing one cannot be shown. */
+export type ProofView = {
+    ok: true;
+    run: number;
+    proof: ParsedProof;
+} | {
+    ok: false;
+    run: number;
+    problem: string;
+};
+/** 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 declare function readVerifiedProofForRun(store: Store, root: string, runId: number): ProofView | null;
+export declare function sniffImageKind(bytes: Buffer): "png" | "jpeg" | 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 declare function validateScreenshotBytes(bytes: Buffer): {
+    ok: true;
+    kind: "png" | "jpeg";
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * 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 declare function imageDimensions(bytes: Buffer, kind: "png" | "jpeg"): {
+    width: number;
+    height: number;
+} | 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 declare function storeEvidence(store: Store, root: string, runId: number, kind: Artifact["kind"], name: string, content: Buffer, capture: string, now: Date, options?: {
+    redacted?: boolean;
+    captureStatus?: "ok" | "failed";
+    sourceBytesOriginal?: number;
+}): number;
+/**
+ * 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.
+ */
+export declare function readVerifiedArtifact(root: string, artifact: Artifact): {
+    ok: true;
+    content: Buffer;
+} | {
+    ok: false;
+    problem: string;
+};
+/** The file alone, no row — quarantines use this; they belong to no live run. */
+export declare function writeEvidenceFile(root: string, runId: number, name: string, content: Buffer): string;
+/**
+ * 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 declare function quarantineMailboxes(worktree: string, root: string | null, runId: number | null): string[];
+/**
+ * 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 declare function captureParkEvidence(store: Store, git: (file: string, args: readonly string[], options?: {
+    cwd?: string;
+}) => Promise<ExecResult>, worktree: string, baseRevision: string | null, root: string, runId: number, now: Date): Promise<number[]>;
+/** One file's row in the terminal diff-stat. null adds/dels = binary. */
+export type DiffStatFile = {
+    path: string;
+    additions: number | null;
+    deletions: number | null;
+    renamedFrom?: string;
+};
+export type DiffStat = {
+    schema: 1;
+    base: string;
+    head: string;
+    fileCount: number;
+    additions: number;
+    deletions: number;
+    binaryCount: number;
+    files: DiffStatFile[];
+    /** True when the file list was cut to fit the cap — counts stay complete. */
+    filesTruncated: boolean;
+};
+/**
+ * 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 declare function parseNumstat(raw: string, base: string, head: string): DiffStat;
+/** The freshness-stamped handoff artifact's shape (M6.10). */
+export type HandoffArtifact = {
+    schema: 1;
+    taskId: string;
+    runId: number;
+    provider: string;
+    /** v47: the exact model that ran, and the sealed route leg it ran as —
+     * provenance a later reader can hold against the approval. Absent on
+     * artifacts written before routes existed. */
+    model?: string;
+    route?: {
+        digest: string;
+        phase: "plan" | "build" | "repair" | "review";
+        provider: string;
+        model: string | null;
+        chosen: "recommended" | "override" | "pinned" | "legacy" | "fallback";
+    };
+    sessionId: string | null;
+    branch: string;
+    worktree: string;
+    base: string;
+    head: string;
+    outcome: "built" | "no-change";
+    committed: boolean;
+    /** Decision ids whose answers were in this run's brief — causality, not time. */
+    decisionsIncorporated: number[];
+    /** The agent's conclusion — agent-reported, and labeled so by its position here. */
+    conclusion: string;
+    /** Structured operator-facing output. Optional for artifacts written by
+     * older versions; readers treat absence as an empty list. */
+    changes?: string[];
+    verification?: string[];
+    followUps?: string[];
+    freshness: {
+        stampedAt: string;
+        /** A successor proves this against the branch before trusting anything above. */
+        currentAsOf: string;
+    };
+};
+/**
+ * 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 declare function storeHandoffArtifact(store: Store, root: string, payload: HandoffArtifact, now: Date): number;
+/**
+ * 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 declare const SECRET_PATTERNS: readonly {
+    name: string;
+    pattern: RegExp;
+}[];
+export type SecretHit = {
+    name: string;
+    line: number;
+};
+/** Scan text line by line; every hit names its pattern and line. */
+export declare function scanForSecrets(text: string): SecretHit[];
+/** Replace every hit line with a marker naming what was found — the display copy holds no secret. */
+export declare function redactSecretLines(text: string, hits: readonly SecretHit[]): string;
+/**
+ * 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 declare function budgetedStatJson(stat: DiffStat): Buffer;
+/**
+ * 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 declare function captureTerminalDiff(store: Store, git: (file: string, args: readonly string[], options?: {
+    cwd?: string;
+}) => Promise<ExecResult>, worktree: string, base: string, head: string, root: string, runId: number, now: Date): Promise<{
+    diffId: number;
+    statId: number;
+}>;
+/**
+ * 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 declare function captureBaseTree(store: Store, git: (file: string, args: readonly string[], options?: {
+    cwd?: string;
+    envAllowlist?: readonly string[];
+}) => Promise<ExecResult>, repoRoot: string, repo: string, base: string, root: string, runId: number, now: Date): Promise<{
+    ok: boolean;
+}>;