commandmate 0.29.1 → 0.30.0

package/dist/server/src/lib/detection/tool-liveness.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * "Did the TOOL exit and leave a bare shell behind?" — the shared rule
+ * (Issue #2070).
+ *
+ * A tmux session outlives the process it was created for more often than the
+ * code used to admit. codex's own update dialog replaces codex with `npm
+ * install` and exits; `Ctrl+C` twice quits it; a crash does the same thing
+ * without asking. In each case `has-session` keeps answering yes, so `isRunning`
+ * stayed true, the sidebar kept its dot, and the next `send` sat in
+ * `waitForPrompt` until it timed out — recoverable only by killing the session
+ * by hand.
+ *
+ * CommandMate already had the answer to this, written for claude and reachable
+ * from exactly one `cliToolId === 'claude'` branch (`isSessionHealthy`). What
+ * was claude-specific about it was not the rule but the two patterns it was
+ * spelled in terms of. This module is that rule with the patterns lifted out
+ * into {@link ToolLivenessSpec}; `lib/cli-tools/liveness-spec` is where each
+ * tool fills them in.
+ *
+ * Pure and synchronous on purpose: no tmux, no capture, nothing to mock. The
+ * probe that feeds it a frame is `probeSessionLiveness` in
+ * `lib/cli-tools/session-liveness`, which is where the tmux round trip belongs
+ * (§4 D4 keeps `src/lib/detection/**` off the transport).
+ *
+ * @module lib/detection/tool-liveness
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FATAL_PATTERN_TAIL_LINES = exports.SHELL_PROMPT_LINE_PATTERNS = exports.MAX_SHELL_PROMPT_LENGTH = exports.SHELL_PROMPT_ENDINGS = void 0;
+exports.findFatalPattern = findFatalPattern;
+exports.findShellPromptTail = findShellPromptTail;
+exports.judgeToolLiveness = judgeToolLiveness;
+const ansi_1 = require("./ansi");
+/**
+ * Trailing characters that make a short last row a shell prompt.
+ *
+ * `$` bash/sh, `%` zsh, `#` root. Verbatim the list `claude-session.ts` has
+ * carried as its private `SHELL_PROMPT_ENDINGS` since the health check was
+ * written — moved, not redesigned.
+ */
+exports.SHELL_PROMPT_ENDINGS = ['$', '%', '#'];
+/**
+ * Longest a last row may be and still be read as a shell prompt by the endings
+ * rule alone.
+ *
+ * claude's number, kept as claude's default (`MAX_SHELL_PROMPT_LENGTH`, "40 is
+ * an empirical threshold with safety margin"). Issue #2070 measured why it
+ * cannot be the whole rule: the zsh default prompt of the machine the Issue was
+ * reproduced on renders as `maenokota@MAENOnoMac-Studio work-codex %` — forty
+ * characters exactly, i.e. one past this gate — so a codex session that had
+ * genuinely fallen back to the shell read as alive. See
+ * {@link SHELL_PROMPT_LINE_PATTERNS}.
+ */
+exports.MAX_SHELL_PROMPT_LENGTH = 40;
+/**
+ * Whole-line forms that positively identify a shell prompt, independent of
+ * length (Issue #2070).
+ *
+ * Checked BEFORE the length gate, so a long-but-real prompt is still a prompt.
+ * Both are anchored at both ends and require a `user@host` head, which is what
+ * keeps them off TUI content: an agent's transcript row that happens to end in
+ * `$` does not begin with `name@host`.
+ *
+ * Deliberately NOT extended to the bare `❯` / `>` prompts starship, pure and
+ * agnoster draw. Those glyphs are the composer of claude, copilot and gemini —
+ * `COPILOT_PROMPT_PATTERN` matching a starship prompt is a measured hazard
+ * (#1907) — so a rule that read them as "shell" would relaunch a tool into its
+ * own live pane. The cost is a false NEGATIVE on those prompts (the exit is not
+ * noticed), which is the direction this rule is allowed to be wrong in.
+ */
+exports.SHELL_PROMPT_LINE_PATTERNS = [
+    // zsh / bash defaults: `user@host dir %`, `user@host:~/dir$`
+    /^[\w.-]+@[\w.-]+[\s:].*[$%#]$/,
+    // RHEL-style bash: `[user@host dir]$`
+    /^\[[\w.-]+@[\w.-]+[^\]]*\][$#]$/,
+];
+/**
+ * How many content rows from the bottom a fatal-pattern search may read.
+ *
+ * claude's `HEALTH_CHECK_ERROR_TAIL_LINES`, unchanged: an error that has already
+ * scrolled up describes a session that recovered, and must not condemn it.
+ */
+exports.FATAL_PATTERN_TAIL_LINES = 10;
+/** `cleanOutput` split into rows, blank ones dropped. */
+function contentRows(cleanTrimmedOutput) {
+    return cleanTrimmedOutput.split('\n').filter((line) => line.trim() !== '');
+}
+/**
+ * The fatal pattern visible in the tail of `cleanOutput`, or null.
+ *
+ * Only the last {@link FATAL_PATTERN_TAIL_LINES} content rows are searched.
+ * Exported because claude's launch loop applies the same judgement while it is
+ * still waiting for the prompt (Issue #1637) — a session already showing
+ * "Claude Code cannot be launched inside another Claude Code session" must not
+ * burn the whole 60 s budget before saying so.
+ *
+ * @param cleanOutput - ANSI-stripped pane output
+ * @param spec - The tool's liveness declaration
+ * @returns The matched pattern (or regex source) for the log, or null
+ */
+function findFatalPattern(cleanOutput, spec) {
+    const tailText = contentRows(cleanOutput.trim())
+        .slice(-exports.FATAL_PATTERN_TAIL_LINES)
+        .join('\n');
+    for (const pattern of spec.fatalPatterns) {
+        if (tailText.includes(pattern))
+            return pattern;
+    }
+    for (const regex of spec.fatalRegexPatterns) {
+        if (regex.test(tailText))
+            return regex.source;
+    }
+    return null;
+}
+/**
+ * Whether `line` ends in one of `endings`, applying claude's own exclusion.
+ *
+ * `Context left until auto-compact: 7%` ends in `%` and is not a prompt; the
+ * `\d+%$` carve-out is the one claude has always had, and it is kept here
+ * character for character because claude's verdicts must not move (Issue #2070
+ * 受入条件).
+ */
+function endsWithShellPromptChar(line, endings) {
+    return endings.some((ending) => {
+        if (!line.endsWith(ending))
+            return false;
+        if (ending === '%' && /\d+%$/.test(line))
+            return false;
+        return true;
+    });
+}
+/**
+ * The bottom row of `cleanOutput`, when it reads as a shell prompt.
+ *
+ * Steps 4-6 of {@link judgeToolLiveness}, lifted out verbatim so there is one
+ * definition of "this pane is a bare shell" rather than two. Note what is NOT
+ * here: the alive-pattern window of step 2. That is the difference between the
+ * two questions, and it is why this is exported (Issue #2068).
+ *
+ * `judgeToolLiveness` asks **"is the tool gone?"** and answers conservatively —
+ * any alive pattern anywhere in the bottom window vetoes the exit, because a
+ * relaunch hangs off its verdict. That veto is right for the general case and
+ * wrong for exactly one measured frame: the pane codex leaves behind after its
+ * own `1. Update now`. codex-cli 0.149.1 exits into `npm install -g
+ * @openai/codex`, which prints three rows and returns to the shell — so the
+ * dead `› 1. Update now` option row is still SEVEN content rows above the live
+ * shell prompt, inside `LIVENESS_ALIVE_TAIL_LINES`, and `CODEX_PROMPT_PATTERN`
+ * reads it as codex still drawing the pane (measured 2026-08-31, private tmux
+ * socket, 200x1000, isolated `CODEX_HOME`).
+ *
+ * `CodexTool.waitForReady` therefore asks this narrower question instead, and
+ * only about a pane it has just watched answer the update dialog — where the
+ * scrollback above the prompt is known to be spent and position is the whole
+ * story, exactly as it is for every other codex classifier since Issue #892.
+ * Widening `judgeToolLiveness` itself to agree would be a change to the shared
+ * rule every tool is judged by, and it is not made here.
+ *
+ * @param cleanOutput - ANSI-stripped pane output
+ * @param spec - The tool's liveness declaration
+ * @returns The prompt row and how it was recognised, or null
+ */
+function findShellPromptTail(cleanOutput, spec) {
+    const rows = contentRows(cleanOutput.trim());
+    const lastLine = rows[rows.length - 1]?.trim() ?? '';
+    if (!/\d+%$/.test(lastLine) && spec.shellPromptPatterns.some((p) => p.test(lastLine))) {
+        return { line: lastLine, via: 'pattern' };
+    }
+    // The length gate is a NEGATIVE result, not a fall-through: a row this long is
+    // not a prompt, and the endings rule below must not get to claim it.
+    if (lastLine.length >= spec.maxShellPromptLength) {
+        return null;
+    }
+    if (endsWithShellPromptChar(lastLine, spec.shellPromptEndings)) {
+        return { line: lastLine, via: 'ending' };
+    }
+    return null;
+}
+/**
+ * Decide whether the tool this spec describes is still drawing the pane.
+ *
+ * The rule, in the order the branches run — which is claude's order, because
+ * claude's spec must produce claude's historical answers:
+ *
+ *  1. **nothing on the pane** → exited only if the spec says an unreadable
+ *     frame counts (claude alone; see {@link ToolLivenessSpec.unreadableIsExited});
+ *  2. **an alive pattern matches the bottom window** → alive. This is the
+ *     tool's prompt-ready rule and its busy/dialog chrome, and it is checked
+ *     against a WINDOW rather than the frame for every tool but claude: a tool's
+ *     chrome does not vanish when it quits, it scrolls up;
+ *  3. **a fatal pattern in the tail** → exited;
+ *  4. **the last row positively reads as a shell prompt** → exited;
+ *  5. **the last row is too long to be a prompt** → alive;
+ *  6. **the last row ends in `$` / `%` / `#`** → exited;
+ *  7. otherwise **alive** — the honest answer when nothing said either way.
+ *
+ * Steps 4-6 are the positive half of the verdict and they are not optional.
+ * A frame that merely fails step 2 (a tool mid-launch, a screen nobody has
+ * measured) must come out ALIVE, because Issue #2070 puts a relaunch behind
+ * this answer and a relaunch into a live pane types the launch command into the
+ * agent's composer.
+ *
+ * @param rawOutput - Pane capture, ANSI intact (stripped here)
+ * @param spec - The tool's liveness declaration
+ * @returns Whether the tool is there, and — when it is not — why not
+ */
+function judgeToolLiveness(rawOutput, spec) {
+    const trimmed = (0, ansi_1.stripAnsi)(rawOutput).trim();
+    if (trimmed === '') {
+        return spec.unreadableIsExited
+            ? { alive: false, reason: 'empty output' }
+            : { alive: true };
+    }
+    const rows = contentRows(trimmed);
+    const aliveWindow = spec.aliveTailLines === null ? trimmed : rows.slice(-spec.aliveTailLines).join('\n');
+    if (spec.alivePatterns.some((pattern) => pattern.test(aliveWindow))) {
+        return { alive: true };
+    }
+    const fatal = findFatalPattern(trimmed, spec);
+    if (fatal !== null) {
+        return { alive: false, reason: `error pattern: ${fatal}` };
+    }
+    // Steps 4-6, via the predicate they were lifted into (Issue #2068). The two
+    // reason strings are unchanged, and so is the verdict for every frame: a
+    // `null` here is the old "too long" and "nothing matched" branches, which both
+    // came out alive.
+    const shellTail = findShellPromptTail(trimmed, spec);
+    if (shellTail !== null) {
+        return shellTail.via === 'pattern'
+            ? { alive: false, reason: `shell prompt detected: ${shellTail.line}` }
+            : { alive: false, reason: `shell prompt ending detected: ${shellTail.line}` };
+    }
+    return { alive: true };
+}

package/dist/server/src/lib/detection/version-probes.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * `DETECTOR_VERSION_PROBES` — are the detector's rules still describing the CLI
+ * that is installed? (Issue #1929, 方針書 §4 D2 / §7 / §10.11 / §13.2 S17)
+ *
+ * Every rule in `src/lib/detection/tools/` was read off a capture of one build
+ * of one CLI. `tools/verified-against.ts` records which build. This module reads
+ * the other half of the comparison — the version that is installed right now —
+ * so `capture --json` and `commandmate status` can say "these rules were
+ * measured against copilot 1.0.80 and you are running 1.2.0" instead of leaving
+ * a reader to guess whether a misdetection is a bug or a version skew.
+ *
+ * ## The cost rules, and why they are not optional
+ *
+ * `capture --json` and `GET /current-output` are the **5-second polling path** —
+ * the monitor skills run them with no iteration cap. A probe table that spawns
+ * six children cannot sit on that path, so (DR3-013):
+ *
+ *  - probes run **once per process**, concurrent first callers share the same
+ *    in-flight promise, and the result is cached;
+ *  - {@link getDetectorStalenessSnapshot} **never awaits a child process**. It
+ *    answers from the cache or answers `undefined` and starts the probe in the
+ *    background. `undefined` means "not known yet", never "nothing is stale":
+ *    the hint is additive, so a poll that lands cold simply shows nothing and
+ *    the next one shows the banner;
+ *  - {@link getDetectorFreshness} is the awaiting form, for the two callers that
+ *    genuinely want the answer (`commandmate status`, `check:detector-freshness`)
+ *    and are operator-initiated one-offs.
+ *
+ * ## The execution rules (DR4-010 / §10.11)
+ *
+ * `PATH` is untrusted input: the server's `PATH` comes from the shell that
+ * started it, and a repo-local `node_modules/.bin` on it would let opening a
+ * worktree decide which binary a cold probe runs. So every `execFile` probe
+ * resolves its command to an **absolute path** through
+ * {@link findExecutableOnPath} first and **skips entirely** — spawning nothing —
+ * when that resolves to nothing; children run with `sanitizeEnvForChildProcess()`
+ * so no probe ever sees CommandMate's auth token or DB path; and both `timeout`
+ * and `maxBuffer` are explicit.
+ *
+ * ## copilot is delegated, and must stay delegated (S17)
+ *
+ * The design policy's first draft probed `gh copilot -- --version`. It cannot be
+ * used: `copilot` is not a gh extension but a preview command built into gh
+ * 2.86.0, and gh's own help says that when `PATH` has no copilot it
+ * **downloads** the CLI into `~/.local/share/gh/copilot`. A version hint that
+ * installs software is not a version hint. #1907 measured this and built
+ * {@link resolveCopilotExecutable}; #1913 wired it into the catalog's
+ * `VERSION_PROBES` as `kind: 'delegated'`; this table reuses the same shape.
+ *
+ * Delegating is not an exception to DR4-010 (1) — it satisfies it more strongly
+ * than an `execFile` row could, because `CopilotTool.isInstalled()` and
+ * `startSession()` decide what to launch from **the same function's same return
+ * value**, so probe and launch cannot disagree.
+ *
+ * ## What "probes must not modify the environment" can actually mean (measured)
+ *
+ * DR4-010 (5) says a probe must not change the environment ("installation,
+ * download, or config-file generation"). Measured on 2026-08-23 (macOS
+ * darwin 25.6.0) by running each `--version` under a **disposable** `HOME` /
+ * `XDG_DATA_HOME` / `XDG_CONFIG_HOME` and listing what appeared:
+ *
+ * | probe                | version   | warm ms | wrote into a pristine HOME              |
+ * |----------------------|-----------|---------|------------------------------------------|
+ * | `claude --version`   | 2.1.240   | 199     | nothing                                   |
+ * | `agy --version`      | 1.1.18    | 176     | nothing                                   |
+ * | `codex --version`    | 0.148.0   | 172     | `~/.codex/tmp/arg0`                       |
+ * | `opencode --version` | 1.18.21   | 404     | `~/.config/opencode`, `~/.cache/opencode`, `~/.local/{state,share}/opencode` |
+ * | `copilot --version`  | 1.0.80    | 436     | `~/Library/Caches/copilot`                |
+ * | `gemini --version`   | 0.55.1    | 929     | `~/.gemini/projects.json.<uuid>.tmp` ×2 (leaked, not cleaned up) |
+ *
+ * So the literal reading of (5) is satisfied by **two** of the six probes, and
+ * four of the rows the policy already approved fail it. The rule that the D2
+ * premise actually rests on is the narrower one #1979 was defending: a probe
+ * must not **install or download software, or change which binary would be
+ * launched**. Every row above satisfies that; none of them fetches anything.
+ * The gemini row is the weakest — it leaks two temp files into a `~/.gemini`
+ * that does not exist yet — and it is kept because it is the same class of
+ * side effect as codex/opencode/copilot, which are already in the table, and
+ * because dropping gemini would leave the one tool with **no** measured
+ * detector rules also with no way to notice that.
+ *
+ * `~/.config/gh` and `~/.local/share/gh` were checksummed before and after the
+ * whole measurement and neither changed (`~/.local/share/gh` still does not
+ * exist), which is the receipt #1979 asked for.
+ *
+ * ## Why this module imports nothing through `@/`
+ *
+ * `commandmate status` is one of the two exposure surfaces §4 D2 names, and
+ * `tsconfig.cli.json` compiles the CLI with `"paths": {}`. See the same
+ * constraint spelled out in `src/cli/types/api-responses.ts`.
+ *
+ * @module lib/detection/version-probes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DETECTOR_VERSION_PROBES = exports.DETECTOR_VERSION_PROBE_TIMEOUT_MS = void 0;
+exports.parseCliVersion = parseCliVersion;
+exports.parseVerifiedAgainstVersion = parseVerifiedAgainstVersion;
+exports.compareCliVersions = compareCliVersions;
+exports.runDetectorVersionProbe = runDetectorVersionProbe;
+exports.getDetectorFreshness = getDetectorFreshness;
+exports.toDetectorStaleness = toDetectorStaleness;
+exports.getDetectorStalenessSnapshot = getDetectorStalenessSnapshot;
+exports.clearDetectorVersionProbeCache = clearDetectorVersionProbeCache;
+const child_process_1 = require("child_process");
+const copilot_executable_1 = require("../cli-tools/copilot-executable");
+const env_sanitizer_1 = require("../security/env-sanitizer");
+const verified_against_1 = require("./tools/verified-against");
+/** Budget for one `<cli> --version`. Matches the catalog probe and copilot-executable. */
+exports.DETECTOR_VERSION_PROBE_TIMEOUT_MS = 5000;
+/**
+ * Cap on `--version` output kept in memory (DR4-010 (4)).
+ *
+ * `execFile` defaults to 1MB. A `--version` that answers with a megabyte is
+ * already misbehaving, so the buffer is sized to a version banner and the child
+ * is killed past it; the over-long answer is discarded rather than parsed.
+ */
+const DETECTOR_VERSION_PROBE_MAX_BUFFER_BYTES = 64 * 1024;
+/** Extracts a `major.minor.patch` triple from arbitrary `--version` output. */
+const VERSION_REGEX = /(\d+)\.(\d+)\.(\d+)/;
+/** Extract a normalized `major.minor.patch` version from `--version` output. */
+function parseCliVersion(output) {
+    const match = VERSION_REGEX.exec(output);
+    return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+/**
+ * A `verifiedAgainst` stamp written as a minor-series wildcard: `0.4.x`.
+ *
+ * Only ever applied to the stamp, never to a probe's own output — one side of
+ * this comparison is a string a human typed into a tool module, the other is
+ * what a binary printed about itself, and only the first is allowed to be vague.
+ */
+const VERIFIED_AGAINST_WILDCARD_REGEX = /^(\d+)\.(\d+)\.(?:x|\*)$/i;
+/**
+ * The comparable form of a `verifiedAgainst` stamp, or null when there is none.
+ *
+ * `'unmeasured'` is null — a tool nobody has captured frames for cannot be
+ * fresh or stale. `'0.4.x'` becomes `0.4.0`: antigravity's stamp is a minor
+ * series rather than a build (Issue #995 measured a range), and reading it as
+ * "no version" would silently exempt the one tool whose rules are furthest
+ * behind. Widening to `.0` is the safe direction — it can only ever call a
+ * newer install stale, never call a stale one current.
+ */
+function parseVerifiedAgainstVersion(stamp) {
+    const wildcard = VERIFIED_AGAINST_WILDCARD_REGEX.exec(stamp);
+    if (wildcard)
+        return `${wildcard[1]}.${wildcard[2]}.0`;
+    return parseCliVersion(stamp);
+}
+/**
+ * Compare two `major.minor.patch` versions numerically.
+ * @returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
+function compareCliVersions(a, b) {
+    const pa = a.split('.').map((n) => Number(n) || 0);
+    const pb = b.split('.').map((n) => Number(n) || 0);
+    for (let i = 0; i < 3; i++) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0)
+            return diff > 0 ? 1 : -1;
+    }
+    return 0;
+}
+/**
+ * Detector staleness probes: tool id → how to read its installed version.
+ *
+ * Deliberately the same shape as `VERSION_PROBES` in `slash-command-catalog.ts`
+ * (§4 D2: 「`VERSION_PROBES` と同型」), and deliberately a separate table: the
+ * catalog's question is "is the bundled slash-command list behind?" and this
+ * one's is "were these detection rules read off the build that is installed?".
+ * They happen to agree today; nothing requires them to.
+ *
+ * The binary for antigravity is `agy` — tool id and executable name differ
+ * (DR2-023). `gemini`'s row is `gemini --version`, measured for this Issue (the
+ * policy left it unconfirmed); its `verifiedAgainst` is `unmeasured`, so it is
+ * reported as "installed, rules never measured" rather than compared.
+ * `vibe-local` has no row: it is not an external CLI.
+ */
+exports.DETECTOR_VERSION_PROBES = {
+    claude: { kind: 'execFile', command: 'claude', args: ['--version'] },
+    codex: { kind: 'execFile', command: 'codex', args: ['--version'] },
+    antigravity: { kind: 'execFile', command: 'agy', args: ['--version'] },
+    opencode: { kind: 'execFile', command: 'opencode', args: ['--version'] },
+    gemini: { kind: 'execFile', command: 'gemini', args: ['--version'] },
+    copilot: {
+        kind: 'delegated',
+        probe: async () => (await (0, copilot_executable_1.resolveCopilotExecutable)())?.version ?? null,
+    },
+};
+let freshnessCache = null;
+let freshnessInFlight = null;
+/**
+ * Run one probe. Resolves null on any failure, and **without spawning anything**
+ * when the command does not resolve to an absolute path (DR4-010 (2)).
+ */
+function runDetectorVersionProbe(probe) {
+    if (probe.kind === 'delegated') {
+        return probe.probe().catch(() => null);
+    }
+    const executable = (0, copilot_executable_1.findExecutableOnPath)(probe.command);
+    // Skip, do not fall back to the bare name: handing an unresolved command to
+    // execFile is exactly the PATH-decides-the-binary case DR4-010 removes.
+    if (!executable)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        (0, child_process_1.execFile)(executable, [...probe.args], {
+            timeout: exports.DETECTOR_VERSION_PROBE_TIMEOUT_MS,
+            maxBuffer: DETECTOR_VERSION_PROBE_MAX_BUFFER_BYTES,
+            env: (0, env_sanitizer_1.sanitizeEnvForChildProcess)(),
+        }, (error, stdout, stderr) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            resolve(parseCliVersion(`${stdout ?? ''}\n${stderr ?? ''}`));
+        });
+    });
+}
+async function computeDetectorFreshness() {
+    const tools = Object.keys(exports.DETECTOR_VERSION_PROBES).sort();
+    return Promise.all(tools.map(async (tool) => {
+        const verifiedAgainst = verified_against_1.DETECTOR_VERIFIED_AGAINST[tool]?.version ?? 'unmeasured';
+        const installed = await runDetectorVersionProbe(exports.DETECTOR_VERSION_PROBES[tool]);
+        const baseline = parseVerifiedAgainstVersion(verifiedAgainst);
+        return {
+            tool,
+            installed,
+            verifiedAgainst,
+            stale: installed !== null && baseline !== null && compareCliVersions(installed, baseline) > 0,
+        };
+    }));
+}
+/**
+ * The full freshness report, computed once per process and cached. Concurrent
+ * first callers share one probe.
+ *
+ * **This awaits child processes — never call it from a request path.** Use
+ * {@link getDetectorStalenessSnapshot} there. Kept for `commandmate status`,
+ * `npm run check:detector-freshness` and tests, and as the single implementation
+ * both entry points share.
+ */
+async function getDetectorFreshness() {
+    if (freshnessCache !== null)
+        return freshnessCache;
+    if (freshnessInFlight)
+        return freshnessInFlight;
+    freshnessInFlight = computeDetectorFreshness();
+    try {
+        freshnessCache = await freshnessInFlight;
+        return freshnessCache;
+    }
+    finally {
+        freshnessInFlight = null;
+    }
+}
+/** Reduce a report to the wire shape: stale tools only. */
+function toDetectorStaleness(rows) {
+    const staleness = {};
+    for (const row of rows) {
+        if (!row.stale || row.installed === null)
+            continue;
+        staleness[row.tool] = { installed: row.installed, verifiedAgainst: row.verifiedAgainst };
+    }
+    return staleness;
+}
+/**
+ * The staleness this process already knows, or `undefined` plus a background
+ * probe when it knows nothing yet. **Never awaits a child process** (§4 D2,
+ * DR3-013 (a)(b)(c)).
+ *
+ * `undefined` is "not known yet", not "nothing is stale" — see the module doc.
+ * The returned object is `{}` once the cache is warm and nothing is stale, which
+ * is how a caller tells the two apart.
+ */
+function getDetectorStalenessSnapshot() {
+    if (freshnessCache !== null)
+        return toDetectorStaleness(freshnessCache);
+    // Fire and forget. No in-flight check here on purpose: getDetectorFreshness
+    // owns that slot and hands a concurrent caller the promise that is already
+    // running, so a second guard would be a copy of an invariant that lives one
+    // function down — and a copy is what goes stale. It swallows its own failures,
+    // so nothing here needs the result.
+    void getDetectorFreshness().catch(() => []);
+    return undefined;
+}
+/** Clear the process-level probe cache (tests, and any future cache-control wiring). */
+function clearDetectorVersionProbeCache() {
+    freshnessCache = null;
+    freshnessInFlight = null;
+}

package/dist/server/src/lib/env.js

@@ -8,6 +8,9 @@
  *
  * Issue #135: DB path resolution fix
  * Uses getDefaultDbPath() from db-path-resolver.ts for consistent DB path handling
+ *
+ * Issue #2132: startup self-check for ".env exists but nothing was loaded"
+ * See {@link runDotenvSelfCheck}.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -17,12 +20,17 @@ exports.ENV_MAPPING = void 0;
 exports.resetWarnedKeys = resetWarnedKeys;
 exports.getEnvWithFallback = getEnvWithFallback;
 exports.getEnvByKey = getEnvByKey;
+exports.parseDotenvKeys = parseDotenvKeys;
+exports.inspectDotenvLoad = inspectDotenvLoad;
+exports.formatDotenvReportLines = formatDotenvReportLines;
+exports.runDotenvSelfCheck = runDotenvSelfCheck;
 exports.resetDatabasePathWarning = resetDatabasePathWarning;
 exports.getDatabasePathWithDeprecationWarning = getDatabasePathWithDeprecationWarning;
 exports.getLogConfig = getLogConfig;
 exports.getServerPort = getServerPort;
 exports.getEnv = getEnv;
 exports.validateEnv = validateEnv;
+const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const db_path_resolver_1 = require("./db/db-path-resolver");
 // ============================================================
@@ -84,6 +92,120 @@ function getEnvWithFallback(newKey, oldKey) {
 function getEnvByKey(key) {
     return getEnvWithFallback(key, exports.ENV_MAPPING[key]);
 }
+/** `KEY`, `export KEY`, ` KEY ` — the assignment forms a `.env` line can take. */
+const DOTENV_ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/**
+ * The variable names a `.env` file declares, in file order, without duplicates.
+ *
+ * Values are never returned. `CM_VAPID_PRIVATE_KEY` lives in this file, and the
+ * only reason to parse it here is to count how many of its NAMES arrived.
+ */
+function parseDotenvKeys(contents) {
+    const keys = [];
+    const seen = new Set();
+    for (const line of contents.split(/\r?\n/)) {
+        const match = DOTENV_ASSIGNMENT.exec(line);
+        if (!match)
+            continue;
+        const key = match[1];
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        keys.push(key);
+    }
+    return keys;
+}
+/**
+ * Compare the `.env` on disk against the environment this process actually got.
+ *
+ * @returns `null` when there is nothing to compare — no `.env`, an unreadable
+ *   one, or one that declares no variables. None of those is a fault worth a
+ *   line of startup output.
+ */
+function inspectDotenvLoad(options = {}) {
+    const { cwd = process.cwd(), env = process.env } = options;
+    const envPath = path_1.default.join(cwd, '.env');
+    let contents;
+    try {
+        if (!fs_1.default.existsSync(envPath))
+            return null;
+        contents = fs_1.default.readFileSync(envPath, 'utf8');
+    }
+    catch {
+        // Unreadable is a permissions question, not a loading question.
+        return null;
+    }
+    const declaredKeys = parseDotenvKeys(contents);
+    if (declaredKeys.length === 0)
+        return null;
+    const presentKeys = declaredKeys.filter((key) => env[key] !== undefined);
+    return {
+        envPath,
+        declaredKeys,
+        presentKeys,
+        loadFailed: presentKeys.length === 0,
+    };
+}
+/** How many key names the report is willing to print before it says "and N more". */
+const DOTENV_REPORT_KEY_LIMIT = 8;
+/**
+ * The lines {@link runDotenvSelfCheck} prints — empty when the load worked.
+ *
+ * Exported so the wording is pinned by a test rather than by a screenshot.
+ */
+function formatDotenvReportLines(inspection) {
+    if (!inspection.loadFailed)
+        return [];
+    const shown = inspection.declaredKeys.slice(0, DOTENV_REPORT_KEY_LIMIT);
+    const omitted = inspection.declaredKeys.length - shown.length;
+    const names = omitted > 0 ? `${shown.join(', ')}, and ${omitted} more` : shown.join(', ');
+    return [
+        `[env] ${inspection.envPath} declares ${inspection.declaredKeys.length} variable(s) `
+            + 'and NOT ONE of them is set in this process: '
+            + `${names}.`,
+        '[env] The server is running on defaults. Web Push, the database path and the '
+            + 'worktree root are all configured through those variables, so this is very '
+            + 'unlikely to be what you wanted.',
+        '[env] Most likely cause (Issue #2132): the server was started by hand after '
+            + '`source scripts/load-env.sh` from a shell that is not bash. That script now '
+            + 'refuses instead of exporting nothing, so re-run it and read what it says.',
+        '[env] Supported restart, no rebuild: ./scripts/restart-nobuild.sh  '
+            + '(or ./scripts/start.sh --daemon)',
+    ];
+}
+/**
+ * Report, in one place at startup, that `.env` exists and none of it arrived.
+ *
+ * Same contract as `runVapidSelfCheck` in `lib/push/vapid.ts`, deliberately:
+ * fail-open, never throws, never blocks `listen`, and a healthy install prints
+ * NOTHING — which is what makes the presence of a line meaningful.
+ *
+ * It exists because the failure it names is invisible from inside the process.
+ * Every consumer of these variables has a defensible default, so a server that
+ * received none of them starts, listens, and answers requests; what it does not
+ * do is send a single push notification, and it may open a different database
+ * than the one the operator believes they are looking at. During the Epic #2002
+ * device UAT the only signal was the VAPID warning, and reading it as "push is
+ * broken" rather than "the environment is empty" cost two UAT rounds.
+ *
+ * @returns The inspection, or `null` when there was nothing to check.
+ */
+function runDotenvSelfCheck(options = {}) {
+    const { warn = (message) => console.warn(message) } = options;
+    try {
+        const inspection = inspectDotenvLoad(options);
+        if (!inspection)
+            return null;
+        for (const line of formatDotenvReportLines(inspection)) {
+            warn(line);
+        }
+        return inspection;
+    }
+    catch {
+        // A diagnostic must never be the reason a server fails to start.
+        return null;
+    }
+}
 // ============================================================
 // [Issue #135] DATABASE_PATH Deprecation Support
 // ============================================================