toolroll 0.9.7 → 0.9.9

package/dist/store.js

@@ -67,8 +67,9 @@ import { PLAN_AUTO_SCHEMA } from "./plan-auto.js";
 import { RECIPE_SCHEMA } from "./recipes.js";
 import { POLICY_SCHEMA, agentRefusal, approvalRefusal, attendedRefusal, policyParts, readPolicy, underCeiling, sessionCeilingRefusal } from "./policy.js";
 import { PROVIDER_AUTH_SCHEMA } from "./provider-auth.js";
+import { REVIEW_SCHEMA, reviewSwitchWords } from "./review-switch.js";
 import { SPEND_SCHEMA, billingOf, budgetStates, canPrice, claudeMachineBilling, countsToward, filersOf, monthOf, priceWork, seenBilling as seenBillingOf, spendItems, teammateFilers, usd } from "./spend.js";
-import { FOREVER, RETENTION_SCHEMA, periodWords } from "./retention.js";
+import { DEFAULT_PERIODS, RETENTION_SCHEMA, periodWords, widenRetentionSchema } from "./retention.js";
 import { CHECKOUT_CLEANUP_SCHEMA, DEFAULT_CLEANUP, cleanupWords } from "./storage.js";
 import { IN_RANGE, LEDGER_CHAIN_SCHEMA, safeWhole, sealLedger, verifyLedgerChain } from "./ledger-chain.js";
 import { NO_RULES, filerFor, isProtectedWork, protectedChanges, rulesWords } from "./approval-policy.js";
@@ -214,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. */
@@ -3801,7 +3816,10 @@ function initializeStore(db, file) {
     db.exec(PROVIDER_AUTH_SCHEMA);
     // The sign-in pause the dispatch gate last left this task waiting on (null: none), for the work index.
     addColumn(db, "task_ref", "auth_wait_pause", "INTEGER REFERENCES provider_auth_pause(id)");
+    db.exec(REVIEW_SCHEMA);
     db.exec(RETENTION_SCHEMA);
+    // 1-day evidence: an older file's retention_setting only allowed 7 days or more (no version bump: its rows carry over).
+    widenRetentionSchema(db);
     db.exec(CHECKOUT_CLEANUP_SCHEMA);
     db.exec(BACKUP_SCHEMA);
     // Sprint 8: the organisation policy (one row, or none: nothing restricted).
@@ -9333,6 +9351,27 @@ export class Store {
             return;
         this.recordAction({ at: now.toISOString(), actor: by, repo, taskId: null, runId: null, action, outcome, source: "policy", detail: `${before} → ${after}` });
     }
+    /** The project's automatic review switch: its explicit setting, else on
+     * while a hands-off mode is active on it, else off. */
+    reviewSwitch(repo, now) {
+        const row = this.db.prepare("SELECT enabled, changed_by, changed_at FROM review_switch WHERE repo = ?").get(repo);
+        if (row !== undefined)
+            return { on: Number(row["enabled"]) === 1, source: "project", changedBy: String(row["changed_by"]), changedAt: String(row["changed_at"]) };
+        const handsOff = this.activeMode(repo, now)?.name === "hands-off";
+        return { on: handsOff, source: handsOff ? "hands-off" : "default", changedBy: null, changedAt: null };
+    }
+    /** Turn a project's automatic review on or off; the policy log keeps before → after. */
+    setReviewSwitch(repo, on, by, now) {
+        return this.transact(() => {
+            const before = this.reviewSwitch(repo, now);
+            this.db.prepare(`INSERT INTO review_switch (repo, enabled, changed_by, changed_at) VALUES (?, ?, ?, ?)
+        ON CONFLICT(repo) DO UPDATE SET enabled = excluded.enabled, changed_by = excluded.changed_by, changed_at = excluded.changed_at`)
+                .run(repo, on ? 1 : 0, by, now.toISOString());
+            const after = this.reviewSwitch(repo, now);
+            this.recordPolicy(by, repo, "automatic review", reviewSwitchWords(before), reviewSwitchWords(after), now);
+            return { before, after };
+        });
+    }
     /** A project deleted (project-delete.ts): who, and what it held → how it went. Returns the entry's id. */
     recordProjectDeleted(by, repo, held, how, now) {
         this.recordPolicy(by, repo, "project deleted", held, how, now, "deleted");
@@ -9982,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
@@ -12696,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
@@ -12734,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") {
@@ -16353,13 +16405,17 @@ export class Store {
         });
     }
     // ---- Retention (v105) -----------------------------------------------------
