toolroll 0.9.71 → 0.9.73

package/dist/release-authority.js

@@ -0,0 +1,135 @@
+/**
+ * The release authority record, read (docs/plans/release-once.md, schema v135): one generation of a release a person
+ * approved, its carried commits and its deploy and merge operations. Kept apart from store.ts so the one live-release
+ * reader (scope.ts liveReleaseOf) can read it without a module cycle; every write is in store.ts.
+ */
+import { readReleasePolicy } from "./contracts/release-terms.js";
+export const LIVE_RELEASE_STATES = ["open", "deploying", "merge-reserved"];
+function readReleaseAuthority(row) {
+    const text = (key) => row[key] == null ? null : String(row[key]);
+    let policy = null;
+    try {
+        const parsed = readReleasePolicyStrict(String(row["policy_json"]));
+        policy = parsed;
+    }
+    catch {
+        policy = null;
+    }
+    const state = String(row["state"]);
+    return {
+        id: Number(row["id"]), repo: String(row["repo"]), generation: Number(row["generation"]), previous: row["previous"] == null ? null : Number(row["previous"]),
+        version: String(row["version"]), pr: Number(row["pr"]), branch: String(row["branch"]), base: String(row["base"]),
+        anchorTask: String(row["anchor_task"]), anchorDigest: String(row["anchor_digest"]), approvedSha: String(row["approved_sha"]), approvedTree: String(row["approved_tree"]),
+        artifactDigest: text("artifact_digest"), tipSha: String(row["tip_sha"]), tipTask: String(row["tip_task"]), policyJson: String(row["policy_json"]), policy,
+        policyDigest: String(row["policy_digest"]), verifyCommand: Number(row["verify_command"]), verifyDigest: String(row["verify_digest"]), accessDigest: String(row["access_digest"]),
+        state: ["open", "deploying", "merge-reserved", "merged", "revoked", "expired", "superseded"].includes(state) ? state : "revoked",
+        rev: Number(row["rev"]), leaseOwner: text("lease_owner"), leaseEpoch: Number(row["lease_epoch"]), leaseExpires: text("lease_expires"),
+        expiresAt: String(row["expires_at"]), createdAt: String(row["created_at"]), endedAt: text("ended_at"), endedBy: text("ended_by"),
+    };
+}
+/** A sealed policy read strictly; null when this runtime doesn't know it (and so refuses to carry under it). */
+function readReleasePolicyStrict(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    const read = readReleasePolicy(parsed);
+    return read.ok && JSON.stringify(read.value) === json ? read.value : null;
+}
+function readReleaseCarry(row) {
+    let commits = [];
+    try {
+        const parsed = JSON.parse(String(row["commits_json"]));
+        if (Array.isArray(parsed))
+            commits = parsed;
+    }
+    catch {
+        commits = [];
+    }
+    return {
+        id: Number(row["id"]), authority: Number(row["authority"]), taskId: String(row["task_id"]), scopeDigest: String(row["scope_digest"]), requestId: String(row["request_id"]),
+        fromSha: String(row["from_sha"]), toSha: String(row["to_sha"]), toTree: String(row["to_tree"]), artifactDigest: String(row["artifact_digest"]), commits,
+        changedLines: Number(row["changed_lines"]), files: Number(row["files"]), churn: Number(row["churn"]), runtime: String(row["runtime"]), provedAt: String(row["proved_at"]),
+    };
+}
+function readReleaseOperation(row) {
+    const text = (key) => row[key] == null ? null : String(row[key]);
+    return {
+        id: String(row["id"]), authority: Number(row["authority"]), kind: row["kind"] === "merge" ? "merge" : "deploy", taskId: String(row["task_id"]), candidate: String(row["candidate"]),
+        epoch: Number(row["epoch"]), state: String(row["state"]), externalRef: text("external_ref"), reservedAt: String(row["reserved_at"]),
+        finishedAt: text("finished_at"), detail: text("detail"), direct: Number(row["direct"] ?? 0) === 1,
+        issuer: row["issuer_pid"] == null || row["issued_at"] == null ? null : { pid: Number(row["issuer_pid"]), started: text("issuer_started"), at: String(row["issued_at"]) },
+        stage: text("stage"),
+    };
+}
+export function releaseAuthority(store, id) {
+    const row = store.handle.prepare("SELECT * FROM release_authority WHERE id = ?").get(id);
+    return row === undefined ? null : readReleaseAuthority(row);
+}
+/** The newest generation of a release, whatever its state. */
+export function newestReleaseGeneration(store, repo, version, pr) {
+    const row = store.handle.prepare("SELECT * FROM release_authority WHERE repo = ? AND version = ? AND pr = ? ORDER BY generation DESC LIMIT 1").get(repo, version, pr);
+    return row === undefined ? null : readReleaseAuthority(row);
+}
+/** The release authority a task belongs to — as an anchor (any generation) or as a carried commit — or null. */
+export function releaseAuthorityOfTask(store, taskId) {
+    const carryRow = store.handle.prepare("SELECT * FROM release_carry WHERE task_id = ?").get(taskId);
+    if (carryRow !== undefined) {
+        const carry = readReleaseCarry(carryRow);
+        const authority = releaseAuthority(store, carry.authority);
+        return authority === null ? null : { authority, carry };
+    }
+    const row = store.handle.prepare("SELECT * FROM release_authority WHERE anchor_task = ? ORDER BY id DESC LIMIT 1").get(taskId);
+    return row === undefined ? null : { authority: readReleaseAuthority(row), carry: null };
+}
+/** Whether a task belongs to any release authority (anchor or carried), from the records alone. */
+/** "Carry release approvals when checks aren't sandboxed": a project setting, newest choice wins (a ledger row each);
+ * off by default. Turning it on is a person's own proven act (release-cli.ts); turning it off is anyone's. */
+export const UNSANDBOXED_CARRY_ACTION = "release unsandboxed carrying changed";
+export function carriesUnsandboxed(store, repo) {
+    const row = store.handle.prepare("SELECT outcome FROM action_ledger WHERE repo = ? AND action = ? ORDER BY id DESC LIMIT 1").get(repo, UNSANDBOXED_CARRY_ACTION);
+    return row !== undefined && row["outcome"] === "on";
+}
+/** How far a check reaches, narrowest first. */
+export const CHECK_ACCESS_WIDTH = Object.freeze({ sandboxed: 0, "sign-ins": 1, unsandboxed: 2 });
+export function belongsToRelease(store, taskId) {
+    return store.handle.prepare("SELECT 1 AS hit FROM release_authority WHERE anchor_task = ? UNION ALL SELECT 1 FROM release_carry WHERE task_id = ? LIMIT 1").get(taskId, taskId) !== undefined;
+}
+export function releaseCarries(store, authority) {
+    return store.handle.prepare("SELECT * FROM release_carry WHERE authority = ? ORDER BY id").all(authority).map(readReleaseCarry);
+}
+export function releaseCarryTo(store, authority, toSha) {
+    const row = store.handle.prepare("SELECT * FROM release_carry WHERE authority = ? AND to_sha = ?").get(authority, toSha);
+    return row === undefined ? null : readReleaseCarry(row);
+}
+export function releaseOperations(store, authority) {
+    return store.handle.prepare("SELECT * FROM release_operation WHERE authority = ? ORDER BY reserved_at, id").all(authority).map(readReleaseOperation);
+}
+export function releaseOperation(store, id) {
+    const row = store.handle.prepare("SELECT * FROM release_operation WHERE id = ?").get(id);
+    return row === undefined ? null : readReleaseOperation(row);
+}
+/** Operations nobody has settled yet: until each is reconciled, nothing new starts. */
+export function outstandingReleaseOperations(store, authority) {
+    return releaseOperations(store, authority).filter(one => one.state === "reserved" || one.state === "running" || one.state === "unknown");
+}
+/**
+ * Why a person's seal of these release terms can't open a new generation now, in words, or null. A live generation is
+ * superseded by the new one — but never while one of its operations is unsettled, and never once its merge started.
+ */
+export function releaseSealProblem(store, terms) {
+    const live = newestReleaseGeneration(store, terms.repo, terms.packageVersion, terms.pr);
+    if (live === null)
+        return null;
+    if (live.state === "merged")
+        return `Release ${terms.packageVersion} from pull request #${terms.pr} was already merged.`;
+    if (live.state === "merge-reserved")
+        return `The merge of release ${terms.packageVersion} already started; it can't be approved again.`;
+    if (LIVE_RELEASE_STATES.includes(live.state) && outstandingReleaseOperations(store, live.id).length > 0) {
+        return `Release ${terms.packageVersion} has a deploy that hasn't been settled yet. Run \`toolroll release ${live.branch}\` to finish or recover it first.`;
+    }
+    return null;
+}

