toolroll 0.9.103 → 0.9.105

package/dist/release-adapters.js

@@ -1,9 +1,3 @@
-/**
- * The world `toolroll release` acts on (release.ts): the gate checkout through git, GitHub through the signed-in `gh`,
- * the npm registry over HTTPS, the installed Toolroll through its own CLI (`--json`) and launchd definitions, and the
- * 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 { execFile, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
@@ -14,7 +8,6 @@ import { fileURLToPath } from "node:url";
 import { parse as parseYaml } from "yaml";
 import { sleep } from "./sleep.js";
 import { callLabel, readOnlyCall, retryCall, retryingExec, writeWithRecheck } from "./release-net.js";
-// Loaded on first use, like the store: a static import prints Node's SQLite warning before the CLI can quiet it.
 const sqlite = () => createRequire(import.meta.url)("node:sqlite");
 import { PROTECTION_MINIMUM_CHECKS, PROTECTION_REPORT_ONLY_CHECKS } from "./release.js";
 import { activeUpdateWork } from "./desktop-update-gate.js";
@@ -43,22 +36,18 @@ import { extractCommit } from "./commit-extract.js";
 import { teardownGit, refusal as gitRefusal } from "./teardown-git.js";
 import { RELEASE_REMOTE, releaseConfigProblem, releaseGitArgs, releaseGitEnv, releaseRemote, releaseTools } from "./release-git.js";
 export { RELEASE_PATH, RELEASE_REMOTE, releaseConfigProblem, releaseGitArgs, releaseGitEnv, releaseRemote, releaseTools } from "./release-git.js";
-/** A child process, its output kept whole; a missing program or a time limit is exit 127 or 124, never a throw. */
 export const exec = (command, args, options = {}) => new Promise(done => {
     const child = execFile(command, [...args], { cwd: options.cwd, env: options.env ?? process.env, timeout: options.timeoutMs ?? 120_000, maxBuffer: 64 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
         const failure = error;
         const code = failure === null ? 0 : failure.code === "ENOENT" ? 127 : failure.killed === true ? 124 : typeof failure.code === "number" ? failure.code : 1;
         done({ code, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
     });
-    // `input`: written on the child's stdin, then closed (a secret that must never ride in argv).
     child.stdin?.on("error", () => { });
     if (options.input !== undefined)
         child.stdin?.end(options.input);
     else
         child.stdin?.end();
 });
-/** Without NODE_OPTIONS, which a test runner or debugger may have left for this process. */
-/** This runtime's own CLI (dist/bin.js beside this module) when it has one; from source, `toolroll` as installed. */
 const ownCli = () => {
     const bin = join(dirname(fileURLToPath(import.meta.url)), "bin.js");
     return existsSync(bin) ? [process.execPath, bin] : ["toolroll"];
@@ -68,7 +57,6 @@ const cleanEnv = (extra = {}) => {
     delete env["NODE_OPTIONS"];
     return env;
 };
-/** A failed call, in the words every release stop uses: what, its exit code and the last lines it printed. */
 const failed = (result, what) => new Error(`${what} failed (exit ${result.code}): ${(result.stderr || result.stdout).trim().split("\n").slice(-3).join(" ")}`);
 const must = async (run, what) => {
     const result = await run;
@@ -76,12 +64,10 @@ const must = async (run, what) => {
         throw failed(result, what);
     return result.stdout;
 };
-/** owner/name from an https or ssh GitHub remote. */
 export function githubSlug(url) {
     const match = /github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(url.trim());
     return match === null ? null : `${match[1]}/${match[2]}`;
 }
-/** The runtime (a `dist` folder, resolved) each launchd service of Toolroll runs: its definition names `<dist>/cli.js`. */
 export function serviceRuntimes(agents = join(homedir(), "Library", "LaunchAgents")) {
     let names = [];
     try {
@@ -98,7 +84,6 @@ export function serviceRuntimes(agents = join(homedir(), "Library", "LaunchAgent
     }
     return [...new Set(found)];
 }
-/** The runtime each CLI name resolves to on PATH: the `dist` folder its `bin.js` sits in, or null when not linked there. */
 export function cliRuntimes(path = process.env["PATH"] ?? "", names = ["toolroll", "standing-orders"]) {
     return names.map(name => {
         for (const dir of path.split(delimiter).filter(Boolean)) {
@@ -119,7 +104,6 @@ catch {
 } };
 const object = (value) => (value !== null && typeof value === "object" && !Array.isArray(value) ? value : {});
 const textOr = (value) => (typeof value === "string" && value !== "" ? value : null);
-/** `task show --json`, read as the release needs it. */
 export function gateStateOf(answer, accounts = []) {
     if (answer["ok"] !== true)
         return { exists: false, candidate: null, scopeDigest: null, approval: null, result: null, failed: null, completion: null };
@@ -134,11 +118,9 @@ export function gateStateOf(answer, accounts = []) {
     const completion = object(assignment["completion"]);
     const approvedAt = textOr(scope["approvedAt"]), approvedBy = textOr(scope["approvedBy"]), approvedDigest = textOr(scope["approvedDigest"]);
     const account = accounts.map(object).find(one => one["name"] === approvedBy);
-    // A newer finished build than the result, with no result of its own, failed before its check could seal one.
     const failed = newest !== undefined && newest["finishedAt"] != null && newest["outcome"] !== "built" && newest["outcome"] !== "no-change" && Number(newest["id"]) !== resultRun
         ? `run ${String(newest["id"])} ended ${String(newest["outcome"] ?? "without an outcome")}` : null;
     const worktree = runs.find(run => run["id"] === resultRun)?.["worktree"];
-    // Queued again or still building past the result shown (a regate): that result is the one before the rerun.
     const state = object(answer["task"])["state"];
     const pending = resultRun !== null && (state === "queued" || state === "running" || (newest !== undefined && newest["finishedAt"] == null && Number(newest["id"]) > resultRun));
     return {
@@ -161,14 +143,12 @@ export function gateStateOf(answer, accounts = []) {
         completion: textOr(completion["digest"]) === null ? null : { actor: String(completion["actor"]), at: String(completion["at"]), digest: String(completion["digest"]) },
     };
 }
-/** Every process on this machine (`ps`): pid and full command line. */
 export function processes() {
     const listed = spawnSync("/bin/ps", ["-axww", "-o", "pid=,command="], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
     if (listed.status !== 0)
         throw new Error(`ps failed: ${listed.stderr.trim()}`);
     return listed.stdout.split("\n").map(line => /^\s*(\d+)\s+(.*)$/.exec(line)).filter(match => match !== null).map(match => ({ pid: Number(match[1]), command: match[2] }));
 }
-/** The final line of deploy-browser's output that is a JSON object: its `runtime` (a dist folder), when it has one. */
 export function deployedRuntime(stdout) {
     const last = stdout.trim().split("\n").reverse().find(line => line.startsWith("{"));
     try {
@@ -179,8 +159,6 @@ export function deployedRuntime(stdout) {
         return null;
     }
 }
-/** What a deployment's stage says about the update pause: its id and phase when the journal is before the swap and the
- * live database's pause is that deployment's. `owner` reads the live pause's owner. */
 export function stageGate(stage, owner) {
     let journal;
     try {
@@ -192,7 +170,6 @@ export function stageGate(stage, owner) {
     const id = textOr(journal["id"]), phase = textOr(journal["phase"]);
     return id !== null && phase !== null && BEFORE_SWAP.includes(phase) && owner() === id ? { id, phase } : null;
 }
-/** The recorded repository for a gate checkout, from the plane's database; throws in plain words when there is none. */
 export function recordedReleaseRepo(database, checkout) {
     const real = (path) => { try {
         return realpathSync(path);
@@ -234,7 +211,6 @@ export function recordedReleaseRepo(database, checkout) {
     }
     return { checkout: at, gitDir, remote, ...parsed };
 }
-/** How many times, and how far apart, a merged branch's deletion is looked for after the push lost a race. */
 export const BRANCH_GONE_LOOKS = 5;
 export const BRANCH_GONE_PAUSE_MS = 2_000;
 export function releaseAdapters(options) {
@@ -247,18 +223,11 @@ export function releaseAdapters(options) {
     const tools = options.tools ?? releaseTools();
     const gitEnv = releaseGitEnv();
     const say = options.say ?? ((line) => { process.stdout.write(`${line}\n`); });
-    /** A short network failure on the way to GitHub (release-net.ts): reads are asked again for up to ~3 minutes; a
-     * write never is, unless GitHub says it didn't happen (writeWithRecheck). */
     const net = { say, sleep: options.sleep ?? sleep, ...(options.now === undefined ? {} : { now: options.now }) };
     const reads = retryingExec(run, net);
-    // Never a PATH lookup or the checkout's Git config: gh by its absolute path, from a neutral folder, naming the repo.
-    // Reads ride out a short network failure; anything that isn't provably a read passes straight through (readOnlyCall).
     const gh = (...args) => reads(tools.gh, args, { cwd: "/", env: gitEnv });
-    /** A write by gh, never retried by itself. */
     const ghWrite = (remainingMs, ...args) => run(tools.gh, args, { cwd: "/", env: gitEnv, timeoutMs: Math.min(120_000, remainingMs) });
     const ghJson = async (what, ...args) => JSON.parse(await must(gh(...args), what));
-    // The build running this release, never a PATH lookup: until the link step, `toolroll` on PATH is still the previous
-    // build, which refuses a database the deployment migrated, so a release resumed after its deploy couldn't read its task.
     const cli = options.cli ?? ownCli();
     const toolroll = async (...args) => {
         const result = await run(cli[0], [...cli.slice(1), ...args, "--json"], { env: cleanEnv(), timeoutMs: 120_000 });
@@ -270,8 +239,6 @@ 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();
@@ -281,18 +248,11 @@ export function releaseAdapters(options) {
     };
     const database = options.database ?? databasePath(process.env, homedir());
     let recorded = options.releaseRepo ?? null;
-    /** The recorded repository, read once (chat-management.md §0a.2). */
     const releaseRepo = () => recorded ??= recordedReleaseRepo(database, checkout);
-    /**
-     * The coordinator's one way to run Git (§0a.2): on the recorded Git directory, hardened, with an allowlisted
-     * environment and the absolute Git. Every attempt uses the shared runner's private view: the audited config is
-     * the exact copy Git reads, so a build cannot redirect a command after its config was checked.
-     */
     const git = async (...args) => {
         const repo = releaseRepo();
         const full = [...releaseGitArgs(repo, tools), ...args];
         const stop = (why) => new Error(`Toolroll won't run Git in ${repo.checkout} for a release: ${why}. Remove it from the project's Git config, then rerun.`);
-        // The checkout's config is read again right before EVERY attempt, a retried one included (checked at the moment of use).
         const once = async (remainingMs = 120_000) => {
             const now = () => (options.now ?? (() => new Date()))().getTime();
             const started = now();
@@ -305,8 +265,6 @@ export function releaseAdapters(options) {
                     throw stop(`its Git config sets ${setting}, which a release doesn't run with (it could run a command, or change where Git connects or what it sends)`);
             };
             if (options.releaseRepo === undefined) {
-                // The shared runner pins both Git directories and freezes config/info in the plane's fenced view folder.
-                // Its private paths replace releaseGitArgs' first two directory flags; the recorded remote stays fixed.
                 const viewed = teardownGit(async (_command, argv, runOptions) => {
                     const timeoutMs = left();
                     if (timeoutMs <= 0)
@@ -323,7 +281,6 @@ export function releaseAdapters(options) {
                     throw stop(why);
                 return result;
             }
-            // Injected repository/exec fixtures have no on-disk checkout, but exercise the same config policy per attempt.
             if (left() <= 0)
                 return { code: 124, stdout: "", stderr: "the network retry budget ran out" };
             const listing = await run(tools.git, [`--git-dir=${repo.gitDir}`, "--no-optional-locks", "config", "--list", "--no-includes", "--show-scope", "-z"], { cwd: "/", env: gitEnv, timeoutMs: left() });
@@ -332,10 +289,8 @@ export function releaseAdapters(options) {
                 return { code: 124, stdout: "", stderr: "the network retry budget ran out" };
             return run(tools.git, full, { cwd: repo.checkout, env: gitEnv, timeoutMs: left() });
         };
-        // ls-remote and fetch ride out a short network failure; a push or a local command is never retried (readOnlyCall).
         return readOnlyCall(tools.git, full) === null ? once() : retryCall(once, callLabel(tools.git, full), net);
     };
-    /** The remote every fetch, look and push names: the recorded URL, defined only on the command line. */
     const remoteUrl = () => RELEASE_REMOTE;
     const liveOwner = () => {
         if (!existsSync(database))
@@ -349,13 +304,10 @@ export function releaseAdapters(options) {
         }
     };
     const tail = (result) => (result.stderr || result.stdout).trim().split("\n").slice(-4).join(" ") || `exit ${result.code}`;
-    /** A deployment that stopped: in words, with the pause it left when that pause is before the swap. */
     const stopped = (stage, message) => {
         const gate = stageGate(stage, liveOwner);
         return gate === null ? { ok: false, message } : { ok: false, message, gate };
     };
-    /** The deployment gate in this runtime (deploy-gate.ts): a person's approval, the passing check, the exact completed
-     * result. Its answer names the approved commit and the project it belongs to, from the plane's own records. */
     const proveCandidate = (runId) => {
         if (!existsSync(database))
             return { ok: false, message: "The plane's database isn't here, so the candidate can't be proven." };
@@ -370,7 +322,6 @@ export function releaseAdapters(options) {
             db.close();
         }
     };
-    /** The run's recorded commit and project, for recovery (which needs no approval). */
     const recordedCommit = (runId) => {
         if (!existsSync(database))
             return null;
@@ -386,13 +337,6 @@ export function releaseAdapters(options) {
             db.close();
         }
     };
-    /**
-     * The approved commit, written by this runtime into a fresh folder it owns (commit-extract.ts): every regular file of
-     * that full SHA, read byte for byte from the PROJECT's own Git directory as Toolroll records it (realpath, a real
-     * directory — never the candidate worktree's `.git` pointer or anything in that worktree), with no filter, attribute,
-     * replacement object, lazy fetch, hook or outside config, and no symlink or submodule. The deployment script runs
-     * from here, so nothing changed, flagged, swapped or untracked in the worktree, nor its Git pointer, changes what runs.
-     */
     const extractApproved = async (repo, head) => {
         let gitDir;
         try {
@@ -412,13 +356,11 @@ export function releaseAdapters(options) {
         }
         return { ok: true, dir, gitDir };
     };
-    /** The approved commit's own deployment script, from the pristine extraction; the worktree is only its --source. */
     const deployScript = async (worktree, stage, runId, commit, extra, input) => {
         const extracted = await extractApproved(commit.repo, commit.head);
         if (!extracted.ok)
             return { code: 1, stdout: "", stderr: extracted.message };
         try {
-            // The script node runs is the extraction's own regular file, by its real path inside the folder.
             let script;
             try {
                 script = realpathSync(join(extracted.dir, "scripts", "deploy-browser.mjs"));
@@ -440,22 +382,16 @@ export function releaseAdapters(options) {
     const release = storeReleaseAdapter(() => openStore(database), store => store.close(), options.now ?? (() => new Date()), undefined, { observe: sha => observeCi(sha), mergeBase: (base, sha) => readMergeBase(reads, ciGh, releaseRepo().slug, base, sha),
         upToDateRequired: () => readUpToDateRequired(reads, ciGh, releaseRepo().slug), evidenceRoot: join(dirname(database), "evidence"),
         macosCases: sha => macosCasesOf(run, ciGh, releaseRepo().slug, sha),
-        // A successful Actions job authenticates the job, not the candidate-writable JSON it uploads. Until the
-        // executor protects that reporting channel, production releases must take the person's approval road.
-        reportsProtected: false }, 
-    // A boundary's one bounded read of GitHub's nightly: plain exec, never the release's long retries (20 s in all).
-    githubReads(run, ciGh));
+        reportsProtected: false }, githubReads(run, ciGh));
     return {
         ...(existsSync(database) ? { release, progress: releaseProgressRecorder(() => openStore(database), store => store.close()) } : {}),
         now: options.now ?? (() => new Date()),
         sleep: options.sleep ?? sleep,
         say,
         repo: {
-            // The recorded owner/name, never the checkout's origin.
             async github() { return releaseRepo().slug; },
             async sync(branch) {
                 await must(git("fetch", "--quiet", "--no-tags", remoteUrl(), "+refs/heads/main:refs/remotes/origin/main"), "git fetch main");
-                // A merged branch may be gone from GitHub; its commit is already here.
                 await git("fetch", "--quiet", "--no-tags", remoteUrl(), `+refs/heads/${branch}:refs/remotes/origin/${branch}`);
                 const current = (await git("symbolic-ref", "--quiet", "--short", "HEAD")).stdout.trim();
                 if (current === "main") {
@@ -483,8 +419,6 @@ export function releaseAdapters(options) {
                 const pushed = await git("push", "--no-verify", `--force-with-lease=${ref}:${head}`, remoteUrl(), `:${ref}`);
                 if (pushed.code === 0)
                     return;
-                // GitHub may delete a merged branch itself between the look and the push; gone is what was wanted. Its refs can
-                // lag the deletion by a few seconds, so look a few times before calling it a failure.
                 for (let look = 0; look < BRANCH_GONE_LOOKS; look++) {
                     if (look > 0)
                         await pause(BRANCH_GONE_PAUSE_MS);
@@ -503,7 +437,6 @@ export function releaseAdapters(options) {
         toolroll: {
             async installed() { return { services: serviceRuntimes(), clis: cliRuntimes() }; },
             async runtimeCommit(runtime) {
-                // deploy-browser writes this beside node_modules, not in the package's own manifest (whose version can repeat).
                 try {
                     const candidate = object(JSON.parse(readFileSync(join(runtime, "..", "..", "..", "package.json"), "utf8")))["candidate"];
                     return typeof candidate === "string" && /^[0-9a-f]{40}$/.test(candidate) ? candidate : null;
@@ -540,7 +473,6 @@ export function releaseAdapters(options) {
             async busy() {
                 const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
                 try {
-                    // Match the deploy guard, including unfinished runs whose claim is gone. Keep one read snapshot.
                     db.exec("BEGIN");
                     const work = activeUpdateWork(db);
                     const tasks = db.prepare(`SELECT DISTINCT external_id FROM task_ref WHERE id IN (
@@ -556,15 +488,9 @@ export function releaseAdapters(options) {
                 }
             },
             async deploy({ run: runId, worktree, stage, operation }) {
-                // Approval policy §1.7: this runtime proves the candidate FIRST — a person approved it, its exact result passed
-                // the approved check and is complete, and the checkout is exactly that commit — before anything from the
-                // candidate's checkout runs. The candidate's own script never decides its own deployment.
                 const proven = proveCandidate(runId);
                 if (!proven.ok)
                     return stopped(stage, proven.message);
-                // The approved commit's own deployment, extracted by this runtime: drain, backup, rehearsal, swap, health. Its
-                // last JSON line names the runtime it installed; the CLI names are moved to it by the release's link step.
-                // The operation the coordinator reserved, adopted by the deploy run with its secret on stdin (never in argv).
                 const result = await deployScript(worktree, stage, runId, proven, ["--yes", ...(operation === undefined ? [] : ["--operation", operation.id])], operation?.secret);
                 const runtime = deployedRuntime(result.stdout);
                 if (result.code !== 0 || runtime === null)
@@ -572,16 +498,11 @@ export function releaseAdapters(options) {
                 return { ok: true, runtime };
             },
             async recoverDeploy({ run: runId, worktree, stage }) {
-                // Before prepare saves deployment.json, staging has not touched the service or admission gate.
                 if (!existsSync(join(stage, "deployment.json")))
                     return { ok: true };
-                // A deployment that outlived a killed release is still at work: recovering under it would race it.
                 const running = (options.processes ?? processes)().filter(one => one.command.includes("deploy-browser.mjs") && one.command.includes(stage));
                 if (running.length > 0)
                     return { ok: false, message: `the deployment is still running (process ${running.map(one => one.pid).join(", ")}); let it finish, then rerun` };
-                // The new service was started (the phase table's "forward" rows, deploy-phase.ts): the release resumes it
-                // forward with the deployment's own finish (health, both consoles, leases, then the pause lifted).
-                // Finishing deploys, so the candidate is proven first, as for a deploy.
                 const journalPhase = () => { try {
                     return object(JSON.parse(readFileSync(join(stage, "deployment.json"), "utf8")))["phase"];
                 }
@@ -600,10 +521,6 @@ export function releaseAdapters(options) {
                     }
                     else
                         why = proven.message;
-                    // Once the new service was recorded as started, a journal alone never rolls it back: the release stops here.
-                    // Still at "starting" (killed while waiting for the new service; finish only looks, and it did not find it
-                    // running): the deployment's own recovery puts the previous service back, and only when it proves the new
-                    // one gone. That needs no approval of the candidate, exactly as below.
                     if (journalPhase() !== "starting")
                         return stopped(stage, why);
                     const recorded = recordedCommit(runId);
@@ -614,14 +531,12 @@ export function releaseAdapters(options) {
                         return { ok: true };
                     return stopped(stage, `${why} The previous service was not put back either: ${tail(back)}`);
                 }
-                // Recovery needs no approval, but it runs only the recorded commit's own script, extracted by this runtime.
                 const recorded = recordedCommit(runId);
                 if (recorded === null)
                     return stopped(stage, `Run ${runId} names no commit to recover with.`);
                 const result = await deployScript(worktree, stage, runId, recorded, ["--phase", "recover"]);
                 if (result.code === 0)
                     return { ok: true };
-                // Killed while preparing, before it paused anything: nothing to undo (its journal is kept).
                 const journal = (() => { try {
                     return object(JSON.parse(readFileSync(join(stage, "deployment.json"), "utf8")));
                 }
@@ -633,7 +548,6 @@ export function releaseAdapters(options) {
                 return stopped(stage, `${tail(result)} (the deployment journal is at ${String(journal["phase"] ?? "an unreadable phase")}; ${join(stage, "deployment.json")})`);
             },
             async deploymentIdle(stage) {
-                // Whatever the stage: no deployment is running, and no update pause is held.
                 if ((options.processes ?? processes)().some(one => one.command.includes("deploy-browser.mjs")))
                     return false;
                 if (liveOwner() !== null)
@@ -641,10 +555,8 @@ export function releaseAdapters(options) {
                 if (stage === null)
                     return false;
                 const journalFile = join(stage, "deployment.json");
-                // Never prepared: staging touched neither the service nor the update pause.
                 if (!existsSync(journalFile))
                     return true;
-                // Its journal lock is free (nothing holds the journal), and it stopped where nothing changed, or finished.
                 try {
                     acquireDeploymentLock(journalFile, 0).release();
                 }
@@ -676,7 +588,6 @@ 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;
             },
-            // Every attempt (filter=all), with its app, check suite and commit: the release judges each job by its latest attempt.
             async checks(repo, sha, options) { return readCheckRuns(reads, ciGh, repo, sha, options); },
             async complete(repo, sha) { return readSuitesComplete(reads, ciGh, repo, sha); },
             async mainHead(repo) { return readMainHead(reads, ciGh, repo); },
@@ -684,9 +595,6 @@ export function releaseAdapters(options) {
             async updateBranch(repo, pr, expectedHead) { return updatePullRequestBranch(reads, ciGh, repo, pr, expectedHead); },
             async upToDateRequired(repo) { return readMainProtection(reads, ciGh, repo); },
             async merge(repo, pr, head, message) {
-                // The squash commit's message lists every commit that landed after the approval (release-once.md). Never asked
-                // again under stale approval/lease/CI checks: reconcile a lost answer, but another write needs a fresh
-                // coordinator pass through those guards. A PR still being open proves none of them.
                 return writeWithRecheck(`merging #${pr}`, { ...net, maxAttempts: 1 }, {
                     write: remaining => ghWrite(remaining, "api", "-X", "PUT", `repos/${repo}/pulls/${pr}/merge`, "-f", "merge_method=squash", "-f", `sha=${head}`, ...(message === undefined ? [] : ["-f", `commit_message=${message}`])),
                     accept: result => {
@@ -726,9 +634,6 @@ export function releaseAdapters(options) {
         homebrew: {
             repo: tap,
             async checked(head) {
-                // Only a workflow that runs on pull requests (or pushes) puts checks on the tap's change; apps that open a
-                // check suite and never run it don't count. Workflows are read as the change has them and as the tap's default
-                // branch has them (pull_request_target runs from there); a file this can't read counts as checking.
                 for (const ref of [head, await defaultBranch()]) {
                     const listed = await gh("api", `repos/${tap}/contents/.github/workflows?ref=${encodeURIComponent(ref)}`, "--jq", ".[] | select(.type == \"file\") | .path");
                     if (listed.code !== 0) {
@@ -749,7 +654,6 @@ export function releaseAdapters(options) {
                 return false;
             },
             async statuses(head) {
-                // The older commit-status API, which some CI reports through instead of checks; newest first, so reversed.
                 const out = await must(gh("api", "--paginate", `repos/${tap}/commits/${head}/statuses?per_page=100`, "--jq", ".[] | {context, state}"), "gh api statuses");
                 return out.split("\n").filter(Boolean).map(line => object(JSON.parse(line))).reverse().map((one) => {
                     const state = String(one["state"]);
@@ -761,11 +665,9 @@ export function releaseAdapters(options) {
                 const current = await formulaAt(branch);
                 if (current.text.includes(`-${version}.tgz`))
                     return { kind: "current" };
-                // Ordering (pipeline-speed.md, P1): a tap already on a later version is never moved back by an older release.
                 const named = formulaVersion(current.text);
                 if (named !== null && versionAfter(named, version))
                     return { kind: "newer", version: named };
-                // Only a change from the tap's own branch counts: a fork's pull request of the same branch name never does.
                 const open = (await ghJson("gh pr list", "pr", "list", "--repo", tap, "--head", brewBranch(version), "--state", "open", "--json", "number,headRefOid,headRepository,headRepositoryOwner,isCrossRepository"));
                 const own = open.filter(one => tapOwnHead(one, tap));
                 if (own.length > 1)
@@ -787,11 +689,9 @@ export function releaseAdapters(options) {
                     throw new Error("The tap current version is unreadable or newer; no downgrade was proposed.");
                 const next = bumpFormula(current.text, tarball, sha256);
                 const branch = brewBranch(version);
-                // A branch left by an earlier attempt is reused.
                 const made = await gh("api", "-X", "POST", `repos/${tap}/git/refs`, "-f", `ref=refs/heads/${branch}`, "-f", `sha=${baseSha}`);
                 if (made.code !== 0 && !/Reference already exists/.test(made.stderr + made.stdout))
                     throw new Error(`creating ${tap} ${branch}: ${made.stderr.trim()}`);
-                // A branch left by an earlier attempt starts again from the base (security scan): none of its history is kept.
                 if (made.code !== 0)
                     await must(gh("api", "-X", "PATCH", `repos/${tap}/git/refs/heads/${branch}`, "-f", `sha=${baseSha}`, "-F", "force=true"), `resetting ${tap} ${branch}`);
                 const onBranch = await formulaAt(branch);
@@ -803,12 +703,9 @@ export function releaseAdapters(options) {
                 return { pr: Number(opened["number"]), head: String(opened["headRefOid"]) };
             },
             async verified(pr, head, version) {
-                // The change at exactly `head` is the tap's own, and its formula is exactly today's formula with npm's published
-                // tarball and that tarball's own sha256: nothing else is ever merged.
                 const view = object(await ghJson("gh pr view", "pr", "view", String(pr), "--repo", tap, "--json", "number,headRefOid,headRefName,baseRefName,headRepository,headRepositoryOwner,isCrossRepository,state"));
                 const base = await defaultBranch();
                 const baseHead = String(object(object(await ghJson("gh api git/ref", "api", `repos/${tap}/git/ref/heads/${base}`))["object"])["sha"]);
-                // The whole change against the tap's default branch head: its merge base, its commits and every file it touches.
                 const compare = object(await ghJson("gh api compare", "api", `repos/${tap}/compare/${encodeURIComponent(baseHead)}...${encodeURIComponent(head)}`));
                 const tarball = `https://registry.npmjs.org/toolroll/-/toolroll-${version}.tgz`;
                 const response = await get(tarball, { signal: AbortSignal.timeout(60_000) });
@@ -835,7 +732,6 @@ export function releaseAdapters(options) {
             },
         },
     };
-    /** A tag's commit as GitHub answers now (an annotated tag: the commit it names), or null when there is no such tag. */
     async function readTag(repo, tag, bounded = net) {
         const read = (path) => retryingExec(run, bounded)(tools.gh, ["api", path], { cwd: "/", env: gitEnv });
         const result = await read(`repos/${repo}/git/ref/tags/${tag}`);
@@ -849,8 +745,6 @@ export function releaseAdapters(options) {
             return String(target["sha"]);
         return String(object(object(JSON.parse(await must(read(`repos/${repo}/git/tags/${String(target["sha"])}`), "gh api git/tags")))["object"])["sha"]);
     }
-    /** Whether a pull request is merged from exactly `head` (its merge commit), still open at `head` (not merged), or
-     * anything else — read after a merge's answer was lost. */
     async function pullMergedAt(repo, pr, head, base, bounded, message) {
         const read = async (path) => object(JSON.parse(await must(retryingExec(run, bounded)(tools.gh, ["api", path], { cwd: "/", env: gitEnv }), "gh api merge recovery")));
         const pull = await read(`repos/${repo}/pulls/${pr}`);
@@ -858,7 +752,6 @@ export function releaseAdapters(options) {
         if (at !== head || object(pull["base"])["ref"] !== base)
             return { state: "other", why: `#${pr} is no longer open at ${head.slice(0, 7)} into ${base}` };
         if (pull["merged"] === true && pull["state"] === "closed" && typeof commit === "string" && /^[0-9a-f]{40}$/.test(commit)) {
-            // Another caller may have merged it. Only the same squash result counts, never merely "merged=true".
             const source = await read(`repos/${repo}/git/commits/${head}`);
             const merged = await read(`repos/${repo}/git/commits/${commit}`);
             const tree = object(source["tree"])["sha"], parents = merged["parents"];
@@ -881,15 +774,8 @@ export function releaseAdapters(options) {
     }
 }
 const brewBranch = (version) => `toolroll-${version}`;
-/**
- * Why a tap change isn't exactly the formula bump this release proposed (security scan), or null when it is: the tap's
- * own open pull request number `pr` at exactly `head`, from its version branch into the default branch; compared with
- * the default branch's head it is one commit on top of exactly that head, changing exactly one file, the formula; and
- * the formula there is exactly today's with npm's published tarball and that tarball's own sha256.
- */
 export function tapChangeProblem(input) {
     const { tap, pr, head, version, view, compare } = input;
-    // State may have changed since the coordinator checked it. Judge the immutable base used for this comparison.
     if (input.baseVersion === null)
         return `${tap} current version cannot be read`;
     if (versionAfter(input.baseVersion, version))
@@ -911,7 +797,6 @@ export function tapChangeProblem(input) {
         return `${tap} #${pr}'s formula isn't npm's ${version} tarball with its sha256 ${input.sha256.slice(0, 12)}`;
     return null;
 }
-/** Whether a pull request's head is a branch of the tap itself (never a fork's). */
 export function tapOwnHead(pr, tap) {
     const [owner, name] = tap.split("/");
     const repo = pr["headRepository"], who = pr["headRepositoryOwner"];
@@ -920,12 +805,10 @@ export function tapOwnHead(pr, tap) {
     return pr["isCrossRepository"] === false && typeof repoName === "string" && typeof ownerLogin === "string"
         && repoName.toLowerCase() === (name ?? "").toLowerCase() && ownerLogin.toLowerCase() === (owner ?? "").toLowerCase();
 }
-/** The version a formula's tarball url names (`…/toolroll-<x.y.z>.tgz`), or null. */
 export function formulaVersion(text) {
     const found = /^\s*url "[^"]*-(\d+\.\d+\.\d+)\.tgz"/m.exec(text);
     return found === null ? null : found[1];
 }
-/** Whether version `a` comes after `b` (both x.y.z). */
 export function versionAfter(a, b) {
     const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
     for (let i = 0; i < 3; i++)
@@ -933,13 +816,7 @@ export function versionAfter(a, b) {
             return (pa[i] ?? 0) > (pb[i] ?? 0);
     return false;
 }
-/** The events that put checks on a change. */
 const CHANGE_EVENTS = new Set(["pull_request", "pull_request_target", "push", "merge_group"]);
-/**
- * Whether a workflow's triggers (its top-level `on:` as a name, a list or a map) include a change to the repository.
- * A file that doesn't parse, or whose triggers aren't one of those shapes, counts as running, so the release waits
- * rather than skipping checks it owes.
- */
 export function workflowRunsOnChange(text) {
     let parsed;
     try {
@@ -951,7 +828,6 @@ export function workflowRunsOnChange(text) {
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
         return true;
     const workflow = parsed;
-    // YAML 1.1 readers take a bare `on` for true; either key names the triggers.
     const on = "on" in workflow ? workflow["on"] : workflow["true"];
     const events = typeof on === "string" ? [on]
         : Array.isArray(on) ? on
@@ -961,13 +837,11 @@ export function workflowRunsOnChange(text) {
         return true;
     return events.some(one => CHANGE_EVENTS.has(one));
 }
-/** The formula with its first `url` and `sha256` replaced; anything else is left exactly as it was. */
 export function bumpFormula(text, url, sha256) {
     if (!/^\s*url "[^"]*"/m.test(text) || !/^\s*sha256 "[0-9a-f]{64}"/m.test(text))
         throw new Error("the formula has no url and sha256 lines to update");
     return text.replace(/^(\s*url ")[^"]*(")/m, `$1${url}$2`).replace(/^(\s*sha256 ")[0-9a-f]{64}(")/m, `$1${sha256}$2`);
 }
-/** The plane's person-approval answer from `task show --json`, read strictly: anything malformed is no person. */
 function personAnswerOf(value) {
     if (value === undefined)
         return {};
@@ -976,17 +850,7 @@ function personAnswerOf(value) {
         return { person: { ok: true, method: read["method"] } };
     return { person: { ok: false, why: typeof read["why"] === "string" ? read["why"] : "the plane's answer about who approved it can't be read" } };
 }
-/**
- * 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, 
-/** 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, 
-/** GitHub's nightly (nightly-github.ts): the plane's own gh reads for a boundary's one bounded read. Absent: nothing
- * is read at the boundary, and the stored debt still holds inside every reservation. */
-nightlyReads) {
+export function storeReleaseAdapter(open, done, now, runner, auto, nightlyReads) {
     const withStore = (body) => { const store = open(); try {
         return body(store);
     }
@@ -995,15 +859,12 @@ nightlyReads) {
     } };
     return {
         ...(auto === undefined ? {} : { auto: autoReleaseAdapter(withStore, now, auto) }),
-        // One-tap release approval (trusted-release-reports.md, slice A): ids and the coordinator's own readings only; the
-        // plane decides from its own records whether anything is written.
         ready: {
             async asked(taskId) { withStore(store => { noteReleaseReady(store, { taskId, now: now() }); }); },
             async ci(input) { withStore(store => { recordReleaseCi(store, { ...input, now: now() }); }); },
             async stopped(input) { withStore(store => { noteReleaseStopped(store, { ...input, now: now() }); }); },
             async verified(input) { withStore(store => { recordVerifiedRelease(store, { ...input, now: now() }); }); },
         },
-        // After a failed release check, and before a pass is taken: the plane's own classification (check-failure.ts).
         ...(auto === undefined ? {} : {
             async recheck(taskId) {
                 return withStore(store => {
@@ -1012,8 +873,6 @@ nightlyReads) {
                 });
             },
             async fencedCoverage(_taskId, run, candidate) {
-                // Today's road, read first and answered at once: a check that ran unsandboxed skips nothing for this reason. A run
-                // from before stamps (a release resumed across an update) is judged by the level its dispatch recorded.
                 const asked = withStore(store => {
                     if (store.runCheckAccess(run) === "unsandboxed")
                         return null;
@@ -1100,8 +959,6 @@ nightlyReads) {
         },
     };
 }
-/** 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) {
     const reportProblem = () => auto.reportsProtected === true ? null
         : "CI test reports aren't protected from candidate writes, so a person must approve this release";
@@ -1119,8 +976,6 @@ function autoReleaseAdapter(withStore, now, auto) {
             const problem = reportProblem();
             if (problem !== null)
                 return { ok: false, why: problem };
-            // 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" };
@@ -1146,7 +1001,6 @@ function autoReleaseAdapter(withStore, now, auto) {
                 return { ok: false, why: unprotected };
             }
             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);
@@ -1173,10 +1027,8 @@ function autoReleaseAdapter(withStore, now, auto) {
         async giveUp(taskId, why) { withStore(store => giveUpAutoApproval(store, { taskId, why, now: now() })); },
         async ciRunning(taskId, candidate) { withStore(store => noteCiRunning(store, { taskId, candidate, now: now() })); },
         async ciPassed(taskId, candidate, ask) {
-            // Reconcile the plane's record, not journal flags; without a pending row there is nothing to lift.
             if (!withStore(store => releaseCiHoldOf(store, taskId) !== null || releaseCiRunningOf(store, taskId) !== null))
                 return { ok: true };
-            // The plane reads CI itself; a short network failure is asked again a few times, and unreadable is never a pass.
             let ci = null, problem = "";
             for (let attempt = 0; attempt < 3 && ci === null; attempt++) {
                 try {
@@ -1197,31 +1049,19 @@ function autoReleaseAdapter(withStore, now, auto) {
         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, 
-/** A release tag (pipeline-speed.md, item 3): a push of exactly this tag binds its workflow file too. */
-options = {}) {
+export async function readCheckRuns(run, gh, repo, sha, options = {}) {
     if (options.tag !== undefined && !/^v\d+\.\d+\.\d+$/.test(options.tag))
         throw new Error("not a release tag");
     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, path: .path, head: .head_sha, event: .event, branch: .head_branch, bases: [(.pull_requests // [])[] | .base.ref], prs: [(.pull_requests // [])[] | {number, repo: .base.repo.url}]}"], { cwd: "/", env: ciEnv() }), "gh api actions/runs");
-    // A pull request's base can be edited after its runs: a run counts only if no pull request it belongs to ever had its
-    // base changed (GitHub's timeline), so a run made against another base can't later read as a run into main.
     const retargeted = new Map();
     const everRetargeted = async (pr) => {
         const known = retargeted.get(pr);
@@ -1239,7 +1079,6 @@ options = {}) {
         return changed;
     };
     const workflowOf = new Map();
-    // Each suite's workflow file: a required check counts only from the workflow that defines it (release.ts).
     const pathOf = new Map();
     for (const line of flows.split("\n").filter(Boolean)) {
         const one = object(JSON.parse(line));
@@ -1249,11 +1088,6 @@ options = {}) {
         if (known !== undefined && (known !== Number(one["workflow"]) || pathOf.get(Number(one["suite"])) !== one["path"]))
             throw new Error("GitHub named two workflows for one check suite");
         workflowOf.set(Number(one["suite"]), Number(one["workflow"]));
-        // Only a run on a pull request into main, or a push to main, binds its workflow file: a pull request into another
-        // branch reads that branch's workflow and join verifier, which the candidate may control (security scan of the
-        // join). Any other run keeps no path, so no required check counts from it.
-        // Each pull request the run belongs to must be this repository's own (a number from another repository names a
-        // different pull request here): any other refuses the run.
         const prs = (Array.isArray(one["prs"]) ? one["prs"] : []).map(pr => (pr !== null && typeof pr === "object" ? pr : {}));
         const ours = prs.length > 0 && prs.every(pr => Number.isSafeInteger(pr["number"]) && pr["repo"] === `https://api.github.com/repos/${repo}`);
         const untouched = one["event"] !== "pull_request" || (ours && !(await Promise.all(prs.map(pr => everRetargeted(Number(pr["number"]))))).some(Boolean));
@@ -1270,8 +1104,6 @@ options = {}) {
     });
     if (new Set(runs.map(one => one.id)).size !== runs.length)
         throw new Error("GitHub answered the same check run twice");
-    // Each unsuccessful GitHub Actions attempt: whether GitHub's own job record (a check run's id is its job's) shows it
-    // ending before any of the workflow's own steps ran. Only that ever counts as the runner's failure; unreadable is no.
     for (const one of runs) {
         if (one.app !== "github-actions" || one.status !== "completed" || one.conclusion === "success" || one.conclusion === "skipped" || one.conclusion === "neutral")
             continue;
@@ -1279,7 +1111,6 @@ options = {}) {
     }
     return runs.sort((a, b) => a.id - b.id);
 }
-/** GitHub's job record for one check run (its job), read strictly: null when it can't be read whole. */
 export async function readJobBeforeTests(run, gh, repo, id) {
     if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !Number.isSafeInteger(id) || id <= 0)
         return null;
@@ -1307,12 +1138,6 @@ export async function readJobBeforeTests(run, gh, repo, id) {
     return failedBeforeTests({ id, status: String(job["status"]), conclusion: textOr(job["conclusion"]),
         steps: steps.map(one => ({ number: Number(one["number"]), name: String(one["name"]), status: String(one["status"]), conclusion: textOr(one["conclusion"]) })) });
 }
-/**
- * GitHub's REST API as GitHub's nightly reads it (nightly-github.ts): GET only, github.com only, a repository path, the
- * plane's own gh with the allowlisted environment, each call bounded by its caller's deadline. A background read rides
- * out a short network failure (release-net.ts, within that call's own share of the deadline); a boundary's read is
- * plain exec. Never an answer that isn't GitHub's whole JSON.
- */
 export function githubReads(run, gh, options = {}) {
     return async (path, timeoutMs) => {
         if (!/^repos\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_./?&=%-]+$/.test(path) || timeoutMs <= 0)
@@ -1335,7 +1160,6 @@ export function githubReads(run, gh, options = {}) {
         }
     };
 }
-/** 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))
@@ -1344,7 +1168,6 @@ export async function readSuitesComplete(run, gh, repo, sha) {
     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");
@@ -1353,10 +1176,6 @@ export async function readMergeBase(run, gh, repo, base, sha) {
         throw new Error("GitHub named no merge base");
     return out;
 }
-/**
- * Main's head as GitHub has it now (eval-harness review 1, finding 4): read by the plane's own gh from GitHub's API,
- * never from a ref in a checkout a build can write.
- */
 export async function readMainHead(run, gh, repo, branch = "main") {
     if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[A-Za-z0-9._/-]+$/.test(branch) || branch.includes(".."))
         throw new Error("not a repository and branch GitHub can be asked about");
@@ -1366,14 +1185,12 @@ export async function readMainHead(run, gh, repo, branch = "main") {
         throw new Error(`GitHub named no commit for ${branch}`);
     return match[1];
 }
-/** GitHub's own "Update branch", with its expected head: a push that got there first refuses. */
 export async function updatePullRequestBranch(run, gh, repo, pr, expectedHead) {
     if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !Number.isSafeInteger(pr) || pr < 1 || !/^[0-9a-f]{40}$/.test(expectedHead))
         return { ok: false, why: "not a pull request GitHub can be asked to update" };
     const ran = await run(gh, ["api", "--hostname", "github.com", "--method", "PUT", `repos/${repo}/pulls/${pr}/update-branch`, "-f", `expected_head_sha=${expectedHead}`], { cwd: "/", env: ciEnv() });
     return ran.code === 0 ? { ok: true } : { ok: false, why: (ran.stderr.trim().split("\n")[0] ?? "").slice(0, 200) || `gh exited ${ran.code}` };
 }
-/** Whether `sha` already holds `ancestor` (GitHub's compare: `sha` is not behind it), as GitHub answers now. */
 export async function readContains(run, gh, repo, sha, ancestor) {
     if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[0-9a-f]{40}$/.test(sha) || !/^[0-9a-f]{40}$/.test(ancestor))
         throw new Error("not a repository and commits GitHub can be asked about");
@@ -1389,24 +1206,11 @@ export async function readContains(run, gh, repo, sha, ancestor) {
         throw new Error("GitHub's comparison couldn't be read");
     return answer[1] === 0 && (answer[0] === "ahead" || answer[0] === "identical");
 }
-/**
- * Main's protection, judged for the principal that merges (eval-harness review 2, finding 1; review 1, finding 4): the
- * plane's own gh, which merges as the same account. A layer holds only when it requires branches to be up to date, names
- * a non-empty set of required checks covering PROTECTION_MINIMUM_CHECKS, bound to GitHub Actions (app 15368), and
- * can't be bypassed by that account:
- * classic protection with "Do not allow bypassing the above settings" (`enforce_admins`); an active ruleset whose
- * bypass list reads whole, names no role, team or organization admin, and says this account never bypasses it. Read
- * only — Toolroll never changes a repository's settings. A layer that can't be read never holds. When no layer holds
- * and one couldn't be read (gh failed for a reason other than "not protected", or its answer didn't parse), the read
- * throws ProtectionUnreadable: "couldn't read GitHub" is never reported as "protection doesn't hold", and never as
- * holding. Null only for a repository or branch name GitHub can't be asked about.
- */
 export async function readMainProtection(run, gh, repo, branch = "main") {
     if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[A-Za-z0-9._/-]+$/.test(branch) || branch.includes(".."))
         return null;
     const missing = [];
     const held = [];
-    /** What couldn't be read at all, and the words gh gave. */
     const unread = [];
     const words = (out) => (out.stderr || out.stdout).trim().split("\n").slice(-1)[0]?.slice(0, 160) || `exit ${out.code}`;
     const judge = (where, strict, checks, bound, bypass) => {
@@ -1444,14 +1248,13 @@ export async function readMainProtection(run, gh, repo, branch = "main") {
     };
     const actionsChecks = (list, appKey) => Array.isArray(list)
         ? list.flatMap(one => { const check = object(one); return check[appKey] === 15368 && typeof check["context"] === "string" ? [check["context"]] : []; }) : [];
-    // Classic branch protection, read whole. Context names alone allow an arbitrary writer to supply their status.
     const classic = await run(gh, ["api", "--hostname", "github.com", `repos/${repo}/branches/${branch}/protection`], { cwd: "/", env: ciEnv() });
     if (classic.code === 0) {
         let answer = null;
         try {
             answer = JSON.parse(classic.stdout);
         }
-        catch { /* unreadable below */ }
+        catch { }
         const p = object(answer), checks = p["required_status_checks"];
         if (answer === null || typeof answer !== "object" || Array.isArray(answer))
             unread.push("classic protection (its answer didn't parse)");
@@ -1460,7 +1263,6 @@ export async function readMainProtection(run, gh, repo, branch = "main") {
         else {
             const rsc = object(checks), contexts = names(rsc["contexts"] ?? [], ""), apps = names(rsc["checks"] ?? [], "context");
             const admins = p["enforce_admins"];
-            // GitHub answered, but without the settings this judges: read, and not holding.
             if (contexts === null || apps === null || typeof rsc["strict"] !== "boolean" || admins === undefined || admins === null || typeof object(admins)["enabled"] !== "boolean")
                 missing.push("classic protection: GitHub's answer doesn't say which checks it requires or whether administrators can bypass it");
             else {
@@ -1470,7 +1272,6 @@ export async function readMainProtection(run, gh, repo, branch = "main") {
     }
     else if (!notProtected(classic))
         unread.push(`classic protection (${words(classic)})`);
-    // Rulesets: every active rule requiring status checks on the branch, then its ruleset's enforcement and bypass list.
     const rules = await run(gh, ["api", "--hostname", "github.com", "--paginate", `repos/${repo}/rules/branches/${branch}`,
         "--jq", ".[] | select(.type == \"required_status_checks\") | @json"], { cwd: "/", env: ciEnv() });
     if (rules.code !== 0)
@@ -1516,7 +1317,6 @@ export async function readMainProtection(run, gh, repo, branch = "main") {
             const actors = set["bypass_actors"];
             if (!Array.isArray(actors))
                 bypass.push("its bypass list couldn't be read");
-            // Only a deploy key never merges as this account; a role, team, app or organization admin might.
             else if (actors.some(one => object(one)["actor_type"] !== "DeployKey"))
                 bypass.push("its bypass list names a role, team, app or organization admin");
             judge(where, params["strict_required_status_checks_policy"] === true, checks, actionsChecks(params["required_status_checks"], "integration_id"), bypass);
@@ -1532,7 +1332,6 @@ export async function readMainProtection(run, gh, repo, branch = "main") {
         missing.push("main has no branch protection or ruleset requiring status checks");
     return { effective: false, missing, notYetRequired: [] };
 }
-/** Main's protection couldn't be read from GitHub (after the network retries): not "doesn't hold", and never "holds". */
 export class ProtectionUnreadable extends Error {
     unread;
     constructor(unread) {
@@ -1540,7 +1339,6 @@ export class ProtectionUnreadable extends Error {
         this.unread = unread;
     }
 }
-/** Whether main's protection holds, as a yes/no (release-auto.ts sealAutoGreen): null when it can't be read. */
 export async function readUpToDateRequired(run, gh, repo, branch = "main") {
     let protection;
     try {
@@ -1553,11 +1351,9 @@ export async function readUpToDateRequired(run, gh, repo, branch = "main") {
     }
     return protection === null ? null : protection.effective;
 }
-/** Whether a workflow run is the push of exactly this release tag (its workflow file is the tagged commit's own, on main). */
 function tagTriggered(run, tag) {
     return tag !== undefined && run["event"] === "push" && run["branch"] === tag;
 }
-/** Whether a workflow run was triggered on main: a push to main, or a pull request whose every base is main. */
 function mainTriggered(run) {
     const bases = Array.isArray(run["bases"]) ? run["bases"] : [];
     if (run["event"] === "push")
@@ -1566,8 +1362,6 @@ function mainTriggered(run) {
         return bases.length > 0 && bases.every(base => base === "main");
     return false;
 }
-/** The release's step record (store.ts release_step, v146) through a store opened for each entry: a failure to open or
- * write is swallowed, so recording never stops or changes the release. */
 export function releaseProgressRecorder(open, done) {
     return entry => {
         let store = null;
@@ -1575,19 +1369,17 @@ export function releaseProgressRecorder(open, done) {
             store = open();
             recordReleaseStep(store, entry);
         }
-        catch { /* best effort: the release goes on */ }
+        catch { }
         finally {
             if (store !== null) {
                 try {
                     done(store);
                 }
-                catch { /* best effort */ }
+                catch { }
             }
         }
     };
 }
-/** The macOS CI's cases on exactly `sha`: the newest pull-request run of ci.yml there, each shard's newest attempt. Null
- * when they can't all be read. The folder is this function's own, removed before it returns. */
 async function macosCasesOf(run, gh, slug, sha) {
     const folder = mkdtempSync(join(tmpdir(), "so-macos-ci-"));
     try {