tumwater 0.4.0 → 0.4.2

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

@@ -4,7 +4,7 @@ import path from "node:path";
 import { enabledRoleIds, parseJsonConfig, loadConfig, loadConfigSafe, } from "../config/config.js";
 import { exampleConfigProblem, exampleDrift } from "../config/config-example.js";
 import { bootstrapStatus } from "../gates/bootstrap-gates.js";
-import { envPath, findOnPath, readTextOrNull, treeBytes } from "../files/files.js";
+import { envPath, findOnPath, readTextOrNull, treeBytes, xdgConfigHomeDir } from "../files/files.js";
 import { readJsonFile } from "../files/json-files.js";
 import { PACKAGE_JSON, belowNodeFloor, packageEnginesNode } from "../version.js";
 import { GIT_MISSING_MESSAGE } from "../git/git-run.js";
@@ -15,7 +15,7 @@ import { resolvedBackendConfig } from "../config/config-views.js";
 import { CONFIG_BASENAME, EXAMPLE_CONFIG_BASENAME, configPath, owningTeamRoot } from "../paths.js";
 import { errorMessage } from "../text/text.js";
 import { formatBytes } from "../text/format.js";
-import { briefFile } from "../brief/brief.js";
+import { BRIEF_TEXT_MAX_CHARS, briefFile, promptBlockOf, readBrief } from "../brief/brief.js";
 import { plural } from "../text/phrases.js";
 import { backendsInUse, unregisteredBackendInUse } from "../gates/startup-gate.js";
 import { claudeSeamsInUse, minVersionOutcome, opencodeSeamsInUse, versionFromProbe, piSeamsInUse } from "./doctor-model-checks.js";
