agent-file-stash 0.5.0 → 0.6.1

package/dist/cli.mjs

@@ -7,39 +7,111 @@ 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 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);
-  if (linesChanged === 0) {
-    return { diff: "", linesChanged: 0, hasChanges: false, changedNewLines };
-  }
   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,38 +175,6 @@ 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";
@@ -173,8 +208,8 @@ function isExcludedPath(absPath, extraPatterns = []) {
   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,
@@ -221,11 +256,62 @@ 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;
+var LIFETIME_KEYS = [
+  "reads_total",
+  "baseline_tokens_total",
+  "sent_tokens_total",
+  "sessions_total",
+  "overhead_tokens_total",
+  "counters_since"
+];
 function positiveOr(value, fallback) {
   return Number.isInteger(value) && value > 0 ? value : fallback;
 }
@@ -330,6 +416,7 @@ 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];
@@ -348,9 +435,10 @@ var StashStore = class {
   recoveryAttempted = false;
   recoveredFrom;
   reason;
+  sessionCounted = false;
   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;
@@ -390,7 +478,7 @@ var StashStore = class {
     try {
       db.exec("PRAGMA busy_timeout=5000");
       db.exec("PRAGMA journal_mode=WAL");
-      db.exec(SCHEMA);
+      runMigrations(db);
       this.registerSession(db);
       this.pruneClosedSessions(db);
     } catch (err) {
@@ -478,8 +566,9 @@ var StashStore = class {
           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)");
+      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)"
@@ -506,26 +595,26 @@ var StashStore = class {
     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 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");
     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 };
+      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, countRead } = snap.early;
+    const { result: result2, countRead } = snap.early;
     if (countRead) {
-      const tokens = estimateTokens(result.content);
+      const tokens = estimateTokens(result2.content);
       this.guarded((db) => this.recordRead(db, tokens, tokens));
     }
-    return result;
+    return result2;
   }
   isStoreable(snap) {
     return snap.size <= this.maxStoreBytes && !isExcludedPath(snap.absPath, this.exclude);
@@ -551,7 +640,8 @@ var StashStore = class {
       now,
       size: snap.size,
       slice: slice.text,
-      midLine: slice.midLine
+      midLine: slice.midLine,
+      tid: this.trackingId(options?.scope)
     };
     if (this.db) {
       try {
@@ -562,6 +652,22 @@ var StashStore = class {
     }
     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 };
   }
@@ -574,9 +680,10 @@ var StashStore = class {
     const lastRead = queryOne(
       db,
       "SELECT hash FROM session_reads WHERE session_id = ? AND path = ?",
-      [this.sessionId, state.absPath]
+      [state.tid, state.absPath]
     );
     if (!lastRead) {
+      this.ensureScopeCapacity(db, state.tid);
       return this.handleFirstRead(db, state);
     }
     const lastHash = lastRead.hash;
@@ -589,43 +696,43 @@ 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);
-    this.clearRanges(db, s.absPath);
+    ).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, absPath, hash) {
+  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(this.sessionId, absPath, 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.absPath, hash), s.rangeStart, this.requestedEnd(s));
+    return coversRange(this.getRanges(db, s.tid, 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);
+  clearRanges(db, tid, absPath) {
+    db.prepare("DELETE FROM session_ranges WHERE session_id = ? AND path = ?").run(tid, absPath);
   }
-  addRange(db, absPath, hash, start, end) {
+  addRange(db, tid, 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 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(this.sessionId, absPath, hash, a, b);
+    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, this.sessionId, s.absPath);
+    ).run(s.now, s.tid, 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.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 };
   }
@@ -636,7 +743,7 @@ var StashStore = class {
     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));
