@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/serve/worker-stdin-frame.mjs

@@ -0,0 +1,107 @@
+/**
+ * Conductor-side stdin framing for resolved worker invocations (#2911).
+ *
+ * `stdin: 'brief-json'` means the worker reads one JSON params document on
+ * stdin, built by the conductor from the brief file and closed at EOF. The
+ * brief stays the source of truth and is never copied into argv, so prompt
+ * text cannot surface in /proc/<pid>/cmdline, unit properties or argv logs.
+ * The document is the OpenHuman agent.chat params shape (`message`,
+ * `model_override`, `cwd`; tinyhumansai/openhuman@216ea32
+ * crates/openhuman-core/src/agent/schemas.rs:97-105), consumed by
+ * `call --params-stdin`, which reads stdin to EOF (core/cli.rs:445-468).
+ *
+ * Shared by the #2887 shell renderer (as a pipeline stage) and the attached
+ * one-shot launcher (written to the child's stdin pipe).
+ */
+import { open } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+
+export const WORKER_STDIN_FRAME_MAX_BRIEF_BYTES = 262144;
+export const WORKER_STDIN_FRAME_MAX_BYTES = 1048576;
+
+/** @returns {string} the exact JSON document delivered on stdin. */
+export function workerStdinDocument({ brief, model, cwd }) {
+  const text = Buffer.isBuffer(brief) ? new TextDecoder('utf-8', { fatal: true }).decode(brief) : brief;
+  if (typeof text !== 'string') throw new Error('brief-json framing requires brief text');
+  if (typeof model !== 'string' || !model || model.includes('\0')) throw new Error('brief-json framing requires an explicit model');
+  if (typeof cwd !== 'string' || !cwd.startsWith('/') || cwd.includes('\0')) throw new Error('brief-json framing requires an absolute workspace');
+  return JSON.stringify({ message: text, model_override: model, cwd });
+}
+
+/** Stdin bytes for a resolved invocation: null (closed), the raw brief, or the framed document. */
+export function workerStdinBytes(invocation, brief, adapter) {
+  if (invocation.stdin === 'closed') return null;
+  if (invocation.stdin === 'brief-text') return Buffer.isBuffer(brief) ? brief : Buffer.from(brief);
+  if (invocation.stdin === 'brief-json') {
+    return Buffer.from(workerStdinDocument({ brief, model: invocation.selected?.model, cwd: invocation.cwd }));
+  }
+  if (invocation.stdin === 'adapter-frame') {
+    if (typeof adapter?.buildWorkerStdinFrame !== 'function') throw new Error('Installed adapter stdin framer is required');
+    if (Buffer.byteLength(brief) > WORKER_STDIN_FRAME_MAX_BRIEF_BYTES) throw new Error('Brief exceeds the framing bound');
+    const frame = adapter.buildWorkerStdinFrame(brief);
+    if (typeof frame !== 'string' && !(frame instanceof Uint8Array)) throw new Error('Adapter stdin frame must be bytes or text');
+    if (Buffer.byteLength(frame) === 0) throw new Error('Adapter stdin frame must not be empty');
+    if (Buffer.byteLength(frame) > WORKER_STDIN_FRAME_MAX_BYTES) throw new Error('Adapter stdin frame exceeds byte bound');
+    return Buffer.from(frame);
+  }
+  throw new Error(`Unsupported worker stdin mode: ${invocation.stdin}`);
+}
+
+async function readBounded(filename) {
+  const handle = await open(filename, 'r');
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > WORKER_STDIN_FRAME_MAX_BRIEF_BYTES) throw new Error('Brief must be a bounded regular file');
+    const bytes = Buffer.alloc(WORKER_STDIN_FRAME_MAX_BRIEF_BYTES + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const { bytesRead } = await handle.read(bytes, length, bytes.length - length, null);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    if (length > WORKER_STDIN_FRAME_MAX_BRIEF_BYTES) throw new Error('Brief exceeds the framing bound');
+    return bytes.subarray(0, length);
+  } finally { await handle.close(); }
+}
+
+/** Bound host authority only; workspace is an execution scope, never a config source. */
+export async function recordedWorkerStdinBytes({ filename, workspace, cli, adapterId, scopeDigest, briefDigest,
+  storePath, storeDigest, policy }) {
+  if (!filename?.startsWith('/') || !storePath?.startsWith('/')
+    || !/^sha256:[a-f0-9]{64}$/.test(storeDigest ?? '')) throw new Error('Invalid adapter stdin framing request');
+  const { loadRecordedWorkerInstallations } = await import('../models/worker-installation.mjs');
+  const { loadProviderModelCapabilities } = await import('../models/provider-policy.js');
+  const { drivers } = await loadRecordedWorkerInstallations({ registry: loadProviderModelCapabilities(),
+    cwd: workspace, policy, storePath, storeDigest });
+  const driver = drivers[cli];
+  if (!driver || driver.qualification.adapterId !== adapterId
+    || driver.qualification.adapter.invocation.stdin !== 'adapter-frame'
+    || driver.qualification.installation?.evidence?.scopeDigest !== scopeDigest) throw new Error('Adapter stdin binding changed');
+  const brief = await readBounded(filename);
+  if (`sha256:${createHash('sha256').update(brief).digest('hex')}` !== briefDigest) throw new Error('Adapter stdin brief changed');
+  return workerStdinBytes({ stdin: 'adapter-frame' }, brief, driver);
+}
+
+// Pipeline stage: `worker-stdin-frame.mjs BRIEF_PATH MODEL CWD`. Only the
+// brief path, never its content, appears on this command line.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const [briefPath, model, cwd] = process.argv.slice(2);
+  try {
+    if (briefPath === '--adapter-frame') {
+      const [filename, workspace, cli, adapterId, scopeDigest, briefDigest, storePath, storeDigest, policyJson] = process.argv.slice(3);
+      if (process.argv.length !== 12) throw new Error('Invalid adapter stdin framing request');
+      // Reuse the recorded-installation loader; no module path or code supplied
+      // by a brief is ever imported. The conductor binds store bytes and policy;
+      // never resolve configuration from the worker-writable workspace.
+      process.stdout.write(await recordedWorkerStdinBytes({ filename, workspace, cli, adapterId, scopeDigest, briefDigest,
+        storePath, storeDigest, policy: JSON.parse(policyJson) ?? undefined }));
+    } else {
+      if (process.argv.length !== 5 || !briefPath?.startsWith('/')) throw new Error('usage: worker-stdin-frame.mjs BRIEF_PATH MODEL CWD');
+      process.stdout.write(workerStdinDocument({ brief: await readBounded(briefPath), model, cwd }));
+    }
+  } catch (error) {
+    process.stderr.write(`worker-stdin-frame: ${error?.message ?? error}\n`);
+    process.exitCode = 2;
+  }
+}

