peaks-loop 4.0.12 → 4.0.14

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 4.0.14 — 2026-08-06 (outer-session cache + ensureSession meta over-coverage)
+
+**Fixes the "5 terminals / 5 sessions stuck on 3fe1be" bug** (slice `2026-08-06-session-outer-cache-and-meta-coverage`, commit `f02a9b45`):
+- `src/services/session/session-binding-bridge.ts` `getCurrentOuterSessionId(projectRoot)` now resolves `PEAKS_OUTER_SESSION_ID` → `CLAUDE_CODE_SESSION_ID` → file-cache at `.peaks/_runtime/.outer-session-cache.json` → `undefined`. Any IO error or non-string `outerSessionId` is a cache-miss (no throw). The cache file lives under the existing `.peaks/_runtime/` gitignore parent rule — no `.gitignore` modification.
+- Same file: `ensureSession` early-return path now calls `setSessionMeta(projectRoot, existing.sessionId, { outerSessionId })` BEFORE returning. The on-disk `.peaks/_runtime/<sid>/session.json` always reflects the latest outerSessionId (not a stale value captured at first-bind time). All other meta fields (title / skill / mode / gate / createdAt) preserved via read-modify-write; `lastActivity` bumped to `now`.
+- `src/services/skills/hooks-settings-service.ts` `resolveHookEntries('claude-code')` now appends a SessionStart entry that runs `peaks outer-cache write --project ...` to keep the cache in sync with the active Claude Code session. Uninstall strips the entry alongside the gate-enforce entry. Multi-binary drift guard (slice 2026-08-05) still fires correctly because the SessionStart entry uses the same `peaks` binary.
+- New CLI: `peaks outer-cache write` (no flags) + `peaks outer-cache read` (returns `{ missing: true }` envelope on absent / malformed / IO error). Write exits 1 with `OUTER_CACHE_NO_ENV` when neither `PEAKS_OUTER_SESSION_ID` nor `CLAUDE_CODE_SESSION_ID` is set.
+- Tests: `tests/unit/session/get-current-outer-session-id.test.ts` (10 cases pinning env > cache > undefined ordering, cache-miss / malformed JSON / IO error tolerance) + `tests/unit/session/ensure-session-meta-coverage.test.ts` (7 cases pinning AC8-AC11 over-coverage). Regression sweep: 179/179 PASS / 1 SKIP (pre-existing Win-only conditional).
+- A.3 / A.4 / A.5 (workflowId by callerId + `session.json` migration + cross-outer rotation cases) explicitly reserved for a future session per PRD NG1-NG4.
+
+**Lockstep bump.** peaks-loop-shared `0.0.43 → 0.0.44` (CLI_VERSION re-stamped to 4.0.14); peaks-loop-mut `0.1.16 → 0.1.17`; peaks-loop-shared-channel `0.0.20 → 0.0.21`.
+
+## 4.0.13 — 2026-08-06 (statusline empty-render fix + sid-only marker + multi-binary drift guard)
+
+**Statusline callerId fallback + active `[short-sid]` suffix** (slice `2026-08-05-statusline-empty-render-and-short-sid-suffix`, commit `4be37d08`):
+- `src/services/skills/skill-statusline-service.ts` `readPresenceReadOnly` now retries with `callerId: null` when callerId-filtered resolution returns `source: 'none'`. Multi-tenant isolation invariant preserved (slice 4-B Case A regression test stays green).
+- `src/services/skills/skill-statusline-renderer.ts` introduces `formatShortSid(sessionId) = sessionId.split('-').pop()` helper. Active state now renders `Peaks ● peaks-code → peaks-loop [3fe1be]`.
+- New tests: `tests/unit/skills/skill-statusline-empty-render-and-short-sid-suffix.test.ts` (8 cases). Existing dual-skill test updated to accept the `[aaaa]` suffix.
+- Fixes the "new session statusline empty despite active peaks-code lease" bug (root cause: outerSessionId drift between caller shell and lease's callerId).
+
+**Statusline sid-only marker (idle/stale) + multi-binary drift guard** (slice `2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard`, commits `95654d48` + `34de6c22` repair):
+- `skill-statusline-service.ts` adds `sessionId: string | null` to `StatusLineModel`. `skill-statusline-sid-suffix.ts` (new, 78 LOC) holds `computeRootSuffix` + `formatShortSid` (extracted from renderer for LOC cap; renderer 806 → 776).
+- Idle and stale states now append ` [3fe1be]` after `peaks-loop` when session.json is bound. Invalid-presence stays unchanged (G2 — read-error signal must remain loud).
+- New `peaks doctor check` plugin `build:multi-binary-drift` scans `process.env.PATH` for `peaks` binaries (cross-platform: `peaks` / `peaks.cmd` / `peaks.ps1`), resolves each to its `node_modules/peaks-loop/package.json`, dedupes by realpath, and emits `PEAKS_MULTI_BINARY_DRIFT` warning when ≥ 2 distinct versions coexist. Caught the `/c/nvm4w/nodejs 4.0.12 + /c/Users/smallMark/AppData/Roaming/npm 3.1.2` case that produced "Hook JSON output validation failed" on fresh IDE sessions.
+- **Severity-aware `buildReport`** (the canonical reference for warn-only doctor checks): `DoctorCheck` now carries `severity: 'error' | 'warning'`. `buildReport` separates errors from warnings; `summary.ok = errors === 0`. Multi-binary drift emits `severity: 'warning'`. CLI exit code only flips on errors.
+- Tests: `tests/unit/skills/skill-statusline-sid-only-marker.test.ts` (8 cases) + `tests/unit/doctor/multi-binary-drift-check.test.ts` (13 cases) + `tests/unit/doctor/final-summary-severity.test.ts` (7 cases) + `tests/unit/doctor/doctor-exit-code-warn-only.test.ts` (5 cases). 170/170 green on slice surface.
+
+**Lockstep bump.** peaks-loop-shared `0.0.42 → 0.0.43` (CLI_VERSION re-stamped to 4.0.13); peaks-loop-mut `0.1.15 → 0.1.16`; peaks-loop-shared-channel `0.0.19 → 0.0.20`.
+
 ## 4.0.12 — 2026-08-05 (5-slice optimization bundle)
 
 **publish.yml strict tag gate** (slice 1, commit `f60f7597`):

package/dist/cli/commands/_register.js

@@ -36,6 +36,7 @@ import { registerWorkflowEvalCommands } from './loop-eval-commands.js';
 import { registerMutCommands } from './mut-commands.js';
 import { registerObservabilityCommands } from './observability-commands.js';
 import { registerOpenSpecCommands } from './openspec-commands.js';
+import { registerOuterCacheCommands } from './outer-cache-commands.js';
 import { registerPerfAuditCommands } from './perf-audit-commands.js';
 import { registerPerfCommands } from './perf-commands.js';
 import { registerPlaywrightCommands } from './playwright-commands.js';
@@ -127,6 +128,7 @@ const REGISTRATIONS = [
     ['adapter-commands-s2a', registerAdapterS2ACommands], ['polyrepo-commands', registerPolyrepoCommands],
     ['worktree-auth-commands', registerWorktreeAuthCommand],
     ['session-spill-demo', registerSpillDemoCommand],
+    ['outer-cache-commands', registerOuterCacheCommands],
 ];
 function dispatchRegister(register, program, io) {
     if (register.length <= 1) {

package/dist/cli/commands/core/doctor-command.js

@@ -212,6 +212,10 @@ export function registerDoctorCommand(program, io) {
         const data = logsSection === null
             ? { ...report, staleBinding: staleBindingSection }
             : { ...report, logs: logsSection, staleBinding: staleBindingSection };
+        // Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+        // repair cycle: `report.summary.ok` already factors in the
+        // severity-aware aggregation in `buildReport` (warnings do NOT
+        // flip `ok`). Stale-binding is independent and still escalates.
         const result = report.summary.ok && staleInstances.length === 0
             ? ok('doctor', data)
             : fail('doctor', 'DOCTOR_FAILED', staleInstances.length > 0
@@ -224,9 +228,20 @@ export function registerDoctorCommand(program, io) {
         }
         else {
             // Human-readable: one line per check, green/red indicators, no JSON.
+            // Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+            // repair cycle: warn-only findings (severity: 'warning') surface
+            // as `! check.ok` with the `! ` (warning) glyph so the operator
+            // can tell them apart from real errors without reading JSON.
             for (const check of report.checks) {
-                const icon = check.ok ? '+' : '×';
-                io.stdout(`  ${icon}  ${check.message}`);
+                if (check.ok) {
+                    io.stdout(`  +  ${check.message}`);
+                }
+                else if (check.severity === 'warning') {
+                    io.stdout(`  !  ${check.message}`);
+                }
+                else {
+                    io.stdout(`  ×  ${check.message}`);
+                }
             }
             if (logsSection !== null) {
                 io.stdout('\n  logs:');
@@ -252,11 +267,19 @@ export function registerDoctorCommand(program, io) {
                     io.stdout('    rerun with --cleanup-stale to drop them');
                 }
             }
-            io.stdout(`\n  ${report.summary.passed} passed, ${report.summary.failed} failed`);
+            io.stdout(`\n  ${report.summary.passed} passed, ${report.summary.failed} failed${report.summary.warnings > 0 ? `, ${report.summary.warnings} warning(s)` : ''}`);
             if (!report.summary.ok || staleInstances.length > 0) {
                 io.stderr(`\nDOCTOR_FAILED: ${staleInstances.length > 0 ? 'stale binding present' : `${report.summary.failed} check(s) failed`}.`);
             }
+            else if (report.summary.warnings > 0) {
+                io.stdout(`\n  ${report.summary.warnings} warning(s) present — exit code 0 (warn-only).`);
+            }
         }
+        // Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+        // repair cycle: `report.summary.ok` already factors in the
+        // severity-aware aggregation in `buildReport` (warnings do NOT
+        // flip `ok`). The exit-code gate remains `summary.ok &&
+        // !staleInstances` — no separate warning special-case needed here.
         if (!report.summary.ok || staleInstances.length > 0) {
             process.exitCode = 1;
         }

package/dist/cli/commands/outer-cache-commands.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type OuterCacheWriteOptions = {
+    readonly project?: string;
+    readonly json?: boolean;
+};
+export type OuterCacheReadOptions = {
+    readonly project?: string;
+    readonly json?: boolean;
+};
+export declare function registerOuterCacheCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/outer-cache-commands.js

@@ -0,0 +1,120 @@
+/**
+ * Slice 2026-08-06-session-outer-cache (G1 / G2) — per-project outer-session
+ * cache CLI surface.
+ *
+ * Writes and reads `.peaks/_runtime/.outer-session-cache.json` so that
+ * peaks CLI sub-processes (which typically do NOT inherit
+ * `CLAUDE_CODE_SESSION_ID` from the parent shell) can resolve the
+ * current outer session id via `getCurrentOuterSessionId(projectRoot)`
+ * in `src/services/session/session-binding-bridge.ts`.
+ *
+ * The SessionStart hook wired by `peaks hooks install` invokes
+ * `peaks outer-cache write` to keep this file in sync with the active
+ * Claude Code / Trae / IDE session. The file is under `.peaks/_runtime/`
+ * (gitignored), so no `.gitignore` change is required.
+ *
+ * Subcommand surface:
+ *   - `peaks outer-cache write` (no flags) — read PEAKS_OUTER_SESSION_ID
+ *     ?? CLAUDE_CODE_SESSION_ID, write the cache file, return JSON
+ *     envelope with `{ outerSessionId, capturedAt, cachePath, written }`.
+ *   - `peaks outer-cache read` — return
+ *     `{ outerSessionId, capturedAt, cachePath }` when present or
+ *     `{ missing: true, cachePath }` when not. Never throws on
+ *     malformed JSON / IO error.
+ *
+ * Both subcommands accept `--project <path>` (defaults to cwd / git
+ * root) and `--json` (default in TTY-less invocations).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+const OUTER_SESSION_CACHE_REL = join('.peaks', '_runtime', '.outer-session-cache.json');
+function resolveCachePath(projectRoot) {
+    return join(projectRoot, OUTER_SESSION_CACHE_REL);
+}
+function readEnvOuter() {
+    const peaks = process.env.PEAKS_OUTER_SESSION_ID;
+    if (typeof peaks === 'string' && peaks.length > 0)
+        return peaks;
+    const claude = process.env.CLAUDE_CODE_SESSION_ID;
+    if (typeof claude === 'string' && claude.length > 0)
+        return claude;
+    return undefined;
+}
+function readCacheFile(cachePath) {
+    if (!existsSync(cachePath))
+        return { ok: false, missing: true };
+    try {
+        const raw = readFileSync(cachePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            typeof parsed.outerSessionId === 'string' &&
+            (parsed.outerSessionId).length > 0 &&
+            typeof parsed.capturedAt === 'string') {
+            return {
+                ok: true,
+                outerSessionId: parsed.outerSessionId,
+                capturedAt: parsed.capturedAt
+            };
+        }
+        return { ok: false, missing: true };
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return { ok: false, missing: true };
+    }
+}
+export function registerOuterCacheCommands(program, io) {
+    const outerCache = program
+        .command('outer-cache')
+        .description('Read / write the per-project outer-session cache file (.peaks/_runtime/.outer-session-cache.json). The SessionStart hook installed by `peaks hooks install` keeps this file in sync with the live Claude Code / Trae / IDE session so peaks CLI sub-processes (which typically do NOT inherit CLAUDE_CODE_SESSION_ID) can resolve the current outer session via getCurrentOuterSessionId(projectRoot).');
+    addJsonOption(outerCache
+        .command('write')
+        .description('Write the current outer-session-id (PEAKS_OUTER_SESSION_ID ?? CLAUDE_CODE_SESSION_ID) into the per-project cache file. Idempotent: re-runs overwrite. Exits 1 with OUTER_CACHE_NO_ENV when neither env var is set.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
+        const projectRoot = options.project ?? (findProjectRoot(process.cwd()) ?? process.cwd());
+        const cachePath = resolveCachePath(projectRoot);
+        const outerSessionId = readEnvOuter();
+        if (outerSessionId === undefined) {
+            printResult(io, fail('outer-cache.write', 'OUTER_CACHE_NO_ENV', 'Neither PEAKS_OUTER_SESSION_ID nor CLAUDE_CODE_SESSION_ID is set; nothing to write', { cachePath, written: false, projectRoot }, [
+                'Set PEAKS_OUTER_SESSION_ID=<id> or run from inside Claude Code / Trae / IDE so CLAUDE_CODE_SESSION_ID is exported',
+                'Re-run `peaks hooks install` to wire the SessionStart hook that writes this cache automatically'
+            ]), options.json === true);
+            process.exitCode = 1;
+            return;
+        }
+        const capturedAt = new Date().toISOString();
+        const payload = { outerSessionId, capturedAt };
+        try {
+            const dir = dirname(cachePath);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            writeFileSync(cachePath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            printResult(io, fail('outer-cache.write', 'OUTER_CACHE_WRITE_FAILED', `Failed to write outer-session cache: ${message}`, { cachePath, written: false, projectRoot, outerSessionId, capturedAt }, [message]), options.json === true);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('outer-cache.write', { cachePath, written: true, projectRoot, outerSessionId, capturedAt }, [], [`Wrote ${cachePath}; getCurrentOuterSessionId() will resolve to "${outerSessionId}" until the next SessionStart fires.`]), options.json === true);
+    });
+    addJsonOption(outerCache
+        .command('read')
+        .description('Read the current value of the per-project outer-session cache. Returns { missing: true, cachePath } when the file is absent / malformed / empty; never throws on IO error.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
+        const projectRoot = options.project ?? (findProjectRoot(process.cwd()) ?? process.cwd());
+        const cachePath = resolveCachePath(projectRoot);
+        const result = readCacheFile(cachePath);
+        if (result.ok) {
+            printResult(io, ok('outer-cache.read', { cachePath, missing: false, projectRoot, outerSessionId: result.outerSessionId, capturedAt: result.capturedAt }, [], [`outer-session-id resolved: ${result.outerSessionId} (captured ${result.capturedAt})`]), options.json === true);
+            return;
+        }
+        printResult(io, ok('outer-cache.read', { cachePath, missing: true, projectRoot }, ['No outer-session cache present — getCurrentOuterSessionId() will return undefined for this project.'], [
+            'Re-run `peaks hooks install` to wire the SessionStart hook that writes this cache automatically',
+            'Or set PEAKS_OUTER_SESSION_ID=<id> so env-first resolution wins without touching the cache'
+        ]), options.json === true);
+    });
+}

package/dist/services/doctor/doctor-service/checks/multi-binary-drift.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Check: PATH-scoped `peaks-loop` binary drift
+ * (`build:multi-binary-drift`).
+ *
+ * Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+ * (G3/G4). When more than one `peaks-loop` binary is discoverable on
+ * `process.env.PATH` AND the discovered versions disagree, the doctor
+ * emits a `PEAKS_MULTI_BINARY_DRIFT` warning. The user-reported
+ * production symptom — `peaks` resolving to an old version (e.g.
+ * 3.1.2 on `%AppData%\Roaming\npm`) while the freshly installed
+ * binary on another PATH entry (e.g. `C:\nvm4w\nodejs\peaks` 4.0.12)
+ * is what the user just bumped — produces "Hook JSON output
+ * validation failed" when the IDE statusline hook inherits the older
+ * binary via PATH ordering.
+ *
+ * Behavior contract (PRD AC6 / AC7 / AC8 / AC9):
+ *   - AC6: ≥ 2 peaks-loop binaries with different versions → warning
+ *   - AC7: warning severity only, doctor exit 0 (no other check
+ *          flipped to error)
+ *   - AC8: drift is scoped to peaks-loop (`package.json#name ===
+ *          'peaks-loop'`); sibling npm tools are NOT flagged
+ *   - AC9: cross-platform — uses `process.env.PATH` + `path.delimiter`
+ *          + binary naming `peaks` / `peaks.cmd` / `peaks.ps1`
+ *
+ * Pure `inspectMultiBinaryDrift` helper is exported so tests can drive
+ * the filesystem walk without monkey-patching `process.env.PATH` or
+ * `realpathSync`. Every probe call is wrapped in try/catch (read-only,
+ * must not throw across the doctor boundary).
+ */
+import type { DoctorCheckPlugin, MultiBinaryDriftInspection } from '../types.js';
+/**
+ * Local record shape — same as the canonical
+ * `MultiBinaryDriftInspection.binaries[number]`. Re-declared so the
+ * helper signature carries the concrete shape (the canonical
+ * `MultiBinaryDriftInspection` widens `version` + `installDate` to
+ * `string | null` so external consumers do not depend on the
+ * field being nullable).
+ */
+export type PeaksBinaryRecord = {
+    readonly path: string;
+    readonly version: string | null;
+    readonly installDate: string | null;
+    readonly realpath: string;
+};
+/**
+ * Pure helper. Inspects `process.env.PATH` (or the injected
+ * `pathEnv`) for `peaks-loop` binaries. Each found binary is walked
+ * to its package.json via `realpathSync` so symlinks / npm shims /
+ * `peaks.cmd` / `peaks.ps1` all collapse to the same dedupe key.
+ *
+ * Exported so tests can drive the filesystem walk without monkey-
+ * patching `process.env.PATH` or `realpathSync`.
+ */
+export declare function inspectMultiBinaryDrift(opts?: {
+    pathEnv?: string;
+    envReader?: (key: string) => string | undefined;
+    binaryExists?: (candidate: string) => boolean;
+    binaryRealpath?: (candidate: string) => string;
+    packageJsonReader?: (path: string) => Buffer | string | null;
+}): MultiBinaryDriftInspection;
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/multi-binary-drift.js

@@ -0,0 +1,268 @@
+/**
+ * Check: PATH-scoped `peaks-loop` binary drift
+ * (`build:multi-binary-drift`).
+ *
+ * Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+ * (G3/G4). When more than one `peaks-loop` binary is discoverable on
+ * `process.env.PATH` AND the discovered versions disagree, the doctor
+ * emits a `PEAKS_MULTI_BINARY_DRIFT` warning. The user-reported
+ * production symptom — `peaks` resolving to an old version (e.g.
+ * 3.1.2 on `%AppData%\Roaming\npm`) while the freshly installed
+ * binary on another PATH entry (e.g. `C:\nvm4w\nodejs\peaks` 4.0.12)
+ * is what the user just bumped — produces "Hook JSON output
+ * validation failed" when the IDE statusline hook inherits the older
+ * binary via PATH ordering.
+ *
+ * Behavior contract (PRD AC6 / AC7 / AC8 / AC9):
+ *   - AC6: ≥ 2 peaks-loop binaries with different versions → warning
+ *   - AC7: warning severity only, doctor exit 0 (no other check
+ *          flipped to error)
+ *   - AC8: drift is scoped to peaks-loop (`package.json#name ===
+ *          'peaks-loop'`); sibling npm tools are NOT flagged
+ *   - AC9: cross-platform — uses `process.env.PATH` + `path.delimiter`
+ *          + binary naming `peaks` / `peaks.cmd` / `peaks.ps1`
+ *
+ * Pure `inspectMultiBinaryDrift` helper is exported so tests can drive
+ * the filesystem walk without monkey-patching `process.env.PATH` or
+ * `realpathSync`. Every probe call is wrapped in try/catch (read-only,
+ * must not throw across the doctor boundary).
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { delimiter as pathDelimiter, join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+/**
+ * Pure helper. Inspects `process.env.PATH` (or the injected
+ * `pathEnv`) for `peaks-loop` binaries. Each found binary is walked
+ * to its package.json via `realpathSync` so symlinks / npm shims /
+ * `peaks.cmd` / `peaks.ps1` all collapse to the same dedupe key.
+ *
+ * Exported so tests can drive the filesystem walk without monkey-
+ * patching `process.env.PATH` or `realpathSync`.
+ */
+export function inspectMultiBinaryDrift(opts) {
+    const envReader = opts?.envReader ?? ((k) => process.env[k]);
+    const exists = opts?.binaryExists ?? ((p) => {
+        try {
+            return existsSync(p);
+        }
+        catch {
+            return false;
+        }
+    });
+    const realpath = opts?.binaryRealpath ?? ((p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    });
+    const reader = opts?.packageJsonReader ?? ((p) => {
+        try {
+            return readFileSync(p);
+        }
+        catch {
+            return null;
+        }
+    });
+    const pathEnv = opts?.pathEnv ?? envReader('PATH') ?? '';
+    if (pathEnv.length === 0) {
+        return { binaries: [], driftDetected: false, uniqueVersions: [] };
+    }
+    const dirs = pathEnv.split(pathDelimiter).filter((d) => d.length > 0);
+    const seen = new Map();
+    for (const dir of dirs) {
+        const candidates = candidateBinaryNames(dir);
+        for (const candidate of candidates) {
+            if (!exists(candidate))
+                continue;
+            const rp = realpath(candidate);
+            if (seen.has(rp))
+                continue;
+            const pkgPath = locatePackageJson(rp, candidate);
+            const record = readBinaryRecord(candidate, rp, pkgPath, reader);
+            seen.set(rp, record);
+        }
+    }
+    const binaries = Array.from(seen.values());
+    const uniqueVersions = dedupeVersions(binaries.map((b) => b.version));
+    return {
+        binaries,
+        driftDetected: uniqueVersions.length >= 2,
+        uniqueVersions
+    };
+}
+/**
+ * Cross-platform candidate names. Windows shims the executable as
+ * `peaks.cmd` and `peaks.ps1` (npm writes both); POSIX names the
+ * binary `peaks`. We probe all three names on every platform —
+ * probing a non-existent file is a no-op, so cross-list probing is
+ * safe.
+ */
+function candidateBinaryNames(dir) {
+    return [join(dir, 'peaks'), join(dir, 'peaks.cmd'), join(dir, 'peaks.ps1')];
+}
+/**
+ * Walk from the binary to its `node_modules/peaks-loop/package.json`.
+ *
+ * Common layouts handled:
+ *
+ *   A. `<root>/bin/peaks` (POSIX npm global / nvm) → parent is
+ *      `<root>/bin/`, parent's parent is `<root>/`. package.json at
+ *      `<root>/package.json`.
+ *   B. `<root>/peaks` or `<root>/peaks.cmd` (Windows npm global shim)
+ *      → parent is `<root>/`. package.json at `<root>/package.json`,
+ *      OR `<root>/../node_modules/peaks-loop/package.json`.
+ *   C. `<root>/node_modules/.bin/peaks` (local install) → parent is
+ *      `node_modules/.bin/`, parent's parent is `node_modules/`.
+ *      package.json at `<root>/node_modules/peaks-loop/package.json`.
+ *
+ * The locator walks up from the binary path (realpathPath first,
+ * then originalCandidate) and checks for the canonical
+ * `node_modules/peaks-loop/package.json` and a `package.json` at each
+ * ancestor. The probe is read-only and stops at the first hit. We do
+ * NOT trust `package.json` without verifying its `name === 'peaks-loop'`
+ * later (see {@link readBinaryRecord}) — a sibling package's
+ * `package.json` is filtered out at read time.
+ */
+function locatePackageJson(realpathPath, originalCandidate) {
+    const ancestors = new Set();
+    for (const start of [realpathPath, originalCandidate]) {
+        let current = start;
+        for (let depth = 0; depth < 8; depth++) {
+            const parent = join(current, '..');
+            if (parent === current)
+                break;
+            ancestors.add(parent);
+            current = parent;
+        }
+    }
+    for (const ancestor of ancestors) {
+        const nmPkg = join(ancestor, 'node_modules', 'peaks-loop', 'package.json');
+        if (existsSafe(nmPkg))
+            return nmPkg;
+    }
+    for (const ancestor of ancestors) {
+        const pkg = join(ancestor, 'package.json');
+        if (existsSafe(pkg))
+            return pkg;
+    }
+    return null;
+}
+function existsSafe(p) {
+    try {
+        return existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+function readBinaryRecord(candidate, realpathPath, pkgPath, reader) {
+    if (pkgPath === null) {
+        return {
+            path: candidate,
+            version: null,
+            installDate: null,
+            realpath: realpathPath
+        };
+    }
+    let version = null;
+    try {
+        const raw = reader(pkgPath);
+        if (raw !== null) {
+            const text = Buffer.isBuffer(raw) ? raw.toString('utf8') : raw;
+            const parsed = JSON.parse(text);
+            if (parsed.name === 'peaks-loop' && typeof parsed.version === 'string') {
+                version = parsed.version;
+            }
+        }
+    }
+    catch {
+        version = null;
+    }
+    let installDate = null;
+    try {
+        const stat = statSync(pkgPath);
+        installDate = stat.mtime.toISOString();
+    }
+    catch {
+        installDate = null;
+    }
+    return {
+        path: candidate,
+        version,
+        installDate,
+        realpath: realpathPath
+    };
+}
+/**
+ * `version === null` means we could not read the package.json (or
+ * its `name` did not equal `peaks-loop`). Those records stay in
+ * `binaries` for the report but do NOT contribute to
+ * `uniqueVersions` — including null would falsely trigger drift
+ * detection when the only failures are unreadable binaries.
+ */
+function dedupeVersions(versions) {
+    const seen = new Set();
+    const out = [];
+    for (const v of versions) {
+        if (typeof v !== 'string' || v.length === 0)
+            continue;
+        if (seen.has(v))
+            continue;
+        seen.add(v);
+        out.push(v);
+    }
+    return out;
+}
+function run({ options }) {
+    const probe = options.multiBinaryDriftProbe ?? (() => inspectMultiBinaryDrift());
+    try {
+        const result = probe();
+        if (result.binaries.length === 0) {
+            return [{
+                    id: 'build:multi-binary-drift',
+                    ok: true,
+                    message: 'no peaks-loop binary on PATH (statusLine may be unavailable)'
+                }];
+        }
+        if (!result.driftDetected) {
+            return [{
+                    id: 'build:multi-binary-drift',
+                    ok: true,
+                    message: result.binaries.length === 1
+                        ? `single peaks-loop binary on PATH at ${result.binaries[0].path} (version ${result.uniqueVersions[0] ?? 'unknown'})`
+                        : `${result.binaries.length} peaks-loop binaries on PATH all at version ${result.uniqueVersions[0] ?? 'unknown'}`
+                }];
+        }
+        // Drift detected — WARN-ONLY. AC7: doctor still exit 0 unless
+        // another check escalates to error. `ok: false` so the operator
+        // sees the finding in the JSON report AND the check carries
+        // `severity: 'warning'` so `buildReport` does NOT count it as a
+        // failure when computing `summary.ok`. Slice
+        // 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+        // repair cycle landed the severity-aware summary so the
+        // previously-handwaved "future severity-aware summary can
+        // downgrade the doctor exit code" actually fires.
+        const binaryTable = result.binaries
+            .map((b) => `  ${b.path} version=${b.version ?? 'unknown'} date=${b.installDate ?? 'unknown'}`)
+            .join('\n');
+        return [{
+                id: 'build:multi-binary-drift',
+                ok: false,
+                severity: 'warning',
+                message: `PEAKS_MULTI_BINARY_DRIFT: ${result.uniqueVersions.length} distinct peaks-loop versions on PATH (${result.uniqueVersions.join(', ')}). Run \`npm uninstall -g peaks-loop\` on the stale entries, or reorder PATH so the desired binary resolves first. Binaries:\n${binaryTable}`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: 'build:multi-binary-drift',
+                ok: false,
+                message: `multi-binary drift check failed: ${getErrorMessage(error)}`
+            }];
+    }
+}
+export const check = {
+    name: 'multi-binary-drift',
+    run
+};

package/dist/services/doctor/doctor-service/plugin-registry.js

@@ -43,6 +43,7 @@ import { check as statuslineInstall } from './checks/statusline-install.js';
 import { check as statuslineRuntime } from './checks/statusline-runtime.js';
 import { check as codegraphCapability } from './checks/codegraph-capability.js';
 import { check as distSourceVersion } from './checks/dist-source-version.js';
+import { check as multiBinaryDrift } from './checks/multi-binary-drift.js';
 import { check as workspaceLayout } from './checks/workspace-layout.js';
 import { check as gateguardConflict } from './checks/gateguard-conflict.js';
 import { check as checkIdSchema } from './checks/check-id-schema.js';
@@ -69,6 +70,7 @@ export const PLUGINS = [
     statuslineRuntime, // id "statusline:runtime"
     codegraphCapability, // id "capability:codegraph"
     distSourceVersion, // id "build:dist-version-matches-source"
+    multiBinaryDrift, // id "build:multi-binary-drift"
     workspaceLayout, // id "build:workspace-layout-canonical"
     gateguardConflict, // id "integration:gateguard-peaks-conflict"
     checkIdSchema, // id "doctor-self:check-id-pattern"

package/dist/services/doctor/doctor-service/report/final-summary.d.ts

@@ -2,11 +2,19 @@
  * Report aggregator: convert the accumulated `DoctorCheck[]` into the
  * public `DoctorReport` shape (checks + summary).
  *
- * The summary is a pure reduction over the checks — it counts the
- * passing and failing rows, derives `ok = failed === 0`, and
- * returns the `{ checks, summary }` tuple. Kept in its own module
- * so the dispatcher (`index.ts`) stays a thin orchestration loop
- * and the aggregation rule has a single test surface.
+ * The summary is a pure reduction over the checks — it separates
+ * `error`-severity findings from `warning`-severity findings, derives
+ * `ok = errors === 0`, and returns the `{ checks, summary }` tuple.
+ * Kept in its own module so the dispatcher (`index.ts`) stays a thin
+ * orchestration loop and the aggregation rule has a single test surface.
+ *
+ * Severity-aware aggregation (slice
+ * 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+ * repair cycle): a check with `severity: 'warning'` reports `ok: false`
+ * (so operators see the finding in the JSON envelope) but does NOT
+ * flip `summary.ok` and therefore does NOT flip the doctor exit code.
+ * Genuine failures (severity omitted, or `severity: 'error'`) behave
+ * the same as the pre-slice `failed === 0` rule.
  */
 import type { DoctorCheck, DoctorReport } from '../types.js';
 /**

package/dist/services/doctor/doctor-service/report/final-summary.js

@@ -2,11 +2,19 @@
  * Report aggregator: convert the accumulated `DoctorCheck[]` into the
  * public `DoctorReport` shape (checks + summary).
  *
- * The summary is a pure reduction over the checks — it counts the
- * passing and failing rows, derives `ok = failed === 0`, and
- * returns the `{ checks, summary }` tuple. Kept in its own module
- * so the dispatcher (`index.ts`) stays a thin orchestration loop
- * and the aggregation rule has a single test surface.
+ * The summary is a pure reduction over the checks — it separates
+ * `error`-severity findings from `warning`-severity findings, derives
+ * `ok = errors === 0`, and returns the `{ checks, summary }` tuple.
+ * Kept in its own module so the dispatcher (`index.ts`) stays a thin
+ * orchestration loop and the aggregation rule has a single test surface.
+ *
+ * Severity-aware aggregation (slice
+ * 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+ * repair cycle): a check with `severity: 'warning'` reports `ok: false`
+ * (so operators see the finding in the JSON envelope) but does NOT
+ * flip `summary.ok` and therefore does NOT flip the doctor exit code.
+ * Genuine failures (severity omitted, or `severity: 'error'`) behave
+ * the same as the pre-slice `failed === 0` rule.
  */
 /**
  * Build the final report from the accumulated checks.
@@ -17,13 +25,15 @@
  * report shape the public API exposes.
  */
 export function buildReport(checks) {
-    const failed = checks.filter((check) => !check.ok).length;
+    const errors = checks.filter((check) => !check.ok && check.severity !== 'warning').length;
+    const warnings = checks.filter((check) => !check.ok && check.severity === 'warning').length;
     return {
         checks: [...checks],
         summary: {
-            ok: failed === 0,
-            passed: checks.length - failed,
-            failed
+            ok: errors === 0,
+            passed: checks.length - errors - warnings,
+            failed: errors,
+            warnings
         }
     };
 }