peaks-loop 4.0.0-beta.9 → 4.0.1

package/dist/services/dispatch/sub-agent-dispatcher.js

@@ -9,7 +9,7 @@
  *
  * Per-IDE contract: given a sub-agent role + prompt + request/session ids,
  * return a tool-call descriptor that the calling LLM should execute in
- * its native environment. The CLI is IDE-agnostic; per-IDE tool names
+ * its own environment. The CLI is IDE-agnostic; per-IDE tool names
  * (Claude Code's `Task`, Trae's UNVERIFIED placeholder) are encapsulated
  * here, never leaked to SKILL.md.
  *
@@ -27,6 +27,13 @@
  * Cross-reference: PRD #002 G1 (AC-1..AC-5); RD tech-doc-002 §2.
  */
 import { existsSync, readFileSync } from 'node:fs';
+// Slice 2026-07-29-dispatch-stall-governance / S4 — the two near-
+// identical poll loops in this file are now thin wrappers around
+// `awaitBatch` (the unified implementation in ./await-batch.ts). The
+// back-compat envelopes are preserved so the pre-S4 S3 character-
+// ization tests + the existing call sites do not have to migrate in
+// the same slice.
+import { awaitBatch as awaitBatchUnified } from './await-batch.js';
 /**
  * Claude Code dispatcher. Real, byte-level implementation.
  *
@@ -233,52 +240,26 @@ const claudeCodeBatchAwaiters = new Map();
  *    for the MVP; the real cross-process version uses heartbeat polling).
  */
 export async function awaitClaudeCodeBatch(input) {
-    const { batchId, dispatchCount, recordPaths, timeoutMs } = input;
-    if (dispatchCount <= 0 || recordPaths.length === 0) {
-        return [];
-    }
-    const startedAt = Date.now();
-    const pollIntervalMs = 50;
-    const deadline = timeoutMs ?? 60_000;
-    const capped = Math.min(deadline, 120_000);
-    // MVP: race the deadline against a simple polling loop. Real per-IDE
-    // implementations land in slice 1.3.
-    const results = [];
-    const remaining = new Map();
-    for (let i = 0; i < recordPaths.length; i += 1) {
-        const recordPath = recordPaths[i] ?? '';
-        remaining.set(i, { recordPath, status: 'timeout', note: null, finishedAt: null });
-    }
-    while (remaining.size > 0 && Date.now() - startedAt < capped) {
-        for (const [idx, slot] of remaining) {
-            if (slot.finishedAt !== null)
-                continue;
-            const outcome = readDispatchOutcome(slot.recordPath);
-            if (outcome === null)
-                continue;
-            slot.status = outcome.status;
-            slot.note = outcome.note;
-            slot.finishedAt = Date.now();
-        }
-        if (Array.from(remaining.values()).every((s) => s.finishedAt !== null))
-            break;
-        await new Promise((r) => setTimeout(r, pollIntervalMs));
-    }
-    for (const [idx, slot] of remaining) {
-        const finishedAt = slot.finishedAt ?? startedAt + capped;
-        results.push({
-            dispatchIndex: idx,
-            recordPath: slot.recordPath,
-            status: slot.status,
-            durationMs: finishedAt - startedAt,
-            note: slot.note
-        });
-    }
-    results.sort((a, b) => a.dispatchIndex - b.dispatchIndex);
-    // Touch batchId so the parameter is "used" — keeps the linter happy when
-    // the in-process queue (claudeCodeBatchAwaiters) is later wired up.
-    void batchId;
-    return results;
+    // Slice 2026-07-29-dispatch-stall-governance / S4 (G8) — this
+    // function is now a thin wrapper around the unified `awaitBatch`
+    // service. The back-compat envelope shape is preserved (one
+    // `SubAgentBatchResult` per record path) so the S3 characterization
+    // test stays green; the underlying loop is identical to the trae /
+    // trae-cn / codex / cursor wrappers below. The new typed outcome
+    // lives on the unified service; the S4 fail-fast test pins it.
+    //
+    // Slice 2026-07-30-nightshift: claude-code does NOT use a
+    // per-IDE note prefix. The 1.4 dogfood contract says the done
+    // note is `null` (raw outcome) and the failed note is the raw
+    // `outcome` string with no prefix. The 4 non-Claude IDEs
+    // (trae / trae-cn / codex / cursor) prefix the note with their
+    // per-IDE label so cross-IDE attribution is visible to the LLM.
+    // Passing no `notePrefix` here keeps the legacy contract.
+    const unified = await awaitBatchUnified(input.dispatchCount, input.recordPaths, input.timeoutMs, { defaultTimeoutMs: 60_000 });
+    // Touch batchId so the parameter remains in scope for any future
+    // in-process queue wiring.
+    void input.batchId;
+    return unified.results;
 }
 /** Best-effort outcome read for a dispatch record. Returns null if pending. */
 function readDispatchOutcome(recordPath) {
@@ -305,48 +286,18 @@ function readDispatchOutcome(recordPath) {
     }
 }
 export async function pollDispatchRecords(input, opts) {
-    const { dispatchCount, recordPaths, timeoutMs } = input;
-    if (dispatchCount <= 0 || recordPaths.length === 0) {
-        return [];
-    }
-    const startedAt = Date.now();
-    const pollIntervalMs = 50;
-    const deadline = timeoutMs ?? opts.defaultTimeoutMs;
-    const capped = Math.min(Math.max(deadline, 0), 120_000);
-    const results = [];
-    const remaining = new Map();
-    for (let i = 0; i < recordPaths.length; i += 1) {
-        const recordPath = recordPaths[i] ?? '';
-        remaining.set(i, { recordPath, status: 'timeout', note: null, finishedAt: null });
-    }
-    while (remaining.size > 0 && Date.now() - startedAt < capped) {
-        for (const [idx, slot] of remaining) {
-            if (slot.finishedAt !== null)
-                continue;
-            const outcome = readDispatchOutcome(slot.recordPath);
-            if (outcome === null)
-                continue;
-            slot.status = outcome.status;
-            slot.note = outcome.note;
-            slot.finishedAt = Date.now();
-        }
-        if (Array.from(remaining.values()).every((s) => s.finishedAt !== null))
-            break;
-        await new Promise((r) => setTimeout(r, pollIntervalMs));
-    }
-    for (const [idx, slot] of remaining) {
-        const finishedAt = slot.finishedAt ?? startedAt + capped;
-        const baseNote = slot.status === 'timeout' ? `${opts.notePrefix} (timeout)` : opts.notePrefix;
-        results.push({
-            dispatchIndex: idx,
-            recordPath: slot.recordPath,
-            status: slot.status,
-            durationMs: finishedAt - startedAt,
-            note: slot.note !== null ? `${baseNote} — ${slot.note}` : baseNote
-        });
-    }
-    results.sort((a, b) => a.dispatchIndex - b.dispatchIndex);
-    return results;
+    // Slice 2026-07-29-dispatch-stall-governance / S4 (G8) — this
+    // function is now a thin wrapper around the unified `awaitBatch`
+    // service. Pre-S4 it diverged from `awaitClaudeCodeBatch` in
+    // (a) the default-fallback source and (b) the `Math.max(deadline, 0)`
+    // step; the divergence is gone. The back-compat envelope (one
+    // `SubAgentBatchResult` per record path, with the IDE-prefixed
+    // note) is preserved.
+    const unified = await awaitBatchUnified(input.dispatchCount, input.recordPaths, input.timeoutMs, {
+        defaultTimeoutMs: opts.defaultTimeoutMs,
+        notePrefix: opts.notePrefix
+    });
+    return unified.results;
 }
 /**
  * 1.2 fallback for trae / trae-cn / codex / cursor. Deprecated by

package/dist/services/dispatch/test-tool-detection.d.ts

@@ -27,10 +27,34 @@
  *  the dispatch CLI always prepends it. This is a guarantee, not a
  *  suggestion.
  */
