codex-control-chrome-mcp 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ This project follows semantic versioning.
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-06-27
+
+### Added
+
+- Self-healing native host registration: the MCP stdio server re-asserts the manifest on startup when a Codex update reverts it (opt out with `CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1`).
+- Robust identification of OpenAI's genuine host via stable signals (manifest name + extension origin, bundle path, binary format, and the macOS OpenAI code signature) instead of the binary filename.
+- `status` now reports `registered` and a `classification` of the live manifest/host.
+
+### Fixed
+
+- Proxy target resolution preferred a stale recorded path over the live manifest, so a renamed/removed official host (e.g. `extension-host` → `Codex for Chrome`) could be recorded as the proxy target. It now prefers the live official manifest and skips paths that no longer exist.
+
 ## [1.0.1] - 2026-06-26
 
 ### Added

package/README.md

@@ -144,6 +144,14 @@ node ./bin/codex-control-chrome-mcp.js --native-host
 
 ## Troubleshooting
 
+`status` reports a `registered` flag and a `classification` of the live manifest. When `registered` is `false` and `classification.kind` is `official-openai`, a Codex update has reclaimed the manifest (see below). `classification` identifies OpenAI's genuine host by stable signals — the `com.openai.codexextension` name, the official extension origin, the bundle path, the binary format, and (on macOS) the OpenAI code signature — not by filename.
+
+### A Codex update stopped the bridge
+
+Codex App/extension updates re-register their own `com.openai.codexextension` native-messaging manifest, which overwrites this project's proxy registration (the bundled host binary has even been renamed across releases). The symptom is `status` showing `sockets: []`, `registered: false`, and a manifest `path` back inside the Codex bundle.
+
+The MCP stdio server now **self-heals**: on startup it re-asserts the manifest when it detects it was reverted, so you usually do not need to re-run `install-native-host`. Because Chrome only reads the manifest when the extension reconnects, **reload the Codex Chrome Extension (or restart Chrome) once** after a Codex update to bring the bridge back. Set `CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1` to disable the auto re-register.
+
 If `status` shows no bridge sockets, reload Chrome or the Codex Chrome Extension after installing the native host.
 
 If Codex App integration stops working, uninstall this native host to restore the backed-up manifest:

package/docs/install.md

@@ -53,7 +53,22 @@ The installer:
 2. Backs it up in the same directory with a timestamped suffix.
 3. Writes a new manifest pointing to this project's CLI.
 4. Records restore metadata in `~/.codex-control-chrome-mcp/install-state.json`.
-5. Records the previous host path for proxy mode when available.
+5. Records the genuine OpenAI host path for proxy mode when available.
+
+### Identifying the official host
+
+The installer identifies OpenAI's genuine host with stable signals instead of the
+binary filename (OpenAI has renamed it across releases, e.g. `extension-host` →
+`Codex for Chrome`):
+
+- the manifest `name` (`com.openai.codexextension`) and the official extension origin,
+- the bundle directory structure (`.../openai-bundled/.../extension-host/...`),
+- the binary format (a compiled Mach-O/ELF executable, not a shell script),
+- on macOS, the OpenAI code signature (Developer ID Team `2DC432GLL2`).
+
+When choosing the proxy target it prefers the **live** manifest (most up to date) and
+skips paths that no longer exist, so a renamed or removed host is never recorded as the
+official target. `status` reports these signals under `classification`.
 
 Example manifest path on macOS:
 
@@ -129,6 +144,16 @@ This prints:
 
 Chrome launches the native host only when the extension connects. If no bridge socket is visible, reload Chrome or the Codex extension after installing the manifest.
 
+### Auto re-register after Codex updates
+
+A Codex App/extension update re-registers its own `com.openai.codexextension` manifest and reverts this project's proxy registration. To avoid a manual repair each time, the MCP stdio server re-asserts the manifest on startup when it detects it was reverted (only if it was installed before — it never bootstraps a fresh install silently). Logs go to stderr only.
+
+Re-asserting the manifest takes effect on the extension's **next** Native Messaging connection, so reload the Codex Chrome Extension or restart Chrome once after a Codex update. Disable this behavior with:
+
+```bash
+CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1
+```
+
 If the extension is missing, install the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) from Chrome Web Store and enable it in the target Chrome profile.
 
 Stopping the MCP stdio process does not uninstall the native host. Uninstall explicitly to restore the original manifest.
