fix(pi): align the doctor with the pi resolver, correct the strip rationale, update the skill

Second review pass on #282, the three items left open after f4dcfbe.

1. `codeman doctor` and the run mode disagreed about pi. The registry entry
   accepted a bare `which pi` hit while pi-cli-resolver demanded semver-shaped
   `--version` output, so the Dependencies panel could report an installed Pi CLI
   on a box where Run Pi stays hidden, which reads as a broken mode rather than a
   missing install. Both sides now share one exported PI_VERSION_REGEX, and
   PathResolver gains an opt-in `requireVersionMatch` so a binary that fails the
   shape check is reported MISSING instead of installed-with-unknown-version.
   Only pi sets it; every other tool keeps its current behaviour.

2. The isAltScreenStripMode comment justified excluding pi with "the alt screen
   is load-bearing for its fullscreen TUI". That is not what exclusion does: pi
   is tmux-backed, so it falls through to isMuxAltScreenOnlyStripMode, which
   strips the alt-screen toggles anyway. What exclusion actually preserves is
   `\x1b[3J` and the mouse DECSETs, which is the real reason (pi renders into the
   main screen and is mouse-aware). Comment and changeset now say that, and state
   the consequence: fullscreen pi paints into the main buffer, like vim in a tmux
   shell session.

3. skills/codeman still enumerated the five pre-pi modes in nine places, telling
   agents a backend does not exist and understating class-wide caveats by one
   mode. All updated, plus stale session.ts line references refreshed.

Tests: a new static guard derives the mode set from the Zod schema (not a copy)
and fails when a skill enumeration lists a partial set of external CLIs, verified
by mutation. It also documents the one legitimate exception it found: the "writes
no transcript" lists drop codex, which does write a rollout Codeman reads back.
Plus doctor cases for an unrelated `pi` on PATH and registry/resolver regex parity.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.changeset/ba4bc996.md

