mixdog 0.9.174 → 1.0.0

package/src/runtime/agent/orchestrator/session/store-summary-index.mjs

@@ -5,14 +5,26 @@
  * file. store.mjs re-exports these so
  * importers stay unchanged.
  */
-import { join } from 'node:path';
+import { appendFileSync, mkdirSync, truncateSync } from 'node:fs';
+import { appendFile, mkdir, readdir, readFile, stat, truncate, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { getPluginData } from '../config.mjs';
-import { updateJsonAtomicSync, updateJsonAtomic, writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
+import {
+  withFileLock,
+  withFileLockSync,
+  writeJsonAtomicAsync,
+  writeJsonAtomicSync,
+} from '../../../shared/atomic-file.mjs';
+import {
+  applySummaryLogText,
+  encodeSummaryOps,
+  summaryLogPath,
+} from './store-summary-log.mjs';
 import {
   cleanSessionPreview,
   isSessionPreviewNoise,
   sessionMessageText,
-} from '../../../../session-runtime/session-text.mjs';
+} from '../runtime-core/session-text.mjs';
 import { sessionVisibility } from './store-summary-visibility.mjs';
 import { isStoredSessionId, positiveNumber as _positiveNumber } from './store-summary-fields.mjs';
 
@@ -257,15 +269,25 @@ export function _writeSummaryIndex(rows) {
     .map(_normalizeSummaryRow)
     .filter(Boolean)
     .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-  writeJsonAtomicSync(
-    summaryIndexPath(),
-    {
-      version: SESSION_SUMMARY_INDEX_VERSION,
-      updatedAt: Date.now(),
-      rows: cleanRows,
-    },
-    { compact: true, lock: true }
-  );
+  // A full rewrite is authoritative: the delta log is emptied under the same
+  // lock, or its older ops would replay over the fresh base.
+  const path = summaryIndexPath();
+  withFileLockSync(`${path}.lock`, () => {
+    writeJsonAtomicSync(
+      path,
+      {
+        version: SESSION_SUMMARY_INDEX_VERSION,
+        updatedAt: Date.now(),
+        rows: cleanRows,
+      },
+      { compact: true, lock: false }
+    );
+    try {
+      truncateSync(summaryLogPath(path), 0);
+    } catch {
+      /* no log yet */
+    }
+  });
   return cleanRows;
 }
 
@@ -282,6 +304,8 @@ export function _writeSummaryIndex(rows) {
 // caller's thread never blocks on this lock at all.
 const SUMMARY_LOCK_TIMEOUT_MS = 0; // try-lock: acquire-or-fail, never wait
 const SUMMARY_RETRY_DELAY_MS = 1000;
+// Delta-log size that triggers folding it into the base (see store-summary-log.mjs).
+const SUMMARY_LOG_COMPACT_BYTES = 1024 * 1024;
 const _pendingUpserts = new Map(); // id → summary row (latest wins)
 const _pendingRemovals = new Set(); // ids to drop (upsert/removal are mutually exclusive per id)
 let _summaryRetryTimer = null;
@@ -325,8 +349,7 @@ function _scheduleSummaryRetry() {
   if (_summarySettleWaiters.size === 0) _summaryRetryTimer.unref?.();
 }
 
-// Defer the flush off the caller's stack: the 1MB+ parse/stringify inside
-// updateJsonAtomicSync (~10ms on a warm cache) has no business on the
+// Defer the flush off the caller's stack: file I/O has no business on the
 // keystroke/session-save path.
 function _scheduleSummaryFlush() {
   if (_summaryFlushScheduled) return;
@@ -347,33 +370,13 @@ export function _flushPendingSummaryOps({ sync = false } = {}) {
   const removals = new Set(_pendingRemovals);
   _pendingUpserts.clear();
   _pendingRemovals.clear();
-  const mutate = (cur) => {
-    const index = _normalizeSummaryIndex(cur);
-    const existingById = new Map(index.rows.map((row) => [row.id, row]));
-    let changed = false;
-    const rows = index.rows.filter((r) => {
-      if (removals.has(r.id) || upserts.has(r.id)) {
-        changed = true;
-        return false;
-      }
-      return true;
-    });
-    for (const row of upserts.values()) {
-      const cleanRow = _normalizeSummaryRow(row);
-      if (!cleanRow) continue;
-      const existing = existingById.get(cleanRow.id) || null;
-      if (existing && JSON.stringify(existing) === JSON.stringify(cleanRow)) {
-        rows.push(existing);
-        continue;
-      }
-      rows.push(cleanRow);
-      changed = true;
-    }
-    if (!changed) return undefined;
-    rows.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-    return { version: SESSION_SUMMARY_INDEX_VERSION, updatedAt: Date.now(), rows };
-  };
-  const requeue = () => {
+  const cleanUpserts = [];
+  for (const row of upserts.values()) {
+    const cleanRow = _normalizeSummaryRow(row);
+    if (cleanRow) cleanUpserts.push(cleanRow);
+  }
+  const requeue = (error) => {
+    if (error?.code === 'ELOCKCONTENDED' || error?.code === 'ELOCKTIMEOUT') _recordSummaryLockFailure();
     // Lock busy (or transient I/O failure) — re-queue what we took unless
     // a newer op for the same id arrived during the flush, then retry
     // asynchronously.
@@ -389,30 +392,175 @@ export function _flushPendingSummaryOps({ sync = false } = {}) {
   // after 'exit'). Normal scheduled flushes on the lead/TUI main process
   // use the async try-lock: the lock WAIT is off the event loop, so a
   // busy multi-MB index never freezes typing/rendering.
+  if (cleanUpserts.length === 0 && removals.size === 0) return;
+  const text = encodeSummaryOps(cleanUpserts, removals);
+  const path = summaryIndexPath();
   if (sync) {
+    // Exit drain: append only (never compact — that is a full rewrite).
     try {
-      updateJsonAtomicSync(summaryIndexPath(), mutate, {
-        compact: true,
-        lock: true,
-        timeoutMs: SUMMARY_LOCK_TIMEOUT_MS,
-      });
-    } catch {
-      requeue();
+      withFileLockSync(
+        `${path}.lock`,
+        () => {
+          mkdirSync(dirname(path), { recursive: true });
+          appendFileSync(summaryLogPath(path), text, { mode: 0o600 });
+        },
+        { timeoutMs: SUMMARY_LOCK_TIMEOUT_MS }
+      );
+    } catch (error) {
+      requeue(error);
     }
     _notifySummarySettled();
     return;
   }
   _summaryFlushInflight++;
-  updateJsonAtomic(summaryIndexPath(), mutate, { compact: true, lock: true, timeoutMs: SUMMARY_LOCK_TIMEOUT_MS })
-    .catch(() => {
-      requeue();
-    })
+  withFileLock(`${path}.lock`, () => _appendSummaryOpsLocked(path, text), { timeoutMs: SUMMARY_LOCK_TIMEOUT_MS })
+    .then(() => _sweepStaleSummaryTempOnce(path))
+    .catch(requeue)
     .finally(() => {
       _summaryFlushInflight--;
       _notifySummarySettled();
     });
 }
 
+// Append one batch of ops to the delta log; fold the log into the base once it
+// outgrows SUMMARY_LOG_COMPACT_BYTES. Runs under the index lock.
+async function _appendSummaryOpsLocked(path, text) {
+  const logPath = summaryLogPath(path);
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(logPath, text, { mode: 0o600 });
+  // The ops are durable once appended; a failed compaction is retried by a
+  // later flush and must not re-queue (and re-append) this batch.
+  try {
+    if ((await stat(logPath)).size >= SUMMARY_LOG_COMPACT_BYTES) await _compactSummaryIndexLocked(path);
+  } catch {
+    /* best effort */
+  }
+}
+
+/** Fold base + log into a fresh base and empty the log. The caller holds the
+ *  index lock, which every appender and full rewrite also takes. A crash
+ *  between the two steps leaves ops in the log that the new base already
+ *  has; replay is last-writer-wins per id, so that is harmless. */
+async function _compactSummaryIndexLocked(path) {
+  const logPath = summaryLogPath(path);
+  let logText = '';
+  try {
+    logText = await readFile(logPath, 'utf8');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  let base = null;
+  try {
+    base = JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    if (error?.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
+  }
+  const { rows } = _normalizeSummaryIndex(applySummaryLogText(base ?? {}, logText));
+  await writeJsonAtomicAsync(
+    path,
+    { version: SESSION_SUMMARY_INDEX_VERSION, updatedAt: Date.now(), rows },
+    { compact: true, lock: false }
+  );
+  await truncate(logPath, 0);
+}
+
+/** Fold the delta log into the base now (tests, maintenance). Resolves false
+ *  when another process holds the index lock. */
+export async function compactSummaryIndex() {
+  const path = summaryIndexPath();
+  try {
+    await withFileLock(`${path}.lock`, () => _compactSummaryIndexLocked(path), { timeoutMs: SUMMARY_LOCK_TIMEOUT_MS });
+    return true;
+  } catch (error) {
+    if (error?.code === 'ELOCKCONTENDED' || error?.code === 'ELOCKTIMEOUT') {
+      _recordSummaryLockFailure();
+      return false;
+    }
+    throw error;
+  }
+}
+
+// ── Try-lock failure accounting ─────────────────────────────────────────────
+// A refused try-lock re-queues and retries every SUMMARY_RETRY_DELAY_MS; that
+// used to be invisible. Failures are counted and reported at most once per
+// SUMMARY_LOCK_FAILURE_LOG_INTERVAL_MS (the first one immediately).
+const SUMMARY_LOCK_FAILURE_LOG_INTERVAL_MS = 60_000;
+let _lockFailuresTotal = 0;
+let _lockFailuresUnreported = 0;
+let _lastLockFailureReportAt = 0;
+
+function _recordSummaryLockFailure(now = Date.now()) {
+  _lockFailuresTotal += 1;
+  _lockFailuresUnreported += 1;
+  if (_lastLockFailureReportAt !== 0 && now - _lastLockFailureReportAt < SUMMARY_LOCK_FAILURE_LOG_INTERVAL_MS) return;
+  process.stderr.write(
+    `[session-summaries] index lock busy: ${_lockFailuresUnreported} try-lock failure(s) since last report ` +
+      `(${_lockFailuresTotal} total); retrying every ${SUMMARY_RETRY_DELAY_MS}ms\n`
+  );
+  _lastLockFailureReportAt = now;
+  _lockFailuresUnreported = 0;
+}
+
+/** Diagnostic seam: try-lock failures seen by this process. */
+export function summaryLockFailureStats() {
+  return { total: _lockFailuresTotal, unreported: _lockFailuresUnreported };
+}
+
+// ── Stale temp sweep ────────────────────────────────────────────────────────
+// A crash between an atomic write's temp file and its rename orphans
+// `.session-summaries.json.<24 hex>.tmp` (multi-MB each). Only this store's
+// pattern is touched. Deleted only when older than SUMMARY_TMP_MIN_AGE_MS and
+// while holding the index lock: every writer of these temps (full rewrite,
+// compaction) holds that lock for the whole write, so no live writer can own a
+// temp file the sweep sees.
+const SUMMARY_TMP_PATTERN = /^\.session-summaries\.json\.[0-9a-f]{24}\.tmp$/;
+const SUMMARY_TMP_MIN_AGE_MS = 10 * 60 * 1000;
+let _sweptSummaryDir = '';
+
+export async function sweepStaleSummaryTempFiles({ now = Date.now(), minAgeMs = SUMMARY_TMP_MIN_AGE_MS } = {}) {
+  const path = summaryIndexPath();
+  const dir = dirname(path);
+  return withFileLock(
+    `${path}.lock`,
+    async () => {
+      let removed = 0;
+      let names;
+      try {
+        names = await readdir(dir);
+      } catch {
+        return 0;
+      }
+      for (const name of names) {
+        if (!SUMMARY_TMP_PATTERN.test(name)) continue;
+        const file = join(dir, name);
+        try {
+          if (now - (await stat(file)).mtimeMs < minAgeMs) continue;
+          await unlink(file);
+          removed += 1;
+        } catch {
+          /* raced away or unremovable: leave it */
+        }
+      }
+      return removed;
+    },
+    { timeoutMs: SUMMARY_LOCK_TIMEOUT_MS }
+  );
+}
+
+// Once per process and data dir, after the first successful flush. A busy lock
+// skips this round; the next flush tries again.
+async function _sweepStaleSummaryTempOnce(path) {
+  const dir = dirname(path);
+  if (_sweptSummaryDir === dir) return;
+  try {
+    const removed = await sweepStaleSummaryTempFiles();
+    _sweptSummaryDir = dir;
+    if (removed > 0) process.stderr.write(`[session-summaries] removed ${removed} stale temp file(s)\n`);
+  } catch {
+    /* lock busy or I/O error: best effort */
+  }
+}
+
 export function _upsertSessionSummary(session) {
   const row = _sessionSummary(session);
   _upsertSessionSummaryRow(row);

package/src/runtime/agent/orchestrator/session/store-summary-log.mjs

@@ -0,0 +1,81 @@
+/**
+ * Delta log of the session summary index (leaf: fs/path only, so the cold
+ * desktop catalog reader can use it without pulling in lock writers).
+ *
+ * Layout: `session-summaries.json` stays the compacted base (version 2, exactly
+ * the historical format). Per-session changes are appended as one JSON line
+ * each to `session-summaries.log` and replayed over the base by every reader;
+ * a compaction (store-summary-index.mjs, under the index lock) folds the log
+ * into the base and empties it. A session update therefore costs one appended
+ * line instead of rewriting every session.
+ *
+ * Line format (one JSON object per line):
+ *   {"u": <summary row>}    upsert the row keyed by its id
+ *   {"r": ["id", ...]}      remove these ids
+ * Replay is last-writer-wins per id, so re-applying a log that a crashed
+ * compaction already folded into the base is harmless. Unparseable lines (a
+ * torn tail) are skipped.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const SUMMARY_LOG_FILENAME = 'session-summaries.log';
+
+export function summaryLogPath(indexPath) {
+  return join(dirname(indexPath), SUMMARY_LOG_FILENAME);
+}
+
+// The leading newline terminates a torn tail left by a crashed append, so it
+// can never fuse with (and corrupt) the first record of this one.
+export function encodeSummaryOps(upserts, removals) {
+  let text = '\n';
+  for (const row of upserts) text += `${JSON.stringify({ u: row })}\n`;
+  const ids = [...removals];
+  if (ids.length > 0) text += `${JSON.stringify({ r: ids })}\n`;
+  return text;
+}
+
+/** The log text, or '' when it is absent/unreadable. Read it BEFORE the base:
+ *  a compaction landing between the two reads then replays already-folded ops
+ *  (harmless) instead of hiding ops the new base has and the old one lacks. */
+export function readSummaryLogText(indexPath) {
+  try {
+    return readFileSync(summaryLogPath(indexPath), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/** `raw` (parsed base) with the log's ops replayed over its rows. */
+export function applySummaryLogText(raw, logText) {
+  if (!logText || !raw || typeof raw !== 'object') return raw;
+  const byId = new Map();
+  for (const row of Array.isArray(raw.rows) ? raw.rows : []) {
+    if (row && typeof row.id === 'string') byId.set(row.id, row);
+  }
+  for (const line of logText.split('\n')) {
+    if (!line) continue;
+    let op;
+    try {
+      op = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (op?.u && typeof op.u.id === 'string') byId.set(op.u.id, op.u);
+    else if (Array.isArray(op?.r)) for (const id of op.r) byId.delete(id);
+  }
+  return { ...raw, rows: [...byId.values()] };
+}
+
+/** Change stamp of base + log: the newest mtime of either (0 when neither exists). */
+export function summaryIndexStampMs(indexPath) {
+  let stamp = 0;
+  for (const path of [indexPath, summaryLogPath(indexPath)]) {
+    try {
+      stamp = Math.max(stamp, statSync(path).mtimeMs || 0);
+    } catch {
+      /* absent */
+    }
+  }
+  return stamp;
+}

package/src/runtime/agent/orchestrator/session/store-summary-reader.mjs

@@ -7,6 +7,7 @@
  * reconnect recovery boundary so restored panes never paint a stale prompt.
  */
 import { readdirSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 // Leaf helpers only (no store.mjs, no workers, no config): the three-way
 // present/absent/unreadable classification and the strict record parser the
@@ -14,7 +15,9 @@ import { join } from 'node:path';
 import { probePath, readTextFile, PROBE_PRESENT, PROBE_ABSENT } from './store/fs-probe.mjs';
 import { readTopLevelLifecycleRecord, isLifecycleUnreadable } from './lifecycle-scan.mjs';
 import { isAgentOnlySession, isRootLeadSession, sessionVisibility } from './store-summary-visibility.mjs';
-import { createStoredTranscriptCache } from './store-transcript-cache.mjs';
+import { applySummaryLogText, readSummaryLogText } from './store-summary-log.mjs';
+import { createStoredTranscriptCache, nextProjectionStamp } from './store-transcript-cache.mjs';
+import { OFFLOAD_MIN_CHARS, projectStoredTranscriptOffThread } from './store-transcript-worker.mjs';
 import { projectStoredTranscript } from './store-transcript-projection.mjs';
 import { dataDir, sessionHeartbeatMtimes } from './store-summary-locations.mjs';
 import { desktopSession, isStoredSessionId, positiveNumber } from './store-summary-fields.mjs';
@@ -341,10 +344,13 @@ export function listStoredSessionSummaries(options = {}) {
   // an individual session file cannot be read.
   const indexRowsById = new Map();
   let indexRows = null;
+  // The delta log (per-session updates since the last compaction) is read
+  // before the base; see store-summary-log.mjs.
+  const logText = readSummaryLogText(indexPath);
   const indexRead = readTextFile(indexPath);
   if (indexRead.state === PROBE_PRESENT) {
     try {
-      const index = JSON.parse(indexRead.text);
+      const index = applySummaryLogText(JSON.parse(indexRead.text), logText);
       if (Number(index?.version) === SESSION_SUMMARY_INDEX_VERSION) {
         const normalizedRows = (Array.isArray(index.rows) ? index.rows : [])
           .map((row) => normalizedRow(row, heartbeatMtimes.get(row?.id) || 0))
@@ -494,6 +500,9 @@ export async function readStoredSessionTranscript(id, options = {}) {
   // The strict record parse (full JSON + duplicate-key scan) is itself a
   // large share of a cold read, so it only runs when the content is new.
   const mode = options.includeMessages === true ? 'messages' : 'items';
+  // Large, checkpoint-free item projections run off the daemon event loop.
+  const offloadable =
+    options.includeMessages !== true && checkpoint.state === PROBE_ABSENT && recordStat.size >= OFFLOAD_MIN_CHARS;
   const { value, hit, read } = await storedTranscriptCache.read({
     key: `${sessionId}|${itemLimit}|${mode}`,
     // Growing history windows of one session replace each other.
@@ -507,9 +516,19 @@ export async function readStoredSessionTranscript(id, options = {}) {
       checkpoint.dev,
     ].join(':'),
     fileStat: recordStat,
-    loadText: () => {
+    loadText: async () => {
       const before = observeStamp(recordPath);
-      const body = readTextFile(recordPath);
+      let body = null;
+      if (offloadable) {
+        // Reading a large record asynchronously keeps its multi-megabyte
+        // UTF-8 decode-and-copy off the loop; failures are classified below.
+        try {
+          body = { state: PROBE_PRESENT, text: (await readFile(recordPath)).toString('utf8') };
+        } catch {
+          body = null;
+        }
+      }
+      body ||= readTextFile(recordPath);
       readState = body.state;
       if (body.state !== PROBE_PRESENT) return null;
       readStamp = before && sameSessionStamp(before, observeStamp(recordPath)) ? before : null;
@@ -517,6 +536,21 @@ export async function readStoredSessionTranscript(id, options = {}) {
     },
     produce: async (text) => {
       const stamp = readStamp;
+      // A large record with no checkpoint sidecar parses and projects on a
+      // worker thread: the same pipeline, off the daemon event loop. It hands
+      // no parse to the load cache (a later resume reads the file itself).
+      if (offloadable && text.length >= OFFLOAD_MIN_CHARS) {
+        try {
+          const answer = await projectStoredTranscriptOffThread({ sessionId, text, itemLimit });
+          if (answer.unreadable) return null;
+          if (stamp) readCanonicalLifecycle.rememberStrictVerdict(recordPath, stamp, answer.lifecycle);
+          // Stamps are process-unique per module realm; re-issue in this one.
+          answer.value.projectionStamp = nextProjectionStamp();
+          return answer.value;
+        } catch {
+          // Worker unavailable: fall through to the in-process pipeline.
+        }
+      }
       const record = readTopLevelLifecycleRecord(text);
       if (isLifecycleUnreadable(record) || record.id !== sessionId) return null;
       // The same strict verdict the lifecycle authority would reach for these

package/src/runtime/agent/orchestrator/session/store-transcript-cache.mjs

@@ -20,7 +20,7 @@ import { createHash } from 'node:crypto';
 // Serialized (UTF-8 JSON) bytes of the retained PROJECTIONS. A tail-window
 // projection is ~0.1-1 MB; a legacy 512-item page of a worker transcript can
 // reach ~16 MB, so this keeps a couple of those or dozens of tail windows.
-export const STORED_TRANSCRIPT_CACHE_MAX_BYTES = 32 * 1024 * 1024;
+const STORED_TRANSCRIPT_CACHE_MAX_BYTES = 32 * 1024 * 1024;
 // Coarse filesystems stamp mtime at whole seconds (FAT: two). A write landing
 // inside that window after our read could keep the same stat, so only a file
 // untouched for longer than this is trusted by stat alone.
@@ -143,7 +143,10 @@ export function createStoredTranscriptCache({
         touch(key, cached, now);
         return { value: cached.value, hit: true, read: false };
       }
-      const text = loadText();
+      // `loadText` may answer asynchronously (a large record is read without
+      // blocking the loop); a plain string is unchanged.
+      let text = loadText();
+      if (typeof text?.then === 'function') text = await text;
       if (typeof text !== 'string') return { value: null, hit: false, read: true };
       // UTF-16 preserves exact JavaScript code units, including lone surrogates
       // that UTF-8 would collapse into the same replacement character.

package/src/runtime/agent/orchestrator/session/store-transcript-projection.mjs

@@ -9,7 +9,7 @@
  * that lazily enters the heavier reconnect-recovery boundary (dynamic imports
  * preserved verbatim so the cold summary path stays leaf-only).
  */
-import { sessionContextMeasurement, contextMeasurementStats } from '../../../../ui/context-measurement.mjs';
+import { sessionContextMeasurement, contextMeasurementStats } from '../../../shared/context-measurement.mjs';
 import { nextProjectionStamp } from './store-transcript-cache.mjs';
 import { cleanValue, desktopSession, positiveNumber } from './store-summary-fields.mjs';
 
@@ -41,14 +41,12 @@ export async function projectStoredTranscript(sessionId, doc, options) {
       if (session?.activeTurnCheckpoint) projectCheckpoint();
     }
   }
-  const { restoreTranscriptItems, sessionContextSnapshotProjection } = await import(
-    '../../../../tui/session/session-api-ext.mjs'
-  );
+  const { restoreTranscriptItems, sessionContextSnapshotProjection } = await import('./transcript-restore/restore.mjs');
   let preparedContextProjection = null;
   try {
     const [{ prepareSessionProjection }, { createContextStatus }, { primeContextEstimates }] = await Promise.all([
       import('./manager.mjs'),
-      import('../../../../session-runtime/context-status.mjs'),
+      import('../runtime-core/context-status.mjs'),
       import('./context-utils.mjs'),
     ]);
     const prepared = prepareSessionProjection(session, 'full');

package/src/runtime/agent/orchestrator/session/store-transcript-worker.mjs

@@ -0,0 +1,54 @@
+/**
+ * Off-thread parse + projection of a large stored transcript.
+ *
+ * The strict record parse and the transcript projection of a multi-megabyte
+ * session took 0.4-3s of daemon event-loop time (`slow stored projection`).
+ * This module runs exactly that pure pipeline (readTopLevelLifecycleRecord →
+ * projectStoredTranscript with no turn checkpoint) on a lazily started worker
+ * thread and hands back the same projection value. The worker loads its own
+ * module graph; only the finished projection crosses back.
+ *
+ * Client (main thread): `projectStoredTranscriptOffThread`. Worker side is
+ * active only when this file is loaded as a worker of that client.
+ */
+import { isMainThread, workerData } from 'node:worker_threads';
+import { createWorkerRequestClient, serveWorkerRequests } from '../../../shared/worker-requests.mjs';
+
+/** Records at least this many characters go to the worker; smaller ones cost
+ *  less on the main thread than the round trip. */
+export const OFFLOAD_MIN_CHARS = 1_000_000;
+const WORKER_KIND = 'stored-transcript-projection';
+const IDLE_EXIT_MS = 120_000;
+
+let client = null;
+
+/**
+ * Parse and project `text` for `sessionId`. Resolves `{ unreadable: true }`
+ * when the record is not a strict, identity-matching session record, else
+ * `{ value, lifecycle }` where `lifecycle` is `{ id, closed, generation }`.
+ * Rejects when the worker cannot answer; callers fall back to the main thread.
+ */
+export function projectStoredTranscriptOffThread({ sessionId, text, itemLimit }) {
+  client ||= createWorkerRequestClient(new URL(import.meta.url), {
+    idleExitMs: IDLE_EXIT_MS,
+    workerData: { kind: WORKER_KIND },
+  });
+  return client({ sessionId, text, itemLimit });
+}
+
+async function project({ sessionId, text, itemLimit }) {
+  const [{ readTopLevelLifecycleRecord, isLifecycleUnreadable }, { projectStoredTranscript }] = await Promise.all([
+    import('./lifecycle-scan.mjs'),
+    import('./store-transcript-projection.mjs'),
+  ]);
+  const record = readTopLevelLifecycleRecord(text);
+  if (isLifecycleUnreadable(record) || record.id !== sessionId) return { unreadable: true };
+  const value = await projectStoredTranscript(sessionId, record.doc, {
+    itemLimit,
+    includeMessages: false,
+    checkpointAbsent: true,
+  });
+  return { value, lifecycle: { id: record.id, closed: record.closed, generation: record.generation } };
+}
+
+if (!isMainThread && workerData?.kind === WORKER_KIND) serveWorkerRequests(project);

package/src/runtime/agent/orchestrator/session/store.mjs

@@ -707,13 +707,9 @@ export { loadSession } from './store/load-session.mjs';
 // re-exported here so prior importers of store.mjs stay unchanged.
 export { deleteSession, listOwnedAgentSessionIds } from './store/session-delete.mjs';
 
-// Listing / summaries / stale sweeping live in store/listing.mjs; re-exported
-// here so importers keep one session-store entry point.
-export {
-  listStoredSessions,
-  listStoredSessionSummaries,
-  getStoredSessionsRaw,
-  sweepStaleSessions,
-  sweepStaleSessionsCooperative,
-} from './store/listing.mjs';
+// Listing / summaries live in store/listing.mjs and the stale sweep in
+// store/sweep/stale-sweep.mjs; re-exported here so importers keep one
+// session-store entry point.
+export { listStoredSessions, listStoredSessionSummaries, getStoredSessionsRaw } from './store/listing.mjs';
+export { sweepStaleSessions, sweepStaleSessionsCooperative } from './store/sweep/stale-sweep.mjs';
 export { _savePending } from './store/pending-saves.mjs';