@gajae-code/coding-agent 0.18.1 → 0.18.6

package/src/sdk/host/control/dispatch.ts

@@ -93,6 +93,7 @@ const IDEMPOTENCY_TTL_MS = 15 * 60 * 1_000;
 const MAX_IDEMPOTENCY_ENTRIES = 256;
 
 const sessionChains = new WeakMap<ControlSurface, Promise<void>>();
+const pendingReplacementBarriers = new WeakMap<ControlSurface, Promise<void>>();
 interface IdempotencyEntry {
 	hash: string;
 	expiresAt: number;
@@ -189,6 +190,19 @@ function invalidInput(message: string): never {
 	throw new TypedControlError("invalid_input", message);
 }
 
+const EXPECTED_SDK_RUN_TOKEN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}:[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+
+function enqueueReplacementBarrier(surface: ControlSurface): () => void {
+	const previous = pendingReplacementBarriers.get(surface) ?? Promise.resolve();
+	const { promise: current, resolve: resolveCurrent } = Promise.withResolvers<void>();
+	const barrier = previous.then(() => current);
+	pendingReplacementBarriers.set(surface, barrier);
+	return () => {
+		resolveCurrent();
+		if (pendingReplacementBarriers.get(surface) === barrier) pendingReplacementBarriers.delete(surface);
+	};
+}
+
 /**
  * C04 `turn.abort` dispatch.
  *
@@ -244,7 +258,11 @@ function invoke(
 		case "turn.prompt":
 			return surface.prompt(text(input), input.images, input.clientRef as string | undefined);
 		case "turn.steer":
-			return surface.steer(text(input), typeof input.clientRef === "string" ? input.clientRef : undefined);
+			return surface.steer(
+				text(input),
+				typeof input.clientRef === "string" ? input.clientRef : undefined,
+				Object.hasOwn(input, "expectedSdkRunToken") ? (input.expectedSdkRunToken as string) : undefined,
+			);
 		case "turn.follow_up":
 			return surface.followUp(text(input));
 		case "turn.abort":
@@ -486,6 +504,15 @@ export function dispatchControl(
 		);
 	if (!isInput(request.input))
 		return Promise.resolve(failure(request.id, "invalid_input", "Control input must be an object."));
+	if (
+		row.sdkId === "turn.steer" &&
+		Object.hasOwn(request.input, "expectedSdkRunToken") &&
+		(typeof request.input.expectedSdkRunToken !== "string" ||
+			!EXPECTED_SDK_RUN_TOKEN_PATTERN.test(request.input.expectedSdkRunToken))
+	)
+		return Promise.resolve(
+			failure(request.id, "invalid_input", "expectedSdkRunToken must be a commandId:turnId pair."),
+		);
 	if (
 		row.sdkId === "turn.abort" &&
 		((brokerAbortFieldPresent && !brokerAbortAuthorized) ||
@@ -538,10 +565,31 @@ export function dispatchControl(
 	const work = () => execute(surface, row, dispatchRequest);
 	if (row.sdkId === "turn.abort_and_prompt") {
 		const cancellable = surface as PreflightCancellableSurface;
-		if (Object.hasOwn(cancellable, "cancelPendingPreflights")) cancellable.cancelPendingPreflights?.();
-		return serialize(surface, work);
+		const releaseBarrier = enqueueReplacementBarrier(surface);
+		try {
+			if (Object.hasOwn(cancellable, "cancelPendingPreflights")) cancellable.cancelPendingPreflights?.();
+			return serialize(surface, async () => {
+				try {
+					return await work();
+				} finally {
+					releaseBarrier();
+				}
+			});
+		} catch (error) {
+			releaseBarrier();
+			throw error;
+		}
 	}
 	if (row.idempotency === "idempotent" && dispatchRequest.idempotencyKey)
 		return idempotent(surface, row, dispatchRequest, work);
-	return row.idempotency === "ordered" && row.sdkId !== "retry.now" ? serialize(surface, work) : work();
+	if (row.sdkId === "turn.steer") {
+		const replacementBarrier = pendingReplacementBarriers.get(surface);
+		return replacementBarrier ? replacementBarrier.then(work) : work();
+	}
+	// Active feedback must reach the worker even while an earlier ordered control
+	// waits for that worker. Correlated steer admission remains deduplicated by
+	// the runtime reconciliation store, independently of this dispatch chain.
+	return row.idempotency === "ordered" && row.sdkId !== "retry.now" && row.sdkId !== "turn.steer"
+		? serialize(surface, work)
+		: work();
 }

package/src/sdk/host/control/operations.ts

@@ -22,7 +22,7 @@ export type ControlInput = Record<string, unknown>;
  */
 export interface ControlSurface {
 	prompt(text: string, images?: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
-	steer(text: string, clientRef?: string): Promise<ControlValue> | ControlValue;
+	steer(text: string, clientRef?: string, expectedSdkRunToken?: string): Promise<ControlValue> | ControlValue;
 	followUp(text: string): Promise<ControlValue> | ControlValue;
 	abort(): Promise<ControlValue> | ControlValue;
 	/** Terminal abort: stop the current root turn (and optionally exact owned work). */

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

@@ -290,7 +290,7 @@ test("session.last_assistant returns the latest projected readable text past non
 	});
 });
 
