@gajae-code/coding-agent 0.18.11 → 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,
@@ -73,7 +78,7 @@ import {
 	syntheticNamespaceCollision,
 } from "../model-profile-model";
 import { projectQ10Models } from "../models.js";
-import { flushWorktreeOnPromptDeadline } from "../prompt-deadline-flush";
+import { autosaveWorktreeOnPromptDeadline } from "../prompt-deadline-flush";
 import {
 	PromptDeadlineManager,
 	type PromptDeadlinePublicationResult,
@@ -103,6 +108,7 @@ import {
 	createKindAwareReconciliation,
 	createReconciliationStore,
 	type KindAwareReconciliation,
+	type ReconciliationStoreInstrumentationEvent,
 	resolveReconciliationSessionFile,
 } from "../reconciliation-extensions";
 import {
@@ -124,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 {
@@ -349,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);
@@ -356,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;
@@ -442,9 +452,13 @@ 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;
+	onDeadlineRecoveryCheckpointForTests?: (checkpoint: SdkOnlyDeadlineRecoveryCheckpoint) => void;
+	onPersistenceInstrumentationForTests?: (event: PersistenceInstrumentationEvent) => void;
 	/** Re-read the active prompt's owning SDK connection for the owner-mismatch
 	 *  recheck; falls back to the runtime-tracked owner when absent (review
 	 *  thread P1). */
@@ -481,6 +495,35 @@ export interface SdkOnlyTerminalAbortSeams {
 	maxDurableTerminalReservationsForTests?: number;
 }
 
+export interface SdkOnlyDeadlineRecoveryCheckpoint {
+	at: number;
+	stage:
+		| "terminalization-start"
+		| "terminalization-result"
+		| "publication-start"
+		| "publication-result"
+		| "note-transition-start"
+		| "note-transition-awaiting-finalization"
+		| "note-transition-finalization-ready"
+		| "note-transition-before-persist"
+		| "note-transition-persisted"
+		| "note-transition-persist-failed"
+		| "deadline-recovery-retired";
+	correlation: InvocationCorrelation;
+	result?: "settled" | "uncertain" | "published" | "not-published" | "rejected";
+	reason?: string;
+	recordStatus?: string;
+	recordRevision?: number;
+	recordTerminalAt?: number;
+	pendingFinalization?: boolean;
+	eventCaptured?: boolean;
+	eventPrepared?: boolean;
+	terminalCommitted?: boolean;
+	leaseCurrent?: boolean;
+	pendingToolCount?: number;
+	errorCode?: string;
+}
+
 /**
  * The transport-neutral SDK session runtime.
  *
@@ -489,6 +532,10 @@ export interface SdkOnlyTerminalAbortSeams {
  * 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;
@@ -519,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);
@@ -1024,8 +1085,26 @@ function canonicalizeHydratedDiagnostics(record: InvocationRecord): InvocationRe
 	return canonical;
 }
 
+export interface PersistenceInstrumentationEvent {
+	at: number;
+	phase: "enqueued" | "started" | "completed" | "failed";
+	operation?: string;
+	substep?: string;
+	error?: string;
+	/** Detailed information about lock acquisition, promise identity, db state, etc. */
+	detail?: string;
+	/** Time spent waiting (ms) before the operation started. */
+	waitMs?: number;
+}
+
 export function createInvocationReconciliation(
-	options: { stateRoot?: string; sessionId?: string; store?: SdkOnlyReconciliationStore } = {},
+	options: {
+		stateRoot?: string;
+		sessionId?: string;
+		store?: SdkOnlyReconciliationStore;
+		onDeadlineRecoveryCheckpointForTests?: (checkpoint: SdkOnlyDeadlineRecoveryCheckpoint) => void;
+		onPersistenceInstrumentationForTests?: (event: PersistenceInstrumentationEvent) => void;
+	} = {},
 ): InvocationReconciliation {
 	const ACTIVE_CAPACITY = 256;
 	const TERMINAL_CAPACITY = 512;
@@ -1063,6 +1142,17 @@ export function createInvocationReconciliation(
 		}
 	>();
 	const pendingTerminalVisibility = new Map<string, { visibleRecord: InvocationRecord; writes: number }>();
+	const recordDeadlineRecoveryCheckpoint = (
+		stage: SdkOnlyDeadlineRecoveryCheckpoint["stage"],
+		correlation: InvocationCorrelation,
+		details: Omit<SdkOnlyDeadlineRecoveryCheckpoint, "at" | "correlation" | "stage"> = {},
+	): void => {
+		try {
+			options.onDeadlineRecoveryCheckpointForTests?.({ at: Date.now(), stage, correlation, ...details });
+		} catch {
+			// A test observer must never participate in durable reconciliation.
+		}
+	};
 	const retainPendingTerminalVisibility = (recordKey: string, visibleRecord: InvocationRecord): (() => void) => {
 		const existing = pendingTerminalVisibility.get(recordKey);
 		if (existing) existing.writes += 1;
@@ -1079,36 +1169,120 @@ export function createInvocationReconciliation(
 	};
 	const persist = async (): Promise<void> => {
 		const run = async (): Promise<void> => {
+			try {
+				options.onPersistenceInstrumentationForTests?.({ at: Date.now(), phase: "enqueued" });
+			} catch {
+				// A test observer must never participate in durable reconciliation.
+			}
+			try {
+				options.onPersistenceInstrumentationForTests?.({ at: Date.now(), phase: "started" });
+			} catch {
+				// Ignore observer errors.
+			}
 			// Construct the candidate only when this serialized write starts. A
 			// pre-await full snapshot lets a later agent_start/agent_end transition
 			// be overwritten on disk by an older queued write even though the live
 			// map has already converged.
 			const snapshot = [...records.values()].map(record => ({ ...record }));
 			if (store) {
-				await store.transact(current => [
-					...current.filter(record => record.kind !== "prompt" && record.kind !== "skill"),
-					...snapshot.map(record => ({ ...record })),
-				]);
+				const promiseId = `transact-${crypto.randomUUID().slice(0, 8)}`;
+				const lockWaitStart = Date.now();
+				try {
+					options.onPersistenceInstrumentationForTests?.({
+						at: lockWaitStart,
+						phase: "started",
+						operation: "store.transact",
+						detail: `promise=${promiseId} awaiting-lock`,
+					});
+				} catch {}
+				const lockAcquiredTime = Date.now();
+				try {
+					await store.transact(current => [
+						...current.filter(record => record.kind !== "prompt" && record.kind !== "skill"),
+						...snapshot.map(record => ({ ...record })),
+					]);
+				} catch (error) {
+					try {
+						options.onPersistenceInstrumentationForTests?.({
+							at: Date.now(),
+							phase: "failed",
+							operation: "store.transact",
+							detail: `promise=${promiseId} lock-wait=${Date.now() - lockWaitStart}ms`,
+							error: error instanceof Error ? error.message : String(error),
+						});
+					} catch {}
+					throw error;
+				}
+				try {
+					options.onPersistenceInstrumentationForTests?.({
+						at: Date.now(),
+						phase: "completed",
+						operation: "store.transact",
+						detail: `promise=${promiseId} lock-acquire=${lockAcquiredTime - lockWaitStart}ms`,
+					});
+				} catch {}
 				return;
 			}
 			if (!reconciliationFile) return;
 			const directory = path.dirname(reconciliationFile);
 			const temporary = `${reconciliationFile}.${process.pid}.${crypto.randomUUID()}.tmp`;
+			try {
+				options.onPersistenceInstrumentationForTests?.({ at: Date.now(), phase: "started", substep: "mkdir" });
+			} catch {}
 			await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+			try {
+				options.onPersistenceInstrumentationForTests?.({ at: Date.now(), phase: "completed", substep: "mkdir" });
+			} catch {}
+			try {
+				options.onPersistenceInstrumentationForTests?.({ at: Date.now(), phase: "started", substep: "writeFile" });
+			} catch {}
 			await fs.writeFile(
 				temporary,
 				JSON.stringify({ version: 1, sessionId: options.sessionId, records: [...snapshot] }),
 				{ encoding: "utf8", mode: 0o600 },
 			);
+			try {
+				options.onPersistenceInstrumentationForTests?.({
+					at: Date.now(),
+					phase: "completed",
+					substep: "writeFile",
+				});
+			} catch {}
+			try {
+				options.onPersistenceInstrumentationForTests?.({ at: Date.now(), phase: "started", substep: "chmod" });
+			} catch {}
 			await fs.chmod(temporary, 0o600);
+			try {
+				options.onPersistenceInstrumentationForTests?.({ at: Date.now(), phase: "completed", substep: "chmod" });
+			} catch {}
+			try {
+				options.onPersistenceInstrumentationForTests?.({ at: Date.now(), phase: "started", substep: "rename" });
+			} catch {}
 			await fs.rename(temporary, reconciliationFile);
+			try {
+				options.onPersistenceInstrumentationForTests?.({ at: Date.now(), phase: "completed", substep: "rename" });
+			} catch {}
 		};
 		const pending = persistenceChain.then(run, run);
 		persistenceChain = pending.then(
 			() => undefined,
 			() => undefined,
 		);
-		await pending;
+		try {
+			await pending;
+			try {
+				options.onPersistenceInstrumentationForTests?.({ at: Date.now(), phase: "completed" });
+			} catch {}
+		} catch (error) {
+			try {
+				options.onPersistenceInstrumentationForTests?.({
+					at: Date.now(),
+					phase: "failed",
+					error: error instanceof Error ? error.message : String(error),
+				});
+			} catch {}
+			throw error;
+		}
 	};
 	// Retention contract (#4547): terminal records are never age-evicted; only
 	// the per-kind oldest-terminal-first capacity trim removes them, so a
@@ -1257,7 +1431,22 @@ export function createInvocationReconciliation(
 			let record = records.get(recordKey);
 			if (!record) return;
 			const pending = pendingFinalizations.get(recordKey);
+			const isPromptEnd = kind === "prompt" && frame.type === "agent_end";
+			if (isPromptEnd)
+				recordDeadlineRecoveryCheckpoint("note-transition-start", correlation, {
+					recordStatus: record.status,
+					recordRevision: record.revision,
+					recordTerminalAt: record.terminalAt,
+					pendingFinalization: pending?.finalizedRecord === record,
+				});
 			if (pending?.finalizedRecord === record) {
+				if (isPromptEnd)
+					recordDeadlineRecoveryCheckpoint("note-transition-awaiting-finalization", correlation, {
+						recordStatus: record.status,
+						recordRevision: record.revision,
+						recordTerminalAt: record.terminalAt,
+						pendingFinalization: true,
+					});
 				const upgrade = Promise.withResolvers<void>();
 				pending.upgrades.add(upgrade);
 				let upgradeError: unknown;
@@ -1269,6 +1458,13 @@ export function createInvocationReconciliation(
 						// so a real lifecycle event is never swallowed.
 					}
 					const current = records.get(recordKey);
+					if (isPromptEnd)
+						recordDeadlineRecoveryCheckpoint("note-transition-finalization-ready", correlation, {
+							recordStatus: current?.status,
+							recordRevision: current?.revision,
+							recordTerminalAt: current?.terminalAt,
+							pendingFinalization: pendingFinalizations.get(recordKey) === pending,
+						});
 					const incomingOutcome = frame.type === "agent_end" ? canonicalTerminalOutcome(frame.outcome) : undefined;
 					const providerFailure =
 						current?.error !== undefined && current.error.code !== "prompt_deadline_exceeded";
@@ -1650,10 +1846,31 @@ export function createInvocationReconciliation(
 				record.terminalAt === undefined && next.terminalAt !== undefined
 					? retainPendingTerminalVisibility(recordKey, record)
 					: undefined;
+			if (isPromptEnd)
+				recordDeadlineRecoveryCheckpoint("note-transition-before-persist", correlation, {
+					recordStatus: next.status,
+					recordRevision: next.revision,
+					recordTerminalAt: next.terminalAt,
+					pendingFinalization: pendingFinalizations.has(recordKey),
+				});
 			records.set(recordKey, next);
 			try {
 				await persist();
+				if (isPromptEnd)
+					recordDeadlineRecoveryCheckpoint("note-transition-persisted", correlation, {
+						recordStatus: next.status,
+						recordRevision: next.revision,
+						recordTerminalAt: next.terminalAt,
+						pendingFinalization: pendingFinalizations.has(recordKey),
+					});
 			} catch (error) {
+				if (isPromptEnd)
+					recordDeadlineRecoveryCheckpoint("note-transition-persist-failed", correlation, {
+						recordStatus: next.status,
+						recordRevision: next.revision,
+						recordTerminalAt: next.terminalAt,
+						pendingFinalization: pendingFinalizations.has(recordKey),
+					});
 				if (records.get(recordKey) === next) records.set(recordKey, record);
 				throw error;
 			} finally {
@@ -2027,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 };
@@ -2110,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>,
@@ -2331,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 =
@@ -2454,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() : [];
@@ -2532,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({
@@ -2918,6 +3144,7 @@ function createControlSurface(
 	) => void,
 	armPromptDeadline: (correlation: InvocationCorrelation) => void,
 	steerReconciliation: KindAwareReconciliation,
+	imageUploads: PromptImageUploadStore | undefined,
 	onPromotedTurn?: (
 		kind: InvocationKind,
 		correlation: InvocationCorrelation,
@@ -2945,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 [];
@@ -2966,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: (
@@ -2976,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));
@@ -2986,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;
 	};
@@ -3113,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
@@ -3126,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",
@@ -3162,6 +3408,7 @@ function createControlSurface(
 		};
 		let accepted = false;
 		let settled = false;
+		let submission: Promise<unknown> | undefined;
 		const cancelPreflight = () => {
 			preflightController.abort();
 			if (settled) return;
@@ -3221,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;
@@ -3248,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";
@@ -3281,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
@@ -3296,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
@@ -3365,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).
@@ -3487,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;
@@ -4405,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 });
@@ -4681,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),
 	};
 }
@@ -4831,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()];
@@ -5361,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];
@@ -5478,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);
@@ -5987,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
@@ -6408,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");
@@ -6419,16 +6820,38 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			(typeof ctx.sessionManager.getSessionFile === "function" ? ctx.sessionManager.getSessionFile() : undefined) ??
 			resolveReconciliationSessionFile(undefined, stateRoot, sessionId);
 		const sessionIdentity = `${sessionId}\u0000${sessionFile}`;
