toolroll 0.9.8 → 0.9.9

package/dist/test-temp.js

@@ -0,0 +1,98 @@
+/**
+ * Test temp folders (`toolroll storage`, `storage clean`): what the unit tests, journeys and scripts make in the
+ * system temp folder. The tests delete their own (each run gets one temp root that its global teardown removes:
+ * test/temp-root.ts); a run that was killed, and older versions, leave folders behind. `toolroll storage` counts them
+ * and `storage clean` removes the ones nothing has touched for a day.
+ *
+ * Every prefix the tests and scripts give tmpdir() is covered here (test-temp.test.ts reads the sources to keep it
+ * so), and Playwright's own browser profiles.
+ */
+import { lstatSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const DAY_MS = 86_400_000;
+/** Name prefixes of what tests, journeys and scripts leave in the temp folder. */
+export const TEST_TEMP_PREFIXES = [
+    "so-", "standing-orders-", "toolroll-", "no-wt", "epoch", "cancel-floor",
+    "attest-", "budgets-", "chat-v66-", "check-levels-", "coding-context-", "console-url-", "console-v2-", "e2-attest-",
+    "flow-goal-", "flow-scratch", "flows-chat-", "invoke-attest-", "knowledge-test-", "learning-", "peek-", "phone-origin-",
+    "proposal-repo-", "race-", "refresh-migration-", "refresh-refusal-", "release-check-", "shared-chat-", "skills-test-",
+    "task-status-surfaces-", "template-repo-", "template-test-", "v14-migrate-", "v17-migrate-", "watch-anchor-",
+    "needs-you-", "deps-lock-", "deps-state-", "upgrade-fresh-", "upgrade-path-",
+    // Playwright's browser profiles and artifacts.
+    "playwright_chromiumdev_profile-", "playwright_firefoxdev_profile-", "playwright-artifacts-",
+];
+export function isTestTemp(name) {
+    return TEST_TEMP_PREFIXES.some(prefix => name.startsWith(prefix));
+}
+/** Where they collect: the temp folder (and /tmp, where some scripts write). */
+export function tempRoots() {
+    const roots = [tmpdir()];
+    if (process.platform !== "win32" && !roots.includes("/tmp"))
+        roots.push("/tmp");
+    return roots;
+}
+/** When anything last happened in a folder: it, or what is directly in it, last changed. */
+function touchedAt(path) {
+    let newest = lstatSync(path).mtimeMs;
+    let names = [];
+    try {
+        names = readdirSync(path);
+    }
+    catch {
+        return newest;
+    }
+    for (const name of names) {
+        try {
+            newest = Math.max(newest, lstatSync(join(path, name)).mtimeMs);
+        }
+        catch { /* gone */ }
+    }
+    return newest;
+}
+/** Every test temp folder in `roots`, and which of them nothing has touched for a day. */
+export function testTempFolders(roots, now) {
+    const all = [];
+    const seen = new Set();
+    for (const root of roots) {
+        let names = [];
+        try {
+            names = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!isTestTemp(name))
+                continue;
+            const path = join(root, name);
+            try {
+                const stat = lstatSync(path);
+                const key = `${stat.dev}:${stat.ino}`;
+                if (seen.has(key) || stat.isSymbolicLink())
+                    continue;
+                seen.add(key);
+                all.push({ path, touchedAt: stat.isDirectory() ? touchedAt(path) : stat.mtimeMs });
+            }
+            catch { /* gone */ }
+        }
+    }
+    return { all, stale: all.filter(one => now.getTime() - one.touchedAt > DAY_MS) };
+}
+/** Remove the test temp folders nothing has touched for a day; each is looked at again right before it goes. */
+export function removeStaleTestTemp(roots, now) {
+    const removed = [];
+    const failed = [];
+    for (const one of testTempFolders(roots, now).stale) {
+        try {
+            if (now.getTime() - (lstatSync(one.path).isDirectory() ? touchedAt(one.path) : lstatSync(one.path).mtimeMs) <= DAY_MS)
+                continue;
+            rmSync(one.path, { recursive: true, force: true, maxRetries: 3 });
+            removed.push(one.path);
+        }
+        catch {
+            failed.push(one.path);
+        }
+    }
+    return { removed, failed };
+}

package/dist/toolroll-update-ui.js

