toolroll 0.9.8 → 0.9.9

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;

package/dist/desktop-update.js

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, chmodSync, copyFileSync, cpSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { bundleHash, readDesktopBundle, verifyDesktopUpdateBundles } from "./desktop-bundle.js";
@@ -139,15 +140,135 @@ async function otherControllers(app, stateDir) {
     const command = `${join(resources(app), "runtime", "node")} ${join(resources(app), "dist", "desktop-host.js")} serve --state `;
     return result.stdout.split("\n").some(line => line.trim().startsWith(command) && line.trim() !== command + resolve(stateDir));
 }
-export function lingeringWork(db) {
+/** How long an update waits on a finished run it cannot show has ended before it stops waiting and says why. */
+export const LINGERING_LIMIT_MS = 120_000;
+export function lingeringRun(db) {
     const store = new Store(db);
     for (const row of db.prepare("SELECT DISTINCT run FROM run_process WHERE exited_at IS NULL").all()) {
         const problem = store.stopQuiescenceProblem(Number(row.run));
         if (problem)
-            return problem;
+            return plainLingering(Number(row.run), problem);
     }
     return null;
 }
+export function lingeringWork(db) {
+    const lingering = lingeringRun(db);
+    return lingering && lingeringWords(lingering);
+}
+export const lingeringWords = (l) => l.action ? `${l.on}. If nothing of it is running, run: ${l.action}` : `${l.on}.`;
+/** What an update says when it stops waiting on `l`: what is in the way, the command, and that new work resumed. */
+export const stoppedWaitingWords = (l) => `Stopped waiting after 2 minutes. ${l.on}. ${clearWords(l)} New work resumed; nothing was changed.`;
+/** The next step once an update has stopped on `l`. */
+export const clearWords = (l) => l.action ? `If nothing of it is running, run ${l.action}, then update again.` : "Update again once it has stopped.";
+export function updateWaitingWords(o) {
+    const { app, version, stopped, lingering: l } = o;
+    const update = `${app ? "App update" : "Update"} to ${version}`;
+    if (!l) {
+        const on = "running work to finish";
+        const words = `${update} is waiting for ${on}. New work is paused.`;
+        return { app, version, stopped: false, run: null, on, action: null, words, short: words };
+    }
+    const next = l.action ? ` If nothing of it is running, run ${l.action}${stopped ? ", then update again" : ""}.` : stopped ? " Update again once it has stopped." : "";
+    return { app, version, stopped, run: l.run, on: l.on, action: l.action,
+        words: `${update} ${stopped ? "stopped waiting" : "is waiting"}: ${l.on}.${next}`,
+        short: `${update} ${stopped ? `stopped: run #${l.run} is in the way` : `is waiting on run #${l.run}`}.${next}` };
+}
+/** 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 function releaseStalledDesktopUpdate(stateDir) {
+    let j;
+    try {
+        j = readUpdateJournal(stateDir);
+    }
+    catch {
+        return null;
+    }
+    if (!j || j.phase !== "draining" || j.serviceInterrupted || j.replacementOccurred)
+        return null;
+    const status = desktopUpdateStatus(stateDir);
+    if (status.running || status.automaticRecovery)
+        return null;
+    const lock = workerLock(j);
+    if (!lock)
+        return null;
+    try {
+        const held = readUpdateJournal(stateDir);
+        if (!held || held.id !== j.id || held.phase !== "draining" || held.serviceInterrupted || held.replacementOccurred || bundleHash(held.old.path) !== held.old.hash)
+            return null;
+        const db = connect(held.databaseFile);
+        try {
+            removeUpdateGate(db, held.id);
+        }
+        finally {
+            db.close();
+        }
+        const words = `The app update to ${held.next.version} stopped: its updater ended before running work finished. Nothing was changed; new work resumed. Update again from the app.`;
+        held.error = "The updater ended while letting work finish.";
+        save(held, "cancelled", words);
+        return words;
+    }
+    finally {
+        lock.close();
+    }
+}
+/** 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 function desktopUpdateWaitingOf(databaseFile, inTheWay, stateDirs = [dirname(databaseFile), join(homedir(), "Library", "Application Support", "Standing Orders")]) {
+    for (const stateDir of new Set(stateDirs.map(dir => resolve(dir)))) {
+        let j;
+        try {
+            j = readUpdateJournal(stateDir);
+        }
+        catch {
+            continue;
+        }
+        if (!j || resolve(j.databaseFile) !== resolve(databaseFile))
+            continue;
+        try {
+            if (releaseStalledDesktopUpdate(stateDir))
+                j = readUpdateJournal(stateDir);
+        }
+        catch { /* shown as last saved */ }
+        const version = j.next.version;
+        if (j.phase === "draining")
+            return updateWaitingWords({ app: true, version, stopped: false, lingering: j.waiting ?? null });
+        if (j.phase === "cancelled" && j.waiting && inTheWay(j.waiting.run))
+            return updateWaitingWords({ app: true, version, stopped: true, lingering: j.waiting });
+    }
+    return 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 function settleLeftoverRecords(db, now) {
+    return new Store(db).settleUnspawnedWitnesses(now);
+}
+/** 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 function plainLingering(fallbackRun, problem) {
+    const run = Number(/run #(\d+)/.exec(problem)?.[1] ?? fallbackRun);
+    const settle = `toolroll run settle ${run} --why "it is not running"`;
+    const pid = /process (\d+)/.exec(problem)?.[1];
+    if (/incomplete spawn witness|before its process witness was recorded/.test(problem))
+        return { run, on: `Run #${run} finished, but Toolroll has no process ID for one of its processes, so it can't confirm that process ended`, action: settle };
+    if (/belongs to another host|another host/.test(problem))
+        return { run, on: `Run #${run} finished on another computer, and Toolroll can only confirm its processes ended there`, action: `${settle} (on that computer)` };
+    if (/incomplete native containment custody|cannot be proven empty/.test(problem))
+        return { run, on: `Run #${run} finished, but Toolroll can't confirm its sandbox is empty`, action: settle };
+    if (/still has members/.test(problem))
+        return { run, on: `Run #${run} finished, but processes are still running in its sandbox`, action: null };
+    if (/workspace is still held/.test(problem))
+        return { run, on: `Run #${run} finished, but process ${pid ?? "?"} is still using its folder`, action: null };
+    if (/workspace occupancy/.test(problem))
+        return { run, on: `Run #${run} finished, but Toolroll can't check whether its folder is still in use`, action: null };
+    if (/may still be running|owned subprocess/.test(problem))
+        return { run, on: `Run #${run} finished, but ${pid ? `its process ${pid}` : "one of its processes"} is still running`, action: null };
+    if (/held supervisor/.test(problem))
+        return { run, on: `Run #${run} is still shutting down`, action: null };
+    if (/still open/.test(problem))
+        return { run, on: `Run #${run} is still running`, action: null };
+    return { run, on: `Run #${run} hasn't finished shutting down`, action: null };
+}
 export async function previewDesktopUpdate(stateDir, installed, candidate, label, hooks = {}) {
     const config = readDesktopConfig(stateDir), old = readDesktopBundle(resolve(installed)), next = readDesktopBundle(resolve(candidate));
     if (!/^[a-zA-Z0-9.-]+$/.test(label))
@@ -634,6 +755,7 @@ export async function runDesktopUpdate(stateDir, hooks = {}) {
             return;
         }
         checkpoint("draining", "Waiting for current work to finish. New work is paused; no task will be killed for this update.");
+        const now = hooks.now ?? (() => new Date());
         for (;;) {
             if (restoreRequested(j) || updateStopRequested(j)) {
                 await cancel();
@@ -642,16 +764,36 @@ export async function runDesktopUpdate(stateDir, hooks = {}) {
             assertConfig(j);
             assertCodingCatalogPresent(j);
             const checking = connect(j.databaseFile);
+            let stuck = null;
             try {
                 const active = activeUpdateWork(checking);
-                const lingering = Object.values(active).every(n => n === 0) ? lingeringWork(checking) : null;
-                if (!lingering && Object.values(active).every(n => n === 0) && freezeUpdateGate(checking, j.id))
+                const idle = Object.values(active).every(n => n === 0);
+                // A finished run's leftover record settles here first, as the background worker would settle it.
+                if (idle)
+                    settleLeftoverRecords(checking, now());
+                const lingering = idle ? lingeringRun(checking) : null;
+                if (!lingering && idle && freezeUpdateGate(checking, j.id)) {
+                    delete j.waiting;
                     break;
-                save(j, "draining", lingering ? `Waiting for a worker to finish shutdown: ${lingering}. No process is being killed.` : `Waiting for current work: ${active.runs} runs, ${active.claims} leases, ${active.conversations} chat requests, ${active.sessions} sessions, ${active.stopping} shutdowns, ${active.coding} coding sessions, ${active.codingDeliveries} unconfirmed messages. Nothing is being cancelled.`);
+                }
+                // Saved, so a resumed updater keeps counting from when it began, and status can say what it waits on.
+                if (!lingering)
+                    delete j.waiting;
+                else if (j.waiting?.run !== lingering.run || j.waiting.on !== lingering.on)
+                    j.waiting = { ...lingering, since: now().toISOString() };
+                if (j.waiting && now().getTime() - Date.parse(j.waiting.since) >= LINGERING_LIMIT_MS)
+                    stuck = lingering;
+                else
+                    save(j, "draining", lingering ? `New work is paused. Waiting for run #${lingering.run}: ${lingeringWords(lingering)} No process is being killed.` : `Waiting for current work: ${active.runs} runs, ${active.claims} leases, ${active.conversations} chat requests, ${active.sessions} sessions, ${active.stopping} shutdowns, ${active.coding} coding sessions, ${active.codingDeliveries} unconfirmed messages. Nothing is being cancelled.`);
             }
             finally {
                 checking.close();
             }
+            // Waiting longer proves nothing more: new work resumes, and the one thing in the way is named.
+            if (stuck) {
+                await release("cancelled", stoppedWaitingWords(stuck));
+                return;
+            }
             assertCodingCatalogPresent(j);
             await sleep(1000);
         }

package/dist/evidence.d.ts

@@ -50,6 +50,12 @@ export declare const RETENTION_NOTE = "REMOVED-BY-RETENTION";
 /** Bounds on a claimed screenshot file's own bytes — independent of the
  * proof manifest's byte cap, since these are binary images, not JSON. */
 export declare const SCREENSHOT_BYTE_CAP: number;
