toolroll 0.9.92 → 0.9.93

package/dist/operate.js

@@ -33,6 +33,7 @@ import { personProof } from "./person-proof.js";
 import { RemoteMains } from "./remote-main.js";
 import { checkoutPlan, cleanCheckouts, discardCheckout, finishedCheckouts, slimKeptCheckouts, whyWords } from "./checkout-cleanup.js";
 import { closeOutCheckouts, closeOutRuns, stoppedWords } from "./run-closeout.js";
+import { proveFinishedRunsStopped, proveRunStopped } from "./stop-proof.js";
 import { MIN_DAYS, RETENTION_KINDS, countWords, dailyRetention, isRetentionKind, lastSweepAt, parsePeriod, periodLabel, periodWords, retentionPlan, sweepWords } from "./retention.js";
 import { checkPolicy, parseList, policyParts } from "./policy.js";
 import { billingOf, budgetHoldWords, budgetLabel, budgetStates, monthNamed, monthOf, spendItems, subagentNames, usd as spendUsd } from "./spend.js";
@@ -63,6 +64,8 @@ import { sendSubagentSummaries } from "./subagent-admin.js";
 import { runRequestedUndos, sendSubagentWeeklies } from "./subagent-week.js";
 import { refreshConnections } from "./mcp-connect.js";
 import { releaseCheckPurposeFor, releaseTermsFor } from "./release-carry.js";
+import { approveReleaseCard, journalMatchesPlane, releaseApprovalCard, releaseCardLines, releaseTaskOf, waitingJournals } from "./release-approval.js";
+import { journalFile } from "./release.js";
 import { refreshTrustedMains, settleReleaseChecks } from "./nightly-check.js";
 import { githubNightlyRepos, readGithubNightlies } from "./nightly-github.js";
 import { exec as releaseExec, githubReads } from "./release-adapters.js";
