@margay/ccl-core 1.5.0-alpha.4 → 1.5.1-alpha.3

package/dist/sdk/query.js

@@ -1,3 +1,7 @@
+import { randomUUID } from 'node:crypto';
+import { approvalInputDigest, pendingApprovalIdentity, pendingApprovalSuspensionResponseSchema, pendingApprovalIdentitySchema, pendingApprovalConflictSchema, samePendingApproval } from './pendingApprovalIdentity.js';
+import { QueryLifecycleObservationSchema } from './queryLifecycleTypes.js';
+import { readOperationReference } from './operations/reference.js';
 import { sanitizeRequestProgress } from './requestProgress.js';
 /**
  * ccl-sdk query() — the programmatic headless entry (issue P0-1) with the
@@ -30,6 +34,7 @@ import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, statSync, sym
 import { createHash } from 'crypto';
 import { describeError, errorDetailsList, sanitizeErrorEnvelope, sanitizeErrorText, sanitizeRecoveryDiagnostic, sanitizeRecoveryOutcome } from './errorDiagnostics.js';
 import { interactionResponseSchema } from './interactionResponseSchema.js';
+import { hostCancellationSchema } from './cancellation.js';
 import { tmpdir } from 'os';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -73,8 +78,17 @@ export function buildCliArgs(options) {
         args.push('--max-turns', String(options.maxTurns));
     if (options.maxBudgetUsd !== undefined)
         args.push('--max-budget-usd', String(options.maxBudgetUsd));
-    if (options.permissionMode)
-        args.push('--permission-mode', options.permissionMode);
+    const permissionMode = options.permissionDelegation?.mode ?? options.permissionMode;
+    if (permissionMode)
+        args.push('--permission-mode', permissionMode);
+    if (options.permissionCallbackMode)
+        args.push('--permission-callback-mode', options.permissionCallbackMode);
+    if (options.permissionDelegation)
+        args.push('--require-permission-delegation');
+    if (options.pendingDecision)
+        args.push('--resume-pending-approval');
+    if (options.pendingDecision?.expectedApproval)
+        args.push('--strict-pending-resume');
     for (const dir of options.pluginDirs ?? [])
         args.push('--plugin-dir', dir);
     if (options.addDirs?.length)
@@ -183,6 +197,7 @@ export async function decideFailClosed(callback, toolName, input, context, timeo
     const deny = (message, failClosedReason) => ({
         kind: 'decision',
         decision: { behavior: 'deny', message, toolUseID: context.toolUseId,
+            cancellation: { origin: 'host', reason: timedOut ? 'timeout' : 'callback_error' },
             ...(toolName === 'AskUserQuestion' ? { interaction: { outcome: timedOut ? 'timed_out' : 'interaction_unavailable' } } : {}),
         },
         failClosedReason,
@@ -226,6 +241,10 @@ export async function decideFailClosed(callback, toolName, input, context, timeo
             };
         }
         case 'deny': {
+            const cancellation = hostCancellationSchema.safeParse(raw.cancellation);
+            if (raw.cancellation !== undefined && !cancellation.success) {
+                return deny('Cancellation provenance was invalid; no user choice was inferred.', 'unrecognized_result');
+            }
             const interaction = interactionResponseSchema.safeParse(raw.interaction);
             if (raw.interaction !== undefined && !interaction.success) {
                 return deny('Interaction response was invalid; no user choice was inferred.', 'unrecognized_result');
@@ -237,6 +256,8 @@ export async function decideFailClosed(callback, toolName, input, context, timeo
                     message: sanitizeErrorText(raw.message ?? 'Denied by host'),
                     ...(toolName === 'AskUserQuestion' && interaction.success ? { interaction: interaction.data } : {}),
                     ...(raw.interrupt !== undefined && { interrupt: raw.interrupt }),
+                    ...(cancellation.success ? { cancellation: cancellation.data } : raw.interrupt
+                        ? { cancellation: { origin: 'host', reason: 'permission_denied' } } : {}),
                     toolUseID: context.toolUseId,
                 },
             };
@@ -282,6 +303,9 @@ export async function* queryWithTransport(prompt, options, transport) {
     let turn = 0;
     let sawResult = false;
     let sessionEnded = false;
+    let suspension;
+    let suspensionTimer;
+    let suspensionTimedOut = false;
     const streamingInput = isAsyncInput(prompt);
     const inputState = { finished: false };
     let resolveProvenanceSupport;
@@ -310,11 +334,27 @@ export async function* queryWithTransport(prompt, options, transport) {
         if (!options.resume) {
             throw new Error('ccl-sdk: pendingDecision requires options.resume');
         }
-        pendingApproval = await store.loadPendingApproval(options.resume);
-        if (!pendingApproval) {
-            throw new Error(`ccl-sdk: no pending approval recorded for session ${options.resume}`);
+        try {
+            pendingApproval = await store.loadPendingApproval(options.resume);
+            if (!pendingApproval)
+                throw new Error(`ccl-sdk: no pending approval recorded for session ${options.resume}`);
+            if (pendingApproval.suspension && pendingApproval.suspension !== 'confirmed')
+                throw new Error('permission_suspension_unconfirmed: the CLI did not confirm a durable suspension; execution status must be checked before resuming');
+            if (pendingDecision.expectedApproval) {
+                const expected = pendingApprovalIdentitySchema.parse(pendingDecision.expectedApproval);
+                if (!samePendingApproval(expected, pendingApproval) || expected.sessionId !== options.resume)
+                    throw new Error('resume_approval_mismatch: saved approval does not match the decision identity');
+                if (pendingDecision.behavior === 'allow' && pendingDecision.updatedInput && approvalInputDigest(pendingDecision.updatedInput) !== expected.inputDigest)
+                    throw new Error('resume_approval_mismatch: strict approval cannot substitute different input');
+                pendingDecision = { ...pendingDecision, expectedApproval: expected };
+            }
+        }
+        catch (error) {
+            await transport.close();
+            throw error;
         }
     }
+    const strictApprovalEvidence = pendingDecision?.expectedApproval ? pendingApproval : null;
     const onAbort = () => { resolveProvenanceSupport(false); void transport.close(); };
     options.signal?.addEventListener('abort', onAbort, { once: true });
     if (options.signal?.aborted)
@@ -342,6 +382,9 @@ export async function* queryWithTransport(prompt, options, transport) {
             request_id: initId,
             request: {
                 subtype: 'initialize',
+                ...(pendingApproval ? { pendingResumeApproval: { approval: pendingApprovalIdentity(pendingApproval), confirmed: pendingApproval.suspension === 'confirmed' } } : {}),
+                ...(options.permissionDelegation ? { permissionDelegation: options.permissionDelegation } : {}),
+                ...(pendingDecision?.expectedApproval ? { strictPendingApproval: pendingDecision.expectedApproval } : {}),
                 ...(options.systemPrompt !== undefined && {
                     systemPrompt: options.systemPrompt,
                 }),
@@ -385,7 +428,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                     await runHook(hooks.onUserPromptSubmit && (() => hooks.onUserPromptSubmit({ prompt: text, sessionId: lastSessionId })));
             })
             : transport.read();
-        for await (const rawMessage of messages) {
+        permissionWire: for await (const rawMessage of messages) {
             let attribution = rawMessage.input_uuid === null
                 ? { origin: 'background' } : typeof rawMessage.input_uuid === 'string'
                 ? { origin: 'user', turnId: rawMessage.input_uuid }
@@ -416,6 +459,13 @@ export async function* queryWithTransport(prompt, options, transport) {
                 yield { ...attribution, type: 'raw', message };
             switch (message.type) {
                 case 'system': {
+                    if (message.subtype === 'query_lifecycle') {
+                        const parsed = QueryLifecycleObservationSchema.safeParse(message.lifecycle);
+                        if (parsed.success && parsed.data.record.session_id === message.session_id && parsed.data.record.event_id === message.uuid)
+                            yield {
+                                ...attribution, type: 'query_lifecycle', lifecycle: parsed.data, sessionId: parsed.data.record.session_id,
+                            };
+                    }
                     if (message.subtype === 'request_progress' && progress)
                         yield { ...attribution,
                             type: 'request_progress', progress,
@@ -463,6 +513,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                     for (const block of contentBlocks(message.message)) {
                         if (block.type === 'tool_result') {
                             const toolUseId = String(block.tool_use_id ?? '');
+                            const operationReference = readOperationReference(message.operation_reference, toolUseId);
                             const isError = block.is_error === true;
                             const resultContent = isError
                                 ? typeof block.content === 'string' ? sanitizeErrorText(block.content)
@@ -473,6 +524,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                                 type: 'tool_result',
                                 toolUseId,
                                 content: resultContent,
+                                ...(operationReference ? { operationReference } : {}),
                                 isError,
                                 sessionId,
                             };
@@ -481,6 +533,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                                     toolUseId,
                                     toolName: toolNamesById.get(toolUseId),
                                     content: resultContent,
+                                    ...(operationReference ? { operationReference } : {}),
                                     isError,
                                     sessionId,
                                 })));
@@ -491,6 +544,10 @@ export async function* queryWithTransport(prompt, options, transport) {
                     break;
                 }
                 case 'control_request': {
+                    // Suspension stops the whole query; never answer another concurrent
+                    // tool while waiting for the targeted CLI acknowledgement.
+                    if (suspension)
+                        break;
                     const requestId = String(message.request_id ?? '');
                     const request = (message.request ?? {});
                     // slice sdk-in-process-mcp-server: route MCP tool calls to host in-process servers.
@@ -535,9 +592,14 @@ export async function* queryWithTransport(prompt, options, transport) {
                         agentId,
                     };
                     // Resume path: settle the recorded approval on its matching call.
-                    // Match by toolName — on allow the tool runs with the RECORDED
-                    // input (or the host's explicit updatedInput), never the model's
-                    // re-generated one, so what the owner approved is what executes.
+                    // Strict callers require the same tool and structured input. Legacy
+                    // callers retain name-only matching and recorded-input substitution.
+                    if (pendingDecision?.expectedApproval && (toolName !== pendingDecision.expectedApproval.toolName || approvalInputDigest(input) !== pendingDecision.expectedApproval.inputDigest)) {
+                        yield { ...attribution, type: 'error', code: 'resume_approval_mismatch', fatal: true, message: 'Regenerated tool/input differs from the original approved invocation' };
+                        // Unwind the read iterator before finally awaits close; otherwise
+                        // unread stdout can keep the child's close event waiting forever.
+                        return;
+                    }
                     if (pendingDecision && pendingApproval?.toolName === toolName) {
                         const decision = pendingDecision.behavior === 'allow'
                             ? {
@@ -620,28 +682,16 @@ export async function* queryWithTransport(prompt, options, transport) {
                             toolName,
                             input,
                             createdAt: new Date().toISOString(),
+                            suspension: 'requested',
                         };
                         await store.savePendingApproval(record);
-                        // Deliberately NO control_response: the tool must not run and
-                        // the model must not see a denial. Terminating here leaves the
-                        // transcript ending at the unresolved tool_use, which the
-                        // resume path drops and re-drives.
-                        yield { ...attribution,
-                            type: 'suspended',
-                            sessionId,
-                            requestId,
-                            toolUseId,
-                            toolName,
-                            input,
-                        };
-                        sessionEnded = true;
-                        await runHook(hooks.onSessionEnd &&
-                            (() => hooks.onSessionEnd({
-                                sessionId,
-                                subtype: 'suspended',
-                                isError: false,
-                            })));
-                        return;
+                        // A saved SDK record alone does not prove the CLI stopped without
+                        // converting EOF into a denial. Ask it to freeze and persist first.
+                        suspension = { requestId: randomUUID(), record, attribution, confirmed: false };
+                        suspensionTimer = setTimeout(() => { suspensionTimedOut = true; void transport.close(); }, 10000);
+                        await transport.write({ type: 'control_request', request_id: suspension.requestId,
+                            request: { subtype: 'suspend_permission', approval: pendingApprovalIdentity(record) } });
+                        break;
                     }
                     await transport.write({
                         type: 'control_response',
@@ -657,6 +707,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                         toolUseId,
                         behavior: outcome.decision.behavior,
                         ...(outcome.decision.behavior === 'deny' && outcome.decision.interaction ? { interaction: outcome.decision.interaction } : {}),
+                        ...(outcome.decision.behavior === 'deny' && outcome.decision.cancellation ? { cancellation: outcome.decision.cancellation } : {}),
                         source: 'callback',
                         ...(outcome.failClosedReason && {
                             failClosedReason: outcome.failClosedReason,
@@ -667,6 +718,20 @@ export async function* queryWithTransport(prompt, options, transport) {
                 case 'control_response': {
                     const response = (message.response ?? {});
                     const requestId = String(response.request_id ?? '');
+                    if (suspension?.requestId === requestId) {
+                        const ack = pendingApprovalSuspensionResponseSchema.safeParse(response.response);
+                        if (response.subtype !== 'success' || !ack.success || !samePendingApproval(ack.data.approval, suspension.record)) {
+                            yield { ...suspension.attribution, type: 'error', code: 'permission_suspension_failed', fatal: true,
+                                message: `CLI did not confirm pending approval suspension: ${String(response.error ?? 'invalid acknowledgement')}` };
+                            return;
+                        }
+                        suspension.record = { ...suspension.record, suspension: 'confirmed' };
+                        await store.savePendingApproval(suspension.record);
+                        suspension.confirmed = true;
+                        if (suspensionTimer)
+                            clearTimeout(suspensionTimer);
+                        break permissionWire;
+                    }
                     if (ownRequestIds.has(requestId)) {
                         ownRequestIds.delete(requestId);
                         const capability = response.response?.input_provenance;
@@ -683,6 +748,34 @@ export async function* queryWithTransport(prompt, options, transport) {
                     break;
                 }
                 case 'result': {
+                    if (suspension && !suspension.confirmed) {
+                        yield { ...suspension.attribution, type: 'error', code: 'permission_suspension_failed', fatal: true,
+                            message: 'CLI ended its turn before confirming permission suspension; inspect execution status' };
+                        return;
+                    }
+                    const conflict = pendingApprovalConflictSchema.safeParse(message.permission_resume_conflict);
+                    if (strictApprovalEvidence && conflict.success && samePendingApproval(conflict.data.approval, strictApprovalEvidence) && message.session_id === strictApprovalEvidence.sessionId) {
+                        if (conflict.data.originalNotExecuted) {
+                            // The CLI guard proves this invocation never reached execution. Restore
+                            // evidence removed on response; never overwrite a newer pending request.
+                            const current = await store.loadPendingApproval(strictApprovalEvidence.sessionId);
+                            if (!current)
+                                await store.savePendingApproval(strictApprovalEvidence);
+                        }
+                        yield { ...attribution, type: 'error', code: conflict.data.code, fatal: true,
+                            message: errorDetailsList(message.errors).join('; ') || 'Strict approval conflict before execution' };
+                        // Unwind the read iterator before finally awaits close; otherwise
+                        // unread stdout can keep the child's close event waiting forever.
+                        return;
+                    }
+                    if (pendingDecision?.expectedApproval) {
+                        yield { ...attribution, type: 'error', code: 'resume_approval_mismatch', fatal: true,
+                            message: 'Strict resume ended without settling the original approval',
+                        };
+                        // Unwind the read iterator before finally awaits close; otherwise
+                        // unread stdout can keep the child's close event waiting forever.
+                        return;
+                    }
                     sawResult = true;
                     const sessionId = message.session_id;
                     const usage = message.usage;
@@ -756,6 +849,22 @@ export async function* queryWithTransport(prompt, options, transport) {
             if (sawResult && !streamingInput)
                 break;
         }
+        if (suspension) {
+            if (!suspension.confirmed) {
+                yield { ...suspension.attribution, type: 'error', code: 'permission_suspension_failed', fatal: true,
+                    message: suspensionTimedOut ? 'Timed out waiting for CLI permission suspension acknowledgement' : 'CLI exited without confirming permission suspension' };
+                return;
+            }
+            // The read iterator has unwound. Stop the original process before exposing
+            // a resumable event, so a consumer can immediately resume in a fresh CLI.
+            await transport.close();
+            const record = suspension.record;
+            yield { ...suspension.attribution, type: 'suspended', sessionId: record.sessionId,
+                requestId: record.requestId, toolUseId: record.toolUseId, toolName: record.toolName, input: record.input };
+            sessionEnded = true;
+            await runHook(hooks.onSessionEnd && (() => hooks.onSessionEnd({ sessionId: record.sessionId, subtype: 'suspended', isError: false })));
+            return;
+        }
         if (streamingInput && inputState.finished) {
             await runHook(hooks.onSessionEnd && (() => hooks.onSessionEnd({
                 sessionId: lastSessionId, subtype: 'input_complete', isError: false,
@@ -783,6 +892,8 @@ export async function* queryWithTransport(prompt, options, transport) {
         }
     }
     finally {
+        if (suspensionTimer)
+            clearTimeout(suspensionTimer);
         resolveProvenanceSupport(false);
         options.signal?.removeEventListener('abort', onAbort);
         await sdkMcpRegistry?.close();
@@ -858,7 +969,8 @@ export function query(prompt, options = {}) {
  *
  * On allow, the suspended tool executes with exactly the recorded input (or
  * decision.updatedInput if the owner amended it); on deny the model receives
- * the denial and the session continues.
+ * the denial and the session continues. With expectedApproval, both the saved
+ * identity and regenerated input must match; substitution is not permitted.
  */
 export function resumeWithDecision(sessionId, decision, options = {}) {
     const merged = {

package/dist/sdk/queryHandle.js

@@ -25,6 +25,7 @@
  */
 import { queryWithTransport, spawnForOptions } from './query.js';
 import { isAsyncInput } from './queryInput.js';
+import { hostCancellationSchema } from './cancellation.js';
 let requestCounter = 0;
 const nextRequestId = () => `ccl-sdk-req-${++requestCounter}-${Math.random().toString(36).slice(2, 10)}`;
 class QueryHandle {
@@ -81,14 +82,15 @@ class QueryHandle {
         // The init promise is settled internally; hosts that never ask for the
         // initialization result must not see an unhandled rejection.
         this.initPromise.catch(() => { });
-        void transport.exited.then(() => this.cancelPermission?.(), () => this.cancelPermission?.());
+        const retired = () => this.cancelPermission?.({ origin: 'host', reason: 'connection_closed' });
+        void transport.exited.then(retired, retired);
         const callback = options.canUseTool;
         void this.pump(prompt, callback ? {
             ...options,
             canUseTool: async (...args) => {
                 let cancel;
                 const cancelled = new Promise(resolve => {
-                    cancel = () => resolve({ behavior: 'deny', message: 'Permission wait cancelled by host', interrupt: true });
+                    cancel = cancellation => resolve({ behavior: 'deny', message: 'Permission wait cancelled by host', interrupt: true, cancellation });
                 });
                 this.cancelPermission = cancel;
                 try {
@@ -220,9 +222,12 @@ class QueryHandle {
         if (response.subtype === 'error') {
             entry.reject(new Error(String(response.error ?? 'control request failed')));
         }
-        else {
+        else if (response.subtype === 'success') {
             entry.resolve(response.response);
         }
+        else {
+            entry.reject(new Error('ccl-sdk: invalid control acknowledgement'));
+        }
     }
     trackInitialize(requestId) {
         this.pending.set(requestId, {
@@ -278,19 +283,34 @@ class QueryHandle {
             return Promise.reject(new Error(this.endReason));
         const requestId = nextRequestId();
         return new Promise((resolve, reject) => {
-            this.pending.set(requestId, { resolve, reject });
+            const timer = opts.timeoutMs ? setTimeout(() => {
+                const entry = this.pending.get(requestId);
+                this.pending.delete(requestId);
+                entry?.reject(new Error('ccl-sdk: interrupt acknowledgement timed out; stop outcome is unknown'));
+            }, opts.timeoutMs) : undefined;
+            this.pending.set(requestId, {
+                resolve: value => { if (timer)
+                    clearTimeout(timer); resolve(value); },
+                reject: error => { if (timer)
+                    clearTimeout(timer); reject(error); },
+            });
             this.transport
                 .write({ type: 'control_request', request_id: requestId, request })
                 .catch(error => {
                 if (this.pending.delete(requestId)) {
+                    if (timer)
+                        clearTimeout(timer);
                     reject(error instanceof Error ? error : new Error(String(error)));
                 }
             });
         });
     }
-    interrupt() {
-        this.cancelPermission?.();
-        return this.controlRequest({ subtype: 'interrupt' });
+    interrupt(cancellation = { origin: 'host', reason: 'cancelled' }) {
+        const parsed = hostCancellationSchema.safeParse(cancellation);
+        if (!parsed.success)
+            return Promise.reject(new Error('ccl-sdk: invalid cancellation provenance'));
+        this.cancelPermission?.(parsed.data);
+        return this.controlRequest({ subtype: 'interrupt', cancellation: parsed.data }, { timeoutMs: 10000 });
     }
     setPermissionMode(mode) {
         return this.controlRequest({ subtype: 'set_permission_mode', mode });
@@ -372,7 +392,7 @@ class QueryHandle {
         return (await this.initializationResult()).account;
     }
     async close() {
-        this.cancelPermission?.();
+        this.cancelPermission?.({ origin: 'host', reason: 'connection_closed' });
         this.markDead('ccl-sdk: query closed');
         await this.transport.close();
     }

package/dist/sdk/queryLifecycle.d.ts

@@ -0,0 +1,19 @@
+import { type QueryLifecycleRecord } from './queryLifecycleTypes.js';
+export type QueryLifecycleRead = {
+    state: 'found';
+    completeness: 'complete' | 'incomplete';
+    records: QueryLifecycleRecord[];
+    terminal?: QueryLifecycleRecord;
+} | {
+    state: 'not_found';
+} | {
+    state: 'unavailable';
+    reason: 'file_unavailable' | 'invalid_record' | 'truncated_tail' | 'record_too_large' | 'conflicting_events';
+};
+/** Read one caller-specified file. Absence is never proof that a tool did not run.
+ * No session discovery, model invocation, daemon startup or repair is performed. */
+export declare function readQueryLifecycle(input: {
+    transcriptPath: string;
+    sessionId: string;
+    queryId: string;
+}): Promise<QueryLifecycleRead>;

package/dist/sdk/queryLifecycle.js

@@ -0,0 +1,93 @@
+import { createReadStream } from 'node:fs';
+import { QueryLifecycleSchema } from './queryLifecycleTypes.js';
+/** Read one caller-specified file. Absence is never proof that a tool did not run.
+ * No session discovery, model invocation, daemon startup or repair is performed. */
+export async function readQueryLifecycle(input) {
+    const records = [];
+    const events = new Map();
+    let failure;
+    let pending = '';
+    const stream = createReadStream(input.transcriptPath, { encoding: 'utf8', highWaterMark: 64 * 1024 });
+    const consume = (line) => {
+        if (!line.trim())
+            return;
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            failure = { state: 'unavailable', reason: 'invalid_record' };
+            return;
+        }
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            failure = { state: 'unavailable', reason: 'invalid_record' };
+            return;
+        }
+        const entry = raw;
+        if (entry.type !== 'query_lifecycle')
+            return;
+        if (entry.record?.session_id !== input.sessionId || entry.record?.query_id !== input.queryId)
+            return;
+        const parsed = QueryLifecycleSchema.safeParse(entry.record);
+        if (!parsed.success) {
+            failure = { state: 'unavailable', reason: 'invalid_record' };
+            return;
+        }
+        const record = parsed.data;
+        const serialized = JSON.stringify(record);
+        const duplicate = events.get(record.event_id);
+        if (duplicate !== undefined) {
+            if (duplicate !== serialized)
+                failure = { state: 'unavailable', reason: 'conflicting_events' };
+            return;
+        }
+        events.set(record.event_id, serialized);
+        records.push(record);
+    };
+    try {
+        for await (const chunk of stream) {
+            pending += chunk;
+            let index;
+            while ((index = pending.indexOf('\n')) !== -1) {
+                if (index > 32 * 1024 * 1024)
+                    return { state: 'unavailable', reason: 'record_too_large' };
+                consume(pending.slice(0, index));
+                if (failure)
+                    return failure;
+                pending = pending.slice(index + 1);
+            }
+            // Protect against an unbounded unterminated line, including ordinary
+            // conversation records. Large files remain streamed rather than loaded.
+            if (pending.length > 32 * 1024 * 1024)
+                return { state: 'unavailable', reason: 'record_too_large' };
+        }
+        if (pending.trim())
+            return { state: 'unavailable', reason: 'truncated_tail' };
+    }
+    catch {
+        return { state: 'unavailable', reason: 'file_unavailable' };
+    }
+    finally {
+        stream.destroy();
+    }
+    if (!records.length)
+        return { state: 'not_found' };
+    let previous;
+    let completeSequence = records[0].phase === 'start';
+    for (const record of records) {
+        if (previous) {
+            if (previous.phase === 'terminal' || record.sequence <= previous.sequence || record.phase === 'start'
+                || record.scope !== previous.scope || record.agent_id !== previous.agent_id
+                || previous.accepted_inputs.some(p => !record.accepted_inputs.some(n => n.message_id === p.message_id && JSON.stringify(n) === JSON.stringify(p)))
+                || previous.input_message_ids.some(id => !record.input_message_ids.includes(id))) {
+                return { state: 'unavailable', reason: 'conflicting_events' };
+            }
+            if (record.sequence !== previous.sequence + 1)
+                completeSequence = false;
+        }
+        previous = record;
+    }
+    const terminal = previous?.phase === 'terminal' ? previous : undefined;
+    return { state: 'found', completeness: terminal && completeSequence ? 'complete' : 'incomplete', records,
+        ...(terminal && completeSequence ? { terminal } : {}) };
+}