@gajae-code/coding-agent 0.16.3 → 0.16.6

package/src/sdk/host/session-runtime.ts

@@ -4,7 +4,7 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { promisify } from "node:util";
-import { ThinkingLevel } from "@gajae-code/agent-core";
+import { isContinuingMidRunMaintenanceOutcome, ThinkingLevel } from "@gajae-code/agent-core";
 import type { Api, ImageContent, Model } from "@gajae-code/ai/core";
 import { logger } from "@gajae-code/utils";
 import { AsyncJobManager } from "../../async";
@@ -27,7 +27,10 @@ import { resolveModelChainWithAuth, splitSelectorThinkingSuffix } from "../../co
 import { type ModelSelectorValue, normalizeModelSelectorValue } from "../../config/model-selector-value";
 import { type Settings, validateSettingPatch } from "../../config/settings";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "../../extensibility/extensions";
+import type { AgentEndEvent } from "../../extensibility/shared-events";
 import { normalizeGoal } from "../../goals/state";
+import { toAgentWireEventPayload } from "../../modes/shared/agent-wire/event-envelope";
+import type { AgentSessionEvent } from "../../session/agent-session";
 import type { SdkRunCapability } from "../../session/sdk-run-capability";
 import {
 	boundTerminalRetentionState,
@@ -192,6 +195,24 @@ class DiffQueryError extends Error {
 	}
 }
 
+/**
+ * Normalize an agent-loop stop reason into the published terminal outcome.
+ *
+ * Only reached for a boundary that actually terminalizes an owned invocation,
+ * so every result is a `stopped` disposition: a failed run publishes its own
+ * correlated `agent_failed` frame with the sanitized cause instead.
+ */
+export function terminalStoppedOutcome(
+	stopReason: AgentEndEvent["stopReason"],
+	maintenanceOutcome: string | undefined,
+): Extract<SdkPromptTerminalOutcome, { kind: "stopped" }> {
+	// An aborted maintenance checkpoint is the one maintenance path that really
+	// ends the run, and it ends it the same way an explicit stop does.
+	return stopReason === "cancelled" || maintenanceOutcome === "aborted"
+		? { kind: "stopped", reason: "cancelled", provenance: "client_cancel" }
+		: { kind: "stopped", reason: "end_turn", provenance: "agent" };
+}
+
 /** Transport-neutral endpoint contract consumed by the SDK session runtime. */
 export interface SessionSdkTransport {
 	readonly sessionId: string;
@@ -395,6 +416,26 @@ export class SessionSdkSessionRuntime {
 		this.transport.broadcastFrame?.(event);
 	}
 
+	/**
+	 * Deliver a frame to specific connections without recording it.
+	 *
+	 * Deliberately not `emitEvent`: that assigns a ring position and broadcasts to
+	 * every authenticated socket. Streamed turn content is high-frequency and
+	 * unbounded in size, so a count-bounded ring would evict the lifecycle events
+	 * clients depend on -- including the `agent_end` that settles their prompt --
+	 * and broadcasting would hand every subscriber a stream only the submitter
+	 * asked for. Delivery failure is ignored: a disconnected consumer must never
+	 * disturb the turn producing the content.
+	 */
+	sendFrameTo(connectionId: string, frame: SdkFrame): void {
+		try {
+			const result = this.transport.sendFrame(connectionId, frame);
+			if (result instanceof Promise) result.catch(() => undefined);
+		} catch {
+			// A dead connection is reaped by the transport's own close handling.
+		}
+	}
+
 	publish(frame: SdkFrame): void {
 		this.emitEvent(frame);
 	}
@@ -448,13 +489,13 @@ export class SessionSdkSessionRuntime {
 		}
 	}
 