+/** Check evidence lives in the run's evidence, never on the branch: images a
+ * build adds under this folder are left out of its commit. */
+export declare const WORKTREE_EVIDENCE_DIR = "evidence/";
+export declare function isImagePath(path: string): boolean;
+/** Images and other files that are never read as text, judged by name alone. */
+export declare function isBinaryAssetPath(path: string): boolean;
 /** Bytes each kind may store. Originals can be any size; the record says what was cut. */
 /** Bound one captured stream to `cap` bytes keeping its beginning and, mostly,
  * its end: a test runner's summary and failure list come last, and that is

package/dist/evidence.js

@@ -55,6 +55,14 @@ export const RETENTION_NOTE = "REMOVED-BY-RETENTION";
 /** Bounds on a claimed screenshot file's own bytes — independent of the
  * proof manifest's byte cap, since these are binary images, not JSON. */
 export const SCREENSHOT_BYTE_CAP = 5 * 1024 * 1024;
+/** Check evidence lives in the run's evidence, never on the branch: images a
+ * build adds under this folder are left out of its commit. */
+export const WORKTREE_EVIDENCE_DIR = "evidence/";
+const IMAGE_PATH = /\.(?:png|jpe?g|gif|webp|bmp|ico|tiff?|avif|heic)$/i;
+const BINARY_PATH = /\.(?:pdf|zip|gz|tgz|tar|7z|woff2?|ttf|otf|eot|mp4|mov|webm|mp3|wav|sqlite3?|db|wasm|bin|jar|exe|dll|so|dylib)$/i;
+export function isImagePath(path) { return IMAGE_PATH.test(path); }
+/** Images and other files that are never read as text, judged by name alone. */
+export function isBinaryAssetPath(path) { return IMAGE_PATH.test(path) || BINARY_PATH.test(path); }
 /** Bytes each kind may store. Originals can be any size; the record says what was cut. */
 /** Bound one captured stream to `cap` bytes keeping its beginning and, mostly,
  * its end: a test runner's summary and failure list come last, and that is

package/dist/first-run.d.ts

@@ -88,7 +88,7 @@ export type JourneyStep = {
  * the build finished with a result.
  */
 export declare function firstTaskJourney(read: {
-    stage: "queued" | "planning" | "needs-you" | "building" | "checking" | "reviewing" | "finished" | "complete" | "failed" | "stopped";
+    stage: "queued" | "planning" | "needs-you" | "waiting" | "building" | "checking" | "reviewing" | "finished" | "complete" | "failed" | "stopped";
     need?: string | undefined;
 }, approved: boolean, built?: boolean): JourneyStep[];
 export {};

