claude-code-kanban 6.1.1 → 7.0.0

package/lib/panes.js

@@ -0,0 +1,174 @@
+// Per-session pane layout: the tabs next to Board. The file is the only copy, shared by every
+// board process on the config dir, the CLI and the agent. Which tab is on screen is each
+// browser tab's own state, not stored here. Expiry: docs/retention.md.
+
+const path = require('node:path');
+const { httpError } = require('./http-error');
+const { canonicalPath } = require('./linked-docs');
+const { isLoopbackAddress } = require('./net-guard');
+const { oneLine } = require('./one-line');
+const { pruneMap } = require('./retention');
+
+const MAX_PANES = 50;
+const MAX_TITLE = 100;
+const KINDS = new Set(['url', 'html', 'markdown', 'text', 'image']);
+
+const portOf = (u) => Number(u.port || (u.protocol === 'https:' ? 443 : 80));
+
+// A frame with allow-scripts plus allow-same-origin on the board's origin or the hub's can reach
+// into its parent and drop its own sandbox. Every name either one is served under counts.
+function isOwnOrigin(url, { boardPort, boardHosts = [], hubUrl }) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return false;
+  }
+  const port = portOf(u);
+  const loopback = isLoopbackAddress(u.hostname);
+  if (u.protocol === 'http:' && port === boardPort && (loopback || boardHosts.includes(u.hostname))) return true;
+  let hub;
+  try {
+    hub = new URL(hubUrl);
+  } catch {
+    return false;
+  }
+  const hubHost = u.hostname === hub.hostname || (loopback && isLoopbackAddress(hub.hostname));
+  return u.protocol === hub.protocol && port === portOf(hub) && hubHost;
+}
+
+const emptyLayout = () => ({ rev: 0, nextId: 1, panes: [], updatedAt: null });
+
+const targetKey = (kind, target) => (kind === 'url' ? `url:${target}` : `file:${canonicalPath(target)}`);
+
+function defaultTitle(kind, target) {
+  if (kind !== 'url') return path.basename(target);
+  try {
+    return new URL(target).host;
+  } catch {
+    return target;
+  }
+}
+
+const idNumber = (id) => Number(id.slice(1)) || 0;
+
+function cleanLayout(raw) {
+  if (!raw || !Array.isArray(raw.panes) || !Number.isFinite(raw.updatedAt)) return null;
+  const ids = new Set();
+  const panes = raw.panes.filter((p) => {
+    const ok = p && typeof p.id === 'string' && !ids.has(p.id) && KINDS.has(p.kind) && typeof p.target === 'string' && p.target;
+    if (ok) ids.add(p.id);
+    return ok;
+  });
+  const nextId = Math.max(Number.isInteger(raw.nextId) ? raw.nextId : 1, ...panes.map((p) => idNumber(p.id) + 1));
+  const rev = Number.isInteger(raw.rev) && raw.rev > 0 ? raw.rev : 1;
+  return { rev, nextId, panes: panes.slice(0, MAX_PANES), updatedAt: raw.updatedAt };
+}
+
+const publicLayout = (l) => ({ rev: l.rev, panes: l.panes.map((p) => ({ ...p })), updatedAt: l.updatedAt });
+
+/**
+ * Every write re-reads the file first, so two boards on one config dir add to each other's
+ * layouts instead of overwriting them. The read-to-rename window is left open: both writers
+ * are one user's own board tabs and CLI calls.
+ *
+ * @param {object} o
+ * @param {() => object|null|undefined} o.load returns `{version: 2, sessions: {[id]: {rev, nextId, panes, updatedAt}}}`,
+ *   null when there is no file, or undefined when the file has not changed since the last load or save
+ * @param {(data: object) => void} o.save
+ * @param {(sessionId: string, layout: object) => void} [o.onChange] called for each layout whose rev
+ *   moved, from this store's writes and from `reload()` alike
+ */
+function createPaneStore({ load, save, onChange = () => {}, now = Date.now }) {
+  let bySession = new Map();
+
+  function reload() {
+    const data = load();
+    if (data === undefined) return;
+    const next = new Map();
+    const saved = data?.sessions;
+    if (saved && typeof saved === 'object') {
+      for (const [id, raw] of Object.entries(saved)) {
+        const layout = cleanLayout(raw);
+        if (layout) next.set(id, layout);
+      }
+    }
+    const before = bySession;
+    bySession = next;
+    for (const [id, layout] of next) {
+      if (before.get(id)?.rev !== layout.rev) onChange(id, publicLayout(layout));
+    }
+  }
+  reload();
+
+  const persist = () => save({ version: 2, sessions: Object.fromEntries(bySession) });
+
+  function write(sessionId, layout) {
+    layout.rev += 1;
+    layout.updatedAt = now();
+    bySession.set(sessionId, layout);
+    persist();
+    onChange(sessionId, publicLayout(layout));
+    return publicLayout(layout);
+  }
+
+  function get(sessionId) {
+    const layout = bySession.get(sessionId);
+    return publicLayout(layout || emptyLayout());
+  }
+
+  // The same target added again returns its pane where it is, so a repeated `pane add` is harmless.
+  function add(sessionId, { kind, target, title }) {
+    if (!KINDS.has(kind)) throw httpError(400, `Unknown pane kind: ${kind}`, 'bad_kind');
+    reload();
+    const layout = bySession.get(sessionId) || emptyLayout();
+    const key = targetKey(kind, target);
+    const existing = layout.panes.find((p) => targetKey(p.kind, p.target) === key);
+    if (existing) return { pane: { ...existing }, added: false, layout: publicLayout(layout) };
+    if (layout.panes.length >= MAX_PANES) throw httpError(409, `A session holds at most ${MAX_PANES} panes`, 'pane_limit');
+    const pane = {
+      id: `p${layout.nextId++}`,
+      kind,
+      target,
+      title: oneLine(title, MAX_TITLE) || oneLine(defaultTitle(kind, target), MAX_TITLE),
+      addedAt: now(),
+    };
+    layout.panes.push(pane);
+    return { pane: { ...pane }, added: true, layout: write(sessionId, layout) };
+  }
+
+  // Returns the new layout, or null when the session has no such pane. An emptied layout stays
+  // until retention drops it, so its ids and rev keep counting up.
+  function remove(sessionId, paneId) {
+    reload();
+    const layout = bySession.get(sessionId);
+    const i = layout ? layout.panes.findIndex((p) => p.id === paneId) : -1;
+    if (i < 0) return null;
+    layout.panes.splice(i, 1);
+    return write(sessionId, layout);
+  }
+
+  // `order` is every pane id of the session, in the new tab order.
+  function reorder(sessionId, order) {
+    reload();
+    const layout = bySession.get(sessionId);
+    const ids = layout ? layout.panes.map((p) => p.id) : [];
+    const valid = Array.isArray(order) && order.length === ids.length && new Set(order).size === ids.length;
+    if (!valid || !order.every((id) => ids.includes(id))) throw httpError(400, 'order must list every pane id once', 'bad_order');
+    if (!layout || order.every((id, i) => id === ids[i])) return get(sessionId);
+    layout.panes = order.map((id) => layout.panes.find((p) => p.id === id));
+    return write(sessionId, layout);
+  }
+
+  // Returns how many layouts went; writes only when one did.
+  function prune({ known, maxAgeMs }) {
+    reload();
+    const removed = pruneMap(bySession, (l) => l.updatedAt, { known, maxAgeMs, now: now() });
+    if (removed) persist();
+    return removed;
+  }
+
+  return { get, add, remove, reorder, prune, reload };
+}
+
+module.exports = { createPaneStore, isOwnOrigin, portOf, MAX_PANES, MAX_TITLE };

