peaks-loop 4.1.1 → 4.1.3

package/dist/shared/format-md-compact.d.ts

@@ -2,7 +2,6 @@
  * format-md-compact — single source of truth for whitespace / decoration
  * normalization across every CLI body-output path.
  *
- * Slice 023 (R3) — `peaks project memories:show`, `peaks retrospective show`,
  * and `peaks request show` (per-artifact) all funnel their `body` field through
  * this helper so the LLM-consumed output is free of blank-line padding,
  * decorative `---` rules, and frontmatter `description:` field-name repeats
@@ -11,7 +10,6 @@
  * inline emphasis, code spans).
  *
  * Pure function: no fs, no I/O. Easy to unit-test (see
- * `tests/unit/shared/format-md-compact.test.ts`).
  */
 export interface FormatMdCompactOptions {
     /** Preserve code-fence (``` ... ```) and frontmatter (--- ... ---) content. Default true. */

package/dist/shared/format-md-compact.js

@@ -2,7 +2,6 @@
  * format-md-compact — single source of truth for whitespace / decoration
  * normalization across every CLI body-output path.
  *
- * Slice 023 (R3) — `peaks project memories:show`, `peaks retrospective show`,
  * and `peaks request show` (per-artifact) all funnel their `body` field through
  * this helper so the LLM-consumed output is free of blank-line padding,
  * decorative `---` rules, and frontmatter `description:` field-name repeats
@@ -11,7 +10,6 @@
  * inline emphasis, code spans).
  *
  * Pure function: no fs, no I/O. Easy to unit-test (see
- * `tests/unit/shared/format-md-compact.test.ts`).
  */
 import { ATX_HEADING_RE, collapseMultiBlanks, computeSetextUnderlines, isDecorativeHorizontalRule, isFenceCloseLine, isFenceOpenLine, isTableLine, splitFrontmatter } from './format-md-compact-internals.js';
 const FENCE_TRIPLE_BACKTICK = '```';

package/dist/shared/incrementing-number.d.ts

@@ -19,7 +19,6 @@ export declare function getNextNumber(dirPath: string): number;
  * Exported separately so lookup paths (e.g. `request-artifact-service.ts`)
  * can compute the SAME slug the writer produced and match on-disk filenames
  * case-insensitively — the writer lowercases, so a mixed-case request id
- * like `2026-09-06-split-batchA` lands as `...-split-batcha.md`.
  */
 export declare function slugifyDescription(description: string): string;
 export declare function buildNumberedFilename(number: number, description: string): string;

package/dist/shared/incrementing-number.js

@@ -52,7 +52,6 @@ const MAX_FILENAME_SLUG_LENGTH = MAX_FILENAME_LENGTH - 7;
  * Exported separately so lookup paths (e.g. `request-artifact-service.ts`)
  * can compute the SAME slug the writer produced and match on-disk filenames
  * case-insensitively — the writer lowercases, so a mixed-case request id
