@code-yeongyu/senpi 2026.9.23-5 → 2026.9.24-2

package/dist/core/session-summary-cache.d.ts

@@ -1,4 +1,5 @@
 import { type SessionSummary } from "./session-summary.ts";
+import { type FileStamp } from "./session-summary-lru.ts";
 /**
  * Upper bound on cached session files, evicted least-recently-used rather than
  * grown with the sessions directory.
@@ -20,6 +21,15 @@ export type CachedSessionSummary = {
     readonly summary: SessionSummary;
     readonly mtime: Date;
 };
+/**
+ * A second cache level consulted on an in-memory miss, such as the persistent
+ * per-directory summary index. `record` receives every summary served from
+ * memory or streamed, so the store can persist what it lacks.
+ */
+export type SessionSummaryStore = {
+    lookup(filePath: string, stamp: FileStamp): Promise<SessionSummary | undefined>;
+    record(filePath: string, stamp: FileStamp, summary: SessionSummary): void;
+};
 /**
  * Exact summary of one session file, reusing the cached summary when the file's
  * size and mtime are unchanged since it was read.
@@ -28,10 +38,13 @@ export type CachedSessionSummary = {
  * sessions directory costs one `stat` per file. A file that cannot be stat'ed or
  * read drops its cache entry, so a truncated or replaced file is never served
  * from stale bytes. A summary too large for the cache's byte budget is returned
- * to the caller without being retained.
+ * to the caller without being retained. On a miss, `store` is consulted before
+ * the file is streamed.
  */
-export declare function readCachedSessionSummary(filePath: string): Promise<CachedSessionSummary | null>;
-/** Drop every cached summary. Test-only seam for cold-read assertions. */
+export declare function readCachedSessionSummary(filePath: string, store?: SessionSummaryStore): Promise<CachedSessionSummary | null>;
+/** Session files streamed since process start. Test-only seam for index-hit assertions. */
+export declare function sessionSummaryStreamCount(): number;
+/** Drop every cached summary and index snapshot. Test-only seam for cold-read assertions. */
 export declare function clearSessionSummaryCache(): void;
 /** Number of cached summaries. Test-only seam for eviction assertions. */
 export declare function sessionSummaryCacheSize(): number;