-test("session.last_assistant returns resource_gone when the projected transcript has no readable assistant text", async () => {
+test("session.last_assistant returns null when the projected transcript has no readable assistant text", async () => {
 	const sessionId = "last-assistant-empty";
 	const ctx = extensionContext(sessionId, "/tmp", {
 		transcript: [
@@ -311,7 +311,7 @@ test("session.last_assistant returns resource_gone when the projected transcript
 		],
 	});
 
-	expect(await queryLastAssistant(ctx, sessionId)).toMatchObject({ ok: false, error: { code: "resource_gone" } });
+	expect(await queryLastAssistant(ctx, sessionId)).toMatchObject({ ok: true, page: { items: [null] } });
 });
 
 test("native prompt reconciliation fails closed for an explicitly empty assistant result", () => {
@@ -4142,6 +4142,7 @@ describe("SessionSdkSessionRuntime", () => {
 interface PreflightHooks {
 	onPreflightAccepted?: () => void;
 	onPreflightAcceptCommit?: () => void | Promise<void>;
+	expectedSdkRunToken?: string;
 }
 
 interface ResponseFrame {
@@ -4482,6 +4483,43 @@ function neverSettlingPromise(): Promise<void> {
 	return Promise.withResolvers<void>().promise;
 }
 
+test("SDK turn.steer preserves its expected run token and propagates a stale-run rejection", async () => {
+	const cwd = await mkdtemp(path.join(os.tmpdir(), "gjc-turn-steer-run-token-"));
+	const staleToken = "ended-command:ended-turn";
+	const clientRef = "stale-steer-ref";
+	const calls: Array<{ content: unknown; deliverAs?: string; expectedSdkRunToken?: string }> = [];
+	let harness: InvocationHarness | undefined;
+	try {
+		harness = await invocationHarness("steer-run-token", cwd, {
+			sendUserMessage: async (content, options) => {
+				calls.push({
+					content,
+					deliverAs: options?.deliverAs,
+					expectedSdkRunToken: options?.expectedSdkRunToken,
+				});
+				if (options?.expectedSdkRunToken === staleToken)
+					throw Object.assign(new Error("The expected SDK run is not active."), { code: "turn_not_active" });
+				return "completed";
+			},
+		});
+
+		const rejected = await harness.control("turn.steer", {
+			text: "stale steer",
+			expectedSdkRunToken: staleToken,
+			clientRef,
+		});
+		expect(rejected).toMatchObject({ ok: false, error: { code: "turn_not_active" } });
+		expect(calls).toEqual([{ content: "stale steer", deliverAs: "steer", expectedSdkRunToken: staleToken }]);
+		expect(await harness.query("turn.steer_status", { clientRef })).toMatchObject({
+			ok: true,
+			result: { status: "rejected" },
+		});
+	} finally {
+		if (harness) await harness.stop();
+		await rm(cwd, { recursive: true, force: true });
+	}
+});
+
 describe("post-acceptance invocation terminalization", () => {
 	test.each([
 		{ status: 402, code: "provider_http_402" },

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

@@ -50,6 +50,12 @@ import { parseThinkingLevel } from "../../thinking";
 import { readEndpointFile } from "../broker/endpoint-authority";
 import { ensureBroker } from "../broker/ensure";
 import { processIncarnation } from "../broker/process-incarnation";
+import { RecoveryBackoffTracker } from "../broker/recovery-backoff";
+import {
+	captureRuntimeImageIdentity,
+	isSdkInternalRuntimeImageReplaced,
+	sdkInternalRuntimeImage,
+} from "../broker/runtime";
 import {
 	type MasterRoleAttestationV2,
 	resolveSessionLocator,
@@ -716,6 +722,15 @@ export interface CreateSdkSessionRuntimeOptions {
 	onFailureDiagnosticKeyCountForTests?: (count: number) => void;
 	/** Test-only observation after a resolved invocation completion is reconciled. */
 	onInvocationCompletionReconciledForTests?: (kind: InvocationKind, correlation: InvocationCorrelation) => void;
+	/** Test hook: provides a function to inject a controlled clock for broker recovery backoff assertions. */
+	setRecoveryBackoffClockForTest?: (inject: (clock: { now(): number }) => void) => void;
+	/** Test hook: inject mock runtime image identity and replacement detection for broker recovery tests. */
+	setRuntimeImageIdentityForTest?: (
+		register: (
+			captureFn: () => Awaited<ReturnType<typeof captureRuntimeImageIdentity>> | undefined,
+			isReplacedFn: () => Promise<boolean>,
+		) => void,
+	) => void;
 }
 
 function unavailable(operation: string): () => never {
@@ -2044,7 +2059,7 @@ function createQuerySurface(
 					: entry.content?.flatMap(block => (block.type === "text" ? [block.text] : [])).join("\n");
 			if (text !== undefined && text.trim().length > 0) return text;
 		}
-		return undefined;
+		return null;
 	};
 	const getProfileCredentialSessionId = () => ctx.credentialSessionId ?? id;
 	const profileSettings = (options.settings ?? ctx.settings) as Pick<Settings, "get"> | undefined;
@@ -2899,6 +2914,7 @@ function createControlSurface(
 	};
 	type InternalSendOptions = NonNullable<Parameters<ExtensionAPI["sendUserMessage"]>[1]> & {
 		sdkRunCapability?: SdkRunCapability;
+		expectedSdkRunToken?: string;
 	};
 	type InternalSdkApi = Omit<ExtensionAPI, "sendUserMessage"> & {
 		sendUserMessage: (
@@ -4228,23 +4244,30 @@ function createControlSurface(
 				),
 			);
 		},
-		steer: async (text, clientRef) => {
+		steer: async (text, clientRef, expectedSdkRunToken) => {
 			const invalid = validateRequiredPromptText("turn.steer", { text });
 			if (invalid) throw Object.assign(new Error(invalid.message), { code: invalid.code });
 			const retainedClientRef = normalizeClientRef(clientRef);
+			const sendSteer = () =>
+				sendSdkUserMessage(text, {
+					deliverAs: "steer",
+					...(expectedSdkRunToken === undefined ? {} : { expectedSdkRunToken }),
+				});
 			if (retainedClientRef === undefined) {
 				const correlation = newCorrelation();
-				await sendSdkUserMessage(text, { deliverAs: "steer" });
+				await sendSteer();
 				return { accepted: true, ...correlation };
 			}
 			const durable = steerReconciliation;
 			const reservation = await durable.reserveSteer(retainedClientRef, text);
 			if (reservation.replay) return { accepted: reservation.result.status === "accepted", ...reservation.result };
 			try {
-				await sendSdkUserMessage(text, { deliverAs: "steer" });
+				await sendSteer();
 				return { accepted: true, ...(await durable.settleSteer(retainedClientRef, "accepted")) };
 			} catch (error) {
-				return { accepted: false, ...(await durable.settleSteer(retainedClientRef, "rejected", error)) };
+				const settled = await durable.settleSteer(retainedClientRef, "rejected", error);
+				if (expectedSdkRunToken !== undefined) throw error;
+				return { accepted: false, ...settled };
 			}
 		},
 		followUp: async text => {
@@ -7013,6 +7036,43 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		let brokerRegistered = false;
 		let brokerRegistrationInFlight: Promise<void> | undefined;
 		let brokerRecoveryStopped = false;
+		let brokerRecoveryRestartRequired = false;
+		const brokerRecoveryBackoff = new RecoveryBackoffTracker();
+		if (options.setRecoveryBackoffClockForTest) {
+			options.setRecoveryBackoffClockForTest((clock: { now(): number }) =>
+				brokerRecoveryBackoff.setClockForTest(clock),
+			);
+		}
+		// Capture runtime image identity at startup to detect replacements
+		let startupRuntimeImageIdentity: Awaited<ReturnType<typeof captureRuntimeImageIdentity>> | undefined;
+		let captureStartupRuntimeImageForTest:
+			| (() => Awaited<ReturnType<typeof captureRuntimeImageIdentity>> | undefined)
+			| undefined;
+		let isRuntimeImageReplacedForTest: (() => Promise<boolean>) | undefined;
+		if (options.setRuntimeImageIdentityForTest) {
+			options.setRuntimeImageIdentityForTest(
+				(
+					captureFn: () => Awaited<ReturnType<typeof captureRuntimeImageIdentity>> | undefined,
+					isReplacedFn: () => Promise<boolean>,
+				) => {
+					captureStartupRuntimeImageForTest = captureFn;
+					isRuntimeImageReplacedForTest = isReplacedFn;
+				},
+			);
+		}
+		const captureStartupRuntimeImage = async (): Promise<void> => {
+			if (options.setRuntimeImageIdentityForTest) {
+				// Test mode: use injected identity
+				startupRuntimeImageIdentity = captureStartupRuntimeImageForTest?.();
+			} else {
+				// Production mode: capture real runtime image
+				const runtimeImage = sdkInternalRuntimeImage();
+				if (runtimeImage) {
+					startupRuntimeImageIdentity = await captureRuntimeImageIdentity(runtimeImage);
+				}
+			}
+		};
+		const startupImageCapture = captureStartupRuntimeImage();
 		const registerBroker = async (): Promise<void> => {
 			if (brokerRegistered) return;
 			if (brokerRegistrationInFlight !== undefined) {
@@ -7143,17 +7203,58 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		let brokerRecoveryTimer: NodeJS.Timeout | undefined;
 		let brokerRecoveryInFlight: Promise<void> | undefined;
 		const runBrokerRecovery = async (): Promise<void> => {
-			if (brokerRecoveryStopped || brokerRecoveryInFlight !== undefined) return;
+			if (brokerRecoveryStopped || brokerRecoveryInFlight !== undefined || brokerRecoveryRestartRequired) return;
+			// Checked synchronously so an interval tick cannot start an attempt the backoff forbids.
+			if (!brokerRecoveryBackoff.canAttemptRecovery(options.agentDir)) return;
+
+			// The single-flight slot is claimed before the first await: the interval does not wait
+			// for prior callbacks, so a slow runtime-image probe must not let a second tick through
+			// to ensure the broker and record the same failure twice.
 			const recovery = (async (): Promise<void> => {
+				// A replaced runtime image cannot launch a broker; restarting the session is the only fix.
+				const imageReplaced = await (isRuntimeImageReplacedForTest
+					? isRuntimeImageReplacedForTest()
+					: isSdkInternalRuntimeImageReplaced(startupRuntimeImageIdentity).catch(() => false));
+				if (imageReplaced) {
+					brokerRecoveryRestartRequired = true;
+					stopBrokerRecovery();
+					logger.warn("sdk broker recovery requires session restart", {
+						reason: "runtime_image_replaced",
+					});
+					return;
+				}
 				if (brokerRecoveryStopped) return;
 				if (brokerRegistered) await (options.ensureBrokerImpl ?? ensureBroker)({ agentDir: options.agentDir });
-				else await registerBroker();
+				else {
+					// Optional registration logs and resolves on failure; recovery must still count it
+					// as a failed attempt so the backoff holds instead of resetting every tick.
+					await registerBroker();
+					if (!brokerRegistered && !brokerRecoveryStopped)
+						throw Object.assign(new Error("SDK broker registration did not complete."), {
+							code: "registration_incomplete",
+						});
+				}
 			})();
 			brokerRecoveryInFlight = recovery;
 			try {
 				await recovery;
+				if (brokerRecoveryRestartRequired || brokerRecoveryStopped) return;
+				brokerRecoveryBackoff.recordSuccess(options.agentDir);
 			} catch (error) {
-				logger.warn("sdk broker recovery unavailable", { code: brokerDiagnosticCode(error) });
+				const shouldContinue = brokerRecoveryBackoff.recordFailure(options.agentDir);
+				if (!shouldContinue) {
+					// Max recovery attempts reached; mark that restart is required.
+					brokerRecoveryRestartRequired = true;
+					stopBrokerRecovery();
+					logger.warn("sdk broker recovery max attempts exceeded", {
+						code: brokerDiagnosticCode(error),
+					});
+				} else {
+					logger.warn("sdk broker recovery unavailable", {
+						code: brokerDiagnosticCode(error),
+						backoffWaitMs: brokerRecoveryBackoff.getBackoffWaitMs(options.agentDir),
+					});
+				}
 			} finally {
 				if (brokerRecoveryInFlight === recovery) brokerRecoveryInFlight = undefined;
 			}
@@ -7210,6 +7311,9 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		try {
 			publishedEndpointUrl = (await runtime.start()).url;
 			await registerBroker();
+			// Await the startup runtime image capture before arming recovery.
+			// This ensures replacement detection works correctly on the first recovery check.
+			await startupImageCapture;
 			if (!brokerRecoveryStopped) startBrokerRecovery();
 		} catch (error) {
 			active = undefined;

package/src/sdk/index.ts

@@ -21,6 +21,7 @@ export type {
 	TrackedSendUserMessageOptions,
 } from "../session/agent-session";
 export * as bus from "./bus";
+export * from "./diagnostics/observe-broker";
 export * as host from "./host";
 export * as lifecycle from "./lifecycle";
 export * as mcp from "./mcp";

package/src/sdk/lifecycle-session.ts

@@ -123,6 +123,7 @@ export async function createLifecycleAgentSession(
 			// inside the broker's readiness window is what kills the child at the
 			// cutoff; the host resumes it once readiness is published.
 			deferMemoryBackendStartup: true,
+			deferOptionalModelRefresh: true,
 			[lifecycleStartupCapabilityOption]: capability,
 			...(mcpStartupTimeoutMs !== undefined ? { [lifecycleMcpStartupTimeoutOption]: mcpStartupTimeoutMs } : {}),
 		} as CreateAgentSessionOptions & {

package/src/sdk/prompt-watchdog.ts

@@ -97,8 +97,13 @@ export class PromptActivity {
 	#awaitingModel = false;
 
 	/** Folds one inbound frame's lifecycle event into the in-flight tool and model state. */
-	observe(eventType: string | undefined, toolCallId: string | undefined, messageRole: string | undefined): void {
-		this.#observeInference(eventType, messageRole);
+	observe(
+		eventType: string | undefined,
+		toolCallId: string | undefined,
+		messageRole: string | undefined,
+		messageHasToolCall = false,
+	): void {
+		this.#observeInference(eventType, messageRole, messageHasToolCall);
 		if (toolCallId === undefined) return;
 		if (eventType === "tool_execution_start" || eventType === "tool_execution_update") this.#running.add(toolCallId);
 		else if (eventType === "tool_execution_end") this.#running.delete(toolCallId);
@@ -110,7 +115,11 @@ export class PromptActivity {
 	 * re-invocation that carries a tool result back — until the first frame of that
 	 * response proves the model answered.
 	 */
-	#observeInference(eventType: string | undefined, messageRole: string | undefined): void {
+	#observeInference(
+		eventType: string | undefined,
+		messageRole: string | undefined,
+		messageHasToolCall: boolean,
+	): void {
 		if (eventType === "agent_start" || eventType === "tool_execution_end") {
 			this.#awaitingModel = true;
 			return;
@@ -132,7 +141,11 @@ export class PromptActivity {
 		// Providers that do not stream emit no `message_update`, so the assistant message
 		// itself is the first proof. `message_start`/`message_end` also carry the user and
 		// tool-result messages the host echoes back, which prove nothing about the model.
-		if ((eventType === "message_start" || eventType === "message_end") && messageRole === "assistant")
+		if (
+			(eventType === "message_start" || eventType === "message_end") &&
+			messageRole === "assistant" &&
+			!messageHasToolCall
+		)
 			this.#awaitingModel = false;
 	}
 

package/src/sdk/protocol/operation-registry.ts

@@ -267,7 +267,7 @@ function controlErrors(id: string): string[] {
 		// refuses a session with no selected model before admission. The code is
 		// appended: ACP machine-only mapping reads errorCodes[0].
 		C01: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed", "model_not_selected"],
-		C02: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
+		C02: ["turn_not_active", "client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
 		C09: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
 		C06: ["action_claimed"],
 		C07: ["action_claimed", "terminal_uncertain"],

package/src/sdk/router/session-router.ts

@@ -287,6 +287,8 @@ export interface SessionRouterOptions {
 	agentDir: string;
 	/** Limits attachment to exact ids selected by a Broker-scoped operation. */
 	sessionIds?: readonly string[];
+	/** Dynamically limits attachment to sessions currently owned by the caller. */
+	attachFilter?: (sessionId: string) => boolean;
 	/** Marks default SDK clients as notification-only observers; demanding by default. */
 	observer?: boolean;
 	deps?: SessionRouterDeps;
@@ -615,6 +617,7 @@ type AdoptedSession = {
 export class SessionRouter {
 	readonly #agentDir: string;
 	readonly #sessionIds: ReadonlySet<string> | undefined;
+	readonly #attachFilter: ((sessionId: string) => boolean) | undefined;
 	readonly #observer: boolean;
 	readonly #deps: SessionRouterDeps;
 	readonly #correlateFrame: SessionRouterFrameCorrelator;
@@ -657,6 +660,7 @@ export class SessionRouter {
 	constructor(options: SessionRouterOptions) {
 		this.#agentDir = options.agentDir;
 		this.#sessionIds = options.sessionIds === undefined ? undefined : new Set(options.sessionIds);
+		this.#attachFilter = options.attachFilter;
 		this.#observer = options.observer === true;
 		this.#deps = options.deps ?? {};
 		this.#correlateFrame = options.correlateFrame ?? fallbackCorrelation;
@@ -797,6 +801,7 @@ export class SessionRouter {
 		if (
 			sessionId !== fallback.sessionId ||
 			(this.#sessionIds !== undefined && !this.#sessionIds.has(sessionId ?? "")) ||
+			(this.#attachFilter !== undefined && !this.#attachFilter(sessionId ?? "")) ||
 			endpointGeneration === undefined ||
 			pid === undefined ||
 			endpointMtimeMs === undefined ||
@@ -1294,7 +1299,8 @@ export class SessionRouter {
 				session.live &&
 				isSessionAuthorityEligible(session) &&
 				!session.terminalUncertain &&
-				(this.#sessionIds === undefined || this.#sessionIds.has(session.sessionId)),
+				(this.#sessionIds === undefined || this.#sessionIds.has(session.sessionId)) &&
+				(this.#attachFilter === undefined || this.#attachFilter(session.sessionId)),
 		);
 		const liveIds = new Set(live.map(session => session.sessionId));
 		const attachedIds = new Set<string>();

package/src/sdk/session.ts

@@ -59,7 +59,11 @@ import { loadCapability, reset as resetCapabilities } from "../capability";
 import { type Rule, ruleCapability, setActiveRules } from "../capability/rule";
 import type { SourceMeta } from "../capability/types";
 import { AUTOROUTING_INACTIVE_WARNING } from "../config/autorouting-contract";
-import { ModelProfileCredentialError, resolveMissingSessionModelRecovery } from "../config/model-profile-activation";
+import {
+	isSessionCredentialPinBlocking,
+	ModelProfileCredentialError,
+	resolveMissingSessionModelRecovery,
+} from "../config/model-profile-activation";
 import { resolveModelProfileName } from "../config/model-profile-contract";
 import { resolveProfileBindings } from "../config/model-profiles";
 import { kNoAuth, ModelRegistry } from "../config/model-registry";
@@ -577,6 +581,12 @@ export interface CreateAgentSessionOptions {
 	 * @internal CLI-only ordering guard; SDK callers retain immediate startup by default.
 	 */
 	deferMemoryBackendStartup?: boolean;
+	/**
+	 * Skip optional model-catalog discovery during lifecycle startup. ACP hosts must
+	 * publish their endpoint before unrelated provider credential refreshes begin.
+	 * @internal lifecycle-only startup guard.
+	 */
+	deferOptionalModelRefresh?: boolean;
 
 	/** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
 	enableLsp?: boolean;
@@ -695,6 +705,22 @@ export interface CreateAgentSessionResult {
 	gjcRuntimeSnapshot?: GjcRuntimeSnapshotProvider;
 }
 
+/**
+ * Start optional provider/model discovery only when it is safe to add work to
+ * the caller's startup graph. Lifecycle hosts deliberately skip this during
+ * construction: discovery preflights every configured provider and may refresh
+ * an unrelated OAuth credential while several hosts are opening the same DB.
+ */
+export function startOptionalModelRefresh(
+	modelRegistry: Pick<ModelRegistry, "refreshInBackground">,
+	credentialSessionId: string | undefined,
+	deferred: boolean,
+): boolean {
+	if (deferred) return false;
+	modelRegistry.refreshInBackground("online-if-uncached", credentialSessionId);
+	return true;
+}
+
 export interface DeferredMcpConfigStartupResult {
 	loadedToolCount: number;
 	hasErrors: boolean;
@@ -1970,11 +1996,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				options.preferredCredentialSelector.selector,
 			);
 		}
+		// A runtime key or this registry's literal models.yml apiKey outranks an
+		// unavailable pin; without one the provider stays blocked (never retargeted).
+		const isCredentialPinBlocking = (provider: string): boolean =>
+			isSessionCredentialPinBlocking(modelRegistry, provider, credentialSessionId);
 		const modelApiKeyAvailability = new Map<string, boolean>();
 		const getModelAvailabilityKey = (candidate: Model): string =>
 			`${candidate.provider}\u0000${candidate.baseUrl ?? ""}`;
 		const hasModelApiKey = async (candidate: Model): Promise<boolean> => {
-			if (authStorage.hasSessionCredentialUnavailable(candidate.provider, credentialSessionId)) return false;
+			if (isCredentialPinBlocking(candidate.provider)) return false;
 			const availabilityKey = getModelAvailabilityKey(candidate);
 			const cached = modelApiKeyAvailability.get(availabilityKey);
 			if (cached !== undefined) {
@@ -2000,6 +2030,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const key = await modelRegistry
 				.getApiKey(candidate, credentialSessionId, { credentialSelector })
 				.catch(error => {
+					if (isCredentialPinBlocking(candidate.provider)) return undefined;
 					if (credentialSelector) {
 						logger.debug("Credential selector did not match model availability candidate", {
 							provider: candidate.provider,
@@ -2148,7 +2179,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				settings,
 			);
 			await refreshMissingQualifiedModelProviders(startupModelSelectors, modelRegistry, credentialSessionId);
-			modelRegistry.refreshInBackground("online-if-uncached", credentialSessionId);
+			startOptionalModelRefresh(modelRegistry, credentialSessionId, options.deferOptionalModelRefresh === true);
 		}
 
 		const hasExplicitModel = options.model !== undefined || options.modelPattern !== undefined;
@@ -2241,8 +2272,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					{
 						managedFallback: defaultModelEntries.length > 1,
 						canonicalSessionId: providerSessionId,
-						isCredentialUnavailable: provider =>
-							authStorage.hasSessionCredentialUnavailable(provider, credentialSessionId),
+						isCredentialUnavailable: isCredentialPinBlocking,
 						...(persistedProfileOwnsDefault ? { aliasIntent: "preset-equivalent" as const } : {}),
 					},
 				);
@@ -2297,7 +2327,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			!hasExplicitModel &&
 			!model &&
 			defaultRoleSpec.model &&
-			!authStorage.hasSessionCredentialUnavailable(defaultRoleSpec.model.provider, credentialSessionId) &&
+			!isCredentialPinBlocking(defaultRoleSpec.model.provider) &&
 			(!preferredCredentialProvider || defaultRoleSpec.model.provider === preferredCredentialProvider)
 		) {
 			const settingsDefaultModel = defaultRoleSpec.model;
@@ -4236,8 +4266,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				{
 					managedFallback: defaultModelEntries.length > 1,
 					canonicalSessionId: providerSessionId,
-					isCredentialUnavailable: provider =>
-						authStorage.hasSessionCredentialUnavailable(provider, credentialSessionId),
+					isCredentialUnavailable: isCredentialPinBlocking,
 					...(persistedProfileOwnsDefault ? { aliasIntent: "preset-equivalent" as const } : {}),
 				},
 			);