@@ -12,7 +12,7 @@ export const UPDATES_CSS = `.updates{max-width:640px;min-width:0;overflow-wrap:a
     `.updates ol.update-steps li[data-state=failed]{color:var(--so-danger);font-weight:600}.updates ol.update-steps li[data-state=failed]::before{background:var(--so-danger);border-color:var(--so-danger)}` +
     `.updates ol.update-steps .step-detail{grid-column:2;font-weight:400;color:var(--so-muted);font-size:.8125rem;margin-top:2px}` +
     `.updates .whats-new ul{margin:10px 0 0;padding-left:18px}.updates .whats-new li{margin:4px 0}.updates .whats-new form{margin:14px 0 0}` +
-    `.updates .update-problem{color:var(--so-danger)}.updates .stamp{margin:10px 0 0}.updates code{white-space:nowrap}` +
+    `.updates .update-problem{color:var(--so-danger)}.updates .stamp{margin:10px 0 0}.updates code{white-space:nowrap}.updates [data-update-outcome=stopped] code,.updates .step-detail code{white-space:normal;overflow-wrap:anywhere}` +
     `@media (prefers-reduced-motion:no-preference){.updates ol.update-steps li[data-state=now]::before{animation:update-pulse 1.6s ease-in-out infinite}}@keyframes update-pulse{50%{box-shadow:0 0 0 7px color-mix(in srgb,var(--so-info) 6%,transparent)}}` +
     `@media (max-width:600px){.updates .update-actions{display:grid}.updates .update-actions button{width:100%;min-height:44px}.updates .step-up{max-width:none}.updates .step-up input{min-height:44px}}`;
 /** The steps, each done, current, failed or waiting. Also the live region's fragment. */
@@ -23,7 +23,8 @@ export function updateStepsHtml(j, running) {
     const items = UPDATE_STEPS.map((step, i) => {
         const state = j.phase === "complete" || i < last ? "done" : i > last ? "waiting" : failed ? "failed" : finished ? "waiting" : "now";
         // Only where it adds something: which work it waits for, or what went wrong.
-        const detail = (state === "now" && step === "draining") || (state === "failed" && j.phase === "rolling-back") ? `<span class="step-detail">${e(j.detail)}</span>` : "";
+        const detail = state === "now" && step === "draining" && j.waiting ? `<span class="step-detail">${e(j.waiting.on)}.${j.waiting.action ? ` If nothing of it is running, run <code>${e(j.waiting.action)}</code>.` : ""}</span>`
+            : (state === "now" && step === "draining") || (state === "failed" && j.phase === "rolling-back") ? `<span class="step-detail">${e(j.detail)}</span>` : "";
         return `<li data-step="${step}" data-state="${state}">${e(STEP_WORDS[step])}${detail}</li>`;
     }).join("");
     const title = j.phase === "scheduled" ? `Update to ${e(j.to.version)} scheduled for ${e(clock(j.at ?? j.startedAt))}`
@@ -38,6 +39,10 @@ function outcomeHtml(j) {
         return j.kind === "rollback" ? `<div class="card" data-update-outcome="rolled-back"><h2>Back on ${e(j.to.version)}</h2><p class="meta">${e(j.detail)}</p></div>` : "";
     if (j.phase === "cancelled")
         return `<div class="card" data-update-outcome="cancelled"><h2>Update cancelled</h2><p class="meta">Nothing changed.</p></div>`;
+    // Stopped on a finished run it can't show has ended: what is in the way and the one command, nothing more.
+    if (j.phase === "refused" && j.waiting)
+        return `<div class="card" data-update-outcome="stopped"><h2>Update to ${e(j.to.version)} stopped: run #${e(j.waiting.run)} is in the way</h2>` +
+            `<p>${e(j.waiting.on)}. New work resumed.</p>` + (j.waiting.action ? `<p class="meta">If nothing of it is running, run <code>${e(j.waiting.action)}</code>, then update again.</p>` : `<p class="meta">Update again once it has stopped.</p>`) + `</div>`;
     const title = j.phase === "refused" ? `Didn't update to ${e(j.to.version)}` : j.phase === "restored" ? `Update to ${e(j.to.version)} didn't finish` : "The update needs attention";
     return `<div class="card" data-update-outcome="${e(j.phase)}"><h2>${title}</h2><p class="${j.phase === "needs-attention" ? "update-problem" : ""}" role="alert">${e(j.detail)}</p>` +
         `<details><summary>Steps</summary>${updateStepsHtml(j, false).replace(/<h2>.*?<\/h2>/, "")}</details></div>`;

package/dist/toolroll-update.d.ts

@@ -1,4 +1,5 @@
 import type { DatabaseSync } from "node:sqlite";
+import { type LingeringRun, type UpdateWaiting } from "./desktop-update.js";
 import { type SupervisorRunner } from "./daemon.js";
 export declare const PROVENANCE_REPOSITORY = "https://github.com/ap9000/toolroll";
 export declare const PROVENANCE_WORKFLOW = ".github/workflows/publish.yml";
@@ -103,6 +104,11 @@ export type RuntimeUpdateJournal = {
      * the restored version and would be lost), and it keeps a fresh copy aside before every attempt until then. */
     restoredDatabase?: boolean;
     seen?: boolean;
+    /** The finished run the update is waiting on (or stopped waiting on): what is in the way and the command that
+     * clears it. Absent while it waits on ordinary running work. */
+    waiting?: LingeringRun & {
+        since: string;
+    };
 };
 export type PackageRelease = {
     version: string;
@@ -160,6 +166,8 @@ export type UpdateOutcome = {
     journal: RuntimeUpdateJournal | null;
 };
 export declare const runtimeUpdateTerminal: (phase: RuntimePhase) => boolean;
+/** How long a launched or resuming updater is expected to take to start and hold the lock. */
+export declare const UPDATER_START_MS: number;
 export declare function readRuntimeUpdate(stateDir: string, file?: string): RuntimeUpdateJournal | null;
 /** The update `--rollback` returns from: the last one that completed, whatever was attempted since. */
 export declare function lastCompletedUpdate(stateDir: string): RuntimeUpdateJournal | null;
@@ -245,6 +253,18 @@ export type RuntimeUpdateStatus = {
     } | null;
 };
 export declare function runtimeUpdateStatus(stateDir: string): RuntimeUpdateStatus;
