From c8972e71c5cd52d1b54721d0c4856bf469329624 Mon Sep 17 00:00:00 2001
From: Peter Dedene <peter@zenjoy.be>
Date: Thu, 19 Mar 2026 12:18:07 +0100
Subject: [PATCH 1/2] feat(browser): attach to running browsers via direct CDP

---
 CHANGELOG.md                          |   8 +
 README.md                             |  15 +-
 bin/oracle-cli.ts                     |  13 +-
 docs/browser-mode.md                  |  55 ++++-
 docs/configuration.md                 |   2 +-
 docs/manual-tests.md                  |  17 ++
 src/browser/attachRunning.ts          |  57 +++++
 src/browser/chromeLifecycle.ts        | 221 ++++++++++++++++++-
 src/browser/config.ts                 |   8 +
 src/browser/detect.ts                 | 304 +++++++++++++++++++++++---
 src/browser/index.ts                  |  64 +++++-
 src/browser/reattach.ts               | 105 +++++++--
 src/browser/sessionRunner.ts          |   5 +
 src/browser/types.ts                  |  11 +
 src/cli/browserConfig.ts              |  41 ++++
 src/cli/browserDefaults.ts            |   4 +
 src/cli/sessionDisplay.ts             |   6 +-
 src/config.ts                         |   1 +
 src/sessionManager.ts                 |   4 +
 tests/browser/attachRunning.test.ts   | 107 +++++++++
 tests/browser/chromeLifecycle.test.ts | 128 ++++++++++-
 tests/browser/detect.test.ts          |  90 ++++++++
 tests/browser/index.test.ts           |  22 +-
 tests/browser/reattach.test.ts        |  60 +++++
 tests/browser/sessionRunner.test.ts   |  67 ++++++
 tests/cli/browserConfig.test.ts       |  68 ++++++
 tests/cli/browserDefaults.test.ts     |  13 ++
 27 files changed, 1406 insertions(+), 90 deletions(-)
 create mode 100644 src/browser/attachRunning.ts
 create mode 100644 tests/browser/attachRunning.test.ts
 create mode 100644 tests/browser/detect.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b35b95da5..fff838caa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Added
+
+- Browser: add `--browser-attach-running` to reuse a local already-running signed-in Chrome through Chrome’s local remote-debugging toggle. Oracle opens a dedicated tab, stores attach metadata for reattach, and leaves the browser itself untouched.
+
+### Docs
+
+- Browser: document the new attach-running workflow and add a manual smoke test for the direct attach path.
+
 ## 0.9.0 — 2026-03-08
 
 ### Changed
diff --git a/README.md b/README.md
index ff42a29e2..e03cdbdd7 100644
--- a/README.md
+++ b/README.md
@@ -211,9 +211,10 @@ oracle --engine browser \
 | `--chatgpt-url <url>`                                           | Target a ChatGPT workspace/folder (browser).                                                                                                                                                                                                                                                                    |
 | `--browser-model-strategy <select\|current\|ignore>`            | Control ChatGPT model selection in browser mode (current keeps the active model; ignore skips the picker).                                                                                                                                                                                                      |
 | `--browser-manual-login`                                        | Skip cookie copy; reuse a persistent automation profile and wait for manual ChatGPT login.                                                                                                                                                                                                                      |
+| `--browser-attach-running`                                      | Reuse your current local browser session through local `DevToolsActivePort` discovery; Oracle opens a dedicated tab instead of launching Chrome (defaults to `127.0.0.1:9222`, or combine with `--remote-chrome <host:port>` to hint a different local endpoint).                                               |
 | `--browser-thinking-time <light\|standard\|extended\|heavy>`    | Set ChatGPT thinking-time intensity (browser; Thinking/Pro models only).                                                                                                                                                                                                                                        |
 | `--browser-port <port>`                                         | Pin the Chrome DevTools port (WSL/Windows firewall helper).                                                                                                                                                                                                                                                     |
-| `--browser-inline-cookies[(-file)] <payload \| path>`          | Supply cookies without Chrome/Keychain (browser).                                                                                                                                                                                                                                                               |
+| `--browser-inline-cookies[(-file)] <payload \| path>`           | Supply cookies without Chrome/Keychain (browser).                                                                                                                                                                                                                                                               |
 | `--browser-timeout`, `--browser-input-timeout`                  | Control overall/browser input timeouts (supports h/m/s/ms).                                                                                                                                                                                                                                                     |
 | `--browser-recheck-delay`, `--browser-recheck-timeout`          | Delayed recheck for long Pro runs: wait then retry capture after timeout (supports h/m/s/ms).                                                                                                                                                                                                                   |
 | `--browser-reuse-wait`                                          | Wait for a shared Chrome profile before launching (parallel browser runs).                                                                                                                                                                                                                                      |
@@ -229,7 +230,7 @@ oracle --engine browser \
 | `--files-report`                                                | Print per-file token usage.                                                                                                                                                                                                                                                                                     |
 | `--dry-run [summary\|json\|full]`                               | Preview without sending.                                                                                                                                                                                                                                                                                        |
 | `--remote-host`, `--remote-token`                               | Use a remote `oracle serve` host (browser).                                                                                                                                                                                                                                                                     |
-| `--remote-chrome <host:port>`                                   | Attach to an existing remote Chrome session (browser).                                                                                                                                                                                                                                                          |
+| `--remote-chrome <host:port>`                                   | Attach to an existing remote Chrome session (browser), or when combined with `--browser-attach-running` use this host:port as the local attach hint.                                                                                                                                                            |
 | `--youtube <url>`                                               | YouTube video URL to analyze (Gemini browser mode).                                                                                                                                                                                                                                                             |
 | `--generate-image <file>`                                       | Generate image and save to file (Gemini browser mode).                                                                                                                                                                                                                                                          |
 | `--edit-image <file>`                                           | Edit existing image with `--output` (Gemini browser mode).                                                                                                                                                                                                                                                      |
@@ -255,11 +256,11 @@ See [docs/configuration.md](docs/configuration.md) for precedence and full schem
 
 Advanced flags
 
-| Area         | Flags                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Browser      | `--browser-manual-login`, `--browser-thinking-time`, `--browser-timeout`, `--browser-input-timeout`, `--browser-recheck-delay`, `--browser-recheck-timeout`, `--browser-reuse-wait`, `--browser-profile-lock-timeout`, `--browser-auto-reattach-delay`, `--browser-auto-reattach-interval`, `--browser-auto-reattach-timeout`, `--browser-cookie-wait`, `--browser-inline-cookies[(-file)]`, `--browser-attachments`, `--browser-inline-files`, `--browser-bundle-files`, `--browser-keep-browser`, `--browser-headless`, `--browser-hide-window`, `--browser-no-cookie-sync`, `--browser-allow-cookie-errors`, `--browser-chrome-path`, `--browser-cookie-path`, `--chatgpt-url` |
-| Run control  | `--background`, `--no-background`, `--http-timeout`, `--zombie-timeout`, `--zombie-last-activity`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Azure/OpenAI | `--azure-endpoint`, `--azure-deployment`, `--azure-api-version`, `--base-url`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Area         | Flags                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Browser      | `--browser-manual-login`, `--browser-attach-running`, `--browser-thinking-time`, `--browser-timeout`, `--browser-input-timeout`, `--browser-recheck-delay`, `--browser-recheck-timeout`, `--browser-reuse-wait`, `--browser-profile-lock-timeout`, `--browser-auto-reattach-delay`, `--browser-auto-reattach-interval`, `--browser-auto-reattach-timeout`, `--browser-cookie-wait`, `--browser-inline-cookies[(-file)]`, `--browser-attachments`, `--browser-inline-files`, `--browser-bundle-files`, `--browser-keep-browser`, `--browser-headless`, `--browser-hide-window`, `--browser-no-cookie-sync`, `--browser-allow-cookie-errors`, `--browser-chrome-path`, `--browser-cookie-path`, `--chatgpt-url` |
+| Run control  | `--background`, `--no-background`, `--http-timeout`, `--zombie-timeout`, `--zombie-last-activity`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Azure/OpenAI | `--azure-endpoint`, `--azure-deployment`, `--azure-api-version`, `--base-url`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 
 Remote browser example
 
diff --git a/bin/oracle-cli.ts b/bin/oracle-cli.ts
index f8768328c..8a6690741 100755
--- a/bin/oracle-cli.ts
+++ b/bin/oracle-cli.ts
@@ -125,6 +125,7 @@ interface CliOptions extends OptionValues {
   browserChromeProfile?: string;
   browserChromePath?: string;
   browserCookiePath?: string;
+  browserAttachRunning?: boolean;
   chatgptUrl?: string;
   browserUrl?: string;
   browserTimeout?: string;
@@ -460,6 +461,12 @@ program
       "Explicit Chrome/Chromium cookie DB path for session reuse.",
     ),
   )
