@sdsrs/code-graph 0.107.0 → 0.108.1

package/README.md

@@ -155,11 +155,11 @@ Then reconnect the MCP server in Claude Code with `/mcp`.
 
 By default, every user prompt the plugin deems code-related gets a small context injection from `code-graph` CLI output. If you'd rather rely on MEMORY.md + explicit tool calls, opt into invited-memory mode:
 
-1. Adopt the plugin contract into your project's memory index (idempotent, self-heals):
+1. Adopt the plugin contract into your project (idempotent, self-heals):
    ```bash
    code-graph-mcp adopt
    ```
-   This writes `plugin_code_graph_mcp.md` (decision rules) into `~/.claude/projects/<slug>/memory/` and links it from `MEMORY.md` inside a sentinel block. Run `code-graph-mcp unadopt` to remove.
+   This writes a sentinel-wrapped managed block into `<cwd>/CLAUDE.md` (auto-loaded each session) plus `<cwd>/.claude/plugin_code_graph_mcp.md` (the full decision table, opened on demand). Run `code-graph-mcp unadopt` to remove both; content outside the managed block is kept.
 2. Set the activation env var in `~/.claude/settings.json`:
    ```json
    {

package/bin/cli.js

@@ -8,9 +8,26 @@ const path = require("path");
 process.env._FIND_BINARY_ROOT = path.resolve(__dirname, "..");
 
 // Intercept adopt / unadopt before forwarding — they're node-only concerns
-// (write to ~/.claude/projects/<slug>/memory/) and have no Rust counterpart.
+// (write <cwd>/CLAUDE.md + <cwd>/.claude/) and have no Rust counterpart.
 // Lets `code-graph-mcp adopt` / `unadopt` work uniformly across plugin / npm / npx.
 const sub = process.argv[2];
+
+// Reject unknown flags on the intercepted subcommands BEFORE doing their work.
+// `--help` was already guarded, but every OTHER token was ignored, so
+// `code-graph-mcp adopt --helpp` ran adopt and wrote the user's CLAUDE.md — a
+// typo away from the very side effect the --help guard exists to prevent. This
+// is the fourth entry point onto the same "ignore what you don't recognise"
+// idiom (doctor.js, lifecycle.js doctor, src/main.rs were the first three); it
+// is the npm/npx surface, so it is the one most users reach.
+function rejectUnknownFlags(name, known) {
+  const unknown = process.argv.slice(3).filter((a) => !known.has(a));
+  if (unknown.length) {
+    process.stderr.write(
+      `code-graph-mcp ${name}: unknown argument(s): ${unknown.join(" ")}\n` +
+      `Run \`code-graph-mcp ${name} --help\` for usage.\n`);
+    process.exit(2);
+  }
+}
 if (sub === "adopt" || sub === "unadopt") {
   // `--help`/`-h` must be side-effect-free: adopt() writes the memory file +
   // MEMORY.md sentinel, unadopt() removes them. The Rust binary guards this for
@@ -19,17 +36,23 @@ if (sub === "adopt" || sub === "unadopt") {
   // `code-graph-mcp adopt --help` rewrites MEMORY.md (the common new-user path).
   if (process.argv.slice(3).some((a) => a === "--help" || a === "-h")) {
     process.stdout.write(sub === "adopt"
-      ? "code-graph-mcp adopt — install the code-graph memory file + MEMORY.md sentinel\n\n" +
+      // Kept in sync with src/main.rs's adopt/unadopt help. This text described
+      // the pre-v0.74 scheme (a sentinel in the ~/.claude memory dir) for three
+      // releases after the target moved to the project's own CLAUDE.md, so npm
+      // users were told this command edits a file it has not touched since.
+      ? "code-graph-mcp adopt — install the code-graph steering block into the project CLAUDE.md\n\n" +
         "USAGE:\n    code-graph-mcp adopt\n\n" +
-        "Writes plugin_code_graph_mcp.md and a sentinel block into this project's\n" +
-        "~/.claude memory so Claude Code auto-loads the decision table. Run\n" +
-        "`code-graph-mcp unadopt` to remove it.\n"
-      : "code-graph-mcp unadopt — remove the code-graph memory file + sentinel\n\n" +
+        "Writes a sentinel-wrapped managed block into <cwd>/CLAUDE.md plus a\n" +
+        "<cwd>/.claude/plugin_code_graph_mcp.md detail doc, so Claude Code loads the\n" +
+        "decision table each session. Run `code-graph-mcp unadopt` to remove it.\n"
+      : "code-graph-mcp unadopt — remove the code-graph steering block\n\n" +
         "USAGE:\n    code-graph-mcp unadopt\n\n" +
-        "Reverses `code-graph-mcp adopt`: deletes the memory file and the MEMORY.md\n" +
-        "sentinel block. User content outside the sentinel is kept.\n");
+        "Reverses `code-graph-mcp adopt`: strips the managed block from\n" +
+        "<cwd>/CLAUDE.md and deletes <cwd>/.claude/plugin_code_graph_mcp.md.\n" +
+        "User content outside the sentinel is kept.\n");
     process.exit(0);
   }
+  rejectUnknownFlags(sub, new Set(["--help", "-h"]));
   const { adopt, unadopt, formatResult } = require("../claude-plugin/scripts/adopt");
   const result = sub === "unadopt" ? unadopt() : adopt();
   process.stdout.write(formatResult(sub, result) + "\n");
@@ -54,6 +77,7 @@ if (sub === "uninstall") {
       "`/plugin uninstall code-graph-mcp` in Claude Code to sync its UI.\n");
     process.exit(0);
   }