+    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 };
@@ -647,7 +754,7 @@ var StashStore = class {
   handleUnchanged(db, s) {
     db.prepare(
       "UPDATE session_reads SET read_at = ? WHERE session_id = ? AND path = ?"
-    ).run(s.now, this.sessionId, s.absPath);
+    ).run(s.now, s.tid, s.absPath);
     return this.unchangedLabel(
       db,
       s,
@@ -660,12 +767,12 @@ var StashStore = class {
       "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);
+    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);
-    this.clearRanges(db, s.absPath);
+    ).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) {
@@ -688,7 +795,7 @@ var StashStore = class {
     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.addRange(db, s.tid, s.absPath, s.currentHash, 1, s.currentLines);
     this.recordRead(db, contentTokens, diffTokens);
     return {
       stashed: true,
@@ -711,29 +818,31 @@ var StashStore = class {
     ).run(absPath, hash, content, lines, now);
   }
   // 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) {
+  async readFileFull(filePath, scope) {
     await this.init();
     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;
+    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(this.sessionId, absPath, hash, now);
-        this.clearRanges(this.db, absPath);
-        this.addRange(this.db, absPath, hash, slice.start, slice.end);
+        ).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 result;
+    return result2;
   }
   async onFileDeleted(filePath) {
     await this.init();
@@ -759,6 +868,8 @@ var StashStore = class {
       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;
+      const lifetime = (key) => queryOne(db, "SELECT value FROM stats WHERE key = ?", [key])?.value ?? 0;
+      const since = queryOne(db, "SELECT value FROM stats WHERE key = 'counters_since'")?.value;
       return {
         filesTracked: versionRow?.c ?? 0,
         tokensSaved: tokenRow?.value ?? 0,
@@ -766,6 +877,12 @@ var StashStore = class {
         sessionReads: sessionStat("reads"),
         sessionBaselineTokens: sessionStat("baseline_tokens"),
         sessionSentTokens: sessionStat("sent_tokens"),
+        lifetimeSessions: lifetime("sessions_total"),
+        lifetimeReads: lifetime("reads_total"),
+        lifetimeBaselineTokens: lifetime("baseline_tokens_total"),
+        lifetimeSentTokens: lifetime("sent_tokens_total"),
+        lifetimeOverheadTokens: lifetime("overhead_tokens_total"),
+        ...since !== void 0 && since > 0 && { countersSince: since },
         degraded: false,
         ...this.recoveredFrom && { recoveredFrom: this.recoveredFrom }
       };
@@ -778,6 +895,11 @@ var StashStore = class {
       sessionReads: 0,
       sessionBaselineTokens: 0,
       sessionSentTokens: 0,
+      lifetimeSessions: 0,
+      lifetimeReads: 0,
+      lifetimeBaselineTokens: 0,
+      lifetimeSentTokens: 0,
+      lifetimeOverheadTokens: 0,
       degraded: true,
       ...this.reason && { degradedReason: this.reason }
     };
@@ -790,6 +912,7 @@ var StashStore = class {
       db.prepare("DELETE FROM session_ranges").run();
       db.prepare("DELETE FROM session_stats").run();
       db.prepare("UPDATE stats SET value = 0").run();
+      db.prepare(`DELETE FROM stats WHERE key IN (${LIFETIME_KEYS.map(() => "?").join(", ")})`).run(...LIFETIME_KEYS);
     });
   }
   async resetReads() {
@@ -817,6 +940,19 @@ var StashStore = class {
     this.bumpSessionStat(db, "baseline_tokens", baseline);
     this.bumpSessionStat(db, "sent_tokens", sent);
     if (baseline > sent) this.addTokensSaved(db, baseline - sent);
+    this.bumpLifetime(db, { reads_total: 1, baseline_tokens_total: baseline, sent_tokens_total: sent });
+  }
+  bumpLifetime(db, counters) {
+    db.prepare("INSERT OR IGNORE INTO stats (key, value) VALUES ('counters_since', ?)").run(Date.now());
+    const bump = db.prepare("INSERT INTO stats (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = value + ?");
+    for (const [key, n] of Object.entries(counters)) bump.run(key, n, n);
+  }
+  async recordSessionStart(overheadTokens) {
+    await this.init();
+    if (this.sessionCounted) return;
+    this.sessionCounted = true;
+    const overhead = Number.isFinite(overheadTokens) && overheadTokens > 0 ? Math.round(overheadTokens) : 0;
+    this.guarded((db) => this.bumpLifetime(db, { sessions_total: 1, overhead_tokens_total: overhead }));
   }
   bumpSessionStat(db, key, n) {
     db.prepare(
@@ -901,6 +1037,23 @@ var FileWatcher = class {
   }
 };
 
+// packages/sdk/src/lifetime.ts
+function lifetimeView(c) {
+  const grossSaved = c.lifetimeBaselineTokens - c.lifetimeSentTokens;
+  const netSaved = grossSaved - c.lifetimeOverheadTokens;
+  return {
+    empty: c.lifetimeSessions === 0 && c.lifetimeReads === 0,
+    sessions: c.lifetimeSessions,
+    reads: c.lifetimeReads,
+    baselineTokens: c.lifetimeBaselineTokens,
+    sentTokens: c.lifetimeSentTokens,
+    overheadTokens: c.lifetimeOverheadTokens,
+    grossSaved,
+    netSaved,
+    netPerSession: c.lifetimeSessions > 0 ? Math.round(netSaved / c.lifetimeSessions) || 0 : null
+  };
+}
+
 // packages/sdk/src/index.ts
 function createStash(config) {
   const stash = new StashStore(config);
@@ -912,13 +1065,11 @@ 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 as writeFileSync2, copyFileSync, mkdirSync as mkdirSync2 } 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 { readFileSync as readFileSync2, realpathSync } from "node:fs";
@@ -954,32 +1105,34 @@ 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")
+  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")
+  ).describe("File paths"),
+  agent: z.string().optional()
 };
 var TOOL_DEFS = {
   read_file: {
@@ -1029,8 +1182,24 @@ function toolDefinitionTokens() {
   }));
   return Math.ceil(JSON.stringify(defs).length / 4);
 }
-function degradedLine(reason = "unknown") {
-  return `Mode: DEGRADED (${reason}) - files are read normally, nothing is stashed`;
+function degradedLine(reason2 = "unknown") {
+  return `Mode: DEGRADED (${reason2}) - files are read normally, nothing is stashed`;
+}
+function formatLifetime(c, since, saved) {
+  const v = lifetimeView(c);
+  if (v.empty) return [`  Lifetime counters start with this version; ${saved} above includes older history.`];
+  const fmt = (n) => `~${n.toLocaleString()}`;
+  const date = since ? ` (since ${new Date(since).toISOString().slice(0, 10)})` : "";
+  const perSession = v.netPerSession === null ? "" : `, ${fmt(v.netPerSession)} per session`;
+  return [
+    `  Lifetime${date}:`,
+    `    Sessions: ${v.sessions}, reads: ${v.reads}`,
+    `    Would have sent (plain reads): ${fmt(v.baselineTokens)} tokens`,
+    `    Actually sent: ${fmt(v.sentTokens)} tokens`,
+    `    Gross saved: ${fmt(v.grossSaved)} tokens`,
+    `    Tool definitions overhead: ${fmt(v.overheadTokens)} tokens (est., ${v.sessions} sessions)`,
+    `    Net saved: ${fmt(v.netSaved)} tokens (est.)${perSession}`
+  ];
 }
 function formatStatus(stats, overheadTokens) {
   if (stats.degraded) return degradedLine(stats.degradedReason);
@@ -1046,7 +1215,8 @@ function formatStatus(stats, overheadTokens) {
     `    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`
+    `  Gross saved (all sessions): ${fmt(stats.tokensSaved)} tokens`,
+    ...formatLifetime(stats, stats.countersSince, `"Gross saved (all sessions)"`)
   ].join("\n");
 }
 function statsSuffix(grossSaved) {
@@ -1054,7 +1224,7 @@ function statsSuffix(grossSaved) {
 
 [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 {
@@ -1064,8 +1234,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} ===
@@ -1093,6 +1263,9 @@ async function startMcpServer() {
     ...limitOptions()
   });
   await stash.init();
+  await stash.recordSessionStart(toolDefinitionTokens());
+  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"
@@ -1100,7 +1273,7 @@ async function startMcpServer() {
   server.registerTool(
     "read_file",
     TOOL_DEFS.read_file,
-    async ({ path, force, offset, limit }) => {
+    async ({ path, force, offset, limit, agent }) => {
       const absPath = resolve3(path);
       if (!isPathAllowed(absPath, cwd)) {
         return {
@@ -1109,12 +1282,13 @@ async function startMcpServer() {
         };
       }
       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);
         }
@@ -1134,8 +1308,8 @@ async function startMcpServer() {
   server.registerTool(
     "read_files",
     TOOL_DEFS.read_files,
-    async ({ paths }) => {
-      const results = await Promise.all(paths.map((p) => readSingleFile(p, cwd, stash)));
+    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 = "";
@@ -1165,7 +1339,8 @@ async function startMcpServer() {
           [`${META_NAMESPACE}/stats`]: {
             ...stats,
             toolDefinitionTokens: overhead,
-            netTokensSaved: stats.sessionTokensSaved - overhead
+            netTokensSaved: stats.sessionTokensSaved - overhead,
+            lifetime: lifetimeView(stats)
           }
         }
       };
@@ -1223,6 +1398,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) {
@@ -1235,19 +1853,16 @@ var RESET_HOOK_ENTRY = {
   matcher: "clear|compact",
   hooks: [{ type: "command", command: RESET_HOOK_COMMAND }]
 };
-var HOOK_STDIN_TIMEOUT_MS = 1e3;
+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() {
-  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();
+  const raw = await readHookStdin();
   if (!raw) return void 0;
   try {
     const cwd = JSON.parse(raw)?.cwd;
@@ -1259,8 +1874,8 @@ async function readHookCwd() {
 async function runReset(fromHook) {
   try {
     const hookCwd = fromHook ? await readHookCwd() : void 0;
-    const dbPath = join3(resolveStashDir(hookCwd), "stash.db");
-    if (!existsSync4(dbPath)) {
+    const dbPath = join5(resolveStashDir(hookCwd), "stash.db");
+    if (!existsSync5(dbPath)) {
       if (!fromHook) console.log("No filestash database found. Nothing to reset.");
       return;
     }
@@ -1280,36 +1895,47 @@ async function runReset(fromHook) {
   }
 }
 function hooksSnippet() {
-  return JSON.stringify({ hooks: { SessionStart: [RESET_HOOK_ENTRY] } }, null, 2);
+  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 = join3(home, ".claude", "settings.json");
+  const settingsPath = join5(home, ".claude", "settings.json");
   let settings = {};
-  const existed = existsSync4(settingsPath);
+  const existed = existsSync5(settingsPath);
   if (existed) {
     try {
-      settings = JSON.parse(readFileSync3(settingsPath, "utf-8"));
+      settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
     } catch {
-      console.error(`  Claude Code hook: ${settingsPath} is not valid JSON, left untouched`);
+      console.error(`  Claude Code hooks: ${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");
+  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(join3(home, ".claude"), { recursive: true });
-  settings.hooks = { ...hooks, SessionStart: [...sessionStart, RESET_HOOK_ENTRY] };
+  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 hook: configured (${settingsPath})`);
+  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)) {
+  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);
   }
@@ -1322,6 +1948,7 @@ async function runStatus() {
     console.log(`filestash status:`);
     console.log(`  Files tracked:          ${stats.filesTracked}`);
     console.log(`  Tokens saved (total):   ~${stats.tokensSaved.toLocaleString()}`);
+    console.log(formatLifetime(stats, stats.countersSince, `"Tokens saved (total)"`).join("\n"));
   } catch (e) {
     console.error(`filestash status failed for ${dbPath}: ${e instanceof Error ? e.message : String(e)}`);
     process.exitCode = 1;
@@ -1330,19 +1957,27 @@ async function runStatus() {
   }
 }
 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 = [];
+  const lifetime = { lifetimeSessions: 0, lifetimeReads: 0, lifetimeBaselineTokens: 0, lifetimeSentTokens: 0, lifetimeOverheadTokens: 0 };
+  let since;
   for (const dbPath of databases) {
     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 });
+      lifetime.lifetimeSessions += stats.lifetimeSessions;
+      lifetime.lifetimeReads += stats.lifetimeReads;
+      lifetime.lifetimeBaselineTokens += stats.lifetimeBaselineTokens;
+      lifetime.lifetimeSentTokens += stats.lifetimeSentTokens;
+      lifetime.lifetimeOverheadTokens += stats.lifetimeOverheadTokens;
+      if (stats.countersSince !== void 0) since = Math.min(since ?? Infinity, stats.countersSince);
+      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 {
@@ -1352,53 +1987,26 @@ 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}`);
   }
   console.log(`  ~${totalTokens.toLocaleString().padStart(10)} tokens  ${String(totalFiles).padStart(5)} files  TOTAL`);
+  console.log(formatLifetime(lifetime, since, "the per-project totals").join("\n"));
   console.log(`
 Savings count re-reads within a session (unchanged files and diffs); a new session always receives full content.`);
 }
 async function runInit(withHooks) {
-  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
-    }
-  ];
+  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 = {};
       }
@@ -1416,7 +2024,7 @@ async function runInit(withHooks) {
   }
   if (configured === 0) {
     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));
+    console.log(JSON.stringify({ mcpServers: { "agent-file-stash": targets[0].entry } }, null, 2));
   } else {
     console.log(`
 Done! Restart your editor to pick up agent-file-stash.`);
@@ -1445,13 +2053,17 @@ function runHelp() {
 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
+                             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:
@@ -1464,13 +2076,17 @@ 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(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 {