@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/sessions/adapters/codex.js

@@ -1,8 +1,8 @@
 import { opendir } from 'node:fs/promises';
 import { basename, resolve } from 'node:path';
 import { z } from 'zod';
-import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
-import { readBoundedJsonLines, streamBoundedJsonLines, } from '../readers.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { streamBoundedJsonLines, } from '../readers.js';
 export const CODEX_ADAPTER_VERSION = '1.0.0';
 export const CODEX_SOURCE_SCHEMA_VERSION = '1.0.0';
 const AppServerEnvelopeSchema = z.object({
@@ -57,7 +57,7 @@ export class CodexSessionAdapter {
         for (const root of [...scope.allowedRoots].sort()) {
             for await (const locator of discoverJsonl(resolve(root), this.discoveryLimits.maxDepth)) {
                 if (++emitted > this.discoveryLimits.maxFiles) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Codex source discovery exceeded the authorized file limit');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Codex source discovery exceeded the authorized file limit', { limit: 'maxFiles', configured: this.discoveryLimits.maxFiles, observed: emitted });
                 }
                 yield {
                     provider: 'codex',
@@ -70,30 +70,34 @@ export class CodexSessionAdapter {
         }
     }
     async inspect(source) {
-        const parsed = await this.readSource(source);
-        return {
-            sourceSchemaVersion: parsed.schemaVersion,
-            consistency: parsed.consistency,
-            operationalState: 'available',
-        };
+        const records = this.readSource(source);
+        let result = await records.next();
+        while (!result.done)
+            result = await records.next();
+        return result.value;
     }
     async *stream(source, cursor) {
+        yield* this.readSource(source, cursor);
+    }
+    async *readSource(source, cursor) {
         const start = parseCursor(cursor?.value);
         const input = await streamBoundedJsonLines({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'provisional', limits: this.limits });
         let mode = isAppServerLocator(source.locator)
             ? 'app-server' : null;
         let schemaVersion = null;
         const sourceArtifactSessionId = rolloutIdFromFilename(source.locator);
-        let nativeSessionId = sourceArtifactSessionId;
+        const rolloutState = { nativeSessionId: sourceArtifactSessionId };
         const identities = new Map();
         let outputIndex = 0;
         let sawRecord = false;
+        let complete = false;
+        let sawActive = false;
         for await (const line of input) {
             sawRecord = true;
             mode ??= isAppServerRecord(line.value) ? 'app-server' : 'rollout';
             const currentSchema = declaredSchemaVersion([line]);
             if (schemaVersion && schemaVersion !== currentSchema) {
-                throw new SessionContractError('SCHEMA_DRIFT', 'Codex source declares mixed schema versions');
+                throw new SessionContractError('SCHEMA_DRIFT', 'Codex source declares mixed schema versions', schemaIssueDetail('schemaVersion'));
             }
             schemaVersion = currentSchema;
             assertSupportedSchemaMajor(schemaVersion);
@@ -101,30 +105,22 @@ export class CodexSessionAdapter {
             if (mode === 'app-server') {
                 const parsed = AppServerEnvelopeSchema.safeParse(line.value);
                 if (!parsed.success) {
-                    throw new SessionContractError('MALFORMED_SOURCE', 'Codex App Server record is malformed');
+                    throw new SessionContractError('MALFORMED_SOURCE', 'Codex App Server record is malformed', schemaRejectionDetail(parsed.error));
                 }
                 for (const thread of extractThreads(parsed.data)) {
                     validateThreadIdentity(thread, identities);
+                    sawActive ||= statusType(thread.status) === 'active';
                 }
-                normalized = normalizeAppServer([line]).records;
+                const appServer = normalizeAppServer([line]);
+                complete ||= appServer.complete;
+                normalized = appServer.records;
             }
             else {
                 const parsed = RolloutEnvelopeSchema.safeParse(line.value);
                 if (!parsed.success) {
-                    throw new SessionContractError('MALFORMED_SOURCE', 'Codex rollout record is malformed');
-                }
-                const payload = asObject(parsed.data.payload);
-                if (parsed.data.type === 'session_meta') {
-                    const declaredId = stringValue(payload.id);
-                    if (!declaredId) {
-                        throw new SessionContractError('MALFORMED_SOURCE', 'Codex session metadata is missing its id');
-                    }
-                    nativeSessionId = declaredId;
+                    throw new SessionContractError('MALFORMED_SOURCE', 'Codex rollout record is malformed', schemaRejectionDetail(parsed.error));
                 }
-                if (!nativeSessionId) {
-                    throw new SessionContractError('MALFORMED_SOURCE', 'Codex rollout has no session identity before content records');
-                }
-                normalized = [rolloutRecord(nativeSessionId, parsed.data, payload, line, sourceArtifactSessionId)];
+                normalized = [normalizeRolloutRecord(rolloutState, parsed.data, line, sourceArtifactSessionId)];
             }
             for (const record of normalized) {
                 if (outputIndex++ >= start)
@@ -132,25 +128,12 @@ export class CodexSessionAdapter {
             }
         }
         if (!sawRecord && !input.incompleteTail) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Codex JSONL source is empty');
-        }
-    }
-    async readSource(source) {
-        const input = await readBoundedJsonLines({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'provisional', limits: this.limits });
-        if (input.records.length === 0 && !input.incompleteTail) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Codex JSONL source is empty');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Codex JSONL source is empty', schemaIssueDetail('<root>'));
         }
-        const appServer = isAppServerLocator(source.locator)
-            || input.records.some((record) => isAppServerRecord(record.value));
-        const schemaVersion = declaredSchemaVersion(input.records);
-        assertSupportedSchemaMajor(schemaVersion);
-        const normalized = appServer
-            ? normalizeAppServer(input.records)
-            : normalizeRollout(input.records, source.locator);
         return {
-            records: normalized.records,
-            schemaVersion,
-            consistency: normalized.complete ? 'complete' : 'provisional',
+            sourceSchemaVersion: schemaVersion ?? CODEX_SOURCE_SCHEMA_VERSION,
+            consistency: complete && !sawActive ? 'complete' : 'provisional',
+            operationalState: 'available',
         };
     }
 }
@@ -162,7 +145,7 @@ function normalizeAppServer(input) {
     for (const line of input) {
         const parsed = AppServerEnvelopeSchema.safeParse(line.value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Codex App Server record is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Codex App Server record is malformed', schemaRejectionDetail(parsed.error));
         }
         const envelope = parsed.data;
         const threads = extractThreads(envelope);
@@ -207,30 +190,75 @@ function normalizeAppServer(input) {
     }
     return { records, complete: complete && !sawActive };
 }
-function normalizeRollout(input, locator) {
-    const sourceArtifactSessionId = rolloutIdFromFilename(locator);
-    let nativeSessionId = sourceArtifactSessionId;
-    const records = [];
-    for (const line of input) {
-        const parsed = RolloutEnvelopeSchema.safeParse(line.value);
-        if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Codex rollout record is malformed');
+function normalizeRolloutRecord(state, envelope, line, sourceArtifactSessionId) {
+    const payload = asObject(envelope.payload);
+    let firstMetadata = false;
+    if (envelope.type === 'session_meta') {
+        const declaredId = stringValue(payload.id);
+        if (!declaredId) {
+            throw new SessionContractError('MALFORMED_SOURCE', 'Codex session metadata is missing its id', schemaIssueDetail('payload.id'));
         }
-        const envelope = parsed.data;
-        const payload = asObject(envelope.payload);
-        if (envelope.type === 'session_meta') {
-            const declaredId = stringValue(payload.id);
-            if (!declaredId) {
-                throw new SessionContractError('MALFORMED_SOURCE', 'Codex session metadata is missing its id');
-            }
-            nativeSessionId = declaredId;
+        if (!state.metadataId) {
+            firstMetadata = true;
+            state.metadataId = declaredId;
+            state.nativeSessionId = declaredId;
+            const lineage = rolloutLineage(payload);
+            if (Object.keys(lineage).length > 0)
+                state.lineage = lineage;
         }
-        if (!nativeSessionId) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Codex rollout has no session identity before content records');
+        else if (declaredId !== state.metadataId) {
+            state.replayParentId ??= declaredId;
         }
-        records.push(rolloutRecord(nativeSessionId, envelope, payload, line, sourceArtifactSessionId));
     }
-    return { records, complete: false };
+    if (!state.nativeSessionId) {
+        throw new SessionContractError('MALFORMED_SOURCE', 'Codex rollout has no session identity before content records', schemaIssueDetail('payload.id'));
+    }
+    const historyStart = state.lineage?.subagentHistoryStartOrdinal;
+    // Legacy rollouts have no ordinal boundary; a new turn ends the replay prefix.
+    if (historyStart === undefined && (envelope.type === 'turn_context'
+        || (envelope.type === 'event_msg' && payload.type === 'task_started'))) {
+        state.replayParentId = undefined;
+    }
+    const parentId = stringValue(state.lineage?.parentThreadId)
+        ?? stringValue(state.lineage?.forkedFromId)
+        ?? state.replayParentId;
+    const inherited = !firstMetadata && parentId && (typeof historyStart === 'number'
+        ? (nonnegativeInteger(envelope.ordinal) ?? line.sequence) < historyStart
+        : state.replayParentId !== undefined);
+    const record = rolloutRecord(state.nativeSessionId, envelope, payload, line, sourceArtifactSessionId);
+    if (state.lineage)
+        record.extensions.lineage = state.lineage;
+    if (inherited) {
+        record.extensions.inheritedFromId = parentId;
+        record.extensions.replayed = true;
+    }
+    return record;
+}
+/** Apply the rollout identity rule to legacy catalog rows, including split parent replay. */
+export function recoverCodexRolloutIdentity(events) {
+    const metadata = [...events].sort((a, b) => a.sequence - b.sequence || a.eventId.localeCompare(b.eventId))
+        .find(event => asObject(event.extensions['native.codex']).rolloutType === 'session_meta');
+    if (!metadata?.nativeId)
+        return undefined; // App Server sources can contain multiple independent threads.
+    const native = asObject(metadata.extensions['native.codex']);
+    return { nativeSessionId: metadata.nativeId,
+        lineage: { ...rolloutLineage(asObject(native.unknownFields)), ...asObject(native.lineage) } };
+}
+function rolloutLineage(payload) {
+    const spawn = asObject(asObject(asObject(payload.source).subagent).thread_spawn);
+    return Object.fromEntries(Object.entries({
+        forkedFromId: stringValue(payload.forked_from_id),
+        parentThreadId: stringValue(spawn.parent_thread_id),
+        depth: nonnegativeInteger(spawn.depth ?? payload.depth),
+        agentPath: stringValue(payload.agent_path ?? spawn.agent_path),
+        agentNickname: stringValue(payload.agent_nickname ?? spawn.agent_nickname),
+        subagentHistoryStartOrdinal: nonnegativeInteger(payload.subagent_history_start_ordinal),
+        threadSource: stringValue(payload.thread_source),
+    }).filter(([, value]) => value !== undefined));
+}
+function nonnegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+        ? value : undefined;
 }
 function threadEvidence(thread, envelope, line) {
     const status = statusType(thread.status);
@@ -350,7 +378,7 @@ function extractThreads(envelope) {
     return candidates.map((candidate) => {
         const parsed = ThreadSchema.safeParse(candidate);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Codex App Server thread is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Codex App Server thread is malformed', schemaRejectionDetail(parsed.error));
         }
         return parsed.data;
     });
@@ -359,7 +387,7 @@ function validateThreadIdentity(thread, identities) {
     const sessionTree = thread.sessionId ?? thread.id;
     const previous = identities.get(thread.id);
     if (previous && previous !== sessionTree) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'Codex thread session-tree identity changed');
+        throw new SessionContractError('SCHEMA_DRIFT', 'Codex thread session-tree identity changed', schemaIssueDetail('sessionId'));
     }
     identities.set(thread.id, sessionTree);
 }
@@ -514,7 +542,7 @@ function parseCursor(value) {
     if (value === undefined || value === '')
         return 0;
     if (!/^\d+$/.test(value))
-        throw new SessionContractError('SCHEMA_DRIFT', 'Codex record cursor is invalid');
+        throw new SessionContractError('SCHEMA_DRIFT', 'Codex record cursor is invalid', schemaIssueDetail('cursor'));
     return Number(value);
 }
 function unixTimestamp(value) {

package/dist/src/sessions/adapters/copilot.js

@@ -1,6 +1,6 @@
 import { basename, extname } from 'node:path';
 import { z } from 'zod';
-import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
 import { readBoundedJson } from '../readers.js';
 export const COPILOT_ADAPTER_VERSION = '1.0.0';
 export const COPILOT_EXPORT_SCHEMA_VERSION = '1.0.0';
@@ -76,7 +76,7 @@ export class CopilotSessionAdapter {
         }, this.limits);
         const parsed = ExportSchema.safeParse(value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Copilot chat export is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Copilot chat export is malformed', schemaRejectionDetail(parsed.error));
         }
         const schemaVersion = declaredSchemaVersion(parsed.data);
         assertSupportedSchemaMajor(schemaVersion);
@@ -193,7 +193,7 @@ function declaredSchemaVersion(value) {
         ? value.version
         : Number(String(value.version).split('.')[0]);
     if (!Number.isInteger(major) || major < 1) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Copilot export version');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Copilot export version', schemaIssueDetail('version'));
     }
     return `${major}.0.0`;
 }
@@ -210,7 +210,7 @@ function parseCursor(value) {
     if (!value)
         return 0;
     if (!/^\d+$/.test(value)) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Copilot record cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Copilot record cursor', schemaIssueDetail('cursor'));
     }
     return Number(value);
 }

