claude-memory-admin 1.10.0 → 1.10.2

package/src/agents.mjs

@@ -1,9 +1,12 @@
-// User-scope subagent definitions: ~/.claude/agents/*.md.
+// Subagent definitions: agents/*.md, in the user scope and in each repository.
 //
-// Not to be confused with ~/.claude/agent-memory (src/stores.mjs), which is what
-// those agents *remember*. This module is about what they *are*: a markdown file
-// whose frontmatter names the agent and, optionally, pins the model and effort
-// it runs at. Pinning a summariser to Haiku while a reviewer stays on Opus is the
+// Not to be confused with agent-memory (src/stores.mjs), which is what those
+// agents *remember*. This module is about what they *are*: a markdown file whose
+// frontmatter names the agent and, optionally, pins the model and effort it runs
+// at, and declares with `memory:` whether it keeps a memory directory at all.
+// That last field is the link between the two: a store exists because some file
+// here asked for it, and a store no file asks for any more is a store nothing
+// loads. Pinning a summariser to Haiku while a reviewer stays on Opus is the
 // finer-grained version of the CLAUDE_CODE_SUBAGENT_MODEL switch in src/cost.mjs,
 // which - worth remembering when both are set - outranks everything here.
 //
@@ -12,13 +15,21 @@
 // somebody wrote on purpose, and this tool has no view on it.
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 
+import { canonicalPath, configPath } from './config.mjs';
 import { parseFrontmatter } from './parse.mjs';
 import { writeFileAtomic } from './mutate.mjs';
 
-export const AGENTS_DIR = path.join(os.homedir(), '.claude', 'agents');
+export const AGENTS_DIR = configPath('agents');
+export const PROJECT_AGENTS_DIR = path.join('.claude', 'agents');
+
+/** The scopes `memory:` accepts, and the store kind each one produces. */
+export const MEMORY_SCOPES = {
+  user: 'agent-user',
+  project: 'agent-project',
+  local: 'agent-local',
+};
 
 const MODEL_ID = /^claude-[A-Za-z0-9._[\]-]+$/;
 
