peaks-loop 4.0.36 → 4.0.38

package/dist/services/context/build-dispatch-system-prompt.js

@@ -93,6 +93,47 @@ export const REPORT_CAP_BLOCK = `## Final report cap (mandatory)
 
 Your FINAL report to the parent MUST be ≤ 40 lines and ≤ 2 KB. Write any longer detail into the artifact file you already own — the parent can \`Read\` that file for the full detail, so nothing is lost. The report itself MUST still carry: changed files (one line each), the exact commands you ran, pass/fail counts, tsc status, and any blocker. Do NOT paste file contents, full tool output, or logs into the report.
 `;
+/**
+ * Slice 2026-09-10-fact-force-gate-adaptation: stand IN FRONT of an external
+ * `PreToolUse` gate instead of explaining its denial after the fact.
+ *
+ * ECC (a third-party plugin under `~/.claude/plugins/`) registers
+ * `gateguard-fact-force.js` on `Edit|Write|MultiEdit`. It denies the first
+ * edit of a file whose facts the agent has not established, and its four-item
+ * message never says two things the agent needs: that the file must be READ
+ * first, and that the edit was NOT applied. Measured failure mode
+ * (session 2026-09-10-session-528a63): the sub-agent reads the denial as
+ * "the tool is broken" and abandons the edit.
+ *
+ * So the block below leads with the STANDING RULE (read before you edit) and
+ * names the paths it covers, and mentions the denial only as the consequence
+ * of skipping that rule. A sub-agent that has never seen the gate can read
+ * this once and never trip it.
+ *
+ * The gate itself is untouched: peaks-loop adapts to it, and does NOT disable,
+ * bypass, or re-implement it. Nor is `ECC_GATEGUARD=off` part of this.
+ *
+ * Always rendered — no opt-out flag and no role split. Every role edits files
+ * outside `.peaks/**`, and only sub-agent #1 of a session sees a denial (the
+ * gate fires once per file), so a role-scoped or opt-in block would leave the
+ * rest of the fleet untold. It joins the stable boilerplate prefix: constant
+ * bytes for every dispatch, prompt-cache friendly.
+ *
+ * The `.peaks/**` exemption is real and pre-dates this slice — peaks-loop
+ * materialises `.claude/settings.local.json` so the gate skips `.peaks/**`
+ * (slice 2.0.1-bug3-fact-forcing-bypass; see
+ * `src/cli/commands/workspace/init-command.ts`).
+ */
+export const FACT_FORCE_GATE_BLOCK = `## Read before you edit (Fact-Forcing Gate)
+
+Read a file BEFORE your first \`Edit\` / \`Write\` / \`MultiEdit\` on it — the normal way to work here, not an optional step. It applies to every path OUTSIDE \`.peaks/**\` (source, tests, docs, config); \`.peaks/**\` writes are exempt.
+
+Skipping that read trips a \`PreToolUse\` plugin gate (ECC's "Fact-Forcing Gate"), which denies the edit. A denial is NOT a failure and the tool is NOT broken — your edit was NOT applied. Read the file, state the four facts the gate asks for (importers, affected API, data schemas if any, the user's verbatim instruction), then retry the same operation. Do not switch tools, do not give up, do not re-attempt blindly.
+`;
+/** Always-on renderer for {@link FACT_FORCE_GATE_BLOCK}. */
+export function renderFactForceGateBlock() {
+    return `${FACT_FORCE_GATE_BLOCK}\n`;
+}
 /**
  * Compose the system-prompt body for a sub-agent dispatch.
  *
@@ -104,7 +145,7 @@ Your FINAL report to the parent MUST be ≤ 40 lines and ≤ 2 KB. Write any lon
  * Byte-identical degradation contract (slice 2026-07-22-orchestrator-memory-preflight
  * controller brief): when the memory block is unavailable, the composed body is
  * exactly `formatTestToolDetection() + "\n\n" + L1 + "\n" + LIFECYCLE +
- * "\n" + REPORT_CAP + "\n" + contextBlock + taskBody`, so the unavailable
+ * "\n" + REPORT_CAP + "\n" + FACT_FORCE_GATE + "\n" + contextBlock + taskBody`, so the unavailable
  * branch MUST return `taskBody` unwrapped (NOT a `# title\n\n` wrap).
  * (REPORT_CAP joined the stable prefix in slice
  * 2026-09-10-context-audit-and-discipline, Slice C.)
@@ -128,15 +169,17 @@ export function buildDispatchSystemPrompt(input) {
     // for every role — the composer owns the injection so callers MUST NOT
     // prepend `formatTestToolDetection()` themselves (double injection).
     const testToolText = `${formatTestToolDetection()}\n\n`;
+    // 2026-09-10-fact-force-gate-adaptation: always-on, both branches.
+    const factForceGateText = renderFactForceGateBlock();
     const contextBlock = renderContextBlock(contextProbe ?? null);
     const codegraphText = renderCodegraphBlock(codegraphBlock);
     const projectStackText = renderProjectStackBlock(projectStackBlock);
     const freshContextText = renderFreshContextBlock(freshContextBlock);
     const capsuleText = renderCapsulePointer(capsule);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${memoryBlock.block}\n## Task\n${taskBody}`;
+        return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${factForceGateText}${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${memoryBlock.block}\n## Task\n${taskBody}`;
     }
-    return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${taskBody}`;
+    return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${factForceGateText}${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${taskBody}`;
 }
 /**
  * Slice 2026-09-10-dispatch-token-and-swarm §4 — session capsule pointer.
@@ -294,6 +337,15 @@ export const BINDING_RULE_TOKENS = [
     'changed files (one line each)',
     'pass/fail counts',
     'tsc status',
+    // fact-forcing gate (slice 2026-09-10-fact-force-gate-adaptation)
+    '## Read before you edit (Fact-Forcing Gate)',
+    'Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on it',
+    'every path OUTSIDE `.peaks/**`',
+    '`PreToolUse` plugin gate',
+    'A denial is NOT a failure and the tool is NOT broken',
+    'your edit was NOT applied',
+    'retry the same operation',
+    'do not re-attempt blindly',
     // test scope — ONE unified block, byte-identical for EVERY role
     '## Test Tool Detection (mandatory)',
     '`package.json#scripts.test`',

package/dist/services/context/context-audit-hint.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Slice 2026-09-10-three-fixes (Slice 2) — proactive context-consumer hint.
+ *
+ * `peaks code context-audit` (Slice A, same day) already reports WHAT fills
+ * the window, but only when someone remembers to run it. The Step 0.8
+ * PreToolUse gate (`peaks code gate-step-08`) runs before every Bash call, so
+ * it is the natural place to surface the single largest consumer — provided
+ * that costs nothing measurable.
+ *
+ * Cost contract (the whole point of this module):
+ *   - The ratio probe is the cheap, adapter-driven `readContextPercent`
+ *     (env-var → statusline file read; the transcript fallback is a
+ *     bounded backwards scan, never a whole-file read).
+ *   - The expensive part — the transcript scan inside `auditContext` — runs
+ *     at most ONCE per TTL window. Its result is cached under
+ *     `.peaks/_runtime/<sid>/context-audit-hint.json`; a fresh entry
+ *     short-circuits the scan entirely.
+ *   - Every failure is fail-soft: a missing/corrupt cache, an unavailable
+ *     transcript, an adapter that cannot locate one — all yield `null`
+ *     (emit nothing). The gate never blocks and never gains more than ONE
+ *     line.
+ *
+ * The cache deliberately records FAILED audits too (with `available:false`),
+ * so a broken transcript cannot turn every Bash call back into a scan.
+ */
+import { type ContextAuditInput, type ContextAuditResult } from './context-audit.js';
+/** Only surface a hint once the window is this full. */
+export declare const CONTEXT_HINT_RATIO_THRESHOLD = 0.7;
+/** Minimum cache TTL — a fresh entry must skip the transcript scan. */
+export declare const CONTEXT_HINT_CACHE_TTL_MS: number;
+/** Per-session cache file name (under `.peaks/_runtime/<sid>/`). */
+export declare const CONTEXT_HINT_CACHE_FILE_NAME = "context-audit-hint.json";
+/** Cached top-consumer snapshot — one audit result, no transcript content. */
+export interface ContextHintCacheEntry {
+    /** Epoch ms when the audit ran (TTL anchor). */
+    readonly cachedAt: number;
+    /** False when the audit could not read the transcript. */
+    readonly available: boolean;
+    /** Ratio observed when the audit ran (informational). */
+    readonly ratio: number;
+    readonly tool: string | null;
+    readonly key: string | null;
+    readonly bytes: number;
+    readonly pctOfTotal: number;
+    readonly count: number;
+}
+export interface ContextAuditHintInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly outerSessionId?: string | null | undefined;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    /** Clock override (test seam). */
+    readonly nowMs?: number | undefined;
+    /** Cache path override (test seam; default is per-session under `_runtime`). */
+    readonly cachePath?: string | undefined;
+    /** Ratio probe override (test seam). Returns null when unknown. */
+    readonly probeRatio?: (() => number | null) | undefined;
+    /** Audit runner override (test seam; lets a test count scans). */
+    readonly runAudit?: ((input: ContextAuditInput) => ContextAuditResult) | undefined;
+}
+/**
+ * `<projectRoot>/.peaks/_runtime/<sid>/context/context-audit-hint.json`
+ * (gitignored). The `context/` bucket mirrors the existing `<sid>/txt/`
+ * convention so session-id artifacts stay under `.peaks/_runtime/<sid>/`.
+ */
+export declare function contextHintCachePath(projectRoot: string, sessionId: string): string;
+/**
+ * The single line the gate may append. Names ONE consumer — the largest by
+ * tool-result bytes — plus the share and call count that justify the number.
+ */
+export declare function formatContextHintLine(entry: ContextHintCacheEntry): string;
+/**
+ * Build the ONE optional hint line for the Step 0.8 gate.
+ *
+ * Returns `null` when: the ratio is unknown or below 0.70, the cache (fresh)
+ * says the audit was unavailable, the fresh audit found no groups, or
+ * anything throws. Never throws, never blocks.
+ */
+export declare function buildContextAuditHint(input: ContextAuditHintInput): string | null;

