Reliability session: stall detector, navigation diagnostics, tab isolation, recovery hook

.gitignore

@@ -14,3 +14,6 @@ sentinel_flow.json
 .rest-proxy.log
 .sse-server.log
 
+
+# ChatGPT collaboration binding (local only)
+.chatgpt-collaboration.json

docs/deployment.md

@@ -287,8 +287,49 @@ W2A_PARALLEL_TABS=1 chatgpt-web2api --port 8082 --cdp-port 9222
 
 > **Rollout warning:** do not mix old (port-lock-only) workers and new
 > (`parallel_tabs=true`) workers on the **same CDP port** during a rolling
-> upgrade — their lock files don't exclude each other. Finish the rollout on a
-> port before enabling parallel mode on it.
+> upgrade — their lock files don't exclude each other. Finish the rollout on
+> a port before enabling parallel mode on it.
+
+### Other CDP clients on the same Chrome (Super-Browser, Playwright, etc.)
+
+The bridge creates **owned tabs** (`tab_mode="owned"`, the default) — each
+driver gets its own dedicated tab via `Target.createTarget` and its own
+websocket. A `Page.navigate` issued by one CDP client goes over that client's
+websocket to that client's tab; it **cannot** navigate another client's tab.
+CDP targets are independent.
+
+However, running multiple CDP clients (e.g., 4 Super-Browser MCP servers + the
+bridge + the MCP server = 6+ clients) on one Chrome instance can still
+**degrade reliability** through resource contention:
+
+- **CPU/memory saturation** — each CDP client drives React hydration, DOM
+  polling, and JS evaluation. Under load, the Chrome renderer can slow
+  enough that ChatGPT's SPA fails to hydrate the composer within the
+  bridge's readiness window (see P2 staged readiness diagnostics).
+- **CDP HTTP endpoint queuing** — the `/json/list` and `/json/version`
+  endpoints are served by Chrome's DevTools HTTP server, which is
+  single-threaded. Many clients polling concurrently can introduce latency.
+- **Profile-level state** — all tabs share one Chrome profile (one account,
+  one cookie jar, one service worker). A service-worker update or auth
+  redirect on one tab can briefly affect the others.
+
+**What this means in practice:** the bridge's write path (navigate + send)
+is more sensitive to these effects than the read path (list/get
+conversations via `/backend-api/*`), because the write path requires
+DOM-level readiness (composer hydrated, send button enabled) while the read
+path is a pure HTTP fetch. If you observe "navigation timeout" or "no send
+button" errors that worsen as more clients connect, consider:
+
+1. Running the bridge on a **dedicated Chrome instance** (separate
+   `--user-data-dir` and `--cdp-port`).
+2. Reducing the number of concurrent CDP clients on the shared Chrome.
+3. Enabling `parallel_tabs: true` so the bridge and MCP server each get
+  their own tab (they do by default with `tab_mode="owned"`, but
+  `parallel_tabs` adds per-target locking and fail-closed semantics).
+
+The bridge's error messages now include staged diagnostics (P2) that name
+the failing readiness stage, making this degradation diagnosable rather
+than opaque.
 
 ---
 

scripts/ensure_hook.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+"""ZCode SessionStart hook wrapper for `chatgpt-web2api ensure`.
+
+Runs `chatgpt-web2api ensure` to reconcile the bridge (start REST + SSE if
+missing, verify health). ALWAYS exits 0 so a bridge failure never blocks the
+ZCode session — the bridge being down is an infrastructure problem, not a
+reason to prevent the user from working. Failures are logged to stderr where
+ZCode captures them in its hook execution log.
+
+Usage (from ZCode hooks.json):
+  command: python.exe
+  args: [path/to/ensure_hook.py, --rest-port, 8080, --mcp-sse-port, 8090]
+
+Exit codes:
+  0 — always (hook passes regardless of bridge state)
+  The bridge's actual state is logged to stderr for diagnosis.
+"""
+import subprocess
+import sys
+
+
+def main() -> None:
+    # Forward our args (minus the script name) to `chatgpt-web2api ensure`.
+    # The first arg is this script's path; the rest are ensure's flags.
+    ensure_args = sys.argv[1:]
+    cmd = [sys.executable, "-m", "chatgpt_web2api", "ensure"] + ensure_args
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=90,  # Chrome cold-start can take 10-15s; 90s is generous
+        )
+        # Log the output for ZCode's hook execution log.
+        if result.stdout:
+            print(result.stdout, file=sys.stderr)
+        if result.stderr:
+            print(result.stderr, file=sys.stderr)
+        if result.returncode != 0:
+            print(
+                f"ensure exited {result.returncode} — bridge may need manual "
+                f"attention (auth=2, failure=1). This does not block the session.",
+                file=sys.stderr,
+            )
+    except subprocess.TimeoutExpired:
+        print(
+            "ensure timed out after 90s — bridge may be slow to start. "
+            "This does not block the session.",
+            file=sys.stderr,
+        )
+    except Exception as e:
+        print(f"ensure hook error: {e}", file=sys.stderr)
+
+    # ALWAYS exit 0 — never block the ZCode session.
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

src/chatgpt_web2api/api_server.py

@@ -530,10 +530,16 @@ async def _full_response(
         transparently — the client only sees it (as a 429) if the limit
         persists across all retries.
         """
+        # P1: resolve model-aware detector budgets from config.
+        from .completion_detector import DetectorBudgets
+
+        budgets = DetectorBudgets.from_config(self._config.chatgpt, model)
 
         async def _send_and_collect() -> str:
             collected = ""
-            async for chunk in self._driver.send_and_stream(text, timeout=timeout):
+            async for chunk in self._driver.send_and_stream(
+                text, timeout=timeout, budgets=budgets, model=model,
+            ):
                 collected += chunk.delta
             return collected
 
@@ -577,6 +583,10 @@ async def _stream_response(
           cleared it), but if one occurs it falls back to the inline
           ``[Error: ...]`` SSE chunk — documented as a known limitation.
         """
+        # P1: resolve model-aware detector budgets from config.
+        from .completion_detector import DetectorBudgets
+
+        budgets = DetectorBudgets.from_config(self._config.chatgpt, model)
 
         async def _preflight() -> None:
             """Raise RateLimitError if the pop-up is present right now."""
@@ -638,7 +648,9 @@ async def _preflight() -> None:
         )
 
         try:
-            async for chunk in self._driver.send_and_stream(text, timeout=timeout):
+            async for chunk in self._driver.send_and_stream(
+                text, timeout=timeout, budgets=budgets, model=model,
+            ):
                 if chunk.delta:
                     await self._send_sse(
                         resp,