@lh8ppl/claude-memory-kit 0.3.4 → 0.4.0

package/src/doctor.mjs

@@ -48,6 +48,8 @@ import { checkKitBinding, checkEmbedderBinding } from './native-binding.mjs';
 import { resolveDefaultSearchMode } from './semantic-backend.mjs';
 import { checkVersionDrift } from './version-drift.mjs';
 import { getKitVersion } from './install.mjs';
+import { hasOurCliAgent } from './kiro-cli-agent.mjs';
+import { stripBom } from './read-json.mjs';
 
 const TWO_DAYS_MS = 2 * 24 * 60 * 60 * 1000;
 const THREE_DAYS_MS = 3 * 24 * 60 * 60 * 1000;
@@ -59,9 +61,41 @@ const MEMORY_DIR_REL = ['context', 'memory'];
 const LOCKS_REL = ['context', '.locks'];
 const NATIVE_MEMORY_LOG_REL = ['context', '.locks', 'native-memory-status.log'];
 
+// Which agent was this project installed for? A `--ide kiro` install wires
+// .kiro/ surfaces (hooks + steering/cmk.md + skills + settings/mcp.json); a
+// Claude Code install wires .claude/settings.json. HC-1 must check the RIGHT
+// surface — before v0.4.0 it hard-checked .claude/settings.json and false-FAILed
+// on every Kiro install (the cut-gate-kiro live-test find, Task 50).
+//
+// Detection precedence:
+//   1. .claude/settings.json present → Claude Code.
+//   2. a CMK-OWNED Kiro marker present (.kiro/steering/cmk.md — written by every
+//      installKiro run) → Kiro. We key on OUR marker, not a bare `.kiro/` dir, so
+//      a stray/unrelated .kiro/ (another tool's, or a partial non-cmk dir) does
+//      NOT flip the project to the Kiro path (I2).
+//   3. neither → Claude Code (historical default — a not-yet-installed project
+//      still reports the Claude-shaped repair hint).
+//
+// NOTE (I1, deliberate punt): a project installed for BOTH agents (.claude AND a
+// cmk .kiro marker) resolves to Claude Code by precedence — HC-1 checks only the
+// Claude surface. Dual-install is rare; the single-surface check is intentional
+// for v0.4.0, not an oversight. Revisit if dual-install becomes common.
+function detectInstallKind(projectRoot) {
+  if (existsSync(join(projectRoot, '.claude', 'settings.json'))) return 'claude-code';
+  if (existsSync(join(projectRoot, '.kiro', 'steering', 'cmk.md'))) return 'kiro';
+  return 'claude-code';
+}
+
 // --- HC-1: Stop + SessionStart hooks registered -----------------------
