toolroll 0.9.71 → 0.9.72

package/dist/builder.js

@@ -8,6 +8,9 @@ import { queueBatchCheck } from "./batch-checks.js";
 import { batchesFullCheck } from "./batch-policy.js";
 import { skillsContext } from "./project-skills.js";
 import { failedVerificationEvidence, sealVerificationReceipt, verificationEvidence, reuseObservationVerification } from "./verification-evidence.js";
+import { CHECK_INVENTORY_CAPTURE, CHECK_REPORT_CAPTURE, prepareCheckAttempt, sealCheckOutcome } from "./check-report.js";
+import { planTargetedRecheck, settleCoverage } from "./release-recheck.js";
+import { effectiveCheckFacts } from "./verification-evidence.js";
 import { learningContext } from "./project-learning.js";
 import { knowledgeContext } from "./project-knowledge.js";
 import { flowGoalCuts } from "./flow-engine.js";
@@ -322,12 +325,13 @@ export function proveApprovedProfile(scope, given) {
                 budgetMicrousd: scope.budgetMicrousd,
                 acceptance: scope.acceptance, candidate: scope.candidate ?? null,
                 qualityMode: scope.qualityMode ?? "default",
+                releaseTerms: scope.releaseTerms ?? null,
             }, snapshot, 
             // v47: the SEALED route is part of the signed bytes whenever it
             // says more than the legacy resolution — re-derived here from
             // the seal's own snapshot, never from mutable configuration.
             routeFromJson(scope.approvedRouteJson ?? null))
-            : digestOf({ goal: scope.goal, outOfScope: scope.outOfScope, touches: scope.touches, budgetMicrousd: scope.budgetMicrousd, acceptance: scope.acceptance, candidate: scope.candidate ?? null });
+            : digestOf({ goal: scope.goal, outOfScope: scope.outOfScope, touches: scope.touches, budgetMicrousd: scope.budgetMicrousd, acceptance: scope.acceptance, candidate: scope.candidate ?? null, releaseTerms: scope.releaseTerms ?? null });
         if (rederived !== scope.approvedDigest) {
             return { ok: false, message: "the approval record does not verify against the stored terms — re-approve (stale-approval)" };
         }
@@ -416,7 +420,7 @@ export async function build(store, request) {
         return {
             ok: false,
             reason: "mode-ended",
-            message: `${taskId}'s approval was signed by an operating mode that has ended — the approval falls back to a person`,
+            message: `${taskId}'s approval no longer stands (an ended mode or flow grant, or an approval that wasn't a person's) — a person approves it again`,
         };
     }
     // v24 DISPATCH PROOF (foundations rulings 10/12, findings 6/17): what is
@@ -2251,6 +2255,9 @@ async function settleProof(captured, statArtifactId, sealedHead) {
     const batched = repo !== null && chosenCheck !== null && batchesFullCheck(store, repo, chosenCheck.level, configured);
     const gateCommand = batched ? null : configured;
     let verifyCommand;
+    let checkAttempt = null;
+    let releaseFacts = null;
+    const verification = { last: null };
     const checkLog = [];
     const checkOutcomes = [];
     const checkSuites = [];
@@ -2296,6 +2303,20 @@ async function settleProof(captured, statArtifactId, sealedHead) {
     else {
         const verifyRunner = request.verify ?? run;
         const verifyShell = approvedCommandShell(configured.command);
+        // A Full check of a prepared candidate (a release gate, the nightly check): its attempt is sealed before the command
+        // runs — intended mode, nonce, inventory, context — and the handshake goes on its stdin (check-report.ts).
+        // A release task's check is targeted when the release's last full check allows it (release-recheck.ts): its plan and
+        // obligation snapshot are sealed with the attempt; otherwise it runs in full, told which tests it must still report.
+        if (repo !== null && chosenCheck?.level === "full" && (store.getScope(request.taskId)?.candidate ?? null) !== null) {
+            const access = checkLaunchOf(store, runId, captured.effective.profile).access;
+            const decision = planTargetedRecheck(store, root, { runId, taskId: request.taskId, repo, head: sealedHead, command: configured, access, now: now() });
+            checkAttempt = prepareCheckAttempt(store, root, { runId, repo, head: sealedHead, command: configured, access, authority: decision.authority,
+                ...(decision.mode === "targeted" ? { plan: decision.plan, snapshot: decision.snapshot } : {}), watch: decision.watch }, now());
+            if (checkAttempt !== null && decision.mode === "targeted")
+                store.addRunNote(runId, "Toolroll", `Re-running only what failed at run #${decision.plan.base}: ${decision.plan.units.length} unit files, ${decision.plan.groups.reduce((n, one) => n + one.groups.length, 0)} journey groups, ${decision.plan.versions.length} upgrade versions${decision.plan.parts.length > 0 ? `, and in full: ${decision.plan.parts.join(", ")}` : ""}.`, now());
+        }
+        else
+            checkAttempt = null;
         const checkProgress = new CheckProgressTracker(snapshot => {
             store.saveCheckProgress(runId, snapshot, now());
         });
@@ -2315,6 +2336,7 @@ async function settleProof(captured, statArtifactId, sealedHead) {
                 },
                 envAllowlist: SETUP_ENV_ALLOWLIST,
                 omitEnv: SETUP_ENV_DENYLIST,
+                ...(checkAttempt === null ? {} : { stdin: checkAttempt.stdin }),
                 onStdout: chunk => { streamed.stdout = true; checkProgress.feed(chunk, "stdout"); },
                 onStderr: chunk => { streamed.stderr = true; checkProgress.feed(chunk, "stderr"); },
             }));
