tumwater 0.1.2 → 0.2.0

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

@@ -1,18 +1,34 @@
-import { spawn } from "node:child_process";
-import { childEnv, releaseChildHandles, signalTree } from "../process/process.js";
+// vocabulary: plain
+import fs from "node:fs";
+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 { readTextOrNull, statOrNull } from "../files/files.js";
 import { enabledRoleIds, defaultConfig, loadConfigSafe } from "../config/config.js";
-import { configForRole, fallbackPair, reviewConfig, tierModel } from "../config/config-views.js";
-import { cacheReadUnpriced, fallbackModelPair, piModelsPath, readPiProviders } from "../pi/pi-models.js";
+import { configForRole, resolvedAgentConfig } from "../config/config-views.js";
+import { fallbackPair, resolveTierFallbacks, seamsInUse, tierChainSteps } from "../config/config-fallbacks.js";
+import { cacheReadUnpriced, fallbackModelPair, piModelsPath, piPairFree, piProviderBaseUrl, readPiProviders } from "../pi/pi-models.js";
 import { MODEL_TIERS } from "../config/config-schema.js";
-import { isAgentId, routeModel } from "../config/model-selector.js";
-import { claudeBackend } from "../agent/claude/claude-backend.js";
+import { isAgentId } from "../config/model-selector.js";
+import { imageReroute, seamImageInput } from "../agent/image-input.js";
+import { modelLabel, usesPiModels } from "../agent/backend-traits.js";
+import { agentBackend } from "../agent/agent-backend.js";
+import { imageProbeEntryFresh, imageProbeKey, readImageProbeCache, runImageProbe, writeImageProbeCache, } from "./image-probe.js";
+import { claudeBackend, claudeConfigDir } from "../agent/claude/claude-backend.js";
 import { claudeAuthUsesSubscription, parseClaudeAuthStatus, readClaudeAccount } from "../agent/claude/claude-account.js";
 import { claudeEnv } from "../agent/claude/claude-env.js";
 import { parseJsonObject } from "../files/json-object.js";
 import { envPath } from "../files/files.js";
+import { modelPairName, pairDailyCost } from "../budget/budget.js";
+import { usd, usdCap } from "../text/format.js";
+import { loadLoopStates } from "./doctor-holds.js";
 import { resolveAgentBin } from "../pi/pi-bin.js";
 import { agree } from "../text/phrases.js";
