@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/sessions/adapters/muse-workspace-scan.js

@@ -1,5 +1,5 @@
 import { open } from 'node:fs/promises';
-import { SessionContractError } from '../contracts.js';
+import { schemaIssueDetail, SessionContractError } from '../contracts.js';
 import { authorizeSourceFile } from '../policy.js';
 // Discovery inspects metadata, not an entire import. Bound allocation before
 // assembling a line (readline would buffer an arbitrarily large single line).
@@ -9,18 +9,31 @@ export const MUSE_WORKSPACE_SCAN_LIMITS = Object.freeze({
     maxTotalBytes: 32 * 1024 * 1024,
     maxNestingDepth: 64,
 });
-export async function* museWorkspaceScanLines(authorization, limits, progress) {
+export const MUSE_WORKSPACE_TAIL_BYTES = 1024 * 1024;
+export class MuseWorkspaceLimitError extends SessionContractError {
+    limitName;
+    limitValue;
+    constructor(limitName, limitValue, observed) {
+        super('RESOURCE_LIMIT_EXCEEDED', `Muse workspace inspection exceeded ${limitName}=${limitValue}`, { limit: limitName, configured: limitValue, observed });
+        this.limitName = limitName;
+        this.limitValue = limitValue;
+    }
+}
+export async function* museWorkspaceScanLines(authorization, limits, progress, tailBytes) {
     const allowed = await authorizeSourceFile(authorization);
     const handle = await open(allowed.canonicalPath, 'r');
     try {
         const buffer = Buffer.allocUnsafe(64 * 1024);
-        let position = 0;
+        let position = tailBytes === undefined ? 0 : Math.max(0, allowed.size - tailBytes);
+        // A tail window may start inside a record (or a UTF-8 code point).
+        // Discard that fragment before parsing any complete JSONL records.
+        let skipPartialLine = position > 0;
         let parts = [];
         let length = 0;
         while (position < allowed.size) {
             const remaining = limits.maxTotalBytes - progress.bytesInspected;
             if (remaining <= 0)
-                throw scanLimit();
+                throw scanLimit('maxTotalBytes', limits.maxTotalBytes, allowed.size);
             const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, allowed.size - position, remaining), position);
             if (bytesRead === 0) {
                 throw new SessionContractError('TRUNCATED_SOURCE', 'Muse source changed during inspection');
@@ -31,8 +44,15 @@ export async function* museWorkspaceScanLines(authorization, limits, progress) {
                 const newline = buffer.indexOf(10, start);
                 const end = newline >= 0 && newline < bytesRead ? newline + 1 : bytesRead;
                 const segment = buffer.subarray(start, end);
+                if (skipPartialLine) {
+                    progress.bytesInspected += segment.length;
+                    start = end;
+                    if (newline >= 0 && newline < bytesRead)
+                        skipPartialLine = false;
+                    continue;
+                }
                 if (length + segment.length > limits.maxRecordBytes)
-                    throw scanLimit();
+                    throw scanLimit('maxRecordBytes', limits.maxRecordBytes, length + segment.length);
                 parts.push(Buffer.from(segment));
                 length += segment.length;
                 progress.bytesInspected += segment.length;
@@ -43,7 +63,7 @@ export async function* museWorkspaceScanLines(authorization, limits, progress) {
                     length = 0;
                     if (line.trim() !== '') {
                         if (progress.recordsInspected >= limits.maxRecords)
-                            throw scanLimit();
+                            throw scanLimit('maxRecords', limits.maxRecords, progress.recordsInspected + 1);
                         const value = parseMuseScanJson(line, limits.maxNestingDepth);
                         progress.recordsInspected += 1;
                         yield value;
@@ -55,7 +75,7 @@ export async function* museWorkspaceScanLines(authorization, limits, progress) {
             const line = Buffer.concat(parts, length).toString('utf8');
             if (line.trim() !== '') {
                 if (progress.recordsInspected >= limits.maxRecords)
-                    throw scanLimit();
+                    throw scanLimit('maxRecords', limits.maxRecords, progress.recordsInspected + 1);
                 let value;
                 try {
                     value = parseMuseScanJson(line, limits.maxNestingDepth);
@@ -85,7 +105,7 @@ export function parseMuseScanJson(line, maxDepth) {
         value = JSON.parse(line);
     }
     catch {
-        throw new SessionContractError('MALFORMED_SOURCE', 'Muse inspection encountered malformed JSON');
+        throw new SessionContractError('MALFORMED_SOURCE', 'Muse inspection encountered malformed JSON', schemaIssueDetail('<root>', 'invalid_json'));
     }
     // Check depth iteratively, including decoded retained children, before zod
     // validation. Deep input must produce a limit diagnostic, not stack overflow.
@@ -93,7 +113,7 @@ export function parseMuseScanJson(line, maxDepth) {
     while (pending.length > 0) {
         const current = pending.pop();
         if (current.depth > maxDepth)
-            throw scanLimit();
+            throw scanLimit('maxNestingDepth', maxDepth, current.depth);
         if (current.value !== null && typeof current.value === 'object') {
             for (const child of Object.values(current.value)) {
                 pending.push({ value: child, depth: current.depth + 1 });
@@ -102,7 +122,7 @@ export function parseMuseScanJson(line, maxDepth) {
     }
     return value;
 }
-function scanLimit() {
-    return new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'bounded Muse workspace inspection limit exceeded');
+function scanLimit(limit, configured, observed) {
+    return new MuseWorkspaceLimitError(limit, configured, observed);
 }
 //# sourceMappingURL=muse-workspace-scan.js.map

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

@@ -42,9 +42,10 @@
 import { opendir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { z } from 'zod';
-import { SessionContractError, SessionErrorCodeSchema, assertSupportedSchemaMajor, } from '../contracts.js';
-import { readBoundedJson, readBoundedJsonLines, } from '../readers.js';
-import { MUSE_WORKSPACE_SCAN_LIMITS, museWorkspaceScanLines, parseMuseScanJson, } from './muse-workspace-scan.js';
+import { matchSessionWorkspace, WORKSPACE_MATCH_KINDS } from '../workspace-matching.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, SessionErrorCodeSchema, SessionRejectionDetailSchema, assertSupportedSchemaMajor, } from '../contracts.js';
+import { readBoundedJson, streamBoundedJsonLines, } from '../readers.js';
+import { MUSE_WORKSPACE_SCAN_LIMITS, MUSE_WORKSPACE_TAIL_BYTES, MuseWorkspaceLimitError, museWorkspaceScanLines, parseMuseScanJson, } from './muse-workspace-scan.js';
 export const MUSE_ADAPTER_VERSION = '1.0.0';
 export const MUSE_EXPORT_SCHEMA_VERSION = '1.0.0';
 export const MUSE_EXPORT_SCHEMA_MAJOR = 1;
@@ -173,7 +174,7 @@ export class MuseSessionAdapter {
         for (const root of [...scope.allowedRoots].sort()) {
             for await (const locator of museNativeSessionLogs(resolve(root))) {
                 if (++count > this.maxFiles) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Muse native session discovery exceeded the authorized file limit');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Muse native session discovery exceeded the authorized file limit', { limit: 'maxFiles', configured: this.maxFiles, observed: count });
                 }
                 yield { provider: 'muse', locator, locatorClass: MUSE_NATIVE_LOCATOR_CLASS };
             }
@@ -203,7 +204,7 @@ export class MuseSessionAdapter {
             const native = await this.readNative(source);
             const start = parseEventCursor(cursor?.value);
             let outputIndex = 0;
-            for (const record of native.records) {
+            for await (const record of this.readNativeRecords(source)) {
                 const position = outputIndex;
                 outputIndex += 1;
                 if (position < start)
@@ -254,13 +255,13 @@ export class MuseSessionAdapter {
         }
         catch (error) {
             if (error instanceof SessionContractError && error.code === 'SCHEMA_DRIFT') {
-                throw new SessionContractError('MALFORMED_SOURCE', 'muse export document is not valid JSON');
+                throw new SessionContractError('MALFORMED_SOURCE', 'muse export document is not valid JSON', error.detail);
             }
             throw error;
         }
         const parsed = MuseTrajectorySchema.safeParse(value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'input is not a declared muse export trajectory document');
+            throw new SessionContractError('MALFORMED_SOURCE', 'input is not a declared muse export trajectory document', schemaRejectionDetail(parsed.error));
         }
         assertSupportedSchemaMajor(`${parsed.data.export_schema_version}.0.0`, MUSE_EXPORT_SCHEMA_MAJOR);
         return { trajectory: parsed.data, bytesRead };
@@ -333,80 +334,89 @@ export class MuseSessionAdapter {
         };
     }
     async readNative(source) {
-        this.assertSupportedLocator(source);
-        let input;
+        const records = this.readNativeRecords(source);
+        let result = await records.next();
+        while (!result.done)
+            result = await records.next();
+        return result.value;
+    }
+    async *readNativeRecords(source) {
         try {
-            input = await readBoundedJsonLines({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'complete', limits: this.limits });
-        }
-        catch (error) {
-            if (error instanceof SessionContractError && error.code === 'SCHEMA_DRIFT') {
-                throw new SessionContractError('MALFORMED_SOURCE', 'Muse native session log contains malformed JSONL');
-            }
-            throw error;
-        }
-        const diagnostics = {};
-        const records = [];
-        let fallbackSessionId = nativeSessionIdFromLocator(source.locator) ?? source.sourceId;
-        let complete = false;
-        for (const line of input.records) {
-            const value = line.value;
-            if (isOmissionMarker(value)) {
-                diagnostics.omitted_records = (diagnostics.omitted_records ?? 0) + 1;
-                if (asObject(value).retained_marker === 'omitted_live_only') {
-                    diagnostics.omitted_live_only = (diagnostics.omitted_live_only ?? 0) + 1;
-                }
-                continue;
-            }
-            const retained = MuseRetainedFrameSchema.safeParse(value);
-            if (retained.success) {
-                diagnostics.retained_frames = (diagnostics.retained_frames ?? 0) + 1;
-                for (const child of retained.data.children) {
-                    let decoded;
-                    try {
-                        decoded = JSON.parse(child.record_json);
+            this.assertSupportedLocator(source);
+            const input = await streamBoundedJsonLines({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'complete', limits: this.limits });
+            const diagnostics = {};
+            let records = 0;
+            let fallbackSessionId = nativeSessionIdFromLocator(source.locator) ?? source.sourceId;
+            let complete = false;
+            for await (const line of input) {
+                const value = line.value;
+                if (isOmissionMarker(value)) {
+                    diagnostics.omitted_records = (diagnostics.omitted_records ?? 0) + 1;
+                    if (asObject(value).retained_marker === 'omitted_live_only') {
+                        diagnostics.omitted_live_only = (diagnostics.omitted_live_only ?? 0) + 1;
                     }
-                    catch {
-                        throw new SessionContractError('MALFORMED_SOURCE', 'Muse retained frame child record is malformed JSON');
-                    }
-                    const event = recordEventFromEnvelope(decoded);
-                    if (!event) {
-                        throw new SessionContractError('MALFORMED_SOURCE', 'Muse retained frame child record is malformed');
+                    continue;
+                }
+                const retained = MuseRetainedFrameSchema.safeParse(value);
+                if (retained.success) {
+                    diagnostics.retained_frames = (diagnostics.retained_frames ?? 0) + 1;
+                    for (const child of retained.data.children) {
+                        let decoded;
+                        try {
+                            decoded = JSON.parse(child.record_json);
+                        }
+                        catch {
+                            throw new SessionContractError('MALFORMED_SOURCE', 'Muse retained frame child record is malformed JSON', schemaIssueDetail('children.record_json', 'invalid_json'));
+                        }
+                        const envelope = MuseEnvelopeSchema.safeParse(decoded);
+                        if (!envelope.success) {
+                            throw new SessionContractError('MALFORMED_SOURCE', 'Muse retained frame child record is malformed', schemaRejectionDetail(envelope.error));
+                        }
+                        const event = { kind: 'record', envelope: envelope.data };
+                        fallbackSessionId = streamSessionIdOf(event.envelope) ?? fallbackSessionId;
+                        complete ||= event.envelope.payload_type === 'session.end';
+                        diagnostics.retained_frame_children = (diagnostics.retained_frame_children ?? 0) + 1;
+                        records += 1;
+                        yield {
+                            event,
+                            line,
+                            retainedFrame: retained.data.retained_frame,
+                            retainedChildIndex: child.child_index,
+                        };
                     }
-                    fallbackSessionId = streamSessionIdOf(event.envelope) ?? fallbackSessionId;
-                    complete ||= event.envelope.payload_type === 'session.end';
-                    diagnostics.retained_frame_children = (diagnostics.retained_frame_children ?? 0) + 1;
-                    records.push({
-                        event,
-                        line,
-                        retainedFrame: retained.data.retained_frame,
-                        retainedChildIndex: child.child_index,
-                    });
+                    continue;
                 }
-                continue;
+                const envelope = MuseEnvelopeSchema.safeParse(value);
+                if (!envelope.success) {
+                    throw new SessionContractError('MALFORMED_SOURCE', 'Muse native session log line is not a supported record shape', schemaRejectionDetail('retained_frame' in asObject(value) ? retained.error : envelope.error));
+                }
+                const event = { kind: 'record', envelope: envelope.data };
+                fallbackSessionId = streamSessionIdOf(event.envelope) ?? fallbackSessionId;
+                complete ||= event.envelope.payload_type === 'session.end';
+                records += 1;
+                yield { event, line };
             }
-            const event = recordEventFromEnvelope(value);
-            if (!event) {
-                throw new SessionContractError('MALFORMED_SOURCE', 'Muse native session log line is not a supported record shape');
+            if (records === 0) {
+                throw new SessionContractError('MALFORMED_SOURCE', 'Muse native session log contains no record envelopes', schemaIssueDetail('<root>'));
             }
-            fallbackSessionId = streamSessionIdOf(event.envelope) ?? fallbackSessionId;
-            complete ||= event.envelope.payload_type === 'session.end';
-            records.push({ event, line });
+            return {
+                complete,
+                context: {
+                    locatorClass: MUSE_NATIVE_LOCATOR_CLASS,
+                    sourceLabel: 'muse native session log',
+                    bytesRead: input.bytesRead,
+                    fallbackSessionId,
+                    spawns: new Map(),
+                    diagnostics,
+                },
+            };
         }
-        if (records.length === 0) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Muse native session log contains no record envelopes');
+        catch (error) {
+            if (error instanceof SessionContractError && error.code === 'SCHEMA_DRIFT') {
+                throw new SessionContractError('MALFORMED_SOURCE', 'Muse native session log contains malformed JSONL', error.detail);
+            }
+            throw error;
         }
-        return {
-            records,
-            complete,
-            context: {
-                locatorClass: MUSE_NATIVE_LOCATOR_CLASS,
-                sourceLabel: 'muse native session log',
-                bytesRead: input.bytesRead,
-                fallbackSessionId,
-                spawns: new Map(),
-                diagnostics,
-            },
-        };
     }
     assertSupportedLocator(source) {
         if (source.locatorClass !== MUSE_LOCATOR_CLASS && source.locatorClass !== MUSE_NATIVE_LOCATOR_CLASS) {
@@ -500,10 +510,18 @@ async function* museNativeSessionLogs(root) {
 }
 export const MuseWorkspaceInspectionSchema = z.object({
     outcome: z.enum(['matched', 'mismatch', 'inconclusive']),
+    attribution: z.enum(['matched', 'mismatch', 'unattributed']),
+    matchKind: z.enum(WORKSPACE_MATCH_KINDS).optional(),
     reasonCode: z.string().nullable(),
     recordsInspected: z.number().int().nonnegative(),
     bytesInspected: z.number().int().nonnegative(),
     completeInspection: z.boolean(),
+    limit: z.object({
+        name: z.enum(['maxRecords', 'maxRecordBytes', 'maxTotalBytes', 'maxNestingDepth']),
+        value: z.number().int().positive(),
+    }).optional(),
+    fallback: z.literal('bounded-tail').optional(),
+    detail: SessionRejectionDetailSchema.optional(),
 });
 /** Positive metadata evidence selects a source; import validates its full history. */
 export async function inspectMuseNativeWorkspace(source, workspacePath, limitsInput) {
@@ -511,25 +529,35 @@ export async function inspectMuseNativeWorkspace(source, workspacePath, limitsIn
     const progress = { recordsInspected: 0, bytesInspected: 0 };
     let sawWorkspaceEvidence = false;
     let retainedChildren = 0;
-    const receipt = (outcome, reasonCode, completeInspection = false) => ({ outcome, reasonCode, ...progress, completeInspection });
+    let limit;
+    let fallback;
+    const authorization = { selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots };
+    const receipt = (outcome, reasonCode, completeInspection = false) => ({
+        outcome, attribution: outcome === 'inconclusive' ? 'unattributed' : outcome,
+        reasonCode, ...progress, completeInspection,
+        ...(limit ? { limit } : {}), ...(fallback ? { fallback } : {}),
+    });
+    const envelopesFromLine = (value) => nativeEnvelopesFromLine(value, limits, (count) => {
+        retainedChildren += count;
+        if (retainedChildren > limits.maxRecords) {
+            throw new MuseWorkspaceLimitError('maxRecords', limits.maxRecords, retainedChildren);
+        }
+    });
     try {
-        if (Object.values(limits).some((limit) => !Number.isSafeInteger(limit) || limit <= 0)) {
+        if ([limits.maxRecords, limits.maxRecordBytes, limits.maxTotalBytes, limits.maxNestingDepth]
+            .some((limit) => !Number.isSafeInteger(limit) || limit <= 0)) {
             throw new SessionContractError('INVALID_ARGUMENT', 'Muse inspection limits must be positive safe integers');
         }
-        for await (const value of museWorkspaceScanLines({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, limits, progress)) {
-            const envelopes = nativeEnvelopesFromLine(value, limits, (count) => {
-                retainedChildren += count;
-                if (retainedChildren > limits.maxRecords) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Muse retained child inspection limit exceeded');
-                }
-            });
+        for await (const value of museWorkspaceScanLines(authorization, limits, progress)) {
+            const envelopes = envelopesFromLine(value);
             for (const envelope of envelopes) {
                 const candidate = workspaceEvidenceOf(envelope);
                 if (!candidate)
                     continue;
                 sawWorkspaceEvidence = true;
-                if (workspacePathEquals(candidate, workspacePath))
-                    return receipt('matched', null);
+                const matchKind = await matchSessionWorkspace(candidate, workspacePath);
+                if (matchKind)
+                    return { ...receipt('matched', null), matchKind };
             }
         }
         return sawWorkspaceEvidence
@@ -537,15 +565,47 @@ export async function inspectMuseNativeWorkspace(source, workspacePath, limitsIn
             : receipt('inconclusive', 'MUSE_WORKSPACE_EVIDENCE_ABSENT', true);
     }
     catch (error) {
-        return receipt('inconclusive', error instanceof SessionContractError
-            ? error.code : 'MUSE_SOURCE_UNREADABLE');
+        if (error instanceof MuseWorkspaceLimitError) {
+            limit = { name: error.limitName, value: error.limitValue };
+            fallback = 'bounded-tail';
+            const tailProgress = { recordsInspected: 0, bytesInspected: 0 };
+            const tailBytes = Math.min(MUSE_WORKSPACE_TAIL_BYTES, limits.maxTotalBytes);
+            retainedChildren = 0;
+            let matchKind;
+            try {
+                for await (const value of museWorkspaceScanLines(authorization, { ...limits, maxTotalBytes: tailBytes }, tailProgress, tailBytes)) {
+                    for (const envelope of envelopesFromLine(value)) {
+                        const candidate = workspaceEvidenceOf(envelope);
+                        if (!candidate)
+                            continue;
+                        matchKind = await matchSessionWorkspace(candidate, workspacePath);
+                        if (matchKind)
+                            break;
+                    }
+                    if (matchKind)
+                        break;
+                }
+            }
+            catch {
+                // Preserve the original limit receipt when the fallback cannot attribute.
+            }
+            progress.recordsInspected += tailProgress.recordsInspected;
+            progress.bytesInspected += tailProgress.bytesInspected;
+            if (matchKind)
+                return { ...receipt('matched', null), matchKind };
+        }
+        return {
+            ...receipt('inconclusive', error instanceof SessionContractError
+                ? error.code : 'MUSE_SOURCE_UNREADABLE'),
+            ...(error instanceof SessionContractError && error.detail ? { detail: error.detail } : {}),
+        };
     }
 }
 export async function museNativeSourceMatchesWorkspace(source, workspacePath) {
     const result = await inspectMuseNativeWorkspace(source, workspacePath);
     if (result.outcome === 'inconclusive') {
         const code = SessionErrorCodeSchema.safeParse(result.reasonCode);
-        throw new SessionContractError(code.success ? code.data : 'SCHEMA_DRIFT', `Muse workspace inspection inconclusive: ${result.reasonCode}`);
+        throw new SessionContractError(code.success ? code.data : 'SCHEMA_DRIFT', `Muse workspace inspection inconclusive: ${result.reasonCode}`, result.detail);
     }
     return result.outcome === 'matched';
 }
@@ -555,7 +615,7 @@ function nativeEnvelopesFromLine(value, limits, countChildren) {
     const retained = MuseRetainedFrameSchema.safeParse(value);
     if (!retained.success) {
         if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Muse inspection encountered a non-object native record');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Muse inspection encountered a non-object native record', schemaIssueDetail('<root>'));
         }
         // Native logs carry record kinds the envelope schema does not model (for
         // example runtime.session mode changes without payload.event.kind). They
@@ -567,7 +627,7 @@ function nativeEnvelopesFromLine(value, limits, countChildren) {
     const envelopes = [];
     for (const child of retained.data.children) {
         if (Buffer.byteLength(child.record_json) > limits.maxRecordBytes) {
-            throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Muse retained child inspection byte limit exceeded');
+            throw new MuseWorkspaceLimitError('maxRecordBytes', limits.maxRecordBytes, Buffer.byteLength(child.record_json));
         }
         const childEvent = recordEventFromEnvelope(parseMuseScanJson(child.record_json, limits.maxNestingDepth));
         if (childEvent)
@@ -593,9 +653,6 @@ function workspaceEvidenceOf(envelope) {
     }
     return null;
 }
-function workspacePathEquals(candidate, workspacePath) {
-    return resolve(candidate) === workspacePath;
-}
 function nativeSessionIdFromLocator(locator) {
     const parts = locator.replaceAll('\\', '/').split('/');
     const leaf = parts.at(-1);
@@ -742,7 +799,7 @@ function parseEventCursor(value) {
     if (value === undefined || value === '')
         return 0;
     if (!/^\d+$/.test(value))
-        throw new SessionContractError('SCHEMA_DRIFT', 'muse event cursor is invalid');
+        throw new SessionContractError('SCHEMA_DRIFT', 'muse event cursor is invalid', schemaIssueDetail('cursor'));
     return Number(value);
 }
 //# sourceMappingURL=muse.js.map

package/dist/src/sessions/adapters/omp.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 OMP_ADAPTER_VERSION = '1.0.0';
 export const OMP_SOURCE_SCHEMA_VERSION = '3.0.0';
 const Title = z.object({ type: z.literal('title'), v: z.literal(1), title: z.string(), source: z.enum(['auto', 'user']).optional(), updatedAt: z.string(), pad: z.string() });
@@ -30,7 +30,7 @@ export class OmpSessionAdapter {
         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', 'OMP discovery file limit exceeded');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'OMP discovery file limit exceeded', { limit: 'maxFiles', configured: this.maxFiles, observed: count });
                 yield { provider: 'omp', locator, locatorClass: 'omp-session-v3-jsonl' };
             }
         }
@@ -38,13 +38,23 @@ export class OmpSessionAdapter {
     async inspect(source) {
         let input;
         try {
-            input = await readBoundedJsonLines({ selectedPath: source.locator,
+            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[titleOffset(input.records[0]) ? 1 : 0]?.value);
+        let header;
+        let prefix = true;
+        for await (const line of input) {
+            if (prefix) {
+                prefix = false;
+                if (titleOffset(line))
+                    continue;
+            }
+            header ??= parseHeader(line.value);
+        }
+        header ??= parseHeader(undefined);
         if (input.incompleteTail)
             throw new SessionContractError('TRUNCATED_SOURCE', 'OMP session has a truncated JSONL tail');
         return { sourceSchemaVersion: `${header.version}.0.0`, consistency: 'complete', operationalState: 'available' };
@@ -63,13 +73,13 @@ export class OmpSessionAdapter {
         let prefix = true;
         const start = cursor?.value.replace(/^byte:/, '') ?? '0';
         if (!/^\d+$/.test(start))
-            throw new SessionContractError('SCHEMA_DRIFT', 'invalid OMP cursor');
+            throw new SessionContractError('SCHEMA_DRIFT', 'invalid OMP cursor', schemaIssueDetail('cursor'));
         let end = 0;
         const ids = new Set();
         for await (const line of input) {
             end = line.byteOffset + line.byteLength;
             if (Number(start) > line.byteOffset && Number(start) < end) {
-                throw new SessionContractError('SCHEMA_DRIFT', 'OMP cursor is not a record boundary');
+                throw new SessionContractError('SCHEMA_DRIFT', 'OMP cursor is not a record boundary', schemaIssueDetail('cursor'));
             }
             if (prefix) {
                 prefix = false;
@@ -83,7 +93,7 @@ export class OmpSessionAdapter {
             }
             const parsed = Entry.safeParse(line.value);
             if (!parsed.success)
-                throw new SessionContractError('MALFORMED_SOURCE', 'OMP session entry is malformed');
+                throw new SessionContractError('MALFORMED_SOURCE', 'OMP session entry is malformed', schemaRejectionDetail(parsed.error));
             const entry = parsed.data;
             if (ids.has(entry.id))
                 throw new SessionContractError('DUPLICATE_NATIVE_ID', 'OMP session contains a duplicate entry id');
@@ -107,9 +117,9 @@ export class OmpSessionAdapter {
                     nativeType: entry.type, parentId: entry.parentId, ...metadata(entry, message) } };
         }
         if (!sessionId)
-            throw new SessionContractError('MALFORMED_SOURCE', 'OMP session header is missing');
+            throw new SessionContractError('MALFORMED_SOURCE', 'OMP session header is missing', schemaIssueDetail('header'));
         if (Number(start) > end)
-            throw new SessionContractError('SCHEMA_DRIFT', 'OMP cursor exceeds source size');
+            throw new SessionContractError('SCHEMA_DRIFT', 'OMP cursor exceeds source size', schemaIssueDetail('cursor'));
         if (input.incompleteTail)
             throw new SessionContractError('TRUNCATED_SOURCE', 'OMP session has a truncated JSONL tail');
     }
@@ -125,7 +135,7 @@ const KNOWN = new Set(['message', 'thinking_level_change', 'model_change', 'comp
 function parseHeader(value) {
     const parsed = Header.safeParse(value);
     if (!parsed.success)
-        throw new SessionContractError('MALFORMED_SOURCE', 'OMP session header is malformed');
+        throw new SessionContractError('MALFORMED_SOURCE', 'OMP session header is malformed', schemaRejectionDetail(parsed.error));
     if (parsed.data.version !== 3)
         throw new SessionContractError('UNKNOWN_SCHEMA_MAJOR', `unsupported OMP session version: ${parsed.data.version}`);
     return parsed.data;
@@ -168,8 +178,12 @@ function normalizeAuthorizationError(error) {
 function titleOffset(line) {
     if (object(line?.value).type !== 'title')
         return 0;
-    if (!Title.safeParse(line?.value).success || line?.byteLength !== 256) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'OMP title slot is malformed');
+    const parsed = Title.safeParse(line?.value);
+    if (!parsed.success) {
+        throw new SessionContractError('MALFORMED_SOURCE', 'OMP title slot is malformed', schemaRejectionDetail(parsed.error));
+    }
+    if (line?.byteLength !== 256) {
+        throw new SessionContractError('MALFORMED_SOURCE', 'OMP title slot is malformed', schemaIssueDetail('title'));
     }
     return 256;
 }
@@ -198,6 +212,6 @@ export async function readOmpSessionHeader(source) {
         }
         return parseHeader(line.value);
     }
-    throw new SessionContractError('MALFORMED_SOURCE', 'OMP header is missing');
+    throw new SessionContractError('MALFORMED_SOURCE', 'OMP header is missing', schemaIssueDetail('header'));
 }
 //# sourceMappingURL=omp.js.map