acpx 0.17.1 → 0.19.0

package/dist/runtime.js

@@ -1,7 +1,7 @@
-import { C as textPrompt, D as findSession, F as resolveSessionRecord, L as assertPersistedKeyPolicy, P as readSessionRecord, R as parseSessionRecord, gt as extractAcpError, mt as writePrivateJsonFile, t as tryCancelOnRunningOwner, vt as isAcpResourceNotFoundError, z as serializeSessionRecordForDisk } from "./ipc-D2rstexT.js";
-import { A as setDesiredModeId, B as recordClientOperation, C as withConnectedSession, D as applyInitialModelSelection, E as applyConfigOptionsToRecord, F as createInitialSessionRecord, G as AcpClient, H as recordSessionUpdate, I as reconcileAgentSessionId, J as RequestedModelUnsupportedError, K as REQUESTED_MODEL_UNSUPPORTED_ERROR_CODE, L as cloneSessionAcpxState, M as sessionOptionsFromRecord, N as applyConversation, O as applyModelSelection, P as applyLifecycleSnapshotToRecord, R as cloneSessionConversation, T as applyConfigOptionSelection, U as trimConversationForRuntime, V as recordPromptSubmission, W as advertisedModelState, Y as isRequestedModelUnsupportedError, _ as cancelSessionPrompt, c as LiveSessionCheckpoint, ct as normalizeOutputError, h as ensureSession, it as assertControlAuthority, j as persistSessionOptions, k as applyRequestedModelIfAdvertised, l as runPromptTurn, ot as withTimeout, q as REQUESTED_MODEL_UNSUPPORTED_REASONS, r as sendSession, rt as TimeoutError, s as DISCARD_OUTPUT_FORMATTER, v as closeSession, w as connectAndLoadSession } from "./queue-owner-runtime-Dgv3e2Tp.js";
-import { D as normalizeAgentCommandInput, a as createAgentRegistry, i as DEFAULT_AGENT_NAME } from "./agent-registry-evUoJINz.js";
-import { t as watchSession } from "./watch-DxuXEc8n.js";
+import { D as textPrompt, H as parseSessionRecord, R as readSessionRecord, St as isAcpResourceNotFoundError, U as serializeSessionRecordForDisk, V as assertPersistedKeyPolicy, bt as extractAcpError, j as findSession, t as tryCancelOnRunningOwner, vt as writePrivateJsonFile, z as resolveSessionRecord } from "./ipc-fMgj5vrO.js";
+import { A as applyInitialModelSelection, B as cloneSessionAcpxState, C as setSessionModeOnOwner, D as connectAndLoadSession, E as withConnectedSession, F as sessionOptionsFromRecord, G as recordSessionUpdate, I as applyConversation, J as AcpClient, K as trimConversationForRuntime, L as applyLifecycleSnapshotToRecord, M as applyRequestedModelIfAdvertised, N as setDesiredModeId, O as applyConfigOptionSelection, P as persistSessionOptions, Q as isRequestedModelUnsupportedError, R as createInitialSessionRecord, T as setSessionModelOnOwner, U as recordClientOperation, V as cloneSessionConversation, W as recordPromptSubmission, X as REQUESTED_MODEL_UNSUPPORTED_REASONS, Y as REQUESTED_MODEL_UNSUPPORTED_ERROR_CODE, Z as RequestedModelUnsupportedError, _ as cancelSessionPrompt, c as LiveSessionCheckpoint, dt as normalizeOutputError, h as ensureSession, j as applyModelSelection, k as applyConfigOptionsToRecord, l as runPromptTurn, lt as withTimeout, ot as TimeoutError, q as advertisedModelState, r as sendSession, s as DISCARD_OUTPUT_FORMATTER, st as assertControlAuthority, v as closeSession, x as setSessionConfigOptionOnOwner, z as reconcileAgentSessionId } from "./queue-owner-runtime-CLwjMYNL.js";
+import { D as normalizeAgentCommandInput, a as createAgentRegistry, i as DEFAULT_AGENT_NAME } from "./agent-registry-Ct2yWPW7.js";
+import { t as watchSession } from "./watch-DH-zXQH2.js";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -22,6 +22,35 @@ function isAcpRuntimeError(value) {
 	return value instanceof AcpRuntimeError;
 }
 //#endregion
