@gajae-code/coding-agent 0.16.4 → 0.16.6

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

@@ -427,14 +427,12 @@ export class SessionSdkSessionRuntime {
 	 * asked for. Delivery failure is ignored: a disconnected consumer must never
 	 * disturb the turn producing the content.
 	 */
-	sendFrameTo(connectionIds: Iterable<string>, frame: SdkFrame): void {
-		for (const connectionId of connectionIds) {
-			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.
-			}
+	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.
 		}
 	}
 
@@ -491,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 {
@@ -2628,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 {
@@ -4037,6 +4048,22 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 						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;
@@ -4220,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,
@@ -4231,6 +4308,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		terminalOutcome?: InvocationOutcome,
 		stopReason?: AgentEndEvent["stopReason"],
 		startToken?: string,
+		startTokens?: string[],
 	): Promise<void> => {
 		const current = lifecycleOwner?.state ?? active;
 		if (!current) return;
@@ -4305,10 +4383,10 @@ 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 cohort = new Set(startTokens);
+			if (startToken) cohort.add(startToken);
 			const matchingPending =
-				typeof startToken === "string" && startToken.length > 0
-					? current.pending.filter(entry => entry.sdkRunToken === startToken)
-					: current.pending.slice();
+				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
@@ -4324,14 +4402,16 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					epoch: current.lifecycleEpoch,
 					invocations: drained,
 					attachedInvocations: [],
+					startPublished: false,
+					heldContentDropped: false,
+					heldContent: [],
 				};
 				current.openLifecycleBatches.push(batch);
-				if (typeof startToken === "string" && startToken.length > 0) {
-					const entry = drained.find(item => item.sdkRunToken === startToken);
-					lifecycleRunOwners.set(startToken, {
+				for (const entry of drained) {
+					lifecycleRunOwners.set(entry.sdkRunToken, {
 						state: current,
 						batch,
-						...(entry ? { correlationKey: lifecycleCorrelationKey(entry.correlation) } : {}),
+						correlationKey: lifecycleCorrelationKey(entry.correlation),
 					});
 				}
 				adoptLifecycleBatch(drained);
@@ -4599,6 +4679,27 @@ 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
@@ -4621,9 +4722,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					}
 				}
 			} else {
-				// Everything that does not terminalize an owned invocation keeps the one
-				// uncorrelated frame: `agent_start` and a host-originated run (autonomous
-				// continuation, cron, monitor) that owns no invocation.
+				// Host-originated runs without an invocation keep an uncorrelated frame.
 				try {
 					current.runtime.emitEvent({ type, sessionId });
 				} catch {
@@ -4704,6 +4803,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					undefined,
 					undefined,
 					typeof event.sdkRunToken === "string" ? event.sdkRunToken : undefined,
+					event.sdkRunTokens,
 				),
 			owner,
 		);
@@ -4880,7 +4980,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		"tool_execution_update",
 		"tool_execution_end",
 	]);
