agent-file-stash 0.4.0 → 0.6.0

package/dist/cli.mjs

@@ -1,45 +1,117 @@
 #!/usr/bin/env node
 
 // packages/sdk/src/stash.ts
-import { readFileSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { readFileSync, writeFileSync, statSync, chmodSync, mkdirSync, existsSync, renameSync, rmSync } from "node:fs";
+import { resolve, dirname as dirname2 } from "node:path";
 import { createHash } from "node:crypto";
 
 // packages/sdk/src/differ.ts
 var CONTEXT = 3;
+var MAX_EDIT_DISTANCE = 2500;
+var MAX_SNAKE_STEPS = 2e7;
 function computeDiff(oldContent, newContent, filePath) {
   const oldLines = oldContent.split("\n");
   const newLines = newContent.split("\n");
-  const lcs = longestCommonSubsequence(oldLines, newLines);
-  const { rawLines, linesChanged } = buildRawLines(oldLines, newLines, lcs);
-  const changedNewLines = collectChangedLines(rawLines);
-  if (linesChanged === 0) {
-    return { diff: "", linesChanged: 0, hasChanges: false, changedNewLines };
+  const shortest = Math.min(oldLines.length, newLines.length);
+  let prefix = 0;
+  while (prefix < shortest && oldLines[prefix] === newLines[prefix]) prefix++;
+  let suffix = 0;
+  while (suffix < shortest - prefix && oldLines[oldLines.length - 1 - suffix] === newLines[newLines.length - 1 - suffix]) suffix++;
+  const n = oldLines.length - prefix - suffix;
+  const m = newLines.length - prefix - suffix;
+  if (n === 0 && m === 0) {
+    return { diff: "", linesChanged: 0, hasChanges: false, changedNewLines: /* @__PURE__ */ new Set() };
   }
+  const edits = myersEdits(oldLines, newLines, prefix, n, m) ?? {
+    removed: new Uint8Array(n).fill(1),
+    added: new Uint8Array(m).fill(1)
+  };
+  const { rawLines, linesChanged } = buildRawLines(oldLines, newLines, prefix, suffix, edits);
+  const changedNewLines = collectChangedLines(rawLines);
   const hunkGroups = groupIntoHunks(rawLines);
   const diff = formatDiff(hunkGroups, filePath);
   return { diff, linesChanged, hasChanges: true, changedNewLines };
 }
-function buildRawLines(oldLines, newLines, lcs) {
+function myersEdits(oldLines, newLines, off, n, m) {
+  const removed = new Uint8Array(n);
+  const added = new Uint8Array(m);
+  if (n === 0 || m === 0) return { removed: removed.fill(1), added: added.fill(1) };
+  if (Math.abs(n - m) > MAX_EDIT_DISTANCE) return null;
+  const max = Math.min(n + m, MAX_EDIT_DISTANCE);
+  const base = max + 1;
+  const v = new Int32Array(2 * max + 3);
+  const trace = [];
+  let steps = 0;
+  let found = -1;
+  for (let d = 0; d <= max && found < 0; d++) {
+    for (let k = -d; k <= d; k += 2) {
+      let x2 = k === -d || k !== d && v[base + k - 1] < v[base + k + 1] ? v[base + k + 1] : v[base + k - 1] + 1;
+      let y2 = x2 - k;
+      while (x2 < n && y2 < m && oldLines[off + x2] === newLines[off + y2]) {
+        x2++;
+        y2++;
+        steps++;
+      }
+      if (steps > MAX_SNAKE_STEPS) return null;
+      v[base + k] = x2;
+      if (x2 >= n && y2 >= m) {
+        found = d;
+        break;
+      }
+    }
+    if (found >= 0) break;
+    const snapshot = new Int32Array(d + 1);
+    for (let k = -d, i = 0; k <= d; k += 2, i++) snapshot[i] = v[base + k];
+    trace.push(snapshot);
+  }
+  if (found < 0) return null;
+  let x = n, y = m;
+  for (let d = found; d > 0; d--) {
+    const k = x - y;
+    const prev = trace[d - 1];
+    const at = (diagonal) => prev[diagonal + d - 1 >> 1];
+    const down = k === -d || k !== d && at(k - 1) < at(k + 1);
+    const prevK = down ? k + 1 : k - 1;
+    const prevX = at(prevK);
+    const prevY = prevX - prevK;
+    if (down) added[prevY] = 1;
+    else removed[prevX] = 1;
+    x = prevX;
+    y = prevY;
+  }
+  return { removed, added };
+}
+function buildRawLines(oldLines, newLines, prefix, suffix, edits) {
   const rawLines = [];
-  let oldIdx = 0, newIdx = 0, lcsIdx = 0, linesChanged = 0;
-  while (oldIdx < oldLines.length || newIdx < newLines.length) {
-    const atLcsMatch = lcsIdx < lcs.length && oldIdx < oldLines.length && oldLines[oldIdx] === lcs[lcsIdx] && newIdx < newLines.length && newLines[newIdx] === lcs[lcsIdx];
-    if (atLcsMatch) {
-      rawLines.push({ type: "keep", line: oldLines[oldIdx], oldLine: oldIdx + 1, newLine: newIdx + 1 });
-      oldIdx++;
-      newIdx++;
-      lcsIdx++;
-    } else if (newIdx < newLines.length && (lcsIdx >= lcs.length || newLines[newIdx] !== lcs[lcsIdx])) {
-      rawLines.push({ type: "add", line: newLines[newIdx], oldLine: oldIdx + 1, newLine: newIdx + 1 });
-      newIdx++;
+  const { removed, added } = edits;
+  let linesChanged = 0;
+  for (let i = 0; i < prefix; i++) {
+    rawLines.push({ type: "keep", line: oldLines[i], oldLine: i + 1, newLine: i + 1 });
+  }
+  let oi = 0, ni = 0;
+  while (oi < removed.length || ni < added.length) {
+    if (oi < removed.length && ni < added.length && !removed[oi] && !added[ni]) {
+      rawLines.push({ type: "keep", line: oldLines[prefix + oi], oldLine: prefix + oi + 1, newLine: prefix + ni + 1 });
+      oi++;
+      ni++;
+      continue;
+    }
+    while (ni < added.length && added[ni]) {
+      rawLines.push({ type: "add", line: newLines[prefix + ni], oldLine: prefix + oi + 1, newLine: prefix + ni + 1 });
+      ni++;
       linesChanged++;
-    } else {
-      rawLines.push({ type: "remove", line: oldLines[oldIdx], oldLine: oldIdx + 1, newLine: newIdx + 1 });
-      oldIdx++;
+    }
+    while (oi < removed.length && removed[oi]) {
+      rawLines.push({ type: "remove", line: oldLines[prefix + oi], oldLine: prefix + oi + 1, newLine: prefix + ni + 1 });
+      oi++;
       linesChanged++;
     }
   }
+  const oldTail = prefix + removed.length;
+  const newTail = prefix + added.length;
+  for (let i = 0; i < suffix; i++) {
+    rawLines.push({ type: "keep", line: oldLines[oldTail + i], oldLine: oldTail + i + 1, newLine: newTail + i + 1 });
+  }
   return { rawLines, linesChanged };
 }
 function collectChangedLines(rawLines) {
@@ -83,13 +155,8 @@ function groupIntoHunks(rawLines) {
 }
 function fillContextGap(current, rawLines, lastChangeIdx, upTo) {
   const contextEnd = lastChangeIdx + CONTEXT + 1;
-  const inCurrent = new Set(current);
   for (let c = contextEnd; c < upTo; c++) {
-    const line = rawLines[c];
-    if (!inCurrent.has(line)) {
-      current.push(line);
-      inCurrent.add(line);
-    }
+    current.push(rawLines[c]);
   }
 }
 function formatDiff(hunkGroups, filePath) {
@@ -108,41 +175,41 @@ function formatDiff(hunkGroups, filePath) {
   }
   return lines.join("\n");
 }
-var LCS_LINE_LIMIT = 5e3;
-function longestCommonSubsequence(a, b) {
-  const m = a.length;
-  const n = b.length;
-  if (m > LCS_LINE_LIMIT || n > LCS_LINE_LIMIT) {
-    return [];
-  }
-  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
-  for (let i2 = 1; i2 <= m; i2++) {
-    for (let j2 = 1; j2 <= n; j2++) {
-      if (a[i2 - 1] === b[j2 - 1]) {
-        dp[i2][j2] = dp[i2 - 1][j2 - 1] + 1;
-      } else {
-        dp[i2][j2] = Math.max(dp[i2 - 1][j2], dp[i2][j2 - 1]);
-      }
-    }
-  }
-  const result = [];
-  let i = m, j = n;
-  while (i > 0 && j > 0) {
-    if (a[i - 1] === b[j - 1]) {
-      result.unshift(a[i - 1]);
-      i--;
-      j--;
-    } else if (dp[i - 1][j] > dp[i][j - 1]) {
-      i--;
-    } else {
-      j--;
-    }
-  }
-  return result;
+
+// packages/sdk/src/exclude.ts
+import { basename, dirname } from "node:path";
+var DEFAULT_PATTERNS = [
+  ".env",
+  ".env.*",
+  "*.pem",
+  "*.key",
+  "*.p12",
+  "*.pfx",
+  "*.keystore",
+  "id_rsa*",
+  "id_ed25519*",
+  "id_ecdsa*",
+  ".npmrc",
+  ".netrc",
+  "credentials*",
+  "secrets.*"
+];
+var ALLOWED_NAMES = /* @__PURE__ */ new Set([".env.example", ".env.sample", ".env.template", ".env.dist"]);
+var SECRET_DIRS = /* @__PURE__ */ new Set([".ssh", ".aws", ".gnupg"]);
+function globToRegExp(glob) {
+  const body = glob.toLowerCase().replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${body}$`);
+}
+var DEFAULT_MATCHERS = DEFAULT_PATTERNS.map(globToRegExp);
+function isExcludedPath(absPath, extraPatterns = []) {
+  const name = basename(absPath).toLowerCase();
+  if (extraPatterns.some((p) => globToRegExp(p.trim()).test(name))) return true;
+  if (!ALLOWED_NAMES.has(name) && !name.endsWith(".pub") && DEFAULT_MATCHERS.some((re) => re.test(name))) return true;
+  return dirname(absPath).split(/[\\/]/).some((seg) => SECRET_DIRS.has(seg.toLowerCase()));
 }
 
-// packages/sdk/src/stash.ts
-var SCHEMA = `
+// packages/sdk/src/migrations.ts
+var SCHEMA_V1 = `
 CREATE TABLE IF NOT EXISTS file_versions (
   path        TEXT NOT NULL,
   hash        TEXT NOT NULL,
@@ -160,6 +227,16 @@ CREATE TABLE IF NOT EXISTS session_reads (
   PRIMARY KEY (session_id, path)
 );
 
+CREATE TABLE IF NOT EXISTS session_ranges (
+  session_id  TEXT NOT NULL,
+  path        TEXT NOT NULL,
+  hash        TEXT NOT NULL,
+  start_line  INTEGER NOT NULL,
+  end_line    INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_session_ranges ON session_ranges (session_id, path);
+
 CREATE TABLE IF NOT EXISTS sessions (
   session_id  TEXT PRIMARY KEY,
   pid         INTEGER NOT NULL
@@ -179,6 +256,83 @@ CREATE TABLE IF NOT EXISTS session_stats (
 
 INSERT OR IGNORE INTO stats (key, value) VALUES ('tokens_saved', 0);
 `;
+var MIGRATIONS = [{ version: 1, up: (db) => db.exec(SCHEMA_V1) }];
+var SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
+var SchemaTooNewError = class extends Error {
+  constructor(found, supported) {
+    super(`database schema version ${found} is newer than this release supports (${supported}); upgrade agent-file-stash`);
+    this.name = "SchemaTooNewError";
+  }
+};
+function readUserVersion(db) {
+  const row = db.prepare("PRAGMA user_version").get();
+  return row.user_version;
+}
+function runMigrations(db, migrations = MIGRATIONS) {
+  const target = migrations[migrations.length - 1].version;
+  const check = (version) => {
+    if (version > target) throw new SchemaTooNewError(version, target);
+  };
+  check(readUserVersion(db));
+  for (const step of migrations) {
+    if (readUserVersion(db) >= step.version) continue;
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      const current = readUserVersion(db);
+      check(current);
+      if (current < step.version) {
+        step.up(db);
+        db.exec(`PRAGMA user_version = ${step.version}`);
+      }
+      db.exec("COMMIT");
+    } catch (err) {
+      try {
+        db.exec("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    }
+  }
+}
+
+// packages/sdk/src/stash.ts
+var DEFAULT_MAX_LINES = 2e3;
+var DEFAULT_MAX_CHARS = 1e5;
+var DEFAULT_MAX_STORE_BYTES = 1e6;
+var HARD_MAX_READ_BYTES = 64 * 1024 * 1024;
+var BINARY_SNIFF_CHARS = 8192;
+var SCOPE_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+var SCOPE_DELIMITER = "::";
+var MAX_SCOPES_PER_SESSION = 32;
+function positiveOr(value, fallback) {
+  return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function sliceLines(content, offset, limit, maxLines, maxChars) {
+  const lines = content.split("\n");
+  const total = lines.length;
+  const startIdx = offset > 0 ? offset - 1 : 0;
+  const start = startIdx + 1;
+  const requestedEnd = limit > 0 ? Math.min(startIdx + limit, total) : total;
+  const maxEnd = Math.min(requestedEnd, startIdx + maxLines);
+  let chars = 0;
+  let i = startIdx;
+  for (; i < maxEnd; i++) {
+    const next = chars + lines[i].length + (i > startIdx ? 1 : 0);
+    if (next > maxChars) break;
+    chars = next;
+  }
+  if (i >= requestedEnd) {
+    return { text: lines.slice(startIdx, i).join("\n"), start, end: limit > 0 ? start + limit - 1 : total, midLine: false, truncated: false };
+  }
+  if (i > startIdx) {
+    const notice2 = `[filestash: truncated, showing lines ${start}-${i} of ${total}; continue with offset=${i + 1}]`;
+    return { text: `${lines.slice(startIdx, i).join("\n")}
+${notice2}`, start, end: i, midLine: false, truncated: true };
+  }
+  const notice = `[filestash: truncated, showing the first ${maxChars} chars of line ${start} of ${total}; continue with offset=${start + 1}]`;
+  return { text: `${lines[startIdx].slice(0, maxChars)}
+${notice}`, start, end: start - 1, midLine: true, truncated: true };
+}
 function estimateTokens(text) {
   return Math.ceil(text.length / 4);
 }
@@ -186,6 +340,19 @@ var HASH_LENGTH = 16;
 function contentHash(content) {
   return createHash("sha256").update(content).digest("hex").slice(0, HASH_LENGTH);
 }
+function mergeIntervals(intervals) {
+  const sorted = intervals.filter(([a, b]) => b >= a).sort((x, y) => x[0] - y[0]);
+  const merged = [];
+  for (const [a, b] of sorted) {
+    const last = merged[merged.length - 1];
+    if (last && a <= last[1] + 1) last[1] = Math.max(last[1], b);
+    else merged.push([a, b]);
+  }
+  return merged;
+}
+function coversRange(intervals, start, end) {
+  return end >= start && intervals.some(([a, b]) => a <= start && b >= end);
+}
 function isProcessAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
@@ -195,6 +362,53 @@ function isProcessAlive(pid) {
     return err.code === "EPERM";
   }
 }
+var SQLITE_BUSY = 5;
+var SQLITE_LOCKED = 6;
+var SQLITE_IOERR = 10;
+var SQLITE_CORRUPT = 11;
+var SQLITE_NOTADB = 26;
+var OPEN_ATTEMPTS = 6;
+var OPEN_BACKOFF_MS = 150;
+var RECOVERY_LOCK_STALE_MS = 15e3;
+var RECOVERY_LOCK_WAIT_MS = 8e3;
+var RECOVERY_LOCK_POLL_MS = 50;
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function isCorruptError(err) {
+  const code = err.errcode;
+  if (typeof code === "number" && [SQLITE_CORRUPT, SQLITE_NOTADB].includes(code & 255)) return true;
+  return /not a database|malformed|corrupt/i.test(errorMessage(err));
+}
+function isTransientError(err) {
+  const code = err.errcode;
+  if (typeof code === "number" && [SQLITE_BUSY, SQLITE_LOCKED, SQLITE_IOERR].includes(code & 255)) return true;
+  return /database is locked|database is busy|disk i\/o error/i.test(errorMessage(err));
+}
+function tryAcquireLock(lockPath) {
+  try {
+    writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+    return true;
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+  }
+  try {
+    if (Date.now() - statSync(lockPath).mtimeMs < RECOVERY_LOCK_STALE_MS) return false;
+    rmSync(lockPath, { force: true });
+    writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function waitForLockRelease(lockPath) {
+  const deadline = Date.now() + RECOVERY_LOCK_WAIT_MS;
+  while (existsSync(lockPath) && Date.now() < deadline) await sleep(RECOVERY_LOCK_POLL_MS);
+}
+var BASE_SESSION_SQL = `(CASE WHEN instr(session_id, '${SCOPE_DELIMITER}') > 0 THEN substr(session_id, 1, instr(session_id, '${SCOPE_DELIMITER}') - 1) ELSE session_id END)`;
 function queryOne(db, sql, params = []) {
   const rows = db.prepare(sql).all(...params);
   return rows[0];
@@ -203,91 +417,269 @@ var StashStore = class {
   db = null;
   dbPath;
   sessionId;
+  exclude;
   initialized = false;
+  recoverCorrupt;
+  quiet;
+  maxLines;
+  maxChars;
+  maxStoreBytes;
+  recoveryAttempted = false;
+  recoveredFrom;
+  reason;
   constructor(config) {
     this.dbPath = config.dbPath;
-    this.sessionId = config.sessionId;
+    this.sessionId = config.sessionId.replace(/:{2,}/g, "_");
+    this.exclude = config.exclude ?? [];
+    this.recoverCorrupt = config.recoverCorrupt ?? true;
+    this.quiet = config.quiet ?? false;
+    this.maxLines = positiveOr(config.maxLines, DEFAULT_MAX_LINES);
+    this.maxChars = positiveOr(config.maxChars, DEFAULT_MAX_CHARS);
+    this.maxStoreBytes = positiveOr(config.maxStoreBytes, DEFAULT_MAX_STORE_BYTES);
+  }
+  get isDegraded() {
+    return this.reason !== void 0;
+  }
+  get degradedReason() {
+    return this.reason;
   }
   async init() {
     if (this.initialized) return;
-    const { DatabaseSync } = await import("node:sqlite");
-    this.db = new DatabaseSync(this.dbPath);
-    this.db.exec("PRAGMA journal_mode=WAL");
-    this.db.exec("PRAGMA busy_timeout=5000");
-    this.db.exec(SCHEMA);
-    this.registerSession(this.db);
-    this.pruneClosedSessions(this.db);
+    try {
+      this.db = await this.openWithRetry();
+    } catch (err) {
+      await this.recoverOrDegrade(err);
+    }
     this.initialized = true;
   }
+  async openWithRetry() {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return await this.openDb();
+      } catch (err) {
+        if (attempt >= OPEN_ATTEMPTS || !isTransientError(err)) throw err;
+        await sleep(OPEN_BACKOFF_MS * attempt);
+      }
+    }
+  }
+  async openDb() {
+    const { DatabaseSync } = await import("node:sqlite");
+    mkdirSync(dirname2(this.dbPath), { recursive: true, mode: 448 });
+    const db = new DatabaseSync(this.dbPath);
+    try {
+      db.exec("PRAGMA busy_timeout=5000");
+      db.exec("PRAGMA journal_mode=WAL");
+      runMigrations(db);
+      this.registerSession(db);
+      this.pruneClosedSessions(db);
+    } catch (err) {
+      try {
+        db.close();
+      } catch {
+      }
+      throw err;
+    }
+    this.restrictPermissions();
+    return db;
+  }
+  async recoverOrDegrade(err) {
+    if (!this.recoverCorrupt || this.recoveryAttempted || !isCorruptError(err)) return this.degrade(err);
+    this.recoveryAttempted = true;
+    const lockPath = `${this.dbPath}.recover.lock`;
+    try {
+      if (!tryAcquireLock(lockPath)) {
+        await waitForLockRelease(lockPath);
+        this.db = await this.openWithRetry();
+        return;
+      }
+      try {
+        try {
+          this.db = await this.openWithRetry();
+          return;
+        } catch (again) {
+          if (!isCorruptError(again)) throw again;
+        }
+        const moved = this.moveAside();
+        this.db = await this.openWithRetry();
+        this.recoveredFrom = moved;
+        this.notice(`${this.dbPath} is corrupt (${errorMessage(err)}); moved to ${moved}, starting a new stash`);
+      } finally {
+        rmSync(lockPath, { force: true });
+      }
+    } catch (retryErr) {
+      this.degrade(retryErr);
+    }
+  }
+  moveAside() {
+    const target = `${this.dbPath}.corrupt-${Date.now()}`;
+    for (const suffix of ["-wal", "-shm", ""]) {
+      if (!existsSync(this.dbPath + suffix)) continue;
+      try {
+        renameSync(this.dbPath + suffix, target + suffix);
+      } catch (e) {
+        if (e.code !== "ENOENT") throw e;
+      }
+    }
+    return target;
+  }
+  notice(message) {
+    if (!this.quiet) process.stderr.write(`[filestash] ${message}
+`);
+  }
+  degrade(err) {
+    if (this.reason !== void 0) return;
+    this.reason = errorMessage(err);
+    this.notice(`stash unavailable (${this.reason}); files are read normally, nothing is stashed`);
+    try {
+      this.db?.close();
+    } catch {
+    }
+    this.db = null;
+  }
+  restrictPermissions() {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        chmodSync(this.dbPath + suffix, 384);
+      } catch {
+      }
+    }
+  }
   registerSession(db) {
     db.prepare("INSERT OR REPLACE INTO sessions (session_id, pid) VALUES (?, ?)").run(this.sessionId, process.pid);
   }
   pruneClosedSessions(db) {
     db.exec("BEGIN IMMEDIATE");
     try {
+      this.purgeExcluded(db);
       const sessions = db.prepare("SELECT session_id, pid FROM sessions").all();
       for (const s of sessions) {
         if (s.session_id !== this.sessionId && !isProcessAlive(s.pid)) {
           db.prepare("DELETE FROM sessions WHERE session_id = ?").run(s.session_id);
         }
       }
-      db.exec("DELETE FROM session_reads WHERE session_id NOT IN (SELECT session_id FROM sessions)");
+      for (const table of ["session_reads", "session_ranges"]) {
+        db.exec(`DELETE FROM ${table} WHERE ${BASE_SESSION_SQL} NOT IN (SELECT session_id FROM sessions)`);
+      }
       db.exec("DELETE FROM session_stats WHERE session_id NOT IN (SELECT session_id FROM sessions)");
       db.exec(
         "DELETE FROM file_versions WHERE NOT EXISTS (SELECT 1 FROM session_reads r WHERE r.path = file_versions.path AND r.hash = file_versions.hash)"
       );
       db.exec("COMMIT");
     } catch (err) {
-      db.exec("ROLLBACK");
+      try {
+        db.exec("ROLLBACK");
+      } catch {
+      }
       throw err;
     }
   }
-  getDb() {
-    if (!this.db) throw new Error("StashStore not initialized. Call init() first.");
-    return this.db;
+  purgeExcluded(db) {
+    for (const table of ["file_versions", "session_reads", "session_ranges"]) {
+      const rows = db.prepare(`SELECT DISTINCT path FROM ${table}`).all();
+      for (const { path } of rows) {
+        if (isExcludedPath(path, this.exclude)) db.prepare(`DELETE FROM ${table} WHERE path = ?`).run(path);
+      }
+    }
   }
   readFileSnapshot(filePath) {
     const absPath = resolve(filePath);
-    statSync(absPath);
+    const size = statSync(absPath).size;
+    const now = Date.now();
+    if (size > HARD_MAX_READ_BYTES) {
+      const result2 = { stashed: false, content: `[filestash: file too large (${size} bytes); not read]`, hash: "" };
+      return { absPath, size, content: "", hash: "", lines: 0, now, early: { result: result2, countRead: false } };
+    }
     const content = readFileSync(absPath, "utf-8");
-    return {
-      absPath,
-      content,
-      hash: contentHash(content),
-      lines: content.split("\n").length,
-      now: Date.now()
-    };
+    const hash = contentHash(content);
+    const lines = content.split("\n").length;
+    const snap = { absPath, size, content, hash, lines, now };
+    if (content.slice(0, BINARY_SNIFF_CHARS).includes("\0")) {
+      const result2 = { stashed: false, content: `[filestash: binary file (${size} bytes), not shown]`, hash, totalLines: lines };
+      snap.early = { result: result2, countRead: true };
+    }
+    return snap;
+  }
+  earlyResult(snap) {
+    const { result: result2, countRead } = snap.early;
+    if (countRead) {
+      const tokens = estimateTokens(result2.content);
+      this.guarded((db) => this.recordRead(db, tokens, tokens));
+    }
+    return result2;
+  }
+  isStoreable(snap) {
+    return snap.size <= this.maxStoreBytes && !isExcludedPath(snap.absPath, this.exclude);
   }
   async readFile(filePath, options) {
     await this.init();
-    const db = this.getDb();
-    const { absPath, content: currentContent, hash: currentHash, lines: currentLines, now } = this.readFileSnapshot(filePath);
+    const snap = this.readFileSnapshot(filePath);
+    if (snap.early) return this.earlyResult(snap);
+    const { absPath, content: currentContent, hash: currentHash, lines: currentLines, now } = snap;
     const offset = options?.offset ?? 0;
     const limit = options?.limit ?? 0;
-    const rangeStart = offset > 0 ? offset : 1;
+    const slice = sliceLines(currentContent, offset, limit, this.maxLines, this.maxChars);
     const state = {
       absPath,
       currentContent,
       currentHash,
       currentLines,
-      isPartial: offset > 0 || limit > 0,
-      rangeStart,
-      rangeEnd: limit > 0 ? rangeStart + limit - 1 : currentLines,
+      isPartial: offset > 0 || limit > 0 || slice.truncated,
+      rangeStart: slice.start,
+      rangeEnd: slice.end,
       offset,
       limit,
-      now
+      now,
+      size: snap.size,
+      slice: slice.text,
+      midLine: slice.midLine,
+      tid: this.trackingId(options?.scope)
     };
+    if (this.db) {
+      try {
+        return this.readWithDb(this.db, state);
+      } catch (err) {
+        this.degrade(err);
+      }
+    }
+    return this.plainResult(state);
+  }
+  trackingId(scope) {
+    return scope !== void 0 && SCOPE_PATTERN.test(scope) ? `${this.sessionId}${SCOPE_DELIMITER}${scope}` : this.sessionId;
+  }
+  ensureScopeCapacity(db, tid) {
+    if (tid === this.sessionId) return;
+    if (queryOne(db, "SELECT 1 FROM session_reads WHERE session_id = ? LIMIT 1", [tid])) return;
+    const prefix = `${this.sessionId}${SCOPE_DELIMITER}`;
+    const scopes = db.prepare(
+      "SELECT session_id, MAX(read_at) AS last FROM session_reads WHERE substr(session_id, 1, ?) = ? GROUP BY session_id ORDER BY last ASC, session_id ASC"
+    ).all(prefix.length, prefix);
+    const excess = scopes.length - MAX_SCOPES_PER_SESSION + 1;
+    for (const { session_id } of scopes.slice(0, Math.max(0, excess))) {
+      db.prepare("DELETE FROM session_reads WHERE session_id = ?").run(session_id);
+      db.prepare("DELETE FROM session_ranges WHERE session_id = ?").run(session_id);
+    }
+  }
+  plainResult(s) {
+    return { stashed: false, content: s.slice, hash: s.currentHash, totalLines: s.currentLines };
+  }
+  readWithDb(db, state) {
+    if (!this.isStoreable(state)) {
+      const content = state.slice;
+      this.recordRead(db, estimateTokens(content), estimateTokens(content));
+      return { stashed: false, content, hash: state.currentHash, totalLines: state.currentLines };
+    }
     const lastRead = queryOne(
       db,
       "SELECT hash FROM session_reads WHERE session_id = ? AND path = ?",
-      [this.sessionId, absPath]
+      [state.tid, state.absPath]
     );
     if (!lastRead) {
+      this.ensureScopeCapacity(db, state.tid);
       return this.handleFirstRead(db, state);
     }
     const lastHash = lastRead.hash;
-    if (lastHash === currentHash) {
-      return this.handleUnchanged(db, state);
+    if (lastHash === state.currentHash) {
+      return this.coversRequest(db, state, lastHash) ? this.handleUnchanged(db, state) : this.handleUncovered(db, state);
     }
     return this.handleChanged(db, state, lastHash);
   }
@@ -295,53 +687,107 @@ var StashStore = class {
     this.storeVersion(db, s.absPath, s.currentHash, s.currentContent, s.currentLines, s.now);
     db.prepare(
       "INSERT OR REPLACE INTO session_reads (session_id, path, hash, read_at) VALUES (?, ?, ?, ?)"
-    ).run(this.sessionId, s.absPath, s.currentHash, s.now);
-    return { stashed: false, content: this.sliceContent(s), hash: s.currentHash, totalLines: s.currentLines };
+    ).run(s.tid, s.absPath, s.currentHash, s.now);
+    this.clearRanges(db, s.tid, s.absPath);
+    return this.fullSlice(db, s);
+  }
+  requestedEnd(s) {
+    return Math.min(s.rangeEnd, s.currentLines);
+  }
+  getRanges(db, tid, absPath, hash) {
+    const rows = db.prepare(
+      "SELECT start_line, end_line FROM session_ranges WHERE session_id = ? AND path = ? AND hash = ?"
+    ).all(tid, absPath, hash);
+    return rows.map((r) => [r.start_line, r.end_line]);
+  }
+  coversRequest(db, s, hash) {
+    return coversRange(this.getRanges(db, s.tid, s.absPath, hash), s.rangeStart, this.requestedEnd(s));
+  }
+  clearRanges(db, tid, absPath) {
+    db.prepare("DELETE FROM session_ranges WHERE session_id = ? AND path = ?").run(tid, absPath);
+  }
+  addRange(db, tid, absPath, hash, start, end) {
+    if (end < start) return;
+    const merged = mergeIntervals([...this.getRanges(db, tid, absPath, hash), [start, end]]);
+    db.prepare("DELETE FROM session_ranges WHERE session_id = ? AND path = ? AND hash = ?").run(tid, absPath, hash);
+    const insert = db.prepare(
+      "INSERT INTO session_ranges (session_id, path, hash, start_line, end_line) VALUES (?, ?, ?, ?, ?)"
+    );
+    for (const [a, b] of merged) insert.run(tid, absPath, hash, a, b);
+  }
+  handleUncovered(db, s) {
+    db.prepare(
+      "UPDATE session_reads SET read_at = ? WHERE session_id = ? AND path = ?"
+    ).run(s.now, s.tid, s.absPath);
+    return this.fullSlice(db, s);
+  }
+  fullSlice(db, s) {
+    const content = s.slice;
+    this.addRange(db, s.tid, s.absPath, s.currentHash, s.rangeStart, this.requestedEnd(s));
+    this.recordRead(db, estimateTokens(content), estimateTokens(content));
+    return { stashed: false, content, hash: s.currentHash, totalLines: s.currentLines };
+  }
+  unchangedLabel(db, s, label) {
+    const content = s.slice;
+    const baseline = estimateTokens(content);
+    const saved = Math.max(0, baseline - estimateTokens(label(baseline)));
+    const text = label(saved);
+    const sent = estimateTokens(text);
+    const base = { stashed: true, hash: s.currentHash, totalLines: s.currentLines, linesChanged: 0 };
+    this.addRange(db, s.tid, s.absPath, s.currentHash, s.rangeStart, this.requestedEnd(s));
+    if (sent >= baseline) {
+      this.recordRead(db, baseline, baseline);
+      return { ...base, content };
+    }
+    this.recordRead(db, baseline, sent);
+    return { ...base, content: text };
   }
   handleUnchanged(db, s) {
-    const slicedTokens = estimateTokens(this.sliceContent(s));
-    this.addTokensSaved(db, slicedTokens);
     db.prepare(
       "UPDATE session_reads SET read_at = ? WHERE session_id = ? AND path = ?"
-    ).run(s.now, this.sessionId, s.absPath);
-    const label = s.isPartial ? `[filestash: unchanged, lines ${s.rangeStart}-${s.rangeEnd} of ${s.currentLines}, ${slicedTokens} tokens saved]` : `[filestash: unchanged, ${s.currentLines} lines, ${slicedTokens} tokens saved]`;
-    return { stashed: true, content: label, hash: s.currentHash, totalLines: s.currentLines, linesChanged: 0 };
+    ).run(s.now, s.tid, s.absPath);
+    return this.unchangedLabel(
+      db,
+      s,
+      (tokens) => s.isPartial ? `[filestash: unchanged, lines ${s.rangeStart}-${s.rangeEnd} of ${s.currentLines}, ${tokens} tokens saved]` : `[filestash: unchanged, ${s.currentLines} lines, ${tokens} tokens saved]`
+    );
   }
   handleChanged(db, s, lastHash) {
     const oldVersion = queryOne(
       db,
-      "SELECT content FROM file_versions WHERE path = ? AND hash = ?",
+      "SELECT content, lines FROM file_versions WHERE path = ? AND hash = ?",
       [s.absPath, lastHash]
     );
+    const oldFullyDelivered = !!oldVersion && coversRange(this.getRanges(db, s.tid, s.absPath, lastHash), 1, oldVersion.lines);
     this.storeVersion(db, s.absPath, s.currentHash, s.currentContent, s.currentLines, s.now);
     db.prepare(
       "UPDATE session_reads SET hash = ?, read_at = ? WHERE session_id = ? AND path = ?"
-    ).run(s.currentHash, s.now, this.sessionId, s.absPath);
-    if (oldVersion) {
+    ).run(s.currentHash, s.now, s.tid, s.absPath);
+    this.clearRanges(db, s.tid, s.absPath);
+    if (oldVersion && oldFullyDelivered) {
       const diffResult = computeDiff(oldVersion.content, s.currentContent, s.absPath);
       if (diffResult.hasChanges) {
         return s.isPartial ? this.handlePartialDiff(db, s, diffResult) : this.handleFullDiff(db, s, diffResult);
       }
     }
-    return { stashed: false, content: this.sliceContent(s), hash: s.currentHash, totalLines: s.currentLines };
+    return this.fullSlice(db, s);
   }
   handlePartialDiff(db, s, diffResult) {
-    if (!this.rangeHasChanges(diffResult.changedNewLines, s.rangeStart, s.rangeEnd)) {
-      const slicedTokens = estimateTokens(this.sliceContent(s));
-      this.addTokensSaved(db, slicedTokens);
-      return {
-        stashed: true,
-        content: `[filestash: unchanged in lines ${s.rangeStart}-${s.rangeEnd}, changes elsewhere in file, ${slicedTokens} tokens saved]`,
-        hash: s.currentHash,
-        totalLines: s.currentLines,
-        linesChanged: 0
-      };
+    if (!s.midLine && !this.rangeHasChanges(diffResult.changedNewLines, s.rangeStart, s.rangeEnd)) {
+      return this.unchangedLabel(
+        db,
+        s,
+        (tokens) => `[filestash: unchanged in lines ${s.rangeStart}-${s.rangeEnd}, changes elsewhere in file, ${tokens} tokens saved]`
+      );
     }
-    return { stashed: false, content: this.sliceContent(s), hash: s.currentHash, totalLines: s.currentLines };
+    return this.fullSlice(db, s);
   }
   handleFullDiff(db, s, diffResult) {
-    const saved = Math.max(0, estimateTokens(s.currentContent) - estimateTokens(diffResult.diff));
-    this.addTokensSaved(db, saved);
+    const contentTokens = estimateTokens(s.currentContent);
+    const diffTokens = estimateTokens(diffResult.diff);
+    if (diffTokens >= contentTokens) return this.fullSlice(db, s);
+    this.addRange(db, s.tid, s.absPath, s.currentHash, 1, s.currentLines);
+    this.recordRead(db, contentTokens, diffTokens);
     return {
       stashed: true,
       content: diffResult.diff,
@@ -351,13 +797,6 @@ var StashStore = class {
       totalLines: s.currentLines
     };
   }
-  sliceContent(s) {
-    if (!s.isPartial) return s.currentContent;
-    const lines = s.currentContent.split("\n");
-    const start = s.offset > 0 ? s.offset - 1 : 0;
-    const end = s.limit > 0 ? start + s.limit : lines.length;
-    return lines.slice(start, end).join("\n");
-  }
   rangeHasChanges(changedLines, rangeStart, rangeEnd) {
     for (let l = rangeStart; l <= rangeEnd; l++) {
       if (changedLines.has(l)) return true;
@@ -369,68 +808,131 @@ var StashStore = class {
       "INSERT OR IGNORE INTO file_versions (path, hash, content, lines, created_at) VALUES (?, ?, ?, ?, ?)"
     ).run(absPath, hash, content, lines, now);
   }
-  // Always returns full content and resets session tracking. Never records token savings.
-  async readFileFull(filePath) {
+  // Resets session tracking for the file and returns the first slice regardless of what was delivered before. Counts as a plain read (baseline equals sent).
+  async readFileFull(filePath, scope) {
     await this.init();
-    const db = this.getDb();
-    const { absPath, content, hash, lines, now } = this.readFileSnapshot(filePath);
-    this.storeVersion(db, absPath, hash, content, lines, now);
-    db.prepare(
-      "INSERT OR REPLACE INTO session_reads (session_id, path, hash, read_at) VALUES (?, ?, ?, ?)"
-    ).run(this.sessionId, absPath, hash, now);
-    return { stashed: false, content, hash, totalLines: lines };
+    const snap = this.readFileSnapshot(filePath);
+    if (snap.early) return this.earlyResult(snap);
+    const { absPath, content, hash, lines, now } = snap;
+    const slice = sliceLines(content, 0, 0, this.maxLines, this.maxChars);
+    const result2 = { stashed: false, content: slice.text, hash, totalLines: lines };
+    if (!this.db) return result2;
+    try {
+      const tokens = estimateTokens(slice.text);
+      if (this.isStoreable(snap)) {
+        const tid = this.trackingId(scope);
+        this.ensureScopeCapacity(this.db, tid);
+        this.storeVersion(this.db, absPath, hash, content, lines, now);
+        this.db.prepare(
+          "INSERT OR REPLACE INTO session_reads (session_id, path, hash, read_at) VALUES (?, ?, ?, ?)"
+        ).run(tid, absPath, hash, now);
+        this.clearRanges(this.db, tid, absPath);
+        this.addRange(this.db, tid, absPath, hash, slice.start, slice.end);
+      }
+      this.recordRead(this.db, tokens, tokens);
+    } catch (err) {
+      this.degrade(err);
+    }
+    return result2;
   }
   async onFileDeleted(filePath) {
     await this.init();
-    const db = this.getDb();
     const absPath = resolve(filePath);
-    db.prepare("DELETE FROM file_versions WHERE path = ?").run(absPath);
-    db.prepare("DELETE FROM session_reads WHERE path = ?").run(absPath);
+    this.guarded((db) => {
+      db.prepare("DELETE FROM file_versions WHERE path = ?").run(absPath);
+      db.prepare("DELETE FROM session_reads WHERE path = ?").run(absPath);
+      db.prepare("DELETE FROM session_ranges WHERE path = ?").run(absPath);
+    });
+  }
+  guarded(fn) {
+    if (!this.db) return void 0;
+    try {
+      return fn(this.db);
+    } catch (err) {
+      this.degrade(err);
+      return void 0;
+    }
   }
   async getStats() {
     await this.init();
-    const db = this.getDb();
-    const versionRow = queryOne(db, "SELECT COUNT(DISTINCT path) as c FROM file_versions");
-    const tokenRow = queryOne(db, "SELECT value FROM stats WHERE key = 'tokens_saved'");
-    const sessionTokenRow = queryOne(
-      db,
-      "SELECT value FROM session_stats WHERE session_id = ? AND key = 'tokens_saved'",
-      [this.sessionId]
-    );
+    const stats = this.guarded((db) => {
+      const versionRow = queryOne(db, "SELECT COUNT(DISTINCT path) as c FROM file_versions");
+      const tokenRow = queryOne(db, "SELECT value FROM stats WHERE key = 'tokens_saved'");
+      const sessionStat = (key) => queryOne(db, "SELECT value FROM session_stats WHERE session_id = ? AND key = ?", [this.sessionId, key])?.value ?? 0;
+      return {
+        filesTracked: versionRow?.c ?? 0,
+        tokensSaved: tokenRow?.value ?? 0,
+        sessionTokensSaved: sessionStat("tokens_saved"),
+        sessionReads: sessionStat("reads"),
+        sessionBaselineTokens: sessionStat("baseline_tokens"),
+        sessionSentTokens: sessionStat("sent_tokens"),
+        degraded: false,
+        ...this.recoveredFrom && { recoveredFrom: this.recoveredFrom }
+      };
+    });
+    if (stats) return stats;
     return {
-      filesTracked: versionRow?.c ?? 0,
-      tokensSaved: tokenRow?.value ?? 0,
-      sessionTokensSaved: sessionTokenRow?.value ?? 0
+      filesTracked: 0,
+      tokensSaved: 0,
+      sessionTokensSaved: 0,
+      sessionReads: 0,
+      sessionBaselineTokens: 0,
+      sessionSentTokens: 0,
+      degraded: true,
+      ...this.reason && { degradedReason: this.reason }
     };
   }
   async clear() {
     await this.init();
-    const db = this.getDb();
-    db.prepare("DELETE FROM file_versions").run();
-    db.prepare("DELETE FROM session_reads").run();
-    db.prepare("DELETE FROM session_stats").run();
-    db.prepare("UPDATE stats SET value = 0").run();
+    this.guarded((db) => {
+      db.prepare("DELETE FROM file_versions").run();
+      db.prepare("DELETE FROM session_reads").run();
+      db.prepare("DELETE FROM session_ranges").run();
+      db.prepare("DELETE FROM session_stats").run();
+      db.prepare("UPDATE stats SET value = 0").run();
+    });
+  }
+  async resetReads() {
+    await this.init();
+    this.guarded((db) => {
+      db.prepare("DELETE FROM session_reads").run();
+      db.prepare("DELETE FROM session_ranges").run();
+    });
   }
   async close() {
-    if (this.db) {
+    if (!this.db) return;
+    try {
       this.db.prepare("DELETE FROM sessions WHERE session_id = ?").run(this.sessionId);
+    } catch {
+    }
+    try {
       this.db.close();
-      this.db = null;
-      this.initialized = false;
+    } catch {
     }
+    this.db = null;
+    this.initialized = false;
+  }
+  recordRead(db, baseline, sent) {
+    this.bumpSessionStat(db, "reads", 1);
+    this.bumpSessionStat(db, "baseline_tokens", baseline);
+    this.bumpSessionStat(db, "sent_tokens", sent);
+    if (baseline > sent) this.addTokensSaved(db, baseline - sent);
+  }
+  bumpSessionStat(db, key, n) {
+    db.prepare(
+      "INSERT INTO session_stats (session_id, key, value) VALUES (?, ?, ?) ON CONFLICT(session_id, key) DO UPDATE SET value = value + ?"
+    ).run(this.sessionId, key, n, n);
   }
   addTokensSaved(db, tokens) {
     db.prepare(
       "UPDATE stats SET value = value + ? WHERE key = 'tokens_saved'"
     ).run(tokens);
-    db.prepare(
-      "INSERT INTO session_stats (session_id, key, value) VALUES (?, 'tokens_saved', ?) ON CONFLICT(session_id, key) DO UPDATE SET value = value + ?"
-    ).run(this.sessionId, tokens, tokens);
+    this.bumpSessionStat(db, "tokens_saved", tokens);
   }
 };
 
 // packages/sdk/src/watcher.ts
-import { watch as fsWatch, existsSync } from "node:fs";
+import { watch as fsWatch, existsSync as existsSync2 } from "node:fs";
 import { resolve as resolve2 } from "node:path";
 var FileWatcher = class {
   watchers = [];
@@ -444,26 +946,39 @@ var FileWatcher = class {
   watch(paths) {
     for (const p of paths) {
       const absPath = resolve2(p);
-      const watcher = fsWatch(absPath, { recursive: true }, (event, filename) => {
-        if (!filename) return;
-        const filePath = resolve2(absPath, filename);
-        if (filename.startsWith(".") || filename.includes("node_modules") || filename.includes(".git")) {
-          return;
-        }
-        const existing = this.debounceTimers.get(filePath);
-        if (existing) clearTimeout(existing);
-        this.debounceTimers.set(
-          filePath,
-          setTimeout(() => {
-            this.debounceTimers.delete(filePath);
-            this.handleChange(filePath).catch((e) => {
-              process.stderr.write(
-                `[filestash] unhandled watcher error: ${e instanceof Error ? e.message : String(e)}
+      let watcher;
+      try {
+        watcher = fsWatch(absPath, { recursive: true }, (event, filename) => {
+          if (!filename) return;
+          const filePath = resolve2(absPath, filename);
+          if (filename.startsWith(".") || filename.includes("node_modules") || filename.includes(".git")) {
+            return;
+          }
+          const existing = this.debounceTimers.get(filePath);
+          if (existing) clearTimeout(existing);
+          this.debounceTimers.set(
+            filePath,
+            setTimeout(() => {
+              this.debounceTimers.delete(filePath);
+              this.handleChange(filePath).catch((e) => {
+                process.stderr.write(
+                  `[filestash] unhandled watcher error: ${e instanceof Error ? e.message : String(e)}
 `
-              );
-            });
-          }, this.debounceMs)
-        );
+                );
+              });
+            }, this.debounceMs)
+          );
+        });
+      } catch (e) {
+        process.stderr.write(`[filestash] file watching disabled for ${absPath}: ${e instanceof Error ? e.message : String(e)}
+`);
+        continue;
+      }
+      watcher.on("error", (e) => {
+        process.stderr.write(`[filestash] file watching stopped for ${absPath}: ${e.message}
+`);
+        watcher.close();
+        this.watchers = this.watchers.filter((w) => w !== watcher);
       });
       this.watchers.push(watcher);
     }
@@ -476,7 +991,7 @@ var FileWatcher = class {
   }
   async handleChange(filePath) {
     try {
-      if (!existsSync(filePath)) {
+      if (!existsSync2(filePath)) {
         await this.stash.onFileDeleted(filePath);
       }
     } catch (e) {
@@ -497,23 +1012,35 @@ function createStash(config) {
 }
 
 // packages/cli/src/index.ts
-import { resolve as resolve4, join as join3 } from "node:path";
-import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { resolve as resolve5, join as join5 } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync2, copyFileSync, mkdirSync as mkdirSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
 
 // packages/cli/src/mcp.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { resolve as resolve3, join, relative, isAbsolute } from "node:path";
-import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { readFileSync as readFileSync2, realpathSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-function getStashDir() {
+function resolveStashDir(baseDir = process.cwd()) {
   const raw = process.env.FILESTASH_DIR ?? ".file-stash";
   if (raw.includes("\0")) throw new Error("FILESTASH_DIR contains invalid characters");
-  const dir = resolve3(raw);
-  if (!existsSync2(dir)) mkdirSync(dir, { recursive: true });
-  return dir;
+  return resolve3(baseDir, raw);
+}
+function parseExcludeEnv() {
+  return (process.env.FILESTASH_EXCLUDE ?? "").split(",").map((p) => p.trim()).filter(Boolean);
+}
+function parseLimitEnv(name) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw === "") return void 0;
+  if (/^[1-9]\d*$/.test(raw) && Number.isSafeInteger(Number(raw))) return Number(raw);
+  process.stderr.write(`[filestash] ignoring invalid ${name}=${JSON.stringify(raw)}; using the default
+`);
+  return void 0;
+}
+function limitOptions() {
+  const maxLines = parseLimitEnv("FILESTASH_MAX_LINES");
+  const maxChars = parseLimitEnv("FILESTASH_MAX_CHARS");
+  return { ...maxLines !== void 0 && { maxLines }, ...maxChars !== void 0 && { maxChars } };
 }
 function isPathAllowed(absPath, cwd) {
   let realPath;
@@ -525,27 +1052,109 @@ function isPathAllowed(absPath, cwd) {
   const rel = relative(cwd, realPath);
   return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
 }
-function formatReadResult(result) {
-  if (result.stashed && result.diff) {
-    return `[filestash: ${result.linesChanged} lines changed out of ${result.totalLines}]
-${result.diff}`;
+function formatReadResult(result2) {
+  if (result2.stashed && result2.diff) {
+    return `[filestash: ${result2.linesChanged} lines changed out of ${result2.totalLines}]
+${result2.diff}`;
   }
-  return result.content;
+  return result2.content;
 }
-function formatFileEntry(path, result) {
-  if (result.stashed && result.diff) {
-    return `=== ${path} [${result.linesChanged} lines changed out of ${result.totalLines}] ===
-${result.diff}`;
+function formatFileEntry(path, result2) {
+  if (result2.stashed && result2.diff) {
+    return `=== ${path} [${result2.linesChanged} lines changed out of ${result2.totalLines}] ===
+${result2.diff}`;
   }
   return `=== ${path} ===
-${result.content}`;
+${result2.content}`;
+}
+var readFileShape = {
+  path: z.string().describe("File path"),
+  offset: z.number().optional().describe("Start line (1-based)"),
+  limit: z.number().optional().describe("Max lines"),
+  force: z.boolean().optional().describe("Bypass stash"),
+  agent: z.string().optional()
+};
+var readFilesShape = {
+  paths: z.preprocess(
+    (val) => typeof val === "string" ? JSON.parse(val) : val,
+    z.array(z.string())
+  ).describe("File paths"),
+  agent: z.string().optional()
+};
+var TOOL_DEFS = {
+  read_file: {
+    description: `Read a file (use instead of Read). Repeat reads of an unchanged file return a short label, changed files return only a diff. offset/limit supported and stashed. Long files are truncated, continue with offset. force=true returns full content (use when the original is no longer in context).`,
+    inputSchema: readFileShape
+  },
+  read_files: {
+    description: `Batched read_file for several files, same stash/diff behavior per file.`,
+    inputSchema: readFilesShape
+  },
+  stash_status: {
+    description: `Show files tracked and this session's token accounting, net of tool-definition overhead.`
+  },
+  stash_clear: {
+    description: `Clear all stashed data.`
+  }
+};
+function jsonType(field) {
+  switch (field._def.typeName) {
+    case z.ZodFirstPartyTypeKind.ZodOptional:
+      return jsonType(field._def.innerType);
+    case z.ZodFirstPartyTypeKind.ZodEffects:
+      return jsonType(field._def.schema);
+    case z.ZodFirstPartyTypeKind.ZodArray:
+      return "array";
+    case z.ZodFirstPartyTypeKind.ZodNumber:
+      return "number";
+    case z.ZodFirstPartyTypeKind.ZodBoolean:
+      return "boolean";
+    default:
+      return "string";
+  }
+}
+function jsonSchema(shape = {}) {
+  const properties = {};
+  for (const [key, field] of Object.entries(shape)) {
+    properties[key] = { type: jsonType(field), description: field.description };
+  }
+  const required = Object.entries(shape).filter(([, f]) => !f.isOptional()).map(([k]) => k);
+  return { type: "object", properties, ...required.length > 0 && { required } };
+}
+function toolDefinitionTokens() {
+  const defs = Object.entries(TOOL_DEFS).map(([name, def]) => ({
+    name,
+    description: def.description,
+    inputSchema: jsonSchema("inputSchema" in def ? def.inputSchema : void 0)
+  }));
+  return Math.ceil(JSON.stringify(defs).length / 4);
 }
-function statsSuffix(tokensSaved) {
+function degradedLine(reason2 = "unknown") {
+  return `Mode: DEGRADED (${reason2}) - files are read normally, nothing is stashed`;
+}
+function formatStatus(stats, overheadTokens) {
+  if (stats.degraded) return degradedLine(stats.degradedReason);
+  const fmt = (n) => `~${n.toLocaleString()}`;
+  const net = stats.sessionTokensSaved - overheadTokens;
+  return [
+    "filestash status:",
+    ...stats.recoveredFrom ? [`  Recovered: corrupt database moved to ${stats.recoveredFrom}`] : [],
+    `  Files tracked: ${stats.filesTracked}`,
+    `  This session: ${stats.sessionReads} reads`,
+    `    Would have sent (plain reads): ${fmt(stats.sessionBaselineTokens)} tokens`,
+    `    Actually sent: ${fmt(stats.sessionSentTokens)} tokens`,
+    `    Gross saved: ${fmt(stats.sessionTokensSaved)} tokens`,
+    `    Tool definitions overhead: ${fmt(overheadTokens)} tokens (est.)`,
+    `    Net saved: ${fmt(net)} tokens (est.)`,
+    `  Gross saved (all sessions): ${fmt(stats.tokensSaved)} tokens`
+  ].join("\n");
+}
+function statsSuffix(grossSaved) {
   return `
 
-[filestash: ~${tokensSaved.toLocaleString()} tokens saved this session. Report this to the user when you complete their task.]`;
+[filestash: net ~${(grossSaved - toolDefinitionTokens()).toLocaleString()} tokens this session (est.)]`;
 }
-async function readSingleFile(path, cwd, stash) {
+async function readSingleFile(path, cwd, stash, scope) {
   const absPath = resolve3(path);
   if (!isPathAllowed(absPath, cwd)) {
     return {
@@ -555,8 +1164,8 @@ Error: Path must be within the working directory (${cwd})`,
     };
   }
   try {
-    const result = await stash.readFile(path);
-    return { text: formatFileEntry(path, result), ok: true };
+    const result2 = await stash.readFile(path, { ...scope !== void 0 && { scope } });
+    return { text: formatFileEntry(path, result2), ok: true };
   } catch (e) {
     const message = e instanceof Error ? e.message : String(e);
     return { text: `=== ${path} ===
@@ -572,39 +1181,28 @@ async function startMcpServer() {
   } catch {
   }
   const META_NAMESPACE = (packageJson.mcpName || "io.github.glommer/filestash").replaceAll("/", ".");
-  const stashDir = getStashDir();
-  const dbPath = resolve3(stashDir, "stash.db");
+  const dbPath = resolve3(resolveStashDir(), "stash.db");
   const cwd = process.cwd();
   const watchPaths = [cwd];
   const sessionId = randomUUID();
   const { stash, watcher } = createStash({
     dbPath,
     sessionId,
-    watchPaths
+    watchPaths,
+    exclude: parseExcludeEnv(),
+    ...limitOptions()
   });
   await stash.init();
+  const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
   const server = new McpServer({
     name: "filestash",
     version: packageJson.version ?? "0.0.0"
   });
   server.registerTool(
     "read_file",
-    {
-      description: `Read a file with stashing. Use this tool INSTEAD of the built-in Read tool for reading files.
-On first read, returns full content and stashes it \u2014 identical to Read.
-On subsequent reads, if the file hasn't changed, returns a short confirmation instead of the full content \u2014 saving significant tokens.
-If the file changed, returns only the diff (changed lines) instead of the full file.
-Supports offset and limit for partial reads \u2014 and partial reads are also stashed. If only lines outside the requested range changed, returns a short confirmation saving tokens.
-Set force=true to bypass the stash and get the full file content (use when you no longer have the original in context).
-ALWAYS prefer this over the Read tool. It is a drop-in replacement with stashing benefits.`,
-      inputSchema: {
-        path: z.string().describe("Path to the file to read"),
-        offset: z.number().optional().describe("Line number to start reading from (1-based). Only provide if the file is too large to read at once."),
-        limit: z.number().optional().describe("Number of lines to read. Only provide if the file is too large to read at once."),
-        force: z.boolean().optional().describe("Bypass stash and return full content")
-      }
-    },
-    async ({ path, force, offset, limit }) => {
+    TOOL_DEFS.read_file,
+    async ({ path, force, offset, limit, agent }) => {
       const absPath = resolve3(path);
       if (!isPathAllowed(absPath, cwd)) {
         return {
@@ -613,12 +1211,13 @@ ALWAYS prefer this over the Read tool. It is a drop-in replacement with stashing
         };
       }
       try {
-        const result = force ? await stash.readFileFull(path) : await stash.readFile(path, {
+        const result2 = force ? await stash.readFileFull(path, agent) : await stash.readFile(path, {
           ...offset !== void 0 && { offset },
-          ...limit !== void 0 && { limit }
+          ...limit !== void 0 && { limit },
+          ...agent !== void 0 && { scope: agent }
         });
-        let text = formatReadResult(result);
-        if (result.stashed) {
+        let text = formatReadResult(result2);
+        if (result2.stashed) {
           const stats = await stash.getStats();
           text += statsSuffix(stats.sessionTokensSaved);
         }
@@ -637,19 +1236,9 @@ ALWAYS prefer this over the Read tool. It is a drop-in replacement with stashing
   );
   server.registerTool(
     "read_files",
-    {
-      description: `Read multiple files at once with stashing. Use this tool INSTEAD of the built-in Read tool when you need to read several files.
-Same behavior as read_file but batched. Returns stashed/diff results for each file.
-ALWAYS prefer this over multiple Read calls \u2014 it's faster and saves significant tokens.`,
-      inputSchema: {
-        paths: z.preprocess(
-          (val) => typeof val === "string" ? JSON.parse(val) : val,
-          z.array(z.string())
-        ).describe("Paths to the files to read")
-      }
-    },
-    async ({ paths }) => {
-      const results = await Promise.all(paths.map((p) => readSingleFile(p, cwd, stash)));
+    TOOL_DEFS.read_files,
+    async ({ paths, agent }) => {
+      const results = await Promise.all(paths.map((p) => readSingleFile(p, cwd, stash, agent)));
       const successfulPaths = paths.filter((_, i) => results[i].ok);
       const combined = results.map((r) => r.text).join("\n\n");
       let footer = "";
@@ -668,31 +1257,31 @@ ALWAYS prefer this over multiple Read calls \u2014 it's faster and saves signifi
   );
   server.registerTool(
     "stash_status",
-    {
-      description: `Show filestash statistics: files tracked, tokens saved, stash hit rates.
-Use this to verify filestash is working and see how many tokens it has saved.`
-    },
+    TOOL_DEFS.stash_status,
     async () => {
       const stats = await stash.getStats();
-      const text = [
-        `filestash status:`,
-        `  Files tracked: ${stats.filesTracked}`,
-        `  Tokens saved (this session): ~${stats.sessionTokensSaved.toLocaleString()}`,
-        `  Tokens saved (all sessions): ~${stats.tokensSaved.toLocaleString()}`
-      ].join("\n");
+      const overhead = toolDefinitionTokens();
+      const text = formatStatus(stats, overhead);
       return {
         content: [{ type: "text", text }],
-        _meta: { [`${META_NAMESPACE}/stats`]: { filesTracked: stats.filesTracked, tokensSaved: stats.tokensSaved, sessionTokensSaved: stats.sessionTokensSaved } }
+        _meta: {
+          [`${META_NAMESPACE}/stats`]: {
+            ...stats,
+            toolDefinitionTokens: overhead,
+            netTokensSaved: stats.sessionTokensSaved - overhead
+          }
+        }
       };
     }
   );
   server.registerTool(
     "stash_clear",
-    {
-      description: `Clear all stashed data. Use this to reset the stash completely.`
-    },
+    TOOL_DEFS.stash_clear,
     async () => {
       await stash.clear();
+      if (stash.isDegraded) {
+        return { content: [{ type: "text", text: "Stash is in degraded mode, nothing to clear." }] };
+      }
       return {
         content: [{ type: "text", text: "Stash cleared." }],
         _meta: { [`${META_NAMESPACE}/cleared`]: true }
@@ -737,6 +1326,449 @@ function findStashDatabases(root, depth = 0) {
   return found;
 }
 
+// packages/cli/src/editors.ts
+import { join as join3 } from "node:path";
+function editorTargets(home) {
+  const mcpServersEntry = {
+    command: "npx",
+    args: ["agent-file-stash", "serve"]
+  };
+  const opencodeMcpEntry = {
+    type: "local",
+    command: ["npx", "agent-file-stash", "serve"]
+  };
+  const xdgConfig = process.env.XDG_CONFIG_HOME || join3(home, ".config");
+  return [
+    { name: "Claude Code", path: join3(home, ".claude.json"), key: "mcpServers", entry: mcpServersEntry },
+    { name: "Cursor", path: join3(home, ".cursor", "mcp.json"), key: "mcpServers", entry: mcpServersEntry },
+    { name: "OpenCode", path: join3(xdgConfig, "opencode", "opencode.json"), key: "mcp", entry: opencodeMcpEntry }
+  ];
+}
+
+// packages/cli/src/doctor.ts
+import { accessSync, constants, existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync2 } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, isAbsolute as isAbsolute2, join as join4, resolve as resolve4 } from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+var PACKAGE_NAME = "agent-file-stash";
+var RECOVERY_LOCK_STALE_MS2 = 15e3;
+var DEFAULT_MIN_NODE = "24";
+var NPM_TIMEOUT_MS = 5e3;
+var MAX_SCRIPT_BYTES = 64 * 1024;
+var SESSION_START_TARGETS = ["clear", "compact"];
+var result = (id, status, message, hint) => ({
+  id,
+  status,
+  message,
+  ...hint !== void 0 && { hint }
+});
+var reason = (e) => e instanceof Error ? e.message : String(e);
+function readJson(path) {
+  return JSON.parse(readFileSync3(path, "utf-8"));
+}
+function asRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? v : void 0;
+}
+function ownPackageJson() {
+  for (const rel of ["../package.json", "../../../package.json"]) {
+    try {
+      const pkg = readJson(join4(import.meta.dirname, rel));
+      if (pkg.name === PACKAGE_NAME) return pkg;
+    } catch {
+      continue;
+    }
+  }
+  return void 0;
+}
+function wide(mode, mask) {
+  return (mode & mask) !== 0;
+}
+function octal(mode) {
+  return (mode & 511).toString(8).padStart(3, "0");
+}
+function checkNode(o) {
+  const range = ownPackageJson()?.engines?.node;
+  const required = Number(/\d+/.exec(range ?? "")?.[0] ?? DEFAULT_MIN_NODE);
+  const major = Number(o.nodeVersion.split(".")[0]);
+  if (major >= required) return [result("node", "ok", `Node ${o.nodeVersion} (requires >=${required})`)];
+  return [
+    result("node", "error", `Node ${o.nodeVersion} is older than the required >=${required}`, `install Node ${required} or newer`)
+  ];
+}
+function checkStashDir(o) {
+  const dir = resolveStashDir(o.cwd);
+  if (!existsSync4(dir)) return [result("stash-dir", "info", `stash directory ${dir} does not exist yet; it will be created on first read`)];
+  const st = statSync2(dir);
+  if (!st.isDirectory()) {
+    return [result("stash-dir", "error", `${dir} exists but is not a directory`, `remove it or point FILESTASH_DIR elsewhere`)];
+  }
+  if (o.platform !== "win32" && wide(st.mode, 63)) {
+    return [result("stash-dir", "warn", `stash directory ${dir} has mode ${octal(st.mode)}, expected 700`, `run: chmod 700 ${dir}`)];
+  }
+  return [result("stash-dir", "info", `stash directory ${dir}`)];
+}
+function isCorruptMessage(err) {
+  const code = err.errcode;
+  if (typeof code === "number" && [11, 26].includes(code & 255)) return true;
+  return /not a database|malformed|corrupt/i.test(reason(err));
+}
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+function formatBytes(n) {
+  return n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${(n / 1024).toFixed(1)} KB` : `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+async function inspectDatabase(dbPath) {
+  const { DatabaseSync } = await import("node:sqlite");
+  const url = pathToFileURL(dbPath);
+  url.search = existsSync4(`${dbPath}-wal`) || existsSync4(`${dbPath}-shm`) ? "mode=ro" : "mode=ro&immutable=1";
+  const db = new DatabaseSync(url.href, { readOnly: true });
+  try {
+    const userVersion = db.prepare("PRAGMA user_version").get().user_version;
+    const first = db.prepare("PRAGMA quick_check").all()[0] ?? {};
+    const integrity = String(Object.values(first)[0] ?? "no result");
+    const facts = { userVersion, integrity };
+    if (integrity === "ok" && userVersion >= 1 && userVersion <= SCHEMA_VERSION) {
+      facts.filesTracked = db.prepare("SELECT COUNT(DISTINCT path) AS c FROM file_versions").get().c;
+      facts.pids = db.prepare("SELECT pid FROM sessions").all().map((r) => r.pid);
+    }
+    return facts;
+  } finally {
+    db.close();
+  }
+}
+function checkDatabaseFiles(dir, now) {
+  const out = [];
+  const names = readdirSync2(dir);
+  const leftovers = names.filter((n) => /^stash\.db\.corrupt-\d+$/.test(n));
+  if (leftovers.length > 0) {
+    out.push(result("database-leftovers", "info", `${leftovers.length} moved-aside corrupt database file(s) in ${dir} (stash.db.corrupt-*); delete them when no longer needed`));
+  }
+  if (names.includes("stash.db.recover.lock")) {
+    const lock = join4(dir, "stash.db.recover.lock");
+    const age = now - statSync2(lock).mtimeMs;
+    if (age > RECOVERY_LOCK_STALE_MS2) {
+      out.push(result("database-lock", "warn", `stale recovery lock ${lock} (${Math.round(age / 1e3)}s old)`, `remove ${lock}; the next start also clears it`));
+    } else {
+      out.push(result("database-lock", "info", `a recovery is in progress (${lock})`));
+    }
+  }
+  return out;
+}
+async function checkDatabase(o) {
+  const dir = resolveStashDir(o.cwd);
+  const dbPath = join4(dir, "stash.db");
+  const out = [];
+  if (existsSync4(dir)) out.push(...checkDatabaseFiles(dir, o.now));
+  if (!existsSync4(dbPath)) return [result("database", "info", `no database at ${dbPath} yet; it will be created on first read`), ...out];
+  const st = statSync2(dbPath);
+  let facts;
+  try {
+    facts = await inspectDatabase(dbPath);
+  } catch (e) {
+    if (isCorruptMessage(e)) {
+      return [
+        result("database", "error", `${dbPath} is corrupt (${reason(e)})`, `it will be moved aside to stash.db.corrupt-<ms> on next start; or delete it`),
+        ...out
+      ];
+    }
+    return [result("database", "warn", `could not inspect ${dbPath} without writing (${reason(e)})`, `stop running servers and re-run doctor`), ...out];
+  }
+  if (facts.integrity !== "ok") {
+    out.unshift(result("database", "error", `${dbPath} failed quick_check (${facts.integrity})`, `it will be moved aside to stash.db.corrupt-<ms> on next start; or delete it`));
+    return out;
+  }
+  if (facts.userVersion > SCHEMA_VERSION) {
+    out.unshift(result("database-schema", "error", new SchemaTooNewError(facts.userVersion, SCHEMA_VERSION).message, "upgrade agent-file-stash or point FILESTASH_DIR at another directory"));
+  } else if (facts.userVersion < SCHEMA_VERSION) {
+    out.unshift(result("database-schema", "info", `schema version ${facts.userVersion} will be upgraded to ${SCHEMA_VERSION} on next start`));
+  } else {
+    out.unshift(result("database-schema", "ok", `database schema version ${facts.userVersion}, quick_check passed`));
+  }
+  if (o.platform !== "win32" && wide(st.mode, 63)) {
+    out.push(result("database-mode", "warn", `${dbPath} has mode ${octal(st.mode)}, expected 600`, `run: chmod 600 ${dbPath}`));
+  }
+  const parts = [formatBytes(st.size)];
+  if (facts.filesTracked !== void 0) parts.push(`${facts.filesTracked} files tracked`);
+  if (facts.pids) {
+    const live = facts.pids.filter(pidAlive).length;
+    parts.push(`${live} live and ${facts.pids.length - live} dead session(s)`);
+  }
+  out.push(result("database-stats", "info", `database ${parts.join(", ")}`));
+  return out;
+}
+function isExecutable(path) {
+  try {
+    if (!statSync2(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function commandResolves(command2, platform) {
+  if (isAbsolute2(command2) || command2.includes("/") || command2.includes("\\")) return isExecutable(command2);
+  const exts = platform === "win32" ? ["", ...(process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")] : [""];
+  return (process.env.PATH ?? "").split(delimiter).filter(Boolean).some((dir) => exts.some((ext) => isExecutable(join4(dir, command2 + ext))));
+}
+function splitCommand(entry) {
+  const raw = entry.command;
+  if (Array.isArray(raw) && typeof raw[0] === "string") return { command: raw[0], args: raw.slice(1).map(String) };
+  if (typeof raw !== "string") return void 0;
+  return { command: raw, args: Array.isArray(entry.args) ? entry.args.map(String) : [] };
+}
+function checkMcpRegistration(o) {
+  const out = [];
+  let found = 0;
+  for (const t of editorTargets(o.home)) {
+    if (!existsSync4(t.path)) continue;
+    found++;
+    const id = `mcp-${t.name.toLowerCase().replace(/\s+/g, "-")}`;
+    let config;
+    try {
+      config = readJson(t.path);
+    } catch {
+      out.push(result(id, "warn", `${t.name}: ${t.path} is not valid JSON`, `fix the file, then run: agent-file-stash init`));
+      continue;
+    }
+    const entry = asRecord(asRecord(asRecord(config)?.[t.key])?.filestash);
+    if (!entry) {
+      out.push(result(id, "warn", `${t.name}: no filestash entry in ${t.path}`, "run: agent-file-stash init"));
+      continue;
+    }
+    const cmd = splitCommand(entry);
+    if (!cmd) {
+      out.push(result(id, "warn", `${t.name}: the filestash entry in ${t.path} has no command`, "run: agent-file-stash init"));
+    } else if (!commandResolves(cmd.command, o.platform)) {
+      out.push(result(id, "warn", `${t.name}: command "${cmd.command}" was not found or is not executable`, `install it or fix the command in ${t.path}`));
+    } else if (!cmd.args.includes("serve")) {
+      out.push(result(id, "warn", `${t.name}: the filestash entry does not run "serve"`, `set the arguments to: agent-file-stash serve`));
+    } else {
+      out.push(result(id, "ok", `${t.name}: filestash registered in ${t.path}`));
+    }
+  }
+  if (found === 0) return [result("mcp", "info", "no editor configuration found (Claude Code, Cursor, OpenCode)")];
+  return out;
+}
+function matcherCovers(matcher, event) {
+  if (matcher === void 0 || matcher === "" || matcher === "*") return true;
+  if (typeof matcher !== "string") return false;
+  try {
+    return new RegExp(`^(?:${matcher})$`).test(event);
+  } catch {
+    return matcher.split("|").includes(event);
+  }
+}
+function commandRuns(command2, o, subcommand) {
+  const mentions = (text) => text.includes(PACKAGE_NAME) && subcommand.test(text);
+  if (mentions(command2)) return true;
+  const target = command2.trim().replace(/^(?:ba|z)?sh\s+/, "").split(/\s+/)[0].replace(/^["']|["']$/g, "").replace(/^~(?=\/)/, o.home).replace(/\$\{?(?:HOME)\}?/, o.home).replace(/\$\{?CLAUDE_PROJECT_DIR\}?/, o.cwd);
+  try {
+    const path = resolve4(o.cwd, target);
+    if (!statSync2(path).isFile() || statSync2(path).size > MAX_SCRIPT_BYTES) return false;
+    return mentions(readFileSync3(path, "utf-8"));
+  } catch {
+    return false;
+  }
+}
+function checkResetHook(o) {
+  const out = [];
+  const covered = /* @__PURE__ */ new Set();
+  let hookFile;
+  let hookFound = false;
+  const files = [
+    join4(o.home, ".claude", "settings.json"),
+    join4(o.cwd, ".claude", "settings.json"),
+    join4(o.cwd, ".claude", "settings.local.json")
+  ];
+  for (const file of files) {
+    if (!existsSync4(file)) continue;
+    let settings;
+    try {
+      settings = readJson(file);
+    } catch {
+      out.push(result("hook-settings", "warn", `${file} is not valid JSON`, "fix the file so hooks in it can be checked"));
+      continue;
+    }
+    const sessionStart = asRecord(asRecord(settings)?.hooks)?.SessionStart;
+    for (const entry of Array.isArray(sessionStart) ? sessionStart : []) {
+      const e = asRecord(entry);
+      const hooks = Array.isArray(e?.hooks) ? e.hooks : [];
+      const runs = hooks.some((h) => typeof asRecord(h)?.command === "string" && commandRuns(asRecord(h).command, o, /\breset\b/));
+      if (!runs) continue;
+      hookFound = true;
+      hookFile ??= file;
+      for (const ev of SESSION_START_TARGETS) if (matcherCovers(e?.matcher, ev)) covered.add(ev);
+    }
+  }
+  if (!hookFound) {
+    out.push(result("hook", "warn", "no SessionStart hook runs 'agent-file-stash reset'", "run: agent-file-stash init --hooks (without it a read after /clear or /compact can come back as unchanged)"));
+    return out;
+  }
+  const missing = SESSION_START_TARGETS.filter((ev) => !covered.has(ev));
+  if (missing.length > 0) {
+    out.push(result("hook", "warn", `reset hook in ${hookFile} does not match ${missing.join(" or ")}`, `set the matcher to "clear|compact"`));
+  } else {
+    out.push(result("hook", "ok", `reset hook configured for clear and compact (${hookFile})`));
+  }
+  return out;
+}
+function checkSubagentScopeHook(o) {
+  const files = [
+    join4(o.home, ".claude", "settings.json"),
+    join4(o.cwd, ".claude", "settings.json"),
+    join4(o.cwd, ".claude", "settings.local.json")
+  ];
+  for (const file of files) {
+    if (!existsSync4(file)) continue;
+    let settings;
+    try {
+      settings = readJson(file);
+    } catch {
+      continue;
+    }
+    const preToolUse = asRecord(asRecord(settings)?.hooks)?.PreToolUse;
+    for (const entry of Array.isArray(preToolUse) ? preToolUse : []) {
+      const e = asRecord(entry);
+      const hooks = Array.isArray(e?.hooks) ? e.hooks : [];
+      const runs = hooks.some((h) => typeof asRecord(h)?.command === "string" && commandRuns(asRecord(h).command, o, /\bhook\s+subagent-scope\b/));
+      if (runs && matcherCovers(e?.matcher, "mcp__filestash__read_file")) {
+        return [result("hook-subagent-scope", "ok", `subagent scope hook configured (${file})`)];
+      }
+    }
+  }
+  return [result("hook-subagent-scope", "warn", "no PreToolUse hook runs 'agent-file-stash hook subagent-scope' for the stash read tools", "run: agent-file-stash init --hooks (without it subagents share read tracking with the main agent)")];
+}
+function checkEnv() {
+  const out = [];
+  const exclude = process.env.FILESTASH_EXCLUDE;
+  if (exclude !== void 0 && exclude !== "") {
+    const n = exclude.split(",").filter((p) => p.trim()).length;
+    out.push(result("env-exclude", "ok", `FILESTASH_EXCLUDE: ${n} pattern(s)`));
+  }
+  for (const name of ["FILESTASH_MAX_LINES", "FILESTASH_MAX_CHARS"]) {
+    const raw = process.env[name];
+    if (raw === void 0 || raw === "") continue;
+    const valid = /^[1-9]\d*$/.test(raw) && Number.isSafeInteger(Number(raw));
+    out.push(
+      valid ? result(`env-${name.toLowerCase()}`, "ok", `${name}=${raw}`) : result(`env-${name.toLowerCase()}`, "warn", `${name}=${JSON.stringify(raw)} is not a positive integer and is ignored`, `set ${name} to a positive integer or unset it`)
+    );
+  }
+  return out;
+}
+function npmLatestVersion() {
+  const res = spawnSync("npm", ["view", PACKAGE_NAME, "version"], {
+    encoding: "utf-8",
+    timeout: NPM_TIMEOUT_MS,
+    shell: process.platform === "win32"
+  });
+  const version = res.status === 0 ? res.stdout.trim() : "";
+  return /^\d+\.\d+\.\d+/.test(version) ? version : void 0;
+}
+function newer(a, b) {
+  const pa = a.split(/[.-]/).map(Number);
+  const pb = b.split(/[.-]/).map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  return false;
+}
+function checkUpdates(o) {
+  if (!o.checkUpdates) return [];
+  const installed = ownPackageJson()?.version;
+  const latest = o.fetchLatest();
+  if (!installed || !latest) return [result("updates", "info", "could not check for updates")];
+  if (newer(latest, installed)) return [result("updates", "info", `update available: ${installed} -> ${latest} (npm install -g ${PACKAGE_NAME})`)];
+  return [result("updates", "ok", `agent-file-stash ${installed} is up to date`)];
+}
+var CHECKS = [
+  ["node", checkNode],
+  ["stash-dir", checkStashDir],
+  ["database", checkDatabase],
+  ["mcp", checkMcpRegistration],
+  ["hook", checkResetHook],
+  ["hook-subagent-scope", checkSubagentScopeHook],
+  ["env", checkEnv],
+  ["updates", checkUpdates]
+];
+function defaultOptions(argv = []) {
+  return {
+    nodeVersion: process.versions.node,
+    cwd: process.cwd(),
+    home: homedir(),
+    platform: process.platform,
+    now: Date.now(),
+    checkUpdates: argv.includes("--check-updates"),
+    fetchLatest: npmLatestVersion
+  };
+}
+async function runChecks(o, checks = CHECKS) {
+  const results = [];
+  for (const [id, check] of checks) {
+    try {
+      results.push(...await check(o));
+    } catch (e) {
+      results.push(result(id, "warn", `check failed: ${reason(e)}`));
+    }
+  }
+  return results;
+}
+function summarize(results) {
+  const count = (s) => results.filter((r) => r.status === s).length;
+  return { ok: count("ok"), warnings: count("warn"), errors: count("error") };
+}
+function formatHuman(results) {
+  const lines = results.flatMap((r) => [`[${r.status}] ${r.message}`, ...r.hint ? [`    ${r.hint}`] : []]);
+  const s = summarize(results);
+  return [...lines, "", `${s.ok} ok, ${s.warnings} warnings, ${s.errors} errors`].join("\n");
+}
+async function runDoctor(argv, overrides = {}) {
+  const results = await runChecks({ ...defaultOptions(argv), ...overrides });
+  console.log(argv.includes("--json") ? JSON.stringify(results, null, 2) : formatHuman(results));
+  return summarize(results).errors > 0 ? 1 : 0;
+}
+
+// packages/cli/src/hook.ts
+var HOOK_STDIN_TIMEOUT_MS = 1e3;
+var AGENT_ID_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+var STASH_READ_TOOL = /__read_files?$/;
+async function readHookStdin() {
+  if (process.stdin.isTTY) return "";
+  const read = (async () => {
+    let raw = "";
+    for await (const chunk of process.stdin) raw += chunk;
+    return raw;
+  })();
+  const timeout = new Promise((res) => setTimeout(() => res(""), HOOK_STDIN_TIMEOUT_MS).unref());
+  return (await Promise.race([read, timeout])).trim();
+}
+function subagentScopeOutput(raw) {
+  try {
+    const input = JSON.parse(raw);
+    const { agent_id: agentId, tool_name: toolName, tool_input: toolInput } = input;
+    if (typeof agentId !== "string" || !AGENT_ID_PATTERN.test(agentId)) return void 0;
+    if (typeof toolName !== "string" || !STASH_READ_TOOL.test(toolName)) return void 0;
+    if (typeof toolInput !== "object" || toolInput === null || Array.isArray(toolInput)) return void 0;
+    return JSON.stringify({
+      hookSpecificOutput: { hookEventName: "PreToolUse", updatedInput: { ...toolInput, agent: agentId } }
+    });
+  } catch {
+    return void 0;
+  }
+}
+async function runSubagentScopeHook() {
+  try {
+    const out = subagentScopeOutput(await readHookStdin());
+    if (out) process.stdout.write(out + "\n");
+  } catch {
+  }
+}
+
 // packages/cli/src/index.ts
 var _origEmitWarning = process.emitWarning;
 process.emitWarning = function(msg, ...args) {
@@ -744,34 +1776,127 @@ process.emitWarning = function(msg, ...args) {
   return _origEmitWarning.apply(process, [msg, ...args]);
 };
 var CLI_STATUS_SESSION = "cli-status";
+var RESET_HOOK_COMMAND = "npx agent-file-stash reset --from-hook";
+var RESET_HOOK_ENTRY = {
+  matcher: "clear|compact",
+  hooks: [{ type: "command", command: RESET_HOOK_COMMAND }]
+};
+var SCOPE_HOOK_COMMAND = "npx agent-file-stash hook subagent-scope";
+var SCOPE_HOOK_ENTRY = {
+  matcher: "mcp__(filestash|agent-file-stash)__read_files?",
+  hooks: [{ type: "command", command: SCOPE_HOOK_COMMAND }]
+};
+function assertHealthy(stash) {
+  if (stash.isDegraded) throw new Error(stash.degradedReason);
+}
+async function readHookCwd() {
+  const raw = await readHookStdin();
+  if (!raw) return void 0;
+  try {
+    const cwd = JSON.parse(raw)?.cwd;
+    return typeof cwd === "string" && cwd !== "" ? cwd : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function runReset(fromHook) {
+  try {
+    const hookCwd = fromHook ? await readHookCwd() : void 0;
+    const dbPath = join5(resolveStashDir(hookCwd), "stash.db");
+    if (!existsSync5(dbPath)) {
+      if (!fromHook) console.log("No filestash database found. Nothing to reset.");
+      return;
+    }
+    const { stash } = createStash({ dbPath, sessionId: CLI_STATUS_SESSION, recoverCorrupt: false, quiet: true });
+    try {
+      await stash.init();
+      assertHealthy(stash);
+      await stash.resetReads();
+      assertHealthy(stash);
+    } finally {
+      await stash.close();
+    }
+    if (!fromHook) console.log("Read tracking reset. The next read of each file returns full content.");
+  } catch (e) {
+    console.error(`filestash reset failed: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(fromHook ? 0 : 1);
+  }
+}
+function hooksSnippet() {
+  return JSON.stringify({ hooks: { SessionStart: [RESET_HOOK_ENTRY], PreToolUse: [SCOPE_HOOK_ENTRY] } }, null, 2);
+}
+var HOOK_INSTALLS = [
+  { event: "SessionStart", entry: RESET_HOOK_ENTRY },
+  { event: "PreToolUse", entry: SCOPE_HOOK_ENTRY }
+];
+function hasHookCommand(entries, command2) {
+  return Array.isArray(entries) && entries.some((e) => e?.hooks?.some((h) => h?.command === command2));
+}
+function installClaudeHook(home) {
+  const settingsPath = join5(home, ".claude", "settings.json");
+  let settings = {};
+  const existed = existsSync5(settingsPath);
+  if (existed) {
+    try {
+      settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
+    } catch {
+      console.error(`  Claude Code hooks: ${settingsPath} is not valid JSON, left untouched`);
+      return;
+    }
+  }
+  const hooks = settings.hooks ?? {};
+  const missing = HOOK_INSTALLS.filter(({ event, entry }) => !hasHookCommand(hooks[event], entry.hooks[0].command));
+  if (missing.length === 0) {
+    console.log("  Claude Code hooks: already configured");
+    return;
+  }
+  if (existed) copyFileSync(settingsPath, `${settingsPath}.bak`);
+  else mkdirSync2(join5(home, ".claude"), { recursive: true });
+  const merged = { ...hooks };
+  for (const { event, entry } of missing) {
+    merged[event] = [...Array.isArray(hooks[event]) ? hooks[event] : [], entry];
+  }
+  settings.hooks = merged;
+  writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  console.log(`  Claude Code hooks: configured (${settingsPath})`);
+}
 async function runStatus() {
-  const stashDir = resolve4(process.env.FILESTASH_DIR ?? ".file-stash");
-  const dbPath = join3(stashDir, "stash.db");
-  if (!existsSync4(dbPath)) {
-    console.log("No filestash database found. Run 'filestash serve' to start stashing.");
+  const stashDir = resolve5(process.env.FILESTASH_DIR ?? ".file-stash");
+  const dbPath = join5(stashDir, "stash.db");
+  if (!existsSync5(dbPath)) {
+    console.log("No filestash database found. Run 'agent-file-stash serve' to start stashing.");
     process.exit(0);
   }
-  const { stash } = createStash({ dbPath, sessionId: CLI_STATUS_SESSION });
-  await stash.init();
-  const stats = await stash.getStats();
-  console.log(`filestash status:`);
-  console.log(`  Files tracked:          ${stats.filesTracked}`);
-  console.log(`  Tokens saved (total):   ~${stats.tokensSaved.toLocaleString()}`);
-  await stash.close();
+  const { stash } = createStash({ dbPath, sessionId: CLI_STATUS_SESSION, recoverCorrupt: false, quiet: true });
+  try {
+    await stash.init();
+    assertHealthy(stash);
+    const stats = await stash.getStats();
+    assertHealthy(stash);
+    console.log(`filestash status:`);
+    console.log(`  Files tracked:          ${stats.filesTracked}`);
+    console.log(`  Tokens saved (total):   ~${stats.tokensSaved.toLocaleString()}`);
+  } catch (e) {
+    console.error(`filestash status failed for ${dbPath}: ${e instanceof Error ? e.message : String(e)}`);
+    process.exitCode = 1;
+  } finally {
+    await stash.close();
+  }
 }
 async function runStatusAll(root) {
-  const databases = findStashDatabases(resolve4(root));
+  const databases = findStashDatabases(resolve5(root));
   if (databases.length === 0) {
-    console.log(`No filestash databases found under ${resolve4(root)}.`);
+    console.log(`No filestash databases found under ${resolve5(root)}.`);
     return;
   }
   const rows = [];
   for (const dbPath of databases) {
-    const { stash } = createStash({ dbPath, sessionId: CLI_STATUS_SESSION });
+    const { stash } = createStash({ dbPath, sessionId: CLI_STATUS_SESSION, recoverCorrupt: false, quiet: true });
     try {
       await stash.init();
       const stats = await stash.getStats();
-      rows.push({ project: resolve4(dbPath, "../..").replace(/\/\.vscode$/, ""), files: stats.filesTracked, tokens: stats.tokensSaved });
+      assertHealthy(stash);
+      rows.push({ project: resolve5(dbPath, "../..").replace(/\/\.vscode$/, ""), files: stats.filesTracked, tokens: stats.tokensSaved });
     } catch (e) {
       console.error(`  skipped ${dbPath}: ${e instanceof Error ? e.message : String(e)}`);
     } finally {
@@ -781,7 +1906,7 @@ async function runStatusAll(root) {
   rows.sort((a, b) => b.tokens - a.tokens);
   const totalTokens = rows.reduce((sum, r) => sum + r.tokens, 0);
   const totalFiles = rows.reduce((sum, r) => sum + r.files, 0);
-  console.log(`filestash status (${rows.length} databases under ${resolve4(root)}):`);
+  console.log(`filestash status (${rows.length} databases under ${resolve5(root)}):`);
   for (const r of rows) {
     console.log(`  ~${r.tokens.toLocaleString().padStart(10)} tokens  ${String(r.files).padStart(5)} files  ${r.project}`);
   }
@@ -789,45 +1914,17 @@ async function runStatusAll(root) {
   console.log(`
 Savings count re-reads within a session (unchanged files and diffs); a new session always receives full content.`);
 }
-async function runInit() {
-  const home = homedir();
-  const mcpServersEntry = {
-    command: "npx",
-    args: ["agent-file-stash", "serve"]
-  };
-  const opencodeMcpEntry = {
-    type: "local",
-    command: ["npx", "agent-file-stash", "serve"]
-  };
-  const xdgConfig = process.env.XDG_CONFIG_HOME || join3(home, ".config");
-  const targets = [
-    {
-      name: "Claude Code",
-      path: join3(home, ".claude.json"),
-      key: "mcpServers",
-      entry: mcpServersEntry
-    },
-    {
-      name: "Cursor",
-      path: join3(home, ".cursor", "mcp.json"),
-      key: "mcpServers",
-      entry: mcpServersEntry
-    },
-    {
-      name: "OpenCode",
-      path: join3(xdgConfig, "opencode", "opencode.json"),
-      key: "mcp",
-      entry: opencodeMcpEntry
-    }
-  ];
+async function runInit(withHooks) {
+  const home = homedir2();
+  const targets = editorTargets(home);
   let configured = 0;
   for (const target of targets) {
-    const dir = join3(target.path, "..");
-    if (!existsSync4(dir)) continue;
+    const dir = join5(target.path, "..");
+    if (!existsSync5(dir)) continue;
     let config = {};
-    if (existsSync4(target.path)) {
+    if (existsSync5(target.path)) {
       try {
-        config = JSON.parse(readFileSync3(target.path, "utf-8"));
+        config = JSON.parse(readFileSync4(target.path, "utf-8"));
       } catch {
         config = {};
       }
@@ -839,16 +1936,16 @@ async function runInit() {
       continue;
     }
     config[target.key] = { ...section, filestash: target.entry };
-    writeFileSync(target.path, JSON.stringify(config, null, 2) + "\n");
+    writeFileSync2(target.path, JSON.stringify(config, null, 2) + "\n");
     console.log(`  ${target.name}: configured (${target.path})`);
     configured++;
   }
   if (configured === 0) {
-    console.log("No supported tools detected. You can manually add filestash to your MCP config:");
-    console.log(JSON.stringify({ mcpServers: { "agent-file-stash": mcpServersEntry } }, null, 2));
+    console.log("No supported tools detected. You can manually add agent-file-stash to your MCP config:");
+    console.log(JSON.stringify({ mcpServers: { "agent-file-stash": targets[0].entry } }, null, 2));
   } else {
     console.log(`
-Done! Restart your editor to pick up filestash.`);
+Done! Restart your editor to pick up agent-file-stash.`);
     console.log(`
 Available MCP tools:`);
     console.log(`  read_file        Read a file, returning only a diff if unchanged since last read`);
@@ -858,33 +1955,59 @@ Available MCP tools:`);
     console.log(`
 Stash location: FILESTASH_DIR env var (default: .file-stash in cwd)`);
   }
+  console.log(`
+Context resets: after /clear or /compact the model loses file contents the stash still considers read.`);
+  if (withHooks) {
+    installClaudeHook(home);
+  } else {
+    console.log(`Add this to ~/.claude/settings.json (or re-run 'init --hooks' to merge it):
+`);
+    console.log(hooksSnippet());
+  }
 }
 function runHelp() {
   console.log(`agent-file-stash - Agent file stash with diff tracking
 
 Usage:
   agent-file-stash init      Auto-configure for your editor
+  agent-file-stash init --hooks
+                             Also add the Claude Code hooks (context reset, subagent read scope) to ~/.claude/settings.json
+  agent-file-stash reset     Forget what was read so the next read returns full content
+                             (--from-hook: quiet mode for Claude Code hooks)
+  agent-file-stash hook subagent-scope
+                             PreToolUse hook that gives each subagent its own read tracking (no output otherwise)
   agent-file-stash serve     Start the MCP server (default)
   agent-file-stash status    Show stash statistics
   agent-file-stash status --all [dir]
                              Sum statistics of every stash under dir (default: home)
+  agent-file-stash doctor    Check the install and report what to fix (read-only)
+                             (--json: machine-readable output, --check-updates: ask npm for the latest version)
   agent-file-stash help      Show this help message
 
 Environment:
-  FILESTASH_DIR       Stash directory (default: .file-stash)`);
+  FILESTASH_DIR       Stash directory (default: .file-stash)
+  FILESTASH_EXCLUDE   Extra comma-separated file name globs that are never stored
+  FILESTASH_MAX_LINES Max lines returned per read (default: 2000)
+  FILESTASH_MAX_CHARS Max characters returned per read (default: 100000)`);
 }
 var command = process.argv[2];
 if (!command || command === "serve") {
   await startMcpServer();
 } else if (command === "status" && process.argv[3] === "--all") {
-  await runStatusAll(process.argv[4] ?? homedir());
+  await runStatusAll(process.argv[4] ?? homedir2());
 } else if (command === "status") {
   await runStatus();
 } else if (command === "init") {
-  await runInit();
+  await runInit(process.argv.includes("--hooks"));
+} else if (command === "reset") {
+  await runReset(process.argv.includes("--from-hook"));
+} else if (command === "hook" && process.argv[3] === "subagent-scope") {
+  await runSubagentScopeHook();
+} else if (command === "doctor") {
+  process.exitCode = await runDoctor(process.argv.slice(3));
 } else if (command === "help" || command === "--help") {
   runHelp();
 } else {
-  console.error(`Unknown command: ${command}. Run 'filestash help' for usage.`);
+  console.error(`Unknown command: ${command}. Run 'agent-file-stash help' for usage.`);
   process.exit(1);
 }