package/dist/first-run.js

@@ -131,11 +131,13 @@ export function firstTaskJourney(read, approved, built = false) {
     const at = read.stage === "finished" || read.stage === "complete" ? { index: 5, stuck: false }
         : read.stage === "checking" || read.stage === "reviewing" ? { index: 3, stuck: false }
             : read.stage === "building" ? { index: 2, stuck: false }
-                : read.stage === "needs-you" && read.need === "approval" ? { index: 1, stuck: false }
-                    : read.stage === "planning" ? { index: 0, stuck: false }
-                        : read.stage === "queued" ? { index: approved ? 2 : 0, stuck: false }
-                            // A build that finished but isn't Ready (its checks failed or didn't run, or it needs a decision) stopped at Checks.
-                            : { index: built ? 3 : approved ? 2 : 0, stuck: true };
+                // Waiting on nothing a person does: the build finished and is settling.
+                : read.stage === "waiting" ? { index: built ? 3 : 2, stuck: false }
+                    : read.stage === "needs-you" && read.need === "approval" ? { index: 1, stuck: false }
+                        : read.stage === "planning" ? { index: 0, stuck: false }
+                            : read.stage === "queued" ? { index: approved ? 2 : 0, stuck: false }
+                                // A build that finished but isn't Ready (its checks failed or didn't run, or it needs a decision) stopped at Checks.
+                                : { index: built ? 3 : approved ? 2 : 0, stuck: true };
     return JOURNEY_STEPS.map(([key, label], index) => ({ key, label,
         state: index < at.index ? "done" : index === at.index ? (at.stuck ? "stuck" : "current") : "todo" }));
 }

