@sdsrs/code-graph 0.116.0 → 0.118.0

package/README.md

@@ -22,7 +22,7 @@ A high-performance code knowledge graph server implementing the [Model Context P
 - **Embedding model** — Optional local embedding via Candle (feature-gated `embed-model`). Context reordered to prioritize structural relations over code for better embedding quality
 - **Self-healing** — Automatic SQLite corruption recovery with rebuild. Startup repair for incomplete indexing (Phase 3 failures)
 - **MCP protocol** — JSON-RPC 2.0 over stdio, plug-and-play with Claude Code, Cursor, Windsurf, and other MCP clients
-- **Claude Code Plugin** — First-class plugin with slash commands (`/understand`, `/trace`, `/impact`), agents, skills, auto-indexing hooks, StatusLine integration, and self-updating
+- **Claude Code Plugin** — First-class plugin with skills (`explore`, `index`), a `code-explorer` agent, auto-indexing hooks, StatusLine integration, and self-updating
 
 ## Why code-graph-mcp?
 
@@ -109,14 +109,18 @@ Real-world benchmarks comparing code-graph-mcp tools against traditional approac
 ```
 src/
 ├── domain.rs     # Shared constants, relation types, env-var config
+├── resolve.rs    # Shared symbol resolution + ambiguity verdicts (CLI and MCP)
+├── outcome.rs    # Retrieval-adoption metrics from session transcripts
+├── cli/          # Every `code-graph-mcp <cmd>` subcommand (one file per command)
 ├── mcp/          # MCP protocol layer (JSON-RPC, tool registry, server)
 │   └── server/   # McpServer with IndexingState + CacheState sub-structs
 ├── parser/       # Tree-sitter parsing, relation extraction, LanguageConfig dispatch
 ├── indexer/      # 3-phase pipeline, Merkle tree, file watcher
-├── storage/      # SQLite schema (v6), CRUD, FTS5, migrations
+├── storage/      # SQLite schema (v10), CRUD, FTS5, migrations
 ├── graph/        # Recursive CTE call graph queries
 ├── search/       # RRF fusion search combining BM25 + vector
 ├── embedding/    # Candle embedding model (optional, masked mean pooling)
+├── snapshot/     # Portable graph snapshots (create / verify / install)
 ├── sandbox/      # Context compressor with token estimation
 └── utils/        # Language detection, config
 ```
@@ -125,7 +129,7 @@ src/
 
 ### Option 1: Claude Code Plugin (Recommended)
 
-Install as a Claude Code plugin for the best experience — includes slash commands, agents, skills, auto-indexing hooks, StatusLine health display, and automatic updates:
+Install as a Claude Code plugin for the best experience — includes skills, the `code-explorer` agent, auto-indexing hooks, StatusLine health display, and automatic updates:
 
 ```bash
 # Step 1: Add the marketplace
@@ -137,11 +141,11 @@ Install as a Claude Code plugin for the best experience — includes slash comma
 
 What you get:
 - **MCP Server** — All code-graph tools available to Claude
-- **Slash Commands** — `/understand <module>`, `/trace <route>`, `/impact <symbol>`
+- **Skills** — `explore` (structure-first navigation before reading files) and `index` (health-check / re-index / full rebuild); see [Plugin Skills](#plugin-skills)
 - **Code Explorer Agent** — Deep code understanding expert via `code-explorer`
 - **Auto-indexing Hook** — Incremental index on every file edit (PostToolUse)
 - **StatusLine** — Real-time health display (nodes, files, watch status) — compatible with other plugins' StatusLine via composite multiplexer
-- **Auto-update** — Checks for new versions every 6h, updates silently
+- **Auto-update** — Checks for a new version at session start (throttled to at most one check every 2 minutes). Between forced checks the re-check interval is 30 minutes after an "up to date" answer and 6 hours while an update is already pending. Updates install silently.
 
 #### Manual Update
 
@@ -301,22 +305,38 @@ All tools are also available as CLI subcommands for shell scripts, hooks, and te
 | `incremental-index` | — | Run incremental index update (auto-creates DB if needed) |
 | `health-check` | `get_index_status` | Query index status and freshness |
 | `benchmark` | — | Benchmark index speed, query latency, token savings |
+| `affected [files…]` | — | Changed files → the test files to re-run (`--stdin`, `--depth`) |
+| `tour [path]` | — | Dependency-ordered reading order for a repo or subtree |
+| `centrality` | `project_map` (`include_centrality=true`) | Rank architectural chokepoints (betweenness over the call graph) |
+| `cycles` | — | Detect circular import dependencies (file-level) |
+| `surprising` | — | Surface unexpected cross-module couplings (uncertain edges) |
+| `report` | — | Consolidated code-health report (summary + all analyses) |
+| `stats` | — | Aggregate session metrics from `.code-graph/usage.jsonl` |
+| `outcome` | — | Retrieval adoption from session transcripts (field-MRR; read-only) |
+| `rebuild-index` | `rebuild_index` | Drop and rebuild the index from scratch (requires `--confirm`) |
+| `reindex` | — | Incremental refresh; `--from-snapshot` refetches the published snapshot |
+| `snapshot create\|inspect` | — | Build or inspect a portable graph snapshot |
+| `doctor` | — | Diagnose and repair environment issues |
+| `adopt` | — | Install the steering block into the project `CLAUDE.md` + detail doc |
+| `unadopt` | — | Remove the steering block + detail doc |
+| `serve` | — | Start the MCP JSON-RPC server on stdio (the default with no subcommand) |
 
 Common options: `--json` (JSON output), `--compact` (compact output), `--limit N`, `--depth N`, `--file <path>`.
 
 As of **v0.37.0** the CLI is [clap](https://docs.rs/clap)-based: **every subcommand has `--help`** for its full flag list (`code-graph-mcp <command> --help`), value flags accept both `--flag value` and `--flag=value`, and unknown flags or malformed arguments fail fast with a clear error and a non-zero exit code (`2`) instead of being silently ignored. For example, `trace` hides downstream middleware with `--no-middleware` (shown by default), and `snapshot` is a `create`/`inspect` subcommand pair.
 
-## Plugin Slash Commands
+## Plugin Skills
 
-Available when installed as a Claude Code plugin:
+Installing the plugin ships two skills that Claude loads on its own when the
+situation matches — there are no slash commands to remember:
 
-| Command | Description |
-|---------|-------------|
-| `/understand <module>` | Deep dive into a module or file's architecture and relationships |
-| `/trace <route>` | Trace a full HTTP request flow from route to data layer |
-| `/impact <symbol>` | Analyze the impact scope of changing a symbol before modifying it |
-| `/status` | Show code-graph index status and embedding progress |
-| `/rebuild` | Force a full code-graph index rebuild |
+| Skill | Loaded when | What it does |
+|-------|-------------|--------------|
+| `explore` | Starting work in unfamiliar code, or before editing a module | Routes the question to `overview` / `map` / `callgraph` / `search` / `impact` instead of reading files one at a time |
+| `index` | Search returns empty or stale results, or after a large restructuring | Walks `health-check`, incremental re-index, and full rebuild |
+
+Both are thin routers over the CLI subcommands documented above, so anything a
+skill does is also runnable by hand.
 
 ## Supported Languages (19)
 
@@ -438,7 +458,10 @@ Data is stored in `.code-graph/index.db` under the project root (auto-created, g
 
 ### Prerequisites
 
-- Rust 1.75+ (2021 edition)
+- Rust 1.95.0 (2021 edition) — the toolchain CI and the release build pin
+  (`dtolnay/rust-toolchain@1.95.0` in `.github/workflows/`). No older toolchain
+  is tested: `Cargo.lock` is lockfile **version 4**, which Cargo 1.75 cannot
+  read at all, and no `rust-version` floor is declared in `Cargo.toml`.
 - A C compiler (for bundled SQLite / sqlite-vec)
 
 ### Build

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

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

package/claude-plugin/scripts/adopt.js

@@ -323,6 +323,42 @@ function escapeRegex(s) {
   return s.replace(/[\\/[\]^$.*+?()|{}]/g, '\\$&');
 }
 
+// Remove every match of `re` and heal ONLY the seam each removal leaves behind.
+//
+// The whole-file `out.replace(/\n{3,}/g, '\n\n')` this replaces was the last
+// unscoped edit in a function whose entire contract is "touch nothing but our
+// block". It rewrote the user's prose: blank-line runs inside fenced code blocks
+// collapsed, and because the collapse changed bytes even when no marker was
+// present, `unadopt` reported "De-blocked" for files that never held our block
+// — on every SessionStart, and across every registered project on uninstall
+// (audit 2026-08-16 P1-15).
+//
+// Seam rule: the blank lines that end up adjacent BECAUSE the block between them
+// was removed collapse to one blank line (the old behavior, now local); bytes
+// anywhere else are copied through untouched. A text containing no match is
+// returned identical, which is what makes "changed" mean "we removed something".
+function stripAndHealSeams(text, re) {
+  let out = '';
+  let cursor = 0;
+  re.lastIndex = 0;
+  for (let m = re.exec(text); m !== null; m = re.exec(text)) {
+    if (m[0] === '') { re.lastIndex++; continue; }  // zero-width guard: never loop forever
+    out += text.slice(cursor, m.index);
+    cursor = m.index + m[0].length;
+    const before = /\n*$/.exec(out)[0].length;
+    const after = /^\n*/.exec(text.slice(cursor))[0].length;
+    if (before + after > 2) {
+      out = out.slice(0, out.length - before) + '\n\n';
+      // Skip the newlines we just absorbed. Safe for the scan: the skipped span
+      // is newlines only, and every pattern here starts at a line's first
+      // non-newline character.
+      cursor += after;
+      re.lastIndex = cursor;
+    }
+  }
+  return out + text.slice(cursor);
+}
+
 // 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.
 //
@@ -352,7 +388,7 @@ function stripSentinelBlock(text) {
     `${BEGIN_LINE}(?:(?!${SENTINEL_BEGIN_SRC})[\\s\\S])*?${END_LINE}\\n?`,
     'gm'
   );
-  let out = text.replace(wellFormed, '');
+  let out = stripAndHealSeams(text, wellFormed);
   // Orphan BEGIN with no matching END (truncation / partial edit): remove the
   // MARKER LINE ONLY, never the content after it.
   //
@@ -371,13 +407,17 @@ function stripSentinelBlock(text) {
   // 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.
+  out = stripAndHealSeams(out, orphanBegin);
+  // Orphan END line by itself — same rule, one line, nothing around it. Written
+  // as the same line-anchored removal the other two passes use (the old
+  // split/filter/join spelling was a third predicate for "is this our END line",
+  // and every duplicated predicate in this file has drifted at least once).
   if (out.includes(SENTINEL_END)) {
-    out = out.split('\n').filter(l => l.trim() !== SENTINEL_END).join('\n');
+    out = stripAndHealSeams(out, new RegExp(`${END_LINE}\\n?`, 'gm'));
   }
-  // Collapse blank-line runs introduced by stripping mid-paragraph blocks.
-  return out.replace(/\n{3,}/g, '\n\n');
+  // NOTE: no whole-file newline collapse here. Each removal above healed its own
+  // seam; bytes the user wrote are returned exactly as they came in.
+  return out;
 }
 
 function platformGuard() {
@@ -402,32 +442,62 @@ function adoptedRegistryFile(home) {
   return path.join(home || os.homedir(), '.cache', 'code-graph', 'adopted-projects.json');
 }
 
-function readAdoptedProjects(home) {
+// Read the registry keeping WHY it failed — the same one bit lifecycle.js's
+// readJsonResult exists for. Only a genuinely ABSENT (or empty) file may be
+// treated as "nothing here, safe to create": everything else (EACCES, EISDIR,
+// truncated JSON, wrong shape) means the file EXISTS and holds entries we cannot
+// read. The old lenient reader returned `[]` for all of them and the next
+// recordAdopted persisted `[thisProject]` over it — dropping every other adopted
+// project, which is exactly the list `uninstall --unadopt-all` iterates, so
+// their managed CLAUDE.md blocks would be stranded (audit 2026-08-16 P1-12).
+function readAdoptedResult(home) {
+  let raw;
+  try {
+    raw = fs.readFileSync(adoptedRegistryFile(home), 'utf8');
+  } catch (err) {
+    const missing = Boolean(err) && err.code === 'ENOENT';
+    return { list: [], missing, unusable: !missing };
+  }
+  if (raw.trim() === '') return { list: [], missing: true, unusable: false };
   try {
-    const list = JSON.parse(fs.readFileSync(adoptedRegistryFile(home), 'utf8'));
-    return Array.isArray(list) ? list.filter((p) => typeof p === 'string') : [];
-  } catch { return []; }
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return { list: [], missing: false, unusable: true };
+    return { list: parsed.filter((p) => typeof p === 'string'), missing: false, unusable: false };
+  } catch {
+    return { list: [], missing: false, unusable: true };
+  }
 }
 
+/** Read-side contract is unchanged: a list, never a throw. */
+function readAdoptedProjects(home) {
+  return readAdoptedResult(home).list;
+}
+
+/** @returns {boolean} true when the project is recorded (or already was). */
 function recordAdopted(projectDir, home) {
+  const res = readAdoptedResult(home);
+  if (res.unusable) return false;   // never rebuild over entries we cannot read
   try {
     const file = adoptedRegistryFile(home);
-    const list = readAdoptedProjects(home);
     const abs = path.resolve(projectDir);
-    if (list.includes(abs)) return;
+    if (res.list.includes(abs)) return true;
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    writeFileAtomic(file, JSON.stringify([...list, abs], null, 2) + '\n');
-  } catch { /* best-effort */ }
+    writeFileAtomic(file, JSON.stringify([...res.list, abs], null, 2) + '\n');
+    return true;
+  } catch { return false; }        // best-effort: registry loss only degrades guidance
 }
 
+/** @returns {boolean} true when the project is absent from the registry afterwards. */
 function removeAdopted(projectDir, home) {
+  const res = readAdoptedResult(home);
+  if (res.unusable) return false;
   try {
-    const list = readAdoptedProjects(home);
     const abs = path.resolve(projectDir);
-    const next = list.filter((p) => p !== abs);
-    if (next.length === list.length) return;
+    const next = res.list.filter((p) => p !== abs);
+    if (next.length === res.list.length) return true;
     writeFileAtomic(adoptedRegistryFile(home), JSON.stringify(next, null, 2) + '\n');
-  } catch { /* best-effort */ }
+    return true;
+  } catch { return false; }
 }
 
 function adopt({ cwd, templatePath, home } = {}) {
@@ -445,18 +515,40 @@ function adopt({ cwd, templatePath, home } = {}) {
     return { ok: false, reason: 'no-template', template: tpl };
   }
 
+  // Every filesystem touch below is on files the USER owns and may have made
+  // unreadable (a root-owned CLAUDE.md from a `sudo` session) or replaced with a
+  // directory. Those throw EACCES/EISDIR, and this function is called bare from
+  // maybeAutoAdopt → runSessionInit: one such file killed the whole SessionStart
+  // hook, so binary verification, index freshness and the hook self-test never
+  // ran (audit 2026-08-16 P1-16). Adoption is optional; the rest of the session
+  // is not. Every arm below returns a REASON instead of throwing.
+
   // 1. Install the detail doc at <cwd>/.claude/plugin_code_graph_mcp.md.
   // First line is the MANAGED_BY marker (HTML comment → invisible in rendered
   // markdown) so unadopt/needsRefresh can tell our generated copy from a user
   // file of the same name. needsRefresh strips it before the bytewise compare.
   const dDir = detailDir(effectiveCwd);
-  if (!fs.existsSync(dDir)) fs.mkdirSync(dDir, { recursive: true });
   const dPath = detailPath(effectiveCwd);
-  const desiredDetail = Buffer.concat([Buffer.from(`${MANAGED_BY}\n`), fs.readFileSync(tpl)]);
   let detailWritten = false;
-  if (!fs.existsSync(dPath) || !fs.readFileSync(dPath).equals(desiredDetail)) {
-    writeFileAtomic(dPath, desiredDetail);
-    detailWritten = true;
+  let desiredDetail;
+  try {
+    desiredDetail = Buffer.concat([Buffer.from(`${MANAGED_BY}\n`), fs.readFileSync(tpl)]);
+  } catch (e) {
+    return { ok: false, reason: 'no-template', template: tpl, error: e.code || String(e) };
+  }
+  try {
+    if (!fs.existsSync(dDir)) fs.mkdirSync(dDir, { recursive: true });
+    // readFileSync on the existing copy can throw for the same reasons as
+    // CLAUDE.md below; an unreadable one is "different from what we want", so
+    // fall through to the write and let THAT report the real failure.
+    let current = null;
+    try { current = fs.readFileSync(dPath); } catch { current = null; }
+    if (current === null || !current.equals(desiredDetail)) {
+      writeFileAtomic(dPath, desiredDetail);
+      detailWritten = true;
+    }
+  } catch (e) {
+    return { ok: false, reason: 'detail-unwritable', detailPath: dPath, error: e.code || String(e) };
   }
 
   // 2. Ensure the managed block in <cwd>/CLAUDE.md. Create-if-missing, else
@@ -465,19 +557,33 @@ function adopt({ cwd, templatePath, home } = {}) {
   const cPath = claudeMdPath(effectiveCwd);
   const block = buildBlock(detectProjectType(effectiveCwd));
   const exists = fs.existsSync(cPath);
-  const current = exists ? fs.readFileSync(cPath, 'utf8') : '';
+  let current = '';
+  if (exists) {
+    try {
+      current = fs.readFileSync(cPath, 'utf8');
+    } catch (e) {
+      // EACCES / EISDIR / EIO: the file is there and we cannot read it. Writing
+      // anyway would replace content we never saw, so this project simply cannot
+      // be adopted right now.
+      return { ok: false, reason: 'claude-md-unreadable', claudeMdPath: cPath, error: e.code || String(e) };
+    }
+  }
   if (current.includes(block)) {
-    recordAdopted(effectiveCwd, home);
-    return { ok: true, detailPath: dPath, claudeMdPath: cPath, detailWritten, claudeMdWritten: false, created: false, healed: false };
+    const registryRecorded = recordAdopted(effectiveCwd, home);
+    return { ok: true, detailPath: dPath, claudeMdPath: cPath, detailWritten, claudeMdWritten: false, created: false, healed: false, registryRecorded };
   }
   const cleaned = exists ? stripSentinelBlock(current) : '';
   const healed = exists && cleaned !== current;
   const base = cleaned.replace(/\n+$/, '');
   const prefix = base ? base + '\n\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 };
+  try {
+    // followLink: read-modify-write of a file the user may have symlinked.
+    writeFileAtomic(cPath, prefix + block + '\n', { followLink: true });
+  } catch (e) {
+    return { ok: false, reason: 'claude-md-unwritable', claudeMdPath: cPath, error: e.code || String(e) };
+  }
+  const registryRecorded = recordAdopted(effectiveCwd, home);
+  return { ok: true, detailPath: dPath, claudeMdPath: cPath, detailWritten, claudeMdWritten: true, created: !exists, healed, registryRecorded };
 }
 
 // "已 install" 判定：detail 文件在 + CLAUDE.md 内有我们的 sentinel 块（任意版本）。
@@ -487,7 +593,11 @@ function isAdopted({ cwd } = {}) {
   const cPath = claudeMdPath(effectiveCwd);
   const dPath = detailPath(effectiveCwd);
   if (!fs.existsSync(dPath) || !fs.existsSync(cPath)) return false;
-  const c = fs.readFileSync(cPath, 'utf8');
+  // Unreadable (EACCES) or a directory (EISDIR) → "not adopted here". A throw
+  // out of this predicate took SessionStart down with it (P1-16), and a file we
+  // cannot read cannot be proven to hold our block anyway.
+  let c;
+  try { c = fs.readFileSync(cPath, 'utf8'); } catch { return false; }
   // 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.
@@ -507,8 +617,15 @@ function needsRefresh({ cwd, templatePath } = {}) {
     return false;
   }
   // Detail-doc body drift — strip the leading MANAGED_BY marker line first.
-  const shipped = fs.readFileSync(tpl);
-  const current = fs.readFileSync(dPath);
+  // Unreadable inputs → false: a refresh we cannot decide is one we must not
+  // attempt (and adopt() would refuse the write anyway). Never throws — this
+  // runs inside the SessionStart hook (P1-16).
+  let shipped;
+  let current;
+  try {
+    shipped = fs.readFileSync(tpl);
+    current = fs.readFileSync(dPath);
+  } catch { return false; }
   let body = current;
   const nl = current.indexOf(0x0a);
   // Equality on the trimmed line, matching the unadopt guard. `includes` here
@@ -523,7 +640,9 @@ function needsRefresh({ cwd, templatePath } = {}) {
   // needsRefresh always agree on the variant — including when a project gains a
   // web-framework dep and switches type bucket, or on a sentinel version bump.
   const block = buildBlock(detectProjectType(effectiveCwd));
-  return !fs.readFileSync(cPath, 'utf8').includes(block);
+  try {
+    return !fs.readFileSync(cPath, 'utf8').includes(block);
+  } catch { return false; }
 }
 
 // 检测脚本是否从 Claude Code 插件 cache 运行。
@@ -643,25 +762,45 @@ function unadopt({ cwd, home } = {}) {
       mine = h === MANAGED_BY
         || (h.startsWith(LEGACY_ADOPTED_BY) && h.endsWith('-->'));
     } catch { mine = false; }
-    if (mine) { fs.unlinkSync(dPath); fileRemoved = true; }
+    // The unlink itself can fail (read-only dir, EPERM) — an uninstall sweep
+    // must keep going for the remaining projects.
+    if (mine) {
+      try { fs.unlinkSync(dPath); fileRemoved = true; } catch { /* left behind, reported as not removed */ }
+    }
   }
 
   // CLAUDE.md — strip only our block. If nothing else remains, remove the file
   // we created; otherwise preserve the user's prose.
+  //
+  // Unreadable / a directory / an un-writable dir: report it and move on. This
+  // path runs over EVERY registered project from `uninstall --unadopt-all`, so
+  // one bad file used to abort the whole sweep with a raw stack trace (P1-16).
+  let claudeMdUnreadable = false;
+  let claudeMdUnwritable = false;
   if (fs.existsSync(cPath)) {
-    const before = fs.readFileSync(cPath, 'utf8');
-    const after = stripSentinelBlock(before);
-    if (after !== before) {
-      blockPruned = true;
-      // 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, { followLink: true });
+    let before;
+    try {
+      before = fs.readFileSync(cPath, 'utf8');
+    } catch { claudeMdUnreadable = true; }
+    if (before !== undefined) {
+      const after = stripSentinelBlock(before);
+      if (after !== before) {
+        try {
+          // 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, { followLink: true });
+          }
+          // Only after the write lands: `blockPruned` drives the "De-blocked"
+          // line, and claiming it for a write that threw is the same class of
+          // false success this batch keeps finding.
+          blockPruned = true;
+        } catch { claudeMdUnwritable = true; }
       }
     }
   }
@@ -669,8 +808,12 @@ function unadopt({ cwd, home } = {}) {
   // Also sweep any legacy memory-dir remnants (uninstall before auto-migration ran).
   const migrated = migrateLegacyMemoryDir({ cwd, home });
 
-  removeAdopted(effectiveCwd, home);
-  return { ok: true, fileRemoved, blockPruned, claudeMdRemoved, target: dPath, claudeMdPath: cPath, migrated };
+  const registryUpdated = removeAdopted(effectiveCwd, home);
+  return {
+    ok: true, fileRemoved, blockPruned, claudeMdRemoved,
+    claudeMdUnreadable, claudeMdUnwritable, registryUpdated,
+    target: dPath, claudeMdPath: cPath, migrated,
+  };
 }
 
 function formatResult(action, result) {
@@ -688,6 +831,18 @@ function formatResult(action, result) {
       if (result.reason === 'no-template') {
         return `[code-graph] Template missing: ${result.template}`;
       }
+      // Name the file and the OS error: "adopt failed: claude-md-unreadable" is
+      // not something a user can act on, and this is the arm a root-owned
+      // CLAUDE.md lands in.
+      if (result.reason === 'claude-md-unreadable' || result.reason === 'claude-md-unwritable') {
+        const what = result.reason === 'claude-md-unreadable' ? 'read' : 'write';
+        return `[code-graph] Cannot ${what} ${result.claudeMdPath} (${result.error || 'unknown error'}).\n` +
+               `  Nothing was changed. Fix its permissions (or move it aside) and re-run;\n` +
+               '  opt out entirely with CODE_GRAPH_NO_AUTO_ADOPT=1.';
+      }
+      if (result.reason === 'detail-unwritable') {
+        return `[code-graph] Cannot write ${result.detailPath} (${result.error || 'unknown error'}). Nothing was changed.`;
+      }
       return `[code-graph] adopt failed: ${result.reason || 'unknown'}`;
     }
     const lines = [];
@@ -707,11 +862,16 @@ function formatResult(action, result) {
     if (result.claudeMdRemoved) lines.push(`[code-graph] Removed → ${result.claudeMdPath} (was code-graph-only)`);
     else if (result.blockPruned) lines.push(`[code-graph] De-blocked → ${result.claudeMdPath}`);
     if (result.fileRemoved) lines.push(`[code-graph] Removed → ${result.target}`);
+    if (result.claudeMdUnreadable || result.claudeMdUnwritable) {
+      lines.push(`[code-graph] Could not ${result.claudeMdUnreadable ? 'read' : 'write'} ${result.claudeMdPath} — ` +
+                 'the managed block (if any) is still there. Fix its permissions and re-run.');
+    }
     const m = result.migrated || {};
     if (m.memoryIndexPruned || m.legacyDetailRemoved) {
       lines.push('[code-graph] Cleaned legacy memory-dir artifacts.');
     }
     if (!result.blockPruned && !result.fileRemoved && !result.claudeMdRemoved &&
+        !result.claudeMdUnreadable && !result.claudeMdUnwritable &&
         !(m.memoryIndexPruned || m.legacyDetailRemoved)) {
       lines.push('[code-graph] Nothing to unadopt');
     }