@jskit-ai/assistant-core 0.2.6 → 0.2.8

package/src/server/conversation/codexProcess.js

@@ -1,36 +1,33 @@
-import { fileURLToPath } from "node:url";
-import WebSocket from "ws";
 import { spawn } from "node:child_process";
 import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
-import { CodexAppServerJsonRpcClient, socketPathFromCodexAppServerEndpoint } from "./codexClient.js";
-import { createConversationProcessIdentity } from "./localExecution.js";
+import { createConversationProcessIdentity } from "./processIdentity.js";
 import { isRecord, normalizePositiveInteger } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeNullableText } from "./normalize.js";
-import { copyCodexProviderHome, prepareCodexModelCatalog } from "./codexConfiguration.js";
-import { codexDisabledProcessFeatureArguments } from "./codexHomeStorage.js";
+import { prepareCodexModelCatalog } from "./codexConfiguration.js";
 import { startCodexHistoryAdapter } from "./codexHistoryAdapter.js";
 
 const CODEX_APP_SERVER_METADATA_FILE = "runtime.json";
 const CODEX_APP_SERVER_LOCK_DIR = "runtime.lock";
 const CODEX_APP_SERVER_LOCK_TIMEOUT_MS = 10000;
 const CODEX_APP_SERVER_LOCK_STALE_MS = 120000;
-const CODEX_APP_SERVER_EXECUTION_MODES = Object.freeze({ HELPER: "helper", INTERACTIVE: "interactive" });
+export const CODEX_APP_SERVER_EXECUTION_MODES = Object.freeze({ HELPER: "helper", INTERACTIVE: "interactive" });
 const runtimeProcessIdentity = createConversationProcessIdentity();
 
