peaks-loop 4.0.54 → 4.1.1

package/dist/cli/commands/dispatch-from-dag.js

@@ -39,10 +39,10 @@ export async function runDispatchFromDag(role, options, asJson, io) {
     const projectRoot = options.project ?? process.cwd();
     // Slice 2026-06-26-unknown-sid-fallback-fix: see dispatch-commands.ts.
     // Auto-resolve sid from .peaks/_runtime/session.json before falling back.
-    const sid = options.sessionId
-        ?? process.env.PEAKS_SESSION_ID
-        ?? getCurrentSessionId(projectRoot)
-        ?? 'unknown-sid';
+    const sid = options.sessionId ??
+        process.env.PEAKS_SESSION_ID ??
+        getCurrentSessionId(projectRoot) ??
+        'unknown-sid';
     const rid = options.requestId ?? 'unknown-rid';
     const batchId = options.batchId ?? randomUUID();
     // Slice 9 (dispatch CLI latency): the --from-dag codepath loads three
@@ -87,7 +87,9 @@ export async function runDispatchFromDag(role, options, asJson, io) {
         const graphNodeId = node.graphNode;
         const candidate = typeof graphNodeId === 'string' && graphNodeId.length > 0 ? graphNodeId : node.id;
         if (typeof candidate !== 'string' || candidate.length === 0) {
-            printResult(io, fail('sub-agent.dispatch', 'PEAKS_GRAPH_NODE_REQUIRED', `DAG node ${node.id} has no graph-node mapping (RD §4 D4c)`, { role, toolCall: null, dispatchRecordPath: null, dagNodeId: node.id }, ['Annotate the DAG node with `graphNode: "<id>"` so each dispatch can bind a prepared graph node.']), asJson);
+            printResult(io, fail('sub-agent.dispatch', 'PEAKS_GRAPH_NODE_REQUIRED', `DAG node ${node.id} has no graph-node mapping (RD §4 D4c)`, { role, toolCall: null, dispatchRecordPath: null, dagNodeId: node.id }, [
+                'Annotate the DAG node with `graphNode: "<id>"` so each dispatch can bind a prepared graph node.'
+            ]), asJson);
             process.exitCode = 1;
             return;
         }
@@ -121,9 +123,7 @@ export async function runDispatchFromDag(role, options, asJson, io) {
     const adapter = getAdapter(ide);
     const dispatcher = adapter.subAgentDispatcher;
     if (!dispatcher.supportsRole(role)) {
-        printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', `IDE ${ide} does not support role "${role}"`, { role, toolCall: null, dispatchRecordPath: null }, [
-            'Switch to a registered IDE (e.g. claude-code) or pick a role the current IDE supports.'
-        ]), asJson);
+        printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', `IDE ${ide} does not support role "${role}"`, { role, toolCall: null, dispatchRecordPath: null }, ['Switch to a registered IDE (e.g. claude-code) or pick a role the current IDE supports.']), asJson);
         process.exitCode = 1;
         return;
     }
@@ -145,8 +145,7 @@ export async function runDispatchFromDag(role, options, asJson, io) {
         id,
         files: dag.nodes.find((n) => n.id === id)?.files ?? []
     }));
-    const firstLevelWaves = firstLevelDescriptors.length > 0
-        && firstLevelDescriptors.every((d) => d.files.length > 0)
+    const firstLevelWaves = firstLevelDescriptors.length > 0 && firstLevelDescriptors.every((d) => d.files.length > 0)
         ? planFileOverlapWaves(firstLevelDescriptors).waves
         : null;
     const emittedToolCalls = [];

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

