@openclaw/codex 2026.7.1 → 2026.7.2-beta.2

package/dist/conversation-control-CGkBlfc5.js

@@ -0,0 +1,286 @@
+import { a as getLeasedSharedCodexAppServerClient, c as releaseLeasedSharedCodexAppServerClient, p as withLeasedCodexAppServerClientStartSelectionRetry, s as releaseCodexAppServerClientLease } from "./shared-client-JiAnW6pc.js";
+import { _ as isCodexFastServiceTier, a as isCodexAppServerNativeAuthProfile, b as resolveCodexAppServerRuntimeOptions, o as normalizeCodexAppServerBindingModelProvider, r as bindingStoreKey, w as resolveCodexModelBackedReviewerPolicyContext } from "./session-binding-h1mmCGnl.js";
+import { _ as resolveCodexBindingModelProviderFallback, h as resolveCodexAppServerRequestModelSelection } from "./thread-lifecycle-CN_pPtPh.js";
+import { d as CODEX_CONTROL_METHODS, r as formatCodexDisplayText } from "./command-formatters-Dq9InZUK.js";
+import { a as resolveCodexBindingAppServerConnection } from "./notification-correlation-KmfV4EkP.js";
+import { ModelSelectionLockedError } from "openclaw/plugin-sdk/model-session-runtime";
+//#region extensions/codex/src/command-authorization.ts
+const CODEX_NATIVE_EXECUTION_AUTH_ERROR = "Only an owner or operator.admin can control Codex native execution.";
+function canMutateCodexHost(ctx) {
+	return ctx.senderIsOwner === true || ctx.gatewayClientScopes?.includes("operator.admin") === true;
+}
+//#endregion
+//#region extensions/codex/src/conversation-control.ts
+const CODEX_CONVERSATION_CONTROL_STATE = Symbol.for("openclaw.codex.conversationControl");
+function getActiveTurns() {
+	const globalState = globalThis;
+	globalState[CODEX_CONVERSATION_CONTROL_STATE] ??= /* @__PURE__ */ new Map();
+	return globalState[CODEX_CONVERSATION_CONTROL_STATE];
+}
+function trackCodexConversationActiveTurn(active) {
+	const activeTurns = getActiveTurns();
+	const key = bindingStoreKey(active.identity);
+	activeTurns.set(key, active);
+	return () => {
+		if (activeTurns.get(key)?.turnId === active.turnId) activeTurns.delete(key);
+	};
+}
+function readCodexConversationActiveTurn(identity) {
+	return getActiveTurns().get(bindingStoreKey(identity));
+}
+async function stopCodexConversationTurn(params) {
+	const active = readCodexConversationActiveTurn(params.identity);
+	if (!active) return {
+		stopped: false,
+		message: "No active Codex run to stop."
+	};
+	const lookup = buildBindingLookup(params);
+	const binding = await params.bindingStore.read(params.identity);
+	if (binding?.threadId !== active.threadId) return {
+		stopped: false,
+		message: "The active Codex run no longer matches this session binding."
+	};
+	const connection = resolveCodexBindingAppServerConnection({
+		binding,
+		authProfileId: binding?.authProfileId,
+		pluginConfig: params.pluginConfig
+	});
+	const runtime = connection.appServer;
+	const client = active.client ?? await getLeasedSharedCodexAppServerClient({
+		startOptions: runtime.start,
+		timeoutMs: runtime.requestTimeoutMs,
+		authProfileId: connection.clientAuthProfileId,
+		...lookup
+	});
+	try {
+		await client.request("turn/interrupt", {
+			threadId: active.threadId,
+			turnId: active.turnId
+		}, { timeoutMs: runtime.requestTimeoutMs });
+	} finally {
+		if (!active.client) releaseLeasedSharedCodexAppServerClient(client);
+	}
+	return {
+		stopped: true,
+		message: "Codex stop requested."
+	};
+}
+async function steerCodexConversationTurn(params) {
+	const active = readCodexConversationActiveTurn(params.identity);
+	const text = params.message.trim();
+	if (!text) return {
+		steered: false,
+		message: "Usage: /codex steer <message>"
+	};
+	if (!active) return {
+		steered: false,
+		message: "No active Codex run to steer."
+	};
+	const lookup = buildBindingLookup(params);
+	const binding = await params.bindingStore.read(params.identity);
+	if (binding?.threadId !== active.threadId) return {
+		steered: false,
+		message: "The active Codex run no longer matches this session binding."
+	};
+	const connection = resolveCodexBindingAppServerConnection({
+		binding,
+		authProfileId: binding?.authProfileId,
+		pluginConfig: params.pluginConfig
+	});
+	const runtime = connection.appServer;
+	const client = active.client ?? await getLeasedSharedCodexAppServerClient({
+		startOptions: runtime.start,
+		timeoutMs: runtime.requestTimeoutMs,
+		authProfileId: connection.clientAuthProfileId,
+		...lookup
+	});
+	try {
+		await client.request("turn/steer", {
+			threadId: active.threadId,
+			expectedTurnId: active.turnId,
+			input: [{
+				type: "text",
+				text,
+				text_elements: []
+			}]
+		}, { timeoutMs: runtime.requestTimeoutMs });
+	} finally {
+		if (!active.client) releaseLeasedSharedCodexAppServerClient(client);
+	}
+	return {
+		steered: true,
+		message: "Sent steer message to Codex."
+	};
+}
+async function setCodexConversationModel(params) {
+	const model = params.model.trim();
+	if (!model) return "Usage: /codex model <model>";
+	const lookup = buildBindingLookup(params);
+	const binding = await requireThreadBinding(params.bindingStore, params.identity);
+	if (binding.connectionScope === "supervision") throw new ModelSelectionLockedError();
+	const reviewerPolicyContext = resolveCodexModelBackedReviewerPolicyContext({
+		provider: "codex",
+		model,
+		bindingModelProvider: binding.modelProvider,
+		bindingModel: binding.model,
+		nativeAuthProfile: isCodexAppServerNativeAuthProfile({
+			authProfileId: binding.authProfileId,
+			...lookup
+		})
+	});
+	const runtime = resolveCodexAppServerRuntimeOptions({
+		pluginConfig: params.pluginConfig,
+		modelProvider: reviewerPolicyContext.modelProvider,
+		model: reviewerPolicyContext.model,
+		config: params.config,
+		agentDir: params.agentDir
+	});
+	const modelSelection = resolveCodexAppServerRequestModelSelection({
+		model,
+		modelProvider: resolveConversationControlModelProvider({
+			authProfileId: binding.authProfileId,
+			bindingModel: binding.model,
+			bindingModelProvider: binding.modelProvider,
+			currentModel: model,
+			...lookup
+		}),
+		authProfileId: binding.authProfileId,
+		...lookup
+	});
+	const resumed = await resumeThreadWithOverrides({
+		runtime,
+		threadId: binding.threadId,
+		authProfileId: binding.authProfileId,
+		...lookup,
+		model: modelSelection.model,
+		modelProvider: modelSelection.modelProvider
+	});
+	const response = resumed.response;
+	const nextModel = response.model ?? modelSelection.model;
+	const nextModelProvider = normalizeCodexAppServerBindingModelProvider({
+		authProfileId: binding.authProfileId,
+		modelProvider: response.modelProvider ?? modelSelection.modelProvider,
+		...lookup
+	});
+	const modelChanged = nextModel !== binding.model || nextModelProvider !== binding.modelProvider;
+	await patchThreadBinding(params.bindingStore, params.identity, binding.threadId, {
+		clientId: resumed.clientId,
+		cwd: response.thread.cwd ?? binding.cwd,
+		model: nextModel,
+		modelProvider: nextModelProvider,
+		...modelChanged && binding.contextEngine?.projection ? { contextEngine: {
+			...binding.contextEngine,
+			projection: void 0
+		} } : {},
+		approvalPolicy: binding.approvalPolicy,
+		sandbox: binding.sandbox,
+		serviceTier: binding.serviceTier ?? runtime.serviceTier ?? void 0
+	});
+	return `Codex model set to ${formatCodexDisplayText(response.model ?? model)}.`;
+}
+async function setCodexConversationFastMode(params) {
+	const binding = await requireThreadBinding(params.bindingStore, params.identity);
+	if (params.enabled == null) return `Codex fast mode: ${isCodexFastServiceTier(binding.serviceTier) ? "on" : "off"}.`;
+	const serviceTier = params.enabled ? "priority" : "flex";
+	await patchThreadBinding(params.bindingStore, params.identity, binding.threadId, { serviceTier });
+	return `Codex fast mode ${params.enabled ? "enabled" : "disabled"}.`;
+}
+async function setCodexConversationPermissions(params) {
+	const binding = await requireThreadBinding(params.bindingStore, params.identity);
+	if (!params.mode) return `Codex permissions: ${formatPermissionsMode(binding)}.`;
+	const policy = permissionsForMode(params.mode);
+	await patchThreadBinding(params.bindingStore, params.identity, binding.threadId, {
+		approvalPolicy: policy.approvalPolicy,
+		sandbox: policy.sandbox
+	});
+	return `Codex permissions set to ${params.mode === "yolo" ? "full access" : "default"}.`;
+}
+function parseCodexFastModeArg(arg) {
+	const normalized = arg?.trim().toLowerCase();
+	if (!normalized || normalized === "status") return;
+	if (normalized === "on" || normalized === "true" || normalized === "fast") return true;
+	if (normalized === "off" || normalized === "false" || normalized === "flex") return false;
+}
+function parseCodexPermissionsModeArg(arg) {
+	const normalized = arg?.trim().toLowerCase();
+	if (!normalized || normalized === "status") return;
+	if (normalized === "yolo" || normalized === "full" || normalized === "full-access") return "yolo";
+	if (normalized === "default" || normalized === "guardian") return "default";
+}
+function formatPermissionsMode(binding) {
+	return binding.approvalPolicy === "never" && binding.sandbox === "danger-full-access" ? "full access" : "default";
+}
+async function requireThreadBinding(bindingStore, identity) {
+	const binding = await bindingStore.read(identity);
+	if (!binding?.threadId) throw new Error("No Codex thread is attached to this OpenClaw session yet.");
+	return binding;
+}
+async function patchThreadBinding(bindingStore, identity, threadId, patch) {
+	if (!await bindingStore.mutate(identity, {
+		kind: "patch",
+		threadId,
+		patch
+	})) throw new Error("Codex thread binding changed while applying the control update.");
+}
+async function resumeThreadWithOverrides(params) {
+	const runtime = params.runtime;
+	const clientOptions = {
+		startOptions: runtime.start,
+		timeoutMs: runtime.requestTimeoutMs,
+		authProfileId: params.authProfileId,
+		...buildBindingLookup(params)
+	};
+	let client = await getLeasedSharedCodexAppServerClient(clientOptions);
+	const clientLease = { client };
+	try {
+		return {
+			response: await withLeasedCodexAppServerClientStartSelectionRetry({
+				lease: clientLease,
+				options: clientOptions,
+				run: async (requestClient, requestOptions) => await requestClient.request(CODEX_CONTROL_METHODS.resumeThread, {
+					threadId: params.threadId,
+					...params.model ? { model: params.model } : {},
+					...params.modelProvider ? { modelProvider: params.modelProvider } : {},
+					approvalPolicy: params.approvalPolicy ?? runtime.approvalPolicy,
+					sandbox: params.sandbox ?? runtime.sandbox,
+					approvalsReviewer: runtime.approvalsReviewer,
+					...params.serviceTier ? { serviceTier: params.serviceTier } : {}
+				}, requestOptions),
+				onClientChange: (nextClient) => {
+					client = nextClient;
+				}
+			}),
+			clientId: client.getInstanceId()
+		};
+	} finally {
+		releaseCodexAppServerClientLease(clientLease);
+	}
+}
+function buildBindingLookup(params) {
+	const agentDir = params.agentDir?.trim();
+	return {
+		...agentDir ? { agentDir } : {},
+		...params.config ? { config: params.config } : {}
+	};
+}
+function resolveConversationControlModelProvider(params) {
+	const modelProvider = resolveCodexBindingModelProviderFallback({
+		currentModel: params.currentModel,
+		bindingModel: params.bindingModel,
+		bindingModelProvider: params.bindingModelProvider
+	})?.trim();
+	if (!modelProvider || modelProvider.toLowerCase() === "codex") return;
+	if (isCodexAppServerNativeAuthProfile(params) && modelProvider.toLowerCase() === "openai") return;
+	return modelProvider.toLowerCase() === "openai" ? "openai" : modelProvider;
+}
+function permissionsForMode(mode) {
+	return mode === "yolo" ? {
+		approvalPolicy: "never",
+		sandbox: "danger-full-access"
+	} : {
+		approvalPolicy: "on-request",
+		sandbox: "workspace-write"
+	};
+}
+//#endregion
+export { setCodexConversationFastMode as a, steerCodexConversationTurn as c, CODEX_NATIVE_EXECUTION_AUTH_ERROR as d, canMutateCodexHost as f, readCodexConversationActiveTurn as i, stopCodexConversationTurn as l, parseCodexFastModeArg as n, setCodexConversationModel as o, parseCodexPermissionsModeArg as r, setCodexConversationPermissions as s, formatPermissionsMode as t, trackCodexConversationActiveTurn as u };