-	async stop(): Promise<void> {
+	async stop(options: { allowLockContention?: boolean } = {}): Promise<void> {
 		this.#connectionDisposer?.();
 		this.#capabilitiesDisposer?.();
 		this.#malformedDisposer?.();
 		let hostError: unknown;
 		try {
-			await this.host.stop();
+			await this.host.stop(options);
 		} catch (error) {
 			hostError = error;
 		} finally {
@@ -577,6 +618,8 @@ function canonicalTerminalOutcome(
 		if (candidate.kind === "stopped") {
 			if (candidate.reason === "cancelled" && candidate.provenance === "client_cancel")
 				return { kind: "stopped", reason: "cancelled", provenance: "client_cancel" };
+			if (candidate.reason === "end_turn" && candidate.provenance === "agent")
+				return { kind: "stopped", reason: "end_turn", provenance: "agent" };
 			return undefined;
 		}
 		if (candidate.kind === "failed")
@@ -2239,6 +2282,7 @@ function createControlSurface(
 	canResolveGate: () => boolean = () => true,
 	trackGateResolution: <T>(resolution: Promise<T>) => Promise<T> = async resolution => await resolution,
 	onInvocationCompletionReconciledForTests?: (kind: InvocationKind, correlation: InvocationCorrelation) => void,
+	publishLifecycleFrame?: (frame: SdkFrame) => void,
 ): ControlSurface {
 	const normalizePromptImages = (value: unknown): ImageContent[] => {
 		if (!Array.isArray(value)) return [];
@@ -2376,6 +2420,24 @@ function createControlSurface(
 		const correlation = newCorrelation();
 		const sdkRunToken = `${correlation.commandId}:${correlation.turnId}`;
 		const sdkRunCapability = createSdkRunCapability(sdkRunToken);
+		const publishTerminal = (outcome: InvocationOutcome): void => {
+			publishLifecycleFrame?.({
+				type: "agent_end",
+				sessionId: ctx.sessionManager.getSessionId(),
+				...correlation,
+				outcome,
+			});
+		};
+		const publishFailure = (error: unknown): void => {
+			const failure = sanitizePromptFailure(error);
+			publishLifecycleFrame?.({
+				type: "agent_failed",
+				sessionId: ctx.sessionManager.getSessionId(),
+				...correlation,
+				error: failure,
+			});
+			publishTerminal(canonicalFailedOutcome(failure));
+		};
 		const preflight = Promise.withResolvers<void>();
 		let accepted = false;
 		let settled = false;
@@ -2484,11 +2546,25 @@ function createControlSurface(
 							retirePendingOwner?.(kind, correlation);
 							const attemptTerminalization = async (remaining: number): Promise<void> => {
 								try {
+									const before = reconciliation.lookup(kind, correlation) as {
+										status?: string;
+									};
+									const alreadyTerminal = before.status === "terminal_ok" || before.status === "failed";
 									await reconciliation.noteTransition(kind, correlation, {
 										type: "agent_end",
 										...(typeof result === "string" ? { content: sanitizeTurnResultContent(result) } : {}),
 									});
 									onInvocationCompletionReconciledForTests?.(kind, correlation);
+									if (!alreadyTerminal) {
+										const settledRecord = reconciliation.lookup(kind, correlation) as {
+											status?: string;
+											outcome?: unknown;
+											error?: { code?: unknown; message?: unknown };
+										};
+										const outcome = canonicalTerminalOutcome(settledRecord.outcome, settledRecord.error);
+										if (outcome?.kind === "failed") publishFailure(settledRecord.error ?? outcome);
+										else if (outcome) publishTerminal(outcome);
+									}
 									retirePendingOwner?.(kind, correlation, "always");
 								} catch (transitionError) {
 									if (kind === "prompt" || kind === "skill") {
@@ -2550,6 +2626,19 @@ function createControlSurface(
 							// so their recovery owner is this bounded in-place retry loop: the same
 							// order, retried, until both writes land or the budget is spent.
 							const attemptRejectionTerminalization = async (remaining: number): Promise<void> => {
+								// AgentSession can reject cleanup after its durable terminal was published.
+								// That rejection is diagnostic, not another outcome for this correlation.
+								const record = reconciliation.lookup(kind, correlation) as { status?: string };
+								if (record.status === "terminal_ok" || record.status === "failed") {
+									logger.warn("SDK submission cleanup failed after terminal publication", {
+										kind,
+										commandId: correlation.commandId,
+										turnId: correlation.turnId,
+										error: sanitizePromptFailure(error),
+									});
+									retirePendingOwner?.(kind, correlation, "always");
+									return;
+								}
 								try {
 									await reconciliation.noteTransition(kind, correlation, { type: "agent_failed", error });
 								} catch {
@@ -2585,6 +2674,7 @@ function createControlSurface(
 								}
 								try {
 									await reconciliation.noteTransition(kind, correlation, { type: "agent_end" });
+									publishFailure(error);
 								} catch (transitionError) {
 									if (kind === "prompt" || kind === "skill") {
 										retirePendingOwner?.(
@@ -3940,7 +4030,11 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				waitForGateResolutionQuiescence: () => Promise<void>;
 				activeInvocation?: { kind: InvocationKind; correlation: InvocationCorrelation };
 				drainedInvocations?: Array<{ kind: InvocationKind; correlation: InvocationCorrelation }>;
-				attachedInvocations?: Array<{ kind: InvocationKind; correlation: InvocationCorrelation }>;
+				attachedInvocations?: Array<{
+					kind: InvocationKind;
+					correlation: InvocationCorrelation;
+					connectionId: string | undefined;
+				}>;
 				openLifecycleBatches: Array<{
 					epoch: number;
 					invocations: Array<{
@@ -3949,7 +4043,27 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 						connectionId: string | undefined;
 						sdkRunToken: string;
 					}>;
-					attachedInvocations: Array<{ kind: InvocationKind; correlation: InvocationCorrelation }>;
+					attachedInvocations: Array<{
+						kind: InvocationKind;
+						correlation: InvocationCorrelation;
+						connectionId: string | undefined;
+					}>;
+					/**
+					 * Content frames observed before this batch's correlated agent_start
+					 * reached the wire. The synchronous session subscription can see a
+					 * message_update before emitLifecycle finishes awaiting durable start
+					 * persistence; holding them here keeps the producer's start/content
+					 * boundary for every SDK consumer. Each entry carries the recipients
+					 * that owned the run when the event was produced: an owner attached
+					 * later must not receive content from before its attachment.
+					 */
+					startPublished: boolean;
+					/** Set once the hold bound dropped content for this batch; gates the single warning. */
+					heldContentDropped: boolean;
+					heldContent: Array<{
+						event: AgentSessionEvent;
+						recipients: Array<{ correlation: InvocationCorrelation; connectionId: string | undefined }>;
+					}>;
 				}>;
 				disposeGate?: () => void;
 				lifecycleActive: boolean;
@@ -4133,6 +4247,56 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		owner.lifecycleTasks.add(task);
 		return task;
 	};
+	/**
+	 * Publish one content frame per owning invocation, each carrying its own
+	 * correlation, so a shared run lets every submitter attribute the content to
+	 * its own prompt. Content is best-effort and bypasses the lifecycle replay
+	 * ring; the turn producing it is authoritative.
+	 */
+	const publishContentFrames = (
+		current: RuntimeState,
+		event: AgentSessionEvent,
+		invocations: ReadonlyArray<{ correlation: InvocationCorrelation; connectionId: string | undefined }>,
+	): void => {
+		try {
+			const payload = toAgentWireEventPayload(event);
+			for (const invocation of invocations) {
+				if (invocation.connectionId === undefined) continue;
+				current.runtime.sendFrameTo(invocation.connectionId, {
+					type: "event",
+					kind: event.type,
+					payload,
+					...invocation.correlation,
+				});
+			}
+		} catch {
+			// Streamed content is best-effort; the turn producing it is authoritative.
+		}
+	};
+	/**
+	 * Upper bound on content events held for one batch while its correlated
+	 * agent_start is still being durably recorded. A start write normally settles
+	 * in milliseconds, so this is only reached when persistence is wedged. Past
+	 * the bound the OLDEST held content is dropped (with one warning per batch):
+	 * content is never published before its start, so a wedged write degrades
+	 * to a gap in the stream, not an inverted start/content boundary, and it
+	 * can never accumulate an entire response in memory. The turn's terminal
+	 * result remains authoritative for anything a consumer did not see.
+	 */
+	const MAX_HELD_CONTENT_EVENTS = 256;
+	/**
+	 * Release content that arrived before the batch's correlated agent_start
+	 * reached the wire. Called once per batch, after the start frames are
+	 * published (or after the start publication path gave up), so SDK consumers
+	 * observe start before any content, in producer order.
+	 */
+	const releaseHeldContent = (current: RuntimeState, batch: LifecycleBatch): void => {
+		if (batch.startPublished) return;
+		batch.startPublished = true;
+		const held = batch.heldContent;
+		batch.heldContent = [];
+		for (const { event, recipients } of held) publishContentFrames(current, event, recipients);
+	};
 	const emitLifecycle = async (
 		type: "agent_start" | "agent_end" | "agent_failed",
 		ctx: ExtensionContext,
@@ -4142,6 +4306,9 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		terminalContent?: TurnResultContent,
 		terminalHasActivity = false,
 		terminalOutcome?: InvocationOutcome,
+		stopReason?: AgentEndEvent["stopReason"],
+		startToken?: string,
+		startTokens?: string[],
 	): Promise<void> => {
 		const current = lifecycleOwner?.state ?? active;
 		if (!current) return;
@@ -4216,19 +4383,46 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			// turn (queued-while-streaming submissions never push), so a mid-prompt
 			// continuation agent_start with an empty queue leaves the current owner
 			// untouched (review thread P1).
-			const drained = current.pending
-				.splice(0)
+			const cohort = new Set(startTokens);
+			if (startToken) cohort.add(startToken);
+			const matchingPending =
+				cohort.size > 0 ? current.pending.filter(entry => cohort.has(entry.sdkRunToken)) : current.pending.slice();
+			const matchingKeys = new Set(matchingPending.map(entry => entry.sdkRunToken));
+			const pendingSnapshot = current.pending.splice(0);
+			const drained = pendingSnapshot
+				.filter(entry => matchingKeys.has(entry.sdkRunToken))
 				.filter(entry => entry.kind !== "prompt" || !current.deadlineManager.isExpiring(entry.correlation));
+			current.pending.push(...pendingSnapshot.filter(entry => !matchingKeys.has(entry.sdkRunToken)));
+			const existingTokenBatch =
+				typeof startToken === "string" && startToken.length > 0
+					? lifecycleRunOwners.get(startToken)?.batch
+					: undefined;
 			if (drained.length > 0) {
-				current.openLifecycleBatches.push({
+				const batch: LifecycleBatch = {
 					epoch: current.lifecycleEpoch,
 					invocations: drained,
 					attachedInvocations: [],
-				});
+					startPublished: false,
+					heldContentDropped: false,
+					heldContent: [],
+				};
+				current.openLifecycleBatches.push(batch);
+				for (const entry of drained) {
+					lifecycleRunOwners.set(entry.sdkRunToken, {
+						state: current,
+						batch,
+						correlationKey: lifecycleCorrelationKey(entry.correlation),
+					});
+				}
 				adoptLifecycleBatch(drained);
 				if (current.activeInvocation?.kind === "prompt") {
 					current.deadlineManager.onAccepted(current.activeInvocation.correlation);
 				}
+			} else if (existingTokenBatch && current.openLifecycleBatches.includes(existingTokenBatch)) {
+				// A continuation within the same SDK-owned run carries the same token
+				// but has no newly pending invocation. Preserve the established owner so
+				// later chunks and the final terminal remain directed to its submitters.
+				adoptLifecycleBatch(existingTokenBatch.invocations);
 			} else {
 				// An empty drain is an agent-initiated successor run. Clear the
 				// predecessor's SDK owner and active invocation so abort ownership and
@@ -4240,7 +4434,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			// Pair this agent_end with the oldest unmatched start. A delayed
 			// aborted-turn end that lands after a successor agent_start must
 			// terminalize the aborted invocation, never the successor.
-			const ended = current.openLifecycleBatches[0];
+			const ended = failureBatch ?? current.openLifecycleBatches[0];
 			const baseTransitions = ended
 				? ended.invocations.map(({ kind, correlation }) => ({ kind, correlation }))
 				: current.activeInvocation
@@ -4364,7 +4558,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			};
 			void attempt().finally(() => skillTerminalRecoveryControllers.delete(recoveryKey));
 		};
-		if (type === "agent_end" && maintenanceOutcome !== undefined && maintenanceOutcome !== "aborted") {
+		if (type === "agent_end" && isContinuingMidRunMaintenanceOutcome(maintenanceOutcome)) {
 			try {
 				current.runtime.emitEvent({ type, sessionId: ctx.sessionManager.getSessionId() });
 			} catch {
@@ -4485,7 +4679,50 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 						observed = false;
 					}
 				}
+			} else if (type === "agent_start" && transitions.length > 0) {
+				for (const invocation of transitions) {
+					try {
+						current.runtime.emitEvent({ type, sessionId, ...invocation.correlation });
+					} catch {
+						observed = false;
+					}
+				}
+				// The start frames are on the wire (or definitively failed); content
+				// that the synchronous session subscription observed meanwhile must
+				// follow them, never precede them.
+				const started = current.openLifecycleBatches.find(candidate =>
+					candidate.invocations.some(entry =>
+						transitions.some(
+							({ correlation }) =>
+								correlation.commandId === entry.correlation.commandId &&
+								correlation.turnId === entry.correlation.turnId,
+						),
+					),
+				);
+				if (started) releaseHeldContent(current, started);
+			} else if (type === "agent_end" && transitions.length > 0) {
+				// An invocation-owned terminal must carry the identity it was accepted
+				// under and the normalized outcome. A client that submitted this turn
+				// matches the terminal against its own acknowledged correlation and
+				// refuses an unowned one, so the bare `{ type, sessionId }` boundary left
+				// every externally submitted prompt reporting `working` forever even
+				// though the turn had finished -- ACP dropped it as
+				// `incomplete_correlation`, and the notifications runtime has always
+				// stamped both fields for exactly this reason. One frame per invocation,
+				// matching the agent_failed shape above, also lets a shared run attribute
+				// the boundary to each owner instead of one signal nobody can claim. A
+				// continuing maintenance checkpoint never reaches this branch: it returned
+				// above with the one uncorrelated frame, so it cannot settle a live prompt.
+				const outcome = terminalOutcome ?? terminalStoppedOutcome(stopReason, maintenanceOutcome);
+				for (const invocation of transitions) {
+					try {
+						current.runtime.emitEvent({ type, sessionId, ...invocation.correlation, outcome });
+					} catch {
+						observed = false;
+					}
+				}
 			} else {
+				// Host-originated runs without an invocation keep an uncorrelated frame.
 				try {
 					current.runtime.emitEvent({ type, sessionId });
 				} catch {
@@ -4495,7 +4732,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		} catch {
 			observed = false;
 		}
-		if (type === "agent_end" && maintenanceOutcome !== undefined && maintenanceOutcome !== "aborted") return;
+		if (type === "agent_end" && isContinuingMidRunMaintenanceOutcome(maintenanceOutcome)) return;
 		if (type === "agent_end") {
 			if (current.lifecycleEpoch !== eventLifecycleEpoch) {
 				// A successor agent_start won the lifecycle race while this event's
@@ -4553,29 +4790,23 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 	};
 	api.on("agent_start", (event, ctx) => {
 		const owner = lifecycleStateForEvent(ctx, "agent_start", event.sdkRunToken);
-		return trackLifecycle(async () => {
-			await emitLifecycle(
-				"agent_start",
-				ctx,
-				undefined,
-				undefined,
-				owner ? { state: owner, sessionId: owner.sessionId } : undefined,
-			);
-			if (owner && typeof event.sdkRunToken === "string" && event.sdkRunToken.length > 0) {
-				const batch = owner.openLifecycleBatches.at(-1);
-				const entry = batch?.invocations.find(item => item.sdkRunToken === event.sdkRunToken);
-				const previous = lifecycleRunOwners.get(event.sdkRunToken);
-				lifecycleRunOwners.set(event.sdkRunToken, {
-					state: owner,
-					batch,
-					...(previous?.correlationKey !== undefined
-						? { correlationKey: previous.correlationKey }
-						: entry
-							? { correlationKey: lifecycleCorrelationKey(entry.correlation) }
-							: {}),
-				});
-			}
-		}, owner);
+		return trackLifecycle(
+			async () =>
+				emitLifecycle(
+					"agent_start",
+					ctx,
+					undefined,
+					undefined,
+					owner ? { state: owner, sessionId: owner.sessionId } : undefined,
+					undefined,
+					false,
+					undefined,
+					undefined,
+					typeof event.sdkRunToken === "string" ? event.sdkRunToken : undefined,
+					event.sdkRunTokens,
+				),
+			owner,
+		);
 	});
 	api.on("agent_end", (event, ctx) => {
 		const tokenBinding =
@@ -4608,11 +4839,20 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		const failureAlreadyPublished = failure === undefined || (hasExistingFailure && genericFailureKeys.length === 0);
 		const terminalEvidence = promptTerminalEvidenceFromAgentEnd(event);
 		const terminalOutcome =
-			event.stopReason === "cancelled"
-				? ({ kind: "stopped", reason: "cancelled", provenance: "client_cancel" } as const)
-				: failure === undefined
-					? undefined
-					: canonicalFailedOutcome(failure);
+			event.stopReason === "cancelled" ||
+			(event.stopReason === "maintenance" && event.maintenanceOutcome === "aborted")
+				? terminalStoppedOutcome(
+						event.stopReason,
+						event.stopReason === "maintenance" ? event.maintenanceOutcome : undefined,
+					)
+				: failure !== undefined
+					? canonicalFailedOutcome(failure)
+					: terminalEvidence.content?.text.trim() || terminalEvidence.hasActivity
+						? terminalStoppedOutcome(
+								event.stopReason,
+								event.stopReason === "maintenance" ? event.maintenanceOutcome : undefined,
+							)
+						: canonicalFailedOutcome(EMPTY_PROMPT_FAILURE);
 		return trackLifecycle(async () => {
 			if (failure && !failureAlreadyPublished) {
 				for (const key of genericFailureKeys) owner?.failureDiagnosticKeys.delete(key);
@@ -4627,6 +4867,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				terminalEvidence.content,
 				terminalEvidence.hasActivity,
 				terminalOutcome,
+				event.stopReason,
 			);
 		}, owner).finally(() => {
 			if (typeof event.sdkRunToken === "string" && lifecycleRunOwners.get(event.sdkRunToken)?.state === owner)
@@ -4716,6 +4957,74 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				current.deadlineManager.onAttributableEvent(invocation.correlation, eventType);
 		}
 	};
+	/**
+	 * Stream one turn event to the connections that submitted the running turn.
+	 *
+	 * This is the same frame the notifications runtime sends for an ACP-launched
+	 * session (`{ type: "event", kind, payload: { event_type, event }, ...correlation }`),
+	 * built from the same shared producer, so an ACP client attached to a live
+	 * interactive session renders assistant text and tool calls exactly as it does
+	 * for a session it started itself. Without it an attached client could drive
+	 * the session and see the turn settle but never receive a single word of the
+	 * answer.
+	 *
+	 * Scoped to the owning invocations of the batch that is actually running: a
+	 * turn nobody submitted over the SDK (an ordinary terminal prompt, an
+	 * autonomous continuation, cron, monitor) has no owner connection and streams
+	 * nothing at all, so a session with no attached client pays one map lookup.
+	 */
+	const STREAMED_TURN_EVENT_TYPES: ReadonlySet<string> = new Set([
+		"message_update",
+		"message_end",
+		"tool_execution_start",
+		"tool_execution_update",
+		"tool_execution_end",
+	]);
+	const streamTurnEvent = (event: AgentSessionEvent | null | undefined, ctx: ExtensionContext): void => {
+		const current = lifecycleStateForContext(ctx, "agent_start");
+		const activeInvocation = current?.activeInvocation;
+		if (!current) return;
+		const batch = activeInvocation
+			? current.openLifecycleBatches.find(candidate =>
+					candidate.invocations.some(
+						entry =>
+							entry.correlation.commandId === activeInvocation.correlation.commandId &&
+							entry.correlation.turnId === activeInvocation.correlation.turnId,
+					),
+				)
+			: undefined;
+		const invocations = batch
+			? [...batch.invocations, ...batch.attachedInvocations]
+			: current.lifecycleActive
+				? (current.attachedInvocations ?? [])
+				: [];
+		if (invocations.length === 0) return;
+		// Content bypasses the lifecycle replay ring and must never interrupt its producer.
+		if (!event || typeof event.type !== "string" || !STREAMED_TURN_EVENT_TYPES.has(event.type)) return;
+		// emitLifecycle("agent_start") awaits durable persistence before it
+		// publishes the correlated start frame, while this subscription is
+		// synchronous. Hold content until that start is on the wire so no consumer
+		// sees turn content before the turn it belongs to.
+		if (batch && !batch.startPublished) {
+			batch.heldContent.push({ event: event as AgentSessionEvent, recipients: invocations });
+			if (batch.heldContent.length > MAX_HELD_CONTENT_EVENTS) {
+				if (!batch.heldContentDropped) {
+					batch.heldContentDropped = true;
+					logger.warn(
+						"sdk: agent_start persistence still pending; dropping oldest held turn content to bound memory",
+						{
+							epoch: batch.epoch,
+							bound: MAX_HELD_CONTENT_EVENTS,
+							invocations: batch.invocations.length,
+						},
+					);
+				}
+				batch.heldContent.splice(0, batch.heldContent.length - MAX_HELD_CONTENT_EVENTS);
+			}
+			return;
+		}
+		publishContentFrames(current, event as AgentSessionEvent, invocations);
+	};
 	api.on("tool_execution_start", async (_event, ctx) => {
 		renewAttributableProgress("tool_execution_start", ctx);
 	});
@@ -4784,7 +5093,17 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				connectionId: string | undefined;
 				sdkRunToken: string;
 			}>;
-			attachedInvocations: Array<{ kind: InvocationKind; correlation: InvocationCorrelation }>;
+			attachedInvocations: Array<{
+				kind: InvocationKind;
+				correlation: InvocationCorrelation;
+				connectionId: string | undefined;
+			}>;
+			startPublished: boolean;
+			heldContentDropped: boolean;
+			heldContent: Array<{
+				event: AgentSessionEvent;
+				recipients: Array<{ correlation: InvocationCorrelation; connectionId: string | undefined }>;
+			}>;
 		}> = [];
 		const configRevision = { current: 0 };
 		let acceptingGateResolutions = true;
@@ -4913,6 +5232,19 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					// 2. Terminal boundary. The durable error from step 1 makes this
 					// classify as failed, never terminal_ok.
 					await reconciliation.noteTransition(kind, correlation, { type: "agent_end" });
+					const failure = sanitizePromptFailure(Object.assign(new Error(error.message), { code: error.code }));
+					runtime.emitEvent({
+						type: "agent_failed",
+						sessionId,
+						...correlation,
+						error: failure,
+					});
+					runtime.emitEvent({
+						type: "agent_end",
+						sessionId,
+						...correlation,
+						outcome: canonicalFailedOutcome(failure),
+					});
 					// 3. Release recovery ownership ONLY after durable terminalization.
 					deadlineManager.clear(correlation);
 				} catch (transitionError) {
@@ -5065,7 +5397,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 								entry.correlation.turnId === correlation.turnId,
 						)
 					)
-						current.attachedInvocations.push({ kind, correlation });
+						current.attachedInvocations.push({ kind, correlation, connectionId });
 					if (
 						activeBatch &&
 						!activeBatch.attachedInvocations.some(
@@ -5074,7 +5406,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 								entry.correlation.turnId === correlation.turnId,
 						)
 					)
-						activeBatch.attachedInvocations.push({ kind, correlation });
+						activeBatch.attachedInvocations.push({ kind, correlation, connectionId });
 					bindPromotedToken(activeBatch);
 					return;
 				}
@@ -5157,6 +5489,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			() => acceptingGateResolutions,
 			trackGateResolution,
 			options.onInvocationCompletionReconciledForTests,
+			frame => runtime.emitEvent(frame),
 		);
 		const installProviderDefinitions = (capability: string, definitions: unknown): void => {
 			if (capability === "permission") {
@@ -5366,9 +5699,15 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				});
 			}
 		});
+		// Extension message_update hooks are queued while final/tool hooks are not.
+		// Use only the synchronous session boundary so those paths cannot reorder or duplicate content.
+		const disposeStream = ctx.onSessionEvent?.(event => {
+			if (STREAMED_TURN_EVENT_TYPES.has(event.type)) streamTurnEvent(event, ctx);
+		});
 		const disposeGate = (): void => {
 			disposeWorkflowGate?.();
 			disposeFold?.();
+			disposeStream?.();
 		};
 		let publishedEndpointUrl: string | undefined;
 		let brokerRegistered = false;
@@ -5579,7 +5918,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				retiredLifecycleOwnerTimers.set(current, timer);
 			} else current.deadlineManager.clearAll();
 			current.disposeGate?.();
-			await current.runtime.stop();
+			await current.runtime.stop({ allowLockContention: cancelSkillRecovery });
 		} catch (error) {
 			// Keep the immutable owner available for a retry when transport teardown
 			// fails after quiescing. Clearing `active` before stop prevents a second

package/src/sdk/lifecycle/service.ts

@@ -200,6 +200,7 @@ export interface SessionLifecycleSessionResult {
 	readonly sessionId: string;
 	readonly cwd?: string;
 	readonly endpointGeneration?: number;
+	readonly endpointIncarnation?: string;
 	readonly reused?: boolean;
 	readonly note?: string;
 }
@@ -511,6 +512,7 @@ function sessionResult(value: unknown, expectedSessionId?: string): SessionLifec
 		sessionId: string;
 		cwd?: string;
 		endpointGeneration?: number;
+		endpointIncarnation?: string;
 		reused?: boolean;
 		note?: string;
 	} = { sessionId };
@@ -518,6 +520,8 @@ function sessionResult(value: unknown, expectedSessionId?: string): SessionLifec
 	const endpointGeneration = record.endpointGeneration;
 	if (typeof endpointGeneration === "number" && Number.isSafeInteger(endpointGeneration) && endpointGeneration > 0)
 		result.endpointGeneration = endpointGeneration;
+	if (typeof record.endpointIncarnation === "string" && /^[a-f0-9]{64}$/.test(record.endpointIncarnation))
+		result.endpointIncarnation = record.endpointIncarnation;
 	if (typeof record.reused === "boolean") result.reused = record.reused;
 	if (typeof record.note === "string") result.note = record.note;
 	return result;