@gajae-code/coding-agent 0.18.11 → 0.19.0

package/src/sdk/host/surface-policy.ts

@@ -80,6 +80,7 @@ export interface SdkSurfacePolicy {
 export interface SdkSurfacePolicyOptions {
 	bindings: Iterable<string>;
 	workflowGateAvailable: boolean;
+	imageUploadsAvailable?: boolean;
 	isBindingInstalled?: (binding: string) => boolean;
 }
 
@@ -96,6 +97,7 @@ export function createSdkSurfacePolicy(options: SdkSurfacePolicyOptions): SdkSur
 					operation.kind === kind &&
 					!BROKER_LIFECYCLE_CONTROL_OPERATIONS.has(operation.sdkId) &&
 					!UNINSTALLED_CONTROL_OPERATIONS.has(operation.sdkId) &&
+					(!operation.sdkId.startsWith("turn.image.") || options.imageUploadsAvailable === true) &&
 					(!WORKFLOW_GATE_CONTROL_OPERATIONS.has(operation.sdkId) || options.workflowGateAvailable) &&
 					(!required[operation.sdkId] || hasBinding(required[operation.sdkId]!)),
 			).map(operation => operation.sdkId),
@@ -129,11 +131,13 @@ export function createSdkCapabilities(
 export function createSdkSurfacePolicyForContext(
 	ctx: ExtensionContext,
 	workflowGateAvailable = false,
+	imageUploadsAvailable = false,
 ): SdkSurfacePolicy {
 	const bindings = ctx.sdkBindings?.() ?? [];
 	return createSdkSurfacePolicy({
 		bindings,
 		workflowGateAvailable,
+		imageUploadsAvailable,
 		isBindingInstalled: binding => typeof (ctx as unknown as Record<string, unknown>)[binding] === "function",
 	});
 }

package/src/sdk/host/websocket-transport.lifecycle.test.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { SdkClient } from "../client/client";
+import { SESSION_HOST_OBSERVER_CAPABILITY, TURN_STREAM_CAPABILITY } from "./host";
 import { SessionSdkSessionRuntime, type SessionSdkTransport } from "./session-runtime";
 import { createSdkWebSocketTransport, type SdkWebSocketTransportDependencies } from "./websocket-transport";
 
@@ -29,6 +30,28 @@ async function probeWebSocketEndpoint(url: string, token: string): Promise<void>
 	}
 }
 
