tumwater 0.2.0 → 0.3.0

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

@@ -0,0 +1,303 @@
+/** The doctor's checks that inspect the project's own on-disk state, disk and build,
+ * split out of doctor-checks.ts (whose environment/repo file still holds the toolchain and
+ * setup checks — the node/git/exec binaries, the repo/init/config/brief/bootstrap setup, the
+ * agent backends' CLI versions and the operator pi-extension/funes coordination). This module
+ * holds the checks that look at the project itself: a writable .tumwater (checkStateDir), a
+ * readable event feed (checkEventLog), enough free disk (checkDiskSpace), a declared project
+ * check (checkBuildCheck), the review gate's flake memory (checkFlakyChecks) and build
+ * provenance (checkBuild). Read-only like every doctor check; the private helpers each cluster
+ * uses (sweepStaleProbes, eventLogHistoryPhrase, firstEventLine, diskReclaimPhrase,
+ * checkDurationPhrase, currentHead) live here beside the checks that use them. doctor.ts stays
+ * the composition layer that calls each check in fixed order. */
+import fs from "node:fs";
+import path from "node:path";
+import { detectBuildCheck, mergeCommandOf } from "../build/build-check-detect.js";
+import { isPassingFullCheck } from "../build/build-check-events.js";
+import { buildStaleness, isSelfHosted, readBuildInfo, STALE_INPUTS_LABEL } from "../build/build-info.js";
+import { dirEntryNames, statOrNull } from "../files/files.js";
+import { refSha } from "../git/git.js";
+import { STATE_DIR, eventsArchivePath, eventsLogPath } from "../paths.js";
+import { BYTES_PER_GB, diskVolumePath, sampleFreeBytes } from "../gates/disk-gate.js";
+import { DAY_MS, dayKey } from "../text/datetime.js";
+import { errorMessage } from "../text/text.js";
+import { lowerMedian } from "../collections.js";
+import { formatGB, shortSha } from "../text/format.js";
+import { eventLogState, readEventsSince } from "../events/event-window.js";
+import { EVENTS_KEEP } from "../events/events.js";
+import { finiteNumber } from "../files/json-object.js";
+import { agree, plural, shortSpanPhrase } from "../text/phrases.js";
+import { flakeCounts, KNOWN_FLAKE_WINDOW_MS, loadQuarantine } from "../review/known-flakes.js";
+import { quarantineWarning } from "../baseline/main-guardrails.js";
+import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
+/** .tumwater writable — absent is fine (created on first run); present, prove it by writing
+ * and deleting a temp file inside. The probe leaves the dir's listing unchanged after the run.
+ * The write is the property under test: only a write that fails is "not writable", so the
+ * cleanup below — deleting the probe, sweeping stales — never vetoes a dir the write just
+ * proved writable, and a probe left over is swept rather than accumulated. */
+export function checkStateDir(root) {
+    const dir = path.join(root, STATE_DIR);
+    if (!fs.existsSync(dir))
+        return okOutcome("absent — created on first run");
+    const probe = path.join(dir, `.doctor-probe-${process.pid}`);
+    try {
+        fs.writeFileSync(probe, "");
+    }
+    catch (err) {
+        // A partial write may already have created the file — sweep it like any other leftover.
+        sweepStaleProbes(dir);
+        return failOutcome(`not writable: ${errorMessage(err)}`);
+    }
+    // The write proved writability. Deleting the probe is cleanup, not measurement: a removal
+    // failure must not turn a succeeded write into a false alarm, and the stray is collected by
+    // the sweep below (or a later pass's sweep).
+    try {
+        fs.rmSync(probe);
+    }
+    catch {
+        // Best-effort — the stray is swept in a moment.
+    }
+    sweepStaleProbes(dir);
+    return okOutcome("writable");
+}
+/** Best-effort removal of every `.doctor-probe-*` file in `dir` — the only artifact
+ * checkStateDir creates, so any present probe is a leftover: a prior run killed between its
+ * write and delete, a partial write above, or a removal that failed. Removed one at a time so
+ * a single unremovable probe cannot stop the sweep. */
+function sweepStaleProbes(dir) {
+    for (const name of dirEntryNames(dir)) {
+        if (!name.startsWith(".doctor-probe-"))
+            continue;
+        try {
+            fs.rmSync(path.join(dir, name));
+        }
+        catch {
+            // Best-effort — leave it for the next pass.
+        }
+    }
+}
+/** Event log readable — open and parse events.jsonl (and its rotated archive) so the one
+ * failure the selfcheck role is chartered to catch — a feed that hid itself — is named by the
+ * pre-flight too. An absent or empty log is fine: a young project writes its first event on the
+ * first run. A present-but-unparseable log (a directory at the path, a permission failure, or
+ * every complete line corrupt) fails, because every observer — selfcheck, the TUI/GUI feeds,
+ * `logs`, `report` — reads that one feed. Read-only. */
+export function checkEventLog(root) {
+    let state;
+    try {
+        state = eventLogState(root);
+    }
+    catch (err) {
+        return failOutcome(`could not read ${eventsLogPath(root)}: ${errorMessage(err)}`);
+    }
+    if (state === "unreadable")
+        return failOutcome(`unreadable: ${eventsLogPath(root)} — the team's event feed cannot be read`);
+    if (state === "empty")
+        return okOutcome("no events yet");
+    const history = eventLogHistoryPhrase(root);
+    return okOutcome(history ? `readable: ${eventsLogPath(root)} — ${history}` : `readable: ${eventsLogPath(root)}`);
+}
+/** The `history from <date>, <n> files` phrase for checkEventLog's ok detail (G4): the first
+ * complete line of the oldest event-log generation present names how far back the kept history
+ * reaches, and the count is how many generations (live file plus archives) exist. Undefined
+ * when no generation parses an event, so a readable-but-shapeless log still reads as readable. */
+function eventLogHistoryPhrase(root) {
+    const present = [];
+    const livePath = eventsLogPath(root);
+    if (statOrNull(livePath))
+        present.push(livePath);
+    for (let gen = 1; gen <= EVENTS_KEEP; gen++) {
+        const archive = eventsArchivePath(root, gen);
+        if (statOrNull(archive))
+            present.push(archive);
+    }
+    if (present.length === 0)
+        return undefined;
+    const oldest = present[present.length - 1];
+    const ev = firstEventLine(oldest);
+    if (!ev || typeof ev.ts !== "number")
+        return undefined;
+    const noun = plural(present.length, "file", "files");
+    return `history from ${dayKey(ev.ts)}, ${noun}`;
+}
+/** Parse the first complete line of an append-only JSONL `file`, or null when it is unreadable
+ * or does not parse. Reads only the first chunk — the event log is up to 16 MB a generation,
+ * and a doctor pre-flight should not slurp the oldest archive just to name its first day. */
+function firstEventLine(file) {
+    try {
+        const fd = fs.openSync(file, "r");
+        try {
+            const buf = Buffer.alloc(4096);
+            const n = fs.readSync(fd, buf, 0, buf.length, 0);
+            const line = buf.toString("utf8", 0, n).split("\n")[0] ?? "";
+            if (!line)
+                return null;
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/** Disk floor (plans/disk-floor.md, parts 1/4 and 2/4) — is there room on the volume the
+ * worktrees live on? Fail below `diskHoldGB`, the same floor the running team holds new work
+ * at, so doctor and the gate agree on when the disk is a problem. Warn in the band between
+ * `diskHoldGB` and `diskReclaimGB`: pressure reclaim will delete ignored build outputs from
+ * idle worktrees but the team still runs. Ok at or above `diskReclaimGB` (or when reclaim is
+ * disabled and free space is above the hold). A statfs failure is a warning, not a failure: an
+ * unmeasurable volume never holds the team, so it must not fail a scripted pre-flight. The
+ * detail names the measured path, the free GB to one decimal, and the floor. `holdGB` 0
+ * disables the hold, so a free space above `reclaimGB`'s own band (or `reclaimGB` 0) passes.
+ * After a successful sample the detail also carries `diskReclaimPhrase` (what `disk_reclaim`
+ * passes freed over the last 24 h); it is informational and never changes the level. */
+export function checkDiskSpace(root, holdGB, reclaimGB, sample = sampleFreeBytes) {
+    const where = diskVolumePath(root);
+    const free = sample(root);
+    if (free === null)
+        return warnOutcome(`cannot measure free space at ${where} (statfs failed) — the disk hold is off for this process`);
+    const freeGB = free / BYTES_PER_GB;
+    const freeText = `${formatGB(freeGB)} free at ${where}`;
+    const phrase = diskReclaimPhrase(readEventsSince(root, DAY_MS).events);
+    const withReclaim = (detail) => (phrase ? `${detail} · ${phrase}` : detail);
+    if (holdGB > 0 && freeGB < holdGB)
+        return failOutcome(withReclaim(`${freeText} — below the ${holdGB} GB diskHoldGB floor; the team waits to start new work until space recovers`));
+    if (reclaimGB > 0 && freeGB < reclaimGB)
+        return warnOutcome(withReclaim(`${freeText} — below the ${reclaimGB} GB diskReclaimGB threshold; a pressure reclaim pass deletes ignored build outputs from idle worktrees`));
+    const floor = holdGB > 0 ? `above the ${holdGB} GB floor` : "diskHoldGB is 0 (hold disabled)";
+    return okOutcome(withReclaim(`${freeText}, ${floor}`));
+}
+/** The `reclaim in the last 24h freed …` phrase for the `disk space` row: the summed
+ * `freedGB` of the `disk_reclaim` passes, their count, and how many ran under pressure (an
+ * event without a `mode` counts as pressure, like its feed line). Each pass is a point event,
+ * so summing cannot straddle the window edge. Undefined when no pass ran. */
+export function diskReclaimPhrase(events) {
+    const passes = events.filter((e) => e.type === "disk_reclaim");
+    if (passes.length === 0)
+        return undefined;
+    const freed = passes.reduce((sum, e) => sum + finiteNumber(e.freedGB, 0), 0);
+    const pressure = passes.filter((e) => (typeof e.mode === "string" && e.mode ? e.mode : "pressure") === "pressure").length;
+    const base = `reclaim in the last 24h freed ${formatGB(freed)} over ${plural(passes.length, "pass", "passes")}`;
+    return pressure > 0 ? `${base}, ${pressure} under pressure` : base;
+}
+/** The `passing merge checks …` phrase for the `check` row: median and slowest wall clock of
+ * the passed full-suite runs (`merge`, `batch`, `baseline` scopes — a `gate` check can run a
+ * subset, and failed or skipped runs do not measure a full pass). The lower median keeps the
+ * figure a run that happened. Undefined when no event qualifies. */
+export function checkDurationPhrase(events) {
+    const durations = events
+        .filter(isPassingFullCheck)
+        .map((e) => finiteNumber(e.durationMs, 0))
+        .filter((ms) => ms > 0);
+    if (durations.length === 0)
+        return undefined;
+    const median = lowerMedian(durations);
+    const slowest = Math.max(...durations);
+    return `passing merge checks in the last 24h took ${shortSpanPhrase(median)} median, ${shortSpanPhrase(slowest)} slowest (${plural(durations.length, "run")})`;
+}
+/** Declared project check — names what the review gate's deterministic pre-check, the
+ * red-main baseline, and redeploy's green check will run, without running it: a configured
+ * `check.command` (plans/portability.md §6/7), else the npm auto-detection. None declared is
+ * a warn, not informational (the 2026-09-05 stance predates non-npm targets being supported,
+ * when a warn would have been noise no operator could act on — with `check.command` available
+ * the warning is actionable): the three gates degrade to "no check" and a silently absent
+ * safety layer is the failure this check exists to surface. Warn does not fail the exit code
+ * (the fallback check's precedent, doctor-model-checks.ts's checkFallbackModel). */
+export function checkBuildCheck(root, config) {
+    const check = detectBuildCheck(root, config ?? undefined);
+    if (!check)
+        return warnOutcome("none declared — the review gate's build pre-check, the red-main baseline, and redeploy's green check are all off (set `check.command` in tumwater.json for a non-npm repo)");
+    // The in-lock command from mergeCommandOf (absent mergeCommand falls back to the gate
+    // command): the row names which command the merge lock runs and where the full check lands,
+    // facts a reader cannot get from detectBuildCheck alone. The after-merge roles are not named
+    // here — they live under `review`, which this slice does not hold, and the `review` row in
+    // docs/config.md documents them.
+    const lockPhrase = (() => {
+        const mc = mergeCommandOf(config ?? undefined);
+        return mc !== undefined
+            ? `merge lock runs ${mc}, full check after merging`
+            : "full check in the merge lock";
+    })();
+    const phrase = checkDurationPhrase(readEventsSince(root, DAY_MS).events);
+    const withTiming = (detail) => okOutcome(`${detail} · ${lockPhrase}${phrase ? ` · ${phrase}` : ""}`);
+    if (check.kind === "command") {
+        const where = path.relative(root, check.cwd);
+        return withTiming(where ? `${check.command} (cwd ${where})` : check.command);
+    }
+    const where = path.relative(root, check.rootDir);
+    return withTiming(where ? `npm ${check.script} in ${where}` : `npm ${check.script}`);
+}
+/** The review gate's flake memory surfaced read-only: names which checks the gate kept excusing as
+ * flakes over its own KNOWN_FLAKE_WINDOW_MS window. The gate logs `gate check failed then passed on
+ * retry — flaky: <headline>` for each failure that passed on its one immediate re-run, and the
+ * in-lock merge check logs the same under MERGE_FLAKY_WARNING_PREFIX when its kept-pin retry passes
+ * (src/review/known-flakes.ts); that record is internal to the gate's matching, so a genuinely
+ * flaky check silently burns a re-run per merge and hides real instability — exactly the
+ * information that explains intermittent rejections. This check reads the same window and folds the
+ * same normalized headline the gate matches with (flakeCounts, so the prefix slice-offset and
+ * cluster normalization cannot drift), and warns only when a normalized check flapped more than
+ * once, so a routine one-off flake stays quiet. ok/warn only — never a fail — so a flaky suite
+ * cannot fail a scripted doctor pre-flight (the checkStalledPlans precedent; the exit-code rule is
+ * outcome.ts's). */
+export function checkFlakyChecks(root, now = Date.now()) {
+    const { events } = readEventsSince(root, KNOWN_FLAKE_WINDOW_MS);
+    const flapped = flakeCounts(events).filter(([, n]) => n >= 2);
+    const phrases = [];
+    if (flapped.length > 0) {
+        const render = ([k, n]) => `"${k}" ×${n}`;
+        const [first, ...rest] = flapped;
+        const more = rest.length > 0 ? ` (and ${rest.length} more: ${rest.map(render).join(", ")})` : "";
+        phrases.push(`${agree(flapped.length, "check", "checks")} flapped more than once in the last 24h: ${render(first)}${more}`);
+    }
+    const q = quarantineWarning(loadQuarantine(root), now);
+    if (q !== null)
+        phrases.push(q);
+    if (phrases.length === 0)
+        return okOutcome("no check flapped more than once in the last 24h");
+    return warnOutcome(phrases.join("; "));
+}
+/** Build provenance — is the harness about to run (this process's dist/) the code main
+ * describes? Only meaningful when this project IS the harness (isSelfHosted); elsewhere the
+ * stamp is reported as-is. A stale build is a warning, not a failure: the team runs, just not
+ * the newest code, and auto-restart (or a rebuild + restart) resolves it. `info`, `head` and
+ * `running` are injectable so tests can exercise every branch without compiling anything. */
+export async function checkBuild(root, info = readBuildInfo(), head = undefined, 
+/** What the running orchestrator published about this build (orchestrator.json), when one is
+ * up. A stale build whose restart was REFUSED must not be reported with the boilerplate
+ * "auto-restart does this for a running team": nothing will happen until main moves, and
+ * doctor is where an operator goes to find out why. */
+running = null) {
+    if (!info)
+        return okOutcome("no build stamp — dist/ compiled without `npm run build`");
+    const sha = shortSha(info.sha);
+    if (!(await isSelfHosted(root, info)))
+        // Not "dist/ from …": in someone else's project that names a dist/ directory the project
+        // does not have — the stamp read here is the running harness install's own, so say that.
+        return okOutcome(`tumwater version ${sha} (this project is not tumwater itself)`);
+    const mainHead = head === undefined ? await currentHead(root) : head;
+    if (!mainHead)
+        return okOutcome(`dist/ from ${sha}`);
+    const stale = await buildStaleness(root, info.sha, mainHead);
+    if (!stale)
+        return okOutcome(`dist/ from ${sha}`);
+    if (stale.stale) {
+        const next = running?.restartBlocked
+            ? `; auto-restart is BLOCKED (${running.restartBlocked}) and will not retry until main moves or the block clears`
+            : running?.restartPending
+                ? "; auto-restart is under way"
+                : "; run `npm run build` and restart `tumwater start` (auto-restart does this for a running team)";
+        return warnOutcome(`dist/ from ${sha} is stale — main has ${stale.aheadCommits} later commit(s) touching ${STALE_INPUTS_LABEL}${next}`);
+    }
+    return okOutcome(`dist/ from ${sha}, matches main`);
+}
+/** The primary checkout's HEAD sha, or null when it cannot be resolved (no repo) —
+ * git/git.ts's refSha, the one home of the rev-parse probe. */
+function currentHead(root) {
+    return refSha(root, "HEAD");
+}

package/dist/src/doctor/doctor.js

@@ -1,43 +1,64 @@
-// vocabulary: plain
 import { loadConfigSafe } from "../config/config.js";
 import { envPath } from "../files/files.js";
 import { orchestratorAlive, readOrchestratorInfo } from "../team/orchestrator-info.js";
 import { systemProcessProbe } from "../process/process-table.js";
 import { checkOrphans } from "./doctor-orphans.js";
-import { checkBudget, checkClaudeWindow, checkErrorStreaks, checkMainRed, checkMaintenanceQuota, checkPause, checkProviderHolds, checkQuietHours } from "./doctor-holds.js";
+import { checkBudget, checkErrorStreaks, checkMainRed, checkMaintenanceQuota, checkPause, checkProviderHolds, checkQuietHours, checkSubscriptionWindow } 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, 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 { failOutcome } from "./outcome.js";
+import { errorMessage } from "../text/text.js";
+import { checkBackendBinary, checkBrief, checkBootstrap, checkClaudeTranscripts, checkExecPath, checkFunes, checkGitBinary, checkConfigKeyNames, checkInit, checkOpencodeVersion, checkNodeVersion, checkPiExtensions, checkRepo, } from "./doctor-checks.js";
+import { checkBuild, checkBuildCheck, checkDiskSpace, checkEventLog, checkFlakyChecks, checkStateDir, } from "./doctor-project-checks.js";
+import { sampleFreeBytes } from "../gates/disk-gate.js";
+import { checkCheckContention, checkLeftoverRoleBranches, checkMergeLock, checkProviderConcurrency, checkProviderContention, checkTumwaterPins, checkWorkInstances, checkWorktreePool, } from "./doctor-contention-checks.js";
+import { checkFallbackChain, checkFallbackModel, checkFeedbackFiling, checkImageInput, checkTierModels } from "./doctor-model-checks.js";
+import { checkAnthroApiKey, checkClaudeAuth, checkClaudeVersion } from "./doctor-claude-checks.js";
+import { checkOpencode } from "./doctor-opencode-checks.js";
+import { checkCodexAccount, checkCodexAuth, checkCodexHome, checkCodexLeaks, checkCodexModels, checkCodexSessions, checkCodexWriteGuard, checkCodexVersion, } from "./doctor-codex-checks.js";
+import { backendQualifiedSelector } 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";
+import { checkBacklogHeadings, checkFixClaims, checkLiveFinished, checkPlanDependencies, checkStalledPlans, checkStrandedPlans, checkValidationGaps } from "./doctor-backlog-plans.js";
+import { checkRefusedEntries, checkRegressedFixes, checkStaleBugs, checkStaleQuestions, checkWaitingBugs } from "./doctor-backlog-bugs.js";
+import { checkMergeQueueFiles, checkStaleQueuedMerges, checkStalePrompts, checkUncommittedBacklog } 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
+ * cmdStart 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 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 }];
+ * doctor-checks.ts, doctor-project-checks.ts, doctor-contention-checks.ts, doctor-model-checks.ts,
+ * doctor-claude-checks.ts, doctor-opencode-checks.ts, doctor-backlog.ts,
+ * doctor-backlog-plans.ts and doctor-backlog-bugs.ts;
+ * this module composes them into the report. */
+/** Run one doctor check, turning a throw or rejection into a fail row: a check that crashed
+ * verified nothing, so it must not read as a pass or abort the report. */
+export async function runDoctorCheck(run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        return failOutcome(`the check threw: ${errorMessage(err)}`);
+    }
 }
 /** 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, probeImages = "never") {
+ * checks, so tests can pin the report without reading the host's process table. `diskSample`
+ * feeds the disk check the same way, so tests can pin the report without reading the host's
+ * real free space (a hosted runner under the 10 GB floor would fail its row). `only` runs
+ * just the named checks, in report order; a skipped check is never evaluated, and a named
+ * conditional check that returns null leaves no row. A check that throws becomes its own fail
+ * row, and every other check still runs. */
+export async function runDoctor(root, pathEnv = envPath(), probe = systemProcessProbe, probeImages = "never", only, diskSample = sampleFreeBytes) {
     // 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);
@@ -48,7 +69,7 @@ export async function runDoctor(root, pathEnv = envPath(), probe = systemProcess
     const routing = config
         ? seamsInUse(config).map((s) => ({
             label: s.label,
-            selector: s.model !== undefined ? agentQualifiedSelector({ ...s, model: s.model }) : "no model declared",
+            selector: s.model !== undefined ? backendQualifiedSelector({ ...s, model: s.model }) : "no model declared",
             backend: s.agent ?? "pi",
         }))
         : [];
@@ -56,80 +77,103 @@ export async function runDoctor(root, pathEnv = envPath(), probe = systemProcess
     const header = orchestratorAlive(root, info) && info
         ? `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) },
+    const steps = [
+        { name: "node", run: () => checkNodeVersion() },
+        { name: "node binary", run: () => checkExecPath() },
+        { name: "git binary", run: () => checkGitBinary(pathEnv) },
+        { name: "repo", run: () => checkRepo(root, config) },
+        { name: "init", run: () => checkInit(root) },
+        { name: "config key names", run: () => checkConfigKeyNames(root) },
+        { name: "brief", run: () => 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.
-        { name: "bootstrap", ...checkBootstrap(root, config) },
-        { name: "pause", ...checkPause(root) },
-        { name: "quiet hours", ...checkQuietHours(config) },
-        { name: "budget", ...checkBudget(root, config, (orchestratorAlive(root, info) && info?.budget) || null) },
-        { 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: "opencode version", ...(await checkOpencodeVersion(root, pathEnv)) },
-        { name: "opencode", ...(await checkOpencode(root, pathEnv)) },
-        { name: "backend binary", ...checkAgentBinary(root, pathEnv) },
+        { name: "bootstrap", run: () => checkBootstrap(root, config) },
+        { name: "pause", run: () => checkPause(root) },
+        { name: "quiet hours", run: () => checkQuietHours(config) },
+        { name: "budget", run: () => checkBudget(root, config, (orchestratorAlive(root, info) && info?.budget) || null) },
+        { name: "claude window", run: () => checkSubscriptionWindow("claude", root, undefined, (orchestratorAlive(root, info) && info?.chain) || undefined, config) },
+        { name: "codex window", run: () => checkSubscriptionWindow("codex", root, undefined, (orchestratorAlive(root, info) && info?.chain) || undefined, config) },
+        { name: "provider waits", run: () => checkProviderHolds(root) },
+        { name: "maintenance allowance", run: () => checkMaintenanceQuota(root, config, orchestratorAlive(root, info)) },
+        { name: "provider concurrency", run: () => checkProviderConcurrency(config, root) },
+        { name: "provider contention", run: () => checkProviderContention(root, config) },
+        { name: "check contention", run: () => checkCheckContention(root, config) },
+        { name: "repeated failures", run: () => checkErrorStreaks(root, config) },
+        { name: "main's check", run: () => checkMainRed(root, config) },
+        { name: "over-cap model", run: () => checkFallbackModel(root, undefined, (orchestratorAlive(root, info) && info?.fallbackDemoted) || null) },
+        { name: "fallback chain", run: () => checkFallbackChain(root) },
+        { name: "models for each tier", run: () => checkTierModels(root) },
+        { name: "image input", run: () => checkImageInput(root, undefined, undefined, undefined, probeImages, pathEnv) },
+        { name: "claude auth", run: () => checkClaudeAuth(root, pathEnv) },
+        { name: "claude api key", run: () => checkAnthroApiKey(root, undefined, pathEnv) },
+        { name: "claude version", run: () => checkClaudeVersion(root, pathEnv) },
+        { name: "opencode version", run: () => checkOpencodeVersion(root, pathEnv) },
+        { name: "opencode", run: () => checkOpencode(root, pathEnv) },
+        { name: "codex version", run: () => checkCodexVersion(root, pathEnv) },
+        { name: "codex login", run: () => checkCodexAuth(root, pathEnv) },
+        { name: "codex home", run: () => checkCodexHome(root) },
+        { name: "codex models", run: () => checkCodexModels(root) },
+        { name: "codex account", run: () => checkCodexAccount(root) },
+        { name: "codex leaks", run: () => checkCodexLeaks(root) },
+        { name: "codex sessions", run: () => checkCodexSessions(root) },
+        { name: "codex write guard", run: () => checkCodexWriteGuard(root, pathEnv) },
+        { name: "backend binary", run: () => checkBackendBinary(root, pathEnv) },
+        { name: "feedback filing", run: () => checkFeedbackFiling(root, pathEnv) },
         // The transcript total is informational and only read when a seam routes to claude.
-        { name: "claude transcripts", ...checkClaudeTranscripts(config) },
+        { name: "claude transcripts", run: () => 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: "workspaces", ...checkWorktreePool(root) },
-        { name: "parallel instances", ...checkWorkInstances(root, config) },
-        { name: "leftover role branches", ...(await checkLeftoverRoleBranches(root, config)) },
+        // the funes row when funes is not on PATH, and the claude/codex window rows when that backend
+        // has no subscription account.
+        { name: "pi extensions", run: () => checkPiExtensions(config, undefined, pathEnv) },
+        { name: "funes", run: () => checkFunes(config, pathEnv) },
+        { name: "state dir", run: () => checkStateDir(root) },
+        { name: "event log", run: () => checkEventLog(root) },
+        { name: "notify", run: () => checkNotify(root, config) },
+        { name: "merge lock", run: () => checkMergeLock(root) },
+        { name: "workspaces", run: () => checkWorktreePool(root) },
+        { name: "parallel instances", run: () => checkWorkInstances(root, config) },
+        { name: "leftover role branches", run: () => checkLeftoverRoleBranches(root, config) },
+        { name: "tumwater pins", run: () => checkTumwaterPins(root) },
         // 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: "check", ...checkBuildCheck(root, config) },
-        { name: "root install", ...checkRootInstall(root) },
+        { name: "disk space", run: () => checkDiskSpace(root, config?.diskHoldGB ?? 10, config?.diskReclaimGB ?? 40, diskSample) },
+        { name: "check", run: () => checkBuildCheck(root, config) },
+        { name: "root install", run: () => 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) },
-        { 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)) },
+        { name: "flaky checks", run: () => checkFlakyChecks(root) },
+        { name: "claimed bugs", run: () => checkFixClaims(root) },
+        { name: "validation gaps", run: () => checkValidationGaps(root) },
+        { name: "plans stuck in Planned", run: () => checkStrandedPlans(root) },
+        { name: "backlog headings", run: () => checkBacklogHeadings(root) },
+        { name: "backlog archive", run: () => checkLiveFinished(root) },
+        { name: "refusals", run: () => checkRefusedEntries(root) },
+        { name: "stalled plans", run: () => checkStalledPlans(root) },
+        { name: "plan dependencies", run: () => checkPlanDependencies(root) },
+        { name: "stale questions", run: () => checkStaleQuestions(root) },
+        { name: "stale bugs", run: () => checkStaleBugs(root) },
+        { name: "waiting bugs", run: () => checkWaitingBugs(root) },
+        { name: "regressed fixes", run: () => checkRegressedFixes(root) },
+        { name: "stale merge-queue entries", run: () => checkStaleQueuedMerges(root, Date.now()) },
+        { name: "merge-queue files", run: () => checkMergeQueueFiles(root) },
+        { name: "stale prompts", run: () => checkStalePrompts(root, Date.now()) },
+        { name: "uncommitted backlog", run: () => 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: "update", ...(await checkBuild(root, undefined, undefined, (orchestratorAlive(root, info) && info?.build) || null)) },
-        { name: "orphans", ...(await checkOrphans(root, probe)) },
-        { name: "macOS port leak", ...(await checkLaunchServicesPorts(probe)) },
+        { name: "update", run: () => checkBuild(root, undefined, undefined, (orchestratorAlive(root, info) && info?.build) || null) },
+        { name: "orphans", run: () => checkOrphans(root, probe) },
+        { name: "macOS port leak", run: () => checkLaunchServicesPorts(probe) },
     ];
+    const checks = [];
+    for (const step of steps) {
+        if (only && !only.includes(step.name))
+            continue;
+        const outcome = await runDoctorCheck(step.run);
+        if (outcome !== null)
+            checks.push({ name: step.name, ...outcome });
+    }
     const problems = checks.filter((c) => c.level === "fail").length;
     return { header, checks, routing, verdict: problems === 0 ? "ready to run" : plural(problems, "problem") };
 }