toolroll 0.9.8 → 0.9.10

package/dist/store.js

@@ -139,7 +139,8 @@ CREATE TABLE IF NOT EXISTS monitoring_status (
  * every step, and an optional evening digest at a local HH:MM. `digest_on` is the local day the last evening
  * digest was considered, so each day is judged once. A task's card is the one chat message a destination keeps
  * for it (or for several tasks filed within a minute): `message` is the Telegram message id or the chat app's
- * part id, `digest` the text last shown, so an unchanged card is never re-sent. */
+ * part id, `digest` the text last shown, so an unchanged card is never re-sent. A `chat_batch` is one person's
+ * finished-work message: every result that lands within two minutes of its first joins it, edited in place. */
 const QUIET_CHAT_SCHEMA = `
 CREATE TABLE IF NOT EXISTS notification_preference (
   account    TEXT PRIMARY KEY,
@@ -166,6 +167,21 @@ CREATE TABLE IF NOT EXISTS chat_card_task (
   PRIMARY KEY (destination, task_ref)
 );
 CREATE INDEX IF NOT EXISTS chat_card_task_card ON chat_card_task(card);
+CREATE TABLE IF NOT EXISTS chat_batch (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  destination TEXT NOT NULL,
+  opened_at   TEXT NOT NULL,
+  message     TEXT,
+  digest      TEXT
+);
+CREATE INDEX IF NOT EXISTS chat_batch_destination ON chat_batch(destination, opened_at);
+CREATE TABLE IF NOT EXISTS chat_batch_item (
+  batch     INTEGER NOT NULL REFERENCES chat_batch(id),
+  task_ref  INTEGER NOT NULL,
+  run       INTEGER,
+  joined_at TEXT NOT NULL,
+  PRIMARY KEY (batch, task_ref)
+);
 `;
 /** Pings follow responsibility (no version bump: additive only). `lead_credential` is a lead token: an agent acting
  * for `owner`, only its hash kept. `task_act` is who filed, approved, cancelled, completed or handed on a task
@@ -215,6 +231,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. */
@@ -3812,6 +3842,8 @@ function initializeStore(db, file) {
     db.exec(POLICY_SCHEMA);
     db.exec(RUN_CHECK_SCHEMA);
     db.exec(QUIET_CHAT_SCHEMA);
+    // The update a batch line speaks for: its newest fact about that task (null: a finished result).
+    addColumn(db, "chat_batch_item", "notification", "INTEGER");
     db.exec(LEAD_QUIET_SCHEMA);
     mergeCheckTables(db);
     addColumn(db, "monitoring_status", "target", "TEXT");
@@ -10007,6 +10039,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 +12757,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 +12811,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") {
@@ -15065,6 +15110,10 @@ export class Store {
             .run(now.toISOString(), head.length, head);
         return Number(changes);
     }
+    notificationById(id) {
+        const row = this.db.prepare("SELECT * FROM notification WHERE id = ?").get(id);
+        return row === undefined ? null : readNotification(row);
+    }
     notificationsAfter(id, limit = 100) {
         return this.db.prepare("SELECT * FROM notification WHERE id>? ORDER BY id LIMIT ?").all(id, Math.max(1, Math.min(100, limit))).map(readNotification);
     }
@@ -20981,21 +21030,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 +21069,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 +21082,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 +21126,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 +21143,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 +21154,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 +21267,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);
@@ -22101,6 +22219,7 @@ export class Store {
      * and the evening digest keep every fact either way.
      */
     pingAllowed(row, account) {
+        // A security alert always pings, ahead of every rule below: own acts, settled, replaced or release-check tasks.
         if (SECURITY_KINDS.has(row.kind) || row.kind === "evening-digest")
             return true;
         if (row.recipient !== null && row.kind === "task-ask")
@@ -22110,10 +22229,42 @@ export class Store {
             return false;
         if (row.recipient !== null)
             return true;
+        // A task this person (or their lead) completed or cancelled is settled for them: nothing more about it.
+        // Release checks and replaced or superseded tasks never ping anyone; a deploy says "is live" instead.
+        if (row.taskRef !== null && (this.settledBy(row.taskRef) === account || this.neverPings(row.taskRef)))
+            return false;
         if (this.leadQuiet(row, actor))
             return false;
         return row.project === null || this.db.prepare("SELECT 1 AS hit FROM project_mute WHERE account = ? AND repo = ?").get(account, row.project) === undefined;
     }
+    /** Who last completed or cancelled this task, when that is still its latest act: null otherwise. A revision's
+     * completion is recorded on its root, so an act on a task it revises counts too, but only one made after this
+     * revision was filed: settling older work never silences a newer revision, whose failures still reach people. */
+    settledBy(taskRef) {
+        const ancestors = [];
+        for (let at = 0, from = taskRef; at < 20; at++) {
+            const parent = this.db.prepare(`SELECT p.id FROM task_ref c JOIN task_ref p ON p.backend = c.backend AND p.external_id = c.revision_of AND p.repo IS c.repo
+        WHERE c.id = ?`).get(from);
+            if (parent === undefined || from === Number(parent["id"]) || ancestors.includes(Number(parent["id"])))
+                break;
+            from = Number(parent["id"]);
+            ancestors.push(from);
+        }
+        const filed = this.db.prepare("SELECT t.created_at FROM task_ref r JOIN task t ON t.id = r.external_id AND r.backend = ? WHERE r.id = ?").get(BUILT_IN, taskRef);
+        const since = filed === undefined || ancestors.length === 0 ? null : String(filed["created_at"]);
+        const last = since === null
+            ? this.db.prepare("SELECT act, account FROM task_act WHERE task_ref = ? ORDER BY id DESC LIMIT 1").get(taskRef)
+            : this.db.prepare(`SELECT act, account FROM task_act WHERE task_ref = ? OR (task_ref IN (${ancestors.map(() => "?").join(", ")}) AND at >= ?)
+          ORDER BY id DESC LIMIT 1`).get(taskRef, ...ancestors, since);
+        return last !== undefined && (last["act"] === "completed" || last["act"] === "cancelled") ? String(last["account"]) : null;
+    }
+    /** A release check, a replaced task, or one a revision superseded: its facts stay in the console. */
+    neverPings(taskRef) {
+        return this.db.prepare(`SELECT 1 AS hit FROM task_ref r WHERE r.id = ? AND (
+        EXISTS (SELECT 1 FROM run JOIN run_check rc ON rc.run = run.id WHERE run.task_ref = r.id AND rc.release = 1)
+        OR EXISTS (SELECT 1 FROM task_replacement x WHERE x.task_ref = r.id)
+        OR EXISTS (SELECT 1 FROM task_ref c WHERE c.backend = r.backend AND c.revision_of = r.external_id AND c.repo IS r.repo))`).get(taskRef) !== undefined;
+    }
     /** The lead's work, which messages nobody: unless it is a security alert or a failure with nothing left for the lead. */
     leadQuiet(row, actor = this.notificationActor(row.id)) {
         if (SECURITY_KINDS.has(row.kind))
@@ -22166,6 +22317,32 @@ export class Store {
         return this.db.prepare("SELECT * FROM notification WHERE created_at >= ? AND task_ref IS NOT NULL AND project IS NOT NULL ORDER BY id DESC LIMIT ?")
             .all(since, limit).map(readNotification).reverse();
     }
+    /** The one message this update joins: the destination's batch opened within `windowMs`, or a new one. A task
+     * has one line in it, saying its newest update (`notification`; null for a finished result). */
+    chatBatchFor(destination, taskRef, run, now, windowMs, notification = null) {
+        return this.transact(() => {
+            const open = this.db.prepare("SELECT id FROM chat_batch WHERE destination = ? AND opened_at > ? AND opened_at <= ? ORDER BY id DESC LIMIT 1")
+                .get(destination, new Date(now.getTime() - windowMs).toISOString(), now.toISOString());
+            const batch = open !== undefined ? Number(open["id"])
+                : Number(this.db.prepare("INSERT INTO chat_batch (destination, opened_at) VALUES (?, ?)").run(destination, now.toISOString()).lastInsertRowid);
+            this.db.prepare(`INSERT INTO chat_batch_item (batch, task_ref, run, joined_at, notification) VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT (batch, task_ref) DO UPDATE SET run = excluded.run, notification = excluded.notification`).run(batch, taskRef, run, now.toISOString(), notification);
+            return this.chatBatch(batch);
+        });
+    }
+    chatBatch(id) {
+        const row = this.db.prepare("SELECT * FROM chat_batch WHERE id = ?").get(id);
+        if (row === undefined)
+            return null;
+        const items = this.db.prepare("SELECT task_ref, run, notification FROM chat_batch_item WHERE batch = ? ORDER BY joined_at, task_ref").all(id)
+            .map(one => ({ taskRef: Number(one["task_ref"]), run: one["run"] == null ? null : Number(one["run"]),
+            notification: one["notification"] == null ? null : Number(one["notification"]) }));
+        return { id, destination: String(row["destination"]), openedAt: String(row["opened_at"]), message: row["message"] == null ? null : String(row["message"]),
+            digest: row["digest"] == null ? null : String(row["digest"]), items };
+    }
+    setChatBatchMessage(id, message, digest) {
+        this.db.prepare("UPDATE chat_batch SET message = ?, digest = ? WHERE id = ?").run(message, digest, id);
+    }
     /** The message now showing this card, and what it shows. */
     setChatCardMessage(id, message, digest) {
         this.db.prepare("UPDATE chat_card SET message = ?, digest = ? WHERE id = ?").run(message, digest, id);

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/teams-chat.js

@@ -195,7 +195,7 @@ export async function deliverTeamsPart(options) {
             const flow = content.flow ? chatFlowButtons(state, row.id, now).map(one => ({ type: "Action.Submit", title: one.label, data: { so: one.token }, ...(one.action === "approve" ? { style: "positive" } : {}) })) : [];
             // A teammate's question (v93): its options, then "Answer in words".
             const asked = content.question ? chatQuestionButtons(state, row.id, now).map(one => ({ type: "Action.Submit", title: one.label.slice(0, 80), data: { so: one.token } })) : [];
-            actions = [...flow, ...asked, ...openUrlAction(options.origin(), content.link)];
+            actions = [...flow, ...asked, ...openUrlAction(options.origin(), content.link), ...(content.also ?? []).flatMap(one => openUrlAction(options.origin(), one))];
         }
         const target = content.edit ?? row.message;
         const body = actions.length || content.proposal ? teamsCard(text, actions) : { type: "message", text, textFormat: "plain" };