+async function waitForFrame(
+	frames: readonly Record<string, unknown>[],
+	predicate: (frame: Record<string, unknown>) => boolean,
+	label: string,
+): Promise<Record<string, unknown>> {
+	const deadline = Date.now() + 5_000;
+	while (true) {
+		const frame = frames.find(predicate);
+		if (frame) return frame;
+		if (Date.now() >= deadline) throw new Error(`Timed out waiting for ${label}`);
+		await Bun.sleep(5);
+	}
+}
+
+async function waitFor(predicate: () => boolean, label: string): Promise<void> {
+	const deadline = Date.now() + 5_000;
+	while (!predicate()) {
+		if (Date.now() >= deadline) throw new Error(`Timed out waiting for ${label}`);
+		await Bun.sleep(5);
+	}
+}
+
 describe("SDK WebSocket transport lifecycle", () => {
 	test("concurrent start calls share one endpoint and one server", async () => {
 		const stateRoot = await tempStateRoot();
@@ -193,7 +216,72 @@ describe("SDK WebSocket transport lifecycle", () => {
 			await fs.rm(stateRoot, { recursive: true, force: true });
 		}
 	});
-	test("event replay capability claims cannot authorize gated replay", async () => {
+	test("loopback replay preserves replay-first, split, and subset capability negotiation", async () => {
+		const stateRoot = await tempStateRoot();
+		const transport = await createSdkWebSocketTransport({
+			sessionId: "loopback-split-capabilities",
+			stateRoot,
+			token: "token",
+		});
+		const runtime = new SessionSdkSessionRuntime({ transport });
+		const frames: Record<string, unknown>[] = [];
+		let socket: WebSocket | undefined;
+		const required = [TURN_STREAM_CAPABILITY, SESSION_HOST_OBSERVER_CAPABILITY];
+		try {
+			const endpoint = await runtime.start();
+			socket = new WebSocket(`${endpoint.url}?token=token`);
+			socket.addEventListener("message", event => {
+				frames.push(JSON.parse(String((event as MessageEvent).data)) as Record<string, unknown>);
+			});
+			await waitForFrame(frames, frame => frame.type === "hello", "server hello");
+			socket.send(
+				JSON.stringify({
+					type: "event_replay",
+					id: "replay-before-hello",
+					sinceSeq: 0,
+					capabilities: [],
+				}),
+			);
+			await waitForFrame(
+				frames,
+				frame => frame.type === "event_replay_result" && frame.id === "replay-before-hello",
+				"replay before hello",
+			);
+			socket.send(JSON.stringify({ type: "hello", protocolVersion: 3, capabilities: [TURN_STREAM_CAPABILITY] }));
+			await waitFor(
+				() => runtime.connectionIdsWithCapabilities([TURN_STREAM_CAPABILITY]).length === 1,
+				"hello after replay",
+			);
+
+			const replayIds = ["observer-addition", "observer-subset", "observer-empty"];
+			for (const [index, capabilities] of [
+				[SESSION_HOST_OBSERVER_CAPABILITY],
+				[SESSION_HOST_OBSERVER_CAPABILITY],
+				[],
+			].entries()) {
+				const id = replayIds[index]!;
+				socket.send(JSON.stringify({ type: "event_replay", id, sinceSeq: 0, capabilities }));
+				await waitForFrame(frames, frame => frame.type === "event_replay_result" && frame.id === id, id);
+				expect(runtime.connectionIdsWithCapabilities(required)).toHaveLength(1);
+			}
+
+			runtime.sendFrameToCapabilities(required, {
+				type: "event",
+				kind: "tool_activity",
+				payload: { phase: "started" },
+			});
+			await waitForFrame(
+				frames,
+				frame => frame.type === "event" && frame.kind === "tool_activity",
+				"live observer event",
+			);
+		} finally {
+			socket?.close();
+			await runtime.stop().catch(() => undefined);
+			await fs.rm(stateRoot, { recursive: true, force: true });
+		}
+	}, 30_000);
+	test("event replay keeps tool activity gated without tool_activity_v2", async () => {
 		const stateRoot = await tempStateRoot();
 		const transport = await createSdkWebSocketTransport({
 			sessionId: "replay-capability-claim",
@@ -223,7 +311,7 @@ describe("SDK WebSocket transport lifecycle", () => {
 					id: "forged-capability-claim",
 					sinceGeneration: 1,
 					sinceSeq: 0,
-					capabilities: ["tool_activity_v2"],
+					capabilities: [SESSION_HOST_OBSERVER_CAPABILITY],
 				}),
 			);
 			const frame = await replay;

package/src/sdk/host/websocket-transport.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { exactUnlink, type NativeExactFileIdentity } from "@gajae-code/natives";
 import {
+	AWAITING_INPUT_CAPABILITY,
 	canDeliverSdkEvent,
 	SESSION_HOST_OBSERVER_CAPABILITY,
 	TOOL_ACTIVITY_CAPABILITY,
@@ -167,6 +168,9 @@ export async function createSdkWebSocketTransport(
 			if (!socket) throw new Error("SDK connection is no longer available.");
 			socket.send(JSON.stringify(frame));
 		},
+		isConnectionOpen(connectionId) {
+			return sockets.has(connectionId);
+		},
 		start: async () => {
 			if (stopPromise) await stopPromise;
 			if (startPromise) return await startPromise;
@@ -203,6 +207,7 @@ export async function createSdkWebSocketTransport(
 										protocolVersion: 3,
 										connectionId: socket.data.connectionId,
 										capabilities: [
+											AWAITING_INPUT_CAPABILITY,
 											TOOL_ACTIVITY_CAPABILITY,
 											TURN_STREAM_CAPABILITY,
 											SESSION_HOST_OBSERVER_CAPABILITY,
@@ -226,16 +231,23 @@ export async function createSdkWebSocketTransport(
 										);
 										return;
 									}
-									if (
+									const isInitialHello =
 										frame.type === "hello" &&
 										frame.protocolVersion === 3 &&
-										(frame.capabilities === undefined || Array.isArray(frame.capabilities)) &&
-										!helloReceived.has(socket.data.connectionId)
+										!helloReceived.has(socket.data.connectionId);
+									if (
+										(isInitialHello || frame.type === "event_replay") &&
+										(frame.capabilities === undefined ||
+											(Array.isArray(frame.capabilities) &&
+												frame.capabilities.every((value: unknown) => typeof value === "string")))
 									) {
-										const capabilities = Array.isArray(frame.capabilities)
-											? frame.capabilities.filter((value): value is string => typeof value === "string")
-											: [];
-										helloReceived.add(socket.data.connectionId);
+										const capabilities = [
+											...new Set([
+												...(negotiatedCapabilities.get(socket.data.connectionId) ?? []),
+												...((frame.capabilities as string[] | undefined) ?? []),
+											]),
+										];
+										if (isInitialHello) helloReceived.add(socket.data.connectionId);
 										negotiatedCapabilities.set(socket.data.connectionId, new Set(capabilities));
 										capabilitiesHandler?.(socket.data.connectionId, capabilities);
 									}

package/src/sdk/lifecycle/service.ts

@@ -101,6 +101,10 @@ export type SessionCreateTarget = SessionLifecycleCoordinatorTarget & {
 	readonly body?: string;
 	readonly modelPreset?: string;
 	readonly mcpServers?: readonly Record<string, unknown>[];
+	/** Per-session environment for the hosted session; `GJC_*` names are reserved (#6735). */
+	readonly env?: Readonly<Record<string, string>>;
+	/** Inherited broker environment names removed from the hosted session (#6735). */
+	readonly unsetEnv?: readonly string[];
 	readonly worktree?: SessionLifecycleWorktreeTarget;
 	readonly readiness?: "immediate" | "deferred";
 	readonly readinessTimeoutMs?: number;
@@ -115,6 +119,10 @@ export type SessionForkTarget = SessionLifecycleCoordinatorTarget & {
 	readonly body?: string;
 	readonly modelPreset?: string;
 	readonly mcpServers?: readonly Record<string, unknown>[];
+	/** Per-session environment for the hosted session; `GJC_*` names are reserved (#6735). */
+	readonly env?: Readonly<Record<string, string>>;
+	/** Inherited broker environment names removed from the hosted session (#6735). */
+	readonly unsetEnv?: readonly string[];
 	readonly worktree?: SessionLifecycleWorktreeTarget;
 	readonly readinessTimeoutMs?: number;
 };
@@ -128,6 +136,10 @@ export type SessionResumeTarget = SessionLifecycleCoordinatorTarget & {
 	readonly body?: string;
 	readonly modelPreset?: string;
 	readonly mcpServers?: readonly Record<string, unknown>[];
+	/** Per-session environment for the hosted session; `GJC_*` names are reserved (#6735). */
+	readonly env?: Readonly<Record<string, string>>;
+	/** Inherited broker environment names removed from the hosted session (#6735). */
+	readonly unsetEnv?: readonly string[];
 	readonly worktree?: SessionLifecycleWorktreeTarget;
 	readonly readinessTimeoutMs?: number;
 };
@@ -550,7 +562,7 @@ export function validateSessionLifecycleMutationRequest(request: unknown): Sessi
 }
 
 function certaintyForBrokerCode(code: string): SessionLifecycleCertainty {
-	if (code === "terminal_uncertain") return "uncertain";
+	if (code === "terminal_uncertain" || code === "legacy_lifecycle_ambiguous") return "uncertain";
 	if (code === "cleanup_pending") return "cleanup_pending";
 	if (RETRYABLE_BROKER_ERRORS.has(code)) return "retryable";
 	return "terminal";
@@ -686,6 +698,7 @@ const savedSessionScopeDetailCodes = new Set([
 	"migration_busy",
 	"atomic_unavailable",
 	"invalid_request",
+	"permission_denied",
 	"durability_failed",
 	"durability_not_provable",
 	"capacity_exceeded",
@@ -700,6 +713,7 @@ const savedSessionCandidateDetailCodes = new Set([
 	"cwd_not_utf8",
 	"cwd_network_unsupported",
 	"cwd_identity_unavailable",
+	"permission_denied",
 	"cwd_io_error",
 ]);
 

package/src/sdk/prompt-deadline-flush.ts

@@ -44,7 +44,8 @@
  * WHERE it runs. `sdk.flushWorktreeOnDeadline` still defaults to on, but the
  * implicit default applies only in a LINKED worktree (`gitDir !== commonDir`) —
  * what agent/paseo sessions run in, and the #5583 field report. In the user's
- * primary checkout an autosave needs an explicit opt-in.
+ * primary checkout an autosave needs an explicit opt-in from the user/global
+ * config or a runtime override. A project `.gjc` file is not that opt-in.
  */
 
 import * as fsp from "node:fs/promises";
@@ -66,9 +67,10 @@ export interface PromptDeadlineFlushOptions {
 	/** Active session's agent directory, used to keep volatile broker state out of the WIP commit. */
 	readonly agentDir?: string;
 	/**
-	 * Whether the caller resolved `sdk.flushWorktreeOnDeadline` to `true` from a
-	 * value the user actually wrote, rather than from the schema default. Only an
-	 * explicit opt-in may autosave outside a linked worktree.
+	 * Whether the caller resolved `sdk.flushWorktreeOnDeadline` to `true` from the
+	 * user/global config or a runtime override, rather than from the schema
+	 * default or a project `.gjc` file. Only that opt-in may autosave outside a
+	 * linked worktree.
 	 */
 	readonly explicitOptIn?: boolean;
 	/**
@@ -162,6 +164,76 @@ function isLinkedWorktree(repository: git.GitRepository): boolean {
 	return path.resolve(repository.gitDir) !== path.resolve(repository.commonDir);
 }
 
+const DEADLINE_FLUSH_SETTING = "sdk.flushWorktreeOnDeadline";
+
+/**
+ * The settings view both deadline hosts already hold. `get` is the merged value
+ * (global, then project, then runtime override, otherwise the schema default).
+ * `getGlobal` and `getOverride` are the layers a project file cannot write.
+ */
+export interface DeadlineFlushSettings {
+	get(path: typeof DEADLINE_FLUSH_SETTING): unknown;
+	getAgentDir?(): string | undefined;
+	getGlobal?(path: typeof DEADLINE_FLUSH_SETTING): unknown;
+	getOverride?(path: typeof DEADLINE_FLUSH_SETTING): unknown;
+}
+
+/**
+ * True only when the user wrote `sdk.flushWorktreeOnDeadline: true` in a runtime
+ * override or the global config. The schema default and a project `.gjc` file
+ * do not count: `Settings.has()` sees the merged view, so a repo-shipped `true`
+ * would otherwise open the primary-checkout gate.
+ */
+export function explicitDeadlineFlushOptIn(settings: DeadlineFlushSettings | undefined): boolean {
+	if (!settings) return false;
+	if (typeof settings.getOverride === "function") {
+		const override = settings.getOverride(DEADLINE_FLUSH_SETTING);
+		if (override !== undefined) return override === true;
+	}
+	if (typeof settings.getGlobal === "function") return settings.getGlobal(DEADLINE_FLUSH_SETTING) === true;
+	return false;
+}
+
+/**
+ * Whether this deadline must not autosave.
+ *
+ * A runtime override wins, then the user/global value. A project file cannot
+ * cancel either one. A project `false` still opts out when the user has not
+ * written the key.
+ */
+export function deadlineFlushSuppressed(settings: DeadlineFlushSettings | undefined): boolean {
+	if (!settings) return false;
+	if (typeof settings.getOverride === "function") {
+		const override = settings.getOverride(DEADLINE_FLUSH_SETTING);
+		if (override === false) return true;
+		if (override === true) return false;
+	}
+	if (typeof settings.getGlobal === "function") {
+		const globalValue = settings.getGlobal(DEADLINE_FLUSH_SETTING);
+		if (globalValue === false) return true;
+		if (globalValue === true) return false;
+	}
+	return settings.get(DEADLINE_FLUSH_SETTING) === false;
+}
+
+/**
+ * Deadline-host entry for the worktree autosave. Both the session runtime and
+ * the notification bus call this so the opt-in decision cannot drift.
+ */
+export async function autosaveWorktreeOnPromptDeadline(
+	cwd: string,
+	settings: DeadlineFlushSettings | undefined,
+	options?: { readonly isCurrent?: () => boolean; readonly signal?: AbortSignal },
+): Promise<PromptDeadlineFlushResult | undefined> {
+	if (deadlineFlushSuppressed(settings)) return undefined;
+	return flushWorktreeOnPromptDeadline(cwd, {
+		agentDir: settings?.getAgentDir?.(),
+		explicitOptIn: explicitDeadlineFlushOptIn(settings),
+		isCurrent: options?.isCurrent,
+		signal: options?.signal,
+	});
+}
+
 /**
  * Commit any uncommitted work in the worktree owning `cwd`.
  *
@@ -195,7 +267,8 @@ export async function flushWorktreeOnPromptDeadline(
 		if (!explicitOptIn && !isLinkedWorktree(repository)) {
 			logger.debug(
 				`sdk: prompt deadline worktree autosave skipped; ${worktreeRoot} is a primary checkout the session does ` +
-					`not own. Set sdk.flushWorktreeOnDeadline to true to autosave here anyway.`,
+					`not own. Set sdk.flushWorktreeOnDeadline to true in the user config or a runtime override to ` +
+					`autosave here anyway.`,
 			);
 			return undefined;
 		}

package/src/sdk/prompt-deadline-manager.ts

@@ -103,10 +103,18 @@ export class PromptDeadlineManager {
 	readonly #uncertaintyRecoveryPending = new Set<string>();
 	readonly #expiring = new Set<string>();
 	readonly #deadlineAttempts = new Set<string>();
+	/**
+	 * The next deadline came due while `#expire` was still inside an await
+	 * (tool-boundary grace or the bounded flush). The in-flight pass owns the
+	 * single-flight slot, so the timer callback only records the follow-up and
+	 * `#onDeadline` runs it after this pass returns.
+	 */
+	readonly #deadlineFollowUps = new Set<string>();
 	readonly #pendingTerminalTransitions = new Set<string>();
 	readonly #deadlineDeferredTerminalTransitions = new Set<string>();
 	readonly #deadlineTerminalizationConfirmed = new Set<string>();
 	readonly #terminalPublicationPending = new Map<string, SdkPromptTerminalOutcome>();
+	readonly #toolsStillPendingOnLastCheck = new Set<string>();
 	readonly #deadlineStartCleanup = new Map<string, () => void>();
 	readonly #pendingTerminalFailureReasons = new Map<
 		string,
@@ -187,7 +195,11 @@ export class PromptDeadlineManager {
 	}
 
 	/** Run the durability hook under the shared bound; see `runBoundedDeadlineFlush`. */
-	async #runDeadlineFlush(correlation: InvocationCorrelation, lease: PromptDeadlineLease): Promise<void> {
+	async #runDeadlineFlush(
+		correlation: InvocationCorrelation,
+		lease: PromptDeadlineLease,
+		generation: number,
+	): Promise<void> {
 		const hook = this.#onDeadlineExceeded;
 		if (hook === undefined) return;
 		const key = leaseKey(correlation);
@@ -195,7 +207,9 @@ export class PromptDeadlineManager {
 			signal =>
 				hook(correlation, signal, () => {
 					const current = this.#leases.get(key);
-					return current === lease && this.#now() >= promptDeadlineAt(current);
+					return (
+						current === lease && current.generation === generation && this.#now() >= promptDeadlineAt(current)
+					);
 				}),
 			this.#deadlineFlushTimeoutMs,
 		);
@@ -239,12 +253,24 @@ export class PromptDeadlineManager {
 	}
 
 	async #onDeadline(key: string): Promise<void> {
-		if (this.#deadlineAttempts.has(key)) return;
+		if (this.#deadlineAttempts.has(key)) {
+			this.#deadlineFollowUps.add(key);
+			return;
+		}
 		this.#deadlineAttempts.add(key);
 		try {
-			await this.#expire(key);
+			do {
+				this.#deadlineFollowUps.delete(key);
+				await this.#expire(key);
+			} while (this.#deadlineFollowUps.has(key));
 		} finally {
 			this.#deadlineAttempts.delete(key);
+			if (this.#deadlineFollowUps.has(key)) {
+				this.#deadlineFollowUps.delete(key);
+				queueMicrotask(() => {
+					void this.#onDeadline(key);
+				});
+			}
 		}
 	}
 
@@ -385,7 +411,9 @@ export class PromptDeadlineManager {
 			terminalization =
 				(await this.#onDeadlineTerminalization?.(correlation, () => {
 					const current = this.#leases.get(key);
-					return current === lease && this.#now() >= promptDeadlineAt(current);
+					return (
+						current === lease && current.generation === generation && this.#now() >= promptDeadlineAt(current)
+					);
 				})) ?? "settled";
 		} catch {
 			terminalization = "uncertain";
@@ -410,7 +438,7 @@ export class PromptDeadlineManager {
 		// The claim above remains the durable pending marker throughout both
 		// bounded operations, so restart recovery never reports unsaved work as
 		// finished.
-		await this.#runDeadlineFlush(correlation, lease);
+		await this.#runDeadlineFlush(correlation, lease, generation);
 		// Fence again AFTER the flush (#5623 review round 2): progress can land
 		// while the bounded git operation runs and renews the lease.
 		if (this.#backOffIfSuperseded(key, lease, generation)) return;
@@ -532,14 +560,19 @@ export class PromptDeadlineManager {
 	/**
 	 * After an awaited reconciliation call, verify the captured lease is still
 	 * authoritative. Fresh attributable progress during the await advances the
-	 * lease generation and its deadline; when superseded, cancel this expiry
-	 * instance (release the expiration fence, clear any retry budget, and
-	 * reschedule the deadline) and report it so the caller stops. A cleared or
-	 * re-accepted lease is stale by identity too.
+	 * lease generation and its deadline. A tool-boundary wait or a flush can
+	 * outlive that renewed lease, so a generation mismatch is stale even when
+	 * the new deadline is already due — the time check alone would let this
+	 * pass publish with the generation it captured, the publisher would refuse,
+	 * and uncertainty recovery would refuse to re-anchor the same mismatch.
+	 * Cancel this expiry instance (release the expiration fence, clear any
+	 * retry budget, and reschedule the deadline) and report it so the caller
+	 * stops. The follow-up expiry captures the current generation. A cleared
+	 * or re-accepted lease is stale by identity too.
 	 */
-	#backOffIfSuperseded(key: string, lease: PromptDeadlineLease, _generation: number): boolean {
+	#backOffIfSuperseded(key: string, lease: PromptDeadlineLease, generation: number): boolean {
 		const current = this.#leases.get(key);
-		if (current !== lease || this.#now() < promptDeadlineAt(current)) {
+		if (current !== lease || current.generation !== generation || this.#now() < promptDeadlineAt(current)) {
 			this.#expiring.delete(key);
 			this.#expiryRetries.delete(key);
 			if (current) this.#schedule(key);
@@ -578,13 +611,32 @@ export class PromptDeadlineManager {
 		this.clear(correlation);
 	}
 
-	#scheduleTerminalPublicationRetry(key: string): void {
+	#scheduleTerminalPublicationRetry(key: string, delayMs?: number): void {
 		this.#clearTimer(key);
-		const timer = setTimeout(() => void this.#onDeadline(key), UNCERTAINTY_RETRY_DELAY_MS);
+		// Use immediate retry (0ms) if tools were pending on last check;
+		// otherwise use normal retry delay. This allows quick detection when tools drain.
+		const effectiveDelayMs =
+			delayMs ?? (this.#toolsStillPendingOnLastCheck.has(key) ? 0 : UNCERTAINTY_RETRY_DELAY_MS);
+		const timer = setTimeout(() => void this.#onDeadline(key), effectiveDelayMs);
 		(timer as unknown as { unref?: () => void }).unref?.();
 		this.#timers.set(key, timer);
 	}
 
+	/** Notify about termination check results to adjust retry strategy. */
+	notifyTerminationResult(
+		correlation: InvocationCorrelation,
+		_result: PromptDeadlineTerminalization,
+		reason: string,
+	): void {
+		const key = leaseKey(correlation);
+		if (reason.includes("tools-still-pending")) {
+			this.#toolsStillPendingOnLastCheck.add(key);
+		} else {
+			// Tools have settled or are no longer relevant
+			this.#toolsStillPendingOnLastCheck.delete(key);
+		}
+	}
+
 	#retry(key: string): void {
 		const attempts = (this.#expiryRetries.get(key) ?? 0) + 1;
 		this.#expiryRetries.set(key, attempts);
@@ -817,6 +869,7 @@ export class PromptDeadlineManager {
 		this.#terminalPublicationPending.delete(key);
 		this.#pendingTerminalFailureReasons.delete(key);
 		this.#pendingTerminalEvidence.delete(key);
+		this.#toolsStillPendingOnLastCheck.delete(key);
 	}
 
 	clearAll(): void {
@@ -839,6 +892,7 @@ export class PromptDeadlineManager {
 		this.#terminalPublicationPending.clear();
 		this.#pendingTerminalFailureReasons.clear();
 		this.#pendingTerminalEvidence.clear();
+		this.#toolsStillPendingOnLastCheck.clear();
 	}
 
 	/** For tests: current deadline or undefined if no lease. */

package/src/sdk/prompt-status.ts

@@ -40,12 +40,14 @@ export interface TurnPromptImageInput {
 	mimeType?: string;
 }
 
-/** Public input contract for ordered `turn.prompt`. */
-export interface TurnPromptInput {
+/** Public input contract for ordered `turn.prompt`; direct and staged images cannot be mixed. */
+export type TurnPromptInput = {
 	text: string;
-	images?: TurnPromptImageInput[];
 	clientRef?: string;
-}
+} & (
+	| { images?: TurnPromptImageInput[]; stagedImages?: never }
+	| { images?: never; stagedImages: Array<{ id: string }> }
+);
 
 /**
  * Terminal outcome is preserved exactly; active records never age into terminal. An