@openclaw/acpx 2026.9.3 → 2026.9.5

package/dist/{runtime-CSNBTQIs.js → .setup/runtime-Du-YvDnr.mjs}

@@ -1,56 +1,125 @@
-import { _ as splitCommandParts, a as hashAcpxProcessCommand, g as renderAgentCommand, l as readAcpxProcessLeaseIdentity, t as ACPX_PROBE_LEASE_SESSION_KEY, u as withAcpxLeaseArgs } from "./process-lease-B83BGiLj.js";
-import { AcpRuntimeError } from "./runtime-api.js";
-import { t as resolveAcpxSessionResource } from "./session-resource-UWe7qD3m.js";
-import { a as CODEX_ACP_PACKAGE, i as isOpenClawLeaseAwareAcpxProcessCommand, n as cleanupOpenClawOwnedAcpxPendingLease, o as OPENCLAW_CODEX_CONFIG_ARG, r as cleanupOpenClawOwnedAcpxProcessTree } from "./service-BAf6nuci.js";
-import { parseStrictPositiveInteger } from "openclaw/plugin-sdk/number-runtime";
+import { _ as splitCommandParts, a as hashAcpxProcessCommand, g as renderAgentCommand, l as readAcpxProcessLeaseIdentity, t as ACPX_PROBE_LEASE_SESSION_KEY, u as withAcpxLeaseArgs } from "./process-lease-B83BGiLj.mjs";
+import { AcpRuntimeError } from "../runtime-api.js";
+import { t as resolveAcpxSessionResource } from "./session-resource-Dzl0U7kK.mjs";
+import { a as CODEX_ACP_PACKAGE, i as isOpenClawLeaseAwareAcpxProcessCommand, n as cleanupOpenClawOwnedAcpxPendingLease, o as OPENCLAW_CODEX_CONFIG_ARG, r as cleanupOpenClawOwnedAcpxProcessTree } from "./service-DZYyo6-7.mjs";
 import { normalizeStringEntries } from "openclaw/plugin-sdk/string-coerce-runtime";
 import path, { resolve } from "node:path";
 import fs from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { sliceUtf16Safe } from "openclaw/plugin-sdk/text-utility-runtime";
+import { parseStrictPositiveInteger } from "openclaw/plugin-sdk/number-runtime";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { isDeepStrictEqual } from "node:util";
 import { ACPX_BACKEND_ID, AcpxRuntime as AcpxRuntime$1, createAcpRuntime, createAgentRegistry, createFileSessionStore, decodeAcpxRuntimeHandleState, decodeAcpxRuntimeHandleState as decodeAcpxRuntimeHandleState$1, encodeAcpxRuntimeHandleState, isRequestedModelUnsupportedError } from "acpx/runtime";
 import { KeyedAsyncQueue } from "openclaw/plugin-sdk/keyed-async-queue";
 import { redactSensitiveText } from "openclaw/plugin-sdk/security-runtime";
