toolroll 0.9.92 → 0.9.94

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,38 +194,70 @@ 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" },
     pick: { title: "Toolroll", body: "agents finished — pick a winner" },
     merge: { title: "Toolroll", body: "a pull request needs a person" },
-    attention: { title: "Toolroll", body: "the plane needs attention" },
+    attention: { title: "Toolroll", body: "Toolroll needs your 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}$/;
+/** The relative links a push may carry (docs/plans/plain-toolroll.md P1.4): every shape an older worker took, kept for
+ * good (/next and /review now redirect to Home and Tasks' Ready view; the rest keep their pages), then Home, Tasks'
+ * Ready and Board views, and a task by its stored number (/n/<n>, resolved under the viewer's own access). */
+export const LINK_SHAPES = [/^\/next$/, /^\/review$/, /^\/system$/, /^\/routines$/, /^\/routines\/[0-9]{1,15}$/, /^\/d\/[0-9]{1,15}$/, /^\/r\/[0-9]{1,15}$/, RELEASE_LINK,
+    /^\/$/, /^\/tasks\?view=ready$/, /^\/tasks\?view=board$/, /^\/n\/[1-9][0-9]{0,14}$/];
 const CLASS_FALLBACK = {
-    decision: "/next",
-    pick: "/next",
-    merge: "/review",
-    attention: "/next",
-    progress: "/next",
+    decision: "/",
+    pick: "/",
+    merge: "/tasks?view=ready",
+    attention: "/",
+    progress: "/",
+    release: "/",
 };
 /** 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) {
+/** One line per ping (docs/plans/plain-toolroll.md P1.5), built only from the task's stored number and fixed words: no
+ * title, no free text. A fact about a task opens that task (/n/<n>); anything else keeps its class's fixed words and
+ * its own allow-listed link. Rows are tried in order; the first that matches says the line. */
+export const PUSH_LINES = [
+    { when: one => one.kind === "plan-ready", say: number => `#${number}: plan ready` },
+    { when: one => one.pushClass === "decision" || one.kind === "task-ask" || one.kind === "decision", say: number => `#${number} has a question` },
+    { when: one => one.pushClass === "merge" || one.pushClass === "pick" || one.kind === "pull-request-ready" || one.kind === "acceptance-ready", say: number => `#${number} is ready to review` },
+    { when: () => true, say: number => `#${number} needs you` },
+];
+/** The one line a ping says, and where its tap lands. */
+export function pushLineOf(notification) {
     const pushClass = notification.pushClass;
-    const words = PUSH_WORDS[pushClass];
+    if (pushClass === "progress" && isCheckProgressLine(notification.body))
+        return { body: notification.body, url: safePushLink(pushClass, notification.link) };
+    const number = notification.taskRef;
+    if (typeof number === "number" && Number.isSafeInteger(number) && number > 0) {
+        const row = PUSH_LINES.find(one => one.when(notification));
+        return { body: row.say(number), url: `/n/${number}` };
+    }
+    return { body: PUSH_WORDS[pushClass].body, url: safePushLink(pushClass, notification.link) };
+}
+/** `release`: the class and link the plane derived for this row at send time (releasePushOf): fixed words and a release's
+ * own link, never the task line. Absent or null, the row's own line. */
+export function buildPushPayload(notification, waiting = null, release = null) {
+    const line = release !== null ? { body: PUSH_WORDS.release.body, url: safePushLink("release", release.link) } : pushLineOf(notification);
     return JSON.stringify({
-        title: words.title,
-        body: pushClass === "progress" && isCheckProgressLine(notification.body) ? notification.body : words.body,
-        url: safePushLink(pushClass, notification.link),
+        title: "Toolroll",
+        body: line.body,
+        url: line.url,
         // The opaque tag collapses a crash-duplicate on the lock screen.
-        tag: pushClass === "progress" && notification.run !== null ? `so-run-${notification.run}` : `so-${notification.id}`,
+        tag: release === null && notification.pushClass === "progress" && notification.run !== null ? `so-run-${notification.run}` : `so-${notification.id}`,
         // The app-icon badge (Phase 2E, v2 S4): the server-computed
         // waiting-on-you COUNT at send time — a number, never content, so the
         // closed-class discipline holds. The console page recomputes and
@@ -268,6 +301,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 +320,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.d.ts

@@ -131,6 +131,8 @@ export type AutoObservers = {
     /** Whether main's protection holds for the account that merges (readMainProtection); null when unreadable. */
     upToDateRequired: () => Promise<boolean | null>;
     evidenceRoot: string;
+    /** The cases that ran in `sha`'s macOS CI (fenced-check-coverage.ts); null when they can't be read. Absent: never read. */
+    macosCases?: (sha: string) => Promise<ReadonlyMap<string, boolean> | null>;
 };
 /**
  * Every check run GitHub holds for one commit — every attempt, not only the latest (`filter=all`; GitHub's default
@@ -169,6 +171,13 @@ export declare function readMergeBase(run: Exec, gh: string, repo: string, base:
  * never from a ref in a checkout a build can write.
  */
 export declare function readMainHead(run: Exec, gh: string, repo: string, branch?: string): Promise<string>;
+/** GitHub's own "Update branch", with its expected head: a push that got there first refuses. */
+export declare function updatePullRequestBranch(run: Exec, gh: string, repo: string, pr: number, expectedHead: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+}>;
 /** Whether `sha` already holds `ancestor` (GitHub's compare: `sha` is not behind it), as GitHub answers now. */
 export declare function readContains(run: Exec, gh: string, repo: string, sha: string, ancestor: string): Promise<boolean>;
 /**

package/dist/release-adapters.js

@@ -24,6 +24,10 @@ import { databasePath, finishReleaseOperation, requireFreshReleaseApproval, open
 import { acquireDeploymentLock } from "./deploy-lock.js";
 import { autoReleaseApprovalOf, liveReleaseOf } from "./scope.js";
 import { recheckReleaseTask, releaseCheckStanding } from "./check-failure.js";
+import { CHECK_REPORT_CAPTURE, readSealedJson } from "./check-report.js";
+import { readCheckReport } from "./contracts/release-check.js";
+import { macosCases, skipCoverage, skippedCases, uncoveredWords } from "./fenced-check-coverage.js";
+import { runCheckStamp } from "./store.js";
 import { noteCiRunning, releaseCiHoldOf, releaseCiRunningOf } from "./release-ci-hold.js";
 import { autoPublishHeld, holdAutoPublish, liftCiHold, authorizeAutoCheck, giveUpAutoApproval, noteAutoCheckFailed, noteAutoRelease, releaseAutoApproves, sealAutoGreen } from "./release-auto.js";
 import { proveCarry } from "./release-carry.js";
@@ -31,6 +35,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";
@@ -434,6 +440,7 @@ export function releaseAdapters(options) {
     };
     const release = storeReleaseAdapter(() => openStore(database), store => store.close(), options.now ?? (() => new Date()), undefined, { observe: sha => observeCi(sha), mergeBase: (base, sha) => readMergeBase(reads, ciGh, releaseRepo().slug, base, sha),
         upToDateRequired: () => readUpToDateRequired(reads, ciGh, releaseRepo().slug), evidenceRoot: join(dirname(database), "evidence"),
+        macosCases: sha => macosCasesOf(run, ciGh, releaseRepo().slug, sha),
         // A successful Actions job authenticates the job, not the candidate-writable JSON it uploads. Until the
         // executor protects that reporting channel, production releases must take the person's approval road.
         reportsProtected: false }, 
@@ -529,7 +536,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 });
@@ -658,6 +665,7 @@ export function releaseAdapters(options) {
             async complete(repo, sha) { return readSuitesComplete(reads, ciGh, repo, sha); },
             async mainHead(repo) { return readMainHead(reads, ciGh, repo); },
             async contains(repo, sha, ancestor) { return readContains(reads, ciGh, repo, sha, ancestor); },
+            async updateBranch(repo, pr, expectedHead) { return updatePullRequestBranch(reads, ciGh, repo, pr, expectedHead); },
             async upToDateRequired(repo) { return readMainProtection(reads, ciGh, repo); },
             async merge(repo, pr, head, message) {
                 // The squash commit's message lists every commit that landed after the approval (release-once.md). Never asked
@@ -971,6 +979,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) {
@@ -979,6 +995,33 @@ nightlyReads) {
                     return answer.action === "rerun" ? { action: "rerun", why: answer.why } : answer.action === "pending" ? { action: "pending" } : { action: "stop", class: answer.class, why: answer.why };
                 });
             },
+            async fencedCoverage(_taskId, run, candidate) {
+                // Today's road, read first and answered at once: a check that ran unsandboxed skips nothing for this reason. A run
+                // from before stamps (a release resumed across an update) is judged by the level its dispatch recorded.
+                const asked = withStore(store => {
+                    if (store.runCheckAccess(run) === "unsandboxed")
+                        return null;
+                    const reading = runCheckStamp(store, run);
+                    if (reading.state !== "current")
+                        return { refused: "how its check ran wasn't recorded, so what it skipped can't be judged" };
+                    if (reading.stamp.level === "unsandboxed")
+                        return null;
+                    const sealed = readSealedJson(store, auto.evidenceRoot, run, CHECK_REPORT_CAPTURE);
+                    const report = sealed === null ? null : readCheckReport(sealed.value);
+                    return report?.ok === true ? { skipped: skippedCases(report.value) } : { refused: "its report can't be read, so what it skipped can't be judged" };
+                });
+                if (asked === null)
+                    return { ok: true, covered: 0 };
+                if ("refused" in asked)
+                    return { ok: false, why: asked.refused };
+                if (asked.skipped.length === 0)
+                    return { ok: true, covered: 0 };
+                const macos = await auto.macosCases?.(candidate) ?? null;
+                if (macos === null)
+                    return { ok: false, why: "this commit's macOS CI reports couldn't be read, so what the sandboxed check skipped isn't covered" };
+                const coverage = skipCoverage(asked.skipped, macos);
+                return coverage.uncovered.length > 0 ? { ok: false, why: uncoveredWords(coverage.uncovered) } : { ok: true, covered: coverage.covered.length };
+            },
             async standing(taskId, run) {
                 return withStore(store => {
                     const standing = releaseCheckStanding(store, auto.evidenceRoot, { taskId, run });
@@ -1307,6 +1350,13 @@ export async function readMainHead(run, gh, repo, branch = "main") {
         throw new Error(`GitHub named no commit for ${branch}`);
     return match[1];
 }
+/** GitHub's own "Update branch", with its expected head: a push that got there first refuses. */
+export async function updatePullRequestBranch(run, gh, repo, pr, expectedHead) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !Number.isSafeInteger(pr) || pr < 1 || !/^[0-9a-f]{40}$/.test(expectedHead))
+        return { ok: false, why: "not a pull request GitHub can be asked to update" };
+    const ran = await run(gh, ["api", "--hostname", "github.com", "--method", "PUT", `repos/${repo}/pulls/${pr}/update-branch`, "-f", `expected_head_sha=${expectedHead}`], { cwd: "/", env: ciEnv() });
+    return ran.code === 0 ? { ok: true } : { ok: false, why: (ran.stderr.trim().split("\n")[0] ?? "").slice(0, 200) || `gh exited ${ran.code}` };
+}
 /** Whether `sha` already holds `ancestor` (GitHub's compare: `sha` is not behind it), as GitHub answers now. */
 export async function readContains(run, gh, repo, sha, ancestor) {
     if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[0-9a-f]{40}$/.test(sha) || !/^[0-9a-f]{40}$/.test(ancestor))
@@ -1520,3 +1570,39 @@ export function releaseProgressRecorder(open, done) {
         }
     };
 }
