@vkmikc/create-vkm-kit 4.2.0

package/src/claude-native-memory.mjs

@@ -0,0 +1,507 @@
+// Make the Obsidian vault Claude Code's ONLY memory: turn OFF the native per-project
+// auto-memory (`autoMemoryEnabled:false`) and install a `SessionStart` hook that injects
+// the vault map + the "vault is the source of truth" reminders.
+//
+// Why: Claude Code ships a native auto-memory (`~/.claude/projects/<enc>/memory/MEMORY.md`)
+// that the harness auto-loads and the base system prompt tells the model to WRITE with the
+// `Write` tool. It competes with the vault and the native side wins by default (it's in the
+// base prompt with `Write` always available, while the `vault_*` MCP tools are often
+// deferred). Disabling it + a reinforced SessionStart reminder makes the vault win out of
+// the box. See ADR-0029.
+//
+// Idempotent: merges `~/.claude/settings.json` without clobbering other keys or hooks, and
+// REPLACES (never duplicates) our managed `SessionStart` entry — re-runs and an older
+// PowerShell variant of the hook are both recognized by the shared filename stem.
+//
+// ADR-0030 adds two more managed hooks (on by default, `enforce` opt-out) so the doctrine
+// holds even when the driving model doesn't reliably honor a prose rule: a `PreToolUse`
+// guard that DENIES Write/Edit/MultiEdit/NotebookEdit into the native auto-memory directory,
+// and a `Stop` nudge that reminds the close ritual once per turn when the session did
+// substantive file work but never touched the vault.
+//
+// ADR-0031 adds a third, independently-toggleable managed hook (on by default, `effortGate`
+// opt-out): a `PreToolUse` gate that DENIES a session's 2nd+ substantive edit until the model
+// proposed an effort level and got a real reply from the user — same "deterministic beats a
+// prose rule" reasoning, aimed at a different failure mode (the model announcing a pause and
+// not actually taking one).
+//
+// Install/remove is SYMMETRIC (audit finding, 2026-07): every call to
+// `configureClaudeNativeMemory` fully reconciles the desired state — pieces that are wanted
+// get merged in, pieces that are NOT wanted get actively stripped out (not just skipped),
+// so a `--no-effort-gate` re-run after a prior install with the effort gate on actually
+// removes that hook entry instead of leaving it orphaned. `uninstallClaudeNativeMemory`
+// builds on the same removal path plus deletes the hook script files themselves, but only
+// when a marker check proves this kit wrote them (never a user's own same-named file).
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import fse from "fs-extra";
+import pc from "picocolors";
+import {
+  atomicWriteJson,
+  backupRestricted,
+  hasManagedHook,
+  isKitOwnedFile,
+  mergeManagedHook,
+  readSettingsSafe,
+  removeManagedHook,
+  setOrDeleteHooks
+} from "./settings-io.mjs";
+
+/** Shared stem so re-runs (and a legacy `.ps1` install) match our managed entry. */
+export const HOOK_STEM = "session-start-vault-context";
+export const HOOK_BASENAME = `${HOOK_STEM}.mjs`;
+
+/** PreToolUse guard (ADR-0030): denies Write/Edit/MultiEdit/NotebookEdit into the native
+ * auto-memory directory, independent of whether the model honored the CLAUDE.md rule. */
+export const GUARD_HOOK_STEM = "guard-native-memory-write";
+export const GUARD_HOOK_BASENAME = `${GUARD_HOOK_STEM}.mjs`;
+
+/** Stop nudge (ADR-0030): reminds the close ritual once per turn when the session did
+ * substantive file work but never touched the vault. */
+export const STOP_HOOK_STEM = "stop-vault-close-reminder";
+export const STOP_HOOK_BASENAME = `${STOP_HOOK_STEM}.mjs`;
+
+/** Effort gate (ADR-0031): denies a session's 2nd+ substantive edit until the model
+ * proposed an effort level and got a real reply from the user. Independently toggleable
+ * from the `enforce` pair above — a user may want one without the other. */
+export const EFFORT_GATE_HOOK_STEM = "guard-effort-gate";
+export const EFFORT_GATE_HOOK_BASENAME = `${EFFORT_GATE_HOOK_STEM}.mjs`;
+
+/** Shared sidecar-cache engine (item 3 / perf fix) the Stop nudge and effort-gate hooks both
+ * import as a sibling module — not a hook Claude Code invokes itself, but installed and
+ * removed alongside whichever of the two needs it (see `configureClaudeNativeMemory`). */
+export const TRANSCRIPT_CACHE_BASENAME = "_transcript-cache.mjs";
+
+/** All filename stems this kit manages in `~/.claude/settings.json` hooks. Used both to
+ * detect "is there anything of ours to remove" and by `--uninstall`'s file-marker check. */
+const ALL_HOOK_STEMS = [HOOK_STEM, GUARD_HOOK_STEM, STOP_HOOK_STEM, EFFORT_GATE_HOOK_STEM];
+
+/** Source hook shipped inside the published package (`src/hooks/`). */
+function packagedHookPath(basename = HOOK_BASENAME) {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), "hooks", basename);
+}
+
+/**
+ * The `SessionStart` hook entry: exec form (`command` + `args`, no shell involved), so a
+ * vault path containing a quote, a backtick, or a trailing backslash is passed through as
+ * one literal argv element — nothing to escape, nothing to get wrong. (Prior versions built
+ * a single interpolated command STRING here — `node "<hook>" "<vault>" <lang>` — which broke
+ * on exactly those inputs, e.g. a trailing backslash before the closing quote swallowed it.
+ * Claude Code's hook schema supports this exec form for any `command` that resolves to a
+ * real executable, which `node` always does, cross-platform.)
+ * @param {string} hookPath
+ * @param {string} vaultAbs
+ * @param {string} [lang]
+ * @returns {{ command: string, args: string[] }}
+ */
+export function hookCommand(hookPath, vaultAbs, lang = "es") {
+  return { command: "node", args: [hookPath, vaultAbs, lang === "en" ? "en" : "es"] };
+}
+
+/** The `PreToolUse` guard hook entry: `node "<hook>" "<claudeDir>" <lang>` (exec form). */
+export function guardHookCommand(hookPath, claudeDir, lang = "es") {
+  return { command: "node", args: [hookPath, claudeDir, lang === "en" ? "en" : "es"] };
+}
+
+/** The `Stop` nudge hook entry (exec form; no path arg — it reads the transcript path
+ * Claude Code passes on stdin). */
+export function stopHookCommand(hookPath, lang = "es") {
+  return { command: "node", args: [hookPath, lang === "en" ? "en" : "es"] };
+}
+
+/** The effort-gate hook entry (exec form; same shape as the Stop nudge — it also reads
+ * `transcript_path` from stdin, not argv). */
+export function effortGateHookCommand(hookPath, lang = "es") {
+  return { command: "node", args: [hookPath, lang === "en" ? "en" : "es"] };
+}
+
+// The shared merge/remove/read/write primitives (hookEntryMatchesStem, mergeManagedHook,
+// removeManagedHook, setOrDeleteHooks, hasManagedHook, readSettingsSafe, backupRestricted,
+// atomicWriteJson, isKitOwnedFile, KIT_FILE_MARKER) live in `settings-io.mjs` — extracted
+// there (Phase 0 groundwork) so other installer modules reuse the same idiom.
+
+/**
+ * Pure merge: return a NEW settings object with the native auto-memory disabled and our
+ * managed `SessionStart` hook present exactly once. Preserves every other key, every other
+ * hook event, and every unrelated `SessionStart` entry.
+ * @param {unknown} existing - parsed `settings.json` (or anything; non-objects are ignored)
+ * @param {{ command: string, args: string[] }} hookEntry - from {@link hookCommand}
+ * @returns {Record<string, unknown>}
+ */
+export function mergeClaudeSettings(existing, hookEntry) {
+  const settings =
+    existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  // The whole point of the override: force it off (documented key; default is true).
+  settings.autoMemoryEnabled = false;
+
+  const hooks =
+    settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
+      ? settings.hooks
+      : {};
+  settings.hooks = mergeManagedHook(hooks, "SessionStart", "*", hookEntry, HOOK_STEM);
+  return settings;
+}
+
+/**
+ * The removal counterpart to {@link mergeClaudeSettings}: drop the managed `SessionStart`
+ * entry, and drop the `autoMemoryEnabled` override too — but ONLY when it's still exactly
+ * `false`, i.e. the value this kit itself would have set. If the user (or something else)
+ * has since set it to `true`, that's left alone rather than silently re-toggled; we only
+ * ever reverse a value we can prove is ours.
+ * @param {unknown} existing
+ * @returns {Record<string, unknown>}
+ */
+export function removeSessionStartHook(existing) {
+  const settings =
+    existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  if (settings.autoMemoryEnabled === false) {
+    delete settings.autoMemoryEnabled;
+  }
+  const hadHooks =
+    settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks);
+  const hooks = hadHooks ? settings.hooks : {};
+  return setOrDeleteHooks(
+    settings,
+    Boolean(hadHooks),
+    removeManagedHook(hooks, "SessionStart", HOOK_STEM)
+  );
+}
+
+/**
+ * Pure merge (ADR-0030): add the deterministic enforcement hooks — a `PreToolUse` guard
+ * that denies writes into the native auto-memory directory, and a `Stop` nudge that
+ * reminds the close ritual once per turn. Either command may be omitted to install just
+ * one. Idempotent and dedup'd the same way as {@link mergeClaudeSettings}.
+ * @param {unknown} existing - parsed `settings.json` (or anything; non-objects are ignored)
+ * @param {{ guardCommand?: {command:string,args:string[]}|null, stopCommand?: {command:string,args:string[]}|null }} commands
+ * @returns {Record<string, unknown>}
+ */
+export function mergeEnforcementHooks(existing, { guardCommand, stopCommand } = {}) {
+  const settings =
+    existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  let hooks =
+    settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
+      ? settings.hooks
+      : {};
+  if (guardCommand) {
+    hooks = mergeManagedHook(
+      hooks,
+      "PreToolUse",
+      "Write|Edit|MultiEdit|NotebookEdit",
+      guardCommand,
+      GUARD_HOOK_STEM
+    );
+  }
+  if (stopCommand) {
+    hooks = mergeManagedHook(hooks, "Stop", "*", stopCommand, STOP_HOOK_STEM);
+  }
+  settings.hooks = hooks;
+  return settings;
+}
+
+/**
+ * The removal counterpart to {@link mergeEnforcementHooks}: strip both the guard and stop
+ * entries unconditionally (a no-op for whichever, or both, aren't present).
+ * @param {unknown} existing
+ * @returns {Record<string, unknown>}
+ */
+export function removeEnforcementHooks(existing) {
+  const settings =
+    existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  const hadHooks =
+    settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks);
+  let hooks = hadHooks ? settings.hooks : {};
+  hooks = removeManagedHook(hooks, "PreToolUse", GUARD_HOOK_STEM);
+  hooks = removeManagedHook(hooks, "Stop", STOP_HOOK_STEM);
+  return setOrDeleteHooks(settings, Boolean(hadHooks), hooks);
+}
+
+/**
+ * Pure merge (ADR-0031): add the effort-gate `PreToolUse` hook. Kept as its OWN function
+ * (not folded into {@link mergeEnforcementHooks}) so it's independently toggleable — same
+ * reasoning ADR-0030 already used to keep the native-memory override separate from its own
+ * hooks. Registers under the same matcher as the native-memory guard; the two coexist as
+ * separate `hooks.PreToolUse` entries (deduped by stem, not by matcher) and either may deny
+ * independently. Idempotent and dedup'd the same way as {@link mergeClaudeSettings}.
+ * @param {unknown} existing - parsed `settings.json` (or anything; non-objects are ignored)
+ * @param {{ effortGateCommand?: {command:string,args:string[]}|null }} commands
+ * @returns {Record<string, unknown>}
+ */
+export function mergeEffortGateHook(existing, { effortGateCommand } = {}) {
+  const settings =
+    existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  let hooks =
+    settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
+      ? settings.hooks
+      : {};
+  if (effortGateCommand) {
+    hooks = mergeManagedHook(
+      hooks,
+      "PreToolUse",
+      "Write|Edit|MultiEdit|NotebookEdit",
+      effortGateCommand,
+      EFFORT_GATE_HOOK_STEM
+    );
+  }
+  settings.hooks = hooks;
+  return settings;
+}
+
+/**
+ * The removal counterpart to {@link mergeEffortGateHook}: strip the effort-gate entry (a
+ * no-op if it isn't present).
+ * @param {unknown} existing
+ * @returns {Record<string, unknown>}
+ */
+export function removeEffortGateHook(existing) {
+  const settings =
+    existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  const hadHooks =
+    settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks);
+  const hooks = hadHooks ? settings.hooks : {};
+  return setOrDeleteHooks(
+    settings,
+    Boolean(hadHooks),
+    removeManagedHook(hooks, "PreToolUse", EFFORT_GATE_HOOK_STEM)
+  );
+}
+
+/**
+ * Install (or, when a piece isn't wanted, actively REMOVE) the Claude Code native-memory
+ * override: copy the hook(s) into `~/.claude/hooks/`, then reconcile `autoMemoryEnabled` +
+ * the hook registrations in `~/.claude/settings.json` to match exactly what's wanted.
+ *
+ * Symmetric by design: every call fully reconciles state, in both directions. `enable:false`
+ * doesn't just skip installing the SessionStart hook — if it was installed by a PRIOR call
+ * (e.g. a previous run without `--no-native-memory-override`), this strips it out, same for
+ * `enforce:false` / `effortGate:false` against their own pieces. That's what makes `--no-X`
+ * flags actually reverse a prior `--X` install instead of only affecting fresh ones.
+ *
+ * As a side effect of being symmetric, a call that wants nothing installed AND finds nothing
+ * of ours already present is a true no-op — it never touches `~/.claude/settings.json` at
+ * all (not even to create it), so running with Claude Code off/unwanted never surprises a
+ * machine that never had this override.
+ *
+ * Best-effort and non-fatal; never throws out (a failure here must not abort the install).
+ * @param {string} home
+ * @param {string} vaultAbs
+ * @param {boolean} dryRun
+ * @param {{ lang?: "es"|"en", enable?: boolean, enforce?: boolean, effortGate?: boolean }} [opts] -
+ *   `enable` (default true) is the top-level on/off for the whole override (SessionStart
+ *   hook + `autoMemoryEnabled:false`); `enforce` (default true, only meaningful when
+ *   `enable`) also installs the ADR-0030 deterministic hooks: a `PreToolUse` guard that
+ *   denies writes into the native auto-memory directory, and a `Stop` nudge for the close
+ *   ritual. `effortGate` (default true, only meaningful when `enable`) installs the
+ *   ADR-0031 effort-gate hook, independently of `enforce`.
+ */
+export async function configureClaudeNativeMemory(
+  home,
+  vaultAbs,
+  dryRun,
+  { lang = "es", enable = true, enforce = true, effortGate = true } = {}
+) {
+  const claudeDir = path.join(home, ".claude");
+  const hooksDir = path.join(claudeDir, "hooks");
+  const hookDest = path.join(hooksDir, HOOK_BASENAME);
+  const guardDest = path.join(hooksDir, GUARD_HOOK_BASENAME);
+  const stopDest = path.join(hooksDir, STOP_HOOK_BASENAME);
+  const effortGateDest = path.join(hooksDir, EFFORT_GATE_HOOK_BASENAME);
+  const transcriptCacheDest = path.join(hooksDir, TRANSCRIPT_CACHE_BASENAME);
+  const settingsFp = path.join(claudeDir, "settings.json");
+
+  const wantEnforce = enable && enforce;
+  const wantEffortGate = enable && effortGate;
+
+  const hookEntry = enable ? hookCommand(hookDest, vaultAbs, lang) : null;
+  const guardCommand = wantEnforce ? guardHookCommand(guardDest, claudeDir, lang) : null;
+  const stopCommand = wantEnforce ? stopHookCommand(stopDest, lang) : null;
+  const effortGateCommand = wantEffortGate ? effortGateHookCommand(effortGateDest, lang) : null;
+
+  try {
+    // Read existing settings up front — needed to reconcile installs AND removals, and to
+    // cheaply detect (via our filename stems, on the raw text) whether there's anything of
+    // ours to remove at all, without depending on the JSON being valid.
+    let { existing, priorBytes, invalidJson, rawText } = await readSettingsSafe(settingsFp);
+    const oursPresent = ALL_HOOK_STEMS.some((stem) => rawText.includes(stem));
+
+    // True no-op: nothing wanted, nothing of ours present — leave the file (even a
+    // nonexistent one) completely untouched. Prevents a bare `--ide claude
+    // --no-native-memory-override` from conjuring a settings.json out of thin air.
+    if (!enable && !oursPresent) {
+      return;
+    }
+
+    if (dryRun) {
+      if (enable) {
+        console.log(
+          pc.cyan("[dry-run] would set"),
+          "autoMemoryEnabled:false",
+          pc.dim(`in ${settingsFp}`)
+        );
+        console.log(pc.cyan("[dry-run] would install SessionStart hook"), pc.dim(hookDest));
+      } else if (
+        hasManagedHook(existing.hooks, "SessionStart", HOOK_STEM) ||
+        existing.autoMemoryEnabled === false
+      ) {
+        console.log(
+          pc.cyan("[dry-run] would remove autoMemoryEnabled override + SessionStart hook"),
+          pc.dim(`from ${settingsFp}`)
+        );
+      }
+      if (wantEnforce) {
+        console.log(
+          pc.cyan("[dry-run] would install PreToolUse native-memory guard hook"),
+          pc.dim(guardDest)
+        );
+        console.log(
+          pc.cyan("[dry-run] would install Stop close-ritual reminder hook"),
+          pc.dim(stopDest)
+        );
+      } else if (
+        hasManagedHook(existing.hooks, "PreToolUse", GUARD_HOOK_STEM) ||
+        hasManagedHook(existing.hooks, "Stop", STOP_HOOK_STEM)
+      ) {
+        console.log(
+          pc.cyan(
+            "[dry-run] would remove PreToolUse native-memory guard + Stop close-ritual reminder hooks"
+          )
+        );
+      }
+      if (wantEffortGate) {
+        console.log(
+          pc.cyan("[dry-run] would install PreToolUse effort-gate hook"),
+          pc.dim(effortGateDest)
+        );
+      } else if (hasManagedHook(existing.hooks, "PreToolUse", EFFORT_GATE_HOOK_STEM)) {
+        console.log(pc.cyan("[dry-run] would remove PreToolUse effort-gate hook"));
+      }
+      return;
+    }
+
+    // 1. Copy (only the pieces being installed) / never delete script files here — that's
+    // `--uninstall`'s job, guarded by a marker check. A per-run `--no-X` only touches the
+    // settings.json registration; an orphaned-but-uncalled script file is harmless.
+    await fse.ensureDir(hooksDir);
+    if (enable) {
+      await fse.copy(packagedHookPath(), hookDest, { overwrite: true });
+    }
+    if (wantEnforce) {
+      await fse.copy(packagedHookPath(GUARD_HOOK_BASENAME), guardDest, { overwrite: true });
+      await fse.copy(packagedHookPath(STOP_HOOK_BASENAME), stopDest, { overwrite: true });
+    }
+    if (wantEffortGate) {
+      await fse.copy(packagedHookPath(EFFORT_GATE_HOOK_BASENAME), effortGateDest, {
+        overwrite: true
+      });
+    }
+    if (wantEnforce || wantEffortGate) {
+      // The Stop nudge and the effort-gate hook both import this sidecar-cache module as a
+      // sibling file (item 3 perf fix) — copy it whenever either consumer is installed.
+      await fse.copy(packagedHookPath(TRANSCRIPT_CACHE_BASENAME), transcriptCacheDest, {
+        overwrite: true
+      });
+    }
+
+    if (invalidJson) {
+      const bak = await backupRestricted(settingsFp, priorBytes);
+      console.warn(pc.yellow("Invalid JSON in ~/.claude/settings.json; backed up to"), bak);
+      existing = {};
+    }
+
+    // 2. Reconcile: merge what's wanted, remove what's not — same code path handles a
+    // fresh install, a no-op re-run, and a partial/full removal.
+    let merged = enable
+      ? mergeClaudeSettings(existing, hookEntry)
+      : removeSessionStartHook(existing);
+    merged = wantEnforce
+      ? mergeEnforcementHooks(merged, { guardCommand, stopCommand })
+      : removeEnforcementHooks(merged);
+    merged = wantEffortGate
+      ? mergeEffortGateHook(merged, { effortGateCommand })
+      : removeEffortGateHook(merged);
+    // Keep a one-`mv`-away backup of the prior valid settings, like mcp.json does. Restricted
+    // to the current user, same as the final file below — settings.json can carry secrets in
+    // keys this kit doesn't own (e.g. a user's own `env` block), on either platform.
+    if (priorBytes && !invalidJson) {
+      const bak = await backupRestricted(settingsFp, priorBytes);
+      console.log(pc.dim("Backed up previous settings.json to"), bak);
+    }
+
+    // Serializes + sanity-parses + writes atomically (tmp → restrict → rename).
+    await atomicWriteJson(settingsFp, merged);
+
+    if (enable) {
+      console.log(pc.green("Claude Code native-memory override:"), settingsFp);
+      console.log(pc.dim("  autoMemoryEnabled:false + SessionStart hook ->"), pc.dim(hookDest));
+    } else if (oursPresent) {
+      console.log(pc.green("Claude Code native-memory override removed:"), settingsFp);
+    }
+    if (wantEnforce) {
+      console.log(pc.dim("  + PreToolUse native-memory guard ->"), pc.dim(guardDest));
+      console.log(pc.dim("  + Stop close-ritual reminder ->"), pc.dim(stopDest));
+    } else if (oursPresent && enable) {
+      console.log(pc.dim("  (enforcement hooks removed or not installed)"));
+    }
+    if (wantEffortGate) {
+      console.log(pc.dim("  + PreToolUse effort-gate ->"), pc.dim(effortGateDest));
+    }
+  } catch (e) {
+    console.warn(
+      pc.yellow("Could not configure the Claude Code native-memory override (skipped):"),
+      e?.message || e
+    );
+  }
+}
+
+/**
+ * Fully reverse everything this kit's Claude Code integration installed: all 4 managed
+ * hook entries in `~/.claude/settings.json`, the `autoMemoryEnabled` override (iff it's
+ * still exactly the value this kit would have set — see {@link removeSessionStartHook}),
+ * and — only for files a marker check proves this kit wrote — the hook script files
+ * themselves under `~/.claude/hooks/`. Never touches MCP server registrations, the vault,
+ * or rules blocks; those have their own manual/CLI removal paths (see docs/en/faq.md).
+ * Best-effort and non-fatal, matching {@link configureClaudeNativeMemory}.
+ * @param {string} home
+ * @param {boolean} dryRun
+ */
+export async function uninstallClaudeNativeMemory(home, dryRun) {
+  // Reuses the same reconcile path as a `--no-X` removal, just with every piece off.
+  await configureClaudeNativeMemory(home, "", dryRun, {
+    enable: false,
+    enforce: false,
+    effortGate: false
+  });
+
+  const hooksDir = path.join(home, ".claude", "hooks");
+  const basenames = [
+    HOOK_BASENAME,
+    GUARD_HOOK_BASENAME,
+    STOP_HOOK_BASENAME,
+    EFFORT_GATE_HOOK_BASENAME,
+    TRANSCRIPT_CACHE_BASENAME
+  ];
+  for (const basename of basenames) {
+    const fp = path.join(hooksDir, basename);
+    if (!(await fse.pathExists(fp))) continue;
+    const owned = await isKitOwnedFile(fp);
+    if (dryRun) {
+      console.log(
+        owned
+          ? pc.cyan("[dry-run] would remove")
+          : pc.yellow("[dry-run] would SKIP (not recognized as this kit's file)"),
+        pc.dim(fp)
+      );
+      continue;
+    }
+    if (!owned) {
+      console.warn(pc.yellow("Skipped (not recognized as this kit's file):"), fp);
+      continue;
+    }
+    try {
+      await fse.remove(fp);
+      console.log(pc.green("Removed"), pc.dim(fp));
+    } catch (e) {
+      console.warn(pc.yellow("Could not remove"), fp, e?.message || e);
+    }
+  }
+}