-//#region extensions/acpx/src/session-owner.ts
-function requireAcpxOwnerMigration(sessionKey) {
-	throw new AcpRuntimeError("ACP_SESSION_INIT_FAILED", `ACP session "${sessionKey}" has an unqualified or unverifiable backend locator. Stop the Gateway and run "openclaw doctor --fix" to migrate ownership without losing history, then restart.`, { detailCode: "SESSION_OWNER_MIGRATION_REQUIRED" });
-}
-function assertAcpxSessionOwnerLocator(target, legacyBareSessionKeys) {
-	const resource = resolveAcpxSessionResource(target);
-	const qualified = resource === target.sessionKey.trim().toLowerCase();
-	const persisted = target.persistedHandle;
-	if (!qualified && (legacyBareSessionKeys?.has(target.sessionKey.trim().toLowerCase()) || legacyBareSessionKeys?.has(resource) && !persisted)) requireAcpxOwnerMigration(target.sessionKey);
-	if (persisted) {
-		const decoded = decodeAcpxRuntimeHandleState$1(persisted.runtimeSessionName);
-		if (!qualified && !decoded || decoded && (decoded.name !== resource || persisted.acpxRecordId && decoded.acpxRecordId !== persisted.acpxRecordId)) requireAcpxOwnerMigration(target.sessionKey);
+//#region extensions/acpx/src/runtime-generations.ts
+var AcpxGenerationRegistry = class {
+	constructor(sessionStore, delegate, createDelegate) {
+		this.sessionStore = sessionStore;
+		this.delegate = delegate;
+		this.createDelegate = createDelegate;
+		this.generations = /* @__PURE__ */ new Map();
+		this.isolatedSessionResources = /* @__PURE__ */ new Set();
+		this.resetDelegates = /* @__PURE__ */ new Set();
+		this.retiringDelegates = /* @__PURE__ */ new WeakSet();
+		this.nextGenerationId = 0;
+		this.generationOwner = Symbol("acpx-runtime-owner");
+		this.stopping = false;
 	}
-	return resource;
-}
-/** Preserve physical oneshot record IDs and the upstream-encoded runtime handle. */
-function toAcpxResourceInput(input) {
-	const sessionKey = assertAcpxSessionOwnerLocator({
-		...input.handle,
-		persistedHandle: input.handle
-	});
-	return {
-		...input,
-		handle: {
-			...input.handle,
-			sessionKey
+	get isStopping() {
+		return this.stopping;
+	}
+	assertRunning() {
+		if (this.stopping) throw new AcpRuntimeError("ACP_BACKEND_UNAVAILABLE", "ACP runtime is shut down.");
+	}
+	fromCaptured(resource, captured) {
+		return captured?.owner === this.generationOwner ? captured : this.currentGeneration(resource);
+	}
+	prepareFresh(resource) {
+		const generation = this.generations.get(resource);
+		if (generation) this.retireGeneration(generation);
+		else this.sessionStore.markFresh(resource);
+	}
+	resolveDelegate(generation) {
+		this.assertRunning();
+		if (!generation.delegate) {
+			generation.delegate = generation.afterReset ? this.createDelegate() : this.delegate;
+			if (generation.delegate !== this.delegate) this.resetDelegates.add(generation.delegate);
 		}
-	};
-}
+		return generation.delegate;
+	}
+	currentGeneration(resource) {
+		if (this.stopping) throw new AcpRuntimeError("ACP_BACKEND_UNAVAILABLE", "ACP runtime is shut down.");
+		let generation = this.generations.get(resource);
+		if (!generation) {
+			const fresh = this.sessionStore.isFresh(resource);
+			const afterReset = fresh || this.isolatedSessionResources.has(resource);
+			if (afterReset) this.isolatedSessionResources.add(resource);
+			generation = {
+				id: ++this.nextGenerationId,
+				owner: this.generationOwner,
+				resource,
+				ensureQueue: new KeyedAsyncQueue(),
+				retired: false,
+				activeOperations: 0,
+				activeRecordOperations: /* @__PURE__ */ new Map(),
+				closedRecordIds: /* @__PURE__ */ new Set(),
+				records: /* @__PURE__ */ new Map(),
+				closeCompleted: false,
+				afterReset,
+				awaitPriorWrites: fresh
+			};
+			this.generations.set(resource, generation);
+		}
+		return generation;
+	}
+	retireGeneration(generation) {
+		generation.retired = true;
+		if (this.generations.get(generation.resource) === generation) {
+			this.generations.delete(generation.resource);
+			this.sessionStore.markFresh(generation.resource);
+		}
+		this.releaseRetiredDelegate(generation);
+	}
+	releaseRetiredDelegate(generation) {
+		const delegate = generation.delegate;
+		if (!generation.retired || generation.activeOperations !== 0 || !delegate || delegate === this.delegate || this.retiringDelegates.has(delegate)) return;
+		this.retiringDelegates.add(delegate);
+		delegate.shutdown().then(() => this.resetDelegates.delete(delegate), () => {});
+	}
+	retainGenerationOperation(generation, recordId) {
+		generation.activeOperations += 1;
+		generation.activeRecordOperations.set(recordId, (generation.activeRecordOperations.get(recordId) ?? 0) + 1);
+		return () => {
+			const remaining = (generation.activeRecordOperations.get(recordId) ?? 1) - 1;
+			if (remaining === 0) {
+				generation.activeRecordOperations.delete(recordId);
+				generation.closedRecordIds.delete(recordId);
+			} else generation.activeRecordOperations.set(recordId, remaining);
+			generation.activeOperations -= 1;
+			if (!generation.retired && generation.closeCompleted && generation.activeOperations === 0 && generation.records.size === 0 && this.generations.get(generation.resource) === generation) {
+				generation.retired = true;
+				this.generations.delete(generation.resource);
+			}
+			this.releaseRetiredDelegate(generation);
+		};
+	}
+	assertCurrentGeneration(generation) {
+		if (this.stopping || generation.retired) throw new AcpRuntimeError("ACP_TURN_FAILED", "ACP runtime operation was superseded by reset.");
+	}
+	async shutdown() {
+		this.stopping = true;
+		const errors = (await Promise.allSettled([this.delegate, ...this.resetDelegates].map((delegate) => delegate.shutdown()))).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+		if (errors.length) throw new AggregateError(errors, "ACP runtime shutdown failed.");
+		this.resetDelegates.clear();
+		this.generations.clear();
+		this.isolatedSessionResources.clear();
+	}
+};
 //#endregion
-//#region extensions/acpx/src/runtime.ts
-/**
-* OpenClaw ACPX runtime adapter. It wraps the upstream acpx runtime with
-* OpenClaw session metadata, lease tracking, model scoping, and cleanup policy.
-*/
-const ACPX_PLUGIN_TOOLS_MCP_SERVER_NAME = "openclaw-plugin-tools";
-const ACPX_OPENCLAW_TOOLS_MCP_SERVER_NAME = "openclaw-tools";
-const OPENCLAW_TOOLS_MCP_AGENT_SESSION_KEY_ENV = "OPENCLAW_TOOLS_MCP_AGENT_SESSION_KEY";
+//#region extensions/acpx/src/runtime-session-store.ts
+/** Generation-bound persistence and process-lease metadata for ACPX resets. */
 function withOpenClawLeaseSessionMetadata(record, lease) {
 	return {
 		...record,
@@ -58,31 +127,12 @@ function withOpenClawLeaseSessionMetadata(record, lease) {
 		openclawGatewayInstanceId: lease.gatewayInstanceId
 	};
 }
-const CODEX_WRAPPER_STDERR_LOG_PREFIX = "codex-acp-wrapper.stderr";
-function safeDiagnosticFilePart(value) {
-	return value.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120) || "unknown";
-}
-function codexWrapperStderrLogFileName(leaseId) {
-	return `${CODEX_WRAPPER_STDERR_LOG_PREFIX}.${safeDiagnosticFilePart(leaseId)}.log`;
-}
-function compactDiagnosticText(value) {
-	return value.replace(/\s+/g, " ").trim();
-}
-function isGenericInternalAcpErrorMessage(message) {
-	return message.trim() === "Internal error";
-}
-function isGenericInternalAcpError(error) {
-	return error instanceof Error && isGenericInternalAcpErrorMessage(error.message);
-}
-async function readCodexWrapperStderrTail(params) {
-	if (!params.wrapperRoot || !params.leaseId) return "";
-	try {
-		const text = await fs.readFile(path.join(params.wrapperRoot, codexWrapperStderrLogFileName(params.leaseId)), "utf8");
-		return compactDiagnosticText(redactSensitiveText(sliceUtf16Safe(text, -6e3)));
-	} catch {
-		return "";
-	}
+function captureGenerationRecord(generation, record) {
+	if (record.closed || generation.closedRecordIds.has(record.acpxRecordId)) generation.records.delete(record.acpxRecordId);
+	else generation.records.set(record.acpxRecordId, record);
 }
+const acpxGenerationKey = Symbol("openclaw.acpxGeneration");
+const acpxOperationScope = new AsyncLocalStorage();
 function readSessionRecordName(record) {
 	if (typeof record !== "object" || record === null) return "";
 	const { name } = record;
@@ -120,7 +170,7 @@ function readOpenClawGatewayInstanceIdFromRecord(record) {
 	return typeof openclawGatewayInstanceId === "string" ? openclawGatewayInstanceId.trim() || void 0 : void 0;
 }
 function extractGeneratedWrapperPath(command) {
-	return splitCommandParts(command ?? "").find((part) => basename(part) === "codex-acp-wrapper.mjs" || basename(part) === "claude-agent-acp-wrapper.mjs") ?? "";
+	return splitCommandParts(command ?? "").find((part) => (part.split(/[\\/]/).pop() ?? "") === "codex-acp-wrapper.mjs" || (part.split(/[\\/]/).pop() ?? "") === "claude-agent-acp-wrapper.mjs") ?? "";
 }
 function selectCurrentSessionLease(params) {
 	const sessionKeys = new Set(normalizeStringEntries(params.sessionKeys));
@@ -132,71 +182,217 @@ function selectCurrentSessionLease(params) {
 }
 function createResetAwareSessionStore(baseStore, params) {
 	const freshSessionKeys = /* @__PURE__ */ new Set();
+	const stateQueue = new KeyedAsyncQueue();
+	const pendingWrites = /* @__PURE__ */ new Map();
 	return {
 		async load(sessionId) {
-			const normalized = sessionId.trim();
-			if (normalized && freshSessionKeys.has(normalized)) return;
-			const record = await baseStore.load(sessionId);
-			if (!record || !params?.leaseStore || !params.gatewayInstanceId) return record;
-			const sessionName = readSessionRecordName(record) || normalized;
-			const lease = selectCurrentSessionLease({
-				leases: await params.leaseStore.listOpen(params.gatewayInstanceId),
-				sessionKeys: [sessionName, normalized],
-				rootPid: readRecordAgentPid(record)
-			});
-			if (!lease) return record;
-			return withOpenClawLeaseSessionMetadata(record, lease);
+			const scope = acpxOperationScope.getStore();
+			if (scope?.closeRecord && (sessionId === scope.generation.resource || sessionId === scope.closeRecord.acpxRecordId)) return scope.closeRecord;
+			const resource = scope?.generation.resource ?? sessionId.trim();
+			const pending = pendingWrites.get(sessionId.trim());
+			if (pending && (scope?.generation.awaitPriorWrites || freshSessionKeys.has(resource))) await Promise.allSettled(pending);
+			const load = async () => {
+				if (scope?.generation.retired) return;
+				const normalized = sessionId.trim();
+				if (normalized && freshSessionKeys.has(normalized)) return;
+				const record = await baseStore.load(sessionId);
+				if (scope?.generation.retired || freshSessionKeys.has(scope?.generation.resource ?? normalized)) return;
+				if (scope && record) captureGenerationRecord(scope.generation, record);
+				if (!record || !params?.leaseStore || !params.gatewayInstanceId) return record;
+				const sessionName = readSessionRecordName(record) || normalized;
+				const lease = selectCurrentSessionLease({
+					leases: await params.leaseStore.listOpen(params.gatewayInstanceId),
+					sessionKeys: [sessionName, normalized],
+					rootPid: readRecordAgentPid(record)
+				});
+				if (!lease) return record;
+				if (scope?.generation.retired) return;
+				const leasedRecord = withOpenClawLeaseSessionMetadata(record, lease);
+				if (scope) captureGenerationRecord(scope.generation, leasedRecord);
+				return leasedRecord;
+			};
+			return await load();
 		},
 		async save(record) {
-			let recordToSave = record;
-			const launch = params?.launchScope?.getStore();
-			const sessionName = readSessionRecordName(record);
-			const agentCommand = readRecordAgentCommand(record);
-			const leasedCommand = launch?.leasedCommand ?? agentCommand;
-			const leaseIdentity = launch ?? readAcpxProcessLeaseIdentity(leasedCommand);
-			if (params?.leaseStore && params.gatewayInstanceId && params.wrapperRoot && (!launch || sessionName === launch.sessionKey) && leasedCommand && leaseIdentity?.gatewayInstanceId === params.gatewayInstanceId && isOpenClawLeaseAwareAcpxProcessCommand({
-				command: leasedCommand,
-				wrapperRoot: params.wrapperRoot
-			})) {
-				const existing = await params.leaseStore.load(leaseIdentity.leaseId);
-				if (!existing || existing.gatewayInstanceId === leaseIdentity.gatewayInstanceId && existing.sessionKey === sessionName && existing.wrapperRoot === params.wrapperRoot) {
-					const adoptingLease = Boolean(launch && !isDeepStrictEqual(splitCommandParts(launch.resolvedCommand), splitCommandParts(launch.leasedCommand)));
-					const persistedCommand = launch && !adoptingLease ? launch.resolvedCommand : leasedCommand;
-					const lifecycleRecord = adoptingLease ? {
-						...record,
-						pid: void 0,
-						processId: void 0,
-						agentStartedAt: void 0
-					} : record;
-					const rootPid = readRecordAgentPid(lifecycleRecord);
-					if (rootPid) await params.leaseStore.save({
-						leaseId: leaseIdentity.leaseId,
-						gatewayInstanceId: leaseIdentity.gatewayInstanceId,
-						sessionKey: sessionName,
-						wrapperRoot: params.wrapperRoot,
-						wrapperPath: extractGeneratedWrapperPath(leasedCommand),
-						rootPid,
-						...existing?.rootPid === rootPid && existing.processGroupId ? { processGroupId: existing.processGroupId } : {},
-						commandHash: hashAcpxProcessCommand(persistedCommand),
-						startedAt: existing?.rootPid === rootPid ? existing.startedAt : Date.now(),
-						state: "open"
-					});
-					recordToSave = withOpenClawLeaseSessionMetadata({
-						...lifecycleRecord,
-						agentCommand: renderAgentCommand(persistedCommand),
-						agentArgv: Array.isArray(persistedCommand) ? persistedCommand : void 0
-					}, leaseIdentity);
+			const scope = acpxOperationScope.getStore();
+			if (scope) captureGenerationRecord(scope.generation, record);
+			const resource = record.acpxRecordId;
+			const retiredCloseRecord = scope?.generation.retired && record.closed && record.acpx?.reset_on_next_ensure === true ? scope.closeRecord : void 0;
+			const writeRecord = async () => {
+				if (scope?.generation.retired) {
+					if (!retiredCloseRecord) return;
+					const persisted = await baseStore.load(record.acpxRecordId);
+					if (!persisted || persisted.acpxRecordId !== retiredCloseRecord.acpxRecordId || persisted.acpSessionId !== retiredCloseRecord.acpSessionId || persisted.createdAt !== retiredCloseRecord.createdAt) return;
+					await baseStore.save(record);
+					return;
+				}
+				let recordToSave = record;
+				const launch = params?.launchScope?.getStore();
+				const sessionName = readSessionRecordName(record);
+				const agentCommand = readRecordAgentCommand(record);
+				const leasedCommand = launch?.leasedCommand ?? agentCommand;
+				const leaseIdentity = launch ?? readAcpxProcessLeaseIdentity(leasedCommand);
+				if (params?.leaseStore && params.gatewayInstanceId && params.wrapperRoot && (!launch || sessionName === launch.sessionKey) && leasedCommand && leaseIdentity?.gatewayInstanceId === params.gatewayInstanceId && isOpenClawLeaseAwareAcpxProcessCommand({
+					command: leasedCommand,
+					wrapperRoot: params.wrapperRoot
+				})) {
+					const existing = await params.leaseStore.load(leaseIdentity.leaseId);
+					if (scope?.generation.retired) return;
+					if (!existing || existing.gatewayInstanceId === leaseIdentity.gatewayInstanceId && existing.sessionKey === sessionName && existing.wrapperRoot === params.wrapperRoot) {
+						const adoptingLease = Boolean(launch && !isDeepStrictEqual(splitCommandParts(launch.resolvedCommand), splitCommandParts(launch.leasedCommand)));
+						const persistedCommand = launch && !adoptingLease ? launch.resolvedCommand : leasedCommand;
+						recordToSave = withOpenClawLeaseSessionMetadata({
+							...adoptingLease ? {
+								...record,
+								pid: void 0,
+								processId: void 0,
+								agentStartedAt: void 0
+							} : record,
+							agentCommand: renderAgentCommand(persistedCommand),
+							agentArgv: Array.isArray(persistedCommand) ? persistedCommand : void 0
+						}, leaseIdentity);
+					}
 				}
+				if (scope?.generation.retired) return;
+				await baseStore.save(recordToSave);
+				if (scope && !scope.generation.retired) scope.generation.awaitPriorWrites = false;
+				if (sessionName && !scope?.generation.retired) freshSessionKeys.delete(sessionName);
+			};
+			const writes = pendingWrites.get(resource) ?? /* @__PURE__ */ new Set();
+			const previous = [...writes];
+			const write = scope?.generation.awaitPriorWrites || retiredCloseRecord ? Promise.allSettled(previous).then(() => stateQueue.enqueue(resource, writeRecord)) : writeRecord();
+			writes.add(write);
+			pendingWrites.set(resource, writes);
+			try {
+				await write;
+			} finally {
+				writes.delete(write);
+				if (writes.size === 0 && pendingWrites.get(resource) === writes) pendingWrites.delete(resource);
 			}
-			await baseStore.save(recordToSave);
-			if (sessionName) freshSessionKeys.delete(sessionName);
 		},
+		loadForClose: (sessionKey) => baseStore.load(sessionKey),
+		isFresh: (sessionKey) => freshSessionKeys.has(sessionKey),
 		markFresh(sessionKey) {
 			const normalized = sessionKey.trim();
 			if (normalized) freshSessionKeys.add(normalized);
 		}
 	};
 }
+//#endregion
+//#region extensions/acpx/src/runtime-process-cleanup.ts
+/** Capture OpenClaw wrapper cleanup ownership before a backend close can yield. */
+async function prepareAcpxProcessCleanup(params) {
+	const { leaseStore, gatewayInstanceId, wrapperRoot, deps } = params;
+	const rootPid = readRecordAgentPid(params.record);
+	const rootCommand = params.command ? renderAgentCommand(params.command) : void 0;
+	const identity = readAcpxProcessLeaseIdentity(params.command);
+	const leaseId = readOpenClawLeaseIdFromRecord(params.record) ?? identity?.leaseId;
+	const expectedGatewayInstanceId = readOpenClawGatewayInstanceIdFromRecord(params.record) ?? identity?.gatewayInstanceId;
+	const sessionKeys = [params.sessionKey, readSessionRecordName(params.record)];
+	const openLeases = rootPid && gatewayInstanceId && leaseStore ? await leaseStore.listOpen(gatewayInstanceId) : [];
+	const selectedLease = rootPid ? selectCurrentSessionLease({
+		leases: openLeases,
+		sessionKeys,
+		rootPid
+	}) : void 0;
+	const loadedLease = leaseId ? await leaseStore?.load(leaseId) : void 0;
+	const ownedLease = selectedLease ?? (loadedLease && loadedLease.gatewayInstanceId === gatewayInstanceId && (!rootPid || loadedLease.rootPid === rootPid) && sessionKeys.includes(loadedLease.sessionKey) ? loadedLease : void 0);
+	const lease = ownedLease ? { ...ownedLease } : void 0;
+	return async () => {
+		if (lease && lease.gatewayInstanceId === gatewayInstanceId) {
+			await leaseStore?.markState(lease.leaseId, "closing");
+			const result = lease.rootPid > 0 ? await cleanupOpenClawOwnedAcpxProcessTree({
+				rootPid: lease.rootPid,
+				rootCommand,
+				expectedLeaseId: lease.leaseId,
+				expectedGatewayInstanceId: lease.gatewayInstanceId,
+				wrapperRoot: lease.wrapperRoot,
+				deps
+			}) : await cleanupOpenClawOwnedAcpxPendingLease({
+				leaseId: lease.leaseId,
+				gatewayInstanceId: lease.gatewayInstanceId,
+				wrapperRoot: lease.wrapperRoot,
+				wrapperPath: lease.wrapperPath,
+				deps
+			});
+			await leaseStore?.markState(lease.leaseId, result.skippedReason === "process-list-unavailable" || result.skippedReason === "unsupported-platform" || lease.rootPid <= 0 && (result.skippedReason === "ambiguous-root" || result.skippedReason === "unverified-root") ? "open" : result.terminatedPids.length > 0 || result.skippedReason === "missing-root" ? "closed" : "lost");
+			return;
+		}
+		if (!rootPid || !rootCommand) return;
+		await cleanupOpenClawOwnedAcpxProcessTree({
+			rootPid,
+			rootCommand,
+			...leaseId ? { expectedLeaseId: leaseId } : {},
+			...expectedGatewayInstanceId ? { expectedGatewayInstanceId } : {},
+			wrapperRoot,
+			deps
+		});
+	};
+}
+//#endregion
+//#region extensions/acpx/src/session-owner.ts
+function requireAcpxOwnerMigration(sessionKey) {
+	throw new AcpRuntimeError("ACP_SESSION_INIT_FAILED", `ACP session "${sessionKey}" has an unqualified or unverifiable backend locator. Stop the Gateway and run "openclaw doctor --fix" to migrate ownership without losing history, then restart.`, { detailCode: "SESSION_OWNER_MIGRATION_REQUIRED" });
+}
+function assertAcpxSessionOwnerLocator(target, legacyBareSessionKeys) {
+	const resource = resolveAcpxSessionResource(target);
+	const qualified = resource === target.sessionKey.trim().toLowerCase();
+	const persisted = target.persistedHandle;
+	if (!qualified && (legacyBareSessionKeys?.has(target.sessionKey.trim().toLowerCase()) || legacyBareSessionKeys?.has(resource) && !persisted)) requireAcpxOwnerMigration(target.sessionKey);
+	if (persisted) {
+		const decoded = decodeAcpxRuntimeHandleState$1(persisted.runtimeSessionName);
+		if (!qualified && !decoded || decoded && (decoded.name !== resource || persisted.acpxRecordId && decoded.acpxRecordId !== persisted.acpxRecordId)) requireAcpxOwnerMigration(target.sessionKey);
+	}
+	return resource;
+}
+/** Preserve physical oneshot record IDs and the upstream-encoded runtime handle. */
+function toAcpxResourceInput(input) {
+	const sessionKey = assertAcpxSessionOwnerLocator({
+		...input.handle,
+		persistedHandle: input.handle
+	});
+	return {
+		...input,
+		handle: {
+			...input.handle,
+			sessionKey
+		}
+	};
+}
+//#endregion
+//#region extensions/acpx/src/runtime.ts
+/**
+* OpenClaw ACPX runtime adapter. It wraps the upstream acpx runtime with
+* OpenClaw session metadata, lease tracking, model scoping, and cleanup policy.
+*/
+const ACPX_PLUGIN_TOOLS_MCP_SERVER_NAME = "openclaw-plugin-tools";
+const ACPX_OPENCLAW_TOOLS_MCP_SERVER_NAME = "openclaw-tools";
+const OPENCLAW_TOOLS_MCP_AGENT_SESSION_KEY_ENV = "OPENCLAW_TOOLS_MCP_AGENT_SESSION_KEY";
+const CODEX_WRAPPER_STDERR_LOG_PREFIX = "codex-acp-wrapper.stderr";
+function safeDiagnosticFilePart(value) {
+	return value.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120) || "unknown";
+}
+function codexWrapperStderrLogFileName(leaseId) {
+	return `${CODEX_WRAPPER_STDERR_LOG_PREFIX}.${safeDiagnosticFilePart(leaseId)}.log`;
+}
+function compactDiagnosticText(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+function isGenericInternalAcpErrorMessage(message) {
+	return message.trim() === "Internal error";
+}
+function isGenericInternalAcpError(error) {
+	return error instanceof Error && isGenericInternalAcpErrorMessage(error.message);
+}
+async function readCodexWrapperStderrTail(params) {
+	if (!params.wrapperRoot || !params.leaseId) return "";
+	try {
+		const text = await fs.readFile(path.join(params.wrapperRoot, codexWrapperStderrLogFileName(params.leaseId)), "utf8");
+		return compactDiagnosticText(redactSensitiveText(sliceUtf16Safe(text, -6e3)));
+	} catch {
+		return "";
+	}
+}
 const OPENCLAW_BRIDGE_EXECUTABLE = "openclaw";
 const OPENCLAW_BRIDGE_SUBCOMMAND = "acp";
 const CODEX_ACP_AGENT_ID = "codex";
@@ -362,7 +558,7 @@ function withAcpxSessionOptions(input) {
 		...existingOptions,
 		model
 	} : existingOptions;
-	const { modelExplicit: _modelExplicit, ...rest } = input;
+	const { modelExplicit: _modelExplicit, thinkingExplicit: _thinkingExplicit, ...rest } = input;
 	return {
 		...rest,
 		...sessionOptions ? { sessionOptions } : {}
@@ -402,10 +598,6 @@ function resolveAgentCommand(params) {
 	if (!normalizedAgentName) return;
 	return splitCommandParts(params.agentRegistry.resolve(normalizedAgentName));
 }
-function shouldUseDistinctBridgeDelegate(options) {
-	const { mcpServers } = options;
-	return Array.isArray(mcpServers) && mcpServers.length > 0;
-}
 function withManagedToolsMcpSessionEnv(params) {
 	const sessionKey = params.sessionKey.trim();
 	if (!params.pluginToolsEnabled && !params.openclawToolsEnabled || !sessionKey || !params.mcpServers?.length) return params.mcpServers;
@@ -436,12 +628,9 @@ var AcpxRuntime = class {
 	constructor(options, testOptions) {
 		this.ownerAwareSessions = 1;
 		this.launchCommandScope = new AsyncLocalStorage();
-		this.managedToolsSessionDelegates = /* @__PURE__ */ new Map();
+		this.sessionScope = new AsyncLocalStorage();
+		this.probeQueue = new KeyedAsyncQueue();
 		this.launchLeaseScope = new AsyncLocalStorage();
-		this.sessionEnsureQueue = new KeyedAsyncQueue();
-		this.processLeaseTransitionQueue = new KeyedAsyncQueue();
-		this.processLeaseOperationCounts = /* @__PURE__ */ new Map();
-		this.uncertainProcessLeaseIds = /* @__PURE__ */ new Set();
 		this.legacyBareSessionKeys = new Set(options.openclawLegacyBareSessionKeys);
 		const { openclawProcessCleanup, ...delegateTestOptions } = testOptions ?? {};
 		this.processCleanupDeps = openclawProcessCleanup;
@@ -466,69 +655,101 @@ var AcpxRuntime = class {
 			},
 			list: () => this.agentRegistry.list()
 		};
-		const sharedOptions = {
+		this.createDelegate = () => new AcpxRuntime$1({
 			...options,
 			sessionStore: this.sessionStore,
-			agentRegistry: this.scopedAgentRegistry
-		};
-		this.delegateOptions = sharedOptions;
-		this.delegateTestOptions = delegateTestOptions;
-		this.delegate = new AcpxRuntime$1(sharedOptions, this.delegateTestOptions);
-		this.bridgeSafeDelegate = shouldUseDistinctBridgeDelegate(options) ? new AcpxRuntime$1({
-			...sharedOptions,
-			mcpServers: []
-		}, this.delegateTestOptions) : this.delegate;
+			agentRegistry: this.scopedAgentRegistry,
+			mcpServers: (context) => {
+				const servers = typeof options.mcpServers === "function" ? options.mcpServers(context) : options.mcpServers ?? [];
+				if (isOpenClawBridgeCommand(context.agentArgv ?? context.agentCommand)) return [];
+				const target = this.sessionScope.getStore();
+				if (!this.managedToolsMcpBridgeEnabled) return servers;
+				if (!target) throw new AcpRuntimeError("ACP_SESSION_INIT_FAILED", "ACP tool bridge has no session owner");
+				return withManagedToolsMcpSessionEnv({
+					pluginToolsEnabled: this.pluginToolsMcpBridgeEnabled,
+					openclawToolsEnabled: this.openclawToolsMcpBridgeEnabled,
+					mcpServers: servers,
+					...target
+				});
+			},
+			processLifecycle: {
+				onBeforeSpawn: async (launch) => {
+					await options.processLifecycle?.onBeforeSpawn?.(launch);
+					await this.recordProcessLaunch(launch);
+				},
+				onSpawned: async (process) => {
+					await this.recordProcessLaunch(process);
+					await options.processLifecycle?.onSpawned?.(process);
+				},
+				onSpawnFailed: options.processLifecycle?.onSpawnFailed,
+				onExit: options.processLifecycle?.onExit
+			}
+		}, delegateTestOptions);
+		this.delegate = this.createDelegate();
+		this.generationRegistry = new AcpxGenerationRegistry(this.sessionStore, this.delegate, this.createDelegate);
 		this.probeAgent = normalizeAgentName(options.probeAgent) ?? "codex";
 		const probeCommand = resolveAgentCommand({
 			agentName: this.probeAgent,
 			agentRegistry: this.agentRegistry
 		});
 		this.probeCommand = probeCommand;
-		const useBridgeSafeProbe = this.managedToolsMcpBridgeEnabled || isOpenClawBridgeCommand(probeCommand);
-		this.probeDelegate = useBridgeSafeProbe ? this.bridgeSafeDelegate : this.delegate;
 	}
-	resolveDelegateForSession(params) {
-		if (isOpenClawBridgeCommand(params.command)) return this.bridgeSafeDelegate;
-		return this.resolveManagedToolsDelegateForSession(params);
+	async runInGeneration(target, scope, run) {
+		const release = this.generationRegistry.retainGenerationOperation(scope.generation, scope.recordId ?? target.acpxRecordId ?? scope.generation.resource);
+		try {
+			return await this.sessionScope.run(target, () => acpxOperationScope.run(scope, run));
+		} finally {
+			release();
+		}
 	}
-	resolveManagedToolsDelegateForSession(target) {
-		if (!this.managedToolsMcpBridgeEnabled) return this.delegate;
-		const normalizedSessionKey = resolveAcpxSessionResource(target);
-		const cached = this.managedToolsSessionDelegates.get(normalizedSessionKey);
-		if (cached) return cached;
-		const delegate = new AcpxRuntime$1({
-			...this.delegateOptions,
-			mcpServers: withManagedToolsMcpSessionEnv({
-				pluginToolsEnabled: this.pluginToolsMcpBridgeEnabled,
-				openclawToolsEnabled: this.openclawToolsMcpBridgeEnabled,
-				mcpServers: this.delegateOptions.mcpServers,
-				sessionKey: target.sessionKey,
-				agentId: target.agentId
-			})
-		}, this.delegateTestOptions);
-		this.managedToolsSessionDelegates.set(normalizedSessionKey, delegate);
-		return delegate;
+	resolveDelegateForSession(params) {
+		const generation = acpxOperationScope.getStore()?.generation ?? this.generationRegistry.currentGeneration(resolveAcpxSessionResource(params));
+		return this.generationRegistry.resolveDelegate(generation);
 	}
-	async loadOperationSnapshotForHandle(handle) {
-		assertAcpxSessionOwnerLocator({
+	generationForHandle(handle) {
+		const resource = assertAcpxSessionOwnerLocator({
 			...handle,
 			persistedHandle: handle
 		}, this.legacyBareSessionKeys);
-		const record = await this.sessionStore.load(handle.acpxRecordId ?? resolveAcpxSessionResource(handle));
+		const capturedGeneration = handle[acpxGenerationKey];
+		return this.generationRegistry.fromCaptured(resource, capturedGeneration);
+	}
+	async loadOperationSnapshotForHandle(handle, allowRetired = false, generation = this.generationForHandle(handle)) {
+		const resource = generation.resource;
+		if (!allowRetired) this.generationRegistry.assertCurrentGeneration(generation);
+		const ownedRecord = generation.records.get(handle.acpxRecordId ?? resource);
+		if (ownedRecord && (handle.acpxRecordId && ownedRecord.acpxRecordId !== handle.acpxRecordId || handle.backendSessionId && ownedRecord.acpSessionId && ownedRecord.acpSessionId !== handle.backendSessionId)) throw new AcpRuntimeError("ACP_TURN_FAILED", "ACP handle no longer owns this runtime generation.");
+		let record = allowRetired ? generation.retired ? ownedRecord : await this.sessionStore.loadForClose(handle.acpxRecordId ?? resource) : await acpxOperationScope.run({ generation }, () => this.sessionStore.load(handle.acpxRecordId ?? resource));
+		if (allowRetired && generation.retired && ownedRecord) record = ownedRecord;
+		if (allowRetired && record) captureGenerationRecord(generation, record);
+		if (!allowRetired) this.generationRegistry.assertCurrentGeneration(generation);
+		if (record && (handle.acpxRecordId && handle.acpxRecordId !== record.acpxRecordId || handle.backendSessionId && record.acpSessionId && handle.backendSessionId !== record.acpSessionId)) throw new AcpRuntimeError("ACP_TURN_FAILED", "ACP handle no longer owns this runtime record.");
+		const command = readRecordAgentCommand(record) ?? resolveAgentCommand({
+			agentName: readAgentFromHandle(handle),
+			agentRegistry: this.agentRegistry
+		});
+		const identity = readAcpxProcessLeaseIdentity(command);
+		if (identity && this.processLeaseStore && this.gatewayInstanceId && this.wrapperRoot) {
+			const lease = await this.processLeaseStore.load(identity.leaseId);
+			if (identity.gatewayInstanceId !== this.gatewayInstanceId) throw new AcpRuntimeError("ACP_TURN_FAILED", `ACPX process lease ${identity.leaseId} belongs to another gateway`);
+			if (lease && (lease.gatewayInstanceId !== identity.gatewayInstanceId || lease.sessionKey !== resolveAcpxSessionResource(handle) || lease.wrapperRoot !== this.wrapperRoot)) throw new AcpRuntimeError("ACP_TURN_FAILED", `ACPX process lease ${identity.leaseId} belongs to another session`);
+		}
+		if (!allowRetired) this.generationRegistry.assertCurrentGeneration(generation);
 		return {
 			record,
-			command: readRecordAgentCommand(record) ?? resolveAgentCommand({
-				agentName: readAgentFromHandle(handle),
-				agentRegistry: this.agentRegistry
-			})
+			command,
+			generation
 		};
 	}
 	resolveDelegateForOperationSnapshot(handle, snapshot) {
-		return this.resolveDelegateForSession({
+		return acpxOperationScope.run({
+			generation: snapshot.generation,
+			recordId: snapshot.record?.acpxRecordId
+		}, () => this.resolveDelegateForSession({
 			command: snapshot.command,
 			sessionKey: handle.sessionKey,
 			agentId: handle.agentId
-		});
+		}));
 	}
 	async readReusablePersistentSessionCommand(params) {
 		if (params.mode !== "persistent" || !params.command) return;
@@ -556,10 +777,8 @@ var AcpxRuntime = class {
 			agent: normalizeAgentName(params.agent) ?? params.agent,
 			command: params.reusableCommand ?? params.command
 		}, params.run);
-		const processLeaseStore = this.processLeaseStore;
 		const reusableIdentity = readAcpxProcessLeaseIdentity(params.reusableCommand);
-		const canReuseLeaseIdentity = reusableIdentity?.gatewayInstanceId === this.gatewayInstanceId;
-		const leaseId = canReuseLeaseIdentity ? reusableIdentity.leaseId : params.finalizeCompletedProbe ? `probe-${hashAcpxProcessCommand(`${this.gatewayInstanceId}\0${extractGeneratedWrapperPath(params.command)}`)}` : randomUUID();
+		const leaseId = reusableIdentity?.gatewayInstanceId === this.gatewayInstanceId ? reusableIdentity.leaseId : params.finalizeCompletedProbe ? `probe-${hashAcpxProcessCommand(`${this.gatewayInstanceId}\0${extractGeneratedWrapperPath(params.command)}`)}` : randomUUID();
 		const leasedCommand = withAcpxLeaseArgs({
 			command: params.command,
 			leaseId,
@@ -573,149 +792,41 @@ var AcpxRuntime = class {
 			resolvedCommand: params.reusableCommand ?? leasedCommand,
 			leasedCommand
 		};
-		await this.retainProcessLeaseOperation(launch, async () => {
-			const reusableLease = canReuseLeaseIdentity ? await processLeaseStore.load(launch.leaseId) : void 0;
-			if (reusableLease && (reusableLease.gatewayInstanceId !== launch.gatewayInstanceId || reusableLease.sessionKey !== launch.sessionKey || reusableLease.wrapperRoot !== launch.wrapperRoot)) throw new AcpRuntimeError("ACP_SESSION_INIT_FAILED", `ACPX process lease ${launch.leaseId} belongs to another session`);
-			if (!(!reusableLease && (!params.reusableCommand || isDeepStrictEqual(splitCommandParts(params.reusableCommand), splitCommandParts(leasedCommand))))) return;
-			await processLeaseStore.save({
-				leaseId: launch.leaseId,
-				gatewayInstanceId: launch.gatewayInstanceId,
-				sessionKey: launch.sessionKey,
-				wrapperRoot: launch.wrapperRoot,
-				wrapperPath: extractGeneratedWrapperPath(leasedCommand),
-				rootPid: 0,
-				commandHash: hashAcpxProcessCommand(leasedCommand),
-				startedAt: Date.now(),
-				state: "open"
-			});
+		const result = await this.launchLeaseScope.run(launch, () => this.launchCommandScope.run({
+			agent: normalizeAgentName(params.agent) ?? params.agent,
+			command: launch.resolvedCommand
+		}, params.run));
+		if (params.finalizeCompletedProbe) await cleanupOpenClawOwnedAcpxPendingLease({
+			leaseId,
+			gatewayInstanceId: launch.gatewayInstanceId,
+			wrapperRoot: launch.wrapperRoot,
+			wrapperPath: extractGeneratedWrapperPath(leasedCommand),
+			deps: this.processCleanupDeps
 		});
-		try {
-			const result = await this.launchLeaseScope.run(launch, () => this.launchCommandScope.run({
-				agent: normalizeAgentName(params.agent) ?? params.agent,
-				command: launch.resolvedCommand
-			}, params.run));
-			if (params.finalizeCompletedProbe) await this.finalizeCompletedProbeLease(launch);
-			else await this.finalizeProcessLeaseForSession(params.sessionKey, launch);
-			return result;
-		} catch (error) {
-			await this.releaseProcessLeaseAfterUncertainFailure(launch);
-			throw error;
-		}
+		return result;
 	}
-	async prepareProcessLeaseForOperation(handle, record) {
-		if (!this.processLeaseStore || !this.gatewayInstanceId || !this.wrapperRoot) return;
-		const processLeaseStore = this.processLeaseStore;
-		const wrapperRoot = this.wrapperRoot;
-		const recordPid = readRecordAgentPid(record);
-		const command = readRecordAgentCommand(record);
+	async recordProcessLaunch(process) {
+		const command = [process.command, ...process.args];
 		const identity = readAcpxProcessLeaseIdentity(command);
-		if (!command || !isOpenClawLeaseAwareAcpxProcessCommand({
+		if (!identity || !this.processLeaseStore || !this.wrapperRoot) return;
+		const sessionKey = process.scope.kind === "runtime-session" ? process.scope.sessionKey : ACPX_PROBE_LEASE_SESSION_KEY;
+		const existing = await this.processLeaseStore.load(identity.leaseId);
+		if (identity.gatewayInstanceId !== this.gatewayInstanceId || existing && (existing.gatewayInstanceId !== identity.gatewayInstanceId || existing.sessionKey !== sessionKey || existing.wrapperRoot !== this.wrapperRoot)) throw new AcpRuntimeError("ACP_SESSION_INIT_FAILED", "ACP process lease belongs to another owner");
+		if (!isOpenClawLeaseAwareAcpxProcessCommand({
 			command,
-			wrapperRoot
-		})) return;
-		if (!identity) return;
-		if (identity.gatewayInstanceId !== this.gatewayInstanceId) throw new AcpRuntimeError("ACP_TURN_FAILED", `ACPX process lease ${identity.leaseId} belongs to another gateway`);
-		await this.retainProcessLeaseOperation(identity, async () => {
-			const existing = await processLeaseStore.load(identity.leaseId);
-			if (!existing) {
-				await processLeaseStore.save({
-					leaseId: identity.leaseId,
-					gatewayInstanceId: identity.gatewayInstanceId,
-					sessionKey: resolveAcpxSessionResource(handle),
-					wrapperRoot,
-					wrapperPath: extractGeneratedWrapperPath(command),
-					rootPid: recordPid ?? 0,
-					commandHash: hashAcpxProcessCommand(command),
-					startedAt: Date.now(),
-					state: "open"
-				});
-				return;
-			}
-			if (existing.gatewayInstanceId !== identity.gatewayInstanceId || existing.sessionKey !== resolveAcpxSessionResource(handle) || existing.wrapperRoot !== wrapperRoot) throw new AcpRuntimeError("ACP_TURN_FAILED", `ACPX process lease ${identity.leaseId} belongs to another session`);
-		});
-		return identity;
-	}
-	async retainProcessLeaseOperation(identity, prepare) {
-		await this.processLeaseTransitionQueue.enqueue(identity.leaseId, async () => {
-			await prepare();
-			this.processLeaseOperationCounts.set(identity.leaseId, (this.processLeaseOperationCounts.get(identity.leaseId) ?? 0) + 1);
-		});
-	}
-	async releaseProcessLeaseOperation(identity, finalize) {
-		if (!identity) return;
-		await this.processLeaseTransitionQueue.enqueue(identity.leaseId, async () => {
-			const count = this.processLeaseOperationCounts.get(identity.leaseId) ?? 0;
-			if (count > 1) {
-				this.processLeaseOperationCounts.set(identity.leaseId, count - 1);
-				return;
-			}
-			if (count === 0) return;
-			this.processLeaseOperationCounts.delete(identity.leaseId);
-			await finalize();
-		});
-	}
-	async finalizeProcessLeaseForOperation(handle, identity) {
-		await this.finalizeProcessLeaseForSession(handle.acpxRecordId ?? resolveAcpxSessionResource(handle), identity);
-	}
-	async finalizeProcessLeaseForSession(sessionId, identity) {
-		if (!identity || !this.processLeaseStore) return;
-		const processLeaseStore = this.processLeaseStore;
-		await this.releaseProcessLeaseOperation(identity, async () => {
-			const lease = await processLeaseStore.load(identity.leaseId);
-			if (!lease || lease.gatewayInstanceId !== identity.gatewayInstanceId) return;
-			if (lease.rootPid <= 0) {
-				if (this.uncertainProcessLeaseIds.has(identity.leaseId)) return;
-				await processLeaseStore.markState(identity.leaseId, "lost");
-				return;
-			}
-			this.uncertainProcessLeaseIds.delete(identity.leaseId);
-			try {
-				const record = await this.sessionStore.load(sessionId);
-				const recordIdentity = readAcpxProcessLeaseIdentity(readRecordAgentCommand(record));
-				if (recordIdentity?.leaseId !== identity.leaseId || recordIdentity.gatewayInstanceId !== identity.gatewayInstanceId) await processLeaseStore.markState(identity.leaseId, "lost");
-			} catch {}
-		});
-	}
-	async finalizeCompletedProbeLease(identity) {
-		if (!this.processLeaseStore) return;
-		const processLeaseStore = this.processLeaseStore;
-		await this.releaseProcessLeaseOperation(identity, async () => {
-			const lease = await processLeaseStore.load(identity.leaseId);
-			if (!lease || lease.gatewayInstanceId !== identity.gatewayInstanceId) return;
-			if (lease.rootPid > 0) return;
-			await cleanupOpenClawOwnedAcpxPendingLease({
-				leaseId: lease.leaseId,
-				gatewayInstanceId: lease.gatewayInstanceId,
-				wrapperRoot: lease.wrapperRoot,
-				wrapperPath: lease.wrapperPath,
-				deps: this.processCleanupDeps
-			});
-		});
-	}
-	async releaseProcessLeaseAfterUncertainFailure(identity) {
-		if (!identity || !this.processLeaseStore) return;
-		this.uncertainProcessLeaseIds.add(identity.leaseId);
-		const processLeaseStore = this.processLeaseStore;
-		await this.releaseProcessLeaseOperation(identity, async () => {
-			const lease = await processLeaseStore.load(identity.leaseId);
-			if (!lease || lease.gatewayInstanceId !== identity.gatewayInstanceId || lease.rootPid > 0) this.uncertainProcessLeaseIds.delete(identity.leaseId);
+			wrapperRoot: this.wrapperRoot
+		})) throw new AcpRuntimeError("ACP_SESSION_INIT_FAILED", "ACP process lease has no owned wrapper");
+		await this.processLeaseStore.save({
+			...identity,
+			sessionKey,
+			wrapperRoot: this.wrapperRoot,
+			wrapperPath: extractGeneratedWrapperPath(command),
+			rootPid: "pid" in process ? process.pid : 0,
+			commandHash: hashAcpxProcessCommand(command),
+			startedAt: "startedAt" in process ? Date.parse(process.startedAt) : Date.now(),
+			state: "open"
 		});
 	}
-	async runWithProcessLeaseForHandle(handle, record, run) {
-		const identity = await this.prepareProcessLeaseForOperation(handle, record);
-		try {
-			return await run();
-		} finally {
-			await this.finalizeProcessLeaseForOperation(handle, identity);
-		}
-	}
-	async finalizeProcessLeaseAfter(handle, identityPromise, resultPromise) {
-		try {
-			return await resultPromise;
-		} finally {
-			await this.finalizeProcessLeaseForOperation(handle, await identityPromise);
-		}
-	}
 	async withCodexWrapperDiagnostics(params) {
 		try {
 			return await params.run();
@@ -736,69 +847,47 @@ var AcpxRuntime = class {
 			leaseId: readOpenClawLeaseIdFromRecord(record)
 		});
 	}
-	async cleanupProcessTreeForRecord(handle, record) {
-		const leaseId = readOpenClawLeaseIdFromRecord(record);
-		const rootPid = readRecordAgentPid(record);
-		const sessionKeys = [resolveAcpxSessionResource(handle), readSessionRecordName(record)];
-		const selectedLease = selectCurrentSessionLease({
-			leases: this.gatewayInstanceId && this.processLeaseStore ? await this.processLeaseStore.listOpen(this.gatewayInstanceId) : [],
-			sessionKeys,
-			rootPid
-		});
-		const loadedLease = leaseId ? await this.processLeaseStore?.load(leaseId) : void 0;
-		const lease = selectedLease ?? (loadedLease && loadedLease.gatewayInstanceId === this.gatewayInstanceId && (!rootPid || loadedLease.rootPid === rootPid) && sessionKeys.includes(loadedLease.sessionKey) ? loadedLease : void 0);
-		if (lease && lease.gatewayInstanceId === this.gatewayInstanceId && lease.rootPid > 0) {
-			await this.processLeaseStore?.markState(lease.leaseId, "closing");
-			const result = await cleanupOpenClawOwnedAcpxProcessTree({
-				rootPid: lease.rootPid,
-				rootCommand: record?.agentCommand,
-				expectedLeaseId: lease.leaseId,
-				expectedGatewayInstanceId: lease.gatewayInstanceId,
-				wrapperRoot: lease.wrapperRoot,
-				deps: this.processCleanupDeps
-			});
-			await this.processLeaseStore?.markState(lease.leaseId, result.skippedReason === "process-list-unavailable" || result.skippedReason === "unsupported-platform" ? "open" : result.terminatedPids.length > 0 || result.skippedReason === "missing-root" ? "closed" : "lost");
-			return;
-		}
-		const rootCommand = readRecordAgentCommand(record) ?? resolveAgentCommand({
-			agentName: readAgentFromHandle(handle),
-			agentRegistry: this.agentRegistry
-		});
-		if (!rootPid || !rootCommand) return;
-		const expectedGatewayInstanceId = readOpenClawGatewayInstanceIdFromRecord(record);
-		await cleanupOpenClawOwnedAcpxProcessTree({
-			rootPid,
-			rootCommand: renderAgentCommand(rootCommand),
-			...leaseId ? { expectedLeaseId: leaseId } : {},
-			...expectedGatewayInstanceId ? { expectedGatewayInstanceId } : {},
-			wrapperRoot: this.wrapperRoot,
-			deps: this.processCleanupDeps
-		});
+	async shutdown() {
+		await this.generationRegistry.shutdown();
 	}
 	isHealthy() {
-		return this.probeDelegate.isHealthy();
+		return this.delegate.isHealthy();
 	}
 	async probeAvailability() {
-		await this.runWithLaunchLease({
+		await this.probeQueue.enqueue(this.probeAgent, () => this.runWithLaunchLease({
 			agent: this.probeAgent,
 			sessionKey: ACPX_PROBE_LEASE_SESSION_KEY,
 			command: this.probeCommand,
 			finalizeCompletedProbe: true,
-			run: () => this.probeDelegate.probeAvailability()
-		});
+			run: () => this.delegate.probeAvailability()
+		}));
 	}
 	async doctor() {
-		return await this.runWithLaunchLease({
+		return await this.probeQueue.enqueue(this.probeAgent, () => this.runWithLaunchLease({
 			agent: this.probeAgent,
 			sessionKey: ACPX_PROBE_LEASE_SESSION_KEY,
 			command: this.probeCommand,
 			finalizeCompletedProbe: true,
-			run: () => this.probeDelegate.doctor()
-		});
+			run: () => this.delegate.doctor()
+		}));
 	}
 	async ensureSession(input) {
 		const resource = assertAcpxSessionOwnerLocator(input, this.legacyBareSessionKeys);
-		return await this.sessionEnsureQueue.enqueue(resource.trim() || resource, () => this.ensureSessionUnlocked(input));
+		const generation = this.generationRegistry.currentGeneration(resource);
+		return await generation.ensureQueue.enqueue(resource + "\0" + generation.id, () => this.runInGeneration(input, { generation }, async () => {
+			this.generationRegistry.assertCurrentGeneration(generation);
+			const handle = {
+				...await this.ensureSessionUnlocked(input),
+				[acpxGenerationKey]: generation
+			};
+			if (generation.retired && !this.generationRegistry.isStopping) await this.close({
+				handle,
+				reason: "superseded-initialization",
+				discardPersistentState: true
+			});
+			this.generationRegistry.assertCurrentGeneration(generation);
+			return handle;
+		}));
 	}
 	async ensureSessionUnlocked(logicalInput) {
 		assertSupportedRuntimeSessionMode(logicalInput.mode);
@@ -820,20 +909,23 @@ var AcpxRuntime = class {
 			sessionKey: resolveAcpxSessionResource(logicalInput)
 		};
 		const isCodexAcp = normalizeAgentName(input.agent) === CODEX_ACP_AGENT_ID && isCodexAcpCommand(command);
+		const dropInheritedCodexMax = isCodexAcp && input.thinking === "max" && input.thinkingExplicit === false;
+		const effectiveInput = dropInheritedCodexMax ? { ...input } : input;
+		if (dropInheritedCodexMax) delete effectiveInput.thinking;
 		const claudeModelOverride = isClaudeAcpCommand(command) ? normalizeClaudeAcpModelOverride(input.model) : void 0;
-		const codexClassification = isCodexAcp ? classifyCodexAcpModelRequest(input.model, input.thinking) : void 0;
+		const codexClassification = isCodexAcp ? classifyCodexAcpModelRequest(effectiveInput.model, effectiveInput.thinking) : void 0;
 		if (codexClassification?.kind === "unsupported" && input.modelExplicit) failUnsupportedCodexAcpModel(input.model ?? "");
 		const classifiedCodexOverride = codexClassification?.kind === "override" ? codexClassification.override : codexClassification?.thinkingOverride;
 		const codexModelOverride = classifiedCodexOverride && Object.keys(classifiedCodexOverride).length > 0 ? classifiedCodexOverride : void 0;
-		const requestedModel = input.model?.trim();
+		const requestedModel = effectiveInput.model?.trim();
 		const appliedModel = isCodexAcp && requestedModel ? codexModelOverride?.model ? {
 			kind: "applied",
 			model: requestedModel
 		} : { kind: "dropped" } : void 0;
-		const ensureInput = isCodexAcp ? withCodexSessionModel(input, codexModelOverride) : claudeModelOverride ? {
-			...input,
+		const ensureInput = isCodexAcp ? withCodexSessionModel(effectiveInput, codexModelOverride) : claudeModelOverride ? {
+			...effectiveInput,
 			model: claudeModelOverride
-		} : input;
+		} : effectiveInput;
 		const stableLaunchCommand = codexModelOverride && command ? appendCodexAcpConfigOverrides(command, codexModelOverride) : command;
 		const reusableCommand = await this.readReusablePersistentSessionCommand({
 			sessionKey: input.sessionKey,
@@ -855,7 +947,8 @@ var AcpxRuntime = class {
 				})
 			}),
 			...logicalTarget,
-			...appliedModel ? { appliedModel } : {}
+			...appliedModel ? { appliedModel } : {},
+			...dropInheritedCodexMax ? { appliedThinking: { kind: "dropped" } } : {}
 		};
 	}
 	async *runTurn(input) {
@@ -888,18 +981,27 @@ var AcpxRuntime = class {
 			fallbackCode: "ACP_TURN_FAILED",
 			run
 		});
-		const snapshotPromise = this.loadOperationSnapshotForHandle(input.handle);
-		const turnLeasePromise = snapshotPromise.then(({ record }) => this.prepareProcessLeaseForOperation(input.handle, record));
-		const turnPromise = Promise.all([snapshotPromise, turnLeasePromise]).then(([snapshot]) => {
-			const { command } = snapshot;
+		const turnPromise = this.loadOperationSnapshotForHandle(input.handle).then((snapshot) => {
+			const { command, generation } = snapshot;
+			this.generationRegistry.assertCurrentGeneration(generation);
 			const delegate = this.resolveDelegateForOperationSnapshot(input.handle, snapshot);
-			return withTurnDiagnostics(command, async () => ({
-				command,
-				turn: delegate.startTurn({
-					...toAcpxResourceInput(input),
-					timeoutMs: 0
-				})
-			}));
+			return this.sessionScope.run(input.handle, () => acpxOperationScope.run({ generation }, () => withTurnDiagnostics(command, async () => {
+				const release = this.generationRegistry.retainGenerationOperation(generation, snapshot.record?.acpxRecordId ?? input.handle.acpxRecordId ?? generation.resource);
+				try {
+					const turn = delegate.startTurn({
+						...toAcpxResourceInput(input),
+						timeoutMs: 0
+					});
+					turn.result.then(release, release);
+					return {
+						command,
+						turn
+					};
+				} catch (error) {
+					release();
+					throw error;
+				}
+			})));
 		});
 		return {
 			requestId: input.requestId,
@@ -915,7 +1017,7 @@ var AcpxRuntime = class {
 					await withTurnDiagnostics(command, () => Promise.reject(error));
 				}
 			} },
-			result: this.finalizeProcessLeaseAfter(input.handle, turnLeasePromise, turnPromise.then(({ command, turn }) => withTurnDiagnostics(command, async () => {
+			result: turnPromise.then(({ command, turn }) => withTurnDiagnostics(command, async () => {
 				const result = await turn.result;
 				if (result.status !== "failed" || !isCodexAcpCommand(command) || !isGenericInternalAcpErrorMessage(result.error.message)) return result;
 				const stderrTail = await this.readCodexTurnFailureStderr({ handle: input.handle });
@@ -928,7 +1030,7 @@ var AcpxRuntime = class {
 						message: `Internal error: ${stderrTail}`
 					}
 				};
-			}))),
+			})),
 			cancel(inputArgs) {
 				return turnPromise.then(({ turn }) => turn.cancel(inputArgs));
 			},
@@ -937,20 +1039,33 @@ var AcpxRuntime = class {
 			}
 		};
 	}
-	getCapabilities(input) {
-		return this.delegate.getCapabilities(input?.handle ? toAcpxResourceInput({ handle: input.handle }) : input);
+	async getCapabilities(input) {
+		const capabilities = await this.delegate.getCapabilities(input?.handle ? toAcpxResourceInput({ handle: input.handle }) : input);
+		return {
+			...capabilities,
+			controls: capabilities.controls.filter((control) => control !== "session/set_model")
+		};
 	}
 	async getStatus(input) {
 		const snapshot = await this.loadOperationSnapshotForHandle(input.handle);
-		return this.resolveDelegateForOperationSnapshot(input.handle, snapshot).getStatus(toAcpxResourceInput(input));
+		return this.runInGeneration(input.handle, {
+			generation: snapshot.generation,
+			recordId: snapshot.record?.acpxRecordId
+		}, () => this.resolveDelegateForOperationSnapshot(input.handle, snapshot).getStatus(toAcpxResourceInput(input)));
 	}
 	async setMode(input) {
 		const snapshot = await this.loadOperationSnapshotForHandle(input.handle);
-		await this.runWithProcessLeaseForHandle(input.handle, snapshot.record, () => this.resolveDelegateForOperationSnapshot(input.handle, snapshot).setMode(toAcpxResourceInput(input)));
+		await this.runInGeneration(input.handle, {
+			generation: snapshot.generation,
+			recordId: snapshot.record?.acpxRecordId
+		}, () => this.resolveDelegateForOperationSnapshot(input.handle, snapshot).setMode(toAcpxResourceInput(input)));
 	}
 	async setConfigOption(input) {
 		const snapshot = await this.loadOperationSnapshotForHandle(input.handle);
-		return await this.runWithProcessLeaseForHandle(input.handle, snapshot.record, () => this.setConfigOptionUnlocked(input, snapshot));
+		return await this.runInGeneration(input.handle, {
+			generation: snapshot.generation,
+			recordId: snapshot.record?.acpxRecordId
+		}, () => this.setConfigOptionUnlocked(input, snapshot));
 	}
 	async setConfigOptionUnlocked(logicalInput, snapshot) {
 		const { command } = snapshot;
@@ -969,6 +1084,7 @@ var AcpxRuntime = class {
 					key: "model",
 					value: override.model
 				}) : void 0;
+				this.generationRegistry.assertCurrentGeneration(snapshot.generation);
 				if (override.reasoningEffort) return await delegate.setConfigOption({
 					...input,
 					key: "reasoning_effort",
@@ -995,39 +1111,54 @@ var AcpxRuntime = class {
 	}
 	async cancel(input) {
 		const snapshot = await this.loadOperationSnapshotForHandle(input.handle);
-		await this.resolveDelegateForOperationSnapshot(input.handle, snapshot).cancel(toAcpxResourceInput(input));
+		await this.runInGeneration(input.handle, {
+			generation: snapshot.generation,
+			recordId: snapshot.record?.acpxRecordId
+		}, () => this.resolveDelegateForOperationSnapshot(input.handle, snapshot).cancel(toAcpxResourceInput(input)));
 	}
 	async prepareFreshSession(input) {
 		const resource = assertAcpxSessionOwnerLocator(input, this.legacyBareSessionKeys);
-		this.sessionStore.markFresh(resource);
+		this.generationRegistry.prepareFresh(resource);
 		this.legacyBareSessionKeys.delete(resource);
 	}
 	async close(input) {
-		const snapshot = await this.loadOperationSnapshotForHandle(input.handle);
-		const closeLease = await this.prepareProcessLeaseForOperation(input.handle, snapshot.record);
-		let cleanupSucceeded = false;
-		try {
+		const generation = this.generationForHandle(input.handle);
+		await this.runInGeneration(input.handle, { generation }, async () => {
+			const snapshot = await this.loadOperationSnapshotForHandle(input.handle, true, generation);
 			const delegate = this.resolveDelegateForOperationSnapshot(input.handle, snapshot);
-			const handle = toAcpxResourceInput(input).handle;
-			try {
-				await delegate.close({
-					handle,
-					reason: input.reason,
-					discardPersistentState: input.discardPersistentState
+			await acpxOperationScope.run({
+				generation,
+				closeRecord: snapshot.record
+			}, async () => {
+				if (input.discardPersistentState && decodeAcpxRuntimeHandleState(input.handle.runtimeSessionName)?.mode !== "oneshot") {
+					this.generationRegistry.retireGeneration(generation);
+					this.legacyBareSessionKeys.delete(generation.resource);
+				}
+				const cleanup = await prepareAcpxProcessCleanup({
+					record: snapshot.record,
+					command: snapshot.command,
+					sessionKey: resolveAcpxSessionResource(input.handle),
+					gatewayInstanceId: this.gatewayInstanceId,
+					wrapperRoot: this.wrapperRoot,
+					leaseStore: this.processLeaseStore,
+					deps: this.processCleanupDeps
+				}).catch((error) => async () => {
+					throw error;
 				});
-				if (this.managedToolsSessionDelegates.get(handle.sessionKey) === delegate) this.managedToolsSessionDelegates.delete(handle.sessionKey);
-			} finally {
-				await this.cleanupProcessTreeForRecord(input.handle, snapshot.record);
-				cleanupSucceeded = true;
-			}
-			if (input.discardPersistentState) await this.prepareFreshSession({
-				...input.handle,
-				persistedHandle: input.handle
+				try {
+					await delegate.close(toAcpxResourceInput(input));
+				} finally {
+					await cleanup();
+				}
+				const recordId = snapshot.record?.acpxRecordId ?? input.handle.acpxRecordId ?? generation.resource;
+				const currentRecord = generation.records.get(recordId);
+				if (!currentRecord || currentRecord.acpSessionId === snapshot.record?.acpSessionId && currentRecord.createdAt === snapshot.record?.createdAt) {
+					generation.records.delete(recordId);
+					if (generation.activeRecordOperations.has(recordId)) generation.closedRecordIds.add(recordId);
+				}
+				generation.closeCompleted = true;
 			});
-		} finally {
-			if (cleanupSucceeded) await this.finalizeProcessLeaseForOperation(input.handle, closeLease);
-			else await this.releaseProcessLeaseAfterUncertainFailure(closeLease);
-		}
+		});
 	}
 };
 /** Test-only hooks for ACPX runtime behavior that is otherwise private. */