peaks-loop 4.1.2 → 4.1.3

package/dist/services/readonly-surface/whitelist-generator.js

@@ -0,0 +1,212 @@
+/**
+ * The schema introspector (spec §3 row 2): turns the hand-authored surface
+ * declaration into the generated whitelist artifact by READING the live Commander
+ * registry - never by restating it.
+ *
+ * Everything the registry can answer is taken from it:
+ *   - does the command path exist,
+ *   - does each `--flag` in the template exist on that command,
+ *   - is that flag mandatory, and does it take a value,
+ *   - which positionals does the command declare, and are they required.
+ * A template that disagrees with the registry is a BUILD FAILURE, not a warning:
+ * that is the whole point of generating the artifact instead of typing it.
+ *
+ * What the registry CANNOT answer is the constraint on a placeholder's value
+ * (`^[a-z0-9-]+$` for a request id). Those constraints come from the surface file
+ * and are marked `constraintSource: 'handwritten'`, so the one place drift can
+ * enter is visible in the artifact. When a command later declares `.choices()`,
+ * the same field flips to `introspected` with no artifact edit.
+ *
+ * DETERMINISM: no timestamps, no `Date`, no unordered iteration. Record
+ * keys follow argv order and entries follow the surface file's order, so two
+ * consecutive runs are byte-identical.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { repoRoot } from 'peaks-loop-shared/paths';
+import { READONLY_WHITELIST_RELATIVE_PATH } from './readonly-whitelist.js';
+/** The hand-authored input, relative to the package root. */
+export const READONLY_SURFACE_RELATIVE_PATH = 'contracts/readonly-surface.json';
+/** The schema version of the artifact this module emits. */
+export const READONLY_WHITELIST_SCHEMA_VERSION = 1;
+const SurfaceParamSchema = z.object({
+    type: z.enum(['slug', 'enum', 'token', 'integer', 'path']),
+    pattern: z.string().min(1).optional(),
+    values: z.array(z.string().min(1)).min(1).optional(),
+    min: z.number().int().optional(),
+    max: z.number().int().optional(),
+    default: z.number().int().optional()
+});
+const SurfaceEntrySchema = z.object({
+    id: z.string().min(1),
+    commandPath: z.array(z.string().min(1)).min(1),
+    argv: z.array(z.string().min(1)).min(1),
+    params: z.record(z.string(), SurfaceParamSchema)
+});
+export const ReadOnlySurfaceSchema = z.object({
+    schemaVersion: z.literal(1),
+    readOnlyDefinition: z.string().min(1),
+    note: z.array(z.string()).default([]),
+    tools: z.array(z.object({ tool: z.string().min(1), entries: z.array(SurfaceEntrySchema).min(1) }))
+});
+/** `<name>` marks a placeholder token in a surface `argv` element. */
+const PLACEHOLDER_TOKEN = /^<([a-z][a-z0-9-]*)>$/;
+class SurfaceDriftError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SurfaceDriftError';
+    }
+}
+function resolveCommand(program, path) {
+    let current = program;
+    for (const name of path) {
+        current = current.commands.find((candidate) => candidate.name() === name);
+        if (current === undefined) {
+            throw new SurfaceDriftError(`No command registered at path: ${path.join(' ')}`);
+        }
+    }
+    return current;
+}
+function hasOption(command, token) {
+    return command.options.some((option) => option.long === token || option.short === token);
+}
+function optionTakingValue(command, token) {
+    return command.options.find((option) => {
+        if (option.long !== token && option.short !== token)
+            return false;
+        return /[<[].+[>\]]/.test(option.flags);
+    });
+}
+/** Placeholders the registry supplies a constraint for are marked as such. */
+function constraintSourceOf(declared, option) {
+    if (declared.type === 'enum' && option?.argChoices !== undefined)
+        return 'introspected';
+    if (option?.defaultValue !== undefined && declared.default !== undefined)
+        return 'introspected';
+    return 'handwritten';
+}
+/** The constraint fields the surface declares, copied without inventing absent ones. */
+function constraintsOf(declared) {
+    return {
+        type: declared.type,
+        ...(declared.pattern === undefined ? {} : { pattern: declared.pattern }),
+        ...(declared.values === undefined ? {} : { values: declared.values }),
+        ...(declared.min === undefined ? {} : { min: declared.min }),
+        ...(declared.max === undefined ? {} : { max: declared.max }),
+        ...(declared.default === undefined ? {} : { default: declared.default })
+    };
+}
+/**
+ * Bind one placeholder either to the value-taking flag before it or to the next
+ * positional the command declares. Membership in the template is what makes a
+ * value required; `binding.required` carries the REGISTRY's opinion, which is a
+ * different fact (`--limit` is not mandatory, yet the template pins it).
+ */
+function bindPlaceholder(slot) {
+    const { entryId, name, declared, command, previousToken, cursor } = slot;
+    if (declared === undefined) {
+        throw new SurfaceDriftError(`Entry ${entryId}: placeholder <${name}> has no params spec`);
+    }
+    const boundOption = previousToken === undefined ? undefined : optionTakingValue(command, previousToken);
+    if (boundOption !== undefined && previousToken !== undefined) {
+        return {
+            ...constraintsOf(declared),
+            binding: { kind: 'option', token: previousToken, required: boundOption.mandatory },
+            constraintSource: constraintSourceOf(declared, boundOption)
+        };
+    }
+    const registered = command.registeredArguments[cursor.positionalIndex];
+    if (registered === undefined) {
+        throw new SurfaceDriftError(`Entry ${entryId}: <${name}> is positional ${cursor.positionalIndex + 1} but the command declares ${command.registeredArguments.length}`);
+    }
+    cursor.positionalIndex += 1;
+    cursor.positionalNames.push(registered.name());
+    return {
+        ...constraintsOf(declared),
+        binding: { kind: 'positional', token: registered.name(), required: registered.required },
+        constraintSource: 'handwritten'
+    };
+}
+/** The non-flag words a template opens with, which must be the command path. */
+function leadingLiteralsOf(argv) {
+    return argv.flatMap((segment) => segment.kind === 'literal' && !segment.value.startsWith('-') ? [segment.value] : []);
+}
+function assertTemplateDrivesCommand(surface, command, argv, cursor) {
+    const leading = leadingLiteralsOf(argv);
+    if (leading.join('\u0000') !== surface.commandPath.join('\u0000')) {
+        throw new SurfaceDriftError(`Entry ${surface.id}: argv opens with [${leading.join(', ')}] but commandPath is [${surface.commandPath.join(', ')}]`);
+    }
+    if (cursor.positionalIndex !== command.registeredArguments.length) {
+        throw new SurfaceDriftError(`Entry ${surface.id}: template fills ${cursor.positionalIndex} positional(s); ${surface.commandPath.join(' ')} declares ${command.registeredArguments.length}`);
+    }
+}
+function buildEntry(program, tool, surface) {
+    const command = resolveCommand(program, surface.commandPath);
+    const optionTokens = [];
+    const argv = [];
+    const params = {};
+    const cursor = { positionalIndex: 0, positionalNames: [] };
+    for (let index = 0; index < surface.argv.length; index += 1) {
+        const token = surface.argv[index];
+        if (token === undefined)
+            continue;
+        const placeholder = PLACEHOLDER_TOKEN.exec(token);
+        const name = placeholder?.[1];
+        if (placeholder !== null && name !== undefined) {
+            params[name] = bindPlaceholder({
+                entryId: surface.id,
+                name,
+                declared: surface.params[name],
+                command,
+                previousToken: index > 0 ? surface.argv[index - 1] : undefined,
+                cursor
+            });
+            argv.push({ kind: 'param', name });
+            continue;
+        }
+        if (token.startsWith('-')) {
+            if (!hasOption(command, token)) {
+                throw new SurfaceDriftError(`Entry ${surface.id}: no such option ${token} on ${surface.commandPath.join(' ')}`);
+            }
+            optionTokens.push(token);
+        }
+        argv.push({ kind: 'literal', value: token });
+    }
+    assertTemplateDrivesCommand(surface, command, argv, cursor);
+    return {
+        id: surface.id,
+        tool,
+        commandPath: [...surface.commandPath],
+        argv,
+        params,
+        introspection: { optionTokens, positionalCount: cursor.positionalNames.length }
+    };
+}
+/** Build the artifact object from a surface declaration and a live program. */
+export function generateReadOnlyWhitelist(surface, program) {
+    const entries = surface.tools.flatMap((group) => group.entries.map((entry) => buildEntry(program, group.tool, entry)));
+    const ids = new Set(entries.map((entry) => entry.id));
+    if (ids.size !== entries.length) {
+        throw new SurfaceDriftError('Entry ids must be unique across the whole surface');
+    }
+    return {
+        schemaVersion: READONLY_WHITELIST_SCHEMA_VERSION,
+        source: READONLY_SURFACE_RELATIVE_PATH,
+        readOnlyDefinition: surface.readOnlyDefinition,
+        entries
+    };
+}
+/** Byte-stable serialization: two runs over the same input MUST match. */
+export function serializeReadOnlyWhitelist(whitelist) {
+    return `${JSON.stringify(whitelist, null, 2)}\n`;
+}
+/** Read + validate the hand-authored surface declaration. */
+export function loadReadOnlySurface(root = repoRoot) {
+    const text = readFileSync(join(root, READONLY_SURFACE_RELATIVE_PATH), 'utf8');
+    return ReadOnlySurfaceSchema.parse(JSON.parse(text));
+}
+/** Absolute path of the generated artifact. */
+export function readonlyWhitelistPath(root = repoRoot) {
+    return join(root, READONLY_WHITELIST_RELATIVE_PATH);
+}

