codex-control-chrome-mcp 1.3.3 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ This project follows semantic versioning.
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-07-04
+
+### Changed
+
+- The debugger attach lifecycle now mirrors the official Codex `browser-client.mjs` discipline instead of trusting the extension's idempotent `attach`. A new `ensureAttached` attaches and then issues `Target.setAutoAttach` (`autoAttach`/`flatten`), which keeps child frames/OOPIFs in the session and doubles as a real liveness probe; `withSession` wraps every CDP tool (`chrome_navigate`/`chrome_evaluate`/`chrome_screenshot`/`chrome_cdp_send`) so a stale or lost attachment — whether it surfaces at the probe or mid-command — is healed once via `detach` → re-attach → retry. `chrome_attach_tab` now verifies the attachment with a probe and reports the real result instead of a hardcoded `{ok:true}`. This supersedes the narrower per-tool self-heal added in 1.3.1/1.3.3.
+- `turn_id` is now stable for the lifetime of the MCP process instead of freshly minted on every request. The extension scopes attach/lease state by `session_id` + `turn_id` (`resolveSession(t).attach(requireTurnId(t))`), so a churning turn re-keyed leases and reset session state on every call. One controller uses one stable turn, matching the official client's turn model.
+
+### Added
+
+- `scripts/concurrency-check.mjs`: a concurrency soak harness that runs N real client sessions against the live bridge and reports unrecovered "not attached" failures (the regression signal) and how many self-heals engaged.
+- [`docs/troubleshooting.md`](docs/troubleshooting.md): a debugging playbook and the reference points (official `browser-client.mjs`, the extension service worker's `se`/attach internals) for future debugger/attach investigations. `docs/architecture.md` gained a "Debugger Attach Lifecycle" section.
+
 ## [1.3.3] - 2026-07-04
 
 ### Fixed

package/README.md

@@ -120,6 +120,7 @@ Because the control entrypoint is inside the normal Chrome profile, existing coo
 Read more:
 
 - [Architecture](./docs/architecture.md)
+- [Troubleshooting & Debugging Playbook](./docs/troubleshooting.md)
 - [Install And Uninstall](./docs/install.md)
 - [Official Socket Probe Notes](./docs/socket-probe.md)
 - [Release Process](./docs/release.md)
@@ -166,6 +167,16 @@ npx -y codex-control-chrome-mcp@latest uninstall-native-host
 
 If tab or CDP tools fail, use the bundled skill workflow: list tabs again, claim only current tab IDs, attach before raw CDP calls, and read CDP events after enabling the relevant domain.
 
+### "Debugger is not attached" / flaky CDP under concurrency
+
+CDP tools self-heal a stale debugger attachment since 1.4.0 (attach is verified,
+and a lost attachment is recovered with `detach` → re-attach → retry). If you
+still see attach flakiness — most likely when several browser-control stacks
+share one Chrome and contend for the single debugger per tab — see the
+[Troubleshooting & Debugging Playbook](./docs/troubleshooting.md) for the root
+cause, reference points (official client, extension service worker), and the
+`scripts/concurrency-check.mjs` soak test.
+
 See [Install And Uninstall](./docs/install.md#troubleshooting) for the full per-browser checklist (the `registered` flag and host `classification`).
 
 ## License

package/docs/architecture.md

@@ -170,6 +170,33 @@ CDP events come back as notifications:
 }
 ```
 
+## Debugger Attach Lifecycle
+
+The extension's `attach` is idempotent on an in-memory set (`background.js`:
+`if(!se.has(t)) chrome.debugger.attach(...)`). If a tab's real debugger is torn
+down out-of-band (a competing debugger client, DevTools, a renderer/process
+swap) and that flag goes stale, `attach` reports success without re-attaching and
+the next CDP command fails with `Debugger is not attached`.
+
+Since 1.4.0 the client mirrors the official `browser-client.mjs` discipline
+instead of trusting that `attach`:
+
+- `ensureAttached(tabId)` — `attach`, then `Target.setAutoAttach`
+  (`autoAttach`/`flatten`), which keeps child frames/OOPIFs in the session and
+  doubles as a real liveness probe that surfaces a stale attach.
+- `withSession(tabId, run)` — `ensureAttached` → run the CDP sequence → on
+  "not attached" (from the probe or mid-command) `detach` (clears the stale
+  flag) → re-`ensureAttached` → retry once. Every CDP tool
+  (`chrome_navigate`/`evaluate`/`screenshot`/`cdp_send`) goes through it, and
+  `chrome_attach_tab` verifies with a probe instead of returning a hardcoded ok.
+- A **stable per-process `turn_id`**. The extension scopes attach/lease state by
+  `session_id` + `turn_id` (`resolveSession(t).attach(requireTurnId(t))`);
+  minting a fresh turn per request churned that state.
+
+When a debugger/attach issue recurs, start from
+[`docs/troubleshooting.md`](./troubleshooting.md) — it has the reference points
+(official client, extension service worker) and the debugging playbook.
+
 ## Reusing Codex Logic
 
 The preferred long-term reuse point is Codex's `browser-client.mjs`, not the official `extension-host` socket.
@@ -187,7 +214,17 @@ globalThis.nodeRepl.setResponseMeta()
 
 This project can shim those APIs and point `nativePipe.createConnection()` at its own bridge socket. That lets the vendored `browser-client.mjs` reuse its existing high-level browser logic while avoiding Codex App as a dependency.
 
-The initial implementation exposes direct MCP tools first. Vendoring `browser-client.mjs` should be a later phase after the native host bridge is stable.
+The initial implementation exposes direct MCP tools first.
+
+As of 1.4.0 we chose to **align the lifecycle discipline in our own small client**
+(see "Debugger Attach Lifecycle" above) rather than vendor `browser-client.mjs`.
+Vendoring the 983 KB minified bundle into this MIT-licensed, published package
+would redistribute OpenAI's proprietary code (a licensing question), couple us to
+a specific Codex build, and add an opaque, unreviewable dependency. Re-implementing
+the key mechanisms (`ensureAttached`, `Target.setAutoAttach`, stable turn,
+verified attach, self-heal) gets the same behavior while staying MIT-clean and
+reviewable. Full vendoring remains an option only if the redistribution question
+is resolved.
 
 ## Runtime And Launch Model
 

package/docs/troubleshooting.md

@@ -0,0 +1,109 @@
+# Troubleshooting & Debugging Playbook
+
+Where to look when something breaks and the fix isn't obvious — especially
+around the Chrome debugger attach lifecycle, which is the trickiest part of this
+project because we drive `chrome.debugger` **through** the Codex extension rather
+than owning it.
+
+## Reference points (read these first)
+
+When a debugger/CDP behavior is confusing, the ground truth lives in three
+places, none of which are this repo's tool layer:
+
+1. **The official Codex browser client** —
+   `~/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs`
+   (minified). This is how Codex App itself drives the browser. It is the
+   reference implementation we align to. Grep it for the lifecycle discipline:
+   `ensureAttached`, `Target.setAutoAttach`, `runAttachedFrameSessionInitialization`,
+   `preserveDebuggerOnTimeout`, `Target.closeTarget`. Its only export is
+   `setupBrowserRuntime`; it expects a `globalThis.nodeRepl` runtime
+   (`nativePipe.createConnection`, `requestMeta["x-codex-turn-metadata"]`, `env`,
+   `cwd`, `config`, `emitImage`, `setResponseMeta`).
+2. **The extension service worker** —
+   `~/Library/Application Support/Google/Chrome/Default/Extensions/hehggadaopoacecdllhhajmbjkdcmajg/<version>/background.js`
+   (minified). This is what actually calls `chrome.debugger.*`. Key internals:
+   - `function cn(t){ ... if(!se.has(t)){ chrome.debugger.attach({tabId:t},"1.3") } }`
+     — `attach` is **idempotent on the in-memory `se` map**. If `se` still has a
+     tab whose real debugger was torn down out-of-band, `attach` reports success
+     without re-attaching. That stale flag is the root of "Debugger is not
+     attached".
+   - `chrome.debugger.onDetach.addListener(t=>{ se.delete(t.tabId) })` — clears
+     `se` on detach, but can miss races / certain eviction types, leaving `se`
+     stale.
+   - `resolveSession(t).attach(requireTurnId(t), t)` — attach/lease state is
+     scoped by `session_id` + `turn_id`; leases are `{sessionId, turnId, instanceId}`.
+     This is why a churning `turn_id` destabilizes session state (see below).
+3. **This repo's design** — [`docs/architecture.md`](./architecture.md), especially
+   "Coexistence With Codex App" (the same-name proxy) and "Reusing Codex Logic".
+
+## The "Debugger is not attached" failure (root cause)
+
+Three layers stack up:
+
+1. **Trigger (environment):** a tab's `chrome.debugger` is torn down by a
+   competing debugger client (another session, DevTools, a renderer/process
+   swap). Only one debugger client is allowed per tab. Running multiple
+   browser-control stacks (Codex App + several MCP sessions + Claude's extension)
+   makes this common.
+2. **Extension bug:** after that teardown, `se` can stay stale, so `attach`
+   lies (`if(!se.has(t))` short-circuit) and the next `sendCommand` throws
+   `Debugger is not attached`. A `detach` clears the flag (it may itself throw
+   "not attached" — expected), after which `attach` re-attaches for real.
+3. **Our client:** the pre-1.4.0 client fired `attach` and trusted the `{ok}`,
+   with no verification and no recovery, so a recoverable state became a dead
+   end.
+
+The 1.4.0 client mirrors the official lifecycle discipline: `ensureAttached`
+(attach + `Target.setAutoAttach`, which doubles as a real liveness probe),
+`withSession` (ensure → run → on "not attached" `detach` → re-`ensureAttached` →
+retry once), verified `chrome_attach_tab` (no more hardcoded `{ok:true}`), and a
+**stable per-process `turn_id`** instead of a fresh one per request. See
+`src/mcp-server.js` (`ensureAttached` / `withSession`) and `test/mcp-server.test.js`.
+
+## Debugging playbook
+
+Techniques that isolated the bug, roughly in order:
+
+- **Is it concurrency?** `chrome_bridge_status` → `clients` is the number of MCP
+  sessions sharing the native host. `proxy: true` means Codex App is proxied
+  through us too.
+- **Which stacks are running?** `ps aux | grep -iE "codex|native-host"` — look
+  for multiple `codex-control-chrome-mcp` instances (global vs `_npx` cache),
+  the official `Codex for Chrome` host, and Claude's extension host.
+- **Tab-specific or global?** Open a **fresh** tab and try it. If the new tab
+  works but the old one doesn't, the old tab's attach state is corrupted (stale
+  `se`), not the whole extension.
+- **Manual recovery / confirm the mechanism:** on a wedged tab, `chrome_detach_tab`
+  (it will error with "not attached" — that's expected and clears the stale flag),
+  then `chrome_attach_tab`, then retry. If that revives it, it's the stale-attach bug.
+- **What did the page/debugger do?** `chrome_read_events` dumps buffered CDP
+  notifications (Page/Runtime lifecycle). Note: events are **broadcast to all MCP
+  clients**, so under concurrency you will see other sessions' tabs too. Large
+  dumps are written to a file — analyze with `jq '.events[].params.method'`.
+- **Extension-side detach reasons** are NOT on disk: `chrome.debugger.onDetach`
+  is a callback, not a CDP event, so `Inspector.detached` won't appear in
+  `chrome_read_events`. To see it you'd need the extension service worker console.
+- **Codex App logs:** `~/Library/Logs/com.openai.codex/<date>/codex-desktop-*.log`.
+- **Concurrency soak:** `node scripts/concurrency-check.mjs [sessions] [rounds]`
+  runs N real sessions concurrently through the create → navigate → raw
+  `cdp_send` → evaluate → finalize flow and reports unrecovered "not attached"
+  (must be 0) plus how many self-heals engaged.
+
+## Known limitations
+
+- **Session isolation holds, the debugger is shared.** Concurrent sessions can't
+  see or close each other's tabs (leases are per `session_id`), but they contend
+  for the one debugger-per-tab, so contention raises the eviction rate. The
+  self-heal recovers one-shot commands; it does not remove the contention.
+- **Streaming CDP is fragile under contention.** Flows that need the debugger to
+  stay attached over time (e.g. `Network.enable` then reading events) can lose
+  the attachment mid-stream. Prefer page-side APIs (Resource Timing /
+  `PerformanceObserver` via `chrome_evaluate`) for network/DOM observation.
+- **Live tools run the installed package, not this repo.** Editing `src/` does
+  nothing until `npm i -g codex-control-chrome-mcp@<version>` **and** the MCP
+  client restarts (and the extension reconnects). Beware stale `_npx` copies.
+
+## Runtime/release gotchas
+
+See [`docs/release.md`](./release.md). Publishing is `git push` of a `v*` tag →
+`.github/workflows/publish.yml` publishes to npm via OIDC (no local `npm login`).

package/package.json

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

package/src/mcp-server.js

@@ -60,9 +60,14 @@ function browserLabel(browser) {
   return browser === "edge" ? "Edge" : "Chrome";
 }
 
-class ChromeUseRuntime {
+export class ChromeUseRuntime {
   constructor() {
     this.sessionId = `codex-control-chrome-mcp-${crypto.randomUUID()}`;
+    // Stable per-process turn id. The Codex extension scopes attach/lease state
+    // by (session_id, turn_id); minting a fresh turn per request (as we used to)
+    // churned that state and re-keyed tab leases on every call. We are a single
+    // controller, so one stable turn mirrors the official client's turn model.
+    this.turnId = `turn-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
     this.bridge = null;
   }
 
