toolroll 0.9.7 → 0.9.8

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";
@@ -3801,7 +3802,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 +9337,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");
@@ -16353,13 +16378,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) {
@@ -21060,6 +21089,108 @@ export class Store {
         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`);
+                }
+            }
+            if (open.length === 0)
+                return { ok: true, witnesses: [], repeated: true };
+            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);
+            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

@@ -42,7 +42,8 @@ export type TaskStatus = {
     primaryAction: StatusAction | null;
     why: string[];
 };
-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" | "building" | "checking" | "reviewing" | "finished" | "complete" | "failed" | "stopped";
 export type ChecksFact = {
     status: "passed" | "failed" | "running" | "not-run" | "unavailable";
     exitCode: number | null;
@@ -121,7 +122,9 @@ 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"];
+}, work?: {
     token: string;
     views?: readonly string[];
 } | null, planning?: boolean): {

package/dist/task-status.js

@@ -13,7 +13,8 @@ export function headlineOf(facts) {
         case "planning": return "Planning";
         case "needs-you": return "Needs you";
         case "building":
-        case "checking": return "Building";
+        case "checking":
+        case "reviewing": return "Building";
         case "finished":
             if (facts.report)
                 return "Ready for review";
@@ -36,7 +37,8 @@ function sentenceOf(headline, facts) {
         case "Needs you": return facts.need === "approval" ? "Review the plan and approve it to start." : reason ?? (facts.need === "answer" ? "Answer the question so the work can continue."
             : facts.need === "sign-in" ? "Sign in again; the task starts on its own after."
                 : "Something needs your decision before the work can continue.");
-        case "Building": return facts.stage === "checking" ? "Checks are running on the change." : reason ?? "An agent is working on it.";
+        case "Building": return facts.stage === "checking" ? "Checks are running on the change."
+            : facts.stage === "reviewing" ? "Reviewing the change before it reaches you." : reason ?? "An agent is working on it.";
         case "Ready for review":
             if (facts.report)
                 return "The report is ready to read. Read it, then mark it complete.";
@@ -140,7 +142,7 @@ export function taskStatusOf(facts) {
 const CODE_STAGE = {
     queued: ["queued"], ready: ["queued"], "worker-at-capacity": ["queued"], "retry-scheduled": ["queued"], updating: ["queued"],
     "waiting-dependency": ["queued"], "scouting-ready": ["queued"], "planning-ready": ["queued"], "provider-quota": ["queued"], "planner-source": ["queued"],
-    running: ["building"], reviewing: ["building"], "review-pending": ["building"],
+    running: ["building"], reviewing: ["reviewing"], "review-pending": ["building"],
     "signed-out": ["needs-you", "sign-in"],
     "needs-approval": ["needs-you", "approval"],
     "waiting-decision": ["needs-you", "answer"], "decision-queue": ["needs-you", "answer"],
@@ -154,7 +156,7 @@ const CODE_STAGE = {
  * building reason is scheduler wording, and the default sentence is plainer. */
 const QUEUED_REASONS = new Set(["worker-at-capacity", "waiting-dependency", "retry-scheduled", "updating", "planning-ready", "scouting-ready", "provider-quota"]);
 export function plainReasonOf(stage, code, detail) {
-    if (stage === "building" || stage === "checking" || stage === "planning")
+    if (stage === "building" || stage === "checking" || stage === "reviewing" || stage === "planning")
         return null;
     if (stage === "queued")
         return QUEUED_REASONS.has(code) ? detail ?? null : null;
@@ -199,7 +201,7 @@ export function assignmentStageOf(assignment, work, planning = false) {
         case "cancelled": return { stage: "stopped" };
         case "complete": return { stage: "complete" };
         case "ready-to-check": return { stage: "finished" };
-        case "checking": return { stage: "checking" };
+        case "checking": return { stage: assignment.review?.state === "pending" ? "reviewing" : "checking" };
         case "working": {
             const token = work?.token ?? "running";
             const read = stageOfCode(token, { needsPerson: work?.views?.includes("needs-you") ?? false, planning });
@@ -325,7 +327,9 @@ export const TASK_STATUS_CSS = `.status-headline{display:flex;align-items:center
  * no assignment. A done task is Complete once a person marked its result;
  * a refuted result whose project check failed is Failed. */
 export function stageOfDispatch(d, options = {}) {
-    if (d.code === "complete" || d.code.startsWith("review-") || d.code === "reviewing")
+    if (d.code === "reviewing")
+        return { stage: "reviewing" };
+    if (d.code === "complete" || d.code.startsWith("review-"))
         return { stage: options.completed ? "complete" : "finished" };
     if (d.code === "proof-refuted")
         return /approved check failed|checks failed/i.test(d.detail ?? "") ? { stage: "failed" } : { stage: "needs-you", need: "other" };

package/dist/work-summary.js

@@ -6,6 +6,7 @@ import { resultCheckLevel } from "./result-follow-ups.js";
 import { diagnoseTaskDispatch } from "./dispatch.js";
 import { isAlive } from "./runner.js";
 import { taskControlOf } from "./task-control.js";
+import { buildReviewOf } from "./review-switch.js";
 import { reviewFactsOf, workStatusOf } from "./workspace-ui.js";
 /** Call only after admitting the task's project. Keep the question's
  * exact run and id; never substitute a family's newest attempt. Expiry
@@ -103,7 +104,7 @@ export function taskWorkSummaryOf(store, taskId, now, access) {
             review: reviewFactsOf(store.reviewRetryStateOf(result.id), name => {
                 const runner = store.getRunner(name)?.runner;
                 return runner !== undefined && isAlive(runner, now);
-            }),
+            }, buildReviewOf(store, result.id)?.state === "pending"),
             ...(result.outcome !== "no-change" ? {} : { recordComplete: (() => {
                     const kinds = new Set(store.artifactsFor(result.id).map(one => one.kind));
                     return kinds.has("handoff") && kinds.has("terminal-diff");

package/dist/workspace-ui.d.ts

@@ -68,11 +68,13 @@ export type ReviewFacts = {
     queuedOrigin?: "operator" | "automatic" | null;
     /** Whether the live attempt's reviewer worker is answering. */
     reviewerAlive: boolean;
+    /** The build's one automatic review is still pending (build-review.ts). */
+    automaticPending?: boolean;
 };
 /** The review facts from the store's bounded retry projection — the same
  * reading `diagnoseTaskDispatch` makes, so every surface starts from one
  * record. `reviewerAlive` answers for the live attempt's runner. */
-export declare function reviewFactsOf(retry: ReviewRetryState | null, reviewerAlive: (runner: string) => boolean): ReviewFacts | null;
+export declare function reviewFactsOf(retry: ReviewRetryState | null, reviewerAlive: (runner: string) => boolean, automaticPending?: boolean): ReviewFacts | null;
 /** The tokens a review in flight wears — the dispatch codes, unchanged. */
 export declare const REVIEW_TOKENS: ReadonlySet<string>;
 /**

package/dist/workspace-ui.js

@@ -30,7 +30,7 @@ export function parseWorkView(raw) {
 /** The review facts from the store's bounded retry projection — the same
  * reading `diagnoseTaskDispatch` makes, so every surface starts from one
  * record. `reviewerAlive` answers for the live attempt's runner. */
-export function reviewFactsOf(retry, reviewerAlive) {
+export function reviewFactsOf(retry, reviewerAlive, automaticPending = false) {
     if (retry === null || retry.state === "unrequested")
         return null;
     const current = retry.live ?? (retry.state === "queued" ? null : retry.latest);
@@ -45,6 +45,7 @@ export function reviewFactsOf(retry, reviewerAlive) {
         queuedBy: retry.openRequest?.requestedBy ?? null,
         queuedOrigin: retry.openRequest?.origin ?? null,
         reviewerAlive: retry.live !== null && reviewerAlive(retry.live.runner),
+        automaticPending,
     };
 }
 /** The tokens a review in flight wears — the dispatch codes, unchanged. */
@@ -59,12 +60,12 @@ const retriesLeft = (count, explicit = true) => `${count}${explicit ? " explicit
  * the v50 dispatch contract; nothing here changes the lifecycle.
  */
 export function reviewStatusOf(review) {
-    // Model review is retired (2026-09-21): nothing schedules, retries or
-    // waits for a reviewer, so a recorded review request or attempt is
-    // history and never the result's primary status. The stored verdict and
-    // the assignment's Ready/Complete state speak instead.
-    void review;
-    return null;
+    // The one automatic review (build-review.ts) holds the result only while it
+    // is queued or running. A failed review never blocks: the result reads as
+    // it would unreviewed, marked "not reviewed" by the result itself.
+    if (review === null || review.automaticPending !== true || (review.state !== "queued" && review.state !== "running"))
+        return null;
+    return { token: "reviewing", label: "Reviewing", detail: "An automatic review is reading this result before it reaches you.", tone: "live", action: { label: "Open the result", kind: "open-result" } };
 }
 const FAILED_CHECK = /^the repository's approved verification command exited (-?[0-9]+)/;
 export function evidenceProblemOf(verdict, reasons) {
@@ -123,7 +124,7 @@ export function publicationStatusOf(publication) {
  * the detail).
  */
 export function resultStatusOf(result, publication = null) {
-    return storedResultStatusOf(result, publication);
+    return (result?.role === "builder" ? reviewStatusOf(result.review ?? null) : null) ?? storedResultStatusOf(result, publication);
 }
 /** What the machine itself recorded about a result, in a clause. */
 function machineVerdictWords(result) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"