toolroll 0.9.74 → 0.9.76

package/dist/planner.js

@@ -20,6 +20,7 @@ import { unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { run } from "./exec.js";
+import { checkoutGit } from "./teardown-git.js";
 import { auditOf, isProviderId } from "./provider.js";
 import { currentClaim, heartbeat } from "./claim.js";
 import { heartbeat as runnerHeartbeat } from "./runner.js";
@@ -491,7 +492,10 @@ function draftedOutcome(root, runId, plan, repairRunId = null) {
     return { ok: true, drafted: { plan, artifact, repairRunId } };
 }
 export async function plan(store, request) {
-    const { taskId, taskRef, runner, worktree, branch, now, agent, git = run, timeoutMs = DEFAULT_PLAN_TIMEOUT_MS, maxTurns = DEFAULT_PLAN_TURNS, } = request;
+    const { taskId, taskRef, runner, worktree, branch, now, agent, git: givenGit = run, timeoutMs = DEFAULT_PLAN_TIMEOUT_MS, maxTurns = DEFAULT_PLAN_TURNS, } = request;
+    // The plane's git on the plan's checkout (agent-written, and its repository shared with every build) runs hardened, against
+    // a frozen view of the repository's config and info (teardown-git.ts checkoutGit); an injected runner is used as given.
+    const git = givenGit === run ? checkoutGit(run, "build", { repo: store.getWorktree(worktree)?.repo ?? null }) : givenGit;
     // An ACP agent works with full access inside the fence: it builds and repairs, and is never handed a plan (routing refuses it first).
     if (request.provider !== undefined && isAcpProvider(request.provider)) {
         return { ok: false, kind: "failure", reason: "provider-unsupported", message: `${ACP_AGENTS[request.provider].name} builds and repairs only — configure the planner to claude, codex or gemini` };

package/dist/project-knowledge.js

@@ -35,7 +35,7 @@ CREATE TRIGGER IF NOT EXISTS knowledge_snapshot_no_update BEFORE UPDATE ON knowl
 CREATE TRIGGER IF NOT EXISTS knowledge_snapshot_no_delete BEFORE DELETE ON knowledge_snapshot BEGIN SELECT RAISE(ABORT,'Knowledge context is immutable'); END;
 `;
 const EMPTY = { instructions: '', references: [] };
-const git = (repo, args) => execFileSync('git', ['--no-optional-locks', '-C', repo, ...args], { encoding: 'utf8', maxBuffer: 200_000, stdio: ['ignore', 'pipe', 'pipe'] }).trimEnd();
+const git = (repo, args) => execFileSync('git', ['--no-optional-locks', '--no-lazy-fetch', '-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', '-C', repo, ...args], { encoding: 'utf8', maxBuffer: 200_000, stdio: ['ignore', 'pipe', 'pipe'] }).trimEnd();
 function clean(value, bytes) {
     if (Buffer.byteLength(value) > bytes || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\ufffd]/u.test(value))
         throw Error('This text is too long or is not readable text.');

package/dist/project-learning.js

@@ -1,8 +1,10 @@
 /** Optional, project-local advice. Core review and approval never depend on it. */
+import { inReadOnlyRequest } from "./read-only-request.js";
+import { checkoutGitSync } from './teardown-git.js';
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { realpathSync, statSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { readVerifiedArtifact, scanForSecrets } from './evidence.js';
 import { normalizeStructuredJson } from "./structured-output.js";
 import { parseReviewContext, reviewContextCustodyProblem } from "./review-context.js";
@@ -50,7 +52,9 @@ const git = (repo, args, seen) => {
     const known = seen?.get(key);
     if (known !== undefined)
         return known;
-    const out = execFileSync('git', ['--no-optional-locks', '-C', repo, ...args], { encoding: 'utf8', maxBuffer: 2 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] }).trimEnd();
+    // Bounded, and no hook or fsmonitor program: it also runs from the console's background pass.
+    // No lazy fetch either: a partial clone's fetch runs whatever transport command the shared config names.
+    const out = execFileSync('git', ['--no-optional-locks', '--no-lazy-fetch', '-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', '-C', repo, ...args], { encoding: 'utf8', maxBuffer: 2 * 1024 * 1024, timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] }).trimEnd();
     seen?.set(key, out);
     return out;
 };
@@ -62,9 +66,42 @@ export const legacyIdentityOf = (repo, common, st) => learningSha(JSON.stringify
 function identityFacts(repo, seen) {
     if (canonicalProject(repo) !== repo)
         throw new Error('Project identity changed.');
-    const common = realpathSync(resolve(repo, git(repo, ['rev-parse', '--git-common-dir'], seen)));
+    // A page visit starts no git (docs/plans/get-side-effects.md): it reads the same answer from the folder itself.
+    const common = realpathSync(resolve(repo, inReadOnlyRequest() ? commonDirOnDisk(repo) : git(repo, ['rev-parse', '--git-common-dir'], seen)));
     return { common, st: statSync(common) };
 }
+/** The shared Git folder as git finds it for a checkout: `.git` itself, or the folder a `.git` file names, through its
+ * `commondir` when it is a linked worktree. Throws when the folder holds neither. */
+function commonDirOnDisk(repo) {
+    const dotGit = join(repo, '.git');
+    if (lstatSync(dotGit).isDirectory())
+        return dotGit;
+    const named = /^gitdir: (.+)$/m.exec(smallFile(dotGit))?.[1]?.trim();
+    if (!named)
+        throw new Error('Project identity is unavailable.');
+    const gitDir = resolve(repo, named);
+    if (!lstatSync(gitDir).isDirectory())
+        throw new Error('Project identity is unavailable.');
+    const commondir = join(gitDir, 'commondir');
+    if (!existsSync(commondir))
+        return gitDir;
+    return resolve(gitDir, smallFile(commondir).trim());
+}
+/** A small plain file's text, read through one descriptor that follows no link and never waits (a FIFO, a device or a
+ * file swapped in between is refused, never read), at most 4 KiB. */
+function smallFile(path) {
+    const fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+    try {
+        const st = fstatSync(fd);
+        if (!st.isFile() || st.size > 4096)
+            throw new Error('Project identity is unavailable.');
+        const buffer = Buffer.alloc(4096);
+        return buffer.subarray(0, readSync(fd, buffer, 0, 4096, 0)).toString('utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 export function learningIdentity(repo, seen) {
     const { common, st } = identityFacts(repo, seen);
     return identityOf(repo, common, st);
@@ -114,7 +151,8 @@ export function reconcileIdentity(store, repo, seen, now = new Date()) {
     if (!done)
         reconciled.set(store, done = new Set());
     const key = `${repo}\n${legacy}`;
-    if (legacy !== current && !done.has(key)) {
+    // Carrying saved rows to the current identity is a write: never a page visit's (the background pass does it).
+    if (legacy !== current && !done.has(key) && !inReadOnlyRequest()) {
         if (!store.handle.prepare('SELECT 1 FROM project_identity_carry WHERE repo=? AND from_identity=? AND to_identity=?').get(repo, legacy, current)
             && store.handle.prepare(STORED_IDENTITY).get(repo, legacy)) {
             // Damaged knowledge history keeps its own error; retry on the next read.
@@ -413,7 +451,9 @@ function supported(store, root, lesson, seen) {
 }
 export function learningView(store, root, repo, actor, before = 0) {
     admission(store, repo, actor);
-    recoverLearning(store, root, repo);
+    // Recovering learning from reviewed runs writes: the console's background pass and each run's start do it.
+    if (!inReadOnlyRequest())
+        recoverLearning(store, root, repo);
     const identity = learningIdentity(repo), accepted = acceptedIdentities(store, repo);
     const p = store.handle.prepare('SELECT * FROM learning_policy WHERE repo=?').get(repo);
     const revision = Number(p?.['revision'] ?? 0), enabled = accepted.has(String(p?.['identity'])) && p?.['enabled'] === 1;
@@ -504,6 +544,24 @@ export function learningContext(store, root, runId, phase, now = new Date(), val
             // advice may inform its proposal; only an approval can authorize a build.
             const unscopedPlan = phase === 'plan' && scope === null && !run.scopeDigest;
             const eligible = [];
+            // The checkout's status, read once for every lesson (one command on one checkout): a hardened read costs a
+            // private view and several git processes, and this runs inside the transaction. A failed read fails every lesson
+            // that reaches it, as each read alone would have.
+            let status = null;
+            const statusLines = (cwd) => {
+                status ??= (() => {
+                    // A build's checkout: status runs filters, so the hardened read (teardown-git.ts checkoutGitSync).
+                    try {
+                        return { lines: checkoutGitSync(cwd, ['status', '--porcelain', '--untracked-files=all'], { timeoutMs: 10_000, maxBuffer: 2 * 1024 * 1024 }).trimEnd().split('\n') };
+                    }
+                    catch (error) {
+                        return { error };
+                    }
+                })();
+                if ('error' in status)
+                    throw status.error;
+                return status.lines;
+            };
             if (policy && (paths.length > 0 || unscopedPlan)) {
                 for (const row of store.handle.prepare("SELECT * FROM project_lesson WHERE repo=? AND identity IN (SELECT value FROM json_each(?)) AND status='adopted' ORDER BY id DESC LIMIT 100").all(repo, carried)) {
                     try {
@@ -514,7 +572,7 @@ export function learningContext(store, root, runId, phase, now = new Date(), val
                         if (l.payload.environment !== environmentFingerprint(store, repo) || learningFingerprint(repo, head, l.payload.paths, seen) !== l.payload.fingerprint)
                             continue;
                         const cwd = run.worktree ?? repo;
-                        const dirty = git(cwd, ['status', '--porcelain', '--untracked-files=all'], seen).split('\n').some(line => { const p = line.slice(3); return configPath(p) || l.payload.paths.includes(p); });
+                        const dirty = statusLines(cwd).some(line => { const p = line.slice(3); return configPath(p) || l.payload.paths.includes(p); });
                         if (!dirty)
                             eligible.push(l);
                     }

package/dist/project-tools.js

@@ -19,6 +19,7 @@
  * the agent. A tool connected by signing in gives a run only an access token
  * of its own (oauth-run-token.ts).
  */
+import { inReadOnlyRequest } from "./read-only-request.js";
 import { toolRefusal } from "./policy.js";
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
@@ -319,6 +320,23 @@ function moveIn(backend, folder, repo, tool) {
 export function readToolSecrets(repo, tool, state) {
     const folder = secretFolder(state);
     const backend = secretBackend();
+    // A page visit moves nothing (docs/plans/get-side-effects.md): it reads the store, else the file not yet moved in.
+    if (inReadOnlyRequest()) {
+        const stored = readStored(backend, folder, repo, tool);
+        if (stored !== null)
+            return stored;
+        for (const file of [legacyFile(folder, repo, tool), backend === null ? null : toolFile(folder, repo, tool, ".json")]) {
+            if (file === null || !existsSync(file))
+                continue;
+            try {
+                const values = readSecretFile(file);
+                if (values !== null)
+                    return values;
+            }
+            catch { /* kept as it is, and never used */ }
+        }
+        return {};
+    }
     moveIn(backend, folder, repo, tool);
     return readStored(backend, folder, repo, tool) ?? {};
 }
@@ -1067,7 +1085,7 @@ export function secretsSetFor(repo, tool, state) {
     if (names === null) {
         const values = readToolSecrets(repo, tool.name, state);
         names = Object.keys(values).filter(name => values[name] !== "");
-        if (backend !== null)
+        if (backend !== null && !inReadOnlyRequest())
             writeNames(folder, repo, tool.name, names);
     }
     return tool.secrets.filter(one => names.includes(one.name)).map(one => one.name);

package/dist/pull-request-flow.js

@@ -25,6 +25,7 @@ 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 { autoReleaseSealed } from "./release-auto.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. */
@@ -402,6 +403,9 @@ export async function mergePullRequest(store, input) {
     // 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`.");
+    // A release task the plane approved (or is checking) automatically (auto-approve-green.md) never merges here either.
+    if (mergedTask !== null && autoReleaseSealed(store, mergedTask))
+        return refuse("release", "This result was approved automatically for 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)

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

@@ -16,7 +16,7 @@ export type PullRequestSettingsView = {
     } | {
         ok: false;
         message: string;
-    } | null;
+    } | "unchecked" | null;
     said: string | null;
     problem: string | null;
 };

package/dist/pull-request-ui.js

@@ -22,8 +22,12 @@ export function pullRequestSettingsHtml(view) {
     const check = view.check;
     if (check === null)
         return html `${head}<section class="card pr-settings"><p><strong>Off</strong></p><p class="meta">An approver can turn on pull requests.</p></section>`;
+    // The checks ask git and GitHub, so they run when asked, never on opening the page (docs/plans/get-side-effects.md).
+    const checkButton = (label) => postForm("/settings/pull-requests/check", html `<button type="submit"${label === "Check again" ? html ` class="secondary"` : ""}>${label}</button>`, { hidden: { repo: view.repo } });
+    if (check === "unchecked")
+        return html `${head}<section class="card pr-settings"><p><strong>Off</strong></p><p class="meta">Check this project's GitHub setup to see what turning on would do.</p>${checkButton("Check setup")}</section>`;
     if (!check.ok) {
-        return html `${head}<section class="card pr-settings"><p><strong>Can’t turn on yet</strong></p><p>${check.message}</p><p><a class="button-link" href="/settings/pull-requests?repo=${encodeURIComponent(view.repo)}">Check again</a></p></section>`;
+        return html `${head}<section class="card pr-settings"><p><strong>Can’t turn on yet</strong></p><p>${check.message}</p>${checkButton("Check again")}</section>`;
     }
     const plan = check.plan;
     return html `${head}${post("on", html `<p><strong>Ready to turn on</strong></p><ul class="pr-terms"><li>Pull requests open on <span class="mono">${plan.githubRepo}</span> into <span class="mono">${plan.base}</span>${plan.account === null ? "" : `, as ${plan.account}`}.</li><li>Complete offers “Complete and open a pull request”, from the exact completed commit. A flow's Pull request zone can open one too.</li><li>Merging squashes and deletes the branch. A person merges with their password; a flow merges only when its zone says so, after a person approved the card.</li></ul>${password}<button type="submit">Turn on pull requests</button>`, { github: plan.githubRepo, base: plan.base })}`;

package/dist/push.d.ts

@@ -31,6 +31,8 @@ export type VapidKeys = {
     fingerprint: string;
 };
 export declare function vapidFingerprint(publicKey: string): string;
+/** Load the saved pair only (null when none is saved yet): what a page reads (docs/plans/get-side-effects.md). */
+export declare function loadVapidKeys(dir: string): VapidKeys | null;
 /**
  * Mint-or-load, atomically across processes (finding 29): exclusive
  * creation; the loser of a race re-reads the winner's file; and a loaded

package/dist/push.js

@@ -35,6 +35,10 @@ const fromB64url = (text) => Buffer.from(text, "base64url");
 export function vapidFingerprint(publicKey) {
     return createHash("sha256").update(publicKey, "utf8").digest("hex").slice(0, 16);
 }
+/** Load the saved pair only (null when none is saved yet): what a page reads (docs/plans/get-side-effects.md). */
+export function loadVapidKeys(dir) {
+    return readVapidKeys(join(dir, VAPID_FILE));
+}
 /**
  * Mint-or-load, atomically across processes (finding 29): exclusive
  * creation; the loser of a race re-reads the winner's file; and a loaded
@@ -43,25 +47,7 @@ export function vapidFingerprint(publicKey) {
  */
 export function loadOrCreateVapidKeys(dir) {
     const path = join(dir, VAPID_FILE);
-    const read = () => {
-        let raw;
-        try {
-            raw = readFileSync(path, "utf8");
-        }
-        catch {
-            return null;
-        }
-        const parsed = JSON.parse(raw);
-        if (typeof parsed.publicKey !== "string" || typeof parsed.privateKey !== "string") {
-            throw new Error(`${VAPID_FILE} is not a key file`);
-        }
-        const check = createECDH("prime256v1");
-        check.setPrivateKey(fromB64url(parsed.privateKey));
-        if (b64url(check.getPublicKey()) !== parsed.publicKey) {
-            throw new Error(`${VAPID_FILE} holds a mismatched key pair — refusing to sign with it`);
-        }
-        return { publicKey: parsed.publicKey, privateKey: parsed.privateKey, fingerprint: vapidFingerprint(parsed.publicKey) };
-    };
+    const read = () => readVapidKeys(path);
     const existing = read();
     if (existing !== null)
         return existing;
@@ -87,6 +73,25 @@ export function loadOrCreateVapidKeys(dir) {
         return winner;
     }
 }
+function readVapidKeys(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.publicKey !== "string" || typeof parsed.privateKey !== "string") {
+        throw new Error(`${VAPID_FILE} is not a key file`);
+    }
+    const check = createECDH("prime256v1");
+    check.setPrivateKey(fromB64url(parsed.privateKey));
+    if (b64url(check.getPublicKey()) !== parsed.publicKey) {
+        throw new Error(`${VAPID_FILE} holds a mismatched key pair — refusing to sign with it`);
+    }
+    return { publicKey: parsed.publicKey, privateKey: parsed.privateKey, fingerprint: vapidFingerprint(parsed.publicKey) };
+}
 // ---- RFC 8291 encryption ----------------------------------------------------
 /**
  * The deterministic core, exported for the Appendix A vector test: given

package/dist/read-only-request.d.ts

@@ -0,0 +1,4 @@
+/** Run a GET or HEAD request's work. */
+export declare function asReadOnlyRequest<T>(work: () => T): T;
+/** Whether the current work answers a GET or HEAD request. */
+export declare function inReadOnlyRequest(): boolean;

package/dist/read-only-request.js

@@ -0,0 +1,15 @@
+/**
+ * A page visit only reads (docs/plans/get-side-effects.md). The server runs every GET and HEAD inside this scope, and
+ * the few store reads that used to tidy up as they went (closing an operating mode past its expiry) check it and
+ * leave the tidying to the background pass and the paths that act.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const scope = new AsyncLocalStorage();
+/** Run a GET or HEAD request's work. */
+export function asReadOnlyRequest(work) {
+    return scope.run(true, work);
+}
+/** Whether the current work answers a GET or HEAD request. */
+export function inReadOnlyRequest() {
+    return scope.getStore() === true;
+}

package/dist/release-adapters.d.ts

@@ -4,8 +4,9 @@
  * Homebrew tap through `gh`. Each call is bounded; none asks for or stores a credential — `gh`, npm and Toolroll use
  * the sign-ins this machine already has.
  */
-import type { GateState, Installed, ReleaseAdapters } from "./release.js";
+import type { CheckRun, GateState, Installed, ReleaseAdapters } from "./release.js";
 import { Store } from "./store.js";
+import { type CiObservation } from "./release-auto.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";
@@ -81,4 +82,25 @@ export declare function bumpFormula(text: string, url: string, sha256: string):
  * 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"]>;
+export declare function storeReleaseAdapter(open: () => Store, done: (store: Store) => void, now: () => Date, runner?: BuildRunner, 
+/** Releases that approve themselves (auto-approve-green.md): the plane's own look at CI on a commit, and where the
+ * check receipts are kept. Absent: no automatic approval, every release asks a person. */
+auto?: AutoObservers): NonNullable<ReleaseAdapters["release"]>;
+/** What the plane itself reads for an automatic release approval. */
+export type AutoObservers = {
+    observe: (sha: string) => Promise<CiObservation>;
+    /** GitHub's merge base of `sha` with the branch `base` of the recorded repository. */
+    mergeBase: (base: string, sha: string) => Promise<string>;
+    evidenceRoot: string;
+};
+/**
+ * Every check run GitHub holds for one commit — every attempt, not only the latest (`filter=all`; GitHub's default
+ * lists only the latest of each), every page — with its id, app, check suite and the commit it is filed under, oldest
+ * first. A row that doesn't parse stops the read: a partial answer is never taken for the whole.
+ */
+export declare function readCheckRuns(run: Exec, gh: string, repo: string, sha: string): Promise<CheckRun[]>;
+/** GitHub lists check runs from at most the latest 1000 check suites of a commit: the history is whole only below that. */
+export declare const CHECK_SUITE_CEILING = 1000;
+export declare function readSuitesComplete(run: Exec, gh: string, repo: string, sha: string): Promise<boolean>;
+/** GitHub's merge base of `sha` with branch `base` (the compare API), read by the plane. */
+export declare function readMergeBase(run: Exec, gh: string, repo: string, base: string, sha: string): Promise<string>;

package/dist/release-adapters.js

@@ -19,7 +19,8 @@ import { BEFORE_SWAP, gateOwner } from "./release-gate.js";
 import { findCliLinks, switchCliLinks } from "./release-links.js";
 import { databasePath, finishReleaseOperation, requireFreshReleaseApproval, openStore, releaseAuthorityOfTask, releaseCarries, releaseOperations, renewReleaseLease, reserveRelease, runReleaseOperation, Store, releaseIssuerGone, takeReleaseLease, } from "./store.js";
 import { acquireDeploymentLock } from "./deploy-lock.js";
-import { liveReleaseOf } from "./scope.js";
+import { autoReleaseApprovalOf, liveReleaseOf } from "./scope.js";
+import { autoPublishHeld, holdAutoPublish, authorizeAutoCheck, giveUpAutoApproval, noteAutoCheckFailed, noteAutoRelease, releaseAutoApproves, sealAutoGreen } from "./release-auto.js";
 import { proveCarry } from "./release-carry.js";
 import { randomBytes, randomUUID } from "node:crypto";
 import { deploymentGate } from "./deploy-gate.js";
@@ -236,6 +237,14 @@ export function releaseAdapters(options) {
         }
     };
     const refused = (answer) => `${String(answer["message"] ?? answer["reason"] ?? "refused")}`;
+    /** gh for every CI and merge-base read (auto-approve-green.md): found only in the system's own folders, never the
+     * caller's PATH (a test hands its own). */
+    const ciGh = options.tools?.gh ?? releaseTools("").gh;
+    const observeCi = async (sha) => {
+        const observedAt = (options.now ?? (() => new Date()))().toISOString();
+        const runs = (await readCheckRuns(run, ciGh, releaseRepo().slug, sha)).map(one => ({ id: one.id ?? null, name: one.name, status: one.status, conclusion: one.conclusion, app: one.app ?? null, suite: one.suite ?? null, head: one.head ?? null, workflow: one.workflow ?? null }));
+        return { head: sha, observedAt, runs, complete: await readSuitesComplete(run, ciGh, releaseRepo().slug, sha) };
+    };
     const database = options.database ?? databasePath(process.env, homedir());
     let recorded = options.releaseRepo ?? null;
     /** The recorded repository, read once (chat-management.md §0a.2). */
@@ -284,7 +293,7 @@ export function releaseAdapters(options) {
             return { ok: false, message: "The plane's database isn't here, so the candidate can't be proven." };
         const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
         try {
-            return deploymentGate(new Store(db), { runId, evidenceRoot: join(dirname(database), "evidence"), now: (options.now ?? (() => new Date()))() });
+            return deploymentGate(new Store(db), { runId, evidenceRoot: join(dirname(database), "evidence"), now: (options.now ?? (() => new Date()))(), releaseFlow: true });
         }
         catch (error) {
             return { ok: false, message: `The candidate can't be proven: ${error.message}` };
@@ -360,7 +369,7 @@ export function releaseAdapters(options) {
             rmSync(extracted.dir, { recursive: true, force: true });
         }
     };
-    const release = storeReleaseAdapter(() => openStore(database), store => store.close(), options.now ?? (() => new Date()));
+    const release = storeReleaseAdapter(() => openStore(database), store => store.close(), options.now ?? (() => new Date()), undefined, { observe: sha => observeCi(sha), mergeBase: (base, sha) => readMergeBase(run, ciGh, releaseRepo().slug, base, sha), evidenceRoot: join(dirname(database), "evidence") });
     return {
         ...(existsSync(database) ? { release } : {}),
         now: options.now ?? (() => new Date()),
@@ -559,12 +568,9 @@ export function releaseAdapters(options) {
                 }));
                 return prs.find(one => one.state === "open") ?? prs.filter(one => one.state === "merged").sort((a, b) => b.number - a.number)[0] ?? null;
             },