package/dist/src/sessions/adapter-registry.js

@@ -0,0 +1,49 @@
+import { resolveImportLimits } from './import-limits.js';
+import { ClaudeSessionAdapter } from './adapters/claude.js';
+import { CodexSessionAdapter } from './adapters/codex.js';
+import { CopilotSessionAdapter } from './adapters/copilot.js';
+import { CursorSessionAdapter } from './adapters/cursor.js';
+import { FactorySessionAdapter } from './adapters/factory.js';
+import { HermesSessionAdapter } from './adapters/hermes.js';
+import { OpenCodeSessionAdapter } from './adapters/opencode.js';
+import { OpenClawSessionAdapter } from './adapters/openclaw.js';
+import { OpenHumanSessionAdapter } from './adapters/openhuman.js';
+import { GrokbotSessionAdapter } from './adapters/grokbot.js';
+import { GrokBuildSessionAdapter } from './adapters/grok-build.js';
+import { MuseSessionAdapter } from './adapters/muse.js';
+import { PiSessionAdapter } from './adapters/pi.js';
+import { OmpSessionAdapter } from './adapters/omp.js';
+import { DeepSeekHarnessSessionAdapter } from './adapters/deepseek-harness.js';
+import { WarpSessionAdapter } from './adapters/warp.js';
+import { DevinDesktopSessionAdapter } from './adapters/windsurf.js';
+import { GenericSessionInterchangeAdapter } from './adapters/generic.js';
+import { SessionSourceAdapterRegistry } from './discovery.js';
+export function createSessionAdapterRegistry(limits) {
+    limits = { ...resolveImportLimits(undefined, {
+            maxRecordBytes: limits?.maxRecordBytes, maxSourceBytes: limits?.maxTotalBytes,
+        }), ...limits };
+    const registry = new SessionSourceAdapterRegistry();
+    for (const adapter of [
+        new ClaudeSessionAdapter(limits),
+        new CodexSessionAdapter(limits),
+        new CopilotSessionAdapter(limits),
+        new CursorSessionAdapter(limits),
+        new FactorySessionAdapter(limits),
+        new HermesSessionAdapter(limits),
+        new OpenCodeSessionAdapter(limits),
+        new OpenClawSessionAdapter(limits),
+        new OpenHumanSessionAdapter(limits),
+        new GrokbotSessionAdapter(limits),
+        new GrokBuildSessionAdapter(limits),
+        new MuseSessionAdapter(limits),
+        new PiSessionAdapter(limits),
+        new OmpSessionAdapter(limits),
+        new DeepSeekHarnessSessionAdapter(limits),
+        new WarpSessionAdapter(limits),
+        new DevinDesktopSessionAdapter(limits),
+        new GenericSessionInterchangeAdapter(limits),
+    ])
+        registry.register(adapter);
+    return registry;
+}
+//# sourceMappingURL=adapter-registry.js.map

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

