memtrace 0.6.20 → 0.6.30

package/bin/memtrace.js

@@ -36,6 +36,20 @@ const args = process.argv.slice(2);
 // upgrade completes, we shell out to `memtrace <rest>` via PATH —
 // which now resolves to the freshly-installed shim, not this old one.
 
+// ── `memtrace setup` — (re)run the integration phases without npm ───────────
+// The consent layer (memtrace-public #25) can defer configuration when
+// `npm install -g memtrace` runs without a consent signal. This command is
+// the documented way to complete (or re-run) setup afterwards. Flags:
+// --yes/-y, --project-only, --no-hooks (see lib/install-consent.js).
+if (args[0] === "setup") {
+  const result = spawnSync(
+    process.execPath,
+    [path.join(__dirname, "..", "install.js"), ...args.slice(1)],
+    { stdio: "inherit" }
+  );
+  process.exit(result.status ?? 1);
+}
+
 if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
   // `npm.cmd` on win32 needs `shell: true` since the CVE-2024-27980
   // mitigation in Node 18.20+ / 20.12+ / 21.7+. The helpers in
@@ -43,6 +57,56 @@ if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
   const npmCmd = platformBinary("npm", process.platform);
   const memtraceCmd = platformBinary("memtrace", process.platform);
 
+  // ── Consent gate (memtrace-public #25) ─────────────────────────────────
+  // The npm postinstall hook that performs the actual config mutation runs
+  // non-interactively, so THIS process — the one that owns the TTY — asks
+  // for consent and forwards the grant (plus scoping flags) via env vars.
+  // A previously consented install (manifest / MEMTRACE.md / managed hooks
+  // present) counts as standing consent so upgrades stay friction-free.
+  const consent = require("../lib/install-consent");
+  const flags = consent.parseInstallFlags(args.slice(1));
+  const home = consent.resolveHome();
+  const consentEnv = {};
+  if (flags.projectOnly) consentEnv.MEMTRACE_INSTALL_PROJECT_ONLY = "1";
+  if (flags.noHooks) consentEnv.MEMTRACE_INSTALL_NO_HOOKS = "1";
+
+  const decision = consent.decideConsent({
+    yes: flags.yes,
+    isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    isNpmLifecycle: false,
+    hasPriorInstall: consent.detectPriorInstall(home),
+  });
+  const mutations = consent.buildMutationList({
+    home,
+    cwd: process.cwd(),
+    projectOnly: flags.projectOnly,
+    noHooks: flags.noHooks,
+  });
+
+  if (decision === "abort") {
+    console.error(consent.formatMutationList(mutations, flags));
+    console.error("");
+    console.error("memtrace install: refusing to modify user configuration without consent in a non-interactive session.");
+    console.error("memtrace install: re-run with --yes (or -y) to approve these changes.");
+    process.exit(consent.EXIT_NO_CONSENT);
+  }
+  if (decision === "prompt") {
+    console.log(consent.formatMutationList(mutations, flags));
+    // Synchronous prompt: the remainder of this script is top-level code
+    // and would otherwise fall through to the Rust-binary delegation
+    // while an async prompt was still pending.
+    const ok = consent.promptYesNoSync("\nProceed with these changes? [y/N] ");
+    if (!ok) {
+      console.log("memtrace install: aborted — no files were modified. Re-run with --yes to skip this prompt.");
+      process.exit(consent.EXIT_NO_CONSENT);
+    }
+  }
+  consentEnv.MEMTRACE_INSTALL_YES = "1";
+  runInstallBranch(npmCmd, memtraceCmd, flags.rest, consentEnv);
+}
+
+function runInstallBranch(npmCmd, memtraceCmd, rest, consentEnv) {
+
   // ── Pre-commit hook drift check (agent-precommit-optin, 2026-05-08) ──
   // `memtrace install` is the natural place a user re-runs after an
   // upgrade. If a prior version installed the pre-commit hook (now
@@ -72,7 +136,9 @@ if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
     ["install", "-g", "memtrace@latest"],
     spawnOptionsForPlatform(process.platform, {
       stdio: "inherit",
-      env: { ...process.env, MEMTRACE_INSTALL_PARENT: "1" },
+      // consentEnv carries MEMTRACE_INSTALL_YES / _PROJECT_ONLY / _NO_HOOKS
+      // through npm into the postinstall hook (memtrace-public #25).
+      env: { ...process.env, MEMTRACE_INSTALL_PARENT: "1", ...consentEnv },
     })
   );
 
@@ -88,7 +154,6 @@ if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
     process.exit(installResult.status ?? 1);
   }
 
