@cloudcli-ai/cloudcli 1.37.2 → 1.37.4

package/server/modules/providers/services/provider-models.service.ts

@@ -1,5 +1,6 @@
 import { providerModelsDb, sessionsDb } from '@/modules/database/index.js';
 import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import { providerCapabilitiesService } from '@/modules/providers/services/provider-capabilities.service.js';
 import type { IProvider } from '@/shared/interfaces.js';
 import type {
   CustomProviderModelInput,
@@ -36,6 +37,15 @@ type ProviderModelsServiceDependencies = {
   sessions?: ProviderModelsSessionStore;
 };
 
+/**
+ * Converts a stored custom row into a catalog option.
+ *
+ * `effort` is emitted in the same shape predefined models use, so the composer
+ * and every runtime's effort validation treat declared levels identically.
+ * Rows without declared levels omit `effort` on purpose: the composer then
+ * hides Reasoning and runtimes send no effort, instead of guessing levels the
+ * model might reject.
+ */
 const toCustomProviderModelOption = (
   record: CustomProviderModelRecord,
 ): ProviderModelOption => ({
@@ -43,9 +53,32 @@ const toCustomProviderModelOption = (
   label: record.model,
   recordId: record.recordId,
   isCustom: true,
+  ...(record.effort
+    ? {
+      effort: {
+        ...(record.effort.default ? { default: record.effort.default } : {}),
+        values: record.effort.values.map((value) => ({ value })),
+      },
+    }
+    : {}),
 });
 
+/**
+ * Effort levels a custom model of this provider may declare, weakest first:
+ * the levels its runtime can pass on, from the capability matrix. Empty
+ * (Cursor) means no effort support at all.
+ *
+ * Deliberately not derived from the predefined models: OpenCode narrows its
+ * catalog to the upstream providers this machine has connected, and only its
+ * OpenCode Go models declare effort, so a catalog-derived set would vanish for
+ * Zen, Anthropic, or OpenAI users and change with unrelated credentials.
+ */
+const readCustomModelEffortLevels = (provider: LLMProvider): string[] => (
+  providerCapabilitiesService.getProviderCapabilities(provider).effortLevels
+);
+
 const mergeProviderModels = (
+  provider: LLMProvider,
   predefined: ProviderModelsDefinition,
   custom: CustomProviderModelRecord[],
 ): ProviderModelsDefinition => {
@@ -55,14 +88,46 @@ const mergeProviderModels = (
       ...custom.map(toCustomProviderModelOption),
     ],
     DEFAULT: predefined.DEFAULT,
+    // Copied so no caller can mutate the shared capability matrix.
+    EFFORT_LEVELS: [...readCustomModelEffortLevels(provider)],
   };
 };
 
 const normalizeCustomModelInput = (input: CustomProviderModelInput): CustomProviderModelInput => ({
   id: input.id.trim(),
   model: input.model.trim(),
+  ...(input.effort === undefined ? {} : { effort: input.effort }),
 });
 
+const assertEffortLevelsSupported = (
+  provider: LLMProvider,
+  input: CustomProviderModelInput,
+): void => {
+  const declaredLevels = input.effort?.values ?? [];
+  if (declaredLevels.length === 0) {
+    return;
+  }
+
+  const supportedLevels = readCustomModelEffortLevels(provider);
+  if (supportedLevels.length === 0) {
+    throw new AppError(`${provider} models do not support reasoning effort.`, {
+      code: 'MODEL_EFFORT_NOT_SUPPORTED',
+      statusCode: 400,
+    });
+  }
+
+  const unsupportedLevel = declaredLevels.find((level) => !supportedLevels.includes(level));
+  if (unsupportedLevel) {
+    throw new AppError(
+      `"${unsupportedLevel}" is not a ${provider} effort level. Use one of: ${supportedLevels.join(', ')}.`,
+      {
+        code: 'INVALID_MODEL_EFFORT',
+        statusCode: 400,
+      },
+    );
+  }
+};
+
 const isUniqueConstraintError = (error: unknown): boolean => (
   error !== null
   && error !== undefined
@@ -87,7 +152,7 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
 
   const getProviderModels = async (provider: LLMProvider): Promise<ProviderModelsDefinition> => {
     const predefined = await resolveProvider(provider).models.getSupportedModels();
-    return mergeProviderModels(predefined, catalog.listCustomProviderModels(provider));
+    return mergeProviderModels(provider, predefined, catalog.listCustomProviderModels(provider));
   };
 
   const getCurrentActiveModel = async (
@@ -139,12 +204,13 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
     const predefined = await resolveProvider(provider).models.getSupportedModels();
     const normalized = normalizeCustomModelInput(input);
     assertModelIdAvailable(provider, predefined, normalized.id);
+    assertEffortLevelsSupported(provider, normalized);
 
     try {
       const created = catalog.createCustomProviderModel(provider, normalized);
       return {
         model: toCustomProviderModelOption(created),
-        models: mergeProviderModels(predefined, catalog.listCustomProviderModels(provider)),
+        models: mergeProviderModels(provider, predefined, catalog.listCustomProviderModels(provider)),
       };
     } catch (error) {
       if (isUniqueConstraintError(error)) {
@@ -166,6 +232,7 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
     readCustomModel(provider, recordId);
     const normalized = normalizeCustomModelInput(input);
     assertModelIdAvailable(provider, predefined, normalized.id, recordId);
+    assertEffortLevelsSupported(provider, normalized);
 
     try {
       const updated = catalog.updateCustomProviderModel(provider, recordId, normalized);
@@ -178,7 +245,7 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
 
       return {
         model: toCustomProviderModelOption(updated),
-        models: mergeProviderModels(predefined, catalog.listCustomProviderModels(provider)),
+        models: mergeProviderModels(provider, predefined, catalog.listCustomProviderModels(provider)),
       };
     } catch (error) {
       if (isUniqueConstraintError(error)) {
@@ -207,7 +274,7 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
 
     return {
       model: toCustomProviderModelOption(removed),
-      models: mergeProviderModels(predefined, catalog.listCustomProviderModels(provider)),
+      models: mergeProviderModels(provider, predefined, catalog.listCustomProviderModels(provider)),
     };
   };
 

package/server/modules/providers/services/provider-runtime.service.ts

@@ -91,6 +91,17 @@ export function createProviderRuntimeService(
       return Boolean(await dependencies.resolveProvider(providerName).runtime.abort(sessionId));
     },
 
+    async stopBackgroundTask(providerName: LLMProvider, sessionId: string, taskId: string): Promise<boolean> {
+      // A runtime that never holds background work has no task to stop.
+      const { runtime } = dependencies.resolveProvider(providerName);
+      return Boolean(await runtime.stopBackgroundTask?.(sessionId, taskId));
+    },
+
+    hasBackgroundWork(sessionId: string): boolean {
+      return dependencies.listProviders().some((provider) =>
+        (provider.runtime.listBackgroundWork?.() ?? []).some((entry) => entry.sessionId === sessionId));
+    },
+
     resolveToolApproval(requestId: string, decision: ProviderPermissionDecision): void {
       for (const provider of dependencies.listProviders()) {
         provider.runtime.permissions?.resolve(requestId, decision);

package/server/modules/providers/services/provider-token-usage.service.ts

@@ -11,6 +11,12 @@ import { AppError, getOpenCodeDatabasePath } from '@/shared/utils.js';
 
 type SessionRow = NonNullable<ReturnType<typeof sessionsDb.getSessionById>>;
 
+type FileTail = {
+  content: string;
+  /** True when `content` is the whole file, not just its trailing bytes. */
+  isComplete: boolean;
+};
+
 type ProviderTokenUsageServiceDependencies = {
   getSessionById: (sessionId: string) => SessionRow | null | undefined;
   getHomeDirectory: () => string;
@@ -18,7 +24,9 @@ type ProviderTokenUsageServiceDependencies = {
   fileExists: (filePath: string) => boolean;
   readDirectory: (directoryPath: string) => Promise<Dirent[]>;
   readTextFile: (filePath: string) => Promise<string>;
+  readTextFileTail: (filePath: string, maxBytes: number) => Promise<FileTail>;
   getClaudeContextWindow: () => string | undefined;
+  isProviderSessionSuperseded: (providerSessionId: string, provider: string) => boolean;
 };
 
 type TokenUsageResult = {
@@ -45,6 +53,14 @@ type OpenCodeTokenRow = {
   cacheWriteTokens: number | null;
 };
 
+/**
+ * Both JSONL usage readers below only need the newest usage row, which sits at
+ * or near the end of the transcript. Reading just this much of the tail keeps
+ * a session-open usage lookup O(1) in the transcript's size; the rare tail
+ * with no usage row at all falls back to the full read.
+ */
+const TOKEN_USAGE_TAIL_BYTES = 4 * 1024 * 1024;
+
 const defaultDependencies: ProviderTokenUsageServiceDependencies = {
   getSessionById: (sessionId) => sessionsDb.getSessionById(sessionId),
   getHomeDirectory: () => os.homedir(),
@@ -52,7 +68,32 @@ const defaultDependencies: ProviderTokenUsageServiceDependencies = {
   fileExists: (filePath) => fsSync.existsSync(filePath),
   readDirectory: (directoryPath) => fsp.readdir(directoryPath, { withFileTypes: true }),
   readTextFile: (filePath) => fsp.readFile(filePath, 'utf8'),
+  readTextFileTail: async (filePath, maxBytes) => {
+    const handle = await fsp.open(filePath, 'r');
+    try {
+      const { size } = await handle.stat();
+      if (size <= maxBytes) {
+        return { content: await handle.readFile({ encoding: 'utf8' }), isComplete: true };
+      }
+
+      const buffer = Buffer.alloc(maxBytes);
+      await handle.read(buffer, 0, maxBytes, size - maxBytes);
+      const content = buffer.toString('utf8');
+      // The window almost never starts on a row boundary; dropping everything
+      // up to the first newline discards the partial row (and any split
+      // multi-byte character with it).
+      const firstNewline = content.indexOf('\n');
+      return {
+        content: firstNewline === -1 ? '' : content.slice(firstNewline + 1),
+        isComplete: false,
+      };
+    } finally {
+      await handle.close();
+    }
+  },
   getClaudeContextWindow: () => process.env.CONTEXT_WINDOW,
+  isProviderSessionSuperseded: (providerSessionId, provider) =>
+    sessionsDb.isProviderSessionSuperseded(providerSessionId, provider),
 };
 
 function readUsageNumber(value: unknown): number {
@@ -92,11 +133,8 @@ async function findCodexSessionFile(
   return null;
 }
 
-function readCodexTokenUsage(fileContent: string): TokenUsageResult {
-  let inputTokens = 0;
-  let outputTokens = 0;
-  let totalTokens = 0;
-  let contextWindow = 200_000;
+/** Newest `token_count` snapshot in the given JSONL text, or null when it has none. */
+function findCodexTokenUsage(fileContent: string): TokenUsageResult | null {
   const lines = fileContent.trim().split('\n');
 
   for (let index = lines.length - 1; index >= 0; index -= 1) {
@@ -109,58 +147,101 @@ function readCodexTokenUsage(fileContent: string): TokenUsageResult {
         continue;
       }
 
+      let inputTokens = 0;
+      let outputTokens = 0;
+      let totalTokens = 0;
       if (tokenInfo.total_token_usage) {
         inputTokens = readUsageNumber(tokenInfo.total_token_usage.input_tokens);
         outputTokens = readUsageNumber(tokenInfo.total_token_usage.output_tokens);
         totalTokens = readUsageNumber(tokenInfo.total_token_usage.total_tokens)
           || inputTokens + outputTokens;
       }
-      contextWindow = readUsageNumber(tokenInfo.model_context_window) || contextWindow;
-      break;
+      return {
+        used: totalTokens,
+        total: readUsageNumber(tokenInfo.model_context_window) || 200_000,
+        inputTokens,
+        outputTokens,
+        breakdown: { input: inputTokens, output: outputTokens },
+      };
     } catch {
       // A provider may be writing the last JSONL line while this read happens.
     }
   }
 
+  return null;
+}
+
+function emptyCodexTokenUsage(): TokenUsageResult {
   return {
-    used: totalTokens,
-    total: contextWindow,
-    inputTokens,
-    outputTokens,
-    breakdown: { input: inputTokens, output: outputTokens },
+    used: 0,
+    total: 200_000,
+    inputTokens: 0,
+    outputTokens: 0,
+    breakdown: { input: 0, output: 0 },
   };
 }
 
-function readClaudeTokenUsage(fileContent: string, configuredContextWindow: string | undefined): TokenUsageResult {
+/**
+ * Latest context-window usage from a Claude transcript's already-parsed rows.
+ *
+ * Exported because the session-messages reader hands the same usage back on
+ * every history page, the way the Codex and OpenCode readers do. Without that,
+ * a Claude session's counter only moved when the session was reselected, and
+ * the store's "this provider reports no usage" path overwrote it with zero.
+ *
+ * Reads the newest assistant turn only: `input_tokens + cache_read +
+ * cache_creation` is that one request's whole prompt, i.e. what the context
+ * window currently holds. Summing turns would count the same cached prefix
+ * once per turn.
+ */
+export function summarizeClaudeTokenUsage(
+  entries: AnyRecord[],
+  configuredContextWindow: string | undefined = process.env.CONTEXT_WINDOW,
+): TokenUsageResult {
   let inputTokens = 0;
   let outputTokens = 0;
   let cacheReadTokens = 0;
   let cacheCreationTokens = 0;
-  const lines = fileContent.trim().split('\n');
 
-  for (let index = lines.length - 1; index >= 0; index -= 1) {
-    try {
-      const entry = JSON.parse(lines[index]) as AnyRecord;
-      const usage = entry.type === 'assistant' ? entry.message?.usage : null;
-      if (!usage) {
-        continue;
-      }
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    // A subagent's turns report the subagent's context window, not this
+    // conversation's; reading one makes the counter drop to the subagent's
+    // number and bounce back on the next main-thread turn.
+    if (entry?.isSidechain === true) {
+      continue;
+    }
 
-      const directInputTokens = readUsageNumber(usage.input_tokens ?? usage.inputTokens);
-      cacheReadTokens = readUsageNumber(
-        usage.cache_read_input_tokens ?? usage.cacheReadInputTokens ?? usage.cacheReadTokens,
-      );
-      cacheCreationTokens = readUsageNumber(
-        usage.cache_creation_input_tokens
-          ?? usage.cacheCreationInputTokens
-          ?? usage.cacheCreationTokens,
-      );
-      inputTokens = directInputTokens + cacheReadTokens + cacheCreationTokens;
-      outputTokens = readUsageNumber(usage.output_tokens ?? usage.outputTokens);
-      break;
-    } catch {
-      // Skip malformed lines without discarding usage from earlier messages.
+    const usage = entry?.type === 'assistant' ? entry.message?.usage : null;
+    if (!usage) {
+      continue;
+    }
+
+    const directInputTokens = readUsageNumber(usage.input_tokens ?? usage.inputTokens);
+    const rowCacheReadTokens = readUsageNumber(
+      usage.cache_read_input_tokens ?? usage.cacheReadInputTokens ?? usage.cacheReadTokens,
+    );
+    const rowCacheCreationTokens = readUsageNumber(
+      usage.cache_creation_input_tokens
+        ?? usage.cacheCreationInputTokens
+        ?? usage.cacheCreationTokens,
+    );
+    const rowInputTokens = directInputTokens + rowCacheReadTokens + rowCacheCreationTokens;
+    const rowOutputTokens = readUsageNumber(usage.output_tokens ?? usage.outputTokens);
+
+    // `<synthetic>` rows — interrupts, API errors, "No response requested" —
+    // are written with an all-zero usage block rather than none at all. They
+    // never carried a prompt, so treating one as the newest turn zeroed a
+    // counter that a live event had just set correctly.
+    if (rowInputTokens === 0 && rowOutputTokens === 0) {
+      continue;
     }
+
+    cacheReadTokens = rowCacheReadTokens;
+    cacheCreationTokens = rowCacheCreationTokens;
+    inputTokens = rowInputTokens;
+    outputTokens = rowOutputTokens;
+    break;
   }
 
   const parsedContextWindow = Number.parseInt(configuredContextWindow ?? '', 10);
@@ -179,6 +260,22 @@ function readClaudeTokenUsage(fileContent: string, configuredContextWindow: stri
   };
 }
 
+function parseClaudeUsageEntries(fileContent: string): AnyRecord[] {
+  const entries: AnyRecord[] = [];
+  for (const line of fileContent.trim().split('\n')) {
+    try {
+      entries.push(JSON.parse(line) as AnyRecord);
+    } catch {
+      // Skip malformed lines without discarding usage from earlier messages.
+    }
+  }
+  return entries;
+}
+
+function claudeEntriesHaveUsage(entries: AnyRecord[]): boolean {
+  return entries.some((entry) => entry?.type === 'assistant' && entry.message?.usage);
+}
+
 function readOpenCodeTokenUsage(databasePath: string, providerSessionId: string): TokenUsageResult {
   const database = new Database(databasePath, { readonly: true, fileMustExist: true });
   try {
@@ -264,6 +361,24 @@ export function createProviderTokenUsageService(
         });
       }
 
+      // The fallback covers rows whose provider id was never recorded, and for
+      // a session discovered from disk the app id *is* its provider id. That
+      // stops being true the moment an edit rewinds the conversation off a
+      // thread: until the replacement run announces its own id, the fallback
+      // would resolve the retired transcript and report the discarded
+      // conversation's usage against an empty one.
+      if (
+        !session.provider_session_id
+        && dependencies.isProviderSessionSuperseded(sessionId, session.provider)
+      ) {
+        return {
+          used: 0,
+          inputTokens: 0,
+          outputTokens: 0,
+          breakdown: { input: 0, output: 0 },
+        };
+      }
+
       const providerSessionId = session.provider_session_id || sessionId;
 
       if (session.provider === 'cursor') {
@@ -307,8 +422,16 @@ export function createProviderTokenUsageService(
           });
         }
 
-        const fileContent = await dependencies.readTextFile(sessionFilePath);
-        return readCodexTokenUsage(fileContent);
+        const tail = await dependencies.readTextFileTail(sessionFilePath, TOKEN_USAGE_TAIL_BYTES);
+        const tailUsage = findCodexTokenUsage(tail.content);
+        if (tailUsage || tail.isComplete) {
+          return tailUsage ?? emptyCodexTokenUsage();
+        }
+
+        // A tail this large with no token_count row is pathological, but the
+        // whole file is still authoritative when it happens.
+        return findCodexTokenUsage(await dependencies.readTextFile(sessionFilePath))
+          ?? emptyCodexTokenUsage();
       }
 
       let sessionFilePath = session.jsonl_path;
@@ -345,8 +468,12 @@ export function createProviderTokenUsageService(
         });
       }
 
-      const fileContent = await dependencies.readTextFile(sessionFilePath);
-      return readClaudeTokenUsage(fileContent, dependencies.getClaudeContextWindow());
+      const tail = await dependencies.readTextFileTail(sessionFilePath, TOKEN_USAGE_TAIL_BYTES);
+      let entries = parseClaudeUsageEntries(tail.content);
+      if (!claudeEntriesHaveUsage(entries) && !tail.isComplete) {
+        entries = parseClaudeUsageEntries(await dependencies.readTextFile(sessionFilePath));
+      }
+      return summarizeClaudeTokenUsage(entries, dependencies.getClaudeContextWindow());
     },
   };
 }

package/server/modules/providers/services/session-conversations-search.service.ts

@@ -5,6 +5,7 @@ import readline from 'node:readline';
 import { spawn } from 'cross-spawn';
 import { rgPath } from '@vscode/ripgrep';
 
+import { stripAnsiSequences } from '@/shared/utils.js';
 import { projectsDb, sessionsDb } from '@/modules/database/index.js';
 
 type AnyRecord = Record<string, any>;
@@ -409,10 +410,6 @@ function buildClaudeLocalCommandDisplayText(payload: ClaudeLocalCommandPayload):
   return commandArgs ? `${baseCommand} ${commandArgs}` : baseCommand;
 }
 
-function stripAnsiFormatting(text: string): string {
-  return text.replace(/\u001B\[[0-9;?]*[ -/]*[@-~]/g, '');
-}
-
 type ClaudeSearchableMessage = {
   text: string;
   role: 'user' | 'assistant';
@@ -456,7 +453,7 @@ function extractClaudeSearchableMessage(entry: AnyRecord): ClaudeSearchableMessa
 
     const localCommandStdout = extractTaggedContent(content, 'local-command-stdout');
     if (localCommandStdout !== null) {
-      const stdoutText = stripAnsiFormatting(localCommandStdout).trim();
+      const stdoutText = stripAnsiSequences(localCommandStdout).trim();
       return stdoutText
         ? {
             text: stdoutText,

package/server/modules/providers/services/session-history-cache.service.ts

@@ -0,0 +1,150 @@
+import fsp from 'node:fs/promises';
+
+import type { FetchHistoryResult } from '@/shared/types.js';
+
+/**
+ * Full-transcript cache for session history reads.
+ *
+ * Every provider history reader materializes the complete normalized
+ * transcript and then slices out the requested page, so serving a 20-row page
+ * of a large session re-read and re-parsed the whole transcript file on every
+ * request — opening a session, each older page while scrolling up, and every
+ * post-turn refresh. For a multi-megabyte JSONL that is most of a second of
+ * CPU per request.
+ *
+ * Entries are keyed by app session id and validated with one `stat` per
+ * request against the transcript file's identity (path + mtime + size), so
+ * only the first read after the file changes pays the parse. Anything that
+ * rewrites history (a new turn, an edit, a rewind, a fork) touches the file
+ * and invalidates naturally.
+ *
+ * One thing the file cannot tell: whether the CLI process behind the session
+ * is still running. Claude's history reader answers a background agent's
+ * status from that, so a session's entry is also dropped explicitly when its
+ * process starts or ends (`invalidate`) — otherwise a page read while the
+ * process was up would keep reporting `running` after it had gone, until the
+ * next row happened to land in the file.
+ *
+ * Only history readers that read `jsonl_path` itself may use this cache —
+ * callers pass `transcriptPath: null` for providers whose messages live
+ * elsewhere (Cursor's store.db, OpenCode's shared SQLite), which bypasses
+ * caching entirely.
+ */
+
+type CacheEntry = {
+  transcriptPath: string;
+  mtimeMs: number;
+  /** File size in bytes; doubles as the entry's cost against the byte budget. */
+  size: number;
+  full: FetchHistoryResult;
+};
+
+type GetFullHistoryArgs = {
+  sessionId: string;
+  /** Path of the file the provider's history reader actually parses, or null to bypass. */
+  transcriptPath: string | null | undefined;
+  /** Loads the complete transcript (`limit: null, offset: 0`) from the provider. */
+  loadFull: () => Promise<FetchHistoryResult>;
+};
+
+/**
+ * A transcript entry's heap cost is roughly the file it was parsed from, so
+ * the budget is expressed in file bytes. The newest entry is always retained
+ * even when it alone exceeds the budget — evicting it would just re-parse the
+ * same file on the next request.
+ */
+const MAX_CACHED_TRANSCRIPT_FILE_BYTES = 256 * 1024 * 1024;
+const MAX_CACHE_ENTRIES = 8;
+
+export function createSessionHistoryCache(
+  maxTotalFileBytes = MAX_CACHED_TRANSCRIPT_FILE_BYTES,
+  maxEntries = MAX_CACHE_ENTRIES,
+) {
+  const entries = new Map<string, CacheEntry>();
+  const pendingLoads = new Map<string, Promise<FetchHistoryResult>>();
+
+  function evictOverBudget(): void {
+    let totalBytes = 0;
+    for (const entry of entries.values()) {
+      totalBytes += entry.size;
+    }
+    for (const key of entries.keys()) {
+      if (entries.size <= 1 || (totalBytes <= maxTotalFileBytes && entries.size <= maxEntries)) {
+        break;
+      }
+      totalBytes -= entries.get(key)!.size;
+      entries.delete(key);
+    }
+  }
+
+  return {
+    /**
+     * Returns the session's full transcript through the cache, or null when
+     * the session is not cacheable (no transcript path, or the file cannot be
+     * stat'ed) — the caller then falls back to a plain provider read.
+     */
+    async getFullHistory({ sessionId, transcriptPath, loadFull }: GetFullHistoryArgs): Promise<FetchHistoryResult | null> {
+      if (!transcriptPath) {
+        return null;
+      }
+
+      let stat;
+      try {
+        stat = await fsp.stat(transcriptPath);
+      } catch {
+        entries.delete(sessionId);
+        return null;
+      }
+      if (!stat.isFile()) {
+        entries.delete(sessionId);
+        return null;
+      }
+
+      const cached = entries.get(sessionId);
+      if (
+        cached
+        && cached.transcriptPath === transcriptPath
+        && cached.mtimeMs === stat.mtimeMs
+        && cached.size === stat.size
+      ) {
+        // Re-insert to mark as most recently used.
+        entries.delete(sessionId);
+        entries.set(sessionId, cached);
+        return cached.full;
+      }
+
+      // Concurrent requests for the same session share one parse. The file may
+      // gain rows while the load runs; the pre-load stat is what the entry is
+      // keyed by, so the next request would see a changed stat and re-read.
+      const pending = pendingLoads.get(sessionId);
+      if (pending) {
+        return pending;
+      }
+
+      const load = loadFull().then((full) => {
+        entries.delete(sessionId);
+        entries.set(sessionId, {
+          transcriptPath,
+          mtimeMs: stat.mtimeMs,
+          size: stat.size,
+          full,
+        });
+        evictOverBudget();
+        return full;
+      });
+      pendingLoads.set(sessionId, load);
+      try {
+        return await load;
+      } finally {
+        pendingLoads.delete(sessionId);
+      }
+    },
+
+    /** Forgets a session's entry so the next read re-parses its transcript. */
+    invalidate(sessionId: string): void {
+      entries.delete(sessionId);
+    },
+  };
+}
+
+export const sessionHistoryCache = createSessionHistoryCache();