toolroll 0.9.7 → 0.9.9

package/dist/review-switch.js

@@ -0,0 +1,88 @@
+export const REVIEW_SCHEMA = `
+-- A project's explicit review switch. No row: on while the project is under a hands-off mode, off otherwise.
+CREATE TABLE IF NOT EXISTS review_switch (
+  repo        TEXT PRIMARY KEY,
+  enabled     INTEGER NOT NULL CHECK (enabled IN (0, 1)),
+  changed_by  TEXT NOT NULL,
+  changed_at  TEXT NOT NULL
+);
+-- One row per reviewed build run: pending until its one reviewer run settles it.
+CREATE TABLE IF NOT EXISTS build_review (
+  run           INTEGER PRIMARY KEY,
+  task_id       TEXT NOT NULL,
+  repo          TEXT NOT NULL,
+  state         TEXT NOT NULL CHECK (state IN ('pending', 'reviewed', 'not-reviewed')),
+  request       INTEGER,
+  reviewer_run  INTEGER,
+  findings_json TEXT,
+  reason        TEXT,
+  sent_back_as  TEXT,
+  queued_at     TEXT NOT NULL,
+  finished_at   TEXT
+);
+CREATE INDEX IF NOT EXISTS build_review_pending ON build_review (repo) WHERE state = 'pending';
+CREATE INDEX IF NOT EXISTS build_review_sent_back ON build_review (sent_back_as) WHERE sent_back_as IS NOT NULL;
+`;
+/** How the policy log words a switch state. */
+export function reviewSwitchWords(state) {
+    return state.source === "project" ? (state.on ? "on" : "off") : state.on ? "on (hands-off default)" : "off (default)";
+}
+export function buildReviewOf(store, runId) {
+    let row;
+    // A deploy reads this with the candidate's code over the INSTALLED runtime's file, before this version's migration
+    // made the table: no table reads as no review.
+    try {
+        row = store.handle.prepare("SELECT * FROM build_review WHERE run = ?").get(runId);
+    }
+    catch (error) {
+        if (/no such table: build_review/.test(String(error)))
+            return null;
+        throw error;
+    }
+    if (row === undefined)
+        return null;
+    // The row was validated when it was written (parseBuildFindings).
+    let findings = [];
+    try {
+        const saved = row["findings_json"] === null ? null : JSON.parse(String(row["findings_json"]));
+        if (Array.isArray(saved?.findings))
+            findings = saved.findings;
+    }
+    catch { /* An unreadable saved row shows no findings; its state stays. */ }
+    return {
+        run: runId,
+        state: String(row["state"]),
+        reviewerRun: row["reviewer_run"] === null ? null : Number(row["reviewer_run"]),
+        reason: row["reason"] === null ? null : String(row["reason"]),
+        high: findings.filter(one => one.severity === "HIGH"),
+        followUps: findings.filter(one => one.severity !== "HIGH"),
+        sentBackAs: row["sent_back_as"] === null ? null : String(row["sent_back_as"]),
+        finishedAt: row["finished_at"] === null ? null : String(row["finished_at"]),
+    };
+}
+export const findingWords = (finding) => `${finding.severity} ${finding.file}:${finding.line} — ${finding.scenario}`;
+/** The review's standing in one line, or null while nothing was asked. */
+export function buildReviewHeadline(view) {
+    if (view === null)
+        return null;
+    if (view.state === "pending")
+        return "Reviewing — an automatic review is reading this result.";
+    if (view.state === "not-reviewed")
+        return `Not reviewed${view.reason === null ? "." : `: ${view.reason}`}`;
+    if (view.sentBackAs !== null)
+        return `Sent back as ${view.sentBackAs}: ${view.high.length} high finding${view.high.length === 1 ? "" : "s"}.`;
+    if (view.high.length > 0)
+        return `Reviewed: ${view.high.length} high finding${view.high.length === 1 ? "" : "s"} for you to decide.`;
+    return `Reviewed: no high findings${view.followUps.length === 0 ? "." : `; ${view.followUps.length} suggested follow-up${view.followUps.length === 1 ? "" : "s"}.`}`;
+}
+/** Plain lines for `task show` and `assignment show`. */
+export function buildReviewLines(view) {
+    const headline = buildReviewHeadline(view);
+    if (view === null || headline === null)
+        return [];
+    return [
+        `  review: ${headline}`,
+        ...view.high.map(one => `    ${findingWords(one)}`),
+        ...view.followUps.map(one => `    suggested follow-up: ${findingWords(one)}`),
+    ];
+}

