toolroll 0.9.7 → 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/dispatch.js

@@ -13,6 +13,7 @@ import { plannerSourceProblemOf } from "./planner-source.js";
 import { authPauseOf, authWaitOf, providerName, signInReason } from "./provider-auth.js";
 import { REVIEW_TOKENS, resultStatusOf, reviewFactsOf } from "./workspace-ui.js";
 import { replacedWords } from "./task-status.js";
+import { buildReviewOf } from "./review-switch.js";
 import { BUILT_IN, parseCapabilityKey } from "./store.js";
 export const DEFAULT_MAX_OPEN_DECISIONS = 5;
 /**
@@ -187,7 +188,7 @@ export function diagnoseTaskDispatch(store, taskId, now) {
         const reviewFacts = reviewFactsOf(retry, runner => {
             const reviewer = store.getRunner(runner)?.runner;
             return reviewer !== undefined && isAlive(reviewer, now);
-        });
+        }, result !== undefined && buildReviewOf(store, result.id)?.state === "pending");
         // A no-change conclusion owes no proof beyond its handoff and sealed
         // diff (the task page's own "attested floor"); with both on record it
         // is complete, not verification-needed.

package/dist/dispose.d.ts

@@ -85,9 +85,10 @@ export type Disposition = {
     kind: "invariant";
     reason: string;
 };
-/** Compatibility for historical integrations: finished work is handed to the
- * lead. No model review is requested and no signed history is rewritten. */
-export declare function maybeRequestAutoReview(_store: Store, _repo: string, _runId: number, _committed: boolean, _noChange: boolean, _now: Date): void;
+/** A committed build whose approved check passed gets the project's one
+ * automatic review when its review switch is on (build-review.ts). No-change
+ * results and failed checks go straight to the person, as before. */
+export declare function maybeRequestAutoReview(store: Store, repo: string, runId: number, committed: boolean, noChange: boolean, now: Date, root?: string): void;
 export declare function disposeBuildOutcome(context: DisposeContext, result: BuildResult): Disposition;
 /**
  * The stale-approval HOLD, shared by the post-build disposition above and

package/dist/dispose.js

@@ -17,7 +17,9 @@ import { createHash } from "node:crypto";
 import { completeFenced, finalizeFailureFenced, finalizeHandBackFenced, finalizeMalformedFenced, finalizeParkFenced, interruptIfStopped, release, } from "./claim.js";
 import { bodyHashOf, publicationBody } from "./publish.js";
 import { modeTermsFromJson } from "./modes.js";
-import { readVerifiedArtifact, writeEvidenceFile } from "./evidence.js";
+import { evidenceRoot, readVerifiedArtifact, writeEvidenceFile } from "./evidence.js";
+import { queueBuildReview } from "./build-review.js";
+import { homedir } from "node:os";
 import {} from "./proof.js";
 import { verificationEvidence, failedVerificationEvidence } from "./verification-evidence.js";
 import { classifyGateFailure, describeGateFailure, gateFailureSummary } from "./gate-failure.js";
@@ -55,9 +57,14 @@ const STANDALONE_BROKE_REASONS = new Set([
     "timeout",
     "git",
 ]);
-/** Compatibility for historical integrations: finished work is handed to the
- * lead. No model review is requested and no signed history is rewritten. */
-export function maybeRequestAutoReview(_store, _repo, _runId, _committed, _noChange, _now) { }
+/** A committed build whose approved check passed gets the project's one
+ * automatic review when its review switch is on (build-review.ts). No-change
+ * results and failed checks go straight to the person, as before. */
+export function maybeRequestAutoReview(store, repo, runId, committed, noChange, now, root = evidenceRoot(homedir())) {
+    if (!committed || noChange)
+        return;
+    queueBuildReview(store, repo, runId, root, now);
+}
 export function disposeBuildOutcome(context, result) {
     // Stop and every terminal side effect compete under the same SQLite
     // write lock. A separate preliminary transaction leaves a completion gap.
@@ -238,6 +245,7 @@ function disposeBuildOutcomeLocked(context, result) {
             // proves the credential, clearing any quota stamp.
             store.resetStrikes(taskRef);
             store.clearQuota(runner, provider, model ?? "");
+            maybeRequestAutoReview(store, repo, runId, result.committed, result.noChange === true, clock(), context.evidenceRoot);
             return { kind: "built", committed: result.committed, noChange: result.noChange === true };
         }
         store.transact(() => {

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/exec.d.ts

@@ -113,6 +113,11 @@ export type RunOptions = ProcessTreeObserver & {
     /** Fires once the child exists, with its pid (the process-group id when
      * processGroup is set) — the slot ledger records it (v14 finding 26). */
     onSpawn?: (pid: number) => void;
+    /** Fires instead of onSpawn when a spawn that beforeSpawn admitted made no
+     * process at all (the OS call threw — ENOENT, EAGAIN — returned no pid, or
+     * its OS object could not be made), so its reserved witness can be settled
+     * as never started in the same step. Never fires once a child exists. */
+    onSpawnFailed?: () => void;
     /** Fires before any target spawn, so a crash cannot lose its OS object. */
     onContainer?: (info: {
         backend: ContainmentBackendId;

package/dist/exec.js

@@ -84,9 +84,24 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
         throw new ContainmentRefusal(effective.refusal);
     if (bag.beforeSpawn?.() === false)
         throw new Error("the attempt stopped before this process could spawn");
-    const made = effective === null ? { container: null } : createContainer(effective, label);
-    if ("refused" in made)
+    // From here a witness may be reserved: every road that makes no process
+    // says so through onSpawnFailed before it returns or throws.
+    const neverStarted = () => { try {
+        bag.onSpawnFailed?.();
+    }
+    catch { /* the reservation stays unproven */ } };
+    let made;
+    try {
+        made = effective === null ? { container: null } : createContainer(effective, label);
+    }
+    catch (error) {
+        neverStarted();
+        throw error;
+    }
+    if ("refused" in made) {
+        neverStarted();
         throw new ContainmentRefusal(made.refused);
+    }
     const container = made.container;
     try {
         if (container !== null)
@@ -94,6 +109,7 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
     }
     catch (error) {
         container?.release();
+        neverStarted();
         throw error;
     }
     let launch;
@@ -102,6 +118,7 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
     }
     catch (error) {
         container?.release();
+        neverStarted();
         throw error;
     }
     let child;
@@ -123,6 +140,7 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
         }
         catch { }
         container?.release();
+        neverStarted();
         throw error;
     }
     if (container !== null) {
@@ -143,6 +161,12 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
         if (child.pid !== undefined) {
             bag.onSpawn?.(child.pid);
         }
+        else if (container === null) {
+            // No pid: the OS refused the spawn (ENOENT, EACCES) and only an
+            // 'error' event follows. A contained spawn settles once its object is
+            // proven empty, and its transport's return finishes the witness.
+            neverStarted();
+        }
     }
     catch (error) {
         throw new SpawnCustodyFailure(child, error);
@@ -201,7 +225,7 @@ function containmentOf(container, empty, attachFailure) {
 }
 /** The streaming transports' spawn: contained when the spawn is a provider (process group), plain otherwise. */
 function spawnStream(file, args, options, stdio, childEnv) {
-    return spawnContained(file, args, { cwd: options.cwd, env: childEnv, stdio, detached: options.processGroup === true && process.platform !== "win32" }, options.owner ?? "stream", { beforeSpawn: options.beforeSpawn, onSpawn: options.onSpawn, onContainer: options.onContainer, onContainerEmpty: options.onContainerEmpty, onUnknown: options.onUnknown, fence: options.fence }, options.processGroup === true);
+    return spawnContained(file, args, { cwd: options.cwd, env: childEnv, stdio, detached: options.processGroup === true && process.platform !== "win32" }, options.owner ?? "stream", { beforeSpawn: options.beforeSpawn, onSpawn: options.onSpawn, onSpawnFailed: options.onSpawnFailed, onContainer: options.onContainer, onContainerEmpty: options.onContainerEmpty, onUnknown: options.onUnknown, fence: options.fence }, options.processGroup === true);
 }
 /** The refusal-before-spawn shape shared by every containable transport. */
 function refusedResult(error) {
@@ -506,6 +530,7 @@ export function run(file, args, options = {}) {
             ...(cwd === undefined ? {} : { cwd }),
             ...(childEnv === undefined ? {} : { childEnv }),
             ...(options.onSpawn === undefined ? {} : { onSpawn: options.onSpawn }),
+            ...(options.onSpawnFailed === undefined ? {} : { onSpawnFailed: options.onSpawnFailed }),
             ...(options.owner === undefined ? {} : { owner: options.owner }),
             ...(options.beforeSpawn === undefined ? {} : { beforeSpawn: options.beforeSpawn }),
             ...(options.onStdout === undefined ? {} : { onStdout: options.onStdout }),
@@ -553,7 +578,7 @@ function runBufferedGroup(file, args, bag) {
         let container = null;
         let attached;
         try {
-            const spawned = spawnContained(file, args, { cwd: bag.cwd, env: bag.childEnv, stdio: [bag.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"], detached: process.platform !== "win32" }, bag.owner ?? "buffered", { beforeSpawn: bag.beforeSpawn, onSpawn: bag.onSpawn, onContainer: bag.onContainer, onContainerEmpty: bag.onContainerEmpty, onUnknown: bag.onUnknown, fence: bag.fence });
+            const spawned = spawnContained(file, args, { cwd: bag.cwd, env: bag.childEnv, stdio: [bag.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"], detached: process.platform !== "win32" }, bag.owner ?? "buffered", { beforeSpawn: bag.beforeSpawn, onSpawn: bag.onSpawn, onSpawnFailed: bag.onSpawnFailed, onContainer: bag.onContainer, onContainerEmpty: bag.onContainerEmpty, onUnknown: bag.onUnknown, fence: bag.fence });
             child = spawned.child;
             container = spawned.container;
             attached = spawned.attached;
@@ -1578,6 +1603,7 @@ export function startClaudeHeldSession(file, args, options) {
             }, options.owner ?? "held", {
                 beforeSpawn: options.beforeSpawn,
                 onSpawn: options.onSpawn,
+                onSpawnFailed: options.onSpawnFailed,
                 onContainer: options.onContainer,
                 onContainerEmpty: options.onContainerEmpty,
                 onUnknown: options.onUnknown,

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" | "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

@@ -129,13 +129,15 @@ export const JOURNEY_STEPS = [["plan", "Plan"], ["approve", "You approve"], ["bu
  */
 export function firstTaskJourney(read, approved, built = false) {
     const at = read.stage === "finished" || read.stage === "complete" ? { index: 5, stuck: false }
-        : read.stage === "checking" ? { index: 3, 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/invoke.js

@@ -646,6 +646,11 @@ export async function invokeHeldAgent(store, runId, spec, argv, options) {
                 store.recordRunProcess(runId, pid, clock(), false, heldWitness);
                 runOptions.onSpawn?.(pid);
             },
+            onSpawnFailed: () => {
+                if (heldWitness !== undefined)
+                    store.finishUnspawnedProcess(heldWitness, clock());
+                runOptions.onSpawnFailed?.();
+            },
             onContainer: info => {
                 nativeHeld = true;
                 if (heldWitness !== undefined)

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;