+		const reconciliationInstrumentation = options.terminalAbortSeams?.onPersistenceInstrumentationForTests
+			? (event: ReconciliationStoreInstrumentationEvent) => {
+					try {
+						options.terminalAbortSeams?.onPersistenceInstrumentationForTests?.(event as never);
+					} catch {}
+				}
+			: undefined;
 		const reconciliationStore =
 			options.terminalAbortSeams?.getReconciliationStore?.() ??
-			createReconciliationStore({ sessionFile, sessionId });
-		const reconciliation = createInvocationReconciliation({ store: reconciliationStore });
+			createReconciliationStore({
+				sessionFile,
+				sessionId,
+				onInstrumentationForTests: reconciliationInstrumentation,
+			});
+		const reconciliation = createInvocationReconciliation({
+			store: reconciliationStore,
+			onDeadlineRecoveryCheckpointForTests: options.terminalAbortSeams?.onDeadlineRecoveryCheckpointForTests,
+			onPersistenceInstrumentationForTests: options.terminalAbortSeams?.onPersistenceInstrumentationForTests,
+		});
 		await reconciliation.hydrate();
 		const steerReconciliation = createKindAwareReconciliation({
 			store: reconciliationStore as never,
 			ownedKinds: ["steer"],
 		});
 		await steerReconciliation.hydrateFromStore();
