tumwater 0.1.2 → 0.2.0

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

@@ -0,0 +1,27 @@
+import { eventsSince } from "../events/event-window.js";
+import { isNotifyFailure } from "../events/notify.js";
+import { humanSeconds } from "../text/datetime.js";
+import { plural } from "../text/phrases.js";
+import { errorMessage, squash } from "../text/text.js";
+import { okOutcome, warnOutcome } from "./outcome.js";
+/** How far back the `notify` check looks for failed pages. */
+const NOTIFY_CHECK_WINDOW_MS = 24 * 3600_000;
+/** 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
+ * fail a scripted pre-flight. Never throws. `now` is the seam for the window's far edge. */
+export function checkNotify(root, config, now = Date.now()) {
+    if (!config?.notify)
+        return okOutcome("no notify command configured — pages are off");
+    try {
+        const failures = eventsSince(root, NOTIFY_CHECK_WINDOW_MS, now, isNotifyFailure);
+        if (failures.length === 0)
+            return okOutcome("configured — no failed pages in the last 24h");
+        const latest = failures[failures.length - 1];
+        const age = humanSeconds(Math.max(0, Math.round((now - latest.ts) / 1000)));
+        return warnOutcome(`${plural(failures.length, "failed page")} in the last 24h; latest ${age} ago: ${squash(String(latest.message), 200)}`);
+    }
+    catch (err) {
+        return warnOutcome(`could not read the event log for failed pages: ${errorMessage(err)}`);
+    }
+}

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

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { worktreesDir } from "../paths.js";
@@ -50,12 +51,12 @@ function argvNamesDir(command, dirs) {
         return false;
     });
 }
