diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index bba1a258..e778d0fc 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -24,6 +24,21 @@
         "./skills/browser"
       ]
     },
+    {
+      "name": "browser-swarm",
+      "source": "./",
+      "description": "Coordinate multiple browser agents in one real Chrome profile through a Chrome extension bridge, colored tab group, and target-bound browse CLI endpoints.",
+      "version": "0.0.1",
+      "author": {
+        "name": "Browserbase"
+      },
+      "category": "automation",
+      "keywords": ["browser", "swarm", "chrome-extension", "tab-groups", "stagehand", "understudy", "browse-cli"],
+      "strict": false,
+      "skills": [
+        "./skills/browser-swarm"
+      ]
+    },
     {
       "name": "functions",
       "source": "./",
diff --git a/README.md b/README.md
index 723da7ca..7bddebd9 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,7 @@ This plugin includes the following skills (see `skills/` for details):
 | Skill | Description |
 |-------|-------------|
 | [browser](skills/browser/SKILL.md) | Automate web browser interactions via CLI commands — supports remote Browserbase sessions with anti-bot stealth, CAPTCHA solving, and residential proxies |
+| [browser-swarm](skills/browser-swarm/SKILL.md) | Coordinate multiple browser agents in one real Chrome profile through a Chrome extension bridge, colored tab group, and target-bound browse CLI endpoints |
 | [browserbase-cli](skills/browserbase-cli/SKILL.md) | Use the official `bb` CLI for Browserbase Functions and platform API workflows including sessions, projects, contexts, extensions, fetch, and dashboard |
 | [functions](skills/functions/SKILL.md) | Deploy serverless browser automation to Browserbase cloud using the `bb` CLI |
 | [site-debugger](skills/site-debugger/SKILL.md) | Diagnose and fix failing browser automations — analyzes bot detection, selectors, timing, auth, and captchas, then generates a tested site playbook |
diff --git a/skills/browser-swarm/SKILL.md b/skills/browser-swarm/SKILL.md
new file mode 100644
index 00000000..d939aef2
--- /dev/null
+++ b/skills/browser-swarm/SKILL.md
@@ -0,0 +1,328 @@
+---
+name: browser-swarm
+description: Coordinate multiple browser agents in one real Chromium-family profile through a Chrome extension bridge, browser-managed tabs, and target-bound browse CLI endpoints.
+compatibility: "Requires Node.js 20+, a Chromium-family browser with extension support, the browse CLI with --cdp and --session support, a locally loaded browser-swarm Chrome extension, and the /browser skill for CLI command reference."
+license: MIT
+allowed-tools: Bash
+---
+
+# Browser Swarm
+
+Use this skill when one task benefits from several independent browser workstreams that should share the user's real browser profile, cookies, and extensions.
+
+The top-level agent owns the user intent, decomposition, business logic, synthesis, and approval gates. Worker agents own one bounded browser workstream each. The browser-swarm adapter owns the worker-to-tab mapping and gives each worker a scoped browser capability.
+
+This is tab capability isolation, not full browser identity isolation. All workers share the same real browser profile, cookies, local storage, extensions, and logged-in user state. The isolation promise is that each worker's browse endpoint exposes only its assigned tab.
+
+## Architecture
+
+The swarm has three parts:
+
+1. A local adapter script in `scripts/swarm-relay.mjs`.
+2. A Manifest V3 Chrome extension in `extension/`.
+3. One unique `browse --session <worker-session> --cdp <target-bound-url>` context per worker.
+
+Flow:
+
+```text
+top-level agent
+  -> starts/checks browser-swarm adapter
+  -> ensures N labeled tabs
+  -> spawns worker agents with one command contract each
+  <- receives evidence and synthesizes final answer
+
+worker agent
+  -> browse ... --session <worker-session> --cdp <target-bound-url>
+  -> sees only its assigned tab
+```
+
+The extension is browser transport and tab control. The `browse` CLI remains the worker-facing browser API. The adapter exposes one target-bound CDP URL per tab so each worker keeps a stable active-page model without cross-agent tab races. Chrome tab groups are only visual organization when the browser supports them cleanly; they are not part of the isolation boundary.
+
+## Setup
+
+From the skills repo:
+
+```bash
+cd skills/browser-swarm
+npm install
+```
+
+Start the real-browser setup helper:
+
+```bash
+node scripts/setup-real-browser.mjs
+```
+
+## Readiness Check
+
+Before creating a swarm, the top-level agent must verify that the local adapter and browser extension are ready:
+
+```bash
+curl -s http://127.0.0.1:19989/health
+```
+
+If the relay is down, start the real-browser setup helper:
+
+```bash
+node scripts/setup-real-browser.mjs
+```
+
+If the relay is up but `extensionConnected` is `false`, guide the user through the manual extension install instead of trying to install silently:
+
+```text
+I need the Browser Swarm extension loaded in the browser you want controlled.
+
+In Arc or Chrome:
+1. Enable Developer Mode.
+2. Click "Load unpacked".
+3. Select:
+   <printed skills/browser-swarm/extension path>
+4. Leave this setup command running until extensionConnected is true.
+```
+
+For Arc specifically:
+
+```bash
+node scripts/setup-real-browser.mjs --browser arc
+```
+
+For Chrome specifically:
+
+```bash
+node scripts/setup-real-browser.mjs --browser chrome
+```
+
+Proceed to `Create A Swarm` only after `/health` reports `extensionConnected: true`.
+
+### Real Browser Mode
+
+Use this mode when the user wants the swarm in their own browser profile, for example Arc, Chrome, Chrome Canary, Chromium, or Chrome for Testing.
+
+By default the helper opens `chrome://extensions` through the OS URL opener using the cross-platform `open` package. On a user's machine this should land in their default Chromium-family browser; for example Arc may route it to `arc://extensions`. This is not profile detection. If the opened browser/profile is not the one the user wants controlled, stop and rerun with an explicit browser.
+
+The setup helper starts the relay if needed, opens the extension management page, prints the unpacked extension path, and waits until the extension connects:
+
+```bash
+node scripts/setup-real-browser.mjs
+node scripts/setup-real-browser.mjs --browser arc
+node scripts/setup-real-browser.mjs --browser chrome
+node scripts/setup-real-browser.mjs --browser canary
+node scripts/setup-real-browser.mjs --browser chromium
+node scripts/setup-real-browser.mjs --browser chrome-for-testing
+node scripts/setup-real-browser.mjs --extensions-url arc://extensions
+```
+
+The user must still approve/install the extension in the browser they want controlled:
+
+1. Enable developer mode if needed.
+2. Click "Load unpacked".
+3. Select the printed `skills/browser-swarm/extension` path.
+4. Wait for the helper or confirm manually:
+
+```bash
+curl -s http://127.0.0.1:19989/health
+```
+
+Proceed only when `extensionConnected` is `true`. If it is false, ask the user to confirm the extension is installed and enabled in the chosen browser/profile.
+When validating a recently changed extension, also check `/health` for the extension version:
+
+```json
+{
+  "extension": {
+    "name": "browser-swarm",
+    "version": "0.1.1"
+  }
+}
+```
+
+If the version is stale, reload Browser Swarm Bridge in the browser's extension manager before testing behavior. If `/health` still reports the old version after reload or the browser's extension Update button, restart the browser to force the MV3 service worker registration to refresh before judging the changed extension.
+
+For Arc stale-worker diagnostics, use the read-only profile scanner:
+
+```bash
+npm run diagnose:arc-worker -- --json
+```
+
+`STALE_ARC_SERVICE_WORKER_REGISTRATION` means Arc's profile still has the old Browser Swarm service-worker registration even though the unpacked manifest has changed. Restart Arc, confirm `/health` reports the expected extension version, then rerun the relevant Arc e2e gate.
+
+Do not try to install an unpacked extension into an already-running personal browser profile without the user's approval. The only automated install path in this POC is launching a separate browser process with `--load-extension`, which creates a separate test browser rather than using the user's active browser.
+
+The default supported relay port is `19989`. The current extension connects to that port by default; non-default ports are only supported after the extension has been explicitly configured to use that port.
+
+Arc Spaces caveat: Arc is Chromium-based, but Arc Spaces are not Chrome tab groups. In Arc real-browser mode, create swarms with `--no-group` so the extension never calls `chrome.tabGroups.*` or `chrome.tabs.group`. Worker isolation still comes from target-bound endpoints, not from Arc's visual grouping.
+
+After changing the extension files, manually reload Browser Swarm Bridge in `arc://extensions` before judging Arc behavior. If pointer or keyboard submission is inconsistent in Arc background tabs, prefer DOM-level writes such as `browse fill` followed by a target-bound `browse eval 'document.querySelector("form").requestSubmit()'`, or serialize the irreversible action through the top-level harness.
+
+To smoke-test Arc-safe writes without restarting Arc, use the serialized-click e2e. It requires the Arc extension to be connected on the default relay port and refuses to reuse existing swarm targets unless `BROWSER_SWARM_ALLOW_EXISTING_TARGETS=1` is set:
+
+```bash
+BROWSER_SWARM_BROWSE_BIN=<browse-cli> npm run e2e:arc-serialized-click
+```
+
+To verify Arc's latest extension-level parallel input queue, use the parallel-click e2e after `/health` reports the connected extension version matches the unpacked manifest version. This command intentionally exits `3` with `BLOCKED_STALE_EXTENSION` when Arc is still running an old MV3 service worker:
+
+```bash
+BROWSER_SWARM_BROWSE_BIN=<browse-cli> npm run e2e:arc-parallel-click
+```
+
+Treat `e2e:arc-parallel-click` as the acceptance gate for Arc parallel pointer input. A `PASS` means parallel same-page pointer-click submission worked against the active Arc extension worker. `BLOCKED_STALE_EXTENSION` means Arc did not load the current unpacked worker yet; reload Browser Swarm Bridge or restart Arc, confirm `/health` shows the expected version, then rerun the same command.
+
+### Disposable Test Browser Mode
+
+Use this mode only for e2e tests, demos, and throwaway profiles. It launches a separate browser profile:
+
+```bash
+node scripts/launch-chrome.mjs
+node scripts/launch-chrome.mjs --relay-port 19990
+```
+
+The relay listens only on `127.0.0.1`. Use `--relay-port` when another installed Browser Swarm extension, for example Arc, is already connected to the default port; the launcher creates a temporary extension copy pointed at the requested port.
+
+## Prerequisites
+
+The `/browser` skill contains the canonical `browse` CLI command reference. Ensure it is installed, then read it:
+
+```bash
+# Install if not already present
+npx skills add browserbase/skills --skill browser -a '*' -g -y
+
+# Load the command reference into context
+cat ~/.agents/skills/browser/SKILL.md
+```
+
+Use only commands from that reference and the worker contract below. Do not invent flags or subcommands.
+
+## Create A Swarm
+
+Allocate one tab per workstream:
+
+```bash
+node scripts/swarm-relay.mjs ensure \
+  --count 3 \
+  --label flights \
+  --label rentals \
+  --label dinner \
+  --url "https://www.google.com/travel/flights" \
+  --url "https://www.google.com/search?q=san+diego+surfing+rentals+downtown" \
+  --url "https://www.kayak.com/San-Diego.10760.guide" \
+  --json
+```
+
+The response contains a `wsUrl` per target. The top-level agent must create one unique browse session name per worker and hand exactly one `wsUrl` plus one session name to each worker.
+
+When the controlled browser is Arc, always disable visual tab grouping:
+
+```bash
+node scripts/swarm-relay.mjs ensure \
+  --no-group \
+  --count 2 \
+  --label research-a \
+  --label research-b \
+  --json
+```
+
+Session naming pattern:
+
+```text
+bs-<label>-<short-id>
+```
+
+Keep session names short, preferably under 32 characters. Very long session names can make the browse CLI fail while waiting for its driver-daemon socket.
+
+## Worker Contract
+
+Every worker must:
+
+- Use only its assigned `wsUrl` by passing `--cdp "<wsUrl>"` on every `browse` command.
+- Use only its assigned session by passing `--session "<session>"` on every `browse` command.
+- Keep the assigned session name short, preferably under 32 characters.
+- Never use `browse tab new`, `browse tab close`, or `browse tab switch`.
+- Only use commands documented in the `/browser` skill.
+- Do not call the relay's raw WebSocket endpoint, `/swarm/*` HTTP endpoints, `curl`, or ad hoc Node/WebSocket scripts from a worker. Raw CDP and relay-admin probes belong to the top-level harness only.
+- Do not probe for commands during the run. If a command shape is needed, use the examples below or the bundled `/browser` reference before spawning the worker.
+- Quote CSS selectors that contain shell-special characters, such as `"#box"` and `"#submit"`, whenever invoking `browse` through a shell.
+- Return concrete evidence: final URL, title, useful extracted facts, and screenshot path when relevant.
+- Report `tabCount` only from `browse tab list` using the assigned `--session` and target-bound `--cdp`; it should be `1` for a correctly scoped worker endpoint.
+- Avoid irreversible actions such as purchases, reservations, or form submission without explicit user confirmation.
+
+The top-level harness should launch independent workers in parallel and require a structured final report from each worker. The minimum report is:
+
+```json
+{
+  "status": "ok",
+  "label": "<worker-label>",
+  "currentAction": "<what the worker just did>",
+  "title": "<final page title>",
+  "url": "<final page URL>",
+  "tabCount": 1,
+  "targetId": "<assigned target id>",
+  "evidence": ["<facts, paths, or extracted values>"]
+}
+```
+
+The harness should verify important worker claims through the same target-bound endpoint before synthesizing the final answer.
+
+Worker prompt shape:
+
+```text
+You own the "<label>" browser-swarm tab.
+
+For every browse command, include both flags exactly:
+--session "<session>"
+--cdp "<wsUrl>"
+
+Use a short session name, for example "bs-<label>-<id>".
+
+<Include the Commands section from ~/.agents/skills/browser/SKILL.md here>
+
+Do not create, close, or switch tabs. Do not use any other browser target.
+Do not use raw WebSocket scripts, curl relay endpoints, or /swarm/* admin endpoints. Only use browse commands.
+Do not invent browse flags or commands. Use "tab list", not "pages". Use "screenshot --path <path>", not "screenshot <path>".
+When running through a shell, quote CSS selectors such as "#box" and "#submit".
+Set tabCount from "browse tab list" on your assigned endpoint. It should be 1.
+Find options, collect evidence, and report concise structured results.
+```
+
+Example worker commands:
+
+```bash
+browse get title --session "browser-swarm-flights-a1b2c3d4" --cdp "ws://127.0.0.1:19989/devtools/browser/<targetId>"
+browse get url --session "browser-swarm-flights-a1b2c3d4" --cdp "ws://127.0.0.1:19989/devtools/browser/<targetId>"
+browse snapshot --compact --session "browser-swarm-flights-a1b2c3d4" --cdp "ws://127.0.0.1:19989/devtools/browser/<targetId>"
+browse fill "#box" "worker-value" --session "browser-swarm-flights-a1b2c3d4" --cdp "ws://127.0.0.1:19989/devtools/browser/<targetId>"
+browse click "#submit" --session "browser-swarm-flights-a1b2c3d4" --cdp "ws://127.0.0.1:19989/devtools/browser/<targetId>"
+browse tab list --session "browser-swarm-flights-a1b2c3d4" --cdp "ws://127.0.0.1:19989/devtools/browser/<targetId>"
+browse screenshot --path /tmp/browser-swarm/flights.png --session "browser-swarm-flights-a1b2c3d4" --cdp "ws://127.0.0.1:19989/devtools/browser/<targetId>"
+```
+
+## Offsite Pattern
+
+For a task like "plan an offsite to San Diego next week - we need flights booked, surfing rentals and dinner near downtown":
+
+1. Create three tabs: `flights`, `rentals`, `dinner`.
+2. Spawn one worker per tab.
+3. Assign `flights` to Google Flights or Kayak flights.
+4. Assign `rentals` to San Diego surf rental search/results.
+5. Assign `dinner` to restaurants near downtown San Diego.
+6. Aggregate worker evidence into one plan and list any actions requiring approval before booking.
+
+## Adapter Isolation Contract
+
+The adapter must preserve the worker-owned-tab model:
+
+- `Target.getTargets` on a target-bound endpoint returns only the assigned tab.
+- `Target.getTargetInfo` and `Target.attachToTarget` reject sibling target IDs.
+- Worker endpoints reject tab creation and closing. Tab lifecycle belongs to the top-level browser-swarm harness.
+- Events are forwarded only to clients that own the event target.
+
+This contract is what keeps subagents from racing over Chrome's active tab state. If a worker is handed a raw, unscoped ModCDP or browser CDP endpoint, this isolation contract no longer holds.
+
+## Future ModCDP Substrate
+
+ModCDP is a promising replacement for the hand-rolled extension transport and CDP forwarding code. Do not make workers connect directly to a generic ModCDP proxy as the final browser-swarm interface. The final shape should remain:
+
+```text
+browse CLI -> browser-swarm adapter -> ModCDP or extension transport -> real browser tab
+```
+
+ModCDP should become the lower-level substrate only after an adapter spike proves it can preserve the target-bound worker isolation behavior above.
diff --git a/skills/browser-swarm/extension/manifest.json b/skills/browser-swarm/extension/manifest.json
new file mode 100644
index 00000000..bfd4fb12
--- /dev/null
+++ b/skills/browser-swarm/extension/manifest.json
@@ -0,0 +1,26 @@
+{
+  "manifest_version": 3,
+  "name": "Browser Swarm Bridge",
+  "version": "0.1.1",
+  "description": "Bridge a scoped Chrome tab group to browser-swarm agents through localhost.",
+  "permissions": [
+    "alarms",
+    "debugger",
+    "storage",
+    "tabGroups",
+    "tabs"
+  ],
+  "host_permissions": [
+    "<all_urls>"
+  ],
+  "background": {
+    "service_worker": "service-worker-v0-1-1.js",
+    "type": "module"
+  },
+  "action": {
+    "default_title": "Browser Swarm Bridge"
+  },
+  "content_security_policy": {
+    "extension_pages": "script-src 'self'; connect-src 'self' ws://127.0.0.1:* http://127.0.0.1:*; object-src 'none';"
+  }
+}
diff --git a/skills/browser-swarm/extension/service-worker-v0-1-1.js b/skills/browser-swarm/extension/service-worker-v0-1-1.js
new file mode 100644
index 00000000..e91a3ae3
--- /dev/null
+++ b/skills/browser-swarm/extension/service-worker-v0-1-1.js
@@ -0,0 +1,488 @@
+const DEFAULT_PORT = 19989;
+const GROUP_TITLE = "browser-swarm";
+const GROUP_COLOR = "cyan";
+const RECONNECT_MS = 2000;
+const CHROME_API_TIMEOUT_MS = 5000;
+
+let ws = null;
+let connectTimer = null;
+let autoAttachParams = null;
+let nextSyntheticSession = 1;
+let inputCommandQueue = Promise.resolve();
+const targetsByTab = new Map();
+const childSessions = new Map();
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function send(message) {
+  if (ws?.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify(message));
+  }
+}
+
+function withTimeout(promise, label, timeoutMs = CHROME_API_TIMEOUT_MS) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      setTimeout(() => reject(new Error(`Timed out waiting for ${label}`)), timeoutMs);
+    })
+  ]);
+}
+
+async function tryChromeApi(label, promise, fallback) {
+  try {
+    return await withTimeout(promise, label);
+  } catch (error) {
+    send({
+      type: "warning",
+      label,
+      message: error instanceof Error ? error.message : String(error)
+    });
+    return fallback;
+  }
+}
+
+function scheduleConnect() {
+  if (connectTimer) return;
+  connectTimer = setTimeout(() => {
+    connectTimer = null;
+    connect();
+  }, RECONNECT_MS);
+}
+
+async function connect() {
+  if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) return;
+
+  const { port = DEFAULT_PORT } = await chrome.storage.local.get({ port: DEFAULT_PORT });
+  const socket = new WebSocket(`ws://127.0.0.1:${port}/extension`);
+  ws = socket;
+
+  socket.onopen = async () => {
+    send({
+      type: "hello",
+      extension: "browser-swarm",
+      id: chrome.runtime.id,
+      version: chrome.runtime.getManifest().version,
+      serviceWorker: chrome.runtime.getManifest().background?.service_worker || null,
+      targets: await listAttachedTargets()
+    });
+  };
+
+  socket.onmessage = async (event) => {
+    let message;
+    try {
+      message = JSON.parse(event.data);
+    } catch (error) {
+      return;
+    }
+
+    if (message.type !== "request") return;
+
+    try {
+      const result = await handleRequest(message);
+      send({ type: "response", id: message.id, result });
+    } catch (error) {
+      send({
+        type: "response",
+        id: message.id,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  };
+
+  socket.onclose = () => {
+    if (ws === socket) ws = null;
+    scheduleConnect();
+  };
+
+  socket.onerror = () => {
+    try {
+      socket.close();
+    } catch {}
+  };
+}
+
+async function handleRequest(message) {
+  const { method, params = {} } = message;
+
+  switch (method) {
+    case "ensureTabs":
+      return ensureTabs(params);
+    case "listTargets":
+      return { targets: await listAttachedTargets() };
+    case "forwardCDPCommand":
+      return forwardCDPCommand(params);
+    case "createTarget":
+      return createTarget(params);
+    case "closeTarget":
+      return closeTarget(params);
+    default:
+      throw new Error(`Unknown extension method: ${method}`);
+  }
+}
+
+async function ensureTabs(params) {
+  const count = Number(params.count || 1);
+  const labels = Array.isArray(params.labels) ? params.labels : [];
+  const urls = Array.isArray(params.urls) ? params.urls : [];
+  const groupDisabled = isGroupDisabled(params);
+  const title = groupDisabled
+    ? null
+    : typeof params.groupTitle === "string" ? params.groupTitle : GROUP_TITLE;
+  const color = typeof params.groupColor === "string" ? params.groupColor : GROUP_COLOR;
+
+  let groupId = null;
+  let tabs = [];
+  if (groupDisabled) {
+    tabs = await managedTabs();
+  } else {
+    groupId = await findGroup(title);
+    tabs = groupId === null
+      ? []
+      : await tryChromeApi("chrome.tabs.query(group)", chrome.tabs.query({ groupId }), []);
+  }
+
+  while (tabs.length < count) {
+    const index = tabs.length;
+    const url = urls[index] || "about:blank";
+    const tab = await withTimeout(chrome.tabs.create({ url, active: index === 0 }), "chrome.tabs.create");
+    tabs.push(tab);
+  }
+
+  const tabIds = tabs.map((tab) => tab.id).filter((id) => typeof id === "number");
+  if (!groupDisabled && tabIds.length > 0) {
+    groupId = await ensureGroup(tabIds, title, color, groupId);
+  }
+
+  const attached = [];
+  for (let i = 0; i < Math.min(count, tabs.length); i++) {
+    const tab = tabs[i];
+    if (!tab.id) continue;
+    if (urls[i] && tab.url !== urls[i] && !tab.url?.startsWith(urls[i])) {
+      await withTimeout(chrome.tabs.update(tab.id, { url: urls[i], active: i === 0 }), "chrome.tabs.update");
+      await waitForTabLoad(tab.id, 15000).catch(() => {});
+    }
+    const target = await attachTab(tab.id, labels[i] || `tab-${i + 1}`);
+    attached.push(target);
+  }
+
+  if (!groupDisabled) {
+    await syncGroupForAttached(title, color);
+  }
+  return { groupId, groupDisabled, targets: attached };
+}
+
+async function findGroup(title) {
+  const groups = await tryChromeApi("chrome.tabGroups.query", chrome.tabGroups.query({ title }), []);
+  return groups.length > 0 ? groups[0].id : null;
+}
+
+function isGroupDisabled(params = {}) {
+  return params.groupDisabled === true || params.groupTitle === null || params.groupTitle === false;
+}
+
+async function managedTabs() {
+  const tabs = [];
+  for (const tabId of targetsByTab.keys()) {
+    const tab = await tryChromeApi("chrome.tabs.get", chrome.tabs.get(tabId), null);
+    if (tab) {
+      tabs.push(tab);
+    } else {
+      targetsByTab.delete(tabId);
+    }
+  }
+  return tabs;
+}
+
+async function ensureGroup(tabIds, title, color, existingGroupId = null) {
+  if (tabIds.length === 0) return existingGroupId;
+  const groupId = existingGroupId === null
+    ? await tryChromeApi("chrome.tabs.group", chrome.tabs.group({ tabIds }), null)
+    : await tryChromeApi("chrome.tabs.group", chrome.tabs.group({ tabIds, groupId: existingGroupId }), existingGroupId);
+  if (groupId !== null) {
+    await tryChromeApi(
+      "chrome.tabGroups.update",
+      chrome.tabGroups.update(groupId, { title, color, collapsed: false }),
+      null
+    );
+  }
+  return groupId;
+}
+
+async function syncGroupForAttached(title, color) {
+  const tabIds = Array.from(targetsByTab.keys());
+  if (tabIds.length === 0) return;
+
+  let groupId = await findGroup(title);
+  await ensureGroup(tabIds, title, color, groupId);
+}
+
+async function waitForTabLoad(tabId, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const tab = await withTimeout(chrome.tabs.get(tabId), "chrome.tabs.get");
+    if (tab.status === "complete") return;
+    await sleep(100);
+  }
+}
+
+async function createTarget(params) {
+  const tab = await withTimeout(chrome.tabs.create({
+    url: params.url || "about:blank",
+    active: false
+  }), "chrome.tabs.create");
+  if (!tab.id) throw new Error("Chrome did not return a tab id");
+  await waitForTabLoad(tab.id, 15000).catch(() => {});
+  const target = await attachTab(tab.id, params.label || "created");
+  if (!isGroupDisabled(params)) {
+    await syncGroupForAttached(params.groupTitle || GROUP_TITLE, params.groupColor || GROUP_COLOR);
+  }
+  return { targetId: target.targetId, target };
+}
+
+async function closeTarget(params) {
+  const target = findTarget(params);
+  if (!target) return { success: false };
+  await withTimeout(chrome.tabs.remove(target.tabId), "chrome.tabs.remove");
+  targetsByTab.delete(target.tabId);
+  return { success: true };
+}
+
+function findTarget(params) {
+  if (params.tabId && targetsByTab.has(params.tabId)) return targetsByTab.get(params.tabId);
+  if (params.targetId) {
+    for (const target of targetsByTab.values()) {
+      if (target.targetId === params.targetId) return target;
+    }
+  }
+  if (params.sessionId) {
+    for (const target of targetsByTab.values()) {
+      if (target.sessionId === params.sessionId) return target;
+    }
+    const child = childSessions.get(params.sessionId);
+    if (child) return targetsByTab.get(child.tabId);
+  }
+  return null;
+}
+
+async function attachTab(tabId, label) {
+  const existing = targetsByTab.get(tabId);
+  if (existing?.state === "connected") {
+    return existing;
+  }
+
+  const debuggee = { tabId };
+  try {
+    await withTimeout(chrome.debugger.attach(debuggee, "1.3"), "chrome.debugger.attach");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes("Another debugger is already attached")) {
+      throw error;
+    }
+  }
+
+  await withTimeout(
+    chrome.debugger.sendCommand(debuggee, "Page.enable"),
+    "chrome.debugger.sendCommand(Page.enable)"
+  ).catch(() => {});
+  await withTimeout(
+    chrome.debugger.sendCommand(debuggee, "Runtime.enable"),
+    "chrome.debugger.sendCommand(Runtime.enable)"
+  ).catch(() => {});
+
+  if (autoAttachParams) {
+    await withTimeout(
+      chrome.debugger.sendCommand(debuggee, "Target.setAutoAttach", autoAttachParams),
+      "chrome.debugger.sendCommand(Target.setAutoAttach)"
+    ).catch(() => {});
+  }
+
+  const info = await withTimeout(
+    chrome.debugger.sendCommand(debuggee, "Target.getTargetInfo"),
+    "chrome.debugger.sendCommand(Target.getTargetInfo)"
+  );
+  const targetInfo = normalizeTargetInfo(info.targetInfo, tabId);
+  const sessionId = existing?.sessionId || `swarm-tab-${Date.now().toString(36)}-${nextSyntheticSession++}`;
+  const target = {
+    tabId,
+    label,
+    sessionId,
+    targetId: targetInfo.targetId,
+    targetInfo,
+    state: "connected"
+  };
+  targetsByTab.set(tabId, target);
+  return target;
+}
+
+function normalizeTargetInfo(info, tabId) {
+  return {
+    targetId: info?.targetId || `tab-${tabId}`,
+    type: info?.type || "page",
+    title: info?.title || "",
+    url: info?.url || "about:blank",
+    attached: true,
+    canAccessOpener: false,
+    browserContextId: info?.browserContextId
+  };
+}
+
+async function listAttachedTargets() {
+  const targets = [];
+  for (const [tabId, target] of targetsByTab.entries()) {
+    try {
+      const info = await withTimeout(
+        chrome.debugger.sendCommand({ tabId }, "Target.getTargetInfo"),
+        "chrome.debugger.sendCommand(Target.getTargetInfo)"
+      );
+      const targetInfo = normalizeTargetInfo(info.targetInfo, tabId);
+      const updated = { ...target, targetId: targetInfo.targetId, targetInfo };
+      targetsByTab.set(tabId, updated);
+      targets.push(updated);
+    } catch {
+      targetsByTab.delete(tabId);
+    }
+  }
+  return targets;
+}
+
+async function forwardCDPCommand(params) {
+  const target = findTarget(params);
+  if (!target) {
+    throw new Error(`No browser-swarm tab for ${JSON.stringify({
+      targetId: params.targetId,
+      sessionId: params.sessionId,
+      tabId: params.tabId
+    })}`);
+  }
+
+  if (params.method === "Target.setAutoAttach" && !params.sessionId) {
+    autoAttachParams = params.params || {};
+    await Promise.all(Array.from(targetsByTab.keys()).map((tabId) =>
+      withTimeout(
+        chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", autoAttachParams),
+        "chrome.debugger.sendCommand(Target.setAutoAttach)"
+      ).catch(() => {})
+    ));
+    return {};
+  }
+
+  const debuggee = { tabId: target.tabId };
+  const childSession = params.sessionId && params.sessionId !== target.sessionId
+    ? params.sessionId
+    : undefined;
+  const debuggerSession = childSession ? { ...debuggee, sessionId: childSession } : debuggee;
+
+  if (params.method === "Runtime.enable") {
+    await withTimeout(
+      chrome.debugger.sendCommand(debuggerSession, "Runtime.disable"),
+      "chrome.debugger.sendCommand(Runtime.disable)"
+    ).catch(() => {});
+  }
+
+  return sendDebuggerCommand(target, debuggerSession, params.method, params.params || {});
+}
+
+function enqueueInputCommand(fn) {
+  const queued = inputCommandQueue.catch(() => {}).then(fn);
+  inputCommandQueue = queued.catch(() => {});
+  return queued;
+}
+
+async function sendDebuggerCommand(target, debuggerSession, method, params) {
+  const sendCommand = async () => {
+    if (method.startsWith("Input.")) {
+      await withTimeout(
+        chrome.tabs.update(target.tabId, { active: true }),
+        "chrome.tabs.update(active input target)"
+      ).catch(() => {});
+    }
+    return withTimeout(
+      chrome.debugger.sendCommand(debuggerSession, method, params),
+      `chrome.debugger.sendCommand(${method})`
+    );
+  };
+
+  if (method.startsWith("Input.")) {
+    return enqueueInputCommand(sendCommand);
+  }
+  return sendCommand();
+}
+
+chrome.debugger.onEvent.addListener((source, method, params) => {
+  const tabId = source.tabId;
+  if (!tabId || !targetsByTab.has(tabId)) return;
+
+  const target = targetsByTab.get(tabId);
+  if (method === "Target.attachedToTarget" && params?.sessionId) {
+    childSessions.set(params.sessionId, {
+      tabId,
+      targetId: params.targetInfo?.targetId
+    });
+  }
+  if (method === "Target.detachedFromTarget" && params?.sessionId) {
+    childSessions.delete(params.sessionId);
+  }
+
+  send({
+    type: "cdpEvent",
+    tabId,
+    targetId: target.targetId,
+    sessionId: source.sessionId || target.sessionId,
+    method,
+    params
+  });
+});
+
+chrome.debugger.onDetach.addListener((source) => {
+  if (!source.tabId) return;
+  const target = targetsByTab.get(source.tabId);
+  targetsByTab.delete(source.tabId);
+  if (target) {
+    send({
+      type: "targetDetached",
+      tabId: source.tabId,
+      targetId: target.targetId,
+      sessionId: target.sessionId
+    });
+  }
+});
+
+chrome.tabs.onRemoved.addListener((tabId) => {
+  const target = targetsByTab.get(tabId);
+  targetsByTab.delete(tabId);
+  if (target) {
+    send({
+      type: "targetDetached",
+      tabId,
+      targetId: target.targetId,
+      sessionId: target.sessionId
+    });
+  }
+});
+
+chrome.alarms.onAlarm.addListener((alarm) => {
+  if (alarm.name === "browser-swarm-heartbeat") {
+    connect();
+    send({ type: "ping" });
+  }
+});
+
+chrome.runtime.onInstalled.addListener(() => {
+  chrome.alarms.create("browser-swarm-heartbeat", { periodInMinutes: 0.1 });
+  connect();
+});
+
+chrome.runtime.onStartup.addListener(() => {
+  chrome.alarms.create("browser-swarm-heartbeat", { periodInMinutes: 0.1 });
+  connect();
+});
+
+chrome.action.onClicked.addListener(() => {
+  connect();
+});
+
+chrome.alarms.create("browser-swarm-heartbeat", { periodInMinutes: 0.1 });
+connect();
diff --git a/skills/browser-swarm/extension/service-worker.js b/skills/browser-swarm/extension/service-worker.js
new file mode 100644
index 00000000..9ddce335
--- /dev/null
+++ b/skills/browser-swarm/extension/service-worker.js
@@ -0,0 +1 @@
+import "./service-worker-v0-1-1.js";
diff --git a/skills/browser-swarm/package-lock.json b/skills/browser-swarm/package-lock.json
new file mode 100644
index 00000000..29329b9f
--- /dev/null
+++ b/skills/browser-swarm/package-lock.json
@@ -0,0 +1,185 @@
+{
+  "name": "@browserbase/browser-swarm-skill",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@browserbase/browser-swarm-skill",
+      "version": "0.1.0",
+      "dependencies": {
+        "open": "^10.2.0",
+        "ws": "^8.18.0"
+      }
+    },
+    "node_modules/bundle-name": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/bundle-name/-/bundle-name-4.1.0.tgz",
+      "integrity": "sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==",
+      "license": "MIT",
+      "dependencies": {
+        "run-applescript": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/default-browser": {
+      "version": "5.5.0",
+      "resolved": "https://registry.npmjs.org/default-browser/-/default-browser-5.5.0.tgz",
+      "integrity": "sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw==",
+      "license": "MIT",
+      "dependencies": {
+        "bundle-name": "^4.1.0",
+        "default-browser-id": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/default-browser-id": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/default-browser-id/-/default-browser-id-5.0.1.tgz",
+      "integrity": "sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/define-lazy-prop": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/define-lazy-prop/-/define-lazy-prop-3.0.0.tgz",
+      "integrity": "sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-docker": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-docker/-/is-docker-3.0.0.tgz",
+      "integrity": "sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==",
+      "license": "MIT",
+      "bin": {
+        "is-docker": "cli.js"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-inside-container": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/is-inside-container/-/is-inside-container-1.0.0.tgz",
+      "integrity": "sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==",
+      "license": "MIT",
+      "dependencies": {
+        "is-docker": "^3.0.0"
+      },
+      "bin": {
+        "is-inside-container": "cli.js"
+      },
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-wsl": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-3.1.1.tgz",
+      "integrity": "sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==",
+      "license": "MIT",
+      "dependencies": {
+        "is-inside-container": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/open": {
+      "version": "10.2.0",
+      "resolved": "https://registry.npmjs.org/open/-/open-10.2.0.tgz",
+      "integrity": "sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA==",
+      "license": "MIT",
+      "dependencies": {
+        "default-browser": "^5.2.1",
+        "define-lazy-prop": "^3.0.0",
+        "is-inside-container": "^1.0.0",
+        "wsl-utils": "^0.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/run-applescript": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/run-applescript/-/run-applescript-7.1.0.tgz",
+      "integrity": "sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.0.tgz",
+      "integrity": "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/wsl-utils": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/wsl-utils/-/wsl-utils-0.1.0.tgz",
+      "integrity": "sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw==",
+      "license": "MIT",
+      "dependencies": {
+        "is-wsl": "^3.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    }
+  }
+}
diff --git a/skills/browser-swarm/package.json b/skills/browser-swarm/package.json
new file mode 100644
index 00000000..64f8c4f9
--- /dev/null
+++ b/skills/browser-swarm/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "@browserbase/browser-swarm-skill",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "serve": "node scripts/swarm-relay.mjs serve",
+    "setup": "node scripts/setup-real-browser.mjs",
+    "launch": "node scripts/launch-chrome.mjs",
+    "diagnose:arc-worker": "node scripts/diagnose-arc-worker.mjs",
+    "e2e": "node scripts/e2e-poc.mjs",
+    "e2e:arc-parallel-click": "node scripts/e2e-arc-parallel-click.mjs",
+    "e2e:arc-serialized-click": "node scripts/e2e-arc-serialized-click.mjs"
+  },
+  "dependencies": {
+    "open": "^10.2.0",
+    "ws": "^8.18.0"
+  }
+}
diff --git a/skills/browser-swarm/scripts/diagnose-arc-worker.mjs b/skills/browser-swarm/scripts/diagnose-arc-worker.mjs
new file mode 100644
index 00000000..3ee50497
--- /dev/null
+++ b/skills/browser-swarm/scripts/diagnose-arc-worker.mjs
@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillDir = resolve(__dirname, "..");
+const manifestPath = resolve(skillDir, "extension", "manifest.json");
+const defaultArcProfile = resolve(
+  process.env.HOME || "",
+  "Library/Application Support/Arc/User Data/Default"
+);
+const fallbackExtensionId = "fnkkfpnldmkoglemodoamghhienkeodp";
+
+function parseArgs(argv) {
+  const opts = {
+    host: process.env.BROWSER_SWARM_HOST || "127.0.0.1",
+    port: Number(process.env.BROWSER_SWARM_PORT || 19989),
+    profile: process.env.BROWSER_SWARM_ARC_PROFILE || defaultArcProfile,
+    extensionId: process.env.BROWSER_SWARM_EXTENSION_ID,
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--host") opts.host = argv[++i];
+    else if (arg === "--port") opts.port = Number(argv[++i]);
+    else if (arg === "--profile") opts.profile = argv[++i];
+    else if (arg === "--extension-id") opts.extensionId = argv[++i];
+    else if (arg === "--json") opts.json = true;
+    else if (arg === "--help" || arg === "-h") {
+      usage();
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return opts;
+}
+
+function usage() {
+  console.log(`Usage: node scripts/diagnose-arc-worker.mjs [--host <host>] [--port <port>] [--profile <arc-profile>] [--extension-id <id>] [--json]
+
+Read-only diagnostic for Arc's Browser Swarm MV3 worker state. It compares:
+- the unpacked extension manifest,
+- the connected relay /health extension version,
+- Arc's Secure Preferences extension registration metadata,
+- Arc's service-worker registration database strings.
+
+It never edits the Arc profile.`);
+}
+
+async function tryHealth(host, port) {
+  try {
+    const response = await fetch(`http://${host}:${port}/health`);
+    if (!response.ok) return { error: `HTTP ${response.status}` };
+    return response.json();
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function readManifest() {
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    serviceWorker: manifest.background?.service_worker || null,
+  };
+}
+
+function walkFiles(dir, files = []) {
+  if (!existsSync(dir)) return files;
+  for (const entry of readdirSync(dir)) {
+    const path = resolve(dir, entry);
+    let stat;
+    try {
+      stat = statSync(path);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) walkFiles(path, files);
+    else if (stat.isFile()) files.push(path);
+  }
+  return files;
+}
+
+function countBuffer(buffer, needle) {
+  if (!needle) return 0;
+  const needleBuffer = Buffer.from(needle);
+  let count = 0;
+  let offset = 0;
+  while (offset < buffer.length) {
+    const found = buffer.indexOf(needleBuffer, offset);
+    if (found === -1) break;
+    count += 1;
+    offset = found + needleBuffer.length;
+  }
+  return count;
+}
+
+function scanServiceWorkerDatabase(profile, expectedWorker, extensionId) {
+  const databaseDir = resolve(profile, "Service Worker", "Database");
+  const oldWorker = "service-worker.js";
+  const extensionOrigin = `chrome-extension://${extensionId}/`;
+  const oldWorkerUrl = `${extensionOrigin}${oldWorker}`;
+  const expectedWorkerUrl = expectedWorker ? `${extensionOrigin}${expectedWorker}` : null;
+  const files = walkFiles(databaseDir);
+  const matches = [];
+
+  for (const file of files) {
+    let buffer;
+    try {
+      buffer = readFileSync(file);
+    } catch {
+      continue;
+    }
+    const extensionHits = countBuffer(buffer, extensionOrigin);
+    const expectedWorkerHits = countBuffer(buffer, expectedWorkerUrl);
+    const oldWorkerHits = expectedWorker === oldWorker ? 0 : countBuffer(buffer, oldWorkerUrl);
+    if (extensionHits || expectedWorkerHits || oldWorkerHits) {
+      matches.push({
+        file,
+        extensionOriginHits: extensionHits,
+        expectedWorkerHits,
+        oldWorkerHits,
+      });
+    }
+  }
+
+  return {
+    databaseDir,
+    exists: existsSync(databaseDir),
+    oldWorkerUrl,
+    expectedWorkerUrl,
+    filesScanned: files.length,
+    matches,
+  };
+}
+
+function readSecurePreferencesRegistration(profile, extensionId) {
+  const securePreferencesPath = resolve(profile, "Secure Preferences");
+  if (!existsSync(securePreferencesPath)) {
+    return {
+      path: securePreferencesPath,
+      exists: false,
+      found: false,
+    };
+  }
+
+  try {
+    const preferences = JSON.parse(readFileSync(securePreferencesPath, "utf8"));
+    const settings = preferences.extensions?.settings?.[extensionId];
+    if (!settings) {
+      return {
+        path: securePreferencesPath,
+        exists: true,
+        found: false,
+      };
+    }
+
+    return {
+      path: securePreferencesPath,
+      exists: true,
+      found: true,
+      extensionPath: settings.path || null,
+      location: settings.location ?? null,
+      hasStartedServiceWorker: settings.has_started_service_worker ?? null,
+      serviceWorkerRegistrationVersion: settings.service_worker_registration_info?.version || null,
+      manifestVersion: settings.manifest?.version || null,
+      manifestServiceWorker: settings.manifest?.background?.service_worker || null,
+      lastUpdateTime: settings.last_update_time || null,
+    };
+  } catch (error) {
+    return {
+      path: securePreferencesPath,
+      exists: true,
+      found: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function summarize({ manifest, health, scan, securePreferences, extensionId }) {
+  const connectedVersion = health?.extension?.version || null;
+  const versionMatches = connectedVersion === manifest.version;
+  const preferenceRegistrationVersion = securePreferences?.serviceWorkerRegistrationVersion || null;
+  const preferenceRegistrationStale = Boolean(
+    preferenceRegistrationVersion &&
+    preferenceRegistrationVersion !== manifest.version
+  );
+  const oldWorkerHits = scan.matches.reduce((sum, match) => sum + match.oldWorkerHits, 0);
+  const expectedWorkerHits = scan.matches.reduce((sum, match) => sum + match.expectedWorkerHits, 0);
+  const staleRegistrationLikely = manifest.serviceWorker !== "service-worker.js"
+    && (
+      (oldWorkerHits > 0 && expectedWorkerHits === 0) ||
+      preferenceRegistrationStale
+    );
+
+  let status = "OK";
+  if (health?.error) status = "RELAY_UNAVAILABLE";
+  else if (!health?.extensionConnected) status = "EXTENSION_DISCONNECTED";
+  else if (!versionMatches && staleRegistrationLikely) status = "STALE_ARC_SERVICE_WORKER_REGISTRATION";
+  else if (!versionMatches) status = "STALE_CONNECTED_EXTENSION";
+
+  return {
+    status,
+    connectedVersion,
+    expectedVersion: manifest.version,
+    extensionId,
+    versionMatches,
+    preferenceRegistrationVersion,
+    preferenceRegistrationStale,
+    expectedWorker: manifest.serviceWorker,
+    oldWorkerHits,
+    expectedWorkerHits,
+    staleRegistrationLikely,
+  };
+}
+
+function printHuman(result) {
+  console.log(`Browser Swarm Arc worker diagnosis
+
+Status:             ${result.summary.status}
+Relay health:       ${result.health?.error ? result.health.error : "available"}
+Connected version:  ${result.summary.connectedVersion || "none"}
+Expected version:   ${result.summary.expectedVersion}
+Expected worker:    ${result.summary.expectedWorker}
+Arc profile:        ${result.arcProfile}
+Prefs registration: ${result.summary.preferenceRegistrationVersion || "none"}
+SW database:        ${result.scan.databaseDir}
+Files scanned:      ${result.scan.filesScanned}
+Old worker hits:    ${result.summary.oldWorkerHits}
+Expected hits:      ${result.summary.expectedWorkerHits}
+`);
+
+  if (result.summary.status === "STALE_ARC_SERVICE_WORKER_REGISTRATION") {
+    console.log("Arc is still registered to the old MV3 service-worker.js. Restart Arc, then rerun this diagnostic and the Arc parallel-click e2e gate.");
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const manifest = readManifest();
+  const health = await tryHealth(opts.host, opts.port);
+  const extensionId = opts.extensionId || health?.extension?.id || fallbackExtensionId;
+  const securePreferences = readSecurePreferencesRegistration(opts.profile, extensionId);
+  const scan = scanServiceWorkerDatabase(opts.profile, manifest.serviceWorker, extensionId);
+  const result = {
+    manifest,
+    health,
+    extensionId,
+    arcProfile: opts.profile,
+    securePreferences,
+    scan,
+    summary: summarize({ manifest, health, scan, securePreferences, extensionId }),
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+
+  if (result.summary.status === "STALE_ARC_SERVICE_WORKER_REGISTRATION") {
+    process.exitCode = 3;
+  } else if (result.summary.status !== "OK") {
+    process.exitCode = 2;
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
diff --git a/skills/browser-swarm/scripts/e2e-arc-click-harness.mjs b/skills/browser-swarm/scripts/e2e-arc-click-harness.mjs
new file mode 100644
index 00000000..b2e1c5ff
--- /dev/null
+++ b/skills/browser-swarm/scripts/e2e-arc-click-harness.mjs
@@ -0,0 +1,340 @@
+import { execFile, spawn, spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { dirname, resolve } from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import WebSocket from "ws";
+
+const execFileP = promisify(execFile);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillDir = resolve(__dirname, "..");
+const manifest = JSON.parse(readFileSync(resolve(skillDir, "extension", "manifest.json"), "utf8"));
+
+const port = Number(process.env.BROWSER_SWARM_PORT || 19989);
+const host = process.env.BROWSER_SWARM_HOST || "127.0.0.1";
+const browseBin = process.env.BROWSER_SWARM_BROWSE_BIN || "browse";
+const allowExistingTargets = process.env.BROWSER_SWARM_ALLOW_EXISTING_TARGETS === "1";
+
+function run(command, args, options = {}) {
+  return execFileP(command, args, {
+    cwd: options.cwd || skillDir,
+    env: { ...process.env, ...(options.env || {}) },
+    maxBuffer: 20_000_000,
+  });
+}
+
+function parseJson(stdout) {
+  return JSON.parse(stdout.trim());
+}
+
+function parseGetField(stdout, field) {
+  const parsed = parseJson(stdout);
+  if (typeof parsed === "string") return parsed;
+  if (parsed && typeof parsed === "object" && field in parsed) return parsed[field];
+  if (parsed && typeof parsed === "object" && "value" in parsed) return parsed.value;
+  return parsed;
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function tryHealth() {
+  try {
+    const response = await fetch(`http://${host}:${port}/health`);
+    if (!response.ok) return null;
+    return response.json();
+  } catch {
+    return null;
+  }
+}
+
+async function waitForHealth(timeoutMs = 20000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const health = await tryHealth();
+    if (health?.extensionConnected) return health;
+    await sleep(500);
+  }
+  throw new Error("Timed out waiting for Arc Browser Swarm extension connection");
+}
+
+async function ensureRelay(relayProcessRef) {
+  const existing = await tryHealth();
+  if (existing) return { started: false, initialHealth: existing };
+
+  relayProcessRef.current = spawn(process.execPath, [
+    "scripts/swarm-relay.mjs",
+    "serve",
+    "--host",
+    host,
+    "--port",
+    String(port),
+  ], {
+    cwd: skillDir,
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+  relayProcessRef.current.stderr.on("data", (chunk) => process.stderr.write(chunk));
+  await sleep(500);
+  return { started: true, initialHealth: await tryHealth() };
+}
+
+function startSamePageServer(titleBase) {
+  const html = `<!doctype html>
+<html>
+  <head><title>${titleBase}</title></head>
+  <body>
+    <form id="form">
+      <label for="box">Worker value</label>
+      <input id="box" name="box" autocomplete="off" autofocus />
+      <button id="submit" type="submit">Submit</button>
+    </form>
+    <output id="result">empty</output>
+    <script>
+      document.getElementById("form").addEventListener("submit", (event) => {
+        event.preventDefault();
+        const value = document.getElementById("box").value;
+        document.body.dataset.workerValue = value;
+        document.getElementById("result").textContent = value;
+        document.title = ${JSON.stringify(titleBase + " ")} + value;
+      });
+    </script>
+  </body>
+</html>`;
+
+  const server = createServer((req, res) => {
+    res.writeHead(200, {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    res.end(html);
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      resolve({ server, url: `http://127.0.0.1:${server.address().port}/same` });
+    });
+  });
+}
+
+async function cdpRoot(method, params = {}) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`ws://${host}:${port}/devtools/browser`);
+    const id = Math.floor(Math.random() * 1_000_000_000);
+    const timer = setTimeout(() => {
+      ws.terminate();
+      reject(new Error(`Timed out waiting for ${method}`));
+    }, 5000);
+
+    ws.once("open", () => ws.send(JSON.stringify({ id, method, params })));
+    ws.on("message", (raw) => {
+      const message = JSON.parse(raw.toString());
+      if (message.id !== id) return;
+      clearTimeout(timer);
+      ws.close();
+      if (message.error) reject(new Error(message.error.message || JSON.stringify(message.error)));
+      else resolve(message.result);
+    });
+    ws.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+function killBrowseDaemons(sessions) {
+  for (const session of sessions) {
+    spawnSync("pkill", ["-f", `daemon --session ${session}`], { stdio: "ignore" });
+  }
+}
+
+export async function runArcClickE2E({
+  titleBase,
+  labels,
+  values,
+  sessionPrefix,
+  requireFreshExtension = false,
+  clickMode,
+}) {
+  let samePageServer;
+  const relayProcessRef = { current: null };
+  let startedRelay = false;
+  let targets = [];
+  let sessions = [];
+
+  async function cleanup() {
+    for (const target of targets) {
+      try {
+        await cdpRoot("Target.closeTarget", { targetId: target.targetId });
+      } catch {}
+    }
+    killBrowseDaemons(sessions);
+    if (samePageServer) samePageServer.close();
+    if (startedRelay && relayProcessRef.current) relayProcessRef.current.kill();
+  }
+
+  try {
+    assert(labels.length === values.length, "Arc click labels and values must have matching lengths");
+    assert(clickMode === "parallel" || clickMode === "sequential", `Unknown Arc click mode: ${clickMode}`);
+
+    const relay = await ensureRelay(relayProcessRef);
+    startedRelay = relay.started;
+    const health = await waitForHealth();
+    const connectedVersion = health.extension?.version || null;
+
+    if (requireFreshExtension && connectedVersion !== manifest.version) {
+      console.log(JSON.stringify({
+        status: "BLOCKED_STALE_EXTENSION",
+        message: "Arc is connected to a stale Browser Swarm service worker. Reload Browser Swarm Bridge or restart Arc, then rerun this command.",
+        diagnosticCommand: "npm run diagnose:arc-worker -- --json",
+        relayStarted: relay.started,
+        expectedExtensionVersion: manifest.version,
+        connectedExtensionVersion: connectedVersion,
+        health,
+      }, null, 2));
+      process.exitCode = 3;
+      return;
+    }
+
+    if (!allowExistingTargets && health.targetCount !== 0) {
+      throw new Error(
+        `Refusing to run Arc click smoke with ${health.targetCount} existing browser-swarm targets. ` +
+        "Close/release them first or set BROWSER_SWARM_ALLOW_EXISTING_TARGETS=1."
+      );
+    }
+
+    const page = await startSamePageServer(titleBase);
+    samePageServer = page.server;
+    const ensure = await run("node", [
+      "scripts/swarm-relay.mjs",
+      "ensure",
+      "--port",
+      String(port),
+      "--host",
+      host,
+      "--no-group",
+      "--count",
+      String(labels.length),
+      ...labels.flatMap((label) => ["--label", label]),
+      ...labels.flatMap(() => ["--url", page.url]),
+      "--json",
+    ]);
+    targets = parseJson(ensure.stdout).targets;
+    assert(targets.length === labels.length, `Expected ${labels.length} Arc targets, got ${targets.length}`);
+
+    sessions = targets.map((target, index) =>
+      `${sessionPrefix}-${index}-${target.targetId.slice(0, 4).toLowerCase()}`
+    );
+
+    const fillResults = await Promise.all(targets.map((target, index) => run(browseBin, [
+      "fill",
+      "#box",
+      values[index],
+      "--session",
+      sessions[index],
+      "--cdp",
+      target.wsUrl,
+    ])));
+
+    let clickResults;
+    if (clickMode === "parallel") {
+      clickResults = await Promise.all(targets.map((target, index) => run(browseBin, [
+        "click",
+        "#submit",
+        "--session",
+        sessions[index],
+        "--cdp",
+        target.wsUrl,
+      ])));
+    } else {
+      clickResults = [];
+      for (let i = 0; i < targets.length; i++) {
+        clickResults.push(await run(browseBin, [
+          "click",
+          "#submit",
+          "--session",
+          sessions[i],
+          "--cdp",
+          targets[i].wsUrl,
+        ]));
+        await sleep(500);
+      }
+    }
+
+    const evidence = [];
+    for (let i = 0; i < targets.length; i++) {
+      const title = parseGetField((await run(browseBin, [
+        "get",
+        "title",
+        "--session",
+        sessions[i],
+        "--cdp",
+        targets[i].wsUrl,
+      ])).stdout, "title");
+      const resultText = parseGetField((await run(browseBin, [
+        "get",
+        "text",
+        "#result",
+        "--session",
+        sessions[i],
+        "--cdp",
+        targets[i].wsUrl,
+      ])).stdout, "text");
+      const inputValue = parseGetField((await run(browseBin, [
+        "get",
+        "value",
+        "#box",
+        "--session",
+        sessions[i],
+        "--cdp",
+        targets[i].wsUrl,
+      ])).stdout, "value");
+      const tabList = parseJson((await run(browseBin, [
+        "tab",
+        "list",
+        "--session",
+        sessions[i],
+        "--cdp",
+        targets[i].wsUrl,
+      ])).stdout);
+
+      assert(tabList.tabs.length === 1, `Expected ${sessions[i]} to see exactly one tab`);
+      assert(tabList.tabs[0].targetId === targets[i].targetId, `Expected ${sessions[i]} target isolation`);
+      assert(title === `${titleBase} ${values[i]}`, `Unexpected title for ${sessions[i]}: ${title}`);
+      assert(resultText === values[i], `Unexpected result text for ${sessions[i]}: ${resultText}`);
+      assert(inputValue === values[i], `Unexpected input value for ${sessions[i]}: ${inputValue}`);
+
+      evidence.push({
+        label: targets[i].label,
+        targetId: targets[i].targetId,
+        session: sessions[i],
+        title,
+        resultText,
+        inputValue,
+        tabCount: tabList.tabs.length,
+      });
+    }
+
+    console.log(JSON.stringify({
+      status: "PASS",
+      relayStarted: relay.started,
+      expectedExtensionVersion: manifest.version,
+      health,
+      samePageUrl: page.url,
+      fillResults: fillResults.map((result) => parseJson(result.stdout)),
+      clickResults: clickResults.map((result) => parseJson(result.stdout)),
+      evidence,
+    }, null, 2));
+  } catch (error) {
+    console.error(error instanceof Error ? error.stack || error.message : String(error));
+    process.exitCode = 1;
+  } finally {
+    await cleanup();
+  }
+}
diff --git a/skills/browser-swarm/scripts/e2e-arc-parallel-click.mjs b/skills/browser-swarm/scripts/e2e-arc-parallel-click.mjs
new file mode 100644
index 00000000..f5592662
--- /dev/null
+++ b/skills/browser-swarm/scripts/e2e-arc-parallel-click.mjs
@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runArcClickE2E } from "./e2e-arc-click-harness.mjs";
+
+await runArcClickE2E({
+  titleBase: "arc-parallel-click-test",
+  labels: ["arc-parallel-a", "arc-parallel-b"],
+  values: ["arc-parallel-alpha", "arc-parallel-beta"],
+  sessionPrefix: "bs-arcpar",
+  requireFreshExtension: true,
+  clickMode: "parallel",
+});
diff --git a/skills/browser-swarm/scripts/e2e-arc-serialized-click.mjs b/skills/browser-swarm/scripts/e2e-arc-serialized-click.mjs
new file mode 100644
index 00000000..5a1535fe
--- /dev/null
+++ b/skills/browser-swarm/scripts/e2e-arc-serialized-click.mjs
@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runArcClickE2E } from "./e2e-arc-click-harness.mjs";
+
+await runArcClickE2E({
+  titleBase: "arc-serialized-click-test",
+  labels: ["arc-serialized-a", "arc-serialized-b"],
+  values: ["arc-serialized-alpha", "arc-serialized-beta"],
+  sessionPrefix: "bs-arcser",
+  requireFreshExtension: false,
+  clickMode: "sequential",
+});
diff --git a/skills/browser-swarm/scripts/e2e-poc.mjs b/skills/browser-swarm/scripts/e2e-poc.mjs
new file mode 100644
index 00000000..79e819fb
--- /dev/null
+++ b/skills/browser-swarm/scripts/e2e-poc.mjs
@@ -0,0 +1,496 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import WebSocket from "ws";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillDir = resolve(__dirname, "..");
+const artifactsDir = "/tmp/browser-swarm-e2e";
+const port = Number(process.env.BROWSER_SWARM_PORT || 19989);
+const browseBin = process.env.BROWSER_SWARM_BROWSE_BIN || "browse";
+const expectedExtension = JSON.parse(readFileSync(resolve(skillDir, "extension", "manifest.json"), "utf8"));
+const workerSessions = [];
+let samePageServer;
+
+mkdirSync(artifactsDir, { recursive: true });
+spawnSync("pkill", ["-f", "/tmp/browser-swarm-e2e-profile"], { stdio: "ignore" });
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || skillDir,
+      env: { ...process.env, ...(options.env || {}) },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => stdout += chunk.toString());
+    child.stderr.on("data", (chunk) => stderr += chunk.toString());
+    child.on("exit", (code) => {
+      const result = { command: [command, ...args].join(" "), code, stdout, stderr };
+      if (code === 0) resolve(result);
+      else reject(Object.assign(new Error(`${result.command} exited ${code}\n${stderr}`), { result }));
+    });
+  });
+}
+
+function parseJson(stdout) {
+  return JSON.parse(stdout.trim());
+}
+
+function parseJsonOrText(stdout) {
+  const text = stdout.trim();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function previewOutput(value) {
+  if (typeof value === "string") return value.slice(0, 500);
+  if (typeof value?.tree === "string") return value.tree.slice(0, 500);
+  return JSON.stringify(value).slice(0, 500);
+}
+
+function parseGetField(stdout, field) {
+  const parsed = parseJson(stdout);
+  if (typeof parsed === "string") return parsed;
+  if (parsed && typeof parsed === "object" && field in parsed) return parsed[field];
+  if (parsed && typeof parsed === "object" && "value" in parsed) return parsed.value;
+  return parsed;
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function startSamePageServer() {
+  const html = `<!doctype html>
+<html>
+  <head><title>same-page-action-test</title></head>
+  <body>
+    <form id="form">
+      <label for="box">Worker value</label>
+      <input id="box" name="box" autocomplete="off" autofocus />
+      <button id="submit" type="submit">Submit</button>
+    </form>
+    <output id="result">empty</output>
+    <script>
+      document.getElementById("form").addEventListener("submit", (event) => {
+        event.preventDefault();
+        const value = document.getElementById("box").value;
+        document.body.dataset.workerValue = value;
+        document.getElementById("result").textContent = value;
+        document.title = "same-page-action-test " + value;
+      });
+    </script>
+  </body>
+</html>`;
+
+  samePageServer = createServer((req, res) => {
+    res.writeHead(200, {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store"
+    });
+    res.end(html);
+  });
+
+  return new Promise((resolve, reject) => {
+    samePageServer.once("error", reject);
+    samePageServer.listen(0, "127.0.0.1", () => {
+      const address = samePageServer.address();
+      resolve(`http://127.0.0.1:${address.port}/same`);
+    });
+  });
+}
+
+async function waitForHealth(timeoutMs = 30000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/health`);
+      const json = await res.json();
+      if (json.extensionConnected) return json;
+    } catch {}
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  throw new Error("Timed out waiting for relay and extension connection");
+}
+
+async function cdpProbe(wsUrl, commands) {
+  const ws = new WebSocket(wsUrl);
+  await new Promise((resolve, reject) => {
+    ws.once("open", resolve);
+    ws.once("error", reject);
+  });
+
+  let nextId = 1;
+  async function send(method, params = {}, sessionId = null) {
+    const id = nextId++;
+    ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+    return new Promise((resolve, reject) => {
+      const onMessage = (raw) => {
+        const message = JSON.parse(raw.toString());
+        if (message.id !== id) return;
+        ws.off("message", onMessage);
+        resolve(message);
+      };
+      ws.on("message", onMessage);
+      setTimeout(() => {
+        ws.off("message", onMessage);
+        reject(new Error(`Timed out waiting for ${method}`));
+      }, 5000).unref();
+    });
+  }
+
+  try {
+    const results = {};
+    for (const command of commands) {
+      const sessionId = command.sessionIdFrom
+        ? results[command.sessionIdFrom]?.result?.sessionId
+        : command.sessionId;
+      results[command.name] = await send(command.method, command.params || {}, sessionId);
+    }
+    return results;
+  } finally {
+    ws.close();
+  }
+}
+
+async function cdpRootLifecycle(wsUrl, createUrl) {
+  const ws = new WebSocket(wsUrl);
+  await new Promise((resolve, reject) => {
+    ws.once("open", resolve);
+    ws.once("error", reject);
+  });
+
+  let nextId = 1;
+  const events = [];
+  const onAnyMessage = (raw) => {
+    const message = JSON.parse(raw.toString());
+    if (message.method) events.push(message);
+  };
+  ws.on("message", onAnyMessage);
+
+  async function send(method, params = {}, sessionId = null) {
+    const id = nextId++;
+    ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+    return new Promise((resolve, reject) => {
+      const onMessage = (raw) => {
+        const message = JSON.parse(raw.toString());
+        if (message.id !== id) return;
+        ws.off("message", onMessage);
+        resolve(message);
+      };
+      ws.on("message", onMessage);
+      setTimeout(() => {
+        ws.off("message", onMessage);
+        reject(new Error(`Timed out waiting for ${method}`));
+      }, 5000).unref();
+    });
+  }
+
+  try {
+    const before = await send("Target.getTargets");
+    const attachTargetId = before.result?.targetInfos?.[0]?.targetId;
+    const attach = attachTargetId
+      ? await send("Target.attachToTarget", { targetId: attachTargetId, flatten: true })
+      : null;
+    const sessionId = attach?.result?.sessionId;
+    assert(sessionId, `Expected root attachToTarget to return a sessionId: ${JSON.stringify(attach)}`);
+    const created = await send("Target.createTarget", { url: createUrl }, sessionId);
+    const createdTargetId = created.result?.targetId;
+    assert(createdTargetId, `Expected root createTarget to return a targetId: ${JSON.stringify(created)}`);
+    const afterCreate = await send("Target.getTargets");
+    const closed = await send("Target.closeTarget", { targetId: createdTargetId }, sessionId);
+    const afterClose = await send("Target.getTargets");
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    const detachEvents = events.filter((event) =>
+      event.method === "Target.detachedFromTarget" &&
+      event.params?.targetId === createdTargetId
+    );
+    return { before, attach, created, afterCreate, closed, afterClose, createdTargetId, detachEvents };
+  } finally {
+    ws.off("message", onAnyMessage);
+    ws.close();
+  }
+}
+
+const relay = spawn("node", ["scripts/swarm-relay.mjs", "serve", "--port", String(port)], {
+  cwd: skillDir,
+  stdio: ["ignore", "pipe", "pipe"]
+});
+
+let relayLog = "";
+relay.stdout.on("data", (chunk) => relayLog += chunk.toString());
+relay.stderr.on("data", (chunk) => relayLog += chunk.toString());
+
+try {
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  const launch = await run("node", [
+    "scripts/launch-chrome.mjs",
+    "--fresh",
+    "--profile",
+    "/tmp/browser-swarm-e2e-profile",
+    "--relay-port",
+    String(port)
+  ]);
+
+  const health = await waitForHealth();
+  assert(health.extension?.version === expectedExtension.version, `Expected extension version ${expectedExtension.version}, got ${health.extension?.version}`);
+  assert(health.extension?.id, "Expected extension /health metadata to include runtime id");
+  assert(
+    health.extension?.serviceWorker === expectedExtension.background?.service_worker,
+    `Expected extension worker ${expectedExtension.background?.service_worker}, got ${health.extension?.serviceWorker}`
+  );
+  const ensure = await run("node", [
+    "scripts/swarm-relay.mjs",
+    "ensure",
+    "--port",
+    String(port),
+    "--count",
+    "3",
+    "--label",
+    "flights",
+    "--label",
+    "rentals",
+    "--label",
+    "dinner",
+    "--url",
+    "https://www.google.com/travel/flights",
+    "--url",
+    "https://www.google.com/search?q=san+diego+surfboard+rentals+downtown",
+    "--url",
+    "https://www.kayak.com/San-Diego.10760.guide",
+    "--json"
+  ]);
+
+  const swarm = JSON.parse(ensure.stdout);
+  const browseResults = [];
+  for (const [index, target] of swarm.targets.slice(0, 3).entries()) {
+    const session = `browser-swarm-e2e-${target.label || `worker-${index + 1}`}-${target.targetId.slice(0, 8)}`;
+    workerSessions.push(session);
+
+    const title = await run(browseBin, ["get", "title", "--session", session, "--cdp", target.wsUrl]);
+    const url = await run(browseBin, ["get", "url", "--session", session, "--cdp", target.wsUrl]);
+    const snapshot = await run(browseBin, ["snapshot", "--compact", "--session", session, "--cdp", target.wsUrl]);
+    const tabList = await run(browseBin, ["tab", "list", "--session", session, "--cdp", target.wsUrl]);
+    const screenshotPath = resolve(artifactsDir, `${target.label || target.targetId}.png`);
+    const screenshot = await run(browseBin, ["screenshot", "--path", screenshotPath, "--session", session, "--cdp", target.wsUrl]);
+
+    const parsedTabs = parseJson(tabList.stdout).tabs;
+    const parsedSnapshot = parseJsonOrText(snapshot.stdout);
+    assert(parsedTabs.length === 1, `Expected ${session} to see exactly one tab, saw ${parsedTabs.length}`);
+    assert(parsedTabs[0].targetId === target.targetId, `Expected ${session} tab list to expose only ${target.targetId}`);
+
+    browseResults.push({
+      label: target.label,
+      targetId: target.targetId,
+      session,
+      wsUrl: target.wsUrl,
+      title: parseJson(title.stdout),
+      url: parseJson(url.stdout),
+      tabList: parseJson(tabList.stdout),
+      snapshotPreview: previewOutput(parsedSnapshot),
+      screenshot: parseJsonOrText(screenshot.stdout)
+    });
+  }
+
+  const [firstTarget, secondTarget] = swarm.targets;
+  const isolation = await cdpProbe(firstTarget.wsUrl, [
+    { name: "visible", method: "Target.getTargets" },
+    { name: "attachOwn", method: "Target.attachToTarget", params: { targetId: firstTarget.targetId, flatten: true } },
+    { name: "visibleWithSession", method: "Target.getTargets", sessionIdFrom: "attachOwn" },
+    { name: "attachOther", method: "Target.attachToTarget", params: { targetId: secondTarget.targetId, flatten: true } },
+    { name: "attachOtherWithSession", method: "Target.attachToTarget", sessionIdFrom: "attachOwn", params: { targetId: secondTarget.targetId, flatten: true } },
+    { name: "infoOther", method: "Target.getTargetInfo", params: { targetId: secondTarget.targetId } },
+    { name: "infoOtherWithSession", method: "Target.getTargetInfo", sessionIdFrom: "attachOwn", params: { targetId: secondTarget.targetId } },
+    { name: "createTarget", method: "Target.createTarget", params: { url: "https://example.net/#worker-created" } },
+    { name: "closeOwn", method: "Target.closeTarget", params: { targetId: firstTarget.targetId } },
+    { name: "createWithSession", method: "Target.createTarget", sessionIdFrom: "attachOwn", params: { url: "https://example.net/#session-worker-created" } },
+    { name: "closeWithSession", method: "Target.closeTarget", sessionIdFrom: "attachOwn", params: { targetId: firstTarget.targetId } },
+    { name: "unknownSessionEval", method: "Runtime.evaluate", sessionId: "browser-swarm-stale-session", params: { expression: "location.href", returnByValue: true } }
+  ]);
+  const visibleTargets = isolation.visible.result?.targetInfos || [];
+  const visibleTargetsWithSession = isolation.visibleWithSession.result?.targetInfos || [];
+  assert(visibleTargets.length === 1, `Expected raw CDP probe to see one target, saw ${visibleTargets.length}`);
+  assert(visibleTargets[0].targetId === firstTarget.targetId, "Raw CDP probe saw the wrong target");
+  assert(visibleTargetsWithSession.length === 1, `Expected session-scoped Target.getTargets to see one target, saw ${visibleTargetsWithSession.length}`);
+  assert(visibleTargetsWithSession[0].targetId === firstTarget.targetId, "Session-scoped Target.getTargets saw the wrong target");
+  assert(!isolation.attachOwn.error, `Expected attaching own target to succeed: ${JSON.stringify(isolation.attachOwn)}`);
+  assert(isolation.attachOther.error, "Expected attaching sibling target to fail");
+  assert(isolation.attachOtherWithSession.error, "Expected attaching sibling target with sessionId to fail");
+  assert(isolation.infoOther.error, "Expected reading sibling target info to fail");
+  assert(isolation.infoOtherWithSession.error, "Expected reading sibling target info with sessionId to fail");
+  assert(isolation.createTarget.error, "Expected worker Target.createTarget to be blocked");
+  assert(isolation.closeOwn.error, "Expected worker Target.closeTarget to be blocked");
+  assert(isolation.createWithSession.error, "Expected worker Target.createTarget with sessionId to be blocked");
+  assert(isolation.closeWithSession.error, "Expected worker Target.closeTarget with sessionId to be blocked");
+  assert(isolation.unknownSessionEval.error, "Expected unknown sessionId to fail instead of falling back to the worker target");
+
+  const samePageUrl = await startSamePageServer();
+  const rootLifecycle = await cdpRootLifecycle(`ws://127.0.0.1:${port}/devtools/browser`, `${samePageUrl}#root-created`);
+  const afterCreateTargets = rootLifecycle.afterCreate.result?.targetInfos || [];
+  const afterCloseTargets = rootLifecycle.afterClose.result?.targetInfos || [];
+  assert(afterCreateTargets.some((target) => target.targetId === rootLifecycle.createdTargetId), "Expected root-created target to appear after createTarget");
+  assert(!afterCloseTargets.some((target) => target.targetId === rootLifecycle.createdTargetId), "Expected root-created target to be absent after closeTarget");
+  assert(rootLifecycle.detachEvents.length === 1, `Expected exactly one root detach event, saw ${rootLifecycle.detachEvents.length}`);
+
+  const relayScreenshotPath = resolve(artifactsDir, "relay-screenshot.png");
+  const relayScreenshot = await run("node", [
+    "scripts/swarm-relay.mjs",
+    "screenshot",
+    "--port",
+    String(port),
+    "--target-id",
+    firstTarget.targetId,
+    "--path",
+    relayScreenshotPath,
+    "--json"
+  ]);
+  const relayScreenshotResult = parseJson(relayScreenshot.stdout);
+  const relayScreenshotBytes = statSync(relayScreenshotPath).size;
+  assert(relayScreenshotBytes > 0, "Expected relay screenshot CLI to write a non-empty image");
+
+  const writeTargets = swarm.targets.slice(0, 3);
+  await Promise.all(writeTargets.map((target) => run("node", [
+    "scripts/swarm-relay.mjs",
+    "navigate",
+    "--port",
+    String(port),
+    "--target-id",
+    target.targetId,
+    samePageUrl
+  ])));
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  const writeValues = ["alpha-worker", "beta-worker", "gamma-worker"];
+  const fillResults = await Promise.all(writeTargets.map((target, index) => run(browseBin, [
+    "fill",
+    "#box",
+    writeValues[index],
+    "--session",
+    browseResults[index].session,
+    "--cdp",
+    target.wsUrl
+  ])));
+  const submitResults = await Promise.all(writeTargets.map((target, index) => run(browseBin, [
+    "click",
+    "#submit",
+    "--session",
+    browseResults[index].session,
+    "--cdp",
+    target.wsUrl
+  ])));
+  const writeEvidence = await Promise.all(writeTargets.map(async (target, index) => {
+    const session = browseResults[index].session;
+    const title = await run(browseBin, ["get", "title", "--session", session, "--cdp", target.wsUrl]);
+    const resultText = await run(browseBin, ["get", "text", "#result", "--session", session, "--cdp", target.wsUrl]);
+    const inputValue = await run(browseBin, ["get", "value", "#box", "--session", session, "--cdp", target.wsUrl]);
+    const tabList = await run(browseBin, ["tab", "list", "--session", session, "--cdp", target.wsUrl]);
+    const parsedTabs = parseJson(tabList.stdout).tabs;
+    assert(parsedTabs.length === 1, `Expected same-page ${session} to see exactly one tab, saw ${parsedTabs.length}`);
+    assert(parsedTabs[0].targetId === target.targetId, `Expected same-page ${session} tab list to expose only ${target.targetId}`);
+
+    const expected = writeValues[index];
+    const parsedTitle = parseGetField(title.stdout, "title");
+    const parsedText = parseGetField(resultText.stdout, "text");
+    const parsedValue = parseGetField(inputValue.stdout, "value");
+    assert(parsedTitle === `same-page-action-test ${expected}`, `Expected title for ${session} to include ${expected}, got ${parsedTitle}`);
+    assert(parsedText === expected, `Expected #result for ${session} to be ${expected}, got ${parsedText}`);
+    assert(parsedValue === expected, `Expected #box for ${session} to be ${expected}, got ${parsedValue}`);
+
+    return {
+      label: target.label,
+      targetId: target.targetId,
+      session,
+      value: expected,
+      title: parsedTitle,
+      resultText: parsedText,
+      inputValue: parsedValue,
+      tabList: parseJson(tabList.stdout)
+    };
+  }));
+
+  const report = {
+    prompt: "plan an offsite to san diego next week - we need flights booked, surfing rentals and dinner near downtown",
+    browseBin,
+    launch: JSON.parse(launch.stdout),
+    health,
+    targets: swarm.targets.map((target) => ({
+      label: target.label,
+      targetId: target.targetId,
+      wsUrl: target.wsUrl,
+      url: target.targetInfo.url,
+      title: target.targetInfo.title
+    })),
+    browseResults,
+    isolation: {
+      visibleTargets: visibleTargets.map((target) => ({
+        targetId: target.targetId,
+        url: target.url,
+        title: target.title
+      })),
+      visibleTargetsWithSession: visibleTargetsWithSession.map((target) => ({
+        targetId: target.targetId,
+        url: target.url,
+        title: target.title
+      })),
+      attachOwn: isolation.attachOwn,
+      attachOther: isolation.attachOther,
+      attachOtherWithSession: isolation.attachOtherWithSession,
+      infoOther: isolation.infoOther,
+      infoOtherWithSession: isolation.infoOtherWithSession,
+      createTarget: isolation.createTarget,
+      closeOwn: isolation.closeOwn,
+      createWithSession: isolation.createWithSession,
+      closeWithSession: isolation.closeWithSession,
+      unknownSessionEval: isolation.unknownSessionEval
+    },
+    rootLifecycle: {
+      createdTargetId: rootLifecycle.createdTargetId,
+      sessionId: rootLifecycle.attach.result?.sessionId,
+      beforeCount: rootLifecycle.before.result?.targetInfos?.length,
+      afterCreateCount: afterCreateTargets.length,
+      afterCloseCount: afterCloseTargets.length,
+      detachEventCount: rootLifecycle.detachEvents.length,
+      closed: rootLifecycle.closed
+    },
+    relayScreenshot: {
+      path: relayScreenshotPath,
+      result: relayScreenshotResult,
+      bytes: relayScreenshotBytes
+    },
+    samePageWrite: {
+      url: samePageUrl,
+      fillResults: fillResults.map((result) => parseJsonOrText(result.stdout)),
+      submitResults: submitResults.map((result) => parseJsonOrText(result.stdout)),
+      evidence: writeEvidence
+    }
+  };
+  const reportPath = resolve(artifactsDir, "report.json");
+  writeFileSync(reportPath, JSON.stringify(report, null, 2));
+  console.log(JSON.stringify({ status: "PASS", reportPath, report }, null, 2));
+} catch (error) {
+  const reportPath = resolve(artifactsDir, "failure.log");
+  writeFileSync(reportPath, [
+    error instanceof Error ? error.stack : String(error),
+    "",
+    "Relay log:",
+    relayLog
+  ].join("\n"));
+  console.error(JSON.stringify({ status: "FAIL", reportPath, error: error.message }, null, 2));
+  process.exitCode = 1;
+} finally {
+  for (const session of workerSessions) {
+    spawnSync(browseBin, ["stop", "--session", session], { stdio: "ignore" });
+  }
+  if (samePageServer) samePageServer.close();
+  relay.kill("SIGTERM");
+  spawnSync("pkill", ["-f", "/tmp/browser-swarm-e2e-profile"], { stdio: "ignore" });
+}
diff --git a/skills/browser-swarm/scripts/launch-chrome.mjs b/skills/browser-swarm/scripts/launch-chrome.mjs
new file mode 100644
index 00000000..c3e98203
--- /dev/null
+++ b/skills/browser-swarm/scripts/launch-chrome.mjs
@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillDir = resolve(__dirname, "..");
+const extensionDir = resolve(skillDir, "extension");
+const defaultRelayPort = 19989;
+
+function parseArgs(argv) {
+  const opts = {
+    profile: "/tmp/browser-swarm-chrome-profile",
+    url: "about:blank",
+    fresh: false,
+    relayPort: Number(process.env.BROWSER_SWARM_PORT || defaultRelayPort)
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--profile") opts.profile = argv[++i];
+    else if (arg === "--url") opts.url = argv[++i];
+    else if (arg === "--fresh") opts.fresh = true;
+    else if (arg === "--relay-port") opts.relayPort = Number(argv[++i]);
+    else if (arg === "--help" || arg === "-h") {
+      console.log(`Usage: launch-chrome.mjs [--profile <dir>] [--url <url>] [--fresh] [--relay-port <port>]`);
+      process.exit(0);
+    }
+  }
+  return opts;
+}
+
+function chromePath() {
+  const playwrightChromium = findPlaywrightChromium();
+  const candidates = [
+    process.env.CHROME_PATH,
+    playwrightChromium,
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    "google-chrome",
+    "chromium",
+    "chromium-browser"
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    if (candidate.includes("/") && existsSync(candidate)) return candidate;
+    if (!candidate.includes("/") && commandExists(candidate)) return candidate;
+  }
+  throw new Error("Could not find Chrome. Set CHROME_PATH.");
+}
+
+function commandExists(command) {
+  const result = spawnSync("sh", ["-lc", "command -v \"$1\"", "sh", command], {
+    stdio: "ignore"
+  });
+  return result.status === 0;
+}
+
+function findPlaywrightChromium() {
+  const cacheDir = `${process.env.HOME}/Library/Caches/ms-playwright`;
+  if (!existsSync(cacheDir)) return null;
+  const installs = readdirSync(cacheDir)
+    .filter((name) => name.startsWith("chromium-"))
+    .sort()
+    .reverse();
+  for (const install of installs) {
+    const candidate = `${cacheDir}/${install}/chrome-mac/Chromium.app/Contents/MacOS/Chromium`;
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function extensionDirForPort(port) {
+  if (!port || port === defaultRelayPort) return extensionDir;
+
+  const patchedDir = `/tmp/browser-swarm-extension-${port}`;
+  rmSync(patchedDir, { recursive: true, force: true });
+  cpSync(extensionDir, patchedDir, { recursive: true });
+
+  const manifestPath = resolve(patchedDir, "manifest.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const workerPath = resolve(patchedDir, manifest.background.service_worker);
+  const worker = readFileSync(workerPath, "utf8");
+  writeFileSync(
+    workerPath,
+    worker.replace(`const DEFAULT_PORT = ${defaultRelayPort};`, `const DEFAULT_PORT = ${port};`)
+  );
+  return patchedDir;
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.fresh && existsSync(opts.profile)) {
+  rmSync(opts.profile, { recursive: true, force: true });
+}
+mkdirSync(opts.profile, { recursive: true });
+
+const activeExtensionDir = extensionDirForPort(opts.relayPort);
+const args = [
+  `--user-data-dir=${opts.profile}`,
+  `--load-extension=${activeExtensionDir}`,
+  `--disable-extensions-except=${activeExtensionDir}`,
+  "--disable-features=DisableLoadExtensionCommandLineSwitch",
+  "--no-first-run",
+  "--no-default-browser-check",
+  opts.url
+];
+
+const child = spawn(chromePath(), args, {
+  detached: true,
+  stdio: "ignore"
+});
+child.unref();
+
+console.log(JSON.stringify({
+  launched: true,
+  pid: child.pid,
+  profile: opts.profile,
+  extensionDir: activeExtensionDir,
+  relayPort: opts.relayPort
+}, null, 2));
diff --git a/skills/browser-swarm/scripts/setup-real-browser.mjs b/skills/browser-swarm/scripts/setup-real-browser.mjs
new file mode 100644
index 00000000..2069a559
--- /dev/null
+++ b/skills/browser-swarm/scripts/setup-real-browser.mjs
@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import open, { apps } from "open";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillDir = resolve(__dirname, "..");
+const extensionDir = resolve(skillDir, "extension");
+const DEFAULT_PORT = 19989;
+const DEFAULT_HOST = "127.0.0.1";
+
+const BROWSERS = {
+  arc: {
+    label: "Arc",
+    appName: process.platform === "darwin" ? "Arc" : "arc",
+    extensionsUrl: "arc://extensions",
+  },
+  chrome: {
+    label: "Google Chrome",
+    appName: apps.chrome,
+    extensionsUrl: "chrome://extensions",
+  },
+  canary: {
+    label: "Google Chrome Canary",
+    appName: process.platform === "darwin" ? "Google Chrome Canary" : "google-chrome-canary",
+    extensionsUrl: "chrome://extensions",
+  },
+  chromium: {
+    label: "Chromium",
+    appName: process.platform === "darwin" ? "Chromium" : ["chromium", "chromium-browser"],
+    extensionsUrl: "chrome://extensions",
+  },
+  "chrome-for-testing": {
+    label: "Chrome for Testing",
+    appName: process.platform === "darwin"
+      ? "Google Chrome for Testing"
+      : ["chrome-for-testing", "google-chrome-for-testing"],
+    extensionsUrl: "chrome://extensions",
+  },
+  default: {
+    label: "default browser for chrome:// URLs",
+    extensionsUrl: "chrome://extensions",
+  },
+};
+
+function usage() {
+  console.log(`Usage:
+  node scripts/setup-real-browser.mjs [--browser <arc|chrome|canary|chromium|chrome-for-testing|default>]
+
+Options:
+  --browser <name>        Browser to open. Defaults to OS URL handler for chrome://extensions.
+  --extensions-url <url>  Override the extensions page URL.
+  --port <port>           Relay port. Default: ${DEFAULT_PORT}
+  --host <host>           Relay host. Default: ${DEFAULT_HOST}
+  --no-open               Print instructions without opening the browser.
+  --no-start-relay        Do not auto-start the relay if it is down.
+  --no-wait               Do not poll for extensionConnected.
+  --timeout <seconds>     Wait time for extension connection. Default: 180
+  --json                  Print the final status as JSON.
+
+This helper does not install the unpacked extension for the user. It starts or checks the
+localhost relay, opens the chosen browser's extensions page, prints the extension path,
+and waits until the user-approved extension connects.`);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    browser: process.env.BROWSER_SWARM_BROWSER || "default",
+    extensionsUrl: process.env.BROWSER_SWARM_EXTENSIONS_URL,
+    port: DEFAULT_PORT,
+    host: DEFAULT_HOST,
+    open: true,
+    startRelay: true,
+    wait: true,
+    timeoutSeconds: 180,
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--browser") opts.browser = argv[++i];
+    else if (arg === "--extensions-url") opts.extensionsUrl = argv[++i];
+    else if (arg === "--port") opts.port = Number(argv[++i]);
+    else if (arg === "--host") opts.host = argv[++i];
+    else if (arg === "--no-open") opts.open = false;
+    else if (arg === "--no-start-relay") opts.startRelay = false;
+    else if (arg === "--no-wait") opts.wait = false;
+    else if (arg === "--timeout") opts.timeoutSeconds = Number(argv[++i]);
+    else if (arg === "--json") opts.json = true;
+    else if (arg === "--help" || arg === "-h") opts.help = true;
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return opts;
+}
+
+async function health(host, port) {
+  const response = await fetch(`http://${host}:${port}/health`);
+  if (!response.ok) throw new Error(`Relay health returned HTTP ${response.status}`);
+  return response.json();
+}
+
+async function tryHealth(host, port) {
+  try {
+    return await health(host, port);
+  } catch {
+    return null;
+  }
+}
+
+function startRelay({ host, port }) {
+  const logDir = "/tmp/browser-swarm";
+  mkdirSync(logDir, { recursive: true });
+  const logPath = `${logDir}/relay-${port}.log`;
+  const logFd = openSync(logPath, "a");
+  let child;
+  try {
+    child = spawn("node", ["scripts/swarm-relay.mjs", "serve", "--host", host, "--port", String(port)], {
+      cwd: skillDir,
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+    });
+  } finally {
+    closeSync(logFd);
+  }
+  child.unref();
+  return { pid: child.pid, logPath };
+}
+
+async function waitForRelay(host, port, timeoutMs = 10000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const status = await tryHealth(host, port);
+    if (status) return status;
+    await sleep(250);
+  }
+  throw new Error(`Timed out waiting for relay on http://${host}:${port}`);
+}
+
+async function waitForExtension(host, port, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const status = await health(host, port);
+    if (status.extensionConnected) return status;
+    await sleep(1000);
+  }
+  return health(host, port);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function readExpectedExtension() {
+  const manifestPath = resolve(extensionDir, "manifest.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    serviceWorker: manifest.background?.service_worker,
+  };
+}
+
+async function openBrowser(browser) {
+  const url = browser.extensionsUrl;
+  try {
+    if (browser.appName) {
+      await open(url, { app: { name: browser.appName } });
+      return { opened: true, target: url, app: browser.appName };
+    }
+    await open(url);
+    return { opened: true, target: url, app: "default" };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to open ${url}: ${message}. Open it manually in the browser you want to use.`);
+  }
+}
+
+function extensionVersionMatches(status, expectedExtension) {
+  return status?.extension?.version === expectedExtension.version;
+}
+
+function printInstructions({ browser, host, port, relayStarted, initialHealth, expectedExtension }) {
+  console.log(`Browser Swarm real-browser setup
+
+Browser: ${browser.label}
+Relay:   http://${host}:${port}
+Status:  ${initialHealth ? JSON.stringify(initialHealth) : "starting"}
+${relayStarted ? `Relay log: ${relayStarted.logPath}` : ""}
+Expected extension: ${expectedExtension.name} ${expectedExtension.version}
+Expected worker:    ${expectedExtension.serviceWorker}
+
+Extension path:
+${extensionDir}
+
+In ${browser.label}:
+1. Enable Developer Mode if it is not already enabled.
+2. Click "Load unpacked".
+3. Select the extension path above.
+4. Leave this terminal running until it reports extensionConnected: true.
+`);
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    usage();
+    return;
+  }
+  if (!existsSync(extensionDir)) {
+    throw new Error(`Missing extension directory: ${extensionDir}`);
+  }
+  const expectedExtension = readExpectedExtension();
+  const browserKey = opts.browser.toLowerCase();
+  const browserTemplate = BROWSERS[browserKey];
+  if (!browserTemplate) {
+    throw new Error(`Unknown browser: ${opts.browser}. Supported: ${Object.keys(BROWSERS).join(", ")}`);
+  }
+  const browser = { ...browserTemplate };
+  if (opts.extensionsUrl) browser.extensionsUrl = opts.extensionsUrl;
+
+  let initialHealth = await tryHealth(opts.host, opts.port);
+  let relayStarted = null;
+  if (!initialHealth && opts.startRelay) {
+    relayStarted = startRelay(opts);
+    initialHealth = await waitForRelay(opts.host, opts.port);
+  } else if (!initialHealth) {
+    throw new Error(`Relay is not running on http://${opts.host}:${opts.port}`);
+  }
+
+  printInstructions({ browser, host: opts.host, port: opts.port, relayStarted, initialHealth, expectedExtension });
+
+  let openResult = null;
+  if (opts.open) {
+    openResult = await openBrowser(browser);
+    console.log(`Opened extensions page: ${JSON.stringify(openResult)}\n`);
+  }
+
+  let finalHealth = initialHealth;
+  if (opts.wait) {
+    finalHealth = await waitForExtension(opts.host, opts.port, opts.timeoutSeconds * 1000);
+    if (finalHealth.extensionConnected) {
+      console.log(`Connected: ${JSON.stringify(finalHealth, null, 2)}`);
+      if (!extensionVersionMatches(finalHealth, expectedExtension)) {
+        console.error(`Stale extension worker detected: connected version ${finalHealth.extension?.version || "unknown"} does not match unpacked manifest version ${expectedExtension.version}. Reload Browser Swarm Bridge in the browser extension manager. If it still reports the old version, restart the browser to force the MV3 service worker registration to refresh.`);
+        process.exitCode = 3;
+      }
+    } else {
+      console.log(`Not connected yet: ${JSON.stringify(finalHealth, null, 2)}`);
+      process.exitCode = 2;
+    }
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      browser: browserKey,
+      extensionDir,
+      relayStarted,
+      openResult,
+      expectedExtension,
+      health: finalHealth,
+      versionMatches: extensionVersionMatches(finalHealth, expectedExtension),
+    }, null, 2));
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
diff --git a/skills/browser-swarm/scripts/swarm-relay.mjs b/skills/browser-swarm/scripts/swarm-relay.mjs
new file mode 100644
index 00000000..13ea3e1c
--- /dev/null
+++ b/skills/browser-swarm/scripts/swarm-relay.mjs
@@ -0,0 +1,705 @@
+#!/usr/bin/env node
+import http from "node:http";
+import { randomUUID } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { WebSocketServer } from "ws";
+
+const DEFAULT_PORT = 19989;
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_GROUP_TITLE = "browser-swarm";
+const DEFAULT_GROUP_COLOR = "cyan";
+
+function parseArgs(argv) {
+  const [command = "help", ...rest] = argv;
+  const opts = { command, labels: [], urls: [], json: false };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--port") opts.port = Number(rest[++i]);
+    else if (arg === "--host") opts.host = rest[++i];
+    else if (arg === "--count") opts.count = Number(rest[++i]);
+    else if (arg === "--label") opts.labels.push(rest[++i]);
+    else if (arg === "--url") opts.urls.push(rest[++i]);
+    else if (arg === "--target-id") opts.targetId = rest[++i];
+    else if (arg === "--group-title") opts.groupTitle = rest[++i];
+    else if (arg === "--group-color") opts.groupColor = rest[++i];
+    else if (arg === "--no-group") opts.noGroup = true;
+    else if (arg === "--json") opts.json = true;
+    else if (arg === "--compact") opts.compact = true;
+    else if (arg === "--path") opts.path = rest[++i];
+    else if (arg === "--expr") opts.expr = rest[++i];
+    else if (arg === "--help" || arg === "-h") opts.help = true;
+    else if (!opts._) opts._ = [arg];
+    else opts._.push(arg);
+  }
+  return opts;
+}
+
+function usage() {
+  console.log(`Usage:
+  node scripts/swarm-relay.mjs serve [--host 127.0.0.1] [--port 19989]
+  node scripts/swarm-relay.mjs ensure --count <n> [--label <name>]... [--url <url>]... [--no-group] [--json]
+  node scripts/swarm-relay.mjs tabs [--json]
+  node scripts/swarm-relay.mjs browse-url --target-id <id>
+  node scripts/swarm-relay.mjs navigate --target-id <id> <url>
+  node scripts/swarm-relay.mjs eval --target-id <id> --expr <js>
+  node scripts/swarm-relay.mjs screenshot --target-id <id> --path <file>
+`);
+}
+
+function json(res, status, value) {
+  const body = JSON.stringify(value, null, 2);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(body)
+  });
+  res.end(body);
+}
+
+async function readBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString("utf8");
+  return raw ? JSON.parse(raw) : {};
+}
+
+function print(value, asJson = false) {
+  if (asJson || typeof value !== "string") {
+    console.log(JSON.stringify(value, null, 2));
+  } else {
+    console.log(value);
+  }
+}
+
+async function post(path, body, port = DEFAULT_PORT, host = DEFAULT_HOST) {
+  const response = await fetch(`http://${host}:${port}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body || {})
+  });
+  const text = await response.text();
+  const parsed = text ? JSON.parse(text) : {};
+  if (!response.ok) {
+    throw new Error(parsed.error || `HTTP ${response.status}`);
+  }
+  return parsed;
+}
+
+async function get(path, port = DEFAULT_PORT, host = DEFAULT_HOST) {
+  const response = await fetch(`http://${host}:${port}${path}`);
+  const text = await response.text();
+  const parsed = text ? JSON.parse(text) : {};
+  if (!response.ok) {
+    throw new Error(parsed.error || `HTTP ${response.status}`);
+  }
+  return parsed;
+}
+
+class Relay {
+  constructor({ host, port }) {
+    this.host = host;
+    this.port = port;
+    this.extension = null;
+    this.extensionInfo = null;
+    this.extensionRequests = new Map();
+    this.targets = new Map();
+    this.clients = new Set();
+    this.groupDisabled = false;
+    this.server = http.createServer((req, res) => this.handleHttp(req, res));
+    this.wss = new WebSocketServer({ noServer: true });
+    this.server.on("upgrade", (req, socket, head) => this.handleUpgrade(req, socket, head));
+  }
+
+  listen() {
+    return new Promise((resolve) => {
+      this.server.listen(this.port, this.host, resolve);
+    });
+  }
+
+  async handleHttp(req, res) {
+    try {
+      const url = new URL(req.url, `http://${this.host}:${this.port}`);
+      if (req.method === "GET" && url.pathname === "/health") {
+        json(res, 200, {
+          ok: true,
+          extensionConnected: Boolean(this.extension),
+          extension: this.extensionInfo,
+          targetCount: this.targets.size
+        });
+        return;
+      }
+
+      if (req.method === "GET" && (url.pathname === "/json/version" || url.pathname === "/json/version/")) {
+        json(res, 200, {
+          Browser: "BrowserSwarm/0.1.0",
+          "Protocol-Version": "1.3",
+          webSocketDebuggerUrl: this.browserWsUrl()
+        });
+        return;
+      }
+
+      if (req.method === "GET" && ["/json/list", "/json/list/", "/json", "/json/"].includes(url.pathname)) {
+        json(res, 200, this.targetList());
+        return;
+      }
+
+      if (req.method === "GET" && url.pathname === "/swarm/tabs") {
+        await this.refreshTargets();
+        json(res, 200, { targets: this.enrichedTargets() });
+        return;
+      }
+
+      if (req.method === "POST" && url.pathname === "/swarm/ensure") {
+        const body = await readBody(req);
+        const result = await this.ensureTabs(body);
+        json(res, 200, result);
+        return;
+      }
+
+      if (req.method === "POST" && url.pathname === "/swarm/navigate") {
+        const body = await readBody(req);
+        const result = await this.forwardToTarget(body.targetId, "Page.navigate", { url: body.url });
+        json(res, 200, result);
+        return;
+      }
+
+      if (req.method === "POST" && url.pathname === "/swarm/eval") {
+        const body = await readBody(req);
+        const result = await this.forwardToTarget(body.targetId, "Runtime.evaluate", {
+          expression: body.expr,
+          awaitPromise: true,
+          returnByValue: true
+        });
+        json(res, 200, result);
+        return;
+      }
+
+      if (req.method === "POST" && url.pathname === "/swarm/screenshot") {
+        const body = await readBody(req);
+        const result = await this.forwardToTarget(body.targetId, "Page.captureScreenshot", {
+          format: "png",
+          captureBeyondViewport: true
+        });
+        json(res, 200, result);
+        return;
+      }
+
+      json(res, 404, { error: `No route for ${req.method} ${url.pathname}` });
+    } catch (error) {
+      json(res, 500, { error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  handleUpgrade(req, socket, head) {
+    const url = new URL(req.url, `http://${this.host}:${this.port}`);
+    this.wss.handleUpgrade(req, socket, head, (ws) => {
+      if (url.pathname === "/extension") {
+        this.attachExtension(ws);
+      } else if (url.pathname.startsWith("/devtools/browser")) {
+        const parts = url.pathname.split("/").filter(Boolean);
+        const targetId = parts.length > 2 ? decodeURIComponent(parts[2]) : null;
+        this.attachCdpClient(ws, targetId);
+      } else {
+        ws.close(1008, "Unknown browser-swarm endpoint");
+      }
+    });
+  }
+
+  browserWsUrl(targetId = null) {
+    const suffix = targetId ? `/${encodeURIComponent(targetId)}` : "";
+    return `ws://${this.host}:${this.port}/devtools/browser${suffix}`;
+  }
+
+  targetList(targetId = null) {
+    return this.enrichedTargets()
+      .filter((target) => !targetId || target.targetId === targetId)
+      .map((target) => ({
+        id: target.targetId,
+        type: target.targetInfo.type,
+        title: target.targetInfo.title,
+        description: target.label || target.targetInfo.title,
+        url: target.targetInfo.url,
+        webSocketDebuggerUrl: this.browserWsUrl(target.targetId),
+        devtoolsFrontendUrl: `/devtools/inspector.html?ws=${this.host}:${this.port}/devtools/browser/${target.targetId}`
+      }));
+  }
+
+  enrichedTargets(targetId = null) {
+    return Array.from(this.targets.values())
+      .filter((target) => !targetId || target.targetId === targetId)
+      .map((target) => ({
+        ...target,
+        wsUrl: this.browserWsUrl(target.targetId)
+      }));
+  }
+
+  attachExtension(ws) {
+    if (this.extension && this.extension.readyState === this.extension.OPEN) {
+      this.extension.close(4001, "Replaced by new extension connection");
+    }
+    this.extension = ws;
+    this.extensionInfo = null;
+
+    ws.on("message", (raw) => this.handleExtensionMessage(raw));
+    ws.on("close", () => {
+      if (this.extension === ws) {
+        this.extension = null;
+        this.extensionInfo = null;
+        this.targets.clear();
+      }
+    });
+    ws.on("error", () => {});
+  }
+
+  handleExtensionMessage(raw) {
+    let message;
+    try {
+      message = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+
+    if (message.type === "hello") {
+      this.extensionInfo = {
+        name: message.extension || "unknown",
+        id: message.id || null,
+        version: message.version || "unknown",
+        serviceWorker: message.serviceWorker || null,
+        connectedAt: new Date().toISOString()
+      };
+      this.targets.clear();
+      this.mergeTargets(message.targets || []);
+      return;
+    }
+
+    if (message.type === "response") {
+      const pending = this.extensionRequests.get(message.id);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      this.extensionRequests.delete(message.id);
+      if (message.error) pending.reject(new Error(message.error));
+      else pending.resolve(message.result);
+      return;
+    }
+
+    if (message.type === "cdpEvent") {
+      this.forwardEvent(message);
+      return;
+    }
+
+    if (message.type === "warning") {
+      console.warn(JSON.stringify({ source: "browser-swarm-extension", ...message }));
+      return;
+    }
+
+    if (message.type === "targetDetached") {
+      const hadTarget = this.targets.delete(message.targetId);
+      if (!hadTarget) return;
+      this.broadcast({
+        method: "Target.detachedFromTarget",
+        params: {
+          sessionId: message.sessionId,
+          targetId: message.targetId
+        }
+      }, message.targetId);
+    }
+  }
+
+  sendToExtension(method, params = {}) {
+    if (!this.extension || this.extension.readyState !== this.extension.OPEN) {
+      throw new Error("Browser Swarm extension is not connected");
+    }
+
+    const id = randomUUID();
+    const payload = { type: "request", id, method, params };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.extensionRequests.delete(id);
+        reject(new Error(`Extension request timed out: ${method}`));
+      }, 30000);
+      this.extensionRequests.set(id, { resolve, reject, timer });
+      this.extension.send(JSON.stringify(payload));
+    });
+  }
+
+  mergeTargets(targets) {
+    for (const target of targets) {
+      if (!target?.targetId || !target?.targetInfo) continue;
+      this.targets.set(target.targetId, {
+        ...target,
+        targetInfo: {
+          ...target.targetInfo,
+          attached: true
+        }
+      });
+    }
+  }
+
+  async refreshTargets() {
+    if (!this.extension || this.extension.readyState !== this.extension.OPEN) return;
+    const result = await this.sendToExtension("listTargets");
+    this.targets.clear();
+    this.mergeTargets(result.targets || []);
+  }
+
+  async ensureTabs(body) {
+    const groupDisabled = Boolean(body.groupDisabled || body.noGroup);
+    this.groupDisabled = groupDisabled;
+    const result = await this.sendToExtension("ensureTabs", {
+      count: body.count || 1,
+      labels: body.labels || [],
+      urls: body.urls || [],
+      groupDisabled,
+      groupTitle: groupDisabled ? null : body.groupTitle || DEFAULT_GROUP_TITLE,
+      groupColor: body.groupColor || DEFAULT_GROUP_COLOR
+    });
+    this.mergeTargets(result.targets || []);
+    return {
+      ...result,
+      targets: this.enrichedTargets()
+    };
+  }
+
+  attachCdpClient(ws, targetId) {
+    const client = {
+      id: randomUUID(),
+      ws,
+      targetId,
+      autoAttach: false
+    };
+    this.clients.add(client);
+
+    ws.on("message", (raw) => this.handleCdpMessage(client, raw));
+    ws.on("close", () => this.clients.delete(client));
+    ws.on("error", () => {});
+  }
+
+  async handleCdpMessage(client, raw) {
+    let message;
+    try {
+      message = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+
+    const { id, method, params = {}, sessionId } = message;
+    try {
+      const result = await this.handleCdpCommand(client, method, params, sessionId);
+      if (id !== undefined) {
+        this.sendCdp(client, { id, sessionId, result: result || {} });
+      }
+      try {
+        this.emitSyntheticEvents(client, method, params, sessionId, result);
+      } catch (error) {
+        console.warn(JSON.stringify({
+          source: "browser-swarm-relay",
+          type: "synthetic-event-warning",
+          method,
+          message: error instanceof Error ? error.message : String(error)
+        }));
+      }
+    } catch (error) {
+      if (id !== undefined) {
+        this.sendCdp(client, {
+          id,
+          sessionId,
+          error: {
+            message: error instanceof Error ? error.message : String(error)
+          }
+        });
+      }
+    }
+  }
+
+  async handleCdpCommand(client, method, params, sessionId) {
+    const targets = this.targetsForClient(client);
+    const firstTarget = targets[0];
+
+    if (client.targetId && method === "Target.createTarget") {
+      throw new Error("Target.createTarget is disabled on browser-swarm worker endpoints; allocate tabs through the browser-swarm harness.");
+    }
+
+    if (client.targetId && method === "Target.closeTarget") {
+      throw new Error("Target.closeTarget is disabled on browser-swarm worker endpoints; release tabs through the browser-swarm harness.");
+    }
+
+    const sessionTarget = sessionId ? this.findTargetBySession(sessionId, client) : null;
+
+    switch (method) {
+      case "Target.getTargets":
+        return {
+          targetInfos: targets.map((target) => ({
+            ...target.targetInfo,
+            attached: true
+          }))
+        };
+      case "Target.getTargetInfo": {
+        const target = params.targetId
+          ? this.findTarget(params.targetId, client)
+          : sessionTarget || this.findTarget(null, client);
+        return { targetInfo: { ...target.targetInfo, attached: true } };
+      }
+      case "Target.attachToTarget": {
+        const target = params.targetId
+          ? this.findTarget(params.targetId, client)
+          : sessionTarget || this.findTarget(null, client);
+        return { sessionId: target.sessionId };
+      }
+    }
+
+    if (!client.targetId && method === "Target.createTarget") {
+      const result = await this.sendToExtension("createTarget", {
+        url: params.url || "about:blank",
+        groupDisabled: this.groupDisabled,
+        groupTitle: this.groupDisabled ? null : DEFAULT_GROUP_TITLE,
+        groupColor: DEFAULT_GROUP_COLOR
+      });
+      this.mergeTargets([result.target]);
+      return { targetId: result.targetId };
+    }
+
+    if (!client.targetId && method === "Target.closeTarget") {
+      const target = this.findTarget(params.targetId, client);
+      const result = await this.sendToExtension("closeTarget", { targetId: target.targetId });
+      if (result?.success !== false) {
+        const hadTarget = this.targets.delete(target.targetId);
+        if (hadTarget) {
+          this.broadcast({
+            method: "Target.detachedFromTarget",
+            params: {
+              sessionId: target.sessionId,
+              targetId: target.targetId
+            }
+          }, target.targetId);
+        }
+      }
+      return result;
+    }
+
+    if (!sessionId) {
+      switch (method) {
+        case "Browser.getVersion":
+          return {
+            protocolVersion: "1.3",
+            product: "Chrome/BrowserSwarm",
+            revision: "browser-swarm",
+            userAgent: "BrowserSwarm/0.1.0",
+            jsVersion: "V8"
+          };
+        case "Browser.setDownloadBehavior":
+          return {};
+        case "Target.setDiscoverTargets":
+          return {};
+        case "Target.setAutoAttach":
+          client.autoAttach = Boolean(params.autoAttach);
+          await this.sendToExtension("forwardCDPCommand", {
+            method,
+            params,
+            targetId: firstTarget?.targetId
+          }).catch(() => {});
+          return {};
+      }
+    }
+
+    const target = sessionTarget || this.findTargetBySession(sessionId, client);
+    return this.sendToExtension("forwardCDPCommand", {
+      targetId: target.targetId,
+      tabId: target.tabId,
+      sessionId,
+      method,
+      params
+    });
+  }
+
+  emitSyntheticEvents(client, method, params, sessionId, result) {
+    if (method === "Target.setAutoAttach" && !sessionId && params?.autoAttach) {
+      for (const target of this.targetsForClient(client)) {
+        this.sendCdp(client, {
+          method: "Target.attachedToTarget",
+          params: {
+            sessionId: target.sessionId,
+            targetInfo: { ...target.targetInfo, attached: true },
+            waitingForDebugger: false
+          }
+        });
+      }
+    }
+
+    if (method === "Target.setDiscoverTargets" && params?.discover) {
+      for (const target of this.targetsForClient(client)) {
+        this.sendCdp(client, {
+          method: "Target.targetCreated",
+          params: {
+            targetInfo: { ...target.targetInfo, attached: true }
+          }
+        });
+      }
+    }
+
+    if (method === "Target.attachToTarget" && result?.sessionId) {
+      const target = this.findTarget(params.targetId, client);
+      this.sendCdp(client, {
+        method: "Target.attachedToTarget",
+        params: {
+          sessionId: result.sessionId,
+          targetInfo: { ...target.targetInfo, attached: true },
+          waitingForDebugger: false
+        }
+      });
+    }
+  }
+
+  targetsForClient(client) {
+    const all = Array.from(this.targets.values());
+    if (!client.targetId) return all;
+    return all.filter((target) => target.targetId === client.targetId);
+  }
+
+  findTarget(targetId, client) {
+    const targets = this.targetsForClient(client);
+    const target = targetId
+      ? targets.find((candidate) => candidate.targetId === targetId)
+      : targets[0];
+    if (!target) {
+      throw new Error(`No target available${targetId ? ` for ${targetId}` : ""}`);
+    }
+    return target;
+  }
+
+  findTargetBySession(sessionId, client) {
+    const targets = this.targetsForClient(client);
+    if (!sessionId) return this.findTarget(null, client);
+    const target = targets.find((candidate) => candidate.sessionId === sessionId);
+    if (target) return target;
+    throw new Error(`No target available for session ${sessionId}`);
+  }
+
+  async forwardToTarget(targetId, method, params) {
+    const target = this.findTarget(targetId, { targetId });
+    return this.sendToExtension("forwardCDPCommand", {
+      targetId: target.targetId,
+      tabId: target.tabId,
+      sessionId: target.sessionId,
+      method,
+      params
+    });
+  }
+
+  forwardEvent(event) {
+    if (event.method === "Target.targetInfoChanged" && event.params?.targetInfo?.targetId) {
+      const existing = this.targets.get(event.params.targetInfo.targetId);
+      if (existing) {
+        this.targets.set(existing.targetId, {
+          ...existing,
+          targetInfo: {
+            ...existing.targetInfo,
+            ...event.params.targetInfo,
+            attached: true
+          }
+        });
+      }
+    }
+
+    this.broadcast({
+      method: event.method,
+      sessionId: event.sessionId,
+      params: event.params
+    }, event.targetId);
+  }
+
+  broadcast(message, targetId = null) {
+    for (const client of this.clients) {
+      if (client.ws.readyState !== client.ws.OPEN) continue;
+      if (client.targetId && targetId && client.targetId !== targetId) continue;
+      this.sendCdp(client, message);
+    }
+  }
+
+  sendCdp(client, message) {
+    if (client.ws.readyState === client.ws.OPEN) {
+      client.ws.send(JSON.stringify(message));
+    }
+  }
+}
+
+async function runCli(opts) {
+  const port = opts.port || DEFAULT_PORT;
+  const host = opts.host || DEFAULT_HOST;
+  if (opts.help || opts.command === "help") {
+    usage();
+    return;
+  }
+
+  if (opts.command === "serve") {
+    const relay = new Relay({ host, port });
+    await relay.listen();
+    console.log(JSON.stringify({
+      listening: true,
+      host,
+      port,
+      extensionEndpoint: `ws://${host}:${port}/extension`,
+      browserEndpoint: `ws://${host}:${port}/devtools/browser`
+    }, null, 2));
+    return;
+  }
+
+  if (opts.command === "ensure") {
+    const groupDisabled = Boolean(opts.noGroup);
+    const result = await post("/swarm/ensure", {
+      count: opts.count || Math.max(opts.labels.length, opts.urls.length, 1),
+      labels: opts.labels,
+      urls: opts.urls,
+      groupDisabled,
+      groupTitle: groupDisabled ? null : opts.groupTitle || DEFAULT_GROUP_TITLE,
+      groupColor: opts.groupColor || DEFAULT_GROUP_COLOR
+    }, port, host);
+    print(result, opts.json);
+    return;
+  }
+
+  if (opts.command === "tabs") {
+    const result = await get("/swarm/tabs", port, host);
+    print(result, opts.json);
+    return;
+  }
+
+  if (opts.command === "browse-url") {
+    if (!opts.targetId) throw new Error("--target-id is required");
+    print(`ws://${host}:${port}/devtools/browser/${encodeURIComponent(opts.targetId)}`, false);
+    return;
+  }
+
+  if (opts.command === "navigate") {
+    if (!opts.targetId || !opts._?.[0]) throw new Error("navigate requires --target-id and URL");
+    const result = await post("/swarm/navigate", { targetId: opts.targetId, url: opts._[0] }, port, host);
+    print(result, opts.json);
+    return;
+  }
+
+  if (opts.command === "eval") {
+    if (!opts.targetId || !opts.expr) throw new Error("eval requires --target-id and --expr");
+    const result = await post("/swarm/eval", { targetId: opts.targetId, expr: opts.expr }, port, host);
+    print(result, opts.json);
+    return;
+  }
+
+  if (opts.command === "screenshot") {
+    if (!opts.targetId) throw new Error("screenshot requires --target-id");
+    const result = await post("/swarm/screenshot", { targetId: opts.targetId }, port, host);
+    if (opts.path) {
+      if (!result?.data) throw new Error("Screenshot response did not include image data");
+      const bytes = Buffer.from(result.data, "base64");
+      writeFileSync(opts.path, bytes);
+      print(opts.json ? { path: opts.path, bytes: bytes.length } : opts.path, opts.json);
+      return;
+    }
+    print(result, opts.json);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${opts.command}`);
+}
+
+runCli(parseArgs(process.argv.slice(2))).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});