@@ -34,9 +34,12 @@ export function registerDocCommands(program, io) {
                 const { writeFileSync, mkdirSync } = require('node:fs');
                 mkdirSync(resolvePath(opts.output, '..'), { recursive: true });
                 writeFileSync(resolvePath(opts.output), md, 'utf8');
-                printResult(io, ok('doc.generate-skill', { projectRoot, output: opts.output, sections: skill.sections.length, bytes: md.length }, [], [
-                    `Wrote ${md.length} bytes to ${opts.output}`
-                ]), opts.json ?? false);
+                printResult(io, ok('doc.generate-skill', {
+                    projectRoot,
+                    output: opts.output,
+                    sections: skill.sections.length,
+                    bytes: md.length
+                }, [], [`Wrote ${md.length} bytes to ${opts.output}`]), opts.json ?? false);
             }
             catch (err) {
                 printResult(io, fail('doc.generate-skill', 'WRITE_FAILED', err.message, { projectRoot }, []), opts.json ?? false);
@@ -44,9 +47,7 @@ export function registerDocCommands(program, io) {
             }
             return;
         }
-        printResult(io, ok('doc.generate-skill', { projectRoot, markdown: md, sections: skill.sections.length }, [], [
-            `Generated ${skill.sections.length} section(s). Pipe into a .md file or redirect.`
-        ]), opts.json ?? false);
+        printResult(io, ok('doc.generate-skill', { projectRoot, markdown: md, sections: skill.sections.length }, [], [`Generated ${skill.sections.length} section(s). Pipe into a .md file or redirect.`]), opts.json ?? false);
     });
     addJsonOption(doc
         .command('changelog-suggest')
@@ -58,8 +59,6 @@ export function registerDocCommands(program, io) {
         const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
         const entries = gitLogSince(projectRoot, opts.since);
         const md = suggestChangelog(entries);
-        printResult(io, ok('doc.changelog-suggest', { projectRoot, since: opts.since, entryCount: entries.length, markdown: md }, [], [
-            `Parsed ${entries.length} commit(s) since ${opts.since}.`
-        ]), opts.json ?? false);
+        printResult(io, ok('doc.changelog-suggest', { projectRoot, since: opts.since, entryCount: entries.length, markdown: md }, [], [`Parsed ${entries.length} commit(s) since ${opts.since}.`]), opts.json ?? false);
     });
 }

package/dist/cli/commands/doctor/invoke-from-code.js

@@ -27,7 +27,7 @@ export async function doctorInvokeFromCode(opts) {
         '## kind: <TBD>',
         '',
         'Real implementation: peaks-doctor LLM-driven analysis of',
-        '.peaks/_runtime/<sid>/txt/handoff.md + dispatch records.',
+        '.peaks/_runtime/<sid>/txt/handoff.md + dispatch records.'
     ].join('\n'));
     // Normalize to POSIX-style separators so callers (and tests) can rely
     // on a forward-slash contract regardless of host OS.

package/dist/cli/commands/e2e-verify-env.d.ts

@@ -0,0 +1,19 @@
+export type E2EVerifyInput = {
+    readonly projectRoot: string;
+    readonly slice: string;
+    readonly dispatchId?: string;
+};
+export type E2EVerifyResult = {
+    readonly outcome: 'pass' | 'fail' | 'skipped' | 'no-fixtures';
+    readonly passCount: number;
+    readonly failCount: number;
+    readonly skippedReason?: string;
+    /** When the real Playwright runner is used, the chromium-exit summary. */
+    readonly runner?: 'playwright' | 'stub';
+};
+export declare const PLAYWRIGHT_USER_DATA_DIR_ENV = "PEAKS_PLAYWRIGHT_USER_DATA_DIR";
+export declare const PLAYWRIGHT_PROFILE_NAME_ENV = "PEAKS_PLAYWRIGHT_PROFILE_NAME";
+export declare function resolvePlaywrightEnv(): {
+    readonly userDataDir: string;
+    readonly profileName: string;
+} | null;

package/dist/cli/commands/e2e-verify-env.js

