toolroll 0.9.91 → 0.9.93

package/dist/release-card.d.ts

@@ -1,4 +1,4 @@
-import { type ReleaseTerms } from "./contracts/release-terms.js";
+import { type ReleaseCheckPurpose, type ReleaseTerms } from "./contracts/release-terms.js";
 import type { Scope } from "./scope.js";
 import type { Store } from "./store.js";
 /** One signed term as the card says it. `key` names the scope field or the release term's path. */
@@ -29,6 +29,23 @@ export declare const SCOPE_TERM_LABELS: {
 /** Every field of the release terms, by its path in the terms (contracts/release-terms.ts), against the schema's
  * own leaves: the contract test checks every one has a label. */
 export declare const RELEASE_TERM_LABELS: Readonly<Record<string, string>>;
+/** Every field of a release check's purpose (contracts/release-terms.ts releaseCheckPurposeSchema): the sealed form
+ * Toolroll's own releases take while their checks run outside the sandbox. A contract test checks every leaf has one. */
+export declare const RELEASE_CHECK_LABELS: Readonly<Record<string, string>>;
+/** What a release scope sealed, either form: release terms (later test-only commits may carry) or a release check's
+ * purpose (every later commit asks again). The identity both share is read from here, never from a title or an id. */
+export type ReleaseSeal = {
+    kind: "terms";
+    terms: ReleaseTerms;
+    identity: ReleaseTerms;
+} | {
+    kind: "check";
+    purpose: ReleaseCheckPurpose;
+    identity: ReleaseCheckPurpose;
+};
+export declare function releaseSealOf(scope: Pick<Scope, "releaseTerms" | "releaseCheck"> | null): ReleaseSeal | null;
+/** What an unsandboxed (or sign-ins) release check means, said before anyone approves it. Null in the sandbox. */
+export declare function releaseAccessWords(access: ReleaseTerms["access"]): string | null;
 /** The leaf paths of a zod object schema (nested objects joined with dots). */
 export declare function schemaLeaves(schema: unknown, prefix?: string): string[];
 /** Every signed term of `scope`, its release terms included, one line each. Reads only. */
@@ -48,6 +65,9 @@ export type ChangeList = {
     digest: string;
     /** A release is on the record but its merge commit can't be read (eval-harness review 2, finding 4). */
     baselineUnreadable?: true;
+    /** Why the list couldn't be read whole (Codex round 2, finding 6): the pull request moved, or it is longer than
+     * GitHub lists. Part of the digest; never a shortened list. */
+    why?: string;
 };
 /**
  * The plane's own record of the last verified release of `repo`: the merge commit GitHub answered with, recorded once
@@ -70,8 +90,57 @@ export declare function commitsBetween(repo: string, from: string, to: string):
     sha: string;
     subject: string;
 }[] | null;
-/** What changed since the last verified release, for a release's terms, from Toolroll's records only. */
-export declare function releaseChangeList(store: Store, terms: ReleaseTerms): ChangeList;
+/** GitHub lists at most this many of a pull request's commits; a longer one is never shown as complete. */
+export declare const PULL_REQUEST_COMMITS_MAX = 250;
+/** A commit subject is someone else's text: one line, control-free (src/terminal-text.ts), bounded. The card digest
+ * binds this cleaned text, so every surface shows exactly what was bound (Codex round 2, finding 7). */
+export declare const subjectText: (subject: string) => string;
+/** How the plane reads GitHub for a pull request's commits (a seam for tests). */
+export type PullRequestReader = (args: readonly string[]) => {
+    status: number | null;
+    stdout: string;
+};
+/**
+ * A pull request's own commits from GitHub, for the recorded owner/name, complete and bound to the candidate (Codex
+ * round 2, finding 6): every page (`--paginate`), accepted only when the pull request's head is `head`, the newest
+ * listed commit is `head` and the count is the pull request's own count. Otherwise why, never a shortened list.
+ */
+export declare function pullRequestCommits(slug: string, pr: number, head: string, read?: PullRequestReader): {
+    ok: true;
+    commits: {
+        sha: string;
+        subject: string;
+    }[];
+} | {
+    ok: false;
+    why: string;
+};
+/** The ledger act that records a verified release (the merged tree proved equal to the approved one). */
+export declare const RELEASE_VERIFIED_ACTION = "release verified";
+/**
+ * Record a verified release (Codex round 2, finding 1: verified release history apart from carrying). The coordinator
+ * calls it once main's merge commit was proved to hold the approved tree; the plane proves it again here, from its own
+ * records only: the task is a release scope of a project, and `merge` read as a verified Git object from the project's
+ * recorded Git directory has exactly the sealed approved tree. False when anything doesn't hold (nothing written).
+ */
+export declare function recordVerifiedRelease(store: Store, input: {
+    taskId: string;
+    merge: string;
+    now: Date;
+}): boolean;
+/**
+ * The last verified release of `repo`, from either record: a merged release authority's succeeded merge, or a verified
+ * release row (recordVerifiedRelease). The newer stands. Shaped as releaseBaselineRecord.
+ */
+export declare function verifiedReleaseBaseline(store: Store, repo: string): {
+    recorded: false;
+} | {
+    recorded: true;
+    sha: string | null;
+};
+/** What changed since the last verified release, for a release's sealed identity (terms or a release check's purpose),
+ * from Toolroll's records only. */
+export declare function releaseChangeList(store: Store, terms: Pick<ReleaseTerms, "repo" | "approvedSha" | "pr">, read?: PullRequestReader): ChangeList;
 export type ReleaseCard = {
     /** Binds the scope digest, the plan form's digest, the baseline and the change list. */
     digest: string;
@@ -85,4 +154,4 @@ export declare function cardDigestOf(scopeDigest: string, formDigest: string, ch
 /** The release card for a deploy gate, against the live records now. */
 export declare function releaseCardOf(store: Store, scope: Scope, formDigest: string, words: {
     profile: (profile: Scope["profile"]) => string | null;
-}): ReleaseCard;
+}, read?: PullRequestReader): ReleaseCard;

package/dist/release-card.js

@@ -22,7 +22,9 @@ import { join } from "node:path";
 import { checkAccessWords } from "./check-access.js";
 import { CHECK_LEVEL_WORDS, effectiveCheckLevel } from "./check-levels.js";
 import { verifiedRange } from "./commit-extract.js";
-import { releaseTermsSchema } from "./contracts/release-terms.js";
+import { releaseCheckPurposeSchema, releaseTermsSchema } from "./contracts/release-terms.js";
+import { readVerifiedCommit } from "./commit-extract.js";
+import { cleanTerminalLine } from "./terminal-text.js";
 import { routeFromJson } from "./phase-routing.js";
 import { projectName } from "./project.js";
 import { RELEASE_CI_RUNNING_WORDS, releaseCiRunningOf } from "./release-ci-hold.js";
@@ -91,6 +93,30 @@ export const RELEASE_TERM_LABELS = {
     "policy.unsandboxedCarry": "Carry when checks aren't sandboxed",
     "grant.id": "Release check grant", "grant.digest": "Release check grant digest", access: "Release check access", expiresAt: "Expires",
 };
+/** Every field of a release check's purpose (contracts/release-terms.ts releaseCheckPurposeSchema): the sealed form
+ * Toolroll's own releases take while their checks run outside the sandbox. A contract test checks every leaf has one. */
+export const RELEASE_CHECK_LABELS = {
+    version: "Release check version", purpose: "Approved as", repo: "Repository", packageVersion: "Package version", branch: "Branch", pr: "Pull request",
+    base: "Base", approvedSha: "Approved commit", approvedTree: "Approved tree", "grant.id": "Release check grant", "grant.digest": "Release check grant digest",
+    access: "Release check access",
+};
+export function releaseSealOf(scope) {
+    if (scope === null)
+        return null;
+    if (scope.releaseTerms != null)
+        return { kind: "terms", terms: scope.releaseTerms, identity: scope.releaseTerms };
+    if (scope.releaseCheck != null)
+        return { kind: "check", purpose: scope.releaseCheck, identity: scope.releaseCheck };
+    return null;
+}
+/** What an unsandboxed (or sign-ins) release check means, said before anyone approves it. Null in the sandbox. */
+export function releaseAccessWords(access) {
+    if (access === "unsandboxed")
+        return "The release check runs this commit's code with full access to this computer.";
+    if (access === "sign-ins")
+        return "The release check runs this commit's code with your sign-ins on this computer.";
+    return null;
+}
 /** The leaf paths of a zod object schema (nested objects joined with dots). */
 export function schemaLeaves(schema, prefix = "") {
     const shape = schema.shape;
@@ -140,6 +166,15 @@ export function approvalTermsOf(store, scope, words) {
                 lines.push({ key: leaf.path, label: `Phase route ${leaf.path.slice("route.".length)}`, value: leaf.value });
     }
     const terms = scope.releaseTerms ?? null;
+    // A release check's purpose (the form Toolroll's own releases seal): every one of its fields, never "none".
+    if (terms === null && scope.releaseCheck != null) {
+        const purpose = scope.releaseCheck;
+        for (const path of schemaLeaves(releaseCheckPurposeSchema)) {
+            const value = path === "pr" ? `#${purpose.pr}` : path === "purpose" ? "a release check: every later commit asks again" : said(valueAt(purpose, path));
+            lines.push({ key: `releaseCheck.${path}`, label: RELEASE_CHECK_LABELS[path] ?? path, value });
+        }
+        return lines;
+    }
     for (const path of schemaLeaves(releaseTermsSchema)) {
         const label = RELEASE_TERM_LABELS[path] ?? path;
         const value = terms === null ? NONE : path === "pr" ? `#${terms.pr}`
@@ -195,20 +230,120 @@ export function commitsBetween(repo, from, to) {
     const range = verifiedRange(gitDir, from, to, { git: tools.git, env });
     if (!range.ok)
         return null;
-    return range.value.map(one => ({ sha: one.id, subject: one.message.split("\n")[0].trim() }));
+    return range.value.map(one => ({ sha: one.id, subject: subjectText(one.message) }));
 }
-/** A pull request's own commits from GitHub, for the recorded owner/name. Null when GitHub can't be read. */
-function pullRequestCommits(slug, pr) {
-    const tools = releaseTools();
-    const read = spawnSync(tools.gh, ["api", `repos/${slug}/pulls/${pr}/commits?per_page=100`, "--jq", '.[] | .sha + "\\t" + (.commit.message | split("\\n")[0])'], { cwd: "/", env: releaseGitEnv(), encoding: "utf8", timeout: 15_000 });
-    if (read.status !== 0)
+/** GitHub lists at most this many of a pull request's commits; a longer one is never shown as complete. */
+export const PULL_REQUEST_COMMITS_MAX = 250;
+/** A commit subject is someone else's text: one line, control-free (src/terminal-text.ts), bounded. The card digest
+ * binds this cleaned text, so every surface shows exactly what was bound (Codex round 2, finding 7). */
+export const subjectText = (subject) => cleanTerminalLine(subject.split("\n")[0] ?? "").trim().slice(0, 200);
+const ghRead = args => {
+    const read = spawnSync(releaseTools().gh, args, { cwd: "/", env: releaseGitEnv(), encoding: "utf8", timeout: 30_000, maxBuffer: 16 * 1024 * 1024 });
+    return { status: read.status, stdout: String(read.stdout ?? "") };
+};
+/**
+ * A pull request's own commits from GitHub, for the recorded owner/name, complete and bound to the candidate (Codex
+ * round 2, finding 6): every page (`--paginate`), accepted only when the pull request's head is `head`, the newest
+ * listed commit is `head` and the count is the pull request's own count. Otherwise why, never a shortened list.
+ */
+export function pullRequestCommits(slug, pr, head, read = ghRead) {
+    const about = read(["api", `repos/${slug}/pulls/${pr}`, "--jq", '[.head.sha, (.commits|tostring)] | join("\\t")']);
+    if (about.status !== 0)
+        return { ok: false, why: "GitHub couldn't be read" };
+    const [prHead, countText] = about.stdout.trim().split("\t");
+    const total = Number(countText);
+    if (prHead !== head)
+        return { ok: false, why: `the pull request is at ${SHA.test(prHead ?? "") ? prHead.slice(0, 7) : "another commit"}, not ${head.slice(0, 7)}` };
+    if (!Number.isSafeInteger(total) || total < 1)
+        return { ok: false, why: "GitHub didn't say how many commits the pull request has" };
+    if (total > PULL_REQUEST_COMMITS_MAX)
+        return { ok: false, why: `incomplete: the pull request has ${total} commits and GitHub lists only ${PULL_REQUEST_COMMITS_MAX}` };
+    const listed = read(["api", "--paginate", `repos/${slug}/pulls/${pr}/commits?per_page=100`, "--jq", '.[] | .sha + "\\t" + ((.commit.message | split("\\n")[0]) | @json)']);
+    if (listed.status !== 0)
+        return { ok: false, why: "GitHub couldn't be read" };
+    const commits = [];
+    for (const line of listed.stdout.split("\n")) {
+        if (line === "")
+            continue;
+        const tab = line.indexOf("\t");
+        const sha = line.slice(0, tab);
+        let subject;
+        try {
+            subject = JSON.parse(line.slice(tab + 1));
+        }
+        catch {
+            return { ok: false, why: "GitHub's answer didn't parse" };
+        }
+        if (tab < 0 || !SHA.test(sha) || typeof subject !== "string")
+            return { ok: false, why: "GitHub's answer didn't parse" };
+        commits.push({ sha, subject: subjectText(subject) });
+    }
+    if (commits.length !== total)
+        return { ok: false, why: `incomplete: GitHub listed ${commits.length} of ${total} commits` };
+    if (commits[commits.length - 1].sha !== head)
+        return { ok: false, why: `the newest commit GitHub listed isn't ${head.slice(0, 7)}` };
+    if (new Set(commits.map(one => one.sha)).size !== commits.length)
+        return { ok: false, why: "GitHub listed a commit twice" };
+    return { ok: true, commits: commits.reverse() };
+}
+/** The ledger act that records a verified release (the merged tree proved equal to the approved one). */
+export const RELEASE_VERIFIED_ACTION = "release verified";
+/** The project's own Git directory: `<realpath(repo)>/.git`, a real directory. */
+function gitDirOf(repo) {
+    try {
+        const named = join(realpathSync(repo), ".git");
+        return lstatSync(named).isDirectory() ? realpathSync(named) : null;
+    }
+    catch {
         return null;
-    return read.stdout.split("\n").filter(line => line !== "").map(line => { const tab = line.indexOf("\t"); return { sha: line.slice(0, tab), subject: line.slice(tab + 1) }; })
-        .filter(one => SHA.test(one.sha)).reverse();
+    }
+}
+/**
+ * Record a verified release (Codex round 2, finding 1: verified release history apart from carrying). The coordinator
+ * calls it once main's merge commit was proved to hold the approved tree; the plane proves it again here, from its own
+ * records only: the task is a release scope of a project, and `merge` read as a verified Git object from the project's
+ * recorded Git directory has exactly the sealed approved tree. False when anything doesn't hold (nothing written).
+ */
+export function recordVerifiedRelease(store, input) {
+    if (!SHA.test(input.merge))
+        return false;
+    const repo = store.lookupRef(input.taskId)?.repo ?? null;
+    const seal = releaseSealOf(store.getScope(input.taskId));
+    if (repo === null || seal === null || seal.identity.repo !== repo)
+        return false;
+    const gitDir = gitDirOf(repo);
+    if (gitDir === null)
+        return false;
+    const commit = readVerifiedCommit(gitDir, input.merge);
+    if (!commit.ok || commit.value.tree !== seal.identity.approvedTree)
+        return false;
+    if (store.handle.prepare("SELECT 1 FROM action_ledger WHERE task_id = ? AND action = ? AND detail = ?").get(input.taskId, RELEASE_VERIFIED_ACTION, input.merge) !== undefined)
+        return true;
+    store.recordAction({ at: input.now.toISOString(), actor: "toolroll", repo, taskId: input.taskId, runId: null, action: RELEASE_VERIFIED_ACTION, outcome: seal.identity.packageVersion,
+        source: "work", detail: input.merge });
+    return true;
+}
+/**
+ * The last verified release of `repo`, from either record: a merged release authority's succeeded merge, or a verified
+ * release row (recordVerifiedRelease). The newer stands. Shaped as releaseBaselineRecord.
+ */
+export function verifiedReleaseBaseline(store, repo) {
+    const authority = store.handle.prepare(`SELECT o.external_ref, COALESCE(o.finished_at, '') AS at FROM release_authority a LEFT JOIN release_operation o
+    ON o.authority = a.id AND o.kind = 'merge' AND o.state = 'succeeded'
+    WHERE a.repo = ? AND a.state = 'merged' ORDER BY a.id DESC, o.finished_at DESC LIMIT 1`).get(repo);
+    const verified = store.handle.prepare("SELECT detail, at FROM action_ledger WHERE repo = ? AND action = ? ORDER BY id DESC LIMIT 1").get(repo, RELEASE_VERIFIED_ACTION);
+    const verifiedSha = typeof verified?.["detail"] === "string" && SHA.test(verified["detail"]) ? verified["detail"] : null;
+    if (verified !== undefined && verifiedSha !== null && (authority === undefined || String(verified["at"]) >= String(authority["at"])))
+        return { recorded: true, sha: verifiedSha };
+    if (authority === undefined)
+        return verified === undefined ? { recorded: false } : { recorded: true, sha: null };
+    const ref = authority["external_ref"];
+    return { recorded: true, sha: typeof ref === "string" && SHA.test(ref) ? ref : null };
 }
-/** What changed since the last verified release, for a release's terms, from Toolroll's records only. */
-export function releaseChangeList(store, terms) {
-    const record = releaseBaselineRecord(store, terms.repo);
+/** What changed since the last verified release, for a release's sealed identity (terms or a release check's purpose),
+ * from Toolroll's records only. */
+export function releaseChangeList(store, terms, read) {
+    const record = verifiedReleaseBaseline(store, terms.repo);
     // A release recorded with a merge commit that can't be read: the list couldn't be read (eval-harness review 2,
     // finding 4) — never the pull request's commits, as if there were no previous release.
     if (record.recorded && record.sha === null)
@@ -216,6 +351,7 @@ export function releaseChangeList(store, terms) {
     const baseline = record.recorded ? record.sha : null;
     let commits;
     let source;
+    let why;
     if (baseline !== null) {
         commits = commitsBetween(terms.repo, baseline, terms.approvedSha);
         source = commits === null ? "unread" : "recorded";
@@ -223,10 +359,14 @@ export function releaseChangeList(store, terms) {
     else {
         const remote = store.projectRemote(terms.repo);
         const parsed = remote === null ? null : releaseRemote(remote);
-        commits = parsed === null ? null : pullRequestCommits(parsed.slug, terms.pr);
+        const listed = parsed === null ? { ok: false, why: "the project has no GitHub remote on record" } : pullRequestCommits(parsed.slug, terms.pr, terms.approvedSha, read);
+        commits = listed.ok ? listed.commits : null;
+        if (!listed.ok)
+            why = listed.why;
         source = commits === null ? "unread" : "pull-request";
     }
-    return { baseline, commits, source, digest: sha256(`release-changes:${JSON.stringify({ baseline, source, commits })}`) };
+    return { baseline, commits, source, ...(why === undefined ? {} : { why }),
+        digest: sha256(`release-changes:${JSON.stringify(why === undefined ? { baseline, source, commits } : { baseline, source, commits, why })}`) };
 }
 /** The card digest: everything the person is shown that can change under them. */
 export function cardDigestOf(scopeDigest, formDigest, changes) {
@@ -236,25 +376,30 @@ function changeWords(changes, terms, cap) {
     const head = changes.baseline === null ? `No earlier verified release is recorded. ${changes.source === "pull-request" ? `Pull request #${terms?.pr ?? "?"}'s commits:` : ""}`.trim()
         : `Changes since the last verified release (${changes.baseline.slice(0, 7)}):`;
     if (changes.commits === null)
-        return [head, changes.baseline === null && changes.baselineUnreadable !== true ? `The pull request's commits couldn't be read; see #${terms?.pr ?? "?"} on GitHub.` : "The change list couldn't be read."];
+        return [head, changes.baseline === null && changes.baselineUnreadable !== true ? `The pull request's commits couldn't be read${changes.why === undefined ? "" : ` (${changes.why})`}; see #${terms?.pr ?? "?"} on GitHub.` : "The change list couldn't be read."];
     if (changes.commits.length === 0)
         return [head, "No commits."];
     return [head, ...changes.commits.slice(0, cap).map(one => `• ${one.sha.slice(0, 7)} ${one.subject.slice(0, 100)}`), ...(changes.commits.length > cap ? [`• and ${changes.commits.length - cap} more`] : [])];
 }
 /** The release card for a deploy gate, against the live records now. */
-export function releaseCardOf(store, scope, formDigest, words) {
+export function releaseCardOf(store, scope, formDigest, words, read) {
     const terms = scope.releaseTerms ?? null;
+    // Either sealed form (Codex round 2, finding 1): the identity both share, for the head lines and the change list.
+    const identity = releaseSealOf(scope)?.identity ?? null;
     const lines = approvalTermsOf(store, scope, words);
     const value = (key) => lines.find(line => line.key === key)?.value ?? NONE;
-    const changes = terms === null
+    const changes = identity === null
         ? { baseline: null, commits: null, source: "unread", digest: sha256("release-changes:none") }
-        : releaseChangeList(store, terms);
-    const version = terms?.packageVersion ?? null;
+        : releaseChangeList(store, identity, read);
+    const version = identity?.packageVersion ?? null;
     const fileName = `release-${version ?? scope.taskId.replace(/[^A-Za-z0-9._-]/g, "-")}-terms.txt`;
     const short = [
         version === null ? `Deploy gate: ${value("title")}` : `Release ${version}: ${value("title")}`,
-        terms === null ? `Candidate ${said(scope.candidate).slice(0, 12)} · ${value("project")}` : `${projectName(terms.repo)} · ${terms.branch} · pull request #${terms.pr} · commit ${terms.approvedSha.slice(0, 7)}`,
-        terms === null ? `Checks: ${value("checks")} · check access: ${value("checkAccess")}` : `Carry later commits: ${terms.policy.carry ? "yes" : "no"} · checks: ${value("checks")} · expires ${terms.expiresAt}`,
+        identity === null ? `Candidate ${said(scope.candidate).slice(0, 12)} · ${value("project")}` : `${projectName(identity.repo)} · ${identity.branch} · pull request #${identity.pr} · commit ${identity.approvedSha.slice(0, 7)}`,
+        terms === null ? identity === null ? `Checks: ${value("checks")} · check access: ${value("checkAccess")}` : `Carry later commits: no, every later commit asks again · checks: ${value("checks")}`
+            : `Carry later commits: ${terms.policy.carry ? "yes" : "no"} · checks: ${value("checks")} · expires ${terms.expiresAt}`,
+        // What an unsandboxed check means, before consent (Codex round 2, finding 1).
+        ...(identity === null || releaseAccessWords(identity.access) === null ? [] : [releaseAccessWords(identity.access)]),
         // Option A's disclosure, on the card as on the approval sheet: never approved from chat without it.
         ...(terms !== null && terms.policy.carry && terms.access !== "sandboxed" ? ["This project's checks don't run in the sandbox: later test-only commits will run outside the sandbox without being shown to you first."] : []),
         // Filed while CI runs (Alex, 2026-10-29): a person may approve now, and is told plainly what still waits.
@@ -262,10 +407,10 @@ export function releaseCardOf(store, scope, formDigest, words) {
         // GitHub's nightly (nightly-github.ts): what holds this release, or why it can't be read. Not a signed term.
         ...(terms === null ? [] : nightlyReleaseLines(store, { repo: terms.repo, taskId: scope.taskId, candidate: scope.candidate ?? null, now: new Date() })),
         "",
-        ...changeWords(changes, terms, 5),
+        ...changeWords(changes, identity, 5),
         "",
         `Every term is in ${fileName}.`,
     ].join("\n");
-    const full = [`${version === null ? "Deploy gate" : `Release ${version}`}: every term`, "", termsText(lines), "", ...changeWords(changes, terms, 200)].join("\n");
+    const full = [`${version === null ? "Deploy gate" : `Release ${version}`}: every term`, "", termsText(lines), "", ...changeWords(changes, identity, 200)].join("\n");
     return { digest: cardDigestOf(scope.digest, formDigest, changes), short, full, fileName, changes };
 }

package/dist/release-cli.js

@@ -36,9 +36,14 @@ export const RELEASE_HELP = `toolroll release <branch> — release Toolroll itse
 
   Run the same command to resume after a stop. Interrupted deployments recover their saved stage before retrying.
 
-  A branch whose name is one of this command's own words (status, nightly, carry…) is named with --branch <name>
+  A branch whose name is one of this command's own words (approve, status, nightly, carry…) is named with --branch <name>
   or after --: \`toolroll release --branch status\`.
 
+toolroll release approve [<branch>] [--repo <path>] — approve the release waiting for you: shows the release, GitHub CI
+  now, what approving does, what changed and every term, then asks for your password (or uses your remembered login
+  where Passwordless allows it). Names the waiting releases when more than one could be meant. With --json it never
+  prompts: --as <you> --token <password> --digest <card digest>
+
 toolroll release status [<task>] — the steps of a release (the newest one recorded, or the release task named): each
   step's state and how long it took, and where it stopped
 
@@ -233,6 +238,9 @@ export async function runReleaseCommand(args, write, deps = {}) {
             return refuse("usage", "`toolroll release status [<task>]` takes only --json.", 2);
         return runStatusCommand(positional[1], write, json, deps);
     }
+    // `release approve` is the toolroll command's own (cli.ts routes it to the operate commands); never a branch here.
+    if (!named && positional[0] === "approve")
+        return refuse("usage", "Run `toolroll release approve [<branch>]`. A branch named approve is released with `--branch approve`.", 2);
     if (!named && positional[0] === "nightly" && positional.length === 1)
         return runNightlyCommand({ repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo), as, token, schedule: scheduleFlag, start: bare.has("--start") }, write, json, deps);
     if (!named && ["carry", "revoke", "ask-every-commit", "unsandboxed-carry", "auto-approve", "publish-ok"].includes(positional[0] ?? "") && positional.length === 2) {

package/dist/release.d.ts

@@ -332,6 +332,34 @@ export type ReleaseAuthorityAdapter = {
         why: string;
         warning: string | null;
     }>;
+    /** One-tap release approval (docs/plans/trusted-release-reports.md, slice A): what the plane tells a person and
+     * keeps for the approval sheet. Best effort: a failure here never changes the release. Absent on an older plane. */
+    ready?: ReleaseReadyAdapter;
+};
+/** What the coordinator tells the plane for a person's release (release-approval.ts). Ids and its own readings only. */
+export type ReleaseReadyAdapter = {
+    /** The approval step was entered (a fresh filing or a resumed one): one notification per task and scope digest. */
+    asked(taskId: string): Promise<void>;
+    /** The pull request's required checks on the candidate, as this coordinator just read them. */
+    ci(input: {
+        taskId: string;
+        candidate: string;
+        state: "passed" | "running" | "failed";
+        failed: readonly string[];
+        runs: readonly CheckRun[];
+    }): Promise<void>;
+    /** A person's release stopped: one attention notification per task, step and reason. */
+    stopped(input: {
+        taskId: string;
+        step: string;
+        reason: string;
+        message: string;
+    }): Promise<void>;
+    /** Main's merge commit was proved to hold the approved tree: the plane checks it again and keeps the release's record. */
+    verified(input: {
+        taskId: string;
+        merge: string;
+    }): Promise<void>;
 };
 /** The plane's automatic release approval, as the coordinator asks it. Every answer is the plane's own: the coordinator
  * hands it ids, never evidence (the plane reads GitHub CI itself for `approve`). */
@@ -451,11 +479,13 @@ export type ReleaseAdapters = {
         }): Promise<{
             scopeDigest: string;
         }>;
+        /** `reason` "stopping": Toolroll is still proving the check's build stopped (stop-proof.ts); it clears on its own. */
         complete(taskId: string, receipt: string): Promise<{
             ok: true;
         } | {
             ok: false;
             message: string;
+            reason?: string;
         }>;
         busy(): Promise<{
             running: number;

package/dist/release.js

@@ -453,6 +453,20 @@ export async function runRelease(options, adapters) {
         };
         // ---- one approval per release (release-once.md) -------------------------------------------------------------
         const rel = adapters.release;
+        /** One-tap release approval: tell the plane, never stopping or changing the release whatever it answers. */
+        const tell = async (act) => { if (rel?.ready === undefined)
+            return; try {
+            await act(rel.ready);
+        }
+        catch { /* best effort */ } };
+        /** The last pull request checks this run read on the candidate (the gate reads them before the task exists). */
+        let lastCi = null;
+        const noteCi = async (runs, verdict) => {
+            lastCi = { candidate: j.candidate.sha, state: verdict.state === "pending" ? "running" : verdict.state, failed: verdict.failed ?? [], runs: runs.filter(run => REQUIRED_PR_CHECKS.includes(run.name)) };
+            const seen = lastCi;
+            await tell(ready => ready.ci({ taskId: j.task.id, ...seen }));
+        };
+        const currentCi = () => lastCi;
         let epoch = null;
         // This invocation's own lease owner (review round 1): two runs of the same journal never share an epoch.
         const owner = `${j.id}:${randomUUID()}`;
@@ -693,6 +707,7 @@ export async function runRelease(options, adapters) {
                 throw error;
             }
             const verdict = prChecksVerdict(runs, j.candidate.sha, REQUIRED_PR_CHECKS, { workflow: REQUIRED_PR_CHECKS_WORKFLOW });
+            await noteCi(runs, verdict);
             if (verdict.state === "failed") {
                 throw new Stop("ci-failed", `GitHub's checks failed on ${j.candidate.sha.slice(0, 7)}: ${verdict.failed.join(", ")}. ${nothing}. ${j.approval === null ? "" : `The approval covers ${j.candidate.sha.slice(0, 7)} only. `}Rerun the failed job on GitHub and run \`${resume}\` again, or fix the branch and release the new commit with \`toolroll release ${releaseBranchArg(j.branch)} --repo ${j.checkout} --new\`.`);
             }
@@ -810,7 +825,7 @@ export async function runRelease(options, adapters) {
                             // The gate only stops on a check that already failed: the task is filed and a person asked while CI runs, and
                             // the release check runs beside it (pipeline-speed.md, D2 and "Decision: a person's release asks during
                             // CI"). The automatic approval waits for CI (the check step); nothing deploys before it passes (the deploy).
-                            const settled = await earlyChecks(adapters, j, (what, probe) => waitFor("gate", what, probe), { pendingIsEnough: true });
+                            const settled = await earlyChecks(adapters, j, (what, probe) => waitFor("gate", what, probe), { pendingIsEnough: true, seen: (runs, verdict) => noteCi(runs, verdict) });
                             // Recorded before the task exists, so its approval card says CI still runs from the first moment.
                             if (!settled)
                                 await rel?.auto?.ciRunning?.(j.task.id, j.candidate.sha);
@@ -830,6 +845,10 @@ export async function runRelease(options, adapters) {
                                 ...(rel === undefined ? {} : { release: { version: j.packageVersion, pr: j.pr, branch: j.branch, noCarry: options.noCarry === true } }),
                             });
                             j.task.scopeDigest = filed.scopeDigest;
+                            // The checks the gate read before the task existed, kept for its approval sheet now that it does.
+                            const seen = currentCi();
+                            if (seen !== null)
+                                await tell(ready => ready.ci({ taskId: j.task.id, ...seen }));
                         }
                         advance("approval");
                         break;
@@ -862,7 +881,11 @@ export async function runRelease(options, adapters) {
                         // A check that already failed asks nobody (as at the gate).
                         if (j.ciAhead === true)
                             await ciWhileRunning("Nothing was deployed or merged", true);
+                        // One push, on every entry to this step (a fresh filing or a resumed one): the plane files it once per task and
+                        // scope digest, so a crash between filing and here is healed by the next run.
+                        await tell(ready => ready.asked(j.task.id));
                         say(`  The release scope needs your approval: \`toolroll task approve ${j.task.id} --digest ${j.task.scopeDigest}\`, or open the task in the console.`);
+                        say(`  Or approve it from here: \`toolroll release approve ${releaseBranchArg(j.branch)}\`.`);
                         if (j.ciAhead === true)
                             say(`  ${CI_RUNNING_WORDS}`);
                         const approved = await waitFor("approval", `a person to approve task ${j.task.id}`, async () => {
@@ -1007,7 +1030,12 @@ export async function runRelease(options, adapters) {
                         await checked(gate, "complete");
                         if (gate.completion?.digest !== check.receipt) {
                             intend("complete");
-                            const done = await adapters.toolroll.complete(j.task.id, check.receipt);
+                            // Toolroll proves the check's build stopped by itself (stop-proof.ts) a short while after it finished: the
+                            // release waits for that, never for a person to confirm it.
+                            const done = await waitFor("quiet", "Toolroll to make sure the release check stopped", async () => {
+                                const tried = await adapters.toolroll.complete(j.task.id, check.receipt);
+                                return !tried.ok && tried.reason === "stopping" ? null : tried;
+                            });
                             if (!done.ok)
                                 throw new Stop("complete", `Couldn't mark task ${j.task.id} complete: ${done.message} Mark that exact result complete in the console, then rerun.`);
                         }
@@ -1202,6 +1230,8 @@ export async function runRelease(options, adapters) {
                         merge.tree = tree;
                         if (tree !== j.candidate.tree)
                             throw new Stop("tree-mismatch", `Main's merge commit ${merge.sha.slice(0, 7)} has tree ${tree.slice(0, 12)}, not the gated ${j.candidate.tree.slice(0, 12)}: main changed what was checked. Nothing was tagged; the deployed build stays as it is.`);
+                        // The release's verified record (trusted-release-reports.md A1): the next release's change list starts here.
+                        await tell(ready => ready.verified({ taskId: j.task.id, merge: merge.sha }));
                         advance("tag");
                         break;
                     }
@@ -1288,6 +1318,14 @@ export async function runRelease(options, adapters) {
             }
             catch { /* the stop is still reported */ }
             mark(journal.step, "failed", stop.message);
+            // A person's release that stops tells them (trusted-release-reports.md A5); the automatic road keeps its own notices.
+            const ready = adapters.release?.ready;
+            if (ready !== undefined && journal.auto?.state !== "checking" && journal.auto?.state !== "approved") {
+                try {
+                    await ready.stopped({ taskId: journal.task.id, step: journal.step, reason: stop.reason, message: stop.message });
+                }
+                catch { /* best effort */ }
+            }
         }
         return { ok: false, reason: stop.reason, message: stop.message, step: journal?.step ?? step, journal, file, resume };
     }
@@ -1428,6 +1466,7 @@ async function earlyChecks(adapters, j, wait, options = {}) {
                 return null;
             }
             const verdict = prChecksVerdict(runs.filter(run => required.includes(run.name)), j.candidate.sha, required, { workflow: REQUIRED_PR_CHECKS_WORKFLOW });
+            await options.seen?.(runs, verdict);
             if (verdict.state === "failed") {
                 throw new Stop("ci-failed", `Pull request checks already failed on ${sha}: ${verdict.failed.join(", ")}. ${nothing}. Fix the branch, then release the new commit with \`toolroll release ${j.branch} --repo ${j.checkout} --new\` (or rerun the failed job on GitHub and run this command again).`);
             }
@@ -1616,6 +1655,6 @@ export function workflowIs(path, file) {
     return /^[A-Za-z0-9._+/-]+$/.test(ref) && !/\.ya?ml$/i.test(ref);
 }
 /** The words `toolroll release` reads as its own (release-cli.ts), never as a branch: such a branch is named with --branch. */
-const RELEASE_WORDS = new Set(["status", "nightly", "carry", "revoke", "ask-every-commit", "unsandboxed-carry", "auto-approve", "publish-ok"]);
+const RELEASE_WORDS = new Set(["status", "nightly", "carry", "revoke", "ask-every-commit", "unsandboxed-carry", "auto-approve", "publish-ok", "approve"]);
 /** How a person names this branch to `toolroll release` again. */
 export function releaseBranchArg(branch) { return RELEASE_WORDS.has(branch) ? `--branch ${branch}` : branch; }

package/dist/result-actions.d.ts

@@ -1,5 +1,6 @@
 import type { Store } from "./store.js";
 import { type FeedbackImage } from "./result-review.js";
+import type { RevisionOrigin } from "./contracts/route-results.js";
 export type RevisionResult = {
     ok: true;
     id: string;
@@ -28,5 +29,8 @@ export declare function createResultRevision(store: Store, evidenceRoot: string,
     repos: readonly string[] | null;
     includeUnplaced?: boolean;
     allowMode?: boolean;
+    /** Who this revision comes from (results routing): each caller says it from its own trusted context, never from
+     * `allowMode` or the actor's name. Only `person` counts against the model that built the result. */
+    origin: RevisionOrigin;
 }, now: Date): RevisionResult;
 export {};

package/dist/result-actions.js

@@ -9,6 +9,7 @@ import { parseFeedbackImage, sameFeedbackImage, isRevisionFeedback, parseRevisio
 import { validateNote, hasForbiddenControls } from "./decision.js";
 import { TASK_TEXT_LIMITS, validateTaskText } from "./task-text.js";
 import { modeFilingCoverage } from "./scope.js";
+import { recordRevisionOrigin } from "./route-store.js";
 /** Re-prove image custody and current result at each write. No file paths supplied by callers. */
 export function feedbackImageProblem(store, root, runId, image) {
     if (image == null)
@@ -257,6 +258,8 @@ export function createResultRevision(store, evidenceRoot, input, now) {
                 // and collision handling. Set only this new row's display title,
                 // atomically with its seal; retries returned earlier, untouched.
                 store.raw().prepare("UPDATE task SET title = ? WHERE id = ?").run(title, result.id);
+                // Who it comes from, with its seal (route-store.ts: written once, on a revision only).
+                recordRevisionOrigin(store, result.id, input.origin);
             }
             // Planned afresh: the planner reads the copied terms and these notes, and a note asking for
             // more than the old plan allows becomes an amendment the person approves before anything

package/dist/result-acts.d.ts

@@ -11,7 +11,7 @@
  *   report and changes disagree,
  *   or the proof is refuted             → Request changes, then Accept (as allowed);
  *                                         never Accept as ink, even with no form here
- *   a Needs you form resolves it        → that form (Build again, Confirm it stopped)
+ *   a Needs you form resolves it        → that form (Build again, Check again)
  *   saved notes or a failing PR         → Revise / Draft a repair task
  *   a failed build                      → Retry (its note starts with what to change), then Run checks when they
  *                                         didn't run; never Accept: a failed build is not a result to accept
@@ -37,7 +37,7 @@ export declare function evidenceProblemOf(verdict: ProofVerdict | null, reasons:
  * when nothing refutes it (a person's acceptance settles it). The result page
  * shows it before Request changes, its one ink act. */
 export declare function cantAcceptYetOf(verdict: ProofVerdict | null, reasons: readonly string[], accepted: boolean): string | null;
-export type ResultActKind = "retry" | "accept" | "accept-anyway" | "next-check" | "checks-running" | "run-checks" | "request-changes" | "rebuild" | "confirm-stopped" | "revise" | "draft-repair";
+export type ResultActKind = "retry" | "accept" | "accept-anyway" | "next-check" | "checks-running" | "run-checks" | "request-changes" | "rebuild" | "recheck-stopped" | "revise" | "draft-repair";
 export type ResultActFacts = {
     /** An Accept this page can post (Accept and finish, or the person's acceptance alone); `ready`: every requirement met and checks passed. */
     accept: {
@@ -52,7 +52,7 @@ export type ResultActFacts = {
     /** The feedback form is on this page. */
     canRequest: boolean;
     /** A Needs you form that resolves it here. */
-    need: "rebuild" | "confirm-stopped" | null;
+    need: "rebuild" | "recheck-stopped" | null;
     /** Saved notes ready to become a revision, or a failing pull request's repair. */
     next: "revise" | "draft-repair" | null;
     /** A failed build: `retry` when the task can be retried from here; `acceptAnyway` when it delivered a result that