minecodex 1.0.82 → 1.1.0

package/packages/cli/src/platform.mjs

@@ -14,8 +14,10 @@ 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 CODEX_WINDOWS_PACKAGE_FAMILY = "OpenAI.Codex_2p2nqsd0c76g0";
 export const MIN_NODE_VERSION = Object.freeze({ major: 22, minor: 5, patch: 0 });
 export const MIN_MACOS_VERSION = Object.freeze({ major: 13, darwinMajor: 22 });
+export const WINDOWS_SERVICE_TASK_NAME = "MineCodex";
 
 function xml(value) {
   return String(value)
@@ -175,6 +177,59 @@ export function serviceIsAbsent(error) {
   );
 }
 
+// PowerShell 统一经 -EncodedCommand 执行：base64(UTF-16LE) 规避引号与编码问题。
+function encodePowerShellCommand(script) {
+  return Buffer.from(String(script), "utf16le").toString("base64");
+}
+
+// Windows 控制台默认代码页不是 UTF-8，脚本内强制统一输出编码，
+// 保证中文用户名等路径在 node 侧按 utf8 解码不失真。
+const POWERSHELL_PREAMBLE = "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; $ErrorActionPreference = 'Stop';";
+
+export function isExactCodexProcessWindows(command, installation) {
+  const executable = String(installation?.executable ?? "");
+  if (!executable) return false;
+  const value = String(command ?? "").trim();
+  if (!value) return false;
+  // Electron 子进程使用同一 exe，接管列表只能包含主进程。
+  if (/(?:^|\s)"?--type(?:=|\s)/.test(value)) return false;
+  // Windows 命令行对含空格路径加引号包裹（"C:\...\ChatGPT.exe" args），先剥引号再比较。
+  if (value.startsWith('"')) {
+    const closing = value.indexOf('"', 1);
+    if (closing === -1) return false;
+    if (value.slice(1, closing).toLowerCase() !== executable.toLowerCase()) return false;
+    const rest = value.slice(closing + 1);
+    return rest === "" || rest.startsWith(" ");
+  }
+  const lowerValue = value.toLowerCase();
+  const lowerExecutable = executable.toLowerCase();
+  return lowerValue === lowerExecutable || lowerValue.startsWith(lowerExecutable + " ");
+}
+
+export function buildWindowsServiceCommand({ nodePath, cliPath, paths }) {
+  return [
+    "@echo off",
+    "rem MineCodex background service entry. Managed by mcx install; do not edit.",
+    'cd /d "%~dp0"',
+    `${cmdQuote(nodePath)} ${cmdQuote(cliPath)} serve >>${cmdQuote(paths.serviceLogPath)} 2>${cmdQuote(paths.serviceErrorLogPath)}`,
+    "",
+  ].join("\r\n");
+}
+
+// cmd 的引号转义是内部双引号翻倍，与 JSON 转义规则不同，不能混用。
+function cmdQuote(value) {
+  return '"' + String(value).replaceAll('"', '""') + '"';
+}
+
+export function buildWindowsServiceRuntimeConfig({ nodePath, cliPath, paths }) {
+  return JSON.stringify({
+    nodePath,
+    cliPath,
+    serviceLogPath: paths.serviceLogPath,
+    serviceErrorLogPath: paths.serviceErrorLogPath,
+  });
+}
+
 async function waitForProcessExit(pid, { processApi, timeoutMs = 8_000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
@@ -690,3 +745,465 @@ export class MacPlatformAdapter {
     throw new Error(`LaunchServices did not expose a loopback CDP ChatGPT process on port ${cdpPort}.`);
   }
 }
+
+export class WindowsPlatformAdapter {
+  constructor({
+    platform = process.platform,
+    homeDir = os.homedir(),
+    appDataDir = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"),
+    localAppDataDir = process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local"),
+    execFile = defaultExecFile,
+    fileSystem = defaultFileSystem,
+    processApi = process,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    codexInstallation,
+  } = {}) {
+    this.platform = platform;
+    this.homeDir = homeDir;
+    this.appDataDir = appDataDir;
+    this.localAppDataDir = localAppDataDir;
+    this.execFile = execFile;
+    this.fileSystem = fileSystem;
+    this.processApi = processApi;
+    this.sleep = sleep;
+    this.codexInstallation = codexInstallation;
+    this.codexInstallationFingerprint = null;
+    this.codexInstallationInjected = Boolean(codexInstallation);
+  }
+
+  async powershell(script) {
+    const { stdout } = await this.execFile("powershell.exe", [
+      "-NoProfile", "-NonInteractive", "-EncodedCommand",
+      encodePowerShellCommand(POWERSHELL_PREAMBLE + "\n" + String(script)),
+    ]);
+    return String(stdout ?? "");
+  }
+
+  assertInstallSupported() {
+    if (this.platform !== "win32") {
+      throw new Error("Windows installation requires Windows 10 or newer (win32).");
+    }
+  }
+
+  async assertCodexInstalled() {
+    const script = [
+      "$pkg = Get-AppxPackage -Name 'OpenAI.Codex' -ErrorAction Stop | Select-Object -First 1;",
+      "if (-not $pkg) { throw 'Codex Desktop (OpenAI.Codex) was not found for the current user.' }",
+      "$exe = Join-Path $pkg.InstallLocation 'app\\ChatGPT.exe';",
+      "if (-not (Test-Path $exe)) { throw 'ChatGPT.exe is missing from the OpenAI.Codex package.' }",
+      "$sig = Get-AuthenticodeSignature -FilePath $exe;",
+      "[pscustomobject]@{",
+      "  installLocation = [string]$pkg.InstallLocation;",
+      "  packageFamilyName = [string]$pkg.PackageFamilyName;",
+      "  version = [string]$pkg.Version;",
+      "  exePath = $exe;",
+      "  signatureStatus = [string]$sig.Status;",
+      "  signerSubject = [string]$sig.SignerCertificate.Subject;",
+      "} | ConvertTo-Json -Compress",
+    ].join("\n");
+    const info = JSON.parse(await this.powershell(script));
+    if (info.packageFamilyName !== CODEX_WINDOWS_PACKAGE_FAMILY) {
+      throw new Error(`Refusing non-official ChatGPT package: ${info.packageFamilyName || "unknown"}`);
+    }
+    if (info.signatureStatus !== "Valid" || !/openai/i.test(info.signerSubject ?? "")) {
+      throw new Error("Refusing ChatGPT with an unexpected signing identity.");
+    }
+    this.codexInstallation = Object.freeze({
+      appPath: info.installLocation,
+      executable: info.exePath,
+      packageFamilyName: info.packageFamilyName,
+      version: info.version,
+      signerSubject: info.signerSubject,
+      verified: true,
+    });
+    this.codexInstallationFingerprint = await this.readCodexInstallationFingerprint(this.codexInstallation);
+    this.codexInstallationInjected = false;
+    return this.codexInstallation;
+  }
+
+  async codex() {
+    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, "AppxManifest.xml"),
+    ];
+    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 pathExists(filePath) {
+    try {
+      if (this.fileSystem.stat) await this.fileSystem.stat(filePath);
+      else await this.fileSystem.readFile(filePath);
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    }
+  }
+
+  async queryScheduledTaskState() {
+    const stdout = await this.powershell([
+      // Get-ScheduledTask 对不存在的任务抛 terminating error，SilentlyContinue 拦不住，必须 try/catch。
+      "try { $task = Get-ScheduledTask -TaskName '" + WINDOWS_SERVICE_TASK_NAME + "' -ErrorAction Stop } catch { $task = $null }",
+      "if ($task) { Write-Output ([string]$task.State) } else { Write-Output 'Missing' }",
+    ].join("\n"));
+    return String(stdout).trim();
+  }
+
+  async isServiceRunning() {
+    return (await this.queryScheduledTaskState()) === "Running";
+  }
+
+  async isServiceInstalled(paths) {
+    return (await this.pathExists(paths.serviceAppPath)) || (await this.queryScheduledTaskState()) !== "Missing";
+  }
+
+  async serviceManagerStatus(paths) {
+    if (!(await this.pathExists(paths.serviceAppPath)) && (await this.queryScheduledTaskState()) === "Missing") {
+      return "not-found";
+    }
+    const state = await this.queryScheduledTaskState();
+    if (state === "Running" || state === "Ready") return "enabled";
+    if (state === "Disabled") return "disabled";
+    return "unknown";
+  }
+
+  async writeServiceRuntimeConfig(paths, content, mode = 0o600) {
+    const temporaryPath = paths.serviceRuntimeConfigPath + ".installing";
+    await this.fileSystem.writeFile(temporaryPath, content, { mode });
+    await this.fileSystem.rename(temporaryPath, paths.serviceRuntimeConfigPath);
+  }
+
+  async writeServiceCommand(paths, content) {
+    await this.fileSystem.writeFile(paths.serviceAppPath, content, { mode: 0o700 });
+  }
+
+  async snapshotServiceState(paths) {
+    const state = await this.queryScheduledTaskState();
+    const appExists = await this.pathExists(paths.serviceAppPath);
+    let runtimeConfig = { exists: false, content: null, mode: null };
+    if (appExists && paths.serviceRuntimeConfigPath) {
+      try {
+        const metadataPromise = this.fileSystem.stat
+          ? this.fileSystem.stat(paths.serviceRuntimeConfigPath).catch(() => null)
+          : Promise.resolve(null);
+        const [content, metadata] = await Promise.all([
+          this.fileSystem.readFile(paths.serviceRuntimeConfigPath, "utf8"),
+          metadataPromise,
+        ]);
+        runtimeConfig = { exists: true, content, mode: metadata?.mode };
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    let taskDefinition = { exists: false, content: null, mode: null };
+    if (state !== "Missing") {
+      try {
+        taskDefinition = { exists: true, content: await this.powershell("Export-ScheduledTask -TaskName '" + WINDOWS_SERVICE_TASK_NAME + "'"), mode: null };
+      } catch {
+        taskDefinition = { exists: true, content: null, mode: null };
+      }
+    }
+    return {
+      app: { exists: appExists, status: appExists ? await this.serviceManagerStatus(paths) : "not-found", runtimeConfig },
+      // 字段名沿用 mac 快照契约（plist），Windows 下内容为计划任务定义。
+      plist: taskDefinition,
+      running: state === "Running",
+    };
+  }
+
+  async installService({ cliPath, paths, start = true }) {
+    await this.stopService(paths, { ignoreErrors: false });
+    await this.fileSystem.mkdir(paths.serviceDir, { recursive: true, mode: 0o700 });
+    await this.fileSystem.mkdir(paths.logsDir, { recursive: true, mode: 0o700 });
+    await this.writeServiceRuntimeConfig(paths, buildWindowsServiceRuntimeConfig({ nodePath: process.execPath, cliPath, paths }));
+    await this.writeServiceCommand(paths, buildWindowsServiceCommand({ nodePath: process.execPath, cliPath, paths }));
+    await this.registerServiceTask(paths);
+    if (start) await this.startService(paths);
+  }
+
+  async registerServiceTask(paths) {
+    // ExecutionTimeLimit 0 表示不限时：服务是常驻进程，不能被默认 72h 限制回收。
+    const script = [
+      "$serviceCmd = '" + String(paths.serviceAppPath).replaceAll("'", "''") + "';",
+      '$action = New-ScheduledTaskAction -Execute \'cmd.exe\' -Argument (\'/c ""\' + $serviceCmd + \'""\');',
+      "$trigger = New-ScheduledTaskTrigger -AtLogOn;",
+      "$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -ExecutionTimeLimit ([TimeSpan]::Zero) -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1);",
+      "Register-ScheduledTask -TaskName '" + WINDOWS_SERVICE_TASK_NAME + "' -Action $action -Trigger $trigger -Settings $settings -Force | Out-Null;",
+      "Write-Output 'registered'",
+    ].join("\n");
+    await this.powershell(script);
+  }
+
+  async startService(paths) {
+    const state = await this.queryScheduledTaskState();
+    if (state === "Missing") throw new Error("MineCodex background task is not installed. Run mcx install first.");
+    if (state === "Disabled") throw new Error("MineCodex background task is disabled. Enable it in Task Scheduler, then run mcx install again.");
+    await this.powershell("Start-ScheduledTask -TaskName '" + WINDOWS_SERVICE_TASK_NAME + "'");
+  }
+
+  async stopService(paths, { ignoreErrors = false } = {}) {
+    try {
+      await this.powershell([
+        "try { $task = Get-ScheduledTask -TaskName '" + WINDOWS_SERVICE_TASK_NAME + "' -ErrorAction Stop } catch { $task = $null }",
+        "if ($task) { Stop-ScheduledTask -TaskName '" + WINDOWS_SERVICE_TASK_NAME + "' -ErrorAction Stop }",
+      ].join("\n"));
+    } catch (error) {
+      if (!ignoreErrors) throw error;
+    }
+  }
+
+  async assertServiceStopped() {
+    if (await this.isServiceRunning()) throw new Error("MineCodex scheduled task is still running.");
+  }
+
+  async restoreServiceState(snapshot, { cliPath, paths } = {}) {
+    await this.removeService(paths);
+    await this.assertServiceStopped();
+    if (snapshot?.app?.exists) {
+      await this.fileSystem.mkdir(paths.serviceDir, { recursive: true, mode: 0o700 });
+      await this.fileSystem.mkdir(paths.logsDir, { recursive: true, mode: 0o700 });
+      if (snapshot.app.runtimeConfig?.exists) {
+        await this.writeServiceRuntimeConfig(
+          paths,
+          snapshot.app.runtimeConfig.content,
+          snapshot.app.runtimeConfig.mode ? snapshot.app.runtimeConfig.mode & 0o777 : 0o600,
+        );
+      }
+      await this.writeServiceCommand(paths, buildWindowsServiceCommand({ nodePath: process.execPath, cliPath, paths }));
+      await this.registerServiceTask(paths);
+      if (snapshot.app.status === "enabled" || snapshot.running) await this.startService(paths);
+      return snapshot;
+    }
+    return snapshot;
+  }
+
+  async removeService(paths) {
+    await this.stopService(paths, { ignoreErrors: false });
+    await this.assertServiceStopped();
+    // Unregister 对不存在的任务抛 terminating error，try/catch 视为已卸载。
+    await this.powershell(
+      "try { Unregister-ScheduledTask -TaskName '" + WINDOWS_SERVICE_TASK_NAME + "' -Confirm:$false -ErrorAction Stop } catch { }",
+    );
+    if (paths?.serviceRuntimeConfigPath) {
+      await this.fileSystem.unlink(paths.serviceRuntimeConfigPath).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+      await this.fileSystem.unlink(paths.serviceRuntimeConfigPath + ".installing").catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    }
+    await this.fileSystem.rm(paths.serviceDir, { recursive: true, force: true });
+  }
+
+  async listCodexProcesses() {
+    const installation = await this.codex();
+    const stdout = await this.powershell([
+      "$procs = Get-CimInstance Win32_Process -Filter \"Name='ChatGPT.exe'\" |",
+      "  Where-Object { $_.CommandLine } |",
+      "  ForEach-Object { [pscustomobject]@{ pid = $_.ProcessId; command = $_.CommandLine } };",
+      "ConvertTo-Json -Compress -InputObject @($procs)",
+    ].join("\n"));
+    let records;
+    try {
+      records = JSON.parse(String(stdout).trim() || "[]");
+    } catch {
+      records = [];
+    }
+    if (!Array.isArray(records)) records = [];
+    return records
+      .filter(({ command }) => isExactCodexProcessWindows(command, installation))
+      .map((processInfo) => ({
+        ...processInfo,
+        appPath: installation.appPath,
+        executable: installation.executable,
+        bundleIdentifier: installation.packageFamilyName ?? CODEX_WINDOWS_PACKAGE_FAMILY,
+        signingIdentity: installation.signerSubject ?? null,
+        verified: installation.verified !== false,
+      }));
+  }
+
+  async ownedCodexProcesses(paths) {
+    const processes = await this.listCodexProcesses();
+    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) {
+    const processes = await this.ownedCodexProcesses(paths);
+    if (processes.length) {
+      throw new Error(`MineCodex-owned Codex processes are still running: ${processes.map(({ pid }) => pid).join(", ")}`);
+    }
+  }
+
+  async snapshotNativeCodexState() {
+    const processes = (await this.listCodexProcesses()).filter(({ command }) => !command.includes("--user-data-dir="));
+    return { count: processes.length, processes };
+  }
+
+  async restoreNativeCodexState(snapshot) {
+    if (!snapshot?.count) return 0;
+    const current = (await this.listCodexProcesses()).filter(({ command }) => !command.includes("--user-data-dir="));
+    if (current.length) return current.length;
+    await this.openNativeCodex();
+    return snapshot.count;
+  }
+
+  async terminateOwnedCodex(paths) {
+    const processInfo = (await this.ownedCodexProcesses(paths))[0];
+    if (!processInfo) {
+      await this.assertOwnedCodexStopped(paths);
+      return false;
+    }
+    this.processApi.kill(processInfo.pid);
+    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(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 ownedProcessTree = await this.collectProcessTree(pid);
+    for (const treePid of ownedProcessTree) {
+      try {
+        this.processApi.kill(treePid);
+      } catch {
+        // 进程可能已自行退出，终止阶段容忍缺失。
+      }
+    }
+    await waitForProcessesExit(ownedProcessTree, { processApi: this.processApi, sleep: this.sleep });
+    return 1;
+  }
+
+  async collectProcessTree(rootPid) {
+    const stdout = await this.powershell([
+      "$procs = Get-CimInstance Win32_Process -Filter \"Name='ChatGPT.exe'\" |",
+      "  ForEach-Object { [pscustomobject]@{ pid = $_.ProcessId; ppid = $_.ParentProcessId } };",
+      "ConvertTo-Json -Compress -InputObject @($procs)",
+    ].join("\n"));
+    let records;
+    try {
+      records = JSON.parse(String(stdout).trim() || "[]");
+    } catch {
+      records = [];
+    }
+    if (!Array.isArray(records)) records = [];
+    const childrenByParent = new Map();
+    for (const { pid, ppid } of records) {
+      const children = childrenByParent.get(ppid) ?? [];
+      children.push(pid);
+      childrenByParent.set(ppid, children);
+    }
+    const descendants = [];
+    const pending = [...(childrenByParent.get(rootPid) ?? [])];
+    while (pending.length) {
+      const current = pending.shift();
+      descendants.push(current);
+      pending.push(...(childrenByParent.get(current) ?? []));
+    }
+    return [rootPid, ...descendants];
+  }
+
+  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.powershell([
+      "$owned = Get-NetTCPConnection -State Listen -LocalPort " + cdpPort + " -ErrorAction SilentlyContinue |",
+      "  Where-Object { $_.OwningProcess -eq " + processInfo.pid + " -and ($_.LocalAddress -eq '127.0.0.1' -or $_.LocalAddress -eq '::1') };",
+      "if ($owned) { Write-Output 'OWNED' } else { throw ('ChatGPT pid ' + " + processInfo.pid + " + ' does not own loopback CDP port " + cdpPort + ".') }",
+    ].join("\n"));
+    if (!String(stdout).includes("OWNED")) {
+      throw new Error(`ChatGPT pid ${processInfo.pid} does not own loopback CDP port ${cdpPort}.`);
+    }
+    return true;
+  }
+
+  async openBrowser(url) {
+    const safeUrl = String(url).replaceAll("'", "''");
+    await this.powershell("Start-Process -FilePath '" + safeUrl + "'");
+  }
+
+  async openNativeCodex({ cdpPort } = {}) {
+    const installation = await this.codex();
+    if (!Number.isInteger(cdpPort) || cdpPort <= 0 || cdpPort > 65_535) {
+      await this.powershell("Start-Process -FilePath '" + String(installation.executable).replaceAll("'", "''") + "'");
+      return null;
+    }
+    const existingPids = new Set((await this.listCodexProcesses()).map(({ pid }) => pid));
+    const safeExecutable = String(installation.executable).replaceAll("'", "''");
+    await this.powershell([
+      "Start-Process -FilePath '" + safeExecutable + "' -ArgumentList @(",
+      "  '--remote-debugging-address=127.0.0.1',",
+      "  '--remote-debugging-port=" + cdpPort + "',",
+      "  '--remote-allow-origins=http://127.0.0.1:" + cdpPort + "');",
+    ].join("\n"));
+    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(`Windows 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(`Windows did not expose a loopback CDP ChatGPT process on port ${cdpPort}.`);
+  }
+}
+
+export function createPlatformAdapter(options = {}) {
+  const platform = options.platform ?? process.platform;
+  if (platform === "win32") return new WindowsPlatformAdapter(options);
+  return new MacPlatformAdapter(options);
+}

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

@@ -190,7 +190,7 @@ export class RuntimeManager {
     const child = this.spawnProcess(process.execPath, [this.paths.runtimeEntry], {
       cwd: this.paths.packageRoot,
       env: runtimeEnvironment,
-      stdio: "inherit",
+      stdio: ["inherit", "inherit", "inherit", "ipc"],
     });
     this.child = child;
     if (hasExited(child)) {
@@ -479,7 +479,14 @@ export class RuntimeManager {
     child.once("exit", onExit);
     try {
       try {
-        child.kill(signal);
+        // Windows 的 SIGTERM 会强杀；先请求宿主清理插件子进程。
+        if (signal === "SIGTERM" && child.connected && typeof child.send === "function") {
+          child.send({ type: "minecodex:shutdown" }, (error) => {
+            if (error && !hasExited(child)) this.logger.warn?.("Runtime shutdown request failed", error.message);
+          });
+        } else {
+          child.kill(signal);
+        }
       } catch (error) {
         if (error?.code === "ESRCH") return true;
         throw error;

package/packages/runtime-host/README.md

@@ -132,8 +132,8 @@ Host 会再次发送当前状态。功能页面可据此暂停隐藏状态下的
 - `attach-file`：用 CDP 填充临时 file input，再把真实 `File` drop 给 Composer；只有
   观察到原生附件 chip/preview 才报告 `attach`，否则明确返回 `insert-path`。
 - `open-detail-tab`：动态发现当前 Codex React right-panel controller 与当前 Task scope，
-  用稳定的 `featureId-detailId` 聚焦或创建唯一原生 Tab；capability 不可用时才回退到
-  RuntimeHost 自建的兼容 Tab host。
+  传入包含 `Component`、`isAvailable`、`kind` 和 `dropDestinations` 的标签描述对象，
+  用稳定的 `featureId-detailId` 聚焦或创建唯一原生 Tab；capability 不可用时返回明确错误。
 - `resolve-file-paths`：通过 Codex preload 暴露的 Electron file bridge 解析 Finder
   drop 的真实 `File` 对象。
 
@@ -145,6 +145,8 @@ Host 会再次发送当前状态。功能页面可据此暂停隐藏状态下的
   本地 Surface 不直接导航到 loopback URL：Host 先创建 `about:blank` iframe，再校验
   manifest URL、health service/protocol/instance，抓取 HTML 并用 `Page.setDocumentContent`
   写入目标 frame。Images/Notes 只向精确的 `app://-` Origin 开放 CORS。
+- CDP 重连时同步轮换后的 binding token；保留已就绪的 Surface 和编辑草稿，
+  使用新 token 重试未就绪页面，避免弹窗停留在空白 iframe。
 - 入口由 Renderer 内的 MutationObserver 幂等挂载，React 重绘不会产生重复入口。
 - Summary 根据对话主区域宽度连续派生 `overlay / shift / gutter`：小于 1096px
   使用临时 Popover；1096–1535px 预留 316px 并把对话内容左移 158px；更宽时
@@ -166,7 +168,7 @@ Host 会再次发送当前状态。功能页面可据此暂停隐藏状态下的
 | --- | --- | --- |
 | loopback HTTP、manifest、Surface message schema | 项目自有稳定接口 | 可由测试直接覆盖 |
 | `window.electronBridge.getPathForFile` | 当前稳定 internal/preload | 仅用于 Finder `File` 路径解析 |
-| React right-panel `openTab`、Task scope、JSX runtime | private internal capability | 动态发现 bundle 并做能力检测；失败时回退自建 Tab host |
+| React right-panel `openTab`、Task scope、JSX runtime | private internal capability | 动态发现 bundle 并做能力检测；失败时返回明确的不可用错误 |
 | toolbar、summary、tabs、Composer selectors | DOM inference | 统一留在本 Adapter |
 | `Runtime.addBinding`、`DOM.setFileInputFiles`、注入脚本 | high-risk CDP | 必须使用隔离 profile 验收 |
 | `togglePinnedSummary`、`composer.addFiles` 字符串 | 探索证据 | 当前实现不把它们当契约 |