+  .addOption(
+    new Option(
+      "--browser-attach-running",
+      "Attach to a running local browser session instead of launching Chrome (defaults to 127.0.0.1:9222; combine with --remote-chrome to hint a different host:port).",
+    ),
+  )
   .addOption(
     new Option(
       "--chatgpt-url <url>",
@@ -609,7 +616,7 @@ program
   .addOption(
     new Option(
       "--remote-chrome <host:port>",
-      "Connect to remote Chrome DevTools Protocol (e.g., 192.168.1.10:9222 or [2001:db8::1]:9222 for IPv6).",
+      "Connect to remote Chrome DevTools Protocol, or when combined with --browser-attach-running use this host:port as the local attach hint.",
     ),
   )
   .addOption(
@@ -2091,6 +2098,10 @@ function printDebugHelp(cliName: string): void {
     ["--browser-chrome-profile <name>", "Reuse cookies from a specific Chrome profile."],
     ["--browser-chrome-path <path>", "Point to a custom Chrome/Chromium binary."],
     ["--browser-cookie-path <path>", "Use a specific Chrome/Chromium cookie store file."],
+    [
+      "--browser-attach-running",
+      "Attach to your current Chrome session through its local remote debugging toggle.",
+    ],
     ["--browser-url <url>", "Alias for --chatgpt-url."],
     ["--browser-timeout <ms|s|m>", "Cap total wait time for the assistant response."],
     ["--browser-input-timeout <ms|s|m>", "Cap how long we wait for the composer textarea."],
diff --git a/docs/browser-mode.md b/docs/browser-mode.md
index c45c15e21..b9b815523 100644
--- a/docs/browser-mode.md
+++ b/docs/browser-mode.md
@@ -1,8 +1,9 @@
 # Browser Mode
 
-Oracle’s `--engine browser` supports two different execution paths:
+Oracle’s `--engine browser` supports three different execution paths:
 
-- **ChatGPT automation** (GPT-\* models): drives the ChatGPT web UI with Chrome automation.
+- **ChatGPT launcher mode** (GPT-\* models): Oracle launches Chrome itself and drives the ChatGPT web UI over CDP.
+- **ChatGPT attach-running mode** (GPT-\* models): Oracle attaches to your already-running local Chrome session through Chrome’s local remote-debugging toggle, opens a dedicated tab, and leaves the browser process/profile alone.
 - **Gemini web mode** (Gemini models): talks directly to `gemini.google.com` using your signed-in Chrome cookies (no ChatGPT automation).
 
 If you’re running Gemini, also see `docs/gemini.md`.
@@ -41,17 +42,48 @@ oracle --engine browser \
 
 You can pass the same payload inline (`--browser-inline-cookies '<json or base64>'`) or via env (`ORACLE_BROWSER_COOKIES_JSON`, `ORACLE_BROWSER_COOKIES_FILE`). Cloudflare cookies (`cf_clearance`, `__cf_bm`, etc.) are only needed when you hit a challenge.
 
+## Quick example: attach to your running Chrome
+
+Use this when you already have a signed-in Chrome session running with DevTools access enabled and want Oracle to reuse that browser instead of launching its own copy.
+
+```bash
+oracle --engine browser \
+  --browser-attach-running \
+  --model "GPT-5.4 Pro" \
+  -p "Summarize the last assistant response in one paragraph"
+```
+
+Notes:
+
+- `--browser-attach-running` defaults to local attach discovery at `127.0.0.1:9222`.
+- If the browser UI shows a different local endpoint, you can point Oracle at it explicitly:
+  ```bash
+  oracle --engine browser \
+    --browser-attach-running \
+    --remote-chrome 127.0.0.1:63332 \
+    --model "GPT-5.4 Pro" \
+    -p "Summarize the last assistant response in one paragraph"
+  ```
+- Oracle reads local `DevToolsActivePort` metadata, connects to the browser websocket directly, and then reuses the normal CDP automation flow.
+- If Chrome shows a remote-debugging approval prompt on first attach, Oracle issues one attach request and waits briefly for you to allow it before failing.
+- Attach mode always opens a fresh Oracle-owned tab and closes only that tab after a successful run.
+- Cookie sync, Chrome launch flags, and profile lifecycle flags are skipped because the browser is already running.
+- If Chrome is not exposing a classic `/json/version` endpoint, use `--browser-attach-running` instead of standalone `--remote-chrome`.
+
 ## Current Pipeline
 
 1. **Prompt assembly** – we reuse the normal prompt builder (`buildPrompt`) and the markdown renderer. Browser mode pastes the system + user text (no special markers) into the ChatGPT composer and, by default, pastes resolved file contents inline until the total pasted content reaches ~60k characters (then switches to uploads).
-2. **Automation stack** – code lives in `src/browserMode.ts` and is a lightly refactored version of the `oraclecheap` utility:
-   - Launches Chrome via `chrome-launcher` and connects with `chrome-remote-interface`.
-   - (Optional) copies cookies from the requested browser profile via Oracle’s built-in cookie reader (Keychain/DPAPI aware) so you stay signed in.
-   - Navigates to `chatgpt.com`, switches the model to the requested GPT-5.4 / GPT-5.2 variant, pastes the prompt, waits for completion, and copies the markdown via the built-in “copy turn” button.
-   - Immediately probes `/backend-api/me` in the ChatGPT tab to verify the session is authenticated; if the endpoint returns 401/403 we abort early with a login-specific error instead of timing out waiting for the composer.
-   - When `--file` inputs would push the pasted composer content over ~60k characters, we switch to uploading attachments (optionally bundled) and wait for ChatGPT to re-enable the send button before submitting the combined system+user prompt.
-   - Cleans up the temporary profile unless `--browser-keep-browser` is passed.
-3. **Session integration** – browser sessions use the normal log writer, add `mode: "browser"` plus `browser.config/runtime` metadata, and log the Chrome PID/port so `oracle session <id>` (or `oracle status <id>`) shows a marker for the background Chrome process.
+2. **Automation stack** – code lives under `src/browser/`:
+   - Launcher mode starts Chrome via `chrome-launcher` and connects with `chrome-remote-interface`.
+
+- Attach-running mode reads local `DevToolsActivePort` metadata for the selected local port, connects to the browser websocket, opens a dedicated tab, and reuses the same DOM automation/capture flow against that attached browser.
+- Launcher mode can optionally copy cookies from the requested browser profile via Oracle’s built-in cookie reader (Keychain/DPAPI aware) so you stay signed in.
+- Navigates to `chatgpt.com`, switches the model to the requested GPT-5.4 / GPT-5.2 variant, pastes the prompt, waits for completion, and copies the markdown via the built-in “copy turn” button.
+- Immediately probes `/backend-api/me` in the ChatGPT tab to verify the session is authenticated; if the endpoint returns 401/403 we abort early with a login-specific error instead of timing out waiting for the composer.
+- When `--file` inputs would push the pasted composer content over ~60k characters, we switch to uploading attachments (optionally bundled) and wait for ChatGPT to re-enable the send button before submitting the combined system+user prompt.
+- Launcher mode cleans up the temporary profile unless `--browser-keep-browser` is passed.
+
+3. **Session integration** – browser sessions use the normal log writer, add `mode: "browser"` plus `browser.config/runtime` metadata, and persist Chrome pid/port or websocket attach metadata plus the Oracle-owned target/tab URL for reattach.
 4. **Usage accounting** – we estimate input tokens with the same tokenizer used for API runs and estimate output tokens via `estimateTokenCount`. `oracle status` therefore shows comparable cost/timing info even though the call ran through the browser.
 
 ### CLI Options
@@ -59,6 +91,7 @@ You can pass the same payload inline (`--browser-inline-cookies '<json or base64
 - `--engine browser`: enables browser mode (legacy `--browser` remains as an alias for now). Without `--engine`, Oracle chooses API when `OPENAI_API_KEY` exists, otherwise browser.
 - `--browser-chrome-profile`, `--browser-chrome-path`: cookie source + binary override (defaults to the standard `"Default"` Chrome profile so existing ChatGPT logins carry over).
 - `--browser-cookie-path`: explicit path to the Chrome/Chromium/Edge `Cookies` SQLite DB. Handy when you launch a fork via `--browser-chrome-path` and want to copy its session cookies; see [docs/chromium-forks.md](chromium-forks.md) for examples.
+- `--browser-attach-running`: attach to a local already-running browser instead of launching Chrome directly. Defaults to `127.0.0.1:9222`; combine with `--remote-chrome <host:port>` to use a different local attach hint.
 - `--chatgpt-url`: override the ChatGPT base URL. Works with the root homepage (`https://chatgpt.com/`) **or** a specific workspace/folder link such as `https://chatgpt.com/g/.../project`. `--browser-url` stays as a hidden alias.
 - `--browser-timeout`, `--browser-input-timeout`: `1200s (20m)`/`60s` defaults. Durations accept `ms`, `s`, `m`, or `h` and can be chained (`1h2m10s`).
 - `--browser-recheck-delay`, `--browser-recheck-timeout`: after an assistant timeout, wait the delay, revisit the conversation, and retry capture (default recheck timeout 120s). Useful for Pro runs that finish later.
@@ -77,6 +110,7 @@ You can pass the same payload inline (`--browser-inline-cookies '<json or base64
 - sqlite bindings: automatic rebuilds now require `ORACLE_ALLOW_SQLITE_REBUILD=1`. Without it, the CLI logs instructions instead of running `pnpm rebuild` on your behalf.
 - `--model`: the same flag used for API runs is accepted, but the ChatGPT automation path supports GPT-5.4 and GPT-5.2 variants. Use `gpt-5.4-pro`, `gpt-5.4`, `gpt-5.2`, `gpt-5.2-thinking`, `gpt-5.2-instant`, or `gpt-5.2-pro`. Legacy Pro aliases still resolve to the latest Pro picker target.
 - Cookie sync is mandatory—if we can’t copy cookies from Chrome, the run exits early. Use the hidden `--browser-allow-cookie-errors` flag only when you’re intentionally running logged out (it skips the early exit but still warns).
+- Attach-running mode is mutually exclusive with launcher-owned flags such as `--browser-manual-login`, `--browser-chrome-profile`, `--browser-cookie-path`, `--browser-hide-window`, `--browser-keep-browser`, and `--browser-port`. `--remote-chrome` is allowed in attach-running mode, but only as the local host:port hint used to find matching `DevToolsActivePort` metadata. `--browser-chrome-path` is accepted but ignored.
 - Experimental cookie controls (hidden flags/env):
   - `--browser-cookie-names <comma-list>` or `ORACLE_BROWSER_COOKIE_NAMES`: allowlist which cookies to sync. Useful for “only NextAuth/Cloudflare, drop the rest.”
   - `--browser-cookie-wait <ms|s|m>`: if cookie sync fails or returns no cookies, wait once and retry (helps when macOS Keychain prompts are slow).
@@ -229,6 +263,7 @@ This mode is ideal when you have a macOS VM (or spare Mac mini) logged into Chat
 ## Limitations / Follow-Up Plan
 
 - **Attachment lifecycle** – in `auto` mode we prefer inlining files into the composer (fewer moving parts). When we do upload, each `--file` path is uploaded separately (or bundled) so ChatGPT can ingest filenames/content. The automation waits for uploads to finish (send button enabled, upload chips visible) before submitting. When inline paste is rejected by ChatGPT (too large), Oracle retries automatically with uploads.
+- **Attach-running uploads** – `--browser-attach-running` currently supports inline file delivery only. If the run would require browser uploads, Oracle fails fast and points you back to the standard launcher path.
 - **Model picker drift** – we rely on heuristics to pick GPT-5.4 / GPT-5.2 variants. If OpenAI changes the DOM we need to refresh the selectors quickly. Consider snapshot tests or a small “self check” command.
 - **Non-mac platforms** – window hiding uses AppleScript today; Linux/Windows just ignore the flag. We should detect platforms explicitly and document the behavior.
 - **Streaming UX** – browser runs cannot stream tokens, so we log a warning before launching Chrome. Investigate whether we can stream clipboard deltas via mutation observers for a closer UX.
diff --git a/docs/configuration.md b/docs/configuration.md
index 85bb39be2..ab58376e4 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -78,7 +78,7 @@ CLI flags → `config.json` → environment → built-in defaults.
 - `sessionRetentionHours` controls the default value for `--retain-hours`. When unset, `ORACLE_RETAIN_HOURS` (if present) becomes the fallback, and the CLI flag still wins over both.
 - `ORACLE_MAX_FILE_SIZE_BYTES` overrides `maxFileSizeBytes` when set. Oracle validates it as a positive integer number of bytes before reading any `--file` inputs.
 - `browser.chatgptUrl` accepts either the root ChatGPT URL (`https://chatgpt.com/`) or a folder/workspace URL (e.g., `https://chatgpt.com/g/.../project`); `browser.url` remains as a legacy alias.
-- Browser automation defaults can be set under `browser.*`, including `browser.manualLogin`, `browser.manualLoginProfileDir`, and `browser.thinkingTime` (CLI override: `--browser-thinking-time`). On Windows, `browser.manualLogin` defaults to `true` when omitted.
+- Browser automation defaults can be set under `browser.*`, including `browser.manualLogin`, `browser.manualLoginProfileDir`, `browser.thinkingTime`, and `browser.attachRunning`. On Windows, `browser.manualLogin` defaults to `true` when omitted.
 
 If the config is missing or invalid, Oracle falls back to defaults and prints a warning for parse errors.
 
diff --git a/docs/manual-tests.md b/docs/manual-tests.md
index 6cf5d6d21..8dd559216 100644
--- a/docs/manual-tests.md
+++ b/docs/manual-tests.md
@@ -193,6 +193,22 @@ Run this whenever you touch CDP connection logic (remote chrome lifecycle, attac
 
 Capture the pass/fail result (include the helper’s log snippet) in your PR description alongside other manual browser tests.
 
+### Attach-running smoke test
+
+Run this whenever you touch the local attach path (`--browser-attach-running`) or the direct browser websocket bootstrap.
+
+1. Start or reuse a local signed-in Chrome with DevTools access available. If you want an explicit local endpoint, launch Chrome with `--remote-debugging-port=9222`.
+2. Run Oracle against the running browser:
+   ```bash
+   pnpm run oracle -- --engine browser \
+     --browser-attach-running \
+     --model "GPT-5.2" \
+     --prompt "Give me two short markdown bullets about browser tabs"
+   ```
+   If the browser’s remote-debugging UI shows a different local port, rerun with `--remote-chrome <host:port>` in addition to `--browser-attach-running`.
+3. Verify Oracle opens a fresh tab in the existing browser, returns the answer, and closes only that Oracle-owned tab afterward.
+4. Reattach sanity check: repeat with a very short timeout if needed, then run `oracle session <id>` and confirm Oracle can reconnect to the saved tab/conversation.
+
 ## Chrome DevTools / MCP Debugging
 
 Use this when you need to inspect the live ChatGPT composer (DOM state, markdown text, screenshots, etc.). For smaller ad‑hoc pokes, you can often rely on `pnpm tsx scripts/browser-tools.ts …` instead.
@@ -227,6 +243,7 @@ Use this when you need to inspect the live ChatGPT composer (DOM state, markdown
      }
      ```
    - Once the server prints `chrome-devtools-mcp exposes…`, you can list/call tools via `mcporter`.
+   - Oracle’s attach-running mode no longer depends on MCP at runtime; `mcporter` remains useful here for manual inspection only.
 
 4. **Interact & capture**
    - Use MCP tools (`click`, `evaluate_js`, `screenshot`, etc.) to debug the composer contents.
diff --git a/src/browser/attachRunning.ts b/src/browser/attachRunning.ts
new file mode 100644
index 000000000..06c3713f9
--- /dev/null
+++ b/src/browser/attachRunning.ts
@@ -0,0 +1,57 @@
+import type { BrowserLogger, ResolvedBrowserConfig } from "./types.js";
+import {
+  discoverDevToolsActivePortCandidates,
+  type DevToolsActivePortCandidate,
+} from "./detect.js";
+
+export interface AttachRunningConnectionInfo {
+  host: string;
+  port: number;
+  browserWSEndpoint: string;
+  profileRoot: string;
+}
+
+export async function resolveAttachRunningConnection(
+  config: Pick<ResolvedBrowserConfig, "chromePath" | "remoteChrome">,
+  logger: BrowserLogger,
+): Promise<AttachRunningConnectionInfo> {
+  const host = config.remoteChrome?.host ?? "127.0.0.1";
+  const port = config.remoteChrome?.port ?? 9222;
+  if (config.chromePath) {
+    logger("Note: --browser-chrome-path is ignored when --browser-attach-running is enabled.");
+  }
+
+  logger(
+    config.remoteChrome
+      ? `Using explicit attach-running target ${host}:${port}.`
+      : `Using default attach-running target ${host}:${port}.`,
+  );
+
+  const candidates = (await discoverDevToolsActivePortCandidates({ host }))
+    .filter((candidate) => candidate.port === port)
+    .sort(compareDevToolsCandidates);
+
+  if (candidates.length === 0) {
+    throw new Error(
+      `No running browser with attach metadata matched ${host}:${port}. Enable remote debugging in chrome://inspect/#remote-debugging first.`,
+    );
+  }
+  const candidate = candidates[0];
+  logger(`Selected attach-running browser metadata from ${candidate.path}`);
+  return {
+    host,
+    port: candidate.port,
+    browserWSEndpoint: candidate.browserWSEndpoint,
+    profileRoot: candidate.profileRoot,
+  };
+}
+
+function compareDevToolsCandidates(
+  left: DevToolsActivePortCandidate,
+  right: DevToolsActivePortCandidate,
+): number {
+  if (right.mtimeMs !== left.mtimeMs) {
+    return right.mtimeMs - left.mtimeMs;
+  }
+  return left.path.localeCompare(right.path);
+}
diff --git a/src/browser/chromeLifecycle.ts b/src/browser/chromeLifecycle.ts
index 51134f0f6..6aff60779 100644
--- a/src/browser/chromeLifecycle.ts
+++ b/src/browser/chromeLifecycle.ts
@@ -163,7 +163,19 @@ export async function connectToRemoteChrome(
   port: number,
   logger: BrowserLogger,
   targetUrl?: string,
+  browserWSEndpoint?: string,
+  options?: {
+    approvalWaitMs?: number;
+  },
 ): Promise<RemoteChromeConnection> {
+  if (browserWSEndpoint) {
+    return await connectToRemoteChromeTarget(host, port, logger, {
+      browserWSEndpoint,
+      targetUrl: targetUrl ?? "about:blank",
+      closeTargetOnDispose: true,
+      approvalWaitMs: options?.approvalWaitMs,
+    });
+  }
   if (targetUrl) {
     const targetConnection = await connectToNewTarget(host, port, targetUrl, logger, {
       opened: () => `Opened dedicated remote Chrome tab targeting ${targetUrl}`,
@@ -175,12 +187,24 @@ export async function connectToRemoteChrome(
         `Failed to close unused remote Chrome tab ${targetId}: ${message}`,
     });
     if (targetConnection) {
-      return { client: targetConnection.client, targetId: targetConnection.targetId };
+      return {
+        client: targetConnection.client,
+        targetId: targetConnection.targetId,
+        close: async () => {
+          await targetConnection.client.close().catch(() => undefined);
+          await closeRemoteChromeTarget(host, port, targetConnection.targetId, logger);
+        },
+      };
     }
   }
   const fallbackClient = await CDP({ host, port });
   logger(`Connected to remote Chrome DevTools protocol at ${host}:${port}`);
-  return { client: fallbackClient };
+  return {
+    client: fallbackClient,
+    close: async () => {
+      await fallbackClient.close().catch(() => undefined);
+    },
+  };
 }
 
 export async function closeRemoteChromeTarget(
@@ -206,6 +230,8 @@ export async function closeRemoteChromeTarget(
 export interface RemoteChromeConnection {
   client: ChromeClient;
   targetId?: string;
+  browserWSEndpoint?: string;
+  close: () => Promise<void>;
 }
 
 export interface IsolatedTabConnection {
@@ -220,6 +246,137 @@ interface TargetConnectMessages {
   closeFailed: (targetId: string, message: string) => string;
 }
 
+export interface RemoteTargetInfo {
+  targetId?: string;
+  type?: string;
+  url?: string;
+}
+
+export async function listRemoteChromeTargets(options: {
+  host: string;
+  port: number;
+  browserWSEndpoint?: string;
+}): Promise<RemoteTargetInfo[]> {
+  if (!options.browserWSEndpoint) {
+    const targets = await CDP.List({ host: options.host, port: options.port });
+    return targets as unknown as RemoteTargetInfo[];
+  }
+  const browser = await CDP({ target: options.browserWSEndpoint, local: true });
+  try {
+    const result = await browser.Target.getTargets();
+    return (result.targetInfos ?? []).map((target) => ({
+      targetId: target.targetId,
+      type: target.type,
+      url: target.url,
+    }));
+  } finally {
+    await browser.close().catch(() => undefined);
+  }
+}
+
+export async function connectToRemoteChromeTarget(
+  host: string,
+  port: number,
+  logger: BrowserLogger,
+  options: {
+    targetId?: string;
+    targetUrl?: string;
+    browserWSEndpoint?: string;
+    closeTargetOnDispose?: boolean;
+    approvalWaitMs?: number;
+  },
+): Promise<RemoteChromeConnection> {
+  if (!options.browserWSEndpoint) {
+    const client = await CDP({ host, port, target: options.targetId });
+    return {
+      client,
+      targetId: options.targetId,
+      close: async () => {
+        await client.close().catch(() => undefined);
+      },
+    };
+  }
+
+  const browser = await connectToBrowserWebSocket(
+    host,
+    port,
+    options.browserWSEndpoint,
+    logger,
+    options.approvalWaitMs,
+  );
+  let targetId = options.targetId;
+  try {
+    if (!targetId) {
+      const created = await browser.Target.createTarget({
+        url: options.targetUrl ?? "about:blank",
+      });
+      targetId = created.targetId;
+      logger(`Opened dedicated remote Chrome tab targeting ${options.targetUrl ?? "about:blank"}`);
+    }
+    const attached = await browser.Target.attachToTarget({ targetId, flatten: true });
+    const client = createSessionBoundChromeClient(browser, attached.sessionId);
+    return {
+      client,
+      targetId,
+      browserWSEndpoint: options.browserWSEndpoint,
+      close: async () => {
+        await browser.Target.detachFromTarget({ sessionId: attached.sessionId }).catch(
+          () => undefined,
+        );
+        if (options.closeTargetOnDispose && targetId) {
+          await browser.Target.closeTarget({ targetId }).catch(() => undefined);
+        }
+        await browser.close().catch(() => undefined);
+      },
+    };
+  } catch (error) {
+    await browser.close().catch(() => undefined);
+    throw error;
+  }
+}
+
+async function connectToBrowserWebSocket(
+  host: string,
+  port: number,
+  browserWSEndpoint: string,
+  logger: BrowserLogger,
+  approvalWaitMs?: number,
+): Promise<ChromeClient> {
+  const connectPromise = CDP({ target: browserWSEndpoint, local: true }) as Promise<ChromeClient>;
+  if (!approvalWaitMs || approvalWaitMs <= 0) {
+    return await connectPromise;
+  }
+
+  logger(`Waiting for Chrome remote debugging approval for ${host}:${port}...`);
+
+  let timeoutId: NodeJS.Timeout | null = null;
+  try {
+    return await Promise.race([
+      connectPromise,
+      new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(
+            new Error(
+              `Oracle waited ${formatApprovalWait(approvalWaitMs)} for Chrome remote debugging approval at ${host}:${port}. Allow the Chrome prompt or retry after toggling remote debugging.`,
+            ),
+          );
+        }, approvalWaitMs);
+      }),
+    ]);
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+function formatApprovalWait(waitMs: number): string {
+  if (waitMs % 1000 === 0) {
+    return `${waitMs / 1000}s`;
+  }
+  return `${waitMs}ms`;
+}
+
 async function connectToNewTarget(
   host: string,
   port: number,
@@ -252,6 +409,66 @@ async function connectToNewTarget(
   return null;
 }
 
+function createSessionBoundChromeClient(browser: ChromeClient, sessionId: string): ChromeClient {
+  const browserWithEvents = browser as ChromeClient & {
+    on: (event: string, listener: (...args: unknown[]) => void) => void;
+    once: (event: string, listener: (...args: unknown[]) => void) => void;
+    off?: (event: string, listener: (...args: unknown[]) => void) => void;
+    removeListener: (event: string, listener: (...args: unknown[]) => void) => void;
+  };
+  const bindDomain = <T extends object>(domainName: string): T => {
+    const domain = (browser as unknown as Record<string, Record<string, unknown>>)[domainName] as
+      | Record<string, unknown>
+      | undefined;
+    const eventName = (name: string) => `${domainName}.${name}.${sessionId}`;
+    return new Proxy((domain ?? {}) as T, {
+      get(target, prop, receiver) {
+        if (prop === "on") {
+          return (name: string, listener: (...args: unknown[]) => void) => {
+            const domainEvent = (target as Record<string, unknown>)[name];
+            if (typeof domainEvent === "function") {
+              return (domainEvent as (...args: unknown[]) => unknown)(sessionId, listener);
+            }
+            browserWithEvents.on(eventName(name), listener);
+            return () => browserWithEvents.removeListener(eventName(name), listener);
+          };
+        }
+        if (prop === "off" || prop === "removeListener") {
+          return (name: string, listener: (...args: unknown[]) => void) => {
+            const off =
+              browserWithEvents.off ?? browserWithEvents.removeListener.bind(browserWithEvents);
+            off(eventName(name), listener);
+          };
+        }
+        const value = Reflect.get(target, prop, receiver);
+        if (typeof value !== "function") {
+          return value;
+        }
+        return (...args: unknown[]) =>
+          (value as (...callArgs: unknown[]) => unknown)(...args, sessionId);
+      },
+    });
+  };
+
+  return {
+    ...browser,
+    Network: bindDomain("Network"),
+    Page: bindDomain("Page"),
+    Runtime: bindDomain("Runtime"),
+    Input: bindDomain("Input"),
+    DOM: bindDomain("DOM"),
+    on: browserWithEvents.on.bind(browserWithEvents),
+    once: browserWithEvents.once.bind(browserWithEvents),
+    off:
+      browserWithEvents.off?.bind(browserWithEvents) ??
+      browserWithEvents.removeListener.bind(browserWithEvents),
+    removeListener: browserWithEvents.removeListener.bind(browserWithEvents),
+    close: async () => {
+      await browser.Target.detachFromTarget({ sessionId }).catch(() => undefined);
+    },
+  } as ChromeClient;
+}
+
 export async function connectWithNewTab(
   port: number,
   logger: BrowserLogger,
diff --git a/src/browser/config.ts b/src/browser/config.ts
index a0c278e20..f4b3360d2 100644
--- a/src/browser/config.ts
+++ b/src/browser/config.ts
@@ -9,6 +9,7 @@ export const DEFAULT_BROWSER_CONFIG: ResolvedBrowserConfig = {
   chromeProfile: null,
   chromePath: null,
   chromeCookiePath: null,
+  attachRunning: false,
   url: CHATGPT_URL,
   chatgptUrl: CHATGPT_URL,
   timeoutMs: 1_200_000,
@@ -34,6 +35,8 @@ export const DEFAULT_BROWSER_CONFIG: ResolvedBrowserConfig = {
   debug: false,
   allowCookieErrors: false,
   remoteChrome: null,
+  remoteChromeBrowserWSEndpoint: null,
+  remoteChromeProfileRoot: null,
   manualLogin: false,
   manualLoginProfileDir: null,
   manualLoginCookieSync: false,
@@ -110,9 +113,14 @@ export function resolveBrowserConfig(
     chromeProfile: config?.chromeProfile ?? DEFAULT_BROWSER_CONFIG.chromeProfile,
     chromePath: config?.chromePath ?? DEFAULT_BROWSER_CONFIG.chromePath,
     chromeCookiePath: config?.chromeCookiePath ?? DEFAULT_BROWSER_CONFIG.chromeCookiePath,
+    attachRunning: config?.attachRunning ?? DEFAULT_BROWSER_CONFIG.attachRunning,
     debug: config?.debug ?? DEFAULT_BROWSER_CONFIG.debug,
     allowCookieErrors:
       config?.allowCookieErrors ?? envAllowCookieErrors ?? DEFAULT_BROWSER_CONFIG.allowCookieErrors,
+    remoteChromeBrowserWSEndpoint:
+      config?.remoteChromeBrowserWSEndpoint ?? DEFAULT_BROWSER_CONFIG.remoteChromeBrowserWSEndpoint,
+    remoteChromeProfileRoot:
+      config?.remoteChromeProfileRoot ?? DEFAULT_BROWSER_CONFIG.remoteChromeProfileRoot,
     thinkingTime: config?.thinkingTime,
     manualLogin,
     manualLoginProfileDir: manualLogin ? resolvedProfileDir : null,
diff --git a/src/browser/detect.ts b/src/browser/detect.ts
index 7f2785213..3bf5f351a 100644
--- a/src/browser/detect.ts
+++ b/src/browser/detect.ts
@@ -1,8 +1,27 @@
 import fs from "node:fs/promises";
+import type { Dirent, Stats } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { Launcher } from "chrome-launcher";
 
+export type AttachRunningBrowserFamily = "chrome" | "chromium" | "edge" | "brave";
+
+export interface AttachRunningProfileRoot {
+  family: AttachRunningBrowserFamily;
+  root: string;
+}
+
+export interface DevToolsActivePortInfo {
+  port: number;
+  browserWSEndpoint: string;
+  path: string;
+}
+
+export interface DevToolsActivePortCandidate extends DevToolsActivePortInfo {
+  profileRoot: string;
+  mtimeMs: number;
+}
+
 export async function detectChromeBinary(): Promise<{ path: string | null }> {
   const envPath = (process.env.CHROME_PATH ?? "").trim();
   if (envPath) {
@@ -17,7 +36,7 @@ export async function detectChromeBinary(): Promise<{ path: string | null }> {
     return { path: launcherDetected };
   }
 
-  const candidates = platformChromeCandidates();
+  const candidates = platformChromeCandidates(process.platform, os.homedir());
   for (const candidate of candidates.absolutePaths) {
     if (await isExecutable(candidate)) {
       return { path: candidate };
@@ -42,9 +61,9 @@ export async function detectChromeCookieDb({
     return null;
   }
 
-  const roots = platformProfileRoots();
+  const roots = resolveAttachRunningProfileRoots();
   for (const root of roots) {
-    const dir = path.join(root, profileName);
+    const dir = path.join(root.root, profileName);
     const direct = path.join(dir, "Cookies");
     if (await isFile(direct)) return direct;
     const network = path.join(dir, "Network", "Cookies");
@@ -54,8 +73,195 @@ export async function detectChromeCookieDb({
   return null;
 }
 
-function platformChromeCandidates(): { absolutePaths: string[]; binaryNames: string[] } {
-  if (process.platform === "linux") {
+export function resolveAttachRunningProfileRoots(
+  platform = process.platform,
+  homeDir = os.homedir(),
+): AttachRunningProfileRoot[] {
+  if (platform === "darwin") {
+    return [
+      {
+        family: "chrome",
+        root: path.join(homeDir, "Library", "Application Support", "Google", "Chrome"),
+      },
+      {
+        family: "chromium",
+        root: path.join(homeDir, "Library", "Application Support", "Chromium"),
+      },
+      {
+        family: "edge",
+        root: path.join(homeDir, "Library", "Application Support", "Microsoft Edge"),
+      },
+      {
+        family: "brave",
+        root: path.join(
+          homeDir,
+          "Library",
+          "Application Support",
+          "BraveSoftware",
+          "Brave-Browser",
+        ),
+      },
+    ];
+  }
+  if (platform === "linux") {
+    return [
+      { family: "chrome", root: path.join(homeDir, ".config", "google-chrome") },
+      { family: "chromium", root: path.join(homeDir, ".config", "chromium") },
+      { family: "edge", root: path.join(homeDir, ".config", "microsoft-edge") },
+      {
+        family: "brave",
+        root: path.join(homeDir, ".config", "BraveSoftware", "Brave-Browser"),
+      },
+      { family: "chromium", root: path.join(homeDir, "snap", "chromium", "common", "chromium") },
+      { family: "chromium", root: path.join(homeDir, "snap", "chromium", "current", "chromium") },
+    ];
+  }
+  if (platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA ?? path.join(homeDir, "AppData", "Local");
+    return [
+      {
+        family: "chrome",
+        root: path.join(localAppData, "Google", "Chrome", "User Data"),
+      },
+      {
+        family: "chromium",
+        root: path.join(localAppData, "Chromium", "User Data"),
+      },
+      {
+        family: "edge",
+        root: path.join(localAppData, "Microsoft", "Edge", "User Data"),
+      },
+      {
+        family: "brave",
+        root: path.join(localAppData, "BraveSoftware", "Brave-Browser", "User Data"),
+      },
+    ];
+  }
+  return [];
+}
+
+export function resolveDevToolsActivePortDiscoveryRoots(
+  platform = process.platform,
+  homeDir = os.homedir(),
+): string[] {
+  if (platform === "darwin") {
+    return [path.join(homeDir, "Library", "Application Support")];
+  }
+  if (platform === "linux") {
+    return [path.join(homeDir, ".config"), path.join(homeDir, "snap")];
+  }
+  if (platform === "win32") {
+    return [process.env.LOCALAPPDATA ?? path.join(homeDir, "AppData", "Local")];
+  }
+  return [];
+}
+
+export function inferAttachRunningBrowserFamily(
+  chromePath?: string | null,
+): AttachRunningBrowserFamily | null {
+  const normalized = chromePath?.trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  if (normalized.includes("microsoft edge") || normalized.includes("msedge")) {
+    return "edge";
+  }
+  if (normalized.includes("brave")) {
+    return "brave";
+  }
+  if (normalized.includes("chromium")) {
+    return "chromium";
+  }
+  if (normalized.includes("chrome")) {
+    return "chrome";
+  }
+  return null;
+}
+
+export function parseDevToolsActivePort(
+  raw: string,
+  options: {
+    host?: string;
+  } = {},
+): { port: number; browserWSEndpoint: string } {
+  const host = formatWebSocketHost(options.host ?? "127.0.0.1");
+  const [rawPort, rawBrowserPath] = raw.split(/\r?\n/u);
+  const port = Number.parseInt(rawPort?.trim() ?? "", 10);
+  if (!Number.isFinite(port) || port <= 0 || port > 65_535) {
+    throw new Error("DevToolsActivePort did not contain a valid port.");
+  }
+  const browserPath = rawBrowserPath?.trim() || "/devtools/browser";
+  const normalizedPath = browserPath.startsWith("/") ? browserPath : `/${browserPath}`;
+  return {
+    port,
+    browserWSEndpoint: `ws://${host}:${port}${normalizedPath}`,
+  };
+}
+
+export async function readDevToolsActivePortInfo(
+  profileRoot: string,
+  options: {
+    host?: string;
+  } = {},
+): Promise<DevToolsActivePortInfo | null> {
+  const candidates = [
+    path.join(profileRoot, "DevToolsActivePort"),
+    path.join(profileRoot, "Default", "DevToolsActivePort"),
+  ];
+  for (const candidate of candidates) {
+    try {
+      const raw = await fs.readFile(candidate, "utf8");
+      const parsed = parseDevToolsActivePort(raw, options);
+      return { ...parsed, path: candidate };
+    } catch {
+      // ignore missing/unreadable candidates
+    }
+  }
+  return null;
+}
+
+export async function discoverDevToolsActivePortCandidates(
+  options: {
+    host?: string;
+    platform?: NodeJS.Platform;
+    homeDir?: string;
+    maxDepth?: number;
+  } = {},
+): Promise<DevToolsActivePortCandidate[]> {
+  const { host, platform = process.platform, homeDir = os.homedir(), maxDepth = 6 } = options;
+  const roots = resolveDevToolsActivePortDiscoveryRoots(platform, homeDir);
+  const candidates: DevToolsActivePortCandidate[] = [];
+  const seenPaths = new Set<string>();
+
+  for (const root of roots) {
+    await walkForDevToolsActivePort(root, maxDepth, async (candidatePath, stat) => {
+      if (seenPaths.has(candidatePath)) {
+        return;
+      }
+      seenPaths.add(candidatePath);
+      try {
+        const raw = await fs.readFile(candidatePath, "utf8");
+        const parsed = parseDevToolsActivePort(raw, { host });
+        candidates.push({
+          ...parsed,
+          path: candidatePath,
+          profileRoot: deriveDevToolsProfileRoot(candidatePath),
+          mtimeMs: Number(stat.mtimeMs),
+        });
+      } catch {
+        // ignore unreadable or malformed DevToolsActivePort files
+      }
+    });
+  }
+
+  return candidates;
+}
+
+function platformChromeCandidates(
+  platform = process.platform,
+  homeDir = os.homedir(),
+): { absolutePaths: string[]; binaryNames: string[] } {
+  if (platform === "linux") {
     return {
       binaryNames: [
         "google-chrome",
@@ -84,7 +290,7 @@ function platformChromeCandidates(): { absolutePaths: string[]; binaryNames: str
       ],
     };
   }
-  if (process.platform === "darwin") {
+  if (platform === "darwin") {
     return {
       binaryNames: [],
       absolutePaths: [
@@ -95,10 +301,10 @@ function platformChromeCandidates(): { absolutePaths: string[]; binaryNames: str
       ],
     };
   }
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
     const programFilesX86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
-    const localAppData = process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local");
+    const localAppData = process.env.LOCALAPPDATA ?? path.join(homeDir, "AppData", "Local");
     return {
       binaryNames: [],
       absolutePaths: [
@@ -113,32 +319,6 @@ function platformChromeCandidates(): { absolutePaths: string[]; binaryNames: str
   return { binaryNames: [], absolutePaths: [] };
 }
 
-function platformProfileRoots(): string[] {
-  const home = os.homedir();
-  if (process.platform === "darwin") {
-    return [
-      path.join(home, "Library", "Application Support", "Google", "Chrome"),
-      path.join(home, "Library", "Application Support", "Chromium"),
-      path.join(home, "Library", "Application Support", "Microsoft Edge"),
-      path.join(home, "Library", "Application Support", "BraveSoftware", "Brave-Browser"),
-    ];
-  }
-  if (process.platform === "linux") {
-    return [
-      path.join(home, ".config", "google-chrome"),
-      path.join(home, ".config", "google-chrome-beta"),
-      path.join(home, ".config", "google-chrome-unstable"),
-      path.join(home, ".config", "chromium"),
-      path.join(home, ".config", "microsoft-edge"),
-      path.join(home, ".config", "BraveSoftware", "Brave-Browser"),
-      // Snap Chromium profiles
-      path.join(home, "snap", "chromium", "common", "chromium"),
-      path.join(home, "snap", "chromium", "current", "chromium"),
-    ];
-  }
-  return [];
-}
-
 async function isExecutable(candidate: string): Promise<boolean> {
   try {
     const stat = await fs.stat(candidate);
@@ -173,3 +353,59 @@ async function findOnPath(names: string[]): Promise<string | null> {
   }
   return null;
 }
+
+function deriveDevToolsProfileRoot(activePortPath: string): string {
+  const parentDir = path.dirname(activePortPath);
+  if (path.basename(parentDir).toLowerCase() === "default") {
+    return path.dirname(parentDir);
+  }
+  return parentDir;
+}
+
+function formatWebSocketHost(host: string): string {
+  if (host.includes(":") && !host.startsWith("[") && !host.endsWith("]")) {
+    return `[${host}]`;
+  }
+  return host;
+}
+
+async function walkForDevToolsActivePort(
+  root: string,
+  maxDepth: number,
+  onFile: (candidatePath: string, stat: Stats) => Promise<void>,
+): Promise<void> {
+  const stack: Array<{ dir: string; depth: number }> = [{ dir: root, depth: 0 }];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current) {
+      continue;
+    }
+    let entries: Dirent[];
+    try {
+      entries = await fs.readdir(current.dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const candidatePath = path.join(current.dir, entry.name);
+      if (entry.isSymbolicLink()) {
+        continue;
+      }
+      if (entry.isFile()) {
+        if (entry.name !== "DevToolsActivePort") {
+          continue;
+        }
+        try {
+          const stat = await fs.stat(candidatePath);
+          await onFile(candidatePath, stat);
+        } catch {
+          // ignore unreadable candidates
+        }
+        continue;
+      }
+      if (entry.isDirectory() && current.depth < maxDepth) {
+        stack.push({ dir: candidatePath, depth: current.depth + 1 });
+      }
+    }
+  }
+}
diff --git a/src/browser/index.ts b/src/browser/index.ts
index b89cd19e9..ec1b73b0a 100644
--- a/src/browser/index.ts
+++ b/src/browser/index.ts
@@ -9,13 +9,13 @@ import type {
   BrowserLogger,
   ChromeClient,
   BrowserAttachment,
+  ResolvedBrowserConfig,
 } from "./types.js";
 import {
   launchChrome,
   registerTerminationHooks,
   hideChromeWindow,
   connectToRemoteChrome,
-  closeRemoteChromeTarget,
   connectWithNewTab,
   closeTab,
 } from "./chromeLifecycle.js";
@@ -59,6 +59,7 @@ import {
 } from "./profileState.js";
 import { runProviderSubmissionFlow } from "./providerDomFlow.js";
 import { chatgptDomProvider } from "./providers/index.js";
+import { resolveAttachRunningConnection } from "./attachRunning.js";
 
 export type { BrowserAutomationConfig, BrowserRunOptions, BrowserRunResult } from "./types.js";
 export { CHATGPT_URL, DEFAULT_MODEL_STRATEGY, DEFAULT_MODEL_TARGET } from "./constants.js";
@@ -77,6 +78,21 @@ export function shouldPreserveBrowserOnErrorForTest(error: unknown, headless: bo
   return shouldPreserveBrowserOnError(error, headless);
 }
 
+function listIgnoredRemoteChromeFlags(config: {
+  attachRunning?: ResolvedBrowserConfig["attachRunning"];
+  headless?: ResolvedBrowserConfig["headless"];
+  hideWindow?: ResolvedBrowserConfig["hideWindow"];
+  keepBrowser?: ResolvedBrowserConfig["keepBrowser"];
+  chromePath?: ResolvedBrowserConfig["chromePath"];
+}): string[] {
+  return [
+    config.headless ? "--browser-headless" : null,
+    config.hideWindow ? "--browser-hide-window" : null,
+    config.keepBrowser ? "--browser-keep-browser" : null,
+    !config.attachRunning && config.chromePath ? "--browser-chrome-path" : null,
+  ].filter((value): value is string => Boolean(value));
+}
+
 export async function runBrowserMode(options: BrowserRunOptions): Promise<BrowserRunResult> {
   const promptText = options.prompt?.trim();
   if (!promptText) {
@@ -128,6 +144,16 @@ export async function runBrowserMode(options: BrowserRunOptions): Promise<Browse
     );
   }
 
+  if (config.attachRunning) {
+    const attached = await resolveAttachRunningConnection(config, logger);
+    config = {
+      ...config,
+      remoteChrome: { host: attached.host, port: attached.port },
+      remoteChromeBrowserWSEndpoint: attached.browserWSEndpoint,
+      remoteChromeProfileRoot: attached.profileRoot,
+    };
+  }
+
   if (!config.remoteChrome && !config.manualLogin) {
     const preferredPort = config.debugPort ?? DEFAULT_DEBUG_PORT;
     const availablePort = await pickAvailableDebugPort(preferredPort, logger);
@@ -142,11 +168,9 @@ export async function runBrowserMode(options: BrowserRunOptions): Promise<Browse
   // Remote Chrome mode - connect to existing browser
   if (config.remoteChrome) {
     // Warn about ignored local-only options
-    if (config.headless || config.hideWindow || config.keepBrowser || config.chromePath) {
-      logger(
-        "Note: --remote-chrome ignores local Chrome flags " +
-          "(--browser-headless, --browser-hide-window, --browser-keep-browser, --browser-chrome-path).",
-      );
+    const ignoredFlags = listIgnoredRemoteChromeFlags(config);
+    if (ignoredFlags.length > 0) {
+      logger(`Note: --remote-chrome ignores local Chrome flags (${ignoredFlags.join(", ")}).`);
     }
 
     return runRemoteBrowserMode(promptText, attachments, config, logger, options);
@@ -1282,6 +1306,8 @@ async function runRemoteBrowserMode(
       await runtimeHintCb({
         chromePort: port,
         chromeHost: host,
+        chromeBrowserWSEndpoint: browserWSEndpoint,
+        chromeProfileRoot,
         chromeTargetId: remoteTargetId ?? undefined,
         tabUrl: lastUrl,
         controllerPid: process.pid,
@@ -1298,9 +1324,14 @@ async function runRemoteBrowserMode(
   let connectionClosedUnexpectedly = false;
   let stopThinkingMonitor: (() => void) | null = null;
   let removeDialogHandler: (() => void) | null = null;
+  let connection: Awaited<ReturnType<typeof connectToRemoteChrome>> | null = null;
+  const browserWSEndpoint = config.remoteChromeBrowserWSEndpoint ?? undefined;
+  const chromeProfileRoot = config.remoteChromeProfileRoot ?? undefined;
 
   try {
-    const connection = await connectToRemoteChrome(host, port, logger, config.url);
+    connection = await connectToRemoteChrome(host, port, logger, config.url, browserWSEndpoint, {
+      approvalWaitMs: config.attachRunning && browserWSEndpoint ? 20_000 : undefined,
+    });
     client = connection.client;
     remoteTargetId = connection.targetId ?? null;
     await emitRuntimeHint();
@@ -1526,6 +1557,8 @@ async function runRemoteBrowserMode(
             runtime: {
               chromeHost: host,
               chromePort: port,
+              chromeBrowserWSEndpoint: browserWSEndpoint,
+              chromeProfileRoot,
               chromeTargetId: remoteTargetId ?? undefined,
               tabUrl: lastUrl,
               conversationId: lastUrl ? extractConversationIdFromUrl(lastUrl) : undefined,
@@ -1572,6 +1605,8 @@ async function runRemoteBrowserMode(
           const runtime = {
             chromePort: port,
             chromeHost: host,
+            chromeBrowserWSEndpoint: browserWSEndpoint,
+            chromeProfileRoot,
             chromeTargetId: remoteTargetId ?? undefined,
             tabUrl: lastUrl,
             conversationId: lastUrl ? extractConversationIdFromUrl(lastUrl) : undefined,
@@ -1715,9 +1750,12 @@ async function runRemoteBrowserMode(
       tookMs: durationMs,
       answerTokens,
       answerChars,
+      browserTransport: "cdp",
       chromePid: undefined,
       chromePort: port,
       chromeHost: host,
+      chromeBrowserWSEndpoint: browserWSEndpoint,
+      chromeProfileRoot,
       userDataDir: undefined,
       chromeTargetId: remoteTargetId ?? undefined,
       tabUrl: lastUrl,
@@ -1742,6 +1780,8 @@ async function runRemoteBrowserMode(
       runtime: {
         chromeHost: host,
         chromePort: port,
+        chromeBrowserWSEndpoint: browserWSEndpoint,
+        chromeProfileRoot,
         chromeTargetId: remoteTargetId ?? undefined,
         tabUrl: lastUrl,
         controllerPid: process.pid,
@@ -1749,14 +1789,13 @@ async function runRemoteBrowserMode(
     });
   } finally {
     try {
-      if (!connectionClosedUnexpectedly && client) {
-        await client.close();
+      if (!connectionClosedUnexpectedly && connection) {
+        await connection.close();
       }
     } catch {
       // ignore
     }
     removeDialogHandler?.();
-    await closeRemoteChromeTarget(host, port, remoteTargetId ?? undefined, logger);
     // Don't kill remote Chrome - it's not ours to manage
     const totalSeconds = (Date.now() - startedAt) / 1000;
     logger(`Remote session complete • ${totalSeconds.toFixed(1)}s total`);
@@ -1765,6 +1804,11 @@ async function runRemoteBrowserMode(
 
 export { estimateTokenCount } from "./utils.js";
 export { resolveBrowserConfig, DEFAULT_BROWSER_CONFIG } from "./config.js";
+
+// biome-ignore lint/style/useNamingConvention: test-only export used in vitest suite
+export const __test__ = {
+  listIgnoredRemoteChromeFlags,
+};
 export { syncCookies } from "./cookies.js";
 export {
   navigateToChatGPT,
diff --git a/src/browser/reattach.ts b/src/browser/reattach.ts
index 1c683f20e..4349974f4 100644
--- a/src/browser/reattach.ts
+++ b/src/browser/reattach.ts
@@ -12,11 +12,18 @@ import {
   ensurePromptReady,
 } from "./pageActions.js";
 import type { BrowserLogger, ChromeClient } from "./types.js";
-import { launchChrome, connectToChrome, hideChromeWindow } from "./chromeLifecycle.js";
+import {
+  launchChrome,
+  connectToChrome,
+  hideChromeWindow,
+  connectToRemoteChromeTarget,
+  listRemoteChromeTargets,
+} from "./chromeLifecycle.js";
 import { resolveBrowserConfig } from "./config.js";
 import { syncCookies } from "./cookies.js";
 import { CHATGPT_URL } from "./constants.js";
 import { cleanupStaleProfileState } from "./profileState.js";
+import { readDevToolsActivePortInfo } from "./detect.js";
 import {
   pickTarget,
   extractConversationIdFromUrl,
@@ -31,7 +38,6 @@ import {
   alignPromptEchoMarkdown,
   type TargetInfoLite,
 } from "./reattachHelpers.js";
-
 export interface ReattachDeps {
   listTargets?: () => Promise<TargetInfoLite[]>;
   connect?: (options?: unknown) => Promise<ChromeClient>;
@@ -60,27 +66,51 @@ export async function resumeBrowserSession(
     (async (runtimeMeta, configMeta) =>
       resumeBrowserSessionViaNewChrome(runtimeMeta, configMeta, logger, deps));
 
-  if (!runtime.chromePort) {
+  if (!runtime.chromePort && !runtime.chromeBrowserWSEndpoint) {
     logger("No running Chrome detected; reopening browser to locate the session.");
     return recoverSession(runtime, config);
   }
 
-  const host = runtime.chromeHost ?? "127.0.0.1";
   try {
+    const liveRuntime = (await refreshAttachRuntime(runtime).catch(() => runtime)) ?? runtime;
+    const host = liveRuntime.chromeHost ?? "127.0.0.1";
+    const port =
+      liveRuntime.chromePort ?? inferPortFromBrowserWSEndpoint(liveRuntime.chromeBrowserWSEndpoint);
+    const browserWSEndpoint = liveRuntime.chromeBrowserWSEndpoint ?? undefined;
     const listTargets =
       deps.listTargets ??
-      (async () => {
-        const targets = await CDP.List({ host, port: runtime.chromePort as number });
-        return targets as unknown as TargetInfoLite[];
-      });
-    const connect = deps.connect ?? ((options?: unknown) => CDP(options as CDP.Options));
+      (async () =>
+        (await listRemoteChromeTargets({
+          host,
+          port: port ?? 9222,
+          browserWSEndpoint,
+        })) as TargetInfoLite[]);
     const targetList = (await listTargets()) as TargetInfoLite[];
-    const target = pickTarget(targetList, runtime);
-    const client: ChromeClient = (await connect({
-      host,
-      port: runtime.chromePort,
-      target: target?.targetId,
-    })) as unknown as ChromeClient;
+    const target = pickTarget(targetList, liveRuntime);
+    const connection =
+      browserWSEndpoint && !deps.connect
+        ? await connectToRemoteChromeTarget(host, port ?? 9222, logger, {
+            browserWSEndpoint,
+            targetId: target?.targetId,
+            closeTargetOnDispose: false,
+          })
+        : ({
+            client: (await (deps.connect ?? ((options?: unknown) => CDP(options as CDP.Options)))(
+              browserWSEndpoint
+                ? {
+                    target: browserWSEndpoint,
+                    local: true,
+                    targetId: target?.targetId,
+                  }
+                : {
+                    host,
+                    port,
+                    target: target?.targetId,
+                  },
+            )) as unknown as ChromeClient,
+            close: async () => undefined,
+          } as const);
+    const client: ChromeClient = connection.client;
     const { Runtime, DOM } = client;
     if (Runtime?.enable) {
       await Runtime.enable();
@@ -150,13 +180,7 @@ export async function resumeBrowserSession(
       )) ?? recovered.text;
     const aligned = alignPromptEchoMarkdown(recovered.text, markdown, promptEcho, logger);
 
-    if (client && typeof client.close === "function") {
-      try {
-        await client.close();
-      } catch {
-        // ignore
-      }
-    }
+    await connection.close().catch(() => undefined);
 
     return { answerText: aligned.answerText, answerMarkdown: aligned.answerMarkdown };
   } catch (error) {
@@ -168,6 +192,43 @@ export async function resumeBrowserSession(
   }
 }
 
+async function refreshAttachRuntime(
+  runtime: BrowserRuntimeMetadata,
+): Promise<BrowserRuntimeMetadata | null> {
+  if (!runtime.chromeProfileRoot) {
+    return runtime;
+  }
+  const host = runtime.chromeHost ?? "127.0.0.1";
+  const activePort = await readDevToolsActivePortInfo(runtime.chromeProfileRoot, {
+    host,
+  });
+  if (!activePort) {
+    return runtime;
+  }
+  return {
+    ...runtime,
+    chromeHost: host,
+    chromePort: activePort.port,
+    chromeBrowserWSEndpoint: activePort.browserWSEndpoint,
+  };
+}
+
+function inferPortFromBrowserWSEndpoint(browserWSEndpoint?: string): number | undefined {
+  if (!browserWSEndpoint) {
+    return undefined;
+  }
+  try {
+    const parsed = new URL(browserWSEndpoint);
+    const port = Number.parseInt(parsed.port, 10);
+    if (Number.isFinite(port) && port > 0) {
+      return port;
+    }
+  } catch {
+    // ignore malformed ws endpoints and fall back to caller defaults
+  }
+  return undefined;
+}
+
 async function resumeBrowserSessionViaNewChrome(
   runtime: BrowserRuntimeMetadata,
   config: BrowserSessionConfig | undefined,
diff --git a/src/browser/sessionRunner.ts b/src/browser/sessionRunner.ts
index 48e5ebd28..e8531d9d6 100644
--- a/src/browser/sessionRunner.ts
+++ b/src/browser/sessionRunner.ts
@@ -163,10 +163,15 @@ export async function runBrowserSessionExecution(
     usage,
     elapsedMs: browserResult.tookMs,
     runtime: {
+      browserTransport: browserResult.browserTransport,
       chromePid: browserResult.chromePid,
       chromePort: browserResult.chromePort,
       chromeHost: browserResult.chromeHost,
+      chromeBrowserWSEndpoint: browserResult.chromeBrowserWSEndpoint,
+      chromeProfileRoot: browserResult.chromeProfileRoot,
       userDataDir: browserResult.userDataDir,
+      chromeTargetId: browserResult.chromeTargetId,
+      tabUrl: browserResult.tabUrl,
       controllerPid: browserResult.controllerPid ?? process.pid,
     },
     answerText,
diff --git a/src/browser/types.ts b/src/browser/types.ts
index 7c5146726..207554013 100644
--- a/src/browser/types.ts
+++ b/src/browser/types.ts
@@ -22,6 +22,7 @@ export interface BrowserAutomationConfig {
   chromeProfile?: string | null;
   chromePath?: string | null;
   chromeCookiePath?: string | null;
+  attachRunning?: boolean;
   url?: string;
   chatgptUrl?: string | null;
   timeoutMs?: number;
@@ -54,6 +55,8 @@ export interface BrowserAutomationConfig {
   debug?: boolean;
   allowCookieErrors?: boolean;
   remoteChrome?: { host: string; port: number } | null;
+  remoteChromeBrowserWSEndpoint?: string | null;
+  remoteChromeProfileRoot?: string | null;
   manualLogin?: boolean;
   manualLoginProfileDir?: string | null;
   manualLoginCookieSync?: boolean;
@@ -84,9 +87,12 @@ export interface BrowserRunResult {
   tookMs: number;
   answerTokens: number;
   answerChars: number;
+  browserTransport?: "cdp";
   chromePid?: number;
   chromePort?: number;
   chromeHost?: string;
+  chromeBrowserWSEndpoint?: string;
+  chromeProfileRoot?: string;
   userDataDir?: string;
   chromeTargetId?: string;
   tabUrl?: string;
@@ -101,6 +107,8 @@ export type ResolvedBrowserConfig = Required<
     | "chromeCookiePath"
     | "desiredModel"
     | "remoteChrome"
+    | "remoteChromeBrowserWSEndpoint"
+    | "remoteChromeProfileRoot"
     | "thinkingTime"
     | "modelStrategy"
   >
@@ -108,12 +116,15 @@ export type ResolvedBrowserConfig = Required<
   chromeProfile?: string | null;
   chromePath?: string | null;
   chromeCookiePath?: string | null;
+  attachRunning?: boolean;
   desiredModel?: string | null;
   modelStrategy?: BrowserModelStrategy;
   thinkingTime?: ThinkingTimeLevel;
   debugPort?: number | null;
   inlineCookiesSource?: string | null;
   remoteChrome?: { host: string; port: number } | null;
+  remoteChromeBrowserWSEndpoint?: string | null;
+  remoteChromeProfileRoot?: string | null;
   manualLogin?: boolean;
   manualLoginProfileDir?: string | null;
   manualLoginCookieSync?: boolean;
diff --git a/src/cli/browserConfig.ts b/src/cli/browserConfig.ts
index ad2919c44..e4cc2f3a4 100644
--- a/src/cli/browserConfig.ts
+++ b/src/cli/browserConfig.ts
@@ -43,6 +43,7 @@ export interface BrowserFlagOptions {
   browserChromeProfile?: string;
   browserChromePath?: string;
   browserCookiePath?: string;
+  browserAttachRunning?: boolean;
   chatgptUrl?: string;
   browserUrl?: string;
   browserTimeout?: string;
@@ -133,6 +134,11 @@ export async function buildBrowserConfig(
   if (options.remoteChrome) {
     remoteChrome = parseRemoteChromeTarget(options.remoteChrome);
   }
+  const attachRunning = options.browserAttachRunning === true;
+  validateAttachRunningOptions(options, {
+    attachRunning,
+    hasInlineCookies: Boolean(inline?.cookies),
+  });
   const rawUrl = options.chatgptUrl ?? options.browserUrl;
   const url = rawUrl ? normalizeChatgptUrl(rawUrl, CHATGPT_URL) : undefined;
 
@@ -158,6 +164,7 @@ export async function buildBrowserConfig(
     chromeProfile: options.browserChromeProfile ?? DEFAULT_CHROME_PROFILE,
     chromePath: options.browserChromePath ?? null,
     chromeCookiePath: options.browserCookiePath ?? null,
+    attachRunning,
     url,
     debugPort: selectBrowserPort(options),
     timeoutMs: options.browserTimeout
@@ -209,6 +216,40 @@ export async function buildBrowserConfig(
   };
 }
 
+function validateAttachRunningOptions(
+  options: BrowserFlagOptions,
+  {
+    attachRunning,
+    hasInlineCookies,
+  }: {
+    attachRunning: boolean;
+    hasInlineCookies: boolean;
+  },
+): void {
+  if (!attachRunning) {
+    return;
+  }
+  const conflicts = [
+    options.browserChromeProfile ? "--browser-chrome-profile" : null,
+    options.browserCookiePath ? "--browser-cookie-path" : null,
+    options.browserNoCookieSync ? "--browser-no-cookie-sync" : null,
+    options.browserHideWindow ? "--browser-hide-window" : null,
+    options.browserKeepBrowser ? "--browser-keep-browser" : null,
+    options.browserManualLogin ? "--browser-manual-login" : null,
+    options.browserManualLoginProfileDir ? "--browser-manual-login-profile-dir" : null,
+    hasInlineCookies ? "--browser-inline-cookies/--browser-inline-cookies-file" : null,
+    options.browserPort != null || options.browserDebugPort != null
+      ? "--browser-port/--browser-debug-port"
+      : null,
+  ].filter((value): value is string => Boolean(value));
+
+  if (conflicts.length > 0) {
+    throw new Error(
+      `--browser-attach-running cannot be combined with ${conflicts.join(", ")} because attach mode reuses an already-running browser instead of launching and configuring its own Chrome instance.`,
+    );
+  }
+}
+
 function selectBrowserPort(options: BrowserFlagOptions): number | null {
   const candidate = options.browserPort ?? options.browserDebugPort;
   if (candidate === undefined || candidate === null) return null;
diff --git a/src/cli/browserDefaults.ts b/src/cli/browserDefaults.ts
index af854e771..a46078cd5 100644
--- a/src/cli/browserDefaults.ts
+++ b/src/cli/browserDefaults.ts
@@ -9,6 +9,7 @@ export interface BrowserDefaultsOptions {
   browserChromeProfile?: string;
   browserChromePath?: string;
   browserCookiePath?: string;
+  browserAttachRunning?: boolean;
   browserTimeout?: string | number;
   browserInputTimeout?: string | number;
   browserRecheckDelay?: string | number;
@@ -59,6 +60,9 @@ export function applyBrowserDefaultsFromConfig(
   if (isUnset("browserCookiePath") && browser.chromeCookiePath !== undefined) {
     options.browserCookiePath = browser.chromeCookiePath ?? undefined;
   }
+  if (isUnset("browserAttachRunning") && browser.attachRunning !== undefined) {
+    options.browserAttachRunning = browser.attachRunning;
+  }
   if (isUnset("browserUrl") && options.browserUrl === undefined && browser.url !== undefined) {
     options.browserUrl = browser.url;
   }
diff --git a/src/cli/sessionDisplay.ts b/src/cli/sessionDisplay.ts
index e3cf44d95..67703d5a9 100644
--- a/src/cli/sessionDisplay.ts
+++ b/src/cli/sessionDisplay.ts
@@ -162,7 +162,11 @@ export async function attachSession(
   const statusAllowsReattach =
     metadata.status === "running" || (metadata.status === "error" && hasChromeDisconnect);
   const hasFallbackSessionInfo = Boolean(
-    runtime?.chromePort || runtime?.tabUrl || runtime?.conversationId,
+    runtime?.chromePort ||
+    runtime?.chromeBrowserWSEndpoint ||
+    runtime?.chromeProfileRoot ||
+    runtime?.tabUrl ||
+    runtime?.conversationId,
   );
   const canReattach =
     statusAllowsReattach &&
diff --git a/src/config.ts b/src/config.ts
index 5963ef26e..bbc92ce95 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -17,6 +17,7 @@ export interface BrowserConfigDefaults {
   chromeProfile?: string | null;
   chromePath?: string | null;
   chromeCookiePath?: string | null;
+  attachRunning?: boolean;
   chatgptUrl?: string | null;
   url?: string;
   /** Delegate browser automation to a remote `oracle serve` instance (host:port). */
diff --git a/src/sessionManager.ts b/src/sessionManager.ts
index 3f6500cec..c638beefa 100644
--- a/src/sessionManager.ts
+++ b/src/sessionManager.ts
@@ -20,6 +20,7 @@ export interface BrowserSessionConfig {
   chromeProfile?: string | null;
   chromePath?: string | null;
   chromeCookiePath?: string | null;
+  attachRunning?: boolean;
   chatgptUrl?: string | null;
   url?: string;
   timeoutMs?: number;
@@ -60,9 +61,12 @@ export interface BrowserSessionConfig {
 }
 
 export interface BrowserRuntimeMetadata {
+  browserTransport?: "cdp";
   chromePid?: number;
   chromePort?: number;
   chromeHost?: string;
+  chromeBrowserWSEndpoint?: string;
+  chromeProfileRoot?: string;
   userDataDir?: string;
   chromeTargetId?: string;
   tabUrl?: string;
diff --git a/tests/browser/attachRunning.test.ts b/tests/browser/attachRunning.test.ts
new file mode 100644
index 000000000..5c21c3e35
--- /dev/null
+++ b/tests/browser/attachRunning.test.ts
@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import type { BrowserLogger } from "../../src/browser/types.js";
+
+describe("resolveAttachRunningConnection", () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  test("defaults attach-running discovery to 127.0.0.1:9222", async () => {
+    vi.doMock("../../src/browser/detect.js", () => ({
+      discoverDevToolsActivePortCandidates: vi.fn(async () => [
+        {
+          port: 9222,
+          browserWSEndpoint: "ws://127.0.0.1:9222/devtools/browser/default",
+          path: "/profiles/default/DevToolsActivePort",
+          profileRoot: "/profiles/default",
+          mtimeMs: 10,
+        },
+      ]),
+    }));
+
+    const { resolveAttachRunningConnection } = await import("../../src/browser/attachRunning.js");
+    const logger = vi.fn();
+
+    const result = await resolveAttachRunningConnection(
+      { chromePath: null, remoteChrome: undefined },
+      logger,
+    );
+
+    expect(result).toMatchObject({
+      host: "127.0.0.1",
+      port: 9222,
+      browserWSEndpoint: "ws://127.0.0.1:9222/devtools/browser/default",
+      profileRoot: "/profiles/default",
+    });
+    expect(logger).not.toHaveBeenCalledWith(
+      expect.stringContaining("Waiting for Chrome remote debugging approval"),
+    );
+    expect(logger).toHaveBeenCalledWith(
+      "Selected attach-running browser metadata from /profiles/default/DevToolsActivePort",
+    );
+  });
+
+  test("uses remote-chrome as the attach-running hint and prefers the newest candidate", async () => {
+    vi.doMock("../../src/browser/detect.js", () => ({
+      discoverDevToolsActivePortCandidates: vi.fn(async () => [
+        {
+          port: 63332,
+          browserWSEndpoint: "ws://127.0.0.1:63332/devtools/browser/older",
+          path: "/profiles/dia-older/DevToolsActivePort",
+          profileRoot: "/profiles/dia-older",
+          mtimeMs: 5,
+        },
+        {
+          port: 63332,
+          browserWSEndpoint: "ws://127.0.0.1:63332/devtools/browser/newer",
+          path: "/profiles/dia-newer/DevToolsActivePort",
+          profileRoot: "/profiles/dia-newer",
+          mtimeMs: 20,
+        },
+      ]),
+    }));
+
+    const { resolveAttachRunningConnection } = await import("../../src/browser/attachRunning.js");
+    const logger = vi.fn();
+
+    const result = await resolveAttachRunningConnection(
+      {
+        chromePath: "/Applications/Dia.app/Contents/MacOS/Dia",
+        remoteChrome: { host: "127.0.0.1", port: 63332 },
+      },
+      logger,
+    );
+
+    expect(result).toMatchObject({
+      host: "127.0.0.1",
+      port: 63332,
+      browserWSEndpoint: "ws://127.0.0.1:63332/devtools/browser/newer",
+      profileRoot: "/profiles/dia-newer",
+    });
+    expect(logger).toHaveBeenCalledWith(
+      "Note: --browser-chrome-path is ignored when --browser-attach-running is enabled.",
+    );
+    expect(logger).toHaveBeenCalledWith(
+      "Selected attach-running browser metadata from /profiles/dia-newer/DevToolsActivePort",
+    );
+  });
+
+  test("rejects attach-running when no local DevToolsActivePort matches the selected port", async () => {
+    vi.doMock("../../src/browser/detect.js", () => ({
+      discoverDevToolsActivePortCandidates: vi.fn(async () => []),
+    }));
+
+    const { resolveAttachRunningConnection } = await import("../../src/browser/attachRunning.js");
+    const logger = vi.fn() as BrowserLogger;
+
+    await expect(
+      resolveAttachRunningConnection(
+        {
+          chromePath: null,
+          remoteChrome: { host: "127.0.0.1", port: 63332 },
+        },
+        logger,
+      ),
+    ).rejects.toThrow(/No running browser with attach metadata matched 127\.0\.0\.1:63332/i);
+  });
+});
diff --git a/tests/browser/chromeLifecycle.test.ts b/tests/browser/chromeLifecycle.test.ts
index 6422cd126..36b70cc6d 100644
--- a/tests/browser/chromeLifecycle.test.ts
+++ b/tests/browser/chromeLifecycle.test.ts
@@ -1,12 +1,15 @@
-import { beforeEach, describe, expect, test, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 const cdpNewMock = vi.fn();
 const cdpCloseMock = vi.fn();
+const cdpListMock = vi.fn();
 const cdpMock = Object.assign(vi.fn(), {
   // biome-ignore lint/style/useNamingConvention: CDP API uses capitalized members.
   New: cdpNewMock,
   // biome-ignore lint/style/useNamingConvention: CDP API uses capitalized members.
   Close: cdpCloseMock,
+  // biome-ignore lint/style/useNamingConvention: CDP API uses capitalized members.
+  List: cdpListMock,
 });
 
 vi.mock("chrome-remote-interface", () => ({ default: cdpMock }));
@@ -61,6 +64,11 @@ describe("connectWithNewTab", () => {
     cdpMock.mockReset();
     cdpNewMock.mockReset();
     cdpCloseMock.mockReset();
+    cdpListMock.mockReset();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
   });
 
   test("falls back to default target when new tab cannot be opened", async () => {
@@ -124,4 +132,122 @@ describe("connectWithNewTab", () => {
     expect(cdpNewMock).toHaveBeenCalledTimes(1);
     expect(cdpMock).toHaveBeenCalledWith({ host: "127.0.0.1", port: 9222, target: "target-2" });
   });
+
+  test("opens a dedicated tab through a browser websocket endpoint", async () => {
+    const browserClient = {
+      Target: {
+        createTarget: vi.fn(async () => ({ targetId: "target-9" })),
+        attachToTarget: vi.fn(async () => ({ sessionId: "session-9" })),
+        detachFromTarget: vi.fn(async () => ({})),
+        closeTarget: vi.fn(async () => ({ success: true })),
+      },
+      Network: { enable: vi.fn(async () => ({})) },
+      Page: { enable: vi.fn(async () => ({})), navigate: vi.fn(async () => ({})) },
+      Runtime: { enable: vi.fn(async () => ({})), evaluate: vi.fn(async () => ({ result: {} })) },
+      Input: { dispatchKeyEvent: vi.fn(async () => ({})) },
+      DOM: { enable: vi.fn(async () => ({})) },
+      on: vi.fn(),
+      once: vi.fn(),
+      removeListener: vi.fn(),
+      close: vi.fn(async () => {}),
+    };
+    cdpMock.mockResolvedValue(browserClient);
+
+    const { connectToRemoteChrome } = await import("../../src/browser/chromeLifecycle.js");
+    const logger = vi.fn();
+
+    const connection = await connectToRemoteChrome(
+      "127.0.0.1",
+      9222,
+      logger,
+      "https://chatgpt.com/",
+      "ws://127.0.0.1:9222/devtools/browser/abc",
+    );
+
+    expect(cdpMock).toHaveBeenCalledWith({
+      target: "ws://127.0.0.1:9222/devtools/browser/abc",
+      local: true,
+    });
+    expect(browserClient.Target.createTarget).toHaveBeenCalledWith({ url: "https://chatgpt.com/" });
+    expect(browserClient.Target.attachToTarget).toHaveBeenCalledWith({
+      targetId: "target-9",
+      flatten: true,
+    });
+    expect(connection.targetId).toBe("target-9");
+  });
+
+  test("waits on a single websocket connection attempt for Chrome approval", async () => {
+    vi.useFakeTimers();
+    const browserClient = {
+      Target: {
+        createTarget: vi.fn(async () => ({ targetId: "target-10" })),
+        attachToTarget: vi.fn(async () => ({ sessionId: "session-10" })),
+        detachFromTarget: vi.fn(async () => ({})),
+        closeTarget: vi.fn(async () => ({ success: true })),
+      },
+      Network: { enable: vi.fn(async () => ({})) },
+      Page: { enable: vi.fn(async () => ({})), navigate: vi.fn(async () => ({})) },
+      Runtime: { enable: vi.fn(async () => ({})), evaluate: vi.fn(async () => ({ result: {} })) },
+      Input: { dispatchKeyEvent: vi.fn(async () => ({})) },
+      DOM: { enable: vi.fn(async () => ({})) },
+      on: vi.fn(),
+      once: vi.fn(),
+      removeListener: vi.fn(),
+      close: vi.fn(async () => {}),
+    };
+    cdpMock.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          setTimeout(() => resolve(browserClient), 1_000);
+        }),
+    );
+
+    const { connectToRemoteChrome } = await import("../../src/browser/chromeLifecycle.js");
+    const logger = vi.fn();
+    const promise = connectToRemoteChrome(
+      "127.0.0.1",
+      9222,
+      logger,
+      "https://chatgpt.com/",
+      "ws://127.0.0.1:9222/devtools/browser/abc",
+      { approvalWaitMs: 20_000 },
+    );
+
+    await vi.advanceTimersByTimeAsync(1_000);
+
+    const connection = await promise;
+
+    expect(cdpMock).toHaveBeenCalledTimes(1);
+    expect(logger).toHaveBeenCalledWith(
+      "Waiting for Chrome remote debugging approval for 127.0.0.1:9222...",
+    );
+    expect(connection.targetId).toBe("target-10");
+  });
+
+  test("fails after the approval wait without opening a second websocket request", async () => {
+    vi.useFakeTimers();
+    cdpMock.mockImplementationOnce(() => new Promise(() => {}));
+
+    const { connectToRemoteChrome } = await import("../../src/browser/chromeLifecycle.js");
+    const logger = vi.fn();
+    const promise = connectToRemoteChrome(
+      "127.0.0.1",
+      9222,
+      logger,
+      "https://chatgpt.com/",
+      "ws://127.0.0.1:9222/devtools/browser/abc",
+      { approvalWaitMs: 20_000 },
+    );
+    const assertion = expect(promise).rejects.toThrow(
+      /waited 20s for Chrome remote debugging approval/i,
+    );
+
+    await vi.advanceTimersByTimeAsync(20_000);
+    await assertion;
+
+    expect(cdpMock).toHaveBeenCalledTimes(1);
+    expect(logger).toHaveBeenCalledWith(
+      "Waiting for Chrome remote debugging approval for 127.0.0.1:9222...",
+    );
+  });
 });
diff --git a/tests/browser/detect.test.ts b/tests/browser/detect.test.ts
new file mode 100644
index 000000000..797086605
--- /dev/null
+++ b/tests/browser/detect.test.ts
@@ -0,0 +1,90 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import {
+  discoverDevToolsActivePortCandidates,
+  inferAttachRunningBrowserFamily,
+  parseDevToolsActivePort,
+  resolveAttachRunningProfileRoots,
+} from "../../src/browser/detect.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    tempDirs.splice(0).map(async (dir) => {
+      await fs.rm(dir, { recursive: true, force: true });
+    }),
+  );
+});
+
+describe("attach-running browser detection", () => {
+  test("parses DevToolsActivePort into a browser websocket endpoint", () => {
+    expect(
+      parseDevToolsActivePort("9222\n/devtools/browser/abc123\n", { host: "127.0.0.1" }),
+    ).toEqual({
+      port: 9222,
+      browserWSEndpoint: "ws://127.0.0.1:9222/devtools/browser/abc123",
+    });
+  });
+
+  test("wraps IPv6 hosts when building browser websocket endpoints", () => {
+    expect(parseDevToolsActivePort("9222\n/devtools/browser/abc123\n", { host: "::1" })).toEqual({
+      port: 9222,
+      browserWSEndpoint: "ws://[::1]:9222/devtools/browser/abc123",
+    });
+  });
+
+  test("infers supported browser family from browser-chrome-path", () => {
+    expect(
+      inferAttachRunningBrowserFamily(
+        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      ),
+    ).toBe("edge");
+    expect(
+      inferAttachRunningBrowserFamily(
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      ),
+    ).toBe("chrome");
+  });
+
+  test("orders attach-running browser roots by preferred browser family", () => {
+    const roots = resolveAttachRunningProfileRoots("darwin", "/Users/peter");
+
+    expect(roots.map((entry) => entry.family)).toEqual(["chrome", "chromium", "edge", "brave"]);
+    expect(roots[0]?.root).toContain("Google/Chrome");
+  });
+
+  test("discovers DevToolsActivePort files recursively and derives profile roots", async () => {
+    const homeDir = await fs.mkdtemp(path.join(os.tmpdir(), "oracle-detect-"));
+    tempDirs.push(homeDir);
+    const defaultDir = path.join(
+      homeDir,
+      "Library",
+      "Application Support",
+      "Dia",
+      "User Data",
+      "Default",
+    );
+    await fs.mkdir(defaultDir, { recursive: true });
+    await fs.writeFile(
+      path.join(defaultDir, "DevToolsActivePort"),
+      "63332\n/devtools/browser/dia\n",
+      "utf8",
+    );
+
+    const candidates = await discoverDevToolsActivePortCandidates({
+      host: "127.0.0.1",
+      platform: "darwin",
+      homeDir,
+    });
+
+    expect(candidates).toHaveLength(1);
+    expect(candidates[0]).toMatchObject({
+      port: 63332,
+      browserWSEndpoint: "ws://127.0.0.1:63332/devtools/browser/dia",
+      profileRoot: path.join(homeDir, "Library", "Application Support", "Dia", "User Data"),
+    });
+  });
+});
diff --git a/tests/browser/index.test.ts b/tests/browser/index.test.ts
index c4a1eab73..072dc32f3 100644
--- a/tests/browser/index.test.ts
+++ b/tests/browser/index.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { shouldPreserveBrowserOnErrorForTest } from "../../src/browser/index.js";
+import { __test__, shouldPreserveBrowserOnErrorForTest } from "../../src/browser/index.js";
 import { BrowserAutomationError } from "../../src/oracle/errors.js";
 
 describe("shouldPreserveBrowserOnErrorForTest", () => {
@@ -24,3 +24,23 @@ describe("shouldPreserveBrowserOnErrorForTest", () => {
     expect(shouldPreserveBrowserOnErrorForTest(error, false)).toBe(false);
   });
 });
+
+describe("remote Chrome option warnings", () => {
+  test("does not mark browser-chrome-path as ignored for attach-running", () => {
+    expect(
+      __test__.listIgnoredRemoteChromeFlags({
+        attachRunning: true,
+        chromePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      }),
+    ).not.toContain("--browser-chrome-path");
+  });
+
+  test("marks browser-chrome-path as ignored for classic remote-chrome", () => {
+    expect(
+      __test__.listIgnoredRemoteChromeFlags({
+        attachRunning: false,
+        chromePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      }),
+    ).toContain("--browser-chrome-path");
+  });
+});
diff --git a/tests/browser/reattach.test.ts b/tests/browser/reattach.test.ts
index c5208bde6..47f473f41 100644
--- a/tests/browser/reattach.test.ts
+++ b/tests/browser/reattach.test.ts
@@ -91,6 +91,66 @@ describe("resumeBrowserSession", () => {
     expect(recoverSession).toHaveBeenCalled();
   });
 
+  test("tries live reattach from browser websocket metadata before falling back", async () => {
+    const runtime = {
+      chromeBrowserWSEndpoint: "ws://127.0.0.1:9222/devtools/browser/abc",
+      chromeProfileRoot: "/tmp/oracle-attach-running-profile",
+      tabUrl: "https://chatgpt.com/c/abc",
+      chromeTargetId: "target-2",
+    };
+    const listTargets = vi.fn(
+      async () =>
+        [
+          { targetId: "target-2", type: "page", url: "https://chatgpt.com/c/abc" },
+        ] satisfies FakeTarget[],
+    ) as unknown as () => Promise<FakeTarget[]>;
+    const evaluate = vi.fn(async ({ expression }: { expression: string }) => {
+      if (expression === "location.href") {
+        return { result: { value: runtime.tabUrl } };
+      }
+      if (expression === "1+1") {
+        return { result: { value: 2 } };
+      }
+      return { result: { value: null } };
+    });
+    const connect = vi.fn(
+      async () =>
+        ({
+          Runtime: { enable: vi.fn(), evaluate },
+          DOM: { enable: vi.fn() },
+          close: vi.fn(async () => {}),
+        }) satisfies FakeClient,
+    ) as unknown as (options?: unknown) => Promise<ChromeClient>;
+    const waitForAssistantResponse = vi.fn(async () => ({
+      text: "attached",
+      html: "",
+      meta: { messageId: "m1", turnId: "conversation-turn-1" },
+    }));
+    const captureAssistantMarkdown = vi.fn(async () => "attached-md");
+    const logger = vi.fn() as BrowserLogger;
+
+    const result = await resumeBrowserSession(
+      runtime,
+      { attachRunning: true, timeoutMs: 2_000 },
+      logger,
+      {
+        listTargets,
+        connect,
+        waitForAssistantResponse,
+        captureAssistantMarkdown,
+      },
+    );
+
+    expect(result.answerMarkdown).toBe("attached-md");
+    expect(listTargets).toHaveBeenCalled();
+    expect(connect).toHaveBeenCalledWith(
+      expect.objectContaining({
+        target: "ws://127.0.0.1:9222/devtools/browser/abc",
+        local: true,
+      }),
+    );
+  });
+
   test("falls back to recovery when existing chrome attach fails", async () => {
     const runtime = {
       chromePort: 51559,
diff --git a/tests/browser/sessionRunner.test.ts b/tests/browser/sessionRunner.test.ts
index 5d224248c..d8681a30e 100644
--- a/tests/browser/sessionRunner.test.ts
+++ b/tests/browser/sessionRunner.test.ts
@@ -67,6 +67,73 @@ describe("runBrowserSessionExecution", () => {
     expect(log).toHaveBeenCalled();
   });
 
+  test("persists attach-mode runtime metadata from the browser runner", async () => {
+    const log = vi.fn();
+    const persistRuntimeHint = vi.fn();
+    const executeBrowser = vi.fn(async (options) => {
+      await options.runtimeHintCb?.({
+        browserTransport: "cdp" as const,
+        chromeBrowserWSEndpoint: "ws://127.0.0.1:9222/devtools/browser/abc",
+        chromeProfileRoot: "/Users/peter/Library/Application Support/Google/Chrome",
+        chromeTargetId: "target-2",
+        tabUrl: "https://chatgpt.com/c/attached",
+      });
+      return {
+        answerText: "ok",
+        answerMarkdown: "ok",
+        tookMs: 100,
+        answerTokens: 2,
+        answerChars: 2,
+        browserTransport: "cdp" as const,
+        chromeBrowserWSEndpoint: "ws://127.0.0.1:9222/devtools/browser/abc",
+        chromeProfileRoot: "/Users/peter/Library/Application Support/Google/Chrome",
+        chromeTargetId: "target-2",
+        tabUrl: "https://chatgpt.com/c/attached",
+      };
+    });
+
+    const result = await runBrowserSessionExecution(
+      {
+        runOptions: baseRunOptions,
+        browserConfig: { attachRunning: true },
+        cwd: "/repo",
+        log,
+      },
+      {
+        assemblePrompt: async () => ({
+          markdown: "prompt",
+          composerText: "prompt",
+          estimatedInputTokens: 10,
+          attachments: [],
+          inlineFileCount: 0,
+          tokenEstimateIncludesInlineFiles: false,
+          attachmentsPolicy: "auto",
+          attachmentMode: "inline",
+          fallback: null,
+        }),
+        executeBrowser,
+        persistRuntimeHint,
+      },
+    );
+
+    expect(persistRuntimeHint).toHaveBeenCalledWith(
+      expect.objectContaining({
+        browserTransport: "cdp",
+        chromeBrowserWSEndpoint: "ws://127.0.0.1:9222/devtools/browser/abc",
+        chromeProfileRoot: "/Users/peter/Library/Application Support/Google/Chrome",
+        chromeTargetId: "target-2",
+        tabUrl: "https://chatgpt.com/c/attached",
+      }),
+    );
+    expect(result.runtime).toMatchObject({
+      browserTransport: "cdp",
+      chromeBrowserWSEndpoint: "ws://127.0.0.1:9222/devtools/browser/abc",
+      chromeProfileRoot: "/Users/peter/Library/Application Support/Google/Chrome",
+      chromeTargetId: "target-2",
+      tabUrl: "https://chatgpt.com/c/attached",
+    });
+  });
+
   test("suppresses automation noise when not verbose", async () => {
     const log = vi.fn();
     const noisyLogger = vi.fn();
diff --git a/tests/cli/browserConfig.test.ts b/tests/cli/browserConfig.test.ts
index 70f6c4077..18e940045 100644
--- a/tests/cli/browserConfig.test.ts
+++ b/tests/cli/browserConfig.test.ts
@@ -117,6 +117,74 @@ describe("buildBrowserConfig", () => {
     expect(config.remoteChrome).toEqual({ host: "remote-host", port: 9_333 });
   });
 
+  test("enables attach-running with auto-connect by default", async () => {
+    const config = await buildBrowserConfig({
+      model: "gpt-5.2-pro",
+      browserAttachRunning: true,
+    });
+    expect(config.attachRunning).toBe(true);
+  });
+
+  test("still accepts browser-chrome-path when attach-running is enabled", async () => {
+    const config = await buildBrowserConfig({
+      model: "gpt-5.2-pro",
+      browserAttachRunning: true,
+      browserChromePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    });
+    expect(config.attachRunning).toBe(true);
+    expect(config.chromePath).toBe("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome");
+  });
+
+  test("rejects launcher-owned flags when attach-running is enabled", async () => {
+    await expect(
+      buildBrowserConfig({
+        model: "gpt-5.2-pro",
+        browserAttachRunning: true,
+        browserManualLogin: true,
+      }),
+    ).rejects.toThrow(/attach-running/i);
+  });
+
+  test("rejects browser-chrome-profile when attach-running is enabled", async () => {
+    await expect(
+      buildBrowserConfig({
+        model: "gpt-5.2-pro",
+        browserAttachRunning: true,
+        browserChromeProfile: "Profile 2",
+      }),
+    ).rejects.toThrow(/attach-running/i);
+  });
+
+  test("rejects browser-manual-login-profile-dir when attach-running is enabled", async () => {
+    await expect(
+      buildBrowserConfig({
+        model: "gpt-5.2-pro",
+        browserAttachRunning: true,
+        browserManualLoginProfileDir: "/tmp/oracle-profile",
+      }),
+    ).rejects.toThrow(/attach-running/i);
+  });
+
+  test("rejects inline cookie overrides when attach-running is enabled", async () => {
+    await expect(
+      buildBrowserConfig({
+        model: "gpt-5.2-pro",
+        browserAttachRunning: true,
+        browserInlineCookies: "[]",
+      }),
+    ).rejects.toThrow(/attach-running/i);
+  });
+
+  test("allows remote-chrome as an attach-running hint", async () => {
+    const config = await buildBrowserConfig({
+      model: "gpt-5.2-pro",
+      browserAttachRunning: true,
+      remoteChrome: "remote-host:9333",
+    });
+    expect(config.attachRunning).toBe(true);
+    expect(config.remoteChrome).toEqual({ host: "remote-host", port: 9_333 });
+  });
+
   test("normalizes chatgpt-url alias and adds https when missing", async () => {
     const config = await buildBrowserConfig({
       model: "gpt-5.1",
diff --git a/tests/cli/browserDefaults.test.ts b/tests/cli/browserDefaults.test.ts
index 43a93b7d6..28e149af2 100644
--- a/tests/cli/browserDefaults.test.ts
+++ b/tests/cli/browserDefaults.test.ts
@@ -121,6 +121,19 @@ describe("applyBrowserDefaultsFromConfig", () => {
     expect(options.browserManualLoginProfileDir).toBe("/tmp/oracle-profile");
   });
 
+  test("applies attach-running defaults from config when CLI flags are untouched", () => {
+    const options: BrowserDefaultsOptions = {};
+    const config: UserConfig = {
+      browser: {
+        attachRunning: true,
+      },
+    };
+
+    applyBrowserDefaultsFromConfig(options, config, (_key) => "default");
+
+    expect(options.browserAttachRunning).toBe(true);
+  });
+
   test("does not override manual-login when CLI enabled it", () => {
     const options: BrowserDefaultsOptions = { browserManualLogin: true };
     const config: UserConfig = {

From 5ca48877cbc60287848088ff5c39a83a99940bff Mon Sep 17 00:00:00 2001
From: seichris <cerujurasa@gmail.com>
Date: Thu, 26 Mar 2026 14:36:48 +0800
Subject: [PATCH 2/2] Fix attach-running validation and docs

---
 README.md                           |  4 ++--
 bin/oracle-cli.ts                   |  4 ++--
 docs/browser-mode.md                |  7 ++++---
 docs/manual-tests.md                |  2 +-
 src/browser/attachRunning.ts        |  6 ++++++
 src/browser/detect.ts               |  7 +++++++
 src/cli/browserConfig.ts            | 10 ++++++++++
 tests/browser/attachRunning.test.ts | 19 +++++++++++++++++++
 tests/browser/detect.test.ts        | 12 ++++++++++++
 tests/cli/browserConfig.test.ts     | 16 +++++++++++++---
 10 files changed, 76 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index e03cdbdd7..0e78cd91f 100644
--- a/README.md
+++ b/README.md
@@ -211,7 +211,7 @@ oracle --engine browser \
 | `--chatgpt-url <url>`                                           | Target a ChatGPT workspace/folder (browser).                                                                                                                                                                                                                                                                    |
 | `--browser-model-strategy <select\|current\|ignore>`            | Control ChatGPT model selection in browser mode (current keeps the active model; ignore skips the picker).                                                                                                                                                                                                      |
 | `--browser-manual-login`                                        | Skip cookie copy; reuse a persistent automation profile and wait for manual ChatGPT login.                                                                                                                                                                                                                      |
-| `--browser-attach-running`                                      | Reuse your current local browser session through local `DevToolsActivePort` discovery; Oracle opens a dedicated tab instead of launching Chrome (defaults to `127.0.0.1:9222`, or combine with `--remote-chrome <host:port>` to hint a different local endpoint).                                               |
+| `--browser-attach-running`                                      | Reuse your current local browser session through local `DevToolsActivePort` discovery; Oracle opens a dedicated tab instead of launching Chrome (defaults to `127.0.0.1:9222`, or combine with `--remote-chrome 127.0.0.1:<port>` to hint a different local loopback endpoint).                                   |
 | `--browser-thinking-time <light\|standard\|extended\|heavy>`    | Set ChatGPT thinking-time intensity (browser; Thinking/Pro models only).                                                                                                                                                                                                                                        |
 | `--browser-port <port>`                                         | Pin the Chrome DevTools port (WSL/Windows firewall helper).                                                                                                                                                                                                                                                     |
 | `--browser-inline-cookies[(-file)] <payload \| path>`           | Supply cookies without Chrome/Keychain (browser).                                                                                                                                                                                                                                                               |
@@ -230,7 +230,7 @@ oracle --engine browser \
 | `--files-report`                                                | Print per-file token usage.                                                                                                                                                                                                                                                                                     |
 | `--dry-run [summary\|json\|full]`                               | Preview without sending.                                                                                                                                                                                                                                                                                        |
 | `--remote-host`, `--remote-token`                               | Use a remote `oracle serve` host (browser).                                                                                                                                                                                                                                                                     |
-| `--remote-chrome <host:port>`                                   | Attach to an existing remote Chrome session (browser), or when combined with `--browser-attach-running` use this host:port as the local attach hint.                                                                                                                                                            |
+| `--remote-chrome <host:port>`                                   | Attach to an existing remote Chrome session (browser), or when combined with `--browser-attach-running` use a local loopback host:port hint such as `127.0.0.1:63332`.                                                                                                                                          |
 | `--youtube <url>`                                               | YouTube video URL to analyze (Gemini browser mode).                                                                                                                                                                                                                                                             |
 | `--generate-image <file>`                                       | Generate image and save to file (Gemini browser mode).                                                                                                                                                                                                                                                          |
 | `--edit-image <file>`                                           | Edit existing image with `--output` (Gemini browser mode).                                                                                                                                                                                                                                                      |
diff --git a/bin/oracle-cli.ts b/bin/oracle-cli.ts
index 8a6690741..d891a16e0 100755
--- a/bin/oracle-cli.ts
+++ b/bin/oracle-cli.ts
@@ -464,7 +464,7 @@ program
   .addOption(
     new Option(
       "--browser-attach-running",
-      "Attach to a running local browser session instead of launching Chrome (defaults to 127.0.0.1:9222; combine with --remote-chrome to hint a different host:port).",
+      "Attach to a running local browser session instead of launching Chrome (defaults to 127.0.0.1:9222; combine with --remote-chrome 127.0.0.1:<port> to hint a different local loopback port).",
     ),
   )
   .addOption(
@@ -616,7 +616,7 @@ program
   .addOption(
     new Option(
       "--remote-chrome <host:port>",
-      "Connect to remote Chrome DevTools Protocol, or when combined with --browser-attach-running use this host:port as the local attach hint.",
+      "Connect to remote Chrome DevTools Protocol, or when combined with --browser-attach-running use a local loopback host:port as the attach hint.",
     ),
   )
   .addOption(
diff --git a/docs/browser-mode.md b/docs/browser-mode.md
index b9b815523..a0c5ab51c 100644
--- a/docs/browser-mode.md
+++ b/docs/browser-mode.md
@@ -65,6 +65,7 @@ Notes:
     -p "Summarize the last assistant response in one paragraph"
   ```
 - Oracle reads local `DevToolsActivePort` metadata, connects to the browser websocket directly, and then reuses the normal CDP automation flow.
+- `--remote-chrome` stays local-only in attach-running mode. Use loopback hosts such as `127.0.0.1`, `localhost`, or `[::1]`.
 - If Chrome shows a remote-debugging approval prompt on first attach, Oracle issues one attach request and waits briefly for you to allow it before failing.
 - Attach mode always opens a fresh Oracle-owned tab and closes only that tab after a successful run.
 - Cookie sync, Chrome launch flags, and profile lifecycle flags are skipped because the browser is already running.
@@ -91,7 +92,7 @@ Notes:
 - `--engine browser`: enables browser mode (legacy `--browser` remains as an alias for now). Without `--engine`, Oracle chooses API when `OPENAI_API_KEY` exists, otherwise browser.
 - `--browser-chrome-profile`, `--browser-chrome-path`: cookie source + binary override (defaults to the standard `"Default"` Chrome profile so existing ChatGPT logins carry over).
 - `--browser-cookie-path`: explicit path to the Chrome/Chromium/Edge `Cookies` SQLite DB. Handy when you launch a fork via `--browser-chrome-path` and want to copy its session cookies; see [docs/chromium-forks.md](chromium-forks.md) for examples.
-- `--browser-attach-running`: attach to a local already-running browser instead of launching Chrome directly. Defaults to `127.0.0.1:9222`; combine with `--remote-chrome <host:port>` to use a different local attach hint.
+- `--browser-attach-running`: attach to a local already-running browser instead of launching Chrome directly. Defaults to `127.0.0.1:9222`; combine with `--remote-chrome 127.0.0.1:<port>` to use a different local attach hint.
 - `--chatgpt-url`: override the ChatGPT base URL. Works with the root homepage (`https://chatgpt.com/`) **or** a specific workspace/folder link such as `https://chatgpt.com/g/.../project`. `--browser-url` stays as a hidden alias.
 - `--browser-timeout`, `--browser-input-timeout`: `1200s (20m)`/`60s` defaults. Durations accept `ms`, `s`, `m`, or `h` and can be chained (`1h2m10s`).
 - `--browser-recheck-delay`, `--browser-recheck-timeout`: after an assistant timeout, wait the delay, revisit the conversation, and retry capture (default recheck timeout 120s). Useful for Pro runs that finish later.
@@ -110,7 +111,7 @@ Notes:
 - sqlite bindings: automatic rebuilds now require `ORACLE_ALLOW_SQLITE_REBUILD=1`. Without it, the CLI logs instructions instead of running `pnpm rebuild` on your behalf.
 - `--model`: the same flag used for API runs is accepted, but the ChatGPT automation path supports GPT-5.4 and GPT-5.2 variants. Use `gpt-5.4-pro`, `gpt-5.4`, `gpt-5.2`, `gpt-5.2-thinking`, `gpt-5.2-instant`, or `gpt-5.2-pro`. Legacy Pro aliases still resolve to the latest Pro picker target.
 - Cookie sync is mandatory—if we can’t copy cookies from Chrome, the run exits early. Use the hidden `--browser-allow-cookie-errors` flag only when you’re intentionally running logged out (it skips the early exit but still warns).
-- Attach-running mode is mutually exclusive with launcher-owned flags such as `--browser-manual-login`, `--browser-chrome-profile`, `--browser-cookie-path`, `--browser-hide-window`, `--browser-keep-browser`, and `--browser-port`. `--remote-chrome` is allowed in attach-running mode, but only as the local host:port hint used to find matching `DevToolsActivePort` metadata. `--browser-chrome-path` is accepted but ignored.
+- Attach-running mode is mutually exclusive with launcher-owned flags such as `--browser-manual-login`, `--browser-chrome-profile`, `--browser-cookie-path`, `--browser-hide-window`, `--browser-keep-browser`, and `--browser-port`. `--remote-chrome` is allowed in attach-running mode, but only as a local loopback host:port hint used to find matching `DevToolsActivePort` metadata. `--browser-chrome-path` is accepted but ignored.
 - Experimental cookie controls (hidden flags/env):
   - `--browser-cookie-names <comma-list>` or `ORACLE_BROWSER_COOKIE_NAMES`: allowlist which cookies to sync. Useful for “only NextAuth/Cloudflare, drop the rest.”
   - `--browser-cookie-wait <ms|s|m>`: if cookie sync fails or returns no cookies, wait once and retry (helps when macOS Keychain prompts are slow).
@@ -263,7 +264,7 @@ This mode is ideal when you have a macOS VM (or spare Mac mini) logged into Chat
 ## Limitations / Follow-Up Plan
 
 - **Attachment lifecycle** – in `auto` mode we prefer inlining files into the composer (fewer moving parts). When we do upload, each `--file` path is uploaded separately (or bundled) so ChatGPT can ingest filenames/content. The automation waits for uploads to finish (send button enabled, upload chips visible) before submitting. When inline paste is rejected by ChatGPT (too large), Oracle retries automatically with uploads.
-- **Attach-running uploads** – `--browser-attach-running` currently supports inline file delivery only. If the run would require browser uploads, Oracle fails fast and points you back to the standard launcher path.
+- **Attach-running uploads** – attach-running reuses the same CDP/DataTransfer upload path as other remote-browser sessions. If Chrome or ChatGPT changes how attached tabs accept file inputs, this path may need follow-up hardening.
 - **Model picker drift** – we rely on heuristics to pick GPT-5.4 / GPT-5.2 variants. If OpenAI changes the DOM we need to refresh the selectors quickly. Consider snapshot tests or a small “self check” command.
 - **Non-mac platforms** – window hiding uses AppleScript today; Linux/Windows just ignore the flag. We should detect platforms explicitly and document the behavior.
 - **Streaming UX** – browser runs cannot stream tokens, so we log a warning before launching Chrome. Investigate whether we can stream clipboard deltas via mutation observers for a closer UX.
diff --git a/docs/manual-tests.md b/docs/manual-tests.md
index 8dd559216..a1368056b 100644
--- a/docs/manual-tests.md
+++ b/docs/manual-tests.md
@@ -205,7 +205,7 @@ Run this whenever you touch the local attach path (`--browser-attach-running`) o
      --model "GPT-5.2" \
      --prompt "Give me two short markdown bullets about browser tabs"
    ```
-   If the browser’s remote-debugging UI shows a different local port, rerun with `--remote-chrome <host:port>` in addition to `--browser-attach-running`.
+   If the browser’s remote-debugging UI shows a different local port, rerun with `--remote-chrome 127.0.0.1:<port>` (or `localhost:<port>`) in addition to `--browser-attach-running`.
 3. Verify Oracle opens a fresh tab in the existing browser, returns the answer, and closes only that Oracle-owned tab afterward.
 4. Reattach sanity check: repeat with a very short timeout if needed, then run `oracle session <id>` and confirm Oracle can reconnect to the saved tab/conversation.
 
diff --git a/src/browser/attachRunning.ts b/src/browser/attachRunning.ts
index 06c3713f9..d1d744162 100644
--- a/src/browser/attachRunning.ts
+++ b/src/browser/attachRunning.ts
@@ -1,6 +1,7 @@
 import type { BrowserLogger, ResolvedBrowserConfig } from "./types.js";
 import {
   discoverDevToolsActivePortCandidates,
+  isLoopbackDevToolsHost,
   type DevToolsActivePortCandidate,
 } from "./detect.js";
 
@@ -17,6 +18,11 @@ export async function resolveAttachRunningConnection(
 ): Promise<AttachRunningConnectionInfo> {
   const host = config.remoteChrome?.host ?? "127.0.0.1";
   const port = config.remoteChrome?.port ?? 9222;
+  if (!isLoopbackDevToolsHost(host)) {
+    throw new Error(
+      `--browser-attach-running only supports local loopback attach hints. Received ${host}:${port}; use 127.0.0.1, localhost, or [::1].`,
+    );
+  }
   if (config.chromePath) {
     logger("Note: --browser-chrome-path is ignored when --browser-attach-running is enabled.");
   }
diff --git a/src/browser/detect.ts b/src/browser/detect.ts
index 3bf5f351a..670e7d1c7 100644
--- a/src/browser/detect.ts
+++ b/src/browser/detect.ts
@@ -22,6 +22,11 @@ export interface DevToolsActivePortCandidate extends DevToolsActivePortInfo {
   mtimeMs: number;
 }
 
+export function isLoopbackDevToolsHost(host: string): boolean {
+  const normalized = host.trim().toLowerCase().replace(/^\[(.*)\]$/u, "$1");
+  return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
+}
+
 export async function detectChromeBinary(): Promise<{ path: string | null }> {
   const envPath = (process.env.CHROME_PATH ?? "").trim();
   if (envPath) {
@@ -106,6 +111,8 @@ export function resolveAttachRunningProfileRoots(
   if (platform === "linux") {
     return [
       { family: "chrome", root: path.join(homeDir, ".config", "google-chrome") },
+      { family: "chrome", root: path.join(homeDir, ".config", "google-chrome-beta") },
+      { family: "chrome", root: path.join(homeDir, ".config", "google-chrome-unstable") },
       { family: "chromium", root: path.join(homeDir, ".config", "chromium") },
       { family: "edge", root: path.join(homeDir, ".config", "microsoft-edge") },
       {
diff --git a/src/cli/browserConfig.ts b/src/cli/browserConfig.ts
index e4cc2f3a4..ef1347904 100644
--- a/src/cli/browserConfig.ts
+++ b/src/cli/browserConfig.ts
@@ -10,6 +10,7 @@ import {
   normalizeChatgptUrl,
   parseDuration,
 } from "../browserMode.js";
+import { isLoopbackDevToolsHost } from "../browser/detect.js";
 import { normalizeBrowserModelStrategy } from "../browser/modelStrategy.js";
 import type { BrowserModelStrategy } from "../browser/types.js";
 import type { CookieParam } from "../browser/types.js";
@@ -138,6 +139,7 @@ export async function buildBrowserConfig(
   validateAttachRunningOptions(options, {
     attachRunning,
     hasInlineCookies: Boolean(inline?.cookies),
+    remoteChrome,
   });
   const rawUrl = options.chatgptUrl ?? options.browserUrl;
   const url = rawUrl ? normalizeChatgptUrl(rawUrl, CHATGPT_URL) : undefined;
@@ -221,9 +223,11 @@ function validateAttachRunningOptions(
   {
     attachRunning,
     hasInlineCookies,
+    remoteChrome,
   }: {
     attachRunning: boolean;
     hasInlineCookies: boolean;
+    remoteChrome?: { host: string; port: number };
   },
 ): void {
   if (!attachRunning) {
@@ -243,6 +247,12 @@ function validateAttachRunningOptions(
       : null,
   ].filter((value): value is string => Boolean(value));
 
+  if (remoteChrome && !isLoopbackDevToolsHost(remoteChrome.host)) {
+    throw new Error(
+      `--browser-attach-running only supports local loopback attach hints via --remote-chrome. Received ${remoteChrome.host}:${remoteChrome.port}; use 127.0.0.1, localhost, or [::1].`,
+    );
+  }
+
   if (conflicts.length > 0) {
     throw new Error(
       `--browser-attach-running cannot be combined with ${conflicts.join(", ")} because attach mode reuses an already-running browser instead of launching and configuring its own Chrome instance.`,
diff --git a/tests/browser/attachRunning.test.ts b/tests/browser/attachRunning.test.ts
index 5c21c3e35..61dd71655 100644
--- a/tests/browser/attachRunning.test.ts
+++ b/tests/browser/attachRunning.test.ts
@@ -104,4 +104,23 @@ describe("resolveAttachRunningConnection", () => {
       ),
     ).rejects.toThrow(/No running browser with attach metadata matched 127\.0\.0\.1:63332/i);
   });
+
+  test("rejects non-loopback attach-running hints", async () => {
+    vi.doMock("../../src/browser/detect.js", () => ({
+      discoverDevToolsActivePortCandidates: vi.fn(async () => []),
+      isLoopbackDevToolsHost: vi.fn(() => false),
+    }));
+
+    const { resolveAttachRunningConnection } = await import("../../src/browser/attachRunning.js");
+
+    await expect(
+      resolveAttachRunningConnection(
+        {
+          chromePath: null,
+          remoteChrome: { host: "192.168.1.10", port: 9222 },
+        },
+        vi.fn(),
+      ),
+    ).rejects.toThrow(/only supports local loopback attach hints/i);
+  });
 });
diff --git a/tests/browser/detect.test.ts b/tests/browser/detect.test.ts
index 797086605..9ac21ee54 100644
--- a/tests/browser/detect.test.ts
+++ b/tests/browser/detect.test.ts
@@ -56,6 +56,18 @@ describe("attach-running browser detection", () => {
     expect(roots[0]?.root).toContain("Google/Chrome");
   });
 
+  test("keeps Linux Chrome beta and unstable roots for cookie discovery", () => {
+    const roots = resolveAttachRunningProfileRoots("linux", "/home/peter");
+
+    expect(roots.map((entry) => entry.root)).toEqual(
+      expect.arrayContaining([
+        "/home/peter/.config/google-chrome",
+        "/home/peter/.config/google-chrome-beta",
+        "/home/peter/.config/google-chrome-unstable",
+      ]),
+    );
+  });
+
   test("discovers DevToolsActivePort files recursively and derives profile roots", async () => {
     const homeDir = await fs.mkdtemp(path.join(os.tmpdir(), "oracle-detect-"));
     tempDirs.push(homeDir);
diff --git a/tests/cli/browserConfig.test.ts b/tests/cli/browserConfig.test.ts
index 18e940045..f87518340 100644
--- a/tests/cli/browserConfig.test.ts
+++ b/tests/cli/browserConfig.test.ts
@@ -175,14 +175,24 @@ describe("buildBrowserConfig", () => {
     ).rejects.toThrow(/attach-running/i);
   });
 
-  test("allows remote-chrome as an attach-running hint", async () => {
+  test("allows loopback remote-chrome as an attach-running hint", async () => {
     const config = await buildBrowserConfig({
       model: "gpt-5.2-pro",
       browserAttachRunning: true,
-      remoteChrome: "remote-host:9333",
+      remoteChrome: "127.0.0.1:9333",
     });
     expect(config.attachRunning).toBe(true);
-    expect(config.remoteChrome).toEqual({ host: "remote-host", port: 9_333 });
+    expect(config.remoteChrome).toEqual({ host: "127.0.0.1", port: 9_333 });
+  });
+
+  test("rejects non-loopback remote-chrome targets when attach-running is enabled", async () => {
+    await expect(
+      buildBrowserConfig({
+        model: "gpt-5.2-pro",
+        browserAttachRunning: true,
+        remoteChrome: "remote-host:9333",
+      }),
+    ).rejects.toThrow(/local loopback attach hints/i);
   });
 
   test("normalizes chatgpt-url alias and adds https when missing", async () => {