tumwater 0.2.0 → 0.3.0

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

@@ -1,44 +1,51 @@
-// 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, resolvedAgentConfig } from "../config/config-views.js";
+import { configForRole } 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 } 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 { backendById } 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 { readClaudeAccount } from "../agent/claude/claude-account.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 { loadRunnerStates } from "./doctor-holds.js";
+import { resolveBackendBin } from "../pi/pi-bin.js";
+import { parsePiModelImages, parsePiModelTable, readPiListedModels, writePiListedModels } from "../pi/pi-listed-models.js";
 import { agree } from "../text/phrases.js";
-import { formatDate, formatTime } from "../text/datetime.js";
-import { belowNodeFloor } from "../version.js";
+import { formatClock, formatDate } from "../text/datetime.js";
+import { errorMessage, joinParts } from "../text/text.js";
 import { failOutcome, okOutcome, warnOutcome } from "./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
+ * checkTierModels and checkImageInput so the two checks word the same "nothing configured"
+ * stance identically. */
+const PHRASE_NO_MODELS_DECLARED = "no models declared — every model job uses pi's own default";
+/** The one phrase a configured-models check uses when pi's definitions file could not be read
+ * at all: the check cannot answer what it was asked, so it warns instead of guessing. Shared by
+ * checkTierModels and checkImageInput so the two checks word the "cannot check" stance
+ * identically; each appends its own modelsPath after the shared stem, and checkTierModels
+ * also appends its ompNote. */
+const PHRASE_CANNOT_READ_MODELS = "cannot check — could not read pi's model definitions at ";
 /** The doctor's model-readiness checks, split out of doctor-checks.ts (whose environment and
- * repo checks stay there): the cap fallback's price check (checkFallbackModel), the agent
- * binary's own credential probe (piProviderAuth), and the declared-tier resolution check
- * (checkTierModels). These three are the doctor's only checks that read pi's model definitions
- * and, for the credential probe, spawn the agent binary — a distinct concern from the
- * filesystem/git checks beside them, kept together so a change to how doctor reads models does
- * not touch the environment checks. The shared report contract (CheckOutcome) is imported from
- * outcome.ts, exactly as doctor-orphans.ts and doctor-backlog.ts do. */
+ * repo-setup checks stay there, and whose state/disk/build checks live in
+ * doctor-project-checks.ts): the cap fallback price and fallback-chain checks (checkFallbackModel,
+ * checkFallbackChain), the pi auth/probe checks (piProviderAuth, piListedModels), the seam
+ * framework (seamPairs and the per-backend seam predicates), and the declared-tier and
+ * image-input checks (checkTierModels, checkImageInput). The claude and opencode provider
+ * checks live in their own modules (doctor-claude-checks.ts, doctor-opencode-checks.ts), each
+ * importing this file's shared seam framework and the AUTH_CHECK_* probe budgets rather than
+ * duplicating them. The shared report contract (CheckOutcome) is imported from 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. */
 /** The config a readiness check reads, or the warn outcome a broken tumwater.json earns:
  * 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
@@ -46,7 +53,7 @@ import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
  * 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) {
+export function loadConfigForCheck(root) {
     const { config, error } = loadConfigSafe(root);
     if (config === undefined)
         return warnOutcome(`cannot check — ${error}`);
@@ -58,7 +65,7 @@ function loadConfigForCheck(root) {
  * 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
- * readiness, though: whether the backend can SERVE is known only from the fallback's own ticks
+ * readiness, though: whether the backend can SERVE is known only from the fallback's own runs
  * (src/budget/fallback-breaker.ts's breaker, BUGS.md 2026-09-20), so a free pair reads "serving not
  * 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),
@@ -77,11 +84,15 @@ export function checkFallbackModel(root, modelsPath = piModelsPath(), demoted =
     // the price-resolved pair (a map with no `default` entry borrows another tier's), while the
     // refusal names the pair the operator declared.
     const nameOf = (pair) => pair.provider && pair.model ? `${pair.provider}/${pair.model}` : "a half-resolved pair";
-    const free = fallbackModelPair(config, modelsPath, readClaudeAccount(root));
+    // The claude account answer (6a/7); the fallback price lookup reads it only for "claude"
+    // (part 2a/9).
+    const account = readClaudeAccount(root);
+    const accounts = (b) => (b === "claude" ? account : null);
+    const free = fallbackModelPair(config, modelsPath, accounts);
     if (free) {
         const name = nameOf(free);
         if (demoted)
-            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 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 ${formatClock(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 roles pause instead of switching`);
@@ -109,7 +120,7 @@ const isLocalUrl = (url) => {
 /** 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
+ * models.json and the role 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);
@@ -118,16 +129,18 @@ export async function checkFallbackChain(root, modelsPath = piModelsPath(), prob
     const steps = tierChainSteps(config);
     if (steps.length === 0)
         return okOutcome("none configured");
-    const states = loadLoopStates(root, config);
+    const states = loadRunnerStates(root, config);
     const providers = readPiProviders(modelsPath);
     const account = readClaudeAccount(root);
+    // The free-ness lookup reads the one claude account held here (part 2a/9).
+    const accounts = (b) => (b === "claude" ? account : null);
     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 nonPiBackend = pair.backend !== undefined && pair.backend !== "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;
@@ -144,7 +157,7 @@ export async function checkFallbackChain(root, modelsPath = piModelsPath(), prob
         else if (nonPiBackend) {
             verdict = `claude ${pair.extraUsage ? "extra usage" : (account?.billing ?? "billing unknown")}`;
         }
-        else if (piPairFree(providers, pair.provider, pair.model, account)) {
+        else if (piPairFree(providers, pair, accounts)) {
             verdict = up ? "free · server up" : "free";
         }
         else {
@@ -169,7 +182,7 @@ export const AUTH_CHECK_MAX_OUTPUT_BYTES = 1024 * 1024;
  * 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) {
+export function seamPairs(config) {
     const pairs = new Map();
     for (const seam of seamsInUse(config)) {
         if (seam.model === undefined)
@@ -183,6 +196,26 @@ function seamPairs(config) {
     }
     return [...pairs.values()];
 }
+/** The model-carrying seam pairs for one backend — `seamPairs` with model guaranteed present
+ * (seamPairs never emits a pair without a model, so the guard only narrows the type) and
+ * narrowed to `agent`'s pairs. The backend readiness checks (claude, codex, opencode) each
+ * walk exactly this filtered list, so they share one filter rather than three copies. */
+export function seamedModels(config, agent) {
+    return seamPairs(config).filter((p) => p.agent === agent && p.model !== undefined);
+}
+/** The warn/fail/ok verdict for a backend CLI's `--version` check against one flat minimum
+ * version (codex's checkCodexVersion and opencode's checkOpencodeVersion both require a
+ * single floor for the whole backend, unlike claude's per-model floors). `found` is the
+ * parsed dotted version, or undefined when the probe could not run or its output was
+ * unreadable. Centralizing the three messages and the belowNodeFloor comparison keeps the
+ * two backends' version verdicts from drifting. */
+export function minVersionOutcome(name, found, min, upgradeHint) {
+    if (found === undefined)
+        return warnOutcome(`could not check — \`${name} --version\` did not run or its output was unreadable`);
+    if (belowNodeFloor(found, `>=${min}`))
+        return failOutcome(`${name} ${found} is older than ${min} — ${upgradeHint}`);
+    return okOutcome(`${name} ${found} (>= ${min})`);
+}
 /** Whether any seam runs on the claude backend — the doctor's claude checks stand down when
  * none does (a pi-only team reads no `~/.claude` state and spawns no claude). */
 export function claudeSeamsInUse(config) {
@@ -193,6 +226,11 @@ export function claudeSeamsInUse(config) {
 export function opencodeSeamsInUse(config) {
     return seamPairs(config).some((pair) => pair.agent === "opencode");
 }
+/** Whether any seam routes to codex — the doctor's codex checks stand down when none does
+ * (a pi-only team spawns no codex and reads no codex home state). */
+export function codexSeamsInUse(config) {
+    return seamPairs(config).some((pair) => pair.agent === "codex");
+}
 /** 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
@@ -202,151 +240,60 @@ 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 ends on "unknown". The bounded subprocess is the shared
- * boundedProbe (probe.ts), also used by the claude probes. */
+ * and read `status` out of its JSON. The binary resolves exactly as the spawn does
+ * (resolveBackendBin — the same source a real run would launch), so doctor tests the auth of
+ * the pi it would actually run. pi's contract is `{"status": "ready"|"not_ready"|"invalid",
+ * provider, reason?, authType?}` with exit codes 0/1/2 — a non-zero exit there is a verdict, not
+ * 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. */
 export async function piProviderAuth(config, provider, pathEnv = envPath(), timeoutMs = AUTH_CHECK_TIMEOUT_MS) {
-    const resolved = resolveAgentBin(config);
+    const resolved = resolveBackendBin(config);
     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)
-        return "unknown";
     // An unreadable reply is unknown, never not-ready (which would blame the credentials).
     const doc = parseJsonObject(result.stdout);
     if (doc === null)
         return "unknown";
-    if (doc.ready === true)
+    if (doc.status === "ready")
         return "ready";
-    if (doc.ready === false)
+    // `invalid` (a bad provider name, exit 2) is likewise not a healthy credential: it reads
+    // not-ready so the warning blames the setup, not the probe.
+    if (doc.status === "not_ready" || doc.status === "invalid")
         return "not-ready";
     return "unknown";
 }
-/** One bounded probe of the resolved `claude` binary under the scrubbed run environment a real
- * tick gets: resolve the binary through the claude adapter that would spawn it and run `args`
- * with a short deadline. Null when the probe could not run, the child errored, or the deadline
- * passed. The one home of the resolveBin + claudeEnv pairing the auth and version checks share,
- * so neither probes a different binary or environment than the other. */
-function claudeProbe(config, args, pathEnv, timeoutMs) {
-    const resolved = claudeBackend.resolveBin(config);
-    // 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);
+/** Read the table `pi --list-models` prints into a set of `provider/model` keys. Null unless the
+ * first non-blank line is the `provider model …` header, so a "No models matching" reply or any
+ * other text is never taken for an empty catalog. */
+export function parsePiModelList(stdout) {
+    const table = parsePiModelTable(stdout);
+    if (table === null)
+        return null;
+    const listed = new Set();
+    for (const [provider, model] of table.rows)
+        if (model !== undefined)
+            listed.add(`${provider}/${model}`);
+    return listed;
 }
-/** 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. */
-async function claudeAuthProbe(config, pathEnv, timeoutMs) {
-    const result = await claudeProbe(config, ["auth", "status"], pathEnv, timeoutMs);
+/** The models pi itself lists (`pi --list-models`), which include its built-in catalog that
+ * models.json does not repeat. pi lists only the providers it has credentials for. Null when the
+ * probe could not run or failed; never throws. Given a `root`, it also records the images column
+ * for `seamImageInput` (src/pi/pi-listed-models.ts). */
+export async function piListedModels(config, pathEnv = envPath(), timeoutMs = AUTH_CHECK_TIMEOUT_MS, root) {
+    const result = await boundedProbe(resolveBackendBin(config).bin, ["--list-models"], childEnv({ PATH: pathEnv }), timeoutMs, AUTH_CHECK_MAX_OUTPUT_BYTES);
     if (result?.code !== 0)
         return null;
-    return parseClaudeAuthStatus(result.stdout);
-}
-/** claude credential readiness (plans/agent-backends.md "Every seam, checked"): a claude seam
- * whose login is gone fails every tick before it can work, so doctor runs `claude auth status`
- * under the scrubbed run environment and fails when it reports `loggedIn: false`. An ok detail
- * 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 team spawns nothing. */
-export async function checkClaudeAuth(root, 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 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)
-        return failOutcome("claude reports logged in: false — run `claude auth login`");
-    const subscription = claudeAuthUsesSubscription(auth);
-    const billing = subscription
-        ? `subscription${auth.subscriptionType !== undefined ? ` (${auth.subscriptionType})` : ""}`
-        : "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 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 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 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) {
-        const min = claudeBackend.minVersion?.(seam.model);
-        if (min !== undefined)
-            floors.set(seam.model, min);
-    }
-    const result = await claudeProbe(config, ["--version"], pathEnv, timeoutMs);
-    const found = result !== null && result.code === 0 ? parseClaudeCliVersion(result.stdout) : undefined;
-    if (found === undefined)
-        return warnOutcome("could not check — `claude --version` did not run or its output was unreadable");
-    const clamped = seams.some((seam) => seam.thinking === "off" || seam.thinking === "minimal");
-    const clampNote = clamped
-        ? "; `off`/`minimal` thinking clamps to `--effort low` (claude has no lower setting)"
-        : "";
-    if (floors.size === 0)
-        return okOutcome(`claude ${found}${clampNote}`);
-    // The highest floor decides: whichever model needs the newest CLI. Below it, fail and name
-    // that model; at or above, print the version against the floor.
-    let required = "";
-    let neededBy = "";
-    for (const [model, min] of floors) {
-        if (required === "" || belowNodeFloor(required, `>=${min}`)) {
-            required = min;
-            neededBy = model;
+    const images = root === undefined ? null : parsePiModelImages(result.stdout);
+    if (root !== undefined && images !== null) {
+        try {
+            writePiListedModels(root, images);
         }
+        catch { } // A failed write never changes the check.
     }
-    if (belowNodeFloor(found, `>=${required}`))
-        return failOutcome(`claude ${found} is older than ${required} required by ${neededBy} — run \`claude update\``);
-    return okOutcome(`claude ${found} (>= ${required} for ${neededBy})${clampNote}`);
+    return parsePiModelList(result.stdout);
 }
 /** 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
@@ -362,13 +309,16 @@ export async function checkClaudeVersion(root, pathEnv = envPath(), timeoutMs =
  * 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) {
+ * (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());
     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.
@@ -394,19 +344,14 @@ export async function checkTierModels(root, modelsPath = piModelsPath(), auth =
         ? ""
         : ` — ${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)(`no models declared — every model job uses pi's own default${ompNote}`);
-    const providers = readPiProviders(modelsPath);
+        return (ompVars.length === 0 ? okOutcome : warnOutcome)(`${PHRASE_NO_MODELS_DECLARED}${ompNote}`);
+    let providers = readPiProviders(modelsPath);
+    if (!providers && [...pairs.values()].some((p) => p.provider !== undefined) && (await listed()))
+        providers = new Map();
     const fails = [];
     const warns = [];
-    // Reserved agent ids: a pi provider whose name is an agent backend's id can never reach pi
-    // (the provider segment wins the routing), so its definitions are unreachable — warn.
-    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 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}`);
+        return warnOutcome(`${PHRASE_CANNOT_READ_MODELS}${modelsPath}${ompNote}`);
     const readyProviders = new Set();
     const checkedProviders = new Set();
     for (const { provider, model } of pairs.values()) {
@@ -423,19 +368,29 @@ export async function checkTierModels(root, modelsPath = piModelsPath(), auth =
             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})`);
-            continue;
-        }
-        const def = defs.find((d) => d.id === model);
+        const def = defs?.find((d) => d.id === model);
         if (!def) {
-            // 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`);
-            continue;
+            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 (cacheReadUnpriced(providers, provider, model)) {
+        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`);
@@ -455,37 +410,44 @@ export async function checkTierModels(root, modelsPath = piModelsPath(), auth =
     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` : ""}`;
     // 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.
+    // id always means the OpenCode CLI, never pi's built-in `opencode` gateway. Every note opens
+    // with the same `<n> <agent>-routed model[s] — ` frame — one phrase in one place (routedNote)
+    // so the branches cannot drift on it; the count prints beside the label, so the number form
+    // needs agree (not plural, which prints the count).
+    const routedNote = (agent, n, tail) => `${n} ${agent}-routed ${agree(n, "model", "models")} — ${tail}`;
     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`);
+            ? routedNote(agent, n, "`opencode/…` ids run on the OpenCode CLI, and pi's built-in `opencode` provider is not reachable from tumwater")
+            : agent === "codex"
+                ? 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("; ") : "";
     const base = fails.length === 0 && warns.length === 0
-        ? [pairs.size > 0 ? resolvedPi : "", routedText].filter(Boolean).join("; ")
+        ? joinParts([pairs.size > 0 ? resolvedPi : "", routedText])
         : 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
+ * which of the team's seams claim to read images, and whether every text-only enabled role 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.
+ * shown a real image and the answer is checked; with "all" (the `--reprobe` flag, the
+ * dashboard's Re-probe models button and the TUI Health tab's Ctrl+P) every claimed model is
+ * re-probed; with "never" (the TUI Health tab and GUI doctor endpoint on entry and refresh)
+ * 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`,
+ * reroute sweep never sends a text-only role 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);
@@ -495,10 +457,13 @@ export async function checkImageInput(root, modelsPath = piModelsPath(), provide
     // 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;
+    // The free-ness lookup reads the image-input check's one claude account (part 2a/9).
+    const accounts = (b) => (b === "claude" ? accountNow : null);
+    const listed = readPiListedModels(root);
     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}`);
+        return warnOutcome(`${PHRASE_CANNOT_READ_MODELS}${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).
@@ -506,7 +471,7 @@ export async function checkImageInput(root, modelsPath = piModelsPath(), provide
     for (const pair of pairs) {
         if (pair.model === undefined)
             continue;
-        if (seamImageInput(pair, providers) === true)
+        if (seamImageInput(pair, providers, undefined, listed) === true)
             claimed.set(imageProbeKey(pair.agent, pair.provider, pair.model), {
                 agent: pair.agent,
                 provider: pair.provider,
@@ -516,16 +481,16 @@ export async function checkImageInput(root, modelsPath = piModelsPath(), provide
     }
     // 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));
+    const resolved = resolveTierFallbacks(config, (p) => piPairFree(providers, p, accounts));
     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)
+        // The readers (seamImageInput, imageReroute) resolve a pair with no backend to the "pi"
+        // agent, so the cache key must carry "pi" — keying it `undefined` would write a verdict the
+        // readers never read.
+        const agent = pair.backend ?? "pi";
+        if (seamImageInput({ ...pair, agent }, providers, undefined, listed) === true)
             claimed.set(imageProbeKey(agent, pair.provider, pair.model), {
                 agent,
                 provider: pair.provider,
@@ -547,7 +512,7 @@ export async function checkImageInput(root, modelsPath = piModelsPath(), provide
         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) {
+        if (agent !== undefined && backendById(agent)?.imageInput !== undefined) {
             readsItems.push(label(agent, seam.provider, seam.model));
             continue;
         }
@@ -582,207 +547,76 @@ export async function checkImageInput(root, modelsPath = piModelsPath(), provide
             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;
+    let saveProblem = null;
+    if (probedAny) {
+        try {
+            writeImageProbeCache(root, probes);
         }
-        for (const key of ["plugin", "agent", "instructions"]) {
-            if (jsonKeyPresent(text, key))
-                parts.push(`a ${key} entry`);
+        catch (err) {
+            saveProblem = errorMessage(err);
         }
-        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;
+    const verdict = () => {
+        // Text-only enabled roles: 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, listed) !== false)
+                continue; // reads images, or unknown (to tier models)
+            const rr = imageReroute(config, role, "primary", modelsPath, accountNow, probes, null, listed);
+            if (rr && seamImageInput(rr.config, providers, probes, listed) === 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)})`);
         }
-        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`;
+        // 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(PHRASE_NO_MODELS_DECLARED);
+        const readsLine = readsItems.length > 0 ? `reads images: ${[...readsItems].sort().join(", ")}` : "";
+        const details = joinParts([readsLine, ...reroutes]);
+        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);
+    };
+    const outcome = verdict();
+    if (saveProblem === null)
+        return outcome;
+    return {
+        level: outcome.level === "ok" ? "warn" : outcome.level,
+        detail: `${outcome.detail} — could not save the image-probe cache (${saveProblem}), so the next doctor probes again`,
+    };
 }
-/** 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) {
+/** `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`
+ * resolves and `gh auth status` exits 0 before a run tries to file — the codex-login pattern
+ * (plans/codex-backend.md part 9/9). Shown only when the role is enabled: on a default install
+ * nothing files upstream, so there is nothing to check and the row is omitted (null). `probe`
+ * is injectable so tests use a fake gh (test/fakes/fake-gh.ts); the real probe runs `gh` under
+ * the scrubbed run environment with a bounded deadline. */
+export async function checkFeedbackFiling(root, pathEnv = envPath(), probe = (args) => boundedProbe("gh", args, childEnv({ PATH: pathEnv }), AUTH_CHECK_TIMEOUT_MS, AUTH_CHECK_MAX_OUTPUT_BYTES)) {
     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);
+    if (!config.roles.feedback?.enabled)
+        return null;
+    const version = await probe(["--version"]);
+    if (version?.code !== 0)
+        return failOutcome("gh is missing or unusable — install GitHub CLI (https://cli.github.com) so the feedback role can file issues as your login");
+    const auth = await probe(["auth", "status"]);
+    if (auth?.code !== 0)
+        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");
 }