package/dist/services/context/context-audit-hint.js

@@ -0,0 +1,150 @@
+/**
+ * Slice 2026-09-10-three-fixes (Slice 2) — proactive context-consumer hint.
+ *
+ * `peaks code context-audit` (Slice A, same day) already reports WHAT fills
+ * the window, but only when someone remembers to run it. The Step 0.8
+ * PreToolUse gate (`peaks code gate-step-08`) runs before every Bash call, so
+ * it is the natural place to surface the single largest consumer — provided
+ * that costs nothing measurable.
+ *
+ * Cost contract (the whole point of this module):
+ *   - The ratio probe is the cheap, adapter-driven `readContextPercent`
+ *     (env-var → statusline file read; the transcript fallback is a
+ *     bounded backwards scan, never a whole-file read).
+ *   - The expensive part — the transcript scan inside `auditContext` — runs
+ *     at most ONCE per TTL window. Its result is cached under
+ *     `.peaks/_runtime/<sid>/context-audit-hint.json`; a fresh entry
+ *     short-circuits the scan entirely.
+ *   - Every failure is fail-soft: a missing/corrupt cache, an unavailable
+ *     transcript, an adapter that cannot locate one — all yield `null`
+ *     (emit nothing). The gate never blocks and never gains more than ONE
+ *     line.
+ *
+ * The cache deliberately records FAILED audits too (with `available:false`),
+ * so a broken transcript cannot turn every Bash call back into a scan.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteJson } from '../ide/shared/atomic-json.js';
+import { readContextPercent } from './auto-compact-reader.js';
+import { auditContext } from './context-audit.js';
+/** Only surface a hint once the window is this full. */
+export const CONTEXT_HINT_RATIO_THRESHOLD = 0.7;
+/** Minimum cache TTL — a fresh entry must skip the transcript scan. */
+export const CONTEXT_HINT_CACHE_TTL_MS = 5 * 60 * 1000;
+/** Per-session cache file name (under `.peaks/_runtime/<sid>/`). */
+export const CONTEXT_HINT_CACHE_FILE_NAME = 'context-audit-hint.json';
+/**
+ * `<projectRoot>/.peaks/_runtime/<sid>/context/context-audit-hint.json`
+ * (gitignored). The `context/` bucket mirrors the existing `<sid>/txt/`
+ * convention so session-id artifacts stay under `.peaks/_runtime/<sid>/`.
+ */
+export function contextHintCachePath(projectRoot, sessionId) {
+    const safeSessionId = sessionId.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '');
+    return join(projectRoot, '.peaks', '_runtime', safeSessionId.length > 0 ? safeSessionId : 'unknown', 'context', CONTEXT_HINT_CACHE_FILE_NAME);
+}
+/**
+ * The single line the gate may append. Names ONE consumer — the largest by
+ * tool-result bytes — plus the share and call count that justify the number.
+ */
+export function formatContextHintLine(entry) {
+    const ratioPct = (entry.ratio * 100).toFixed(1);
+    const sharePct = entry.pctOfTotal.toFixed(1);
+    const calls = entry.count === 1 ? '1 call' : `${entry.count} calls`;
+    return `Context ${ratioPct}% used — top consumer: ${entry.tool} \`${entry.key}\` (${sharePct}% of tool-result bytes, ${calls}). Run \`peaks code context-audit\` for the full breakdown.`;
+}
+function readCache(cachePath) {
+    if (!existsSync(cachePath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath, 'utf8'));
+        if (typeof parsed.cachedAt !== 'number' || !Number.isFinite(parsed.cachedAt))
+            return null;
+        if (typeof parsed.available !== 'boolean')
+            return null;
+        return {
+            cachedAt: parsed.cachedAt,
+            available: parsed.available,
+            ratio: typeof parsed.ratio === 'number' && Number.isFinite(parsed.ratio) ? parsed.ratio : 0,
+            tool: typeof parsed.tool === 'string' ? parsed.tool : null,
+            key: typeof parsed.key === 'string' ? parsed.key : null,
+            bytes: typeof parsed.bytes === 'number' && Number.isFinite(parsed.bytes) ? parsed.bytes : 0,
+            pctOfTotal: typeof parsed.pctOfTotal === 'number' && Number.isFinite(parsed.pctOfTotal) ? parsed.pctOfTotal : 0,
+            count: typeof parsed.count === 'number' && Number.isFinite(parsed.count) ? parsed.count : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Never throws: an unavailable ratio probe degrades to "no hint". */
+function probeRatioSafe(input) {
+    if (input.probeRatio !== undefined) {
+        try {
+            const value = input.probeRatio();
+            return typeof value === 'number' && Number.isFinite(value) ? value : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        const probe = readContextPercent({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            outerSessionId: input.outerSessionId ?? undefined,
+            env: input.env ?? process.env,
+        });
+        return Number.isFinite(probe.ratio) ? probe.ratio : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the ONE optional hint line for the Step 0.8 gate.
+ *
+ * Returns `null` when: the ratio is unknown or below 0.70, the cache (fresh)
+ * says the audit was unavailable, the fresh audit found no groups, or
+ * anything throws. Never throws, never blocks.
+ */
+export function buildContextAuditHint(input) {
+    try {
+        const nowMs = input.nowMs ?? Date.now();
+        const ratio = probeRatioSafe(input);
+        if (ratio === null || ratio < CONTEXT_HINT_RATIO_THRESHOLD)
+            return null;
+        const cachePath = input.cachePath ?? contextHintCachePath(input.projectRoot, input.sessionId);
+        const cached = readCache(cachePath);
+        // Fresh entry → the transcript scan is skipped entirely (cost guard).
+        if (cached !== null && nowMs - cached.cachedAt < CONTEXT_HINT_CACHE_TTL_MS) {
+            return cached.available && cached.tool !== null ? formatContextHintLine(cached) : null;
+        }
+        // Cache miss / stale → at most one scan per TTL window.
+        const result = (input.runAudit ?? auditContext)({
+            outerSessionId: input.outerSessionId ?? null,
+            topN: 1,
+        });
+        const top = result.available ? (result.entries[0] ?? null) : null;
+        const entry = {
+            cachedAt: nowMs,
+            available: result.available,
+            ratio,
+            tool: top?.tool ?? null,
+            key: top?.key ?? null,
+            bytes: top?.bytes ?? 0,
+            pctOfTotal: top?.pctOfTotal ?? 0,
+            count: top?.count ?? 0,
+        };
+        try {
+            atomicWriteJson(cachePath, entry);
+        }
+        catch {
+            // Fail-soft: an unwritable cache must not lose this turn's hint.
+        }
+        return top !== null ? formatContextHintLine(entry) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/services/hooks/auto-compact-hook-install.js

@@ -32,6 +32,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { resolveHookShell } from '../skills/hooks-codegate-superpowers.js';
 /**
  * Stable matcher for the auto-compact hook. Single source of truth
  * — `install` and `remove` both key off this constant so the
@@ -105,6 +106,13 @@ export function installAutoCompactHook(input) {
     if (alreadyInstalled) {
         return { action: 'already-installed', settingsPath };
     }
+    // The matcher is `Bash|Task`, so on Windows this runs on the same
+    // Git-Bash / MSYS2 shell-form path as the other peaks Bash hooks, which
+    // force-allocates a console window on every matching tool call. The
+    // entry is written only into the machine-local, gitignored
+    // `.claude/settings.local.json`, so a machine-specific `shell` cannot
+    // leak into a shared file. `undefined` on POSIX omits the key entirely.
+    const shell = resolveHookShell();
     const nextPreToolUse = [
         ...preToolUse,
         {
@@ -112,7 +120,8 @@ export function installAutoCompactHook(input) {
             hooks: [
                 {
                     type: 'command',
-                    command: AUTO_COMPACT_HOOK_COMMAND
+                    command: AUTO_COMPACT_HOOK_COMMAND,
+                    ...(shell !== undefined ? { shell } : {})
                 }
             ]
         }

package/dist/services/hooks/write-gate.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * write-gate.js — peaks Write|Edit|MultiEdit PreToolUse path gate.
+ *
+ * Slice c5-write-hook-exec-form (session 2026-09-10-session-528a63).
+ * VERBATIM RELOCATION: the predicate chain below was character-for-character
+ * the chain that used to be inlined into `claude-settings-template.ts` as a
+ * `node -e "<js>"` one-liner.
+ *
+ * Slice c5b-write-gate-polarity (same session) NARROWED the decision to match
+ * the contract `.claude/HOOKS.md` documents for this handler. The relocated
+ * chain read its eight directory names as an EXCLUSION list, so `_runtime`
+ * AND every other `.peaks/<slug>/` were allowed; it now allows only paths
+ * under `.peaks/_runtime/` and falls through on everything else. That earlier
+ * polarity also permitted a top-level `.peaks/<change-id>/` write, which
+ * `CLAUDE.md`'s hard ban forbids outright.
+ *
+ * Why it moved into a file: the inlined form was shell-dialect-coupled. Its
+ * escaping contract was defined in terms of bash reducing `\\` to `\` inside a
+ * `"..."` wrapper, which PowerShell does NOT do — so the handler could not take
+ * the platform `shell` pin its Bash siblings carry. `node <path>` has no inline
+ * payload, so there is nothing left to escape and no dialect to couple to.
+ *
+ * Why `.js` and not `.sh` (the convention for the other hook scripts here):
+ *   - `.sh` needs `bash`; on Windows that means Git Bash, so it is itself a
+ *     shell dependency and the escaping problem merely moves to the
+ *     `bash <script>` boundary.
+ *   - `node` is already a hard dependency — the previous form invoked it.
+ *   - A plain `.js` needs no compile step, so the SAME relative filename
+ *     exists in `src/` (used by `tsx` + vitest) and in `dist/` (copied by
+ *     `scripts/copy-templates.mjs`), which lets one emitted path string be
+ *     valid for both the repo and an installed consumer.
+ *
+ * Contract (`.claude/HOOKS.md`): exit 0 = allow, exit 1 = fall through to the
+ * gate — NOT a deny. Only exit 2 blocks a tool call, and this handler never
+ * returns it. This handler's job is to stay silent on the paths the gate is
+ * meant to skip.
+ *
+ * Path source: the hook payload arrives as JSON on STDIN (Claude Code's
+ * documented channel; it appends no argv). `process.argv[2]` is honoured as a
+ * fallback so a positional-arg invocation keeps working.
+ */
+
+/** First string found at any of the candidate keys of `root`. */
+function pathFrom(root) {
+  if (!root || typeof root !== 'object') return '';
+  for (const key of ['file_path', 'path', 'notebook_path']) {
+    if (typeof root[key] === 'string') return root[key];
+  }
+  return '';
+}
+
+/** Pull the candidate file path out of a parsed hook payload. */
+function candidatePath(payload) {
+  if (!payload || typeof payload !== 'object') return '';
+  return pathFrom(payload.tool_input) || pathFrom(payload);
+}
+
+/**
+ * The gate decision: allow (0) only for paths under `.peaks/_runtime/`;
+ * everything else falls through to the gate (1).
+ */
+function decide(p) {
+  return p.includes('.peaks/_runtime/') ? 0 : 1;
+}
+
+const ARGV_PATH = typeof process.argv[2] === 'string' ? process.argv[2] : '';
+
+// No stdin to read (a human running this by hand): decide on argv alone
+// instead of blocking forever waiting for an 'end' that never comes.
+if (process.stdin.isTTY) {
+  process.exit(decide(ARGV_PATH));
+}
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    // Malformed or empty payload → no path → deny, which is the same
+    // outcome the old form produced for an absent `process.argv[1]`.
+    payload = undefined;
+  }
+  process.exit(decide(candidatePath(payload) || ARGV_PATH));
+});

package/dist/services/lint/detect-eslint.d.ts

@@ -7,4 +7,6 @@ export type EslintDetectResult = {
     readonly warnings: readonly string[];
     readonly nextActions: readonly string[];
 };
+/** Named code for "npm itself could not be launched" — distinct from a registry miss. */
+export declare const NPM_PROBE_UNRESOLVED_CODE = "NPM_PROBE_UNRESOLVED";
 export declare function detectEslint(): EslintDetectResult;

package/dist/services/lint/detect-eslint.js

@@ -4,7 +4,7 @@
  * unified Gate B5 verdict.
  */
 import { spawnSync } from 'node:child_process';
-import { resolveNpxInvocation } from './npx-resolver.js';
+import { resolveNpmInvocation, resolveNpxInvocation } from './npx-resolver.js';
 import { ESLINT_PACKAGE_PINS } from './eslint-runner.js';
 const PACKAGES_TO_PROBE = [
     'eslint',
@@ -23,14 +23,23 @@ function probeNpx() {
     const probe = spawnSync(command, args, { encoding: 'utf8', env: baseEnv });
     return probe.status === 0;
 }
+/** Named code for "npm itself could not be launched" — distinct from a registry miss. */
+export const NPM_PROBE_UNRESOLVED_CODE = 'NPM_PROBE_UNRESOLVED';
 function probePackage(key) {
     const pkg = packageNameFor(key);
     const pin = ESLINT_PACKAGE_PINS[key];
-    // shell:true required on Windows because `npm` (like npx) is a `.cmd`
-    // shim; Node 22 refuses to invoke it without shell wrapper.
-    // 2026-08-06 lint-dogfood cycle-2 follow-up.
-    const result = spawnSync('npm', ['view', `${pkg}@${pin}`, 'version'], { encoding: 'utf8', shell: true });
-    return result.status === 0;
+    // 2026-09-10: `npm` on Windows is an `npm.cmd` shim, which Node >= 20 refuses
+    // to spawn at all without `shell: true` — and `shell: true` concatenates the
+    // argv unescaped (DEP0190 on every call, and any argument containing a space
+    // is split). So the shim is bypassed: `resolveNpmInvocation` resolves npm's
+    // own JS entry and this runs it through `process.execPath`. Same shape as the
+    // npx probe above and as `eslint-runner.ts`.
+    const { command, args, baseEnv } = resolveNpmInvocation(['view', `${pkg}@${pin}`, 'version']);
+    const result = spawnSync(command, args, { encoding: 'utf8', env: baseEnv });
+    return {
+        ok: result.status === 0,
+        error: result.error === undefined || result.error === null ? null : result.error.message
+    };
 }
 export function detectEslint() {
     const nextActions = [];
@@ -45,9 +54,14 @@ export function detectEslint() {
         };
     }
     for (const key of PACKAGES_TO_PROBE) {
-        if (!probePackage(key)) {
-            warnings.push(`npm registry cannot resolve ${packageNameFor(key)}@${ESLINT_PACKAGE_PINS[key]}`);
-        }
+        const probe = probePackage(key);
+        if (probe.ok)
+            continue;
+        const target = `${packageNameFor(key)}@${ESLINT_PACKAGE_PINS[key]}`;
+        warnings.push(probe.error === null
+            ? `npm registry cannot resolve ${target}`
+            : `${NPM_PROBE_UNRESOLVED_CODE}: could not launch npm to probe ${target} (${probe.error}). ` +
+                'Ensure Node.js >= 20 with its bundled npm is installed.');
     }
     if (warnings.length > 0) {
         nextActions.push('Re-run `peaks code lint --json` after npm connectivity is restored.');

package/dist/services/lint/detect-ocr-18.d.ts

@@ -7,4 +7,6 @@ export type Ocr18DetectResult = {
     readonly warnings: readonly string[];
     readonly nextActions: readonly string[];
 };
+/** Named code for "npx itself could not be launched" — distinct from "npx is absent". */
+export declare const NPX_PROBE_UNRESOLVED_CODE = "NPX_PROBE_UNRESOLVED";
 export declare function detectOcr18(): Ocr18DetectResult;

package/dist/services/lint/detect-ocr-18.js

@@ -2,22 +2,53 @@
  * 5-state OCR 1.8.x detect. Mirrors the ECC detect shape.
  */
 import { spawnSync } from 'node:child_process';
+import { resolveNpxInvocation } from './npx-resolver.js';
 import { OCR_18_PACKAGE } from './ocr-multilang-adapter.js';
+/** Named code for "npx itself could not be launched" — distinct from "npx is absent". */
+export const NPX_PROBE_UNRESOLVED_CODE = 'NPX_PROBE_UNRESOLVED';
+// 2026-09-10: `npx` on Windows is an `npx.cmd` shim, which Node refuses to spawn
+// without `shell: true` — a bare `spawnSync('npx', …)` failed with ENOENT and was
+// then reported as "npx is not on PATH" on machines where `npx --version` exits 0.
+// The shim is bypassed through `resolveNpxInvocation` (same helper as
+// `detect-eslint.ts`), and a launch failure is reported as its OWN reason rather
+// than being collapsed into "absent".
 function probeNpx() {
-    const probe = spawnSync('npx', ['--version'], { encoding: 'utf8' });
-    return probe.status === 0;
+    const { command, args, baseEnv } = resolveNpxInvocation(['--version']);
+    const probe = spawnSync(command, args, { encoding: 'utf8', env: baseEnv });
+    if (probe.status === 0)
+        return { available: true };
+    const error = probe.error;
+    if (error !== undefined && error !== null) {
+        // `command !== 'npx'` ⇒ the resolver located a real npx CLI entry and it STILL
+        // could not be launched — a different failure from "npx is not on PATH".
+        return command !== 'npx'
+            ? { available: false, reason: 'not-launchable', detail: error.message }
+            : { available: false, reason: 'not-on-path', detail: error.message };
+    }
+    return { available: false, reason: 'probe-failed', detail: `npx --version exited ${probe.status ?? 'null'}` };
 }
 function probeOcr18() {
-    const result = spawnSync('npx', ['--package', OCR_18_PACKAGE, '--', 'ocr', 'version'], { encoding: 'utf8' });
+    const { command, args, baseEnv } = resolveNpxInvocation(['--package', OCR_18_PACKAGE, '--', 'ocr', 'version']);
+    const result = spawnSync(command, args, { encoding: 'utf8', env: baseEnv });
     return result.status === 0;
 }
 export function detectOcr18() {
-    if (!probeNpx()) {
+    const probe = probeNpx();
+    if (!probe.available) {
+        if (probe.reason === 'not-launchable') {
+            return {
+                state: 'detection-failed',
+                npxAvailable: false,
+                package: OCR_18_PACKAGE,
+                warnings: [`${NPX_PROBE_UNRESOLVED_CODE}: could not launch npx to probe (${probe.detail}).`],
+                nextActions: ['Ensure Node.js >= 20 with its bundled npm is installed; `npx --version` must succeed.']
+            };
+        }
         return {
             state: 'ocr18-missing',
             npxAvailable: false,
             package: OCR_18_PACKAGE,
-            warnings: ['npx is not on PATH'],
+            warnings: [probe.reason === 'not-on-path' ? 'npx is not on PATH' : probe.detail],
             nextActions: ['Install Node.js ≥ 20 with npm to enable `npx --package`.']
         };
     }

package/dist/services/lint/npx-resolver.d.ts

@@ -4,3 +4,9 @@ export type NpxInvocation = {
     readonly baseEnv: NodeJS.ProcessEnv;
 };
 export declare function resolveNpxInvocation(npxArgs: readonly string[]): NpxInvocation;
+/**
+ * `npm` sibling of `resolveNpxInvocation`, same shim bypass: `node
+ * <npm-cli.js> <args>`. A caller must NOT reach for bare `npm` + `shell: true`
+ * instead — the shim is the defect, not the justification.
+ */
+export declare function resolveNpmInvocation(npmArgs: readonly string[]): NpxInvocation;