Add persistent Chrome via CDP — browser survives session restarts

Three-layer browser resilience:

Layer 1 — Persistent Chrome via CDP:
  Chrome runs as a background process with remote debugging (port 9222).
  Playwright MCP connects via Chrome DevTools Protocol instead of
  launching its own browser. Chrome survives Claude Code restarts,
  login sessions persist, browser never dies with the session.

  New: bin/chrome-debug.sh (start/stop/status/restart/url)
  Updated: config/playwright-config.json uses cdpEndpoint
  Updated: install.sh auto-starts Chrome CDP during installation

Layer 2 — Auto-retry on context errors:
  When a page/context closes, the agent tries browser_close + retry
  once before falling back. Recovers from tab-level crashes without
  user intervention.

Layer 3 — Smart browser avoidance:
  Agent checks if browser is actually needed before using it. Skips
  browser for encrypted messaging apps, QR code flows, native apps,
  and any task with a CLI/API alternative.

Author: rish-e

README.md

@@ -127,8 +127,17 @@ A PreToolUse hook that runs before every Bash command. It's a shell script — d
 ### Smart Permissions
 All tools auto-approved (same speed as `--dangerously-skip-permissions`), with the Guardian catching dangerous patterns. Safe commands fly through with zero prompts. Dangerous commands are hard-blocked before they execute.
 
-### Browser Stability & Recovery
-The Playwright MCP is pre-configured with Chromium stability flags that prevent background throttling, hang detection, and IPC flooding — the most common causes of browser death during long sessions. A persistent browser profile at `~/MCPs/autopilot/browser-profile/` keeps login sessions alive across restarts. If the browser still dies (rare), the agent falls back to CLI tools automatically and only asks you to restart if browser is truly needed (e.g., first-time login to a new service).
+### Persistent Browser (Never Dies)
+The browser runs as a separate Chrome process via Chrome DevTools Protocol — independent of Claude Code. When your session ends or restarts, the browser stays alive. Login sessions persist. The Playwright MCP just reconnects to it.
+
+```
+Chrome (persistent, background)  ←── CDP ──→  Playwright MCP  ←──→  Claude Code
+      ↑                                              ↑
+  Always alive                                Dies with session
+  Login sessions persist                      Reconnects on start
+```
+
+Three-layer resilience: (1) persistent Chrome via CDP — browser never dies with the session, (2) auto-retry on context errors — recovers from tab crashes, (3) smart browser avoidance — skips the browser entirely for tasks it can't help with (encrypted apps, CLI-available operations).
 
 ### MCP Auto-Discovery
 Maintains a whitelist of trusted MCP servers. Whitelisted MCPs install silently when needed. Unknown MCPs: Autopilot explains what it found, why it's useful, and asks once. Approved MCPs are whitelisted forever.