package/dist/reviewer.d.ts

@@ -1,6 +1,8 @@
-/** Pure parser for retained historical review payloads. Model-review execution
- * is retired; this module cannot launch providers, create runs or retry work. */
+/** Pure parsers for review payloads: retained historical reviews, and the one
+ * automatic build review's findings (build-review.ts runs it). This module
+ * cannot launch providers, create runs or retry work. */
 import type { CriterionJudgementWord } from "./proof.js";
+import type { BuildFinding } from "./review-switch.js";
 /** The files the pass writes INTO the scratch directory for the agent —
  * the patch always; the rubric, re-serialized proof, check log, and
  * screenshots only when this run actually has one (v40) — a grandfathered
@@ -95,3 +97,23 @@ export declare function parseReview(raw: string, patchPaths: ReadonlySet<string>
     ok: false;
     problems: ReviewProblem[];
 };
+export type { BuildFinding, FindingSeverity } from "./review-switch.js";
+export declare const FINDING_LIMITS: {
+    readonly findings: 40;
+    readonly file: 300;
+    readonly scenario: 500;
+};
+/**
+ * The automatic build review's reply, strict and wholesale like parseReview:
+ * `{"version":1,"findings":[{"severity","file","line","scenario"}]}`. Any
+ * invalid finding refuses the whole reply — a review that did not answer
+ * what it was asked is "not reviewed", never a partial pass. Text is kept
+ * to one line so it can travel in a revision note and a terminal.
+ */
+export declare function parseBuildFindings(raw: string): {
+    ok: true;
+    findings: BuildFinding[];
+} | {
+    ok: false;
+    problem: string;
+};

package/dist/reviewer.js

@@ -1,5 +1,5 @@
 import { citesSuppliedProvenance } from "./review-context.js";