@@ -0,0 +1,19 @@
+/**
+ * e2e-verify support surface — moved VERBATIM out of `e2e-verify.ts` for the
+ * 300-raw-line cap (slice `b1-filesplit-campaign`, wave 3C): the public
+ * input/result types, the two Playwright env-var names, and the env
+ * resolver. `e2e-verify.ts` re-exports the public types, so existing import
+ * paths keep working.
+ */
+import { existsSync } from 'node:fs';
+export const PLAYWRIGHT_USER_DATA_DIR_ENV = 'PEAKS_PLAYWRIGHT_USER_DATA_DIR';
+export const PLAYWRIGHT_PROFILE_NAME_ENV = 'PEAKS_PLAYWRIGHT_PROFILE_NAME';
+export function resolvePlaywrightEnv() {
+    const userDataDir = process.env[PLAYWRIGHT_USER_DATA_DIR_ENV];
+    const profileName = process.env[PLAYWRIGHT_PROFILE_NAME_ENV];
+    if (!userDataDir || !profileName)
+        return null;
+    if (!existsSync(userDataDir))
+        return null;
+    return { userDataDir, profileName };
+}

package/dist/cli/commands/e2e-verify.d.ts

@@ -28,20 +28,9 @@
  * never silently blocked from running the real runner — they can set
  * the env vars and re-run.
  */
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-export type E2EVerifyInput = {
-    readonly projectRoot: string;
-    readonly slice: string;
-    readonly dispatchId?: string;
-};
-export type E2EVerifyResult = {
-    readonly outcome: 'pass' | 'fail' | 'skipped' | 'no-fixtures';
-    readonly passCount: number;
-    readonly failCount: number;
-    readonly skippedReason?: string;
-    /** When the real Playwright runner is used, the chromium-exit summary. */
-    readonly runner?: 'playwright' | 'stub';
-};
+import { type E2EVerifyInput, type E2EVerifyResult } from './e2e-verify-env.js';
+export type { E2EVerifyInput, E2EVerifyResult } from './e2e-verify-env.js';
 export declare function runE2EVerify(input: E2EVerifyInput): Promise<E2EVerifyResult>;
 export declare function registerE2EVerifyCommand(program: Command, io: ProgramIO): void;

package/dist/cli/commands/e2e-verify.js