package/dist/src/sessions/adapters/cursor.js

@@ -1,8 +1,8 @@
 import { opendir } from 'node:fs/promises';
 import { basename, dirname, extname, resolve, } from 'node:path';
 import { z } from 'zod';
-import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
-import { readBoundedJsonLines, readBoundedText, streamBoundedJsonLines, } from '../readers.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { readBoundedText, streamBoundedJsonLines, } from '../readers.js';
 export const CURSOR_ADAPTER_VERSION = '1.0.0';
 export const CURSOR_SOURCE_SCHEMA_VERSION = '1.0.0';
 const CliEventSchema = z.object({
@@ -82,7 +82,7 @@ export class CursorSessionAdapter {
         for (const root of [...scope.allowedRoots].sort()) {
             for await (const locator of discoverJsonl(resolve(root), this.discoveryLimits.maxDepth)) {
                 if (++emitted > this.discoveryLimits.maxFiles) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Cursor source discovery exceeded the authorized file limit');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Cursor source discovery exceeded the authorized file limit', { limit: 'maxFiles', configured: this.discoveryLimits.maxFiles, observed: emitted });
                 }
                 yield {
                     provider: 'cursor',
@@ -93,6 +93,16 @@ export class CursorSessionAdapter {
         }
     }
     async inspect(source) {
+        if (source.locatorClass === 'cursor-cli-stream-json'
+            || source.locatorClass === 'cursor-cloud-events-jsonl'
+            || source.locatorClass === 'cursor-agent-transcript-jsonl') {
+            const records = this.stream(source);
+            let result = await records.next();
+            while (!result.done)
+                result = await records.next();
+            if (result.value)
+                return result.value;
+        }
         const parsed = await this.readSource(source);
         return {
             sourceSchemaVersion: parsed.schemaVersion,
@@ -102,7 +112,8 @@ export class CursorSessionAdapter {
     }
     async *stream(source, cursor) {
         if (source.locatorClass === 'cursor-cli-stream-json'
-            || source.locatorClass === 'cursor-cloud-events-jsonl') {
+            || source.locatorClass === 'cursor-cloud-events-jsonl'
+            || source.locatorClass === 'cursor-agent-transcript-jsonl') {
             const input = await streamBoundedJsonLines({
                 selectedPath: source.locator,
                 allowedRoots: source.authorizedScope.allowedRoots,
@@ -114,13 +125,14 @@ export class CursorSessionAdapter {
             let agentId;
             let runId;
             let sawRecord = false;
+            let complete = false;
             for await (const line of input) {
                 sawRecord = true;
                 const raw = asObject(line.value);
                 const currentSchema = typeof raw.schemaVersion === 'string'
                     ? raw.schemaVersion : CURSOR_SOURCE_SCHEMA_VERSION;
                 if (schemaVersion && schemaVersion !== currentSchema) {
-                    throw new SessionContractError('SCHEMA_DRIFT', 'Cursor source declares mixed schema versions');
+                    throw new SessionContractError('SCHEMA_DRIFT', 'Cursor source declares mixed schema versions', schemaIssueDetail('schemaVersion'));
                 }
                 schemaVersion = currentSchema;
                 assertSupportedSchemaMajor(schemaVersion);
@@ -128,7 +140,7 @@ export class CursorSessionAdapter {
                 if (source.locatorClass === 'cursor-cli-stream-json') {
                     const parsed = CliEventSchema.safeParse(line.value);
                     if (!parsed.success) {
-                        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor CLI event is malformed');
+                        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor CLI event is malformed', schemaRejectionDetail(parsed.error));
                     }
                     const event = parsed.data;
                     if (cliSessionId && cliSessionId !== event.session_id) {
@@ -137,10 +149,10 @@ export class CursorSessionAdapter {
                     cliSessionId = event.session_id;
                     record = normalizeCli([line]).records[0];
                 }
-                else {
+                else if (source.locatorClass === 'cursor-cloud-events-jsonl') {
                     const parsed = CloudEventSchema.safeParse(line.value);
                     if (!parsed.success) {
-                        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Cloud Agent event is malformed');
+                        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Cloud Agent event is malformed', schemaRejectionDetail(parsed.error));
                     }
                     const event = parsed.data;
                     const nextAgentId = event.agent?.id ?? agentId;
@@ -153,27 +165,38 @@ export class CursorSessionAdapter {
                     }
                     agentId = nextAgentId;
                     runId = nextRunId;
-                    record = normalizeCloud([{
+                    const normalized = normalizeCloud([{
                             ...line,
                             value: {
                                 ...event,
                                 agent: event.agent ?? (agentId ? { id: agentId } : undefined),
                                 run: event.run ?? (runId ? { id: runId } : undefined),
                             },
-                        }]).records[0];
+                        }]);
+                    complete ||= normalized.complete;
+                    record = normalized.records[0];
+                }
+                else {
+                    record = normalizeAgentTranscript([line], source.locator).records[0];
                 }
+                complete ||= record.extensions?.lifecycle === 'complete';
                 if (outputIndex++ >= start)
                     yield record;
             }
             if (!sawRecord && !input.incompleteTail) {
-                throw new SessionContractError('MALFORMED_SOURCE', 'Cursor structured source is empty');
+                throw new SessionContractError('MALFORMED_SOURCE', 'Cursor structured source is empty', schemaIssueDetail('<root>'));
             }
-            return;
+            return {
+                sourceSchemaVersion: schemaVersion ?? CURSOR_SOURCE_SCHEMA_VERSION,
+                consistency: complete && !input.incompleteTail ? 'complete' : 'provisional',
+                operationalState: 'available',
+            };
         }
         const parsed = await this.readSource(source);
         const start = parseCursor(cursor?.value);
         for (const record of parsed.records.slice(start))
             yield record;
+        return undefined;
     }
     async readSource(source) {
         const authorization = {
@@ -191,36 +214,6 @@ export class CursorSessionAdapter {
                 records: normalizeMarkdown(input.value, source.locator),
             };
         }
-        const input = await readBoundedJsonLines(authorization, { consistency: 'provisional', limits: this.limits });
-        if (input.records.length === 0 && !input.incompleteTail) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor structured source is empty');
-        }
-        const schemaVersion = declaredVersion(input.records);
-        assertSupportedSchemaMajor(schemaVersion);
-        if (source.locatorClass === 'cursor-cli-stream-json') {
-            const normalized = normalizeCli(input.records);
-            return {
-                schemaVersion,
-                consistency: normalized.complete && !input.incompleteTail ? 'complete' : 'provisional',
-                records: normalized.records,
-            };
-        }
-        if (source.locatorClass === 'cursor-cloud-events-jsonl') {
-            const normalized = normalizeCloud(input.records);
-            return {
-                schemaVersion,
-                consistency: normalized.complete && !input.incompleteTail ? 'complete' : 'provisional',
-                records: normalized.records,
-            };
-        }
-        if (source.locatorClass === 'cursor-agent-transcript-jsonl') {
-            const normalized = normalizeAgentTranscript(input.records, source.locator);
-            return {
-                schemaVersion,
-                consistency: normalized.complete && !input.incompleteTail ? 'complete' : 'provisional',
-                records: normalized.records,
-            };
-        }
         throw new SessionContractError('UNSUPPORTED_OPERATION', 'unsupported Cursor source class');
     }
 }
@@ -257,7 +250,7 @@ function normalizeCli(input) {
     for (const line of input) {
         const parsed = CliEventSchema.safeParse(line.value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor CLI event is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor CLI event is malformed', schemaRejectionDetail(parsed.error));
         }
         const event = parsed.data;
         if (sessionId && sessionId !== event.session_id) {
@@ -307,7 +300,7 @@ function normalizeCloud(input) {
     for (const line of input) {
         const parsed = CloudEventSchema.safeParse(line.value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Cloud Agent event is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Cloud Agent event is malformed', schemaRejectionDetail(parsed.error));
         }
         const event = parsed.data;
         const nextAgentId = event.agent?.id ?? agentId;
@@ -371,7 +364,7 @@ function normalizeAgentTranscript(input, locator) {
     for (const line of input) {
         const parsed = AgentTranscriptEventSchema.safeParse(line.value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor agent transcript event is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor agent transcript event is malformed', schemaRejectionDetail(parsed.error));
         }
         const event = parsed.data;
         const terminal = event.type === 'turn_ended' && event.status === 'success';
@@ -411,7 +404,7 @@ function normalizeMarkdown(value, locator) {
     const heading = /^#{1,3}\s+(User|Assistant|Cursor)\s*$/gim;
     const matches = [...value.matchAll(heading)];
     if (matches.length === 0) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Markdown export has no role headings');
+        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Markdown export has no role headings', schemaIssueDetail('headings'));
     }
     const nativeSessionId = basename(locator, extname(locator));
     return matches.map((match, index) => {
@@ -462,16 +455,6 @@ function messageText(value) {
         return '';
     }).filter(Boolean).join('\n');
 }
-function declaredVersion(records) {
-    const versions = new Set(records.map((line) => {
-        const value = asObject(line.value);
-        return typeof value.schemaVersion === 'string' ? value.schemaVersion : CURSOR_SOURCE_SCHEMA_VERSION;
-    }));
-    if (versions.size !== 1) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'Cursor source declares mixed schema versions');
-    }
-    return [...versions][0];
-}
 function declaredEventVersion(event) {
     return event.schemaVersion ?? CURSOR_SOURCE_SCHEMA_VERSION;
 }
@@ -511,7 +494,7 @@ function parseCursor(value) {
     if (!value)
         return 0;
     if (!/^\d+$/.test(value)) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Cursor record cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Cursor record cursor', schemaIssueDetail('cursor'));
     }
     return Number(value);
 }

package/dist/src/sessions/adapters/deepseek-harness.js

@@ -1,8 +1,8 @@
 import { opendir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { z } from 'zod';
-import { SessionContractError, } from '../contracts.js';
-import { readBoundedJsonLines, streamBoundedJsonLines } from '../readers.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, } from '../contracts.js';
+import { streamBoundedJsonLines } from '../readers.js';
 export const DEEPSEEK_HARNESS_ADAPTER_VERSION = '1.0.0';
 export const DEEPSEEK_HARNESS_SOURCE_SCHEMA_VERSION = '2.0.0';
 const Header = z.object({
@@ -39,7 +39,7 @@ export class DeepSeekHarnessSessionAdapter {
         for (const root of [...scope.allowedRoots].sort()) {
             for await (const locator of jsonlFiles(resolve(root))) {
                 if (++count > this.maxFiles)
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'DeepSeek Harness discovery file limit exceeded');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'DeepSeek Harness discovery file limit exceeded', { limit: 'maxFiles', configured: this.maxFiles, observed: count });
                 yield { provider: this.provider, locator, locatorClass: 'deepseek-harness-session-v2-jsonl' };
             }
         }
@@ -47,12 +47,15 @@ export class DeepSeekHarnessSessionAdapter {
     async inspect(source) {
         let input;
         try {
-            input = await readBoundedJsonLines({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'provisional', limits: this.limits });
+            input = await streamBoundedJsonLines({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'provisional', limits: this.limits });
         }
         catch (error) {
             throw normalizeAuthorizationError(error);
         }
-        const header = parseHeader(input.records[0]?.value);
+        let header;
+        for await (const line of input)
+            header ??= parseHeader(line.value);
+        header ??= parseHeader(undefined);
         if (input.incompleteTail)
             throw new SessionContractError('TRUNCATED_SOURCE', 'DeepSeek Harness session has a truncated JSONL tail');
         return { sourceSchemaVersion: `${header.version}.0.0`, consistency: 'complete', operationalState: 'available' };
@@ -67,24 +70,24 @@ export class DeepSeekHarnessSessionAdapter {
         }
         const start = cursor?.value.replace(/^byte:/, '') ?? '0';
         if (!/^\d+$/.test(start))
-            throw new SessionContractError('SCHEMA_DRIFT', 'invalid DeepSeek Harness cursor');
+            throw new SessionContractError('SCHEMA_DRIFT', 'invalid DeepSeek Harness cursor', schemaIssueDetail('cursor'));
         let header;
         let expectedSeq = 0;
         let end = 0;
         for await (const line of input) {
             end = line.byteOffset + line.byteLength;
             if (Number(start) > line.byteOffset && Number(start) < end)
-                throw new SessionContractError('SCHEMA_DRIFT', 'DeepSeek Harness cursor is not a record boundary');
+                throw new SessionContractError('SCHEMA_DRIFT', 'DeepSeek Harness cursor is not a record boundary', schemaIssueDetail('cursor'));
             if (!header) {
                 header = parseHeader(line.value);
                 continue;
             }
             const parsed = Event.safeParse(line.value);
             if (!parsed.success)
-                throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session event is malformed');
+                throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session event is malformed', schemaRejectionDetail(parsed.error));
             const event = parsed.data;
             if (event.seq !== expectedSeq)
-                throw new SessionContractError(event.seq < expectedSeq ? 'DUPLICATE_NATIVE_ID' : 'SCHEMA_DRIFT', `DeepSeek Harness sequence expected ${expectedSeq}, received ${event.seq}`);
+                throw new SessionContractError(event.seq < expectedSeq ? 'DUPLICATE_NATIVE_ID' : 'SCHEMA_DRIFT', `DeepSeek Harness sequence expected ${expectedSeq}, received ${event.seq}`, schemaIssueDetail('seq'));
             expectedSeq++;
             if (end <= Number(start))
                 continue;
@@ -121,9 +124,9 @@ export class DeepSeekHarnessSessionAdapter {
             };
         }
         if (!header)
-            throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session header is missing');
+            throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session header is missing', schemaIssueDetail('header'));
         if (Number(start) > end)
-            throw new SessionContractError('SCHEMA_DRIFT', 'DeepSeek Harness cursor exceeds source size');
+            throw new SessionContractError('SCHEMA_DRIFT', 'DeepSeek Harness cursor exceeds source size', schemaIssueDetail('cursor'));
         if (input.incompleteTail)
             throw new SessionContractError('TRUNCATED_SOURCE', 'DeepSeek Harness session has a truncated JSONL tail');
     }
@@ -131,7 +134,7 @@ export class DeepSeekHarnessSessionAdapter {
 function parseHeader(value) {
     const parsed = Header.safeParse(value);
     if (!parsed.success)
-        throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session header is malformed');
+        throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session header is malformed', schemaRejectionDetail(parsed.error));
     if (parsed.data.version !== 2)
         throw new SessionContractError('UNKNOWN_SCHEMA_MAJOR', `unsupported DeepSeek Harness session version: ${parsed.data.version}`);
     return parsed.data;