toolroll 0.9.7 → 0.9.9

package/dist/task-status.js

@@ -1,9 +1,11 @@
+import { CODE_NEED, NEEDS, needSentence, waitSentence } from "./needs-you.js";
 /** A cancelled task with a successor reads "Replaced by <id>" everywhere, never "Cancelled". */
 export const replacedWords = (successor) => `Replaced by ${successor}`;
 const REPLACED = /^Replaced by \S+/;
-export const HEADLINES = ["Queued", "Planning", "Needs you", "Building", "Ready for review", "Complete", "Failed", "Stopped"];
+/** Waiting: a reason no person can act on, worded as what it waits for (needs-you.ts). */
+export const HEADLINES = ["Queued", "Planning", "Needs you", "Waiting", "Building", "Ready for review", "Complete", "Failed", "Stopped"];
 export const HEADLINE_TONE = {
-    Queued: "neutral", Planning: "live", "Needs you": "attention", Building: "live",
+    Queued: "neutral", Planning: "live", "Needs you": "attention", Waiting: "neutral", Building: "live",
     "Ready for review": "ready", Complete: "success", Failed: "danger", Stopped: "neutral",
 };
 const short = (sha) => sha !== null && /^[a-f0-9]{7,40}$/.test(sha) ? sha.slice(0, 7) : null;