@@ -1,9 +1,9 @@
 import { opendir } from 'node:fs/promises';
 import { basename, extname, resolve } from 'node:path';
 import { z } from 'zod';
-import { SessionContractError, assertSupportedSchemaMajor, sha256, } from '../contracts.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, sha256, } from '../contracts.js';
 import { redactSourceLocator } from '../discovery.js';
-import { readBoundedJson, readBoundedJsonLines, streamBoundedJsonLines, } from '../readers.js';
+import { readBoundedJson, streamBoundedJsonLines, } from '../readers.js';
 export const CLAUDE_ADAPTER_VERSION = '1.1.0';
 export const CLAUDE_TRANSCRIPT_SCHEMA_VERSION = '1.0.0';
 /** AIWG's own understanding of the layout it supports; Claude web/account
@@ -101,7 +101,7 @@ export class ClaudeSessionAdapter {
             for await (const locator of discoverJsonl(resolve(root), this.discoveryLimits.maxDepth)) {
                 emitted += 1;
                 if (emitted > this.discoveryLimits.maxFiles) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Claude source discovery exceeded the authorized file limit');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Claude source discovery exceeded the authorized file limit', { limit: 'maxFiles', configured: this.discoveryLimits.maxFiles, observed: emitted });
                 }
                 yield {
                     provider: 'claude',
@@ -112,12 +112,19 @@ export class ClaudeSessionAdapter {
         }
     }
     async inspect(source) {
-        const parsed = await this.readSource(source);
-        return {
-            sourceSchemaVersion: parsed.schemaVersion,
-            consistency: parsed.consistency,
-            operationalState: 'available',
-        };
+        if (source.locatorClass === 'claude-web-export-json') {
+            const parsed = await this.readWebExportSource(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) {
         if (source.locatorClass === 'claude-web-export-json') {
@@ -127,69 +134,57 @@ export class ClaudeSessionAdapter {
                 yield record;
             return;
         }
+        yield* this.readSource(source, cursor);
+    }
+    async *readSource(source, cursor) {
         const start = parseRecordCursor(cursor?.value);
         const input = await streamBoundedJsonLines({
             selectedPath: source.locator,
             allowedRoots: source.authorizedScope.allowedRoots,
         }, { consistency: 'provisional', limits: this.limits });
-        const hookSource = isHookLocator(source.locator);
+        let hookSource = isHookLocator(source.locator) ? true : undefined;
         let outputIndex = 0;
         let sawRecord = false;
+        let complete = false;
         let schemaVersion = null;
         for await (const line of input) {
             sawRecord = true;
-            const value = line.value;
+            const value = line.value && typeof line.value === 'object'
+                ? line.value : {};
             const currentSchema = typeof value.schemaVersion === 'string'
                 ? value.schemaVersion : CLAUDE_TRANSCRIPT_SCHEMA_VERSION;
             if (schemaVersion && currentSchema !== schemaVersion) {
-                throw new SessionContractError('SCHEMA_DRIFT', 'Claude source declares mixed schema versions');
+                throw new SessionContractError('SCHEMA_DRIFT', 'Claude source declares mixed schema versions', schemaIssueDetail('schemaVersion'));
             }
             schemaVersion = currentSchema;
             assertSupportedSchemaMajor(schemaVersion);
-            const normalized = hookSource || isHookRecord(line.value)
-                ? normalizeHooks([line]).records
-                : normalizeTranscript([line], source.locator).records;
-            for (const record of normalized) {
+            hookSource ??= isHookRecord(line.value);
+            const normalized = hookSource
+                ? normalizeHooks([line])
+                : normalizeTranscript([line], source.locator);
+            complete ||= normalized.complete;
+            for (const record of normalized.records) {
                 if (outputIndex++ >= start)
                     yield record;
             }
         }
         if (!sawRecord && !input.incompleteTail) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Claude JSONL source is empty');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Claude JSONL source is empty', schemaIssueDetail('<root>'));
         }
-    }
-    async readSource(source) {
-        if (source.locatorClass === 'claude-web-export-json') {
-            return this.readWebExportSource(source);
-        }
-        const result = await readBoundedJsonLines({
-            selectedPath: source.locator,
-            allowedRoots: source.authorizedScope.allowedRoots,
-        }, { consistency: 'provisional', limits: this.limits });
-        if (result.records.length === 0 && !result.incompleteTail) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Claude JSONL source is empty');
-        }
-        const hookSource = isHookLocator(source.locator)
-            || result.records.some((record) => isHookRecord(record.value));
-        const normalized = hookSource
-            ? normalizeHooks(result.records)
-            : normalizeTranscript(result.records, source.locator);
-        const schemaVersion = declaredSchemaVersion(result.records);
-        assertSupportedSchemaMajor(schemaVersion);
         return {
-            records: normalized.records,
-            schemaVersion,
-            consistency: normalized.complete ? 'complete' : 'provisional',
+            sourceSchemaVersion: schemaVersion ?? CLAUDE_TRANSCRIPT_SCHEMA_VERSION,
+            consistency: complete ? 'complete' : 'provisional',
+            operationalState: 'available',
         };
     }
     async readWebExportSource(source) {
         const { value } = await readBoundedJson({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, this.limits);
         const parsed = ClaudeWebExportSchema.safeParse(value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Claude web/account export is not a recognized conversations.json layout');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Claude web/account export is not a recognized conversations.json layout', schemaRejectionDetail(parsed.error));
         }
         if (parsed.data.length === 0) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Claude web/account export is empty');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Claude web/account export is empty', schemaIssueDetail('<root>'));
         }
         return {
             records: normalizeWebExport(parsed.data),
@@ -263,7 +258,7 @@ function normalizeTranscript(records, locator) {
     for (const record of records) {
         const parsed = ClaudeRecordSchema.safeParse(record.value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Claude transcript record is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Claude transcript record is malformed', schemaRejectionDetail(parsed.error));
         }
         const value = parsed.data;
         const embeddedSessionId = value.sessionId ?? value.session_id;
@@ -297,7 +292,7 @@ function normalizeHooks(records) {
     for (const record of records) {
         const parsed = ClaudeHookSchema.safeParse(record.value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Claude lifecycle hook record is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Claude lifecycle hook record is malformed', schemaRejectionDetail(parsed.error));
         }
         const hook = parsed.data;
         complete ||= hook.hook_event_name === 'SessionEnd';
@@ -464,21 +459,11 @@ async function* discoverJsonl(root, maxDepth) {
             pending.push({ path, depth: current.depth + 1 });
     }
 }
-function declaredSchemaVersion(records) {
-    const declared = records
-        .map((record) => {
-        if (!record.value || typeof record.value !== 'object' || Array.isArray(record.value))
-            return undefined;
-        return record.value.schemaVersion;
-    })
-        .find((value) => typeof value === 'string');
-    return declared ?? CLAUDE_TRANSCRIPT_SCHEMA_VERSION;
-}
 function parseRecordCursor(value) {
     if (value === undefined || value === '')
         return 0;
     if (!/^\d+$/.test(value))
-        throw new SessionContractError('SCHEMA_DRIFT', 'Claude record cursor is invalid');
+        throw new SessionContractError('SCHEMA_DRIFT', 'Claude record cursor is invalid', schemaIssueDetail('cursor'));
     return Number(value);
 }
 function hookNativeId(hook, sequence) {

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,62 @@ 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 spawn = asObject(asObject(asObject(payload.source).subagent).thread_spawn);
+            const lineage = 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));
+            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;
+}
+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 +365,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 +374,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 +529,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);
 }