tumwater 0.1.2 → 0.2.0

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

@@ -1,32 +1,50 @@
+// vocabulary: plain
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { enabledRoleIds, loadConfig, loadConfigSafe, slotCount, } from "../config/config.js";
+import { enabledRoleIds, knownRoleIds, parseJsonConfig, loadConfig, loadConfigSafe, slotCount, } from "../config/config.js";
 import { exampleConfigProblem, exampleDrift } from "../config/config-example.js";
 import { detectBuildCheck } from "../build/build-check-detect.js";
+import { isPassingFullCheck } from "../build/build-check-events.js";
+import { CUSTOM_NAME_RE } from "../config/config-schema.js";
 import { bootstrapStatus } from "../gates/bootstrap-gates.js";
 import { buildStaleness, isSelfHosted, readBuildInfo, STALE_INPUTS_LABEL } from "../build/build-info.js";
 import { envPath, findOnPath, subdirectoryNames } 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";
-import { branchExists, currentBranch, hasCommits, branchesPhrase, isGitRepo, refSha, repoToplevel, } from "../git/git.js";
+import { branchExists, currentBranch, hasCommits, branchesPhrase, isGitRepo, listBranches, refSha, repoToplevel, } from "../git/git.js";
 import { DETACHED_HEAD_MESSAGE, NOT_A_REPO_MESSAGE, NOT_INITIALIZED_MESSAGE, NO_COMMITS_MESSAGE, } from "../gates/readiness.js";
 import { agentBinSourceLabelFor, agentMissingMessage, findAgentBinary, resolveAgentBin } from "../pi/pi-bin.js";
+import { piModelsPath } from "../pi/pi-models.js";
+import { piSettingsPath, readPiDefaultModel } from "../pi/pi-settings.js";
+import { seamConcurrencyKey } from "../config/config-views.js";
+import { resolvedAgentConfig } from "../config/config-views.js";
+import { seamsInUse } from "../config/config-fallbacks.js";
 import { classifyLock, readLockPid } from "../concurrency/lock.js";
-import { EXAMPLE_CONFIG_BASENAME, STATE_DIR, configPath, eventsLogPath, mergeLockDir, worktreesDir } from "../paths.js";
+import { CONFIG_BASENAME, EXAMPLE_CONFIG_BASENAME, branchName, STATE_DIR, configPath, eventsLogPath, mergeLockDir, worktreesDir } from "../paths.js";
 import { BYTES_PER_GB, diskVolumePath, sampleFreeBytes } from "../gates/disk-gate.js";
 import { errorMessage, textOr } from "../text/text.js";
+import { lowerMedian } from "../collections.js";
 import { formatGB, shortSha } from "../text/format.js";
-import { briefFile } from "../brief.js";
-import { eventLogState } from "../events/event-window.js";
+import { briefFile } from "../brief/brief.js";
+import { eventLogState, eventsSince, readEventsSince } from "../events/event-window.js";
+import { finiteNumber } from "../files/json-object.js";
+import { agree, plural, shortSpanPhrase } from "../text/phrases.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { readSlotsState } from "../git/slots-state.js";
-import { agentsInUse } from "../gates/startup-gate.js";
-import { claudeSeamsInUse } from "./doctor-model-checks.js";
+import { agentsInUse, unregisteredBackendInUse } from "../gates/startup-gate.js";
+import { claudeSeamsInUse, opencodeSeamsInUse, piSeamsInUse, AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS } from "./doctor-model-checks.js";
+import { claudeConfigDir } from "../agent/claude/claude-backend.js";
+import { boundedProbe } from "./probe.js";
+import { childEnv } from "../process/process.js";
+import { opencodeBackend, OPENCODE_MIN_VERSION } from "../agent/opencode/opencode-backend.js";
 import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
+import { spawnSync } from "node:child_process";
 import { loadLoopState } from "../loop/loop-state.js";
-import { INSTANCE_ROLES, loopIds } from "../roles/loop-ids.js";
+import { INSTANCE_ROLES, loopEnabled, loopIds } from "../roles/loop-ids.js";
 import { CLAIM_IDLE_MAX_MS, listedKeys } from "../scheduling/claims.js";
+import { flakeCounts, KNOWN_FLAKE_WINDOW_MS } from "../review/known-flakes.js";
 /** The floor doctor falls back to when package.json — the one source of the declared
  * engines.node spec, read below — cannot be read (a broken install, the version command's
  * story). The CLI's startup gate enforces the spec itself; this check stays a warning so a
@@ -62,7 +80,7 @@ export function checkGitBinary(pathEnv = envPath()) {
 /** Repo ready — the git/git.ts predicates in requireReadyRepo's order, so doctor and the
  * readiness gate cannot drift: not a git repo → no commits yet → detached HEAD. Reports the
  * resolved toplevel (not the cwd — doctor must say where .tumwater/ lives) and the branch the
- * fleet would target: a configured `baseBranch` wins (`run --branch` is per-invocation), and
+ * team would target: a configured `baseBranch` wins (`run --branch` is per-invocation), and
  * one that does not exist fails here instead of at the first tick. `config` is optional so
  * the check stands alone; runDoctor passes the loaded config behind a guard. */
 export async function checkRepo(root, config) {
@@ -117,6 +135,18 @@ export function checkInit(root) {
         return failOutcome(errorMessage(err));
     }
 }
