peaks-loop 4.1.1 → 4.1.2

package/dist/services/workspace/workspace-service.js

@@ -8,7 +8,6 @@ import { resolveCallerProjection } from '../session/resolve-caller-id.js';
 import { normalizePath } from '../../shared/path-utils.js';
 import { assertWritableProjectRoot } from '../config/config-safety.js';
 /**
- * Slice 2026-09-10 (rid=rebind-must-update-caller-binding): repoint the
  * calling process's own per-caller binding at the session id this init just
  * bound. `getSessionIdCanonical` reads `callers/<callerId>.json` FIRST, so a
  * binding left behind by an earlier session shadows every explicit rebind.
@@ -31,7 +30,6 @@ function rebindCurrentCallerBinding(projectRoot, sessionId) {
     return updateCallerBindingSessionId(projectRoot, callerId, sessionId);
 }
 /**
- * Slice 2026-06-29-change-id-root-removal: list the immediate children of
  * `.peaks/` so the legacy sibling-dir guard can enumerate date-stamped
  * residue dirs without re-implementing `readdirSync` inline. Returns
  * `[]` when the `.peaks/` dir does not exist (legitimate first-run
@@ -49,7 +47,6 @@ function listPeaksRuntimeSiblings(projectRoot) {
     }
 }
 /**
- * Slice 2026-06-29-change-id-root-removal: list the immediate children of
  * `.peaks/_runtime/` so the legacy sibling-dir guard can enumerate
  * date-stamped residue dirs at the runtime layer. Returns `[]` when
  * the `.peaks/_runtime/` dir does not exist.
@@ -66,7 +63,6 @@ function listRuntimeSiblings(projectRoot) {
     }
 }
 /**
- * Slice 2026-06-29-change-id-root-removal: returns `true` when the
  * basename matches the auto-generated session-id shape
  * `YYYY-MM-DD-<slug>` (the v2.8.3 hard-ban target). Bare dates
  * (`YYYY-MM-DD`) are NOT auto-generated and are kept as plain dates.
@@ -78,7 +74,6 @@ function isDateStampedSiblingId(name) {
         return false;
     return true;
 }
-// Slice 2026-06-29-change-id-root-removal: `setCurrentChangeId` and
 // `validateChangeIdOrThrow` were removed with the change-id axis. Init
 // preserves the legacy-sibling-dir guard via inline `lstatSync`; the
 // path-safety helpers moved to `shared/path-safety.ts` but this module
@@ -97,7 +92,6 @@ const PROHIBITED_SUFFIXES = [
 // Auto-generated session ID pattern: YYYY-MM-DD-session-<6位hex>
 const AUTO_SESSION_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]{6}$/;
 /**
- * Slice C10 (2026-06-24-legacy-change-id-sibling): the relative path
  * patterns under `.peaks/_runtime/<sessionId>/` that the lazy WRITER (peaks-qa,
  * peaks-rd, peaks-prd, peaks-txt, peaks-sc) creates via
  * `mkdir(parent, { recursive: true })` immediately before a write. When
@@ -196,9 +190,6 @@ export async function initWorkspace(options) {
     // the user's home. Enforced here as well as at the CLI so a non-CLI caller
     // cannot reach the same write by another door.
     assertWritableProjectRoot(options.projectRoot);
-    // Phase 6 refactor (slice 2026-06-05-change-id-as-unit-of-work) +
-    // slice 006 (2026-06-06-change-folder-simplify-and-lazy-role-subdirs) +
-    // slice 2026-06-22-top-level-change-id-cleanup (2.8.3):
     //   - Reviewable artifacts (rd/, qa/, prd/, txt/) live at
     //     `.peaks/_runtime/<change-id>/<role>/` (tracked in git) when a change-id
     //     is given. The role subdirs are NOT pre-created — the writer
@@ -206,7 +197,6 @@ export async function initWorkspace(options) {
     //     dirs on demand via `mkdirSync(..., { recursive: true })`.
     //   - The session dir `.peaks/_runtime/<session-id>/` (gitignored)
     //     now holds ONLY the canonical `session.json` metadata. The
-    //     F3-introduced `system/` subdir is gone — slice 006 removes
     //     it via `peaks workspace reconcile`; new init calls do not
     //     pre-create it.
     //   - The change-id dir is NOT created at top level when `--change-id`
@@ -227,7 +217,6 @@ export async function initWorkspace(options) {
     const alreadyExisted = [];
     // 1. Create the session dir (canonical location `.peaks/_runtime/<sid>/`)
     //    with NO subdirs. The session dir is gitignored; the role
-    //    subdirs and the `system/` subdir are gone entirely (slice 006).
     if (await isDirectory(sessionRoot)) {
         alreadyExisted.push('.');
     }
@@ -235,13 +224,11 @@ export async function initWorkspace(options) {
         await mkdir(sessionRoot, { recursive: true });
         created.push('.');
     }
-    // 1a. Write the per-session metadata file. Slice 006 makes
     //     `.peaks/_runtime/<sid>/session.json` the durable session
     //     metadata (the body's source of truth, the `peaks workspace
     //     reconcile` discovery source). The file is created on first
     //     init and refreshed on every subsequent init. Idempotent.
     setSessionMeta(options.projectRoot, options.sessionId, {});
-    // 2. Slice 2026-06-29-change-id-root-removal: the change-id axis is
     //    gone. The session id IS the binding — there is no separate
     //    `.peaks/_runtime/current-change` file. The v2.8.3 hard-ban on
     //    `.peaks/<YYYY-MM-DD-*>/` siblings still fires via the inline
@@ -339,7 +326,6 @@ export async function initWorkspace(options) {
         // Either: existing session dir is empty (true leftover, no user data),
         // or the caller explicitly authorised a rebind. Overwrite.
         setCurrentSessionBinding(options.projectRoot, options.sessionId);
-        // Slice 2026-09-10 (rid=rebind-must-update-caller-binding): an
         // explicit rebind must ALSO repoint this caller's per-caller binding.
         // `getSessionIdCanonical` prefers `callers/<callerId>.json`, so leaving
         // it untouched shadowed the rebind for every command resolving through
@@ -350,7 +336,6 @@ export async function initWorkspace(options) {
         rebindCurrentCallerBinding(options.projectRoot, options.sessionId);
         bound = true;
     }
-    // Slice 2026-06-16-peaks-code-auto-scaffold (RD#7):
     //   - Always run the detector and surface the descriptor so the CLI can
     //     put it on stderr + into the JSON envelope's `data.standardsMissing`.
     //   - When `initStandards: true` AND the detector reports missing, run
@@ -404,7 +389,6 @@ import { materializeClaudeSettingsLocal } from './workspace-claude-settings-mate
 export { materializeClaudeSettingsLocal } from './workspace-claude-settings-materializer.js';
 import { writeGeneratedArtifactsStamp } from './generated-artifacts-stamp.js';
 /**
- * Slice C10 (2026-06-24-legacy-change-id-sibling): whole-dir shape check
  * for the legacy sibling `.peaks/_runtime/<sessionId>/`. Returns `true` ONLY when
  * every leaf path under the sibling matches one of
  * `WRITER_ALLOWED_RELATIVE_PATTERNS` AND no entry is a symlink (anywhere

package/dist/services/worktree/playwright-profile.js

@@ -2,7 +2,6 @@
  * playwright-profile — deterministic Chromium user-data-dir +
  * profile-name pair generator for a (session, dispatch) tuple.
  *
- * Slice 2026-08-01-subagent-merge-and-e2e (Task 2). Each sub-agent
  * dispatch with `--isolation worktree` MUST land its Playwright MCP
  * browser session in a unique Chromium profile so concurrent
  * dispatches do not share cookies / localStorage / IndexedDB. The

package/dist/services/worktree/worktree-lease-types.d.ts

@@ -2,7 +2,6 @@
  * worktree-lease-types — the pure declaration surface of the worktree lease
  * store (`worktree-lease.ts`).
  *
- * Slice 2026-07-29-worktree-l2-extended Part 1 owns the lease behavior; this
  * module owns only the shapes (lifecycle status, lease record, creation draft,
  * and the list-read result). `worktree-lease.ts` imports and re-exports every
  * name here, so importers keep resolving them from the original path.

package/dist/services/worktree/worktree-lease-types.js

@@ -2,7 +2,6 @@
  * worktree-lease-types — the pure declaration surface of the worktree lease
  * store (`worktree-lease.ts`).
  *
- * Slice 2026-07-29-worktree-l2-extended Part 1 owns the lease behavior; this
  * module owns only the shapes (lifecycle status, lease record, creation draft,
  * and the list-read result). `worktree-lease.ts` imports and re-exports every
  * name here, so importers keep resolving them from the original path.

package/dist/services/worktree/worktree-lease.d.ts

@@ -1,7 +1,6 @@
 /**
  * worktree-lease — pure-function lease store for `peaks worktree spawn`.
  *
- * Slice 2026-07-29-worktree-l2-extended Part 1. This is the Layer 2
  * governance complement to Layer 3 (`permissions.deny` for the superpowers
  * chain) and Layer 1 (sub-agent dispatch prompt refusal). Together the
  * three layers close the superpowers-chain jailbreak that previously
@@ -11,7 +10,6 @@
  * directory path as an argument and returns structured data. Atomic
  * filesystem writes happen at the call site (CLI command), keeping the
  * helpers trivially testable. The CLI surface lives in
- * `src/cli/commands/worktree-spawn-commands.ts`.
  *
  * Why a separate lease (vs reusing `peaks worktree auth grant`):
  * - `auth grant` is a single-shot, short-lived token file consulted by

package/dist/services/worktree/worktree-lease.js

@@ -1,7 +1,6 @@
 /**
  * worktree-lease — pure-function lease store for `peaks worktree spawn`.
  *
- * Slice 2026-07-29-worktree-l2-extended Part 1. This is the Layer 2
  * governance complement to Layer 3 (`permissions.deny` for the superpowers
  * chain) and Layer 1 (sub-agent dispatch prompt refusal). Together the
  * three layers close the superpowers-chain jailbreak that previously
@@ -11,7 +10,6 @@
  * directory path as an argument and returns structured data. Atomic
  * filesystem writes happen at the call site (CLI command), keeping the
  * helpers trivially testable. The CLI surface lives in
- * `src/cli/commands/worktree-spawn-commands.ts`.
  *
  * Why a separate lease (vs reusing `peaks worktree auth grant`):
  * - `auth grant` is a single-shot, short-lived token file consulted by

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.2",
   "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,6 +75,9 @@
     "scripts/copy-templates.mjs",
     "scripts/sync-version.mjs",
     "scripts/install-skills.mjs",
+    "scripts/canonical-store.mjs",
+    "scripts/canonical-store-link.mjs",
+    "scripts/canonical-store-prune.mjs",
     "scripts/watch.mjs",
     "skills/**",
     "!skills/**/test-prompts.json",
@@ -105,22 +109,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.42",
+    "peaks-loop-shared-channel": "0.0.59",
+    "peaks-loop-mut": "0.1.56",
+    "peaks-loop-shared": "0.0.91"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",
@@ -128,8 +131,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",

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
+  });
+}