@@ -12,8 +14,10 @@ export function headlineOf(facts) {
         case "queued": return "Queued";
         case "planning": return "Planning";
         case "needs-you": return "Needs you";
+        case "waiting": return "Waiting";
         case "building":
-        case "checking": return "Building";
+        case "checking":
+        case "reviewing": return "Building";
         case "finished":
             if (facts.report)
                 return "Ready for review";
@@ -32,11 +36,11 @@ function sentenceOf(headline, facts) {
     switch (headline) {
         case "Queued": return reason ?? "Waiting for a worker.";
         case "Planning": return reason ?? "The lead is writing the plan.";
-        // An approval always reads the same way; the plan itself names the work.
-        case "Needs you": return facts.need === "approval" ? "Review the plan and approve it to start." : reason ?? (facts.need === "answer" ? "Answer the question so the work can continue."
-            : facts.need === "sign-in" ? "Sign in again; the task starts on its own after."
-                : "Something needs your decision before the work can continue.");
-        case "Building": return facts.stage === "checking" ? "Checks are running on the change." : reason ?? "An agent is working on it.";
+        // One plain sentence per need (needs-you.ts); a recorded reason only where the need keeps one.
+        case "Needs you": return needSentence(facts.need ?? "other", reason, facts.needContext);
+        case "Waiting": return waitSentence(facts.wait, reason, facts.needContext);
+        case "Building": return facts.stage === "checking" ? "Checks are running on the change."
+            : facts.stage === "reviewing" ? "Reviewing the change before it reaches you." : reason ?? "An agent is working on it.";
         case "Ready for review":
             if (facts.report)
                 return "The report is ready to read. Read it, then mark it complete.";
@@ -131,8 +135,12 @@ function detailsOf(headline, facts) {
 }
 export function taskStatusOf(facts) {
     const headline = headlineOf(facts);
+    // Every Needs you carries the one action that resolves it, worded the same everywhere.
+    const need = headline === "Needs you" ? { key: facts.need ?? "other", action: NEEDS[facts.need ?? "other"].action } : null;
+    const ownWords = need !== null && (need.key === "other" || need.key === "review-result") && facts.action != null;
+    const primaryAction = need === null || ownWords ? facts.action ?? null : { label: need.action.label, href: facts.action?.href ?? null };
     return { headline, tone: HEADLINE_TONE[headline], sentence: sentenceOf(headline, facts), details: detailsOf(headline, facts),
-        primaryAction: facts.action ?? null, why: [...new Set(facts.why ?? [])].filter(one => one.trim() !== "") };
+        primaryAction, why: [...new Set(facts.why ?? [])].filter(one => one.trim() !== ""), need };
 }
 // ---- reading the existing projections ----------------------------------------
 /** Every dispatch or work-index code, as the stage it means. Unknown codes that
@@ -140,10 +148,11 @@ export function taskStatusOf(facts) {
 const CODE_STAGE = {
     queued: ["queued"], ready: ["queued"], "worker-at-capacity": ["queued"], "retry-scheduled": ["queued"], updating: ["queued"],
     "waiting-dependency": ["queued"], "scouting-ready": ["queued"], "planning-ready": ["queued"], "provider-quota": ["queued"], "planner-source": ["queued"],
-    running: ["building"], reviewing: ["building"], "review-pending": ["building"],
+    running: ["building"], reviewing: ["reviewing"], "review-pending": ["building"],
     "signed-out": ["needs-you", "sign-in"],
     "needs-approval": ["needs-you", "approval"],
     "waiting-decision": ["needs-you", "answer"], "decision-queue": ["needs-you", "answer"],
+    "build-stopping": ["waiting"], "other-computer": ["waiting"],
     stopping: ["stopped"], stopped: ["stopped"], paused: ["stopped"], cancelled: ["stopped"],
     failed: ["failed"], "waiting-incident": ["failed"], "checks-failed": ["failed"],
     "ready-to-check": ["finished"], "ready-to-review": ["finished"], "report-ready": ["finished"], "no-change": ["finished"],
@@ -154,7 +163,7 @@ const CODE_STAGE = {
  * building reason is scheduler wording, and the default sentence is plainer. */
 const QUEUED_REASONS = new Set(["worker-at-capacity", "waiting-dependency", "retry-scheduled", "updating", "planning-ready", "scouting-ready", "provider-quota"]);
 export function plainReasonOf(stage, code, detail) {
-    if (stage === "building" || stage === "checking" || stage === "planning")
+    if (stage === "building" || stage === "checking" || stage === "reviewing" || stage === "planning")
         return null;
     if (stage === "queued")
         return QUEUED_REASONS.has(code) ? detail ?? null : null;
@@ -164,11 +173,11 @@ export function stageOfCode(code, options = {}) {
     if (code === "running" && options.planning)
         return { stage: "planning" };
     if (code === "held")
-        return options.operatorHold === false ? { stage: "needs-you", need: "other" } : { stage: "stopped" };
+        return options.operatorHold === false ? { stage: "needs-you", need: "hold" } : { stage: "stopped" };
     const known = CODE_STAGE[code];
     if (known !== undefined)
         return known[1] === undefined ? { stage: known[0] } : { stage: known[0], need: known[1] };
-    return options.needsPerson === false ? { stage: "queued" } : { stage: "needs-you", need: "other" };
+    return options.needsPerson === false ? { stage: "queued" } : { stage: "needs-you", need: CODE_NEED[code] ?? "other" };
 }
 /** The pull request as the task page's follower reports it, or the bare publication row. */
 export function pullRequestFactOf(publication) {
@@ -195,11 +204,15 @@ export function pullRequestFactOf(publication) {
 /** The assignment's stage. The work status, when the caller read one, names
  * the exact reason (a running planner, a pause, a failed attempt, a sign-in). */
 export function assignmentStageOf(assignment, work, planning = false) {
+    // The assignment's own reading (a build Toolroll can't confirm stopped) comes first.
+    const own = assignment.need ?? null;
+    if (own !== null && (assignment.state === "working" || assignment.state === "needs-decision"))
+        return "wait" in own ? { stage: "waiting", wait: own.wait } : { stage: "needs-you", need: own.key };
     switch (assignment.state) {
         case "cancelled": return { stage: "stopped" };
         case "complete": return { stage: "complete" };
         case "ready-to-check": return { stage: "finished" };
-        case "checking": return { stage: "checking" };
+        case "checking": return { stage: assignment.review?.state === "pending" ? "reviewing" : "checking" };
         case "working": {
             const token = work?.token ?? "running";
             const read = stageOfCode(token, { needsPerson: work?.views?.includes("needs-you") ?? false, planning });
@@ -209,8 +222,10 @@ export function assignmentStageOf(assignment, work, planning = false) {
             const action = assignment.primaryAction?.code;
             if (action === "approve-scope")
                 return { stage: "needs-you", need: "approval" };
-            if (action === "answer-decision" || action === "inspect-decisions")
+            if (action === "answer-decision")
                 return { stage: "needs-you", need: "answer" };
+            if (action === "inspect-decisions")
+                return { stage: "needs-you", need: "questions" };
             const token = work?.token ?? "";
             // A failed attempt is Failed. A saved result that still needs a decision
             // (its scope, a hold, a process exit) is Needs you, even if its checks
@@ -218,7 +233,10 @@ export function assignmentStageOf(assignment, work, planning = false) {
             if (token === "failed" || token === "waiting-incident")
                 return { stage: "failed" };
             const read = stageOfCode(token, { needsPerson: true, operatorHold: action === "unhold" });
-            return read.stage === "stopped" ? read : { stage: "needs-you", need: read.need ?? "other" };
+            if (read.stage === "stopped" || read.stage === "waiting")
+                return read;
+            // A saved result that isn't ready keeps its own reading; a task's dispatch reason names its need.
+            return { stage: "needs-you", need: read.need ?? "other" };
         }
     }
 }
@@ -241,11 +259,12 @@ export function evidenceOf(receipt, problems = receipt?.caveats ?? []) {
 }
 /** The status facts of one assignment, as every surface reads them. */
 export function assignmentStatusFacts(assignment, options = {}) {
-    const { stage, need } = assignmentStageOf(assignment, options.work ?? null, options.planning ?? false);
+    const { stage, need, wait } = assignmentStageOf(assignment, options.work ?? null, options.planning ?? false);
+    const build = assignment.need?.build ?? null;
     const receipt = assignment.receipt;
     const finished = stage === "finished" || stage === "complete";
     // A saved result's rows show whenever it is the reason a person is needed, too.
-    const withResult = finished || stage === "failed" || (stage === "needs-you" && receipt !== null);
+    const withResult = finished || stage === "failed" || ((stage === "needs-you" || stage === "waiting") && receipt !== null);
     const report = receipt?.completionKind === "research-report";
     const checks = receipt === null || !withResult ? null
         : { status: receipt.checks.status, exitCode: receipt.checks.exitCode, head: receipt.head,
@@ -255,11 +274,11 @@ export function assignmentStatusFacts(assignment, options = {}) {
         : publication === null ? (withResult && !report ? { state: "none", number: null, url: null, ci: null, error: null } : null)
             : pullRequestFactOf(publication);
     // Ready, Complete and Failed speak for themselves; every other stage keeps its recorded reason.
-    const reason = stage === "needs-you" || stage === "stopped" || stage === "queued" || (stage === "failed" && checks?.status !== "failed")
+    const reason = stage === "needs-you" || stage === "waiting" || stage === "stopped" || stage === "queued" || (stage === "failed" && checks?.status !== "failed")
         ? stage === "stopped" && assignment.state === "cancelled" ? REPLACED.test(assignment.detail) ? assignment.detail : "Cancelled. Nothing else will run." : plainReasonOf(stage, options.work?.token ?? "", options.work?.detail ?? assignment.detail)
         : null;
     return {
-        stage, ...(need === undefined ? {} : { need }), reason, report,
+        stage, ...(need === undefined ? {} : { need }), ...(wait === undefined ? {} : { wait }), ...(build === null ? {} : { needContext: { build } }), reason, report,
         checks,
         pullRequest: withResult ? pullRequest : null,
         requirements: withResult ? requirementsOf(receipt?.proof?.matrix) : null,
@@ -290,7 +309,7 @@ export function statusDetailLines(status) {
 }
 /** The headline's emoji for chat cards (colour is never the only signal: the words follow). */
 export function headlineEmoji(headline) {
-    return { Queued: "🕓", Planning: "📝", "Needs you": "👋", Building: "⏳", "Ready for review": "✅", Complete: "✅", Failed: "❌", Stopped: "⏹" }[headline];
+    return { Queued: "🕓", Planning: "📝", "Needs you": "👋", Waiting: "⏸", Building: "⏳", "Ready for review": "✅", Complete: "✅", Failed: "❌", Stopped: "⏹" }[headline];
 }
 const escapeHtml = (value) => value.replace(/[&<>"']/g, char => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
 const ICON_PATHS = {
@@ -325,11 +344,13 @@ export const TASK_STATUS_CSS = `.status-headline{display:flex;align-items:center
  * no assignment. A done task is Complete once a person marked its result;
  * a refuted result whose project check failed is Failed. */
 export function stageOfDispatch(d, options = {}) {
-    if (d.code === "complete" || d.code.startsWith("review-") || d.code === "reviewing")
+    if (d.code === "reviewing")
+        return { stage: "reviewing" };
+    if (d.code === "complete" || d.code.startsWith("review-"))
         return { stage: options.completed ? "complete" : "finished" };
     if (d.code === "proof-refuted")
-        return /approved check failed|checks failed/i.test(d.detail ?? "") ? { stage: "failed" } : { stage: "needs-you", need: "other" };
+        return /approved check failed|checks failed/i.test(d.detail ?? "") ? { stage: "failed" } : { stage: "needs-you", need: "review-result" };
     if (d.code === "needs-verification")
-        return { stage: "needs-you", need: "other" };
+        return { stage: "needs-you", need: "review-result" };
     return stageOfCode(d.code, { needsPerson: d.condition === "waiting" && d.action !== null, planning: d.condition === "running" && d.role === "planner", operatorHold: d.action === "unhold" });
 }

package/dist/telegram-progress.js

@@ -86,6 +86,7 @@ export function telegramProgressCard(store, run, taskId, project, now = new Date
     const failedChecks = status.details.some(one => one.key === "checks" && (one.mark === "failed" || one.mark === "note"));
     const recovery = operatorHold !== undefined || accessBlocked || (!built && run.outcome !== null);
     return { text, next, entities: [{ type: "bold", offset: 0, length: title.length }, { type: "bold", offset: title.length + 1, length: heading.length }],
-        link: { label: built ? "Open result" : "Open task", path: recovery
+        // Needs you: the button names the action that resolves it.
+        link: { label: status.need != null && status.need.key !== "other" && status.need.key !== "review-result" ? status.need.action.label : built ? "Open result" : "Open task", path: recovery
                 ? chatControlHref("recovery", taskId) : built ? chatResultHref(taskId, run.id, failedChecks ? "checks" : "summary") : chatControlHref("task", taskId) } };
 }

package/dist/telegram-status.js

@@ -3,7 +3,7 @@ import { manualReviewOnly } from "./proof.js";
 /** Read-only phone views over the same dispatch and proof records as chat.
  * No provider calls, repository access, new workflow state, or inferred success. */
 import { diagnoseTaskDispatch, withDispatchDiagnoses } from "./dispatch.js";
-import { COMPLETION_ACTION } from "./result-completion.js";
+import { familyCompleted } from "./result-completion.js";
 import { plainReasonOf, stageOfDispatch, taskStatusOf } from "./task-status.js";
 import { CHAT_CONTROLS, chatControlHref, chatResultHref } from "./chat-controls.js";
 export function phoneCommand(text) {
@@ -54,8 +54,8 @@ export function projectLabel(repo) {
 }
 /** The shared headline (task-status.ts) for a dispatch diagnosis on the phone. */
 function headlineFor(store, id, d) {
-    const completed = d.code === "complete" && store.handle.prepare("SELECT 1 FROM action_ledger WHERE task_id = ? AND action = ? AND source = 'work' LIMIT 1")
-        .get(store.taskFamilyOf(id, null, true)?.root.id ?? id, COMPLETION_ACTION) !== undefined;
+    // Any version of a completed family reads Complete, as taskWaitSnapshot says.
+    const completed = d.code === "complete" && familyCompleted(store, id);
     const read = stageOfDispatch(d, { completed });
     const finished = read.stage === "finished" || read.stage === "complete" || read.stage === "failed";
     return taskStatusOf({ stage: read.stage, ...(read.need === undefined ? {} : { need: read.need }), reason: finished ? null : plainReasonOf(read.stage, d.code, d.detail),

package/dist/test-temp.d.ts

@@ -0,0 +1,19 @@
+/** Name prefixes of what tests, journeys and scripts leave in the temp folder. */
+export declare const TEST_TEMP_PREFIXES: readonly string[];
+export declare function isTestTemp(name: string): boolean;
+/** Where they collect: the temp folder (and /tmp, where some scripts write). */
+export declare function tempRoots(): string[];
+export type TempLeftover = {
+    path: string;
+    touchedAt: number;
+};
+/** Every test temp folder in `roots`, and which of them nothing has touched for a day. */
+export declare function testTempFolders(roots: readonly string[], now: Date): {
+    all: TempLeftover[];
+    stale: TempLeftover[];
+};
+/** Remove the test temp folders nothing has touched for a day; each is looked at again right before it goes. */
+export declare function removeStaleTestTemp(roots: readonly string[], now: Date): {
+    removed: string[];
+    failed: string[];
+};

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();