+/** Whether tumwater.json still spells keys by an old name (config-aliases.ts). Both spellings
+ * load, so this only warns, naming each exact rename. Ok when the file is absent or broken
+ * (checkInit reports that) or nothing in it is renamed. */
+export function checkConfigKeyNames(root) {
+    const file = configPath(root);
+    if (!fs.existsSync(file))
+        return okOutcome("no tumwater.json");
+    const { renamed } = parseJsonConfig(file, CONFIG_BASENAME);
+    if (renamed === undefined || renamed.length === 0)
+        return okOutcome("current key names");
+    return warnOutcome(`old key names: ${renamed.join(", ")} — rename them in tumwater.json; both spellings work until then`);
+}
 /** Which file holds the project brief (the managed initial prompt + status sections,
  * plans/portability.md §7a/7): TUMWATER.md first, README.md as the compatibility path. A repo
  * whose README carries no markers — or that has no brief at all — still boots, but every loop
@@ -126,7 +156,7 @@ export function checkInit(root) {
 export function checkBrief(root) {
     // briefFile throws on a brief candidate that exists but cannot be read (a directory at
     // the README.md path, a permission-lost file) — report it as the check's failure instead
-    // of crashing doctor: the fleet would run without its brief every tick.
+    // of crashing doctor: the team would run without its brief every tick.
     let owner;
     try {
         owner = briefFile(root);
@@ -137,7 +167,7 @@ export function checkBrief(root) {
     if (owner)
         return okOutcome(`brief in ${owner}`);
     if (fs.existsSync(path.join(root, "README.md"))) {
-        return warnOutcome(`README.md carries no tumwater:prompt markers — the fleet would run without its project brief; add the block or re-run \`tumwater init\``);
+        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\``);
     }
     return warnOutcome("no brief file — run `tumwater init <prompt>` to seed one");
 }
@@ -149,7 +179,7 @@ export function checkBootstrap(root, config) {
     const status = config ? bootstrapStatus(root, config) : null;
     if (!status?.active)
         return okOutcome("not bootstrapping");
-    return okOutcome(`bootstrapping: ${status.plansDone}/${status.untilPlansDone} plans done — plan, feature and director tick`);
+    return okOutcome(`bootstrapping: ${status.plansDone}/${status.untilPlansDone} plans done — plan, feature and director runs`);
 }
 /** Resolve and test ONE agent's binary: the ok detail names the resolved path and its source
  * whenever the value is not the PATH default, so a configured binary is never mistaken for the
@@ -173,11 +203,18 @@ function agentBinaryCheck(config, agent, pathEnv) {
  * path-shaped accessSync(X_OK) rule, and null-on-unusable verdict the startup gate asks — so
  * doctor cannot pass a binary the gate would reject. resolveAgentBin normalizes path-shaped
  * values against the process cwd at resolution time, so what doctor tests is exactly what
- * spawns. A claude-only fleet checks claude, not pi. The check fails on the first missing
+ * spawns. A claude-only team checks claude, not pi. The check fails on the first missing
  * binary, naming its agent; an ok detail joins each agent's resolved path and source. */
 export function checkAgentBinary(root, pathEnv = envPath()) {
     const { config } = loadConfigSafe(root);
     const agents = config !== undefined ? agentsInUse(config) : ["pi"];
+    // A seam backend with no registered adapter in this build can never run; naming that beats
+    // the binary check (which would pass an installed binary only to fall through to pi). The
+    // same rule and wording as the startup gate's. After opencode's adapter lands (part 5/7)
+    // this stays the general rule for any future id.
+    const unregistered = config !== undefined ? unregisteredBackendInUse(config) : undefined;
+    if (unregistered !== undefined)
+        return failOutcome(`backend ${unregistered} is configured but this build has no adapter for it`);
     const checks = agents.map((agent) => ({
         agent,
         outcome: agentBinaryCheck(config ?? {}, agent, pathEnv),
@@ -229,18 +266,44 @@ function formatBytes(n) {
         return `${(n / 1024).toFixed(1)} KB`;
     return `${n} B`;
 }
-/** claude transcript disk — the total size of `~/.claude/projects` (plans/agent-backends.md
- * "Sessions" retention): claude ages transcripts out under its own cleanupPeriodDays, so an
- * operator asking where claude's disk went gets the number without `du`. Informational (ok) in
- * every case — a large transcript tree is a fact, not a misconfiguration. Stands down when no
- * seam routes to claude: a pi-only fleet reads no claude state, and the report must not walk a
- * host directory that has nothing to do with the fleet. `homeDir` is a test seam. */
-export function checkClaudeTranscripts(config, homeDir = os.homedir()) {
+/** claude transcript disk — the total size of the claude config dir's `projects/`
+ * (plans/agent-backends.md "Sessions" retention): the perf adapter ages transcripts out under
+ * its own cleanupPeriodDays, so an operator asking where claude's disk went gets the number
+ * without `du`. Informational (ok) in every case — a large transcript tree is a fact, not a
+ * misconfiguration. Stands down when no seam routes to claude: a pi-only team reads no claude
+ * state, and the report must not walk a host directory that has nothing to do with the team.
+ * `homeDir` and `env` are test seams. */
+/** The dotted version in `opencode --version` (prints `opencode v2.0.32`), or undefined when it
+ * names none. */
+function parseOpencodeCliVersion(output) {
+    return /v(\d+\.\d+\.\d+)/.exec(output)?.[1];
+}
+/** OpenCode CLI-version readiness (plans/opencode-backend.md "Which OpenCode", part 7/7): the
+ * team targets V2 at 2.0.32 or later, the version H1 verified live. An installed CLI below that
+ * (a 1.x binary included) fails naming `brew install opencode`; at or above it reads the
+ * version. Stands down when no seam routes to opencode, so a pi-only team spawns no opencode. */
+export async function checkOpencodeVersion(root, pathEnv = envPath(), timeoutMs = AUTH_CHECK_TIMEOUT_MS) {
+    const { config } = loadConfigSafe(root);
+    if (config === undefined)
+        return okOutcome("no readable tumwater.json — nothing to verify");
+    if (!opencodeSeamsInUse(config))
+        return okOutcome("no model jobs run on opencode");
+    const resolved = opencodeBackend.resolveBin(config);
+    const result = await boundedProbe(resolved.bin, ["--version"], childEnv({ PATH: pathEnv }), timeoutMs, AUTH_CHECK_MAX_OUTPUT_BYTES);
+    const found = result !== null && result.code === 0 ? parseOpencodeCliVersion(result.stdout) : undefined;
+    if (found === undefined)
+        return warnOutcome("could not check — `opencode --version` did not run or its output was unreadable");
+    if (belowNodeFloor(found, `>=${OPENCODE_MIN_VERSION}`))
+        return failOutcome(`opencode ${found} is older than ${OPENCODE_MIN_VERSION} — run \`brew install opencode\``);
+    return okOutcome(`opencode ${found} (>= ${OPENCODE_MIN_VERSION})`);
+}
+export function checkClaudeTranscripts(config, homeDir = os.homedir(), env = process.env) {
     if (!config)
         return okOutcome("no readable tumwater.json — nothing to verify");
     if (!claudeSeamsInUse(config))
-        return okOutcome("no claude seams configured");
-    const dir = path.join(homeDir, ".claude", "projects");
+        return okOutcome("no model jobs run on claude");
+    const configDir = resolvedAgentConfig(config, "claude").configDir;
+    const dir = path.join(claudeConfigDir(env, homeDir, configDir), "projects");
     let slugs;
     try {
         slugs = fs
@@ -254,11 +317,158 @@ export function checkClaudeTranscripts(config, homeDir = os.homedir()) {
     let bytes = 0;
     for (const slug of slugs)
         bytes += treeBytes(path.join(dir, slug));
-    const projects = slugs.length === 1 ? "1 project" : `${slugs.length} projects`;
+    const projects = plural(slugs.length, "project");
     return okOutcome(`${formatBytes(bytes)} across ${projects} in ${dir}`);
 }
+/** Bounding for the `pi list` probe below: the packages a team run now skips are names, so a
+ * short deadline and a small output cap keep an unlucky host from stalling doctor. */
+const PI_LIST_TIMEOUT_MS = 5_000;
+const PI_LIST_MAX_BYTES = 64 * 1024;
+/** MCP server names in `~/.pi/agent/mcp.json` (the file pi's built-in MCP extension reads),
+ * or `[]` for a missing/malformed file: the `mcpServers` keys, or `mcp.<name>`. Best-effort
+ * naming so a server the operator meant for the team is surfaced even when the file is odd. */
+function piMcpServerNames(file) {
+    // The tolerant read-and-parse half (missing, torn, scalar, `null`, or array file is "no
+    // data", never an error) is src/files/json-files.ts's readJsonFile, the same shared
+    // convention every other state/marker/info file reader uses.
+    const parsed = readJsonFile(file);
+    if (parsed === null)
+        return [];
+    const names = new Set();
+    const serverMap = parsed["mcpServers"];
+    if (serverMap && typeof serverMap === "object")
+        for (const name of Object.keys(serverMap))
+            names.add(name);
+    const mcp = parsed["mcp"];
+    if (mcp && typeof mcp === "object")
+        for (const [name, value] of Object.entries(mcp))
+            if (name !== "servers" && value && typeof value === "object")
+                names.add(name);
+    return [...names];
+}
+/** The operator pi state a team run now skips (plans/notes-command.md "Keeping funes out of
+ * team runs"): installed packages (`pi list`, bounded), files in `~/.pi/agent/extensions`, and
+ * MCP servers in `~/.pi/agent/mcp.json`. Each is named, so a package, extension file, or server
+ * the operator meant for the team does not vanish silently when pi loads none of it. Shown only
+ * when a model job runs on pi; returns null otherwise so doctor omits the row and never reads
+ * a host `~/.pi` a pi-only-install team does not use. `homeDir` and `pathEnv` are test seams. */
+export function checkPiExtensions(config, homeDir = os.homedir(), pathEnv = envPath()) {
+    if (!config)
+        return null;
+    if (!piSeamsInUse(config))
+        return null;
+    const parts = [];
+    // Installed pi packages (pi list, bounded): each stdout line a package name. A probe that
+    // cannot run or produces nothing contributes nothing; the rest still name what team runs skip.
+    const resolved = resolveAgentBin(config, "pi");
+    const piBin = findAgentBinary(resolved, pathEnv);
+    if (piBin !== null) {
+        try {
+            const stdout = spawnSync(piBin, ["list"], {
+                encoding: "utf8",
+                timeout: PI_LIST_TIMEOUT_MS,
+                maxBuffer: PI_LIST_MAX_BYTES,
+                killSignal: "SIGKILL",
+            }).stdout;
+            // `pi list` is not line-per-package: each package is a two-space-indented source line
+            // (optionally followed by its installed path at four spaces), under the bold `User
+            // packages:` / `Project packages:` headers. Keep only the two-space source lines so the
+            // headers and installed paths are not mistaken for packages.
+            const packages = String(stdout)
+                .split(/\r?\n/)
+                .map((line) => line.replace(/\r$/, ""))
+                .map((line) => /^  (\S.*)$/.exec(line)?.[1]?.trim())
+                .filter((name) => name !== undefined && name.length > 0);
+            if (packages.length > 0)
+                parts.push(`packages: ${packages.join(", ")}`);
+        }
+        catch {
+            // A `pi list` that could not be read just names nothing; extensions/servers below still show.
+        }
+    }
+    // Files in ~/.pi/agent/extensions.
+    try {
+        const files = fs
+            .readdirSync(path.join(homeDir, ".pi", "agent", "extensions"), { withFileTypes: true })
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name);
+        if (files.length > 0)
+            parts.push(`~/.pi/agent/extensions: ${files.join(", ")}`);
+    }
+    catch {
+        // Absent or unreadable; nothing to name.
+    }
+    // MCP servers named in ~/.pi/agent/mcp.json (the file pi's MCP built-in reads).
+    const mcpNames = piMcpServerNames(path.join(homeDir, ".pi", "agent", "mcp.json"));
+    if (mcpNames.length > 0)
+        parts.push(`mcp.json servers: ${mcpNames.join(", ")}`);
+    if (parts.length === 0)
+        return okOutcome("team pi runs skip discovered extensions; none found on this host");
+    return okOutcome(`team pi runs skip discovered extensions: ${parts.join("; ")}`);
+}
+/** 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");
+    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.
+ * A best-effort note (the design's doctor `funes` row) so an operator who installed funes's
+ * OpenCode integration is told it could reach an OpenCode team; a malformed file reads nothing. */
+function opencodePluginNamesFunes(homeDir, readPath) {
+    for (const file of opencodeGlobalConfigPaths(homeDir)) {
+        const text = readPath(file);
+        if (text === null)
+            continue;
+        // A global config that mentions funes in or near a plugin reference is worth naming; the
+        // exact JSON shape varies by version (array or object), so a substring scan over the text is
+        // the honest check.
+        if (/"plugin(s)?"\s*[:\[\{]/.test(text) && /funes/i.test(text))
+            return file;
+    }
+    return null;
+}
+/** The `funes` row (plans/notes-command.md "Keeping funes out of team runs"): whether the
+ * transcript-recall tool you use for your own sessions can reach the team. Shows only when
+ * `funes` is on PATH (else no row at all) and warns when a Claude Code team runs without a
+ * `backends.claude.configDir` while funes's Claude Code hook is installed (`~/.funes/
+ * integrations/claude-plugin`) — that hook indexes every session under `~/.claude/projects`,
+ * which is exactly what a team config dir moves out from under. It also notes a global
+ * OpenCode plugin naming funes. `pathEnv`, `homeDir`, and `readPath` are test seams. */
+export function checkFunes(config, pathEnv = envPath(), homeDir = os.homedir(), readPath = (file) => {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}) {
+    if (!config)
+        return null;
+    if (findOnPath("funes", pathEnv) === null)
+        return null;
+    const notes = [];
+    if (claudeSeamsInUse(config)) {
+        const configDir = resolvedAgentConfig(config, "claude").configDir;
+        const plugin = path.join(homeDir, ".funes", "integrations", "claude-plugin");
+        if (configDir === undefined && fs.existsSync(plugin)) {
+            return warnOutcome("funes's Claude Code hook indexes team transcripts into your personal memory — set backends.claude.configDir and log in there once (`CLAUDE_CONFIG_DIR=<dir> claude auth login`)");
+        }
+        notes.push(configDir === undefined
+            ? "Claude Code runs use the default config dir (no funes Claude Code hook installed)"
+            : "Claude Code runs use their own config dir");
+    }
+    const opencodePlugin = opencodePluginNamesFunes(homeDir, readPath);
+    if (opencodePlugin !== null)
+        notes.push(`global OpenCode config mentions funes (${opencodePlugin})`);
+    const detail = notes.length > 0 ? `funes on PATH, no team reach: ${notes.join("; ")}` : "funes on PATH, no team reach";
+    return okOutcome(detail);
+}
 /** .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. */
+ * 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))
@@ -266,12 +476,46 @@ export function checkStateDir(root) {
     const probe = path.join(dir, `.doctor-probe-${process.pid}`);
     try {
         fs.writeFileSync(probe, "");
-        fs.rmSync(probe);
-        return okOutcome("writable");
     }
     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) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return; // Unreadable dir — nothing to sweep.
+    }
+    for (const name of names) {
+        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 telemetry role is chartered to catch — a feed that hid itself — is named by the
@@ -288,20 +532,22 @@ export function checkEventLog(root) {
         return failOutcome(`could not read ${eventsLogPath(root)}: ${errorMessage(err)}`);
     }
     if (state === "unreadable")
-        return failOutcome(`unreadable: ${eventsLogPath(root)} — the fleet's event feed cannot be read`);
+        return failOutcome(`unreadable: ${eventsLogPath(root)} — the team's event feed cannot be read`);
     if (state === "empty")
         return okOutcome("no events yet");
     return okOutcome(`readable: ${eventsLogPath(root)}`);
 }
 /** 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 fleet holds new work
+ * 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 fleet still runs. Ok at or above `diskReclaimGB` (or when reclaim is
+ * 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 fleet, so it must not fail a scripted pre-flight. The
+ * 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. */
+ * 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);
@@ -309,12 +555,27 @@ export function checkDiskSpace(root, holdGB, reclaimGB, sample = sampleFreeBytes
         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, 24 * 60 * 60 * 1000).events);
+    const withReclaim = (detail) => (phrase ? `${detail} · ${phrase}` : detail);
     if (holdGB > 0 && freeGB < holdGB)
-        return failOutcome(`${freeText} — below the ${holdGB} GB diskHoldGB floor; the fleet holds new work until space recovers`);
+        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(`${freeText} — below the ${reclaimGB} GB diskReclaimGB threshold; a pressure reclaim pass deletes ignored build outputs from idle worktrees`);
+        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(`${freeText}, ${floor}`);
+    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;
 }
 /** Merge lock — read-only classification via classifyLock (the same three cases the breaker
  * uses). A stale lock is a warning, not a failure: it self-heals on the next merge. */
@@ -325,7 +586,7 @@ export function checkMergeLock(root) {
             return okOutcome("not held");
         case "live": {
             const pid = readLockPid(dir);
-            return okOutcome(pid !== null ? `held by running loop (pid ${pid})` : "held (pid not yet written)");
+            return okOutcome(pid !== null ? `held by running role (pid ${pid})` : "held (pid not yet written)");
         }
         case "stale":
             return warnOutcome("stale — will be broken on next merge");
@@ -341,9 +602,15 @@ const PIN_STALE_MS = 24 * 60 * 60 * 1000;
 function leftoverWorktreeDirs(root) {
     return subdirectoryNames(worktreesDir(root), (name) => name !== DIRECTOR_ROLE && !(name.startsWith("_") && !name.startsWith("_land-")));
 }
-/** Worktree pool (plans/worktree-pool.md, part 5/5): report the pooled slots and warn on the two
+/** The window of `slot_wait` events the pool row sums, and the total wait inside it that warns. */
+const SLOT_WAIT_CHECK_WINDOW_MS = 24 * 3600_000;
+const SLOT_WAIT_WARN_TOTAL_MS = 10 * 60_000;
+const PROVIDER_WAIT_CHECK_WINDOW_MS = 24 * 3600_000;
+const PROVIDER_WAIT_WARN_TOTAL_MS = 10 * 60_000;
+/** Worktree pool (plans/worktree-pool.md, part 5/5): report the pooled slots and warn on the
  * states an operator should act on — a legacy `<role>` or `_land-*` checkout the pool migration
- * left behind, and a pin older than PIN_STALE_MS (a paused role holding a checkout). Read-only,
+ * left behind, a pin older than PIN_STALE_MS (a paused role holding a checkout), and the last
+ * 24 h of `slot_wait` events totalling SLOT_WAIT_WARN_TOTAL_MS (the pool is too small). Read-only,
  * like every doctor check; `now` is a test seam for the pin-age arithmetic. */
 export function checkWorktreePool(root, now = Date.now()) {
     const slots = readSlotsState(root).slots;
@@ -351,7 +618,7 @@ export function checkWorktreePool(root, now = Date.now()) {
     const pins = slots.filter((slot) => slot.pinnedFor !== null);
     const stale = pins.filter((slot) => slot.pinnedAt != null && now - slot.pinnedAt > PIN_STALE_MS);
     const leftover = leftoverWorktreeDirs(root);
-    const parts = [`${slots.length} slots, ${leased.length} leased, ${pins.length} pinned`];
+    const parts = [`${plural(slots.length, "workspace")}, ${leased.length} leased, ${pins.length} pinned`];
     if (leftover.length > 0)
         parts.push(`legacy worktrees still present: ${leftover.join(", ")}`);
     if (stale.length > 0) {
@@ -359,15 +626,137 @@ export function checkWorktreePool(root, now = Date.now()) {
             .map((slot) => `${textOr(slot.pinnedFor)} pinned on ${path.basename(slot.dir)} for ${Math.round((now - (slot.pinnedAt ?? now)) / 3_600_000)}h`)
             .join("; "));
     }
-    return (leftover.length > 0 || stale.length > 0 ? warnOutcome : okOutcome)(parts.join(" — "));
+    let contended = false;
+    try {
+        const waits = eventsSince(root, SLOT_WAIT_CHECK_WINDOW_MS, now, (ev) => ev.type === "slot_wait");
+        if (waits.length > 0) {
+            let total = 0;
+            let longest = waits[0];
+            for (const ev of waits) {
+                const waited = finiteNumber(ev.waitedMs, 0);
+                total += waited;
+                if (waited > finiteNumber(longest.waitedMs, 0))
+                    longest = ev;
+            }
+            contended = total >= SLOT_WAIT_WARN_TOTAL_MS;
+            const purpose = longest.purpose === "verify" ? "check" : "run";
+            parts.push(`${plural(waits.length, "wait")} to start in the last 24h, ${shortSpanPhrase(total)} total, longest ${shortSpanPhrase(finiteNumber(longest.waitedMs, 0))} (${textOr(longest.role)} ${purpose})${contended ? ` — raise worktreeSlots above ${slots.length}` : ""}`);
+        }
+    }
+    catch (err) {
+        parts.push(`could not read the event log for waits to start: ${errorMessage(err)}`);
+    }
+    const warn = leftover.length > 0 || stale.length > 0 || contended;
+    return (warn ? warnOutcome : okOutcome)(parts.join(" — "));
+}
+/** Provider-slot contention: sums the last 24 h of `provider_wait` events (each a role tick
+ * whose semaphore admission waited PROVIDER_WAIT_EVENT_MS or more, recorded in
+ * orchestrator-launch.ts) and warns when the total reaches PROVIDER_WAIT_WARN_TOTAL_MS — the
+ * provider cap is too small. Names every key that waited, busiest first (the key-less
+ * bucket reads "the run cap") and, on a warn, each key's maxConcurrentPerProvider cap to raise. A
+ * counterpoint to checkWorktreePool's slot-wait half; read-only, like every doctor check.
+ * `now` is a test seam for the window. */
+export function checkProviderContention(root, config, now = Date.now()) {
+    let count = 0;
+    let total = 0;
+    let longestMs = 0;
+    const perKey = new Map();
+    try {
+        const waits = eventsSince(root, PROVIDER_WAIT_CHECK_WINDOW_MS, now, (ev) => ev.type === "provider_wait");
+        for (const ev of waits) {
+            count += 1;
+            const waited = finiteNumber(ev.waitedMs, 0);
+            total += waited;
+            if (waited > longestMs)
+                longestMs = waited;
+            const key = typeof ev.key === "string" && ev.key.length > 0 ? ev.key : "";
+            perKey.set(key, (perKey.get(key) ?? 0) + waited);
+        }
+    }
+    catch (err) {
+        // A read error leaves the level ok, exactly like the slot-wait branch's own read: the
+        // check cannot measure, so it says so rather than crying wolf.
+        return okOutcome(`could not read the event log for provider waits: ${errorMessage(err)}`);
+    }
+    if (count === 0)
+        return okOutcome("no provider waits");
+    // Rank the buckets by wait total, ties breaking on key name so the detail is deterministic.
+    // The key-less bucket reads "the run cap" — maxConcurrent, since no seam keys to a provider.
+    const ranked = [...perKey.entries()]
+        .map(([key, total]) => ({ key, total }))
+        .sort((a, b) => b.total - a.total || a.key.localeCompare(b.key));
+    const bucketLabel = (key) => (key === "" ? "the run cap" : `the ${key} slot`);
+    const cells = ranked.map((b) => `${bucketLabel(b.key)} ${shortSpanPhrase(b.total)}`);
+    // A single bucket keeps the pre-existing wording, a bare `(the X slot)` without the total
+    // (the total is already named by the `shortSpanPhrase(total)` in the clause before it);
+    // two or more name each bucket's total so the ranking reads at a glance.
+    const parenthetical = ranked.length === 1
+        ? `(${bucketLabel(ranked[0].key)})`
+        : `(${cells[0]}, also ${cells.slice(1).join(", ")})`;
+    let detail = `${plural(count, "wait")} for a provider slot in the last 24h, ${shortSpanPhrase(total)} total, longest ${shortSpanPhrase(longestMs)} ${parenthetical}`;
+    const contended = total >= PROVIDER_WAIT_WARN_TOTAL_MS;
+    if (contended) {
+        const advice = ranked
+            .filter((b) => b.key !== "" && config?.maxConcurrentPerProvider?.[b.key] !== undefined)
+            .map((b) => `raise maxConcurrentPerProvider.${b.key} above ${config?.maxConcurrentPerProvider?.[b.key]}`)
+            .join(" and ");
+        if (advice)
+            detail += ` — ${advice}`;
+    }
+    return (contended ? warnOutcome : okOutcome)(detail);
+}
+/** The "leftover role branches" row: `tumwater/<id>` branches whose role is no longer enabled
+ * (disabled in tumwater.json, or an instance above the configured count). Retirable ids are
+ * the ones `tumwater retire --role <id>` accepts (knownRoleIds, or any well-formed custom-role name
+ * with a leftover branch); any other id is listed by
+ * full branch name with a manual-delete hint. The director and enabled roles are skipped.
+ * Read-only, like every check: it only lists refs; an unreadable tumwater.json skips it. */
+export async function checkLeftoverRoleBranches(root, config) {
+    if (!config)
+        return okOutcome("no readable tumwater.json — nothing to verify");
+    const prefix = branchName("");
+    const known = new Set(knownRoleIds(config));
+    const retirable = [];
+    const unknown = [];
+    for (const branch of await listBranches(root)) {
+        if (!branch.startsWith(prefix))
+            continue;
+        const id = branch.slice(prefix.length);
+        if (!id || id.includes("/") || id === DIRECTOR_ROLE || loopEnabled(config, id))
+            continue;
+        if (known.has(id) || CUSTOM_NAME_RE.test(id))
+            retirable.push(id);
+        else
+            unknown.push(branch);
+    }
+    const parts = [];
+    if (retirable.length > 0) {
+        const n = retirable.length;
+        parts.push(`${retirable.join(", ")} ${agree(n, "is", "are")} disabled but still ${agree(n, "has", "have")} a branch — \`tumwater retire --role <id>\` removes each (\`--dry-run\` previews)`);
+    }
+    if (unknown.length > 0) {
+        parts.push(`${unknown.join(", ")} ${agree(unknown.length, "names", "name")} no role retire accepts — delete with \`git branch -D\` once its commits are not needed`);
+    }
+    return parts.length === 0 ? okOutcome("no branches left by disabled roles") : warnOutcome(parts.join("; "));
 }
-/** Parallel work instances (plans/parallel-work-instances.md "Observability", part 6/7): the
- * fleet's claims and the two states an operator should act on — a claim whose key is no longer
- * listed under its role's section (its instance is stuck on an entry that moved), and a claim
- * idle for more than CLAIM_IDLE_MAX_MS (the scheduler releases these, so seeing one means the
- * reader's view and the scheduler's disagree). An enabled 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
+/** The ok detail of the instance check: non-zero counts, plans first, each pluralized. */
+function claimCounts(claims) {
+    const bugs = claims.filter((c) => c.file === "BUGS.md").length;
+    const plans = claims.length - bugs;
+    const parts = [
+        plans > 0 ? plural(plans, "claimed plan") : "",
+        bugs > 0 ? plural(bugs, "claimed bug") : "",
+    ].filter(Boolean);
+    return parts.length > 0 ? parts.join(", ") : "no claimed plans or bugs";
+}
+/** Parallel work instances (plans/parallel-work-instances.md "Observability", part 6/7):
+ * each instance's claimed plan or bug and the two states an operator should act on — a claim
+ * whose key is no longer listed under its role's section (its instance is stuck on an entry
+ * that moved), and a claim idle for more than CLAIM_IDLE_MAX_MS (the scheduler releases
+ * these, so seeing one means the reader's view and the scheduler's disagree). An enabled
+ * 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.
  * 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. */
@@ -378,7 +767,7 @@ export function checkWorkInstances(root, config, now = Date.now()) {
     for (const id of loopIds(config)) {
         const claim = loadLoopState(root, id).claim;
         if (claim)
-            claims.push({ id, title: claim.title, key: claim.key, at: claim.at });
+            claims.push({ id, title: claim.title, key: claim.key, at: claim.at, file: claim.file });
     }
     const gone = claims.filter((c) => !listedKeys(root, c.id).has(c.key));
     const stale = claims.filter((c) => !gone.includes(c) && now - c.at > CLAIM_IDLE_MAX_MS);
@@ -388,15 +777,80 @@ export function checkWorkInstances(root, config, now = Date.now()) {
     const slots = slotCount(config);
     const smallPool = multi.length > 0 && slots < config.maxConcurrent;
     if (gone.length === 0 && stale.length === 0 && !smallPool)
-        return okOutcome(claims.length > 0 ? `${claims.length} claims held` : "no claims held");
+        return okOutcome(claimCounts(claims));
+    const noun = (c) => (c.file === "BUGS.md" ? "bug" : "plan");
     const parts = [
-        ...gone.map((c) => `claim "${c.title}" (${c.id}) names an entry no longer listed`),
-        ...stale.map((c) => `claim "${c.title}" (${c.id}) has been idle ${Math.round((now - c.at) / 3_600_000)}h`),
+        ...gone.map((c) => `claimed ${noun(c)} "${c.title}" (${c.id}) names an entry no longer listed`),
+        ...stale.map((c) => `claimed ${noun(c)} "${c.title}" (${c.id}) has been idle ${Math.round((now - c.at) / 3_600_000)}h`),
     ];
     if (smallPool)
         parts.push(`${multi.join(", ")} run instances but worktreeSlots ${slots} is below maxConcurrent ${config.maxConcurrent}`);
     return warnOutcome(parts.join("; "));
 }
+/** Provider concurrency caps (plans/provider-concurrency.md §8): audit the
+ * `maxConcurrentPerProvider` map against the seams the config can actually spawn — each role,
+ * the review gate, the resolver, the director, and each tier's fallback — so the operator
+ * sees whether every cap names a provider in use and whether any cap actually binds. Warns on
+ * a cap key no seam resolves to (a typo, or a provider not in use), a cap at or above
+ * `maxConcurrent` (which never binds — the team total is the real ceiling), and a capped
+ * team whose seams include one with no key (pi's default provider is unreadable, so that
+ * seam cannot be capped). A config with no per-provider map or no caps is fine, and so is a
+ * 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) {
+    if (!config)
+        return okOutcome("no config to audit");
+    const caps = config.maxConcurrentPerProvider;
+    const capEntries = Object.entries(caps ?? {}).filter(([, v]) => Number.isInteger(v) && v > 0);
+    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 seams = seamsInUse(config);
+    const keyed = [];
+    for (const s of seams) {
+        const k = seamConcurrencyKey(s, piDefault);
+        if (k !== undefined && !keyed.includes(k))
+            keyed.push(k);
+    }
+    const keySet = new Set(keyed);
+    const capKeys = capEntries.map(([k]) => k);
+    const warnings = [];
+    for (const key of capKeys) {
+        if (!keySet.has(key))
+            warnings.push(`cap key "${key}" resolves to no model job (a typo, or a provider not in use)`);
+    }
+    for (const [key, cap] of capEntries) {
+        if (cap >= config.maxConcurrent)
+            warnings.push(`cap "${key}" ${cap} is at or above maxConcurrent ${config.maxConcurrent} — it never binds`);
+    }
+    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(", ")}`);
+    }
+    if (warnings.length === 0)
+        return okOutcome(`${plural(capEntries.length, "provider cap")} — all model jobs resolve`);
+    return warnOutcome(warnings.join("; "));
+}
+/** 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
@@ -409,22 +863,46 @@ 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)");
+    const phrase = checkDurationPhrase(readEventsSince(root, 24 * 60 * 60 * 1000).events);
+    const withTiming = (detail) => okOutcome(phrase ? `${detail} · ${phrase}` : detail);
     if (check.kind === "command") {
         const where = path.relative(root, check.cwd);
-        return okOutcome(where ? `${check.command} (cwd ${where})` : check.command);
+        return withTiming(where ? `${check.command} (cwd ${where})` : check.command);
     }
     const where = path.relative(root, check.rootDir);
-    return okOutcome(where ? `npm ${check.script} in ${where}` : `npm ${check.script}`);
+    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) {
+    const { events } = readEventsSince(root, KNOWN_FLAKE_WINDOW_MS);
+    const flapped = flakeCounts(events).filter(([, n]) => n >= 2);
+    if (flapped.length === 0)
+        return okOutcome("no check flapped more than once in the last 24h");
+    const render = ([k, n]) => `"${k}" ×${n}`;
+    const [first, ...rest] = flapped;
+    const more = rest.length > 0 ? ` (and ${rest.length} more: ${rest.map(render).join(", ")})` : "";
+    return warnOutcome(`${agree(flapped.length, "check", "checks")} flapped more than once in the last 24h: ${render(first)}${more}`);
 }
 /** 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 fleet runs, just not
+ * 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 fleet": nothing will happen until main moves, and
+ * "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)
@@ -433,7 +911,7 @@ running = null) {
     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(`harness build ${sha} (this project is not the harness itself)`);
+        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}`);
@@ -445,7 +923,7 @@ running = null) {
             ? `; 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 run` (auto-restart does this for a running fleet)";
+                : "; 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`);