package/dist/doctor-contract-api.js

@@ -3,8 +3,37 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { listAgentIds, resolveAgentDir, resolveSessionAgentIds } from "openclaw/plugin-sdk/agent-runtime";
 import { isDeepStrictEqual } from "node:util";
-import { listSessionEntries, resolveSessionFilePath, resolveStorePath, updateSessionStoreEntry } from "openclaw/plugin-sdk/session-store-runtime";
+import { patchSessionEntry, resolveStorePath } from "openclaw/plugin-sdk/session-store-runtime";
 import { withFileLock } from "openclaw/plugin-sdk/file-lock";
+//#region extensions/codex/src/migration/session-binding-sidecar-archive.ts
+async function pathExists$1(filePath) {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function firstFreeArchivePath(sourcePath) {
+	for (let index = 2;; index++) {
+		const candidate = `${sourcePath}.migrated.${index}`;
+		if (!await pathExists$1(candidate)) return candidate;
+	}
+}
+async function archiveBindingSidecar(sourcePath) {
+	const archivePath = `${sourcePath}.migrated`;
+	if (!await pathExists$1(archivePath)) {
+		await fs.rename(sourcePath, archivePath);
+		return;
+	}
+	const [sourceBytes, archiveBytes] = await Promise.all([fs.readFile(sourcePath), fs.readFile(archivePath)]);
+	if (sourceBytes.equals(archiveBytes)) {
+		await fs.rm(sourcePath, { force: true });
+		return;
+	}
+	await fs.rename(sourcePath, await firstFreeArchivePath(sourcePath));
+}
+//#endregion
 //#region extensions/codex/src/migration/session-binding-sidecars.ts
 const LEGACY_BINDING_SUFFIX = ".codex-app-server.json";
 const CODEX_AGENT_HARNESS_ID = "codex";
@@ -74,7 +103,7 @@ async function collectLegacyBindingSources(params, options = {}) {
 		return source;
 	};
 	for (const surface of surfaces) {
-		const sidecars = surface.scan ? walkSidecars(surface.root) : iterateIndexedSidecars(surface, params);
+		const sidecars = surface.scan ? walkSidecars(surface.root) : iterateIndexedSidecars(surface);
 		for await (const sidecarPath of sidecars) {
 			const source = await addSource(sidecarPath, surface);
 			if (options.firstOnly) return {
@@ -103,54 +132,37 @@ async function readLegacySessionIndex(storePath) {
 		return { failure: `session index ${storePath} could not be read (invalid JSON)` };
 	}
 	if (!isRecord(raw)) return { failure: `session index ${storePath} has invalid entries` };
-	let normalizedEntries;
-	try {
-		normalizedEntries = listSessionEntries({
-			storePath,
-			hydrateSkillPromptRefs: false
-		});
-	} catch {
-		return { failure: `session index ${storePath} could not be normalized` };
-	}
-	const normalizedByKey = new Map(normalizedEntries.map(({ sessionKey, entry }) => [sessionKey, entry]));
 	const entries = [];
 	for (const [sessionKey, value] of Object.entries(raw)) {
 		if (!isRecord(value)) return { failure: `session index ${storePath} has invalid entries` };
 		if (value.sessionId === void 0) continue;
-		const rawSessionId = typeof value.sessionId === "string" ? value.sessionId.trim() : "";
-		const sessionId = normalizedByKey.get(sessionKey)?.sessionId?.trim() ?? "";
+		const sessionId = typeof value.sessionId === "string" ? value.sessionId.trim() : "";
 		const sessionFile = value.sessionFile;
 		const lifecycleRevision = value.lifecycleRevision;
 		const agentHarnessId = value.agentHarnessId;
-		if (!sessionId || sessionId !== rawSessionId || sessionFile !== void 0 && typeof sessionFile !== "string" || lifecycleRevision !== void 0 && typeof lifecycleRevision !== "string" || agentHarnessId !== void 0 && typeof agentHarnessId !== "string") return { failure: `session index ${storePath} has invalid entries` };
+		if (!isSafeLegacySessionId(value.sessionId) || sessionFile !== void 0 && typeof sessionFile !== "string" || lifecycleRevision !== void 0 && typeof lifecycleRevision !== "string" || agentHarnessId !== void 0 && typeof agentHarnessId !== "string") return { failure: `session index ${storePath} has invalid entries` };
 		entries.push({
 			sessionKey,
 			entry: {
 				sessionId,
 				...typeof sessionFile === "string" ? { sessionFile } : {},
 				...typeof lifecycleRevision === "string" ? { lifecycleRevision } : {},
-				...typeof agentHarnessId === "string" ? { agentHarnessId } : {}
+				...typeof agentHarnessId === "string" ? { agentHarnessId } : {},
+				...typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt) && value.updatedAt >= 0 ? { updatedAt: value.updatedAt } : {}
 			}
 		});
 	}
 	return { entries };
 }
-async function* iterateIndexedSidecars(surface, params) {
+async function* iterateIndexedSidecars(surface) {
 	for (const storePath of surface.storePaths) {
 		const index = await readLegacySessionIndex(storePath);
 		if ("failure" in index) continue;
-		for (const { sessionKey, entry } of index.entries) {
-			const agentId = resolveLegacyBindingOwnerAgentId({
-				sessionKey,
-				config: params.config,
-				storeAgentIds: surface.agentIds
-			});
+		for (const { entry } of index.entries) {
+			if ((entry.sessionFile?.trim() ?? "").startsWith("sqlite:")) continue;
 			let transcriptPath;
 			try {
-				transcriptPath = resolveSessionFilePath(entry.sessionId, entry, {
-					sessionsDir: path.dirname(storePath),
-					agentId
-				});
+				transcriptPath = await resolveLegacySessionFileLocator(path.dirname(storePath), entry, entry.sessionId);
 			} catch {
 				continue;
 			}
@@ -203,35 +215,34 @@ async function collectBindingOwners(sources, surfaces, params) {
 				config: params.config,
 				storeAgentIds: storeAgentIds.get(storePath)
 			});
-			let effectiveTranscriptPath;
+			let legacyTranscriptPath;
+			let canonicalLegacyTranscriptPath;
 			try {
-				effectiveTranscriptPath = resolveSessionFilePath(sessionId, entry, {
-					sessionsDir,
-					agentId
-				});
+				legacyTranscriptPath = await resolveLegacySessionFileLocator(sessionsDir, entry, sessionId);
+				canonicalLegacyTranscriptPath = await canonicalizePath(legacyTranscriptPath);
 			} catch {
 				failures.push(`session index ${storePath} has an invalid locator for ${sessionKey}`);
 				continue;
 			}
-			const transcriptPath = await canonicalizePath(effectiveTranscriptPath);
-			if (!sourcePaths.has(transcriptPath)) continue;
+			if (!sourcePaths.has(canonicalLegacyTranscriptPath)) continue;
 			const owner = {
 				agentId,
 				sessionId,
 				sessionKey,
 				storePath,
-				transcriptPath: effectiveTranscriptPath,
+				transcriptPath: legacyTranscriptPath,
 				...entry.lifecycleRevision ? { lifecycleRevision: entry.lifecycleRevision } : {},
-				...entry.agentHarnessId?.trim() ? { agentHarnessId: entry.agentHarnessId.trim() } : {}
+				...entry.agentHarnessId?.trim() ? { agentHarnessId: entry.agentHarnessId.trim() } : {},
+				...entry.updatedAt !== void 0 ? { updatedAt: entry.updatedAt } : {}
 			};
-			const candidates = owners.get(transcriptPath) ?? /* @__PURE__ */ new Map();
+			const candidates = owners.get(canonicalLegacyTranscriptPath) ?? /* @__PURE__ */ new Map();
 			const ownerKey = `${agentId}\0${sessionId}\0${sessionKey}\0${canonicalStorePath}`;
 			const configuredStorePath = resolveStorePath(params.config.session?.store, {
 				agentId,
 				env: params.env
 			});
 			if (!candidates.has(ownerKey) || storePath === configuredStorePath) candidates.set(ownerKey, owner);
-			owners.set(transcriptPath, candidates);
+			owners.set(canonicalLegacyTranscriptPath, candidates);
 		}
 	}
 	return {
@@ -239,6 +250,16 @@ async function collectBindingOwners(sources, surfaces, params) {
 		failures
 	};
 }
+async function resolveLegacySessionFileLocator(sessionsDir, entry, sessionId) {
+	const base = path.resolve(sessionsDir);
+	const fallback = path.join(base, `${sessionId}.jsonl`);
+	const sessionFile = entry.sessionFile?.trim();
+	if (!sessionFile) return fallback;
+	const candidate = path.resolve(base, sessionFile);
+	const [canonicalBase, canonicalCandidate] = await Promise.all([canonicalizePathForContainment(base), canonicalizePathForContainment(candidate)]);
+	if (!isPathWithin(canonicalBase, canonicalCandidate)) throw new Error("legacy session file locator escapes its session directory");
+	return candidate;
+}
 function resolveLegacyBindingOwnerAgentId(params) {
 	if (params.sessionKey.trim().toLowerCase().startsWith("agent:")) return resolveSessionAgentIds({
 		sessionKey: params.sessionKey,
@@ -271,12 +292,17 @@ async function migrateSource(source, candidates, params, store) {
 		importedKeys,
 		warning: `Left Codex binding sidecar in place because ${reason}: ${source.sidecarPath}`
 	});
+	const retainNotice = (reason) => ({
+		archived: false,
+		importedKeys,
+		notice: `Left Codex binding sidecar in place because ${reason}: ${source.sidecarPath}`
+	});
 	const owner = candidates.length === 1 ? candidates[0] : void 0;
 	try {
 		return await withFileLock(source.sidecarPath, LEGACY_BINDING_LOCK_OPTIONS, async () => {
 			const [contents, stat] = await Promise.all([fs.readFile(source.sidecarPath, "utf8"), fs.stat(source.sidecarPath)]);
 			const raw = JSON.parse(contents);
-			const [{ bindingStoreKey, createStoredCodexAppServerBinding, normalizeStoredCodexAppServerBindingFingerprints, readStoredCodexAppServerBinding }, { legacyCodexConversationBindingId }] = await Promise.all([import("./session-binding-C1ZXdP-x.js").then((n) => n.c), import("./conversation-binding-data-BHRpYbX3.js").then((n) => n.t)]);
+			const [{ bindingStoreKey, createStoredCodexAppServerBinding, normalizeStoredCodexAppServerBindingFingerprints, readStoredCodexAppServerBinding }, { legacyCodexConversationBindingId }] = await Promise.all([import("./session-binding-h1mmCGnl.js").then((n) => n.l), import("./conversation-binding-data-BHRpYbX3.js").then((n) => n.t)]);
 			const agentId = owner?.agentId ?? (source.agentIds.size === 1 ? [...source.agentIds][0] : void 0);
 			const baseStored = createStoredCodexAppServerBinding(raw, {
 				now: stat.mtime.toISOString(),
@@ -287,7 +313,7 @@ async function migrateSource(source, candidates, params, store) {
 			});
 			if (!baseStored) return retain("its binding is invalid");
 			if (candidates.length > 1) return retain(`${candidates.length} matching session owners make ownership ambiguous`);
-			if (owner?.agentHarnessId && owner.agentHarnessId !== CODEX_AGENT_HARNESS_ID) return retain(`its session is owned by agent harness ${owner.agentHarnessId}`);
+			if (owner?.agentHarnessId && owner.agentHarnessId !== CODEX_AGENT_HARNESS_ID) return retainNotice(`its session is owned by agent harness ${owner.agentHarnessId}`);
 			const sourceSessionFile = typeof raw.sessionFile === "string" && raw.sessionFile.trim() ? raw.sessionFile : source.transcriptPath;
 			const ownerSessionFile = typeof raw.sessionFile === "string" && raw.sessionFile.trim() ? raw.sessionFile : owner?.transcriptPath;
 			const conversationKeys = [sourceSessionFile, ...ownerSessionFile && ownerSessionFile !== sourceSessionFile ? [ownerSessionFile] : []].map((sessionFile) => bindingStoreKey({
@@ -354,7 +380,7 @@ async function migrateSource(source, candidates, params, store) {
 				if (!hasExpected(await store.lookup(entry.key), entry.value)) return retain(`canonical plugin state changed at ${entry.key}`);
 			}
 			if (owner) {
-				const ownershipWarning = await recordSessionOwner(owner);
+				const ownershipWarning = await recordSessionOwner(owner, params.env);
 				if (ownershipWarning) {
 					if (sessionEntry?.value.state === "active") {
 						const update = store.update;
@@ -372,7 +398,7 @@ async function migrateSource(source, candidates, params, store) {
 						});
 						if (hasExpected(await store.lookup(sessionEntry.key), sessionEntry.value)) return retain(`${ownershipWarning}; its stale session binding could not be retired`);
 					}
-					return retain(ownershipWarning);
+					return retainNotice(ownershipWarning);
 				}
 				for (const entry of entries) if (!hasExpected(await store.lookup(entry.key), entry.value)) return retain(`canonical plugin state changed at ${entry.key}`);
 			}
@@ -390,18 +416,39 @@ async function migrateSource(source, candidates, params, store) {
 		return retain(`migration or archiving failed: ${String(error)}`);
 	}
 }
-async function recordSessionOwner(owner) {
+async function recordSessionOwner(owner, env) {
+	const currentIndex = await readLegacySessionIndex(owner.storePath);
+	if ("failure" in currentIndex) return "its legacy session owner could not be revalidated";
+	const currentOwner = currentIndex.entries.find(({ sessionKey }) => sessionKey === owner.sessionKey);
+	if (!currentOwner || currentOwner.entry.sessionId !== owner.sessionId) return "its session owner changed before Codex ownership could be recorded";
+	let currentTranscriptPath;
+	try {
+		currentTranscriptPath = await resolveLegacySessionFileLocator(path.dirname(owner.storePath), currentOwner.entry, currentOwner.entry.sessionId);
+	} catch {
+		return "its session owner changed before Codex ownership could be recorded";
+	}
+	if (await canonicalizePath(currentTranscriptPath) !== await canonicalizePath(owner.transcriptPath) || currentOwner.entry.lifecycleRevision !== owner.lifecycleRevision) return "its session owner changed before Codex ownership could be recorded";
+	const legacyHarnessId = currentOwner.entry.agentHarnessId?.trim();
+	if (currentOwner.entry.agentHarnessId !== void 0 && !legacyHarnessId) return "its session owner changed before Codex ownership could be recorded";
+	if (legacyHarnessId && legacyHarnessId !== CODEX_AGENT_HARNESS_ID) return `its session is owned by agent harness ${legacyHarnessId}`;
 	let observedForeignHarness;
-	const updated = await updateSessionStoreEntry({
+	const updated = await patchSessionEntry({
+		agentId: owner.agentId,
+		env,
+		fallbackEntry: {
+			sessionId: owner.sessionId,
+			updatedAt: currentOwner.entry.updatedAt ?? owner.updatedAt ?? 0,
+			...owner.lifecycleRevision ? { lifecycleRevision: owner.lifecycleRevision } : {}
+		},
+		preserveActivity: true,
+		requireWriteSuccess: true,
+		skipMaintenance: true,
 		storePath: owner.storePath,
 		sessionKey: owner.sessionKey,
-		skipMaintenance: true,
-		requireWriteSuccess: true,
 		update: (entry) => {
-			const transcriptPath = resolveOwnerTranscriptPath(owner, entry);
-			if (entry.sessionId.trim() !== owner.sessionId || transcriptPath !== owner.transcriptPath || entry.lifecycleRevision !== owner.lifecycleRevision) return null;
+			if (entry.sessionId.trim() !== owner.sessionId || entry.lifecycleRevision !== owner.lifecycleRevision) return null;
 			const harnessId = typeof entry.agentHarnessId === "string" ? entry.agentHarnessId.trim() : void 0;
-			if (entry.agentHarnessId !== void 0 && harnessId === void 0) return null;
+			if (entry.agentHarnessId !== void 0 && !harnessId) return null;
 			if (harnessId && harnessId !== CODEX_AGENT_HARNESS_ID) {
 				observedForeignHarness = harnessId;
 				return null;
@@ -410,21 +457,10 @@ async function recordSessionOwner(owner) {
 		}
 	});
 	if (!updated) return observedForeignHarness ? `its session is owned by agent harness ${observedForeignHarness}` : "its session owner changed before Codex ownership could be recorded";
-	const transcriptPath = resolveOwnerTranscriptPath(owner, updated);
-	if (updated.sessionId.trim() !== owner.sessionId || transcriptPath !== owner.transcriptPath || updated.lifecycleRevision !== owner.lifecycleRevision) return "its session owner changed before Codex ownership could be recorded";
+	if (updated.sessionId.trim() !== owner.sessionId || updated.lifecycleRevision !== owner.lifecycleRevision) return "its session owner changed before Codex ownership could be recorded";
 	const harnessId = updated.agentHarnessId?.trim();
 	return harnessId === CODEX_AGENT_HARNESS_ID ? void 0 : harnessId ? `its session is owned by agent harness ${harnessId}` : "Codex harness ownership could not be recorded on its session";
 }
-function resolveOwnerTranscriptPath(owner, entry) {
-	try {
-		return resolveSessionFilePath(entry.sessionId, entry, {
-			sessionsDir: path.dirname(owner.storePath),
-			agentId: owner.agentId
-		});
-	} catch {
-		return;
-	}
-}
 async function readDirectoryEntries(directory) {
 	try {
 		return await fs.readdir(directory, { withFileTypes: true });
@@ -448,6 +484,11 @@ async function isRegularFile(filePath) {
 function isRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function isSafeLegacySessionId(value) {
+	if (typeof value !== "string") return false;
+	const trimmed = value.trim();
+	return trimmed.length > 0 && trimmed.length <= 255 && /^[A-Za-z0-9][A-Za-z0-9._:@-]*$/.test(trimmed);
+}
 function isPathWithin(root, candidate) {
 	const relative = path.relative(root, candidate);
 	return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
@@ -459,6 +500,20 @@ async function canonicalizePath(filePath) {
 		return path.resolve(filePath);
 	}
 }
+async function canonicalizePathForContainment(filePath) {
+	const resolved = path.resolve(filePath);
+	const suffix = [];
+	let probe = resolved;
+	while (true) try {
+		const realProbe = await fs.realpath(probe);
+		return suffix.length === 0 ? realProbe : path.join(realProbe, ...suffix.toReversed());
+	} catch {
+		const parent = path.dirname(probe);
+		if (parent === probe) return resolved;
+		suffix.push(path.basename(probe));
+		probe = parent;
+	}
+}
 async function pathExists(filePath) {
 	try {
 		await fs.access(filePath);
@@ -467,25 +522,6 @@ async function pathExists(filePath) {
 		return false;
 	}
 }
-async function firstFreeArchivePath(sourcePath) {
-	for (let index = 2;; index++) {
-		const candidate = `${sourcePath}.migrated.${index}`;
-		if (!await pathExists(candidate)) return candidate;
-	}
-}
-async function archiveBindingSidecar(sourcePath) {
-	const archivePath = `${sourcePath}.migrated`;
-	if (await pathExists(archivePath)) {
-		const [sourceBytes, archiveBytes] = await Promise.all([fs.readFile(sourcePath), fs.readFile(archivePath)]);
-		if (sourceBytes.equals(archiveBytes)) {
-			await fs.rm(sourcePath, { force: true });
-			return;
-		}
-		await fs.rename(sourcePath, await firstFreeArchivePath(sourcePath));
-		return;
-	}
-	await fs.rename(sourcePath, archivePath);
-}
 const stateMigrations = [{
 	id: "codex-app-server-sidecars-to-plugin-state",
 	label: "Codex app-server thread bindings",
@@ -496,6 +532,7 @@ const stateMigrations = [{
 	async migrateLegacyState(params) {
 		const changes = [];
 		const warnings = [];
+		const notices = [];
 		const { sources, surfaces } = await collectLegacyBindingSources(params);
 		if (sources.length === 0) return {
 			changes,
@@ -519,6 +556,7 @@ const stateMigrations = [{
 		for (const source of sources) {
 			const result = await migrateSource(source, ownerCollection.owners.get(await canonicalizePath(source.transcriptPath)) ?? [], params, store);
 			if (result.warning) warnings.push(result.warning);
+			if (result.notice) notices.push(result.notice);
 			if (result.archived) migrated++;
 			else partialImports += result.importedKeys;
 		}
@@ -526,7 +564,8 @@ const stateMigrations = [{
 		if (partialImports > 0) changes.push(`Migrated ${partialImports} safe Codex app-server binding row(s) to plugin state; retained legacy sidecars needing review`);
 		return {
 			changes,
-			warnings
+			warnings,
+			...notices.length > 0 ? { notices } : {}
 		};
 	}
 }];