toolroll 0.9.8 → 0.9.9

package/dist/store.js

@@ -215,6 +215,20 @@ CREATE TABLE IF NOT EXISTS project_mute (
 const SECURITY_KINDS = new Set(["secret-detected", "security-release"]);
 /** A failure that leaves nothing for the lead to try: the attempts are spent. */
 const SPENT_KINDS = new Set(["attempts-exhausted", "plan-attempts-exhausted"]);
+/** Store.stopQuiescenceFact, read safely: a deploy proves completion with this code over the INSTALLED runtime's store,
+ * which may predate the method. There the older stopQuiescenceProblem decides, and its words give the kind. */
+export function stopFactOf(store, runId) {
+    if (typeof store.stopQuiescenceFact === "function")
+        return store.stopQuiescenceFact(runId);
+    const problem = store.stopQuiescenceProblem(runId);
+    if (problem === null)
+        return null;
+    const kind = /still open|does not exist/.test(problem) ? "open"
+        : /another host/.test(problem) ? "elsewhere"
+            : /may still be running|still has|held by|has not finished|still has members/.test(problem) ? "alive"
+                : /cannot be proven|could not be established|incomplete native/.test(problem) ? "unknown" : "unprovable";
+    return { run: Number(/run #(\d+)/.exec(problem)?.[1] ?? runId), kind, problem };
+}
 /** Settings → Integrations (no version bump): each integration's last check. `outcome` is ok, failed, or absent (the check found
  * nothing set up, such as no `gh` sign-in). `ok_at` and `error`/`error_at` keep the last success and the last
  * failure across checks, so a row can say both. `account` is a display name only, never a credential. */
@@ -10007,6 +10021,10 @@ export class Store {
     stampWorktreeSetup(path, digest) {
         this.db.prepare("UPDATE worktree SET setup_digest = ? WHERE path = ?").run(digest, path);
     }
+    /** The checkout no longer holds what its setup made (its dependencies were dropped): the next lease runs setup again. */
+    forgetWorktreeSetup(path) {
+        this.db.prepare("UPDATE worktree SET setup_digest = NULL WHERE path = ?").run(path);
+    }
     // ---- verify command (Priority 2) ---------------------------------------
     /**
      * Approve one repo's verification command, revoking any predecessor in
@@ -12721,6 +12739,22 @@ export class Store {
             .get(taskRef, head);
         return Number(row?.["n"] ?? 0);
     }
+    /** Why a finished result can't be built again on the same filing: it was
+     * verified, attested or accepted, or its branch was published (revised
+     * through its pull request). Null when `requeueTask` may run it again. */
+    finalResultReason(runId) {
+        const verdict = this.proofVerdictFor(runId);
+        if (verdict !== null && (verdict.verdict === "verified" || verdict.verdict === "attested"))
+            return "accepted-result";
+        if (this.proofAcceptance(runId) !== null)
+            return "accepted-result";
+        // An intent that never pushed is not a publication; a pushed or
+        // opened branch is, and is revised through its pull request.
+        const publication = this.publicationForRun(runId);
+        if (publication !== null && (publication.state === "pushed" || publication.state === "opened"))
+            return "published";
+        return null;
+    }
     requeueTask(taskId, by, now) {
         return this.transact(() => {
             const ref = this.db
@@ -12759,16 +12793,9 @@ export class Store {
                 }
                 else {
                     rejectedRun = Number(last["id"]);
-                    const verdict = this.proofVerdictFor(rejectedRun);
-                    if (verdict !== null && (verdict.verdict === "verified" || verdict.verdict === "attested"))
-                        return { ok: false, reason: "accepted-result" };
-                    if (this.proofAcceptance(rejectedRun) !== null)
-                        return { ok: false, reason: "accepted-result" };
-                    // An intent that never pushed is not a publication; a pushed or
-                    // opened branch is, and is revised through its pull request.
-                    const publication = this.publicationForRun(rejectedRun);
-                    if (publication !== null && (publication.state === "pushed" || publication.state === "opened"))
-                        return { ok: false, reason: "published" };
+                    const final = this.finalResultReason(rejectedRun);
+                    if (final !== null)
+                        return { ok: false, reason: final };
                 }
             }
             else if (incidents.length === 0 && state !== "failed") {
@@ -20981,21 +21008,32 @@ export class Store {
     /** Every owned run must have ended, and every retained local process
      * witness must be absent. Read-only probes never authorize PID kills. */
     stopQuiescenceProblem(runId) {
+        return this.stopQuiescenceFact(runId)?.problem ?? null;
+    }
+    /** The same answer as stopQuiescenceProblem, with which run it names and
+     * what kind of answer it is (needs-you.ts reads it): `alive` while
+     * something of the run may still be running, `elsewhere` when only
+     * another computer can tell, `unprovable` when nothing is known to run
+     * but its exit was never recorded, `unknown` when this computer can't
+     * check at all (both are what `run settle` resolves; only the first may
+     * be called not running). */
+    stopQuiescenceFact(runId) {
+        const fact = (run, kind, problem) => ({ run, kind, problem });
         const ids = this.ownedRunsOf(runId);
         if (ids.length === 0)
-            return `run #${runId} does not exist`;
+            return fact(runId, "open", `run #${runId} does not exist`);
         for (const id of ids) {
             const run = this.getRun(id);
             if (run.outcome === null)
-                return `run #${id} is still open`;
+                return fact(id, "open", `run #${id} is still open`);
             if (ownedProcessCount(runOwnerTag(this, id)) > 0)
-                return `run #${id} still has an owned subprocess`;
+                return fact(id, "alive", `run #${id} still has an owned subprocess`);
             const held = this.heldSessionOf(id);
             if (held !== null && held.endedAt === null)
-                return `run #${id}'s held supervisor has not finished shutdown`;
+                return fact(id, "alive", `run #${id}'s held supervisor has not finished shutdown`);
             const witnesses = this.db.prepare("SELECT * FROM run_process WHERE run = ? ORDER BY id").all(id);
             if (run.providerStartedAt !== null && witnesses.length === 0) {
-                return `run #${id} may have spawned before its process witness was recorded; exit is unproven`;
+                return fact(id, "unprovable", `run #${id} may have spawned before its process witness was recorded; exit is unproven`);
             }
             for (const witness of witnesses) {
                 if (witness["exited_at"] !== null)
@@ -21009,12 +21047,12 @@ export class Store {
                 if (provenDeadByBootChange({ host, bootId }))
                     continue;
                 if (host !== hostname())
-                    return `run #${id}'s process belongs to another host; exit is unproven here`;
+                    return fact(id, "elsewhere", `run #${id}'s process belongs to another host; exit is unproven here`);
                 const backend = witness["containment"] === null || witness["containment"] === undefined ? null : String(witness["containment"]);
                 const container = witness["container"] === null || witness["container"] === undefined ? null : String(witness["container"]);
                 if (backend !== null || container !== null) {
                     if (backend === null || container === null)
-                        return `run #${id} has incomplete native containment custody`;
+                        return fact(id, "unknown", `run #${id} has incomplete native containment custody`);
                     if (witness["container_empty_at"] !== null)
                         continue;
                     // A native witness settles ONLY on the OS's word: the object is
@@ -21022,30 +21060,37 @@ export class Store {
                     // when empty). A transport exit never proved it.
                     const state = containerEmptiness(backend, container, process.platform, witness["container_identity"] == null ? null : String(witness["container_identity"]));
                     if (state === "populated")
-                        return `run #${id}'s ${backend} object ${container} still has members`;
+                        return fact(id, "alive", `run #${id}'s ${backend} object ${container} still has members`);
                     if (state === "unknown")
-                        return `run #${id}'s ${backend} object ${container} cannot be proven empty from here`;
+                        return fact(id, "unknown", `run #${id}'s ${backend} object ${container} cannot be proven empty from here`);
                     continue;
                 }
                 if (witness["pid"] === null)
-                    return `run #${id} has an incomplete spawn witness; exit is unproven`;
+                    return fact(id, "unprovable", `run #${id} has an incomplete spawn witness; exit is unproven`);
                 const pid = Number(witness["pid"]);
                 if (processMayBeAlive(pid, witness["process_group"] === 1, { observedAt: witness["observed_at"], finishedAt: run.finishedAt }))
-                    return `run #${id}'s process ${pid} may still be running`;
+                    return fact(id, "alive", `run #${id}'s process ${pid} may still be running`);
             }
             if (run.worktree !== null) {
                 try {
                     const occupied = worktreeProcessOccupancy(run.worktree);
                     if (occupied.held)
-                        return `run #${id}'s workspace is still held by process ${occupied.by}`;
+                        return fact(id, "alive", `run #${id}'s workspace is still held by process ${occupied.by}`);
                 }
                 catch {
-                    return `run #${id}'s workspace occupancy could not be established`;
+                    // An unreadable workspace note is no proof either way; an approver's recorded word settles it.
+                    if (!this.workspaceConfirmedByApprover(id))
+                        return fact(id, "unknown", `run #${id}'s workspace occupancy could not be established`);
                 }
             }
         }
         return null;
     }
+    /** `run settle` recorded an approver's word that a run whose workspace
+     * note couldn't be read has stopped. */
+    workspaceConfirmedByApprover(runId) {
+        return this.db.prepare("SELECT 1 FROM action_ledger WHERE run_id = ? AND action = 'workspace settled by approver' LIMIT 1").get(runId) !== undefined;
+    }
     reserveRunProcess(runId, now, group = true) {
         return Number(this.db.prepare("INSERT INTO run_process (run,host,process_group,observed_at,boot_id) VALUES (?,?,?,?,?)")
             .run(runId, hostname(), group ? 1 : 0, now.toISOString(), currentBootId()).lastInsertRowid);
@@ -21059,6 +21104,10 @@ export class Store {
         const rows = only === undefined
             ? this.db.prepare("SELECT * FROM run_process WHERE run = ? AND exited_at IS NULL").all(runId)
             : this.db.prepare("SELECT * FROM run_process WHERE run = ? AND pid = ? AND process_group = ? AND exited_at IS NULL").all(runId, only.pid, only.group ? 1 : 0);
+        // A finished run's witness gets the same proof the deploy's quiescence
+        // check uses: ESRCH, or a process now holding the pid that was born after
+        // the run ended. An open run has no finish time, so only ESRCH counts.
+        const finishedAt = this.getRun(runId)?.finishedAt ?? null;
         let recorded = 0;
         for (const row of rows) {
             const host = String(row["host"]), bootId = row["boot_id"] == null ? null : String(row["boot_id"]);
@@ -21072,9 +21121,7 @@ export class Store {
                     gone = backend !== null && container !== null && (row["container_empty_at"] != null || containerEmptiness(backend, container, process.platform, row["container_identity"] == null ? null : String(row["container_identity"])) === "empty");
                 }
                 else {
-                    // Do not borrow the run's finish time or guess a legacy spawn time.
-                    // With no historical witness argument only ESRCH proves absence.
-                    gone = row["pid"] != null && !processMayBeAlive(Number(row["pid"]), row["process_group"] === 1);
+                    gone = row["pid"] != null && !processMayBeAlive(Number(row["pid"]), row["process_group"] === 1, finishedAt === null ? undefined : { observedAt: row["observed_at"], finishedAt });
                 }
             }
             if (gone)
@@ -21085,6 +21132,25 @@ export class Store {
         }
         return recorded;
     }
+    /** The reconcile road for a finished run whose process outlived its
+     * finish: once each process is provably gone, its exit is recorded, so
+     * the task stops waiting on a person by itself. A run that can't be proven
+     * yet stays open and is passed over, never holding newer runs behind it:
+     * every finished run is visited, a batch at a time. Never signals. */
+    recordFinishedRunExits(now, batch = 200) {
+        const page = this.db.prepare(`SELECT DISTINCT p.run FROM run_process p JOIN run r ON r.id = p.run
+      WHERE p.exited_at IS NULL AND p.host = ? AND p.run > ? AND r.outcome IS NOT NULL AND r.finished_at IS NOT NULL
+      ORDER BY p.run LIMIT ?`);
+        let recorded = 0;
+        for (let after = 0;;) {
+            const runs = page.all(hostname(), after, batch).map(row => Number(row["run"]));
+            for (const run of runs)
+                recorded += this.recordRunProcessExits(run, now);
+            if (runs.length < batch)
+                return recorded;
+            after = runs[runs.length - 1];
+        }
+    }
     finishUnspawnedProcess(witness, now) {
         this.db.prepare("UPDATE run_process SET exited_at = ? WHERE id = ? AND pid IS NULL AND ((containment IS NULL AND container IS NULL) OR container_empty_at IS NOT NULL)")
             .run(now.toISOString(), witness);
@@ -21179,12 +21245,42 @@ export class Store {
                     return alive(`run #${args.runId}'s ${String(row["containment"])} object ${String(row["container"])} still has members`);
                 }
             }
-            if (open.length === 0)
-                return { ok: true, witnesses: [], repeated: true };
+            // A workspace still held by a live process refuses; one whose note can't
+            // be read is settled by the approver's word, in the ledger.
+            let workspace = false;
+            if (run.worktree !== null) {
+                try {
+                    const occupied = worktreeProcessOccupancy(run.worktree);
+                    if (occupied.held)
+                        return alive(`run #${args.runId}'s workspace is still held by process ${occupied.by}`);
+                }
+                catch {
+                    workspace = !this.workspaceConfirmedByApprover(args.runId);
+                }
+            }
+            const ref = this.refById(run.taskRef);
+            if (workspace) {
+                this.recordAction({ at: now.toISOString(), actor: args.by, repo: ref?.repo ?? null, taskId: ref?.externalId ?? null, runId: args.runId,
+                    action: "workspace settled by approver", outcome: run.worktree ?? "", source: "request", detail: args.why });
+            }
+            // A run that may have spawned before any witness was written has none
+            // to settle: the approver's word is recorded as one ended witness.
+            if (rows.length === 0 && run.providerStartedAt !== null) {
+                const id = Number(this.db.prepare("INSERT INTO run_process (run,host,process_group,observed_at,boot_id,exited_at) VALUES (?,?,0,?,?,?)")
+                    .run(args.runId, hostname(), now.toISOString(), currentBootId(), now.toISOString()).lastInsertRowid);
+                this.recordAction({ at: now.toISOString(), actor: args.by, repo: ref?.repo ?? null, taskId: ref?.externalId ?? null, runId: args.runId,
+                    action: "process witness settled by approver", outcome: `witness ${id}`, source: "request", detail: args.why });
+                this.settleQuiescentStops(now);
+                return { ok: true, witnesses: [id], repeated: false };
+            }
+            if (open.length === 0) {
+                if (workspace)
+                    this.settleQuiescentStops(now);
+                return { ok: true, witnesses: [], repeated: !workspace };
+            }
             const ids = open.map(row => Number(row["id"]));
             for (const id of ids)
                 this.db.prepare("UPDATE run_process SET exited_at = ? WHERE id = ? AND run = ? AND exited_at IS NULL").run(now.toISOString(), id, args.runId);
-            const ref = this.refById(run.taskRef);
             this.recordAction({ at: now.toISOString(), actor: args.by, repo: ref?.repo ?? null, taskId: ref?.externalId ?? null, runId: args.runId,
                 action: "process witness settled by approver", outcome: `witness ${ids.join(", ")}`, source: "request", detail: args.why });
             this.settleQuiescentStops(now);

package/dist/task-status.d.ts

@@ -11,9 +11,12 @@
  * output) is an amber note on its own row with one action; the exact
  * technical reason stays one tap away in `why`. */
 import type { AssignmentSnapshot } from "./assignment.js";
+import { type NeedAction, type NeedContext, type NeedKey, type WaitKey } from "./needs-you.js";
+export type { NeedKey, WaitKey } from "./needs-you.js";
 /** A cancelled task with a successor reads "Replaced by <id>" everywhere, never "Cancelled". */
 export declare const replacedWords: (successor: string) => string;
-export declare const HEADLINES: readonly ["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 declare const HEADLINES: readonly ["Queued", "Planning", "Needs you", "Waiting", "Building", "Ready for review", "Complete", "Failed", "Stopped"];
 export type Headline = (typeof HEADLINES)[number];
 export type HeadlineTone = "neutral" | "live" | "attention" | "ready" | "success" | "danger";
 export declare const HEADLINE_TONE: Readonly<Record<Headline, HeadlineTone>>;
@@ -34,6 +37,7 @@ export type StatusDetail = {
     action: StatusAction | null;
     why: string | null;
 };
+/** `need`: what a Needs you asks for and the one action that resolves it; null under every other headline. */
 export type TaskStatus = {
     headline: Headline;
     tone: HeadlineTone;
@@ -41,9 +45,13 @@ export type TaskStatus = {
     details: StatusDetail[];
     primaryAction: StatusAction | null;
     why: string[];
+    need?: {
+        key: NeedKey;
+        action: NeedAction;
+    } | null;
 };
 /** `reviewing`: the one automatic review (build-review.ts) is reading a finished build; it reads Building, not a headline of its own. */
-export type TaskStage = "queued" | "planning" | "needs-you" | "building" | "checking" | "reviewing" | "finished" | "complete" | "failed" | "stopped";
+export type TaskStage = "queued" | "planning" | "needs-you" | "waiting" | "building" | "checking" | "reviewing" | "finished" | "complete" | "failed" | "stopped";
 export type ChecksFact = {
     status: "passed" | "failed" | "running" | "not-run" | "unavailable";
     exitCode: number | null;
@@ -66,8 +74,12 @@ export type PullRequestFact = {
 };
 export type TaskStatusFacts = {
     stage: TaskStage;
-    /** Needs you: what a person is asked for. The sentence names it. */
-    need?: "approval" | "answer" | "sign-in" | "other";
+    /** Needs you: what a person is asked for (needs-you.ts). The sentence names it. */
+    need?: NeedKey;
+    /** Waiting: what the work waits for when no person can act. */
+    wait?: WaitKey;
+    /** The build or agent a need's sentence names. */
+    needContext?: NeedContext;
     /** The recorded reason in plain words, when the stage has one. */
     reason?: string | null;
     /** A research report rather than a code change. */
@@ -124,12 +136,14 @@ export declare function pullRequestFactOf(publication: {
  * the exact reason (a running planner, a pause, a failed attempt, a sign-in). */
 export declare function assignmentStageOf(assignment: Pick<AssignmentSnapshot, "state" | "primaryAction"> & {
     review?: AssignmentSnapshot["review"];
+    need?: AssignmentSnapshot["need"];
 }, work?: {
     token: string;
     views?: readonly string[];
 } | null, planning?: boolean): {
     stage: TaskStage;
     need?: TaskStatusFacts["need"];
+    wait?: WaitKey;
 };
 /** Requirements from the stored matrix: met, the ones only a person confirms, and the total. */
 export declare function requirementsOf(matrix: readonly {

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,6 +14,7 @@ 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":
         case "reviewing": return "Building";
@@ -33,10 +36,9 @@ 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.");
+        // 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":
@@ -133,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
@@ -146,6 +152,7 @@ const CODE_STAGE = {
     "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"],
@@ -166,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) {
@@ -197,6 +204,10 @@ 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" };
@@ -211,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
@@ -220,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" };
         }
     }
 }
@@ -243,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,
@@ -257,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,
@@ -292,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 = {
@@ -332,8 +349,8 @@ export function stageOfDispatch(d, options = {}) {
     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[];
+};