tumwater 0.4.2 → 0.4.3

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

@@ -1,13 +1,16 @@
 import { childEnv } from "../process/process.js";
-import { AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS, boundedProbe } from "./probe.js";
+import { AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS, boundedProbe } from "./doctor-probe.js";
 import { defaultConfig, loadConfigSafe } from "../config/config.js";
 import { seamsInUse } from "../config/config-fallbacks.js";
 import { cacheReadUnpriced, piModelsPath, readPiProviders } from "../pi/pi-models.js";
+import { roleImageInfo } from "../agent/image-input.js";
+import { readPiListedModels } from "../pi/pi-listed-models.js";
+import { runnerIds } from "../roles/runner-ids.js";
 import { envPath } from "../files/files.js";
 import { piListedModels, piProviderAuth } from "./doctor-pi-checks.js";
 import { agree } from "../text/phrases.js";
 import { joinParts } from "../text/text.js";
-import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
+import { failOutcome, okOutcome, warnOutcome } from "./doctor-outcome.js";
 import { belowNodeFloor } from "../version.js";
 /** The one phrase a configured-models check uses when the config declares no models at all:
  * informational (capability falls to pi's own defaults), not a warning. Shared by
@@ -30,8 +33,9 @@ const PHRASE_CANNOT_READ_MODELS = "cannot check — could not read pi's model de
  * modules do. The claude, opencode, codex and pi provider checks live in their own per-backend
  * modules (doctor-claude-checks.ts, doctor-opencode-checks.ts, doctor-codex-checks.ts,
  * doctor-pi-checks.ts), each importing this file's shared seam framework and the AUTH_CHECK_*
- * probe budgets from probe.ts rather than duplicating them. The shared report contract
- * (CheckOutcome) is imported from outcome.ts, exactly as the other doctor-* modules do. Together
+ * probe budgets from doctor-probe.ts rather than duplicating them. The shared report contract
+ * (CheckOutcome) is imported from doctor-outcome.ts, exactly as the other doctor-*
+ * modules do. Together
  * these are the doctor's only checks that read pi's model definitions and, for the probes, spawn
  * an agent binary — a distinct concern from the filesystem/git checks, kept together so a change
  * to how doctor reads models does not touch the environment checks. */