@@ -157,8 +157,20 @@ export function checkBrief(root) {
     catch (err) {
         return failOutcome(errorMessage(err));
     }
-    if (owner)
+    if (owner) {
+        const prompt = readBrief(root)?.prompt ?? "";
+        if (prompt === "") {
+            return warnOutcome(`${owner} carries an empty tumwater:prompt block — every role would run without its project brief; add the brief text or re-run \`tumwater init\``);
+        }
+        const raw = readTextOrNull(path.join(root, owner));
+        if (raw !== null) {
+            const block = promptBlockOf(raw);
+            if (block !== null && block.length > BRIEF_TEXT_MAX_CHARS) {
+                return warnOutcome(`brief in ${owner} is ${block.length} characters, over the ${BRIEF_TEXT_MAX_CHARS}-character read cap every role sees (the prompt is truncated at ${BRIEF_TEXT_MAX_CHARS} chars); hand-edit ${owner} to shrink the block below ${BRIEF_TEXT_MAX_CHARS} characters, or paste a shorter brief in the dashboard's Brief card`);
+            }
+        }
         return okOutcome(`brief in ${owner}`);
+    }
     if (fs.existsSync(path.join(root, "README.md"))) {
         return warnOutcome(`README.md carries no tumwater:prompt markers — the team would run without its project brief; add the block or re-run \`tumwater init\``);
     }
@@ -353,7 +365,7 @@ export function checkPiExtensions(config, homeDir = os.homedir(), pathEnv = envP
 /** The operator's global opencode config files, in XDG order — the same home `opencode-config.ts`
  * reads for MCP names. Home is the operator's home; `$XDG_CONFIG_HOME`, when set, wins. */
 function opencodeGlobalConfigPaths(homeDir) {
-    const configHome = process.env.XDG_CONFIG_HOME ?? path.join(homeDir, ".config");
+    const configHome = xdgConfigHomeDir(process.env, homeDir);
     return ["config.json", "opencode.json", "opencode.jsonc"].map((file) => path.join(configHome, "opencode", file));
 }
 /** Report the operator's global opencode config file that mentions funes, or null.

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

@@ -10,8 +10,8 @@ import { belowNodeFloor } from "../version.js";
 import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
 import { claudeSeamsInUse, loadConfigForCheck, versionFromProbe, seamedModels, } from "./doctor-model-checks.js";
 /** The doctor's claude credential and version readiness checks, split out of
- * doctor-model-checks.ts (whose shared seam/model framework and the pi, tier-models and
- * image-input checks stay there): checkClaudeAuth, checkAnthroApiKey and checkClaudeVersion.
+ * doctor-model-checks.ts (whose shared seam/model framework and the pi and tier-models
+ * checks stay there): checkClaudeAuth, checkAnthroApiKey and checkClaudeVersion.
  * These are the doctor's only checks that spawn the `claude` binary and read its auth — a
  * distinct concern from the filesystem/git checks, kept together so a change to how doctor
  * spawns or scrubs claude does not touch the other model checks. The shared report contract

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

@@ -10,7 +10,7 @@ import { codexHookTrust } from "../agent/codex/codex-hook-trust.js";
 import { parseCodexLoginStatus } from "../agent/codex/codex-account.js";
 import { codexWriteGuardDefinition } from "../agent/codex/codex-write-guard.js";
 import { resolvedBackendConfig } from "../config/config-views.js";
-import { envPath, isDirectory, readTextOrNull, statOrNull, treeBytes } from "../files/files.js";
+import { envPath, isDirectory, readTextOrNull, statOrNull, treeBytes, walkFiles } from "../files/files.js";
 import { formatBytes, tokenWindowLabel } from "../text/format.js";
 import { errorMessage } from "../text/text.js";
 import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
@@ -152,26 +152,15 @@ function codexSessionCredits(home) {
     if (!isDirectory(sessions))
         return null;
     const rollouts = [];
-    const walk = (dir) => {
-        let entries;
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
+    // The walk-and-swallow recursion is files.ts's walkFiles; each rollout file is statted so
+    // the newest (by mtime) can win below.
+    walkFiles(sessions, (file, entry) => {
+        if (/^rollout-.*\.jsonl$/.test(entry.name)) {
+            const st = statOrNull(file);
+            if (st !== null)
+                rollouts.push({ file, mtimeMs: st.mtimeMs });
         }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            const p = path.join(dir, entry.name);
-            if (entry.isDirectory())
-                walk(p);
-            else if (entry.isFile() && /^rollout-.*\.jsonl$/.test(entry.name)) {
-                const st = statOrNull(p);
-                if (st !== null)
-                    rollouts.push({ file: p, mtimeMs: st.mtimeMs });
-            }
-        }
-    };
-    walk(sessions);
+    });
     rollouts.sort((a, b) => b.mtimeMs - a.mtimeMs);
     for (const r of rollouts) {
         const text = readTextOrNull(r.file);

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

@@ -70,7 +70,7 @@ export function staleWorkspacePins(root, now = Date.now()) {
     }));
 }
 /** The shared one-pin clause of the doctor's `worktree pool` row (checkWorktreePool) and the
- * standing `workspace-pins` alert (team-alerts.ts): `<role> pinned on <dir> for <Nh>`. One
+ * standing `workspace-pins` alert (team-alert-tail.ts): `<role> pinned on <dir> for <Nh>`. One
  * home so the row and the alert cannot drift on how a pin's age is phrased (whole hours, off
  * the pin's whole-ms age). `role` is a non-optional string on StaleWorkspacePin, but the
  * clause renders it through textOr like the row always did, so a malformed pin can never
@@ -433,7 +433,9 @@ function claimCounts(claims) {
  * multi-instance role configured with fewer pooled slots than maxConcurrent also warns:
  * instances then contend for the same checkouts. A disabled role runs none of its
  * configured instances, so it never contends and
- * stays out of that warning.
+ * stays out of that warning. The pool-mismatch clause comes from the shared
+ * `smallPoolProblems` selector, so the row and the always-on `instance-pool` alert cannot
+ * drift on the trigger, the role list, or the wording.
  * Read-only, like every check; `now` is the claim-age test seam, and an unreadable
  * tumwater.json (config undefined) skips the walk — checkInit reports the config itself. */
 export function checkWorkInstances(root, config, now = Date.now()) {
@@ -443,17 +445,29 @@ export function checkWorkInstances(root, config, now = Date.now()) {
     const entries = staleClaimEntries(root, runnerIds(config), now);
     const gone = entries.filter((e) => e.kind === "gone");
     const stale = entries.filter((e) => e.kind === "idle");
+    const smallPool = smallPoolProblems(config);
+    if (gone.length === 0 && stale.length === 0 && smallPool.length === 0)
+        return okOutcome(claimCounts(claims));
+    const parts = [...gone.map(staleClaimDetail), ...stale.map(staleClaimDetail)];
+    parts.push(...smallPool);
+    return warnOutcome(parts.join("; "));
+}
+/** An enabled multi-instance role contending for a worktree pool smaller than the run cap —
+ * the pool-mismatch clause of the doctor's `parallel instances` row (checkWorkInstances) and
+ * the always-on `instance-pool` alert (alert-feeds.ts instancePoolProblems). Returns the
+ * `INSTANCE_ROLES` ids with more than one configured instance while `slotCount(config)`
+ * (worktreeSlots, else maxConcurrent + 1) is below `config.maxConcurrent`, phrased as the
+ * row's one clause; `[]` when no such role or the pool is at least `maxConcurrent`. Shared by
+ * the doctor row and the alert so they cannot drift on the trigger, the role list, or the
+ * wording. */
+export function smallPoolProblems(config) {
     const multi = Object.entries(config.roles)
         .filter(([id, role]) => INSTANCE_ROLES.has(id) && role.enabled && (role.instances ?? 1) > 1)
         .map(([id]) => id);
     const slots = slotCount(config);
-    const smallPool = multi.length > 0 && slots < config.maxConcurrent;
-    if (gone.length === 0 && stale.length === 0 && !smallPool)
-        return okOutcome(claimCounts(claims));
-    const parts = [...gone.map(staleClaimDetail), ...stale.map(staleClaimDetail)];
-    if (smallPool)
-        parts.push(`${multi.join(", ")} run instances but worktreeSlots ${slots} is below maxConcurrent ${config.maxConcurrent}`);
-    return warnOutcome(parts.join("; "));
+    if (multi.length === 0 || slots >= config.maxConcurrent)
+        return [];
+    return [`${multi.join(", ")} run instances but worktreeSlots ${slots} is below maxConcurrent ${config.maxConcurrent}`];
 }
 /** Provider concurrency caps (plans/provider-concurrency.md §8): audit the
  * `maxConcurrentPerProvider` map against the seams the config can actually spawn — each role,
@@ -466,17 +480,22 @@ export function checkWorkInstances(root, config, now = Date.now()) {
  * well-formed map; a broken config is reported by the init check. Takes `root` to read pi's
  * own default model (piSettingsPath), the same seam the orchestrator's admission uses, so a
  * bare no-model pi seam keys exactly as the team would key it. */
-export function checkProviderConcurrency(config, root) {
+/** The warnings behind checkProviderConcurrency, as a pure function of the config and pi's
+ * default model name: a cap key no seam resolves to (a typo, or a provider not in use), a cap
+ * at or above `maxConcurrent` (which never binds), and a capped team whose seams include one
+ * with no key (pi's default provider is unreadable, so that seam cannot be capped). The doctor's
+ * `provider concurrency` row and the always-on `provider-caps` team alert both read this one
+ * computation, so the row and the alert cannot drift on the trigger or the wording. `[]` for no
+ * config, a map with no enforcedKeyCaps entries, or a map with no problem. `piDefault` is the
+ * bare default model the orchestrator's admission seam carries, read once by the callers
+ * through readPiDefaultModel(piSettingsPath(piModelsPath()), root). */
+export function providerConcurrencyProblems(config, piDefault) {
     if (!config)
-        return okOutcome("no config to audit");
+        return [];
     const caps = config.maxConcurrentPerProvider;
     const capEntries = enforcedKeyCaps(caps);
     if (capEntries.length === 0)
-        return okOutcome("no per-provider caps configured");
-    // The pi default model the orchestrator's admission seam carries: a bare no-model pi seam
-    // resolves its key only through it, so a team whose default is readable has keyed seams and
-    // only an unreadable default leaves a key-less seam to warn about.
-    const piDefault = readPiDefaultModel(piSettingsPath(piModelsPath()), root);
+        return [];
     const seams = seamsInUse(config);
     const keyed = [];
     for (const s of seams) {
@@ -498,9 +517,23 @@ export function checkProviderConcurrency(config, root) {
     const capSet = new Set(capKeys);
     const keyless = seams.filter((s) => seamConcurrencyKey(s, piDefault) === undefined);
     if (capSet.size > 0 && keyless.length > 0) {
-        warnings.push(`${keyless.length} model job(s) resolve to no provider key (pi's default provider is unreadable, so they cannot be capped): ${keyless.map((s) => s.label).join(", ")}`);
+        warnings.push(`${plural(keyless.length, "model job")} ${agree(keyless.length, "resolves", "resolve")} to no provider key (pi's default provider is unreadable, so they cannot be capped): ${keyless.map((s) => s.label).join(", ")}`);
     }
-    if (warnings.length === 0)
+    return warnings;
+}
+export function checkProviderConcurrency(config, root) {
+    if (!config)
+        return okOutcome("no config to audit");
+    const caps = config.maxConcurrentPerProvider;
+    const capEntries = enforcedKeyCaps(caps);
+    if (capEntries.length === 0)
+        return okOutcome("no per-provider caps configured");
+    // The pi default model the orchestrator's admission seam carries: a bare no-model pi seam
+    // resolves its key only through it, so a team whose default is readable has keyed seams and
+    // only an unreadable default leaves a key-less seam to warn about.
+    const piDefault = readPiDefaultModel(piSettingsPath(piModelsPath()), root);
+    const problems = providerConcurrencyProblems(config, piDefault);
+    if (problems.length === 0)
         return okOutcome(`${plural(capEntries.length, "provider cap")} — all model jobs resolve`);
-    return warnOutcome(warnings.join("; "));
+    return warnOutcome(problems.join("; "));
 }

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

@@ -1,4 +1,5 @@
 import { roleLabel } from "../roles/role-labels.js";
+import { sortEntriesByKey } from "../collections.js";
 import { pausedRoles, pausedRolesUntil, standingTeamPause } from "../team/team-state.js";
 import { MODEL_TIERS } from "../config/config-schema.js";
 import { withModelOverrides } from "../config/config-views.js";
@@ -10,7 +11,7 @@ import { MAINTENANCE_DAILY_FLOOR } from "../gates/maintenance-quota.js";
 import { heldByMainRed, mainCheckForPoll, maintenanceQuotaForPoll } from "../status/status-polls.js";
 import { loadRunnerState } from "../runner/runner-state-load.js";
 import { baseRoleOf, runnerIds, runnerPaused } from "../roles/runner-ids.js";
-import { ERROR_STREAK_BREAKER, ERROR_STREAK_WARN } from "../run/run-apply.js";
+import { ERROR_STREAK_BREAKER, errorStreakAtWarn } from "../run/run-apply.js";
 import { squash } from "../text/text.js";
 import { usd } from "../text/format.js";
 import { parseQuietHours, quietHoursStatus, quietWindowEnd, roleQuietHold } from "../scheduling/quiet-hours.js";
@@ -32,6 +33,12 @@ export function loadRunnerStates(root, config) {
         .map((id) => loadRunnerState(root, id))
         .sort((a, b) => a.role.localeCompare(b.role));
 }
+/** A doctor row's `not checked` outcome when tumwater.json is unreadable: the row blanks its
+ * verdict rather than claim a state it cannot see (checkInit owns that error). Every check that
+ * reads the config returns this same outcome when the file is unreadable. */
+function uncheckedConfigOutcome() {
+    return okOutcome("not checked — tumwater.json unreadable");
+}
 /** The `pause` check: names a standing operator pause so doctor does not print "ready to run"
  * over a team that starts no run. Read-only: it reads the same team and per-role pause
  * markers the scheduler reads (standingTeamPause, pausedRoles, pausedRolesUntil — all treat
@@ -95,14 +102,11 @@ export function checkQuietHours(config, now = new Date()) {
  * per-role caps reached alone are ok because the operator chose them by name. */
 export function checkBudget(root, config, published, now = Date.now()) {
     if (config === undefined)
-        return okOutcome("not checked — tumwater.json unreadable");
+        return uncheckedConfigOutcome();
     const states = loadRunnerStates(root, config);
     const spent = published?.spentUsd ?? teamDailyCost(states, now);
     const caps = config.maxDailyCostUsdPerRole;
-    const capped = [...roleCapVerdicts(states.map((s) => ({ role: s.role, state: s })), caps, now)]
-        .filter(([, v]) => v.over)
-        .sort(([a], [b]) => a.localeCompare(b))
-        .map(([base, v]) => `${base} (${budgetPhrase(v.spentUsd, caps?.[base])})`);
+    const capped = sortEntriesByKey([...roleCapVerdicts(states.map((s) => ({ role: s.role, state: s })), caps, now)].filter(([, v]) => v.over)).map(([base, v]) => `${base} (${budgetPhrase(v.spentUsd, caps?.[base])})`);
     const cappedPhrase = capped.length > 0 ? `; capped roles: ${capped.join(", ")}` : "";
     const cap = config.maxDailyCostUsd;
     if (!(cap > 0))
@@ -124,7 +128,7 @@ export function checkBudget(root, config, published, now = Date.now()) {
  * because it stops a whole tier. */
 export function checkMaintenanceQuota(root, config, aliveTeam, now = Date.now()) {
     if (config === undefined)
-        return okOutcome("not checked — tumwater.json unreadable");
+        return uncheckedConfigOutcome();
     const runners = loadRunnerStates(root, config).map((s) => ({ role: s.role, running: aliveTeam && s.running === true }));
     const queued = aliveTeam ? new Set(readMergeQueue(root).entries.map((e) => e.role)) : new Set();
     const { allowance, used, held } = maintenanceQuotaForPoll(root, config.maintenancePerWorkMerge, runners, queued, now);
@@ -201,9 +205,7 @@ export function checkProviderHolds(root, now = Date.now()) {
             standing.delete(typeof ev.provider === "string" ? ev.provider : undefined);
         }
     }
-    const held = [...standing.entries()]
-        .filter(([, h]) => h.end > now)
-        .sort(([a], [b]) => (a ?? "").localeCompare(b ?? ""));
+    const held = sortEntriesByKey([...standing.entries()].filter(([, h]) => h.end > now));
     if (held.length === 0)
         return okOutcome("no provider holds");
     const lines = held.map(([provider, h]) => {
@@ -221,9 +223,9 @@ export function checkProviderHolds(root, now = Date.now()) {
  * fail: a failing role does not stop the team from running. */
 export function checkErrorStreaks(root, config) {
     if (config === undefined)
-        return okOutcome("not checked — tumwater.json unreadable");
+        return uncheckedConfigOutcome();
     const failing = loadRunnerStates(root, config)
-        .filter((s) => (s.consecutiveErrors ?? 0) >= ERROR_STREAK_WARN);
+        .filter((s) => errorStreakAtWarn(s));
     if (failing.length === 0)
         return okOutcome("no role failing repeatedly");
     const paused = new Set(pausedRoles(root));
@@ -243,16 +245,16 @@ export function checkErrorStreaks(root, config) {
     });
     return warnOutcome(`failing run after run: ${phrases.join("; ")}`);
 }
-/** The `main red` check: names the code roles the red-main gate (mainRedGate) holds, ending
- * each blocked run `main_red` while main's suite is red, and warns when main has been red over
- * RED_MAIN_WARN_MS even with no role held (the red-main gate's guardrail, G1). Read-only: it
- * asks heldByMainRed, the predicate the status phase's `main red` label reads, so the two
- * cannot disagree on the held roles, and redMainWarning over the event trail, so both phrases
- * can appear in one row. A warn, not a fail: a red main does not stop the team from running.
- * `now` is injected so a test can pin a red's age. */
+/** The `main red` check: the row lists the runs the merge-side `main_red` pin ended — a red
+ * main is still recorded as the `main_red` outcome that ended those runs until parts 3d/3–3f/3
+ * land — and warns when main has been red over RED_MAIN_WARN_MS even with no role held (the
+ * guardrail, G1). Read-only: it asks heldByMainRed, the predicate the status phase's `main red`
+ * label reads, so the two cannot disagree on the held runs, and redMainWarning over the event
+ * trail, so both phrases can appear in one row. A warn, not a fail: a red main does not stop
+ * the team from running. `now` is injected so a test can pin a red's age. */
 export function checkMainRed(root, config, now = Date.now()) {
     if (config === undefined)
-        return okOutcome("not checked — tumwater.json unreadable");
+        return uncheckedConfigOutcome();
     const mainCheck = mainCheckForPoll(root, config);
     const ids = runnerIds(config);
     const held = loadRunnerStates(root, config)

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

@@ -1,31 +1,22 @@
 import { childEnv } from "../process/process.js";
 import { AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS, boundedProbe } from "./probe.js";
-import { enabledRoleIds, defaultConfig, loadConfigSafe } from "../config/config.js";
-import { configForRole } from "../config/config-views.js";
-import { resolveTierFallbacks, seamsInUse } from "../config/config-fallbacks.js";
-import { cacheReadUnpriced, piModelsPath, piPairFree, readPiProviders } from "../pi/pi-models.js";
-import { MODEL_TIERS } from "../config/config-schema.js";
-import { imageReroute, seamImageInput } from "../agent/image-input.js";
-import { modelLabel, usesPiModels } from "../agent/backend-traits.js";
-import { backendById } from "../agent/agent-backend.js";
-import { imageProbeEntryFresh, imageProbeKey, readImageProbeCache, runImageProbe, writeImageProbeCache, } from "./image-probe.js";
-import { readClaudeAccount } from "../agent/claude/claude-account.js";
+import { defaultConfig, loadConfigSafe } from "../config/config.js";
+import { seamsInUse } from "../config/config-fallbacks.js";
+import { cacheReadUnpriced, piModelsPath, readPiProviders } from "../pi/pi-models.js";
 import { envPath } from "../files/files.js";
 import { piListedModels, piProviderAuth } from "./doctor-pi-checks.js";
-import { readPiListedModels } from "../pi/pi-listed-models.js";
 import { agree } from "../text/phrases.js";
-import { formatDate } from "../text/datetime.js";
-import { errorMessage, joinParts } from "../text/text.js";
+import { 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. */
+ * checkTierModels so the check words the same "nothing configured"
+ * stance. */
 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
+ * checkTierModels so the check words 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 ";
@@ -33,7 +24,7 @@ const PHRASE_CANNOT_READ_MODELS = "cannot check — could not read pi's model de
  * repo-setup checks stay there, and whose state/disk/build checks live in
  * doctor-project-checks.ts), and split apart again so one theme owns one module: this file holds
  * the shared config guard, the seam framework (seamPairs and the per-backend seam predicates),
- * and the declared-tier and image-input checks (checkTierModels, checkImageInput). The cap
+ * and the declared-tier check (checkTierModels). The cap
  * fallback price and fallback-chain checks (checkFallbackModel, checkFallbackChain) live in
  * doctor-fallback-checks.ts, importing this file's loadConfigForCheck just as the per-backend
  * modules do. The claude, opencode, codex and pi provider checks live in their own per-backend
@@ -277,173 +268,6 @@ export async function checkTierModels(root, modelsPath = piModelsPath(), auth =
         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 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, 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 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);
-    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;
-    // 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(`${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).
-    const claimed = new Map();
-    for (const pair of pairs) {
-        if (pair.model === undefined)
-            continue;
-        if (seamImageInput(pair, providers, undefined, listed) === 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, accounts));
-    for (const tier of MODEL_TIERS) {
-        const pair = resolved[tier].pair;
-        if (pair?.model === undefined)
-            continue;
-        // 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,
-                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 && backendById(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\`)`);
-        }
-    }
-    let saveProblem = null;
-    if (probedAny) {
-        try {
-            writeImageProbeCache(root, probes);
-        }
-        catch (err) {
-            saveProblem = errorMessage(err);
-        }
-    }
-    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)})`);
-        }
-        // 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`,
-    };
-}
 /** `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

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

@@ -6,11 +6,8 @@ import { errorMessage, squash } from "../text/text.js";
 import { okOutcome, warnOutcome } from "./outcome.js";
 /** How far back the `notify` check looks for failed pages: a day, fixed. An opinionated
  * default with no knob, like STALE_BUG_DAYS: long enough that a transient hook failure shows
- * up, short enough that a page that did not go through is still the operator's business. The
- * always-on notify team alert (src/ui/status-payload.ts notifyFailures) reuses this same
- * threshold and the same isNotifyFailure window, so it cannot drift from the doctor's check
- * — the STALE_BUG_DAYS precedent. */
-export const NOTIFY_CHECK_WINDOW_MS = DAY_MS;
+ * up, short enough that a page that did not go through is still the operator's business. */
+const NOTIFY_CHECK_WINDOW_MS = DAY_MS;
 /** The `notify` check: whether a notify command is configured, and a warning when it failed to
  * page within the last day (a nonzero exit, a kill, or a failed start — the warnings
  * spawnNotifyCommand logs). Warns but never fails, like the hold rows: a dead webhook must not