+  rejectUnknownFlags("uninstall", new Set(["--help", "-h", "--unadopt-all", "--purge-global"]));
   const lifecycle = require("../claude-plugin/scripts/lifecycle");
   const { unadopt } = require("../claude-plugin/scripts/adopt");
   const r = lifecycle.uninstall({

package/claude-plugin/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.107.0",
+  "version": "0.108.1",
   "keywords": [
     "code-graph",
     "ast",

package/claude-plugin/scripts/adopt.js

@@ -20,7 +20,11 @@ const { PROJECT_MARKERS, isProjectRoot, isNonProjectCwd } = require('./project-d
 const SENTINEL_VERSION = 'v2';
 const SENTINEL_BEGIN = `<!-- code-graph-mcp:begin ${SENTINEL_VERSION} -->`;
 const SENTINEL_END = '<!-- code-graph-mcp:end -->';
-const SENTINEL_BEGIN_SRC = '<!-- code-graph-mcp:begin[^>]*-->';
+// `[^>\n]*`, not `[^>]*`: an HTML comment marker cannot span lines, but the
+// permissive class could — a marker truncated mid-write (`…:begin v2 --`) let
+// the match run across newlines to whatever `-->` came next, swallowing every
+// user line in between before any of the guards in stripSentinelBlock applied.
+const SENTINEL_BEGIN_SRC = '<!-- code-graph-mcp:begin[^>\\n]*-->';
 // Marker on the first line of the installed .claude/plugin_code_graph_mcp.md so
 // unadopt/needsRefresh can distinguish our generated copy from a user's own file
 // of the same name (and so needsRefresh strips it before the bytewise compare).
@@ -32,11 +36,28 @@ const LEGACY_ADOPTED_BY = '<!-- adopted-by:';
 // half-written MEMORY.md / detail file — the dir is shared with claude-mem-lite,
 // which reads MEMORY.md on every keyword match. Mirrors lifecycle.js
 // writeJsonAtomic / auto-update.js binary promote; accepts a string or Buffer.
-function writeFileAtomic(filePath, data) {
-  const tmp = filePath + '.tmp.' + process.pid;
+// `followLink` is opt-in, and ONLY the CLAUDE.md read-modify-write passes it.
+//
+// `rename` REPLACES a symlink with a regular file. For CLAUDE.md that is wrong:
+// we READ through the link, strip the block from what we read, and must write
+// the result back to the same file — otherwise the shared target keeps the block
+// while we report `blockPruned: true`, and the project silently gets a detached
+// private copy.
+//
+// For every other caller it is the opposite. The detail file and the registry
+// are whole-file REPLACEMENTS of content we own; following a link there turns
+// "replace our symlink" into "overwrite whatever the user pointed it at". A
+// first pass applied realpath to all four callers and created exactly that loss
+// path — the fix for one caller became a bug in the others.
+function writeFileAtomic(filePath, data, { followLink = false } = {}) {
+  let target = filePath;
+  if (followLink) {
+    try { target = fs.realpathSync(filePath); } catch { /* new file — no link to follow */ }
+  }
+  const tmp = target + '.tmp.' + process.pid;
   fs.writeFileSync(tmp, data);
   try {
-    fs.renameSync(tmp, filePath);
+    fs.renameSync(tmp, target);
   } catch (e) {
     // rename can fail (ENOSPC / EACCES / EROFS on the dir). Don't orphan the
     // temp in the shared memory dir — mirror auto-update.js's binary promote,
@@ -304,23 +325,54 @@ function escapeRegex(s) {
 
 // Strip our sentinel block — well-formed first, then self-heal orphan begin/end.
 // Shared by adopt (so re-adopt rewrites a stale/malformed block) and unadopt.
+//
+// Every rule below exists because its absence deleted a user's prose. The file
+// this runs against is the user's own CLAUDE.md, `unadopt` runs it over EVERY
+// registered project via `uninstall({unadoptAll:true})`, and the only thing that
+// distinguishes our block from their text is a string they are *invited* to
+// write down — the block itself tells them not to edit inside it. So: never
+// start a match at a marker we cannot prove we wrote, and when in doubt delete
+// less. A stale block left behind is visible and removable; deleted prose is not.
 function stripSentinelBlock(text) {
+  // Line-anchored. A marker mentioned mid-sentence ("the block starts with
+  // `<!-- code-graph-mcp:begin v2 -->` — don't edit inside it") is prose, not a
+  // block opener; matching it ate everything from that sentence to the end of
+  // the real block below it.
+  const BEGIN_LINE = `^[ \\t]*${SENTINEL_BEGIN_SRC}[ \\t]*$`;
+  const END_LINE = `^[ \\t]*${escapeRegex(SENTINEL_END)}[ \\t]*$`;
+
   // Match ANY begin version (v1 legacy MEMORY.md block, v2 CLAUDE.md block) so a
   // single strip handles both the new target and the legacy migration cleanup.
+  //
+  // `(?:(?!BEGIN)[\s\S])*?` — the body may not contain another BEGIN. Without it
+  // a lazy `[\s\S]*?` still ANCHORS at the earliest BEGIN in the file, so a
+  // marker quoted on its own line (a fenced example, a note to a teammate) made
+  // the match start there and run through everything up to our real END.
   const wellFormed = new RegExp(
-    `${SENTINEL_BEGIN_SRC}[\\s\\S]*?${escapeRegex(SENTINEL_END)}\\n?`, 'g'
+    `${BEGIN_LINE}(?:(?!${SENTINEL_BEGIN_SRC})[\\s\\S])*?${END_LINE}\\n?`,
+    'gm'
   );
   let out = text.replace(wellFormed, '');
-  // Orphan BEGIN with no matching END (truncation / partial edit).
-  // Strip from BEGIN to the next blank line or EOF — the file may be shared with
-  // claude-mem-lite (legacy MEMORY.md), so we must not eat past a blank-line boundary.
-  if (new RegExp(SENTINEL_BEGIN_SRC).test(out)) {
-    out = out.replace(
-      new RegExp(`${SENTINEL_BEGIN_SRC}[\\s\\S]*?(?=\\n\\n|$)`, 'g'),
-      ''
-    );
-  }
-  // Orphan END line by itself.
+  // Orphan BEGIN with no matching END (truncation / partial edit): remove the
+  // MARKER LINE ONLY, never the content after it.
+  //
+  // This used to strip from the marker to the next blank line, on the theory
+  // that the content below a stray begin marker was our truncated block. It is
+  // not decidable. These two files are byte-for-byte the same shape:
+  //
+  //   BEGIN / "- stale partial block" / "" / "Also keep me."      <- our leftovers
+  //   BEGIN / "KEEP: on-call rotation" / "" / "tail prose"        <- their notes
+  //
+  // and the second one is what a user writes after reading "the block opens
+  // with <marker>". The blank-line bound protects nothing when their next line
+  // is prose. Since the two cases cannot be told apart, the tie goes to the
+  // outcome that is recoverable: a stale fragment left in the file is visible
+  // and the user can delete it; prose we deleted is gone. `isAdopted` requires a
+  // line-anchored BEGIN *and* END, so a leftover fragment does not block
+  // re-adoption — the next adopt writes a fresh, well-formed block.
+  const orphanBegin = new RegExp(`${BEGIN_LINE}\\n?`, 'gm');
+  out = out.replace(orphanBegin, '');
+  // Orphan END line by itself — same rule, one line, nothing around it.
   if (out.includes(SENTINEL_END)) {
     out = out.split('\n').filter(l => l.trim() !== SENTINEL_END).join('\n');
   }
@@ -422,7 +474,8 @@ function adopt({ cwd, templatePath, home } = {}) {
   const healed = exists && cleaned !== current;
   const base = cleaned.replace(/\n+$/, '');
   const prefix = base ? base + '\n\n' : '';
-  writeFileAtomic(cPath, prefix + block + '\n');
+  // followLink: read-modify-write of a file the user may have symlinked.
+  writeFileAtomic(cPath, prefix + block + '\n', { followLink: true });
   recordAdopted(effectiveCwd, home);
   return { ok: true, detailPath: dPath, claudeMdPath: cPath, detailWritten, claudeMdWritten: true, created: !exists, healed };
 }
@@ -435,7 +488,11 @@ function isAdopted({ cwd } = {}) {
   const dPath = detailPath(effectiveCwd);
   if (!fs.existsSync(dPath) || !fs.existsSync(cPath)) return false;
   const c = fs.readFileSync(cPath, 'utf8');
-  return new RegExp(SENTINEL_BEGIN_SRC).test(c) && c.includes(SENTINEL_END);
+  // Line-anchored for the same reason stripSentinelBlock is: a user quoting the
+  // markers in prose would otherwise read as adopted, and this gates the
+  // idempotent auto-adopt — so the block would never actually be written.
+  return new RegExp(`^[ \\t]*${SENTINEL_BEGIN_SRC}[ \\t]*$`, 'm').test(c)
+    && new RegExp(`^[ \\t]*${escapeRegex(SENTINEL_END)}[ \\t]*$`, 'm').test(c);
 }
 
 // shipped template / 管理块 与已落地版本出现漂移时返回 true。让已 install 的项目
@@ -454,7 +511,11 @@ function needsRefresh({ cwd, templatePath } = {}) {
   const current = fs.readFileSync(dPath);
   let body = current;
   const nl = current.indexOf(0x0a);
-  if (nl > 0 && current.subarray(0, nl).toString().includes('managed-by: code-graph-mcp')) {
+  // Equality on the trimmed line, matching the unadopt guard. `includes` here
+  // was harmless in isolation (worst case: a spurious refresh) but it is the
+  // third spelling of the same predicate in this file, and the other two both
+  // turned out to be wrong — a loose one left behind is the next audit's finding.
+  if (nl > 0 && current.subarray(0, nl).toString().trim() === MANAGED_BY) {
     body = current.subarray(nl + 1);
   }
   if (!shipped.equals(body)) return true;
@@ -495,7 +556,15 @@ function migrateLegacyMemoryDir({ cwd, home } = {}) {
   if (fs.existsSync(legacyDetail)) {
     try {
       const head = fs.readFileSync(legacyDetail, 'utf8').split('\n', 1)[0];
-      if (head.startsWith(LEGACY_ADOPTED_BY)) {
+      // Same guard as unadopt's (:636), and it must be — this is the MORE
+      // frequently executed of the two: maybeAutoAdopt calls migrate on every
+      // SessionStart, while unadopt is explicit. Tightening only unadopt's copy
+      // left the hot path deleting any user file whose first line merely began
+      // with `<!-- adopted-by:` — e.g. a note from someone else's tooling.
+      // The legacy marker carries a payload after the prefix, so it is matched
+      // as a whole-line HTML comment rather than by equality.
+      const h = head.trim();
+      if (h.startsWith(LEGACY_ADOPTED_BY) && h.endsWith('-->')) {
         fs.unlinkSync(legacyDetail);
         result.legacyDetailRemoved = true;
       }
@@ -507,7 +576,7 @@ function migrateLegacyMemoryDir({ cwd, home } = {}) {
       const before = fs.readFileSync(legacyIndex, 'utf8');
       const after = stripSentinelBlock(before);
       if (after !== before) {
-        writeFileAtomic(legacyIndex, after);
+        writeFileAtomic(legacyIndex, after, { followLink: true });
         result.memoryIndexPruned = true;
       }
     } catch { /* unreadable → leave it */ }
@@ -561,7 +630,18 @@ function unadopt({ cwd, home } = {}) {
     let mine = false;
     try {
       const head = fs.readFileSync(dPath, 'utf8').split('\n', 1)[0];
-      mine = head.includes(MANAGED_BY) || head.startsWith(LEGACY_ADOPTED_BY);
+      // `===`, not `includes`. adopt writes the marker as the ENTIRE first line
+      // (`${MANAGED_BY}\n` + template, :403), so equality is exactly as capable
+      // here — while `includes` unlinked any user file whose first line merely
+      // quoted the marker, e.g. a note about what this plugin writes.
+      // BOTH arms anchored. Tightening only the current marker left the legacy
+      // one as a loose startsWith, so a user file opening `<!-- adopted-by: …`
+      // was still unlinked — the same half-applied shape this batch keeps
+      // producing. The legacy marker carries a payload after the prefix, so it
+      // is matched as a whole-line HTML comment rather than by equality.
+      const h = head.trim();
+      mine = h === MANAGED_BY
+        || (h.startsWith(LEGACY_ADOPTED_BY) && h.endsWith('-->'));
     } catch { mine = false; }
     if (mine) { fs.unlinkSync(dPath); fileRemoved = true; }
   }
@@ -573,11 +653,15 @@ function unadopt({ cwd, home } = {}) {
     const after = stripSentinelBlock(before);
     if (after !== before) {
       blockPruned = true;
-      if (after.trim() === '') {
+      // Only delete a file we could have created. A symlinked CLAUDE.md points
+      // at something the user owns (a shared team file, a dotfiles repo);
+      // unlinking it removes their link, and the "file we created" rationale
+      // does not apply. Write the stripped text through the link instead.
+      if (after.trim() === '' && !fs.lstatSync(cPath).isSymbolicLink()) {
         fs.unlinkSync(cPath);
         claudeMdRemoved = true;
       } else {
-        writeFileAtomic(cPath, after);
+        writeFileAtomic(cPath, after, { followLink: true });
       }
     }
   }

package/claude-plugin/scripts/cg-answer.js

@@ -20,7 +20,22 @@
 
 const { spawnSync } = require('child_process');
 
-const DEFAULT_TIMEOUT_MS = 2000;
+// 2000 ms is a product decision, not a tuning knob: a PreToolUse hook that
+// stalls longer than this costs the user more than the answer is worth, so the
+// answer degrades instead.
+//
+// `_CG_ANSWER_TIMEOUT_MS` exists ONLY as a test seam, mirroring the
+// `_CG_ANSWER_BINARY` override already used by the same tests. Without it the
+// hint tests spawn a real `node` process under whatever load the machine
+// happens to be under — a full cargo build saturating every core pushed cold
+// node startup past 2 s and reddened `trackReadAndMaybeHint: fires on 5th read`
+// roughly one run in seven, while 12/12 isolated runs passed. An intermittently
+// red suite teaches people to re-run instead of read, which is the one habit
+// this whole audit is about.
+const DEFAULT_TIMEOUT_MS = (() => {
+  const override = Number(process.env._CG_ANSWER_TIMEOUT_MS);
+  return Number.isFinite(override) && override > 0 ? override : 2000;
+})();
 // ~1000 tokens. A deny reason carrying more than this stops being an answer
 // and starts being a context tax.
 const DEFAULT_MAX_BYTES = 4000;

package/claude-plugin/scripts/doctor.js

@@ -6,7 +6,7 @@ const path = require('path');
 const os = require('os');
 const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-utils');
 const {
-  getPluginVersion, readJson, healthCheck, CACHE_DIR,
+  getPluginVersion, readJson, readJsonResult, healthCheck, scanForBrokenPaths, CACHE_DIR,
   settingsPath, surveyHookCoverage,
   installedGlobalPkgs, GLOBAL_INSTALL_MARKER, SHELL_PKG,
 } = require('./lifecycle');
@@ -57,7 +57,15 @@ function classifyEmbeddings(hc) {
  * Run all diagnostic checks. Returns an array of:
  *   { name: string, status: 'ok'|'warn'|'error'|'skip', detail: string, fixId?: string }
  */
-function runDiagnostics() {
+// `checkOnly` must reach here, not just formatReport. `--check-only` is a
+// SHIPPED read-only contract (CHANGELOG v0.82.1: "it never reaches runRepairs"),
+// but the write was never in runRepairs — `healthCheck()` below calls
+// `install()`, which REBUILDS an unusable settings.json. Reproduced: under
+// `--check-only`, a settings.json holding `{"model":"opus",}` went 36 B -> 3318 B
+// with the model key gone, and the report then said "Run without --check-only to
+// fix." A read-only mode that rewrites the user's config is worse than one that
+// lies about it.
+function runDiagnostics({ checkOnly = false } = {}) {
   const results = [];
   const binary = findBinary();
 
@@ -214,9 +222,28 @@ function runDiagnostics() {
   // returning clean. If repaired:false despite install() running, the
   // re-scan still found broken paths — surfacing 'remaining' makes that
   // honest instead of telling the user we fixed nothing.
-  const hookResult = healthCheck();
+  // In check-only mode, SCAN without the auto-repair half of healthCheck().
+  const hookResult = checkOnly
+    ? (() => {
+        const issues = scanForBrokenPaths();
+        return { healthy: issues.length === 0, issues, repaired: false, rebuiltFrom: null };
+      })()
+    : healthCheck();
   if (hookResult.healthy) {
     results.push({ name: 'Hooks', status: 'ok', detail: 'all paths valid' });
+  } else if (hookResult.repaired && hookResult.rebuiltFrom) {
+    // The repair WORKED, but it worked by replacing an unusable settings.json
+    // with a freshly built one — the user's model / env / permissions / own
+    // hooks now exist only in the backup. Reporting that as `✅ auto-repaired`
+    // (which this did) describes a destructive event as a clean one and never
+    // names the file that holds their config.
+    results.push({
+      name: 'Hooks',
+      status: 'warn',
+      detail:
+        `settings.json was unusable and has been REBUILT — your original is at ` +
+        `${hookResult.rebuiltFrom}. Merge anything you need back by hand.`,
+    });
   } else if (hookResult.repaired) {
     results.push({
       name: 'Hooks',
@@ -224,13 +251,20 @@ function runDiagnostics() {
       detail: `${hookResult.issues.length} issue(s) auto-repaired`,
     });
   } else {
-    const remainingCount = Array.isArray(hookResult.remaining)
-      ? hookResult.remaining.length
-      : hookResult.issues.length;
+    const remaining = Array.isArray(hookResult.remaining)
+      ? hookResult.remaining
+      : hookResult.issues;
+    // An unusable settings.json is not a broken PATH — auto-repair correctly
+    // refuses to touch the file, so "invalid path(s)" would send the user
+    // hunting for a missing script instead of at the file that actually needs
+    // repairing.
+    const unusable = remaining.find((i) => i.type === 'settings-unusable');
     results.push({
       name: 'Hooks',
       status: 'warn',
-      detail: `${remainingCount} invalid path(s) — auto-repair did not resolve`,
+      detail: unusable
+        ? `settings.json unusable (${unusable.reason}) — hooks cannot be verified or repaired`
+        : `${remaining.length} invalid path(s) — auto-repair did not resolve`,
       fixId: 'hooks-invalid',
     });
   }
@@ -241,9 +275,24 @@ function runDiagnostics() {
   //    registering them in settings.json. "Missing" is the bug (previously
   //    "present" was treated as legacy debris — that was wrong).
   try {
-    const settings = readJson(settingsPath()) || {};
+    // Sibling of the `scanForBrokenPaths` read above, and it was left on the old
+    // collapsed-`null` idiom: an unusable settings.json became `{}`, which has no
+    // hooks, so this reported "missing 6/6 settings.json entries" — a confident,
+    // wrong diagnosis sitting in the SAME table as the correct "settings.json
+    // unusable" line two rows up.
+    const settingsRead = readJsonResult(settingsPath());
+    const settings = settingsRead.value || {};
     const cov = surveyHookCoverage(settings);
-    if (cov.missing.length === 0 && cov.stale.length === 0) {
+    if (settingsRead.corrupt) {
+      // No `fixId`: the repair is `install()`, which is already driven by the
+      // `Hooks` row above. Raising `missing-hooks-in-settings` here too would
+      // make doctor attempt the same repair twice and count the issue twice.
+      results.push({
+        name: 'Hook coverage',
+        status: 'warn',
+        detail: 'not determinable — settings.json could not be read or parsed',
+      });
+    } else if (cov.missing.length === 0 && cov.stale.length === 0) {
       results.push({
         name: 'Hook coverage',
         status: 'ok',
@@ -266,7 +315,17 @@ function runDiagnostics() {
         fixId: 'missing-hooks-in-settings',
       });
     }
-  } catch { /* probe failed — skip */ }
+  } catch (err) {
+    // Do NOT swallow silently: this catch hid a plain ReferenceError (a helper
+    // that was not imported) by simply dropping the whole Hook-coverage row, so
+    // the table looked complete while a check had not run at all. A probe that
+    // cannot run is itself a finding.
+    results.push({
+      name: 'Hook coverage',
+      status: 'warn',
+      detail: `probe failed: ${err && err.message ? err.message : err}`,
+    });
+  }
 
   // 8. Hook firing (v0.67.0) — coverage (#7) proves the hook is WIRED into
   //    settings.json; this proves the script actually RUNS. Spawns each
@@ -554,7 +613,7 @@ function runRepairs(results) {
         console.log('\n  Repairing hooks...');
         if (relicRepairGuard()) break;
         const { install, scanForBrokenPaths } = require('./lifecycle');
-        install();
+        const installResult = install();
         // Diagnosis already ran install()+re-scan and the paths were STILL
         // broken (that `repaired:false` is what raised hooks-invalid). Verify
         // this second attempt actually cleared them before counting it fixed \u2014
@@ -564,6 +623,24 @@ function runRepairs(results) {
         if (remaining.length === 0) {
           console.log('  \u2705 Hooks repaired \u2014 restart Claude Code to apply');
           fixed++;
+        } else if (installResult && installResult.settingsUnwritable) {
+          // `scanForBrokenPaths` cannot surface this one: the file READS fine, so
+          // it reports no `settings-unusable` issue and the branch below is
+          // skipped. Without this arm a chmod on ~/.claude was diagnosed as
+          // "plugin scripts may be missing — reinstall the npm package". The
+          // sibling arm at `missing-hooks-in-settings` learned the unwritable
+          // case in the previous round and this one did not; the two arms print
+          // about the same install() call and have to agree about why it failed.
+          console.log('  ❌ settings.json is not writable — hooks NOT repaired');
+          console.log('     Fix the permissions on it (or on ~/.claude) and re-run; see the error above.');
+        } else if (remaining.some((i) => i.type === 'settings-unusable')) {
+          // Same branch runDiagnostics needs, for the same reason. This arm only
+          // became REACHABLE for unusable settings once scanForBrokenPaths began
+          // reporting them, so it inherited a diagnosis written for a different
+          // cause \u2014 telling the user to reinstall an npm package because their
+          // settings.json has a permissions problem or a trailing comma.
+          console.log('  \u274c settings.json could not be read or parsed \u2014 hooks cannot be verified or repaired');
+          console.log('     Repair it (or move it aside) and re-run; see the error above.');
         } else {
           console.log(`  \u274c ${remaining.length} hook path(s) still invalid \u2014 plugin scripts may be missing.`);
           console.log('     Reinstall: npm install -g @sdsrs/code-graph  (or re-run the plugin installer)');
@@ -579,6 +656,21 @@ function runRepairs(results) {
         if (r.hooksRegistered) {
           console.log('  \u2705 settings.json updated — restart Claude Code to apply');
           fixed++;
+        } else if (r.settingsUnwritable) {
+          // Symmetric with the unreadable arm below. Round-5 finding: the
+          // unwritable case was wired into lifecycle's CLI but not here, so
+          // doctor printed "install reported no change (settings already had
+          // entries)" for a settings.json it had just failed to write.
+          console.log('  \u274c settings.json is not writable \u2014 hooks NOT registered');
+          console.log('     Fix the permissions on it (or on ~/.claude) and re-run; see the error above.');
+        } else if (r.settingsUnreadable) {
+          // install() refused because settings.json exists but cannot be turned
+          // into an object (unparseable / unreadable / not an object). Reporting
+          // "already had entries" here states the exact opposite of the truth,
+          // at the one moment the user most needs the real cause \u2014 which
+          // otherwise appears only on stderr, contradicted by this very line.
+          console.log('  \u274c settings.json could not be read or parsed \u2014 hooks NOT registered');
+          console.log('     Repair it (or move it aside) and re-run; see the error above.');
         } else {
           console.log('  \u2796 install reported no change (settings already had entries)');
         }
@@ -615,7 +707,7 @@ function unresolvedCount({ checkOnly, issueCount, fixed }) {
 }
 
 function runDoctor(opts = {}) {
-  const results = runDiagnostics();
+  const results = runDiagnostics({ checkOnly: opts.checkOnly });
   console.log(formatReport(results, { checkOnly: opts.checkOnly }));
 
   const issues = results.filter(r => r.status === 'warn' || r.status === 'error');
@@ -632,11 +724,57 @@ function runDoctor(opts = {}) {
   return { results, issueCount: issues.length, unresolved };
 }
 
-module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, detectEmbedModel, devBuildCommand };
+module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, detectEmbedModel, devBuildCommand };
+
+// Shared by BOTH doctor entry points: `node doctor.js …` and `node lifecycle.js
+// doctor …`. It exists as one function because the first version of this guard
+// lived only in doctor.js's `require.main` block, leaving lifecycle's arm on the
+// original `process.argv.includes('--check-only')` — so the exact bug being
+// fixed (a typo'd flag running the repair pass) survived on the sibling entry
+// point. Same half-applied shape this whole batch keeps producing.
+//
+// Returns `{ checkOnly }` to run, `{ help: true }` to print usage, or
+// `{ error }` naming the offending arguments.
+const DOCTOR_KNOWN_FLAGS = new Set(['--check-only', '--help', '-h']);
+// Kept in sync with the `doctor` help text in src/main.rs, which intercepts
+// `--help` before this script is spawned so that help stays side-effect-free.
+// Two texts for one command drift silently; a user who reaches this one (direct
+// `node doctor.js`) should read the same thing as one who reaches the other.
+const DOCTOR_USAGE = [
+  'code-graph-mcp doctor — diagnose and repair environment issues',
+  '',
+  'USAGE:',
+  '    code-graph-mcp doctor [--check-only]',
+  '',
+  'By default doctor repairs detected issues (re-registers hooks in',
+  '~/.claude/settings.json, fixes stale binary/model paths). Pass',
+  '--check-only to report issues without changing anything.',
+].join('\n');
+
+function parseDoctorArgs(args) {
+  const unknown = args.filter((a) => !DOCTOR_KNOWN_FLAGS.has(a));
+  if (unknown.length) return { error: `doctor: unknown argument(s): ${unknown.join(' ')}` };
+  if (args.includes('--help') || args.includes('-h')) return { help: true };
+  return { checkOnly: args.includes('--check-only') };
+}
+
+// Run the CLI for a parsed argv tail and return the process exit code. Shared so
+// the two entry points cannot drift on exit-code semantics either.
+function runDoctorCli(args) {
+  const parsed = parseDoctorArgs(args);
+  if (parsed.error) {
+    console.error(parsed.error);
+    console.error(DOCTOR_USAGE);
+    return 2;
+  }
+  if (parsed.help) {
+    console.log(DOCTOR_USAGE);
+    return 0;
+  }
+  const { unresolved } = runDoctor({ checkOnly: parsed.checkOnly });
+  return unresolved > 0 ? 1 : 0;
+}
 
 if (require.main === module) {
-  const args = process.argv.slice(2);
-  const checkOnly = args.includes('--check-only');
-  const { unresolved } = runDoctor({ checkOnly });
-  process.exit(unresolved > 0 ? 1 : 0);
+  process.exit(runDoctorCli(process.argv.slice(2)));
 }

package/claude-plugin/scripts/lifecycle.js

@@ -39,10 +39,131 @@ function pluginsCacheDir() { return path.join(claudeHome(), 'plugins', 'cache');
 
 // --- Helpers ---
 
+// Read JSON while keeping *why* it failed. The distinction that matters to a
+// caller about to REBUILD the file is exactly one bit — "may I treat this as a
+// fresh install?" — and only a genuine ENOENT earns a yes.
+//
+//   missing: true   ENOENT only. Nothing is there; rebuilding destroys nothing.
+//   corrupt: true   Everything else: the file EXISTS and we could not turn it
+//                   into a settings object — unparseable (trailing comma),
+//                   unreadable (EACCES after a stray `sudo`, EPERM, EIO), a
+//                   directory (EISDIR), or valid JSON that isn't an object
+//                   (`null` / `[]` / `123` / `"str"`).
+//
+// Collapsing ANY of those into "absent" is the bug: `readJson(...) || {}` then
+// hands install() an empty object and the next atomic write replaces the user's
+// whole settings.json. The first version of this fix split out only the
+// unparseable case and left the unreadable one behind — a `chmod 000`
+// settings.json was still destroyed, silently, with no backup. `err.code` is the
+// whole gate; do not widen it back to a bare `catch`.
+function readJsonResult(filePath) {
+  // Read BYTES, decode separately. `readFileSync(p, 'utf8')` replaces every
+  // invalid byte with U+FFFD, and `raw` is what backupCorruptFile writes to the
+  // `.corrupt-*` copy before the original is overwritten — so a settings.json
+  // containing any non-UTF-8 byte (a latin-1 path, a stray BOM pair) was
+  // "preserved" as a lossy transcription and the true bytes were destroyed. The
+  // backup is the user's only copy; it has to be byte-exact.
+  let bytes;
+  let raw;
+  try {
+    bytes = fs.readFileSync(filePath);
+    raw = bytes.toString('utf8');
+  } catch (err) {
+    const missing = err && err.code === 'ENOENT';
+    return { value: null, missing, corrupt: !missing, error: err };
+  }
+  // A zero-byte file is what a crash mid-write leaves behind. It carries nothing
+  // to preserve, so back-up-then-rebuild would only litter `~/.claude` with an
+  // empty `.corrupt-*` copy; treat it as absent instead.
+  if (raw.trim() === '') {
+    return { value: null, missing: true, corrupt: false, raw: bytes };
+  }
+  try {
+    // Parse the TRIMMED text. A UTF-8 BOM is JS whitespace (so `.trim()` above
+    // strips it) but `JSON.parse` rejects it — and a BOM is exactly what
+    // PowerShell 5.1's `Out-File` / `Set-Content` write by default. Parsing the
+    // untrimmed string classified a perfectly valid settings.json as corrupt and
+    // rebuilt the live file from a backup-and-replace path it never needed.
+    const value = JSON.parse(raw.trim());
+    // `null` / `"str"` / `[]` parse fine but are not a settings object; treating
+    // them as "absent" would rebuild over them just the same.
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      return { value: null, missing: false, corrupt: true, raw: bytes };
+    }
+    return { value, missing: false, corrupt: false, raw: bytes };
+  } catch (err) {
+    return { value: null, missing: false, corrupt: true, raw: bytes, error: err };
+  }
+}
+
+// Lenient reader kept exactly as-is for its 20+ callers (manifests, registries,
+// plugin.json …) where "absent" and "unreadable" genuinely mean the same thing.
+// Only the settings write path needs readJsonResult's distinction.
 function readJson(filePath) {
   try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { return null; }
 }
 
+// Preserve a file we are about to overwrite but could not turn into settings.
+// `raw` is its contents when we managed to read them; when we did not (EACCES,
+// EISDIR) it is undefined and we fall back to a filesystem-level copy — which
+// will usually fail for the same reason the read did, and that failure is the
+// point: it makes the caller refuse rather than overwrite. Returns the backup
+// path, or null when no copy could be made.
+function backupCorruptFile(filePath, raw) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dest = `${filePath}.corrupt-${stamp}`;
+  try {
+    // Buffer, not string: see readJsonResult. A string here would re-encode.
+    if (Buffer.isBuffer(raw)) fs.writeFileSync(dest, raw);
+    else if (typeof raw === 'string') fs.writeFileSync(dest, Buffer.from(raw, 'utf8'));
+    else fs.copyFileSync(filePath, dest);
+    return dest;
+  } catch {
+    return null;
+  }
+}
+
+// Read ~/.claude/settings.json for a caller that will WRITE it back.
+//
+// A settings.json that exists but yields no object used to be indistinguishable
+// from an absent one, so `readJson(settingsPath()) || {}` handed
+// install()/update() an empty object and the next atomic write replaced the
+// user's model / env / permissions / enabledPlugins / own hooks with a two-key
+// file — silently, with no copy left. Such a file is now copied aside first; if
+// even the copy fails we refuse to touch the original and return null, and the
+// caller skips its settings work entirely.
+// Returns `{ settings, backedUpTo }`:
+//   settings   — the object to write back, or null when we refused to touch the file
+//   backedUpTo — path of the preserved original when we are about to REBUILD over
+//                a file that had content, else null
+//
+// `backedUpTo` is not decoration. Rebuilding from `{}` REPLACES the user's whole
+// settings.json, and callers report their outcome to a human: `doctor` was
+// printing "Hooks ✅ 1 issue(s) auto-repaired" for a run that moved the user's
+// model / env / permissions into a `.corrupt-*` file it never mentioned. A
+// destructive repair has to be reported as one, with the path to get it back.
+function readSettingsForWrite() {
+  const p = settingsPath();
+  const res = readJsonResult(p);
+  if (res.value) return { settings: res.value, backedUpTo: null };
+  if (res.missing) return { settings: {}, backedUpTo: null };
+  const why = res.error ? res.error.message : 'it does not contain a JSON object';
+  const backup = backupCorruptFile(p, res.raw);
+  if (!backup) {
+    console.error(
+      `[code-graph] cannot use ${p} (${why}), and no backup copy could be made. ` +
+      `Leaving it untouched and skipping settings changes — repair the file ` +
+      `(or move it aside) and re-run.`
+    );
+    return { settings: null, backedUpTo: null };
+  }
+  console.error(
+    `[code-graph] cannot use ${p} (${why}). ` +
+    `Saved the original to ${backup} before rebuilding it.`
+  );
+  return { settings: {}, backedUpTo: backup };
+}
+
 function writeJsonAtomic(filePath, data) {
   const dir = path.dirname(filePath);
   fs.mkdirSync(dir, { recursive: true });
@@ -51,6 +172,25 @@ function writeJsonAtomic(filePath, data) {
   fs.renameSync(tmp, filePath);
 }
 
+// A settings.json we can READ but not WRITE (read-only ~/.claude, EROFS, a
+// container mount) used to escape as a raw fs stack trace with no `[code-graph]`
+// line — and because nothing of ours got registered, the follow-up `health` then
+// reported "OK — all paths valid", since it only checks that the paths it FINDS
+// are valid and it found none. Same class as the unreadable-file arm: report the
+// real cause, change nothing, and make the caller's exit code non-zero.
+function tryWriteSettings(settings) {
+  try {
+    writeJsonAtomic(settingsPath(), settings);
+    return null;
+  } catch (err) {
+    console.error(
+      `[code-graph] cannot write ${settingsPath()} (${err.code || err.name}: ${err.message}). ` +
+      `Nothing was changed. The plugin stays inactive until the file is writable.`
+    );
+    return err;
+  }
+}
+
 function readManifest() {
   return readJson(MANIFEST_FILE) || { version: null, config: {} };
 }
@@ -451,7 +591,19 @@ function buildSettingsHookEntries() {
 // in plugin-cache hooks.json (it's still loaded from there), so we don't
 // re-write it to settings.json.
 function registerHooksToSettings(settings) {
-  settings.hooks = settings.hooks || {};
+  // `hooks` must be a plain object. `settings.hooks || {}` accepted an ARRAY —
+  // and every named property assigned onto it below (`hooks.PreToolUse = [...]`)
+  // is silently dropped by JSON.stringify, which serializes an array by index.
+  // The result was total, reported-as-success inertness: `install` printed
+  // "Installed | settings=true", `health` printed "OK — all paths valid", and
+  // `"hooks": []` came back out with zero of our six hooks registered. A string
+  // or number was worse — an uncaught "Cannot create property on string".
+  // Anything non-object is replaced, same as a missing key: we cannot merge into
+  // a shape the schema does not allow, and leaving it means the plugin never
+  // works while claiming it does.
+  if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) {
+    settings.hooks = {};
+  }
 
   // Idempotent across delivery surfaces: if every desired (event,matcher) is
   // already present exactly once, pointing at a current, existing script
@@ -693,7 +845,19 @@ function verifyHooksFire({ hooks, env, timeoutMs = 4000, tmpBase } = {}) {
 function install({ reclaimStatusline = false } = {}) {
   const version = getPluginVersion();
   const manifest = readManifest();
-  const settings = readJson(settingsPath()) || {};
+  const { settings, backedUpTo } = readSettingsForWrite();
+  if (!settings) {
+    // Unusable settings.json that we could not even copy aside. Bail without
+    // touching it — and without stamping the manifest, so the next run retries
+    // the whole install once the user has repaired the file.
+    return {
+      version,
+      settingsChanged: false,
+      statusLineClaimed: manifest.config.statusLine,
+      hooksRegistered: false,
+      settingsUnreadable: true,
+    };
+  }
   let settingsChanged = false;
 
   // 0. Migrate from old plugin IDs
@@ -768,7 +932,20 @@ function install({ reclaimStatusline = false } = {}) {
 
   // 3. Write settings atomically if changed
   if (settingsChanged) {
-    writeJsonAtomic(settingsPath(), settings);
+    const writeErr = tryWriteSettings(settings);
+    if (writeErr) {
+      // Do NOT fall through to the manifest stamp. A manifest carrying the
+      // current version tells the next run "already installed", so it would skip
+      // the retry and the plugin would stay inactive after the user makes the
+      // file writable again — the same trap as the unreadable arm.
+      return {
+        version,
+        settingsChanged: false,
+        hooksRegistered: false,
+        settingsUnwritable: true,
+        error: writeErr.code || writeErr.name,
+      };
+    }
   }
 
   // 4. Write manifest with version
@@ -777,7 +954,14 @@ function install({ reclaimStatusline = false } = {}) {
   manifest.updatedAt = new Date().toISOString();
   writeManifest(manifest);
 
-  return { version, settingsChanged, statusLineClaimed: manifest.config.statusLine, hooksRegistered };
+  return {
+    version,
+    settingsChanged,
+    statusLineClaimed: manifest.config.statusLine,
+    hooksRegistered,
+    // Non-null => the previous settings.json was REPLACED and lives here now.
+    settingsRebuiltFrom: backedUpTo,
+  };
 }
 
 // --- Uninstall (clean all config) ---
@@ -910,7 +1094,10 @@ function update() {
   const version = getPluginVersion();
   const manifest = readManifest();
   const oldVersion = manifest.version;
-  const settings = readJson(settingsPath()) || {};
+  const { settings, backedUpTo } = readSettingsForWrite();
+  if (!settings) {
+    return { oldVersion, version, settingsChanged: false, hooksRegistered: false, settingsUnreadable: true };
+  }
   let settingsChanged = false;
 
   // 0. Migrate from old plugin IDs
@@ -939,7 +1126,18 @@ function update() {
 
   // 4. Write settings if changed
   if (settingsChanged) {
-    writeJsonAtomic(settingsPath(), settings);
+    const writeErr = tryWriteSettings(settings);
+    if (writeErr) {
+      // Same reasoning as install(): stamping the manifest here would make the
+      // next run believe the update landed.
+      return {
+        oldVersion, version,
+        settingsChanged: false,
+        hooksRegistered: false,
+        settingsUnwritable: true,
+        error: writeErr.code || writeErr.name,
+      };
+    }
   }
 
   // 5. Clear update-check cache (force re-check after update)
@@ -959,7 +1157,7 @@ function update() {
   //    therefore skips any version still referenced by a live process cmdline.
   cleanupOldCacheVersions(5);
 
-  return { oldVersion, version, settingsChanged, hooksRegistered };
+  return { oldVersion, version, settingsChanged, hooksRegistered, settingsRebuiltFrom: backedUpTo };
 }
 
 /**
@@ -1050,7 +1248,29 @@ function readActiveProcessCmdlines() {
 //              empty array means repair succeeded
 
 function scanForBrokenPaths() {
-  const settings = readJson(settingsPath()) || {};
+  // The READ-side member of the same collapsed-`null` class the write side was
+  // fixed for: `readJson(...) || {}` on an unusable settings.json yields an
+  // empty object, every loop below finds nothing to check, and the caller
+  // reports "all paths valid" — the most confidently wrong answer available,
+  // delivered during the exact incident it should be flagging. Surface it as an
+  // issue instead.
+  //
+  // NOT auto-repairable in the sense that this issue carries no `fixId`. Be
+  // precise about what `install()` then does, because an earlier version of this
+  // comment claimed it "correctly refuses this file" and that is only half true:
+  // it refuses only the subset it cannot copy aside (unreadable file, read-only
+  // dir, path-is-a-directory). For the common case — unparseable but writable —
+  // it BACKS UP and REBUILDS, so `healthCheck` reports `repaired: true` and hands
+  // back `rebuiltFrom`. Callers must render that as the destructive repair it is.
+  const settingsRead = readJsonResult(settingsPath());
+  if (settingsRead.corrupt) {
+    return [{
+      type: 'settings-unusable',
+      path: settingsPath(),
+      reason: settingsRead.error ? settingsRead.error.message : 'not a JSON object',
+    }];
+  }
+  const settings = settingsRead.value || {};
   const issues = [];
 
   // Check statusLine path
@@ -1101,13 +1321,17 @@ function healthCheck() {
   // away. install() may legitimately fail to resolve a problem (binary path
   // permanently gone, registry corrupted, etc.) and the previous code lied
   // by always returning repaired:true.
-  install();
+  const r = install();
   const remaining = scanForBrokenPaths();
   return {
     healthy: false,
     issues,
     repaired: remaining.length === 0,
     remaining,
+    // A "repair" that rebuilt an unusable settings.json REPLACED the user's
+    // file — model / env / permissions / their own hooks now live only in the
+    // backup. Callers must not render that as a plain success.
+    rebuiltFrom: r.settingsRebuiltFrom || null,
   };
 }
 
@@ -1127,16 +1351,49 @@ function isPluginUninstalled(settings = readJson(settingsPath()) || {}) {
 // this so a CC `/plugin uninstall` (which fires no uninstall hook) still reclaims
 // the disk. Idempotent: rm is force, so repeat SessionStarts are no-ops. Does NOT
 // touch the plugin-cache script dirs — those are CC-managed and may be executing.
+// One thing in CACHE_DIR is NOT residue: adopted-projects.json, the only record
+// of which repos carry a managed CLAUDE.md block. Wiping it strands every block
+// — `uninstall({unadoptAll:true})` afterwards reads an empty registry, reports
+// `unadopted: []`, and the blocks stay in the user's repos with nothing left
+// that knows where they are. `uninstall()` captures the list before calling
+// here; `cleanupDisabledStatusline` does not, and by this function's own comment
+// that is the ONE path guaranteed to run after `/plugin uninstall`. So the
+// preservation belongs here, at the wipe, rather than at each caller — the same
+// "fix it at the shared layer, not per surface" the <external> query filter
+// needed.
 function removeCacheResidue() {
-  try { fs.rmSync(CACHE_DIR, { recursive: true, force: true }); return true; }
-  catch { return false; }
+  // Path comes from adopt.js rather than a second spelling of the basename —
+  // a literal here would silently stop matching the day adopt.js renames it,
+  // and the failure mode is exactly the data loss this guard exists to stop.
+  // Preserve ONLY when the registry still names projects. A registry that is
+  // absent, empty, or already fully unadopted (the normal SessionStart teardown
+  // order, which unadopts first) strands nothing, and re-creating CACHE_DIR to
+  // hold `[]` would just be new residue.
+  let registryPath = null;
+  let registry = null;
+  try {
+    registryPath = require('./adopt').adoptedRegistryFile();
+    const raw = fs.existsSync(registryPath) ? fs.readFileSync(registryPath) : null;
+    const parsed = raw ? JSON.parse(raw.toString('utf8')) : null;
+    if (Array.isArray(parsed) && parsed.length) registry = raw;
+  } catch { /* POSIX-only helper, unreadable, or corrupt — nothing to preserve */ }
+  try {
+    fs.rmSync(CACHE_DIR, { recursive: true, force: true });
+  } catch { return false; }
+  if (registryPath && registry) {
+    try {
+      fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+      fs.writeFileSync(registryPath, registry);
+    } catch { /* best-effort: the binary is still reclaimed */ }
+  }
+  return true;
 }
 
 module.exports = {
   install, uninstall, update, healthCheck, scanForBrokenPaths, checkScopeConflict,
   isPluginExplicitlyDisabled, isPluginInactive, isPluginUninstalled, removeCacheResidue,
   cleanupDisabledStatusline,
-  readManifest, readJson, writeJsonAtomic,
+  readManifest, readJson, readJsonResult, readSettingsForWrite, writeJsonAtomic,
   readRegistry, writeRegistry,
   getPluginVersion, cleanupOldCacheVersions,
   removeHooksFromSettings, isOurHookEntry,
@@ -1158,6 +1415,15 @@ if (require.main === module) {
   if (cmd === 'install') {
     // Explicit CLI install = user intent: reset any statusline stand-down and re-claim.
     const r = install({ reclaimStatusline: true });
+    // Refusing to touch an unusable settings.json means NOTHING was installed —
+    // no hooks, no statusline, no manifest stamp. Printing "Installed" and
+    // exiting 0 there would make `lifecycle.js install && …` chains read the
+    // refusal as success; the true diagnosis is already on stderr.
+    if (r.settingsUnreadable || r.settingsUnwritable) {
+      const why = r.settingsUnreadable ? 'unusable' : 'not writable';
+      console.log(`Not installed: ${settingsPath()} is ${why} (see the error above). Nothing was changed.`);
+      process.exit(1);
+    }
     console.log(`Installed v${r.version} | settings=${r.settingsChanged} | statusLine=${r.statusLineClaimed}`);
   } else if (cmd === 'uninstall') {
     const r = uninstall({
@@ -1191,6 +1457,11 @@ if (require.main === module) {
     console.log('  Note: also run `/plugin uninstall code-graph-mcp` inside Claude Code to sync its UI state.');
   } else if (cmd === 'update') {
     const r = update();
+    if (r.settingsUnreadable || r.settingsUnwritable) {
+      const why = r.settingsUnreadable ? 'unusable' : 'not writable';
+      console.log(`Not updated: ${settingsPath()} is ${why} (see the error above). Nothing was changed.`);
+      process.exit(1);
+    }
     console.log(`Updated ${r.oldVersion} → ${r.version} | settings=${r.settingsChanged}`);
   } else if (cmd === 'health') {
     const r = healthCheck();
@@ -1203,12 +1474,14 @@ if (require.main === module) {
       }
     }
   } else if (cmd === 'doctor') {
-    const { runDoctor } = require('./doctor');
-    const checkOnly = process.argv.includes('--check-only');
-    // Exit on issues that remain UNRESOLVED after repair, not issues found —
-    // a run that fixes everything exits 0. See unresolvedCount in doctor.js.
-    const { unresolved } = runDoctor({ checkOnly });
-    process.exit(unresolved > 0 ? 1 : 0);
+    // Delegate to doctor.js's shared CLI so the two entry points cannot drift on
+    // flag validation or exit codes. This arm used to do its own
+    // `process.argv.includes('--check-only')`, which silently ignored every other
+    // argument — `lifecycle.js doctor --check-onlyy` ran the full repair pass.
+    // Exit code still reflects issues that remain UNRESOLVED after repair, not
+    // issues found (see unresolvedCount in doctor.js).
+    const { runDoctorCli } = require('./doctor');
+    process.exit(runDoctorCli(process.argv.slice(3)));
   } else if (cmd === 'verify-hooks-fire') {
     // v0.67.0 — Layer-A firing self-test. Spawned detached by session-init
     // (off the SessionStart budget); writes a small state file the next

package/claude-plugin/scripts/session-init.js

@@ -193,6 +193,29 @@ function isHighIntentSource(source) {
   return source !== 'compact';
 }
 
+// Every install()/update() in this file goes through these wrappers so the
+// "your settings.json was rebuilt" notice cannot be wired into some call sites
+// and not others — there are seven, and the previous fix wired the notice only
+// into `doctor`, the path a user runs deliberately, while THIS path runs on
+// every SessionStart and stayed silent.
+//
+// The notice goes to STDOUT on purpose. lifecycle.js already logs it to stderr,
+// which a SessionStart hook discards — so from the user's side their model /
+// env / permissions vanished with no message at all. stdout is the channel
+// Claude Code surfaces (same one injectProjectMap uses).
+function reportRebuild(r) {
+  if (r && r.settingsRebuiltFrom) {
+    process.stdout.write(
+      `[code-graph] ${settingsPath()} could not be parsed and has been REBUILT. ` +
+      `Your original is saved at ${r.settingsRebuiltFrom} — merge anything you ` +
+      `still need (model / env / permissions / your own hooks) back by hand.\n`
+    );
+  }
+  return r;
+}
+function installReporting(...args) { return reportRebuild(install(...args)); }
+function updateReporting(...args) { return reportRebuild(update(...args)); }
+
 function syncLifecycleConfig() {
   // v0.49.1: stale-relic guard. A still-running Claude Code process fires
   // SessionStart from the plugin-cache dir it loaded at startup; after
@@ -207,11 +230,11 @@ function syncLifecycleConfig() {
   const currentVersion = getPluginVersion();
 
   if (!manifest.version) {
-    install();
+    installReporting();
     return 'installed';
   }
   if (manifest.version !== currentVersion) {
-    update();
+    updateReporting();
     return 'updated';
   }
   // Self-heal: version matches but statusLine may have been lost or path corrupted
@@ -220,13 +243,13 @@ function syncLifecycleConfig() {
   const settings = readJson(settingsPath()) || {};
   if (!settings.statusLine || !settings.statusLine.command ||
       !settings.statusLine.command.includes('statusline-composite')) {
-    install();
+    installReporting();
     return 'self-healed';
   }
   // Also self-heal if composite path points to a non-existent script (path pollution)
   const scriptMatch = settings.statusLine.command.match(/node\s+"([^"]+)"/);
   if (scriptMatch && scriptMatch[1] && !fs.existsSync(scriptMatch[1])) {
-    install();
+    installReporting();
     return 'self-healed-bad-path';
   }
   // v0.49.1: also self-heal when the composite path exists but is not the one
@@ -234,7 +257,7 @@ function syncLifecycleConfig() {
   // invisible to the existence check above; same fault class as the binary pin).
   const { compositeCommand } = require('./lifecycle');
   if (settings.statusLine.command !== compositeCommand()) {
-    install();
+    installReporting();
     return 'self-healed-stale-statusline';
   }
   // Self-heal if any hook command points to a non-existent script (path pollution)
@@ -246,7 +269,7 @@ function syncLifecycleConfig() {
         for (const h of entry.hooks) {
           const m = h.command && h.command.match(/node\s+"([^"]+)"/);
           if (m && m[1] && m[1].includes('code-graph') && !fs.existsSync(m[1])) {
-            install();
+            installReporting();
             return 'self-healed-bad-hook';
           }
         }
@@ -265,11 +288,11 @@ function syncLifecycleConfig() {
   const { surveyHookCoverage } = require('./lifecycle');
   const cov = surveyHookCoverage(settings);
   if (cov.missing.length > 0) {
-    install();
+    installReporting();
     return 'self-healed-missing-settings-hook';
   }
   if (cov.stale.length > 0) {
-    install();
+    installReporting();
     return 'self-healed-stale-settings-hook';
   }
   return 'noop';
@@ -489,7 +512,21 @@ function runSessionInit({ source } = {}) {
     // only place project unadoption can happen automatically.
     let teardown = null;
     if (uninstalled) {
-      const cacheRemoved = removeCacheResidue();
+      // Unadopt BEFORE the wipe. The adopted-projects registry lives inside
+      // CACHE_DIR, so wiping first destroyed the record of every OTHER adopted
+      // repo — this branch only unadopts the current cwd, and a later
+      // `uninstall --unadopt-all` then read an empty registry and reported
+      // `unadopted: []` while the blocks stayed behind. Same capture-before-
+      // cleanup ordering `uninstall()` already had to learn; this was its
+      // sibling.
+      //
+      // Honest scope: this reorder alone does NOT save the registry. On the
+      // genuine post-uninstall path `cleanupDisabledStatusline()` runs earlier
+      // in this same function and already calls removeCacheResidue() itself, so
+      // the wipe still happens before we get here. What actually protects the
+      // other projects is the preservation inside removeCacheResidue(); this
+      // ordering is the belt to that pair of braces, and it is what keeps the
+      // single-project case from depending on the preservation at all.
       let unadopted = false;
       try {
         if (!isNonProjectCwd(process.cwd())) {
@@ -497,6 +534,7 @@ function runSessionInit({ source } = {}) {
           unadopted = !!(r && (r.blockPruned || r.fileRemoved || r.claudeMdRemoved));
         }
       } catch { /* best-effort — never let teardown break SessionStart */ }
+      const cacheRemoved = removeCacheResidue();
       teardown = { cacheRemoved, unadopted };
     }
     return { inactive: true, lifecycle: 'noop', autoUpdateLaunched: false, teardown };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.107.0",
+  "version": "0.108.1",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.107.0",
-    "@sdsrs/code-graph-linux-arm64": "0.107.0",
-    "@sdsrs/code-graph-darwin-x64": "0.107.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.107.0",
-    "@sdsrs/code-graph-win32-x64": "0.107.0"
+    "@sdsrs/code-graph-linux-x64": "0.108.1",
+    "@sdsrs/code-graph-linux-arm64": "0.108.1",
+    "@sdsrs/code-graph-darwin-x64": "0.108.1",
+    "@sdsrs/code-graph-darwin-arm64": "0.108.1",
+    "@sdsrs/code-graph-win32-x64": "0.108.1"
   }
 }