maka-agent 0.2.0-dev.31.20260913 → 0.2.0-dev.32.20260914

package/node_modules/@maka/storage/dist/claude-code-session-adapter.js

@@ -29,17 +29,21 @@
 // between `/Users/a/b` and `/Users/a-b`. Every record carries its own `cwd`,
 // and that is what a project-scoped query reads.
 import { existsSync } from 'node:fs';
-import { readFile, readdir, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { open, readdir, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { claudeAssistantText, claudeUserAuthoredText, isSyntheticClaudeUserText, pickClaudeTitle, sanitizeForeignTitle, } from '@maka/core/foreign-session';
-import { externalSessionMatchesQuery } from '@maka/core/external-session';
-import { resolveTranscriptLineage, } from './claude-code-transcript-lineage.js';
+import { claudeAssistantText, claudeUserAuthoredText, collectClaudeTitle, isSyntheticClaudeUserText, pickClaudeTitle, sanitizeForeignTitle, } from '@maka/core/foreign-session';
+import { ExternalSessionLimitError, externalSessionMatchesQuery, } from '@maka/core/external-session';
+import { TranscriptLineageIndexer, } from './claude-code-transcript-lineage.js';
 export const CLAUDE_CODE_SESSION_ADAPTER_ID = 'claude-code';
-/** A transcript larger than this is not read. Bounded for the same reason the
- *  Codex rollout cap exists: a single hostile or runaway file must not be able
- *  to exhaust the Host's memory during an import the user asked for. */
-export const CLAUDE_TRANSCRIPT_MAX_BYTES = 64 * 1024 * 1024;
+/** Maximum source bytes scanned from one fixed transcript snapshot. */
+export const CLAUDE_TRANSCRIPT_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+const CLAUDE_TRANSCRIPT_READ_BYTES = 64 * 1024;
+const CLAUDE_TRANSCRIPT_MAX_RECORD_BYTES = 64 * 1024 * 1024;
+const CLAUDE_TRANSCRIPT_MAX_CONVERTED_BYTES = 256 * 1024 * 1024;
+const CLAUDE_TRANSCRIPT_MAX_MESSAGES = 250_000;
+const CLAUDE_TRANSCRIPT_MAX_RECORDS = 1_000_000;
 /** Session ids are the transcript's filename stem, and reach the filesystem.
  *  A uuid is what Claude Code writes; anything else is refused rather than
  *  joined onto a path. */
@@ -47,7 +51,7 @@ const SESSION_ID_PATTERN = /^[0-9a-fA-F-]{1,128}$/u;
 export class ClaudeCodeSessionAdapter {
     id = CLAUDE_CODE_SESSION_ADAPTER_ID;
     #home;
-    #maxBytes;
+    #limits;
     /**
      * Summaries already derived from a transcript, keyed by path and invalidated
      * by the file's own mtime and size.
@@ -64,7 +68,18 @@ export class ClaudeCodeSessionAdapter {
     #summaries = new Map();
     constructor(options = {}) {
         this.#home = options.claudeHome ?? join(homedir(), '.claude');
-        this.#maxBytes = options.maxTranscriptBytes ?? CLAUDE_TRANSCRIPT_MAX_BYTES;
+        this.#limits = {
+            maxTranscriptBytes: options.maxTranscriptBytes ?? CLAUDE_TRANSCRIPT_MAX_BYTES,
+            maxRecordBytes: options.maxRecordBytes ?? CLAUDE_TRANSCRIPT_MAX_RECORD_BYTES,
+            maxConvertedBytes: options.maxConvertedBytes ?? CLAUDE_TRANSCRIPT_MAX_CONVERTED_BYTES,
+            maxMessages: options.maxMessages ?? CLAUDE_TRANSCRIPT_MAX_MESSAGES,
+            maxRecords: options.maxRecords ?? CLAUDE_TRANSCRIPT_MAX_RECORDS,
+        };
+        assertPositiveSafeInteger(this.#limits.maxTranscriptBytes, 'Claude transcript byte limit');
+        assertPositiveSafeInteger(this.#limits.maxRecordBytes, 'Claude transcript record byte limit');
+        assertPositiveSafeInteger(this.#limits.maxConvertedBytes, 'Claude converted message byte limit');
+        assertPositiveSafeInteger(this.#limits.maxMessages, 'Claude converted message count limit');
+        assertPositiveSafeInteger(this.#limits.maxRecords, 'Claude transcript record count limit');
     }
     async detect() {
         return existsSync(this.#projectsRoot());
@@ -114,7 +129,7 @@ export class ClaudeCodeSessionAdapter {
         const cached = this.#summaries.get(path);
         if (cached && cached.mtimeMs === mtimeMs && cached.size === size)
             return cached.summary;
-        const parsed = await this.#parse(path, sessionId);
+        const parsed = await readTranscriptSummary(path);
         // Sub-agent transcripts are whole files, never records interleaved into a
         // parent — so exclusion is per file. Importing one would present a
         // fragment of a conversation as a conversation.
@@ -135,17 +150,7 @@ export class ClaudeCodeSessionAdapter {
         const file = (await this.#transcriptFiles()).find((candidate) => candidate.sessionId === sessionId);
         if (!file)
             throw new Error(`Claude Code transcript not found: ${sessionId}`);
-        const parsed = await this.#parse(file.path, sessionId);
-        if (!parsed)
-            throw new Error(`Claude Code transcript could not be read: ${sessionId}`);
-        if (parsed.isSidechain) {
-            throw new Error(`Claude Code transcript is a sub-agent sidechain: ${sessionId}`);
-        }
-        return {
-            sourceSessionId: sessionId,
-            metadata: { name: parsed.title || sessionId, cwd: parsed.cwd },
-            messages: convertTranscript(sessionId, parsed.records),
-        };
+        return convertClaudeTranscript(file.path, sessionId, this.#limits);
     }
     #projectsRoot() {
         return join(this.#home, 'projects');
@@ -206,66 +211,233 @@ export class ClaudeCodeSessionAdapter {
         }
         return [...bySessionId.values()].map(({ path, sessionId }) => ({ path, sessionId }));
     }
-    async #parse(path, sessionId) {
-        try {
-            const info = await stat(path);
-            if (info.size > this.#maxBytes)
-                return undefined;
+}
+async function convertClaudeTranscript(path, sessionId, limits) {
+    const snapshot = await ClaudeTranscriptSnapshot.open(path, sessionId, limits.maxTranscriptBytes);
+    try {
+        const indexer = new TranscriptLineageIndexer();
+        let cwd = '';
+        let isSidechain = false;
+        const titles = {};
+        let records = 0;
+        for await (const record of snapshot.records(sessionId, limits)) {
+            records += 1;
+            indexer.accept(record);
+            if (record.isSidechain === true)
+                isSidechain = true;
+            if (!cwd && typeof record.cwd === 'string' && record.cwd)
+                cwd = record.cwd;
+            collectClaudeTitle(record, titles);
+            collectLegacyClaudeTitle(record, titles);
         }
-        catch {
-            return undefined;
+        if (records === 0)
+            throw new Error(`Claude Code transcript could not be read: ${sessionId}`);
+        if (isSidechain) {
+            throw new Error(`Claude Code transcript is a sub-agent sidechain: ${sessionId}`);
+        }
+        const lineage = indexer.finish();
+        const fragmentFilter = lineage.createFilter();
+        const responseCollector = new ClaudeResponseCollector(limits.maxConvertedBytes);
+        for await (const record of snapshot.records(sessionId, limits)) {
+            if (!fragmentFilter.keep(record) || record.type !== 'assistant')
+                continue;
+            responseCollector.accept(record);
         }
-        let raw;
+        const converter = new ClaudeTranscriptConverter(sessionId, responseCollector.responses, limits);
+        const conversionFilter = lineage.createFilter();
+        for await (const record of snapshot.records(sessionId, limits)) {
+            if (conversionFilter.keep(record))
+                converter.accept(record);
+        }
+        return {
+            sourceSessionId: sessionId,
+            metadata: { name: pickClaudeTitle(titles) || sessionId, cwd },
+            messages: converter.finish(),
+        };
+    }
+    finally {
+        await snapshot.close();
+    }
+}
+/**
+ * One open file descriptor and one byte length define the import snapshot.
+ * Appends are ignored, path replacement cannot redirect later passes, and a
+ * digest check rejects in-place rewrites that would otherwise mix records
+ * from different points in time.
+ */
+class ClaudeTranscriptSnapshot {
+    #handle;
+    #size;
+    #digest;
+    constructor(handle, size) {
+        this.#handle = handle;
+        this.#size = size;
+    }
+    static async open(path, sessionId, maxBytes) {
+        const handle = await open(path, 'r');
         try {
-            raw = await readFile(path, 'utf8');
+            const metadata = await handle.stat();
+            if (!metadata.isFile())
+                throw new Error('Claude Code transcript is not a regular file');
+            if (metadata.size > maxBytes) {
+                throw new ExternalSessionLimitError('transcript_bytes', maxBytes, `Claude Code transcript exceeds ${maxBytes} bytes: ${sessionId}`);
+            }
+            return new ClaudeTranscriptSnapshot(handle, metadata.size);
         }
-        catch {
-            return undefined;
+        catch (error) {
+            await handle.close();
+            throw error;
         }
-        const records = [];
-        let cwd = '';
-        let isSidechain = false;
-        let createdAt;
-        let updatedAt;
-        const titles = {};
-        for (const line of raw.split('\n')) {
-            const trimmed = line.trim();
-            if (!trimmed)
-                continue;
-            let record;
-            try {
-                record = JSON.parse(trimmed);
+    }
+    async *records(sessionId, limits) {
+        const digest = createHash('sha256');
+        yield* readClaudeTranscriptRecords(this.#handle, this.#size, sessionId, limits, (chunk) => digest.update(chunk));
+        this.#verifyDigest(digest.digest('hex'));
+    }
+    async close() {
+        await this.#handle.close();
+    }
+    #verifyDigest(digest) {
+        if (this.#digest === undefined) {
+            this.#digest = digest;
+            return;
+        }
+        if (this.#digest !== digest) {
+            throw new Error('Claude Code transcript changed while being read');
+        }
+    }
+}
+async function* readClaudeTranscriptRecords(handle, snapshotBytes, sessionId, limits, observeChunk) {
+    const metadata = await handle.stat();
+    if (!metadata.isFile())
+        throw new Error('Claude Code transcript is not a regular file');
+    if (metadata.size < snapshotBytes) {
+        throw new Error('Claude Code transcript changed while being read');
+    }
+    const pending = [];
+    let pendingBytes = 0;
+    let observedBytes = 0;
+    let parsedRecords = 0;
+    if (snapshotBytes > 0) {
+        for await (const value of handle.createReadStream({
+            autoClose: false,
+            emitClose: false,
+            start: 0,
+            end: snapshotBytes - 1,
+            highWaterMark: CLAUDE_TRANSCRIPT_READ_BYTES,
+        })) {
+            const chunk = Buffer.from(value);
+            observeChunk?.(chunk);
+            observedBytes += chunk.byteLength;
+            if (observedBytes > snapshotBytes) {
+                throw new Error('Claude Code transcript changed while being read');
             }
-            catch {
-                // A torn final line is what an interrupted write leaves behind, and a
-                // corrupt interior line is not worth failing an otherwise readable
-                // transcript over. Skipping is what the scanner already does.
-                continue;
+            let start = 0;
+            for (;;) {
+                const newline = chunk.indexOf(0x0a, start);
+                if (newline === -1)
+                    break;
+                const segment = chunk.subarray(start, newline);
+                assertClaudeRecordSize(pendingBytes + segment.byteLength, limits.maxRecordBytes, sessionId);
+                const bytes = pending.length === 0
+                    ? segment
+                    : Buffer.concat([...pending, segment], pendingBytes + segment.byteLength);
+                const record = parseClaudeTranscriptLine(bytes);
+                if (record) {
+                    parsedRecords += 1;
+                    assertClaudeRecordCount(parsedRecords, limits.maxRecords, sessionId);
+                    yield record;
+                }
+                pending.length = 0;
+                pendingBytes = 0;
+                start = newline + 1;
             }
-            if (typeof record !== 'object' || record === null || Array.isArray(record))
-                continue;
-            const typed = record;
-            records.push(typed);
-            if (typed.isSidechain === true)
+            if (start < chunk.byteLength) {
+                const segment = chunk.subarray(start);
+                assertClaudeRecordSize(pendingBytes + segment.byteLength, limits.maxRecordBytes, sessionId);
+                pending.push(segment);
+                pendingBytes += segment.byteLength;
+            }
+        }
+    }
+    if (observedBytes !== snapshotBytes) {
+        throw new Error('Claude Code transcript changed while being read');
+    }
+    if (pendingBytes > 0) {
+        const record = parseClaudeTranscriptLine(pending.length === 1 ? pending[0] : Buffer.concat(pending, pendingBytes));
+        if (record) {
+            parsedRecords += 1;
+            assertClaudeRecordCount(parsedRecords, limits.maxRecords, sessionId);
+            yield record;
+        }
+    }
+}
+function assertClaudeRecordSize(actualBytes, maxBytes, sessionId) {
+    if (actualBytes > maxBytes) {
+        throw new ClaudeTranscriptReadLimitError('record_bytes', maxBytes, `Claude Code transcript record exceeds ${maxBytes} bytes: ${sessionId}`);
+    }
+}
+function assertClaudeRecordCount(actual, maxRecords, sessionId) {
+    if (actual > maxRecords) {
+        throw new ClaudeTranscriptReadLimitError('records', maxRecords, `Claude Code transcript has more than ${maxRecords} records: ${sessionId}`);
+    }
+}
+class ClaudeTranscriptReadLimitError extends ExternalSessionLimitError {
+}
+function parseClaudeTranscriptLine(bytes) {
+    const text = bytes.toString('utf8').trim();
+    if (!text)
+        return undefined;
+    try {
+        const value = JSON.parse(text);
+        return typeof value === 'object' && value !== null && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        // Interrupted writes leave a torn tail, while old transcripts can contain
+        // corrupt interior lines. Both were historically skipped so one bad line
+        // does not erase an otherwise readable conversation.
+        return undefined;
+    }
+}
+async function readTranscriptSummary(path) {
+    const handle = await open(path, 'r').catch(() => undefined);
+    if (!handle)
+        return undefined;
+    const titles = {};
+    let cwd = '';
+    let isSidechain = false;
+    let createdAt;
+    let updatedAt;
+    let records = 0;
+    let mtimeMs;
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            return undefined;
+        mtimeMs = info.mtimeMs;
+        for await (const record of readClaudeTranscriptRecords(handle, info.size, path, {
+            maxRecordBytes: CLAUDE_TRANSCRIPT_MAX_RECORD_BYTES,
+            maxRecords: CLAUDE_TRANSCRIPT_MAX_RECORDS,
+        })) {
+            records += 1;
+            collectClaudeTitle(record, titles);
+            collectLegacyClaudeTitle(record, titles);
+            if (record.isSidechain === true)
                 isSidechain = true;
-            if (typeof typed.cwd === 'string' && typed.cwd && !cwd)
-                cwd = typed.cwd;
-            const ts = timestampMs(typed);
+            if (!cwd && typeof record.cwd === 'string' && record.cwd)
+                cwd = record.cwd;
+            const ts = timestampMs(record);
             if (ts !== undefined) {
                 createdAt ??= ts;
-                updatedAt = ts;
-            }
-            collectTitle(typed, titles);
-            if (titles.firstUserMessage === undefined && typed.type === 'user') {
-                const text = claudeUserAuthoredText(typed);
-                if (text)
-                    titles.firstUserMessage = text;
+                if (updatedAt === undefined || ts > updatedAt)
+                    updatedAt = ts;
             }
         }
-        if (records.length === 0)
+        if (records === 0)
             return undefined;
         return {
-            records,
             cwd,
             title: pickClaudeTitle(titles),
             ...(createdAt !== undefined ? { createdAt } : {}),
@@ -273,26 +445,43 @@ export class ClaudeCodeSessionAdapter {
             isSidechain,
         };
     }
+    catch (error) {
+        if (error instanceof ClaudeTranscriptReadLimitError && mtimeMs !== undefined) {
+            // Import keeps strict per-record and record-count bounds, but reaching
+            // one of them must not erase a real transcript from the catalog. Retain
+            // any metadata already observed and use the file mtime for a stable,
+            // sortable fallback row; selecting it then surfaces the precise limit.
+            return {
+                cwd,
+                title: pickClaudeTitle(titles),
+                ...(createdAt !== undefined ? { createdAt } : {}),
+                updatedAt: mtimeMs,
+                isSidechain,
+            };
+        }
+        return undefined;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function collectLegacyClaudeTitle(record, titles) {
+    const take = (value) => typeof value === 'string' && value.trim() ? sanitizeForeignTitle(value) : undefined;
+    if (record.type === 'ai-title') {
+        titles.aiTitle = take(record.aiTitle ?? record.title) ?? titles.aiTitle;
+    }
+    else if (record.type === 'last-prompt') {
+        titles.lastPrompt = take(record.lastPrompt ?? record.prompt) ?? titles.lastPrompt;
+    }
 }
 function assertSafeSessionId(sessionId) {
     if (!SESSION_ID_PATTERN.test(sessionId)) {
         throw new Error('Claude Code session id is not a transcript name');
     }
 }
-function collectTitle(record, titles) {
-    const take = (value) => typeof value === 'string' && value.trim() ? sanitizeForeignTitle(value) : undefined;
-    switch (record.type) {
-        case 'ai-title':
-            titles.aiTitle = take(record.aiTitle ?? record.title) ?? titles.aiTitle;
-            return;
-        case 'last-prompt':
-            titles.lastPrompt = take(record.lastPrompt ?? record.prompt) ?? titles.lastPrompt;
-            return;
-        case 'summary':
-            titles.summary = take(record.summary) ?? titles.summary;
-            return;
-        default:
-            return;
+function assertPositiveSafeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive safe integer`);
     }
 }
 function timestampMs(record) {
@@ -324,112 +513,49 @@ const TERMINAL_STOP_REASONS = new Set(['end_turn', 'stop_sequence']);
 /** Names the cutoff for a turn the transcript simply stops inside, so a reader
  *  can tell an imported snapshot's edge from a user's Stop or a provider abort. */
 const EXTERNAL_SNAPSHOT_ABORT_SOURCE = 'external_session_snapshot';
-/**
- * Which records are the conversation, decided before any of them becomes a
- * message. See `claude-code-transcript-lineage` for what the transcript's own
- * fields say about rewind branches, compaction boundaries, and fragmented
- * responses; this file only converts what that returns.
- */
-export function convertTranscript(sessionId, rawRecords) {
-    const records = resolveTranscriptLineage(rawRecords).records;
-    // Every fragment of one assistant response, keyed by `message.id`. A
-    // response is emitted once, from all of its fragments, at the position of
-    // the first — so a later fragment's text is part of the reply rather than
-    // something the first fragment's absence of text can suppress.
-    const responseFragments = new Map();
-    for (const record of records) {
-        if (record.type !== 'assistant')
-            continue;
+class ClaudeResponseCollector {
+    responses = new Map();
+    #maxBytes;
+    #retainedBytes = 0;
+    constructor(maxBytes) {
+        this.#maxBytes = maxBytes;
+    }
+    accept(record) {
         const responseId = stringOf(asMessageRecord(record)?.id);
         if (responseId === undefined)
-            continue;
-        const existing = responseFragments.get(responseId);
+            return;
+        const retainedBytes = Buffer.byteLength(JSON.stringify(record), 'utf8');
+        if (retainedBytes > this.#maxBytes - this.#retainedBytes) {
+            throw new ExternalSessionLimitError('converted_bytes', this.#maxBytes, `Claude Code transcript converts to more than ${this.#maxBytes} bytes`);
+        }
+        this.#retainedBytes += retainedBytes;
+        const existing = this.responses.get(responseId);
         if (existing)
             existing.push(record);
         else
-            responseFragments.set(responseId, [record]);
-    }
-    const emittedResponses = new Set();
-    const messages = [];
-    // A boundary can precede the first turn — a transcript that opens straight
-    // after a compaction. A system note needs a turn to hang from, so the fact
-    // waits for one rather than being dropped for arriving early.
-    let pendingCompactBoundaryTs;
-    let turn;
-    let sequence = 0;
-    const id = (kind) => `claude-code:${sessionId}:${kind}:${sequence++}`;
-    // Turn ids count separately from message ids. Sharing one counter made turn
-    // ids skip (`turn:0`, `turn:3`) for no reason, and left them one edit away
-    // from colliding with a message id if the emission order ever changed.
-    let turnSequence = 0;
-    const nextTurnId = () => `claude-code:${sessionId}:turn:${turnSequence++}`;
-    const closeTurn = () => {
-        if (!turn)
-            return;
-        // Every turn gets a terminal state, and which one depends on what the
-        // transcript actually says.
-        //
-        // Leaving one out is not the same as preserving "unfinished". Without a
-        // `turn_state`, `deriveTurnRecords` falls back to `inferLegacyTurnStatus`,
-        // which answers `completed` for any turn holding an assistant message
-        // (`session.ts:1250`) and marks it `inferred`. The Ledger then refuses
-        // that uncorroborated terminal and the repair path persists
-        // `failed / missing_terminal_event` — an internal-corruption verdict on a
-        // transcript that was merely cut short. Measured: 13.9% of turns across
-        // 1130 local transcripts end with no assistant reply or at a `tool_use`
-        // whose result never arrived.
-        //
-        // So an unfinished turn is recorded as what it is: a snapshot that ended
-        // mid-turn, with an `abortSource` naming the import rather than a user or
-        // a provider. `end_turn`, interrupt notices and API errors keep their own
-        // evidence and are unaffected.
-        if (turn.aborted) {
-            messages.push({
-                type: 'turn_state',
-                id: id('turn-state'),
-                turnId: turn.turnId,
-                ts: turn.lastTs,
-                status: 'aborted',
-                abortedAt: turn.lastTs,
-                abortSource: 'claude-code.interrupt',
-            });
-        }
-        else if (turn.failed) {
-            messages.push({
-                type: 'turn_state',
-                id: id('turn-state'),
-                turnId: turn.turnId,
-                ts: turn.lastTs,
-                status: 'failed',
-                errorClass: 'claude_code_api_error',
-            });
-        }
-        else if (turn.terminalStop) {
-            messages.push({
-                type: 'turn_state',
-                id: id('turn-state'),
-                turnId: turn.turnId,
-                ts: turn.lastTs,
-                status: 'completed',
-            });
-        }
-        else {
-            messages.push({
-                type: 'turn_state',
-                id: id('turn-state'),
-                turnId: turn.turnId,
-                ts: turn.lastTs,
-                status: 'aborted',
-                abortedAt: turn.lastTs,
-                abortSource: EXTERNAL_SNAPSHOT_ABORT_SOURCE,
-            });
-        }
-        turn = undefined;
-    };
-    for (const record of records) {
-        const ts = timestampMs(record) ?? turn?.lastTs ?? 0;
-        if (turn)
-            turn.lastTs = ts;
+            this.responses.set(responseId, [record]);
+    }
+}
+class ClaudeTranscriptConverter {
+    #emittedResponses = new Set();
+    #messages = [];
+    #sessionId;
+    #responseFragments;
+    #limits;
+    #pendingCompactBoundaryTs;
+    #turn;
+    #sequence = 0;
+    #turnSequence = 0;
+    #convertedBytes = 0;
+    constructor(sessionId, responseFragments, limits) {
+        this.#sessionId = sessionId;
+        this.#responseFragments = responseFragments;
+        this.#limits = limits;
+    }
+    accept(record) {
+        const ts = timestampMs(record) ?? this.#turn?.lastTs ?? 0;
+        if (this.#turn)
+            this.#turn.lastTs = ts;
         const type = record.type;
         if (type === 'user') {
             const message = asMessageRecord(record);
@@ -439,7 +565,7 @@ export function convertTranscript(sessionId, rawRecords) {
                 // model, not the human. Importing them as user Turns would put the
                 // model's own tool output in the user's mouth.
                 for (const block of toolResults) {
-                    if (!turn)
+                    if (!this.#turn)
                         continue;
                     const toolUseId = stringOf(block.tool_use_id);
                     // A result with no `tool_use_id` cannot be matched to its call.
@@ -448,17 +574,17 @@ export function convertTranscript(sessionId, rawRecords) {
                     // than the row being absent.
                     if (!toolUseId)
                         continue;
-                    messages.push({
+                    this.#append({
                         type: 'tool_result',
-                        id: id('tool-result'),
-                        turnId: turn.turnId,
+                        id: this.#id('tool-result'),
+                        turnId: this.#turn.turnId,
                         ts,
                         toolUseId,
                         isError: block.is_error === true,
                         content: { kind: 'text', text: toolResultText(block.content) },
                     });
                 }
-                continue;
+                return;
             }
             const text = claudeUserAuthoredText(record);
             if (text === undefined) {
@@ -469,45 +595,51 @@ export function convertTranscript(sessionId, rawRecords) {
                 if (raw &&
                     isSyntheticClaudeUserText(raw) &&
                     raw.trimStart().startsWith('[Request interrupted')) {
-                    if (turn)
-                        turn.aborted = true;
+                    if (this.#turn)
+                        this.#turn.aborted = true;
                 }
-                continue;
+                return;
             }
             // A human-authored user record opens a new turn.
-            closeTurn();
-            turn = { turnId: nextTurnId(), lastTs: ts };
-            if (pendingCompactBoundaryTs !== undefined) {
-                messages.push({
+            this.#closeTurn();
+            this.#turn = { turnId: this.#nextTurnId(), lastTs: ts };
+            if (this.#pendingCompactBoundaryTs !== undefined) {
+                this.#append({
                     type: 'system_note',
-                    id: id('compact'),
-                    turnId: turn.turnId,
-                    ts: pendingCompactBoundaryTs,
+                    id: this.#id('compact'),
+                    turnId: this.#turn.turnId,
+                    ts: this.#pendingCompactBoundaryTs,
                     kind: 'context_compacted',
                 });
-                pendingCompactBoundaryTs = undefined;
+                this.#pendingCompactBoundaryTs = undefined;
             }
-            messages.push({ type: 'user', id: id('user'), turnId: turn.turnId, ts, text });
-            continue;
+            this.#append({
+                type: 'user',
+                id: this.#id('user'),
+                turnId: this.#turn.turnId,
+                ts,
+                text,
+            });
+            return;
         }
         if (type === 'assistant') {
-            if (!turn) {
+            if (!this.#turn) {
                 // A transcript can open with an assistant record when the session was
                 // resumed. Give it a turn rather than dropping the content.
-                turn = { turnId: nextTurnId(), lastTs: ts };
-                if (pendingCompactBoundaryTs !== undefined) {
-                    messages.push({
+                this.#turn = { turnId: this.#nextTurnId(), lastTs: ts };
+                if (this.#pendingCompactBoundaryTs !== undefined) {
+                    this.#append({
                         type: 'system_note',
-                        id: id('compact'),
-                        turnId: turn.turnId,
-                        ts: pendingCompactBoundaryTs,
+                        id: this.#id('compact'),
+                        turnId: this.#turn.turnId,
+                        ts: this.#pendingCompactBoundaryTs,
                         kind: 'context_compacted',
                     });
-                    pendingCompactBoundaryTs = undefined;
+                    this.#pendingCompactBoundaryTs = undefined;
                 }
             }
             if (record.isApiErrorMessage === true)
-                turn.failed = true;
+                this.#turn.failed = true;
             const message = asMessageRecord(record);
             const responseId = stringOf(message?.id);
             // A response is emitted once, at its first fragment, assembled from all
@@ -515,22 +647,22 @@ export function convertTranscript(sessionId, rawRecords) {
             // being written — its content is already in what was emitted, and
             // emitting again would repeat the reply.
             if (responseId !== undefined) {
-                if (emittedResponses.has(responseId))
-                    continue;
-                emittedResponses.add(responseId);
+                if (this.#emittedResponses.has(responseId))
+                    return;
+                this.#emittedResponses.add(responseId);
             }
             // A fragment with no id stands alone; it is the only fragment of itself.
             const fragments = (responseId === undefined
                 ? undefined
-                : responseFragments.get(responseId)) ?? [record];
+                : this.#responseFragments.get(responseId)) ?? [record];
             // Status evidence is read from every fragment, not just the first: the
             // `stop_reason` lands on whichever fragment the response finished on.
             for (const fragment of fragments) {
                 if (fragment.isApiErrorMessage === true)
-                    turn.failed = true;
+                    this.#turn.failed = true;
                 const stop = stringOf(asMessageRecord(fragment)?.stop_reason);
                 if (stop && TERMINAL_STOP_REASONS.has(stop))
-                    turn.terminalStop = stop;
+                    this.#turn.terminalStop = stop;
             }
             // The transcript names the model that produced each step. Carrying the
             // real value keeps an imported turn attributable; a placeholder would
@@ -545,10 +677,10 @@ export function convertTranscript(sessionId, rawRecords) {
                 .filter((part) => part.length > 0)
                 .join('\n\n');
             if (thinking) {
-                messages.push({
+                this.#append({
                     type: 'assistant',
-                    id: id('thinking'),
-                    turnId: turn.turnId,
+                    id: this.#id('thinking'),
+                    turnId: this.#turn.turnId,
                     ts,
                     text: '',
                     thinking: { text: thinking },
@@ -561,10 +693,10 @@ export function convertTranscript(sessionId, rawRecords) {
                 .filter((part) => part !== undefined && part.length > 0)
                 .join('\n\n');
             if (text) {
-                messages.push({
+                this.#append({
                     type: 'assistant',
-                    id: id('assistant'),
-                    turnId: turn.turnId,
+                    id: this.#id('assistant'),
+                    turnId: this.#turn.turnId,
                     ts,
                     text,
                     contentOrder: ['text'],
@@ -577,18 +709,20 @@ export function convertTranscript(sessionId, rawRecords) {
             // arriving; a call written after its sibling's result did not follow it.
             for (const fragment of fragments) {
                 for (const block of toolUseBlocks(asMessageRecord(fragment))) {
-                    messages.push({
+                    this.#append({
                         type: 'tool_call',
                         // The id must equal the tool_use id so the result can match it.
-                        id: stringOf(block.id) ?? id('tool-call'),
-                        turnId: turn.turnId,
+                        id: stringOf(block.id) ?? this.#id('tool-call'),
+                        turnId: this.#turn.turnId,
                         ts,
                         toolName: stringOf(block.name) ?? 'unknown',
                         args: block.input ?? {},
                     });
                 }
             }
-            continue;
+            if (responseId !== undefined)
+                this.#responseFragments.delete(responseId);
+            return;
         }
         // The compaction boundary, keyed on the record that states it.
         //
@@ -604,21 +738,103 @@ export function convertTranscript(sessionId, rawRecords) {
         // the boundary marks where the model's context restarted, which is the
         // part a reader cannot reconstruct from the messages themselves.
         if (record.subtype === 'compact_boundary') {
-            if (!turn) {
-                pendingCompactBoundaryTs = ts;
-                continue;
+            if (!this.#turn) {
+                this.#pendingCompactBoundaryTs = ts;
+                return;
             }
-            messages.push({
+            this.#append({
                 type: 'system_note',
-                id: id('compact'),
-                turnId: turn.turnId,
+                id: this.#id('compact'),
+                turnId: this.#turn.turnId,
                 ts,
                 kind: 'context_compacted',
             });
         }
     }
-    closeTurn();
-    return messages;
+    finish() {
+        this.#closeTurn();
+        return this.#messages;
+    }
+    #id(kind) {
+        return `claude-code:${this.#sessionId}:${kind}:${this.#sequence++}`;
+    }
+    #nextTurnId() {
+        return `claude-code:${this.#sessionId}:turn:${this.#turnSequence++}`;
+    }
+    #append(message) {
+        if (this.#messages.length >= this.#limits.maxMessages) {
+            throw new ExternalSessionLimitError('messages', this.#limits.maxMessages, `Claude Code transcript converts to more than ${this.#limits.maxMessages} messages`);
+        }
+        const encodedBytes = Buffer.byteLength(JSON.stringify(message), 'utf8');
+        if (encodedBytes > this.#limits.maxConvertedBytes - this.#convertedBytes) {
+            throw new ExternalSessionLimitError('converted_bytes', this.#limits.maxConvertedBytes, `Claude Code transcript converts to more than ${this.#limits.maxConvertedBytes} bytes`);
+        }
+        this.#convertedBytes += encodedBytes;
+        this.#messages.push(message);
+    }
+    #closeTurn() {
+        if (!this.#turn)
+            return;
+        // Every turn gets a terminal state, and which one depends on what the
+        // transcript actually says.
+        //
+        // Leaving one out is not the same as preserving "unfinished". Without a
+        // `turn_state`, `deriveTurnRecords` falls back to `inferLegacyTurnStatus`,
+        // which answers `completed` for any turn holding an assistant message
+        // (`session.ts:1250`) and marks it `inferred`. The Ledger then refuses
+        // that uncorroborated terminal and the repair path persists
+        // `failed / missing_terminal_event` — an internal-corruption verdict on a
+        // transcript that was merely cut short. Measured: 13.9% of turns across
+        // 1130 local transcripts end with no assistant reply or at a `tool_use`
+        // whose result never arrived.
+        //
+        // So an unfinished turn is recorded as what it is: a snapshot that ended
+        // mid-turn, with an `abortSource` naming the import rather than a user or
+        // a provider. `end_turn`, interrupt notices and API errors keep their own
+        // evidence and are unaffected.
+        if (this.#turn.aborted) {
+            this.#append({
+                type: 'turn_state',
+                id: this.#id('turn-state'),
+                turnId: this.#turn.turnId,
+                ts: this.#turn.lastTs,
+                status: 'aborted',
+                abortedAt: this.#turn.lastTs,
+                abortSource: 'claude-code.interrupt',
+            });
+        }
+        else if (this.#turn.failed) {
+            this.#append({
+                type: 'turn_state',
+                id: this.#id('turn-state'),
+                turnId: this.#turn.turnId,
+                ts: this.#turn.lastTs,
+                status: 'failed',
+                errorClass: 'claude_code_api_error',
+            });
+        }
+        else if (this.#turn.terminalStop) {
+            this.#append({
+                type: 'turn_state',
+                id: this.#id('turn-state'),
+                turnId: this.#turn.turnId,
+                ts: this.#turn.lastTs,
+                status: 'completed',
+            });
+        }
+        else {
+            this.#append({
+                type: 'turn_state',
+                id: this.#id('turn-state'),
+                turnId: this.#turn.turnId,
+                ts: this.#turn.lastTs,
+                status: 'aborted',
+                abortedAt: this.#turn.lastTs,
+                abortSource: EXTERNAL_SNAPSHOT_ABORT_SOURCE,
+            });
+        }
+        this.#turn = undefined;
+    }
 }
 function asMessageRecord(record) {
     const message = record.message;