claude-memory-admin 1.0.0 → 1.1.0

package/src/pathcache.mjs

@@ -0,0 +1,93 @@
+// An opt-in record of project paths the user has confirmed.
+//
+// Claude Code sweeps session transcripts after cleanupPeriodDays but explicitly
+// never touches the memory directory, so the evidence this tool uses to name a
+// store expires while the store itself does not. A project whose transcripts
+// have aged out shows its raw slug forever, and no amount of re-reading brings
+// the name back.
+//
+// Nothing here runs on its own. The file is created only when the user asks for
+// a path to be remembered, and it holds slugs and directory paths - never memory
+// content. That keeps the default behaviour a pure read of the store, and keeps
+// this the only writer outside a memory/ directory.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const CACHE_DIR = process.env.MEMORY_PATH_CACHE_DIR || path.join(os.homedir(), '.claude-memory-admin');
+export const CACHE_FILE = path.join(CACHE_DIR, 'paths.json');
+
+/** Remembered paths by slug, or an empty map. Never throws: a bad file is ignored. */
+export function readPathCache() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The remembered path for one slug, only if it still exists on disk. */
+export function rememberedPath(slug) {
+  const entry = readPathCache()[slug];
+  const dir = entry && typeof entry.path === 'string' ? entry.path : null;
+  if (!dir) return null;
+  try {
+    return fs.statSync(dir).isDirectory() ? dir : null;
+  } catch {
+    // Remembered, then moved or deleted. Say nothing rather than assert a path
+    // that is no longer there.
+    return null;
+  }
+}
+
+function writeCache(data) {
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  const tmp = `${CACHE_FILE}.tmp-${process.pid}`;
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeFileSync(fd, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, CACHE_FILE);
+}
+
+/**
+ * Record a path for a slug. Only an existing directory is accepted: the point is
+ * to preserve a fact that was verifiable once, not to let a typo become the
+ * label a project carries from now on.
+ */
+export function rememberPath(slug, dir) {
+  if (typeof slug !== 'string' || !slug) throw new Error('Invalid project');
+  if (typeof dir !== 'string' || !path.isAbsolute(dir)) {
+    throw new Error('Path must be absolute');
+  }
+  let stat;
+  try {
+    stat = fs.statSync(dir);
+  } catch {
+    throw new Error(`${dir} does not exist`);
+  }
+  if (!stat.isDirectory()) throw new Error(`${dir} is not a directory`);
+
+  const cache = readPathCache();
+  cache[slug] = { path: dir, rememberedAt: new Date().toISOString() };
+  writeCache(cache);
+  return { slug, path: dir };
+}
+
+/** Drop a remembered path. Removing the last one removes the file entirely. */
+export function forgetPath(slug) {
+  const cache = readPathCache();
+  if (!(slug in cache)) return { slug, forgotten: false };
+  delete cache[slug];
+  if (Object.keys(cache).length === 0) {
+    try { fs.unlinkSync(CACHE_FILE); } catch { /* already gone */ }
+  } else {
+    writeCache(cache);
+  }
+  return { slug, forgotten: true };
+}

package/src/projects.mjs

@@ -6,42 +6,57 @@
 // from a path separator. So decoding the slug is a fallback, not the primary
 // method. The reliable source is the session transcripts sitting next to the
 // memory dir, whose JSONL lines carry the true `cwd`.
+//
+// One memory directory can serve several working directories: Claude Code keys
+// the store on the git repository, so every worktree and subdirectory of a repo
+// shares it. Reading a single `cwd` therefore names the store after whichever
+// directory happened to run last, which is why every distinct cwd is collected
+// and the repository root preferred as the store's identity.
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { rememberedPath } from './pathcache.mjs';
+import { autoMemoryState, expandHome, resolveMemoryDirectory } from './settings.mjs';
 
 export const DEFAULT_ROOT = path.join(os.homedir(), '.claude', 'projects');
-const USER_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
-
-function expandHome(value) {
-  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2));
-  return value;
-}
 
 /**
- * Claude Code lets `autoMemoryDirectory` in settings.json move the memory store
- * somewhere else entirely. Honour it, or this tool would confidently show an
- * empty store to anyone who has set it.
+ * Which store to read, and what decided it. The source travels with the path so
+ * the UI can say where a non-default store came from; a tool that silently reads
+ * somewhere other than the default is worse than one that reads nothing.
  */
