Lykhoyda
diff --git a/‎.changeset/debugger-seat-optout.md‎
Lines changed: 9 additions & 0 deletions b/‎.changeset/debugger-seat-optout.md‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎CLAUDE-MD-TEMPLATE.md‎
Lines changed: 1 addition & 0 deletions b/‎CLAUDE-MD-TEMPLATE.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 2 additions & 1 deletion b/‎CLAUDE.md‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎README.md‎
Lines changed: 1 addition & 1 deletion b/‎README.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎commands/doctor.md‎
Lines changed: 2 additions & 2 deletions b/‎commands/doctor.md‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎docs-site/src/content/docs/guides/maestro-interop.mdx‎
Lines changed: 25 additions & 0 deletions b/‎docs-site/src/content/docs/guides/maestro-interop.mdx‎
Lines changed: 25 additions & 0 deletions
@@ -0,0 +1,9 @@
+---
+"rn-dev-agent-cdp": minor
+"rn-dev-agent-plugin": minor
+---
+
+Debugger-seat coexistence with React Native DevTools + silent hook-mode network capture.
+
+- New opt-out for background auto-reconnect: `RN_CDP_AUTOCONNECT=0` or `.rn-agent/config.json` `{ "cdp": { "autoConnect": false } }`. In passive mode the bridge yields the single RN debugger seat to the visual DevTools and reconnects only on explicit tool calls. Resolved mode is visible in `cdp_status` → `autoConnect` and `/doctor`.
+- Hook-mode network capture (RN < 0.83 fallback) no longer transports entries via `console.log("__RN_NET__:…")` — entries go to an in-app ring buffer drained on demand, so Metro logs and the user's DevTools console stay clean.
@@ -493,6 +493,7 @@ Tool calls must follow this sequence to avoid race conditions:
 | `cdp_reload` reports `reconnected: false` | Wait 5-10s | New Hermes target not yet registered | `cdp_connect force: true`; if ambiguous target, pass `targetId:` |
 | `device_screenshot` captures the wrong platform | — | Multi-device routing bug | Pass `platform:` explicitly, or fall back to raw `adb screencap` / `simctl io` |
 | `cdp_interact accessibilityLabel="..."` fails (label matching is fuzzy) | Prefer testID-keyed calls: `cdp_interact(testID="...")` or `device_batch` with `testID=` field. Fall back to `device_snapshot` + `device_press(ref="@eN")` only when no testID exists. | Label matching unreliable; testID matching is exact and fiber-tree-resolved | — |
+| "Disconnected due to opening a second DevTools window" / React Native DevTools keeps getting kicked | `cdp_status` → `autoConnect` field | RN allows one debugger frontend per app; bridge auto-reconnects by default (agent-first) | Set `RN_CDP_AUTOCONNECT=0` or `.rn-agent/config.json` → `{ "cdp": { "autoConnect": false } }`. Bridge then reconnects only on explicit tool calls and yields again when DevTools reopens. Note: **any** CDP tool call — including `cdp_status` — reclaims the seat while it runs; passive mode only stops *background* re-grabs. |
 
 ### Authentication & Permission Pre-flight
 
 
