@gajae-code/coding-agent 0.18.11 → 0.19.0

package/src/sdk/bus/index.ts

@@ -71,7 +71,7 @@ import {
 	type WorkflowGateTerminalController,
 	type WorkflowGateTerminalProof,
 } from "../../modes/shared/agent-wire/workflow-gate-broker";
-import type { AgentSessionEvent } from "../../session/agent-session";
+import type { AgentSessionEvent, QueuedRunStartFailure } from "../../session/agent-session";
 import type { ClientBridge } from "../../session/client-bridge";
 import {
 	createSessionWorkLease,
@@ -102,6 +102,7 @@ import {
 	registerAskAnswerSource,
 	registerWorkflowGateEmitterListener,
 } from "../../tools/ask-answer-registry";
+import type { AwaitingInputKind } from "../../tools/awaiting-input";
 import { acpFinalTextFromMessage } from "../acp/final-text";
 import { ensureBroker } from "../broker/ensure";
 import { publishSessionHostRuntimeEvidence, type SessionHostRuntimePublication } from "../broker/lifecycle";
@@ -117,11 +118,13 @@ import {
 	type SessionSdkHost,
 	SessionSdkSessionRuntime,
 	shouldHostSdk,
+	TURN_STREAM_CAPABILITY,
 	verifyMasterCapabilityFrame,
 } from "../host";
 import { type AbortScope, type ControlSurface, dispatchControl, TypedControlError } from "../host/control";
 import { BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD } from "../host/control/runtime-gate";
 import { isAutoroutingInactive, markAutoroutingInactive } from "../host/internal-autorouting-state";
+import { PromptImageUploadStore, retirePromptImageReservation } from "../host/prompt-image-upload";
 import { CursorRegistry, QueryHandlers, RevisionStore, type SessionSurface } from "../host/query";
 import { RESPONSE_CEILING_BYTES } from "../host/query/handlers";
 import type { SdkFrame } from "../host/types";
@@ -132,7 +135,7 @@ import {
 	syntheticModelInputError,
 	syntheticNamespaceCollision,
 } from "../model-profile-model";
-import { flushWorktreeOnPromptDeadline } from "../prompt-deadline-flush";
+import { autosaveWorktreeOnPromptDeadline, deadlineFlushSuppressed } from "../prompt-deadline-flush";
 import {
 	createPromptDeadlineLease,
 	isAttributableProgressEventType,
@@ -1235,6 +1238,10 @@ export class PresentationArbiter {
 interface SessionRuntime {
 	server: NotificationServer;
 	host: SessionSdkHost;
+	imageUploads: PromptImageUploadStore | undefined;
+	releaseAcceptedImage: (correlation: { commandId: string; turnId: string }) => void;
+	releaseAcceptedImagesForRun: (owner: AgentTerminalOwnerContext) => void;
+	releaseAcceptedImages: () => void;
 	getJoinedPromptCorrelations: (owner: AgentTerminalOwnerContext) => Array<{ commandId: string; turnId: string }>;
 	isPromptRunOwner: (correlation: { commandId: string; turnId: string }, owner: AgentTerminalOwnerContext) => boolean;
 	retireJoinedPromptOwners: () => void;
@@ -1421,6 +1428,12 @@ interface SessionRuntime {
 		string,
 		{ toolName: string; args?: unknown; pendingPhase?: "completed" | "failed" | "cancelled" }
 	>;
+	/**
+	 * Running tool calls that reported an awaiting-input signal, keyed by tool call
+	 * id. An entry stays undelivered while notifications are inactive or policy is
+	 * provisional, and is dropped when the call ends; one notification per call.
+	 */
+	awaitingInput: Map<string, { toolName: string; kind: AwaitingInputKind; delivered: boolean }>;
 	/** Cancels the postmortem cleanup that emits `session_closed` on process teardown. */
 	cancelPostmortemCleanup: () => void;
 	/** Disposes side-turn resources when their owning logical session becomes unavailable. */
@@ -1431,6 +1444,48 @@ const SENSITIVE_MODEL_LABEL =
 	/(?:\b(?:https?|wss?):\/\/|\b[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}\b|\b(?:api[-_ ]?key|access[-_ ]?token|bearer|secret|password|account(?:\s*id)?|email|exception|stack trace)\b|\b(?:sk|pk|rk)-[A-Za-z0-9_-]{12,}\b)/i;
 const TOOL_SUMMARY_MAX = 280;
 
+/** The `awaitingInput` signal a running bash update carries, validated at the extension boundary. */
+function readAwaitingInput(partialResult: unknown): { kind: AwaitingInputKind } | undefined {
+	if (!partialResult || typeof partialResult !== "object") return undefined;
+	const details = (partialResult as { details?: unknown }).details;
+	if (!details || typeof details !== "object") return undefined;
+	const signal = (details as { awaitingInput?: unknown }).awaitingInput;
+	if (!signal || typeof signal !== "object") return undefined;
+	const kind = (signal as { kind?: unknown }).kind;
+	return kind === "browser_auth" || kind === "device_code" ? { kind } : undefined;
+}
+
+/**
+ * Deliver every undelivered awaiting-input notice once stable policy admits it.
+ * The notice describes the present ("a command is waiting now"), so it goes out
+ * on the live native leg only and never enters the replay ring: a client that
+ * reconnects after the command exited must not receive it. The native server
+ * still withholds it from connections without `awaiting_input_v1`.
+ */
+function deliverAwaitingInput(
+	runtime: Pick<SessionRuntime, "server" | "awaitingInput" | "notificationsActive" | "policySuspended">,
+	sessionId: string,
+): void {
+	if (!runtime.notificationsActive || runtime.policySuspended) return;
+	for (const [toolCallId, entry] of runtime.awaitingInput) {
+		if (entry.delivered) continue;
+		entry.delivered = true;
+		try {
+			runtime.server.pushFrame(
+				JSON.stringify({
+					type: "awaiting_input",
+					sessionId,
+					toolCallId,
+					toolName: entry.toolName,
+					kind: entry.kind,
+				}),
+			);
+		} catch (e) {
+			logger.warn(`notifications: awaiting_input failed: ${String(e)}`);
+		}
+	}
+}
+
 /** Stable projection of the tool-owned safe-display seam (never the full Tool surface). */
 type SafeSummaryTool = Pick<Tool, "safeSummary" | "safeSummaryFields">;
 
@@ -2459,11 +2514,13 @@ function sdkQuerySurface(
 	}),
 	getRuntimeHost: () => SessionSdkHost | undefined = () => undefined,
 	primaryControlSurface: "cli" | "sdk" = "sdk",
+	imageUploadsAvailable = false,
 ): SessionSurface {
 	return createSdkSurfaceFactory({
 		ctx,
 		id,
 		api,
+		imageUploadsAvailable,
 		getInstalledDefinitions,
 		getLiveState,
 		configOverrides,
@@ -2612,6 +2669,19 @@ function sdkControlSurface(
 	pendingInteractive: Map<string, PendingInteractiveAsk>,
 	gatePresentations: PresentationArbiter | undefined,
 	api: ExtensionAPI,
+	imageUploads: PromptImageUploadStore | undefined,
+	imageUploadsAvailable: boolean,
+	retainAcceptedImage: (
+		correlation: { commandId: string; turnId: string },
+		release: () => void,
+		preflightSignal: AbortSignal,
+		submissionSettled: Promise<void>,
+	) => {
+		accepted: () => void;
+		promoted: (promotion: { startsOwnRun?: boolean; removed?: boolean }) => void;
+		refused: () => boolean;
+	},
+	releaseAcceptedImage: (correlation: { commandId: string; turnId: string }) => void,
 	isBusy: () => boolean,
 	onPromptAccepted: (
 		correlation: { commandId: string; turnId: string },
@@ -2626,6 +2696,12 @@ function sdkControlSurface(
 		correlation: { commandId: string; turnId: string },
 		error: unknown,
 	) => void | Promise<void> = () => {},
+	onQueuedRunStartFailed: (
+		correlation: { commandId: string; turnId: string },
+		failure: QueuedRunStartFailure,
+		sdkRunToken: string | undefined,
+		refuseImage: (() => boolean) | undefined,
+	) => boolean,
 	onPromptAcceptFailed: (correlation: { commandId: string; turnId: string }) => void = () => {},
 	onPromptDiverted: (correlation: { commandId: string; turnId: string }) => void,
 	onPromptPromoted: (
@@ -2659,6 +2735,10 @@ function sdkControlSurface(
 		// the session-wide preflight seam must not be invoked while another
 		// connection's active preflight could be cancelled by it (review P1).
 		noOtherConnectionPreflights?: () => boolean,
+		// True only for an operator terminal abort that the broker control route already
+		// authorized (`TerminalAbortInput.operator`, which a public SDK caller cannot grant):
+		// it addresses the session's active turn, not the requesting connection's own prompt.
+		operatorAuthorized?: boolean,
 	) => Promise<
 		| {
 				ok: true;
@@ -2723,6 +2803,7 @@ function sdkControlSurface(
 		ctx,
 		id: ctx.sessionManager.getSessionId(),
 		api,
+		imageUploadsAvailable,
 	}).policy;
 	const missingExpectedSessionAudits = new Set<"workflow.gate_answer" | "workflow.plan_approve">();
 	const auditMissingExpectedSessionId = (operation: "workflow.gate_answer" | "workflow.plan_approve") => {
@@ -2908,6 +2989,18 @@ function sdkControlSurface(
 		requesterConnectionId?: string,
 		clientRef?: string,
 		trackReconciliation = false,
+		onCorrelation?: (
+			correlation: { commandId: string; turnId: string },
+			preflightSignal: AbortSignal,
+			submissionSettled: Promise<void>,
+		) =>
+			| {
+					accepted: () => void;
+					promoted: (promotion: { startsOwnRun?: boolean; removed?: boolean }) => void;
+					refused: () => boolean;
+			  }
+			| undefined,
+		resolveImages?: () => unknown,
 	) => {
 		const trimmedClientRef = typeof clientRef === "string" ? clientRef.trim() : undefined;
 		if (clientRef !== undefined && (!trimmedClientRef || trimmedClientRef.length > PROMPT_CLIENT_REF_MAX_LENGTH))
@@ -2953,6 +3046,8 @@ function sdkControlSurface(
 						code: "busy",
 					},
 				);
+			// Staged bytes are one-shot: reserve reconciliation before consuming them.
+			if (resolveImages) images = resolveImages();
 		} catch (error) {
 			admission.abandon();
 			if (trackReconciliation) releasePromptAdmission(trimmedClientRef);
@@ -2984,6 +3079,8 @@ function sdkControlSurface(
 		const submissionSettled = Promise.withResolvers<void>();
 		let cancellation: Promise<void> | undefined;
 		const correlation = { commandId, turnId };
+		let queuedRunRefused = false;
+		const imageLifecycle = onCorrelation?.(correlation, preflightController.signal, submissionSettled.promise);
 		const key = preflightKey(requesterConnectionId, correlation);
 		const settlePreflight = (result: PreflightTerminalResult) => {
 			if (preflightSettled) return;
@@ -3034,6 +3131,8 @@ function sdkControlSurface(
 			admission.accepted();
 			accepting = false;
 			accepted = true;
+			// A late durable acceptance after direct abort cannot end image retention.
+			if (!preflightController.signal.aborted) imageLifecycle?.accepted();
 			if (effectiveDeliverAs !== undefined) onPromptDiverted(correlation);
 			// #4743: an accepted run owns a durable terminal publication when it
 			// settles; teardown joins it via this latch (never-accepted preflights
@@ -3061,13 +3160,22 @@ function sdkControlSurface(
 					onPreflightAcceptCommit,
 					onPreflightAccepted,
 					onQueuedPromoted: promotion => {
+						if (queuedRunRefused) return;
+						if (promotion.startsOwnRun === true) imageLifecycle?.promoted(promotion);
 						admission.hooks.onQueuedPromoted(promotion);
 						onPromptPromoted(correlation, promotion, ctx.getActivePromptHandle());
+						if (promotion.startsOwnRun !== true) imageLifecycle?.promoted(promotion);
+						if (promotion.removed) releaseAcceptedImage(correlation);
 					},
 					onDispatchDisposition: disposition => {
+						if (queuedRunRefused) return;
 						admission.hooks.onDispatchDisposition(disposition);
 						if (!disposition.startsOwnRun) onPromptDiverted(correlation);
 					},
+					onQueuedRunStartFailed: failure => {
+						if (queuedRunRefused) return;
+						queuedRunRefused = onQueuedRunStartFailed(correlation, failure, sdkRunToken, imageLifecycle?.refused);
+					},
 					preflightSignal: preflightController.signal,
 					...(sdkRunToken ? { sdkRunToken } : {}),
 				}),
@@ -3075,7 +3183,7 @@ function sdkControlSurface(
 		} catch (error) {
 			submissionSettled.resolve();
 			admission.abandon();
-			if (accepted && !preflightController.signal.aborted)
+			if (accepted && !queuedRunRefused && !preflightController.signal.aborted)
 				trackReconciliationProducer?.(Promise.resolve(onPromptFailed(correlation, error)));
 			else settlePreflight({ status: "rejected", error });
 		}
@@ -3097,7 +3205,7 @@ function sdkControlSurface(
 				},
 				error => {
 					admission.abandon();
-					if (accepted && !preflightController.signal.aborted)
+					if (accepted && !queuedRunRefused && !preflightController.signal.aborted)
 						trackReconciliationProducer?.(Promise.resolve(onPromptFailed(correlation, error)));
 					else settlePreflight({ status: "rejected", error });
 					submissionSettled.resolve();
@@ -3120,8 +3228,52 @@ function sdkControlSurface(
 		cancelPendingPreflights(): Promise<void>;
 		cancelPendingPreflightsForConnection(connectionId: string): Promise<void>;
 	} = {
-		prompt: (text, images, clientRef) =>
-			submitPrompt(text, images, false, undefined, true, controlRequesterContext.getStore(), clientRef, true),
+		prompt: async (text, images, clientRef, stagedImages) => {
+			if (stagedImages !== undefined && images !== undefined)
+				throw Object.assign(new Error("Direct and staged images cannot be mixed."), { code: "invalid_input" });
+			const requesterConnectionId = controlRequesterContext.getStore();
+			let reservation: { images: ImageContent[]; release: () => void } | undefined;
+			let correlation: { commandId: string; turnId: string } | undefined;
+			try {
+				return await submitPrompt(
+					text,
+					images,
+					false,
+					undefined,
+					true,
+					requesterConnectionId,
+					clientRef,
+					true,
+					(current, preflightSignal, submissionSettled) => {
+						correlation = current;
+						if (reservation)
+							return retainAcceptedImage(current, reservation.release, preflightSignal, submissionSettled);
+					},
+					stagedImages === undefined
+						? undefined
+						: () => {
+								if (!imageUploads)
+									throw Object.assign(new Error("Staged images are unavailable."), {
+										code: "image_upload_unavailable",
+									});
+								reservation = imageUploads.redeem(requesterConnectionId, stagedImages);
+								return reservation.images;
+							},
+				);
+			} catch (error) {
+				if (correlation) releaseAcceptedImage(correlation);
+				else reservation?.release();
+				throw error;
+			}
+		},
+		...(imageUploads
+			? {
+					imageBegin: (input: unknown) => imageUploads.begin(controlRequesterContext.getStore(), input),
+					imageAppend: (input: unknown) => imageUploads.append(controlRequesterContext.getStore(), input),
+					imageFinish: (input: unknown) => imageUploads.finish(controlRequesterContext.getStore(), input),
+					imageDiscard: (input: unknown) => imageUploads.discard(controlRequesterContext.getStore(), input),
+				}
+			: {}),
 		steer: (text, clientRef) => sendSteer(text, clientRef),
 		followUp: text => submitPrompt(text, undefined, false, "followUp", false, controlRequesterContext.getStore()),
 		abort: async () => {
@@ -3178,6 +3330,9 @@ function sdkControlSurface(
 				// invoking it (review thread P1).
 				() =>
 					![...pendingPreflightCancellations.values()].some(entry => entry.connectionId !== requesterConnectionId),
+				// Broker-authorized operator authority is the one case where the abort
+				// addresses a turn another connection submitted (see the parameter note).
+				input.operator === true,
 			);
 			// Preflight cancellation happens ONLY for a NEWLY ADMITTED abort,
 			// after the durable admission/replay decision inside
@@ -4281,6 +4436,34 @@ export function boundedCorrelatedAgentEndFrame(frame: Record<string, unknown>):
 	};
 }
 
+/** Connection-scoped identity of a queued prompt submission an abort may address. */
+export interface TerminalAbortSubmissionScope {
+	connectionId?: string;
+	terminal: boolean;
+}
+
+/**
+ * Whether a terminal abort addresses this prompt submission.
+ *
+ * An ordinary abort is scoped to the requesting connection's own prompt: `connectionId`
+ * identifies the connection that submitted it, and a submission that already reached a
+ * terminal state is never addressed. Broker-authorized operator authority
+ * (`TerminalAbortInput.operator`, granted only through the broker control route) is the
+ * documented exception — "operator authority changes only connection ownership, never
+ * those settlement proofs" — so it addresses the session's submission even when another
+ * connection submitted it. Without that override every operator abort issued over a
+ * second connection (the SDK client case, where each request is its own connection)
+ * reported no_active_turn while the turn was still running.
+ */
+export function terminalAbortAddressesSubmission(input: {
+	connectionId: string | undefined;
+	operatorAuthorized: boolean;
+	submission: TerminalAbortSubmissionScope;
+}): boolean {
+	if (input.submission.terminal) return false;
+	return input.operatorAuthorized || input.submission.connectionId === input.connectionId;
+}
+
 export function createNotificationsExtension(
 	api: ExtensionAPI,
 	options: {
@@ -4313,6 +4496,8 @@ export function createNotificationsExtension(
 		 * preflight outside the durable admission path (review thread P2).
 		 */
 		terminalAbortSeams?: {
+			/** Definitive event-driven observation; never mutates the owning run. */
+			waitForRunSettlement?: (handle: string) => Promise<RunSettlementProof>;
 			getTerminalRunOwnerForEvent?: (event: object) => AgentTerminalOwnerContext | undefined;
 			getRunOwnerDomain?: (handle: string) => RunCancellationDomain | undefined;
 			getTerminalTurnEpoch: () => number | undefined;
@@ -4602,6 +4787,7 @@ export function createNotificationsExtension(
 		if (reason === "session" && requestedRuntime) {
 			requestedRuntime.inboundFenced = true;
 			requestedRuntime.stopping = true;
+			requestedRuntime.imageUploads?.close();
 			requestedRuntime.retireJoinedPromptOwners();
 			requestedRuntime.abortEphemeralTurns();
 		}
@@ -4780,6 +4966,7 @@ export function createNotificationsExtension(
 			cleanupRetries.set(id, rt);
 			throw new AggregateError(ownerReleaseFailures, `SDK notification runtime ${id} owner release failed.`);
 		}
+		rt.releaseAcceptedImages();
 		if (cleanupRetries.get(id) === rt) cleanupRetries.delete(id);
 		return true;
 	}
@@ -5054,7 +5241,11 @@ export function createNotificationsExtension(
 		};
 
 		type HostConnectionIncarnation = { generation: number; closed: boolean };
-		type HostCapabilityCacheEntry = { generation: number; capabilities: ReadonlySet<string> };
+		type HostCapabilityCacheEntry = {
+			generation: number;
+			capabilities: ReadonlySet<string>;
+			nativeConfirmed: ReadonlySet<string>;
+		};
 		const hostCapCache = new Map<string, HostCapabilityCacheEntry>();
 		const hostConnectionIncarnations = new Map<string, HostConnectionIncarnation>();
 		const hostAttachedConnections = new Set<string>();
@@ -5068,12 +5259,28 @@ export function createNotificationsExtension(
 			hostConnectionIncarnations.set(connectionId, incarnation);
 			return incarnation;
 		};
-		const rememberHostCapabilities = (connectionId: string, capabilities: readonly string[]): void => {
+		const rememberHostCapabilities = (
+			connectionId: string,
+			capabilities: readonly string[],
+			source: "replay" | "native",
+		): void => {
 			const incarnation = liveHostConnection(connectionId);
 			if (!incarnation) return;
+			const previous = hostCapCache.get(connectionId);
+			const merged =
+				previous?.generation === incarnation.generation ? new Set(previous.capabilities) : new Set<string>();
+			const nativeConfirmed =
+				previous?.generation === incarnation.generation ? new Set(previous.nativeConfirmed) : new Set<string>();
+			for (const capability of capabilities) merged.add(capability);
+			// Replay claims enable stream routing immediately, but only native snapshots
+			// can remove a socket from host demand. Merge delayed snapshots monotonically.
+			if (source === "native") {
+				for (const capability of capabilities) nativeConfirmed.add(capability);
+			}
 			hostCapCache.set(connectionId, {
 				generation: incarnation.generation,
-				capabilities: new Set(capabilities),
+				capabilities: merged,
+				nativeConfirmed,
 			});
 		};
 		const liveHostCapabilities = (connectionId: string): ReadonlySet<string> | undefined => {
@@ -5095,6 +5302,17 @@ export function createNotificationsExtension(
 			hostCapCache.delete(connectionId);
 			hostAttachedConnections.delete(connectionId);
 		};
+		const imageUploadsAvailable =
+			typeof terminalAbortSeams?.waitForRunSettlement === "function" &&
+			typeof terminalAbortSeams.getRunOwnerDomain === "function" &&
+			typeof terminalAbortSeams.getTerminalRunOwnerForEvent === "function" &&
+			typeof ctx.getActivePromptHandle === "function";
+		const imageUploads = imageUploadsAvailable
+			? new PromptImageUploadStore(connectionId => {
+					const incarnation = hostConnectionIncarnations.get(connectionId);
+					return incarnation !== undefined && !incarnation.closed;
+				})
+			: undefined;
 
 		const configOverrides = new Map<string, unknown>();
 		const configRevision = { current: 0 };
@@ -5110,6 +5328,115 @@ export function createNotificationsExtension(
 		const OWNED_SETTLEMENT_GRACE_MS = 500;
 		const promptSubmissionKey = (correlation: { commandId: string; turnId: string }) =>
 			`${correlation.commandId}:${correlation.turnId}`;
+		type AcceptedImageReservation = {
+			release: () => void;
+			preflightSignal: AbortSignal;
+			/** The producer can still retain ImageContent until settlement or exact run adoption. */
+			submissionPending: boolean;
+			/** A promoted queue entry needs its own run's proof before release authority transfers. */
+			awaitingAdoption: boolean;
+			accepted: boolean;
+			releaseRequested: boolean;
+		};
+		const acceptedImages = new Map<string, AcceptedImageReservation>();
+		// Absence means never consumed; a present undefined owner means execution
+		// started without exact ownership evidence and must remain charged.
+		const acceptedImageRunOwners = new Map<string, AgentTerminalOwnerContext | undefined>();
+		const retiringImages = new Set<string>();
+		const retireAcceptedImage = (key: string): void => {
+			const reservation = acceptedImages.get(key);
+			if (!reservation) return;
+			if (reservation.submissionPending || reservation.awaitingAdoption) {
+				reservation.releaseRequested = true;
+				return;
+			}
+			if (retiringImages.has(key)) return;
+			const discard = (): void => {
+				if (acceptedImages.get(key) !== reservation) return;
+				acceptedImages.delete(key);
+				acceptedImageRunOwners.delete(key);
+				retiringImages.delete(key);
+				reservation.release();
+			};
+			const owner = acceptedImageRunOwners.get(key);
+			if (!owner) {
+				if (acceptedImageRunOwners.has(key)) {
+					retiringImages.add(key);
+					logger.warn("SDK image capacity retained for execution without an exact resource owner");
+					return;
+				}
+				discard();
+				return;
+			}
+			const waitForSettlement = terminalAbortSeams?.waitForRunSettlement;
+			if (!waitForSettlement) return;
+			retiringImages.add(key);
+			retirePromptImageReservation(
+				owner.resourceRunId,
+				waitForSettlement,
+				() => acceptedImages.get(key) === reservation,
+				discard,
+			);
+		};
+		const settleAcceptedImageSubmission = (key: string, reservation: AcceptedImageReservation): void => {
+			if (acceptedImages.get(key) !== reservation || !reservation.submissionPending) return;
+			reservation.submissionPending = false;
+			if (reservation.releaseRequested) retireAcceptedImage(key);
+		};
+		const retainAcceptedImage = (
+			correlation: { commandId: string; turnId: string },
+			release: () => void,
+			preflightSignal: AbortSignal,
+			submissionSettled: Promise<void>,
+		): {
+			accepted: () => void;
+			promoted: (promotion: { startsOwnRun?: boolean; removed?: boolean }) => void;
+			refused: () => boolean;
+		} => {
+			const key = promptSubmissionKey(correlation);
+			const reservation: AcceptedImageReservation = {
+				release,
+				preflightSignal,
+				submissionPending: true,
+				awaitingAdoption: false,
+				accepted: false,
+				releaseRequested: false,
+			};
+			acceptedImages.set(key, reservation);
+			void submissionSettled.then(() => settleAcceptedImageSubmission(key, reservation));
+			return {
+				accepted: () => {
+					reservation.accepted = true;
+					if (reservation.preflightSignal.aborted) return;
+					if (acceptedImageRunOwners.get(key) && !reservation.awaitingAdoption) {
+						settleAcceptedImageSubmission(key, reservation);
+						if (reservation.releaseRequested) retireAcceptedImage(key);
+					}
+				},
+				promoted: promotion => {
+					reservation.awaitingAdoption = promotion.startsOwnRun === true && promotion.removed !== true;
+					if (!reservation.awaitingAdoption && reservation.releaseRequested) retireAcceptedImage(key);
+				},
+				refused: () => {
+					if (acceptedImages.get(key) !== reservation || acceptedImageRunOwners.has(key)) return false;
+					reservation.awaitingAdoption = false;
+					retireAcceptedImage(key);
+					return true;
+				},
+			};
+		};
+		const releaseAcceptedImage = (correlation: { commandId: string; turnId: string }): void =>
+			retireAcceptedImage(promptSubmissionKey(correlation));
+		const releaseAcceptedImagesForRun = (owner: AgentTerminalOwnerContext): void => {
+			for (const [key, runOwner] of acceptedImageRunOwners) {
+				if (!runOwner || runOwner.resourceRunId !== owner.resourceRunId || runOwner.domain !== owner.domain)
+					continue;
+				retireAcceptedImage(key);
+			}
+		};
+		const releaseAcceptedImages = (): void => {
+			for (const key of acceptedImages.keys()) retireAcceptedImage(key);
+		};
 		type PromptLifecycleFrame =
 			| {
 					type: "agent_start" | "agent_end";
@@ -5815,7 +6142,7 @@ export function createNotificationsExtension(
 			);
 		};
 		const emitPromptEvent = (event: AgentSessionEvent) => {
-			if (!runtime) return;
+			if (!runtime || runtime.stopping || runtime.serverStopped || runtimes.get(id) !== runtime) return;
 			cleanupPromptRecords();
 			const handle = ctx.getActivePromptHandle();
 			const domain = handle ? terminalAbortSeams?.getRunOwnerDomain?.(handle) : undefined;
@@ -5828,12 +6155,14 @@ export function createNotificationsExtension(
 				)
 			)
 				correlations.unshift(root);
+			const owners = new Set<string>();
 			for (const correlation of correlations) {
 				// Renewal is attributed exactly like the correlated delivery below.
 				renewPromptDeadline(correlation, event);
 				noteToolDispatchBoundary(correlation, event);
 				const submission = promptSubmissions.get(promptSubmissionKey(correlation));
 				if (!submission || submission.abandoned) continue;
+				owners.add(submission.connectionId);
 				const frame = {
 					type: "event",
 					kind: event.type,
@@ -5846,6 +6175,25 @@ export function createNotificationsExtension(
 				}
 				deliverCorrelatedFrame(submission, frame);
 			}
+			// Broker-created hosts use this bus, not the SDK-only extension. Observers
+			// must opt into BOTH capabilities and receive no other client's correlation.
+			// Keep cumulative partialResult snapshots and authoritative final result
+			// intact, and off the durable lifecycle replay ring, like owner content.
+			for (const connectionId of sdkRuntime?.connectionIdsWithCapabilities([
+				TURN_STREAM_CAPABILITY,
+				SESSION_HOST_OBSERVER_CAPABILITY,
+			]) ?? []) {
+				if (owners.has(connectionId)) continue;
+				try {
+					sdkRuntime?.sendFrameTo(connectionId, {
+						type: "event",
+						kind: event.type,
+						payload: toAgentWireEventPayload(event),
+					});
+				} catch {
+					// Content delivery is best-effort and must not interrupt execution.
+				}
+			}
 		};
 		/**
 		 * Status of a registered deadline expiry attempt after an awaited
@@ -6165,6 +6513,7 @@ export function createNotificationsExtension(
 					logger.warn(`sdk: failed to cancel fenced preflight: ${String(error)}`),
 				);
 			fencedConnections.add(submission.connectionId);
+			imageUploads?.disconnect(submission.connectionId);
 			host?.handleDisconnect(submission.connectionId);
 			for (const [key, owned] of promptSubmissions)
 				if (owned.connectionId === submission.connectionId) {
@@ -6197,6 +6546,21 @@ export function createNotificationsExtension(
 				submission.executionHandle = handle;
 				submission.preflightAbort = undefined;
 			}
+			if (acceptedImages.has(key) && !acceptedImageRunOwners.has(key)) {
+				acceptedImageRunOwners.set(key, undefined);
+				const domain = handle ? terminalAbortSeams?.getRunOwnerDomain?.(handle) : undefined;
+				if (handle && domain) acceptedImageRunOwners.set(key, { resourceRunId: handle, domain });
+			}
+			const imageReservation = acceptedImages.get(key);
+			if (
+				imageReservation?.accepted &&
+				!imageReservation.preflightSignal.aborted &&
+				acceptedImageRunOwners.get(key)
+			) {
+				imageReservation.awaitingAdoption = false;
+				settleAcceptedImageSubmission(key, imageReservation);
+				if (imageReservation.releaseRequested) retireAcceptedImage(key);
+			}
 		};
 		const onPromptDiverted = (correlation: { commandId: string; turnId: string }) => {
 			const submission = promptSubmissions.get(promptSubmissionKey(correlation));
@@ -6384,6 +6748,7 @@ export function createNotificationsExtension(
 					return;
 				}
 				if (capture) capture.proof = proof;
+				releaseAcceptedImage(correlation);
 			}
 			if (deadlineAttempt) {
 				// Durability BEFORE the durable terminal (#5583, #5623 review round 4).
@@ -6408,21 +6773,12 @@ export function createNotificationsExtension(
 				if (
 					winner.kind === "failed" &&
 					winner.code === "prompt_deadline_exceeded" &&
-					settings?.get("sdk.flushWorktreeOnDeadline") !== false
+					!deadlineFlushSuppressed(settings)
 				) {
-					// `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 = settings?.get("sdk.flushWorktreeOnDeadline");
-					const hasExplicitSetting =
-						typeof settings?.has === "function"
-							? settings.has("sdk.flushWorktreeOnDeadline")
-							: configured === true;
-					const explicitOptIn = hasExplicitSetting === true && configured === true;
+					// Same opt-in as the session runtime: user/global config or a runtime
+					// override, never a project `.gjc` file or the schema default.
 					await runBoundedDeadlineFlush(signal =>
-						flushWorktreeOnPromptDeadline(ctx.cwd, {
-							agentDir: settings?.getAgentDir(),
-							explicitOptIn,
+						autosaveWorktreeOnPromptDeadline(ctx.cwd, settings, {
 							isCurrent: () =>
 								deadlineAttemptStatus(promptSubmissionKey(correlation), submission, deadlineAttempt) ===
 								"current",
@@ -6611,7 +6967,8 @@ export function createNotificationsExtension(
 		};
 		const recordPromptFailure = async (correlation: { commandId: string; turnId: string }, error: unknown) => {
 			const submission = promptSubmissions.get(promptSubmissionKey(correlation));
-			if (!submission) return;
+			if (!submission || submission.terminal || submission.failed) return;
+			releaseAcceptedImage(correlation);
 			submission.failed = true;
 			removePendingPromptCorrelation(correlation);
 			if (
@@ -6621,6 +6978,29 @@ export function createNotificationsExtension(
 				runtime.activePromptCorrelation = undefined;
 			await emitPromptFailure(correlation, error);
 		};
+		const recordQueuedRunStartFailure = (
+			correlation: { commandId: string; turnId: string },
+			failure: QueuedRunStartFailure,
+			sdkRunToken: string | undefined,
+			refuseImage: (() => boolean) | undefined,
+		): boolean => {
+			const key = promptSubmissionKey(correlation);
+			const submission = promptSubmissions.get(key);
+			// A present undefined owner is already-started execution, not no-start evidence.
+			if (
+				failure.disposition !== "not-started" ||
+				(submission && submission.sdkRunToken !== sdkRunToken) ||
+				submission?.executionHandle !== undefined ||
+				acceptedImageRunOwners.has(key)
+			)
+				return false;
+			// Reservation proof outlives the mutable receipt. The captured lifecycle
+			// checks reservation identity and keeps the pending producer fenced.
+			if (refuseImage ? !refuseImage() : !submission) return false;
+			if (submission && !submission.terminal && !submission.failed)
+				trackReconciliationProducer(recordPromptFailure(correlation, failure.error));
+			return true;
+		};
 		const acknowledgePrompt = (connectionId: string, correlation: { commandId: string; turnId: string }) => {
 			const key = promptSubmissionKey(correlation);
 			const submission = promptSubmissions.get(key);
@@ -6653,6 +7033,7 @@ export function createNotificationsExtension(
 				selector => kindReconciliation.lookupSteer(selector),
 				() => host,
 				options.primaryControlSurface ?? "sdk",
+				imageUploadsAvailable,
 			),
 			id,
 			revisions,
@@ -6663,12 +7044,17 @@ export function createNotificationsExtension(
 			pendingInteractive,
 			gatePresentations,
 			api,
+			imageUploads,
+			imageUploadsAvailable,
+			retainAcceptedImage,
+			releaseAcceptedImage,
 			() =>
 				runtime?.busy === true ||
 				pendingPromptCorrelations.length > 0 ||
 				pendingPromptCorrelationsBySdkRunToken.size > 0,
 			recordPromptAccepted,
 			recordPromptFailure,
+			recordQueuedRunStartFailure,
 			discardPromptAcceptance,
 			onPromptDiverted,
 			onPromptPromoted,
@@ -6732,11 +7118,19 @@ export function createNotificationsExtension(
 						await terminalizePrompt({ commandId, turnId }, cancellationOutcome, {
 							fence: hasExecutionHandle || !submission.preflightAbort,
 						});
+						if (!hasExecutionHandle && submission.preflightAbort) releaseAcceptedImage({ commandId, turnId });
 					}
 				}
 				return { aborted: true, disposition: "cancelled" as const };
 			},
-			async (connectionId, scope, idempotencyKey, preflightCancel, noOtherConnectionPreflights) => {
+			async (
+				connectionId,
+				scope,
+				idempotencyKey,
+				preflightCancel,
+				noOtherConnectionPreflights,
+				operatorAuthorized = false,
+			) => {
 				// Capture the steering snapshot at ADMISSION (before the durable
 				// marker transaction): client steering admitted while the abort
 				// is in flight classifies as post-snapshot and is preserved at
@@ -7098,9 +7492,9 @@ export function createNotificationsExtension(
 						return "failed";
 					}
 				};
-				let active = [...promptSubmissions.entries()].find(
-					([, submission]) => submission.connectionId === connectionId && !submission.terminal,
-				);
+				const addresses = (submission: TerminalAbortSubmissionScope): boolean =>
+					terminalAbortAddressesSubmission({ connectionId, operatorAuthorized, submission });
+				let active = [...promptSubmissions.entries()].find(([, submission]) => addresses(submission));
 				if (!active) {
 					// DURABLY reserve the key even for a no-active-turn abort: the
 					// generic idempotency cache is in-memory only, so after restart
@@ -7130,9 +7524,7 @@ export function createNotificationsExtension(
 					// and the durable no-effect row would block a same-key retry from
 					// stopping it — fall through to the pre-run / active fencing path
 					// when a submission now exists (review thread P1).
-					active = [...promptSubmissions.entries()].find(
-						([, submission]) => submission.connectionId === connectionId && !submission.terminal,
-					);
+					active = [...promptSubmissions.entries()].find(([, submission]) => addresses(submission));
 					if (!active) {
 						// Close the remaining acceptance race: cancel the requester's
 						// preflights HERE, in the same synchronous region as the
@@ -8157,6 +8549,10 @@ export function createNotificationsExtension(
 		runtime = {
 			server,
 			host,
+			imageUploads,
+			releaseAcceptedImage,
+			releaseAcceptedImagesForRun,
+			releaseAcceptedImages,
 			getJoinedPromptCorrelations,
 			isPromptRunOwner: (correlation, owner) => {
 				const handle = promptSubmissions.get(promptSubmissionKey(correlation))?.executionHandle;
@@ -8296,6 +8692,7 @@ export function createNotificationsExtension(
 				string,
 				{ toolName: string; args?: unknown; pendingPhase?: "completed" | "failed" | "cancelled" }
 			>(),
+			awaitingInput: new Map(),
 			deferredInboundControls: [],
 		};
 		const initializedRuntime = runtime;
@@ -8415,7 +8812,18 @@ export function createNotificationsExtension(
 						sendEndpointStale(inbound.connectionId, typedFrame);
 						return;
 					}
+					if (typedFrame.type === "control_request" && !liveHostConnection(inbound.connectionId)) {
+						sendEndpointStale(inbound.connectionId, typedFrame);
+						return;
+					}
 					if (typedFrame.type === "event_replay") {
+						const capabilities = typedFrame.capabilities;
+						if (
+							Array.isArray(capabilities) &&
+							capabilities.every((capability: unknown) => typeof capability === "string")
+						) {
+							rememberHostCapabilities(inbound.connectionId, capabilities as string[], "replay");
+						}
 						if (liveHostConnection(inbound.connectionId)) hostAttachedConnections.add(inbound.connectionId);
 					}
 					if (typedFrame.type === "ephemeral_turn" || typedFrame.type === "ephemeral_turn_cancel") return;
@@ -8460,7 +8868,7 @@ export function createNotificationsExtension(
 				const negotiated = tuple?.[1] ?? capabilities;
 				if (typeof id !== "string" || !Array.isArray(negotiated)) return;
 				const normalized = negotiated.filter((capability): capability is string => typeof capability === "string");
-				rememberHostCapabilities(id, normalized);
+				rememberHostCapabilities(id, normalized, "native");
 				if (liveHostCapabilities(id) === undefined) return;
 				hostAttachedConnections.add(id);
 				negotiatedCapabilitiesHandler?.(id, normalized);
@@ -8468,6 +8876,7 @@ export function createNotificationsExtension(
 			server.onConnectionClose((_err, connectionId) => {
 				if (!connectionId) return;
 				closeHostConnection(connectionId);
+				imageUploads?.disconnect(connectionId);
 				connectionCloseHandler?.(connectionId);
 				void controlSurface
 					.cancelPendingPreflightsForConnection(connectionId)
@@ -9003,8 +9412,10 @@ export function createNotificationsExtension(
 				attachedClients: () => server.clientCount(),
 				observerClients: () => {
 					if (workLease.isHeld()) return 0;
-					const observers = [...hostCapCache.keys()].filter(connectionId =>
-						liveHostCapabilities(connectionId)?.has(SESSION_HOST_OBSERVER_CAPABILITY),
+					const observers = [...hostCapCache.entries()].filter(
+						([connectionId, entry]) =>
+							liveHostCapabilities(connectionId)?.has(SESSION_HOST_OBSERVER_CAPABILITY) &&
+							entry.nativeConfirmed.has(SESSION_HOST_OBSERVER_CAPABILITY),
 					).length;
 					return Math.min(server.clientCount(), observers);
 				},
@@ -9459,6 +9870,7 @@ export function createNotificationsExtension(
 			runtime.gatePresentations?.activateDeferred(runtime.workflowGatePublicationEpoch);
 			flushPendingFinal(runtime, runtime.id);
 			flushPendingSettled(runtime, runtime.id);
+			deliverAwaitingInput(runtime, runtime.id);
 			for (const processControl of runtime.deferredInboundControls.splice(0)) processControl();
 		},
 		reproveOwnership: async binding => {
@@ -10069,6 +10481,7 @@ export function createNotificationsExtension(
 		// The Agent's terminal owner is independent of delivery correlation. Never
 		// borrow a successor's run handle to settle a predecessor's SDK prompts.
 		const terminalOwner = terminalAbortSeams?.getTerminalRunOwnerForEvent?.(event);
+		if (terminalOwner) rt.releaseAcceptedImagesForRun(terminalOwner);
 		const rootCorrelation = rt.activePromptCorrelation;
 		const correlations = terminalOwner ? rt.getJoinedPromptCorrelations(terminalOwner) : [];
 		if (
@@ -10085,6 +10498,7 @@ export function createNotificationsExtension(
 			// subsequent durable terminal claim fails. A fatal transport closure
 			// clears attribution, so an unrelated later agent_end cannot settle a
 			// predecessor's prompt correlation.
+			if (terminalOwner) rt.releaseAcceptedImage(correlation);
 			const assistants = (Array.isArray(event.messages) ? [...event.messages].reverse() : []).filter(
 				message => message && typeof message === "object" && (message as { role?: unknown }).role === "assistant",
 			) as Array<{ stopReason?: unknown; errorKind?: unknown; errorCode?: unknown }>;
@@ -10360,8 +10774,18 @@ export function createNotificationsExtension(
 	});
 
 	api.on("tool_execution_update", (event, ctx) => {
-		const rt = runtimes.get(sessionId(ctx));
+		const id = sessionId(ctx);
+		const rt = runtimes.get(id);
 		rt?.emitPromptEvent(event);
+		if (!rt) return;
+		const awaitingInput = readAwaitingInput(event.partialResult);
+		if (!awaitingInput || rt.awaitingInput.has(event.toolCallId)) return;
+		// Notify-only and content-free (prompt kind only, never the URL or code), so
+		// it is delivered under redaction exactly like the idle marker. While policy
+		// is provisional it stays pending; activation delivers it if the call is
+		// still running.
+		rt.awaitingInput.set(event.toolCallId, { toolName: event.toolName, kind: awaitingInput.kind, delivered: false });
+		deliverAwaitingInput(rt, id);
 	});
 
 	api.on("tool_execution_end", (event, ctx) => {
@@ -10369,6 +10793,7 @@ export function createNotificationsExtension(
 		const rt = runtimes.get(id);
 		if (!rt) return;
 		rt.emitPromptEvent(event);
+		rt.awaitingInput.delete(event.toolCallId);
 		const inFlight = rt.inFlightTools.get(event.toolCallId);
 		if (!inFlight) return;
 		if (!rt.notificationsActive) {