@@ -1,11 +1,9 @@
 import { spawn as nodeSpawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { readE2EPlan } from '../../services/dispatch/e2e-fixtures.js';
 import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-const PLAYWRIGHT_USER_DATA_DIR_ENV = 'PEAKS_PLAYWRIGHT_USER_DATA_DIR';
-const PLAYWRIGHT_PROFILE_NAME_ENV = 'PEAKS_PLAYWRIGHT_PROFILE_NAME';
+import { resolvePlaywrightEnv } from './e2e-verify-env.js';
 /**
  * Probe whether a Chromium binary is callable on this host. The probe
  * uses `process.platform` to pick the right finder (`where` on Windows,
@@ -13,18 +11,27 @@ const PLAYWRIGHT_PROFILE_NAME_ENV = 'PEAKS_PLAYWRIGHT_PROFILE_NAME';
  * least one match is found AND `--version` exits 0.
  */
 async function probeChromiumBinary() {
-    const candidates = process.platform === 'win32' ? ['chromium.exe', 'chrome.exe'] : ['chromium', 'chromium-browser', 'google-chrome'];
+    const candidates = process.platform === 'win32'
+        ? ['chromium.exe', 'chrome.exe']
+        : ['chromium', 'chromium-browser', 'google-chrome'];
     const finder = process.platform === 'win32' ? 'where' : 'which';
     for (const candidate of candidates) {
         try {
-            const result = nodeSpawn(finder, [candidate], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+            const result = nodeSpawn(finder, [candidate], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                windowsHide: true
+            });
             const stdout = await new Promise((resolve, reject) => {
                 let buf = '';
-                result.stdout.on('data', (chunk) => { buf += chunk.toString('utf8'); });
-                result.on('close', (code) => { if (code === 0)
-                    resolve(buf);
-                else
-                    reject(new Error(`exit ${code}`)); });
+                result.stdout.on('data', (chunk) => {
+                    buf += chunk.toString('utf8');
+                });
+                result.on('close', (code) => {
+                    if (code === 0)
+                        resolve(buf);
+                    else
+                        reject(new Error(`exit ${code}`));
+                });
                 result.on('error', reject);
             });
             if (stdout.trim().length === 0)
@@ -33,7 +40,10 @@ async function probeChromiumBinary() {
             const firstLine = stdout.split(/\r?\n/)[0]?.trim();
             if (!firstLine)
                 continue;
-            const probe = nodeSpawn(firstLine, ['--version'], { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+            const probe = nodeSpawn(firstLine, ['--version'], {
+                stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true
+            });
             const exitCode = await new Promise((resolve) => {
                 probe.on('close', (code) => resolve(code ?? 1));
                 probe.on('error', () => resolve(1));
@@ -47,15 +57,6 @@ async function probeChromiumBinary() {
     }
     return false;
 }
-function resolvePlaywrightEnv() {
-    const userDataDir = process.env[PLAYWRIGHT_USER_DATA_DIR_ENV];
-    const profileName = process.env[PLAYWRIGHT_PROFILE_NAME_ENV];
-    if (!userDataDir || !profileName)
-        return null;
-    if (!existsSync(userDataDir))
-        return null;
-    return { userDataDir, profileName };
-}
 /**
  * Run a single fixture through the real Chromium-driven matcher.
  *
@@ -113,10 +114,12 @@ async function runOneFixtureWithPlaywright(fixture, env) {
                 `--user-data-dir=${env.userDataDir}`,
                 `--profile-directory=${env.profileName}`,
                 `--dump-dom`,
-                fixture.url,
+                fixture.url
             ], { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
             let html = '';
-            proc.stdout.on('data', (chunk) => { html += chunk.toString('utf8'); });
+            proc.stdout.on('data', (chunk) => {
+                html += chunk.toString('utf8');
+            });
             proc.on('error', () => settle({ pass: false, reason: 'chromium-spawn-failed' }));
             proc.on('close', (code) => {
                 if (code !== 0) {
@@ -128,8 +131,9 @@ async function runOneFixtureWithPlaywright(fixture, env) {
                     const looksLikeCss = matcher.startsWith('css:') || matcher.startsWith('#') || matcher.startsWith('.');
                     const needle = looksLikeCss ? matcher.replace(/^css:/, '').trim() : matcher;
                     const present = looksLikeCss
-                        ? new RegExp(`<[a-zA-Z][^>]*class=["'][^"']*\\b${needle.replace(/^\./, '').replace(/^#/, '')}\\b`).test(html)
-                            || (needle.startsWith('#') && new RegExp(`id=["']${needle.replace(/^#/, '')}["']`).test(html))
+                        ? new RegExp(`<[a-zA-Z][^>]*class=["'][^"']*\\b${needle.replace(/^\./, '').replace(/^#/, '')}\\b`).test(html) ||
+                            (needle.startsWith('#') &&
+                                new RegExp(`id=["']${needle.replace(/^#/, '')}["']`).test(html))
                         : html.includes(needle);
                     if (!present) {
                         settle({ pass: false, reason: `matcher-missing:${matcher}` });
@@ -150,7 +154,13 @@ export async function runE2EVerify(input) {
     if (plan.kind === 'empty')
         return { outcome: 'no-fixtures', passCount: 0, failCount: 0, runner: 'stub' };
     if (plan.kind === 'disabled') {
-        return { outcome: 'skipped', passCount: 0, failCount: 0, skippedReason: plan.reason, runner: 'stub' };
+        return {
+            outcome: 'skipped',
+            passCount: 0,
+            failCount: 0,
+            skippedReason: plan.reason,
+            runner: 'stub'
+        };
     }
     // Decide between the real Playwright runner and the deterministic
     // stub. Either env-var unset OR chromium missing → fallback. The
@@ -189,7 +199,7 @@ export async function runE2EVerify(input) {
         passCount,
         failCount,
         runner: 'playwright',
-        ...(chromiumReason !== null ? { skippedReason: chromiumReason } : {}),
+        ...(chromiumReason !== null ? { skippedReason: chromiumReason } : {})
     };
 }
 export function registerE2EVerifyCommand(program, io) {
@@ -200,11 +210,21 @@ export function registerE2EVerifyCommand(program, io) {
         .option('--project <path>', 'project root (default: cwd)', '.')
         .option('--dispatch-id <id>', 'optional dispatch id used in observability events')).action(async (options) => {
         try {
-            const result = await runE2EVerify({ projectRoot: options.project, slice: options.slice, ...(options.dispatchId !== undefined ? { dispatchId: options.dispatchId } : {}) });
-            printResult(io, ok('e2e.verify', { ...result, slice: options.slice, dispatchId: options.dispatchId ?? null }), options.json);
+            const result = await runE2EVerify({
+                projectRoot: options.project,
+                slice: options.slice,
+                ...(options.dispatchId !== undefined ? { dispatchId: options.dispatchId } : {})
+            });
+            printResult(io, ok('e2e.verify', {
+                ...result,
+                slice: options.slice,
+                dispatchId: options.dispatchId ?? null
+            }), options.json);
         }
         catch (error) {
-            printResult(io, fail('e2e.verify', 'E2E_VERIFY_FAILED', getErrorMessage(error), {}, [getErrorMessage(error)]), options.json);
+            printResult(io, fail('e2e.verify', 'E2E_VERIFY_FAILED', getErrorMessage(error), {}, [
+                getErrorMessage(error)
+            ]), options.json);
             process.exitCode = 1;
         }
     });

package/dist/cli/commands/ecc-commands.d.ts

@@ -1,30 +1,25 @@
 /**
- * `peaks ecc install|status|ls|show` — Slice 3 of 4.0.0-beta.11.
+ * `peaks ecc install|status|ls|show` — the ECC read layer.
  *
- * Drop-in replacement for the deleted `peaks agent run|list`
- * surface. The pre-Slice-3 implementation shelled out to
- * `npx ecc agent run ...`, but the upstream `affaan-m/everything-claude-code`
- * v2.0.0 release has NO `ecc` binary — the repo is `agents/*.md`
- * flat files plus SKILL.md descriptors.
+ * ECC's agent definitions come from the `ecc-universal` npm dependency of
+ * `peaks-loop-mut`. `install` copies `<package>/agents/*.md` into the
+ * plugin-free dir the LLM reads (`~/.peaks/agents/ecc/`); `status`, `ls` and
+ * `show` read that copy. There is no download anywhere in this file: the
+ * previous design fetched a GitHub release tarball on the premise that the
+ * project was not on npm, and that premise was false (`ecc-universal`
+ * `repository.url` is `git+https://github.com/affaan-m/ECC.git`).
  *
- * The new flow:
- *   - `peaks ecc install [--ref <tag>]` downloads the ECC tarball
- *     into `~/.peaks/cache/ecc-<sha>/agents/` (selective extract,
- *     agents/*.md only).
- *   - `peaks ecc status` reports the cache manifest state.
- *   - `peaks ecc ls` lists cached agents from `<cache>/agents/*.md`,
- *     parsing YAML frontmatter (with D-009 fallback to filename +
- *     first body line when frontmatter is malformed).
- *   - `peaks ecc show <name> [--section H] [--max-lines N]` prints
- *     the SKILL.md body to stdout — this is the Skill-first path
- *     the LLM consumes directly.
+ *   - `peaks ecc install` — land/refresh the copy. Idempotent; prunes agents the
+ *     installed package no longer ships.
+ *   - `peaks ecc status` — package version + what landed and when.
+ *   - `peaks ecc ls` — the roster with declared name + description (D-009
+ *     fallback to filename + first body line when frontmatter is malformed).
+ *   - `peaks ecc show <name> [--section H] [--max-lines N]` — the agent body;
+ *     this is the Skill-first path the LLM consumes directly.
  *
- * The `--section` filter extracts a single H1 (`# heading`)
- * through the next H1 — useful when the SKILL.md is large.
- *
- * Per the "Enhancement, not new AI CLI" tenet: this command is a
- * download + read-only access layer. There is no `peaks ecc run`.
+ * Per the "Enhancement, not new AI CLI" tenet: read-only access plus a local
+ * copy. There is no `peaks ecc run`, and no ECC subprocess is spawned.
  */
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerEccCommands(program: Command, io: ProgramIO): void;

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

@@ -1,59 +1,66 @@
-import { downloadToCache, listCachedAgents, readAgentSkill, readCacheManifest, } from 'peaks-loop-mut';
+import { EccSourceError, installEccAgents, listEccAgents, readEccMaterializeManifest, readMaterializedAgent } from 'peaks-loop-mut';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 export function registerEccCommands(program, io) {
     const ecc = program
         .command('ecc')
-        .description('affaan-m/ECC cache: download + read-only access for the LLM (no subprocess; no peaks agent run).');
+        .description('ECC agents from the bundled `ecc-universal` dependency: copy + read-only access for the LLM (no subprocess; no peaks agent run).');
     addJsonOption(ecc
         .command('install')
-        .description('Download affaan-m/ECC to ~/.peaks/cache/ecc-<sha>/ (selective extract: agents/ subtree only).')
-        .option('--ref <tag>', 'release tag (default: latest)')).action(async (options) => {
-        const asJson = options.json === true;
+        .description('Copy <node_modules>/ecc-universal/agents/*.md into ~/.peaks/agents/ecc/ (idempotent).')).action((_options) => {
+        const asJson = _options.json === true;
         try {
-            const result = await downloadToCache(options.ref !== undefined && options.ref.length > 0 ? { ref: options.ref } : {});
+            const result = installEccAgents();
             const envelope = ok('ecc.install', result, [], [
-                `Cache landed at ~/.peaks/cache/ecc-${result.sha}/agents/`,
-                `Plugin-free copy materialized at ~/.peaks/agents/ecc/ (read it directly when the ECC plugin is absent)`,
-                `Inspect with: peaks ecc ls`,
-                `Consume one agent with: peaks ecc show <name>`,
+                `Materialized ${result.materialized.length} ECC agent(s) at ${result.targetDir}`,
+                `Source: ecc-universal@${result.packageVersion}`,
+                'Inspect with: peaks ecc ls',
+                'Consume one agent with: peaks ecc show <name>'
             ]);
             printResult(io, envelope, asJson);
         }
         catch (error) {
-            const message = getErrorMessage(error);
-            printResult(io, fail('ecc.install', 'FETCH_FAILED', message, { ref: options.ref ?? 'latest' }, [
-                'Network failure during ECC download. Manual fallback:',
-                '  git clone https://github.com/affaan-m/ECC.git',
-                '  Copy <repo>/agents/*.md into ~/.peaks/cache/ecc-<sha>/agents/.',
-                '  Drop a minimal ecc-installed.json manifest into ~/.peaks/cache/.',
-            ]), asJson);
+            const missing = error instanceof EccSourceError;
+            printResult(io, fail('ecc.install', missing ? 'ECC_PACKAGE_MISSING' : 'ECC_INSTALL_FAILED', getErrorMessage(error), { source: missing ? error.failure : 'copy-failed' }, missing
+                ? [
+                    'The `ecc-universal` dependency is not resolvable from this installation.',
+                    'Reinstall peaks-loop (`npm i -g peaks-loop@latest`) — the ECC agents ship inside that dependency.',
+                    'A partial or `--ignore-scripts` install can leave the dependency tree incomplete.'
+                ]
+                : ['Check that ~/.peaks is writable, then re-run `peaks ecc install`.']), asJson);
             process.exitCode = 1;
         }
     });
     addJsonOption(ecc
         .command('status')
-        .description('Show ECC cache state (version, sha, fetchedAt, agent count).')).action((options) => {
+        .description('Show the materialized ECC copy: source version, agent list, when it landed.')).action((options) => {
         const asJson = options.json === true;
-        const manifest = readCacheManifest();
+        const manifest = readEccMaterializeManifest();
         if (manifest === null) {
-            printResult(io, fail('ecc.status', 'NO_CACHE', 'No ECC cache found. Run `peaks ecc install` first.', { installed: false }, ['Run `peaks ecc install [--ref <tag>]` to populate ~/.peaks/cache/ecc-<sha>/agents/.']), asJson);
+            printResult(io, fail('ecc.status', 'NOT_INSTALLED', 'No materialized ECC agents found. Run `peaks ecc install` first.', { installed: false }, [
+                'Run `peaks ecc install` to copy the bundled ecc-universal agents into ~/.peaks/agents/ecc/.'
+            ]), asJson);
             process.exitCode = 1;
             return;
         }
+        // `status` reads the copy and reports it. It does not re-probe the package:
+        // `manifest.packageVersion` already records which version landed the agents,
+        // and probing again would need either a throw that hides the answer or a
+        // swallowed error — the second is the class the repository's silent-catch
+        // ratchet counts, the first would turn "here is what the LLM can read" into a
+        // failure just because a dependency moved.
         printResult(io, ok('ecc.status', manifest, [], [
-            `Inspect agents with: peaks ecc ls`,
-            `Print one agent with: peaks ecc show <name>`,
+            `Materialized from ecc-universal@${manifest.packageVersion}.`,
+            'Inspect agents with: peaks ecc ls',
+            'Print one agent with: peaks ecc show <name>'
         ]), asJson);
     });
     addJsonOption(ecc
         .command('ls')
-        .description('List cached agents from <cache>/agents/*.md with parsed frontmatter.')).action((options) => {
+        .description('List materialized agents from ~/.peaks/agents/ecc/*.md with parsed frontmatter.')).action((options) => {
         const asJson = options.json === true;
-        const agents = listCachedAgents();
-        printResult(io, ok('ecc.ls', { agents }, [], [
-            'Print one with: `peaks ecc show <name>`',
-        ]), asJson);
+        const agents = listEccAgents();
+        printResult(io, ok('ecc.ls', { agents }, [], ['Print one with: `peaks ecc show <name>`']), asJson);
     });
     addJsonOption(ecc
         .command('show <name>')
@@ -62,17 +69,15 @@ export function registerEccCommands(program, io) {
         .option('--max-lines <n>', 'cap stdout at N lines (default: unlimited)')).action((name, options) => {
         const asJson = options.json === true;
         if (!/^[a-z][a-z0-9-]*$/.test(name)) {
-            printResult(io, fail('ecc.show', 'INVALID_NAME', `agent name must match ^[a-z][a-z0-9-]*$ (got "${name}")`, { name }, [
-                'Run `peaks ecc ls` to see valid agent names.',
-            ]), asJson);
+            printResult(io, fail('ecc.show', 'INVALID_NAME', `agent name must match ^[a-z][a-z0-9-]*$ (got "${name}")`, { name }, ['Run `peaks ecc ls` to see valid agent names.']), asJson);
             process.exitCode = 1;
             return;
         }
-        const body = readAgentSkill(name);
+        const body = readMaterializedAgent(name);
         if (body === null) {
-            printResult(io, fail('ecc.show', 'NOT_FOUND', `agent "${name}" is not in the cache`, { name }, [
+            printResult(io, fail('ecc.show', 'NOT_FOUND', `agent "${name}" is not in the materialized copy`, { name }, [
                 'Run `peaks ecc ls` to see available agents.',
-                'Or run `peaks ecc install` to (re-)populate the cache.',
+                'Or run `peaks ecc install` to (re-)copy the bundled agents into ~/.peaks/agents/ecc/.'
             ]), asJson);
             process.exitCode = 1;
             return;
@@ -83,9 +88,7 @@ export function registerEccCommands(program, io) {
             const lines = body.split(/\r?\n/);
             const startIdx = lines.findIndex((line) => new RegExp(`^#\\s+${escapeRegExp(heading)}\\s*$`).test(line));
             if (startIdx === -1) {
-                printResult(io, fail('ecc.show', 'SECTION_NOT_FOUND', `section "# ${heading}" not found in ${name}.md`, { name, section: heading }, [
-                    'Open the file directly to see section names.',
-                ]), asJson);
+                printResult(io, fail('ecc.show', 'SECTION_NOT_FOUND', `section "# ${heading}" not found in ${name}.md`, { name, section: heading }, ['Open the file directly to see section names.']), asJson);
                 process.exitCode = 1;
                 return;
             }

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

@@ -4,7 +4,9 @@ import { generateEvidence, parseFiles, parseLineCounts } from '../../services/ev
 import { getSessionId } from '../../services/session/session-manager.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 export function registerEvidenceCommands(program, io) {
-    const evidence = program.command('evidence').description('Generate per-slice evidence artifacts for mechanical slices');
+    const evidence = program
+        .command('evidence')
+        .description('Generate per-slice evidence artifacts for mechanical slices');
     addJsonOption(evidence
         .command('generate')
         .description('Write the ~11 rd/qa/audit/prd evidence artifacts for a mechanical file-split slice under .peaks/_runtime/<sid>/')
@@ -17,7 +19,9 @@ export function registerEvidenceCommands(program, io) {
             const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
             const sessionId = options.sessionId ?? getSessionId(projectRoot);
             if (sessionId === null || sessionId === undefined || sessionId.length === 0) {
-                printResult(io, fail('evidence.generate', 'SESSION_NOT_BOUND', 'No --session-id was provided and no peaks session is bound for this project.', { projectRoot }, ['Pass --session-id <sid>, or run `peaks workspace init` first so a session directory exists.']), options.json);
+                printResult(io, fail('evidence.generate', 'SESSION_NOT_BOUND', 'No --session-id was provided and no peaks session is bound for this project.', { projectRoot }, [
+                    'Pass --session-id <sid>, or run `peaks workspace init` first so a session directory exists.'
+                ]), options.json);
                 process.exitCode = 1;
                 return;
             }
@@ -31,12 +35,12 @@ export function registerEvidenceCommands(program, io) {
                 lineCounts,
                 sessionId
             });
-            printResult(io, ok('evidence.generate', result, [], [
-                `Wrote ${result.writtenFiles.length} evidence files under ${result.sessionRoot}`
-            ]), options.json);
+            printResult(io, ok('evidence.generate', result, [], [`Wrote ${result.writtenFiles.length} evidence files under ${result.sessionRoot}`]), options.json);
         }
         catch (error) {
-            printResult(io, fail('evidence.generate', 'EVIDENCE_GENERATE_FAILED', getErrorMessage(error), {}, ['Verify the target project is writable.']), options.json);
+            printResult(io, fail('evidence.generate', 'EVIDENCE_GENERATE_FAILED', getErrorMessage(error), {}, [
+                'Verify the target project is writable.'
+            ]), options.json);
             process.exitCode = 1;
         }
     });

package/dist/cli/commands/evolution-commands.d.ts

@@ -22,6 +22,6 @@
  * rules (AC-8 / AC-10 / AC-11); the CLI only translates flags
  * into the service payload.
  */
-import { Command } from "commander";
-import { type ProgramIO } from "../cli-helpers.js";
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerEvolutionCommands(program: Command, io: ProgramIO): void;