toolroll 0.9.8 → 0.9.10

package/dist/chat-voice.d.ts

@@ -0,0 +1,68 @@
+/** How chat sounds: a teammate talking. One or two short sentences, outcome
+ * first, plain words, one action at most. Every chat (Telegram, Slack,
+ * Discord, Teams) takes its titles and its finished-work lines from here, so a
+ * task id, a "— revision" suffix or a person's own act never reaches a chat.
+ * The console keeps every exact name and fact. */
+import type { TelegramTransport } from "./telegram.js";
+import type { Store } from "./store.js";
+/** The bot's display name in every chat app. */
+export declare const BOT_NAME = "Toolroll";
+/** Updates for one person landing within this window become one message, edited in place as it grows. */
+export declare const BATCH_MS: number;
+export declare const SHORT_TITLE_MAX = 60;
+/** A short human summary of a task's title, at most 60 characters: no "— revision", and no task ids. Only the
+ * task's own id and tokens `isTaskId` names as real tasks are dropped; `node-20` and `utf-8` stay. */
+export declare function shortTitle(title: string | null | undefined, taskId?: string | null, isTaskId?: (token: string) => boolean): string;
+/** A task's title as every chat says it: short, with its own id and any other real task's id dropped. */
+export declare function chatTitle(store: Pick<Store, "getTask">, taskId: string): string;
+/** A title inside a sentence or list: "faster tests", but "API keys" and "iOS" keep their capitals. */
+export declare function inSentence(summary: string): string;
+/** The facts one line of a chat update is made of, read from the shared task status. */
+export type FinishedFact = {
+    summary: string;
+    headline: string;
+    checks: "passed" | "failed" | "not-run" | "off" | null;
+    report: boolean;
+    completedBy: string | null;
+    /** An open pull request carries this result: the ask is "Merge it?" rather than "Mark it complete?". */
+    pullRequest?: boolean;
+    /** The lead did this (built it, or marked it complete), so the lead says "I". */
+    lead?: boolean;
+    /** Not a finished result but another update about the task: its own words when it stands alone, and a few
+     * words for a list ("has a plan to review"). */
+    update?: {
+        words: string;
+        phrase: string;
+    } | null;
+};
+/** The two buttons under a result ready for a person: the real next step, then a look first. */
+export declare const READY_ACTIONS: {
+    readonly merge: "Merge";
+    readonly complete: "Mark complete";
+    readonly look: "Look first";
+};
+/** Whether this line asks for the result's next step, so it carries [Merge] or [Mark complete] and [Look first]. */
+export declare function asksToFinish(fact: FinishedFact): boolean;
+/** One update, said plainly: what happened, then what happens next. The lead says "I" for what it did. */
+export declare function finishedLine(fact: FinishedFact): string;
+/** Several updates in one message: "4 tasks finished: faster tests, cleanup, …" (or "3 updates: …" when not all of
+ * them are finished work), then what broke and what happens next. */
+export declare function batchLine(facts: readonly FinishedFact[]): string;
+/**
+ * Name the Telegram bot Toolroll. On pairing it always becomes Toolroll; on upgrade only a bot still called
+ * StandingOrders is renamed, so a name a person chose later is kept. Best effort: a refused or failed call
+ * leaves the old name and never blocks pairing or delivery. Returns whether a rename was sent and accepted.
+ */
+export declare function nameTelegramBot(transport: TelegramTransport, when: "pairing" | "upgrade"): Promise<boolean>;
+/** The last word on any pushed chat text: a task's own id (bare or in brackets), a "— revision" suffix and a
+ * "Replaced by <id>" never reach a chat, whatever words the fact was recorded with. A bare id reads as the
+ * task's short title when one is given, else "this task". */
+export declare function chatText(text: string, tasks?: readonly (string | null | undefined | {
+    id: string;
+    title?: string;
+})[]): string;
+/** The one button a plain fact may carry: its label names where its machine-minted console path goes; nothing in
+ * it comes from the fact's text. */
+export declare function factLinkLabel(path: string): string;
+/** Whether the words already name this title as a whole phrase (so it need not be said twice). */
+export declare function mentions(text: string, title: string): boolean;

package/dist/chat-voice.js

