peaks-loop 4.0.35 → 4.0.37

package/dist/services/dispatch/session-capsule.d.ts

@@ -0,0 +1,23 @@
+/** Reserved batch id for the session capsule (matches the channel path pattern). */
+export declare const SESSION_CAPSULE_BATCH_ID = "session-capsule";
+/** Reserved key inside that channel. */
+export declare const SESSION_CAPSULE_KEY = "orchestrator.capsule";
+export interface SessionCapsuleRef {
+    readonly batchId: string;
+    readonly key: string;
+    /** Byte size of the published value (for the pointer line). */
+    readonly bytes: number;
+    /** ISO8601 timestamp of the last write. */
+    readonly updatedAt: string;
+}
+/**
+ * Read the session capsule, if one was published. Returns `null` when the
+ * channel is absent, empty, or unreadable — the dispatch prompt then
+ * renders neither the pointer nor the precedence line (byte-identical to
+ * the pre-slice shape).
+ */
+export declare function readSessionCapsule(opts: {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+}): SessionCapsuleRef | null;

package/dist/services/dispatch/session-capsule.js

@@ -0,0 +1,56 @@
+/**
+ * Slice 2026-09-10-dispatch-token-and-swarm §4 — session capsule reader.
+ *
+ * The orchestrator publishes already-known background ONCE per session
+ * through the existing G8.4 channel:
+ *
+ *   peaks sub-agent share \
+ *     --batch session-capsule \
+ *     --key orchestrator.capsule \
+ *     --value '{"rootCauses":[...],"decisions":[...],"fileMap":{...}}'
+ *
+ * Dispatch prompts then carry a one-line `shared-read` pointer instead of
+ * re-explaining that background in every task spec.
+ *
+ * QUALITY GUARD: the capsule is ADVISORY BACKGROUND ONLY. Nothing a
+ * sub-agent must ACT on may live only in the capsule — the task spec is
+ * authoritative and wins on conflict. The precedence sentence is rendered
+ * by `renderCapsulePointer` in build-dispatch-system-prompt.ts and is not
+ * optional when the pointer is emitted.
+ *
+ * This module only READS. Publishing is the orchestrator's job through the
+ * already-shipped `peaks sub-agent share` primitive — no new write path.
+ */
+import { readSharedChannel } from 'peaks-loop-shared-channel';
+/** Reserved batch id for the session capsule (matches the channel path pattern). */
+export const SESSION_CAPSULE_BATCH_ID = 'session-capsule';
+/** Reserved key inside that channel. */
+export const SESSION_CAPSULE_KEY = 'orchestrator.capsule';
+/**
+ * Read the session capsule, if one was published. Returns `null` when the
+ * channel is absent, empty, or unreadable — the dispatch prompt then
+ * renders neither the pointer nor the precedence line (byte-identical to
+ * the pre-slice shape).
+ */
+export function readSessionCapsule(opts) {
+    try {
+        const channel = readSharedChannel({
+            projectRoot: opts.projectRoot,
+            sid: opts.sid,
+            rid: opts.rid,
+            batchId: SESSION_CAPSULE_BATCH_ID
+        });
+        const entry = channel.entries[SESSION_CAPSULE_KEY];
+        if (entry === undefined)
+            return null;
+        return {
+            batchId: SESSION_CAPSULE_BATCH_ID,
+            key: SESSION_CAPSULE_KEY,
+            bytes: entry.valueSize,
+            updatedAt: entry.at
+        };
+    }
+    catch {
+        return null; // fail-soft: a missing capsule never blocks a dispatch
+    }
+}

package/dist/services/dispatch/slice-dag.d.ts