-import { REVIEW_OUTPUT_LIMITS } from "./structured-output.js";
+import { normalizeStructuredJson, REVIEW_OUTPUT_LIMITS } from "./structured-output.js";
 /** The files the pass writes INTO the scratch directory for the agent —
  * the patch always; the rubric, re-serialized proof, check log, and
  * screenshots only when this run actually has one (v40) — a grandfathered
@@ -200,3 +200,51 @@ export function parseReview(raw, patchPaths, approvedCriteriaIds = new Set(), pr
         return { ok: false, problems };
     return { ok: true, comments, criteria, ...(payload["learning"] === undefined ? {} : { learning: payload["learning"] }), ...(payload["learningAssessment"] === undefined ? {} : { learningAssessment: payload["learningAssessment"] }) };
 }
+export const FINDING_LIMITS = { findings: 40, file: REVIEW_OUTPUT_LIMITS.path, scenario: REVIEW_OUTPUT_LIMITS.note };
+/**
+ * The automatic build review's reply, strict and wholesale like parseReview:
+ * `{"version":1,"findings":[{"severity","file","line","scenario"}]}`. Any
+ * invalid finding refuses the whole reply — a review that did not answer
+ * what it was asked is "not reviewed", never a partial pass. Text is kept
+ * to one line so it can travel in a revision note and a terminal.
+ */
+export function parseBuildFindings(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(normalizeStructuredJson(raw).text);
+    }
+    catch {
+        return { ok: false, problem: "the reply is not JSON" };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return { ok: false, problem: "the reply is not an object" };
+    const payload = parsed;
+    if (payload["version"] !== 1)
+        return { ok: false, problem: "version must be 1" };
+    const list = payload["findings"];
+    if (!Array.isArray(list))
+        return { ok: false, problem: "findings must be an array" };
+    if (list.length > FINDING_LIMITS.findings)
+        return { ok: false, problem: `at most ${FINDING_LIMITS.findings} findings` };
+    const findings = [];
+    const oneLine = (text) => text.replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]+/g, " ").replace(/\s+/g, " ").trim();
+    for (const [index, one] of list.entries()) {
+        if (one === null || typeof one !== "object" || Array.isArray(one))
+            return { ok: false, problem: `finding ${index}: not an object` };
+        const finding = one;
+        const severity = finding["severity"];
+        if (severity !== "HIGH" && severity !== "MEDIUM" && severity !== "LOW")
+            return { ok: false, problem: `finding ${index}: severity must be HIGH, MEDIUM or LOW` };
+        const file = typeof finding["file"] === "string" ? oneLine(finding["file"]) : "";
+        if (file.length === 0 || file.length > FINDING_LIMITS.file)
+            return { ok: false, problem: `finding ${index}: file must be a path of 1..${FINDING_LIMITS.file} characters` };
+        const line = finding["line"];
+        if (typeof line !== "number" || !Number.isInteger(line) || line < 1)
+            return { ok: false, problem: `finding ${index}: line must be a positive whole number` };
+        const scenario = typeof finding["scenario"] === "string" ? oneLine(finding["scenario"]) : "";
+        if (scenario.length === 0 || scenario.length > FINDING_LIMITS.scenario)
+            return { ok: false, problem: `finding ${index}: scenario must be one sentence of 1..${FINDING_LIMITS.scenario} characters` };
+        findings.push({ severity, file, line, scenario });
+    }
+    return { ok: true, findings };
+}

package/dist/run-closeout.d.ts

