@gajae-code/coding-agent 0.17.2 → 0.17.4

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

@@ -26,7 +26,12 @@ import {
 import { isAuthenticated, kNoAuth } from "../../config/model-registry";
 import { resolveModelChainWithAuth, splitSelectorThinkingSuffix } from "../../config/model-resolver";
 import { type ModelSelectorValue, normalizeModelSelectorValue } from "../../config/model-selector-value";
-import { type Settings, validateSettingPatch } from "../../config/settings";
+import {
+	resolveSdkPromptDeadlineMs,
+	resolveSdkPromptMaxRuntimeMs,
+	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";
@@ -59,6 +64,7 @@ import {
 	syntheticNamespaceCollision,
 } from "../model-profile-model";
 import { projectQ10Models } from "../models.js";
+import { flushWorktreeOnPromptDeadline } from "../prompt-deadline-flush";
 import { PromptDeadlineManager, type PromptTerminalTransitionEvidence } from "../prompt-deadline-manager";
 import {
 	assistantFailureCode,
@@ -92,7 +98,12 @@ import {
 	BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD,
 	hasBrokerRuntimeAbortCapability,
 } from "./control/runtime-gate";
-import { SessionSdkHost, type SessionSdkHostOptions } from "./host";
+import {
+	SESSION_HOST_OBSERVER_CAPABILITY,
+	SessionSdkHost,
+	type SessionSdkHostOptions,
+	TURN_STREAM_CAPABILITY,
+} from "./host";
 import { clearAutoroutingInactive, isAutoroutingInactive, markAutoroutingInactive } from "./internal-autorouting-state";
 import { CursorRegistry, QueryHandlers, RevisionStore, type SessionSurface } from "./query";
 import { createSdkRunCapability } from "./sdk-run-capability";
@@ -196,6 +207,13 @@ export function verifyMasterCapabilityFrame(input: {
 
 /** Maximum time a replaced runtime may retain a lifecycle persistence task. */
 const LIFECYCLE_QUIESCENCE_MS = 1_000;
+/**
+ * Keep a live session's broker discovery recoverable well inside the session
+ * index's two-minute heartbeat freshness window. `ensureBroker` has its own
+ * bounded startup/recovery budget; the in-flight guard below prevents those
+ * budgets from stacking when one attempt outlives this cadence.
+ */
+export const SESSION_BROKER_RECOVERY_INTERVAL_MS = 30_000;
 
 class DiffQueryError extends Error {
 	constructor(
@@ -357,6 +375,17 @@ export interface SdkOnlyTerminalAbortSeams {
 			terminal?: { scope: "turn" | "owned"; expectedEpoch?: number; steeringSnapshotToken?: number };
 		},
 	) => Promise<{ status: string; terminalScope?: unknown }>;
+	/**
+	 * Live, SYNCHRONOUS view of the dispatched tool calls the run resource
+	 * ledger holds for an execution handle (#5637). Strictly read-only: it
+	 * never claims, reserves, seals or quarantines ledger state. Declared here
+	 * so both hosts expose ONE seam contract — the bus route consumes it for its
+	 * deadline tool-boundary wait, and this route threads it so a future boundary
+	 * wait or deadline abort reads the ledger rather than silently falling back
+	 * to the event-derived set. Optional so an older host that does not thread it
+	 * degrades to that fallback instead of failing to construct.
+	 */
+	pendingToolExecutions?: (handle: string) => readonly string[];
 	/** Test override for the maximum durable terminal reservation rows. */
 	maxDurableTerminalReservationsForTests?: number;
 }
@@ -372,6 +401,9 @@ export interface SdkOnlyTerminalAbortSeams {
 export class SessionSdkSessionRuntime {
 	readonly host: SessionSdkHost;
 	readonly transport: SessionSdkTransport;
+	readonly #connectionCapabilities = new Map<string, ReadonlySet<string>>();
+	readonly #connectionIds = new Set<string>();
+	readonly #connectionCapabilitiesProvider: (connectionId: string) => ReadonlySet<string> | undefined;
 	readonly #connectionDisposer?: () => void;
 	readonly #malformedDisposer?: () => void;
 	readonly #capabilitiesDisposer?: () => void;
@@ -380,10 +412,11 @@ export class SessionSdkSessionRuntime {
 
 	constructor(options: SessionSdkRuntimeOptions) {
 		this.transport = options.transport;
-		const capabilities = new Map<string, ReadonlySet<string>>();
+		this.#connectionCapabilitiesProvider =
+			options.connectionCapabilities ?? (connectionId => this.#connectionCapabilities.get(connectionId));
 		this.host = new SessionSdkHost({
 			...options,
-			connectionCapabilities: options.connectionCapabilities ?? (connectionId => capabilities.get(connectionId)),
+			connectionCapabilities: this.#connectionCapabilitiesProvider,
 			sessionId: options.transport.sessionId,
 			stateRoot: options.transport.stateRoot,
 			token: options.transport.token,
@@ -392,14 +425,20 @@ export class SessionSdkSessionRuntime {
 				if (result instanceof Promise) return result.then(outcome => outcome ?? "written");
 				return result ?? "written";
 			},
-			onFrame: options.transport.onFrame,
+			onFrame: handler =>
+				options.transport.onFrame((connectionId, frame) => {
+					this.#connectionIds.add(connectionId);
+					handler(connectionId, frame);
+				}),
 		});
 		this.#connectionDisposer = options.transport.onConnectionClose?.(connectionId => {
-			capabilities.delete(connectionId);
+			this.#connectionIds.delete(connectionId);
+			this.#connectionCapabilities.delete(connectionId);
 			this.host.handleDisconnect(connectionId);
 		});
 		this.#capabilitiesDisposer = options.transport.onNegotiatedCapabilities?.((connectionId, negotiated) => {
-			capabilities.set(connectionId, new Set(negotiated));
+			this.#connectionIds.add(connectionId);
+			this.#connectionCapabilities.set(connectionId, new Set(negotiated));
 		});
 		this.#malformedDisposer = options.transport.onMalformedFrame?.((connectionId, message) => {
 			this.host.handleMalformedFrame(connectionId, message);
@@ -418,6 +457,11 @@ export class SessionSdkSessionRuntime {
 		return this.host.getProviderDefinitions(capability);
 	}
 
+	/** Persist the host's current observable activity for broker/session-list consumers. */
+	async reportActivity(state: "active" | "idle", at = Date.now()): Promise<void> {
+		await this.host.reportActivity(state, at);
+	}
+
 	emitEvent(frame: SdkFrame): void {
 		const eventInput =
 			typeof frame.kind === "string"
@@ -447,6 +491,28 @@ export class SessionSdkSessionRuntime {
 		}
 	}
 
+	/** Snapshot connections that negotiated every capability in the requirement set. */
+	connectionIdsWithCapabilities(required: readonly string[]): string[] {
+		return [...this.#connectionIds].flatMap(connectionId => {
+			const capabilities = this.#connectionCapabilitiesProvider(connectionId);
+			return capabilities !== undefined && required.every(capability => capabilities.has(capability))
+				? [connectionId]
+				: [];
+		});
+	}
+
+	/** Deliver a non-replayable frame to connections with an explicit capability intersection. */
+	sendFrameToCapabilities(
+		required: readonly string[],
+		frame: SdkFrame,
+		excluding: ReadonlySet<string> = new Set(),
+	): void {
+		for (const connectionId of this.connectionIdsWithCapabilities(required)) {
+			if (excluding.has(connectionId)) continue;
+			this.sendFrameTo(connectionId, frame);
+		}
+	}
+
 	publish(frame: SdkFrame): void {
 		this.emitEvent(frame);
 	}
@@ -500,7 +566,7 @@ export class SessionSdkSessionRuntime {
 		}
 	}
 
-	async stop(options: { allowLockContention?: boolean } = {}): Promise<void> {
+	async stop(options: { allowLockContention?: boolean; unregisterReason?: "detached_idle" } = {}): Promise<void> {
 		this.#connectionDisposer?.();
 		this.#capabilitiesDisposer?.();
 		this.#malformedDisposer?.();
@@ -558,6 +624,11 @@ export interface CreateSdkSessionRuntimeOptions {
 	terminalAbortSeams?: SdkOnlyTerminalAbortSeams;
 	/** Callback when a frame is admitted to the runtime (test harness). */
 	onFrameAdmitted?: () => void;
+	/** Timer seams for deterministic broker-recovery lifecycle tests. */
+	setIntervalImpl?: typeof setInterval;
+	clearIntervalImpl?: typeof clearInterval;
+	/** Test-only broker ensure seam; production always uses the owner-fenced helper. */
+	ensureBrokerImpl?: typeof ensureBroker;
 	/** Test-only observation of a genuinely timed-out lifecycle drain. */
 	onLifecycleDrainTimeoutForTests?: () => void;
 	/** Test-only observation of bounded failure-diagnostic deduplication state. */
@@ -1947,6 +2018,7 @@ function createQuerySurface(
 					...gate,
 					id: `pending:${gate.gate_id}`,
 					tag: "pending" as const,
+					answer_recorded: false as const,
 				})) ??
 				[]
 			);
@@ -4167,6 +4239,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					sdkRunToken: string;
 				}>;
 				registerBroker: () => Promise<void>;
+				stopBrokerRecovery: () => void;
 				quiesceInput: () => void;
 				fenceGateResolutions: () => void;
 				waitForGateResolutionQuiescence: () => Promise<void>;
@@ -4474,8 +4547,10 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 	): void => {
 		try {
 			const payload = toAgentWireEventPayload(event);
+			const delivered = new Set<string>();
 			for (const invocation of invocations) {
 				if (invocation.connectionId === undefined) continue;
+				delivered.add(invocation.connectionId);
 				current.runtime.sendFrameTo(invocation.connectionId, {
 					type: "event",
 					kind: event.type,
@@ -4483,6 +4558,14 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					...invocation.correlation,
 				});
 			}
+			// A relay or dashboard can observe a turn submitted by another client. It
+			// explicitly negotiates both the stream and observer capabilities, so give it
+			// the same live content frames without inventing a submitter correlation.
+			current.runtime.sendFrameToCapabilities(
+				[TURN_STREAM_CAPABILITY, SESSION_HOST_OBSERVER_CAPABILITY],
+				{ type: "event", kind: event.type, payload },
+				delivered,
+			);
 		} catch {
 			// Streamed content is best-effort; the turn producing it is authoritative.
 		}
@@ -5031,7 +5114,16 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 	};
 	api.on("agent_start", (event, ctx) => {
 		const owner = lifecycleStateForEvent(ctx, "agent_start", event.sdkRunToken);
-		return trackLifecycle(
+		// The activity checkpoint is already fire-and-forget and does not depend on
+		// the handler awaiting trackLifecycle, so it composes with #5683 unchanged.
+		void (owner?.runtime ?? lifecycleStateForContext(ctx, "agent_start")?.runtime)
+			?.reportActivity("active")
+			.catch(error => logger.warn(`sdk: active activity checkpoint failed: ${String(error)}`));
+		// Interactive/skill turns must not wait on durable start persist. Keep
+		// trackLifecycle so drain, persist-then-publish, content-hold release, and
+		// shutdown still run; do not return that promise to the extension runner
+		// (EXTENSION_HANDLER_TIMEOUT_MS would otherwise stall the prompt).
+		void trackLifecycle(
 			async () =>
 				emitLifecycle(
 					"agent_start",
@@ -5047,12 +5139,19 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					event.sdkRunTokens,
 				),
 			owner,
-		);
+		).catch(error => {
+			logger.error("SDK agent_start lifecycle task failed", {
+				error: sanitizePromptFailure(error),
+			});
+		});
 	});
 	api.on("agent_end", (event, ctx) => {
 		const tokenBinding =
 			typeof event.sdkRunToken === "string" ? lifecycleRunOwners.get(event.sdkRunToken) : undefined;
 		const owner = tokenBinding?.state ?? lifecycleStateForEvent(ctx, "agent_end", event.sdkRunToken);
+		void (owner?.runtime ?? lifecycleStateForContext(ctx, "agent_end")?.runtime)
+			?.reportActivity("idle")
+			.catch(error => logger.warn(`sdk: idle activity checkpoint failed: ${String(error)}`));
 		// Capture the oldest unmatched batch synchronously. A successor may start
 		// while the failed diagnostic persists; that must not retarget the
 		// predecessor's reason or terminal boundary to the successor invocation.
@@ -5218,10 +5317,10 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 	 * 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.
+	 * Correlated content is scoped to the owning invocations of the batch that is
+	 * actually running. Explicit observer connections additionally receive the
+	 * uncorrelated copy, including for agent-owned runs with no SDK submitter.
+	 * A session with no owner or eligible observer pays one capability-map lookup.
 	 */
 	const STREAMED_TURN_EVENT_TYPES: ReadonlySet<string> = new Set([
 		"message_update",
@@ -5234,6 +5333,10 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		const current = lifecycleStateForContext(ctx, "agent_start");
 		const activeInvocation = current?.activeInvocation;
 		if (!current) return;
+		const observerConnections = current.runtime.connectionIdsWithCapabilities([
+			TURN_STREAM_CAPABILITY,
+			SESSION_HOST_OBSERVER_CAPABILITY,
+		]);
 		const batch = activeInvocation
 			? current.openLifecycleBatches.find(candidate =>
 					candidate.invocations.some(
@@ -5248,7 +5351,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			: current.lifecycleActive
 				? (current.attachedInvocations ?? [])
 				: [];
-		if (invocations.length === 0) return;
+		if (invocations.length === 0 && observerConnections.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
@@ -5291,6 +5394,10 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		typeof (error as { code?: unknown }).code === "string"
 			? (error as { code: string }).code
 			: undefined;
+	const brokerDiagnosticCode = (error: unknown): string => {
+		const code = errorCode(error);
+		return code !== undefined && /^[A-Za-z0-9_.-]{1,64}$/u.test(code) ? code : "unavailable";
+	};
 	const startRuntime = async (ctx: ExtensionContext): Promise<void> => {
 		if (active) return;
 		const sessionId = ctx.sessionManager.getSessionId();
@@ -5315,13 +5422,23 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		await steerReconciliation.hydrateFromStore();
 		const deadlineManager = new PromptDeadlineManager({
 			reconciliation,
-			getLeaseMs: () => {
-				const v = options.settings?.get("sdk.promptDeadlineMs" as never) as number | undefined;
-				return typeof v === "number" && Number.isFinite(v) ? v : 1_800_000;
-			},
-			getMaxMs: () => {
-				const v = options.settings?.get("sdk.promptMaxRuntimeMs" as never) as number | undefined;
-				return typeof v === "number" && Number.isFinite(v) ? v : 21_600_000;
+			getLeaseMs: () => resolveSdkPromptDeadlineMs(options.settings?.get("sdk.promptDeadlineMs" as never)),
+			getMaxMs: () => resolveSdkPromptMaxRuntimeMs(options.settings?.get("sdk.promptMaxRuntimeMs" as never)),
+			// Persist the agent's uncommitted work before the retirement below tears
+			// the session down (#5583). Best effort by contract: failures are logged
+			// inside the flush and the deadline outcome is unaffected.
+			onDeadlineExceeded: async (_correlation, signal, isCurrent) => {
+				if (options.settings?.get("sdk.flushWorktreeOnDeadline" as never) === false) return;
+				// `has` is true only for a value the user actually wrote, so this
+				// separates an explicit opt-in from the schema default. The flush only
+				// honours the default inside a linked worktree the session owns.
+				const configured = options.settings?.get("sdk.flushWorktreeOnDeadline" as never);
+				const hasExplicitSetting =
+					typeof options.settings?.has === "function"
+						? options.settings.has("sdk.flushWorktreeOnDeadline" as never)
+						: configured === true;
+				const explicitOptIn = hasExplicitSetting === true && configured === true;
+				await flushWorktreeOnPromptDeadline(ctx.cwd, { explicitOptIn, isCurrent, signal });
 			},
 			onExpired: (correlation, deadlineOutcome) => {
 				const owner = lifecycleOwnerHolder.state;
@@ -6025,83 +6142,168 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		};
 		let publishedEndpointUrl: string | undefined;
 		let brokerRegistered = false;
+		let brokerRegistrationInFlight: Promise<void> | undefined;
+		let brokerRecoveryStopped = false;
 		const registerBroker = async (): Promise<void> => {
 			if (brokerRegistered) return;
+			if (brokerRegistrationInFlight !== undefined) {
+				await brokerRegistrationInFlight;
+				return;
+			}
+			const registration = (async (): Promise<void> => {
+				try {
+					if (options.brokerRegistrationRequired && !options.lifecycleRequestId)
+						throw new Error("Lifecycle broker registration requires a request identity.");
+					await (options.ensureBrokerImpl ?? ensureBroker)({ agentDir: options.agentDir });
+					if (brokerRecoveryStopped) return;
+					const index = await new SessionIndex(options.agentDir).open();
+					if (brokerRecoveryStopped) return;
+					const locator = await resolveSessionLocator(ctx.cwd, stateRoot);
+					const effectiveIncarnation = processIncarnation(process.pid);
+					const direct = await reattestMasterSessionIdentity({
+						index,
+						locator,
+						masterCapability: options.masterCapability,
+						attestationEpoch: options.masterAttestationEpoch,
+						ownerSessionId: options.masterOwnerSessionId,
+						sessionId,
+						pid: process.pid,
+						processIncarnation: effectiveIncarnation,
+					});
+					if (brokerRecoveryStopped) return;
+					let brokerRegistrationEvent: SessionIndexEvent | undefined;
+					await runtime.registerWithBroker({
+						register: async input => {
+							if (publishedEndpointUrl === undefined)
+								throw new Error("SDK transport endpoint was not published before broker registration.");
+							const endpointPath = path.join(input.stateRoot, "sdk", `${input.sessionId}.json`);
+							const file = await readEndpointFile(endpointPath);
+							if (!file) throw new Error("SDK endpoint could not be read as a stable regular file.");
+							const endpoint = JSON.parse(file.source) as Record<string, unknown>;
+							if (
+								endpoint.sessionId !== input.sessionId ||
+								endpoint.pid !== process.pid ||
+								endpoint.url !== publishedEndpointUrl ||
+								endpoint.token !== transport.token
+							)
+								throw new Error("SDK endpoint did not match the published transport authority.");
+							const endpointMtimeMs = file.mtimeMs;
+							const endpointFileId = `${file.dev}:${file.ino}`;
+							const masterRole = masterAttestationForEffectiveHost({
+								masterCapability: options.masterCapability,
+								attestationEpoch: options.masterAttestationEpoch,
+								ownerSessionId: options.masterOwnerSessionId,
+								sessionId: input.sessionId,
+								pid: process.pid,
+								processIncarnation: effectiveIncarnation,
+								direct,
+							});
+							const published = await index.append({
+								type: "host_registered",
+								...input,
+								locator,
+								pid: process.pid,
+								endpointMtimeMs,
+								endpointFileId,
+								...(options.lifecycleRequestId ? { lifecycleRequestId: options.lifecycleRequestId } : {}),
+								...(masterRole ? { masterRole } : {}),
+							});
+							brokerRegistrationEvent = published;
+							if (brokerRecoveryStopped) {
+								// Teardown may have run before append returned its ownership proof.
+								await index.unregisterIfCurrent(published);
+								if (brokerRegistrationEvent === published) brokerRegistrationEvent = undefined;
+							}
+						},
+						heartbeat: async input => {
+							// Heartbeat only ever speaks for the publication this host proved it
+							// owns. A stale or foreign generation must not renew liveness.
+							const expected = brokerRegistrationEvent;
+							if (
+								!expected ||
+								expected.sessionId !== input.sessionId ||
+								expected.endpointGeneration !== input.endpointGeneration ||
+								path.resolve(expected.locator.stateRoot) !== path.resolve(input.stateRoot)
+							)
+								return;
+							await index.append({
+								type: "host_heartbeat",
+								sessionId: expected.sessionId,
+								locator: expected.locator,
+								endpointGeneration: expected.endpointGeneration,
+								pid: expected.pid,
+								...(expected.processIncarnation === undefined
+									? {}
+									: { processIncarnation: expected.processIncarnation }),
+								...(expected.hostIncarnation === undefined
+									? {}
+									: { hostIncarnation: expected.hostIncarnation }),
+								...(expected.masterRole === undefined ? {} : { masterRole: expected.masterRole }),
+								activity: input.activity,
+								ts: input.activity.at,
+							});
+						},
+						unregister: async input => {
+							const expected = brokerRegistrationEvent;
+							if (
+								!expected ||
+								expected.sessionId !== input.sessionId ||
+								expected.endpointGeneration !== input.endpointGeneration ||
+								path.resolve(expected.locator.stateRoot) !== path.resolve(input.stateRoot)
+							)
+								return;
+							// Use the successful publication's proof, never a teardown-time file read.
+							await index.unregisterIfCurrent(expected, input.reason);
+							if (brokerRegistrationEvent === expected) brokerRegistrationEvent = undefined;
+						},
+					});
+					if (brokerRecoveryStopped) return;
+					brokerRegistered = true;
+				} catch (error) {
+					if (options.brokerRegistrationRequired) throw error;
+					logger.warn("sdk broker registration unavailable", { code: brokerDiagnosticCode(error) });
+				}
+			})();
+			brokerRegistrationInFlight = registration;
 			try {
-				if (options.brokerRegistrationRequired && !options.lifecycleRequestId)
-					throw new Error("Lifecycle broker registration requires a request identity.");
-				await ensureBroker({ agentDir: options.agentDir });
-				const index = await new SessionIndex(options.agentDir).open();
-				const locator = await resolveSessionLocator(ctx.cwd, stateRoot);
-				const effectiveIncarnation = processIncarnation(process.pid);
-				const direct = await reattestMasterSessionIdentity({
-					index,
-					locator,
-					masterCapability: options.masterCapability,
-					attestationEpoch: options.masterAttestationEpoch,
-					ownerSessionId: options.masterOwnerSessionId,
-					sessionId,
-					pid: process.pid,
-					processIncarnation: effectiveIncarnation,
-				});
-				let registration: SessionIndexEvent | undefined;
-				await runtime.registerWithBroker({
-					register: async input => {
-						if (publishedEndpointUrl === undefined)
-							throw new Error("SDK transport endpoint was not published before broker registration.");
-						const endpointPath = path.join(input.stateRoot, "sdk", `${input.sessionId}.json`);
-						const file = await readEndpointFile(endpointPath);
-						if (!file) throw new Error("SDK endpoint could not be read as a stable regular file.");
-						const endpoint = JSON.parse(file.source) as Record<string, unknown>;
-						if (
-							endpoint.sessionId !== input.sessionId ||
-							endpoint.pid !== process.pid ||
-							endpoint.url !== publishedEndpointUrl ||
-							endpoint.token !== transport.token
-						)
-							throw new Error("SDK endpoint did not match the published transport authority.");
-						const endpointMtimeMs = file.mtimeMs;
-						const endpointFileId = `${file.dev}:${file.ino}`;
-						const masterRole = masterAttestationForEffectiveHost({
-							masterCapability: options.masterCapability,
-							attestationEpoch: options.masterAttestationEpoch,
-							ownerSessionId: options.masterOwnerSessionId,
-							sessionId: input.sessionId,
-							pid: process.pid,
-							processIncarnation: effectiveIncarnation,
-							direct,
-						});
-						registration = await index.append({
-							type: "host_registered",
-							...input,
-							locator,
-							pid: process.pid,
-							endpointMtimeMs,
-							endpointFileId,
-							...(options.lifecycleRequestId ? { lifecycleRequestId: options.lifecycleRequestId } : {}),
-							...(masterRole ? { masterRole } : {}),
-						});
-					},
-					unregister: async input => {
-						const expected = registration;
-						if (
-							!expected ||
-							expected.sessionId !== input.sessionId ||
-							expected.endpointGeneration !== input.endpointGeneration ||
-							path.resolve(expected.locator.stateRoot) !== path.resolve(input.stateRoot)
-						)
-							return;
-						// Use the successful publication's proof, never a teardown-time file read.
-						await index.unregisterIfCurrent(expected);
-						if (registration === expected) registration = undefined;
-					},
-				});
-				brokerRegistered = true;
+				await registration;
+			} finally {
+				if (brokerRegistrationInFlight === registration) brokerRegistrationInFlight = undefined;
+			}
+		};
+		let brokerRecoveryTimer: NodeJS.Timeout | undefined;
+		let brokerRecoveryInFlight: Promise<void> | undefined;
+		const runBrokerRecovery = async (): Promise<void> => {
+			if (brokerRecoveryStopped || brokerRecoveryInFlight !== undefined) return;
+			const recovery = (async (): Promise<void> => {
+				if (brokerRecoveryStopped) return;
+				if (brokerRegistered) await (options.ensureBrokerImpl ?? ensureBroker)({ agentDir: options.agentDir });
+				else await registerBroker();
+			})();
+			brokerRecoveryInFlight = recovery;
+			try {
+				await recovery;
 			} catch (error) {
-				if (options.brokerRegistrationRequired) throw error;
-				logger.warn(`sdk broker registration unavailable: ${String(error)}`);
+				logger.warn("sdk broker recovery unavailable", { code: brokerDiagnosticCode(error) });
+			} finally {
+				if (brokerRecoveryInFlight === recovery) brokerRecoveryInFlight = undefined;
 			}
 		};
+		const startBrokerRecovery = (): void => {
+			if (brokerRecoveryStopped || brokerRecoveryTimer !== undefined) return;
+			const timer = (options.setIntervalImpl ?? setInterval)(
+				() => void runBrokerRecovery(),
+				SESSION_BROKER_RECOVERY_INTERVAL_MS,
+			) as NodeJS.Timeout;
+			brokerRecoveryTimer = timer;
+			timer.unref?.();
+		};
+		const stopBrokerRecovery = (): void => {
+			brokerRecoveryStopped = true;
+			if (brokerRecoveryTimer === undefined) return;
+			(options.clearIntervalImpl ?? clearInterval)(brokerRecoveryTimer);
+			brokerRecoveryTimer = undefined;
+		};
 		const runtimeOwner: RuntimeState = {
 			sessionId,
 			sessionIdentity,
@@ -6114,6 +6316,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			pending,
 			openLifecycleBatches,
 			registerBroker,
+			stopBrokerRecovery,
 			quiesceInput: () => {
 				inputGate.quiescing = true;
 				lifecycleOwnerHolder.quiescing = true;
@@ -6129,13 +6332,19 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			failureDiagnosticCodes: new Map(),
 			lifecycleTasks: new Set(),
 		};
+		// Capture the SDK turn that owns a headless workflow gate before it is
+		// persisted. Q12 can then explain both sides of a stalled turn: the gate
+		// identity and whether an answer was recorded for that originating turn.
+		ctx.workflowGate?.setRuntimeTurnProvider?.(() => active?.activeInvocation?.correlation.turnId);
 		lifecycleOwnerHolder.state = runtimeOwner;
 		active = runtimeOwner;
 		try {
 			publishedEndpointUrl = (await runtime.start()).url;
 			await registerBroker();
+			if (!brokerRecoveryStopped) startBrokerRecovery();
 		} catch (error) {
 			active = undefined;
+			stopBrokerRecovery();
 			disposeGate?.();
 			try {
 				await runtime.stop();
@@ -6156,6 +6365,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					pending,
 					openLifecycleBatches,
 					registerBroker,
+					stopBrokerRecovery,
 					quiesceInput: () => {
 						inputGate.quiescing = true;
 						lifecycleOwnerHolder.quiescing = true;
@@ -6180,7 +6390,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			throw error;
 		}
 	};
-	const stopActive = async (cancelSkillRecovery = false): Promise<void> => {
+	const stopActive = async (cancelSkillRecovery = false, unregisterReason?: "detached_idle"): Promise<void> => {
 		const current = active;
 		if (!current) return;
 		if (cancelSkillRecovery) {
@@ -6189,6 +6399,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		}
 		activePromptOwnerHolder.connectionIds = undefined;
 		activePromptOwnerHolder.lifecycleEpoch = undefined;
+		current.stopBrokerRecovery();
 		current.quiesceInput();
 		current.fenceGateResolutions();
 		try {
@@ -6237,7 +6448,10 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				retiredLifecycleOwnerTimers.set(current, timer);
 			} else current.deadlineManager.clearAll();
 			current.disposeGate?.();
-			await current.runtime.stop({ allowLockContention: cancelSkillRecovery });
+			await current.runtime.stop({
+				allowLockContention: cancelSkillRecovery,
+				...(unregisterReason === undefined ? {} : { unregisterReason }),
+			});
 		} catch (error) {
 			// Keep the immutable owner available for a retry when transport teardown
 			// fails after quiescing. Clearing `active` before stop prevents a second
@@ -6260,7 +6474,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		await stopActive();
 		await startRuntime(ctx);
 	});
-	api.on("session_shutdown", async () => {
-		await stopActive(true);
+	api.on("session_shutdown", async event => {
+		await stopActive(true, event.reason);
 	});
 }

package/src/sdk/host/types.ts

@@ -25,5 +25,16 @@ export interface HostEndpointAdapters {
 
 export interface BrokerIndexWriter {
 	register(input: { sessionId: string; stateRoot: string; endpointGeneration: number }): void | Promise<void>;
-	unregister?(input: { sessionId: string; stateRoot: string; endpointGeneration: number }): void | Promise<void>;
+	heartbeat?(input: {
+		sessionId: string;
+		stateRoot: string;
+		endpointGeneration: number;
+		activity: { state: "active" | "idle"; at: number };
+	}): void | Promise<void>;
+	unregister?(input: {
+		sessionId: string;
+		stateRoot: string;
+		endpointGeneration: number;
+		reason?: "detached_idle";
+	}): void | Promise<void>;
 }