toolroll 0.9.104 → 0.9.105

package/dist/nightly-github.js

@@ -1,26 +1,3 @@
-/**
- * GitHub's nightly as release debt (docs/plans/evals-nightly.md, part A). The plane reads every Nightly run and every
- * attempt on main itself, through its own gh, and a lane that failed its tests becomes debt.
- *
- * - Opting in (`toolroll release nightly --github`) is a person's step, proved now: it records the GitHub repository
- *   from the project's recorded remote and seeds one stable lane per required check (release.ts REQUIRED_PR_CHECKS).
- *   A rename needs a person's alias; a lane retires only when no required check names it, by a person.
- * - Reading keeps a paging cursor (at most NIGHTLY_PAGES_PER_READ pages a read, resumed on the next) and a watch list
- *   of every counted run created in the last 30 days (GitHub's re-run horizon), each re-read for new attempts; a run
- *   that hasn't finished stays watched whatever its age. A run counts only from `.github/workflows/nightly.yml`
- *   exactly, in the project's own repository, on main, by schedule or dispatch, at a commit on main's first-parent
- *   history as the plane read it (nightly-check.ts trustedMainOf). Every attempt's completed jobs are recorded once.
- * - A lane's failure is a test failure unless GitHub's own step records show the runner failed (github-jobs.ts):
- *   before the lane's own steps, or, for an aggregate lane failing only at "Every shard passed", a positively
- *   established chain of readable shard failures in the same attempt, each before its tests. The coverage verifier
- *   ("Every shard ran the whole suite") failing is always a test failure. A cause that can't be read is a failure.
- * - A failure clears only when a different counted nightly run, started after the failure completed, passes the same
- *   lane on a commit that contains the failed one. Nothing read later — a cancellation, a missing job, an unreadable
- *   page, a newer attempt — ever removes a recorded failure.
- *
- * Trust: a lane's conclusion is GitHub's record of the job, not independent evidence (the tests are the repository's
- * code). It only ever adds holds, and never trusts more than the required-checks gate already does.
- */
 import { authenticateApprover, personProof } from "./scope.js";
 import { verifiedFirstParentAncestry } from "./commit-extract.js";
 import { projectGitDir } from "./check-report.js";
@@ -30,34 +7,22 @@ import { REQUIRED_PR_CHECKS, REQUIRED_PR_CHECKS_WORKFLOW } from "./release.js";
 import { releaseRemote } from "./release-git.js";
 import { TRUSTED_MAIN_ACTION, releaseAuthorityOfTask, trustedRemoteIdentity } from "./store.js";
 export { GITHUB_NIGHTLY_ON };
-/** The one workflow file whose runs count: exactly this path, never one with an `@` suffix or another folder's. */
 export const NIGHTLY_WORKFLOW_PATH = ".github/workflows/nightly.yml";
-/** GitHub's re-run horizon: a counted run is read again for new attempts for this long. */
 export const NIGHTLY_WATCH_MS = 30 * 24 * 60 * 60_000;
-/** Listing never goes further back than this: no run older than it can still be unfinished. */
 export const NIGHTLY_LIST_HORIZON_MS = 40 * 24 * 60 * 60_000;
-/** Pages of runs one read lists at most; a longer backlog resumes on the next read. */
 export const NIGHTLY_PAGES_PER_READ = 10;
 const PAGE = 100;
-/** GitHub answers at most this many runs to one filtered listing. */
 const LISTING_CAP = 1000;
-/** A boundary's one bounded read (deploy, merge, pre-tag), and the background read's overall deadline. */
 export const NIGHTLY_BOUNDARY_READ_MS = 20_000;
 export const NIGHTLY_BACKGROUND_READ_MS = 60_000;
-/** How often the watch loop reads each opted-in project's nightly. */
 export const NIGHTLY_BACKGROUND_EVERY_MS = 30 * 60_000;
-/** One call never waits longer than this, inside the read's deadline. */
 const CALL_MS = 15_000;
-/** How far back main's first-parent history is walked. */
 const MAIN_WALK = 20_000;
 const SHA = /^[0-9a-f]{40}$/;
-/** The job-name prefix GitHub gives a lane of each called workflow inside nightly.yml (its job names "nightly" and
- * "nightly floor"). */
 const LANE_PREFIX = {
     ".github/workflows/ci.yml": "nightly / ",
     ".github/workflows/release-candidate.yml": "nightly floor / ",
 };
-/** An aggregate lane: the join of a sharded unit suite. */
 const AGGREGATE = /^node (\d+) · (ubuntu|macos)-latest$/;
 export const SHARDS_PASSED_STEP = "Every shard passed";
 export const SHARDS_COVERED_STEP = "Every shard ran the whole suite";
@@ -69,8 +34,6 @@ const isoOf = (value) => {
     return Number.isFinite(at) ? new Date(at).toISOString() : null;
 };
 const positive = (value) => Number.isSafeInteger(value) && value > 0;
-// ---- opting in, lanes and aliases ----------------------------------------------------------------------------------
-/** Whether a project opted in, as the plane recorded a person's step: the newest such ledger row, read strictly. */
 export function githubNightlyOf(store, repo) {
     const row = store.handle.prepare("SELECT detail FROM action_ledger WHERE repo = ? AND action = ? ORDER BY id DESC LIMIT 1").get(repo, GITHUB_NIGHTLY_ON);
     if (row === undefined)
@@ -86,14 +49,10 @@ export function githubNightlyOf(store, repo) {
         return null;
     }
 }