+//#region src/runtime/engine/controls.ts
+function advertisedConfigOptionIds(record) {
+	const configOptions = record?.acpx?.config_options;
+	if (!configOptions) return;
+	return new Set(configOptions.map((option) => option.id).filter((id) => typeof id === "string" && id.trim().length > 0));
+}
+/** Caller-owned controls and the config option keys the session last advertised. */
+function capabilitiesFromRecord(record) {
+	const advertisedIds = advertisedConfigOptionIds(record);
+	return {
+		controls: [
+			"session/set_mode",
+			"session/set_model",
+			"session/set_config_option",
+			"session/status"
+		],
+		...advertisedIds?.size ? { configOptionKeys: [...advertisedIds] } : {}
+	};
+}
+function resolveSupportedConfigOptionId(record, configId) {
+	const advertisedIds = advertisedConfigOptionIds(record);
+	if (!advertisedIds) return configId;
+	if (advertisedIds.has(configId)) return configId;
+	if (configId === "thinking" && advertisedIds.has("effort")) return "effort";
+	const supported = [...advertisedIds].toSorted();
+	const supportedText = supported.length > 0 ? supported.join(", ") : "none";
+	throw new AcpRuntimeError("ACP_BACKEND_UNSUPPORTED_CONTROL", `ACP session ${record.acpxRecordId} does not advertise config option '${configId}'. Supported config options: ${supportedText}.`);
+}
+//#endregion
 //#region src/runtime/public/shared.ts
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -333,6 +362,7 @@ const TOOL_KINDS = /* @__PURE__ */ new Set([
 	"execute",
 	"fetch",
 	"think",
+	"switch_mode",
 	"other"
 ]);
 function createToolCallEvent(params) {
@@ -673,6 +703,8 @@ function createProbeClient(options, agentName, agentCommand, deps) {
 		permissionMode: options.permissionMode,
 		nonInteractivePermissions: options.nonInteractivePermissions,
 		permissionPolicy: options.permissionPolicy,
+		fs: false,
+		terminal: false,
 		processLifecycle: options.processLifecycle,
 		processLaunchScope: {
 			kind: "runtime-probe",
@@ -833,10 +865,15 @@ var AsyncEventQueue = class {
 		return await waiter.promise;
 	}
 	async *iterate() {
-		while (true) {
-			const next = await this.next();
-			if (!next) return;
-			yield next;
+		try {
+			while (true) {
+				const next = await this.next();
+				if (!next) return;
+				yield next;
+			}
+		} finally {
+			this.close();
+			this.clear();
 		}
 	}
 };
@@ -918,20 +955,6 @@ function createRecordId(sessionKey, mode) {
 function resumePolicyForSessionMode(mode) {
 	return mode === "persistent" ? "same-session-only" : "allow-new";
 }
-function advertisedConfigOptionIds(record) {
-	const configOptions = record.acpx?.config_options;
-	if (!configOptions) return;
-	return new Set(configOptions.map((option) => option.id).filter((id) => typeof id === "string" && id.trim().length > 0));
-}
-function resolveSupportedConfigOptionId(record, configId) {
-	const advertisedIds = advertisedConfigOptionIds(record);
-	if (!advertisedIds) return configId;
-	if (advertisedIds.has(configId)) return configId;
-	if (configId === "thinking" && advertisedIds.has("effort")) return "effort";
-	const supported = [...advertisedIds].toSorted();
-	const supportedText = supported.length > 0 ? supported.join(", ") : "none";
-	throw new AcpRuntimeError("ACP_BACKEND_UNSUPPORTED_CONTROL", `ACP session ${record.acpxRecordId} does not advertise config option '${configId}'. Supported config options: ${supportedText}.`);
-}
 async function startRuntimeClient(client, agent, timeoutMs) {
 	try {
 		await withTimeout(client.start(), timeoutMs);
@@ -969,6 +992,7 @@ var AcpRuntimeManager = class {
 	options;
 	deps;
 	activeControllers = /* @__PURE__ */ new Map();
+	controlSessionRecords = /* @__PURE__ */ new Map();
 	retainedSessionOwners = /* @__PURE__ */ new Map();
 	retiringSessionOwners = /* @__PURE__ */ new Set();
 	pendingOneShotRecordIds = /* @__PURE__ */ new Map();
@@ -1085,6 +1109,7 @@ var AcpRuntimeManager = class {
 	createSessionOwner(input) {
 		const owner = {
 			...input,
+			checkpoint: new LiveSessionCheckpoint({ save: async () => this.saveSessionOwner(owner) }),
 			bufferSessionUpdates: false,
 			pendingSessionUpdates: []
 		};
@@ -1094,13 +1119,26 @@ var AcpRuntimeManager = class {
 		});
 		return owner;
 	}
+	async saveSessionOwner(owner) {
+		if (!owner.recordId) return;
+		const active = owner.activeTurn?.turn;
+		const target = active ?? owner.projection;
+		if (!target) return;
+		const { record, conversation } = target;
+		if (active?.connected) record.acpx = active.acpxState;
+		record.lastUsedAt = isoNow();
+		applyConversation(record, conversation);
+		applyLifecycleSnapshotToRecord(record, owner.client.getAgentLifecycleSnapshot());
+		await this.refreshClosedState(record);
+		await this.options.sessionStore.save(record);
+	}
 	routeOwnedSessionUpdate(owner, notification) {
 		const active = owner.activeTurn;
 		if (active) {
 			const { task, turn } = active;
 			if (turn.connected) {
 				turn.acpxState = recordSessionUpdate(turn.conversation, turn.acpxState, notification);
-				turn.liveCheckpoint.request();
+				owner.checkpoint.request();
 			} else turn.record.acpx = recordSessionUpdate(turn.conversation, turn.record.acpx, notification);
 			trimConversationForRuntime(turn.conversation);
 			this.emitRuntimeTurnEvent(task, {
@@ -1121,7 +1159,7 @@ var AcpRuntimeManager = class {
 		}
 		projection.record.acpx = recordSessionUpdate(projection.conversation, projection.record.acpx, notification);
 		trimConversationForRuntime(projection.conversation);
-		projection.checkpoint.request();
+		owner.checkpoint.request();
 	}
 	routeOwnedClientOperation(owner, operation) {
 		const active = owner.activeTurn;
@@ -1129,7 +1167,7 @@ var AcpRuntimeManager = class {
 		const { task, turn } = active;
 		if (turn.connected) {
 			turn.acpxState = recordClientOperation(turn.conversation, turn.acpxState, operation);
-			turn.liveCheckpoint.request();
+			owner.checkpoint.request();
 		} else turn.record.acpx = recordClientOperation(turn.conversation, turn.record.acpx, operation);
 		trimConversationForRuntime(turn.conversation);
 		this.emitRuntimeTurnEvent(task, {
@@ -1141,15 +1179,7 @@ var AcpRuntimeManager = class {
 		record.acpx = acpxState;
 		owner.projection = {
 			record,
-			conversation,
-			checkpoint: new LiveSessionCheckpoint({ save: async () => {
-				if (!owner.recordId) return;
-				record.lastUsedAt = isoNow();
-				applyConversation(record, conversation);
-				applyLifecycleSnapshotToRecord(record, owner.client.getAgentLifecycleSnapshot());
-				await this.refreshClosedState(record);
-				await this.options.sessionStore.save(record);
-			} })
+			conversation
 		};
 		owner.activeTurn = void 0;
 		this.drainPendingSessionUpdates(owner);
@@ -1159,7 +1189,7 @@ var AcpRuntimeManager = class {
 	}
 	async flushSessionOwner(owner) {
 		await owner.client.waitForSessionUpdatesIdle?.().catch(() => {});
-		await owner.projection?.checkpoint.flush();
+		await owner.checkpoint.flush();
 	}
 	removeRetainedSessionOwner(owner) {
 		if (owner.recordId && this.retainedSessionOwners.get(owner.recordId) === owner) this.retainedSessionOwners.delete(owner.recordId);
@@ -1190,7 +1220,7 @@ var AcpRuntimeManager = class {
 		await this.closeClient(owner.client).catch(() => {
 			this.retiringSessionOwners.add(owner);
 		});
-		await owner.projection?.checkpoint.flush().catch(() => {});
+		await owner.checkpoint.flush().catch(() => {});
 		try {
 			owner.client.clearEventHandlers();
 		} catch {}
@@ -1213,19 +1243,15 @@ var AcpRuntimeManager = class {
 		const latest = await this.options.sessionStore.load(record.acpxRecordId).catch(() => void 0);
 		record.closed = true;
 		record.closedAt = latest?.closedAt ?? record.closedAt ?? isoNow();
-		if (latest?.acpx) record.acpx = {
+		if (latest?.acpx?.reset_on_next_ensure === true) record.acpx = {
 			...record.acpx,
-			...latest.acpx
+			reset_on_next_ensure: true
 		};
 		return true;
 	}
 	async retainPersistentSessionOwnerAfterTurn(input) {
-		const { record, owner, conversation, acpxState } = input;
-		if (!this.canRetainPersistentSessionOwner(owner, record)) {
-			owner.activeTurn = void 0;
-			return false;
-		}
-		this.attachIdleProjection(owner, record, conversation, acpxState);
+		const { record, owner } = input;
+		if (!this.canRetainPersistentSessionOwner(owner, record)) return false;
 		const previousOwner = this.retainedSessionOwners.get(record.acpxRecordId);
 		this.retainedSessionOwners.set(record.acpxRecordId, owner);
 		if (previousOwner && previousOwner !== owner) {
@@ -1262,7 +1288,13 @@ var AcpRuntimeManager = class {
 			onPermissionRequest
 		};
 	}
-	async withRuntimeControlSession(record, sessionMode, run, replacingConfigOption, authority) {
+	resolveClientCapabilities() {
+		return {
+			fs: this.options.fs,
+			terminal: this.options.terminal
+		};
+	}
+	async withRuntimeControlSession(record, sessionMode, run, replayOptions, authority) {
 		await this.retrySessionCleanup(record.acpxRecordId);
 		assertControlAuthority(authority);
 		const owner = await this.readRetainedSessionOwner(record, { consume: false });
@@ -1276,20 +1308,27 @@ var AcpRuntimeManager = class {
 					record: ownedRecord
 				});
 				this.refreshOwnedRecordLifecycle(owner, ownedRecord);
-				return {
-					value,
-					record: ownedRecord
-				};
+				await owner.checkpoint.checkpoint();
+				return value;
 			} finally {
 				await this.flushSessionOwner(owner);
 			}
 		}
 		let controlClient;
+		let controlledRecord = record;
+		const checkpoint = new LiveSessionCheckpoint({ save: async () => this.options.sessionStore.save(controlledRecord) });
 		try {
-			const result = await withConnectedSession({
+			const result = await settleAttempt(async () => withConnectedSession({
 				sessionRecordId: record.acpxRecordId,
-				loadRecord: async (sessionRecordId) => await this.requireRecord(sessionRecordId),
-				saveRecord: async (connectedRecord) => await this.options.sessionStore.save(connectedRecord),
+				loadRecord: async (sessionRecordId) => {
+					controlledRecord = await this.requireRecord(sessionRecordId);
+					this.controlSessionRecords.set(sessionRecordId, {
+						record: controlledRecord,
+						checkpoint
+					});
+					return controlledRecord;
+				},
+				saveRecord: async () => checkpoint.checkpoint(),
 				createClient: (options) => controlClient = this.createClient({
 					...options,
 					processLifecycle: this.options.processLifecycle,
@@ -1306,19 +1345,23 @@ var AcpRuntimeManager = class {
 					...record,
 					sessionKey: record.name ?? record.acpxRecordId
 				}),
+				...this.resolveClientCapabilities(),
 				elicitationModes: this.options.elicitationModes,
 				verbose: this.options.verbose,
 				timeoutMs: this.options.timeoutMs,
 				resumePolicy: resumePolicyForSessionMode(sessionMode),
-				replacingConfigOption,
+				replacingMode: replayOptions?.replacingMode,
+				replacingConfigOption: replayOptions?.replacingConfigOption,
 				authority,
 				run
-			});
-			return {
-				value: result.value,
-				record: result.record
-			};
+			}));
+			this.controlSessionRecords.delete(record.acpxRecordId);
+			const flushed = await settleAttempt(async () => checkpoint.flush());
+			if (!result.ok) throw result.error;
+			if (!flushed.ok) throw flushed.error;
+			return result.value.value;
 		} finally {
+			this.controlSessionRecords.delete(record.acpxRecordId);
 			if (controlClient) this.liveClients.delete(controlClient);
 		}
 	}
@@ -1340,6 +1383,13 @@ var AcpRuntimeManager = class {
 	async withManagerLock(locks, key, run, authority) {
 		this.assertOpen();
 		assertControlAuthority(authority);
+		return await this.serializeManagerOperation(locks, key, async () => {
+			this.assertOpen();
+			assertControlAuthority(authority);
+			return await run();
+		});
+	}
+	async serializeManagerOperation(locks, key, run) {
 		const previous = locks.get(key) ?? Promise.resolve();
 		let release;
 		const gate = new Promise((resolve) => {
@@ -1349,8 +1399,6 @@ var AcpRuntimeManager = class {
 		locks.set(key, tail);
 		await previous;
 		try {
-			this.assertOpen();
-			assertControlAuthority(authority);
 			return await run();
 		} finally {
 			release();
@@ -1365,8 +1413,26 @@ var AcpRuntimeManager = class {
 			agentCommand,
 			agentArgv
 		};
+		if (input.mode !== "persistent") return await this.acquireRuntimeSession(input, agent);
+		const compatible = await this.reuseCompatiblePersistentSession(input, agent);
+		if (compatible) return compatible;
+		this.assertRuntimeSessionIdle(input.sessionKey);
+		return await this.withManagerLock(this.runtimeOperationLocks, input.sessionKey, async () => this.acquireRuntimeSession(input, agent));
+	}
+	async reuseCompatiblePersistentSession(input, agent) {
+		const controlled = this.controlSessionRecords.get(input.sessionKey);
+		const record = controlled ? controlled.record : await this.findSession(input.sessionKey);
+		if (!record || this.closingActiveRecords.has(input.sessionKey) || !shouldReuseExistingRecord(record, {
+			...agent,
+			resumeSessionId: input.resumeSessionId
+		})) return;
+		if (!record.closed) return record;
+		if (!controlled || this.sessionTasks.has(input.sessionKey)) return;
+		return await this.reuseRuntimeSession({ record }, controlled.checkpoint);
+	}
+	async acquireRuntimeSession(input, agent) {
 		const existing = await this.loadExistingRuntimeSession(input);
-		if (existing && this.canReuseRuntimeSession(input, agent, existing)) return await this.reuseRuntimeSession(existing.record);
+		if (existing && this.canReuseRuntimeSession(input, agent, existing)) return await this.reuseRuntimeSession(existing);
 		await this.closeConflictingPersistentSession(input, existing?.owner);
 		return await this.createOwnedRuntimeSession(input, agent);
 	}
@@ -1397,17 +1463,26 @@ var AcpRuntimeManager = class {
 			resumeSessionId: input.resumeSessionId
 		})) return false;
 		if (input.mode === "persistent") return true;
-		return Boolean(existing.owner && isDeepStrictEqual(sessionOptionsFromRecord(existing.record), input.sessionOptions));
+		return Boolean(existing.owner && !existing.record.closed && this.pendingOneShotRecordIds.get(input.sessionKey) === existing.record.acpxRecordId && this.retainedSessionOwners.get(existing.record.acpxRecordId) === existing.owner && isDeepStrictEqual(sessionOptionsFromRecord(existing.record), input.sessionOptions));
+	}
+	assertRuntimeSessionIdle(recordId) {
+		if (this.sessionTasks.has(recordId) || this.runtimeOperationLocks.has(recordId)) throw new AcpRuntimeError("ACP_SESSION_INIT_FAILED", `Cannot ensure session ${recordId} with incompatible or closing state while its work is unfinished. Wait for existing work to finish or use a different session key.`);
 	}
-	async reuseRuntimeSession(record) {
+	async reuseRuntimeSession({ record, owner }, checkpoint = owner?.checkpoint) {
+		if (!record.closed && !this.closingActiveRecords.has(record.acpxRecordId)) return record;
 		record.closed = false;
 		record.closedAt = void 0;
 		this.closingActiveRecords.delete(record.acpxRecordId);
-		await this.options.sessionStore.save(record);
+		if (checkpoint) await checkpoint.checkpoint();
+		else await this.options.sessionStore.save(record);
 		return record;
 	}
 	async closeConflictingPersistentSession(input, owner) {
-		if (input.mode === "persistent" && owner?.recordId) await this.closeRetainedSessionOwner(owner.recordId);
+		if (input.mode === "persistent" && owner?.recordId) {
+			this.removeRetainedSessionOwner(owner);
+			this.retiringSessionOwners.add(owner);
+			await this.retrySessionCleanup(owner.recordId);
+		}
 	}
 	async createOwnedRuntimeSession(input, agent) {
 		const { cwd, agentCommand, agentArgv } = agent;
@@ -1423,6 +1498,7 @@ var AcpRuntimeManager = class {
 				...agent,
 				sessionKey: input.sessionKey
 			}),
+			...this.resolveClientCapabilities(),
 			elicitationModes: this.options.elicitationModes,
 			processLifecycle: this.options.processLifecycle,
 			processLaunchScope: {
@@ -1493,7 +1569,7 @@ var AcpRuntimeManager = class {
 	}
 	async retainInitializedSessionOwner(owner, record) {
 		owner.recordId = record.acpxRecordId;
-		await owner.projection?.checkpoint.checkpoint();
+		await owner.checkpoint.checkpoint();
 		this.assertOpen();
 		const previousOwner = this.retainedSessionOwners.get(record.acpxRecordId);
 		this.retainedSessionOwners.set(record.acpxRecordId, owner);
@@ -1571,7 +1647,9 @@ var AcpRuntimeManager = class {
 	}
 	async closeRetainedOneShotHandle(handle) {
 		const recordId = handle.acpxRecordId ?? handle.sessionKey;
-		if (this.retainedSessionOwners.get(recordId)?.mode === "oneshot") await this.closeRetainedSessionOwner(recordId);
+		await this.serializeManagerOperation(this.runtimeOperationLocks, recordId, async () => {
+			if (this.retainedSessionOwners.get(recordId)?.mode === "oneshot") await this.closeRetainedSessionOwner(recordId);
+		});
 	}
 	async runRuntimeTurnTask(task) {
 		let turn;
@@ -1594,7 +1672,7 @@ var AcpRuntimeManager = class {
 				};
 				else {
 					const response = await this.runRuntimePrompt(task, turn, sessionId);
-					await this.saveCompletedRuntimeTurn(turn);
+					this.updateCompletedRuntimeTurn(turn);
 					terminalResult = {
 						status: response.stopReason === "cancelled" ? "cancelled" : "completed",
 						...response.stopReason ? { stopReason: response.stopReason } : {},
@@ -1605,7 +1683,7 @@ var AcpRuntimeManager = class {
 		} catch (error) {
 			terminalResult = this.handleRuntimeTurnFailure(task, error);
 		}
-		const finalization = await settleAttempt(async () => this.finalizeRuntimeTurn(task, turn));
+		const finalization = await settleAttempt(async () => this.serializeManagerOperation(this.runtimeOperationLocks, task.input.handle.acpxRecordId ?? task.input.handle.sessionKey, async () => this.finalizeRuntimeTurn(task, turn)));
 		if (!finalization.ok) {
 			task.settleResult(this.failRuntimeTurn(task, finalization.error));
 			throw finalization.error;
@@ -1613,22 +1691,18 @@ var AcpRuntimeManager = class {
 		task.settleResult(terminalResult);
 	}
 	async runRuntimePrompt(task, turn, sessionId) {
-		try {
-			return await runPromptTurn({
-				client: turn.client,
-				sessionId,
-				prompt: task.promptInput,
-				timeoutMs: task.input.timeoutMs ?? this.options.timeoutMs,
-				conversation: turn.conversation,
-				promptMessageId: turn.promptMessageId,
-				onPromptRequestWritten: () => task.promptStarted.resolve(),
-				onElicitation: task.input.onElicitation,
-				onPermissionRequest: task.input.onPermissionRequest,
-				authority: task.input
-			});
-		} finally {
-			turn.client.endPromptElicitation?.(sessionId);
-		}
+		return await runPromptTurn({
+			client: turn.client,
+			sessionId,
+			prompt: task.promptInput,
+			timeoutMs: task.input.timeoutMs ?? this.options.timeoutMs,
+			conversation: turn.conversation,
+			promptMessageId: turn.promptMessageId,
+			onPromptRequestWritten: () => task.promptStarted.resolve(),
+			onElicitation: task.input.onElicitation,
+			onPermissionRequest: task.input.onPermissionRequest,
+			authority: task.input
+		});
 	}
 	async prepareRuntimeTurn(task) {
 		const recordId = task.input.handle.acpxRecordId ?? task.input.handle.sessionKey;
@@ -1688,13 +1762,19 @@ var AcpRuntimeManager = class {
 		let record = await this.requireRecord(recordId);
 		const retainedOwner = await this.readRetainedSessionOwner(record, { consume: false });
 		if (!retainedOwner) return { record };
-		const projection = retainedOwner.projection;
-		if (projection) record = structuredClone(projection.record);
 		retainedOwner.bufferSessionUpdates = true;
-		return {
-			record,
-			retainedOwner
-		};
+		try {
+			await retainedOwner.checkpoint.flush();
+			const projection = retainedOwner.projection;
+			if (projection) record = structuredClone(projection.record);
+			return {
+				record,
+				retainedOwner
+			};
+		} catch (error) {
+			this.restoreBufferedSessionOwner(retainedOwner);
+			throw error;
+		}
 	}
 	restoreBufferedSessionOwner(owner) {
 		if (!owner) return;
@@ -1710,18 +1790,16 @@ var AcpRuntimeManager = class {
 	}
 	createRunningRuntimeTurn(input) {
 		const { record, conversation, acpxState, client, owner, connected, promptMessageId } = input;
-		const turn = {
+		return {
 			record,
 			conversation,
 			acpxState,
-			liveCheckpoint: this.createRuntimeTurnCheckpoint(record, conversation, () => turn.acpxState),
 			client,
 			owner,
 			connected,
 			promptMessageId,
 			activeSessionId: record.acpSessionId
 		};
-		return turn;
 	}
 	activateRuntimeTurn(task, turn) {
 		const { owner, record } = turn;
@@ -1750,6 +1828,7 @@ var AcpRuntimeManager = class {
 				...record,
 				sessionKey: record.name ?? record.acpxRecordId
 			}),
+			...this.resolveClientCapabilities(),
 			elicitationModes: this.options.elicitationModes,
 			processLifecycle: this.options.processLifecycle,
 			processLaunchScope: {
@@ -1760,15 +1839,6 @@ var AcpRuntimeManager = class {
 			sessionOptions: sessionOptionsFromRecord(record)
 		});
 	}
-	createRuntimeTurnCheckpoint(record, conversation, readAcpxState) {
-		return new LiveSessionCheckpoint({ save: async () => {
-			record.lastUsedAt = isoNow();
-			record.acpx = readAcpxState();
-			applyConversation(record, conversation);
-			await this.refreshClosedState(record);
-			await this.options.sessionStore.save(record);
-		} });
-	}
 	buildRuntimeTurnController(task, turn) {
 		return {
 			hasActivePrompt: () => turn.client.hasActivePrompt(),
@@ -1779,12 +1849,14 @@ var AcpRuntimeManager = class {
 				const nextState = cloneSessionAcpxState(turn.acpxState) ?? {};
 				nextState.desired_mode_id = modeId;
 				turn.acpxState = nextState;
+				await turn.owner.checkpoint.checkpoint();
 			},
 			setSessionModel: async (modelId, authority) => {
 				await this.waitForRuntimeControlSession(task, turn);
 				const models = advertisedModelState(turn.acpxState);
 				const response = await turn.client.setSessionModel(turn.activeSessionId, modelId, models, authority);
 				turn.acpxState = applyModelSelection(turn.acpxState, modelId, response);
+				await turn.owner.checkpoint.checkpoint();
 				return response;
 			},
 			setSessionConfigOption: async (configId, value, authority) => {
@@ -1809,9 +1881,10 @@ var AcpRuntimeManager = class {
 			...turn.record,
 			acpx: turn.acpxState ?? void 0
 		}, configId);
-		const modelConfigId = advertisedModelState(turn.acpxState)?.configId;
-		const response = await turn.client.setSessionConfigOption(turn.activeSessionId, resolvedConfigId, value, authority);
-		turn.acpxState = applyConfigOptionSelection(turn.acpxState, resolvedConfigId, value, response, modelConfigId);
+		const models = advertisedModelState(turn.acpxState);
+		const response = await turn.client.setSessionConfigOption(turn.activeSessionId, resolvedConfigId, value, models, authority);
+		turn.acpxState = applyConfigOptionSelection(turn.acpxState, resolvedConfigId, value, response, models?.configId);
+		await turn.owner.checkpoint.checkpoint();
 		return {
 			configId: resolvedConfigId,
 			response
@@ -1860,7 +1933,7 @@ var AcpRuntimeManager = class {
 		turn.record.closed = false;
 		turn.record.closedAt = void 0;
 		turn.record.lastUsedAt = isoNow();
-		await turn.liveCheckpoint.checkpoint();
+		await turn.owner.checkpoint.checkpoint();
 	}
 	cancelRuntimeTurnBeforePrompt(task) {
 		if (!task.state.pendingCancel && !task.input.signal?.aborted) return false;
@@ -1868,15 +1941,11 @@ var AcpRuntimeManager = class {
 		task.promptStarted.reject(/* @__PURE__ */ new Error("ACP turn cancelled before prompt submission."));
 		return true;
 	}
-	async saveCompletedRuntimeTurn(turn) {
+	updateCompletedRuntimeTurn(turn) {
 		turn.record.acpSessionId = turn.activeSessionId;
 		reconcileAgentSessionId(turn.record, turn.record.agentSessionId);
 		turn.record.protocolVersion = turn.client.initializeResult?.protocolVersion;
 		turn.record.agentCapabilities = turn.client.initializeResult?.agentCapabilities;
-		turn.record.acpx = turn.acpxState;
-		applyConversation(turn.record, turn.conversation);
-		applyLifecycleSnapshotToRecord(turn.record, turn.client.getAgentLifecycleSnapshot());
-		await this.options.sessionStore.save(turn.record);
 	}
 	handleRuntimeTurnFailure(task, error) {
 		if (!task.input.signal?.aborted || error !== task.input.signal.reason) return this.failRuntimeTurn(task, error);
@@ -1919,13 +1988,24 @@ var AcpRuntimeManager = class {
 	discardRetainedRuntimeTurnOwner(turn) {
 		if (turn) {
 			this.removeRetainedSessionOwner(turn.owner);
-			turn.owner.activeTurn = void 0;
+			this.attachFinalRuntimeProjection(turn);
 		}
 	}
+	attachFinalRuntimeProjection(turn) {
+		const current = turn.connected ? turn.acpxState : turn.record.acpx;
+		const state = turn.record.acpx?.reset_on_next_ensure === true ? {
+			...current,
+			reset_on_next_ensure: true
+		} : current;
+		this.attachIdleProjection(turn.owner, turn.record, turn.conversation, state);
+	}
 	async closeRuntimeTurnClient(turn, pooled) {
 		if (!turn || pooled) return;
-		turn.owner.activeTurn = void 0;
-		const failure = firstFailedAttempt([await settleAttempt(() => turn.client.clearEventHandlers()), await settleAttempt(async () => this.closeClient(turn.client))]);
+		const failure = firstFailedAttempt([
+			await settleAttempt(() => turn.client.clearEventHandlers()),
+			await settleAttempt(async () => this.closeClient(turn.client)),
+			await settleAttempt(async () => this.flushSessionOwner(turn.owner))
+		]);
 		if (failure) {
 			this.retiringSessionOwners.add(turn.owner);
 			throw failure.error;
@@ -1940,19 +2020,12 @@ var AcpRuntimeManager = class {
 	}
 	async finalizeRuntimeTurnRecord(turn) {
 		if (!turn.connected) turn.acpxState = cloneSessionAcpxState(turn.record.acpx);
-		applyLifecycleSnapshotToRecord(turn.record, turn.client.getAgentLifecycleSnapshot());
-		turn.record.acpx = turn.acpxState;
-		applyConversation(turn.record, turn.conversation);
-		turn.record.lastUsedAt = isoNow();
-		await turn.liveCheckpoint.flush();
-		const closed = await this.refreshClosedState(turn.record);
-		await this.options.sessionStore.save(turn.record);
-		if (closed || !turn.connected) return false;
+		await turn.owner.checkpoint.checkpoint();
+		this.attachFinalRuntimeProjection(turn);
+		if (turn.record.closed || !turn.connected) return false;
 		return await this.retainPersistentSessionOwnerAfterTurn({
 			record: turn.record,
-			owner: turn.owner,
-			conversation: turn.conversation,
-			acpxState: turn.acpxState
+			owner: turn.owner
 		});
 	}
 	async *runTurn(input) {
@@ -1978,13 +2051,14 @@ var AcpRuntimeManager = class {
 		const record = await this.requireRecord(handle.acpxRecordId ?? handle.sessionKey);
 		assertControlAuthority(authority);
 		const controller = this.activeControllers.get(record.acpxRecordId);
-		let targetRecord = record;
-		if (controller) await controller.setSessionMode(mode, authority);
-		else targetRecord = (await this.withRuntimeControlSession(record, sessionMode, async ({ client, sessionId }) => {
+		if (controller) {
+			await controller.setSessionMode(mode, authority);
+			return;
+		}
+		await this.withRuntimeControlSession(record, sessionMode, async ({ client, sessionId, record: connectedRecord }) => {
 			await client.setSessionMode(sessionId, mode, authority);
-		}, void 0, authority)).record;
-		setDesiredModeId(targetRecord, mode);
-		await this.options.sessionStore.save(targetRecord);
+			setDesiredModeId(connectedRecord, mode);
+		}, { replacingMode: true }, authority);
 	}
 	async setModel(handle, model, sessionMode = "persistent", authority) {
 		const recordId = handle.acpxRecordId ?? handle.sessionKey;
@@ -1995,16 +2069,13 @@ var AcpRuntimeManager = class {
 		assertControlAuthority(authority);
 		const controller = this.activeControllers.get(record.acpxRecordId);
 		if (controller) {
-			const response = await controller.setSessionModel(model, authority);
-			record.acpx = applyModelSelection(record.acpx, model, response);
-			await this.options.sessionStore.save(record);
+			await controller.setSessionModel(model, authority);
 			return;
 		}
-		const result = await this.withRuntimeControlSession(record, sessionMode, async ({ client, sessionId, record: connectedRecord }) => {
+		await this.withRuntimeControlSession(record, sessionMode, async ({ client, sessionId, record: connectedRecord }) => {
 			const response = await client.setSessionModel(sessionId, model, advertisedModelState(connectedRecord.acpx), authority);
 			connectedRecord.acpx = applyModelSelection(connectedRecord.acpx, model, response);
-		}, { key: "model" }, authority);
-		await this.options.sessionStore.save(result.record);
+		}, { replacingConfigOption: { key: "model" } }, authority);
 	}
 	async setConfigOption(handle, key, value, sessionMode = "persistent", authority) {
 		const recordId = handle.acpxRecordId ?? handle.sessionKey;
@@ -2015,23 +2086,19 @@ var AcpRuntimeManager = class {
 		assertControlAuthority(authority);
 		const controller = this.activeControllers.get(record.acpxRecordId);
 		if (controller) {
-			const { configId, response } = await controller.setResolvedSessionConfigOption(key, value, authority);
-			record.acpx = applyConfigOptionSelection(record.acpx, configId, value, response);
-			await this.options.sessionStore.save(record);
+			const { response } = await controller.setResolvedSessionConfigOption(key, value, authority);
 			return response;
 		}
-		const result = await this.withRuntimeControlSession(record, sessionMode, async ({ client, sessionId, record: connectedRecord }) => {
+		return await this.withRuntimeControlSession(record, sessionMode, async ({ client, sessionId, record: connectedRecord }) => {
 			const configId = resolveSupportedConfigOptionId(connectedRecord, key);
-			const modelConfigId = advertisedModelState(connectedRecord.acpx)?.configId;
-			const response = await client.setSessionConfigOption(sessionId, configId, value, authority);
-			connectedRecord.acpx = applyConfigOptionSelection(connectedRecord.acpx, configId, value, response, modelConfigId);
+			const models = advertisedModelState(connectedRecord.acpx);
+			const response = await client.setSessionConfigOption(sessionId, configId, value, models, authority);
+			connectedRecord.acpx = applyConfigOptionSelection(connectedRecord.acpx, configId, value, response, models?.configId);
 			return response;
-		}, {
+		}, { replacingConfigOption: {
 			key,
 			resolve: (connectedRecord) => resolveSupportedConfigOptionId(connectedRecord, key)
-		}, authority);
-		await this.options.sessionStore.save(result.record);
-		return result.value;
+		} }, authority);
 	}
 	async cancel(handle) {
 		await this.activeControllers.get(handle.acpxRecordId ?? handle.sessionKey)?.requestCancelActivePrompt();
@@ -2104,7 +2171,8 @@ var AcpRuntimeManager = class {
 				if (connection.owner) await this.flushSessionOwner(connection.owner);
 			}),
 			await settleAttempt(() => connection.owner?.client.clearEventHandlers()),
-			await settleAttempt(async () => this.closeClient(connection.client))
+			await settleAttempt(async () => this.closeClient(connection.client)),
+			await settleAttempt(async () => connection.owner?.checkpoint.flush())
 		]);
 		if (failure) throw failure.error;
 	}
@@ -2169,7 +2237,8 @@ var FileSessionStore = class {
 		} catch {
 			return;
 		}
-		return parseSessionRecord(parsed) ?? void 0;
+		const record = parseSessionRecord(parsed);
+		return record?.acpxRecordId === sessionId ? record : void 0;
 	}
 	async save(record) {
 		const persisted = serializeSessionRecordForDisk(record);
@@ -2239,6 +2308,16 @@ function sharedRecordId(handle) {
 	if (handle.backend !== SHARED_BACKEND || !handle.acpxRecordId) return invalidOption("A shared runtime requires a handle from a shared session.");
 	return handle.acpxRecordId;
 }
+/**
+* Shared controls are owner-only. Falling back to a direct connection would
+* start a second adapter connection for a session another process owns, and
+* that path may create a fresh provider session when the saved one no longer
+* loads. Shared turns already refuse that trade; controls refuse it too.
+*/
+function requireOwnerDispatch(result, control) {
+	if (result === void 0) throw new AcpRuntimeError("ACP_BACKEND_UNAVAILABLE", `No running owner holds this shared session, so ${control} was not sent. Submit a turn to start an owner, or apply the change with the equivalent acpx command, which connects directly instead of starting one.`);
+	return result;
+}
 function turnFailure(error) {
 	const normalized = normalizeOutputError(error, {
 		defaultCode: "RUNTIME",
@@ -2264,6 +2343,7 @@ var SharedAcpRuntime = class {
 	options;
 	disconnect = new AbortController();
 	pending = /* @__PURE__ */ new Set();
+	controlChains = /* @__PURE__ */ new Map();
 	constructor(options) {
 		for (const name of [
 			"sessionStore",
@@ -2272,7 +2352,9 @@ var SharedAcpRuntime = class {
 			"sessionPermissions",
 			"processLifecycle",
 			"onPermissionRequest",
-			"elicitationModes"
+			"elicitationModes",
+			"fs",
+			"terminal"
 		]) if (Object.hasOwn(options, name)) invalidOption(`${name} belongs to the in-process runtime and is not supported by shared sessions.`);
 		this.options = {
 			...options,
@@ -2414,6 +2496,72 @@ var SharedAcpRuntime = class {
 		this.assertOpen();
 		return runtimeStatusFromRecord(await resolveSessionRecord(sharedRecordId(input.handle)));
 	}
+	async getCapabilities(input) {
+		this.assertOpen();
+		if (!input?.handle) return capabilitiesFromRecord(void 0);
+		return capabilitiesFromRecord(await readSessionRecord(sharedRecordId(input.handle)));
+	}
+	/**
+	* Preserves this client's control order, including caller-side persistence
+	* when talking to older owners. Updated owners checkpoint accepted controls
+	* themselves; serialization here cannot coordinate other legacy callers.
+	*/
+	chainControl(sessionId, run) {
+		const result = (this.controlChains.get(sessionId) ?? Promise.resolve()).then(run, run);
+		const chained = result.then(() => void 0, () => void 0);
+		this.controlChains.set(sessionId, chained);
+		chained.then(() => {
+			if (this.controlChains.get(sessionId) === chained) this.controlChains.delete(sessionId);
+		});
+		return result;
+	}
+	/**
+	* Checks this client's authority locally, then hands the control to the
+	* running owner. The check gates this client's dispatch only; it cannot gate
+	* controls other clients of the same owner send, and it cannot recall a
+	* control the owner already accepted.
+	*/
+	async dispatchControl(input, control, send) {
+		this.assertOpen();
+		const sessionId = sharedRecordId(input.handle);
+		const assertAuthority = () => {
+			this.assertOpen();
+			assertControlAuthority(input);
+		};
+		return await this.track(this.chainControl(sessionId, async () => {
+			assertAuthority();
+			return requireOwnerDispatch(await send(sessionId, assertAuthority), control);
+		}));
+	}
+	async setMode(input) {
+		await this.dispatchControl(input, "session/set_mode", async (sessionId, assertAuthority) => setSessionModeOnOwner({
+			sessionId,
+			modeId: input.mode,
+			timeoutMs: this.options.timeoutMs,
+			assertDispatch: assertAuthority
+		}));
+	}
+	async setModel(input) {
+		await this.dispatchControl(input, "session/set_model", async (sessionId, assertAuthority) => setSessionModelOnOwner({
+			sessionId,
+			modelId: input.model,
+			timeoutMs: this.options.timeoutMs,
+			assertDispatch: assertAuthority
+		}));
+	}
+	async setConfigOption(input) {
+		return (await this.dispatchControl(input, "session/set_config_option", async (sessionId, assertAuthority) => {
+			const configId = resolveSupportedConfigOptionId(await resolveSessionRecord(sessionId), input.key);
+			assertAuthority();
+			return await setSessionConfigOptionOnOwner({
+				sessionId,
+				configId,
+				value: input.value,
+				timeoutMs: this.options.timeoutMs,
+				assertDispatch: assertAuthority
+			});
+		})).response;
+	}
 	watchSession(input) {
 		this.assertOpen();
 		const signal = input.signal ? AbortSignal.any([input.signal, this.disconnect.signal]) : this.disconnect.signal;
@@ -2448,12 +2596,6 @@ function createSharedAcpRuntime(options) {
 //#endregion
 //#region src/runtime.ts
 const ACPX_BACKEND_ID = "acpx";
-const ACPX_CAPABILITIES = { controls: [
-	"session/set_mode",
-	"session/set_model",
-	"session/set_config_option",
-	"session/status"
-] };
 var AcpxRuntime = class {
 	options;
 	testOptions;
@@ -2557,6 +2699,7 @@ var AcpxRuntime = class {
 			onElicitation: input.onElicitation,
 			onPermissionRequest: input.onPermissionRequest
 		}));
+		turnPromise.catch(() => {});
 		return {
 			requestId: input.requestId,
 			get promptStarted() {
@@ -2593,15 +2736,9 @@ var AcpxRuntime = class {
 		});
 	}
 	async getCapabilities(input) {
-		if (!input?.handle) return ACPX_CAPABILITIES;
+		if (!input?.handle) return capabilitiesFromRecord(void 0);
 		const { handle } = this.resolveManagerHandle(input.handle);
-		const record = await this.options.sessionStore.load(handle.acpxRecordId ?? handle.sessionKey);
-		if (!record?.acpx?.config_options) return ACPX_CAPABILITIES;
-		const configOptionKeys = Array.from(new Set(record.acpx.config_options.map((option) => option.id).filter((id) => typeof id === "string" && id.trim().length > 0)));
-		return {
-			...ACPX_CAPABILITIES,
-			...configOptionKeys.length > 0 ? { configOptionKeys } : {}
-		};
+		return capabilitiesFromRecord(await this.options.sessionStore.load(handle.acpxRecordId ?? handle.sessionKey));
 	}
 	async getStatus(input) {
 		const { handle } = this.resolveManagerHandle(input.handle);