@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/rules/rule-frontmatter.schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aiwg.io/schemas/rules/rule-frontmatter.v1.schema.json",
+  "title": "Rule activation frontmatter",
+  "description": "ADR rule activation contract. Other existing discovery metadata is preserved. Missing activation is permitted only by the migration parser, which warns and infers tier delivery.",
+  "type": "object",
+  "required": [
+    "activation"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "activation": {
+      "type": "string",
+      "enum": [
+        "kernel",
+        "summary",
+        "bound",
+        "paths",
+        "on-demand"
+      ]
+    },
+    "summary": {
+      "type": "string",
+      "pattern": "^[^\\r\\n\\u0085\\u2028\\u2029]*\\S[^\\r\\n\\u0085\\u2028\\u2029]*$",
+      "description": "A nonempty single-line imperative, <=240 Unicode code points after trimming. Imperative mood is reviewed by authors.",
+      "allOf": [
+        {
+          "pattern": "^\\s*\\S(?:[^\\r\\n\\u0085\\u2028\\u2029]{0,238}\\S)?\\s*$"
+        }
+      ]
+    },
+    "bound_to": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*(?:^|/)\\.\\.?(/|$))[A-Za-z0-9_][A-Za-z0-9_.:-]*(?:/[A-Za-z0-9_][A-Za-z0-9_.:-]*)*$"
+          }
+        },
+        "agents": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*(?:^|/)\\.\\.?(/|$))[A-Za-z0-9_][A-Za-z0-9_.:-]*(?:/[A-Za-z0-9_][A-Za-z0-9_.:-]*)*$"
+          }
+        },
+        "flows": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*(?:^|/)\\.\\.?(/|$))[A-Za-z0-9_][A-Za-z0-9_.:-]*(?:/[A-Za-z0-9_][A-Za-z0-9_.:-]*)*$"
+          }
+        }
+      }
+    },
+    "paths": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^(?![A-Za-z]:)(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$))(?=.*\\S)[^\\r\\n]+$"
+      }
+    },
+    "enforcedBy": {
+      "description": "Opaque reserved metadata for #2839. Has no activation or runtime enforcement effect."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "activation": {
+            "enum": [
+              "summary",
+              "bound",
+              "paths"
+            ]
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "summary"
+        ],
+        "properties": {
+          "summary": {}
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "activation": {
+            "enum": [
+              "kernel",
+              "on-demand"
+            ]
+          }
+        }
+      },
+      "then": {
+        "not": {
+          "required": [
+            "bound_to"
+          ],
+          "properties": {
+            "bound_to": {}
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "activation": {
+            "const": "paths"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "paths"
+        ],
+        "properties": {
+          "paths": {}
+        }
+      },
+      "else": {
+        "not": {
+          "required": [
+            "paths"
+          ],
+          "properties": {
+            "paths": {}
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "activation": {
+            "const": "bound"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "bound_to"
+        ],
+        "properties": {
+          "bound_to": {
+            "type": "object",
+            "anyOf": [
+              {
+                "required": [
+                  "skills"
+                ],
+                "properties": {
+                  "skills": {
+                    "type": "array",
+                    "minItems": 1
+                  }
+                }
+              },
+              {
+                "required": [
+                  "agents"
+                ],
+                "properties": {
+                  "agents": {
+                    "type": "array",
+                    "minItems": 1
+                  }
+                }
+              },
+              {
+                "required": [
+                  "flows"
+                ],
+                "properties": {
+                  "flows": {
+                    "type": "array",
+                    "minItems": 1
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/dist/src/serve/mission-conductor.js

@@ -25,8 +25,6 @@
 import { routeMission } from './agent-router.js';
 import { StackAdapterRegistry } from './stack-adapters.js';
 import { assertMissionWorkerHandoff } from '../mission-protocol/codecs.js';
-const defaultRunWorker = () => ({ output: undefined, cost: 0 });
-const defaultScore = (r) => (r.output ? r.output.length : 0);
 /**
  * The cross-stack Mission conductor. Decomposes a Mission into worker cycles,
  * dispatches each to an executor of the chosen runtime via `routeMission`, and
@@ -36,10 +34,12 @@ export class MissionConductor {
     adapters;
     runWorker;
     scoreOutput;
+    scorerId;
     constructor(opts = {}) {
         this.adapters = opts.adapters ?? new StackAdapterRegistry();
-        this.runWorker = opts.runWorker ?? defaultRunWorker;
-        this.scoreOutput = opts.scoreOutput ?? defaultScore;
+        this.runWorker = opts.runWorker;
+        this.scoreOutput = opts.scoreOutput;
+        this.scorerId = opts.scoreOutput ? (opts.scorerId ?? 'custom') : null;
     }
     /**
      * Conduct a Mission across the given executor pool. Returns the ledger.
@@ -69,6 +69,8 @@ export class MissionConductor {
             missionId: plan.missionId,
             goal: plan.goal,
             completionCriterion: plan.completionCriterion,
+            executionMode: this.runWorker ? 'executed' : 'plan-only',
+            scorerId: this.scorerId,
             activityLog: [],
             cycles: [],
             totalCost: 0,
@@ -77,6 +79,7 @@ export class MissionConductor {
             ...(plan.graph ? { graph: structuredClone(plan.graph) } : {}),
         };
         ledger.activityLog.push(`mission ${plan.missionId} start — goal: ${plan.goal} — ${plan.cycles.length} cycle(s)` +
+            ` — mode: ${ledger.executionMode}, scorer: ${ledger.scorerId ?? '(none)'}` +
             (resumeFrom ? ` (resume: ${carried.size} carried)` : ''));
         for (const cycle of plan.cycles) {
             const graph = plan.graph && cycle.graph ? {
@@ -134,6 +137,20 @@ export class MissionConductor {
             const executor = routing.selected.executor;
             const invocation = adapter.invoke(cycle.prompt, graph);
             ledger.activityLog.push(`cycle ${cycle.id} → executor ${executor.name} (${executor.executorId}) on ${cycle.runtime}: ${invocation.describe}`);
+            if (!this.runWorker) {
+                ledger.cycles.push({
+                    cycleId: cycle.id,
+                    runtime: cycle.runtime,
+                    primitive: adapter.primitive,
+                    executorId: executor.executorId,
+                    routed: true,
+                    reason: 'plan-only: worker not configured; execution pending',
+                    cost: 0,
+                    ...(graph ? { graph } : {}),
+                });
+                ledger.activityLog.push(`cycle ${cycle.id} PLANNED on ${cycle.runtime} — execution pending`);
+                continue;
+            }
             let output;
             let cost = 0;
             try {
@@ -173,23 +190,32 @@ export class MissionConductor {
             ledger.totalCost += cost;
             ledger.activityLog.push(`cycle ${cycle.id} done on ${cycle.runtime} (cost ${cost})`);
         }
-        // Pending = cycles neither completed nor failed (none, here — full pass).
+        // Planned cycles remain pending until a worker executes them.
         const accounted = new Set([...ledger.checkpoint.completed, ...ledger.checkpoint.failed]);
         ledger.checkpoint.pending = plan.cycles.map((c) => c.id).filter((id) => !accounted.has(id));
         // Cross-stack aggregation: distinct runtimes that actually ran a worker.
         ledger.runtimesUsed = [
-            ...new Set(ledger.cycles.filter((c) => c.routed).map((c) => c.runtime)),
+            ...new Set(ledger.cycles.filter((c) => c.routed && accounted.has(c.cycleId)).map((c) => c.runtime)),
         ];
         // Best-output selection (REF-015) — conductor-side, across stacks.
         let best;
-        for (const c of ledger.cycles) {
-            if (!c.output)
-                continue;
-            const score = this.scoreOutput(c);
-            if (!best || score > best.score) {
-                best = { cycleId: c.cycleId, runtime: c.runtime, output: c.output, score };
+        if (this.scoreOutput) {
+            for (const c of ledger.cycles) {
+                if (c.output === undefined)
+                    continue;
+                const score = this.scoreOutput(c);
+                if (!Number.isFinite(score)) {
+                    ledger.activityLog.push(`cycle ${c.cycleId} UNSCORED — scorer ${this.scorerId} returned a non-finite score`);
+                    continue;
+                }
+                if (!best || score > best.score) {
+                    best = { cycleId: c.cycleId, runtime: c.runtime, output: c.output, score };
+                }
             }
         }
+        else {
+            ledger.activityLog.push('best-output unavailable: no scorer configured');
+        }
         ledger.bestOutput = best;
         ledger.activityLog.push(`mission ${plan.missionId} end — completed ${ledger.checkpoint.completed.length}, ` +
             `failed ${ledger.checkpoint.failed.length}, runtimes [${ledger.runtimesUsed.join(', ')}], ` +

package/dist/src/serve/worker-invocation.js

@@ -8,7 +8,7 @@ import { resolveWorkerPlan } from '../models/resolver.js';
 import { workerConfigDigest, validateWorkerHealthConfig } from '../config/aiwg-config.js';
 import { assertValidWorkerPayload } from '../mission-protocol/codecs.js';
 import { qualificationDigest } from '../models/qualification-digest.mjs';
-import { qualifyWorkerInvocationProfile, assertWorkerSelectionAllowed, requiredWorkerControls, requiresWorkerExternalBoundary, isCanonicalWorkerModelKey, assertWorkerHealthQualification, WorkerPolicyError, DEFAULT_WORKER_SELECTION } from '../models/provider-policy.js';
+import { qualifyWorkerInvocationProfile, isOperatorQualifiedWorkerAdapter, assertOperatorWorkerNativeArgv, assertWorkerSelectionAllowed, requiredWorkerControls, requiresWorkerExternalBoundary, isCanonicalWorkerModelKey, assertWorkerHealthQualification, WorkerPolicyError, DEFAULT_WORKER_SELECTION } from '../models/provider-policy.js';
 /** Frozen per-attempt windows; parent/transport ceilings include time already spent. */
 export function resolveWorkerEffectiveHealth(config, input) {
     const roleDefaults = { efficiency: 1, coding: 1, reasoning: 2 };
@@ -149,6 +149,7 @@ export async function prepareWorkerInvocation(invocation, qualification) {
         throw new Error('Worker invocation input/output paths must be distinct');
     }
     if (result.transport === 'shell') {
+        assertOperatorWorkerNativeArgv(qualification.adapter, result.argv, result.selected, qualification.permissions);
         if (!absolute(result.argv[0]) || result.argv[0].includes('=') || result.argv.some(value => value.includes('\0'))) {
             throw new WorkerPolicyError('OG_CONFIG_REFERENCE', 'Worker invocation requires an absolute binary without equals and NUL-free argv');
         }
@@ -230,8 +231,15 @@ export function parseWorkerCommandArgs(args) {
         workdir: 'workdir', 'final-output': 'final_output', transport: 'transport', format: 'format' };
     const result = {};
     let json = false;
+    let premiumAuthorized = false;
     for (let i = 0; i < args.length; i++) {
         const token = args[i];
+        if (token === '--authorize-premium') {
+            if (premiumAuthorized)
+                throw new Error('Duplicate --authorize-premium');
+            premiumAuthorized = true;
+            continue;
+        }
         if (token === '--json') {
             if (json)
                 throw new Error('Duplicate --json');
@@ -266,7 +274,7 @@ export function parseWorkerCommandArgs(args) {
         throw new Error('Unsupported transport');
     if (result.format && !['shell', 'json'].includes(result.format))
         throw new Error('Unsupported renderer; use POSIX shell or JSON');
-    return result;
+    return { ...result, ...(premiumAuthorized ? { authority: { premiumAuthorized: true, maxAutoTier: 3 } } : {}) };
 }
 const bytesDigest = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
 export async function inspectWorkerPath(filename, kind) {
@@ -324,6 +332,14 @@ async function readBrief(filename) {
         await handle.close();
     }
 }
+/** Structured root-check failure; only these explicit path details are public. */
+export class WorkerPathScopeError extends WorkerPolicyError {
+    pointer;
+    constructor(key, filename, roots) {
+        super('OG_CONFIG_REFERENCE', `${filename} must be inside the worker-writable ${roots.length === 1 ? 'root' : 'roots'} ${roots.join(', ')}.`);
+        this.pointer = key === 'briefPath' ? '/request/brief' : '/request/finalOutput';
+    }
+}
 /** Re-resolve saved JSON through the same trusted owners; saved argv is never authority. */
 export async function revalidateWorkerInvocationPlan(saved, snapshot, drivers, now = new Date().toISOString()) {
     if (!saved.request || saved.mode !== 'direct' || saved.status !== 'eligible'
@@ -350,6 +366,8 @@ export async function resolveWorkerInvocation(snapshot, request, drivers, now =
     let failureCode = 'OG_CONFIG_REFERENCE';
     let plan;
     try {
+        if (!path.isAbsolute(request.brief))
+            throw new WorkerPolicyError('OG_CONFIG_REFERENCE', '--brief must be an absolute path; relative paths are not resolved against cwd or --workdir.');
         const bytes = await readBrief(request.brief);
         const briefDigest = bytes === null ? null : bytesDigest(bytes);
         if (expected && expected.briefDigest !== briefDigest)
@@ -364,7 +382,7 @@ export async function resolveWorkerInvocation(snapshot, request, drivers, now =
             }
         }
         plan = resolveWorkerPlan(snapshot, { role: request.role, taskClass: request.task, group: request.group,
-            transport: request.transport, now, expectedDigests: expected?.digests,
+            transport: request.transport, authority: request.authority, now, expectedDigests: expected?.digests,
             ...(brief ? { dataClass: brief.intent.dataClass, member: brief.intent.pins.member,
                 model: brief.intent.pins.model, effort: brief.intent.pins.effort?.value, ceilings: {
                     ...brief.intent.limits, costUsd: brief.intent.limits.costUsd ?? undefined
@@ -442,7 +460,7 @@ export async function resolveWorkerInvocation(snapshot, request, drivers, now =
                 throw new Error('MCP server/tool is not registered and allowed by the current MCP profile');
             }
         }
-        const controls = requiredWorkerControls({ policy: plan.policy, permissions: tuple.permissions, effort: tuple.effort,
+        const controls = isOperatorQualifiedWorkerAdapter(adapter) ? (healthConfig?.requireStepCap ? ['stepCap'] : []) : requiredWorkerControls({ policy: plan.policy, permissions: tuple.permissions, effort: tuple.effort,
             requiredControls: healthConfig?.requireStepCap ? ['stepCap'] : [] });
         pointer = `/parallelism/clis/${tuple.cli}/invocationProfile`;
         failureCode = 'OG_ADAPTER_UNQUALIFIED';
@@ -469,9 +487,8 @@ export async function resolveWorkerInvocation(snapshot, request, drivers, now =
             readiness: bytes !== null && workspaceExists && outputParentsExist ? 'launchable' : 'preparatory', briefDigest,
             limits, maxOutputBytes: adapter.invocation.maxOutputBytes ?? 10485760,
             effectiveCaps: tuple.effectiveMaxParallel === null ? {} : { parallel: tuple.effectiveMaxParallel },
-            controlEvidence: controls.map(name => profile.controls[name].evidence),
-            health: effectiveHealth,
-        };
+            controlEvidence: isOperatorQualifiedWorkerAdapter(adapter) ? [adapter.qualification.evidenceRef, ...controls.map(name => profile.controls[name].evidence)] : controls.map(name => profile.controls[name].evidence),
+            health: effectiveHealth, };
         const invocationQualification = { ...qualification, now: Date.parse(now),
             policy: plan.policy, permissions: tuple.permissions, role: request.role, modelObservation: observation,
             expectedDigests: { policyDigest, catalogDigest: plan.digests.catalogDigest, profileDigest: plan.digests.profileDigest, briefDigest },
@@ -520,8 +537,10 @@ export async function resolveWorkerInvocation(snapshot, request, drivers, now =
         return plan;
     }
 }
-/** Public diagnostics contain fixed summaries, never filesystem/probe/provider error text. */
+/** Public diagnostics contain fixed summaries or explicit typed request-path details. */
 export function workerInvocationDiagnostic(error, pointer, fallback = 'OG_CONFIG_REFERENCE') {
+    if (error instanceof WorkerPathScopeError)
+        return { code: error.code, pointer: error.pointer, message: error.message };
     const code = error instanceof WorkerPolicyError ? error.code : fallback;
     const messages = {
         OG_CONFIG_REFERENCE: 'Invalid request or configuration reference; check the paths and settings.',
@@ -529,10 +548,11 @@ export function workerInvocationDiagnostic(error, pointer, fallback = 'OG_CONFIG
         OG_MODEL_UNAPPROVED: 'The selected model lacks current approved observation evidence.',
         OG_EFFORT_DENIED: 'The selected effort is denied by the resolved worker policy.',
         OG_DATA_POLICY: 'The selected model does not satisfy the resolved data policy.',
-        OG_ADAPTER_UNQUALIFIED: 'The installation or invocation could not be revalidated. Use inspectWorkerInstallation, qualifyWorkerInstallation and recordWorkerInstallation from the trusted installation owner to qualify this workspace.',
+        OG_ADAPTER_UNQUALIFIED: 'The installation or invocation could not be revalidated. Run aiwg doctor --probe-workers --qualify to qualify this workspace.',
         OG_POLICY_RELAXATION: 'The request would relax the resolved worker policy.',
         OG_BUDGET_UNMEASURABLE: 'The requested worker budget cannot be enforced.',
     };
-    return { code, pointer, message: messages[code] };
+    return { code, pointer, message: error instanceof WorkerPolicyError && error.message === '--brief must be an absolute path; relative paths are not resolved against cwd or --workdir.'
+            ? error.message : messages[code] };
 }
 //# sourceMappingURL=worker-invocation.js.map

package/dist/src/serve/worker-stdin-frame.d.mts

@@ -0,0 +1,10 @@
+/** Conductor-side stdin framing shared by the shell renderer and the one-shot launcher. */
+export const WORKER_STDIN_FRAME_MAX_BRIEF_BYTES: number;
+export const WORKER_STDIN_FRAME_MAX_BYTES: number;
+export function recordedWorkerStdinBytes(input: {
+  filename: string; workspace: string; cli: string; adapterId: string; scopeDigest: string; briefDigest: string;
+  storePath: string; storeDigest: string; policy?: import('../models/types.js').WorkerSelectionPolicy;
+}): Promise<Buffer | null>;
+export function workerStdinDocument(input: { brief: string | Buffer; model: string; cwd: string }): string;
+export function workerStdinBytes(invocation: { stdin: 'closed' | 'brief-text' | 'brief-json' | 'adapter-frame'; cwd?: string;
+  selected?: { model?: string } }, brief: string | Buffer, adapter?: { buildWorkerStdinFrame?(brief: string | Buffer): string | Uint8Array }): Buffer | null;

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

@@ -1,3 +1,4 @@
+import { resolveImportLimits } from './import-limits.js';
 import { ClaudeSessionAdapter } from './adapters/claude.js';
 import { CodexSessionAdapter } from './adapters/codex.js';
 import { CopilotSessionAdapter } from './adapters/copilot.js';
@@ -17,27 +18,30 @@ 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() {
+export function createSessionAdapterRegistry(limits) {
+    limits = { ...resolveImportLimits(undefined, {
+            maxRecordBytes: limits?.maxRecordBytes, maxSourceBytes: limits?.maxTotalBytes,
+        }), ...limits };
     const registry = new SessionSourceAdapterRegistry();
     for (const adapter of [
-        new ClaudeSessionAdapter(),
-        new CodexSessionAdapter(),
-        new CopilotSessionAdapter(),
-        new CursorSessionAdapter(),
-        new FactorySessionAdapter(),
-        new HermesSessionAdapter(),
-        new OpenCodeSessionAdapter(),
-        new OpenClawSessionAdapter(),
-        new OpenHumanSessionAdapter(),
-        new GrokbotSessionAdapter(),
-        new GrokBuildSessionAdapter(),
-        new MuseSessionAdapter(),
-        new PiSessionAdapter(),
-        new OmpSessionAdapter(),
-        new DeepSeekHarnessSessionAdapter(),
-        new WarpSessionAdapter(),
-        new DevinDesktopSessionAdapter(),
-        new GenericSessionInterchangeAdapter(),
+        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;

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) {