package/dist/release-card.d.ts

@@ -0,0 +1,76 @@
+import { 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. */
+export type TermLine = {
+    key: string;
+    label: string;
+    value: string;
+};
+/** The scope's own terms the card names, in order. A contract test holds `goal`, `outOfScope`, `touches` and
+ * `acceptance` (contracts/scope.ts) and the scope's other signed fields to this list; the agent profile and the phase
+ * route follow as one line per signed setting (`profile.…`, `route.…`). */
+export declare const SCOPE_TERM_LABELS: {
+    readonly title: "Title";
+    readonly project: "Project";
+    readonly filedBy: "Filed by";
+    readonly goal: "Goal";
+    readonly outOfScope: "Not in scope";
+    readonly touches: "Paths it may touch";
+    readonly acceptance: "Done when";
+    readonly qualityMode: "Evidence standard";
+    readonly agents: "Agents and model";
+    readonly permission: "Agents may";
+    readonly checks: "Checks";
+    readonly checkAccess: "Check access";
+    readonly budgetMicrousd: "Budget per attempt";
+    readonly candidate: "Candidate commit";
+};
+/** 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>>;
+/** 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. */
+export declare function approvalTermsOf(store: Store, scope: Scope, words: {
+    profile: (profile: Scope["profile"]) => string | null;
+}): TermLine[];
+export declare const termsText: (lines: readonly TermLine[]) => string;
+export type ChangeList = {
+    /** The merge commit of the last verified release, or null when none is recorded. */
+    baseline: string | null;
+    /** Newest first; null when it couldn't be read. */
+    commits: {
+        sha: string;
+        subject: string;
+    }[] | null;
+    source: "recorded" | "pull-request" | "unread";
+    digest: string;
+};
+/** The plane's own record of the last verified release of `repo`: the merge commit GitHub answered with, recorded once
+ * the release verified the merged tree (the newest merged authority whose merge operation succeeded). Never a tag. */
+export declare function releaseBaseline(store: Store, repo: string): string | null;
+/** The commits after `from` up to `to`, as verified Git objects only, from the project's recorded Git directory: the
+ * release coordinator's checkout config allowlist first, then commit-extract's verified range (every commit hashed here,
+ * a shallow boundary, grafts or replacement refs refused, and the range proved to stop only in the last release's own
+ * history). Null when they can't be read, so a card never shows a shortened list. */
+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;
+export type ReleaseCard = {
+    /** Binds the scope digest, the plan form's digest, the baseline and the change list. */
+    digest: string;
+    short: string;
+    full: string;
+    fileName: string;
+    changes: ChangeList;
+};
+/** The card digest: everything the person is shown that can change under them. */
+export declare function cardDigestOf(scopeDigest: string, formDigest: string, changes: Pick<ChangeList, "baseline" | "digest">): string;
+/** 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;

package/dist/release-card.js

@@ -0,0 +1,252 @@
+/**
+ * The release card (docs/plans/chat-management.md §0a.5): how a deploy gate is approved from chat until the
+ * authenticator ships. Alex's decision (2026-10-25): chat keeps approving releases by tap, so the tap is made to mean
+ * exactly what was shown.
+ *
+ * - `approvalTermsOf`: every signed term of the scope (its agent profile and phase route setting by setting) and every
+ *   field of its release terms, one line each, "none" for an empty one and "any file in the project" for unnamed paths
+ *   (a contract test changes each input of the approval digest in turn and holds the text to change with it).
+ * - `releaseChangeList`: what changed since the last verified release, from the plane's own record of it (the merge
+ *   commit of the newest merged release whose merge operation succeeded), read as verified Git objects from the
+ *   project's recorded Git directory: never a tag or a ref, so moving one changes nothing, and history rewritten around
+ *   the objects (a shallow boundary, grafts, replacement refs) refuses the list rather than shortening it.
+ *   With no earlier release on record, the pull request's own commits from GitHub, for the recorded owner/name.
+ * - `releaseCardOf`: the short card, the full terms (sent as a file where the chat app limits a message), and
+ *   `cardDigest`, which binds the scope digest, the plan form's digest, the baseline and the change list: Continue and
+ *   Approve carry it, and anything different at the tap refuses.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstatSync, realpathSync } from "node:fs";
+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 { routeFromJson } from "./phase-routing.js";
+import { projectName } from "./project.js";
+import { RELEASE_PATH, releaseConfigProblem, releaseGitEnv, releaseRemote, releaseTools } from "./release-git.js";
+const NONE = "none";
+/** A budget in dollars from integer micro-dollars, in integer arithmetic: cents when it is whole cents, else every digit. */
+const money = (micro) => {
+    const exact = BigInt(micro), whole = exact / 1000000n, rest = (exact < 0n ? -exact : exact) % 1000000n;
+    const fraction = rest.toString().padStart(6, "0");
+    return `${exact < 0n && whole === 0n ? "-" : ""}$${whole}.${rest % 10000n === 0n ? fraction.slice(0, 2) : fraction}`;
+};
+/** Words the card itself says in place of a value: a signed string spelled the same is quoted, never mistaken for one. */
+const RESERVED = new Set([NONE, "yes", "no", "null", "empty", "not set", "any file in the project", "the whole project", "unreadable"]);
+/** Text that reads the same plain as quoted: ASCII letters, digits and ordinary punctuation only (no lookalike letters
+ * from other scripts, no direction marks), never a comma, semicolon, parenthesis, quote, backslash, line break or
+ * control character, nor a trailing space. */
+const PLAIN = /^[A-Za-z0-9~/.#$@][A-Za-z0-9 ._/@~+#=!?&%$*:<>|^-]*$/;
+/** JSON-quoted with everything outside printable ASCII \u-escaped (JSON.stringify leaves non-ASCII as it is). */
+const quoted = (value) => JSON.stringify(value).replace(/[^\x20-\x7e]/g, one => `\\u${one.charCodeAt(0).toString(16).padStart(4, "0")}`);
+/** One signed string, unambiguous: as it is when plain, else quoted; an empty, number-like or colon-bearing string, or
+ * one of the card's own words, is quoted too. */
+const text = (value) => PLAIN.test(value) && !value.endsWith(" ") && !RESERVED.has(value.toLowerCase()) && !/^-?\d+(\.\d+)?$/.test(value) ? value : quoted(value);
+/** One signed value as the card says it, every shape distinct: "none" for null, "not set" for absent, "empty" for an
+ * empty list, `""` for an empty string; a list's entries each said the same way, so a comma never joins two into one. */
+const said = (value) => {
+    if (value === undefined)
+        return "not set";
+    if (value === null)
+        return NONE;
+    if (typeof value === "boolean")
+        return value ? "yes" : "no";
+    if (typeof value === "number")
+        return String(value);
+    if (Array.isArray(value))
+        return value.length === 0 ? "empty" : value.map(one => typeof one === "string" ? text(one) : one === null ? "null" : said(one)).join(", ");
+    return text(String(value));
+};
+/** The scope's own terms the card names, in order. A contract test holds `goal`, `outOfScope`, `touches` and
+ * `acceptance` (contracts/scope.ts) and the scope's other signed fields to this list; the agent profile and the phase
+ * route follow as one line per signed setting (`profile.…`, `route.…`). */
+export const SCOPE_TERM_LABELS = {
+    title: "Title", project: "Project", filedBy: "Filed by", goal: "Goal", outOfScope: "Not in scope", touches: "Paths it may touch",
+    acceptance: "Done when", qualityMode: "Evidence standard", agents: "Agents and model", permission: "Agents may", checks: "Checks", checkAccess: "Check access",
+    budgetMicrousd: "Budget per attempt", candidate: "Candidate commit",
+};
+/** Every leaf of a signed value, at its path (`a.b`, `legs.0.model`), as the card says it. */
+function leavesOf(value, path) {
+    if (Array.isArray(value))
+        return value.every(one => one === null || typeof one !== "object") ? [{ path, value: said(value) }]
+            : value.flatMap((one, index) => leavesOf(one, `${path}.${index}`));
+    if (value !== null && typeof value === "object") {
+        const keys = Object.keys(value).sort();
+        return keys.length === 0 ? [{ path, value: "no settings" }] : keys.flatMap(key => leavesOf(value[key], `${path}.${key}`));
+    }
+    return [{ path, value: said(value) }];
+}
+/** 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 const RELEASE_TERM_LABELS = {
+    version: "Release terms version", repo: "Repository", packageVersion: "Package version", branch: "Branch", pr: "Pull request", base: "Base",
+    approvedSha: "Approved commit", approvedTree: "Approved tree",
+    "policy.version": "Carry policy version", "policy.rules": "Carry rules", "policy.carry": "Carry later commits",
+    "policy.protectProject": "Protected: the whole project", "policy.protectedPaths": "Protected paths",
+    "policy.limits.lines": "Carry limit: lines", "policy.limits.files": "Carry limit: files", "policy.limits.churn": "Carry limit: churn",
+    "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",
+};
+/** The leaf paths of a zod object schema (nested objects joined with dots). */
+export function schemaLeaves(schema, prefix = "") {
+    const shape = schema.shape;
+    if (shape === undefined || shape === null)
+        return [prefix];
+    return Object.entries(shape).flatMap(([key, child]) => schemaLeaves(child, prefix === "" ? key : `${prefix}.${key}`));
+}
+const valueAt = (terms, path) => path.split(".").reduce((at, key) => at !== null && typeof at === "object" ? at[key] : undefined, terms);
+/** Every signed term of `scope`, its release terms included, one line each. Reads only. */
+export function approvalTermsOf(store, scope, words) {
+    const ref = store.lookupRef(scope.taskId);
+    const repo = ref?.repo ?? null;
+    const filer = store.taskFiler(scope.taskId);
+    const profile = scope.profile ?? null;
+    const scopeValues = {
+        title: said(store.getTask(scope.taskId)?.title),
+        project: repo === null ? NONE : `${text(projectName(repo))} (${text(repo)})`,
+        filedBy: filer === null ? NONE : filer.name === null ? filer.kind : `${text(filer.name)}${filer.kind === "person" ? "" : ` (${filer.kind})`}`,
+        goal: said(scope.goal),
+        // null (nothing excluded) and an empty exclusion are signed apart, and read apart.
+        outOfScope: said(scope.outOfScope),
+        // No paths named is no limit: the work may touch any file in the project.
+        touches: scope.touches.length === 0 ? "any file in the project" : said(scope.touches),
+        // Each criterion's fields quoted, always: a colon or a parenthesis in one never moves the boundary to the next.
+        acceptance: scope.acceptance.length === 0 ? NONE : scope.acceptance.map(one => `${quoted(one.id)}: ${quoted(one.statement)} (evidence: ${said(one.evidence)})`).join("; "),
+        qualityMode: scope.qualityMode === "strict" ? "strict" : "standard",
+        agents: profile === null ? NONE : `${profile.provider} · ${text(profile.model)}`,
+        permission: said(words.profile(profile)),
+        checks: CHECK_LEVEL_WORDS[effectiveCheckLevel(store, repo, scope.taskId).level],
+        checkAccess: checkAccessWords(profile?.checkAccess ?? "sandboxed"),
+        budgetMicrousd: scope.budgetMicrousd === null ? NONE : money(scope.budgetMicrousd),
+        candidate: said(scope.candidate),
+    };
+    const lines = Object.keys(SCOPE_TERM_LABELS).map(key => ({ key, label: SCOPE_TERM_LABELS[key], value: scopeValues[key] }));
+    // Every signed setting of the agent profile (what it may read, reach and write, its limits) and the phase route the
+    // digest binds, one line each: the summary lines above never stand in for them.
+    if (profile !== null)
+        for (const leaf of leavesOf(profile, "profile"))
+            lines.push({ key: leaf.path, label: `Agent setting ${leaf.path.slice("profile.".length)}`, value: leaf.value });
+    if (scope.proposedRouteJson != null) {
+        const route = routeFromJson(scope.proposedRouteJson);
+        // Unreadable (it then never seals): its stored text, exactly, so two different ones never read alike.
+        if (route === null)
+            lines.push({ key: "route", label: "Phase route (unreadable)", value: quoted(scope.proposedRouteJson) });
+        else
+            for (const leaf of leavesOf(route, "route"))
+                lines.push({ key: leaf.path, label: `Phase route ${leaf.path.slice("route.".length)}`, value: leaf.value });
+    }
+    const terms = scope.releaseTerms ?? null;
+    for (const path of schemaLeaves(releaseTermsSchema)) {
+        const label = RELEASE_TERM_LABELS[path] ?? path;
+        const value = terms === null ? NONE : path === "pr" ? `#${terms.pr}`
+            // The whole project is protected, and the signed list is said too (it is part of what was signed).
+            : path === "policy.protectedPaths" && terms.policy.protectProject ? `the whole project (listed: ${said(terms.policy.protectedPaths)})`
+                // Absent (sealed before the setting existed) is off, said apart from a signed "no".
+                : path === "policy.unsandboxedCarry" && terms.policy.unsandboxedCarry === undefined ? "no (not set when sealed)" : said(valueAt(terms, path));
+        lines.push({ key: `release.${path}`, label, value });
+    }
+    return lines;
+}
+export const termsText = (lines) => lines.map(line => `${line.label}: ${line.value}`).join("\n");
+const SHA = /^[0-9a-f]{40}$/;
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/** The plane's own record of the last verified release of `repo`: the merge commit GitHub answered with, recorded once
+ * the release verified the merged tree (the newest merged authority whose merge operation succeeded). Never a tag. */
+export function releaseBaseline(store, repo) {
+    const row = store.handle.prepare(`SELECT o.external_ref FROM release_authority a JOIN release_operation o ON o.authority = a.id
+    WHERE a.repo = ? AND a.state = 'merged' AND o.kind = 'merge' AND o.state = 'succeeded' AND o.external_ref IS NOT NULL ORDER BY a.id DESC, o.finished_at DESC LIMIT 1`).get(repo);
+    const ref = row === undefined ? null : String(row["external_ref"]);
+    return ref !== null && SHA.test(ref) ? ref : null;
+}
+/** The commits after `from` up to `to`, as verified Git objects only, from the project's recorded Git directory: the
+ * release coordinator's checkout config allowlist first, then commit-extract's verified range (every commit hashed here,
+ * a shallow boundary, grafts or replacement refs refused, and the range proved to stop only in the last release's own
+ * history). Null when they can't be read, so a card never shows a shortened list. */
+export function commitsBetween(repo, from, to) {
+    if (!SHA.test(from) || !SHA.test(to))
+        return null;
+    let gitDir;
+    try {
+        const named = join(realpathSync(repo), ".git");
+        if (!lstatSync(named).isDirectory())
+            return null;
+        gitDir = realpathSync(named);
+    }
+    catch {
+        return null;
+    }
+    const tools = releaseTools();
+    const env = { ...releaseGitEnv(), PATH: RELEASE_PATH };
+    const listing = spawnSync(tools.git, [`--git-dir=${gitDir}`, "--no-optional-locks", "config", "--list", "--no-includes", "--show-scope", "-z"], { cwd: "/", env, encoding: "utf8", timeout: 15_000 });
+    if (listing.status !== 0 || releaseConfigProblem(listing.stdout) !== null)
+        return null;
+    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() }));
+}
+/** 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)
+        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();
+}
+/** What changed since the last verified release, for a release's terms, from Toolroll's records only. */
+export function releaseChangeList(store, terms) {
+    const baseline = releaseBaseline(store, terms.repo);
+    let commits;
+    let source;
+    if (baseline !== null) {
+        commits = commitsBetween(terms.repo, baseline, terms.approvedSha);
+        source = commits === null ? "unread" : "recorded";
+    }
+    else {
+        const remote = store.projectRemote(terms.repo);
+        const parsed = remote === null ? null : releaseRemote(remote);
+        commits = parsed === null ? null : pullRequestCommits(parsed.slug, terms.pr);
+        source = commits === null ? "unread" : "pull-request";
+    }
+    return { baseline, commits, source, digest: sha256(`release-changes:${JSON.stringify({ baseline, source, commits })}`) };
+}
+/** The card digest: everything the person is shown that can change under them. */
+export function cardDigestOf(scopeDigest, formDigest, changes) {
+    return sha256(`release-card:v1:${JSON.stringify([scopeDigest, formDigest, changes.baseline, changes.digest])}`);
+}
+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 ? `The pull request's commits couldn't be read; 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) {
+    const terms = scope.releaseTerms ?? null;
+    const lines = approvalTermsOf(store, scope, words);
+    const value = (key) => lines.find(line => line.key === key)?.value ?? NONE;
+    const changes = terms === null
+        ? { baseline: null, commits: null, source: "unread", digest: sha256("release-changes:none") }
+        : releaseChangeList(store, terms);
+    const version = terms?.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}`,
+        // 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."] : []),
+        "",
+        ...changeWords(changes, terms, 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");
+    return { digest: cardDigestOf(scope.digest, formDigest, changes), short, full, fileName, changes };
+}