minecodex 0.1.15 → 0.1.18

package/README.md

@@ -26,6 +26,8 @@ mcx install
 
 运行 `mcx install` 不会强制关闭或启动 Codex，也不会影响当前打开的窗口。安装完成后，终端会说明更改将在下一次重启 Codex 时生效，并询问是否立即重启；默认选项为 **No**。只有在您明确确认，或后续手动运行 `mcx restart` 时，才会重新打开 Codex。安装完成后，macOS 的“登录项与扩展”中会添加名为 **MineCodex** 的后台项目。
 
+MineCodex 只以后台辅助服务运行，前台应用始终是 OpenAI 签名的官方 `ChatGPT.app`，并继续使用官方默认用户数据。通过 Dock、Finder、Spotlight、登录项或会话恢复打开 ChatGPT 时，后台服务会验证官方应用与对应进程；若该进程尚未开放兼容的本机调试端口，则确认其完整退出后再通过 LaunchServices 重新打开官方应用并注入功能。MineCodex 不修改 `ChatGPT.app`、`app.asar`、Dock 项目或默认打开方式。
+
 打开本地控制台：
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecodex",
-  "version": "0.1.15",
+  "version": "0.1.18",
   "description": "Lightweight, local-first plugins for the Codex desktop app.",
   "license": "MIT",
   "type": "module",

package/packages/cli/src/chatgpt-launch-coordinator.mjs

@@ -0,0 +1,77 @@
+function hasExactArgument(command, argument) {
+  const value = String(command);
+  let offset = value.indexOf(argument);
+  while (offset >= 0) {
+    const before = offset === 0 || /\s/.test(value[offset - 1]);
+    const end = offset + argument.length;
+    const after = end === value.length || /\s/.test(value[end]);
+    if (before && after) return true;
+    offset = value.indexOf(argument, offset + 1);
+  }
+  return false;
+}
+
+export function hasLoopbackCdpArguments(command, cdpPort) {
+  return hasExactArgument(command, "--remote-debugging-address=127.0.0.1")
+    && hasExactArgument(command, `--remote-debugging-port=${cdpPort}`)
+    && hasExactArgument(command, `--remote-allow-origins=http://127.0.0.1:${cdpPort}`);
+}
+
+function requireProcess(processInfo, context) {
+  if (!processInfo || !Number.isInteger(processInfo.pid) || processInfo.pid <= 1) {
+    throw new Error(`MineCodex could not verify the ${context} ChatGPT process.`);
+  }
+  if (typeof processInfo.command !== "string" || !processInfo.command.trim()) {
+    throw new Error(`MineCodex could not verify the ${context} ChatGPT command line.`);
+  }
+  if (processInfo.verified === false) {
+    throw new Error(`MineCodex rejected an unverified ${context} ChatGPT process.`);
+  }
+}
+
+export class ChatGPTLaunchCoordinator {
+  constructor({ platform, cdpPort }) {
+    this.platform = platform;
+    this.cdpPort = cdpPort;
+  }
+
+  async attach(processInfo, owned, { startRuntime, waitForHealthy }) {
+    requireProcess(processInfo, owned ? "LaunchServices-created" : "observed");
+    await this.platform.assertNativeCodexCdp(processInfo, this.cdpPort);
+    const status = await startRuntime();
+    const healthy = await waitForHealthy(status);
+    await this.platform.assertNativeCodexCdp(processInfo, this.cdpPort);
+    return {
+      ...healthy,
+      codex: { pid: processInfo.pid, owned, command: processInfo.command ?? null },
+    };
+  }
+
+  async ensureObservedLaunch(processInfo, { stopRuntime, startRuntime, waitForHealthy }) {
+    requireProcess(processInfo, "observed");
+    if (typeof this.platform?.terminateNativeCodex !== "function"
+      || typeof this.platform?.openNativeCodex !== "function"
+      || typeof this.platform?.assertNativeCodexCdp !== "function") {
+      throw new Error("MineCodex platform adapter cannot coordinate an official ChatGPT launch.");
+    }
+
+    await stopRuntime();
+    if (hasLoopbackCdpArguments(processInfo.command, this.cdpPort)) {
+      return this.attach(processInfo, false, { startRuntime, waitForHealthy });
+    }
+
+    const terminated = await this.platform.terminateNativeCodex(processInfo.pid, processInfo.command);
+    if (terminated !== 1) {
+      throw new Error(`MineCodex refused to replace ChatGPT pid ${processInfo.pid} after identity changed.`);
+    }
+    const launched = await this.platform.openNativeCodex({ cdpPort: this.cdpPort });
+    return this.attach(launched, true, { startRuntime, waitForHealthy });
+  }
+
+  async relaunchOwned({ stopRuntime, terminateOwned, startRuntime, waitForHealthy }) {
+    await stopRuntime();
+    await terminateOwned();
+    const launched = await this.platform.openNativeCodex({ cdpPort: this.cdpPort });
+    return this.attach(launched, true, { startRuntime, waitForHealthy });
+  }
+}

package/packages/cli/src/control-server.mjs