@@ -76,7 +81,7 @@ class ChromeUseRuntime {
   sessionParams() {
     return {
       session_id: this.sessionId,
-      turn_id: `turn-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`,
+      turn_id: this.turnId,
       session_context: "codex-control-chrome-mcp",
     };
   }
@@ -187,7 +192,16 @@ export function registerTools(server, runtime) {
       },
     },
     async ({ tabId }) => {
-      await runtime.request("attach", { tabId });
+      // Verify the attachment for real instead of trusting the extension's
+      // idempotent `attach` (which can report success on a stale flag). The
+      // probe runs a trivial evaluate; withSession heals a stale attach first.
+      await withSession(runtime, tabId, () =>
+        executeCdp(runtime, {
+          tabId,
+          method: "Runtime.evaluate",
+          params: { expression: "1", returnByValue: true },
+        }),
+      );
       return toolResult({ ok: true });
     },
   );
@@ -218,7 +232,7 @@ export function registerTools(server, runtime) {
       },
     },
     async ({ tabId, method, params, timeoutMs }) =>
-      toolResult(await withReattach(runtime, tabId, () =>
+      toolResult(await withSession(runtime, tabId, () =>
         executeCdp(runtime, { tabId, method, params, timeoutMs }),
       )),
   );
@@ -233,7 +247,7 @@ export function registerTools(server, runtime) {
       },
     },
     async ({ tabId, url }) =>
