toolroll 0.8.1 → 0.8.2

package/dist/toolroll-update.d.ts

@@ -67,10 +67,12 @@ export type RuntimeUpdateJournal = {
         unit: string;
         pids: number[];
     };
-    /** Each repo's watch daemon that runs this version, recorded the same way: stopped, switched and restarted with the service. */
+    /** Each repo's watch daemon that runs this version, recorded the same way: switched with the service, and stopped and
+     * restarted with it only when launchd had it loaded before the update (`loaded` absent: 0.8.1 stopped every one). */
     watches?: {
         unit: string;
         pids: number[];
+        loaded?: boolean;
     }[];
     /** Recorded before each change so a resumed or failed run knows what to put back. */
     switched?: {
@@ -88,10 +90,15 @@ export type RuntimeUpdateJournal = {
         }[];
         databaseRestored?: boolean;
     };
-    /** What the live database held when a failed run restored its backup: nothing written is lost. */
+    /** What the live database held when a failed run restored its backup: nothing written is lost. The newest of `kept`. */
     keptAside?: string;
     /** The live database could not be read, so it was moved aside whole rather than copied. */
     keptAsideUnreadable?: boolean;
+    /** Every copy kept aside, oldest first: a retried restore adds one and never drops the pointer to an earlier one. */
+    kept?: {
+        path: string;
+        unreadable: boolean;
+    }[];
     /** The restore put the backup back: a retried restore never puts it back again (what was written since belongs to
      * the restored version and would be lost), and it keeps a fresh copy aside before every attempt until then. */
     restoredDatabase?: boolean;
@@ -129,6 +136,8 @@ export type UpdateSystem = {
     }) => Promise<void>;
     /** The processes the service runs now. */
     servicePids: (unit: string) => Promise<number[]>;
+    /** Whether launchd has the service loaded now. */
+    serviceLoaded: (unit: string) => Promise<boolean>;
     /** Unload the service; resolves once launchd no longer has it. */
     stopService: (unit: string) => Promise<void>;
     /** Load and start the service from its definition on disk. */