package/dist/lead-context.d.ts

@@ -5,4 +5,4 @@ import { type AssignmentCatchUp } from './assignment-brief.js';
 export declare function leadContext(store: Store, repos: readonly string[], now: Date, evidenceRoot?: string): string;
 /** The same saved brief is useful before chat spending is authorized. */
 export declare function leadBriefHtml(brief: AssignmentCatchUp): string;
-export declare const LEAD_CONTEXT_CSS = ".lead-brief{margin:1rem 0;min-width:0}.lead-brief h2{font-size:1.1rem;margin:0 0 .8rem}.repository-context input[name=q]{display:block;box-sizing:border-box;min-height:44px;width:100%;margin:.4rem 0 .75rem;padding:.6rem .75rem;border:1px solid var(--border);border-radius:8px;background:var(--surface);color:inherit;font:inherit}.repository-context form{margin:.5rem 0 1rem}.repository-context summary{min-height:44px;padding:.75rem 0;overflow-wrap:anywhere}.lead-brief h3{font-size:.85rem;margin:1rem 0 .4rem;color:var(--muted-foreground)}.lead-brief ul{list-style:none;margin:0;padding:0}.lead-brief li{display:grid;grid-template-columns:minmax(0,1fr) auto;column-gap:.75rem;align-items:center;padding:.35rem 0;border-bottom:1px solid var(--border);min-width:0}.lead-brief li a{display:flex;min-height:44px;align-items:center;font-weight:500;overflow-wrap:anywhere;text-decoration:none}.lead-brief li a:hover{text-decoration:underline}.lead-brief-state{font-size:.75rem;font-weight:600;padding:.15rem .5rem;border-radius:.375rem;background:var(--so-neutral-soft);color:var(--so-neutral-ink);white-space:nowrap}.lead-brief-state--needs-decision,.lead-brief-state--ready-to-check{background:var(--so-attention-soft);color:var(--so-attention)}.lead-brief-state--working,.lead-brief-state--checking{background:var(--so-info-soft);color:var(--so-info)}.lead-brief-state--complete{background:var(--so-success-soft);color:var(--so-success)}.lead-brief-detail{grid-column:1/-1;font-size:.85rem;color:var(--muted-foreground);overflow-wrap:anywhere;padding-bottom:.35rem}@media(max-width:760px){.lead-brief{margin:.5rem 0}.lead-brief h2{margin:0 0 .25rem}.lead-brief h3{margin:.5rem 0 0}.lead-brief li{padding:0 0 .375rem}.lead-brief-detail{margin-top:-.375rem;padding-bottom:0;line-height:1.35;pointer-events:none}}";
+export declare const LEAD_CONTEXT_CSS = ".lead-brief{margin:1rem 0;min-width:0}.lead-brief h2{font-size:1.1rem;margin:0 0 .8rem}.repository-context input[name=q]{display:block;box-sizing:border-box;min-height:44px;width:100%;margin:.4rem 0 .75rem;padding:.6rem .75rem;border:1px solid var(--border);border-radius:8px;background:var(--surface);color:inherit;font:inherit}.repository-context form{margin:.5rem 0 1rem}.repository-context summary{min-height:44px;padding:.75rem 0;overflow-wrap:anywhere}.lead-brief h3{font-size:.85rem;margin:1rem 0 .4rem;color:var(--muted-foreground)}.lead-brief ul{list-style:none;margin:0;padding:0}.lead-brief li{display:grid;grid-template-columns:minmax(0,1fr) auto;column-gap:.75rem;align-items:center;padding:.35rem 0;border-bottom:1px solid var(--border);min-width:0}.lead-brief li a{display:flex;min-height:44px;align-items:center;font-weight:500;overflow-wrap:anywhere;text-decoration:none}.lead-brief li a:hover{text-decoration:underline}.lead-brief-state{font-size:.75rem;font-weight:600;padding:.15rem .5rem;border-radius:.375rem;background:var(--so-neutral-soft);color:var(--so-neutral-ink);white-space:nowrap}.lead-brief-state--needs-decision,.lead-brief-state--ready-to-check{background:var(--so-attention-soft);color:var(--so-attention)}.lead-brief-state--working,.lead-brief-state--checking{background:var(--so-info-soft);color:var(--so-info)}.lead-brief-state--complete{background:var(--so-success-soft);color:var(--so-success)}.lead-brief li a.lead-brief-act{grid-column:1/-1;justify-self:start;display:inline-flex;min-height:40px;margin:.15rem 0 .4rem;font-weight:600}@media(max-width:760px){.lead-brief li a.lead-brief-act{justify-self:stretch;justify-content:center;min-height:44px}}.lead-brief-detail{grid-column:1/-1;font-size:.85rem;color:var(--muted-foreground);overflow-wrap:anywhere;padding-bottom:.35rem}@media(max-width:760px){.lead-brief{margin:.5rem 0}.lead-brief h2{margin:0 0 .25rem}.lead-brief h3{margin:.5rem 0 0}.lead-brief li{padding:0 0 .375rem}.lead-brief-detail{margin-top:-.375rem;padding-bottom:0;line-height:1.35;pointer-events:none}}";