package/dist/services/skills/hooks-codegate-superpowers.d.ts

@@ -15,6 +15,7 @@ interface ResolvedHookSpec {
     readonly hookEnforceSentinel: string;
     readonly hookEnforceMatcher: string;
     readonly hookEnforceEvent: string;
+    readonly hookEnforceMcpMatcher: string | undefined;
     /**
      * True when the gate-enforce entry must be materialized into the IDE's
      * MACHINE-LOCAL settings file rather than the shared one (see

package/dist/services/skills/hooks-codegate-superpowers.js

@@ -8,6 +8,7 @@
  * type contract re-exported by the caller.
  */
 import { getAdapter } from '../ide/ide-registry.js';
+import { mcpHookMatcher } from '../ide/mcp-tool-matcher.js';
 import { HOOK_COMPACT_SETTLE_COMMAND, HOOK_COMPACT_SETTLE_EVENT, HOOK_COMPACT_SETTLE_MATCHER, HOOK_COMPACT_SETTLE_SENTINEL, HOOK_OUTER_CACHE_COMMAND, HOOK_OUTER_CACHE_EVENT, HOOK_OUTER_CACHE_SENTINEL, HOOK_POST_COMPACT_REINJECT_COMMAND, HOOK_POST_COMPACT_REINJECT_EVENT, HOOK_POST_COMPACT_REINJECT_MATCHER, HOOK_POST_COMPACT_REINJECT_SENTINEL, HOOK_WORKSPACE_INIT_COMMAND, HOOK_WORKSPACE_INIT_EVENT, HOOK_WORKSPACE_INIT_SENTINEL } from './session-start-hook-constants.js';
 /** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
 export const HOOK_ENFORCE_SENTINEL = 'peaks gate enforce';
@@ -87,6 +88,7 @@ export function resolveHookSpec(ide) {
         hookEnforceSentinel: spec.sentinel,
         hookEnforceMatcher: adapter.toolMatcher,
         hookEnforceEvent: adapter.hookEvent,
+        hookEnforceMcpMatcher: mcpHookMatcher(adapter),
         // Only Claude Code has the machine-local sibling settings file the
         // routing depends on, and only Claude Code's hook schema accepts a
         // `shell` key.
@@ -105,6 +107,27 @@ export const HOOK_CODE_GATE_SENTINEL = 'peaks code-gate';
 export const HOOK_CODE_GATE_MATCHER = 'Edit|Write|MultiEdit';
 export const HOOK_CODE_GATE_EVENT = 'PreToolUse';
 export const HOOK_CODE_GATE_COMMAND = `peaks code-gate --json`;
+/**
+ * The read-only MCP surface as a hook entry: the same command under the
+ * adapter's MCP matcher, or `undefined` for a harness that declares no MCP
+ * naming. A hook fires only for the matchers its OWN entry names, so without this
+ * entry the fail-closed branch in `mcp-surface-gate.ts` never runs on a live
+ * harness. A second entry rather than a wider matcher on the Bash one: that entry
+ * is mirrored by the workspace-init template, and widening it would put installer
+ * and template out of step.
+ */
+function mcpMatcherEntry(spec) {
+    if (spec.hookEnforceMcpMatcher === undefined)
+        return undefined;
+    return {
+        sentinel: spec.hookEnforceSentinel,
+        matcher: spec.hookEnforceMcpMatcher,
+        command: spec.hookEnforceCommand,
+        event: spec.hookEnforceEvent,
+        machineLocal: spec.hookEnforceMachineLocal,
+        ...(spec.hookEnforceShell !== undefined ? { shell: spec.hookEnforceShell } : {})
+    };
+}
 export function resolveHookEntries(ide, _skipProgress = false) {
     const spec = resolveHookSpec(ide);
     const entries = [
@@ -117,6 +140,9 @@ export function resolveHookEntries(ide, _skipProgress = false) {
             ...(spec.hookEnforceShell !== undefined ? { shell: spec.hookEnforceShell } : {})
         }
     ];
+    const mcpEntry = mcpMatcherEntry(spec);
+    if (mcpEntry !== undefined)
+        entries.push(mcpEntry);
     // ── Why the three SessionStart entries below carry NO `shell` pin ─────────
     //
     // The gate-enforce entry above is shell-pinned on Windows (see

package/dist/services/skills/hooks-settings-service.js

@@ -358,8 +358,16 @@ function shapeMatchesDesired(settings, entries, allPeaksSentinels) {
         //     source" — so a file written before matchers were explicit converges
         //     once instead of churning on every install.
         for (const desired of entries.filter((e) => e.event === eventKey)) {
-            const onDisk = peaksPresent.find((entry) => (entry.hooks ?? []).some((h) => String(h.command ?? '').includes(desired.sentinel)));
-            if (onDisk === undefined || (onDisk.matcher ?? '') !== desired.matcher)
+            // The identity of a desired entry is the PAIR (sentinel, matcher), not the
+            // sentinel alone: one command may legitimately be installed under several
+            // matchers (the read-only MCP surface rides `peaks gate enforce` under its
+            // own matcher set). Matching on the sentinel first found that first entry
+            // every time, so the second one never looked installed and every install
+            // rewrote the file. A wrong matcher is still un-repaired — it fails to
+            // match and the caller rewrites.
+            const onDisk = peaksPresent.find((entry) => (entry.matcher ?? '') === desired.matcher &&
+                (entry.hooks ?? []).some((h) => String(h.command ?? '').includes(desired.sentinel)));
+            if (onDisk === undefined)
                 return false;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.1.2",
+  "version": "4.1.3",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -75,16 +75,25 @@
     "scripts/copy-templates.mjs",
     "scripts/sync-version.mjs",
     "scripts/install-skills.mjs",
+    "scripts/install-skills-fs.mjs",
+    "scripts/install-skills-report.mjs",
+    "scripts/install-skills-user-config.mjs",
+    "scripts/install-skills-ide.mjs",
+    "scripts/install-skills-bundles.mjs",
+    "scripts/install-skills-output-styles.mjs",
+    "scripts/install-skills-output-style-default.mjs",
     "scripts/canonical-store.mjs",
     "scripts/canonical-store-link.mjs",
     "scripts/canonical-store-prune.mjs",
     "scripts/watch.mjs",
+    "scripts/watch-tree.mjs",
     "skills/**",
     "!skills/**/test-prompts.json",
     "!skills/**/.DS_Store",
     "output-styles/**",
     "agents/**",
     "schemas/*.json",
+    "contracts/readonly-argv-whitelist.json",
     ".claude-plugin/**",
     "config/eslint/.peaks-rules.cjs",
     "config/eslint/tsconfig.lint.json",
@@ -120,10 +129,10 @@
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.42",
-    "peaks-loop-shared-channel": "0.0.59",
-    "peaks-loop-mut": "0.1.56",
-    "peaks-loop-shared": "0.0.91"
+    "peaks-loop-internal-runtime": "0.0.43",
+    "peaks-loop-mut": "0.1.57",
+    "peaks-loop-shared-channel": "0.0.60",
+    "peaks-loop-shared": "0.0.92"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",
@@ -148,7 +157,9 @@
     "vitest": "^4.1.10"
   },
   "scripts": {
-    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && pnpm -r --filter \"./packages/*\" run build && node ./scripts/write-package-dist-stamps.mjs && tsc -p tsconfig.build.json && node ./scripts/copy-templates.mjs && node ./scripts/check-build-integrity.mjs && node ./scripts/write-dist-stamp.mjs",
+    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && pnpm -r --filter \"./packages/*\" run build && node ./scripts/write-package-dist-stamps.mjs && node node_modules/tsx/dist/cli.mjs scripts/generate-readonly-whitelist.ts && node node_modules/tsx/dist/cli.mjs scripts/generate-plugin-manifest.ts && tsc -p tsconfig.build.json && node ./scripts/copy-templates.mjs && node ./scripts/check-build-integrity.mjs && node ./scripts/write-dist-stamp.mjs",
+    "readonly:whitelist": "node node_modules/tsx/dist/cli.mjs scripts/generate-readonly-whitelist.ts",
+    "plugin:manifest": "node node_modules/tsx/dist/cli.mjs scripts/generate-plugin-manifest.ts",
     "prepublish": "node ./scripts/sync-version.mjs",
     "postinstall": "node ./scripts/install-skills.mjs",
     "predev": "node ./scripts/sync-version.mjs",

package/scripts/install-skills-bundles.mjs

@@ -0,0 +1,233 @@
+// scripts/install-skills-bundles.mjs
+//
+// The two installers that read a directory of bundled assets out of the package and
+// reconcile each entry into an IDE directory: the DIRECTORY-shaped family (skills) and
+// the FILE-shaped one (agents). Each owns its dispatch precedence and its repair rule.
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+import { existsSync, lstatSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { reconcileCanonicalEntry } from './canonical-store.mjs';
+import { reconcileCanonicalFileEntry } from './canonical-store-link.mjs';
+import { pruneBundledEntries } from './canonical-store-prune.mjs';
+import { createInstallResult } from './install-skills-report.mjs';
+import { createInstallRootValidator, resolvePackageRoot } from './install-skills-fs.mjs';
+import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
+
+/**
+ * THE INSTALL CANDIDATE LIST — every skill the package ships, as
+ * `{ skillName, sourcePath }`.
+ *
+ * After the v2.13.0 bee-demote (commit de0872b), the role skills (peaks-prd,
+ * peaks-rd, peaks-qa, peaks-ui, peaks-sc, peaks-txt) moved under
+ * `skills/bee/<role>/` while user-facing helpers stayed at `skills/<name>/`. So the
+ * list is built by walking top-level entries (user-facing helpers) AND
+ * `skills/bee/<role>` (demoted role skills). Each candidate is installed under its
+ * basename, so the postinstall links `~/.claude/skills/peaks-rd` to
+ * `skills/bee/peaks-rd` rather than to `skills/bee`.
+ *
+ * De-dupe rule: a top-level helper with the same name WINS, which preserves the
+ * existing install contract for any helper sharing a name with a demoted role skill
+ * (legacy overlap).
+ *
+ * @param {string} skillsRoot
+ * @returns {Array<{ skillName: string, sourcePath: string }>}
+ */
+function collectSkillCandidates(skillsRoot) {
+  const beeRoot = join(skillsRoot, 'bee');
+  /** @type {Array<{ skillName: string, sourcePath: string }>} */
+  const candidates = [];
+  for (const skillName of readdirSync(skillsRoot)) {
+    if (skillName === 'bee') continue;
+    const sourcePath = join(skillsRoot, skillName);
+    if (!isSkillSource(sourcePath)) continue;
+    candidates.push({ skillName, sourcePath });
+  }
+  if (existsSync(beeRoot) && isDirectoryEntry(beeRoot)) {
+    for (const skillName of readdirSync(beeRoot)) {
+      const sourcePath = join(beeRoot, skillName);
+      if (!isSkillSource(sourcePath)) continue;
+      if (candidates.some((c) => c.skillName === skillName)) continue;
+      candidates.push({ skillName, sourcePath });
+    }
+  }
+  return candidates;
+}
+
+/** A real directory entry — `lstat`, so a symlink to one is NOT one. */
+function isDirectoryEntry(entryPath) {
+  return lstatSync(entryPath).isDirectory();
+}
+
+/** A directory entry that is a skill: a real directory holding a `SKILL.md`. */
+function isSkillSource(sourcePath) {
+  return isDirectoryEntry(sourcePath) && existsSync(join(sourcePath, 'SKILL.md'));
+}
+
+export function installBundledSkills(options = {}) {
+  const packageRoot = resolvePackageRoot(options);
+  const skillsRoot = join(packageRoot, 'skills');
+
+  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(skillsRoot)) {
+    return createInstallResult();
+  }
+
+  // Slice #011: IDE-aware dispatch — the precedence itself now lives in ONE place
+  // (`resolveBundleTargetRoot` in `install-skills-ide.mjs`), because all three
+  // families stated it and only this one also warns.
+  const targetRoot = resolveBundleTargetRoot(options, {
+    profileField: 'skillsDir',
+    envVar: 'PEAKS_CLAUDE_SKILLS_DIR',
+    fallback: '.claude/skills',
+    warn: true
+  });
+
+  const installed = [];
+  const skipped = [];
+  mkdirSync(targetRoot, { recursive: true });
+  const validateSkillsRoot = createInstallRootValidator(targetRoot, 'Peaks skills');
+
+  const candidates = collectSkillCandidates(skillsRoot);
+
+  for (const { skillName, sourcePath } of candidates) {
+    const targetPath = join(targetRoot, skillName);
+
+    // Slice 2 (`agents-canonical-store`) — the entry points at the CANONICAL
+    // STORE (`~/.peaks/skills/<name>`), not at `<packageRoot>/skills/<name>`,
+    // because `<packageRoot>` changes on every `npm i -g peaks-loop@latest` and
+    // the links must bind to a PATH peaks-loop owns, not to a VERSION. Repair is
+    // the only behaviour: an entry peaks-loop owns (sidecar matches, or the link
+    // dangles) is relinked onto the store; only a real directory the user authored
+    // is left alone and reported `skipped`. `options.reconcileJunctions` is
+    // therefore READ NOWHERE here — still accepted (`sync-service.ts` forwards it)
+    // so passing it changes nothing, and removing it is a CLI-surface change this
+    // slice does not own.
+    validateSkillsRoot();
+    const reconciled = reconcileCanonicalEntry({
+      kind: 'skills',
+      name: skillName,
+      sourcePath,
+      linkPath: targetPath
+    });
+    validateSkillsRoot();
+
+    if (reconciled.linkAction === 'skipped') {
+      skipped.push(skillName);
+      continue;
+    }
+    installed.push(skillName);
+  }
+
+  // Slice 3 — PRUNE. The loop above only ever ADDS. A skill removed from the
+  // package left its canonical copy, every IDE link and every sidecar on the
+  // user's machine forever, because nothing walked the DESTINATIONS. This does,
+  // and deletes only what `isManagedEntry` proves is ours.
+  const { pruned } = pruneBundledEntries({
+    kind: 'skills',
+    keepNames: candidates.map((candidate) => candidate.skillName),
+    linkDirs: [targetRoot]
+  });
+
+  return { installed, skipped, pruned };
+}
+
+/**
+ * Slice 7/7 — bundled agents (Claude Code sub-agent prompts).
+ *
+ * Writes into the IDE's sub-agent loader directory (`~/.claude/agents/` for Claude
+ * Code, and whatever `agentsDir` the detected profile declares). The bytes live in
+ * the canonical store (`~/.peaks/agents/<name>`) and the IDE entry is a link to it.
+ *
+ * Ownership policy — ONE predicate, in `canonical-store-link.mjs::isOwnedFileEntry`,
+ * and it is deliberately not a string comparison:
+ *   - entry resolves to the canonical copy              → leave it (idempotent run)
+ *   - entry is a link we wrote (sidecar agrees, dangles) → relink onto the store
+ *   - entry is a real file with OUR sidecar beside it    → re-point it at the store
+ *   - entry is a real file with a LEGACY sidecar whose
+ *     recorded package path no longer resolves           → same: repair it
+ *   - entry is a real file we never wrote (no sidecar)   → skip (user-authored)
+ *   - entry is a real file whose sidecar names a path
+ *     that STILL resolves                                → skip (a second live install)
+ *
+ * The two "skip" arms above are the ones the old code got wrong in opposite
+ * directions: it skipped whenever the package path merely DIFFERED, which froze
+ * every entry on the first upgrade, silently and permanently. See
+ * `isOwnedFileEntry` for why a vanished package path is proof of an earlier install.
+ */
+export function installBundledAgents(options = {}) {
+  const packageRoot = resolvePackageRoot(options);
+  const agentsRoot = join(packageRoot, 'agents');
+
+  // Per-IDE env-var override (claude-code only today): PEAKS_CLAUDE_AGENTS_DIR.
+  // Universal escape hatch: PEAKS_SKIP_AGENT_INSTALL=1 (parallel to
+  // PEAKS_SKIP_SKILL_INSTALL).
+  if (
+    process.env.PEAKS_SKIP_SKILL_INSTALL === '1' ||
+    process.env.PEAKS_SKIP_AGENT_INSTALL === '1' ||
+    !existsSync(agentsRoot)
+  ) {
+    return createInstallResult();
+  }
+
+  // Slice #011: IDE-aware dispatch — same precedence as the other two families,
+  // resolved by the same helper (`resolveBundleTargetRoot`).
+  const targetRoot = resolveBundleTargetRoot(options, {
+    profileField: 'agentsDir',
+    envVar: 'PEAKS_CLAUDE_AGENTS_DIR',
+    fallback: '.claude/agents'
+  });
+
+  const installed = [];
+  const skipped = [];
+  const fallbacks = [];
+  mkdirSync(targetRoot, { recursive: true });
+  const validateAgentsRoot = createInstallRootValidator(targetRoot, 'Peaks agents');
+
+  // Slice 4 (`agents-canonical-store`) — the canonical store owns the bytes and the
+  // IDE entry points at it. Everything this loop used to decide about ownership is
+  // now `reconcileCanonicalFileEntry`'s, and the reason is the defect the brief
+  // names as this slice's core: the old test was
+  // `resolve(marker.sourcePath) === resolve(sourcePath)`, a STRING comparison against
+  // the package path of the installing version — a path with a node version inside it
+  // (`…\nvm\v24.21.0\node_modules\peaks-loop\agents\…`). It went false the first time
+  // the package moved and stayed false, so the agent silently never updated again.
+  const bundledAgentNames = [];
+  for (const agentFileName of readdirSync(agentsRoot)) {
+    const sourcePath = join(agentsRoot, agentFileName);
+    if (!lstatSync(sourcePath).isFile() || !agentFileName.endsWith('.md')) continue;
+    bundledAgentNames.push(agentFileName);
+
+    validateAgentsRoot();
+    const reconciled = reconcileCanonicalFileEntry({
+      kind: 'agents',
+      name: agentFileName,
+      sourcePath,
+      linkPath: join(targetRoot, agentFileName),
+      createFileLink: options.createFileLink
+    });
+    validateAgentsRoot();
+
+    if (reconciled.linkAction === 'skipped') {
+      skipped.push(agentFileName);
+      continue;
+    }
+    installed.push(agentFileName);
+    if (reconciled.fallback !== null) {
+      fallbacks.push({ name: agentFileName, ...reconciled.fallback });
+    }
+  }
+
+  // The delete half: an agent the package stops shipping used to leave its canonical
+  // copy, its IDE entry and both sidecars on the machine forever.
+  const { pruned } = pruneBundledEntries({
+    kind: 'agents',
+    keepNames: bundledAgentNames,
+    linkDirs: [targetRoot]
+  });
+
+  return { installed, skipped, pruned, fallbacks };
+}