@@ -142,7 +167,8 @@ If `status` shows no sockets:
 1. Confirm Chrome is running with the profile where the extension is installed.
 2. Reload or disable/enable the Codex Chrome Extension.
 3. Run `npx -y codex-control-chrome-mcp@latest status`.
-4. Check that the active manifest path points to `~/.codex-control-chrome-mcp/native-host-launcher`.
+4. Check `registered`. If it is `false` and `classification.kind` is `official-openai`, a Codex update reclaimed the manifest. The stdio server re-asserts it on next startup; reload the extension or restart Chrome to reconnect (or run `install-native-host` to repair immediately).
+5. When `registered` is `true`, the active manifest points to `~/.codex-control-chrome-mcp/native-host-launcher` (or your local launcher) and the extension just needs to connect.
 
 If Codex App integration is affected, uninstall this project:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-control-chrome-mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "MCP server and native host bridge for controlling Chrome through the Codex Chrome extension.",
   "license": "MIT",
   "type": "module",

package/src/host-identity.js

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { APP_STATE_DIR, CODEX_EXTENSION_ID, CODEX_NATIVE_HOST_NAME } from "./constants.js";
+
+// Description we stamp on manifests we own. Used as one (not the only) signal.
+export const MANIFEST_DESCRIPTION = "Codex Control Chrome MCP native messaging host";
+
+/** A manifest this project wrote (description marker, or path inside our state dir). */
+export function isProjectManifest(manifest) {
+  if (!manifest || typeof manifest !== "object") return false;
+  if (manifest.description === MANIFEST_DESCRIPTION) return true;
+  return isOurLauncherPath(manifest.path);
+}
+
+/** True when a host path points at a launcher we generated under APP_STATE_DIR. */
+export function isOurLauncherPath(hostPath) {
+  if (typeof hostPath !== "string" || hostPath.length === 0) return false;
+  const resolved = path.resolve(hostPath);
+  const stateRoot = path.resolve(APP_STATE_DIR) + path.sep;
+  return resolved === path.resolve(APP_STATE_DIR) || resolved.startsWith(stateRoot);
+}
+
+/**
+ * Positive identification of OpenAI's genuine Codex native-host *manifest*,
+ * using stable identifiers (host name + the official extension id) rather than
+ * the binary filename (which OpenAI has renamed across releases).
+ */
+export function isOfficialCodexManifest(manifest) {
+  if (!manifest || typeof manifest !== "object") return false;
+  if (isProjectManifest(manifest)) return false;
+  if (manifest.name !== CODEX_NATIVE_HOST_NAME) return false;
+  const origins = Array.isArray(manifest.allowed_origins) ? manifest.allowed_origins : [];
+  return origins.some((origin) => originMatchesCodexExtension(origin));
+}
+
+function originMatchesCodexExtension(origin) {
+  return typeof origin === "string" && origin.includes(`chrome-extension://${CODEX_EXTENSION_ID}`);
+}
+
+/** Stable directory-structure signature of the bundled Codex host (filename-agnostic). */
+export function hostPathLooksOfficial(hostPath) {
+  if (typeof hostPath !== "string" || hostPath.length === 0) return false;
+  const normalized = path.resolve(hostPath).split(path.sep).join("/").toLowerCase();
+  return normalized.includes("/openai-bundled/") && normalized.includes("/extension-host/");
+}
+
+const MAGIC = {
+  "7f454c46": "elf", // ELF
+  feedface: "macho", // Mach-O 32 LE
+  feedfacf: "macho", // Mach-O 64 LE
+  cefaedfe: "macho", // Mach-O 32 BE
+  cffaedfe: "macho", // Mach-O 64 BE
+  cafebabe: "macho", // universal (fat) — also Java .class, acceptable for a host binary
+  bebafeca: "macho",
+};
+
+/** Inspect the host file: does it exist, is it a compiled binary or a shell script? */
+export async function inspectHostBinary(hostPath) {
+  if (typeof hostPath !== "string" || hostPath.length === 0) {
+    return { exists: false, kind: "missing", executable: false };
+  }
+  let handle;
+  try {
+    const stat = await fs.stat(hostPath);
+    if (!stat.isFile()) return { exists: true, kind: "unknown", executable: false };
+    handle = await fs.open(hostPath, "r");
+    const buf = Buffer.alloc(4);
+    const { bytesRead } = await handle.read(buf, 0, 4, 0);
+    const head = buf.subarray(0, bytesRead);
+    let kind = "unknown";
+    if (head.length >= 2 && head[0] === 0x23 && head[1] === 0x21) kind = "script"; // #!
+    else if (head.length === 4 && MAGIC[head.toString("hex")]) kind = MAGIC[head.toString("hex")];
+    else if (head.length >= 2 && head[0] === 0x4d && head[1] === 0x5a) kind = "pe"; // MZ
+    return { exists: true, kind, executable: (stat.mode & 0o111) !== 0 };
+  } catch {
+    return { exists: false, kind: "missing", executable: false };
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+/** Best-effort macOS code-signature check; the strongest OpenAI signal when available. */
+export function verifyOpenAiCodesign(hostPath) {
+  if (process.platform !== "darwin" || typeof hostPath !== "string" || !hostPath) {
+    return Promise.resolve({ available: false });
+  }
+  return new Promise((resolve) => {
+    execFile("codesign", ["-dvvv", hostPath], { timeout: 4000 }, (error, stdout, stderr) => {
+      const out = `${stdout || ""}${stderr || ""}`; // codesign -d writes to stderr
+      if (!out) return resolve({ available: false, error: error?.message });
+      const teamId = (out.match(/TeamIdentifier=(\S+)/) || [])[1] || null;
+      const authority = (out.match(/Authority=([^\r\n]+)/) || [])[1] || null;
+      const openai = /openai/i.test(out);
+      resolve({ available: true, signed: Boolean(authority), openai, teamId, authority });
+    });
+  });
+}
+
+/**
+ * Full classification of a (manifest, hostPath) pair against stable signals.
+ * `trustedOfficial` means: looks like OpenAI's real host and is safe to back up /
+ * proxy to. We require the manifest-level identity plus at least one host-level
+ * signal (bundle path, compiled binary, or an OpenAI code signature).
+ */
+export async function classifyHost({ manifest, hostPath } = {}) {
+  const resolvedPath = hostPath ?? manifest?.path ?? null;
+  const ours = isProjectManifest(manifest) || isOurLauncherPath(resolvedPath);
+  const officialManifest = isOfficialCodexManifest(manifest);
+  const pathOfficial = hostPathLooksOfficial(resolvedPath);
+  const binary = await inspectHostBinary(resolvedPath);
+  const codesign = await verifyOpenAiCodesign(resolvedPath);
+
+  const hostSignal = pathOfficial || codesign.openai === true || binary.kind === "macho" || binary.kind === "elf";
+  const trustedOfficial = !ours && officialManifest && hostSignal;
+
+  return {
+    ours,
+    officialManifest,
+    pathOfficial,
+    binary,
+    codesign,
+    trustedOfficial,
+    kind: ours ? "ours" : trustedOfficial ? "official-openai" : "unknown",
+  };
+}

package/src/installer.js

@@ -8,10 +8,16 @@ import {
   INSTALL_STATE_PATH,
   nativeHostManifestPath,
 } from "./constants.js";
+import {
+  MANIFEST_DESCRIPTION,
+  classifyHost,
+  inspectHostBinary,
+  isOfficialCodexManifest,
+  isOurLauncherPath,
+  isProjectManifest,
+} from "./host-identity.js";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 
-const MANIFEST_DESCRIPTION = "Codex Control Chrome MCP native messaging host";
-
 export async function installNativeHost({ binPath, proxy = true, paths = defaultInstallPaths() } = {}) {
   const { manifestPath, appStateDir, configPath, installStatePath } = paths;
   await fs.mkdir(path.dirname(manifestPath), { recursive: true });
@@ -34,23 +40,9 @@ export async function installNativeHost({ binPath, proxy = true, paths = default
     backupPath = previousState.backupPath;
   }
 
-  let officialHostPath = null;
-  if (proxy && previousBackup?.path && !previousBackupIsOurs) {
-    officialHostPath = previousBackup.path;
-  } else if (
-    proxy &&
-    typeof previousState?.officialHostPath === "string" &&
-    path.resolve(previousState.officialHostPath) !== path.resolve(hostPath)
-  ) {
-    officialHostPath = previousState.officialHostPath;
-  } else if (
-    proxy &&
-    existing?.path &&
-    !existingIsOurs &&
-    path.resolve(existing.path) !== path.resolve(hostPath)
-  ) {
-    officialHostPath = existing.path;
-  }
+  const officialHostPath = proxy
+    ? await resolveOfficialHostPath({ existing, existingIsOurs, previousState, previousBackup, hostPath })
+    : null;
 
   const manifest = {
     allowed_origins: [`chrome-extension://${CODEX_EXTENSION_ID}/`],
@@ -65,6 +57,7 @@ export async function installNativeHost({ binPath, proxy = true, paths = default
     installedAt: new Date().toISOString(),
     manifestPath,
     hostPath,
+    binPath: binPath ? path.resolve(binPath) : null,
     launchMode: binPath ? "direct-bin" : "npx-launcher",
     backupPath,
     officialHostPath,
@@ -75,6 +68,82 @@ export async function installNativeHost({ binPath, proxy = true, paths = default
   return config;
 }
 
+/**
+ * Resolve the genuine OpenAI host to proxy to. Authority order:
+ *   1. the live manifest, when it is verifiably OpenAI's (most up to date),
+ *   2. the previously recorded official host,
+ *   3. the backed-up manifest's path.
+ * Self-references and our own launcher are dropped, and a candidate whose file
+ * still exists is preferred so a renamed/removed host (e.g. after a Codex
+ * update) never gets recorded as the official target.
+ */
+async function resolveOfficialHostPath({ existing, existingIsOurs, previousState, previousBackup, hostPath }) {
+  const candidates = [];
+  if (existing?.path && !existingIsOurs && isOfficialCodexManifest(existing)) {
+    candidates.push(existing.path);
+  }
+  if (typeof previousState?.officialHostPath === "string") {
+    candidates.push(previousState.officialHostPath);
+  }
+  if (previousBackup?.path && !isProjectManifest(previousBackup)) {
+    candidates.push(previousBackup.path);
+  }
+
+  const seen = new Set();
+  const unique = [];
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    if (resolved === path.resolve(hostPath) || isOurLauncherPath(candidate) || seen.has(resolved)) {
+      continue;
+    }
+    seen.add(resolved);
+    unique.push(candidate);
+  }
+
+  for (const candidate of unique) {
+    if ((await inspectHostBinary(candidate)).exists) return candidate;
+  }
+  // None of the candidates exist on disk; fall back to the most authoritative
+  // one (the live official manifest) for diagnostics rather than inventing null.
+  return unique[0] ?? null;
+}
+
+/**
+ * Idempotently re-assert a previously-established install. Used on stdio
+ * startup so a Codex update that reclaims the manifest self-heals without a
+ * manual `install-native-host`. Never bootstraps a fresh install silently.
+ */
+export async function ensureNativeHostRegistered({ paths = defaultInstallPaths() } = {}) {
+  const { manifestPath, installStatePath } = paths;
+  const state = await readJsonIfExists(installStatePath);
+  if (!state || typeof state.hostPath !== "string") {
+    return { action: "skip", reason: "not-installed" };
+  }
+
+  const manifest = await readJsonIfExists(manifestPath);
+  const pointsToUs =
+    isProjectManifest(manifest) &&
+    typeof manifest?.path === "string" &&
+    path.resolve(manifest.path) === path.resolve(state.hostPath);
+  const launcherExists = (await inspectHostBinary(state.hostPath)).exists;
+  if (pointsToUs && launcherExists) {
+    return { action: "ok", reason: "already-registered" };
+  }
+
+  const result = await installNativeHost({
+    binPath: state.launchMode === "direct-bin" ? state.binPath ?? undefined : undefined,
+    proxy: state.proxy !== false,
+    paths,
+  });
+  return {
+    action: "re-registered",
+    reason: launcherExists ? "manifest-reverted" : "launcher-missing",
+    manifestPath,
+    hostPath: result.hostPath,
+    officialHostPath: result.officialHostPath,
+  };
+}
+
 export async function uninstallNativeHost({ force = false, paths = defaultInstallPaths() } = {}) {
   const { manifestPath, installStatePath } = paths;
   const state = await readJsonIfExists(installStatePath);
@@ -103,7 +172,13 @@ export async function nativeHostInstallStatus() {
   const { manifestPath, installStatePath } = defaultInstallPaths();
   const manifest = await readJsonIfExists(manifestPath);
   const state = await readJsonIfExists(installStatePath);
-  return { manifestPath, manifest, state };
+  const classification = await classifyHost({ manifest, hostPath: manifest?.path });
+  const registered =
+    isProjectManifest(manifest) &&
+    typeof state?.hostPath === "string" &&
+    typeof manifest?.path === "string" &&
+    path.resolve(manifest.path) === path.resolve(state.hostPath);
+  return { manifestPath, manifest, state, registered, classification };
 }
 
 function defaultInstallPaths() {
@@ -138,10 +213,6 @@ exec npx -y ${PACKAGE_NAME}@${PACKAGE_VERSION} --native-host "$@"
   return launcherPath;
 }
 
-function isProjectManifest(manifest) {
-  return manifest?.description === MANIFEST_DESCRIPTION;
-}
-
 async function createLocalLauncher(binPath, appStateDir) {
   if (process.platform === "win32") {
     return binPath;

package/src/mcp-server.js

@@ -4,9 +4,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { connectBridge, listBridgeSockets } from "./bridge-client.js";
 import { nativeHostManifestPath } from "./constants.js";
+import { ensureNativeHostRegistered } from "./installer.js";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 
 export async function runMcpServer() {
+  await autoRegisterNativeHost();
   const runtime = new ChromeUseRuntime();
   const server = new McpServer({
     name: PACKAGE_NAME,
@@ -19,6 +21,32 @@ export async function runMcpServer() {
   await server.connect(transport);
 }
 
+/**
+ * On stdio startup, re-assert our native-host manifest if a Codex update (or
+ * anything else) reverted it. Best-effort and silent: it only logs to stderr
+ * (stdout is the MCP JSON-RPC channel) and never blocks server startup.
+ * Opt out with CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1.
+ *
+ * Note: re-asserting the manifest only takes effect on the Chrome extension's
+ * next Native Messaging connection (reload the extension or restart Chrome).
+ */
+async function autoRegisterNativeHost() {
+  if (process.env.CODEX_CONTROL_CHROME_NO_AUTO_REGISTER === "1") return;
+  try {
+    const result = await ensureNativeHostRegistered();
+    if (result.action === "re-registered") {
+      process.stderr.write(
+        `[codex-control-chrome-mcp] native host manifest was ${result.reason}; re-registered it. ` +
+          "Reload the Codex Chrome extension (or restart Chrome) to reconnect the bridge.\n",
+      );
+    }
+  } catch (error) {
+    process.stderr.write(
+      `[codex-control-chrome-mcp] auto-register skipped: ${error?.message ?? error}\n`,
+    );
+  }
+}
+
 class ChromeUseRuntime {
   constructor() {
     this.sessionId = `codex-control-chrome-mcp-${crypto.randomUUID()}`;