toolroll 0.9.75 → 0.9.76

package/dist/operate.js

@@ -224,6 +224,8 @@ import { scout as scoutTask } from "./scout.js";
 import { profileDigestOf } from "./scope.js";
 import { PROVIDER_KEY_ENV, clearProviderKey, keyStatus, readAuthMode, readAuthModeStrict, readProviderKey, saveProviderKey, setAuthMode, verifyProviderKey, verdictWords } from "./keys.js";
 import { run, terminateLiveProviders, run as execRun } from "./exec.js";
+import { hardenedGit } from "./teardown-git.js";
+import { noticeGitIncidents } from "./git-incident.js";
 import { containmentNotice, containmentStatus, currentContainment, describeContainment, resolveContainment } from "./containment.js";
 import { readPulls } from "./pulls.js";
 import { startMaintenance } from "./maintenance.js";
@@ -2220,7 +2222,7 @@ function flowIoOf(context, pool, git, base) {
         replies: { fetch: context.flowTriggerIo?.fetch ?? fetch, dir: context.flowTriggerIo?.dir ?? dir,
             ...(context.flowTriggerIo?.mail === undefined ? {} : { mail: context.flowTriggerIo.mail }) },
         // Check and update steps run outside a model: an approved command in a fresh copy of the card's work, or a comment on the issue it came from.
-        steps: { gh: context.flowStepIo?.gh ?? run, git: context.flowStepIo?.git ?? git, shell: context.flowStepIo?.shell ?? run, fetch: context.flowStepIo?.fetch ?? fetch,
+        steps: { gh: context.flowStepIo?.gh ?? run, git: context.flowStepIo?.git ?? (git === run ? hardenedGit(run) : git), shell: context.flowStepIo?.shell ?? run, fetch: context.flowStepIo?.fetch ?? fetch,
             dir: context.flowStepIo?.dir ?? dir, scratch: context.flowStepIo?.scratch ?? join(pool, "flow-checks"), base,
             ...(context.evidenceRoot === undefined ? {} : { evidenceRoot: context.evidenceRoot }) },
         ...(context.evidenceRoot === undefined ? {} : { evidenceRoot: context.evidenceRoot }),
@@ -3905,6 +3907,8 @@ async function decideCommand(positional, flags, context) {
  */
 async function startConsole(options) {
     const { context } = options;
+    // A git incident (teardown-git.ts) raises an attention notification in this console's outbox.
+    noticeGitIncidents(context.store, context.clock);
     const server = createDecisionServer({
         store: context.store,
         // Sign-in, integration and model checks, and the tidy-ups no page visit does (docs/plans/get-side-effects.md).
@@ -6041,6 +6045,8 @@ let staleStatusesRepaired = false;
 async function runWatchLoop(args) {
     const { context, flags, runner, token, repo, progress } = args;
     const { store } = context;
+    // A git incident in this worker's builds raises an attention notification in its outbox (once per store).
+    noticeGitIncidents(store, context.clock);
     const tickEveryMs = Number(text(flags, "tick-every") ?? 60_000);
     const bridgeEveryMs = Number(text(flags, "bridge-every") ?? 45_000);
     const reconcileEveryMs = Number(text(flags, "reconcile-every") ?? 5 * 60_000);

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,5 +1,6 @@
 /** 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 { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync } from 'node:fs';
@@ -52,7 +53,8 @@ const git = (repo, args, seen) => {
     if (known !== undefined)
         return known;
     // Bounded, and no hook or fsmonitor program: it also runs from the console's background pass.
-    const out = execFileSync('git', ['--no-optional-locks', '-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();
+    // 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;
 };
@@ -542,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 {
@@ -552,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/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/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;

package/dist/release-authority.js

@@ -133,3 +133,67 @@ export function releaseSealProblem(store, terms) {
     }
     return null;
 }
+// ------------------------------------------------------------------ automatic release approval (auto-approve-green.md)
+/** "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 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 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 const AUTO_WITHDRAWN_ACTION = "release auto-approval withdrawn";
+/** Read live at every use. Fail closed: a missing, unreadable or unknown row is `ask`. */
+export function releaseApprovalSetting(store, repo) {
+    let row;
+    try {
+        row = store.handle.prepare("SELECT actor, at, outcome FROM action_ledger WHERE repo = ? AND task_id IS NULL AND action = ? ORDER BY id DESC LIMIT 1").get(repo, RELEASE_APPROVAL_ACTION);
+    }
+    catch {
+        return { auto: false, setBy: null, at: null };
+    }
+    if (row === undefined || (row["outcome"] !== "auto" && row["outcome"] !== "ask"))
+        return { auto: false, setBy: null, at: null };
+    return { auto: row["outcome"] === "auto", setBy: String(row["actor"]), at: String(row["at"]) };
+}
+export const releaseAutoApproves = (store, repo) => releaseApprovalSetting(store, repo).auto;
+/** SQL: the newest setting row for `repo` (an SQL expression) says `auto`. */
+export const releaseAutoSql = (repo) => `COALESCE((SELECT ra_set.outcome = 'auto' FROM action_ledger ra_set WHERE ra_set.repo = ${repo} AND ra_set.task_id IS NULL
+      AND ra_set.action = '${RELEASE_APPROVAL_ACTION}' ORDER BY ra_set.id DESC LIMIT 1), 0)`;
+/**
+ * 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 const autoSealSql = (scope, repo) => `(${scope}.candidate IS NOT NULL AND ${scope}.release_terms_json IS NOT NULL AND ${releaseAutoSql(repo)}
+    AND EXISTS (SELECT 1 FROM action_ledger ae WHERE ae.task_id = ${scope}.task_id AND ae.action = '${AUTO_EVIDENCE_ACTION}'
+        AND ae.outcome = ${scope}.approval_basis AND ${scope}.mode_digest = 'auto:' || ae.id AND json_valid(ae.detail)
+        AND json_extract(ae.detail, '$.v') = 1 AND json_extract(ae.detail, '$.digest') = ${scope}.approved_digest
+        AND json_extract(ae.detail, '$.candidate') = ${scope}.candidate)
+    AND NOT EXISTS (SELECT 1 FROM action_ledger aw WHERE aw.task_id = ${scope}.task_id AND aw.action = '${AUTO_WITHDRAWN_ACTION}' AND aw.outcome = ${scope}.mode_digest))`;
+export function autoEvidenceOf(store, taskId, modeDigest, kind) {
+    const match = /^auto:([1-9][0-9]{0,15})$/.exec(modeDigest ?? "");
+    if (match === null)
+        return null;
+    const row = store.handle.prepare("SELECT id, at, actor, task_id, outcome, detail FROM action_ledger WHERE id = ? AND action = ?").get(Number(match[1]), AUTO_EVIDENCE_ACTION);
+    if (row === undefined || row["task_id"] !== taskId || row["outcome"] !== kind)
+        return null;
+    if (store.handle.prepare("SELECT 1 AS hit FROM action_ledger WHERE task_id = ? AND action = ? AND outcome = ?").get(taskId, AUTO_WITHDRAWN_ACTION, `auto:${match[1]}`) !== undefined)
+        return null;
+    let detail;
+    try {
+        detail = JSON.parse(String(row["detail"]));
+    }
+    catch {
+        return null;
+    }
+    if (detail === null || typeof detail !== "object" || detail["v"] !== 1 || typeof detail["digest"] !== "string" || typeof detail["candidate"] !== "string")
+        return null;
+    const ci = Array.isArray(detail["ci"]) ? detail["ci"].filter((one) => one !== null && typeof one === "object" && Number.isSafeInteger(one.id) && typeof one.name === "string") : [];
+    const textOr = (value) => typeof value === "string" ? value : null;
+    return {
+        id: Number(row["id"]), kind, taskId, digest: detail["digest"], candidate: detail["candidate"], at: String(row["at"]), by: String(detail["by"] ?? row["actor"]),
+        run: Number.isSafeInteger(detail["run"]) ? Number(detail["run"]) : null, receipt: textOr(detail["receipt"]), ci, observedAt: textOr(detail["observedAt"]), base: textOr(detail["base"]),
+    };
+}