-export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nBefore running any test, read `package.json#scripts.test` to identify the project's test framework. Use the project-local runner \u2014 do NOT invoke `npx <runner>`:\n\n- **vitest** \u2192 `./node_modules/.bin/vitest run <file>` (or `pnpm test -- <file>`)\n- **jest**   \u2192 `./node_modules/.bin/jest <file>`   (or `pnpm test -- <file>`)\n- **mocha**  \u2192 `./node_modules/.bin/mocha <file>`  (or `pnpm test -- <file>`)\n\nIf unsure which framework the consumer project uses, run `peaks test --json` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command `peaks test <file>` already resolves the local binary for you (Windows-aware).";
+export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nBefore running any test, read `package.json#scripts.test` to identify the project's test framework. Use the project-local runner \u2014 do NOT invoke `npx <runner>`:\n\n- **vitest** \u2192 `./node_modules/.bin/vitest run <file>` (or `pnpm test -- <file>`)\n- **jest**   \u2192 `./node_modules/.bin/jest <file>`   (or `pnpm test -- <file>`)\n- **mocha**  \u2192 `./node_modules/.bin/mocha <file>`  (or `pnpm test -- <file>`)\n\n## Test Scope (mandatory)\n\nThe dispatched test command MUST be **scoped** to a single file or pattern. An unscoped `./node_modules/.bin/vitest run` (no path filter) is **refused** because the 483-file suite is one keystroke from a 36-minute wall clock:\n\n- **scoped**    \u2192 `./node_modules/.bin/vitest run tests/unit/foo.test.ts` (or any explicit file/pattern)\n- **intentional full run** \u2192 prefix with the explicit opt-in token `PEAKS_FULL_TEST=1` to override the scope gate. Use only for CI / release verification, never for routine verification during a slice.\n- **refused**   \u2192 bare `./node_modules/.bin/vitest run` (no argument after `run`) without the opt-in token.\n\n`pnpm test` / `pnpm test:unit` / `pnpm test:cli` / `pnpm test:integration` and any repo-defined `test*` script remain the **human / LLM direct path** and are not gated by this rule (PB-5).\n\nIf unsure which framework the consumer project uses, run `peaks test --json` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command `peaks test <file>` already resolves the local binary for you (Windows-aware).";
 /**
  * Pure helper that returns the block. Exists as a function (not just an
  * exported constant) so future variants can take a runtime parameter
  * (e.g. projectRoot for context) without churning every call site.
  */
 export declare function formatTestToolDetection(): string;
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S5 (AC-4.1 / AC-4.2) —
+ * pure scope classifier. Returns a typed result so callers (the
+ * dispatch prompt template, future test-runner bridges) can decide
+ * whether the command is allowed, refused, or requires the explicit
+ * opt-in.
+ *
+ *   - 'scoped'    — the command names a file/pattern after `run`
+ *   - 'opt-in'    — the user/LLM set PEAKS_FULL_TEST=1 to override
+ *   - 'refused'   — bare `vitest run` with no path and no opt-in
+ *   - 'unsupported' — the command is not a vitest/jest/mocha run at
+ *     all (the static block does not gate it; the caller decides)
+ *
+ * Pure: no I/O, no process spawn, no env reads. The dispatcher
+ * passes `env` explicitly so the test seam can assert behavior
+ * without mutating process.env.
+ */
+export type TestScopeClassification = 'scoped' | 'opt-in' | 'refused' | 'unsupported';
+export interface TestScopeDecision {
+    readonly classification: TestScopeClassification;
+    readonly reason: string;
+    readonly extractedPath: string | null;
+}
+export declare function classifyTestCommand(command: string, env?: Readonly<Record<string, string | undefined>>): TestScopeDecision;