-            async checks(repo, sha) {
-                const out = await must(gh("api", "--paginate", `repos/${repo}/commits/${sha}/check-runs?per_page=100`, "--jq", ".check_runs[] | {id, name, status, conclusion, app: .app.slug}"), "gh api check-runs");
-                const runs = out.split("\n").filter(Boolean).map(line => object(JSON.parse(line)));
-                // Oldest first, so a rerun's attempt is the last one listed for its name.
-                return runs.sort((a, b) => Number(a["id"]) - Number(b["id"])).map((one) => ({ name: String(one["name"]), status: String(one["status"]), conclusion: textOr(one["conclusion"]), app: textOr(one["app"]) }));
-            },
+            // Every attempt (filter=all), with its app, check suite and commit: the release judges each job by its latest attempt.
+            async checks(repo, sha) { return readCheckRuns(run, ciGh, repo, sha); },
+            async complete(repo, sha) { return readSuitesComplete(run, ciGh, repo, sha); },
             async merge(repo, pr, head, message) {
                 // The squash commit's message lists every commit that landed after the approval (release-once.md).
                 const merged = object(await ghJson("gh api pulls merge", "api", "-X", "PUT", `repos/${repo}/pulls/${pr}/merge`, "-f", "merge_method=squash", "-f", `sha=${head}`, ...(message === undefined ? [] : ["-f", `commit_message=${message}`])));
@@ -728,7 +734,10 @@ function personAnswerOf(value) {
  * 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 function storeReleaseAdapter(open, done, now, runner) {
+export function storeReleaseAdapter(open, done, now, runner, 
+/** Releases that approve themselves (auto-approve-green.md): the plane's own look at CI on a commit, and where the
+ * check receipts are kept. Absent: no automatic approval, every release asks a person. */
+auto) {
     const withStore = (body) => { const store = open(); try {
         return body(store);
     }
@@ -736,6 +745,7 @@ export function storeReleaseAdapter(open, done, now, runner) {
         done(store);
     } };
     return {
+        ...(auto === undefined ? {} : { auto: autoReleaseAdapter(withStore, now, auto) }),
         async authority(taskId) {
             return withStore(store => {
                 const found = releaseAuthorityOfTask(store, taskId);
@@ -777,3 +787,119 @@ export function storeReleaseAdapter(open, done, now, runner) {
         },
     };
 }
+/** The plane's automatic release approval through a store (release-auto.ts): what `toolroll release` asks. It hands the
+ * plane ids only; the plane reads CI itself (`observe`) right before it seals. */
+function autoReleaseAdapter(withStore, now, auto) {
+    return {
+        async setting(taskId) {
+            return withStore(store => { try {
+                const ref = store.lookupRef(taskId);
+                return ref?.repo != null && releaseAutoApproves(store, ref.repo);
+            }
+            catch {
+                return false;
+            } });
+        },
+        async authorizeCheck(input) {
+            // The comparison base for what the release changes: GitHub's own merge base of the candidate with the release's
+            // base branch (its signed terms), read by the plane — never a task branch or a build's recorded base.
+            const branch = withStore(store => store.getScope(input.taskId)?.releaseTerms?.base ?? null);
+            if (branch === null)
+                return { ok: false, why: "only a release task is approved automatically" };
+            let base;
+            try {
+                base = await auto.mergeBase(branch, input.candidate);
+            }
+            catch (error) {
+                return { ok: false, why: `GitHub couldn't say where ${input.candidate.slice(0, 7)} left ${branch} (${String(error?.message ?? error).slice(0, 160)})` };
+            }
+            return withStore(store => { const answer = authorizeAutoCheck(store, { ...input, base, now: now() }); return answer.ok ? { ok: true } : answer; });
+        },
+        async checking(taskId) {
+            return withStore(store => { const answer = autoReleaseApprovalOf(store, taskId, "auto-check"); return answer.ok ? { ok: true } : { ok: false, why: answer.why }; });
+        },
+        async approve(input) {
+            let ci = null, problem = "";
+            // A short network failure is asked again a few times; GitHub not answering is never a pass.
+            for (let attempt = 0; attempt < 3 && ci === null; attempt++) {
+                try {
+                    ci = await auto.observe(input.candidate);
+                }
+                catch (error) {
+                    problem = String(error?.message ?? error).slice(0, 200);
+                }
+            }
+            if (ci === null) {
+                const why = `GitHub CI on ${input.candidate.slice(0, 7)} couldn't be read (${problem})`;
+                withStore(store => giveUpAutoApproval(store, { taskId: input.taskId, why, now: now() }));
+                return { ok: false, why };
+            }
+            const observed = ci;
+            return withStore(store => sealAutoGreen(store, { ...input, ci: observed, evidenceRoot: auto.evidenceRoot, now: now() }));
+        },
+        async giveUp(taskId, why) { withStore(store => giveUpAutoApproval(store, { taskId, why, now: now() })); },
+        async checkFailed(taskId, why) { withStore(store => noteAutoCheckFailed(store, { taskId, why, now: now() })); },
+        async released(taskId, tag) { withStore(store => noteAutoRelease(store, { taskId, tag, now: now() })); },
+        async holdPublish(taskId, why) { withStore(store => holdAutoPublish(store, { taskId, why, now: now() })); },
+        async publishHeld(taskId) { return withStore(store => autoPublishHeld(store, taskId)); },
+    };
+}
+/** The environment every CI read runs gh with: no caller PATH, host, config folder or proxy override. */
+function ciEnv() {
+    const kept = Object.fromEntries(["HOME", "LANG", "LC_ALL", "TMPDIR", "USER", "LOGNAME", "GH_TOKEN", "GITHUB_TOKEN"].flatMap(name => process.env[name] === undefined ? [] : [[name, process.env[name]]]));
+    return { ...kept, PATH: "/usr/bin:/bin", GH_HOST: "github.com", GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1" };
+}
+/**
+ * Every check run GitHub holds for one commit — every attempt, not only the latest (`filter=all`; GitHub's default
+ * lists only the latest of each), every page — with its id, app, check suite and the commit it is filed under, oldest
+ * first. A row that doesn't parse stops the read: a partial answer is never taken for the whole.
+ */
+export async function readCheckRuns(run, gh, repo, sha) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[0-9a-f]{40}$/.test(sha))
+        throw new Error("not a repository and commit GitHub can be asked about");
+    const out = await must(run(gh, ["api", "--hostname", "github.com", "--paginate", `repos/${repo}/commits/${sha}/check-runs?filter=all&per_page=100`,
+        "--jq", ".check_runs[] | {id, name, status, conclusion, app: .app.slug, suite: .check_suite.id, head: .head_sha}"], { cwd: "/", env: ciEnv() }), "gh api check-runs");
+    // Which workflow each check suite is a run of (GitHub's workflow-run API): a newer run of a workflow supersedes its
+    // older runs on this commit (release.ts prChecksVerdict).
+    const flows = await must(run(gh, ["api", "--hostname", "github.com", "--paginate", `repos/${repo}/actions/runs?head_sha=${sha}&per_page=100`,
+        "--jq", ".workflow_runs[] | {suite: .check_suite_id, workflow: .workflow_id, head: .head_sha}"], { cwd: "/", env: ciEnv() }), "gh api actions/runs");
+    const workflowOf = new Map();
+    for (const line of flows.split("\n").filter(Boolean)) {
+        const one = object(JSON.parse(line));
+        if (!Number.isSafeInteger(one["suite"]) || !Number.isSafeInteger(one["workflow"]) || one["head"] !== sha)
+            throw new Error("GitHub answered a workflow run this can't read");
+        const known = workflowOf.get(Number(one["suite"]));
+        if (known !== undefined && known !== Number(one["workflow"]))
+            throw new Error("GitHub named two workflows for one check suite");
+        workflowOf.set(Number(one["suite"]), Number(one["workflow"]));
+    }
+    const runs = out.split("\n").filter(Boolean).map(line => {
+        const one = object(JSON.parse(line));
+        if (!Number.isSafeInteger(one["id"]) || typeof one["name"] !== "string" || typeof one["status"] !== "string")
+            throw new Error("GitHub answered a check run this can't read");
+        const suite = Number.isSafeInteger(one["suite"]) ? Number(one["suite"]) : null;
+        return { id: Number(one["id"]), name: one["name"], status: one["status"], conclusion: textOr(one["conclusion"]), app: textOr(one["app"]),
+            suite, head: textOr(one["head"]), workflow: suite === null ? null : workflowOf.get(suite) ?? null };
+    });
+    if (new Set(runs.map(one => one.id)).size !== runs.length)
+        throw new Error("GitHub answered the same check run twice");
+    return runs.sort((a, b) => a.id - b.id);
+}
+/** GitHub lists check runs from at most the latest 1000 check suites of a commit: the history is whole only below that. */
+export const CHECK_SUITE_CEILING = 1000;
+export async function readSuitesComplete(run, gh, repo, sha) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[0-9a-f]{40}$/.test(sha))
+        return false;
+    const out = await run(gh, ["api", "--hostname", "github.com", `repos/${repo}/commits/${sha}/check-suites?per_page=1`, "--jq", ".total_count"], { cwd: "/", env: ciEnv() });
+    const total = Number(out.stdout.trim());
+    return out.code === 0 && out.stdout.trim() !== "" && Number.isSafeInteger(total) && total >= 0 && total < CHECK_SUITE_CEILING;
+}
+/** GitHub's merge base of `sha` with branch `base` (the compare API), read by the plane. */
+export async function readMergeBase(run, gh, repo, base, sha) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[0-9a-f]{40}$/.test(sha) || !/^[A-Za-z0-9._/-]+$/.test(base) || base.includes(".."))
+        throw new Error("not a repository, branch and commit GitHub can be asked about");
+    const out = (await must(run(gh, ["api", "--hostname", "github.com", `repos/${repo}/compare/${base}...${sha}`, "--jq", ".merge_base_commit.sha"], { cwd: "/", env: ciEnv() }), "gh api compare")).trim();
+    if (!/^[0-9a-f]{40}$/.test(out))
+        throw new Error("GitHub named no merge base");
+    return out;
+}

package/dist/release-authority.d.ts

@@ -116,3 +116,49 @@ export declare function outstandingReleaseOperations(store: Store, authority: nu
  * superseded by the new one — but never while one of its operations is unsettled, and never once its merge started.
  */
 export declare function releaseSealProblem(store: Store, terms: ReleaseTerms): string | null;
+/** "Release approval: Ask me / Approve automatically when checks pass": a project setting, newest choice wins (a ledger
+ * row each); `ask` by default. Turning it on is a person's credential act (a password typed now); off is one click. */
+export declare const RELEASE_APPROVAL_ACTION = "release approval changed";
+/** The plane's record of what proved an automatic seal (`auto-check` or `auto-green`): one ledger row per seal, its
+ * id named by the seal's `mode_digest` as `auto:<id>`. Only release-auto.ts writes it. */
+export declare const AUTO_EVIDENCE_ACTION = "release auto-approved";
+/** An automatic seal taken back for good (the setting lowered, a refusal): its outcome names the seal's `auto:<id>`, and
+ * that evidence never stands again. */
+export declare const AUTO_WITHDRAWN_ACTION = "release auto-approval withdrawn";
+export type ReleaseApprovalSetting = {
+    auto: boolean;
+    setBy: string | null;
+    at: string | null;
+};
+/** Read live at every use. Fail closed: a missing, unreadable or unknown row is `ask`. */
+export declare function releaseApprovalSetting(store: Store, repo: string): ReleaseApprovalSetting;
+export declare const releaseAutoApproves: (store: Store, repo: string) => boolean;
+/** SQL: the newest setting row for `repo` (an SQL expression) says `auto`. */
+export declare const releaseAutoSql: (repo: string) => string;
+/**
+ * SQL over a `task_scope` alias: its automatic seal (`auto-check` or `auto-green`) stands on its own evidence row — this
+ * task, this kind, `mode_digest = 'auto:<row id>'`, the row's digest and candidate exactly the sealed ones — on a release
+ * task (a candidate and release terms signed in), while the project's setting is on. The approver's standing is read
+ * beside it (approval-authority.ts).
+ */
+export declare const autoSealSql: (scope: string, repo: string) => string;
+/** The evidence an automatic seal names, read strictly; null when the row is missing or doesn't match the seal. */
+export type AutoEvidence = {
+    id: number;
+    kind: "auto-check" | "auto-green";
+    taskId: string;
+    digest: string;
+    candidate: string;
+    at: string;
+    by: string;
+    /** auto-green only: the build whose check passed, its receipt, the CI check runs observed green and when, the base. */
+    run: number | null;
+    receipt: string | null;
+    ci: {
+        id: number;
+        name: string;
+    }[];
+    observedAt: string | null;
+    base: string | null;
+};
+export declare function autoEvidenceOf(store: Store, taskId: string, modeDigest: string | null | undefined, kind: "auto-check" | "auto-green"): AutoEvidence | null;