@@ -55,6 +66,7 @@ export const AGENT_PROBLEM_SEVERITY = {
   'name-mismatch': 'warn',
   'unknown-model': 'warn',
   'unknown-effort': 'warn',
+  'unknown-memory-scope': 'warn',
 };
 
 function known(field, value) {
@@ -92,9 +104,9 @@ export function safeAgentPath(dir, file) {
   return full;
 }
 
-function describeAgent(dir, file) {
+function describeAgent(dir, file, { scope = 'user', writable = true, projectPath = null } = {}) {
   const full = path.join(dir, file);
-  const stem = file.replace(/\.md$/, '');
+  const stem = path.basename(file).replace(/\.md$/, '');
 
   let text;
   try {
@@ -102,11 +114,15 @@ function describeAgent(dir, file) {
   } catch (err) {
     return {
       file,
+      scope,
+      writable: false,
+      projectPath,
       name: stem,
       description: '',
       tools: '',
       model: null,
       effort: null,
+      memory: null,
       bytes: 0,
       problems: [{ kind: 'no-frontmatter', severity: 'bad', detail: err.message }],
     };
@@ -117,6 +133,7 @@ function describeAgent(dir, file) {
   const name = scalar('name') || stem;
   const model = scalar('model') || null;
   const effort = scalar('effort') || null;
+  const memory = scalar('memory') || null;
 
   const problems = [];
   const flag = (kind, detail) => problems.push({ kind, severity: AGENT_PROBLEM_SEVERITY[kind], detail });
@@ -129,26 +146,39 @@ function describeAgent(dir, file) {
     if (scalar('name') && scalar('name') !== stem) flag('name-mismatch', `Named "${scalar('name')}" in a file called "${file}".`);
     if (model && !known('model', model)) flag('unknown-model', `model: ${model} is neither an alias nor a claude- model name.`);
     if (effort && !known('effort', effort)) flag('unknown-effort', `effort: ${effort} is not one of low, medium, high, xhigh or max.`);
+    if (memory && !Object.prototype.hasOwnProperty.call(MEMORY_SCOPES, memory)) {
+      flag('unknown-memory-scope', `memory: ${memory} is not one of user, project or local, so this agent keeps no memory directory.`);
+    }
   }
 
   return {
     file,
+    scope,
+    // Only a plain .md at the top of the user directory is rewritable: writes go
+    // through safeAgentPath, which takes a bare basename, and nothing here has
+    // any business editing a file inside somebody's repository.
+    writable: writable && file === path.basename(file),
+    projectPath,
     name,
     description: scalar('description'),
     tools: scalar('tools'),
     model,
     effort,
+    memory: memory && Object.prototype.hasOwnProperty.call(MEMORY_SCOPES, memory) ? memory : null,
+    memoryRaw: memory,
     bytes: Buffer.byteLength(text, 'utf8'),
     problems,
   };
 }
 
 /**
- * Every user-scope agent definition. A directory that is not there is the
- * ordinary state of a machine whose owner has never written one, not a failure,
- * so it answers with an empty list.
+ * Every .md under an agents directory, including the subfolders people use to
+ * group them. Claude Code scans both agent roots recursively and identifies an
+ * agent by its `name` rather than by where the file sits, so a scan that stopped
+ * at the top level would miss agents that are running.
  */
-export function listAgents({ dir = AGENTS_DIR } = {}) {
+function agentFiles(dir, prefix = '', depth = 0) {
+  if (depth > 4) return [];
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -156,12 +186,54 @@ export function listAgents({ dir = AGENTS_DIR } = {}) {
     return [];
   }
 
-  return entries
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('.'))
-    .map((entry) => describeAgent(dir, entry.name))
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) files.push(...agentFiles(path.join(dir, entry.name), rel, depth + 1));
+    else if (entry.isFile() && entry.name.endsWith('.md')) files.push(rel);
+  }
+  return files;
+}
+
+/**
+ * Every user-scope agent definition. A directory that is not there is the
+ * ordinary state of a machine whose owner has never written one, not a failure,
+ * so it answers with an empty list.
+ */
+export function listAgents({ dir = AGENTS_DIR } = {}) {
+  return agentFiles(dir)
+    .map((file) => describeAgent(dir, file, { scope: 'user', writable: true }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Project-scope definitions, from <repo>/.claude/agents. These are read and
+ * never written: they belong to a repository somebody else may share, and an
+ * agent with `memory: project` is normally defined here rather than in the user
+ * scope, so leaving them out would orphan the very stores this exists to explain.
+ */
+export function listProjectAgents(projectPath, { relative = PROJECT_AGENTS_DIR } = {}) {
+  if (!projectPath || !path.isAbsolute(projectPath)) return [];
+  const dir = path.join(projectPath, relative);
+  return agentFiles(dir)
+    .map((file) => describeAgent(dir, file, { scope: 'project', writable: false, projectPath }))
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/** Every definition on the machine this tool can see: user scope plus each repository. */
+export function listAllAgents({ dir = AGENTS_DIR, projectPaths = [] } = {}) {
+  const agents = listAgents({ dir });
+  const seen = new Set();
+  for (const projectPath of projectPaths) {
+    const key = canonicalPath(projectPath || '');
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    agents.push(...listProjectAgents(projectPath));
+  }
+  return agents;
+}
+
 /** Whether the directory itself exists, which is what tells an empty list from a missing one. */
 export function agentsDirExists({ dir = AGENTS_DIR } = {}) {
   try {
@@ -205,7 +277,11 @@ function insertionIndex(block) {
  * that changed, never re-emit the document from a parse of it.
  */
 export function rewriteAgentField(text, field, value) {
-  const lines = text.split('\n');
+  // Rejoin with whatever the file already used. A checkout on Windows is CRLF
+  // throughout, and splitting on \n then rejoining with it would leave every
+  // line this function did not touch ending \r\n and the one it did ending \n.
+  const eol = /\r\n/.test(text) ? '\r\n' : '\n';
+  const lines = text.split(/\r?\n/);
   if (lines[0]?.trim() !== '---') {
     throw new Error('This file has no frontmatter block, so there is nothing to set.');
   }
@@ -230,7 +306,7 @@ export function rewriteAgentField(text, field, value) {
     block[at] = `${field}: ${value}`;
   }
 
-  return [lines[0], ...block, ...lines.slice(end)].join('\n');
+  return [lines[0], ...block, ...lines.slice(end)].join(eol);
 }
 
 function normaliseAgentValue(field, value) {

package/src/checks.mjs

@@ -2,6 +2,13 @@ import path from 'node:path';
 import { parseFrontmatter } from './parse.mjs';
 
 export const VALID_TYPES = ['user', 'feedback', 'project', 'reference'];
+
+/** The scope each subagent store kind stands for, for the messages below. */
+const STORE_SCOPES = {
+  'agent-user': 'user',
+  'agent-project': 'project',
+  'agent-local': 'local',
+};
 export const EMPTY_BODY_CHARS = 40;
 export const EMPTY_INSTRUCTION_CHARS = 10;
 export const HOOK_ECHO_OVERLAP = 0.9;
@@ -218,6 +225,68 @@ export function checkNoMemoryDespiteSessions(store, memories, retention) {
   }];
 }
 
+/**
+ * A subagent store nothing declares any more.
+ *
+ * The directory only exists because some agent file once carried a `memory:`
+ * field naming this scope. Rename the agent, move it to another scope or drop
+ * the field and the directory stays exactly where it is, still holding whatever
+ * it learned, and no session will ever read it again. That is invisible on disk,
+ * which is the whole reason to say it here.
+ */
+export function checkAgentStoreOrphan(store) {
+  if (!store || !store.linkage || store.linked) return [];
+  if (store.declaredScope) return [];
+
+  return [{
+    kind: 'agent-store-orphan',
+    severity: 'warn',
+    agentName: store.agentName,
+    scope: STORE_SCOPES[store.kind] || null,
+    defined: Boolean(store.defined),
+  }];
+}
+
+/** The agent still exists, but its `memory:` names a different scope than this store. */
+export function checkAgentStoreScopeMismatch(store) {
+  if (!store || !store.linkage || store.linked) return [];
+  if (!store.declaredScope) return [];
+
+  return [{
+    kind: 'agent-store-scope-mismatch',
+    severity: 'warn',
+    agentName: store.agentName,
+    scope: STORE_SCOPES[store.kind] || null,
+    declaredScope: store.declaredScope,
+    declaredBy: store.declaredBy,
+  }];
+}
+
+/**
+ * Subagent memory is part of auto memory, so turning auto memory off turns this
+ * store off with it: the `memory:` field stops having any effect, the agent
+ * launches with no memory instructions and no file tools, and the directory can
+ * neither be read nor grow. Nothing about the files themselves shows that.
+ */
+export function checkAgentMemoryInert(store) {
+  if (!store || !store.linkage || !store.inert) return [];
+
+  return [{
+    kind: 'agent-memory-inert',
+    severity: 'warn',
+    agentName: store.agentName,
+    setBy: store.inertBy || null,
+  }];
+}
+
+export function agentStoreChecks(store) {
+  return [
+    ...checkAgentMemoryInert(store),
+    ...checkAgentStoreOrphan(store),
+    ...checkAgentStoreScopeMismatch(store),
+  ];
+}
+
 export function sessionChecks(store, memories, retention, { remembered = false, resolveOrigin = null } = {}) {
   if (!retention) return [];
   return [

package/src/config.mjs

@@ -0,0 +1,130 @@
+// Where Claude Code keeps its files, and the path primitives that answer it the
+// same way on all three platforms.
+//
+// Everything under ~/.claude - the projects root, the agent definitions, the
+// agent memory directories, the user settings file, the output styles - moves as
+// one when CLAUDE_CONFIG_DIR is set. Hardcoding the home-relative path in each
+// module meant a machine with a custom config dir opened this tool to an empty
+// list rather than to its memory, so all of them resolve through configDir()
+// instead.
+//
+// The platform is a parameter on every function here rather than a read of
+// process.platform inside it. Only one of the three platforms is ever available
+// to develop on, and behaviour that cannot be exercised from a test is behaviour
+// nobody checks: the defaults keep the call sites unchanged and the parameter is
+// what lets test/config.test.mjs assert the Windows rules from anywhere.
+
+import os from 'node:os';
+import path from 'node:path';
+
+/** The separator rules of the named platform, rather than of the host. */
+const pathFor = (platform) => (platform === 'win32' ? path.win32 : path.posix);
+
+/**
+ * Expand a leading `~/`. Claude Code documents that form for autoMemoryDirectory
+ * and it is what people type on every platform, Windows included, so it is
+ * handled before any separator rule is applied.
+ *
+ * The join goes through pathFor rather than through path directly. A caller that
+ * names a platform is naming its separator too, and the native join would answer
+ * from the host instead: a POSIX home joined under win32 comes back rooted at no
+ * drive, which isAbsolutePath then rejects for a reason the caller never asked
+ * for.
+ */
+export function expandHome(value, { home = os.homedir(), platform = process.platform } = {}) {
+  if (typeof value !== 'string') return value;
+  if (value === '~') return home;
+  if (value.startsWith('~/') || value.startsWith('~\\')) return pathFor(platform).join(home, value.slice(2));
+  return value;
+}
+
+/**
+ * Whether a path is absolute in the sense Claude Code requires: rooted, and on
+ * Windows rooted at a drive or a UNC share.
+ *
+ * path.isAbsolute is not enough on its own. Under win32 it answers true for
+ * "/foo", which has no drive and so names nothing that can be opened. Accepting
+ * it would turn a typo into a silent read of the wrong place, which is the one
+ * failure every caller here exists to prevent.
+ */
+export function isAbsolutePath(value, platform = process.platform) {
+  if (typeof value !== 'string' || !value) return false;
+  if (platform === 'win32') {
+    return /^[A-Za-z]:[\\/]/.test(value) || /^\\\\[^\\]/.test(value) || /^\/\/[^/]/.test(value);
+  }
+  return value.startsWith('/');
+}
+
+/** A path with forward slashes, which is the only separator glob syntax knows. */
+export function toPosix(value) {
+  return typeof value === 'string' ? value.replace(/\\/g, '/') : value;
+}
+
+/**
+ * A path in the form to compare two paths by, never the form to display or store.
+ *
+ * Windows and a default macOS volume are both case-insensitive, so two spellings
+ * of one directory are one directory, and a dedup set keyed on the raw string
+ * misses the duplicate. Lowercasing is only sound for the comparison: the store
+ * ids in src/stores.mjs are derived from the path as found on disk and have to
+ * stay that way, or every id on the machine changes.
+ */
+export function canonicalPath(value, platform = process.platform) {
+  if (typeof value !== 'string' || !value) return value;
+  const resolved = toPosix(path.resolve(value));
+  return platform === 'win32' || platform === 'darwin' ? resolved.toLowerCase() : resolved;
+}
+
+export const DEFAULT_CONFIG_DIR_NAME = '.claude';
+
+/**
+ * The config directory and what decided it, in the shape src/projects.mjs
+ * already uses for the memory root: a tool that silently reads somewhere other
+ * than the default is worse than one that reads nothing, so the source travels
+ * with the path.
+ *
+ * A CLAUDE_CONFIG_DIR that is not absolute is reported and not used. Claude Code
+ * would not accept it either, so falling back to the default is the honest
+ * answer - but silently is not, hence `invalid`.
+ */
+export function configSource({ env = process.env, home = os.homedir(), platform = process.platform } = {}) {
+  const fallback = pathFor(platform).join(home, DEFAULT_CONFIG_DIR_NAME);
+  const raw = typeof env.CLAUDE_CONFIG_DIR === 'string' ? env.CLAUDE_CONFIG_DIR.trim() : '';
+  if (!raw) return { path: fallback, source: 'default', raw: null, invalid: null };
+
+  const expanded = expandHome(raw, { home, platform });
+  if (!isAbsolutePath(expanded, platform)) {
+    return {
+      path: fallback,
+      source: 'default',
+      raw,
+      invalid: `CLAUDE_CONFIG_DIR "${raw}" is not an absolute or ~/ path`,
+    };
+  }
+  return { path: expanded, source: 'env', raw, invalid: null };
+}
+
+export function configDir(options = {}) {
+  return configSource(options).path;
+}
+
+/** A path inside the config directory, such as configPath('agents'). */
+export function configPath(...segments) {
+  return path.join(configDir(), ...segments);
+}
+
+/**
+ * CLAUDE_CODE_PROJECT_DIR_NAME, which fixes the <project> directory name so that
+ * every repository launched with this config dir shares one store instead of
+ * getting a slug of its own.
+ *
+ * Claude Code documents it as being set beside CLAUDE_CONFIG_DIR, and it is only
+ * honoured here on that condition: on its own it would silently redirect a
+ * default installation to a directory Claude Code is not using.
+ */
+export function fixedProjectDirName({ env = process.env } = {}) {
+  if (typeof env.CLAUDE_CONFIG_DIR !== 'string' || !env.CLAUDE_CONFIG_DIR.trim()) return null;
+  const name = typeof env.CLAUDE_CODE_PROJECT_DIR_NAME === 'string' ? env.CLAUDE_CODE_PROJECT_DIR_NAME.trim() : '';
+  if (!name || name !== path.basename(name) || name.startsWith('.')) return null;
+  return name;
+}

package/src/cost.mjs

@@ -18,9 +18,9 @@
 //                                   prompt and are untouched by it.
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 
+import { configPath } from './config.mjs';
 import { parseFrontmatter } from './parse.mjs';
 import { writeFileAtomic } from './mutate.mjs';
 import {
@@ -31,7 +31,7 @@ import {
   settingsCandidates,
 } from './settings.mjs';
 
-export const OUTPUT_STYLES_DIR = path.join(os.homedir(), '.claude', 'output-styles');
+export const OUTPUT_STYLES_DIR = configPath('output-styles');
 
 // A full model name is documented as acceptable wherever an alias is, and this
 // tool has no business deciding which ones exist. The shape is checked so a

package/src/instructions.mjs

@@ -13,8 +13,8 @@
 // would hide exactly the problem this is meant to surface.
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { canonicalPath, configDir, DEFAULT_CONFIG_DIR_NAME, expandHome, toPosix } from './config.mjs';
 import { parseFrontmatter } from './parse.mjs';
 import { estimateTokens } from './stats.mjs';
 import { lookup, settingsLayers } from './settings.mjs';
@@ -133,7 +133,7 @@ export function findImports(text) {
 }
 
 function resolveImport(spec, fromFile) {
-  if (spec.startsWith('~/')) return path.join(os.homedir(), spec.slice(2));
+  if (spec.startsWith('~/') || spec.startsWith('~\\')) return expandHome(spec);
   if (path.isAbsolute(spec)) return spec;
   // Relative to the file holding the import, not to the working directory.
   return path.resolve(path.dirname(fromFile), spec);
@@ -149,7 +149,10 @@ function resolveImport(spec, fromFile) {
 export function expandImports(rootFile, rootText, { projectDir = null } = {}) {
   const files = [];
   const problems = [];
-  const seen = new Set([rootFile]);
+  // Canonical keys: on a case-insensitive filesystem two spellings of one file
+  // are one file, and a cycle spelled differently at each hop would otherwise
+  // recurse until it hit the depth limit instead of being named as a cycle.
+  const seen = new Set([canonicalPath(rootFile)]);
   let frontier = [{ file: rootFile, text: rootText, depth: 0 }];
 
   while (frontier.length) {
@@ -162,7 +165,7 @@ export function expandImports(rootFile, rootText, { projectDir = null } = {}) {
           problems.push({ kind: 'too-deep', spec, from: current.file, file: resolved });
           continue;
         }
-        if (seen.has(resolved)) {
+        if (seen.has(canonicalPath(resolved))) {
           problems.push({ kind: 'cycle', spec, from: current.file, file: resolved });
           continue;
         }
@@ -173,7 +176,7 @@ export function expandImports(rootFile, rootText, { projectDir = null } = {}) {
           continue;
         }
 
-        seen.add(resolved);
+        seen.add(canonicalPath(resolved));
         // An import resolving outside the project is the kind Claude Code asks
         // you to approve once; a declined one then stays silently disabled.
         const external = projectDir ? path.relative(projectDir, resolved).startsWith('..') : false;
@@ -342,17 +345,34 @@ function entry(file, scope, kind, { conditional = false } = {}) {
 }
 
 /** Directories from the filesystem root down to `dir`, in load order. */
+/**
+ * Every directory from the filesystem root down to `dir`, root last.
+ *
+ * Walked with dirname rather than by splitting on the separator, because the
+ * separator alone does not describe a root: a Windows path starts at `C:\` and
+ * a UNC path at `\\server\share`, and splitting either of those produces
+ * candidates that name nothing.
+ */
 function ancestors(dir) {
-  const parts = path.resolve(dir).split(path.sep);
   const out = [];
-  for (let i = 1; i < parts.length; i++) {
-    out.push(parts.slice(0, i + 1).join(path.sep) || path.sep);
+  let current = path.resolve(dir);
+  while (true) {
+    out.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
   }
-  return out;
+  return out.reverse();
 }
 
-function globToRegExp(pattern) {
-  // Only used for claudeMdExcludes, which matches absolute paths.
+export function globToRegExp(pattern, platform = process.platform) {
+  // Only used for claudeMdExcludes, which matches absolute paths. Glob syntax
+  // knows one separator, so a Windows path has to be compared in its forward
+  // slash form or every pattern silently matches nothing - and on the two
+  // case-insensitive platforms the comparison has to ignore case for the same
+  // reason a path does.
+  const flags = platform === 'win32' || platform === 'darwin' ? 'i' : '';
+  pattern = toPosix(pattern);
   let out = '';
   for (let i = 0; i < pattern.length; i++) {
     const char = pattern[i];
@@ -362,16 +382,26 @@ function globToRegExp(pattern) {
     } else if (char === '?') out += '[^/]';
     else out += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
   }
-  return new RegExp(`^${out}$`);
+  return new RegExp(`^${out}$`, flags);
 }
 
 /**
  * Managed policy and user scope: what loads whichever project a session starts in.
  *
- * `home` is a parameter rather than a call to os.homedir() so this is a total
+ * `home` is a parameter rather than a read of the config directory so this is a total
  * function of where it is told to look, which is what makes it testable without a
  * real home directory.
  */
+/**
+ * The user-scope directory: normally the config directory, which
+ * CLAUDE_CONFIG_DIR may have moved off the home directory entirely. A `home`
+ * passed in names its own, which is what lets the tests point the user scope at
+ * a fixture.
+ */
+function userDir(home) {
+  return home ? path.join(home, DEFAULT_CONFIG_DIR_NAME) : configDir();
+}
+
 function userCandidates(home, layers) {
   const candidates = [entry(managedClaudeMd(), 'managed', 'claude-md')];
 
@@ -382,8 +412,9 @@ function userCandidates(home, layers) {
     : null;
   if (inline) candidates.push(inline);
 
-  candidates.push(entry(path.join(home, '.claude', 'CLAUDE.md'), 'user', 'claude-md'));
-  for (const file of listRuleFiles(path.join(home, '.claude', 'rules'))) {
+  const dir = userDir(home);
+  candidates.push(entry(path.join(dir, 'CLAUDE.md'), 'user', 'claude-md'));
+  for (const file of listRuleFiles(path.join(dir, 'rules'))) {
     candidates.push(ruleEntry(file, 'user'));
   }
   return candidates;
@@ -416,14 +447,14 @@ function readExcludes(layers) {
  * one cannot drift apart in what they count or what they consider broken.
  */
 function finalize(candidates, { projectDir, excludes }) {
-  const matchers = excludes.map(globToRegExp);
+  const matchers = excludes.map((pattern) => globToRegExp(pattern));
   const excluded = [];
   const loaded = [];
   const problems = [];
 
   for (const candidate of candidates.filter(Boolean)) {
     // Managed policy cannot be excluded; that is the point of managed policy.
-    if (candidate.scope !== 'managed' && matchers.some((re) => re.test(candidate.file))) {
+    if (candidate.scope !== 'managed' && matchers.some((re) => re.test(toPosix(candidate.file)))) {
       excluded.push(candidate.file);
       continue;
     }
@@ -498,7 +529,7 @@ function finalize(candidates, { projectDir, excludes }) {
  * and walking into them would bury the one finding that matters.
  */
 export function unreferencedUserFiles(home, loadedFiles) {
-  const dir = path.join(home, '.claude');
+  const dir = userDir(home);
   // Imports arrive already absolutised by resolveImport while candidates are
   // joined from `home`, so both sides are resolved before they are compared.
   const loaded = new Set(loadedFiles.map((item) => path.resolve(item.file)));
@@ -526,7 +557,7 @@ export function unreferencedUserFiles(home, loadedFiles) {
 export function resolveInstructions(projectDir) {
   const layers = settingsLayers({ projectDir });
   const candidates = [
-    ...userCandidates(os.homedir(), layers),
+    ...userCandidates(null, layers),
     ...projectCandidates(projectDir),
   ];
   const resolved = finalize(candidates, { projectDir, excludes: readExcludes(layers) });
@@ -552,7 +583,7 @@ export function resolveInstructions(projectDir) {
  * With no project there is no boundary for an import to resolve outside of, so
  * nothing is marked external here - that check belongs to the whole-session view.
  */
-export function resolveGlobalInstructions({ home = os.homedir(), settingsFile = null } = {}) {
+export function resolveGlobalInstructions({ home = null, settingsFile = null } = {}) {
   const layers = settingsLayers(settingsFile ? { settingsFile } : {});
   const resolved = finalize(userCandidates(home, layers), { projectDir: null, excludes: readExcludes(layers) });
   resolved.problems.push(...unreferencedUserFiles(home, resolved.files));

package/src/liveSessions.mjs

@@ -4,9 +4,10 @@
 // happening right now.
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 
+import { configPath } from './config.mjs';
+
 function isAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -21,7 +22,7 @@ function isAlive(pid) {
  * left behind by a process that has since exited is silently skipped rather
  * than reported as stale - the registry itself is not this app's to clean up.
  */
-export function readLiveSessions({ dir = path.join(os.homedir(), '.claude', 'sessions') } = {}) {
+export function readLiveSessions({ dir = configPath('sessions') } = {}) {
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });

package/src/model.mjs

@@ -15,7 +15,7 @@ import { parseIndex, parseFrontmatter, extractWikilinks } from './parse.mjs';
 import { listMemoryFiles, memoryDir, resolveProjectPath, shortLabel } from './projects.mjs';
 import { autoMemoryState } from './settings.mjs';
 import { ageInDays, estimateTokens, findDuplicates, indexStats } from './stats.mjs';
-import { memoryChecks, sessionChecks } from './checks.mjs';
+import { agentStoreChecks, memoryChecks, sessionChecks } from './checks.mjs';
 import { listSessions, originSession, retention, transcriptDir } from './sessions.mjs';
 import { rememberedPath } from './pathcache.mjs';
 
@@ -198,6 +198,7 @@ export function buildStore(store) {
     ...(health.longHooks.length
       ? [{ kind: 'long-hooks', severity: 'warn', count: health.longHooks.length, longest: health.longHooks[0] }]
       : []),
+    ...agentStoreChecks(store),
     ...memoryChecks(memories, index),
     ...sessionChecks(store, memories, sessions.retention, {
       remembered: sessions.remembered,