tumwater 0.2.0 → 0.3.0

package/dist/src/doctor/doctor-notify.js

@@ -1,11 +1,11 @@
 import { eventsSince } from "../events/event-window.js";
 import { isNotifyFailure } from "../events/notify.js";
-import { humanSeconds } from "../text/datetime.js";
+import { DAY_MS, humanAgo } from "../text/datetime.js";
 import { plural } from "../text/phrases.js";
 import { errorMessage, squash } from "../text/text.js";
 import { okOutcome, warnOutcome } from "./outcome.js";
 /** How far back the `notify` check looks for failed pages. */
-const NOTIFY_CHECK_WINDOW_MS = 24 * 3600_000;
+const NOTIFY_CHECK_WINDOW_MS = DAY_MS;
 /** The `notify` check: whether a notify command is configured, and a warning when it failed to
  * page within the last day (a nonzero exit, a kill, or a failed start — the warnings
  * spawnNotifyCommand logs). Warns but never fails, like the hold rows: a dead webhook must not
@@ -18,8 +18,7 @@ export function checkNotify(root, config, now = Date.now()) {
         if (failures.length === 0)
             return okOutcome("configured — no failed pages in the last 24h");
         const latest = failures[failures.length - 1];
-        const age = humanSeconds(Math.max(0, Math.round((now - latest.ts) / 1000)));
-        return warnOutcome(`${plural(failures.length, "failed page")} in the last 24h; latest ${age} ago: ${squash(String(latest.message), 200)}`);
+        return warnOutcome(`${plural(failures.length, "failed page")} in the last 24h; latest ${humanAgo(latest.ts, now)}: ${squash(String(latest.message), 200)}`);
     }
     catch (err) {
         return warnOutcome(`could not read the event log for failed pages: ${errorMessage(err)}`);

package/dist/src/doctor/doctor-opencode-checks.js

@@ -0,0 +1,162 @@
+import os from "node:os";
+import path from "node:path";
+import { childEnv } from "../process/process.js";
+import { boundedProbe } from "./probe.js";
+import { opencodeBackend, opencodeSpillDir } from "../agent/opencode/opencode-backend.js";
+import { opencodeModelKey, readOpencodeCache } from "../agent/opencode/opencode-catalog.js";
+import { opencodeDbPath } from "../paths.js";
+import { envPath, isDirectory, readTextOrNull, statOrNull, treeBytes } from "../files/files.js";
+import { formatBytes, tokenWindowLabel } from "../text/format.js";
+import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
+import { AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS, loadConfigForCheck, opencodeSeamsInUse, seamedModels, } from "./doctor-model-checks.js";
+/** The doctor's opencode credential and leak readiness check, split out of doctor-model-checks.ts
+ * (whose shared seam/model framework and the pi, tier-models and image-input checks stay there):
+ * checkOpencode and its helpers (opencodeProviderOf, opencodeAuthLists, jsonKeyPresent,
+ * opencodeConfigLeaks). This is the doctor's only check that spawns the `opencode` CLI and reads
+ * its catalog and the operator's global opencode config — a distinct concern from the
+ * filesystem/git checks beside it, kept together so a change to how doctor reads opencode does
+ * not touch the other model checks. The shared report contract (CheckOutcome) and the
+ * seam/model framework (loadConfigForCheck, opencodeSeamsInUse, seamPairs, the AUTH_CHECK_*
+ * budgets) come from doctor-model-checks.ts and outcome.ts, as the other doctor-* modules do. */
+/** The provider of a non-gateway opencode model id (`opencode/<provider>/<model>`), or
+ * undefined for a gateway id (a bare `opencode/<model>` or `<model>`, served by OpenCode's
+ * own gateway with no credential). A model id with more than the `opencode/` namespace prefix
+ * is provider-qualified and needs a credential OpenCode lists. */
+function opencodeProviderOf(model) {
+    const parts = model.split("/");
+    if (parts[0] === "opencode" && parts.length >= 3)
+        return parts[1];
+    if (parts[0] !== "opencode" && parts.length >= 2)
+        return parts[0];
+    return undefined;
+}
+/** Whether `opencode auth list --format json` (bounded) lists `provider` exactly. A probe that
+ * cannot run, exits nonzero, or omits the provider reads as NOT listed — the safe direction,
+ * since doctor is warning the operator to add the credential, never confirming one it did not
+ * see. The list is matched EXACTLY, not as a raw substring: when the output parses as an array
+ * (of names or of per-credential objects), a credential listed as `anthropic` must never vouch
+ * for `anthropic-foo` twice over; when it cannot be parsed as JSON (a shape the CLI may change),
+ * the text is matched word-bounded so a truncated or prose line still reads. */
+async function opencodeAuthLists(config, provider, pathEnv, timeoutMs) {
+    const resolved = opencodeBackend.resolveBin(config);
+    const result = await boundedProbe(resolved.bin, ["auth", "list", "--format", "json"], childEnv({ PATH: pathEnv }), timeoutMs, AUTH_CHECK_MAX_OUTPUT_BYTES);
+    if (result?.code !== 0)
+        return false;
+    const text = result.stdout;
+    try {
+        const parsed = JSON.parse(text);
+        if (Array.isArray(parsed)) {
+            return parsed.some((item) => {
+                if (typeof item === "string")
+                    return item === provider;
+                return (item !== null &&
+                    typeof item === "object" &&
+                    Object.values(item).some((v) => v === provider));
+            });
+        }
+    }
+    catch {
+        // Not an array-shaped JSON payload — fall through to the word-bounded text match.
+    }
+    const esc = provider.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[^A-Za-z0-9_-])${esc}([^A-Za-z0-9_-]|$)`).test(text);
+}
+/** Whether a JSON-ish key (optionally quoted, followed by a colon) appears in a config file's
+ * text — a loose match that tolerates JSONC comments without parsing them. */
+function jsonKeyPresent(text, key) {
+    return new RegExp(`["']?${key}["']?\\s*:`).test(text);
+}
+/** The operator's global opencode config files and AGENTS.md (plans/opencode-backend.md §7
+ * "Leaks", part 7/7): the operator's own config and instructions still load into team runs,
+ * so each MCP server (disabled for team runs) or plugin/agent/instructions entry or the
+ * AGENTS.md file itself produces one warning naming the file and what leaks in: an MCP server
+ * is switched off by the harness, while a plugin/agent/instructions entry or AGENTS.md is NOT
+ * switched off and still loads. `configHome` is the config root to scan — the XDG config home
+ * (when set) or `~/.config`, the SAME folder opencode's own operatorMcpNames reads, so the leak
+ * scan matches the config a run actually loads. Config files
+ * are JSON/C, so the keys are matched loosely (a word followed by a colon) rather than fully
+ * parsed — enough to name what still loads before a run inherits it. */
+function opencodeConfigLeaks(configHome) {
+    const dir = path.join(configHome, "opencode");
+    const warns = [];
+    for (const file of ["config.json", "opencode.json", "opencode.jsonc"]) {
+        const text = readTextOrNull(path.join(dir, file));
+        if (text === null)
+            continue;
+        const parts = [];
+        let mcp = false;
+        if (jsonKeyPresent(text, "mcp") && jsonKeyPresent(text, "servers")) {
+            parts.push("an MCP server");
+            mcp = true;
+        }
+        for (const key of ["plugin", "agent", "instructions"]) {
+            if (jsonKeyPresent(text, key))
+                parts.push(`a ${key} entry`);
+        }
+        if (parts.length === 0)
+            continue;
+        const joined = parts.join(" and ");
+        // Only the MCP server is disabled for team runs; everything else still loads.
+        const verdict = mcp && parts.length === 1 ? " — disabled for team runs" : " — still loads into team runs";
+        warns.push(`${path.join(dir, file)} carries ${joined}${verdict}`);
+    }
+    const agentsMd = path.join(dir, "AGENTS.md");
+    if (statOrNull(agentsMd)?.isFile() === true)
+        warns.push(`${agentsMd} still loads into team runs`);
+    return warns;
+}
+/** OpenCode model, credential and leak readiness (plans/opencode-backend.md §7, part 7/7):
+ * every model routed to opencode must be in the catalog cache — an unknown model fails, a
+ * cached one reads "free" or its per-M prices and context window, and a thinking level with no
+ * catalog effort is noted as dropped; a non-gateway provider (`opencode/<provider>/…`) must
+ * have a credential `opencode auth list` lists, else warns; and the operator's global opencode
+ * config and AGENTS.md must not leak an MCP server or a plugin/agent/instructions entry into
+ * team runs, else warns naming the file and key. Reports the team's opencode database and spill
+ * sizes as information. Stands down (ok) when no seam routes to opencode, so a pi-only team
+ * spawns nothing and reads nothing. `pathEnv` and `home` are injectable so tests need no real
+ * PATH or HOME. The version half of the opencode pre-flight is the sibling checkOpencodeVersion
+ * in doctor-checks.ts. */
+export async function checkOpencode(root, pathEnv = envPath(), home = os.homedir(), xdgConfigHome = process.env.XDG_CONFIG_HOME ?? "", timeoutMs = AUTH_CHECK_TIMEOUT_MS) {
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
+    if (!opencodeSeamsInUse(config))
+        return okOutcome("no model jobs run on opencode");
+    const models = seamedModels(config, "opencode");
+    const cache = readOpencodeCache(root);
+    const fails = [];
+    const warns = [];
+    const notes = [];
+    for (const pair of models) {
+        const key = opencodeModelKey(pair.model);
+        const entry = cache.models[key];
+        if (entry === undefined) {
+            fails.push(`${pair.model} is not in the opencode catalog cache`);
+            continue;
+        }
+        const price = entry.free ? "free" : `$${entry.inputPerM ?? 0}/$${entry.outputPerM ?? 0} per M`;
+        const window = entry.context !== undefined ? `, ${tokenWindowLabel(entry.context)}` : "";
+        notes.push(`${pair.model} — ${price}${window}`);
+        // A model with no effort list at all supports no thinking level, so a requested level is
+        // dropped just the same as one the list omits.
+        if (pair.thinking !== undefined &&
+            pair.thinking !== "" &&
+            !entry.efforts?.includes(pair.thinking)) {
+            warns.push(`${pair.model} has no ${pair.thinking} effort — that thinking level is dropped`);
+        }
+        const provider = opencodeProviderOf(pair.model);
+        if (provider !== undefined && !(await opencodeAuthLists(config, provider, pathEnv, timeoutMs))) {
+            warns.push(`${pair.model} is a non-gateway provider opencode does not list a credential for`);
+        }
+    }
+    warns.push(...opencodeConfigLeaks(xdgConfigHome !== "" ? xdgConfigHome : path.join(home, ".config")));
+    const db = statOrNull(opencodeDbPath(root));
+    const spillDir = opencodeSpillDir(root);
+    const spill = spillDir !== "" && isDirectory(spillDir) ? treeBytes(spillDir) : null;
+    const sizeNotes = `db ${formatBytes(db?.size ?? 0)}${spill !== null ? `, spill ${formatBytes(spill)}` : ", no spill dir"}`;
+    const found = [...fails, ...warns];
+    const base = found.length === 0 ? `opencode ready — ${notes.join("; ")}; ${sizeNotes}` : found.join("; ");
+    if (fails.length > 0)
+        return failOutcome(base);
+    return (warns.length > 0 ? warnOutcome : okOutcome)(base);
+}