package/dist/services/dispatch/test-tool-detection.js

@@ -35,6 +35,16 @@ Before running any test, read \`package.json#scripts.test\` to identify the proj
 - **jest**   → \`./node_modules/.bin/jest <file>\`   (or \`pnpm test -- <file>\`)
 - **mocha**  → \`./node_modules/.bin/mocha <file>\`  (or \`pnpm test -- <file>\`)
 
+## Test Scope (mandatory)
+
+The dispatched test command MUST be **scoped** to a single file or pattern. An unscoped \`./node_modules/.bin/vitest run\` (no path filter) is **refused** because the 483-file suite is one keystroke from a 36-minute wall clock:
+
+- **scoped**    → \`./node_modules/.bin/vitest run tests/unit/foo.test.ts\` (or any explicit file/pattern)
+- **intentional full run** → prefix with the explicit opt-in token \`PEAKS_FULL_TEST=1\` to override the scope gate. Use only for CI / release verification, never for routine verification during a slice.
+- **refused**   → bare \`./node_modules/.bin/vitest run\` (no argument after \`run\`) without the opt-in token.
+
+\`pnpm test\` / \`pnpm test:unit\` / \`pnpm test:cli\` / \`pnpm test:integration\` and any repo-defined \`test*\` script remain the **human / LLM direct path** and are not gated by this rule (PB-5).
+
 If unsure which framework the consumer project uses, run \`peaks test --json\` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command \`peaks test <file>\` already resolves the local binary for you (Windows-aware).`;
 /**
  * Pure helper that returns the block. Exists as a function (not just an
@@ -44,3 +54,73 @@ If unsure which framework the consumer project uses, run \`peaks test --json\` f
 export function formatTestToolDetection() {
     return TEST_TOOL_DETECTION_BLOCK;
 }
+export function classifyTestCommand(command, env = process.env) {
+    if (typeof command !== 'string') {
+        return {
+            classification: 'unsupported',
+            reason: 'command is not a string',
+            extractedPath: null
+        };
+    }
+    const trimmed = command.trim();
+    // Only vitest / jest / mocha runner invocations are in scope; other
+    // commands (e.g. node, curl) are out of the scope-rule's reach
+    // (PB-5: ordinary direct human project scripts are not gated).
+    const lower = trimmed.toLowerCase();
+    const isRunnerInvocation = /(?:\.\/node_modules\/\.bin\/|\b)(?:vitest|jest|mocha)\b/.test(lower);
+    if (!isRunnerInvocation) {
+        return {
+            classification: 'unsupported',
+            reason: 'command is not a vitest/jest/mocha runner invocation',
+            extractedPath: null
+        };
+    }
+    // Split into tokens. Quoted paths (e.g. "tests/unit/foo bar.test.ts")
+    // are preserved as a single token by the simple `match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)`
+    // approach; the static block does not need shell-level fidelity,
+    // only the existence of at least one non-flag, non-runner path
+    // token.
+    const tokens = trimmed.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+    // Find the runner token and look for arguments after it.
+    const runnerIdx = tokens.findIndex((t) => /(^|\/)(vitest|jest|mocha)(\.cmd|\.exe)?$/.test(t.toLowerCase()));
+    if (runnerIdx < 0) {
+        return {
+            classification: 'unsupported',
+            reason: 'runner token not found in command',
+            extractedPath: null
+        };
+    }
+    const after = tokens.slice(runnerIdx + 1);
+    // Strip flags (e.g. --config, --reporter, --coverage). A flag is
+    // any token starting with `-`. The path we care about is the first
+    // non-flag, non-runner, non-keyword token after the runner.
+    const PATH_KEYWORDS = new Set(['run', 'watch', 'test', 'c', 'ci', 'r', 'reporter', 't', 'u', 'coverage']);
+    const pathTokens = [];
+    for (const tok of after) {
+        if (tok.startsWith('-'))
+            continue;
+        if (PATH_KEYWORDS.has(tok.toLowerCase()))
+            continue;
+        pathTokens.push(tok);
+    }
+    if (pathTokens.length === 0) {
+        // No path at all. The opt-in token flips this to 'opt-in'.
+        if (env.PEAKS_FULL_TEST === '1' || env.PEAKS_FULL_TEST === 'true') {
+            return {
+                classification: 'opt-in',
+                reason: 'bare run command with PEAKS_FULL_TEST=1 opt-in',
+                extractedPath: null
+            };
+        }
+        return {
+            classification: 'refused',
+            reason: 'bare runner invocation with no path filter and no PEAKS_FULL_TEST opt-in',
+            extractedPath: null
+        };
+    }
+    return {
+        classification: 'scoped',
+        reason: `runner invocation scoped to ${pathTokens.length} path token(s)`,
+        extractedPath: pathTokens[0] ?? null
+    };
+}

package/dist/services/doctor/doctor-service/checks/check-id-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Check: every emitted check ID matches the `doctor-report.schema.json`
+ * check.id pattern (`doctor-self:check-id-pattern`).
+ *
+ * Self-validation gate that runs after every other check so it can
+ * observe the full list of emitted IDs. Fails when:
+ *   - The schema file is missing / unreadable.
+ *   - The schema does not declare a `checks.items.properties.id.pattern`.
+ *   - Any emitted check ID does not match the declared pattern.
+ *
+ * The accumulator is passed via the `DoctorContext` (see types.ts:
+ * `accumulatedChecks`). The plugin dispatcher in `index.ts` builds
+ * the accumulator incrementally and updates it before each plugin
+ * runs, so by the time this check fires every prior check's IDs are
+ * visible.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/check-id-schema.js

@@ -0,0 +1,64 @@
+/**
+ * Check: every emitted check ID matches the `doctor-report.schema.json`
+ * check.id pattern (`doctor-self:check-id-pattern`).
+ *
+ * Self-validation gate that runs after every other check so it can
+ * observe the full list of emitted IDs. Fails when:
+ *   - The schema file is missing / unreadable.
+ *   - The schema does not declare a `checks.items.properties.id.pattern`.
+ *   - Any emitted check ID does not match the declared pattern.
+ *
+ * The accumulator is passed via the `DoctorContext` (see types.ts:
+ * `accumulatedChecks`). The plugin dispatcher in `index.ts` builds
+ * the accumulator incrementally and updates it before each plugin
+ * runs, so by the time this check fires every prior check's IDs are
+ * visible.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+function runSelfCheck(schemaRoot, emittedIds) {
+    const schemaPath = join(schemaRoot, 'doctor-report.schema.json');
+    if (!existsSync(schemaPath)) {
+        return [{
+                id: 'doctor-self:check-id-pattern',
+                ok: false,
+                message: `Failed to load doctor-report.schema.json for self-validation: ${getErrorMessage(new Error(`ENOENT: ${schemaPath}`))}`
+            }];
+    }
+    try {
+        const schemaText = readFileSync(schemaPath, 'utf8');
+        const schema = JSON.parse(schemaText);
+        const patternSource = schema.properties?.checks?.items?.properties?.id?.pattern;
+        if (typeof patternSource !== 'string') {
+            return [{
+                    id: 'doctor-self:check-id-pattern',
+                    ok: false,
+                    message: 'doctor-report.schema.json does not declare a check.id pattern'
+                }];
+        }
+        const pattern = new RegExp(patternSource);
+        const mismatches = emittedIds.filter((id) => !pattern.test(id));
+        return [{
+                id: 'doctor-self:check-id-pattern',
+                ok: mismatches.length === 0,
+                message: mismatches.length === 0
+                    ? 'All doctor check IDs match the doctor-report schema pattern'
+                    : `Doctor check IDs missing from schema pattern: ${mismatches.join(', ')}`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: 'doctor-self:check-id-pattern',
+                ok: false,
+                message: `Failed to load doctor-report.schema.json for self-validation: ${getErrorMessage(error)}`
+            }];
+    }
+}
+function run({ schemaRoot, accumulatedChecks }) {
+    return runSelfCheck(schemaRoot, accumulatedChecks.map((check) => check.id));
+}
+export const check = {
+    name: 'check-id-schema',
+    run
+};

package/dist/services/doctor/doctor-service/checks/codegraph-capability.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Check: codegraph capability (`capability:codegraph`).
+ *
+ * Verifies that `@colbymchenry/codegraph` resolves at the pinned
+ * version AND that the binary exists at the expected on-disk path.
+ * Fails when the version drifts, when the binary is missing, or
+ * when the package is not resolvable at all.
+ *
+ * The probe is injected so tests do not depend on the real
+ * `node_modules` resolution; the default probe uses
+ * `createRequire(import.meta.url)` to find the package.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/codegraph-capability.js

@@ -0,0 +1,69 @@
+/**
+ * Check: codegraph capability (`capability:codegraph`).
+ *
+ * Verifies that `@colbymchenry/codegraph` resolves at the pinned
+ * version AND that the binary exists at the expected on-disk path.
+ * Fails when the version drifts, when the binary is missing, or
+ * when the package is not resolvable at all.
+ *
+ * The probe is injected so tests do not depend on the real
+ * `node_modules` resolution; the default probe uses
+ * `createRequire(import.meta.url)` to find the package.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { createRequire } from 'node:module';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+const CODEGRAPH_EXPECTED_VERSION = '0.7.10';
+function defaultCodegraphProbe() {
+    const require = createRequire(import.meta.url);
+    const packagePath = require.resolve('@colbymchenry/codegraph/package.json');
+    const pkg = require(packagePath);
+    const binaryPath = resolvePath(dirname(packagePath), 'dist', 'bin', 'codegraph.js');
+    return {
+        packagePath,
+        version: pkg.version ?? 'unknown',
+        binaryPath,
+        binaryExists: existsSync(binaryPath)
+    };
+}
+function runCheck(probe) {
+    try {
+        const result = probe();
+        const versionOk = result.version === CODEGRAPH_EXPECTED_VERSION;
+        if (!versionOk) {
+            return [{
+                    id: 'capability:codegraph',
+                    ok: false,
+                    message: `@colbymchenry/codegraph version mismatch: expected ${CODEGRAPH_EXPECTED_VERSION}, resolved ${result.version} at ${result.packagePath}`
+                }];
+        }
+        if (!result.binaryExists) {
+            return [{
+                    id: 'capability:codegraph',
+                    ok: false,
+                    message: `@colbymchenry/codegraph@${result.version} resolved at ${result.packagePath} but binary is missing at ${result.binaryPath}`
+                }];
+        }
+        return [{
+                id: 'capability:codegraph',
+                ok: true,
+                message: `@colbymchenry/codegraph@${result.version} resolves with binary at ${result.binaryPath}`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: 'capability:codegraph',
+                ok: false,
+                message: `@colbymchenry/codegraph not resolvable: ${getErrorMessage(error)}`
+            }];
+    }
+}
+function run({ options }) {
+    const probe = options.codegraphProbe ?? defaultCodegraphProbe;
+    return runCheck(probe);
+}
+export const check = {
+    name: 'codegraph-capability',
+    run
+};

package/dist/services/doctor/doctor-service/checks/dist-source-version.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Check: dist CLI_VERSION matches source `package.json#version`
+ * (`build:dist-version-matches-source`).
+ *
+ * Build-hygiene check that surfaces the silent-stale-CLI failure
+ * mode where the user runs `npx peaks` / `node bin/peaks.js` after
+ * `pnpm install` but before `pnpm build`. A missing dist/ is treated
+ * as informational (fresh clone, not broken) so the check does not
+ * flip the summary to red on a clean checkout.
+ *
+ * IMPORTANT: the on-disk path is `dist/shared/version.js` (NOT
+ * `dist/src/shared/version.js`) because `tsconfig.build.json#rootDir
+ * = "src"` trims the `src/` segment from emitted output.
+ *
+ * The pure compare helper is exported as `compareDistVersion` so
+ * tests can drive the filesystem reads without monkey-patching
+ * `process.cwd()`.
+ */
+import type { DistVersionComparison, DoctorCheckPlugin } from '../types.js';
+/**
+ * Pure helper that compares the published dist `CLI_VERSION` against
+ * the source-of-truth `package.json#version`. Default readers fail-
+ * soft to `null` on missing/unreadable/malformed input. Exported so
+ * tests can drive the filesystem reads without monkey-patching
+ * `process.cwd()`.
+ */
+export declare function compareDistVersion(opts: {
+    projectRoot: string;
+    distVersionReader?: (root: string) => string | null;
+    sourceVersionReader?: (root: string) => string | null;
+}): DistVersionComparison;
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/dist-source-version.js