package/dist/lead-context.js

@@ -53,8 +53,10 @@ export function leadBriefHtml(brief) {
         };
         return [`<section><h3>${group.title}</h3><ul>${entries.map(one => `<li><a href="/chat?task=${encodeURIComponent(one.rootId)}">${escape(one.title)}</a>` +
                 stateChip(one.state, one.detail) +
-                (quiet ? '' : `<span class="lead-brief-detail">${escape(publicChatText(one.detail || one.outcome || '', 160))}</span>`) + `</li>`).join('')}</ul></section>`];
+                (quiet ? '' : `<span class="lead-brief-detail">${escape(publicChatText(one.detail || one.outcome || '', 160))}</span>`) +
+                // Needs you: the one action that resolves it, under its sentence.
+                (one.state === 'needs-decision' && one.nextAction !== null && one.nextHref ? `<a class="lead-brief-act button-link" href="${escape(one.nextHref)}" data-catch-up-action>${escape(one.nextAction.label)}</a>` : '') + `</li>`).join('')}</ul></section>`];
     });
     return `<section class="lead-brief" aria-label="Project catch-up"><h2>Catch up</h2>${sections.length ? sections.join('') : '<p class="meta">Nothing needs you right now.</p>'}${brief.assignments.length > 3 || brief.omissions.candidateScanLimited || brief.omissions.assignments > 0 ? '<a href="/work">See all tasks</a>' : ''}</section>`;
 }
-export const LEAD_CONTEXT_CSS = '.lead-brief{margin:1rem 0;min-width:0}.lead-brief h2{font-size:1.1rem;margin:0 0 .8rem}.repository-context input[name=q]{display:block;box-sizing:border-box;min-height:44px;width:100%;margin:.4rem 0 .75rem;padding:.6rem .75rem;border:1px solid var(--border);border-radius:8px;background:var(--surface);color:inherit;font:inherit}.repository-context form{margin:.5rem 0 1rem}.repository-context summary{min-height:44px;padding:.75rem 0;overflow-wrap:anywhere}.lead-brief h3{font-size:.85rem;margin:1rem 0 .4rem;color:var(--muted-foreground)}.lead-brief ul{list-style:none;margin:0;padding:0}.lead-brief li{display:grid;grid-template-columns:minmax(0,1fr) auto;column-gap:.75rem;align-items:center;padding:.35rem 0;border-bottom:1px solid var(--border);min-width:0}.lead-brief li a{display:flex;min-height:44px;align-items:center;font-weight:500;overflow-wrap:anywhere;text-decoration:none}.lead-brief li a:hover{text-decoration:underline}.lead-brief-state{font-size:.75rem;font-weight:600;padding:.15rem .5rem;border-radius:.375rem;background:var(--so-neutral-soft);color:var(--so-neutral-ink);white-space:nowrap}.lead-brief-state--needs-decision,.lead-brief-state--ready-to-check{background:var(--so-attention-soft);color:var(--so-attention)}.lead-brief-state--working,.lead-brief-state--checking{background:var(--so-info-soft);color:var(--so-info)}.lead-brief-state--complete{background:var(--so-success-soft);color:var(--so-success)}.lead-brief-detail{grid-column:1/-1;font-size:.85rem;color:var(--muted-foreground);overflow-wrap:anywhere;padding-bottom:.35rem}@media(max-width:760px){.lead-brief{margin:.5rem 0}.lead-brief h2{margin:0 0 .25rem}.lead-brief h3{margin:.5rem 0 0}.lead-brief li{padding:0 0 .375rem}.lead-brief-detail{margin-top:-.375rem;padding-bottom:0;line-height:1.35;pointer-events:none}}';
+export const LEAD_CONTEXT_CSS = '.lead-brief{margin:1rem 0;min-width:0}.lead-brief h2{font-size:1.1rem;margin:0 0 .8rem}.repository-context input[name=q]{display:block;box-sizing:border-box;min-height:44px;width:100%;margin:.4rem 0 .75rem;padding:.6rem .75rem;border:1px solid var(--border);border-radius:8px;background:var(--surface);color:inherit;font:inherit}.repository-context form{margin:.5rem 0 1rem}.repository-context summary{min-height:44px;padding:.75rem 0;overflow-wrap:anywhere}.lead-brief h3{font-size:.85rem;margin:1rem 0 .4rem;color:var(--muted-foreground)}.lead-brief ul{list-style:none;margin:0;padding:0}.lead-brief li{display:grid;grid-template-columns:minmax(0,1fr) auto;column-gap:.75rem;align-items:center;padding:.35rem 0;border-bottom:1px solid var(--border);min-width:0}.lead-brief li a{display:flex;min-height:44px;align-items:center;font-weight:500;overflow-wrap:anywhere;text-decoration:none}.lead-brief li a:hover{text-decoration:underline}.lead-brief-state{font-size:.75rem;font-weight:600;padding:.15rem .5rem;border-radius:.375rem;background:var(--so-neutral-soft);color:var(--so-neutral-ink);white-space:nowrap}.lead-brief-state--needs-decision,.lead-brief-state--ready-to-check{background:var(--so-attention-soft);color:var(--so-attention)}.lead-brief-state--working,.lead-brief-state--checking{background:var(--so-info-soft);color:var(--so-info)}.lead-brief-state--complete{background:var(--so-success-soft);color:var(--so-success)}.lead-brief li a.lead-brief-act{grid-column:1/-1;justify-self:start;display:inline-flex;min-height:40px;margin:.15rem 0 .4rem;font-weight:600}@media(max-width:760px){.lead-brief li a.lead-brief-act{justify-self:stretch;justify-content:center;min-height:44px}}.lead-brief-detail{grid-column:1/-1;font-size:.85rem;color:var(--muted-foreground);overflow-wrap:anywhere;padding-bottom:.35rem}@media(max-width:760px){.lead-brief{margin:.5rem 0}.lead-brief h2{margin:0 0 .25rem}.lead-brief h3{margin:.5rem 0 0}.lead-brief li{padding:0 0 .375rem}.lead-brief-detail{margin-top:-.375rem;padding-bottom:0;line-height:1.35;pointer-events:none}}';

package/dist/lead-status.d.ts

@@ -47,7 +47,7 @@ export type InstallationStatus = {
         count: number;
         results: {
             task: string;
-            run: number;
+            run: number | null;
             check: CheckSummary;
         }[];
     };
@@ -84,6 +84,15 @@ export type InstallationStatus = {
  * has been observed yet. */
 export declare function taskWaitSnapshot(store: Store, taskId: string, now: Date, watchedRun?: number): TaskWaitSnapshot | null;
 /** Whole-installation status, deliberately aggregated and bounded. */
+/** The one-off repair on start. An older build left finished runs' process
+ * exits unrecorded and counted completed families as waiting; nothing about
+ * a status is stored, so recording every exit that can now be proven and
+ * re-deriving each open task's headline from the shared projection clears
+ * them. What can't be proven stays as it was. */
+export declare function repairStaleStatuses(store: Store, now: Date): {
+    exitsRecorded: number;
+    readyForReview: number;
+};
 export declare function installationStatus(store: Store, now: Date): InstallationStatus;
 export declare function renderInstallationStatus(status: InstallationStatus): string[];
 export declare function renderTaskWait(snapshot: TaskWaitSnapshot, outcome?: string): string;

package/dist/lead-status.js

@@ -1,10 +1,10 @@
 /** Cheap lead-facing status. Every fact comes from indexed SQLite records;
  * this module never opens a repository, retained evidence, or a live log. */
-import { COMPLETION_ACTION } from "./result-completion.js";
+import { familyCompleted } from "./result-completion.js";
 import { windowLabel } from "./provider-limits.js";
 import { openAuthPauses, signInCommand, signInReason } from "./provider-auth.js";
 import { BUILT_IN, checkSuitesOf } from "./store.js";
-import { workIndexPage } from "./work-index.js";
+import { workIndexPage, workReadyForReview } from "./work-index.js";
 const maybeNumber = (value) => value === null || value === undefined || !Number.isInteger(Number(value)) ? null : Number(value);
 const CHECK_COLUMNS = "rc.status AS check_status, rc.exit_code AS check_exit_code, rc.suites_json AS check_suites_json";
 function checkOf(row) {
@@ -90,9 +90,9 @@ export function taskWaitSnapshot(store, taskId, now, watchedRun) {
         if (state !== "done")
             return answer("Ready", "Review result", true, 0, "ready");
     }
-    const completion = result === undefined ? undefined : store.handle.prepare(`SELECT 1 AS hit FROM action_ledger INDEXED BY work_completion
-    WHERE task_id = ? AND action = ? AND source = 'work' AND run_id = ? LIMIT 1`).get(taskId, COMPLETION_ACTION, Number(result["id"]));
-    if (state === "done" && completion !== undefined)
+    // A completed family is Complete from any of its tasks.
+    const completed = state === "done" && familyCompleted(store, taskId);
+    if (completed)
         return answer("Complete", "No action needed", true, 0, "complete");
     if (state === "done")
         return answer("Ready", "Review result", true, 0, "ready");
@@ -113,7 +113,7 @@ export function taskWaitSnapshot(store, taskId, now, watchedRun) {
         return answer("Needs a person", next, true, 1, "needs-person");
     }
     if (task["plan"] === "drafted")
-        return answer("Needs a person", "Review plan", true, 1, "needs-person");
+        return answer("Needs a person", "Approve plan", true, 1, "needs-person");
     if (Number(task["strikes"] ?? 0) >= 3)
         return answer("Needs a person", "Review repeated failures", true, 1, "needs-person");
     // An admitted attempt is already the work being watched. Its immutable
@@ -168,6 +168,15 @@ function queueReason(row) {
     return "ready for a worker";
 }
 /** Whole-installation status, deliberately aggregated and bounded. */
+/** The one-off repair on start. An older build left finished runs' process
+ * exits unrecorded and counted completed families as waiting; nothing about
+ * a status is stored, so recording every exit that can now be proven and
+ * re-deriving each open task's headline from the shared projection clears
+ * them. What can't be proven stays as it was. */
+export function repairStaleStatuses(store, now) {
+    const exitsRecorded = store.recordFinishedRunExits(now);
+    return { exitsRecorded, readyForReview: workReadyForReview(store, now, { principal: "operator", repos: null, includeUnplaced: true }, 0).count };
+}
 export function installationStatus(store, now) {
     const runningRows = store.handle.prepare(`SELECT run.id, run.role, run.phase, ref.external_id AS task
     FROM run INDEXED BY work_unfinished
