@gajae-code/coding-agent 0.18.12 → 0.19.0

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

@@ -4,7 +4,12 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { promisify } from "node:util";
-import { isContinuingMidRunMaintenanceOutcome, isNonDispatchedToolEvent, ThinkingLevel } from "@gajae-code/agent-core";
+import {
+	isContinuingMidRunMaintenanceOutcome,
+	isNonDispatchedToolEvent,
+	type RunSettlementProof,
+	ThinkingLevel,
+} from "@gajae-code/agent-core";
 import type { AttemptScope } from "@gajae-code/agent-core/attempt-scope";
 import type { Api, ImageContent, Model, ProviderDiagnostic } from "@gajae-code/ai/core";
 
@@ -39,7 +44,7 @@ import { tagSdkLifecycleObserver } from "../../extensibility/extensions/function
 import type { AgentEndEvent } from "../../extensibility/shared-events";
 import { normalizeGoal } from "../../goals/state";
 import { toAgentWireEventPayload } from "../../modes/shared/agent-wire/event-envelope";
-import type { AgentSessionEvent } from "../../session/agent-session";
+import type { AgentSessionEvent, QueuedRunStartFailure } from "../../session/agent-session";
 import type { SdkRunCapability } from "../../session/sdk-run-capability";
 import {
 	boundTerminalRetentionState,
@@ -125,6 +130,7 @@ import {
 	TURN_STREAM_CAPABILITY,
 } from "./host";
 import { clearAutoroutingInactive, isAutoroutingInactive, markAutoroutingInactive } from "./internal-autorouting-state";
+import { PromptImageUploadStore, retirePromptImageReservation } from "./prompt-image-upload";
 import { CursorRegistry, QueryHandlers, RevisionStore, type SessionSurface } from "./query";
 import { createSdkRunCapability } from "./sdk-run-capability";
 import {
@@ -350,6 +356,8 @@ export interface SessionSdkTransport {
 	stop(): Promise<void>;
 	broadcastFrame?(frame: SdkFrame): void;
 	onConnectionClose?(handler: (connectionId: string) => void): undefined | (() => void);
+	/** Authoritative live socket membership, not a cache of previously observed frames. */
+	isConnectionOpen?(connectionId: string): boolean;
 	onNegotiatedCapabilities?(
 		handler: (connectionId: string, capabilities: readonly string[]) => void,
 	): undefined | (() => void);
@@ -357,6 +365,7 @@ export interface SessionSdkTransport {
 
 export interface SessionSdkRuntimeOptions
 	extends Omit<SessionSdkHostOptions, "sessionId" | "stateRoot" | "token" | "sendFrame" | "onFrame"> {
+	onDisconnected?: (connectionId: string) => void;
 	transport: SessionSdkTransport;
 	/** Session settings; enables `config.patch` application on this runtime. */
 	settings?: Settings;
@@ -443,6 +452,8 @@ export interface SdkOnlyReconciliationStore {
 }
 
 export interface SdkOnlyTerminalAbortSeams {
+	/** Definitive event-driven observation: never abort, seal or quarantine a run to reclaim images. */
+	waitForRunSettlement?: (handle: string) => Promise<RunSettlementProof>;
 	getReconciliationStore?: () => SdkOnlyReconciliationStore | undefined;
 	getTerminalTurnEpoch: () => number | undefined;
 	getActivePromptHandle: () => string | undefined;
@@ -521,6 +532,10 @@ export interface SdkOnlyDeadlineRecoveryCheckpoint {
  * dispatch, replay/event publication, and reverse-provider lifecycle without
  * importing any notification adapter or native notification class.
  */
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item: unknown) => typeof item === "string");
+}
+
 export class SessionSdkSessionRuntime {
 	readonly host: SessionSdkHost;
 	readonly transport: SessionSdkTransport;
@@ -551,18 +566,32 @@ export class SessionSdkSessionRuntime {
 			onFrame: handler =>
 				options.transport.onFrame((connectionId, frame) => {
 					this.#connectionIds.add(connectionId);
+					if (
+						!options.connectionCapabilities &&
+						frame.type === "event_replay" &&
+						isStringArray(frame.capabilities)
+					) {
+						this.#connectionCapabilities.set(
+							connectionId,
+							new Set([...(this.#connectionCapabilities.get(connectionId) ?? []), ...frame.capabilities]),
+						);
+					}
 					handler(connectionId, frame);
 				}),
 		});
 		this.#connectionDisposer = options.transport.onConnectionClose?.(connectionId => {
 			this.#connectionIds.delete(connectionId);
 			this.#connectionCapabilities.delete(connectionId);
+			options.onDisconnected?.(connectionId);
 			this.host.handleDisconnect(connectionId);
 		});
 		this.#capabilitiesDisposer = options.transport.onNegotiatedCapabilities?.((connectionId, negotiated) => {
 			if (options.connectionCapabilities && this.#connectionCapabilitiesProvider(connectionId) === undefined) return;
 			this.#connectionIds.add(connectionId);
-			this.#connectionCapabilities.set(connectionId, new Set(negotiated));
+			this.#connectionCapabilities.set(
+				connectionId,
+				new Set([...(this.#connectionCapabilities.get(connectionId) ?? []), ...negotiated]),
+			);
 		});
 		this.#malformedDisposer = options.transport.onMalformedFrame?.((connectionId, message) => {
 			this.host.handleMalformedFrame(connectionId, message);
@@ -2215,6 +2244,8 @@ export interface SdkSurfaceFactoryOptions {
 	api: ExtensionAPI;
 	/** Startup surface that owns host-level permission and lifecycle authority. */
 	primaryControlSurface?: "cli" | "sdk";
+	/** Private staging controls are advertised only with authoritative transport liveness. */
+	imageUploadsAvailable?: boolean;
 	policy?: SdkSurfacePolicy;
 	getInstalledDefinitions?: (capability: string) => unknown | undefined;
 	getLiveState?: () => { isStreaming: boolean; steeringQueueDepth: number; followupQueueDepth: number };
@@ -2298,7 +2329,8 @@ function createQuerySurface(
 	};
 	const getProfileCredentialSessionId = () => ctx.credentialSessionId ?? id;
 	const profileSettings = (options.settings ?? ctx.settings) as Pick<Settings, "get"> | undefined;
-	const getProfileAvailableModels = (): Model<Api>[] => ctx.modelRegistry.getAvailable();
+	const getProfileAvailableModels = (): Model<Api>[] =>
+		ctx.modelRegistry.getAvailable(getProfileCredentialSessionId());
 	const resolveProfileAvailability = async (
 		profile: ModelProfileDefinition,
 		authenticatedProviders: ReadonlySet<string>,
@@ -2519,7 +2551,7 @@ function createQuerySurface(
 		getDiff,
 		getUsage: () => ctx.sessionManager.getUsageStatistics(),
 		getModels: async () => {
-			const models = ctx.modelRegistry.getAll();
+			const models = ctx.modelRegistry.getAll(getProfileCredentialSessionId());
 			const currentModel = ctx.model;
 			const currentThinkingLevel = api.getThinkingLevel();
 			const activeProfile =
@@ -2642,7 +2674,9 @@ function createQuerySurface(
 		getBranchCandidates: () => ctx.getBranchCandidates(),
 		getLastAssistant: lastAssistant,
 		getCapabilities: () => createSdkCapabilities(policy, hasHostTools(), options.primaryControlSurface),
-		getAuthProviders: () => [...new Set(ctx.modelRegistry.getAll().map(model => model.provider))],
+		getAuthProviders: () => [
+			...new Set(ctx.modelRegistry.getAll(getProfileCredentialSessionId()).map(model => model.provider)),
+		],
 		getActiveProviders: () => ctx.modelRegistry.getActiveProviders(),
 		getTools: () => {
 			const tools = typeof (ctx as Partial<ExtensionContext>).getAllTools === "function" ? ctx.getAllTools() : [];
@@ -2720,7 +2754,11 @@ export function createSdkSurfaceFactory(
 ): SdkSurfaceFactory {
 	const policy =
 		options.policy ??
-		createSdkSurfacePolicyForContext(options.ctx, hasSdkWorkflowGateCapability(options.ctx.workflowGate));
+		createSdkSurfacePolicyForContext(
+			options.ctx,
+			hasSdkWorkflowGateCapability(options.ctx.workflowGate),
+			options.imageUploadsAvailable,
+		);
 	const reconciliation =
 		options.reconciliation ??
 		createInvocationReconciliation({
@@ -3106,6 +3144,7 @@ function createControlSurface(
 	) => void,
 	armPromptDeadline: (correlation: InvocationCorrelation) => void,
 	steerReconciliation: KindAwareReconciliation,
+	imageUploads: PromptImageUploadStore | undefined,
 	onPromotedTurn?: (
 		kind: InvocationKind,
 		correlation: InvocationCorrelation,
@@ -3133,7 +3172,15 @@ function createControlSurface(
 	trackGateResolution: <T>(resolution: Promise<T>) => Promise<T> = async resolution => await resolution,
 	onInvocationCompletionReconciledForTests?: (kind: InvocationKind, correlation: InvocationCorrelation) => void,
 	publishLifecycleFrame?: (frame: SdkFrame) => void,
+	retainAcceptedImage?: (correlation: InvocationCorrelation, release: () => void) => void,
+	settleAcceptedImageSubmission?: (correlation: InvocationCorrelation) => void,
+	releaseAcceptedImage?: (correlation: InvocationCorrelation) => void,
 	acceptedQueueCancellations: Map<string, AcceptedQueueCancellation> = new Map(),
+	onQueuedRunStartFailed?: (
+		kind: InvocationKind,
+		correlation: InvocationCorrelation,
+		failure: QueuedRunStartFailure,
+	) => boolean,
 ): ControlSurface {
 	const normalizePromptImages = (value: unknown): ImageContent[] => {
 		if (!Array.isArray(value)) return [];
@@ -3154,6 +3201,7 @@ function createControlSurface(
 	type InternalSendOptions = NonNullable<Parameters<ExtensionAPI["sendUserMessage"]>[1]> & {
 		sdkRunCapability?: SdkRunCapability;
 		expectedSdkRunToken?: string;
+		onQueuedRunStartFailed?: (failure: QueuedRunStartFailure) => void;
 	};
 	type InternalSdkApi = Omit<ExtensionAPI, "sendUserMessage"> & {
 		sendUserMessage: (
@@ -3164,7 +3212,7 @@ function createControlSurface(
 	const internalApi = api as InternalSdkApi;
 	const sendSdkUserMessage = (
 		content: Parameters<ExtensionAPI["sendUserMessage"]>[0],
-		options?: Record<string, unknown>,
+		options?: InternalSendOptions,
 	): Promise<void> => internalApi.sendUserMessage(content, options);
 	const surfacePolicy =
 		policy ?? createSdkSurfacePolicyForContext(ctx, hasSdkWorkflowGateCapability(ctx.workflowGate));
@@ -3174,8 +3222,14 @@ function createControlSurface(
 		const [provider, ...modelId] = id.split("/");
 		const model =
 			modelId.length > 0
-				? ctx.modelRegistry.find(provider, modelId.join("/"))
-				: ctx.modelRegistry.getAll().find(candidate => candidate.id === id);
+				? ctx.modelRegistry.find(
+						provider,
+						modelId.join("/"),
+						ctx.credentialSessionId ?? ctx.sessionManager.getSessionId(),
+					)
+				: ctx.modelRegistry
+						.getAll(ctx.credentialSessionId ?? ctx.sessionManager.getSessionId())
+						.find(candidate => candidate.id === id);
 		if (!model) throw Object.assign(new Error(`Model ${id} was not found.`), { code: "invalid_input" });
 		return model;
 	};
@@ -3301,11 +3355,13 @@ function createControlSurface(
 			onDispatchDisposition: (promotion: { startsOwnRun: boolean }) => void;
 			/** Fired when a queued submission (steering or follow-up) is promoted to its own run (SDK ownership correlation). */
 			onQueuedPromoted: (promotion?: { startsOwnRun?: boolean; removed?: boolean }) => void;
+			onQueuedRunStartFailed: (failure: QueuedRunStartFailure) => void;
 			queuedAtDispatch: boolean;
 		}) => Promise<unknown>,
 		acceptedFields?: () => Record<string, unknown>,
 		allowCompletionFallback = false,
 		alwaysQueued = false,
+		onCreated?: (correlation: InvocationCorrelation) => void,
 	): Promise<unknown> => {
 		// Capture the REQUESTING connection at admission: a terminal abort from
 		// another SDK connection must never stop the prompt this one accepts
@@ -3314,9 +3370,11 @@ function createControlSurface(
 		const retainedClientRef = normalizeClientRef(clientRef);
 		reconciliation.admit(kind, retainedClientRef);
 		const correlation = newCorrelation();
+		onCreated?.(correlation);
 		const sdkRunToken = `${correlation.commandId}:${correlation.turnId}`;
 		const sdkRunCapability = createSdkRunCapability(sdkRunToken);
 		const publishTerminal = (outcome: InvocationOutcome): void => {
+			releaseAcceptedImage?.(correlation);
 			retireAcceptedQueueCancellation(acceptedQueueCancellations, correlation);
 			publishLifecycleFrame?.({
 				type: "agent_end",
@@ -3350,6 +3408,7 @@ function createControlSurface(
 		};
 		let accepted = false;
 		let settled = false;
+		let submission: Promise<unknown> | undefined;
 		const cancelPreflight = () => {
 			preflightController.abort();
 			if (settled) return;
@@ -3409,14 +3468,16 @@ function createControlSurface(
 		if (kind === "prompt")
 			acceptedQueueCancellations.set(`${correlation.commandId}:${correlation.turnId}`, queueCancellation);
 		let promotionStartsOwnRun: boolean | undefined;
+		let queuedRunStartRefused = false;
 		try {
-			const submission = Promise.resolve(
+			submission = Promise.resolve(
 				run({
 					onPreflightAccepted: () => void accept().catch(() => undefined),
 					preflightSignal: preflightController.signal,
 					sdkRunCapability,
 					onPreflightAcceptCommit: accept,
 					onDispatchDisposition: promotion => {
+						if (queuedRunStartRefused) return;
 						promotionStartsOwnRun = promotion.startsOwnRun;
 						if (promotion.startsOwnRun === false) {
 							queueCancellation.queueCandidate = true;
@@ -3436,6 +3497,7 @@ function createControlSurface(
 					// created at promotion so the submitting connection can
 					// terminal-abort that turn (review threads P1/P2).
 					onQueuedPromoted: (promotion?: { startsOwnRun?: boolean; removed?: boolean }) => {
+						if (queuedRunStartRefused) return;
 						promotionStartsOwnRun = promotion?.startsOwnRun;
 						if (promotion?.removed) {
 							queueCancellation.disposition = "removed";
@@ -3469,11 +3531,29 @@ function createControlSurface(
 						}
 						void onPromotedTurn?.(kind, correlation, requesterConnectionId, sdkRunToken, promotion);
 					},
+					onQueuedRunStartFailed: failure => {
+						if (
+							queuedRunStartRefused ||
+							!accepted ||
+							!queueCancellation.queueCandidate ||
+							failure.disposition !== "not-started"
+						)
+							return;
+						// Only the private Core decision for this selected queue entry is proof.
+						// The lifecycle owner rejects contradictory decisions after adoption.
+						queuedRunStartRefused = onQueuedRunStartFailed?.(kind, correlation, failure) === true;
+						if (queuedRunStartRefused) {
+							queueCancellation.disposition = "consumed";
+							queueCancellation.resolveDisposition("consumed");
+						}
+					},
 					queuedAtDispatch,
 				}),
 			);
 			void submission.then(
 				result => {
+					settleAcceptedImageSubmission?.(correlation);
+					if (queuedRunStartRefused) return;
 					if (settled) {
 						// A resolved submission after preflight acceptance means the work is over
 						// for every kind. `noteTransition` ignores an already-terminal record, so
@@ -3484,7 +3564,9 @@ function createControlSurface(
 						// a delayed preflight diverted to steering fires onQueuedPromoted
 						// with startsOwnRun:false and is now attached to the in-flight run.
 						// Do not terminalize from the stale snapshot — the run will.
-						if (!queuedAtDispatch && promotionStartsOwnRun !== false) {
+						// Remember actual diversion even after own-run promotion changes
+						// promotionStartsOwnRun: enqueue completion is still not run completion.
+						if (!queueCancellation.queueCandidate && promotionStartsOwnRun !== false) {
 							// The accepted work settled without its own run still pending:
 							// retire the pending ownership entry (and with it the
 							// acceptance-anchored deadline lease, #4668 review) BEFORE
@@ -3553,7 +3635,10 @@ function createControlSurface(
 					);
 				},
 				error => {
+					settleAcceptedImageSubmission?.(correlation);
+					if (queuedRunStartRefused) return;
 					if (settled) {
+						releaseAcceptedImage?.(correlation);
 						retireAcceptedQueueCancellation(acceptedQueueCancellations, correlation);
 						// The submission promise rejects after preflight acceptance only when the
 						// work itself is over (provider stream interrupt, abort, queue failure).
@@ -3675,6 +3760,9 @@ function createControlSurface(
 				...(acceptedFields?.() ?? {}),
 			};
 		} catch (error) {
+			if (!accepted) preflightController.abort();
+			if (!submission) settleAcceptedImageSubmission?.(correlation);
+			releaseAcceptedImage?.(correlation);
 			retireAcceptedQueueCancellation(acceptedQueueCancellations, correlation);
 			if (!accepted) reconciliation.release(kind, retainedClientRef);
 			throw error;
@@ -4593,28 +4681,57 @@ function createControlSurface(
 		}
 	};
 	return {
-		prompt: async (text, images, clientRef) => {
-			const invalid = validateRequiredPromptText("turn.prompt", { text, images });
+		prompt: async (text, images, clientRef, stagedImages) => {
+			const invalid = validateRequiredPromptText("turn.prompt", { text, images, stagedImages });
 			if (invalid) throw Object.assign(new Error(invalid.message), { code: invalid.code });
-			return await submit("prompt", clientRef, ({ queuedAtDispatch, sdkRunCapability, ...options }) =>
-				sendSdkUserMessage(
-					typeof images === "undefined"
-						? text
-						: ([{ type: "text", text }, ...normalizePromptImages(images)] as [
-								{ type: "text"; text: string },
-								...ImageContent[],
-							]),
-					{
-						...options,
-						sdkRunCapability,
-						// ACP terminal settlement is owned by the correlated agent_end
-						// publication. Post-prompt recovery may include independent
-						// subagent work and must not hold that client-facing boundary.
-						...(queuedAtDispatch ? { queuedAtDispatch: true } : {}),
+			if (stagedImages !== undefined && images !== undefined)
+				throw Object.assign(new Error("Direct and staged images cannot be mixed."), { code: "invalid_input" });
+			if (stagedImages !== undefined && !imageUploads)
+				throw Object.assign(new Error("Image uploads are unavailable."), { code: "operation_prohibited" });
+			let reservation: { images: ImageContent[]; release: () => void } | undefined;
+			let imageCorrelation: InvocationCorrelation | undefined;
+			try {
+				return await submit(
+					"prompt",
+					clientRef,
+					({ queuedAtDispatch, sdkRunCapability, ...options }) => {
+						// submit has reserved reconciliation/clientRef before consuming staged IDs.
+						if (stagedImages !== undefined) {
+							reservation = imageUploads!.redeem(sdkControlRequesterContext.getStore(), stagedImages);
+							if (imageCorrelation && retainAcceptedImage)
+								retainAcceptedImage(imageCorrelation, reservation.release);
+						}
+						return sendSdkUserMessage(
+							typeof images === "undefined" && !reservation
+								? text
+								: ([{ type: "text", text }, ...(reservation?.images ?? normalizePromptImages(images))] as [
+										{ type: "text"; text: string },
+										...ImageContent[],
+									]),
+							{ ...options, sdkRunCapability, ...(queuedAtDispatch ? { queuedAtDispatch: true } : {}) },
+						);
 					},
-				),
-			);
+					undefined,
+					false,
+					false,
+					correlation => {
+						if (retainAcceptedImage) imageCorrelation = correlation;
+					},
+				);
+			} catch (error) {
+				if (imageCorrelation) releaseAcceptedImage?.(imageCorrelation);
+				else reservation?.release();
+				throw error;
+			}
 		},
+		...(imageUploads
+			? {
+					imageBegin: (input: unknown) => imageUploads.begin(sdkControlRequesterContext.getStore(), input),
+					imageAppend: (input: unknown) => imageUploads.append(sdkControlRequesterContext.getStore(), input),
+					imageFinish: (input: unknown) => imageUploads.finish(sdkControlRequesterContext.getStore(), input),
+					imageDiscard: (input: unknown) => imageUploads.discard(sdkControlRequesterContext.getStore(), input),
+				}
+			: {}),
 		steer: async (text, clientRef, expectedSdkRunToken) => {
 			const invalid = validateRequiredPromptText("turn.steer", { text });
 			if (invalid) throw Object.assign(new Error(invalid.message), { code: invalid.code });
@@ -4869,7 +4986,9 @@ function createControlSurface(
 		retryLast: () => typed("retry.last"),
 		retryNow: () => typed("retry.now"),
 		backgroundBash: () => typed("bash.background"),
-		installedOperations: surfacePolicy.installedControls,
+		installedOperations: imageUploads
+			? surfacePolicy.installedControls
+			: new Set([...surfacePolicy.installedControls].filter(operation => !operation.startsWith("turn.image."))),
 		revisionProvider: resource => (resource === "config" ? String(configRevision.current) : undefined),
 	};
 }
@@ -5019,6 +5138,89 @@ function quiescingFrame(frame: Record<string, unknown>): Record<string, unknown>
 
 /** Install a complete SDK host for a session when notifications are inactive. */
 export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: CreateSdkSessionRuntimeOptions): void {
+	const acceptedImages = new Map<
+		string,
+		{
+			store: PromptImageUploadStore;
+			release: () => void;
+			handle?: string;
+			executionStarted?: boolean;
+			submissionPending?: boolean;
+			awaitingAdoption?: boolean;
+			releaseRequested?: boolean;
+			retiring?: boolean;
+		}
+	>();
+	const imageKey = (correlation: InvocationCorrelation): string => `${correlation.commandId}:${correlation.turnId}`;
+	const retireAcceptedImage = (key: string): void => {
+		const reservation = acceptedImages.get(key);
+		if (!reservation) return;
+		if ((reservation.submissionPending || reservation.awaitingAdoption) && !reservation.executionStarted) {
+			reservation.releaseRequested = true;
+			return;
+		}
+		if (reservation.retiring) return;
+		const release = (): void => {
+			if (acceptedImages.get(key) !== reservation) return;
+			acceptedImages.delete(key);
+			reservation.release();
+		};
+		if (!reservation.handle) {
+			if (reservation.executionStarted) {
+				reservation.retiring = true;
+				logger.warn("SDK image capacity retained for execution without an exact resource handle");
+				return;
+			}
+			release();
+			return;
+		}
+		const waitForSettlement = options.terminalAbortSeams?.waitForRunSettlement;
+		if (!waitForSettlement) return;
+		reservation.retiring = true;
+		retirePromptImageReservation(
+			reservation.handle,
+			waitForSettlement,
+			() => acceptedImages.get(key) === reservation,
+			release,
+		);
+	};
+	const releaseAcceptedImage = (correlation: InvocationCorrelation): void =>
+		retireAcceptedImage(imageKey(correlation));
+	const settleAcceptedImageSubmission = (correlation: InvocationCorrelation): void => {
+		const key = imageKey(correlation);
+		const reservation = acceptedImages.get(key);
+		if (!reservation) return;
+		reservation.submissionPending = false;
+		if (reservation.releaseRequested) {
+			reservation.releaseRequested = false;
+			retireAcceptedImage(key);
+		}
+	};
+	const bindAcceptedImage = (correlation: InvocationCorrelation, handle: string | undefined): void => {
+		const reservation = acceptedImages.get(imageKey(correlation));
+		if (!reservation) return;
+		reservation.awaitingAdoption = false;
+		reservation.executionStarted = true;
+		if (handle && reservation.handle === undefined) reservation.handle = handle;
+		if (reservation.releaseRequested) retireAcceptedImage(imageKey(correlation));
+	};
+	// Promotion commits a queued image to its next own-run before agent_start supplies the exact resource handle.
+	const awaitAcceptedImageAdoption = (correlation: InvocationCorrelation): void => {
+		const reservation = acceptedImages.get(imageKey(correlation));
+		if (reservation) reservation.awaitingAdoption = true;
+	};
+	const releaseImagesForStore = (store: PromptImageUploadStore | undefined): void => {
+		for (const [key, reservation] of acceptedImages) {
+			if (reservation.store !== store) continue;
+			retireAcceptedImage(key);
+		}
+	};
+	const pendingImageCleanups = new Set<PromptImageUploadStore>();
+	const completeImageCleanups = (): void => {
+		for (const store of pendingImageCleanups) releaseImagesForStore(store);
+		pendingImageCleanups.clear();
+	};
+	let currentImageUploads: PromptImageUploadStore | undefined;
 	const acceptedQueueCancellations = new Map<string, AcceptedQueueCancellation>();
 	const disposeAcceptedQueueCancellations = async (): Promise<void> => {
 		const cancellations = [...acceptedQueueCancellations.values()];
@@ -5549,6 +5751,10 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 	): Promise<void> => {
 		const current = lifecycleOwner?.state ?? active;
 		if (!current) return;
+		const imageRunHandle =
+			type === "agent_start" && acceptedImages.size > 0
+				? options.terminalAbortSeams?.getActivePromptHandle()
+				: undefined;
 		const failureBatch = lifecycleOwner?.batch;
 		const adoptLifecycleBatch = (batch: LifecycleBatch | undefined): void => {
 			current.activeInvocation = batch?.invocations[0];
@@ -5666,6 +5872,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			adoptLifecycleBatch(batch);
 			for (const entry of drained) {
 				if (entry.kind !== "prompt") continue;
+				bindAcceptedImage(entry.correlation, imageRunHandle);
 				if (current.deadlineManager.isExpiring(entry.correlation))
 					current.deadlineManager.captureExpiringRun(entry.correlation);
 				else current.deadlineManager.onRunStarted(entry.correlation);
@@ -6175,8 +6382,13 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		}
 		if (type === "agent_end" && isContinuingMidRunMaintenanceOutcome(maintenanceOutcome)) return;
 		if (type === "agent_end") {
-			for (const invocation of transitions)
+			for (const invocation of transitions) {
+				// A deadline can capture this event while the exact run still owns
+				// pending tools. Its settlement owner, not event capture, releases quota.
+				if (!current.deadlineManager.shouldDeferTerminalTransition(invocation.correlation))
+					releaseAcceptedImage(invocation.correlation);
 				retireAcceptedQueueCancellation(acceptedQueueCancellations, invocation.correlation);
+			}
 			if (current.lifecycleEpoch !== eventLifecycleEpoch) {
 				// A successor agent_start won the lifecycle race while this event's
 				// durable transitions were awaiting persistence. Retire the ended
@@ -6596,6 +6808,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 	const startRuntime = async (ctx: ExtensionContext): Promise<void> => {
 		if (active) return;
 		if (acceptedQueueCancellations.size > 0) await disposeAcceptedQueueCancellations();
+		completeImageCleanups();
 		if (active) return;
 		const sessionId = ctx.sessionManager.getSessionId();
 		const stateRoot = path.join(ctx.cwd, ".gjc", "state");
@@ -6947,6 +7160,10 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				await autosaveWorktreeOnPromptDeadline(ctx.cwd, options.settings, { isCurrent, signal });
 			},
 			onExpired: correlation => {
+				// The manager invokes retirement only after confirmed settlement and
+				// durable terminalization (including recovered queue removals), never
+				// merely because an inactivity timer fired or execution is uncertain.
+				releaseAcceptedImage(correlation);
 				retireAcceptedQueueCancellation(acceptedQueueCancellations, correlation, true);
 				const owner = lifecycleOwnerHolder.state;
 				if (owner) {
@@ -7011,6 +7228,9 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			ctx,
 			id: sessionId,
 			api,
+			imageUploadsAvailable:
+				typeof transport.isConnectionOpen === "function" &&
+				typeof options.terminalAbortSeams?.waitForRunSettlement === "function",
 			reconciliation,
 			turnResultLookup: selector => reconciliation.lookupResult(selector.kind, selector),
 			steerStatusLookup: selector => steerReconciliation.lookupSteer(selector),
@@ -7141,7 +7361,10 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					});
 					// 3. Release recovery ownership ONLY after durable terminalization.
 					deadlineManager.clear(correlation);
-					if (kind === "prompt") retireAcceptedQueueCancellation(acceptedQueueCancellations, correlation);
+					if (kind === "prompt") {
+						releaseAcceptedImage(correlation);
+						retireAcceptedQueueCancellation(acceptedQueueCancellations, correlation);
+					}
 					return true;
 				} catch (transitionError) {
 					// Keep prompt recovery leased; skill recovery has no prompt lease.
@@ -7159,6 +7382,14 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			return attempt(3);
 		};
 
+		// This is a private SDK transport facility. A frame-observer cache cannot
+		// establish that the authenticated connection still exists at redemption.
+		const imageUploads =
+			typeof transport.isConnectionOpen === "function" &&
+			typeof options.terminalAbortSeams?.waitForRunSettlement === "function"
+				? new PromptImageUploadStore(connectionId => transport.isConnectionOpen?.(connectionId) === true)
+				: undefined;
+		currentImageUploads = imageUploads;
 		const controlSurface = createControlSurface(
 			ctx,
 			api,
@@ -7195,7 +7426,13 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			},
 			correlation => deadlineManager.onAccepted(correlation),
 			steerReconciliation,
+			imageUploads,
 			(kind, correlation, connectionId, sdkRunToken, promotion) => {
+				if (!promotion?.removed) {
+					if (promotion?.startsOwnRun === false)
+						bindAcceptedImage(correlation, options.terminalAbortSeams?.getActivePromptHandle());
+					else awaitAcceptedImageAdoption(correlation);
+				}
 				const bindPromotedToken = (batch?: LifecycleBatch): void => {
 					const owner = lifecycleOwnerHolder.state;
 					if (sdkRunToken && owner)
@@ -7251,6 +7488,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				// with it.
 				const current = active;
 				if (current?.lifecycleActive) {
+					bindAcceptedImage(correlation, options.terminalAbortSeams?.getActivePromptHandle());
 					// If this correlation was already admitted as own-run via the
 					// idle snapshot (onAccepted -> pending) but later diverted to
 					// steering and consumed in-run, move it from pending to the
@@ -7411,7 +7649,47 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					throw error;
 				}
 			},
+			(correlation, release) => {
+				if (imageUploads)
+					acceptedImages.set(imageKey(correlation), {
+						store: imageUploads,
+						release,
+						submissionPending: true,
+					});
+			},
+			settleAcceptedImageSubmission,
+			releaseAcceptedImage,
 			acceptedQueueCancellations,
+			(kind, correlation, failure) => {
+				const record = reconciliation.lookup(kind, correlation) as { status?: string };
+				const reservation = acceptedImages.get(imageKey(correlation));
+				const terminal = record.status === "terminal_ok" || record.status === "failed";
+				if (record.status !== "accepted" && !(terminal && reservation)) return false;
+				// A known execution/handle retains exact-ledger authority even if a
+				// contradictory callback arrives later. Never downgrade adoption.
+				if (reservation?.executionStarted || reservation?.handle) return false;
+				const adopted = active?.openLifecycleBatches.some(batch =>
+					[...batch.invocations, ...batch.attachedInvocations].some(
+						entry => entry.kind === kind && imageKey(entry.correlation) === imageKey(correlation),
+					),
+				);
+				if (adopted) return false;
+				const index = pending.findIndex(entry => entry.kind === kind && entry.correlation === correlation);
+				if (index >= 0) {
+					const [removed] = pending.splice(index, 1);
+					if (removed) lifecycleRunOwners.delete(removed.sdkRunToken);
+				}
+				if (reservation) {
+					reservation.awaitingAdoption = false;
+					// Ordinary retirement still waits for an outstanding enqueue producer.
+					retireAcceptedImage(imageKey(correlation));
+				}
+				// Keep the existing durable-first failure/recovery owner; this is not
+				// queue removal, and cannot publish cancellation or synthetic success.
+				if (!terminal)
+					void terminalizeAbandonedSubmission(kind, correlation, rejectionRecoveryIntent(failure.error));
+				return true;
+			},
 		);
 		const installProviderDefinitions = (capability: string, definitions: unknown): void => {
 			if (capability === "permission") {
@@ -7479,6 +7757,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		};
 		runtime = new SessionSdkSessionRuntime({
 			transport,
+			onDisconnected: connectionId => imageUploads?.disconnect(connectionId),
 			eventRevision: () =>
 				typeof (ctx as Partial<ExtensionContext>).getTranscript === "function"
 					? ctx.getTranscript().length
@@ -7929,6 +8208,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		} catch (error) {
 			runtimeOwner.quiesceInput();
 			runtimeOwner.fenceGateResolutions();
+			imageUploads?.close();
 			active = undefined;
 			let queueCancellationFailure: unknown;
 			try {
@@ -7987,7 +8267,8 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			}
 			cursors.close();
 			await revisions.close().catch(() => undefined);
-			if (queueCancellationFailure !== undefined)
+			if (queueCancellationFailure !== undefined) {
+				if (imageUploads) pendingImageCleanups.add(imageUploads);
 				throw Object.assign(
 					new AggregateError(
 						[error, queueCancellationFailure],
@@ -7995,14 +8276,25 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					),
 					{ code: "sdk_reconciliation_teardown_failed" },
 				);
+			}
+			if (currentImageUploads === imageUploads) currentImageUploads = undefined;
+			releaseImagesForStore(imageUploads);
 			throw error;
 		}
 	};
 	const stopActive = async (cancelSkillRecovery = false, unregisterReason?: "detached_idle"): Promise<void> => {
 		const current = active;
-		if (!current) return;
+		if (!current) {
+			if (pendingImageCleanups.size > 0) {
+				await disposeAcceptedQueueCancellations();
+				completeImageCleanups();
+			}
+			return;
+		}
 		current.quiesceInput();
 		current.fenceGateResolutions();
+		const imageUploads = currentImageUploads;
+		imageUploads?.close();
 		let queueCancellationFailure: unknown;
 		try {
 			await disposeAcceptedQueueCancellations();
@@ -8068,6 +8360,10 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				allowLockContention: cancelSkillRecovery,
 				...(unregisterReason === undefined ? {} : { unregisterReason }),
 			});
+			if (queueCancellationFailure === undefined) {
+				if (currentImageUploads === imageUploads) currentImageUploads = undefined;
+				releaseImagesForStore(imageUploads);
+			} else if (imageUploads) pendingImageCleanups.add(imageUploads);
 		} catch (error) {
 			// Keep the immutable owner available for a retry when transport teardown
 			// fails after quiescing. Clearing `active` before stop prevents a second