-	const streamTurnEvent = (event: { type?: unknown } | null | undefined, ctx: ExtensionContext): void => {
+	const streamTurnEvent = (event: AgentSessionEvent | null | undefined, ctx: ExtensionContext): void => {
 		const current = lifecycleStateForContext(ctx, "agent_start");
 		const activeInvocation = current?.activeInvocation;
 		if (!current) return;
@@ -4899,42 +4999,37 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				? (current.attachedInvocations ?? [])
 				: [];
 		if (invocations.length === 0) return;
-		// The handlers below also renew prompt deadlines, so streaming must never
-		// throw out of them: a frame the wire producer does not recognize is dropped.
+		// 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;
-		try {
-			const payload = toAgentWireEventPayload(event as AgentSessionEvent);
-			// One frame per owning invocation, each carrying its own correlation, so a
-			// shared run lets every submitter attribute the content to its own prompt.
-			for (const invocation of invocations) {
-				if (invocation.connectionId === undefined) continue;
-				current.runtime.sendFrameTo([invocation.connectionId], {
-					type: "event",
-					kind: event.type,
-					payload,
-					...invocation.correlation,
-				});
+		// 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);
 			}
-		} catch {
-			// Streamed content is best-effort; the turn producing it is authoritative.
+			return;
 		}
+		publishContentFrames(current, event as AgentSessionEvent, invocations);
 	};
-	api.on("tool_execution_start", async (event, ctx) => {
+	api.on("tool_execution_start", async (_event, ctx) => {
 		renewAttributableProgress("tool_execution_start", ctx);
-		streamTurnEvent(event, ctx);
 	});
-	api.on("tool_execution_update", async (event, ctx) => {
-		streamTurnEvent(event, ctx);
-	});
-	api.on("tool_execution_end", async (event, ctx) => {
+	api.on("tool_execution_end", async (_event, ctx) => {
 		renewAttributableProgress("tool_execution_end", ctx);
-		streamTurnEvent(event, ctx);
-	});
-	api.on("message_update", async (event, ctx) => {
-		streamTurnEvent(event, ctx);
-	});
-	api.on("message_end", async (event, ctx) => {
-		streamTurnEvent(event, ctx);
 	});
 	const errorCode = (error: unknown): string | undefined =>
 		typeof error === "object" &&
@@ -5003,6 +5098,12 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				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;
@@ -5598,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;
@@ -5811,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;

package/src/sdk/protocol/operation-inventory.generated.json

@@ -2940,6 +2940,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:awaitCoordinatorRuntimeStatePersistenceForTests",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "test-only coordinator persistence drain barrier, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:queueCoordinatorRuntimeStatePersistForTests",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

package/src/sdk/router/session-router.ts

@@ -2,6 +2,7 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { logger, resolveEquivalentPath } from "@gajae-code/utils";
+import { matchesIndexedEndpointFile } from "../broker/endpoint-authority";
 import {
 	canonicalSessionCwd,
 	SessionIndex as DefaultSessionIndex,
@@ -11,7 +12,13 @@ import {
 	type SessionIndex,
 } from "../broker/session-index";
 import { cancellableSleep, lifecycleRequestTimeoutMs } from "../broker/startup-budget";
-import { SdkClient, SdkClientError, type SdkDispatchContext, type SdkDispatchHandler } from "../client/client";
+import {
+	SdkClient,
+	SdkClientError,
+	type SdkDispatchContext,
+	type SdkDispatchHandler,
+	SdkPreparedDispatchError,
+} from "../client/client";
 import {
 	endpointDirectory,
 	readSdkBrokerDiscovery,
@@ -27,6 +34,7 @@ import {
 import { ACP_SESSION_RECONNECT, SESSION_REQUEST_TIMEOUT_MS } from "../session-reconnect";
 
 export interface SessionEndpointIdentity {
+	readonly dev: bigint;
 	readonly mtimeMs: number;
 	readonly mtimeNs: bigint;
 	readonly ctimeNs: bigint;
@@ -56,6 +64,7 @@ export function sessionAttachmentAuthorityId(input: {
 		.digest("hex");
 	const endpointIdentity = input.endpointIdentity
 		? {
+				dev: input.endpointIdentity.dev.toString(),
 				mtimeMs: input.endpointIdentity.mtimeMs,
 				mtimeNs: input.endpointIdentity.mtimeNs.toString(),
 				ctimeNs: input.endpointIdentity.ctimeNs.toString(),
@@ -86,7 +95,13 @@ export interface SessionAttachment {
 	readonly connectionId?: string;
 	readonly generation: number;
 	isCurrent(): boolean;
-	send(frame: Record<string, unknown>): unknown;
+	send(
+		frame: Record<string, unknown>,
+		options?: {
+			beforeDispatch?: () => void;
+			dispatchFence?: (dispatch: () => Promise<void>) => Promise<void>;
+		},
+	): unknown;
 	/**
 	 * Idempotent provider-lease heartbeat send that skips the pre-send authority
 	 * reconcile (#4689).
@@ -179,6 +194,7 @@ export interface SessionRouterClient {
 		frame: Record<string, unknown>,
 		options?: {
 			timeoutMs?: number;
+			connectedOnly?: boolean;
 			/** Synchronous pre-send observer; a throw aborts the dispatch before the wire. */
 			beforeDispatch?: (context: SdkDispatchContext) => void;
 			/** Synchronous post-send boundary observer for transport-close-aware consumers. */
@@ -456,6 +472,7 @@ async function lstatEndpoint(file: string): Promise<SessionEndpointIdentity | un
 	)
 		return undefined;
 	return {
+		dev: identity.dev,
 		mtimeMs: stat.mtimeMs,
 		mtimeNs: identity.mtimeNs,
 		ctimeNs: identity.ctimeNs,
@@ -470,6 +487,7 @@ function warningAffectsSession(warning: string, sessionId: string): boolean {
 
 function sameEndpointIdentity(expected: SessionEndpointIdentity, current: SessionEndpointIdentity): boolean {
 	return (
+		expected.dev === current.dev &&
 		expected.mtimeMs === current.mtimeMs &&
 		expected.mtimeNs === current.mtimeNs &&
 		expected.ctimeNs === current.ctimeNs &&
@@ -909,6 +927,7 @@ export class SessionRouter {
 			timeoutMs?: number;
 			beforeDispatch?: (context: SdkDispatchContext) => void;
 			onDispatch?: SdkDispatchHandler;
+			dispatchFence?: (dispatch: () => Promise<Record<string, unknown>>) => Promise<Record<string, unknown>>;
 		},
 	): Promise<Record<string, unknown>> {
 		const matchesExpectedAuthority = (attachment: SessionAttachment): boolean =>
@@ -946,31 +965,34 @@ export class SessionRouter {
 		// token: the wire frame alone carries credentials, and the observer
 		// context is a deep-frozen, token-redacted copy (#4640 review).
 		const wireFrame = this.#prepareFrame(attached, frame);
-		const { beforeDispatch, onDispatch, ...requestOptions } = options ?? {};
-		const response = await attached.client.request(wireFrame, {
-			...requestOptions,
-			timeoutMs: requestOptions.timeoutMs ?? SESSION_REQUEST_TIMEOUT_MS,
-			...(beforeDispatch
-				? {
-						beforeDispatch: (context: SdkDispatchContext) => {
-							return beforeDispatch({
-								...context,
-								frame: redactDispatchFrame(context.frame),
-							});
-						},
-					}
-				: {}),
-			...(onDispatch
-				? {
-						onDispatch: (context: SdkDispatchContext) => {
-							return onDispatch({
-								...context,
-								frame: redactDispatchFrame(context.frame),
-							});
-						},
-					}
-				: {}),
-		});
+		const { beforeDispatch, onDispatch, dispatchFence, ...requestOptions } = options ?? {};
+		try {
+			await attached.client.connect?.();
+		} catch (error) {
+			if (error instanceof SdkClientError) throw new SdkPreparedDispatchError(error);
+			throw error;
+		}
+		if (!this.#attachmentPublished(attached))
+			throw new SessionRouterError("pre_send", "SDK session attachment changed during transport preparation.");
+		const dispatch = () =>
+			attached.client.request(wireFrame, {
+				...requestOptions,
+				connectedOnly: true,
+				timeoutMs: requestOptions.timeoutMs ?? SESSION_REQUEST_TIMEOUT_MS,
+				...(beforeDispatch
+					? {
+							beforeDispatch: (context: SdkDispatchContext) =>
+								beforeDispatch({ ...context, frame: redactDispatchFrame(context.frame) }),
+						}
+					: {}),
+				...(onDispatch
+					? {
+							onDispatch: (context: SdkDispatchContext) =>
+								onDispatch({ ...context, frame: redactDispatchFrame(context.frame) }),
+						}
+					: {}),
+			});
+		const response = await (dispatchFence ? dispatchFence(dispatch) : dispatch());
 		const settled = this.#sessions.get(sessionId);
 		if (
 			!settled ||
@@ -1141,7 +1163,12 @@ export class SessionRouter {
 	}
 
 	/** Lists saved sessions through Router-owned Broker discovery without exposing credentials or mutation authority. */
-	async listBrokerSessions(input: Record<string, unknown>, idempotencyKey: string): Promise<Record<string, unknown>> {
+	async listBrokerSessions(
+		input: Record<string, unknown>,
+		idempotencyKey: string,
+		options?: { beforeDispatch?: (context: SdkDispatchContext) => void },
+		dispatchFence?: (dispatch: () => Promise<Record<string, unknown>>) => Promise<Record<string, unknown>>,
+	): Promise<Record<string, unknown>> {
 		const operation = "session.list";
 		const discovery = await readSdkBrokerDiscovery(this.#agentDir);
 		if (!discovery) throw new SessionRouterError("pre_send", "SDK broker discovery is unavailable.");
@@ -1155,10 +1182,18 @@ export class SessionRouter {
 		}
 		try {
 			const timeoutMs = lifecycleRequestTimeoutMs(operation, input);
-			return await client.request(
-				{ type: "broker_request", operation, input, idempotencyKey },
-				timeoutMs === undefined ? undefined : { timeoutMs },
-			);
+			try {
+				await client.connect?.();
+			} catch (error) {
+				if (error instanceof SdkClientError) throw new SdkPreparedDispatchError(error);
+				throw error;
+			}
+			const dispatch = () =>
+				client.request(
+					{ type: "broker_request", operation, input, idempotencyKey },
+					{ ...(timeoutMs === undefined ? {} : { timeoutMs }), ...options, connectedOnly: true },
+				);
+			return await (dispatchFence ? dispatchFence(dispatch) : dispatch());
 		} finally {
 			await client.close().catch(error => {
 				logger.warn(`SDK Broker session.list transport cleanup failed (${String(error)}).`);
@@ -1360,7 +1395,7 @@ export class SessionRouter {
 		// cannot keep the old attachment authorized.
 		const identityBefore = await lstatEndpoint(attached.endpoint.path);
 		if (!identityBefore || !sameEndpointIdentity(attached.endpointIdentity, identityBefore)) return false;
-		if (identityBefore.mtimeMs !== indexed.endpointMtimeMs) return false;
+		if (!matchesIndexedEndpointFile(identityBefore, indexed)) return false;
 		let raw: Record<string, unknown>;
 		try {
 			const parsed = JSON.parse(await Bun.file(attached.endpoint.path).text());
@@ -1384,7 +1419,7 @@ export class SessionRouter {
 		const identityAfter = await lstatEndpoint(attached.endpoint.path);
 		return (
 			identityAfter !== undefined &&
-			identityAfter.mtimeMs === indexed.endpointMtimeMs &&
+			matchesIndexedEndpointFile(identityAfter, indexed) &&
 			sameEndpointIdentity(attached.endpointIdentity, identityAfter)
 		);
 	}
@@ -1416,7 +1451,7 @@ export class SessionRouter {
 		const endpointIdentity = await lstatEndpoint(endpointPath);
 		const endpoint = await readSdkSessionEndpoint(cwd, indexed.sessionId, scope);
 		if (!endpoint || endpoint.stale || endpoint.pid !== indexed.pid) return null;
-		if (!endpointIdentity || endpointIdentity.mtimeMs !== indexed.endpointMtimeMs) return null;
+		if (!endpointIdentity || !matchesIndexedEndpointFile(endpointIdentity, indexed)) return null;
 		// Identity is proven INSIDE this authority read (#4730 review): sampling it
 		// afterwards would let an identical rename between the read and the sample
 		// install the replacement's inode as the trusted baseline.
@@ -1441,7 +1476,7 @@ export class SessionRouter {
 		const endpointIdentityAfterRead = await lstatEndpoint(endpoint.path);
 		if (
 			!endpointIdentityAfterRead ||
-			endpointIdentityAfterRead.mtimeMs !== indexed.endpointMtimeMs ||
+			!matchesIndexedEndpointFile(endpointIdentityAfterRead, indexed) ||
 			!sameEndpointIdentity(endpointIdentity, endpointIdentityAfterRead)
 		)
 			return null;
@@ -1641,7 +1676,13 @@ export class SessionRouter {
 				return attached?.client.connectionId;
 			},
 			isCurrent: () => attached !== undefined && this.#attachmentPublished(attached),
-			send: async (frame: Record<string, unknown>) => {
+			send: async (
+				frame: Record<string, unknown>,
+				options?: {
+					beforeDispatch?: () => void;
+					dispatchFence?: (dispatch: () => Promise<void>) => Promise<void>;
+				},
+			) => {
 				if (!attached || !this.#attachmentPublished(attached))
 					throw new SessionRouterError("pre_send", "SDK session attachment is stale.");
 				if (attached.initializingPublication) {
@@ -1659,7 +1700,17 @@ export class SessionRouter {
 				} else await this.#serialReconcile(runEpoch, true, true);
 				if (!attached || !this.#attachmentPublished(attached))
 					throw new SessionRouterError("pre_send", "SDK session attachment is stale.");
-				attached.client.send(this.#prepareFrame(attached, frame));
+				const dispatchAttachment = attached;
+				const dispatch = async () => {
+					options?.beforeDispatch?.();
+					try {
+						dispatchAttachment.client.send(this.#prepareFrame(dispatchAttachment, frame));
+					} catch (error) {
+						if (error instanceof SdkClientError) throw new SdkPreparedDispatchError(error);
+						throw error;
+					}
+				};
+				await (options?.dispatchFence ? options.dispatchFence(dispatch) : dispatch());
 			},
 			/**
 			 * Provider-lease heartbeats skip the pre-send authority reconcile