@@ -68,7 +68,7 @@ Development scaffolding lives in the **sibling workspace repo**:
 Authoring & lifecycle:
 ```
 /rn-dev-agent:setup                    — Check & install all prerequisites; scaffolds .rn-agent/
-/rn-dev-agent:doctor                   — 14-row diagnostic table for the whole environment
+/rn-dev-agent:doctor                   — 15-row diagnostic table for the whole environment
 /rn-dev-agent:check-env                — Quick environment-readiness check
 /rn-dev-agent:rn-feature-dev <desc>    — Full 8-phase feature development pipeline
 /rn-dev-agent:test-feature <desc>      — Test a feature end-to-end; auto-records an action on pass
@@ -105,6 +105,7 @@ Repo-local troubleshooting memory (replaces the Experience Engine):
 - **"rn-fast-runner did not become ready" / no `.xctestrun` at the expected path** → The runner self-builds on first use (cold `xcodebuild test`), so this now usually means the cold build itself timed out or failed — not a missing prebuild. The cold-build ready timeout is 360s; a slower machine or a build error (check Xcode/simulator state) can still trip it. To take the build out of the hot path, pre-build once with `xcodebuild build-for-testing` (see Prerequisites). The build artifacts live at `scripts/rn-fast-runner/build/DerivedData/`.
 - **Legacy `AgentDeviceRunner` re-appears on the simulator** → A stale `~/.agent-device/daemon.json` is respawning the upstream runner. Since #202 the plugin terminates stale `AgentDeviceRunner` processes at session-open by default (scoped to the target simulator UDID) and clears orphaned `~/.agent-device/daemon.{json,lock}`, so this should self-heal. If you've opted out via `RN_DEVICE_KILL_LEGACY=0`, either drop that override or clean up one-time: `pkill -f AgentDeviceRunner && rm -f ~/.agent-device/daemon.json ~/.agent-device/daemon.lock`.
 - **`RnFastRunner` / `RnFastRunnerUITests-Runner` icons appear on the simulator** → Expected, not clutter. iOS device control is an XCUITest rig (D1219), so running it installs two apps: `RnFastRunner` (the minimal host app, bundle `dev.lykhoyda.rndevagent.fastrunner`) and `RnFastRunnerUITests-Runner` (the XCUITest harness — same pattern as WebDriverAgent's `WebDriverAgentRunner`). The Runner hosts the `POST /command` HTTP server on port 22088 and drives YOUR app via `XCUIApplication(bundleIdentifier:)` — it never drives itself. It stays installed/running on purpose so subsequent `device_*` calls are fast; leave it. (Contrast the legacy `AgentDeviceRunner` above, which IS unwanted.)
+- **"Disconnected due to opening a second DevTools window" / React Native DevTools keeps getting kicked** → RN allows exactly one debugger frontend per app, and the bridge auto-reconnects by default (agent-first). To let the visual DevTools hold the seat, set `RN_CDP_AUTOCONNECT=0` (or `.rn-agent/config.json` → `{ "cdp": { "autoConnect": false } }`). The bridge then reconnects only when a CDP tool actually runs, and yields again once you reopen DevTools. Note: **any** CDP tool call — including `cdp_status` — reclaims the seat while it runs; passive mode only stops *background* re-grabs. Check the resolved mode in `cdp_status` → `autoConnect`.
 - **"No booted simulator"** → Open Simulator.app or boot one via Xcode
 - **iOS 26.x beta issues** → Use iOS 18 stable runtime (Xcode > Settings > Platforms)
 - **Node.js odd version (v25)** → Switch to Node 22 LTS: `nvm install 22 && nvm use 22`
 
@@ -95,7 +95,7 @@ An **action** is a saved Maestro flow the agent **emits** when `/test-feature` v
 | Command | Purpose |
 |---------|---------|
 | `/rn-dev-agent:setup` | Inject CLAUDE.md tool-routing rules + nav-ref + Zustand exposure |
-| `/rn-dev-agent:doctor` | 14-row diagnostic table — Node, CDP, rn-fast-runner (iOS), agent-device (Android), maestro-runner, simulators, Metro, helpers freshness, plugin version |
+| `/rn-dev-agent:doctor` | 15-row diagnostic table — Node, CDP, rn-fast-runner (iOS), agent-device (Android), maestro-runner, simulators, Metro, helpers freshness, plugin version, CDP auto-reconnect mode |
 | `/rn-dev-agent:check-env` | Quick environment-readiness check |
 | `/rn-dev-agent:nav-graph` | Extract and inspect the app navigation graph |
 | `/rn-dev-agent:send-feedback` | Open a GitHub issue with sanitized environment context |
 
@@ -4,12 +4,12 @@ description: Diagnose installation health. Check Node, CDP bridge, rn-fast-runne
 argument-hint: 
 ---
 
-Run the environment-diagnostic checklist from the `rn-setup` skill. Walk all 14 prerequisite checks (Node.js version, CDP bridge dependencies, **rn-fast-runner build (iOS)**, **agent-device CLI (Android)**, maestro-runner, iOS simulator, Android emulator, Metro dev server, CDP connection, **injected `__RN_AGENT` helpers**, ffmpeg, physical-device prerequisites, **plugin version freshness**, **Vercel rules sync freshness**) and surface install commands for any missing dependencies.
+Run the environment-diagnostic checklist from the `rn-setup` skill. Walk all 15 prerequisite checks (Node.js version, CDP bridge dependencies, **rn-fast-runner build (iOS)**, **agent-device CLI (Android)**, maestro-runner, iOS simulator, Android emulator, Metro dev server, CDP connection, **injected `__RN_AGENT` helpers**, ffmpeg, physical-device prerequisites, **plugin version freshness**, **Vercel rules sync freshness**, **CDP auto-reconnect mode**) and surface install commands for any missing dependencies.
 
 iOS device automation is owned by the in-tree `rn-fast-runner` XCTest project (D1219, PR #164) — `agent-device` is Android-only after that change. Mark `agent-device` as N/A on iOS-only setups and `rn-fast-runner` as N/A on Android-only / non-macOS setups.
 
 **This command is read-only.** It diagnoses the current environment and recommends fixes. It does NOT modify any files in the user's project, inject documentation, or instrument source code.
 
-Present results as a 14-row table. For any RED rows, give the user the exact install command (with `nvm` / `sudo` / `brew` flag selection based on their environment). For the `rn-fast-runner` row: if NEEDS_BUILD, note that the runner self-builds on first use (a slow cold build) and OFFER to run the one-time `xcodebuild build-for-testing` now to move that cost out of the first interaction (the rn-setup skill section 3 has the exact form + the offer prompt). Building the runner writes only to plugin-internal `scripts/rn-fast-runner/build/` — it does not touch the user's project, so the offer is consistent with this command's read-only-on-your-project contract. For the helpers row specifically, do NOT suggest retrying `cdp_status` — the bridge already auto-retried injection. If MISSING, recommend `device_*` fallbacks or `cdp_reload`. For the **plugin version** row: if BEHIND, surface `/plugin update rn-dev-agent` and let the user decide whether to update before continuing. If OFFLINE (GitHub unreachable), skip without failing — plugin works fine without the upstream check. For the **Vercel rules sync** row: if STALE (>30 days since last sync) or MISSING (no `third_party/vercel-labs/agent-skills/UPSTREAM.lock.json`), surface the resync command — do NOT auto-run; the user runs `node ${CLAUDE_PLUGIN_ROOT}/scripts/sync-vercel-skills.mjs --ref <sha>` themselves.
+Present results as a 15-row table. For any RED rows, give the user the exact install command (with `nvm` / `sudo` / `brew` flag selection based on their environment). For the `rn-fast-runner` row: if NEEDS_BUILD, note that the runner self-builds on first use (a slow cold build) and OFFER to run the one-time `xcodebuild build-for-testing` now to move that cost out of the first interaction (the rn-setup skill section 3 has the exact form + the offer prompt). Building the runner writes only to plugin-internal `scripts/rn-fast-runner/build/` — it does not touch the user's project, so the offer is consistent with this command's read-only-on-your-project contract. For the helpers row specifically, do NOT suggest retrying `cdp_status` — the bridge already auto-retried injection. If MISSING, recommend `device_*` fallbacks or `cdp_reload`. For the **plugin version** row: if BEHIND, surface `/plugin update rn-dev-agent` and let the user decide whether to update before continuing. If OFFLINE (GitHub unreachable), skip without failing — plugin works fine without the upstream check. For the **Vercel rules sync** row: if STALE (>30 days since last sync) or MISSING (no `third_party/vercel-labs/agent-skills/UPSTREAM.lock.json`), surface the resync command — do NOT auto-run; the user runs `node ${CLAUDE_PLUGIN_ROOT}/scripts/sync-vercel-skills.mjs --ref <sha>` themselves. For the **CDP auto-reconnect** row: read `autoConnect` from `cdp_status` output; report `ON (default)`, `OFF (env)`, or `OFF (config)`. OFF is informational (YELLOW, not RED) with note "React Native DevTools can hold the debugger seat; the bridge reconnects only on tool calls".
 
 If the user wants the plugin to also inject project instructions (CLAUDE.md template, nav-ref, store exposure) — point them at `/rn-dev-agent:setup` instead.
@@ -29,3 +29,28 @@ A `maestro_run` / `maestro_test_all` flow (rn-dev-agent's own L3) takes the devi
 ## Why there's no shared "WDA session" to ride (#210)
 
 A natural question: since maestro drives the device fine via WebDriverAgent, can `device_*` "ride" that WDA session instead of rn-fast-runner? No — maestro-runner spawns WDA **per flow** and tears it down when the flow exits, so there's no persistent session to attach to, and a WDA client would add a *second* XCUITest backend (the opposite of unifying). The coherent model is: **rn-fast-runner is the `device_*` backend** (it auto-spawns when prebuilt — `cdp_status.deviceSession` shows its `alive`/`stale`/`dead` state), **maestro/WDA is the flow engine**, and they're serialized. Mid-flow, use simctl for pixels and CDP reads for state/tree.
+
+## Using rn-dev-agent with React Native DevTools
+
+React Native (Hermes) allows **exactly one debugger frontend** per app at a time. By default, rn-dev-agent is agent-first: its CDP bridge auto-reconnects in the background after each disconnect, which means opening the visual React Native DevTools window will kick the bridge out — and the bridge will immediately reclaim the seat.
+
+**To let React Native DevTools hold the debugger seat**, disable background auto-reconnect with one of two opt-out surfaces:
+
+- **Environment variable** (takes precedence over everything):
+  ```bash
+  RN_CDP_AUTOCONNECT=0 # also accepts 'false'; '1'/'true' force it back on
+  ```
+- **Project config file** (`.rn-agent/config.json` in your project root, env wins):
+  ```json
+  { "cdp": { "autoConnect": false } }
+  ```
+
+In passive mode the bridge **yields the seat** and reconnects only when a CDP tool actually runs (e.g. `cdp_status`, `cdp_component_tree`). Once you reopen React Native DevTools after a tool call, the bridge yields again automatically.
+
+**Known limitation:** in passive mode, a previously-opened DevTools-sharing proxy (`cdp_open_devtools`) is not auto-resumed after a disconnect — re-run `cdp_open_devtools` if you use it.
+
+**Important caveat:** *any* CDP tool call — including `cdp_status` — reclaims the seat while it runs. Passive mode stops only *background* re-grabs (the close-triggered reconnect loop and the background poll). If you need uninterrupted DevTools access, avoid running CDP tools while the window is open.
+
+The resolved auto-connect mode is always visible in `cdp_status` → top-level `autoConnect` field: `{ enabled: true|false, source: 'default'|'env'|'config' }`. The `/rn-dev-agent:doctor` command also reports it as the **CDP auto-reconnect** row (YELLOW when OFF — informational, not an error).
+
+**Hook-mode network capture note:** on React Native < 0.83 (or when `RN_FORCE_NETWORK_HOOK=1` is set), network entries are captured by in-app `fetch`/XHR wrappers. As of this release that capture **no longer writes `__RN_NET__:…` lines to the console** — entries go directly to an in-app ring buffer (`globalThis.__RN_AGENT_NET_BUF__`, capped at 100) that the network tools drain on demand. Metro logs and your React Native DevTools console will no longer contain hook-mode network noise. No user action is required; the change is transparent.