@@ -2327,6 +2349,7 @@ async function settleProof(captured, statArtifactId, sealedHead) {
             checkOutcomes.push(attemptOutcome(label, result));
             noteCheckSuite(label, result);
             checkLog.push(attemptLog(label, configured.command, result));
+            verification.last = result;
             return result;
         };
         const ownInstallIfChanged = async () => {
@@ -2497,6 +2520,22 @@ async function settleProof(captured, statArtifactId, sealedHead) {
             }
         }
         checkProgress.finish();
+        // The check's own report (the last line carrying the nonce), sealed beside what was sealed before it ran.
+        const last = verification.last;
+        if (checkAttempt !== null && last !== null && !last.notFound) {
+            sealCheckOutcome(store, root, checkAttempt, { stdout: last.stdout, exitCode: last.timedOut ? null : last.code }, now());
+        }
+        // What the check covered (receipt version 3): full, composed from the release's last full check, partial, or
+        // identity-removed (which stops the release carrying).
+        if (checkAttempt !== null) {
+            const settled = settleCoverage(store, root, { runId, taskId: request.taskId, exitCode: last === null || last.notFound || last.timedOut ? null : last.code, now: now() }, run => { const gate = verificationEvidence(store, root, run); return gate.ok ? gate.digest : null; });
+            const sha = (capture) => { const found = store.artifactsFor(runId).filter(a => a.kind === "structured-output" && a.capture === capture); return found.length === 1 ? found[0].sha256 : null; };
+            // The one place coverage meets the outcome: a partial or identity-removed check is a failed attempt for every
+            // reader from here on (the verdict, the run's check, the receipt, reuse, the deploy gates).
+            const effective = effectiveCheckFacts(verifyCommand, { coverage: settled.coverage, check: { attempt: checkAttempt.mode, report: sha(CHECK_REPORT_CAPTURE), inventory: sha(CHECK_INVENTORY_CAPTURE) }, composed: settled.composed });
+            verifyCommand = effective.result;
+            releaseFacts = effective.facts;
+        }
     }
     if (configured !== null && checkLog.length > 0) {
         const summary = `=== Attempt summary ===\n${checkOutcomes.length === 0 ? "No command started." : checkOutcomes.map(one => `- ${one}`).join("\n")}`;
@@ -2513,14 +2552,17 @@ async function settleProof(captured, statArtifactId, sealedHead) {
         });
     }
     if (configured !== null && checkLog.length > 0)
-        sealVerificationReceipt(store, root, runId, sealedHead, configured, verifyCommand, now());
+        sealVerificationReceipt(store, root, runId, sealedHead, configured, verifyCommand, now(), undefined, releaseFacts ?? undefined);
     // The receipt above remains the evidence. This compact projection is what
     // `status` and `task wait` can read without opening logs. A reused gate did
     // not execute here, so its label says so instead of implying a fresh run.
+    // A release check that didn't cover what it owed (partial) or lost a required test reads failed, whatever its exit.
+    const uncovered = releaseFacts !== null && releaseFacts.coverage !== "full" && releaseFacts.coverage !== "composed";
     const checkStatus = verifyCommand.configured === false ? "not-run"