package/dist/src/doctor/doctor-orphans.js

@@ -1,9 +1,10 @@
-// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { worktreesDir } from "../paths.js";
 import { pidAlive } from "../process/process.js";
+import { GROUP_POLL_MS, KILL_GRACE_MS } from "../process/process-group.js";
 import { systemProcessProbe } from "../process/process-table.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage, truncate } from "../text/text.js";
 import { plural } from "../text/phrases.js";
 import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
@@ -71,10 +72,10 @@ function relativeArgvIsOurs(command, cwd, root, dirs) {
     }
     return false;
 }
-/** How many processes descend from `pid`, given the table's parent → children map — an
+/** The processes that descend from `pid`, given the table's parent → children map — an
  * orphaned test runner's workers keep the runner as their parent, so they are the orphan's
  * tree, not orphans of their own, and killing the runner alone leaves them running. */
-function descendantCount(children, pid) {
+function descendantPids(children, pid) {
     const seen = new Set();
     const stack = [...(children.get(pid) ?? [])];
     for (let p = stack.pop(); p !== undefined; p = stack.pop()) {
@@ -83,52 +84,43 @@ function descendantCount(children, pid) {
         seen.add(p);
         stack.push(...(children.get(p) ?? []));
     }
-    return seen.size;
+    return [...seen];
 }
-/** Orphaned worktree processes — the detector half of the grandchild-leak fix (BUGS.md
- * 2026-09-21): a process reparented to PID 1 that belongs to one of this repo's worktrees.
- * Leaks of this kind (a killed tick's tool-call grandchildren, a timed-out build check's test
- * tree, a pi run's backgrounded server, a stray orchestrator an orphaned suite started) hold
- * no lock, write no event and touch no state file, so nothing else in the harness can see
- * them. A process is this repo's when its argv names a path under `.tumwater/worktrees/`
- * (absolute; or relative, confirmed by cwd where it can be — relativeArgvIsOurs) or when its
- * cwd lies under it: a leaked `node dist/test/test-runner.js` names no worktree at all.
- *
- * PPID 1 is what keeps the live team out: a running orchestrator's pi runs and build checks
- * have the orchestrator as parent, and the orchestrator and its supervisor run from the repo
- * root, never from a worktree, even when a detached `nohup` launch leaves them parentless.
- * (macOS always reparents an orphan to launchd, PID 1; on Linux a process under a child
- * subreaper — `systemd --user` in a desktop session — is reparented to that instead, and is
- * not seen here.)
- *
- * A second kind of evidence closes the gap the 2026-09-30 sweep fix left (BUGS.md, part
- * 2/2): every process a run starts carries `TUMWATER_RUN=<harness pid>-<nonce>` in its
- * environment (appended to any inherited mark), wherever its cwd is — exactly where the
- * prompts send agents (scratch dirs under the system temp). A parentless process whose
- * every mark names a harness pid that is no longer alive is this team's orphan: nothing
- * will reap it, because the run sweep that would have dies with its harness. A mark naming
- * ANY live harness is not reported — that harness's own sweep kills everything carrying the
- * mark when its run folds. A pid that died and was recycled by an unrelated process reads
- * as live (pidAlive cannot tell), so such a straggler stays unseen here — the same limit the
- * merge lock's stale-holder check carries. An unparseable mark (a torn or foreign value
- * without a `<pid>-` prefix) judges nothing; on macOS ps -E hides platform binaries'
- * environments, so a marked sleep/sh leak stays unseen there, as the sweep's own scan does.
- *
- * Cheap by construction: one `ps`, then one cwd lookup covering only the parentless
- * processes argv did not already settle (and only those this user can inspect — lsof and
- * /proc cannot read anyone else's, root reads all). An unreadable table degrades to a warn,
- * never a crashed doctor; unreadable cwds degrade to the argv match and say so. Any orphan is
- * a fail — the exit code is the point: a scripted doctor must notice. `probe` is injectable so
- * tests run against a fake table. */
-export async function checkOrphans(root, probe = systemProcessProbe) {
+/** A mark's harness is dead (true), alive (false), or the mark names no harness (null — a torn
+ * or foreign value judges nothing rather than counting as dead). */
+function harnessGone(marker) {
+    const m = /^(\d+)-/.exec(marker);
+    return m ? !pidAlive(Number(m[1])) : null;
+}
+/** A parent pid → child pids map of the table. */
+function childrenOf(rows) {
+    const children = new Map();
+    for (const r of rows) {
+        const siblings = children.get(r.ppid);
+        if (siblings)
+            siblings.push(r.pid);
+        else
+            children.set(r.ppid, [r.pid]);
+    }
+    return children;
+}
+/** An orphan's command with the repo root cut out, longest spelling first: the resolved one can
+ * contain the given one (/private/var/… holds /var/…) — then trimmed to ORPHAN_COMMAND_MAX. */
+function shownCommand(command, root) {
+    const cut = [...rootSpellings(root)].sort((a, b) => b.length - a.length);
+    return truncate(cut.reduce((c, rt) => c.split(`${rt}/`).join(""), command), ORPHAN_COMMAND_MAX);
+}
+/** The detection half of checkOrphans, shared with killOrphans so the check and the kill cannot
+ * disagree about the set. */
+async function findOrphans(root, probe) {
+    const roots = rootSpellings(root);
     let rows;
     try {
         rows = await probe.list();
     }
     catch (err) {
-        return warnOutcome(`could not scan the process table — ${errorMessage(err)}`);
+        return { error: errorMessage(err) };
     }
-    const roots = rootSpellings(root);
     const dirs = roots.map(worktreesDir);
     // Never doctor itself, should it be run parentless from a worktree's build.
     const parentless = rows.filter((r) => r.ppid === 1 && r.pid !== process.pid);
@@ -156,12 +148,6 @@ export async function checkOrphans(root, probe = systemProcessProbe) {
             // Best-effort per the probe contract: argv and cwd still carry the check alone.
         }
     }
-    /** A mark's harness is dead (true), alive (false), or the mark names no harness (null —
-     * a torn or foreign value judges nothing rather than counting as dead). */
-    const harnessGone = (marker) => {
-        const m = /^(\d+)-/.exec(marker);
-        return m ? !pidAlive(Number(m[1])) : null;
-    };
     const byMark = new Set();
     for (const r of parentless) {
         if (byArgv.has(r.pid))
@@ -176,35 +162,168 @@ export async function checkOrphans(root, probe = systemProcessProbe) {
         const cwd = cwds.get(r.pid);
         return (cwd !== undefined && isUnder(cwd, dirs)) || relativeArgvIsOurs(r.command, cwd, root, dirs);
     });
+    return { rows, orphans, marks, cwdProblem };
+}
+/** Orphaned worktree processes — the detector half of the grandchild-leak fix (BUGS.md
+ * 2026-09-21): a process reparented to PID 1 that belongs to one of this repo's worktrees.
+ * Leaks of this kind (a killed run's tool-call grandchildren, a timed-out build check's test
+ * tree, a pi run's backgrounded server, a stray orchestrator an orphaned suite started) hold
+ * no lock, write no event and touch no state file, so nothing else in the harness can see
+ * them. A process is this repo's when its argv names a path under `.tumwater/worktrees/`
+ * (absolute; or relative, confirmed by cwd where it can be — relativeArgvIsOurs) or when its
+ * cwd lies under it: a leaked `node dist/test/test-runner.js` names no worktree at all.
+ *
+ * PPID 1 is what keeps the live team out: a running orchestrator's pi runs and build checks
+ * have the orchestrator as parent, and the orchestrator and its supervisor run from the repo
+ * root, never from a worktree, even when a detached `nohup` launch leaves them parentless.
+ * (macOS always reparents an orphan to launchd, PID 1; on Linux a process under a child
+ * subreaper — `systemd --user` in a desktop session — is reparented to that instead, and is
+ * not seen here.)
+ *
+ * A second kind of evidence closes the gap the 2026-09-30 sweep fix left (BUGS.md, part
+ * 2/2): every process a run starts carries `TUMWATER_RUN=<harness pid>-<nonce>` in its
+ * environment (appended to any inherited mark), wherever its cwd is — exactly where the
+ * prompts send agents (scratch dirs under the system temp). A parentless process whose
+ * every mark names a harness pid that is no longer alive is this team's orphan: nothing
+ * will reap it, because the run sweep that would have dies with its harness. A mark naming
+ * ANY live harness is not reported — that harness's own sweep kills everything carrying the
+ * mark when its run folds. A pid that died and was recycled by an unrelated process reads
+ * as live (pidAlive cannot tell), so such a straggler stays unseen here — the same limit the
+ * merge lock's stale-holder check carries. An unparseable mark (a torn or foreign value
+ * without a `<pid>-` prefix) judges nothing; on macOS ps -E hides platform binaries'
+ * environments, so a marked sleep/sh leak stays unseen there, as the sweep's own scan does.
+ *
+ * Cheap by construction: one `ps`, then one cwd lookup covering only the parentless
+ * processes argv did not already settle (and only those this user can inspect — lsof and
+ * /proc cannot read anyone else's, root reads all). An unreadable table degrades to a warn,
+ * never a crashed doctor; unreadable cwds degrade to the argv match and say so. Any orphan is
+ * a fail — the exit code is the point: a scripted doctor must notice. `probe` is injectable so
+ * tests run against a fake table. */
+export async function checkOrphans(root, probe = systemProcessProbe) {
+    const scan = await findOrphans(root, probe);
+    if ("error" in scan)
+        return warnOutcome(`could not scan the process table — ${scan.error}`);
+    const { rows, orphans, marks, cwdProblem } = scan;
     if (orphans.length === 0) {
         if (cwdProblem !== null)
             return warnOutcome(`none named in argv, but process cwds are unreadable (${cwdProblem}) — an orphan started inside a worktree, like a leaked test runner, would be missed`);
         return okOutcome("none — no process reparented to PID 1 runs from .tumwater/worktrees/ or carries only dead runs' marks");
     }
-    const children = new Map();
-    for (const r of rows) {
-        const siblings = children.get(r.ppid);
-        if (siblings)
-            siblings.push(r.pid);
-        else
-            children.set(r.ppid, [r.pid]);
-    }
-    // The root is cut from each shown command, longest spelling first: the resolved one can
-    // contain the given one (/private/var/… holds /var/…).
-    const cut = [...roots].sort((a, b) => b.length - a.length);
+    const children = childrenOf(rows);
     const listed = orphans.slice(0, ORPHANS_LISTED_MAX).map((r) => {
-        const n = descendantCount(children, r.pid);
+        const n = descendantPids(children, r.pid).length;
         const tree = n > 0 ? `, +${plural(n, "descendant")}` : "";
-        const command = cut.reduce((c, rt) => c.split(`${rt}/`).join(""), r.command);
         // A mark-caught orphan says which run marked it: the operator killing it wants to know
         // nothing else will, and the dead harness's pid is the evidence argv and cwd lacked.
         const mark = (marks.get(r.pid) ?? []).find((m) => harnessGone(m) === true);
         const marked = mark !== undefined ? ` (run ${mark}; tumwater ${mark.split("-")[0]} exited)` : "";
-        return `pid ${r.pid} (age ${r.etime}, cpu ${r.time}${tree}) ${truncate(command, ORPHAN_COMMAND_MAX)}${marked}`;
+        return `pid ${r.pid} (age ${r.etime}, cpu ${r.time}${tree}) ${shownCommand(r.command, root)}${marked}`;
     });
     const more = orphans.length - listed.length;
     const count = `${plural(orphans.length, "orphaned process", "orphaned processes")} (PPID 1)`;
     return failOutcome(`${count}: ${listed.join("; ")}${more > 0 ? `; and ${more} more` : ""}` +
-        " — nothing reaps these; kill each with its descendants" +
+        " — nothing reaps these; `tumwater doctor --kill-orphans` (or the dashboard Health card's Kill orphans, or the TUI Health tab's Ctrl+K pressed twice) kills each with its descendants" +
         (cwdProblem !== null ? ` (process cwds unreadable — ${cwdProblem}; argv matched only)` : ""));
 }
+const systemSignals = {
+    kill: (pid, signal) => void process.kill(pid, signal),
+    alive: pidAlive,
+    graceMs: KILL_GRACE_MS,
+    pollMs: GROUP_POLL_MS,
+};
+/** The lines `doctor --kill-orphans` prints for a report, shared with the dashboard's Kill
+ * orphans toast. */
+export function orphanKillLines(report) {
+    if ("error" in report)
+        return [`could not scan the process table — ${report.error}; nothing killed`];
+    const lines = report.killed.map((k) => {
+        const tree = k.descendants > 0 ? ` (+${plural(k.descendants, "descendant")})` : "";
+        return `killed pid ${k.pid}${tree} ${k.command}`;
+    });
+    for (const f of report.failed)
+        lines.push(`could not kill pid ${f.pid}: ${f.reason}`);
+    if (lines.length === 0)
+        lines.push("no orphaned processes to kill");
+    return lines;
+}
+/** Kill the processes checkOrphans lists, each with its descendants from the same scan:
+ * SIGTERM all, wait up to `graceMs` for them to go, SIGKILL what remains. A pid already gone
+ * (ESRCH) counts as killed; any other refusal (EPERM) is reported and the rest are still
+ * signalled. An orphan with a refused pid in its tree is reported failed, not killed. */
+export async function killOrphans(root, probe = systemProcessProbe, signals = systemSignals) {
+    const scan = await findOrphans(root, probe);
+    if ("error" in scan)
+        return { error: scan.error };
+    return killTrees(root, scan.rows, scan.orphans, signals);
+}
+/** The signal-and-wait half of killOrphans: SIGTERM each chosen row's tree from `rows`, wait,
+ * SIGKILL the rest, and report what went. */
+async function killTrees(root, rows, chosen, signals) {
+    const children = childrenOf(rows);
+    const refused = new Map();
+    const send = (pid, signal) => {
+        try {
+            signals.kill(pid, signal);
+        }
+        catch (err) {
+            if (err.code !== "ESRCH")
+                refused.set(pid, errorMessage(err));
+        }
+    };
+    const trees = chosen.map((r) => ({ r, pids: [r.pid, ...descendantPids(children, r.pid)] }));
+    const all = [...new Set(trees.flatMap((t) => t.pids))];
+    for (const pid of all)
+        send(pid, "SIGTERM");
+    const stillAlive = () => all.filter((pid) => !refused.has(pid) && signals.alive(pid));
+    const deadline = Date.now() + signals.graceMs;
+    while (stillAlive().length > 0 && Date.now() < deadline)
+        await new Promise((resolve) => setTimeout(resolve, signals.pollMs));
+    for (const pid of stillAlive())
+        send(pid, "SIGKILL");
+    const killed = [];
+    const failed = [];
+    for (const { r, pids } of trees) {
+        const bad = pids.find((pid) => refused.has(pid));
+        if (bad === undefined)
+            killed.push({ pid: r.pid, command: shownCommand(r.command, root), descendants: pids.length - 1 });
+        else
+            failed.push({ pid: bad, reason: refused.get(bad) ?? "" });
+    }
+    return { killed, failed };
+}
+/** Team start's reap of a crashed predecessor's leaks: kill the parentless processes whose run
+ * marks all name dead harnesses and at least one names `previousPid`, the orchestrator the
+ * info file recorded. Safe without an operator's judgment: a mark proves a tumwater start
+ * started the process, the previous-pid match scopes it to this repo, and the dead-harness
+ * test excludes any run whose own sweep is still coming. A live `previousPid` (a hand-off
+ * whose old orchestrator is draining) scans nothing. Orphans caught only by argv or cwd carry
+ * no mark read (findOrphans asks marks only of processes argv did not settle) and stay for
+ * `doctor --kill-orphans`. Returns the killed count; never throws. */
+export async function reapPreviousTeamOrphans(root, previousPid, probe = systemProcessProbe, signals = systemSignals) {
+    try {
+        if (pidAlive(previousPid))
+            return 0;
+        const scan = await findOrphans(root, probe);
+        if ("error" in scan)
+            return 0;
+        const chosen = scan.orphans.filter((r) => {
+            const marks = scan.marks.get(r.pid) ?? [];
+            return marks.length > 0 && marks.every((m) => harnessGone(m) === true) &&
+                marks.some((m) => m.startsWith(`${previousPid}-`));
+        });
+        if (chosen.length === 0)
+            return 0;
+        const { killed, failed } = await killTrees(root, scan.rows, chosen, signals);
+        const items = killed.map((k) => {
+            const tree = k.descendants > 0 ? ` (+${plural(k.descendants, "descendant")})` : "";
+            return `pid ${k.pid}${tree} ${k.command}`;
+        });
+        const refused = failed.map((f) => `could not kill pid ${f.pid}: ${f.reason}`);
+        warnEventBestEffort(root, TUMWATER_SOURCE, `killed ${plural(killed.length, "orphaned process", "orphaned processes")} left by tumwater ` +
+            `${previousPid}'s runs at team start: ${[...items, ...refused].join("; ")}`);
+        return killed.length;
+    }
+    catch {
+        return 0;
+    }
+}