agent-file-stash 0.3.0 → 0.5.0

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 #!/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
@@ -141,6 +141,38 @@ function longestCommonSubsequence(a, b) {
   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 = `
 CREATE TABLE IF NOT EXISTS file_versions (
@@ -160,6 +192,21 @@ 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
+);
+
 CREATE TABLE IF NOT EXISTS stats (
   key   TEXT PRIMARY KEY,
   value INTEGER NOT NULL DEFAULT 0
@@ -174,6 +221,40 @@ CREATE TABLE IF NOT EXISTS session_stats (
 
 INSERT OR IGNORE INTO stats (key, value) VALUES ('tokens_saved', 0);
 `;
+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;
+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);
 }
@@ -181,6 +262,74 @@ 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 {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    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);
+}
 function queryOne(db, sql, params = []) {
   const rows = db.prepare(sql).all(...params);
   return rows[0];
@@ -189,65 +338,250 @@ 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.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(SCHEMA);
+    try {
+      this.db = await this.openWithRetry();
+    } catch (err) {
+      await this.recoverOrDegrade(err);
+    }
     this.initialized = true;
   }
-  getDb() {
-    if (!this.db) throw new Error("StashStore not initialized. Call init() first.");
-    return this.db;
+  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");
+      db.exec(SCHEMA);
+      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)");
+      db.exec("DELETE FROM session_ranges WHERE session_id 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) {
+      try {
+        db.exec("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    }
+  }
+  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 result = { stashed: false, content: `[filestash: file too large (${size} bytes); not read]`, hash: "" };
+      return { absPath, size, content: "", hash: "", lines: 0, now, early: { result, 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 result = { stashed: false, content: `[filestash: binary file (${size} bytes), not shown]`, hash, totalLines: lines };
+      snap.early = { result, countRead: true };
+    }
+    return snap;
+  }
+  earlyResult(snap) {
+    const { result, countRead } = snap.early;
+    if (countRead) {
+      const tokens = estimateTokens(result.content);
+      this.guarded((db) => this.recordRead(db, tokens, tokens));
+    }
+    return result;
+  }
+  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
     };
+    if (this.db) {
+      try {
+        return this.readWithDb(this.db, state);
+      } catch (err) {
+        this.degrade(err);
+      }
+    }
+    return this.plainResult(state);
+  }
+  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]
+      [this.sessionId, state.absPath]
     );
     if (!lastRead) {
       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);
   }
@@ -256,52 +590,106 @@ var StashStore = class {
     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 };
+    this.clearRanges(db, s.absPath);
+    return this.fullSlice(db, s);
+  }
+  requestedEnd(s) {
+    return Math.min(s.rangeEnd, s.currentLines);
+  }
+  getRanges(db, absPath, hash) {
+    const rows = db.prepare(
+      "SELECT start_line, end_line FROM session_ranges WHERE session_id = ? AND path = ? AND hash = ?"
+    ).all(this.sessionId, absPath, hash);
+    return rows.map((r) => [r.start_line, r.end_line]);
+  }
+  coversRequest(db, s, hash) {
+    return coversRange(this.getRanges(db, s.absPath, hash), s.rangeStart, this.requestedEnd(s));
+  }
+  clearRanges(db, absPath) {
+    db.prepare("DELETE FROM session_ranges WHERE session_id = ? AND path = ?").run(this.sessionId, absPath);
+  }
+  addRange(db, absPath, hash, start, end) {
+    if (end < start) return;
+    const merged = mergeIntervals([...this.getRanges(db, absPath, hash), [start, end]]);
+    db.prepare("DELETE FROM session_ranges WHERE session_id = ? AND path = ? AND hash = ?").run(this.sessionId, 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(this.sessionId, absPath, hash, a, b);
+  }
+  handleUncovered(db, s) {
+    db.prepare(
+      "UPDATE session_reads SET read_at = ? WHERE session_id = ? AND path = ?"
+    ).run(s.now, this.sessionId, s.absPath);
+    return this.fullSlice(db, s);
+  }
+  fullSlice(db, s) {
+    const content = s.slice;
+    this.addRange(db, 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.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 };
+    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.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) {
+    this.clearRanges(db, 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.absPath, s.currentHash, 1, s.currentLines);
+    this.recordRead(db, contentTokens, diffTokens);
     return {
       stashed: true,
       content: diffResult.diff,
@@ -311,13 +699,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;
@@ -329,67 +710,129 @@ 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.
+  // 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) {
     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 result = { stashed: false, content: slice.text, hash, totalLines: lines };
+    if (!this.db) return result;
+    try {
+      const tokens = estimateTokens(slice.text);
+      if (this.isStoreable(snap)) {
+        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(this.sessionId, absPath, hash, now);
+        this.clearRanges(this.db, absPath);
+        this.addRange(this.db, absPath, hash, slice.start, slice.end);
+      }
+      this.recordRead(this.db, tokens, tokens);
+    } catch (err) {
+      this.degrade(err);
+    }
+    return result;
   }
   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 = [];
@@ -403,26 +846,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);
     }