@@ -1215,6 +1218,9 @@ async function dispatch(command, positional, flags, context) {
     switch (command) {
         case "status":
             return statusCommand(positional, flags, context);
+        // `toolroll release approve` (cli.ts routes only this verb here; every other `release` form is release-cli.ts).
+        case "release":
+            return releaseApproveCommand(positional, flags, context);
         case "evals":
             return evalsCommand(positional, flags, context);
         case "ready":
@@ -3576,6 +3582,9 @@ async function reconcileCommand(flags, context) {
     // A witness reserved for a spawn that never made a process (a crash or a
     // thrown spawn) settles once its run's process groups are proven gone.
     store.settleUnspawnedWitnesses(clock());
+    // What no record proves stopped, Toolroll proves itself from this computer's processes (stop-proof.ts): nobody is
+    // asked to confirm a build stopped, so a release waiting on its check moves on by itself.
+    await proveFinishedRunsStopped(store, clock);
     store.settleQuiescentStops(clock());
     // An update whose updater ended while letting work finish must not leave new work paused.
     try {
@@ -10790,43 +10799,47 @@ async function resumeTaskCommand(positional, flags, context) {
     ]);
 }
 /**
- * `toolroll run settle <id> --why "<text>" --as <you> --token <t>`: an
- * approver's last resort for a finished run whose process witnesses can be
- * proven neither exited nor alive (a spawn interrupted before its pid was
- * written). Refuses while anything of the run is alive; the reason is kept
- * in the ledger against the approver's name. Signals nothing.
+ * `toolroll run settle <id> --as <you> --token <t>`: have Toolroll check again whether a finished run stopped. Nobody
+ * vouches that a build stopped (a person can't see whether a process exited): this runs Toolroll's own look at this
+ * computer's processes (stop-proof.ts), the one the worker makes on its own, and settles the run when none of them is
+ * the run's. A leftover proven the run's is stopped; anything else is left alone. `--why` is still accepted from older
+ * scripts and ignored.
  */
 async function runCommand(positional, flags, context) {
     const { store, write, json, clock } = context;
     const [action, id, ...extra] = positional;
     const command = "run settle";
-    const usage = "`toolroll run settle <run-id> --why \"<reason>\" --as <you> --token <t>`";
+    const usage = "`toolroll run settle <run-id>`";
     if (action !== "settle")
         return fail(write, json, "run", "usage", usage, EXIT.usage);
     const runId = Number(id ?? "");
-    const why = text(flags, "why")?.trim();
     if (id === undefined || extra.length > 0 || !/^[1-9]\d*$/.test(id) || !Number.isSafeInteger(runId))
         return fail(write, json, command, "usage", usage, EXIT.usage);
-    if (why === undefined || why === "" || why.length > 300 || /[\x00-\x1f\x7f]/.test(why))
-        return fail(write, json, command, "usage", "say why in one line with --why (at most 300 characters) — it is kept in the ledger", EXIT.usage);
     const run = store.getRun(runId);
     if (run === null)
         return fail(write, json, command, "unknown-run", `no run #${runId}`, EXIT.refused);
     const acting = await askCredentials(flags, context);
     if (acting === null)
-        return fail(write, json, command, "usage", "settling takes `--as <you> --token <t>` — it is an approver's act and is recorded against your name", EXIT.usage);
+        return fail(write, json, command, "usage", "checking a run again takes `--as <you> --token <t>` (or your sign-in from `toolroll up`)", EXIT.usage);
     const authenticated = authenticateApprover(store, acting.name, acting.token);
     const repo = store.refById(run.taskRef)?.repo ?? null;
     if (!authenticated.ok || !store.accountCanAccess(acting.name, repo))
         return fail(write, json, command, "not-an-approver", "that is not an approver for this run's project, or the token does not match", EXIT.refused);
-    const settled = store.settleRunWitnessesByApprover({ runId, by: acting.name, why }, clock());
-    if (!settled.ok)
-        return fail(write, json, command, settled.reason, settled.detail, EXIT.refused, { run: runId });
-    return succeed(write, json, command, { run: runId, witnesses: settled.witnesses, repeated: settled.repeated }, () => [
-        settled.repeated
-            ? `Run #${runId} has no unsettled process witness; nothing changed.`
-            : `Settled run #${runId}: ${settled.witnesses.length} process witness${settled.witnesses.length === 1 ? "" : "es"} recorded as ended, with your reason in the ledger.`,
-    ]);
+    if (run.outcome === null)
+        return fail(write, json, command, "still-running", `run #${runId} is still open`, EXIT.refused, { run: runId });
+    const proved = await proveRunStopped(store, runId, clock);
+    const stopped = store.stopQuiescenceFact(runId);
+    if (stopped === null) {
+        return succeed(write, json, command, { run: runId, outcome: proved.outcome === "skipped" ? "already-stopped" : "stopped", stoppedProcesses: proved.stopped ?? 0 }, () => [
+            proved.outcome === "skipped" ? `Run #${runId} had already stopped; nothing changed.`
+                : `Run #${runId} stopped: Toolroll checked this computer's processes and none of them is the run's${proved.stopped ? ` (it stopped ${proved.stopped} the run left running)` : ""}. The check is in the ledger.`,
+        ]);
+    }
+    const reason = proved.outcome === "blocked" ? "unproven" : stopped.kind === "alive" ? "alive" : "waiting";
+    const words = proved.outcome === "blocked" ? `Run #${proved.run} ${proved.words}.`
+        : stopped.kind === "alive" ? `Something of run #${stopped.run} is still running; Toolroll stops what is proven the run's on its own.`
+            : `Toolroll is still making sure run #${stopped.run} stopped. This clears on its own.`;
+    return fail(write, json, command, reason, words, EXIT.refused, { run: runId });
 }
 // ---- shared ---------------------------------------------------------------
 /**
@@ -13466,3 +13479,110 @@ function memoryWriteVerb(positional) {
     return MEMORY_WRITE_VERBS.has(positional[0] ?? "");
 }
 const MEMORY_WRITE_REFUSAL = "Project memory is changed by a person with their own sign-in, not the lead. The lead proposes decisions in chat for you to confirm.";
+/**
+ * `toolroll release approve [<branch>] [--repo <path>]` (docs/plans/trusted-release-reports.md, slice A, A8): approve
+ * the release waiting for a person from this terminal, without copying a task id or a digest. The release journals are
+ * discovery only, read strictly; the plane's sealed release identity decides which release this is. The card prints
+ * control-free; the person is asked through `askCredentials` (or its remembered login, under its existing conditions);
+ * the card is built again AFTER that prompt and anything changed refuses; then the shared card wrapper hands the
+ * snapshot's scope digest to the unchanged approve(). `--json` never prompts.
+ */
+async function releaseApproveCommand(positional, flags, context) {
+    const { store, write, json } = context;
+    const command = "release approve";
+    const usage = "`toolroll release approve [<branch>] [--repo <path>]` (with --json: --as <you> --token <password> --digest <card digest>)";
+    const branchFlag = text(flags, "branch");
+    if (positional[0] !== "approve" || positional.length > 2 || (branchFlag !== undefined && positional.length > 1))
+        return fail(write, json, command, "usage", usage, EXIT.usage);
+    const branch = branchFlag ?? positional[1];
+    if (branch !== undefined && (!/^[A-Za-z0-9._/-]{1,255}$/.test(branch) || branch.startsWith("-") || branch.includes("..")))
+        return fail(write, json, command, "usage", `${branch} is not a branch name this command takes.`, EXIT.usage);
+    const repoFlag = text(flags, "repo");
+    const repo = repoFlag === undefined ? null : resolve(repoFlag);
+    const stateDir = dirname(context.databaseFile);
+    const { journals, unreadable } = waitingJournals(stateDir, name => journalFile(stateDir, name));
+    // The exact branch asked for, never another that shares its file name (feature/foo and feature_foo).
+    const named = branch === undefined ? journals : journals.filter(one => one.branch === branch);
+    if (branch !== undefined && named.length === 0 && unreadable.includes(basename(journalFile(stateDir, branch)))) {
+        return fail(write, json, command, "unreadable", `${branch}'s release journal can't be read as one; nothing was approved. Run \`toolroll release ${branch}\` again.`, EXIT.refused);
+    }
+    const matches = [], refusals = [];
+    for (const one of named) {
+        if (releaseTaskOf(store, one.taskId) !== null && approvalOf(store.getScope(one.taskId)).approved)
+            continue;
+        const proved = journalMatchesPlane(store, one, repo);
+        if (proved.ok)
+            matches.push(one);
+        else
+            refusals.push(proved.why);
+    }
+    if (matches.length === 0) {
+        const why = refusals.length > 0 ? `${refusals[0]}; nothing was approved` : branch === undefined ? "No release is waiting for your approval" : `No release of ${branch} is waiting for your approval`;
+        return fail(write, json, command, refusals.length > 0 ? "mismatch" : "none", `${why}.`, EXIT.refused);
+    }
+    if (matches.length > 1) {
+        return fail(write, json, command, "ambiguous", `More than one release is waiting: ${matches.map(one => `${one.branch} (${one.version})`).join(", ")}. Name the branch: \`toolroll release approve <branch>\`.`, EXIT.refused, { releases: matches.map(one => ({ branch: one.branch, version: one.version, task: one.taskId })) });
+    }
+    const chosen = matches[0];
+    const built = releaseApprovalCard(store, chosen.taskId);
+    if (!built.ok)
+        return fail(write, json, command, "none", built.why, EXIT.refused);
+    const shown = built.card;
+    const cardData = { task: shown.taskId, version: shown.seal.identity.packageVersion, branch: shown.seal.identity.branch, candidate: shown.seal.identity.approvedSha, digest: shown.digest, ci: shown.ci?.state ?? null };
+    if (shown.approved !== null)
+        return fail(write, json, command, "approved", `Release ${cardData.version} is already approved by ${shown.approved.by}.`, EXIT.refused, { release: cardData });
+    if (shown.refusal !== null) {
+        if (!json)
+            for (const line of releaseCardLines(shown))
+                write(line);
+        return fail(write, json, command, "refused", `Can't approve now: ${shown.refusal}`, EXIT.refused, { release: cardData });
+    }
+    let name, token;
+    if (json) {
+        const given = credentialsFrom(flags, context);
+        if (given.name === undefined || given.token === undefined || given.name === "" || given.token === "")
+            return fail(write, json, command, "credentials", "Approving a release needs who is agreeing: --as <you> --token <password>. Nothing was approved.", EXIT.usage, { release: cardData });
+        if (text(flags, "digest") !== shown.digest)
+            return fail(write, json, command, "unconfirmed", "Name the card you read: --digest <card digest>. Nothing was approved.", EXIT.refused, { release: cardData });
+        name = given.name;
+        token = given.token;
+    }
+    else {
+        for (const line of releaseCardLines(shown))
+            write(line);
+        write("");
+        if (interactive()) {
+            if (!await confirm(`Approve release ${cardData.version}?`)) {
+                write("Nothing approved.");
+                return EXIT.refused;
+            }
+        }
+        else if (!flags.has("yes") || text(flags, "digest") !== shown.digest) {
+            write(`Nothing has been approved. Agree to exactly this card with: toolroll release approve ${chosen.branch} --yes --digest ${shown.digest} --as <you> --token <your password>`);
+            return EXIT.refused;
+        }
+        const acting = await askCredentials(flags, context);
+        if (acting === null)
+            return fail(write, json, command, "credentials", "Approving a release needs who is agreeing. Nothing was approved.", EXIT.usage);
+        name = acting.name;
+        token = acting.token;
+    }
+    // After the prompt: the card again, from the plane. A change refuses; it is never approved in place of what was shown.
+    const again = releaseApprovalCard(store, chosen.taskId);
+    if (!again.ok || again.card.digest !== shown.digest)
+        return fail(write, json, command, "changed", "This release changed while you were being asked; nothing was approved. Run the command again to read it.", EXIT.refused);
+    const now = context.clock();
+    const answer = approveReleaseCard(store, { taskId: chosen.taskId, cardDigest: shown.digest, approveNow: scopeDigest => approve(store, chosen.taskId, name, now, scopeDigest, token, mutationFrom(flags, now)) });
+    if (!answer.ok) {
+        if (answer.reason !== "approve")
+            return fail(write, json, command, answer.reason, `${answer.message} Nothing was approved.`, EXIT.refused);
+        const refused = answer.result;
+        if (refused.reason === "policy")
+            return fail(write, json, command, "policy", `${chosen.taskId}: ${refused.message}`, EXIT.refused);
+        return fail(write, json, command, refused.reason, describeApproveFailure(refused.reason, chosen.taskId), EXIT.refused);
+    }
+    return succeed(write, json, command, { release: cardData }, () => [
+        `Approved release ${cardData.version} (${cardData.candidate.slice(0, 7)}). The release check runs next; it deploys, merges and publishes once GitHub CI and the check pass.`,
+        ...(shown.stopped === null ? [] : [`The release isn't running: run \`toolroll release ${chosen.branch}\` to go on.`]),
+    ]);
+}

package/dist/project-delete.js

@@ -15,7 +15,7 @@
 import { existsSync, lstatSync, rmSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { teardownGit, refusal } from "./teardown-git.js";
-import { BUILT_IN, forgetProjectModels } from "./store.js";
+import { BUILT_IN, forgetProjectModels, V149_REPO_TABLES } from "./store.js";
 import { BRANCH_PREFIXES, isOwnBranch } from "./names.js";
 /** The tables whose history is the audit record itself: never touched. */
 const KEPT = new Set(["action_ledger", "ledger_seal", "ledger_checkpoint"]);
@@ -318,6 +318,10 @@ function deleteRows(store, repo, d, now) {
     // Settings, knowledge and the project itself.
     del("operating_mode_event", "mode IN (SELECT id FROM operating_mode WHERE repo = ?)", repo);
     del("decision_change", "decision IN (SELECT id FROM project_decision WHERE repo = ?)", repo);
+    // Its learning-loops rows (v149), by repo; a check's results, a note's tallies and a merge of its decisions go with
+    // the rows they hang off (the deleted runs, notes and decisions), below.
+    for (const table of V149_REPO_TABLES)
+        del(table, "repo = ?", repo);
     del("memory_sighting", "gap IN (SELECT id FROM memory_gap WHERE repo = ?) OR session IN (SELECT id FROM memory_session WHERE repo = ?)", repo, repo);
     for (const [table, column] of SETTINGS)
         del(table, `${column} = ?`, repo);

package/dist/project-knowledge.d.ts

@@ -22,18 +22,18 @@ export type KnowledgeView = ReturnType<typeof knowledgeView>;
 export declare function knowledgeVersion(store: Store, repo: string, actor: string, revision: number): Knowledge;
 /** Chat reads only an admitted project. Keep the full source in the project UI. */
 export declare function conversationKnowledge(store: Store, repo: string, actor: string, reference?: string, decision?: number): {
-    history?: never;
+    content?: never;
     revision: number;
     stale: boolean;
     notice: string;
     decision?: never;
     title?: never;
-    content?: never;
+    history?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
 } | {
-    history?: never;
+    content?: never;
     stale?: never;
     decision: {
         repo: string;
@@ -51,27 +51,27 @@ export declare function conversationKnowledge(store: Store, repo: string, actor:
     };
     notice: string;
     title?: never;
-    content?: never;
     revision?: never;
+    history?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
 } | {
-    history?: never;
     stale?: never;
     decision?: never;
     revision: number;
     title: string;
     content: string;
     notice: string;
+    history?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
 } | {
+    content?: never;
     stale?: never;
     decision?: never;
     title?: never;
-    content?: never;
     revision: number;
     history: {
         revision: number;

package/dist/push.d.ts

@@ -61,14 +61,21 @@ export declare function validatePushEndpoint(raw: string): {
     ok: false;
     problem: string;
 };
+/** A push's class: a stored class, or `release`, which is never stored: it is derived at send time from the plane's own
+ * state (release-approval.ts releasePushOf), never from a title, a task id or a link. */
+export type PushClass = NonNullable<Notification["pushClass"]> | "release";
 /** Fixed words, except for one validated machine-only suite/count line. */
-export declare const PUSH_WORDS: Record<NonNullable<Notification["pushClass"]>, {
+export declare const PUSH_WORDS: Record<PushClass, {
     title: string;
     body: string;
 }>;
 /** Static words and machine-minted numbers only — re-proved at send time. */
-export declare function safePushLink(pushClass: NonNullable<Notification["pushClass"]>, link: string | null): string;
-export declare function buildPushPayload(notification: Notification, waiting?: number | null): string;
+export declare function safePushLink(pushClass: PushClass, link: string | null): string;
+/** `release`: the class and link the plane derived for this row at send time (releasePushOf); absent or null, the
+ * row's stored class and link, revalidated. */
+export declare function buildPushPayload(notification: Notification, waiting?: number | null, release?: {
+    link: string;
+} | null): string;
 export type PushFetch = (url: string, init: Record<string, unknown>) => Promise<{
     status: number;
     headers: {

package/dist/push.js

@@ -20,6 +20,7 @@ import { closeSync, constants as fsConstants, fsyncSync, openSync, readFileSync,
 import { join } from "node:path";
 import { createCipheriv, createECDH, createPrivateKey, hkdfSync, randomBytes, createHash, sign as cryptoSign } from "node:crypto";
 import { isCheckProgressLine } from "./check-progress.js";
+import { RELEASE_PUSH_WORDS, releasePushOf, releaseReadyObsolete } from "./release-approval.js";
 export const VAPID_FILE = "vapid-keys.json";
 /** RFC 8291 §4: rs 4096 leaves room for the record's delimiter and tag. */
 const RECORD_SIZE = 4096;
@@ -193,7 +194,6 @@ export function validatePushEndpoint(raw) {
         return { ok: false, problem: "that host is not a known push service — extending the list is a code change, deliberately" };
     return { ok: true, url };
 }
-// ---- the payload ------------------------------------------------------------
 /** Fixed words, except for one validated machine-only suite/count line. */
 export const PUSH_WORDS = {
     decision: { title: "Toolroll", body: "a decision needs you" },
@@ -201,28 +201,37 @@ export const PUSH_WORDS = {
     merge: { title: "Toolroll", body: "a pull request needs a person" },
     attention: { title: "Toolroll", body: "the plane needs attention" },
     progress: { title: "Toolroll", body: "checks in progress" },
+    release: { title: "Toolroll", body: RELEASE_PUSH_WORDS },
 };
-const LINK_SHAPES = [/^\/next$/, /^\/review$/, /^\/system$/, /^\/routines$/, /^\/routines\/[0-9]{1,15}$/, /^\/d\/[0-9]{1,15}$/, /^\/r\/[0-9]{1,15}$/];
+// `/approve/<n>`: a release's opaque locator (a task ref number: no version, commit or branch), resolved by the console.
+const RELEASE_LINK = /^\/approve\/[0-9]{1,15}$/;
+const LINK_SHAPES = [/^\/next$/, /^\/review$/, /^\/system$/, /^\/routines$/, /^\/routines\/[0-9]{1,15}$/, /^\/d\/[0-9]{1,15}$/, /^\/r\/[0-9]{1,15}$/, RELEASE_LINK];
 const CLASS_FALLBACK = {
     decision: "/next",
     pick: "/next",
     merge: "/review",
     attention: "/next",
     progress: "/next",
+    release: "/next",
 };
 /** Static words and machine-minted numbers only — re-proved at send time. */
 export function safePushLink(pushClass, link) {
+    // The release locator rides only the derived `release` class: a stored link of that shape on any other row is not one.
+    if (link !== null && RELEASE_LINK.test(link))
+        return pushClass === "release" ? link : CLASS_FALLBACK[pushClass];
     if (link !== null && LINK_SHAPES.some(shape => shape.test(link)))
         return link;
     return CLASS_FALLBACK[pushClass];
 }
-export function buildPushPayload(notification, waiting = null) {
-    const pushClass = notification.pushClass;
+/** `release`: the class and link the plane derived for this row at send time (releasePushOf); absent or null, the
+ * row's stored class and link, revalidated. */
+export function buildPushPayload(notification, waiting = null, release = null) {
+    const pushClass = release !== null ? "release" : notification.pushClass;
     const words = PUSH_WORDS[pushClass];
     return JSON.stringify({
         title: words.title,
         body: pushClass === "progress" && isCheckProgressLine(notification.body) ? notification.body : words.body,
-        url: safePushLink(pushClass, notification.link),
+        url: safePushLink(pushClass, release !== null ? release.link : notification.link),
         // The opaque tag collapses a crash-duplicate on the lock screen.
         tag: pushClass === "progress" && notification.run !== null ? `so-run-${notification.run}` : `so-${notification.id}`,
         // The app-icon badge (Phase 2E, v2 S4): the server-computed
@@ -268,6 +277,13 @@ export async function pushPass(store, options) {
         if (fenced === null)
             continue; // resolved, retired, rotated, or lost — nothing to send
         const subscription = fenced.subscriptionRow;
+        // A release's "ready for your approval" that no longer stands (approved, superseded, put away) is resolved, never
+        // sent; one that stands is sent as `release`, its class and link derived from the plane's state now.
+        if (releaseReadyObsolete(store, fenced.notificationRow)) {
+            store.handle.prepare("UPDATE notification SET resolved_at = ? WHERE id = ? AND resolved_at IS NULL").run(clock().toISOString(), fenced.notificationRow.id);
+            continue;
+        }
+        const release = releasePushOf(store, fenced.notificationRow);
         const endpoint = validatePushEndpoint(subscription.endpoint);
         if (!endpoint.ok) {
             store.retirePushSubscription(subscription.id, "invalid-endpoint", clock());
@@ -280,7 +296,7 @@ export async function pushPass(store, options) {
             // The badge count rides every push: the same inbox classifier the
             // console's own sidebar badge reads, unscoped (a phone has no
             // project pane), computed at send time.
-            buildPushPayload(fenced.notificationRow, store.countInboxScoped(null, clock(), 100, null).count));
+            buildPushPayload(fenced.notificationRow, store.countInboxScoped(null, clock(), 100, null).count, release));
         }
         catch {
             // Off-curve or malformed subscriber material: the device, not us.

package/dist/release-adapters.js

@@ -31,6 +31,8 @@ import { randomBytes, randomUUID } from "node:crypto";
 import { deploymentGate } from "./deploy-gate.js";
 import { failedBeforeTests } from "./github-jobs.js";
 import { mainHistoryOf, nightlyBoundary } from "./nightly-github.js";
+import { noteReleaseReady, noteReleaseStopped, recordReleaseCi } from "./release-approval.js";
+import { recordVerifiedRelease } from "./release-card.js";
 export { failedBeforeTests } from "./github-jobs.js";
 import { extractCommit } from "./commit-extract.js";
 import { teardownGit, refusal as gitRefusal } from "./teardown-git.js";
@@ -529,7 +531,7 @@ export function releaseAdapters(options) {
             },
             async complete(taskId, receipt) {
                 const answer = await toolroll("task", "complete", taskId, "--digest", receipt);
-                return answer["ok"] === true ? { ok: true } : { ok: false, message: refused(answer) };
+                return answer["ok"] === true ? { ok: true } : { ok: false, message: refused(answer), ...(typeof answer["reason"] === "string" ? { reason: answer["reason"] } : {}) };
             },
             async busy() {
                 const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
@@ -971,6 +973,14 @@ nightlyReads) {
     } };
     return {
         ...(auto === undefined ? {} : { auto: autoReleaseAdapter(withStore, now, auto) }),
+        // One-tap release approval (trusted-release-reports.md, slice A): ids and the coordinator's own readings only; the
+        // plane decides from its own records whether anything is written.
+        ready: {
+            async asked(taskId) { withStore(store => { noteReleaseReady(store, { taskId, now: now() }); }); },
+            async ci(input) { withStore(store => { recordReleaseCi(store, { ...input, now: now() }); }); },
+            async stopped(input) { withStore(store => { noteReleaseStopped(store, { ...input, now: now() }); }); },
+            async verified(input) { withStore(store => { recordVerifiedRelease(store, { ...input, now: now() }); }); },
+        },
         // After a failed release check, and before a pass is taken: the plane's own classification (check-failure.ts).
         ...(auto === undefined ? {} : {
             async recheck(taskId) {

package/dist/release-approval.d.ts

@@ -0,0 +1,191 @@
+import { type PullRequestReader, type ReleaseCard, type ReleaseSeal, type TermLine } from "./release-card.js";
+import { type ApproveResult, type Scope } from "./scope.js";
+import { type Notification, type Store } from "./store.js";
+/** The ledger act holding the coordinator's latest reading of the pull request's CI on the exact candidate. */
+export declare const RELEASE_CI_SEEN_ACTION = "release CI observed";
+/** One check's newest attempt, as the coordinator's own gh read it. A re-run is a new check run id. */
+export type ReleaseCiRun = {
+    id: number | null;
+    name: string;
+    status: string;
+    conclusion: string | null;
+};
+export type ReleaseCiSnapshot = {
+    candidate: string;
+    at: string;
+    state: "passed" | "running" | "failed";
+    failed: string[];
+    runs: ReleaseCiRun[];
+};
+/**
+ * Record what the coordinator just read of the pull request's CI on `candidate` (its verdict and every check's newest
+ * attempt), when it differs from the last reading recorded: the sheet and the CLI show it, and the card digest binds
+ * it. The coordinator is Toolroll's own runtime reading GitHub through the plane's recorded repository.
+ */
+export declare function recordReleaseCi(store: Store, input: {
+    taskId: string;
+    candidate: string;
+    state: ReleaseCiSnapshot["state"];
+    failed: readonly string[];
+    runs: readonly {
+        id?: number | null;
+        name: string;
+        status: string;
+        conclusion: string | null;
+    }[];
+    now: Date;
+}): boolean;
+/** The coordinator's latest CI reading for this task on exactly `candidate`, or null (not read yet, or another commit). */
+export declare function releaseCiOf(store: Store, taskId: string, candidate: string): ReleaseCiSnapshot | null;
+/** What of a CI reading the card binds: its state and each check's attempt, whether it finished, and how. Queued and
+ * in progress read alike (neither is finished); the time it was read is not bound. */
+export declare function ciBinding(ci: ReleaseCiSnapshot | null): unknown;
+/** GitHub CI in one line, as the sheet and the CLI say it. */
+export declare function ciWords(ci: ReleaseCiSnapshot | null, candidate: string): string;
+export type ReleaseApprovalCard = {
+    taskId: string;
+    taskRef: number;
+    repo: string;
+    scope: Scope;
+    seal: ReleaseSeal;
+    /** The chat release card (release-card.ts): the change list and its own digest. */
+    card: ReleaseCard;
+    /** Every signed term, one line each (release-card.ts approvalTermsOf). */
+    terms: TermLine[];
+    ci: ReleaseCiSnapshot | null;
+    /** Why it can't be approved now, in words; null when it can (or already is). */
+    refusal: string | null;
+    approved: {
+        by: string;
+        at: string;
+    } | null;
+    /** The release coordinator stopped (its last step failed): approving needs `toolroll release` run again. */
+    stopped: {
+        step: string;
+        message: string;
+    } | null;
+    /** Binds everything above that a person is shown and can change under them. */
+    digest: string;
+};
+/** A release task from the plane's own state: a sealed form (terms or a release check's purpose) whose repository is the
+ * task's project and whose approved commit is the scope's candidate. Never from a title or a task id. */
+export declare function releaseTaskOf(store: Store, taskId: string): {
+    ref: {
+        id: number;
+        repo: string;
+    };
+    scope: Scope;
+    seal: ReleaseSeal;
+} | null;
+/** The authoritative card for a release task waiting for its person, or why there is none. Reads only. */
+export declare function releaseApprovalCard(store: Store, taskId: string, options?: {
+    read?: PullRequestReader;
+}): {
+    ok: true;
+    card: ReleaseApprovalCard;
+} | {
+    ok: false;
+    why: string;
+};
+/** What approving does, in the sheet's and the CLI's words: the consequence, the check's access, and whether later
+ * commits carry. */
+export declare function releaseConsequence(card: ReleaseApprovalCard): string[];
+export type ReleaseCardRefusal = {
+    ok: false;
+    reason: "not-release" | "changed" | "approved" | "refused";
+    message: string;
+} | {
+    ok: false;
+    reason: "approve";
+    result: Exclude<ApproveResult, {
+        ok: true;
+    }>;
+};
+/**
+ * The one card-approval wrapper (Codex round 2, finding 2): rebuild the authoritative card and compare the digest the
+ * person saw; then, in one transaction, re-read the store's parts (the scope digest, the CI reading, the refusal state)
+ * and refuse on any change; then hand THAT snapshot's scope digest to `approveNow`, the caller's unchanged
+ * transactional `approve()`, which proves the person and seals. Nothing here proves anyone.
+ */
+export declare function approveReleaseCard(store: Store, input: {
+    taskId: string;
+    cardDigest: string;
+    read?: PullRequestReader;
+    approveNow: (scopeDigest: string) => ApproveResult;
+}): {
+    ok: true;
+    scope: Scope;
+} | ReleaseCardRefusal;
+export declare const RELEASE_READY_KIND = "release-ready";
+export declare const RELEASE_STOPPED_KIND = "release-stopped";
+/** The one push phrase for a release waiting on its person (push.ts PUSH_WORDS.release). */
+export declare const RELEASE_PUSH_WORDS = "A release is ready for your approval";
+/** The sheet's own address for a task (the in-app link; a push carries the opaque `/approve/<task ref>` instead). */
+export declare const releaseSheetHref: (taskId: string) => string;
+/**
+ * The coordinator asked a person (on entering the approval step, a fresh filing or a resumed one): one notification per
+ * task and stable scope digest, so a crash between filing and asking is healed by the next run and a repeat says nothing
+ * new. Every older `release-ready` row of the project (another task or digest) is resolved first. Nothing when the task
+ * isn't a release waiting for a person.
+ */
+export declare function noteReleaseReady(store: Store, input: {
+    taskId: string;
+    now: Date;
+}): boolean;
+/** Resolve a task's `release-ready` rows (it was approved, or the release stopped): a push not sent yet never is. */
+export declare function retireReleaseReady(store: Store, taskRef: number, now: Date): number;
+/**
+ * The push class `release` and its link, derived at send time from the plane's own state, never from a title, a task id,
+ * the stored link or the stored class: the row is a `release-ready` row for exactly its task ref and a scope digest, and
+ * that task is a release scope (terms or a release check's purpose, its candidate the approved commit), not put away,
+ * not approved, at that same digest. Null otherwise.
+ */
+export declare function releasePushOf(store: Store, notification: Pick<Notification, "kind" | "dedupeKey" | "taskRef" | "resolvedAt">): {
+    link: string;
+} | null;
+/** A `release-ready` row that no longer stands (the push pass resolves it instead of sending it). */
+export declare function releaseReadyObsolete(store: Store, notification: Pick<Notification, "kind" | "dedupeKey" | "taskRef" | "resolvedAt">): boolean;
+/**
+ * A person's release stopped (CI failed, the check failed, the deploy, the merge, the tag or publication failed, or it
+ * stopped waiting): one attention notification per task, step and reason, with the stop's words in the app (the push
+ * says only the fixed attention phrase). Its `release-ready` row is resolved, except while it only stopped waiting
+ * for the approval (the sheet still approves it then).
+ */
+export declare function noteReleaseStopped(store: Store, input: {
+    taskId: string;
+    step: string;
+    reason: string;
+    message: string;
+    now: Date;
+}): boolean;
+/** The card as the CLI prints it, every line control-free (src/terminal-text.ts). */
+export declare function releaseCardLines(card: ReleaseApprovalCard): string[];
+/** One release journal as discovery reads it: strictly, every field it relies on in its exact shape. */
+export type WaitingJournal = {
+    file: string;
+    branch: string;
+    checkout: string;
+    taskId: string;
+    scopeDigest: string;
+    candidate: string;
+    version: string;
+    pr: number;
+};
+/** A journal's own fields, strictly; null when any is missing or not its exact shape. */
+export declare function readWaitingJournal(file: string, raw: unknown, expectedFile: (branch: string) => string): WaitingJournal | null;
+/**
+ * Whether a journal (discovery only) names exactly the release the plane sealed: the task is a release scope whose
+ * sealed identity has this exact branch, version, pull request and candidate at this scope digest, and the journal's
+ * checkout, the task's project and the sealed repository are one real folder (`repo` too, when given). Why not, in words.
+ */
+export declare function journalMatchesPlane(store: Store, journal: WaitingJournal, repo: string | null): {
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+};
+/** Every release journal in the state folder, read strictly; unreadable ones are counted, never guessed at. */
+export declare function waitingJournals(stateDir: string, expectedFile: (branch: string) => string): {
+    journals: WaitingJournal[];
+    unreadable: string[];
+};