@lh8ppl/claude-memory-kit 0.3.5 → 0.4.1

package/src/lazy-compress.mjs

@@ -29,9 +29,7 @@ import {
   existsSync,
   mkdirSync,
   readdirSync,
-  readFileSync,
   statSync,
-  writeFileSync,
   unlinkSync,
 } from 'node:fs';
 import { join } from 'node:path';
@@ -46,44 +44,58 @@ import { weeklyCurate } from './weekly-curate.mjs';
 import { compressSession } from './compress-session.mjs';
 import { CEILING_FREE_TIMEOUT_MS, CEILING_FREE_BACKOFF_MS } from './compress-retry.mjs';
 import { syncDecisionsJournal } from './decisions-journal.mjs';
+import {
+  isCompactionNeeded,
+  recordCronHeartbeat,
+  cronHeartbeatPath,
+} from './compaction-state.mjs';
 
 const DEFAULT_DAILY_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const DEFAULT_WEEKLY_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
-const SESSIONS_REL = ['context', 'sessions'];
 const LOCKS_REL = ['context', '.locks'];
-const NOW_MD_REL = ['context', 'sessions', 'now.md'];
-const RECENT_MD_REL = ['context', 'sessions', 'recent.md'];
-const CRON_SENTINEL_REL = ['context', '.locks', 'cron-registered'];
 const LAZY_LOG_REL = ['context', '.locks', 'lazy-compress.log'];
 