-/** Every project that ever opted in (a broken or superseded record still counts here: its debt still holds). */
 export function githubNightlyRepos(store) {
     return store.handle.prepare("SELECT DISTINCT repo FROM action_ledger WHERE action = ? AND repo IS NOT NULL").all(GITHUB_NIGHTLY_ON).map(row => String(row["repo"]));
 }
-/** A lane's stable id: its workflow file and the required check's name when it was seeded. */
 export const laneIdOf = (workflow, name) => `${workflow.replace(/^\.github\/workflows\//, "")}:${name}`;
-/** One lane per required check whose name no lane (by its name or an alias) answers to yet. A retired lane whose name
- * is required again opens again. */
 export function seedLanes(store, repo, now) {
     for (const name of REQUIRED_PR_CHECKS) {
         const workflow = REQUIRED_PR_CHECKS_WORKFLOW[name];
@@ -104,8 +63,6 @@ export function seedLanes(store, repo, now) {
             .run(repo, laneIdOf(workflow, name), workflow, name, now.toISOString());
     }
 }
-/** The live lane a job of `workflow` named `name` belongs to: a person's alias first (the newest for that name), then
- * the lane seeded under it. Never a guess: anything else is no lane. */
 export function resolveLane(store, repo, workflow, name) {
     const aliased = store.handle.prepare(`SELECT a.lane_id FROM nightly_lane_alias a JOIN nightly_lane l ON l.repo = a.repo AND l.lane_id = a.lane_id
       WHERE a.repo = ? AND a.name = ? AND l.workflow = ? AND l.retired_at IS NULL ORDER BY a.id DESC LIMIT 1`).get(repo, name, workflow);
@@ -114,13 +71,11 @@ export function resolveLane(store, repo, workflow, name) {
     const own = store.handle.prepare("SELECT lane_id FROM nightly_lane WHERE repo = ? AND workflow = ? AND display_name = ? AND retired_at IS NULL").get(repo, workflow, name);
     return own === undefined ? null : String(own["lane_id"]);
 }
-/** Every name a lane answers to: its seeded name and each alias. */
 function laneNames(store, repo, laneId) {
     const lane = store.handle.prepare("SELECT display_name FROM nightly_lane WHERE repo = ? AND lane_id = ?").get(repo, laneId);
     const aliases = store.handle.prepare("SELECT name FROM nightly_lane_alias WHERE repo = ? AND lane_id = ? ORDER BY id").all(repo, laneId).map(row => String(row["name"]));
     return [...new Set([...(lane === undefined ? [] : [String(lane["display_name"])]), ...aliases])];
 }
-/** The name a lane is shown by: its newest alias, else the name it was seeded under. */
 export function laneName(store, repo, laneId) {
     const alias = store.handle.prepare("SELECT name FROM nightly_lane_alias WHERE repo = ? AND lane_id = ? ORDER BY id DESC LIMIT 1").get(repo, laneId);
     if (alias !== undefined)
@@ -128,23 +83,17 @@ export function laneName(store, repo, laneId) {
     const lane = store.handle.prepare("SELECT display_name FROM nightly_lane WHERE repo = ? AND lane_id = ?").get(repo, laneId);
     return lane === undefined ? laneId : String(lane["display_name"]);
 }
-/** A person proved now — called INSIDE the mutation's own transaction (Codex rounds 1 and 2, finding 7): the password
- * is checked, and the approver's standing and access read, under the same lock as the write, so nothing (a
- * revocation, a credential rotation, an access change) can land between the proof and the change. */
 function provePerson(store, repo, as, token, what) {
     const proved = authenticateApprover(store, as, token, repo);
     if (!proved.ok || !personProof(proved.method))
         return { ok: false, message: `Only an approver of this project, proved as a person, ${what}.` };
     return { ok: true, by: as, proof: proved.method };
 }
-/** `toolroll release nightly --github`: a person turns GitHub's nightly into release debt for this project. The
- * repository is the project's recorded remote's, never the checkout's. */
 export function optInGithubNightly(store, input, now) {
     return store.transact(() => {
         const proved = provePerson(store, input.repo, input.as, input.token, "turns on GitHub's nightly");
         if (!proved.ok)
             return proved;
-        // The recorded remote as it stands inside this transaction.
         const identity = trustedRemoteIdentity(store, input.repo);
         const remote = identity === null ? null : releaseRemote(identity.url);
         if (identity === null || remote === null)
@@ -157,7 +106,6 @@ export function optInGithubNightly(store, input, now) {
         return { ok: true, slug: remote.slug, lanes };
     });
 }
-/** `--lane-alias <old-id> <new name>`: a person says a renamed job is the same lane. Open debt goes with the lane. */
 export function aliasNightlyLane(store, input, now) {
     const name = input.name.trim();
     if (name === "" || name.length > 200 || /[\u0000-\u001f\u007f]/.test(name))
@@ -169,8 +117,6 @@ export function aliasNightlyLane(store, input, now) {
         const lane = store.handle.prepare("SELECT workflow, retired_at FROM nightly_lane WHERE repo = ? AND lane_id = ?").get(input.repo, input.laneId);
         if (lane === undefined || lane["retired_at"] !== null)
             return { ok: false, message: `No live lane ${input.laneId} in this project.` };
-        // Only a name no other lane answers to: never one another live lane resolves (whatever its debt), nor a required
-        // check's name that another lane owns, so a rename can't re-route a live lane's results onto this one.
         const workflow = String(lane["workflow"]);
         const other = resolveLane(store, input.repo, workflow, name);
         if (other !== null && other !== input.laneId)
@@ -183,8 +129,6 @@ export function aliasNightlyLane(store, input, now) {
         return { ok: true };
     });
 }
-/** `--lane-retire <lane-id>`: a person retires a lane no required check names any more; its open debt closes,
- * recorded as theirs. */
 export function retireNightlyLane(store, input, now) {
     return store.transact(() => {
         const proved = provePerson(store, input.repo, input.as, input.token, "retires a nightly lane");
@@ -233,22 +177,16 @@ function jobOf(value) {
         startedAt: isoOf(one["started_at"]), completedAt: isoOf(one["completed_at"]), headSha: one["head_sha"], runId: Number(one["run_id"]),
         runAttempt: positive(one["run_attempt"]) ? Number(one["run_attempt"]) : null, steps };
 }
-/** Whether a run is one of the project's own nightly runs on main (everything but main's history, checked apart). */
 export function nightlyRunBinds(run, slug) {
     return run.path === NIGHTLY_WORKFLOW_PATH && run.repository === slug && run.headRepository === slug && run.headBranch === "main"
         && (run.event === "schedule" || run.event === "workflow_dispatch") && SHA.test(run.headSha);
 }
-/** A lane job's workflow and its name inside that workflow, from its name in the nightly ("nightly / node 24 · …"). */
 function laneJobName(name) {
     for (const [workflow, prefix] of Object.entries(LANE_PREFIX))
         if (name.startsWith(prefix))
             return { workflow, name: name.slice(prefix.length) };
     return null;
 }
-/**
- * Why a completed lane job ended as it did, from GitHub's own job and step records in the same attempt
- * (evals-nightly.md, "Cause of a failure"). Fails closed: anything not positively the runner's is a test failure.
- */
 export function causeOf(job, attempt) {
     if (job.conclusion === "success")
         return "passed";
@@ -263,12 +201,9 @@ export function causeOf(job, attempt) {
     const aggregate = lane === null ? null : AGGREGATE.exec(lane.name);
     if (lane === null || aggregate === null)
         return "test-failure";
-    // The coverage verifier failing is always the tests' (it can fail with every shard green: a file that ran nowhere).
     const failedSteps = job.steps.filter(step => step.conclusion !== null && step.conclusion !== "success" && step.conclusion !== "skipped");
     if (failedSteps.length !== 1 || failedSteps[0].name !== SHARDS_PASSED_STEP || failedSteps[0].conclusion !== "failure")
         return "test-failure";
-    // Only "Every shard passed" failed: the runner's only on a positively established, non-empty chain — every failed
-    // shard of the same attempt readable and ended before its tests.
     const prefix = LANE_PREFIX[lane.workflow];
     const shard = new RegExp(`^node ${aggregate[1]} · ${aggregate[2] === "macos" ? "macos " : ""}shard \\d+/\\d+$`);
     const shards = attempt.filter(one => one.name.startsWith(prefix) && shard.test(one.name.slice(prefix.length)));
@@ -298,7 +233,6 @@ function cursorOf(store, repo) {
 function saveCursor(store, repo, cursor) {
     store.handle.prepare("INSERT INTO github_nightly_cursor (repo, page_cursor) VALUES (?, ?) ON CONFLICT (repo) DO UPDATE SET page_cursor = excluded.page_cursor").run(repo, JSON.stringify(cursor));
 }
-/** Why the project's nightly can't be read now (not opted in, or its remote changed since), or its repository. */
 function readableSlug(store, repo) {
     const on = githubNightlyOf(store, repo);
     if (on === null)
@@ -308,11 +242,6 @@ function readableSlug(store, repo) {
         return { ok: false, why: "the project's recorded remote changed since GitHub's nightly was turned on; turn it on again" };
     return { ok: true, slug: on.slug };
 }
-/**
- * One read of the project's GitHub nightly within `budgetMs`: list runs from the cursor, re-read the watch list (new
- * and unfinished runs first, then the oldest-checked), record every completed lane job, open and clear failures. A
- * failed call stops where it is; what was recorded stays, and the cursor never moves past a page it couldn't read.
- */
 export async function readGithubNightly(store, repo, deps, budgetMs) {
     const started = deps.now();
     const deadline = started.getTime() + budgetMs;
@@ -334,7 +263,6 @@ export async function readGithubNightly(store, repo, deps, budgetMs) {
             return { ok: false, why: String(error?.message ?? error).slice(0, 200) };
         }
     };
-    // Local history work (main's first-parent walks) is bounded by the same budget on the wall clock.
     const wall = Date.now() + budgetMs;
     let problem = null;
     const listing = await listRuns(store, repo, slug, get, deps.now);
@@ -345,8 +273,6 @@ export async function readGithubNightly(store, repo, deps, budgetMs) {
         problem = watched.why;
     const settled = settleGithubNightly(store, repo, deps, deps.now(), wall);
     const complete = listing.ok && listing.complete && watched.ok && watched.complete && settled.complete;
-    // Partial progress is never a whole read (Codex round 1, finding 5): what is still unresolved is said, and the last
-    // whole read's time stays as it was.
     const unresolved = problem ?? (complete ? null : watched.ok && watched.unresolved !== null ? watched.unresolved : settled.unresolved ?? "some runs are still to be read");
     noteRead(store, repo, unresolved, deps.now());
     return problem === null ? { ok: true, listed: listing.listed, checked: watched.checked, complete } : { ok: false, why: problem };
@@ -356,8 +282,6 @@ function noteRead(store, repo, why, now) {
     ON CONFLICT (repo) DO UPDATE SET last_ok_at = COALESCE(excluded.last_ok_at, last_ok_at), last_why = excluded.last_why`)
         .run(repo, JSON.stringify(EMPTY_CURSOR), why === null ? now.toISOString() : null, why === null ? null : why.slice(0, 300));
 }
-/** List nightly.yml's runs on main from the cursor, at most NIGHTLY_PAGES_PER_READ pages, putting every run that binds
- * on the watch list page by page. A page that can't be read whole stops here, the cursor before it. */
 async function listRuns(store, repo, slug, get, now) {
     const cursor = cursorOf(store, repo);
     const filter = cursor.scan?.below ?? null;
@@ -409,7 +333,6 @@ async function listRuns(store, repo, slug, get, now) {
     }
     return { ok: true, listed, complete: false };
 }
-/** Read one run by id, strictly. */
 export async function readRun(get, slug, id) {
     const got = await get(`repos/${slug}/actions/runs/${id}`);
     if (!got.ok)
@@ -417,8 +340,6 @@ export async function readRun(get, slug, id) {
     const run = runOf(got.body);
     return run !== null && run.id === id ? run : null;
 }
-/** Every job of one exact attempt of one run, every page, each GitHub's record of that run, attempt and commit. Null
- * when any page can't be read whole. */
 export async function readAttemptJobs(get, slug, run, attempt, sha) {
     const all = [];
     let total = null;
@@ -445,11 +366,7 @@ export async function readAttemptJobs(get, slug, run, attempt, sha) {
         return null;
     return all;
 }
-/** Re-read every watched run within the budget (never-checked first, then unfinished, then the oldest-checked): new
- * attempts' jobs are recorded; a run leaves once it is 30 days old, finished and fully read. */
 async function revisitWatchList(store, repo, slug, get, deps, outOfTime, wall) {
-    // Never-checked first, then strictly the oldest-checked (Codex round 1, finding 4: unfinished runs never starve a
-    // finished one whose rerun is waiting to be seen).
     const rows = store.handle.prepare(`SELECT gh_run, created_at, attempts_read, finished FROM github_nightly_watch WHERE repo = ?
     ORDER BY last_checked_at IS NOT NULL, last_checked_at, gh_run`).all(repo);
     let problem = null, checked = 0, complete = true, unresolved = null;
@@ -470,14 +387,11 @@ async function revisitWatchList(store, repo, slug, get, deps, outOfTime, wall) {
             continue;
         }
         checked++;
-        // A run that doesn't bind never counts; one not on main's history (as the plane read main) never counts either.
         if (!nightlyRunBinds(first, slug)) {
             drop();
             continue;
         }
         const old = deps.now().getTime() - Date.parse(first.createdAt) > NIGHTLY_WATCH_MS;
-        // "No" only from a read of main made after the run was created, and only for a finished run; anything less certain
-        // keeps the run watched (never dropped on a stale read of main: its failure would never be recorded).
         const onMain = deps.onMain(first.headSha, first.createdAt, wall);
         if (onMain === "no" && first.status === "completed") {
             drop();
@@ -504,13 +418,11 @@ async function revisitWatchList(store, repo, slug, get, deps, outOfTime, wall) {
                 break;
             }
             recordAttempt(store, repo, { run: id, attempt, sha: first.headSha, createdAt: first.createdAt, jobs }, deps.now());
-            // An earlier attempt than the newest is over: GitHub re-runs only a finished run.
             if (attempt < first.runAttempt)
                 read = attempt;
         }
         let finished = false;
         if (whole) {
-            // Read again: an attempt or status that changed mid-read is read whole next time; what was recorded stays.
             const again = await readRun(get, slug, id);
             if (again !== null && again.runAttempt === first.runAttempt && again.status === first.status && first.status === "completed") {
                 read = first.runAttempt;
@@ -531,7 +443,6 @@ async function revisitWatchList(store, repo, slug, get, deps, outOfTime, wall) {
     }
     return problem === null ? { ok: true, checked, complete, unresolved } : { ok: false, why: problem, checked };
 }
-/** Record one attempt's completed lane jobs once each, and open a failure for each test failure. */
 function recordAttempt(store, repo, attempt, now) {
     const at = now.toISOString();
     store.transact(() => {
@@ -547,15 +458,12 @@ function recordAttempt(store, repo, attempt, now) {
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(repo, laneId, attempt.run, attempt.createdAt, attempt.attempt, job.id, attempt.sha, job.startedAt, job.completedAt, job.conclusion, cause, at);
             if (cause !== "test-failure")
                 continue;
-            // No completion time on record: the failure counts as completed now, so only a pass started later clears it.
             const opened = store.handle.prepare(`INSERT OR IGNORE INTO nightly_lane_failure (repo, lane_id, gh_run, run_created_at, attempt, job_id, sha, completed_at, opened_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
                 .run(repo, laneId, attempt.run, attempt.createdAt, attempt.attempt, job.id, attempt.sha, job.completedAt ?? at, at);
-            // One attention notice per failure, when it is first recorded.
             if (Number(opened.changes) === 1) {
                 const lane = laneName(store, repo, laneId);
                 store.enqueueNotification({ dedupeKey: `github-nightly-failed:${Number(opened.lastInsertRowid)}`, kind: "github-nightly-failed", subject: "GitHub's nightly failed on main",
                     body: `Nightly checks failed: ${lane}, on main at ${attempt.sha.slice(0, 7)}. Releases wait until it passes again.`, pushClass: "attention",
-                    // The project it belongs to, so its people's chats may carry it (Codex round 1, finding 8).
                     source: { project: repo }, link: "/tasks?view=board" }, now);
             }
         }
@@ -567,12 +475,6 @@ export function openFailures(store, repo) {
         sha: String(row["sha"]), completedAt: String(row["completed_at"]), openedAt: String(row["opened_at"]),
     }));
 }
-/**
- * Clear each open failure that a later counted nightly run passed: a run created after the failed run (a rerun of an
- * older run never clears newer debt; Codex round 1, finding 2), the same lane, a job started after the failed one
- * completed, on a commit that contains the failed one. A re-run inside the same run never clears. Local history work
- * stops at `wall` (wall-clock ms); what is left is settled on a later read.
- */
 export function settleGithubNightly(store, repo, history, now, wall = Date.now() + NIGHTLY_BACKGROUND_READ_MS) {
     let cleared = 0, unresolved = null;
     const late = () => ({ cleared, complete: false, unresolved: unresolved ?? "settling the open failures ran out of time; the rest is settled on the next read" });
@@ -582,8 +484,6 @@ export function settleGithubNightly(store, repo, history, now, wall = Date.now()
         const passes = store.handle.prepare(`SELECT j.gh_run, j.attempt, j.job_id, j.sha FROM nightly_lane_job j JOIN nightly_lane_failure f ON f.id = ?
         WHERE j.repo = ? AND j.lane_id = ? AND j.cause = 'passed' AND j.gh_run <> f.gh_run AND j.run_created_at > f.run_created_at
           AND j.started_at IS NOT NULL AND j.started_at > f.completed_at ORDER BY j.started_at, j.id`).all(failure.id, repo, failure.laneId);
-        // Three-state, candidate by candidate: an unreadable or timed-out ancestry is never "doesn't contain" (Codex round 2,
-        // finding 5) — the failure stays open and the read says it is unresolved.
         let pass;
         for (const one of passes) {
             if (Date.now() >= wall)
@@ -611,11 +511,8 @@ export function settleGithubNightly(store, repo, history, now, wall = Date.now()
     }
     return unresolved === null ? { cleared, complete: true, unresolved: null } : { cleared, complete: false, unresolved };
 }
-/** Main's history as the plane read it from the project's recorded remote (nightly-check.ts trustedMainOf), from the
- * verified objects in the project's own Git store; never a ref a build could move. */
 export function mainHistoryOf(store, repo, now) {
     const main = trustedMainOf(store, repo, now, TRUSTED_MAIN_CLEAR_MS);
-    // When that read of main was made: the same ledger row trustedMainOf stands on.
     const readAt = main === null ? null : String(store.handle.prepare("SELECT at FROM action_ledger WHERE repo = ? AND action = ? ORDER BY id DESC LIMIT 1").get(repo, TRUSTED_MAIN_ACTION)?.["at"] ?? "");
     const gitDir = projectGitDir(repo);
     return {
@@ -624,9 +521,6 @@ export function mainHistoryOf(store, repo, now) {
                 return "unknown";
             if (sha === main)
                 return "yes";
-            // "No" only when proven: every commit back to the root read and verified without meeting it (Codex round 1,
-            // finding 1) — and only by a read of main made after the run was created. A missing or unreadable object, the
-            // walk's limit or the deadline is "unknown": the run stays watched.
             const walked = verifiedFirstParentAncestry(gitDir, main, sha, { deadline, max: MAIN_WALK });
             if (walked !== "no")
                 return walked;
@@ -639,10 +533,6 @@ export function mainHistoryOf(store, repo, now) {
         },
     };
 }
-/**
- * The watch loop's background read (operate.ts refreshGithubNightlies): each opted-in project at most every
- * NIGHTLY_BACKGROUND_EVERY_MS, claimed in the store so two processes don't both read, within one overall deadline.
- */
 export async function readGithubNightlies(store, deps, budgetMs = NIGHTLY_BACKGROUND_READ_MS) {
     const started = deps.now();
     const deadline = started.getTime() + budgetMs;
@@ -665,39 +555,26 @@ export async function readGithubNightlies(store, deps, budgetMs = NIGHTLY_BACKGR
     }
     return read;
 }
-/** How long a boundary's re-read of a candidate's exemption stands for the stored checks inside the reservation, the
- * deployment gate and the installed runtime's deploy check after it. */
 export const EXEMPTION_FRESH_MS = 10 * 60_000;
 const STAMP = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", hour: "2-digit", minute: "2-digit", hourCycle: "h23", timeZone: "UTC" });
-/** "Oct 30, 06:17 UTC". */
 export const nightlyStamp = (iso) => `${STAMP.format(new Date(iso))} UTC`;
-/** The words of a nightly hold: the first open failure, how many more, and the way out at this point. */
 export function nightlyDebtWords(store, held, phase, release) {
     const first = held[0];
     const more = held.length - 1;
     const lanes = `GitHub's nightly failed "${laneName(store, first.repo, first.laneId)}" on main at ${first.sha.slice(0, 7)} (${nightlyStamp(first.completedAt)})${more > 0 ? `, and ${more} more lane${more === 1 ? "" : "s"}` : ""}.`;
     const who = release ? "This release" : "This candidate";
     const what = phase === "deploy" ? "can't deploy" : phase === "merge" ? "can't merge" : phase === "tag" ? "can't be tagged or published" : "can't be approved automatically";
-    // After the merge the release's own CI can't help (the release proof refuses jobs finished after the merge).
     const way = release && phase !== "tag" ? "re-run this release's CI, or wait for tonight's nightly" : "wait for tonight's nightly, or dispatch Nightly on main";
     return `${lanes} ${who} ${what} until ${more > 0 ? "those lanes pass" : "that lane passes"} again: ${way}.`;
 }
-/** Whether this exact candidate of this task holds a fresh exemption for one failure. */
 function exempted(store, taskId, candidate, failure, now) {
     const row = store.handle.prepare("SELECT read_at FROM nightly_exemption WHERE task = ? AND candidate = ? AND failure_id = ?").get(taskId, candidate, failure);
     return row !== undefined && Date.parse(String(row["read_at"])) >= now.getTime() - EXEMPTION_FRESH_MS && Date.parse(String(row["read_at"])) <= now.getTime() + 60_000;
 }
-/**
- * The stored check every boundary makes, inside the caller's own transaction where it has one (the deployment gate, the
- * deploy and merge reservations, the pre-tag step, an automatic approval): the project's open lane failures, less those
- * this exact task and candidate hold a fresh exemption for. Null when nothing holds. A project that never opted in has
- * no lane failures.
- */
 export function nightlyDebtHold(store, input) {
     const held = openFailures(store, input.repo).filter(failure => input.taskId === null || input.candidate === null || !exempted(store, input.taskId, input.candidate, failure.id, input.now));
     return held.length === 0 ? null : { why: nightlyDebtWords(store, held, input.phase, input.release), failures: held };
 }
-/** No nightly run seen for this long reads "hasn't run since". */
 export const NIGHTLY_STALE_MS = 36 * 60 * 60_000;
 export function githubNightlyStatus(store, repo, now) {
     const on = githubNightlyOf(store, repo);
@@ -715,7 +592,6 @@ const agoWords = (iso, now) => {
     const minutes = Math.max(0, Math.round((now.getTime() - Date.parse(iso)) / 60_000));
     return minutes < 60 ? `last read ${minutes} min ago` : minutes < 48 * 60 ? `last read ${Math.round(minutes / 60)} h ago` : `last read ${Math.round(minutes / 1440)} days ago`;
 };
-/** A warning that never holds anything (Decision 1): GitHub couldn't be read, or the nightly hasn't run lately. */
 export function nightlyWarning(status, now) {
     if (!status.on)
         return null;
@@ -725,13 +601,6 @@ export function nightlyWarning(status, now) {
         return status.lastRunAt === null ? "GitHub nightly: hasn't run since it was turned on. Not holding the release." : `GitHub nightly: hasn't run since ${nightlyStamp(status.lastRunAt)}. Not holding the release.`;
     return null;
 }
-/**
- * A release candidate's own pull-request CI, as an exemption needs it (modelled on scripts/release-proof.mjs): for each
- * workflow, the newest run on `head` from that pull request's `pull_request` event, that run's latest attempt's jobs
- * with their times, then the run read again. The newest run is chosen first: one that doesn't bind to this pull
- * request never lets an older run stand. `null` for a workflow with no such run; "unreadable" when anything can't be
- * read whole or changed during the read.
- */
 export async function readLaneJobs(get, slug, pr, head, workflows) {
     const listed = [];
     const raw = new Map();
@@ -786,7 +655,6 @@ export async function readLaneJobs(get, slug, pr, head, workflows) {
             return "unreadable";
         found.set(workflow, { run: newest.id, attempt: newest.runAttempt, status: newest.status, jobs });
     }
-    // The runs again: a newer run or attempt that appeared mid-read voids the read.
     const relisted = await get(`repos/${slug}/actions/runs?head_sha=${head}&event=pull_request&per_page=${PAGE}&page=1`);
     const relistedBody = relisted.ok ? object(relisted.body) : null;
     const relistedRows = relistedBody === null ? null : relistedBody["workflow_runs"];
@@ -802,13 +670,7 @@ export async function readLaneJobs(get, slug, pr, head, workflows) {
     }
     return found;
 }
-/** The files a lane's job runs that the candidate could otherwise rewrite to make a job of that name pass: its workflow
- * file and the CI scripts the workflows call. An exemption stands only when each is byte-identical (the same Git
- * blob) on the candidate and at the failed commit. The tests themselves are the candidate's, as for every required
- * check (the trust the required-checks gate already places in them). */
 export const LANE_PINNED_FILES = ["scripts/ci-shards.mjs", "scripts/ci-scope.mjs", "scripts/ci-git.sh", "scripts/ci-no-skips.mjs"];
-/** Whether every pinned file of a lane's workflow is the same blob on `candidate` as at `failed`, by GitHub's own
- * contents API; null when any can't be read. */
 async function lanePinned(get, slug, workflow, candidate, failed) {
     for (const path of [workflow, ...LANE_PINNED_FILES]) {
         const blobs = [];
@@ -824,7 +686,6 @@ async function lanePinned(get, slug, workflow, candidate, failed) {
     }
     return { same: true };
 }
-/** Whether `candidate` contains `ancestor`, by GitHub's own comparison; null when it can't be read. */
 async function candidateContains(get, slug, candidate, ancestor) {
     if (candidate === ancestor)
         return true;
@@ -836,14 +697,7 @@ async function candidateContains(get, slug, candidate, ancestor) {
         return null;
     return body["behind_by"] === 0 && (body["status"] === "ahead" || body["status"] === "identical");
 }
-/** A read time no stored check accepts: an exemption whose last re-read failed. */
 const STALE_READ = "1970-01-01T00:00:00.000Z";
-/**
- * A boundary (the coordinator's deploy, merge and pre-tag steps): one bounded read of GitHub's nightly, then this
- * candidate's exemptions read again from its own pull-request CI — minted only before the merge (`deploy`, `merge`);
- * at the tag an exemption obtained before the merge is re-read, never made — then the stored debt. A read that fails is
- * a warning and the stored debt still holds; an exemption that can't be re-read is no exemption here.
- */
 export async function nightlyBoundary(store, input, deps, budgetMs = NIGHTLY_BOUNDARY_READ_MS) {
     const started = deps.now().getTime();
     const deadline = started + budgetMs;
@@ -860,17 +714,13 @@ export async function nightlyBoundary(store, input, deps, budgetMs = NIGHTLY_BOU
             return { ok: false, why: String(error?.message ?? error).slice(0, 200) };
         }
     };
-    // The nightly itself, within about two thirds of the budget; the rest is the candidate's own CI.
     if (githubNightlyOf(store, input.repo) !== null)
         await readGithubNightly(store, input.repo, deps, Math.max(0, Math.floor(budgetMs * 2 / 3) - (deps.now().getTime() - started)));
     const warning = nightlyWarning(githubNightlyStatus(store, input.repo, deps.now()), deps.now());
     const open = openFailures(store, input.repo);
     const unverified = new Set();
-    // A re-read that fails takes the stored permission away too (Codex round 1, finding 3): the row stays, so a later
-    // boundary that reads it whole again (the tag included) can restore it, but no stored check accepts it meanwhile.
     const invalidate = (failure) => store.handle.prepare("UPDATE nightly_exemption SET read_at = ? WHERE task = ? AND candidate = ? AND failure_id = ?")
         .run(STALE_READ, input.taskId, input.candidate, failure);
-    /** Failures this candidate can't be exempted from: it changes how the lane runs (the path that differs). */
     const changed = new Map();
     const slug = githubNightlyOf(store, input.repo)?.slug ?? null;
     if (open.length > 0 && slug !== null && SHA.test(input.candidate) && positive(input.pr)) {
@@ -892,7 +742,6 @@ export async function nightlyBoundary(store, input, deps, budgetMs = NIGHTLY_BOU
                 && job.startedAt !== null && job.completedAt !== null && job.startedAt > failure.completedAt;
             const same = row !== undefined && found !== null && job !== null && Number(row["gh_run"]) === found.run && Number(row["attempt"]) === found.attempt && Number(row["job_id"]) === job.id;
             const at = deps.now().toISOString();
-            // The newest run or attempt differs, is pending, or holds a failure for that lane: the exemption is void.
             if (row !== undefined && !(same && valid))
                 store.handle.prepare("DELETE FROM nightly_exemption WHERE task = ? AND candidate = ? AND failure_id = ?").run(input.taskId, input.candidate, failure.id);
             if (!valid)
@@ -911,7 +760,6 @@ export async function nightlyBoundary(store, input, deps, budgetMs = NIGHTLY_BOU
                 }
                 continue;
             }
-            // A job named like the lane proves nothing if the candidate rewrote what that job runs.
             const pinned = await lanePinned(get, slug, workflow, input.candidate, failure.sha);
             if (pinned === null) {
                 unverified.add(failure.id);
@@ -931,7 +779,6 @@ export async function nightlyBoundary(store, input, deps, budgetMs = NIGHTLY_BOU
     const now = deps.now();
     const hold = store.transact(() => {
         const stored = nightlyDebtHold(store, { repo: input.repo, taskId: input.taskId, candidate: input.candidate, phase: input.phase, release: true, now });
-        // An exemption that couldn't be re-read now never counts at this boundary, whatever is stored.
         const held = openFailures(store, input.repo).filter(failure => unverified.has(failure.id) || stored?.failures.some(one => one.id === failure.id) === true);
         if (held.length === 0)
             return null;
@@ -941,11 +788,6 @@ export async function nightlyBoundary(store, input, deps, budgetMs = NIGHTLY_BOU
     });
     return hold === null ? { ok: true, warning } : { ok: false, why: hold, warning };
 }
-/**
- * Needs you, for the projects `shown` admits: one item per open GitHub nightly lane failure (linking to its job on
- * GitHub, under the opted-in repository the plane recorded), and one per nightly check of main with open failures
- * (linking to its task). Oldest first.
- */
 export function nightlyNeedsYou(store, shown) {
     const needs = [];
     const failed = store.handle.prepare("SELECT DISTINCT repo FROM nightly_lane_failure WHERE cleared_at IS NULL").all().map(row => String(row["repo"])).filter(shown);
@@ -957,7 +799,6 @@ export function nightlyNeedsYou(store, shown) {
                 href: slug === null ? "/tasks?view=board" : `https://github.com/${slug}/actions/runs/${failure.ghRun}/job/${failure.jobId}`, since: failure.openedAt });
         }
     }
-    // The plane's own nightly check of main (nightly-check.ts): one item per failed check, its items summed up.
     const rows = store.handle.prepare("SELECT repo, run, sha, MIN(opened_at) AS since, COUNT(*) AS n FROM main_check_failure WHERE cleared_at IS NULL GROUP BY repo, run, sha ORDER BY since").all();
     for (const row of rows) {
         const repo = String(row["repo"]);
@@ -972,8 +813,6 @@ export function nightlyNeedsYou(store, shown) {
     }
     return needs.sort((a, b) => a.since.localeCompare(b.since));
 }
-/** The release card's GitHub nightly lines: each open lane failure (held, or exempted for this candidate), then a
- * warning when GitHub couldn't be read or the nightly hasn't run lately. Empty when there is nothing to say. */
 export function nightlyReleaseLines(store, input) {
     const lines = openFailures(store, input.repo).map(failure => {
         const lane = `GitHub nightly: failed ${laneName(store, input.repo, failure.laneId)} (${nightlyStamp(failure.completedAt)}).`;
@@ -983,13 +822,6 @@ export function nightlyReleaseLines(store, input) {
     const warning = nightlyWarning(githubNightlyStatus(store, input.repo, input.now), input.now);
     return warning === null ? lines : [...lines, warning];
 }
-/**
- * A deploy run's own boundary (scripts/deploy-browser.mjs, through the installed runtime; Codex round 1, finding 3):
- * the same bounded read as the coordinator's — GitHub's nightly, then this candidate's exemptions re-read — before the
- * stored check, so a deploy started by hand neither misses a new failure nor rides an exemption its CI no longer
- * supports. A task no release covers has no exemption to re-read; its nightly is still read. Anything that fails here
- * takes away the candidate's stored exemptions; the stored check that follows decides.
- */
 export async function refreshNightlyForDeploy(store, input) {
     const run = store.getRun(input.runId);
     const ref = run === null ? null : store.refById(run.taskRef);

package/dist/notification-delivery.js

@@ -1,9 +1,7 @@
 import { createHash } from "node:crypto";
-/** URLs and shell commands can contain secrets. Only a destination hash enters saved receipts. */
 export function notificationDestination(kind, target) {
     return `${kind}:${createHash("sha256").update(target).digest("hex")}`;
 }
-/** One-release compatibility for operator-configured, installation-wide senders. Personal notifications never leave here. */
 export function claimNotifications(store, destination, owner, now) {
     return store.transact(() => {
         const db = store.handle, stamp = now.toISOString();
@@ -28,7 +26,6 @@ export function finalizeNotification(store, row, owner, outcome, now) {
     WHERE notification = ? AND destination = ? AND claim_owner = ? AND claim_generation = ?
       AND claim_expires_at > ? AND delivered_at IS NULL`).run(now.toISOString(), outcome.ok && !skipped ? now.toISOString() : null, outcome.ok ? outcome.receipt : null, outcome.ok ? null : outcome.error, row.id, row.destination, owner, row.generation, now.toISOString()).changes) === 1;
 }
-/** Recheck after earlier network sends: expiry or resolution must stop this send, not just its receipt. */
 export function notificationClaimHeld(store, row, owner, now) {
     return store.handle.prepare(`SELECT 1 FROM notification_delivery d JOIN notification n ON n.id = d.notification
     WHERE d.notification = ? AND d.destination = ? AND d.claim_owner = ? AND d.claim_generation = ?

package/dist/notification-rows.js

@@ -1,7 +1,3 @@
-/** The one task a card is about: a task its confirmation created (a new
- * task, a revision), else the task it names (and, for feedback on a result,
- * that result). Null for a card about no single task. A pointer for
- * replies, never an authority. */
 export function proposalTaskOf(proposal) {
     if (proposal === null)
         return null;
@@ -15,16 +11,7 @@ export function proposalTaskOf(proposal) {
     const run = proposal.kind === "review" ? proposal.payload["run"] : null;
     return { task: named, run: typeof run === "number" && Number.isSafeInteger(run) ? run : null };
 }
-/** Every lifecycle dedupe key starts here: `life:<kind>:<identity>:<ordinal>`. */
 export const LIFECYCLE_KEY_PREFIX = "life:";
-/**
- * Task lifecycle updates (Telegram task updates, 2026-09-16): the CLOSED
- * vocabulary of routine progress facts the shared mutations record beside
- * the change that made them true. None carries a push class — they are
- * digest-eligible progress, never a page — and every one is project-bound
- * through the task it names. A decision, incident, gap, stall, publication
- * or merge page keeps its own producer; nothing here repeats one.
- */
 export const LIFECYCLE_KINDS = [
     "task-filed",
     "scope-approved",
@@ -46,12 +33,9 @@ export const LIFECYCLE_KINDS = [
     "acceptance-evidence",
     "acceptance-ready",
 ];
-/** A progress fact, told apart by its durable key — never by display text. */
 export function isLifecycleNotification(row) {
     return row.dedupeKey.startsWith(LIFECYCLE_KEY_PREFIX);
 }
-/** Only known progress producers can repaint a card. Decisions and urgent
- * incidents keep their own alerts; a routine retry updates its saved attempt. */
 export function isTelegramProgressNotification(row) {
     if (row.kind === "check-progress" && row.pushClass === "progress" && row.run !== null)
         return isLifecycleNotification(row);
@@ -59,7 +43,6 @@ export function isTelegramProgressNotification(row) {
         return false;
     if (row.kind === "build-failed" && row.run !== null && row.dedupeKey === `run:${row.run}:failed`)
         return true;
-    // The owner's lead took the attempt on, or let it lapse (lead-voice.ts): its card repaints in place.
     if ((row.kind === "lead-on-it" || row.kind === "lead-lapsed") && row.run !== null)
         return true;
     return isLifecycleNotification(row) &&