-// Run in the host-owned execution's leader, independently of subscribers.
+// Run in the host-owned execution's leader, independently of subscribers. `env` is the leader's environment.
 export async function runCodexAppServerProcess({
-  runtimeDir, command, args = [], runtimeToken: token, bundled = false, additionalModels = []
+  runtimeDir, command, args = [], runtimeToken: token, bundled = false, additionalModels = [], env
 }) {
+  if (!env) throw new TypeError("runCodexAppServerProcess requires the application's environment, such as process.env.");
   const descriptor = path.join(runtimeDir, "history-adapter.json");
   const startup = new AbortController();
   const abortStartup = () => startup.abort();
   process.once("SIGTERM", abortStartup);
   process.once("SIGINT", abortStartup);
-  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  const codexHome = env.CODEX_HOME || path.join(os.homedir(), ".codex");
   const catalogPath = await prepareCodexModelCatalog({
     command,
     runtimeDir,
@@ -237,7 +234,7 @@ export async function acquireCodexRuntimeLock(runtimeDir = "", {
 
 export const CODEX_APP_SERVER_METADATA_SCHEMA_VERSION = 19;
 
-const CODEX_APP_SERVER_PROVIDER_ID = "codex_app_server";
+export const CODEX_APP_SERVER_PROVIDER_ID = "codex_app_server";
 
 export const CODEX_APP_SERVER_TRANSPORT = Object.freeze({
   UNIX: "unix"
@@ -249,9 +246,9 @@ const CODEX_APP_SERVER_LOG_FILE = "app-server.log";
 
 const CODEX_APP_SERVER_SOCKET_FILE = "app-server.sock";
 
-const CODEX_APP_SERVER_READY_TIMEOUT_MS = 60000;
+export const CODEX_APP_SERVER_READY_TIMEOUT_MS = 60000;
 
-const CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS = 2000;
+export const CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS = 2000;
 
 export const CODEX_APP_SERVER_DESKTOP_BUS_ENV_NAMES = new Set([
   "DBUS_SESSION_BUS_ADDRESS",
@@ -263,16 +260,16 @@ const CODEX_APP_SERVER_HELPER_HOME_DIR = "codex-home";
 
 const CODEX_APP_SERVER_HELPER_WORKSPACE_DIR = "workspace";
 
-const CODEX_APP_SERVER_UNIX_SOCKET_PATH_MAX_BYTES = process.platform === "linux" ? 107 : 103;
+export const CODEX_APP_SERVER_UNIX_SOCKET_PATH_MAX_BYTES = process.platform === "linux" ? 107 : 103;
 
-const CODEX_APP_SERVER_ENDPOINT_STATUS = Object.freeze({
+export const CODEX_APP_SERVER_ENDPOINT_STATUS = Object.freeze({
   MISSING: "missing",
   RESPONSIVE: "responsive",
   TIMEOUT: "timeout",
   UNREACHABLE: "unreachable"
 });
 
-const CODEX_APP_SERVER_RUNTIME_STATUS = Object.freeze({
+export const CODEX_APP_SERVER_RUNTIME_STATUS = Object.freeze({
   EXITED: "exited",
   INCOMPATIBLE: "incompatible",
   LIVE: "live",
@@ -285,7 +282,7 @@ export const CODEX_APP_SERVER_PROCESS_STATE = Object.freeze({
   STOPPED: "stopped"
 });
 
-const CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS = Object.freeze({
+export const CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS = Object.freeze({
   ABSENT: "absent",
   AMBIGUOUS: "ambiguous",
   EXACT: "exact",
@@ -293,7 +290,7 @@ const CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS = Object.freeze({
   MISMATCH: "mismatch"
 });
 
-function stableHash(value) {
+export function stableHash(value) {
   return createHash("sha256")
     .update(String(value || ""))
     .digest("hex")
@@ -329,7 +326,7 @@ export function codexAppServerHelperWorkspaceDir(runtimeDir = "") {
   return path.join(runtimeDir, CODEX_APP_SERVER_HELPER_WORKSPACE_DIR);
 }
 
-function codexAppServerHelperCommandBaseEnv(env = process.env, codexHome = "") {
+export function codexAppServerHelperCommandBaseEnv(env, codexHome = "") {
   const source = isRecord(env) ? env : {};
   const cleared = Object.fromEntries(Object.keys({
     ...process.env,
@@ -355,27 +352,27 @@ function codexAppServerHelperCommandBaseEnv(env = process.env, codexHome = "") {
   };
 }
 
-function codexAppServerLogPath(runtimeDir = "") {
+export function codexAppServerLogPath(runtimeDir = "") {
   return path.join(runtimeDir, CODEX_APP_SERVER_LOG_FILE);
 }
 
-function codexAppServerSocketPath(runtimeDir = "") {
+export function codexAppServerSocketPath(runtimeDir = "") {
   return path.join(runtimeDir, CODEX_APP_SERVER_SOCKET_FILE);
 }
 
-function codexAppServerSocketPathBytes(socketPath = "") {
+export function codexAppServerSocketPathBytes(socketPath = "") {
   return Buffer.byteLength(String(socketPath || ""), "utf8");
 }
 
-function codexAppServerSocketPathTooLong(socketPath = "") {
+export function codexAppServerSocketPathTooLong(socketPath = "") {
   return codexAppServerSocketPathBytes(socketPath) > CODEX_APP_SERVER_UNIX_SOCKET_PATH_MAX_BYTES;
 }
 
-function codexAppServerUnixEndpoint(socketPath = "") {
+export function codexAppServerUnixEndpoint(socketPath = "") {
   return `unix://${socketPath}`;
 }
 
-function codexAppServerProjectTrustOverride(workdir = "") {
+export function codexAppServerProjectTrustOverride(workdir = "") {
   const normalizedWorkdir = normalizeNullableText(workdir);
   if (!normalizedWorkdir) {
     return "";
@@ -400,7 +397,7 @@ export function codexAppServerProcessCwd({
   return normalizeNullableText(runtimeDir) ? path.resolve(runtimeDir) : "";
 }
 
-function codexAppServerRuntimeDirIsManaged(runtimeDir = "") {
+export function codexAppServerRuntimeDirIsManaged(runtimeDir = "") {
   const normalizedRuntimeDir = normalizeNullableText(runtimeDir);
   if (!normalizedRuntimeDir) {
     return false;
@@ -422,7 +419,7 @@ export async function removeCodexAppServerRuntimeDir(runtimeDir = "") {
   return true;
 }
 
-async function removeCodexAppServerMetadataTemps(runtimeDir = "") {
+export async function removeCodexAppServerMetadataTemps(runtimeDir = "") {
   let names = [];
   try {
     names = await readdir(runtimeDir);
@@ -434,7 +431,7 @@ async function removeCodexAppServerMetadataTemps(runtimeDir = "") {
     .map((name) => rm(path.join(runtimeDir, name), { force: true })));
 }
 
-function codexAppServerRuntimeCleanupCanSkip(error) {
+export function codexAppServerRuntimeCleanupCanSkip(error) {
   return ["EACCES", "EPERM", "ENOENT"].includes(String(error?.code || ""));
 }
 
@@ -470,7 +467,7 @@ export function normalizeCodexAppServerTerminalEnv(terminalEnv = {}) {
 }
 
 export function codexAppServerCommandBaseEnv({
-  env = process.env,
+  env,
   terminalEnv = {}
 } = {}) {
   const baseEnv = {
@@ -499,7 +496,7 @@ export function codexAppServerTerminalEnvHash(terminalEnv = {}) {
     .sort(([left], [right]) => left.localeCompare(right))));
 }
 
-function codexHistoryAdapterUrlIsValid(baseUrl, token) {
+export function codexHistoryAdapterUrlIsValid(baseUrl, token) {
   // Only this adapter URL shape serves thread-bound compaction recovery. Any
   // other shape keeps its process identity readable but is retired through
   // normal owned cleanup.
@@ -507,14 +504,14 @@ function codexHistoryAdapterUrlIsValid(baseUrl, token) {
   return Boolean(match && Number(match[1]) <= 65535 && baseUrl.endsWith(`/${token}/v2`));
 }
 
-function codexAppServerLivenessTimeoutMs(options = {}) {
+export function codexAppServerLivenessTimeoutMs(options = {}) {
   return normalizePositiveInteger(
     options.livenessTimeoutMs,
     { fallback: normalizePositiveInteger(options.timeoutMs, { fallback: CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS }) }
   );
 }
 
-function codexAppServerProcessCommandHash({
+export function codexAppServerProcessCommandHash({
   codexArgs = [],
   codexCommand = "",
   executionMode = "",
@@ -530,11 +527,6 @@ function codexAppServerProcessCommandHash({
   }));
 }
 
-const codexAppServerRuntimePreparations = new Map();
-
-/** The production shared runtime: one process owner per stable runtime directory.
- * Execution and credential facilities retain host policy; threads do not own this process.
- */
 /** Default environment names the runtime and its process leader share. */
 export const CODEX_APP_SERVER_DEFAULT_ENVIRONMENT = Object.freeze({
   runtimeToken: "JSKIT_EXECUTION_RUNTIME_TOKEN",
@@ -547,1019 +539,3 @@ export function codexCommandHookDefinition(command) {
   return [{ matcher: "^Bash$", hooks: [{ type: "command", command, timeout: 30 }] }];
 }
 
-// Inline TOML for `-c` overrides: bare keys, JSON-quoted strings.
-function tomlInlineValue(value) {
-  if (Array.isArray(value)) {
-    return `[${value.map(tomlInlineValue).join(",")}]`;
-  }
-  if (isRecord(value)) {
-    return `{${Object.entries(value).map(([key, item]) => `${key}=${tomlInlineValue(item)}`).join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
-export function createCodexAppServerRuntime({ execution, credentials, configuration = {} }) {
-  const {
-    clientInfo = { name: "jskit", title: "JSKIT", version: "0.1.0" },
-    commandHookCommand,
-    errorPrefix = "",
-    modelCatalogEnvironmentName = CODEX_APP_SERVER_DEFAULT_ENVIRONMENT.modelCatalogSource,
-    processLabel = "jskit-codex-app-server",
-    processPath = fileURLToPath(new URL("./codexProcessLeader.js", import.meta.url)),
-    runtimeTokenEnvironmentName = CODEX_APP_SERVER_DEFAULT_ENVIRONMENT.runtimeToken,
-    commandHashEnvironmentName = CODEX_APP_SERVER_DEFAULT_ENVIRONMENT.commandHash,
-    socketPathHelp = "Configure a shorter host runtime directory.",
-    umask = "0007"
-  } = configuration;
-  const CODEX_APP_SERVER_PROCESS_PATH = processPath;
-  const CODEX_APP_SERVER_PROCESS_RUNTIME_TOKEN_ENV = runtimeTokenEnvironmentName;
-  const CODEX_APP_SERVER_PROCESS_COMMAND_HASH_ENV = commandHashEnvironmentName;
-  const codexProcessIdentity = createConversationProcessIdentity({
-    runtimeTokenEnvironmentName, commandHashEnvironmentName,
-    label: "Codex app-server",
-    unavailableCode: `${errorPrefix}codex_app_server_process_identity_unavailable`
-  });
-  const codexAppServerProcessIdentityIsWellFormed = codexProcessIdentity.isValid;
-  const captureCodexAppServerProcessIdentity = codexProcessIdentity.capture;
-  const currentCodexAccountIdentitySignature = credentials.identity;
-  const currentCodexAuthStateSignature = credentials.generation;
-  const assertCodexAuthGenerationCurrent = credentials.assertCurrent;
-
-  function codexAppServerSessionCommandHookConfig() {
-    return `hooks.PreToolUse=${tomlInlineValue(codexCommandHookDefinition(commandHookCommand))}`;
-  }
-
-  async function acquireRuntimeLock(runtimeDir = "", options = {}) {
-    await execution.prepare?.();
-    return acquireCodexRuntimeLock(runtimeDir, { ...options, busyCode: `${errorPrefix}codex_app_server_runtime_busy` });
-  }
-
-  // An empty or null umask inherits the host's own; hosts that share files set one.
-  const startupUmask = normalizeNullableText(umask);
-  if (startupUmask && !/^[0-7]{3,4}$/u.test(startupUmask)) {
-    throw new TypeError(`Codex app-server umask must be octal, not ${JSON.stringify(startupUmask)}.`);
-  }
-  const CODEX_APP_SERVER_UMASK_LINES = startupUmask ? [`umask ${startupUmask}`] : [];
-
-  const CODEX_APP_SERVER_MANAGED_SHELL = "/bin/sh";
-
-  const CODEX_APP_SERVER_MANAGED_STARTUP_SCRIPT = [
-    ...CODEX_APP_SERVER_UMASK_LINES,
-    `unset ${[...CODEX_APP_SERVER_DESKTOP_BUS_ENV_NAMES].join(" ")}`,
-    'exec "$@"'
-  ].join("\n");
-
-  const CODEX_APP_SERVER_HELPER_STARTUP_SCRIPT = [
-    ...CODEX_APP_SERVER_UMASK_LINES,
-    "exec /usr/bin/env -i \\",
-    '  HOME="$HOME" LOGNAME="$LOGNAME" USER="$USER" PATH="$PATH" \\',
-    '  CODEX_HOME="$CODEX_HOME" LANG="$LANG" LC_ALL="$LC_ALL" LC_CTYPE="$LC_CTYPE" \\',
-    `  ${CODEX_APP_SERVER_PROCESS_RUNTIME_TOKEN_ENV}="$${CODEX_APP_SERVER_PROCESS_RUNTIME_TOKEN_ENV}" ${CODEX_APP_SERVER_PROCESS_COMMAND_HASH_ENV}="$${CODEX_APP_SERVER_PROCESS_COMMAND_HASH_ENV}" \\`,
-    '  SSL_CERT_DIR="$SSL_CERT_DIR" SSL_CERT_FILE="$SSL_CERT_FILE" TERM="$TERM" TMPDIR="$TMPDIR" TZ="$TZ" \\',
-    '  "$@"'
-  ].join("\n");
-
-  function codexAppServerProcessMetadataIsIdentifiable(metadata = {}, runtimeDir = "") {
-    const normalizedRuntimeDir = normalizeNullableText(runtimeDir);
-    return Boolean(
-      Number(metadata.schemaVersion) === CODEX_APP_SERVER_METADATA_SCHEMA_VERSION &&
-      metadata.provider === CODEX_APP_SERVER_PROVIDER_ID &&
-      Number.isSafeInteger(Number(metadata.pid)) && Number(metadata.pid) > 0 &&
-      (!normalizedRuntimeDir || metadata.runtimeDir === normalizedRuntimeDir) &&
-      codexAppServerProcessIdentityIsWellFormed(metadata.processIdentity) &&
-      [
-        CODEX_APP_SERVER_PROCESS_STATE.RUNNING,
-        CODEX_APP_SERVER_PROCESS_STATE.STOPPED
-      ].includes(metadata.processState)
-    );
-  }
-
-  async function inspectCodexAppServerProcessIdentity(metadata = {}, options = {}) {
-    if (typeof options.processIdentityInspector === "function") {
-      return codexProcessIdentity.normalizeInspection(await options.processIdentityInspector(metadata));
-    }
-    if (!codexAppServerProcessMetadataIsIdentifiable(metadata)) {
-      return { processGroupIds: [], status: CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.INVALID };
-    }
-    return codexProcessIdentity.inspect(metadata);
-  }
-
-  async function stopCodexAppServerProcessGroup(metadata = {}, options = {}) {
-    if (!codexAppServerProcessMetadataIsIdentifiable(metadata)) {
-      return {
-        identityStatus: CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.INVALID,
-        processExitVerified: false,
-        stopped: false
-      };
-    }
-    return codexProcessIdentity.stop(metadata, {
-      ...options,
-      processIdentityInspector: (current) => inspectCodexAppServerProcessIdentity(current, options)
-    });
-  }
-
-  function assertCodexAppServerSocketPathSupported(socketPath = "") {
-    if (!codexAppServerSocketPathTooLong(socketPath)) {
-      return;
-    }
-    throw new Error(
-      `Codex app-server Unix socket path is too long for this OS: ${socketPath} ` +
-      `(${codexAppServerSocketPathBytes(socketPath)} bytes, max ${CODEX_APP_SERVER_UNIX_SOCKET_PATH_MAX_BYTES}). ` +
-      socketPathHelp
-    );
-  }
-
-  async function stopOwnedCodexAppServerExecution(metadata = {}, options = {}) {
-    if (
-      metadata.processState === CODEX_APP_SERVER_PROCESS_STATE.STOPPED &&
-      metadata.processExitVerifiedAt
-    ) {
-      return stopCodexAppServerProcessGroup(metadata, options);
-    }
-    const executionId = normalizeNullableText(metadata.executionId);
-    if (executionId) {
-      const stopExecution = typeof options.stopExecution === "function"
-        ? options.stopExecution
-        : execution.stop;
-      let executionStop;
-      try {
-        executionStop = await stopExecution(executionId, {
-          allowMissingRecordScopeRecovery: true,
-          killTimeoutMs: options.killTimeoutMs,
-          reason: options.reason || "codex-app-server-stop",
-          termTimeoutMs: options.termTimeoutMs
-        });
-      } catch (error) {
-        return {
-          error: String(error?.message || error || "The owned execution could not be stopped."),
-          executionId,
-          processExitVerified: false,
-          scopeEmpty: false,
-          stopped: false
-        };
-      }
-      if (executionStop?.ok === true && executionStop?.scopeEmpty === true) {
-        return {
-          ...executionStop,
-          executionId,
-          processExitVerified: true,
-          stopped: executionStop.stopped === true
-        };
-      }
-      if (typeof options.stopExecution === "function" || execution.authoritative) {
-        return {
-          ...(executionStop && typeof executionStop === "object" ? executionStop : {}),
-          executionId,
-          processExitVerified: false,
-          scopeEmpty: false,
-          stopped: false
-        };
-      }
-    }
-    return stopCodexAppServerProcessGroup(metadata, options);
-  }
-
-  async function stopCodexAppServerProcess(runtimeDir = "", options = {}) {
-    const normalizedRuntimeDir = normalizeNullableText(runtimeDir);
-    if (!normalizedRuntimeDir) {
-      return {
-        processExitVerified: false,
-        stopped: false
-      };
-    }
-    const metadata = await readCodexAppServerMetadata(normalizedRuntimeDir);
-    if (!codexAppServerProcessMetadataIsIdentifiable(metadata, normalizedRuntimeDir)) {
-      return {
-        identityStatus: CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.INVALID,
-        processExitVerified: false,
-        stopped: false
-      };
-    }
-    return stopOwnedCodexAppServerExecution(metadata, options);
-  }
-
-  async function cleanupFailedCodexAppServerStart(runtimeDir = "", {
-    helper = false,
-    executionId = "",
-    neverStarted = false,
-    pid = null,
-    processIdentity = null
-  } = {}, options = {}) {
-    let processStop = {
-      processExitVerified: neverStarted === true,
-      scopeEmpty: neverStarted === true,
-      stopped: false
-    };
-    let processCleanupFailed = false;
-    if (!neverStarted) {
-      try {
-        processStop = await stopOwnedCodexAppServerExecution({
-          executionId: normalizeNullableText(executionId),
-          pid: Number(pid),
-          processIdentity,
-          processState: CODEX_APP_SERVER_PROCESS_STATE.RUNNING,
-          provider: CODEX_APP_SERVER_PROVIDER_ID,
-          runtimeDir: normalizeNullableText(runtimeDir),
-          schemaVersion: CODEX_APP_SERVER_METADATA_SCHEMA_VERSION
-        }, options);
-      } catch {
-        processCleanupFailed = true;
-      }
-    }
-    if (processCleanupFailed || processStop.processExitVerified !== true) {
-      return {
-        ...processStop,
-        cleanupFailed: true
-      };
-    }
-    const helperRemovals = helper
-      ? [
-          rm(codexAppServerHelperHomeDir(runtimeDir), { force: true, recursive: true }),
-          rm(codexAppServerHelperWorkspaceDir(runtimeDir), { force: true, recursive: true }),
-          rm(codexAppServerLogPath(runtimeDir), { force: true })
-        ]
-      : [];
-    const removals = await Promise.allSettled([
-      ...helperRemovals,
-      rm(codexAppServerSocketPath(runtimeDir), { force: true }),
-      rm(codexAppServerMetadataPath(runtimeDir), { force: true }),
-      removeCodexAppServerMetadataTemps(runtimeDir)
-    ]);
-    return {
-      ...processStop,
-      cleanupFailed: removals.some(({ status }) => status === "rejected")
-    };
-  }
-
-  async function stopCodexAppServerRuntime(options = {}) {
-    const runtimeDir = normalizeNullableText(options.runtimeDir);
-    const preserveProcessExitProof = options.preserveProcessExitProof === true;
-    if (!runtimeDir || !codexAppServerRuntimeDirIsManaged(runtimeDir)) {
-      return {
-        processExitVerified: false,
-        runtimeDirPreserved: false,
-        runtimeDirRemoved: false,
-        stopped: false
-      };
-    }
-    let releaseLock;
-    try {
-      releaseLock = await acquireRuntimeLock(runtimeDir, options);
-    } catch (error) {
-      if (!codexAppServerRuntimeCleanupCanSkip(error)) {
-        throw error;
-      }
-      return {
-        processExitVerified: false,
-        runtimeDirCleanupError: String(error?.message || error || ""),
-        runtimeDirCleanupSkipped: String(error?.code || "") !== "ENOENT",
-        runtimeDirPreserved: false,
-        runtimeDirRemoved: false,
-        stopped: false
-      };
-    }
-    let runtimeDirRemoved = false;
-    let runtimeDirCleanupSkipped = false;
-    let runtimeDirCleanupError = "";
-    let runtimeDirPreserved = false;
-    let processStop = {
-      processExitVerified: false,
-      stopped: false
-    };
-    try {
-      const existing = await readCodexAppServerMetadata(runtimeDir);
-      const expectedAccount = normalizeNullableText(options.expectedAccountIdentitySignature);
-      const ownedRuntime = options.ownedRuntime;
-      if (
-        ownedRuntime &&
-        codexAppServerProcessMetadataIsIdentifiable(ownedRuntime, runtimeDir) &&
-        (!expectedAccount || ownedRuntime.accountIdentitySignature === expectedAccount) &&
-        (!existing || codexAppServerRuntimeIdentity(existing) !== codexAppServerRuntimeIdentity(ownedRuntime))
-      ) {
-        // Another owner may already have removed or replaced the shared runtime.
-        // Prove this provider's exact execution stopped without touching its successor.
-        return {
-          ...await stopOwnedCodexAppServerExecution(ownedRuntime, options),
-          runtimeDirPreserved: Boolean(existing),
-          runtimeDirRemoved: false
-        };
-      }
-      if (!existing) {
-        // Changeover after a server restart may have no runtime.json left. The
-        // managed execution owner can still drain and prove its exact scope empty.
-        // A missing file alone is never process-exit proof, and account-specific
-        // cleanup must keep using its retained execution identity above.
-        const owned = options.verifyOwnerScope === true && !expectedAccount
-          ? await execution.stopOwned({
-            kind: "assistant",
-            operationId: "codex-app-server",
-            ownerId: normalizeNullableText(options.ownerId) || stableHash(runtimeDir)
-          }, { reason: "codex-app-server-changeover" })
-          : null;
-        const ownerExitVerified = owned?.supported === true && owned?.ok === true && owned?.scopeEmpty === true;
-        return {
-          processExitVerified: ownerExitVerified,
-          runtimeDirPreserved: false,
-          runtimeDirRemoved: false,
-          stopped: ownerExitVerified && Number(owned?.closed) > 0
-        };
-      }
-      if (expectedAccount) {
-        // A replacement runtime is installed only after the previous process has
-        // drained under this same lock. Never stop that replacement for stale
-        // ephemeral-thread cleanup.
-        if (!codexAppServerProcessMetadataIsIdentifiable(existing, runtimeDir) ||
-            !/^sha256:[a-f0-9]{64}$/u.test(existing.accountIdentitySignature)) {
-          return { processExitVerified: false, runtimeDirRemoved: false, stopped: false };
-        }
-        if (existing.accountIdentitySignature !== expectedAccount) {
-          return { ownershipSuperseded: true, processExitVerified: false, runtimeDirRemoved: false, stopped: false };
-        }
-      }
-      processStop = await stopCodexAppServerProcess(runtimeDir, options);
-      if (processStop.processExitVerified === true && preserveProcessExitProof) {
-        const metadata = await readCodexAppServerMetadata(runtimeDir);
-        if (!codexAppServerProcessMetadataIsIdentifiable(metadata, runtimeDir)) {
-          return {
-            ...processStop,
-            processExitVerified: false,
-            runtimeDirPreserved: false,
-            runtimeDirRemoved: false
-          };
-        }
-        await writeCodexAppServerMetadata(runtimeDir, {
-          ...metadata,
-          processExitVerifiedAt: metadata.processExitVerifiedAt || new Date().toISOString(),
-          processState: CODEX_APP_SERVER_PROCESS_STATE.STOPPED
-        });
-        runtimeDirPreserved = true;
-      } else if (processStop.processExitVerified === true) {
-        try {
-          runtimeDirRemoved = await removeCodexAppServerRuntimeDir(runtimeDir);
-        } catch (error) {
-          if (!codexAppServerRuntimeCleanupCanSkip(error)) {
-            throw error;
-          }
-          runtimeDirCleanupSkipped = true;
-          runtimeDirCleanupError = String(error?.message || error || "");
-        }
-      }
-    } finally {
-      await releaseLock();
-    }
-    return {
-      ...processStop,
-      runtimeDirCleanupError,
-      runtimeDirCleanupSkipped,
-      runtimeDirPreserved,
-      runtimeDirRemoved
-    };
-  }
-
-  function codexAppServerMetadataIsWellFormed(metadata = {}, options = {}) {
-    const expectedAttachmentHostRoot = options.compatibility.attachmentHostRoot;
-    const expectedAccountIdentitySignature = normalizeNullableText(options.accountIdentitySignature);
-    const expectedExecutionMode = codexAppServerExecutionMode(options);
-    const expectedToolHomeSource = codexAppServerIsHelper(options) ? "" : normalizeNullableText(options.toolHomeSource);
-    const expectedTerminalEnvHash = codexAppServerTerminalEnvHash(codexAppServerIsHelper(options) ? {} : options.terminalEnv);
-    const expectedRuntimesHash = options.compatibility.runtimesHash;
-    const expectedExecutionContextHash = options.compatibility.executionContextHash;
-    const expectedHelperProcessCwd = expectedExecutionMode === CODEX_APP_SERVER_EXECUTION_MODES.HELPER
-      ? codexAppServerHelperWorkspaceDir(metadata.runtimeDir)
-      : "";
-    return Boolean(
-      metadata.schemaVersion === CODEX_APP_SERVER_METADATA_SCHEMA_VERSION &&
-      metadata.accountIdentitySignature === expectedAccountIdentitySignature &&
-      metadata.attachmentHostRoot === expectedAttachmentHostRoot &&
-      metadata.authStateSignature &&
-      metadata.executionId &&
-      metadata.executionContextHash === expectedExecutionContextHash &&
-      metadata.executionMode === expectedExecutionMode &&
-      metadata.processCwd &&
-      codexAppServerProcessMetadataIsIdentifiable(metadata) &&
-      metadata.processState === CODEX_APP_SERVER_PROCESS_STATE.RUNNING &&
-      (expectedExecutionMode === CODEX_APP_SERVER_EXECUTION_MODES.HELPER ||
-        codexHistoryAdapterUrlIsValid(metadata.historyAdapterBaseUrl, metadata.processIdentity.runtimeToken)) &&
-      (!expectedHelperProcessCwd || metadata.processCwd === expectedHelperProcessCwd) &&
-      metadata.provider === CODEX_APP_SERVER_PROVIDER_ID &&
-      metadata.runtimesHash === expectedRuntimesHash &&
-      metadata.terminalEnvHash === expectedTerminalEnvHash &&
-      metadata.toolHomeSource === expectedToolHomeSource &&
-      metadata.transport === CODEX_APP_SERVER_TRANSPORT.UNIX &&
-      metadata.endpoint &&
-      metadata.socketPath
-    );
-  }
-
-  async function codexAppServerEndpointStatus(endpoint = "", {
-    timeoutMs = CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS,
-    WebSocketImpl = WebSocket
-  } = {}) {
-    const normalizedEndpoint = normalizeNullableText(endpoint);
-    const socketPath = socketPathFromCodexAppServerEndpoint(normalizedEndpoint);
-    if (!socketPath || !await fileExists(socketPath)) {
-      return {
-        status: CODEX_APP_SERVER_ENDPOINT_STATUS.MISSING
-      };
-    }
-    const normalizedTimeoutMs = normalizePositiveInteger(timeoutMs, { fallback: CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS });
-    return {
-      status: await probeCodexAppServer(normalizedEndpoint, normalizedTimeoutMs, WebSocketImpl)
-    };
-  }
-
-  // One bounded connect-and-initialize handshake: responsive, timeout or unreachable.
-  async function probeCodexAppServer(endpoint, timeoutMs, WebSocketImpl) {
-    const client = new CodexAppServerJsonRpcClient({
-      endpoint,
-      requestTimeoutMs: timeoutMs,
-      WebSocketImpl
-    });
-    let timeout = null;
-    const probe = (async () => {
-      await client.connect();
-      await client.initialize({ clientInfo });
-      return CODEX_APP_SERVER_ENDPOINT_STATUS.RESPONSIVE;
-    })();
-    probe.catch(() => null);
-    try {
-      return await Promise.race([
-        probe,
-        new Promise((resolve) => {
-          timeout = setTimeout(() => resolve(CODEX_APP_SERVER_ENDPOINT_STATUS.TIMEOUT), timeoutMs);
-          timeout.unref?.();
-        })
-      ]);
-    } catch {
-      return CODEX_APP_SERVER_ENDPOINT_STATUS.UNREACHABLE;
-    } finally {
-      clearTimeout(timeout);
-      client.close();
-    }
-  }
-
-  async function codexAppServerMetadataIsLive(metadata = {}, options = {}) {
-    return (await codexAppServerRuntimeStatus(metadata, options)).status === CODEX_APP_SERVER_RUNTIME_STATUS.LIVE;
-  }
-
-  async function codexAppServerRuntimeStatus(metadata = {}, options = {}) {
-    const normalized = normalizeCodexAppServerMetadata(metadata);
-    if (
-      codexAppServerProcessMetadataIsIdentifiable(normalized) &&
-      normalized.processState === CODEX_APP_SERVER_PROCESS_STATE.STOPPED &&
-      normalized.processExitVerifiedAt
-    ) {
-      return {
-        metadata: normalized,
-        replace: true,
-        reusable: false,
-        status: CODEX_APP_SERVER_RUNTIME_STATUS.EXITED
-      };
-    }
-    if (!codexAppServerMetadataIsWellFormed(normalized, options)) {
-      return {
-        metadata: normalized,
-        replace: true,
-        reusable: false,
-        status: CODEX_APP_SERVER_RUNTIME_STATUS.INCOMPATIBLE
-      };
-    }
-    const authStateSignature = await currentCodexAuthStateSignature(options);
-    if (normalized.authStateSignature !== authStateSignature) {
-      return {
-        metadata: normalized,
-        replace: true,
-        reusable: false,
-        status: CODEX_APP_SERVER_RUNTIME_STATUS.INCOMPATIBLE
-      };
-    }
-    let processIdentity = null;
-    if (typeof options.processGroupIsAlive === "function") {
-      const alive = options.processGroupIsAlive(normalized.pid);
-      processIdentity = {
-        processGroupIds: alive ? [normalized.pid] : [],
-        status: alive
-          ? CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.EXACT
-          : CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.ABSENT
-      };
-    } else {
-      processIdentity = await inspectCodexAppServerProcessIdentity(normalized, options);
-    }
-    if (
-      processIdentity.status === CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.ABSENT ||
-      processIdentity.status === CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.MISMATCH
-    ) {
-      return {
-        metadata: normalized,
-        replace: true,
-        reusable: false,
-        status: CODEX_APP_SERVER_RUNTIME_STATUS.EXITED
-      };
-    }
-    if (processIdentity.status !== CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.EXACT) {
-      return {
-        metadata: normalized,
-        replace: false,
-        reusable: true,
-        status: CODEX_APP_SERVER_RUNTIME_STATUS.SUSPECT
-      };
-    }
-    const endpoint = await codexAppServerEndpointStatus(normalized.endpoint, {
-      timeoutMs: codexAppServerLivenessTimeoutMs(options),
-      WebSocketImpl: options.WebSocketImpl
-    });
-    if (endpoint.status === CODEX_APP_SERVER_ENDPOINT_STATUS.RESPONSIVE) {
-      return {
-        metadata: normalized,
-        replace: false,
-        reusable: true,
-        status: CODEX_APP_SERVER_RUNTIME_STATUS.LIVE
-      };
-    }
-    if (endpoint.status === CODEX_APP_SERVER_ENDPOINT_STATUS.MISSING) {
-      return {
-        metadata: normalized,
-        replace: true,
-        reusable: false,
-        status: CODEX_APP_SERVER_RUNTIME_STATUS.MISSING
-      };
-    }
-    if (endpoint.status === CODEX_APP_SERVER_ENDPOINT_STATUS.TIMEOUT) {
-      return {
-        metadata: normalized,
-        replace: false,
-        reusable: true,
-        status: CODEX_APP_SERVER_RUNTIME_STATUS.SUSPECT
-      };
-    }
-    return {
-      metadata: normalized,
-      replace: true,
-      reusable: false,
-      status: CODEX_APP_SERVER_RUNTIME_STATUS.MISSING
-    };
-  }
-
-  async function waitForCodexAppServer(endpoint = "", {
-    timeoutMs = CODEX_APP_SERVER_READY_TIMEOUT_MS,
-    WebSocketImpl = WebSocket
-  } = {}) {
-    const socketPath = socketPathFromCodexAppServerEndpoint(endpoint);
-    if (!socketPath) {
-      return false;
-    }
-    const startedAt = Date.now();
-    while (!await fileExists(socketPath) && Date.now() - startedAt <= timeoutMs) {
-      await delay(100);
-    }
-    const remainingMs = Math.max(1, timeoutMs - (Date.now() - startedAt));
-    if (!await fileExists(socketPath)) {
-      return false;
-    }
-    return await probeCodexAppServer(endpoint, remainingMs, WebSocketImpl) === CODEX_APP_SERVER_ENDPOINT_STATUS.RESPONSIVE;
-  }
-
-  async function startCodexAppServerProcess({
-    providerHome = false,
-    accountIdentitySignature = "",
-    authStateSignature = "",
-    codexCommand = "codex",
-    env = process.env,
-    executionRoot = "",
-    executionMode = CODEX_APP_SERVER_EXECUTION_MODES.INTERACTIVE,
-    killTimeoutMs = 0,
-    processIdentityInspector = null,
-    readyTimeoutMs = CODEX_APP_SERVER_READY_TIMEOUT_MS,
-    signalProcessGroup: signalProcessGroupOverride = null,
-    stopExecution = null,
-    terminalEnv = {},
-    termTimeoutMs = 0,
-    toolHomeSource = "",
-    WebSocketImpl = WebSocket,
-    workdir = "",
-    socketOwnerDrained = false,
-    runtimeDir,
-    ownerId = "",
-    compatibility
-  } = {}) {
-    const processLifecycleOptions = {
-      killTimeoutMs,
-      processIdentityInspector,
-      signalProcessGroup: signalProcessGroupOverride,
-      stopExecution,
-      termTimeoutMs
-    };
-    await ensureWritablePrivateDirectory(runtimeDir);
-    const helper = codexAppServerExecutionMode({ executionMode }) ===
-      CODEX_APP_SERVER_EXECUTION_MODES.HELPER;
-    const normalizedToolHomeSource = normalizeNullableText(toolHomeSource);
-    if (normalizedToolHomeSource) {
-      await assertExistingDirectory(normalizedToolHomeSource, "Codex credential home");
-    }
-    const resolvedAuthStateSignature = await currentCodexAuthStateSignature({ authStateSignature });
-    await assertCodexAuthGenerationCurrent(resolvedAuthStateSignature);
-    const socketPath = codexAppServerSocketPath(runtimeDir);
-    assertCodexAppServerSocketPathSupported(socketPath);
-    const endpoint = codexAppServerUnixEndpoint(socketPath);
-    const logPath = codexAppServerLogPath(runtimeDir);
-    const helperHome = helper ? codexAppServerHelperHomeDir(runtimeDir) : "";
-    const helperWorkspace = helper ? codexAppServerHelperWorkspaceDir(runtimeDir) : "";
-    if (helper) {
-      await Promise.all([
-        rm(helperHome, { force: true, recursive: true }),
-        rm(helperWorkspace, { force: true, recursive: true })
-      ]);
-      await Promise.all([
-        ensureWritablePrivateDirectory(helperHome),
-        ensureWritablePrivateDirectory(helperWorkspace)
-      ]);
-      if (providerHome) {
-        // The canonical home contains only our curated provider projection. Copy
-        // it into the existing isolated helper home; never load OpenAI auth here.
-        try {
-          await copyCodexProviderHome(path.join(normalizedToolHomeSource, ".codex"), helperHome);
-        } catch (cause) {
-          const error = new Error("Codex isolated helper runtime could not copy the provider home.", { cause });
-          error.code = `${errorPrefix}codex_helper_runtime_start_failed`;
-          throw error;
-        }
-      }
-    }
-    const processCwd = helper
-      ? helperWorkspace
-      : codexAppServerProcessCwd({
-          executionRoot,
-          runtimeDir,
-          workdir
-        });
-    const projectTrustOverride = helper ? "" : codexAppServerProjectTrustOverride(workdir);
-    const normalizedTerminalEnv = normalizeCodexAppServerTerminalEnv(helper ? {} : terminalEnv);
-    const commandBaseEnv = helper
-      ? codexAppServerHelperCommandBaseEnv(env, helperHome)
-      : codexAppServerCommandBaseEnv({
-          env,
-          terminalEnv: normalizedTerminalEnv
-        });
-    if (await fileExists(socketPath) && !socketOwnerDrained) {
-      const endpointStatus = await codexAppServerEndpointStatus(endpoint, {
-        timeoutMs: CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS,
-        WebSocketImpl
-      });
-      if (![CODEX_APP_SERVER_ENDPOINT_STATUS.MISSING, CODEX_APP_SERVER_ENDPOINT_STATUS.UNREACHABLE]
-        .includes(endpointStatus.status)) {
-        const error = new Error("The existing Codex app-server socket still has an unretired owner.");
-        error.code = `${errorPrefix}codex_app_server_socket_owner_unverified`;
-        error.retryable = false;
-        throw error;
-      }
-    }
-    await rm(socketPath, {
-      force: true
-    });
-    const codexArgs = [
-      // Keep every override after app-server: a trailing -c (including the model
-      // catalogue) otherwise drops the earlier ones. See openai/codex#39012.
-      "app-server",
-      "--listen",
-      endpoint,
-      // App-server uses config overrides, not the top-level sandbox bypass flag.
-      ...(helper ? [] : [
-        "-c",
-        'approval_policy="never"',
-        "-c",
-        'sandbox_mode="danger-full-access"',
-        "-c",
-        `features.hooks=${Boolean(commandHookCommand)}`,
-        ...(commandHookCommand ? ["-c", codexAppServerSessionCommandHookConfig()] : [])
-      ]),
-      "-c",
-      "check_for_update_on_startup=false",
-      // Plugin and app startup syncs fill the home with unused catalogues.
-      ...codexDisabledProcessFeatureArguments(),
-      ...(projectTrustOverride
-        ? [
-            "-c",
-            projectTrustOverride
-          ]
-        : [])
-    ];
-    const runtimeToken = randomUUID();
-    const commandHash = codexAppServerProcessCommandHash({
-      codexArgs,
-      codexCommand,
-      executionMode,
-      processCwd,
-      runtimeDir
-    });
-    const baseEnv = {
-      ...commandBaseEnv,
-      // A curated provider home contains a provider-only static catalogue. Use
-      // the binary's native definitions as the base for its shared runtime.
-      [modelCatalogEnvironmentName]: providerHome ? "bundled" : "native",
-      [CODEX_APP_SERVER_PROCESS_COMMAND_HASH_ENV]: commandHash,
-      [CODEX_APP_SERVER_PROCESS_RUNTIME_TOKEN_ENV]: runtimeToken
-    };
-    const profileBinary = path.isAbsolute(codexCommand) ? await stat(codexCommand).catch(() => null) : null;
-    const startResult = await execution.run({
-      args: [
-        "-c",
-        helper ? CODEX_APP_SERVER_HELPER_STARTUP_SCRIPT : CODEX_APP_SERVER_MANAGED_STARTUP_SCRIPT,
-        processLabel,
-        ...(helper ? [] : [process.execPath, CODEX_APP_SERVER_PROCESS_PATH, runtimeDir]),
-        codexCommand,
-        ...codexArgs
-      ],
-      baseEnv,
-      command: CODEX_APP_SERVER_MANAGED_SHELL,
-      credentialHome: codexAppServerCredentialHome(
-        helper ? helperHome : normalizedToolHomeSource,
-        baseEnv
-      ),
-      cwd: processCwd || process.cwd(),
-      execution: {
-        kind: "assistant",
-        label: "Codex assistant",
-        lifecycle: "service",
-        operationId: "codex-app-server",
-        ownerId: normalizeNullableText(ownerId) || stableHash(runtimeDir)
-      },
-      processProfile: profileBinary?.isFile() ? {
-        command: codexCommand, helper, executionMode,
-        binary: [profileBinary.dev, profileBinary.ino, profileBinary.size, profileBinary.mtimeMs, profileBinary.ctimeMs],
-        platform: process.platform, architecture: process.arch,
-        startup: helper ? CODEX_APP_SERVER_HELPER_STARTUP_SCRIPT : CODEX_APP_SERVER_MANAGED_STARTUP_SCRIPT,
-        historyAdapter: !helper
-      } : null,
-      logPath,
-      inheritProcessEnv: false,
-      mode: "detached",
-      timeout: readyTimeoutMs
-    });
-    if (!startResult.ok) {
-      const failedProcessIdentity = await captureCodexAppServerProcessIdentity({
-        commandHash,
-        pid: startResult.pid,
-        reportedIdentity: startResult.processIdentity,
-        runtimeToken
-      }).catch(() => null);
-      const cleanup = await cleanupFailedCodexAppServerStart(runtimeDir, {
-        helper,
-        executionId: startResult.execution?.id,
-        neverStarted: !Number.isSafeInteger(Number(startResult.pid)),
-        pid: startResult.pid,
-        processIdentity: failedProcessIdentity
-      }, processLifecycleOptions);
-      const error = new Error(
-        startResult.output || startResult.error ||
-        (helper ? "Codex isolated helper runtime failed to start." : "Codex app-server failed to start.")
-      );
-      error.code = cleanup.cleanupFailed
-        ? (helper
-            ? `${errorPrefix}codex_helper_runtime_cleanup_required`
-            : `${errorPrefix}codex_app_server_cleanup_required`)
-        : (startResult.code || (helper
-            ? `${errorPrefix}codex_helper_runtime_start_failed`
-            : `${errorPrefix}codex_app_server_start_failed`));
-      error.cleanupRequired = cleanup.cleanupFailed;
-      error.execution = startResult.execution;
-      error.retryable = cleanup.cleanupFailed ? false : startResult.retryable === true;
-      throw error;
-    }
-
-    let processIdentity;
-    try {
-      processIdentity = await captureCodexAppServerProcessIdentity({
-        commandHash,
-        pid: startResult.pid,
-        reportedIdentity: startResult.processIdentity,
-        runtimeToken
-      });
-    } catch (cause) {
-      const cleanup = await cleanupFailedCodexAppServerStart(runtimeDir, {
-        helper,
-        executionId: startResult.execution?.id,
-        pid: startResult.pid,
-        processIdentity: startResult.processIdentity
-      }, processLifecycleOptions);
-      const error = new Error("Codex app-server process ownership could not be recorded.", {
-        cause
-      });
-      error.code = cleanup.cleanupFailed
-        ? `${errorPrefix}codex_app_server_cleanup_required`
-        : `${errorPrefix}codex_app_server_process_identity_unavailable`;
-      error.cleanupRequired = cleanup.cleanupFailed;
-      throw error;
-    }
-
-    const ready = await waitForCodexAppServer(endpoint, {
-      timeoutMs: readyTimeoutMs,
-      WebSocketImpl
-    });
-    if (!ready) {
-      const logTail = await tailTextFile(logPath);
-      const cleanup = await cleanupFailedCodexAppServerStart(runtimeDir, {
-        helper,
-        executionId: startResult.execution?.id,
-        pid: startResult.pid,
-        processIdentity
-      }, processLifecycleOptions);
-      if (!cleanup.cleanupFailed && !helper) {
-        await credentials.observeFailure(logTail);
-      }
-      const error = new Error([
-        helper
-          ? "Codex isolated helper runtime did not become ready."
-          : `Codex app-server did not become ready at ${endpoint}.`,
-        logTail ? `Recent log output:\n${logTail}` : ""
-      ].filter(Boolean).join("\n"));
-      error.code = cleanup.cleanupFailed
-        ? (helper
-            ? `${errorPrefix}codex_helper_runtime_cleanup_required`
-            : `${errorPrefix}codex_app_server_cleanup_required`)
-        : (helper
-            ? `${errorPrefix}codex_helper_runtime_start_failed`
-            : `${errorPrefix}codex_app_server_ready_timeout`);
-      error.cleanupRequired = cleanup.cleanupFailed;
-      error.retryable = false;
-      throw error;
-    }
-
-    let historyAdapterBaseUrl = "";
-    try {
-      if (!helper) {
-        const descriptor = JSON.parse(await readFile(path.join(runtimeDir, "history-adapter.json"), "utf8"));
-        if (descriptor.runtimeToken !== runtimeToken || !codexHistoryAdapterUrlIsValid(descriptor.baseUrl, runtimeToken)) {
-          throw new Error("Codex history adapter did not confirm the current runtime.");
-        }
-        historyAdapterBaseUrl = descriptor.baseUrl;
-      }
-      await assertCodexAuthGenerationCurrent(resolvedAuthStateSignature);
-    } catch (cause) {
-      const cleanup = await cleanupFailedCodexAppServerStart(runtimeDir, {
-        helper,
-        executionId: startResult.execution?.id,
-        pid: startResult.pid,
-        processIdentity
-      }, processLifecycleOptions);
-      if (cleanup.cleanupFailed) {
-        const error = new Error("Codex app-server authentication changed and its execution could not be drained.", {
-          cause
-        });
-        error.code = `${errorPrefix}codex_app_server_cleanup_required`;
-        error.cleanupRequired = true;
-        error.retryable = false;
-        throw error;
-      }
-      throw cause;
-    }
-
-    return {
-      accountIdentitySignature: normalizeNullableText(accountIdentitySignature),
-      attachmentHostRoot: compatibility.attachmentHostRoot,
-      authStateSignature: resolvedAuthStateSignature,
-      endpoint,
-      executionId: normalizeNullableText(startResult.execution?.id),
-      executionMode: helper
-        ? CODEX_APP_SERVER_EXECUTION_MODES.HELPER
-        : CODEX_APP_SERVER_EXECUTION_MODES.INTERACTIVE,
-      executionContextHash: compatibility.executionContextHash,
-      healthz: "",
-      historyAdapterBaseUrl,
-      logPath,
-      pid: Number.isSafeInteger(Number(startResult.pid)) ? Number(startResult.pid) : null,
-      processCwd,
-      processIdentity,
-      processState: CODEX_APP_SERVER_PROCESS_STATE.RUNNING,
-      provider: CODEX_APP_SERVER_PROVIDER_ID,
-      readyz: "",
-      runtimeDir,
-      runtimesHash: compatibility.runtimesHash,
-      schemaVersion: CODEX_APP_SERVER_METADATA_SCHEMA_VERSION,
-      socketPath,
-      startedAt: new Date().toISOString(),
-      terminalEnvHash: codexAppServerTerminalEnvHash(normalizedTerminalEnv),
-      toolHomeSource: helper ? "" : normalizedToolHomeSource,
-      transport: CODEX_APP_SERVER_TRANSPORT.UNIX
-    };
-  }
-
-  async function ensureCodexAppServerRuntime(options = {}) {
-    const runtimeDir = path.resolve(options.runtimeDir);
-    while (codexAppServerRuntimePreparations.has(runtimeDir)) {
-      await codexAppServerRuntimePreparations.get(runtimeDir);
-    }
-    // Each waiter rechecks its own auth and runtime configuration after startup.
-    const operation = prepareCodexAppServerRuntime({ ...options, runtimeDir });
-    codexAppServerRuntimePreparations.set(runtimeDir, operation);
-    try {
-      return await operation;
-    } finally {
-      codexAppServerRuntimePreparations.delete(runtimeDir);
-    }
-  }
-
-  async function prepareCodexAppServerRuntime(options) {
-    const { runtimeDir } = options;
-    const [accountIdentitySignature, authStateSignature] = await Promise.all([
-      currentCodexAccountIdentitySignature(options),
-      currentCodexAuthStateSignature(options)
-    ]);
-    const runtimeOptions = {
-      ...options,
-      accountIdentitySignature,
-      authStateSignature
-    };
-    const runtimeMetadataWriter = typeof options.runtimeMetadataWriter === "function"
-      ? options.runtimeMetadataWriter
-      : writeCodexAppServerMetadata;
-    await ensureWritablePrivateDirectory(runtimeDir);
-
-    const existing = await readCodexAppServerMetadata(runtimeDir);
-    const existingStatus = existing ? await codexAppServerRuntimeStatus(existing, runtimeOptions) : null;
-    if (existingStatus?.reusable) {
-      return {
-        ...existingStatus.metadata,
-        reused: true,
-        runtimeStatus: existingStatus.status
-      };
-    }
-
-    const releaseLock = await acquireRuntimeLock(runtimeDir, runtimeOptions);
-    try {
-      let socketOwnerDrained = false;
-      const afterLock = await readCodexAppServerMetadata(runtimeDir);
-      const afterLockStatus = afterLock ? await codexAppServerRuntimeStatus(afterLock, runtimeOptions) : null;
-      if (afterLockStatus?.reusable) {
-        return {
-          ...afterLockStatus.metadata,
-          reused: true,
-          runtimeStatus: afterLockStatus.status
-        };
-      }
-
-      if (afterLock && (!afterLockStatus || afterLockStatus.replace !== false)) {
-        const stopped = await stopCodexAppServerProcess(runtimeDir, runtimeOptions);
-        if (stopped.processExitVerified !== true) {
-          const error = new Error(
-            `${clientInfo.title} found an earlier Codex app-server but could not prove that its owned execution was stopped. It refused to start a replacement because two assistant processes could damage the session or worsen resource pressure.`
-          );
-          error.code = `${errorPrefix}codex_app_server_process_identity_unverified`;
-          error.cleanupRequired = true;
-          error.retryable = false;
-          throw error;
-        }
-        socketOwnerDrained = true;
-      }
-
-      const started = await startCodexAppServerProcess({
-        ...runtimeOptions,
-        runtimeDir,
-        socketOwnerDrained
-      });
-      try {
-        await assertCodexAuthGenerationCurrent(started.authStateSignature, runtimeOptions);
-        await runtimeMetadataWriter(runtimeDir, started);
-        await assertCodexAuthGenerationCurrent(started.authStateSignature, runtimeOptions);
-      } catch (error) {
-        const helper = codexAppServerIsHelper(runtimeOptions);
-        const cleanup = await cleanupFailedCodexAppServerStart(runtimeDir, {
-          helper,
-          executionId: started.executionId,
-          pid: started.pid,
-          processIdentity: started.processIdentity
-        }, runtimeOptions);
-        const failure = new Error(
-          helper
-            ? "Codex isolated helper runtime metadata could not be recorded."
-            : "Codex app-server runtime could not be published safely.",
-          { cause: error }
-        );
-        failure.code = cleanup.cleanupFailed
-          ? (helper
-              ? `${errorPrefix}codex_helper_runtime_cleanup_required`
-              : `${errorPrefix}codex_app_server_cleanup_required`)
-          : (error?.code || (helper
-              ? `${errorPrefix}codex_helper_runtime_metadata_failed`
-              : `${errorPrefix}codex_app_server_metadata_failed`));
-        failure.cleanupRequired = cleanup.cleanupFailed;
-        failure.retryable = false;
-        throw failure;
-      }
-      return {
-        ...started,
-        reused: false
-      };
-    } finally {
-      await releaseLock();
-    }
-  }
-
-  return {
-    ensure: ensureCodexAppServerRuntime,
-    start: startCodexAppServerProcess,
-    stop: stopCodexAppServerRuntime,
-    isLive: codexAppServerMetadataIsLive,
-    cleanupFailedStart: cleanupFailedCodexAppServerStart
-  };
-}
-