@@ -138,8 +147,11 @@ export type UpdateSystem = {
     healthTimeoutMs?: number;
     /** How long stopped service processes may take to exit. */
     exitTimeoutMs?: number;
-    /** Fault injection for state-machine tests, never selectable by a flag. */
-    checkpoint?: (phase: RuntimePhase) => void;
+    /** Bytes free for this user in the folder `dir` is on. */
+    freeBytes?: (dir: string) => number;
+    /** Fault injection for state-machine tests, never selectable by a flag. `kept-aside`: the live database was just
+     * kept aside, before the backup is put back. */
+    checkpoint?: (phase: RuntimePhase | "kept-aside") => void;
 };
 export type UpdateOutcome = {
     ok: boolean;
@@ -211,7 +223,10 @@ export declare function startRuntimeRollback(o: {
 export declare function resumeRuntimeUpdate(stateDir: string, system: UpdateSystem, id?: string): Promise<UpdateOutcome>;
 /** A prepared update whose job could not start. */
 export declare function abandonRuntimeUpdate(stateDir: string, id: string, why: string, now: Date): void;
-export declare function requestRuntimeUpdateCancel(stateDir: string, now?: Date): string;
+/** `locked`: a test's seam, called once the updater's lock is held and before the journal is read again. */
+export declare function requestRuntimeUpdateCancel(stateDir: string, now?: Date, seams?: {
+    locked?: () => void;
+}): string;
 /** 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 declare function pruneRuntimes(stateDir: string, keep: readonly string[]): string[];
@@ -223,6 +238,11 @@ export type RuntimeUpdateStatus = {
         version: string;
         notes: string[];
     } | null;
+    /** The last completed update `--rollback` returns from, whatever was attempted since. */
+    lastUpdate: {
+        from: string;
+        to: string;
+    } | null;
 };
 export declare function runtimeUpdateStatus(stateDir: string): RuntimeUpdateStatus;
 export declare function markWhatsNewSeen(stateDir: string): void;
@@ -261,7 +281,7 @@ export declare function launchRuntimeUpdate(args: {
     home?: string;
     run?: SupervisorRunner;
     platform?: NodeJS.Platform;
-    npmBin?: () => string | null;
+    npmBin?: () => Promise<string | null>;
 }): Promise<void>;
 /** The job's last act: its definition goes, so nothing can start it again. Only the definition for this id. */
 export declare function retireUpdateJob(id: string, home?: string): void;

package/dist/toolroll-update.js

@@ -24,7 +24,7 @@
  */
 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 { accessSync, chmodSync, closeSync, constants, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statfsSync, 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";
@@ -115,6 +115,9 @@ function save(j, phase, detail, now) {
 /** 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);
     try {
         db.exec("PRAGMA busy_timeout=5000");
@@ -333,17 +336,53 @@ 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. */
+/** 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.`);
     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);
+    try {
+        copyFileSync(backup, temp);
+        chmodSync(temp, 0o600);
+        for (const suffix of ["-wal", "-shm"])
+            rmSync(live + suffix, { force: true });
+        durableRename(temp, live);
+    }
+    finally {
+        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.");
+    if (from.codingPath && fileHash(from.codingPath) !== from.codingHash)
+        throw Error("The retained coding catalog backup changed. Nothing was put back; the live database is as it was.");
+    const size = (file) => { try {
+        return statSync(file).size;
+    }
+    catch {
+        return 0;
+    } };
+    const live = size(j.databaseFile) + size(`${j.databaseFile}-wal`);
+    const needs = new Map();
+    const need = (dir, bytes) => { const dev = statSync(dir).dev; const at = needs.get(dev) ?? { dir, bytes: 0 }; at.bytes += bytes; needs.set(dev, at); };
+    need(j.stageDir, live);
+    need(dirname(j.databaseFile), size(from.path) + (from.codingPath ? size(from.codingPath) : 0));
+    const free = system.freeBytes ?? freeBytes;
+    for (const { dir, bytes } of needs.values()) {
+        const available = free(dir);
+        if (available < bytes)
+            throw Error(`${dir} has ${megabytes(available)} free and the restore needs ${megabytes(bytes)}. Nothing was put back; the live database is as it was. Free some space, then run toolroll update --resume.`);
+    }
+}
+function freeBytes(dir) {
+    const fs = statfsSync(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");
@@ -351,10 +390,47 @@ function restoreDatabase(j, from) {
         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 }] : []);
+}
+function recordKept(j, path, unreadable) {
+    j.kept = [...keptOf(j), { path, unreadable }];
+    j.keptAside = path;
+    if (unreadable)
+        j.keptAsideUnreadable = true;
+    else
+        delete j.keptAsideUnreadable;
+}
+function forgetKept(j, path) {
+    j.kept = keptOf(j).filter(one => one.path !== path);
+    const newest = j.kept[j.kept.length - 1];
+    if (newest) {
+        j.keptAside = newest.path;
+        if (newest.unreadable)
+            j.keptAsideUnreadable = true;
+        else
+            delete j.keptAsideUnreadable;
+    }
+    else {
+        delete j.keptAside;
+        delete j.keptAsideUnreadable;
+    }
+}
 /** 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. */
+ * 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`);
     try {
         const db = new (sqlite().DatabaseSync)(j.databaseFile, { readOnly: true });
@@ -366,29 +442,47 @@ async function keepAside(j) {
         }
         chmodSync(kept, 0o600);
         fsyncPath(kept);
-        j.keptAside = kept;
-        delete j.keptAsideUnreadable;
+        recordKept(j, kept, false);
+        return [];
     }
-    catch {
+    catch (error) {
         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;
+        if (!unreadableDatabase(error))
+            throw Error(`The live database could not be copied aside before the restore (${error.message || "no reason given"}). It was left as it was, and nothing was put back.`);
     }
+    const unreadable = join(j.stageDir, `orders.unreadable.${id}.db`);
+    const moved = [];
+    try {
+        for (const suffix of ["-wal", "-shm", ""]) {
+            if (!existsSync(j.databaseFile + suffix))
+                continue;
+            durableRename(j.databaseFile + suffix, unreadable + suffix);
+            moved.push({ from: j.databaseFile + suffix, to: unreadable + suffix });
+        }
+    }
+    catch (error) {
+        moveBack(moved);
+        throw Error(`The unreadable live database could not be moved aside (${error.message}). It was left as it was, and nothing was put back.`);
+    }
+    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) ?? [] };
 }
-/** 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. */
+/** 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;
@@ -396,12 +490,16 @@ async function stopServices(j, system, main, watches) {
     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 ?? []) });
+    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 });
+    }
     if (watching.length > 0)
         j.watches = watching;
     save(j, j.phase, j.detail, system.now());
-    for (const unit of [main, ...watches])
+    for (const unit of [main, ...loadedWatches(j, watches)])
         if (unit)
             await system.stopService(unit);
     const pids = [...(main ? j.service.pids : []), ...watching.flatMap(w => w.pids)];
@@ -475,6 +573,7 @@ async function switchRuntime(j, system) {
     if (j.restoreFrom && !j.switched.databaseRestored) {
         await stopServices(j, system, main, watches);
         refuseWhileWatching(j, system, true);
+        assertRestorable(j, j.restoreFrom, system);
         restoreDatabase(j, j.restoreFrom);
         gate(j);
         j.switched.databaseRestored = true;
@@ -653,31 +752,45 @@ export function abandonRuntimeUpdate(stateDir, id, why, now) {
     if (j?.id === id && j.phase === "scheduled")
         save(j, "refused", why, now);
 }
-export function requestRuntimeUpdateCancel(stateDir, now = new Date()) {
+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))
         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" });
+    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.includes(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)
+    if (!lock) {
+        durableJson(cancelFile(j), { id: j.id, action: "cancel" });
         return `Cancelling the update to ${j.to.version}. Nothing is switched; new work resumes.`;
+    }
     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.";
+        if (held.id !== j.id)
+            return "A different update was saved while cancelling. Nothing was cancelled.";
+        if (!CANCELLABLE.includes(held.phase))
+            return tooLate(held);
+        durableJson(cancelFile(held), { id: held.id, action: "cancel" });
         try {
-            ungate(j);
+            ungate(held);
         }
         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);
+        if (held.kind === "update")
+            rmSync(join(held.stageDir, "runtime"), { recursive: true, force: true });
+        const noun = held.kind === "update" ? "update" : "rollback";
+        save(held, "cancelled", `The ${noun} to ${held.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}`);
+            ledger(held.databaseFile, now, held.actor, `toolroll ${noun} cancelled`, "cancelled", `${held.from.version} → ${held.to.version}`);
         }
         catch { /* the journal still says what happened */ }
-        return `Cancelled the ${noun} to ${j.to.version}. Nothing was switched; new work resumes.`;
+        return `Cancelled the ${noun} to ${held.to.version}. Nothing was switched; new work resumes.`;
     }
     finally {
         lock.close();
@@ -757,7 +870,7 @@ async function driveRuntimeUpdate(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])
+            for (const unit of [main, ...loadedWatches(j, watches)])
                 if (unit)
                     await system.restartService(unit);
         }
@@ -805,7 +918,7 @@ async function driveRuntimeUpdate(j, system) {
                 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)]) {
+            for (const unit of [j.service?.unit, ...(j.watches ?? []).filter(w => w.loaded !== false).map(w => w.unit)]) {
                 if (!unit)
                     continue;
                 try {
@@ -849,18 +962,34 @@ async function restore(j, system, finish, verb, why) {
             throw Error("No verified backup was recorded.");
         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.
-            await keepAside(j);
+            const moved = 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 } : {}) });
+            try {
+                system.checkpoint?.("kept-aside");
+                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);
+                    save(j, "rolling-back", j.detail, system.now());
+                }
+                throw error;
+            }
             j.restoredDatabase = true;
             save(j, "rolling-back", j.detail, system.now());
         }
-        for (const unit of [main, ...watches])
+        for (const unit of [main, ...loadedWatches(j, 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 copies = keptOf(j), readable = copies.filter(one => !one.unreadable).map(one => one.path), unreadable = copies.filter(one => one.unreadable).map(one => one.path);
+        const kept = (unreadable.length > 0 ? ` The live database could not be read, so it was left as it was at ${unreadable.join(" and ")}.` : "") + (readable.length > 0 ? ` Anything written since the backup is kept in ${readable.join(" and ")}.` : "");
         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));
@@ -983,7 +1112,14 @@ export function runtimeUpdateStatus(stateDir) {
         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 };
+    let last = null;
+    try {
+        last = lastCompletedUpdate(stateDir);
+    }
+    catch {
+        last = null;
+    }
+    return { journal: j, running, whatsNew, lastUpdate: last ? { from: last.from.version, to: last.to.version } : null };
 }
 export function markWhatsNewSeen(stateDir) {
     const j = readRuntimeUpdate(stateDir);
@@ -1126,6 +1262,7 @@ export function machineSystem(home = homedir(), env = process.env, seams = {}) {
                 return false;
             } });
         },
+        serviceLoaded: async (unit) => (await supervise("launchctl", ["print", `${domain}/${labelOf(unit)}`])).code === 0,
         servicePids: async (unit) => {
             const printed = await supervise("launchctl", ["print", `${domain}/${labelOf(unit)}`]);
             const pid = Number(printed.stdout.match(/\n\s*pid = (\d+)/)?.[1]);
@@ -1214,10 +1351,11 @@ const jobUnit = (home) => join(home, "Library", "LaunchAgents", `${UPDATE_JOB_LA
  * 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() : "";
+/** 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() : "";
     return isAbsolute(prefix) ? join(prefix, "bin") : null;
 }
 export async function launchRuntimeUpdate(args, seams = {}) {
@@ -1229,7 +1367,7 @@ export async function launchRuntimeUpdate(args, seams = {}) {
         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 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 });
         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);

package/dist/worktree.d.ts

@@ -233,23 +233,37 @@ export declare class WorktreePool {
         message: string;
     }>;
     /**
-     * Keep storage in check: remove the working copies nobody needs any more.
-     * A checkout goes when it was released `keepMs` ago or longer, nothing
-     * holds it, it is clean (build output that .gitignore hides is not work),
-     * everything its HEAD reaches is on a branch, tag or remote, and it isn't the
-     * checkout of one of `keep()`'s branches (those unfinished tasks work on or
-     * would come back to, read afresh before each removal), by its branch or by
-     * the name a lease of that branch would give it under any root. Only the
-     * working copy goes: its branch, and so every commit, stays, and a later
-     * lease of the same branch makes a new one. At most `max` go per pass.
+     * Whether a let-go checkout could go without losing anything: clean (build output that .gitignore hides is not
+     * work, and neither are the files Toolroll itself wrote in there), and everything its HEAD reaches on a branch, tag
+     * or remote. Reads only.
      */
-    prune(repo: string, now: Date, keepMs: number, keep: () => readonly string[], max?: number): Promise<{
+    inspect(path: string): Promise<"clean" | KeptWhy>;
+    /**
+     * Keep storage in check: remove the working copies nobody needs any more. Of `rows`, a checkout goes when it is
+     * let go, nothing holds it, `wanted` says it may go (asked again right before it goes, so a task coming back or a
+     * lease since keeps it) and `inspect` finds it clean. Only the working copy goes: its branch, and so every commit,
+     * stays, and a later lease of the same branch makes a new one. At most `max` go per pass.
+     */
+    prune(rows: readonly WorktreeRow[], wanted: (row: WorktreeRow, fresh: boolean) => boolean, max?: number): Promise<{
         removed: WorktreeRow[];
         kept: {
             path: string;
             why: KeptWhy;
         }[];
     }>;
+    /**
+     * Throw away a let-go checkout kept for its changes, on purpose: the working copy and what is uncommitted in it
+     * go; its branch, and every commit on it, stays. Refused while anything holds it.
+     */
+    discardChanges(path: string): Promise<{
+        ok: true;
+        row: WorktreeRow;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    /** Remove one idle checkout's working copy (the caller holds it in `busy`) and forget its row. */
+    private removeWorkingCopy;
     /**
      * Whether anybody's work is in there. null means we could not tell, which is
      * neither clean nor dirty and must not be rounded to either.