toolroll 0.9.71 → 0.9.73

package/dist/publish.js

@@ -26,6 +26,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { run as execRun } from "./exec.js";
 import { summarizeChecks } from "./pulls.js";
+import { releasePublication } from "./store.js";
 import { headWithin } from "./names.js";
 export const BODY_TEMPLATE_VERSION = 2;
 /** After this many failed attempts a publication stops retrying and pages instead. */
@@ -529,168 +530,179 @@ export async function sweepMerges(store, options) {
     const method = grant.mergeMethod;
     const termsHash = mergeTermsHash(grant);
     for (const publication of store.openedPublications()) {
-        if (publication.prNumber === null || publication.headSha === null)
-            continue;
-        const prNumber = publication.prNumber;
-        const headSha = publication.headSha;
-        // The local-repo fence (finding 6): repo B's publication never rides
-        // repo A's sweep, whatever the remote terms coincide on.
-        const ref = store.refForId(publication.taskRef);
-        if (ref === null || ref.repo !== options.repo)
-            continue;
-        if (publication.githubRepo !== grant.githubRepo)
-            continue;
-        const blocker = store.mergeBlockerFor(publication.id);
-        if (blocker !== null) {
+        // A release's result merges only through `toolroll release` (release-once.md): the sweep never takes it up.
+        if (releasePublication(store, publication.id)) {
             report.skipped++;
-            pagePerson(publication, "blocked", "PR #" + prNumber + " holds for a repair", "A CI repair (" + (blocker.taskId ?? "?") + ") is in flight. It merges nothing until you lift it: toolroll publish unblock " + prNumber + ".");
             continue;
         }
-        store.createMergeIntent({ publication: publication.id, repo: options.repo, grantTermsHash: termsHash, headSha, method, deleteBranch: grant.mergeDeleteBranch === true }, clock());
-        const intent = store.mergeIntentFor(publication.id);
-        if (intent === null || intent.state === "merged" || intent.state === "refused" || intent.state === "superseded")
-            continue;
-        // WAITING-HUMAN never fires itself (E1): the person is paged once,
-        // episodically, with the exact ceremony that releases it.
-        if (intent.state === "waiting-human") {
-            report.skipped++;
-            pagePerson(publication, "waiting-human", "PR #" + prNumber + " waits for your go-ahead", "Merges wait for you while this posture holds. When you want it merged: toolroll publish merge " + prNumber + " --as <you> --token <t>. It still merges only when CI is seen green on the exact head.");
-            continue;
-        }
-        // FIRING is one-shot (E1): a live firing row belongs to its owner.
-        // A STALE one (deadline passed) recovers by STRUCTURED REMOTE REREAD
-        // (F1): an observed terminal settles it; an OPEN same-head PR is
-        // NEVER auto-retried - the person gets the recovery ceremony.
-        if (intent.state === "firing") {
-            if (intent.firingDeadline !== null && intent.firingDeadline <= clock().toISOString()) {
-                const reread = await observeOne(store, exec, clock, grant.githubRepo, prNumber);
-                if (!reread.ok && reread.why === "pr-merged") {
-                    store.settleMergeIntent(intent.id, intent.generation, "merged", clock(), {
-                        receipt: "observed merged remotely after a stale firing claim", from: "firing", bumpGeneration: true,
-                    });
-                    report.merged++;
+        // One bad row never stops the rest of the sweep: every other publication, in every project, still merges.
+        try {
+            if (publication.prNumber === null || publication.headSha === null)
+                continue;
+            const prNumber = publication.prNumber;
+            const headSha = publication.headSha;
+            // The local-repo fence (finding 6): repo B's publication never rides
+            // repo A's sweep, whatever the remote terms coincide on.
+            const ref = store.refForId(publication.taskRef);
+            if (ref === null || ref.repo !== options.repo)
+                continue;
+            if (publication.githubRepo !== grant.githubRepo)
+                continue;
+            const blocker = store.mergeBlockerFor(publication.id);
+            if (blocker !== null) {
+                report.skipped++;
+                pagePerson(publication, "blocked", "PR #" + prNumber + " holds for a repair", "A CI repair (" + (blocker.taskId ?? "?") + ") is in flight. It merges nothing until you lift it: toolroll publish unblock " + prNumber + ".");
+                continue;
+            }
+            store.createMergeIntent({ publication: publication.id, repo: options.repo, grantTermsHash: termsHash, headSha, method, deleteBranch: grant.mergeDeleteBranch === true }, clock());
+            const intent = store.mergeIntentFor(publication.id);
+            if (intent === null || intent.state === "merged" || intent.state === "refused" || intent.state === "superseded")
+                continue;
+            // WAITING-HUMAN never fires itself (E1): the person is paged once,
+            // episodically, with the exact ceremony that releases it.
+            if (intent.state === "waiting-human") {
+                report.skipped++;
+                pagePerson(publication, "waiting-human", "PR #" + prNumber + " waits for your go-ahead", "Merges wait for you while this posture holds. When you want it merged: toolroll publish merge " + prNumber + " --as <you> --token <t>. It still merges only when CI is seen green on the exact head.");
+                continue;
+            }
+            // FIRING is one-shot (E1): a live firing row belongs to its owner.
+            // A STALE one (deadline passed) recovers by STRUCTURED REMOTE REREAD
+            // (F1): an observed terminal settles it; an OPEN same-head PR is
+            // NEVER auto-retried - the person gets the recovery ceremony.
+            if (intent.state === "firing") {
+                if (intent.firingDeadline !== null && intent.firingDeadline <= clock().toISOString()) {
+                    const reread = await observeOne(store, exec, clock, grant.githubRepo, prNumber);
+                    if (!reread.ok && reread.why === "pr-merged") {
+                        store.settleMergeIntent(intent.id, intent.generation, "merged", clock(), {
+                            receipt: "observed merged remotely after a stale firing claim", from: "firing", bumpGeneration: true,
+                        });
+                        report.merged++;
+                    }
+                    else if (!reread.ok && reread.why.startsWith("pr-")) {
+                        store.settleMergeIntent(intent.id, intent.generation, "superseded", clock(), {
+                            error: reread.why, from: "firing", bumpGeneration: true,
+                        });
+                    }
+                    else if (reread.ok && reread.headSha !== intent.headSha) {
+                        store.settleMergeIntent(intent.id, intent.generation, "superseded", clock(), {
+                            error: "the head moved while the firing claim was stale", from: "firing", bumpGeneration: true,
+                        });
+                    }
+                    else {
+                        report.skipped++;
+                        pagePerson(publication, "half-fired", "PR #" + prNumber + " may have half-merged", "A merge was issued and its owner went silent; the PR is still open on the same commit. Nothing retries by itself. If you want it fired again: toolroll publish refire " + prNumber + " --as <you> --token <t>.");
+                    }
                 }
-                else if (!reread.ok && reread.why.startsWith("pr-")) {
-                    store.settleMergeIntent(intent.id, intent.generation, "superseded", clock(), {
-                        error: reread.why, from: "firing", bumpGeneration: true,
-                    });
+                else {
+                    report.skipped++;
                 }
-                else if (reread.ok && reread.headSha !== intent.headSha) {
-                    store.settleMergeIntent(intent.id, intent.generation, "superseded", clock(), {
-                        error: "the head moved while the firing claim was stale", from: "firing", bumpGeneration: true,
-                    });
+                continue;
+            }
+            const claim = store.claimMergeIntent(intent.id, who, MERGE_LEASE_MS, clock());
+            if (claim === null)
+                continue; // someone else's live claim
+            const settle = (state, detail = {}) => store.settleMergeIntent(intent.id, claim.generation, state, clock(), { from: "claimed", ...detail });
+            // The live grant, re-read AFTER the claim (finding 7): revocation,
+            // narrowing, or any term drift supersedes rather than merges.
+            const live = store.publicationGrantFor(options.repo);
+            if (live === null || live.merge !== true || mergeTermsHash(live) !== termsHash || intent.headSha !== headSha) {
+                settle("superseded", { error: "the grant or the head moved since this intent was written" });
+                continue;
+            }
+            const queue = await proveNoMergeQueue(exec, grant.githubRepo, grant.base);
+            if (!queue.ok) {
+                settle("refused", { error: queue.why });
+                report.refused++;
+                pagePerson(publication, queue.why, "PR #" + prNumber + " will not auto-merge", queue.why === "merge-queue"
+                    ? "The base branch requires a merge queue - out of this release's scope. Merge it on GitHub, or lift the queue and run: toolroll publish rearm " + prNumber + "."
+                    : "The branch's protection could not be READ well enough to prove no merge queue governs it - auto-merge stays paused. Check access, then run: toolroll publish rearm " + prNumber + ".");
+                continue;
+            }
+            // One fresh, winning observation - green on the EXACT publication head.
+            const seen = await observeOne(store, exec, clock, grant.githubRepo, prNumber);
+            if (!seen.ok) {
+                if (seen.why === "draft") {
+                    settle("refused", { error: "draft" });
+                    report.refused++;
+                    pagePerson(publication, "draft", "PR #" + prNumber + " is a draft", "Drafts never merge themselves. Mark it ready on GitHub, then run: toolroll publish rearm " + prNumber + ".");
+                }
+                else if (seen.why.startsWith("pr-")) {
+                    settle("superseded", { error: seen.why });
                 }
                 else {
+                    settle("pending");
+                    report.problems.push("PR #" + prNumber + ": " + seen.why);
+                }
+                continue;
+            }
+            if (seen.headSha !== headSha || seen.state !== "passing") {
+                settle(seen.headSha !== headSha ? "superseded" : "pending", {
+                    error: seen.headSha !== headSha ? "the head moved" : "CI is " + seen.state + ", not green",
+                });
+                continue;
+            }
+            // The linearization point (E1): claimed -> firing as a DURABLE CAS
+            // re-proving grant terms, head, and basis-specific authority in one
+            // transaction. Before it commits, a revocation wins; after, the
+            // issued call is one-shot and no revocation demotes it.
+            const fired = store.fireMergeIntent(intent.id, claim.generation, { repo: options.repo, headSha, liveGrantTermsHash: mergeTermsHash(live), graceMs: FIRING_GRACE_MS }, clock());
+            if (!fired.ok) {
+                if (fired.outcome === "waiting-human") {
                     report.skipped++;
-                    pagePerson(publication, "half-fired", "PR #" + prNumber + " may have half-merged", "A merge was issued and its owner went silent; the PR is still open on the same commit. Nothing retries by itself. If you want it fired again: toolroll publish refire " + prNumber + " --as <you> --token <t>.");
+                    pagePerson(publication, "waiting-human", "PR #" + prNumber + " waits for your go-ahead", fired.why + " - when you want it merged: toolroll publish merge " + prNumber + " --as <you> --token <t>.");
                 }
+                continue;
             }
-            else {
-                report.skipped++;
+            const merged = await exec("gh", [
+                "pr", "merge", String(prNumber),
+                "--repo", grant.githubRepo,
+                "--" + method,
+                "--match-head-commit", headSha,
+                ...(grant.mergeDeleteBranch === true ? ["--delete-branch"] : []),
+            ], { timeoutMs: EXEC_TIMEOUT_MS });
+            if (merged.code === 0) {
+                store.transact(() => {
+                    settle("merged", { receipt: "merged " + headSha.slice(0, 12) + " at " + clock().toISOString(), countAttempt: true, from: "firing" });
+                    store.recordPublicationRemoteState(publication.id, "MERGED", clock());
+                    store.resolveCiEpisodes(grant.githubRepo, prNumber, null, clock());
+                });
+                report.merged++;
+                store.resolveEpisodes(`merge-attn:${publication.id}`, clock());
+                page(publication, "merge:" + publication.id + ":merged", "merged: PR #" + prNumber, (publication.prUrl ?? grant.githubRepo) + " - " + method + " of " + headSha.slice(0, 12) + ", under the merge terms you approved.");
+                continue;
             }
-            continue;
-        }
-        const claim = store.claimMergeIntent(intent.id, who, MERGE_LEASE_MS, clock());
-        if (claim === null)
-            continue; // someone else's live claim
-        const settle = (state, detail = {}) => store.settleMergeIntent(intent.id, claim.generation, state, clock(), { from: "claimed", ...detail });
-        // The live grant, re-read AFTER the claim (finding 7): revocation,
-        // narrowing, or any term drift supersedes rather than merges.
-        const live = store.publicationGrantFor(options.repo);
-        if (live === null || live.merge !== true || mergeTermsHash(live) !== termsHash || intent.headSha !== headSha) {
-            settle("superseded", { error: "the grant or the head moved since this intent was written" });
-            continue;
-        }
-        const queue = await proveNoMergeQueue(exec, grant.githubRepo, grant.base);
-        if (!queue.ok) {
-            settle("refused", { error: queue.why });
-            report.refused++;
-            pagePerson(publication, queue.why, "PR #" + prNumber + " will not auto-merge", queue.why === "merge-queue"
-                ? "The base branch requires a merge queue - out of this release's scope. Merge it on GitHub, or lift the queue and run: toolroll publish rearm " + prNumber + "."
-                : "The branch's protection could not be READ well enough to prove no merge queue governs it - auto-merge stays paused. Check access, then run: toolroll publish rearm " + prNumber + ".");
-            continue;
-        }
-        // One fresh, winning observation - green on the EXACT publication head.
-        const seen = await observeOne(store, exec, clock, grant.githubRepo, prNumber);
-        if (!seen.ok) {
-            if (seen.why === "draft") {
-                settle("refused", { error: "draft" });
+            // NEVER classify from the exit code alone (only auth=4 is distinct):
+            // re-read structured state and let the PR say what happened.
+            if (merged.code === 4) {
+                settle("refused", { error: "credential", countAttempt: true, from: "firing" });
                 report.refused++;
-                pagePerson(publication, "draft", "PR #" + prNumber + " is a draft", "Drafts never merge themselves. Mark it ready on GitHub, then run: toolroll publish rearm " + prNumber + ".");
+                pagePerson(publication, "credential", "PR #" + prNumber + ": gh is not signed in", "The merge acts as this machine's GitHub account, and it could not authenticate. Run gh auth login, then: toolroll publish rearm " + prNumber + ".");
+                continue;
             }
-            else if (seen.why.startsWith("pr-")) {
-                settle("superseded", { error: seen.why });
+            const after = await observeOne(store, exec, clock, grant.githubRepo, prNumber);
+            if (!after.ok && after.why === "pr-merged") {
+                settle("merged", { receipt: "merged (confirmed by re-read after an ambiguous exit)", countAttempt: true, from: "firing" });
+                report.merged++;
             }
-            else {
-                settle("pending");
-                report.problems.push("PR #" + prNumber + ": " + seen.why);
+            else if (!after.ok && (after.why === "draft" || after.why.startsWith("pr-"))) {
+                settle(after.why === "draft" ? "refused" : "superseded", { error: after.why, countAttempt: true, from: "firing" });
+                if (after.why === "draft")
+                    report.refused++;
             }
-            continue;
-        }
-        if (seen.headSha !== headSha || seen.state !== "passing") {
-            settle(seen.headSha !== headSha ? "superseded" : "pending", {
-                error: seen.headSha !== headSha ? "the head moved" : "CI is " + seen.state + ", not green",
-            });
-            continue;
-        }
-        // The linearization point (E1): claimed -> firing as a DURABLE CAS
-        // re-proving grant terms, head, and basis-specific authority in one
-        // transaction. Before it commits, a revocation wins; after, the
-        // issued call is one-shot and no revocation demotes it.
-        const fired = store.fireMergeIntent(intent.id, claim.generation, { repo: options.repo, headSha, liveGrantTermsHash: mergeTermsHash(live), graceMs: FIRING_GRACE_MS }, clock());
-        if (!fired.ok) {
-            if (fired.outcome === "waiting-human") {
-                report.skipped++;
-                pagePerson(publication, "waiting-human", "PR #" + prNumber + " waits for your go-ahead", fired.why + " - when you want it merged: toolroll publish merge " + prNumber + " --as <you> --token <t>.");
+            else if (after.ok && after.headSha !== headSha) {
+                settle("superseded", { error: "the head moved during the attempt", countAttempt: true, from: "firing" });
             }
-            continue;
-        }
-        const merged = await exec("gh", [
-            "pr", "merge", String(prNumber),
-            "--repo", grant.githubRepo,
-            "--" + method,
-            "--match-head-commit", headSha,
-            ...(grant.mergeDeleteBranch === true ? ["--delete-branch"] : []),
-        ], { timeoutMs: EXEC_TIMEOUT_MS });
-        if (merged.code === 0) {
-            store.transact(() => {
-                settle("merged", { receipt: "merged " + headSha.slice(0, 12) + " at " + clock().toISOString(), countAttempt: true, from: "firing" });
-                store.recordPublicationRemoteState(publication.id, "MERGED", clock());
-                store.resolveCiEpisodes(grant.githubRepo, prNumber, null, clock());
-            });
-            report.merged++;
-            store.resolveEpisodes(`merge-attn:${publication.id}`, clock());
-            page(publication, "merge:" + publication.id + ":merged", "merged: PR #" + prNumber, (publication.prUrl ?? grant.githubRepo) + " - " + method + " of " + headSha.slice(0, 12) + ", under the merge terms you approved.");
-            continue;
-        }
-        // NEVER classify from the exit code alone (only auth=4 is distinct):
-        // re-read structured state and let the PR say what happened.
-        if (merged.code === 4) {
-            settle("refused", { error: "credential", countAttempt: true, from: "firing" });
-            report.refused++;
-            pagePerson(publication, "credential", "PR #" + prNumber + ": gh is not signed in", "The merge acts as this machine's GitHub account, and it could not authenticate. Run gh auth login, then: toolroll publish rearm " + prNumber + ".");
-            continue;
-        }
-        const after = await observeOne(store, exec, clock, grant.githubRepo, prNumber);
-        if (!after.ok && after.why === "pr-merged") {
-            settle("merged", { receipt: "merged (confirmed by re-read after an ambiguous exit)", countAttempt: true, from: "firing" });
-            report.merged++;
-        }
-        else if (!after.ok && (after.why === "draft" || after.why.startsWith("pr-"))) {
-            settle(after.why === "draft" ? "refused" : "superseded", { error: after.why, countAttempt: true, from: "firing" });
-            if (after.why === "draft")
+            else if (intent.attempts + 1 >= MERGE_MAX_ATTEMPTS) {
+                settle("refused", { error: firstLine(merged.stderr) || "the merge was rejected", countAttempt: true, from: "firing" });
                 report.refused++;
+                pagePerson(publication, "rejected", "PR #" + prNumber + " would not merge", (firstLine(merged.stderr) || "GitHub rejected the merge") + " - likely branch protection, required reviews, or a conflict. Fix the cause, then run: toolroll publish rearm " + prNumber + ".");
+            }
+            else {
+                settle("pending", { error: firstLine(merged.stderr) || "transport", countAttempt: true, from: "firing" });
+            }
         }
-        else if (after.ok && after.headSha !== headSha) {
-            settle("superseded", { error: "the head moved during the attempt", countAttempt: true, from: "firing" });
-        }
-        else if (intent.attempts + 1 >= MERGE_MAX_ATTEMPTS) {
-            settle("refused", { error: firstLine(merged.stderr) || "the merge was rejected", countAttempt: true, from: "firing" });
-            report.refused++;
-            pagePerson(publication, "rejected", "PR #" + prNumber + " would not merge", (firstLine(merged.stderr) || "GitHub rejected the merge") + " - likely branch protection, required reviews, or a conflict. Fix the cause, then run: toolroll publish rearm " + prNumber + ".");
-        }
-        else {
-            settle("pending", { error: firstLine(merged.stderr) || "transport", countAttempt: true, from: "firing" });
+        catch (error) {
+            report.problems.push("publication " + publication.id + ": " + (error instanceof Error ? error.message : String(error)));
         }
     }
     return report;

package/dist/pull-request-flow.d.ts

@@ -180,4 +180,6 @@ export type PullRequestView = {
 export declare function pullRequestViewOf(store: Store, runId: number): PullRequestView | null;
 /** The newest pull request any version of a task opened through Complete (versions oldest first), or null. */
 export declare function newestPullRequestOf(store: Store, versions: readonly string[]): PullRequestView | null;
+/** Why a machine credential's merge is refused (approval policy §1.7). */
+export declare const MERGE_NEEDS_PERSON = "Only a person can merge. Merge it on the task page or from your paired chat.";
 export {};

package/dist/pull-request-flow.js

@@ -21,8 +21,10 @@ import { failingChecks, summarizeChecks } from "./pulls.js";
 import { assignmentOf, checkAssignmentAsOperator } from "./assignment.js";
 import { requestResultChanges } from "./result-actions.js";
 import { revisionSourceOf } from "./result-review.js";
-import { authenticateApprover } from "./scope.js";
+import { authenticateApprover, personProof } from "./scope.js";
 import { BRANCH_PREFIX, headWithin } from "./names.js";
+import { NIGHTLY_CHECK_ONLY, RELEASE_MERGES_ONLY, nightlyTaskRef, releaseTaskRef } from "./store.js";
+import { belongsToRelease } from "./release-authority.js";
 import { fullCheckGate, requestFollowUpChecks } from "./result-follow-ups.js";
 export const MERGE_METHODS = ["squash", "merge", "rebase"];
 /** CI revisions one task may file across its revisions before a person is asked instead. */
@@ -143,6 +145,10 @@ export function pullRequestBlocker(store, runId) {
         return "Pull requests aren't set up for this project.";
     if (run.headRevision === null || run.committed === false)
         return "This result has no commit to publish.";
+    if (nightlyTaskRef(store, run.taskRef))
+        return NIGHTLY_CHECK_ONLY;
+    if (releaseTaskRef(store, run.taskRef))
+        return RELEASE_MERGES_ONLY;
     if (run.branch === null || !headWithin(run.branch, grant.headPrefix))
         return "This result's branch isn't one Toolroll may push.";
     if (store.hasRedactedTerminalDiff(runId))
@@ -370,8 +376,13 @@ export async function mergeAsPerson(store, input) {
     const repo = run === null ? null : store.refById(run.taskRef)?.repo ?? null;
     if (input.password === "")
         return refuse("password", "Enter your password to merge.");
-    if (!authenticateApprover(store, input.name, input.password, repo).ok)
+    const proved = authenticateApprover(store, input.name, input.password, repo);
+    if (!proved.ok)
         return refuse("password", "That password didn't work, or you can't merge in this project.");
+    // A merge by hand is a person's (approval policy §1.7): the lead's token or a remote API token proves a credential,
+    // not a person — `--anyway` included.
+    if (!personProof(proved.method))
+        return refuse("person-required", MERGE_NEEDS_PERSON);
     return mergePullRequest(store, { runId: input.runId, by: input.name, ...(input.anyway === true ? { anyway: true } : {}), ...(input.exec === undefined ? {} : { exec: input.exec }), ...(input.clock === undefined ? {} : { clock: input.clock }) });
 }
 /**
@@ -382,6 +393,15 @@ export async function mergeAsPerson(store, input) {
 export async function mergePullRequest(store, input) {
     const exec = input.exec ?? execRun;
     const clock = input.clock ?? (() => new Date());
+    // The nightly check of main (release-once.md, part 3) is a check only: it never merges.
+    const mergedRun = store.getRun(input.runId);
+    const mergedTask = mergedRun === null ? null : store.refById(mergedRun.taskRef)?.externalId ?? null;
+    if (mergedTask !== null && store.handle.prepare("SELECT 1 AS hit FROM nightly_check WHERE task = ?").get(mergedTask) !== undefined)
+        return refuse("check-only", "The nightly check of main is only a check; it never merges.");
+    // A release's task merges only through `toolroll release` (release-once.md), which proves the live release, reserves
+    // the merge at its lease's epoch and checks the exact pull request: never here, by hand or automatically.
+    if (mergedTask !== null && belongsToRelease(store, mergedTask))
+        return refuse("release", "This result belongs to a release; it merges only through `toolroll release`.");
     const publication = store.publicationForRun(input.runId);
     const follow = publication === null ? null : followOf(store, publication.id);
     if (publication === null || follow === null || publication.prNumber === null)
@@ -505,3 +525,5 @@ export function newestPullRequestOf(store, versions) {
     }
     return null;
 }
+/** Why a machine credential's merge is refused (approval policy §1.7). */
+export const MERGE_NEEDS_PERSON = "Only a person can merge. Merge it on the task page or from your paired chat.";

package/dist/release-adapters.d.ts

@@ -5,10 +5,15 @@
  * the sign-ins this machine already has.
  */
 import type { GateState, Installed, ReleaseAdapters } from "./release.js";
+import { Store } from "./store.js";
+import { type BuildRunner } from "./release-carry.js";
+import { type ReleaseRepo, type ReleaseTools } from "./release-git.js";
+export { RELEASE_PATH, RELEASE_REMOTE, releaseConfigProblem, releaseGitArgs, releaseGitEnv, releaseRemote, releaseTools, type ReleaseRepo, type ReleaseTools } from "./release-git.js";
 export type Exec = (command: string, args: readonly string[], options?: {
     cwd?: string;
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
+    input?: string;
 }) => Promise<{
     code: number;
     stdout: string;
@@ -38,8 +43,14 @@ export declare function stageGate(stage: string, owner: () => string | null): {
     id: string;
     phase: string;
 } | null;
+/** The recorded repository for a gate checkout, from the plane's database; throws in plain words when there is none. */
+export declare function recordedReleaseRepo(database: string, checkout: string): ReleaseRepo;
 export type AdapterOptions = {
     checkout: string;
+    /** The recorded repository and the programs, when a caller (a test) supplies them; otherwise read from the plane's
+     * records and found on this machine when the first Git command runs. */
+    releaseRepo?: ReleaseRepo;
+    tools?: ReleaseTools;
     /** The live database (default: this installation's). */
     database?: string;
     processes?: typeof processes;
@@ -66,4 +77,8 @@ export declare function releaseAdapters(options: AdapterOptions): ReleaseAdapter
 export declare function workflowRunsOnChange(text: string): boolean;
 /** The formula with its first `url` and `sha256` replaced; anything else is left exactly as it was. */
 export declare function bumpFormula(text: string, url: string, sha256: string): string;
-export {};
+/**
+ * The release's authority record through a store (release-once.md): what `toolroll release` reads and writes for its
+ * lease, its carries and its operations. `open` hands a store for each call and `done` lets it go.
+ */
+export declare function storeReleaseAdapter(open: () => Store, done: (store: Store) => void, now: () => Date, runner?: BuildRunner): NonNullable<ReleaseAdapters["release"]>;