-import { formatTime } from "../text/datetime.js";
+import { formatDate, formatTime } from "../text/datetime.js";
 import { belowNodeFloor } from "../version.js";
 import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
 /** The doctor's model-readiness checks, split out of doctor-checks.ts (whose environment and
@@ -27,16 +43,18 @@ import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
  * checkInit already fails on a broken config, so a model check only reports that it could not
  * run. One home for the guard and its wording, shared by checkFallbackModel and
  * checkTierModels (the same shape doctor-backlog.ts's readDocChecked uses for unreadable
- * files). */
+ * files). The config or the warn outcome, so each check's one-line guard — `const config =
+ * loadConfigForCheck(root); if ("level" in config) return config;` — is all a check needs to
+ * read its config instead of repeating a load-and-unwrap prologue. */
 function loadConfigForCheck(root) {
     const { config, error } = loadConfigSafe(root);
     if (config === undefined)
-        return { outcome: warnOutcome(`cannot check — ${error}`) };
-    return { config };
+        return warnOutcome(`cannot check — ${error}`);
+    return config;
 }
 /** Fallback model readiness — the daily-cost budget's third state (plans/fallback-model.md): with
  * `fallbackModel` set, pi's definitions must price that pair at zero or the gate refuses it and
- * role loops pause at the cap exactly as if no fallback existed. That refusal is the right runtime
+ * roles pause at the cap exactly as if no fallback existed. That refusal is the right runtime
  * behavior (spend must never climb past the cap), but a typo'd id would otherwise surface only
  * after the day's budget is already spent — so doctor checks it up front, before the operator
  * needs it. Read-only: it inspects pi's definitions file, never pi or the network. A price is not
@@ -45,16 +63,15 @@ function loadConfigForCheck(root) {
  * verified" — unless the running orchestrator has published that its breaker demoted the pair
  * (`demoted`, from orchestrator.json; runDoctor passes it only while that orchestrator is alive),
  * which warns with the failure count and the next probe time. No fallbackModel configured is
- * informational, not a warning — plenty of fleets intend to stop at the cap. `modelsPath` is
+ * informational, not a warning — plenty of teams intend to stop at the cap. `modelsPath` is
  * injectable so tests need no real pi install. */
 export function checkFallbackModel(root, modelsPath = piModelsPath(), demoted = null) {
-    const loaded = loadConfigForCheck(root);
-    if ("outcome" in loaded)
-        return loaded.outcome;
-    const { config } = loaded;
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
     const declared = fallbackPair(config);
     if (!declared)
-        return okOutcome("none configured — role loops pause at the cap");
+        return okOutcome("none configured — roles pause at the cap");
     // A pair missing either half would fall through to pi's own (unverified) default, so it can
     // never be free; naming that case beats rendering a bare "?/model". The free branch names
     // the price-resolved pair (a map with no `default` entry borrows another tier's), while the
@@ -64,124 +81,134 @@ export function checkFallbackModel(root, modelsPath = piModelsPath(), demoted =
     if (free) {
         const name = nameOf(free);
         if (demoted)
-            return warnOutcome(`${name} is priced at zero but not serving — the running fleet demoted it after ${demoted.failures} consecutive failed ticks, so role loops pause at the cap; one probe tick retries it from ${formatTime(new Date(demoted.probeAt))}`);
+            return warnOutcome(`${name} is priced at zero but not serving — the running team demoted it after ${demoted.failures} consecutive failed runs, so roles pause at the cap; one probe run retries it from ${formatTime(new Date(demoted.probeAt))}`);
         return okOutcome(`${name} — priced at zero (cost n/a), serving not verified`);
     }
-    return warnOutcome(`${nameOf(declared)} is not priced at zero in ${modelsPath} — at the cap role loops pause instead of switching`);
+    return warnOutcome(`${nameOf(declared)} is not priced at zero in ${modelsPath} — at the cap roles pause instead of switching`);
+}
+/** Whether a local server answers `GET <url>`: node's built-in fetch with a short timeout, false
+ * on any failure — doctor is a pre-flight, not a place to wait out a hung server. */
+async function probeModels(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+const isLocalUrl = (url) => {
+    try {
+        const host = new URL(url).hostname;
+        return host === "127.0.0.1" || host === "localhost";
+    }
+    catch {
+        return false;
+    }
+};
+/** The `fallback chain` check: one fragment per step of every tier's chain saying whether the
+ * step can run now — a local pi server that does not answer (warn), a step whose own daily cap is
+ * spent, a free pair, a claude step with its billing, or a priced pair. Reads config, pi's
+ * models.json and the loop states; only a pi step on 127.0.0.1/localhost makes a network
+ * request. `probe` is injectable so tests need no real server. */
+export async function checkFallbackChain(root, modelsPath = piModelsPath(), probe = probeModels) {
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
+    const steps = tierChainSteps(config);
+    if (steps.length === 0)
+        return okOutcome("none configured");
+    const states = loadLoopStates(root, config);
+    const providers = readPiProviders(modelsPath);
+    const account = readClaudeAccount(root);
+    const now = Date.now();
+    let down = false;
+    const fragments = [];
+    for (const { tier, step, pair } of steps) {
+        // A provider that names a backend other than pi (claude today; opencode from part 2) never
+        // asks pi for a base URL or runs pi's price probe — only a pi step may.
+        const nonPiBackend = isAgentId(pair.provider) && pair.provider !== "pi";
+        const base = !nonPiBackend && pair.provider ? piProviderBaseUrl(modelsPath, pair.provider) : null;
+        const local = base !== null && isLocalUrl(base);
+        const up = local ? await probe(`${base}/models`) : null;
+        const cap = pair.maxDailyCostUsd;
+        const spent = cap !== undefined ? pairDailyCost(states, modelPairName(pair), now) : 0;
+        let verdict;
+        if (up === false) {
+            down = true;
+            verdict = `not running (GET ${base}/models failed)`;
+        }
+        else if (cap !== undefined && spent >= cap) {
+            verdict = `cap reached (${usd(spent)}/${usdCap(cap)})`;
+        }
+        else if (nonPiBackend) {
+            verdict = `claude ${pair.extraUsage ? "extra usage" : (account?.billing ?? "billing unknown")}`;
+        }
+        else if (piPairFree(providers, pair.provider, pair.model, account)) {
+            verdict = up ? "free · server up" : "free";
+        }
+        else {
+            verdict = cap !== undefined ? `priced, ${usd(spent)}/${usdCap(cap)} today` : "priced, team cap only";
+        }
+        fragments.push(`${tier} ${step + 1}: ${pair.provider ?? "?"}/${pair.model ?? "?"} — ${verdict}`);
+    }
+    const detail = fragments.join("; ");
+    return down ? warnOutcome(detail) : okOutcome(detail);
 }
 /** How long the credential probe may take before it counts as unknown — a doctor run is a
  * pre-flight, not a place to wait out a hung backend. */
-const AUTH_CHECK_TIMEOUT_MS = 15_000;
+export const AUTH_CHECK_TIMEOUT_MS = 15_000;
 /** Cap on the probe's captured stdout. The auth reply is a tiny JSON object; a binary whose
  * output is a runaway log (or a pipe held open with no EOF) must not grow `out` without bound.
  * Sibling probes share EXEC_MAX_BUFFER, but 1 MiB is already orders of magnitude past any real
  * reply, so it is the tighter bound here. Over it the probe kills the child and reads as
  * unknown. */
-const AUTH_CHECK_MAX_OUTPUT_BYTES = 1024 * 1024;
-/** Every model a seam can run, paired with its backend (plans/agent-backends.md "Config"):
- * the top-level tiers (routed so a `claude/<id>` selector names its backend), every enabled
- * role's resolved pair, and the reviewer's while review is on. Deduplicated by
+export const AUTH_CHECK_MAX_OUTPUT_BYTES = 1024 * 1024;
+/** Every model a seam can run, paired with its backend (plans/agent-backends.md "Config"): the
+ * distinct pairs of the one seamsInUse list — every enabled role, the review gate, the
+ * resolver, the director, and each tier's budget/model-failure fallback — so a claude or pi
+ * pair that exists only as a fallback is checked exactly like a primary one. Deduplicated by
  * backend/provider/model, so a model reached through several surfaces is checked once. */
 function seamPairs(config) {
     const pairs = new Map();
-    const add = (pair) => {
-        if (pair.model === undefined)
-            return;
-        pairs.set(`${pair.agent ?? ""}\0${pair.provider ?? ""}\0${pair.model}`, pair);
-    };
-    for (const tier of MODEL_TIERS) {
-        const sel = tierModel(config, tier);
-        if (!sel)
+    for (const seam of seamsInUse(config)) {
+        if (seam.model === undefined)
             continue;
-        const routed = routeModel(sel.provider, sel.model, config.agent ?? "pi", tier);
-        add({
-            agent: routed.agent,
-            provider: routed.agent === "pi" ? sel.provider : undefined,
-            model: routed.model,
-            thinking: sel.thinking,
+        pairs.set(`${seam.agent ?? ""}\0${seam.provider ?? ""}\0${seam.model}`, {
+            agent: seam.agent,
+            provider: seam.provider,
+            model: seam.model,
+            thinking: seam.thinking,
         });
     }
-    for (const role of enabledRoleIds(config)) {
-        const rc = configForRole(config, role);
-        add({ agent: rc.agent, provider: rc.provider, model: rc.model, thinking: rc.thinking });
-    }
-    if (config.review.enabled) {
-        const rv = reviewConfig(config);
-        add({ agent: rv.agent, provider: rv.provider, model: rv.model, thinking: rv.thinking });
-    }
     return [...pairs.values()];
 }
 /** Whether any seam runs on the claude backend — the doctor's claude checks stand down when
- * none does (a pi-only fleet reads no `~/.claude` state and spawns no claude). */
+ * none does (a pi-only team reads no `~/.claude` state and spawns no claude). */
 export function claudeSeamsInUse(config) {
     return seamPairs(config).some((pair) => pair.agent === "claude");
 }
-/** One bounded probe of an agent binary: `null` when the spawn threw, the child errored, the
- * deadline passed, or stdout overran the cap — every case the caller must read as "could not
- * check", never as a verdict. The child runs detached and at the deadline (or on overrun) its
- * whole process group is SIGKILLed and the promise settles, because `'close'` waits for the
- * stdio pipes and a grandchild holding them open would otherwise leave the promise pending past
- * the deadline and hang `tumwater doctor` (the same trap git-run.ts's bounded spawn closes for
- * git). `timeoutMs` is a test seam; production callers leave it at the default. */
-function boundedProbe(bin, args, env, timeoutMs) {
-    return new Promise((resolve) => {
-        let child;
-        try {
-            child = spawn(bin, args, {
-                cwd: process.cwd(),
-                // Detached so the deadline's signalTree reaches a grandchild too; stderr is ignored
-                // rather than piped, since nothing reads it and a full stderr pipe would block the
-                // child until the deadline.
-                detached: true,
-                stdio: ["ignore", "pipe", "ignore"],
-                env,
-            });
-        }
-        catch {
-            resolve(null);
-            return;
-        }
-        let out = "";
-        let bytes = 0;
-        let settled = false;
-        let timer;
-        const settle = (result) => {
-            if (settled)
-                return;
-            settled = true;
-            if (timer !== undefined)
-                clearTimeout(timer);
-            // Destroy the captured stdout and unref the process handle (releaseChildHandles): a
-            // grandchild that escaped the group and holds the pipe's write end would otherwise keep
-            // the harness's event loop alive though the probe already has its answer.
-            releaseChildHandles(child);
-            resolve(result);
-        };
-        // Deadline or runaway output: kill the whole group, tear down the handles, and settle —
-        // do not wait for a `'close'` the group may never deliver.
-        const abort = () => {
-            signalTree(child, "SIGKILL");
-            settle(null);
-        };
-        timer = setTimeout(abort, timeoutMs);
-        child.stdout?.on("data", (chunk) => {
-            out += chunk.toString("utf8");
-            bytes += chunk.length;
-            if (bytes > AUTH_CHECK_MAX_OUTPUT_BYTES)
-                abort();
-        });
-        child.on("error", () => settle(null));
-        child.on("close", (code) => settle({ code, stdout: out }));
-    });
+/** Whether any seam routes to opencode — the doctor's opencode checks stand down when none
+ * does (a pi-only team spawns no opencode and reads no opencode state). */
+export function opencodeSeamsInUse(config) {
+    return seamPairs(config).some((pair) => pair.agent === "opencode");
+}
+/** Whether any seam routes to the pi backend — the doctor's pi-extension row stands down when
+ * none does (an all-claude or all-opencode team reads no `~/.pi` state). Unlike the model-based
+ * seam consult, this scans the routed seams directly (not seamPairs' model-filtered view) so a
+ * default pi team — whose seams route to pi with pi's own default model and no explicit
+ * selector — still gets the row: that is the feature's main scenario. */
+export function piSeamsInUse(config) {
+    return seamsInUse(config).some((s) => s.agent === "pi");
 }
-/** The default credential probe: run the resolved agent binary's own auth check for one
- * provider and read `ready` out of its JSON. The binary resolves exactly as the spawn does
- * (resolveAgentBin — the same source a real tick would launch), so doctor tests the auth of
- * the pi it would actually run. Never throws; every failure mode lands on "unknown". The
- * bounded subprocess is boundedProbe above, shared with the claude probes. */
+/** The default credential probe: run the resolved agent binary's own auth check for one provider
+ * and read `ready` out of its JSON. The binary resolves exactly as the spawn does (resolveAgentBin
+ * — the same source a real tick would launch), so doctor tests the auth of the pi it would actually
+ * run. Never throws; every failure mode ends on "unknown". The bounded subprocess is the shared
+ * boundedProbe (probe.ts), also used by the claude probes. */
 export async function piProviderAuth(config, provider, pathEnv = envPath(), timeoutMs = AUTH_CHECK_TIMEOUT_MS) {
     const resolved = resolveAgentBin(config);
-    const result = await boundedProbe(resolved.bin, ["auth", "check", "--provider", provider, "--json"], childEnv({ PATH: pathEnv }), timeoutMs);
+    const result = await boundedProbe(resolved.bin, ["auth", "check", "--provider", provider, "--json"], childEnv({ PATH: pathEnv }), timeoutMs, AUTH_CHECK_MAX_OUTPUT_BYTES);
     if (result === null)
         return "unknown";
     if (result.code !== 0)
@@ -203,8 +230,18 @@ export async function piProviderAuth(config, provider, pathEnv = envPath(), time
  * so neither probes a different binary or environment than the other. */
 function claudeProbe(config, args, pathEnv, timeoutMs) {
     const resolved = claudeBackend.resolveBin(config);
-    const env = claudeEnv(childEnv({ PATH: pathEnv }), { quietTimeoutSeconds: 0 });
-    return boundedProbe(resolved.bin, args, env, timeoutMs);
+    // The configured team config dir must reach the probe's env the way a real run's does, or
+    // the auth/version rows would look in claude's default dir (usually ~/.claude) while a run
+    // with backends.claude.configDir writes and reads elsewhere — the very mismatch doctor exists
+    // to surface. Mirror backends.run's expansion: only claude accepts configDir, and unset leaves
+    // today's env byte-identical.
+    const configDir = resolvedAgentConfig(config, "claude").configDir;
+    const expandedConfigDir = configDir !== undefined ? claudeConfigDir(process.env, os.homedir(), configDir) : undefined;
+    const env = claudeEnv(childEnv({ PATH: pathEnv }), {
+        quietTimeoutSeconds: 0,
+        ...(expandedConfigDir !== undefined ? { configDir: expandedConfigDir } : {}),
+    });
+    return boundedProbe(resolved.bin, args, env, timeoutMs, AUTH_CHECK_MAX_OUTPUT_BYTES);
 }
 /** Run `claude auth status` under the same scrubbed environment a real run gets (claudeEnv),
  * or null when the probe could not run or its reply was unreadable. */
@@ -220,14 +257,13 @@ async function claudeAuthProbe(config, pathEnv, timeoutMs) {
  * names the billing the reply implies — the subscription type, or an API key — so an operator
  * telling subscription spend from API spend does not have to run the command themselves. A
  * probe that could not run or a reply this cannot read warns rather than guesses. Stands down
- * (ok) when no seam routes to claude, so a pi-only fleet spawns nothing. */
+ * (ok) when no seam routes to claude, so a pi-only team spawns nothing. */
 export async function checkClaudeAuth(root, pathEnv = envPath(), timeoutMs = AUTH_CHECK_TIMEOUT_MS) {
-    const loaded = loadConfigForCheck(root);
-    if ("outcome" in loaded)
-        return loaded.outcome;
-    const { config } = loaded;
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
     if (!claudeSeamsInUse(config))
-        return okOutcome("no claude seams configured");
+        return okOutcome("no model jobs run on claude");
     const auth = await claudeAuthProbe(config, pathEnv, timeoutMs);
     if (auth === null)
         return warnOutcome("could not check — `claude auth status` did not run or its output was unreadable");
@@ -239,25 +275,48 @@ export async function checkClaudeAuth(root, pathEnv = envPath(), timeoutMs = AUT
         : "API key";
     return okOutcome(`logged in — billing: ${billing}`);
 }
+/** The subscription-vs-API billing trap (plans/provider-concurrency.md §9 gap 6): an operator
+ * who exports `ANTHROPIC_API_KEY` for pi's `anthropic` provider will silently move every claude
+ * seam to API billing — claude prefers the key over a claude.ai login — and subscription seams
+ * stop counting as free. Doctor warns when the key is set, some seam routes to claude, and
+ * `claude auth status` reports a claude.ai login (the subscription the key would override). It
+ * stays silent (ok) when no seam runs on claude, when the key is unset, or when claude reports
+ * an API-key login (then there is no subscription to lose). `env` is injectable so the check
+ * stays hermetic; a probe that cannot run warns rather than guesses like checkClaudeAuth. */
+export async function checkAnthroApiKey(root, env = process.env, pathEnv = envPath(), timeoutMs = AUTH_CHECK_TIMEOUT_MS) {
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
+    if (!claudeSeamsInUse(config))
+        return okOutcome("no model jobs run on claude");
+    const apiKey = env.ANTHROPIC_API_KEY;
+    if (apiKey === undefined || apiKey === "")
+        return okOutcome("no ANTHROPIC_API_KEY set");
+    const auth = await claudeAuthProbe(config, pathEnv, timeoutMs);
+    if (auth === null)
+        return warnOutcome("could not check — `claude auth status` did not run or its output was unreadable");
+    if (!auth.loggedIn || !claudeAuthUsesSubscription(auth))
+        return okOutcome("ANTHROPIC_API_KEY is set, but claude reports no claude.ai login");
+    return warnOutcome("ANTHROPIC_API_KEY is set while claude reports a claude.ai login — model jobs on claude will bill the API key, not the subscription; unset it or route every anthropic model job on pi explicitly");
+}
 /** The dotted version in `claude --version`'s output, or undefined when it names none. */
 function parseClaudeCliVersion(output) {
     return /(\d+\.\d+\.\d+)/.exec(output)?.[1];
 }
 /** claude CLI-version readiness (plans/agent-backends.md finding 9): an installed CLI below a
- * configured model's minimum fails or misprices that model, and fleet runs disable the
+ * configured model's minimum fails or misprices that model, and team runs disable the
  * auto-updater, so the version an operator has is the version ticks run. Fails below the
  * highest floor among the claude-routed models, naming which model needs it; an ok detail
  * prints the installed version and the floor it satisfied (or no floor when none applies).
  * The `off`/`minimal` thinking clamp is noted here too, since this check already has the
  * claude seams in hand. Stands down when no seam routes to claude. */
 export async function checkClaudeVersion(root, pathEnv = envPath(), timeoutMs = AUTH_CHECK_TIMEOUT_MS) {
-    const loaded = loadConfigForCheck(root);
-    if ("outcome" in loaded)
-        return loaded.outcome;
-    const { config } = loaded;
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
     const seams = seamPairs(config).filter((pair) => pair.agent === "claude" && pair.model !== undefined);
     if (seams.length === 0)
-        return okOutcome("no claude seams configured");
+        return okOutcome("no model jobs run on claude");
     // The floor each configured model needs; a model the adapter does not gate contributes none.
     const floors = new Map();
     for (const seam of seams) {
@@ -289,39 +348,41 @@ export async function checkClaudeVersion(root, pathEnv = envPath(), timeoutMs =
         return failOutcome(`claude ${found} is older than ${required} required by ${neededBy} — run \`claude update\``);
     return okOutcome(`claude ${found} (>= ${required} for ${neededBy})${clampNote}`);
 }