-function hc1Hooks({ projectRoot }) {
-  // Per design §5 — the kit's hooks live in .claude/settings.json
+function hc1Hooks({ projectRoot, awsDir }) {
+  // Agent-aware (v0.4.0): a Kiro install keeps its hooks in .kiro/hooks/ (IDE)
+  // and/or ~/.kiro/agents/ (kiro-cli), so route to the Kiro check
+  // rather than false-failing on a missing .claude/settings.json with a
+  // Claude-Code repair hint.
+  if (detectInstallKind(projectRoot) === 'kiro') {
+    return hc1KiroHooks({ projectRoot, awsDir });
+  }
+  // Per design §5 — the Claude Code hooks live in .claude/settings.json
   // alongside its plugin manifest. Required for auto-extract +
   // session-end compression to fire.
   const settingsPath = join(projectRoot, '.claude', 'settings.json');
@@ -76,7 +110,9 @@ function hc1Hooks({ projectRoot }) {
   }
   let settings;
   try {
-    settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    // stripBom: a Windows-editor BOM on .claude/settings.json must not make a
+    // valid file read as a parse error → false HC-1 FAIL (D-187).
+    settings = JSON.parse(stripBom(readFileSync(settingsPath, 'utf8')));
   } catch (err) {
     return {
       id: 'HC-1',
@@ -141,6 +177,51 @@ function hc1Hooks({ projectRoot }) {
   };
 }
 
+// --- HC-1 (Kiro variant): capture + inject can fire via EITHER Kiro surface ----
+// Kiro wires capture/inject through TWO independent surfaces (D-186):
+//   • IDE hooks  → .kiro/hooks/{cmk-capture,cmk-inject}.kiro.hook  (the GUI user)
+//   • CLI agent  → ~/.kiro/agents/cmk.json with
+//                  agentSpawn(inject)+stop(capture) hooks  (the kiro-cli user)
+// HC-1 is a CAPABILITY check ("can capture/inject fire?"), not a single-file
+// check — so it PASSES if EITHER surface is present, and FAILs only when NEITHER
+// is. The original v0.4.0 fix checked only the IDE hooks, which false-FAILed a
+// working kiro-cli-only install (the surface lives in ~/.aws, which is also
+// machine-local and doesn't travel with a clone) — the same separately-correct-
+// jointly-broken class as D-184/D-185, one level down (skill-review B1).
+// `awsDir` is injectable so tests can sandbox the ~/.aws probe.
+function hc1KiroHooks({ projectRoot, awsDir }) {
+  const hooksDir = join(projectRoot, '.kiro', 'hooks');
+  const ideHooks = ['cmk-capture.kiro.hook', 'cmk-inject.kiro.hook'];
+  const ideMissing = ideHooks.filter((f) => !existsSync(join(hooksDir, f)));
+  const ideComplete = ideMissing.length === 0;
+  const cliAgent = hasOurCliAgent({ awsDir });
+
+  if (ideComplete || cliAgent) {
+    const surfaces = [];
+    if (ideComplete) surfaces.push('IDE hooks (.kiro/hooks/)');
+    if (cliAgent) surfaces.push('CLI agent (~/.kiro/agents/cmk.json)');
+    return {
+      id: 'HC-1',
+      name: 'Stop + SessionStart hooks registered',
+      status: 'pass',
+      message: `Kiro capture/inject wired via ${surfaces.join(' + ')}`,
+    };
+  }
+
+  // Neither surface present → genuinely not wired. Name both so a kiro-cli user
+  // isn't pushed at the IDE-only repair.
+  return {
+    id: 'HC-1',
+    name: 'Stop + SessionStart hooks registered',
+    status: 'fail',
+    message:
+      `Kiro install: no capture/inject surface found — neither the IDE hooks ` +
+      `(${ideMissing.join(', ')} in .kiro/hooks/) nor a cmk CLI agent in ` +
+      `~/.kiro/agents/`,
+    recoveryCommand: 'cmk install --ide kiro',
+  };
+}
+
 // --- HC-2: distill freshness (≤2 days) --------------------------------
 function hc2DistillFreshness({ projectRoot, now }) {
   const recentPath = join(projectRoot, ...RECENT_MD_REL);
@@ -566,6 +647,7 @@ export async function runDoctor({
   kitVersion,
   kitBindingProbe,
   embedderBindingProbe,
+  awsDir, // injectable: sandboxes the HC-1 Kiro CLI-agent (~/.aws) probe in tests
 } = {}) {
   const t0 = Date.now();
   if (!projectRoot) {
@@ -580,7 +662,7 @@ export async function runDoctor({
   const resolvedUserDir = userDir ?? join(homedir(), '.claude-memory-kit');
 
   // Run all checks in order.
-  const c1 = hc1Hooks({ projectRoot });
+  const c1 = hc1Hooks({ projectRoot, awsDir });
   const c2 = hc2DistillFreshness({ projectRoot, now: ts });
   const c3 = hc3Transcripts({ projectRoot, now: ts });
   const c4 = hc4IndexConsistency({ projectRoot });

package/src/guard-memory.mjs

@@ -0,0 +1,151 @@
+// guard-memory.mjs — the memory delete-guardrail core (D-192).
+//
+// A Claude Code `PreToolUse` hook (wired by `cmk install`) calls the
+// `cmk-guard-memory` bin before every Bash/PowerShell tool call. This module
+// is the pure decision: given a shell command, should it be BLOCKED because it
+// would delete a claude-memory-kit memory path?
+//
+// Why this exists: 2026-06-22 (D-192), a `cd` that silently failed left a
+// following `rm -f context/sessions/* context/transcripts/*` running in the
+// wrong repo, deleting gitignored (non-recoverable) memory. A prose rule relies
+// on the agent remembering; this hook enforces it structurally — the command
+// never runs. Recovered only via an off-machine backup; this prevents the next.
+//
+// Design: BROAD by intent. A false block is recoverable (the user rephrases or
+// deletes by hand); a false allow is the data loss we're preventing. So the
+// predicates favor over-blocking a memory delete over under-blocking one.
+
+// A command is destructive if it invokes a delete/destroy verb OR an equivalent
+// data-destroying mechanism that carries no `rm` token (find -delete, truncate,
+// a `>`/`:>` redirection that truncates a file). Skill-review I2: a memory file
+// can be destroyed with no `rm` at all.
+const DESTRUCTIVE = [
+  /\brm\b/i, // unix rm
+  /\bRemove-Item\b/i, // PowerShell
+  /\brmdir\b/i,
+  /\brd\b/i, // cmd rd
+  /\bdel\b/i, // cmd del
+  /\bunlink\b/i,
+  /\bgit\s+clean\b/i,
+  /\bgit\s+reset\s+--hard\b/i,
+  /\bfind\b[^|]*-delete\b/i, // find … -delete
+  /\btruncate\b/i, // truncate -s0 file
+  /(^|[\s;&|])>\s*\S/, // a `>`/`> file` redirection (truncates the target to empty)
+];
+
+// A path is a MEMORY path if the command mentions any of these. The bare
+// `context` segment matcher requires a path-ish boundary so the WORD "context"
+// (e.g. `grep context`, `rm contextual.md`) is not a false positive.
+const MEMORY_TOKENS = [
+  /context\/sessions/i,
+  /context\/transcripts/i,
+  /context\/memory/i,
+  /context\.local/i,
+  // a `context` path segment: `context/`, `context\`, `./context`, `repo/context`,
+  // or a bare ` context` argument (e.g. `git clean -fd context`).
+  /(^|[\s'"./\\])context([\s'"/\\]|$)/i,
+  /\.claude-memory-kit/i, // the cross-project user tier
+  /MEMORY\.md/i,
+  /DECISIONS\.md/i,
+];
+
+/** True if the command invokes a delete/destroy verb. */
+export function isDestructive(cmd) {
+  return typeof cmd === 'string' && DESTRUCTIVE.some((re) => re.test(cmd));
+}
+
+/** True if the command references a claude-memory-kit memory path. */
+export function touchesMemory(cmd) {
+  return typeof cmd === 'string' && MEMORY_TOKENS.some((re) => re.test(cmd));
+}
+
+// A SEGMENT (not the whole command) may be exempt: it only MENTIONS a delete in
+// its text and can't itself execute one — a `git commit` whose message describes
+// a delete, an `echo`/`grep`/`cat` of text about a delete. (oh-my-kiro's
+// block-dangerous.sh exempts `git commit` for the same reason.) CRITICAL: this
+// is applied PER SEGMENT, never to a whole compound command — `echo x && rm -rf
+// context/memory` must NOT be exempted by its leading `echo` (skill-review B1).
+const SEGMENT_EXEMPT = [
+  /^\s*git\s+commit\b/i,
+  /^\s*git\s+log\b/i,
+  /^\s*echo\b/i,
+  /^\s*(grep|rg|cat|less|head|tail|sed -n|awk)\b/i,
+];
+
+// Split a shell command into its sequenced segments on the separators that start
+// a NEW command: && || ; | and newlines. (A `>` redirection is NOT a separator —
+// it's handled as a destructive mechanism on its own segment.) Also surface any
+// $(...) / `...` command substitution as its own segment so a delete hidden in a
+// commit-message arg (`git commit -m "$(rm -rf context/memory)"`) is evaluated
+// on its own and can't ride the outer command's exemption (skill-review I1).
+function splitSegments(cmd) {
+  const segments = [];
+  // pull out command substitutions first, add them as standalone segments
+  const subRe = /\$\(([^)]*)\)|`([^`]*)`/g;
+  let m;
+  while ((m = subRe.exec(cmd)) !== null) {
+    const inner = m[1] ?? m[2];
+    if (inner && inner.trim()) segments.push(inner);
+  }
+  const stripped = cmd.replace(subRe, ' '); // remove subs so they don't leak into outer segments
+  for (const seg of stripped.split(/&&|\|\||;|\||\r?\n/)) {
+    if (seg.trim()) segments.push(seg);
+  }
+  return segments;
+}
+
+function isSegmentExempt(seg) {
+  return SEGMENT_EXEMPT.some((re) => re.test(seg));
+}
+
+/**
+ * The pure decision. Returns { block: boolean, reason?: string }.
+ * Splits the command into segments and BLOCKS if ANY non-exempt segment is both
+ * destructive AND aimed at a memory path. Per-segment so an exempt verb in front
+ * (`echo …`, `git commit …`) cannot launder a chained real delete (B1/I1).
+ */
+export function decideGuard(cmd) {
+  if (typeof cmd !== 'string' || cmd.trim() === '') return { block: false };
+  const offending = splitSegments(cmd).some(
+    (seg) => !isSegmentExempt(seg) && isDestructive(seg) && touchesMemory(seg),
+  );
+  if (offending) {
+    return {
+      block: true,
+      reason:
+        'BLOCKED by the claude-memory-kit delete-guardrail: this command deletes a ' +
+        'memory path (context/ , the persona tier ~/.claude-memory-kit, or a memory ' +
+        'file). Memory is precious and a delete here is often non-recoverable. If you ' +
+        'REALLY mean to delete memory, do it by hand after a backup — or ask the user. ' +
+        'NEVER run a delete after a `cd` you have not verified with `pwd`.',
+    };
+  }
+  return { block: false };
+}
+
+// The shell-tool names across agents. Claude Code: `Bash` / `PowerShell`.
+// Kiro / Amazon-Q: `execute_bash` (+ legacy alias `executeBash`); kiro-cli V3
+// (2.9.0) RENAMED it to `execute_command` (D-198, observed live in the cut-gate).
+// Payload `.tool_name` + `.tool_input.command` on STDIN — the SAME shape as
+// Claude Code, so one bin guards every agent. D-192.
+const SHELL_TOOLS = new Set([
+  'Bash',
+  'PowerShell',
+  'execute_bash',
+  'executeBash',
+  'execute_command', // kiro-cli V3 (2.9.0) rename — D-198
+  'shell',
+]);
+
+/**
+ * Evaluate a PreToolUse payload (already parsed) from EITHER Claude Code or Kiro
+ * — both deliver `{ tool_name, tool_input: { command } }` on stdin. Only shell
+ * tools are inspected; everything else is allowed. Returns { block, reason? }.
+ */
+export function evaluatePayload(payload) {
+  const tool = payload?.tool_name;
+  if (!SHELL_TOOLS.has(tool)) return { block: false };
+  const cmd = payload?.tool_input?.command;
+  if (typeof cmd !== 'string' || cmd === '') return { block: false };
+  return decideGuard(cmd);
+}

package/src/import-anthropic-memory.mjs

@@ -253,7 +253,21 @@ export async function importAnthropicMemory({
     })
     .join('\n');
   mkdirSync(join(projectRoot, 'context'), { recursive: true });
-  appendFileSync(targetPath, sectionHeader + '\n' + bulletLines + '\n', 'utf8');
+  // Lint-clean append (MD022): guarantee exactly one blank line ABOVE the
+  // `## Imported …` heading when the target file already has content (the
+  // leading `\n` in sectionHeader assumes the file ends in `\n` — fragile if it
+  // doesn't). The blank below the heading is the `+ '\n'` after sectionHeader.
+  let prefix = '';
+  if (existsSync(targetPath)) {
+    const existing = readFileSync(targetPath, 'utf8');
+    if (existing.trim() !== '') {
+      prefix = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '' : '\n';
+    }
+  }
+  // sectionHeader already starts with `\n`, so a file ending in `\n` yields the
+  // needed blank line; prefix adds the missing one only when the file lacks a
+  // trailing newline.
+  appendFileSync(targetPath, prefix + sectionHeader + '\n' + bulletLines + '\n', 'utf8');
 
   let accepted = 0;
   for (const p of proposals) {

package/src/inject-context.mjs

@@ -31,7 +31,8 @@ import {
   closeSync,
 } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { SCRATCHPADS_BY_TIER, resolveTierRoot, ID_PATTERN } from './tier-paths.mjs';
 import { nowIso } from './audit-log.mjs';
@@ -617,6 +618,32 @@ function enforceCap(orderedBlocks, capBytes, ts, reportCapBytes = capBytes) {
  * Exposed so injectContext can override via dependency injection in tests
  * (testSpawnLazy parameter) — production callers pass nothing.
  */
+/**
+ * Resolve the path to `bin/cmk-compress-lazy.mjs` from THIS module's location
+ * (`src/` → `../bin/`), honoring the $CMK_COMPRESS_LAZY_PATH override. Returns
+ * null if it can't be found (→ the shell:true fallback).
+ *
+ * Why this exists (the cross-agent console-popup fix): the no-popup spawn (Task
+ * 81) only kicks in when `injectContext` receives a real `compressLazyPath` —
+ * otherwise `lazyCompressSpawnDescriptor` falls to the `shell:true` `.cmd` shim,
+ * which flashes a `node` console window on Windows. The Claude Code bin
+ * (`cmk-inject-context.mjs`) passed the path; the Kiro `cmk hook agentSpawn`
+ * path did NOT, so a real Kiro user got the popup (the cut-gate-kiro live find).
+ * Resolving it HERE (in injectContext's default) fixes EVERY caller — Claude
+ * bin, Kiro hook, any future agent — not just the ones that remember to pass it.
+ */
+export function resolveCompressLazyPath() {
+  const fromEnv = process.env.CMK_COMPRESS_LAZY_PATH;
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
+  try {
+    const here = dirname(fileURLToPath(import.meta.url)); // .../packages/cli/src
+    const candidate = join(here, '..', 'bin', 'cmk-compress-lazy.mjs');
+    return existsSync(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Pure spawn descriptor for the lazy-compress child (Task 81). Separated so the
  * Door-3 contract (node-direct + windowsHide, no shell, when the path is known)
@@ -706,8 +733,12 @@ export function injectContext({
   // Resolved path to cmk-compress-lazy.mjs (passed by the bin wrapper, which
   // knows the install layout). Lets spawnLazyCompress run `node <path>`
   // directly instead of the shell:true `.cmd` shim — the Windows
-  // console-popup fix (Task 81). Absent → graceful shell:true fallback.
-  compressLazyPath,
+  // console-popup fix (Task 81). Absent → self-resolve from this module's
+  // location (resolveCompressLazyPath), so EVERY caller gets the no-popup
+  // node-direct spawn — not just the Claude bin that passed it explicitly. A
+  // caller may still override (e.g. tests). Only a genuinely-unfindable bin
+  // (corrupt install) falls to the shell:true descriptor.
+  compressLazyPath = resolveCompressLazyPath(),
 } = {}) {
   const ts = now ?? nowIso();
   const cap = typeof capBytes === 'number' ? capBytes : DEFAULT_CAP_BYTES;

package/src/install-agent.mjs

@@ -0,0 +1,220 @@
+// install-agent.mjs — wire a per-agent profile's legs into a project (Task 50.E/50.F).
+//
+// Given a profile (DATA from agent-profiles.mjs) + a project root, this lands the
+// profile's three legs in its DECLARED paths, reusing the kit's shared primitives:
+//   - MCP registration → mutateAgentConfig (touch-only-our-keys, refuse-on-parse-error)
+//   - hook entry       → mutateAgentConfig (the agent's hook-config file)
+//   - instruction file → a managed marker block (byte-preserving install/uninstall)
+//
+// This is the per-agent path. install.mjs keeps its existing Claude-Code wiring
+// for the default `--ide claude-code` route (regression-proof, D-180 / 50.E); this
+// module handles the OTHER agents (Kiro first). The kit's core — store, compression,
+// search, CLI, MCP server — is identical across agents; only these legs differ.
+//
+// Public surface:
+//   installAgent({ projectRoot, profile }) → { action, agent, changed, legs, errors? }
+//   uninstallAgent({ projectRoot, profile }) → { action, agent, changed }
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { mutateAgentConfig, atomicWrite } from './mutate-agent-config.mjs';
+import {
+  removeJsonKey,
+  pruneEmptyParent,
+  escapeRe,
+  trimLeadingNewlines,
+  trimTrailingNewlines,
+} from './managed-block.mjs';
+
+// The kit's MCP server entry — same shape settings-hooks.mjs writes for Claude
+// Code (`cmk mcp serve` over stdio). Agent-neutral: every agent registers the
+// same server; only the FILE it goes in differs (profile.mcp.path).
+const MCP_ENTRY = Object.freeze({ type: 'stdio', command: 'cmk', args: ['mcp', 'serve'] });
+const MCP_SERVER_NAME = 'claude-memory-kit';
+
+// The kit's lifecycle-hook commands, keyed by the ABSTRACT event the profile's
+// eventMap translates to the agent's concrete event name. Only the events an
+// agent supports (present in its eventMap) get wired.
+const HOOK_COMMANDS = Object.freeze({
+  sessionStart: 'cmk-inject-context',
+  promptSubmit: 'cmk-capture-prompt',
+  postEdit: 'cmk-observe-edit',
+  turnEnd: 'cmk-capture-turn',
+  sessionEnd: 'cmk-compress-session',
+});
+
+// Steering / instruction-file body. Kiro reads `inclusion: always` frontmatter
+// to keep this in context every session (kiro.dev primary-verified). The body is
+// intentionally short — it points the agent at the kit's recall surface; the rich
+// memory lives in context/.
+const INSTRUCTION_BODY = [
+  '# claude-memory-kit',
+  '',
+  'This project uses claude-memory-kit for durable, in-repo memory across sessions.',
+  'Recall before re-deriving: run `cmk search "<topic>"` for prior decisions, preferences,',
+  'and project facts; the curated tiers live under `context/`. Capture durable facts with',
+  '`cmk remember` — never hand-edit the memory files.',
+].join('\n');
+
+const MARK_START = '<!-- claude-memory-kit:start -->';
+const MARK_END = '<!-- claude-memory-kit:end -->';
+
+export function installAgent({ projectRoot, profile }) {
+  if (!projectRoot) throw new Error('installAgent: projectRoot is required');
+  if (!profile || !profile.name) throw new Error('installAgent: a profile is required');
+
+  const legs = {};
+  const errors = [];
+  let changed = false;
+
+  // ── MCP leg ───────────────────────────────────────────────────────────────
+  if (profile.mcp) {
+    const r = mutateAgentConfig({
+      path: join(projectRoot, profile.mcp.path),
+      format: 'json',
+      keyPath: [profile.mcp.serversKey, MCP_SERVER_NAME],
+      entry: MCP_ENTRY,
+    });
+    legs.mcp = r.action;
+    if (r.action === 'error') errors.push({ leg: 'mcp', ...r });
+    else if (r.changed) changed = true;
+  }
+
+  // ── hooks leg ───────────────────────────────────────────────────────────────
+  // Only if MCP didn't already error (refuse-to-clobber means a corrupt config
+  // should halt this agent's install — report, don't push past it).
+  if (profile.hooks && errors.length === 0) {
+    const hookEntry = buildHookEntry(profile);
+    const r = mutateAgentConfig({
+      path: join(projectRoot, profile.hooks.path),
+      format: 'json',
+      keyPath: ['hooks'],
+      entry: hookEntry,
+    });
+    legs.hooks = r.action;
+    if (r.action === 'error') errors.push({ leg: 'hooks', ...r });
+    else if (r.changed) changed = true;
+  }
+
+  // ── instruction leg (managed marker block) ──────────────────────────────────
+  if (errors.length === 0) {
+    const instrPath = join(projectRoot, profile.instructionFile);
+    const r = writeInstructionFile(instrPath, profile);
+    legs.instruction = r.action;
+    if (r.changed) changed = true;
+  }
+
+  if (errors.length > 0) {
+    return { action: 'error', agent: profile.name, changed, legs, errors };
+  }
+  return { action: 'installed', agent: profile.name, changed, legs };
+}
+
+export function uninstallAgent({ projectRoot, profile }) {
+  if (!projectRoot) throw new Error('uninstallAgent: projectRoot is required');
+  if (!profile || !profile.name) throw new Error('uninstallAgent: a profile is required');
+
+  let changed = false;
+
+  // MCP: remove only our server key, preserve siblings.
+  if (profile.mcp) {
+    const p = join(projectRoot, profile.mcp.path);
+    if (removeJsonKey(p, [profile.mcp.serversKey, MCP_SERVER_NAME])) changed = true;
+    // prune an emptied servers object we leave behind (no kit-shaped residue).
+    pruneEmptyParent(p, [profile.mcp.serversKey]);
+  }
+  // hooks: remove ONLY the event keys WE wrote (symmetry with the MCP leg —
+  // remove our keys, preserve any the user added to the same `hooks` object).
+  // This is safe even if a future profile points hooks.path at a shared file.
+  if (profile.hooks) {
+    const p = join(projectRoot, profile.hooks.path);
+    const ourEvents = Object.keys(buildHookEntry(profile));
+    for (const ev of ourEvents) {
+      if (removeJsonKey(p, ['hooks', ev])) changed = true;
+    }
+    // prune an emptied `hooks` object we leave behind (no residue).
+    pruneEmptyParent(p, ['hooks']);
+  }
+  // instruction: strip our marker block, byte-preserve the rest.
+  const instrPath = join(projectRoot, profile.instructionFile);
+  if (removeInstructionBlock(instrPath)) changed = true;
+
+  return { action: 'uninstalled', agent: profile.name, changed };
+}
+
+// ── internal helpers ───────────────────────────────────────────────────────
+
+// Build the agent's hook object: { <concreteEvent>: [ {command} ] } for each
+// abstract event the profile maps + the kit has a command for.
+function buildHookEntry(profile) {
+  const hooks = {};
+  for (const [abstractEvent, concreteEvent] of Object.entries(profile.hooks.eventMap)) {
+    const command = HOOK_COMMANDS[abstractEvent];
+    if (command) hooks[concreteEvent] = [{ command }];
+  }
+  return hooks;
+}
+
+// Write the instruction file with a managed marker block + agent-specific
+// frontmatter (Kiro wants `inclusion: always`). Idempotent: re-writing identical
+// content reports changed:false.
+function writeInstructionFile(path, profile) {
+  const frontmatter = needsInclusionFrontmatter(profile) ? '---\ninclusion: always\n---\n\n' : '';
+  const block = `${MARK_START}\n${INSTRUCTION_BODY}\n${MARK_END}`;
+  const desired = `${frontmatter}${block}\n`;
+
+  let existing = '';
+  if (existsSync(path)) existing = readFileSync(path, 'utf8');
+
+  let next;
+  if (existing === '') {
+    next = desired;
+  } else if (existing.includes(MARK_START) && existing.includes(MARK_END)) {
+    // refresh in place — replace only the managed block, byte-preserve the rest.
+    next = existing.replace(
+      new RegExp(`${escapeRe(MARK_START)}[\\s\\S]*?${escapeRe(MARK_END)}`),
+      block,
+    );
+  } else {
+    // append our block to the user's existing file.
+    next = `${trimTrailingNewlines(existing)}\n\n${block}\n`;
+  }
+
+  if (next === existing) return { action: 'unchanged', changed: false };
+  atomicWrite(path, next);
+  return { action: existing === '' ? 'created' : 'updated', changed: true };
+}
+
+function removeInstructionBlock(path) {
+  if (!existsSync(path)) return false;
+  const existing = readFileSync(path, 'utf8');
+  if (!existing.includes(MARK_START)) return false;
+  // Strip our block (+ surrounding blank lines). The inner [\s\S]*? is lazy +
+  // bounded by two fixed literal delimiters (no nested quantifier) → linear, not
+  // ReDoS-prone. The newline trims are done WITHOUT regex (no `\n*$`/`^\n+`
+  // super-linear shapes) — see trimLeadingNewlines/trimTrailingNewlines.
+  const blockRe = new RegExp(`${escapeRe(MARK_START)}[\\s\\S]*?${escapeRe(MARK_END)}`);
+  const withoutBlock = existing.replace(blockRe, '');
+  const stripped = trimLeadingNewlines(collapseBlankRun(withoutBlock));
+  atomicWrite(path, stripped);
+  return true;
+}
+
+// removeJsonKey / pruneEmptyParent / escapeRe / trim{Leading,Trailing}Newlines
+// are now shared from managed-block.mjs (deduped — the kit's shared-module
+// discipline; install-kiro.mjs uses the same source).
+
+function needsInclusionFrontmatter(profile) {
+  // Kiro steering files use `inclusion: always`. Driven by the profile's
+  // instruction path living under a steering dir — kept simple for v0.4.0
+  // (only Kiro needs it); generalize when a second steering-style agent lands.
+  return profile.instructionFile.includes('/steering/') || profile.name === 'kiro';
+}
+
+// Collapse a run of 2+ blank lines left where our block was removed into a
+// single newline, so an uninstall doesn't leave a widening gap.
+function collapseBlankRun(s) {
+  // split on newlines, drop empty segments created by the removed block's
+  // surrounding blanks, rejoin — no regex, no backtracking.
+  return s.replace(/\n{3,}/g, '\n\n');
+}