package/src/file-perms.mjs

@@ -0,0 +1,53 @@
+// Restrict a just-written config file (and its `.bak.*` copies) to the current user.
+//
+// `mcp.json` / `settings.json` may carry `env` blocks with API tokens (this kit's own
+// writes don't add secrets, but we merge into and preserve whatever else the user already
+// had in the file, which can). POSIX: chmod 0600. Windows has no chmod bits at all — the
+// prior code just skipped the whole step there (`if (process.platform !== "win32")`), which
+// on the platform this repo's own maintainer uses meant the protection never applied, and
+// `.bak.*` copies accumulated with default (often broader) ACLs. This restricts the file to
+// the current user via `icacls`, the Windows analogue of chmod 0600 (ADR-none; audit fix).
+//
+// Best-effort by design, on BOTH platforms: a permissions failure must never abort a write
+// that otherwise succeeded (matches the existing chmod call sites' `catch { /* ignore */ }`
+// precedent) — ACL manipulation in particular can be fragile across Windows configs (domain
+// accounts, non-NTFS volumes, restricted environments), so failures here only warn.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import fs from "node:fs/promises";
+import os from "node:os";
+import pc from "picocolors";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Best-effort: restrict `fp` to the current user only (POSIX: chmod 0600; Windows: icacls
+ * ACL reset). Never throws — callers should NOT await-fail their write on this.
+ * @param {string} fp
+ */
+export async function restrictFileToOwner(fp) {
+  if (process.platform === "win32") {
+    try {
+      const username = process.env.USERNAME || os.userInfo().username;
+      if (!username) return;
+      // /inheritance:r drops inherited ACEs; /grant:r replaces the explicit grant list with
+      // just the current user (Full control) — together, the closest Windows analogue of
+      // POSIX chmod 0600. Passed as an argv array (no shell), so no quoting to get wrong.
+      await execFileAsync("icacls", [fp, "/inheritance:r", "/grant:r", `${username}:F`], {
+        windowsHide: true
+      });
+    } catch (e) {
+      console.warn(
+        pc.yellow("Could not restrict file permissions (icacls, best-effort):"),
+        fp,
+        e?.message || e
+      );
+    }
+    return;
+  }
+  try {
+    await fs.chmod(fp, 0o600);
+  } catch {
+    /* best-effort: not all filesystems support chmod */
+  }
+}