@@ -435,7 +891,7 @@ var FileWatcher = class {
   }
   async handleChange(filePath) {
     try {
-      if (!existsSync(filePath)) {
+      if (!existsSync2(filePath)) {
         await this.stash.onFileDeleted(filePath);
       }
     } catch (e) {
@@ -457,7 +913,7 @@ 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 { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2, copyFileSync, mkdirSync as mkdirSync2 } from "node:fs";
 import { homedir } from "node:os";
 
 // packages/cli/src/mcp.ts
@@ -465,14 +921,28 @@ 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;
@@ -499,10 +969,90 @@ ${result.diff}`;
   return `=== ${path} ===
 ${result.content}`;
 }
-function statsSuffix(tokensSaved) {
+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")
+};
+var readFilesShape = {
+  paths: z.preprocess(
+    (val) => typeof val === "string" ? JSON.parse(val) : val,
+    z.array(z.string())
+  ).describe("File paths")
+};
+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 degradedLine(reason = "unknown") {
+  return `Mode: DEGRADED (${reason}) - 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) {
   const absPath = resolve3(path);
@@ -531,15 +1081,16 @@ 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 server = new McpServer({
@@ -548,21 +1099,7 @@ async function startMcpServer() {
   });
   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")
-      }
-    },
+    TOOL_DEFS.read_file,
     async ({ path, force, offset, limit }) => {
       const absPath = resolve3(path);
       if (!isPathAllowed(absPath, cwd)) {
@@ -596,17 +1133,7 @@ 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")
-      }
-    },
+    TOOL_DEFS.read_files,
     async ({ paths }) => {
       const results = await Promise.all(paths.map((p) => readSingleFile(p, cwd, stash)));
       const successfulPaths = paths.filter((_, i) => results[i].ok);
@@ -627,31 +1154,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 }
@@ -703,20 +1230,104 @@ 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 HOOK_STDIN_TIMEOUT_MS = 1e3;
+function assertHealthy(stash) {
+  if (stash.isDegraded) throw new Error(stash.degradedReason);
+}
+async function readHookCwd() {
+  if (process.stdin.isTTY) return void 0;
+  const read = (async () => {
+    let raw2 = "";
+    for await (const chunk of process.stdin) raw2 += chunk;
+    return raw2;
+  })();
+  const timeout = new Promise((res) => setTimeout(() => res(""), HOOK_STDIN_TIMEOUT_MS).unref());
+  const raw = (await Promise.race([read, timeout])).trim();
+  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 = join3(resolveStashDir(hookCwd), "stash.db");
+    if (!existsSync4(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] } }, null, 2);
+}
+function installClaudeHook(home) {
+  const settingsPath = join3(home, ".claude", "settings.json");
+  let settings = {};
+  const existed = existsSync4(settingsPath);
+  if (existed) {
+    try {
+      settings = JSON.parse(readFileSync3(settingsPath, "utf-8"));
+    } catch {
+      console.error(`  Claude Code hook: ${settingsPath} is not valid JSON, left untouched`);
+      return;
+    }
+  }
+  const hooks = settings.hooks ?? {};
+  const sessionStart = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+  if (sessionStart.some((e) => e?.hooks?.some((h) => h?.command === RESET_HOOK_COMMAND))) {
+    console.log("  Claude Code hook: already configured");
+    return;
+  }
+  if (existed) copyFileSync(settingsPath, `${settingsPath}.bak`);
+  else mkdirSync2(join3(home, ".claude"), { recursive: true });
+  settings.hooks = { ...hooks, SessionStart: [...sessionStart, RESET_HOOK_ENTRY] };
+  writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  console.log(`  Claude Code hook: 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.");
+    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));
@@ -726,10 +1337,11 @@ async function runStatusAll(root) {
   }
   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();
+      assertHealthy(stash);
       rows.push({ project: resolve4(dbPath, "../..").replace(/\/\.vscode$/, ""), files: stats.filesTracked, tokens: stats.tokensSaved });
     } catch (e) {
       console.error(`  skipped ${dbPath}: ${e instanceof Error ? e.message : String(e)}`);
@@ -748,7 +1360,7 @@ 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() {
+async function runInit(withHooks) {
   const home = homedir();
   const mcpServersEntry = {
     command: "npx",
@@ -798,16 +1410,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("No supported tools detected. You can manually add agent-file-stash to your MCP config:");
     console.log(JSON.stringify({ mcpServers: { "agent-file-stash": mcpServersEntry } }, 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`);
@@ -817,12 +1429,25 @@ 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 context-reset hook 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 serve     Start the MCP server (default)
   agent-file-stash status    Show stash statistics
   agent-file-stash status --all [dir]
@@ -830,7 +1455,10 @@ Usage:
   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") {
@@ -840,10 +1468,12 @@ if (!command || command === "serve") {
 } 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 === "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);
 }