@@ -0,0 +1,110 @@
+/**
+ * Check: dist CLI_VERSION matches source `package.json#version`
+ * (`build:dist-version-matches-source`).
+ *
+ * Build-hygiene check that surfaces the silent-stale-CLI failure
+ * mode where the user runs `npx peaks` / `node bin/peaks.js` after
+ * `pnpm install` but before `pnpm build`. A missing dist/ is treated
+ * as informational (fresh clone, not broken) so the check does not
+ * flip the summary to red on a clean checkout.
+ *
+ * IMPORTANT: the on-disk path is `dist/shared/version.js` (NOT
+ * `dist/src/shared/version.js`) because `tsconfig.build.json#rootDir
+ * = "src"` trims the `src/` segment from emitted output.
+ *
+ * The pure compare helper is exported as `compareDistVersion` so
+ * tests can drive the filesystem reads without monkey-patching
+ * `process.cwd()`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+/**
+ * Pure helper that compares the published dist `CLI_VERSION` against
+ * the source-of-truth `package.json#version`. Default readers fail-
+ * soft to `null` on missing/unreadable/malformed input. Exported so
+ * tests can drive the filesystem reads without monkey-patching
+ * `process.cwd()`.
+ */
+export function compareDistVersion(opts) {
+    const distReader = opts.distVersionReader ?? defaultDistVersionReader;
+    const sourceReader = opts.sourceVersionReader ?? defaultSourceVersionReader;
+    const dist = safeRead(() => distReader(opts.projectRoot));
+    const source = safeRead(() => sourceReader(opts.projectRoot)) ?? 'unknown';
+    const distReadable = dist !== null;
+    return {
+        dist,
+        source,
+        match: distReadable && dist === source,
+        distReadable
+    };
+}
+function safeRead(reader) {
+    try {
+        return reader();
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function defaultDistVersionReader(projectRoot) {
+    const distPath = join(projectRoot, 'dist', 'shared', 'version.js');
+    if (!existsSync(distPath)) {
+        return null;
+    }
+    const body = readFileSync(distPath, 'utf8');
+    const match = /export\s+const\s+CLI_VERSION\s*=\s*["']([^"']+)["']/.exec(body);
+    return match?.[1] ?? null;
+}
+function defaultSourceVersionReader(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return null;
+    }
+    const body = readFileSync(pkgPath, 'utf8');
+    const parsed = JSON.parse(body);
+    return typeof parsed.version === 'string' ? parsed.version : null;
+}
+function defaultDistVersionProbe(projectRootResolver) {
+    const projectRoot = projectRootResolver();
+    if (projectRoot === null) {
+        return { dist: null, source: 'unknown', match: false, distReadable: false };
+    }
+    return compareDistVersion({ projectRoot });
+}
+function run({ options, projectRootResolver }) {
+    const probe = options.distVersionProbe ?? (() => defaultDistVersionProbe(projectRootResolver));
+    try {
+        const result = probe();
+        if (!result.distReadable) {
+            return [{
+                    id: 'build:dist-version-matches-source',
+                    ok: true,
+                    message: `dist/ is not present; run \`pnpm build\` to populate dist/shared/version.js (source version ${result.source})`
+                }];
+        }
+        if (result.match) {
+            return [{
+                    id: 'build:dist-version-matches-source',
+                    ok: true,
+                    message: `dist/shared/version.js ships CLI_VERSION ${result.dist} matching source ${result.source}`
+                }];
+        }
+        return [{
+                id: 'build:dist-version-matches-source',
+                ok: false,
+                message: `dist/shared/version.js ships CLI_VERSION ${result.dist} but source ${result.source} is in src/shared/version.ts; run \`pnpm build\` to refresh dist/`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: 'build:dist-version-matches-source',
+                ok: false,
+                message: `dist version check failed: ${getErrorMessage(error)}`
+            }];
+    }
+}
+export const check = {
+    name: 'dist-source-version',
+    run
+};

package/dist/services/doctor/doctor-service/checks/gateguard-conflict.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Check: gateguard-fact-force hook does not intercept `.peaks/`
+ * writes (`integration:gateguard-peaks-conflict`).
+ *
+ * 2026-06-10 — the `gateguard-fact-force` hook is a third-party
+ * PreToolUse hook (NOT peaks-loop) that fires on Edit/Write and
+ * demands a 4-fact questionnaire before allowing the edit. When
+ * the LLM is in a peaks-qa flow and edits
+ * `.peaks/_runtime/<sid>/qa/requests/*.md`, the questionnaire
+ * demands facts that do not apply. We warn when the hook is
+ * installed and no `.peaks/**` skip is configured.
+ *
+ * Probing is split out of the check so the check itself stays a
+ * pure mapping over `GateguardProbeResult`. Tests inject the probe
+ * to keep `~/.claude/settings.json` from leaking into fixtures.
+ */
+import type { DoctorCheckPlugin, GateguardHookLocation, GateguardProbeResult } from '../types.js';
+/**
+ * Pure mapping over a `GateguardProbeResult`. Exported so tests
+ * can drive the entry extraction without monkey-patching
+ * `~/.claude/settings.json`.
+ */
+export declare function collectGateguardEntries(probe: GateguardProbeResult): GateguardHookLocation[];
+export declare const check: DoctorCheckPlugin;