-    /** How long each kind of data is kept; null is forever (every kind, until someone chooses). */
+    /** How long each kind of data is kept; null is forever. A kind nobody chose keeps its default (evidence 28 days, the rest forever). */
     retentionPeriods() {
-        const periods = { ...FOREVER };
+        return { ...DEFAULT_PERIODS, ...this.retentionChosen() };
+    }
+    /** The periods someone chose: only kinds with a saved row. */
+    retentionChosen() {
+        const chosen = {};
         for (const row of this.db.prepare("SELECT kind, days FROM retention_setting").all()) {
-            periods[String(row["kind"])] = row["days"] === null ? null : Number(row["days"]);
+            chosen[String(row["kind"])] = row["days"] === null ? null : Number(row["days"]);
         }
-        return periods;
+        return chosen;
     }
     /** Set how long one kind is kept (null: forever); the ledger keeps before → after. */
     setRetentionPeriod(kind, days, by, now) {
@@ -20952,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)
@@ -20980,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
@@ -20993,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);
@@ -21030,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"]);
@@ -21043,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)
@@ -21056,10 +21132,161 @@ 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);
     }
+    /** The reconcile road for a pid-less witness a crash or a thrown spawn
+     * left behind: once its run has finished, no live child is tracked for it
+     * here, every other witness of the run has exited and none of the run's
+     * process groups is alive, it settles as never started, with a ledger
+     * entry. A sole pid-less witness has no group to prove gone and stays for
+     * `run settle`. Native witnesses keep their OS-only road. */
+    settleUnspawnedWitnesses(now) {
+        const candidates = 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.pid IS NULL AND p.containment IS NULL AND p.container IS NULL
+        AND p.host = ? AND r.outcome IS NOT NULL AND r.finished_at IS NOT NULL ORDER BY p.run`).all(hostname());
+        let settled = 0;
+        for (const candidate of candidates) {
+            const runId = Number(candidate["run"]);
+            this.recordRunProcessExits(runId, now);
+            settled += this.transact(() => {
+                const run = this.getRun(runId);
+                if (run === null || run.outcome === null)
+                    return 0;
+                if (ownedProcessCount(runOwnerTag(this, runId)) > 0)
+                    return 0;
+                const held = this.heldSessionOf(runId);
+                if (held !== null && held.endedAt === null)
+                    return 0;
+                const rows = this.db.prepare("SELECT * FROM run_process WHERE run = ? ORDER BY id").all(runId);
+                const pidless = rows.filter(row => row["exited_at"] === null && row["pid"] === null && row["containment"] === null && row["container"] === null && row["host"] === hostname());
+                const others = rows.filter(row => !pidless.includes(row));
+                if (pidless.length === 0 || others.length === 0)
+                    return 0;
+                if (others.some(row => row["exited_at"] === null))
+                    return 0;
+                // Exit was recorded once; the group's members are asked again now.
+                const groups = others.filter(row => row["pid"] !== null && row["host"] === hostname());
+                if (groups.length === 0 || groups.some(row => processMayBeAlive(Number(row["pid"]), row["process_group"] === 1, { observedAt: row["observed_at"], finishedAt: run.finishedAt })))
+                    return 0;
+                const ref = this.refById(run.taskRef);
+                let count = 0;
+                for (const row of pidless) {
+                    const changed = this.db.prepare(`UPDATE run_process SET exited_at = ?
+            WHERE id = ? AND run = ? AND pid IS NULL AND exited_at IS NULL AND containment IS NULL AND container IS NULL`)
+                        .run(now.toISOString(), row["id"], runId);
+                    if (Number(changed.changes) !== 1)
+                        continue;
+                    count++;
+                    this.recordAction({ at: now.toISOString(), actor: "system", repo: ref?.repo ?? null, taskId: ref?.externalId ?? null, runId,
+                        action: "process witness settled", outcome: "never started", source: "work",
+                        detail: `witness ${String(row["id"])}: no pid; the run finished, every other witness exited and none of its process groups is alive` });
+                }
+                return count;
+            });
+        }
+        return settled;
+    }
+    /** `run settle` (an approver's last resort): every witness of a finished
+     * run that cannot be proven either way is recorded settled under the
+     * approver's reason, in the ledger. Refuses while anything of the run is
+     * alive or could be checked only from another host. Never signals. */
+    settleRunWitnessesByApprover(args, now) {
+        return this.transact(() => {
+            const run = this.getRun(args.runId);
+            if (run === null)
+                return { ok: false, reason: "unknown-run", detail: `no run #${args.runId}` };
+            if (run.outcome === null)
+                return { ok: false, reason: "still-running", detail: `run #${args.runId} is still open` };
+            const alive = (detail) => ({ ok: false, reason: "alive", detail });
+            if (ownedProcessCount(runOwnerTag(this, args.runId)) > 0)
+                return alive(`run #${args.runId} still has an owned subprocess`);
+            const held = this.heldSessionOf(args.runId);
+            if (held !== null && held.endedAt === null)
+                return alive(`run #${args.runId}'s held supervisor has not finished shutdown`);
+            const rows = this.db.prepare("SELECT * FROM run_process WHERE run = ? ORDER BY id").all(args.runId);
+            const open = rows.filter(row => row["exited_at"] === null);
+            for (const row of rows) {
+                if (row["pid"] === null)
+                    continue;
+                if (row["host"] !== hostname()) {
+                    if (row["exited_at"] === null)
+                        return alive(`run #${args.runId}'s process ${String(row["pid"])} belongs to ${String(row["host"])}; settle it there`);
+                    continue;
+                }
+                if (processMayBeAlive(Number(row["pid"]), row["process_group"] === 1, { observedAt: row["observed_at"], finishedAt: run.finishedAt }))
+                    return alive(`run #${args.runId}'s process ${String(row["pid"])} is still running`);
+            }
+            for (const row of open) {
+                if (row["pid"] === null && row["host"] !== hostname())
+                    return alive(`run #${args.runId} has a witness from ${String(row["host"])}; settle it there`);
+                if (row["containment"] != null && row["container"] != null && row["container_empty_at"] == null &&
+                    containerEmptiness(String(row["containment"]), String(row["container"]), process.platform, row["container_identity"] == null ? null : String(row["container_identity"])) === "populated") {
+                    return alive(`run #${args.runId}'s ${String(row["containment"])} object ${String(row["container"])} still has members`);
+                }
+            }
+            // 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);
+            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);
+            return { ok: true, witnesses: ids, repeated: false };
+        });
+    }
     recordRunProcess(runId, pid, now, group = true, witness) {
         if (!Number.isSafeInteger(pid) || pid <= 0)
             throw new Error("a process witness needs a valid spawned PID");

package/dist/surface.js

@@ -265,12 +265,13 @@ export const COMMAND_GUIDE = [
     operator("task approve", "the yes — nothing builds without one; binds to the scope digest"),
     operator("task requeue", "exit a stall: incidents resolved, strikes cleared, queued again"),
     operator("task regate", "explicitly rerun the approved check on the last exact commit — no agent or automatic retry"),
-    operator("task review", "retired compatibility command; inspect the saved result and explicitly complete or revise it"),
+    operator("task review", "show a run's automatic review: HIGH findings, suggested follow-ups, or why it was not reviewed"),
     operator("task accept", "record an explicit acceptance with limitations; does not change checks or prove deployment"),
     operator("task repair", "inspect or approve an existing historical repair draft; use task revise for new feedback"),
     operator("task route", "which configured agents plan, build and repair this task; phase and risk changes require renewed approval"),
     operator("task reopen", "resume external work its tracker closed and has been SEEN open again"),
     operator("task stop", "stop ONE exact live attempt (--run <id>): durable before any process is signalled, answers 'stopping' until its own processes are established gone; work, branch, and evidence preserved; no strike, no retry"),
+    operator("run settle", "last resort for a finished run whose process witness can't be proven either way: records your --why in the ledger; refuses while any of the run's processes is alive"),
     operator("task resume", "resume the exact stopped attempt (--run <id>): refuses until it is quiescent, lifts only that stop's hold, approves nothing — the next pass re-proves the scope and inherits the draft with fresh proof"),
     // ---- leases (runner surface) ----
     { invocation: "claim", synopsis: "take one ready, approved task; answers with a lease", audience: "agent", agentMayInvoke: true, mutation: "keyed",
@@ -358,6 +359,9 @@ export const COMMAND_GUIDE = [
     operator("mode set", "sign a per-repository operating mode (password ceremony; standard or hands-off, always expiring)"),
     operator("publish merge", "say yes to ONE waiting merge — it fires only when CI is seen green on the exact commit you authorized"),
     operator("publish refire", "recover a merge whose issued call went silent — re-enters the full merge road, never auto-retried"),
+    operatorRead("review show", "whether a project's finished builds get one automatic review"),
+    operator("review on", "one automatic review of each finished build whose check passes; only HIGH findings send it back, once"),
+    operator("review off", "finished builds go straight to the person, unreviewed"),
     operator("mode revoke", "revoke a repository's mode — one click, every act it covered falls back to its own ceremony"),
     operator("config set", "set phase or spend configuration"),
     operator("config clear", "clear phase or spend configuration"),

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,8 +45,13 @@ export type TaskStatus = {
     details: StatusDetail[];
     primaryAction: StatusAction | null;
     why: string[];
+    need?: {
+        key: NeedKey;
+        action: NeedAction;
+    } | null;
 };
-export type TaskStage = "queued" | "planning" | "needs-you" | "building" | "checking" | "finished" | "complete" | "failed" | "stopped";
+/** `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" | "waiting" | "building" | "checking" | "reviewing" | "finished" | "complete" | "failed" | "stopped";
 export type ChecksFact = {
     status: "passed" | "failed" | "running" | "not-run" | "unavailable";
     exitCode: number | null;
@@ -65,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. */
@@ -121,12 +134,16 @@ export declare function pullRequestFactOf(publication: {
 } | null): PullRequestFact | null;
 /** 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 declare function assignmentStageOf(assignment: Pick<AssignmentSnapshot, "state" | "primaryAction">, work?: {
+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 {