claude-code-memory-explorer 0.11.0 → 0.12.0

package/server.js

@@ -598,7 +598,7 @@ function stripContent(source) {
 const app = express();
 
 // Mounted before express.json() so a rejected request never buffers a body.
-const net = createNetGuard({ appName: 'Claude Code Memory' });
+const net = createNetGuard({ appName: 'Memory Diagnoser' });
 app.use(net.hostGuard);
 app.use(net.frameGuard);
 app.use(net.originGuard);
@@ -608,7 +608,7 @@ app.use(express.static(path.join(__dirname, 'public')));
 
 app.get('/hub-config', (_req, res) => {
   res.json({
-    name: 'Claude Code Memory',
+    name: 'Memory Diagnoser',
     icon: 'brain',
     description: 'Explore Claude Code memory sources',
     enabled: !!process.env.CLAUDE_HUB,
@@ -711,78 +711,81 @@ const ANALYSIS_SCHEMA = {
       items: {
         type: 'object',
         properties: {
-          kind: { type: 'string', enum: ['duplicate', 'contradiction', 'promote', 'merge', 'stale', 'invalidate', 'quality'] },
+          kind: { type: 'string', enum: ['duplicate', 'contradiction', 'promote', 'merge', 'stale', 'invalidate', 'quality', 'override', 'shadow', 'demote'] },
           severity: { type: 'string', enum: ['high', 'med', 'low'] },
+          scope: { type: 'string', enum: ['user', 'project', 'cross'] },
           title: { type: 'string' },
           detail: { type: 'string' },
           files: { type: 'array', items: { type: 'string' } },
           suggestion: { type: 'string' },
           evidence: { type: 'string' },
         },
-        required: ['kind', 'severity', 'title', 'detail', 'files', 'suggestion'],
+        required: ['kind', 'severity', 'scope', 'title', 'detail', 'files', 'suggestion'],
       },
     },
   },
   required: ['summary', 'findings'],
 };
 
-// Generous: the run fans out one verification subagent per audited file.
-const ANALYZE_TIMEOUT_MS = 600_000;
+// Analysis state lives in one file per project under ~/.claude/memory-analysis/,
+// named by the same path encoding Claude Code uses for its projects dir. Disk is the
+// single source of truth — in-flight runs are persisted as `pending` entries so they
+// survive page reloads and are visible to other server instances (hub + standalone).
+const ANALYSIS_DIR = path.join(CLAUDE_DIR, 'memory-analysis');
 
-// Analysis results keyed by project path — switching projects keeps each project's
-// last result. Completed runs are persisted to disk so they survive server restarts.
-const ANALYSIS_STORE = path.join(CLAUDE_DIR, 'claude-code-memory-analysis.json');
-const analysisStates = new Map();
-
-const EMPTY_ANALYSIS = { running: false, result: null, error: null, hash: null, ts: null, ids: null, runs: [] };
+const EMPTY_ANALYSIS = { pending: [], result: null, error: null, hash: null, ts: null, ids: null, runs: [], dismissed: [] };
 const MAX_ANALYSIS_RUNS = 10;
 
-function hydrateAnalysisEntry(st) {
-  const loaded = { ...EMPTY_ANALYSIS, ...st, running: false };
-  // Migrate pre-runs entries: the stored latest result becomes the first history run.
-  if (loaded.result && !(loaded.runs || []).length)
-    loaded.runs = [{ result: loaded.result, ts: loaded.ts, hash: loaded.hash, ids: loaded.ids }];
-  return loaded;
+// Findings about the user-level CLAUDE.md are shared across projects: they live in
+// their own entry so any project's view (and dismissals) sees the same audit.
+// The sentinel contains ':' mid-string, which encodeProjectPath output never keeps,
+// so it cannot collide with a real project file.
+const USER_SCOPE = '::user::';
+
+function analysisFile(project) {
+  if (project === USER_SCOPE) return path.join(ANALYSIS_DIR, 'user-scope.json');
+  return path.join(ANALYSIS_DIR, `${encodeProjectPath(project)}.json`);
 }
 
-let analysisStoreCache = null; // { mtimeMs, data } — reparse only when the shared file changes
-function readAnalysisStore() {
-  try {
-    const { mtimeMs } = fs.statSync(ANALYSIS_STORE);
-    if (analysisStoreCache?.mtimeMs !== mtimeMs) {
-      analysisStoreCache = { mtimeMs, data: JSON.parse(fs.readFileSync(ANALYSIS_STORE, 'utf-8')) };
-    }
-    return analysisStoreCache.data;
-  } catch {
-    return {}; // no store yet, or unreadable
-  }
+// A pending entry whose server died mid-run would otherwise show as running forever.
+// Instead of deleting it (losing the trace), mark it stalled: the UI stops spinning
+// but the entry survives — if its run ever completes, the completion handler still
+// removes it by id and the result surfaces. Runs are never killed, so stalled is a
+// hint ("probably orphaned by a server restart"), not a verdict.
+const PENDING_STALL_MS = 1_800_000;
+function markStalePending(pending) {
+  const cutoff = Date.now() - PENDING_STALL_MS;
+  return (pending || []).map((p) => (p.startedAt > cutoff ? p : { ...p, stalled: true }));
 }
 
-// The store file is shared between server instances (hub + standalone), so disk is
-// the source of truth whenever this instance has no run in flight for the project.
 function getAnalysisState(project) {
-  const cur = analysisStates.get(project);
-  if (cur?.running) return cur;
-  const st = readAnalysisStore()[project];
-  if (!st) {
-    analysisStates.delete(project);
-    return EMPTY_ANALYSIS;
+  let st = null;
+  try {
+    st = JSON.parse(fs.readFileSync(analysisFile(project), 'utf-8'));
+  } catch {
+    return { ...EMPTY_ANALYSIS };
   }
-  const loaded = hydrateAnalysisEntry(st);
-  analysisStates.set(project, loaded);
+  const loaded = { ...EMPTY_ANALYSIS, ...st };
+  loaded.pending = markStalePending(loaded.pending);
+  // result/ts/hash/ids are a projection of the newest run — derived here so no
+  // writer can persist them out of sync with the runs history.
+  const latest = (loaded.runs || [])[0];
+  loaded.result = latest?.result || null;
+  loaded.ts = latest?.ts || null;
+  loaded.hash = latest?.hash || null;
+  loaded.ids = latest ? latest.ids : null;
   return loaded;
 }
 
-// Write only this project's entry, merged over what is on disk — a blind full
-// rewrite would clobber runs another instance saved since we last read.
-function saveAnalysisState(project) {
-  const disk = readAnalysisStore();
-  const st = analysisStates.get(project);
-  if (st && (st.result || st.error || (st.runs || []).length))
-    disk[project] = { result: st.result, error: st.error, hash: st.hash, ts: st.ts, ids: st.ids, runs: st.runs || [] };
-  else delete disk[project];
+function saveAnalysisState(project, st) {
+  const { pending = [], error = null, runs = [], dismissed = [] } = st;
   try {
-    fs.writeFileSync(ANALYSIS_STORE, JSON.stringify(disk), 'utf-8');
+    if (!pending.length && !error && !runs.length && !dismissed.length) {
+      fs.rmSync(analysisFile(project), { force: true });
+      return;
+    }
+    fs.mkdirSync(ANALYSIS_DIR, { recursive: true });
+    fs.writeFileSync(analysisFile(project), JSON.stringify({ pending, error, runs, dismissed }), 'utf-8');
   } catch { /* best-effort persistence */ }
 }
 
@@ -834,7 +837,39 @@ const RUBRIC_CLAUDE_MD = [
   '- Missing high-value content is also a finding: the build/test/run commands, non-obvious architecture facts, and repo-specific gotchas are exactly what the file exists to carry.',
 ].join('\n');
 
-function buildAnalyzePrompt(memSources, userClaudeMd, skillSources, agentSources, claudeMdSources) {
+// The user-level CLAUDE.md loads in every session of every project, so its rubric is
+// project-blind: rules must hold everywhere, and verification runs against the machine
+// (PATH, ~/.claude), never against whichever repo happens to be the working directory.
+const RUBRIC_CLAUDE_MD_USER = [
+  'User-level CLAUDE.md criteria (global instructions, loaded in every session of every project):',
+  '- Universality: every rule must hold on any project. Flag rules referencing one specific repo, stack, tool chain, or project path — they belong in that project\'s CLAUDE.md (kind: demote).',
+  '- Machine verification only: check that tools the file names exist on PATH (command -v / which / where) and that files, skills, or agents it references exist under ~/.claude. NEVER verify against the working directory\'s repository — it is an arbitrary project and proves nothing about a global rule.',
+  '- Self-consistency: flag sections, tags, or mnemonics that contradict or duplicate each other within the file and its imports.',
+  '- Executability: flag standards name-dropped without concrete behaviors ("follow style guide X") and rules the model cannot act on — require the 2-3 specific behaviors the user actually wants.',
+  '- Flag emphasis inflation (all-caps, NEVER/ALWAYS without stakes) and vague or no-op rules the model cannot act on.',
+  '- Preferences should carry their why: a bare prohibition gets overridden when inconvenient; a one-clause reason makes it generalize.',
+].join('\n');
+
+// The server already knows every `@import` a file makes: parseImports() carries the
+// grammar (npm scopes excluded, extension required) and resolveImport() the resolution
+// (~ = home, else relative to the importing file). Handing the reviewer that answer as
+// fact beats shipping it a prose reimplementation it would run differently each time.
+// Hard `@` imports only — markdown links are references, not inlined content.
+function importLines(src) {
+  const lines = [`PATH: ${src.path}`];
+  const resolved = [];
+  const missing = [];
+  for (const imp of parseImports(src.content).imports) {
+    const abs = resolveImport(imp, src.path);
+    if (fs.existsSync(abs)) resolved.push(abs);
+    else missing.push(`${imp} (tried ${abs})`);
+  }
+  if (resolved.length) lines.push(`IMPORTS: ${resolved.join(', ')}`);
+  if (missing.length) lines.push(`MISSING IMPORTS: ${missing.join(', ')}`);
+  return lines;
+}
+
+function buildAnalyzePrompt(memSources, skillSources, agentSources, claudeMdSources, userSrc, userAudited) {
   const fullSkills = skillSources || [];
   const fullAgent = agentSources || [];
   const fullClaudeMd = claudeMdSources || [];
@@ -843,6 +878,8 @@ function buildAnalyzePrompt(memSources, userClaudeMd, skillSources, agentSources
   if (fullSkills.length) audited.push('project skills (SKILL.md files)');
   if (fullAgent.length) audited.push('agent memory files');
   if (fullClaudeMd.length) audited.push('CLAUDE.md instruction files');
+  if (userAudited) audited.push('the user-level (global) CLAUDE.md');
+  const crossScope = userAudited && fullClaudeMd.length;
   const parts = [
     `You are auditing what shapes Claude Code behavior in this project: ${audited.join(', ')}. Find real problems; an empty findings list is a valid answer. Do not pad.`,
     '',
@@ -854,22 +891,42 @@ function buildAnalyzePrompt(memSources, userClaudeMd, skillSources, agentSources
     '- stale: content that is outdated — verified against the repo when checkable, or judged from its own text otherwise.',
     '- invalidate: a rule or memory that verification shows no longer applies at all (the thing it guards against is gone, the file/tool it references was removed, the convention is now enforced elsewhere) — suggest deleting it.',
     '- quality: content that is vague, missing its why, or unlikely to change agent behavior — reported by the reviewers against their rubrics.',
+  ];
+  if (crossScope) {
+    parts.push(
+      '- override: a project rule that contradicts a user-level rule. This is often intentional (a project legitimately specializes global preferences) — suggest making the override explicit ("overrides global X because Y"), not deleting either side.',
+      '- shadow: a project rule that restates a user-level rule near-verbatim; the project copy is the deletion candidate.',
+    );
+  }
+  if (userAudited) {
+    parts.push('- demote: a user-level rule that is specific to one project or stack and belongs in that project\'s CLAUDE.md — the inverse of promote.');
+  }
+  parts.push(
     '',
     'Rules:',
-    '- You are the orchestrator; do not review files yourself. Your working directory is the project root. For every audited file, launch the type-matched reviewer subagent via your Agent tool — "memory-reviewer" for memory and agent-memory files, "skill-reviewer" for skills, "claude-md-reviewer" for CLAUDE.md files — all in a single parallel batch. Pass each one only the file name and its full content; the reviewers carry their own criteria and verify claims against the repo.',
-    '- Your own job: merge the reviewers\' per-file findings and add the cross-file kinds (duplicate, contradiction, merge, promote) by comparing the files side by side.',
+    `- You are the orchestrator; do not review files yourself. Your working directory is the project root. For every audited file, launch the type-matched reviewer subagent via your Agent tool — "memory-reviewer" for memory and agent-memory files, "skill-reviewer" for skills, "claude-md-reviewer" for project CLAUDE.md files${userAudited ? ', "claude-md-user-reviewer" for the user-level CLAUDE.md' : ''} — all in a single parallel batch of blocking calls (never background/async agents — you must hold your final report until every reviewer has returned). Pass each one only the file name, its full content, and — for skills and CLAUDE.md files — the PATH:, IMPORTS:, and MISSING IMPORTS: lines from its block below; the reviewers carry their own criteria and verify claims against the repo${userAudited ? ' (the user-level reviewer verifies against the machine, never the repo)' : ''}.`,
+    `- Your own job: merge the reviewers' per-file findings and add the cross-file kinds (duplicate, contradiction, merge, promote${crossScope ? ', override, shadow' : ''}) by comparing the files side by side.`,
+    '- @imports are inlined content: the files on a block\'s IMPORTS: line load as part of that file. Reviewers read them, so treat what they report from an import as belonging to the importing file when you compare files side by side — a rule imported by one file and written out in another is still a duplicate. Imported files are never audited on their own; attribute every finding to the importer.',
     '- Verification is a filter: drop any finding a reviewer\'s claim checks disproved, and never report "likely outdated" for a claim a reviewer confirmed still HOLDS. Record what was checked in the finding\'s "evidence" field (one sentence, internal bookkeeping — it is not shown to the user). Omit "evidence" for judgment-only findings.',
-    '- files: the exact file names involved as listed below (e.g. feedback_foo.md, MEMORY.md, or a skill name like my-skill).',
+    '- files: the exact file names involved as listed below (e.g. feedback_foo.md, MEMORY.md, or a skill name like my-skill). Bare names only — never append scope markers like "(user)"; scope is carried by the scope field.',
+    '- scope: "user" if the finding only cites the user-level CLAUDE.md (demote findings are always "user"); "cross" if it cites both the user-level file and any project-side file (override, shadow, and promote findings are "cross"); "project" for everything else.',
     '- suggestion: one actionable sentence (what to merge, delete, rewrite, or promote).',
     '- severity: high = actively harmful (contradictions, wrong guidance), med = wasted context or confusion, low = polish.',
     '- summary: 1-2 sentences on the overall health of this set.',
+    // The Sonnet orchestrator has been observed serializing findings as XML-ish text
+    // inside "summary" (failing schema validation), then "probing" with placeholder
+    // payloads until one passed — losing the real report. Spell the output contract out.
+    '- Final structured output: every finding goes as an object in the top-level "findings" array; "summary" is a short plain string. Never embed findings inside the summary text, never use XML-style tags in any field, and never submit placeholder or probe output (e.g. "Test", or a truncated findings list) just to pass validation. If your output is rejected for a schema mismatch, resubmit the SAME complete set of findings as valid JSON matching the schema — do not shrink, drop, or simplify it.',
     '',
-    'GLOBAL CLAUDE.md (reference only, do not audit it):',
-    '<<<',
-    userClaudeMd || '(none)',
-    '>>>',
-    '',
-  ];
+  );
+  if (userAudited) {
+    parts.push('USER CLAUDE.MD (audit this with claude-md-user-reviewer):', `=== FILE (user): ${userSrc.name} ===`, ...importLines(userSrc), userSrc.content, '');
+  } else {
+    parts.push(
+      'GLOBAL CLAUDE.md (reference only, do not audit it):',
+      ...(userSrc ? importLines(userSrc).slice(1).map((l) => `${l} — inlined into the global file; read these before judging a rule missing from it`) : []),
+      '<<<', userSrc?.content || '(none)', '>>>', '');
+  }
   if (memSources.length) {
     parts.push('MEMORY FILES:');
     for (const s of memSources) {
@@ -879,7 +936,7 @@ function buildAnalyzePrompt(memSources, userClaudeMd, skillSources, agentSources
   if (fullSkills.length) {
     parts.push('PROJECT SKILLS (audit these):');
     for (const s of fullSkills) {
-      parts.push(`=== SKILL: ${s.name} ===`, s.content, '');
+      parts.push(`=== SKILL: ${s.name} ===`, ...importLines(s), s.content, '');
     }
   }
   if (fullAgent.length) {
@@ -891,7 +948,7 @@ function buildAnalyzePrompt(memSources, userClaudeMd, skillSources, agentSources
   if (fullClaudeMd.length) {
     parts.push('CLAUDE.MD FILES (audit these):');
     for (const s of fullClaudeMd) {
-      parts.push(`=== FILE (${s.scope}): ${s.name} ===`, s.content, '');
+      parts.push(`=== FILE (${s.scope}): ${s.name} ===`, ...importLines(s), s.content, '');
     }
   }
   return parts.join('\n');
@@ -904,8 +961,18 @@ const ANALYSIS_MODELS = new Set(['sonnet', 'opus', 'fable']);
 // agent's system prompt — the parent orchestrator only passes file name + content.
 const REVIEWER_COMMON = [
   'You review exactly one file that shapes Claude Code behavior; the parent passes its name and full content.',
-  'Verify before judging: for every claim that references the repository in your working directory — a file, directory, command, script, flag, or path — check whether it still holds with your read-only tools. Never call something "likely stale" when you can check it.',
+  'Verify before judging: for every claim that references the repository in your working directory — a file, directory, command, script, flag, or path — check whether it still holds with your read-only tools. For tools the file expects on the machine, check existence with `command -v` / `which` / `where` (the only Bash commands you may run). Never call something "likely stale" when you can check it.',
   'Also judge whether the content is still needed at all: if the thing it guards against is gone (the tool was removed, the convention is enforced elsewhere, the referenced file no longer exists), say so explicitly.',
+  'A check you could not run is not evidence of absence. If a probe is denied by permissions or errors out, report that claim as UNCHECKED and say why — never turn a failed check into a stale or invalidate finding.',
+];
+
+// The user reviewer swaps repo verification for machine verification — the working
+// directory is an arbitrary project and must not influence a global-file audit.
+const REVIEWER_COMMON_USER = [
+  'You review the user-level (global) CLAUDE.md that loads in every session of every project; the parent passes its name and full content.',
+  'Verify before judging, against the machine only: check tools the file names with `command -v` / `which` / `where` (the only Bash commands you may run), and check files, skills, or agents it references under ~/.claude with your read tools. NEVER read or judge against the repository in your working directory — it is one arbitrary project and proves nothing about a global rule.',
+  'Also judge whether the content is still needed at all: if the tool it references is gone from the machine or the file it points to no longer exists, say so explicitly.',
+  'A check you could not run is not evidence of absence. If a probe is denied by permissions or errors out, report that claim as UNCHECKED and say why — never turn a failed check into a stale or invalidate finding.',
 ];
 
 const REVIEWER_REPORT = [
@@ -914,11 +981,27 @@ const REVIEWER_REPORT = [
   '2. FINDINGS: candidate findings for this file only (kind: stale, invalidate, or quality; severity high/med/low; title; detail; one-sentence fix). An empty list is a valid answer — do not pad.',
 ];
 
-function reviewerAgent(description, rubric) {
+// `@path/to/file.md` in a CLAUDE.md or a skill is an import: Claude Code inlines the
+// target's content where the token sits. A reviewer that judges only the text in front
+// of it reads an import as a dangling reference and never sees the rules the file
+// actually loads. `importLines()` resolves the graph server-side and states it as fact,
+// so the rubric only has to say what an import means. Memory files are excluded: the
+// imports they make are audited as sources in their own right.
+const RUBRIC_IMPORTS = [
+  'Import notation (@path):',
+  '- The IMPORTS: line of your file block lists absolute paths Claude Code inlines into this file at load time. Read each one and judge its content against every criterion above as part of this file — including imports of imports. Duplication between the file and its own import, contradictions across its imports, and bloat pulled in through an import all count against the importing file.',
+  '- An @path token is an import, never a broken link or an unexplained reference: do not flag the pointer itself as vague or undefined. Anything on the MISSING IMPORTS: line resolves to nothing, and is the only missing-import finding to report (kind: stale).',
+].join('\n');
+
+// `rubric` takes one rubric constant or a list of them, so a reviewer can stack the
+// shared import rubric on top of its per-type one without a second parameter.
+function reviewerAgent(description, rubric, common = REVIEWER_COMMON) {
   return {
     description,
-    prompt: [REVIEWER_COMMON.join('\n'), RUBRIC_CORE, rubric, REVIEWER_REPORT.join('\n')].join('\n\n'),
-    tools: ['Read', 'Grep', 'Glob'],
+    prompt: [common.join('\n'), RUBRIC_CORE, ...[].concat(rubric), REVIEWER_REPORT.join('\n')].join('\n\n'),
+    // Bash is permission-scoped to command -v / which / where by the spawn's
+    // --allowedTools — anything else the reviewer tries is auto-denied in -p mode.
+    tools: ['Read', 'Grep', 'Glob', 'Bash'],
   };
 }
 
@@ -929,18 +1012,28 @@ const ANALYSIS_AGENTS = {
   ),
   'skill-reviewer': reviewerAgent(
     'Reviews and verifies one SKILL.md file against the skill rubric and the repository. One per skill, in parallel.',
-    RUBRIC_SKILL,
+    [RUBRIC_SKILL, RUBRIC_IMPORTS],
   ),
   'claude-md-reviewer': reviewerAgent(
     'Reviews and verifies one CLAUDE.md instruction file against the CLAUDE.md rubric and the repository. One per file, in parallel.',
-    RUBRIC_CLAUDE_MD,
+    [RUBRIC_CLAUDE_MD, RUBRIC_IMPORTS],
+  ),
+  'claude-md-user-reviewer': reviewerAgent(
+    'Reviews and verifies the user-level (global) CLAUDE.md against the user rubric, PATH, and ~/.claude — never against the working repository.',
+    [RUBRIC_CLAUDE_MD_USER, RUBRIC_IMPORTS],
+    REVIEWER_COMMON_USER,
   ),
 };
 
+// Tool-existence checks are the only Bash the reviewers get; everything else
+// stays auto-denied by headless mode's default permissions.
+const ANALYSIS_ALLOWED_TOOLS = ['Bash(command -v:*)', 'Bash(which:*)', 'Bash(where:*)'];
+
 function runClaudeAnalysis(prompt, model, cwd) {
   return new Promise((resolve) => {
     const args = ['-p', '--output-format', 'json', '--json-schema', JSON.stringify(ANALYSIS_SCHEMA)];
     args.push('--agents', JSON.stringify(ANALYSIS_AGENTS));
+    args.push('--allowedTools', ...ANALYSIS_ALLOWED_TOOLS);
     if (model) args.push('--model', model);
     let child;
     try {
@@ -953,8 +1046,9 @@ function runClaudeAnalysis(prompt, model, cwd) {
     let out = '';
     let err = '';
     let done = false;
-    const finish = (r) => { if (done) return; done = true; clearTimeout(timer); resolve(r); };
-    const timer = setTimeout(() => { child.kill('SIGKILL'); finish({ ok: false, error: 'Claude Code timed out' }); }, ANALYZE_TIMEOUT_MS);
+    // No timeout: a long run is never killed — it runs until claude exits on its
+    // own. Past PENDING_STALL_MS the UI just shows it as stalled instead of spinning.
+    const finish = (r) => { if (done) return; done = true; resolve(r); };
     child.stdout.on('data', (d) => { out += d; });
     child.stderr.on('data', (d) => { err += d; });
     child.on('error', (e) => finish({ ok: false, error: `claude not found — is Claude Code installed? (${e.message})` }));
@@ -962,7 +1056,15 @@ function runClaudeAnalysis(prompt, model, cwd) {
       try {
         const envelope = JSON.parse(out);
         if (envelope.is_error) return finish({ ok: false, error: String(envelope.result || 'Claude Code reported an error') });
-        finish({ ok: true, data: envelope.structured_output, costUsd: envelope.total_cost_usd, durationMs: envelope.duration_ms });
+        // A run can exit clean without structured_output (schema retries exhausted,
+        // truncated stdout). Spreading that absence downstream yields an empty
+        // findings list, which the UI cannot tell apart from a genuine all-clear —
+        // so treat a missing payload as a failure rather than as "no problems".
+        const data = envelope.structured_output;
+        if (!data || !Array.isArray(data.findings)) {
+          return finish({ ok: false, error: 'Claude Code returned no structured output — the audit did not complete, so no result is being shown.' });
+        }
+        finish({ ok: true, data, costUsd: envelope.total_cost_usd, durationMs: envelope.duration_ms });
       } catch {
         finish({ ok: false, error: `Claude Code returned an invalid JSON envelope${err ? `: ${err.slice(0, 300)}` : ''}` });
       }
@@ -979,7 +1081,7 @@ function analyzableSources(stack) {
     (s) =>
       s.scope === 'memory' ||
       s.scope === 'agent-memory' ||
-      ((s.scope === 'skill' || CLAUDE_MD_SCOPES.has(s.scope)) && !s.parentId),
+      ((s.scope === 'skill' || s.scope === 'user' || CLAUDE_MD_SCOPES.has(s.scope)) && !s.parentId),
   );
 }
 
@@ -1001,98 +1103,163 @@ function scopeDescription(selected) {
   const skl = n((s) => s.scope === 'skill');
   const agt = n((s) => s.scope === 'agent-memory');
   const cmd = n((s) => CLAUDE_MD_SCOPES.has(s.scope));
+  const usr = n((s) => s.scope === 'user');
   if (mem) parts.push(`${mem} memory`);
   if (skl) parts.push(`${skl} skill${skl === 1 ? '' : 's'}`);
   if (agt) parts.push(`${agt} agent`);
   if (cmd) parts.push(`${cmd} CLAUDE.md`);
+  if (usr) parts.push('user CLAUDE.md');
   return parts.join(' + ');
 }
 
 app.get('/api/memory/analysis', (_req, res) => {
   const st = getAnalysisState(currentProjectPath);
+  const running = st.pending.some((p) => !p.stalled);
+  // The shared user-scope entry rides along on every project's payload; its
+  // staleness tracks the user CLAUDE.md itself, independent of the project.
+  const us = getAnalysisState(USER_SCOPE);
   // Staleness needs a full stack scan + content hash — skip it while a run is in
   // flight (the client polls every 2.5s and stale is meaningless mid-run anyway).
   let stale = false;
-  if (!st.running && st.result) {
-    const selected = selectAnalysisSources(getStack(), st.ids);
-    const hash = selected.length ? memoryContentHash(selected) : null;
-    stale = st.hash !== hash;
+  let userStale = false;
+  if (!running && (st.result || us.result)) {
+    const stack = getStack();
+    if (st.result) {
+      const selected = selectAnalysisSources(stack, st.ids);
+      const hash = selected.length ? memoryContentHash(selected) : null;
+      stale = st.hash !== hash;
+    }
+    if (us.result) {
+      const userSrc = stack.find((s) => s.id === 'user-claude-md');
+      userStale = us.hash !== (userSrc ? memoryContentHash([userSrc]) : null);
+    }
   }
   res.json({
-    running: st.running,
+    pending: st.pending,
     result: st.result,
     error: st.error,
     ts: st.ts,
     stale,
     project: currentProjectPath,
     runs: st.runs || [],
+    dismissed: st.dismissed || [],
+    user: { result: us.result, ts: us.ts, stale: userStale, runs: us.runs || [], dismissed: us.dismissed || [] },
   });
 });
 
+// scope:'user' targets the shared user-scope entry, so the action holds across
+// projects; anything else targets the current project's entry.
+function analysisTarget(req) {
+  return req.body?.scope === 'user' ? USER_SCOPE : currentProjectPath;
+}
+
 app.post('/api/memory/analysis/delete-run', (req, res) => {
-  const st = getAnalysisState(currentProjectPath);
-  if (st.running) return res.status(409).json({ error: 'analysis running' });
+  const target = analysisTarget(req);
+  const st = getAnalysisState(target);
   const ts = req.body?.ts;
   const runs = (st.runs || []).filter((run) => run.ts !== ts);
   if (runs.length === (st.runs || []).length) return res.status(404).json({ error: 'run not found' });
-  const latest = runs[0] || null;
-  analysisStates.set(currentProjectPath, {
-    ...st,
-    result: latest?.result || null,
-    ts: latest?.ts || null,
-    hash: latest?.hash || null,
-    ids: latest ? latest.ids : null,
-    error: null,
-    runs,
-  });
-  saveAnalysisState(currentProjectPath);
+  saveAnalysisState(target, { ...st, error: null, runs });
   res.json({ ok: true, runs: runs.length });
 });
 
+// Dismissals persist per project so they survive reloads and re-runs.
+// Body: {key} adds, {all:true} clears.
+app.post('/api/memory/analysis/dismiss', (req, res) => {
+  const target = analysisTarget(req);
+  const st = getAnalysisState(target);
+  const set = new Set(st.dismissed || []);
+  if (req.body?.all) set.clear();
+  else {
+    const key = req.body?.key;
+    if (typeof key !== 'string' || !key) return res.status(400).json({ error: 'key required' });
+    set.add(key);
+  }
+  saveAnalysisState(target, { ...st, dismissed: [...set] });
+  res.json({ ok: true, dismissed: [...set] });
+});
+
 app.post('/api/memory/analyze', (req, res) => {
   const prev = getAnalysisState(currentProjectPath);
-  if (prev.running) return res.status(409).json({ error: 'analysis already running' });
   const stack = getStack();
   const ids = req.body?.ids;
   const selected = selectAnalysisSources(stack, ids);
   if (!selected.length) return res.status(404).json({ error: 'nothing to analyze for this scope' });
   const hash = memoryContentHash(selected);
-  if (!req.body?.force && prev.result && prev.hash === hash) {
-    return res.json({ running: false, cached: true });
+  // The user CLAUDE.md is audited when picked; otherwise it stays reference
+  // context for the 'promote' kind.
+  const userSelected = selected.find((s) => s.scope === 'user');
+  // A user-only run's result lives in the shared user-scope entry, so that is
+  // where its cache hit must be checked.
+  const userOnly = !!userSelected && selected.length === 1;
+  const cacheEntry = userOnly ? getAnalysisState(USER_SCOPE) : prev;
+  if (!req.body?.force && cacheEntry.result && cacheEntry.hash === hash) {
+    return res.json({ cached: true });
   }
   const memSources = selected.filter((s) => s.scope === 'memory');
   const skills = selected.filter((s) => s.scope === 'skill');
   const agentSources = selected.filter((s) => s.scope === 'agent-memory');
   const claudeMdSources = selected.filter((s) => CLAUDE_MD_SCOPES.has(s.scope));
-  // The global CLAUDE.md is reference context for the 'promote' kind (never audited itself).
-  const userClaudeMd = stack.find((s) => s.id === 'user-claude-md');
-  const prompt = buildAnalyzePrompt(memSources, userClaudeMd?.content, skills, agentSources, claudeMdSources);
+  const userSrc = userSelected || stack.find((s) => s.id === 'user-claude-md');
+  const prompt = buildAnalyzePrompt(memSources, skills, agentSources, claudeMdSources, userSrc, !!userSelected);
   const stateIds = Array.isArray(ids) && ids.length ? ids : null;
   const model = ANALYSIS_MODELS.has(req.body?.model) ? req.body.model : null;
   // Capture the project now — the user may switch projects while the run is in flight,
   // and the result must land under the project it was computed for.
   const project = currentProjectPath;
-  const prevRuns = prev.runs || [];
-  analysisStates.set(project, { running: true, result: null, error: null, hash, ts: null, ids: stateIds, runs: prevRuns });
-  runClaudeAnalysis(prompt, model, project).then((r) => {
+  const runId = crypto.randomUUID();
+  const scopeDesc = scopeDescription(selected);
+  saveAnalysisState(project, {
+    ...prev,
+    // Starting a fresh run retires stalled leftovers — the user has moved on.
+    pending: [...prev.pending.filter((p) => !p.stalled), { id: runId, startedAt: Date.now(), model, scopeDesc }],
+  });
+  const userHash = userSelected ? memoryContentHash([userSelected]) : null;
+  // Snapshot the audited files into the run — the stack changes over time, so
+  // historical runs must not re-derive their scope from the live stack. The user
+  // file is owned by the user-scope entry's snapshot, not the project's.
+  // Snapshotting up front also keeps `selected` (full file contents) out of the
+  // completion closure, which can live for hours on a run that never returns.
+  const audited = selected.filter((s) => s.scope !== 'user').map((s) => ({ id: s.id, name: s.name, scope: s.scope, lines: s.lines }));
+  const userAudited = userSelected ? [{ id: userSelected.id, name: userSelected.name, scope: 'user', lines: userSelected.lines }] : null;
+  const userId = userSelected?.id || null;
+  // Prepend a run to an entry's history, newest first, capped.
+  const withRun = (cur, run) => [run, ...(cur.runs || [])].slice(0, MAX_ANALYSIS_RUNS);
+  runClaudeAnalysis(prompt, model, userOnly ? os.homedir() : project).then((r) => {
     const ts = Date.now();
-    const result = r.ok ? { ...r.data, costUsd: r.costUsd, durationMs: r.durationMs, scopeDesc: scopeDescription(selected), model } : null;
-    // Another instance may have added runs while this one was in flight — merge by ts.
-    const diskRuns = readAnalysisStore()[project]?.runs || [];
-    const baseRuns = [...new Map([...prevRuns, ...diskRuns].map((run) => [run.ts, run])).values()].sort((a, b) => b.ts - a.ts);
-    const runs = (result ? [{ result, ts, hash, ids: stateIds }, ...baseRuns] : baseRuns).slice(0, MAX_ANALYSIS_RUNS);
-    analysisStates.set(project, {
-      running: false,
-      result,
+    let result = r.ok ? { ...r.data, costUsd: r.costUsd, durationMs: r.durationMs, scopeDesc, model } : null;
+    if (result) {
+      // Reviewers sometimes copy the prompt's scope marker into file names
+      // ("CLAUDE.md (user)") — canonicalize before persisting so no consumer sees it.
+      const findings = (result.findings || []).map((f) => ({ ...f, files: (f.files || []).map((n) => n.replace(/\s*\((user|project|local)\)$/, '')) }));
+      result = { ...result, findings };
+    }
+    // Findings about the user CLAUDE.md alone are shared across projects: split them
+    // into the user-scope entry; project and cross findings stay with the project.
+    if (result && userId) {
+      const all = result.findings;
+      const uCur = getAnalysisState(USER_SCOPE);
+      const uRun = {
+        result: { ...result, findings: all.filter((f) => f.scope === 'user'), scopeDesc: 'user CLAUDE.md' },
+        ts,
+        hash: userHash,
+        ids: [userId],
+        audited: userAudited,
+      };
+      saveAnalysisState(USER_SCOPE, { ...uCur, runs: withRun(uCur, uRun) });
+      result = { ...result, findings: all.filter((f) => f.scope !== 'user') };
+    }
+    // Re-read from disk — parallel runs or another instance may have finished meanwhile.
+    const cur = getAnalysisState(project);
+    const runs = result && !userOnly ? withRun(cur, { result, ts, hash, ids: stateIds, audited }) : cur.runs || [];
+    saveAnalysisState(project, {
+      ...cur,
+      pending: cur.pending.filter((p) => p.id !== runId),
       error: r.ok ? null : r.error,
-      hash,
-      ts,
-      ids: stateIds,
       runs,
     });
-    saveAnalysisState(project);
   });
-  res.status(202).json({ running: true });
+  res.status(202).json({ ok: true });
 });
 
 // #endregion ANALYZER
@@ -1121,7 +1288,17 @@ app.get('/api/summary', (_req, res) => {
   const stack = getStack();
   // Memory topic files load on demand like skill bodies — only the startup MEMORY.md
   // index is standing cost, so ondemand memory-scope files stay out of the footprint.
-  const sources = stack.filter(s => s.scope !== 'skill' && s.load !== 'link'
+  // Nested CLAUDE.md files (load:'tree') load progressively when Claude works in their
+  // directory, so they and their import chains are not standing cost either.
+  const treeIds = new Set(stack.filter(s => s.load === 'tree').map(s => s.id));
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const s of stack) {
+      if (s.parentId && treeIds.has(s.parentId) && !treeIds.has(s.id)) { treeIds.add(s.id); grew = true; }
+    }
+  }
+  const sources = stack.filter(s => s.scope !== 'skill' && s.load !== 'link' && !treeIds.has(s.id)
     && !((s.scope === 'memory' || s.scope === 'agent-memory') && s.load === 'ondemand'));
   const totalFiles = sources.length;
   const totalLines = sources.reduce((s, f) => s + (f.lines || 0), 0);
@@ -1135,7 +1312,8 @@ app.get('/api/summary', (_req, res) => {
   const scopeChars = {};
   for (const f of sources) scopeChars[f.scope] = (scopeChars[f.scope] || 0) + (f.chars || 0);
   const totalChars = sources.reduce((s, f) => s + (f.chars || 0), 0) + skillDesc.chars;
-  res.json({ totalFiles, totalLines, totalBytes, totalChars, scopeChars, skillDesc, alwaysLoaded, conditional, onDemand });
+  // ids: which sources make up the footprint, so the client can highlight them
+  res.json({ totalFiles, totalLines, totalBytes, totalChars, scopeChars, skillDesc, alwaysLoaded, conditional, onDemand, ids: sources.map(s => s.id) });
 });
 
 app.get('/api/stack', (_req, res) => {
@@ -1207,7 +1385,7 @@ app.get('/api/imports', (req, res) => {
 // #region STARTUP
 
 const onReady = (port) => {
-  console.log(`Claude Code Memory running at http://localhost:${port}`);
+  console.log(`Memory Diagnoser running at http://localhost:${port}`);
   console.log(`Project: ${currentProjectPath}`);
   const warning = net.exposureWarning();
   if (warning) console.log(warning);