peaks-loop 4.0.11 → 4.0.13

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 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`):
+- New `gate-strict-tag-format` step inserted after `Checkout` (publish.yml lines 104-130). Runs `git describe --tags --exact-match HEAD` and validates against `^v[0-9]+\.[0-9]+\.[0-9]+$`; rejects `v1` / `v4.0` / `v4.0.11-rc1` / `v4.0.11+sha` shapes with `::error title=strict-tag-format::`.
+- Drift guard: `tests/unit/publish-tag-strict.test.ts` (4 cases).
+
+**PreToolUse:Bash hook JSON output validation** (slice 2, commit `eb13e44c`):
+- Regression fix for the 2026-07-27 root cause. `.claude/settings.json` line 14 + `src/services/skills/hooks-settings-service.ts:86` both now append ` --json` to the `peaks gate enforce` hook command.
+- Drift guard: `tests/unit/hooks/gate-enforce-template-json-flag.test.ts` (3 cases).
+- PRD mis-reference correction noted: the actual hook template owner is `hooks-settings-service.ts`, not `claude-settings-template.ts` (the latter carries `peaks code gate-step-08`, a different hook path).
+
+**Session-overload signal index** (slice 3, commit `6ef12bde`):
+- New `skills/peaks-code/references/session-overload-signal-index.md` (60 lines): 7-signal lookup table (prompt size / auto-compact zone / sub-agent dispatch guard / statusline compact bar / in-flight batch deferral / compact stalled / sub-agent heartbeat) with thresholds + files + LLM actions + decision flowchart.
+- SKILL.md Step N+2 section gets a 1-line "See also" pointer (+141 bytes; under 30000 cap).
+- Codifies red line: LLM MUST NOT re-ask user about cost/length/context (cite `references/job-loop.md:59` red line #2).
+
+**active-skill.json → sid-scoped lease projection** (slice 4, 3 sub-slices):
+- Slice 4-A (`dc350c2c`): `skill-presence-service.ts` write path removed; `presence-marker-detector.ts` deprecated-constant comments added.
+- Slice 4-B (`7699f70f`): `skill-statusline-service.ts` `readPresenceReadOnly` rewritten to canonical-only (drops `legacyPresence: true`, enumerates `listPresenceLeases`, deletes `PRESENCE_FILE` / `PRESENCE_FILE_LEGACY`). Fixes the "new session statusline empty" issue (root cause: outerSessionId drift between session.json and the global single-slot file).
+- Slice 4-C (`1b08a62c`): doctor / sc / migration / hooks / skills / reconcile-command all migrated to canonical lease reads. New `STALE_SINGLE_SLOT_FILES` workspace-layout check surfaces orphan `.peaks/_runtime/active-skill.json` as a "stale single-slot presence" diagnostic (not an error). Drift guard: `tests/unit/workspace/active-skill-json-cleanup.test.ts` (3 cases).
+- Multi-session on one project is now safe (each session writes its own `presence-<callerId>.json` under `.peaks/_runtime/<sid>/presence-index/`; the deprecated single-slot global file no longer races).
+
+**Orchestrator-can-do probe CLI** (slice 5, commit `52736c82`):
+- New `peaks code orchestrator-can-do --slice-spec <text> --json` command (the 2026-08-05 lesson converted into a downstream-inheritable CLI). Evaluates 4 boundary questions (source code? sub-agent available? requires user decision? context sustainable?) and returns `{ canDoInSession, blockers, warnings, suggestions, contextRatio, subAgentAvailable }`.
+- SKILL.md gains a Step 0.51 paragraph pointing at it (LLM must run this probe before deciding to push a slice to the next session).
+- 17 unit tests cover all 4 boundary branches.
+- Anti-fake-green pattern: any future orchestrator capability judgment MUST call this CLI rather than re-derive the 4-question matrix from intuition.
+
+**Lockstep bump.** peaks-loop-shared `0.0.41 → 0.0.42` (CLI_VERSION re-stamped to 4.0.12); peaks-loop-mut `0.1.14 → 0.1.15`; peaks-loop-shared-channel `0.0.18 → 0.0.19`.
+
 ## 4.0.11 — 2026-08-05 (BDD test-style + statusline bugs)
 
 **BDD given-when-then test style** (rid-2026-08-05-bdd-test-style, 5 slice / 19 commit):

package/dist/cli/commands/code-commands.js

@@ -26,6 +26,7 @@ import { registerCodeRunCommand } from './code-run-command.js';
 import { registerCodeModeGateCommands } from './code-mode-gate-commands.js';
 import { registerCodeJobShapeCommands } from './code-job-shape-commands.js';
 import { registerCodeRuntimeCommands } from './code-runtime-commands.js';
+import { registerCodeOrchestratorCanDoCommand } from './code-orchestrator-can-do.js';
 const STEP_ORDER = [
     'load-memory',
     'standards-preflight',
@@ -114,5 +115,6 @@ export function registerCodeCommands(program, io) {
     registerCodeModeGateCommands(code, io);
     registerCodeJobShapeCommands(code, io);
     registerCodeRuntimeCommands(code, io);
+    registerCodeOrchestratorCanDoCommand(code, io);
     registerCodeRunCommand(code, io);
 }

package/dist/cli/commands/code-orchestrator-can-do.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Slice 2026-08-05-orchestrator-can-do-probe — CLI shim for
+ * `peaks code orchestrator-can-do`.
+ *
+ * Thin entry point that wires the `orchestrator-can-do` subcommand
+ * to the parent `code` command. The actual probe logic lives in
+ * `../../services/code/orchestrator-can-do.ts`.
+ *
+ * Encodes the 2026-08-05 lesson (`.peaks/memory/2026-08-05-peaks-code-
+ * orchestrator-capability-misjudgment.md`) — the peaks-code orchestrator
+ * MUST delegate source-code changes via sub-agent dispatch, not via
+ * direct Edit/Write. The probe returns a structured verdict so the LLM
+ * does not need to vibes-call "can this slice run in the current session".
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodeOrchestratorCanDoCommand(code: Command, io: ProgramIO): void;

package/dist/cli/commands/code-orchestrator-can-do.js

@@ -0,0 +1,75 @@
+/**
+ * Slice 2026-08-05-orchestrator-can-do-probe — CLI shim for
+ * `peaks code orchestrator-can-do`.
+ *
+ * Thin entry point that wires the `orchestrator-can-do` subcommand
+ * to the parent `code` command. The actual probe logic lives in
+ * `../../services/code/orchestrator-can-do.ts`.
+ *
+ * Encodes the 2026-08-05 lesson (`.peaks/memory/2026-08-05-peaks-code-
+ * orchestrator-capability-misjudgment.md`) — the peaks-code orchestrator
+ * MUST delegate source-code changes via sub-agent dispatch, not via
+ * direct Edit/Write. The probe returns a structured verdict so the LLM
+ * does not need to vibes-call "can this slice run in the current session".
+ */
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { evaluateOrchestratorCanDo, OrchestratorCanDoError, ORCHESTRATOR_PRECOMPACT_RATIO, ORCHESTRATOR_REDLINE_RATIO, } from '../../services/code/orchestrator-can-do.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+export function registerCodeOrchestratorCanDoCommand(code, io) {
+    addJsonOption(code
+        .command('orchestrator-can-do')
+        .description('2026-08-05 lesson: probe whether the LLM orchestrator can execute a slice in the ' +
+        'current session. Evaluates 4 boundary questions (source-code touched? sub-agent ' +
+        'available? requires user decision? context sustainable?) and returns a structured ' +
+        'verdict with canDoInSession, blockers, warnings, and concrete next-action ' +
+        'suggestions. Default to canDoInSession=true unless hard blockers are present; ' +
+        'sub-agent dispatch (`peaks sub-agent dispatch rd`) is the canonical delegation path ' +
+        'for source-code changes.')
+        .requiredOption('--slice-spec <text>', 'short description of the slice (e.g. "modify src/services/foo.ts")')
+        .option('--project <path>', 'target project root (default: findProjectRoot(cwd))')
+        .option('--peaks-bin <path>', 'peaks binary path (test seam; default: peaks on PATH)')).action(async (opts) => {
+        try {
+            const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const peaksBin = opts.peaksBin ?? 'peaks';
+            const result = await evaluateOrchestratorCanDo({
+                sliceSpec: opts.sliceSpec,
+                projectRoot,
+                probeSubAgentAvailable: () => probeSubAgentAvailableWithBin(projectRoot, peaksBin),
+                probeContextRatio: () => probeContextRatioWithBin(projectRoot, peaksBin),
+            });
+            printResult(io, ok('code.orchestrator-can-do', result, [...result.warnings], [...result.suggestions, ...summaryLines(result)]), opts.json);
+            if (!result.canDoInSession)
+                process.exitCode = 1;
+        }
+        catch (err) {
+            if (err instanceof OrchestratorCanDoError) {
+                printResult(io, fail('code.orchestrator-can-do', err.code, err.message, null, [
+                    'Pass --slice-spec <text> describing what the slice should change',
+                ]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('code.orchestrator-can-do', 'PROBE_FAILED', getErrorMessage(err), null, [
+                'Verify --slice-spec is non-empty and --project is a valid path',
+            ]), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}
+function summaryLines(result) {
+    const lines = [];
+    lines.push(`verdict: ${result.canDoInSession ? 'canDoInSession=true' : 'canDoInSession=false (blockers present)'}; ` +
+        `q1=src[${result.q1SourceCodeTouched ? 'Y' : 'N'}] q2=subagent[${result.q2SubAgentAvailable ? 'Y' : 'N'}] ` +
+        `q3=user-decision[${result.q3RequiresUserDecision ? 'Y' : 'N'}] q4=ratio=${result.contextRatio.toFixed(2)} ` +
+        `(red-line ${ORCHESTRATOR_REDLINE_RATIO} / pre-compact ${ORCHESTRATOR_PRECOMPACT_RATIO})`);
+    return lines;
+}
+async function probeSubAgentAvailableWithBin(projectRoot, peaksBin) {
+    const { probeSubAgentAvailable } = await import('../../services/code/orchestrator-can-do.js');
+    return probeSubAgentAvailable(projectRoot, peaksBin);
+}
+async function probeContextRatioWithBin(projectRoot, peaksBin) {
+    const { probeContextRatio } = await import('../../services/code/orchestrator-can-do.js');
+    return probeContextRatio(projectRoot, peaksBin);
+}

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/workspace/reconcile-command.js

@@ -26,9 +26,12 @@ export function registerWorkspaceReconcileCommand(workspace, io) {
         'By default (no --apply) the command performs four actions:\n' +
         '  1. Migrates legacy runtime files into .peaks/_runtime/: ' +
         '.peaks/.session.json -> .peaks/_runtime/session.json, ' +
-        '.peaks/.active-skill.json -> .peaks/_runtime/active-skill.json, ' +
         '.peaks/sop-state/ -> .peaks/_runtime/sop-state/ ' +
-        '(idempotent; no-op if already on the new layout).\n' +
+        '(idempotent; no-op if already on the new layout). ' +
+        'Single-slot presence files (.peaks/.active-skill.json and ' +
+        '.peaks/_runtime/active-skill.json) are no longer migrated; ' +
+        'they were removed in slice 4.0.11 and should be deleted ' +
+        'manually if present.\n' +
         '  2. Re-points .peaks/_runtime/session.json to the canonical session ' +
         'using a 4-tier heuristic: active-skill binding -> latest session.json mtime -> ' +
         'latest any-file mtime -> dir-name sort.\n' +

package/dist/services/code/orchestrator-can-do.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Slice 2026-08-05-orchestrator-can-do-probe — service layer for
+ * `peaks code orchestrator-can-do`.
+ *
+ * Encodes the 2026-08-05 lesson (`.peaks/memory/2026-08-05-peaks-code-
+ * orchestrator-capability-misjudgment.md`): the peaks-code orchestrator
+ * MUST NOT Edit/Write `src/` files directly, but MUST delegate via
+ * `peaks sub-agent dispatch`. The decision "can this slice run in the
+ * current session" must be a structured probe — not a vibes call.
+ *
+ * The probe answers 4 boundary questions:
+ *   Q1 — Is the change to source code? (keywords: src/, *.ts, *.tsx,
+ *        *.js, package.json, tsconfig, workflows/). If yes → NOT a
+ *        blocker; orchestrator delegates to sub-agent.
+ *   Q2 — Can a sub-agent be dispatched? (probe `peaks sub-agent
+ *        dispatch --role rd --help`). If no → blocker.
+ *   Q3 — Does the slice require user decisions? (keywords: design,
+ *        decide, ?, 选择, 决定). If yes → soft warning, NOT a blocker
+ *        (the LLM should AskUserQuestion, which is cheap).
+ *   Q4 — Is context usage sustainable? (probe `peaks code context-now
+ *        --json`). ratio ≥ 0.95 → blocker (red-line); ≥ 0.85 →
+ *        blocker (auto-compact-now).
+ *
+ * Decision rule:
+ *   canDoInSession === (blockers.length === 0)
+ *
+ * Concrete suggestion when canDoInSession=true and slice touches
+ * source code:
+ *   `peaks sub-agent dispatch rd --prompt "<slice-spec>" --request-id
+ *   <rid> --project . --batch-id <uuid>`
+ *
+ * Pure-function module. The CLI shim (code-orchestrator-can-do.ts)
+ * adapts the envelope into the program's `ResultEnvelope<T>` shape.
+ */
+/** Slice 2026-08-05-orchestrator-can-do-probe: red-line threshold. */
+export declare const ORCHESTRATOR_REDLINE_RATIO = 0.95;
+/** Slice 2026-08-05-orchestrator-can-do-probe: pre-compact threshold. */
+export declare const ORCHESTRATOR_PRECOMPACT_RATIO = 0.85;
+/** Source-code keywords that signal "do NOT Edit/Write directly". */
+export declare const SOURCE_CODE_KEYWORDS: readonly string[];
+/** Decision-marker keywords that signal "needs user AskUserQuestion". */
+export declare const DECISION_KEYWORDS: readonly string[];
+export interface ContextProbe {
+    /** 0.0–1.0; ≥0.85 = pre-compact; ≥0.95 = red-line. */
+    readonly ratio: number;
+    /** Source tag from `peaks code context-now`. */
+    readonly source: string;
+}
+export interface OrchestratorCanDoInput {
+    readonly sliceSpec: string;
+    readonly projectRoot: string;
+    /**
+     * Test seam — caller injects probe results. Production CLI builds
+     * these via `probeSubAgentAvailable` + `probeContextRatio`. When the
+     * test seam is set, the CLI's actual probes are skipped.
+     */
+    readonly probeSubAgentAvailable?: () => Promise<boolean>;
+    readonly probeContextRatio?: () => Promise<ContextProbe>;
+}
+export interface OrchestratorCanDoResult {
+    /** canDoInSession === (blockers.length === 0). */
+    readonly canDoInSession: boolean;
+    readonly blockers: readonly string[];
+    readonly warnings: readonly string[];
+    readonly suggestions: readonly string[];
+    readonly contextRatio: number;
+    readonly subAgentAvailable: boolean;
+    /** Diagnostic — which of the 4 boundary questions fired. */
+    readonly q1SourceCodeTouched: boolean;
+    readonly q2SubAgentAvailable: boolean;
+    readonly q3RequiresUserDecision: boolean;
+    readonly q4ContextRatio: number;
+}
+export declare class OrchestratorCanDoError extends Error {
+    readonly code: 'MISSING_SLICE_SPEC' | 'PROBE_FAILED';
+    constructor(message: string, code: 'MISSING_SLICE_SPEC' | 'PROBE_FAILED');
+}
+/**
+ * Q1: does the slice touch source code? Pure keyword scan over
+ * the slice-spec string. Case-insensitive substring match.
+ */
+export declare function detectSourceCodeTouched(sliceSpec: string): boolean;
+/**
+ * Q3: does the slice require user decisions? Pure keyword scan
+ * over the slice-spec string.
+ */
+export declare function detectRequiresUserDecision(sliceSpec: string): boolean;
+/**
+ * Q2: probe `peaks sub-agent dispatch --role rd --help`. Returns
+ * true when the subprocess exits 0. Resolves to false on spawn
+ * failure or non-zero exit.
+ */
+export declare function probeSubAgentAvailable(projectRoot: string, peaksBin?: string): Promise<boolean>;
+/**
+ * Q4: probe `peaks code context-now --json`. Parses the data.ratio
+ * field. Falls back to {ratio: 0, source: 'unavailable'} when the
+ * subprocess fails or returns malformed JSON.
+ */
+export declare function probeContextRatio(projectRoot: string, peaksBin?: string): Promise<ContextProbe>;
+/**
+ * Build the structured OrchestratorCanDoResult. Pure over the 4 Q
+ * signals + sliceSpec. Decision rule is: canDoInSession === !blockers.
+ */
+export declare function buildOrchestratorCanDoResult(input: OrchestratorCanDoInput, signals: {
+    q1SourceCodeTouched: boolean;
+    q2SubAgentAvailable: boolean;
+    q3RequiresUserDecision: boolean;
+    q4ContextRatio: number;
+}): OrchestratorCanDoResult;
+/**
+ * Evaluate a slice-spec end-to-end. Probes Q2/Q4 via subprocess
+ * (overridable via test seams in `input`). Q1/Q3 are pure.
+ */
+export declare function evaluateOrchestratorCanDo(input: OrchestratorCanDoInput): Promise<OrchestratorCanDoResult>;

package/dist/services/code/orchestrator-can-do.js

@@ -0,0 +1,205 @@
+/**
+ * Slice 2026-08-05-orchestrator-can-do-probe — service layer for
+ * `peaks code orchestrator-can-do`.
+ *
+ * Encodes the 2026-08-05 lesson (`.peaks/memory/2026-08-05-peaks-code-
+ * orchestrator-capability-misjudgment.md`): the peaks-code orchestrator
+ * MUST NOT Edit/Write `src/` files directly, but MUST delegate via
+ * `peaks sub-agent dispatch`. The decision "can this slice run in the
+ * current session" must be a structured probe — not a vibes call.
+ *
+ * The probe answers 4 boundary questions:
+ *   Q1 — Is the change to source code? (keywords: src/, *.ts, *.tsx,
+ *        *.js, package.json, tsconfig, workflows/). If yes → NOT a
+ *        blocker; orchestrator delegates to sub-agent.
+ *   Q2 — Can a sub-agent be dispatched? (probe `peaks sub-agent
+ *        dispatch --role rd --help`). If no → blocker.
+ *   Q3 — Does the slice require user decisions? (keywords: design,
+ *        decide, ?, 选择, 决定). If yes → soft warning, NOT a blocker
+ *        (the LLM should AskUserQuestion, which is cheap).
+ *   Q4 — Is context usage sustainable? (probe `peaks code context-now
+ *        --json`). ratio ≥ 0.95 → blocker (red-line); ≥ 0.85 →
+ *        blocker (auto-compact-now).
+ *
+ * Decision rule:
+ *   canDoInSession === (blockers.length === 0)
+ *
+ * Concrete suggestion when canDoInSession=true and slice touches
+ * source code:
+ *   `peaks sub-agent dispatch rd --prompt "<slice-spec>" --request-id
+ *   <rid> --project . --batch-id <uuid>`
+ *
+ * Pure-function module. The CLI shim (code-orchestrator-can-do.ts)
+ * adapts the envelope into the program's `ResultEnvelope<T>` shape.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
+const execFileAsync = promisify(execFile);
+/** Slice 2026-08-05-orchestrator-can-do-probe: red-line threshold. */
+export const ORCHESTRATOR_REDLINE_RATIO = 0.95;
+/** Slice 2026-08-05-orchestrator-can-do-probe: pre-compact threshold. */
+export const ORCHESTRATOR_PRECOMPACT_RATIO = 0.85;
+/** Source-code keywords that signal "do NOT Edit/Write directly". */
+export const SOURCE_CODE_KEYWORDS = [
+    'src/',
+    'source/',
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    'package.json',
+    'tsconfig',
+    'workflows/',
+    '.py',
+    '.go',
+    '.rs',
+];
+/** Decision-marker keywords that signal "needs user AskUserQuestion". */
+export const DECISION_KEYWORDS = [
+    'design',
+    'decide',
+    'choose',
+    '?',
+    '选择',
+    '决定',
+    'design decision',
+    'user choice',
+];
+export class OrchestratorCanDoError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'OrchestratorCanDoError';
+    }
+}
+/**
+ * Q1: does the slice touch source code? Pure keyword scan over
+ * the slice-spec string. Case-insensitive substring match.
+ */
+export function detectSourceCodeTouched(sliceSpec) {
+    const lower = sliceSpec.toLowerCase();
+    return SOURCE_CODE_KEYWORDS.some((kw) => lower.includes(kw.toLowerCase()));
+}
+/**
+ * Q3: does the slice require user decisions? Pure keyword scan
+ * over the slice-spec string.
+ */
+export function detectRequiresUserDecision(sliceSpec) {
+    const lower = sliceSpec.toLowerCase();
+    return DECISION_KEYWORDS.some((kw) => lower.includes(kw.toLowerCase()));
+}
+/**
+ * Q2: probe `peaks sub-agent dispatch --role rd --help`. Returns
+ * true when the subprocess exits 0. Resolves to false on spawn
+ * failure or non-zero exit.
+ */
+export async function probeSubAgentAvailable(projectRoot, peaksBin = 'peaks') {
+    try {
+        await execFileAsync(peaksBin, ['sub-agent', 'dispatch', '--role', 'rd', '--help'], {
+            cwd: projectRoot,
+            timeout: 5000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Q4: probe `peaks code context-now --json`. Parses the data.ratio
+ * field. Falls back to {ratio: 0, source: 'unavailable'} when the
+ * subprocess fails or returns malformed JSON.
+ */
+export async function probeContextRatio(projectRoot, peaksBin = 'peaks') {
+    try {
+        const { stdout } = await execFileAsync(peaksBin, ['code', 'context-now', '--project', projectRoot, '--json'], {
+            cwd: projectRoot,
+            timeout: 10000,
+        });
+        const parsed = JSON.parse(stdout);
+        const ratio = typeof parsed.data?.ratio === 'number' ? parsed.data.ratio : 0;
+        const source = typeof parsed.data?.source === 'string' ? parsed.data.source : 'unavailable';
+        return { ratio, source };
+    }
+    catch {
+        return { ratio: 0, source: 'unavailable' };
+    }
+}
+/**
+ * Build the structured OrchestratorCanDoResult. Pure over the 4 Q
+ * signals + sliceSpec. Decision rule is: canDoInSession === !blockers.
+ */
+export function buildOrchestratorCanDoResult(input, signals) {
+    const blockers = [];
+    const warnings = [];
+    const suggestions = [];
+    // Q2 — sub-agent availability is a hard precondition.
+    if (!signals.q2SubAgentAvailable) {
+        blockers.push('sub-agent dispatch unavailable (peaks sub-agent dispatch --help failed)');
+        suggestions.push('verify peaks CLI is on PATH; check `peaks --version`');
+    }
+    // Q4 — context ratio gate. ≥0.95 → red-line; ≥0.85 → pre-compact.
+    if (signals.q4ContextRatio >= ORCHESTRATOR_REDLINE_RATIO) {
+        blockers.push(`context red-line (ratio=${signals.q4ContextRatio.toFixed(2)} ≥ ${ORCHESTRATOR_REDLINE_RATIO}); auto-compact now or push to next session`);
+        suggestions.push('peaks compact auto --execute');
+    }
+    else if (signals.q4ContextRatio >= ORCHESTRATOR_PRECOMPACT_RATIO) {
+        blockers.push(`context near limit (ratio=${signals.q4ContextRatio.toFixed(2)} ≥ ${ORCHESTRATOR_PRECOMPACT_RATIO}); auto-compact or push to next session`);
+        suggestions.push('peaks compact auto --execute');
+    }
+    // Q3 — user-decision keywords → soft warning, NOT a blocker. The
+    // LLM should AskUserQuestion, which is cheap.
+    if (signals.q3RequiresUserDecision) {
+        warnings.push('slice-spec contains decision keywords; AskUserQuestion before proceeding');
+    }
+    // Q1 — source-code touched is NOT a blocker. The orchestrator
+    // delegates via sub-agent dispatch.
+    if (signals.q1SourceCodeTouched && signals.q2SubAgentAvailable) {
+        const batchId = randomUUID();
+        const rid = 'rid-' + Date.now().toString(36);
+        suggestions.push(`peaks sub-agent dispatch rd --prompt "<slice-spec>" --request-id ${rid} --project ${input.projectRoot} --batch-id ${batchId}`);
+    }
+    // When canDoInSession=true and there's no source code touched,
+    // surface a generic "do it" suggestion.
+    const canDoInSession = blockers.length === 0;
+    if (canDoInSession && !signals.q1SourceCodeTouched) {
+        suggestions.push(`non-source-code slice; orchestrator may handle in-session (e.g. via Write/Edit tools or directly)`);
+    }
+    return {
+        canDoInSession,
+        blockers,
+        warnings,
+        suggestions,
+        contextRatio: signals.q4ContextRatio,
+        subAgentAvailable: signals.q2SubAgentAvailable,
+        q1SourceCodeTouched: signals.q1SourceCodeTouched,
+        q2SubAgentAvailable: signals.q2SubAgentAvailable,
+        q3RequiresUserDecision: signals.q3RequiresUserDecision,
+        q4ContextRatio: signals.q4ContextRatio,
+    };
+}
+/**
+ * Evaluate a slice-spec end-to-end. Probes Q2/Q4 via subprocess
+ * (overridable via test seams in `input`). Q1/Q3 are pure.
+ */
+export async function evaluateOrchestratorCanDo(input) {
+    if (!input.sliceSpec || input.sliceSpec.trim().length === 0) {
+        throw new OrchestratorCanDoError('--slice-spec is required', 'MISSING_SLICE_SPEC');
+    }
+    const q1SourceCodeTouched = detectSourceCodeTouched(input.sliceSpec);
+    const q3RequiresUserDecision = detectRequiresUserDecision(input.sliceSpec);
+    const probeSubAgent = input.probeSubAgentAvailable ?? (() => probeSubAgentAvailable(input.projectRoot));
+    const probeContext = input.probeContextRatio ?? (() => probeContextRatio(input.projectRoot));
+    const [subAgentAvailable, ctxProbe] = await Promise.all([
+        probeSubAgent(),
+        probeContext(),
+    ]);
+    return buildOrchestratorCanDoResult(input, {
+        q1SourceCodeTouched,
+        q2SubAgentAvailable: subAgentAvailable,
+        q3RequiresUserDecision,
+        q4ContextRatio: ctxProbe.ratio,
+    });
+}

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;