@@ -0,0 +1,175 @@
+import { phoneText } from "./telegram-status.js";
+/** The bot's display name in every chat app. */
+export const BOT_NAME = "Toolroll";
+/** Updates for one person landing within this window become one message, edited in place as it grows. */
+export const BATCH_MS = 2 * 60_000;
+export const SHORT_TITLE_MAX = 60;
+/** A token that could be an id: letters and digits joined by `-` or `_`, or with a digit in it (`release-099b`,
+ * `t42`). Words such as `node-20` and `utf-8` look the same, so a token goes only when it names a real task. */
+const ID_SHAPED = /\(?(?<![\p{L}\p{N}._/-])[\p{L}\p{N}]+(?:[-_.][\p{L}\p{N}]+)*(?![\p{L}\p{N}_/-]|\.[\p{L}\p{N}])\)?/gu;
+/** An id that could be mistaken for nothing else (`release-099b`, `fix_tax`, `t42`). A one-word id such as `tidy`
+ * is also a word, and prose keeps its words. */
+const idLike = (id) => /[-_\d]/.test(id);
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** A short human summary of a task's title, at most 60 characters: no "— revision", and no task ids. Only the
+ * task's own id and tokens `isTaskId` names as real tasks are dropped; `node-20` and `utf-8` stay. */
+export function shortTitle(title, taskId, isTaskId) {
+    let text = phoneText(title ?? "", 400);
+    // "— revision", "- revision 2", "(revision)": a revision is the same work to a person.
+    text = text.replace(/(?:(?:\s*[—–]+|\s+-+)\s*revision\b(?:\s*#?\d+)?|\s*[([]\s*revision(?:\s*#?\d+)?\s*[)\]])/giu, "");
+    text = text.replace(ID_SHAPED, token => {
+        const bare = token.replace(/^\(|\)$/g, "");
+        return idLike(bare) && (bare === taskId || isTaskId?.(bare) === true) ? " " : token;
+    });
+    text = text.replace(/\(\s*\)/g, " ").replace(/\s+/g, " ").replace(/^[\s·:,;—–-]+|[\s·:,;—–-]+$/gu, "").trim();
+    if (text === "") {
+        // A task filed with only its id as a title: the words, never the slug.
+        const words = (taskId ?? "").replace(/[-_]+/g, " ").trim();
+        return words === "" ? "A task" : shortTitle(words[0].toUpperCase() + words.slice(1));
+    }
+    if (text.length <= SHORT_TITLE_MAX)
+        return text;
+    const cut = text.slice(0, SHORT_TITLE_MAX - 1);
+    const space = cut.lastIndexOf(" ");
+    return `${(space > 20 ? cut.slice(0, space) : cut).replace(/[\s·:,;—–-]+$/u, "")}…`;
+}
+/** A task's title as every chat says it: short, with its own id and any other real task's id dropped. */
+export function chatTitle(store, taskId) {
+    return shortTitle(store.getTask(taskId)?.title, taskId, token => token !== taskId && store.getTask(token) !== null);
+}
+/** A title inside a sentence or list: "faster tests", but "API keys" and "iOS" keep their capitals. */
+export function inSentence(summary) {
+    return /^\p{Lu}\p{Ll}/u.test(summary) ? summary[0].toLowerCase() + summary.slice(1) : summary;
+}
+/** The two buttons under a result ready for a person: the real next step, then a look first. */
+export const READY_ACTIONS = { merge: "Merge", complete: "Mark complete", look: "Look first" };
+/** Whether this line asks for the result's next step, so it carries [Merge] or [Mark complete] and [Look first]. */
+export function asksToFinish(fact) {
+    return fact.update == null && fact.headline === "Ready for review" && !fact.report;
+}
+/** One update, said plainly: what happened, then what happens next. The lead says "I" for what it did. */
+export function finishedLine(fact) {
+    if (fact.update != null)
+        return fact.update.words;
+    const name = fact.summary, lower = inSentence(fact.summary);
+    const ready = fact.lead === true ? `I finished ${lower}` : `${name} is ready`;
+    switch (fact.headline) {
+        case "Ready for review":
+            if (fact.report)
+                return fact.lead === true ? `I wrote up ${lower}. The report is ready to read.` : `${name}: the report is ready to read.`;
+            if (fact.checks === "passed")
+                return `${ready}. Your tests passed. ${fact.pullRequest === true ? "Merge it?" : "Mark it complete?"}`;
+            if (fact.checks === "off")
+                return `${ready}. Checks are off for this project, so look it over first.`;
+            return `${ready}, but no tests ran. Look it over first.`;
+        case "Failed":
+            if (fact.checks === "failed")
+                return fact.lead === true
+                    ? `I built ${lower}, but its tests failed. It waits for you: retry or ask for changes.`
+                    : `${name} is built, but its tests failed. It waits for you: retry or ask for changes.`;
+            return fact.lead === true
+                ? `I couldn't finish ${lower}. The work so far is kept; retry when you're ready.`
+                : `${name} stopped before it finished. The work so far is kept; retry when you're ready.`;
+        case "Complete":
+            if (fact.lead === true && fact.completedBy)
+                return `I marked ${lower} complete.`;
+            return fact.completedBy ? `${name} is done. ${fact.completedBy} marked it complete.` : `${name} is done.`;
+        case "Needs you":
+            return fact.lead === true ? `I need your decision on ${lower} before I can go on.` : `${name} needs your decision before it can continue.`;
+        default:
+            return `${name}: ${fact.headline.toLowerCase()}.`;
+    }
+}
+/** One task in a list of updates: "faster tests is ready", "cleanup failed". */
+function phraseOf(fact) {
+    const name = inSentence(fact.summary);
+    if (fact.update != null)
+        return `${name} ${fact.update.phrase}`;
+    switch (fact.headline) {
+        case "Ready for review": return `${name} is ready`;
+        case "Failed": return `${name} failed`;
+        case "Complete": return `${name} is done`;
+        case "Needs you": return `${name} needs you`;
+        default: return `${name}: ${fact.headline.toLowerCase()}`;
+    }
+}
+/** Several updates in one message: "4 tasks finished: faster tests, cleanup, …" (or "3 updates: …" when not all of
+ * them are finished work), then what broke and what happens next. */
+export function batchLine(facts) {
+    if (facts.length === 1)
+        return finishedLine(facts[0]);
+    const finishedOnly = facts.every(one => one.update == null);
+    const names = finishedOnly ? facts.map(one => inSentence(one.summary)) : facts.map(phraseOf);
+    const shown = names.slice(0, 3).join(", ");
+    const first = `${facts.length} ${finishedOnly ? "tasks finished" : "updates"}: ${shown}${names.length > 3 ? ", …" : "."}`;
+    // What happens next: anything that broke or needs a decision waits for the person.
+    const failed = facts.filter(one => one.headline === "Failed");
+    const needs = facts.filter(one => one.headline === "Needs you").length;
+    const broke = failed.length !== 1 ? `${failed.length} failed`
+        : failed[0].checks === "failed" ? `tests failed on ${inSentence(failed[0].summary)}` : `${inSentence(failed[0].summary)} stopped before it finished`;
+    const waits = [
+        ...(failed.length === 0 ? [] : [broke]),
+        ...(needs === 0 ? [] : [needs === facts.length ? "each needs your decision" : `${needs} ${needs === 1 ? "needs" : "need"} your decision`]),
+    ];
+    if (waits.length === 0)
+        return first;
+    const said = waits.join(", and ");
+    return `${first}\n${said[0].toUpperCase()}${said.slice(1)}; ${failed.length + needs === 1 ? "it waits" : "they wait"} for you.`;
+}
+/** The old product name a bot may still wear from before the rename. */
+const OLD_NAME = /standing\s*-?\s*orders/i;
+/**
+ * Name the Telegram bot Toolroll. On pairing it always becomes Toolroll; on upgrade only a bot still called
+ * StandingOrders is renamed, so a name a person chose later is kept. Best effort: a refused or failed call
+ * leaves the old name and never blocks pairing or delivery. Returns whether a rename was sent and accepted.
+ */
+export async function nameTelegramBot(transport, when) {
+    try {
+        const current = await transport("getMyName", {});
+        const name = current.ok ? current.result?.name : undefined;
+        const shown = typeof name === "string" ? name : null;
+        if (shown === BOT_NAME)
+            return false;
+        if (when === "upgrade" && (shown === null || !OLD_NAME.test(shown)))
+            return false;
+        const set = await transport("setMyName", { name: BOT_NAME });
+        return set.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** The last word on any pushed chat text: a task's own id (bare or in brackets), a "— revision" suffix and a
+ * "Replaced by <id>" never reach a chat, whatever words the fact was recorded with. A bare id reads as the
+ * task's short title when one is given, else "this task". */
+export function chatText(text, tasks = []) {
+    let out = text.replace(/(?:(?:[ \t]*[—–]+|[ \t]+-+)[ \t]*revision\b(?:[ \t]*#?\d+)?|[ \t]*[([][ \t]*revision(?:[ \t]*#?\d+)?[ \t]*[)\]])/giu, "");
+    out = out.replace(/\bReplaced by (?!a newer task)[^\s.,;:!?)]+/gu, "Replaced by a newer task");
+    for (const task of tasks) {
+        const id = typeof task === "string" ? task : task?.id;
+        if (!id || !idLike(id))
+            continue;
+        const title = typeof task === "object" && task !== null ? task.title : undefined;
+        out = out.replace(new RegExp(`[ \\t]*\\(${escape(id)}\\)|(?<![\\p{L}\\p{N}_/=-])${escape(id)}(?![\\p{L}\\p{N}_-])`, "gu"), match => match.trimStart().startsWith("(") ? "" : title ?? "this task");
+    }
+    return out;
+}
+/** The one button a plain fact may carry: its label names where its machine-minted console path goes; nothing in
+ * it comes from the fact's text. */
+export function factLinkLabel(path) {
+    if (/^\/review\?result=[^&]+&run=\d+&tab=checks$/.test(path))
+        return "Inspect result";
+    if (/^\/t\/[^?#]+#merge$/.test(path))
+        return "Merge";
+    if (/^\/chat\?task=[^&]+&result=/.test(path))
+        return "Open result";
+    if (/^\/(?:chat\?task=|t\/)/.test(path))
+        return "Open task";
+    if (/^\/d\//.test(path))
+        return "Open decision";
+    return "Open console";
+}
+/** Whether the words already name this title as a whole phrase (so it need not be said twice). */
+export function mentions(text, title) {
+    return new RegExp(`(?<![\\p{L}\\p{N}_-])${escape(title)}(?![\\p{L}\\p{N}_-])`, "u").test(text);
+}

package/dist/check-progress.js

@@ -153,9 +153,10 @@ export class CheckProgressTracker {
             }
             return;
         }
-        // scripts/e2e-parallel.mjs: "Running 7 groups at once: console, task, …", then every group's
-        // lines as "[group] [app] …", then "✅ group  3.1 min" per group and "N of M groups passed …".
-        const starting = /^Running ([0-9]+) groups at once: (.+)$/.exec(line);
+        // scripts/e2e-parallel.mjs: "Running 7 groups, at most 4 at once (12.0 GB available, about 400 MB each): console,
+        // task, …" (before: "Running 7 groups at once: …"), then every group's lines as "[group] [app] …", then
+        // "✅ group  3.1 min" per group and "N of M groups passed …".
+        const starting = /^Running ([0-9]+) groups(?:, at most [0-9]+)? at once(?: \([^)]*\))?: (.+)$/.exec(line);
         if (starting !== null) {
             const total = safeCount(starting[1]);
             const names = starting[2].split(",").map(one => one.trim()).filter(one => one !== "");

package/dist/checkout-cleanup.d.ts

@@ -1,5 +1,5 @@
 import { type CheckoutCleanup } from "./storage.js";
-import type { Store } from "./store.js";
+import type { Store, WorktreeRow } from "./store.js";
 import { type WorktreePool } from "./worktree.js";
 /** A release candidate's checkout holds the build a deploy installs: kept a week after its task was done. */
 export declare const CANDIDATE_KEEP_MS: number;
@@ -36,12 +36,33 @@ type Status = {
     taskId: string;
     finishedAt: string | null;
     dueAt?: string;
+    atOnce?: boolean;
 };
+/** The release a deploy installed last (staged-upgrades/<stage>/deployment.json at phase "deployed"): its commit and
+ * builder run. A deploy runs from the gate's checkout, so that checkout stays while it is what runs. */
+export type Deployed = {
+    head: string | null;
+    run: number | null;
+};
+export declare function deployedRelease(stateDir: string | null): Deployed | null;
+/**
+ * Which release a gate belongs to: a failed gate is re-filed as the same name plus a letter (`release-x`, then
+ * `release-xb`, `release-xc` …), so a gate whose name is another gate's in the same project plus one letter is that
+ * release's.
+ */
+export declare function releaseOf(id: string, gates: ReadonlySet<string>): string;
 /** Where every task stands for cleanup, by task_ref id and by each branch it or its runs used. */
-export declare function taskStatuses(store: Store, now: Date): {
+export declare function taskStatuses(store: Store, now: Date, deployed?: Deployed | null): {
     byRef: Map<number, Status>;
     byBranch: Map<string, Status>;
 };
+/** The let-go checkouts whose task is complete or cancelled, and when it finished. Not a release candidate's that
+ * stays: a deploy runs from it. */
+export declare function finishedCheckouts(store: Store, now: Date, repo?: string): {
+    row: WorktreeRow;
+    taskId: string | null;
+    finishedAt: string;
+}[];
 /**
  * What a clean-up would remove now, how much space it would free, and what stays and why. `manual` is a clean-up by
  * hand (it doesn't wait for the setting); otherwise it is the worker's pass under the setting. Reads only.
@@ -71,6 +92,23 @@ export declare function cleanCheckouts(store: Store, pool: WorktreePool, now: ()
     repo?: string;
     only?: ReadonlySet<string>;
 }): Promise<CleanResult>;
+export type SlimResult = {
+    slimmed: {
+        path: string;
+        taskId: string | null;
+        dropped: string[];
+        bytes: number;
+    }[];
+};
+/**
+ * A kept checkout (its result waiting for review, or with changes) drops its dependencies and build output once its
+ * run has ended; the next run's setup restores them (node_modules only goes where the project has a setup to restore
+ * it). Never one in use or a release candidate (a deploy installs from it). Each in the ledger.
+ */
+export declare function slimKeptCheckouts(store: Store, pool: WorktreePool, now: () => Date, options: {
+    actor: string;
+    repo?: string;
+}): Promise<SlimResult>;
 /** Throw away a checkout kept for its changes, on purpose; its branch stays. In the ledger. */
 export declare function discardCheckout(store: Store, pool: WorktreePool, path: string, now: Date, actor: string): Promise<{
     ok: true;

package/dist/checkout-cleanup.js

@@ -6,13 +6,18 @@
  * Only the working copy goes: its branch, and so every commit, stays, and a later lease of the branch makes a new one.
  *
  * Always kept: a checkout in use, one whose task isn't finished (on hold, failed, a revision under way), a result
- * still waiting for review, a release candidate for a week after it was done (a deploy installs from it), a checkout
- * with changes (files Toolroll wrote itself aside), and one with commits on no branch. A checkout no task names
- * (adopted after a crash) goes only in a clean-up by hand. Every removal is in the ledger.
+ * still waiting for review, a checkout with changes (files Toolroll wrote itself aside), and one with commits on no
+ * branch. A release candidate's checkout (a deploy installs from it) is kept only while it is the newest gate for its
+ * release (for a week after it was done) or the one deployed; a superseded or cancelled gate goes at once, whatever
+ * its task's state (staged releases keep the rollback copy). A checkout no task names (adopted after a crash) goes only
+ * in a clean-up by hand. Every removal is in the ledger.
+ *
+ * A kept checkout waiting for review or with changes drops its dependencies and build output once its run ends
+ * (`slimKeptCheckouts`); the next run's setup restores them.
  */
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { basename } from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { taskBranches } from "./names.js";
 import { COMPLETION_ACTION } from "./result-completion.js";
 import { CLEANUP_CHOICES, bytesWords, diskBytes } from "./storage.js";
@@ -24,19 +29,80 @@ export const CANDIDATE_KEEP_MS = 7 * DAY_MS;
 export const AUTO_MAX = 20;
 /** Git inspections at once. */
 const INSPECT_AT_ONCE = 8;
+export function deployedRelease(stateDir) {
+    if (stateDir === null)
+        return null;
+    const root = join(stateDir, "staged-upgrades");
+    let newest = null;
+    let names = [];
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        return null;
+    }
+    for (const name of names) {
+        let journal;
+        try {
+            journal = JSON.parse(readFileSync(join(root, name, "deployment.json"), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (journal["phase"] !== "deployed")
+            continue;
+        const at = typeof journal["deployedAt"] === "string" ? journal["deployedAt"] : typeof journal["updatedAt"] === "string" ? journal["updatedAt"] : "";
+        if (newest !== null && newest.at >= at)
+            continue;
+        newest = { at, head: typeof journal["candidate"] === "string" ? journal["candidate"] : null, run: Number.isSafeInteger(journal["builder"]) ? Number(journal["builder"]) : null };
+    }
+    return newest === null ? null : { head: newest.head, run: newest.run };
+}
+/** The folder beside the database (where staged releases live), or null for a database in memory. */
+function stateDirOf(store) {
+    const main = store.handle.prepare("PRAGMA database_list").all().find(row => row["name"] === "main");
+    return typeof main?.["file"] === "string" && main["file"] !== "" ? dirname(main["file"]) : null;
+}
+/**
+ * Which release a gate belongs to: a failed gate is re-filed as the same name plus a letter (`release-x`, then
+ * `release-xb`, `release-xc` …), so a gate whose name is another gate's in the same project plus one letter is that
+ * release's.
+ */
+export function releaseOf(id, gates) {
+    return /[b-z]$/.test(id) && gates.has(id.slice(0, -1)) ? id.slice(0, -1) : id;
+}
 const STRENGTH = { "in use": 5, "task not finished": 4, "waiting for review": 3, "release candidate": 2 };
 const strength = (one) => one === undefined ? -1 : one.keep === null ? 0 : STRENGTH[one.keep] ?? 1;
 const stronger = (a, b) => strength(b) > strength(a) || (strength(b) === 0 && strength(a) === 0 && (b.finishedAt ?? "") > (a.finishedAt ?? "")) ? b : a;
 /** Where every task stands for cleanup, by task_ref id and by each branch it or its runs used. */
-export function taskStatuses(store, now) {
+export function taskStatuses(store, now, deployed) {
     const db = store.handle;
     const refs = db.prepare(`SELECT r.id AS ref, r.external_id AS id, r.revision_of AS revision_of, t.state AS state, t.updated_at AS updated_at,
       EXISTS (SELECT 1 FROM hold h WHERE h.task_ref = r.id) AS held,
       EXISTS (SELECT 1 FROM run live WHERE live.task_ref = r.id AND live.finished_at IS NULL) AS live,
-      EXISTS (SELECT 1 FROM task_scope s WHERE s.task_id = r.external_id AND s.candidate IS NOT NULL) AS candidate
+      (SELECT MAX(s.candidate) FROM task_scope s WHERE s.task_id = r.external_id) AS candidate, r.repo AS repo
     FROM task_ref r LEFT JOIN task t ON t.id = r.external_id AND r.backend = 'built-in'`).all();
     const runs = db.prepare("SELECT id, task_ref, branch FROM run").all();
     const refOfRun = new Map(runs.map(row => [Number(row["id"]), Number(row["task_ref"])]));
+    // Release candidates: per project and release, the newest gate not cancelled; and the one deployed.
+    const gates = refs.filter(row => row["candidate"] !== null);
+    const gateIds = new Map();
+    for (const row of gates) {
+        const repo = String(row["repo"]);
+        gateIds.set(repo, (gateIds.get(repo) ?? new Set()).add(String(row["id"])));
+    }
+    const releaseKey = (row) => `${String(row["repo"])}\u0000${releaseOf(String(row["id"]), gateIds.get(String(row["repo"])))}`;
+    const newestGate = new Map();
+    for (const row of gates) {
+        if (row["state"] === "cancelled")
+            continue;
+        const key = releaseKey(row);
+        newestGate.set(key, Math.max(newestGate.get(key) ?? -1, Number(row["ref"])));
+    }
+    const live = deployed === undefined ? deployedRelease(stateDirOf(store)) : deployed;
+    const deployedRef = live === null ? undefined : live.run !== null ? refOfRun.get(live.run) : undefined;
+    const isDeployed = (row) => live !== null &&
+        (Number(row["ref"]) === deployedRef || (live.head !== null && String(row["candidate"]) === live.head));
     // The completion names its family's root; its run names the result it completes.
     const completed = new Map();
     const completedRef = new Map();
@@ -59,16 +125,22 @@ export function taskStatuses(store, now) {
         const id = String(row["id"]);
         const state = row["state"] === null ? null : String(row["state"]);
         const updated = row["updated_at"] === null ? null : String(row["updated_at"]);
+        const gate = row["candidate"] !== null;
         let status;
         if (Number(row["live"]) === 1)
             status = { keep: "in use", taskId: id, finishedAt: null };
+        else if (gate && isDeployed(row))
+            status = { keep: "release candidate", taskId: id, finishedAt: updated };
+        // A superseded or cancelled gate goes at once, whatever its task's state: a newer gate (or none) is the release.
+        else if (gate && (state === "cancelled" || newestGate.get(releaseKey(row)) !== ref))
+            status = { keep: null, taskId: id, finishedAt: updated, atOnce: true };
         else if (state === null || Number(row["held"]) === 1 || (state !== "done" && state !== "cancelled"))
             status = { keep: "task not finished", taskId: id, finishedAt: null };
         else if (state === "cancelled")
             status = { keep: null, taskId: id, finishedAt: updated };
         else {
             const completedAt = [completed.get(id), completedRef.get(ref)].filter((one) => one !== undefined).sort().at(-1) ?? null;
-            if (Number(row["candidate"]) === 1) {
+            if (gate) {
                 const since = completedAt ?? updated ?? now.toISOString();
                 const until = new Date(Date.parse(since) + CANDIDATE_KEEP_MS).toISOString();
                 status = until > now.toISOString() ? { keep: "release candidate", taskId: id, finishedAt: since, dueAt: until } : { keep: null, taskId: id, finishedAt: since };
@@ -119,6 +191,17 @@ function statusOf(row, statuses) {
     }
     return found;
 }
+/** The let-go checkouts whose task is complete or cancelled, and when it finished. Not a release candidate's that
+ * stays: a deploy runs from it. */
+export function finishedCheckouts(store, now, repo) {
+    const statuses = taskStatuses(store, now);
+    return store.listWorktrees().filter(row => row.releasedAt !== null && row.runner === null && (repo === undefined || row.repo === repo)).flatMap(row => {
+        const status = statusOf(row, statuses);
+        if (status === undefined || status.finishedAt === null || status.keep !== null)
+            return [];
+        return [{ row, taskId: status.taskId, finishedAt: status.finishedAt }];
+    });
+}
 /** Why a checkout stays before anyone looks at its files, or null: it may go (as far as its task and the setting say). */
 function keptFor(pool, row, statuses, now, cleanup) {
     const status = statusOf(row, statuses);
@@ -136,6 +219,8 @@ function keptFor(pool, row, statuses, now, cleanup) {
         return { why: null, taskId };
     if (cleanup === "never")
         return { why: "cleanup is off", taskId };
+    if (status.atOnce === true)
+        return { why: null, taskId };
     const days = CLEANUP_CHOICES.find(one => one.value === cleanup).days;
     const since = [status.finishedAt, row.releasedAt].filter((one) => one !== null).sort().at(-1);
     const dueAt = new Date(Date.parse(since) + days * DAY_MS).toISOString();
@@ -215,6 +300,41 @@ export async function cleanCheckouts(store, pool, now, options) {
     }
     return { removed, kept: pruned.kept, freed: removed.reduce((sum, one) => sum + one.bytes, 0) };
 }
+/** Checkouts this process already looked at since they were let go (path and release time): looked at once. */
+const looked = new Set();
+/**
+ * A kept checkout (its result waiting for review, or with changes) drops its dependencies and build output once its
+ * run has ended; the next run's setup restores them (node_modules only goes where the project has a setup to restore
+ * it). Never one in use or a release candidate (a deploy installs from it). Each in the ledger.
+ */
+export async function slimKeptCheckouts(store, pool, now, options) {
+    const rows = store.listWorktrees().filter(row => row.releasedAt !== null && row.runner === null && (options.repo === undefined || row.repo === options.repo)
+        && !looked.has(`${row.path}\u0000${row.releasedAt}`) && existsSync(row.path));
+    const slimmed = [];
+    if (rows.length === 0)
+        return { slimmed };
+    const keptAs = (row) => keptFor(pool, row, taskStatuses(store, now()), now(), "manual");
+    const statuses = taskStatuses(store, now());
+    for (const row of rows) {
+        const kept = keptFor(pool, row, statuses, now(), "manual");
+        if (kept.why === "in use")
+            continue;
+        looked.add(`${row.path}\u0000${row.releasedAt}`);
+        if (kept.why === "release candidate")
+            continue;
+        if (kept.why !== "waiting for review" && await pool.inspect(row.path) !== "has changes")
+            continue;
+        const wanted = (fresh) => { const why = keptAs(fresh).why; return why !== "in use" && why !== "release candidate"; };
+        const done = await pool.slim(row, wanted, store.liveWorktreeSetup(row.repo) !== null);
+        if (!done.ok || done.dropped.length === 0)
+            continue;
+        const bytes = done.bytes;
+        slimmed.push({ path: row.path, taskId: kept.taskId, dropped: done.dropped, bytes });
+        store.recordAction({ at: now().toISOString(), actor: options.actor, repo: row.repo, taskId: kept.taskId, runId: null, action: "checkout slimmed", outcome: "removed", source: "work",
+            detail: `${basename(row.path)}: dropped ${done.dropped.join(", ")}${bytes > 0 ? ` (about ${bytesWords(bytes)})` : ""}; the next run's setup restores them` });
+    }
+    return { slimmed };
+}
 /** Throw away a checkout kept for its changes, on purpose; its branch stays. In the ledger. */
 export async function discardCheckout(store, pool, path, now, actor) {
     const bytes = existsSync(path) ? diskBytes([path]).get(path) ?? 0 : 0;
@@ -233,7 +353,7 @@ export function whyWords(item) {
         case "in use": return "in use";
         case "task not finished": return "its task isn't finished";
         case "waiting for review": return "its result is waiting for review";
-        case "release candidate": return `release candidate, kept until ${item.dueAt?.slice(0, 10) ?? "a week after"}`;
+        case "release candidate": return item.dueAt === undefined ? "the deployed release candidate" : `newest release candidate, kept until ${item.dueAt.slice(0, 10)}`;
         case "has changes": return "has changes";
         case "has commits": return "has commits on no branch";
         case "unreadable": return "git couldn't read it";

package/dist/desktop-update.d.ts

@@ -27,6 +27,10 @@ export type UpdateJournal = {
     serviceInterrupted?: boolean;
     replacementOccurred?: boolean;
     retryableRecovery?: boolean;
+    /** The finished run the update is waiting on (or stopped waiting on). Absent while it waits on ordinary work. */
+    waiting?: LingeringRun & {
+        since: string;
+    };
 };
 type ServiceState = {
     state: string;
@@ -39,6 +43,8 @@ export type UpdateHooks = {
     healthy?: (bundle: DesktopBundle, journal: UpdateJournal, since: string) => Promise<boolean>;
     swap?: (journal: UpdateJournal) => Promise<void>;
     sleep?: (ms: number) => Promise<void>;
+    /** The clock the drain's two-minute limit reads (tests). */
+    now?: () => Date;
     healthTimeoutMs?: number;
     /** Fault injection for state-machine tests, never selectable by a CLI flag. */
     checkpoint?: (phase: Phase) => void;
@@ -48,7 +54,53 @@ export declare const updateTerminal: (phase: string) => boolean;
 /** Durable receipts are private and independent of the app being replaced. */
 export declare function durableJson(file: string, value: unknown): void;
 export declare function readUpdateJournal(stateDir: string, retainedReceipt?: string): UpdateJournal | null;
+/** A finished run whose end Toolroll cannot show yet: in plain words, with the one command that clears it when a
+ * person can. */
+export type LingeringRun = {
+    run: number;
+    on: string;
+    action: string | null;
+};
+/** How long an update waits on a finished run it cannot show has ended before it stops waiting and says why. */
+export declare const LINGERING_LIMIT_MS = 120000;
+export declare function lingeringRun(db: DatabaseSync): LingeringRun | null;
 export declare function lingeringWork(db: DatabaseSync): string | null;
+export declare const lingeringWords: (l: LingeringRun) => string;
+/** What an update says when it stops waiting on `l`: what is in the way, the command, and that new work resumed. */
+export declare const stoppedWaitingWords: (l: LingeringRun) => string;
+/** The next step once an update has stopped on `l`. */
+export declare const clearWords: (l: LingeringRun) => string;
+/** An update that is waiting or stopped, what on, and the one action that clears it: for `toolroll status` and the
+ * console. `app`: the desktop app's update rather than `toolroll update`. */
+export type UpdateWaiting = {
+    app: boolean;
+    version: string;
+    stopped: boolean;
+    run: number | null;
+    on: string;
+    action: string | null;
+    words: string;
+    short: string;
+};
+export declare function updateWaitingWords(o: {
+    app: boolean;
+    version: string;
+    stopped: boolean;
+    lingering: LingeringRun | null;
+}): UpdateWaiting;
+/** An app updater that ended while letting work finish, with no automatic recovery coming to resume it, leaves new
+ * work paused with nobody left to lift the pause. Nothing was stopped or swapped yet, so the pause is lifted here and
+ * the update says it stopped. Returns what it said, or null. */
+export declare function releaseStalledDesktopUpdate(stateDir: string): string | null;
+/** The desktop app's update, when it is waiting on work in `databaseFile`'s installation, or stopped on a run still in
+ * the way. An app updater that ended mid-drain is released first, as `toolroll update`'s is. */
+export declare function desktopUpdateWaitingOf(databaseFile: string, inTheWay: (run: number) => boolean, stateDirs?: readonly string[]): UpdateWaiting | null;
+/** The same settling reconcile the background worker runs: a finished run's leftover record of a process that never
+ * started settles once the run's process groups are proven gone. A record nothing can prove either way stays. */
+export declare function settleLeftoverRecords(db: DatabaseSync, now: Date): number;
+/** Store.stopQuiescenceProblem's reasons, said for a person: no internal terms, and `toolroll run settle` only where it
+ * can clear the record (it refuses while anything of the run is alive). */
+export declare function plainLingering(fallbackRun: number, problem: string): LingeringRun;
 export declare function previewDesktopUpdate(stateDir: string, installed: string, candidate: string, label: string, hooks?: UpdateHooks): Promise<{
     old: DesktopBundle;
     next: DesktopBundle;