-      toolResult(await withReattach(runtime, tabId, async () => {
+      toolResult(await withSession(runtime, tabId, async () => {
         await executeCdp(runtime, { tabId, method: "Page.enable", params: {} });
         return await executeCdp(runtime, {
           tabId,
@@ -254,7 +268,7 @@ export function registerTools(server, runtime) {
       },
     },
     async ({ tabId, expression, awaitPromise }) =>
-      toolResult(await withReattach(runtime, tabId, async () => {
+      toolResult(await withSession(runtime, tabId, async () => {
         await executeCdp(runtime, { tabId, method: "Runtime.enable", params: {} });
         return await executeCdp(runtime, {
           tabId,
@@ -278,7 +292,7 @@ export function registerTools(server, runtime) {
       },
     },
     async ({ tabId, format }) =>
-      toolResult(await withReattach(runtime, tabId, async () => {
+      toolResult(await withSession(runtime, tabId, async () => {
         await executeCdp(runtime, { tabId, method: "Page.enable", params: {} });
         return await executeCdp(runtime, {
           tabId,
@@ -323,30 +337,66 @@ export function registerTools(server, runtime) {
 }
 
 /**
- * Attach the debugger, run a CDP sequence, and self-heal a stale-attach state.
- *
- * The Codex Chrome extension tracks debugger attachments in memory. When Chrome
- * tears an attachment down out-of-band (a competing debugger client, DevTools, a
- * renderer/process swap), that flag can go stale: a fresh `attach` short-circuits
- * and reports success without actually re-attaching, so the next CDP command
- * fails with "Debugger is not attached". A `detach` clears the stale flag (it may
- * itself throw "not attached" — expected, and ignored), after which `attach`
- * re-attaches for real. We retry the sequence once on that specific error.
+ * Bring `tabId` to a known-attached state, mirroring the official Codex
+ * browser-client's discipline instead of trusting the extension's idempotent
+ * `attach`. The extension only calls `chrome.debugger.attach` when the tab is
+ * absent from its in-memory set (background.js: `if(!se.has(t)) attach()`), so
+ * after an out-of-band detach that flag can go stale and `attach` reports
+ * success with no live debugger. `Target.setAutoAttach` is a real CDP command:
+ * it keeps child frames/OOPIFs in the session (as the official client does) and
+ * doubles as a liveness probe that surfaces a stale attach as "not attached".
  */
-export async function withReattach(runtime, tabId, run) {
+async function ensureAttached(runtime, tabId) {
   await runtime.request("attach", { tabId });
   try {
+    await executeCdp(runtime, {
+      tabId,
+      method: "Target.setAutoAttach",
+      params: { autoAttach: true, flatten: true, waitForDebuggerOnStart: false },
+    });
+  } catch (error) {
+    // A stale attach surfaces here as "not attached"; re-throw so withSession
+    // heals it. Any other setAutoAttach failure is best-effort (some targets
+    // reject it) and must not block the real command.
+    if (isNotAttachedError(error)) throw error;
+  }
+}
+
+/**
+ * Ensure the tab is attached, run a CDP sequence, and self-heal once if the
+ * debugger is torn down out-of-band (a competing debugger client, DevTools, or a
+ * renderer/process swap) — whether that surfaces during the attach probe or
+ * mid-command. Recovery is a `detach`, which clears the extension's stale attach
+ * flag (it may itself throw "not attached" — expected, and ignored), then a real
+ * re-attach via ensureAttached, then one retry.
+ */
+/**
+ * Diagnostics for the self-heal path: `heals` counts how often a stale/lost
+ * attachment was recovered, `unrecovered` how often recovery still failed.
+ * Used by scripts/concurrency-check.mjs to observe behavior under contention.
+ */
+export const sessionStats = { heals: 0, unrecovered: 0 };
+
+export async function withSession(runtime, tabId, run) {
+  try {
+    await ensureAttached(runtime, tabId);
     return await run();
   } catch (error) {
     if (!isNotAttachedError(error)) throw error;
+    sessionStats.heals += 1;
     try {
       await runtime.request("detach", { tabId });
     } catch {
       // Detach throws when the debugger is already gone; we only need its side
       // effect of clearing the extension's stale attach flag.
     }
-    await runtime.request("attach", { tabId });
-    return await run();
+    try {
+      await ensureAttached(runtime, tabId);
+      return await run();
+    } catch (retryError) {
+      if (isNotAttachedError(retryError)) sessionStats.unrecovered += 1;
+      throw retryError;
+    }
   }
 }