@@ -0,0 +1,89 @@
+import type { Store, WorktreeRow } from "./store.js";
+/** How long a process has after SIGTERM before SIGKILL. */
+export declare const STOP_GRACE_MS = 10000;
+export type ProcessRow = {
+    pid: number;
+    ppid: number;
+    pgid: number;
+    bornAt: number;
+    name: string;
+    terminal: boolean;
+};
+/** Every process now: ids, when it was born (from its age) and its program's name — never its arguments, which can
+ * carry private provider inputs. */
+export declare function processCensus(now?: number): ProcessRow[];
+/** `ps -o pid=,ppid=,pgid=,etime=,tty=,comm=` rows; etime is [[dd-]hh:]mm:ss, tty `??` or `?` for none. Unreadable rows are left out. */
+export declare function parseCensus(text: string, now: number): ProcessRow[];
+/** This process, its ancestors, pid 1 and their process groups: the live service, never stopped. */
+export declare function protectedProcesses(census: readonly ProcessRow[], self?: number): {
+    pids: Set<number>;
+    groups: Set<number>;
+};
+export type Witness = {
+    pid: number;
+    group: boolean;
+    observedAt: number;
+};
+/**
+ * What of a run is still running: each witnessed process that is still the same process (born no later than the run
+ * saw it), and every member of each witnessed group whose leader is that same process or gone. Never anything
+ * protected.
+ */
+export declare function closeoutTargets(census: readonly ProcessRow[], witnesses: readonly Witness[], guard: {
+    pids: ReadonlySet<number>;
+    groups: ReadonlySet<number>;
+}): ProcessRow[];
+export type Stopped = {
+    stopped: ProcessRow[];
+    killed: ProcessRow[];
+};
+export type StopOptions = {
+    graceMs?: number;
+    census?: () => ProcessRow[];
+    signal?: (pid: number, signal: NodeJS.Signals) => void;
+    sleep?: (ms: number) => Promise<void>;
+};
+/** SIGTERM each target, wait up to the grace for them to go, then SIGKILL what is still the same process. */
+export declare function stopProcesses(targets: readonly ProcessRow[], options?: StopOptions): Promise<Stopped>;
+/** "node (4123), serve (4130); 1 needed SIGKILL after 10 s" — for the ledger. */
+export declare function stoppedWords(done: Stopped, graceMs?: number): string;
+export type CloseoutOptions = StopOptions & {
+    repo?: string;
+    actor?: string;
+};
+/**
+ * The worker's pass: every finished run of this host that still has a process witness open is closed out. A run
+ * whose transport here still holds a live child, or whose held supervisor hasn't shut down, is left to that road.
+ * Returns what each run had stopped.
+ */
+export declare function closeOutRuns(store: Store, clock: () => Date, options?: CloseoutOptions): Promise<{
+    runId: number;
+    done: Stopped;
+}[]>;
+/** Which processes run from inside each of `paths` (their working directory is there): lsof on macOS, /proc on Linux. */
+export declare function processesIn(paths: readonly string[]): Map<string, number[]>;
+/**
+ * Of the processes running from a finished checkout (`inside`), the ones Toolroll left there: each descends from a
+ * process a finished run started (`roots`), or is an orphan (its parent is pid 1), or is the child of one that goes.
+ * Never one with a live parent Toolroll didn't start — a deploy the lead runs from the checkout, a person's agent or
+ * its tools — nor anything at a terminal or protected.
+ */
+export declare function checkoutTargets(census: readonly ProcessRow[], inside: ReadonlySet<number>, roots: ReadonlySet<number>, guard: {
+    pids: ReadonlySet<number>;
+    groups: ReadonlySet<number>;
+}): ProcessRow[];
+/**
+ * Completing or cancelling a task closes out its checkout: what Toolroll left running from it (`checkoutTargets`) is
+ * stopped (SIGTERM, then SIGKILL after the grace), in the ledger. `finished` lists the checkouts whose task is
+ * complete or cancelled, with when it finished; each is looked at once per finish.
+ */
+export declare function closeOutCheckouts(store: Store, clock: () => Date, finished: readonly {
+    row: WorktreeRow;
+    taskId: string | null;
+    finishedAt: string;
+}[], options?: CloseoutOptions & {
+    find?: typeof processesIn;
+}): Promise<{
+    path: string;
+    done: Stopped;
+}[]>;

package/dist/run-closeout.js

