maka-agent 0.2.0-dev.3.20260830 → 0.2.0-dev.31.20260913

package/node_modules/@maka/runtime/dist/agent-run.js

@@ -16,25 +16,32 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { decodeRunCompositionSnapshot } from '@maka/core/run-composition';
+import { RUN_COMPOSITION_RECORDED_EVENT_TYPE } from '@maka/core/agent-run';
+import { isRuntimeHandoffPause } from '@maka/core/runtime-handoff';
+import { RunHandoffGate } from './run-handoff-gate.js';
+import { preserveHandoffOpening } from './runtime-resume.js';
+import { createRequestCompositionSnapshot, decodeRequestCompositionSnapshot, decodeRunCompositionSnapshot, } from '@maka/core/run-composition';
 import { DurableStoreWriteError, RunSealedError } from '@maka/core/runtime-event-store';
-import { isSessionInlineRun } from '@maka/core/agent-run';
+import { buildInvocationOpenedEvent, buildSyntheticTerminalRuntimeEvent, isSessionInlineInvocation, } from '@maka/core/runtime-invocation';
+import { MODEL_PROJECTION_TRANSITION_EVENT_TYPE, } from '@maka/core/model-projection-transition';
 import { isTerminalRuntimeEvent } from '@maka/core/runtime-event';
 import { ToolLedgerCorruptionError, ToolLedgerRejectionError, } from '@maka/core/tool-ledger-scanner';
+import { stableHash } from './request-shape.js';
 import { Buffer } from 'node:buffer';
 import { isDeepStrictEqual } from 'node:util';
 import { redactSecrets } from '@maka/core/redaction';
+import { truncateUtf8 } from '@maka/core/diagnostic-log';
+import { MODEL_FAILURE_MESSAGE_MAX_BYTES } from '@maka/core/model-failure';
 import { MODEL_CALL_ATTEMPT_EVENT_TYPE, } from '@maka/core/model-call-attempt';
 import { resolveEffectiveOrchestration, } from '@maka/core/orchestration';
-import { messageContentsEqual } from '@maka/core/events';
-import { projectRuntimeEventsToStoredMessages } from './runtime-event-read-model.js';
 import { buildPriorRuntimeContext as buildPriorRuntimeContextProjection, } from './prior-run-context.js';
-import { buildStatusPatch, isTerminalRunStatus, normalizeStopSessionSource, statusFromEvent, turnStatusFromEvent, } from './session-projection-helpers.js';
-import { buildSyntheticTerminalRuntimeEvent, commitOrCreateTerminalRunFact, } from './terminal-run-commit.js';
+import { buildStatusPatch, normalizeStopSessionSource, statusFromEvent, turnStatusFromEvent, } from './session-projection-helpers.js';
+import { admittedPromptEventId } from './message-authority.js';
+import { commitOrCreateTerminalRunFact } from './terminal-run-commit.js';
 import { createRuntimeContinuationStartAdmissionProof, } from './runtime-continuation-admission.js';
 import { DEFAULT_TOOL_MODE, isToolMode } from '@maka/core/tool-mode';
-import { materializeRuntimeEventTranscriptProjection } from './runtime-ledger-repair.js';
 import { cloneAndFreezeRuntimeSnapshot } from './runtime-snapshot.js';