+		const recordDeadlineRecoveryCheckpoint = (checkpoint: Omit<SdkOnlyDeadlineRecoveryCheckpoint, "at">): void => {
+			try {
+				options.terminalAbortSeams?.onDeadlineRecoveryCheckpointForTests?.({ ...checkpoint, at: Date.now() });
+			} catch {
+				// A test observer must never participate in deadline correctness.
+			}
+		};
 		const deadlineManager = new PromptDeadlineManager({
 			reconciliation,
 			getLeaseMs: () => resolveSdkPromptDeadlineMs(options.settings?.get("sdk.promptDeadlineMs" as never)),
@@ -6448,6 +6871,9 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				const seams = options.terminalAbortSeams;
 				const handle = seams?.getActivePromptHandle();
 				const epoch = seams?.getTerminalTurnEpoch();
+				// Capture lifecycle ownership independently of settlement proof. Without
+				// a tool-set observer the later terminalization hook still fails closed,
+				// but a matching real end must remain private and recoverable meanwhile.
 				if (!seams || !handle || epoch === undefined) return;
 				const existing = deadlineTerminalizationObservations.get(key);
 				if (existing) return () => cleanupDeadlineTerminalizationObservation(key, existing);
@@ -6495,8 +6921,36 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				const observation = deadlineTerminalizationObservations.get(target);
 				const seams = options.terminalAbortSeams;
 				const pendingToolExecutions = seams?.pendingToolExecutions;
-				if (!observation || !seams || !pendingToolExecutions) return "uncertain";
-				const pendingTools = () => pendingToolExecutions(observation.handle);
+				recordDeadlineRecoveryCheckpoint({
+					stage: "terminalization-start",
+					correlation,
+					eventCaptured: observation?.eventCaptured,
+					eventPrepared: observation?.eventPrepared,
+					terminalCommitted: observation?.terminalCommitted,
+				});
+				let pendingToolCount: number | undefined;
+				const finish = (result: PromptDeadlineTerminalization, reason: string): PromptDeadlineTerminalization => {
+					recordDeadlineRecoveryCheckpoint({
+						stage: "terminalization-result",
+						correlation,
+						result,
+						reason,
+						eventCaptured: observation?.eventCaptured,
+						eventPrepared: observation?.eventPrepared,
+						terminalCommitted: observation?.terminalCommitted,
+						pendingToolCount,
+					});
+					// Notify deadline manager about termination result to adjust retry strategy
+					deadlineManager.notifyTerminationResult(correlation, result, reason);
+					return result;
+				};
+				if (!observation || !seams || !pendingToolExecutions)
+					return finish("uncertain", "missing-observation-or-tool-observer");
+				const pendingTools = () => {
+					const pending = pendingToolExecutions(observation.handle);
+					pendingToolCount = pending.length;
+					return pending;
+				};
 				const awaitEventPreparation = async (): Promise<boolean> => {
 					if (observation.eventPrepared) return true;
 					const captured = await Promise.race([
@@ -6507,7 +6961,15 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				};
 				if (observation.eventCaptured) {
 					const prepared = await awaitEventPreparation();
-					return prepared && pendingTools().length === 0 ? "settled" : "uncertain";
+					pendingToolCount = pendingTools().length;
+					return finish(
+						prepared && pendingToolCount === 0 ? "settled" : "uncertain",
+						!prepared
+							? "captured-event-not-prepared"
+							: pendingToolCount > 0
+								? "tools-still-pending"
+								: "captured-event-and-tools-settled",
+					);
 				}
 
 				if (!observation.eventCaptured) {
@@ -6521,13 +6983,13 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 							entry => lifecycleCorrelationKey(entry.correlation) === target,
 						)
 					)
-						return "uncertain";
+						return finish("uncertain", "lifecycle-batch-no-longer-owns-correlation");
 					if (
 						!isCurrent() ||
 						seams.getActivePromptHandle() !== observation.handle ||
 						seams.getTerminalTurnEpoch() !== observation.epoch
 					)
-						return "uncertain";
+						return finish("uncertain", "lease-or-active-run-mismatch");
 				}
 				await waitForToolCallBoundary({
 					pending: pendingTools,
@@ -6536,14 +6998,22 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				});
 				if (observation.eventCaptured) {
 					const prepared = await awaitEventPreparation();
-					return prepared && pendingTools().length === 0 ? "settled" : "uncertain";
+					pendingToolCount = pendingTools().length;
+					return finish(
+						prepared && pendingToolCount === 0 ? "settled" : "uncertain",
+						!prepared
+							? "captured-event-not-prepared"
+							: pendingToolCount > 0
+								? "tools-still-pending"
+								: "captured-event-and-tools-settled",
+					);
 				}
 				if (
 					!isCurrent() ||
 					seams.getActivePromptHandle() !== observation.handle ||
 					seams.getTerminalTurnEpoch() !== observation.epoch
 				)
-					return "uncertain";
+					return finish("uncertain", "lease-or-active-run-mismatch-after-tool-boundary");
 
 				let steeringSnapshotToken: number | undefined;
 				let proof: { status: string; terminalScope?: unknown } | undefined;
@@ -6560,7 +7030,15 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					});
 					if (proof.status !== "settled") {
 						const prepared = await awaitEventPreparation();
-						return prepared && pendingTools().length === 0 ? "settled" : "uncertain";
+						pendingToolCount = pendingTools().length;
+						return finish(
+							prepared && pendingToolCount === 0 ? "settled" : "uncertain",
+							!prepared
+								? "abort-proof-not-settled-and-event-not-prepared"
+								: pendingToolCount > 0
+									? "tools-still-pending"
+									: "captured-event-and-tools-settled",
+						);
 					}
 					const terminalScope = proof.terminalScope as
 						| { abortedAttemptEpoch?: unknown; lineageIdHash?: unknown }