+/** The macOS CI's cases on exactly `sha`: the newest pull-request run of ci.yml there, each shard's newest attempt. Null
+ * when they can't all be read. The folder is this function's own, removed before it returns. */
+async function macosCasesOf(run, gh, slug, sha) {
+    const folder = mkdtempSync(join(tmpdir(), "so-macos-ci-"));
+    try {
+        const listed = await run(gh, ["api", `repos/${slug}/actions/runs?head_sha=${sha}&event=pull_request&per_page=100`], { timeoutMs: 60_000 });
+        if (listed.code !== 0)
+            return null;
+        const runs = JSON.parse(listed.stdout).workflow_runs ?? [];
+        const newest = runs.filter(one => typeof one.id === "number" && one.head_sha === sha && (one.path === ".github/workflows/ci.yml" || String(one.path).startsWith(".github/workflows/ci.yml@"))).map(one => one.id).sort((a, b) => b - a)[0];
+        if (newest === undefined)
+            return null;
+        const got = await run(gh, ["run", "download", String(newest), "--repo", slug, "--pattern", "macos-shard-*", "--dir", folder], { timeoutMs: 180_000 });
+        if (got.code !== 0)
+            return null;
+        const shards = new Map();
+        for (const name of readdirSync(folder)) {
+            const match = /^macos-(shard-\d+-\d+)-a([1-9]\d*)$/.exec(name);
+            if (match === null)
+                return null;
+            const was = shards.get(match[1]);
+            if (was === undefined || Number(match[2]) > was.attempt)
+                shards.set(match[1], { attempt: Number(match[2]), name });
+        }
+        if (shards.size === 0)
+            return null;
+        const reports = [...shards.values()].map(one => JSON.parse(readFileSync(join(folder, one.name, "shard-report.json"), "utf8")));
+        return macosCases(reports, `/Users/runner/work/${slug.split("/")[1]}/${slug.split("/")[1]}`);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        rmSync(folder, { recursive: true, force: true });
+    }
+}

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[];
+};