-export function configuredMemoryDirectory() {
-  try {
-    const settings = JSON.parse(fs.readFileSync(USER_SETTINGS, 'utf8'));
-    const configured = settings?.autoMemoryDirectory;
-    if (typeof configured === 'string' && configured.trim()) return expandHome(configured.trim());
-  } catch {
-    // No settings file, or not readable/parseable: fall through to the default.
+export function resolveRoot() {
+  if (process.env.MEMORY_ROOT) {
+    return { path: expandHome(process.env.MEMORY_ROOT), source: 'flag', file: null, invalid: null };
   }
-  return null;
+  const configured = resolveMemoryDirectory({ projectDir: process.cwd() });
+  if (configured?.path) {
+    return { path: configured.path, source: configured.scope, file: configured.file, invalid: null };
+  }
+  if (configured?.invalid) {
+    // Set, but to something Claude Code would not accept either. Fall back, and
+    // carry the reason so it can be reported rather than swallowed.
+    return {
+      path: DEFAULT_ROOT,
+      source: 'default',
+      file: configured.file,
+      invalid: `autoMemoryDirectory "${configured.raw}" is ${configured.invalid}`,
+    };
+  }
+  return { path: DEFAULT_ROOT, source: 'default', file: null, invalid: null };
 }
 
 export function projectsRoot() {
-  if (process.env.MEMORY_ROOT) return expandHome(process.env.MEMORY_ROOT);
-  return configuredMemoryDirectory() || DEFAULT_ROOT;
+  return resolveRoot().path;
 }
 
-/** Read the first chunk of a file without pulling a multi-megabyte transcript into memory. */
-function readHead(file, bytes = 131072) {
+/**
+ * Read the head of a file without pulling a multi-megabyte transcript into
+ * memory. The `cwd` field shows up within the first few lines in practice, so
+ * the small read almost always suffices and the large one is a fallback.
+ */
+function readHead(file, bytes) {
   const fd = fs.openSync(file, 'r');
   try {
     const buf = Buffer.alloc(bytes);
@@ -73,15 +88,14 @@ function findTranscripts(dir, depth = 2) {
   return out;
 }
 
-/** Pull `cwd` out of the newest transcripts. Authoritative when present. */
-function cwdFromTranscripts(dir) {
-  const transcripts = findTranscripts(dir).sort((a, b) => b.mtime - a.mtime);
-  for (const { file } of transcripts.slice(0, 3)) {
+/** The first `cwd` in one transcript, escalating the read only if the small one missed. */
+function cwdInTranscript(file) {
+  for (const size of [16384, 131072]) {
     let head;
     try {
-      head = readHead(file);
+      head = readHead(file, size);
     } catch {
-      continue;
+      return null;
     }
     for (const line of head.split('\n')) {
       if (!line.includes('"cwd"')) continue;
@@ -92,10 +106,71 @@ function cwdFromTranscripts(dir) {
         // Truncated final line of the chunk, or a non-object line. Skip it.
       }
     }
+    if (head.length < size) return null; // Read the whole file already.
   }
   return null;
 }
 
+/**
+ * Distinct `cwd` values across the newest transcripts, newest first.
+ *
+ * The cap keeps this cheap on projects with hundreds of sessions. It biases
+ * towards recent directories, which is the right bias: a worktree deleted a year
+ * ago is not worth naming the store after.
+ */
+export function cwdsFromTranscripts(dir, { limit = 12 } = {}) {
+  const transcripts = findTranscripts(dir).sort((a, b) => b.mtime - a.mtime);
+  const seen = new Set();
+  for (const { file } of transcripts.slice(0, limit)) {
+    const cwd = cwdInTranscript(file);
+    if (cwd) seen.add(cwd);
+  }
+  return [...seen];
+}
+
+/** Longest path prefix shared by every input, or null when they share only "/". */
+function commonAncestor(paths) {
+  if (paths.length === 0) return null;
+  let parts = paths[0].split('/');
+  for (const other of paths.slice(1)) {
+    const segments = other.split('/');
+    let i = 0;
+    while (i < parts.length && i < segments.length && parts[i] === segments[i]) i += 1;
+    parts = parts.slice(0, i);
+  }
+  const joined = parts.join('/');
+  return joined.length > 1 ? joined : null;
+}
+
+function isGitRoot(dir) {
+  try {
+    return fs.existsSync(path.join(dir, '.git'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Which of several working directories names the store.
+ *
+ * Claude Code derives the store from the git repository, so when the cwds share
+ * an ancestor that is a repository root, that root is the store's real identity
+ * and every cwd is a worktree or subdirectory of it. When they do not - two
+ * worktrees checked out in unrelated places share a repo but not a path prefix -
+ * there is nothing to confirm, so the newest cwd is used exactly as before
+ * rather than inventing a common parent that means nothing.
+ */
+export function storeIdentity(cwds) {
+  if (cwds.length === 0) return null;
+  if (cwds.length === 1) return { path: cwds[0], resolvedBy: 'transcript' };
+
+  const ancestor = commonAncestor(cwds);
+  if (ancestor && isGitRoot(ancestor)) {
+    return { path: ancestor, resolvedBy: 'repo-root' };
+  }
+  return { path: cwds[0], resolvedBy: 'transcript' };
+}
+
 /**
  * Best-effort slug decode, used only when there is no transcript to read.
  * Candidates are verified against the filesystem so a wrong guess is reported
@@ -116,21 +191,30 @@ function decodeSlug(slug) {
 }
 
 export function resolveProjectPath(dir, slug) {
-  const fromTranscript = cwdFromTranscripts(dir);
-  if (fromTranscript) {
+  const cwds = cwdsFromTranscripts(dir);
+  const identity = storeIdentity(cwds);
+  if (identity) {
     return {
-      path: fromTranscript,
-      resolvedBy: 'transcript',
-      exists: fs.existsSync(fromTranscript),
+      path: identity.path,
+      resolvedBy: identity.resolvedBy,
+      exists: fs.existsSync(identity.path),
+      workingDirs: cwds,
     };
   }
+  // A path the user confirmed once outranks a decode, and is the only thing that
+  // survives Claude Code sweeping the transcripts this store was named from.
+  const remembered = rememberedPath(slug);
+  if (remembered) {
+    return { path: remembered, resolvedBy: 'remembered', exists: true, workingDirs: [] };
+  }
+
   const decoded = decodeSlug(slug);
   if (decoded.verified) {
-    return { path: decoded.path, resolvedBy: 'slug', exists: true };
+    return { path: decoded.path, resolvedBy: 'slug', exists: true, workingDirs: [] };
   }
   // Nothing confirmed the guess, so show the slug rather than a path that
   // looks authoritative and is probably wrong.
-  return { path: slug, resolvedBy: 'unresolved', exists: false, guess: decoded.path };
+  return { path: slug, resolvedBy: 'unresolved', exists: false, guess: decoded.path, workingDirs: [] };
 }
 
 /** A short label for the sidebar: the last two path segments. */
@@ -181,6 +265,8 @@ export function listProjects(root = projectsRoot()) {
         label: shortLabel(resolved.path),
         resolvedBy: resolved.resolvedBy,
         pathExists: resolved.exists,
+        workingDirs: resolved.workingDirs,
+        autoMemory: autoMemoryState({ projectDir: resolved.exists ? resolved.path : null }),
         hasMemoryDir,
         hasIndex: hasMemoryDir && fs.existsSync(path.join(mem, 'MEMORY.md')),
         memoryCount: files.length,

package/src/search.mjs

@@ -3,8 +3,8 @@
 // The whole store is a few hundred kilobytes, so this scans it directly on each
 // query rather than maintaining an index that could go stale.
 
-import { buildProject } from './model.mjs';
-import { listProjects } from './projects.mjs';
+import { buildStore } from './model.mjs';
+import { listStores } from './stores.mjs';
 
 const FIELD_WEIGHT = { name: 6, description: 3, hook: 2, body: 1 };
 
@@ -102,26 +102,28 @@ export function searchProject(project, terms) {
   return { results: results.sort((a, b) => b.score - a.score), indexHits };
 }
 
-/** Search every project under `root`. */
+/** Search every store: auto memory and subagent memory alike. */
 export function searchAll(root, query, { limit = 200 } = {}) {
   const terms = fold(query).split(/\s+/).filter(Boolean);
   if (!terms.length) return { terms, total: 0, projects: [] };
 
-  const projects = [];
+  const stores = [];
   let total = 0;
-  for (const listed of listProjects(root)) {
+  for (const listed of listStores(root)) {
     if (!listed.hasMemoryDir) continue;
-    const project = buildProject(root, listed.slug);
-    const { results, indexHits } = searchProject(project, terms);
+    const store = buildStore(listed);
+    const { results, indexHits } = searchProject(store, terms);
     if (!results.length && !indexHits.length) continue;
     total += results.length;
-    projects.push({
-      slug: listed.slug,
-      label: project.label,
+    stores.push({
+      id: listed.id,
+      kind: listed.kind,
+      label: store.label,
+      sublabel: listed.sublabel || null,
       results: results.slice(0, limit),
       indexHits: indexHits.slice(0, 20),
     });
   }
 
-  return { terms, total, projects: projects.sort((a, b) => b.results.length - a.results.length) };
+  return { terms, total, stores: stores.sort((a, b) => b.results.length - a.results.length) };
 }

package/src/settings.mjs

@@ -0,0 +1,151 @@
+// Layered reads of Claude Code's settings files.
+//
+// Several keys this tool cares about - autoMemoryDirectory, autoMemoryEnabled -
+// can be set in any settings scope, and the scope that wins is not the one you
+// would guess: managed policy beats everything, and the user file everyone
+// actually edits is the weakest of the five. Reading only ~/.claude/settings.json
+// silently shows the wrong store to anyone who set the key anywhere else.
+//
+// Precedence, strongest first:
+//   managed policy  ->  --settings  ->  .claude/settings.local.json
+//               ->  .claude/settings.json  ->  ~/.claude/settings.json
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const USER_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
+
+/** Default when nothing sets cleanupPeriodDays; transcripts older than this are swept. */
+export const DEFAULT_CLEANUP_PERIOD_DAYS = 30;
+
+function managedDir() {
+  if (process.platform === 'darwin') return '/Library/Application Support/ClaudeCode';
+  if (process.platform === 'win32') return 'C:\\Program Files\\ClaudeCode';
+  return '/etc/claude-code';
+}
+
+/**
+ * Managed policy settings: the main file plus the managed-settings.d drop-in
+ * directory, which organisations use to compose policy from several files.
+ */
+export function managedSettingsFiles() {
+  const dir = managedDir();
+  const files = [path.join(dir, 'managed-settings.json')];
+  let dropIns;
+  try {
+    dropIns = fs.readdirSync(path.join(dir, 'managed-settings.d'));
+  } catch {
+    dropIns = [];
+  }
+  for (const name of dropIns.filter((n) => n.endsWith('.json')).sort()) {
+    files.push(path.join(dir, 'managed-settings.d', name));
+  }
+  return files;
+}
+
+function readJson(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    // Absent, unreadable, or not valid JSON. Claude Code would ignore it too.
+    return null;
+  }
+}
+
+/**
+ * Every settings file that exists and parses, strongest first, each tagged with
+ * the scope it came from so the UI can name the file a value came from rather
+ * than leaving the user to guess which of five files is in charge.
+ *
+ * `projectDir` is the directory a session would run in. This tool browses every
+ * project at once and is not itself a session, so callers pass either the launch
+ * cwd (for the store location, which is decided before any project is chosen) or
+ * a specific project's resolved path (for that project's auto memory state).
+ */
+export function settingsLayers({ projectDir = null, settingsFile = null } = {}) {
+  const candidates = [];
+  for (const file of managedSettingsFiles()) candidates.push({ scope: 'managed', file });
+  if (settingsFile) candidates.push({ scope: 'settings-flag', file: settingsFile });
+  if (projectDir) {
+    candidates.push({ scope: 'local', file: path.join(projectDir, '.claude', 'settings.local.json') });
+    candidates.push({ scope: 'project', file: path.join(projectDir, '.claude', 'settings.json') });
+  }
+  candidates.push({ scope: 'user', file: USER_SETTINGS });
+
+  const layers = [];
+  for (const candidate of candidates) {
+    const data = readJson(candidate.file);
+    if (data) layers.push({ ...candidate, data });
+  }
+  return layers;
+}
+
+/** First layer that defines `key`, or null. Layers are already in precedence order. */
+export function lookup(layers, key) {
+  for (const layer of layers) {
+    if (Object.prototype.hasOwnProperty.call(layer.data, key)) {
+      return { value: layer.data[key], scope: layer.scope, file: layer.file };
+    }
+  }
+  return null;
+}
+
+export function expandHome(value) {
+  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+/**
+ * Where the auto memory store lives, per settings.
+ *
+ * The documented contract is "an absolute path or a `~/`-prefixed path". A value
+ * that is neither is reported rather than quietly ignored: the alternative is
+ * showing someone the default store while their setting points elsewhere, which
+ * is the exact failure this function exists to prevent.
+ *
+ * Returns { path, scope, file } when set, { invalid, ... } when set but
+ * unusable, or null when no layer sets it.
+ */
+export function resolveMemoryDirectory(options = {}) {
+  const found = lookup(settingsLayers(options), 'autoMemoryDirectory');
+  if (!found) return null;
+
+  const raw = typeof found.value === 'string' ? found.value.trim() : '';
+  if (!raw) return null;
+  if (!raw.startsWith('/') && !raw.startsWith('~/') && !/^[A-Za-z]:[\\/]/.test(raw)) {
+    return { ...found, raw, path: null, invalid: 'not an absolute or ~/ path' };
+  }
+  return { ...found, raw, path: expandHome(raw), invalid: null };
+}
+
+/**
+ * Whether auto memory is on for a project, and what decided it.
+ *
+ * A project with auto memory off has a store that will never grow again, which
+ * on disk is indistinguishable from a project Claude has simply not learned
+ * anything about yet. Without a resolved project path there is no project or
+ * local layer to read, so the answer is unknown rather than assumed.
+ */
+export function autoMemoryState({ projectDir = null } = {}) {
+  const env = process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY;
+  if (env && env !== '0' && env !== 'false') {
+    return { enabled: false, setBy: 'CLAUDE_CODE_DISABLE_AUTO_MEMORY', scope: 'env', known: true };
+  }
+
+  const found = lookup(settingsLayers({ projectDir }), 'autoMemoryEnabled');
+  if (found && typeof found.value === 'boolean') {
+    return { enabled: found.value, setBy: found.file, scope: found.scope, known: true };
+  }
+  // Default is true, but without a project path the project and local layers
+  // were never consulted, so "on" here is an assumption and is labelled one.
+  return { enabled: true, setBy: null, scope: 'default', known: Boolean(projectDir) };
+}
+
+/** Retention period for session transcripts. Memory files are excluded from the sweep. */
+export function cleanupPeriodDays(options = {}) {
+  const found = lookup(settingsLayers(options), 'cleanupPeriodDays');
+  const value = Number(found?.value);
+  return Number.isFinite(value) && value >= 1 ? value : DEFAULT_CLEANUP_PERIOD_DAYS;
+}

package/src/stats.mjs

@@ -26,16 +26,107 @@ export const INDEX_BYTE_LIMIT = 25 * 1024;
 export const LONG_HOOK_CHARS = 200;
 
 /**
- * The text that actually counts against the limits. Claude Code strips YAML
- * frontmatter and block-level HTML comments before loading the index, so
- * measuring the raw file would overstate the size.
+ * The text that actually counts against the limits, plus a map from each line of
+ * it back to the line it came from in the raw file.
+ *
+ * Claude Code strips YAML frontmatter and block-level HTML comments before
+ * loading the index, so measuring the raw file would overstate the size. That
+ * stripping is also why a position in the loaded text is not a line number in
+ * the file: to draw the cutoff where the user can see it, the removed spans have
+ * to be tracked rather than just discarded.
  */
+export function loadedIndex(indexText) {
+  if (!indexText) return { text: '', rawLineFor: [] };
+
+  const removed = [];
+  const frontmatter = indexText.match(/^---\n[\s\S]*?\n---\n?/);
+  const base = frontmatter ? frontmatter[0].length : 0;
+  if (frontmatter) removed.push([0, base]);
+
+  // Matched on the post-frontmatter text, exactly as the stripping itself is, so
+  // the `m` anchors land on the same line starts.
+  for (const match of indexText.slice(base).matchAll(/^[ \t]*<!--[\s\S]*?-->[ \t]*\n?/gm)) {
+    removed.push([base + match.index, base + match.index + match[0].length]);
+  }
+
+  removed.sort((a, b) => a[0] - b[0]);
+  const kept = [];
+  let cursor = 0;
+  for (const [start, end] of removed) {
+    if (start > cursor) kept.push([cursor, start]);
+    cursor = Math.max(cursor, end);
+  }
+  if (cursor < indexText.length) kept.push([cursor, indexText.length]);
+
+  const rawLineStarts = [0];
+  for (let i = 0; i < indexText.length; i++) {
+    if (indexText[i] === '\n') rawLineStarts.push(i + 1);
+  }
+  const rawLineAt = (offset) => {
+    let low = 0;
+    let high = rawLineStarts.length - 1;
+    while (low < high) {
+      const mid = (low + high + 1) >> 1;
+      if (rawLineStarts[mid] <= offset) low = mid;
+      else high = mid - 1;
+    }
+    return low;
+  };
+
+  // One raw offset per surviving character, which is what makes the line map a
+  // lookup rather than a second parse that could disagree with the first.
+  const offsets = [];
+  for (const [start, end] of kept) {
+    for (let i = start; i < end; i++) offsets.push(i);
+  }
+
+  const rawLineFor = [];
+  if (offsets.length) rawLineFor.push(rawLineAt(offsets[0]));
+  for (let i = 0; i < offsets.length - 1; i++) {
+    if (indexText[offsets[i]] === '\n') rawLineFor.push(rawLineAt(offsets[i + 1]));
+  }
+
+  return { text: kept.map(([start, end]) => indexText.slice(start, end)).join(''), rawLineFor };
+}
+
+/** The loaded text alone, for callers that do not need the line map. */
 export function loadedIndexText(indexText) {
-  if (!indexText) return '';
-  let text = indexText;
-  const frontmatter = text.match(/^---\n[\s\S]*?\n---\n?/);
-  if (frontmatter) text = text.slice(frontmatter[0].length);
-  return text.replace(/^[ \t]*<!--[\s\S]*?-->[ \t]*\n?/gm, '');
+  return loadedIndex(indexText).text;
+}
+
+/**
+ * Where the index stops being loaded, and which entries fall past it.
+ *
+ * The percentage on the meter says an index is too big; this says which memories
+ * Claude can no longer see, which is the thing you can act on. Both are derived
+ * from the same loaded text, so they cannot disagree.
+ */
+function findCutoff(loaded, entries) {
+  const lines = loaded.text.split('\n');
+  let bytes = 0;
+  let byteCut = Infinity;
+  for (let i = 0; i < lines.length; i++) {
+    // Every line but the last carries its newline.
+    bytes += Buffer.byteLength(lines[i], 'utf8') + (i < lines.length - 1 ? 1 : 0);
+    if (bytes > INDEX_BYTE_LIMIT) { byteCut = i; break; }
+  }
+  const lineCut = loaded.rawLineFor.length > INDEX_LINE_LIMIT ? INDEX_LINE_LIMIT : Infinity;
+
+  const loadedLine = Math.min(lineCut, byteCut);
+  if (!Number.isFinite(loadedLine)) return null;
+
+  const rawLine = loaded.rawLineFor[loadedLine];
+  if (rawLine === undefined) return null;
+
+  return {
+    loadedLine,
+    rawLine,
+    by: lineCut <= byteCut ? 'lines' : 'bytes',
+    droppedLines: loaded.rawLineFor.length - loadedLine,
+    droppedEntries: entries
+      .filter((entry) => entry.index >= rawLine)
+      .map((entry) => ({ index: entry.index, file: entry.file, title: entry.title })),
+  };
 }
 
 export function indexStats(indexText, entries) {
@@ -44,12 +135,13 @@ export function indexStats(indexText, entries) {
       bytes: 0, lines: 0, tokens: 0, entryCount: 0, longHooks: [], longestHook: 0,
       lineLimit: INDEX_LINE_LIMIT, byteLimit: INDEX_BYTE_LIMIT,
       linePercent: 0, bytePercent: 0, worstPercent: 0, level: 'ok', overLimit: false, nearLimit: false,
+      cutoff: null,
     };
   }
 
-  const loaded = loadedIndexText(indexText);
-  const lines = loaded.split('\n').filter((line, i, all) => i < all.length - 1 || line.length > 0).length;
-  const bytes = Buffer.byteLength(loaded, 'utf8');
+  const loaded = loadedIndex(indexText);
+  const lines = loaded.rawLineFor.length;
+  const bytes = Buffer.byteLength(loaded.text, 'utf8');
 
   const longHooks = entries
     .filter((entry) => entry.hook.length > LONG_HOOK_CHARS)
@@ -64,7 +156,7 @@ export function indexStats(indexText, entries) {
     bytes,
     lines,
     rawBytes: Buffer.byteLength(indexText, 'utf8'),
-    tokens: estimateTokens(loaded),
+    tokens: estimateTokens(loaded.text),
     entryCount: entries.length,
     longHooks,
     longestHook: entries.reduce((max, e) => Math.max(max, e.hook.length), 0),
@@ -77,6 +169,7 @@ export function indexStats(indexText, entries) {
     overLimit: lines > INDEX_LINE_LIMIT || bytes > INDEX_BYTE_LIMIT,
     nearLimit: worstPercent >= 75,
     level: worstPercent > 100 ? 'over' : worstPercent >= 75 ? 'near' : 'ok',
+    cutoff: findCutoff(loaded, entries),
   };
 }