peaks-loop 4.0.11 → 4.0.13

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/checks/skill-presence.js

@@ -33,7 +33,7 @@ function run({ options, presence }) {
             {
                 id: 'skill-presence:current',
                 ok: true,
-                message: 'No active Peaks skill presence (.peaks/.active-skill.json absent or invalid)'
+                message: 'No active Peaks skill presence (no canonical lease under .peaks/_runtime/<sid>/leases/)'
             },
             {
                 id: 'skill-presence:freshness',

package/dist/services/doctor/doctor-service/checks/workspace-layout.d.ts

@@ -4,8 +4,10 @@
  *
  * Build-hygiene check that surfaces any leftover top-level session
  * dirs (`.peaks/<YYYY-MM-DD-session-<hex>>/`), the legacy runtime
- * dotfiles (`.peaks/.session.json`, `.peaks/.active-skill.json`),
- * OR per-change-id top-level dirs (`.peaks/NNN-YYYY-MM-DD-<slug>/`).
+ * dotfiles (`.peaks/.session.json`), the stale single-slot
+ * presence file (`.peaks/_runtime/active-skill.json`, the deprecated
+ * project-level marker removed in slice 4.0.11), OR per-change-id
+ * top-level dirs (`.peaks/NNN-YYYY-MM-DD-<slug>/`).
  *
  * The post-F3 canonical layout puts session dirs under
  * `.peaks/_runtime/<sid>/` and the runtime binding at
@@ -29,5 +31,6 @@ export declare function inspectWorkspaceLayout(opts: {
     topLevelScanner?: (root: string) => string[];
     dotfileScanner?: (root: string) => string[];
     perChangeIdScanner?: (root: string) => string[];
+    staleSingleSlotScanner?: (root: string) => string[];
 }): WorkspaceLayoutInspection;
 export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/workspace-layout.js

@@ -4,8 +4,10 @@
  *
  * Build-hygiene check that surfaces any leftover top-level session
  * dirs (`.peaks/<YYYY-MM-DD-session-<hex>>/`), the legacy runtime
- * dotfiles (`.peaks/.session.json`, `.peaks/.active-skill.json`),
- * OR per-change-id top-level dirs (`.peaks/NNN-YYYY-MM-DD-<slug>/`).
+ * dotfiles (`.peaks/.session.json`), the stale single-slot
+ * presence file (`.peaks/_runtime/active-skill.json`, the deprecated
+ * project-level marker removed in slice 4.0.11), OR per-change-id
+ * top-level dirs (`.peaks/NNN-YYYY-MM-DD-<slug>/`).
  *
  * The post-F3 canonical layout puts session dirs under
  * `.peaks/_runtime/<sid>/` and the runtime binding at
@@ -31,7 +33,24 @@ const SESSION_DIR_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
  * `0NN-session-...`, `YYYY-MM-DD-session-...`).
  */
 const PER_CHANGE_ID_PATTERN = /^\d{3}-\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
-const LEGACY_DOTFILES = ['.session.json', '.active-skill.json'];
+// Slice 4.0.11 statusline-sid-scoped-lease C: `.peaks/.active-skill.json`
+// is REMOVED from LEGACY_DOTFILES (the file should not exist on
+// healthy post-4.0.11 projects; treating it as a generic legacy
+// dotfile is misleading). The new single-slot presence file
+// `.peaks/_runtime/active-skill.json` is reported separately under
+// `STALE_SINGLE_SLOT_FILES` so the operator gets a clear "stale
+// single-slot presence" message instead of a generic legacy warning.
+const LEGACY_DOTFILES = ['.session.json'];
+// Top-level single-slot presence files that are stale after the
+// sid-scoped lease projection (slice 4.0.8) shipped. Reported
+// separately from LEGACY_DOTFILES so the doctor message names the
+// specific issue ("stale single-slot presence") and the operator
+// can delete the file. The canonical sid-scoped lease at
+// `.peaks/_runtime/<sid>/leases/presence-*.json` is the source of truth.
+const STALE_SINGLE_SLOT_FILES = [
+    'active-skill.json',
+    '.active-skill.json'
+];
 /**
  * Pure helper that inspects the on-disk workspace layout for
  * post-F3-canonical violations. Exported so tests can drive the
@@ -42,10 +61,12 @@ export function inspectWorkspaceLayout(opts) {
     const topLevel = opts.topLevelScanner ?? defaultTopLevelSessionDirScanner;
     const dotfiles = opts.dotfileScanner ?? defaultLegacyDotfileScanner;
     const perChangeId = opts.perChangeIdScanner ?? defaultPerChangeIdDirScanner;
+    const staleSingleSlot = opts.staleSingleSlotScanner ?? defaultStaleSingleSlotScanner;
     return {
         topLevelSessionDirs: safeList(() => topLevel(opts.projectRoot)),
         legacyDotfiles: safeList(() => dotfiles(opts.projectRoot)),
-        perChangeIdDirs: safeList(() => perChangeId(opts.projectRoot))
+        perChangeIdDirs: safeList(() => perChangeId(opts.projectRoot)),
+        staleSingleSlotFiles: safeList(() => staleSingleSlot(opts.projectRoot))
     };
 }
 function safeList(reader) {
@@ -103,6 +124,39 @@ function defaultLegacyDotfileScanner(projectRoot) {
     }
     return offenders;
 }
+/**
+ * Slice 4.0.11 statusline-sid-scoped-lease C: surface the deprecated
+ * single-slot presence files (`.peaks/_runtime/active-skill.json` and
+ * the legacy `.peaks/.active-skill.json`) as a separate offender
+ * category. The canonical sid-scoped lease projection
+ * (`.peaks/_runtime/<sid>/leases/presence-*.json`) is the source of
+ * truth; these single-slot files should be deleted so the doctor
+ * report is clean.
+ *
+ * The reported path is the project-relative form so the doctor's
+ * human-readable output stays consistent with `legacyDotfiles`.
+ */
+function defaultStaleSingleSlotScanner(projectRoot) {
+    const offenders = [];
+    const candidates = [
+        join(projectRoot, '.peaks', '_runtime', 'active-skill.json'),
+        join(projectRoot, '.peaks', '.active-skill.json')
+    ];
+    const reported = [
+        join('.peaks', '_runtime', 'active-skill.json'),
+        join('.peaks', '.active-skill.json')
+    ];
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = candidates[i];
+        const reportedPath = reported[i];
+        if (candidate === undefined || reportedPath === undefined)
+            continue;
+        if (existsSync(candidate)) {
+            offenders.push(reportedPath);
+        }
+    }
+    return offenders;
+}
 function defaultPerChangeIdDirScanner(projectRoot) {
     const peaksRoot = join(projectRoot, '.peaks');
     if (!existsSync(peaksRoot))
@@ -136,7 +190,7 @@ function defaultPerChangeIdDirScanner(projectRoot) {
 function defaultWorkspaceLayoutProbe(projectRootResolver) {
     const projectRoot = projectRootResolver();
     if (projectRoot === null) {
-        return { topLevelSessionDirs: [], legacyDotfiles: [], perChangeIdDirs: [] };
+        return { topLevelSessionDirs: [], legacyDotfiles: [], perChangeIdDirs: [], staleSingleSlotFiles: [] };
     }
     return inspectWorkspaceLayout({ projectRoot });
 }
@@ -148,22 +202,29 @@ function run({ options, projectRootResolver }) {
         // return a 2-field shape (no perChangeIdDirs). Treat missing
         // field as empty.
         const perChangeIdDirs = layout.perChangeIdDirs ?? [];
-        if (layout.topLevelSessionDirs.length === 0 && layout.legacyDotfiles.length === 0 && perChangeIdDirs.length === 0) {
+        // Slice 4.0.11: probes injected by pre-4.0.11 tests also omit
+        // staleSingleSlotFiles. Treat missing field as empty.
+        const staleSingleSlotFiles = layout.staleSingleSlotFiles ?? [];
+        if (layout.topLevelSessionDirs.length === 0 &&
+            layout.legacyDotfiles.length === 0 &&
+            perChangeIdDirs.length === 0 &&
+            staleSingleSlotFiles.length === 0) {
             return [{
                     id: 'build:workspace-layout-canonical',
                     ok: true,
-                    message: 'Workspace layout is canonical: no top-level session dirs, no legacy runtime dotfiles, no per-change-id top-level dirs'
+                    message: 'Workspace layout is canonical: no top-level session dirs, no legacy runtime dotfiles, no per-change-id top-level dirs, no stale single-slot presence files'
                 }];
         }
         const offenders = [
             ...layout.topLevelSessionDirs.map((p) => `top-level session dir: ${p}`),
             ...layout.legacyDotfiles.map((p) => `legacy dotfile: ${p}`),
-            ...perChangeIdDirs.map((p) => `per-change-id top-level dir: ${p}`)
+            ...perChangeIdDirs.map((p) => `per-change-id top-level dir: ${p}`),
+            ...staleSingleSlotFiles.map((p) => `stale single-slot presence: ${p}`)
         ];
         return [{
                 id: 'build:workspace-layout-canonical',
                 ok: false,
-                message: `Workspace layout is not canonical. Offenders: ${offenders.join('; ')}. Run \`peaks workspace migrate --to-runtime --project <repo> --apply\` to consolidate.`
+                message: `Workspace layout is not canonical. Offenders: ${offenders.join('; ')}. Run \`peaks workspace migrate --to-runtime --project <repo> --apply\` to consolidate; delete stale single-slot presence files manually after migration.`
             }];
     }
     catch (error) {

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
         }
     };
 }

package/dist/services/doctor/doctor-service/types.d.ts

@@ -12,10 +12,32 @@
  * flow through the same names so the main package's `import { runDoctor }`
  * keeps working unchanged.
  */
+/**
+ * Severity for a single doctor check. `'error'` flips the exit code
+ * (via `buildReport` and the CLI dispatcher); `'warning'` surfaces
+ * the finding in the JSON envelope (`ok: false` + `severity: 'warning'`)
+ * but does NOT escalate the doctor exit code to 1.
+ *
+ * Optional in the type for back-compat with older check plugins that
+ * pre-date the severity-aware summary (slice
+ * 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+ * repair cycle). When omitted, the dispatcher treats the check as
+ * `'error'` — i.e. `ok: false` escalates the exit code the same way
+ * it did before this slice.
+ */
+export type DoctorCheckSeverity = 'error' | 'warning';
 export type DoctorCheck = {
     id: string;
     ok: boolean;
     message: string;
+    /**
+     * Optional severity tag. When `'warning'`, the check still reports
+     * `ok: false` (so operators see the finding in the JSON envelope)
+     * but `buildReport` does NOT count it as a failure for the
+     * `summary.ok` exit-code calculation. Default-omitted checks
+     * behave as `'error'`.
+     */
+    severity?: DoctorCheckSeverity;
 };
 export type DoctorReport = {
     checks: DoctorCheck[];
@@ -23,6 +45,15 @@ export type DoctorReport = {
         ok: boolean;
         passed: number;
         failed: number;
+        /**
+         * Severity-aware summary (slice
+         * 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+         * repair cycle): count of findings tagged
+         * `severity: 'warning'`. Warnings surface in the JSON envelope
+         * (`ok: false`) but do NOT flip `summary.ok` and therefore do
+         * NOT flip the doctor exit code.
+         */
+        warnings: number;
     };
 };
 export type CodegraphCapabilityProbe = {
@@ -38,6 +69,24 @@ export type DistVersionComparison = {
     distReadable: boolean;
 };
 export type DistVersionProbe = () => DistVersionComparison;
+/**
+ * Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+ * (G3/G4) — probe for the multi-binary drift check. The probe returns
+ * the discovered peaks-loop binaries on PATH (with their resolved
+ * version + install date) and a `driftDetected` flag. Injected so tests
+ * can drive the filesystem walk without monkey-patching
+ * `process.env.PATH` or `realpathSync`.
+ */
+export type MultiBinaryDriftInspection = {
+    readonly binaries: ReadonlyArray<{
+        readonly path: string;
+        readonly version: string | null;
+        readonly installDate: string | null;
+    }>;
+    readonly driftDetected: boolean;
+    readonly uniqueVersions: ReadonlyArray<string>;
+};
+export type MultiBinaryDriftProbe = () => MultiBinaryDriftInspection;
 export type WorkspaceLayoutInspection = {
     topLevelSessionDirs: string[];
     legacyDotfiles: string[];
@@ -55,6 +104,15 @@ export type WorkspaceLayoutInspection = {
      * to an empty array when the field is missing.
      */
     perChangeIdDirs?: string[];
+    /**
+     * Slice 4.0.11 statusline-sid-scoped-lease C — single-slot
+     * presence files that are stale after the sid-scoped lease
+     * projection shipped in 4.0.8. Reported separately from
+     * `legacyDotfiles` so the doctor message names the specific
+     * "stale single-slot presence" condition. Optional for back-compat
+     * with probes injected by older tests.
+     */
+    staleSingleSlotFiles?: string[];
 };
 export type WorkspaceLayoutProbe = () => WorkspaceLayoutInspection;
 /**
@@ -141,6 +199,12 @@ export type DoctorOptions = {
     platform?: NodeJS.Platform;
     /** Injected for the build:dist-version-matches-source check (defaults to compareDistVersion on disk). */
     distVersionProbe?: DistVersionProbe;
+    /**
+     * Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
+     * (G3/G4) — injected for the build:multi-binary-drift check (defaults
+     * to inspectMultiBinaryDrift against `process.env.PATH`).
+     */
+    multiBinaryDriftProbe?: MultiBinaryDriftProbe;
     /** Injected for the build:workspace-layout-canonical check (defaults to inspectWorkspaceLayout on disk). */
     workspaceLayoutProbe?: WorkspaceLayoutProbe;
     /** Injected for the integration:gateguard-peaks-conflict check (defaults to defaultGateguardProbe on disk). */

package/dist/services/doctor/doctor-service.d.ts

@@ -14,5 +14,6 @@ export * from './doctor-service/index.js';
 export { compareDistVersion } from './doctor-service/checks/dist-source-version.js';
 export { inspectWorkspaceLayout } from './doctor-service/checks/workspace-layout.js';
 export { collectGateguardEntries } from './doctor-service/checks/gateguard-conflict.js';
+export { inspectMultiBinaryDrift, type PeaksBinaryRecord } from './doctor-service/checks/multi-binary-drift.js';
 export { PLUGINS } from './doctor-service/plugin-registry.js';
-export type { DoctorCheck, DoctorReport, DoctorOptions, DoctorCheckPlugin, DoctorContext, DoctorSkillEntry, DoctorSkillLoadFailure, DoctorSkillsResult, DoctorSkillPresence, CodegraphCapabilityProbe, DistVersionComparison, DistVersionProbe, WorkspaceLayoutInspection, WorkspaceLayoutProbe, GateguardHookLocation, GateguardProbeResult, GateguardProbe } from './doctor-service/types.js';
+export type { DoctorCheck, DoctorReport, DoctorOptions, DoctorCheckPlugin, DoctorContext, DoctorSkillEntry, DoctorSkillLoadFailure, DoctorSkillsResult, DoctorSkillPresence, CodegraphCapabilityProbe, DistVersionComparison, DistVersionProbe, MultiBinaryDriftInspection, MultiBinaryDriftProbe, WorkspaceLayoutInspection, WorkspaceLayoutProbe, GateguardHookLocation, GateguardProbeResult, GateguardProbe } from './doctor-service/types.js';

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

@@ -19,6 +19,7 @@ export * from './doctor-service/index.js';
 export { compareDistVersion } from './doctor-service/checks/dist-source-version.js';
 export { inspectWorkspaceLayout } from './doctor-service/checks/workspace-layout.js';
 export { collectGateguardEntries } from './doctor-service/checks/gateguard-conflict.js';
+export { inspectMultiBinaryDrift } from './doctor-service/checks/multi-binary-drift.js';
 // Re-export the fixed plugin registry so characterization tests and
 // future CLI surfaces (e.g. `peaks doctor --list-checks`) can enumerate
 // the check pipeline without reaching into a private module path.

package/dist/services/doctor/index.d.ts

@@ -19,4 +19,4 @@
  * See .peaks/_runtime/2026-07-17-session-1d5ac0/rd/slice-3b-doctor.md
  * for the slice-3b Option C decision rationale.
  */
-export { runDoctor, isWorkspaceInitializedAt, compareDistVersion, inspectWorkspaceLayout, collectGateguardEntries, type DoctorCheck, type DoctorReport, type DoctorOptions, type CodegraphCapabilityProbe, type DistVersionComparison, type DistVersionProbe, type WorkspaceLayoutInspection, type WorkspaceLayoutProbe, type GateguardHookLocation, type GateguardProbeResult, type GateguardProbe, } from './doctor-service.js';
+export { runDoctor, isWorkspaceInitializedAt, compareDistVersion, inspectWorkspaceLayout, inspectMultiBinaryDrift, collectGateguardEntries, type DoctorCheck, type DoctorReport, type DoctorOptions, type CodegraphCapabilityProbe, type DistVersionComparison, type DistVersionProbe, type MultiBinaryDriftInspection, type MultiBinaryDriftProbe, type PeaksBinaryRecord, type WorkspaceLayoutInspection, type WorkspaceLayoutProbe, type GateguardHookLocation, type GateguardProbeResult, type GateguardProbe, } from './doctor-service.js';

package/dist/services/doctor/index.js

@@ -19,4 +19,4 @@
  * See .peaks/_runtime/2026-07-17-session-1d5ac0/rd/slice-3b-doctor.md
  * for the slice-3b Option C decision rationale.
  */
-export { runDoctor, isWorkspaceInitializedAt, compareDistVersion, inspectWorkspaceLayout, collectGateguardEntries, } from './doctor-service.js';
+export { runDoctor, isWorkspaceInitializedAt, compareDistVersion, inspectWorkspaceLayout, inspectMultiBinaryDrift, collectGateguardEntries, } from './doctor-service.js';