- * like `2026-09-06-split-batchA` lands as `...-split-batcha.md`.
  */
 export function slugifyDescription(description) {
     return description

package/dist/shared/path-utils.d.ts

@@ -67,7 +67,6 @@ export declare function stablePath(path: string): string;
  * disk stays the real path (see `writeSessionFile`).
  *
  * Lifted from `src/services/session/session-manager.ts` in slice
- * `2026-08-04-rid-002-bridge-canonicalize` so both `session-manager.ts`
  * and `session-binding-bridge.ts` share a single canonicalization
  * authority.
  */

package/dist/shared/path-utils.js

@@ -116,7 +116,6 @@ export function stablePath(path) {
  * disk stays the real path (see `writeSessionFile`).
  *
  * Lifted from `src/services/session/session-manager.ts` in slice
- * `2026-08-04-rid-002-bridge-canonicalize` so both `session-manager.ts`
  * and `session-binding-bridge.ts` share a single canonicalization
  * authority.
  */

package/dist/shared/runtime-root.d.ts

@@ -1,7 +1,6 @@
 /**
  * The one seam through which a `.peaks/_runtime` path is built.
  *
- * Slice 2026-09-15 (runtime-path-unrepresentable). Three attempts to *detect*
  * a caller-supplied id reaching a runtime join all failed the same way: the
  * shipped text rule caught 4 of 12 fixture shapes where the name-based
  * predicate it replaced caught 8, and the version that reached 10 of 12 gave

package/dist/shared/runtime-root.js

@@ -1,7 +1,6 @@
 /**
  * The one seam through which a `.peaks/_runtime` path is built.
  *
- * Slice 2026-09-15 (runtime-path-unrepresentable). Three attempts to *detect*
  * a caller-supplied id reaching a runtime join all failed the same way: the
  * shipped text rule caught 4 of 12 fixture shapes where the name-based
  * predicate it replaced caught 8, and the version that reached 10 of 12 gave

package/dist/shared/stale-policy.d.ts

@@ -2,7 +2,6 @@
  * stale-policy — pure helper for stale detection and filtering on memory
  * and (future) retrospective entries.
  *
- * Slice 023 (R3) applies this to memory only (`peaks project memories:show`
  * and the underlying `readMemoryIndex` load path). The retrospective index
  * loader shares the same shape (`updatedAt: string`) and will be wired to
  * the same helper in a future slice.

package/dist/shared/stale-policy.js

@@ -2,7 +2,6 @@
  * stale-policy — pure helper for stale detection and filtering on memory
  * and (future) retrospective entries.
  *
- * Slice 023 (R3) applies this to memory only (`peaks project memories:show`
  * and the underlying `readMemoryIndex` load path). The retrospective index
  * loader shares the same shape (`updatedAt: string`) and will be wired to
  * the same helper in a future slice.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.1.1",
+  "version": "4.1.3",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -65,6 +65,7 @@
   },
   "files": [
     "bin/peaks.js",
+    "bin/node-floor.mjs",
     "dist/cli/index.js",
     "dist/**/*.js",
     "dist/**/*.d.ts",
@@ -74,13 +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",
@@ -105,22 +118,21 @@
     ]
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0"
   },
   "dependencies": {
     "@alibaba-group/open-code-review": "^1.8.9",
-    "@colbymchenry/codegraph": "0.7.10",
+    "@colbymchenry/codegraph": "1.6.2",
     "@upstash/context7-mcp": "^4.0.2",
-    "better-sqlite3": "^12.11.1",
     "commander": "^12.1.0",
     "fzf": "^0.5.2",
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.41",
-    "peaks-loop-mut": "0.1.55",
-    "peaks-loop-shared": "0.0.90",
-    "peaks-loop-shared-channel": "0.0.58"
+    "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",
@@ -128,8 +140,7 @@
     "@stryker-mutator/core": "^8.7.1",
     "@stryker-mutator/typescript-checker": "^8.7.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^22.10.2",
+    "@types/node": "^24.19.1",
     "@types/picomatch": "4.0.3",
     "@typescript-eslint/eslint-plugin": "8.66.0",
     "@typescript-eslint/parser": "8.66.0",
@@ -146,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/canonical-store-link.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+//
+// The canonical store's FILE-shaped entry point — one `.md` asset per entry, not a
+// tree. `canonical-store.mjs` owns the copy and the link for DIRECTORY assets
+// (skills, linked with a junction); this module owns them for `agents` and
+// `output-styles`, where the entry is a single file and the only link Windows will
+// take is a FILE SYMLINK, which needs developer mode or Administrator.
+//
+// WHY IT IS A SEPARATE MODULE — three behaviours with no counterpart in the
+// directory case, each one a place the slice could have gone silently wrong:
+//
+//   1. THE FALLBACK IS REPORTED. When the symlink is refused the entry is written as
+//      a REAL COPY — today's behaviour, reused — and the return value says
+//      `fallback: { mode: 'copy', … }`. A degradation that carries no reason is
+//      indistinguishable from a success; that lesson is already paid for here.
+//
+//   2. OWNERSHIP BY PROVENANCE, NOT BY STRING EQUALITY. The pre-canonical-store
+//      installer sidecarred `resolve(recorded) === resolve(sourcePath)` against the
+//      PACKAGE path of the installing version — measured on a real machine, a path
+//      with a NODE VERSION inside it (`…\nvm\v24.21.0\node_modules\…`). See
+//      `isOwnedLegacyEntry` for what replaced it, and why both of its arms matter.
+//
+//   3. A COPY MUST NOT FREEZE. The fallback copy is detected as ours and kept
+//      byte-equal to the canonical copy on every run, so a refusal still propagates
+//      upgrades. It does NOT retry the symlink: a retry deletes and rebuilds the file
+//      each run, which breaks the installer's mtime idempotence assertion.
+
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+import {
+  MANAGED_MARKER_SUFFIX,
+  ensureCanonicalCopy,
+  linkResolvesTo,
+  readManagedTarget,
+  writeManagedMarker
+} from './canonical-store.mjs';
+
+/** Codes that mean "this host refused to create the link", not "the link is wrong". */
+const LINK_REFUSED_CODES = new Set(['EPERM', 'EACCES', 'UNKNOWN', 'ENOTSUP', 'EINVAL']);
+
+/** The `kind` each family wrote into its pre-canonical-store JSON sidecar. */
+const LEGACY_MARKER_KIND = Object.freeze({ agents: 'agent', 'output-styles': 'output-style' });
+
+/** Scratch prefix for the atomic copy; never a valid asset name (assets start with a letter). */
+const TEMP_PREFIX = '.peaks-tmp-';
+
+function getPathStats(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    return null;
+  }
+}
+
+/** `\\?\C:\x` and `\\?\UNC\srv\share` are spellings of a path, not other paths. */
+function stripLongPathPrefix(value) {
+  const uncPrefix = '\\\\?\\UNC\\';
+  if (value.startsWith(uncPrefix)) return `\\\\${value.slice(uncPrefix.length)}`;
+  const prefix = '\\\\?\\';
+  return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}
+
+/** The resolved, case-folded identity of a path, or null when it does not resolve. */
+function resolveIdentity(path) {
+  let resolved;
+  try {
+    resolved = realpathSync(path);
+  } catch {
+    return null;
+  }
+  const normalized = stripLongPathPrefix(resolved);
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+/** Does the recorded provenance TEXT name the canonical entry? Realpath on both sides. */
+function provenanceNamesCanonicalPath(recorded, canonicalPath) {
+  if (typeof recorded !== 'string' || recorded.length === 0) return false;
+  const recordedIdentity = resolveIdentity(recorded);
+  const canonicalIdentity = resolveIdentity(canonicalPath);
+  return recordedIdentity !== null && recordedIdentity === canonicalIdentity;
+}
+
+/**
+ * The sidecar shape written before the canonical store existed: JSON naming the
+ * package path the file was copied from, plus a content hash. Parsed, never trusted.
+ */
+function parseLegacyMarker(recorded) {
+  if (typeof recorded !== 'string' || !recorded.startsWith('{')) return null;
+  try {
+    const marker = JSON.parse(recorded);
+    const assetName = marker?.agentName ?? marker?.outputStyleName;
+    if (marker?.version !== 1 || typeof marker.kind !== 'string') return null;
+    if (typeof assetName !== 'string' || typeof marker.sourcePath !== 'string') return null;
+    return { kind: marker.kind, assetName, sourcePath: marker.sourcePath };
+  } catch {
+    return null;
+  }
+}
+
+/** A link is ours when it points at the canonical copy, or when it points at nothing. */
+function isOwnedLink(entryPath, canonicalPath, recorded) {
+  if (linkResolvesTo(entryPath, canonicalPath)) return true;
+  if (!existsSync(entryPath)) return true;
+  return recorded !== null && linkResolvesTo(entryPath, recorded);
+}
+
+/**
+ * The LEGACY arm of the ownership test, and the fix for the freeze this slice exists
+ * to close. A recorded package path is a version-scoped fact, so it can only be
+ * describing one of two things, and BOTH of them are ours:
+ *
+ *   a recorded path that NO LONGER RESOLVES  — an earlier peaks-loop install, whose
+ *       package has since been replaced or removed. This is the arm the old code
+ *       lacked entirely: it demanded string equality with the path of the version
+ *       installing RIGHT NOW, so from the first `npm i -g peaks-loop@latest` onward
+ *       the comparison was false and stayed false, freezing the agent with no error.
+ *   a recorded path that IS the package we are installing from — the in-place upgrade
+ *       (`npm i -g` replacing the same directory). Here the old string comparison was
+ *       TRUE, but the code still skipped: it only reached the rewrite branch when the
+ *       content hash MATCHED (`getManagedPeaksAgentIdentity` returns null on any hash
+ *       difference), so it rewrote identical bytes and skipped every real upgrade —
+ *       the opposite of the "SHA differs → overwrite" its own comment promised.
+ *
+ * A recorded path that resolves to some OTHER live package stays untouched: that is a
+ * second installation, not a stale one, and taking it over would be a regression.
+ * Compared through `resolveIdentity` — realpath, `\\?\` stripped, case-folded — never
+ * by string: two spellings of the same path are one path, and the s2 slice already paid
+ * for that lesson.
+ */
+function isOwnedLegacyEntry({ kind, name, legacy, sourcePath }) {
+  if (legacy === null) return false;
+  if (legacy.kind !== LEGACY_MARKER_KIND[kind]) return false;
+  if (legacy.assetName !== name) return false;
+  const recordedIdentity = resolveIdentity(legacy.sourcePath);
+  if (recordedIdentity === null) return true;
+  return recordedIdentity === resolveIdentity(sourcePath);
+}
+
+/**
+ * May peaks-loop replace or delete `entryPath`? A real directory, a foreign link and a
+ * file with no sidecar are all "no".
+ *
+ *   A LINK — ours when it resolves to the canonical copy, when it DANGLES (a link whose
+ *            target is gone is still a link we wrote), or when the sidecar's recorded
+ *            path is what it resolves to. Identity is `realpath`, never the string:
+ *            `\\?\` prefixes and case spellings differ from call to call.
+ *   A FILE — ours when the sidecar beside it says so: either it names the canonical
+ *            path (what this module writes), or it is the legacy shape above.
+ */
+function isOwnedFileEntry({ entryPath, canonicalPath, kind, name, sourcePath, recorded }) {
+  const stats = getPathStats(entryPath);
+  if (!stats) return false;
+  if (stats.isSymbolicLink()) return isOwnedLink(entryPath, canonicalPath, recorded);
+  if (recorded === null) return false;
+  if (provenanceNamesCanonicalPath(recorded, canonicalPath)) return true;
+  return isOwnedLegacyEntry({ kind, name, legacy: parseLegacyMarker(recorded), sourcePath });
+}
+
+/** True when `entryPath` already holds exactly the bytes the canonical copy holds. */
+function holdsCanonicalBytes(entryPath, canonicalPath) {
+  try {
+    return readFileSync(entryPath).equals(readFileSync(canonicalPath));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * What is at the entry path right now, as one of four verdicts the caller acts on:
+ * `absent` (write a link or the fallback copy), `foreign` (leave it alone), `copy` (a
+ * real copy WE wrote on a host that refused a link, already current) or `ours` (ours,
+ * but not the link we want — replace it). `stats` tells "link" from "repair".
+ */
+function existingEntryVerdict({ entryPath, canonicalPath, kind, name, sourcePath }) {
+  const stats = getPathStats(entryPath);
+  if (stats === null) return { stats: null, verdict: 'absent' };
+  const recorded = readManagedTarget(entryPath);
+  if (!isOwnedFileEntry({ entryPath, canonicalPath, kind, name, sourcePath, recorded })) {
+    return { stats, verdict: 'foreign' };
+  }
+  const settled =
+    !stats.isSymbolicLink() &&
+    provenanceNamesCanonicalPath(recorded, canonicalPath) &&
+    holdsCanonicalBytes(entryPath, canonicalPath);
+  return { stats, verdict: settled ? 'copy' : 'ours' };
+}
+
+/** Write the canonical bytes beside the entry and swap them in, so no reader sees half. */
+function writeRealCopy(canonicalPath, entryPath) {
+  mkdirSync(dirname(entryPath), { recursive: true });
+  const tempPath = `${entryPath}${TEMP_PREFIX}${randomUUID()}`;
+  writeFileSync(tempPath, readFileSync(canonicalPath));
+  renameSync(tempPath, entryPath);
+}
+
+/** A settled fallback copy: nothing to fix, but the degradation must still be visible. */
+function settledCopyResult({ copied, entryPath }) {
+  return {
+    ...copied,
+    linkAction: 'copied',
+    fallback: {
+      mode: 'copy',
+      code: null,
+      reason: `${entryPath} is a real copy: this host refused the symlink on an earlier run`
+    }
+  };
+}
+
+/**
+ * Replace whatever is at the entry path with a link to `copied.canonicalPath` — or,
+ * when this host refuses the link, with a real copy plus a reported reason.
+ */
+function linkOrCopyEntry({ copied, linkPath, current, createFileLink }) {
+  if (current !== null) {
+    unlinkSync(linkPath);
+    const markerPath = `${linkPath}${MANAGED_MARKER_SUFFIX}`;
+    if (existsSync(markerPath)) unlinkSync(markerPath);
+  }
+  mkdirSync(dirname(linkPath), { recursive: true });
+  try {
+    createFileLink(copied.canonicalPath, linkPath, 'file');
+    writeManagedMarker(linkPath, copied.canonicalPath);
+    return { ...copied, linkAction: current === null ? 'linked' : 'repaired', fallback: null };
+  } catch (error) {
+    const code = error?.code;
+    if (!LINK_REFUSED_CODES.has(code)) throw error;
+    writeRealCopy(copied.canonicalPath, linkPath);
+    // Provenance records the CANONICAL path even here, so a later run recognises the
+    // copy as ours and keeps it current instead of reading it as user-authored.
+    writeManagedMarker(linkPath, copied.canonicalPath);
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ...copied,
+      linkAction: 'copied',
+      fallback: {
+        mode: 'copy',
+        code: code ?? null,
+        reason: `${linkPath} could not be linked: ${message}`
+      }
+    };
+  }
+}
+
+/**
+ * Store one single-file asset canonically, then point the IDE entry at that copy —
+ * a symlink when the host allows one, a real copy when it does not.
+ *
+ * @param {{
+ *   kind: 'agents' | 'output-styles',
+ *   name: string,
+ *   sourcePath: string,
+ *   linkPath?: string,
+ *   createFileLink?: (target: string, path: string, type: string) => void
+ * }} options
+ *   `createFileLink` exists so the refused-symlink arm can be MEASURED on a host where
+ *   symlinks are permitted (this one). Without it the fallback branch would be
+ *   unreachable in the test suite, and an unverified branch is an unverified claim.
+ *   Defaults to `fs.symlinkSync`.
+ */
+export function reconcileCanonicalFileEntry(options) {
+  const { kind, name, sourcePath, linkPath } = options;
+  const copied = ensureCanonicalCopy({ kind, name, sourcePath });
+  const skipped = { ...copied, linkAction: 'skipped', fallback: null };
+  if (copied.action === 'unmanaged') return skipped;
+  if (typeof linkPath !== 'string' || linkPath.length === 0) return skipped;
+  if (linkResolvesTo(linkPath, copied.canonicalPath)) {
+    return { ...copied, linkAction: 'unchanged', fallback: null };
+  }
+  const entry = existingEntryVerdict({
+    entryPath: linkPath,
+    canonicalPath: copied.canonicalPath,
+    kind,
+    name,
+    sourcePath
+  });
+  if (entry.verdict === 'foreign') return skipped;
+  if (entry.verdict === 'copy') return settledCopyResult({ copied, entryPath: linkPath });
+  return linkOrCopyEntry({
+    copied,
+    linkPath,
+    current: entry.stats,
+    createFileLink: options.createFileLink ?? symlinkSync
+  });
+}

package/scripts/canonical-store-prune.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+//
+// PRUNE — the delete half of the canonical store (`scripts/canonical-store.mjs`).
+//
+// WHY. Until this slice the installer only ever ADDED. When a skill left the package,
+// its canonical copy, every IDE link to it and every `.peaks-managed` sidecar stayed
+// on the user's machine forever: `installBundledSkills` walked the package's skill
+// list and had no loop that walked the DESTINATIONS. This module is that loop.
+//
+// THE WHOLE RISK IS THE WORD "ONLY". A prune that is one predicate too wide is, from
+// outside, indistinguishable from a correct one — both print success and both leave
+// a shorter listing. So ownership is never inferred from "the name is not in the
+// package": it is asked of ONE predicate, `isManagedEntry` in `canonical-store.mjs`,
+// which demands a `.peaks-managed` marker beside the entry. A real directory the user
+// authored — including one that reuses a retired skill's name — carries no marker,
+// survives byte for byte, and is reported `kept` rather than silently dropped. The
+// negative control in `tests/unit/ide/install-skills-prune.test.ts` is that directory.
+//
+// It is also the shape `ensureCanonicalCopy` deletes behind: that function used to run
+// `rmSync(canonicalPath, ...)` with no ownership test at all, which today is
+// unreachable only because no bundled asset is named `ecc` — while `~/.peaks/agents/`
+// really does hold a user ECC tree under that name. Both delete paths now gate on the
+// same predicate.
+//
+// Idempotent by construction: prune is driven by a name set, not by a marker that
+// says "already pruned", so a second run finds nothing and moves no mtime.
+
+import { existsSync, lstatSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { MANAGED_MARKER_SUFFIX, isManagedEntry, resolveKindRoot } from './canonical-store.mjs';
+
+/** Every name directly under `dir`, sorted, or `[]` when `dir` does not exist. */
+function listEntryNames(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).sort();
+}
+
+/** Remove `entryPath`, following a link instead of the tree it points at. */
+function removeEntry(entryPath) {
+  if (lstatSync(entryPath).isSymbolicLink()) {
+    unlinkSync(entryPath);
+  } else {
+    rmSync(entryPath, { recursive: true, force: true });
+  }
+  const markerPath = `${entryPath}${MANAGED_MARKER_SUFFIX}`;
+  if (existsSync(markerPath)) unlinkSync(markerPath);
+}
+
+/**
+ * Drop every CANONICAL entry of one kind that peaks-loop owns and the package no
+ * longer ships. `keepNames` is what this run of the package shipped.
+ *
+ * @param {{ kind: string, keepNames: readonly string[], root?: string }} options
+ */
+export function pruneCanonicalEntries(options) {
+  const { kind, keepNames } = options;
+  const kindRoot = resolveKindRoot(kind, options);
+  const keep = new Set(keepNames);
+  const pruned = [];
+  const kept = [];
+
+  for (const name of listEntryNames(kindRoot)) {
+    const entryPath = join(kindRoot, name);
+    if (name.endsWith(MANAGED_MARKER_SUFFIX)) {
+      // A sidecar whose asset is gone and whose name the package does not claim is
+      // ours with nothing left to describe — the leftover of a partial install. The
+      // last `existsSync` is load-bearing: the branch below removes a retired entry
+      // AND its sidecar, and this listing is a snapshot taken before that happened.
+      const base = name.slice(0, -MANAGED_MARKER_SUFFIX.length);
+      if (!keep.has(base) && !existsSync(join(kindRoot, base)) && existsSync(entryPath)) {
+        unlinkSync(entryPath);
+        pruned.push(`${kind}/${base}`);
+      }
+      continue;
+    }
+    if (keep.has(name)) continue;
+    if (!isManagedEntry(entryPath)) {
+      kept.push(name);
+      continue;
+    }
+    removeEntry(entryPath);
+    pruned.push(`${kind}/${name}`);
+  }
+  return { pruned, kept };
+}
+
+/**
+ * Drop every IDE entry in `linkDir` that peaks-loop owns and the package no longer
+ * ships. A real directory the user authored is never a candidate: it has no marker.
+ *
+ * @param {{ linkDir: string, keepNames: readonly string[] }} options
+ */
+export function pruneLinkedEntries(options) {
+  const { linkDir, keepNames } = options;
+  const keep = new Set(keepNames);
+  const pruned = [];
+  const kept = [];
+
+  for (const name of listEntryNames(linkDir)) {
+    if (name.endsWith(MANAGED_MARKER_SUFFIX)) continue;
+    if (keep.has(name)) continue;
+    const linkPath = join(linkDir, name);
+    if (!isManagedEntry(linkPath)) {
+      kept.push(`${linkDir}/${name}`);
+      continue;
+    }
+    removeEntry(linkPath);
+    pruned.push(`${linkDir}/${name}`);
+  }
+  return { pruned, kept };
+}
+
+/**
+ * The installer's entry point for this module: prune one asset family's canonical
+ * store AND every IDE directory that links into it.
+ *
+ * @param {{ kind: string, keepNames: readonly string[], linkDirs?: readonly string[], root?: string }} options
+ */
+export function pruneBundledEntries(options) {
+  const { keepNames, linkDirs = [] } = options;
+  const canonical = pruneCanonicalEntries({ ...options, keepNames });
+  const pruned = [...canonical.pruned];
+  const kept = [...canonical.kept];
+  for (const linkDir of linkDirs) {
+    const linked = pruneLinkedEntries({ linkDir, keepNames });
+    pruned.push(...linked.pruned);
+    kept.push(...linked.kept);
+  }
+  return { pruned, kept };
+}