toolroll 0.9.103 → 0.9.105

package/dist/toolroll-update.js

@@ -1,27 +1,3 @@
-/**
- * `toolroll update`: a verified, drained, undoable update of an npm-installed
- * Toolroll. It reuses the desktop update engine's pieces (desktop-update.ts):
- * the SQLite admission gate that lets running work finish, the verified
- * private backup (the coding catalog's inside the same reservation), the
- * durable journal written before every irreversible step, the OS lock that
- * shows whether an updater is alive, and resume after a crash. What differs
- * is what gets swapped: a staged npm runtime instead of an app bundle.
- *
- *   verify → drain → stop and back up → rehearse → switch → restart → health
- *
- * The new release is installed from the npm registry into a Toolroll-managed
- * runtimes folder (`staged-upgrades/`, as deploy-browser stages), never over
- * the running one. npm's own signature and attestation check covers what it
- * installed, the installed bytes must be the ones downloaded and hashed, and
- * the certificate that signed their provenance must name ap9000/toolroll, its
- * publish workflow and GitHub Actions, checked by npm's own Sigstore verifier. The
- * service is stopped, and its processes seen gone, before the final backup,
- * so nothing written before the switch is lost. A failed health check puts
- * back the previous runtime, database and coding catalog on its own, keeping
- * what the new version wrote in a named copy. `--rollback` returns to the
- * previous runtime and its backups. Every update, rollback, refusal and
- * failure is a ledger entry.
- */
 import { inReadOnlyRequest } from "./read-only-request.js";
 import { createHash, randomUUID, verify as signatureValid, X509Certificate } from "node:crypto";
 import { spawnSync } from "node:child_process";
@@ -49,36 +25,26 @@ import { isNewer, REGISTRY } from "./releases.js";
 import { markNeverIndex } from "./never-index.js";
 import { readRuntimeUpdateJournal, RUNTIME_PHASES, RUNTIME_UPDATE_STEPS, stagedStartedAt, updaterStartingOf } from "./contracts/update-journal.js";
 import { sleep } from "./sleep.js";
-/** Loaded on first use (as backup.ts and store.ts do), so modules that only import this one (the console,
- * and tests that load it in a browser-like environment) never need `node:sqlite` itself. */
 function sqlite() {
     return createRequire(import.meta.url)("node:sqlite");
 }
 export const PROVENANCE_REPOSITORY = "https://github.com/ap9000/toolroll";
 export const PROVENANCE_WORKFLOW = ".github/workflows/publish.yml";
 export const PROVENANCE_ISSUER = "https://token.actions.githubusercontent.com";
-/** How long a watch's `toolroll up` may take to exit once launchd stops it (controller-supervisor's shutdown). */
 const UP_EXIT_MS = 45_000;
-/** The steps a person sees, in order. */
 export const UPDATE_STEPS = RUNTIME_UPDATE_STEPS;
 export const STEP_WORDS = {
     verifying: "Verify the package", draining: "Let running work finish", "backing-up": "Stop and back up",
     rehearsing: "Rehearse the migration", switching: "Switch to the new version", restarting: "Restart", health: "Health check",
 };
-/** How many release-* runtimes stay on disk: the running one and the one before it. */
 export const KEEP_RUNTIMES = 2;
-/** The one-off launchd job the console starts the updater as. */
 export const UPDATE_JOB_LABEL = "com.toolroll.update";
 const TERMINAL = ["complete", "restored", "refused", "cancelled"];
 export const runtimeUpdateTerminal = (phase) => TERMINAL.some(known => known === phase);
 const journalFile = (stateDir) => join(stateDir, "toolroll-update.json");
-/** The last completed update, kept apart from the journal: what `--rollback` returns from. */
 const lastUpdateFile = (stateDir) => join(stateDir, "toolroll-update.last.json");
 const cancelFile = (j) => join(j.stageDir, "cancel-request.json");
-/** An updater on its way to this update before it holds the lock: the console's job once launched (launchd may not
- * have started it yet), or a resume about to drive it. */
 const startingFile = (j) => join(j.stageDir, "updater-starting.json");