@@ -290,11 +290,13 @@ export async function createControlServer({
           service: { running: true },
           runtime: {
             running: runtime.running,
+            healthy: runtime.healthy === true,
             pid: runtime.pid ?? null,
             runtimeSessionId: runtime.runtimeSessionId ?? null,
             ready: runtime.ready ?? null,
             plugins: runtime.plugins ?? runtime.pluginStates ?? [],
             renderer: runtime.renderer ?? null,
+            codex: runtime.codex ?? null,
             failures: runtime.failures ?? [],
           },
           runtimeSessionId: runtime.runtimeSessionId ?? null,

package/packages/cli/src/platform.mjs

@@ -3,6 +3,7 @@ import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/pr
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { hasLoopbackCdpArguments } from "./chatgpt-launch-coordinator.mjs";
 
 const defaultExecFile = promisify(execFileCallback);
 const defaultFileSystem = Object.freeze({ mkdir, readFile, rename, rm, stat, unlink, writeFile });
@@ -11,6 +12,8 @@ export const SERVICE_LABEL = "com.vontean.minecodex.background";
 export const LEGACY_SERVICE_LABEL = "com.vontean.minecodex";
 export const CODEX_APP_PATH = "/Applications/ChatGPT.app";
 export const CODEX_EXECUTABLE = `${CODEX_APP_PATH}/Contents/MacOS/ChatGPT`;
+export const CODEX_BUNDLE_IDENTIFIER = "com.openai.codex";
+export const CODEX_TEAM_IDENTIFIER = "2DC432GLL2";
 export const MIN_NODE_VERSION = Object.freeze({ major: 22, minor: 5, patch: 0 });
 export const MIN_MACOS_VERSION = Object.freeze({ major: 13, darwinMajor: 22 });
 
@@ -90,6 +93,40 @@ export async function resolveCodexInstallation({
   );
 }
 
+export async function verifyCodexInstallation({ installation, execFile = defaultExecFile } = {}) {
+  if (!installation?.appPath || !installation?.executable) {
+    throw new Error("Codex Desktop installation is incomplete.");
+  }
+  const infoPath = path.join(installation.appPath, "Contents", "Info.plist");
+  const { stdout: bundleIdentifier } = await execFile("/usr/bin/plutil", [
+    "-extract", "CFBundleIdentifier", "raw", "-o", "-", infoPath,
+  ]);
+  if (String(bundleIdentifier).trim() !== CODEX_BUNDLE_IDENTIFIER) {
+    throw new Error(`Refusing non-official ChatGPT bundle: ${String(bundleIdentifier).trim() || "unknown"}`);
+  }
+  await execFile("/usr/bin/codesign", ["--verify", "--deep", "--strict", installation.appPath]);
+  const { stderr: details } = await execFile("/usr/bin/codesign", [
+    "-dv", "--verbose=4", installation.appPath,
+  ]);
+  const authority = String(details).match(/^Authority=(.+)$/m)?.[1] ?? "";
+  const identifier = String(details).match(/^Identifier=(.+)$/m)?.[1] ?? "";
+  const teamIdentifier = String(details).match(/^TeamIdentifier=(.+)$/m)?.[1] ?? "";
+  if (
+    identifier !== CODEX_BUNDLE_IDENTIFIER
+    || teamIdentifier !== CODEX_TEAM_IDENTIFIER
+    || !/\bOpenAI\b/i.test(authority)
+  ) {
+    throw new Error("Refusing ChatGPT with an unexpected signing identity.");
+  }
+  return Object.freeze({
+    ...installation,
+    bundleIdentifier: CODEX_BUNDLE_IDENTIFIER,
+    signingIdentity: authority,
+    teamIdentifier,
+    verified: true,
+  });
+}
+
 export function parseProcessList(output) {
   return String(output).split("\n").flatMap((line) => {
     const match = line.match(/^\s*(\d+)\s+(.+)$/);
@@ -116,6 +153,22 @@ function hasManagedProfile(command, profileDir) {
   return false;
 }
 
+function extractCdpPort(command) {
+  const match = String(command).match(/(?:^|\s)--remote-debugging-port=(\d+)(?:\s|$)/);
+  return match ? Number(match[1]) : null;
+}
+
+function parseCodexOwnerMarker(content) {
+  try {
+    const marker = JSON.parse(String(content));
+    if (marker?.version !== 1 || !Number.isInteger(marker.pid) || marker.pid <= 1) return null;
+    if (typeof marker.command !== "string" || !marker.command.trim()) return null;
+    return marker;
+  } catch {
+    return null;
+  }
+}
+
 export function serviceIsAbsent(error) {
   return /could not find service|service not found|no such process|domain does not support specified action/i.test(
     `${error?.stderr ?? ""}\n${error?.message ?? ""}`,
@@ -136,6 +189,48 @@ async function waitForProcessExit(pid, { processApi, timeoutMs = 8_000, sleep =
   throw new Error(`Process ${pid} did not exit in time`);
 }
 
+async function waitForProcessesExit(
+  pids,
+  { processApi, timeoutMs = 8_000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) },
+) {
+  const pending = new Set(pids);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    for (const pid of pending) {
+      try {
+        processApi.kill(pid, 0);
+      } catch (error) {
+        if (error.code === "ESRCH") pending.delete(pid);
+        else throw error;
+      }
+    }
+    if (pending.size === 0) return;
+    await sleep(100);
+  }
+  throw new Error(`ChatGPT process tree did not exit in time: ${[...pending].join(", ")}`);
+}
+
+function descendantPids(output, rootPid) {
+  const childrenByParent = new Map();
+  for (const line of String(output).split("\n")) {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+/);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const parentPid = Number(match[2]);
+    const children = childrenByParent.get(parentPid) ?? [];
+    children.push(pid);
+    childrenByParent.set(parentPid, children);
+  }
+  const descendants = [];
+  const pending = [...(childrenByParent.get(rootPid) ?? [])];
+  while (pending.length) {
+    const pid = pending.shift();
+    descendants.push(pid);
+    pending.push(...(childrenByParent.get(pid) ?? []));
+  }
+  return descendants;
+}
+
 function serviceTarget(uid) {
   return `gui/${uid}/${SERVICE_LABEL}`;
 }
@@ -169,7 +264,7 @@ export class MacPlatformAdapter {
     execFile = defaultExecFile,
     fileSystem = defaultFileSystem,
     processApi = process,
-    sleep,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     codexInstallation,
   } = {}) {
     this.uid = uid;
@@ -181,6 +276,8 @@ export class MacPlatformAdapter {
     this.processApi = processApi;
     this.sleep = sleep;
     this.codexInstallation = codexInstallation;
+    this.codexInstallationFingerprint = null;
+    this.codexInstallationInjected = Boolean(codexInstallation);
   }
 
   assertInstallSupported() {
@@ -194,7 +291,7 @@ export class MacPlatformAdapter {
   }
 
   async assertCodexInstalled() {
-    this.codexInstallation = await resolveCodexInstallation({
+    const installation = await resolveCodexInstallation({
       homeDir: this.homeDir,
       fileExists: async (filePath) => {
         try {
@@ -206,11 +303,36 @@ export class MacPlatformAdapter {
         }
       },
     });
+    this.codexInstallation = await verifyCodexInstallation({ installation, execFile: this.execFile });
+    this.codexInstallationFingerprint = await this.readCodexInstallationFingerprint(this.codexInstallation);
+    this.codexInstallationInjected = false;
     return this.codexInstallation;
   }
 
   async codex() {
-    return this.codexInstallation ?? this.assertCodexInstalled();
+    if (!this.codexInstallation) return this.assertCodexInstalled();
+    if (this.codexInstallationInjected) return this.codexInstallation;
+    const currentFingerprint = await this.readCodexInstallationFingerprint(this.codexInstallation);
+    if (this.codexInstallationFingerprint == null) {
+      this.codexInstallationFingerprint = currentFingerprint;
+    } else if (currentFingerprint !== this.codexInstallationFingerprint) {
+      return this.assertCodexInstalled();
+    }
+    return this.codexInstallation;
+  }
+
+  async readCodexInstallationFingerprint(installation) {
+    if (typeof this.fileSystem.stat !== "function") return null;
+    const paths = [
+      installation.executable,
+      path.join(installation.appPath, "Contents", "Info.plist"),
+      path.join(installation.appPath, "Contents", "_CodeSignature", "CodeResources"),
+    ];
+    const records = await Promise.all(paths.map(async (filePath) => {
+      const info = await this.fileSystem.stat(filePath);
+      return [filePath, info.dev ?? null, info.ino ?? null, info.size ?? null, info.mtimeMs ?? null];
+    }));
+    return JSON.stringify(records);
   }
 
   async isLaunchdServiceRunning(target) {
@@ -428,12 +550,34 @@ export class MacPlatformAdapter {
   async listCodexProcesses() {
     const installation = await this.codex();
     const { stdout } = await this.execFile("/bin/ps", ["-axo", "pid=,command="]);
-    return parseProcessList(stdout).filter(({ command }) => isExactCodexProcess(command, installation));
+    return parseProcessList(stdout)
+      .filter(({ command }) => isExactCodexProcess(command, installation))
+      .map((processInfo) => ({
+        ...processInfo,
+        appPath: installation.appPath,
+        executable: installation.executable,
+        bundleIdentifier: installation.bundleIdentifier ?? CODEX_BUNDLE_IDENTIFIER,
+        signingIdentity: installation.signingIdentity ?? null,
+        verified: installation.verified !== false,
+      }));
   }
 
   async ownedCodexProcesses(paths) {
     const processes = await this.listCodexProcesses();
-    return processes.filter(({ command }) => hasManagedProfile(command, paths.profileDir));
+    let marker = null;
+    try {
+      marker = parseCodexOwnerMarker(await this.fileSystem.readFile(paths.codexPidPath, "utf8"));
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    return processes.filter(({ pid, command, verified }) => verified === true && (
+      hasManagedProfile(command, paths.profileDir)
+      || (
+        pid === marker?.pid
+        && command === marker.command
+        && hasLoopbackCdpArguments(command, extractCdpPort(command))
+      )
+    ));
   }
 
   async assertOwnedCodexStopped(paths) {
@@ -457,45 +601,104 @@ export class MacPlatformAdapter {
   }
 
   async terminateOwnedCodex(paths) {
-    let pid;
-    try {
-      pid = Number((await this.fileSystem.readFile(paths.codexPidPath, "utf8")).trim());
-    } catch (error) {
-      if (error.code === "ENOENT") {
-        await this.assertOwnedCodexStopped(paths);
-        return false;
-      }
-      throw error;
-    }
-    if (!Number.isInteger(pid) || pid <= 1) {
-      await this.assertOwnedCodexStopped(paths);
-      return false;
-    }
-    const processInfo = (await this.ownedCodexProcesses(paths)).find((candidate) => candidate.pid === pid);
+    const processInfo = (await this.ownedCodexProcesses(paths))[0];
     if (!processInfo) {
       await this.assertOwnedCodexStopped(paths);
       return false;
     }
-    this.processApi.kill(pid, "SIGTERM");
-    await waitForProcessExit(pid, { processApi: this.processApi, sleep: this.sleep });
+    this.processApi.kill(processInfo.pid, "SIGTERM");
+    await waitForProcessExit(processInfo.pid, { processApi: this.processApi, sleep: this.sleep });
     await this.fileSystem.unlink(paths.codexPidPath).catch(() => {});
     await this.assertOwnedCodexStopped(paths);
     return true;
   }
 
-  async terminateNativeCodex() {
-    const processes = (await this.listCodexProcesses()).filter(({ command }) => !command.includes("--user-data-dir="));
-    for (const { pid } of processes) this.processApi.kill(pid, "SIGTERM");
-    await Promise.all(processes.map(({ pid }) => waitForProcessExit(pid, { processApi: this.processApi, sleep: this.sleep })));
-    return processes.length;
+  async codexProcessStartedMsAgo(processInfo) {
+    if (!processInfo || !Number.isInteger(processInfo.pid) || processInfo.pid <= 1) return null;
+    const { stdout } = await this.execFile("/bin/ps", ["-axo", "pid=,lstart="]);
+    const line = String(stdout).split("\n").find((row) => {
+      const match = row.match(/\s*(\d+)\s+(.*)/);
+      return match?.[1] === String(processInfo.pid);
+    });
+    const startedAt = line ? Date.parse(line.replace(/^\s*\d+\s+/, "")) : Number.NaN;
+    if (!line || !Number.isFinite(startedAt)) return null;
+    return Math.max(0, Date.now() - startedAt);
+  }
+
+  async terminateNativeCodex(pid, expectedCommand = null) {
+    if (!Number.isInteger(pid) || pid <= 1) {
+      throw new Error("MineCodex requires an exact ChatGPT PID to terminate.");
+    }
+    const processInfo = (await this.listCodexProcesses()).find((candidate) => (
+      candidate.pid === pid
+      && candidate.verified === true
+      && !candidate.command.includes("--user-data-dir=")
+      && (!expectedCommand || candidate.command === expectedCommand)
+    ));
+    if (!processInfo) return 0;
+    const { stdout: processTree } = await this.execFile("/bin/ps", ["-axo", "pid=,ppid=,command="]);
+    const ownedProcessTree = [pid, ...descendantPids(processTree, pid)];
+    this.processApi.kill(pid, "SIGTERM");
+    await waitForProcessesExit(ownedProcessTree, { processApi: this.processApi, sleep: this.sleep });
+    return 1;
+  }
+
+  async assertNativeCodexCdp(processInfo, cdpPort) {
+    if (!processInfo?.verified || !Number.isInteger(processInfo.pid) || !hasLoopbackCdpArguments(processInfo.command, cdpPort)) {
+      throw new Error("MineCodex could not bind the loopback CDP endpoint to a verified ChatGPT process.");
+    }
+    const { stdout } = await this.execFile("/usr/sbin/lsof", [
+      "-nP", "-a", "-p", String(processInfo.pid), `-iTCP:${cdpPort}`, "-sTCP:LISTEN", "-Fn",
+    ]);
+    const fields = String(stdout).split("\n");
+    if (!fields.includes(`p${processInfo.pid}`) || !fields.includes(`n127.0.0.1:${cdpPort}`)) {
+      throw new Error(`ChatGPT pid ${processInfo.pid} does not own loopback CDP port ${cdpPort}.`);
+    }
+    return true;
   }
 
   async openBrowser(url) {
     await this.execFile("/usr/bin/open", [url]);
   }
 
-  async openNativeCodex() {
+  async openNativeCodex({ cdpPort } = {}) {
     const installation = await this.codex();
-    await this.execFile("/usr/bin/open", ["-a", installation.appPath]);
+    if (!Number.isInteger(cdpPort) || cdpPort <= 0 || cdpPort > 65_535) {
+      await this.execFile("/usr/bin/open", ["-a", installation.appPath]);
+      return null;
+    }
+    const existingPids = new Set((await this.listCodexProcesses()).map(({ pid }) => pid));
+    await this.execFile("/usr/bin/open", [
+      "-n",
+      "-a",
+      installation.appPath,
+      "--args",
+      "--remote-debugging-address=127.0.0.1",
+      `--remote-debugging-port=${cdpPort}`,
+      `--remote-allow-origins=http://127.0.0.1:${cdpPort}`,
+    ]);
+    return this.waitForNativeCodex({ cdpPort, excludedPids: existingPids });
+  }
+
+  async waitForNativeCodex({ cdpPort, excludedPids = new Set(), timeoutMs = 15_000 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const candidates = (await this.listCodexProcesses()).filter(({ pid, command, verified }) => (
+        verified === true
+        && !excludedPids.has(pid)
+        && !command.includes("--user-data-dir=")
+        && hasLoopbackCdpArguments(command, cdpPort)
+      ));
+      if (candidates.length > 1) {
+        throw new Error(`LaunchServices exposed multiple new ChatGPT processes on CDP port ${cdpPort}.`);
+      }
+      const processInfo = candidates[0];
+      if (processInfo) {
+        await this.assertNativeCodexCdp(processInfo, cdpPort);
+        return processInfo;
+      }
+      await this.sleep?.(50);
+    }
+    throw new Error(`LaunchServices did not expose a loopback CDP ChatGPT process on port ${cdpPort}.`);
   }
 }

package/packages/cli/src/runtime-manager.mjs

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { ChatGPTLaunchCoordinator } from "./chatgpt-launch-coordinator.mjs";
 import { readConfig, FEATURE_IDS } from "./config.mjs";
 
 export const RUNTIME_PLUGIN_STATES = Object.freeze([
@@ -19,19 +20,6 @@ function hasExited(child) {
   return Boolean(child && (child.exitCode != null || child.signalCode != null));
 }
 
-function hasExactCommandArgument(command, argument) {
-  const value = String(command);
-  let offset = value.indexOf(argument);
-  while (offset >= 0) {
-    const before = offset === 0 || /\s/.test(value[offset - 1]);
-    const end = offset + argument.length;
-    const after = end === value.length || /\s/.test(value[end]);
-    if (before && after) return true;
-    offset = value.indexOf(argument, offset + 1);
-  }
-  return false;
-}
-
 function normalizedFailure(failure) {
   if (!failure || typeof failure !== "object") return failure ?? null;
   return {
@@ -132,8 +120,10 @@ export class RuntimeManager {
     waitForReady: readyWaiter = waitForReady,
     sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     stopTimeoutMs = 5_000,
-    manualLaunchPollMs = 1_000,
+    manualLaunchPollMs = 150,
+    manualTakeoverGraceMs = 60_000,
     cdpPort = Number(process.env.CODEX_RUNTIME_CDP_PORT ?? 9231),
+    launchCoordinator = null,
   }) {
     this.paths = paths;
     this.platform = platform;
@@ -143,6 +133,7 @@ export class RuntimeManager {
     this.sleep = sleep;
     this.stopTimeoutMs = stopTimeoutMs;
     this.manualLaunchPollMs = manualLaunchPollMs;
+    this.manualTakeoverGraceMs = manualTakeoverGraceMs;
     this.cdpPort = cdpPort;
     this.child = null;
     this.appliedFeatures = [];
@@ -157,6 +148,13 @@ export class RuntimeManager {
     this.manualLaunchWake = null;
     this.manualLaunchBaselinePids = new Set();
     this.manualLaunchArmed = false;
+    this.manualLaunchSuppressionDepth = 0;
+    this.enhancedCodex = null;
+    this.enhancementFailure = null;
+    this.launchCoordinator = launchCoordinator ?? new ChatGPTLaunchCoordinator({
+      platform,
+      cdpPort,
+    });
   }
 
   enqueue(operation) {
@@ -165,36 +163,33 @@ export class RuntimeManager {
     return next;
   }
 
-  async startInternal({ launchCodex = false } = {}) {
+  async startInternal() {
     if (this.child && !hasExited(this.child)) return this.status();
     this.clearChildState();
     this.stopping = false;
     const config = await readConfig(this.paths.configPath);
     const features = enabledFeatureIds(config);
-    const codexInstallation = typeof this.platform?.codex === "function"
-      ? await this.platform.codex()
-      : null;
-    const codexExecutable = codexInstallation?.executable
-      ?? process.env.MINECODEX_CODEX_EXECUTABLE;
+    if (typeof this.platform?.codex === "function") await this.platform.codex();
     await mkdir(this.paths.supportDir, { recursive: true, mode: 0o700 });
     await unlink(this.paths.runtimeReadyPath).catch((error) => {
       if (error.code !== "ENOENT") throw error;
     });
+    const runtimeEnvironment = {
+      ...process.env,
+      CODEX_FEATURES_ROOT: this.paths.featuresRoot,
+      CODEX_RUNTIME_PROFILE_DIR: this.paths.profileDir,
+      CODEX_RUNTIME_CDP_PORT: String(this.cdpPort),
+      CODEX_IMAGE_HOST_DATA_DIR: this.paths.imagesDataDir,
+      CODEX_NOTES_DATA_DIR: this.paths.notesDataDir,
+      MINECODEX_ENABLED_FEATURES: features.join(","),
+      MINECODEX_CODEX_PID_FILE: this.paths.codexPidPath,
+      MINECODEX_RUNTIME_READY_FILE: this.paths.runtimeReadyPath,
+    };
+    delete runtimeEnvironment.MINECODEX_LAUNCH_CODEX;
+    delete runtimeEnvironment.MINECODEX_CODEX_EXECUTABLE;
     const child = this.spawnProcess(process.execPath, [this.paths.runtimeEntry], {
       cwd: this.paths.packageRoot,
-      env: {
-        ...process.env,
-        CODEX_FEATURES_ROOT: this.paths.featuresRoot,
-        CODEX_RUNTIME_PROFILE_DIR: this.paths.profileDir,
-        CODEX_RUNTIME_CDP_PORT: String(this.cdpPort),
-        CODEX_IMAGE_HOST_DATA_DIR: this.paths.imagesDataDir,
-        CODEX_NOTES_DATA_DIR: this.paths.notesDataDir,
-        MINECODEX_ENABLED_FEATURES: features.join(","),
-        MINECODEX_CODEX_PID_FILE: this.paths.codexPidPath,
-        MINECODEX_RUNTIME_READY_FILE: this.paths.runtimeReadyPath,
-        MINECODEX_LAUNCH_CODEX: launchCodex ? "1" : "0",
-        ...(codexExecutable ? { MINECODEX_CODEX_EXECUTABLE: codexExecutable } : {}),
-      },
+      env: runtimeEnvironment,
       stdio: "inherit",
     });
     this.child = child;
@@ -261,9 +256,8 @@ export class RuntimeManager {
   async nativeCodexSnapshot() {
     if (typeof this.platform?.snapshotNativeCodexState !== "function") return null;
     const snapshot = await this.platform.snapshotNativeCodexState();
-    const cdpArgument = `--remote-debugging-port=${this.cdpPort}`;
     const processes = (Array.isArray(snapshot?.processes) ? snapshot.processes : [])
-      .filter(({ command }) => !hasExactCommandArgument(command, cdpArgument));
+      .filter(({ command }) => !String(command).includes("--user-data-dir="));
     return {
       count: processes.length,
       processes,
@@ -271,11 +265,24 @@ export class RuntimeManager {
     };
   }
 
+  async syncManualLaunchBaseline() {
+    const snapshot = await this.nativeCodexSnapshot();
+    if (!snapshot) return;
+    this.manualLaunchBaselinePids = new Set(snapshot.pids);
+    this.manualLaunchArmed = true;
+  }
+
+  async clearOwnedCodexMarker() {
+    await unlink(this.paths.codexPidPath).catch((error) => {
+      if (error.code !== "ENOENT") this.logger.warn?.("MineCodex could not clear its ChatGPT owner marker", error.message);
+    });
+  }
+
   async startManualLaunchMonitor() {
     if (this.manualLaunchMonitorPromise || typeof this.platform?.snapshotNativeCodexState !== "function") return;
-    const snapshot = await this.nativeCodexSnapshot();
-    this.manualLaunchBaselinePids = new Set(snapshot?.pids ?? []);
-    this.manualLaunchArmed = this.manualLaunchBaselinePids.size === 0;
+    // 登录恢复时 ChatGPT 可能先于服务启动，首次扫描也必须纳入增强流程。
+    this.manualLaunchBaselinePids.clear();
+    this.manualLaunchArmed = true;
     this.manualLaunchMonitorStopped = false;
     const monitor = this.monitorManualCodexLaunches().catch((error) => {
       if (!this.manualLaunchMonitorStopped) {
@@ -322,84 +329,130 @@ export class RuntimeManager {
     this.manualLaunchArmed = false;
   }
 
+  async isManualTakeoverAllowed(processInfo) {
+    if (typeof this.platform?.codexProcessStartedMsAgo !== "function") return true;
+    let startedMsAgo;
+    try {
+      startedMsAgo = await this.platform.codexProcessStartedMsAgo(processInfo);
+    } catch (error) {
+      this.logger.warn?.("MineCodex could not read the ChatGPT start time", error.message);
+      return true;
+    }
+    if (!Number.isInteger(startedMsAgo) || startedMsAgo < 0) return true;
+    return startedMsAgo < this.manualTakeoverGraceMs;
+  }
+
   async reconcileManualCodexLaunch() {
-    if (this.manualLaunchMonitorStopped) return false;
+    if (this.manualLaunchMonitorStopped || this.manualLaunchSuppressionDepth > 0) return false;
     const snapshot = await this.nativeCodexSnapshot();
     if (!snapshot) return false;
-
-    if (this.manualLaunchBaselinePids.size > 0) {
-      const baselineStillRunning = [...this.manualLaunchBaselinePids]
-        .some((pid) => snapshot.pids.has(pid));
-      if (baselineStillRunning) return false;
-      this.manualLaunchBaselinePids.clear();
-      if (snapshot.count === 0) {
-        this.manualLaunchArmed = true;
-        return false;
-      }
-      this.manualLaunchArmed = true;
+    if (this.enhancedCodex && !snapshot.pids.has(this.enhancedCodex.pid)) {
+      if (this.enhancedCodex.owned) await this.clearOwnedCodexMarker();
+      this.enhancedCodex = null;
     }
-
     if (snapshot.count === 0) {
+      if (this.enhancedCodex?.owned) await this.clearOwnedCodexMarker();
+      this.enhancedCodex = null;
+      this.manualLaunchBaselinePids.clear();
       this.manualLaunchArmed = true;
       return false;
     }
     if (!this.manualLaunchArmed) return false;
+    const newProcesses = snapshot.processes.filter(({ pid }) => !this.manualLaunchBaselinePids.has(pid));
+    this.manualLaunchBaselinePids = new Set(snapshot.pids);
+    if (newProcesses.length === 0) return false;
+    if (newProcesses.length > 1) {
+      this.enhancementFailure = {
+        code: "MULTIPLE_CHATGPT_LAUNCHES",
+        message: "MineCodex found multiple new official ChatGPT processes and did not terminate any of them.",
+        phase: "launch",
+      };
+      return false;
+    }
 
-    const observedPids = new Set(snapshot.pids);
+    const observedProcess = newProcesses[0];
     this.manualLaunchArmed = false;
-    this.manualLaunchBaselinePids = observedPids;
+    this.enhancementFailure = null;
+    this.manualLaunchSuppressionDepth += 1;
     return this.enqueue(async () => {
-      if (this.manualLaunchMonitorStopped) return false;
-      const latest = await this.nativeCodexSnapshot();
-      const observedProcessStillRunning = latest
-        && [...observedPids].some((pid) => latest.pids.has(pid));
-      if (!observedProcessStillRunning) {
-        if (!latest?.count) {
-          this.manualLaunchBaselinePids.clear();
+      try {
+        if (this.manualLaunchMonitorStopped) return false;
+        const latest = await this.nativeCodexSnapshot();
+        const currentProcess = latest?.processes.find((candidate) => (
+          candidate.pid === observedProcess.pid
+          && candidate.command === observedProcess.command
+        ));
+        if (!currentProcess) {
           this.manualLaunchArmed = true;
+          return false;
         }
-        return false;
-      }
-
-      await this.stopInternal();
-      let terminated;
-      try {
-        terminated = await this.platform.terminateNativeCodex();
-      } catch (error) {
-        await this.restoreIdleRuntimeAfterAdoptionFailure(error);
-        throw error;
-      }
-
-      if (!(terminated > 0)) {
-        await this.startInternal();
-        this.manualLaunchBaselinePids.clear();
-        this.manualLaunchArmed = true;
-        return false;
-      }
-
-      try {
-        const status = await this.startInternal({ launchCodex: true });
-        this.manualLaunchBaselinePids.clear();
-        this.manualLaunchArmed = true;
-        return status;
-      } catch (error) {
-        this.manualLaunchBaselinePids.clear();
+        try {
+          if (!(await this.isManualTakeoverAllowed(currentProcess))) {
+            this.enhancementFailure = {
+              code: "OFFICIAL_CHATGPT_IN_USE",
+              message: "MineCodex left the official ChatGPT instance running because it was already in use.",
+              phase: "launch",
+            };
+            return null;
+          }
+          const result = await this.launchCoordinator.ensureObservedLaunch(currentProcess, {
+            stopRuntime: () => this.stopInternal(),
+            startRuntime: () => this.startInternal(),
+            waitForHealthy: () => this.waitForHealthyRuntime(),
+          });
+          this.enhancedCodex = result.codex;
+          this.enhancementFailure = null;
+          if (this.enhancedCodex.owned) await this.writeOwnedCodexPid(this.enhancedCodex);
+          await this.syncManualLaunchBaseline();
+          return result;
+        } catch (error) {
+          this.enhancementFailure = normalizedFailure({
+            code: error.code ?? "CHATGPT_ENHANCEMENT_FAILED",
+            message: error.message,
+            phase: "launch",
+          });
+          try {
+            await this.startInternal();
+          } catch (recoveryError) {
+            throw new Error(
+              `${error.message}; idle RuntimeHost recovery failed: ${recoveryError.message}`,
+              { cause: error },
+            );
+          }
+          throw error;
+        }
+      } finally {
         this.manualLaunchArmed = true;
-        await this.restoreIdleRuntimeAfterAdoptionFailure(error);
-        throw error;
+        await this.syncManualLaunchBaseline().catch((error) => {
+          this.logger.warn?.("MineCodex could not refresh the ChatGPT launch baseline", error.message);
+        });
+        this.manualLaunchSuppressionDepth -= 1;
       }
     });
   }
 
-  async restoreIdleRuntimeAfterAdoptionFailure(failure) {
-    try {
-      await this.startInternal();
-    } catch (recoveryError) {
-      throw new Error(
-        `${failure.message}; idle RuntimeHost recovery failed: ${recoveryError.message}`,
-        { cause: failure },
-      );
+  async writeOwnedCodexPid(processInfo) {
+    if (!this.paths.codexPidPath) return;
+    const marker = {
+      version: 1,
+      pid: processInfo?.pid,
+      command: processInfo?.command,
+    };
+    if (!Number.isInteger(marker.pid) || marker.pid <= 1 || typeof marker.command !== "string" || !marker.command) {
+      throw new Error("MineCodex cannot persist incomplete ChatGPT ownership identity.");
+    }
+    await writeFile(this.paths.codexPidPath, `${JSON.stringify(marker)}\n`, { mode: 0o600 });
+  }
+
+  async waitForHealthyRuntime(initialStatus = null, timeoutMs = 25_000) {
+    const deadline = Date.now() + timeoutMs;
+    let status = initialStatus ?? this.status();
+    while (Date.now() < deadline) {
+      if (!status.healthy) status = await this.refreshStatus();
+      if (status.healthy) return status;
+      await this.sleep(100);
     }
+    throw new Error("MineCodex RuntimeHost did not prove renderer discovery and feature injection.");
   }
 
   async stopInternal() {
@@ -477,11 +530,54 @@ export class RuntimeManager {
 
   restart() {
     if (this.restartInFlight) return this.restartInFlight;
+    this.manualLaunchSuppressionDepth += 1;
     const operation = this.enqueue(async () => {
-      await this.stopInternal();
-      await this.platform.terminateOwnedCodex(this.paths);
-      await this.platform.terminateNativeCodex?.();
-      return this.startInternal({ launchCodex: true });
+      try {
+        const previousCodex = this.enhancedCodex;
+        if (previousCodex?.owned && typeof this.platform?.terminateNativeCodex === "function") {
+          const result = await this.launchCoordinator.relaunchOwned({
+            stopRuntime: () => this.stopInternal(),
+            terminateOwned: async () => {
+              const terminated = await this.platform.terminateNativeCodex(previousCodex.pid, previousCodex.command);
+              if (terminated !== 1) throw new Error(`MineCodex could not terminate owned ChatGPT pid ${previousCodex.pid}.`);
+            },
+            startRuntime: () => this.startInternal(),
+            waitForHealthy: (status) => this.waitForHealthyRuntime(status),
+          });
+          this.enhancedCodex = result.codex;
+          this.enhancementFailure = null;
+          if (this.enhancedCodex.pid) await this.writeOwnedCodexPid(this.enhancedCodex);
+          await this.syncManualLaunchBaseline();
+          return result;
+        }
+        if (previousCodex && !previousCodex.owned) {
+          await this.stopInternal();
+          const healthy = await this.waitForHealthyRuntime(await this.startInternal());
+          await this.syncManualLaunchBaseline();
+          return { ...healthy, codex: previousCodex };
+        }
+        await this.stopInternal();
+        if (!previousCodex) await this.platform.terminateOwnedCodex?.(this.paths);
+        this.enhancedCodex = null;
+        this.enhancementFailure = null;
+        if (typeof this.platform?.openNativeCodex !== "function") return this.startInternal();
+        const launched = await this.platform.openNativeCodex({ cdpPort: this.cdpPort });
+        const status = await this.startInternal();
+        const healthy = await this.waitForHealthyRuntime(status);
+        this.enhancedCodex = {
+          pid: launched?.pid ?? null,
+          owned: true,
+          command: launched?.command ?? null,
+        };
+        if (this.enhancedCodex.pid) await this.writeOwnedCodexPid(this.enhancedCodex);
+        await this.syncManualLaunchBaseline();
+        return { ...healthy, codex: this.enhancedCodex };
+      } finally {
+        await this.syncManualLaunchBaseline().catch((error) => {
+          this.logger.warn?.("MineCodex could not refresh the ChatGPT launch baseline", error.message);
+        });
+        this.manualLaunchSuppressionDepth -= 1;
+      }
     });
     this.restartInFlight = operation;
     const shared = this.restartInFlight.finally(() => {
@@ -492,8 +588,10 @@ export class RuntimeManager {
 
   status() {
     const running = Boolean(this.child && !hasExited(this.child));
+    const healthy = running && this.ready?.renderer?.active === true;
     return {
       running,
+      healthy,
       pid: this.child?.pid ?? null,
       appliedFeatures: running ? [...this.appliedFeatures] : [],
       plugins: running ? [...this.plugins] : [],
@@ -501,7 +599,10 @@ export class RuntimeManager {
       ready: running ? this.ready : null,
       runtimeSessionId: running ? this.ready?.runtimeSessionId ?? null : null,
       renderer: running ? this.ready?.renderer ?? null : null,
-      failures: running ? [...(this.ready?.failures ?? [])] : [],
+      codex: this.enhancedCodex ? { ...this.enhancedCodex } : null,
+      failures: running
+        ? [...(this.ready?.failures ?? []), ...(this.enhancementFailure ? [this.enhancementFailure] : [])]
+        : (this.enhancementFailure ? [this.enhancementFailure] : []),
     };
   }
 }

package/packages/runtime-host/src/codex-runtime.mjs

@@ -1,5 +1,4 @@
 import { randomBytes } from "node:crypto";
-import { spawn } from "node:child_process";
 import { mkdir, stat } from "node:fs/promises";
 import path from "node:path";
 
@@ -321,6 +320,9 @@ export function createInjectionSource(features, {
       [data-codex-model-slider-trigger-label] {
         display: inline; overflow: visible; text-overflow: clip; white-space: nowrap;
       }
+      [data-codex-model-slider-trigger] [class*="_ModelPickerTriggerEffortLabel_"] {
+        display: inline-flex; align-items: center; align-self: center;
+      }
       html[data-codex-model-slider-selecting-effort] [role="menu"][data-state="open"]:not(:has([data-reasoning-slider])) {
         visibility: hidden !important; opacity: 0 !important; animation: none !important; pointer-events: none !important;
       }
@@ -374,7 +376,6 @@ export function createInjectionSource(features, {
     if (modelSelectorFeature) {
       document.documentElement.setAttribute("data-codex-model-slider-catalog-ready", "");
       document.documentElement.append(modelSelectorStyle);
-      void loadNativeFastIcon();
     }
 
     for (const feature of pageScriptFeatures) {
@@ -617,32 +618,6 @@ export function createInjectionSource(features, {
       return icon;
     }
 
-    async function loadNativeFastIcon() {
-      const sourceLink = document.querySelector('link[href*="/assets/app-initial-"][href$=".js"]');
-      if (!sourceLink?.href) return;
-      try {
-        const source = await fetch(sourceLink.href).then((response) => response.text());
-        const active = source.match(/d:`(M11\.9125 21\.4125[^`]+)`,fill:`currentColor`/);
-        const inactive = source.match(/d:`(M7\.38 16\.2207[^`]+)`,fill:`currentColor`/);
-        if (!active?.[1] || !inactive?.[1]) return;
-        modelSelectorNativeFastIcons = {
-          active: { viewBox: "0 0 24 24", markup: `<path d="${active[1]}" fill="currentColor" />` },
-          inactive: {
-            viewBox: "0 0 20 20",
-            markup: `<g transform="translate(2.43 1.609)"><path d="${inactive[1]}" fill="currentColor" /></g>`,
-          },
-        };
-        document.querySelectorAll("[data-codex-model-slider-fast]").forEach((button) => {
-          const icon = createNativeFastIcon(button.getAttribute("aria-pressed") === "true");
-          const content = button.querySelector("[data-codex-model-slider-fast-content]");
-          if (icon && content) content.replaceChildren(icon);
-        });
-        queueEnsure();
-      } catch {
-        // Leave the native control untouched when this private Codex asset moves.
-      }
-    }
-
     function nativeCssModuleClass(tokenName, root = document) {
       const pattern = new RegExp(`^_${tokenName}_[A-Za-z0-9_-]+$`);
       const live = Array.from(root.querySelectorAll(`[class*="_${tokenName}_"]`))
@@ -674,11 +649,33 @@ export function createInjectionSource(features, {
       return null;
     }
 
+    function captureNativeFastIcon() {
+      const capture = (state, pathPrefix) => {
+        if (modelSelectorNativeFastIcons?.[state]) return;
+        const path = Array.from(document.querySelectorAll("svg path")).find(
+          (candidate) => candidate.getAttribute("d")?.startsWith(pathPrefix),
+        );
+        const svg = path?.closest("svg");
+        if (!svg) return;
+        const template = svg.cloneNode(true);
+        template.removeAttribute("id");
+        template.removeAttribute("width");
+        template.removeAttribute("height");
+        if (!modelSelectorNativeFastIcons) modelSelectorNativeFastIcons = {};
+        modelSelectorNativeFastIcons[state] = template;
+      };
+      capture("active", "M11.9125 21.4125");
+      capture("inactive", "M7.38 16.2207");
+      return modelSelectorNativeFastIcons;
+    }
+
     function createNativeFastIcon(active) {
-      const definition = modelSelectorNativeFastIcons?.[active ? "active" : "inactive"];
-      const icon = createModelSelectorIcon(definition, { brand: true });
+      const template = captureNativeFastIcon()?.[active ? "active" : "inactive"];
+      if (!template) return null;
+      const icon = template.cloneNode(true);
+      icon.setAttribute("aria-hidden", "true");
       const iconClass = nativeCssModuleClass("FastModeIcon");
-      if (icon && iconClass) icon.classList.add(iconClass);
+      if (iconClass && !icon.classList.contains(iconClass)) icon.classList.add(iconClass);
       return icon;
     }
 
@@ -1847,8 +1844,14 @@ export function createInjectionSource(features, {
       const model = modelDefinitionFor(identity, selector);
       const efforts = model?.supportedReasoningLevels ?? [];
       if (!model || efforts.length < 2) return false;
-      const selectedEffort = document.querySelector("[data-codex-intelligence-trigger]")
-        ?.getAttribute("data-selected-reasoning-effort") ?? model.defaultReasoningLevel ?? efforts[0].effort;
+      // 控制器推导的任务内实际 effort 优先，避免子任务/主任务切换后触发器属性滞后；
+      // 触发器属性仅在控制器无法解析时作为实时回退，静态目录默认值最后兜底。
+      const nativeModel = nativeCatalogModelFor(identity);
+      const selectedEffort = nativeModel?.defaultReasoningLevel
+        ?? document.querySelector("[data-codex-intelligence-trigger]")
+          ?.getAttribute("data-selected-reasoning-effort")
+        ?? model.defaultReasoningLevel
+        ?? efforts[0].effort;
       const selectedServiceTier = nativeComposerModelController()?.selectedServiceTier;
       const serviceTierKey = selectedServiceTier?.id ?? selectedServiceTier ?? "standard";
       const key = `${identity.raw}:${selectedEffort}:${serviceTierKey}:${efforts.map((level) => level.effort).join(",")}`;
@@ -1857,7 +1860,6 @@ export function createInjectionSource(features, {
         parentMenu.firstElementChild
           ?.querySelector("[data-model-picker-power-slider] [class*='_TickRail_'] > span"),
       );
-      const nativeModel = nativeCatalogModelFor(identity);
       const templateWaitCount = Number(parentMenu.getAttribute("data-codex-model-slider-template-wait") ?? 0);
       if (nativeModel?.slug.toLowerCase().startsWith("gpt-") && !nativeTemplateReady && templateWaitCount < 3) {
         parentMenu.setAttribute("data-codex-model-slider-template-wait", String(templateWaitCount + 1));
@@ -1953,6 +1955,7 @@ export function createInjectionSource(features, {
     function ensureModelSelector() {
       const selector = modelSelectorFeature?.modelSelector;
       if (!selector) return;
+      captureNativeFastIcon();
       pruneModelSubmenuPositionObservers();
       if (!modelSelectorStyle.isConnected) document.head?.append(modelSelectorStyle);
       enhanceComposerModelTrigger(selector);
@@ -2997,28 +3000,18 @@ export function createInjectionSource(features, {
           const moduleUrl = await waitForNativeTabModuleUrl();
           if (!moduleUrl) throw new Error("Codex app-initial modulepreload was not found");
           const appModule = await import(moduleUrl);
-          if (typeof appModule.Gtt !== "function") {
-            throw new Error("Codex right-panel controller factory is unavailable");
-          }
-          if (typeof appModule.hkt !== "function" || typeof appModule.Skt !== "function") {
-            throw new Error("Codex React runtime factories are unavailable");
-          }
-          const controller = appModule.Gtt("right");
-          const jsx = appModule.hkt();
-          const React = appModule.Skt();
-          if (
-            typeof controller?.openTab !== "function"
-            || typeof controller?.activateTab !== "function"
-            || typeof controller?.closeTab !== "function"
-            || !controller?.tabById$
-            || typeof jsx?.jsx !== "function"
-            || typeof React?.useLayoutEffect !== "function"
-            || typeof React?.useRef !== "function"
-          ) throw new Error("Codex native tab capability is incomplete");
+          const controller = Object.values(appModule).find((value) => (
+            value
+            && typeof value === "object"
+            && typeof value.openTab === "function"
+            && typeof value.closeTab === "function"
+            && typeof value.activateTab === "function"
+            && value.panelId === "right"
+          ));
+          if (!controller) throw new Error("Codex right-panel controller is unavailable");
+          if (!controller?.tabById$) throw new Error("Codex native tab capability is incomplete");
           nativeTabCapability = {
             controller,
-            jsx,
-            React,
             moduleAsset: moduleUrl.split("/").pop(),
           };
           nativeTabCapabilityError = null;
@@ -3033,10 +3026,20 @@ export function createInjectionSource(features, {
       return capability;
     }
 
-    function nativeDetailIcon(feature, detail, jsx) {
+    function nativeReactElement(type, props) {
+      return {
+        $$typeof: Symbol.for("react.transitional.element"),
+        type,
+        key: null,
+        ref: null,
+        props: props ?? {},
+      };
+    }
+
+    function nativeDetailIcon(feature, detail) {
       const icon = detail.icon ?? feature.icon;
       if (!icon?.markup) return undefined;
-      return jsx.jsx("svg", {
+      return nativeReactElement("svg", {
         width: 16,
         height: 16,
         viewBox: icon.viewBox ?? "0 0 24 24",
@@ -3051,42 +3054,13 @@ export function createInjectionSource(features, {
       });
     }
 
-    function nativeDetailComponent(feature, detail, capability) {
+    function nativeDetailComponent(feature, detail) {
       const detailKey = `${feature.id}:${detail.id}`;
       let Component = nativeDetailComponents.get(detailKey);
       if (Component) return Component;
-      const { jsx, React } = capability;
+      const frameName = surfaceFrameName(feature.id);
       Component = function CodexPersonalDetailTab() {
-        const elementRef = React.useRef(null);
-        const frameRef = React.useRef(null);
-        const recordKeyRef = React.useRef(null);
-        const frameNameRef = React.useRef(null);
-        frameNameRef.current ??= surfaceFrameName(feature.id);
-        React.useLayoutEffect(() => {
-          const element = elementRef.current;
-          const frame = frameRef.current;
-          if (!element || !frame) return undefined;
-          const instanceId = crypto.randomUUID?.()
-            ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
-          const recordKey = surfaceKey(feature.id, "native-detail", `${detail.id}:${instanceId}`);
-          recordKeyRef.current = recordKey;
-          registerSurface(recordKey, feature, "detail", detail.surfaceUrl, element, frame, detail.id);
-          let keys = nativeDetailSurfaceKeys.get(detailKey);
-          if (!keys) {
-            keys = new Set();
-            nativeDetailSurfaceKeys.set(detailKey, keys);
-          }
-          keys.add(recordKey);
-          queueTheme();
-          return () => {
-            keys.delete(recordKey);
-            if (keys.size === 0) nativeDetailSurfaceKeys.delete(detailKey);
-            removeSurfaceRecord(recordKey);
-            recordKeyRef.current = null;
-          };
-        }, []);
-        return jsx.jsx("div", {
-          ref: elementRef,
+        return nativeReactElement("div", {
           "data-codex-personal-native-detail": detailKey,
           style: {
             height: "100%",
@@ -3094,9 +3068,8 @@ export function createInjectionSource(features, {
             overflow: "hidden",
             background: "var(--color-token-main-surface-primary)",
           },
-          children: jsx.jsx("iframe", {
-            ref: frameRef,
-            name: frameNameRef.current,
+          children: nativeReactElement("iframe", {
+            name: frameName,
             src: "about:blank",
             title: detail.label,
             allow: "clipboard-write",
@@ -3124,17 +3097,17 @@ export function createInjectionSource(features, {
       return reloaded;
     }
 
-    async function waitForNativeDetailTabMount(scope, controller, tabId, detailKey) {
+    async function waitForNativeDetailTabElement(detailKey) {
       const deadline = performance.now() + 2_000;
       do {
-        let registered = false;
-        try {
-          registered = scope.get(controller.tabById$, tabId) != null;
-        } catch {}
-        if (registered && nativeDetailSurfaceKeys.has(detailKey)) return true;
+        const element = document.querySelector(
+          `[data-codex-personal-native-detail="${detailKey}"]`,
+        );
+        const frame = element?.querySelector("iframe");
+        if (element && frame) return { element, frame };
         await new Promise((resolve) => setTimeout(resolve, 25));
       } while (performance.now() < deadline);
-      return false;
+      return null;
     }
 
     async function openNativeDetailTab(feature, detail) {
@@ -3146,7 +3119,7 @@ export function createInjectionSource(features, {
         return null;
       }
 
-      const { controller, jsx } = capability;
+      const { controller } = capability;
       const tabId = `${feature.id}-${detail.id}`;
       const detailKey = `${feature.id}:${detail.id}`;
       let session = Array.from(nativeOpenTabSessions).find((candidate) => (
@@ -3165,15 +3138,22 @@ export function createInjectionSource(features, {
       }
 
       try {
-        controller.openTab(scope, nativeDetailComponent(feature, detail, capability), {
+        controller.openTab(scope, nativeDetailComponent(feature, detail), {
           id: tabId,
           kind: tabId,
           title: detail.label,
           tooltip: detail.label,
-          icon: nativeDetailIcon(feature, detail, jsx),
+          icon: nativeDetailIcon(feature, detail),
           isClosable: true,
           props: {},
-          onClose: () => nativeOpenTabSessions.delete(session),
+          onClose: () => {
+            nativeOpenTabSessions.delete(session);
+            const closedKeys = nativeDetailSurfaceKeys.get(detailKey);
+            if (closedKeys) {
+              for (const key of closedKeys) removeSurfaceRecord(key);
+              nativeDetailSurfaceKeys.delete(detailKey);
+            }
+          },
         });
       } catch (error) {
         if (isNewSession) nativeOpenTabSessions.delete(session);
@@ -3181,15 +3161,29 @@ export function createInjectionSource(features, {
         return null;
       }
 
-      if (!await waitForNativeDetailTabMount(scope, controller, tabId, detailKey)) {
-        if (isNewSession) nativeOpenTabSessions.delete(session);
-        if (!focusedExisting) {
-          try {
-            controller.closeTab(scope, tabId);
-          } catch {}
+      if (!nativeDetailSurfaceKeys.has(detailKey)) {
+        const mounted = await waitForNativeDetailTabElement(detailKey);
+        if (!mounted) {
+          if (isNewSession) nativeOpenTabSessions.delete(session);
+          if (!focusedExisting) {
+            try {
+              controller.closeTab(scope, tabId);
+            } catch {}
+          }
+          nativeTabCapabilityError = new Error("Codex native right-panel Tab did not mount");
+          return null;
         }
-        nativeTabCapabilityError = new Error("Codex native right-panel Tab did not mount");
-        return null;
+        const instanceId = crypto.randomUUID?.()
+          ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        const recordKey = surfaceKey(feature.id, "native-detail", `${detail.id}:${instanceId}`);
+        registerSurface(recordKey, feature, "detail", detail.surfaceUrl, mounted.element, mounted.frame, detail.id);
+        let keys = nativeDetailSurfaceKeys.get(detailKey);
+        if (!keys) {
+          keys = new Set();
+          nativeDetailSurfaceKeys.set(detailKey, keys);
+        }
+        keys.add(recordKey);
+        queueTheme();
       }
 
       nativeTabCapabilityError = null;
@@ -3207,6 +3201,9 @@ export function createInjectionSource(features, {
     }
 
     function closeNativeDetailTabs() {
+      for (const keys of Array.from(nativeDetailSurfaceKeys.values())) {
+        for (const key of keys) removeSurfaceRecord(key);
+      }
       for (const session of Array.from(nativeOpenTabSessions)) {
         try {
           session.controller.closeTab(session.scope, session.tabId);
@@ -3923,7 +3920,7 @@ export class CodexRuntime {
     cdpPort = 9231,
     logger = console,
     fetchImpl = globalThis.fetch,
-    spawnProcess = spawn,
+    launchApplication = null,
     connectClient = connect,
     sleep = (timeoutMs) => new Promise((resolve) => setTimeout(resolve, timeoutMs)),
     availabilityTimeoutMs = 20_000,
@@ -3942,7 +3939,7 @@ export class CodexRuntime {
     this.cdpPort = cdpPort;
     this.logger = logger;
     this.fetchImpl = fetchImpl;
-    this.spawnProcess = spawnProcess;
+    this.launchApplication = launchApplication;
     this.connectClient = connectClient;
     this.sleep = sleep;
     this.availabilityTimeoutMs = availabilityTimeoutMs;
@@ -4079,17 +4076,19 @@ export class CodexRuntime {
   }
 
   launchManagedCodex() {
-    const child = this.spawnProcess(
-      this.appPath,
-      [
+    if (typeof this.launchApplication !== "function") {
+      throw new Error("CodexRuntime requires an explicit application launcher for isolated tests.");
+    }
+    const child = this.launchApplication({
+      appPath: this.appPath,
+      args: [
         `--user-data-dir=${this.profileDir}`,
         "--remote-debugging-address=127.0.0.1",
         `--remote-debugging-port=${this.cdpPort}`,
         `--remote-allow-origins=http://127.0.0.1:${this.cdpPort}`,
         "--no-first-run",
       ],
-      { detached: true, stdio: "ignore" },
-    );
+    });
     this.managedCodexChild = child;
     this.appPid = child.pid ?? null;
     this.notifyManagedCodexPidChange(this.appPid);

package/packages/runtime-host/src/main.mjs

@@ -17,7 +17,6 @@ const featuresRoot = process.env.CODEX_FEATURES_ROOT ?? path.dirname(runtimeRoot
 const legacyDataDir = process.env.CODEX_IMAGE_HOST_DATA_DIR ?? path.join(os.homedir(), ".codex-image-host");
 const profileDir = process.env.CODEX_RUNTIME_PROFILE_DIR ?? path.join(legacyDataDir, "codex-profile");
 const cdpPort = Number(process.env.CODEX_RUNTIME_CDP_PORT ?? 9231);
-const launchCodex = process.env.MINECODEX_LAUNCH_CODEX === "1";
 
 const discoveredFeatures = await discoverFeatures(featuresRoot);
 if (!discoveredFeatures.length) throw new Error(`No codex-feature.json files found under ${featuresRoot}`);
@@ -66,13 +65,12 @@ runtime = new CodexRuntime({
   featureInstanceId,
   profileDir,
   cdpPort,
-  appPath: process.env.MINECODEX_CODEX_EXECUTABLE || undefined,
   onManagedCodexPidChange: updateCodexPidFile,
   onStatusChange: requestReadyFileRefresh,
 });
 
 try {
-  await runtime.start({ launchCodex });
+  await runtime.start();
   runtimeReady = true;
   await writeReadyFile();
 } catch (error) {