-/** True when an argv's RELATIVE worktree path (`node .tumwater/worktrees/qa/dist/src/cli.js
- * gui …`) is this repo's. Resolved against the process's cwd it must land here; one that lands
- * in a worktree that exists elsewhere belongs to another checkout's fleet and is not blamed on
- * this one. When the resolution lands nowhere — the cwd is unreadable, or is a scratch dir
- * since deleted (the leaked qa GUI's was), or the process chdir'd after exec — the worktree's
- * name is the evidence left: it counts only when this repo has a worktree by that name. */
+/** True when an argv's RELATIVE worktree path (`node .tumwater/worktrees/qa/dist/src/cli.js gui …`)
+ * is this repo's. Resolved against the process's cwd it must resolve here; one that resolves in a
+ * worktree that exists elsewhere belongs to another checkout's team and is not blamed on this one.
+ * When the resolution points nowhere — the cwd is unreadable, or is a scratch dir since deleted
+ * (the leaked qa GUI's was), or the process chdir'd after exec — the worktree's name is the
+ * evidence left: it counts only when this repo has a worktree by that name. */
 function relativeArgvIsOurs(command, cwd, root, dirs) {
     for (const [, rel = "", name = ""] of command.matchAll(RELATIVE_WORKTREE_ARG)) {
         if (cwd !== undefined) {
@@ -93,7 +94,7 @@ function descendantCount(children, pid) {
  * (absolute; or relative, confirmed by cwd where it can be — relativeArgvIsOurs) or when its
  * cwd lies under it: a leaked `node dist/test/test-runner.js` names no worktree at all.
  *
- * PPID 1 is what keeps the live fleet out: a running orchestrator's pi runs and build checks
+ * PPID 1 is what keeps the live team out: a running orchestrator's pi runs and build checks
  * have the orchestrator as parent, and the orchestrator and its supervisor run from the repo
  * root, never from a worktree, even when a detached `nohup` launch leaves them parentless.
  * (macOS always reparents an orphan to launchd, PID 1; on Linux a process under a child
@@ -104,7 +105,7 @@ function descendantCount(children, pid) {
  * 2/2): every process a run starts carries `TUMWATER_RUN=<harness pid>-<nonce>` in its
  * environment (appended to any inherited mark), wherever its cwd is — exactly where the
  * prompts send agents (scratch dirs under the system temp). A parentless process whose
- * every mark names a harness pid that is no longer alive is this fleet's orphan: nothing
+ * every mark names a harness pid that is no longer alive is this team's orphan: nothing
  * will reap it, because the run sweep that would have dies with its harness. A mark naming
  * ANY live harness is not reported — that harness's own sweep kills everything carrying the
  * mark when its run folds. A pid that died and was recycled by an unrelated process reads
@@ -198,7 +199,7 @@ export async function checkOrphans(root, probe = systemProcessProbe) {
         // A mark-caught orphan says which run marked it: the operator killing it wants to know
         // nothing else will, and the dead harness's pid is the evidence argv and cwd lacked.
         const mark = (marks.get(r.pid) ?? []).find((m) => harnessGone(m) === true);
-        const marked = mark !== undefined ? ` (run ${mark}; harness ${mark.split("-")[0]} exited)` : "";
+        const marked = mark !== undefined ? ` (run ${mark}; tumwater ${mark.split("-")[0]} exited)` : "";
         return `pid ${r.pid} (age ${r.etime}, cpu ${r.time}${tree}) ${truncate(command, ORPHAN_COMMAND_MAX)}${marked}`;
     });
     const more = orphans.length - listed.length;

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

@@ -1,13 +1,40 @@
-/** Render the report: a header line, one line per check (level, name, detail), and the
- * verdict. The name column is one width for every row — 12 columns by default, widened to
- * the longest name in this report ("backlog headings" is 16) so no row's detail starts a
- * few columns early — which keeps a report of short-named checks byte-identical to the
- * fixed-width output. Warnings never affect the exit code — only fails do. */
+import { plural } from "../text/phrases.js";
+/** One line per check (level, name, detail), the name column as wide as the longest name, at
+ * least 12. */
+function checkLines(checks) {
+    const nameWidth = checks.reduce((w, c) => Math.max(w, c.name.length), 12);
+    return checks.map((c) => `${c.level.padEnd(5)} ${c.name.padEnd(nameWidth)} ${c.detail}`);
+}
+/** Render the report: a header line, one line per check (level, name, detail), the routing
+ * table (each seam's label, its agent-qualified selector, and its backend), and the verdict.
+ * The name column is one width for every row — 12 columns by default, widened to the longest
+ * name in this report ("backlog headings" is 16) so no row's detail starts a few columns early
+ * — which keeps a report of short-named checks byte-identical to the fixed-width output.
+ * Warnings never affect the exit code — only fails do. */
 export function renderDoctor(report) {
-    const nameWidth = report.checks.reduce((w, c) => Math.max(w, c.name.length), 12);
-    const lines = [report.header];
-    for (const c of report.checks)
-        lines.push(`${c.level.padEnd(5)} ${c.name.padEnd(nameWidth)} ${c.detail}`);
+    const lines = [report.header, ...checkLines(report.checks)];
+    if (report.routing.length > 0) {
+        const width = report.routing.reduce((w, s) => Math.max(w, s.label.length), "job".length);
+        lines.push("routing: job · model · backend");
+        for (const s of report.routing)
+            lines.push(`  ${s.label.padEnd(width)}  ${s.selector}  (${s.backend})`);
+    }
+    lines.push(report.verdict);
+    return lines.join("\n");
+}
+/** The report with only its warn and fail checks; header, routing, and verdict stay. */
+export function problemsOnly(report) {
+    return { ...report, checks: report.checks.filter((c) => c.level !== "ok") };
+}
+/** `--problems`: the header, the warn and fail rows (name column sized over those rows alone), a
+ * line counting the hidden ok rows (left out when none), and the verdict — never the routing
+ * table. Takes the full report so it can count what it hides. */
+export function renderDoctorProblems(report) {
+    const shown = problemsOnly(report).checks;
+    const hidden = report.checks.length - shown.length;
+    const lines = [report.header, ...checkLines(shown)];
+    if (hidden > 0)
+        lines.push(`${plural(hidden, "ok check")} hidden — run tumwater doctor for the full report`);
     lines.push(report.verdict);
     return lines.join("\n");
 }

package/dist/src/doctor/doctor.js

@@ -1,44 +1,67 @@
+// vocabulary: plain
 import { loadConfigSafe } from "../config/config.js";
 import { envPath } from "../files/files.js";
-import { orchestratorAlive, readOrchestratorInfo } from "../fleet/orchestrator-info.js";
+import { orchestratorAlive, readOrchestratorInfo } from "../team/orchestrator-info.js";
 import { systemProcessProbe } from "../process/process-table.js";
 import { checkOrphans } from "./doctor-orphans.js";
-import { checkBudget, checkMaintenanceQuota, checkPause, checkQuietHours } from "./doctor-holds.js";
+import { checkBudget, checkClaudeWindow, checkErrorStreaks, checkMainRed, checkMaintenanceQuota, checkPause, checkProviderHolds, checkQuietHours } from "./doctor-holds.js";
+import { checkRootInstall } from "./doctor-install.js";
+import { checkNotify } from "./doctor-notify.js";
 import { checkLaunchServicesPorts } from "./doctor-launch-services.js";
 import { plural } from "../text/phrases.js";
 import { shortSha } from "../text/format.js";
-import { checkAgentBinary, checkBrief, checkBootstrap, checkBuild, checkBuildCheck, checkClaudeTranscripts, checkGitBinary, checkInit, checkDiskSpace, checkEventLog, checkMergeLock, checkNodeVersion, checkRepo, checkStateDir, checkWorktreePool, checkWorkInstances, } from "./doctor-checks.js";
-import { checkClaudeAuth, checkClaudeVersion, checkFallbackModel, checkTierModels } from "./doctor-model-checks.js";
-import { checkBacklogHeadings, checkFixClaims, checkStrandedPlans } from "./doctor-backlog.js";
+import { checkAgentBinary, checkBrief, checkBootstrap, checkBuild, checkBuildCheck, checkClaudeTranscripts, checkFunes, checkGitBinary, checkConfigKeyNames, checkInit, checkDiskSpace, checkEventLog, checkFlakyChecks, checkOpencodeVersion, checkMergeLock, checkNodeVersion, checkPiExtensions, checkProviderConcurrency, checkProviderContention, checkRepo, checkStateDir, checkWorktreePool, checkLeftoverRoleBranches, checkWorkInstances, } from "./doctor-checks.js";
+import { checkClaudeAuth, checkClaudeVersion, checkAnthroApiKey, checkFallbackChain, checkFallbackModel, checkImageInput, checkOpencode, checkTierModels } from "./doctor-model-checks.js";
+import { agentQualifiedSelector } from "../config/config-views.js";
+import { seamsInUse } from "../config/config-fallbacks.js";
+import { checkBacklogHeadings, checkFixClaims, checkLiveFinished, checkPlanDependencies, checkRefusedEntries, checkRegressedFixes, checkStaleQueuedMerges, checkStaleBugs, checkStalePrompts, checkStaleQuestions, checkStalledPlans, checkStrandedPlans, checkUncommittedBacklog, checkValidationGaps, checkWaitingBugs } from "./doctor-backlog.js";
 /** Pre-flight environment check (`tumwater doctor`). The harness's preconditions are
  * scattered across fail-fast checks that each command re-runs on its own (requireReadyRepo in
  * cli.ts walks git-binary → repo → tumwater.json → commits and stops at the first failure;
  * cmdRun adds pi-on-PATH and orchestrator-alive), so a user facing a partially initialized or
  * drifted environment gets one error at a time. doctor runs every check, reports each result
  * individually instead of stopping at the first failure, and exits 0/1 so it can be scripted —
- * the pre-flight sibling of `status --json`, which queries live fleet state while doctor
+ * the pre-flight sibling of `status --json`, which queries live team state while doctor
  * verdicts on the environment. Every check is read-only against .tumwater/ (works with or
  * without a running harness) and none runs the project's build/test: that can take minutes and
  * belongs in the review gate / red-main check, not a pre-flight. The individual checks live in
  * doctor-checks.ts and doctor-model-checks.ts; this module composes them into the report. */
+/** Wrap a possibly-absent doctor check into the report's `checks` spread: null omits the row
+ * entirely (the pi-extensions row for a team with no pi seam; the funes row when funes is not
+ * on PATH); an outcome contributes `{ name, ...outcome }`. */
+function appendNamedOutcome(name, outcome) {
+    return outcome === null ? [] : [{ name, ...outcome }];
+}
 /** Run every check in order and compose the report. Read-only against .tumwater/ by
  * construction — no check removes or repairs anything (the state-dir probe writes a temp file
  * and deletes it again; the orphan check reports processes, never signals them) — so doctor
  * works identically with or without a running harness. `probe` feeds the orphan and port
  * checks, so tests can pin the report without reading the host's process table. */
-export async function runDoctor(root, pathEnv = envPath(), probe = systemProcessProbe) {
+export async function runDoctor(root, pathEnv = envPath(), probe = systemProcessProbe, probeImages = "never") {
     // Loaded once for the checks that read config (repo's baseBranch); a broken file stays
     // undefined — checkInit reports it verbatim — so doctor still runs every other check.
     const { config } = loadConfigSafe(root);
+    // The routing table: every seam the config can spawn, with the selector each one runs on and
+    // the backend it routes to — read from the same one list the checks sweep, so an operator
+    // sees (and the checks cover) a claude fallback exactly like a primary seam. A broken config
+    // keeps it empty (the init check reports that separately).
+    const routing = config
+        ? seamsInUse(config).map((s) => ({
+            label: s.label,
+            selector: s.model !== undefined ? agentQualifiedSelector({ ...s, model: s.model }) : "no model declared",
+            backend: s.agent ?? "pi",
+        }))
+        : [];
     const info = readOrchestratorInfo(root);
     const header = orchestratorAlive(root, info) && info
-        ? `tumwater doctor — harness running (pid ${info.pid}${info.build ? `, build ${shortSha(info.build.sha)}${info.build.stale ? " — STALE" : ""}${info.build.restartBlocked ? " (restart blocked)" : ""}` : ""})`
-        : "tumwater doctor — harness not running";
+        ? `tumwater doctor — running (pid ${info.pid}${info.build ? `, version ${shortSha(info.build.sha)}${info.build.stale ? " — update available" : ""}${info.build.restartBlocked ? " (restart blocked)" : ""}` : ""})`
+        : "tumwater doctor — not running";
     const checks = [
         { name: "node", ...checkNodeVersion() },
         { name: "git binary", ...checkGitBinary(pathEnv) },
         { name: "repo", ...(await checkRepo(root, config)) },
         { name: "init", ...checkInit(root) },
+        { name: "config key names", ...checkConfigKeyNames(root) },
         { name: "brief", ...checkBrief(root) },
         // New-project bootstrap (plans/work-ratio.md, part 2/2): an active hold reports as ok
         // information, never a warning — a young project is not misconfigured.
@@ -46,32 +69,67 @@ export async function runDoctor(root, pathEnv = envPath(), probe = systemProcess
         { name: "pause", ...checkPause(root) },
         { name: "quiet hours", ...checkQuietHours(config) },
         { name: "budget", ...checkBudget(root, config, (orchestratorAlive(root, info) && info?.budget) || null) },
-        { name: "maintenance quota", ...checkMaintenanceQuota(root, config, orchestratorAlive(root, info)) },
-        { name: "fallback", ...checkFallbackModel(root, undefined, (orchestratorAlive(root, info) && info?.fallbackDemoted) || null) },
-        { name: "tier models", ...(await checkTierModels(root)) },
+        { name: "claude window", ...checkClaudeWindow(root, undefined, (orchestratorAlive(root, info) && info?.chain) || undefined, config) },
+        { name: "provider waits", ...checkProviderHolds(root) },
+        { name: "maintenance allowance", ...checkMaintenanceQuota(root, config, orchestratorAlive(root, info)) },
+        { name: "provider concurrency", ...checkProviderConcurrency(config, root) },
+        { name: "provider contention", ...checkProviderContention(root, config) },
+        { name: "repeated failures", ...checkErrorStreaks(root, config) },
+        { name: "main's check", ...checkMainRed(root, config) },
+        { name: "over-cap model", ...checkFallbackModel(root, undefined, (orchestratorAlive(root, info) && info?.fallbackDemoted) || null) },
+        { name: "fallback chain", ...(await checkFallbackChain(root)) },
+        { name: "models for each tier", ...(await checkTierModels(root)) },
+        { name: "image input", ...(await checkImageInput(root, undefined, undefined, undefined, probeImages, pathEnv)) },
         { name: "claude auth", ...(await checkClaudeAuth(root, pathEnv)) },
+        { name: "claude api key", ...(await checkAnthroApiKey(root, undefined, pathEnv)) },
         { name: "claude version", ...(await checkClaudeVersion(root, pathEnv)) },
-        { name: "agent binary", ...checkAgentBinary(root, pathEnv) },
+        { name: "opencode version", ...(await checkOpencodeVersion(root, pathEnv)) },
+        { name: "opencode", ...(await checkOpencode(root, pathEnv)) },
+        { name: "backend binary", ...checkAgentBinary(root, pathEnv) },
         // The transcript total is informational and only read when a seam routes to claude.
         { name: "claude transcripts", ...checkClaudeTranscripts(config) },
+        // The receive-side guards name what a running team skips, so an operator tool meant for the
+        // team (a pi package, an extension file, an mcp.json server, or funes) does not vanish
+        // silently. Each check returns null to omit its row: the pi row for a team with no pi seam,
+        // the funes row when funes is not on PATH.
+        ...(appendNamedOutcome("pi extensions", checkPiExtensions(config, undefined, pathEnv))),
+        ...(appendNamedOutcome("funes", checkFunes(config, pathEnv))),
         { name: "state dir", ...checkStateDir(root) },
         { name: "event log", ...checkEventLog(root) },
+        { name: "notify", ...checkNotify(root, config) },
         { name: "merge lock", ...checkMergeLock(root) },
-        { name: "worktree pool", ...checkWorktreePool(root) },
-        { name: "work instances", ...checkWorkInstances(root, config) },
+        { name: "workspaces", ...checkWorktreePool(root) },
+        { name: "parallel instances", ...checkWorkInstances(root, config) },
+        { name: "leftover role branches", ...(await checkLeftoverRoleBranches(root, config)) },
         // The disk floor (plans/disk-floor.md, part 1/4): a broken config stays undefined (checkInit
         // reports it), so the check falls back to the 10 GB default rather than skipping itself.
         { name: "disk space", ...checkDiskSpace(root, config?.diskHoldGB ?? 10, config?.diskReclaimGB ?? 40) },
-        { name: "project check", ...checkBuildCheck(root, config) },
-        { name: "fix claims", ...checkFixClaims(root) },
-        { name: "stranded plans", ...checkStrandedPlans(root) },
+        { name: "check", ...checkBuildCheck(root, config) },
+        { name: "root install", ...checkRootInstall(root) },
+        // The review gate's flake memory, surfaced read-only: naming which checks the gate kept
+        // excusing as flakes (ok/warn only, so a flaky suite never fails a scripted pre-flight).
+        { name: "flaky checks", ...checkFlakyChecks(root) },
+        { name: "claimed bugs", ...checkFixClaims(root) },
+        { name: "validation gaps", ...checkValidationGaps(root) },
+        { name: "plans stuck in Planned", ...checkStrandedPlans(root) },
         { name: "backlog headings", ...checkBacklogHeadings(root) },
-        // The running fleet's own view of its build (staleness and what auto-restart made of it)
+        { name: "backlog archive", ...checkLiveFinished(root) },
+        { name: "refusals", ...checkRefusedEntries(root) },
+        { name: "stalled plans", ...checkStalledPlans(root) },
+        { name: "plan dependencies", ...checkPlanDependencies(root) },
+        { name: "stale questions", ...checkStaleQuestions(root) },
+        { name: "stale bugs", ...checkStaleBugs(root) },
+        { name: "waiting bugs", ...checkWaitingBugs(root) },
+        { name: "regressed fixes", ...checkRegressedFixes(root) },
+        { name: "stale merge-queue entries", ...checkStaleQueuedMerges(root, Date.now()) },
+        { name: "stale prompts", ...checkStalePrompts(root, Date.now()) },
+        { name: "uncommitted backlog", ...(await checkUncommittedBacklog(root, config)) },
+        // The running team's own view of its build (staleness and what auto-restart made of it)
         // when there is one; without it the check still stands on its own git comparison.
-        { name: "build", ...(await checkBuild(root, undefined, undefined, (orchestratorAlive(root, info) && info?.build) || null)) },
+        { name: "update", ...(await checkBuild(root, undefined, undefined, (orchestratorAlive(root, info) && info?.build) || null)) },
         { name: "orphans", ...(await checkOrphans(root, probe)) },
-        { name: "mach ports", ...(await checkLaunchServicesPorts(probe)) },
+        { name: "macOS port leak", ...(await checkLaunchServicesPorts(probe)) },
     ];
     const problems = checks.filter((c) => c.level === "fail").length;
-    return { header, checks, verdict: problems === 0 ? "ready to run" : plural(problems, "problem") };
+    return { header, checks, routing, verdict: problems === 0 ? "ready to run" : plural(problems, "problem") };
 }

package/dist/src/doctor/image-probe.js

@@ -0,0 +1,244 @@
+/** The doctor's live image-input probe (plans/image-input.md "Doctor", part 2/5): a claimed
+ * image-input capability in pi's models.json is only a claim — doctor shows each claimed model
+ * a real image and checks the answer. This module owns three things: the in-process PNG
+ * generator (a random 4-digit code drawn with a built-in 5×7 bitmap, encoded with
+ * `zlib.deflateSync` + `zlib.crc32` is newer than the `>=20.3` node floor, so the CRC-32 here is
+ * hand-rolled), the probe runner (the resolved pi binary in a run's environment, bounded like
+ * the doctor's other binary probes), and the `.tumwater/state/image-probes.json` cache the
+ * doctor check reads back. No new dependency; runs entirely offline against the operator's pi. */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomInt } from "node:crypto";
+import zlib from "node:zlib";
+import { PiStreamParser } from "../pi/pi-stream.js";
+import { resolveAgentBin } from "../pi/pi-bin.js";
+import { imageProbesPath } from "../paths.js";
+import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
+import { boundedProbe } from "./probe.js";
+/** How long a cached image-probe verdict stays valid while the claim is unchanged (7 days) —
+ * a model's endpoint can change underneath a stale pass, so the answer is dated. */
+export const IMAGE_PROBE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** The probe's deadline (90 s): a local model may need to load, far beyond the quick credential
+ * probes, but a doctor run is still a pre-flight — a hung backend must lose, not stall the
+ * report. */
+const PROBE_TIMEOUT_MS = 90_000;
+/** Cap on the probe's captured stdout, the same guard as the auth probes: a doctor run must not
+ * grow an unbounded buffer off a runaway log. */
+const PROBE_MAX_OUTPUT_BYTES = 1024 * 1024;
+/** The cache-file key for one seam — agent/provider/model, the natural identity of a team
+ * model, joined on `/` (agent and provider never contain it and a model id is fully qualified,
+ * so the key cannot collide with another seam's). */
+export function imageProbeKey(agent, provider, model) {
+    return [agent ?? "", provider ?? "", model ?? ""].join("/");
+}
+/** Whether a cached entry still stands for the current claim: it exists, it recorded a real
+ * verdict (never `could-not-verify`, which is never cached), it tested the image-input claim,
+ * and it is younger than the TTL. */
+export function imageProbeEntryFresh(entry, now = Date.now()) {
+    return (entry !== undefined &&
+        (entry.verdict === "pass" || entry.verdict === "fail") &&
+        entry.claim &&
+        now - entry.at <= IMAGE_PROBE_TTL_MS);
+}
+/** Read the probe cache, or an empty cache when the file is missing or torn (the harness's
+ * no-data policy: a crashed writer never takes down a reader). */
+export function readImageProbeCache(root) {
+    return readJsonFile(imageProbesPath(root)) ?? {};
+}
+/** Write the probe cache atomically (tmp+rename) so a concurrent reader never sees a torn
+ * file. */
+export function writeImageProbeCache(root, cache) {
+    writeJsonAtomic(imageProbesPath(root), cache);
+}
+// ── PNG generator ─────────────────────────────────────────────────────────────────────────
+/** Each digit as 7 rows of 5 bits, '1' = drawn (black); the standard 5×7 seven-segment-ish
+ * font, big enough for a vision model to read and small enough to stay a trivial payload. */
+const DIGIT_BITMAP = {
+    "0": ["01110", "10001", "10011", "10101", "11001", "10001", "01110"],
+    "1": ["00100", "01100", "00100", "00100", "00100", "00100", "01110"],
+    "2": ["01110", "10001", "00001", "00110", "01000", "10000", "11111"],
+    "3": ["11111", "00010", "00100", "00010", "00001", "10001", "01110"],
+    "4": ["00010", "00110", "01010", "10010", "11111", "00010", "00010"],
+    "5": ["11111", "10000", "11110", "00001", "00001", "10001", "01110"],
+    "6": ["00110", "01000", "10000", "11110", "10001", "10001", "01110"],
+    "7": ["11111", "00001", "00010", "00100", "01000", "01000", "01000"],
+    "8": ["01110", "10001", "10001", "01110", "10001", "10001", "01110"],
+    "9": ["01110", "10001", "10001", "01111", "00001", "00010", "01100"],
+};
+/** A hand-rolled CRC-32 (the PNG chunk checksum): `zlib.crc32` is newer than the `>=20.3` node
+ * floor, so this bitwise table version is the one home of the polynomial. */
+const CRC32_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = (CRC32_TABLE[(c ^ (buf[i] ?? 0)) & 0xff] ?? 0) ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** One PNG chunk: 4-byte big-endian length, the 4-byte ASCII type, the data, and the CRC over
+ * type+data. */
+function pngChunk(type, data) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length, 0);
+    const typeBuf = Buffer.from(type, "ascii");
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
+    return Buffer.concat([len, typeBuf, data, crc]);
+}
+/** A PNG showing `code` black on white, drawn with the 5×7 bitmap scaled `scale`-fold (each
+ * font cell becomes a `scale`×`scale` block) and one `scale`-wide gap between digits. Truecolor
+ * (color type 2) so any reader handles it and the decode-check in the tests is trivial. Exported
+ * for tests (and the doctor's own validity check of a generated image). */
+export function makeProbePng(code, scale = 8) {
+    const digits = [...code].map((d) => DIGIT_BITMAP[d] ?? DIGIT_BITMAP["0"]);
+    const width = digits.length * 5 * scale + (digits.length - 1) * scale;
+    const height = 7 * scale;
+    // Truecolor RGB scanlines, each prefixed with filter byte 0 (none).
+    const raw = Buffer.alloc(height * (1 + width * 3));
+    for (let y = 0; y < height; y++) {
+        const rowStart = y * (1 + width * 3);
+        raw[rowStart] = 0;
+        for (let x = 0; x < width; x++) {
+            // Which font cell does this pixel fall in?
+            const cell = Math.floor(x / (5 * scale + scale));
+            const inCellX = x - cell * (5 * scale + scale);
+            const cellDigit = digits[cell];
+            const row = Math.floor(y / scale);
+            const col = Math.floor(inCellX / scale);
+            const bit = inCellX < 5 * scale && cellDigit !== undefined
+                ? ((cellDigit[row] ?? "")[col] ?? "")
+                : "";
+            const on = bit === "1";
+            const p = rowStart + 1 + x * 3;
+            raw[p] = on ? 0 : 255;
+            raw[p + 1] = on ? 0 : 255;
+            raw[p + 2] = on ? 0 : 255;
+        }
+    }
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 2; // color type: truecolor RGB
+    const idat = zlib.deflateSync(raw, { level: 9 });
+    return Buffer.concat([
+        Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+        pngChunk("IHDR", ihdr),
+        pngChunk("IDAT", idat),
+        pngChunk("IEND", Buffer.alloc(0)),
+    ]);
+}
+/** A random 4-digit code for one probe attempt. */
+function randomCode() {
+    let out = "";
+    for (let i = 0; i < 4; i++)
+        out += String(randomInt(0, 10));
+    return out;
+}
+// ── Probe runner ──────────────────────────────────────────────────────────────────────────
+/** Parse the resolved probe's stdout (pi's `--mode json` event stream) the same way a real run
+ * is parsed, so a live probe sees the same final text and error classification the harness
+ * would. */
+function parseProbeOutput(stdout) {
+    const parser = new PiStreamParser();
+    parser.feed(stdout);
+    return {
+        finalText: parser.finalText,
+        configError: parser.configError,
+        transientRateLimit: parser.transientRateLimit,
+        transientBackend: parser.transientBackend,
+    };
+}
+/** Whether an answer looks like a (wrong) read of the 4-digit code rather than a refusal: the
+ * text contains a 4-digit run of digits (e.g. "The number is 5825."). A model that cannot see
+ * at all does not emit a number. */
+function isFourDigitNumber(text) {
+    return /\b\d{4}\b/.test(text);
+}
+/** Probe one claimed pi seam with a real image (plans/image-input.md "Doctor"). Runs the
+ * resolved pi binary in a run's environment (the caller passes `env`, typically
+ * `childEnv({ PATH: pathEnv })` which inherits `PI_CODING_AGENT_DIR`, so the probe reads the
+ * same models.json a real tick would):
+ *
+ *   `pi --print --mode json --no-session --no-tools --no-mcp --provider P --model M
+ *        --thinking <level> @<png> "Reply with only the 4-digit number shown in the image."`
+ *
+ * Pass: the final assistant text contains the code. A wrong answer retries once with a fresh
+ * code (a misread is not blindness). Two wrong answers that are not both numbers fail (a
+ * refusal or empty answer is blindness), and so does a 4xx. Two wrong *numbers* — the model
+ * read a number, wrongly — cannot be told from a flaky misread, so it is `could-not-verify`
+ * rather than `fail` and is never cached: the next doctor run probes again instead of turning
+ * a capable seam text-only for a week. A timeout, spawn failure, 429, 5xx, or connection error
+ * is also `could-not-verify` — it says nothing about capability and is never cached. `code` is
+ * a test seam (a real probe always draws a fresh random code); `env` and `timeoutMs` are
+ * injectable so tests need no real pi. */
+export async function runImageProbe(config, seam, env, timeoutMs = PROBE_TIMEOUT_MS, code) {
+    const envBin = env.TUMWATER_PI_BIN?.trim();
+    // Resolve from the run's own environment (env override → config), exactly as a real tick's
+    // spawn would rather than only the harness process env — so tests can point a fake pi there.
+    const bin = envBin
+        ? envBin.includes("/")
+            ? path.resolve(envBin)
+            : envBin
+        : resolveAgentBin(config).bin;
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tumwater-image-probe-"));
+    const wrong = []; // the per-attempt "answered …" detail for a wrong answer
+    const misread = []; // whether each wrong answer was a (wrong) 4-digit number
+    try {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const thisCode = code ?? randomCode();
+            const png = makeProbePng(thisCode);
+            const pngPath = path.join(dir, `probe-${attempt}.png`);
+            fs.writeFileSync(pngPath, png);
+            const args = ["--print", "--mode", "json", "--no-session", "--no-tools", "--no-mcp"];
+            if (seam.provider)
+                args.push("--provider", seam.provider);
+            if (seam.model)
+                args.push("--model", seam.model);
+            if (seam.thinking)
+                args.push("--thinking", seam.thinking);
+            args.push(`@${pngPath}`, "Reply with only the 4-digit number shown in the image.");
+            const result = await boundedProbe(bin, args, env, timeoutMs, PROBE_MAX_OUTPUT_BYTES);
+            if (result === null)
+                return { verdict: "could-not-verify", detail: "the probe could not run or timed out" };
+            const parsed = parseProbeOutput(result.stdout);
+            if (parsed.configError)
+                return { verdict: "fail", detail: "the provider rejected the request (4xx)" };
+            if (parsed.transientRateLimit)
+                return { verdict: "could-not-verify", detail: "the provider rate-limited the request (429)" };
+            if (parsed.transientBackend)
+                return { verdict: "could-not-verify", detail: "the provider backend failed (5xx or connection)" };
+            const text = parsed.finalText.trim();
+            if (text.includes(thisCode))
+                return { verdict: "pass", detail: `answered "${text}"` };
+            // A wrong 4-digit number says "I looked and got the digits wrong"; a refusal or empty
+            // answer says "I cannot see". The drawn code is exactly 4 digits, so a 4-digit answer is
+            // a plausible (wrong) read.
+            misread.push(isFourDigitNumber(text));
+            wrong.push(text ? `answered "${text}"` : "answered nothing");
+        }
+        // A refusal or empty answer on either attempt is blindness — the two-strikes rule: fail,
+        // cached. Two wrong *numbers* cannot be told from a flaky misread, so it is could-not-verify
+        // and never cached: the next doctor run probes again instead of turning a capable seam
+        // text-only for a week. Either way the detail names what the model said, so the doctor
+        // line, the alert, and a bug report can tell blindness from a misread.
+        return misread[0] && misread[1]
+            ? {
+                verdict: "could-not-verify",
+                detail: `two misreads (${wrong.join(", ")}) — the model read a number, wrongly; not blindness, re-probe on the next doctor run`,
+            }
+            : { verdict: "fail", detail: `two wrong answers (${wrong[1]})` };
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/src/doctor/probe.js

@@ -0,0 +1,64 @@
+import { spawn } from "node:child_process";
+import { releaseChildHandles, signalTree } from "../process/process.js";
+/** One bounded probe of a resolved binary: `null` when the spawn threw, the child errored,
+ * the deadline passed, or stdout overran `maxOutputBytes` — every case the caller must read as
+ * "could not check", never as a verdict. The child runs detached and at the deadline (or on
+ * overrun) its whole process group is SIGKILLed and the promise settles, because `'close'`
+ * waits for the stdio pipes and a grandchild holding them open would otherwise leave the
+ * promise pending past the deadline and hang the caller (the same trap git-run.ts's bounded
+ * spawn closes for git). stderr is ignored rather than piped, since nothing reads it and a
+ * full stderr pipe would block the child. `timeoutMs` and `maxOutputBytes` are test seams;
+ * production callers pass their own named constants. One home of the shape, shared by the
+ * model checks' credential/version probes, the tier-model probes, and the image-input probe —
+ * before the split each doctor module carried its own byte-for-byte copy. */
+export function boundedProbe(bin, args, env, timeoutMs, maxOutputBytes) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            // Detached so the deadline's signalTree reaches a grandchild too; stderr is ignored
+            // rather than piped, since nothing reads it and a full stderr pipe would block the
+            // child until the deadline.
+            child = spawn(bin, args, {
+                cwd: process.cwd(),
+                detached: true,
+                stdio: ["ignore", "pipe", "ignore"],
+                env,
+            });
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        let out = "";
+        let bytes = 0;
+        let settled = false;
+        let timer;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            // Destroy the captured stdout and unref the process handle (releaseChildHandles): a
+            // grandchild that escaped the group and holds the pipe's write end would otherwise keep
+            // the process's event loop alive though the probe already has its answer.
+            releaseChildHandles(child);
+            resolve(result);
+        };
+        // Deadline or runaway output: kill the whole group, tear down the handles, and settle —
+        // do not wait for a `'close'` the group may never deliver.
+        const abort = () => {
+            signalTree(child, "SIGKILL");
+            settle(null);
+        };
+        timer = setTimeout(abort, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            out += chunk.toString("utf8");
+            bytes += chunk.length;
+            if (bytes > maxOutputBytes)
+                abort();
+        });
+        child.on("error", () => settle(null));
+        child.on("close", (code) => settle({ code, stdout: out }));
+    });
+}