-        : verifyCommand.ran ? verifyCommand.exitCode === 0 ? "passed" : "failed"
-            : checkSuites.some(one => one.status === "failed") ? "failed"
-                : "not-run";
+        : uncovered ? "failed"
+            : verifyCommand.ran ? verifyCommand.exitCode === 0 ? "passed" : "failed"
+                : checkSuites.some(one => one.status === "failed") ? "failed"
+                    : "not-run";
     const suites = checkSuites.length > 0 ? checkSuites : verifyCommand.configured === false ? [] : [{
             name: reused === null ? chosenCheck?.level === "quick" ? "Quick check" : "Project check" : "Project check (reused)",
             status: checkStatus,

package/dist/chat-decide.js

@@ -12,6 +12,7 @@
  * The same in every chat app: Telegram's bridge and the shared engine Slack, Discord and Teams run on (chat-delivery.ts)
  * offer, mint and answer these through the same tokens (the `channel` column). Every act runs through the door the
  * console uses. */
+import { NIGHTLY_CHECK_ONLY, RELEASE_MERGES_ONLY, nightlyTaskRef, releaseTaskRef } from "./store.js";
 import { isAcpProfile } from "./acp-agents.js";
 import { DECIDE_ACTS, readDecideActionRow } from "./contracts/chat-callback-rows.js";
 import { createHash, randomBytes } from "node:crypto";
@@ -27,6 +28,7 @@ import { verifyApproverStanding } from "./principal.js";
 import { pullRequestFollowOf } from "./pull-request-flow.js";
 import { requestResultChanges } from "./result-actions.js";
 import { revisionSourceOf } from "./result-review.js";
+import { APPROVAL_PROOF, approvalOf, approvalProofDetail, quarantinedAuthor } from "./scope.js";
 import { phoneText } from "./telegram-status.js";
 /** The words, said once. */
 export const DECIDE_LABELS = {
@@ -100,7 +102,9 @@ export function planInChat(store, taskId, approver, now, channel, root) {
     const scope = store.getScope(taskId);
     if (ref === null || ref.repo === null || scope === null)
         return { ok: false, why: "This plan isn't available now." };
-    if (scope.approvedDigest != null && scope.approvedDigest === scope.digest)
+    // Approved only as dispatch reads it (approval policy): an old seal a lead token made, or one whose authority has
+    // ended, is no approval, so the person can approve it here.
+    if (approvalOf(scope).approved && store.modeApprovalLive(ref.id, now))
         return { ok: false, why: "This plan is already approved." };
     if (ref.plan === "requested")
         return { ok: false, why: "The plan is still being written." };
@@ -113,7 +117,7 @@ export function planInChat(store, taskId, approver, now, channel, root) {
     if (family === null || family.problem !== null || family.current.id !== taskId)
         return { ok: false, why: "A newer version of this task is current." };
     // What the mode's seal refuses anyway, said first: model- or coordinator-written terms, an unreadable route.
-    if (ref.coordinatorCid !== null || (scope.proposedVia ?? null) !== null)
+    if (ref.coordinatorCid !== null || quarantinedAuthor(scope.proposedVia ?? null))
         return { ok: false, why: "This plan was written for you, so you approve it in Toolroll." };
     if (scope.profileState === "unresolved" || scope.routeEra == null || (scope.termsProblem ?? null) !== null)
         return { ok: false, why: "This plan can't say exactly which agents run, so you approve it in Toolroll." };
@@ -158,6 +162,12 @@ export function planInChat(store, taskId, approver, now, channel, root) {
 /** A ready pull request this person's chat may merge now, bound to the exact commit. */
 export function mergeInChat(store, taskId, run, approver, now, channel) {
     const ref = store.lookupRef(taskId);
+    // The nightly check of main never merges (release-once.md, part 3).
+    if (ref !== null && nightlyTaskRef(store, ref.id))
+        return { ok: false, why: NIGHTLY_CHECK_ONLY };
+    // A release's result merges only through its coordinator.
+    if (ref !== null && releaseTaskRef(store, ref.id))
+        return { ok: false, why: RELEASE_MERGES_ONLY };
     const publication = store.publicationForRun(run);
     const follow = publication === null ? null : pullRequestFollowOf(store, publication.id);
     if (ref === null || ref.repo === null || publication === null || follow === null || publication.prNumber === null)
@@ -517,6 +527,11 @@ export function applyDecideTap(store, seat, input) {
             // The owner's own yes, sealed as theirs ("chat"), never as a mode's: it stands like the console's after the mode or setting ends.
             if (!store.sealScopeApproval(row.taskId, who.name, now, {}, { kind: "chat", modeDigest: plan.modeDigest }))
                 return notDone("the plan couldn't be approved from chat. Open it in Toolroll.");
+            // The person's proof beside the seal, bound to these exact words (approval policy §1.2): a paired-chat tap, never a
+            // password. Release, deploy and the protected counters read it as a person's.
+            const sealedDigest = store.getScope(row.taskId)?.approvedDigest ?? "";
+            store.recordAction({ at: now.toISOString(), actor: who.name, repo: ref.repo, taskId: row.taskId, runId: null, action: APPROVAL_PROOF, outcome: "chat",
+                source: "request", detail: approvalProofDetail(now.getTime(), store.accountOf(who.name)?.generation ?? 0, sealedDigest) });
             store.recordAction({ at: now.toISOString(), actor: who.name, repo: ref.repo, taskId: row.taskId, runId: null, action: "plan approved in chat", outcome: "approved",
                 source: "request", detail: `via ${seat.channel} · chat binding #${seat.binding} · ${plan.source} ${plan.modeDigest}` });
             return done("✓ Approved. Work starts when a worker is free.");

package/dist/check-access.js

@@ -17,11 +17,11 @@ export const widerThan = (a, b) => RANK[a] > RANK[b];
 export const narrowestAccess = (levels) => levels.reduce((low, one) => RANK[one] < RANK[low] ? one : low, levels.length === 0 ? CHECK_ACCESS_DEFAULT : "unsandboxed");
 /** The level as a person reads it, in a sentence's middle ("Checks: …"). */
 export function checkAccessWords(level) {
-    return level === "sandboxed" ? "sandboxed" : level === "sign-ins" ? "sandboxed, with model and GitHub sign-ins and, on a Mac, Keychain access" : "not sandboxed";
+    return level === "sandboxed" ? "sandboxed" : level === "sign-ins" ? "sandboxed, with model and GitHub sign-ins" : "not sandboxed";
 }
 /** What each wider level means, said before anyone chooses it. */
 export const CHECK_ACCESS_WARNINGS = {
-    "sign-ins": "This project's checks can read your Claude, Codex and GitHub sign-ins, even where the project hides your home folder's files from builds. On a Mac that includes Keychain access: they can read any keychain item that lets every program read it, not only those sign-ins. Its tests could use or send those credentials anywhere its network setting allows. Only choose this for projects you trust.",
+    "sign-ins": "This project's checks can read your Claude, Codex and GitHub sign-ins, even where the project hides your home folder's files from builds. Its tests could use or send those credentials anywhere its network setting allows. Only choose this for projects you trust.",
     unsandboxed: "This project's checks get your full access to this machine and to Toolroll itself, including its database and every sign-in. Only for a project whose checks must create sandboxes themselves, such as Toolroll's own.",
 };
 /** The services whose sign-ins a `sign-ins` check reads: Claude's and Codex's own hosts (egress.ts), and GitHub's. */

package/dist/check-report.d.ts

@@ -0,0 +1,109 @@
+import { type VerifiedEntry } from "./commit-extract.js";
+import { CHECK_PARTS, type CheckContext, type CheckInventory, type CheckReport, type ObligationSnapshot, type TargetedPlan } from "./contracts/release-check.js";
+import { type Store, type VerifyCommand } from "./store.js";
+/** The sealed artifacts' capture labels: what a reader looks for, by exact name. */
+export declare const CHECK_REPORT_CAPTURE = "release check report v1";
+export declare const CHECK_INVENTORY_CAPTURE = "release check inventory v1";
+export declare const TARGETED_PLAN_CAPTURE = "release check targeted plan v1";
+export declare const OBLIGATION_SNAPSHOT_CAPTURE = "release check obligation snapshot v1";
+export declare const CHECK_CONTEXT_CAPTURE = "release check context v1";
+/** How large a sealed check artifact may be (the report's own bound). */
+export declare const CHECK_ARTIFACT_CAP: number;
+/** The release check's harness, named: the orchestrator, its runners and helpers, Vitest's configuration and setup, and
+ * the reporter. These never carry (release-carry.ts). The execution context digests far more (inHarnessDigest). */
+export declare const HARNESS_FILES: readonly string[];
+/** Vitest's include globs (vitest.config.ts), as the plane reads them: a change to that file is a harness change. */
+export declare const UNIT_INCLUDE: readonly RegExp[];
+export declare const isUnitFile: (path: string) => boolean;
+/** The project's own Git directory as Toolroll records it: `<realpath(repo)>/.git`, a real directory. */
+export declare function projectGitDir(repo: string): string | null;
+/** A digest of a payload, over its canonical JSON. */
+export declare const payloadDigest: (value: unknown) => string;
+/**
+ * Whether a tree path is part of the harness for the execution context: every file EXCEPT the unit test files
+ * themselves, the two journey scripts, docs and Markdown. No import tracing: a harness dependency reached by any road
+ * (a `require`, a computed `import()`, a side-effect import, a `src/` helper, a config file) is inside this set, so a
+ * change to it always changes the digest (fail closed).
+ */
+export declare function inHarnessDigest(path: string): boolean;
+/** What the plane reads from a commit for a check: its tree's entries, its unit files and its harness. */
+export type TreeFacts = {
+    tree: string;
+    entries: VerifiedEntry[];
+    units: string[];
+    harness: string[];
+    harnessDigest: string;
+    lockfile: string | null;
+};
+/** The tree facts of `sha`, from objects hashed here (never the checkout). Null with why when they can't be read. */
+export declare function treeFactsOf(gitDir: string, sha: string): {
+    ok: true;
+    facts: TreeFacts;
+} | {
+    ok: false;
+    problem: string;
+};
+/** The execution context a check runs in: what must match for results to stand beside each other. The machine's load
+ * budget is left out: it changes how fast a check runs, never what passes (scripts/release-check.mjs checkBudget). */
+export declare function checkContextOf(facts: TreeFacts, command: VerifyCommand, access: string): CheckContext;
+/** The parts a full check selects, as far as the plane knows them before it runs. */
+export declare const FULL_PARTS: readonly (typeof CHECK_PARTS[number])[];
+/** What a check must account for, sealed before it runs: every unit file of the tree, whatever runs (a targeted
+ * check accounts for the rest through its base), and the parts it selects. */
+export declare function inventoryOf(facts: TreeFacts, plan: TargetedPlan | null): CheckInventory;
+/** A check about to run: its handshake (written on stdin, then closed) and the facts sealed with it. */
+export type PreparedAttempt = {
+    runId: number;
+    nonce: string;
+    stdin: string;
+    mode: "full" | "targeted";
+    inventory: CheckInventory;
+    context: CheckContext;
+    plan: TargetedPlan | null;
+    snapshot: ObligationSnapshot | null;
+    /** The identities the check was asked to report one by one (required ones). */
+    watch: string[];
+};
+/**
+ * Seal a check's attempt row before its command is spawned: intended mode, nonce hash, inventory and context (and for a
+ * targeted check its plan and obligation snapshot, sealed as artifacts first). Null when the plane can't read the
+ * commit, which leaves the check running exactly as it always has, with no handshake.
+ */
+export declare function prepareCheckAttempt(store: Store, root: string, input: {
+    runId: number;
+    repo: string;
+    head: string;
+    command: VerifyCommand;
+    access: string;
+    authority?: number | null;
+    plan?: TargetedPlan | null;
+    snapshot?: ObligationSnapshot | null;
+    watch?: readonly string[];
+}, now: Date): PreparedAttempt | null;
+/** Seal one JSON payload as a structured-output artifact under its capture label. */
+export declare function sealJson(store: Store, root: string, runId: number, name: string, value: unknown, capture: string, now: Date): number;
+/**
+ * The check's report from its output: the LAST `TOOLROLL_CHECK_REPORT <json>` line carrying this nonce, at most 256 KiB,
+ * that matches the contract. Lines without the nonce (a test's print, a leftover process's write) are passed over.
+ */
+export declare function reportFromOutput(stdout: string, nonce: string): {
+    ok: true;
+    report: CheckReport;
+    raw: string;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * After the check: seal its report (when it gave a valid one) and the inventory artifact. `exitCode` is the check's own
+ * exit; a report that disagrees with it is no report. Returns the report, or null.
+ */
+export declare function sealCheckOutcome(store: Store, root: string, attempt: PreparedAttempt, output: {
+    stdout: string;
+    exitCode: number | null;
+}, now: Date): CheckReport | null;
+/** One sealed check artifact of a run, read back and verified, or null (missing, ambiguous, cut short or changed). */
+export declare function readSealedJson(store: Store, root: string, runId: number, capture: string): {
+    value: unknown;
+    digest: string;
+} | null;

package/dist/check-report.js

@@ -0,0 +1,204 @@
+/**
+ * The release check's structured report, on the plane's side (docs/plans/release-once.md, part 2 and rollout phase A).
+ *
+ * Before a Full check of a prepared candidate runs, the builder seals a `release_check_attempt` row: the intended mode
+ * (`full`, or `targeted` with its plan and obligation snapshot), the hash of a fresh nonce, the inventory the check must
+ * account for (the unit files, from the verified tree and Vitest's include globs, and the parts selected) and the
+ * execution context. It then writes `{"nonce","mode","plan","watch"}` on the check's stdin and closes it.
+ *
+ * After the check, the report is the last `TOOLROLL_CHECK_REPORT <json>` line of its output that carries that nonce
+ * (a line a test prints, or one a leftover process writes, has no nonce and is ignored). It is read strictly and sealed
+ * as `check-report.json`, beside `check-inventory.json` (what was sealed, and the groups and versions the check
+ * declared). A run with no valid report still passes or fails as before; it just can't be the base of a targeted check.
+ *
+ * Coverage trusts test code (the trust decision in the plan). Nothing here decides who may release or deploy.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { lstatSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { readVerifiedCommit, verifiedTreeEntries } from "./commit-extract.js";
+import { CHECK_PARTS, CHECK_REPORT_MAX_BYTES, CHECK_REPORT_PREFIX, readCheckReport, } from "./contracts/release-check.js";
+import { readVerifiedArtifact, storeEvidence } from "./evidence.js";
+import { checkAttemptOf, recordCheckAttempt } from "./store.js";
+/** The sealed artifacts' capture labels: what a reader looks for, by exact name. */
+export const CHECK_REPORT_CAPTURE = "release check report v1";
+export const CHECK_INVENTORY_CAPTURE = "release check inventory v1";
+export const TARGETED_PLAN_CAPTURE = "release check targeted plan v1";
+export const OBLIGATION_SNAPSHOT_CAPTURE = "release check obligation snapshot v1";
+export const CHECK_CONTEXT_CAPTURE = "release check context v1";
+/** How large a sealed check artifact may be (the report's own bound). */
+export const CHECK_ARTIFACT_CAP = CHECK_REPORT_MAX_BYTES;
+/** The release check's harness, named: the orchestrator, its runners and helpers, Vitest's configuration and setup, and
+ * the reporter. These never carry (release-carry.ts). The execution context digests far more (inHarnessDigest). */
+export const HARNESS_FILES = Object.freeze([
+    "scripts/release-check.mjs", "scripts/release-check-ci.mjs", "scripts/suite-lifecycle.mjs", "scripts/provider-gate.mjs",
+    "scripts/e2e-parallel.mjs", "scripts/e2e-kit.mjs", "scripts/upgrade-path.mjs", "scripts/check-results.mjs",
+    "vitest.config.ts", "test/attacks/vitest.config.ts",
+    "test/setup-state.ts", "test/fresh-store.ts", "test/temp-root.ts", "test/ensure-build.ts", "test/release-reporter.ts",
+]);
+/** Vitest's include globs (vitest.config.ts), as the plane reads them: a change to that file is a harness change. */
+export const UNIT_INCLUDE = Object.freeze([/^src\/.+\.test\.ts$/, /^test\/attacks\/.+\.test\.ts$/]);
+export const isUnitFile = (path) => UNIT_INCLUDE.some(one => one.test(path));
+/** The project's own Git directory as Toolroll records it: `<realpath(repo)>/.git`, a real directory. */
+export function projectGitDir(repo) {
+    try {
+        const named = join(realpathSync(repo), ".git");
+        return lstatSync(named).isDirectory() ? realpathSync(named) : null;
+    }
+    catch {
+        return null;
+    }
+}
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+/** A digest of a payload, over its canonical JSON. */
+export const payloadDigest = (value) => sha256(JSON.stringify(value));
+/**
+ * Whether a tree path is part of the harness for the execution context: every file EXCEPT the unit test files
+ * themselves, the two journey scripts, docs and Markdown. No import tracing: a harness dependency reached by any road
+ * (a `require`, a computed `import()`, a side-effect import, a `src/` helper, a config file) is inside this set, so a
+ * change to it always changes the digest (fail closed).
+ */
+export function inHarnessDigest(path) {
+    if (isUnitFile(path))
+        return false;
+    if (path === "scripts/app-e2e.mjs" || path === "scripts/flows-e2e.mjs")
+        return false;
+    if (path.startsWith("docs/") || path.endsWith(".md"))
+        return false;
+    return true;
+}
+/** The tree facts of `sha`, from objects hashed here (never the checkout). Null with why when they can't be read. */
+export function treeFactsOf(gitDir, sha) {
+    const commit = readVerifiedCommit(gitDir, sha);
+    if (!commit.ok)
+        return { ok: false, problem: commit.message };
+    const entries = verifiedTreeEntries(gitDir, commit.value.tree);
+    if (!entries.ok)
+        return { ok: false, problem: entries.message };
+    const harness = entries.value.filter(one => inHarnessDigest(one.path)).map(one => one.path).sort();
+    const ids = new Map(entries.value.map(one => [one.path, one.id]));
+    return { ok: true, facts: {
+            tree: commit.value.tree,
+            entries: entries.value,
+            units: entries.value.filter(one => (one.mode === "100644" || one.mode === "100755") && isUnitFile(one.path)).map(one => one.path).sort(),
+            harness,
+            harnessDigest: payloadDigest(entries.value.filter(one => inHarnessDigest(one.path)).map(one => [one.path, one.mode, one.id])),
+            lockfile: ids.get("package-lock.json") ?? null,
+        } };
+}
+/** The execution context a check runs in: what must match for results to stand beside each other. The machine's load
+ * budget is left out: it changes how fast a check runs, never what passes (scripts/release-check.mjs checkBudget). */
+export function checkContextOf(facts, command, access) {
+    return { version: 1, node: process.version, platform: process.platform, arch: process.arch, lockfile: facts.lockfile, harness: facts.harnessDigest, grant: { id: command.id, digest: command.digest }, access };
+}
+/** The parts a full check selects, as far as the plane knows them before it runs. */
+export const FULL_PARTS = CHECK_PARTS;
+/** What a check must account for, sealed before it runs: every unit file of the tree, whatever runs (a targeted
+ * check accounts for the rest through its base), and the parts it selects. */
+export function inventoryOf(facts, plan) {
+    return { version: 1, units: facts.units, parts: plan === null ? [...FULL_PARTS] : ["typecheck", "build", ...plan.parts.filter(one => one !== "typecheck" && one !== "build")] };
+}
+/**
+ * Seal a check's attempt row before its command is spawned: intended mode, nonce hash, inventory and context (and for a
+ * targeted check its plan and obligation snapshot, sealed as artifacts first). Null when the plane can't read the
+ * commit, which leaves the check running exactly as it always has, with no handshake.
+ */
+export function prepareCheckAttempt(store, root, input, now) {
+    if (checkAttemptOf(store, input.runId) !== null)
+        return null;
+    const gitDir = projectGitDir(input.repo);
+    if (gitDir === null)
+        return null;
+    const read = treeFactsOf(gitDir, input.head);
+    if (!read.ok)
+        return null;
+    const plan = input.plan ?? null, snapshot = input.snapshot ?? null;
+    const inventory = inventoryOf(read.facts, plan);
+    const context = checkContextOf(read.facts, input.command, input.access);
+    const nonce = randomBytes(32).toString("hex");
+    const mode = plan === null ? "full" : "targeted";
+    sealJson(store, root, input.runId, "check-context.json", context, CHECK_CONTEXT_CAPTURE, now);
+    if (plan !== null)
+        sealJson(store, root, input.runId, "targeted-plan.json", plan, TARGETED_PLAN_CAPTURE, now);
+    if (snapshot !== null)
+        sealJson(store, root, input.runId, "obligation-snapshot.json", snapshot, OBLIGATION_SNAPSHOT_CAPTURE, now);
+    recordCheckAttempt(store, {
+        run: input.runId, authority: input.authority ?? null, mode, baseRun: plan?.base ?? null,
+        planDigest: plan === null ? null : payloadDigest(plan), snapshotDigest: snapshot === null ? null : payloadDigest(snapshot),
+        inventoryDigest: payloadDigest(inventory), contextDigest: payloadDigest(context), nonceHash: sha256(nonce),
+    }, now);
+    const stdin = JSON.stringify({ nonce, mode, plan, watch: [...(input.watch ?? [])] });
+    return { runId: input.runId, nonce, stdin, mode, inventory, context, plan, snapshot, watch: [...(input.watch ?? [])] };
+}
+/** Seal one JSON payload as a structured-output artifact under its capture label. */
+export function sealJson(store, root, runId, name, value, capture, now) {
+    const bytes = Buffer.from(JSON.stringify(value), "utf8");
+    if (bytes.length > CHECK_ARTIFACT_CAP)
+        throw new Error(`${name} is over ${CHECK_ARTIFACT_CAP} bytes`);
+    return storeEvidence(store, root, runId, "structured-output", name, bytes, capture, now, { captureStatus: "ok", cap: CHECK_ARTIFACT_CAP });
+}
+/**
+ * The check's report from its output: the LAST `TOOLROLL_CHECK_REPORT <json>` line carrying this nonce, at most 256 KiB,
+ * that matches the contract. Lines without the nonce (a test's print, a leftover process's write) are passed over.
+ */
+export function reportFromOutput(stdout, nonce) {
+    const lines = stdout.split("\n");
+    for (let at = lines.length - 1; at >= 0; at--) {
+        const line = lines[at];
+        if (!line.startsWith(CHECK_REPORT_PREFIX))
+            continue;
+        if (Buffer.byteLength(line) > CHECK_REPORT_MAX_BYTES)
+            continue;
+        const raw = line.slice(CHECK_REPORT_PREFIX.length);
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (parsed === null || typeof parsed !== "object" || parsed["nonce"] !== nonce)
+            continue;
+        const read = readCheckReport(parsed);
+        if (!read.ok)
+            return { ok: false, problem: `The check's report doesn't match its contract: ${read.issues.slice(0, 3).map(one => one.line).join("; ")}` };
+        return { ok: true, report: read.value, raw };
+    }
+    return { ok: false, problem: "The check gave no report for this run." };
+}
+/**
+ * After the check: seal its report (when it gave a valid one) and the inventory artifact. `exitCode` is the check's own
+ * exit; a report that disagrees with it is no report. Returns the report, or null.
+ */
+export function sealCheckOutcome(store, root, attempt, output, now) {
+    const read = reportFromOutput(output.stdout, attempt.nonce);
+    const report = read.ok && read.report.mode === attempt.mode && read.report.exitCode === output.exitCode &&
+        read.report.planDigest === (attempt.plan === null ? null : payloadDigest(attempt.plan)) ? read.report : null;
+    const declared = report === null ? { groups: [], versions: [] } : {
+        groups: report.journeys.map(one => ({ script: one.script, kind: one.kind, groups: one.groups.map(group => group.group) })),
+        versions: report.upgrades?.versions.map(one => one.version) ?? [],
+    };
+    const sealedInventory = { version: 1, sealed: attempt.inventory, declared };
+    sealJson(store, root, attempt.runId, "check-inventory.json", sealedInventory, CHECK_INVENTORY_CAPTURE, now);
+    if (report !== null)
+        sealJson(store, root, attempt.runId, "check-report.json", report, CHECK_REPORT_CAPTURE, now);
+    return report;
+}
+/** One sealed check artifact of a run, read back and verified, or null (missing, ambiguous, cut short or changed). */
+export function readSealedJson(store, root, runId, capture) {
+    const found = store.artifactsFor(runId).filter(one => one.kind === "structured-output" && one.capture === capture);
+    if (found.length !== 1)
+        return null;
+    const artifact = found[0];
+    if (artifact.truncated || artifact.redacted || artifact.captureStatus !== "ok")
+        return null;
+    const read = readVerifiedArtifact(root, artifact);
+    if (!read.ok)
+        return null;
+    try {
+        return { value: JSON.parse(read.content.toString("utf8")), digest: artifact.sha256 };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/claim.js

@@ -128,7 +128,7 @@ function acquireLocked(store, taskRef, runner, options) {
             return {
                 ok: false,
                 reason: "mode-ended",
-                message: "the operating mode that approved this has ended — the approval falls back to a person",
+                message: "the approval it was sealed with no longer stands (an ended mode or flow grant, or an approval that wasn't a person's) — a person approves it again",
             };
         }
         // A LEAD SWEEP'S LIMIT, inside this write transaction so two runners can't both take the last slot: at most

package/dist/commit-extract.d.ts

@@ -0,0 +1,94 @@
+export type Extraction = {
+    ok: true;
+    files: number;
+} | {
+    ok: false;
+    message: string;
+};
+/** What one extraction may hold, all checked before anything is written: the bytes written (every path, a blob shared
+ * by many paths counted once per path), the files, the tree entries walked and how deep the trees nest. */
+export type ExtractionLimits = {
+    bytes: number;
+    files: number;
+    entries: number;
+    depth: number;
+};
+export declare const EXTRACTION_LIMITS: ExtractionLimits;
+/** A tree path that stays where it says: relative, no empty, `.` or `..` part, no backslash or control character. */
+export declare function normalizedTreePath(path: string): boolean;
+/** The object id Git gives `<type> <size>\0<bytes>` in this repository's object format. */
+export declare const objectIdOf: (format: "sha1" | "sha256", type: string, bytes: Buffer) => string;
+type TreeEntry = {
+    mode: string;
+    name: string;
+    id: string;
+};
+/** A tree object's entries, parsed from its verified bytes: `<mode> <name>\0<raw id>` each. Null when malformed. */
+export declare function parseTree(bytes: Buffer, idBytes: number): TreeEntry[] | null;
+/** Write commit `sha` of the repository whose Git directory is `gitDir` (a realpath Toolroll took from its own
+ * records) into `dest`, an empty folder this process made. Every object on the way — the commit, each tree, each
+ * blob — is hashed here and must be the id that names it: Git's own answer about an id is never taken on trust, so a
+ * corrupted or replaced object in a store a build could write to refuses the extraction. */
+export declare function extractCommit(gitDir: string, sha: string, dest: string, limits?: ExtractionLimits): Extraction;
+/** A commit read from its verified bytes: its tree and its parents, in order. */
+export type VerifiedCommit = {
+    id: string;
+    tree: string;
+    parents: string[];
+    message: string;
+};
+/** One entry of a verified tree, at its full path: a file (100644, 100755), a symlink (120000) or a submodule (160000). */
+export type VerifiedEntry = {
+    path: string;
+    mode: string;
+    id: string;
+};
+/** One path that differs between two verified trees, with its line counts when both sides are text. */
+export type TreeChange = {
+    path: string;
+    kind: "added" | "modified" | "deleted";
+    before: VerifiedEntry | null;
+    after: VerifiedEntry | null;
+    added: number;
+    deleted: number;
+    binary: boolean;
+};
+export type Verified<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    message: string;
+};
+/** One commit, hashed here and parsed from its own bytes. */
+export declare function readVerifiedCommit(gitDir: string, sha: string): Verified<VerifiedCommit>;
+/**
+ * The commits from `from` back to `until` along first parents, newest first, `until` itself left out. Refuses when
+ * `until` isn't reached within `max` commits (it isn't an ancestor, or too much lies between), and hands back each
+ * commit's full parent list so a caller can refuse merges.
+ */
+export declare function verifiedFirstParentWalk(gitDir: string, from: string, until: string, max?: number): Verified<VerifiedCommit[]>;
+/** Every entry of a verified tree at its full path, symlinks and submodules included (a caller decides on them). An
+ * unnormalized path, or one a tree lists twice, refuses the whole read. */
+export declare function verifiedTreeEntries(gitDir: string, tree: string, limits?: ExtractionLimits): Verified<VerifiedEntry[]>;
+/** Whether bytes look binary: a NUL in the first 8000 bytes, as Git judges. */
+export declare const looksBinary: (bytes: Buffer) => boolean;
+/** The lines added and deleted from `before` to `after`, by the shortest edit (Myers): each counted once, stopped at
+ * `cap` total edits (the counts then add up to more than `cap`, which every limit here refuses). */
+export declare function lineChanges(before: Buffer, after: Buffer, cap?: number): {
+    added: number;
+    deleted: number;
+};
+/**
+ * What differs between two verified trees, path by path (no rename pairing: a moved file is a deletion and an
+ * addition). Text files get their added and deleted lines; a binary side, a symlink or a submodule is marked so a caller
+ * can refuse it.
+ */
+export declare function verifiedTreeDiff(gitDir: string, beforeTree: string, afterTree: string): Verified<TreeChange[]>;
+/** The ids of verified blobs at these paths of a tree (absent paths left out): a digest's inputs, read without
+ * running anything. */
+export declare function verifiedBlobs(gitDir: string, tree: string, paths: readonly string[]): Verified<Map<string, {
+    id: string;
+    bytes: Buffer;
+}>>;
+export {};