-/** 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 landing — the check exists so the operator finds out before the
- * fleet does, mid-review. Pairs collected in the same sweep fleetModelsFree 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 agentBaseEnv) — 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. */
+/** 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 agentBaseEnv) — 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) {
-    const loaded = loadConfigForCheck(root);
-    if ("outcome" in loaded)
-        return loaded.outcome;
-    const { config } = loaded;
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
     const pairs = new Map();
-    const claudeModels = new Set();
+    // Routed (non-pi) models keyed by the backend they resolved to, so the routing note names
+    // each backend correctly; opencode is not claude.
+    const routedModels = new Map();
     const add = (agent, provider, model) => {
         if (model === undefined)
             return;
         // A non-pi backend's models are not in pi's definitions, so they are not swept for
-        // resolution or auth here — the claude checks cover them instead.
+        // resolution or auth here — the backend's own checks cover them instead.
         if (agent !== undefined && agent !== "pi") {
-            claudeModels.add(model);
+            let models = routedModels.get(agent);
+            if (models === undefined)
+                routedModels.set(agent, (models = new Set()));
+            models.add(model);
             return;
         }
         pairs.set(`${provider ?? ""}/${model}`, { provider, model });
@@ -332,8 +393,8 @@ export async function checkTierModels(root, modelsPath = piModelsPath(), auth =
     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 && claudeModels.size === 0)
-        return (ompVars.length === 0 ? okOutcome : warnOutcome)(`no models declared — every seam uses pi's own default${ompNote}`);
+    if (pairs.size === 0 && routedModels.size === 0)
+        return (ompVars.length === 0 ? okOutcome : warnOutcome)(`no models declared — every model job uses pi's own default${ompNote}`);
     const providers = readPiProviders(modelsPath);
     const fails = [];
     const warns = [];
@@ -342,7 +403,7 @@ export async function checkTierModels(root, modelsPath = piModelsPath(), auth =
     if (providers) {
         const reserved = [...providers.keys()].filter(isAgentId);
         if (reserved.length > 0)
-            warns.push(`pi's definitions (${modelsPath}) declare provider ${reserved.map((p) => `"${p}"`).join(", ")} — the name is reserved for an agent backend, so selectors under it never reach pi`);
+            warns.push(`pi's definitions (${modelsPath}) declare provider ${reserved.map((p) => `"${p}"`).join(", ")} — the name is reserved for an agent backend, so model ids under it never reach pi`);
     }
     if (pairs.size > 0 && !providers)
         return warnOutcome(`cannot check — could not read pi's model definitions at ${modelsPath}${ompNote}`);
@@ -353,6 +414,14 @@ export async function checkTierModels(root, modelsPath = piModelsPath(), auth =
             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);
         if (!defs) {
             fails.push(`provider ${provider} is not in pi's definitions (${modelsPath})`);
@@ -384,13 +453,336 @@ export async function checkTierModels(root, modelsPath = piModelsPath(), auth =
     }
     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` : ""}`;
-    const claudeNote = claudeModels.size > 0
-        ? `${claudeModels.size} claude-routed ${agree(claudeModels.size, "model", "models")} — resolved by the claude backend, not pi's definitions`
-        : "";
+    // 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.
+    const routedNotes = [];
+    for (const [agent, models] of routedModels) {
+        const n = models.size;
+        routedNotes.push(agent === "opencode"
+            ? `${n} opencode-routed ${agree(n, "model", "models")} — \`opencode/…\` ids run on the OpenCode CLI, and pi's built-in \`opencode\` provider is not reachable from tumwater`
+            : `${n} claude-routed ${agree(n, "model", "models")} — resolved by the claude backend, not pi's definitions`);
+    }
+    const routedText = routedNotes.length > 0 ? routedNotes.join("; ") : "";
     const base = fails.length === 0 && warns.length === 0
-        ? [pairs.size > 0 ? resolvedPi : "", claudeNote].filter(Boolean).join("; ")
+        ? [pairs.size > 0 ? resolvedPi : "", routedText].filter(Boolean).join("; ")
         : found;
     if (fails.length > 0)
         return failOutcome(`${base}${ompNote}`);
     return (warns.length > 0 || ompVars.length > 0 ? warnOutcome : okOutcome)(`${base}${ompNote}`);
 }
+/** The doctor's image-input capability check (plans/image-input.md "Doctor", parts 1-2/5):
+ * which of the team's seams claim to read images, and whether every text-only enabled loop can
+ * reroute to one that does. Part 2 adds the live probe — with `probeImages` "missing" (the
+ * terminal `tumwater doctor` default) each claimed pi model with no fresh cached verdict is
+ * shown a real image and the answer is checked; with "all" (the `--reprobe` flag) every claimed
+ * model is re-probed; with "never" (the TUI Health tab and the GUI doctor endpoint) nothing is
+ * spawned and only cached verdicts are read, so a refresh never spends a model call. claude
+ * seams are never probed — every Claude model reads images, and a probe would spend subscription
+ * window to confirm it.
+ *
+ * Covers the same seams as `tier models` (seamPairs — the tiers, enabled roles and the
+ * reviewer) plus the tiers' fallback pairs (the reroute part picks its target among them, so a
+ * text-only fallback would promise a reroute no fallback can serve). A claimed model whose probe
+ * failed (fresh verdict) is dropped from the readers and reads false from seamImageInput, so the
+ * reroute sweep never sends a text-only loop to a model that lost its probe. `providers`,
+ * `account`, `pathEnv` and `probe` are injectable so tests need no real pi install or account. */
+export async function checkImageInput(root, modelsPath = piModelsPath(), providers = readPiProviders(modelsPath), account, probeImages = "never", pathEnv = envPath(), probe = runImageProbe) {
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
+    // `tier models` already fails on a missing/unknown pair, so this check names only what it can
+    // answer; unknown (null) pairs are left to that check. A missing definitions file only blocks
+    // this check when a seam actually needs it — an all-claude team reads images without it.
+    const accountNow = account === undefined ? readClaudeAccount(root) : account;
+    const pairs = seamPairs(config);
+    const needsDefinitions = pairs.some((p) => usesPiModels(p.agent ?? "pi"));
+    if (providers === null && needsDefinitions)
+        return warnOutcome(`cannot check — could not read pi's model definitions at ${modelsPath}`);
+    const label = modelLabel;
+    // The catalog claims (raw `input`, ignoring the cache): what to probe and report, including a
+    // model whose earlier probe failed (it must still be named and re-probed by --reprobe).
+    const claimed = new Map();
+    for (const pair of pairs) {
+        if (pair.model === undefined)
+            continue;
+        if (seamImageInput(pair, providers) === true)
+            claimed.set(imageProbeKey(pair.agent, pair.provider, pair.model), {
+                agent: pair.agent,
+                provider: pair.provider,
+                model: pair.model,
+                thinking: pair.thinking,
+            });
+    }
+    // The tiers' fallback pairs: a reroute target must itself read images to help, and part 4's
+    // fallback regime picks among these, so a text-only fallback team is a coverage gap here.
+    const resolved = resolveTierFallbacks(config, (p) => piPairFree(providers, p.provider, p.model, accountNow));
+    for (const tier of MODEL_TIERS) {
+        const pair = resolved[tier].pair;
+        if (pair?.model === undefined)
+            continue;
+        // Fallback pairs are always pi (FallbackModelConfig has no agent), and the readers
+        // (seamImageInput, imageReroute) resolve a pi seam to the "pi" agent, so the cache key
+        // must carry "pi" — keying it `undefined` would write a verdict the readers never read.
+        const agent = "pi";
+        if (seamImageInput(pair, providers) === true)
+            claimed.set(imageProbeKey(agent, pair.provider, pair.model), {
+                agent,
+                provider: pair.provider,
+                model: pair.model,
+                thinking: pair.thinking,
+            });
+    }
+    const probes = readImageProbeCache(root);
+    const now = Date.now();
+    const env = childEnv({ PATH: pathEnv });
+    const readsItems = [];
+    const failed = [];
+    const couldNot = [];
+    let probedAny = false;
+    // Settle one claimed seam: probe when asked and uncached, read a fresh cached verdict
+    // otherwise, or report "not verified yet". Only pass/fail are cached; could-not-verify is
+    // reported but never cached.
+    for (const seam of claimed.values()) {
+        const agent = seam.agent;
+        // A backend that registers an imageInput hook trusts the hook (claude today, which reads
+        // every model); a backend without one is probed through its model catalog.
+        if (agent !== undefined && agentBackend(agent)?.imageInput !== undefined) {
+            readsItems.push(label(agent, seam.provider, seam.model));
+            continue;
+        }
+        const key = imageProbeKey(agent, seam.provider, seam.model);
+        const cached = probes[key];
+        const valid = imageProbeEntryFresh(cached, now);
+        const wantProbe = probeImages !== "never" && (probeImages === "all" || !valid);
+        if (wantProbe) {
+            probedAny = true;
+            const result = await probe(config, { provider: seam.provider, model: seam.model, thinking: seam.thinking }, env);
+            if (result.verdict === "pass") {
+                probes[key] = { verdict: "pass", detail: result.detail, at: now, claim: true };
+                readsItems.push(`${label(agent, seam.provider, seam.model)} (verified ${formatDate(new Date(now))})`);
+            }
+            else if (result.verdict === "fail") {
+                probes[key] = { verdict: "fail", detail: result.detail, at: now, claim: true };
+                failed.push(`${label(agent, seam.provider, seam.model)} failed the image probe — ${result.detail}`);
+            }
+            else {
+                couldNot.push(`${label(agent, seam.provider, seam.model)} could not be verified — ${result.detail}`);
+            }
+        }
+        else if (cached && imageProbeEntryFresh(cached, now)) {
+            if (cached.verdict === "pass") {
+                readsItems.push(`${label(agent, seam.provider, seam.model)} (verified ${formatDate(new Date(cached.at))})`);
+            }
+            else {
+                failed.push(`${label(agent, seam.provider, seam.model)} failed the image probe — ${cached.detail}`);
+            }
+        }
+        else {
+            readsItems.push(`${label(agent, seam.provider, seam.model)} (not verified yet — run \`tumwater doctor\`)`);
+        }
+    }
+    if (probedAny)
+        writeImageProbeCache(root, probes);
+    // Text-only enabled loops: which can reroute to a tier that reads images (honoring failed
+    // probes), and which cannot.
+    const reroutes = [];
+    const noTarget = [];
+    for (const role of enabledRoleIds(config)) {
+        const rc = configForRole(config, role);
+        if (rc.model === undefined)
+            continue;
+        if (seamImageInput(rc, providers, probes) !== false)
+            continue; // reads images, or unknown (to tier models)
+        const rr = imageReroute(config, role, "primary", modelsPath, accountNow, probes);
+        if (rr && seamImageInput(rr.config, providers, probes) === true)
+            reroutes.push(`${role} text-only (${label(rc.agent, rc.provider, rc.model)}) — reroutes to ${rr.tier} (${label(rr.config.agent, rr.config.provider, rr.config.model)})`);
+        else
+            noTarget.push(`${role} text-only (${label(rc.agent, rc.provider, rc.model)})`);
+    }
+    // A team that declared no models at all leaves capability to pi's own defaults — the same
+    // "nothing configured" stance as tier models, informational rather than a warning.
+    const declared = pairs.some((p) => p.model !== undefined) ||
+        MODEL_TIERS.some((t) => resolved[t].pair?.model !== undefined);
+    if (!declared)
+        return okOutcome("no models declared — every model job uses pi's own default");
+    const readsLine = readsItems.length > 0 ? `reads images: ${[...readsItems].sort().join(", ")}` : "";
+    const details = [readsLine, ...reroutes].filter(Boolean).join("; ");
+    if (failed.length > 0)
+        return failOutcome(`${failed.join("; ")} — remove "image" from its input in pi's models.json or fix the endpoint, then run \`tumwater doctor --reprobe\``);
+    if (couldNot.length > 0)
+        return warnOutcome(`${couldNot.join("; ")}; ${details}`.replace(/;\s*$/, ""));
+    if (noTarget.length > 0)
+        return warnOutcome(`${noTarget.join("; ")} — no configured model reads images, so a run that reads an image fails; declare image input on a vision model in pi's models.json, or point a tier at one`);
+    if (readsItems.length === 0)
+        return warnOutcome("no configured model reads images — a run that reads an image fails; declare image input on a vision model in pi's models.json, or point a tier at one");
+    return okOutcome(details);
+}
+/** 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;
+}
+/** Total bytes of every regular file under `dir` (a shallow recursive walk), 0 for a missing
+ * or unreadable dir. */
+function opencodeDirBytes(dir) {
+    try {
+        let total = 0;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const p = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                total += opencodeDirBytes(p);
+            else if (entry.isFile())
+                total += fs.statSync(p).size;
+        }
+        return total;
+    }
+    catch {
+        return 0;
+    }
+}
+/** A byte count for display: MB, KB, or bytes. */
+function opencodeBytes(n) {
+    if (n >= 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    if (n >= 1024)
+        return `${Math.round(n / 1024)} KB`;
+    return `${n} B`;
+}
+/** 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 = seamPairs(config).filter((p) => p.agent === "opencode" && p.model !== undefined);
+    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 ? `, ${entry.context.toLocaleString("en-US")}-token window` : "";
+        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 !== "" && statOrNull(spillDir)?.isDirectory() === true ? opencodeDirBytes(spillDir) : null;
+    const sizeNotes = `db ${opencodeBytes(db?.size ?? 0)}${spill !== null ? `, spill ${opencodeBytes(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);
+}