@@ -6570,17 +7048,26 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 						typeof terminalScope.lineageIdHash !== "string" ||
 						isOwnedAttemptRegistrationIncomplete(terminalScope.lineageIdHash, observation.epoch)
 					)
-						return "uncertain";
+						return finish("uncertain", "terminal-scope-mismatch");
 					const exactJobs = findOwnedRegistrationsForTurn(terminalScope.lineageIdHash, observation.epoch);
 					if (exactJobs.length > 0) {
 						const endpointId = exactJobs[0]?.endpointId;
 						const manager = AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance();
-						if (!manager || (await settleOwnedWork(manager, exactJobs, 500)) !== "stopped") return "uncertain";
+						if (!manager || (await settleOwnedWork(manager, exactJobs, 500)) !== "stopped")
+							return finish("uncertain", "owned-work-not-stopped");
 					}
 					const prepared = await awaitEventPreparation();
-					return prepared && pendingTools().length === 0 ? "settled" : "uncertain";
+					pendingToolCount = pendingTools().length;
+					return finish(
+						prepared && pendingToolCount === 0 ? "settled" : "uncertain",
+						!prepared
+							? "captured-event-not-prepared"
+							: pendingToolCount > 0
+								? "tools-still-pending"
+								: "captured-event-and-tools-settled",
+					);
 				} catch {
-					return "uncertain";
+					return finish("uncertain", "terminal-abort-error");
 				} finally {
 					if (steeringSnapshotToken !== undefined && proof?.status !== "settled")
 						seams.discardTerminalAbortSteeringSnapshot?.(steeringSnapshotToken);
@@ -6592,21 +7079,57 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				const terminalOutcome = observation
 					? deadlineOutcomeAfterAbort(correlation, observation.terminalOutcome, observation.terminalHasActivity)
 					: undefined;
-				if (!observation?.eventCaptured || !observation.eventPrepared || terminalOutcome === undefined)
+				let terminalIsCurrent: boolean | undefined;
+				let pendingToolCount = -1;
+				const recordPublicationResult = (
+					result: SdkOnlyDeadlineRecoveryCheckpoint["result"],
+					reason: string,
+					errorCodeValue?: string,
+				): void => {
+					recordDeadlineRecoveryCheckpoint({
+						stage: "publication-result",
+						correlation,
+						result,
+						reason,
+						eventCaptured: observation?.eventCaptured,
+						eventPrepared: observation?.eventPrepared,
+						terminalCommitted: observation?.terminalCommitted,
+						leaseCurrent: terminalIsCurrent,
+						pendingToolCount,
+						errorCode: errorCodeValue,
+					});
+				};
+				recordDeadlineRecoveryCheckpoint({
+					stage: "publication-start",
+					correlation,
+					eventCaptured: observation?.eventCaptured,
+					eventPrepared: observation?.eventPrepared,
+					terminalCommitted: observation?.terminalCommitted,
+				});
+				if (!observation?.eventCaptured || !observation.eventPrepared || terminalOutcome === undefined) {
+					recordPublicationResult("rejected", "missing-captured-terminal-outcome");
 					return false;
+				}
 				if (!observation.terminalCommitted) {
 					const pendingTools = options.terminalAbortSeams?.pendingToolExecutions;
-					let terminalIsCurrent = false;
-					let pendingToolCount = -1;
 					try {
 						terminalIsCurrent = isCurrent();
 						if (pendingTools) pendingToolCount = pendingTools(observation.handle).length;
-					} catch {
+					} catch (error) {
+						recordPublicationResult("rejected", "publication-precheck-threw", errorCode(error));
+						return false;
+					}
+					if (!terminalIsCurrent || !pendingTools || pendingToolCount > 0) {
+						recordPublicationResult("rejected", "publication-precheck-rejected");
 						return false;
 					}
-					if (!terminalIsCurrent || !pendingTools || pendingToolCount > 0) return false;
 					try {
-						if (!isCurrent() || pendingTools(observation.handle).length > 0) return false;
+						terminalIsCurrent = isCurrent();
+						pendingToolCount = pendingTools(observation.handle).length;
+						if (!terminalIsCurrent || pendingToolCount > 0) {
+							recordPublicationResult("rejected", "publication-recheck-rejected");
+							return false;
+						}
 						// Commit the authoritative Q26 result before exposing its terminal
 						// boundary; a crash between publication and this write would strand
 						// restart recovery with only a hidden pending claim.
@@ -6619,40 +7142,39 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 						observation.terminalOutcome = terminalOutcome;
 						observation.terminalCommitted = true;
 						observation.clearUnrecordedFailure?.();
-					} catch {
+					} catch (error) {
+						recordPublicationResult("rejected", "terminal-transition-persist-failed", errorCode(error));
 						return false;
 					}
 				}
 				const published = publishDeadlineTerminalBoundary(observation, correlation, terminalOutcome);
+				recordPublicationResult(published ? "published" : "not-published", "terminal-boundary-result");
 				return { outcome: terminalOutcome, published } satisfies PromptDeadlinePublicationResult;
 			},
 			// 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, {
-					agentDir: options.settings?.getAgentDir(),
-					explicitOptIn,
-					isCurrent,
-					signal,
-				});
+				// Project `.gjc` files are not an opt-in. The shared helper reads the
+				// user/global layer and runtime overrides only (#5583).
+				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) return;
-				removeLifecycleReferences(owner, correlation);
-				maybeRetireLifecycleOwner(owner);
+				if (owner) {
+					removeLifecycleReferences(owner, correlation);
+					maybeRetireLifecycleOwner(owner);
+				}
+				recordDeadlineRecoveryCheckpoint({
+					stage: "deadline-recovery-retired",
+					correlation,
+					terminalCommitted: true,
+				});
 			},
 		});
 		const pending: Array<{
@@ -6706,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),
@@ -6836,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.
@@ -6854,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,
@@ -6890,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)
@@ -6946,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
@@ -7106,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") {
@@ -7174,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
@@ -7624,6 +8208,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		} catch (error) {
 			runtimeOwner.quiesceInput();
 			runtimeOwner.fenceGateResolutions();
+			imageUploads?.close();
 			active = undefined;
 			let queueCancellationFailure: unknown;
 			try {
@@ -7682,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],
@@ -7690,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();
@@ -7763,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