toolroll 0.7.0 → 0.8.1

package/dist/toolroll-update.js

@@ -0,0 +1,1253 @@
+/**
+ * `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 { createHash, randomUUID, verify as signatureValid, X509Certificate } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { accessSync, chmodSync, closeSync, constants, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+import { durableJson, lingeringWork, sqliteLock, verifiedDatabaseBackup } from "./desktop-update.js";
+import { activeUpdateWork, freezeUpdateGate, installUpdateGate, removeUpdateGate, updateAdmissionPaused, updateGateOwned } from "./desktop-update-gate.js";
+import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, removeCodingUpdateGate } from "./coding-update.js";
+import { installLaunchdService, launchdPlist, stopLaunchdService, writeFileDurably } from "./daemon.js";
+import { NAME } from "./names.js";
+import { isNewer, REGISTRY } from "./releases.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 = ["verifying", "draining", "backing-up", "rehearsing", "switching", "restarting", "health"];
+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.includes(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");
+const sha = (bytes, algorithm = "sha256") => createHash(algorithm).update(bytes).digest("hex");
+const fileHash = (file) => sha(readFileSync(file));
+const quote = (s) => '"' + s.replaceAll('"', '""') + '"';
+const codingFile = (databaseFile) => `${databaseFile}.coding.sqlite`;
+class Refusal extends Error {
+}
+export function readRuntimeUpdate(stateDir, file = journalFile(stateDir)) {
+    if (!existsSync(file))
+        return null;
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw Error("The saved update record is not a regular file. Nothing was changed.");
+    const j = JSON.parse(readFileSync(file, "utf8"));
+    const real = (path) => { try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    } };
+    if (j.version !== 1 || !/^[a-f0-9-]{36}$/.test(j.id) || typeof j.stateDir !== "string" || real(j.stateDir) !== real(stateDir) || !isAbsolute(j.stageDir ?? "") || real(dirname(j.stageDir)) !== real(join(stateDir, "staged-upgrades")))
+        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")
+        return;
+    const kept = existsSync(lastUpdateFile(stateDir)) ? readRuntimeUpdate(stateDir, lastUpdateFile(stateDir)) : null;
+    if (kept && (kept.finishedAt ?? "") >= (saved.finishedAt ?? ""))
+        return;
+    durableJson(lastUpdateFile(stateDir), saved);
+}
+function save(j, phase, detail, now) {
+    if (j.phase !== phase)
+        j.steps.push({ phase, at: now.toISOString() });
+    j.phase = phase;
+    j.detail = detail;
+    j.updatedAt = now.toISOString();
+    if (runtimeUpdateTerminal(phase))
+        j.finishedAt = now.toISOString();
+    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) {
+    const db = new (sqlite().DatabaseSync)(databaseFile);
+    try {
+        db.exec("PRAGMA busy_timeout=5000");
+        db.prepare("INSERT INTO action_ledger(at,actor,repo,task_id,run_id,action,outcome,source,detail) VALUES (?,?,NULL,NULL,NULL,?,?,'policy',?)")
+            .run(now.toISOString(), actor, action, outcome, detail.replace(/[\u0000-\u001f\u007f]+/g, " ").slice(0, 300));
+    }
+    finally {
+        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))
+        return null;
+    const runs = db.prepare("SELECT tr.external_id id, COALESCE(t.title, tr.external_id) title FROM run r JOIN task_ref tr ON tr.id = r.task_ref LEFT JOIN task t ON t.id = tr.external_id WHERE r.outcome IS NULL ORDER BY r.id LIMIT 3").all()
+        .map(row => `${String(row["id"])} (${String(row["title"]).slice(0, 60)})`);
+    const more = Number(active["runs"] ?? 0) - runs.length;
+    const other = Object.entries(active).filter(([key, n]) => key !== "runs" && n > 0).map(([key, n]) => `${n} ${key === "claims" ? "claimed task" : key === "conversations" ? "chat request" : key === "sessions" ? "held session" : key === "stopping" ? "run still stopping" : key === "codingDeliveries" ? "unconfirmed coding message" : "coding session"}${n === 1 ? "" : "s"}`);
+    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) {
+        const bytes = length & 0x7f;
+        if (bytes < 1 || bytes > 4)
+            throw Error("unsupported DER length");
+        length = 0;
+        for (let i = 0; i < bytes; i++)
+            length = length * 256 + (der[start + i] ?? 0);
+        start += bytes;
+    }
+    if (at >= der.length || start + length > der.length)
+        throw Error("truncated DER");
+    return { tag: der[at], start, end: start + length };
+}
+function derChildren(der, parent) {
+    const children = [];
+    for (let at = parent.start; at < parent.end;) {
+        const child = derAt(der, at);
+        children.push(child);
+        at = child.end;
+    }
+    return children;
+}
+function oidText(bytes) {
+    const parts = [Math.floor(bytes[0] / 40), bytes[0] % 40];
+    let n = 0;
+    for (const byte of bytes.subarray(1)) {
+        n = n * 128 + (byte & 0x7f);
+        if (!(byte & 0x80)) {
+            parts.push(n);
+            n = 0;
+        }
+    }
+    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();
+    const wrapper = derChildren(der, tbs).find(element => element.tag === 0xa3);
+    if (!wrapper)
+        return found;
+    for (const extension of derChildren(der, derChildren(der, wrapper)[0])) {
+        const parts = derChildren(der, extension), oid = parts[0], value = parts[parts.length - 1];
+        if (oid.tag !== 0x06 || value.tag !== 0x04)
+            throw Error("malformed extension");
+        found.set(oidText(der.subarray(oid.start, oid.end)), der.subarray(value.start, value.end));
+    }
+    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)
+        return null; const one = derAt(value, 0); if (one.tag !== 0x0c)
+        throw Error("not a UTF8String"); return value.subarray(one.start, one.end).toString("utf8"); };
+    const raw = (oid) => extensions.get(oid)?.toString("utf8") ?? null;
+    const san = extensions.get(OID.subjectAltName);
+    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)
+        throw new Refusal(`Toolroll ${version} has no npm provenance, so it cannot be verified. Nothing was changed.`);
+    const found = list.find(one => String(one?.predicateType ?? "").startsWith("https://slsa.dev/provenance/"));
+    if (!found)
+        throw new Refusal(`Toolroll ${version} has no build provenance statement. Nothing was changed.`);
+    const bundle = found.bundle ?? {}, envelope = bundle.dsseEnvelope ?? {};
+    let statement, certificate, who;
+    const payload = Buffer.from(String(envelope.payload ?? ""), "base64"), payloadType = String(envelope.payloadType ?? "");
+    try {
+        const material = bundle.verificationMaterial;
+        const der = Buffer.from(String(material?.certificate?.rawBytes ?? material?.x509CertificateChain?.certificates?.[0]?.rawBytes ?? ""), "base64");
+        certificate = new X509Certificate(der);
+        who = certificateIdentity(der);
+        statement = JSON.parse(payload.toString("utf8"));
+    }
+    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;
+    try {
+        valid = signatures.length === 1 && typeof signatures[0].sig === "string" && signatureValid("sha256", signed, certificate.publicKey, Buffer.from(signatures[0].sig, "base64"));
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        throw new Refusal(`Toolroll ${version}'s provenance is not signed by the certificate it carries. Nothing was changed.`);
+    const subject = statement.subject?.find(s => s.name === `pkg:npm/${NAME}@${version}`);
+    if (!subject || subject.digest?.sha512 !== sha512Hex)
+        throw new Refusal(`Toolroll ${version}'s provenance is for different bytes than the package downloaded. Nothing was changed.`);
+    const workflow = `${PROVENANCE_REPOSITORY}/${PROVENANCE_WORKFLOW}@`;
+    const identity = who.uris.length === 1 ? who.uris[0] : null;
+    const repository = who.repository ?? (who.repositoryV1 === null ? null : `https://github.com/${who.repositoryV1}`);
+    const named = who.issuer === PROVENANCE_ISSUER && repository === PROVENANCE_REPOSITORY
+        && (who.repositoryV1 === null || `https://github.com/${who.repositoryV1}` === PROVENANCE_REPOSITORY)
+        && identity !== null && identity.startsWith(workflow) && (who.signer === null || who.signer.startsWith(workflow));
+    if (!named || identity === null || who.issuer === null) {
+        const by = identity ?? repository ?? "an unnamed workflow";
+        throw new Refusal(`Toolroll ${version} was built by ${by}${who.issuer === PROVENANCE_ISSUER ? "" : ` (signed in by ${who.issuer ?? "no issuer"})`}, not ${PROVENANCE_REPOSITORY.replace("https://github.com/", "")} (${PROVENANCE_WORKFLOW}) on GitHub Actions. Nothing was changed.`);
+    }
+    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));
+    if (start < 0)
+        return [];
+    const end = lines.findIndex((line, i) => i > start && line.startsWith("## "));
+    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 {
+        fsyncSync(fd);
+    }
+    finally {
+        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));
+}
+function tableDigest(db, name, columns) {
+    const rows = db.prepare("SELECT " + columns.map(quote).join(",") + " FROM " + quote(name)).all().map(r => JSON.stringify(r)).sort();
+    return { count: rows.length, hash: sha(rows.join("\n")) };
+}
+/** Every historical row, table by table (deploy-browser's rehearsal check). */
+export function historySnapshot(db) {
+    return db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name <> 'schema_version' ORDER BY name").all()
+        .map(row => String(row["name"])).map(name => {
+        const columns = db.prepare("PRAGMA table_info(" + quote(name) + ")").all().map(r => String(r["name"]));
+        return { name, columns, ...tableDigest(db, name, columns) };
+    });
+}
+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"])));
+    return before.filter(t => {
+        if (!tables.has(t.name))
+            return true;
+        const present = new Set(db.prepare("PRAGMA table_info(" + quote(t.name) + ")").all().map(r => String(r["name"])));
+        if (t.columns.some(c => !present.has(c)))
+            return true;
+        const after = tableDigest(db, t.name, t.columns);
+        return after.count !== t.count || after.hash !== t.hash;
+    }).map(t => t.name);
+}
+async function rehearse(j, system, source) {
+    const copy = join(j.stageDir, `rehearsal.${randomUUID()}.db`);
+    copyFileSync(source, copy);
+    chmodSync(copy, 0o600);
+    try {
+        let db = new (sqlite().DatabaseSync)(copy, { readOnly: true });
+        const before = historySnapshot(db);
+        db.close();
+        await system.rehearse(j.to.dist, copy);
+        db = new (sqlite().DatabaseSync)(copy, { readOnly: true });
+        try {
+            const changed = changedHistory(db, before);
+            if (changed.length > 0)
+                throw new Refusal(`Toolroll ${j.to.version} would change saved history in ${changed.slice(0, 4).join(", ")}${changed.length > 4 ? ` and ${changed.length - 4} more` : ""}. Nothing was changed.`);
+            if (db.prepare("PRAGMA integrity_check").get()?.["integrity_check"] !== "ok")
+                throw new Refusal(`The rehearsed database failed its integrity check under ${j.to.version}. Nothing was changed.`);
+        }
+        finally {
+            db.close();
+        }
+        return { tables: before.length, rows: before.reduce((n, t) => n + t.count, 0) };
+    }
+    finally {
+        for (const suffix of ["", "-wal", "-shm"])
+            rmSync(copy + suffix, { force: true });
+    }
+}
+/** Put a verified backup in place of a live SQLite file. Only once the service's processes are gone. */
+function restoreFile(live, backup, hash, what) {
+    if (fileHash(backup) !== hash)
+        throw Error(`The retained ${what} backup changed. It was not put back.`);
+    const temp = `${live}.${randomUUID()}.restore`;
+    copyFileSync(backup, temp);
+    chmodSync(temp, 0o600);
+    for (const suffix of ["-wal", "-shm"])
+        rmSync(live + suffix, { force: true });
+    durableRename(temp, live);
+}
+/** 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);
+}
+/** A private copy of the live database before a restore replaces it: what the new version wrote is kept, and named.
+ * A database that cannot be read (corrupt, unreadable) is not copied: it is moved aside whole, with its WAL, and the
+ * restore goes ahead. */
+async function keepAside(j) {
+    const id = randomUUID().slice(0, 8), kept = join(j.stageDir, `orders.kept.${id}.db`);
+    try {
+        const db = new (sqlite().DatabaseSync)(j.databaseFile, { readOnly: true });
+        try {
+            await sqlite().backup(db, kept);
+        }
+        finally {
+            db.close();
+        }
+        chmodSync(kept, 0o600);
+        fsyncPath(kept);
+        j.keptAside = kept;
+        delete j.keptAsideUnreadable;
+    }
+    catch {
+        rmSync(kept, { force: true });
+        // Already moved aside by an earlier attempt: that path stays the one named.
+        if (!existsSync(j.databaseFile))
+            return;
+        const unreadable = join(j.stageDir, `orders.unreadable.${id}.db`);
+        for (const suffix of ["-wal", "-shm", ""])
+            if (existsSync(j.databaseFile + suffix))
+                durableRename(j.databaseFile + suffix, unreadable + suffix);
+        j.keptAside = unreadable;
+        j.keptAsideUnreadable = true;
+    }
+}
+// ---- 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) ?? [] };
+}
+/** Stop the service and every 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;
+    const pidsOf = async (unit, earlier) => [...new Set([...earlier, ...await system.servicePids(unit)])];
+    if (main)
+        j.service = { unit: main, pids: await pidsOf(main, j.service?.unit === main ? j.service.pids : []) };
+    const watching = [];
+    for (const unit of watches)
+        watching.push({ unit, pids: await pidsOf(unit, j.watches?.find(w => w.unit === unit)?.pids ?? []) });
+    if (watching.length > 0)
+        j.watches = watching;
+    save(j, j.phase, j.detail, system.now());
+    for (const unit of [main, ...watches])
+        if (unit)
+            await system.stopService(unit);
+    const pids = [...(main ? j.service.pids : []), ...watching.flatMap(w => w.pids)];
+    const deadline = system.now().getTime() + (system.exitTimeoutMs ?? 60_000);
+    for (;;) {
+        const alive = pids.filter(pid => system.processAlive(pid));
+        if (alive.length === 0)
+            return;
+        if (system.now().getTime() >= deadline)
+            throw Error(`The background service is still running (process ${alive.join(", ")}) after it was stopped. Nothing was replaced.`);
+        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)
+        throw new Refusal(`No background service or toolroll command runs ${j.from.version} from ${j.from.dist}, so there is nothing to switch. Nothing was changed.`);
+    const real = (path) => { try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    } };
+    const root = real(dirname(j.from.dist)) ?? dirname(j.from.dist);
+    for (const link of links) {
+        if (!lstatSync(link).isSymbolicLink())
+            throw new Refusal(`${link} is not a link Toolroll can switch (a shim or a copy), so it would keep running ${j.from.version}. Remove it or reinstall with npm, then update again. Nothing was changed.`);
+        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);
+        }
+        catch {
+            throw new Refusal(`${dirname(link)} cannot be written, so ${link} would keep running ${j.from.version}. Make that folder writable, then update again. Nothing was changed.`);
+        }
+    }
+    for (const one of [unit, ...watches])
+        if (one && !readFileSync(one, "utf8").includes(j.from.dist))
+            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: [] };
+        if (unit) {
+            const saved = join(j.stageDir, "service.saved.plist");
+            writeFileDurably(saved, readFileSync(unit));
+            j.switched.unit = { path: unit, saved };
+        }
+        for (const [i, path] of watches.entries()) {
+            const saved = join(j.stageDir, `watch.${i}.saved.plist`);
+            writeFileDurably(saved, readFileSync(path));
+            j.switched.watches.push({ path, saved });
+        }
+        save(j, "switching", `Pointing ${unit || watches.length > 0 ? "the service and " : ""}the toolroll and standing-orders commands at ${j.to.version}.`, system.now());
+    }
+    const { main, watches } = unitsOf(j);
+    if (j.restoreFrom && !j.switched.databaseRestored) {
+        await stopServices(j, system, main, watches);
+        refuseWhileWatching(j, system, true);
+        restoreDatabase(j, j.restoreFrom);
+        gate(j);
+        j.switched.databaseRestored = true;
+        save(j, "switching", j.detail, system.now());
+    }
+    for (const one of [j.switched.unit, ...j.switched.watches ?? []])
+        if (one)
+            writeFileDurably(one.path, readFileSync(one.saved, "utf8").replaceAll(j.from.dist, j.to.dist), 0o644);
+    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 ?? []]) {
+        if (!one || !existsSync(one.saved))
+            continue;
+        try {
+            writeFileDurably(one.path, readFileSync(one.saved), 0o644);
+        }
+        catch (error) {
+            stuck.push(`${one.path} (${error.message})`);
+        }
+    }
+    for (const link of j.switched?.links ?? []) {
+        try {
+            pointLink(link.path, link.previous);
+        }
+        catch (error) {
+            stuck.push(`${link.path} (${error.message})`);
+        }
+    }
+    return stuck;
+}
+function gate(j) {
+    const db = new (sqlite().DatabaseSync)(j.databaseFile);
+    try {
+        db.exec("PRAGMA busy_timeout=5000");
+        installUpdateGate(db, j.id);
+        freezeUpdateGate(db, j.id);
+    }
+    finally {
+        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 {
+        db.exec("PRAGMA busy_timeout=5000");
+        if (updateGateOwned(db, j.id))
+            removeUpdateGate(db, j.id);
+        else
+            removeCodingUpdateGate(db, j.id);
+    }
+    finally {
+        db.close();
+    }
+}
+function ungateCoding(j) {
+    const db = new (sqlite().DatabaseSync)(j.databaseFile);
+    try {
+        db.exec("PRAGMA busy_timeout=5000");
+        removeCodingUpdateGate(db, j.id);
+    }
+    finally {
+        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 {
+        const db = new (sqlite().DatabaseSync)(j.databaseFile, { readOnly: true });
+        try {
+            row = db.prepare("SELECT runner, repo FROM watch_lease WHERE expires_at > ? LIMIT 1").get(system.now().toISOString());
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (error) {
+        if (!restoring)
+            throw error;
+        row = undefined;
+    }
+    if (!row)
+        return;
+    const what = `toolroll up is running for ${String(row["repo"])} (${String(row["runner"])}).`;
+    throw new Refusal(restoring ? `${what} The database was not put back under it; stop it first.` : `${what} Stop it first; ${j.kind === "update" ? "an update replaces the version it runs" : "a rollback replaces the database"}. Nothing was changed.`);
+}
+function nextAt(hhmm, now) {
+    const [h, m] = hhmm.split(":").map(Number);
+    const at = new Date(now);
+    at.setHours(h, m, 0, 0);
+    if (at <= now)
+        at.setDate(at.getDate() + 1);
+    return at;
+}
+function newJournal(kind, o, now) {
+    const id = randomUUID(), stageDir = join(resolve(o.stateDir), "staged-upgrades", `${kind === "update" ? "release" : "rollback"}-${o.to.version}-${id.slice(0, 8)}`);
+    mkdirSync(stageDir, { recursive: true, mode: 0o700 });
+    chmodSync(stageDir, 0o700);
+    return { version: 1, id, kind, stateDir: resolve(o.stateDir), databaseFile: o.databaseFile, stageDir, from: o.from, to: o.to, when: o.when, at: o.at, actor: o.actor, phase: "scheduled", detail: "", steps: [], startedAt: now.toISOString(), updatedAt: now.toISOString() };
+}
+function assertNoneActive(stateDir) {
+    const existing = readRuntimeUpdate(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).` };
+    if (!o.allowDowngrade && !isNewer(o.version, o.current.version))
+        return { refused: `Toolroll ${o.version} is not newer than ${o.current.version}. To go back to an older release, run toolroll update --version ${o.version} --allow-downgrade.` };
+    try {
+        assertNoneActive(o.stateDir);
+        keepCompletedUpdate(o.stateDir);
+    }
+    catch (error) {
+        return { refused: error.message };
+    }
+    const at = o.when === "at" ? nextAt(o.at ?? "03:00", now).toISOString() : null;
+    const j = newJournal("update", { stateDir: o.stateDir, databaseFile: o.databaseFile, from: o.current, to: { version: o.version, dist: "" }, when: o.when, at, actor: o.actor }, now);
+    save(j, "scheduled", at ? `Scheduled for ${at}.` : "Starting.", now);
+    if (at)
+        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 };
+    const j = prepareRuntimeUpdate(o, system.now());
+    if ("refused" in j)
+        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 {
+        assertNoneActive(o.stateDir);
+        keepCompletedUpdate(o.stateDir);
+        last = lastCompletedUpdate(o.stateDir);
+    }
+    catch (error) {
+        return { ok: false, phase: "refused", message: error.message, journal: null };
+    }
+    if (!last || !last.backupPath || !last.backupHash)
+        return { ok: false, phase: "refused", message: "There is no completed update to roll back.", journal: null };
+    if (!existsSync(join(last.from.dist, "bin.js")) || !existsSync(last.backupPath) || (last.codingBackupPath && !existsSync(last.codingBackupPath)))
+        return { ok: false, phase: "refused", message: `The previous runtime (${last.from.version}) or its backup is no longer on this machine. Nothing was changed.`, journal: null };
+    const now = system.now();
+    const j = newJournal("rollback", { stateDir: o.stateDir, databaseFile: o.databaseFile, from: last.to, to: last.from, when: o.when, at: null, actor: o.actor }, now);
+    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)
+        return { ok: true, phase: j?.phase ?? "complete", message: "The update this job was started for is no longer the saved one. Nothing was changed.", journal: j };
+    if (!j || runtimeUpdateTerminal(j.phase))
+        return { ok: true, phase: j?.phase ?? "complete", message: "No update is in progress.", journal: j };
+    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);
+}
+export function requestRuntimeUpdateCancel(stateDir, now = new Date()) {
+    const j = readRuntimeUpdate(stateDir);
+    if (!j || runtimeUpdateTerminal(j.phase))
+        return "No update is in progress.";
+    if (!["scheduled", "verifying", "draining"].includes(j.phase))
+        return `The update to ${j.to.version} is past the point it can be cancelled (${j.phase}); it will finish or restore on its own.`;
+    durableJson(cancelFile(j), { id: j.id, action: "cancel" });
+    // 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)
+        return `Cancelling the update to ${j.to.version}. Nothing is switched; new work resumes.`;
+    try {
+        try {
+            ungate(j);
+        }
+        catch { /* no pause yet */ }
+        if (j.kind === "update")
+            rmSync(join(j.stageDir, "runtime"), { recursive: true, force: true });
+        const noun = j.kind === "update" ? "update" : "rollback";
+        save(j, "cancelled", `The ${noun} to ${j.to.version} was cancelled. Nothing changed; new work resumed.`, now);
+        try {
+            ledger(j.databaseFile, now, j.actor, `toolroll ${noun} cancelled`, "cancelled", `${j.from.version} → ${j.to.version}`);
+        }
+        catch { /* the journal still says what happened */ }
+        return `Cancelled the ${noun} to ${j.to.version}. Nothing was switched; new work resumes.`;
+    }
+    finally {
+        lock.close();
+    }
+}
+const cancelRequested = (j) => existsSync(cancelFile(j));
+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 };
+    const at = (phase) => UPDATE_STEPS.indexOf(phase);
+    const step = (phase, detail) => { save(j, phase, detail, system.now()); system.checkpoint?.(phase); };
+    const noun = j.kind === "update" ? "update" : "rollback";
+    const verb = j.kind === "update" ? `${j.from.version} → ${j.to.version}` : `${j.from.version} → ${j.to.version} (back)`;
+    const finish = (ok, phase, message, action, outcome, detail) => {
+        save(j, phase, message, system.now());
+        try {
+            ledger(j.databaseFile, system.now(), j.actor, action, outcome, detail);
+        }
+        catch { /* the journal still says what happened */ }
+        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))
+                    return finish(true, "cancelled", `The ${noun} to ${j.to.version} was cancelled before it started. Nothing changed.`, `toolroll ${noun} cancelled`, "cancelled", verb);
+                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.");
+        if (resumedAt < at("switching")) {
+            if (resumedAt <= at("verifying")) {
+                step("verifying", j.kind === "update" ? `Downloading and verifying Toolroll ${j.to.version}.` : `Checking the previous runtime (${j.to.version}) and its backup.`);
+                if (j.kind === "update")
+                    await verify(j, system);
+                else if (fileHash(j.restoreFrom.path) !== j.restoreFrom.hash || (j.restoreFrom.codingPath && fileHash(j.restoreFrom.codingPath) !== j.restoreFrom.codingHash))
+                    throw new Refusal("The update's backup changed since it was made. Nothing was changed.");
+            }
+            const { unit, watches } = switchable(j, system);
+            if (!unit && watches.length === 0)
+                refuseWhileWatching(j, system);
+            if (resumedAt <= at("draining")) {
+                step("draining", j.when === "now" ? "Checking that no work is running, then pausing new work." : "Pausing new work and letting running work finish. Nothing is being cancelled.");
+                await drain(j, system);
+                if (cancelRequested(j)) {
+                    ungate(j);
+                    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 {
+                assertCodingUpdateStopped(db);
+            }
+            finally {
+                db.close();
+            }
+            const backup = join(j.stageDir, existsSync(join(j.stageDir, "orders.backup.db")) ? `orders.backup.${randomUUID()}.db` : "orders.backup.db");
+            j.backupHash = await verifiedDatabaseBackup(j.databaseFile, backup, j.id, async () => { await codingBackup(j); });
+            j.backupPath = backup;
+            save(j, "backing-up", "Database and coding catalog backed up.", system.now());
+            step("rehearsing", `Rehearsing ${j.to.version} on a copy of the database.`);
+            j.rehearsal = await rehearse(j, system, j.restoreFrom?.path ?? j.backupPath);
+        }
+        if (resumedAt <= at("switching")) {
+            step("switching", `Switching to ${j.to.version}.`);
+            await switchRuntime(j, system);
+        }
+        if (resumedAt <= at("restarting")) {
+            const { main, watches } = unitsOf(j);
+            step("restarting", main || watches.length > 0 ? "Restarting the background service." : "No background service runs here; the commands now start the new version.");
+            for (const unit of [main, ...watches])
+                if (unit)
+                    await system.restartService(unit);
+        }
+        step("health", `Checking that ${j.to.version} is running and healthy.`);
+        const deadline = system.now().getTime() + (system.healthTimeoutMs ?? 90_000);
+        let healthy = false;
+        do {
+            healthy = await system.healthy(j);
+            if (!healthy)
+                await system.sleep(1000);
+        } while (!healthy && system.now().getTime() < deadline);
+        if (!healthy)
+            throw Error(`Toolroll ${j.to.version} did not pass its health check.`);
+        ungate(j);
+        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 */ }
+        try {
+            pruneRuntimes(j.stateDir, [j.to.dist, j.from.dist]);
+        }
+        catch { /* an old runtime left on disk is harmless */ }
+        return done;
+    }
+    catch (error) {
+        if (error.simulatedCrash)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        j.error = message.slice(0, 1500);
+        if (!j.switched) {
+            try {
+                ungate(j);
+            }
+            catch { /* no gate yet, or the database is unreadable */ }
+            // Nothing uses a refused download; the database backup is kept.
+            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 ?? []).map(w => w.unit)]) {
+                if (!unit)
+                    continue;
+                try {
+                    await system.restartService(unit);
+                }
+                catch (again) {
+                    restarted += ` ${unit === j.service?.unit ? "The background service" : `The watch ${basename(unit, ".plist")}`} did not start again: ${again.message}`;
+                }
+            }
+            const refused = error instanceof Refusal;
+            return finish(false, "refused", (refused ? message : `The ${noun} stopped before anything was switched: ${message} Nothing changed; new work resumed.`) + restarted, refused ? `toolroll ${noun} refused` : `toolroll ${noun} failed`, refused ? "refused" : "failed", `${verb}: ${message}`);
+        }
+        return await restore(j, system, finish, verb, message);
+    }
+    finally {
+        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))
+        return;
+    const target = join(j.stageDir, existsSync(join(j.stageDir, "coding.backup.sqlite")) ? `coding.backup.${randomUUID()}.sqlite` : "coding.backup.sqlite");
+    await backupCodingCatalog(source, target, j.id);
+    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);
+        if (!j.backupPath || !j.backupHash)
+            throw Error("No verified backup was recorded.");
+        if (!j.restoredDatabase) {
+            refuseWhileWatching(j, system, true);
+            // 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.
+            await keepAside(j);
+            save(j, "rolling-back", j.detail, system.now());
+            restoreDatabase(j, { path: j.backupPath, hash: j.backupHash, ...(j.codingBackupPath && j.codingBackupHash ? { codingPath: j.codingBackupPath, codingHash: j.codingBackupHash } : {}) });
+            j.restoredDatabase = true;
+            save(j, "rolling-back", j.detail, system.now());
+        }
+        for (const unit of [main, ...watches])
+            if (unit)
+                await system.restartService(unit);
+        const kept = !j.keptAside ? "" : j.keptAsideUnreadable ? ` The live database could not be read, so it was left as it was at ${j.keptAside}.` : ` Anything written since the backup is kept in ${j.keptAside}.`;
+        const restored = `${why} Toolroll ${j.from.version} and its database were restored.${kept}`;
+        if (stuck.length > 0)
+            return finish(false, "needs-attention", `${restored} ${stuck.join("; ")} could not be pointed back at ${j.from.version}. Make ${stuck.length === 1 ? "its folder" : "those folders"} writable, then run toolroll update --resume.`, `toolroll ${noun} failed`, "needs attention", `${verb}: ${why} / ${stuck.join("; ")}`.slice(0, 300));
+        return finish(false, "restored", restored, `toolroll ${noun} failed`, "restored", `${verb}: ${why}`.slice(0, 300));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return finish(false, "needs-attention", `${why} Restoring the previous version also failed: ${message} Run toolroll update --resume to try again; the backup is kept at ${j.backupPath ?? "(none)"}.`, `toolroll ${noun} failed`, "needs attention", `${verb}: ${why} / ${message}`.slice(0, 300));
+    }
+}
+async function verify(j, system) {
+    const release = await system.release(j.to.version);
+    if (release.version !== j.to.version)
+        throw new Refusal(`The registry answered with ${release.version}, not ${j.to.version}. Nothing was changed.`);
+    if (!release.attestations)
+        throw new Refusal(`Toolroll ${j.to.version} has no npm provenance, so it cannot be verified. Nothing was changed.`);
+    if (!onRegistry(release.attestations))
+        throw new Refusal(`Toolroll ${j.to.version}'s provenance is not served by the npm registry (${release.attestations.slice(0, 120)}). Nothing was changed.`);
+    const bytes = await system.download(release.tarball);
+    const sha512 = createHash("sha512").update(bytes).digest();
+    if (release.integrity !== `sha512-${sha512.toString("base64")}`)
+        throw new Refusal(`The downloaded package does not match the registry's checksum. Nothing was changed.`);
+    const provenance = checkProvenance(await system.attestations(release.attestations), j.to.version, sha512.toString("hex"));
+    await system.sigstore(provenance.bundle, { issuer: provenance.issuer, identity: provenance.identity });
+    const runtime = join(j.stageDir, "runtime");
+    mkdirSync(runtime, { recursive: true, mode: 0o700 });
+    j.to.dist = await system.install(runtime, release);
+    if (!j.to.dist.startsWith(runtime + sep) || !existsSync(join(j.to.dist, "bin.js")))
+        throw new Refusal("The staged runtime has no Toolroll command. Nothing was changed.");
+    j.package = { sha512: sha512.toString("hex"), repository: provenance.repository, workflow: provenance.workflow };
+    try {
+        j.notes = releaseNotes(readFileSync(join(dirname(j.to.dist), "CHANGELOG.md"), "utf8"), j.to.version);
+    }
+    catch {
+        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);
+        return at.protocol === "https:" && at.host === registry.host && !at.username && !at.password;
+    }
+    catch {
+        return false;
+    }
+}
+async function drain(j, system) {
+    const db = new (sqlite().DatabaseSync)(j.databaseFile);
+    try {
+        db.exec("PRAGMA busy_timeout=5000");
+        if (j.when === "now") {
+            const running = runningWorkWords(db) ?? lingeringWork(db);
+            if (running)
+                throw new Refusal(`Work is running: ${running}. Nothing was changed. Use When idle to wait for it.`);
+            if (updateAdmissionPaused(db) && !updateGateOwned(db, j.id))
+                throw new Refusal("Another update owns the admission pause. Nothing was changed.");
+            installUpdateGate(db, j.id);
+            if (!freezeUpdateGate(db, j.id)) {
+                removeUpdateGate(db, j.id);
+                throw new Refusal(`Work started just now: ${runningWorkWords(db) ?? "a new run"}. Nothing was changed.`);
+            }
+            return;
+        }
+        installUpdateGate(db, j.id);
+        for (;;) {
+            if (cancelRequested(j))
+                return;
+            const lingering = Object.values(activeUpdateWork(db)).every(n => n === 0) ? lingeringWork(db) : null;
+            if (!lingering && freezeUpdateGate(db, j.id))
+                return;
+            save(j, "draining", `New work is paused. Waiting for ${lingering ?? runningWorkWords(db) ?? "running work"} to finish. Nothing is being cancelled.`, system.now());
+            await system.sleep(2000);
+        }
+    }
+    finally {
+        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");
+    const started = (dir) => { try {
+        return String(JSON.parse(readFileSync(join(dir, "update.json"), "utf8")).startedAt ?? "");
+    }
+    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));
+    }
+    catch {
+        return true;
+    } };
+    const removed = releases.filter(dir => !kept.has(dir) && !holdsKeptAside(dir));
+    for (const dir of removed)
+        rmSync(dir, { recursive: true, force: true });
+    return removed;
+}
+export function runtimeUpdateStatus(stateDir) {
+    let j = null;
+    try {
+        j = readRuntimeUpdate(stateDir);
+    }
+    catch {
+        j = null;
+    }
+    let running = false;
+    if (j && !runtimeUpdateTerminal(j.phase)) {
+        const lock = sqliteLock(join(j.stageDir, "worker.sqlite"));
+        running = lock === null;
+        lock?.close();
+    }
+    const whatsNew = j && j.kind === "update" && j.phase === "complete" && !j.seen ? { version: j.to.version, notes: j.notes ?? [] } : null;
+    return { journal: j, running, whatsNew };
+}
+export function markWhatsNewSeen(stateDir) {
+    const j = readRuntimeUpdate(stateDir);
+    if (!j || j.seen || j.phase !== "complete")
+        return;
+    j.seen = true;
+    durableJson(journalFile(stateDir), j);
+    durableJson(join(j.stageDir, "update.json"), j);
+}
+const exec = (command, args, options = {}) => spawnSync(command, args, { encoding: "utf8", timeout: options.timeout ?? 300_000, maxBuffer: 16 * 1024 * 1024, ...(options.cwd ? { cwd: options.cwd } : {}), ...(options.input !== undefined ? { input: options.input } : {}) });
+const LABELS = ["com.toolroll.browser", "com.standing-orders.browser"];
+export function currentRuntime(version) {
+    return { version, dist: dirname(fileURLToPath(import.meta.url)) };
+}
+async function json(url) {
+    const response = await fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(30_000) });
+    if (!response.ok)
+        throw new Refusal(`${url} answered ${response.status}. Nothing was changed.`);
+    return response.json();
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        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));
+    const unitFor = (from) => {
+        for (const label of LABELS) {
+            const unit = join(home, "Library", "LaunchAgents", `${label}.plist`);
+            if (existsSync(unit) && readFileSync(unit, "utf8").includes(from.dist))
+                return unit;
+        }
+        return null;
+    };
+    const labelOf = (unit) => basename(unit, ".plist");
+    const domain = `gui/${typeof process.getuid === "function" ? process.getuid() : userInfo().uid}`;
+    const definition = (unit) => {
+        const content = readFileSync(unit, "utf8");
+        const logPath = content.match(/<key>StandardOutPath<\/key>\s*<string>([^<]+)<\/string>/)?.[1] ?? join(dirname(unit), `${labelOf(unit)}.log`);
+        return { platform: "darwin", label: labelOf(unit), unitPath: unit, unitContent: content, logPath, bin: process.execPath, entry: null };
+    };
+    return {
+        now: () => new Date(),
+        sleep: ms => new Promise(done => setTimeout(done, ms)),
+        release: async (version) => {
+            const body = await json(`${REGISTRY}/${NAME}/${version}`);
+            return { version: String(body.version ?? ""), tarball: String(body.dist?.tarball ?? ""), integrity: String(body.dist?.integrity ?? ""), attestations: body.dist?.attestations?.url ?? null };
+        },
+        download: async (url) => {
+            if (!url.startsWith(`${REGISTRY}/`))
+                throw new Refusal("The package is not hosted on the npm registry. Nothing was changed.");
+            const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+            if (!response.ok)
+                throw new Refusal(`The package download answered ${response.status}. Nothing was changed.`);
+            return new Uint8Array(await response.arrayBuffer());
+        },
+        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 });
+            if (installed.status !== 0)
+                throw new Refusal(`npm could not install Toolroll ${release.version}: ${(installed.stderr || installed.stdout).trim().slice(-400)} Nothing was changed.`);
+            let locked;
+            try {
+                locked = JSON.parse(readFileSync(join(runtime, "package-lock.json"), "utf8")).packages?.[`node_modules/${NAME}`];
+            }
+            catch {
+                locked = undefined;
+            }
+            if (locked?.version !== release.version || locked.integrity !== release.integrity || !String(locked.resolved ?? "").startsWith(`${REGISTRY}/`))
+                throw new Refusal(`npm installed different bytes than the verified Toolroll ${release.version}. Nothing was changed.`);
+            const signatures = sh("npm", ["audit", "signatures", "--no-color", registry], { cwd: runtime });
+            const output = `${signatures.stdout}\n${signatures.stderr}`;
+            if (signatures.status !== 0)
+                throw new Refusal(`npm could not verify the package signatures: ${output.trim().slice(-400)} Nothing was changed.`);
+            if (!/\b[1-9]\d* packages? ha(?:s|ve) (?:a )?verified attestations?\b/.test(output))
+                throw new Refusal(`npm did not verify Toolroll ${release.version}'s provenance attestation. Nothing was changed.`);
+            return join(runtime, "node_modules", NAME, "dist");
+        },
+        rehearse: async (dist, copy) => {
+            const script = `import(${JSON.stringify(pathToFileURL(join(dist, "store.js")).href)}).then(m => { m.openStore(${JSON.stringify(copy)}).close(); })`;
+            const done = sh(process.execPath, ["--no-warnings", "--input-type=module", "-e", script], { timeout: 600_000 });
+            if (done.status !== 0)
+                throw new Refusal(`The new version could not open a copy of the database: ${(done.stderr || "").trim().slice(-400)} Nothing was changed.`);
+        },
+        commands: () => {
+            const found = new Set();
+            for (const dir of (env["PATH"] ?? "").split(":").filter(Boolean)) {
+                for (const name of [NAME, "standing-orders"]) {
+                    const path = join(dir, name);
+                    try {
+                        lstatSync(path);
+                        found.add(path);
+                    }
+                    catch { /* not here */ }
+                }
+            }
+            return [...found];
+        },
+        sigstore: async (bundle, identity) => {
+            const verifier = findSigstoreVerifier({
+                path: env["PATH"] ?? "", execPath: seams.execPath ?? process.execPath,
+                npmRoot: () => { const root = sh("npm", ["root", "--global", "--no-color"], { timeout: 30_000 }); return root.status === 0 ? root.stdout.trim() : null; },
+            });
+            if (!verifier)
+                throw new Refusal("Toolroll could not find the Sigstore verifier that npm ships (npm 10 or newer), so its provenance cannot be checked. Nothing was changed.");
+            const checked = sh(process.execPath, ["--no-warnings", "-e", SIGSTORE_SCRIPT], { input: JSON.stringify({ verifier, bundle, ...identity }), timeout: 120_000 });
+            if (checked.status !== 0)
+                throw new Refusal(`Sigstore did not verify Toolroll's provenance for ${identity.identity}: ${(checked.stderr || checked.stdout).trim().slice(-400)} Nothing was changed.`);
+        },
+        serviceUnit: from => unitFor(from),
+        watchUnits: from => {
+            const dir = join(home, "Library", "LaunchAgents");
+            let names = [];
+            try {
+                names = readdirSync(dir);
+            }
+            catch {
+                return [];
+            }
+            return names.filter(name => /^com\.(?:toolroll|standing-orders)\.watch\..+\.plist$/.test(name)).map(name => join(dir, name))
+                .filter(unit => { try {
+                return readFileSync(unit, "utf8").includes(from.dist);
+            }
+            catch {
+                return false;
+            } });
+        },
+        servicePids: async (unit) => {
+            const printed = await supervise("launchctl", ["print", `${domain}/${labelOf(unit)}`]);
+            const pid = Number(printed.stdout.match(/\n\s*pid = (\d+)/)?.[1]);
+            return printed.code === 0 && pid > 1 ? [pid] : [];
+        },
+        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.`);
+            }
+        },
+        restartService: async (unit) => {
+            const started = await installLaunchdService(definition(unit), supervise);
+            if (!started.ok)
+                throw Error(`launchctl could not start the service: ${started.message}`);
+        },
+        processAlive: seams.alive ?? processAlive,
+        healthy: async (j) => {
+            const version = sh(process.execPath, [join(j.to.dist, "bin.js"), "--version"], { timeout: 30_000 });
+            if (version.status !== 0 || version.stdout.trim() !== j.to.version)
+                return false;
+            for (const link of j.switched?.links ?? []) {
+                try {
+                    if (realpathSync(link.path) !== realpathSync(join(j.to.dist, "bin.js")))
+                        return false;
+                }
+                catch {
+                    return false;
+                }
+            }
+            const unit = j.switched?.unit?.path;
+            if (!unit)
+                return true;
+            const printed = await supervise("launchctl", ["print", `${domain}/${labelOf(unit)}`]);
+            const pid = Number(printed.stdout.match(/\n\s*pid = (\d+)/)?.[1]);
+            if (!(pid > 1) || !printed.stdout.includes("state = running"))
+                return false;
+            if (!sh("/bin/ps", ["-p", String(pid), "-o", "command="]).stdout.includes(j.to.dist))
+                return false;
+            const port = readFileSync(unit, "utf8").match(/<string>--port<\/string>\s*<string>(\d+)<\/string>/)?.[1];
+            if (!port)
+                return true;
+            const answered = await fetch(`http://127.0.0.1:${port}/login`, { redirect: "manual", signal: AbortSignal.timeout(5000) }).catch(() => null);
+            return answered !== null && answered.status < 500;
+        },
+    };
+}
+/** 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)) {
+            try {
+                if (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name === "npm")
+                    return dir;
+            }
+            catch { /* not the package folder yet */ }
+        }
+        return null;
+    };
+    const candidates = [
+        ...o.path.split(":").filter(dir => isAbsolute(dir)).map(dir => () => { try {
+            return npmPackage(realpathSync(join(dir, "npm")));
+        }
+        catch {
+            return null;
+        } }),
+        () => join(dirname(o.execPath), "..", "lib", "node_modules", "npm"),
+        () => { const root = o.npmRoot(); return root && isAbsolute(root) ? join(root, "npm") : null; },
+    ];
+    for (const candidate of candidates) {
+        const npm = candidate();
+        const verifier = npm ? join(npm, "node_modules", "sigstore") : null;
+        if (verifier && existsSync(join(verifier, "package.json")))
+            return resolve(verifier);
+    }
+    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. */
+function npmPrefixBin() {
+    const answered = exec("npm", ["prefix", "--global", "--no-color"], { timeout: 30_000 });
+    const prefix = answered.status === 0 ? answered.stdout.trim() : "";
+    return isAbsolute(prefix) ? join(prefix, "bin") : null;
+}
+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);
+    const log = join(stateDir, "toolroll-update.log");
+    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 = (seams.npmBin ?? npmPrefixBin)();
+        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 });
+        const started = await installLaunchdService({ platform: "darwin", label: UPDATE_JOB_LABEL, bin: process.execPath, entry: join(dist, "bin.js"), logPath: log, unitPath: jobUnit(home), unitContent: unit }, run);
+        if (!started.ok)
+            throw Error(started.message);
+        return;
+    }
+    const { spawn } = await import("node:child_process");
+    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 */ }
+}
+export const nextScheduledAt = nextAt;