@gajae-code/coding-agent 0.17.1 → 0.17.2

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

@@ -4,13 +4,14 @@ 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, ThinkingLevel } from "@gajae-code/agent-core";
+import { isContinuingMidRunMaintenanceOutcome, isNonDispatchedToolEvent, ThinkingLevel } from "@gajae-code/agent-core";
 import type { Api, ImageContent, Model } from "@gajae-code/ai/core";
 import { logger } from "@gajae-code/utils";
 import { AsyncJobManager } from "../../async";
 import {
 	getProxyRoutableProviders,
 	inspectProxyProviderId,
+	isModelProfileProxyConfigured,
 	requiresQualifiedModelProfileRoleResolution,
 	resolveProxyMode,
 	rewriteSelectorForProxy,
@@ -1645,18 +1646,18 @@ function createQuerySurface(
 		};
 		try {
 			const proxyMode = profile.source === "user" ? "fallback" : resolveProxyMode(profileSettings);
-			if (profile.source !== "user") {
-				const configuredProviders = ctx.modelRegistry.getConfiguredProviderIds?.() ?? [];
-				if (proxyProvider !== undefined && !configuredProviders.includes(proxyProvider))
+			if (proxyProvider !== undefined) {
+				const configuredProviders = ctx.modelRegistry.getConfiguredProviderIds?.();
+				const credentialless =
+					proxyProvider === "opencodex" &&
+					!configuredProviders?.includes(proxyProvider) &&
+					(await ctx.modelRegistry.getApiKeyForProvider(proxyProvider, getProfileCredentialSessionId())) ===
+						kNoAuth;
+				if (!isModelProfileProxyConfigured(proxyProvider, configuredProviders, credentialless))
 					return { available: false };
 			}
 			if (profile.source !== "user" && proxyMode === "always") {
-				if (
-					proxyProvider === undefined ||
-					!proxyAuthenticated ||
-					!(ctx.modelRegistry.getConfiguredProviderIds?.() ?? []).includes(proxyProvider)
-				)
-					return { available: false };
+				if (proxyProvider === undefined || !proxyAuthenticated) return { available: false };
 			}
 			const bindings = resolveProfileBindings(profile);
 			const assignments: Array<{ value: ModelSelectorValue; isDefault: boolean }> = [];
@@ -4378,6 +4379,78 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 	const activePromptOwnerHolder: { connectionIds?: Set<string>; lifecycleEpoch?: number } = {};
 	let nextLifecycleEpoch = 0;
 	const skillTerminalRecoveryKeys = new Set<string>();
+	/**
+	 * Exactly one correlated terminal BOUNDARY (agent_end) may reach the wire per
+	 * correlation. The provider agent_end handler and the prompt-deadline expiry can both
+	 * reach their emission after the other has already published: the handler captures its
+	 * transitions synchronously and then awaits durable writes, while the deadline callback
+	 * fires only after its own claim/finalize awaits have settled. Neither can be stopped by
+	 * removing lifecycle references, and noteTransition is a no-op once the record is
+	 * terminal, so durable state would record one outcome while clients received two. This
+	 * claim is the shared arbiter, taken synchronously -- no await between the check and the
+	 * set -- by whoever is about to publish the boundary.
+	 *
+	 * The key is never removed at cleanup: dropping it when the correlation retires would
+	 * re-open the window, and would stop a late real boundary from being idempotent for an
+	 * already-retired correlation. Growth is bounded by FIFO eviction instead (a Set
+	 * preserves insertion order). A correlation displaced by 1024 later boundaries is long
+	 * retired, and its durable record stays authoritative for anything a consumer missed.
+	 *
+	 * Eviction must never reach a correlation that can still be published (review P1). A
+	 * handler captures its transitions, awaits durable writes, and claims only immediately
+	 * before its emit; parked on those awaits, 1024 later boundaries would otherwise evict
+	 * its key and let its delayed agent_end publish a SECOND boundary for a correlation the
+	 * deadline already terminalized. Every would-be publisher therefore RETAINS its
+	 * correlations for as long as it can still reach a claim, and a retained key is skipped
+	 * as an eviction victim.
+	 */
+	const MAX_PUBLISHED_TERMINAL_BOUNDARIES = 1024;
+	const publishedTerminalBoundaries = new Set<string>();
+	/** Correlations with at least one publisher still able to reach a claim. */
+	const retainedTerminalBoundaries = new Map<string, number>();
+	/**
+	 * Protect every correlation this publisher may still claim, and return its release.
+	 * Callers MUST release on every exit path -- published, claim lost, or threw -- so a
+	 * failure cannot leak a permanent protection.
+	 */
+	const retainTerminalBoundaries = (
+		invocations: ReadonlyArray<{ correlation: InvocationCorrelation }>,
+	): (() => void) => {
+		const keys = invocations.map(({ correlation }) => lifecycleCorrelationKey(correlation));
+		for (const key of keys) retainedTerminalBoundaries.set(key, (retainedTerminalBoundaries.get(key) ?? 0) + 1);
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			for (const key of keys) {
+				const retained = retainedTerminalBoundaries.get(key);
+				if (retained === undefined) continue;
+				if (retained > 1) retainedTerminalBoundaries.set(key, retained - 1);
+				else retainedTerminalBoundaries.delete(key);
+			}
+		};
+	};
+	const claimTerminalBoundary = (correlation: InvocationCorrelation): boolean => {
+		const key = lifecycleCorrelationKey(correlation);
+		if (publishedTerminalBoundaries.has(key)) return false;
+		publishedTerminalBoundaries.add(key);
+		while (publishedTerminalBoundaries.size > MAX_PUBLISHED_TERMINAL_BOUNDARIES) {
+			let victim: string | undefined;
+			for (const candidate of publishedTerminalBoundaries) {
+				if (retainedTerminalBoundaries.has(candidate)) continue;
+				victim = candidate;
+				break;
+			}
+			// Every key is still publishable: exceed the bound rather than evict a live
+			// one. Correctness beats the bound, and the excess is bounded by the live
+			// lifecycles the session already bounds.
+			if (victim === undefined) break;
+			publishedTerminalBoundaries.delete(victim);
+		}
+		return true;
+	};
+	const hasClaimedTerminalBoundary = (correlation: InvocationCorrelation): boolean =>
+		publishedTerminalBoundaries.has(lifecycleCorrelationKey(correlation));
 	const trackLifecycle = (handler: () => Promise<void>, owner: RuntimeState | undefined): Promise<void> => {
 		if (!owner) return Promise.resolve();
 		let task: Promise<void>;
@@ -4728,6 +4801,11 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		// recorded as observed=false, never rethrown into the api handler.
 		let observed = true;
 		const failedTransitions: Array<{ kind: InvocationKind; correlation: InvocationCorrelation }> = [];
+		// Retained BEFORE the first durable await: from here this publisher can still
+		// reach the claim below, so no later boundary may evict its correlations while
+		// it is parked. A start retains too -- its keys are not published yet, so the
+		// protection is inert, and one unconditional release path cannot leak.
+		const releaseTerminalRetention = retainTerminalBoundaries(transitions);
 		try {
 			for (const invocation of transitions) {
 				try {
@@ -4809,6 +4887,15 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					failureCause ?? Object.assign(new Error("agent run failed"), { code: "agent_failed" }),
 				);
 				for (const invocation of transitions) {
+					// A correlation whose terminal boundary is already published was
+					// terminalized by the deadline, which emitted its own diagnostic together
+					// with the pair; a second correlated agent_failed would duplicate it. The
+					// check is READ-ONLY: the claim is taken by would-be agent_end publishers
+					// alone, because the real path emits its agent_failed and its agent_end
+					// from two SEPARATE emitLifecycle invocations, so claiming here would make
+					// the publisher block its own boundary. In the ordinary flow this changes
+					// nothing -- agent_failed precedes agent_end and the claim is untaken.
+					if (hasClaimedTerminalBoundary(invocation.correlation)) continue;
 					try {
 						current.runtime.emitEvent({
 							type,
@@ -4856,6 +4943,15 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				// above with the one uncorrelated frame, so it cannot settle a live prompt.
 				const outcome = terminalOutcome ?? terminalStoppedOutcome(stopReason, maintenanceOutcome);
 				for (const invocation of transitions) {
+					// Claim synchronously, immediately before the emit: the durable awaits
+					// above give the deadline expiry room to publish this correlation's
+					// boundary first. On a lost claim skip ONLY this frame -- every durable
+					// write, diagnostic cleanup, batch retirement and waiter resolution below
+					// still runs. `observed` deliberately stays true: it means "the correlated
+					// publication reached the wire", and it did, the deadline put it there.
+					// Flipping it would make a terminal abort's durable row refuse to claim
+					// terminalPublished for a boundary that IS on the wire.
+					if (!claimTerminalBoundary(invocation.correlation)) continue;
 					try {
 						current.runtime.emitEvent({ type, sessionId, ...invocation.correlation, outcome });
 					} catch {
@@ -4872,6 +4968,10 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			}
 		} catch {
 			observed = false;
+		} finally {
+			// Every exit path -- published, claim lost, or threw -- releases: this
+			// publisher can no longer reach a claim.
+			releaseTerminalRetention();
 		}
 		if (type === "agent_end" && isContinuingMidRunMaintenanceOutcome(maintenanceOutcome)) return;
 		if (type === "agent_end") {
@@ -5055,7 +5155,16 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 	// the active run — the root invocation plus any in-run consumed follow-ups
 	// sharing it — not only the head, or an attached correlation would
 	// false-fire prompt_deadline_exceeded during a long shared run.
-	const renewAttributableProgress = (eventType: string, ctx: ExtensionContext): void => {
+	const renewAttributableProgress = (
+		eventType: "tool_execution_start" | "tool_execution_update" | "tool_execution_end",
+		event: AgentSessionEvent,
+		ctx: ExtensionContext,
+	): void => {
+		// Pairing-only tool boundaries synthesized while an abort unwinds never
+		// entered a tool. Treating them as progress lets a deadline renew its own
+		// lease after claiming the terminal outcome, leaving that claim pending
+		// instead of durably finalizing it.
+		if (isNonDispatchedToolEvent(event)) return;
 		// Tool events do not carry an SDK run token. Prefer the lifecycle-active
 		// runtime for the current session so a retained predecessor cannot make a
 		// live replacement look ambiguous and suppress its lease renewal.
@@ -5166,14 +5275,14 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		}
 		publishContentFrames(current, event as AgentSessionEvent, invocations);
 	};
-	api.on("tool_execution_start", async (_event, ctx) => {
-		renewAttributableProgress("tool_execution_start", ctx);
+	api.on("tool_execution_start", async (event, ctx) => {
+		renewAttributableProgress("tool_execution_start", event as AgentSessionEvent, ctx);
 	});
-	api.on("tool_execution_update", async (_event, ctx) => {
-		renewAttributableProgress("tool_execution_update", ctx);
+	api.on("tool_execution_update", async (event, ctx) => {
+		renewAttributableProgress("tool_execution_update", event as AgentSessionEvent, ctx);
 	});
-	api.on("tool_execution_end", async (_event, ctx) => {
-		renewAttributableProgress("tool_execution_end", ctx);
+	api.on("tool_execution_end", async (event, ctx) => {
+		renewAttributableProgress("tool_execution_end", event as AgentSessionEvent, ctx);
 	});
 	const errorCode = (error: unknown): string | undefined =>
 		typeof error === "object" &&
@@ -5214,11 +5323,69 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				const v = options.settings?.get("sdk.promptMaxRuntimeMs" as never) as number | undefined;
 				return typeof v === "number" && Number.isFinite(v) ? v : 21_600_000;
 			},
-			onExpired: correlation => {
+			onExpired: (correlation, deadlineOutcome) => {
 				const owner = lifecycleOwnerHolder.state;
-				if (!owner) return;
-				removeLifecycleReferences(owner, correlation);
-				maybeRetireLifecycleOwner(owner);
+				if (deadlineOutcome === undefined) {
+					if (!owner) return;
+					removeLifecycleReferences(owner, correlation);
+					maybeRetireLifecycleOwner(owner);
+					return;
+				}
+				const failure = sanitizePromptFailure(
+					Object.assign(new Error("Prompt deadline exceeded."), { code: deadlineOutcome.code }),
+				);
+				// The deadline publishes a failed/end PAIR and owns it atomically, so the
+				// boundary claim is taken once, here, covering both frames. Losing it means
+				// a real agent_end already reached the wire for this correlation: emit
+				// NEITHER frame, but still run the cleanup below, and still let #expire
+				// finish its durable reconciliation. Losing the boundary must not skip
+				// cleanup.
+				//
+				// Retained for the whole publication: this path owns the correlation from
+				// here, so a concurrent boundary must not evict its key mid-flight.
+				const releaseTerminalRetention = retainTerminalBoundaries([{ correlation }]);
+				try {
+					if (claimTerminalBoundary(correlation)) {
+						// Each required frame is emitted INDEPENDENTLY (review P2): a throwing
+						// diagnostic must never suppress the boundary, which is the frame this
+						// path exists to deliver. Both failures are reported, never rethrown --
+						// the cleanup below still has to run.
+						try {
+							runtime.emitEvent({
+								type: "agent_failed",
+								sessionId,
+								...correlation,
+								error: failure,
+							});
+						} catch (error) {
+							logger.warn("sdk: deadline correlated diagnostic publication failed", {
+								commandId: correlation.commandId,
+								turnId: correlation.turnId,
+								error: sanitizePromptFailure(error),
+							});
+						}
+						try {
+							runtime.emitEvent({
+								type: "agent_end",
+								sessionId,
+								...correlation,
+								outcome: canonicalFailedOutcome(failure, "deadline"),
+							});
+						} catch (error) {
+							logger.error("sdk: deadline correlated boundary publication failed", {
+								commandId: correlation.commandId,
+								turnId: correlation.turnId,
+								error: sanitizePromptFailure(error),
+							});
+						}
+					}
+				} finally {
+					releaseTerminalRetention();
+				}
+				if (owner) {
+					removeLifecycleReferences(owner, correlation);
+					maybeRetireLifecycleOwner(owner);
+				}
 			},
 		});
 		const pending: Array<{

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

@@ -48,14 +48,14 @@ export class PromptDeadlineManager {
 	readonly #getLeaseMs: () => number;
 	readonly #getMaxMs: () => number;
 	readonly #now: () => number;
-	readonly #onExpired?: (correlation: InvocationCorrelation) => void;
+	readonly #onExpired?: (correlation: InvocationCorrelation, outcome?: PromptDeadlineOutcome) => void;
 
 	constructor(options: {
 		reconciliation: DeadlineReconciliation;
 		getLeaseMs: () => number;
 		getMaxMs: () => number;
 		now?: () => number;
-		onExpired?: (correlation: InvocationCorrelation) => void;
+		onExpired?: (correlation: InvocationCorrelation, outcome?: PromptDeadlineOutcome) => void;
 	}) {
 		this.#reconciliation = options.reconciliation;
 		this.#getLeaseMs = options.getLeaseMs;
@@ -197,7 +197,7 @@ export class PromptDeadlineManager {
 		// accepted/in-flight invocation without an owner, retry, or deadline
 		// recovery path.
 		try {
-			this.#onExpired?.(correlation);
+			this.#onExpired?.(correlation, outcome);
 		} catch {}
 		this.#expiryRetries.delete(key);
 		this.clear(correlation);

package/src/sdk/prompt-failure.ts

@@ -3,7 +3,12 @@
  * Provider error text is retained only in the local diagnostic log; wire and
  * persisted reconciliation details expose a fixed redacted message.
  */
-import type { SdkPromptFailureCategory, SdkPromptFailurePhase, SdkPromptTerminalOutcome } from "./prompt-status";
+import type {
+	SdkPromptFailureCategory,
+	SdkPromptFailurePhase,
+	SdkPromptFailureRetryability,
+	SdkPromptTerminalOutcome,
+} from "./prompt-status";
 
 export const PROMPT_FAILURE_CODE_MAX = 64;
 const LOCAL_FAILURE_LOG_MAX = 16_384;
@@ -79,6 +84,43 @@ export function promptFailureCategory(
 	return "unknown";
 }
 
+/**
+ * Whether the bounded category says an identical re-submission could still
+ * succeed. Read off the category alone, so it cannot drift from the sets above.
+ *
+ * `provider_transport` is the only transient class: every classifier in
+ * `PROVIDER_TRANSPORT_CODES` (and the 5xx range) describes the link to the
+ * provider failing, never a judgement about the request, so the same bytes may
+ * well succeed on a second attempt. That is exactly the class the shipped
+ * first-turn gate (`isStartupReadinessFailure`, issue #5574) already treats as
+ * re-submittable, so the wire signal and the internal gate stay in agreement.
+ *
+ * Everything else is terminal for this turn: `provider_rejected` is the provider
+ * judging this request (quota, refusal, 4xx) and re-sending it reproduces the
+ * rejection; `deadline` means the turn's budget is spent, which a re-submit does
+ * not restore; `agent_runtime` is a local fault that re-running the same prompt
+ * re-enters. `unknown` stays `unknown` — the module's standing contract is to
+ * preserve uncertain attribution rather than guess a recovery for it.
+ *
+ * This is advisory classification for the caller, not a retry gate: nothing in
+ * this repo's retry paths consults it.
+ */
+export function promptFailureRetryability(category: SdkPromptFailureCategory): SdkPromptFailureRetryability {
+	if (category === "provider_transport") return "transient";
+	if (category === "unknown") return "unknown";
+	return "terminal";
+}
+
+/**
+ * Whether a value is a safe bounded classifier token — the same rule
+ * `sanitizePromptFailure` and `assistantFailureCode` apply before retaining one.
+ * Anything else is provider text rather than a classifier and must not be
+ * forwarded to a caller.
+ */
+export function isSafePromptFailureCode(value: unknown): value is string {
+	return typeof value === "string" && value.length <= PROMPT_FAILURE_CODE_MAX && /^[A-Za-z0-9._-]+$/.test(value);
+}
+
 /**
  * Phase- and category-aware safe wording. A post-start failure is never
  * described as a submission rejection; the wording says only what the bounded

package/src/sdk/prompt-status.ts

@@ -75,6 +75,14 @@ export type SdkPromptFailureCategory =
 	| "agent_runtime"
 	| "deadline"
 	| "unknown";
+/**
+ * Whether the failure class says an identical re-submission could still succeed.
+ * Derived from `SdkPromptFailureCategory` alone (see `promptFailureRetryability`)
+ * so a consumer never has to re-implement the category matrix or parse a message.
+ * `unknown` is preserved rather than collapsed into `terminal`: an uncertain
+ * attribution is not evidence that the turn is unrecoverable.
+ */
+export type SdkPromptFailureRetryability = "transient" | "terminal" | "unknown";
 export type SdkPromptTerminalOutcome =
 	| { kind: "stopped"; reason: SdkPromptStopReason; provenance: "agent" | "client_cancel" }
 	| {

package/src/sdk/router/replay-retention-gap-cache.ts

@@ -0,0 +1,27 @@
+/**
+ * Retention-gap concessions are durable stream facts, but a Router can observe
+ * many streams over its lifetime. Keep the warning memo bounded while retaining
+ * enough recent coordinates to suppress reconnect/poll duplicates.
+ */
+export const REPLAY_CONCESSION_CACHE_LIMIT = 1_024;
+
+/**
+ * Records one stream/gap coordinate in an LRU memo.
+ *
+ * `undefined` means this is the first observation; a number is the duplicate
+ * count after the coordinate was already observed.
+ */
+export function rememberReplayRetentionGap(cache: Map<string, number>, key: string): number | undefined {
+	const previous = cache.get(key);
+	if (previous !== undefined) {
+		cache.delete(key);
+		cache.set(key, previous + 1);
+		return previous + 1;
+	}
+	cache.set(key, 0);
+	if (cache.size > REPLAY_CONCESSION_CACHE_LIMIT) {
+		const oldest = cache.keys().next().value;
+		if (oldest !== undefined) cache.delete(oldest);
+	}
+	return undefined;
+}

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

@@ -33,6 +33,7 @@ import {
 } from "../session-activation";
 import type { SessionBindingAuthority } from "../session-authority";
 import { ACP_SESSION_RECONNECT, SESSION_REQUEST_TIMEOUT_MS } from "../session-reconnect";
+import { rememberReplayRetentionGap } from "./replay-retention-gap-cache";
 
 export type { SessionBindingAuthority, SessionEndpointAuthority } from "../session-authority";
 
@@ -627,6 +628,8 @@ export class SessionRouter {
 	>();
 	readonly #reviving = new Set<string>();
 	readonly #notificationReceipts = new Map<string, NotificationCleanupReceipt>();
+	/** Recent retention-gap coordinates already reported at warning level. */
+	readonly #concededReplayGaps = new Map<string, number>();
 	#stopTimer: (() => void) | undefined;
 	#reconcileTail: Promise<void> = Promise.resolve();
 	#reconcilePending: { readonly runEpoch: number; force: boolean } | undefined;
@@ -2203,6 +2206,24 @@ export class SessionRouter {
 			`chat daemon replay barrier failed (${reason}); rebuilding session ${attached.sessionId} at generation ${attached.generation} from seq ${attached.cursor.seq}.`,
 		);
 	}
+
+	#logReplayRetentionGap(
+		attached: AttachedSession,
+		gap: Readonly<{ fromSeq: number; toSeq: number }>,
+		recoveredNote: string,
+	): void {
+		const key = JSON.stringify([attached.sessionId, attached.generation, gap.fromSeq, gap.toSeq]);
+		const repeat = rememberReplayRetentionGap(this.#concededReplayGaps, key);
+		if (repeat !== undefined) {
+			logger.debug(
+				`chat daemon replay retention gap repeated (sequences ${gap.fromSeq}-${gap.toSeq}); suppressed warning ${repeat} for session ${attached.sessionId} generation ${attached.generation}.`,
+			);
+			return;
+		}
+		logger.warn(
+			`chat daemon replay conceded a retention gap (sequences ${gap.fromSeq}-${gap.toSeq} are gone from the host${recoveredNote}); session ${attached.sessionId} generation ${attached.generation} resumes at seq ${gap.toSeq + 1}.`,
+		);
+	}
 	#failDelivery(attached: AttachedSession, seq: number, error: unknown): void {
 		const previous = this.#undelivered.get(attached.sessionId);
 		const attempts = previous?.generation === attached.generation && previous.seq === seq ? previous.attempts + 1 : 1;
@@ -2503,9 +2524,7 @@ export class SessionRouter {
 				held.splice(0, held.length, ...carried);
 				const recoveredNote =
 					recovered.length > 0 ? `, ${recovered.length} of them recovered from live delivery` : "";
-				logger.warn(
-					`chat daemon replay conceded a retention gap (sequences ${gap.fromSeq}-${gap.toSeq} are gone from the host${recoveredNote}); session ${attached.sessionId} generation ${attached.generation} resumes at seq ${gap.toSeq + 1}.`,
-				);
+				this.#logReplayRetentionGap(attached, gap, recoveredNote);
 				for (const entry of recovered) this.#rememberRecoveredFrame(attached, entry.seq, entry.frame);
 				if (!(await this.#deliverRecoveredFrames(attached))) return;
 				if (gap.toSeq > attached.cursor.seq) attached.cursor.seq = gap.toSeq;

package/src/sdk/session.ts

@@ -1516,6 +1516,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	let processCwdClaimed = false;
 	let hasRegistered = false;
 	let asyncJobManager: AsyncJobManager | undefined;
+	let asyncJobManagerOwned = false;
 	let asyncJobManagerAdmitted = false;
 	let priorAsyncJobManager: AsyncJobManager | undefined;
 	let cleanupOwnedMcpManager: (() => Promise<void>) | undefined;
@@ -2296,6 +2297,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						},
 					})
 				: options.inheritedAsyncJobManager;
+		asyncJobManagerOwned = backgroundJobsEnabled === true && !options.parentTaskPrefix;
 
 		let promptMetadataModel: Model | undefined;
 		const getActiveModelString = (): string | undefined => {
@@ -5196,15 +5198,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			} else {
 				if (hasRegistered) agentRegistry.unregister(resolvedAgentId);
 				// Admission happens before session construction. Any later startup
-				// failure must remove THIS manager's endpoint mapping and restore
-				// the prior global only when this manager is still global: otherwise
-				// a retry under the same endpoint is falsely rejected and an orphan
-				// redirects global-manager consumers away from the live session
-				// (review thread P1).
-				if (asyncJobManagerAdmitted && asyncJobManager) {
-					AsyncJobManager.unregisterManager(asyncJobManager);
-					if (AsyncJobManager.instance() === asyncJobManager) {
-						AsyncJobManager.setInstance(priorAsyncJobManager);
+				// failure must eventually release THIS manager's endpoint mapping
+				// through disposal and restore the prior global only when this manager
+				// is still global: otherwise a retry under the same endpoint is falsely
+				// rejected and an orphan redirects global-manager consumers away from
+				// the live session (review thread P1).
+				if (asyncJobManagerOwned && asyncJobManager) {
+					if (asyncJobManagerAdmitted) {
+						if (AsyncJobManager.instance() === asyncJobManager) {
+							AsyncJobManager.setInstance(priorAsyncJobManager);
+						}
 					}
 					await asyncJobManager.dispose({ timeoutMs: 100 });
 				}