@@ -237,8 +246,9 @@ If something breaks midway, open the log to see exactly what happened and where.
 ```
 ~/MCPs/autopilot/
   bin/
-    keychain.sh          # macOS Keychain wrapper (get/set/delete/list/has)
+    keychain.sh          # Cross-platform credential store (Keychain/libsecret/Credential Manager)
     guardian.sh           # PreToolUse safety hook (hard-blocks dangerous commands)
+    chrome-debug.sh       # Persistent Chrome manager (start/stop/status via CDP)
     setup-clis.sh         # CLI installer (gh, vercel, supabase, wrangler, etc.)
     test-guardian.sh      # 55-test suite for the guardian
   config/
@@ -373,7 +383,7 @@ Edit `~/MCPs/autopilot/config/trusted-mcps.yaml` and add to the `whitelisted` se
 - **Payment method setup** — PCI-compliant forms resist automation
 
 ### Technical
-- **Browser can still crash** — Stability flags reduce browser deaths significantly, but can't prevent all crashes. Autopilot falls back to CLI automatically. If you need browser automation after a crash, restart your Claude Code session. Login sessions persist in the browser profile.
+- **Chrome CDP needs to be running** — The persistent Chrome must be started before using browser features: `~/MCPs/autopilot/bin/chrome-debug.sh start`. The installer does this automatically, but after a system reboot you may need to start it again.
 - **Browser UIs change** — Playwright steps in service registry can break when dashboards redesign
 - **New MCPs need a restart** — installed MCPs take effect next Claude Code session
 - **No automatic rollback** — if a deploy goes wrong, you fix it manually

agent/autopilot.md

@@ -270,31 +270,63 @@ Do NOT search when:
 
 ## Browser Automation Protocol
 
-When using Playwright MCP for service interaction:
+### Pre-Browser Check (Layer 3 — avoid unnecessary browser use)
 
-1. **Navigate** to the service dashboard URL
-2. **Snapshot** the page (use `browser_snapshot`, NOT screenshots) to understand the current state
-3. **Check login status** — look for dashboard elements vs. login form
-4. If login needed:
-   a. Retrieve email/password from keychain
+Before opening the browser, ask: **can this task be done without it?**
+
+DO NOT use the browser for:
+- **Encrypted/authenticated messaging** (WhatsApp, Slack, Telegram) — data is encrypted, browser automation won't help
+- **Native apps or desktop software** — browser can't interact with these
+- **QR code login flows** — can't scan QR codes programmatically
+- **Tasks where a CLI/API exists** — always prefer CLI over browser
+
+Only use the browser for:
+- **Signing up for a new service** (no CLI can do this)
+- **Getting API tokens from dashboards** (when no CLI auth flow exists)
+- **Service-specific web operations** with no API/CLI equivalent
+
+### Browser Automation Steps
+
+When the browser IS needed:
+
+1. **Check Chrome CDP is running**: `~/MCPs/autopilot/bin/chrome-debug.sh status`. If not running, tell the user: "Run `~/MCPs/autopilot/bin/chrome-debug.sh start` to start the persistent browser."
+2. **Navigate** to the service dashboard URL
+3. **Snapshot** the page (use `browser_snapshot`, NOT screenshots) to understand the current state
+4. **Check login status** — look for dashboard elements vs. login form
+5. If login needed:
+   a. Retrieve email/password from keychain (service-specific or primary)
    b. Fill the login form using `browser_fill_form`
    c. Click the sign-in button
    d. Snapshot again to check result
-5. **If 2FA/MFA appears**: STOP IMMEDIATELY. Tell the user exactly what's needed. Do not attempt to bypass.
-6. **If CAPTCHA appears**: STOP. Tell the user.
-7. **Take it step by step** — snapshot after every significant action to verify it succeeded
-8. **Wait for page loads** — use `browser_wait_for` when navigating between pages
-9. When done, capture any values needed (API keys, URLs, etc.) and store them in keychain
+6. **If 2FA/MFA appears**: STOP IMMEDIATELY. Tell the user exactly what's needed. Do not attempt to bypass.
+7. **If CAPTCHA appears**: STOP. Tell the user.
+8. **Take it step by step** — snapshot after every significant action to verify it succeeded
+9. **Wait for page loads** — use `browser_wait_for` when navigating between pages
+10. When done, capture any values needed (API keys, URLs, etc.) and store them in keychain
+
+### Browser Error Recovery (Layer 2 — auto-retry)
 
-### Browser Recovery Protocol
+If a browser operation fails with "Target page, context or browser has been closed" or similar:
 
-The Playwright browser instance can die or expire during a session. When this happens:
+1. **Try to recover**: call `browser_close` to clean up, then retry the navigation ONCE. Sometimes only the page/context dies, not the whole browser — a close + reopen can recover it.
+2. **If retry fails**: DO NOT attempt to fix it further. Never run `kill`, `pkill`, `killall` on Playwright or MCP processes.
+3. **Check if CLI can handle the task.** Most operations that use the browser have a CLI equivalent. Check if the required credential is already in keychain (`keychain.sh has {service} {key}`). If yes, switch to CLI and continue.
+4. **If CLI works** → switch to CLI, complete the task, include a brief note: "Browser context error, completed via CLI instead."
+5. **If browser is truly required** → tell the user: "The browser context has closed. Run `~/MCPs/autopilot/bin/chrome-debug.sh restart` and try again."
+
+### Persistent Chrome Architecture
+
+The browser runs as a separate Chrome process with Chrome DevTools Protocol (CDP) on port 9222. Playwright MCP connects to it rather than launching its own browser.
+
+```
+Chrome (persistent, background)  ←── CDP ──→  Playwright MCP  ←──→  Claude Code
+      ↑                                              ↑
+  Survives restarts                           Dies with session
+  Login sessions persist                      Reconnects on start
+  ~/MCPs/autopilot/browser-profile/
+```
 
-1. **DO NOT attempt to fix it.** Never run `kill`, `pkill`, `killall`, or any command targeting Playwright or MCP processes. MCP servers are managed by the Claude Code harness — killing them disconnects the MCP entirely and makes things worse.
-2. **Check if CLI can handle the task.** Most operations that use the browser have a CLI equivalent. Check if the required credential is already in keychain (`keychain.sh has {service} {key}`). If yes, switch to CLI and continue.
-3. **If CLI works** → switch to CLI, complete the task, include a brief note: "Browser session expired, completed via CLI instead."
-4. **If browser is truly required** (first-time login to a service with no CLI, no credential in keychain) → tell the user: "The Playwright browser session has expired. Please restart Claude Code (`claude --agent autopilot`) and I'll pick up where I left off. Your credentials and progress are saved."
-5. **Never retry browser operations** after the browser is confirmed dead. Immediately fall back.
+Managed via `~/MCPs/autopilot/bin/chrome-debug.sh start|stop|status|restart`.
 
 **Key insight:** Once a credential is stored in Keychain, the browser is rarely needed again. The browser's primary job is first-time credential acquisition. Prioritize getting tokens into Keychain early in any workflow so subsequent operations are browser-independent.
 

bin/chrome-debug.sh

@@ -0,0 +1,213 @@
+#!/bin/bash
+# chrome-debug.sh — Launch and manage a persistent Chrome instance with CDP
+#
+# The Playwright MCP connects to this via Chrome DevTools Protocol instead of
+# launching its own browser. The browser persists independently of Claude Code —
+# it never dies when your session ends.
+#
+# Usage:
+#   chrome-debug.sh start     # Launch Chrome with CDP (background, survives terminal close)
+#   chrome-debug.sh stop      # Stop the Chrome instance
+#   chrome-debug.sh status    # Check if Chrome CDP is running
+#   chrome-debug.sh restart   # Stop + start
+#   chrome-debug.sh url       # Print the CDP endpoint URL
+
+set -euo pipefail
+
+CDP_PORT="${CDP_PORT:-9222}"
+PROFILE_DIR="$HOME/MCPs/autopilot/browser-profile"
+PID_FILE="$HOME/MCPs/autopilot/.chrome-debug.pid"
+
+# ─── Detect Chrome Binary ────────────────────────────────────────────────────
+
+find_chrome() {
+    case "$(uname -s)" in
+        Darwin)
+            for bin in \
+                "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+                "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary" \
+                "/Applications/Chromium.app/Contents/MacOS/Chromium" \
+                "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"; do
+                [ -x "$bin" ] && echo "$bin" && return
+            done
+            ;;
+        Linux)
+            for bin in google-chrome google-chrome-stable chromium-browser chromium; do
+                command -v "$bin" &>/dev/null && echo "$bin" && return
+            done
+            # Check snap
+            [ -x "/snap/bin/chromium" ] && echo "/snap/bin/chromium" && return
+            ;;
+        MINGW*|MSYS*|CYGWIN*)
+            for bin in \
+                "/c/Program Files/Google/Chrome/Application/chrome.exe" \
+                "/c/Program Files (x86)/Google/Chrome/Application/chrome.exe" \
+                "$LOCALAPPDATA/Google/Chrome/Application/chrome.exe"; do
+                [ -x "$bin" ] && echo "$bin" && return
+            done
+            ;;
+    esac
+    echo ""
+}
+
+# ─── CDP Endpoint Detection ──────────────────────────────────────────────────
+
+# macOS Chrome may bind to IPv6 only — try both
+get_cdp_url() {
+    # Try IPv4 first, then IPv6
+    if curl -s --connect-timeout 2 "http://127.0.0.1:${CDP_PORT}/json/version" > /dev/null 2>&1; then
+        echo "http://127.0.0.1:${CDP_PORT}"
+    elif curl -s --connect-timeout 2 "http://[::1]:${CDP_PORT}/json/version" > /dev/null 2>&1; then
+        echo "http://[::1]:${CDP_PORT}"
+    else
+        echo ""
+    fi
+}
+
+is_running() {
+    local url
+    url=$(get_cdp_url)
+    [ -n "$url" ]
+}
+
+# ─── Commands ────────────────────────────────────────────────────────────────
+
+cmd_start() {
+    if is_running; then
+        echo "Chrome CDP already running on port ${CDP_PORT}"
+        echo "Endpoint: $(get_cdp_url)"
+        return 0
+    fi
+
+    local chrome_bin
+    chrome_bin=$(find_chrome)
+
+    if [ -z "$chrome_bin" ]; then
+        echo "ERROR: No Chrome/Chromium installation found." >&2
+        echo "Install Google Chrome or Chromium and try again." >&2
+        exit 1
+    fi
+
+    echo "Starting Chrome with CDP on port ${CDP_PORT}..."
+    echo "Binary: $chrome_bin"
+    echo "Profile: $PROFILE_DIR"
+
+    mkdir -p "$PROFILE_DIR"
+
+    # Launch Chrome in background with CDP enabled
+    nohup "$chrome_bin" \
+        --remote-debugging-port="${CDP_PORT}" \
+        --no-first-run \
+        --no-default-browser-check \
+        --user-data-dir="$PROFILE_DIR" \
+        --disable-background-timer-throttling \
+        --disable-renderer-backgrounding \
+        --disable-backgrounding-occluded-windows \
+        --disable-ipc-flooding-protection \
+        --disable-hang-monitor \
+        --disable-back-forward-cache \
+        --disable-features=CalculateNativeWinOcclusion \
+        > /dev/null 2>&1 &
+
+    local pid=$!
+    echo "$pid" > "$PID_FILE"
+
+    # Wait for CDP to become available (up to 10 seconds)
+    local attempts=0
+    while [ $attempts -lt 20 ]; do
+        if is_running; then
+            echo "Chrome CDP ready"
+            echo "Endpoint: $(get_cdp_url)"
+            echo "PID: $pid"
+            return 0
+        fi
+        sleep 0.5
+        ((attempts++))
+    done
+
+    echo "ERROR: Chrome started but CDP not responding on port ${CDP_PORT}" >&2
+    echo "Check if another Chrome instance is using the debugging port" >&2
+    exit 1
+}
+
+cmd_stop() {
+    if [ -f "$PID_FILE" ]; then
+        local pid
+        pid=$(cat "$PID_FILE")
+        if kill -0 "$pid" 2>/dev/null; then
+            kill "$pid" 2>/dev/null
+            echo "Stopped Chrome CDP (PID: $pid)"
+        else
+            echo "PID $pid not running (stale PID file)"
+        fi
+        rm -f "$PID_FILE"
+    else
+        # Try to find and stop any Chrome with our debug port
+        local pids
+        pids=$(lsof -ti ":${CDP_PORT}" 2>/dev/null || true)
+        if [ -n "$pids" ]; then
+            echo "$pids" | xargs kill 2>/dev/null
+            echo "Stopped Chrome CDP process(es) on port ${CDP_PORT}"
+        else
+            echo "No Chrome CDP instance found on port ${CDP_PORT}"
+        fi
+    fi
+}
+
+cmd_status() {
+    if is_running; then
+        local url
+        url=$(get_cdp_url)
+        echo "Chrome CDP is running"
+        echo "Endpoint: $url"
+        # Show browser version
+        local version
+        version=$(curl -s "${url}/json/version" 2>/dev/null | jq -r '.Browser // "unknown"' 2>/dev/null)
+        echo "Browser: $version"
+        # Show open tabs
+        local tabs
+        tabs=$(curl -s "${url}/json/list" 2>/dev/null | jq 'length' 2>/dev/null || echo "?")
+        echo "Open tabs: $tabs"
+        if [ -f "$PID_FILE" ]; then
+            echo "PID: $(cat "$PID_FILE")"
+        fi
+    else
+        echo "Chrome CDP is NOT running"
+        echo "Start it: ~/MCPs/autopilot/bin/chrome-debug.sh start"
+        return 1
+    fi
+}
+
+cmd_url() {
+    local url
+    url=$(get_cdp_url)
+    if [ -n "$url" ]; then
+        echo "$url"
+    else
+        echo "ERROR: Chrome CDP not running on port ${CDP_PORT}" >&2
+        exit 1
+    fi
+}
+
+cmd_restart() {
+    cmd_stop
+    sleep 1
+    cmd_start
+}
+
+# ─── Main ────────────────────────────────────────────────────────────────────
+
+case "${1:-status}" in
+    start)   cmd_start ;;
+    stop)    cmd_stop ;;
+    status)  cmd_status ;;
+    restart) cmd_restart ;;
+    url)     cmd_url ;;
+    *)
+        echo "Usage: chrome-debug.sh {start|stop|status|restart|url}"
+        echo ""
+        echo "Manages a persistent Chrome instance with Chrome DevTools Protocol."
+        echo "Playwright MCP connects to this instead of launching its own browser."
+        exit 2
+        ;;
+esac

config/playwright-config.json

@@ -1,22 +1,6 @@
 {
   "browser": {
-    "browserName": "chromium",
-    "launchOptions": {
-      "channel": "chrome",
-      "headless": false,
-      "args": [
-        "--disable-background-timer-throttling",
-        "--disable-renderer-backgrounding",
-        "--disable-backgrounding-occluded-windows",
-        "--disable-ipc-flooding-protection",
-        "--disable-hang-monitor",
-        "--disable-back-forward-cache",
-        "--disable-features=CalculateNativeWinOcclusion"
-      ]
-    },
-    "contextOptions": {
-      "viewport": { "width": 1280, "height": 720 }
-    }
+    "cdpEndpoint": "http://127.0.0.1:9222"
   },
   "timeouts": {
     "action": 10000,