@gajae-code/coding-agent 0.12.11 → 0.12.12

package/src/session/agent-session.ts

@@ -184,7 +184,7 @@ import {
 } from "@gajae-code/utils";
 
 import { createAppendOnlyContextManager, resolveAppendOnlyMode } from "../append-only-mode";
-import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async";
+import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager, type OwnerSubagentShutdownLease } from "../async";
 import { reset as resetCapabilities } from "../capability";
 import type { Rule } from "../capability/rule";
 import type { CasReceipt } from "../config/atomic-yaml-patch";
@@ -610,6 +610,8 @@ export interface AgentSessionConfig {
 	discoveryMode?: "off" | "mcp-only" | "all";
 	/** MCP tool names to activate for the current session when discovery mode is enabled. */
 	initialSelectedMCPToolNames?: string[];
+	/** Keep persisted MCP names until a deferred exact catalog becomes available. */
+	preserveUnavailableInitialMCPToolSelection?: boolean;
 	/** Built-in discoverable tool names restored for the current all-discovery session. */
 	initialSelectedDiscoveredBuiltinToolNames?: string[];
 	/** Discoverable built-ins active for configured or explicit reasons independently of persisted discovery selection. */
@@ -656,6 +658,8 @@ export interface AgentSessionConfig {
 	 * process-global manager **MUST NOT** dispose it on their own teardown.
 	 */
 	ownedMcpManager?: MCPManager;
+	/** Optional startup dependency that must settle before the first provider turn. */
+	startupTurnBarrier?: Promise<void>;
 	/** Optional fork-context seed used to initialize a child session before its first prompt. */
 	forkContextSeed?: ForkContextSeed;
 	/** Optional provider state override. Fork-context children should omit this by default. */
@@ -1947,6 +1951,7 @@ export class AgentSession {
 	 */
 	readonly #ownedAsyncJobManager: AsyncJobManager | undefined;
 	readonly #ownedMcpManager: MCPManager | undefined;
+	#startupTurnBarrier: Promise<void> | undefined;
 	#pendingPythonMessages: PythonExecutionMessage[] = [];
 	#activeEvalExecutions = new Set<Promise<unknown>>();
 	#evalExecutionDisposing = false;
@@ -1966,6 +1971,8 @@ export class AgentSession {
 	#isDisposed = false;
 	#disposePromise: Promise<void> | undefined;
 	readonly #toolSessionCleanups = new Set<() => Promise<void> | void>();
+	readonly #toolSessionTransitionCleanups = new Set<() => Promise<void> | void>();
+	readonly #deferredOwnerShutdownFinalizations = new Set<Promise<void>>();
 	#newSessionTransition: Promise<boolean> | undefined;
 	// Extension system
 	#extensionRunner: ExtensionRunner | undefined = undefined;
@@ -2269,10 +2276,23 @@ export class AgentSession {
 		next.ready.resolve();
 	}
 
+	async #awaitStartupTurnBarrier(): Promise<void> {
+		const barrier = this.#startupTurnBarrier;
+		if (!barrier) return;
+		await barrier;
+		if (this.#startupTurnBarrier === barrier) this.#startupTurnBarrier = undefined;
+	}
+	extendStartupTurnBarrier(barrier: Promise<void>): void {
+		const current = this.#startupTurnBarrier;
+		this.#startupTurnBarrier = current ? Promise.all([current, barrier]).then(() => {}) : barrier;
+		void this.#startupTurnBarrier.catch(() => {});
+	}
+
 	async #withSessionAdmission<T>(
 		kind: SessionAdmissionKind,
 		body: (lease: SessionAdmissionLease) => Promise<T>,
 	): Promise<T> {
+		if (kind === "prompt") await this.#awaitStartupTurnBarrier();
 		const owner = this.#sessionAdmissionContext.getStore();
 		if (owner && !owner.released) throw this.#sessionAdmissionBusyError();
 		if (this.#sessionAdmissionClosed || this.#isDisposed) throw this.#sessionAdmissionBusyError();
@@ -2601,6 +2621,7 @@ export class AgentSession {
 		this.#ownedAsyncJobManager = config.ownedAsyncJobManager;
 		this.#retainedMemorySampler = config.retainedMemorySampler;
 		this.#ownedMcpManager = config.ownedMcpManager;
+		this.#startupTurnBarrier = config.startupTurnBarrier;
 		this.#scopedModels = config.scopedModels ?? [];
 		this.#thinkingLevel = config.thinkingLevel;
 		this.#promptTemplates = config.promptTemplates ?? [];
@@ -2661,6 +2682,8 @@ export class AgentSession {
 			injectIdle: async messages => {
 				const first = messages[0];
 				if (!first) return;
+				await this.#awaitStartupTurnBarrier();
+				if (this.#isDisposed) return;
 				if (messages.length === 1) {
 					await this.agent.prompt(first, this.#managedFallbackPromptOptions());
 				} else {
@@ -2723,7 +2746,7 @@ export class AgentSession {
 			config.initialDiscoveredBuiltinToolSelectionIsExplicit === true
 				? this.#selectRestorableDiscoveredBuiltinToolNames(config.initialPersistedDiscoveredBuiltinToolNames ?? [])
 				: undefined;
-		this.#pruneSelectedMCPToolNames();
+		if (!config.preserveUnavailableInitialMCPToolSelection) this.#pruneSelectedMCPToolNames();
 		const persistInitialMCPToolSelection =
 			config.persistInitialMCPToolSelection === true && config.initialMCPToolSelectionIsExplicit !== false;
 		const persistInitialDiscoveredBuiltinToolSelection =
@@ -3377,6 +3400,9 @@ export class AgentSession {
 	getAgentId(): string | undefined {
 		return this.#agentId;
 	}
+	get isDisposed(): boolean {
+		return this.#isDisposed;
+	}
 
 	registerToolSessionCleanup(cleanup: () => Promise<void> | void): () => void {
 		if (this.#isDisposed) throw new Error("Cannot register tool cleanup after session disposal has started.");
@@ -3384,6 +3410,23 @@ export class AgentSession {
 		return () => this.#toolSessionCleanups.delete(cleanup);
 	}
 
+	registerToolSessionTransitionCleanup(cleanup: () => Promise<void> | void): () => void {
+		if (this.#isDisposed)
+			throw new Error("Cannot register tool transition cleanup after session disposal has started.");
+		this.#toolSessionTransitionCleanups.add(cleanup);
+		return () => this.#toolSessionTransitionCleanups.delete(cleanup);
+	}
+
+	async #runToolSessionTransitionCleanups(): Promise<void> {
+		const cleanups = Array.from(this.#toolSessionTransitionCleanups);
+		this.#toolSessionTransitionCleanups.clear();
+		const results = await Promise.allSettled(cleanups.map(async cleanup => await cleanup()));
+		for (const result of results) {
+			if (result.status === "rejected")
+				logger.warn("Tool session transition cleanup failed", { error: String(result.reason) });
+		}
+	}
+
 	async #runToolSessionCleanups(): Promise<void> {
 		const cleanups = Array.from(this.#toolSessionCleanups);
 		this.#toolSessionCleanups.clear();
@@ -3436,6 +3479,61 @@ export class AgentSession {
 		manager.cancelAll({ ownerId: this.#agentId });
 	}
 
+	async #settleOwnAsyncJobsBeforeArtifactRetirement(): Promise<void> {
+		const ownerId = this.#agentId;
+		const manager = AsyncJobManager.instance();
+		if (!ownerId || !manager) return;
+		const lease = manager.beginOwnerSubagentShutdown(ownerId);
+		if (!lease) throw new Error("Owned async cleanup is already in progress before artifact retirement.");
+		let committed = false;
+		try {
+			manager.runOwnerProducerCleanupsStrict({ ownerId });
+			const proof = await manager.cancelAndProveOwnerSubagents(lease);
+			if (!proof.confirmed)
+				throw new Error("Owned subagent cleanup could not be confirmed before artifact retirement.");
+			if (!(await manager.waitForOwnerInFlightDeliveries(ownerId)))
+				throw new Error("Owned async deliveries did not settle before artifact retirement.");
+			if (!(await manager.cancelAndSettleOwnerJobs(ownerId)))
+				throw new Error("Owned async jobs did not settle before artifact retirement.");
+			committed = true;
+		} finally {
+			manager.finishOwnerSubagentShutdown(lease, committed ? "commit" : "release");
+		}
+	}
+
+	#scheduleDeferredOwnerShutdownFinalization(
+		manager: AsyncJobManager,
+		lease: OwnerSubagentShutdownLease,
+		ownerId: string,
+	): void {
+		const finalization = (async () => {
+			while (!this.#isDisposed) {
+				try {
+					manager.runOwnerProducerCleanupsStrict({ ownerId });
+					const proof = await manager.cancelAndProveOwnerSubagents(lease);
+					if (!proof.confirmed) throw new Error(`owner_subagent_${proof.reason}`);
+					if (!(await manager.waitForOwnerInFlightDeliveries(ownerId)))
+						throw new Error("owner_delivery_settlement_timeout");
+					if (!(await manager.cancelAndSettleOwnerJobs(ownerId))) throw new Error("owner_job_settlement_timeout");
+					if (this.#isDisposed) break;
+					this.sessionManager.retireEphemeralArtifactsAfterTransition();
+					await this.#runToolSessionTransitionCleanups();
+					manager.finishOwnerSubagentShutdown(lease, "commit");
+					return;
+				} catch (error) {
+					logger.warn("Deferred owner shutdown finalization retry failed", {
+						ownerId,
+						error: error instanceof Error ? error.message : String(error),
+					});
+					await Bun.sleep(25);
+				}
+			}
+			manager.finishOwnerSubagentShutdown(lease, "release");
+		})();
+		this.#deferredOwnerShutdownFinalizations.add(finalization);
+		void finalization.finally(() => this.#deferredOwnerShutdownFinalizations.delete(finalization));
+	}
+
 	#suppressOwnAsyncJobDeliveries(): void {
 		if (!this.#agentId) return;
 		const manager = AsyncJobManager.instance();
@@ -4647,6 +4745,11 @@ export class AgentSession {
 						settleLease();
 						return;
 					}
+					await this.#awaitStartupTurnBarrier();
+					if (!canContinue()) {
+						settleLease();
+						return;
+					}
 					try {
 						if (!options?.skipCompactionCheck) {
 							await this.#checkEstimatedContextBeforePrompt();
@@ -5996,6 +6099,7 @@ export class AgentSession {
 		// the session that owns the manager goes on to dispose it (which itself
 		// nukes any leftover jobs and pending deliveries).
 		this.#cancelOwnAsyncJobs();
+		await Promise.allSettled(this.#deferredOwnerShutdownFinalizations);
 		const ownedAsyncManager = this.#ownedAsyncJobManager;
 		if (ownedAsyncManager) {
 			const drained = await ownedAsyncManager.dispose({ timeoutMs: 3_000 });
@@ -6007,6 +6111,7 @@ export class AgentSession {
 				AsyncJobManager.setInstance(undefined);
 			}
 		}
+		await this.#runToolSessionTransitionCleanups();
 		await this.#runToolSessionCleanups();
 		// Only disconnect the MCP manager THIS session owns (top-level sessions that
 		// connected plugin-bundle MCP servers). Subagents and callers that merely
@@ -6834,6 +6939,12 @@ export class AgentSession {
 				const built = await this.#runAdmittedBaseSystemPromptRebuild(() =>
 					this.#rebuildSystemPrompt!(validToolNames, this.#toolRegistry),
 				);
+				if (this.#isDisposed) {
+					if (generation === this.#baseSystemPromptGeneration) {
+						this.#pendingAppliedToolSignature = undefined;
+					}
+					return;
+				}
 				if (generation === this.#baseSystemPromptGeneration) {
 					this.#baseSystemPrompt = built.systemPrompt;
 					this.agent.setSystemPrompt(this.#baseSystemPrompt);
@@ -7319,6 +7430,8 @@ export class AgentSession {
 		if (!canContinuePersistedHistory(this.agent.state.messages)) {
 			throw new Error("Cannot continue from persisted message history");
 		}
+		await this.#awaitStartupTurnBarrier();
+		if (this.#sessionAdmissionClosed || this.#isDisposed) throw this.#sessionAdmissionBusyError();
 		this.#beginInFlight();
 		let hindsightRecall: string | undefined;
 		try {
@@ -10183,6 +10296,7 @@ export class AgentSession {
 				// Last fallible gate while public getters still show the predecessor (#3138).
 				await initializeLocalRoot(this.#localProtocolOptions(prepared));
 				this.sessionManager.commitPreparedNewSession(prepared);
+				await this.#runToolSessionTransitionCleanups();
 			} catch (error) {
 				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
 			}
@@ -10252,6 +10366,7 @@ export class AgentSession {
 				// Last fallible gate while public getters still show the predecessor (#3138).
 				await initializeLocalRoot(this.#localProtocolOptions(prepared));
 				this.sessionManager.commitPreparedNewSession(prepared);
+				await this.#runToolSessionTransitionCleanups();
 			} catch (error) {
 				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
 			}
@@ -10418,7 +10533,9 @@ export class AgentSession {
 			}
 			try {
 				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+				await this.#settleOwnAsyncJobsBeforeArtifactRetirement();
 				this.sessionManager.commitPreparedNewSession(prepared);
+				await this.#runToolSessionTransitionCleanups();
 			} catch (error) {
 				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
 			}
@@ -11535,6 +11652,7 @@ export class AgentSession {
 		const artifactManager = this.sessionManager.getArtifactManager();
 		const prunedArtifacts: Array<{ entryId: string; id: string; toolType: string; originalText: string }> = [];
 		let reservedArtifactId: string | undefined;
+		let artifactAllocationAvailable = artifactManager !== null;
 		if (artifactManager) {
 			try {
 				reservedArtifactId = (await artifactManager.allocatePath("tool-output")).id;
@@ -11542,14 +11660,24 @@ export class AgentSession {
 				logger.warn("Failed to reserve artifact ID for pruned tool output", {
 					error: error instanceof Error ? error.message : String(error),
 				});
+				artifactAllocationAvailable = false;
 			}
 		}
 		const result = pruneToolOutputs(branchEntries, DEFAULT_PRUNE_CONFIG, {
 			relaxedMinimum: overThreshold ? 0 : undefined,
 			artifactRefMaxChars: PRUNED_ARTIFACT_REF_MAX_CHARS,
 			artifactRef: candidate => {
-				if (!artifactManager) return undefined;
-				const id = reservedArtifactId ?? String(artifactManager.allocateId());
+				if (!artifactManager || !artifactAllocationAvailable) return undefined;
+				let id: string;
+				try {
+					id = reservedArtifactId ?? String(artifactManager.allocateId());
+				} catch (error) {
+					artifactAllocationAvailable = false;
+					logger.warn("Failed to allocate artifact ID for pruned tool output", {
+						error: error instanceof Error ? error.message : String(error),
+					});
+					return undefined;
+				}
 				reservedArtifactId = undefined;
 				const toolType = (candidate.toolName ?? "tool-output").replace(/[^a-zA-Z0-9_-]/g, "_") || "tool-output";
 				prunedArtifacts.push({ entryId: candidate.entryId, id, toolType, originalText: candidate.originalText });
@@ -12161,10 +12289,12 @@ export class AgentSession {
 				const successorGateEmitter = this.#constructWorkflowGateEmitter(prepared.sessionId);
 				// Last fallible action: verified local:// readiness from immutable staged options.
 				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+				await this.#settleOwnAsyncJobsBeforeArtifactRetirement();
 
 				// --- Commit boundary: synchronous adoption is the sole identity publication.
 				this.sessionManager.commitPreparedNewSession(prepared);
 				committed = true;
+				await this.#runToolSessionTransitionCleanups();
 				this.agent.reset();
 				this.#syncAgentSessionId();
 				this.#rekeyHindsightMemoryForCurrentSessionId();
@@ -12195,7 +12325,6 @@ export class AgentSession {
 				this.#resetIrcRosterDeliveryState();
 				this.#planReferenceSent = false;
 				this.#planReferencePath = "local://PLAN.md";
-				this.#cancelOwnAsyncJobs();
 				// The predecessor's fenced async-job results (queued while the
 				// transition held the delivery fence) belong to the handed-off session,
 				// not the successor. Suppress and drop ONLY the async-result kind so they
@@ -14937,6 +15066,17 @@ export class AgentSession {
 		// before the failure. This bypasses #hasCleanRetryReplaySafety because the
 		// content-free check is the replay-safety guarantee for credential rotation.
 		const canReplayRotatedCredential = credentialRotated;
+		// Universal automatic replay-safety gate (#3791): once the failed attempt
+		// carries observable assistant text, thinking, or tool-call content,
+		// automatic session retry must not re-issue the request. This covers
+		// configured legacy retry (which previously only gated first-event
+		// timeouts) as well as bare defaults. Managed fallback keeps its
+		// provisional discard path (events never published to the session).
+		// Content-free credential rotation remains eligible above; first-event
+		// timeout keeps its additional typed/scope checks earlier in this method.
+		if (!managedFallback && assistantMessageHasVisibleOrToolContent(message)) {
+			return false;
+		}
 		// Bare defaults retain their narrow watchdog and Codex admissions. A
 		// first-event timeout adds the typed, content-free, current-clean-scope
 		// requirement above; other transient watchdogs preserve legacy behavior.
@@ -16300,6 +16440,10 @@ export class AgentSession {
 			onTransitionMutationStarted?: () => void;
 		},
 	): Promise<boolean> {
+		let ownerShutdownManager: AsyncJobManager | undefined;
+		let ownerShutdownLease: OwnerSubagentShutdownLease | undefined;
+		let ownerShutdownTransitionCommitted = false;
+		let ownerShutdownFinalizationDeferred = false;
 		this.#beginSessionTransition("switch-session");
 		try {
 			const previousSessionFile = this.sessionManager.getSessionFile();
@@ -16320,9 +16464,31 @@ export class AgentSession {
 			}
 			options?.onTransitionMutationStarted?.();
 
-			this.#disconnectFromAgent();
+			const asyncManager = AsyncJobManager.instance();
+			const ownerId = this.#agentId;
+			const lease =
+				switchingToDifferentSession && asyncManager && ownerId
+					? asyncManager.beginOwnerSubagentShutdown(ownerId)
+					: undefined;
+			if (switchingToDifferentSession && asyncManager && ownerId && !lease) {
+				this.emitNotice(
+					"error",
+					"Cannot switch sessions while owned subagent cleanup is already in progress.",
+					"switch-session-subagent-cleanup",
+				);
+				return false;
+			}
+			if (lease && asyncManager) {
+				ownerShutdownManager = asyncManager;
+				ownerShutdownLease = lease;
+			}
 			await this.abort();
+			if (this.isCompacting) {
+				this.abortCompaction();
+				while (this.isCompacting) await Bun.sleep(10);
+			}
 
+			this.#disconnectFromAgent();
 			// Flush pending writes before switching so restore snapshots reflect committed state.
 			await this.sessionManager.flush();
 			const previousSessionState = this.sessionManager.captureState();
@@ -16353,9 +16519,13 @@ export class AgentSession {
 				? this.#suspendWorkflowGateEmitter(previousSessionState.sessionId)
 				: undefined;
 			let unavailableDefaultChainMessage: string | undefined;
+			let transitionCleanupCommitted = false;
 
 			try {
-				await this.sessionManager.setSessionFile(sessionPath);
+				await this.sessionManager.setSessionFile(sessionPath, {
+					deferEphemeralArtifactRetirement: switchingToDifferentSession,
+				});
+				if (switchingToDifferentSession) this.sessionManager.stageAdoptedArtifactManagerForTransition();
 				// The successor identity is already rotated in the manager but not yet
 				// published; gate its local:// root before publication so the agent,
 				// workflow-gate emitter, and hooks cannot resolve against an ungated
@@ -16455,6 +16625,38 @@ export class AgentSession {
 					this.#resetIrcRosterDeliveryState();
 				}
 
+				if (switchingToDifferentSession) {
+					let ownerShutdownSettled = true;
+					if (ownerShutdownManager && ownerShutdownLease && ownerId) {
+						try {
+							ownerShutdownManager.runOwnerProducerCleanupsStrict({ ownerId });
+							const proof = await ownerShutdownManager.cancelAndProveOwnerSubagents(ownerShutdownLease);
+							if (!proof.confirmed)
+								throw new Error("Owned subagent cleanup could not be confirmed after successor validation.");
+							if (!(await ownerShutdownManager.waitForOwnerInFlightDeliveries(ownerId)))
+								throw new Error("Owned async deliveries did not settle after successor validation.");
+							if (!(await ownerShutdownManager.cancelAndSettleOwnerJobs(ownerId)))
+								throw new Error("Owned async jobs did not settle after successor validation.");
+						} catch (error) {
+							ownerShutdownSettled = false;
+							ownerShutdownFinalizationDeferred = true;
+							this.#scheduleDeferredOwnerShutdownFinalization(ownerShutdownManager, ownerShutdownLease, ownerId);
+							this.#suppressOwnAsyncJobDeliveries();
+							this.emitNotice(
+								"error",
+								`Successor session is active, but predecessor async cleanup did not settle: ${error instanceof Error ? error.message : String(error)}`,
+								"switch-session-subagent-cleanup",
+							);
+						}
+					}
+					transitionCleanupCommitted = true;
+					// Different files may intentionally carry the same copied session id; pathname transition is the commit signal.
+					ownerShutdownTransitionCommitted = true;
+					if (ownerShutdownSettled) {
+						this.sessionManager.retireEphemeralArtifactsAfterTransition();
+						await this.#runToolSessionTransitionCleanups();
+					}
+				}
 				this.#reconnectToAgent();
 				// Fence predecessor continuations before session_switch starts SDK runtime
 				// teardown. The previous runtime waits for those continuations to settle;
@@ -16463,7 +16665,8 @@ export class AgentSession {
 					this.#bindWorkflowGateEmitter(previousSessionState.sessionId, suspendedWorkflowGateEmitter);
 				// session_switch is the post-commit identity signal. SDK authority and
 				// other identity-bound integrations must not observe the successor until
-				// messages, model state, MCP selections, and the agent subscription are live.
+				// messages, model state, MCP selections, the agent subscription, and
+				// session-scoped tool cleanup are complete.
 				if (this.#extensionRunner) {
 					await this.#extensionRunner.emit({
 						type: "session_switch",
@@ -16474,6 +16677,7 @@ export class AgentSession {
 				}
 				return true;
 			} catch (error) {
+				if (transitionCleanupCommitted) throw error;
 				this.sessionManager.restoreState(previousSessionState);
 				this.#defaultFallbackController = undefined;
 				this.#syncAgentSessionId(previousSessionState.sessionId);
@@ -16532,6 +16736,12 @@ export class AgentSession {
 				throw error;
 			}
 		} finally {
+			if (ownerShutdownManager && ownerShutdownLease && !ownerShutdownFinalizationDeferred) {
+				ownerShutdownManager.finishOwnerSubagentShutdown(
+					ownerShutdownLease,
+					ownerShutdownTransitionCommitted ? "commit" : "release",
+				);
+			}
 			this.#endSessionTransition();
 		}
 	}
@@ -16583,13 +16793,14 @@ export class AgentSession {
 				: await this.sessionManager.prepareNewSession({ parentSession: previousSessionFile });
 			try {
 				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+				await this.#settleOwnAsyncJobsBeforeArtifactRetirement();
 				this.sessionManager.commitPreparedNewSession(prepared);
+				await this.#runToolSessionTransitionCleanups();
 			} catch (error) {
 				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
 			}
 			this.#pendingNextTurnMessages = [];
 			this.#scheduledHiddenNextTurnGeneration = undefined;
-			this.#cancelOwnAsyncJobs();
 
 			this.#syncTodoPhasesFromBranch();
 			this.#syncAgentSessionId();

package/src/session/artifacts.ts

@@ -13,6 +13,7 @@ import {
 	ensureManagedDirectory,
 	type ManagedSessionDescendantStore,
 	publishManagedFileNoReplace,
+	publishManagedFileNoReplaceSync,
 } from "./internal/managed-session-storage";
 import { DEFAULT_ARTIFACT_MAX_BYTES, truncateHeadBytes } from "./streaming-output";
 
@@ -78,7 +79,8 @@ export class ArtifactManager {
 	readonly #dir: string;
 	readonly #store: ManagedSessionDescendantStore | undefined;
 	#dirCreated = false;
-	#initialized = false;
+	#initialized: Promise<void> | undefined;
+	#initializedComplete = false;
 
 	/**
 	 * @param dir Directory that will hold artifact files. Created lazily on first save.
@@ -118,10 +120,10 @@ export class ArtifactManager {
 			else ensureManagedDirectory(this.#dir);
 			this.#dirCreated = true;
 		}
-		if (!this.#initialized) {
-			await this.#scanExistingIds();
-			this.#initialized = true;
-		}
+		// Memoized: concurrent first writers must not each rescan and restart the
+		// ID counter at the same value, which would collide on publish.
+		this.#initialized ??= this.#scanExistingIds();
+		await this.#initialized;
 	}
 
 	#filename(id: string, toolType: string): string {
@@ -129,6 +131,44 @@ export class ArtifactManager {
 		return `${id}.${toolType}.log`;
 	}
 
+	#claimFilename(id: number): string {
+		return `.artifact-id-${id}`;
+	}
+
+	#nextCandidateId(): number {
+		const id = this.#nextId++;
+		if (!Number.isSafeInteger(id) || id < 0) throw new Error("artifact_id_out_of_range");
+		return id;
+	}
+
+	async #claimNextId(): Promise<number> {
+		while (true) {
+			const id = this.#nextCandidateId();
+			try {
+				await this.#publish("", this.#claimFilename(id));
+				return id;
+			} catch (error) {
+				if (!(error instanceof Error) || error.message !== "destination_conflict") throw error;
+			}
+		}
+	}
+
+	#claimNextIdSync(): number {
+		if (!this.#initializedComplete)
+			throw new Error("ArtifactManager must be initialized before synchronous allocation");
+		while (true) {
+			const id = this.#nextCandidateId();
+			try {
+				const filename = this.#claimFilename(id);
+				if (this.#store) this.#store.publishNoReplaceSync(filename, new Uint8Array());
+				else publishManagedFileNoReplaceSync(path.join(this.#dir, filename), new Uint8Array());
+				return id;
+			} catch (error) {
+				if (!(error instanceof Error) || error.message !== "destination_conflict") throw error;
+			}
+		}
+	}
+
 	async #publish(content: string, filename: string): Promise<void> {
 		if (this.#store) await this.#store.publishNoReplace(filename, Buffer.from(content, "utf8"));
 		else await publishManagedFileNoReplace(path.join(this.#dir, filename), Buffer.from(content, "utf8"));
@@ -250,22 +290,25 @@ export class ArtifactManager {
 		const files = await this.listFiles();
 		let maxId = -1;
 		for (const file of files) {
-			// Files are named: {id}.{toolType}.log
-			const match = file.match(/^(\d+)\..*\.log$/);
+			// Published artifacts are `{id}.{toolType}.log`; hidden claim files reserve
+			// the numeric namespace across independent managers and processes.
+			const match = file.match(/^(\d+)\..*\.log$/) ?? file.match(/^\.artifact-id-(\d+)$/);
 			if (match) {
-				const id = parseInt(match[1], 10);
+				const id = Number(match[1]);
+				if (!Number.isSafeInteger(id) || id < 0) throw new Error("artifact_id_out_of_range");
 				if (id > maxId) maxId = id;
 			}
 		}
 		this.#nextId = maxId + 1;
+		this.#initializedComplete = true;
 	}
 
 	/**
-	 * Atomically allocate next artifact ID.
-	 * IDs are sequential within the session.
+	 * Atomically claim the next artifact ID after this manager has been initialized.
+	 * Prefer `allocatePath` or `save`; this synchronous seam exists for pruning callbacks.
 	 */
 	allocateId(): number {
-		return this.#nextId++;
+		return this.#claimNextIdSync();
 	}
 
 	/**
@@ -276,7 +319,7 @@ export class ArtifactManager {
 	 */
 	async allocatePath(toolType: string): Promise<{ id: string; path?: string }> {
 		await this.#ensureDir();
-		const id = String(this.allocateId());
+		const id = String(await this.#claimNextId());
 		if (this.#store) return { id };
 		return { id, path: path.join(this.#dir, this.#filename(id, toolType)) };
 	}
@@ -288,7 +331,7 @@ export class ArtifactManager {
 	 */
 	async save(content: string, toolType: string, options: ArtifactSaveOptions = {}): Promise<string> {
 		await this.#ensureDir();
-		const id = String(this.allocateId());
+		const id = String(await this.#claimNextId());
 		const maxBytes = Math.max(0, options.maxBytes ?? DEFAULT_ARTIFACT_MAX_BYTES);
 		const contentBytes = Buffer.byteLength(content, "utf-8");
 		const published =