@@ -10,8 +10,9 @@ Add Pi (pi.dev) as a sixth CLI run mode (#206).
 - **`PiConfig`** maps to `--model` (accepts `provider/id` and a `:thinking` suffix), `--provider`, `--thinking`, `--session`/`-c`, and the tri-state `--approve` / `--no-approve`. Every value is regex-allowlisted and dropped on failure. `--api-key` is deliberately never wired: it would put a provider secret on the spawn command line.
 - **No bypass flag.** Pi has no permission prompts and no sandbox, so there is no `--dangerously-skip-permissions` analog. Its privilege-shaped knob is `approveProjectTrust`, which makes pi load and execute repo-local `.pi/extensions` TypeScript and install missing project packages. `clampExternalCliBypassForOwner()` therefore puts pi in the **materialize** branch: a non-granted multi-user owner gets `--no-approve` even when no config was sent, because pi's own default is an interactive prompt the session user could answer themselves. The same materialization applies to cron-fired jobs (`clampCronExternalCliConfigs`), which carry no per-CLI config and would otherwise launch on pi's own default. Both helpers had no test coverage at all; they now do, for every CLI.
 - **Env allowlist gains only the `PI_*` prefix.** Pi's ~34 provider key vars share no prefix and `ALLOWED_ENV_PREFIXES` is one global list with no mode context, so admitting them would widen the allowlist for every mode at once. Users authenticate via pi's `/login` or the server process's own environment.
-- **Pi stays out of `isAltScreenStripMode()`.** Its default TUI renders into the main screen with terminal-owned scrollback, and since 0.84.0 the user can flip to a fullscreen TUI at runtime via `/settings` — verified to switch the pane into the alt screen, which the strip would have corrupted.
+- **Pi stays out of `isAltScreenStripMode()`.** Its default TUI renders into the main screen with terminal-owned scrollback and is mouse-aware, so it consumes `\x1b[3J` and the mouse DECSETs that the full strip removes, unlike an Ink TUI repainting in place. Note what exclusion does NOT do: pi is tmux-backed, so it still falls through to the narrow `isMuxAltScreenOnlyStripMode()` strip and its alt-screen toggles are dropped either way. Pi's runtime-switchable fullscreen TUI therefore paints into the main buffer, exactly like vim inside a tmux `shell` session.
 - **Docker**: pi installs in its own `--ignore-scripts` step so that flag cannot affect the other four CLIs, and its credentials are seeded per-file (`auth.json`, `settings.json`, `trust.json`, `models.json`, `models-store.json`) rather than whole-dir, since `~/.pi/agent` also holds sessions, extensions and installed package trees.
 - **Local echo**: pi lands on the buffer overlay. Verified that codex's per-keystroke starvation does not reproduce — pi's slash picker re-filters on the whole composer content, so a one-shot flush behaves identically to per-keystroke typing.
-- **Mode-list parity**: pi is excluded from the Ralph tracker auto-enable on `POST /api/sessions/:id/interactive` (like every other external CLI, whose output the tracker never parses), carries a `REMOTE_CLI_BIN` entry so a remote-SSH pi session reports its CLI version, and gets its own badge in the desktop home rail instead of rendering like Claude.
+- **Mode-list parity**: pi is excluded from the Ralph tracker auto-enable on `POST /api/sessions/:id/interactive` (like every other external CLI, whose output the tracker never parses), carries a `REMOTE_CLI_BIN` entry so a remote-SSH pi session reports its CLI version, and gets its own badge in the desktop home rail instead of rendering like Claude. The packaged agent skill's mode enumerations list pi too, pinned by a new guard that derives the mode set from the Zod schema instead of restating it.
+- **`codeman doctor` and the run mode agree about pi.** The registry entry resolved a bare `which pi` while `pi-cli-resolver` demanded semver output, so the Dependencies panel could report an installed Pi CLI that sessions refuse to launch. Both now share one exported regex, and the registry's new `requireVersionMatch` reports a non-semver `pi` as missing rather than installed. Only pi sets it; every other tool keeps its existing behaviour.
 - Installer detection, docs (`docs/pi-integration.md`), READMEs, and the architecture invariants are updated. Tests: `test/pi-mode.test.ts` and `test/routes/external-cli-bypass-clamp.test.ts`, plus extensions to the run-mode, mobile-overview, render-index-html, system-routes and local-echo suites.

skills/codeman/SKILL.md

@@ -568,7 +568,7 @@ recovered by submitting it with `{"input":"\r"}`.
 
 ⚠️ `stop` and `blocked` fire for `claude` sessions only (they are Claude Code hooks,
 and only when the workspace actually has them, see [§5.1](#51-where-to-spawn)). On
-`shell`/`opencode`/`codex`/`gemini`/`antigravity`, requesting them explicitly is a
+`shell`/`opencode`/`codex`/`gemini`/`antigravity`/`pi`, requesting them explicitly is a
 400, and lifecycle transitions there are coarse (a short shell command may emit **no**
 `idle` transition at all, verified live), so synchronize those with markers.
 
@@ -594,7 +594,8 @@ from the transcript file, which is flushed slightly *after* the `stop` hook fire
 single read taken the instant send-and-wait returns comes back `""` even though the
 turn finished (verified live: empty on the first call, full text seconds later). `text`
 is also `""` before the worker's first completed turn, and always `""` for modes with
-no transcript (`shell`, `opencode`, `gemini`, `antigravity`, verified live), which is
+no transcript (`shell`, `opencode`, `gemini`, `antigravity`, `pi`; the first four
+verified live, pi from the same source path), which is
 why the loop above is bounded rather than open-ended. Fall back to the terminal buffer
 there, tail in **bytes** (`textOutput` in `GET .../output` stays empty for interactive
 sessions; don't use it):
@@ -678,7 +679,7 @@ turn), and both better than diffing terminal samples:
 ```
 
 ⚠️ `active-tools` is parsed out of Claude's own output format, so it is **empty for
-`opencode`/`codex`/`gemini`/`antigravity`** (those parsers are skipped wholesale) and
+`opencode`/`codex`/`gemini`/`antigravity`/`pi`** (those parsers are skipped wholesale) and
 in practice empty for `shell`. Source-verified, not measured live.
 
 Only if neither helps: sample `terminal?tail=` twice a few seconds apart. A changing

skills/codeman/reference/endpoints.md

@@ -237,7 +237,7 @@ minutes, never retry the credential.
 flushed slightly *after* the `stop` hook fires, so a read taken the instant the wait
 returns is too early (verified live: empty on the first call, full prose seconds later).
 It is also `""` before the worker's first completed turn, and permanently `""` for
-`shell`, `opencode`, `gemini` and `antigravity`, which write no transcript.
+`shell`, `opencode`, `gemini`, `antigravity` and `pi`, which write no Claude transcript.
 
 **Fix** Poll it, bounded (10 tries, 1 s apart). If it is still empty on a hook-less mode,
 that is expected, not a failure: read `terminal?tail=` and strip ANSI instead.
@@ -334,7 +334,7 @@ ESC=$(printf '\033')
 
 `POST /api/v1/quick-start` body (all optional):
 `{"caseName":"worker-1","mode":"claude","sessionName":"w9-worker","effort":"high"}`
-,  `mode` ∈ `claude|shell|opencode|codex|gemini|antigravity`; response is
+,  `mode` ∈ `claude|shell|opencode|codex|gemini|antigravity|pi`; response is
 `.data.{sessionId, caseName, casePath}`. Creates the case directory (a real directory
 on the user's disk) if missing, do not retry it in a loop, and remember the name.
 
@@ -450,9 +450,9 @@ Quirks that will bite you:
   session answers with an empty timeline rather than a 404.
 - ⚠️ **`active-tools` proves presence, never absence.** It is fed by the BashToolParser,
   which reads Claude's rendered `● Bash(…)` lines, and `_processExpensiveParsers`
-  returns early for every external CLI mode (`session.ts:2086`), so it is permanently
-  `[]` on `opencode`/`codex`/`gemini`/`antigravity`. ⚠️ **`shell` is NOT one of those**
-  (`isExternalCliMode`, `session.ts:164-166`, lists only those four), so the parser does
+  returns early for every external CLI mode (`session.ts:2136`), so it is permanently
+  `[]` on `opencode`/`codex`/`gemini`/`antigravity`/`pi`. ⚠️ **`shell` is NOT one of those**
+  (`isExternalCliMode`, `session.ts:165-167`, lists only those five), so the parser does
   run on a shell worker, and `TEXT_COMMAND_PATTERN` (`bash-tool-parser.ts:88`) matches
   bare `tail|cat|head|less|grep|watch|multitail <path>` lines with no `● Bash(` wrapper:
   a shell worker running `cat build.log` really does populate this. In practice it stays

skills/codeman/reference/messaging.md

@@ -56,7 +56,7 @@ own head: the worker enforcing the cap is the one who has to be told about it.
 | synchronize on end of turn | HTTP `wait until=stop` (fires for message-initiated turns too, verified live) |
 | liveness / death check | HTTP `wait?until=exit` |
 | interrupt a running turn (break-glass) | HTTP input, a bare `\x1b` with no `\r` |
-| non-claude modes (`shell`/`opencode`/`codex`/`gemini`/`antigravity`) | HTTP only (no other CLI has messaging) |
+| non-claude modes (`shell`/`opencode`/`codex`/`gemini`/`antigravity`/`pi`) | HTTP only (no other CLI has messaging) |
 | delete | HTTP, via SKILL.md's `delete_session` guard |
 
 ## Availability: probe, never assume
@@ -345,7 +345,7 @@ Without a break-glass, a pair with a bad brief is a token bonfire with no off sw
 
 ### Mixed fleets: the pairing matrix
 
-Non-claude workers (`shell`, `opencode`, `codex`, `gemini`, `antigravity`) cannot be peers
+Non-claude workers (`shell`, `opencode`, `codex`, `gemini`, `antigravity`, `pi`) cannot be peers
 at all; no other CLI has this feature. Their tasks route over HTTP, and you never mention
 messaging in their briefs. The claude half of the fleet can use messaging among itself,
 subject to the namespace rule: **messaging works between two sessions that share one

skills/codeman/reference/recipes.md

@@ -177,7 +177,7 @@ for _ in $(seq 1 10); do
 done
 printf '%s\n' "$TXT"
 #    (.data is {text,timestamp}; text is also "" before the first completed turn and
-#     always "" for shell/opencode/gemini/antigravity, which have no transcript, use
+#     always "" for shell/opencode/gemini/antigravity/pi, which have no transcript, use
 #     the terminal tail there, and here only to diagnose an unsubmitted prompt.)
 
 # 6. clean up: exact id, own list only, through the fail-closed preamble helper

src/config/dependency-registry.ts

@@ -7,6 +7,8 @@
  * @module config/dependency-registry
  */
 
+import { PI_VERSION_REGEX } from '../utils/pi-cli-resolver.js';
+
 export type ProbeEnvironment = 'linux' | 'darwin' | 'win32' | 'wsl';
 
 /** The valid `--category` filter values; single source of truth for the type, the CLI
@@ -20,6 +22,13 @@ export interface PathResolver {
   bins: string[];
   versionArg?: string; // default '--version'
   versionRegex?: RegExp; // default matches first \d+.\d+(.\d+)?
+  /**
+   * Treat a binary whose version output does not match as NOT INSTALLED, instead of
+   * reporting it with an unknown version. Only for tools with a short, generic binary
+   * name (`pi`), where a `which` hit is not by itself evidence the right program is
+   * there and a false "installed" contradicts the run mode's own resolver.
+   */
+  requireVersionMatch?: boolean;
 }
 
 /** Resolve a Windows-installed app reachable from win32 or WSL. */
@@ -112,7 +121,23 @@ export const DEPENDENCY_REGISTRY: ToolDependency[] = [
     category: 'core',
     required: false,
     usedBy: ['Pi sessions'],
-    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['pi'], versionArg: '--version' } }],
+    // The only entry that requires a version match, for the same reason
+    // pi-cli-resolver.ts probes: `pi` is a short generic name (Raspberry Pi tooling,
+    // personal scripts), so a `which pi` hit alone is not the coding agent. Both sides
+    // share PI_VERSION_REGEX, so the doctor and the run mode cannot drift into telling
+    // the user opposite things about the same binary.
+    resolvers: [
+      {
+        match: ALL,
+        resolver: {
+          kind: 'path',
+          bins: ['pi'],
+          versionArg: '--version',
+          versionRegex: PI_VERSION_REGEX,
+          requireVersionMatch: true,
+        },
+      },
+    ],
   },
   {
     id: 'libreoffice',

src/session.ts

@@ -194,11 +194,20 @@ function getModeLabel(mode: SessionMode): string {
  * repaint via cursor positioning, so dropping the alt-screen switch is safe —
  * content stays in the normal buffer. Excluded: `shell` (arbitrary programs like
  * vim/less/htop legitimately need the alt screen), `opencode` (renders its own
- * TUI that may rely on it) and `pi` (its default TUI already renders into the
- * MAIN screen with terminal-owned scrollback, so there is nothing to strip — and
- * since pi 0.84.0 the user can switch to a fullscreen TUI at runtime via
- * `/settings`, where the alt screen is load-bearing). Keep parity with the
- * replay-side strip in session-routes.ts.
+ * TUI that may rely on it) and `pi` (below). Keep parity with the replay-side
+ * strip in session-routes.ts.
+ *
+ * ⚠️ Being excluded here does NOT preserve the alt screen. Every excluded mode
+ * falls through to isMuxAltScreenOnlyStripMode(), which strips the alt-screen
+ * toggles too whenever the session is tmux-backed, and pi/opencode ALWAYS are
+ * (both refuse the direct-PTY fallback). What exclusion actually buys is the rest
+ * of the full strip: `\x1b[3J` and the mouse-tracking DECSETs survive. That is the
+ * real reason pi is out: its default TUI renders into the MAIN screen with
+ * terminal-owned scrollback and is mouse-aware, so it is a `3J`/mouse consumer in
+ * a way an Ink TUI repainting in place is not. Consequence to know before
+ * debugging it: pi's runtime-switchable fullscreen TUI (`/settings`, 0.84.0+)
+ * still gets its `?1049h` stripped and paints into the main buffer, exactly like
+ * vim inside a tmux `shell` session.
  */
 export function isAltScreenStripMode(mode: SessionMode): boolean {
   return mode === 'codex' || mode === 'claude' || mode === 'gemini';

src/utils/dependency-checker.ts

@@ -94,12 +94,17 @@ export function checkTool(tool: ToolDependency, host: ProbeHost): ToolResult {
   if (!spec) return { ...base, status: 'skipped', reason: `not applicable on ${host.environment}` };
 
   if (spec.resolver.kind === 'path') {
-    const { bins, versionArg, versionRegex } = spec.resolver;
+    const { bins, versionArg, versionRegex, requireVersionMatch } = spec.resolver;
     for (const bin of bins) {
       const resolved = host.which(bin);
       if (resolved) {
         const out = host.runVersion(bin, [versionArg ?? '--version']);
         const version = out ? extractVersion(out, versionRegex) : undefined;
+        // A generic binary name that prints the wrong thing is some OTHER program (see
+        // PathResolver.requireVersionMatch). Keep looking, then report MISSING; the
+        // alternative is claiming a tool is installed that the feature's own resolver
+        // rejects, which reads as "the mode is broken" rather than "install it".
+        if (requireVersionMatch && !version) continue;
         return finalize(base, tool, resolved, version);
       }
     }

src/utils/pi-cli-resolver.ts

@@ -30,8 +30,20 @@ const PI_SEARCH_DIRS = [
   join(homedir(), 'bin'),
 ];
 
-/** A real `pi --version` prints a semver-shaped string (e.g. `0.84.1`). */
-const PI_VERSION_PATTERN = /^\d+\.\d+\.\d+/;
+/**
+ * A real `pi --version` prints a semver-shaped string (e.g. `0.84.1`).
+ *
+ * Exported and SHARED with the `pi` entry in `config/dependency-registry.ts`, so
+ * `codeman doctor` and the run mode cannot disagree about what counts as an installed
+ * pi: two copies of this rule would let the Dependencies panel report "Pi CLI ✓" on a
+ * box where `resolvePiDir()` rejects the same binary and Run Pi stays hidden.
+ *
+ * Shape is dictated by the doctor's `extractVersion()`, which returns the first CAPTURE
+ * GROUP and scans the whole output: hence a capturing group, and a leading boundary
+ * instead of `^` so `pi 0.84.1` matches while `v0.84.1` (some other program) does not.
+ * No `g` flag, so there is no shared `lastIndex` to reset.
+ */
+export const PI_VERSION_REGEX = /(?:^|\s)(\d+\.\d+\.\d+)/;
 
 /** Cached directory containing the pi binary (empty string = searched but not found) */
 let _piDir: string | null = null;
@@ -56,7 +68,7 @@ function probePiVersion(binPath: string): string | null {
       stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
     // Upstream prints a bare version today; tolerate a `pi 0.84.1` style prefix too.
-    const candidate = out.split(/\s+/).find((token) => PI_VERSION_PATTERN.test(token));
+    const candidate = PI_VERSION_REGEX.exec(out)?.[1];
     if (candidate) return candidate;
     console.warn(`[PiResolver] Ignoring ${binPath}: "pi --version" printed ${JSON.stringify(out.slice(0, 80))}`);
   } catch (err) {

test/agent-skill-mode-lists.test.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview Static guard: the packaged agent skill's run-mode enumerations stay in
+ * step with the modes the server actually accepts.
+ *
+ * `skills/codeman/**` is injected into cases and read by agents driving Codeman over
+ * HTTP, so a mode missing from its lists is not cosmetic: the agent is told a backend
+ * does not exist, or that a whole-class caveat ("these modes write no transcript")
+ * covers four modes when it covers five. Adding pi (#206) left every one of those lists
+ * stale while CI stayed green, because nothing tied the prose to the schema.
+ *
+ * Two rules, both derived from the RUNTIME source of truth (the Zod enum in schemas.ts,
+ * not a copy):
+ *
+ *  1. The `mode ∈ a|b|c` enumeration in endpoints.md is the mode list, exactly.
+ *  2. Any prose enumeration of 3+ distinct modes must be COMPLETE with respect to the
+ *     external CLIs: those lists exist to describe what `isExternalCliMode()` gates
+ *     (no Claude transcript, no hooks, no Claude-format parsers), so naming some but
+ *     not all of them is the drift itself. Runs of one or two modes are exempt, since
+ *     a legitimate pair ("claude or shell") is not a class claim. ONE exception is
+ *     allowed and it is a real one: the "writes no transcript" lists drop `codex`,
+ *     which does write a rollout Codeman reads back (the pane carries a unique
+ *     originator precisely so `last-response` can find it), so external-minus-codex
+ *     is a meaningful class rather than an oversight.
+ *
+ * Port: N/A (pure static analysis).
+ */
+
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { CreateSessionSchema, QuickStartSchema } from '../src/web/schemas.js';
+import { isExternalCliMode } from '../src/session.js';
+import type { SessionMode } from '../src/types/session.js';
+
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+const SKILL_DIR = join(HERE, '../skills/codeman');
+const SKILL_FILES = ['SKILL.md', 'reference/endpoints.md', 'reference/messaging.md', 'reference/recipes.md'];
+
+/** Modes the API actually accepts, read off the schema rather than restated here. */
+function schemaModes(schema: typeof CreateSessionSchema | typeof QuickStartSchema): SessionMode[] {
+  // `mode` is `z.enum([...]).optional()`; unwrap the optional to reach `.options`.
+  return (schema as unknown as { shape: { mode: { unwrap(): { options: SessionMode[] } } } }).shape.mode.unwrap()
+    .options;
+}
+
+const MODES = schemaModes(CreateSessionSchema);
+const EXTERNAL_MODES = MODES.filter(isExternalCliMode);
+
+/**
+ * Mode tokens appearing back to back, separated only by list punctuation — `a|b|c`,
+ * `a`/`b`/`c`, "`a`, `b` and `c`". Newlines collapse to spaces first so a wrapped list
+ * still reads as one run. The separator budget is deliberately small: it must span
+ * ", " and " and " without swallowing a sentence between two unrelated mentions.
+ */
+const MODE_ALTERNATION = MODES.map((m) => `\`?${m}\`?`).join('|');
+const ENUMERATION_RUN = new RegExp(`(?:(?:${MODE_ALTERNATION})(?:[\\s,/|]|and\\b|or\\b){0,6}){3,}`, 'g');
+
+function enumerationRuns(text: string): string[] {
+  const flat = text.replace(/\s+/g, ' ');
+  return [...flat.matchAll(ENUMERATION_RUN)].map((m) => m[0]);
+}
+
+function modesIn(run: string): SessionMode[] {
+  return MODES.filter((m) => new RegExp(`\\b${m}\\b`).test(run));
+}
+
+describe('agent skill run-mode lists', () => {
+  it('derives the mode list from the schema, and both endpoints agree', () => {
+    expect(MODES).toContain('pi');
+    expect(new Set(schemaModes(QuickStartSchema))).toEqual(new Set(MODES));
+    expect(EXTERNAL_MODES.length).toBeGreaterThan(1);
+  });
+
+  it("documents exactly the accepted modes in endpoints.md's `mode ∈ …` enumeration", () => {
+    const doc = readFileSync(join(SKILL_DIR, 'reference/endpoints.md'), 'utf-8');
+    const match = doc.match(/`mode` ∈ `([a-z|]+)`/);
+    expect(match, 'endpoints.md no longer states the accepted `mode` values').not.toBeNull();
+    expect(new Set(match![1].split('|'))).toEqual(new Set(MODES));
+  });
+
+  it('never enumerates a partial set of external CLI modes', () => {
+    const complete = new Set<string>(EXTERNAL_MODES);
+    /** The documented exception: codex writes a rollout, so it is absent from the
+     *  "no transcript" lists on purpose. Every OTHER external mode must still be there. */
+    const withoutCodex = new Set<string>(EXTERNAL_MODES.filter((m) => m !== 'codex'));
+    const sameSet = (a: Set<string>, b: Set<string>) => a.size === b.size && [...a].every((v) => b.has(v));
+
+    const offenders: string[] = [];
+    for (const file of SKILL_FILES) {
+      for (const run of enumerationRuns(readFileSync(join(SKILL_DIR, file), 'utf-8'))) {
+        const listed = modesIn(run);
+        if (listed.length < 3) continue;
+        const externals = new Set<string>(listed.filter(isExternalCliMode));
+        // Empty is fine (a claude/shell-only list); partial is the drift.
+        if (externals.size === 0 || sameSet(externals, complete) || sameSet(externals, withoutCodex)) continue;
+        const missing = EXTERNAL_MODES.filter((m) => !externals.has(m));
+        offenders.push(`${file}: "${run.trim()}" is missing ${missing.join(', ')}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});

test/dependency-checker.test.ts

@@ -10,6 +10,7 @@ import {
 } from '../src/utils/dependency-checker.js';
 import type { ProbeHost } from '../src/utils/dependency-checker.js';
 import type { ProbeEnvironment, ToolDependency } from '../src/config/dependency-registry.js';
+import { PI_VERSION_REGEX } from '../src/utils/pi-cli-resolver.js';
 
 describe('DEPENDENCY_REGISTRY', () => {
   it('has unique ids', () => {
@@ -29,6 +30,20 @@ describe('DEPENDENCY_REGISTRY', () => {
     expect(office.every((t) => t.required === false)).toBe(true);
   });
 
+  it('resolves pi through the SAME version rule the run mode uses', () => {
+    // `pi` is a short generic name, so pi-cli-resolver.ts refuses a binary that does not
+    // print semver. If the doctor did not apply the identical rule it would report
+    // "Pi CLI ✓" on a box where Run Pi stays hidden, which reads as a broken mode
+    // rather than a missing install. One regex, shared, is what keeps them agreeing.
+    const pi = DEPENDENCY_REGISTRY.find((t) => t.id === 'pi');
+    expect(pi).toBeDefined();
+    const spec = pi!.resolvers.find((r) => r.resolver.kind === 'path');
+    expect(spec).toBeDefined();
+    const resolver = spec!.resolver as { versionRegex?: RegExp; requireVersionMatch?: boolean };
+    expect(resolver.requireVersionMatch).toBe(true);
+    expect(resolver.versionRegex).toBe(PI_VERSION_REGEX);
+  });
+
   it('gives msoffice a windows-side resolver scoped to wsl + win32 only', () => {
     const ms = DEPENDENCY_REGISTRY.find((t) => t.id === 'msoffice');
     expect(ms).toBeDefined();
@@ -164,6 +179,54 @@ describe('checkTool', () => {
   });
 });
 
+describe('checkTool with requireVersionMatch (generic binary names)', () => {
+  const piTool: ToolDependency = {
+    id: 'pi',
+    label: 'Pi CLI',
+    category: 'core',
+    required: false,
+    resolvers: [
+      {
+        match: ['linux'],
+        resolver: {
+          kind: 'path',
+          bins: ['pi'],
+          versionArg: '--version',
+          versionRegex: PI_VERSION_REGEX,
+          requireVersionMatch: true,
+        },
+      },
+    ],
+  };
+
+  it('accepts a binary that prints a semver version', () => {
+    const host = fakeHost('linux', { which: () => '/home/u/.npm-global/bin/pi', runVersion: () => '0.84.1\n' });
+    expect(checkTool(piTool, host)).toMatchObject({
+      id: 'pi',
+      status: 'ok',
+      version: '0.84.1',
+      path: '/home/u/.npm-global/bin/pi',
+    });
+  });
+
+  it('reports MISSING for an unrelated `pi` on PATH instead of an installed tool', () => {
+    // The whole point: a Raspberry Pi helper answers `--version` with prose, and calling
+    // that "installed" contradicts resolvePiDir(), which rejects it.
+    const host = fakeHost('linux', { which: () => '/usr/bin/pi', runVersion: () => 'Raspberry Pi utility\n' });
+    expect(checkTool(piTool, host)).toMatchObject({ id: 'pi', status: 'missing' });
+  });
+
+  it('reports MISSING when the binary answers nothing at all', () => {
+    const host = fakeHost('linux', { which: () => '/usr/bin/pi', runVersion: () => null });
+    expect(checkTool(piTool, host)).toMatchObject({ id: 'pi', status: 'missing' });
+  });
+
+  it('leaves tools without the flag reporting ok on an unparsable version (unchanged)', () => {
+    const host = fakeHost('linux', { which: () => '/usr/bin/tmux', runVersion: () => 'no version here' });
+    expect(checkTool(tmuxTool, host)).toMatchObject({ id: 'tmux', status: 'ok', version: undefined });
+  });
+});
+
 describe('checkAll', () => {
   it('maps every tool to a result', () => {
     const results = checkAll([tmuxTool, msTool], fakeHost('linux'));