+/** An update that is waiting, what on, and the one action that clears it: for `toolroll status` and the console.
+ * `inTheWay` asks whether a finished run still holds it up; a stopped update whose run has since cleared says nothing. */
+export type { UpdateWaiting };
+export declare function updateWaitingOf(stateDir: string, inTheWay: (run: number) => boolean): UpdateWaiting | null;
+/** An updater that ended while letting work finish (a crash, a kill, the Mac restarting) leaves new work paused with
+ * nobody left to lift the pause. With no updater holding the update, the pause is lifted here and the update says it
+ * stopped. Nothing was switched before the backup, so nothing else needs putting back. The background worker's
+ * reconcile, `toolroll status` and the console run this. Returns what it said, or null. */
+export declare function releaseStalledUpdate(stateDir: string, now: Date): string | null;
+/** What `toolroll status` and the console show: a stalled `toolroll update` released first, then this installation's
+ * waiting update, `toolroll update`'s or the desktop app's. */
+export declare function waitingUpdate(databaseFile: string, inTheWay: (run: number) => boolean, now: Date, desktopStates?: readonly string[]): UpdateWaiting | null;
 export declare function markWhatsNewSeen(stateDir: string): void;
 type Exec = (command: string, args: string[], options?: {
     cwd?: string;
@@ -282,8 +302,8 @@ export declare function launchRuntimeUpdate(args: {
     run?: SupervisorRunner;
     platform?: NodeJS.Platform;
     npmBin?: () => Promise<string | null>;
+    now?: () => Date;
 }): Promise<void>;
 /** The job's last act: its definition goes, so nothing can start it again. Only the definition for this id. */
 export declare function retireUpdateJob(id: string, home?: string): void;
 export declare const nextScheduledAt: typeof nextAt;
-export {};

package/dist/toolroll-update.js

@@ -29,7 +29,7 @@ import { homedir, userInfo } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
-import { durableJson, lingeringWork, sqliteLock, verifiedDatabaseBackup } from "./desktop-update.js";
+import { clearWords, durableJson, LINGERING_LIMIT_MS, lingeringRun, lingeringWords, settleLeftoverRecords, sqliteLock, desktopUpdateWaitingOf, stoppedWaitingWords, updateWaitingWords, verifiedDatabaseBackup } from "./desktop-update.js";
 import { activeUpdateWork, freezeUpdateGate, installUpdateGate, removeUpdateGate, updateAdmissionPaused, updateGateOwned } from "./desktop-update-gate.js";
 import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, removeCodingUpdateGate } from "./coding-update.js";
 import { installLaunchdService, launchdPlist, stopLaunchdService, writeFileDurably } from "./daemon.js";
@@ -61,6 +61,24 @@ const journalFile = (stateDir) => join(stateDir, "toolroll-update.json");
 /** The last completed update, kept apart from the journal: what `--rollback` returns from. */
 const lastUpdateFile = (stateDir) => join(stateDir, "toolroll-update.last.json");
 const cancelFile = (j) => join(j.stageDir, "cancel-request.json");
+/** An updater on its way to this update before it holds the lock: the console's job once launched (launchd may not
+ * have started it yet), or a resume about to drive it. */
+const startingFile = (j) => join(j.stageDir, "updater-starting.json");
+/** How long a launched or resuming updater is expected to take to start and hold the lock. */
+export const UPDATER_START_MS = 2 * 60_000;
+function markStarting(j, state, now) {
+    durableJson(startingFile(j), { id: j.id, state, at: now.toISOString() });
+}
+function updaterStarting(j, now) {
+    try {
+        const mark = JSON.parse(readFileSync(startingFile(j), "utf8"));
+        const age = now.getTime() - Date.parse(mark.at ?? "");
+        return mark.id === j.id && age >= 0 && age < UPDATER_START_MS;
+    }
+    catch {
+        return false;
+    }
+}
 const sha = (bytes, algorithm = "sha256") => createHash(algorithm).update(bytes).digest("hex");
 const fileHash = (file) => sha(readFileSync(file));
 const quote = (s) => '"' + s.replaceAll('"', '""') + '"';
@@ -744,6 +762,7 @@ export async function resumeRuntimeUpdate(stateDir, system, id) {
         return { ok: true, phase: j?.phase ?? "complete", message: "The update this job was started for is no longer the saved one. Nothing was changed.", journal: j };
     if (!j || runtimeUpdateTerminal(j.phase))
         return { ok: true, phase: j?.phase ?? "complete", message: "No update is in progress.", journal: j };
+    markStarting(j, "resuming", system.now());
     return driveRuntimeUpdate(j, system);
 }
 /** A prepared update whose job could not start. */
@@ -801,6 +820,23 @@ async function driveRuntimeUpdate(j, system) {
     const lock = sqliteLock(join(j.stageDir, "worker.sqlite"), 1000);
     if (!lock)
         return { ok: false, phase: j.phase, message: `An updater is already working on the update to ${j.to.version}.`, journal: j };
+    // What was read before the lock may be out of date: a stalled update released, or a cancel, in between.
+    let saved = null;
+    try {
+        saved = readRuntimeUpdate(j.stateDir);
+    }
+    catch {
+        saved = null;
+    }
+    if (saved?.id === j.id) {
+        if (runtimeUpdateTerminal(saved.phase)) {
+            lock.close();
+            return { ok: saved.phase === "complete" || saved.phase === "cancelled", phase: saved.phase, message: saved.detail, journal: saved };
+        }
+        Object.assign(j, saved);
+    }
+    // The lock now says an updater is here; the starting mark has done its job.
+    rmSync(startingFile(j), { force: true });
     const at = (phase) => UPDATE_STEPS.indexOf(phase);
     const step = (phase, detail) => { save(j, phase, detail, system.now()); system.checkpoint?.(phase); };
     const noun = j.kind === "update" ? "update" : "rollback";
@@ -1042,9 +1078,15 @@ async function drain(j, system) {
     try {
         db.exec("PRAGMA busy_timeout=5000");
         if (j.when === "now") {
-            const running = runningWorkWords(db) ?? lingeringWork(db);
+            const running = runningWorkWords(db);
             if (running)
                 throw new Refusal(`Work is running: ${running}. Nothing was changed. Use When idle to wait for it.`);
+            settleLeftoverRecords(db, system.now());
+            const lingering = lingeringRun(db);
+            if (lingering) {
+                j.waiting = { ...lingering, since: system.now().toISOString() };
+                throw new Refusal(`${lingering.on}. ${clearWords(lingering)} Nothing was changed.`);
+            }
             if (updateAdmissionPaused(db) && !updateGateOwned(db, j.id))
                 throw new Refusal("Another update owns the admission pause. Nothing was changed.");
             installUpdateGate(db, j.id);
@@ -1058,10 +1100,23 @@ async function drain(j, system) {
         for (;;) {
             if (cancelRequested(j))
                 return;
-            const lingering = Object.values(activeUpdateWork(db)).every(n => n === 0) ? lingeringWork(db) : null;
-            if (!lingering && freezeUpdateGate(db, j.id))
+            const idle = Object.values(activeUpdateWork(db)).every(n => n === 0);
+            // The same settling reconcile the background worker runs, so a leftover record it can prove never holds this up.
+            if (idle)
+                settleLeftoverRecords(db, system.now());
+            const lingering = idle ? lingeringRun(db) : null;
+            if (!lingering && freezeUpdateGate(db, j.id)) {
+                delete j.waiting;
                 return;
-            save(j, "draining", `New work is paused. Waiting for ${lingering ?? runningWorkWords(db) ?? "running work"} to finish. Nothing is being cancelled.`, system.now());
+            }
+            if (!lingering)
+                delete j.waiting;
+            else if (j.waiting?.run !== lingering.run || j.waiting.on !== lingering.on)
+                j.waiting = { ...lingering, since: system.now().toISOString() };
+            // Waiting longer on a finished run proves nothing more: stop, let new work resume, and say what clears it.
+            if (j.waiting && system.now().getTime() - Date.parse(j.waiting.since) >= LINGERING_LIMIT_MS)
+                throw new Refusal(stoppedWaitingWords(j.waiting));
+            save(j, "draining", lingering ? `New work is paused. Waiting for run #${lingering.run}: ${lingeringWords(lingering)}` : `New work is paused. Waiting for ${runningWorkWords(db) ?? "running work"} to finish. Nothing is being cancelled.`, system.now());
             await system.sleep(2000);
         }
     }
@@ -1121,6 +1176,77 @@ export function runtimeUpdateStatus(stateDir) {
     }
     return { journal: j, running, whatsNew, lastUpdate: last ? { from: last.from.version, to: last.to.version } : null };
 }
+export function updateWaitingOf(stateDir, inTheWay) {
+    let j;
+    try {
+        j = readRuntimeUpdate(stateDir);
+    }
+    catch {
+        return null;
+    }
+    if (!j || j.kind !== "update")
+        return null;
+    const version = j.to.version;
+    if (j.phase === "draining")
+        return updateWaitingWords({ app: false, version, stopped: false, lingering: j.waiting ?? null });
+    if (j.phase !== "refused" || !j.waiting || !inTheWay(j.waiting.run))
+        return null;
+    return updateWaitingWords({ app: false, version, stopped: true, lingering: j.waiting });
+}
+/** An updater that ended while letting work finish (a crash, a kill, the Mac restarting) leaves new work paused with
+ * nobody left to lift the pause. With no updater holding the update, the pause is lifted here and the update says it
+ * stopped. Nothing was switched before the backup, so nothing else needs putting back. The background worker's
+ * reconcile, `toolroll status` and the console run this. Returns what it said, or null. */
+export function releaseStalledUpdate(stateDir, now) {
+    let j;
+    try {
+        j = readRuntimeUpdate(stateDir);
+    }
+    catch {
+        return null;
+    }
+    if (!j || j.phase !== "draining")
+        return null;
+    const lock = sqliteLock(join(j.stageDir, "worker.sqlite"));
+    if (!lock)
+        return null;
+    try {
+        // An updater may have moved on, or a resumed one replaced it, between the first read and the lock.
+        const held = readRuntimeUpdate(stateDir);
+        if (!held || held.id !== j.id || held.phase !== "draining")
+            return null;
+        // A job launched or a resume under way has not taken the lock yet: it continues this update; nothing is lifted under it.
+        if (updaterStarting(held, now))
+            return null;
+        try {
+            ungate(held);
+        }
+        catch { /* no pause yet, or the database is unreadable: the journal still says it stopped */ }
+        if (held.kind === "update")
+            rmSync(join(held.stageDir, "runtime"), { recursive: true, force: true });
+        const noun = held.kind === "update" ? "update" : "rollback";
+        const words = `The ${noun} to ${held.to.version} stopped: its updater ended before running work finished. Nothing was changed; new work resumed. Run toolroll ${noun === "update" ? "update" : "update --rollback"} to try again.`;
+        save(held, "refused", words, now);
+        try {
+            ledger(held.databaseFile, now, held.actor, `toolroll ${noun} stopped`, "refused", `${held.from.version} → ${held.to.version}: the updater ended while draining`);
+        }
+        catch { /* the journal still says what happened */ }
+        return words;
+    }
+    finally {
+        lock.close();
+    }
+}
+/** What `toolroll status` and the console show: a stalled `toolroll update` released first, then this installation's
+ * waiting update, `toolroll update`'s or the desktop app's. */
+export function waitingUpdate(databaseFile, inTheWay, now, desktopStates) {
+    const stateDir = dirname(databaseFile);
+    try {
+        releaseStalledUpdate(stateDir, now);
+    }
+    catch { /* an unreadable record is shown as it is */ }
+    return updateWaitingOf(stateDir, inTheWay) ?? desktopUpdateWaitingOf(databaseFile, inTheWay, desktopStates);
+}
 export function markWhatsNewSeen(stateDir) {
     const j = readRuntimeUpdate(stateDir);
     if (!j || j.seen || j.phase !== "complete")
@@ -1362,6 +1488,10 @@ export async function launchRuntimeUpdate(args, seams = {}) {
     const dist = args.dist ?? dirname(fileURLToPath(import.meta.url));
     const command = [process.execPath, join(dist, "bin.js"), "update", "--resume", "--id", args.id, "--db", args.databaseFile];
     const stateDir = dirname(args.databaseFile);
+    // Pending until launchd starts the job and it holds the lock: nothing releases the update meanwhile.
+    const saved = readRuntimeUpdate(stateDir);
+    if (saved?.id === args.id && !runtimeUpdateTerminal(saved.phase))
+        markStarting(saved, "launched", (seams.now ?? (() => new Date()))());
     const log = join(stateDir, "toolroll-update.log");
     if ((seams.platform ?? process.platform) === "darwin") {
         const home = seams.home ?? homedir();

package/dist/work-index.d.ts

@@ -66,3 +66,14 @@ export declare class WorkIndexCursorError extends Error {
  * Cursors bind the admitted scope, project and view, never broaden access. */
 export declare function workIndexPage(store: Store, now: Date, access: WorkSummaryAccess, options?: WorkIndexOptions): WorkIndexPage;
 export declare function workCountsByProject(store: Store, now: Date, access: WorkSummaryAccess): WorkProjectCounts[];
+/** Families whose headline is Ready for review, newest first: the Tasks
+ * list's own rows, so a completed family (root or any revision), a failed
+ * check and a superseded version never count. */
+export declare function workReadyForReview(store: Store, now: Date, access: WorkSummaryAccess, limit?: number): {
+    count: number;
+    results: {
+        rootId: string;
+        taskId: string;
+        run: number | null;
+    }[];
+};

package/dist/work-index.js

@@ -1,12 +1,17 @@
 /** Paginated, permission-bound summaries of saved task facts. These reads do
- * not verify artifacts, inspect processes, or authorize task operations. */
+ * not verify artifacts or authorize task operations; a build Toolroll can't
+ * yet confirm stopped is read through the store's own read-only probe. */
 import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { readProjectAccess } from './project-access.js';
 import { pauseOnTaskProviders, providerName, signInReason } from './provider-auth.js';
-import { scopeTermsProblem } from './store.js';
+import { scopeTermsProblem, stopFactOf } from './store.js';
 import { plainReasonOf, replacedWords, stageOfCode, taskStatusOf, workToneOf } from './task-status.js';
 import { isCheckLevel } from './check-levels.js';
+import { MARKER } from './worktree.js';
 import { withFollowUps } from './result-follow-ups.js';
+import { NEEDS, processNeedOf } from './needs-you.js';
 export const WORK_INDEX_PAGE_LIMIT = 40;
 export const WORK_INDEX_MAX_LIMIT = 100;
 const EMPTY = { all: 0, 'needs-you': 0, running: 0, completed: 0 };
@@ -20,6 +25,8 @@ const s = (row, key) => row[key] == null ? null : String(row[key]);
  * MATERIALIZED prevents counts + page selection repeating correlated reads. */
 /** A gate note counts only while its pause is on one of the task's current providers. */
 const GATE_PAUSE_ON_TASK = pauseOnTaskProviders('p', 'c.ref_id');
+/** A row whose build may still be running (the store's reading, custodyReadings): Waiting, not Needs you. */
+const CUSTODY_WAITS = `(custody_unresolved AND code IN ('process-needs-attention','result-needs-attention') AND ref_id IN (SELECT value FROM json_each($waitingCustody)))`;
 const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
   SELECT t.id, t.title, t.state, t.created_at, t.updated_at, r.id ref_id, r.repo,
     r.revision_of, r.revision_brief_artifact, r.assigned_runner, r.plan,
@@ -55,7 +62,8 @@ const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
     (SELECT id FROM run WHERE task_ref=a.ref_id AND outcome IS NULL ORDER BY id DESC LIMIT 1) unfinished,
     CASE WHEN a.state='done' THEN (SELECT id FROM run WHERE task_ref=a.ref_id AND finished_at IS NOT NULL AND role IN ('builder','scout') ORDER BY id DESC LIMIT 1) END result_id,
     (SELECT h.id FROM hold h WHERE h.task_ref=a.ref_id AND (h.until IS NULL OR h.until>$now) ORDER BY h.held_at,h.id LIMIT 1) hold_id,
-    q.decision_id,cu.task_ref IS NOT NULL custody_unresolved
+    q.decision_id,(cu.task_ref IS NOT NULL OR a.ref_id IN (SELECT value FROM json_each($workspaceCustody)))
+      AND a.ref_id NOT IN (SELECT value FROM json_each($settledCustody)) custody_unresolved
   FROM admitted a LEFT JOIN lineage l ON l.ref_id=a.ref_id
   LEFT JOIN questions q ON q.task_ref=a.ref_id LEFT JOIN custody cu ON cu.task_ref=a.ref_id
 ), family_heads AS MATERIALIZED (
@@ -197,9 +205,9 @@ const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
     ELSE 'queued' END code
   FROM checked f
 ), ranked AS MATERIALIZED (
-  SELECT c.*,code NOT IN ('cancelled','complete','running','updating','retry-scheduled','waiting-dependency','worker-at-capacity','planning-ready','scouting-ready','queued') needs,
+  SELECT c.*,code NOT IN ('cancelled','complete','running','updating','retry-scheduled','waiting-dependency','worker-at-capacity','planning-ready','scouting-ready','queued') AND NOT ${CUSTODY_WAITS} needs,
     CASE WHEN code='complete' THEN 3 WHEN code='cancelled' THEN 4 WHEN code='running' THEN 1
-      WHEN code IN ('updating','retry-scheduled','waiting-dependency','worker-at-capacity','planning-ready','scouting-ready','queued') THEN 2 ELSE 0 END rank,
+      WHEN ${CUSTODY_WAITS} OR code IN ('updating','retry-scheduled','waiting-dependency','worker-at-capacity','planning-ready','scouting-ready','queued') THEN 2 ELSE 0 END rank,
     CASE WHEN code='complete' THEN completed.at ELSE family_updated END sort_at,
     completed.actor checked_actor,completed.at checked_at,completed.outcome checked_digest
   FROM classified c LEFT JOIN action_ledger completed ON completed.id=c.checked_id WHERE ($state IS NULL OR c.state=$state) AND ($leadId IS NULL OR EXISTS(SELECT 1 FROM team_task_owner own WHERE own.task_ref=c.root_ref AND own.lead=$leadId))
@@ -235,8 +243,38 @@ function registerValidators(store) {
     registered.set(db, projection);
     return projection;
 }
-function parameters(now, access, options) {
-    return { $now: now.toISOString(), $alive: new Date(now.getTime() - 180_000).toISOString(),
+/** The list can't see processes: each task whose build Toolroll can't yet
+ * confirm stopped, as the store reads it now (the task page's own reading).
+ * Null when it has since settled; `open` runs are the classification's own.
+ * `workspace`: a finished task whose last build's workspace note is still
+ * there, which only the store can read (a held or unreadable workspace). */
+function custodyReadings(store) {
+    const refs = store.handle.prepare(`SELECT r.task_ref FROM held_session h JOIN run r ON r.id=h.run WHERE h.ended_at IS NULL
+    UNION SELECT r.task_ref FROM run r WHERE r.provider_started_at IS NOT NULL AND NOT EXISTS(SELECT 1 FROM run_process p WHERE p.run=r.id)
+    UNION SELECT r.task_ref FROM run_process p JOIN run r ON r.id=p.run WHERE p.exited_at IS NULL AND p.container_empty_at IS NULL`).all().map(row => Number(row['task_ref']));
+    const noted = store.handle.prepare(`SELECT r.task_ref,r.worktree FROM task t JOIN task_ref tr ON tr.external_id=t.id
+    JOIN run r ON r.id=(SELECT MAX(id) FROM run WHERE task_ref=tr.id AND role IN ('builder','scout') AND finished_at IS NOT NULL)
+    WHERE t.state='done' AND r.worktree IS NOT NULL`).all()
+        .filter(row => existsSync(join(String(row['worktree']), MARKER))).map(row => Number(row['task_ref']));
+    const readings = new Map();
+    for (const ref of new Set([...refs, ...noted])) {
+        let found = null;
+        for (const run of store.runsFor(ref)) {
+            const fact = stopFactOf(store, run.id);
+            if (fact !== null && fact.kind !== 'open') {
+                found = fact;
+                break;
+            }
+        }
+        readings.set(ref, found);
+    }
+    return { readings, workspace: new Set(noted) };
+}
+function parameters(now, access, options, custody) {
+    const ids = (keep) => JSON.stringify([...custody.readings].filter(([ref, fact]) => keep(ref, fact)).map(([ref]) => ref));
+    return { $settledCustody: ids((_, fact) => fact === null), $waitingCustody: ids((_, fact) => fact !== null && 'wait' in (processNeedOf(fact) ?? {})),
+        $workspaceCustody: ids((ref, fact) => fact !== null && custody.workspace.has(ref)),
+        $now: now.toISOString(), $alive: new Date(now.getTime() - 180_000).toISOString(),
         $all: access.repos === null ? 1 : 0, $repos: JSON.stringify(access.repos ?? []),
         $unplaced: access.principal === 'operator' && access.includeUnplaced === true ? 1 : 0,
         $projectSet: options.project != null ? 1 : 0, $project: options.project ?? null, $state: options.state ?? null, $leadId: options.leadId ?? null };
@@ -279,6 +317,7 @@ function readCursor(value, scope) {
  * Cursors bind the admitted scope, project and view, never broaden access. */
 export function workIndexPage(store, now, access, options = {}) {
     const projection = registerValidators(store);
+    const custody = custodyReadings(store);
     const view = VIEWS.includes(options.view ?? 'all') ? options.view ?? 'all' : 'all';
     const limit = Number.isFinite(options.limit) ? Math.max(1, Math.min(WORK_INDEX_MAX_LIMIT, Math.floor(options.limit))) : WORK_INDEX_PAGE_LIMIT;
     const scope = cursorScope(access, options, view), cursor = readCursor(options.cursor, scope);
@@ -309,21 +348,39 @@ export function workIndexPage(store, now, access, options = {}) {
     'question_run',(SELECT run FROM decision WHERE id=page.question_id),'replaced_by',(SELECT successor FROM task_replacement WHERE task_ref=page.ref_id),
     'completed_by_lead',(SELECT lead FROM task_act WHERE task_ref=page.root_ref AND act='completed' ORDER BY id DESC LIMIT 1),
     'question_task',(SELECT r.external_id FROM decision d JOIN run ON run.id=d.run JOIN task_ref r ON r.id=run.task_ref WHERE d.id=page.question_id)) FROM page`)
-        .all({ ...parameters(now, access, options), $cursorRoot: cursor?.root ?? 0, $cursorRank: cursor?.rank ?? 0, $cursorAt: cursor?.at ?? '', $limit: limit + 1, $recent: new Date(now.getTime() - 86_400_000).toISOString() });
+        .all({ ...parameters(now, access, options, custody), $cursorRoot: cursor?.root ?? 0, $cursorRank: cursor?.rank ?? 0, $cursorAt: cursor?.at ?? '', $limit: limit + 1, $recent: new Date(now.getTime() - 86_400_000).toISOString() });
     const selected = rows.slice(1).map(row => JSON.parse(String(row['row_json'])));
     const page = selected.slice(0, limit), last = page.at(-1);
     const nextCursor = selected.length > limit && last !== undefined ? Buffer.from(JSON.stringify({ version: 1, scope,
         rank: n(last, 'rank'), at: s(last, 'sort_at'), root: n(last, 'root_ref') })).toString('base64url') : null;
     const projects = JSON.parse(String(rows[0]?.['row_json'] ?? '[]')).map(row => ({ repo: s(row, 'repo'), totals: counts(row), queued: n(row, 'queued'), doneRecently: n(row, 'done_recently') }));
-    return { items: page.map(row => itemOf(row, access.principal)), projects, totals: rows[0] === undefined ? { ...EMPTY } : counts(rows[0]), nextCursor, limit, view };
+    // A row whose build Toolroll can't confirm stopped reads the store's own answer, as the task page does.
+    const probe = (taskId) => {
+        const ref = store.lookupRef(taskId);
+        return ref === null ? null : custody.readings.get(ref.id) ?? null;
+    };
+    return { items: page.map(row => itemOf(row, access.principal, probe)), projects, totals: rows[0] === undefined ? { ...EMPTY } : counts(rows[0]), nextCursor, limit, view };
 }
 export function workCountsByProject(store, now, access) {
     const projection = registerValidators(store);
     return store.handle.prepare(`${projection} SELECT repo,${TOTALS},SUM(state='queued' AND family_running=0) queued,
     SUM(state='done' AND family_running=0 AND updated_at>=$recent) done_recently FROM ranked GROUP BY repo ORDER BY repo`)
-        .all({ ...parameters(now, access, {}), $recent: new Date(now.getTime() - 86_400_000).toISOString() })
+        .all({ ...parameters(now, access, {}, custodyReadings(store)), $recent: new Date(now.getTime() - 86_400_000).toISOString() })
         .map(row => ({ repo: s(row, 'repo'), totals: counts(row), queued: n(row, 'queued'), doneRecently: n(row, 'done_recently') }));
 }
+/** Families whose headline is Ready for review, newest first: the Tasks
+ * list's own rows, so a completed family (root or any revision), a failed
+ * check and a superseded version never count. */
+export function workReadyForReview(store, now, access, limit = 5) {
+    const ready = [];
+    let cursor = null;
+    do {
+        const page = workIndexPage(store, now, access, { view: 'needs-you', limit: WORK_INDEX_MAX_LIMIT, cursor });
+        ready.push(...page.items.filter(one => one.status.label === 'Ready for review'));
+        cursor = page.nextCursor;
+    } while (cursor !== null);
+    return { count: ready.length, results: ready.slice(0, Math.max(0, limit)).map(one => ({ rootId: one.rootId, taskId: one.activeTaskId, run: one.resultRunId })) };
+}
 /** Labels stay navigation, never an authorization to mutate. Full task
  * opening re-proves process custody, receipt bytes and approval terms. */
 /** The list's Checks: the build's own result, its level, and follow-up checks on the same commit (result-follow-ups.ts). */
@@ -347,9 +404,16 @@ function listChecksOf(own, level, follows) {
         return null;
     return { status: read.status, exitCode: null, head: null, level: read.level, running: read.running };
 }
-function itemOf(row, principal) {
+/** Index codes that wait on a person, as their need (needs-you.ts); dispatch codes come from task-status's own table. */
+const INDEX_NEED = {
+    'earlier-active': 'earlier-version', 'process-needs-attention': 'confirm-stopped', 'invalid-scope': 'define-task', 'decision-queue': 'questions',
+};
+function itemOf(row, principal, probe) {
     const code = String(row['code']), id = String(row['id']);
-    const need = n(row, 'needs') === 1, running = n(row, 'family_running') === 1;
+    const custody = code === 'process-needs-attention' || (code === 'result-needs-attention' && n(row, 'custody_unresolved') === 1);
+    const process = custody && probe !== undefined ? processNeedOf(probe(id)) : null;
+    const waiting = process !== null && 'wait' in process;
+    const need = n(row, 'needs') === 1 && !waiting, running = n(row, 'family_running') === 1;
     const assignmentState = code === 'complete' ? 'complete' : code === 'ready-to-check' ? 'ready-to-check'
         : code === 'cancelled' ? 'cancelled' : need ? 'needs-decision' : 'working';
     const words = {
@@ -375,7 +439,7 @@ function itemOf(row, principal) {
         'needs-scope': ['Needs your decision', 'Define the task before a worker can start.', 'write-scope', 'Define the task'],
         'invalid-scope': ['Needs your decision', 'The saved task scope cannot be read safely.', 'write-scope', 'Review scope'],
         'needs-agent-profile': ['Needs your decision', 'Choose an available agent for this task.', 'select-agent', 'Choose an agent'],
-        'needs-approval': ['Needs your decision', 'Review the current plan before a worker can start.', 'approve-scope', 'Review plan'],
+        'needs-approval': ['Needs your decision', 'Review the current plan before a worker can start.', 'approve-scope', 'Approve plan'],
         'missing-requirement': ['Needs your decision', 'A required capability is missing or expired.', 'repair-capability', 'Review missing requirement'],
         'no-worker-registered': ['Needs your decision', 'No connected builder includes this project.', 'start-worker', 'Check connection'],
         'no-worker-online': ['Needs your decision', 'The builder has stopped checking in.', 'start-worker', 'Check connection'],
@@ -409,6 +473,18 @@ function itemOf(row, principal) {
         actionCode = 'open-result';
         actionLabel = 'Open result';
     }
+    if (process !== null && 'need' in process) {
+        actionCode = 'confirm-stopped';
+        actionLabel = NEEDS[process.need].action.label;
+    }
+    else if (custody && probe === undefined) {
+        actionCode = 'confirm-stopped';
+        actionLabel = NEEDS['confirm-stopped'].action.label;
+    }
+    if (code === 'signed-out') {
+        actionCode = 'sign-in';
+        actionLabel = NEEDS['sign-in'].action.label;
+    }
     if (actionCode === null) {
         actionCode = code === 'running' ? 'inspect-run' : 'inspect-task';
         actionLabel = code === 'running' ? 'Watch the build' : 'View task details';
@@ -417,21 +493,32 @@ function itemOf(row, principal) {
     const primaryAction = actionCode === null ? null : { code: actionCode, label: actionLabel,
         target: { taskId: successor ?? (code === 'earlier-active' ? s(row, 'earlier_id') ?? id : actionCode === 'answer-decision' ? s(row, 'question_task') ?? id : id),
             runId: actionCode === 'answer-decision' ? n(row, 'question_run') || null : actionCode === 'inspect-run' && code === 'running' ? n(row, 'live_run') || null : actionCode === 'open-result' || actionCode === 'inspect-run' ? n(row, 'result_id') || null
-                : actionCode === 'reconcile-run' ? n(row, 'unfinished') || null : ['resume-run', 'inspect-stop'].includes(actionCode) ? n(row, 'stop_run') || null : null,
+                : actionCode === 'reconcile-run' ? n(row, 'unfinished') || null : ['resume-run', 'inspect-stop'].includes(actionCode) ? n(row, 'stop_run') || null
+                    : actionCode === 'confirm-stopped' ? process?.build ?? (n(row, 'result_id') || null) : null,
             decisionId: actionCode === 'answer-decision' ? n(row, 'question_id') || null : null },
         access: read ? 'read' : principal === 'operator' ? 'operator-control' : ['answer-decision', 'write-scope', 'unhold'].includes(actionCode) ? 'proposal-only' : 'operator-handoff',
         retry: actionCode === 'reconcile-run' ? 'reconcile-before-retry' : read ? 'read-again' : 'refresh-before-acting' };
     // The one shared status: the headline and sentence every surface uses.
-    const reading = stageOfCode(code, { needsPerson: need, planning: s(row, 'live_role') === 'planner', operatorHold: s(row, 'hold_kind') === 'operator' });
+    const coded = stageOfCode(code, { needsPerson: need, planning: s(row, 'live_role') === 'planner', operatorHold: s(row, 'hold_kind') === 'operator' });
+    const reading = process !== null
+        ? 'wait' in process ? { stage: 'waiting', wait: process.wait } : { stage: 'needs-you', need: process.need }
+        : custody ? { stage: 'needs-you', need: 'confirm-stopped' }
+            : coded.stage === 'needs-you' && (coded.need === undefined || coded.need === 'other') && INDEX_NEED[code] !== undefined ? { stage: 'needs-you', need: INDEX_NEED[code] } : coded;
     const checkStatus = s(row, 'check_status'), verdict = s(row, 'proof_verdict');
     const finished = reading.stage === 'finished' || reading.stage === 'complete';
     const own = checkStatus === 'failed' || n(row, 'proof_failed_check') === 1 ? 'failed' : checkStatus === 'passed' || verdict === 'verified' ? 'passed' : null;
-    const shared = taskStatusOf({ stage: reading.stage, ...(reading.need === undefined ? {} : { need: reading.need }),
+    const shared = taskStatusOf({ stage: reading.stage, ...(reading.need === undefined ? {} : { need: reading.need }), ...(reading.wait === undefined ? {} : { wait: reading.wait }),
+        ...(process === null ? {} : { needContext: { build: process.build } }),
         reason: finished ? null : plainReasonOf(reading.stage, code, detail || null), report: s(row, 'result_role') === 'scout',
         checks: !finished ? null : listChecksOf(own, s(row, 'check_level'), row['check_follows']),
         completedBy: code !== 'complete' ? null : n(row, 'completed_by_lead') === 1 ? 'the lead' : String(row['checked_actor']).replace(/^(?:operator|coordinator|lead):/, '') });
     label = shared.headline;
     detail = shared.sentence;
+    // Every Needs you action wears its need's own words.
+    if (shared.need != null && shared.need.key !== 'other' && shared.need.key !== 'review-result' && primaryAction !== null) {
+        actionLabel = shared.need.action.label;
+        primaryAction.label = actionLabel;
+    }
     const views = ['all'];
     if (need)
         views.push('needs-you');