toolroll 0.9.8 → 0.9.10

package/dist/review-context.js

@@ -43,7 +43,7 @@ import { isVerificationReceipt } from "./verification-evidence.js";
  */
 import { createHash } from "node:crypto";
 import { hasForbiddenControls } from "./decision.js";
-import { EVIDENCE_CAPS, readVerifiedArtifact, redactSecretLines, scanForSecrets, storeEvidence } from "./evidence.js";
+import { EVIDENCE_CAPS, isBinaryAssetPath, isImagePath, readVerifiedArtifact, redactSecretLines, scanForSecrets, storeEvidence } from "./evidence.js";
 import { parseProof } from "./proof.js";
 /** Explicit bounds. Content bytes are UTF-8 of the stored (possibly
  * redacted) text; the aggregate is the sum over every stored item. */
@@ -420,7 +420,8 @@ export function parseReviewContext(raw) {
         const c = one;
         if (!str(c["id"], 64) || coverageIds.has(c["id"]) || (c["state"] !== "patch" && c["state"] !== "context" && c["state"] !== "gap") ||
             typeof c["inherited"] !== "boolean" || !strList(c["paths"], 200) || !strList(c["items"], r["schema"] === 3 ? contentLimits.items : 64) || !strList(c["gaps"], r["schema"] === 3 ? 400 : 64) ||
-            (c["priorSupport"] !== "eligible" && c["priorSupport"] !== "invalid" && c["priorSupport"] !== "none")) {
+            (c["priorSupport"] !== "eligible" && c["priorSupport"] !== "invalid" && c["priorSupport"] !== "none") ||
+            (c["assets"] !== undefined && !str(c["assets"], 300))) {
             return { ok: false, problem: `coverage ${index}: malformed` };
         }
         if (c["items"].some(id => !ids.has(id) || !items.find(item => item.id === id)?.criteria.includes(String(c["id"]))))
@@ -431,6 +432,7 @@ export function parseReviewContext(raw) {
         coverage.push({
             id: c["id"], state: c["state"], inherited: c["inherited"], paths: [...c["paths"]],
             items: [...c["items"]], gaps: [...c["gaps"]], priorSupport: c["priorSupport"],
+            ...(c["assets"] === undefined ? {} : { assets: c["assets"] }),
         });
     }
     return {
@@ -499,6 +501,32 @@ async function treeEntries(git, cwd, revision, paths) {
     }
     return entries;
 }
+/** "12 images, 3.4 MB, in the run's evidence": every binary file at the head
+ * in one line. Files deleted by the change are not counted. */
+async function assetSummary(git, cwd, head, assets) {
+    const sizes = new Map();
+    const paths = [...assets].filter(safeContextPath);
+    for (let at = 0; at < paths.length; at += 500) {
+        const listed = await treeEntries(git, cwd, head, paths.slice(at, at + 500));
+        for (const [path, entry] of listed ?? [])
+            if (regular(entry))
+                sizes.set(path, entry.size);
+    }
+    if (sizes.size === 0)
+        return null;
+    const images = [...sizes.keys()].filter(isImagePath).length;
+    const others = sizes.size - images;
+    const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+    const counted = [...(images > 0 ? [plural(images, "image")] : []), ...(others > 0 ? [plural(others, images > 0 ? "other binary file" : "binary file")] : [])].join(", ");
+    return `${counted}, ${assetBytesWords([...sizes.values()].reduce((sum, one) => sum + one, 0))}, in the run's evidence`;
+}
+function assetBytesWords(bytes) {
+    if (bytes >= 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    if (bytes >= 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${bytes} bytes`;
+}
 function regular(entry) {
     return entry !== undefined && entry.type === "blob" && ["100644", "100755"].includes(entry.mode) && SHA1.test(entry.object) && Number.isSafeInteger(entry.size) && entry.size >= 0;
 }
@@ -822,11 +850,22 @@ export async function deriveReviewContext(store, git, args, lineage) {
                 gapAll("capture-failed", "the committed source paths in the approved scope could not be listed");
         }
     }
+    // Files named as images or other binaries are never text context: they are
+    // counted in one summary line, never listed as gaps or held against the
+    // bounds. A text-named file that turns out not to be text stays a gap.
+    const assets = new Set();
+    const textOnly = (paths) => paths.filter(path => {
+        if (!isBinaryAssetPath(path))
+            return true;
+        assets.add(path);
+        return false;
+    });
+    generalPaths.splice(0, generalPaths.length, ...textOnly(generalPaths));
     const specificFor = new Map();
     for (const criterion of sourceProof?.criteria ?? []) {
         const cited = [...new Set(criterion.evidence.filter(one => one.kind === "changed-path").map(one => one.ref))].filter(safeContextPath).sort();
         const inherited = parentContext?.coverage.find(one => one.id === criterion.id)?.paths ?? [];
-        const combined = [...new Set([...cited, ...inherited])].filter(safeContextPath).sort();
+        const combined = textOnly([...new Set([...cited, ...inherited])].filter(safeContextPath).sort());
         if (combined.length > 0)
             specificFor.set(criterion.id, combined);
     }
@@ -852,7 +891,7 @@ export async function deriveReviewContext(store, git, args, lineage) {
     // A proof's path citations are relevance hints, not permission to omit other
     // changed files. Deliver new revision files and tests in full as supplemental
     // context without inventing criterion ownership or inheriting a judgement.
-    for (const path of args.patchPaths) {
+    for (const path of textOnly([...args.patchPaths])) {
         if (safeContextPath(path) && !relevance.has(path))
             relevance.set(path, { criteria: new Set(), why: new Set(["candidate-changed-path"]) });
     }
@@ -965,6 +1004,7 @@ export async function deriveReviewContext(store, git, args, lineage) {
         }
     }
     inventory.items = [...itemsByPath.values()];
+    const assetLine = await assetSummary(git, args.worktree, args.head, assets);
     // 6. Prior review provenance — context, proved per criterion, never a verdict.
     const sourceDiff = sourceArtifacts.find(one => one.kind === "terminal-diff") ?? null;
     const sourceProofArtifact = sourceArtifacts.find(one => one.kind === "proof") ?? null;
@@ -1039,5 +1079,5 @@ export async function deriveReviewContext(store, git, args, lineage) {
         const gapsFor = state === "gap" && relevantGaps.length === 0 ? [plan.paths.length === 0 ? "no relevant source paths are known" : "inherited context is incomplete"] : relevantGaps;
         return { id: plan.id, state, inherited: plan.inherited && lineage.sourceRun !== args.runId, paths: plan.paths, items, gaps: gapsFor, priorSupport };
     });
-    return finish(coverage);
+    return finish(assetLine === null ? coverage : coverage.map(one => ({ ...one, assets: assetLine })));
 }

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