@gajae-code/coding-agent 0.12.11 → 0.12.12

package/src/session/internal/managed-session-storage.ts

@@ -217,8 +217,84 @@ type ReplacementCleanupReceipt = {
 	predecessor: SerializedReplacementIdentity;
 };
 
+type LegacyReplacementCleanupIdentity = {
+	dev: bigint;
+	ino: bigint;
+	nlink: bigint;
+	size: bigint;
+	mtimeNs: bigint;
+	ctimeNs: bigint;
+	sha256: string;
+};
+
 const U64_MAX = 18_446_744_073_709_551_615n;
 
+function parseCanonicalU64(value: unknown): bigint | undefined {
+	if (typeof value !== "string" || !/^(0|[1-9][0-9]*)$/.test(value) || value.length > 20) return undefined;
+	const parsed = BigInt(value);
+	return parsed <= U64_MAX ? parsed : undefined;
+}
+
+function parseLegacyHexU64(value: string): bigint | undefined {
+	if (!/^[0-9a-f]+$/.test(value) || value.length > 16) return undefined;
+	const parsed = BigInt(`0x${value}`);
+	return parsed <= U64_MAX ? parsed : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+function legacyReplacementCleanupReceiptBinding(name: string): { dev: bigint; ino: bigint } | undefined {
+	const match = /^\.gjc-replace-cleanup-([0-9a-f]+)-([0-9a-f]+)\.json$/.exec(name);
+	if (!match?.[1] || !match[2]) return undefined;
+	const dev = parseLegacyHexU64(match[1]);
+	const ino = parseLegacyHexU64(match[2]);
+	return dev !== undefined && ino !== undefined ? { dev, ino } : undefined;
+}
+
+function parseLegacyReplacementCleanupIdentity(value: unknown): LegacyReplacementCleanupIdentity | undefined {
+	const identity = asRecord(value);
+	if (!identity) return undefined;
+	const dev = parseCanonicalU64(identity.dev);
+	const ino = parseCanonicalU64(identity.ino);
+	const nlink = parseCanonicalU64(identity.nlink);
+	const size = parseCanonicalU64(identity.size);
+	const mtimeNs = parseCanonicalU64(identity.mtimeNs);
+	const ctimeNs = parseCanonicalU64(identity.ctimeNs);
+	const sha256 = identity.sha256;
+	if (
+		dev === undefined ||
+		ino === undefined ||
+		nlink === undefined ||
+		size === undefined ||
+		mtimeNs === undefined ||
+		ctimeNs === undefined ||
+		typeof sha256 !== "string" ||
+		!/^[0-9a-f]{64}$/.test(sha256)
+	)
+		return undefined;
+	return { dev, ino, nlink, size, mtimeNs, ctimeNs, sha256 };
+}
+
+function parseLegacyReplacementCleanupReceipt(
+	bytes: Uint8Array,
+): { predecessor: string; successor: string; identity: LegacyReplacementCleanupIdentity } | undefined {
+	let value: unknown;
+	try {
+		value = JSON.parse(Buffer.from(bytes).toString("utf8")) as unknown;
+	} catch {
+		return undefined;
+	}
+	const receipt = asRecord(value);
+	if (receipt?.version !== 1 || typeof receipt.predecessor !== "string" || typeof receipt.successor !== "string")
+		return undefined;
+	const identity = parseLegacyReplacementCleanupIdentity(receipt.identity);
+	return identity ? { predecessor: receipt.predecessor, successor: receipt.successor, identity } : undefined;
+}
+
 function replacementCleanupReceiptBinding(
 	name: string,
 ): { predecessor: { dev: bigint; ino: bigint }; receipt: { dev: bigint; ino: bigint } } | undefined {
@@ -258,12 +334,20 @@ function replacementReceiptPath(
 }
 
 function replacementReceiptRetirementName(
-	receipt: ManagedFileSnapshot["identity"],
-	predecessor: ManagedFileSnapshot["identity"],
+	receipt: { dev: bigint; ino: bigint },
+	predecessor: { dev: bigint; ino: bigint },
 ): string {
 	return `.gjc-receipt-remove-${receipt.dev.toString(16)}-${receipt.ino.toString(16)}-${predecessor.dev.toString(16)}-${predecessor.ino.toString(16)}`;
 }
 
+function replacementReceiptPlaceholderRetirementName(
+	placeholder: { dev: bigint; ino: bigint },
+	predecessor: { dev: bigint; ino: bigint },
+	receipt: { dev: bigint; ino: bigint },
+): string {
+	return `.gjc-receipt-placeholder-remove-${placeholder.dev.toString(16)}-${placeholder.ino.toString(16)}-${predecessor.dev.toString(16)}-${predecessor.ino.toString(16)}-${receipt.dev.toString(16)}-${receipt.ino.toString(16)}`;
+}
+
 const ACL_FAILURE_CODES = new Set(["acl_denied", "acl_io_error", "acl_present", "acl_malformed", "acl_unknown"]);
 const ACL_CLEAR_EVIDENCE = new Set(["cleared", "already_absent", "unsupported", "not_run"]);
 const GENERAL_FAILURE_CODES = new Set([
@@ -785,14 +869,68 @@ export class ManagedSessionDescendantStore {
 		}
 	}
 
+	#recoverReplacementCleanupPlaceholder(
+		receiptPath: string,
+		binding: { predecessor: { dev: bigint; ino: bigint }; receipt: { dev: bigint; ino: bigint } },
+		placeholder: ManagedFileSnapshot,
+	): boolean {
+		if (placeholder.bytes.byteLength !== 0) return false;
+		const detachedReceiptPath = path.join(
+			this.#baseDir,
+			replacementReceiptRetirementName(binding.receipt, binding.predecessor),
+		);
+		let detachedReceipt: ManagedFileSnapshot;
+		try {
+			detachedReceipt = captureManagedFileNoFollow(detachedReceiptPath);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+			throw error;
+		}
+		if (detachedReceipt.identity.dev !== binding.receipt.dev || detachedReceipt.identity.ino !== binding.receipt.ino)
+			return false;
+
+		const quarantineName = replacementReceiptPlaceholderRetirementName(
+			placeholder.identity,
+			binding.predecessor,
+			binding.receipt,
+		);
+		const removed = exactUnlink(receiptPath, {
+			dev: placeholder.identity.dev,
+			ino: placeholder.identity.ino,
+			nlink: placeholder.identity.nlink,
+			parentDev: this.#subtreeRoot.dev,
+			parentIno: this.#subtreeRoot.ino,
+			size: BigInt(placeholder.identity.size),
+			mtimeNs: placeholder.identity.mtimeNs,
+			sha256: placeholder.identity.sha256,
+			quarantineName,
+		});
+		if (
+			(!exactUnlinkCompleted(removed) && removed.code !== "not_found") ||
+			removed.retainedSuccessorPath !== undefined ||
+			removed.retainedUnknownPath !== undefined
+		)
+			throw new Error(`managed_replace_receipt_cleanup_pending:${removed.code ?? "unknown"}`);
+		fsyncDirectory(this.#baseDir);
+		return true;
+	}
+
 	#detachReplacementCleanupReceipt(receiptPath: string): void {
 		const binding = replacementCleanupReceiptBinding(path.basename(receiptPath));
 		if (!binding) throw new Error("managed_replace_cleanup_receipt_invalid");
-		const receipt = captureManagedFileNoFollow(receiptPath);
-		if (receipt.identity.dev !== binding.receipt.dev || receipt.identity.ino !== binding.receipt.ino)
+		let receipt: ManagedFileSnapshot;
+		try {
+			receipt = captureManagedFileNoFollow(receiptPath);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			throw error;
+		}
+		if (receipt.identity.dev !== binding.receipt.dev || receipt.identity.ino !== binding.receipt.ino) {
+			if (this.#recoverReplacementCleanupPlaceholder(receiptPath, binding, receipt)) return;
 			throw new Error("managed_replace_cleanup_receipt_invalid");
+		}
 		const predecessor = binding.predecessor;
-		const quarantineName = `.gjc-receipt-remove-${receipt.identity.dev.toString(16)}-${receipt.identity.ino.toString(16)}-${predecessor.dev.toString(16)}-${predecessor.ino.toString(16)}`;
+		const quarantineName = replacementReceiptRetirementName(receipt.identity, predecessor);
 		const detached = exactUnlink(receiptPath, {
 			dev: receipt.identity.dev,
 			ino: receipt.identity.ino,
@@ -815,14 +953,75 @@ export class ManagedSessionDescendantStore {
 		fsyncDirectory(this.#baseDir);
 	}
 
+	#reconcileLegacyReplacementCleanupReceipt(receiptPath: string, name: string): void {
+		const binding = legacyReplacementCleanupReceiptBinding(name);
+		if (!binding) throw new Error("managed_replace_cleanup_receipt_invalid");
+		const receipt = captureManagedFileNoFollow(receiptPath);
+		const parsed = parseLegacyReplacementCleanupReceipt(receipt.bytes);
+		const expectedPredecessor = path.join(
+			this.#baseDir,
+			`.gjc-exact-replace-destination-${binding.dev.toString(16)}-${binding.ino.toString(16)}`,
+		);
+		if (
+			!parsed ||
+			parsed.identity.dev !== binding.dev ||
+			parsed.identity.ino !== binding.ino ||
+			path.resolve(parsed.predecessor) !== expectedPredecessor ||
+			path.dirname(path.resolve(parsed.successor)) !== this.#baseDir
+		)
+			throw new Error("managed_replace_cleanup_receipt_invalid");
+
+		const retired = exactUnlink(expectedPredecessor, {
+			dev: parsed.identity.dev,
+			ino: parsed.identity.ino,
+			nlink: parsed.identity.nlink,
+			parentDev: this.#subtreeRoot.dev,
+			parentIno: this.#subtreeRoot.ino,
+			size: parsed.identity.size,
+			mtimeNs: parsed.identity.mtimeNs,
+			sha256: parsed.identity.sha256,
+			quarantineName: `.gjc-replace-retry-${parsed.identity.dev.toString(16)}-${parsed.identity.ino.toString(16)}`,
+		});
+		if (!exactUnlinkCompleted(retired) && retired.code !== "not_found")
+			throw new Error(`managed_replace_cleanup_pending:${retired.code ?? "unknown"}`);
+
+		const currentReceipt = captureManagedFileNoFollow(receiptPath);
+		if (
+			!sameIdentity(currentReceipt.identity, receipt.identity) ||
+			currentReceipt.identity.sha256 !== receipt.identity.sha256
+		)
+			throw new Error("managed_replace_cleanup_receipt_invalid");
+		const removed = exactUnlink(receiptPath, {
+			dev: currentReceipt.identity.dev,
+			ino: currentReceipt.identity.ino,
+			nlink: currentReceipt.identity.nlink,
+			parentDev: this.#subtreeRoot.dev,
+			parentIno: this.#subtreeRoot.ino,
+			size: BigInt(currentReceipt.identity.size),
+			mtimeNs: currentReceipt.identity.mtimeNs,
+			sha256: currentReceipt.identity.sha256,
+			quarantineName: `.gjc-receipt-remove-${currentReceipt.identity.dev.toString(16)}-${currentReceipt.identity.ino.toString(16)}`,
+		});
+		if (!exactUnlinkCompleted(removed) && removed.code !== "not_found")
+			throw new Error(`managed_replace_receipt_cleanup_pending:${removed.code ?? "unknown"}`);
+		fsyncDirectory(this.#baseDir);
+	}
+
 	#reconcileReplacementCleanupReceipts(): void {
 		if (this.#reconcilingReplacementCleanup) return;
 		this.#reconcilingReplacementCleanup = true;
 		try {
 			for (const name of fs.readdirSync(this.#baseDir)) {
 				if (!name.startsWith(".gjc-replace-cleanup-")) continue;
-				if (!replacementCleanupReceiptBinding(name)) throw new Error("managed_replace_cleanup_receipt_invalid");
-				this.#detachReplacementCleanupReceipt(path.join(this.#baseDir, name));
+				if (replacementCleanupReceiptBinding(name)) {
+					this.#detachReplacementCleanupReceipt(path.join(this.#baseDir, name));
+					continue;
+				}
+				if (legacyReplacementCleanupReceiptBinding(name)) {
+					this.#reconcileLegacyReplacementCleanupReceipt(path.join(this.#baseDir, name), name);
+					continue;
+				}
+				throw new Error("managed_replace_cleanup_receipt_invalid");
 			}
 		} finally {
 			this.#reconcilingReplacementCleanup = false;

package/src/session/session-manager.ts

@@ -4765,6 +4765,7 @@ interface SessionManagerStateSnapshot {
 	needsFullRewriteOnNextPersist: boolean;
 	fileEntries: FileEntry[];
 	materializedFileEntries: FileEntry[];
+	adoptedArtifactManager: ArtifactManager | null;
 }
 
 /** Benchmark-derived cap for strong materialized session snapshots. */
@@ -4775,6 +4776,7 @@ export const SessionManagerTestHooks: {
 	materializedCacheMaxBytesOverride?: number;
 	beforeResidentTransitionIndexBuild?: () => void;
 	afterForkSnapshot?: () => void | Promise<void>;
+	beforeEphemeralArtifactManagerInstall?: (dir: string) => void | Promise<void>;
 } = {};
 
 function materializedCacheMaxBytes(): number {
@@ -4841,10 +4843,13 @@ export class SessionManager {
 	// Subagents adopt the parent's manager so artifact IDs are unique across the
 	// whole agent tree and all files land in the parent's artifacts dir.
 	#adoptedArtifactManager: ArtifactManager | null = null;
-	// In-memory artifact fallback for non-persistent sessions (persist=false).
-	// Keyed by sequential numeric ID string; mirrors the file-based ArtifactManager ID scheme.
-	#inMemoryArtifacts: Map<string, string> | null = null;
-	#inMemoryArtifactCounter = 0;
+	// Filesystem-backed artifact fallback for non-persistent sessions (persist=false).
+	// The directory is created lazily on first save so artifact content is read back
+	// from disk on demand instead of being retained in memory for the session lifetime.
+	#ephemeralArtifactManager: ArtifactManager | null = null;
+	#ephemeralArtifactDir: string | null = null;
+	#ephemeralArtifactInit: Promise<ArtifactManager | null> | null = null;
+	#ephemeralArtifactCleanups = new Set<Promise<void>>();
 	readonly #blobStore: BlobStore;
 	#residentTextBlobStore: BlobStore = new MemoryBlobStore();
 	#residentImageBlobStore: BlobStore;
@@ -5360,6 +5365,7 @@ export class SessionManager {
 			// Rollback snapshots must own resident data before another session reset disposes
 			// the ephemeral store backing the resident sentinels above.
 			materializedFileEntries,
+			adoptedArtifactManager: this.#adoptedArtifactManager,
 		};
 	}
 
@@ -5397,7 +5403,7 @@ export class SessionManager {
 		this.#persistErrorReported = false;
 		this.#artifactManager = null;
 		this.#artifactManagerSessionFile = null;
-		this.#adoptedArtifactManager = null;
+		this.#adoptedArtifactManager = snapshot.adoptedArtifactManager;
 		this.#commitResidentTextStoreTransition(prepared);
 		if (this.#sessionFile) writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
 	}
@@ -5438,8 +5444,7 @@ export class SessionManager {
 		this.#flushed = false;
 		this.#needsFullRewriteOnNextPersist = false;
 		this.#ensuredOnDisk = false;
-		this.#inMemoryArtifacts = null;
-		this.#inMemoryArtifactCounter = 0;
+
 		this.#artifactManager = null;
 		this.#artifactManagerSessionFile = null;
 		this.#adoptedArtifactManager = null;
@@ -5471,6 +5476,7 @@ export class SessionManager {
 			const prepared = this.#prepareFreshSessionTransition(fresh, "memory-fallback");
 			this.#applyFreshSessionMetadata(fresh);
 			this.#commitResidentTextStoreTransition(prepared);
+			this.#retireEphemeralArtifacts();
 			writeTerminalBreadcrumb(this.cwd, resolvedSessionFile);
 			await this.#rewriteFile();
 			this.#flushed = true;
@@ -5544,7 +5550,7 @@ export class SessionManager {
 	}
 
 	/** Switch to a different session file (used for resume and branching). */
-	async setSessionFile(sessionFile: string): Promise<void> {
+	async setSessionFile(sessionFile: string, options?: { deferEphemeralArtifactRetirement?: boolean }): Promise<void> {
 		this.#assertRecoveryHydrationWritable();
 		const resolvedSessionFile = this.storage instanceof FileSessionStorage ? path.resolve(sessionFile) : sessionFile;
 		const strictAdoption = this.#pendingStrictAdoption;
@@ -5641,6 +5647,7 @@ export class SessionManager {
 					prepared.dispose();
 					throw error;
 				}
+				if (!options?.deferEphemeralArtifactRetirement) this.#retireEphemeralArtifacts();
 				managedTransition?.settle();
 				this.#pendingStrictAdoption = undefined;
 				this.#flushed = true;
@@ -5668,8 +5675,6 @@ export class SessionManager {
 				flushed: this.#flushed,
 				needsFullRewriteOnNextPersist: this.#needsFullRewriteOnNextPersist,
 				ensuredOnDisk: this.#ensuredOnDisk,
-				inMemoryArtifacts: this.#inMemoryArtifacts,
-				inMemoryArtifactCounter: this.#inMemoryArtifactCounter,
 				artifactManager: this.#artifactManager,
 				artifactManagerSessionFile: this.#artifactManagerSessionFile,
 				adoptedArtifactManager: this.#adoptedArtifactManager,
@@ -5679,6 +5684,7 @@ export class SessionManager {
 				managedTransition?.adopt();
 				writeTerminalBreadcrumb(this.cwd, resolvedSessionFile);
 				this.#commitResidentTextStoreTransition(prepared);
+				if (!options?.deferEphemeralArtifactRetirement) this.#retireEphemeralArtifacts();
 			} catch (error) {
 				managedTransition?.rollback();
 				this.#lifecycleIdAdopted = previous.lifecycleIdAdopted;
@@ -5692,8 +5698,6 @@ export class SessionManager {
 				this.#flushed = previous.flushed;
 				this.#needsFullRewriteOnNextPersist = previous.needsFullRewriteOnNextPersist;
 				this.#ensuredOnDisk = previous.ensuredOnDisk;
-				this.#inMemoryArtifacts = previous.inMemoryArtifacts;
-				this.#inMemoryArtifactCounter = previous.inMemoryArtifactCounter;
 				this.#artifactManager = previous.artifactManager;
 				this.#artifactManagerSessionFile = previous.artifactManagerSessionFile;
 				this.#adoptedArtifactManager = previous.adoptedArtifactManager;
@@ -6139,12 +6143,12 @@ export class SessionManager {
 		this.#flushed = stage.flushed;
 		this.#needsFullRewriteOnNextPersist = false;
 		this.#ensuredOnDisk = stage.flushed;
-		this.#inMemoryArtifacts = null;
-		this.#inMemoryArtifactCounter = 0;
+
 		this.#artifactManager = null;
 		this.#artifactManagerSessionFile = null;
 		this.#adoptedArtifactManager = null;
 		this.#commitResidentTextStoreTransition(transition);
+		this.#retireEphemeralArtifacts();
 		stage.committed = true;
 		this.#preparedNewSessions.delete(stage);
 	}
@@ -6955,6 +6959,7 @@ export class SessionManager {
 		const prepared = this.#prepareFreshSessionTransition(fresh, "memory-fallback");
 		this.#applyFreshSessionMetadata(fresh);
 		this.#commitResidentTextStoreTransition(prepared);
+		this.#retireEphemeralArtifacts();
 		if (writeBreadcrumb && fresh.sessionFile) writeTerminalBreadcrumb(this.cwd, fresh.sessionFile);
 		return fresh.sessionFile;
 	}
@@ -7677,6 +7682,8 @@ export class SessionManager {
 				this.#flushed = true;
 			}
 		});
+		this.#retireEphemeralArtifacts();
+		await this.#drainEphemeralArtifactCleanups();
 		this.#releaseResidentTextStore();
 		this.#releaseOwnedManagedAuthority();
 		if (this.#persistError) throw this.#persistError;
@@ -7736,6 +7743,12 @@ export class SessionManager {
 		// close leaves the session live for a genuine retry.
 		if (!this.#persistWriter) {
 			this.#releaseResidentTextStore();
+			this.#retireEphemeralArtifacts();
+			try {
+				await this.#drainEphemeralArtifactCleanups();
+			} catch (error) {
+				outcome = { kind: "close_unknown", error: toError(error) };
+			}
 		}
 		return outcome;
 	}
@@ -8024,14 +8037,40 @@ export class SessionManager {
 		this.#adoptedArtifactManager = manager;
 	}
 
+	/** Release only the matching externally adopted manager. */
+	releaseArtifactManager(manager: ArtifactManager): void {
+		if (this.#adoptedArtifactManager === manager) this.#adoptedArtifactManager = null;
+	}
+
+	/** Temporarily release adopted authority while an outer transition validates its successor. */
+	stageAdoptedArtifactManagerForTransition(): void {
+		this.#adoptedArtifactManager = null;
+	}
+
+	/** Prove manager authority by exact object identity, never by pathname shape. */
+	isArtifactManagerAuthorized(manager: ArtifactManager): boolean {
+		return (
+			manager === this.#adoptedArtifactManager ||
+			manager === this.#artifactManager ||
+			manager === this.#ephemeralArtifactManager
+		);
+	}
+
 	/**
 	 * Returns the ArtifactManager this session writes through. Lazily creates
 	 * one bound to the current session file unless an external manager was
-	 * adopted via `adoptArtifactManager`. Returns null only for non-persistent
-	 * sessions with no adopted manager.
+	 * adopted via `adoptArtifactManager`. Falls back to the lazily created
+	 * ephemeral filesystem store once a non-persistent session has saved an
+	 * artifact, so `artifact://` stays resolvable. Returns null only when no
+	 * store has been established yet.
 	 */
 	getArtifactManager(): ArtifactManager | null {
-		return this.#getOrCreateArtifactManager();
+		return this.#getOrCreateArtifactManager() ?? this.#ephemeralArtifactManager;
+	}
+
+	/** Linearizably establish this session's persistent or ephemeral artifact manager. */
+	async ensureArtifactManager(): Promise<ArtifactManager | null> {
+		return this.#getOrCreateArtifactManager() ?? (await this.#ensureEphemeralArtifactManager());
 	}
 
 	/**
@@ -8074,28 +8113,89 @@ export class SessionManager {
 
 	/**
 	 * Save artifact content under the current session and return artifact ID.
-	 * Returns an artifact ID for all sessions (file-backed for persistent, in-memory fallback otherwise).
+	 * Persistent sessions write into the session artifact directory; non-persistent
+	 * sessions write into a lazily created temporary directory so the content is
+	 * read back from the filesystem instead of being retained in memory.
 	 */
 	async saveArtifact(content: string, toolType: string): Promise<string | undefined> {
-		const manager = this.#getOrCreateArtifactManager();
-		if (manager) return manager.save(content, toolType);
-		// Non-persistent session: store in memory so spill truncation can proceed.
-		if (!this.#inMemoryArtifacts) this.#inMemoryArtifacts = new Map();
-		const id = String(this.#inMemoryArtifactCounter++);
-		this.#inMemoryArtifacts.set(id, content);
-		return id;
+		const manager = this.#getOrCreateArtifactManager() ?? (await this.#ensureEphemeralArtifactManager());
+		return manager ? manager.save(content, toolType) : undefined;
 	}
 
 	/**
 	 * Resolve an artifact ID to an on-disk path for the current session.
-	 * Returns null when missing or when the session is not persisted.
+	 * Returns null when the artifact is missing.
 	 */
 	async getArtifactPath(id: string): Promise<string | null> {
-		const manager = this.#getOrCreateArtifactManager();
+		const manager = this.getArtifactManager();
 		if (!manager) return null;
 		return manager.getPath(id);
 	}
 
+	/**
+	 * Create the non-persistent session's temporary artifact directory on first use.
+	 * Returns null when the directory cannot be created; callers then report no artifact.
+	 */
+	async #ensureEphemeralArtifactManager(): Promise<ArtifactManager | null> {
+		if (!this.#ephemeralArtifactInit) {
+			let init: Promise<ArtifactManager | null>;
+			init = fs.promises
+				.mkdtemp(path.join(os.tmpdir(), "gjc-session-artifacts-"))
+				.then(async dir => {
+					try {
+						await SessionManagerTestHooks.beforeEphemeralArtifactManagerInstall?.(dir);
+					} catch (error) {
+						await fs.promises.rm(dir, { recursive: true, force: true });
+						throw error;
+					}
+					const manager = new ArtifactManager(dir);
+					if (this.#ephemeralArtifactInit !== init) {
+						await fs.promises.rm(dir, { recursive: true, force: true });
+						return null;
+					}
+					this.#ephemeralArtifactDir = dir;
+					this.#ephemeralArtifactManager = manager;
+					return manager;
+				})
+				.catch(() => null);
+			this.#ephemeralArtifactInit = init;
+		}
+		const init = this.#ephemeralArtifactInit;
+		const manager = await init;
+		if (!manager && this.#ephemeralArtifactInit === init) this.#ephemeralArtifactInit = null;
+		return manager;
+	}
+
+	/** Unbind the active ephemeral root only after a successor transition commits. */
+	#retireEphemeralArtifacts(): void {
+		const dir = this.#ephemeralArtifactDir;
+		const init = this.#ephemeralArtifactInit;
+		if (!dir && !init) return;
+		this.#ephemeralArtifactManager = null;
+		this.#ephemeralArtifactDir = null;
+		this.#ephemeralArtifactInit = null;
+		const cleanup = (async () => {
+			const initialized = await init;
+			const cleanupDir = dir ?? initialized?.dir;
+			if (cleanupDir) await fs.promises.rm(cleanupDir, { recursive: true, force: true });
+		})();
+		void cleanup.catch(() => {});
+		this.#ephemeralArtifactCleanups.add(cleanup);
+	}
+
+	/** Retire predecessor ephemeral artifacts after an outer logical transition commits. */
+	retireEphemeralArtifactsAfterTransition(): void {
+		this.#retireEphemeralArtifacts();
+	}
+
+	async #drainEphemeralArtifactCleanups(): Promise<void> {
+		while (this.#ephemeralArtifactCleanups.size > 0) {
+			const pending = Array.from(this.#ephemeralArtifactCleanups);
+			this.#ephemeralArtifactCleanups.clear();
+			await Promise.all(pending);
+		}
+	}
+
 	/**
 	 * Path to the unsent-input draft sidecar for an explicit session. It lives
 	 * inside the artifacts directory so `dropSession` removes it with its owner.
@@ -8229,20 +8329,26 @@ export class SessionManager {
 		await this.#persistPatch({ type: "header_patch", patch });
 	}
 
-	#appendManagedRecordSync(record: FileEntry | SessionPatchRecord): void {
+	#appendManagedRecordsSync(records: readonly (FileEntry | SessionPatchRecord)[]): void {
 		if (!this.#sessionFile) throw new Error("Managed transcript path is unavailable");
 		const store = this.#managedTranscriptStore();
 		const relativePath = path.basename(this.#sessionFile);
-		store.appendSync(relativePath, Buffer.from(`${JSON.stringify(record)}\n`, "utf8"));
+		const bytes = Buffer.from(`${records.map(record => JSON.stringify(record)).join("\n")}\n`, "utf8");
+		store.appendSync(relativePath, bytes);
 	}
 
 	async #persistPatch(record: SessionPatchRecord): Promise<void> {
-		if (!this.persist || !this.#sessionFile || !this.storage.existsSync(this.#sessionFile)) return;
+		await this.#persistPatches([record]);
+	}
+
+	async #persistPatches(records: readonly SessionPatchRecord[]): Promise<void> {
+		if (records.length === 0 || !this.persist || !this.#sessionFile || !this.storage.existsSync(this.#sessionFile))
+			return;
 		await this.#queuePersistTask(async () => {
 			const header = this.#fileEntries.find(entry => entry.type === "session") as SessionHeader | undefined;
 			if (this.#needsFullRewriteOnNextPersist || !this.#flushed || (header?.version ?? 1) < CURRENT_SESSION_VERSION)
 				return this.#rewriteFileContents();
-			const persistedRecord =
+			const persistedRecords = records.map(record =>
 				record.type === "entry_patch"
 					? (prepareEntryForPersistenceSync(
 							materializeResidentEntryForPersistenceSync(
@@ -8252,14 +8358,17 @@ export class SessionManager {
 							),
 							this.#blobStore,
 						) as unknown as SessionPatchRecord)
-					: record;
+					: record,
+			);
 			if (this.destination.kind === "managed") {
-				this.#appendManagedRecordSync(persistedRecord);
+				this.#appendManagedRecordsSync(persistedRecords);
 				return;
 			}
 			const writer = this.#ensurePersistWriter();
 			if (!writer) return this.#rewriteFileContents();
-			await writer.write(persistedRecord);
+			for (const persistedRecord of persistedRecords) {
+				await writer.write(persistedRecord);
+			}
 		});
 	}
 	_persist(entry: SessionEntry): void {
@@ -8308,7 +8417,7 @@ export class SessionManager {
 					new Map(),
 				);
 				const persistedEntry = prepareEntryForPersistenceSync(materializedEntry, this.#blobStore);
-				this.#appendManagedRecordSync(persistedEntry);
+				this.#appendManagedRecordsSync([persistedEntry]);
 				return;
 			}
 			const writer = this.#ensurePersistWriter();
@@ -9228,9 +9337,7 @@ export class SessionManager {
 
 	async #sanitizeLoadedOpenAIResponsesReplayMetadataAndPersist(): Promise<boolean> {
 		const patches = this.#sanitizeLoadedOpenAIResponsesReplayMetadata();
-		for (const patch of patches) {
-			await this.#persistPatch(patch);
-		}
+		await this.#persistPatches(patches);
 		return patches.length > 0;
 	}
 
@@ -9803,6 +9910,7 @@ export class SessionManager {
 		);
 		manager.#applyFreshSessionMetadata(fresh);
 		manager.#commitResidentTextStoreTransition(transition);
+		manager.#retireEphemeralArtifacts();
 		if (fresh.sessionFile) writeTerminalBreadcrumb(manager.cwd, fresh.sessionFile);
 		manager.sanitizeLoadedOpenAIResponsesReplayMetadata();
 		await manager.#rewriteFile();
@@ -9905,6 +10013,7 @@ export class SessionManager {
 			const transition = manager.#prepareFreshSessionTransition(fresh, "memory-fallback");
 			manager.#applyFreshSessionMetadata(fresh);
 			manager.#commitResidentTextStoreTransition(transition);
+			manager.#retireEphemeralArtifacts();
 			writeTerminalBreadcrumb(manager.cwd, resolved);
 			await manager.#rewriteFile();
 			manager.#flushed = true;
@@ -10096,6 +10205,7 @@ export class SessionManager {
 			);
 			manager.#applyFreshSessionMetadata(fresh);
 			manager.#commitResidentTextStoreTransition(transition);
+			manager.#retireEphemeralArtifacts();
 			manager.sanitizeLoadedOpenAIResponsesReplayMetadata();
 			const beforeWrite = inspectResumeSessionFile(snapshot.sourcePath, snapshot.storage);
 			if ("kind" in beforeWrite) {

package/src/setup/provider-presets.json

@@ -2,5 +2,5 @@
   {"id":"minimax","aliases":["minimax-code"],"name":"MiniMax Coding Plan","description":"OpenAI-compatible MiniMax Coding Plan endpoint","compatibility":"openai","api":"openai-completions","providerId":"minimax-code","baseUrl":"https://api.minimax.io/v1","apiKeyEnv":"MINIMAX_CODE_API_KEY","models":["minimax-m3"],"compat":{"supportsStore":false,"supportsDeveloperRole":false,"supportsReasoningEffort":false,"reasoningContentField":"reasoning_content"}},
   {"id":"minimax-cn","aliases":["minimax-code-cn","minimaxi"],"name":"MiniMax Coding Plan (China)","description":"OpenAI-compatible MiniMax China endpoint","compatibility":"openai","api":"openai-completions","providerId":"minimax-code-cn","baseUrl":"https://api.minimaxi.com/v1","apiKeyEnv":"MINIMAX_CODE_CN_API_KEY","models":["minimax-m3"],"compat":{"supportsStore":false,"supportsDeveloperRole":false,"supportsReasoningEffort":false,"reasoningContentField":"reasoning_content"}},
   {"id":"glm","aliases":["zai","z-ai","bigmodel"],"name":"GLM / zAI","description":"OpenAI-compatible GLM endpoint from zAI/BigModel","compatibility":"openai","api":"openai-completions","providerId":"glm-proxy","baseUrl":"https://api.z.ai/api/paas/v4","apiKeyEnv":"ZAI_API_KEY","models":["glm-4.6"],"compat":{"supportsDeveloperRole":false,"supportsReasoningEffort":false,"thinkingFormat":"zai","reasoningContentField":"reasoning_content"}},
-  {"id":"alibaba-token-plan","aliases":["alibaba","token-plan"],"name":"Alibaba Token Plan","description":"OpenAI-compatible Alibaba Token Plan endpoint","compatibility":"openai","api":"openai-completions","providerId":"alibaba-token-plan","baseUrl":"https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1","apiKeyEnv":"ALIBABA_TOKEN_PLAN_API_KEY","models":["qwen3.8-max-preview","glm-5.2","deepseek-v4-pro"],"modelApi":{"qwen3.8-max-preview":"openai-responses","glm-5.2":"openai-completions","deepseek-v4-pro":"openai-completions"},"compat":{"supportsDeveloperRole":false}}
+  {"id":"alibaba-token-plan","aliases":["alibaba","token-plan"],"name":"Alibaba Token Plan","description":"OpenAI-compatible Alibaba Token Plan endpoint","compatibility":"openai","api":"openai-completions","providerId":"alibaba-token-plan","baseUrl":"https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1","apiKeyEnv":"ALIBABA_TOKEN_PLAN_API_KEY","models":["qwen3.8-max-preview","qwen-3.8-max","glm-5.2","deepseek-v4-pro"],"modelApi":{"qwen3.8-max-preview":"openai-responses","qwen-3.8-max":"openai-responses","glm-5.2":"openai-completions","deepseek-v4-pro":"openai-completions"},"compat":{"supportsDeveloperRole":false}}
 ]