-/** How long a launched or resuming updater is expected to take to start and hold the lock. */
 export const UPDATER_START_MS = 2 * 60_000;
 function markStarting(j, state, now) {
     durableJson(startingFile(j), { id: j.id, state, at: now.toISOString() });
@@ -121,14 +87,10 @@ export function readRuntimeUpdate(stateDir, file = journalFile(stateDir)) {
         throw Error("The saved update record is invalid. Preserve it and its backups; nothing was changed.");
     return j;
 }
-/** The update `--rollback` returns from: the last one that completed, whatever was attempted since. */
 export function lastCompletedUpdate(stateDir) {
     const kept = existsSync(lastUpdateFile(stateDir)) ? readRuntimeUpdate(stateDir, lastUpdateFile(stateDir)) : readRuntimeUpdate(stateDir);
     return kept?.kind === "update" && kept.phase === "complete" ? kept : null;
 }
-/** Before a new attempt replaces the saved journal: a completed update is kept as what `--rollback` returns from.
- * 0.8.0 and older never wrote `.last.json`, so the update that brought this version would otherwise be lost to the
- * first refused or failed attempt. */
 function keepCompletedUpdate(stateDir) {
     const saved = readRuntimeUpdate(stateDir);
     if (saved?.kind !== "update" || saved.phase !== "complete")
@@ -138,7 +100,6 @@ function keepCompletedUpdate(stateDir) {
         return;
     durableJson(lastUpdateFile(stateDir), saved);
 }
-/** A null phase saves progress without changing the saved phase, including one a newer release wrote. */
 function save(j, phase, detail, now) {
     if (phase !== null) {
         if (j.phase !== phase)
@@ -152,10 +113,7 @@ function save(j, phase, detail, now) {
     durableJson(join(j.stageDir, "update.json"), j);
     durableJson(journalFile(j.stateDir), j);
 }
-/** Every update, rollback, refusal and failure. Plain SQL any build can run,
- * written after any database restore so the restore cannot erase it. */
 function ledger(databaseFile, now, actor, action, outcome, detail) {
-    // Never an empty database where the live one should be.
     if (!existsSync(databaseFile))
         throw Error("The database is not in place.");
     const db = new (sqlite().DatabaseSync)(databaseFile);
@@ -168,7 +126,6 @@ function ledger(databaseFile, now, actor, action, outcome, detail) {
         db.close();
     }
 }
-/** Running work by name, for a refusal a person can act on. */
 export function runningWorkWords(db) {
     const active = activeUpdateWork(db);
     if (Object.values(active).every(n => n === 0))
@@ -180,9 +137,7 @@ export function runningWorkWords(db) {
     const parts = [...(runs.length ? [`running ${runs.join(", ")}${more > 0 ? ` and ${more} more` : ""}`] : []), ...other];
     return parts.join("; ");
 }
-/** Sigstore's certificate extensions (Fulcio's OID registry) and subjectAltName. */
 const OID = { issuerV1: "1.3.6.1.4.1.57264.1.1", repositoryV1: "1.3.6.1.4.1.57264.1.5", issuer: "1.3.6.1.4.1.57264.1.8", buildSigner: "1.3.6.1.4.1.57264.1.9", sourceRepository: "1.3.6.1.4.1.57264.1.12", subjectAltName: "2.5.29.17" };
-/** One DER element at `at`: its tag and where its contents start and end. */
 function derAt(der, at) {
     let length = der[at + 1] ?? 0, start = at + 2;
     if (length & 0x80) {
@@ -219,7 +174,6 @@ function oidText(bytes) {
     }
     return parts.join(".");
 }
-/** A certificate's extensions by OID: each one's value octets. Node's X509Certificate does not expose them. */
 function certificateExtensions(der) {
     const tbs = derChildren(der, derAt(der, 0))[0];
     const found = new Map();
@@ -234,7 +188,6 @@ function certificateExtensions(der) {
     }
     return found;
 }
-/** The signing certificate's own words: who asked Sigstore for it (issuer), which repository and which workflow. */
 function certificateIdentity(der) {
     const extensions = certificateExtensions(der);
     const utf8 = (oid) => { const value = extensions.get(oid); if (!value)
@@ -245,10 +198,6 @@ function certificateIdentity(der) {
     const uris = san ? derChildren(san, derAt(san, 0)).filter(name => name.tag === 0x86).map(name => san.subarray(name.start, name.end).toString("ascii")) : [];
     return { issuer: utf8(OID.issuer) ?? raw(OID.issuerV1), repository: utf8(OID.sourceRepository), repositoryV1: raw(OID.repositoryV1), signer: utf8(OID.buildSigner), uris };
 }
-/** The npm provenance for exactly these bytes of Toolroll itself must be signed by a certificate that names the
- * Toolroll repository, its publish workflow and GitHub Actions as the issuer. The statement's own claims name
- * nobody: only the certificate, whose key must have signed the statement. Sigstore's chain and transparency log are
- * then checked by npm's own verifier (UpdateSystem.sigstore) for the identity returned here. */
 export function checkProvenance(attestations, version, sha512Hex) {
     const list = attestations?.attestations;
     if (!Array.isArray(list) || list.length === 0)
@@ -269,7 +218,6 @@ export function checkProvenance(attestations, version, sha512Hex) {
     catch {
         throw new Refusal(`Toolroll ${version}'s provenance could not be read. Nothing was changed.`);
     }
-    // DSSE: the signature covers the pre-authentication encoding of the payload and its type.
     const signed = Buffer.concat([Buffer.from(`DSSEv1 ${Buffer.byteLength(payloadType)} ${payloadType} ${payload.length} `), payload]);
     const signatures = envelope.signatures ?? [];
     let valid = false;
@@ -296,7 +244,6 @@ export function checkProvenance(attestations, version, sha512Hex) {
     }
     return { repository: PROVENANCE_REPOSITORY, workflow: PROVENANCE_WORKFLOW, issuer: who.issuer, identity, bundle };
 }
-/** Headlines of this version's changelog section: its bold lead phrases. */
 export function releaseNotes(changelog, version) {
     const lines = changelog.split("\n");
     const start = lines.findIndex(line => new RegExp(`^## ${version.replaceAll(".", "\\.")}( |$)`).test(line));
@@ -306,7 +253,6 @@ export function releaseNotes(changelog, version) {
     const section = lines.slice(start + 1, end < 0 ? undefined : end).join("\n");
     return [...section.matchAll(/^- \*\*(.+?)\*\*/gm)].map(m => m[1].replace(/\.$/, "")).slice(0, 6);
 }
-// ---- durable files ----------------------------------------------------------
 function fsyncPath(path) {
     const fd = openSync(path, "r");
     try {
@@ -316,36 +262,17 @@ function fsyncPath(path) {
         closeSync(fd);
     }
 }
-/** Every rename here: what is renamed is flushed first (a file itself, a link
- * by its directory), and the directory after, so a crash never leaves a torn
- * database, catalog or command. */
 export function durableRename(temp, target) {
     fsyncPath(lstatSync(temp).isSymbolicLink() ? dirname(temp) : temp);
     renameSync(temp, target);
     if (process.platform !== "win32")
         fsyncPath(dirname(target));
 }
-// ---- database: snapshot, rehearse, restore --------------------------------
-/** How a rehearsed migration may change each saved table. An unlisted table keeps every column, its row count and
- * its last rowid (a WITHOUT ROWID table, all small, keeps the hash of its rows). `appendOnly`: every row through the
- * last one before hashes the same, in rowid order; new rows may follow. `dropped`: columns the new schema may remove
- * only when every saved value is null, or, with `carried`, when the receiving table gained exactly one receipt under
- * that destination per row holding a value, and as many non-null values per column as the dropped columns held.
- * `receives`: the only rows the table may gain are those receipts. `compacted`: rows may go only into summary rows,
- * whose `sum` grows by exactly as many. `summarizes`: old summaries stay identical by run key; new ones account for
- * that run's compacted witnesses, even below the previous maximum key. `retired`: a removed feature's table, which may go whole. `fromRoutines`: rows
- * kept as they were, and the only rows the table may gain are one per saved routine, moved into a scheduled flow (its
- * flow, or its schedule trigger naming that routine) — on only when the routine was approved and running. `moved`:
- * the table may go only when every row it had (or the ones `rows` counts) arrived in `into`: the rows there that
- * `where` picks grew by exactly that many. */
 const LEGACY_DESTINATION = "legacy:single-destination";
-/** v116: every old per-app chat table into the shared chat tables, keyed by provider (chat-migration.ts). Several old
- * tables fan into one shared table; each picks out only its own rows there, so every count is checked on its own. */
 const TELEGRAM_MOVES = {
     telegram_binding: { into: "chat_binding", where: "1" },
     telegram_pairing: { into: "chat_pair", where: "1" },
     telegram_team_chat: { into: "chat_room", where: "1" },
-    // An applied update is a receipt; a pushed one still waiting is queued (one already applied was spent with it).
     telegram_update: { into: "chat_event", where: "kind = 'update' AND state = 'done'" },
     telegram_inbox: { into: "chat_event", where: "kind = 'update' AND state = 'queued'", rows: "update_id NOT IN (SELECT update_id FROM telegram_update)" },
     telegram_conversation: { into: "chat_event", where: "kind = 'message'" },
@@ -362,7 +289,6 @@ const TELEGRAM_MOVES = {
     telegram_task_message: { into: "chat_message_ref", where: "kind = 'task'" },
     telegram_outbound_message: { into: "chat_message_ref", where: "kind = 'notification'" },
     telegram_note_draft: { into: "chat_note_draft", where: "1" },
-    // A bot's lease and its rate-limit wait share its one runtime row.
     bridge_lease: { into: "chat_runtime", where: "lease_until IS NOT NULL" },
     telegram_retry: { into: "chat_runtime", where: "retry_at IS NOT NULL" },
     telegram_digest: { into: "chat_digest", where: "1", rows: "id = 1" },
@@ -373,7 +299,6 @@ export const CHAT_MOVES = {
     ...Object.fromEntries(Object.entries(TELEGRAM_MOVES).map(([table, move]) => [table, { ...move, where: `provider = 'telegram' AND (${move.where})` }])),
     ...Object.fromEntries(["slack", "discord", "teams"].flatMap(app => APP_TABLES.map(suffix => [`${app}_${suffix}`, { into: `chat_${suffix}`, where: `provider = '${app}'` }]))),
 };
-/** Each table's added columns across versions, merged: a table two versions both extend keeps every column. */
 function addedColumns(...versions) {
     const rules = {};
     for (const version of versions) {
@@ -383,67 +308,30 @@ function addedColumns(...versions) {
     }
     return rules;
 }
-/** Rules on tables that later gained declared columns (addedColumns merges into these instead of replacing them). */
 const EARLIER_RULES = { flow_trigger: { fromRoutines: "trigger" },
-    // v114: a finished run whose process witnesses have all exited keeps one summary row in place of them (v150 adds
-    // their machine id).
     run_process: { compacted: { into: "run_process_summary", sum: "witnesses" } } };
 const HISTORY_RULES = {
     ...Object.fromEntries(Object.entries(CHAT_MOVES).map(([table, moved]) => [table, { moved }])),
     action_ledger: { appendOnly: true }, ledger_seal: { appendOnly: true }, ledger_checkpoint: { appendOnly: true },
-    // v114: a finished run whose process witnesses have all exited keeps one summary row in place of them (the
-    // run_process rule is in EARLIER_RULES, under its v150 column).
     run_process: EARLIER_RULES["run_process"], run_process_summary: { summarizes: "run_process" },
-    // v114: single-destination delivery columns may be dropped only once their values are legacy receipts.
     notification: { dropped: ["attempts", "last_attempt_at", "last_error", "delivered_at", "receipt", "claim_owner", "claim_expires_at"], carried: { into: "notification_delivery", destination: LEGACY_DESTINATION } },
     notification_delivery: { receives: LEGACY_DESTINATION },
-    // v115: contests, held sessions, fallback chains and routines are removed; their tables go whole.
     tournament_terms: { retired: true }, contest: { retired: true }, contestant: { retired: true },
     routine: { retired: true }, routine_fire: { retired: true },
     attended_authorization: { retired: true }, session_turn: { retired: true }, held_session: { retired: true },
     fallback_config: { retired: true }, fallback_cycle: { retired: true }, fallback_transition: { retired: true },
-    // v115: each routine becomes one scheduled flow and its schedule trigger.
     flow: { fromRoutines: "flow" }, flow_trigger: { fromRoutines: "trigger" },
-    // v117 (D5): the lead's and the subagents' tables keep every row under their new names (mate_* → lead_*, teammate* →
-    // subagent*); a column renamed in a table that keeps its name keeps its values under the new one.
     ...Object.fromEntries(Object.entries(V117_RENAMED_TABLES).map(([old, now]) => [old, { moved: { into: now, where: "1" } }])),
     ...Object.fromEntries(V117_RENAMED_COLUMNS.filter(([table]) => !Object.values(V117_RENAMED_TABLES).includes(table)).map(([table, from, to]) => [table, { renamed: { [from]: to } }])),
-    // v118 (D7): every API token, coordinator and lead token arrives in the one credential table under its kind.
     ...Object.fromEntries(Object.entries(V118_MERGED_TABLES).map(([table, kind]) => [table, { moved: { into: "credential", where: `kind = '${kind}'` } }])),
-    // v119: planning generations and a question's closure reason are new columns; every row saved before them reads
-    // the declared value (generation 0, no closure reason).
-    // v120: a steering note's mailing and acknowledgement, and a run's steering folder, are new columns; every row
-    // saved before them reads none.
-    // v121: live steering's columns and a run's attempt key read none, and no sends, the same way.
-    // v122: a project's recorded remote reads none the same way.
-    // v123: a plan authorization's basis reads the operating mode, and a trigger firing reads not on time and no script ran.
-    // v126: a receipt's state, acceptance time and held item, a trigger's credential generation and turned-away count,
-    // and who made a card read none, 0, or none. A table with an earlier rule (flow_trigger's v115 move) keeps it too.
-    // v128: a lead message's pending flag reads waiting exactly for a team queue's unadmitted operator message.
-    // v147: an account's password flag reads set (1), a browser session reads full with no local binding or key, and the
-    // console record reads no key epoch.
-    // v148: a run's execution class and a revision's origin read none (NULL), and a project's suggestion switch reads on.
-    // v149 adds tables only (the learning-loops records): no saved row changes, so no rule is needed for it.
-    // v150: a saved process witness reads no machine id (NULL), and is matched by host name as before.
-    // v151: a saved cleanup setting's idle limit reads none (NULL): the default.
-    // v152: a saved project's code map reads on, with no enrollment yet; the code map's tables are new.
-    // v153: a saved task reads no fast start and a saved project no fast-start setting (NULL); its tables are new.
-    // v154 adds a table only (check_stamp): no saved row changes, so no rule is needed for it.
-    // v155 adds tables only (fleet-schema.ts): no saved row changes, so no rule is needed for it.
-    // v156 adds tables only (fallback chains): likewise.
-    // v158 (after v157's chat-app tables): a saved lead step reads no tool names and no failure detail, and a saved reply no route and no failure detail
-    // (NULL); the quick-answer switch is a new table.
-    // v159: a saved fast-start preview reads no lead turn (NULL); a typed yes's record is a new table.
     ...Object.fromEntries(Object.entries(addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS, V147_ADDED_COLUMNS, V148_ADDED_COLUMNS, V150_ADDED_COLUMNS, V151_ADDED_COLUMNS, V152_ADDED_COLUMNS, V153_ADDED_COLUMNS, V158_ADDED_COLUMNS, V159_ADDED_COLUMNS))
         .map(([table, rule]) => [table, { ...EARLIER_RULES[table], ...rule }])),
 };
-/** The tables a migration may remove whole (v115's removed features). */
 export const RETIRED_TABLES = Object.freeze(Object.keys(HISTORY_RULES).filter(name => HISTORY_RULES[name].retired));
 const tableColumns = (db, name) => db.prepare("PRAGMA table_info(" + quote(name) + ")").all().map(r => String(r["name"]));
 const plainValue = (_, v) => v instanceof Uint8Array ? Buffer.from(v).toString("hex") : typeof v === "bigint" ? String(v) : v;
 const rowHash = (row) => createHash("sha256").update(JSON.stringify(Object.values(row), plainValue)).digest("hex");
 const summaryRows = (db, name, columns) => db.prepare("SELECT " + columns.map(quote).join(",") + " FROM " + quote(name) + " ORDER BY run").iterate();
-/** Keep every saved summary byte-identical. A new key must replace all witnesses saved for that same run. */
 function keptSummaries(db, name, before, source) {
     const saved = new Map(before?.summaries?.map(row => [row.run, row.hash]));
     const witnesses = new Map(source?.compactedRuns?.map(row => [row.run, row.count]));
@@ -462,7 +350,6 @@ function keptSummaries(db, name, before, source) {
     }
     return saved.size === 0;
 }
-/** Rows streamed into a sha256, never held together: through a rowid in rowid order, or a WITHOUT ROWID table whole. */
 function rowsHash(db, name, columns, through) {
     const select = "SELECT " + (through === undefined ? "" : 'rowid AS "rowid:", ') + columns.map(quote).join(",") + " FROM " + quote(name);
     const key = () => db.prepare("SELECT name FROM pragma_table_info(?) WHERE pk > 0 ORDER BY pk").all(name).map(r => quote(String(r["name"]))).join(",");
@@ -475,16 +362,12 @@ function rowsHash(db, name, columns, through) {
     }
     return { count, hash: hash.digest("hex") };
 }
-/** Rows under one receipt destination, and each column's non-null values among them: counted, never read. */
 function receipts(db, name, destination, columns) {
     const r = db.prepare("SELECT count(*) AS n" + columns.map(column => ",count(" + quote(column) + ") AS " + quote(column)).join("") + " FROM " + quote(name) + " WHERE destination = ?").get(destination);
     return { count: Number(r["n"]), nonNull: Object.fromEntries(columns.map(column => [column, Number(r[column])])) };
 }
-/** The rows a moved table's rule picks out in its destination (none while there is no such table). */
 const arrived = (db, move) => db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(move.into) ? Number(db.prepare("SELECT count(*) AS n FROM " + quote(move.into) + " WHERE " + move.where).get()["n"]) : 0;
 const summed = (db, into) => db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(into.into) ? Number(db.prepare("SELECT coalesce(sum(" + quote(into.sum) + "),0) AS n FROM " + quote(into.into)).get()["n"]) : 0;
-/** Each saved table's columns, row count and last rowid; the append-only ones hashed (deploy-browser's rehearsal check).
- * Bounded: only the ledger and small tables are read row by row. */
 export function historySnapshot(db) {
     return db.prepare("SELECT name, wr FROM pragma_table_list WHERE schema='main' AND type IN ('table','shadow') AND name NOT LIKE 'sqlite_%' AND name <> 'schema_version' ORDER BY name").all()
         .map(row => {
@@ -518,7 +401,6 @@ export function historySnapshot(db) {
         return t;
     });
 }
-/** Each saved routine (none when the table is gone or was never made), and whether it was approved and running. */
 function savedRoutines(db) {
     if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='routine'").get())
         return [];
@@ -528,7 +410,6 @@ function savedRoutines(db) {
     return db.prepare("SELECT id, repo, name, " + live + " AS live FROM routine ORDER BY id").all()
         .map(r => ({ id: Number(r["id"]), repo: String(r["repo"]), name: String(r["name"]), live: Number(r["live"]) === 1 }));
 }
-/** Whether a table's rows past its saved last rowid are exactly the flows (or schedule triggers) its saved routines became. */
 function movedRoutines(db, t, before) {
     const routines = t.routines ?? [];
     if (HISTORY_RULES[t.name].fromRoutines === "flow") {
@@ -537,7 +418,6 @@ function movedRoutines(db, t, before) {
         return added.length === routines.length && added.every(r => r["state"] === "active")
             && JSON.stringify(added.map(r => key(r["repo"], r["name"])).sort()) === JSON.stringify(routines.map(r => key(r.repo, r.name)).sort());
     }
-    // A trigger names its routine in its order, and belongs to a flow the move added for that same routine.
     const flows = before.find(one => one.name === "flow");
     if (flows === undefined)
         return false;
@@ -553,10 +433,8 @@ function movedRoutines(db, t, before) {
         return r["repo"] === routine.repo && r["name"] === routine.name && (r["state"] === "paused" || (r["state"] === "active" && routine.live));
     });
 }
-/** The tables whose saved history the migration changed beyond what HISTORY_RULES declares. */
 export function changedHistory(db, before) {
     const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map(r => String(r["name"])));
-    // Receipts each receiving table gained, and the dropped values a carrying table owes it.
     const gained = new Map(), owed = new Map();
     for (const t of before) {
         if (t.received && tables.has(t.name)) {
@@ -589,7 +467,6 @@ export function changedHistory(db, before) {
         if (t.columns.some(c => !kept(c) && (!rule?.dropped?.includes(c) || (t.nonNull?.[c] !== 0 && !accounted(rule, t)))))
             return true;
         const columns = t.columns.filter(c => present.has(c));
-        // A declared new column: every row saved before it reads its declared value.
         const added = Object.entries(rule?.added ?? {}).filter(([c]) => !t.columns.includes(c) && present.has(c));
         if (t.rowid && added.some(([c, saved]) => Number(db.prepare("SELECT count(*) AS n FROM " + quote(t.name) + " WHERE rowid <= ? AND " + quote(c) + " IS NOT " + saved).get(t.last)["n"]) > 0))
             return true;
@@ -610,7 +487,6 @@ export function changedHistory(db, before) {
         const r = db.prepare("SELECT count(*) AS n, coalesce(max(rowid),0) AS last FROM " + quote(t.name)).get(), count = Number(r["n"]), last = Number(r["last"]);
         if (rule?.compacted)
             return count > t.count || last > t.last || t.count - count !== summed(db, rule.compacted) - (t.summed ?? 0)
-                // A newly created summary table has no digest of its own; check its keys here too.
                 || (!before.some(one => one.name === rule.compacted.into) && tables.has(rule.compacted.into) && !keptSummaries(db, rule.compacted.into, undefined, t));
         if (rule?.receives) {
             const added = gained.get(t.name)?.count ?? 0;
@@ -625,8 +501,6 @@ async function rehearse(j, system, source) {
     chmodSync(copy, 0o600);
     try {
         let db = new (sqlite().DatabaseSync)(copy, { readOnly: true });
-        // Rows already pointing nowhere before the update are the install's own; only ones the migration makes refuse. (By
-        // today's table names: a renamed table's old orphan is the same row under its new name, orphanKey.)
         const orphans = () => new Set([...db.prepare("PRAGMA foreign_key_check").iterate()].map(row => orphanKey(row)));
         const before = historySnapshot(db), orphaned = orphans();
         db.close();
@@ -651,8 +525,6 @@ async function rehearse(j, system, source) {
             rmSync(copy + suffix, { force: true });
     }
 }
-/** Put a verified backup in place of a live SQLite file. Only once the service's processes are gone. The live file
- * is replaced only by a complete copy: a copy that fails leaves it as it was. */
 function restoreFile(live, backup, hash, what) {
     if (fileHash(backup) !== hash)
         throw Error(`The retained ${what} backup changed. It was not put back.`);
@@ -668,8 +540,6 @@ function restoreFile(live, backup, hash, what) {
         rmSync(temp, { force: true });
     }
 }
-/** Before anything is moved or replaced: every backup is still the one recorded, and there is room for the copy
- * kept aside and for the backups put back. */
 function assertRestorable(j, from, system) {
     if (fileHash(from.path) !== from.hash)
         throw Error("The retained database backup changed. Nothing was put back; the live database is as it was.");
@@ -698,20 +568,16 @@ function freeBytes(dir) {
     return Number(fs.bavail) * Number(fs.bsize);
 }
 const megabytes = (bytes) => `${Math.ceil(bytes / 1_048_576)} MB`;
-/** The database and, when one was backed up, the coding catalog, then this run's coding gate lifted. */
 function restoreDatabase(j, from) {
     restoreFile(j.databaseFile, from.path, from.hash, "database");
     if (from.codingPath && from.codingHash)
         restoreFile(codingFile(j.databaseFile), from.codingPath, from.codingHash, "coding catalog");
     ungateCoding(j);
 }
-/** SQLite's own answer for a file it cannot read as a database: corrupt, or not a database at all. Anything else
- * (busy, a full disk, a permission) is not a reason to move the live database. */
 function unreadableDatabase(error) {
     const code = error.errcode;
     return typeof code === "number" && [11, 26].includes(code & 0xff);
 }
-/** The kept-aside copies a journal names, oldest first; a journal written by 0.8.1 names only its newest. */
 function keptOf(j) {
     return j.kept ?? (j.keptAside ? [{ path: j.keptAside, unreadable: j.keptAsideUnreadable === true }] : []);
 }
@@ -738,12 +604,7 @@ function forgetKept(j, path) {
         delete j.keptAsideUnreadable;
     }
 }
-/** A private copy of the live database before a restore replaces it: what the new version wrote is kept, and named.
- * Only a database SQLite says is corrupt or not a database is moved aside whole, with its WAL; any other failure
- * stops the restore with the live database where it was. Returns what was moved, so a failed restore moves it back. */
 async function keepAside(j) {
-    // Nothing at the live path: an earlier attempt moved it aside and stopped before putting the backup back. That
-    // copy stays named in `kept`.
     if (!existsSync(j.databaseFile))
         return [];
     const id = randomUUID().slice(0, 8), kept = join(j.stageDir, `orders.kept.${id}.db`);
@@ -782,22 +643,15 @@ async function keepAside(j) {
     recordKept(j, unreadable, true);
     return moved;
 }
-/** Undo keepAside's moves: the live database goes back where it was, never leaving the path empty. */
 function moveBack(moved) {
     for (const one of [...moved].reverse())
         if (!existsSync(one.from) && existsSync(one.to))
             durableRename(one.to, one.from);
 }
-// ---- the service: stop, and see it gone -------------------------------------
-/** The service and watch daemons this run stops, switches and restarts: once switched, the ones it switched. */
 function unitsOf(j) {
     return { main: j.switched?.unit?.path ?? j.service?.unit ?? null, watches: j.switched?.watches?.map(w => w.path) ?? j.watches?.map(w => w.unit) ?? [] };
 }
-/** The watch daemons launchd had loaded before the update: the only ones stopped and started again. One a person
- * unloaded stays unloaded (its definition is still switched, so it starts the new version when they load it). */
 const loadedWatches = (j, watches) => watches.filter(unit => j.watches?.find(w => w.unit === unit)?.loaded !== false);
-/** Stop the service and every loaded watch daemon, and wait until every process they ran has exited: only then may
- * a file they write be replaced. */
 async function stopServices(j, system, main, watches) {
     if (!main && watches.length === 0)
         return;
@@ -807,7 +661,6 @@ async function stopServices(j, system, main, watches) {
     const watching = [];
     for (const unit of watches) {
         const earlier = j.watches?.find(w => w.unit === unit);
-        // Recorded once, before the first stop: a resumed run must not read its own stop as the person's choice.
         const loaded = earlier ? earlier.loaded !== false : await system.serviceLoaded(unit);
         watching.push({ unit, pids: loaded ? await pidsOf(unit, earlier?.pids ?? []) : [], loaded });
     }
@@ -828,13 +681,11 @@ async function stopServices(j, system, main, watches) {
         await system.sleep(250);
     }
 }
-// ---- runtime switch: service definition and commands ----------------------
 function pointLink(path, target) {
     const temp = join(dirname(path), `.${basename(path)}.${randomUUID().slice(0, 8)}`);
     symlinkSync(target, temp);
     durableRename(temp, path);
 }
-/** What runs the current version: its service definition and every command on PATH. */
 function switchable(j, system) {
     const unit = system.serviceUnit(j.from), watches = system.watchUnits(j.from), links = system.commands(j.from);
     if (!unit && watches.length === 0 && links.length === 0)
@@ -852,7 +703,6 @@ function switchable(j, system) {
         const target = real(link);
         if (target === null || !target.startsWith(root + sep))
             throw new Refusal(`${link} runs a different Toolroll (${target ?? "a missing file"}), not ${j.from.version}, so it cannot be switched. Remove it, then update again. Nothing was changed.`);
-        // A link is replaced by a rename beside it: its folder must take one, or the switch would stop halfway.
         try {
             accessSync(dirname(link), constants.W_OK);
         }
@@ -865,10 +715,7 @@ function switchable(j, system) {
             throw new Refusal("The service definition does not name the current runtime. Nothing was changed.");
     return { unit, watches, links };
 }
-/** Every change is recorded before it is made; `revert` undoes exactly those.
- * A rollback puts the earlier database back only once the service is gone. */
 async function switchRuntime(j, system) {
-    // A resumed switch keeps what it first recorded, so a revert still reaches the original.
     if (!j.switched) {
         const { unit, watches, links } = switchable(j, system);
         j.switched = { links: links.map(path => ({ path, previous: readlinkSync(path) })), unit: null, watches: [] };
@@ -900,7 +747,6 @@ async function switchRuntime(j, system) {
     for (const link of j.switched.links)
         pointLink(link.path, join(j.to.dist, "bin.js"));
 }
-/** Put back every definition and command it can; one it cannot write is skipped and named, so the restore goes on. */
 function revertSwitch(j) {
     const stuck = [];
     for (const one of [j.switched?.unit, ...j.switched?.watches ?? []]) {
@@ -934,8 +780,6 @@ function gate(j) {
         db.close();
     }
 }
-/** Lift this run's admission pause, in the database and the coding catalog. A restored database has no pause of
- * its own (its backup dropped it), so the catalog's is lifted on its own. */
 function ungate(j) {
     const db = new (sqlite().DatabaseSync)(j.databaseFile);
     try {
@@ -962,9 +806,6 @@ function ungateCoding(j) {
         db.close();
     }
 }
-/** A foreground `toolroll up` holds a live watch lease; the runtime or database under it must not be replaced.
- * (A watch daemon releases its lease when it is stopped.) `restoring`: checked right before a backup is put back,
- * where a database that cannot be read has no watch on it to protect. */
 function refuseWhileWatching(j, system, restoring = false) {
     let row;
     try {
@@ -1006,7 +847,6 @@ function assertNoneActive(stateDir) {
     if (existing && !runtimeUpdateTerminal(existing.phase))
         throw new Refusal(`An update to ${existing.to.version} is already ${existing.phase === "scheduled" ? "scheduled" : "under way"} (${existing.detail}) Cancel it with toolroll update --cancel, or resume it with toolroll update --resume.`);
 }
-/** Record an update without running it: the console's job resumes exactly this journal id. */
 export function prepareRuntimeUpdate(o, now) {
     if (!/^\d+\.\d+\.\d+$/.test(o.version))
         return { refused: `${o.version} is not a release version (x.y.z).` };
@@ -1026,7 +866,6 @@ export function prepareRuntimeUpdate(o, now) {
         ledger(j.databaseFile, now, j.actor, "toolroll update scheduled", "scheduled", `${j.from.version} → ${j.to.version} at ${at}`);
     return j;
 }
-/** Start an update: stage, verify, then run the journaled steps. */
 export async function startRuntimeUpdate(o, system) {
     if (o.version === o.current.version)
         return { ok: true, phase: "complete", message: `Toolroll ${o.version} is current.`, journal: null };
@@ -1035,7 +874,6 @@ export async function startRuntimeUpdate(o, system) {
         return { ok: false, phase: "refused", message: j.refused, journal: null };
     return driveRuntimeUpdate(j, system);
 }
-/** Return to the runtime and database backup an update replaced. */
 export async function startRuntimeRollback(o, system) {
     let last;
     try {
@@ -1055,8 +893,6 @@ export async function startRuntimeRollback(o, system) {
     j.restoreFrom = { path: last.backupPath, hash: last.backupHash, updateId: last.id, ...(last.codingBackupPath && last.codingBackupHash ? { codingPath: last.codingBackupPath, codingHash: last.codingBackupHash } : {}) };
     return driveRuntimeUpdate(j, system);
 }
-/** Continue a saved update after a crash, where it left off. With `id` (the console's job), only that update:
- * a job never starts a fresh one, and a finished, replaced or rolled-back one is left alone. */
 export async function resumeRuntimeUpdate(stateDir, system, id) {
     const j = readRuntimeUpdate(stateDir);
     if (id !== undefined && j?.id !== id)
@@ -1066,14 +902,12 @@ export async function resumeRuntimeUpdate(stateDir, system, id) {
     markStarting(j, "resuming", system.now());
     return driveRuntimeUpdate(j, system);
 }
-/** A prepared update whose job could not start. */
 export function abandonRuntimeUpdate(stateDir, id, why, now) {
     const j = readRuntimeUpdate(stateDir);
     if (j?.id === id && j.phase === "scheduled")
         save(j, "refused", why, now);
 }
 const CANCELLABLE = ["scheduled", "verifying", "draining"];
-/** `locked`: a test's seam, called once the updater's lock is held and before the journal is read again. */
 export function requestRuntimeUpdateCancel(stateDir, now = new Date(), seams = {}) {
     const j = readRuntimeUpdate(stateDir);
     if (!j || runtimeUpdateTerminal(j.phase))
@@ -1081,7 +915,6 @@ export function requestRuntimeUpdateCancel(stateDir, now = new Date(), seams = {
     const tooLate = (at) => `The update to ${at.to.version} is past the point it can be cancelled (${at.phase}); it will finish or restore on its own.`;
     if (!CANCELLABLE.some(phase => phase === j.phase))
         return tooLate(j);
-    // No updater is running to see the request: cancel here, so the admission pause does not outlive it.
     const lock = sqliteLock(join(j.stageDir, "worker.sqlite"));
     if (!lock) {
         durableJson(cancelFile(j), { id: j.id, action: "cancel" });
@@ -1089,7 +922,6 @@ export function requestRuntimeUpdateCancel(stateDir, now = new Date(), seams = {
     }
     try {
         seams.locked?.();
-        // An updater may have moved on, finished or been replaced between the first read and the lock.
         const held = readRuntimeUpdate(stateDir);
         if (!held || runtimeUpdateTerminal(held.phase))
             return "No update is in progress.";
@@ -1101,7 +933,7 @@ export function requestRuntimeUpdateCancel(stateDir, now = new Date(), seams = {
         try {
             ungate(held);
         }
-        catch { /* no pause yet */ }
+        catch { }
         if (held.kind === "update")
             rmSync(join(held.stageDir, "runtime"), { recursive: true, force: true });
         const noun = held.kind === "update" ? "update" : "rollback";
@@ -1109,7 +941,7 @@ export function requestRuntimeUpdateCancel(stateDir, now = new Date(), seams = {
         try {
             ledger(held.databaseFile, now, held.actor, `toolroll ${noun} cancelled`, "cancelled", `${held.from.version} → ${held.to.version}`);
         }
-        catch { /* the journal still says what happened */ }
+        catch { }
         return `Cancelled the ${noun} to ${held.to.version}. Nothing was switched; new work resumes.`;
     }
     finally {
@@ -1121,7 +953,6 @@ async function driveRuntimeUpdate(j, system) {
     const lock = sqliteLock(join(j.stageDir, "worker.sqlite"), 1000);
     if (!lock)
         return { ok: false, phase: j.phase, message: `An updater is already working on the update to ${j.to.version}.`, journal: j };
-    // What was read before the lock may be out of date: a stalled update released, or a cancel, in between.
     let saved = null;
     try {
         saved = readRuntimeUpdate(j.stateDir);
@@ -1136,7 +967,6 @@ async function driveRuntimeUpdate(j, system) {
         }
         Object.assign(j, saved);
     }
-    // The lock now says an updater is here; the starting mark has done its job.
     rmSync(startingFile(j), { force: true });
     const at = (phase) => UPDATE_STEPS.findIndex(step => step === phase);
     const step = (phase, detail) => { save(j, phase, detail, system.now()); system.checkpoint?.(phase); };
@@ -1147,11 +977,10 @@ async function driveRuntimeUpdate(j, system) {
         try {
             ledger(j.databaseFile, system.now(), j.actor, action, outcome, detail);
         }
-        catch { /* the journal still says what happened */ }
+        catch { }
         return { ok, phase, message, journal: j };
     };
     try {
-        // Scheduled: wait for the time, still cancellable.
         if (j.phase === "scheduled" && j.at) {
             while (system.now() < new Date(j.at)) {
                 if (cancelRequested(j))
@@ -1159,7 +988,6 @@ async function driveRuntimeUpdate(j, system) {
                 await system.sleep(Math.min(60_000, new Date(j.at).getTime() - system.now().getTime()));
             }
         }
-        // Resumed past the switch: the only question left is whether the new runtime is healthy.
         const resumedAt = at(j.phase);
         if (j.phase === "rolling-back" || j.phase === "needs-attention")
             return await restore(j, system, finish, verb, j.error ?? "An earlier attempt stopped.");
@@ -1182,13 +1010,11 @@ async function driveRuntimeUpdate(j, system) {
                     return finish(true, "cancelled", `The ${noun} to ${j.to.version} was cancelled. Nothing changed; new work resumed.`, `toolroll ${noun} cancelled`, "cancelled", verb);
                 }
             }
-            // The service stops before the backup, so nothing it writes afterwards can be lost by a restore.
             step("backing-up", unit || watches.length > 0 ? "Stopping the background service, then backing up the database." : "Backing up the database.");
             await stopServices(j, system, unit, watches);
             refuseWhileWatching(j, system);
             const db = new (sqlite().DatabaseSync)(j.databaseFile, { readOnly: true });
             try {
-                // An older runtime killed before its close left its owner record behind: released once its processes are proved gone.
                 const released = releaseStaleCodingOwner(db, [...j.service?.pids ?? [], ...(j.watches ?? []).flatMap(w => w.pids)], (pid, group) => system.processAlive(pid) || processMayBeAlive(pid, group));
                 if (released !== null) {
                     j.codingOwnerReleased = released;
@@ -1200,8 +1026,6 @@ async function driveRuntimeUpdate(j, system) {
                 db.close();
             }
             const backup = join(j.stageDir, existsSync(join(j.stageDir, "orders.backup.db")) ? `orders.backup.${randomUUID()}.db` : "orders.backup.db");
-            // A database one or more update-safe migrations behind is backed up as it is: the rehearsal below proves the
-            // migration on a copy, and the new runtime runs it. Any other schema needs the separate migration procedure.
             j.backupHash = await verifiedDatabaseBackup(j.databaseFile, backup, j.id, async () => { await codingBackup(j); }, undefined, updateSafeSchema);
             j.backupPath = backup;
             save(j, "backing-up", "Database and coding catalog backed up.", system.now());
@@ -1233,19 +1057,17 @@ async function driveRuntimeUpdate(j, system) {
         const done = j.kind === "update"
             ? finish(true, "complete", `Toolroll ${j.to.version} is running. Your previous version (${j.from.version}) and its backup are kept; toolroll update --rollback returns to them.`, "toolroll updated", "complete", verb)
             : finish(true, "complete", `Back on Toolroll ${j.to.version} with the database from before the update. The records made since are kept in ${basename(j.backupPath ?? "")}.`, "toolroll rolled back", "complete", verb);
-        // What --rollback returns from, kept apart from the journal a later refused or failed attempt replaces.
-        // The update is done: failing to write this must never send it back through the restore below.
         try {
             if (j.kind === "update")
                 durableJson(lastUpdateFile(j.stateDir), j);
             else
                 rmSync(lastUpdateFile(j.stateDir), { force: true });
         }
-        catch { /* the journal still holds it until the next attempt */ }
+        catch { }
         try {
             pruneRuntimes(j.stateDir, [j.to.dist, j.from.dist]);
         }
-        catch { /* an old runtime left on disk is harmless */ }
+        catch { }
         return done;
     }
     catch (error) {
@@ -1257,11 +1079,9 @@ async function driveRuntimeUpdate(j, system) {
             try {
                 ungate(j);
             }
-            catch { /* no gate yet, or the database is unreadable */ }
-            // Nothing uses a refused download; the database backup is kept.
+            catch { }
             if (j.kind === "update")
                 rmSync(join(j.stageDir, "runtime"), { recursive: true, force: true });
-            // A service and watch daemons stopped for the backup start again, unchanged.
             let restarted = "";
             for (const unit of [j.service?.unit, ...(j.watches ?? []).filter(w => w.loaded !== false).map(w => w.unit)]) {
                 if (!unit)
@@ -1282,7 +1102,6 @@ async function driveRuntimeUpdate(j, system) {
         lock.close();
     }
 }
-/** The coding catalog, backed up inside the database's write reservation (as the desktop update does). */
 async function codingBackup(j) {
     const source = codingFile(j.databaseFile);
     if (!codingCatalogExists(source))
@@ -1292,14 +1111,11 @@ async function codingBackup(j) {
     j.codingBackupPath = target;
     j.codingBackupHash = fileHash(target);
 }
-/** Put back the previous runtime, then this run's own backups of the database and coding catalog, keeping what
- * was written since in a named copy. */
 async function restore(j, system, finish, verb, why) {
     const noun = j.kind === "update" ? "update" : "rollback";
     try {
         save(j, "rolling-back", `${why} Restoring ${j.from.version} and the database backup.`, system.now());
         system.checkpoint?.("rolling-back");
-        // The commands go back first, so a stop that fails never leaves them on the failed version.
         const stuck = revertSwitch(j);
         const { main, watches } = unitsOf(j);
         await stopServices(j, system, main, watches);
@@ -1308,10 +1124,7 @@ async function restore(j, system, finish, verb, why) {
         if (!j.restoredDatabase) {
             refuseWhileWatching(j, system, true);
             const from = { path: j.backupPath, hash: j.backupHash, ...(j.codingBackupPath && j.codingBackupHash ? { codingPath: j.codingBackupPath, codingHash: j.codingBackupHash } : {}) };
-            // Nothing moves until the backups are the ones recorded and there is room to put them back.
             assertRestorable(j, from, system);
-            // A fresh copy before EVERY attempt that is about to replace the database, not only the first: a retry
-            // after a failure earlier in the restore must not overwrite writes made since without keeping them.
             const moved = await keepAside(j);
             save(j, "rolling-back", j.detail, system.now());
             try {
@@ -1319,7 +1132,6 @@ async function restore(j, system, finish, verb, why) {
                 restoreDatabase(j, from);
             }
             catch (error) {
-                // The backup did not go in: the live database comes back to its own path, and is no longer named as kept.
                 if (moved.length > 0 && !existsSync(j.databaseFile)) {
                     moveBack(moved);
                     forgetKept(j, j.keptAside);
@@ -1372,7 +1184,6 @@ async function verify(j, system) {
         j.notes = [];
     }
 }
-/** Served over HTTPS by the registry itself, as the package is. */
 function onRegistry(url) {
     try {
         const at = new URL(url), registry = new URL(REGISTRY);
@@ -1410,7 +1221,6 @@ async function drain(j, system) {
             if (cancelRequested(j))
                 return;
             const idle = Object.values(activeUpdateWork(db)).every(n => n === 0);
-            // The same settling reconcile the background worker runs, so a leftover record it can prove never holds this up.
             if (idle)
                 settleLeftoverRecords(db, system.now());
             const lingering = idle ? lingeringRun(db) : null;
@@ -1422,7 +1232,6 @@ async function drain(j, system) {
                 delete j.waiting;
             else if (j.waiting?.run !== lingering.run || j.waiting.on !== lingering.on)
                 j.waiting = { ...lingering, since: system.now().toISOString() };
-            // Waiting longer on a finished run proves nothing more: stop, let new work resume, and say what clears it.
             if (j.waiting && system.now().getTime() - Date.parse(j.waiting.since) >= LINGERING_LIMIT_MS)
                 throw new Refusal(stoppedWaitingWords(j.waiting));
             save(j, "draining", lingering ? `New work is paused. Waiting for run #${lingering.run}: ${lingeringWords(lingering)}` : `New work is paused. Waiting for ${runningWorkWords(db) ?? "running work"} to finish. Nothing is being cancelled.`, system.now());
@@ -1433,24 +1242,20 @@ async function drain(j, system) {
         db.close();
     }
 }
-/** Keep the newest release-* runtimes (and any in `keep`), at most KEEP_RUNTIMES; deploy-browser's browser-* and
- * the rollback-* records are not this updater's to remove. */
 export function pruneRuntimes(stateDir, keep) {
     const root = join(stateDir, "staged-upgrades");
-    // A partial or older stage file still says when it started; one that is not JSON (or is null) falls back to the mtime.
     const started = (dir) => { try {
         const at = stagedStartedAt(JSON.parse(readFileSync(join(dir, "update.json"), "utf8")));
         if (at !== null)
             return at;
     }
-    catch { /* below */ } return statSync(dir).mtime.toISOString(); };
+    catch { } return statSync(dir).mtime.toISOString(); };
     const releases = readdirSync(root, { withFileTypes: true }).filter(entry => entry.isDirectory() && entry.name.startsWith("release-"))
         .map(entry => join(root, entry.name)).sort((a, b) => started(b).localeCompare(started(a)));
     const kept = new Set(releases.filter(dir => keep.some(dist => dist !== "" && dist.startsWith(dir + sep))));
     for (const dir of releases)
         if (kept.size < KEEP_RUNTIMES)
             kept.add(dir);
-    // A database a failed update kept aside is the only copy of what was written then: never pruned.
     const holdsKeptAside = (dir) => { try {
         return readdirSync(dir).some(name => /^orders\.(?:kept|unreadable)\./.test(name));
     }
@@ -1500,10 +1305,6 @@ export function updateWaitingOf(stateDir, inTheWay) {
         return null;
     return updateWaitingWords({ app: false, version, stopped: true, lingering: j.waiting });
 }
-/** An updater that ended while letting work finish (a crash, a kill, the Mac restarting) leaves new work paused with
- * nobody left to lift the pause. With no updater holding the update, the pause is lifted here and the update says it
- * stopped. Nothing was switched before the backup, so nothing else needs putting back. The background worker's
- * reconcile, `toolroll status` and the console run this. Returns what it said, or null. */
 export function releaseStalledUpdate(stateDir, now) {
     let j;
     try {
@@ -1518,17 +1319,15 @@ export function releaseStalledUpdate(stateDir, now) {
     if (!lock)
         return null;
     try {
-        // An updater may have moved on, or a resumed one replaced it, between the first read and the lock.
         const held = readRuntimeUpdate(stateDir);
         if (!held || held.id !== j.id || held.phase !== "draining")
             return null;
-        // A job launched or a resume under way has not taken the lock yet: it continues this update; nothing is lifted under it.
         if (updaterStarting(held, now))
             return null;
         try {
             ungate(held);
         }
-        catch { /* no pause yet, or the database is unreadable: the journal still says it stopped */ }
+        catch { }
         if (held.kind === "update")
             rmSync(join(held.stageDir, "runtime"), { recursive: true, force: true });
         const noun = held.kind === "update" ? "update" : "rollback";
@@ -1537,23 +1336,20 @@ export function releaseStalledUpdate(stateDir, now) {
         try {
             ledger(held.databaseFile, now, held.actor, `toolroll ${noun} stopped`, "refused", `${held.from.version} → ${held.to.version}: the updater ended while draining`);
         }
-        catch { /* the journal still says what happened */ }
+        catch { }
         return words;
     }
     finally {
         lock.close();
     }
 }
-/** What `toolroll status` and the console show: a stalled `toolroll update` released first, then this installation's
- * waiting update, `toolroll update`'s or the desktop app's. */
 export function waitingUpdate(databaseFile, inTheWay, now, desktopStates) {
     const stateDir = dirname(databaseFile);
-    // A page visit only reads (docs/plans/get-side-effects.md): the console's background pass releases a stalled update.
     if (!inReadOnlyRequest()) {
         try {
             releaseStalledUpdate(stateDir, now);
         }
-        catch { /* an unreadable record is shown as it is */ }
+        catch { }
     }
     return updateWaitingOf(stateDir, inTheWay) ?? desktopUpdateWaitingOf(databaseFile, inTheWay, desktopStates);
 }
@@ -1585,15 +1381,12 @@ function processAlive(pid) {
         return error.code === "EPERM";
     }
 }
-/** The Sigstore verifier npm itself ships (npm install and npm audit signatures use it): no dependency of Toolroll's.
- * It checks the certificate chain, the transparency log entry and that the certificate names this identity. */
 const SIGSTORE_SCRIPT = `const input = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
 require(input.verifier).verify(input.bundle, { certificateIssuer: input.issuer, certificateIdentityURI: input.identity })
   .then(() => process.exit(0), error => { process.stderr.write(String(error && error.message || error)); process.exit(1); });`;
 export function machineSystem(home = homedir(), env = process.env, seams = {}) {
     const sh = seams.exec ?? exec;
     const supervise = seams.run ?? (async (file, args, options) => (await import("./exec.js")).run(file, args, options));
-    // Linux: the laptop service is a systemd user unit; nothing else here runs under systemd (watches use launchd's road).
     if ((seams.platform ?? process.platform) === "linux")
         return { ...machineSystem(home, env, { ...seams, platform: "darwin" }), ...systemdLaptopService(home, sh, supervise, seams) };
     const unitFor = (from) => {
@@ -1628,8 +1421,6 @@ export function machineSystem(home = homedir(), env = process.env, seams = {}) {
         },
         attestations: url => json(url),
         install: async (runtime, release) => {
-            // From the registry by name, so npm's signature and attestation check covers the package itself (a local
-            // tarball is not checked), and the lockfile records exactly which bytes were installed.
             writeFileSync(join(runtime, "package.json"), JSON.stringify({ name: `${NAME}-runtime`, private: true, dependencies: { [NAME]: release.version } }, null, 2));
             const registry = `--registry=${REGISTRY}/`;
             const installed = sh("npm", ["install", "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund", "--no-color", registry], { cwd: runtime });
@@ -1667,7 +1458,7 @@ export function machineSystem(home = homedir(), env = process.env, seams = {}) {
                         lstatSync(path);
                         found.add(path);
                     }
-                    catch { /* not here */ }
+                    catch { }
                 }
             }
             return [...found];
@@ -1707,15 +1498,12 @@ export function machineSystem(home = homedir(), env = process.env, seams = {}) {
             const pid = Number(printed.stdout.match(/\n\s*pid = (\d+)/)?.[1]);
             if (printed.code !== 0 || !(pid > 1))
                 return [];
-            // Its `up` child too: the process that owns the coding catalog, so its exit is proved as well.
             const children = await supervise("pgrep", ["-P", String(pid)]);
             return [pid, ...(children.code === 0 ? children.stdout.trim().split(/\s+/).map(Number).filter(one => Number.isSafeInteger(one) && one > 1) : [])];
         },
         stopService: async (unit) => {
-            // As long as a watch's toolroll up takes to exit.
             const stopped = await stopLaunchdService(definition(unit), supervise, { waitMs: UP_EXIT_MS, ...(seams.sleep ? { sleep: seams.sleep } : {}) });
             if (!stopped.ok) {
-                // The stop disabled the label: enabled again before anything kickstarts it, or it could never start.
                 await supervise("launchctl", ["enable", `${domain}/${labelOf(unit)}`]);
                 throw Error(`${stopped.message}. Nothing was replaced.`);
             }
@@ -1756,9 +1544,6 @@ export function machineSystem(home = homedir(), env = process.env, seams = {}) {
         },
     };
 }
-/** npm's own Sigstore verifier. Found from npm itself (the `npm` on PATH, then the one beside node), never only from
- * `npm root --global`: with a custom global prefix (npm's advice for permission errors) that folder holds the global
- * packages, not npm. */
 export function findSigstoreVerifier(o) {
     const npmPackage = (start) => {
         for (let dir = dirname(start); dir !== dirname(dir); dir = dirname(dir)) {
@@ -1766,7 +1551,7 @@ export function findSigstoreVerifier(o) {
                 if (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name === "npm")
                     return dir;
             }
-            catch { /* not the package folder yet */ }
+            catch { }
         }
         return null;
     };
@@ -1789,13 +1574,6 @@ export function findSigstoreVerifier(o) {
     return null;
 }
 const jobUnit = (home) => join(home, "Library", "LaunchAgents", `${UPDATE_JOB_LABEL}.plist`);
-/** The console starts the updater for one prepared journal as its own one-off
- * launchd job, so the service it restarts is not its parent. The job resumes
- * that id only; it does not run at login (no RunAtLoad: launchd starts it
- * with a kickstart) and removes its definition when it finishes. Elsewhere it
- * is a detached process. */
-/** Where npm puts global commands (`npm prefix --global`/bin), or null when npm does not say. Asked without blocking:
- * the console's request handler starts the job. */
 async function npmPrefixBin(run) {
     const answered = await run("npm", ["prefix", "--global", "--no-color"], { timeoutMs: 30_000 }).catch(() => null);
     const prefix = answered?.code === 0 ? answered.stdout.trim() : "";
@@ -1805,7 +1583,6 @@ export async function launchRuntimeUpdate(args, seams = {}) {
     const dist = args.dist ?? dirname(fileURLToPath(import.meta.url));
     const command = [process.execPath, join(dist, "bin.js"), "update", "--resume", "--id", args.id, "--db", args.databaseFile];
     const stateDir = dirname(args.databaseFile);
-    // Pending until launchd starts the job and it holds the lock: nothing releases the update meanwhile.
     const saved = readRuntimeUpdate(stateDir);
     if (saved?.id === args.id && !runtimeUpdateTerminal(saved.phase))
         markStarting(saved, "launched", (seams.now ?? (() => new Date()))());
@@ -1813,7 +1590,6 @@ export async function launchRuntimeUpdate(args, seams = {}) {
     if ((seams.platform ?? process.platform) === "darwin") {
         const home = seams.home ?? homedir();
         const run = seams.run ?? (await import("./exec.js")).run;
-        // Everywhere a toolroll command is usually linked: the job switches every one it finds on this PATH.
         const npmBin = await (seams.npmBin ?? (() => npmPrefixBin(run)))();
         const pathEnv = [...new Set([dirname(process.execPath), ...(npmBin ? [npmBin] : []), join(home, ".local", "bin"), join(home, "bin"), join(home, "Library", "pnpm"), "/usr/local/bin", "/opt/homebrew/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"])].join(":");
         const unit = launchdPlist({ label: UPDATE_JOB_LABEL, command, workingDirectory: stateDir, logPath: log, pathEnv, keepAlive: false, runAtLoad: false });
@@ -1826,23 +1602,14 @@ export async function launchRuntimeUpdate(args, seams = {}) {
     const out = openSync(log, "a", 0o600);
     spawn(command[0], command.slice(1), { detached: true, stdio: ["ignore", out, out], cwd: stateDir }).unref();
 }
-/** The job's last act: its definition goes, so nothing can start it again. Only the definition for this id. */
 export function retireUpdateJob(id, home = homedir()) {
     const unit = jobUnit(home);
     try {
         if (readFileSync(unit, "utf8").includes(`<string>${id}</string>`))
             rmSync(unit, { force: true });
     }
-    catch { /* none */ }
+    catch { }
 }
-// ---- the laptop service under systemd (easy-start D) --------------------------------------------------------------
-/**
- * The parts of the update's machine that differ for toolroll-up.service, the laptop service on Linux: finding the
- * unit, which processes it runs, stopping it and proving its controller exited through the controller's own signed
- * process record (by start identity, never a pid alone), starting it again, and the health check (the unit active,
- * running the new runtime, and its console proved live at the new version). Every outside effect is `supervise`
- * (systemctl), `sh` (ps) or a seam, so a test scripts all of it.
- */
 function systemdLaptopService(home, sh, supervise, seams) {
     const unitPath = join(home, ".config", "systemd", "user", `${LAPTOP_LABEL_LINUX}.service`);
     const name = `${LAPTOP_LABEL_LINUX}.service`;
@@ -1854,8 +1621,6 @@ function systemdLaptopService(home, sh, supervise, seams) {
         return shown.code === 0 && pid > 1 ? pid : null;
     };
     const active = async () => (await supervise("systemctl", ["--user", "is-active", name])).stdout.trim() === "active";
-    /** The processes the controller's signed record names, when that record is authentic for its registration and its
-     * `up` is the unit's main process by start identity. Null: no such proof (the stop then waits on the pid alone). */
     const recorded = (unit, pid) => {
         const db = unitFlag(readFileSync(unit, "utf8"), "linux", "--db");
         if (db === null || !isAbsolute(db))
@@ -1900,7 +1665,6 @@ function systemdLaptopService(home, sh, supervise, seams) {
         catch {
             return null;
         } },
-        // `daemon install` watches keep launchd's road; on Linux the update switches only the laptop service.
         watchUnits: () => [],
         serviceLoaded: async () => active(),
         servicePids: async () => {
@@ -1918,7 +1682,6 @@ function systemdLaptopService(home, sh, supervise, seams) {
                 throw Error(`systemctl could not stop ${LAPTOP_LABEL_LINUX}: ${(stopped.stderr || `exit ${stopped.code}`).trim().split("\n")[0]}. Nothing was replaced.`);
             if (processes === null)
                 return;
-            // The controller drains and exits; every process its record names must be proved gone before anything is replaced.
             for (let waited = 0;; waited += 250) {
                 const left = processes.filter(one => !processGone(one, probe));
                 if (left.length === 0)
@@ -1929,7 +1692,6 @@ function systemdLaptopService(home, sh, supervise, seams) {
             }
         },
         restartService: async () => {
-            // The switch rewrote the unit on disk: systemd reads it again before starting it.
             const reload = await supervise("systemctl", ["--user", "daemon-reload"]);
             if (reload.code !== 0)
                 throw Error(`systemctl daemon-reload failed: ${(reload.stderr || `exit ${reload.code}`).trim()}`);
@@ -1961,7 +1723,6 @@ function systemdLaptopService(home, sh, supervise, seams) {
         },
     };
 }
-/** The database's console is proved live (socket and HTTP) and says it is `version`. */
 async function liveConsoleAt(databaseFile, version) {
     const { proveLiveConsole } = await import("./console-instance.js");
     const handle = new (sqlite().DatabaseSync)(databaseFile, { readOnly: true });