-const TODAY_RE = /^today-(\d{4}-\d{2}-\d{2})\.md$/;
+// Task 167 (D-206/D-207): the cron-liveness gate moved from a presence-only
+// `cron-registered` sentinel to an anacron-style `cron-heartbeat` (in
+// compaction-state.mjs), gated on AGE not existence — a registered-but-dead cron
+// no longer disables the lazy roll. These three exports are kept as thin
+// back-compat shims so existing callers (register-crons / doctor / subcommands /
+// tests) keep working; they now operate on the heartbeat.
+//
+// **Decision-trail (the retired sentinel):** the old `cron-registered` marker
+// recorded "a cron was REGISTERED" (written once at register-crons time, never
+// updated). detectStaleness short-circuited to 'cron-active' on its mere
+// existence — so a cron that never actually fired (laptop asleep at 23:00)
+// disabled the lazy fallback forever and now.md grew to 410 KB (the v0.4.0
+// dogfood). The heartbeat records "a run HAPPENED" and is re-stamped each fire.
 
 /**
- * Path helper for the cron-registered sentinel marker file. Public so
- * register-crons.mjs can write/remove it without re-deriving the path.
+ * Back-compat alias for the cron-liveness marker path. Now points at the
+ * `cron-heartbeat` stamp (was `cron-registered`). Retained for callers that still
+ * import it; prefer `cronHeartbeatPath` from compaction-state.mjs in new code.
  */
 export function cronSentinelPath(projectRoot) {
-  return join(projectRoot, ...CRON_SENTINEL_REL);
+  return cronHeartbeatPath(projectRoot);
 }
 
 /**
- * Write the cron-registered sentinel marker. Called by registerCron
- * after a successful host-scheduler registration.
+ * Record that the cron is alive. Now writes the anacron-style heartbeat (was: a
+ * one-time registration sentinel). `register-crons` calls it on registration so a
+ * just-registered cron reads alive until its first real run re-stamps it; the
+ * cron BINS also call `recordCronHeartbeat` on each fire (the durable liveness
+ * signal). Both go to the same stamp.
  */
 export function markCronRegistered({ projectRoot }) {
-  if (!projectRoot) return;
-  const locksDir = join(projectRoot, ...LOCKS_REL);
-  mkdirSync(locksDir, { recursive: true });
-  writeFileSync(cronSentinelPath(projectRoot), nowIso() + '\n', 'utf8');
+  recordCronHeartbeat({ projectRoot });
 }
 
 /**
- * Remove the cron-registered sentinel marker. Called by unregisterCron.
- * Best-effort — if the marker is missing, that's already the desired state.
+ * Remove the cron-liveness heartbeat (on unregister). Best-effort — a missing
+ * stamp is already the desired "no live cron" state.
  */
 export function unmarkCronRegistered({ projectRoot }) {
   if (!projectRoot) return;
-  const path = cronSentinelPath(projectRoot);
+  const path = cronHeartbeatPath(projectRoot);
   if (existsSync(path)) {
     try {
       unlinkSync(path);
@@ -93,18 +105,6 @@ export function unmarkCronRegistered({ projectRoot }) {
   }
 }
 
-function listTodayFiles(projectRoot) {
-  const sessionsDir = join(projectRoot, ...SESSIONS_REL);
-  if (!existsSync(sessionsDir)) return [];
-  const matches = [];
-  for (const name of readdirSync(sessionsDir)) {
-    const m = TODAY_RE.exec(name);
-    if (!m) continue;
-    matches.push({ name, date: m[1], path: join(sessionsDir, name) });
-  }
-  return matches;
-}
-
 // Task 105 (D-75): does now.md carry prior-session content? The now→today
 // roll (compressSession) fires only at SessionEnd, and Claude Code fires
 // SessionEnd ONLY on a clean window-close — so a never-cleanly-closed session
@@ -114,25 +114,10 @@ function listTodayFiles(projectRoot) {
 // capture-turn writes haven't fired yet), so non-empty ⇒ stale. Emptiness must
 // match compressSession's own `buffer.trim() === ''` check so the spawn verdict
 // and the actual roll agree (else we'd spawn for a roll that immediately skips).
-function nowMdHasContent(projectRoot) {
-  const p = join(projectRoot, ...NOW_MD_REL);
-  if (!existsSync(p)) return false;
-  try {
-    return readFileSync(p, 'utf8').trim() !== '';
-  } catch {
-    return false;
-  }
-}
-
-function recentMdMtimeMs(projectRoot) {
-  const p = join(projectRoot, ...RECENT_MD_REL);
-  if (!existsSync(p)) return null;
-  try {
-    return statSync(p).mtimeMs;
-  } catch {
-    return null;
-  }
-}
+// Task 167 (D-207): nowMdHasContent / recentMdMtimeMs / listTodayFiles + the
+// now/daily/weekly derive logic moved to compaction-state.mjs (the deep module
+// that owns the verdict). detectStaleness now delegates there; only isJournalStale
+// (an INDEPENDENT signal, not part of the compaction verdict) stays here.
 
 const MEMORY_REL = ['context', 'memory'];
 const DECISIONS_MD_REL = ['context', 'DECISIONS.md'];
@@ -210,66 +195,14 @@ export function detectStaleness({
   dailyTtlMs = DEFAULT_DAILY_TTL_MS,
   weeklyTtlMs = DEFAULT_WEEKLY_TTL_MS,
 } = {}) {
-  if (!projectRoot) {
-    return { action: 'no-context-dir', reason: 'missing-project-root' };
-  }
-  // Cron sentinel short-circuits everything.
-  if (existsSync(cronSentinelPath(projectRoot))) {
-    return { action: 'cron-active', reason: 'cron-sentinel-present' };
-  }
-  const sessionsDir = join(projectRoot, ...SESSIONS_REL);
-  if (!existsSync(sessionsDir)) {
-    return { action: 'no-context-dir', reason: 'sessions-dir-missing' };
-  }
-
-  // Task 105 (D-75): a non-empty now.md is the now→today roll the SessionEnd
-  // hook would have done. It takes PRECEDENCE over daily/weekly because it's
-  // the FIRST pipeline level (now → today → recent → archive) — roll it this
-  // SessionStart; the today→recent + weekly levels cascade on subsequent
-  // SessionStarts once now.md is drained. (cron-active above still wins — a
-  // registered cron owns the whole pipeline.)
-  if (nowMdHasContent(projectRoot)) {
-    return { action: 'stale-now', reason: 'now-md-has-prior-session-content' };
-  }
-
-  const ts = now ?? nowIso();
-  const nowMs = new Date(ts).getTime();
-  const files = listTodayFiles(projectRoot);
-
-  // Weekly check: any today-*.md older than weeklyTtlMs by its date stamp
-  // (NOT mtime — the file's date is the canonical age signal; mtime can
-  // drift if someone touched the file).
-  const weeklyCutoffMs = nowMs - weeklyTtlMs;
-  const hasOldToday = files.some((f) => {
-    const fileMs = new Date(f.date + 'T00:00:00Z').getTime();
-    return Number.isFinite(fileMs) && fileMs < weeklyCutoffMs;
-  });
-  if (hasOldToday) {
-    return { action: 'stale-weekly', reason: 'today-file-older-than-7d' };
-  }
-
-  // Task 36 I1 fix: if there are NO today-*.md files at all, the
-  // pipeline has nothing to compress — return fresh regardless of
-  // recent.md mtime. Previously this check only fired when recent.md
-  // was MISSING; for the stale-but-no-input case (e.g., right after
-  // weeklyCurate archived every today file), the daily-stale branch
-  // would fire and the SessionStart hook would spawn lazy-compress
-  // forever (no new today file means no work; dailyDistill would
-  // return skipped:no-input but not touch recent.md, so the next
-  // SessionStart sees the same stale verdict).
-  if (files.length === 0) {
-    return { action: 'fresh', reason: 'no-input' };
-  }
-
-  // Daily check: recent.md missing OR older than dailyTtlMs.
-  const mtimeMs = recentMdMtimeMs(projectRoot);
-  if (mtimeMs === null) {
-    return { action: 'stale-daily', reason: 'recent-md-missing' };
-  }
-  if (nowMs - mtimeMs > dailyTtlMs) {
-    return { action: 'stale-daily', reason: 'recent-md-older-than-ttl' };
-  }
-  return { action: 'fresh', reason: 'within-ttl' };
+  // Task 167 (D-207): delegate to the compaction-state deep module. This is a
+  // thin back-compat adapter — it maps the rich `{verdict, cronStale,
+  // heartbeatAge}` return onto the legacy `{action, reason}` shape callers
+  // (inject-context, runLazyCompress) already consume. The KEY behavior change
+  // vs the old body: `cron-active` is now gated on heartbeat FRESHNESS (age), not
+  // sentinel existence, so a dead cron falls through to the stale verdicts.
+  const r = isCompactionNeeded({ projectRoot, now, dailyTtlMs, weeklyTtlMs });
+  return { action: r.verdict, reason: r.reason, cronStale: r.cronStale, heartbeatAge: r.heartbeatAge };
 }
 
 function writeLazyLogEntry({ projectRoot, entry }) {

package/src/managed-block.mjs

@@ -0,0 +1,138 @@
+// managed-block.mjs — shared helpers for agent-config + instruction-file writes.
+//
+// install-agent.mjs (the generic per-agent installer) and install-kiro.mjs (the
+// Kiro 4-surface orchestrator) both need the same primitives: a managed
+// marker-block instruction-file writer, JSON-key removal that preserves siblings,
+// empty-parent pruning, and the non-regex newline trims (ReDoS-safe). These were
+// duplicated verbatim across the two; centralizing them here removes the drift
+// hazard (the kit's shared-module discipline — the same lesson the duplicated
+// atomicWrite taught earlier in Task 50).
+//
+// Public surface:
+//   writeManagedBlock(path, {body, frontmatter, markStart, markEnd}) → changed:bool
+//   removeManagedBlock(path, {markStart, markEnd}) → changed:bool
+//   removeJsonKey(path, keyPath) → changed:bool   (preserves siblings)
+//   pruneEmptyParent(path, keyPath) → void         (drops an emptied {} we leave)
+//   escapeRe / trimLeadingNewlines / trimTrailingNewlines (ReDoS-safe utils)
+
+import { existsSync, readFileSync } from 'node:fs';
+import { atomicWrite } from './mutate-agent-config.mjs';
+
+export const DEFAULT_MARK_START = '<!-- claude-memory-kit:start -->';
+export const DEFAULT_MARK_END = '<!-- claude-memory-kit:end -->';
+
+/**
+ * Write/refresh a managed marker block in an instruction file, byte-preserving
+ * everything outside the markers. `frontmatter` (e.g. Kiro's `inclusion: always`)
+ * is prepended only when the file is created fresh. Idempotent: identical content
+ * → no write, returns false.
+ * @returns {boolean} whether a write happened.
+ */
+export function writeManagedBlock(path, { body, frontmatter = '', markStart = DEFAULT_MARK_START, markEnd = DEFAULT_MARK_END } = {}) {
+  const block = `${markStart}\n${body}\n${markEnd}`;
+  const desired = `${frontmatter}${block}\n`;
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+
+  let next;
+  if (existing === '') {
+    next = desired;
+  } else if (existing.includes(markStart) && existing.includes(markEnd)) {
+    // refresh in place — replace only the managed block, byte-preserve the rest.
+    next = existing.replace(
+      new RegExp(`${escapeRe(markStart)}[\\s\\S]*?${escapeRe(markEnd)}`),
+      block,
+    );
+  } else {
+    // append our block to the user's existing file.
+    next = `${trimTrailingNewlines(existing)}\n\n${block}\n`;
+  }
+
+  if (next === existing) return false;
+  atomicWrite(path, next);
+  return true;
+}
+
+/** Strip our managed block (+ surrounding blank lines), byte-preserve the rest. */
+export function removeManagedBlock(path, { markStart = DEFAULT_MARK_START, markEnd = DEFAULT_MARK_END } = {}) {
+  if (!existsSync(path)) return false;
+  const existing = readFileSync(path, 'utf8');
+  if (!existing.includes(markStart)) return false;
+  // The inner [\s\S]*? is lazy + bounded by two fixed literal delimiters → linear,
+  // not ReDoS-prone. Newline trims are non-regex (no `\n*$`/`^\n+` super-linear
+  // shapes); the `\n{3,}` collapse is a bounded quantifier, also linear.
+  const blockRe = new RegExp(`${escapeRe(markStart)}[\\s\\S]*?${escapeRe(markEnd)}`);
+  const stripped = trimLeadingNewlines(existing.replace(blockRe, '').replace(/\n{3,}/g, '\n\n'));
+  atomicWrite(path, stripped);
+  return true;
+}
+
+/**
+ * Remove a nested key from a JSON file, preserving everything else. Skips
+ * (returns false) on a missing file / parse error (never clobbers a corrupt file).
+ * @returns {boolean} whether a change was written.
+ */
+export function removeJsonKey(path, keyPath) {
+  if (!existsSync(path)) return false;
+  let root;
+  try {
+    root = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return false;
+  }
+  let cur = root;
+  for (let i = 0; i < keyPath.length - 1; i += 1) {
+    if (!cur || typeof cur !== 'object' || !(keyPath[i] in cur)) return false;
+    cur = cur[keyPath[i]];
+  }
+  const last = keyPath[keyPath.length - 1];
+  if (!cur || typeof cur !== 'object' || !(last in cur)) return false;
+  delete cur[last];
+  atomicWrite(path, `${JSON.stringify(root, null, 2)}\n`);
+  return true;
+}
+
+/**
+ * If the object at keyPath exists and is now empty ({}), remove it — so an
+ * uninstall doesn't leave a kit-shaped `{"mcpServers":{}}` husk. No-op on a
+ * missing file / parse error / non-empty target.
+ */
+export function pruneEmptyParent(path, keyPath) {
+  if (!existsSync(path)) return;
+  let root;
+  try {
+    root = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return;
+  }
+  let cur = root;
+  for (let i = 0; i < keyPath.length - 1; i += 1) {
+    if (!cur || typeof cur !== 'object' || !(keyPath[i] in cur)) return;
+    cur = cur[keyPath[i]];
+  }
+  const last = keyPath[keyPath.length - 1];
+  const target = cur && typeof cur === 'object' ? cur[last] : undefined;
+  if (target && typeof target === 'object' && !Array.isArray(target) && Object.keys(target).length === 0) {
+    delete cur[last];
+    atomicWrite(path, `${JSON.stringify(root, null, 2)}\n`);
+  }
+}
+
+// ── ReDoS-safe string utils ──────────────────────────────────────────────────
+
+export function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Non-regex newline trims — avoid the `\n*$` / `^\n+` super-linear-backtracking
+// shapes a static analyzer (rightly) flags as ReDoS-prone. O(n), no backtracking.
+export function trimTrailingNewlines(s) {
+  let end = s.length;
+  while (end > 0 && s[end - 1] === '\n') end -= 1;
+  return s.slice(0, end);
+}
+
+export function trimLeadingNewlines(s) {
+  let start = 0;
+  while (start < s.length && s[start] === '\n') start += 1;
+  return s.slice(start);
+}

package/src/memory-write.mjs

@@ -203,6 +203,27 @@ function findMatchingBullet({ lines, substring, sectionTitle }) {
   return null;
 }
 
+// Strip a bullet + its provenance comment (lines bulletIdx..commentIdx) and
+// collapse a resulting double blank line at the seam, so removing a bullet from
+// a blank-padded scratchpad doesn't leave two adjacent blank lines (MD012
+// no-multiple-blanks). Only the seam is touched — blanks elsewhere are
+// preserved. The bullet↔comment pair is removed together (the adjacency
+// invariant the whole kit depends on).
+function stripBulletPair(lines, bulletIdx, commentIdx) {
+  const kept = [...lines.slice(0, bulletIdx), ...lines.slice(commentIdx + 1)];
+  // If the splice put a blank line directly after a blank line at the seam,
+  // drop one. The seam is at index `bulletIdx` in `kept`.
+  if (
+    bulletIdx > 0 &&
+    bulletIdx < kept.length &&
+    kept[bulletIdx - 1].trim() === '' &&
+    kept[bulletIdx].trim() === ''
+  ) {
+    kept.splice(bulletIdx, 1);
+  }
+  return kept.join('\n');
+}
+
 // --- Tombstone writer (design §6.5) --------------------------------
 
 function writeTombstone({
@@ -438,10 +459,7 @@ function doReplace(opts) {
     });
   }
   // Strip the matched bullet + provenance comment.
-  const stripped = [
-    ...lines.slice(0, match.bulletIdx),
-    ...lines.slice(match.commentIdx + 1),
-  ].join('\n');
+  const stripped = stripBulletPair(lines, match.bulletIdx, match.commentIdx);
   writeFileSync(path, stripped, 'utf8');
 
   // Append the new bullet via the GUARDED inner path. We already ran
@@ -550,10 +568,7 @@ function doRemove(opts) {
   });
 
   // Strip from scratchpad.
-  const stripped = [
-    ...lines.slice(0, match.bulletIdx),
-    ...lines.slice(match.commentIdx + 1),
-  ].join('\n');
+  const stripped = stripBulletPair(lines, match.bulletIdx, match.commentIdx);
   writeFileSync(path, stripped, 'utf8');
 
   appendAuditEntry(tierRoot, {

package/src/mutate-agent-config.mjs

@@ -0,0 +1,243 @@
+// mutate-agent-config.mjs — the shared per-agent config-write PRIMITIVE.
+//
+// Task 50 (cross-agent install). This is the one piece of machinery the whole
+// `cmk install --ide <agent>` seam rests on: a single, tested function that
+// writes the kit's entry (an MCP-server registration, a hook entry) into ANY
+// agent's config file WITHOUT clobbering the user's other keys.
+//
+// The D-180 finding (research note 2026-06-20): do NOT build a per-agent
+// `Installer` base class — claude-mem proved it breaks the moment agents differ
+// in format/mechanism, and its ~6 bespoke config writers drifted in rigor (one
+// surgical, one whole-file-clobber, one that discards user config on a JSON
+// parse error). What actually generalizes is THIS primitive. Each per-agent
+// profile is then just DATA (where the file is, which key, which format).
+//
+// The kit's existing disciplines, applied to third-party files:
+//   - touch-only-our-keys      = the marker-block byte-preservation invariant
+//   - refuse-on-parse-error    = the safe-write / Poison_Guard fail-closed rule
+//   - atomic (tmp + rename)    = the same pattern compress-session/persona use
+//   - idempotent changed-bool  = re-running install is a no-op (Codex's pattern)
+//
+// Public surface (one function — a deep module, narrow interface):
+//
+//   mutateAgentConfig({ path, format, keyPath, entry, mode? }) → result
+//
+//     path     absolute path to the agent's config file (may not exist yet)
+//     format   'json'  (v0.4.0; 'yaml' / 'toml' deferred until an agent needs them)
+//     keyPath  array of keys to the slot we own, e.g. ['mcpServers', 'claude-memory-kit']
+//     entry    the object to place at keyPath
+//     mode     'merge' (default — deep-merge into an existing entry) | 'replace'
+//
+//   Result shape (result-shapes.mjs conventions):
+//     { action: 'created'|'updated'|'skipped'|'error', changed: boolean, path,
+//       errorCategory?, errors? }
+//       created  — the file did not exist; we created it with just our key
+//       updated  — the file existed; our key was added/changed (siblings preserved)
+//       skipped  — our key already matched exactly; nothing written (changed:false)
+//       error    — input invalid (schema) or target unparseable (config_parse);
+//                  NEVER writes on error
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+import { stripBom } from './read-json.mjs';
+
+const SUPPORTED_FORMATS = new Set(['json']);
+
+/**
+ * Write the kit's entry into an agent config file, preserving everything else.
+ * @returns {{action:string, changed:boolean, path:string, errorCategory?:string, errors?:string[]}}
+ */
+export function mutateAgentConfig({ path, format, keyPath, entry, mode = 'merge' }) {
+  // ── input validation (schema) ───────────────────────────────────────────
+  if (typeof path !== 'string' || path.length === 0) {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors: ['path must be a non-empty string'], changed: false });
+  }
+  if (!SUPPORTED_FORMATS.has(format)) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: [`unsupported format ${JSON.stringify(format)} — supported: ${[...SUPPORTED_FORMATS].join(', ')}`],
+      changed: false,
+      path,
+    });
+  }
+  if (!Array.isArray(keyPath) || keyPath.length === 0 || !keyPath.every((k) => typeof k === 'string' && k.length > 0)) {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors: ['keyPath must be a non-empty array of non-empty strings'], changed: false, path });
+  }
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors: ['entry must be a plain object'], changed: false, path });
+  }
+  if (mode !== 'merge' && mode !== 'replace') {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors: [`mode must be 'merge' or 'replace', got ${JSON.stringify(mode)}`], changed: false, path });
+  }
+
+  // ── read existing (refuse-to-clobber on parse error) ─────────────────────
+  const fileExists = existsSync(path);
+  let root;
+  if (fileExists) {
+    let raw;
+    try {
+      // stripBom: a user's config file written by a Windows editor may carry a
+      // leading UTF-8 BOM, which would otherwise make the JSON.parse below refuse
+      // a perfectly valid file as "corrupt" (D-187). Strip only the BOM; the
+      // refuse-to-clobber-on-real-corruption guarantee below is unchanged.
+      raw = stripBom(readFileSync(path, 'utf8'));
+    } catch (err) {
+      return errorResult({ category: ERROR_CATEGORIES.CONFIG_PARSE, errors: [`could not read ${path}: ${err.message}`], changed: false, path });
+    }
+    if (raw.trim() === '') {
+      // an empty file is treated as an empty object (not a parse error)
+      root = {};
+    } else {
+      try {
+        root = JSON.parse(raw);
+      } catch (err) {
+        // The crucial guarantee: a corrupt target is NEVER overwritten.
+        return errorResult({ category: ERROR_CATEGORIES.CONFIG_PARSE, errors: [`${path} is not valid JSON — refusing to overwrite: ${err.message}`], changed: false, path });
+      }
+    }
+    if (root === null || typeof root !== 'object' || Array.isArray(root)) {
+      return errorResult({ category: ERROR_CATEGORIES.CONFIG_PARSE, errors: [`${path} is valid JSON but not an object — refusing to overwrite`], changed: false, path });
+    }
+  } else {
+    root = {};
+  }
+
+  // ── compute the next entry at keyPath ────────────────────────────────────
+  const existing = getAt(root, keyPath);
+  const nextEntry =
+    mode === 'merge' && isPlainObject(existing) ? deepMerge(existing, entry) : entry;
+
+  // idempotent: if our slot already deep-equals what we'd write, do nothing.
+  if (existing !== undefined && deepEqual(existing, nextEntry)) {
+    return { action: 'skipped', changed: false, path };
+  }
+
+  // ── apply + atomic write ─────────────────────────────────────────────────
+  const next = cloneDeep(root);
+  setAt(next, keyPath, nextEntry);
+
+  const serialized = `${JSON.stringify(next, null, 2)}\n`;
+  atomicWrite(path, serialized);
+
+  return { action: fileExists ? 'updated' : 'created', changed: true, path };
+}
+
+// ── internal helpers ───────────────────────────────────────────────────────
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function getAt(obj, keyPath) {
+  let cur = obj;
+  for (const k of keyPath) {
+    if (!isPlainObject(cur) || !(k in cur)) return undefined;
+    cur = cur[k];
+  }
+  return cur;
+}
+
+function setAt(obj, keyPath, value) {
+  let cur = obj;
+  for (let i = 0; i < keyPath.length - 1; i += 1) {
+    const k = keyPath[i];
+    if (!isPlainObject(cur[k])) cur[k] = {};
+    cur = cur[k];
+  }
+  cur[keyPath[keyPath.length - 1]] = value;
+}
+
+// Deep-merge `source` onto a copy of `target`. Objects merge recursively;
+// arrays + scalars from source replace target's (no array concat — replacing
+// args/command is the intended semantics).
+function deepMerge(target, source) {
+  const out = cloneDeep(target);
+  for (const [k, v] of Object.entries(source)) {
+    if (isPlainObject(v) && isPlainObject(out[k])) {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = cloneDeep(v);
+    }
+  }
+  return out;
+}
+
+function cloneDeep(v) {
+  return v === undefined ? undefined : JSON.parse(JSON.stringify(v));
+}
+
+function deepEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+// Atomic write: serialize to a temp sibling, then rename over the target.
+// rename is atomic on the same filesystem, so a reader never sees a partial file.
+// Exported so install-agent.mjs (the per-agent wiring) shares ONE implementation
+// — the kit's shared-module discipline (no two copies to drift).
+//
+// Two Windows-specific hazards this guards against (BOTH real, BOTH surfaced by
+// the Task-50 stress runs — not "flakes": concrete EPERM-under-load failures):
+//   1. The tmp suffix is UNIQUE PER CALL (randomUUID), not `process.pid` — a
+//      single install sequence writes the same path several times (write →
+//      uninstall → prune) and vitest runs files concurrently in one worker
+//      (shared pid), so a pid-keyed tmp name could collide.
+//   2. `renameSync(tmp, target)` ONTO an existing file intermittently throws
+//      EPERM/EBUSY on Windows when the target is transiently locked (AV /
+//      indexer / another handle) under heavy parallel FS load. The kit already
+//      hit + documented this in persona-portability.mjs (restoreBackup); the
+//      proven fix is a short bounded retry. Without it, a `cmk install` on a
+//      busy Windows machine could spuriously fail mid-write.
+export function atomicWrite(path, contents) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(tmp, contents, 'utf8');
+    renameWithRetry(tmp, path);
+  } finally {
+    if (existsSync(tmp)) {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        /* best-effort cleanup; the rename already succeeded or threw */
+      }
+    }
+  }
+}
+
+// renameSync with a bounded retry + BACKOFF on transient Windows EPERM/EBUSY
+// (the target briefly locked by AV/indexer/another handle under load). A
+// no-delay spin doesn't work — the lock lasts milliseconds while 5 immediate
+// retries finish in microseconds (the Task-50 stress proved this: retry fired
+// but exhausted instantly). So we sleep between attempts with a synchronous
+// backoff (Atomics.wait — real sync sleep, no busy-spin). A non-transient error
+// (e.g. ENOENT on the source) reraises immediately so we don't mask a real bug.
+//
+// `rename` + `sleep` are injectable so the retry policy is unit-testable WITHOUT
+// mocking node:fs or actually sleeping — production passes nothing.
+export function renameWithRetry(from, to, attempts = 8, rename = renameSync, sleep = sleepMs) {
+  let lastErr;
+  for (let i = 0; i < attempts; i += 1) {
+    try {
+      rename(from, to);
+      return;
+    } catch (err) {
+      if (err && (err.code === 'EPERM' || err.code === 'EBUSY' || err.code === 'EACCES')) {
+        lastErr = err; // transient lock under load — back off + retry
+        if (i < attempts - 1) sleep(Math.min(10 * 2 ** i, 250)); // 10,20,40…≤250ms
+        continue;
+      }
+      throw err; // anything else is a real error — don't mask it
+    }
+  }
+  throw lastErr;
+}
+
+// Synchronous sleep via Atomics.wait on a throwaway SharedArrayBuffer — blocks
+// the thread for `ms` without a CPU busy-spin. Used only on the (rare) Windows
+// transient-lock retry path, so the block is bounded + infrequent.
+function sleepMs(ms) {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}