@@ -208,22 +217,10 @@ export function installationStatus(store, now) {
         if (queuedTasks.length < 8)
             queuedTasks.push({ task: String(row["id"]), reason });
     }
-    const waitingCount = Number(store.handle.prepare(`SELECT COUNT(*) AS n FROM task INDEXED BY task_by_state
-    JOIN task_ref AS ref INDEXED BY sqlite_autoindex_task_ref_1 ON ref.backend = ? AND ref.external_id = task.id
-    WHERE task.state = 'done' AND EXISTS (SELECT 1 FROM run INDEXED BY work_result
-      WHERE run.task_ref = ref.id AND run.finished_at IS NOT NULL AND run.role IN ('builder','scout'))
-      AND NOT EXISTS (SELECT 1 FROM action_ledger INDEXED BY work_completion
-        WHERE action_ledger.task_id = task.id AND action_ledger.action = ? AND action_ledger.source = 'work'
-          AND action_ledger.run_id = (SELECT id FROM run INDEXED BY work_result WHERE task_ref = ref.id AND finished_at IS NOT NULL AND role IN ('builder','scout') ORDER BY id DESC LIMIT 1))`)
-        .get(BUILT_IN, COMPLETION_ACTION)?.["n"] ?? 0);
-    const waitingRows = store.handle.prepare(`SELECT task.id AS task, result.id, ${CHECK_COLUMNS}
-    FROM task INDEXED BY task_done_recent
-    JOIN task_ref AS ref INDEXED BY sqlite_autoindex_task_ref_1 ON ref.backend = ? AND ref.external_id = task.id
-    JOIN run AS result ON result.id = (SELECT id FROM run INDEXED BY work_result WHERE task_ref = ref.id AND finished_at IS NOT NULL AND role IN ('builder','scout') ORDER BY id DESC LIMIT 1)
-    LEFT JOIN run_check AS rc ON rc.run = result.id
-    WHERE task.state = 'done' AND NOT EXISTS (SELECT 1 FROM action_ledger INDEXED BY work_completion
-      WHERE action_ledger.task_id = task.id AND action_ledger.action = ? AND action_ledger.source = 'work' AND action_ledger.run_id = result.id)
-    ORDER BY task.updated_at DESC, task.id DESC LIMIT 5`).all(BUILT_IN, COMPLETION_ACTION);
+    // One per family, from the same projection as the Tasks list: a completed
+    // family (root or any revision) and a superseded version never count.
+    const ready = workReadyForReview(store, now, { principal: "operator", repos: null, includeUnplaced: true }, 5);
+    const checkRow = (run) => store.handle.prepare(`SELECT ${CHECK_COLUMNS} FROM run_check AS rc WHERE rc.run = ?`).get(run);
     // Run ids grow with time, so the newest finished release check is the
     // first finished row down the partial index.
     const release = store.handle.prepare(`SELECT run.id, run.finished_at, ${CHECK_COLUMNS}, ref.external_id AS task
@@ -240,7 +237,7 @@ export function installationStatus(store, now) {
             reasons: [...reasons].map(([reason, count]) => ({ reason, count })).sort((a, b) => b.count - a.count || a.reason.localeCompare(b.reason)),
             tasks: queuedTasks,
         },
-        waitingForReview: { count: waitingCount, results: waitingRows.map(row => ({ task: String(row["task"]), run: Number(row["id"]), check: checkOf(row) })) },
+        waitingForReview: { count: ready.count, results: ready.results.map(one => ({ task: one.taskId, run: one.run, check: checkOf(one.run === null ? undefined : checkRow(one.run)) })) },
         releaseCheck: release === undefined ? null : { task: String(release["task"]), run: Number(release["id"]), finishedAt: release["finished_at"] == null ? null : String(release["finished_at"]), check: checkOf(release) },
         planWindows: store.handle.prepare(`SELECT provider, window, used_percent, window_minutes, resets_at, reached, plan, observed_at
       FROM provider_limit INDEXED BY sqlite_autoindex_provider_limit_1 ORDER BY provider, window`).all().map(row => ({
@@ -271,7 +268,7 @@ export function renderInstallationStatus(status) {
     }
     lines.push(status.running.count === 0 ? "Building: none" : `Building: ${status.running.count} — ${status.running.tasks.map(one => `${one.task} (#${one.run}, ${one.phase})`).join(", ")}${status.running.count > status.running.tasks.length ? ", …" : ""}`);
     lines.push(status.queued.count === 0 ? "Queued: none" : `Queued: ${status.queued.count} — ${status.queued.tasks.map(one => `${one.task} (${one.reason})`).join(", ")}${status.queued.count > status.queued.tasks.length ? ", …" : ""}`);
-    lines.push(status.waitingForReview.count === 0 ? "Ready for review: none" : `Ready for review: ${status.waitingForReview.count} — ${status.waitingForReview.results.map(one => `${one.task} (#${one.run})`).join(", ")}${status.waitingForReview.count > status.waitingForReview.results.length ? ", …" : ""}`);
+    lines.push(status.waitingForReview.count === 0 ? "Ready for review: none" : `Ready for review: ${status.waitingForReview.count} — ${status.waitingForReview.results.map(one => one.run === null ? one.task : `${one.task} (#${one.run})`).join(", ")}${status.waitingForReview.count > status.waitingForReview.results.length ? ", …" : ""}`);
     if (status.releaseCheck === null) {
         lines.push("Release check: none recorded");
     }

package/dist/needs-you.d.ts

@@ -0,0 +1,55 @@
+/** Every reason a task, result or flow card can wait on a person, in one
+ * place: the plain sentence it shows and the one action that resolves it
+ * (task-status.ts reads it for every surface). A reason no person can act
+ * on is not Needs you: it is a Waiting reason, worded as what it waits for.
+ *
+ * The words never name the machine's internals; `plainSentence` keeps a
+ * recorded reason only when it is free of them. */
+/** What a person is asked for. */
+export type NeedKey = "approval" | "card" | "answer" | "questions" | "sign-in" | "confirm-stopped" | "check-stopped" | "hold" | "choose-project" | "define-task" | "fix-request" | "choose-agent" | "fix-dependency" | "add-requirement" | "connect-builder" | "start-builder" | "vanished" | "review-result" | "rebuild" | "earlier-version" | "other";
+/** What the work waits for when no person can act. */
+export type WaitKey = "build-stopping" | "other-computer" | "card-reply" | "card-time" | "card-ci";
+/** The action's code: the WorkAction that owns the act, or one of the acts a surface renders itself. */
+export type NeedActionCode = "approve-scope" | "approve-card" | "answer-decision" | "inspect-decisions" | "sign-in" | "confirm-stopped" | "inspect-hold" | "place-task" | "write-scope" | "select-agent" | "repair-dependency" | "repair-capability" | "start-worker" | "reconcile-run" | "open-result" | "retry-task" | "inspect-task";
+export type NeedAction = {
+    code: NeedActionCode;
+    label: string;
+};
+/** `build`: the run a sentence names; `provider`: the agent that signed out. */
+export type NeedContext = {
+    build?: number | null;
+    provider?: string | null;
+};
+/** `useReason`: which recorded reasons say what is needed better than the default words. */
+type Need = {
+    sentence: (context: NeedContext) => string;
+    action: NeedAction;
+    useReason?: (reason: string) => boolean;
+    /** How a kept reason reads: by default the reason alone. */
+    withReason?: (reason: string) => string;
+};
+export declare const NEEDS: Readonly<Record<NeedKey, Need>>;
+export declare const WAITS: Readonly<Record<WaitKey, (context: NeedContext) => string>>;
+/** Words that name the machine's internals; no Needs you or Waiting sentence carries them. */
+export declare const BANNED_WORDS: readonly ["witness", "unproven", "quiescence", "quiescent", "digest", "scope digest"];
+export declare const hasInternalWords: (text: string) => boolean;
+/** The sentence for a need: its recorded reason when the need keeps one and
+ * it reads plainly, otherwise the need's own words. */
+export declare function needSentence(key: NeedKey, reason: string | null, context?: NeedContext): string;
+export declare function waitSentence(key: WaitKey | undefined, reason: string | null, context?: NeedContext): string;
+/** A finished run Toolroll can't prove stopped (store.stopQuiescenceFact):
+ * a person can confirm it only when nothing of it may still be running.
+ * `unknown`: Toolroll can't check, so the person confirms they checked. */
+export declare function processNeedOf(fact: {
+    run: number;
+    kind: "open" | "alive" | "elsewhere" | "unprovable" | "unknown";
+} | null): {
+    need: "confirm-stopped" | "check-stopped";
+    build: number;
+} | {
+    wait: WaitKey;
+    build: number;
+} | null;
+/** Dispatch and work-index codes that wait on a person, as their need. */
+export declare const CODE_NEED: Readonly<Record<string, NeedKey>>;
+export {};