@@ -31,6 +31,15 @@ export interface SliceNode {
      * (complex = user-attended, simple/trivial = overnight). Optional.
      */
     readonly complexity?: SliceComplexity;
+    /**
+     * Slice 2026-09-10-dispatch-token-and-swarm §3: files this slice is
+     * expected to touch. When EVERY node of a topological level declares
+     * `files`, `--from-dag` emits a file-overlap wave plan (`firstLevelWaves`)
+     * so the LLM can fan the level out without serializing on a shared file.
+     * Optional and additive: absent → DAG hash and dispatch behavior are
+     * byte-identical to before this slice.
+     */
+    readonly files?: readonly string[];
 }
 export interface DependsOn {
     readonly from: string;

package/dist/services/dispatch/slice-dag.js

@@ -103,6 +103,11 @@ export function validateDag(dag) {
         if (n.complexity !== undefined && !isSliceComplexity(n.complexity)) {
             throw new InvalidSliceDagError(`node ${n.id} complexity must be one of ${SLICE_COMPLEXITIES.join('|')} when present`);
         }
+        // Slice 2026-09-10 §3: optional file list. Only shape-checked when
+        // present so pre-existing DAGs stay valid.
+        if (n.files !== undefined && (!Array.isArray(n.files) || n.files.some((f) => typeof f !== 'string' || f.length === 0))) {
+            throw new InvalidSliceDagError(`node ${n.id} files must be an array of non-empty strings when present`);
+        }
     }
     // v2.15.0 follow-up — G12 defensive rule: foundation slice can only
     // depend on another foundation slice. Business depending on foundation
@@ -219,7 +224,10 @@ export function serializeDag(dag) {
         // (only when present, preserving hash stability for old DAGs).
         ...(n.foundation !== undefined ? { foundation: n.foundation } : {}),
         ...(n.upstreamSync !== undefined ? { upstreamSync: n.upstreamSync } : {}),
-        ...(n.complexity !== undefined ? { complexity: n.complexity } : {})
+        ...(n.complexity !== undefined ? { complexity: n.complexity } : {}),
+        // Slice 2026-09-10 §3: only present when declared, so the hash of a
+        // file-less DAG is unchanged.
+        ...(n.files !== undefined ? { files: [...n.files] } : {})
     }));
     const edges = [...dag.edges]
         .sort((a, b) => {

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

@@ -26,8 +26,19 @@
  *  "remove the redundancy" of a test-tool-detection instruction because
  *  the dispatch CLI always prepends it. This is a guarantee, not a
  *  suggestion.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): ONE block for EVERY role. The
+ * runner-table EXAMPLES were dropped — they were never rules, and
+ * `package.json#scripts.test` is the source of truth at run time — while
+ * the one missing real rule is stated inline: PB-5, i.e. repo-defined
+ * `test` / `test:*` scripts are the human/LLM direct path and are NOT
+ * gated by the scope rule. The soft fallback ("only as a last resort, ask
+ * the user before assuming a runner") and the Windows-aware note on
+ * `peaks test <file>` are RETAINED — they are quality guidance, not
+ * examples. No role split remains, so every role receives a byte-identical
+ * block.
  */
-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).";
+export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nRead `package.json#scripts.test` for the project's framework and use the project-local runner \u2014 do NOT invoke `npx <runner>`. If unsure, run `peaks test --json` first. Only as a last resort, ask the user before assuming a runner. `peaks test <file>` already resolves the local binary for you (Windows-aware).\n\n## Test Scope (mandatory)\n\nAny test command MUST be **scoped** to a single file or pattern; a bare `./node_modules/.bin/vitest run` is **refused** unless you prefix the explicit opt-in token `PEAKS_FULL_TEST=1` (CI / release verification only, never routine slice verification).\n\nRepo-defined `test` / `test:*` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).";
 /**
  * Pure helper that returns the block. Exists as a function (not just an
  * exported constant) so future variants can take a runtime parameter

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

@@ -26,26 +26,27 @@
  *  "remove the redundancy" of a test-tool-detection instruction because
  *  the dispatch CLI always prepends it. This is a guarantee, not a
  *  suggestion.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): ONE block for EVERY role. The
+ * runner-table EXAMPLES were dropped — they were never rules, and
+ * `package.json#scripts.test` is the source of truth at run time — while
+ * the one missing real rule is stated inline: PB-5, i.e. repo-defined
+ * `test` / `test:*` scripts are the human/LLM direct path and are NOT
+ * gated by the scope rule. The soft fallback ("only as a last resort, ask
+ * the user before assuming a runner") and the Windows-aware note on
+ * `peaks test <file>` are RETAINED — they are quality guidance, not
+ * examples. No role split remains, so every role receives a byte-identical
+ * block.
  */
 export const TEST_TOOL_DETECTION_BLOCK = `## Test Tool Detection (mandatory)
 
-Before running any test, read \`package.json#scripts.test\` to identify the project's test framework. Use the project-local runner — do NOT invoke \`npx <runner>\`:
-
-- **vitest** → \`./node_modules/.bin/vitest run <file>\` (or \`pnpm test -- <file>\`)
-- **jest**   → \`./node_modules/.bin/jest <file>\`   (or \`pnpm test -- <file>\`)
-- **mocha**  → \`./node_modules/.bin/mocha <file>\`  (or \`pnpm test -- <file>\`)
+Read \`package.json#scripts.test\` for the project's framework and use the project-local runner — do NOT invoke \`npx <runner>\`. If unsure, run \`peaks test --json\` first. Only as a last resort, ask the user before assuming a runner. \`peaks test <file>\` already resolves the local binary for you (Windows-aware).
 
 ## 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).
+Any test command MUST be **scoped** to a single file or pattern; a bare \`./node_modules/.bin/vitest run\` is **refused** unless you prefix the explicit opt-in token \`PEAKS_FULL_TEST=1\` (CI / release verification only, never routine slice verification).
 
-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).`;
+Repo-defined \`test\` / \`test:*\` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).`;
 /**
  * Pure helper that returns the block. Exists as a function (not just an
  * exported constant) so future variants can take a runtime parameter

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/ide/adapters/claude-code-adapter.d.ts

@@ -1,4 +1,14 @@
 import type { IdeAdapter } from '../ide-types.js';
+/**
+ * Resolve the absolute path of a Claude Code transcript jsonl by OUTER
+ * session id, searching `~/.claude/projects/**` recursively.
+ *
+ * Exported (slice 2026-09-10-context-audit-and-discipline, Slice A) so
+ * `peaks code context-audit` reuses THIS locator instead of re-implementing
+ * the recursive find. Returns `null` when the transcript does not exist —
+ * callers MUST treat that as "unavailable", never as an error.
+ */
+export declare function resolveClaudeTranscriptPath(outerSessionId: string, projectsDir?: string): string | null;
 /**
  * Resolve the currently-active Claude Code model id from a runtime env map.
  * Returns the first non-empty `CLAUDE_CODE_MODEL_ENV_VARS` value (trimmed), or

package/dist/services/ide/adapters/claude-code-adapter.js

@@ -90,6 +90,20 @@ function findTranscriptJsonl(projectsDir, outerSessionId) {
     }
     return null;
 }
+/**
+ * Resolve the absolute path of a Claude Code transcript jsonl by OUTER
+ * session id, searching `~/.claude/projects/**` recursively.
+ *
+ * Exported (slice 2026-09-10-context-audit-and-discipline, Slice A) so
+ * `peaks code context-audit` reuses THIS locator instead of re-implementing
+ * the recursive find. Returns `null` when the transcript does not exist —
+ * callers MUST treat that as "unavailable", never as an error.
+ */
+export function resolveClaudeTranscriptPath(outerSessionId, projectsDir = join(homedir(), '.claude', 'projects')) {
+    if (typeof outerSessionId !== 'string' || outerSessionId.length === 0)
+        return null;
+    return findTranscriptJsonl(projectsDir, outerSessionId);
+}
 /** 1M-context window size in tokens (documented single choice: 1,000,000). */
 const ONE_MILLION_CONTEXT_TOKENS = 1_000_000;
 /** Safe-default (non-1M) context window size in tokens. */
@@ -483,7 +497,12 @@ export const CLAUDE_CODE_ADAPTER = {
         compactCommand: 'claude --compact',
         compactPathway: 'ide-native',
         postCompactDetectCommand: 'peaks code auto-compact --json',
-        readContextPercentFallback
+        readContextPercentFallback,
+        // Slice 2026-09-10-context-audit-and-discipline (Slice A): the vendor
+        // layout knowledge (`~/.claude/projects/**/<outerSessionId>.jsonl`)
+        // stays here; `peaks code context-audit` resolves it through the
+        // adapter registry, never by naming this adapter directly.
+        resolveTranscriptPath: (outerSessionId) => resolveClaudeTranscriptPath(outerSessionId),
     },
     // Slice #011: standards profile. Claude Code reads its constitution at
     // CLAUDE.md + module-level rules under .claude/rules/**. The values mirror

package/dist/services/ide/ide-types.d.ts

@@ -217,6 +217,21 @@ export interface IdeCompactProfile {
      * Added in slice 2026-09-02-vendor-neutral-context-probe.
      */
     readonly readContextPercentFallback?: (input: ContextPercentFallbackInput) => ContextPercentProbe | null;
+    /**
+     * Optional locator for the IDE's per-session transcript file (jsonl),
+     * keyed by the OUTER (harness) session id. `peaks code context-audit`
+     * (slice 2026-09-10-context-audit-and-discipline, Slice A) uses it to
+     * group the session's tool results by tool + short input key, so the
+     * generic audit service never learns any vendor's on-disk layout.
+     *
+     * Returns the absolute path, or `null` when the transcript does not
+     * exist. Adapters MUST NOT throw on a missing file — the audit treats
+     * `null` as `available: false` and continues.
+     *
+     * Adapters that do not opt in simply omit the field; the audit then
+     * reports `transcript-locator-unavailable`.
+     */
+    readonly resolveTranscriptPath?: (outerSessionId: string) => string | null;
 }
 /**
  * Input the generic `readContextPercent` reader passes to an adapter's

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

package/dist/services/lint/npx-resolver.js

@@ -1,26 +1,28 @@
 /**
- * Cross-platform `npx` resolver.
+ * Cross-platform `npm` / `npx` resolver.
  *
- * On Windows, `npm` installs `npx` as a `.cmd` shim; Node 22's
- * `child_process.spawnSync` refuses to invoke it unless `shell: true`
- * is set, and `shell: true` corrupts quoted `--package` arguments.
- * Rather than depend on shell quoting, this helper resolves the
- * npx script bundled with the user's `npm` install and invokes it
- * via `node <npx-cli.js>` with the same argv. macOS / Linux continue
- * to use the regular `npx` binary.
+ * On Windows, `npm` installs `npx` and `npm` as `.cmd` shims; Node's
+ * `child_process.spawnSync` refuses to invoke a `.cmd` unless `shell: true`
+ * is set, and `shell: true` concatenates (does not escape) the argv — it
+ * corrupts quoted `--package` arguments, splits any argument containing a
+ * space, and emits DEP0190 on every call. Rather than depend on shell
+ * quoting, these helpers resolve the CLI script bundled with the user's
+ * `npm` install and invoke it via `node <npm|npx>-cli.js` with the same
+ * argv. macOS / Linux continue to use the regular binaries.
  */
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
-function locateNpxCliScript() {
+/** Locate `<npm install>/bin/<scriptFile>`, or `null` when not on disk. */
+function locateNpmCliScript(scriptFile) {
     const candidates = process.platform === 'win32'
         ? [
-            join(process.execPath, '..', '..', 'node_modules', 'npm', 'bin', 'npx-cli.js'),
-            'C:/nvm4w/nodejs/node_modules/npm/bin/npx-cli.js',
-            'C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js'
+            join(process.execPath, '..', '..', 'node_modules', 'npm', 'bin', scriptFile),
+            `C:/nvm4w/nodejs/node_modules/npm/bin/${scriptFile}`,
+            `C:/Program Files/nodejs/node_modules/npm/bin/${scriptFile}`
         ]
         : [
-            join(process.execPath, '..', '..', 'lib', 'node_modules', 'npm', 'bin', 'npx-cli.js')
+            join(process.execPath, '..', '..', 'lib', 'node_modules', 'npm', 'bin', scriptFile)
         ];
     for (const candidate of candidates) {
         if (existsSync(candidate))
@@ -30,7 +32,7 @@ function locateNpxCliScript() {
 }
 export function resolveNpxInvocation(npxArgs) {
     if (process.platform === 'win32') {
-        const cliScript = locateNpxCliScript();
+        const cliScript = locateNpmCliScript('npx-cli.js');
         if (cliScript !== null) {
             return {
                 command: process.execPath,
@@ -45,3 +47,25 @@ export function resolveNpxInvocation(npxArgs) {
         baseEnv: process.env
     };
 }
+/**
+ * `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 function resolveNpmInvocation(npmArgs) {
+    if (process.platform === 'win32') {
+        const cliScript = locateNpmCliScript('npm-cli.js');
+        if (cliScript !== null) {
+            return {
+                command: process.execPath,
+                args: [cliScript, ...npmArgs],
+                baseEnv: process.env
+            };
+        }
+    }
+    return {
+        command: 'npm',
+        args: npmArgs,
+        baseEnv: process.env
+    };
+}

package/dist/services/memory/project-memory-service/parsers/frontmatter.d.ts

@@ -55,6 +55,11 @@ export declare function resolveMemoryKind(content: string): MemoryKindResolution
  * `parseStoredMemoryFile` (read path) and the reindex / ingest / doctor
  * classifiers consume this so there is exactly one kind-resolution rule
  * in the codebase.
+ *
+ * Tolerates a leading run of HTML-comment lines (e.g. the
+ * `<!-- peaks-memory:start -->` sediment marker) before the opening `---`
+ * fence. The closing fence is still required and body extraction is
+ * unchanged: the body is the text after the closing fence.
  */
 export declare function parseMemoryFrontmatter(content: string): ParsedMemoryFrontmatter;
 /** Which frontmatter field (or the filename) supplied a memory's name. */

package/dist/services/memory/project-memory-service/parsers/frontmatter.js

@@ -10,7 +10,10 @@
 //
 //   2. `parseStoredMemoryFile` — read-path side. Files in `.peaks/memory/`
 //      are stored as standard YAML frontmatter (name / description /
-//      metadata.type / metadata.sourceArtifact) followed by the body.
+//      metadata.type / metadata.sourceArtifact) followed by the body. A file
+//      may also open with HTML-comment lines (the `<!-- peaks-memory:start -->`
+//      sediment marker) before the frontmatter; `parseMemoryFrontmatter`
+//      skips that leading comment run before looking for the `---` fence.
 //
 // Both parsers share the `VALID_MEMORY_KINDS` allow-list (derived from the
 // canonical `PROJECT_MEMORY_KINDS` tuple in `../types.ts`) and the
@@ -83,23 +86,70 @@ export function resolveMemoryKind(content) {
     const parsed = parseMemoryFrontmatter(content);
     return parsed.kind;
 }
+/** Start of an HTML comment line, allowing leading horizontal whitespace. */
+const LEADING_COMMENT_OPEN = /^[ \t]*<!--/;
+/**
+ * Length of the leading run of blank lines and standalone HTML-comment lines.
+ *
+ * A stored memory may be written with the documented sediment marker
+ * (`<!-- peaks-memory:start -->`) — or any HTML comment — BEFORE its YAML
+ * frontmatter. This helper reports how much of the file to skip so the fence
+ * can still be found. At least one comment line must be present: a file that
+ * merely starts with blank lines is not treated as marker-prefixed, so the
+ * pre-existing (fence-at-byte-0) behaviour is preserved exactly.
+ */
+function leadingCommentPrefixLength(normalized) {
+    let offset = 0;
+    let sawComment = false;
+    for (;;) {
+        const rest = normalized.slice(offset);
+        const blank = /^[ \t]*\n/.exec(rest);
+        if (blank !== null) {
+            offset += blank[0].length;
+            continue;
+        }
+        const open = LEADING_COMMENT_OPEN.exec(rest);
+        if (open === null)
+            break;
+        const closeIndex = rest.indexOf('-->', open[0].length);
+        if (closeIndex < 0)
+            break;
+        const afterClose = closeIndex + '-->'.length;
+        const lineEnd = rest.indexOf('\n', afterClose);
+        if (lineEnd < 0)
+            break;
+        // Only a whole comment line counts; trailing prose after `-->` means the
+        // file does not open with a comment block.
+        if (rest.slice(afterClose, lineEnd).trim() !== '')
+            break;
+        offset += lineEnd + 1;
+        sawComment = true;
+    }
+    return sawComment ? offset : 0;
+}
 /**
  * Single parse surface for stored memory frontmatter. Both
  * `parseStoredMemoryFile` (read path) and the reindex / ingest / doctor
  * classifiers consume this so there is exactly one kind-resolution rule
  * in the codebase.
+ *
+ * Tolerates a leading run of HTML-comment lines (e.g. the
+ * `<!-- peaks-memory:start -->` sediment marker) before the opening `---`
+ * fence. The closing fence is still required and body extraction is
+ * unchanged: the body is the text after the closing fence.
  */
 export function parseMemoryFrontmatter(content) {
     const normalized = content.replace(/\r\n/g, '\n');
-    if (!normalized.startsWith('---\n')) {
+    const head = normalized.slice(leadingCommentPrefixLength(normalized));
+    if (!head.startsWith('---\n')) {
         return { hasFrontmatter: false, kind: { kind: null, source: 'none', rawKind: null }, frontmatter: '', body: normalized.trim() };
     }
-    const endIndex = normalized.indexOf('\n---\n', 4);
+    const endIndex = head.indexOf('\n---\n', 4);
     if (endIndex < 0) {
         return { hasFrontmatter: false, kind: { kind: null, source: 'none', rawKind: null }, frontmatter: '', body: normalized.trim() };
     }
-    const frontmatter = normalized.slice(4, endIndex);
-    const body = normalized.slice(endIndex + '\n---\n'.length).trim();
+    const frontmatter = head.slice(4, endIndex);
+    const body = head.slice(endIndex + '\n---\n'.length).trim();
     let name;
     let titleField;
     let description;