-  const rest = args.slice(1);
   if (rest.length === 0) {
     process.stdout.write("memtrace: latest installed.\n");
     process.exit(0);

package/install.js

@@ -236,45 +236,87 @@ function selfHealPlatformPackage() {
   return true;
 }
 
-// ── Main postinstall ─────────────────────────────────────────────────────────
-
-if (require.main === module) {
-  // 1. Verify binary exists + is executable. If the optional platform
-  //    dep was silently omitted by npm, fetch it directly.
-  selfHealPlatformPackage();
+// ── Integration phases (post-consent) ───────────────────────────────────────
+//
+// Everything below this line mutates user configuration and therefore only
+// runs AFTER the consent gate in `main()` (memtrace-public #25). The phases
+// are identical to the pre-consent-era behavior; the gate, the scoping
+// flags, and the backup manifest are the only additions.
+//
+// flags: { yes, projectOnly, noHooks } — see lib/install-consent.js.
+function runIntegrationPhases({ home, flags }) {
+  const manifestLib = require("./lib/install-manifest");
+  const claudeDir = path.join(home, ".claude");
 
-  let binaryPath = null;
-  try {
-    binaryPath = getBinaryPath();
-    if (!fs.existsSync(binaryPath)) {
-      throw new Error(`Binary not found at: ${binaryPath}`);
+  // Phase 0 — snapshot every user-global file we may mutate BEFORE any
+  // mutation, so uninstall can restore pre-install bytes. --project-only
+  // touches nothing under home, so there is nothing to back up.
+  let snapshot = null;
+  if (!flags.projectOnly) {
+    try {
+      snapshot = manifestLib.snapshotFiles(home, [
+        {
+          path: path.join(claudeDir, "settings.json"),
+          owned: {
+            kind: "json-keys",
+            keys: [
+              "hooks.* entries with _managed_by=memtrace (UserPromptSubmit, PostToolUse)",
+              "hooks.PreToolUse entries whose command contains 'route --hook' (Rail)",
+              "mcpServers.memtrace",
+              "enabledPlugins[\"memtrace-skills@memtrace\"]",
+              "extraKnownMarketplaces.memtrace (+ legacy marketplace containers)",
+            ],
+          },
+        },
+        {
+          path: path.join(claudeDir, "CLAUDE.md"),
+          owned: { kind: "block", markers: ["BEGIN MEMTRACE BLOCK", "END MEMTRACE BLOCK"] },
+        },
+        {
+          path: path.join(claudeDir, "MEMTRACE.md"),
+          owned: { kind: "file" },
+        },
+      ]);
+    } catch (e) {
+      console.warn(`memtrace: failed to write pre-install backups: ${e.message}`);
     }
-    ensureExecutableBits(binaryPath);
-    console.log(`memtrace: binary installed at ${binaryPath}`);
-  } catch (e) {
-    console.warn(`memtrace: ${e.message}`);
   }
 
-  // 2. Delegate to compiled installer (global, all agents, non-interactive)
-  const bundled = path.join(__dirname, "installer", "dist", "index.js");
-  if (fs.existsSync(bundled)) {
-    const result = spawnSync(process.execPath, [bundled, "install", "--yes"], {
-      stdio: "inherit",
-      env: { ...process.env, MEMTRACE_POSTINSTALL: "1" },
-    });
-    if (result.status !== 0) {
-      console.warn(`memtrace: installer exited with code ${result.status}; continuing.`);
+  // Phase 1 — delegate to compiled installer (skills + MCP + plugin).
+  //   default:        global, all agents, non-interactive
+  //   --project-only: local scope, Claude only — writes <cwd>/.claude/skills
+  //                   and <cwd>/.mcp.json, never a home path
+  //   --no-hooks:     MEMTRACE_INSTALL_NO_HOOKS=1 tells the bundled
+  //                   installer to skip the Rail PreToolUse hook
+  if (process.env.MEMTRACE_INSTALL_SKIP_BUNDLED !== "1") {
+    const bundled = path.join(__dirname, "installer", "dist", "index.js");
+    if (fs.existsSync(bundled)) {
+      const instArgs = ["install", "--yes"];
+      if (flags.projectOnly) instArgs.push("--local", "--only", "claude");
+      const childEnv = { ...process.env, MEMTRACE_POSTINSTALL: "1" };
+      if (flags.noHooks) childEnv.MEMTRACE_INSTALL_NO_HOOKS = "1";
+      const result = spawnSync(process.execPath, [bundled, ...instArgs], {
+        stdio: "inherit",
+        env: childEnv,
+      });
+      if (result.status !== 0) {
+        console.warn(`memtrace: installer exited with code ${result.status}; continuing.`);
+      }
+    } else {
+      console.warn("memtrace: bundled installer not found at installer/dist/index.js");
+      console.warn("memtrace: run 'memtrace install' manually after the package is built.");
     }
-  } else {
-    console.warn("memtrace: bundled installer not found at installer/dist/index.js");
-    console.warn("memtrace: run 'memtrace install' manually after the package is built.");
   }
 
-  // 3. Claude Code adoption layer (v0.3.35+):
+  // Phases 2+ are user-global by definition; --project-only stops here.
+  if (flags.projectOnly) return;
+
+  // Phase 2 — Claude Code adoption layer (v0.3.35+):
   //    - write ~/.claude/MEMTRACE.md (sidecar directive we own)
   //    - add a breadcrumb block to ~/.claude/CLAUDE.md if it exists
   //    - register UserPromptSubmit + PostToolUse hooks in
   //      ~/.claude/settings.json under `_managed_by: "memtrace"`
+  //      (skipped entirely under --no-hooks)
   //
   //    This layer is what makes Claude Code consistently reach for
   //    Memtrace MCP tools FIRST instead of falling back to Read/Grep
@@ -292,8 +334,7 @@ if (require.main === module) {
         }
       }
     }
-    const claudeDir = path.join(os.homedir(), ".claude");
-    const summary = installToFs({ claudeDir, hooksDir });
+    const summary = installToFs({ claudeDir, hooksDir, noHooks: flags.noHooks });
     if (summary.wrote.length > 0) {
       console.log(
         `memtrace: configured Claude Code integration (${summary.wrote.length} file(s) updated)`
@@ -303,9 +344,10 @@ if (require.main === module) {
     console.warn(`memtrace: Claude Code integration setup skipped: ${e.message}`);
   }
 
-  // 5. Persist uninstall script to ~/.memtrace/ (survives `npm uninstall -g`).
+  // Phase 3 — persist uninstall script to ~/.memtrace/ (survives
+  // `npm uninstall -g`, which skips preuninstall for global packages).
   try {
-    const memtraceDir = path.join(os.homedir(), ".memtrace");
+    const memtraceDir = path.join(home, ".memtrace");
     fs.mkdirSync(memtraceDir, { recursive: true });
     fs.copyFileSync(
       path.join(__dirname, "uninstall.js"),
@@ -316,11 +358,104 @@ if (require.main === module) {
     console.warn(`memtrace: failed to persist uninstall script: ${e.message}`);
   }
 
+  // Phase 4 — record post-install hashes + write the manifest that
+  // `memtrace uninstall` restores from.
+  if (snapshot) {
+    try {
+      manifestLib.finalizeManifest(home, snapshot, {
+        createdPaths: [
+          path.join(claudeDir, "plugins", "cache", "memtrace"),
+          path.join(home, ".memtrace", "uninstall.js"),
+        ],
+        flags: { projectOnly: flags.projectOnly, noHooks: flags.noHooks },
+        version: require("./package.json").version,
+      });
+      console.log(`memtrace: backups + install manifest written to ${manifestLib.backupRoot(home)}`);
+    } catch (e) {
+      console.warn(`memtrace: failed to write install manifest: ${e.message}`);
+    }
+  }
+}
+
+// ── Main postinstall / `memtrace setup` entry ────────────────────────────────
+
+async function main() {
+  const consent = require("./lib/install-consent");
+
+  // Step 1 — verify the platform binary exists + is executable. This is
+  // package-internal provisioning (never touches user config), so it runs
+  // before the consent gate: even a "defer" install must leave a working
+  // binary behind. MEMTRACE_INSTALL_SKIP_SELFHEAL=1 short-circuits it in
+  // tests (it can hit the network via `npm install`).
+  if (process.env.MEMTRACE_INSTALL_SKIP_SELFHEAL !== "1") {
+    selfHealPlatformPackage();
+    try {
+      const binaryPath = getBinaryPath();
+      if (!fs.existsSync(binaryPath)) {
+        throw new Error(`Binary not found at: ${binaryPath}`);
+      }
+      ensureExecutableBits(binaryPath);
+      console.log(`memtrace: binary installed at ${binaryPath}`);
+    } catch (e) {
+      console.warn(`memtrace: ${e.message}`);
+    }
+  }
+
+  // Step 2 — consent gate (memtrace-public #25). Print the full mutation
+  // list and require explicit approval before touching ANY user config.
+  const flags = consent.parseInstallFlags(process.argv.slice(2));
+  const home = consent.resolveHome();
+  const mutations = consent.buildMutationList({
+    home,
+    cwd: process.cwd(),
+    projectOnly: flags.projectOnly,
+    noHooks: flags.noHooks,
+  });
+  const decision = consent.decideConsent({
+    yes: flags.yes,
+    isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    isNpmLifecycle: process.env.npm_lifecycle_event === "postinstall",
+    hasPriorInstall: consent.detectPriorInstall(home),
+  });
+
+  if (decision === "prompt") {
+    console.log(consent.formatMutationList(mutations, flags));
+    const ok = await consent.promptYesNo("\nProceed with these changes? [y/N] ");
+    if (!ok) {
+      console.log("memtrace: aborted — no files were modified. Re-run with --yes to skip this prompt.");
+      process.exit(consent.EXIT_NO_CONSENT);
+    }
+  } else if (decision === "abort") {
+    console.error(consent.formatMutationList(mutations, flags));
+    console.error("");
+    console.error("memtrace: refusing to modify user configuration without consent in a non-interactive session.");
+    console.error("memtrace: re-run with --yes (or set MEMTRACE_INSTALL_YES=1) to approve these changes.");
+    process.exit(consent.EXIT_NO_CONSENT);
+  } else if (decision === "defer") {
+    // npm postinstall without a consent signal: never silently mutate, but
+    // never fail the package install either (a non-zero lifecycle exit
+    // would abort `npm install -g memtrace` for every fresh CI user).
+    console.log(consent.formatMutationList(mutations, flags));
+    console.log("");
+    console.log("memtrace: skipped agent/Claude Code configuration — no consent signal in npm lifecycle.");
+    console.log("memtrace: run `memtrace setup --yes` (or set MEMTRACE_INSTALL_YES=1 before npm install) to complete setup.");
+    process.exit(0);
+  }
+
+  runIntegrationPhases({ home, flags });
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    console.error(`memtrace: install failed: ${e.message}`);
+    process.exit(1);
+  });
 }
 
 module.exports = {
   getBinaryPath,
   ensureExecutableBits,
+  runIntegrationPhases,
   selfHealPlatformPackage,
   buildSelfHealEnv,
   buildSelfHealInstallArgs,

package/installer/dist/transformers/claude.js

@@ -430,11 +430,15 @@ async function registerMcpServer(memtraceBinaryPath) {
     // hook defaults to observe mode (zero behavior change) until the user opts
     // into MEMTRACE_RAIL=nudge|rail|strict. Failure here must not block MCP
     // registration.
-    try {
-        registerRailHookInSettingsAt(settingsFile, memtraceBinaryPath);
-    }
-    catch (e) {
-        console.warn(`memtrace: failed to register Rail hook: ${e.message}`);
+    // `memtrace install --no-hooks` (memtrace-public #25) propagates here via
+    // MEMTRACE_INSTALL_NO_HOOKS=1 — skip ALL settings.json hook registration.
+    if (process.env.MEMTRACE_INSTALL_NO_HOOKS !== '1') {
+        try {
+            registerRailHookInSettingsAt(settingsFile, memtraceBinaryPath);
+        }
+        catch (e) {
+            console.warn(`memtrace: failed to register Rail hook: ${e.message}`);
+        }
     }
     // Strategy 1 (preferred): claude CLI's own add-json path
     const viaCli = await tryMcpAddJson(memtraceBinaryPath);

package/installer/dist/transformers/codex.js

@@ -4,6 +4,7 @@ import path from 'path';
 import { commandExists, execCommand } from '../utils.js';
 import { registerSettingsHook, removeSettingsHook, CODEX_MATCHER, } from './rail-hooks.js';
 const MCP_SERVER_NAME = 'memtrace';
+const CODEX_MCP_SHIM_NAME = 'memtrace-mcp-codex-shim.cjs';
 function codexRailHooksPath(ctx) {
     const base = ctx.scope === 'global' ? path.join(os.homedir(), '.codex') : path.join(ctx.cwd, '.codex');
     return path.join(base, 'hooks.json');
@@ -37,6 +38,82 @@ function writeTextAtomic(filePath, content) {
     fs.writeFileSync(tmpPath, content);
     fs.renameSync(tmpPath, filePath);
 }
+function codexMcpShimSource() {
+    return `#!/usr/bin/env node
+const { spawn } = require('node:child_process');
+
+const binary = process.argv[2] || 'memtrace';
+const child = spawn(binary, ['mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
+
+process.stdin.pipe(child.stdin);
+child.stderr.pipe(process.stderr);
+
+function stripAnnotations(line) {
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    return line;
+  }
+
+  const content = message && message.result && message.result.content;
+  if (!Array.isArray(content)) return line;
+
+  const assistantItems = [];
+  const fallbackItems = [];
+  for (const item of content) {
+    if (!item || typeof item !== 'object') continue;
+    const clean = { ...item };
+    const annotations = clean.annotations;
+    delete clean.annotations;
+    fallbackItems.push(clean);
+    const audience = annotations && annotations.audience;
+    if (Array.isArray(audience) && audience.includes('assistant')) {
+      assistantItems.push(clean);
+    }
+  }
+
+  message.result.content = assistantItems.length > 0 ? assistantItems : fallbackItems;
+  return JSON.stringify(message);
+}
+
+let buffer = '';
+child.stdout.on('data', (chunk) => {
+  buffer += chunk.toString('utf8');
+  let index = buffer.indexOf('\\n');
+  while (index !== -1) {
+    const line = buffer.slice(0, index);
+    buffer = buffer.slice(index + 1);
+    process.stdout.write(stripAnnotations(line) + '\\n');
+    index = buffer.indexOf('\\n');
+  }
+});
+
+child.stdout.on('end', () => {
+  if (buffer.length > 0) process.stdout.write(stripAnnotations(buffer));
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  process.exit(code ?? 0);
+});
+`;
+}
+function codexMcpShimPath(configFile) {
+    return path.join(path.dirname(configFile), CODEX_MCP_SHIM_NAME);
+}
+function writeCodexMcpShim(configFile) {
+    const shimPath = codexMcpShimPath(configFile);
+    writeTextAtomic(shimPath, codexMcpShimSource());
+    try {
+        fs.chmodSync(shimPath, 0o755);
+    }
+    catch {
+        // Windows and locked-down filesystems may reject chmod; Codex invokes it
+        // through Node, so executable bits are a convenience, not a requirement.
+    }
+    return shimPath;
+}
 function isMemtraceMcpTable(tableName) {
     return tableName === `mcp_servers.${MCP_SERVER_NAME}`
         || tableName === `mcp_servers."${MCP_SERVER_NAME}"`
@@ -119,10 +196,11 @@ export function registerCodexMcpAt(configFile, binary) {
     // after the freshly written parent block for readability.
     const stripped = stripCodexMcpServer(existing);
     const { rest, envBlock } = extractMemtraceEnvBlock(stripped);
+    const shimPath = writeCodexMcpShim(configFile);
     const block = [
         `[mcp_servers.${MCP_SERVER_NAME}]`,
-        `command = ${tomlString(binary)}`,
-        `args = [${tomlString('mcp')}]`,
+        `command = ${tomlString(process.execPath)}`,
+        `args = [${[shimPath, binary].map(tomlString).join(', ')}]`,
     ].join('\n');
     const parts = [];
     if (rest)
@@ -167,15 +245,11 @@ export const codexTransformer = {
         const warnings = [];
         const mcpConfigPath = codexConfigPath(ctx);
         if (!ctx.skipMcp) {
-            if (ctx.scope === 'global' && await tryCodexMcpAdd(ctx.memtraceBinary)) {
-                mcpRegistered = true;
-            }
-            else {
-                registerCodexMcpAt(mcpConfigPath, ctx.memtraceBinary);
-                mcpRegistered = true;
-                if (ctx.scope === 'global') {
-                    warnings.push('codex CLI MCP registration was unavailable; wrote ~/.codex/config.toml directly.');
-                }
+            const cliRegistered = ctx.scope === 'global' && await tryCodexMcpAdd(ctx.memtraceBinary);
+            registerCodexMcpAt(mcpConfigPath, ctx.memtraceBinary);
+            mcpRegistered = true;
+            if (ctx.scope === 'global' && !cliRegistered) {
+                warnings.push('codex CLI MCP registration was unavailable; wrote ~/.codex/config.toml directly.');
             }
         }
         // ─── memtrace-rail ─── Wire the discovery hook into .codex/hooks.json

package/lib/claude-integration.js

@@ -339,6 +339,8 @@ function removeSettingsHooks(settings) {
  * @param {object} [opts]
  * @param {string} [opts.claudeDir]   default `~/.claude`
  * @param {string} [opts.hooksDir]    absolute dir where hook scripts live
+ * @param {boolean} [opts.noHooks]    skip settings.json hook registration
+ *                                    entirely (`memtrace install --no-hooks`)
  * @returns {object}                  summary `{ wrote: [...], skipped: [...] }`
  */
 function installToFs(opts = {}) {
@@ -372,8 +374,12 @@ function installToFs(opts = {}) {
         summary.skipped.push(claudeMdPath + " (does not exist; not creating)");
     }
 
-    // 3. Register hooks in settings.json.
+    // 3. Register hooks in settings.json (skipped under --no-hooks).
     const settingsPath = path.join(claudeDir, "settings.json");
+    if (opts.noHooks) {
+        summary.skipped.push(settingsPath + " (--no-hooks)");
+        return summary;
+    }
     let settings = {};
     if (fs.existsSync(settingsPath)) {
         try {

package/lib/install-consent.js

@@ -0,0 +1,202 @@
+"use strict";
+
+// Consent + scoping layer for `memtrace install` / npm postinstall.
+//
+// memtrace-public issue #25: `memtrace install` mutated user-global
+// Claude Code configuration (~/.claude/settings.json, ~/.claude/CLAUDE.md,
+// ~/.claude/MEMTRACE.md, MCP/plugin/marketplace registries) with no
+// consent prompt, no documented mutation list, and no opt-out flags —
+// silently diverging dotfiles managed by chezmoi / Nix home-manager.
+//
+// This module is the single source of truth for:
+//   1. The full mutation list (what install will touch, with paths)
+//   2. Flag parsing  (--yes/-y, --project-only, --no-hooks)
+//   3. The consent decision table (pure, unit-tested)
+//
+// All side effects stay in install.js / uninstall.js / bin/memtrace.js.
+//
+// Environment knobs (set by the bin shim or the Rust `memtrace install`
+// parent after IT obtained consent on the TTY it owns, or by CI):
+//   MEMTRACE_INSTALL_YES=1           — consent granted (same as --yes)
+//   MEMTRACE_ASSUME_YES=1            — alias for the above
+//   MEMTRACE_INSTALL_PROJECT_ONLY=1  — same as --project-only
+//   MEMTRACE_INSTALL_NO_HOOKS=1      — same as --no-hooks
+//   MEMTRACE_INSTALL_HOME=<dir>      — home-dir override (tests)
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const readline = require("readline");
+
+/** Exit code used whenever install aborts without consent. */
+const EXIT_NO_CONSENT = 2;
+
+function resolveHome(env = process.env) {
+    return env.MEMTRACE_INSTALL_HOME || os.homedir();
+}
+
+/**
+ * Parse install flags out of an argv slice. Unrecognised arguments are
+ * preserved in `rest` (the bin shim chains them: `memtrace install start`).
+ * Env vars provide the non-interactive channel through `npm install -g`.
+ */
+function parseInstallFlags(argv = [], env = process.env) {
+    const flags = {
+        yes: env.MEMTRACE_INSTALL_YES === "1" || env.MEMTRACE_ASSUME_YES === "1",
+        projectOnly: env.MEMTRACE_INSTALL_PROJECT_ONLY === "1",
+        noHooks: env.MEMTRACE_INSTALL_NO_HOOKS === "1",
+        rest: [],
+    };
+    for (const a of argv) {
+        if (a === "--yes" || a === "-y") flags.yes = true;
+        else if (a === "--project-only") flags.projectOnly = true;
+        else if (a === "--no-hooks") flags.noHooks = true;
+        else flags.rest.push(a);
+    }
+    return flags;
+}
+
+/**
+ * The complete list of files/registries `memtrace install` may mutate,
+ * as `{ path, change }` entries. Pure. This is what gets printed before
+ * any mutation happens and what docs/INSTALL-FOOTPRINT.md documents.
+ */
+function buildMutationList({ home, cwd, projectOnly = false, noHooks = false }) {
+    const list = [];
+    if (projectOnly) {
+        list.push(
+            { path: path.join(cwd, ".claude", "skills", "memtrace-*"), change: "create/replace Memtrace skill directories (project scope)" },
+            { path: path.join(cwd, ".mcp.json"), change: "merge-add mcpServers.memtrace entry (project scope)" },
+        );
+        return list;
+    }
+    const claude = path.join(home, ".claude");
+    list.push(
+        { path: path.join(claude, "MEMTRACE.md"), change: "create/overwrite (file is fully memtrace-owned)" },
+        { path: path.join(claude, "CLAUDE.md"), change: "append one marker-delimited breadcrumb block (only if the file already exists)" },
+        {
+            path: path.join(claude, "settings.json"),
+            change: noHooks
+                ? "merge-add mcpServers.memtrace, enabledPlugins[\"memtrace-skills@memtrace\"], extraKnownMarketplaces.memtrace (hooks SKIPPED via --no-hooks)"
+                : "merge-add hooks (UserPromptSubmit, PostToolUse[mcp__memtrace__.*], PreToolUse Rail[Grep|Glob|Bash]), mcpServers.memtrace, enabledPlugins[\"memtrace-skills@memtrace\"], extraKnownMarketplaces.memtrace",
+        },
+        { path: path.join(claude, "plugins", "cache", "memtrace", "memtrace-skills") + path.sep, change: "create/replace plugin cache (skills payload)" },
+        { path: path.join(claude, "plugins", "marketplaces", "{memtrace,syncable-dev-memtrace*}") + path.sep, change: "remove stale + re-clone marketplace caches (via `claude` CLI when available)" },
+        { path: path.join(claude, "plugins", "installed_plugins.json"), change: "plugin registry entry (written by the `claude` CLI when available)" },
+        { path: path.join(home, ".claude.json"), change: "possible memtrace MCP entry (written by `claude mcp add-json --scope user` when the `claude` CLI is available)" },
+        { path: path.join(home, ".memtrace") + path.sep, change: "create memtrace data dir: persisted uninstall.js + install-backup/ (backups + manifest)" },
+        { path: path.join(home, "{.cursor,.codex,.gemini,.codeium,.hermes,.kiro,.copilot,.config/opencode,VS Code user config}"), change: "skills + memtrace MCP registration for other detected agents (same merge-add pattern)" },
+    );
+    return list;
+}
+
+function formatMutationList(list, { projectOnly = false, noHooks = false } = {}) {
+    const lines = [];
+    lines.push("memtrace install will modify the following files:");
+    lines.push("");
+    for (const m of list) {
+        lines.push(`  ${m.path}`);
+        lines.push(`      ${m.change}`);
+    }
+    lines.push("");
+    lines.push("  Every change is marker-tagged or merge-added; a backup of each");
+    lines.push("  pre-existing file plus a manifest is written to ~/.memtrace/install-backup/.");
+    lines.push("  `memtrace uninstall` restores from that manifest (surgically removing only");
+    lines.push("  memtrace-added blocks if you edited a file after install).");
+    lines.push("");
+    const flagHints = [];
+    if (!projectOnly) flagHints.push("--project-only (never touch ~/.claude or any home path)");
+    if (!noHooks) flagHints.push("--no-hooks (skip all settings.json hook registration)");
+    flagHints.push("--yes / -y (skip this prompt)");
+    lines.push(`  Flags: ${flagHints.join(", ")}`);
+    lines.push("  Full footprint: docs/INSTALL-FOOTPRINT.md (memtrace repo) / https://github.com/syncable-dev/memtrace-public");
+    return lines.join("\n");
+}
+
+/**
+ * A previous memtrace install on this machine implies prior consent: a
+ * re-run is a refresh of state the user already accepted, so upgrades
+ * (`memtrace install`, `npm i -g memtrace@latest`) stay friction-free
+ * and behave exactly as before this consent layer existed.
+ */
+function detectPriorInstall(home) {
+    try {
+        if (fs.existsSync(path.join(home, ".memtrace", "install-backup", "manifest.json"))) return true;
+        if (fs.existsSync(path.join(home, ".claude", "MEMTRACE.md"))) return true;
+        const settingsPath = path.join(home, ".claude", "settings.json");
+        if (fs.existsSync(settingsPath)) {
+            const text = fs.readFileSync(settingsPath, "utf8");
+            if (text.includes('"_managed_by": "memtrace"') || text.includes('"_managed_by":"memtrace"')) {
+                return true;
+            }
+        }
+    } catch {
+        // unreadable home — treat as fresh install (consent required)
+    }
+    return false;
+}
+
+/**
+ * Pure consent decision table.
+ *
+ *   proceed — consent established (--yes / env / prior consented install)
+ *   prompt  — interactive TTY available: print the list and ask
+ *   defer   — npm lifecycle (postinstall) without consent: print the
+ *             list, SKIP all user-config mutation, exit 0. Exiting 2
+ *             here would fail the entire `npm install -g memtrace`
+ *             (lifecycle scripts propagate), which would break every
+ *             fresh CI install. "Never silently mutate from a pipe" is
+ *             honored: nothing is mutated and the skip is loud.
+ *   abort   — any other non-TTY invocation without consent: print the
+ *             list and exit 2. Never silently mutate from a pipe.
+ */
+function decideConsent({ yes, isTTY, isNpmLifecycle, hasPriorInstall }) {
+    if (yes || hasPriorInstall) return "proceed";
+    if (isNpmLifecycle) return "defer";
+    if (isTTY) return "prompt";
+    return "abort";
+}
+
+/**
+ * Synchronous y/N prompt (default No) for callers whose remaining
+ * top-level code would otherwise race an async prompt (bin/memtrace.js).
+ * Blocking read on fd 0; any read error counts as "no".
+ */
+function promptYesNoSync(question) {
+    process.stdout.write(question);
+    const buf = Buffer.alloc(256);
+    let n = 0;
+    for (;;) {
+        try {
+            n = fs.readSync(0, buf, 0, 256);
+            break;
+        } catch (e) {
+            if (e.code === "EAGAIN") continue; // non-blocking stdin: retry
+            return false;
+        }
+    }
+    return /^y(es)?$/i.test(buf.toString("utf8", 0, n).trim());
+}
+
+/** Ask a y/N question on the current TTY. Default: No. */
+function promptYesNo(question) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+
+module.exports = {
+    EXIT_NO_CONSENT,
+    resolveHome,
+    parseInstallFlags,
+    buildMutationList,
+    formatMutationList,
+    detectPriorInstall,
+    decideConsent,
+    promptYesNo,
+    promptYesNoSync,
+};

package/lib/install-manifest.js

@@ -0,0 +1,138 @@
+"use strict";
+
+// Backup + manifest layer for `memtrace install` (memtrace-public #25).
+//
+// Before install mutates any user-global file it snapshots the file's
+// pre-install bytes into ~/.memtrace/install-backup/<timestamp>/ and,
+// after all phases complete, writes a manifest recording for each file:
+//
+//   - whether it existed before install
+//   - where the backup copy lives
+//   - sha256 BEFORE install (preSha256)
+//   - sha256 AFTER install completed (postSha256)
+//   - exactly which memtrace-owned blocks/keys the file gained
+//
+// `memtrace uninstall` then has two safe paths per file:
+//
+//   current sha == postSha256  → file untouched since install:
+//                                restore the backup byte-for-byte
+//                                (or delete the file if we created it)
+//   current sha != postSha256  → user edited the file after install:
+//                                surgically remove ONLY the recorded
+//                                memtrace-owned blocks/keys, preserving
+//                                every user byte.
+//
+// The manifest lives at ~/.memtrace/install-backup/manifest.json and is
+// renamed to manifest.consumed-<ts>.json after a successful restore so
+// repeated uninstalls are idempotent no-ops.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const MANIFEST_VERSION = 1;
+
+function backupRoot(home) {
+    return path.join(home, ".memtrace", "install-backup");
+}
+
+function manifestPath(home) {
+    return path.join(backupRoot(home), "manifest.json");
+}
+
+function sha256OfFile(filePath) {
+    try {
+        return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+    } catch {
+        return null; // missing/unreadable
+    }
+}
+
+/**
+ * Snapshot the pre-install state of `targets` (absolute paths).
+ * Copies each existing file into a timestamped backup dir.
+ * Returns `{ stamp, dir, entries }`; entries carry `owned` descriptors
+ * so uninstall knows exactly what memtrace added to each file.
+ *
+ * @param {string} home
+ * @param {Array<{path: string, owned: object}>} targets
+ */
+function snapshotFiles(home, targets, now = new Date()) {
+    const stamp = now.toISOString().replace(/[:.]/g, "-");
+    const dir = path.join(backupRoot(home), stamp);
+    const entries = [];
+    let idx = 0;
+    for (const t of targets) {
+        const existed = fs.existsSync(t.path);
+        let backupPath = null;
+        if (existed) {
+            fs.mkdirSync(dir, { recursive: true });
+            backupPath = path.join(dir, `${idx}-${path.basename(t.path)}`);
+            fs.copyFileSync(t.path, backupPath);
+        }
+        entries.push({
+            path: t.path,
+            owned: t.owned,
+            existedBefore: existed,
+            backupPath,
+            preSha256: existed ? sha256OfFile(t.path) : null,
+            postSha256: null, // filled in by finalizeManifest
+        });
+        idx++;
+    }
+    return { stamp, dir, entries };
+}
+
+/**
+ * Record post-install hashes and persist the manifest. Call AFTER every
+ * install phase has finished mutating files.
+ */
+function finalizeManifest(home, snapshot, { createdPaths = [], flags = {}, version = null } = {}) {
+    for (const e of snapshot.entries) {
+        e.postSha256 = sha256OfFile(e.path);
+    }
+    const manifest = {
+        version: MANIFEST_VERSION,
+        memtraceVersion: version,
+        createdAt: new Date().toISOString(),
+        backupDir: snapshot.dir,
+        flags,
+        entries: snapshot.entries,
+        // Paths memtrace created wholesale (safe to delete on uninstall).
+        createdPaths,
+    };
+    fs.mkdirSync(backupRoot(home), { recursive: true });
+    fs.writeFileSync(manifestPath(home), JSON.stringify(manifest, null, 2) + "\n");
+    return manifest;
+}
+
+function readManifest(home) {
+    try {
+        return JSON.parse(fs.readFileSync(manifestPath(home), "utf8"));
+    } catch {
+        return null;
+    }
+}
+
+/** Rename the manifest aside so a second uninstall is a no-op. */
+function consumeManifest(home) {
+    const p = manifestPath(home);
+    if (!fs.existsSync(p)) return;
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    try {
+        fs.renameSync(p, path.join(backupRoot(home), `manifest.consumed-${stamp}.json`));
+    } catch {
+        try { fs.unlinkSync(p); } catch { /* best-effort */ }
+    }
+}
+
+module.exports = {
+    MANIFEST_VERSION,
+    backupRoot,
+    manifestPath,
+    sha256OfFile,
+    snapshotFiles,
+    finalizeManifest,
+    readManifest,
+    consumeManifest,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.6.20",
+  "version": "0.6.30",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -39,12 +39,12 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.6.20",
-    "@memtrace/linux-x64": "0.6.20",
-    "@memtrace/linux-arm64": "0.6.20",
-    "@memtrace/win32-x64": "0.6.20",
-    "@memtrace/linux-x64-noavx2": "0.6.20",
-    "@memtrace/win32-x64-noavx2": "0.6.20"
+    "@memtrace/darwin-arm64": "0.6.30",
+    "@memtrace/linux-x64": "0.6.30",
+    "@memtrace/linux-arm64": "0.6.30",
+    "@memtrace/win32-x64": "0.6.30",
+    "@memtrace/linux-x64-noavx2": "0.6.30",
+    "@memtrace/win32-x64-noavx2": "0.6.30"
   },
   "engines": {
     "node": ">=18"

package/uninstall.js

@@ -4,6 +4,7 @@
 const os = require("os");
 const path = require("path");
 const fs = require("fs");
+const crypto = require("crypto");
 const { execSync, spawnSync } = require("child_process");
 
 // claude-integration may not be present in old installs running this
@@ -53,6 +54,235 @@ const SKILL_NAMES = [
   "memtrace-refactoring-guide",
 ];
 
+// ── Manifest-driven restore (memtrace-public #25) ───────────────────────────
+//
+// `memtrace install` writes ~/.memtrace/install-backup/manifest.json with a
+// pre-install backup + pre/post sha256 for every user-global file it mutated.
+// Restore strategy per file:
+//
+//   current sha == postSha256 → untouched since install → byte-exact restore
+//                               of the backup (or delete, if install created
+//                               the file).
+//   current sha != postSha256 → user edited it after install → surgically
+//                               remove ONLY memtrace-owned blocks/keys,
+//                               preserving every user byte.
+//
+// Everything here is deliberately self-contained (constants inlined, no
+// require of lib/claude-integration) because this script is persisted to
+// ~/.memtrace/uninstall.js, where lib/ does not exist. That missing-lib
+// fallback was exactly how pre-#25 uninstalls left the CLAUDE.md breadcrumb
+// and the managed hooks behind.
+
+const MT_BLOCK_BEGIN =
+  "<!-- BEGIN MEMTRACE BLOCK · managed by `memtrace install` · remove with `memtrace uninstall` -->";
+const MT_BLOCK_END = "<!-- END MEMTRACE BLOCK -->";
+const MT_HOOK_MANAGED_TAG = "memtrace";
+const MT_HOOK_SCRIPTS = ["userprompt-claude.sh", "posttool-mcp-telemetry.sh"];
+const MT_RAIL_HOOK_MARKER = "route --hook";
+
+function installManifestPath(home = os.homedir()) {
+  return path.join(home, ".memtrace", "install-backup", "manifest.json");
+}
+
+function readInstallManifest(home = os.homedir()) {
+  try {
+    return JSON.parse(fs.readFileSync(installManifestPath(home), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function consumeInstallManifest(home = os.homedir()) {
+  const p = installManifestPath(home);
+  if (!fs.existsSync(p)) return;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  try {
+    fs.renameSync(p, path.join(path.dirname(p), `manifest.consumed-${stamp}.json`));
+  } catch {
+    try { fs.unlinkSync(p); } catch { /* best-effort */ }
+  }
+}
+
+function sha256OfFile(filePath) {
+  try {
+    return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/** Remove the memtrace breadcrumb block from CLAUDE.md text. Tolerant:
+ *  a dangling BEGIN without END leaves the text unchanged. */
+function stripBreadcrumbText(text) {
+  const beginIdx = text.indexOf(MT_BLOCK_BEGIN);
+  if (beginIdx === -1) return text;
+  const endIdx = text.indexOf(MT_BLOCK_END, beginIdx);
+  if (endIdx === -1) return text;
+  const blockEnd = endIdx + MT_BLOCK_END.length;
+  const tailNewline = text.charAt(blockEnd) === "\n" ? 1 : 0;
+  return text.slice(0, beginIdx) + text.slice(blockEnd + tailNewline);
+}
+
+/** True when an inner hook object is memtrace-owned (managed tag, our hook
+ *  scripts, or the Rail `route --hook` command). */
+function isMemtraceHook(h) {
+  if (!isRecord(h)) return false;
+  if (h._managed_by === MT_HOOK_MANAGED_TAG) return true;
+  if (typeof h.command === "string") {
+    if (h.command.includes(MT_RAIL_HOOK_MARKER)) return true;
+    for (const script of MT_HOOK_SCRIPTS) {
+      if (h.command.endsWith(script)) return true;
+    }
+  }
+  return false;
+}
+
+/** Strip every memtrace-owned hook entry (managed UserPromptSubmit /
+ *  PostToolUse + Rail PreToolUse) from a parsed settings object. */
+function stripManagedHooksFromSettings(settings) {
+  const out = JSON.parse(JSON.stringify(settings || {}));
+  if (!isRecord(out.hooks)) return out;
+  for (const eventName of Object.keys(out.hooks)) {
+    const blocks = out.hooks[eventName];
+    if (!Array.isArray(blocks)) continue;
+    const cleaned = [];
+    for (const block of blocks) {
+      if (!isRecord(block) || !Array.isArray(block.hooks)) {
+        cleaned.push(block);
+        continue;
+      }
+      const remaining = block.hooks.filter((h) => !isMemtraceHook(h));
+      if (remaining.length === 0) continue; // block was entirely ours
+      cleaned.push({ ...block, hooks: remaining });
+    }
+    if (cleaned.length === 0) delete out.hooks[eventName];
+    else out.hooks[eventName] = cleaned;
+  }
+  if (isRecord(out.hooks) && Object.keys(out.hooks).length === 0) delete out.hooks;
+  return out;
+}
+
+/** Surgically remove memtrace-owned content from one manifest-tracked file.
+ *  Used when the file changed after install (hand-edited). */
+function surgicalCleanFile(entry) {
+  const file = entry.path;
+  if (!fs.existsSync(file)) return false;
+  const kind = entry.owned && entry.owned.kind;
+
+  if (kind === "file") {
+    // Wholly memtrace-owned (MEMTRACE.md) — always safe to delete.
+    fs.unlinkSync(file);
+    return true;
+  }
+
+  if (kind === "block") {
+    const existing = fs.readFileSync(file, "utf8");
+    const updated = stripBreadcrumbText(existing);
+    if (updated === existing) return false;
+    if (updated === "") fs.unlinkSync(file);
+    else fs.writeFileSync(file, updated);
+    return true;
+  }
+
+  if (kind === "json-keys") {
+    let settings;
+    try {
+      settings = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+      console.warn(`memtrace: ${file} is not valid JSON; leaving it untouched.`);
+      return false;
+    }
+    let out = stripManagedHooksFromSettings(settings);
+    if (isRecord(out.mcpServers) && out.mcpServers[MCP_SERVER_NAME]) {
+      delete out.mcpServers[MCP_SERVER_NAME];
+      if (Object.keys(out.mcpServers).length === 0) delete out.mcpServers;
+    }
+    if (isRecord(out.enabledPlugins)) {
+      for (const key of Object.keys(out.enabledPlugins)) {
+        if (key === PLUGIN_KEY || (key.startsWith(`${PLUGIN_NAME}@`) && key.includes("memtrace"))) {
+          delete out.enabledPlugins[key];
+        }
+      }
+      if (Object.keys(out.enabledPlugins).length === 0) delete out.enabledPlugins;
+    }
+    for (const containerName of MARKETPLACE_SETTING_CONTAINERS) {
+      const container = out[containerName];
+      if (!isRecord(container)) continue;
+      for (const key of MARKETPLACE_SETTING_KEYS) {
+        if (Object.prototype.hasOwnProperty.call(container, key)) delete container[key];
+      }
+      if (Object.keys(container).length === 0) delete out[containerName];
+    }
+    const before = JSON.stringify(settings);
+    const after = JSON.stringify(out);
+    if (before === after) return false;
+    if (Object.keys(out).length === 0) fs.unlinkSync(file);
+    else fs.writeFileSync(file, JSON.stringify(out, null, 2) + "\n");
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Restore user-global files from the install manifest. Returns a summary
+ * object, or null when no manifest exists (pre-#25 install — callers fall
+ * back to legacy surgical cleanup). Idempotent: the manifest is renamed
+ * aside after a successful pass.
+ */
+function restoreFromManifest(home = os.homedir()) {
+  const manifest = readInstallManifest(home);
+  if (!manifest || !Array.isArray(manifest.entries)) return null;
+
+  const summary = { restored: [], surgical: [], skipped: [] };
+  for (const entry of manifest.entries) {
+    try {
+      const currentSha = sha256OfFile(entry.path);
+      if (currentSha === null && entry.postSha256 === null) {
+        summary.skipped.push(`${entry.path} (never existed)`);
+        continue;
+      }
+      if (currentSha !== null && currentSha === entry.postSha256) {
+        // Untouched since install — byte-exact restore of pre-install state.
+        if (entry.existedBefore && entry.backupPath && fs.existsSync(entry.backupPath)) {
+          fs.copyFileSync(entry.backupPath, entry.path);
+          summary.restored.push(`${entry.path} (restored pre-install backup)`);
+        } else if (!entry.existedBefore) {
+          fs.unlinkSync(entry.path);
+          summary.restored.push(`${entry.path} (removed — created by install)`);
+        } else {
+          // Backup missing: fall back to surgical removal.
+          if (surgicalCleanFile(entry)) summary.surgical.push(entry.path);
+          else summary.skipped.push(`${entry.path} (backup missing, nothing to remove)`);
+        }
+      } else if (currentSha === null) {
+        summary.skipped.push(`${entry.path} (already removed)`);
+      } else {
+        // Hand-edited after install — remove ONLY memtrace-owned content.
+        if (surgicalCleanFile(entry)) {
+          summary.surgical.push(`${entry.path} (memtrace blocks removed, user edits preserved)`);
+        } else {
+          summary.skipped.push(`${entry.path} (no memtrace content found)`);
+        }
+      }
+    } catch (e) {
+      console.warn(`memtrace: manifest restore failed for ${entry.path}: ${e.message}`);
+    }
+  }
+
+  // Paths install created wholesale (plugin cache etc.) are safe to delete.
+  for (const p of manifest.createdPaths || []) {
+    try {
+      if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true });
+    } catch (e) {
+      console.warn(`memtrace: failed to remove ${p}: ${e.message}`);
+    }
+  }
+
+  consumeInstallManifest(home);
+  return summary;
+}
+
 // ── Remove skills ───────────────────────────────────────────────────────────
 //
 // Each cleanup helper takes an optional `home` parameter so we can
@@ -271,14 +501,53 @@ function tryClaudeCliUninstall() {
 
 function removeClaudeIntegration(home = os.homedir()) {
   const ci = loadClaudeIntegration();
-  if (!ci) return;
+  if (ci) {
+    try {
+      const summary = ci.uninstallFromFs({ claudeDir: path.join(home, ".claude") });
+      if (summary.removed.length > 0) {
+        console.log(`memtrace: cleaned Claude Code integration (${summary.removed.length} item(s))`);
+      }
+      return;
+    } catch (e) {
+      console.warn(`memtrace: Claude Code integration cleanup failed: ${e.message}`);
+      // fall through to the inline cleanup below
+    }
+  }
+
+  // Inline fallback (memtrace-public #25): when this script runs from its
+  // persisted copy at ~/.memtrace/uninstall.js, lib/claude-integration is
+  // not on disk. The old behavior silently no-op'd here, leaving the
+  // CLAUDE.md breadcrumb and the managed settings.json hooks behind.
   try {
-    const summary = ci.uninstallFromFs({ claudeDir: path.join(home, ".claude") });
-    if (summary.removed.length > 0) {
-      console.log(`memtrace: cleaned Claude Code integration (${summary.removed.length} item(s))`);
+    const claudeDir = path.join(home, ".claude");
+
+    const memtraceMd = path.join(claudeDir, "MEMTRACE.md");
+    if (fs.existsSync(memtraceMd)) fs.unlinkSync(memtraceMd);
+
+    const claudeMd = path.join(claudeDir, "CLAUDE.md");
+    if (fs.existsSync(claudeMd)) {
+      const existing = fs.readFileSync(claudeMd, "utf8");
+      const updated = stripBreadcrumbText(existing);
+      if (updated !== existing) {
+        if (updated === "") fs.unlinkSync(claudeMd);
+        else fs.writeFileSync(claudeMd, updated);
+      }
     }
+
+    const settingsFile = settingsPath(home);
+    if (fs.existsSync(settingsFile)) {
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsFile, "utf8"));
+        const updated = stripManagedHooksFromSettings(settings);
+        if (JSON.stringify(updated) !== JSON.stringify(settings)) {
+          if (Object.keys(updated).length === 0) fs.unlinkSync(settingsFile);
+          else fs.writeFileSync(settingsFile, JSON.stringify(updated, null, 2) + "\n");
+        }
+      } catch { /* malformed settings — leave untouched */ }
+    }
+    console.log("memtrace: cleaned Claude Code integration (inline fallback)");
   } catch (e) {
-    console.warn(`memtrace: Claude Code integration cleanup failed: ${e.message}`);
+    console.warn(`memtrace: inline Claude Code cleanup failed: ${e.message}`);
   }
 }
 
@@ -376,6 +645,21 @@ function run() {
   killRunningMemtraceProcesses();
   console.log("memtrace: cleaning up...");
 
+  // Manifest-first restore (memtrace-public #25): put every file the
+  // install mutated back to its pre-install bytes (or surgically strip
+  // memtrace blocks if the user edited it since). The legacy cleanup
+  // below still runs afterwards — it is idempotent and catches state
+  // from older installer versions that wrote no manifest.
+  try {
+    const summary = restoreFromManifest(process.env.MEMTRACE_INSTALL_HOME || os.homedir());
+    if (summary) {
+      const n = summary.restored.length + summary.surgical.length;
+      if (n > 0) console.log(`memtrace: restored ${n} file(s) from the install manifest`);
+    }
+  } catch (e) {
+    console.warn(`memtrace: manifest restore failed: ${e.message}`);
+  }
+
   // Try delegating to the compiled installer (handles ALL agents via registry)
   const bundled = path.join(__dirname, "installer", "dist", "index.js");
   if (fs.existsSync(bundled)) {
@@ -428,6 +712,13 @@ module.exports = {
   killRunningMemtraceProcesses,
   removeClaudeIntegration,
   legacyCleanup,
+  // Manifest restore (memtrace-public #25)
+  installManifestPath,
+  readInstallManifest,
+  restoreFromManifest,
+  stripBreadcrumbText,
+  stripManagedHooksFromSettings,
+  surgicalCleanFile,
 };
 
 // Run when called directly (npm preuninstall hook). When require()'d