@@ -131,30 +135,8 @@ export function codexSeamsInUse(config) {
 export function piSeamsInUse(config) {
     return seamsInUse(config).some((s) => s.agent === "pi");
 }
-/** Declared model readiness — plans/model-tiers.md "Doctor" (part 7c/8): every model the config can
- * put on a seam must resolve in pi's definitions, and its provider must report `ready` from the
- * agent binary's own auth check. A strong tier pi cannot resolve would fail every review, and so
- * every merge — the check exists so the operator finds out before the team does, mid-review. Pairs
- * collected in the same sweep teamModelsFree prices: each tier's top-level selector (a string is
- * default's), every enabled role's resolved pair (per-role overrides included; tier-name overrides
- * resolve through configForRole), and the reviewer's while review is on. A pair with no model is
- * pi's own default and out of scope; fallback pairs are the sibling check's (checkFallbackModel
- * prices the cap pair). Levels: an unresolvable pair fails, a provider that is not ready warns
- * (credentials are fixable without a config edit), a probe that cannot run warns rather than
- * guesses, and a priced model whose cache reads declare $0 warns — the daily budget would
- * undercount it (BUGS.md 2026-10-06). When one of PI_SMOL_MODEL / PI_SLOW_MODEL / PI_PLAN_MODEL is
- * set the check also reports that tumwater does not read it — the variables are oh-my-pi's, pi
- * ignores them, and with omp as `agentBin` they still reach omp through the inherited environment
- * (src/pi/pi-backend.ts, built on src/process/run-marker.ts's backendBaseEnv) — pointing at the
- * tier keys that do the same job (`model.small` / `model.strong`). `auth` is injectable so tests
- * need no pi on PATH; `env` so the PI_* branches stay hermetic. */
-export async function checkTierModels(root, modelsPath = piModelsPath(), auth = (provider) => piProviderAuth(loadConfigSafe(root).config ?? defaultConfig(), provider), env = process.env, listModels = () => piListedModels(loadConfigSafe(root).config ?? defaultConfig(), envPath(), AUTH_CHECK_TIMEOUT_MS, root)) {
-    const config = loadConfigForCheck(root);
-    if ("level" in config)
-        return config;
-    // Asked lazily and at most once: only a pair models.json does not declare needs the listing.
-    let listing;
-    const listed = () => (listing ??= listModels());
+/** One job: sweep the config's seam pairs into the pair map and the routed-models map. */
+function collectTierPairs(config) {
     const pairs = new Map();
     // Routed (non-pi) models keyed by the backend they resolved to, so the routing note names
     // each backend correctly; opencode is not claude.
@@ -175,75 +157,100 @@ export async function checkTierModels(root, modelsPath = piModelsPath(), auth =
     };
     for (const pair of seamPairs(config))
         add(pair.agent, pair.provider, pair.model);
+    return { pairs, routedModels };
+}
+/** One job: compute the oh-my-pi variables note, and whether any is set. */
+function ompTierNote(env) {
     const ompVars = ["PI_SMOL_MODEL", "PI_SLOW_MODEL", "PI_PLAN_MODEL"].filter((v) => env[v] !== undefined && env[v] !== "");
-    const ompNote = ompVars.length === 0
-        ? ""
-        : ` — ${ompVars.join(" and ")} ${agree(ompVars.length, "is", "are")} set: tumwater does not read ${agree(ompVars.length, "it", "them")} (oh-my-pi's variables; pi ignores them; with omp as agentBin they still reach omp through the inherited environment) — set model.small / model.strong instead`;
-    if (pairs.size === 0 && routedModels.size === 0)
-        return (ompVars.length === 0 ? okOutcome : warnOutcome)(`${PHRASE_NO_MODELS_DECLARED}${ompNote}`);
+    return {
+        set: ompVars.length > 0,
+        note: ompVars.length === 0
+            ? ""
+            : ` — ${ompVars.join(" and ")} ${agree(ompVars.length, "is", "are")} set: tumwater does not read ${agree(ompVars.length, "it", "them")} (oh-my-pi's variables; pi ignores them; with omp as agentBin they still reach omp through the inherited environment) — set model.small / model.strong instead`,
+    };
+}
+/** One job: read pi's provider definitions, or the empty map when the file is unreadable but
+ * every pair names a provider the listing can back (the unreadable case the caller warns on). */
+async function readTierProviders(modelsPath, pairs, listed) {
     let providers = readPiProviders(modelsPath);
     if (!providers && [...pairs.values()].some((p) => p.provider !== undefined) && (await listed()))
         providers = new Map();
-    const fails = [];
+    return providers;
+}
+/** One job: the fail string for a pair neither pi's definitions nor (when reachable) its
+ * listing resolve, or undefined when the listing does contain it. */
+function unresolvedModelFail(provider, model, defs, listedModels, modelsPath) {
+    if (listedModels?.has(`${provider}/${model}`))
+        return undefined;
+    const providerListed = listedModels != null && [...listedModels].some((k) => k.startsWith(`${provider}/`));
+    if (!defs && !providerListed) {
+        return listedModels === null
+            ? `provider ${provider} is not in pi's definitions (${modelsPath})`
+            : `provider ${provider} is not in pi's definitions (${modelsPath}) and \`pi --list-models\` lists none of its models — pi lists only providers it has credentials for`;
+    }
+    if (listedModels === null) {
+        // No exact entry: pi clones the provider's default model for the id, inheriting that
+        // default's price and context window (BUGS.md 2026-10-06) — name that consequence
+        // instead of only the failed lookup.
+        return `${provider}/${model} does not resolve in pi's definitions (${modelsPath}) — pi would price it at the provider default's rates and context window`;
+    }
+    return `${provider}/${model} is neither in pi's definitions (${modelsPath}) nor listed by \`pi --list-models\``;
+}
+/** One job: the warn string for a priced model whose cache reads declare $0, or undefined. */
+function cacheReadWarning(providers, provider, model, def) {
+    if (def && cacheReadUnpriced(providers, provider, model)) {
+        return `${provider}/${model} prices cache reads at $0 — the daily budget will undercount its spend`;
+    }
+    return undefined;
+}
+/** One job: probe one provider's auth once, reporting ready or the warn when it is not. */
+async function probeTierProvider(provider, auth, checkedProviders) {
+    if (checkedProviders.has(provider))
+        return {};
+    checkedProviders.add(provider);
+    const verdict = await auth(provider);
+    if (verdict === "ready")
+        return { ready: true };
+    if (verdict === "not-ready")
+        return { warn: `provider ${provider} reports not ready — check its credentials` };
+    return { warn: `could not verify provider ${provider} — the auth check did not run or its output was unreadable` };
+}
+/** One job: resolve one pi pair — the per-token claude warn, the definitions lookup and its
+ * unresolved fail, the free-cache-reads warn, and the once-per-provider auth probe. */
+async function resolveTierPair(provider, model, providers, listed, auth, checkedProviders, modelsPath) {
     const warns = [];
-    if (pairs.size > 0 && !providers)
-        return warnOutcome(`${PHRASE_CANNOT_READ_MODELS}${modelsPath}${ompNote}`);
-    const readyProviders = new Set();
-    const checkedProviders = new Set();
-    for (const { provider, model } of pairs.values()) {
-        if (provider === undefined) {
-            warns.push(`${model} names no provider — pi resolves it with its own default, tumwater cannot verify it`);
-            continue;
-        }
-        // A Claude model routed to pi (plans/provider-concurrency.md "Routing a bare Claude model id
-        // to claude"): a named provider keeps it on pi, but since Anthropic's 2026-04-04
-        // third-party-harness change a Claude plan's limits cover only first-party tools, so it is
-        // billed per token even under a Claude subscription login — the bare `claude-…` form on the
-        // claude CLI uses the plan's included usage instead.
-        if (model?.startsWith("claude-")) {
-            warns.push(`${provider}/${model} runs on pi and is billed per token, not the Claude plan's included usage — use a bare claude-… id to route it to the claude CLI`);
-        }
-        const defs = providers?.get(provider);
-        const def = defs?.find((d) => d.id === model);
-        if (!def) {
-            const listedModels = await listed();
-            if (!listedModels?.has(`${provider}/${model}`)) {
-                const providerListed = listedModels != null && [...listedModels].some((k) => k.startsWith(`${provider}/`));
-                if (!defs && !providerListed) {
-                    fails.push(listedModels === null
-                        ? `provider ${provider} is not in pi's definitions (${modelsPath})`
-                        : `provider ${provider} is not in pi's definitions (${modelsPath}) and \`pi --list-models\` lists none of its models — pi lists only providers it has credentials for`);
-                }
-                else if (listedModels === null) {
-                    // No exact entry: pi clones the provider's default model for the id, inheriting that
-                    // default's price and context window (BUGS.md 2026-10-06) — name that consequence
-                    // instead of only the failed lookup.
-                    fails.push(`${provider}/${model} does not resolve in pi's definitions (${modelsPath}) — pi would price it at the provider default's rates and context window`);
-                }
-                else {
-                    fails.push(`${provider}/${model} is neither in pi's definitions (${modelsPath}) nor listed by \`pi --list-models\``);
-                }
-                continue;
-            }
-        }
-        if (def && providers && cacheReadUnpriced(providers, provider, model)) {
-            // A priced model whose cache reads declare $0: pi bills cache-read tokens at zero and
-            // the daily budget undercounts the real spend (BUGS.md 2026-10-06).
-            warns.push(`${provider}/${model} prices cache reads at $0 — the daily budget will undercount its spend`);
-        }
-        if (!checkedProviders.has(provider)) {
-            checkedProviders.add(provider);
-            const verdict = await auth(provider);
-            if (verdict === "ready")
-                readyProviders.add(provider);
-            else if (verdict === "not-ready")
-                warns.push(`provider ${provider} reports not ready — check its credentials`);
-            else
-                warns.push(`could not verify provider ${provider} — the auth check did not run or its output was unreadable`);
-        }
+    if (provider === undefined) {
+        warns.push(`${model} names no provider — pi resolves it with its own default, tumwater cannot verify it`);
+        return { warns };
     }
-    const found = [...fails, ...warns].join("; ");
-    const resolvedPi = `${pairs.size} declared ${agree(pairs.size, "model", "models")} resolve${readyProviders.size > 0 ? ` and ${agree(readyProviders.size, "provider", "all providers")} ${[...readyProviders].sort().join(", ")} report ready` : ""}`;
+    // A Claude model routed to pi (plans/provider-concurrency.md "Routing a bare Claude model id
+    // to claude"): a named provider keeps it on pi, but since Anthropic's 2026-04-04
+    // third-party-harness change a Claude plan's limits cover only first-party tools, so it is
+    // billed per token even under a Claude subscription login — the bare `claude-…` form on the
+    // claude CLI uses the plan's included usage instead.
+    if (model?.startsWith("claude-")) {
+        warns.push(`${provider}/${model} runs on pi and is billed per token, not the Claude plan's included usage — use a bare claude-… id to route it to the claude CLI`);
+    }
+    const defs = providers?.get(provider);
+    const def = defs?.find((d) => d.id === model);
+    if (!def) {
+        const listedModels = await listed();
+        const fail = unresolvedModelFail(provider, model, defs, listedModels, modelsPath);
+        if (fail !== undefined)
+            return { warns, fail };
+    }
+    if (providers) {
+        const warning = cacheReadWarning(providers, provider, model, def);
+        if (warning !== undefined)
+            warns.push(warning);
+    }
+    const probe = await probeTierProvider(provider, auth, checkedProviders);
+    if (probe.warn !== undefined)
+        warns.push(probe.warn);
+    return { warns, ready: probe.ready };
+}
+/** One job: one routing note per non-pi backend in use, joined. */
+function routedTierNotes(routedModels) {
     // One routing note per non-pi backend in use, so an opencode-routed model is never labeled
     // as claude's. The opencode note also carries the design §2 caveat that a bare `opencode/…`
     // id always means the OpenCode CLI, never pi's built-in `opencode` gateway. Every note opens
@@ -260,13 +267,67 @@ export async function checkTierModels(root, modelsPath = piModelsPath(), auth =
                 ? routedNote(agent, n, "resolved by the codex backend, not pi's definitions")
                 : routedNote(agent, n, "resolved by the claude backend, not pi's definitions"));
     }
-    const routedText = routedNotes.length > 0 ? routedNotes.join("; ") : "";
+    return routedNotes.length > 0 ? routedNotes.join("; ") : "";
+}
+/** One job: assemble the final fail/warn/ok outcome from the collected verdicts. */
+function tierOutcome(fails, warns, pairsCount, readyProviders, routedText, ompNote, ompSet) {
+    const found = [...fails, ...warns].join("; ");
+    const resolvedPi = `${pairsCount} declared ${agree(pairsCount, "model", "models")} resolve${readyProviders.size > 0 ? ` and ${agree(readyProviders.size, "provider", "all providers")} ${[...readyProviders].sort().join(", ")} report ready` : ""}`;
     const base = fails.length === 0 && warns.length === 0
-        ? joinParts([pairs.size > 0 ? resolvedPi : "", routedText])
+        ? joinParts([pairsCount > 0 ? resolvedPi : "", routedText])
         : found;
     if (fails.length > 0)
         return failOutcome(`${base}${ompNote}`);
-    return (warns.length > 0 || ompVars.length > 0 ? warnOutcome : okOutcome)(`${base}${ompNote}`);
+    return (warns.length > 0 || ompSet ? warnOutcome : okOutcome)(`${base}${ompNote}`);
+}
+/** Declared model readiness — plans/model-tiers.md "Doctor" (part 7c/8): every model the config can
+ * put on a seam must resolve in pi's definitions, and its provider must report `ready` from the
+ * agent binary's own auth check. A strong tier pi cannot resolve would fail every review, and so
+ * every merge — the check exists so the operator finds out before the team does, mid-review. Pairs
+ * collected in the same sweep teamModelsFree prices: each tier's top-level selector (a string is
+ * default's), every enabled role's resolved pair (per-role overrides included; tier-name overrides
+ * resolve through configForRole), and the reviewer's while review is on. A pair with no model is
+ * pi's own default and out of scope; fallback pairs are the sibling check's (checkFallbackModel
+ * prices the cap pair). Levels: an unresolvable pair fails, a provider that is not ready warns
+ * (credentials are fixable without a config edit), a probe that cannot run warns rather than
+ * guesses, and a priced model whose cache reads declare $0 warns — the daily budget would
+ * undercount it (BUGS.md 2026-10-06). When one of PI_SMOL_MODEL / PI_SLOW_MODEL / PI_PLAN_MODEL is
+ * set the check also reports that tumwater does not read it — the variables are oh-my-pi's, pi
+ * ignores them, and with omp as `agentBin` they still reach omp through the inherited environment
+ * (src/pi/pi-backend.ts, built on src/process/run-marker.ts's backendBaseEnv) — pointing at the
+ * tier keys that do the same job (`model.small` / `model.strong`). `auth` is injectable so tests
+ * need no pi on PATH; `env` so the PI_* branches stay hermetic. The inline jobs are split into
+ * the module-private helpers `collectTierPairs`, `ompTierNote`, `readTierProviders`,
+ * `resolveTierPair`, `unresolvedModelFail`, `cacheReadWarning`, `probeTierProvider`,
+ * `routedTierNotes` and `tierOutcome` so each is found by name. */
+export async function checkTierModels(root, modelsPath = piModelsPath(), auth = (provider) => piProviderAuth(loadConfigSafe(root).config ?? defaultConfig(), provider), env = process.env, listModels = () => piListedModels(loadConfigSafe(root).config ?? defaultConfig(), envPath(), AUTH_CHECK_TIMEOUT_MS, root)) {
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
+    // Asked lazily and at most once: only a pair models.json does not declare needs the listing.
+    let listing;
+    const listed = () => (listing ??= listModels());
+    const { pairs, routedModels } = collectTierPairs(config);
+    const { set: ompSet, note: ompNote } = ompTierNote(env);
+    if (pairs.size === 0 && routedModels.size === 0)
+        return (ompSet ? warnOutcome : okOutcome)(`${PHRASE_NO_MODELS_DECLARED}${ompNote}`);
+    const providers = await readTierProviders(modelsPath, pairs, listed);
+    const fails = [];
+    const warns = [];
+    if (pairs.size > 0 && !providers)
+        return warnOutcome(`${PHRASE_CANNOT_READ_MODELS}${modelsPath}${ompNote}`);
+    const readyProviders = new Set();
+    const checkedProviders = new Set();
+    for (const { provider, model } of pairs.values()) {
+        const result = await resolveTierPair(provider, model, providers, listed, auth, checkedProviders, modelsPath);
+        warns.push(...result.warns);
+        if (result.fail !== undefined)
+            fails.push(result.fail);
+        if (result.ready === true)
+            readyProviders.add(provider);
+    }
+    const routedText = routedTierNotes(routedModels);
+    return tierOutcome(fails, warns, pairs.size, readyProviders, routedText, ompNote, ompSet);
 }
 /** `gh` readiness for the opt-in `feedback` observer (plans/feedback-role.md "Shape" → "Part 1"):
  * the role files issues as the operator's GitHub login through `gh`, so doctor confirms `gh`
@@ -289,3 +350,26 @@ export async function checkFeedbackFiling(root, pathEnv = envPath(), probe = (ar
         return failOutcome("gh is not authenticated — run `gh auth login` — the feedback role files issues as your GitHub login");
     return okOutcome("gh present and authenticated — the feedback role can file issues on znation/tumwater");
 }
+/** The `image input` row (plans/image-input.md "Surfaces", part 5/5): which enabled roles run
+ * on a model that cannot read images, and where each reroutes an image prompt — or that no
+ * usable reroute exists. Re-added probe-free by Subtract part 1d/6 after part 5f/6 deleted the
+ * probe-backed row: it reads roleImageInfo (the same resolver the status rows, role page, and
+ * submit gate share) rather than spawning a backend, so doctor and the surfaces cannot drift on
+ * who is text-only. No alert when none is (imageInput true or null — an unknown pair is not
+ * counted as text-only, mirroring the submit gate and the `models for each tier` stance). */
+export function checkImageInput(root, modelsPath = piModelsPath(), listed = readPiListedModels(root)) {
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
+    const textOnly = runnerIds(config).filter((role) => roleImageInfo(config, role, modelsPath, listed).imageInput === false);
+    if (textOnly.length === 0)
+        return okOutcome("every enabled role reads images");
+    const noTarget = textOnly.filter((role) => {
+        const rr = roleImageInfo(config, role, modelsPath, listed).imageReroute;
+        return rr === null || rr === "";
+    });
+    if (noTarget.length > 0)
+        return warnOutcome(`${noTarget.join(", ")} ${agree(noTarget.length, "runs", "run")} on models that can't read images and ${agree(noTarget.length, "has", "have")} no reroute target — a run that reads an image fails, and image attachments to these roles are refused. Declare image input on a vision model in pi's models.json, or point a tier at one.`);
+    const targets = new Set(textOnly.map((role) => roleImageInfo(config, role, modelsPath, listed).imageReroute ?? ""));
+    return okOutcome(`${textOnly.join(", ")} ${agree(textOnly.length, "runs", "run")} on models that can't read images — image prompts rerun on ${[...targets].join(", ")}.`);
+}

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

@@ -1,9 +1,9 @@
 import { eventsSince } from "../events/event-window.js";
-import { isNotifyFailure } from "../events/notify.js";
+import { isNotifyFailure } from "../events/event-notify.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";
+import { okOutcome, warnOutcome } from "./doctor-outcome.js";
 /** How far back the `notify` check looks for failed pages: a day, fixed. An opinionated
  * default with no knob, like STALE_BUG_DAYS: long enough that a transient hook failure shows
  * up, short enough that a page that did not go through is still the operator's business. */

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

@@ -1,7 +1,7 @@
 import os from "node:os";
 import path from "node:path";
 import { childEnv } from "../process/process.js";
-import { AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS, boundedProbe } from "./probe.js";
+import { AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS, boundedProbe } from "./doctor-probe.js";
 import { opencodeBackend, opencodeSpillDir } from "../agent/opencode/opencode-backend.js";
 import { opencodeModelFree, opencodeModelKey, readOpencodeCache } from "../agent/opencode/opencode-catalog.js";
 import { formatDate } from "../text/datetime.js";
@@ -9,7 +9,7 @@ import { opencodeDbPath } from "../paths.js";
 import { envPath, isDirectory, readTextOrNull, statOrNull, treeBytes } from "../files/files.js";
 import { formatBytes, tokenWindowLabel } from "../text/format.js";
 import { escapeRegExp } from "../text/text.js";
-import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
+import { failOutcome, okOutcome, warnOutcome } from "./doctor-outcome.js";
 import { 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 and tier-models checks stay there):
@@ -19,8 +19,9 @@ import { loadConfigForCheck, opencodeSeamsInUse, seamedModels, } from "./doctor-
  * 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) come from
- * doctor-model-checks.ts, the AUTH_CHECK_* probe budgets from probe.ts, and the shared report
- * contract (CheckOutcome) from outcome.ts, as the other doctor-* modules do. */
+ * doctor-model-checks.ts, the AUTH_CHECK_* probe budgets from doctor-probe.ts, and the
+ * shared report contract (CheckOutcome) from doctor-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

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

@@ -2,12 +2,13 @@ import fs from "node:fs";
 import path from "node:path";
 import { worktreesDir } from "../paths.js";
 import { pidAlive } from "../process/process.js";
+import { rootToken } from "../process/run-marker.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";
+import { failOutcome, okOutcome, warnOutcome } from "./doctor-outcome.js";
 /** The orphan-process check of `tumwater doctor`, split out of doctor.ts: it is the one
  * doctor check that inspects the operating system's process table (argv, cwd, parent-child
  * tree) rather than the repo's own files, so it carries a different shape of logic — path
@@ -92,6 +93,36 @@ function harnessGone(marker) {
     const m = /^(\d+)-/.exec(marker);
     return m ? !pidAlive(Number(m[1])) : null;
 }
+/** The repo-identity token in a run marker's third dash segment — the team root tag
+ * `makeRunMarker` stamps when it knows one — or null for a rootless two-segment mark
+ * (`<pid>-<hex>`, or a torn or foreign value with no third segment): there is no evidence of
+ * which checkout's harness minted it. */
+export function markRootToken(mark) {
+    const third = mark.split("-")[2];
+    return third === undefined ? null : third;
+}
+/** The repo-identity token `makeRunMarker` stamps into a team-rooted mark — the same `rootToken`
+ * run-marker.ts mints, re-exported here so the orphan scan can spell this root's side of the
+ * comparison without importing process/run-marker. */
+export { rootToken };
+/** ps's elapsed-time field (`[[D-]HH:]MM:SS`, the string the doctor line already prints) in
+ * milliseconds, the minimum-age gate the automatic reap uses so a just-leaked — still
+ * possibly owned — process is not killed. Any shape that does not parse, or that carries an
+ * out-of-range minute or second, reads 0: the conservative reading that keeps the reap from
+ * acting on uncertain evidence. */
+export function parseEtimeMs(etime) {
+    const m = /^(?:\d+-)?(?:(\d+):)?(\d{1,2}):(\d{2})$/.exec(etime.trim());
+    if (!m)
+        return 0;
+    const hh = Number(m[1] ?? 0);
+    const mm = Number(m[2]);
+    const ss = Number(m[3]);
+    if (mm > 59 || ss > 59)
+        return 0;
+    const days = /^(\d+)-/.exec(etime.trim());
+    const d = days ? Number(days[1]) : 0;
+    return ((d * 24 + hh) * 3600 + mm * 60 + ss) * 1000;
+}
 /** A parent pid → child pids map of the table. */
 function childrenOf(rows) {
     const children = new Map();
@@ -111,8 +142,10 @@ function shownCommand(command, root) {
     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) {
+ * disagree about the set. Exported so the always-on orphan alert feed (src/ui/alert-feeds.ts)
+ * runs the exact same scan the doctor row reads — the alert and the row cannot drift on the
+ * orphan set. */
+export async function findOrphans(root, probe) {
     const roots = rootSpellings(root);
     let rows;
     try {
@@ -148,12 +181,24 @@ async function findOrphans(root, probe) {
             // Best-effort per the probe contract: argv and cwd still carry the check alone.
         }
     }
+    const ours = rootToken(root);
     const byMark = new Set();
     for (const r of parentless) {
         if (byArgv.has(r.pid))
             continue;
-        const verdicts = (marks.get(r.pid) ?? []).map(harnessGone);
-        if (verdicts.length > 0 && verdicts.every((v) => v === true))
+        const rMarks = marks.get(r.pid) ?? [];
+        const verdicts = rMarks.map(harnessGone);
+        // A dead-marked process is this checkout's only when no mark names a different root: a
+        // token that is present and not `ours` proves another checkout's harness stamped that
+        // process, and signalling it would break the "never signal a process not attributable"
+        // rule (BUGS.md, "Reap the doctor's orphans, part 1/3"). A rootless mark keeps today's
+        // report — whatever started it, nothing else will reap it.
+        if (verdicts.length > 0 &&
+            verdicts.every((v) => v === true) &&
+            rMarks.every((m) => {
+                const t = markRootToken(m);
+                return t === null || t === ours;
+            }))
             byMark.add(r.pid);
     }
     const orphans = parentless.filter((r) => {
@@ -199,16 +244,17 @@ async function findOrphans(root, probe) {
  * 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);
+/** The orphan-problem sentence for the standing alert feed, shared with checkOrphans so the
+ * alert and the doctor row cannot drift on the wording: the count, each listed orphan's pid,
+ * age, cpu and command (with its descendant count and the run mark that caught it), and the
+ * nothing-reaps-these remediation. null when the scan errored or found no orphans. Public so
+ * the feed (src/ui/alert-feeds.ts) can stage a scan and get exactly the row's message. */
+export function orphanFailDetail(root, scan) {
     if ("error" in scan)
-        return warnOutcome(`could not scan the process table — ${scan.error}`);
+        return null;
     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");
-    }
+    if (orphans.length === 0)
+        return null;
     const children = childrenOf(rows);
     const listed = orphans.slice(0, ORPHANS_LISTED_MAX).map((r) => {
         const n = descendantPids(children, r.pid).length;
@@ -221,9 +267,22 @@ export async function checkOrphans(root, probe = systemProcessProbe) {
     });
     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` : ""}` +
+    return `${count}: ${listed.join("; ")}${more > 0 ? `; and ${more} more` : ""}` +
         " — 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)` : ""));
+        (cwdProblem !== null ? ` (process cwds unreadable — ${cwdProblem}; argv matched only)` : "");
+}
+/** The doctor's `orphans` row. */
+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 { orphans, 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");
+    }
+    return failOutcome(orphanFailDetail(root, scan));
 }
 const systemSignals = {
     kill: (pid, signal) => void process.kill(pid, signal),
@@ -291,6 +350,20 @@ async function killTrees(root, rows, chosen, signals) {
     }
     return { killed, failed };
 }
+/** The `pid N (+N descendant) command` line per killed tree and the `could not kill` line per
+ * refused tree, in the read the reapers' best-effort warning logs — the one shape both
+ * reapPreviousTeamOrphans and reapAttributableOrphans report, so the two cannot drift on the
+ * itemized wording. Callers join `[...items, ...refused]` with "; " behind their own verb
+ * phrase. */
+function orphanKillReportLines(killed, failed) {
+    return {
+        items: killed.map((k) => {
+            const tree = k.descendants > 0 ? ` (+${plural(k.descendants, "descendant")})` : "";
+            return `pid ${k.pid}${tree} ${k.command}`;
+        }),
+        refused: failed.map((f) => `could not kill pid ${f.pid}: ${f.reason}`),
+    };
+}
 /** 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
@@ -314,11 +387,7 @@ export async function reapPreviousTeamOrphans(root, previousPid, probe = systemP
         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}`);
+        const { items, refused } = orphanKillReportLines(killed, failed);
         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;
@@ -327,3 +396,34 @@ export async function reapPreviousTeamOrphans(root, previousPid, probe = systemP
         return 0;
     }
 }
+/** How long an orphan must have been running before the automatic reap may kill it: a young
+ * orphan may still be a live run's process that findOrphans read as parentless mid-hand-off,
+ * and ten minutes is far longer than any such attribution would hold. The operator's
+ * `--kill-orphans`/dashboard/TUI click bypasses this — doctors judge with their eyes. */
+const ORPHAN_REAP_MIN_AGE_MS = 10 * 60 * 1000;
+/** The orchestrator's once-per-interval sweep of the orphans `checkOrphans` already reports:
+ * kill the same set the operator's `--kill-orphans` kills, once each is old enough that no
+ * live run can still own it. Reuses findOrphans' attribution and killTrees' signal-and-wait,
+ * so the automatic reap cannot drift from the doctor row or the operator kill and never
+ * signals a process findOrphans does not list. An unreadable table, or no old-enough orphan,
+ * kills nothing and logs nothing; it never throws. Returns the number of orphan trees killed. */
+export async function reapAttributableOrphans(root, probe = systemProcessProbe, signals = systemSignals) {
+    try {
+        const scan = await findOrphans(root, probe);
+        if ("error" in scan)
+            return 0;
+        const chosen = scan.orphans.filter((r) => parseEtimeMs(r.etime) >= ORPHAN_REAP_MIN_AGE_MS);
+        if (chosen.length === 0)
+            return 0;
+        const { killed, failed } = await killTrees(root, scan.rows, chosen, signals);
+        if (killed.length === 0)
+            return 0;
+        const { items, refused } = orphanKillReportLines(killed, failed);
+        warnEventBestEffort(root, TUMWATER_SOURCE, `reaped ${plural(killed.length, "orphaned process", "orphaned processes")}: ` +
+            [...items, ...refused].join("; "));
+        return killed.length;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/src/doctor/{outcome.js → doctor-outcome.js}

@@ -9,6 +9,13 @@
 export function okOutcome(detail) {
     return { level: "ok", detail };
 }
+/** The doctor's stand-down on a missing or unreadable tumwater.json: an ok outcome saying
+ * there is nothing to verify, because the config check reports the broken file itself. Shared
+ * by the four checks that skip their walk when config is unavailable, so the message reads
+ * identically across them. */
+export function noConfigOutcome() {
+    return okOutcome("no readable tumwater.json — nothing to verify");
+}
 export function warnOutcome(detail) {
     return { level: "warn", detail };
 }

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

@@ -1,5 +1,5 @@
 import { childEnv } from "../process/process.js";
-import { boundedProbe, AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS } from "./probe.js";
+import { boundedProbe, AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS } from "./doctor-probe.js";
 import { parseJsonObject } from "../files/json-object.js";
 import { envPath } from "../files/files.js";
 import { resolveBackendBin } from "../pi/pi-bin.js";
@@ -12,7 +12,7 @@ import { parsePiModelImages, parsePiModelTable, writePiListedModels } from "../p
  * a crash, so readiness is read from the body alone and a reply that did not run or does not
  * parse is the only "unknown" (never not-ready, which would blame credentials). Never throws;
  * every failure mode ends on "unknown". The bounded subprocess is the shared boundedProbe
- * (probe.ts), also used by the claude probes. */
+ * (doctor-probe.ts), also used by the claude probes. */
 export async function piProviderAuth(config, provider, pathEnv = envPath(), timeoutMs = AUTH_CHECK_TIMEOUT_MS) {
     const resolved = resolveBackendBin(config);
     const result = await boundedProbe(resolved.bin, ["auth", "check", "--provider", provider, "--json"], childEnv({ PATH: pathEnv }), timeoutMs, AUTH_CHECK_MAX_OUTPUT_BYTES);

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

@@ -1,7 +1,7 @@
 import path from "node:path";
-import { readTextOrNull } from "../files/files.js";
+import { readRegularTextOrNull } from "../files/files.js";
 import { PRINCIPLES_MAX_CHARS } from "../prompt/principles.js";
-import { okOutcome, warnOutcome } from "./outcome.js";
+import { okOutcome, warnOutcome } from "./doctor-outcome.js";
 /** Doctor check for PRINCIPLES.md's injection cap. readPrinciples caps the trimmed text at
  * PRINCIPLES_MAX_CHARS for every prompt's <principles> block, and principleBullets keeps only
  * its leading bullets; a file over the cap loses its tail (and a long header eats bullet
@@ -9,7 +9,7 @@ import { okOutcome, warnOutcome } from "./outcome.js";
  * truncate, naming the trimmed count, the cap, the marker, and the fix. Read-only, like every
  * doctor check — it never edits PRINCIPLES.md. */
 export function checkPrinciples(root) {
-    const raw = readTextOrNull(path.join(root, "PRINCIPLES.md"));
+    const raw = readRegularTextOrNull(path.join(root, "PRINCIPLES.md"));
     if (raw === null)
         return okOutcome("no PRINCIPLES.md");
     const length = raw.trim().length;