package/lib/parsers.js

@@ -373,20 +373,50 @@ const modeOf = (data) => {
   return (data.type === 'user' || data.type === 'permission-mode') && data.permissionMode || null;
 };
 
+const isMainReply = (data) =>
+  data.type === 'assistant' && !data.isSidechain && data.message?.usage && data.message.model !== '<synthetic>';
+
 // The TTL of the last prompt-cache write, from the API's 5m/1h split of cache_creation.
 const cacheTtlOf = (data) => {
-  const cc = data.type === 'assistant' && !data.isSidechain && data.message?.usage?.cache_creation;
+  const cc = isMainReply(data) && data.message.usage.cache_creation;
   if (!cc) return null;
   return cc.ephemeral_1h_input_tokens > 0 ? '1h' : cc.ephemeral_5m_input_tokens > 0 ? '5m' : null;
 };
 
+// Copy of displayName in the plugin's hooks/context.ts; Node cannot import the mod.
+function modelDisplayName(model) {
+  const m = /^claude-([a-z]+)-(\d+)(?:-(\d{1,2})(?!\d))?/.exec(model || '');
+  if (!m) return model || null;
+  return `${m[1][0].toUpperCase()}${m[1].slice(1)} ${m[3] ? `${m[2]}.${m[3]}` : m[2]}`;
+}
+
+const isMainUser = (data) => data.type === 'user' && !data.isSidechain && data.timestamp;
+
+// `at` is when the request went out: the reply's own lines land seconds to tens of seconds later,
+// which would make the cache countdown run long.
+const replyOf = (data, requestTs) => {
+  const u = data.message.usage;
+  return {
+    at: Date.parse(requestTs || data.timestamp) || null,
+    model: data.message.model || null,
+    usage: {
+      input_tokens: u.input_tokens || 0,
+      cache_read_input_tokens: u.cache_read_input_tokens || 0,
+      cache_creation_input_tokens: u.cache_creation_input_tokens || 0,
+      output_tokens: u.output_tokens || 0,
+    },
+  };
+};
+// After a compaction the old usage overstates what the next request writes.
+const withoutUsage = (reply) => reply && { ...reply, usage: null };
+
 // gitBranch in the JSONL is pinned to the launch-time repo by Claude Code
 // and goes stale once cwd shifts (Bash `cd`, submodule). Callers needing the
 // live branch must resolve it from cwd separately. Cache is reset on inode
 // change or truncation (size < scannedUpTo).
 
 function readSessionInfoFromJsonl(jsonlPath) {
-  const result = { slug: null, projectPath: null, cwd: null, gitBranch: null, customTitle: null, logicalParentUuid: null, compactBoundaryUuid: null, permissionMode: null, cacheTtl: null };
+  const result = { slug: null, projectPath: null, cwd: null, gitBranch: null, customTitle: null, logicalParentUuid: null, compactBoundaryUuid: null, permissionMode: null, cacheTtl: null, lastReply: null };
   let stat;
   let fd;
   try {
@@ -408,6 +438,7 @@ function readSessionInfoFromJsonl(jsonlPath) {
       compactBoundaryUuid: cached.compactBoundaryUuid || null,
       permissionMode: cached.permissionMode || null,
       cacheTtl: cached.cacheTtl || null,
+      lastReply: cached.lastReply || null,
       customTitle: readCustomTitle(jsonlPath, stat)
     };
   }
@@ -421,9 +452,11 @@ function readSessionInfoFromJsonl(jsonlPath) {
     result.compactBoundaryUuid = cached.compactBoundaryUuid || null;
     result.permissionMode = cached.permissionMode || null;
     result.cacheTtl = cached.cacheTtl || null;
+    result.lastReply = cached.lastReply || null;
   }
 
   let lastCwdSeen = result.cwd;
+  let lastUserTs = canIncrement ? cached.lastUserTs || null : null;
   const applyLine = (line) => {
     try {
       const data = JSON.parse(line);
@@ -437,6 +470,9 @@ function readSessionInfoFromJsonl(jsonlPath) {
       if (mode) result.permissionMode = mode;
       const ttl = cacheTtlOf(data);
       if (ttl) result.cacheTtl = ttl;
+      if (isMainUser(data)) lastUserTs = data.timestamp;
+      else if (isMainReply(data)) result.lastReply = replyOf(data, lastUserTs);
+      if (data.subtype === 'compact_boundary') result.lastReply = withoutUsage(result.lastReply);
       if (data.subtype === 'compact_boundary' && data.logicalParentUuid && !result.logicalParentUuid) {
         result.logicalParentUuid = data.logicalParentUuid;
         // The boundary record's own uuid: a fork copies it verbatim from the
@@ -450,6 +486,8 @@ function readSessionInfoFromJsonl(jsonlPath) {
   const CHUNK_SIZE = 16384;
   const TAIL_SIZE = 16384;
   const HEAD_MAX = 1048576;
+  const BACK_CHUNK = 65536;
+  const BACK_MAX = 2097152;
   let scannedUpTo = canIncrement ? cached.scannedUpTo : 0;
 
   try {
@@ -502,29 +540,66 @@ function readSessionInfoFromJsonl(jsonlPath) {
 
       // Tail scan catches late cwd switches past HEAD_MAX. projectPath stays
       // anchored to the earliest cwd — it is never overwritten here.
+      // The first window is TAIL_SIZE. A tail of one long line (11% of transcripts over 1 MB)
+      // holds no reply, so it reads further back in BACK_CHUNK steps until it finds one.
       if (stat.size > offset) {
-        const tailStart = Math.max(offset, stat.size - TAIL_SIZE);
-        const tailBuf = Buffer.alloc(TAIL_SIZE);
-        const tn = fs.readSync(fd, tailBuf, 0, TAIL_SIZE, tailStart);
-        const lines = tailBuf.toString('utf8', 0, tn).split('\n');
         let latestTailCwd = null;
         let latestTailMode = null;
         let latestTailTtl = null;
-        for (let i = lines.length - 1; i >= 0; i--) {
-          try {
-            const data = JSON.parse(lines[i]);
-            if (!latestTailTtl) latestTailTtl = cacheTtlOf(data);
-            if (!result.slug && data.slug) result.slug = data.slug;
-            if (!result.projectPath && data.cwd) result.projectPath = data.cwd;
-            if (!result.gitBranch && data.gitBranch) result.gitBranch = data.gitBranch;
-            if (!latestTailCwd && data.cwd) latestTailCwd = data.cwd;
-            if (!latestTailMode) latestTailMode = modeOf(data);
-            if (latestTailCwd && latestTailMode && latestTailTtl && result.slug && result.projectPath && result.gitBranch) break;
-          } catch {}
+        let tailReply = null;
+        let tailRequestTs = null;
+        let compactedAfterReply = false;
+        let latestTailUserTs = null;
+        // Filled from the end; [start, end) holds read bytes not parsed yet.
+        const window = Buffer.allocUnsafe(Math.min(BACK_MAX, stat.size - offset));
+        let start = window.length;
+        let end = window.length;
+        let pos = stat.size;
+        while (!(tailReply && tailRequestTs) && start > 0) {
+          const len = Math.min(pos === stat.size ? TAIL_SIZE : BACK_CHUNK, start);
+          start -= len;
+          pos -= len;
+          if (fs.readSync(fd, window, start, len, pos) < len) break;
+          let from = start;
+          if (pos > offset) {
+            // Bytes before the first newline may be the end of a line that starts further back.
+            const nl = window.subarray(start, start + len).indexOf(10);
+            if (nl < 0) continue;
+            from = start + nl + 1;
+          }
+          const lines = window.toString('utf8', from, end).split('\n');
+          end = from - 1;
+          for (let i = lines.length - 1; i >= 0; i--) {
+            try {
+              const data = JSON.parse(lines[i]);
+              if (!latestTailTtl) latestTailTtl = cacheTtlOf(data);
+              if (!result.slug && data.slug) result.slug = data.slug;
+              if (!result.projectPath && data.cwd) result.projectPath = data.cwd;
+              if (!result.gitBranch && data.gitBranch) result.gitBranch = data.gitBranch;
+              if (!latestTailCwd && data.cwd) latestTailCwd = data.cwd;
+              if (!latestTailMode) latestTailMode = modeOf(data);
+              if (!latestTailUserTs && isMainUser(data)) latestTailUserTs = data.timestamp;
+              if (!tailReply) {
+                if (data.subtype === 'compact_boundary') compactedAfterReply = true;
+                else if (isMainReply(data)) tailReply = data;
+              } else if (!tailRequestTs && isMainUser(data)) tailRequestTs = data.timestamp;
+              if (latestTailCwd && latestTailMode && latestTailTtl && tailRequestTs && result.slug && result.projectPath && result.gitBranch) break;
+            } catch {}
+          }
         }
+        const reachedHead = pos <= offset;
         if (latestTailCwd) lastCwdSeen = latestTailCwd;
         if (latestTailMode) result.permissionMode = latestTailMode;
         if (latestTailTtl) result.cacheTtl = latestTailTtl;
+        if (latestTailUserTs || !reachedHead) lastUserTs = latestTailUserTs;
+        if (tailReply) {
+          const reply = replyOf(tailReply, tailRequestTs);
+          result.lastReply = compactedAfterReply ? withoutUsage(reply) : reply;
+        } else if (!reachedHead) {
+          // No reply in the last BACK_MAX bytes: the head's reply is far older than any TTL.
+          result.lastReply = null;
+          result.cacheTtl = null;
+        }
       }
       scannedUpTo = stat.size;
     }
@@ -548,7 +623,9 @@ function readSessionInfoFromJsonl(jsonlPath) {
       logicalParentUuid: result.logicalParentUuid,
       compactBoundaryUuid: result.compactBoundaryUuid,
       permissionMode: result.permissionMode,
-      cacheTtl: result.cacheTtl
+      cacheTtl: result.cacheTtl,
+      lastReply: result.lastReply,
+      lastUserTs
     });
     if (sessionInfoCache.size > SESSION_INFO_CACHE_MAX) {
       const firstKey = sessionInfoCache.keys().next().value;
@@ -1592,35 +1669,78 @@ function extractPromptFromTranscript(jsonlPath) {
   return null;
 }
 
+// The last maxBytes of a file as whole lines: a cut first line is dropped.
+function readTailLines(jsonlPath, maxBytes) {
+  const size = statSync(jsonlPath).size;
+  const readSize = Math.min(maxBytes, size);
+  const start = size - readSize;
+  const buf = Buffer.alloc(readSize);
+  const fd = fs.openSync(jsonlPath, 'r');
+  try {
+    fs.readSync(fd, buf, 0, readSize, start);
+  } finally {
+    fs.closeSync(fd);
+  }
+  const text = buf.toString('utf8');
+  return (start > 0 ? text.slice(text.indexOf('\n') + 1) : text).split('\n');
+}
+
+function lineModel(line) {
+  if (!line.trim()) return null;
+  try {
+    const obj = JSON.parse(line);
+    return obj.model || obj.message?.model || null;
+  } catch (_) {
+    return null;
+  }
+}
+
 function extractModelFromTranscript(jsonlPath) {
   const { openSync, readSync, closeSync } = fs;
   const MAX_READ = 65536;
   const CHUNK = 4096;
   const fd = openSync(jsonlPath, 'r');
+  let size;
   try {
+    size = fs.fstatSync(fd).size;
     let accumulated = '';
+    let total = 0;
     const buf = Buffer.alloc(CHUNK);
-    while (accumulated.length < MAX_READ) {
+    while (total < MAX_READ) {
       const bytesRead = readSync(fd, buf, 0, CHUNK, null);
       if (bytesRead === 0) break;
+      total += bytesRead;
       accumulated += buf.toString('utf8', 0, bytesRead);
       for (let nlIdx = accumulated.indexOf('\n'); nlIdx !== -1; nlIdx = accumulated.indexOf('\n')) {
-        const line = accumulated.slice(0, nlIdx);
+        const model = lineModel(accumulated.slice(0, nlIdx));
         accumulated = accumulated.slice(nlIdx + 1);
-        if (!line.trim()) continue;
-        try {
-          const obj = JSON.parse(line);
-          const model = obj.model || obj.message?.model;
-          if (model) return model;
-        } catch (_) {}
+        if (model) return model;
       }
     }
   } finally {
     closeSync(fd);
   }
+  // A long prompt or tool result can push the first assistant line past the
+  // head window, so look at the newest lines too.
+  if (size <= MAX_READ) return null;
+  const lines = readTailLines(jsonlPath, MAX_READ);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const model = lineModel(lines[i]);
+    if (model) return model;
+  }
   return null;
 }
 
+// The meta file Claude Code writes next to a subagent transcript: agentType,
+// description, and the model the agent was asked for ("opus", "haiku", "inherit").
+function readSubagentMeta(jsonlPath) {
+  try {
+    return JSON.parse(readFileSync(jsonlPath.replace(/\.jsonl$/, '.meta.json'), 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
 // Full-file scan of a subagent transcript for roster stats: model, summed
 // output tokens, and first/last timestamps (for duration). COLD PATH ONLY —
 // used by the workflow run view on demand, never from the session-scan hot
@@ -1680,18 +1800,8 @@ function resultFromBlock(b) {
 }
 
 function extractAgentResultFromTranscript(jsonlPath) {
-  const { openSync, readSync, closeSync } = fs;
-  const stat = statSync(jsonlPath);
-  const readSize = Math.min(1048576, stat.size);
-  const start = stat.size - readSize;
-  const fd = openSync(jsonlPath, 'r');
+  const lines = readTailLines(jsonlPath, 1048576);
   try {
-    const buf = Buffer.alloc(readSize);
-    readSync(fd, buf, 0, readSize, start);
-    const text = buf.toString('utf8');
-    // Drop the leading partial line unless we read from the very start.
-    const clean = start > 0 ? text.slice(text.indexOf('\n') + 1) : text;
-    const lines = clean.split('\n');
     const lastAssistant = (needle, pick) => {
       for (let i = lines.length - 1; i >= 0; i--) {
         if (!needle(lines[i])) continue;
@@ -1710,10 +1820,7 @@ function extractAgentResultFromTranscript(jsonlPath) {
       (line) => line.includes('"type":"assistant"'),
       (content) => toolResultText(content).trim(),
     );
-  } catch (_) {
-  } finally {
-    closeSync(fd);
-  }
+  } catch (_) {}
   return null;
 }
 
@@ -1851,6 +1958,7 @@ function buildLoopInfoFromState(state) {
 }
 
 module.exports = {
+  modelDisplayName,
   parseTask,
   parseAgent,
   parseWaiting,
@@ -1881,6 +1989,7 @@ module.exports = {
   findTerminatedTeammates,
   extractPromptFromTranscript,
   extractModelFromTranscript,
+  readSubagentMeta,
   extractAgentResultFromTranscript,
   extractTranscriptStats,
   readLines

package/lib/rate-limits.js

@@ -0,0 +1,21 @@
+// Rate limits belong to the account, so each window comes from the freshest context-status
+// file that has it. A window whose `resets_at` (epoch seconds) has passed is dropped: its
+// percent is from before the reset. A window with no `resets_at` is kept.
+
+const WINDOWS = ['five_hour', 'seven_day'];
+
+function freshRateLimits(entries, nowSec) {
+  const best = {};
+  for (const e of entries) {
+    for (const w of WINDOWS) {
+      const limit = e?.rate_limits?.[w];
+      if (limit?.used_percentage == null) continue;
+      if (limit.resets_at != null && limit.resets_at <= nowSec) continue;
+      const at = e._updatedAt || 0;
+      if (!best[w] || at > best[w].at) best[w] = { at, limit };
+    }
+  }
+  return Object.fromEntries(Object.entries(best).map(([w, b]) => [w, b.limit]));
+}
+
+module.exports = { freshRateLimits };

package/lib/retention.js

@@ -10,6 +10,7 @@ const DEFAULT_CLEANUP_DAYS = 30;
 // read that gap as a deleted transcript.
 const GRACE_MS = 60 * 60 * 1000;
 const MAX_DISPATCHED = 500;
+const MAX_CONTEXT_STATUS = 2000;
 
 // Only the config dir's settings: retention is per config dir, not per project.
 function retentionMs(claudeDir) {
@@ -25,6 +26,18 @@ function isExpired(id, at, { known, maxAgeMs, now }) {
   return (known && !known.has(id)) || age > maxAgeMs;
 }
 
+// Deletes the expired entries of a session-keyed map and returns how many went.
+function pruneMap(map, atOf, { known, maxAgeMs, now }) {
+  let removed = 0;
+  for (const [id, entry] of map) {
+    if (isExpired(id, atOf(entry), { known, maxAgeMs, now })) {
+      map.delete(id);
+      removed++;
+    }
+  }
+  return removed;
+}
+
 /**
  * Sessions started through `dispatch start`, kept after their terminal ends so the card
  * keeps its marker.
@@ -54,14 +67,7 @@ function createDispatchedStore({ load, save, now = Date.now }) {
 
   // Returns how many entries went; writes only when one did.
   function prune({ known, maxAgeMs }) {
-    const t = now();
-    let removed = 0;
-    for (const [id, e] of entries) {
-      if (isExpired(id, e.at, { known, maxAgeMs, now: t })) {
-        entries.delete(id);
-        removed++;
-      }
-    }
+    const removed = pruneMap(entries, (e) => e.at, { known, maxAgeMs, now: now() });
     if (removed) persist();
     return removed;
   }
@@ -94,6 +100,22 @@ async function scanTranscripts(projectsDir) {
   return ids.size ? { ids, dirs } : null;
 }
 
+async function expireFiles(dir, names, idOf, opts) {
+  let removed = 0;
+  const kept = [];
+  for (const f of names) {
+    const file = path.join(dir, f);
+    try {
+      const { mtimeMs } = await fs.stat(file);
+      if (isExpired(idOf(f), mtimeMs, opts)) {
+        await fs.rm(file, { force: true });
+        removed++;
+      } else kept.push({ file, mtimeMs });
+    } catch {}
+  }
+  return { removed, kept };
+}
+
 // `<dir>/<session id>/<ts>.md`, one folder per session.
 async function pruneSessionDirs(dir, { known, maxAgeMs, now = Date.now() }) {
   let removed = 0;
@@ -108,21 +130,47 @@ async function pruneSessionDirs(dir, { known, maxAgeMs, now = Date.now() }) {
     const sessionDir = path.join(dir, d.name);
     try {
       const files = await fs.readdir(sessionDir);
-      let kept = 0;
-      for (const f of files) {
-        const file = path.join(sessionDir, f);
-        const { mtimeMs } = await fs.stat(file);
-        if (isExpired(d.name, mtimeMs, { known, maxAgeMs, now })) {
-          await fs.rm(file, { force: true });
-          removed++;
-        } else kept++;
-      }
+      const res = await expireFiles(sessionDir, files, () => d.name, { known, maxAgeMs, now });
+      removed += res.removed;
       // An old mtime means no file was added since the read, so a review written right
       // now cannot lose its folder.
-      if (!kept && now - (await fs.stat(sessionDir)).mtimeMs >= GRACE_MS) await fs.rmdir(sessionDir);
+      if (!res.kept.length && now - (await fs.stat(sessionDir)).mtimeMs >= GRACE_MS) await fs.rmdir(sessionDir);
     } catch {}
   }
   return removed;
 }
 
-module.exports = { createDispatchedStore, scanTranscripts, pruneSessionDirs, retentionMs, GRACE_MS, MAX_DISPATCHED, DAY_MS };
+// `<dir>/<session id>.json`, written by the plugin mod. The cap guards users who keep
+// transcripts forever; it drops the oldest by mtime.
+async function pruneContextStatus(dir, { known, maxAgeMs, now = Date.now(), max = MAX_CONTEXT_STATUS }) {
+  let names;
+  try {
+    names = await fs.readdir(dir);
+  } catch {
+    return 0;
+  }
+  const jsonNames = names.filter((f) => f.endsWith('.json'));
+  let { removed, kept } = await expireFiles(dir, jsonNames, (f) => f.slice(0, -'.json'.length), { known, maxAgeMs, now });
+  if (kept.length > max) {
+    kept.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (const { file } of kept.slice(max)) {
+      try {
+        await fs.rm(file, { force: true });
+        removed++;
+      } catch {}
+    }
+  }
+  return removed;
+}
+
+module.exports = {
+  pruneMap,
+  createDispatchedStore,
+  scanTranscripts,
+  pruneSessionDirs,
+  pruneContextStatus,
+  retentionMs,
+  GRACE_MS,
+  MAX_DISPATCHED,
+  DAY_MS,
+};

package/lib/scratchpad-dir.js

@@ -0,0 +1,41 @@
+// Where the harness puts a session's scratchpad. The rule and its probes: docs/session-scanning.md.
+
+const path = require('node:path');
+const { existsSync, opendirSync } = require('node:fs');
+const { encodeProjectDirName } = require('./claude-dir');
+
+function isEmptyDir(dir) {
+  let handle;
+  try {
+    handle = opendirSync(dir);
+    return handle.readSync() === null;
+  } catch {
+    return true;
+  } finally {
+    handle?.closeSync();
+  }
+}
+
+function createScratchpadDirResolver({ root, resolveWorktree, exists = existsSync, isEmpty = isEmptyDir }) {
+  // A by-project dir that holds an entry always wins, so that answer is kept and never probed again.
+  const settled = new Map();
+
+  return function getScratchpadDir(id, meta) {
+    if (!meta.jsonlPath) return null;
+    const byProject = path.join(root, path.basename(path.dirname(meta.jsonlPath)), id, 'scratchpad');
+    if (settled.get(id) === byProject) return byProject;
+
+    // Claude Code keys the scratchpad on the process's original cwd, while entering a worktree
+    // moves the transcript under the worktree.
+    const wt = resolveWorktree(meta.project);
+    const launch = wt ? wt.repo : meta.project;
+    if (!launch) return byProject;
+    const byLaunch = path.join(root, encodeProjectDirName(launch), id, 'scratchpad');
+    if (byLaunch === byProject || !exists(byLaunch)) return byProject;
+    if (isEmpty(byProject)) return byLaunch;
+    settled.set(id, byProject);
+    return byProject;
+  };
+}
+
+module.exports = { createScratchpadDirResolver };