package/dist/core/session-summary-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-summary-cache.d.ts","sourceRoot":"","sources":["../../src/core/session-summary-cache.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG/E;;;GAGG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oCAAoC,QAAmB,CAAC;AAErE,MAAM,MAAM,oBAAoB,GAAG;IAClC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;CACrB,CAAC;AAYF;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA4BrG;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED,wFAAwF;AACxF,wBAAgB,4BAA4B,IAAI,MAAM,CAErD"}
+{"version":3,"file":"session-summary-cache.d.ts","sourceRoot":"","sources":["../../src/core/session-summary-cache.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE/E,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,0BAA0B,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oCAAoC,QAAmB,CAAC;AAErE,MAAM,MAAM,oBAAoB,GAAG;IAClC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IACjC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAChF,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;CAC1E,CAAC;AAcF;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC7C,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAqCtC;AAED,2FAA2F;AAC3F,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED,6FAA6F;AAC7F,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED,wFAAwF;AACxF,wBAAgB,4BAA4B,IAAI,MAAM,CAErD"}

package/dist/core/session-summary-cache.js

@@ -1,6 +1,7 @@
 import { stat } from "fs/promises";
 import { resolve } from "path";
 import { readSessionSummary } from "./session-summary.js";
+import { forgetSessionSummaryIndexSnapshots } from "./session-summary-index.js";
 import { SessionSummaryLru } from "./session-summary-lru.js";
 /**
  * Upper bound on cached session files, evicted least-recently-used rather than
@@ -24,6 +25,7 @@ const cache = new SessionSummaryLru({
     maxEntries: SESSION_SUMMARY_CACHE_LIMIT,
     maxTextBytes: SESSION_SUMMARY_CACHE_MAX_TEXT_BYTES,
 });
+let streamedSummaries = 0;
 function stampsMatch(left, right) {
     return left.size === right.size && left.mtimeMs === right.mtimeMs;
 }
@@ -35,9 +37,10 @@ function stampsMatch(left, right) {
  * sessions directory costs one `stat` per file. A file that cannot be stat'ed or
  * read drops its cache entry, so a truncated or replaced file is never served
  * from stale bytes. A summary too large for the cache's byte budget is returned
- * to the caller without being retained.
+ * to the caller without being retained. On a miss, `store` is consulted before
+ * the file is streamed.
  */
-export async function readCachedSessionSummary(filePath) {
+export async function readCachedSessionSummary(filePath, store) {
     const key = resolve(filePath);
     let stamp;
     let mtime;
@@ -54,19 +57,32 @@ export async function readCachedSessionSummary(filePath) {
     }
     const cached = cache.get(key);
     if (cached && stampsMatch(cached.stamp, stamp)) {
+        store?.record(filePath, stamp, cached.summary);
         return { summary: cached.summary, mtime: cached.mtime };
     }
+    const stored = await store?.lookup(filePath, stamp);
+    if (stored) {
+        cache.retain(key, { stamp, summary: stored, mtime });
+        return { summary: stored, mtime };
+    }
+    streamedSummaries++;
     const summary = await readSessionSummary(filePath);
     if (!summary) {
         cache.drop(key);
         return null;
     }
     cache.retain(key, { stamp, summary, mtime });
+    store?.record(filePath, stamp, summary);
     return { summary, mtime };
 }
-/** Drop every cached summary. Test-only seam for cold-read assertions. */
+/** Session files streamed since process start. Test-only seam for index-hit assertions. */
+export function sessionSummaryStreamCount() {
+    return streamedSummaries;
+}
+/** Drop every cached summary and index snapshot. Test-only seam for cold-read assertions. */
 export function clearSessionSummaryCache() {
     cache.clear();
+    forgetSessionSummaryIndexSnapshots();
 }
 /** Number of cached summaries. Test-only seam for eviction assertions. */
 export function sessionSummaryCacheSize() {

package/dist/core/session-summary-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-summary-cache.js","sourceRoot":"","sources":["../../src/core/session-summary-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAuB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAkB,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7E;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAOrE,mFAAmF;AACnF,MAAM,KAAK,GAAG,IAAI,iBAAiB,CAAC;IACnC,UAAU,EAAE,2BAA2B;IACvC,YAAY,EAAE,oCAAoC;CAClD,CAAC,CAAC;AAEH,SAAS,WAAW,CAAC,IAAe,EAAE,KAAgB;IACrD,OAAO,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,CAAC;AACnE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,QAAgB;IAC9D,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE9B,IAAI,KAAgB,CAAC;IACrB,IAAI,KAAW,CAAC;IAChB,IAAI,CAAC;QACJ,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,KAAK,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QACrD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACnD,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,wBAAwB;IACvC,KAAK,CAAC,KAAK,EAAE,CAAC;AACf,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,uBAAuB;IACtC,OAAO,KAAK,CAAC,IAAI,CAAC;AACnB,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,4BAA4B;IAC3C,OAAO,KAAK,CAAC,SAAS,CAAC;AACxB,CAAC","sourcesContent":["import { stat } from \"fs/promises\";\nimport { resolve } from \"path\";\nimport { readSessionSummary, type SessionSummary } from \"./session-summary.ts\";\nimport { type FileStamp, SessionSummaryLru } from \"./session-summary-lru.ts\";\n\n/**\n * Upper bound on cached session files, evicted least-recently-used rather than\n * grown with the sessions directory.\n */\nexport const SESSION_SUMMARY_CACHE_LIMIT = 4096;\n\n/**\n * Upper bound on retained transcript text across the whole cache.\n *\n * A cached summary's footprint is its `allMessagesText`, which grows with the\n * session, so the entry ceiling alone bounds nothing: 4096 large sessions would\n * pin gigabytes for the life of the process. 64 MiB is deliberately conservative\n * — it holds a normal user's entire sessions directory (a heavy 2 MB session\n * file yields well under 2 MB of visible text, so hundreds of them fit) while\n * capping the worst case at a fraction of a Node heap. Exceeding it evicts the\n * least recently listed sessions, which then cost one streaming re-read.\n */\nexport const SESSION_SUMMARY_CACHE_MAX_TEXT_BYTES = 64 * 1024 * 1024;\n\nexport type CachedSessionSummary = {\n\treadonly summary: SessionSummary;\n\treadonly mtime: Date;\n};\n\n/** Process-local summary cache, bounded by entry count and retained text bytes. */\nconst cache = new SessionSummaryLru({\n\tmaxEntries: SESSION_SUMMARY_CACHE_LIMIT,\n\tmaxTextBytes: SESSION_SUMMARY_CACHE_MAX_TEXT_BYTES,\n});\n\nfunction stampsMatch(left: FileStamp, right: FileStamp): boolean {\n\treturn left.size === right.size && left.mtimeMs === right.mtimeMs;\n}\n\n/**\n * Exact summary of one session file, reusing the cached summary when the file's\n * size and mtime are unchanged since it was read.\n *\n * A cache hit deserializes nothing: the whole point is that listing an unchanged\n * sessions directory costs one `stat` per file. A file that cannot be stat'ed or\n * read drops its cache entry, so a truncated or replaced file is never served\n * from stale bytes. A summary too large for the cache's byte budget is returned\n * to the caller without being retained.\n */\nexport async function readCachedSessionSummary(filePath: string): Promise<CachedSessionSummary | null> {\n\tconst key = resolve(filePath);\n\n\tlet stamp: FileStamp;\n\tlet mtime: Date;\n\ttry {\n\t\tconst stats = await stat(filePath);\n\t\tstamp = { size: stats.size, mtimeMs: stats.mtimeMs };\n\t\tmtime = stats.mtime;\n\t} catch (error) {\n\t\tif (!(error instanceof Error)) throw error;\n\t\tcache.drop(key);\n\t\treturn null;\n\t}\n\n\tconst cached = cache.get(key);\n\tif (cached && stampsMatch(cached.stamp, stamp)) {\n\t\treturn { summary: cached.summary, mtime: cached.mtime };\n\t}\n\n\tconst summary = await readSessionSummary(filePath);\n\tif (!summary) {\n\t\tcache.drop(key);\n\t\treturn null;\n\t}\n\n\tcache.retain(key, { stamp, summary, mtime });\n\treturn { summary, mtime };\n}\n\n/** Drop every cached summary. Test-only seam for cold-read assertions. */\nexport function clearSessionSummaryCache(): void {\n\tcache.clear();\n}\n\n/** Number of cached summaries. Test-only seam for eviction assertions. */\nexport function sessionSummaryCacheSize(): number {\n\treturn cache.size;\n}\n\n/** Retained transcript bytes across the cache. Test-only seam for budget assertions. */\nexport function sessionSummaryCacheTextBytes(): number {\n\treturn cache.textBytes;\n}\n"]}
+{"version":3,"file":"session-summary-cache.js","sourceRoot":"","sources":["../../src/core/session-summary-cache.ts"],"names":[],"mappings":"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","sourcesContent":["import { stat } from \"fs/promises\";\nimport { resolve } from \"path\";\nimport { readSessionSummary, type SessionSummary } from \"./session-summary.ts\";\nimport { forgetSessionSummaryIndexSnapshots } from \"./session-summary-index.ts\";\nimport { type FileStamp, SessionSummaryLru } from \"./session-summary-lru.ts\";\n\n/**\n * Upper bound on cached session files, evicted least-recently-used rather than\n * grown with the sessions directory.\n */\nexport const SESSION_SUMMARY_CACHE_LIMIT = 4096;\n\n/**\n * Upper bound on retained transcript text across the whole cache.\n *\n * A cached summary's footprint is its `allMessagesText`, which grows with the\n * session, so the entry ceiling alone bounds nothing: 4096 large sessions would\n * pin gigabytes for the life of the process. 64 MiB is deliberately conservative\n * — it holds a normal user's entire sessions directory (a heavy 2 MB session\n * file yields well under 2 MB of visible text, so hundreds of them fit) while\n * capping the worst case at a fraction of a Node heap. Exceeding it evicts the\n * least recently listed sessions, which then cost one streaming re-read.\n */\nexport const SESSION_SUMMARY_CACHE_MAX_TEXT_BYTES = 64 * 1024 * 1024;\n\nexport type CachedSessionSummary = {\n\treadonly summary: SessionSummary;\n\treadonly mtime: Date;\n};\n\n/**\n * A second cache level consulted on an in-memory miss, such as the persistent\n * per-directory summary index. `record` receives every summary served from\n * memory or streamed, so the store can persist what it lacks.\n */\nexport type SessionSummaryStore = {\n\tlookup(filePath: string, stamp: FileStamp): Promise<SessionSummary | undefined>;\n\trecord(filePath: string, stamp: FileStamp, summary: SessionSummary): void;\n};\n\n/** Process-local summary cache, bounded by entry count and retained text bytes. */\nconst cache = new SessionSummaryLru({\n\tmaxEntries: SESSION_SUMMARY_CACHE_LIMIT,\n\tmaxTextBytes: SESSION_SUMMARY_CACHE_MAX_TEXT_BYTES,\n});\n\nlet streamedSummaries = 0;\n\nfunction stampsMatch(left: FileStamp, right: FileStamp): boolean {\n\treturn left.size === right.size && left.mtimeMs === right.mtimeMs;\n}\n\n/**\n * Exact summary of one session file, reusing the cached summary when the file's\n * size and mtime are unchanged since it was read.\n *\n * A cache hit deserializes nothing: the whole point is that listing an unchanged\n * sessions directory costs one `stat` per file. A file that cannot be stat'ed or\n * read drops its cache entry, so a truncated or replaced file is never served\n * from stale bytes. A summary too large for the cache's byte budget is returned\n * to the caller without being retained. On a miss, `store` is consulted before\n * the file is streamed.\n */\nexport async function readCachedSessionSummary(\n\tfilePath: string,\n\tstore?: SessionSummaryStore,\n): Promise<CachedSessionSummary | null> {\n\tconst key = resolve(filePath);\n\n\tlet stamp: FileStamp;\n\tlet mtime: Date;\n\ttry {\n\t\tconst stats = await stat(filePath);\n\t\tstamp = { size: stats.size, mtimeMs: stats.mtimeMs };\n\t\tmtime = stats.mtime;\n\t} catch (error) {\n\t\tif (!(error instanceof Error)) throw error;\n\t\tcache.drop(key);\n\t\treturn null;\n\t}\n\n\tconst cached = cache.get(key);\n\tif (cached && stampsMatch(cached.stamp, stamp)) {\n\t\tstore?.record(filePath, stamp, cached.summary);\n\t\treturn { summary: cached.summary, mtime: cached.mtime };\n\t}\n\n\tconst stored = await store?.lookup(filePath, stamp);\n\tif (stored) {\n\t\tcache.retain(key, { stamp, summary: stored, mtime });\n\t\treturn { summary: stored, mtime };\n\t}\n\n\tstreamedSummaries++;\n\tconst summary = await readSessionSummary(filePath);\n\tif (!summary) {\n\t\tcache.drop(key);\n\t\treturn null;\n\t}\n\n\tcache.retain(key, { stamp, summary, mtime });\n\tstore?.record(filePath, stamp, summary);\n\treturn { summary, mtime };\n}\n\n/** Session files streamed since process start. Test-only seam for index-hit assertions. */\nexport function sessionSummaryStreamCount(): number {\n\treturn streamedSummaries;\n}\n\n/** Drop every cached summary and index snapshot. Test-only seam for cold-read assertions. */\nexport function clearSessionSummaryCache(): void {\n\tcache.clear();\n\tforgetSessionSummaryIndexSnapshots();\n}\n\n/** Number of cached summaries. Test-only seam for eviction assertions. */\nexport function sessionSummaryCacheSize(): number {\n\treturn cache.size;\n}\n\n/** Retained transcript bytes across the cache. Test-only seam for budget assertions. */\nexport function sessionSummaryCacheTextBytes(): number {\n\treturn cache.textBytes;\n}\n"]}

package/dist/core/session-summary-index-file.d.ts

@@ -0,0 +1,38 @@
+import { type SessionSummary } from "./session-summary.ts";
+import type { FileStamp } from "./session-summary-lru.ts";
+/**
+ * Name of the summary index inside the sessions directory it describes. The
+ * extension is deliberately not `.jsonl`: every `*.jsonl` there is a session.
+ */
+export declare const SESSION_SUMMARY_INDEX_FILE = ".session-summaries.index";
+/** One indexed session file: its basename, the stamp it was read at, and its summary. */
+export type IndexEntry = {
+    readonly file: string;
+    readonly stamp: FileStamp;
+    readonly summary: SessionSummary;
+    /** Serialized line, newline included. */
+    readonly line: string;
+    readonly lineBytes: number;
+};
+/** An index as loaded from disk; an absent or unusable file loads as `usable: false`. */
+export type LoadedIndex = {
+    readonly usable: boolean;
+    /** Deduplicated entries, last line wins. */
+    readonly entries: ReadonlyMap<string, IndexEntry>;
+    /** Bytes after the header line, including torn and superseded lines. */
+    readonly entryBytes: number;
+    /** False when the file ends in a torn line, so the next append must start a new line. */
+    readonly endsWithNewline: boolean;
+};
+/** Serialize one entry, or undefined when the summary would not survive a JSON round trip. */
+export declare function toIndexEntry(file: string, stamp: FileStamp, summary: SessionSummary): IndexEntry | undefined;
+/**
+ * Load an index, tolerating every failure: a missing file, a missing or foreign
+ * version header, or a read error loads as unusable; a line that does not parse
+ * (a torn append, truncation, garbage) is skipped.
+ */
+export declare function loadIndexFile(path: string): Promise<LoadedIndex>;
+/** Append entries one whole line per write, first closing a torn tail when there is one. */
+export declare function appendIndexEntries(path: string, entries: readonly IndexEntry[], endsWithNewline: boolean): Promise<void>;
+export declare function rewriteIndexFile(path: string, entries: readonly IndexEntry[]): Promise<void>;
+//# sourceMappingURL=session-summary-index-file.d.ts.map

package/dist/core/session-summary-index-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-summary-index-file.d.ts","sourceRoot":"","sources":["../../src/core/session-summary-index-file.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,0BAA0B,6BAA6B,CAAC;AAKrE,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,yFAAyF;AACzF,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClD,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CAClC,CAAC;AA6BF,8FAA8F;AAC9F,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,UAAU,GAAG,SAAS,CAQ5G;AA6BD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA0BtE;AAED,4FAA4F;AAC5F,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,eAAe,EAAE,OAAO,GACtB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CASlG"}

package/dist/core/session-summary-index-file.js

@@ -0,0 +1,119 @@
+import { appendFile, rename, rm, writeFile } from "fs/promises";
+import { readFileLines } from "./session-summary.js";
+/**
+ * Name of the summary index inside the sessions directory it describes. The
+ * extension is deliberately not `.jsonl`: every `*.jsonl` there is a session.
+ */
+export const SESSION_SUMMARY_INDEX_FILE = ".session-summaries.index";
+const INDEX_VERSION = 1;
+const HEADER_LINE = `${JSON.stringify({ version: INDEX_VERSION })}\n`;
+const UNUSABLE = { usable: false, entries: new Map(), entryBytes: 0, endsWithNewline: true };
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function isOptional(value, type) {
+    return value === undefined || typeof value === type;
+}
+function isSessionSummary(value) {
+    if (!isObject(value) || !isObject(value.header))
+        return false;
+    return (value.header.type === "session" &&
+        typeof value.header.id === "string" &&
+        typeof value.firstUserMessage === "string" &&
+        typeof value.messageCount === "number" &&
+        typeof value.allMessagesText === "string" &&
+        isOptional(value.name, "string") &&
+        isOptional(value.lastActivityTime, "number"));
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+/** Serialize one entry, or undefined when the summary would not survive a JSON round trip. */
+export function toIndexEntry(file, stamp, summary) {
+    if (summary.lastActivityTime !== undefined && !Number.isFinite(summary.lastActivityTime))
+        return undefined;
+    return withLine(file, stamp, summary, `${JSON.stringify({ file, size: stamp.size, mtimeMs: stamp.mtimeMs, summary })}\n`);
+}
+function withLine(file, stamp, summary, line) {
+    return { file, stamp, summary, line, lineBytes: Buffer.byteLength(line, "utf8") };
+}
+function parseEntryLine(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isObject(parsed) || typeof parsed.file !== "string" || parsed.file.includes("/"))
+        return undefined;
+    if (!isFiniteNumber(parsed.size) || !isFiniteNumber(parsed.mtimeMs) || !isSessionSummary(parsed.summary)) {
+        return undefined;
+    }
+    return withLine(parsed.file, { size: parsed.size, mtimeMs: parsed.mtimeMs }, parsed.summary, `${line}\n`);
+}
+function isCurrentHeader(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return isObject(parsed) && parsed.version === INDEX_VERSION;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Load an index, tolerating every failure: a missing file, a missing or foreign
+ * version header, or a read error loads as unusable; a line that does not parse
+ * (a torn append, truncation, garbage) is skipped.
+ */
+export async function loadIndexFile(path) {
+    const entries = new Map();
+    let headerSeen = false;
+    let headerBytes = 0;
+    try {
+        const read = await readFileLines(path, (line) => {
+            if (!headerSeen) {
+                headerSeen = true;
+                headerBytes = Buffer.byteLength(line, "utf8") + 1;
+                return isCurrentHeader(line);
+            }
+            const entry = parseEntryLine(line);
+            if (entry)
+                entries.set(entry.file, entry);
+            return true;
+        });
+        if (!read.completed || !headerSeen)
+            return UNUSABLE;
+        return {
+            usable: true,
+            entries,
+            entryBytes: Math.max(0, read.bytes - headerBytes),
+            endsWithNewline: read.endsWithNewline,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return UNUSABLE;
+        throw error;
+    }
+}
+/** Append entries one whole line per write, first closing a torn tail when there is one. */
+export async function appendIndexEntries(path, entries, endsWithNewline) {
+    let prefix = endsWithNewline ? "" : "\n";
+    for (const entry of entries) {
+        await appendFile(path, prefix + entry.line);
+        prefix = "";
+    }
+}
+export async function rewriteIndexFile(path, entries) {
+    const temp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await writeFile(temp, HEADER_LINE + entries.map((entry) => entry.line).join(""));
+        await rename(temp, path);
+    }
+    catch (error) {
+        await rm(temp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+//# sourceMappingURL=session-summary-index-file.js.map

package/dist/core/session-summary-index-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-summary-index-file.js","sourceRoot":"","sources":["../../src/core/session-summary-index-file.ts"],"names":[],"mappings":"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","sourcesContent":["import { appendFile, rename, rm, writeFile } from \"fs/promises\";\nimport { readFileLines, type SessionSummary } from \"./session-summary.ts\";\nimport type { FileStamp } from \"./session-summary-lru.ts\";\n\n/**\n * Name of the summary index inside the sessions directory it describes. The\n * extension is deliberately not `.jsonl`: every `*.jsonl` there is a session.\n */\nexport const SESSION_SUMMARY_INDEX_FILE = \".session-summaries.index\";\n\nconst INDEX_VERSION = 1;\nconst HEADER_LINE = `${JSON.stringify({ version: INDEX_VERSION })}\\n`;\n\n/** One indexed session file: its basename, the stamp it was read at, and its summary. */\nexport type IndexEntry = {\n\treadonly file: string;\n\treadonly stamp: FileStamp;\n\treadonly summary: SessionSummary;\n\t/** Serialized line, newline included. */\n\treadonly line: string;\n\treadonly lineBytes: number;\n};\n\n/** An index as loaded from disk; an absent or unusable file loads as `usable: false`. */\nexport type LoadedIndex = {\n\treadonly usable: boolean;\n\t/** Deduplicated entries, last line wins. */\n\treadonly entries: ReadonlyMap<string, IndexEntry>;\n\t/** Bytes after the header line, including torn and superseded lines. */\n\treadonly entryBytes: number;\n\t/** False when the file ends in a torn line, so the next append must start a new line. */\n\treadonly endsWithNewline: boolean;\n};\n\nconst UNUSABLE: LoadedIndex = { usable: false, entries: new Map(), entryBytes: 0, endsWithNewline: true };\n\nfunction isObject(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null;\n}\n\nfunction isOptional(value: unknown, type: \"string\" | \"number\"): boolean {\n\treturn value === undefined || typeof value === type;\n}\n\nfunction isSessionSummary(value: unknown): value is SessionSummary {\n\tif (!isObject(value) || !isObject(value.header)) return false;\n\treturn (\n\t\tvalue.header.type === \"session\" &&\n\t\ttypeof value.header.id === \"string\" &&\n\t\ttypeof value.firstUserMessage === \"string\" &&\n\t\ttypeof value.messageCount === \"number\" &&\n\t\ttypeof value.allMessagesText === \"string\" &&\n\t\tisOptional(value.name, \"string\") &&\n\t\tisOptional(value.lastActivityTime, \"number\")\n\t);\n}\n\nfunction isFiniteNumber(value: unknown): value is number {\n\treturn typeof value === \"number\" && Number.isFinite(value);\n}\n\n/** Serialize one entry, or undefined when the summary would not survive a JSON round trip. */\nexport function toIndexEntry(file: string, stamp: FileStamp, summary: SessionSummary): IndexEntry | undefined {\n\tif (summary.lastActivityTime !== undefined && !Number.isFinite(summary.lastActivityTime)) return undefined;\n\treturn withLine(\n\t\tfile,\n\t\tstamp,\n\t\tsummary,\n\t\t`${JSON.stringify({ file, size: stamp.size, mtimeMs: stamp.mtimeMs, summary })}\\n`,\n\t);\n}\n\nfunction withLine(file: string, stamp: FileStamp, summary: SessionSummary, line: string): IndexEntry {\n\treturn { file, stamp, summary, line, lineBytes: Buffer.byteLength(line, \"utf8\") };\n}\n\nfunction parseEntryLine(line: string): IndexEntry | undefined {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(line);\n\t} catch {\n\t\treturn undefined;\n\t}\n\tif (!isObject(parsed) || typeof parsed.file !== \"string\" || parsed.file.includes(\"/\")) return undefined;\n\tif (!isFiniteNumber(parsed.size) || !isFiniteNumber(parsed.mtimeMs) || !isSessionSummary(parsed.summary)) {\n\t\treturn undefined;\n\t}\n\treturn withLine(parsed.file, { size: parsed.size, mtimeMs: parsed.mtimeMs }, parsed.summary, `${line}\\n`);\n}\n\nfunction isCurrentHeader(line: string): boolean {\n\ttry {\n\t\tconst parsed: unknown = JSON.parse(line);\n\t\treturn isObject(parsed) && parsed.version === INDEX_VERSION;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * Load an index, tolerating every failure: a missing file, a missing or foreign\n * version header, or a read error loads as unusable; a line that does not parse\n * (a torn append, truncation, garbage) is skipped.\n */\nexport async function loadIndexFile(path: string): Promise<LoadedIndex> {\n\tconst entries = new Map<string, IndexEntry>();\n\tlet headerSeen = false;\n\tlet headerBytes = 0;\n\ttry {\n\t\tconst read = await readFileLines(path, (line) => {\n\t\t\tif (!headerSeen) {\n\t\t\t\theaderSeen = true;\n\t\t\t\theaderBytes = Buffer.byteLength(line, \"utf8\") + 1;\n\t\t\t\treturn isCurrentHeader(line);\n\t\t\t}\n\t\t\tconst entry = parseEntryLine(line);\n\t\t\tif (entry) entries.set(entry.file, entry);\n\t\t\treturn true;\n\t\t});\n\t\tif (!read.completed || !headerSeen) return UNUSABLE;\n\t\treturn {\n\t\t\tusable: true,\n\t\t\tentries,\n\t\t\tentryBytes: Math.max(0, read.bytes - headerBytes),\n\t\t\tendsWithNewline: read.endsWithNewline,\n\t\t};\n\t} catch (error) {\n\t\tif (error instanceof Error) return UNUSABLE;\n\t\tthrow error;\n\t}\n}\n\n/** Append entries one whole line per write, first closing a torn tail when there is one. */\nexport async function appendIndexEntries(\n\tpath: string,\n\tentries: readonly IndexEntry[],\n\tendsWithNewline: boolean,\n): Promise<void> {\n\tlet prefix = endsWithNewline ? \"\" : \"\\n\";\n\tfor (const entry of entries) {\n\t\tawait appendFile(path, prefix + entry.line);\n\t\tprefix = \"\";\n\t}\n}\n\nexport async function rewriteIndexFile(path: string, entries: readonly IndexEntry[]): Promise<void> {\n\tconst temp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;\n\ttry {\n\t\tawait writeFile(temp, HEADER_LINE + entries.map((entry) => entry.line).join(\"\"));\n\t\tawait rename(temp, path);\n\t} catch (error) {\n\t\tawait rm(temp, { force: true }).catch(() => undefined);\n\t\tthrow error;\n\t}\n}\n"]}

package/dist/core/session-summary-index.d.ts

@@ -0,0 +1,52 @@
+import type { SessionSummary } from "./session-summary.ts";
+import type { SessionSummaryStore } from "./session-summary-cache.ts";
+import type { FileStamp } from "./session-summary-lru.ts";
+export { SESSION_SUMMARY_INDEX_FILE } from "./session-summary-index-file.ts";
+/**
+ * Upper bound on live index bytes per sessions directory. It sits well above the
+ * in-memory cache's 64 MiB because the index is read once per cold listing, not
+ * retained; past it the least recently active sessions are left out and stream
+ * like any cache miss.
+ */
+export declare const SESSION_SUMMARY_INDEX_MAX_BYTES: number;
+export type SessionSummaryIndexOptions = {
+    readonly maxBytes?: number;
+};
+/** Forget every index snapshot, as a fresh process would start. */
+export declare function forgetSessionSummaryIndexSnapshots(): void;
+/**
+ * Persistent summaries for one sessions directory, stored as
+ * `<dir>/.session-summaries.index` (senpi#2087).
+ *
+ * It is the second cache level behind the in-memory LRU: a cold process lists an
+ * unchanged directory by reading this one file instead of re-streaming every
+ * session. The file is loaded lazily on the first in-memory miss it can serve,
+ * so a warm process does not read it again for a session that just changed.
+ * Nothing here throws or logs: an unreadable, corrupt,
+ * or unwritable index only means the listing streams, and its rows are
+ * identical either way.
+ */
+export declare class SessionSummaryIndex implements SessionSummaryStore {
+    private readonly path;
+    private readonly maxBytes;
+    private loading;
+    private snapshot;
+    private readonly recorded;
+    constructor(dir: string, options?: SessionSummaryIndexOptions);
+    lookup(filePath: string, stamp: FileStamp): Promise<SessionSummary | undefined>;
+    record(filePath: string, stamp: FileStamp, summary: SessionSummary): void;
+    /**
+     * Bring the index up to date after a listing of `presentFiles`.
+     *
+     * Summaries the index lacks are appended one line each. The file is rewritten
+     * instead (temp file, then rename) when it is unusable, or when its entry
+     * bytes exceed twice the live entries' bytes: superseded lines, torn lines,
+     * removed sessions, and entries over the byte budget all count as dead.
+     */
+    persist(presentFiles: readonly string[]): Promise<void>;
+    private currentSnapshot;
+    /** Stat before reading, so a concurrent writer can only make the snapshot look stale. */
+    private load;
+    private remember;
+}
+//# sourceMappingURL=session-summary-index.d.ts.map

package/dist/core/session-summary-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-summary-index.d.ts","sourceRoot":"","sources":["../../src/core/session-summary-index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAUtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,QAAoB,CAAC;AAEjE,MAAM,MAAM,0BAA0B,GAAG;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAqBF,mEAAmE;AACnE,wBAAgB,kCAAkC,IAAI,IAAI,CAEzD;AAiCD;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAoB,YAAW,mBAAmB;IAC9D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,QAAQ,CAAiD;IACjE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAE3C,YAAY,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,0BAA+B,EAGhE;IAEK,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAWpF;IAED,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAExE;IAED;;;;;;;OAOG;IACG,OAAO,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC5D;YAEa,eAAe;IAO7B,yFAAyF;YAC3E,IAAI;IAOlB,OAAO,CAAC,QAAQ;CAShB"}

package/dist/core/session-summary-index.js

@@ -0,0 +1,157 @@
+import { stat } from "fs/promises";
+import { basename, join } from "path";
+import { appendIndexEntries, loadIndexFile, rewriteIndexFile, SESSION_SUMMARY_INDEX_FILE, toIndexEntry, } from "./session-summary-index-file.js";
+export { SESSION_SUMMARY_INDEX_FILE } from "./session-summary-index-file.js";
+/**
+ * Upper bound on live index bytes per sessions directory. It sits well above the
+ * in-memory cache's 64 MiB because the index is read once per cold listing, not
+ * retained; past it the least recently active sessions are left out and stream
+ * like any cache miss.
+ */
+export const SESSION_SUMMARY_INDEX_MAX_BYTES = 256 * 1024 * 1024;
+const snapshots = new Map();
+/** Forget every index snapshot, as a fresh process would start. */
+export function forgetSessionSummaryIndexSnapshots() {
+    snapshots.clear();
+}
+function stampsMatch(left, right) {
+    return left.size === right.size && left.mtimeMs === right.mtimeMs;
+}
+async function statStamp(path) {
+    try {
+        const stats = await stat(path);
+        return { size: stats.size, mtimeMs: stats.mtimeMs };
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return undefined;
+        throw error;
+    }
+}
+function recency(entry) {
+    const headerTime = Date.parse(entry.summary.header.timestamp);
+    return entry.summary.lastActivityTime ?? (Number.isNaN(headerTime) ? 0 : headerTime);
+}
+function selectWithinBudget(entries, maxBytes) {
+    const kept = [];
+    let bytes = 0;
+    for (const entry of [...entries].sort((left, right) => recency(right) - recency(left))) {
+        if (entry.lineBytes > maxBytes)
+            continue;
+        if (bytes + entry.lineBytes > maxBytes)
+            break;
+        kept.push(entry);
+        bytes += entry.lineBytes;
+    }
+    return kept;
+}
+/**
+ * Persistent summaries for one sessions directory, stored as
+ * `<dir>/.session-summaries.index` (senpi#2087).
+ *
+ * It is the second cache level behind the in-memory LRU: a cold process lists an
+ * unchanged directory by reading this one file instead of re-streaming every
+ * session. The file is loaded lazily on the first in-memory miss it can serve,
+ * so a warm process does not read it again for a session that just changed.
+ * Nothing here throws or logs: an unreadable, corrupt,
+ * or unwritable index only means the listing streams, and its rows are
+ * identical either way.
+ */
+export class SessionSummaryIndex {
+    constructor(dir, options = {}) {
+        this.recorded = [];
+        this.path = join(dir, SESSION_SUMMARY_INDEX_FILE);
+        this.maxBytes = options.maxBytes ?? SESSION_SUMMARY_INDEX_MAX_BYTES;
+    }
+    async lookup(filePath, stamp) {
+        const file = basename(filePath);
+        if (!this.loading) {
+            this.snapshot ??= this.currentSnapshot();
+            const known = await this.snapshot;
+            const indexed = known?.entryStamps.get(file);
+            if (known && !(indexed && stampsMatch(indexed, stamp)))
+                return undefined;
+        }
+        this.loading ??= this.load();
+        const entry = (await this.loading).entries.get(file);
+        return entry && stampsMatch(entry.stamp, stamp) ? entry.summary : undefined;
+    }
+    record(filePath, stamp, summary) {
+        this.recorded.push({ file: basename(filePath), stamp, summary });
+    }
+    /**
+     * Bring the index up to date after a listing of `presentFiles`.
+     *
+     * Summaries the index lacks are appended one line each. The file is rewritten
+     * instead (temp file, then rename) when it is unusable, or when its entry
+     * bytes exceed twice the live entries' bytes: superseded lines, torn lines,
+     * removed sessions, and entries over the byte budget all count as dead.
+     */
+    async persist(presentFiles) {
+        if (!this.loading)
+            return;
+        const loaded = await this.loading;
+        const entries = new Map(loaded.entries);
+        const added = new Set();
+        for (const { file, stamp, summary } of this.recorded) {
+            const existing = entries.get(file);
+            if (existing && stampsMatch(existing.stamp, stamp))
+                continue;
+            const entry = toIndexEntry(file, stamp, summary);
+            if (!entry)
+                continue;
+            entries.set(file, entry);
+            added.add(entry);
+        }
+        const present = new Set(presentFiles.map((path) => basename(path)));
+        const live = [...entries.values()].filter((entry) => present.has(entry.file));
+        const kept = selectWithinBudget(live, this.maxBytes);
+        const keptBytes = kept.reduce((total, entry) => total + entry.lineBytes, 0);
+        const appended = kept.filter((entry) => added.has(entry));
+        const appendedBytes = appended.reduce((total, entry) => total + entry.lineBytes, 0);
+        try {
+            if ((!loaded.usable && kept.length > 0) ||
+                (loaded.usable && loaded.entryBytes + appendedBytes > 2 * keptBytes)) {
+                await rewriteIndexFile(this.path, kept);
+                this.remember(await statStamp(this.path), kept);
+            }
+            else if (loaded.usable && appended.length > 0) {
+                await appendIndexEntries(this.path, appended, loaded.endsWithNewline);
+                const inFile = new Map(loaded.entries);
+                for (const entry of appended)
+                    inFile.set(entry.file, entry);
+                this.remember(await statStamp(this.path), inFile.values());
+            }
+        }
+        catch (error) {
+            if (!(error instanceof Error))
+                throw error;
+            snapshots.delete(this.path);
+        }
+    }
+    async currentSnapshot() {
+        const recorded = snapshots.get(this.path);
+        if (!recorded)
+            return undefined;
+        const current = await statStamp(this.path);
+        return current && stampsMatch(current, recorded.indexStamp) ? recorded : undefined;
+    }
+    /** Stat before reading, so a concurrent writer can only make the snapshot look stale. */
+    async load() {
+        const before = await statStamp(this.path);
+        const loaded = await loadIndexFile(this.path);
+        this.remember(before, loaded.usable ? loaded.entries.values() : undefined);
+        return loaded;
+    }
+    remember(indexStamp, entries) {
+        if (!indexStamp || !entries) {
+            snapshots.delete(this.path);
+            return;
+        }
+        const entryStamps = new Map();
+        for (const entry of entries)
+            entryStamps.set(entry.file, entry.stamp);
+        snapshots.set(this.path, { indexStamp, entryStamps });
+    }
+}
+//# sourceMappingURL=session-summary-index.js.map

package/dist/core/session-summary-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-summary-index.js","sourceRoot":"","sources":["../../src/core/session-summary-index.ts"],"names":[],"mappings":"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","sourcesContent":["import { stat } from \"fs/promises\";\nimport { basename, join } from \"path\";\nimport type { SessionSummary } from \"./session-summary.ts\";\nimport type { SessionSummaryStore } from \"./session-summary-cache.ts\";\nimport {\n\tappendIndexEntries,\n\ttype IndexEntry,\n\ttype LoadedIndex,\n\tloadIndexFile,\n\trewriteIndexFile,\n\tSESSION_SUMMARY_INDEX_FILE,\n\ttoIndexEntry,\n} from \"./session-summary-index-file.ts\";\nimport type { FileStamp } from \"./session-summary-lru.ts\";\n\nexport { SESSION_SUMMARY_INDEX_FILE } from \"./session-summary-index-file.ts\";\n\n/**\n * Upper bound on live index bytes per sessions directory. It sits well above the\n * in-memory cache's 64 MiB because the index is read once per cold listing, not\n * retained; past it the least recently active sessions are left out and stream\n * like any cache miss.\n */\nexport const SESSION_SUMMARY_INDEX_MAX_BYTES = 256 * 1024 * 1024;\n\nexport type SessionSummaryIndexOptions = {\n\treadonly maxBytes?: number;\n};\n\ntype Recorded = {\n\treadonly file: string;\n\treadonly stamp: FileStamp;\n\treadonly summary: SessionSummary;\n};\n\n/**\n * What this process last saw in one index file: every entry's stamp, trusted\n * only while the index file keeps the size and mtime recorded with it. A warm\n * process uses it to skip loading the index for a file the index cannot serve\n * (changed since it was indexed, or never indexed, like a non-session file).\n */\ntype IndexSnapshot = {\n\treadonly indexStamp: FileStamp;\n\treadonly entryStamps: ReadonlyMap<string, FileStamp>;\n};\n\nconst snapshots = new Map<string, IndexSnapshot>();\n\n/** Forget every index snapshot, as a fresh process would start. */\nexport function forgetSessionSummaryIndexSnapshots(): void {\n\tsnapshots.clear();\n}\n\nfunction stampsMatch(left: FileStamp, right: FileStamp): boolean {\n\treturn left.size === right.size && left.mtimeMs === right.mtimeMs;\n}\n\nasync function statStamp(path: string): Promise<FileStamp | undefined> {\n\ttry {\n\t\tconst stats = await stat(path);\n\t\treturn { size: stats.size, mtimeMs: stats.mtimeMs };\n\t} catch (error) {\n\t\tif (error instanceof Error) return undefined;\n\t\tthrow error;\n\t}\n}\n\nfunction recency(entry: IndexEntry): number {\n\tconst headerTime = Date.parse(entry.summary.header.timestamp);\n\treturn entry.summary.lastActivityTime ?? (Number.isNaN(headerTime) ? 0 : headerTime);\n}\n\nfunction selectWithinBudget(entries: readonly IndexEntry[], maxBytes: number): IndexEntry[] {\n\tconst kept: IndexEntry[] = [];\n\tlet bytes = 0;\n\tfor (const entry of [...entries].sort((left, right) => recency(right) - recency(left))) {\n\t\tif (entry.lineBytes > maxBytes) continue;\n\t\tif (bytes + entry.lineBytes > maxBytes) break;\n\t\tkept.push(entry);\n\t\tbytes += entry.lineBytes;\n\t}\n\treturn kept;\n}\n\n/**\n * Persistent summaries for one sessions directory, stored as\n * `<dir>/.session-summaries.index` (senpi#2087).\n *\n * It is the second cache level behind the in-memory LRU: a cold process lists an\n * unchanged directory by reading this one file instead of re-streaming every\n * session. The file is loaded lazily on the first in-memory miss it can serve,\n * so a warm process does not read it again for a session that just changed.\n * Nothing here throws or logs: an unreadable, corrupt,\n * or unwritable index only means the listing streams, and its rows are\n * identical either way.\n */\nexport class SessionSummaryIndex implements SessionSummaryStore {\n\tprivate readonly path: string;\n\tprivate readonly maxBytes: number;\n\tprivate loading: Promise<LoadedIndex> | undefined;\n\tprivate snapshot: Promise<IndexSnapshot | undefined> | undefined;\n\tprivate readonly recorded: Recorded[] = [];\n\n\tconstructor(dir: string, options: SessionSummaryIndexOptions = {}) {\n\t\tthis.path = join(dir, SESSION_SUMMARY_INDEX_FILE);\n\t\tthis.maxBytes = options.maxBytes ?? SESSION_SUMMARY_INDEX_MAX_BYTES;\n\t}\n\n\tasync lookup(filePath: string, stamp: FileStamp): Promise<SessionSummary | undefined> {\n\t\tconst file = basename(filePath);\n\t\tif (!this.loading) {\n\t\t\tthis.snapshot ??= this.currentSnapshot();\n\t\t\tconst known = await this.snapshot;\n\t\t\tconst indexed = known?.entryStamps.get(file);\n\t\t\tif (known && !(indexed && stampsMatch(indexed, stamp))) return undefined;\n\t\t}\n\t\tthis.loading ??= this.load();\n\t\tconst entry = (await this.loading).entries.get(file);\n\t\treturn entry && stampsMatch(entry.stamp, stamp) ? entry.summary : undefined;\n\t}\n\n\trecord(filePath: string, stamp: FileStamp, summary: SessionSummary): void {\n\t\tthis.recorded.push({ file: basename(filePath), stamp, summary });\n\t}\n\n\t/**\n\t * Bring the index up to date after a listing of `presentFiles`.\n\t *\n\t * Summaries the index lacks are appended one line each. The file is rewritten\n\t * instead (temp file, then rename) when it is unusable, or when its entry\n\t * bytes exceed twice the live entries' bytes: superseded lines, torn lines,\n\t * removed sessions, and entries over the byte budget all count as dead.\n\t */\n\tasync persist(presentFiles: readonly string[]): Promise<void> {\n\t\tif (!this.loading) return;\n\t\tconst loaded = await this.loading;\n\t\tconst entries = new Map(loaded.entries);\n\t\tconst added = new Set<IndexEntry>();\n\t\tfor (const { file, stamp, summary } of this.recorded) {\n\t\t\tconst existing = entries.get(file);\n\t\t\tif (existing && stampsMatch(existing.stamp, stamp)) continue;\n\t\t\tconst entry = toIndexEntry(file, stamp, summary);\n\t\t\tif (!entry) continue;\n\t\t\tentries.set(file, entry);\n\t\t\tadded.add(entry);\n\t\t}\n\n\t\tconst present = new Set(presentFiles.map((path) => basename(path)));\n\t\tconst live = [...entries.values()].filter((entry) => present.has(entry.file));\n\t\tconst kept = selectWithinBudget(live, this.maxBytes);\n\t\tconst keptBytes = kept.reduce((total, entry) => total + entry.lineBytes, 0);\n\t\tconst appended = kept.filter((entry) => added.has(entry));\n\t\tconst appendedBytes = appended.reduce((total, entry) => total + entry.lineBytes, 0);\n\n\t\ttry {\n\t\t\tif (\n\t\t\t\t(!loaded.usable && kept.length > 0) ||\n\t\t\t\t(loaded.usable && loaded.entryBytes + appendedBytes > 2 * keptBytes)\n\t\t\t) {\n\t\t\t\tawait rewriteIndexFile(this.path, kept);\n\t\t\t\tthis.remember(await statStamp(this.path), kept);\n\t\t\t} else if (loaded.usable && appended.length > 0) {\n\t\t\t\tawait appendIndexEntries(this.path, appended, loaded.endsWithNewline);\n\t\t\t\tconst inFile = new Map(loaded.entries);\n\t\t\t\tfor (const entry of appended) inFile.set(entry.file, entry);\n\t\t\t\tthis.remember(await statStamp(this.path), inFile.values());\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tif (!(error instanceof Error)) throw error;\n\t\t\tsnapshots.delete(this.path);\n\t\t}\n\t}\n\n\tprivate async currentSnapshot(): Promise<IndexSnapshot | undefined> {\n\t\tconst recorded = snapshots.get(this.path);\n\t\tif (!recorded) return undefined;\n\t\tconst current = await statStamp(this.path);\n\t\treturn current && stampsMatch(current, recorded.indexStamp) ? recorded : undefined;\n\t}\n\n\t/** Stat before reading, so a concurrent writer can only make the snapshot look stale. */\n\tprivate async load(): Promise<LoadedIndex> {\n\t\tconst before = await statStamp(this.path);\n\t\tconst loaded = await loadIndexFile(this.path);\n\t\tthis.remember(before, loaded.usable ? loaded.entries.values() : undefined);\n\t\treturn loaded;\n\t}\n\n\tprivate remember(indexStamp: FileStamp | undefined, entries: Iterable<IndexEntry> | undefined): void {\n\t\tif (!indexStamp || !entries) {\n\t\t\tsnapshots.delete(this.path);\n\t\t\treturn;\n\t\t}\n\t\tconst entryStamps = new Map<string, FileStamp>();\n\t\tfor (const entry of entries) entryStamps.set(entry.file, entry.stamp);\n\t\tsnapshots.set(this.path, { indexStamp, entryStamps });\n\t}\n}\n"]}

package/dist/core/session-summary.d.ts

@@ -18,10 +18,29 @@ export type SessionSummary = {
     /** Full user/assistant transcript text in file order. */
     readonly allMessagesText: string;
 };
+/** What a completed {@link readFileLines} pass saw. */
+export type FileLinesRead = {
+    /** False when `onLine` stopped the pass early. */
+    readonly completed: boolean;
+    /** Bytes read from the file. */
+    readonly bytes: number;
+    /** Whether the last byte read was a newline (a torn tail has none). */
+    readonly endsWithNewline: boolean;
+};
+/**
+ * Read a file line by line through one reused 1 MiB buffer, handing each line
+ * (LF-split, a trailing CR dropped) to `onLine` until it returns false.
+ *
+ * This replaces `readline`, whose per-line async iteration dominated summary
+ * cost (senpi#2087). Only the unfinished tail of a chunk is carried between
+ * reads, and the next newline search resumes where the carried tail ends, so a
+ * record larger than the buffer is not rescanned per chunk. Read errors throw.
+ */
+export declare function readFileLines(filePath: string, onLine: (line: string) => boolean): Promise<FileLinesRead>;
 /**
- * Stream one session file line by line and fold it into an exact summary.
+ * Read one session file line by line and fold it into an exact summary.
  *
- * Memory stays bounded by readline's buffer plus the transcript text the summary
+ * Memory stays bounded by one read buffer plus the transcript text the summary
  * contract requires; no full-file string is ever materialized. A file whose
  * first record is not a session header, or that cannot be read, yields null.
  */

package/dist/core/session-summary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-summary.d.ts","sourceRoot":"","sources":["../../src/core/session-summary.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,yDAAyD;IACzD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC,CAAC;AA4DF;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA4BzF"}
+{"version":3,"file":"session-summary.d.ts","sourceRoot":"","sources":["../../src/core/session-summary.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,yDAAyD;IACzD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC,CAAC;AA8DF,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CAClC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAmC/G;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAsBzF"}