+import { projectRuntimeEventUserMessage } from './runtime-event-read-model.js';
 export class ContinuationStartCommitError extends Error {
     storeCause;
     name = 'ContinuationStartCommitError';
@@ -64,6 +71,7 @@ export class AgentRun {
     runStoreAvailable = true;
     runtimeEventStoreAvailable = true;
     runtimeEventStoreFailure;
+    lastAssistantPreview;
     runtimePartialStreamKey;
     runtimePartialBuffer = [];
     runtimePartialBufferBytes = 0;
@@ -71,6 +79,10 @@ export class AgentRun {
     traceWriteError;
     runComposition;
     runCompositionWrite;
+    runCompositionCommitted = false;
+    requestComposition;
+    requestCompositionIndex;
+    requestCompositionIndexRead;
     failureClass;
     failureMessage;
     lastTs = 0;
@@ -78,8 +90,16 @@ export class AgentRun {
     finalStatus;
     turnFailed = false;
     finalized = false;
-    terminalRunHeaderCommitted = false;
+    handoffGate = new RunHandoffGate();
+    handoffRequest;
+    handoffPaused = false;
+    terminalRunFactCommitted = false;
     continuationActive = false;
+    providerStateIdentity;
+    invocationOpening;
+    invocationOpeningCommitted = false;
+    /** Set once `begin()` owes this run's prompt, cleared once the ledger has it. */
+    initialRuntimeEventPending = false;
     terminalClaim;
     constructor(input) {
         const acceptedInput = {
@@ -88,6 +108,9 @@ export class AgentRun {
             ...(input.effectiveOrchestration
                 ? { effectiveOrchestration: cloneAndFreezeRuntimeSnapshot(input.effectiveOrchestration) }
                 : {}),
+            ...(input.handoffSourceComposition
+                ? { handoffSourceComposition: decodeRunCompositionSnapshot(input.handoffSourceComposition) }
+                : {}),
         };
         this.input = acceptedInput;
         if (acceptedInput.runStore && !acceptedInput.runtimeEventStore) {
@@ -106,7 +129,14 @@ export class AgentRun {
         this.effectiveOrchestration =
             acceptedInput.effectiveOrchestration ??
                 resolveEffectiveOrchestration(acceptedInput.header.orchestrationMode, acceptedInput.userInput.turnOrchestration);
-        const requestedToolMode = acceptedInput.effectiveToolMode ?? acceptedInput.userInput.toolMode ?? DEFAULT_TOOL_MODE;
+        if (acceptedInput.userInput.toolMode !== undefined &&
+            !isToolMode(acceptedInput.userInput.toolMode)) {
+            throw new Error(`Invalid tool mode: ${String(acceptedInput.userInput.toolMode)}`);
+        }
+        const requestedToolMode = acceptedInput.effectiveToolMode ??
+            acceptedInput.header.toolMode ??
+            acceptedInput.userInput.toolMode ??
+            DEFAULT_TOOL_MODE;
         if (!isToolMode(requestedToolMode)) {
             throw new Error(`Invalid tool mode: ${String(requestedToolMode)}`);
         }
@@ -130,22 +160,145 @@ export class AgentRun {
                 : {}),
         };
     }
-    stop(source) {
+    stop(source, workHubActionId) {
+        const abortSource = normalizeStopSessionSource(source, workHubActionId);
         if (this.terminalClaim)
             return false;
         this.terminalClaim = { owner: 'stop' };
         this.stopped = true;
-        this.abortSource = normalizeStopSessionSource(source);
+        this.handoffGate.close();
+        this.abortSource = abortSource;
         return true;
     }
     isStopped() {
         return this.stopped;
     }
-    isSessionInline() {
-        return isSessionInlineRun({
-            ...(this.lineage.parentRunId ? { parentRunId: this.lineage.parentRunId } : {}),
-            ...(this.continuationActive ? { continuationSource: true } : {}),
+    requestHandoff(pause, signal) {
+        if (this.handoffRequest ||
+            this.finalized ||
+            this.terminalClaim ||
+            this.input.runtimeEventStore?.durability !== 'canonical' ||
+            !this.toolBoundaryProtocol ||
+            Object.hasOwn(pause, 'remainingSteps') ||
+            !isRuntimeHandoffPause({ ...pause, remainingSteps: null }) ||
+            !this.invocationOpening ||
+            pause.rootRunId !==
+                (this.invocationOpening.source.kind === 'handoff'
+                    ? this.invocationOpening.source.rootRunId
+                    : this.runId)) {
+            throw new Error('Run cannot reserve a cooperative handoff');
+        }
+        let settle;
+        let fail;
+        const sealed = new Promise((resolve, reject) => {
+            settle = resolve;
+            fail = reject;
+        });
+        void sealed.catch(() => { });
+        const pending = {
+            pause: cloneAndFreezeRuntimeSnapshot(pause),
+            preview: undefined,
+            committed: false,
+            settle: (value) => {
+                signal.removeEventListener('abort', onAbort);
+                settle(value);
+            },
+            fail: (error) => {
+                signal.removeEventListener('abort', onAbort);
+                fail(error);
+            },
+        };
+        this.handoffRequest = pending;
+        const gate = this.handoffGate.request(signal);
+        const cancel = () => {
+            if (pending.committed || this.handoffRequest !== pending)
+                return;
+            gate.cancel();
+            this.handoffRequest = undefined;
+            pending.settle(false);
+        };
+        const onAbort = () => cancel();
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted)
+            cancel();
+        void gate.ready.then((ready) => {
+            if (!ready)
+                cancel();
         });
+        return {
+            ready: gate.ready,
+            sealed,
+            cancel,
+            preview: () => {
+                if (this.handoffRequest !== pending ||
+                    this.stopped ||
+                    pending.committed ||
+                    !pending.preview) {
+                    throw new Error('Handoff preview requires the currently held Runtime boundary');
+                }
+                this.assertRunCompositionCommitted();
+                return pending.preview;
+            },
+            commit: () => {
+                this.assertRunCompositionCommitted();
+                if (this.handoffRequest !== pending || !gate.commit())
+                    return false;
+                pending.committed = true;
+                return true;
+            },
+        };
+    }
+    async reachHandoffBoundary(signal, remainingSteps) {
+        if (remainingSteps !== null && (!Number.isSafeInteger(remainingSteps) || remainingSteps <= 0)) {
+            throw new Error('Invalid handoff step budget');
+        }
+        const pending = this.handoffRequest;
+        if (pending) {
+            pending.preview = cloneAndFreezeRuntimeSnapshot({
+                id: this.input.newId(),
+                sessionId: this.sessionId,
+                runId: this.runId,
+                invocationId: this.invocationId,
+                turnId: this.turnId,
+                ts: this.input.now(),
+                partial: false,
+                role: 'system',
+                author: 'host',
+                modelVisibility: 'hidden',
+                actions: { endInvocation: true, handoffPause: { ...pending.pause, remainingSteps } },
+            });
+        }
+        const decision = await this.handoffGate.reachBoundary(signal);
+        if (decision === 'pause') {
+            this.handoffPaused = true;
+        }
+        return decision;
+    }
+    hasCommittedHandoff() {
+        return (this.handoffPaused &&
+            this.handoffRequest?.committed === true &&
+            !this.stopped &&
+            !this.failureClass &&
+            !this.terminalClaim);
+    }
+    headerSnapshot() {
+        return this.header;
+    }
+    bindProviderStateIdentity(identity) {
+        const claimed = claimedProviderStateIdentity(this.input.claimedOpening);
+        const expected = claimed ?? this.providerStateIdentity;
+        if (expected !== undefined && expected !== identity) {
+            throw new Error('Prepared backend provider state does not match the AgentRun admission');
+        }
+        this.providerStateIdentity = identity;
+    }
+    isSessionInline() {
+        const opening = this.invocationOpening;
+        if (opening)
+            return isSessionInlineInvocation(opening);
+        // Before the opening fact exists there is only the lineage the turn was
+        // admitted with, which decides the same question the same way.
+        return this.lineage.parentRunId === undefined;
     }
     hasPendingStop() {
         return this.terminalClaim?.owner === 'stop' && this.terminalClaim.stopCompleted !== true;
@@ -166,7 +319,7 @@ export class AgentRun {
      * produces its own terminal event finds the claim taken and writes nothing.
      */
     async settleStopTerminal() {
-        if (this.terminalClaim?.owner !== 'stop' || this.terminalRunHeaderCommitted)
+        if (this.terminalClaim?.owner !== 'stop' || this.terminalRunFactCommitted)
             return;
         // Nothing durable is configured, so there is no fact to land. Every other
         // failure below is real and must reach the stop's caller: a stop that
@@ -194,7 +347,7 @@ export class AgentRun {
             // the latch, one that cannot fails the settlement loudly so the stop
             // stays retryable.
             try {
-                await runStore.readRun(this.sessionId, this.runId);
+                await runStore.readEvents(this.sessionId, this.runId);
                 this.runStoreAvailable = true;
             }
             catch (error) {
@@ -233,6 +386,15 @@ export class AgentRun {
             return Promise.reject(new Error('AgentRun store is not configured'));
         }
         const normalized = decodeRunCompositionSnapshot(snapshot);
+        const expected = this.input.handoffSourceComposition;
+        if (expected &&
+            (normalized.baseSystemPromptHash !== expected.baseSystemPromptHash ||
+                normalized.toolCatalogHash !== expected.toolCatalogHash ||
+                normalized.toolAvailabilityHash !== expected.toolAvailabilityHash ||
+                normalized.baseProviderOptionsHash !== expected.baseProviderOptionsHash ||
+                normalized.contextWindow !== expected.contextWindow)) {
+            return Promise.reject(new Error('Handoff Run Composition execution semantics changed'));
+        }
         if (this.runComposition && !isDeepStrictEqual(this.runComposition, normalized)) {
             return Promise.reject(new Error('AgentRun Run Composition changed after resolution'));
         }
@@ -240,7 +402,20 @@ export class AgentRun {
         if (this.runCompositionWrite)
             return this.runCompositionWrite;
         const write = this.enqueueRequiredRunStoreWrite('commit Run Composition', async () => {
-            await this.input.runStore?.updateRun(this.sessionId, this.runId, { runComposition: normalized }, { durable: this.requiresDurablePersistence() });
+            await this.input.runStore?.appendEvent(this.sessionId, this.runId, {
+                type: RUN_COMPOSITION_RECORDED_EVENT_TYPE,
+                id: this.input.newId(),
+                runId: this.runId,
+                sessionId: this.sessionId,
+                turnId: this.turnId,
+                ts: this.input.now(),
+                data: { runComposition: normalized },
+            }, {
+                durable: this.requiresDurablePersistence() ||
+                    this.input.runtimeEventStore?.durability === 'canonical',
+            });
+        }).then(() => {
+            this.runCompositionCommitted = true;
         });
         this.runCompositionWrite = write;
         return write.catch((error) => {
@@ -249,36 +424,76 @@ export class AgentRun {
             throw error;
         });
     }
-    recordProviderRequestCapture(capture) {
-        if (!this.input.runStore)
-            return Promise.reject(new Error('AgentRun store is not configured'));
-        return this.enqueueRequiredRunStoreWrite('append provider request capture', async () => {
-            const { schemaVersion, serializedRequest: _serializedRequest, ...data } = capture;
+    assertRunCompositionCommitted() {
+        if (!this.runCompositionCommitted) {
+            throw new Error('Cooperative handoff requires a durably committed Run Composition');
+        }
+    }
+    /**
+     * Durably binds one logical model step to its effective request surface.
+     * Unchanged steps reuse the latest snapshot; a changed surface appends a full
+     * replacement before provider dispatch, matching DSH request/header epochs.
+     */
+    async recordRequestComposition(input) {
+        if (!this.input.runStore) {
+            throw new Error('AgentRun store is not configured');
+        }
+        await this.loadRequestCompositionIndex();
+        const snapshot = createRequestCompositionSnapshot(input, this.requestCompositionIndex?.size ? 'change' : 'initial');
+        const surfaceHash = requestCompositionSurfaceHash(snapshot);
+        const existing = this.requestCompositionIndex?.get(surfaceHash);
+        if (existing) {
+            if (!sameRequestCompositionSurface(existing, snapshot)) {
+                throw new Error(`Request Composition surface hash collision: ${surfaceHash}`);
+            }
+            this.requestComposition = existing;
+            return existing.compositionId;
+        }
+        await this.enqueueRequiredRunStoreWrite('append request composition', async () => {
             await this.input.runStore?.appendEvent(this.sessionId, this.runId, {
-                type: 'provider_request_captured',
-                id: capture.captureId,
+                type: 'request_composition_resolved',
+                id: snapshot.compositionId,
                 runId: this.runId,
                 sessionId: this.sessionId,
-                turnId: capture.turnId,
+                turnId: this.turnId,
                 ts: this.input.now(),
-                data: { schemaVersion, ...data },
+                data: { snapshot },
             }, { durable: true });
         });
+        this.requestComposition = snapshot;
+        this.requestCompositionIndex?.set(surfaceHash, snapshot);
+        return snapshot.compositionId;
     }
-    recordProviderRequestAttempt(attempt) {
-        if (!this.input.runStore)
+    async loadRequestCompositionIndex() {
+        if (this.requestCompositionIndex)
             return;
-        this.enqueueBestEffortProviderAttempt('append provider request attempt', async () => {
-            await this.input.runStore?.appendEvent(this.sessionId, this.runId, {
-                type: 'provider_request_attempt_recorded',
-                id: attempt.attemptId,
-                runId: this.runId,
-                sessionId: this.sessionId,
-                turnId: attempt.turnId,
-                ts: attempt.completedAt,
-                data: { ...attempt },
-            });
-        });
+        if (this.requestCompositionIndexRead)
+            return await this.requestCompositionIndexRead;
+        const read = (async () => {
+            const index = new Map();
+            const events = await this.input.runStore?.readEvents(this.sessionId, this.runId);
+            for (const event of events ?? []) {
+                if (event.type !== 'request_composition_resolved')
+                    continue;
+                const snapshot = decodeRequestCompositionSnapshot(event.data?.snapshot);
+                const surfaceHash = requestCompositionSurfaceHash(snapshot);
+                const existing = index.get(surfaceHash);
+                if (existing && !sameRequestCompositionSurface(existing, snapshot)) {
+                    throw new Error(`Request Composition surface hash collision: ${surfaceHash}`);
+                }
+                index.set(surfaceHash, existing ?? snapshot);
+                this.requestComposition = snapshot;
+            }
+            this.requestCompositionIndex = index;
+        })();
+        this.requestCompositionIndexRead = read;
+        try {
+            await read;
+        }
+        finally {
+            if (this.requestCompositionIndexRead === read)
+                this.requestCompositionIndexRead = undefined;
+        }
     }
     /**
      * Canonical accounting record for one physical provider request (#1679).
@@ -314,6 +529,34 @@ export class AgentRun {
             { durable: true, ...(latestContext ? { latestContext } : {}) });
         });
     }
+    /**
+     * Durable append for one model-projection transition (#4283).
+     *
+     * Rethrows like the checkpoint recorder above: the caller may only show the
+     * replacement once the ledger holds the record, so a failed append must be a
+     * failed prune, not a silent one.
+     */
+    recordModelProjectionTransition(transition) {
+        if (!this.input.runStore)
+            return Promise.reject(new Error('AgentRun store is not configured'));
+        if (!this.runStoreAvailable)
+            return Promise.reject(new Error('AgentRun store is unavailable'));
+        return this.enqueueRunStore('append model projection transition', async () => {
+            await this.input.runStore?.appendEvent(this.sessionId, this.runId, {
+                type: MODEL_PROJECTION_TRANSITION_EVENT_TYPE,
+                id: transition.transitionId,
+                runId: this.runId,
+                sessionId: this.sessionId,
+                turnId: this.turnId,
+                ts: transition.createdAt,
+                data: {
+                    runtimeEventId: transition.target.runtimeEventId,
+                    part: transition.target.part,
+                    transition,
+                },
+            });
+        }, { rethrow: true });
+    }
     recordHistoryCompactCheckpoint(checkpoint) {
         if (!this.input.runStore)
             return Promise.reject(new Error('AgentRun store is not configured'));
@@ -383,12 +626,14 @@ export class AgentRun {
                 requireTerminalWrite: options.requireTerminalWrite ?? Boolean(this.input.runtimeEventStore),
             });
             await this.recordSessionEvent(sessionEvent, options);
+            await this.commitMessageProjection(this.lastAssistantPreview);
             return;
         }
+        this.rememberAssistantPreview(runtimeEvent);
         if (this.requiresDurablePersistence() && isInteractionResumeAck(sessionEvent)) {
             // A hosted continuation may resume execution only after its identity-only
-            // settlement fact is durable. Run status advances next, then Session
-            // status; the queue consumer acknowledges the event only after all three.
+            // settlement fact is durable. Session status advances next, and the queue
+            // consumer acknowledges the event only after both.
             await this.recordRuntimeEvents([runtimeEvent], { requireDurableWrite: true });
             await this.recordSessionEvent(sessionEvent, options);
             return;
@@ -412,54 +657,66 @@ export class AgentRun {
             // stays fail-open (a trace gap, not a correctness gap).
             const steering = runtimeEvent.content?.kind === 'text' && runtimeEvent.content.steering === true;
             await this.recordRuntimeEvents([runtimeEvent], steering ? { requireDurableWrite: true } : {});
-            await materializeRuntimeEventTranscriptProjection(this.input.store, this.sessionId, runtimeEvent);
+            if (steering) {
+                await this.commitMessageProjection(projectRuntimeEventUserMessage(runtimeEvent, runtimeEvent.id));
+            }
         }
     }
+    /**
+     * A user message is fail-CLOSED: it also takes the Session's connection lock,
+     * and no other path re-derives that latch now that the transcript is not a
+     * second authority. An assistant preview is fail-open — losing it costs a
+     * stale sidebar entry, never the turn.
+     */
+    async commitMessageProjection(message) {
+        const commit = this.input.hooks.commitMessageProjection;
+        if (!commit || !message)
+            return;
+        const committed = commit.call(this.input.hooks, this.sessionId, message);
+        if (message.type === 'user')
+            return committed;
+        await committed.catch(() => { });
+    }
+    /**
+     * The assistant text the Session list shows once the Turn ends.
+     *
+     * Kept as the run goes so the catalog costs one write per Turn rather than
+     * one per streamed step, and read only after the terminal fact is durable —
+     * a Turn that never spoke leaves the previous preview standing.
+     */
+    rememberAssistantPreview(event) {
+        if (event.role !== 'model' || event.content?.kind !== 'text')
+            return;
+        if (!event.content.text?.trim())
+            return;
+        this.lastAssistantPreview = {
+            type: 'assistant',
+            id: event.id,
+            turnId: event.turnId,
+            ts: event.ts,
+            text: event.content.text,
+            modelId: this.header.model,
+        };
+    }
+    async beginUserTurn() {
+        // Owed from here, not from after the opening: `openInvocation` can leave the
+        // invocation open and still throw, and `finalize` reopens what it can.
+        this.initialRuntimeEventPending = true;
+        await this.openInvocation();
+        this.lastTs = this.input.now();
+        const initialRuntimeEvent = await this.recordInitialRuntimeEvent(this.lastTs);
+        return initialRuntimeEvent;
+    }
+    /** Host actions share Turn facts and finalization without activating a provider. */
+    async beginCoordination() {
+        await this.beginUserTurn();
+        await this.input.hooks.updateStatus(this.sessionId, 'running', undefined, this.lastTs);
+    }
     async begin() {
-        await this.createRunRecord();
-        let initialRuntimeEventId;
-        const userMessageTs = this.input.now();
-        if (this.input.userMessageId === null) {
-            initialRuntimeEventId = this.input.newId();
-        }
-        else {
-            const userMessageId = this.input.userMessageId ?? this.input.newId();
-            initialRuntimeEventId = userMessageId;
-            const userMsg = cloneAndFreezeRuntimeSnapshot({
-                type: 'user',
-                id: userMessageId,
-                turnId: this.turnId,
-                ts: userMessageTs,
-                text: this.input.userInput.text,
-                ...(this.input.userInput.displayText !== undefined
-                    ? { displayText: this.input.userInput.displayText }
-                    : {}),
-                ...(this.input.userInput.attachments
-                    ? { attachments: this.input.userInput.attachments }
-                    : {}),
-                ...(this.input.userInput.quotes ? { quotes: this.input.userInput.quotes } : {}),
-                ...(this.input.userInput.inlineReferences
-                    ? { inlineReferences: this.input.userInput.inlineReferences }
-                    : {}),
-                ...(this.input.userInput.origin ? { origin: this.input.userInput.origin } : {}),
-            });
-            await appendUserMessageOnce(this.input.store, this.sessionId, userMsg);
-        }
-        await this.input.hooks.appendTurnState(this.sessionId, this.turnId, 'running', this.lineage);
-        this.lastTs = userMessageTs;
-        const initialRuntimeEvent = cloneAndFreezeRuntimeSnapshot(this.buildInitialRuntimeEvent(initialRuntimeEventId, this.lastTs));
-        await this.recordRuntimeEvents([initialRuntimeEvent], {
-            requireDurableWrite: this.requiresDurablePersistence(),
-        });
+        const initialRuntimeEvent = await this.beginUserTurn();
         this.active = await this.input.hooks.reserveRun(this.sessionId, this.header, this);
-        await this.markRunStarted(this.lastTs);
         await this.input.hooks.updateStatus(this.sessionId, 'running', undefined, this.lastTs);
         const priorRuntimeContext = await this.buildPriorRuntimeContext();
-        const projectionContext = priorRuntimeContext
-            ? projectRuntimeEventsToStoredMessages(priorRuntimeContext.events, {
-                runHeaders: priorRuntimeContext.runs,
-            }).messages
-            : [];
         return {
             backend: this.active.backend,
             backendInput: cloneAndFreezeRuntimeSnapshot({
@@ -473,27 +730,44 @@ export class AgentRun {
                 ...(this.input.userInput.attachments
                     ? { attachments: this.input.userInput.attachments }
                     : {}),
+                ...(this.input.userInput.directoryReferences
+                    ? { directoryReferences: this.input.userInput.directoryReferences }
+                    : {}),
                 ...(this.input.userInput.quotes ? { quotes: this.input.userInput.quotes } : {}),
-                context: projectionContext,
-                ...(priorRuntimeContext ? { runtimeContext: priorRuntimeContext.events } : {}),
+                ...(priorRuntimeContext
+                    ? {
+                        runtimeContext: priorRuntimeContext.events,
+                        runtimeContextInvocations: priorRuntimeContext.invocations,
+                    }
+                    : {}),
             }),
             initialRuntimeEvent,
         };
     }
+    /** Say what this run was asked to do. */
+    async recordInitialRuntimeEvent(ts) {
+        const event = cloneAndFreezeRuntimeSnapshot(this.buildInitialRuntimeEvent(admittedPromptEventId(this.runId, this.input.userMessageId), ts));
+        await this.recordRuntimeEvents([event], {
+            requireDurableWrite: this.requiresDurablePersistence(),
+        });
+        // Owed until the catalog carries it too, not just until the ledger does:
+        // the projection is where the connection lock latches, and re-recording the
+        // event is free because its id is derived and the store dedupes it.
+        await this.commitMessageProjection(projectRuntimeEventUserMessage(event, event.id));
+        this.initialRuntimeEventPending = false;
+        return event;
+    }
     async beginOperation() {
-        await this.createRunRecord();
+        await this.openInvocation();
         const startedAt = this.input.now();
         this.lastTs = startedAt;
-        await this.input.hooks.appendTurnState(this.sessionId, this.turnId, 'running', this.lineage, {
-            ts: startedAt,
-        });
         this.active = await this.input.hooks.reserveRun(this.sessionId, this.header, this);
-        await this.markRunStarted(startedAt);
         await this.input.hooks.updateStatus(this.sessionId, 'running', undefined, startedAt);
         const priorRuntimeContext = await this.buildPriorRuntimeContext();
         return {
             backend: this.active.backend,
             runtimeContext: priorRuntimeContext?.events ?? [],
+            runtimeContextInvocations: priorRuntimeContext?.invocations ?? [],
             startedAt,
         };
     }
@@ -504,8 +778,7 @@ export class AgentRun {
             throw new Error('Runtime continuation identity does not match the target AgentRun');
         }
         this.continuationActive = true;
-        await this.createRunRecord(continuation);
-        await this.input.continuationFailpoint?.('after_run_created');
+        await this.openInvocation(continuation);
         const startedAt = this.input.now();
         this.lastTs = startedAt;
         if (!this.input.commitContinuationStart) {
@@ -519,11 +792,7 @@ export class AgentRun {
             throw new ContinuationStartCommitError(error);
         }
         await this.input.continuationFailpoint?.('after_continuation_start_committed');
-        await this.input.hooks.appendTurnState(this.sessionId, this.turnId, 'running', this.lineage, {
-            ts: startedAt,
-        });
         this.active = await this.input.hooks.reserveRun(this.sessionId, this.header, this);
-        await this.markRunStarted(startedAt);
         await this.input.hooks.updateStatus(this.sessionId, 'running', undefined, startedAt);
         return {
             backend: this.active.backend,
@@ -564,20 +833,43 @@ export class AgentRun {
                 ...(input.attachments !== undefined && input.attachments.length > 0
                     ? { attachments: input.attachments }
                     : {}),
+                ...(input.directoryReferences ? { directoryReferences: input.directoryReferences } : {}),
                 ...(input.quotes !== undefined && input.quotes.length > 0 ? { quotes: input.quotes } : {}),
                 ...(input.inlineReferences !== undefined
                     ? { inlineReferences: input.inlineReferences }
                     : {}),
             },
-            ...(this.toolBoundaryProtocol
+            // The marker belongs to the invocation's first event. Once an opening
+            // fact exists it holds the marker, and a second copy here would read as
+            // a stray marker to RecoveryResolver.
+            ...(this.toolBoundaryProtocol && !this.invocationOpeningCommitted
                 ? { actions: { runtimeProtocol: { toolBoundary: this.toolBoundaryProtocol } } }
                 : {}),
         };
     }
-    async recordStoredSessionEvent(ev) {
-        if (ev.type === 'token_usage') {
-            await this.input.store.appendMessage(this.sessionId, { ...ev });
-        }
+    /**
+     * Record something the runtime needs to tell the reader about this turn.
+     *
+     * It is a fact of the invocation, so it goes where the invocation's facts go.
+     * Never model-visible: the note describes what happened to the conversation,
+     * it is not part of it.
+     */
+    async recordSystemNote(kind, data) {
+        await this.recordRuntimeEvents([
+            {
+                id: this.input.newId(),
+                invocationId: this.invocationId,
+                runId: this.runId,
+                sessionId: this.sessionId,
+                turnId: this.turnId,
+                ts: this.input.now(),
+                partial: false,
+                role: 'system',
+                author: 'system',
+                modelVisibility: 'hidden',
+                content: { kind: 'system_note', note: kind, ...(data !== undefined ? { data } : {}) },
+            },
+        ]);
     }
     async recordSessionEvent(ev, options = {}) {
         this.lastTs = ev.ts;
@@ -599,12 +891,12 @@ export class AgentRun {
                 turnStatus.errorClass &&
                 !this.failureClass &&
                 !this.stopped) {
-                this.markRunFailed(turnStatus.errorClass, `turn ended with stopReason=${ev.type === 'complete' ? ev.stopReason : 'unknown'}`, ev.ts);
+                this.markRunFailed(turnStatus.errorClass, `turn ended with stopReason=${ev.type === 'complete' ? ev.stopReason : 'unknown'}`);
             }
         }
-        if (transition && !this.stopped) {
+        if (transition && !this.stopped && ev.type !== 'error') {
             const updateSessionStatus = async () => {
-                if (terminalSessionEvent || ev.type === 'error') {
+                if (terminalSessionEvent) {
                     await this.input.hooks
                         .updateStatus(this.sessionId, transition.status, transition.blockedReason, ev.ts)
                         .catch((error) => this.enqueueTraceWriteFailure(error, 'terminal session projection'));
@@ -612,31 +904,7 @@ export class AgentRun {
                 }
                 await this.input.hooks.updateStatus(this.sessionId, transition.status, transition.blockedReason, ev.ts);
             };
-            // On resume, advance the Run before the Session so an interrupted pair
-            // remains conservatively waiting rather than advertising false readiness.
-            if (this.requiresDurablePersistence() && isInteractionResumeAck(ev)) {
-                await this.recordStatusFromTransition(ev, transition, ev.ts);
-                await updateSessionStatus();
-            }
-            else {
-                await updateSessionStatus();
-                await this.recordStatusFromTransition(ev, transition, ev.ts);
-            }
-        }
-        if (turnStatus && !this.stopped) {
-            const appendTurnState = this.input.hooks.appendTurnState(this.sessionId, this.turnId, turnStatus.status, this.lineage, {
-                ts: ev.ts,
-                errorClass: turnStatus.errorClass,
-                ...(turnStatus.status === 'aborted' && this.abortSource
-                    ? { abortSource: this.abortSource }
-                    : {}),
-            });
-            if (terminalSessionEvent || ev.type === 'error') {
-                await appendTurnState.catch((error) => this.enqueueTraceWriteFailure(error, 'terminal session projection'));
-            }
-            else {
-                await appendTurnState;
-            }
+            await updateSessionStatus();
         }
         if (ev.type === 'error') {
             if (this.stopped) {
@@ -645,13 +913,7 @@ export class AgentRun {
             else {
                 this.turnFailed = true;
                 this.finalStatus = transition ?? { status: 'blocked', blockedReason: 'unknown' };
-                await this.input.hooks
-                    .appendTurnState(this.sessionId, this.turnId, 'failed', this.lineage, {
-                    ts: ev.ts,
-                    errorClass: ev.reason ?? ev.code ?? 'unknown',
-                })
-                    .catch((error) => this.enqueueTraceWriteFailure(error, 'terminal session projection'));
-                this.markRunFailed(ev.reason ?? ev.code ?? 'unknown', ev.message, ev.ts);
+                this.markRunFailed(ev.reason ?? ev.code ?? 'unknown', ev.message);
             }
         }
     }
@@ -746,24 +1008,61 @@ export class AgentRun {
             return;
         }
         this.finalStatus = { status: 'blocked', blockedReason: 'unknown' };
-        await this.input.hooks
-            .appendTurnState(this.sessionId, this.turnId, 'failed', this.lineage, {
-            errorClass: error instanceof Error ? error.name : 'unknown',
-        })
-            .catch(() => { });
-        this.markRunFailed(error instanceof Error ? error.name : 'unknown', errorMessage(error), this.input.now());
+        this.markRunFailed(error instanceof Error ? error.name : 'unknown', error instanceof Error ? error.message : String(error));
     }
     async finalize() {
         if (this.finalized)
             return;
         this.finalized = true;
+        this.handoffGate.close();
+        const handoff = this.handoffRequest;
+        if (this.handoffPaused &&
+            handoff?.committed &&
+            !this.stopped &&
+            !this.failureClass &&
+            !this.terminalClaim) {
+            try {
+                await this.flushRuntimePartialBuffer(true);
+                // Stop may have claimed the logical outcome during the flush. Reserving
+                // the pause below is synchronous up to its first write, so only one wins.
+                if (!this.stopped && !this.failureClass && !this.terminalClaim) {
+                    this.assertRunCompositionCommitted();
+                    await this.recordRuntimeEvents([handoff.preview], { requireTerminalWrite: true });
+                    this.terminalRunFactCommitted = true;
+                    if (this.active)
+                        await this.input.hooks.unregisterRun(this.active, this);
+                    await this.traceQueue;
+                    handoff.settle(true);
+                    return;
+                }
+            }
+            catch (error) {
+                handoff.fail(error);
+                throw error;
+            }
+        }
+        handoff?.settle(false);
+        // A run cannot end without having begun. Finalizing one that never reached
+        // its start would otherwise leave a terminal event on an invocation the
+        // inventory cannot see, because nothing opened it. A continuation is the
+        // exception at both ends: its opening rides the continuation-start event,
+        // and a continuation that never committed one has no invocation to end.
+        if (!this.input.commitContinuationStart)
+            await this.openInvocation().catch(() => { });
+        // A run also cannot end without saying what it was asked to do. `begin()`
+        // can fail between opening the invocation and recording its prompt, and
+        // the terminal event below seals the run against every later append —
+        // including the one crash recovery would use to repair the same shape.
+        if (this.initialRuntimeEventPending) {
+            await this.recordInitialRuntimeEvent(this.lastTs || this.input.now()).catch(() => { });
+        }
         await this.flushRuntimePartialBuffer(true);
         const lastTs = this.lastTs || this.input.now();
         if (this.stopped)
             this.finalStatus = { status: 'aborted' };
         if (!this.finalStatus) {
             this.finalStatus = { status: 'blocked', blockedReason: 'unknown' };
-            this.markRunFailed('missing_terminal_event', 'run finalized without a terminal SessionEvent', lastTs);
+            this.markRunFailed('missing_terminal_event', 'run finalized without a terminal SessionEvent');
         }
         this.reserveFinalizationTerminal(this.finalStatus, lastTs);
         if (this.active) {
@@ -782,123 +1081,149 @@ export class AgentRun {
         catch {
             // The user-visible turn already completed; preserve existing behavior.
         }
-        if (this.sawCompletion) {
-            await this.input.store
-                .appendMessage(this.sessionId, {
-                type: 'system_note',
-                id: this.input.newId(),
-                turnId: this.turnId,
-                ts: lastTs,
-                kind: 'session_resume',
-            })
-                .catch(() => { });
-        }
         await this.finishRun(this.finalStatus, lastTs);
     }
-    async createRunRecord(continuation) {
-        if (!this.input.runStore) {
-            if (continuation)
-                throw new Error('Runtime continuation requires a durable run store');
-            return;
+    async openInvocation(continuation) {
+        if (!this.input.runStore && continuation) {
+            throw new Error('Runtime continuation requires a durable run store');
         }
-        const createdAt = continuation && this.input.claimedRunHeader
-            ? this.input.claimedRunHeader.createdAt
+        // The opening fact is a RuntimeEvent, so it opens whenever this run has a
+        // spine to open on. The operational ledger is a separate store with its own
+        // availability, and a run without one still exists.
+        if (!this.input.runtimeEventStore)
+            return;
+        const createdAt = continuation && this.input.claimedOpenedAt !== undefined
+            ? this.input.claimedOpenedAt
             : this.input.now();
-        const computedHeader = {
-            runId: this.runId,
-            invocationId: this.invocationId,
-            sessionId: this.sessionId,
-            turnId: this.turnId,
-            status: 'created',
-            backendKind: this.header.backend,
-            ...(this.header.llmConnectionId === undefined
-                ? {}
-                : { llmConnectionId: this.header.llmConnectionId }),
-            llmConnectionSlug: this.header.llmConnectionSlug,
-            modelId: this.header.model,
-            cwd: this.header.cwd,
-            ...(this.input.workspaceIdentity ? { workspaceIdentity: this.input.workspaceIdentity } : {}),
-            permissionMode: this.header.permissionMode,
-            collaborationMode: this.header.collaborationMode ?? 'agent',
-            orchestrationMode: this.effectiveOrchestration.mode,
-            orchestrationSource: this.effectiveOrchestration.source,
-            agentSwarmAuthorization: this.effectiveOrchestration.agentSwarmAuthorization,
-            toolMode: this.toolMode,
-            createdAt,
-            updatedAt: createdAt,
+        const providerStateIdentity = claimedProviderStateIdentity(this.input.claimedOpening) ?? this.providerStateIdentity;
+        this.providerStateIdentity = providerStateIdentity;
+        const computedOpening = this.buildInvocationOpening(continuation, providerStateIdentity);
+        if (continuation &&
+            this.input.claimedOpening &&
+            !isDeepStrictEqual(this.input.claimedOpening, computedOpening)) {
+            throw new Error('Claimed continuation target opening no longer matches execution');
+        }
+        this.invocationOpening = this.input.claimedOpening ?? computedOpening;
+        // A continuation's opening fact rides its continuation-start event, which
+        // the store requires to be event 1 of the target invocation. Every other
+        // invocation opens with its own event, committed before any provider or
+        // tool dispatch.
+        if (!continuation)
+            await this.commitInvocationOpening(createdAt);
+    }
+    /**
+     * The one immutable statement of how this invocation was opened.
+     *
+     * Everything a later reader needs to know about the run's route,
+     * configuration, root authority and lineage is decided here, once, and never
+     * restated anywhere else.
+     */
+    buildInvocationOpening(continuation, providerStateIdentity) {
+        const lineage = {
             ...this.lineage,
-            ...(continuation
-                ? {
-                    continuationSource: continuation.claimId && continuation.boundary
-                        ? {
-                            protocol: 'continuation_source_v2',
-                            claimId: continuation.claimId,
-                            boundaryDigest: continuation.boundary.manifestDigest,
-                            sourceInvocationId: continuation.sourceInvocationId,
-                            sourceRunId: continuation.sourceRunId,
-                            sourceTurnId: continuation.sourceTurnId,
-                            sourceRuntimeEventHighWater: continuation.sourceRuntimeEventHighWater,
-                            sourcePrefixDigest: continuation.boundary.segments.at(-1).prefixDigest,
-                            replayManifestDigest: continuation.boundary.manifestDigest,
-                        }
-                        : {
-                            sourceInvocationId: continuation.sourceInvocationId,
-                            sourceRunId: continuation.sourceRunId,
-                            sourceTurnId: continuation.sourceTurnId,
-                            sourceRuntimeEventHighWater: continuation.sourceRuntimeEventHighWater,
-                        },
-                }
-                : {}),
             ...(this.input.userInput.agentId ? { agentId: this.input.userInput.agentId } : {}),
             ...(this.input.userInput.agentName ? { agentName: this.input.userInput.agentName } : {}),
-            ...(this.input.userInput.origin?.kind === 'scheduled_task'
-                ? { scheduledTaskId: this.input.userInput.origin.scheduledTaskId }
-                : {}),
-            ...(this.input.userInput.origin?.kind === 'goal'
-                ? { goalId: this.input.userInput.origin.goalId }
-                : {}),
-            ...(this.input.userInput.origin?.kind === 'agent_graph'
+            ...(continuation ? { parentRunId: continuation.sourceRunId } : {}),
+        };
+        const opening = {
+            kind: 'invocation_opened',
+            protocol: 'invocation_opened_v1',
+            route: this.header.llmConnectionId === undefined
                 ? {
-                    agentGraphWakeId: this.input.userInput.origin.wakeId,
-                    agentGraphWakeAttemptId: this.input.userInput.origin.attemptId,
+                    provenance: 'unknown',
+                    backendKind: this.header.backend,
+                    llmConnectionSlug: this.header.llmConnectionSlug,
+                    modelId: this.header.model,
                 }
-                : {}),
-            ...(this.input.rootExecutionKind ? { rootExecutionKind: this.input.rootExecutionKind } : {}),
-        };
-        const header = continuation && this.input.claimedRunHeader ? this.input.claimedRunHeader : computedHeader;
-        if (continuation &&
-            this.input.claimedRunHeader &&
-            !isDeepStrictEqual(this.input.claimedRunHeader, computedHeader)) {
-            throw new Error('Claimed continuation target Run header no longer matches execution');
-        }
-        try {
-            const durable = this.requiresDurablePersistence();
-            await this.input.runStore.createRun(header, { durable });
-            await this.input.runStore.appendEvent(this.sessionId, this.runId, {
-                type: 'run_created',
-                id: this.input.newId(),
-                runId: this.runId,
-                sessionId: this.sessionId,
-                turnId: this.turnId,
-                ts: createdAt,
-                data: {
-                    textLength: this.input.userInput.text.length,
-                    attachmentCount: this.input.userInput.attachments?.length ?? 0,
-                    orchestrationMode: this.effectiveOrchestration.mode,
-                    orchestrationSource: this.effectiveOrchestration.source,
-                    agentSwarmAuthorization: this.effectiveOrchestration.agentSwarmAuthorization,
-                    toolMode: this.toolMode,
+                : {
+                    provenance: 'runtime',
+                    backendKind: this.header.backend,
+                    llmConnectionId: this.header.llmConnectionId,
+                    llmConnectionSlug: this.header.llmConnectionSlug,
+                    modelId: this.header.model,
+                    ...(providerStateIdentity ? { providerStateIdentity } : {}),
                 },
-            }, { durable });
+            configuration: {
+                cwd: this.header.cwd,
+                permissionMode: this.header.permissionMode,
+                collaborationMode: this.header.collaborationMode ?? 'agent',
+                orchestrationMode: this.effectiveOrchestration.mode,
+                orchestrationSource: this.effectiveOrchestration.source,
+                toolMode: this.toolMode,
+                ...(this.effectiveOrchestration.agentSwarmAuthorization !== undefined
+                    ? { agentSwarmAuthorization: this.effectiveOrchestration.agentSwarmAuthorization }
+                    : {}),
+                ...(this.input.workspaceIdentity
+                    ? { workspaceIdentity: this.input.workspaceIdentity }
+                    : {}),
+            },
+            root: this.invocationRootAuthority(),
+            source: continuation
+                ? {
+                    kind: 'continuation',
+                    sourceInvocationId: continuation.sourceInvocationId,
+                    sourceRunId: continuation.sourceRunId,
+                    sourceTurnId: continuation.sourceTurnId,
+                    sourceRuntimeEventHighWater: continuation.sourceRuntimeEventHighWater,
+                    ...(continuation.claimId ? { claimId: continuation.claimId } : {}),
+                    ...(continuation.boundary
+                        ? { boundaryDigest: continuation.boundary.manifestDigest }
+                        : {}),
+                }
+                : { kind: 'fresh' },
+            ...(Object.keys(lineage).length > 0 ? { lineage } : {}),
+        };
+        return continuation
+            ? preserveHandoffOpening(continuation, opening, this.input.handoffSourceOpening)
+            : opening;
+    }
+    invocationRootAuthority() {
+        const origin = this.input.userInput.origin;
+        if (origin?.kind === 'scheduled_task') {
+            return { kind: 'scheduled_task', scheduledTaskId: origin.scheduledTaskId };
         }
-        catch (error) {
-            this.runStoreAvailable = false;
-            if (this.requiresDurablePersistence())
-                throw error;
-            this.enqueueTraceWriteFailure(error);
-            if (continuation)
-                throw error;
+        if (origin?.kind === 'goal')
+            return { kind: 'goal', goalId: origin.goalId };
+        if (origin?.kind === 'agent_graph') {
+            return {
+                kind: 'agent_graph_supervisor_wake',
+                wakeId: origin.wakeId,
+                attemptId: origin.attemptId,
+            };
         }
+        if (this.input.rootExecutionKind === 'context_compact')
+            return { kind: 'context_compact' };
+        return { kind: 'user' };
+    }
+    /**
+     * Make the invocation's opening fact durable before anything can dispatch.
+     *
+     * It is the invocation's first event, so it also carries the protocol marker
+     * RecoveryResolver reads off event one.
+     */
+    async commitInvocationOpening(ts) {
+        const opening = this.invocationOpening;
+        if (!opening || this.invocationOpeningCommitted)
+            return;
+        await this.recordRuntimeEvents([
+            {
+                ...buildInvocationOpenedEvent({
+                    id: this.input.newId(),
+                    run: {
+                        sessionId: this.sessionId,
+                        invocationId: this.invocationId,
+                        runId: this.runId,
+                        turnId: this.turnId,
+                    },
+                    openedAt: ts,
+                    opening,
+                }),
+                ...(this.toolBoundaryProtocol
+                    ? { actions: { runtimeProtocol: { toolBoundary: this.toolBoundaryProtocol } } }
+                    : {}),
+            },
+        ], { requireDurableWrite: this.requiresDurablePersistence() });
+        this.invocationOpeningCommitted = true;
     }
     requiresDurablePersistence() {
         return this.input.durability === 'required';
@@ -908,181 +1233,34 @@ export class AgentRun {
             sessionId: this.sessionId,
             currentRunId: this.runId,
             currentTurnId: this.turnId,
-            runStore: this.input.runStore,
             runtimeEventStore: this.input.runtimeEventStore,
-            runStoreAvailable: this.runStoreAvailable,
             runtimeEventStoreAvailable: this.runtimeEventStoreAvailable,
-            repairRunRuntimeLedger: this.input.repairRunRuntimeLedger,
-            readMessages: () => this.input.store.readMessages(this.sessionId),
         });
     }
-    async markRunStarted(ts) {
-        if (!this.input.runStore || !this.runStoreAvailable)
-            return;
-        const durable = this.requiresDurablePersistence();
-        const write = this.enqueueRunStore('mark run started', async () => {
-            await this.input.runStore?.appendEvent(this.sessionId, this.runId, {
-                type: 'run_started',
-                id: this.input.newId(),
-                runId: this.runId,
-                sessionId: this.sessionId,
-                turnId: this.turnId,
-                ts,
-            }, { durable });
-            await this.input.runStore?.updateRun(this.sessionId, this.runId, { status: 'running', updatedAt: ts }, { durable });
-        }, { rethrow: durable });
-        if (durable)
-            await write;
-    }
-    async recordStatusFromTransition(ev, transition, ts) {
-        const durable = this.requiresDurablePersistence();
-        const runStore = this.input.runStore;
-        if (!runStore) {
-            if (durable) {
-                throw new Error('AgentRun store is unavailable for a required status transition');
-            }
-            return;
-        }
-        const status = transition.status === 'waiting_for_user'
-            ? 'waiting_for_user'
-            : transition.status === 'aborted'
-                ? 'cancelled'
-                : transition.status === 'blocked'
-                    ? 'failed'
-                    : transition.status === 'active'
-                        ? 'completed'
-                        : 'running';
-        if (isTerminalRunStatus(status))
-            return;
-        const appendAudit = async () => {
-            await runStore.appendEvent(this.sessionId, this.runId, {
-                type: 'run_status_changed',
-                id: this.input.newId(),
-                runId: this.runId,
-                sessionId: this.sessionId,
-                turnId: this.turnId,
-                ts,
-                data: {
-                    sessionStatus: transition.status,
-                    ...(transition.blockedReason ? { blockedReason: transition.blockedReason } : {}),
-                },
-            }, { durable });
-        };
-        if (durable) {
-            await this.enqueueRequiredRunStoreWrite('record required run status', async () => {
-                await runStore.updateRun(this.sessionId, this.runId, { status, updatedAt: ts }, { durable: true });
-            });
-            // The audit remains best-effort, but its physical write belongs to this
-            // required transition and must settle before the resume acknowledgement.
-            await this.enqueueRunStore('append run status audit', appendAudit);
-        }
-        else {
-            this.enqueueRunStore('record run status', async () => {
-                await runStore.updateRun(this.sessionId, this.runId, { status, updatedAt: ts });
-                await appendAudit();
-            });
-        }
-        if (ev.type === 'abort') {
-            this.markRunCancelled(ev.reason, ts);
-        }
-    }
-    markRunFailed(failureClass, message, ts) {
-        if (!this.input.runStore || !this.runStoreAvailable)
-            return;
+    /**
+     * Remember why this run is going to fail.
+     *
+     * Preserve diagnostic text without trace redaction, within the byte budget.
+     * Nothing is written here: the terminal RuntimeEvent carries the failure, and
+     * it is committed once, at the end, by `commitTerminalRun`.
+     */
+    markRunFailed(failureClass, message) {
         this.failureClass = failureClass;
-        this.failureMessage = redactTraceString(message);
-        if (this.input.runtimeEventStore)
-            return;
-        this.enqueueRunStore('mark run failed', async () => {
-            await this.input.runStore?.updateRun(this.sessionId, this.runId, {
-                status: 'failed',
-                updatedAt: ts,
-                completedAt: ts,
-                failureClass,
-                failureMessage: this.failureMessage,
-            });
-            await this.input.runStore?.appendEvent(this.sessionId, this.runId, {
-                type: 'run_failed',
-                id: this.input.newId(),
-                runId: this.runId,
-                sessionId: this.sessionId,
-                turnId: this.turnId,
-                ts,
-                message: redactTraceString(message),
-                data: { failureClass },
-            });
-        });
-    }
-    markRunCancelled(reason, ts) {
-        if (!this.input.runStore || !this.runStoreAvailable)
-            return;
-        if (this.input.runtimeEventStore)
-            return;
-        this.enqueueRunStore('mark run cancelled', async () => {
-            await this.input.runStore?.updateRun(this.sessionId, this.runId, {
-                status: 'cancelled',
-                updatedAt: ts,
-                completedAt: ts,
-            });
-            await this.input.runStore?.appendEvent(this.sessionId, this.runId, {
-                type: 'run_cancelled',
-                id: this.input.newId(),
-                runId: this.runId,
-                sessionId: this.sessionId,
-                turnId: this.turnId,
-                ts,
-                ...(reason ? { message: redactTraceString(reason) } : {}),
-            });
-        });
+        this.failureMessage = truncateUtf8(message, MODEL_FAILURE_MESSAGE_MAX_BYTES, '…');
     }
+    /**
+     * End the run by committing its terminal RuntimeEvent, and nothing else.
+     *
+     * A turn that parks on an interaction has not ended, so it commits nothing:
+     * the absence of a terminal event is exactly what "still open" means.
+     */
     async finishRun(finalStatus, ts) {
         await this.traceQueue.catch(() => { });
-        if (!this.input.runStore || !this.runStoreAvailable)
+        if (!this.input.runtimeEventStore)
             return;
-        const status = this.runStatusForFinalStatus(finalStatus);
-        const isTerminal = status === 'completed' || status === 'failed' || status === 'cancelled';
-        if (isTerminal && this.input.runtimeEventStore) {
-            await this.commitTerminalRun(finalStatus, ts);
+        if (this.runStatusForFinalStatus(finalStatus) === 'waiting_for_user')
             return;
-        }
-        await this.enqueueRunStore('finish run', async () => {
-            await this.input.runStore?.updateRun(this.sessionId, this.runId, {
-                status,
-                updatedAt: ts,
-                ...(isTerminal ? { completedAt: ts } : {}),
-                ...(status === 'failed'
-                    ? {
-                        failureClass: this.failureClass ?? finalStatus?.blockedReason ?? 'unknown',
-                        ...(this.failureMessage ? { failureMessage: this.failureMessage } : {}),
-                    }
-                    : {}),
-            });
-            await this.input.runStore?.appendEvent(this.sessionId, this.runId, {
-                type: status === 'cancelled'
-                    ? 'run_cancelled'
-                    : status === 'failed'
-                        ? 'run_failed'
-                        : status === 'completed'
-                            ? 'run_completed'
-                            : 'run_status_changed',
-                id: this.input.newId(),
-                runId: this.runId,
-                sessionId: this.sessionId,
-                turnId: this.turnId,
-                ts,
-                ...(status === 'failed'
-                    ? { data: { failureClass: this.failureClass ?? finalStatus?.blockedReason ?? 'unknown' } }
-                    : status === 'waiting_for_user'
-                        ? {
-                            data: {
-                                sessionStatus: 'waiting_for_user',
-                                blockedReason: finalStatus?.blockedReason ?? 'permission_required',
-                            },
-                        }
-                        : {}),
-            });
-        });
-        await this.traceQueue.catch(() => { });
+        await this.commitTerminalRun(finalStatus, ts);
     }
     runStatusForFinalStatus(finalStatus) {
         if (this.stopped || finalStatus?.status === 'aborted')
@@ -1094,11 +1272,10 @@ export class AgentRun {
         return 'completed';
     }
     async commitTerminalRun(finalStatus, ts) {
-        if (this.terminalRunHeaderCommitted)
+        if (this.terminalRunFactCommitted)
             return;
-        const runStore = this.input.runStore;
         const runtimeEventStore = this.input.runtimeEventStore;
-        if (!runStore || !runtimeEventStore)
+        if (!runtimeEventStore)
             return;
         // A latched RuntimeEvent store normally keeps the skip below: the latch
         // marks a write failure, and a transient one leaves the run non-terminal
@@ -1116,8 +1293,6 @@ export class AgentRun {
                 return;
             corruptionRecovery = true;
         }
-        if (!this.runStoreAvailable)
-            return;
         const fallbackStatus = this.stopped || finalStatus?.status === 'aborted' ? 'cancelled' : 'failed';
         const fallbackFailureClass = 'missing_terminal_event';
         const fallbackFailureMessage = this.failureMessage ?? 'run finalized without a terminal RuntimeEvent';
@@ -1142,9 +1317,8 @@ export class AgentRun {
             // Re-check after the await, not only at entry. Two callers — a stop
             // settling the claim and the stream's own finalize — can both pass the
             // entry guard and then queue behind the same write. The claim slot
-            // dedupes the RuntimeEvent, but the run-store projection would append a
-            // second terminal AgentRunEvent for the one run.
-            if (this.terminalRunHeaderCommitted)
+            // dedupes the RuntimeEvent, so a second pass has nothing left to do.
+            if (this.terminalRunFactCommitted)
                 return;
             // On the recovery path the claimed event's write never committed, so
             // the boundary named after that commit must wait for the durability
@@ -1156,7 +1330,6 @@ export class AgentRun {
                 await this.input.continuationFailpoint?.('after_terminal_event_committed');
             }
             const commit = commitOrCreateTerminalRunFact({
-                runStore,
                 runtimeEventStore,
                 ...(this.continuationActive && deferContinuationBoundary
                     ? {
@@ -1175,27 +1348,19 @@ export class AgentRun {
                     ? { failureClass: this.failureClass ?? finalStatus?.blockedReason }
                     : {}),
                 ...(this.failureMessage ? { failureMessage: this.failureMessage } : {}),
-                ...(this.traceWriteError ? { traceWriteError: this.traceWriteError } : {}),
                 ...(this.abortSource || fallbackStatus === 'cancelled'
                     ? { abortSource: this.abortSource ?? 'user_stop' }
                     : {}),
                 fallbackStatus,
                 fallbackInvocationId: this.runId,
                 ...(fallbackStatus === 'failed' ? { fallbackFailureClass, fallbackFailureMessage } : {}),
-                allowHeaderCommitFailure: true,
             });
             if (!terminalClaim.write) {
                 terminalClaim.write = commit.then(() => undefined);
                 void terminalClaim.write.catch(() => { });
             }
-            const result = await commit;
-            this.terminalRunHeaderCommitted = result.headerCommitted;
-            if (result.headerCommitted && this.continuationActive) {
-                await this.input.continuationFailpoint?.('after_terminal_header_committed');
-            }
-            if (result.headerCommitError !== undefined) {
-                await this.enqueueTraceWriteFailure(result.headerCommitError, 'commit terminal run header');
-            }
+            await commit;
+            this.terminalRunFactCommitted = true;
         }
         catch (error) {
             if (corruptionRecovery) {
@@ -1203,11 +1368,11 @@ export class AgentRun {
                 // terminal fact. The latch never lifted, so there is nothing to
                 // restore; record the failure and keep the finalize path's
                 // historical silence for a store that stays broken.
-                await this.enqueueTraceWriteFailure(error, 'commit terminal run header');
+                await this.enqueueTraceWriteFailure(error, 'commit terminal run fact');
                 return;
             }
             this.runStoreAvailable = false;
-            await this.enqueueTraceWriteFailure(error, 'commit terminal run header');
+            await this.enqueueTraceWriteFailure(error, 'commit terminal run fact');
             throw error;
         }
         await this.traceQueue.catch(() => { });
@@ -1249,18 +1414,6 @@ export class AgentRun {
         this.traceQueue = next.catch(() => { });
         return next;
     }
-    /**
-     * Each physical provider request gets its own best-effort diagnostic row.
-     * One failed attempt append must not suppress later attempts or poison the
-     * general AgentRun store latch; a required capture independently gates every
-     * provider dispatch.
-     */
-    enqueueBestEffortProviderAttempt(label, operation) {
-        const next = this.traceQueue
-            .then(operation, operation)
-            .catch((error) => this.enqueueTraceWriteFailure(error, label));
-        this.traceQueue = next.catch(() => { });
-    }
     /**
      * Serialize a required Run-store write without consulting the best-effort
      * latch. A successful required write proves the store is available again;
@@ -1420,15 +1573,6 @@ export class AgentRun {
     async enqueueTraceWriteFailure(error, label = 'agent run store write') {
         const message = errorMessage(error);
         this.traceWriteError ??= `${label}: ${message}`;
-        try {
-            await this.input.runStore?.updateRun(this.sessionId, this.runId, {
-                traceWriteError: this.traceWriteError,
-                updatedAt: this.input.now(),
-            });
-        }
-        catch {
-            // The terminal header commit retries the in-memory latch.
-        }
         try {
             await this.input.runStore?.appendEvent(this.sessionId, this.runId, {
                 type: 'trace_write_failed',
@@ -1515,20 +1659,19 @@ function redactTraceString(value) {
 function errorMessage(error) {
     return redactTraceString(error instanceof Error ? error.message : String(error));
 }
-async function appendUserMessageOnce(store, sessionId, message) {
-    const existing = (await store.readMessages(sessionId)).find((candidate) => candidate.id === message.id);
-    if (!existing) {
-        await store.appendMessage(sessionId, message);
-        return;
-    }
-    if (existing.type !== 'user' ||
-        existing.turnId !== message.turnId ||
-        !messageContentsEqual(existing, message)) {
-        throw new Error(`Durable UserMessage identity ${message.id} has conflicting content`);
-    }
+function sameRequestCompositionSurface(current, candidate) {
+    const { schemaVersion: _schemaVersion, compositionId: _compositionId, step: _step, reason: _reason, ...currentSurface } = current;
+    const { schemaVersion: _candidateSchemaVersion, compositionId: _candidateCompositionId, step: _candidateStep, reason: _candidateReason, ...candidateSurface } = candidate;
+    return isDeepStrictEqual(currentSurface, candidateSurface);
+}
+function requestCompositionSurfaceHash(snapshot) {
+    const { schemaVersion: _schemaVersion, compositionId: _compositionId, step: _step, reason: _reason, ...surface } = snapshot;
+    return stableHash(surface);
 }
 function isInteractionResumeAck(event) {
-    return (event.type === 'sandbox_boundary_decision_ack' || event.type === 'user_question_answer_ack');
+    return (event.type === 'sandbox_boundary_decision_ack' ||
+        event.type === 'user_question_answer_ack' ||
+        event.type === 'form_answer_ack');
 }
 /**
  * Non-terminal error content never reaches the ledger: the trailing terminal
@@ -1543,3 +1686,8 @@ function isAtomicToolBoundaryProjection(event, protocol) {
         return false;
     return event.content?.kind === 'function_call' || event.content?.kind === 'function_response';
 }
+/** The provider endpoint identity a continuation claim froze, if it named one. */
+function claimedProviderStateIdentity(opening) {
+    const route = opening?.route;
+    return route?.provenance === 'runtime' ? route.providerStateIdentity : undefined;
+}