@@ -0,0 +1,302 @@
+/**
+ * Closing out what a run started. When a run ends, whatever its outcome, anything still running in its process
+ * groups — the provider's own group and every process or group the run was seen to start — is stopped: SIGTERM, then
+ * SIGKILL for whatever is still there after 10 s. Completing or cancelling a task does the same for what Toolroll left
+ * running from its checkout: what a finished run started (descends from one of its processes) or an orphan (its parent
+ * gone), never one with a live parent Toolroll did not start (a deploy, a person's agent or shell). Each stop is in
+ * the ledger, naming what was stopped.
+ *
+ * Never the live service: this process, its ancestors and their process groups are never targets.
+ *
+ * A pid saved in the database is never signalled on its word alone (the OS reuses pids): a target must be alive in a
+ * fresh process listing and born no later than the run saw it. A group counts when its leader is that same process,
+ * or when the leader is gone and the group still has members (the OS never hands a live group's id to a new
+ * process). The worker's pass runs this (operate.ts reconcile), so every road a run ends by is covered.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
+import { hostname } from "node:os";
+import { basename, sep } from "node:path";
+import { ownedProcessCount, runOwnerTag } from "./exec.js";
+/** How long a process has after SIGTERM before SIGKILL. */
+export const STOP_GRACE_MS = 10_000;
+/** `ps` reports age in whole seconds: a process born this close after the run saw its pid is still that process. */
+const BIRTH_SLACK_MS = 2_000;
+/** Every process now: ids, when it was born (from its age) and its program's name — never its arguments, which can
+ * carry private provider inputs. */
+export function processCensus(now = Date.now()) {
+    if (process.platform === "win32")
+        return [];
+    const text = execFileSync("/bin/ps", ["-axo", "pid=,ppid=,pgid=,etime=,tty=,comm="], { encoding: "utf8", timeout: 5_000, maxBuffer: 16 * 1024 * 1024 });
+    return parseCensus(text, now);
+}
+/** `ps -o pid=,ppid=,pgid=,etime=,tty=,comm=` rows; etime is [[dd-]hh:]mm:ss, tty `??` or `?` for none. Unreadable rows are left out. */
+export function parseCensus(text, now) {
+    const rows = [];
+    for (const line of text.split("\n")) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+        if (match === null)
+            continue;
+        const [, pid, ppid, pgid, days, hours, minutes, seconds, tty, comm] = match;
+        const age = ((Number(days ?? 0) * 24 + Number(hours ?? 0)) * 60 + Number(minutes)) * 60 + Number(seconds);
+        rows.push({ pid: Number(pid), ppid: Number(ppid), pgid: Number(pgid), bornAt: now - age * 1000, name: basename(comm.trim()) || "?", terminal: !/^(\?+|-)$/.test(tty) });
+    }
+    return rows;
+}
+/** This process, its ancestors, pid 1 and their process groups: the live service, never stopped. */
+export function protectedProcesses(census, self = process.pid) {
+    const byPid = new Map(census.map(row => [row.pid, row]));
+    const pids = new Set([1, self, process.ppid]);
+    for (let at = byPid.get(self), hops = 0; at !== undefined && hops < 64; at = byPid.get(at.ppid), hops++) {
+        pids.add(at.pid);
+        if (at.ppid <= 1)
+            break;
+    }
+    const groups = new Set();
+    for (const pid of pids) {
+        const row = byPid.get(pid);
+        if (row !== undefined)
+            groups.add(row.pgid);
+    }
+    return { pids, groups };
+}
+/**
+ * What of a run is still running: each witnessed process that is still the same process (born no later than the run
+ * saw it), and every member of each witnessed group whose leader is that same process or gone. Never anything
+ * protected.
+ */
+export function closeoutTargets(census, witnesses, guard) {
+    const byPid = new Map(census.map(row => [row.pid, row]));
+    const groups = new Set();
+    const pids = new Set();
+    for (const one of witnesses) {
+        const now = byPid.get(one.pid);
+        const same = now !== undefined && now.bornAt <= one.observedAt + BIRTH_SLACK_MS;
+        if (same)
+            pids.add(one.pid);
+        if (one.group && (same || now === undefined))
+            groups.add(one.pid);
+    }
+    return census.filter(row => (pids.has(row.pid) || groups.has(row.pgid)) && !guard.pids.has(row.pid) && !guard.groups.has(row.pgid));
+}
+/** SIGTERM each target, wait up to the grace for them to go, then SIGKILL what is still the same process. */
+export async function stopProcesses(targets, options = {}) {
+    if (targets.length === 0)
+        return { stopped: [], killed: [] };
+    const graceMs = options.graceMs ?? STOP_GRACE_MS;
+    const census = options.census ?? (() => processCensus());
+    const signal = options.signal ?? ((pid, name) => process.kill(pid, name));
+    const sleep = options.sleep ?? (ms => new Promise(done => setTimeout(done, ms)));
+    const send = (rows, name) => {
+        for (const row of rows) {
+            try {
+                signal(row.pid, name);
+            }
+            catch (error) {
+                if (error.code !== "ESRCH" && error.code !== "EPERM")
+                    throw error;
+            }
+        }
+    };
+    // Still there: the same pid, born at the same time (a reused pid is somebody else).
+    const remaining = () => {
+        let rows;
+        try {
+            rows = census();
+        }
+        catch {
+            return [...targets];
+        }
+        const alive = new Map(rows.map(row => [row.pid, row]));
+        return targets.filter(one => { const now = alive.get(one.pid); return now !== undefined && Math.abs(now.bornAt - one.bornAt) <= BIRTH_SLACK_MS; });
+    };
+    send(targets, "SIGTERM");
+    const deadline = Date.now() + graceMs;
+    let left = remaining();
+    while (left.length > 0 && Date.now() < deadline) {
+        await sleep(Math.min(250, Math.max(0, deadline - Date.now())));
+        left = remaining();
+    }
+    if (left.length > 0)
+        send(left, "SIGKILL");
+    return { stopped: [...targets], killed: left };
+}
+/** "node (4123), serve (4130); 1 needed SIGKILL after 10 s" — for the ledger. */
+export function stoppedWords(done, graceMs = STOP_GRACE_MS) {
+    const names = done.stopped.map(one => `${one.name} (${one.pid})`).join(", ");
+    const groups = new Set(done.stopped.map(one => one.pgid)).size;
+    const killed = done.killed.length === 0 ? "" : `; ${done.killed.length} needed SIGKILL after ${Number((graceMs / 1000).toFixed(1))} s`;
+    return `${done.stopped.length} process${done.stopped.length === 1 ? "" : "es"} in ${groups} group${groups === 1 ? "" : "s"}: ${names}${killed}`;
+}
+/**
+ * The worker's pass: every finished run of this host that still has a process witness open is closed out. A run
+ * whose transport here still holds a live child, or whose held supervisor hasn't shut down, is left to that road.
+ * Returns what each run had stopped.
+ */
+export async function closeOutRuns(store, clock, options = {}) {
+    if (process.platform === "win32")
+        return [];
+    const db = store.handle;
+    const runs = db.prepare(`SELECT DISTINCT p.run AS run FROM run_process p JOIN run r ON r.id = p.run JOIN task_ref t ON t.id = r.task_ref
+    WHERE p.exited_at IS NULL AND p.pid IS NOT NULL AND p.containment IS NULL AND p.container IS NULL AND p.host = ?
+      AND r.outcome IS NOT NULL${options.repo === undefined ? "" : " AND t.repo = ?"} ORDER BY p.run`)
+        .all(...[hostname(), ...(options.repo === undefined ? [] : [options.repo])]).map(row => Number(row["run"]));
+    const out = [];
+    if (runs.length === 0)
+        return out;
+    let census = null;
+    for (const runId of runs) {
+        store.recordRunProcessExits(runId, clock());
+        if (ownedProcessCount(runOwnerTag(store, runId)) > 0)
+            continue;
+        const held = store.heldSessionOf(runId);
+        if (held !== null && held.endedAt === null)
+            continue;
+        const witnesses = db.prepare(`SELECT pid, process_group, observed_at FROM run_process
+      WHERE run = ? AND exited_at IS NULL AND pid IS NOT NULL AND containment IS NULL AND container IS NULL AND host = ?`).all(runId, hostname())
+            .map(row => ({ pid: Number(row["pid"]), group: Number(row["process_group"]) === 1, observedAt: Date.parse(String(row["observed_at"])) }))
+            .filter(one => Number.isFinite(one.observedAt));
+        if (witnesses.length === 0)
+            continue;
+        try {
+            census ??= (options.census ?? (() => processCensus()))();
+        }
+        catch {
+            return out;
+        }
+        const targets = closeoutTargets(census, witnesses, protectedProcesses(census));
+        if (targets.length === 0)
+            continue;
+        const done = await stopProcesses(targets, options);
+        census = null;
+        const run = store.getRun(runId);
+        const ref = run === null ? null : store.refById(run.taskRef);
+        store.recordAction({ at: clock().toISOString(), actor: options.actor ?? "worker", repo: ref?.repo ?? null, taskId: ref?.externalId ?? null, runId,
+            action: "run processes stopped", outcome: "stopped", source: "work", detail: `run #${runId} ended (${run?.outcome ?? "?"}); stopped ${stoppedWords(done, options.graceMs)}` });
+        store.recordRunProcessExits(runId, clock());
+        out.push({ runId, done });
+    }
+    store.settleQuiescentStops(clock());
+    return out;
+}
+/** Which processes run from inside each of `paths` (their working directory is there): lsof on macOS, /proc on Linux. */
+export function processesIn(paths) {
+    const found = new Map();
+    if (paths.length === 0 || process.platform === "win32")
+        return found;
+    const roots = paths.map(path => { let real = path; try {
+        real = realpathSync(path);
+    }
+    catch { /* gone */ } return { path, real }; });
+    const note = (pid, cwd) => {
+        for (const one of roots) {
+            if ([one.path, one.real].some(root => cwd === root || cwd.startsWith(root + sep)))
+                found.set(one.path, [...(found.get(one.path) ?? []), pid]);
+        }
+    };
+    if (process.platform === "linux" && existsSync("/proc")) {
+        for (const name of readdirSync("/proc")) {
+            if (!/^\d+$/.test(name))
+                continue;
+            try {
+                note(Number(name), readlinkSync(`/proc/${name}/cwd`));
+            }
+            catch { /* gone, or not ours */ }
+        }
+        return found;
+    }
+    let text = "";
+    try {
+        text = execFileSync("lsof", ["-nP", "-d", "cwd", "-Fpn"], { encoding: "utf8", timeout: 20_000, maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch (error) {
+        text = String(error.stdout ?? "");
+    }
+    let pid = 0;
+    for (const line of text.split("\n")) {
+        if (line.startsWith("p"))
+            pid = Number(line.slice(1));
+        else if (line.startsWith("n") && pid > 0)
+            note(pid, line.slice(1));
+    }
+    return found;
+}
+/**
+ * Of the processes running from a finished checkout (`inside`), the ones Toolroll left there: each descends from a
+ * process a finished run started (`roots`), or is an orphan (its parent is pid 1), or is the child of one that goes.
+ * Never one with a live parent Toolroll didn't start — a deploy the lead runs from the checkout, a person's agent or
+ * its tools — nor anything at a terminal or protected.
+ */
+export function checkoutTargets(census, inside, roots, guard) {
+    const byPid = new Map(census.map(row => [row.pid, row]));
+    const fromRun = (row) => {
+        for (let at = row, hops = 0; at !== undefined && at.pid > 1 && hops < 64; at = byPid.get(at.ppid), hops++) {
+            if (roots.has(at.pid))
+                return true;
+        }
+        return false;
+    };
+    const verdict = new Map();
+    const left = (row) => {
+        const known = verdict.get(row.pid);
+        if (known !== undefined)
+            return known;
+        verdict.set(row.pid, false);
+        const parent = byPid.get(row.ppid);
+        const ours = inside.has(row.pid) && !row.terminal && !guard.pids.has(row.pid) && !guard.groups.has(row.pgid)
+            && (row.ppid === 1 || fromRun(row) || (parent !== undefined && left(parent)));
+        verdict.set(row.pid, ours);
+        return ours;
+    };
+    return census.filter(left);
+}
+/** The processes finished runs on this host started that are still the same process: what a leftover may descend from. */
+function finishedRunProcesses(store, census) {
+    const byPid = new Map(census.map(row => [row.pid, row]));
+    const roots = new Set();
+    const rows = store.handle.prepare(`SELECT p.pid AS pid, p.observed_at AS observed_at FROM run_process p JOIN run r ON r.id = p.run
+    WHERE p.exited_at IS NULL AND p.pid IS NOT NULL AND p.host = ? AND r.outcome IS NOT NULL`).all(hostname());
+    for (const row of rows) {
+        const now = byPid.get(Number(row["pid"]));
+        const observedAt = Date.parse(String(row["observed_at"]));
+        if (now !== undefined && Number.isFinite(observedAt) && now.bornAt <= observedAt + BIRTH_SLACK_MS)
+            roots.add(now.pid);
+    }
+    return roots;
+}
+/** Checkouts this process already closed out since their task finished (path and when). */
+const closed = new Set();
+/**
+ * Completing or cancelling a task closes out its checkout: what Toolroll left running from it (`checkoutTargets`) is
+ * stopped (SIGTERM, then SIGKILL after the grace), in the ledger. `finished` lists the checkouts whose task is
+ * complete or cancelled, with when it finished; each is looked at once per finish.
+ */
+export async function closeOutCheckouts(store, clock, finished, options = {}) {
+    const fresh = finished.filter(one => !closed.has(`${one.row.path}\u0000${one.finishedAt}`) && existsSync(one.row.path) && one.row.runner === null);
+    const out = [];
+    if (fresh.length === 0 || process.platform === "win32")
+        return out;
+    const inside = (options.find ?? processesIn)(fresh.map(one => one.row.path));
+    let census = null;
+    for (const one of fresh) {
+        closed.add(`${one.row.path}\u0000${one.finishedAt}`);
+        const pids = new Set(inside.get(one.row.path) ?? []);
+        if (pids.size === 0)
+            continue;
+        try {
+            census ??= (options.census ?? (() => processCensus()))();
+        }
+        catch {
+            return out;
+        }
+        const targets = checkoutTargets(census, pids, finishedRunProcesses(store, census), protectedProcesses(census));
+        if (targets.length === 0)
+            continue;
+        const done = await stopProcesses(targets, options);
+        census = null;
+        store.recordAction({ at: clock().toISOString(), actor: options.actor ?? "worker", repo: one.row.repo, taskId: one.taskId, runId: null,
+            action: "checkout processes stopped", outcome: "stopped", source: "work", detail: `${basename(one.row.path)}: its task finished; stopped ${stoppedWords(done, options.graceMs)}` });
+        out.push({ path: one.row.path, done });
+    }
+    return out;
+}

package/dist/serve.d.ts

@@ -1,10 +1,11 @@
-import { type BrowserWorkspace, type BrowserSignIn, type BrowserUpdateNotice } from './browser-workspace.js';
+import { type BrowserWorkspace, type BrowserNeedAction, type BrowserSignIn, type BrowserUpdateNotice } from './browser-workspace.js';
 import { CodingWorkspace } from './coding-workspace.js';
 import { type FetchLike } from "./flow-share.js";
 import { type MailSender } from "./flow-actions.js";
 import { type TriggerIo } from "./flow-triggers.js";
 import { type AssignmentSnapshot } from './assignment.js';
 import type { PublishExec } from './publish.js';
+import { type TaskStatus } from './task-status.js';
 import { type VersionRunner } from "./model-catalog.js";
 import { type Server } from "node:http";
 import { type ProofVerdict, type CriterionMatrixRow } from "./proof.js";
@@ -266,6 +267,10 @@ type Chrome = {
     signIn?: BrowserSignIn[];
     /** A newer Toolroll: a quiet notice for an operator until they dismiss this version. */
     update?: BrowserUpdateNotice;
+    /** An update waiting on something, what, and the action that clears it: every page, for an operator. */
+    updateWaiting?: {
+        words: string;
+    };
     /** The chat tab renders only where chat could ever be allowed. */
     chat?: boolean;
     code?: boolean;
@@ -541,6 +546,15 @@ export declare function orderChangedFiles(files: readonly ReviewFileRow[], proof
 /** Older machine-checked results saved a mechanical sentence; say the same
  * facts in plain words (the version id stays, shortened). */
 export declare function plainConclusionOf(conclusion: string): string;
+/** A Needs you result's one action (needs-you.ts): a link to the act that resolves it, or Confirm it
+ * stopped behind the password. Null under every other headline. */
+export declare function needActionOf(assignment: AssignmentSnapshot | null, status: TaskStatus | null, csrf: string, returnTo: string, result?: {
+    accepted: boolean;
+    humanReview: boolean;
+    run: number;
+    action: string;
+    rebuildable?: boolean;
+}): BrowserNeedAction | null;
 /** The facts region alone, for the open-run poll (A4). A finished run's
  * fragment says so instead of quietly growing forms (finding 5), and a run
  * that stopped being the task's live claim says so too — both carry the