spiracha 2.0.0 → 2.2.0

package/src/lib/opencode-think-tags.ts

@@ -27,9 +27,23 @@ const findClosingBackticks = (text: string, start: number, runLength: number): n
 };
 
 const findThinkCloseIndex = (text: string, start: number): number => {
-    THINK_CLOSE_PATTERN.lastIndex = start;
-    const match = THINK_CLOSE_PATTERN.exec(text);
-    return match ? match.index : -1;
+    let cursor = start;
+    while (cursor < text.length) {
+        THINK_CLOSE_PATTERN.lastIndex = cursor;
+        const match = THINK_CLOSE_PATTERN.exec(text);
+        if (!match) {
+            return -1;
+        }
+
+        const backtickIndex = text.indexOf('`', cursor);
+        if (backtickIndex === -1 || backtickIndex >= match.index) {
+            return match.index;
+        }
+
+        cursor = findClosingBackticks(text, backtickIndex, getBacktickRunLength(text, backtickIndex));
+    }
+
+    return -1;
 };
 
 const getLastVisibleChar = (parts: string[]): string => {

package/src/lib/opencode-transcript.ts

@@ -88,10 +88,11 @@ const renderTextPart = (
     options: OpenCodeExportOptions,
     finalAssistantTextPartIds: Set<string>,
 ): string => {
+    const rawText = part.text ?? '';
     const { reasoningBlocks, visibleText } =
         part.role === 'assistant'
-            ? splitOpenCodeThinkTaggedText(part.text ?? '')
-            : { reasoningBlocks: [], visibleText: part.text ?? '' };
+            ? splitOpenCodeThinkTaggedText(rawText)
+            : { reasoningBlocks: [], visibleText: rawText };
     const sections: string[] = [];
 
     if (options.includeCommentary) {
@@ -119,7 +120,8 @@ const renderReasoningPart = (part: OpenCodeTranscriptPart, options: OpenCodeExpo
         return '';
     }
 
-    const { reasoningBlocks, visibleText } = splitOpenCodeThinkTaggedText(part.text ?? '');
+    const rawText = part.text ?? '';
+    const { reasoningBlocks, visibleText } = splitOpenCodeThinkTaggedText(rawText);
     const text = cleanExtractedText([...reasoningBlocks, visibleText].filter(Boolean).join('\n\n')).trim();
     return text ? renderSection('Reasoning', text, options.outputFormat) : '';
 };
@@ -143,8 +145,9 @@ const renderToolPart = (part: OpenCodeTranscriptPart, options: OpenCodeExportOpt
     if (part.argumentsText?.trim()) {
         lines.push('', 'Input:', '', renderCodeBlock(part.argumentsText.trim(), options.outputFormat));
     }
-    if (part.outputText?.trim()) {
-        lines.push('', 'Output:', '', renderCodeBlock(truncateOutput(part.outputText.trim()), options.outputFormat));
+    const outputText = part.outputText ?? '';
+    if (outputText.trim()) {
+        lines.push('', 'Output:', '', renderCodeBlock(truncateOutput(outputText.trim()), options.outputFormat));
     }
 
     return renderSection('Tool Call', lines.join('\n'), options.outputFormat);

package/src/lib/portable-path.ts

@@ -0,0 +1,9 @@
+export const getPortablePathBasename = (value: string): string => {
+    const trimmed = value.replace(/[\\/]+$/u, '');
+    if (!trimmed) {
+        return '';
+    }
+
+    const separatorIndex = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
+    return separatorIndex === -1 ? trimmed : trimmed.slice(separatorIndex + 1);
+};

package/src/lib/qoder-acp-client.ts

@@ -9,6 +9,7 @@ const INITIALIZE_REQUEST_ID = 1;
 const LOAD_REQUEST_ID = 2;
 
 type JsonRpcMessage = {
+    error?: JsonValue;
     id?: number;
     jsonrpc?: '2.0';
     method?: string;
@@ -16,6 +17,14 @@ type JsonRpcMessage = {
     result?: JsonValue;
 };
 
+export const isQoderAcpResponse = (message: JsonRpcMessage, requestId: number) => {
+    return (
+        message.id === requestId &&
+        message.method === undefined &&
+        (Object.hasOwn(message, 'result') || Object.hasOwn(message, 'error'))
+    );
+};
+
 export type QoderAcpSessionUpdate = {
     requestId: string | null;
     sessionId: string;
@@ -207,7 +216,7 @@ export const loadQoderAcpSession = async (
         };
 
         const markLoadCompleted = (message: JsonRpcMessage) => {
-            if (message.id !== LOAD_REQUEST_ID || loadCompleted) {
+            if (!isQoderAcpResponse(message, LOAD_REQUEST_ID) || loadCompleted) {
                 return false;
             }
 
@@ -221,7 +230,7 @@ export const loadQoderAcpSession = async (
         };
 
         const handleMessage = (message: JsonRpcMessage) => {
-            if (message.id === INITIALIZE_REQUEST_ID) {
+            if (isQoderAcpResponse(message, INITIALIZE_REQUEST_ID)) {
                 sendLoadRequest();
                 return;
             }

package/src/lib/qoder-db.ts

@@ -2,6 +2,7 @@ import { Database } from 'bun:sqlite';
 import { readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { mapWithConcurrency } from './concurrency';
+import { getPortablePathBasename } from './portable-path';
 import { loadQoderAcpSession, type QoderAcpSessionUpdate, resolveQoderAcpSocketPath } from './qoder-acp-client';
 import {
     getDefaultQoderUserDir,
@@ -14,16 +15,18 @@ import {
     resolveQoderGlobalStateDb,
     resolveQoderWorkspaceStorageDir,
 } from './qoder-exporter-types';
+import { coalesceQoderMessageChunks } from './qoder-transcript-phase';
 import {
     asObject,
     asString,
     cleanExtractedText,
     cleanInlineTitle,
-    getPortablePathBasename,
     isWorkspacePathQuery,
     type JsonValue,
+    toFileUri,
     workspacePathMatchesQuery,
 } from './shared';
+import { runWithSqliteRetry } from './sqlite-retry';
 
 export {
     getDefaultQoderUserDir,
@@ -202,7 +205,7 @@ const getWorkspaceLabel = (worktree: string): string => {
 };
 
 const getWorkspaceUri = (worktree: string): string => {
-    return worktree.startsWith(path.sep) ? `file://${worktree}` : worktree;
+    return worktree.startsWith(path.sep) ? toFileUri(worktree) : worktree;
 };
 
 const parseJsonValue = (value: string): JsonValue | null => {
@@ -213,23 +216,50 @@ const parseJsonValue = (value: string): JsonValue | null => {
     }
 };
 
+export const isUnavailableQoderGlobalStateError = (error: unknown): boolean => {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+
+    const code = 'code' in error && typeof error.code === 'string' ? error.code : '';
+    return (
+        code === 'SQLITE_CANTOPEN' ||
+        code === 'SQLITE_IOERR_READ' ||
+        /^(?:SQLite operation failed after \d+ attempts?:\s*)?(?:SQLITE_CANTOPEN:.*|unable to open database file)$/iu.test(
+            error.message,
+        )
+    );
+};
+
 const readGlobalRows = async (globalStateDb = resolveQoderGlobalStateDb()): Promise<ItemTableRow[]> => {
-    if (!(await pathExists(globalStateDb))) {
+    const isDatabaseFile = await stat(globalStateDb)
+        .then((metadata) => metadata.isFile())
+        .catch(() => false);
+    if (!isDatabaseFile) {
         return [];
     }
 
-    let db: Database | null = null;
     try {
-        db = new Database(globalStateDb, { readonly: true, strict: true });
-        return db
-            .query(
-                "select key, value from ItemTable where key like 'lingma.chat.localHistory.%.quest' or key = 'aicoding.questTaskListSnapshot' or key in ('aicoding.modelConfigs.cache.assistant', 'aicoding.modelConfigs.cache.quest')",
-            )
-            .all() as ItemTableRow[];
-    } catch {
-        return [];
-    } finally {
-        db?.close();
+        return runWithSqliteRetry({
+            action: () => {
+                const db = new Database(globalStateDb, { readonly: true, strict: true });
+                try {
+                    db.exec('PRAGMA busy_timeout = 1000');
+                    return db
+                        .query(
+                            "select key, value from ItemTable where key like 'lingma.chat.localHistory.%.quest' or key = 'aicoding.questTaskListSnapshot' or key in ('aicoding.modelConfigs.cache.assistant', 'aicoding.modelConfigs.cache.quest')",
+                        )
+                        .all() as ItemTableRow[];
+                } finally {
+                    db.close();
+                }
+            },
+        });
+    } catch (error) {
+        if (isUnavailableQoderGlobalStateError(error)) {
+            return [];
+        }
+        throw error;
     }
 };
 
@@ -800,6 +830,7 @@ const readRecordSummary = async (
     modelFallback: string | null,
 ): Promise<QoderSessionSummary> => {
     const state = await readStateData(workspaceStorageDir, workspaceStorageIds, record);
+    // List stats describe persisted Qoder state only; detail reads may additionally hydrate CLI or live ACP messages.
     const entries = buildLocalTranscriptEntries(record, state);
     const stats = createStatsFromEntries(entries, state.snapshotFileCount);
     return toSessionSummary(record, state, stats, modelFallback);
@@ -1128,6 +1159,7 @@ const cliToolCallPartToTranscriptPart = (part: Record<string, JsonValue>): Qoder
               raw: {
                   ...part,
                   command: text,
+                  toolCallId: asString(data.id ?? data.tool_use_id ?? part.id ?? part.tool_use_id ?? null),
                   toolName: getCliToolName(part, data),
               },
               role: 'tool',
@@ -1494,9 +1526,11 @@ const readAcpTranscriptEntries = async (
     }
 
     return {
-        entries: loaded.events
-            .map((event, index) => acpUpdateToEntry(event, index))
-            .filter((entry): entry is QoderTranscriptEntry => Boolean(entry)),
+        entries: coalesceQoderMessageChunks(
+            loaded.events
+                .map((event, index) => acpUpdateToEntry(event, index))
+                .filter((entry): entry is QoderTranscriptEntry => Boolean(entry)),
+        ),
         model: getAcpModel(loaded.events),
         socketPath: loaded.socketPath,
     };

package/src/lib/qoder-transcript-phase.ts

@@ -2,6 +2,59 @@ import type { QoderTranscriptEntry } from './qoder-exporter-types';
 
 export type QoderMessagePhase = 'commentary' | 'final_answer' | null;
 
+const getMessageChunkType = (entry: QoderTranscriptEntry): string | null => {
+    if (entry.entryType !== 'message' || (entry.role !== 'assistant' && entry.role !== 'user')) {
+        return null;
+    }
+
+    const sessionUpdate = entry.parts[0]?.raw.sessionUpdate;
+    return typeof sessionUpdate === 'string' && sessionUpdate.endsWith('_message_chunk') ? sessionUpdate : null;
+};
+
+const mergeMessageChunks = (first: QoderTranscriptEntry, second: QoderTranscriptEntry): QoderTranscriptEntry => {
+    const firstPart = first.parts[0]!;
+    const secondPart = second.parts[0]!;
+    return {
+        ...first,
+        parts: [
+            {
+                ...firstPart,
+                raw: {
+                    ...firstPart.raw,
+                    coalescedChunkCount:
+                        (typeof firstPart.raw.coalescedChunkCount === 'number'
+                            ? firstPart.raw.coalescedChunkCount
+                            : 1) + 1,
+                },
+                text: `${firstPart.text ?? ''}${secondPart.text ?? ''}`,
+            },
+        ],
+        raw: second.raw,
+        timestamp: second.timestamp ?? first.timestamp,
+    };
+};
+
+export const coalesceQoderMessageChunks = (entries: QoderTranscriptEntry[]): QoderTranscriptEntry[] => {
+    const coalesced: QoderTranscriptEntry[] = [];
+    for (const entry of entries) {
+        const previous = coalesced.at(-1);
+        const chunkType = getMessageChunkType(entry);
+        if (
+            previous &&
+            chunkType &&
+            chunkType === getMessageChunkType(previous) &&
+            previous.requestId === entry.requestId &&
+            previous.parts.length === 1 &&
+            entry.parts.length === 1
+        ) {
+            coalesced[coalesced.length - 1] = mergeMessageChunks(previous, entry);
+        } else {
+            coalesced.push(entry);
+        }
+    }
+    return coalesced;
+};
+
 export const getFinalQoderAssistantMessageEntryIds = (entries: QoderTranscriptEntry[]): Set<string> => {
     const finalEntryIds = new Set<string>();
     let latestAssistantMessageEntryId: string | null = null;
@@ -37,5 +90,16 @@ export const getQoderMessagePhase = (entry: QoderTranscriptEntry, finalAssistant
         return null;
     }
 
+    const isExplicitReasoning = entry.parts.some((part) => {
+        return (
+            part.raw.sourceType === 'reasoning' ||
+            part.raw.sourceType === 'thinking' ||
+            part.raw.sessionUpdate === 'agent_thought_chunk'
+        );
+    });
+    if (isExplicitReasoning) {
+        return 'commentary';
+    }
+
     return finalAssistantMessageEntryIds.has(entry.entryId) ? 'final_answer' : 'commentary';
 };

package/src/lib/qoder-transcript.ts

@@ -9,6 +9,7 @@ import { getFinalQoderAssistantMessageEntryIds, getQoderMessagePhase } from './q
 import {
     cleanExtractedText,
     cleanInlineTitle,
+    formatInlineLiteral,
     type MetadataEntry,
     renderDocumentTitle,
     renderMetadataBlock,
@@ -61,6 +62,33 @@ const renderTextPart = (part: QoderTranscriptPart, title: string, options: Qoder
     return text ? renderSection(title, text, options.outputFormat) : '';
 };
 
+const getPartString = (part: QoderTranscriptPart, key: string): string | null => {
+    const value = part.raw[key];
+    return typeof value === 'string' && value.trim() ? value : null;
+};
+
+const renderToolPart = (part: QoderTranscriptPart, title: string, options: QoderExportOptions): string => {
+    const text = cleanExtractedText(part.text ?? '').trim();
+    if (!text) {
+        return '';
+    }
+
+    const lines: string[] = [];
+    const toolName = getPartString(part, 'toolName');
+    const toolCallId = getPartString(part, 'toolCallId');
+    if (toolName) {
+        lines.push(`Tool: ${formatInlineLiteral(toolName, options.outputFormat)}`);
+    }
+    if (toolCallId) {
+        lines.push(`Call ID: ${toolCallId}`);
+    }
+    if (lines.length > 0) {
+        lines.push('');
+    }
+    lines.push(text);
+    return renderSection(title, lines.join('\n'), options.outputFormat);
+};
+
 const renderPart = (
     entry: QoderTranscriptEntry,
     part: QoderTranscriptPart,
@@ -68,11 +96,11 @@ const renderPart = (
     finalAssistantMessageEntryIds: Set<string>,
 ): string => {
     if (entry.entryType === 'tool_call') {
-        return options.includeTools && part.type === 'text' ? renderTextPart(part, 'Tool call', options) : '';
+        return options.includeTools && part.type === 'text' ? renderToolPart(part, 'Tool call', options) : '';
     }
 
     if (entry.entryType === 'tool_output') {
-        return options.includeTools && part.type === 'text' ? renderTextPart(part, 'Tool output', options) : '';
+        return options.includeTools && part.type === 'text' ? renderToolPart(part, 'Tool output', options) : '';
     }
 
     if (getQoderMessagePhase(entry, finalAssistantMessageEntryIds) === 'commentary' && !options.includeCommentary) {

package/src/lib/shared.ts

@@ -1,9 +1,10 @@
 import { createReadStream, createWriteStream } from 'node:fs';
-import { mkdir } from 'node:fs/promises';
+import { mkdir, readdir, stat } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { finished } from 'node:stream/promises';
+import { pathToFileURL } from 'node:url';
 import { formatModelLabel as formatSharedModelLabel } from './model-label';
 
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
@@ -17,6 +18,19 @@ export type MetadataEntry = {
 
 export class CliUsageError extends Error {}
 
+export const readDirectoryEntriesIfExists = async (directoryPath: string) => {
+    try {
+        return await readdir(directoryPath, { withFileTypes: true });
+    } catch (error) {
+        if ((error as { code?: unknown }).code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+};
+
+export const toFileUri = (filePath: string): string => pathToFileURL(filePath).href;
+
 export const expandHome = (value: string): string => {
     if (!value) {
         return value;
@@ -26,20 +40,26 @@ export const expandHome = (value: string): string => {
         return os.homedir();
     }
 
-    if (value.startsWith('~/')) {
-        return path.join(os.homedir(), value.slice(2));
+    if (value.startsWith('~/') || value.startsWith('~\\')) {
+        return path.join(
+            os.homedir(),
+            ...value
+                .slice(2)
+                .split(/[\\/]+/u)
+                .filter(Boolean),
+        );
     }
 
     return value;
 };
 
-export const getPortablePathBasename = (value: string): string => {
-    const trimmed = value.replace(/[\\/]+$/u, '');
-    if (!trimmed) {
-        return '';
+export const pathExists = async (target: string): Promise<boolean> => {
+    try {
+        await stat(target);
+        return true;
+    } catch {
+        return false;
     }
-
-    return path.win32.basename(path.posix.basename(trimmed));
 };
 
 export const isWorkspacePathQuery = (value: string): boolean => {
@@ -86,6 +106,18 @@ export const cleanExtractedText = (text: string): string => {
     return text.replace(/^\s*<\/?image>\s*$/gm, '').replace(/\n{3,}/g, '\n\n');
 };
 
+const CODEX_APP_DIRECTIVE_PATTERN =
+    /^::(?:code-comment|created-thread|git-commit|git-create-branch|git-create-pr|git-push|git-stage)\{.*\}\s*$/u;
+
+export const stripCodexAppDirectiveLines = (text: string): string => {
+    return text
+        .split('\n')
+        .filter((line) => !CODEX_APP_DIRECTIVE_PATTERN.test(line.trim()))
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+};
+
 export const formatModelLabel = formatSharedModelLabel;
 
 export const asObject = (value: JsonValue): Record<string, JsonValue> | null => {
@@ -116,6 +148,7 @@ export const readJsonlObjects = (filePath: string): AsyncIterableIterator<Record
     });
     const lineIterator = lines[Symbol.asyncIterator]();
     let closed = false;
+    let lineNumber = 0;
 
     const close = () => {
         if (closed) {
@@ -135,17 +168,27 @@ export const readJsonlObjects = (filePath: string): AsyncIterableIterator<Record
                 return { done: true, value: undefined as never };
             }
 
+            lineNumber += 1;
             const trimmed = nextLine.value.trim();
             if (!trimmed) {
                 continue;
             }
 
             try {
+                const parsed = JSON.parse(trimmed) as JsonValue;
+                const object = asObject(parsed);
+                if (!object) {
+                    console.warn('[spiracha:jsonl] invalid_json_line', { filePath, lineNumber });
+                    continue;
+                }
+
                 return {
                     done: false,
-                    value: JSON.parse(trimmed) as Record<string, JsonValue>,
+                    value: object,
                 };
-            } catch {}
+            } catch {
+                console.warn('[spiracha:jsonl] invalid_json_line', { filePath, lineNumber });
+            }
         }
     };
 
@@ -213,7 +256,8 @@ export const renderSection = (title: string, body: string, format: ExportFormat)
 
 export const renderCodeBlock = (text: string, format: ExportFormat): string => {
     if (format === 'md') {
-        return `\`\`\`text\n${text}\n\`\`\``;
+        const fence = getBacktickFence(text, 3);
+        return `${fence}text\n${text}\n${fence}`;
     }
 
     return text;
@@ -223,10 +267,14 @@ export const formatInlineLiteral = (value: string, format: ExportFormat): string
     return format === 'md' ? inlineCode(value) : value;
 };
 
-export const inlineCode = (value: string): string => {
-    const backtickRuns = value.match(/`+/g) ?? [];
+const getBacktickFence = (value: string, minimumLength: number): string => {
+    const backtickRuns = value.match(/`+/gu) ?? [];
     const maxRunLength = backtickRuns.reduce((max, run) => Math.max(max, run.length), 0);
-    const fence = '`'.repeat(maxRunLength + 1);
+    return '`'.repeat(Math.max(minimumLength, maxRunLength + 1));
+};
+
+export const inlineCode = (value: string): string => {
+    const fence = getBacktickFence(value, 1);
     const padded = value.startsWith('`') || value.endsWith('`') ? ` ${value} ` : value;
     return `${fence}${padded}${fence}`;
 };

package/src/lib/sqlite-error.ts

@@ -1,14 +1,40 @@
+const SQLITE_RETRYABLE_CODES = new Set(['SQLITE_BUSY', 'SQLITE_BUSY_SNAPSHOT', 'SQLITE_CANTOPEN', 'SQLITE_LOCKED']);
+const SQLITE_OPERATION_PREFIX = String.raw`(?:SQLite operation failed after \d+ attempts?:\s*)?`;
 const SQLITE_RETRYABLE_PATTERNS = [
-    /unable to open database file/iu,
-    /database is locked/iu,
-    /SQLITE_BUSY/iu,
-    /SQLITE_CANTOPEN/iu,
+    new RegExp(`^${SQLITE_OPERATION_PREFIX}unable to open database(?: file)?(?:$|:)`, 'iu'),
+    new RegExp(`^${SQLITE_OPERATION_PREFIX}database(?: table)? is locked(?:$|:)`, 'iu'),
+    /^SQLITE_(?:BUSY|CANTOPEN|LOCKED)(?:_[A-Z_]+)?(?:$|:)/u,
 ];
+const SQLITE_DATABASE_PATTERNS = [
+    ...SQLITE_RETRYABLE_PATTERNS,
+    /^SQLITE_[A-Z_]+(?:$|:)/u,
+    new RegExp(
+        `^${SQLITE_OPERATION_PREFIX}(?:attempt to write a readonly database|database disk image is malformed|disk I/O error)(?:$|:)`,
+        'iu',
+    ),
+];
+
+const getSqliteCode = (error: Error): string | null => {
+    const code = 'code' in error ? error.code : null;
+    return typeof code === 'string' && code.startsWith('SQLITE_') ? code.toUpperCase() : null;
+};
 
 export const isRetryableSqliteError = (error: unknown) => {
     if (!(error instanceof Error)) {
         return false;
     }
 
-    return SQLITE_RETRYABLE_PATTERNS.some((pattern) => pattern.test(error.message));
+    const code = getSqliteCode(error);
+    return (
+        Boolean(code && SQLITE_RETRYABLE_CODES.has(code)) ||
+        SQLITE_RETRYABLE_PATTERNS.some((pattern) => pattern.test(error.message))
+    );
+};
+
+export const isSqliteDatabaseError = (error: unknown): boolean => {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+
+    return getSqliteCode(error) !== null || SQLITE_DATABASE_PATTERNS.some((pattern) => pattern.test(error.message));
 };

package/src/lib/transcript-load-limiter.ts

@@ -0,0 +1,87 @@
+import { createConcurrencyLimiter } from './concurrency';
+
+const DEFAULT_TRANSCRIPT_LOAD_CONCURRENCY = 3;
+const MAX_TRANSCRIPT_LOAD_CONCURRENCY = 16;
+type TranscriptLoadLogContext = {
+    id?: string;
+    path?: string;
+    source?: string;
+};
+
+let nextTranscriptLoadId = 1;
+let activeTranscriptLoads = 0;
+let queuedTranscriptLoads = 0;
+
+export const resolveTranscriptLoadConcurrency = (value = process.env.SPIRACHA_TRANSCRIPT_LOAD_CONCURRENCY): number => {
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0
+        ? Math.min(parsed, MAX_TRANSCRIPT_LOAD_CONCURRENCY)
+        : DEFAULT_TRANSCRIPT_LOAD_CONCURRENCY;
+};
+
+let transcriptLoadLimiter: ReturnType<typeof createConcurrencyLimiter> | null = null;
+
+const getTranscriptLoadLimiter = () => {
+    transcriptLoadLimiter ??= createConcurrencyLimiter(resolveTranscriptLoadConcurrency());
+    return transcriptLoadLimiter;
+};
+
+const shouldLogTranscriptLoads = () => process.env.SPIRACHA_TRANSCRIPT_LOAD_LOGS === '1';
+
+const logTranscriptLoad = (event: string, details: Record<string, unknown>) => {
+    if (shouldLogTranscriptLoads()) {
+        console.info(`[spiracha:transcript-load] ${event}`, details);
+    }
+};
+
+export const runWithTranscriptLoadLimit = async <T>(
+    loader: () => Promise<T>,
+    context: TranscriptLoadLogContext = {},
+): Promise<T> => {
+    const loadId = nextTranscriptLoadId;
+    nextTranscriptLoadId += 1;
+    queuedTranscriptLoads += 1;
+    const queuedAt = Date.now();
+
+    return getTranscriptLoadLimiter()(async () => {
+        queuedTranscriptLoads -= 1;
+        activeTranscriptLoads += 1;
+        const startedAt = Date.now();
+        logTranscriptLoad('start', {
+            active: activeTranscriptLoads,
+            id: context.id,
+            loadId,
+            path: context.path,
+            queued: queuedTranscriptLoads,
+            source: context.source,
+            waitMs: startedAt - queuedAt,
+        });
+
+        try {
+            return await loader();
+        } catch (error) {
+            logTranscriptLoad('error', {
+                active: activeTranscriptLoads,
+                durationMs: Date.now() - startedAt,
+                error: error instanceof Error ? error.message : String(error),
+                id: context.id,
+                loadId,
+                path: context.path,
+                queued: queuedTranscriptLoads,
+                source: context.source,
+            });
+            throw error;
+        } finally {
+            activeTranscriptLoads -= 1;
+            logTranscriptLoad('finish', {
+                active: activeTranscriptLoads,
+                durationMs: Date.now() - startedAt,
+                id: context.id,
+                loadId,
+                path: context.path,
+                queued: queuedTranscriptLoads,
+                source: context.source,
+            });
+        }
+    });
+};