fix(bsk): fix ci

feat(bsk): harden browser file transfer transactions
fix(bsk): fix ci
2026-09-10 13:01:23 +08:00 · 2026-08-21 16:34:06 +08:00 · 2026-08-21 16:31:47 +08:00 · 2026-08-21 14:32:29 +08:00 · 2026-08-21 14:11:13 +08:00 · 2026-08-21 11:14:51 +08:00
295 changed files with 4907 additions and 37854 deletions
@@ -37,35 +37,6 @@ jobs:
      - name: Run Rust tests
        run: cargo test --workspace --locked
  windows-daemon:
    name: Windows daemon, installer and cancellation regression tests
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v6
      - uses: dtolnay/rust-toolchain@stable
      - name: Run Windows named-pipe tests
        run: cargo test -p bsk --lib --locked daemon::ipc::windows::tests
      - name: Run Windows process liveness tests
        run: cargo test -p bsk --lib --locked daemon::lockfile::tests
      - name: Run Windows update tests
        run: cargo test -p bsk --lib --locked cli::update::tests
      - name: Run Windows update and cancellation process tests
        run: cargo test -p bsk --test windows_update --test windows_parent_cancel --locked
      - name: Run installer tests (Windows PowerShell 5.1)
        shell: powershell
        run: ./scripts/install-windows.test.ps1
      - name: Run installer tests (PowerShell 7)
        shell: pwsh
        run: ./scripts/install-windows.test.ps1
  frontend:
    name: Frontend lint, typecheck, tests, build
    runs-on: ubuntu-latest
@@ -325,180 +325,3 @@ jobs:
          echo "Chrome Web Store submission created successfully:"
          jq '{itemId, state, warningInfo}' "$PUBLISH_RESPONSE"
  publish-edge-addons:
    needs: [resolve, build-extension]
    runs-on: ubuntu-latest
    environment: edge-addons
    permissions:
      contents: read
    steps:
      - name: Download build artifact
        uses: actions/download-artifact@v8
        with:
          name: extension-zip
          path: dist
      - name: Validate Microsoft Edge Add-ons configuration
        shell: bash
        env:
          API_KEY: ${{ secrets.EDGE_ADDONS_API_KEY }}
          CLIENT_ID: ${{ vars.EDGE_ADDONS_CLIENT_ID }}
          PRODUCT_ID: ${{ vars.EDGE_ADDONS_PRODUCT_ID }}
        run: |
          set -euo pipefail
          if [ -z "$API_KEY" ]; then
            echo "::error::Environment secret EDGE_ADDONS_API_KEY is not configured"
            exit 1
          fi
          if [ -z "$CLIENT_ID" ]; then
            echo "::error::Environment variable EDGE_ADDONS_CLIENT_ID is not configured"
            exit 1
          fi
          if [ -z "$PRODUCT_ID" ]; then
            echo "::error::Environment variable EDGE_ADDONS_PRODUCT_ID is not configured"
            exit 1
          fi
          if ! [[ "$PRODUCT_ID" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]]; then
            echo "::error::EDGE_ADDONS_PRODUCT_ID must be the Partner Center product GUID, not the public Edge Add-ons extension ID"
            exit 1
          fi
          ARCHIVE="$(find dist -maxdepth 1 -name '*.zip' -type f -print -quit)"
          if [ -z "$ARCHIVE" ]; then
            echo "::error::No extension zip found in the downloaded artifact"
            exit 1
          fi
          echo "ARCHIVE=$ARCHIVE" >> "$GITHUB_ENV"
      - name: Upload and publish Microsoft Edge Add-ons extension
        shell: bash
        env:
          API_KEY: ${{ secrets.EDGE_ADDONS_API_KEY }}
          CLIENT_ID: ${{ vars.EDGE_ADDONS_CLIENT_ID }}
          PRODUCT_ID: ${{ vars.EDGE_ADDONS_PRODUCT_ID }}
          RELEASE_VERSION: ${{ needs.resolve.outputs.version }}
        run: |
          set -euo pipefail
          API_ROOT="https://api.addons.microsoftedge.microsoft.com/v1"
          UPLOAD_HEADERS="$RUNNER_TEMP/edge-upload-headers.txt"
          UPLOAD_RESPONSE="$RUNNER_TEMP/edge-upload-response.json"
          STATUS_RESPONSE="$RUNNER_TEMP/edge-status-response.json"
          PUBLISH_HEADERS="$RUNNER_TEMP/edge-publish-headers.txt"
          PUBLISH_RESPONSE="$RUNNER_TEMP/edge-publish-response.json"
          operation_id_from_headers() {
            local headers="$1"
            local location
            location="$(awk '
              tolower($1) == "location:" {
                sub(/\r$/, "")
                sub(/^[^:]*:[[:space:]]*/, "")
                print
                exit
              }
            ' "$headers")"
            location="${location%%\?*}"
            printf '%s' "${location##*/}"
          }
          poll_operation() {
            local operation_name="$1"
            local status_url="$2"
            local status="InProgress"
            local http_status
            for attempt in $(seq 1 30); do
              sleep 5
              http_status="$(curl --silent --show-error \
                --output "$STATUS_RESPONSE" \
                --write-out '%{http_code}' \
                --header "Authorization: ApiKey $API_KEY" \
                --header "X-ClientID: $CLIENT_ID" \
                "$status_url")"
              if [ "$http_status" -lt 200 ] || [ "$http_status" -ge 300 ]; then
                echo "::error::Microsoft Edge Add-ons $operation_name status check failed with HTTP $http_status"
                jq . "$STATUS_RESPONSE" || cat "$STATUS_RESPONSE"
                exit 1
              fi
              status="$(jq -r '.status // empty' "$STATUS_RESPONSE")"
              echo "$operation_name status check $attempt/30: $status"
              case "$status" in
                Succeeded)
                  return 0
                  ;;
                InProgress)
                  ;;
                Failed)
                  echo "::error::Microsoft Edge Add-ons $operation_name failed"
                  jq . "$STATUS_RESPONSE"
                  exit 1
                  ;;
                *)
                  echo "::error::Microsoft Edge Add-ons returned an unknown $operation_name status: $status"
                  jq . "$STATUS_RESPONSE"
                  exit 1
                  ;;
              esac
            done
            echo "::error::Microsoft Edge Add-ons $operation_name did not complete after 30 checks"
            jq . "$STATUS_RESPONSE"
            exit 1
          }
          HTTP_STATUS="$(curl --silent --show-error \
            --output "$UPLOAD_RESPONSE" \
            --dump-header "$UPLOAD_HEADERS" \
            --write-out '%{http_code}' \
            --request POST \
            --header "Authorization: ApiKey $API_KEY" \
            --header "X-ClientID: $CLIENT_ID" \
            --header "Content-Type: application/zip" \
            --data-binary "@$ARCHIVE" \
            "$API_ROOT/products/$PRODUCT_ID/submissions/draft/package")"
          if [ "$HTTP_STATUS" != "202" ]; then
            echo "::error::Microsoft Edge Add-ons upload failed with HTTP $HTTP_STATUS"
            jq . "$UPLOAD_RESPONSE" || cat "$UPLOAD_RESPONSE"
            exit 1
          fi
          UPLOAD_OPERATION_ID="$(operation_id_from_headers "$UPLOAD_HEADERS")"
          if [ -z "$UPLOAD_OPERATION_ID" ]; then
            echo "::error::Microsoft Edge Add-ons upload response has no Location operation ID"
            cat "$UPLOAD_HEADERS"
            exit 1
          fi
          poll_operation \
            "package upload" \
            "$API_ROOT/products/$PRODUCT_ID/submissions/draft/package/operations/$UPLOAD_OPERATION_ID"
          HTTP_STATUS="$(curl --silent --show-error \
            --output "$PUBLISH_RESPONSE" \
            --dump-header "$PUBLISH_HEADERS" \
            --write-out '%{http_code}' \
            --request POST \
            --header "Authorization: ApiKey $API_KEY" \
            --header "X-ClientID: $CLIENT_ID" \
            --header "Content-Type: application/json" \
            --data "{\"notes\":\"Automated BrowserSkill extension v${RELEASE_VERSION} release from GitHub Actions.\"}" \
            "$API_ROOT/products/$PRODUCT_ID/submissions")"
          if [ "$HTTP_STATUS" != "202" ]; then
            echo "::error::Microsoft Edge Add-ons publish failed with HTTP $HTTP_STATUS"
            jq . "$PUBLISH_RESPONSE" || cat "$PUBLISH_RESPONSE"
            exit 1
          fi
          PUBLISH_OPERATION_ID="$(operation_id_from_headers "$PUBLISH_HEADERS")"
          if [ -z "$PUBLISH_OPERATION_ID" ]; then
            echo "::error::Microsoft Edge Add-ons publish response has no Location operation ID"
            cat "$PUBLISH_HEADERS"
            exit 1
          fi
          poll_operation \
            "submission" \
            "$API_ROOT/products/$PRODUCT_ID/submissions/operations/$PUBLISH_OPERATION_ID"
          echo "Microsoft Edge Add-ons submission created successfully:"
          jq '{status, message, errorCode, errors}' "$STATUS_RESPONSE"
@@ -7,18 +7,10 @@ dist/
 .output/
 .wxt/
 .web-extension-id
 .pnpm-store/
 # Git worktrees
 .worktrees/
 # Logs
 *.log
 # Local browser evaluation artifacts
 evals/browser/results/
 evals/browser/agents.local.json
 # macOS
 .DS_Store
@@ -1,109 +0,0 @@
 # Changelog
 All notable changes to BrowserSkill will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 Starting from 0.2.0, CLI / Extension / DSH Plugin share the same version number.
 ## [0.2.1] - 2026-09-09
 ### Changed
 - DSH Plugin: clarified installation, configuration, profile restart, and upgrade instructions
 ### Fixed
 - CLI: reliable Windows self-updates, including executable replacement and daemon restart
 - CLI: Windows named-pipe connection continuity and stale daemon process detection
 - Windows installer: PowerShell 5.1 compatibility, path quoting, and staged executable replacement
 - CLI / DSH Plugin: cancellation propagation and upload/download cleanup when the parent process exits
 - Extension: tab ownership and session cleanup when agent tabs fail to open or borrowed tabs are returned or closed
 - Extension: navigation recovery when other extensions restrict Chrome DevTools Protocol access
 - Extension: background input filling, automatic append behavior, and verification of field values before reporting success
 - Extension: match observed form state to the correct element after page changes
 - Extension: UUID generation fallback for recording and overlays on insecure origins
 - Browser locale matching for regional language variants
 - DSH Plugin: observation state synchronization, thumbnail capture lifecycle, and stale preview cleanup
 - DSH Plugin: removed the obsolete client runtime host dependency
 ## [0.2.0] - 2026-09-02
 ### Added
 - File transfer: upload and download support across CLI, Extension, and DSH Plugin
 - File transfer: drag-and-drop upload (`drop-to-upload`)
 - VOM semantic graph, name enrichment, and hover perception modules
 - VOM hover probing (opt-in via `observe` parameter)
 - DSH Plugin: browser tool parity with CLI commands
 - Edge Add-ons automated publishing in CI
 - Protocol upgrade reminder when CLI / Extension protocol versions differ
 - Browser evaluation harness (`evals/browser/`)
 - Unified release script (`scripts/release.mjs`)
 ### Changed
 - **Version scheme**: all three components now share the same semver
 - VOM rendering algorithm optimizations
 - Leaner SKILL.md agent instructions
 - DSH Plugin: simplified browser commands
 - Borrow confirmation UX — proactive focus and longer timeout
 - PiP window now has a close button
 ### Fixed
 - Screenshot media type detection (was hard-coded to `image/png`)
 - DSH Plugin session lifecycle stability
 - DSH Plugin Cordis package ID mismatch
 - Observation thumbnail media type sniffing
 - Upload/download race conditions and layout bypass issues
 - VOM repeated name and safety policy issues
 ---
 *Previous releases used independent version numbers per component.*
 ## CLI 0.1.11 / Extension 0.1.7 / DSH Plugin 0.1.2 — 2026-08-26 ~ 2026-08-29
 ### Added
 - DSH Plugin sidebar integration, session lifecycle, and archive cleanup
 - Recorder iframe and OOPIF support
 ### Changed
 - VOM functional refactor
 ### Fixed
 - Recorder safety policy and bug fixes
 ## CLI 0.1.10 / Extension 0.1.6 — 2026-08-08
 ### Added
 - VOM observation recording and settled-state detection
 - Record overlay timer
 ### Fixed
 - Browser keepalive disconnect handling
 ## CLI 0.1.9 / Extension 0.1.5 — 2026-07-29
 ### Added
 - CLI auto-update mechanism
 - Trace v3 protocol and recorder
 ### Fixed
 - MV3 keepalive disconnect
 ## CLI 0.1.8 / Extension 0.1.4 — 2026-07-22
 ### Added
 - More browser interaction actions
 ### Fixed
 - Windows named-pipe hash-only path issue
 ## CLI 0.1.7 / Extension 0.1.3 — 2026-07-07
 Initial public release pair.
 ## CLI 0.1.6 — 2026-06-30
 ### Fixed
 - Minor CLI fixes
 ## CLI 0.1.5 / Extension 0.1.2 — 2026-06-22
 First tagged releases.
@@ -134,7 +134,7 @@ dependencies = [
 [[package]]
 name = "bsk"
-version = "0.2.1"
+version = "0.1.10"
 dependencies = [
 "anyhow",
 "base64",
@@ -169,7 +169,7 @@ dependencies = [
 [[package]]
 name = "bsk-protocol"
-version = "0.2.1"
+version = "0.1.10"
 dependencies = [
 "schemars",
 "semver",
@@ -7,7 +7,7 @@ members = [
 default-members = ["crates/bsk-cli"]
 [workspace.package]
-version = "0.2.1"
+version = "0.1.10"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT"
@@ -43,7 +43,7 @@ rand = "0.8"
 uuid = { version = "1", features = ["v4", "serde"] }
 # Workspace crates (version required for `cargo publish` of dependents)
-bsk-protocol = { version = "0.2.1", path = "crates/bsk-protocol" }
+bsk-protocol = { version = "0.1.9", path = "crates/bsk-protocol" }
 [profile.release]
 strip = "symbols"
@@ -147,26 +147,20 @@ Start a new Agent session and write a prompt that needs the browser, for example
 Using [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`)?
 BrowserSkill ships a first-class dsh plugin on npm as
 [`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin).
-It gives the agent native `browser_*` tools and a live view of its browser sessions
+It injects native `browser_*` tools (no shelling out to `bsk`) and a live Web UI
-in the Web UI. The plugin runs `bsk` on the agent's behalf.
+overlay of each Agent Window.
-Install the `bsk` CLI and connect the browser extension first. Then add the plugin
+Add it to a dsh profile, then start that profile:
 to a dsh profile and start it (replace `web` with your profile name):
 ```sh
 dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
 dsh --profile web
 ```
-The plugin includes the `browser-skill` skill, so `bsk install-skill` is not needed
+The plugin carries its own copy of the skill, so `bsk install-skill` is not needed
-for dsh. Installed plugins do not update automatically. To upgrade this plugin:
+for dsh — but the `bsk` CLI and the browser extension are still prerequisites. See
-
+the [plugin README](packages/dsh-plugin-browserskill/README.md) for the tool list,
-```sh
+configuration, and the observation overlay.
 dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest
 ```
 Restart the profile after upgrading. See the
 [plugin README](packages/dsh-plugin-browserskill/README.md) for usage and configuration.
 ## How It Works
@@ -214,7 +208,6 @@ The repository is a Cargo + pnpm workspace:
 - `apps/extension` — browser extension
 - `packages/ui` and `packages/i18n` — shared extension UI support
 - `packages/dsh-plugin-browserskill` — DeepSeek Harness plugin (`@wxg-prc-cpg/browser-skill-dsh-plugin`)
 - [`evals/browser`](evals/browser/README.md) — deterministic local pages and agent-neutral browser capability evaluation
 ## License
@@ -125,22 +125,16 @@ bsk install-skill
 ## DeepSeek Harness 插件
-在用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）？BrowserSkill 提供了官方 dsh 插件，已发布到 npm：[`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)。它为 Agent 提供原生 `browser_*` 工具，由插件代为调用 `bsk`，并在 Web UI 中实时展示浏览器会话。
+在用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）？BrowserSkill 提供了官方 dsh 插件，已发布到 npm：[`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)。它会注入原生 `browser_*` 工具（无需再通过 Shell 调用 `bsk`），并在 Web UI 中实时观察每个 Agent Window。
-先安装 `bsk` CLI 并连接浏览器扩展，再将插件装进 dsh profile 并启动（将 `web` 替换为你的 profile 名称）：
+把它装进某个 dsh profile，然后启动该 profile：
 ```sh
 dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
 dsh --profile web
 ```
-插件自带 `browser-skill` skill，所以在 dsh 下无需执行 `bsk install-skill`。已安装的插件不会自动更新；升级此插件请运行：
+插件自带 skill，所以在 dsh 下无需执行 `bsk install-skill`；但 `bsk` CLI 和浏览器扩展仍是前置条件。工具清单、配置项与观察浮层见[插件 README](packages/dsh-plugin-browserskill/README.md)。
 ```sh
 dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest
 ```
 升级后重启该 profile。用法与配置见[插件 README](packages/dsh-plugin-browserskill/README.md)。
 ## 工作原理
@@ -184,7 +178,6 @@ Agent 不直接与浏览器通信。它通过 `bsk` CLI 下发浏览器任务；
 - `apps/extension` — 浏览器扩展
 - `packages/ui` 和 `packages/i18n` — 扩展 UI 共享支持
 - `packages/dsh-plugin-browserskill` — DeepSeek Harness 插件（`@wxg-prc-cpg/browser-skill-dsh-plugin`）
 - [`evals/browser`](evals/browser/README.zh-CN.md) — 确定性本地页面与 Agent 无关的浏览器能力测试台
 ## 许可证
@@ -1,81 +0,0 @@
 <!doctype html>
 <html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>BrowserSkill file-transfer fixture</title>
    <style>
      body { font: 16px system-ui; max-width: 760px; margin: 48px auto; }
      .actions { display: flex; gap: 12px; align-items: center; margin: 24px 0; }
      button, a { padding: 10px 16px; border: 1px solid #777; border-radius: 8px; }
      a[aria-disabled="true"] { opacity: .45; pointer-events: none; }
      #drop { padding: 36px; border: 3px dashed #777; border-radius: 12px; text-align: center; }
      #drop.dragging { border-color: #2563eb; background: #eff6ff; }
      img { display: block; max-width: 480px; max-height: 360px; margin-top: 20px; }
    </style>
  </head>
  <body>
    <h1>Upload then download the same image</h1>
    <p id="status">No image selected</p>
    <div class="actions">
      <button id="upload" type="button">Upload through file input</button>
      <input id="file" type="file" accept="image/png" hidden />
      <a id="download" aria-disabled="true">Download uploaded image</a>
    </div>
    <div id="drop" role="button" tabindex="0">Drop an image here</div>
    <img id="preview" alt="Uploaded image preview" hidden />
    <script>
      const input = document.querySelector('#file');
      const upload = document.querySelector('#upload');
      const drop = document.querySelector('#drop');
      const download = document.querySelector('#download');
      const preview = document.querySelector('#preview');
      const status = document.querySelector('#status');
      let objectUrl;
      window.__bskTransferFixture = { events: [], result: null };
      function accept(file, mechanism) {
        if (!file) return;
        if (objectUrl) URL.revokeObjectURL(objectUrl);
        objectUrl = URL.createObjectURL(file);
        preview.src = objectUrl;
        preview.hidden = false;
        download.href = objectUrl;
        download.download = file.name;
        download.removeAttribute('aria-disabled');
        status.textContent = `Ready via ${mechanism}: ${file.name} (${file.size} bytes)`;
        window.__bskTransferFixture.result = {
          mechanism,
          name: file.name,
          size: file.size,
          type: file.type,
          hasPathProperty: 'path' in file,
        };
      }
      upload.addEventListener('click', () => input.click());
      input.addEventListener('change', () => accept(input.files[0], 'input'));
      for (const type of ['dragenter', 'dragover']) {
        drop.addEventListener(type, event => {
          const types = [...event.dataTransfer.types];
          window.__bskTransferFixture.events.push({ type, types });
          if (!types.includes('Files')) return;
          event.preventDefault();
          drop.classList.add('dragging');
        });
      }
      drop.addEventListener('dragleave', () => drop.classList.remove('dragging'));
      drop.addEventListener('drop', event => {
        window.__bskTransferFixture.events.push({
          type: 'drop',
          types: [...event.dataTransfer.types],
          fileCount: event.dataTransfer.files.length,
        });
        event.preventDefault();
        drop.classList.remove('dragging');
        accept(event.dataTransfer.files[0], 'drop');
      });
    </script>
  </body>
 </html>
@@ -1,6 +1,6 @@
 {
  "name": "@browser-skill/extension",
-  "version": "0.2.1",
+  "version": "0.1.6",
  "private": true,
  "type": "module",
  "scripts": {
@@ -254,69 +254,6 @@ describe("ChromiumCdp", () => {
    expect(cdp.isAttached(7)).toBe(false);
  });
  it.each([
    false,
    true,
  ])("waits for detach before reconnecting a returned tab (detach rejects: %s)", async (rejectDetach) => {
    const { api } = fakeApi();
    const attached = new Set<number>();
    let finishDetach!: () => void;
    vi.mocked(api.attach).mockImplementation(async ({ tabId }) => {
      if (attached.has(tabId!)) throw new Error("Another debugger is already attached");
      attached.add(tabId!);
    });
    vi.mocked(api.detach).mockImplementation(async ({ tabId }) => {
      attached.delete(tabId!);
    });
    vi.mocked(api.detach).mockImplementationOnce(
      ({ tabId }) =>
        new Promise<void>((resolve, reject) => {
          finishDetach = () => {
            attached.delete(tabId!);
            if (rejectDetach) reject(new Error("tab already detached"));
            else resolve();
          };
        }),
    );
    const cdp = new ChromiumCdp(api);
    cdp.trackSessionTab("aa11", 7);
    await cdp.ensureAttached(7);
    const returning = cdp.releaseSessionTab("aa11", 7);
    await vi.waitFor(() => expect(api.detach).toHaveBeenCalledOnce());
    let duplicateDetachFinished = false;
    const duplicateDetach = cdp.detach(7).then(() => {
      duplicateDetachFinished = true;
    });
    cdp.trackSessionTab("bb22", 7);
    // Register rejection handlers immediately; the pre-fix driver rejects
    // both commands while the browser still has the previous attachment.
    const pending = Promise.allSettled([
      cdp.send(7, "Runtime.evaluate", { expression: "document.title" }),
      cdp.send(7, "DOM.getDocument"),
    ]);
    await cdp.send(8, "DOM.getDocument");
    const finishedEarly = duplicateDetachFinished;
    finishDetach();
    await Promise.all([returning, duplicateDetach]);
    expect(await pending).toEqual([
      { status: "fulfilled", value: { ok: true } },
      { status: "fulfilled", value: { ok: true } },
    ]);
    expect(finishedEarly).toBe(false);
    expect(vi.mocked(api.attach).mock.calls.filter(([target]) => target.tabId === 7)).toHaveLength(
      2,
    );
    expect(cdp.isAttached(7)).toBe(true);
    expect(cdp.isAttached(8)).toBe(true);
    await cdp.detachSession("bb22");
    expect(api.detach).toHaveBeenCalledTimes(2);
    expect(cdp.isAttached(7)).toBe(false);
    expect(attached.has(7)).toBe(false);
    expect(cdp.isAttached(8)).toBe(true);
  });
  it("detachAll() iterates every cached tab", async () => {
    const { api } = fakeApi();
    const cdp = new ChromiumCdp(api);
@@ -714,155 +651,6 @@ describe("ChromiumCdp", () => {
    expect(cdp.networkEntriesSince(33, 0, 50, 1000).entries[0].url).toBeUndefined();
  });
  it("releases only the returning session's claim on a tab", async () => {
    const { api } = fakeApi();
    const cdp = new ChromiumCdp(api);
    await cdp.ensureAttached(1);
    await cdp.ensureAttached(2);
    cdp.trackSessionTab("aa11", 1);
    cdp.trackSessionTab("bb22", 1);
    cdp.trackSessionTab("aa11", 2);
    await cdp.releaseSessionTab("unknown", 1);
    await cdp.releaseSessionTab("aa11", 1);
    expect(api.detach).not.toHaveBeenCalled();
    await cdp.releaseSessionTab("bb22", 1);
    await cdp.releaseSessionTab("bb22", 1);
    expect(api.detach).toHaveBeenCalledExactlyOnceWith({ tabId: 1 });
    expect(cdp.isAttached(2)).toBe(true);
    await cdp.detachSession("aa11");
    expect(api.detach).toHaveBeenCalledTimes(2);
    expect(api.detach).toHaveBeenLastCalledWith({ tabId: 2 });
  });
  it.each([
    false,
    true,
  ])("releases a tab with an attachment in flight (new owner: %s)", async (newOwner) => {
    const { api } = fakeApi();
    let finishAttach!: () => void;
    vi.mocked(api.attach).mockImplementationOnce(
      () =>
        new Promise<void>((resolve) => {
          finishAttach = resolve;
        }),
    );
    const cdp = new ChromiumCdp(api);
    cdp.trackSessionTab("aa11", 1);
    const attaching = cdp.ensureAttached(1);
    const releasing = cdp.releaseSessionTab("aa11", 1);
    if (newOwner) cdp.trackSessionTab("bb22", 1);
    finishAttach();
    await Promise.all([attaching, releasing]);
    expect(cdp.isAttached(1)).toBe(newOwner);
    expect(api.detach).toHaveBeenCalledTimes(newOwner ? 0 : 1);
  });
  it("stops accepting dialogs on a returned tab even when another session keeps CDP attached", async () => {
    const { api, onEvent } = fakeApi();
    let controlled = true;
    const cdp = new ChromiumCdp(api, { shouldAutoAcceptDialog: () => controlled });
    cdp.trackSessionTab("aa11", 1);
    cdp.trackSessionTab("bb22", 1);
    await cdp.ensureAttached(1);
    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", {
      type: "confirm",
      message: "before return",
    });
    await vi.waitFor(() => expect(cdp.dialogsSince(1, 0)).toHaveLength(1));
    vi.mocked(api.sendCommand).mockClear();
    controlled = false;
    await cdp.releaseSessionTab("aa11", 1);
    expect(cdp.isAttached(1)).toBe(true);
    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", {
      type: "confirm",
      message: "after return",
    });
    await Promise.resolve();
    expect(api.sendCommand).not.toHaveBeenCalled();
    expect(cdp.dialogsSince(1, 0)).toHaveLength(1);
    controlled = true;
    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", {
      type: "alert",
      message: "borrowed again",
    });
    await vi.waitFor(() => expect(cdp.dialogsSince(1, 0)).toHaveLength(2));
    expect(api.sendCommand).toHaveBeenCalledExactlyOnceWith(
      { tabId: 1 },
      "Page.handleJavaScriptDialog",
      { accept: true },
    );
  });
  it("ignores dialog events after detach, including a pending eligibility check", async () => {
    const { api, onEvent } = fakeApi();
    let resolveEligibility!: (value: boolean) => void;
    const shouldAutoAcceptDialog = vi.fn(
      () =>
        new Promise<boolean>((resolve) => {
          resolveEligibility = resolve;
        }),
    );
    const cdp = new ChromiumCdp(api, { shouldAutoAcceptDialog });
    await cdp.ensureAttached(1);
    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", { type: "alert" });
    await cdp.detach(1);
    resolveEligibility(true);
    await Promise.resolve();
    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", { type: "alert" });
    expect(shouldAutoAcceptDialog).toHaveBeenCalledOnce();
    expect(api.sendCommand).not.toHaveBeenCalledWith(
      expect.anything(),
      "Page.handleJavaScriptDialog",
      expect.anything(),
    );
    expect(cdp.dialogsSince(1, 0)).toEqual([]);
  });
  it("does not accept dialogs when the tab's current scope cannot be determined", async () => {
    const { api, onEvent } = fakeApi();
    const shouldAutoAcceptDialog = vi.fn(async () => {
      throw new Error("tab is gone");
    });
    const cdp = new ChromiumCdp(api, { shouldAutoAcceptDialog });
    await cdp.ensureAttached(1);
    vi.mocked(api.sendCommand).mockClear();
    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", { type: "confirm" });
    await Promise.resolve();
    expect(shouldAutoAcceptDialog).toHaveBeenCalledWith(1);
    expect(api.sendCommand).not.toHaveBeenCalled();
    expect(cdp.dialogsSince(1, 0)).toEqual([]);
  });
  it("does not restore dialog state when an acceptance completes after detach", async () => {
    const { api, onEvent } = fakeApi();
    const cdp = new ChromiumCdp(api);
    await cdp.ensureAttached(1);
    let finishAccept!: () => void;
    vi.mocked(api.sendCommand).mockImplementationOnce(
      () =>
        new Promise<void>((resolve) => {
          finishAccept = resolve;
        }),
    );
    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", { type: "alert" });
    await cdp.detach(1);
    finishAccept();
    await Promise.resolve();
    expect(cdp.dialogsSince(1, 0)).toEqual([]);
    expect(cdp.dialogCursor(1)).toBe(0);
  });
  it("detachSession only detaches tabs no other session owns", async () => {
    const { api } = fakeApi();
    const cdp = new ChromiumCdp(api);
@@ -165,7 +165,6 @@ export class ChromiumCdp {
  private readonly api: CdpDebuggerApi;
  private readonly attachedTabs = new Set<number>();
  private readonly attachInFlight = new Map<number, Promise<void>>();
  private readonly detachInFlight = new Map<number, Promise<void>>();
  private readonly tabOwners = new Map<number, Set<string>>();
  private readonly dialogBuffers = new Map<number, JavaScriptDialogInfo[]>();
  private readonly dialogSequences = new Map<number, number>();
@@ -183,13 +182,7 @@ export class ChromiumCdp {
  private networkSubscription: { dispose(): void } | null = null;
  private frameTargetSubscription: { dispose(): void } | null = null;
-  constructor(
+  constructor(api: CdpDebuggerApi = chromeDebuggerApi) {
    api: CdpDebuggerApi = chromeDebuggerApi,
    private readonly options: {
      /** CDP observation alone does not authorize dismissing user dialogs. */
      shouldAutoAcceptDialog?: (tabId: number) => boolean | Promise<boolean>;
    } = {},
  ) {
    this.api = api;
    this.bindAutoDetach();
    this.bindDialogHandler();
@@ -200,10 +193,6 @@ export class ChromiumCdp {
  /** Attach to `tabId` if we haven't already in this driver. */
  async ensureAttached(tabId: number): Promise<void> {
    // Returning a tab clears the cache before Chrome finishes detaching.
    // New observers must wait before opening the next connection to that tab.
    const detaching = this.detachInFlight.get(tabId);
    if (detaching) await detaching;
    if (this.attachedTabs.has(tabId)) return;
    const existing = this.attachInFlight.get(tabId);
    if (existing) {
@@ -436,11 +425,6 @@ export class ChromiumCdp {
  /** Detach if attached; never throws. */
  async detach(tabId: number): Promise<void> {
    const existing = this.detachInFlight.get(tabId);
    if (existing) {
      await existing;
      return;
    }
    this.attachInFlight.delete(tabId);
    if (!this.attachedTabs.has(tabId)) return;
    this.attachedTabs.delete(tabId);
@@ -448,19 +432,13 @@ export class ChromiumCdp {
    this.clearConsoleState(tabId);
    this.clearNetworkState(tabId);
    this.clearFrameState(tabId);
-    const detach = (async () => {
+    try {
-      try {
+      await this.api.detach({ tabId });
-        await this.api.detach({ tabId });
+    } catch (err) {
-      } catch (err) {
+      // Tab may already be gone — Chrome auto-detaches on close. Log
-        // Tab may already be gone — Chrome auto-detaches on close. Log
+      // at debug so production builds aren't noisy.
-        // at debug so production builds aren't noisy.
+      console.debug("[bsk cdp] detach failed (likely tab already closed)", err);
-        console.debug("[bsk cdp] detach failed (likely tab already closed)", err);
+    }
      }
    })().finally(() => {
      this.detachInFlight.delete(tabId);
    });
    this.detachInFlight.set(tabId, detach);
    await detach;
  }
  /** True iff `ensureAttached(tabId)` has succeeded since the last detach. */
@@ -475,17 +453,6 @@ export class ChromiumCdp {
    this.tabOwners.set(tabId, owners);
  }
  /** Release one session's claim, preserving attachments still used by another. */
  async releaseSessionTab(sessionId: string, tabId: number): Promise<void> {
    const owners = this.tabOwners.get(tabId);
    if (!owners?.delete(sessionId) || owners.size > 0) return;
    this.tabOwners.delete(tabId);
    // An observation may still be attaching when the tab is returned. Wait
    // for it so detach cannot miss the attachment or remove a new owner's claim.
    await this.attachInFlight.get(tabId)?.catch(() => {});
    if (!this.tabOwners.has(tabId)) await this.detach(tabId);
  }
  /** Subscribe to all CDP events. Returned disposable removes the listener. */
  onEvent(handler: (source: CdpDebuggee, method: string, params: unknown) => void): {
    dispose(): void;
@@ -672,23 +639,13 @@ export class ChromiumCdp {
  }
  private async onJavaScriptDialogOpening(tabId: number, params: unknown): Promise<void> {
    if (!this.attachedTabs.has(tabId) && !this.attachInFlight.has(tabId)) return;
    const parsed = parseDialogOpeningParams(params);
    try {
      if (
        this.options.shouldAutoAcceptDialog &&
        !(await this.options.shouldAutoAcceptDialog(tabId))
      ) {
        return;
      }
      // The tab may have been returned while its current scope was checked.
      if (!this.attachedTabs.has(tabId) && !this.attachInFlight.has(tabId)) return;
      const handleParams: { accept: boolean; promptText?: string } = { accept: true };
      if (parsed.type === "prompt") {
        handleParams.promptText = parsed.defaultPrompt ?? "";
      }
      await this.api.sendCommand({ tabId }, "Page.handleJavaScriptDialog", handleParams);
      if (!this.attachedTabs.has(tabId) && !this.attachInFlight.has(tabId)) return;
      const sequence = (this.dialogSequences.get(tabId) ?? 0) + 1;
      this.dialogSequences.set(tabId, sequence);
      this.appendDialog(tabId, {
@@ -878,9 +835,15 @@ export class ChromiumCdp {
  /** Detach tabs only when no other live session has claimed them. */
  async detachSession(sessionId: string): Promise<void> {
-    await Promise.all(
+    const tabsToDetach: number[] = [];
-      Array.from(this.tabOwners.keys(), (tabId) => this.releaseSessionTab(sessionId, tabId)),
+    for (const [tabId, owners] of this.tabOwners) {
-    );
+      owners.delete(sessionId);
      if (owners.size === 0) {
        this.tabOwners.delete(tabId);
        tabsToDetach.push(tabId);
      }
    }
    await Promise.all(tabsToDetach.map((tabId) => this.detach(tabId)));
  }
 }
@@ -23,7 +23,7 @@ describe("BorrowConfirmationOverlay", () => {
            id: "req-1",
            isActiveTab: true,
            tabTitle: "Example",
-            timeoutMs: 60_000,
+            timeoutMs: 5000,
            onAllow,
            onDeny,
          },
@@ -32,7 +32,7 @@ describe("BorrowConfirmationOverlay", () => {
    );
    expect(screen.getByText("允许借用标签页？")).toBeTruthy();
-    for (let i = 0; i < 60; i++) {
+    for (let i = 0; i < 5; i++) {
      await act(async () => {
        await vi.advanceTimersByTimeAsync(1000);
      });
@@ -66,7 +66,7 @@ describe("BorrowConfirmationOverlay", () => {
            id: "req-fallback",
            isActiveTab: true,
            tabTitle: "Example",
-            timeoutMs: 60_000,
+            timeoutMs: 5000,
            onAllow,
            onDeny,
          },
@@ -74,7 +74,7 @@ describe("BorrowConfirmationOverlay", () => {
      />,
    );
-    for (let i = 0; i < 60; i++) {
+    for (let i = 0; i < 5; i++) {
      await act(async () => {
        await vi.advanceTimersByTimeAsync(1000);
      });
@@ -1,12 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { RecordStepPayload } from "@/lib/record-bridge";
+import { RECORD_STOP, type RecordStepPayload } from "@/lib/record-bridge";
-import { startRecordCapture } from "../record-capture";
+import { handleRecordContentMessage, startRecordCapture } from "../record-capture";
 vi.stubGlobal("chrome", {
  runtime: {
-    sendMessage: vi.fn((message: { sequence?: number }) =>
+    sendMessage: vi.fn(() => Promise.resolve()),
      Promise.resolve({ ok: true, sequence: message.sequence }),
    ),
  },
 });
@@ -48,6 +46,58 @@ function click(el: Element): void {
  el.dispatchEvent(new MouseEvent("click", { bubbles: true, button: 0, detail: 1 }));
 }
 describe("handleRecordContentMessage stop/cancel", () => {
  it("ignores STOP when no recording is active", () => {
    const dispose = vi.fn();
    const onStop = vi.fn();
    const setActiveRequestId = vi.fn();
    const setCapture = vi.fn();
    const sendResponse = vi.fn();
    const needsAsync = handleRecordContentMessage(
      { type: RECORD_STOP, requestId: "rec-stale" },
      {
        activeRequestId: null,
        capture: { dispose },
        setActiveRequestId,
        setCapture,
        onStart: vi.fn(),
        onStop,
      },
      sendResponse,
    );
    expect(needsAsync).toBe(false);
    expect(dispose).not.toHaveBeenCalled();
    expect(onStop).not.toHaveBeenCalled();
    expect(setActiveRequestId).not.toHaveBeenCalled();
    expect(setCapture).not.toHaveBeenCalled();
    expect(sendResponse).not.toHaveBeenCalled();
  });
  it("ignores STOP for a mismatched requestId", () => {
    const dispose = vi.fn();
    const onStop = vi.fn();
    const needsAsync = handleRecordContentMessage(
      { type: RECORD_STOP, requestId: "rec-other" },
      {
        activeRequestId: "rec-1",
        capture: { dispose },
        setActiveRequestId: vi.fn(),
        setCapture: vi.fn(),
        onStart: vi.fn(),
        onStop,
      },
      vi.fn(),
    );
    expect(needsAsync).toBe(false);
    expect(dispose).not.toHaveBeenCalled();
    expect(onStop).not.toHaveBeenCalled();
  });
 });
 describe("record-capture semantic", () => {
  let steps: RecordStepPayload[];
@@ -124,19 +174,6 @@ describe("record-capture semantic", () => {
    ]);
  });
  it("does not emit page navigation from a child Document capture", () => {
    const originalUrl = location.href;
    const capture = startRecordCapture("rec-child", (step) => steps.push(step), {
      captureNavigation: false,
    });
    history.pushState({}, "", "#inside-frame");
    expect(steps).toEqual([]);
    capture.dispose();
    history.replaceState({}, "", originalUrl);
  });
  it("does not record clicks on anonymous layout divs", () => {
    document.body.innerHTML = `
      <div id="chrome">page chrome</div>
@@ -191,7 +228,6 @@ describe("record-capture semantic", () => {
    expect(steps[0]).toMatchObject({
      op: "hover",
      target: { role: "button", name: "Open user navigation menu" },
      geometry: { tag: "button", rect: { x: 900, y: 8, w: 32, h: 32 } },
    });
    expect(steps[1]).toMatchObject({
      op: "click",
@@ -1,124 +0,0 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { RecordFramePortMessage } from "@/lib/recording/frame-bridge";
 import { RECORD_FRAME_START } from "@/lib/recording/frame-bridge";
 import { RECORD_DOCUMENT_ATTRIBUTE } from "@/shared/recording-document-identity";
 import { RecordFrameAgent } from "../recording/frame-agent";
 class PortListeners<T extends (...args: never[]) => unknown> {
  readonly values = new Set<T>();
  addListener = (listener: T) => this.values.add(listener);
  removeListener = (listener: T) => this.values.delete(listener);
 }
 function portHarness() {
  const onMessage = new PortListeners<(message: unknown) => void>();
  const onDisconnect = new PortListeners<() => void>();
  const outbound: RecordFramePortMessage[] = [];
  const port = {
    name: "bsk-record-frame",
    onMessage,
    onDisconnect,
    postMessage(message: RecordFramePortMessage) {
      outbound.push(message);
      if (message.type === "ready") {
        queueMicrotask(() => {
          for (const listener of onMessage.values) {
            listener({
              type: "ready_ack",
              requestId: message.requestId,
              producerId: message.producerId,
            });
          }
        });
      }
    },
    disconnect: vi.fn(),
  } as unknown as chrome.runtime.Port;
  return {
    port,
    outbound,
    receive(message: RecordFramePortMessage) {
      for (const listener of onMessage.values) listener(message);
    },
  };
 }
 describe("RecordFrameAgent", () => {
  afterEach(() => {
    vi.unstubAllGlobals();
    document.documentElement.removeAttribute(RECORD_DOCUMENT_ATTRIBUTE);
    document.body.replaceChildren();
  });
  it("starts when crypto.randomUUID is unavailable", async () => {
    const harness = portHarness();
    const getRandomValues = vi.fn((bytes: Uint8Array) => {
      bytes.fill(0x11);
      return bytes;
    });
    vi.stubGlobal("crypto", { getRandomValues });
    vi.stubGlobal("chrome", {
      runtime: {
        connect: vi.fn(() => harness.port),
        sendMessage: vi.fn(),
      },
    });
    const agent = new RecordFrameAgent();
    await expect(
      agent.start({ type: RECORD_FRAME_START, requestId: "rec-http", startedAtMs: 10 }),
    ).resolves.toEqual({ ok: true });
    expect(getRandomValues).toHaveBeenCalled();
  });
  it("keeps a failed stop retryable and flushes the final dirty fill", async () => {
    const harness = portHarness();
    const sendMessage = vi
      .fn<(message: { sequence: number }) => Promise<unknown>>()
      .mockRejectedValueOnce(new Error("offline"))
      .mockRejectedValueOnce(new Error("still offline"))
      .mockImplementation(async (message) => ({ ok: true, sequence: message.sequence }));
    vi.stubGlobal("chrome", {
      runtime: {
        connect: vi.fn(() => harness.port),
        sendMessage,
      },
    });
    document.body.innerHTML = `<label for="draft">Draft</label><input id="draft" />`;
    const agent = new RecordFrameAgent();
    await expect(
      agent.start({ type: RECORD_FRAME_START, requestId: "rec-1", startedAtMs: 10 }),
    ).resolves.toEqual({ ok: true });
    expect(document.documentElement.hasAttribute(RECORD_DOCUMENT_ATTRIBUTE)).toBe(true);
    const input = document.querySelector("input")!;
    input.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
    input.value = "final value";
    input.dispatchEvent(new Event("input", { bubbles: true }));
    harness.receive({ type: "stop", requestId: "rec-1", commandId: "stop-1" });
    await vi.waitFor(() =>
      expect(harness.outbound).toContainEqual({
        type: "stopped",
        requestId: "rec-1",
        commandId: "stop-1",
        ok: false,
        error: "failed to deliver one or more recorded steps",
      }),
    );
    expect(document.documentElement.hasAttribute(RECORD_DOCUMENT_ATTRIBUTE)).toBe(true);
    harness.receive({ type: "stop", requestId: "rec-1", commandId: "stop-2" });
    await vi.waitFor(() =>
      expect(harness.outbound).toContainEqual({
        type: "stopped",
        requestId: "rec-1",
        commandId: "stop-2",
        ok: true,
      }),
    );
    expect(sendMessage).toHaveBeenCalledTimes(3);
    expect(document.documentElement.hasAttribute(RECORD_DOCUMENT_ATTRIBUTE)).toBe(false);
  });
 });
@@ -1,36 +0,0 @@
 import { describe, expect, it, vi } from "vitest";
 import type { RecordStepMessage } from "@/lib/record-bridge";
 import { RecordStepDelivery } from "../record-step-delivery";
 describe("RecordStepDelivery", () => {
  it("retries from the first unacknowledged sequence before sending later steps", async () => {
    const sent: RecordStepMessage[] = [];
    const send = vi.fn(async (message: RecordStepMessage) => {
      sent.push(message);
      if (sent.length === 1) throw new Error("service worker unavailable");
      return { ok: true, sequence: message.sequence };
    });
    const delivery = new RecordStepDelivery("rec-ordered", send, "document-1");
    delivery.enqueue({ op: "click", target: { tag: "button", name: "First" } });
    delivery.enqueue({ op: "click", target: { tag: "button", name: "Second" } });
    await expect(delivery.flush()).resolves.toBe(true);
    expect(sent.map((message) => message.sequence)).toEqual([1, 1, 2]);
    expect(sent.map((message) => message.step.target?.name)).toEqual(["First", "First", "Second"]);
  });
  it("keeps unacknowledged steps pending for a later flush", async () => {
    const send = vi
      .fn<(message: RecordStepMessage) => Promise<unknown>>()
      .mockRejectedValueOnce(new Error("offline"))
      .mockRejectedValueOnce(new Error("still offline"))
      .mockImplementation(async (message) => ({ ok: true, sequence: message.sequence }));
    const delivery = new RecordStepDelivery("rec-retry", send, "document-1");
    delivery.enqueue({ op: "click", target: { tag: "button", name: "Save" } });
    await expect(delivery.flush()).resolves.toBe(false);
    await expect(delivery.flush()).resolves.toBe(true);
    expect(send).toHaveBeenCalledTimes(3);
  });
 });
@@ -1,9 +1,9 @@
 import {
  type CaptureTargetDescriptor,
  describeEventTarget,
  describeTarget,
  resolveClickableElement,
  resolveHoverElement,
  type TargetDescriptor,
 } from "@/lib/describe-target";
 import {
  evaluateHoverTrigger,
@@ -12,8 +12,22 @@ import {
  hasDirectHoverInteractiveSignal,
  hasStrongHoverExpansionSignal,
 } from "@/lib/hover-trigger-policy";
-import type { RecordStepPayload } from "@/lib/record-bridge";
+import {
-import { shouldRecordPress } from "@/lib/recording/draft-policy";
+  isRecordCancelMessage,
  isRecordStartMessage,
  isRecordStopMessage,
  RECORD_CANCEL,
  RECORD_START,
  RECORD_STEP,
  RECORD_STOP,
  type RecordCancelMessage,
  type RecordStartAck,
  type RecordStartMessage,
  type RecordStepPayload,
  type RecordStopAck,
  type RecordStopMessage,
 } from "@/lib/record-bridge";
 import { shouldRecordPress } from "@/lib/trace-reducer";
 import {
  closestHoverSurfaceCandidate,
  collectHoverSurfaceStates,
@@ -23,21 +37,42 @@ import {
  isLikelyHoverSurfaceOwner,
 } from "./record-hover-surface";
 const pendingStepSends = new Map<string, Set<Promise<boolean>>>();
 const failedStepDeliveries = new Set<string>();
 const knownRecordRequests = new Set<string>();
 function sendRecordStep(requestId: string, step: RecordStepPayload): void {
  const payload = { type: RECORD_STEP, requestId, step };
  const pending = Promise.resolve(chrome.runtime.sendMessage(payload)).then(
    () => true,
    () => {
      failedStepDeliveries.add(requestId);
      return false;
    },
  );
  const sends = pendingStepSends.get(requestId) ?? new Set<Promise<boolean>>();
  sends.add(pending);
  pendingStepSends.set(requestId, sends);
  void pending.then(() => {
    sends.delete(pending);
    if (sends.size === 0) pendingStepSends.delete(requestId);
  });
 }
 export interface RecordCaptureController {
  dispose(): void;
 }
 interface FillSession {
  element: FillableElement;
-  target: CaptureTargetDescriptor;
+  target: TargetDescriptor;
  baselineValue: string;
  lastValue: string;
  pendingCommit?: "enter" | "suggestion" | "blur";
 }
 interface HoverCandidate {
  element: Element;
-  target: CaptureTargetDescriptor;
+  target: TargetDescriptor;
  recordedAt: number;
  score: number;
  eligible: boolean;
@@ -122,24 +157,6 @@ function nearbyFillableFromSearchChrome(target: Element): FillableElement | null
  return null;
 }
 function captureGeometry(el: Element): RecordStepPayload["geometry"] {
  const rect = el.getBoundingClientRect();
  return {
    rect: { x: rect.x, y: rect.y, w: rect.width, h: rect.height },
    tag: el.tagName.toLowerCase(),
  };
 }
 function geometryForEventTarget(
  target: EventTarget | null,
 ): RecordStepPayload["geometry"] | undefined {
  if (!(target instanceof Element)) return undefined;
  const clickable = target.closest(
    'a,button,input,select,textarea,[role="button"],[role="link"],[role="menuitem"],[contenteditable="true"]',
  );
  return captureGeometry(clickable ?? target);
 }
 function fillableValue(el: FillableElement): string {
  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
    return el.value;
@@ -215,10 +232,7 @@ function collectHoverTriggerLabelText(root: Element): string {
  return normalizeLabelText(text);
 }
-function compactHoverTargetName(
+function compactHoverTargetName(el: Element, desc: TargetDescriptor): TargetDescriptor {
  el: Element,
  desc: CaptureTargetDescriptor,
 ): CaptureTargetDescriptor {
  if (!desc.name) return desc;
  const fullText = normalizeLabelText(el.textContent ?? "");
  const compactName = collectHoverTriggerLabelText(el);
@@ -236,7 +250,7 @@ function compactHoverTargetName(
  return desc;
 }
-function isWeakHoverTarget(target: CaptureTargetDescriptor): boolean {
+function isWeakHoverTarget(target: TargetDescriptor): boolean {
  return !target.role && !target.name && target.tag === "div";
 }
@@ -247,9 +261,9 @@ function looksLikeAvatarElement(el: Element): boolean {
 function normalizeHoverTarget(
  el: Element,
-  desc: CaptureTargetDescriptor,
+  desc: TargetDescriptor,
  decision: HoverTriggerDecision,
-): CaptureTargetDescriptor {
+): TargetDescriptor {
  if (desc.role === "img" && !desc.name && looksLikeAvatarElement(el)) {
    return { ...desc, name: "image" };
  }
@@ -263,7 +277,7 @@ function normalizeHoverTarget(
  return desc;
 }
-function hoverTriggerSignals(el: Element, desc: CaptureTargetDescriptor) {
+function hoverTriggerSignals(el: Element, desc: TargetDescriptor) {
  if (!(el instanceof HTMLElement)) return null;
  const style = hoverTriggerStyle(el);
  return {
@@ -359,7 +373,6 @@ function scheduleInputCompletionCommit(
 export function startRecordCapture(
  _requestId: string,
  sendStep: (step: RecordStepPayload) => void,
  options: { captureNavigation?: boolean } = {},
 ): RecordCaptureController {
  const emitStep = (step: RecordStepPayload) => {
    sendStep({ page_url: location.href, ...step });
@@ -398,17 +411,14 @@ export function startRecordCapture(
    emitStep({
      op: "fill",
      target: session.target,
      geometry: captureGeometry(session.element),
      value,
      commit: session.pendingCommit ?? "blur",
      ...(isPassword ? { redacted: true } : {}),
    });
  };
-  const commitFillSession = (commit: "enter" | "suggestion" | "blur" = "blur") => {
+  const commitFillSession = () => {
    if (!fillSession || composing) return;
    const session = fillSession;
    session.pendingCommit = commit;
    fillSession = null;
    emitFill(session);
    committedValues.set(session.element, session.lastValue);
@@ -614,7 +624,6 @@ export function startRecordCapture(
    emitStep({
      op: "hover",
      target: hover.target,
      geometry: captureGeometry(hover.element),
    });
    emittedHoverElements.add(hover.element);
  };
@@ -669,7 +678,6 @@ export function startRecordCapture(
    emitStep({
      op: "click",
      target,
      geometry: geometryForEventTarget(eventTarget(event)),
      expects_navigation: true,
    });
  };
@@ -771,7 +779,7 @@ export function startRecordCapture(
      scheduleInputCompletionCommit(
        sessionElement,
        syncFillSessionValue,
-        () => commitFillSession("suggestion"),
+        commitFillSession,
        (el) => fillSession?.element === el,
      );
      return;
@@ -831,7 +839,6 @@ export function startRecordCapture(
      emitStep({
        op: "select",
        target: desc,
        geometry: captureGeometry(target),
        values,
        labels,
        expects_navigation: true,
@@ -872,7 +879,7 @@ export function startRecordCapture(
      };
    }
    if (fillable) {
-      commitFillSession(event.key === "Enter" ? "enter" : "blur");
+      commitFillSession();
    }
    const desc = describeEventTarget(target);
    if (!desc && !event.key) return;
@@ -880,7 +887,7 @@ export function startRecordCapture(
    emitStep({
      op: "press",
      key: event.key,
-      ...(desc ? { target: desc, geometry: geometryForEventTarget(target) } : {}),
+      ...(desc ? { target: desc } : {}),
      ...(modifiers.length ? { modifiers } : {}),
      expects_navigation: event.key === "Enter",
    });
@@ -896,33 +903,23 @@ export function startRecordCapture(
  document.addEventListener("change", onChange, true);
  document.addEventListener("keydown", onKeyDown, true);
-  const captureNavigation = options.captureNavigation ?? true;
+  const urlObserver = new MutationObserver(() => emitNavigateIfChanged());
-  const urlObserver = captureNavigation
+  urlObserver.observe(document, { subtree: true, childList: true });
    ? new MutationObserver(() => emitNavigateIfChanged())
    : null;
  urlObserver?.observe(document, { subtree: true, childList: true });
  const onUrlEvent = () => emitNavigateIfChanged();
-  // Wrap: passing commitFillSession directly would forward the DOM event as
+  window.addEventListener("hashchange", onUrlEvent);
-  // the `commit` argument and stamp it onto the recorded fill step.
+  window.addEventListener("popstate", onUrlEvent);
-  const onPageHide = () => commitFillSession();
+  window.addEventListener("pagehide", commitFillSession);
  if (captureNavigation) {
    window.addEventListener("hashchange", onUrlEvent);
    window.addEventListener("popstate", onUrlEvent);
  }
  window.addEventListener("pagehide", onPageHide);
  const originalPushState = history.pushState;
  const originalReplaceState = history.replaceState;
-  if (captureNavigation) {
+  history.pushState = function (...args: Parameters<History["pushState"]>) {
-    history.pushState = function (...args: Parameters<History["pushState"]>) {
+    originalPushState.apply(this, args);
-      originalPushState.apply(this, args);
+    emitNavigateIfChanged(navigationActionPending ? true : undefined);
-      emitNavigateIfChanged(navigationActionPending ? true : undefined);
+  };
-    };
+  history.replaceState = function (...args: Parameters<History["replaceState"]>) {
-    history.replaceState = function (...args: Parameters<History["replaceState"]>) {
+    originalReplaceState.apply(this, args);
-      originalReplaceState.apply(this, args);
+    emitNavigateIfChanged(navigationActionPending ? true : undefined);
-      emitNavigateIfChanged(navigationActionPending ? true : undefined);
+  };
    };
  }
  return {
    dispose() {
@@ -936,16 +933,93 @@ export function startRecordCapture(
      document.removeEventListener("compositionend", onCompositionEnd, true);
      document.removeEventListener("change", onChange, true);
      document.removeEventListener("keydown", onKeyDown, true);
-      urlObserver?.disconnect();
+      urlObserver.disconnect();
-      if (captureNavigation) {
+      window.removeEventListener("hashchange", onUrlEvent);
-        window.removeEventListener("hashchange", onUrlEvent);
+      window.removeEventListener("popstate", onUrlEvent);
-        window.removeEventListener("popstate", onUrlEvent);
+      window.removeEventListener("pagehide", commitFillSession);
-      }
+      history.pushState = originalPushState;
-      window.removeEventListener("pagehide", onPageHide);
+      history.replaceState = originalReplaceState;
      if (captureNavigation) {
        history.pushState = originalPushState;
        history.replaceState = originalReplaceState;
      }
    },
  };
 }
 export type RecordContentMessage = RecordStartMessage | RecordStopMessage | RecordCancelMessage;
 export function isRecordContentMessage(msg: unknown): msg is RecordContentMessage {
  return isRecordStartMessage(msg) || isRecordStopMessage(msg) || isRecordCancelMessage(msg);
 }
 export function handleRecordContentMessage(
  message: RecordContentMessage,
  state: {
    activeRequestId: string | null;
    capture: RecordCaptureController | null;
    setActiveRequestId(id: string | null): void;
    setCapture(capture: RecordCaptureController | null): void;
    onStart(requestId: string, startedAtMs?: number): void;
    onStop(): void;
  },
  sendResponse?: (response: RecordStartAck | RecordStopAck) => void,
 ): boolean {
  if (isRecordStartMessage(message)) {
    if (!knownRecordRequests.has(message.requestId)) {
      knownRecordRequests.add(message.requestId);
      failedStepDeliveries.delete(message.requestId);
    }
    state.capture?.dispose();
    state.setCapture(
      startRecordCapture(message.requestId, (step) => {
        sendRecordStep(message.requestId, step);
      }),
    );
    state.setActiveRequestId(message.requestId);
    state.onStart(message.requestId, message.startedAtMs);
    sendResponse?.({ ok: true });
    return sendResponse !== undefined;
  }
  if (isRecordStopMessage(message) || isRecordCancelMessage(message)) {
    // Require an active recording that matches this requestId — otherwise a
    // stray STOP/CANCEL (e.g. after teardown) would still run finishStop and
    // clear overlay state even though nothing was capturing.
    if (!state.activeRequestId || state.activeRequestId !== message.requestId) {
      return false;
    }
    state.capture?.dispose();
    state.setCapture(null);
    const finishStop = () => {
      state.onStop();
      state.setActiveRequestId(null);
    };
    if (isRecordStopMessage(message) && sendResponse) {
      const pending = [...(pendingStepSends.get(message.requestId) ?? [])];
      void Promise.all(pending).then((delivered) => {
        finishStop();
        const succeeded = delivered.every(Boolean) && !failedStepDeliveries.has(message.requestId);
        if (succeeded) {
          failedStepDeliveries.delete(message.requestId);
          knownRecordRequests.delete(message.requestId);
        }
        sendResponse(
          succeeded
            ? { ok: true }
            : {
                ok: false,
                error: "failed to deliver one or more recorded steps",
              },
        );
      });
      return true;
    }
    if (isRecordCancelMessage(message)) {
      failedStepDeliveries.delete(message.requestId);
      knownRecordRequests.delete(message.requestId);
    }
    finishStop();
    return false;
  }
  return false;
 }
 export { RECORD_CANCEL, RECORD_START, RECORD_STEP, RECORD_STOP };
@@ -1,66 +0,0 @@
 import { createRandomUuid } from "@/lib/random-uuid";
 import {
  isAcceptedRecordStepAck,
  RECORD_STEP,
  type RecordStepMessage,
  type RecordStepPayload,
 } from "@/lib/record-bridge";
 export type SendRecordStepMessage = (message: RecordStepMessage) => Promise<unknown>;
 export class RecordStepDelivery {
  readonly #requestId: string;
  readonly #producerId: string;
  readonly #send: SendRecordStepMessage;
  readonly #pending = new Map<number, RecordStepPayload>();
  #nextSequence = 1;
  #tail = Promise.resolve();
  constructor(
    requestId: string,
    send: SendRecordStepMessage = (message) => chrome.runtime.sendMessage(message),
    producerId: string = createRandomUuid(),
  ) {
    this.#requestId = requestId;
    this.#producerId = producerId;
    this.#send = send;
  }
  enqueue(step: RecordStepPayload): void {
    const sequence = this.#nextSequence;
    this.#nextSequence += 1;
    this.#pending.set(sequence, step);
    void this.#schedule();
  }
  async flush(): Promise<boolean> {
    await this.#tail;
    await this.#schedule();
    return this.#pending.size === 0;
  }
  #schedule(): Promise<void> {
    const drain = () => this.#drain();
    this.#tail = this.#tail.then(drain, drain);
    return this.#tail;
  }
  async #drain(): Promise<void> {
    for (const [sequence, step] of this.#pending) {
      const message: RecordStepMessage = {
        type: RECORD_STEP,
        requestId: this.#requestId,
        producerId: this.#producerId,
        sequence,
        step,
      };
      try {
        const response = await this.#send(message);
        if (!isAcceptedRecordStepAck(response, sequence)) return;
        this.#pending.delete(sequence);
      } catch {
        return;
      }
    }
  }
 }
@@ -1,210 +0,0 @@
 import { createRandomUuid } from "@/lib/random-uuid";
 import {
  markRecordingDocument,
  type RecordingDocumentMarker,
  waitForDocumentElement,
 } from "@/lib/recording/document-marker";
 import {
  isRecordFrameStartMessage,
  RECORD_FRAME_PORT,
  RECORD_FRAME_QUERY,
  RECORD_FRAME_START,
  type RecordFramePortMessage,
  type RecordFrameQueryResponse,
  type RecordFrameStartMessage,
 } from "@/lib/recording/frame-bridge";
 import { type RecordCaptureController, startRecordCapture } from "../record-capture";
 import { RecordStepDelivery } from "../record-step-delivery";
 interface ActiveFrameRecording {
  requestId: string;
  producerId: string;
  port: chrome.runtime.Port;
  delivery: RecordStepDelivery;
  capture: RecordCaptureController;
  marker: RecordingDocumentMarker;
 }
 const RECORD_FRAME_REGISTER_TIMEOUT_MS = 5_000;
 export class RecordFrameAgent {
  #active: ActiveFrameRecording | null = null;
  #startPromise: Promise<{ ok: true } | { ok: false; error: string }> | null = null;
  #disposed = false;
  async start(
    message: RecordFrameStartMessage,
  ): Promise<{ ok: true } | { ok: false; error: string }> {
    if (this.#active?.requestId === message.requestId) return { ok: true };
    if (this.#disposed) return { ok: false, error: "recording document is disposed" };
    if (this.#startPromise) {
      await this.#startPromise;
      return this.start(message);
    }
    if (this.#active) this.cancel(this.#active.requestId);
    const starting = this.#start(message);
    this.#startPromise = starting;
    try {
      return await starting;
    } finally {
      if (this.#startPromise === starting) this.#startPromise = null;
    }
  }
  cancel(requestId: string): void {
    const active = this.#active;
    if (!active || active.requestId !== requestId) return;
    active.capture.dispose();
    active.marker.restore();
    active.port.disconnect();
    this.#active = null;
  }
  dispose(): void {
    this.#disposed = true;
    if (this.#active) this.cancel(this.#active.requestId);
  }
  async #start(
    message: RecordFrameStartMessage,
  ): Promise<{ ok: true } | { ok: false; error: string }> {
    const producerId = createRandomUuid();
    const root = await waitForDocumentElement();
    if (this.#disposed) return { ok: false, error: "recording document is disposed" };
    const marker = markRecordingDocument(producerId, root);
    const port = chrome.runtime.connect({ name: RECORD_FRAME_PORT });
    try {
      await registerPort(port, message.requestId, producerId);
    } catch {
      marker.restore();
      port.disconnect();
      return { ok: false, error: "failed to register recording document" };
    }
    if (this.#disposed) {
      marker.restore();
      port.disconnect();
      return { ok: false, error: "recording document is disposed" };
    }
    const delivery = new RecordStepDelivery(message.requestId, undefined, producerId);
    const capture = startRecordCapture(
      message.requestId,
      (step) => {
        marker.ensure();
        delivery.enqueue(step);
      },
      { captureNavigation: window.top === window },
    );
    const active: ActiveFrameRecording = {
      requestId: message.requestId,
      producerId,
      port,
      delivery,
      capture,
      marker,
    };
    this.#active = active;
    port.onMessage.addListener((raw: unknown) => {
      const command = raw as Partial<RecordFramePortMessage>;
      if (command.type === "stop" && command.requestId === active.requestId) {
        void this.#stop(active, command.commandId);
      } else if (command.type === "cancel" && command.requestId === active.requestId) {
        this.cancel(active.requestId);
      }
    });
    port.onDisconnect.addListener(() => {
      if (this.#active !== active) return;
      active.capture.dispose();
      active.marker.restore();
      this.#active = null;
    });
    return { ok: true };
  }
  async #stop(active: ActiveFrameRecording, commandId: string | undefined): Promise<void> {
    if (!commandId || this.#active !== active) return;
    active.capture.dispose();
    const succeeded = await active.delivery.flush();
    try {
      active.port.postMessage({
        type: "stopped",
        requestId: active.requestId,
        commandId,
        ok: succeeded,
        ...(succeeded ? {} : { error: "failed to deliver one or more recorded steps" }),
      } satisfies RecordFramePortMessage);
    } catch {
      return;
    }
    if (!succeeded || this.#active !== active) return;
    active.marker.restore();
    this.#active = null;
    active.port.disconnect();
  }
 }
 function registerPort(
  port: chrome.runtime.Port,
  requestId: string,
  producerId: string,
 ): Promise<void> {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      cleanup();
      reject(new Error("recording document registration timed out"));
    }, RECORD_FRAME_REGISTER_TIMEOUT_MS);
    const cleanup = () => {
      clearTimeout(timer);
      port.onMessage.removeListener(onMessage);
      port.onDisconnect.removeListener(onDisconnect);
    };
    const onMessage = (raw: unknown) => {
      const message = raw as Partial<RecordFramePortMessage>;
      if (
        message.type !== "ready_ack" ||
        message.requestId !== requestId ||
        message.producerId !== producerId
      ) {
        return;
      }
      cleanup();
      resolve();
    };
    const onDisconnect = () => {
      cleanup();
      reject(new Error("recording document port disconnected"));
    };
    port.onMessage.addListener(onMessage);
    port.onDisconnect.addListener(onDisconnect);
    port.postMessage({ type: "ready", requestId, producerId } satisfies RecordFramePortMessage);
  });
 }
 export function attachRecordFrameAgent(): () => void {
  const agent = new RecordFrameAgent();
  const onMessage = (
    message: unknown,
    _sender: chrome.runtime.MessageSender,
    sendResponse: (response: { ok: true } | { ok: false; error: string }) => void,
  ) => {
    if (!isRecordFrameStartMessage(message)) return false;
    void agent.start(message).then(sendResponse);
    return true;
  };
  chrome.runtime.onMessage.addListener(onMessage);
  void chrome.runtime
    .sendMessage({ type: RECORD_FRAME_QUERY })
    .then((response: RecordFrameQueryResponse | undefined) => {
      if (!response?.active || !response.requestId || response.startedAtMs === undefined) return;
      return agent.start({
        type: RECORD_FRAME_START,
        requestId: response.requestId,
        startedAtMs: response.startedAtMs,
      });
    })
    .catch(() => {});
  return () => {
    chrome.runtime.onMessage.removeListener(onMessage);
    agent.dispose();
  };
 }
@@ -21,11 +21,10 @@ import {
  type OverlayMode,
 } from "@/lib/overlay-bridge";
 import { POPUP_PORT_NAME, type PopupInbound, type PopupOutbound } from "@/lib/popup-bridge";
 import { recordFrameCoordinator } from "@/lib/recording/frame-coordinator";
 import { attachSessionsLiveFlag } from "@/lib/sessions-live-flag";
 import { createDisconnectCleanup } from "@/session-manager/disconnect-cleanup";
 import { attachSessionEventHandler } from "@/session-manager/event-handler";
-import { isAgentControlledTab, SessionManager } from "@/session-manager/manager";
+import { SessionManager } from "@/session-manager/manager";
 import {
  attachBorrowNotificationButtonHandler,
  attachBorrowNotificationClickHandler,
@@ -39,10 +38,7 @@ import {
  attachRecordFinishListener,
  attachRecordQueryListener,
  attachRecordStepListener,
  type RecordRuntimeDeps,
 } from "@/tools/record";
 import { chromeTabsApi } from "@/tools/shared";
 import { chromeTabMutationApi } from "@/tools/tabs";
 import { detectBrowserMeta } from "@/transport/handshake";
 import type { Transport } from "@/transport/transport";
 import { WSTransport } from "@/transport/ws-transport";
@@ -51,12 +47,7 @@ export default defineBackground(() => {
  const controller = new ConnectionController();
  const transport = new WSTransport({ url: __BSK_DAEMON_WS_URL__ });
  const sessions = new SessionManager();
-  const cdp = new ChromiumCdp(undefined, {
+  const cdp = new ChromiumCdp();
    shouldAutoAcceptDialog: async (tabId) => {
      const tab = await chrome.tabs.get(tabId);
      return sessions.findByWindowId(tab.windowId) !== null;
    },
  });
  const sessionsLive = attachSessionsLiveFlag({ manager: sessions });
  let overlayGeneration = 0;
  const controlModes = new Map<string, OverlayMode>();
@@ -87,24 +78,6 @@ export default defineBackground(() => {
    };
  }
  /**
   * Authoritative overlay state for a specific tab. Agent Window tabs are
   * free by default; only tabs explicitly claimed through session startup,
   * `tab_create`, or `tab_borrow` receive the control overlay.
   */
  function overlayStateForTab(tabId?: number, windowId?: number): OverlayAgentStateMessage {
    if (typeof tabId === "number" && typeof windowId === "number") {
      const ctx = sessions.findByWindowId(windowId);
      if (ctx && isAgentControlledTab(ctx, tabId)) return overlayStateForWindow(windowId);
    }
    return {
      type: OVERLAY_AGENT_STATE,
      sessionId: null,
      mode: "hidden",
      generation: overlayGeneration,
    };
  }
  async function pushOverlayStateToTab(
    tabId: number,
    state: OverlayAgentStateMessage,
@@ -116,18 +89,13 @@ export default defineBackground(() => {
    }
  }
  async function pushOverlayStateForTab(tabId: number, windowId?: number): Promise<void> {
    const state = overlayStateForTab(tabId, windowId);
    await pushOverlayStateToTab(tabId, state);
  }
  async function pushOverlayStateForWindow(windowId: number): Promise<void> {
    const state = overlayStateForWindow(windowId);
    const tabs = await chrome.tabs.query({ windowId });
    await Promise.all(
-      tabs.map((tab) => {
+      tabs.map((tab) =>
-        if (typeof tab.id !== "number") return Promise.resolve();
+        typeof tab.id === "number" ? pushOverlayStateToTab(tab.id, state) : Promise.resolve(),
-        return pushOverlayStateForTab(tab.id, windowId);
+      ),
      }),
    );
  }
@@ -166,66 +134,23 @@ export default defineBackground(() => {
    if (typeof tab.windowId !== "number") return;
    pushOverlayStateForAgentWindow(tab.windowId);
  });
  // Newly observed tabs are free unless the agent's own creation path has
  // already claimed their concrete id. This listener only renders that
  // state; it never infers or mutates ownership from event ordering.
  chrome.tabs.onCreated.addListener((tab) => {
    if (typeof tab.windowId !== "number" || typeof tab.id !== "number") return;
    if (!sessions.findByWindowId(tab.windowId)) return;
    void pushOverlayStateForTab(tab.id, tab.windowId);
  });
  chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
    sessions.forgetClosedTab(tabId, { isWindowClosing: removeInfo.isWindowClosing });
  });
  // Re-sync the storage.session flag on SW startup so a previous SW's
  // stale `true` does not keep waking us on every page load until the
  // first mutation (review M4/M5 round 3 m-R3-1).
  void sessionsLive.refresh();
  const cleanupAfterDisconnect = createDisconnectCleanup({
    manager: sessions,
-    // Same contract as the dispatcher's `tool.session_stop`: without these
+    sessionStopDeps: { cdp },
    // deps the agent-tab cleanup and the window-release path are dead code.
    sessionStopDeps: {
      cdp,
      tabManagement: { tabs: chromeTabMutationApi },
      tabsQuery: chromeTabsApi,
    },
    onSessionsChanged: () => {
      void sessionsLive.syncFromManager();
    },
  });
  const recordDeps = {
    tabsApi: chrome.tabs,
    cdp,
    frameCoordinator: recordFrameCoordinator,
    sendToTab: (tabId: number, msg: Parameters<typeof chrome.tabs.sendMessage>[1]) =>
      chrome.tabs.sendMessage(tabId, msg),
    bypassOverlay: async (tabId: number, enabled: boolean) => {
      try {
        await chrome.tabs.sendMessage(tabId, {
          type: OVERLAY_AUTOMATION_BYPASS,
          enabled,
        });
      } catch {
        // Content script may be unavailable on restricted pages.
      }
    },
  } satisfies RecordRuntimeDeps;
  recordFrameCoordinator.attach();
  attachRecordStepListener(recordDeps);
  attachRecordFinishListener(recordDeps);
  attachRecordQueryListener(recordDeps);
  const dispatcher = new ToolDispatcher({
    transport,
    sessions,
    cdp,
    recording: recordDeps,
    onSessionsChanged: onOverlaySessionStateChanged,
    onBrowserControlResumed,
    onAgentTabClaimed: (tabId, windowId) => {
      void pushOverlayStateForTab(tabId, windowId);
    },
    approveBorrow: (ctx) =>
      requestBorrowConfirmation(ctx.tabId, {
        ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
@@ -245,6 +170,27 @@ export default defineBackground(() => {
    }),
  });
  dispatcher.start();
  const recordDeps = {
    tabsApi: chrome.tabs,
    sendToTab: (tabId: number, msg: Parameters<typeof chrome.tabs.sendMessage>[1]) =>
      chrome.tabs.sendMessage(tabId, msg),
    bypassOverlay: async (tabId: number, enabled: boolean) => {
      try {
        await chrome.tabs.sendMessage(tabId, {
          type: OVERLAY_AUTOMATION_BYPASS,
          enabled,
        });
      } catch {
        // Content script may be unavailable on restricted pages.
      }
    },
  };
  // Message listeners stay up (cheap; fire only for record message types).
  // Tab / webNavigation observation attaches lazily while a recording is
  // active — see ensureBrowserObservationListeners in tools/record.ts.
  attachRecordStepListener();
  attachRecordFinishListener(recordDeps);
  attachRecordQueryListener(recordDeps);
  if (typeof chrome.notifications?.onClicked?.addListener === "function") {
    attachBorrowNotificationClickHandler({
      onClicked: chrome.notifications.onClicked,
@@ -359,11 +305,7 @@ export default defineBackground(() => {
    }
    if (msg.kind === OVERLAY_MSG_READY) {
-      // Resolve from explicit tab ownership before sending so free tabs never
+      sendResponse(overlayStateForWindow(sender.tab?.windowId));
      // flash the control mask.
      if (typeof sender.tab?.id === "number") {
        void pushOverlayStateForTab(sender.tab.id, sender.tab.windowId);
      }
      return false;
    }
@@ -11,6 +11,11 @@ import { createHelpRequestData } from "@/content/help-request";
 import overlayCss from "@/content/overlay.css?inline";
 import { OverlayController, shouldShowAgentControlOverlay } from "@/content/overlay-controller";
 import { RecordOverlay } from "@/content/RecordOverlay";
 import {
  handleRecordContentMessage,
  isRecordContentMessage,
  type RecordCaptureController,
 } from "@/content/record-capture";
 import {
  type CaptureSuppressAck,
  type CaptureSuppressMessage,
@@ -40,17 +45,11 @@ import {
 } from "@/lib/overlay-bridge";
 import { sendInterrupt } from "@/lib/overlay-interrupt-client";
 import {
  isRecordCancelMessage,
  isRecordStartMessage,
  isRecordStopMessage,
  RECORD_FINISH,
  RECORD_QUERY,
  type RecordCancelMessage,
  type RecordQueryResponse,
  type RecordStartAck,
  type RecordStartMessage,
  type RecordStopAck,
  type RecordStopMessage,
 } from "@/lib/record-bridge";
 import type {
  BorrowCancelMessage,
@@ -70,6 +69,7 @@ export default defineContentScript({
    if (window.top !== window) return;
    const overlays = new OverlayController();
    let recordCapture: RecordCaptureController | null = null;
    let activeRecordRequestId: string | null = null;
    let reactRoot: ReactDOM.Root | null = null;
    let overlayHost: HTMLElement | null = null;
@@ -228,6 +228,8 @@ export default defineContentScript({
      if (previousHelp) {
        void sendHelpFinish(previousHelp.id, "cancelled");
      }
      recordCapture?.dispose();
      recordCapture = null;
      activeRecordRequestId = null;
      renderAll();
    }
@@ -257,9 +259,6 @@ export default defineContentScript({
        | HelpRequestMessage
        | HelpCancelMessage
        | CaptureSuppressMessage
        | RecordStartMessage
        | RecordStopMessage
        | RecordCancelMessage
        | OverlayAgentOverlayResetMessage
        | OverlayAgentStateMessage
        | OverlayAutomationBypassMessage,
@@ -270,32 +269,41 @@ export default defineContentScript({
        return captureSuppress.handleMessage(message, sendResponse);
      }
-      if (isRecordStartMessage(message)) {
+      if (isRecordContentMessage(message)) {
-        activeRecordRequestId = message.requestId;
+        const needsAsync = handleRecordContentMessage(
-        overlays.setAgentRecordRequest({
+          message,
-          id: message.requestId,
+          {
-          ...(typeof message.startedAtMs === "number" ? { startedAtMs: message.startedAtMs } : {}),
+            activeRequestId: activeRecordRequestId,
-          onFinish: () => {
+            capture: recordCapture,
-            void chrome.runtime.sendMessage({
+            setActiveRequestId: (id) => {
-              type: RECORD_FINISH,
+              activeRecordRequestId = id;
-              requestId: message.requestId,
+            },
-            });
+            setCapture: (capture) => {
              recordCapture = capture;
            },
            onStart: (requestId, startedAtMs) => {
              overlays.setAgentRecordRequest({
                id: requestId,
                ...(typeof startedAtMs === "number" ? { startedAtMs } : {}),
                onFinish: () => {
                  void chrome.runtime.sendMessage({
                    type: RECORD_FINISH,
                    requestId,
                  });
                },
              });
              renderAll();
            },
            onStop: () => {
              overlays.clearAgentRecordRequest(activeRecordRequestId ?? undefined);
              renderAll();
            },
          },
-        });
+          sendResponse as unknown as
-        renderAll();
+            | ((response: RecordStartAck | RecordStopAck) => void)
-        (sendResponse as unknown as (response: RecordStartAck) => void)({ ok: true });
+            | undefined,
-        return false;
+        );
-      }
+        return needsAsync;
      if (isRecordStopMessage(message) || isRecordCancelMessage(message)) {
        if (activeRecordRequestId !== message.requestId) return false;
        overlays.clearAgentRecordRequest(message.requestId);
        activeRecordRequestId = null;
        renderAll();
        if (isRecordStopMessage(message)) {
          (sendResponse as unknown as (response: RecordStopAck) => void)({ ok: true });
        }
        return false;
      }
      if (
@@ -518,6 +526,9 @@ export default defineContentScript({
      chrome.runtime.onMessage.removeListener(onMessage);
      chrome.storage.onChanged.removeListener(onStorageChange);
      window.removeEventListener("pageshow", onPageShow);
      // Restore history hooks / remove capture listeners before the CS unloads.
      recordCapture?.dispose();
      recordCapture = null;
      activeRecordRequestId = null;
    });
  },
@@ -122,8 +122,8 @@ describe("App", () => {
    expect(screen.queryByText(/^扩展 v/)).toBeNull();
    expect(screen.queryByText(/^daemon v/)).toBeNull();
-    expect(screen.getByTitle("扩展版本").textContent).toBe(`Ext ${EXTENSION_VERSION}`);
+    expect(screen.getByTitle("扩展版本").textContent).toBe(EXTENSION_VERSION);
-    expect(screen.getByTitle("bsk 版本").textContent).toBe(`CLI ${mockDaemonVersion}`);
+    expect(screen.getByTitle("bsk 版本").textContent).toBe(mockDaemonVersion);
    expect(screen.getByText("03c3e47f")).toBeTruthy();
    const copyButton = screen.getByRole("button", { name: "复制实例 ID" });
@@ -200,9 +200,6 @@ describe("App", () => {
    expect(copied).toContain("--browser 03c3e47f");
    expect(copied).toContain('--purpose "发布 wiki 文档"');
    expect(copied).not.toMatch(/bsk record start[^\n]*--url/);
    expect(copied).toContain("./trace");
    expect(copied).toContain("trace.json");
    expect(copied).toContain("states/");
    // Button label stays static; a transient toast confirms the copy.
    expect(copyButton.textContent).toContain("复制录制指令");
    await waitFor(() => expect(screen.getByRole("status").textContent).toContain("已复制"));
@@ -247,41 +244,6 @@ describe("App", () => {
    expect(copyButton.getAttribute("disabled")).not.toBeNull();
    expect(screen.getByText("连接后可用")).toBeTruthy();
  });
  it("treats protocol drift as still connected and prompts an upgrade", async () => {
    mockUseConnectionState.mockReturnValue({
      snapshot: {
        ...baseSnapshot,
        state: "version_skew",
        instanceId: "03c3e47f",
        handshake: {
          server: "bh",
          version: mockDaemonVersion,
          protocol_version: "1.0",
        },
      },
      statusState: "version_skew",
      setLabel,
      setConnectionEnabled,
    });
    render(<App />);
    expect(screen.getByText("已连接")).toBeTruthy();
    expect(screen.getByText("可升级")).toBeTruthy();
    expect(screen.queryByText("协议不一致")).toBeNull();
    expect(screen.queryByText("Action needed")).toBeNull();
    expect(screen.queryByText("兼容")).toBeNull();
    const warning = screen.getByText(/协议版本不同，请及时升级/);
    expect(warning.textContent).toContain("CLI 协议");
    expect(warning.textContent).toContain("扩展协议");
    openRecordView();
    const copyButton = screen.getByRole("button", { name: "复制录制指令" });
    expect(copyButton.getAttribute("disabled")).toBeNull();
    fireEvent.click(copyButton);
    expect(navigator.clipboard.writeText).toHaveBeenCalledTimes(1);
  });
 });
 describe("control hints toggle", () => {
@@ -79,7 +79,6 @@ export function App() {
  }, [copiedTick]);
  const isSkewed = statusState === "version_skew";
  const connectionLive = statusState === "connected" || isSkewed;
  const daemonVersion = snapshot.handshake?.version ?? "—";
  const daemonProtocol = snapshot.handshake?.protocol_version ?? "—";
  const extensionVersion = snapshot.extensionVersion || "—";
@@ -91,7 +90,7 @@ export function App() {
    setCopiedInstanceId(true);
  };
-  const recordReady = connectionLive && Boolean(snapshot.instanceId);
+  const recordReady = statusState === "connected" && Boolean(snapshot.instanceId);
  const recordPurpose = purposeDraft.trim();
  const recordStartUrl = startUrlDraft.trim();
  const recordCommand = snapshot.instanceId
@@ -207,12 +206,12 @@ export function App() {
            </div>
            {isSkewed && (
              <p
-                className="mt-2 text-xs leading-snug text-muted-foreground"
+                className="mt-2 text-xs leading-snug text-amber-600 dark:text-amber-400"
                data-slot="popup-version-skew-warning"
              >
                {t("popup.versionSkewWarning", {
                  extensionProtocol: PROTOCOL_VERSION,
-                  cliProtocol: daemonProtocol,
+                  daemonProtocol,
                })}
              </p>
            )}
@@ -267,9 +266,9 @@ export function App() {
            data-slot="popup-meta"
          >
            <div className="flex shrink-0 items-center gap-1">
-              <span title={t("popup.daemonVersionHint")}>CLI {daemonVersion}</span>
+              <span title={t("popup.extensionVersionHint")}>{extensionVersion}</span>
              <span aria-hidden>/</span>
-              <span title={t("popup.extensionVersionHint")}>Ext {extensionVersion}</span>
+              <span title={t("popup.daemonVersionHint")}>{daemonVersion}</span>
            </div>
            <div className="flex min-w-0 items-center justify-end gap-1">
              <span className="shrink-0">{t("popup.instanceTitle")}</span>
@@ -1,14 +0,0 @@
 import { attachRecordFrameAgent } from "@/content/recording/frame-agent";
 export default defineContentScript({
  matches: ["<all_urls>"],
  runAt: "document_start",
  allFrames: true,
  matchAboutBlank: true,
  matchOriginAsFallback: true,
  main(ctx) {
    const dispose = attachRecordFrameAgent();
    ctx.onInvalidated(dispose);
  },
 });
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 import {
  CAPTURE_SUPPRESS,
  type CaptureSuppressMessage,
-  withExtensionOverlayHidden,
+  withOverlaysHiddenForCapture,
 } from "../capture-suppress-bridge";
 function recordingSendToTab(events: string[]) {
@@ -12,12 +12,12 @@ function recordingSendToTab(events: string[]) {
  });
 }
-describe("withExtensionOverlayHidden", () => {
+describe("withOverlaysHiddenForCapture", () => {
  it("sends begin → fn → end and returns fn's result", async () => {
    const events: string[] = [];
    const sendToTab = recordingSendToTab(events);
-    const result = await withExtensionOverlayHidden(
+    const result = await withOverlaysHiddenForCapture(
      7,
      async () => {
        events.push("capture");
@@ -37,7 +37,7 @@ describe("withExtensionOverlayHidden", () => {
    const sendToTab = recordingSendToTab(events);
    await expect(
-      withExtensionOverlayHidden(
+      withOverlaysHiddenForCapture(
        7,
        async () => {
          events.push("capture");
@@ -55,7 +55,7 @@ describe("withExtensionOverlayHidden", () => {
    });
    const fn = vi.fn(async () => "shot");
-    const result = await withExtensionOverlayHidden(7, fn, sendToTab);
+    const result = await withOverlaysHiddenForCapture(7, fn, sendToTab);
    expect(result).toBe("shot");
    expect(fn).toHaveBeenCalledTimes(1);
@@ -69,7 +69,7 @@ describe("withExtensionOverlayHidden", () => {
      return { type: CAPTURE_SUPPRESS, ok: true };
    });
-    const result = await withExtensionOverlayHidden(7, async () => "shot", sendToTab);
+    const result = await withOverlaysHiddenForCapture(7, async () => "shot", sendToTab);
    expect(result).toBe("shot");
    expect(sendToTab).toHaveBeenCalledTimes(2);
@@ -26,20 +26,20 @@ function handshake(
 }
 describe("computeConnectedState (protocol-based compat)", () => {
-  it("returns connected when daemon protocol equals extension protocol", () => {
+  it("returns connected when protocol strings match", () => {
-    expect(computeConnectedState(handshake("1.1", "1.0"), MIN_COMPATIBLE_PROTOCOL)).toEqual({
+    expect(computeConnectedState(handshake("1.0", "1.0"), MIN_COMPATIBLE_PROTOCOL)).toEqual({
      kind: "connected",
    });
  });
  it("returns version_skew when daemon protocol minor is newer", () => {
-    expect(computeConnectedState(handshake("1.2", "1.0"))).toEqual({
+    expect(computeConnectedState(handshake("1.1", "1.0"))).toEqual({
      kind: "version_skew",
    });
  });
  it("returns version_skew when daemon protocol string differs but floor is satisfied", () => {
-    expect(computeConnectedState(handshake("1.1.0", "1.0"))).toEqual({
+    expect(computeConnectedState(handshake("1", "1.0"))).toEqual({
      kind: "version_skew",
    });
  });
@@ -53,7 +53,7 @@ describe("computeConnectedState (protocol-based compat)", () => {
  });
  it("rejects when extension is below daemon min_compatible_protocol", () => {
-    const result = computeConnectedState(handshake("1.1", "1.5"));
+    const result = computeConnectedState(handshake("1.0", "1.5"));
    expect(result.kind).toBe("rejected");
    if (result.kind === "rejected") {
      expect(result.reason).toContain("min_compatible_protocol");
@@ -65,7 +65,7 @@ describe("computeConnectedState (protocol-based compat)", () => {
    const result = computeConnectedState({
      server: "browser-skill-daemon",
      version: "0.1.0",
-      protocol_version: "1.1",
+      protocol_version: "1.0",
      min_compatible_peer: "0.1.0",
    });
    expect(result).toEqual({ kind: "connected" });
@@ -80,7 +80,7 @@ describe("computeConnectedState (protocol-based compat)", () => {
  });
  it("rejects malformed daemon min_compatible_protocol with a daemon-floor reason", () => {
-    const result = computeConnectedState(handshake("1.1", "not-a-protocol"));
+    const result = computeConnectedState(handshake("1.0", "not-a-protocol"));
    expect(result.kind).toBe("rejected");
    if (result.kind === "rejected") {
      expect(result.reason).toContain("daemon min_compatible_protocol");
@@ -242,11 +242,11 @@ describe("ConnectionController connectionEnabled", () => {
    const second = transport.send.mock.calls[1]?.[0] as { id: string };
    expect(second.id).not.toBe(first.id);
-    transport.emitMessage({ id: first.id, result: handshake("1.1", "1.0") });
+    transport.emitMessage({ id: first.id, result: handshake("1.0", "1.0") });
    await Promise.resolve();
    expect(controller.snapshot().state).not.toBe("connected");
-    transport.emitMessage({ id: second.id, result: handshake("1.1", "1.0") });
+    transport.emitMessage({ id: second.id, result: handshake("1.0", "1.0") });
    await vi.waitFor(() => expect(controller.snapshot().state).toBe("connected"));
  });
 });
@@ -1,101 +0,0 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { CdpRunner } from "@/tools/shared";
 import { waitForDocumentSettled } from "../recording/document-settle";
 function quietCdp(): { cdp: CdpRunner; send: ReturnType<typeof vi.fn> } {
  const send = vi.fn(async () => ({
    result: { value: { idleMs: 1_000, readyState: "complete" } },
  }));
  return {
    cdp: { send: send as unknown as CdpRunner["send"] },
    send,
  };
 }
 describe("waitForDocumentSettled", () => {
  afterEach(() => {
    vi.useRealTimers();
  });
  it("waits through the minimum observation floor before accepting a quiet page", async () => {
    vi.useFakeTimers();
    const { cdp, send } = quietCdp();
    const settled = waitForDocumentSettled(cdp, { target: { tabId: 7 } });
    await vi.advanceTimersByTimeAsync(180);
    await expect(settled).resolves.toBe("quiet");
    expect(send).toHaveBeenCalledTimes(3);
  });
  it("cancels before probing a superseded observation", async () => {
    vi.useFakeTimers();
    const { cdp, send } = quietCdp();
    const controller = new AbortController();
    const settled = waitForDocumentSettled(
      cdp,
      { target: { tabId: 7 } },
      {
        signal: controller.signal,
      },
    );
    controller.abort();
    await vi.advanceTimersByTimeAsync(60);
    await expect(settled).resolves.toBe("cancelled");
    expect(send).not.toHaveBeenCalled();
  });
  it("probes a same-process iframe through its isolated execution context", async () => {
    vi.useFakeTimers();
    const send = vi.fn(async (_tabId: number, method: string) => {
      if (method === "Page.createIsolatedWorld") return { executionContextId: 91 };
      return { result: { value: { idleMs: 1_000, readyState: "complete" } } };
    });
    const cdp: CdpRunner = { send: send as unknown as CdpRunner["send"] };
    const settled = waitForDocumentSettled(cdp, {
      target: { tabId: 7 },
      frameId: "child-frame",
    });
    await vi.advanceTimersByTimeAsync(180);
    await expect(settled).resolves.toBe("quiet");
    expect(send).toHaveBeenCalledWith(
      7,
      "Page.createIsolatedWorld",
      expect.objectContaining({ frameId: "child-frame" }),
    );
    expect(send).toHaveBeenCalledWith(
      7,
      "Runtime.evaluate",
      expect.objectContaining({ contextId: 91 }),
    );
  });
  it("routes an OOPIF probe through its CDP target session", async () => {
    vi.useFakeTimers();
    const send = vi.fn();
    const sendToTarget = vi.fn(async (_target, method: string) => {
      if (method === "Page.createIsolatedWorld") return { executionContextId: 27 };
      return { result: { value: { idleMs: 1_000, readyState: "complete" } } };
    });
    const cdp: CdpRunner = {
      send: send as unknown as CdpRunner["send"],
      sendToTarget: sendToTarget as unknown as NonNullable<CdpRunner["sendToTarget"]>,
    };
    const target = { tabId: 7, sessionId: "oopif-session" };
    const settled = waitForDocumentSettled(cdp, { target, frameId: "oopif-frame" });
    await vi.advanceTimersByTimeAsync(180);
    await expect(settled).resolves.toBe("quiet");
    expect(send).not.toHaveBeenCalled();
    expect(sendToTarget).toHaveBeenCalledWith(
      target,
      "Runtime.evaluate",
      expect.objectContaining({ contextId: 27 }),
    );
  });
 });
@@ -1,30 +0,0 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createRandomUuid } from "../random-uuid";
 describe("createRandomUuid", () => {
  afterEach(() => {
    vi.unstubAllGlobals();
  });
  it("uses crypto.randomUUID when it is available", () => {
    const randomUUID = vi.fn(() => "00000000-0000-4000-8000-000000000000");
    vi.stubGlobal("crypto", { randomUUID, getRandomValues: vi.fn() });
    expect(createRandomUuid()).toBe("00000000-0000-4000-8000-000000000000");
    expect(randomUUID).toHaveBeenCalledOnce();
  });
  it("falls back to getRandomValues and sets UUID v4 bits", () => {
    const bytes = new Uint8Array(16).fill(0xff);
    const getRandomValues = vi.fn((target: Uint8Array) => {
      target.set(bytes);
      return target;
    });
    vi.stubGlobal("crypto", { getRandomValues });
    const uuid = createRandomUuid();
    expect(uuid).toBe("ffffffff-ffff-4fff-bfff-ffffffffffff");
    expect(getRandomValues).toHaveBeenCalledOnce();
  });
 });
@@ -1,32 +0,0 @@
 import { describe, expect, it } from "vitest";
 import {
  isAcceptedRecordStepAck,
  isRecordStepMessage,
  RECORD_STEP,
  type RecordStepMessage,
 } from "../record-bridge";
 const message: RecordStepMessage = {
  type: RECORD_STEP,
  requestId: "rec-1",
  producerId: "document-1",
  sequence: 1,
  step: { op: "click", target: { tag: "button", name: "Submit" } },
 };
 describe("record step delivery protocol", () => {
  it("requires a producer and a positive integer sequence", () => {
    expect(isRecordStepMessage(message)).toBe(true);
    expect(isRecordStepMessage({ ...message, producerId: "" })).toBe(false);
    expect(isRecordStepMessage({ ...message, sequence: 0 })).toBe(false);
    expect(isRecordStepMessage({ ...message, sequence: 1.5 })).toBe(false);
  });
  it("accepts only the acknowledgement for the sent sequence", () => {
    expect(isAcceptedRecordStepAck({ ok: true, sequence: 2 }, 2)).toBe(true);
    expect(isAcceptedRecordStepAck({ ok: true, sequence: 1 }, 2)).toBe(false);
    expect(isAcceptedRecordStepAck({ ok: false, expectedSequence: 2, error: "gap" }, 2)).toBe(
      false,
    );
  });
 });
@@ -1,213 +0,0 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { RECORD_FRAME_PORT, RECORD_FRAME_QUERY } from "../recording/frame-bridge";
 import { RecordFrameCoordinator } from "../recording/frame-coordinator";
 class ListenerSet<T extends (...args: never[]) => unknown> {
  readonly listeners = new Set<T>();
  addListener = (listener: T) => this.listeners.add(listener);
  removeListener = (listener: T) => this.listeners.delete(listener);
 }
 function fakePort(sender: chrome.runtime.MessageSender) {
  const messages: unknown[] = [];
  const onMessage = new ListenerSet<(message: unknown) => void>();
  const onDisconnect = new ListenerSet<() => void>();
  return {
    port: {
      name: RECORD_FRAME_PORT,
      sender,
      onMessage,
      onDisconnect,
      postMessage: vi.fn((message: unknown) => messages.push(message)),
      disconnect: vi.fn(),
    } as unknown as chrome.runtime.Port,
    messages,
    receive(message: unknown) {
      for (const listener of onMessage.listeners) listener(message);
    },
  };
 }
 describe("RecordFrameCoordinator", () => {
  const onConnect = new ListenerSet<(port: chrome.runtime.Port) => void>();
  const onMessage = new ListenerSet<
    (
      message: unknown,
      sender: chrome.runtime.MessageSender,
      sendResponse: (response: unknown) => void,
    ) => boolean
  >();
  beforeEach(() => {
    onConnect.listeners.clear();
    onMessage.listeners.clear();
    vi.stubGlobal("chrome", {
      runtime: { onConnect, onMessage },
    });
  });
  it("answers child-document queries for the initial tab before it is armed", () => {
    const coordinator = new RecordFrameCoordinator({
      getAllFrames: async () => [],
      sendToDocument: async () => ({ ok: true }),
    });
    coordinator.attach();
    coordinator.begin("rec-1", 10, 3);
    const query = (tabId: number) => {
      let response: unknown;
      for (const listener of onMessage.listeners) {
        listener(
          { type: RECORD_FRAME_QUERY },
          {
            tab: { id: tabId },
            frameId: 7,
            documentId: "child-document",
          } as chrome.runtime.MessageSender,
          (value) => {
            response = value;
          },
        );
      }
      return response;
    };
    expect(query(3)).toEqual({ active: true, requestId: "rec-1", startedAtMs: 10 });
    expect(query(4)).toEqual({ active: false });
  });
  it("starts a child Document that appears after the initial frame snapshot", async () => {
    let notifyFrameNavigation:
      | ((frame: {
          tabId: number;
          frameId: number;
          documentId?: string;
          lifecycle: "committed" | "completed";
        }) => void)
      | undefined;
    const sendToDocument = vi.fn(async () => ({ ok: true }));
    const coordinator = new RecordFrameCoordinator({
      getAllFrames: async () => [{ frameId: 0, documentId: "top-document" }],
      sendToDocument,
      subscribeFrameNavigation(listener) {
        notifyFrameNavigation = listener;
        return () => {};
      },
    });
    coordinator.attach();
    const onDocumentReady = vi.fn();
    coordinator.begin("rec-1", 10, 3, onDocumentReady);
    await coordinator.armTab("rec-1", 3);
    sendToDocument.mockClear();
    notifyFrameNavigation?.({
      tabId: 3,
      frameId: 7,
      documentId: "late-child",
      lifecycle: "completed",
    });
    await vi.waitFor(() => {
      expect(sendToDocument).toHaveBeenCalledWith(
        3,
        { type: "bsk-record-frame-start", requestId: "rec-1", startedAtMs: 10 },
        { documentId: "late-child" },
      );
    });
    expect(onDocumentReady).not.toHaveBeenCalled();
    const child = fakePort({
      tab: { id: 3 },
      frameId: 7,
      documentId: "late-child",
    } as chrome.runtime.MessageSender);
    for (const listener of onConnect.listeners) listener(child.port);
    child.receive({ type: "ready", requestId: "rec-1", producerId: "producer-1" });
    notifyFrameNavigation?.({
      tabId: 3,
      frameId: 7,
      documentId: "late-child",
      lifecycle: "completed",
    });
    await vi.waitFor(() => {
      expect(onDocumentReady).toHaveBeenCalledWith({
        tabId: 3,
        documentId: "late-child",
        browserFrameId: 7,
        producerId: "producer-1",
      });
    });
  });
  it("binds a producer to its sender Document and keeps final steps valid while stopping", async () => {
    const sendToDocument = vi.fn(async () => ({ ok: true }));
    const coordinator = new RecordFrameCoordinator({
      getAllFrames: async () => [
        { frameId: 0, documentId: "top-document" },
        { frameId: 7, documentId: "child-document" },
      ],
      sendToDocument,
    });
    coordinator.attach();
    coordinator.begin("rec-1", 10, 3);
    await expect(coordinator.armTab("rec-1", 3)).resolves.toBe(true);
    const sender = {
      tab: { id: 3 },
      frameId: 7,
      documentId: "child-document",
    } as chrome.runtime.MessageSender;
    const frame = fakePort(sender);
    for (const listener of onConnect.listeners) listener(frame.port);
    frame.receive({ type: "ready", requestId: "rec-1", producerId: "producer-1" });
    expect(coordinator.sourceFor("rec-1", "producer-1", sender)).toEqual({
      tabId: 3,
      documentId: "child-document",
      browserFrameId: 7,
      producerId: "producer-1",
    });
    const stopping = coordinator.stop("rec-1");
    expect(coordinator.sourceFor("rec-1", "producer-1", sender)).not.toBeNull();
    const stop = frame.messages.find(
      (message): message is { type: "stop"; commandId: string } =>
        typeof message === "object" &&
        message !== null &&
        (message as { type?: string }).type === "stop",
    );
    expect(stop).toBeDefined();
    frame.receive({
      type: "stopped",
      requestId: "rec-1",
      commandId: stop!.commandId,
      ok: true,
    });
    await expect(stopping).resolves.toBe(true);
    expect(coordinator.sourceFor("rec-1", "producer-1", sender)).toBeNull();
  });
  it("rejects a producer used from another Document", async () => {
    const coordinator = new RecordFrameCoordinator({
      getAllFrames: async () => [{ frameId: 0, documentId: "top-document" }],
      sendToDocument: async () => ({ ok: true }),
    });
    coordinator.attach();
    coordinator.begin("rec-1", 10, 3);
    await coordinator.armTab("rec-1", 3);
    const sender = {
      tab: { id: 3 },
      frameId: 0,
      documentId: "top-document",
    } as chrome.runtime.MessageSender;
    const frame = fakePort(sender);
    for (const listener of onConnect.listeners) listener(frame.port);
    frame.receive({ type: "ready", requestId: "rec-1", producerId: "producer-1" });
    expect(
      coordinator.sourceFor("rec-1", "producer-1", {
        ...sender,
        documentId: "other-document",
      }),
    ).toBeNull();
  });
 });
@@ -1,70 +0,0 @@
 import { describe, expect, it } from "vitest";
 import {
  RECORD_DOCUMENT_ATTRIBUTE,
  recordingDocumentMarkerValue,
 } from "@/shared/recording-document-identity";
 import { markRecordingDocument } from "../recording/document-marker";
 import { ObservationNodeIndex } from "../recording/observation-capture";
 describe("recording document marker", () => {
  it("rejects a non-random Document identity", () => {
    expect(() => markRecordingDocument("user@example.com")).toThrow(
      "recording Document identity must be a random UUID",
    );
  });
  it("restores the Document attribute exactly", () => {
    document.documentElement.setAttribute(RECORD_DOCUMENT_ATTRIBUTE, "page-value");
    const producerId = "123e4567-e89b-42d3-a456-426614174000";
    const marker = markRecordingDocument(producerId);
    expect(document.documentElement.getAttribute(RECORD_DOCUMENT_ATTRIBUTE)).toBe(
      recordingDocumentMarkerValue(producerId),
    );
    marker.restore();
    expect(document.documentElement.getAttribute(RECORD_DOCUMENT_ATTRIBUTE)).toBe("page-value");
    document.documentElement.removeAttribute(RECORD_DOCUMENT_ATTRIBUTE);
  });
  it("indexes the CDP scope from the safe frame identity", () => {
    const index = new ObservationNodeIndex({
      rootFrameId: "root",
      frames: [
        {
          frameId: "child",
          target: { tabId: 3, sessionId: "oopif-session" },
          recordingDocumentId: "producer-1",
        },
      ],
      matchNodes: [],
      refs: [],
    });
    expect(index.documentScope("producer-1")).toEqual({
      frameId: "child",
      target: { tabId: 3, sessionId: "oopif-session" },
    });
  });
  it("fails closed when a recording identity maps to multiple Documents", () => {
    const index = new ObservationNodeIndex({
      rootFrameId: "root",
      frames: [
        {
          frameId: "left",
          target: { tabId: 3, sessionId: "left-session" },
          recordingDocumentId: "duplicate",
        },
        {
          frameId: "right",
          target: { tabId: 3, sessionId: "right-session" },
          recordingDocumentId: "duplicate",
        },
      ],
      matchNodes: [],
      refs: [],
    });
    expect(index.documentScope("duplicate")).toBeUndefined();
  });
 });
@@ -1,146 +0,0 @@
 import { describe, expect, it } from "vitest";
 import { ObservationNodeIndex } from "../recording/observation-capture";
 import { RecordingObservationSession } from "../recording/observation-session";
 import { RecordingStateRegistry } from "../recording/state-registry";
 import { buildTraceV3 } from "../recording/trace-builder-v3";
 import type { RecordingDraftStep } from "../recording/types";
 const URL = "https://example.com/login";
 function sessionWithInput(redactValues = false): RecordingObservationSession {
  const session = new RecordingObservationSession({ redactValues });
  const state = session.registry.register({
    url: URL,
    vomText: '@vom 1\ntextbox "Password" value="••••••" [ref=e1]',
  });
  session.cursor.lastSettled = {
    stateId: state.id,
    rootFrameId: "root",
    index: new ObservationNodeIndex({
      rootFrameId: "root",
      matchNodes: [
        {
          frameId: "root",
          backendNodeId: 42,
          tag: "input",
          rect: { x: 20, y: 40, w: 200, h: 30 },
          localRect: { x: 20, y: 40, w: 200, h: 30 },
        },
      ],
      refs: [{ ref: "e1", backendNodeId: 42, role: "textbox", name: "Password", line: 1 }],
    }),
    url: URL,
  };
  return session;
 }
 function finalizedFillTrace(value: string, redactValues: boolean) {
  const session = sessionWithInput(redactValues);
  const draft: RecordingDraftStep = {
    op: "fill",
    captureTarget: { tag: "input", role: "textbox", name: "Password" },
    value,
    targetHint: {
      geometry: { rect: { x: 20, y: 40, w: 200, h: 30 }, tag: "input" },
    },
  };
  session.bindDraft(draft, 1);
  draft.postStateId = draft.preStateId;
  return buildTraceV3({
    registry: session.registry,
    drafts: [draft],
    annotations: session.annotations,
    startedAt: "2026-08-12T00:00:00.000Z",
    stoppedBy: "user_finish",
    bskVersion: "test",
    redactValues,
  });
 }
 function finalizedFillBody(value: string, redactValues: boolean): string {
  return finalizedFillTrace(value, redactValues).states[0]!.body;
 }
 describe("record observation annotations", () => {
  it("omits a fill literal when values are redacted", () => {
    const secret = "hunter2-private";
    const dumped = JSON.stringify(finalizedFillTrace(secret, true));
    expect(dumped).toContain("step 1: fill");
    expect(dumped).not.toContain(secret);
  });
  it("keeps ordinary fill details", () => {
    expect(finalizedFillBody("ordinary text", false)).toContain('step 1: fill: "ordinary text"');
  });
  it("encodes title and URL so line breaks cannot corrupt state metadata", () => {
    const registry = new RecordingStateRegistry();
    const state = registry.register({
      url: "https://example.com/a\nb",
      title: "hello\nworld",
      vomText: "@vom 1",
    });
    const trace = buildTraceV3({
      registry,
      drafts: [{ op: "scroll", preStateId: state.id, postStateId: state.id }],
      startedAt: "2026-08-12T00:00:00.000Z",
      stoppedBy: "user_finish",
      bskVersion: "test",
    });
    expect(trace.states[0]?.body).toContain('url: "https://example.com/a\\nb"');
    expect(trace.states[0]?.body).toContain('title: "hello\\nworld"');
  });
 });
 describe("recording state ownership", () => {
  it("deduplicates within one recording and isolates ids between recordings", () => {
    const first = new RecordingStateRegistry();
    const second = new RecordingStateRegistry();
    expect(first.register({ url: URL, vomText: "same" }).id).toBe("s1");
    expect(first.register({ url: URL, vomText: "same" }).id).toBe("s1");
    expect(second.register({ url: URL, vomText: "other" }).id).toBe("s1");
  });
  it("enriches metadata when a deduplicated observation becomes more complete", () => {
    const registry = new RecordingStateRegistry();
    registry.register({ url: URL, vomText: "same" });
    const state = registry.register({
      url: URL,
      title: "Login",
      vomText: "same",
      truncated: true,
    });
    expect(state).toMatchObject({ id: "s1", title: "Login", truncated: true });
  });
 });
 describe("draft binding", () => {
  it("keeps capture semantics when no observation exists", () => {
    const session = new RecordingObservationSession();
    const draft: RecordingDraftStep = {
      op: "hover",
      captureTarget: { tag: "button", role: "button", name: "新建" },
    };
    session.bindDraft(draft, 1);
    expect(draft.matchedTarget).toEqual({ role: "button", name: "新建", unmatched: true });
    expect(draft.preStateId).toBeUndefined();
  });
  it("does not bind an unmatched new action to a stale observation", () => {
    const session = sessionWithInput();
    const draft: RecordingDraftStep = {
      op: "click",
      captureTarget: { tag: "button", role: "button", name: "Confirm" },
      targetHint: {
        geometry: { rect: { x: 400, y: 300, w: 80, h: 30 }, tag: "button" },
      },
    };
    session.bindDraft(draft, 2, true);
    expect(draft.preStateId).toBeUndefined();
    expect("matchedTarget" in draft ? draft.matchedTarget : undefined).toEqual({
      role: "button",
      name: "Confirm",
      unmatched: true,
    });
  });
 });
@@ -1,289 +0,0 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { CdpRunner, ChromeTabsApi } from "@/tools/shared";
 const captureRecordingObservation = vi.hoisted(() => vi.fn());
 const waitForDocumentSettled = vi.hoisted(() => vi.fn(async () => "quiet" as const));
 vi.mock("../recording/observation-capture", async (importOriginal) => {
  const actual = await importOriginal<typeof import("../recording/observation-capture")>();
  return { ...actual, captureRecordingObservation };
 });
 vi.mock("../recording/document-settle", async (importOriginal) => {
  const actual = await importOriginal<typeof import("../recording/document-settle")>();
  return { ...actual, waitForDocumentSettled };
 });
 import { ObservationNodeIndex } from "../recording/observation-capture";
 import { RecordingObservationRuntime } from "../recording/recording-runtime";
 import type { RecordingDraftStep } from "../recording/types";
 function observation(url = "https://example.com/") {
  return {
    rootFrameId: "root",
    index: new ObservationNodeIndex({ rootFrameId: "root", matchNodes: [], refs: [] }),
    url,
    title: "Example",
    vomText: '@vom 1\nRootWebArea "Example"',
    truncated: false,
  };
 }
 function runtime(): RecordingObservationRuntime {
  return new RecordingObservationRuntime({
    cdp: { send: vi.fn() as unknown as CdpRunner["send"] },
    tabsApi: { get: vi.fn(), query: vi.fn() } as unknown as ChromeTabsApi,
  });
 }
 describe("RecordingObservationRuntime", () => {
  afterEach(() => {
    captureRecordingObservation.mockReset();
    waitForDocumentSettled.mockClear();
  });
  it("shares one initial capture and includes it in flush", async () => {
    let release!: (value: ReturnType<typeof observation>) => void;
    captureRecordingObservation.mockReturnValueOnce(
      new Promise((resolve) => {
        release = resolve;
      }),
    );
    const recording = runtime();
    const first = recording.captureInitial(7);
    const second = recording.captureInitial(7);
    const flushed = recording.flush();
    let flushCompleted = false;
    void flushed.then(() => {
      flushCompleted = true;
    });
    await Promise.resolve();
    expect(captureRecordingObservation).toHaveBeenCalledTimes(1);
    expect(flushCompleted).toBe(false);
    release(observation());
    await Promise.all([first, second, flushed]);
    expect(flushCompleted).toBe(true);
  });
  it("cancels an in-flight initial capture", async () => {
    captureRecordingObservation.mockImplementationOnce(
      (input: { signal?: AbortSignal }) =>
        new Promise((_, reject) => {
          input.signal?.addEventListener(
            "abort",
            () => reject(new DOMException("observation aborted", "AbortError")),
            { once: true },
          );
        }),
    );
    const recording = runtime();
    const pending = recording.captureInitial(7);
    recording.cancel();
    await expect(pending).rejects.toMatchObject({ name: "AbortError" });
  });
  it("retries a failed initial capture when the recording settles at stop", async () => {
    captureRecordingObservation
      .mockRejectedValueOnce(new Error("document swapped"))
      .mockResolvedValueOnce(observation());
    const recording = runtime();
    await expect(recording.captureInitial(7)).rejects.toThrow("document swapped");
    await recording.settleTrailing(7, []);
    const trace = recording.buildTrace({
      drafts: [],
      startedAt: "2026-08-19T00:00:00.000Z",
      stoppedBy: "user_finish",
      bskVersion: "0.1.6",
    });
    expect(captureRecordingObservation).toHaveBeenCalledTimes(2);
    expect(trace.states).toHaveLength(1);
  });
  it("keeps runtime matching data out of the serialized trace", async () => {
    const captured = observation();
    captured.index = new ObservationNodeIndex({
      rootFrameId: "root",
      matchNodes: [
        {
          frameId: "root",
          backendNodeId: 42,
          tag: "button",
          rect: { x: 10, y: 20, w: 100, h: 30 },
          localRect: { x: 10, y: 20, w: 100, h: 30 },
        },
      ],
      refs: [{ ref: "e1", backendNodeId: 42, role: "button", name: "Submit", line: 1 }],
    });
    captureRecordingObservation.mockResolvedValueOnce(captured);
    const recording = runtime();
    await recording.captureInitial(7);
    const dumped = JSON.stringify(
      recording.buildTrace({
        drafts: [],
        startedAt: "2026-08-19T00:00:00.000Z",
        stoppedBy: "user_finish",
        bskVersion: "0.1.6",
      }),
    );
    expect(dumped).toContain("RootWebArea");
    expect(dumped).not.toContain("matchNodes");
    expect(dumped).not.toContain("localRect");
    expect(dumped).not.toContain("backendNodeId");
    expect(dumped).not.toContain("ObservationNodeIndex");
  });
  it("captures a tab transition without sharing observation cursors", async () => {
    captureRecordingObservation
      .mockResolvedValueOnce(observation("https://example.com/first"))
      .mockResolvedValueOnce(observation("https://example.com/second"));
    const recording = runtime();
    await recording.captureInitial(4);
    const transition = await recording.captureTabTransition(4, 5);
    await recording.captureInitial(4);
    await recording.captureInitial(5);
    expect(transition).toEqual({
      preStateId: "s1",
      postStateId: "s2",
      targetUrl: "https://example.com/second",
    });
    expect(captureRecordingObservation.mock.calls.map(([input]) => input.tabId)).toEqual([4, 5]);
  });
  it("binds an iframe draft to its marked CDP Document scope", async () => {
    captureRecordingObservation.mockResolvedValueOnce({
      ...observation(),
      index: new ObservationNodeIndex({
        rootFrameId: "root",
        frames: [
          {
            frameId: "child",
            target: { tabId: 7, sessionId: "oopif-session" },
            recordingDocumentId: "producer-1",
          },
        ],
        matchNodes: [
          {
            backendNodeId: 42,
            frameId: "child",
            tag: "button",
            rect: { x: 410, y: 20, w: 100, h: 30 },
            localRect: { x: 10, y: 20, w: 100, h: 30 },
          },
        ],
        refs: [{ ref: "e1", backendNodeId: 42, frameId: "child", line: 1 }],
      }),
    });
    const recording = runtime();
    const drafts: RecordingDraftStep[] = [
      {
        op: "click" as const,
        captureTarget: { tag: "button", role: "button", name: "Save" },
        targetHint: {
          geometry: { rect: { x: 10, y: 20, w: 100, h: 30 }, tag: "button" },
        },
      },
    ];
    await recording.captureInitial(7);
    await recording.processDraft(7, drafts, 0, "producer-1");
    recording.cancel();
    const draft = drafts[0];
    expect(draft?.op).toBe("click");
    if (!draft || draft.op !== "click") throw new Error("expected click draft");
    expect(draft.targetHint).toMatchObject({
      frameId: "child",
      geometrySpace: "local",
    });
    expect(draft.matchedTarget?.ref).toBe("e1");
  });
  it("refreshes a late iframe before matching its first action", async () => {
    const iframeObservation = {
      ...observation(),
      index: new ObservationNodeIndex({
        rootFrameId: "root",
        frames: [
          {
            frameId: "child",
            target: { tabId: 7, sessionId: "oopif-session" },
            recordingDocumentId: "producer-1",
          },
        ],
        matchNodes: [
          {
            backendNodeId: 42,
            frameId: "child",
            tag: "button",
            rect: { x: 410, y: 20, w: 100, h: 30 },
            localRect: { x: 10, y: 20, w: 100, h: 30 },
          },
        ],
        refs: [
          {
            ref: "e1",
            backendNodeId: 42,
            frameId: "child",
            role: "button",
            name: "表格视图",
            line: 1,
          },
        ],
      }),
    };
    captureRecordingObservation
      .mockResolvedValueOnce(observation())
      .mockResolvedValueOnce(iframeObservation)
      .mockResolvedValueOnce(iframeObservation);
    const recording = runtime();
    await recording.captureInitial(7);
    await recording.refreshDocument(7, "producer-1");
    const drafts: RecordingDraftStep[] = [
      {
        op: "click",
        captureTarget: { tag: "button", role: "button", name: "表格视图" },
        targetHint: {
          geometry: { rect: { x: 10, y: 20, w: 100, h: 30 }, tag: "button" },
        },
      },
    ];
    await recording.processDraft(7, drafts, 0, "producer-1");
    recording.cancel();
    expect(captureRecordingObservation).toHaveBeenCalledTimes(3);
    expect(waitForDocumentSettled).toHaveBeenCalledWith(
      expect.anything(),
      { frameId: "child", target: { tabId: 7, sessionId: "oopif-session" } },
      { signal: expect.any(AbortSignal) },
    );
    const draft = drafts[0];
    expect(draft?.op).toBe("click");
    if (!draft || draft.op !== "click") throw new Error("expected click draft");
    expect(draft.matchedTarget).toMatchObject({ ref: "e1", name: "表格视图" });
  });
  it("does not poison final flush when a frame readiness refresh fails", async () => {
    captureRecordingObservation
      .mockResolvedValueOnce(observation())
      .mockRejectedValueOnce(new Error("child Document replaced"));
    const recording = runtime();
    await recording.captureInitial(7);
    await expect(recording.refreshDocument(7, "producer-1")).rejects.toThrow(
      "child Document replaced",
    );
    await expect(recording.flush()).resolves.toBeUndefined();
  });
 });
@@ -0,0 +1,80 @@
 import { describe, expect, it } from "vitest";
 import { appendRecordedPayload, observeRecordedNavigation } from "../recording-step-buffer";
 describe("recording-step-buffer", () => {
  it("stores semantic click without summary", () => {
    const buffer = { steps: [], pendingNavigation: false };
    appendRecordedPayload(buffer, {
      op: "click",
      target: { tag: "button", role: "button", name: "发布" },
      expects_navigation: true,
    });
    expect(buffer.steps).toEqual([
      {
        op: "click",
        target: { tag: "button", role: "button", name: "发布" },
      },
    ]);
    expect(buffer.pendingNavigation).toBe(true);
  });
  it("annotates navigated_to on action-caused navigation instead of wait_for_navigation", () => {
    const buffer = {
      steps: [
        {
          op: "click" as const,
          target: { tag: "button", role: "button", name: "发布" },
        },
      ],
      currentUrl: "https://example.com/a",
      pendingNavigation: true,
      pendingNavigationDeadline: Date.now() + 5_000,
    };
    observeRecordedNavigation(buffer, "https://example.com/b", true);
    expect(buffer.steps).toEqual([
      {
        op: "click",
        target: { tag: "button", role: "button", name: "发布" },
        navigated_to: "https://example.com/b",
      },
    ]);
    expect(JSON.stringify(buffer.steps)).not.toContain("wait_for_navigation");
  });
  it("annotates navigated_to onto a select that auto-submits a navigation", () => {
    const buffer = {
      steps: [
        {
          op: "select" as const,
          target: { tag: "select", role: "combobox", name: "分类" },
          values: ["tech"],
        },
      ],
      currentUrl: "https://example.com/list",
      pendingNavigation: true,
      pendingNavigationDeadline: Date.now() + 5_000,
    };
    observeRecordedNavigation(buffer, "https://example.com/list?cat=tech", true);
    expect(buffer.steps).toEqual([
      {
        op: "select",
        target: { tag: "select", role: "combobox", name: "分类" },
        values: ["tech"],
        navigated_to: "https://example.com/list?cat=tech",
      },
    ]);
  });
  it("emits navigate for uncaused URL changes", () => {
    const buffer = {
      steps: [],
      currentUrl: "https://example.com/a",
      pendingNavigation: false,
    };
    observeRecordedNavigation(buffer, "https://example.com/b", false);
    expect(buffer.steps[0]).toMatchObject({
      op: "navigate",
      url: "https://example.com/b",
    });
  });
 });
@@ -1,136 +0,0 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { CdpRunner, ChromeTabsApi } from "@/tools/shared";
 import { ObservationNodeIndex, type RegisteredObservation } from "../recording/observation-capture";
 import { RecordingObservationSession } from "../recording/observation-session";
 import { SettleController } from "../recording/settle-controller";
 import type { RecordingDraftStep } from "../recording/types";
 const OBSERVATION: RegisteredObservation = {
  stateId: "s-next",
  rootFrameId: "root",
  index: new ObservationNodeIndex({ rootFrameId: "root", matchNodes: [], refs: [] }),
  url: "https://example.com/next",
 };
 describe("SettleController", () => {
  afterEach(() => vi.useRealTimers());
  it("aborts superseded capture work and lands the prior action on the next origin", async () => {
    vi.useFakeTimers();
    const cdp: CdpRunner = {
      send: vi.fn(async () => ({
        result: { value: { idleMs: 1_000, readyState: "complete" } },
      })) as unknown as CdpRunner["send"],
    };
    const tabsApi: ChromeTabsApi = {
      get: vi.fn(async () => ({ id: 7, url: OBSERVATION.url }) as chrome.tabs.Tab),
      query: vi.fn(async () => []),
    };
    const session = new RecordingObservationSession();
    let firstSignal: AbortSignal | undefined;
    vi.spyOn(session, "capture")
      .mockImplementationOnce(async (_cdp, _tabs, _tabId, signal) => {
        firstSignal = signal;
        return new Promise<RegisteredObservation>((_resolve, reject) => {
          signal?.addEventListener(
            "abort",
            () => reject(new DOMException("observation aborted", "AbortError")),
            { once: true },
          );
        });
      })
      .mockResolvedValueOnce(OBSERVATION);
    const drafts: RecordingDraftStep[] = [
      { op: "click", captureTarget: { tag: "button", name: "First" }, preStateId: "s1" },
    ];
    const controller = new SettleController({ session, cdp, tabsApi, tabId: 7 });
    controller.schedule(drafts, 0);
    await vi.advanceTimersByTimeAsync(180);
    drafts.push({
      op: "click",
      captureTarget: { tag: "button", name: "Second" },
      preStateId: "s-next",
    });
    controller.schedule(drafts, 1);
    expect(firstSignal?.aborted).toBe(true);
    expect(drafts[0]?.postStateId).toBe("s-next");
    await vi.advanceTimersByTimeAsync(500);
    await controller.flush();
    expect(drafts[1]?.postStateId).toBe("s-next");
  });
  it("does not consume a newer redirect while reading the prior landing URL", async () => {
    vi.useFakeTimers();
    const cdp: CdpRunner = {
      send: vi.fn(async () => ({
        result: { value: { idleMs: 1_000, readyState: "complete" } },
      })) as unknown as CdpRunner["send"],
    };
    let resolveFirstTab!: (tab: chrome.tabs.Tab) => void;
    const firstTab = new Promise<chrome.tabs.Tab>((resolve) => {
      resolveFirstTab = resolve;
    });
    const tabsApi: ChromeTabsApi = {
      get: vi
        .fn()
        .mockImplementationOnce(() => firstTab)
        .mockResolvedValue({ id: 7, url: OBSERVATION.url }),
      query: vi.fn(async () => []),
    };
    const session = new RecordingObservationSession();
    session.cursor.lastSettled = OBSERVATION;
    const drafts: RecordingDraftStep[] = [];
    const controller = new SettleController({ session, cdp, tabsApi, tabId: 7 });
    controller.scheduleRedirect(drafts, "https://example.com/intermediate");
    await vi.advanceTimersByTimeAsync(180);
    expect(tabsApi.get).toHaveBeenCalledTimes(1);
    controller.scheduleRedirect(drafts, OBSERVATION.url);
    resolveFirstTab({ id: 7, url: "https://example.com/intermediate" } as chrome.tabs.Tab);
    await vi.advanceTimersByTimeAsync(500);
    await controller.flushRedirects();
    expect(drafts).toEqual([]);
    expect(controller.hasPending).toBe(false);
  });
  it("settles an action in its own OOPIF document scope", async () => {
    vi.useFakeTimers();
    const send = vi.fn();
    const sendToTarget = vi.fn(async (_target, method: string) => {
      if (method === "Page.createIsolatedWorld") return { executionContextId: 39 };
      return { result: { value: { idleMs: 1_000, readyState: "complete" } } };
    });
    const cdp: CdpRunner = {
      send: send as unknown as CdpRunner["send"],
      sendToTarget: sendToTarget as unknown as NonNullable<CdpRunner["sendToTarget"]>,
    };
    const tabsApi: ChromeTabsApi = {
      get: vi.fn(async () => ({ id: 7, url: OBSERVATION.url }) as chrome.tabs.Tab),
      query: vi.fn(async () => []),
    };
    const session = new RecordingObservationSession();
    vi.spyOn(session, "capture").mockResolvedValue(OBSERVATION);
    const drafts: RecordingDraftStep[] = [
      { op: "click", captureTarget: { tag: "button", name: "Inside frame" } },
    ];
    const controller = new SettleController({ session, cdp, tabsApi, tabId: 7 });
    const target = { tabId: 7, sessionId: "oopif-session" };
    controller.schedule(drafts, 0, { target, frameId: "oopif-frame" });
    await vi.advanceTimersByTimeAsync(180);
    await controller.flush();
    expect(send).not.toHaveBeenCalled();
    expect(sendToTarget).toHaveBeenCalledWith(
      target,
      "Runtime.evaluate",
      expect.objectContaining({ contextId: 39 }),
    );
    expect(drafts[0]?.postStateId).toBe("s-next");
  });
 });
@@ -1,164 +0,0 @@
 import { describe, expect, it } from "vitest";
 import { appendRecordedPayload, observeRecordedNavigation } from "../recording/step-buffer";
 describe("recording-step-buffer", () => {
  it("stores semantic click without summary", () => {
    const buffer = { steps: [], navigation: { pendingNavigation: false } };
    appendRecordedPayload(buffer, {
      op: "click",
      target: { tag: "button", role: "button", name: "发布" },
      expects_navigation: true,
    });
    expect(buffer.steps).toEqual([
      {
        op: "click",
        captureTarget: { tag: "button", role: "button", name: "发布" },
      },
    ]);
    expect(buffer.navigation.pendingNavigation).toBe(true);
  });
  it("keeps the hovered element description as a capture fallback", () => {
    const buffer = { steps: [], navigation: { pendingNavigation: false } };
    appendRecordedPayload(
      buffer,
      {
        op: "hover",
        target: { tag: "button", role: "button", name: "新建" },
        geometry: {
          rect: { x: 900, y: 8, w: 60, h: 32 },
          tag: "button",
        },
      },
      {
        geometry: {
          rect: { x: 900, y: 8, w: 60, h: 32 },
          tag: "button",
        },
      },
    );
    expect(buffer.steps).toEqual([
      {
        op: "hover",
        captureTarget: { tag: "button", role: "button", name: "新建" },
        targetHint: {
          geometry: {
            rect: { x: 900, y: 8, w: 60, h: 32 },
            tag: "button",
          },
        },
      },
    ]);
  });
  it("annotates navigated_to on action-caused navigation instead of wait_for_navigation", () => {
    const buffer = {
      steps: [
        {
          op: "click" as const,
          captureTarget: { tag: "button", role: "button", name: "发布" },
        },
      ],
      navigation: {
        currentUrl: "https://example.com/a",
        pendingNavigation: true,
        pendingNavigationDeadline: Date.now() + 5_000,
      },
    };
    observeRecordedNavigation(buffer, "https://example.com/b", true);
    expect(buffer.steps).toEqual([
      {
        op: "click",
        captureTarget: { tag: "button", role: "button", name: "发布" },
        navigatedTo: "https://example.com/b",
      },
    ]);
    expect(JSON.stringify(buffer.steps)).not.toContain("wait_for_navigation");
  });
  it("annotates navigated_to onto a select that auto-submits a navigation", () => {
    const buffer = {
      steps: [
        {
          op: "select" as const,
          captureTarget: { tag: "select", role: "combobox", name: "分类" },
          values: ["tech"],
        },
      ],
      navigation: {
        currentUrl: "https://example.com/list",
        pendingNavigation: true,
        pendingNavigationDeadline: Date.now() + 5_000,
      },
    };
    observeRecordedNavigation(buffer, "https://example.com/list?cat=tech", true);
    expect(buffer.steps).toEqual([
      {
        op: "select",
        captureTarget: { tag: "select", role: "combobox", name: "分类" },
        values: ["tech"],
        navigatedTo: "https://example.com/list?cat=tech",
      },
    ]);
  });
  it("emits navigate for uncaused URL changes", () => {
    const buffer = {
      steps: [],
      navigation: { currentUrl: "https://example.com/a", pendingNavigation: false },
    };
    const result = observeRecordedNavigation(buffer, "https://example.com/b", false);
    expect(result).toEqual({ kind: "appended", index: 0 });
    expect(buffer.steps[0]).toMatchObject({
      op: "navigate",
      url: "https://example.com/b",
    });
  });
  it("asks the recorder to coalesce redirect hops instead of emitting each one", () => {
    const buffer = {
      steps: [],
      navigation: {
        currentUrl: "https://passport.example/login",
        pendingNavigation: false,
      },
    };
    const hop1 = observeRecordedNavigation(
      buffer,
      "https://passport.example/callback",
      false,
      "link",
      ["server_redirect"],
    );
    expect(hop1).toEqual({
      kind: "coalesce_redirect",
      url: "https://passport.example/callback",
    });
    expect(buffer.steps).toEqual([]);
    const hop2 = observeRecordedNavigation(buffer, "https://app.example/dashboard", false, "link", [
      "client_redirect",
    ]);
    expect(hop2).toEqual({
      kind: "coalesce_redirect",
      url: "https://app.example/dashboard",
    });
    expect(buffer.steps).toEqual([]);
    expect(buffer.navigation.currentUrl).toBe("https://app.example/dashboard");
  });
  it("does not reuse redirect metadata for a later content-observed URL change", () => {
    const buffer = {
      steps: [],
      navigation: {
        currentUrl: "https://example.com/redirect",
        pendingNavigation: false,
      },
    };
    const result = observeRecordedNavigation(buffer, "https://example.com/spa");
    expect(result).toEqual({ kind: "appended", index: 0 });
    expect(buffer.steps[0]).toMatchObject({ op: "navigate", url: "https://example.com/spa" });
  });
 });
@@ -1,39 +0,0 @@
 import { describe, expect, it } from "vitest";
 import { RecordingTabCoordinator } from "../recording/tab-coordinator";
 describe("RecordingTabCoordinator", () => {
  it("keeps navigation state isolated per tab", () => {
    const tabs = new RecordingTabCoordinator(4, "https://example.com/first");
    const first = tabs.navigation(4);
    first.pendingNavigation = true;
    const second = tabs.navigation(5, "https://example.com/second");
    expect(second).toEqual({
      currentUrl: "https://example.com/second",
      pendingNavigation: false,
    });
    expect(tabs.navigation(4)).toBe(first);
    expect(tabs.navigation(4).pendingNavigation).toBe(true);
  });
  it("invalidates an earlier activation when a newer tab becomes active", () => {
    const tabs = new RecordingTabCoordinator(4);
    const second = tabs.noteActivation(5);
    const third = tabs.noteActivation(6);
    expect(tabs.isLatest(second)).toBe(false);
    expect(tabs.isLatest(third)).toBe(true);
    tabs.commit(6);
    expect(tabs.currentTabId).toBe(6);
  });
  it("commits the freshly observed URL when returning to an existing tab", () => {
    const tabs = new RecordingTabCoordinator(4);
    tabs.navigation(5, "https://example.com/old");
    tabs.commit(5, "https://example.com/new");
    expect(tabs.currentTabId).toBe(5);
    expect(tabs.navigation(5).currentUrl).toBe("https://example.com/new");
  });
 });
@@ -1,159 +0,0 @@
 import type { RenderedRef } from "@browser-skill/vom";
 import { describe, expect, it } from "vitest";
 import type { CaptureVomMatchNode } from "@/tools/capture-vom-observation";
 import { ObservationNodeIndex, type RegisteredObservation } from "../recording/observation-capture";
 import { matchObservationTarget } from "../recording/target-matcher";
 function node(backendNodeId: number, frameId: string, x = 10): CaptureVomMatchNode {
  return {
    backendNodeId,
    frameId,
    tag: "button",
    rect: { x, y: 20, w: 100, h: 30 },
    localRect: { x, y: 20, w: 100, h: 30 },
  };
 }
 function observation(
  matchNodes: CaptureVomMatchNode[],
  refs: RenderedRef[],
 ): RegisteredObservation {
  return {
    stateId: "s1",
    rootFrameId: "root",
    index: new ObservationNodeIndex({ rootFrameId: "root", matchNodes, refs }),
    url: "https://example.com",
  };
 }
 describe("matchObservationTarget", () => {
  it("indexes the safe geometry DTO without discarding frame-local geometry", () => {
    const geometry = node(42, "child");
    geometry.localRect = { x: 5, y: 6, w: 100, h: 30 };
    const ref: RenderedRef = {
      ref: "e1",
      backendNodeId: 42,
      frameId: "child",
      line: 1,
    };
    const candidate = observation([geometry], [ref]).index.candidates("child", "button")[0];
    expect(candidate).toEqual({ frameId: "child", geometry, ref });
  });
  it("matches a unique node using canonical top-level viewport geometry", () => {
    const target = matchObservationTarget({
      observation: observation(
        [node(42, "root")],
        [{ ref: "e1", backendNodeId: 42, role: "button", name: "发布", line: 1 }],
      ),
      hint: { geometry: { rect: { x: 10, y: 20, w: 100, h: 30 }, tag: "button" } },
    });
    expect(target).toEqual({ ref: "e1", role: "button", name: "发布" });
  });
  it("uses frame id with backend node id so sibling frames cannot collide", () => {
    const target = matchObservationTarget({
      observation: observation(
        [node(42, "left"), node(42, "right")],
        [
          { ref: "e1", backendNodeId: 42, frameId: "left", line: 1 },
          { ref: "e2", backendNodeId: 42, frameId: "right", line: 2 },
        ],
      ),
      hint: {
        frameId: "right",
        geometry: { rect: { x: 10, y: 20, w: 100, h: 30 }, tag: "button" },
      },
    });
    expect(target.ref).toBe("e2");
  });
  it("matches iframe capture geometry in the child viewport coordinate space", () => {
    const child = node(42, "child", 410);
    child.localRect = { x: 10, y: 20, w: 100, h: 30 };
    const target = matchObservationTarget({
      observation: observation(
        [child],
        [{ ref: "e1", backendNodeId: 42, frameId: "child", line: 1 }],
      ),
      hint: {
        frameId: "child",
        geometrySpace: "local",
        geometry: { rect: { x: 10, y: 20, w: 100, h: 30 }, tag: "button" },
      },
    });
    expect(target.ref).toBe("e1");
  });
  it("restricts a missing frame hint to the root frame", () => {
    const target = matchObservationTarget({
      observation: observation(
        [node(42, "child")],
        [{ ref: "e1", backendNodeId: 42, frameId: "child", line: 1 }],
      ),
      hint: { geometry: { rect: { x: 10, y: 20, w: 100, h: 30 }, tag: "button" } },
      fallback: { tag: "button", name: "发布" },
    });
    expect(target).toEqual({ name: "发布", unmatched: true });
  });
  it("fails closed when the source Document has no VOM frame mapping", () => {
    const target = matchObservationTarget({
      observation: observation(
        [node(42, "root")],
        [{ ref: "e1", backendNodeId: 42, role: "button", name: "发布", line: 1 }],
      ),
      hint: {
        frameId: null,
        geometry: { rect: { x: 10, y: 20, w: 100, h: 30 }, tag: "button" },
      },
      fallback: { tag: "button", role: "button", name: "发布" },
    });
    expect(target).toEqual({ role: "button", name: "发布", unmatched: true });
  });
  it("returns unmatched for ambiguous geometry", () => {
    const target = matchObservationTarget({
      observation: observation(
        [node(42, "root"), node(43, "root")],
        [
          { ref: "e1", backendNodeId: 42, line: 1 },
          { ref: "e2", backendNodeId: 43, line: 2 },
        ],
      ),
      hint: { geometry: { rect: { x: 10, y: 20, w: 100, h: 30 }, tag: "button" } },
    });
    expect(target.unmatched).toBe(true);
  });
  it("uses semantics when geometry is unavailable without crossing frame boundaries", () => {
    const target = matchObservationTarget({
      observation: observation(
        [node(41, "root"), node(42, "child")],
        [
          { ref: "e1", backendNodeId: 41, role: "button", name: "保存", line: 1 },
          { ref: "e2", backendNodeId: 42, frameId: "child", role: "button", name: "保存", line: 2 },
        ],
      ),
      hint: { frameId: "child" },
      fallback: { tag: "button", role: "button", name: "保存" },
    });
    expect(target.ref).toBe("e2");
  });
  it("uses semantics to disambiguate equal geometry in one frame", () => {
    const target = matchObservationTarget({
      observation: observation(
        [node(42, "root"), node(43, "root")],
        [
          { ref: "e1", backendNodeId: 42, role: "button", name: "保存", line: 1 },
          { ref: "e2", backendNodeId: 43, role: "button", name: "取消", line: 2 },
        ],
      ),
      hint: { geometry: { rect: { x: 10, y: 20, w: 100, h: 30 }, tag: "button" } },
      fallback: { tag: "button", role: "button", name: "取消" },
    });
    expect(target.ref).toBe("e2");
  });
 });
@@ -1,132 +0,0 @@
 import { describe, expect, it } from "vitest";
 import { TRACE_VERSION_V3, VOM_FORMAT_VERSION } from "@/transport/types";
 import { RecordingStateRegistry } from "../recording/state-registry";
 import { buildTraceV3 } from "../recording/trace-builder-v3";
 import { reduceTraceStepsV3 } from "../recording/trace-reducer-v3";
 import type { RecordingDraftStep } from "../recording/types";
 describe("trace reducer v3", () => {
  it("removes form literals when value redaction is requested", () => {
    const reduced = reduceTraceStepsV3(
      [
        {
          op: "fill",
          value: "private@example.com",
          preStateId: "s1",
          postStateId: "s1",
        },
        {
          op: "select",
          values: ["private-account-id"],
          labels: ["Private account"],
          preStateId: "s1",
          postStateId: "s1",
        },
      ],
      { redactValues: true },
    );
    expect(reduced.steps[0]).toMatchObject({ op: "fill", value: "***", redacted: true });
    expect(reduced.steps[1]).toMatchObject({ op: "select" });
    expect(reduced.steps[1]).not.toHaveProperty("selection");
    expect(JSON.stringify(reduced.steps)).not.toContain("private@example.com");
    expect(JSON.stringify(reduced.steps)).not.toContain("private-account-id");
  });
  it("emits tab transitions only for callers that advertised support", () => {
    const drafts: RecordingDraftStep[] = [
      {
        op: "switch_tab",
        preStateId: "s1",
        postStateId: "s2",
      },
    ];
    expect(reduceTraceStepsV3(drafts).steps).toEqual([]);
    expect(reduceTraceStepsV3(drafts, { includeTabSwitches: true }).steps).toEqual([
      { op: "switch_tab", id: 1, state: "s1", result: { state: "s2" } },
    ]);
  });
  it("keeps hover steps before menu clicks", () => {
    const drafts: RecordingDraftStep[] = [
      {
        op: "hover",
        captureTarget: { tag: "span", role: "button", name: "Account" },
        preStateId: "s1",
        postStateId: "s1",
      },
      {
        op: "click",
        captureTarget: { tag: "a", role: "link", name: "Profile" },
        preStateId: "s1",
        postStateId: "s1",
      },
    ];
    expect(reduceTraceStepsV3(drafts).steps.map((s) => s.op)).toEqual(["hover", "click"]);
  });
  it("does not export a tab transition without both observation endpoints", () => {
    const sourceOnly: RecordingDraftStep = { op: "switch_tab", preStateId: "s1" };
    const targetOnly: RecordingDraftStep = { op: "switch_tab", postStateId: "s2" };
    expect(
      reduceTraceStepsV3([sourceOnly, targetOnly], { includeTabSwitches: true }).steps,
    ).toEqual([]);
  });
  it("collapses redirect hops while retaining draft-to-step identity", () => {
    const drafts: RecordingDraftStep[] = [
      { op: "navigate", url: "https://example.com/start", preStateId: "s1", postStateId: "s2" },
      {
        op: "navigate",
        url: "https://example.com/final",
        transitionQualifiers: ["server_redirect"],
        preStateId: "s2",
        postStateId: "s3",
      },
    ];
    const before = structuredClone(drafts);
    const reduced = reduceTraceStepsV3(drafts);
    expect(drafts).toEqual(before);
    expect(reduced.steps).toEqual([
      expect.objectContaining({
        id: 1,
        op: "navigate",
        state: "s1",
        to: "https://example.com/final",
        result: { state: "s3" },
      }),
    ]);
    expect(reduced.stepIdByDraftId.get(1)).toBe(1);
    expect(reduced.stepIdByDraftId.get(2)).toBe(1);
  });
  it("builds the wire model from protocol constants", () => {
    const registry = new RecordingStateRegistry();
    const state = registry.register({ url: "https://example.com", vomText: "@vom 1" });
    const trace = buildTraceV3({
      registry,
      drafts: [
        {
          op: "click",
          captureTarget: { tag: "button", role: "button", name: "Save" },
          preStateId: state.id,
          postStateId: state.id,
        },
      ],
      startedAt: "2026-08-12T00:00:00.000Z",
      stoppedBy: "user_finish",
      bskVersion: "test",
    });
    expect(trace.version).toBe(TRACE_VERSION_V3);
    expect(trace.recorder.vom).toBe(VOM_FORMAT_VERSION);
    expect(trace.steps[0]).toMatchObject({
      op: "click",
      target: { role: "button", name: "Save", unmatched: true },
    });
  });
 });
@@ -1,15 +1,6 @@
 import { describe, expect, it } from "vitest";
-import type { RecordingDraftStep } from "@/lib/recording/types";
+import type { DraftTraceStep } from "@/transport/types";
-import { shouldRecordPress } from "../recording/draft-policy";
+import { reduceTraceSteps, resolveTraceStartUrl, shouldRecordPress } from "../trace-reducer";
 import { buildTraceV2 } from "../recording/trace-reducer-v2";
 function reduceTraceSteps(steps: RecordingDraftStep[], startUrl?: string) {
  return buildTraceV2({
    steps,
    startedAt: "2026-01-01T00:00:00.000Z",
    ...(startUrl ? { startUrl } : {}),
  });
 }
 describe("shouldRecordPress", () => {
  it("keeps Enter and Escape", () => {
@@ -27,47 +18,36 @@ describe("shouldRecordPress", () => {
 });
 describe("reduceTraceSteps", () => {
  it("does not expose internal tab transitions in trace v2", () => {
    const trace = reduceTraceSteps([
      {
        op: "switch_tab",
        preStateId: "s1",
        postStateId: "s2",
      },
    ]);
    expect(trace.steps).toEqual([]);
  });
  it("builds steps with pages dictionary and page id references", () => {
-    const drafts: RecordingDraftStep[] = [
+    const drafts: DraftTraceStep[] = [
      {
        op: "navigate",
        url: "https://example.com/search?q=hello&utm_source=x",
-        pageUrl: "https://example.com/search?q=hello&utm_source=x",
+        page_url: "https://example.com/search?q=hello&utm_source=x",
      },
      {
        op: "fill",
-        captureTarget: { tag: "input", role: "textbox", name: "搜索", name_attr: "q" },
+        target: { tag: "input", role: "textbox", name: "搜索", name_attr: "q" },
        value: "browser skill",
-        pageUrl: "https://example.com/search?q=hello&utm_source=x",
+        page_url: "https://example.com/search?q=hello&utm_source=x",
      },
      {
        op: "press",
        key: "Enter",
-        captureTarget: { tag: "input", role: "textbox", name: "搜索", name_attr: "q" },
+        target: { tag: "input", role: "textbox", name: "搜索", name_attr: "q" },
-        navigatedTo: "https://example.com/results/42",
+        navigated_to: "https://example.com/results/42",
-        pageUrl: "https://example.com/search?q=hello&utm_source=x",
+        page_url: "https://example.com/search?q=hello&utm_source=x",
      },
      {
        op: "click",
-        captureTarget: { tag: "button", role: "button", name: "发布" },
+        target: { tag: "button", role: "button", name: "发布" },
-        navigatedTo: "https://example.com/p/99",
+        navigated_to: "https://example.com/p/99",
-        pageUrl: "https://example.com/results/42",
+        page_url: "https://example.com/results/42",
      },
      {
        op: "press",
        key: "a",
-        pageUrl: "https://example.com/p/99",
+        page_url: "https://example.com/p/99",
      },
    ];
@@ -129,9 +109,9 @@ describe("reduceTraceSteps", () => {
      [
        {
          op: "fill",
-          captureTarget: { tag: "input", role: "textbox", name: "Search query" },
+          target: { tag: "input", role: "textbox", name: "Search query" },
          value: "",
-          pageUrl: "https://example.com/search",
+          page_url: "https://example.com/search",
        },
      ],
      "https://example.com/search",
@@ -145,16 +125,16 @@ describe("reduceTraceSteps", () => {
    ]);
  });
-  it("maps select navigatedTo onto effect.navigatedTo (page id)", () => {
+  it("maps select navigated_to onto effect.navigated_to (page id)", () => {
    const { pages, steps } = reduceTraceSteps(
      [
        {
          op: "select",
-          captureTarget: { tag: "select", role: "combobox", name: "分类" },
+          target: { tag: "select", role: "combobox", name: "分类" },
          values: ["tech"],
          labels: ["技术"],
-          navigatedTo: "https://example.com/list?cat=tech",
+          navigated_to: "https://example.com/list?cat=tech",
-          pageUrl: "https://example.com/list",
+          page_url: "https://example.com/list",
        },
      ],
      "https://example.com/list",
@@ -171,32 +151,36 @@ describe("reduceTraceSteps", () => {
    });
  });
-  it("drops hover steps, which only exist in trace v3", () => {
+  it("keeps hover steps before menu clicks", () => {
    const { steps } = reduceTraceSteps(
      [
        {
          op: "hover",
-          captureTarget: { tag: "span", role: "button", name: "Account" },
+          target: { tag: "span", role: "button", name: "Account" },
-          pageUrl: "https://example.com/app",
+          page_url: "https://example.com/app",
        },
        {
          op: "click",
-          captureTarget: { tag: "a", role: "link", name: "Profile" },
+          target: { tag: "a", role: "link", name: "Profile" },
-          pageUrl: "https://example.com/app",
+          page_url: "https://example.com/app",
        },
      ],
      "https://example.com/app",
    );
-    expect(steps.map((s) => s.op)).toEqual(["click"]);
+    expect(steps.map((s) => s.op)).toEqual(["hover", "click"]);
    expect(steps[0]).toMatchObject({
      op: "hover",
      page: "p1",
      target: { name: "Account" },
    });
  });
  it("resolveTraceStartUrl prefers explicit start URL", () => {
    expect(
-      buildTraceV2({
+      resolveTraceStartUrl(
-        steps: [{ op: "navigate", url: "https://example.com/other" }],
+        [{ op: "navigate", url: "https://example.com/other" }],
-        startedAt: "2026-01-01T00:00:00.000Z",
+        "https://example.com/start",
-        startUrl: "https://example.com/start",
+      ),
      }).entry.start_url,
    ).toBe("https://example.com/start");
  });
 });
@@ -1,9 +1,9 @@
 /**
- * Wire protocol and background-side helper for temporarily excluding the
+ * Wire protocol and background-side helper for hiding the extension's
- * extension's in-page overlay. Screenshots use it to avoid captured chrome;
+ * in-page overlay while a screenshot is captured, so captured frames only
- * coordinate-driven native input uses it so Chrome hit-tests the page.
+ * contain the page itself.
 *
- * The background wraps each bounded operation in `withExtensionOverlayHidden`,
+ * The background wraps every capture in `withOverlaysHiddenForCapture`,
 * which sends `begin` (the content script hides the overlay host and only
 * acks once the compositor has produced an overlay-free frame) and always
 * follows up with `end`, even when the capture throws. Tabs without the
@@ -46,7 +46,7 @@ const defaultSendToTab: CaptureSuppressSendToTab = (tabId, message) =>
 * (or any other `begin` failure) simply skips suppression — there is no
 * overlay to hide in that tab.
 */
-export async function withExtensionOverlayHidden<T>(
+export async function withOverlaysHiddenForCapture<T>(
  tabId: number,
  fn: () => Promise<T>,
  sendToTab: CaptureSuppressSendToTab = defaultSendToTab,
@@ -1,13 +1,12 @@
 /**
- * Build a semantic capture descriptor for an interacted element.
+ * Build a semantic TargetDescriptor for an interacted element.
 *
 * Trace steps are an LLM *textbook*: each click must say what to look for
 * on screen (usually a short visible name). Tag-only noise like
 * `{ "tag": "div" }` / “点击div” is useless and must not be recorded.
 */
-/** Content-script capture descriptor before VOM geometric matching. */
+export interface TargetDescriptor {
 export interface CaptureTargetDescriptor {
  role?: string;
  name?: string;
  tag: string;
@@ -248,7 +247,7 @@ export function resolveHoverElement(target: Element): Element | null {
 * (visible name), or at least a form `name_attr` for checkbox/radio.
 * Recording “点击div” with no name fails this bar.
 */
-export function isMeaningfulClickTarget(target: CaptureTargetDescriptor): boolean {
+export function isMeaningfulClickTarget(target: TargetDescriptor): boolean {
  const name = target.name?.trim();
  if (name && isActionableLabel(name)) return true;
  if (
@@ -324,7 +323,7 @@ function nearbyLabelText(el: Element): string | undefined {
  return undefined;
 }
-export function describeTarget(el: Element): CaptureTargetDescriptor {
+export function describeTarget(el: Element): TargetDescriptor {
  const tag = el.tagName.toLowerCase();
  const role = inferRole(el);
  const name = accessibleName(el);
@@ -351,7 +350,7 @@ export function describeTarget(el: Element): CaptureTargetDescriptor {
  };
 }
-export function describeEventTarget(target: EventTarget | null): CaptureTargetDescriptor | null {
+export function describeEventTarget(target: EventTarget | null): TargetDescriptor | null {
  if (!(target instanceof Element)) return null;
  const clickable = resolveClickableElement(target);
  if (!clickable) return null;
@@ -3,10 +3,8 @@
 * between the content-script control overlay and the background SW.
 *
 * Content script → background:
- *  - `{ kind: "overlay.ready" }` → background decides the per-tab state first
+ *  - `{ kind: "overlay.ready" }` → background replies with the authoritative
- *      (see overlayStateForTab) and pushes the authoritative overlay state for
+ *      overlay state for the sender's window.
 *      that tab. It also proactively pushes on tab create and control-mode
 *      change, so a tab usually receives state before it ever sends ready.
 *  - `{ kind: "overlay.interrupt", sessionId }` → background asks the
 *      daemon (via a `session.user_interrupt` WS event) to cancel
 *      every inflight + queued tool call for that session with
@@ -1,26 +0,0 @@
 /**
 * Generate a UUID v4 in browser contexts where randomUUID() is unavailable.
 *
 * Crypto.randomUUID() is restricted to secure contexts, while
 * crypto.getRandomValues() is available to content scripts on ordinary HTTP
 * origins. BrowserSkill records many intranet pages served over HTTP, so the
 * fallback is required for recording to work on those pages.
 */
 export function createRandomUuid(): string {
  const cryptoApi = globalThis.crypto;
  if (typeof cryptoApi.randomUUID === "function") return cryptoApi.randomUUID();
  const bytes = new Uint8Array(16);
  cryptoApi.getRandomValues(bytes);
  bytes[6] = (bytes[6]! & 0x0f) | 0x40;
  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
  return [
    hex.slice(0, 8),
    hex.slice(8, 12),
    hex.slice(12, 16),
    hex.slice(16, 20),
    hex.slice(20),
  ].join("-");
 }
@@ -3,7 +3,7 @@
 * service worker and a tab's content script.
 */
-import type { CaptureTargetDescriptor } from "./describe-target";
+import type { TargetDescriptor } from "./describe-target";
 export const RECORD_START = "bsk-record-start";
 export const RECORD_STEP = "bsk-record-step";
@@ -16,10 +16,6 @@ export interface RecordStartAck {
  ok: true;
 }
 export type RecordStepAck =
  | { ok: true; sequence: number }
  | { ok: false; expectedSequence: number; error: string };
 export type RecordStopAck = { ok: true } | { ok: false; error: string };
 export interface RecordQueryMessage {
@@ -46,7 +42,7 @@ export interface RecordStartMessage {
 export interface RecordStepPayload {
  op: "click" | "hover" | "fill" | "press" | "select" | "navigate";
-  target?: CaptureTargetDescriptor;
+  target?: TargetDescriptor;
  value?: string;
  key?: string;
  modifiers?: Array<"alt" | "ctrl" | "meta" | "shift">;
@@ -54,30 +50,17 @@ export interface RecordStepPayload {
  labels?: string[];
  url?: string;
  redacted?: boolean;
  commit?: "enter" | "suggestion" | "blur";
  /** Page URL when the step was captured. */
  page_url?: string;
  /** Event-target bounds in the source frame's viewport coordinate space. */
  geometry?: {
    rect: { x: number; y: number; w: number; h: number };
    tag: string;
  };
  /** Capture-only hint; never persisted unless converted to navigated_to. */
  expects_navigation?: boolean;
  /** Whether an observed URL change was synchronously caused by the action. */
  navigation_caused_by_action?: boolean;
  /** Raw webNavigation transition metadata for cause mapping. */
  transitionType?: string;
  transitionQualifiers?: string[];
 }
 export interface RecordStepMessage {
  type: typeof RECORD_STEP;
  requestId: string;
  /** Stable for the lifetime of one content-script document. */
  producerId: string;
  /** Monotonic within one content-script producer and recording request. */
  sequence: number;
  step: RecordStepPayload;
 }
@@ -129,27 +112,8 @@ export function isRecordQueryMessage(msg: unknown): msg is RecordQueryMessage {
 export function isRecordStepMessage(msg: unknown): msg is RecordStepMessage {
  if (typeof msg !== "object" || msg === null) return false;
  const m = msg as Record<string, unknown>;
-  if (
+  if (m.type !== RECORD_STEP || typeof m.requestId !== "string") return false;
    m.type !== RECORD_STEP ||
    typeof m.requestId !== "string" ||
    typeof m.producerId !== "string" ||
    m.producerId.length === 0 ||
    typeof m.sequence !== "number" ||
    !Number.isSafeInteger(m.sequence) ||
    m.sequence < 1
  ) {
    return false;
  }
  const step = m.step;
  if (typeof step !== "object" || step === null) return false;
  return typeof (step as RecordStepPayload).op === "string";
 }
 export function isAcceptedRecordStepAck(
  value: unknown,
  sequence: number,
 ): value is Extract<RecordStepAck, { ok: true }> {
  if (typeof value !== "object" || value === null) return false;
  const ack = value as Partial<RecordStepAck>;
  return ack.ok === true && ack.sequence === sequence;
 }
@@ -0,0 +1,136 @@
 import type { DraftTraceStep } from "@/transport/types";
 import type { RecordStepPayload } from "./record-bridge";
 export interface RecordingStepBuffer {
  steps: DraftTraceStep[];
  currentUrl?: string;
  pendingNavigation: boolean;
  pendingNavigationDeadline?: number;
 }
 const NAVIGATION_TRIGGER_WINDOW_MS = 3_000;
 function toDraftStep(payload: RecordStepPayload): DraftTraceStep | null {
  const pageUrl = payload.page_url;
  switch (payload.op) {
    case "click":
      return payload.target
        ? {
            op: "click",
            target: payload.target,
            ...(pageUrl ? { page_url: pageUrl } : {}),
          }
        : null;
    case "hover":
      return payload.target
        ? {
            op: "hover",
            target: payload.target,
            ...(pageUrl ? { page_url: pageUrl } : {}),
          }
        : null;
    case "fill":
      return payload.target
        ? {
            op: "fill",
            target: payload.target,
            value: payload.value ?? "",
            ...(payload.redacted ? { redacted: true } : {}),
            ...(pageUrl ? { page_url: pageUrl } : {}),
          }
        : null;
    case "press":
      return payload.key
        ? {
            op: "press",
            key: payload.key,
            ...(payload.target ? { target: payload.target } : {}),
            ...(payload.modifiers?.length ? { modifiers: payload.modifiers } : {}),
            ...(pageUrl ? { page_url: pageUrl } : {}),
          }
        : null;
    case "select":
      return payload.target && payload.values
        ? {
            op: "select",
            target: payload.target,
            values: payload.values,
            ...(payload.labels?.length ? { labels: payload.labels } : {}),
            ...(pageUrl ? { page_url: pageUrl } : {}),
          }
        : null;
    case "navigate":
      return null;
  }
 }
 function annotateLastStepNavigation(buffer: RecordingStepBuffer, url: string): boolean {
  for (let i = buffer.steps.length - 1; i >= 0; i -= 1) {
    const step = buffer.steps[i];
    if (!step) continue;
    if (step.op === "click" || step.op === "press" || step.op === "select") {
      buffer.steps[i] = { ...step, navigated_to: url };
      return true;
    }
    break;
  }
  return false;
 }
 export function observeRecordedNavigation(
  buffer: RecordingStepBuffer,
  url: string,
  causedByAction?: boolean,
 ): void {
  if (!url || url === buffer.currentUrl) return;
  buffer.currentUrl = url;
  const pendingIsCurrent =
    buffer.pendingNavigation &&
    (buffer.pendingNavigationDeadline === undefined ||
      buffer.pendingNavigationDeadline >= Date.now());
  if (causedByAction === true || (causedByAction === undefined && pendingIsCurrent)) {
    buffer.pendingNavigation = false;
    buffer.pendingNavigationDeadline = undefined;
    if (!annotateLastStepNavigation(buffer, url)) {
      buffer.steps.push({
        op: "navigate",
        url,
        page_url: url,
      });
    }
    return;
  }
  buffer.pendingNavigation = false;
  buffer.pendingNavigationDeadline = undefined;
  buffer.steps.push({
    op: "navigate",
    url,
    page_url: url,
  });
 }
 export function appendRecordedPayload(
  buffer: RecordingStepBuffer,
  payload: RecordStepPayload,
 ): void {
  if (payload.op === "navigate") {
    if (payload.url) {
      observeRecordedNavigation(buffer, payload.url, payload.navigation_caused_by_action);
    }
    return;
  }
  const step = toDraftStep({
    ...payload,
    page_url: payload.page_url ?? buffer.currentUrl,
  });
  if (!step) return;
  buffer.steps.push(step);
  if (step.op === "click" || step.op === "press" || step.op === "select" || step.op === "fill") {
    buffer.pendingNavigation = payload.expects_navigation === true;
    buffer.pendingNavigationDeadline = buffer.pendingNavigation
      ? Date.now() + NAVIGATION_TRIGGER_WINDOW_MS
      : undefined;
  }
 }
@@ -1,39 +0,0 @@
 import {
  RECORD_DOCUMENT_ATTRIBUTE,
  recordingDocumentMarkerValue,
 } from "@/shared/recording-document-identity";
 export interface RecordingDocumentMarker {
  restore(): void;
  ensure(): void;
 }
 export function waitForDocumentElement(): Promise<HTMLElement> {
  if (document.documentElement) return Promise.resolve(document.documentElement);
  return new Promise((resolve) => {
    const observer = new MutationObserver(() => {
      if (!document.documentElement) return;
      observer.disconnect();
      resolve(document.documentElement);
    });
    observer.observe(document, { childList: true });
  });
 }
 export function markRecordingDocument(
  producerId: string,
  root: HTMLElement = document.documentElement,
 ): RecordingDocumentMarker {
  const previous = root.getAttribute(RECORD_DOCUMENT_ATTRIBUTE);
  const markerValue = recordingDocumentMarkerValue(producerId);
  const ensure = () => root.setAttribute(RECORD_DOCUMENT_ATTRIBUTE, markerValue);
  ensure();
  return {
    ensure,
    restore() {
      if (root.getAttribute(RECORD_DOCUMENT_ATTRIBUTE) !== markerValue) return;
      if (previous === null) root.removeAttribute(RECORD_DOCUMENT_ATTRIBUTE);
      else root.setAttribute(RECORD_DOCUMENT_ATTRIBUTE, previous);
    },
  };
 }
@@ -1,134 +0,0 @@
 import type { CdpTarget } from "@/browser-driver/frame-graph";
 import { type CdpRunner, sendToCdpTarget } from "@/tools/shared";
 const SETTLE_MIN_MS = 150;
 const SETTLE_QUIET_MS = 250;
 const SETTLE_MAX_MS = 2_000;
 const SETTLE_POLL_MS = 60;
 const SETTLE_WORLD_NAME = "__bsk_record_settle__";
 const QUIET_PROBE = `(() => {
  const scope = window;
  let probe = scope.__bskRecordQuiet;
  if (!probe) {
    probe = { changedAt: Date.now() };
    const observer = new MutationObserver(() => {
      probe.changedAt = Date.now();
    });
    observer.observe(document.documentElement, {
      subtree: true,
      childList: true,
      attributes: true,
      characterData: true,
    });
    scope.__bskRecordQuiet = probe;
  }
  return { idleMs: Date.now() - probe.changedAt, readyState: document.readyState };
 })()`;
 export interface DocumentSettleScope {
  target: CdpTarget;
  /** Omit only for the target's root document. */
  frameId?: string;
 }
 type SettleOutcome = "quiet" | "timeout" | "cancelled";
 interface QuietProbe {
  idleMs: number;
  readyState: string;
 }
 interface ProbeContext {
  executionContextId?: number;
 }
 function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  return new Promise((resolve) => {
    if (signal?.aborted) return resolve();
    const timer = setTimeout(resolve, ms);
    signal?.addEventListener(
      "abort",
      () => {
        clearTimeout(timer);
        resolve();
      },
      { once: true },
    );
  });
 }
 async function executionContextForScope(
  cdp: CdpRunner,
  scope: DocumentSettleScope,
 ): Promise<number | undefined> {
  if (!scope.frameId) return undefined;
  const result = await sendToCdpTarget<{ executionContextId?: number }>(
    cdp,
    scope.target,
    "Page.createIsolatedWorld",
    {
      frameId: scope.frameId,
      worldName: SETTLE_WORLD_NAME,
      grantUniveralAccess: false,
    },
  );
  return result.executionContextId;
 }
 async function readQuietProbe(
  cdp: CdpRunner,
  scope: DocumentSettleScope,
  context: ProbeContext,
 ): Promise<QuietProbe | null> {
  try {
    if (scope.frameId && context.executionContextId === undefined) {
      context.executionContextId = await executionContextForScope(cdp, scope);
      if (context.executionContextId === undefined) return null;
    }
    const reply = await sendToCdpTarget<{ result?: { value?: unknown } }>(
      cdp,
      scope.target,
      "Runtime.evaluate",
      {
        expression: QUIET_PROBE,
        returnByValue: true,
        ...(context.executionContextId !== undefined
          ? { contextId: context.executionContextId }
          : {}),
      },
    );
    const value = reply.result?.value;
    if (!value || typeof value !== "object") return null;
    const { idleMs, readyState } = value as { idleMs?: unknown; readyState?: unknown };
    if (typeof idleMs !== "number" || typeof readyState !== "string") return null;
    return { idleMs, readyState };
  } catch {
    context.executionContextId = undefined;
    return null;
  }
 }
 export async function waitForDocumentSettled(
  cdp: CdpRunner,
  scope: DocumentSettleScope,
  options: { signal?: AbortSignal } = {},
 ): Promise<SettleOutcome> {
  const startedAt = Date.now();
  const floor = startedAt + SETTLE_MIN_MS;
  const deadline = startedAt + SETTLE_MAX_MS;
  const context: ProbeContext = {};
  for (;;) {
    if (options.signal?.aborted) return "cancelled";
    await sleep(SETTLE_POLL_MS, options.signal);
    if (options.signal?.aborted) return "cancelled";
    const probe = await readQuietProbe(cdp, scope, context);
    const now = Date.now();
    if (now < floor) continue;
    if (now >= deadline) return "timeout";
    if (!probe || probe.readyState === "loading") continue;
    if (probe.idleMs >= SETTLE_QUIET_MS) return "quiet";
  }
 }
@@ -1,34 +0,0 @@
 import type { RecordingDraftStep } from "./types";
 const CLIPBOARD_KEYS = new Set(["a", "c", "v", "x", "A", "C", "V", "X"]);
 const MODIFIER_ONLY_KEYS = new Set(["Meta", "Control", "Alt", "Shift", "OS", "Hyper", "Super"]);
 export function shouldRecordPress(
  key: string,
  modifiers?: Array<"alt" | "ctrl" | "meta" | "shift">,
 ): boolean {
  if (MODIFIER_ONLY_KEYS.has(key)) return false;
  const mods = modifiers ?? [];
  const hasCtrlOrMeta = mods.includes("ctrl") || mods.includes("meta");
  if (hasCtrlOrMeta && CLIPBOARD_KEYS.has(key)) return false;
  if (key === "Enter" || key === "Escape") return true;
  if (key.length === 1 && !hasCtrlOrMeta && !mods.includes("alt")) return false;
  return false;
 }
 export function shouldIncludeDraft(step: RecordingDraftStep): boolean {
  return step.op !== "press" || shouldRecordPress(step.key, step.modifiers);
 }
 export function resolveDraftStartUrl(
  drafts: RecordingDraftStep[],
  explicitStartUrl?: string,
  fallbackUrl?: string,
 ): string {
  if (explicitStartUrl) return explicitStartUrl;
  const navigation = drafts.find(
    (step): step is Extract<RecordingDraftStep, { op: "navigate" }> => step.op === "navigate",
  );
  if (navigation) return navigation.url;
  return drafts.find((step) => step.pageUrl)?.pageUrl ?? fallbackUrl ?? "about:blank";
 }
@@ -1,65 +0,0 @@
 export const RECORD_FRAME_PORT = "bsk-record-frame";
 export const RECORD_FRAME_QUERY = "bsk-record-frame-query";
 export const RECORD_FRAME_START = "bsk-record-frame-start";
 export interface RecordFrameQueryMessage {
  type: typeof RECORD_FRAME_QUERY;
 }
 export interface RecordFrameQueryResponse {
  active: boolean;
  requestId?: string;
  startedAtMs?: number;
 }
 export interface RecordFrameStartMessage {
  type: typeof RECORD_FRAME_START;
  requestId: string;
  startedAtMs: number;
 }
 export type RecordFramePortMessage =
  | {
      type: "ready";
      requestId: string;
      producerId: string;
    }
  | {
      type: "ready_ack";
      requestId: string;
      producerId: string;
    }
  | {
      type: "stop";
      requestId: string;
      commandId: string;
    }
  | {
      type: "cancel";
      requestId: string;
    }
  | {
      type: "stopped";
      requestId: string;
      commandId: string;
      ok: boolean;
      error?: string;
    };
 export function isRecordFrameQueryMessage(value: unknown): value is RecordFrameQueryMessage {
  return (
    typeof value === "object" &&
    value !== null &&
    (value as { type?: unknown }).type === RECORD_FRAME_QUERY
  );
 }
 export function isRecordFrameStartMessage(value: unknown): value is RecordFrameStartMessage {
  if (typeof value !== "object" || value === null) return false;
  const message = value as Partial<RecordFrameStartMessage>;
  return (
    message.type === RECORD_FRAME_START &&
    typeof message.requestId === "string" &&
    typeof message.startedAtMs === "number"
  );
 }
@@ -1,400 +0,0 @@
 import { createRandomUuid } from "../random-uuid";
 import {
  isRecordFrameQueryMessage,
  RECORD_FRAME_PORT,
  RECORD_FRAME_START,
  type RecordFramePortMessage,
  type RecordFrameQueryResponse,
  type RecordFrameStartMessage,
 } from "./frame-bridge";
 export interface RecordingCaptureScope {
  tabId: number;
  documentId: string;
  browserFrameId: number;
  producerId: string;
 }
 interface ArmedRecording {
  requestId: string;
  startedAtMs: number;
  tabIds: Set<number>;
  agents: Map<string, FrameAgent>;
  onDocumentReady?: (scope: RecordingCaptureScope) => void | Promise<void>;
  finishing: boolean;
 }
 interface FrameAgent extends RecordingCaptureScope {
  requestId: string;
  port: chrome.runtime.Port;
  stopWaiters: Map<string, (ok: boolean) => void>;
 }
 interface BrowserFrame {
  frameId: number;
  documentId?: string;
 }
 interface BrowserFrameNavigation extends BrowserFrame {
  tabId: number;
  lifecycle: "committed" | "completed";
 }
 const RECORD_FRAME_STOP_TIMEOUT_MS = 5_000;
 export interface RecordFrameCoordinatorDeps {
  getAllFrames(tabId: number): Promise<BrowserFrame[]>;
  sendToDocument(
    tabId: number,
    message: RecordFrameStartMessage,
    target: { documentId?: string; frameId?: number },
  ): Promise<unknown>;
  subscribeFrameNavigation?(listener: (frame: BrowserFrameNavigation) => void): () => void;
 }
 function documentKey(tabId: number, documentId: string): string {
  return `${tabId}:${documentId}`;
 }
 function senderAddress(
  sender: chrome.runtime.MessageSender,
 ): { tabId: number; documentId: string; browserFrameId: number } | null {
  const tabId = sender.tab?.id;
  const documentId = sender.documentId;
  const browserFrameId = sender.frameId;
  if (
    typeof tabId !== "number" ||
    typeof documentId !== "string" ||
    typeof browserFrameId !== "number"
  ) {
    return null;
  }
  return { tabId, documentId, browserFrameId };
 }
 function defaultDeps(): RecordFrameCoordinatorDeps {
  return {
    async getAllFrames(tabId) {
      return (await chrome.webNavigation.getAllFrames({ tabId })) ?? [];
    },
    sendToDocument(tabId, message, target) {
      return chrome.tabs.sendMessage(tabId, message, target);
    },
    subscribeFrameNavigation(listener) {
      const onCommitted = (details: chrome.webNavigation.WebNavigationTransitionCallbackDetails) =>
        listener({ ...details, lifecycle: "committed" });
      const onCompleted = (details: chrome.webNavigation.WebNavigationFramedCallbackDetails) =>
        listener({ ...details, lifecycle: "completed" });
      chrome.webNavigation.onCommitted.addListener(onCommitted);
      chrome.webNavigation.onCompleted.addListener(onCompleted);
      return () => {
        chrome.webNavigation.onCommitted.removeListener(onCommitted);
        chrome.webNavigation.onCompleted.removeListener(onCompleted);
      };
    },
  };
 }
 export class RecordFrameCoordinator {
  readonly #deps: RecordFrameCoordinatorDeps;
  readonly #recordings = new Map<string, ArmedRecording>();
  #attached = false;
  #detachFrameNavigation: (() => void) | null = null;
  constructor(deps: RecordFrameCoordinatorDeps = defaultDeps()) {
    this.#deps = deps;
  }
  attach(): () => void {
    if (this.#attached) return () => {};
    this.#attached = true;
    chrome.runtime.onConnect.addListener(this.#onConnect);
    chrome.runtime.onMessage.addListener(this.#onMessage);
    this.#detachFrameNavigation =
      this.#deps.subscribeFrameNavigation?.(this.#onFrameNavigation) ?? null;
    return () => {
      if (!this.#attached) return;
      this.#attached = false;
      chrome.runtime.onConnect.removeListener(this.#onConnect);
      chrome.runtime.onMessage.removeListener(this.#onMessage);
      this.#detachFrameNavigation?.();
      this.#detachFrameNavigation = null;
      for (const recording of this.#recordings.values()) this.#cancelAgents(recording);
      this.#recordings.clear();
    };
  }
  begin(
    requestId: string,
    startedAtMs: number,
    initialTabId: number,
    onDocumentReady?: (scope: RecordingCaptureScope) => void | Promise<void>,
  ): void {
    const previous = this.#recordings.get(requestId);
    if (previous) this.#cancelAgents(previous);
    this.#recordings.set(requestId, {
      requestId,
      startedAtMs,
      // Register the initial tab before navigation begins. A newly-created
      // child document can query at document_start before armTab's frame
      // snapshot sees it, especially when Chromium promotes it to an OOPIF.
      tabIds: new Set([initialTabId]),
      agents: new Map(),
      ...(onDocumentReady ? { onDocumentReady } : {}),
      finishing: false,
    });
  }
  async armTab(requestId: string, tabId: number): Promise<boolean> {
    const recording = this.#recordings.get(requestId);
    if (!recording || recording.finishing) return false;
    recording.tabIds.add(tabId);
    let frames: BrowserFrame[];
    try {
      frames = await this.#deps.getAllFrames(tabId);
    } catch {
      frames = [{ frameId: 0 }];
    }
    if (!frames.some((frame) => frame.frameId === 0)) frames.unshift({ frameId: 0 });
    const results = await Promise.all(
      frames.map(async (frame) => {
        const started = await this.#startFrame(recording, tabId, frame);
        return { frameId: frame.frameId, started };
      }),
    );
    return results.some((result) => result.frameId === 0 && result.started);
  }
  sourceFor(
    requestId: string,
    producerId: string,
    sender: chrome.runtime.MessageSender,
  ): RecordingCaptureScope | null {
    const address = senderAddress(sender);
    const recording = this.#recordings.get(requestId);
    if (!address || !recording) return null;
    const agent = recording.agents.get(documentKey(address.tabId, address.documentId));
    if (!agent || agent.producerId !== producerId) return null;
    return {
      tabId: agent.tabId,
      documentId: agent.documentId,
      browserFrameId: agent.browserFrameId,
      producerId: agent.producerId,
    };
  }
  async stop(requestId: string): Promise<boolean> {
    const recording = this.#recordings.get(requestId);
    if (!recording) return true;
    recording.finishing = true;
    const commandId = createRandomUuid();
    const results = await Promise.all(
      [...recording.agents.values()].map((agent) => this.#stopAgent(agent, requestId, commandId)),
    );
    const succeeded = results.every(Boolean);
    if (succeeded) this.#recordings.delete(requestId);
    else recording.finishing = false;
    return succeeded;
  }
  cancel(requestId: string): void {
    const recording = this.#recordings.get(requestId);
    if (!recording) return;
    this.#cancelAgents(recording);
    this.#recordings.delete(requestId);
  }
  readonly #onMessage = (
    message: unknown,
    sender: chrome.runtime.MessageSender,
    sendResponse: (response: RecordFrameQueryResponse) => void,
  ): boolean => {
    if (!isRecordFrameQueryMessage(message)) return false;
    const tabId = sender.tab?.id;
    const recording =
      typeof tabId === "number"
        ? [...this.#recordings.values()].find(
            (candidate) => !candidate.finishing && candidate.tabIds.has(tabId),
          )
        : undefined;
    sendResponse(
      recording
        ? {
            active: true,
            requestId: recording.requestId,
            startedAtMs: recording.startedAtMs,
          }
        : { active: false },
    );
    return false;
  };
  readonly #onFrameNavigation = (frame: BrowserFrameNavigation): void => {
    if (frame.frameId === 0) return;
    for (const recording of this.#recordings.values()) {
      if (recording.finishing || !recording.tabIds.has(frame.tabId)) continue;
      // onCommitted can race document_start, while onCompleted runs after the
      // content script is available. Starting twice is safe and closes both
      // the early-query and late-SPA-frame gaps.
      void (async () => {
        const started = await this.#startFrame(recording, frame.tabId, frame);
        if (!started || frame.lifecycle !== "completed" || recording.finishing) return;
        const agent = frame.documentId
          ? recording.agents.get(documentKey(frame.tabId, frame.documentId))
          : [...recording.agents.values()].find(
              (candidate) =>
                candidate.tabId === frame.tabId && candidate.browserFrameId === frame.frameId,
            );
        if (!agent) return;
        await recording.onDocumentReady?.({
          tabId: agent.tabId,
          documentId: agent.documentId,
          browserFrameId: agent.browserFrameId,
          producerId: agent.producerId,
        });
      })();
    }
  };
  readonly #onConnect = (port: chrome.runtime.Port): void => {
    if (port.name !== RECORD_FRAME_PORT) return;
    const address = senderAddress(port.sender ?? {});
    if (!address) {
      port.disconnect();
      return;
    }
    let registered: FrameAgent | null = null;
    port.onMessage.addListener((raw: unknown) => {
      const message = raw as Partial<RecordFramePortMessage>;
      if (message.type === "ready") {
        if (typeof message.requestId !== "string" || typeof message.producerId !== "string") {
          port.disconnect();
          return;
        }
        const requestId = message.requestId;
        const producerId = message.producerId;
        if (registered) {
          if (registered.requestId === requestId && registered.producerId === producerId) {
            port.postMessage({
              type: "ready_ack",
              requestId,
              producerId,
            } satisfies RecordFramePortMessage);
          } else {
            port.disconnect();
          }
          return;
        }
        const recording = this.#recordings.get(requestId);
        if (
          !recording ||
          recording.finishing ||
          !recording.tabIds.has(address.tabId) ||
          producerId.length === 0
        ) {
          port.disconnect();
          return;
        }
        const agent: FrameAgent = {
          ...address,
          requestId,
          producerId,
          port,
          stopWaiters: new Map(),
        };
        registered = agent;
        const key = documentKey(address.tabId, address.documentId);
        const previous = recording.agents.get(key);
        if (previous && previous !== agent) previous.port.disconnect();
        recording.agents.set(key, agent);
        port.postMessage({
          type: "ready_ack",
          requestId,
          producerId,
        } satisfies RecordFramePortMessage);
        return;
      }
      if (
        message.type === "stopped" &&
        registered &&
        message.requestId === registered.requestId &&
        typeof message.commandId === "string"
      ) {
        registered.stopWaiters.get(message.commandId)?.(message.ok === true);
        registered.stopWaiters.delete(message.commandId);
      }
    });
    port.onDisconnect.addListener(() => {
      if (!registered) return;
      for (const resolve of registered.stopWaiters.values()) resolve(true);
      const recording = this.#recordings.get(registered.requestId);
      const key = documentKey(registered.tabId, registered.documentId);
      if (recording?.agents.get(key) === registered) recording.agents.delete(key);
    });
  };
  #stopAgent(agent: FrameAgent, requestId: string, commandId: string): Promise<boolean> {
    return new Promise((resolve) => {
      const timer = setTimeout(() => {
        agent.stopWaiters.delete(commandId);
        resolve(false);
      }, RECORD_FRAME_STOP_TIMEOUT_MS);
      agent.stopWaiters.set(commandId, (ok) => {
        clearTimeout(timer);
        resolve(ok);
      });
      try {
        agent.port.postMessage({
          type: "stop",
          requestId,
          commandId,
        } satisfies RecordFramePortMessage);
      } catch {
        clearTimeout(timer);
        agent.stopWaiters.delete(commandId);
        resolve(true);
      }
    });
  }
  async #startFrame(
    recording: ArmedRecording,
    tabId: number,
    frame: BrowserFrame,
  ): Promise<boolean> {
    const message: RecordFrameStartMessage = {
      type: RECORD_FRAME_START,
      requestId: recording.requestId,
      startedAtMs: recording.startedAtMs,
    };
    try {
      const response = await this.#deps.sendToDocument(tabId, message, {
        ...(frame.documentId ? { documentId: frame.documentId } : { frameId: frame.frameId }),
      });
      return isStarted(response);
    } catch {
      return false;
    }
  }
  #cancelAgents(recording: ArmedRecording): void {
    for (const agent of recording.agents.values()) {
      try {
        agent.port.postMessage({
          type: "cancel",
          requestId: recording.requestId,
        } satisfies RecordFramePortMessage);
      } catch {
        // A destroyed Document has no remaining capture state to cancel.
      }
    }
  }
 }
 function isStarted(value: unknown): boolean {
  return typeof value === "object" && value !== null && (value as { ok?: unknown }).ok === true;
 }
 export const recordFrameCoordinator = new RecordFrameCoordinator();
@@ -1,5 +0,0 @@
 const REDIRECT_QUALIFIERS = new Set(["client_redirect", "server_redirect"]);
 export function hasRedirectQualifier(qualifiers?: readonly string[]): boolean {
  return (qualifiers ?? []).some((qualifier) => REDIRECT_QUALIFIERS.has(qualifier));
 }
@@ -1,140 +0,0 @@
 import type { RenderedRef } from "@browser-skill/vom";
 import type { CdpTarget } from "@/browser-driver/frame-graph";
 import {
  type CaptureVomMatchNode,
  type CaptureVomObservationResult,
  captureVomObservation,
 } from "@/tools/capture-vom-observation";
 import type { CdpRunner, ChromeTabsApi } from "@/tools/shared";
 export interface IndexedObservationNode {
  frameId: string;
  geometry: CaptureVomMatchNode;
  ref?: RenderedRef;
 }
 export interface CapturedRecordingObservation {
  rootFrameId: string;
  index: ObservationNodeIndex;
  url: string;
  title?: string;
  vomText: string;
  truncated: boolean;
 }
 export interface RegisteredObservation {
  stateId: string;
  rootFrameId: string;
  index: ObservationNodeIndex;
  url: string;
 }
 export interface RecordingDocumentScope {
  frameId: string;
  target: CdpTarget;
 }
 function nodeKey(frameId: string, backendNodeId: number): string {
  return `${frameId}:${backendNodeId}`;
 }
 function frameTagKey(frameId: string, tag: string): string {
  return `${frameId}:${tag.toLowerCase()}`;
 }
 export class ObservationNodeIndex {
  readonly #nodesByFrameTag = new Map<string, IndexedObservationNode[]>();
  readonly #refById = new Map<string, RenderedRef>();
  readonly #refsByFrame = new Map<string, RenderedRef[]>();
  readonly #scopeByProducer = new Map<string, RecordingDocumentScope | null>();
  constructor(
    input: Pick<CaptureVomObservationResult, "rootFrameId" | "matchNodes" | "refs"> &
      Partial<Pick<CaptureVomObservationResult, "frames">>,
  ) {
    const refByNode = new Map<string, RenderedRef>();
    for (const ref of input.refs) {
      const frameId = ref.frameId ?? input.rootFrameId;
      refByNode.set(nodeKey(frameId, ref.backendNodeId), ref);
      this.#refById.set(ref.ref, ref);
      const frameRefs = this.#refsByFrame.get(frameId) ?? [];
      frameRefs.push(ref);
      this.#refsByFrame.set(frameId, frameRefs);
    }
    for (const frame of input.frames ?? []) {
      const documentId = frame.recordingDocumentId;
      if (!documentId) continue;
      this.#scopeByProducer.set(
        documentId,
        this.#scopeByProducer.has(documentId)
          ? null
          : { frameId: frame.frameId, target: frame.target },
      );
    }
    for (const geometry of input.matchNodes) {
      const { frameId } = geometry;
      const entry = {
        frameId,
        geometry,
        ref: refByNode.get(nodeKey(frameId, geometry.backendNodeId)),
      };
      const key = frameTagKey(frameId, geometry.tag);
      const bucket = this.#nodesByFrameTag.get(key) ?? [];
      bucket.push(entry);
      this.#nodesByFrameTag.set(key, bucket);
    }
  }
  candidates(frameId: string, tag: string): readonly IndexedObservationNode[] {
    return this.#nodesByFrameTag.get(frameTagKey(frameId, tag)) ?? [];
  }
  ref(refId: string): RenderedRef | undefined {
    return this.#refById.get(refId);
  }
  refs(frameId: string): readonly RenderedRef[] {
    return this.#refsByFrame.get(frameId) ?? [];
  }
  documentScope(producerId: string): RecordingDocumentScope | undefined {
    return this.#scopeByProducer.get(producerId) ?? undefined;
  }
 }
 async function readTabMeta(
  tabsApi: ChromeTabsApi,
  tabId: number,
 ): Promise<{ url: string; title?: string }> {
  try {
    const tab = await tabsApi.get(tabId);
    return { url: tab.url ?? "about:blank", title: tab.title };
  } catch {
    return { url: "about:blank" };
  }
 }
 export async function captureRecordingObservation(input: {
  cdp: CdpRunner;
  tabsApi: ChromeTabsApi;
  tabId: number;
  maxTokens: number;
  redactValues: boolean;
  signal?: AbortSignal;
 }): Promise<CapturedRecordingObservation> {
  const { url, title } = await readTabMeta(input.tabsApi, input.tabId);
  const captured = await captureVomObservation(input.cdp, input.tabId, url, {
    maxTokens: input.maxTokens,
    redactValues: input.redactValues,
    conditionalSurfaceProbe: false,
    signal: input.signal,
  });
  return {
    rootFrameId: captured.rootFrameId,
    index: new ObservationNodeIndex(captured),
    url,
    title,
    vomText: captured.text,
    truncated: captured.truncated,
  };
 }
@@ -1,128 +0,0 @@
 import type { CdpRunner, ChromeTabsApi } from "@/tools/shared";
 import { captureRecordingObservation, type RegisteredObservation } from "./observation-capture";
 import { RecordingStateRegistry } from "./state-registry";
 import { matchObservationTarget, unmatchedTarget } from "./target-matcher";
 import type { RecordingDraftStep, StepAnnotation, TargetedRecordingDraft } from "./types";
 const DEFAULT_MAX_PAGE_TOKENS = 3_000;
 const MIN_CAPTURE_INTERVAL_MS = 200;
 export interface TabObservationCursor {
  lastSettled: RegisteredObservation | null;
  lastCaptureAt: number;
 }
 function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
  return new Promise((resolve) => {
    if (signal?.aborted) return resolve();
    const timer = setTimeout(resolve, ms);
    signal?.addEventListener(
      "abort",
      () => {
        clearTimeout(timer);
        resolve();
      },
      { once: true },
    );
  });
 }
 function isTargeted(draft: RecordingDraftStep): draft is TargetedRecordingDraft {
  return (
    draft.op === "click" ||
    draft.op === "hover" ||
    draft.op === "fill" ||
    draft.op === "press" ||
    draft.op === "select"
  );
 }
 export class RecordingObservationSession {
  readonly registry: RecordingStateRegistry;
  readonly cursor: TabObservationCursor;
  readonly annotations: StepAnnotation[];
  readonly #maxTokens: number;
  readonly #redactValues: boolean;
  constructor(
    options: {
      registry?: RecordingStateRegistry;
      cursor?: TabObservationCursor;
      annotations?: StepAnnotation[];
      maxTokens?: number;
      redactValues?: boolean;
    } = {},
  ) {
    this.registry = options.registry ?? new RecordingStateRegistry();
    this.cursor = options.cursor ?? { lastSettled: null, lastCaptureAt: 0 };
    this.annotations = options.annotations ?? [];
    this.#maxTokens = options.maxTokens ?? DEFAULT_MAX_PAGE_TOKENS;
    this.#redactValues = options.redactValues ?? false;
  }
  async capture(
    cdp: CdpRunner,
    tabsApi: ChromeTabsApi,
    tabId: number,
    signal?: AbortSignal,
  ): Promise<RegisteredObservation> {
    const waitMs = Math.max(0, MIN_CAPTURE_INTERVAL_MS - (Date.now() - this.cursor.lastCaptureAt));
    if (waitMs > 0) await abortableDelay(waitMs, signal);
    if (signal?.aborted) throw new DOMException("observation aborted", "AbortError");
    const captured = await captureRecordingObservation({
      cdp,
      tabsApi,
      tabId,
      maxTokens: this.#maxTokens,
      redactValues: this.#redactValues,
      signal,
    });
    const state = this.registry.register({
      url: captured.url,
      title: captured.title,
      vomText: captured.vomText,
      truncated: captured.truncated,
    });
    const observation: RegisteredObservation = {
      stateId: state.id,
      rootFrameId: captured.rootFrameId,
      index: captured.index,
      url: captured.url,
    };
    this.cursor.lastSettled = observation;
    this.cursor.lastCaptureAt = Date.now();
    return observation;
  }
  bindDraft(draft: RecordingDraftStep, draftId: number, previousActionPending = false): void {
    const observation = this.cursor.lastSettled;
    if (isTargeted(draft)) {
      draft.matchedTarget = observation
        ? matchObservationTarget({
            observation,
            hint: draft.targetHint,
            fallback: draft.captureTarget,
          })
        : unmatchedTarget(draft.captureTarget);
    }
    if (!observation) return;
    const unmatched = isTargeted(draft) && draft.matchedTarget?.unmatched === true;
    if (previousActionPending && unmatched) return;
    draft.preStateId = observation.stateId;
    this.registry.markStep(observation.stateId, draftId);
    if (!isTargeted(draft) || !draft.matchedTarget?.ref) return;
    const ref = observation.index.ref(draft.matchedTarget.ref);
    if (!ref) return;
    this.annotations.push({
      draftId,
      op: draft.op,
      line: ref.line,
      stateId: observation.stateId,
      ...(draft.op === "fill" && !this.#redactValues
        ? { detail: JSON.stringify(draft.value) }
        : {}),
    });
  }
 }
@@ -1,277 +0,0 @@
 import type { CdpRunner, ChromeTabsApi } from "@/tools/shared";
 import type { StopReason, TraceV3 } from "@/transport/types";
 import { type DocumentSettleScope, waitForDocumentSettled } from "./document-settle";
 import type { RegisteredObservation } from "./observation-capture";
 import { RecordingObservationSession } from "./observation-session";
 import { inferMissingPostStates, SettleController } from "./settle-controller";
 import { RecordingStateRegistry } from "./state-registry";
 import { buildTraceV3 } from "./trace-builder-v3";
 import type { RecordingDraftStep, StepAnnotation } from "./types";
 interface TabRecordingContext {
  session: RecordingObservationSession;
  settle: SettleController;
  pendingCapture: PendingCapture | null;
  frameRefresh: Promise<void>;
  frameRefreshAbort: AbortController | null;
 }
 interface PendingCapture {
  promise: Promise<RegisteredObservation>;
  abort: AbortController;
 }
 export class RecordingObservationRuntime {
  readonly #cdp: CdpRunner;
  readonly #tabsApi: ChromeTabsApi;
  readonly #registry = new RecordingStateRegistry();
  readonly #annotations: StepAnnotation[] = [];
  readonly #contexts = new Map<number, TabRecordingContext>();
  readonly #maxTokens?: number;
  readonly #redactValues: boolean;
  constructor(input: {
    cdp: CdpRunner;
    tabsApi: ChromeTabsApi;
    maxTokens?: number;
    redactValues?: boolean;
  }) {
    this.#cdp = input.cdp;
    this.#tabsApi = input.tabsApi;
    this.#maxTokens = input.maxTokens;
    this.#redactValues = input.redactValues ?? false;
  }
  #context(tabId: number): TabRecordingContext {
    const existing = this.#contexts.get(tabId);
    if (existing) return existing;
    const session = new RecordingObservationSession({
      registry: this.#registry,
      annotations: this.#annotations,
      maxTokens: this.#maxTokens,
      redactValues: this.#redactValues,
    });
    const context: TabRecordingContext = {
      session,
      settle: new SettleController({
        session,
        cdp: this.#cdp,
        tabsApi: this.#tabsApi,
        tabId,
      }),
      pendingCapture: null,
      frameRefresh: Promise.resolve(),
      frameRefreshAbort: null,
    };
    this.#contexts.set(tabId, context);
    return context;
  }
  async #capture(tabId: number): Promise<RegisteredObservation> {
    const context = this.#context(tabId);
    if (context.pendingCapture) return context.pendingCapture.promise;
    const abort = new AbortController();
    let pending!: PendingCapture;
    const promise = context.session.capture(this.#cdp, this.#tabsApi, tabId, abort.signal);
    pending = {
      abort,
      promise: promise.finally(() => {
        if (context.pendingCapture === pending) context.pendingCapture = null;
      }),
    };
    context.pendingCapture = pending;
    return pending.promise;
  }
  async captureInitial(tabId: number): Promise<void> {
    const context = this.#context(tabId);
    if (context.session.cursor.lastSettled) return;
    await this.#capture(tabId);
  }
  /** Refresh the safe observation after a late child Document becomes usable. */
  async refreshDocument(tabId: number, producerId: string): Promise<void> {
    const context = this.#context(tabId);
    context.frameRefreshAbort?.abort();
    const abort = new AbortController();
    context.frameRefreshAbort = abort;
    const previous = context.frameRefresh;
    const refresh = (async () => {
      await previous;
      if (abort.signal.aborted) return;
      if (context.pendingCapture) await Promise.allSettled([context.pendingCapture.promise]);
      if (abort.signal.aborted) return;
      // The first capture discovers the safe producer -> CDP Document scope.
      await this.#capture(tabId);
      if (abort.signal.aborted) return;
      const scope = context.session.cursor.lastSettled?.index.documentScope(producerId);
      if (scope) {
        await waitForDocumentSettled(this.#cdp, scope, { signal: abort.signal });
      }
      if (abort.signal.aborted) return;
      // Capture again after the child SPA is quiet so the next action can be
      // matched against refs that actually exist in its pre-action state.
      await this.#capture(tabId);
    })();
    const tracked = refresh.catch(() => {});
    context.frameRefresh = tracked;
    try {
      await refresh;
    } finally {
      if (context.frameRefresh === tracked) context.frameRefreshAbort = null;
    }
  }
  async captureTabTransition(
    fromTabId: number,
    toTabId: number,
  ): Promise<{ preStateId?: string; postStateId?: string; targetUrl?: string }> {
    const from = this.#context(fromTabId);
    await this.#flushContext(from);
    if (!from.session.cursor.lastSettled) {
      try {
        await this.captureInitial(fromTabId);
      } catch {
        // A target-tab observation can still preserve the forward transition.
      }
    }
    const to = this.#context(toTabId);
    let target = to.session.cursor.lastSettled;
    try {
      target = await this.#capture(toTabId);
    } catch {
      // Reuse the last settled target state when a refresh races navigation.
    }
    const source = from.session.cursor.lastSettled;
    return {
      ...(source ? { preStateId: source.stateId } : {}),
      ...(target ? { postStateId: target.stateId, targetUrl: target.url } : {}),
    };
  }
  bindTabTransition(
    draft: Extract<RecordingDraftStep, { op: "switch_tab" }>,
    draftId: number,
  ): void {
    if (draft.preStateId) this.#registry.markStep(draft.preStateId, draftId);
  }
  async processDraft(
    tabId: number,
    drafts: RecordingDraftStep[],
    draftIndex: number,
    producerId?: string,
  ): Promise<void> {
    const draft = drafts[draftIndex];
    if (!draft) return;
    const context = this.#context(tabId);
    if (!context.session.cursor.lastSettled) {
      try {
        await this.captureInitial(tabId);
      } catch {
        // Post-action settle can still provide a usable state.
      }
    }
    const scope = producerId
      ? context.session.cursor.lastSettled?.index.documentScope(producerId)
      : undefined;
    if (
      producerId &&
      (draft.op === "click" ||
        draft.op === "hover" ||
        draft.op === "fill" ||
        draft.op === "press" ||
        draft.op === "select")
    ) {
      draft.targetHint = {
        ...(draft.targetHint ?? {}),
        frameId: scope?.frameId ?? null,
        geometrySpace: "local",
      };
    }
    context.session.bindDraft(draft, draftIndex + 1, context.settle.hasPending);
    context.settle.schedule(drafts, draftIndex, scope);
  }
  scheduleSettle(
    tabId: number,
    drafts: RecordingDraftStep[],
    draftIndex: number,
    scope?: DocumentSettleScope,
  ): void {
    this.#context(tabId).settle.schedule(drafts, draftIndex, scope);
  }
  clearRedirect(tabId: number): void {
    this.#contexts.get(tabId)?.settle.clearRedirect();
  }
  scheduleRedirect(tabId: number, drafts: RecordingDraftStep[], url: string): void {
    this.#context(tabId).settle.scheduleRedirect(drafts, url);
  }
  async #flushContext(context: TabRecordingContext): Promise<void> {
    await context.frameRefresh;
    if (context.pendingCapture) await Promise.allSettled([context.pendingCapture.promise]);
    await context.settle.flushRedirects();
    await context.settle.flush();
  }
  async flushRedirects(tabId: number): Promise<void> {
    await this.#contexts.get(tabId)?.settle.flushRedirects();
  }
  async flush(): Promise<void> {
    for (const context of this.#contexts.values()) await this.#flushContext(context);
  }
  async settleTrailing(tabId: number, drafts: RecordingDraftStep[]): Promise<void> {
    const context = this.#context(tabId);
    if (context.pendingCapture) await Promise.allSettled([context.pendingCapture.promise]);
    if (!context.session.cursor.lastSettled) {
      try {
        await this.captureInitial(tabId);
      } catch {
        // The trace may remain observation-free when CDP is unavailable.
      }
    }
    await context.settle.settleTrailing(drafts);
    inferMissingPostStates(drafts);
  }
  cancel(): void {
    for (const context of this.#contexts.values()) {
      context.frameRefreshAbort?.abort();
      context.pendingCapture?.abort.abort();
      context.settle.cancel();
    }
  }
  buildTrace(input: {
    drafts: RecordingDraftStep[];
    startedAt: string;
    purpose?: string;
    startUrl?: string;
    stoppedBy: StopReason;
    bskVersion: string;
    includeTabSwitches?: boolean;
  }): TraceV3 {
    return buildTraceV3({
      registry: this.#registry,
      drafts: input.drafts,
      annotations: this.#annotations,
      startedAt: input.startedAt,
      purpose: input.purpose,
      startUrl: input.startUrl,
      stoppedBy: input.stoppedBy,
      bskVersion: input.bskVersion,
      redactValues: this.#redactValues,
      includeTabSwitches: input.includeTabSwitches,
    });
  }
 }
@@ -1,233 +0,0 @@
 import type { CdpRunner, ChromeTabsApi } from "@/tools/shared";
 import { type DocumentSettleScope, waitForDocumentSettled } from "./document-settle";
 import { RecordingObservationSession } from "./observation-session";
 import type { RecordingDraftStep } from "./types";
 interface PendingSettle {
  abort: AbortController;
  scope: DocumentSettleScope;
 }
 interface PendingRedirect {
  url: string;
  abort: AbortController;
 }
 const CAPTURE_RETRY_DELAY_MS = 250;
 function delay(ms: number, signal?: AbortSignal): Promise<void> {
  return new Promise((resolve) => {
    if (signal?.aborted) return resolve();
    const timer = setTimeout(resolve, ms);
    signal?.addEventListener(
      "abort",
      () => {
        clearTimeout(timer);
        resolve();
      },
      { once: true },
    );
  });
 }
 function isAbortError(error: unknown): boolean {
  return (
    typeof error === "object" &&
    error !== null &&
    (error as { name?: string }).name === "AbortError"
  );
 }
 export function inferMissingPostStates(drafts: RecordingDraftStep[]): void {
  for (let index = 0; index < drafts.length - 1; index += 1) {
    const draft = drafts[index];
    const next = drafts[index + 1];
    if (draft && next && !draft.postStateId && next.preStateId) {
      draft.postStateId = next.preStateId;
    }
  }
 }
 export class SettleController {
  readonly #session: RecordingObservationSession;
  readonly #cdp: CdpRunner;
  readonly #tabsApi: ChromeTabsApi;
  readonly #tabId: number;
  readonly #rootScope: DocumentSettleScope;
  readonly #pending = new Map<number, PendingSettle>();
  #queue = Promise.resolve();
  #pendingRedirect: PendingRedirect | null = null;
  #redirectQueue = Promise.resolve();
  constructor(input: {
    session: RecordingObservationSession;
    cdp: CdpRunner;
    tabsApi: ChromeTabsApi;
    tabId: number;
  }) {
    this.#session = input.session;
    this.#cdp = input.cdp;
    this.#tabsApi = input.tabsApi;
    this.#tabId = input.tabId;
    this.#rootScope = { target: { tabId: input.tabId } };
  }
  get hasPending(): boolean {
    return this.#pending.size > 0 || this.#pendingRedirect !== null;
  }
  async #captureWithRetry(signal?: AbortSignal) {
    try {
      return await this.#session.capture(this.#cdp, this.#tabsApi, this.#tabId, signal);
    } catch (error) {
      if (signal?.aborted) throw error;
      await delay(CAPTURE_RETRY_DELAY_MS, signal);
      return this.#session.capture(this.#cdp, this.#tabsApi, this.#tabId, signal);
    }
  }
  schedule(
    drafts: RecordingDraftStep[],
    draftIndex: number,
    scope: DocumentSettleScope = this.#rootScope,
  ): void {
    if (scope.target.tabId !== this.#tabId) {
      throw new Error(
        `settle scope tab ${scope.target.tabId} does not belong to tab ${this.#tabId}`,
      );
    }
    const landing = drafts[draftIndex]?.preStateId;
    for (const [index, pending] of this.#pending) {
      if (index >= draftIndex) continue;
      pending.abort.abort();
      this.#pending.delete(index);
      if (landing && drafts[index] && !drafts[index].postStateId) {
        drafts[index].postStateId = landing;
      }
    }
    this.#pending.get(draftIndex)?.abort.abort();
    const pending = { abort: new AbortController(), scope };
    this.#pending.set(draftIndex, pending);
    const task = async () => {
      if (pending.abort.signal.aborted) return;
      try {
        const outcome = await waitForDocumentSettled(this.#cdp, pending.scope, {
          signal: pending.abort.signal,
        });
        if (outcome === "cancelled") return;
        const observation = await this.#captureWithRetry(pending.abort.signal);
        if (!pending.abort.signal.aborted && drafts[draftIndex]) {
          drafts[draftIndex].postStateId = observation.stateId;
        }
      } catch (error) {
        if (!isAbortError(error)) {
          console.warn(
            `[bsk record] post-action observation failed for step ${draftIndex + 1}`,
            error,
          );
        }
      } finally {
        if (this.#pending.get(draftIndex) === pending) this.#pending.delete(draftIndex);
      }
    };
    this.#queue = this.#queue.then(task, task).catch(() => {});
  }
  cancel(): void {
    for (const pending of this.#pending.values()) pending.abort.abort();
    this.#pending.clear();
    this.clearRedirect();
  }
  async flush(): Promise<void> {
    for (let round = 0; round < 10; round += 1) {
      const current = this.#queue;
      await current;
      if (current === this.#queue) return;
    }
    console.warn("[bsk record] settle queue kept growing; using completed observations");
  }
  async settleTrailing(drafts: RecordingDraftStep[]): Promise<void> {
    const trailing: RecordingDraftStep[] = [];
    for (let index = drafts.length - 1; index >= 0; index -= 1) {
      const draft = drafts[index];
      if (!draft || draft.postStateId) break;
      trailing.push(draft);
    }
    if (trailing.length === 0) return;
    try {
      const observation = await this.#captureWithRetry();
      for (const draft of trailing) draft.postStateId = observation.stateId;
    } catch (error) {
      console.warn("[bsk record] final observation at stop failed", error);
    }
  }
  clearRedirect(): void {
    this.#pendingRedirect?.abort.abort();
    this.#pendingRedirect = null;
  }
  scheduleRedirect(drafts: RecordingDraftStep[], url: string): void {
    this.#pendingRedirect?.abort.abort();
    const pending: PendingRedirect = { url, abort: new AbortController() };
    this.#pendingRedirect = pending;
    const task = () => this.#settleRedirect(drafts, pending);
    this.#redirectQueue = this.#redirectQueue.then(task, task).catch(() => {});
  }
  async #settleRedirect(drafts: RecordingDraftStep[], pending: PendingRedirect): Promise<void> {
    const outcome = await waitForDocumentSettled(this.#cdp, this.#rootScope, {
      signal: pending.abort.signal,
    });
    if (outcome === "cancelled" || this.#pendingRedirect !== pending) return;
    let finalUrl = pending.url;
    try {
      finalUrl = (await this.#tabsApi.get(this.#tabId)).url || finalUrl;
    } catch {
      // The navigation event URL remains the best available destination.
    }
    if (this.#pendingRedirect !== pending) return;
    this.#pendingRedirect = null;
    if (
      !finalUrl ||
      finalUrl === "about:blank" ||
      this.#session.cursor.lastSettled?.url === finalUrl
    ) {
      return;
    }
    const last = drafts[drafts.length - 1];
    if (last?.op === "navigate" && last.url === finalUrl) {
      if (!last.postStateId) this.schedule(drafts, drafts.length - 1);
      await this.flush();
      return;
    }
    const draft: RecordingDraftStep = {
      op: "navigate",
      url: finalUrl,
      pageUrl: finalUrl,
      cause: "browser",
      transitionQualifiers: ["server_redirect"],
      preStateId: this.#session.cursor.lastSettled?.stateId,
    };
    drafts.push(draft);
    const draftIndex = drafts.length - 1;
    if (draft.preStateId) this.#session.registry.markStep(draft.preStateId, draftIndex + 1);
    this.schedule(drafts, draftIndex);
    await this.flush();
  }
  async flushRedirects(): Promise<void> {
    for (let round = 0; round < 10; round += 1) {
      const current = this.#redirectQueue;
      await current;
      if (current === this.#redirectQueue) return;
    }
    console.warn("[bsk record] redirect queue kept growing; using the final completed landing");
  }
 }
@@ -1,57 +0,0 @@
 export interface RecordedStateEntry {
  id: string;
  url: string;
  title?: string;
  /** Rendered VOM text; capture indexes and source DOM/AX data never enter the registry. */
  vomText: string;
  truncated: boolean;
  stepsHere: number[];
 }
 function stateIdentity(url: string, body: string): string {
  return `${url}\0${body}`;
 }
 export class RecordingStateRegistry {
  readonly #entriesById = new Map<string, RecordedStateEntry>();
  readonly #idByIdentity = new Map<string, string>();
  #nextId = 1;
  register(input: {
    url: string;
    title?: string;
    vomText: string;
    truncated?: boolean;
  }): RecordedStateEntry {
    const identity = stateIdentity(input.url, input.vomText);
    const existingId = this.#idByIdentity.get(identity);
    if (existingId) {
      const existing = this.#entriesById.get(existingId)!;
      if (!existing.title && input.title) existing.title = input.title;
      if (input.truncated) existing.truncated = true;
      return existing;
    }
    const entry: RecordedStateEntry = {
      id: `s${this.#nextId}`,
      url: input.url,
      ...(input.title ? { title: input.title } : {}),
      vomText: input.vomText,
      truncated: input.truncated ?? false,
      stepsHere: [],
    };
    this.#nextId += 1;
    this.#entriesById.set(entry.id, entry);
    this.#idByIdentity.set(identity, entry.id);
    return entry;
  }
  values(): RecordedStateEntry[] {
    return [...this.#entriesById.values()];
  }
  markStep(stateId: string, draftId: number): void {
    const entry = this.#entriesById.get(stateId);
    if (entry && !entry.stepsHere.includes(draftId)) entry.stepsHere.push(draftId);
  }
 }
@@ -1,155 +0,0 @@
 import type { RecordStepPayload } from "../record-bridge";
 import { hasRedirectQualifier } from "./navigation-policy";
 import type { RecordingDraftStep, TargetMatchHint } from "./types";
 export interface RecordingStepBuffer {
  steps: RecordingDraftStep[];
  navigation: RecordingNavigationCursor;
 }
 export interface RecordingNavigationCursor {
  currentUrl?: string;
  pendingNavigation: boolean;
  pendingNavigationDeadline?: number;
 }
 const NAVIGATION_TRIGGER_WINDOW_MS = 3_000;
 function toDraftStep(
  payload: RecordStepPayload,
  targetHint?: TargetMatchHint,
 ): RecordingDraftStep | null {
  const pageUrl = payload.page_url;
  const common = {
    ...(pageUrl ? { pageUrl } : {}),
    ...(targetHint ? { targetHint } : {}),
  };
  switch (payload.op) {
    case "click":
      return payload.target ? { op: "click", captureTarget: payload.target, ...common } : null;
    case "hover":
      return payload.target ? { op: "hover", captureTarget: payload.target, ...common } : null;
    case "fill":
      return payload.target
        ? {
            op: "fill",
            captureTarget: payload.target,
            value: payload.value ?? "",
            ...(payload.commit ? { commit: payload.commit } : {}),
            ...(payload.redacted ? { redacted: true } : {}),
            ...common,
          }
        : null;
    case "press":
      return payload.key
        ? {
            op: "press",
            key: payload.key,
            ...(payload.target ? { captureTarget: payload.target } : {}),
            ...(payload.modifiers?.length ? { modifiers: payload.modifiers } : {}),
            ...common,
          }
        : null;
    case "select":
      return payload.target && payload.values
        ? {
            op: "select",
            captureTarget: payload.target,
            values: payload.values,
            ...(payload.labels?.length ? { labels: payload.labels } : {}),
            ...common,
          }
        : null;
    case "navigate":
      return null;
  }
 }
 function annotateLastStepNavigation(buffer: RecordingStepBuffer, url: string): number {
  for (let index = buffer.steps.length - 1; index >= 0; index -= 1) {
    const step = buffer.steps[index];
    if (!step) continue;
    if (step.op === "click" || step.op === "press" || step.op === "select" || step.op === "fill") {
      step.navigatedTo = url;
      return index;
    }
    break;
  }
  return -1;
 }
 export type NavigationObserveResult =
  | { kind: "noop" }
  | { kind: "annotated"; index: number }
  | { kind: "appended"; index: number }
  | { kind: "coalesce_redirect"; url: string };
 export function observeRecordedNavigation(
  buffer: RecordingStepBuffer,
  url: string,
  causedByAction?: boolean,
  transitionType?: string,
  transitionQualifiers?: string[],
 ): NavigationObserveResult {
  const navigation = buffer.navigation;
  if (!url || url === navigation.currentUrl) return { kind: "noop" };
  navigation.currentUrl = url;
  const pendingIsCurrent =
    navigation.pendingNavigation &&
    (navigation.pendingNavigationDeadline === undefined ||
      navigation.pendingNavigationDeadline >= Date.now());
  if (causedByAction === true || (causedByAction === undefined && pendingIsCurrent)) {
    navigation.pendingNavigation = false;
    navigation.pendingNavigationDeadline = undefined;
    const annotatedIndex = annotateLastStepNavigation(buffer, url);
    if (annotatedIndex >= 0) return { kind: "annotated", index: annotatedIndex };
  } else {
    navigation.pendingNavigation = false;
    navigation.pendingNavigationDeadline = undefined;
  }
  if (hasRedirectQualifier(transitionQualifiers)) {
    return { kind: "coalesce_redirect", url };
  }
  buffer.steps.push({
    op: "navigate",
    url,
    pageUrl: url,
    transitionType,
    transitionQualifiers,
  });
  return { kind: "appended", index: buffer.steps.length - 1 };
 }
 export function appendRecordedPayload(
  buffer: RecordingStepBuffer,
  payload: RecordStepPayload,
  targetHint?: TargetMatchHint,
 ): number | null {
  if (payload.op === "navigate") {
    if (!payload.url) return null;
    const result = observeRecordedNavigation(
      buffer,
      payload.url,
      payload.navigation_caused_by_action,
      payload.transitionType,
      payload.transitionQualifiers,
    );
    return result.kind === "appended" ? result.index : null;
  }
  const step = toDraftStep(
    { ...payload, page_url: payload.page_url ?? buffer.navigation.currentUrl },
    targetHint,
  );
  if (!step) return null;
  buffer.steps.push(step);
  if (step.op === "click" || step.op === "press" || step.op === "select" || step.op === "fill") {
    buffer.navigation.pendingNavigation = payload.expects_navigation === true;
    buffer.navigation.pendingNavigationDeadline = buffer.navigation.pendingNavigation
      ? Date.now() + NAVIGATION_TRIGGER_WINDOW_MS
      : undefined;
  }
  return buffer.steps.length - 1;
 }
@@ -1,61 +0,0 @@
 import type { RecordingNavigationCursor } from "./step-buffer";
 export interface TabActivation {
  tabId: number;
  revision: number;
 }
 export class RecordingTabCoordinator {
  readonly #navigationByTab = new Map<number, RecordingNavigationCursor>();
  #activeTabId: number;
  #currentTabId: number;
  #activationRevision = 0;
  constructor(initialTabId: number, initialUrl?: string) {
    this.#activeTabId = initialTabId;
    this.#currentTabId = initialTabId;
    this.#navigationByTab.set(initialTabId, {
      currentUrl: initialUrl,
      pendingNavigation: false,
    });
  }
  get activeTabId(): number {
    return this.#activeTabId;
  }
  get currentTabId(): number {
    return this.#currentTabId;
  }
  noteActivation(tabId: number): TabActivation {
    this.#activeTabId = tabId;
    this.#activationRevision += 1;
    return { tabId, revision: this.#activationRevision };
  }
  isLatest(activation: TabActivation): boolean {
    return (
      activation.tabId === this.#activeTabId && activation.revision === this.#activationRevision
    );
  }
  commit(tabId: number, currentUrl?: string): void {
    if (currentUrl !== undefined) this.navigation(tabId).currentUrl = currentUrl;
    this.#currentTabId = tabId;
  }
  navigation(tabId: number, fallbackUrl?: string): RecordingNavigationCursor {
    const existing = this.#navigationByTab.get(tabId);
    if (existing) {
      if (!existing.currentUrl && fallbackUrl) existing.currentUrl = fallbackUrl;
      return existing;
    }
    const created: RecordingNavigationCursor = {
      currentUrl: fallbackUrl,
      pendingNavigation: false,
    };
    this.#navigationByTab.set(tabId, created);
    return created;
  }
 }
@@ -1,86 +0,0 @@
 import type { RenderedRef } from "@browser-skill/vom";
 import type { TargetDescriptorV3 } from "@/transport/types";
 import type { CaptureTargetDescriptor } from "../describe-target";
 import type { IndexedObservationNode, RegisteredObservation } from "./observation-capture";
 import type { TargetGeometry, TargetMatchHint } from "./types";
 const MATCH_TOLERANCE_PX = 2;
 function close(a: number, b: number): boolean {
  return Math.abs(a - b) <= MATCH_TOLERANCE_PX;
 }
 function rectMatches(a: TargetGeometry["rect"], b: TargetGeometry["rect"]): boolean {
  return close(a.x, b.x) && close(a.y, b.y) && close(a.w, b.w) && close(a.h, b.h);
 }
 function candidateMatches(
  candidate: IndexedObservationNode,
  geometry: TargetGeometry,
  geometrySpace: "top" | "local",
 ): boolean {
  const rect = geometrySpace === "local" ? candidate.geometry.localRect : candidate.geometry.rect;
  return rect != null && rectMatches(geometry.rect, rect);
 }
 export function unmatchedTarget(fallback?: CaptureTargetDescriptor): TargetDescriptorV3 {
  return {
    ...(fallback?.role ? { role: fallback.role } : {}),
    ...(fallback?.name ? { name: fallback.name } : {}),
    unmatched: true,
  };
 }
 function normalized(value: string | undefined): string {
  return value?.replace(/\s+/g, " ").trim().toLowerCase() ?? "";
 }
 function matchesSemantics(ref: RenderedRef, fallback?: CaptureTargetDescriptor): boolean {
  const role = normalized(fallback?.role);
  const name = normalized(fallback?.name);
  if (!role && !name) return false;
  if (role && normalized(ref.role) !== role) return false;
  if (name && normalized(ref.name) !== name) return false;
  return true;
 }
 function descriptor(ref: RenderedRef): TargetDescriptorV3 {
  return {
    ref: ref.ref,
    ...(ref.role ? { role: ref.role } : {}),
    ...(ref.name ? { name: ref.name } : {}),
    ...(ref.ctx ? { ctx: ref.ctx } : {}),
  };
 }
 export function matchObservationTarget(input: {
  observation: RegisteredObservation;
  hint?: TargetMatchHint;
  fallback?: CaptureTargetDescriptor;
 }): TargetDescriptorV3 {
  if (input.hint?.frameId === null) return unmatchedTarget(input.fallback);
  const frameId = input.hint?.frameId ?? input.observation.rootFrameId;
  const geometry = input.hint?.geometry;
  if (geometry) {
    const matches = input.observation.index
      .candidates(frameId, geometry.tag)
      .filter(
        (candidate) =>
          candidate.ref &&
          candidateMatches(candidate, geometry, input.hint?.geometrySpace ?? "top"),
      );
    if (matches.length === 1) return descriptor(matches[0]!.ref!);
    const semanticMatches = matches.filter(
      (candidate) => candidate.ref && matchesSemantics(candidate.ref, input.fallback),
    );
    if (semanticMatches.length === 1) return descriptor(semanticMatches[0]!.ref!);
    return unmatchedTarget(input.fallback);
  }
  const semanticMatches = input.observation.index
    .refs(frameId)
    .filter((ref) => matchesSemantics(ref, input.fallback));
  return semanticMatches.length === 1
    ? descriptor(semanticMatches[0]!)
    : unmatchedTarget(input.fallback);
 }
@@ -1,92 +0,0 @@
 import {
  type StepV3,
  type StopReason,
  TRACE_VERSION_V3,
  type TraceStateV3,
  type TraceV3,
  VOM_FORMAT_VERSION,
 } from "@/transport/types";
 import { resolveDraftStartUrl } from "./draft-policy";
 import type { RecordedStateEntry, RecordingStateRegistry } from "./state-registry";
 import { reduceTraceStepsV3 } from "./trace-reducer-v3";
 import { formatTraceStateBody } from "./trace-state-body";
 import type { RecordingDraftStep, StepAnnotation } from "./types";
 function publishedEntries(registry: RecordingStateRegistry, steps: StepV3[]): RecordedStateEntry[] {
  const entries = registry.values();
  if (steps.length === 0) return entries.slice(0, 1);
  const referenced = new Set(steps.flatMap((step) => [step.state, step.result.state]));
  return entries.filter((entry) => referenced.has(entry.id));
 }
 function remapDraftIds(draftIds: number[], stepIdByDraftId: Map<number, number>): number[] {
  return [
    ...new Set(
      draftIds.flatMap((id) => {
        const stepId = stepIdByDraftId.get(id);
        return stepId === undefined ? [] : [stepId];
      }),
    ),
  ].sort((a, b) => a - b);
 }
 export function buildTraceV3(input: {
  registry: RecordingStateRegistry;
  drafts: RecordingDraftStep[];
  annotations?: StepAnnotation[];
  startedAt: string;
  purpose?: string;
  startUrl?: string;
  stoppedBy: StopReason;
  bskVersion: string;
  redactValues?: boolean;
  includeTabSwitches?: boolean;
 }): TraceV3 {
  const reduced = reduceTraceStepsV3(input.drafts, {
    includeTabSwitches: input.includeTabSwitches,
    redactValues: input.redactValues,
  });
  const entries = publishedEntries(input.registry, reduced.steps);
  const publishedId = new Map(entries.map((entry, index) => [entry.id, `s${index + 1}`]));
  const annotationsByState = new Map<string, StepAnnotation[]>();
  for (const annotation of input.annotations ?? []) {
    const bucket = annotationsByState.get(annotation.stateId) ?? [];
    bucket.push(annotation);
    annotationsByState.set(annotation.stateId, bucket);
  }
  const steps = reduced.steps.map((step) => ({
    ...step,
    state: publishedId.get(step.state) ?? step.state,
    result: { state: publishedId.get(step.result.state) ?? step.result.state },
  }));
  const states: TraceStateV3[] = entries.map((entry) => {
    const id = publishedId.get(entry.id) ?? entry.id;
    return {
      id,
      url: entry.url,
      ...(entry.title ? { title: entry.title } : {}),
      body: formatTraceStateBody({
        stateId: id,
        url: entry.url,
        title: entry.title,
        stepIds: remapDraftIds(entry.stepsHere, reduced.stepIdByDraftId),
        vomText: entry.vomText,
        annotations: annotationsByState.get(entry.id) ?? [],
        stepIdByDraftId: reduced.stepIdByDraftId,
      }),
      ...(entry.truncated ? { truncated: true } : {}),
    };
  });
  return {
    version: TRACE_VERSION_V3,
    ...(input.purpose ? { purpose: input.purpose } : {}),
    recorded_at: new Date().toISOString(),
    started_at: input.startedAt,
    stopped_by: input.stoppedBy,
    entry: { start_url: resolveDraftStartUrl(input.drafts, input.startUrl, states[0]?.url) },
    recorder: { bsk: input.bskVersion, vom: VOM_FORMAT_VERSION },
    states,
    steps,
  };
 }
@@ -1,154 +0,0 @@
 import type { NavigationCause, StepV3 } from "@/transport/types";
 import { shouldIncludeDraft } from "./draft-policy";
 import { hasRedirectQualifier } from "./navigation-policy";
 import { unmatchedTarget } from "./target-matcher";
 import type { RecordingDraftStep } from "./types";
 interface CollapsedDraft {
  draft: RecordingDraftStep;
  draftIds: number[];
 }
 const TRANSITION_CAUSES: Record<string, NavigationCause> = {
  typed: "user_typed",
  generated: "user_typed",
  keyword: "user_typed",
  keyword_generated: "user_typed",
  link: "link",
  form_submit: "form_submit",
  reload: "reload",
  auto_bookmark: "browser",
  start_page: "browser",
 };
 function isRedirect(step: Extract<RecordingDraftStep, { op: "navigate" }>): boolean {
  return hasRedirectQualifier(step.transitionQualifiers);
 }
 function collapseRedirects(steps: RecordingDraftStep[]): CollapsedDraft[] {
  const output: CollapsedDraft[] = [];
  steps.forEach((step, index) => {
    const previous = output[output.length - 1];
    if (step.op === "navigate" && previous?.draft.op === "navigate" && isRedirect(step)) {
      previous.draft = {
        ...previous.draft,
        url: step.url,
        postStateId: step.postStateId ?? previous.draft.postStateId,
      };
      previous.draftIds.push(index + 1);
      return;
    }
    output.push({ draft: { ...step }, draftIds: [index + 1] });
  });
  return output;
 }
 function navigationCause(step: Extract<RecordingDraftStep, { op: "navigate" }>): NavigationCause {
  if (step.cause) return step.cause;
  const qualifiers = step.transitionQualifiers ?? [];
  if (qualifiers.includes("forward_back")) return "history";
  if (qualifiers.includes("from_address_bar")) return "user_typed";
  return TRANSITION_CAUSES[step.transitionType ?? ""] ?? "browser";
 }
 function selection(values: string[], labels?: string[]): Array<{ value: string; label?: string }> {
  return values.map((value, index) => ({
    value,
    ...(labels?.[index] ? { label: labels[index] } : {}),
  }));
 }
 interface ReduceDraftOptions {
  includeTabSwitches: boolean;
  redactValues: boolean;
 }
 function reduceDraft(
  draft: RecordingDraftStep,
  id: number,
  options: ReduceDraftOptions,
 ): StepV3 | null {
  if (!shouldIncludeDraft(draft)) return null;
  if (draft.op === "switch_tab") {
    if (!options.includeTabSwitches || !draft.preStateId || !draft.postStateId) return null;
    return {
      op: "switch_tab",
      id,
      state: draft.preStateId,
      result: { state: draft.postStateId },
    };
  }
  const state = draft.preStateId ?? draft.postStateId;
  const resultState = draft.postStateId ?? draft.preStateId;
  if (!state || !resultState) return null;
  const common = { id, state, result: { state: resultState } };
  switch (draft.op) {
    case "navigate":
      return { op: "navigate", ...common, to: draft.url, cause: navigationCause(draft) };
    case "click":
      return {
        op: "click",
        ...common,
        target: draft.matchedTarget ?? unmatchedTarget(draft.captureTarget),
      };
    case "hover":
      return {
        op: "hover",
        ...common,
        target: draft.matchedTarget ?? unmatchedTarget(draft.captureTarget),
      };
    case "fill":
      const fillIsRedacted = options.redactValues || draft.redacted === true;
      return {
        op: "fill",
        ...common,
        target: draft.matchedTarget ?? unmatchedTarget(draft.captureTarget),
        value: fillIsRedacted ? "***" : draft.value,
        commit: draft.commit ?? "blur",
        ...(fillIsRedacted ? { redacted: true } : {}),
      };
    case "press":
      return {
        op: "press",
        ...common,
        key: draft.key,
        ...(draft.captureTarget || draft.matchedTarget
          ? { target: draft.matchedTarget ?? unmatchedTarget(draft.captureTarget) }
          : {}),
        ...(draft.modifiers?.length ? { modifiers: draft.modifiers } : {}),
      };
    case "select":
      return {
        op: "select",
        ...common,
        target: draft.matchedTarget ?? unmatchedTarget(draft.captureTarget),
        ...(!options.redactValues ? { selection: selection(draft.values, draft.labels) } : {}),
      };
    case "scroll":
      return { op: "scroll", ...common };
  }
 }
 export interface ReducedTraceV3 {
  steps: StepV3[];
  stepIdByDraftId: Map<number, number>;
 }
 export function reduceTraceStepsV3(
  steps: RecordingDraftStep[],
  options: { includeTabSwitches?: boolean; redactValues?: boolean } = {},
 ): ReducedTraceV3 {
  const output: StepV3[] = [];
  const stepIdByDraftId = new Map<number, number>();
  for (const { draft, draftIds } of collapseRedirects(steps)) {
    const step = reduceDraft(draft, output.length + 1, {
      includeTabSwitches: options.includeTabSwitches === true,
      redactValues: options.redactValues === true,
    });
    if (!step) continue;
    output.push(step);
    for (const draftId of draftIds) stepIdByDraftId.set(draftId, step.id);
  }
  return { steps: output, stepIdByDraftId };
 }
@@ -1,39 +0,0 @@
 import type { StepAnnotation } from "./types";
 function annotationText(annotation: StepAnnotation, stepId: number): string {
  return ` ⟵ step ${stepId}: ${annotation.op}${annotation.detail ? `: ${annotation.detail}` : ""}`;
 }
 export function formatTraceStateBody(input: {
  stateId: string;
  url: string;
  title?: string;
  stepIds: number[];
  vomText: string;
  annotations: StepAnnotation[];
  stepIdByDraftId: Map<number, number>;
 }): string {
  const lines = ["# bsk-observation 1", `state: ${JSON.stringify(input.stateId)}`];
  lines.push(`url: ${JSON.stringify(input.url)}`);
  if (input.title) lines.push(`title: ${JSON.stringify(input.title)}`);
  if (input.stepIds.length > 0) lines.push(`steps_here: [${input.stepIds.join(", ")}]`);
  lines.push("---");
  const byLine = new Map<number, Array<{ annotation: StepAnnotation; stepId: number }>>();
  for (const annotation of input.annotations) {
    const stepId = input.stepIdByDraftId.get(annotation.draftId);
    if (stepId === undefined) continue;
    const bucket = byLine.get(annotation.line) ?? [];
    bucket.push({ annotation, stepId });
    byLine.set(annotation.line, bucket);
  }
  input.vomText.split("\n").forEach((bodyLine, lineIndex) => {
    let line = bodyLine;
    for (const item of byLine.get(lineIndex) ?? []) {
      line += annotationText(item.annotation, item.stepId);
    }
    lines.push(line);
  });
  return `${lines.join("\n")}\n`;
 }
@@ -1,85 +0,0 @@
 import type { CaptureTargetDescriptor } from "@/lib/describe-target";
 import type {
  FillCommit,
  KeyModifier,
  NavigationCause,
  StepV3,
  TargetDescriptorV3,
 } from "@/transport/types";
 export interface TargetGeometry {
  /** Top-level viewport-relative CSS pixels, as defined by the geometry module. */
  rect: { x: number; y: number; w: number; h: number };
  tag: string;
 }
 export interface TargetMatchHint {
  geometry?: TargetGeometry;
  /** Missing means top frame; null means the source Document could not be resolved. */
  frameId?: string | null;
  geometrySpace?: "top" | "local";
 }
 export interface StepAnnotation {
  draftId: number;
  op: StepV3["op"];
  line: number;
  stateId: string;
  detail?: string;
 }
 interface DraftStateLink {
  pageUrl?: string;
  preStateId?: string;
  postStateId?: string;
 }
 interface DraftTarget {
  captureTarget?: CaptureTargetDescriptor;
  targetHint?: TargetMatchHint;
  matchedTarget?: TargetDescriptorV3;
 }
 interface DraftNavigationEffect {
  navigatedTo?: string;
 }
 export type RecordingDraftStep =
  | ({ op: "click" } & DraftStateLink & DraftTarget & DraftNavigationEffect)
  | ({ op: "hover" } & DraftStateLink & DraftTarget)
  | ({
      op: "fill";
      value: string;
      commit?: FillCommit;
      redacted?: boolean;
    } & DraftStateLink &
      DraftTarget &
      DraftNavigationEffect)
  | ({
      op: "press";
      key: string;
      modifiers?: KeyModifier[];
    } & DraftStateLink &
      DraftTarget &
      DraftNavigationEffect)
  | ({
      op: "select";
      values: string[];
      labels?: string[];
    } & DraftStateLink &
      DraftTarget &
      DraftNavigationEffect)
  | ({ op: "scroll" } & DraftStateLink)
  | ({ op: "switch_tab" } & DraftStateLink)
  | ({
      op: "navigate";
      url: string;
      cause?: NavigationCause;
      transitionType?: string;
      transitionQualifiers?: string[];
    } & DraftStateLink);
 export type TargetedRecordingDraft = Extract<
  RecordingDraftStep,
  { op: "click" | "hover" | "fill" | "press" | "select" }
 >;
@@ -1,10 +1,30 @@
-import type { PageRefV2, SelectedOptionV2, StepV2, TraceV2 } from "@/transport/types";
+import type { DraftTraceStep, PageRef, SelectedOption, Step } from "@/transport/types";
-import { resolveDraftStartUrl, shouldIncludeDraft } from "./draft-policy";
+
-import type { RecordingDraftStep } from "./types";
+const CLIPBOARD_KEYS = new Set(["a", "c", "v", "x", "A", "C", "V", "X"]);
 const MODIFIER_ONLY_KEYS = new Set(["Meta", "Control", "Alt", "Shift", "OS", "Hyper", "Super"]);
 export function shouldRecordPress(
  key: string,
  modifiers?: Array<"alt" | "ctrl" | "meta" | "shift">,
 ): boolean {
  if (MODIFIER_ONLY_KEYS.has(key)) return false;
  const mods = modifiers ?? [];
  const hasCtrlOrMeta = mods.includes("ctrl") || mods.includes("meta");
  if (hasCtrlOrMeta && CLIPBOARD_KEYS.has(key)) return false;
  if (key === "Enter" || key === "Escape") return true;
  // Drop bare character typing — FillSession already records the value.
  if (key.length === 1 && !hasCtrlOrMeta && !mods.includes("alt")) return false;
  return false;
 }
 function shouldIncludeDraft(step: DraftTraceStep): boolean {
  if (step.op === "press" && !shouldRecordPress(step.key, step.modifiers)) return false;
  return true;
 }
 /** Collapse consecutive navigations to the last hop. */
-function collapseNavigations(steps: RecordingDraftStep[]): RecordingDraftStep[] {
+function collapseNavigations(steps: DraftTraceStep[]): DraftTraceStep[] {
-  const out: RecordingDraftStep[] = [];
+  const out: DraftTraceStep[] = [];
  for (const step of steps) {
    const prev = out[out.length - 1];
    if (step.op === "navigate" && prev?.op === "navigate") {
@@ -16,7 +36,7 @@ function collapseNavigations(steps: RecordingDraftStep[]): RecordingDraftStep[]
  return out;
 }
-function collectUrls(steps: RecordingDraftStep[], startUrl?: string): string[] {
+function collectUrls(steps: DraftTraceStep[], startUrl?: string): string[] {
  const urls: string[] = [];
  if (startUrl) urls.push(startUrl);
  for (const step of steps) {
@@ -24,8 +44,8 @@ function collectUrls(steps: RecordingDraftStep[], startUrl?: string): string[] {
      urls.push(step.url);
      continue;
    }
-    if (step.pageUrl) urls.push(step.pageUrl);
+    if ("page_url" in step && step.page_url) urls.push(step.page_url);
-    if ("navigatedTo" in step && step.navigatedTo) urls.push(step.navigatedTo);
+    if ("navigated_to" in step && step.navigated_to) urls.push(step.navigated_to);
  }
  const seen = new Set<string>();
  const unique: string[] = [];
@@ -38,9 +58,9 @@ function collectUrls(steps: RecordingDraftStep[], startUrl?: string): string[] {
 }
 function buildPageRegistry(
-  steps: RecordingDraftStep[],
+  steps: DraftTraceStep[],
  startUrl?: string,
-): { pages: PageRefV2[]; urlToId: Map<string, string> } {
+): { pages: PageRef[]; urlToId: Map<string, string> } {
  const urls = collectUrls(steps, startUrl);
  const urlToId = new Map<string, string>();
  const pages = urls.map((url, index) => {
@@ -61,28 +81,28 @@ function pageIdFor(
  return urlToId.values().next().value ?? "p1";
 }
-function pageUrlForDraft(step: RecordingDraftStep, fallbackUrl?: string): string | undefined {
+function pageUrlForDraft(step: DraftTraceStep, fallbackUrl?: string): string | undefined {
-  if (step.op === "navigate") return step.pageUrl ?? step.url;
+  if (step.op === "navigate") return step.page_url ?? step.url;
-  if (step.pageUrl) return step.pageUrl;
+  if ("page_url" in step && step.page_url) return step.page_url;
  return fallbackUrl;
 }
 function effectForNavigation(
  navigatedTo: string | undefined,
  urlToId: Map<string, string>,
-): StepV2["effect"] {
+): Step["effect"] {
  if (!navigatedTo) return undefined;
  const pageId = urlToId.get(navigatedTo);
  if (!pageId) return undefined;
  return { navigated_to: pageId };
 }
-function withEffect(step: StepV2, effect: StepV2["effect"]): StepV2 {
+function withEffect(step: Step, effect: Step["effect"]): Step {
  if (!effect) return step;
  return { ...step, effect };
 }
-function toSelection(values: string[], labels?: string[]): SelectedOptionV2[] {
+function toSelection(values: string[], labels?: string[]): SelectedOption[] {
  return values.map((value, index) => ({
    value,
    ...(labels?.[index] ? { label: labels[index] } : {}),
@@ -90,11 +110,11 @@ function toSelection(values: string[], labels?: string[]): SelectedOptionV2[] {
 }
 function toV2Step(
-  step: RecordingDraftStep,
+  step: DraftTraceStep,
  id: number,
  urlToId: Map<string, string>,
  fallbackUrl?: string,
-): StepV2 | null {
+): Step | null {
  if (!shouldIncludeDraft(step)) return null;
  const pageUrl = pageUrlForDraft(step, fallbackUrl);
@@ -109,23 +129,28 @@ function toV2Step(
        to: step.url,
      };
    case "click":
      if (!step.captureTarget) return null;
      return withEffect(
        {
          op: "click",
          id,
          page,
-          target: step.captureTarget,
+          target: step.target,
        },
-        effectForNavigation(step.navigatedTo, urlToId),
+        effectForNavigation(step.navigated_to, urlToId),
      );
    case "hover":
      return {
        op: "hover",
        id,
        page,
        target: step.target,
      };
    case "fill":
      if (!step.captureTarget) return null;
      return {
        op: "fill",
        id,
        page,
-        target: step.captureTarget,
+        target: step.target,
        value: step.value,
        ...(step.redacted ? { redacted: true } : {}),
      };
@@ -136,51 +161,44 @@ function toV2Step(
          id,
          page,
          key: step.key,
-          ...(step.captureTarget ? { target: step.captureTarget } : {}),
+          ...(step.target ? { target: step.target } : {}),
          ...(step.modifiers?.length ? { modifiers: step.modifiers } : {}),
        },
-        effectForNavigation(step.navigatedTo, urlToId),
+        effectForNavigation(step.navigated_to, urlToId),
      );
    case "select":
      if (!step.captureTarget) return null;
      return withEffect(
        {
          op: "select",
          id,
          page,
-          target: step.captureTarget,
+          target: step.target,
          selection: toSelection(step.values, step.labels),
        },
-        effectForNavigation(step.navigatedTo, urlToId),
+        effectForNavigation(step.navigated_to, urlToId),
      );
    // `hover` only exists in Trace v3. Peers that negotiate v2 predate the
    // step variant and fail to decode the whole result if we emit it.
    case "hover":
    case "scroll":
    case "switch_tab":
      return null;
  }
 }
-interface ReducedTrace {
+export interface ReducedTrace {
-  pages: PageRefV2[];
+  pages: PageRef[];
-  steps: StepV2[];
+  steps: Step[];
 }
 /**
 * Compile capture drafts into record-only trace v2 steps.
 * Variable inputs are NOT classified here — executing agents infer that at run time.
 */
-function reduceTraceSteps(steps: RecordingDraftStep[], startUrl?: string): ReducedTrace {
+export function reduceTraceSteps(steps: DraftTraceStep[], startUrl?: string): ReducedTrace {
  const collapsed = collapseNavigations(steps);
  const { pages, urlToId } = buildPageRegistry(collapsed, startUrl);
-  const out: StepV2[] = [];
+  const out: Step[] = [];
  let id = 1;
  let lastUrl = startUrl;
  for (const draft of collapsed) {
    if (draft.op === "navigate") lastUrl = draft.url;
-    else if ("navigatedTo" in draft && draft.navigatedTo) lastUrl = draft.navigatedTo;
+    else if ("navigated_to" in draft && draft.navigated_to) lastUrl = draft.navigated_to;
-    else if (draft.pageUrl) lastUrl = draft.pageUrl;
+    else if ("page_url" in draft && draft.page_url) lastUrl = draft.page_url;
    const step = toV2Step(draft, id, urlToId, lastUrl);
    if (!step) continue;
    out.push(step);
@@ -189,27 +207,18 @@ function reduceTraceSteps(steps: RecordingDraftStep[], startUrl?: string): Reduc
  return { pages, steps: out };
 }
-function resolveTraceStartUrl(
+export function resolveTraceStartUrl(
-  drafts: RecordingDraftStep[],
+  drafts: DraftTraceStep[],
  startUrl?: string,
-  pages?: PageRefV2[],
+  pages?: PageRef[],
 ): string {
-  return resolveDraftStartUrl(drafts, startUrl, pages?.[0]?.url);
+  if (startUrl) return startUrl;
-}
+  const navigate = drafts.find((step): step is Extract<DraftTraceStep, { op: "navigate" }> => {
-
+    return step.op === "navigate";
-export function buildTraceV2(input: {
+  });
-  steps: RecordingDraftStep[];
+  if (navigate) return navigate.url;
-  startedAt: string;
+  for (const draft of drafts) {
-  startUrl?: string;
+    if ("page_url" in draft && draft.page_url) return draft.page_url;
-  purpose?: string;
+  }
-}): TraceV2 {
+  return pages?.[0]?.url ?? "about:blank";
  const { pages, steps } = reduceTraceSteps(input.steps, input.startUrl);
  return {
    recorded_at: new Date().toISOString(),
    started_at: input.startedAt,
    ...(input.purpose ? { purpose: input.purpose } : {}),
    entry: { start_url: resolveTraceStartUrl(input.steps, input.startUrl, pages) },
    pages,
    steps,
  };
 }
@@ -9,7 +9,7 @@ describe("disconnect session cleanup", () => {
    const manager = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => nextWindowId++),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
        remove,
      },
    });
@@ -41,7 +41,7 @@ describe("disconnect session cleanup", () => {
    const manager = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 100),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
        remove: vi.fn(() => removeGate),
      },
    });
@@ -39,7 +39,7 @@ describe("attachSessionEventHandler", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    await manager.start("aa11");
@@ -73,7 +73,7 @@ describe("attachSessionEventHandler", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const ctx = await manager.start("aa11");
@@ -87,7 +87,6 @@ describe("attachSessionEventHandler", () => {
      windowEvents: events.api,
    });
    manager.forgetClosedTab(7, { isWindowClosing: true });
    events.emit(4242);
    for (let i = 0; i < 4; i += 1) await Promise.resolve();
@@ -114,7 +113,7 @@ describe("attachSessionEventHandler", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const transport = fakeTransport();
@@ -130,7 +129,7 @@ describe("attachSessionEventHandler", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const transport = fakeTransport();
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import type { AgentWindowApi, AgentWindowCreateOptions } from "../agent-window";
-import { isAgentControlledTab, SessionManager } from "../manager";
+import { SessionManager } from "../manager";
 function fakeAgentWindow(): AgentWindowApi & {
  createMock: ReturnType<typeof vi.fn>;
@@ -13,7 +13,7 @@ function fakeAgentWindow(): AgentWindowApi & {
    return id;
  });
  const removeMock = vi.fn(async (_id: number) => {});
-  const ensureActiveTabMock = vi.fn(async (_windowId: number, _url: string) => 0);
+  const ensureActiveTabMock = vi.fn(async (_windowId: number, _url: string) => {});
  return {
    create: createMock,
    remove: removeMock,
@@ -151,76 +151,6 @@ describe("SessionManager", () => {
    expect(sm.list()).toEqual([]);
  });
  describe("explicit tab claims", () => {
    it("claims the exact home tab returned by AgentWindowApi", async () => {
      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
      const ctx = await sm.start("aa11");
      expect(ctx.agentCreatedTabs).toEqual(new Set([0]));
      expect(isAgentControlledTab(ctx, 0)).toBe(true);
    });
    it("keeps every other tab free without classification state", async () => {
      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
      const ctx = await sm.start("aa11");
      expect(isAgentControlledTab(ctx, 99)).toBe(false);
      expect(ctx).not.toHaveProperty("userTabs");
      expect(ctx).not.toHaveProperty("pendingAgentTabCount");
    });
    it("treats a committed borrow as an explicit claim", async () => {
      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
      const ctx = await sm.start("aa11");
      const reservation = sm.tryReserveBorrow(42, ctx.sessionId);
      if ("borrowedBy" in reservation) throw new Error("unexpected borrow conflict");
      reservation.commit({ tabId: 42, originalWindowId: 7, originalIndex: 3 });
      expect(isAgentControlledTab(ctx, 42)).toBe(true);
    });
    it("forgets an agent-created tab after Chrome removes it", async () => {
      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
      const ctx = await sm.start("aa11");
      ctx.agentCreatedTabs.add(42);
      sm.forgetClosedTab(42);
      expect(ctx.agentCreatedTabs.has(42)).toBe(false);
      expect(isAgentControlledTab(ctx, 0)).toBe(true);
    });
    it("forgets closed borrows idempotently without affecting other tabs or sessions", async () => {
      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
      const a = await sm.start("aa11");
      const b = await sm.start("bb22");
      a.borrowedTabs.set(42, { tabId: 42, originalWindowId: 7, originalIndex: 0 });
      a.borrowedTabs.set(43, { tabId: 43, originalWindowId: 7, originalIndex: 1 });
      b.borrowedTabs.set(44, { tabId: 44, originalWindowId: 8, originalIndex: 0 });
      sm.forgetClosedTab(42);
      sm.forgetClosedTab(42);
      sm.forgetClosedTab(999);
      expect(isAgentControlledTab(a, 42)).toBe(false);
      expect(sm.findBorrowingSession(42, null)).toBeNull();
      expect([...a.borrowedTabs.keys()]).toEqual([43]);
      expect([...b.borrowedTabs.keys()]).toEqual([44]);
      expect(sm.list()).toHaveLength(2);
    });
    it("prevents an in-flight borrow from reclaiming a closed tab", async () => {
      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
      const ctx = await sm.start("aa11");
      const reservation = sm.tryReserveBorrow(42, ctx.sessionId);
      if ("borrowedBy" in reservation) throw new Error("unexpected borrow conflict");
      sm.forgetClosedTab(42);
      expect(() =>
        reservation.commit({ tabId: 42, originalWindowId: 7, originalIndex: 0 }),
      ).toThrow(/reservation disappeared/);
      reservation.release();
      expect(sm.findBorrowingSession(42, null)).toBeNull();
      expect(ctx.borrowedTabs.has(42)).toBe(false);
    });
  });
  describe("findBorrowingSession", () => {
    it("returns null when no session has borrowed the tab", async () => {
      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
@@ -14,11 +14,8 @@ export interface AgentWindowApi {
   * Guarantee the Agent Window has an active, CDP-navigable tab.
   * `chrome://` pages (including the New Tab page) reject `Page.navigate`,
   * so sessions bootstrap with `about:blank` instead.
   *
   * Resolves with the id of the activated (or newly created) tab, so callers
   * can track the session's home tab without re-querying Chrome.
   */
-  ensureActiveTab(windowId: number, url: string): Promise<number>;
+  ensureActiveTab(windowId: number, url: string): Promise<void>;
 }
 /** Creation hints for a new Agent Window. */
@@ -52,19 +49,15 @@ export const chromeAgentWindowApi: AgentWindowApi = {
    // cancellation success while the Agent Window remains open.
    await chrome.windows.remove(windowId);
  },
-  async ensureActiveTab(windowId: number, url: string): Promise<number> {
+  async ensureActiveTab(windowId: number, url: string): Promise<void> {
    const tabs = await chrome.tabs.query({ windowId });
    const first = tabs.find((t) => typeof t.id === "number");
-    if (first?.id !== undefined) {
+    if (first?.id) {
      if (!first.active) {
        await chrome.tabs.update(first.id, { active: true });
      }
-      return first.id;
+      return;
    }
-    const created = await chrome.tabs.create({ windowId, url, active: true });
+    await chrome.tabs.create({ windowId, url, active: true });
    if (typeof created?.id !== "number") {
      throw new Error("[bh] chrome.tabs.create returned no tab id");
    }
    return created.id;
  },
 };
@@ -6,20 +6,9 @@ export interface SessionContext {
  agentWindowId: number;
  refStore: RefStore;
  borrowedTabs: Map<number, BorrowedTab>;
  /**
   * Tabs explicitly claimed by the agent because it created them. This
   * includes the Agent Window's home tab and tabs created by `tool.tab_create`.
   * Tabs opened through Chrome UI never enter this set.
   */
  agentCreatedTabs: Set<number>;
  createdAtMs: number;
 }
 /** Whether this session has explicitly claimed control of `tabId`. */
 export function isAgentControlledTab(ctx: SessionContext, tabId: number): boolean {
  return ctx.agentCreatedTabs.has(tabId) || ctx.borrowedTabs.has(tabId);
 }
 export interface BorrowedTab {
  tabId: number;
  originalWindowId: number;
@@ -117,19 +106,6 @@ export class SessionManager {
    return Array.from(this.sessions.values());
  }
  /**
   * Forget a tab Chrome has removed, including any uncommitted borrow.
   * Whole-window closures keep committed borrows until the window-removed
   * handler reports which user tabs could not be returned.
   */
  forgetClosedTab(tabId: number, { isWindowClosing = false } = {}): void {
    this.borrowReservations.delete(tabId);
    for (const ctx of this.sessions.values()) {
      ctx.agentCreatedTabs.delete(tabId);
      if (!isWindowClosing) ctx.borrowedTabs.delete(tabId);
    }
  }
  /**
   * Look up whether `tabId` is currently borrowed by some *other*
   * session than the one calling. Used by M8 `tab_borrow` to refuse
@@ -203,7 +179,7 @@ export class SessionManager {
      const { signal: _signal, ...createOptions } = opts;
      windowId = await this.agentWindow.create(AGENT_WINDOW_HOME, createOptions);
      throwIfSessionStartAborted(opts.signal);
-      const homeTabId = await this.agentWindow.ensureActiveTab(windowId, AGENT_WINDOW_HOME);
+      await this.agentWindow.ensureActiveTab(windowId, AGENT_WINDOW_HOME);
      throwIfSessionStartAborted(opts.signal);
      const ctx: SessionContext = {
@@ -211,10 +187,6 @@ export class SessionManager {
        agentWindowId: windowId,
        refStore: new RefStore(),
        borrowedTabs: new Map(),
        // The home tab is the session's first explicit claim. Every other
        // tab remains free until `tab_create` or `tab_borrow` identifies it
        // by its concrete Chrome tab id.
        agentCreatedTabs: new Set([homeTabId]),
        createdAtMs: this.now(),
      };
      this.sessions.set(sessionId, ctx);
@@ -1,22 +0,0 @@
 export const RECORD_DOCUMENT_ATTRIBUTE = "data-bsk-record-document";
 const RECORDING_DOCUMENT_ID_PATTERN =
  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const RECORDING_DOCUMENT_MARKER_PREFIX = "bsk:";
 export function recordingDocumentMarkerValue(identity: string): string {
  if (!RECORDING_DOCUMENT_ID_PATTERN.test(identity)) {
    throw new TypeError("recording Document identity must be a random UUID");
  }
  return `${RECORDING_DOCUMENT_MARKER_PREFIX}${identity}`;
 }
 /** Read BrowserSkill's opaque per-Document recording identity from captured attributes. */
 export function readRecordingDocumentIdentity(
  attrs: Readonly<Record<string, string>>,
 ): string | undefined {
  const marker = attrs[RECORD_DOCUMENT_ATTRIBUTE];
  if (!marker?.startsWith(RECORDING_DOCUMENT_MARKER_PREFIX)) return undefined;
  const identity = marker.slice(RECORDING_DOCUMENT_MARKER_PREFIX.length);
  return identity && RECORDING_DOCUMENT_ID_PATTERN.test(identity) ? identity : undefined;
 }
@@ -127,38 +127,6 @@ describe("requestBorrowConfirmation", () => {
    expect(message.requestId.length).toBeGreaterThan(0);
  });
  it("proactively focuses the user window before sending the overlay message", async () => {
    tabs.get.mockResolvedValueOnce({ id: 42, title: "Tab" });
    windows.getLastFocused.mockResolvedValueOnce(
      userWindowWithActiveTab({ windowId: 77, tabId: 7, url: "https://app.example/" }),
    );
    tabs.sendMessage.mockResolvedValueOnce({ type: "borrow-response", allowed: true });
    const pending = requestBorrowConfirmation(42, {
      deps: { tabs, windows, notifications },
    });
    await vi.runAllTimersAsync();
    await pending;
    expect(windows.update).toHaveBeenCalledWith(77, { focused: true });
  });
  it("still proceeds when proactive window focus fails", async () => {
    tabs.get.mockResolvedValueOnce({ id: 42, title: "Tab" });
    windows.getLastFocused.mockResolvedValueOnce(
      userWindowWithActiveTab({ windowId: 77, tabId: 7, url: "https://app.example/" }),
    );
    windows.update.mockRejectedValueOnce(new Error("window gone"));
    tabs.sendMessage.mockResolvedValueOnce({ type: "borrow-response", allowed: true });
    const pending = requestBorrowConfirmation(42, {
      deps: { tabs, windows, notifications },
    });
    await vi.runAllTimersAsync();
    expect(await pending).toBe(true);
  });
  it("sends confirmation to the borrow target when it is the active tab", async () => {
    tabs.get.mockResolvedValueOnce({ id: 42, title: "Active Tab" });
    windows.getLastFocused.mockResolvedValueOnce(
@@ -13,7 +13,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
  };
 }
@@ -8,7 +8,6 @@ import type {
  RequestFrame,
 } from "@/transport/types";
 import { ToolDispatcher } from "../dispatcher";
 import { resetBrowserObservationForTests, setBrowserObservationAttachForTests } from "../record";
 type TestDispatcherCdp = NonNullable<ConstructorParameters<typeof ToolDispatcher>[0]["cdp"]>;
@@ -45,120 +44,16 @@ function makeRequest(method: string, params: unknown): RequestFrame {
 describe("ToolDispatcher", () => {
  afterEach(() => {
    resetBrowserObservationForTests();
    vi.unstubAllGlobals();
  });
  it.each([
    "tool.snapshot",
    "tool.evaluate",
    "tool.get_html",
    "tool.console",
  ])("annotates Chrome extension-access failures from %s", async (method) => {
    const tab = { id: 7, windowId: 4242, active: true, url: "https://example.test" };
    vi.stubGlobal("chrome", {
      tabs: {
        get: vi.fn(async () => tab),
        query: vi.fn(async () => [tab]),
      },
    });
    const { transport, sent, deliver } = fakeTransport();
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(),
        ensureActiveTab: vi.fn(),
      },
    });
    await sessions.start("test");
    const error = new Error("Cannot access a chrome-extension:// URL of different extension");
    const cdp = {
      send: vi.fn().mockRejectedValue(error),
      ensureConsoleCapture: vi.fn().mockRejectedValue(error),
      consoleEntriesSince: vi.fn(),
    } as unknown as TestDispatcherCdp;
    const dispatcher = new ToolDispatcher({ transport, sessions, cdp });
    dispatcher.start();
    deliver(makeRequest(method, { session_id: "test", expression: "document.title" }));
    await vi.waitFor(() => expect(sent).toHaveLength(1));
    expect(sent[0]).toMatchObject({
      error: {
        code: "cdp_failed",
        data: { reason: "cdp_extension_access_denied" },
      },
    });
    dispatcher.stop();
  });
  it("uses the configured recording runtime for start and stop", async () => {
    const { transport, sent, deliver } = fakeTransport();
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(),
        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await sessions.start("aa11");
    const tab = {
      id: 7,
      windowId: 4242,
      active: true,
      status: "complete",
      url: "https://example.com/start",
    } as chrome.tabs.Tab;
    const frameCoordinator = {
      begin: vi.fn(),
      armTab: vi.fn(async () => true),
      sourceFor: vi.fn(() => null),
      stop: vi.fn(async () => true),
      cancel: vi.fn(),
    };
    const sendToTab = vi.fn(async () => ({ ok: true }));
    setBrowserObservationAttachForTests(
      () => () => {},
      () => () => {},
    );
    const dispatcher = new ToolDispatcher({
      transport,
      sessions,
      recording: {
        tabsApi: {
          get: vi.fn(async () => tab),
          query: vi.fn(async () => [tab]),
        },
        frameCoordinator,
        sendToTab,
      },
    });
    dispatcher.start();
    deliver(
      makeRequest("tool.record_start", {
        session_id: "aa11",
        url: "https://example.com/start",
      }),
    );
    await vi.waitFor(() => expect(sent).toHaveLength(1));
    expect(sent[0]).toMatchObject({ result: { tab_id: 7, recording: true } });
    expect(frameCoordinator.begin).toHaveBeenCalledOnce();
    expect(frameCoordinator.armTab).toHaveBeenCalledWith(expect.any(String), 7);
    deliver({ id: "r-2", method: "tool.record_stop", params: { session_id: "aa11" } });
    await vi.waitFor(() => expect(sent).toHaveLength(2));
    expect(frameCoordinator.stop).toHaveBeenCalledOnce();
    expect(sent[1]).toMatchObject({ id: "r-2", result: { trace: { steps: [] } } });
  });
  it("routes tool.session_start to the SessionManager and replies with the window id", async () => {
    const { transport, sent, deliver } = fakeTransport();
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -181,7 +76,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create,
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -199,7 +94,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    await sessions.start("aa11");
@@ -213,47 +108,6 @@ describe("ToolDispatcher", () => {
    expect(sent[0]).toEqual({ id: "r-1", result: {} });
  });
  it("wires the production tab APIs into tool.session_stop so a surviving user tab releases the window", async () => {
    // Regression guard for the deps that session_stop reads directly: when
    // `tabManagement.tabs` / `tabsQuery` are not injected by the dispatcher,
    // the agent-tab cleanup and the release decision silently no-op and the
    // Agent Window is closed even though a user tab is still open (issue #57).
    const removeTab = vi.fn(async () => {});
    const closeWindow = vi.fn(async () => {});
    // After cleanup the window still holds one tab (id 99) that is neither
    // the home tab nor an agent-created tab — i.e. a genuine user tab.
    vi.stubGlobal("chrome", {
      tabs: {
        remove: removeTab,
        query: vi.fn(async () => [{ id: 99, windowId: 4242, active: true }]),
      },
    });
    const { transport, sent, deliver } = fakeTransport();
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: closeWindow,
        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await sessions.start("aa11");
    // Register the exact tab id returned by the agent's creation path.
    sessions.get("aa11")?.agentCreatedTabs.add(7);
    const dispatcher = new ToolDispatcher({ transport, sessions });
    dispatcher.start();
    deliver(makeRequest("tool.session_stop", { session_id: "aa11" }));
    await flushMicrotasks();
    // The agent tab is closed through the real chrome.tabs surface...
    expect(removeTab).toHaveBeenCalledWith(7);
    // ...and the window is released rather than closed, so the user's tab survives.
    expect(closeWindow).not.toHaveBeenCalled();
    expect(sessions.has("aa11")).toBe(false);
    expect(sent[0]).toEqual({ id: "r-1", result: { window_released: true } });
  });
  it("routes tool.console through the CDP console buffer", async () => {
    vi.stubGlobal("chrome", {
      tabs: {
@@ -265,7 +119,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    await sessions.start("aa11");
@@ -328,7 +182,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const ctx = await sessions.start("aa11");
@@ -421,7 +275,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    await sessions.start("aa11");
@@ -450,62 +304,13 @@ describe("ToolDispatcher", () => {
    expect(sent[0]).toEqual({ id: "r-1", result: {} });
  });
  it("forwards daemon cancellation into an in-flight session stop", async () => {
    const { transport, sent, deliver } = fakeTransport();
    const remove = vi.fn(async () => {});
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove,
        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await sessions.start("aa11");
    let finishDetach: () => void = () => {};
    const detach = new Promise<void>((resolve) => {
      finishDetach = resolve;
    });
    const cdp = {
      send: vi.fn(),
      detachSession: vi.fn(() => detach),
      ensureNetworkCapture: vi.fn(async () => {}),
      networkEntriesSince: vi.fn(() => ({
        tab_id: 7,
        entries: [],
        next_since: 0,
        truncated: false,
      })),
      setDeviceMetricsOverride: vi.fn(async () => {}),
      clearDeviceMetricsOverride: vi.fn(async () => {}),
      setUserAgentOverride: vi.fn(async () => {}),
      setTouchEmulationEnabled: vi.fn(async () => {}),
    };
    const dispatcher = new ToolDispatcher({ transport, sessions, cdp: cdp as TestDispatcherCdp });
    dispatcher.start();
    deliver(makeRequest("tool.session_stop", { session_id: "aa11" }));
    await vi.waitFor(() => expect(cdp.detachSession).toHaveBeenCalledWith("aa11"));
    deliver({ id: "cancel-stop", method: "cancel", params: { rpc_id: "r-1" } });
    await flushMicrotasks();
    finishDetach();
    await flushMicrotasks();
    expect(sent).toContainEqual({ id: "cancel-stop", result: { cancelled: true } });
    expect(sent).toContainEqual({
      id: "r-1",
      error: expect.objectContaining({ code: "cancelled" }),
    });
    expect(sessions.has("aa11")).toBe(true);
    expect(remove).not.toHaveBeenCalled();
  });
  it("returns not_found when stopping an unknown session", async () => {
    const { transport, sent, deliver } = fakeTransport();
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -525,7 +330,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -549,7 +354,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -566,7 +371,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -583,7 +388,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const onSessionsChanged = vi.fn();
@@ -600,32 +405,16 @@ describe("ToolDispatcher", () => {
  });
  it("invokes onBrowserControlResumed for browser-control tools but not passive reads", async () => {
    vi.stubGlobal("chrome", {
      tabs: {
        create: vi.fn(async (props: chrome.tabs.CreateProperties) => ({
          id: 7,
          windowId: props.windowId,
          url: props.url,
          active: props.active,
        })),
      },
    });
    const { transport, sent, deliver } = fakeTransport();
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const onBrowserControlResumed = vi.fn();
-    const onAgentTabClaimed = vi.fn();
+    const dispatcher = new ToolDispatcher({ transport, sessions, onBrowserControlResumed });
    const dispatcher = new ToolDispatcher({
      transport,
      sessions,
      onBrowserControlResumed,
      onAgentTabClaimed,
    });
    dispatcher.start();
    deliver(makeRequest("tool.session_start", { session_id: "aa11" }));
@@ -642,7 +431,6 @@ describe("ToolDispatcher", () => {
    });
    await flushMicrotasks();
    expect(onBrowserControlResumed).toHaveBeenCalledWith("aa11");
    expect(onAgentTabClaimed).toHaveBeenCalledWith(7, 1);
  });
  it("reasserts remembered hover before follow-up work and releases only after actions", async () => {
@@ -656,7 +444,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const order: string[] = [];
@@ -738,7 +526,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const cdp = {
@@ -788,135 +576,6 @@ describe("ToolDispatcher", () => {
    );
  });
  it.each([
    { tab_id: 7, code: "not_found" },
    { tab_id: undefined, code: "invalid_params" },
  ])("keeps hover when tab_return is rejected with $code", async ({ tab_id, code }) => {
    const sendMessage = vi.fn(async () => undefined);
    vi.stubGlobal("chrome", {
      tabs: {
        sendMessage,
        get: vi.fn(async () => ({ id: 7, windowId: 100, active: true })),
        query: vi.fn(async () => [{ id: 7, windowId: 100, active: true }]),
      },
    });
    const { transport, sent, deliver } = fakeTransport();
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 100),
        remove: vi.fn(async () => {}),
        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await sessions.start("aa11");
    const cdp = {
      send: vi.fn(async <T>() => ({}) as T),
      detachSession: vi.fn(async () => {}),
      releaseSessionTab: vi.fn(async () => {}),
    };
    const dispatcher = new ToolDispatcher({
      transport,
      sessions,
      cdp: cdp as unknown as TestDispatcherCdp,
    });
    const helpers = dispatcher as unknown as {
      rememberHover: (sessionId: string, result: unknown) => unknown;
      setHoverBypass: (sessionId: string, tabId: number, enabled: boolean) => Promise<void>;
      withHoverReassert: <T>(
        params: { session_id: string; tab_id?: number },
        work: () => Promise<T>,
      ) => Promise<T>;
    };
    helpers.rememberHover("aa11", { tab_id: 7, x: 10, y: 20 });
    await helpers.setHoverBypass("aa11", 7, true);
    dispatcher.start();
    deliver(makeRequest("tool.tab_return", { session_id: "aa11", tab_id }));
    await vi.waitFor(() => expect(sent).toHaveLength(1));
    expect(sent[0]).toMatchObject({ error: { code } });
    expect(cdp.releaseSessionTab).not.toHaveBeenCalled();
    expect(sendMessage).not.toHaveBeenCalledWith(7, expect.objectContaining({ enabled: false }));
    await helpers.withHoverReassert({ session_id: "aa11", tab_id: 7 }, async () => ({}));
    expect(cdp.send).toHaveBeenCalledExactlyOnceWith(7, "Input.dispatchMouseEvent", {
      type: "mouseMoved",
      x: 10,
      y: 20,
    });
    dispatcher.stop();
  });
  it("releases the returned tab's hover before moving it and leaves other tabs alone", async () => {
    const sendMessage = vi.fn(async () => undefined);
    const move = vi.fn(async () => {
      expect(sendMessage).toHaveBeenCalledWith(7, expect.objectContaining({ enabled: false }));
      return { id: 7, windowId: 200, index: 4 };
    });
    vi.stubGlobal("chrome", {
      tabs: { sendMessage, move },
      windows: { get: vi.fn(async () => ({ id: 200 })) },
    });
    const { transport, sent, deliver } = fakeTransport();
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 100),
        remove: vi.fn(async () => {}),
        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const ctx = await sessions.start("aa11");
    ctx.borrowedTabs.set(7, { tabId: 7, originalWindowId: 200, originalIndex: 4 });
    const cdp = {
      send: vi.fn(async <T>() => ({}) as T),
      detachSession: vi.fn(async () => {}),
      releaseSessionTab: vi.fn(async () => {}),
    };
    const dispatcher = new ToolDispatcher({
      transport,
      sessions,
      cdp: cdp as unknown as TestDispatcherCdp,
    });
    const helpers = dispatcher as unknown as {
      rememberHover: (sessionId: string, result: unknown) => unknown;
      setHoverBypass: (sessionId: string, tabId: number, enabled: boolean) => Promise<void>;
      withHoverReassert: <T>(
        params: { session_id: string; tab_id?: number },
        work: () => Promise<T>,
      ) => Promise<T>;
    };
    for (const [sessionId, tabId] of [
      ["aa11", 7],
      ["aa11", 8],
      ["bb22", 9],
    ] as const) {
      helpers.rememberHover(sessionId, { tab_id: tabId, x: 10, y: 20 });
      await helpers.setHoverBypass(sessionId, tabId, true);
    }
    dispatcher.start();
    deliver(makeRequest("tool.tab_return", { session_id: "aa11", tab_id: 7 }));
    await vi.waitFor(() => expect(sent).toHaveLength(1));
    expect(sent[0]).toMatchObject({ result: { tab_id: 7, returned_to_window_id: 200 } });
    expect(cdp.releaseSessionTab).toHaveBeenCalledExactlyOnceWith("aa11", 7);
    await helpers.withHoverReassert({ session_id: "aa11", tab_id: 7 }, async () => ({}));
    expect(cdp.send).not.toHaveBeenCalled();
    for (const [sessionId, tabId] of [
      ["aa11", 8],
      ["bb22", 9],
    ] as const) {
      expect(sendMessage).not.toHaveBeenCalledWith(
        tabId,
        expect.objectContaining({ enabled: false }),
      );
      await helpers.withHoverReassert({ session_id: sessionId, tab_id: tabId }, async () => ({}));
      expect(cdp.send).toHaveBeenLastCalledWith(tabId, "Input.dispatchMouseEvent", {
        type: "mouseMoved",
        x: 10,
        y: 20,
      });
    }
    dispatcher.stop();
  });
  it("transfers hover overlay bypass ownership between sessions", async () => {
    vi.stubGlobal("chrome", {
      tabs: {
@@ -928,7 +587,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -965,7 +624,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    await sessions.start("aa11");
@@ -1017,7 +676,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -1051,7 +710,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    transport.send = () => {
@@ -1073,7 +732,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 5555),
        remove,
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    transport.send = () => {
@@ -1101,7 +760,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(() => createPromise),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -1152,7 +811,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -1173,7 +832,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(() => createPromise),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -20,7 +20,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
  };
 }
@@ -1,39 +0,0 @@
 import { describe, expect, it } from "vitest";
 import type { RpcError } from "@/transport/types";
 import { cdpError, classifyCdpError } from "../errors";
 const denied = "Cannot access a chrome-extension:// URL of different extension";
 describe("CDP extension access errors", () => {
  it("classifies both Chrome Error instances and string failures", () => {
    for (const error of [new Error(denied), denied]) {
      expect(cdpError(error)).toEqual({
        code: "cdp_failed",
        message: denied,
        data: { reason: "cdp_extension_access_denied" },
      });
    }
  });
  it("preserves transfer outcome and cleanup instructions when CDP was denied", () => {
    const error: RpcError = {
      code: "cdp_failed",
      message: denied,
      data: {
        reason: "transfer_outcome_unknown",
        effect_state: "unknown",
        cleanup_state: "failed",
      },
    };
    expect(classifyCdpError(error)).toBe(error);
  });
  it("leaves other error codes and unrelated debugger failures unchanged", () => {
    for (const error of [
      { code: "permission_denied", message: denied },
      { code: "cdp_failed", message: "Another debugger is already attached" },
    ] satisfies RpcError[]) {
      expect(classifyCdpError(error)).toBe(error);
    }
  });
 });
@@ -12,7 +12,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
  };
 }
@@ -2,7 +2,6 @@ import { describe, expect, it, vi } from "vitest";
 import { SessionManager } from "@/session-manager/manager";
 import { type DownloadsApi, handleDownload } from "../download";
 import { captureBrowserDownload } from "../download-capture";
 import { uploadThroughFileDrop } from "../file-drop-transaction";
 import { uploadThroughActivatedFileInput } from "../file-input-transaction";
 import type { ResolvedActionTarget } from "../interaction";
 import type { CdpRunner } from "../shared";
@@ -13,7 +12,7 @@ function sessions() {
    agentWindow: {
      create: vi.fn(async () => 100),
      remove: vi.fn(async () => {}),
-      ensureActiveTab: vi.fn(async () => 1),
+      ensureActiveTab: vi.fn(async () => {}),
    },
  });
 }
@@ -38,20 +37,16 @@ function fakeEvent<T extends (...args: never[]) => unknown>() {
  };
 }
-function actionTarget(frameId?: string, sessionId?: string): ResolvedActionTarget {
+function actionTarget(frameId?: string): ResolvedActionTarget {
  return {
    tab: { tabId: 4, windowId: 100, active: true },
    backendNodeId: 123,
-    cdpTarget: { tabId: 4, ...(sessionId ? { sessionId } : {}) },
+    cdpTarget: { tabId: 4 },
    ...(frameId ? { frameId } : {}),
    usedRef: "e3",
  };
 }
 function withoutOverlay<T>(operation: () => Promise<T>): Promise<T> {
  return operation();
 }
 function uploadCdp(
  options: {
    inputCount?: number;
@@ -64,7 +59,6 @@ function uploadCdp(
  let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
  const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
    calls.push({ method, params });
    if (method === "DOM.scrollIntoViewIfNeeded") return {};
    if (method === "Page.setInterceptFileChooserDialog") return {};
    if (method === "Page.getLayoutMetrics")
      return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
@@ -116,50 +110,6 @@ function uploadCdp(
  };
 }
 function dropCdp(
  options: {
    targetContainsPoint?: boolean;
    dispatchError?: (type: string) => Error | Promise<never> | undefined;
    onCall?: (method: string) => void;
  } = {},
 ) {
  const calls: Array<{ method: string; params?: object }> = [];
  const detach = vi.fn(async () => {});
  const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
    calls.push({ method, params });
    options.onCall?.(method);
    if (method === "DOM.scrollIntoViewIfNeeded") return {};
    if (method === "Page.getLayoutMetrics") {
      return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
    }
    if (method === "DOM.getContentQuads") {
      return { quads: [[10, 20, 210, 20, 210, 120, 10, 120]] };
    }
    if (method === "DOM.getNodeForLocation") return { backendNodeId: 124 };
    if (method === "DOM.resolveNode") {
      const id = (params as { backendNodeId?: number }).backendNodeId;
      return { object: { objectId: id === 123 ? "drop-target" : "hit-target" } };
    }
    if (method === "Runtime.callFunctionOn") {
      return { result: { value: options.targetContainsPoint ?? true } };
    }
    if (method === "Input.dispatchDragEvent") {
      const type = (params as { type?: string }).type ?? "";
      const error = options.dispatchError?.(type);
      if (error instanceof Promise) return error;
      if (error) throw error;
      return {};
    }
    if (method === "Runtime.releaseObjectGroup") return {};
    throw new Error(`unexpected drop CDP command ${method}`);
  });
  const cdp: CdpRunner = {
    send: send as unknown as CdpRunner["send"],
    detach,
  };
  return { calls, cdp, detach };
 }
 describe("file transfer tools", () => {
  it("captures the file input activated by the requested click and injects only staged paths", async () => {
    const manager = sessions();
@@ -321,236 +271,6 @@ describe("file transfer tools", () => {
    expect(detach).toHaveBeenCalledWith(4);
  });
  it("delivers staged files through one explicit native drop without clicking", async () => {
    const manager = sessions();
    const ctx = await manager.start("s1");
    ctx.refStore.set("e3", 123, { tabId: 4 });
    const lifecycle: string[] = [];
    const { cdp, calls } = dropCdp({ onCall: (method) => lifecycle.push(method) });
    const overlayPhases: string[] = [];
    const result = await handleUpload(
      manager,
      {
        session_id: "s1",
        ref: "@e3",
        mode: "drop",
        files: [{ transfer_id: "tr_1", name: "one.png", staged_path: "/stage/one.png" }],
      },
      {
        cdp,
        tabsApi: tabsApi(),
        sendToTab: vi.fn(async (_tabId, message) => {
          overlayPhases.push(message.phase);
          lifecycle.push(`overlay:${message.phase}`);
        }),
      },
    );
    expect(result).toMatchObject({ tab_id: 4, used_ref: "e3", file_names: ["one.png"] });
    expect(calls.filter((call) => call.method === "Input.dispatchDragEvent")).toEqual([
      {
        method: "Input.dispatchDragEvent",
        params: {
          type: "dragEnter",
          x: 110,
          y: 70,
          data: { items: [], files: ["/stage/one.png"], dragOperationsMask: 1 },
        },
      },
      {
        method: "Input.dispatchDragEvent",
        params: {
          type: "dragOver",
          x: 110,
          y: 70,
          data: { items: [], files: ["/stage/one.png"], dragOperationsMask: 1 },
        },
      },
      {
        method: "Input.dispatchDragEvent",
        params: {
          type: "drop",
          x: 110,
          y: 70,
          data: { items: [], files: ["/stage/one.png"], dragOperationsMask: 1 },
        },
      },
    ]);
    expect(calls.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
    expect(overlayPhases).toEqual(["begin", "end"]);
    expect(lifecycle.indexOf("DOM.getContentQuads")).toBeLessThan(
      lifecycle.indexOf("overlay:begin"),
    );
    expect(lifecycle.indexOf("overlay:begin")).toBeLessThan(
      lifecycle.indexOf("DOM.getNodeForLocation"),
    );
    expect(lifecycle.lastIndexOf("Input.dispatchDragEvent")).toBeLessThan(
      lifecycle.indexOf("overlay:end"),
    );
    expect(lifecycle.indexOf("overlay:end")).toBeLessThan(
      lifecycle.indexOf("Runtime.releaseObjectGroup"),
    );
  });
  it("fails closed before dragging when another element owns the action point", async () => {
    const { cdp, calls } = dropCdp({ targetContainsPoint: false });
    const result = await uploadThroughFileDrop({
      cdp,
      actionTarget: actionTarget(),
      files: ["/stage/one.png"],
      timeoutMs: 100,
      withOverlayHidden: withoutOverlay,
    });
    expect(result).toMatchObject({
      code: "permission_denied",
      data: {
        reason: "file_drop_target_unavailable",
        mechanism: "drop",
        effect_state: "none",
        phase: "resolve_target",
      },
    });
    expect(calls.some((call) => call.method === "Input.dispatchDragEvent")).toBe(false);
  });
  it("dispatches an OOPIF file drop in the child target's local coordinates", async () => {
    const rootCalls: Array<{ method: string; params?: object }> = [];
    const childCalls: Array<{ method: string; params?: object }> = [];
    const cdp: CdpRunner = {
      send: vi.fn(async (_tabId, method, params) => {
        rootCalls.push({ method, params });
        if (method === "DOM.scrollIntoViewIfNeeded") return {};
        if (method === "DOM.getBoxModel") {
          return { model: { content: [100, 100, 300, 100, 300, 200, 100, 200] } };
        }
        if (method === "Page.getLayoutMetrics") {
          return { cssLayoutViewport: { clientWidth: 800, clientHeight: 600 } };
        }
        throw new Error(`unexpected root command ${method}`);
      }) as CdpRunner["send"],
      sendToTarget: vi.fn(async (_target, method, params) => {
        childCalls.push({ method, params });
        if (method === "DOM.scrollIntoViewIfNeeded") return {};
        if (method === "DOM.getContentQuads") {
          return { quads: [[10, 20, 210, 20, 210, 120, 10, 120]] };
        }
        if (method === "Page.getLayoutMetrics") {
          return { cssLayoutViewport: { clientWidth: 400, clientHeight: 300 } };
        }
        if (method === "DOM.getNodeForLocation") {
          return { backendNodeId: 124, frameId: "child" };
        }
        if (method === "DOM.resolveNode") {
          const id = (params as { backendNodeId?: number }).backendNodeId;
          return { object: { objectId: id === 123 ? "drop-target" : "hit-target" } };
        }
        if (method === "Runtime.callFunctionOn") return { result: { value: true } };
        if (method === "Input.dispatchDragEvent" || method === "Runtime.releaseObjectGroup") {
          return {};
        }
        throw new Error(`unexpected child command ${method}`);
      }) as CdpRunner["sendToTarget"],
      getFrameGraph: vi.fn(async () => ({
        rootFrameId: "main",
        frames: [
          { frameId: "main", target: { tabId: 4 } },
          {
            frameId: "child",
            parentFrameId: "main",
            ownerBackendNodeId: 10,
            target: { tabId: 4, sessionId: "child-session" },
          },
        ],
      })),
    };
    const result = await uploadThroughFileDrop({
      cdp,
      actionTarget: actionTarget("child", "child-session"),
      files: ["/stage/one.png"],
      timeoutMs: 100,
      withOverlayHidden: withoutOverlay,
    });
    expect(result).toMatchObject({ x: 110, y: 70 });
    expect(
      childCalls
        .filter((call) => call.method === "Input.dispatchDragEvent")
        .map((call) => call.params),
    ).toEqual([
      expect.objectContaining({ type: "dragEnter", x: 110, y: 70 }),
      expect.objectContaining({ type: "dragOver", x: 110, y: 70 }),
      expect.objectContaining({ type: "drop", x: 110, y: 70 }),
    ]);
    expect(rootCalls.some((call) => call.method === "Input.dispatchDragEvent")).toBe(false);
  });
  it("reports a missing native drag command as unsupported before commit", async () => {
    const { cdp } = dropCdp({
      dispatchError: (type) =>
        type === "dragEnter" ? new Error("'Input.dispatchDragEvent' wasn't found") : undefined,
    });
    const result = await uploadThroughFileDrop({
      cdp,
      actionTarget: actionTarget(),
      files: ["/stage/one.png"],
      timeoutMs: 100,
      withOverlayHidden: withoutOverlay,
    });
    expect(result).toMatchObject({
      code: "unsupported",
      data: {
        reason: "upload_mechanism_unsupported",
        effect_state: "none",
        phase: "drag_enter",
      },
    });
  });
  it("cancels an unresolved drag before returning a pre-commit timeout", async () => {
    const { cdp, calls } = dropCdp({
      dispatchError: (type) => (type === "dragEnter" ? new Promise<never>(() => {}) : undefined),
    });
    const result = await uploadThroughFileDrop({
      cdp,
      actionTarget: actionTarget(),
      files: ["/stage/one.png"],
      timeoutMs: 10,
      withOverlayHidden: withoutOverlay,
    });
    expect(result).toMatchObject({
      code: "timeout",
      data: { reason: "file_drop_failed", effect_state: "none", phase: "drag_enter" },
    });
    expect(calls).toContainEqual({
      method: "Input.dispatchDragEvent",
      params: expect.objectContaining({ type: "dragCancel" }),
    });
  });
  it("marks an unresolved drop unknown and detaches browser state", async () => {
    const { cdp, detach } = dropCdp({
      dispatchError: (type) => (type === "drop" ? new Promise<never>(() => {}) : undefined),
    });
    const result = await uploadThroughFileDrop({
      cdp,
      actionTarget: actionTarget(),
      files: ["/stage/one.png"],
      timeoutMs: 10,
      withOverlayHidden: withoutOverlay,
    });
    expect(result).toMatchObject({
      code: "timeout",
      data: { reason: "file_drop_failed", effect_state: "unknown", phase: "drop" },
    });
    expect(detach).toHaveBeenCalledWith(4);
  });
  it("routes one exact-target download through a browser-relative capability", async () => {
    const manager = sessions();
    const ctx = await manager.start("s1");
@@ -773,155 +493,6 @@ describe("file transfer tools", () => {
    expect(result).toMatchObject({ item: { id: 21, state: "complete" } });
  });
  it("removes a completed download when the final size exceeds the limit", async () => {
    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
    const onDeterminingFilename =
      fakeEvent<
        (
          item: chrome.downloads.DownloadItem,
          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
        ) => void | true
      >();
    const initial = {
      id: 22,
      url: "https://example.test/oversized.bin",
      finalUrl: "https://example.test/oversized.bin",
      filename: "oversized.bin",
      state: "in_progress",
      fileSize: -1,
      totalBytes: -1,
      bytesReceived: 0,
    } as chrome.downloads.DownloadItem;
    const complete = {
      ...initial,
      filename: "/profile/Downloads/BrowserSkill/tr_22/oversized.bin",
      state: "complete",
      fileSize: 8,
      totalBytes: 8,
      bytesReceived: 8,
    } as chrome.downloads.DownloadItem;
    const downloads: DownloadsApi = {
      onCreated,
      onChanged,
      onDeterminingFilename,
      search: vi.fn(async () => [complete]),
      cancel: vi.fn(async () => {}),
      removeFile: vi.fn(async () => {}),
    };
    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
    const cdp: CdpRunner = {
      send: vi.fn(async () => ({})) as CdpRunner["send"],
      onEvent: (handler) => {
        cdpEvent = handler;
        return { dispose: vi.fn() };
      },
    };
    const result = await captureBrowserDownload({
      cdp,
      target: { tabId: 4 },
      downloads,
      browserRelativeDir: "BrowserSkill/tr_22",
      maxByteSize: 4,
      timeoutMs: 1_000,
      trigger: async () => {
        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
          url: initial.url,
          suggestedFilename: initial.filename,
        });
        await new Promise<void>((resolve) => {
          onDeterminingFilename.emit(initial, () => resolve());
        });
        onCreated.emit(initial);
        onChanged.emit({ id: initial.id, state: { current: "complete" } });
        return { tab_id: 4, x: 10, y: 10 };
      },
    });
    expect(result).toMatchObject({
      code: "cdp_failed",
      data: { reason: "download_capture_failed", effect_state: "committed" },
    });
    expect(downloads.removeFile).toHaveBeenCalledWith(initial.id);
    expect(downloads.cancel).not.toHaveBeenCalled();
  });
  it("reconciles a download that completes while cancellation is being requested", async () => {
    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
    const onDeterminingFilename =
      fakeEvent<
        (
          item: chrome.downloads.DownloadItem,
          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
        ) => void | true
      >();
    const initial = {
      id: 23,
      url: "https://example.test/racing.bin",
      finalUrl: "https://example.test/racing.bin",
      filename: "racing.bin",
      state: "in_progress",
      fileSize: -1,
      totalBytes: -1,
      bytesReceived: 0,
    } as chrome.downloads.DownloadItem;
    const complete = {
      ...initial,
      filename: "/profile/Downloads/BrowserSkill/tr_23/racing.bin",
      state: "complete",
      fileSize: 4,
      totalBytes: 4,
      bytesReceived: 4,
    } as chrome.downloads.DownloadItem;
    const downloads: DownloadsApi = {
      onCreated,
      onChanged,
      onDeterminingFilename,
      search: vi.fn().mockResolvedValueOnce([initial]).mockResolvedValueOnce([complete]),
      cancel: vi.fn(async () => {
        throw new Error("download already complete");
      }),
      removeFile: vi.fn(async () => {}),
    };
    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
    const cdp: CdpRunner = {
      send: vi.fn(async () => ({})) as CdpRunner["send"],
      onEvent: (handler) => {
        cdpEvent = handler;
        return { dispose: vi.fn() };
      },
    };
    const result = await captureBrowserDownload({
      cdp,
      target: { tabId: 4 },
      downloads,
      browserRelativeDir: "BrowserSkill/tr_23",
      timeoutMs: 80,
      trigger: async () => {
        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
          url: initial.url,
          suggestedFilename: initial.filename,
        });
        await new Promise<void>((resolve) => {
          onDeterminingFilename.emit(initial, () => resolve());
        });
        onCreated.emit(initial);
        return { tab_id: 4, x: 10, y: 10 };
      },
    });
    expect(result).toMatchObject({
      code: "cdp_failed",
      data: { reason: "download_capture_failed", effect_state: "committed" },
    });
    expect(downloads.cancel).toHaveBeenCalledWith(initial.id);
    expect(downloads.removeFile).toHaveBeenCalledWith(initial.id);
    expect(result).not.toMatchObject({ data: { cleanup_state: "failed" } });
  });
  it("rejects ambiguous attribution without cancelling either unclaimed download", async () => {
    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
@@ -1,573 +0,0 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { SessionManager } from "@/session-manager/manager";
 import type { CdpRunner } from "@/tools/shared";
 import { handleFill } from "../interaction";
 interface ScriptParams {
  functionDeclaration: string;
  arguments?: Array<{ value: unknown }>;
 }
 async function setup(markup = '<input value="old">') {
  document.body.innerHTML = markup;
  const element = document.body.firstElementChild as HTMLInputElement;
  const manager = new SessionManager({
    agentWindow: {
      create: async () => 100,
      remove: async () => {},
      ensureActiveTab: async () => 4,
    },
  });
  const ctx = await manager.start("aa11");
  ctx.refStore.set("e1", 12, { tabId: 4 });
  const script = vi.fn(async (params: ScriptParams): Promise<unknown> => {
    try {
      const fn = new Function(`return (${params.functionDeclaration})`)();
      return {
        result: {
          value: await fn.apply(
            element,
            (params.arguments ?? []).map((arg) => arg.value),
          ),
        },
      };
    } catch {
      return { exceptionDetails: { text: "test page script failed" } };
    }
  });
  // Number/email controls have a browser caret even though their selection
  // getters return null. Model that caret instead of assuming it is at the end.
  const hiddenCaret = { start: 0, end: 0 };
  const moveToEnd = vi.fn(async () => {
    if (typeof element.selectionStart === "number") {
      element.setSelectionRange(element.value.length, element.value.length);
    } else {
      hiddenCaret.start = hiddenCaret.end = element.value.length;
    }
  });
  const insert = vi.fn(async (text: string) => {
    const focused = document.activeElement as HTMLInputElement;
    if (focused.readOnly || focused.disabled) return;
    const start = focused.selectionStart ?? hiddenCaret.start;
    const end = focused.selectionEnd ?? hiddenCaret.end;
    const value = focused.value.slice(0, start) + text + focused.value.slice(end);
    focused.value = focused.maxLength >= 0 ? value.slice(0, focused.maxLength) : value;
    hiddenCaret.start = hiddenCaret.end = Math.min(start + text.length, focused.value.length);
    focused.dispatchEvent(new Event("input", { bubbles: true }));
  });
  const release = vi.fn(async () => ({}));
  const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
    switch (method) {
      case "DOM.describeNode":
        return {
          node: {
            nodeName: element.tagName,
            attributes: Array.from(element.attributes).flatMap((attr) => [attr.name, attr.value]),
          },
        };
      case "DOM.scrollIntoViewIfNeeded":
        return {};
      case "DOM.focus":
        element.focus();
        return {};
      case "DOM.resolveNode":
        return { object: { objectId: "fill-target" } };
      case "Runtime.callFunctionOn":
        return script(params as ScriptParams);
      case "Input.insertText":
        await insert((params as { text: string }).text);
        return {};
      case "Input.dispatchKeyEvent":
        if ((params as { commands?: string[] }).commands?.includes("moveToEndOfDocument")) {
          await moveToEnd();
        }
        return {};
      case "Runtime.releaseObject":
        return release();
      default:
        throw new Error(`unexpected ${method}`);
    }
  });
  return {
    element,
    hiddenCaret,
    moveToEnd,
    script,
    insert,
    release,
    send,
    fill: (value = "hello", clearBefore = true, signal?: AbortSignal) =>
      handleFill(
        manager,
        { session_id: "aa11", ref: "e1", value, clear_before: clearBefore },
        {
          cdp: { send: send as CdpRunner["send"] },
          tabsApi: {
            get: async (id) => ({ id, windowId: 100, active: true }) as chrome.tabs.Tab,
            query: async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab],
          },
          signal,
        },
      ),
  };
 }
 afterEach(() => {
  vi.restoreAllMocks();
  document.body.innerHTML = "";
 });
 describe("fill result verification", () => {
  it.each([
    "readonly",
    "disabled",
  ])("preserves a %s field before rejecting it", async (attribute) => {
    const h = await setup(`<input ${attribute} value="old">`);
    expect(await h.fill()).toMatchObject({
      code: "invalid_params",
      data: { reason: "target_not_fillable" },
    });
    expect(h.element.value).toBe("old");
    expect(h.insert).not.toHaveBeenCalled();
    expect(h.release).toHaveBeenCalledOnce();
  });
  it.each([
    "checkbox",
    "radio",
    "range",
    "date",
    "file",
  ])("rejects an unsupported %s input before clearing", async (type) => {
    const h = await setup(`<input type="${type}">`);
    const before = h.element.value;
    expect(await h.fill()).toMatchObject({
      code: "invalid_params",
      data: { reason: "target_not_fillable" },
    });
    expect(h.element.value).toBe(before);
    expect(h.insert).not.toHaveBeenCalled();
  });
  it("rejects an overlong value before clearing", async () => {
    const h = await setup('<input maxlength="3" value="old">');
    expect(await h.fill()).toMatchObject({
      code: "invalid_params",
      message: /maxlength/,
      data: { reason: "fill_value_invalid" },
    });
    expect(h.element.value).toBe("old");
    expect(h.insert).not.toHaveBeenCalled();
  });
  it.each([
    true,
    false,
  ])("classifies a DOM.focus rejection on a disabled=%s target", async (disabled) => {
    const h = await setup(`<input ${disabled ? "disabled" : ""} value="old">`);
    const send = h.send.getMockImplementation()!;
    h.send.mockImplementation(async (tabId, method, params) => {
      if (method === "DOM.focus") throw new Error("Element is not focusable");
      return send(tabId, method, params);
    });
    expect(await h.fill()).toMatchObject({
      code: disabled ? "invalid_params" : "cdp_failed",
      data: { reason: disabled ? "target_not_fillable" : "fill_failed" },
    });
    expect(h.element.value).toBe("old");
    expect(h.insert).not.toHaveBeenCalled();
    expect(h.release).toHaveBeenCalledOnce();
  });
  it("fills a background document without requiring foreground browser focus", async () => {
    const h = await setup();
    vi.spyOn(document, "hasFocus").mockReturnValue(false);
    expect(await h.fill()).toMatchObject({ value_length: 5 });
    expect(h.element.value).toBe("hello");
  });
  it("restores focus once after clearing without typing into another field", async () => {
    const h = await setup();
    const other = document.createElement("input");
    document.body.append(other);
    h.element.addEventListener("input", () => other.focus());
    expect(await h.fill()).toMatchObject({ value_length: 5 });
    expect(h.element.value).toBe("hello");
    expect(other.value).toBe("");
    expect(h.send.mock.calls.filter(([, method]) => method === "DOM.focus")).toHaveLength(2);
  });
  it.each([
    "focus",
    "value",
  ])("rechecks %s after restoring focus, without retrying again", async (action) => {
    const h = await setup();
    const other = document.createElement("input");
    document.body.append(other);
    h.element.addEventListener(
      "input",
      () => {
        other.focus();
        h.element.addEventListener("focus", () => {
          if (action === "focus") queueMicrotask(() => other.focus());
          else h.element.value = "changed";
        });
      },
      { once: true },
    );
    expect(await h.fill()).toMatchObject({
      code: "cdp_failed",
      data: { reason: action === "focus" ? "fill_focus_lost" : "fill_target_changed" },
    });
    expect(other.value).toBe("");
    expect(h.insert).not.toHaveBeenCalled();
    expect(h.send.mock.calls.filter(([, method]) => method === "DOM.focus")).toHaveLength(2);
  });
  it.each([
    "remove",
    "readonly",
    "restore",
    "microtask-restore",
  ])("stops when clearing causes the page to %s the target", async (action) => {
    const h = await setup();
    h.element.addEventListener("input", () => {
      if (action === "remove") h.element.remove();
      if (action === "readonly") h.element.readOnly = true;
      if (action === "restore") h.element.value = "restored";
      if (action === "microtask-restore")
        queueMicrotask(() => {
          h.element.value = "restored";
        });
    });
    expect(await h.fill()).toMatchObject({
      code: "cdp_failed",
      data: { reason: "fill_target_changed" },
    });
    expect(h.insert).not.toHaveBeenCalled();
  });
  it("fails when insertText is acknowledged without changing the value", async () => {
    const h = await setup();
    h.insert.mockImplementation(async () => {});
    expect(await h.fill()).toMatchObject({
      code: "cdp_failed",
      data: { reason: "fill_value_mismatch" },
    });
    expect(h.release).toHaveBeenCalledOnce();
  });
  it("detects truncation when maxlength changes after preparation", async () => {
    const h = await setup();
    h.element.addEventListener(
      "input",
      () => {
        h.element.maxLength = 3;
      },
      { once: true },
    );
    expect(await h.fill()).toMatchObject({
      code: "cdp_failed",
      data: { reason: "fill_value_mismatch" },
    });
    expect(h.element.value).toBe("hel");
  });
  it.each([
    "input",
    "change",
    "microtask-change",
  ])("detects a value reverted by the %s handler", async (event) => {
    const h = await setup();
    h.element.addEventListener(event === "microtask-change" ? "change" : event, () => {
      if (event === "microtask-change")
        queueMicrotask(() => {
          h.element.value = "";
        });
      else h.element.value = "";
    });
    expect(await h.fill()).toMatchObject({ code: "cdp_failed", message: /expected value/ });
  });
  it("compares content rather than length without including field values in the error", async () => {
    const h = await setup('<input type="password">');
    h.element.addEventListener("change", () => {
      h.element.value = "other-secret";
    });
    const result = await h.fill("given-secret");
    expect(result).toMatchObject({ code: "cdp_failed", message: /expected value/ });
    expect(JSON.stringify(result)).not.toMatch(/given-secret|other-secret/);
  });
  it("does not report success for a target replaced by a change handler", async () => {
    const h = await setup();
    h.element.addEventListener("change", () => h.element.replaceWith(h.element.cloneNode()));
    expect(await h.fill()).toMatchObject({
      code: "cdp_failed",
      data: { reason: "fill_target_changed" },
    });
  });
  it.each([
    1, 2, 3, 4, 5,
  ])("rejects script exceptions at phase %s and releases the target", async (phase) => {
    const h = await setup();
    vi.spyOn(document, "hasFocus").mockReturnValue(false);
    const run = h.script.getMockImplementation()!;
    let count = 0;
    h.script.mockImplementation(async (params) =>
      ++count === phase ? { exceptionDetails: { text: "page secret" } } : run(params),
    );
    const result = await h.fill();
    expect(result).toMatchObject({ code: "cdp_failed", data: { reason: "fill_failed" } });
    expect(JSON.stringify(result)).not.toContain("page secret");
    if (phase <= 3) expect(h.insert).not.toHaveBeenCalled();
    expect(h.release).toHaveBeenCalledOnce();
  });
  it.each([1, 2, 3, 5])("rejects missing results at phase %s", async (phase) => {
    const h = await setup();
    vi.spyOn(document, "hasFocus").mockReturnValue(false);
    const run = h.script.getMockImplementation()!;
    let count = 0;
    h.script.mockImplementation(async (params) =>
      ++count === phase ? { result: { type: "undefined" } } : run(params),
    );
    expect(await h.fill()).toMatchObject({ code: "cdp_failed" });
    if (phase <= 3) expect(h.insert).not.toHaveBeenCalled();
  });
  it.each(["input", "change"])("checks state after nested microtasks from %s", async (event) => {
    const h = await setup();
    h.element.addEventListener(event, () => {
      queueMicrotask(() =>
        queueMicrotask(() => {
          h.element.value = "reverted";
        }),
      );
    });
    expect(await h.fill()).toMatchObject({ code: "cdp_failed" });
    if (event === "input") expect(h.insert).not.toHaveBeenCalled();
  });
  it.each([
    "<input>",
    '<input type="password">',
    "<textarea></textarea>",
  ])("verifies successful text in %s", async (markup) => {
    const h = await setup(markup);
    expect(await h.fill("你好🙂")).toMatchObject({ value_length: 4 });
    expect(h.element.value).toBe("你好🙂");
    expect(h.release).toHaveBeenCalledOnce();
  });
  it("verifies append against the old value plus the requested text", async () => {
    const h = await setup();
    h.element.focus();
    h.element.setSelectionRange(3, 3);
    expect(await h.fill("!", false)).toMatchObject({ value_length: 4 });
    expect(h.element.value).toBe("old!");
  });
  it.each([
    ["<textarea></textarea>", "a\r\nb", "a\nb"],
    ["<input>", "a\nb", "a b"],
    ["<input>", "a\r\nb", "a b"],
    [
      '<input type="email" multiple>',
      " a@example.com , b@example.com ",
      "a@example.com,b@example.com",
    ],
  ])("accepts native normalization for %s", async (markup, requested, normalized) => {
    if (markup.startsWith("<textarea")) {
      // Happy DOM does not implement Chrome's textarea line-ending normalization.
      const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")!.set!;
      vi.spyOn(HTMLTextAreaElement.prototype, "value", "set").mockImplementation(function (
        this: HTMLTextAreaElement,
        value,
      ) {
        setter.call(this, value.replace(/\r\n?/g, "\n"));
      });
    }
    const h = await setup(markup);
    h.insert.mockImplementation(async () => {
      h.element.value = normalized;
    });
    expect(await h.fill(requested)).toMatchObject({ value_length: normalized.length });
  });
  it("does not count an editable padding break as an extra typed character", async () => {
    const h = await setup('<div contenteditable="true" tabindex="0"></div>');
    // These two layout/editability properties are missing in Happy DOM.
    let innerText = "";
    Object.defineProperty(h.element, "isContentEditable", { get: () => true });
    Object.defineProperty(h.element, "innerText", { get: () => innerText });
    h.insert.mockImplementation(async () => {
      h.element.innerHTML = "one<div><br></div>";
      innerText = "one\n\n";
    });
    expect(await h.fill("one\n")).toMatchObject({ value_length: 4 });
  });
  it.each([
    [0, 0],
    [1, 1],
    [0, 3],
  ])("appends after moving selection %s:%s to the end", async (start, end) => {
    const h = await setup();
    h.element.focus();
    h.element.setSelectionRange(start, end);
    expect(await h.fill("🙂", false)).toMatchObject({ value_length: 5 });
    expect(h.element.value).toBe("old🙂");
  });
  it.each(
    ["number", "email"].flatMap((type) =>
      [
        [0, 0],
        [1, 1],
        [0, 2],
      ].map(([start, end]) => ({ type, start, end })),
    ),
  )("appends to $type from selection $start:$end without using its unsupported API", async ({
    type,
    start,
    end,
  }) => {
    const h = await setup(`<input type="${type}" value="12">`);
    Object.assign(h.hiddenCaret, { start, end });
    vi.spyOn(h.element, "selectionStart", "get").mockReturnValue(null);
    vi.spyOn(h.element, "selectionEnd", "get").mockReturnValue(null);
    const selection = vi.spyOn(h.element, "setSelectionRange").mockImplementation(() => {
      throw new DOMException("unsupported", "InvalidStateError");
    });
    expect(await h.fill("3", false)).toMatchObject({ value_length: 3 });
    expect(h.element.value).toBe("123");
    expect(selection).not.toHaveBeenCalled();
  });
  it.each([
    "number",
    "email",
  ])("does not report successful %s append when the caret command is ignored", async (type) => {
    const h = await setup(`<input type="${type}" value="12">`);
    vi.spyOn(h.element, "selectionStart", "get").mockReturnValue(null);
    vi.spyOn(h.element, "selectionEnd", "get").mockReturnValue(null);
    h.moveToEnd.mockResolvedValueOnce(undefined);
    expect(await h.fill("3", false)).toMatchObject({
      code: "cdp_failed",
      data: { reason: "fill_value_mismatch" },
    });
    expect(h.element.value).toBe("312");
    expect(h.insert).toHaveBeenCalledOnce();
  });
  it("rejects invalid number text before clearing", async () => {
    const h = await setup('<input type="number" value="12">');
    expect(await h.fill("abc")).toMatchObject({
      code: "invalid_params",
      data: { reason: "fill_value_invalid" },
    });
    expect(h.element.value).toBe("12");
    expect(h.insert).not.toHaveBeenCalled();
  });
  it("reports page formatting as unconfirmed without retrying the write", async () => {
    const h = await setup();
    h.element.addEventListener("change", () => {
      h.element.value = h.element.value.toUpperCase();
    });
    expect(await h.fill()).toMatchObject({
      code: "cdp_failed",
      data: { reason: "fill_value_mismatch" },
    });
    expect(h.element.value).toBe("HELLO");
    expect(h.insert).toHaveBeenCalledOnce();
  });
  it.each([
    ["focus", false],
    ["focus", true],
    ["value", false],
    ["value", true],
    ["cancel", false],
    ["cancel", true],
    ["throw", false],
    ["throw", true],
  ] as const)("stops when positioning triggers %s (clear=%s) and releases the key", async (action, clearBefore) => {
    const h = await setup();
    vi.spyOn(document, "hasFocus").mockReturnValue(false);
    const controller = new AbortController();
    const other = document.createElement("input");
    document.body.append(other);
    const send = h.send.getMockImplementation()!;
    h.send.mockImplementation(async (tabId, method, params) => {
      const reply = await send(tabId, method, params);
      if (
        method === "Input.dispatchKeyEvent" &&
        (params as { type: string }).type === "rawKeyDown"
      ) {
        if (action === "focus") other.focus();
        if (action === "value") h.element.value = "changed";
        if (action === "cancel") controller.abort();
        if (action === "throw") throw new Error("dispatch failed");
      }
      return reply;
    });
    const result = await h.fill("!", clearBefore, controller.signal);
    expect(result).toMatchObject({ code: action === "cancel" ? "cancelled" : "cdp_failed" });
    expect(h.insert).not.toHaveBeenCalled();
    expect(other.value).toBe("");
    expect(h.send).toHaveBeenCalledWith(
      4,
      "Input.dispatchKeyEvent",
      expect.objectContaining({ type: "keyUp" }),
    );
    expect(h.release).toHaveBeenCalledOnce();
  });
  it.each([true, false])("verifies an empty request with clear_before=%s", async (clearBefore) => {
    const h = await setup();
    expect(await h.fill("", clearBefore)).toMatchObject({ value_length: clearBefore ? 0 : 3 });
    expect(h.element.value).toBe(clearBefore ? "" : "old");
    expect(h.insert).not.toHaveBeenCalled();
  });
  it("cancels after insertion without sending change events", async () => {
    const h = await setup();
    const controller = new AbortController();
    h.insert.mockImplementation(async () => controller.abort());
    expect(await h.fill("hello", true, controller.signal)).toMatchObject({ code: "cancelled" });
    expect(h.script).toHaveBeenCalledTimes(2);
    expect(h.release).toHaveBeenCalledOnce();
  });
  it("cancels after resolving the remote object without clearing the field", async () => {
    const h = await setup();
    const controller = new AbortController();
    const send = h.send.getMockImplementation()!;
    h.send.mockImplementation(async (tabId, method, params) => {
      const result = await send(tabId, method, params);
      if (method === "DOM.resolveNode") controller.abort();
      return result;
    });
    expect(await h.fill("hello", true, controller.signal)).toMatchObject({ code: "cancelled" });
    expect(h.element.value).toBe("old");
    expect(h.script).not.toHaveBeenCalled();
    expect(h.release).toHaveBeenCalledOnce();
  });
  it("honors cancellation during verification", async () => {
    const h = await setup();
    const controller = new AbortController();
    h.element.addEventListener("change", () => controller.abort());
    expect(await h.fill("hello", true, controller.signal)).toMatchObject({ code: "cancelled" });
    expect(h.release).toHaveBeenCalledOnce();
  });
  it("keeps the verified outcome when releasing the remote object fails", async () => {
    const h = await setup();
    h.release.mockRejectedValueOnce(new Error("target closed"));
    expect(await h.fill()).toMatchObject({ value_length: 5 });
  });
 });
@@ -169,7 +169,6 @@ describe("frame geometry projection", () => {
    expect(geometry).toMatchObject({
      topBounds: { x: 100, y: 100, width: 200, height: 100 },
      actionPoint: { x: 200, y: 150 },
      targetActionPoint: { x: 100, y: 50 },
    });
  });
@@ -262,7 +261,6 @@ describe("frame geometry projection", () => {
    expect(geometry).toMatchObject({
      topBounds: { x: 100, y: 100, width: 200, height: 100 },
      actionPoint: { x: 200, y: 150 },
      targetActionPoint: { x: 200, y: 150 },
    });
  });
@@ -21,7 +21,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
  };
 }
@@ -540,21 +540,6 @@ describe("handleHover", () => {
  });
 });
 function successfulFillScript(params: unknown) {
  const script = params as { arguments?: Array<{ value: unknown }>; functionDeclaration: string };
  const args = script.arguments ?? [];
  return {
    result: {
      value:
        args.length === 2
          ? { before: "", expected: args[0].value }
          : script.functionDeclaration.startsWith("function(expected)")
            ? { connected: true, matches: true, valueLength: String(args[0].value).length }
            : "ready",
    },
  };
 }
 describe("handleFill", () => {
  it("returns not_found for unknown ref", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
@@ -601,8 +586,7 @@ describe("handleFill", () => {
      "DOM.scrollIntoViewIfNeeded": () => ({}),
      "DOM.focus": () => ({}),
      "DOM.resolveNode": () => ({ object: { objectId: "obj-1" } }),
-      "Runtime.callFunctionOn": successfulFillScript,
+      "Runtime.callFunctionOn": () => ({ result: { type: "undefined" } }),
      "Runtime.releaseObject": () => ({}),
      "Input.insertText": () => ({}),
    });
    const res = await handleFill(
@@ -616,12 +600,13 @@ describe("handleFill", () => {
    expect(res.used_ref).toBe("e1");
    const insert = fake.sent.find((c) => c.method === "Input.insertText");
    expect(insert?.params).toEqual({ text: "hello" });
-    // Foreground replacement needs no extra caret-positioning round trip.
+    // clear_before defaults to true → callFunctionOn invoked once to
    // clear, once to fire input/change after typing.
    const callFns = fake.sent.filter((c) => c.method === "Runtime.callFunctionOn");
-    expect(callFns).toHaveLength(4);
+    expect(callFns.length).toBeGreaterThanOrEqual(2);
  });
-  it("passes clear_before=false to preparation and verifies the result", async () => {
+  it("clear_before=false skips the wipe call", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
    ctx.refStore.set("e1", 1, { tabId: 4 });
@@ -633,12 +618,12 @@ describe("handleFill", () => {
      "DOM.focus": () => ({}),
      "DOM.resolveNode": () => ({ object: { objectId: "obj-2" } }),
      "Runtime.callFunctionOn": (p) => {
-        const args = (p as { arguments?: Array<{ value: unknown }> }).arguments ?? [];
+        const fn = (p as { functionDeclaration?: string }).functionDeclaration ?? "";
-        if (args.length === 2) expect(args[1].value).toBe(false);
+        // No "this.value = ''" clearing on a no-clear path; only the
-        return successfulFillScript(p);
+        // post-input dispatchEvent.
        expect(fn).not.toMatch(/this\.value\s*=\s*''/);
        return { result: { type: "undefined" } };
      },
      "Input.dispatchKeyEvent": () => ({}),
      "Runtime.releaseObject": () => ({}),
      "Input.insertText": () => ({}),
    });
    const res = await handleFill(
@@ -665,8 +650,7 @@ describe("handleFill", () => {
      "DOM.scrollIntoViewIfNeeded": () => ({}),
      "DOM.focus": () => ({}),
      "DOM.resolveNode": () => ({ object: { objectId: "obj-3" } }),
-      "Runtime.callFunctionOn": successfulFillScript,
+      "Runtime.callFunctionOn": () => ({ result: { type: "undefined" } }),
      "Runtime.releaseObject": () => ({}),
      "Input.insertText": () => ({}),
    });
    const res = await handleFill(
@@ -1,266 +0,0 @@
 import { describe, expect, it, vi } from "vitest";
 import { SessionManager } from "@/session-manager/manager";
 import type { BrowserNavigationApi } from "../browser-navigation";
 import { handleNavigate, handleReload } from "../navigation";
 import type { CdpRunner } from "../shared";
 const denied = "Cannot access a chrome-extension:// URL of different extension";
 const url = "https://example.test/recovered";
 function event<T extends (...args: never[]) => void>() {
  const listeners = new Set<T>();
  return {
    listeners,
    addListener: (listener: T) => listeners.add(listener),
    removeListener: (listener: T) => listeners.delete(listener),
    fire: (...args: Parameters<T>) => {
      for (const listener of [...listeners]) listener(...args);
    },
  };
 }
 async function fixture() {
  const manager = new SessionManager({
    agentWindow: {
      create: vi.fn(async () => 100),
      remove: vi.fn(async () => {}),
      ensureActiveTab: vi.fn(async () => 4),
    },
  });
  await manager.start("test");
  type Listener = Parameters<BrowserNavigationApi["onCommitted"]["addListener"]>[0];
  const events = {
    onCommitted: event<Listener>(),
    onDOMContentLoaded: event<Listener>(),
    onCompleted: event<Listener>(),
    onErrorOccurred: event<Listener>(),
  };
  const cdpEvents = event<Parameters<NonNullable<CdpRunner["onEvent"]>>[0]>();
  const state = { blocked: true, destinationBlocked: false, emitIdle: true };
  const send = vi.fn(async (_tabId: number, method: string) => {
    if (state.blocked) throw new Error(denied);
    if (method === "Page.getFrameTree") {
      return { frameTree: { frame: { id: "main", loaderId: "new-loader" } } };
    }
    if (method === "Runtime.evaluate") return { result: { value: "complete" } };
    if (method === "Page.setLifecycleEventsEnabled" && state.emitIdle) {
      cdpEvents.fire({ tabId: 4 }, "Page.lifecycleEvent", {
        frameId: "main",
        loaderId: "new-loader",
        name: "networkIdle",
      });
    }
    if (method === "Page.navigate") return { frameId: "main", loaderId: "new-loader" };
    return {};
  });
  const cdp: CdpRunner = {
    send: send as CdpRunner["send"],
    onEvent: (listener) => {
      cdpEvents.addListener(listener);
      return { dispose: () => cdpEvents.removeListener(listener) };
    },
  };
  const main = { tabId: 4, frameId: 0, documentId: "new-document" };
  const navigate = async () => {
    state.blocked = state.destinationBlocked;
    events.onCommitted.fire(main);
    events.onDOMContentLoaded.fire(main);
    events.onCompleted.fire(main);
  };
  const browserNavigation = { ...events, update: vi.fn(navigate), reload: vi.fn(navigate) };
  const tab = { id: 4, windowId: 100, active: true, url } as chrome.tabs.Tab;
  const tabsApi = { get: vi.fn(async () => tab), query: vi.fn(async () => [tab]) };
  const deps = { cdp, tabsApi, browserNavigation, defaultTimeoutMs: 1000 };
  const expectCleanedUp = () => {
    for (const entry of Object.values(events)) expect(entry.listeners.size).toBe(0);
    expect(cdpEvents.listeners.size).toBe(0);
  };
  return { manager, deps, state, send, events, main, cdpEvents, expectCleanedUp };
 }
 describe("navigation after Chrome denies extension-frame access", () => {
  it.each([
    "load",
    "commit",
    "domcontentloaded",
    "networkidle",
  ] as const)("recovers the same tab with the requested %s checkpoint", async (waitUntil) => {
    const f = await fixture();
    const result = await handleNavigate(
      f.manager,
      {
        session_id: "test",
        url,
        wait_until: waitUntil,
      },
      f.deps,
    );
    expect(result).toMatchObject({ tab_id: 4, final_url: url, reached: waitUntil });
    expect(f.deps.browserNavigation.update).toHaveBeenCalledExactlyOnceWith(4, { url });
    expect(f.send.mock.calls.some(([, method]) => method === "Page.navigate")).toBe(false);
    expect(f.send).toHaveBeenCalledWith(4, "Page.enable", {});
    f.expectCleanedUp();
  });
  it("recovers reload through tabs.reload and preserves hard reload", async () => {
    const f = await fixture();
    const result = await handleReload(f.manager, { session_id: "test", hard: true }, f.deps);
    expect(result).toMatchObject({ tab_id: 4, reached: "load" });
    expect(f.deps.browserNavigation.reload).toHaveBeenCalledExactlyOnceWith(4, {
      bypassCache: true,
    });
    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
    f.expectCleanedUp();
  });
  it("reports the restriction when reload leaves the conflicting frame present", async () => {
    const f = await fixture();
    f.state.destinationBlocked = true;
    const result = await handleReload(f.manager, { session_id: "test" }, f.deps);
    expect(result).toMatchObject({
      code: "cdp_failed",
      data: { reason: "cdp_extension_access_denied" },
    });
    expect(f.deps.browserNavigation.reload).toHaveBeenCalledOnce();
    f.expectCleanedUp();
  });
  it("does not fall back for unrelated debugger failures", async () => {
    const f = await fixture();
    f.send.mockRejectedValue(new Error("Another debugger is already attached"));
    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
    expect(result).toMatchObject({
      code: "cdp_failed",
      message: "Another debugger is already attached",
    });
    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
    f.expectCleanedUp();
  });
  it("does not replay navigation when a dispatched CDP command fails", async () => {
    const f = await fixture();
    f.state.blocked = false;
    const send = f.send.getMockImplementation()!;
    f.send.mockImplementation(async (tabId, method) => {
      if (method === "Page.navigate") throw new Error(denied);
      return send(tabId, method);
    });
    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
    expect(result).toMatchObject({
      code: "cdp_failed",
      data: { reason: "cdp_extension_access_denied" },
    });
    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
    f.expectCleanedUp();
  });
  it("keeps the Agent Window guard in front of the recovery", async () => {
    const f = await fixture();
    f.deps.tabsApi.get.mockResolvedValue({
      id: 4,
      windowId: 200,
      active: true,
      url,
    } as chrome.tabs.Tab);
    const result = await handleNavigate(f.manager, { session_id: "test", tab_id: 4, url }, f.deps);
    expect(result).toMatchObject({ code: "permission_denied" });
    expect(f.send).not.toHaveBeenCalled();
    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
  });
  it("ignores old-document, subframe, and other-tab completion events", async () => {
    const f = await fixture();
    f.deps.browserNavigation.update.mockImplementation(async () => {});
    let settled = false;
    const work = handleNavigate(f.manager, { session_id: "test", url }, f.deps).then((result) => {
      settled = true;
      return result;
    });
    await vi.waitFor(() => expect(f.deps.browserNavigation.update).toHaveBeenCalledOnce());
    f.events.onCompleted.fire(f.main);
    f.events.onCommitted.fire({ ...f.main, tabId: 9 });
    f.events.onCommitted.fire({ ...f.main, frameId: 1 });
    f.events.onCompleted.fire(f.main);
    await Promise.resolve();
    expect(settled).toBe(false);
    f.events.onCommitted.fire(f.main);
    f.events.onCompleted.fire({ ...f.main, documentId: "old-document" });
    await Promise.resolve();
    expect(settled).toBe(false);
    f.state.blocked = false;
    f.events.onCompleted.fire(f.main);
    expect(await work).toMatchObject({ reached: "load" });
    f.expectCleanedUp();
  });
  it("does not infer network idle from a browser load event", async () => {
    const f = await fixture();
    f.state.emitIdle = false;
    const result = await handleNavigate(
      f.manager,
      {
        session_id: "test",
        url,
        wait_until: "networkidle",
        timeout_ms: 10,
      },
      f.deps,
    );
    expect(result).toMatchObject({ reached: "timeout" });
    f.expectCleanedUp();
  });
  it("cleans up browser listeners on timeout", async () => {
    const f = await fixture();
    f.deps.browserNavigation.update.mockImplementation(async () => {});
    const result = await handleNavigate(
      f.manager,
      { session_id: "test", url, timeout_ms: 10 },
      f.deps,
    );
    expect(result).toMatchObject({ reached: "timeout" });
    f.expectCleanedUp();
  });
  it("does not navigate an already-cancelled request", async () => {
    const f = await fixture();
    const result = await handleNavigate(
      f.manager,
      { session_id: "test", url },
      {
        ...f.deps,
        signal: AbortSignal.abort(),
      },
    );
    expect(result).toMatchObject({ code: "cancelled" });
    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
    f.expectCleanedUp();
  });
  it("cleans up browser listeners when cancelled after dispatch", async () => {
    const f = await fixture();
    const ac = new AbortController();
    f.deps.browserNavigation.update.mockImplementation(async () => {
      ac.abort();
    });
    const result = await handleNavigate(
      f.manager,
      { session_id: "test", url },
      { ...f.deps, signal: ac.signal },
    );
    expect(result).toMatchObject({ code: "cancelled" });
    expect(f.deps.browserNavigation.update).toHaveBeenCalledOnce();
    f.expectCleanedUp();
  });
  it("reports browser navigation errors and releases listeners", async () => {
    const f = await fixture();
    f.deps.browserNavigation.update.mockImplementation(async () => {
      f.events.onErrorOccurred.fire({ ...f.main, error: "net::ERR_NAME_NOT_RESOLVED" });
    });
    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
    expect(result).toMatchObject({ code: "cdp_failed", message: "net::ERR_NAME_NOT_RESOLVED" });
    f.expectCleanedUp();
  });
 });
@@ -21,7 +21,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
  };
 }
@@ -12,7 +12,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
  };
 }
@@ -1,26 +1,8 @@
 import { describe, expect, it, vi } from "vitest";
 import { SessionManager } from "@/session-manager/manager";
 import { handleSessionStop } from "../session";
 import type { ChromeTabsApi } from "../shared";
 import { type AgentOverlayResetApi, type ChromeWindowsApi, type TabMutationApi } from "../tabs";
 /** Build a read-only query api over a FakeState. */
 function makeQuery(state: FakeState): ChromeTabsApi {
  return {
    get: vi.fn(async (id) => {
      const t = state.tabs.get(id);
      if (!t) throw new Error(`tab ${id} not found`);
      return t;
    }),
    query: vi.fn(async (q: chrome.tabs.QueryInfo) => {
      const w = q.windowId;
      return Array.from(state.tabs.values()).filter(
        (t) => typeof w !== "number" || t.windowId === w,
      );
    }),
  };
 }
 function fakeAgentWindow(ids: number[]) {
  let i = 0;
  const create = vi.fn(async () => {
@@ -29,7 +11,7 @@ function fakeAgentWindow(ids: number[]) {
    return id;
  });
  const remove = vi.fn(async () => {});
-  const ensureActiveTab = vi.fn(async () => 0);
+  const ensureActiveTab = vi.fn(async () => {});
  return { create, remove, ensureActiveTab };
 }
@@ -48,9 +30,7 @@ function makeApis(
 } {
  const tabs: TabMutationApi = {
    create: vi.fn(),
-    remove: vi.fn(async (id: number) => {
+    remove: vi.fn(async () => {}),
      state.tabs.delete(id);
    }),
    update: vi.fn(async (_id, _p) => undefined),
    get: vi.fn(async (id) => {
      const t = state.tabs.get(id);
@@ -86,52 +66,6 @@ function makeApis(
 }
 describe("handleSessionStop with auto-return", () => {
  it("leaves the session untouched when cancellation arrived before teardown", async () => {
    const aw = fakeAgentWindow([100]);
    const sm = new SessionManager({ agentWindow: aw });
    await sm.start("aa11");
    const cdp = { detachSession: vi.fn(async () => {}) };
    const controller = new AbortController();
    controller.abort();
    const res = await handleSessionStop(
      sm,
      { session_id: "aa11" },
      { cdp, signal: controller.signal },
    );
    expect(res).toMatchObject({ code: "cancelled" });
    expect(sm.has("aa11")).toBe(true);
    expect(cdp.detachSession).not.toHaveBeenCalled();
    expect(aw.remove).not.toHaveBeenCalled();
  });
  it("does not close the Agent Window when cancellation lands during CDP detach", async () => {
    const aw = fakeAgentWindow([100]);
    const sm = new SessionManager({ agentWindow: aw });
    await sm.start("aa11");
    const controller = new AbortController();
    let finishDetach: () => void = () => {};
    const detach = new Promise<void>((resolve) => {
      finishDetach = resolve;
    });
    const cdp = { detachSession: vi.fn(() => detach) };
    const stopping = handleSessionStop(
      sm,
      { session_id: "aa11" },
      { cdp, signal: controller.signal },
    );
    await vi.waitFor(() => expect(cdp.detachSession).toHaveBeenCalledWith("aa11"));
    controller.abort();
    finishDetach();
    const res = await stopping;
    expect(res).toMatchObject({ code: "cancelled" });
    expect(sm.has("aa11")).toBe(true);
    expect(aw.remove).not.toHaveBeenCalled();
  });
  it("returns every borrowed tab and closes the Agent Window in the right order", async () => {
    const aw = fakeAgentWindow([100]);
    const sm = new SessionManager({ agentWindow: aw });
@@ -257,15 +191,11 @@ describe("handleSessionStop with auto-return", () => {
      moves: [],
    };
    const { tabs, windows } = makeApis(state, { moveThrowsFor: new Set([1]) });
    const cdp = {
      detachSession: vi.fn(async () => {}),
      releaseSessionTab: vi.fn(async () => {}),
    };
    const res = await handleSessionStop(
      sm,
      { session_id: "aa11" },
-      { cdp, tabManagement: { tabs, windows } },
+      { tabManagement: { tabs, windows } },
    );
    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
    expect(res.return_failures?.map((f) => f.tab_id)).toEqual([1]);
@@ -273,8 +203,6 @@ describe("handleSessionStop with auto-return", () => {
    expect(sm.has("aa11")).toBe(true);
    expect(ctx.borrowedTabs.has(1)).toBe(true);
    expect(ctx.borrowedTabs.has(2)).toBe(false);
    expect(cdp.releaseSessionTab).toHaveBeenCalledExactlyOnceWith("aa11", 2);
    expect(cdp.detachSession).not.toHaveBeenCalled();
    expect(aw.remove).not.toHaveBeenCalled();
  });
@@ -293,275 +221,4 @@ describe("handleSessionStop with auto-return", () => {
    await handleSessionStop(sm, { session_id: "aa11" }, { tabManagement: { tabs, windows } });
    expect(ctx.refStore.isEmpty()).toBe(true);
  });
  it.each([
    "before teardown",
    "during its return",
    "after its return failed",
    "before its turn in the return loop",
  ])("finishes stopping when a borrowed tab closes %s", async (timing) => {
    const aw = fakeAgentWindow([100]);
    const sm = new SessionManager({ agentWindow: aw });
    const ctx = await sm.start("aa11");
    ctx.borrowedTabs.set(1, { tabId: 1, originalWindowId: 200, originalIndex: 0 });
    ctx.borrowedTabs.set(2, { tabId: 2, originalWindowId: 200, originalIndex: 1 });
    const state: FakeState = {
      tabs: new Map([
        [1, { id: 1, windowId: 100 } as chrome.tabs.Tab],
        [2, { id: 2, windowId: 100 } as chrome.tabs.Tab],
      ]),
      windowsClosed: new Set(),
      moves: [],
    };
    const { tabs, windows } = makeApis(state);
    const cdp = { detachSession: vi.fn(async () => {}) };
    const closeTab = (tabId: number) => {
      state.tabs.delete(tabId);
      sm.forgetClosedTab(tabId);
    };
    const baseMove = tabs.move;
    tabs.move = vi.fn(async (tabId, props) => {
      if (tabId === 1 && timing === "during its return") closeTab(1);
      if (tabId === 1 && timing === "after its return failed") {
        throw new Error("simulated move failure");
      }
      if (tabId === 2 && timing === "after its return failed") closeTab(1);
      if (tabId === 1 && timing === "before its turn in the return loop") closeTab(2);
      if (!state.tabs.has(tabId)) throw new Error(`tab ${tabId} not found`);
      return baseMove(tabId, props);
    });
    if (timing === "before teardown") closeTab(1);
    const res = await handleSessionStop(
      sm,
      { session_id: "aa11" },
      {
        cdp,
        tabManagement: {
          tabs,
          windows,
          agentOverlayReset: { resetAgentOverlays: vi.fn(async () => {}) },
        },
        tabsQuery: makeQuery(state),
      },
    );
    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
    const closedTabId = timing === "before its turn in the return loop" ? 2 : 1;
    expect(res.returned_tab_ids).toEqual([closedTabId === 1 ? 2 : 1]);
    expect(res.return_failures).toBeUndefined();
    expect(ctx.borrowedTabs.size).toBe(0);
    expect(sm.has("aa11")).toBe(false);
    expect(cdp.detachSession).toHaveBeenCalledWith("aa11");
    expect(aw.remove).toHaveBeenCalledWith(100);
    if (timing === "before teardown" || timing === "before its turn in the return loop") {
      expect(tabs.move).not.toHaveBeenCalledWith(closedTabId, expect.anything());
    }
  });
 });
 describe("handleSessionStop window release (issue #57)", () => {
  const agentWindowId = 100;
  it("releases the window when user-created tabs remain", async () => {
    const aw = fakeAgentWindow([agentWindowId]);
    // ensureActiveTab returns the home tab id (10). We override the fake to
    // return a known id.
    aw.ensureActiveTab = vi.fn(async () => 10);
    const sm = new SessionManager({ agentWindow: aw });
    const ctx = await sm.start("aa11");
    ctx.agentCreatedTabs.add(11);
    ctx.agentCreatedTabs.add(12);
    // user tab 99 (created via Chrome UI, NOT in agentCreatedTabs)
    const state: FakeState = {
      tabs: new Map([
        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
        [12, { id: 12, windowId: agentWindowId } as chrome.tabs.Tab],
        [99, { id: 99, windowId: agentWindowId } as chrome.tabs.Tab],
      ]),
      windowsClosed: new Set(),
      moves: [],
    };
    const { tabs, windows } = makeApis(state);
    const query = makeQuery(state);
    const res = await handleSessionStop(
      sm,
      { session_id: "aa11" },
      { tabManagement: { tabs, windows }, tabsQuery: query },
    );
    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
    expect(res.window_released).toBe(true);
    // agent tabs + home removed, user tab 99 kept
    expect((tabs.remove as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[0]).sort()).toEqual([
      10, 11, 12,
    ]);
    expect(state.tabs.has(99)).toBe(true);
    // window released (dropOnly), not closed
    expect(aw.remove).not.toHaveBeenCalled();
    expect(sm.has("aa11")).toBe(false);
  });
  it("closes the window (not release) when no user tabs remain", async () => {
    const aw = fakeAgentWindow([agentWindowId]);
    aw.ensureActiveTab = vi.fn(async () => 10);
    const sm = new SessionManager({ agentWindow: aw });
    const ctx = await sm.start("aa11");
    ctx.agentCreatedTabs.add(11);
    const state: FakeState = {
      tabs: new Map([
        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
      ]),
      windowsClosed: new Set(),
      moves: [],
    };
    const { tabs, windows } = makeApis(state);
    const query = makeQuery(state);
    const res = await handleSessionStop(
      sm,
      { session_id: "aa11" },
      { tabManagement: { tabs, windows }, tabsQuery: query },
    );
    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
    expect(res.window_released).toBeFalsy();
    expect(aw.remove).toHaveBeenCalledWith(agentWindowId);
    expect(sm.has("aa11")).toBe(false);
  });
  it("is non-fatal when an agent tab is already gone", async () => {
    const aw = fakeAgentWindow([agentWindowId]);
    aw.ensureActiveTab = vi.fn(async () => 10);
    const sm = new SessionManager({ agentWindow: aw });
    const ctx = await sm.start("aa11");
    ctx.agentCreatedTabs.add(11); // no longer in state → remove throws
    const state: FakeState = {
      tabs: new Map([[10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab]]),
      windowsClosed: new Set(),
      moves: [],
    };
    const { tabs, windows } = makeApis(state);
    (tabs.remove as ReturnType<typeof vi.fn>).mockImplementation(async (id: number) => {
      if (id === 11) throw new Error("tab 11 already closed");
      state.tabs.delete(id); // home (10) removed normally
    });
    const query = makeQuery(state);
    const res = await handleSessionStop(
      sm,
      { session_id: "aa11" },
      { tabManagement: { tabs, windows }, tabsQuery: query },
    );
    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
    // user tab 10? no — 10 is home, removed. window would be empty → close.
    expect(res.window_released).toBeFalsy();
    expect(aw.remove).toHaveBeenCalled();
  });
  it("degrades to close-window when tabsQuery is missing", async () => {
    const aw = fakeAgentWindow([agentWindowId]);
    aw.ensureActiveTab = vi.fn(async () => 10);
    const sm = new SessionManager({ agentWindow: aw });
    const ctx = await sm.start("aa11");
    ctx.agentCreatedTabs.add(11);
    const state: FakeState = {
      tabs: new Map([
        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
      ]),
      windowsClosed: new Set(),
      moves: [],
    };
    const { tabs, windows } = makeApis(state);
    const res = await handleSessionStop(
      sm,
      { session_id: "aa11" },
      { tabManagement: { tabs, windows } }, // no tabsQuery
    );
    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
    // No query available → conservatively close the window.
    expect(res.window_released).toBeFalsy();
    expect(aw.remove).toHaveBeenCalledWith(agentWindowId);
  });
  it("degrades to close-window when tabsQuery.query throws", async () => {
    const aw = fakeAgentWindow([agentWindowId]);
    aw.ensureActiveTab = vi.fn(async () => 10);
    const sm = new SessionManager({ agentWindow: aw });
    const ctx = await sm.start("aa11");
    ctx.agentCreatedTabs.add(11);
    const state: FakeState = {
      tabs: new Map([[11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab]]),
      windowsClosed: new Set(),
      moves: [],
    };
    const { tabs, windows } = makeApis(state);
    const query = makeQuery(state);
    (query.query as ReturnType<typeof vi.fn>).mockImplementation(async () => {
      throw new Error("query failed");
    });
    const res = await handleSessionStop(
      sm,
      { session_id: "aa11" },
      { tabManagement: { tabs, windows }, tabsQuery: query },
    );
    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
    expect(res.window_released).toBeFalsy();
    expect(aw.remove).toHaveBeenCalled();
  });
  it("tracks agentCreatedTabs across tab_create / tab_close", async () => {
    const aw = fakeAgentWindow([agentWindowId]);
    aw.ensureActiveTab = vi.fn(async () => 10);
    const sm = new SessionManager({ agentWindow: aw });
    const ctx = await sm.start("aa11");
    // Simulate handleTabCreate adding, then handleTabClose removing.
    ctx.agentCreatedTabs.add(11);
    expect(ctx.agentCreatedTabs.has(11)).toBe(true);
    ctx.agentCreatedTabs.delete(11); // as handleTabClose does on success
    expect(ctx.agentCreatedTabs.has(11)).toBe(false);
    // Unknown id delete is a safe no-op (user-closed tab).
    expect(() => ctx.agentCreatedTabs.delete(999)).not.toThrow();
  });
  it("closes the window (not release) when an agent tab fails to close", async () => {
    // Regression: a leaked agent tab (still in agentCreatedTabs, but
    // still present because Step 4 remove() threw) must NOT be mistaken
    // for a user tab. Otherwise the window would be released (dropOnly)
    // and the agent tab would leak (issue #57 regression).
    const aw = fakeAgentWindow([agentWindowId]);
    aw.ensureActiveTab = vi.fn(async () => 10);
    const sm = new SessionManager({ agentWindow: aw });
    const ctx = await sm.start("aa11");
    ctx.agentCreatedTabs.add(11); // Step 4 remove() will throw for this tab
    const state: FakeState = {
      tabs: new Map([
        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
      ]),
      windowsClosed: new Set(),
      moves: [],
    };
    const { tabs, windows } = makeApis(state);
    (tabs.remove as ReturnType<typeof vi.fn>).mockImplementation(async (id: number) => {
      if (id === 11) throw new Error("tab 11 failed to close");
      state.tabs.delete(id); // home (10) removed normally; 11 lingers
    });
    const query = makeQuery(state);
    const res = await handleSessionStop(
      sm,
      { session_id: "aa11" },
      { tabManagement: { tabs, windows }, tabsQuery: query },
    );
    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
    // The leaked agent tab must NOT keep the window open.
    expect(res.window_released).toBeFalsy();
    expect(aw.remove).toHaveBeenCalledWith(agentWindowId);
    expect(sm.has("aa11")).toBe(false);
  });
 });
@@ -12,7 +12,7 @@ function fakeAgentWindow() {
  return {
    create: vi.fn(async () => 100),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
  };
 }
@@ -11,7 +11,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    },
    remove: async () => {},
-    ensureActiveTab: async () => 1,
+    ensureActiveTab: async () => {},
  };
 }
@@ -1,7 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
 import { type CdpDebuggerApi, ChromiumCdp } from "@/browser-driver/chromium-cdp";
 import { SessionManager } from "@/session-manager/manager";
 import { handleHover } from "../interaction";
 import {
  type AgentOverlayResetApi,
  type ChromeWindowsApi,
@@ -25,7 +23,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
  };
 }
@@ -223,7 +221,6 @@ describe("handleTabCreate", () => {
      active: true,
    });
    expect(res).toMatchObject({ tab_id: 10, window_id: 100 });
    expect(sm.get("aa11")?.agentCreatedTabs.has(10)).toBe(true);
  });
  it("forwards explicit url + index + active=false", async () => {
@@ -259,41 +256,6 @@ describe("handleTabCreate", () => {
    const res = await handleTabCreate(sm, { session_id: "aa11", index: -1 }, { tabs: api });
    expect(res).toMatchObject({ code: "invalid_params" });
  });
  it("does not claim any tab when chrome.tabs.create fails", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    await sm.start("aa11");
    const state: FakeTabState = { tabs: new Map(), nextTabId: 10, windowsClosed: new Set() };
    const { api, spies } = makeTabMutationApi(state);
    spies.create.mockRejectedValueOnce(new Error("chrome.tabs.create failed"));
    const res = await handleTabCreate(sm, { session_id: "aa11" }, { tabs: api });
    expect(res).toMatchObject({ code: "protocol_error" });
    expect(sm.get("aa11")?.agentCreatedTabs).toEqual(new Set([1]));
  });
  it("claims the returned id even when a user tab appears during tab creation", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
    const state: FakeTabState = { tabs: new Map(), nextTabId: 10, windowsClosed: new Set() };
    const { api, spies } = makeTabMutationApi(state);
    let resolveCreate!: (tab: chrome.tabs.Tab) => void;
    const createResult = new Promise<chrome.tabs.Tab>((resolve) => {
      resolveCreate = resolve;
    });
    spies.create.mockImplementationOnce(() => createResult);
    const pending = handleTabCreate(sm, { session_id: "aa11" }, { tabs: api });
    // A user can create an unrelated same-window tab while Chrome is still
    // resolving the agent request. There is no pending slot for it to steal.
    expect(ctx.agentCreatedTabs.has(99)).toBe(false);
    resolveCreate({ id: 10, windowId: 100, active: true } as chrome.tabs.Tab);
    await expect(pending).resolves.toMatchObject({ tab_id: 10 });
    expect(ctx.agentCreatedTabs.has(10)).toBe(true);
    expect(ctx.agentCreatedTabs.has(99)).toBe(false);
  });
 });
 describe("handleTabClose", () => {
@@ -549,148 +511,6 @@ describe("handleTabBorrow", () => {
 });
 describe("handleTabReturn", () => {
  it.each([
    "not_found",
    "cdp_failed",
  ])("detaches after selector resolution fails with %s", async (code) => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
    ctx.borrowedTabs.set(7, { tabId: 7, originalWindowId: 200, originalIndex: 4 });
    const state: FakeTabState = {
      tabs: new Map([[7, { id: 7, windowId: 100 } as chrome.tabs.Tab]]),
      nextTabId: 50,
      windowsClosed: new Set(),
    };
    const { api } = makeTabMutationApi(state);
    const { api: windows } = makeWindowsApi(state);
    const debuggerApi = {
      attach: vi.fn(async () => {}),
      detach: vi.fn(async () => {}),
      sendCommand: vi.fn(async (_target: unknown, method: string) => {
        if (method === "DOM.getDocument") return { root: { nodeId: 1 } };
        if (method === "DOM.querySelector") {
          if (code === "cdp_failed") throw new Error("selector query failed");
          return { nodeId: 0 };
        }
        return {};
      }),
      onEvent: { addListener: vi.fn(), removeListener: vi.fn() },
      onDetach: { addListener: vi.fn(), removeListener: vi.fn() },
    };
    const cdp = new ChromiumCdp(debuggerApi as unknown as CdpDebuggerApi);
    const hover = await handleHover(
      sm,
      { session_id: "aa11", tab_id: 7, selector: "#missing" },
      {
        cdp,
        tabsApi: { get: api.get, query: vi.fn(async () => []) },
      },
    );
    expect(hover).toMatchObject({ code });
    expect(cdp.isAttached(7)).toBe(true);
    const returned = await handleTabReturn(
      sm,
      { session_id: "aa11", tab_id: 7 },
      {
        tabs: api,
        windows,
        cdp,
        agentOverlayReset: { resetAgentOverlays: vi.fn(async () => {}) },
      },
    );
    expect(returned).toMatchObject({ returned_to_window_id: 200 });
    expect(ctx.borrowedTabs.has(7)).toBe(false);
    expect(cdp.isAttached(7)).toBe(false);
    expect(debuggerApi.detach).toHaveBeenCalledExactlyOnceWith({ tabId: 7 });
    cdp.dispose();
  });
  it("honours cancellation while preparing a validated return", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
    ctx.borrowedTabs.set(7, { tabId: 7, originalWindowId: 200, originalIndex: 4 });
    const state: FakeTabState = {
      tabs: new Map([[7, { id: 7, windowId: 100 } as chrome.tabs.Tab]]),
      nextTabId: 50,
      windowsClosed: new Set(),
    };
    const { api, spies } = makeTabMutationApi(state);
    const { api: windows } = makeWindowsApi(state);
    const controller = new AbortController();
    const beforeReturn = vi.fn(async () => {
      controller.abort();
    });
    const result = await handleTabReturn(
      sm,
      { session_id: "aa11", tab_id: 7 },
      {
        tabs: api,
        windows,
        signal: controller.signal,
        beforeReturn,
      },
    );
    expect(result).toMatchObject({ code: "cancelled" });
    expect(beforeReturn).toHaveBeenCalledExactlyOnceWith("aa11", 7);
    expect(spies.move).not.toHaveBeenCalled();
    expect(ctx.borrowedTabs.has(7)).toBe(true);
  });
  it.each([
    "original",
    "fallback",
    "cleanup_failed",
    "failed",
    "cancelled",
  ])("releases CDP only after a successful return (%s)", async (mode) => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
    ctx.borrowedTabs.set(7, { tabId: 7, originalWindowId: 200, originalIndex: 4 });
    const state: FakeTabState = {
      tabs: new Map([[7, { id: 7, windowId: 100 } as chrome.tabs.Tab]]),
      nextTabId: 50,
      windowsClosed: new Set(),
    };
    const { api, spies } = makeTabMutationApi(state);
    const { api: windowsApi } = makeWindowsApi(state, { lastFocused: 500 });
    const success = mode !== "failed" && mode !== "cancelled";
    if (mode === "fallback") spies.move.mockRejectedValueOnce(new Error("original move failed"));
    if (mode === "failed") spies.move.mockRejectedValue(new Error("move failed"));
    let windowAtRelease: number | undefined;
    const cdp = {
      releaseSessionTab: vi.fn(async () => {
        windowAtRelease = state.tabs.get(7)?.windowId;
        if (mode === "cleanup_failed") throw new Error("debugger release failed");
      }),
    };
    const controller = new AbortController();
    if (mode === "cancelled") controller.abort();
    const result = await handleTabReturn(
      sm,
      { session_id: "aa11", tab_id: 7 },
      {
        tabs: api,
        windows: windowsApi,
        cdp,
        signal: controller.signal,
        agentOverlayReset: { resetAgentOverlays: vi.fn(async () => {}) },
      },
    );
    expect("code" in result).toBe(!success);
    expect(ctx.borrowedTabs.has(7)).toBe(!success);
    expect(cdp.releaseSessionTab).toHaveBeenCalledTimes(success ? 1 : 0);
    if (success) {
      expect(cdp.releaseSessionTab).toHaveBeenCalledWith("aa11", 7);
      expect(windowAtRelease).toBe(mode === "fallback" ? 500 : 200);
      expect(spies.move).toHaveBeenCalledTimes(mode === "fallback" ? 2 : 1);
    }
  });
  it("returns the tab to its original window/index and clears borrowedTabs", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
@@ -12,7 +12,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
  };
 }
@@ -11,7 +11,7 @@ function fakeAgentWindow(ids: number[]) {
    return id;
  });
  const remove = vi.fn(async () => {});
-  const ensureActiveTab = vi.fn(async () => 1);
+  const ensureActiveTab = vi.fn(async () => {});
  return { create, remove, ensureActiveTab };
 }
@@ -24,7 +24,7 @@ export interface BorrowResponseMessage {
  allowed: boolean;
 }
-export const CONFIRMATION_TIMEOUT_MS = 60_000;
+export const CONFIRMATION_TIMEOUT_MS = 5000;
 const EXIT_ANIMATION_MS = 150;
 /** Matches BorrowConfirmationOverlay progress ring/bar transition (duration-1000). */
 export const PROGRESS_TRANSITION_MS = 1000;
@@ -480,13 +480,6 @@ export async function requestBorrowConfirmation(
      settle(false);
    }, BACKGROUND_TIMEOUT_MS);
    // Bring the user window to the front so the overlay is visible even
    // when the Agent Window has stolen focus. This is fire-and-forget: if
    // it fails the overlay / OS notification still give the user a path.
    void windowsApi.update(notificationAnchor.windowId, { focused: true }).catch((err) => {
      console.debug("[bsk borrow] proactive focus of user window failed", err);
    });
    // Surface the OS notification *before* messaging any candidate so the
    // user has a parallel signal even if every content script is missing.
    // The Allow / Deny buttons let the user authorize explicitly when the
@@ -1,110 +0,0 @@
 import type { RpcError, WaitUntil } from "@/transport/types";
 import { cdpError } from "./errors";
 interface NavigationEvent {
  tabId: number;
  frameId: number;
  documentId?: string;
  error?: string;
 }
 interface NavigationEvents {
  addListener(listener: (details: NavigationEvent) => void): void;
  removeListener(listener: (details: NavigationEvent) => void): void;
 }
 /** Normal browser navigation remains available when chrome.debugger is denied. */
 export interface BrowserNavigationApi {
  update(tabId: number, props: { url: string }): Promise<unknown>;
  reload(tabId: number, props: { bypassCache: boolean }): Promise<void>;
  onCommitted: NavigationEvents;
  onDOMContentLoaded: NavigationEvents;
  onCompleted: NavigationEvents;
  onErrorOccurred: NavigationEvents;
 }
 export const chromeBrowserNavigationApi: BrowserNavigationApi = {
  update: (tabId, props) => chrome.tabs.update(tabId, props),
  reload: (tabId, props) => chrome.tabs.reload(tabId, props),
  get onCommitted() {
    return chrome.webNavigation.onCommitted;
  },
  get onDOMContentLoaded() {
    return chrome.webNavigation.onDOMContentLoaded;
  },
  get onCompleted() {
    return chrome.webNavigation.onCompleted;
  },
  get onErrorOccurred() {
    return chrome.webNavigation.onErrorOccurred;
  },
 };
 export type NavigationOutcome =
  | { reached: "match" | "timeout" | "cancelled"; lastLifecycle?: string }
  | { reached: "failed"; error: RpcError };
 /** Subscribe before dispatch and ignore the departing document's load events. */
 export async function navigateWithBrowserApi(
  api: BrowserNavigationApi,
  tabId: number,
  action: () => Promise<unknown>,
  waitUntil: Exclude<WaitUntil, "networkidle">,
  timeoutMs: number,
  signal?: AbortSignal,
 ): Promise<NavigationOutcome> {
  if (signal?.aborted) return { reached: "cancelled" };
  if (timeoutMs <= 0) return { reached: "timeout" };
  let committed = false;
  let documentId: string | undefined;
  let lastLifecycle: string | undefined;
  let finish!: (outcome: NavigationOutcome) => void;
  const outcome = new Promise<NavigationOutcome>((resolve) => {
    finish = resolve;
  });
  const isMainFrame = (details: NavigationEvent) =>
    details.tabId === tabId && details.frameId === 0;
  const onCommitted = (details: NavigationEvent) => {
    if (!isMainFrame(details)) return;
    committed = true;
    documentId = details.documentId;
    lastLifecycle = "commit";
    if (waitUntil === "commit") finish({ reached: "match", lastLifecycle });
  };
  const onDOMContentLoaded = (details: NavigationEvent) => {
    if (!isMainFrame(details) || !committed || (documentId && details.documentId !== documentId))
      return;
    lastLifecycle = "DOMContentLoaded";
    if (waitUntil === "domcontentloaded") finish({ reached: "match", lastLifecycle });
  };
  const onCompleted = (details: NavigationEvent) => {
    if (!isMainFrame(details) || !committed || (documentId && details.documentId !== documentId))
      return;
    finish({ reached: "match", lastLifecycle: "load" });
  };
  const onError = (details: NavigationEvent) => {
    if (!isMainFrame(details)) return;
    finish({ reached: "failed", error: cdpError(details.error ?? "browser navigation failed") });
  };
  const onAbort = () => finish({ reached: "cancelled", lastLifecycle });
  const subscriptions = [
    [api.onCommitted, onCommitted],
    [api.onDOMContentLoaded, onDOMContentLoaded],
    [api.onCompleted, onCompleted],
    [api.onErrorOccurred, onError],
  ] as const;
  for (const [event, listener] of subscriptions) event.addListener(listener);
  signal?.addEventListener("abort", onAbort, { once: true });
  const timer = setTimeout(() => finish({ reached: "timeout", lastLifecycle }), timeoutMs);
  try {
    if (signal?.aborted) return { reached: "cancelled" };
    await action();
    return await outcome;
  } catch (error) {
    return { reached: "failed", error: cdpError(error) };
  } finally {
    clearTimeout(timer);
    signal?.removeEventListener("abort", onAbort);
    for (const [event, listener] of subscriptions) event.removeListener(listener);
  }
 }
@@ -1,9 +0,0 @@
 export {
  type CaptureVomObservationOptions,
  captureVomObservation,
 } from "./observation";
 export {
  type CaptureVomFrame,
  type CaptureVomMatchNode,
  type CaptureVomObservationResult,
 } from "./vom/record-safe-observation";
@@ -36,7 +36,6 @@ import { isRequestFrame } from "@/transport/types";
 import { handleConsole } from "./console";
 import { handleDownload } from "./download";
 import { type EmulateCdpRunner, handleEmulate } from "./emulate";
 import { classifyCdpError } from "./errors";
 import { handleEvaluate } from "./evaluate";
 import { handleRequestHelp } from "./human-loop";
 import { handleClick, handleFill, handleHover, handlePress, handleSelect } from "./interaction";
@@ -55,12 +54,7 @@ import {
  handleScreenshot,
  handleSnapshot,
 } from "./observation";
-import {
+import { handleRecordAwait, handleRecordStart, handleRecordStop } from "./record";
  handleRecordAwait,
  handleRecordStart,
  handleRecordStop,
  type RecordRuntimeDeps,
 } from "./record";
 import {
  handleSessionStart,
  handleSessionStop,
@@ -70,7 +64,6 @@ import {
 import { chromeTabsApi, lookupSession, resolveTargetTab } from "./shared";
 import {
  type BorrowConfirmationApprover,
  chromeTabMutationApi,
  handleTabBorrow,
  handleTabClose,
  handleTabCreate,
@@ -110,7 +103,6 @@ export interface DispatcherDeps {
  transport: Transport;
  sessions: SessionManager;
  cdp?: DispatcherCdpRunner;
  recording?: RecordRuntimeDeps;
  /**
   * Invoked whenever a dispatched RPC may have changed the live
   * session set (currently `tool.session_start` and
@@ -120,8 +112,6 @@ export interface DispatcherDeps {
  onSessionsChanged?: () => void;
  /** Invoked before a tool that dispatches page input or mutates browser state is forwarded. */
  onBrowserControlResumed?: (sessionId: string) => void;
  /** Invoked after a tab is explicitly claimed so its overlay can be refreshed immediately. */
  onAgentTabClaimed?: (tabId: number, windowId: number) => void;
  /** User approval for `tool.tab_borrow` (overlay in content script). */
  approveBorrow?: BorrowConfirmationApprover;
  /** i18n notification copy for `tool.request_help` (resolved per-call). */
@@ -148,10 +138,8 @@ export class ToolDispatcher {
  private readonly transport: Transport;
  private readonly sessions: SessionManager;
  private readonly cdp?: DispatcherCdpRunner;
  private readonly recording?: RecordRuntimeDeps;
  private readonly onSessionsChanged?: () => void;
  private readonly onBrowserControlResumed?: (sessionId: string) => void;
  private readonly onAgentTabClaimed?: (tabId: number, windowId: number) => void;
  private readonly approveBorrow?: BorrowConfirmationApprover;
  private readonly helpNotificationCopy?: () => { title: string; body: string };
  private subscription: { dispose(): void } | null = null;
@@ -169,10 +157,8 @@ export class ToolDispatcher {
    this.transport = deps.transport;
    this.sessions = deps.sessions;
    this.cdp = deps.cdp;
    this.recording = deps.recording;
    this.onSessionsChanged = deps.onSessionsChanged;
    this.onBrowserControlResumed = deps.onBrowserControlResumed;
    this.onAgentTabClaimed = deps.onAgentTabClaimed;
    this.approveBorrow = deps.approveBorrow;
    this.helpNotificationCopy = deps.helpNotificationCopy;
  }
@@ -240,7 +226,7 @@ export class ToolDispatcher {
      if (sessionId) this.onBrowserControlResumed?.(sessionId);
      const result = await this.invoke(req, ac.signal);
      if (isRpcError(result)) {
-        body = { id: req.id, error: classifyCdpError(result) };
+        body = { id: req.id, error: result };
      } else {
        body = { id: req.id, result };
        if (req.method === "tool.session_start") {
@@ -308,25 +294,12 @@ export class ToolDispatcher {
        await this.releaseHoverLatch((req.params as SessionStopParams).session_id);
        return handleSessionStop(this.sessions, req.params as SessionStopParams, {
          cdp: this.cdp,
          // Must be wired in production: the agent-tab cleanup and the
          // window-release decision (issue #57) read these deps directly
          // and silently no-op when they are absent.
          tabManagement: { tabs: chromeTabMutationApi },
          tabsQuery: chromeTabsApi,
          signal,
        });
      }
      case "tool.tab_list":
        return handleTabList(this.sessions, req.params as TabListParams, chromeTabsApi, signal);
-      case "tool.tab_create": {
+      case "tool.tab_create":
-        const result = await handleTabCreate(this.sessions, req.params as TabCreateParams, {
+        return handleTabCreate(this.sessions, req.params as TabCreateParams, { signal });
          signal,
        });
        if (!isRpcError(result)) {
          this.onAgentTabClaimed?.(result.tab_id, result.window_id);
        }
        return result;
      }
      case "tool.tab_close":
        return this.withHoverReleaseForRequest(
          req.params as TabCloseParams,
@@ -335,22 +308,13 @@ export class ToolDispatcher {
        );
      case "tool.tab_select":
        return handleTabSelect(this.sessions, req.params as TabSelectParams, { signal });
-      case "tool.tab_borrow": {
+      case "tool.tab_borrow":
-        const result = await handleTabBorrow(this.sessions, req.params as TabBorrowParams, {
+        return handleTabBorrow(this.sessions, req.params as TabBorrowParams, {
          signal,
          approveBorrow: this.approveBorrow,
        });
        if (!isRpcError(result)) {
          this.onAgentTabClaimed?.(result.tab_id, result.agent_window_id);
        }
        return result;
      }
      case "tool.tab_return":
-        return handleTabReturn(this.sessions, req.params as TabReturnParams, {
+        return handleTabReturn(this.sessions, req.params as TabReturnParams, { signal });
          signal,
          cdp: this.cdp,
          beforeReturn: (sessionId, tabId) => this.releaseHoverLatch(sessionId, tabId),
        });
      case "tool.window_resize":
        return handleWindowResize(
          this.sessions,
@@ -414,11 +378,7 @@ export class ToolDispatcher {
                ? {
                    cdp: this.cdp,
                    tabsApi: chromeTabsCaptureApi,
-                    // Active hover probing is opt-in. A held hover latch still
+                    conditionalSurfaceProbe: !this.hasHoverLatchForScope(hoverScope),
                    // suppresses it, because probing would move the cursor off
                    // the element the caller is deliberately holding.
                    conditionalSurfaceProbe:
                      params.probe_hover === true && !this.hasHoverLatchForScope(hoverScope),
                    hoverProbeBypassOverlay: bypassOverlay,
                  }
                : undefined,
@@ -608,26 +568,44 @@ export class ToolDispatcher {
          signal,
        });
      case "tool.record_start":
-        return this.recording
+        return handleRecordStart(this.sessions, req.params as RecordStartParams, {
-          ? handleRecordStart(this.sessions, req.params as RecordStartParams, {
+          tabsApi: chromeTabsApi,
-              ...this.recording,
+          sendToTab: (tabId, msg) => chrome.tabs.sendMessage(tabId, msg),
-              signal,
+          bypassOverlay: async (tabId, enabled) => {
-            })
+            try {
-          : recordingRuntimeUnavailable();
+              await chrome.tabs.sendMessage(tabId, {
                type: OVERLAY_AUTOMATION_BYPASS,
                enabled,
              });
            } catch {
              // Content script may be unavailable on restricted pages.
            }
          },
          ...(this.cdp ? { cdp: this.cdp } : {}),
          signal,
        });
      case "tool.record_stop":
-        return this.recording
+        return handleRecordStop(this.sessions, req.params as RecordStopParams, {
-          ? handleRecordStop(this.sessions, req.params as RecordStopParams, {
+          tabsApi: chromeTabsApi,
-              ...this.recording,
+          sendToTab: (tabId, msg) => chrome.tabs.sendMessage(tabId, msg),
-              signal,
+          bypassOverlay: async (tabId, enabled) => {
-            })
+            try {
-          : recordingRuntimeUnavailable();
+              await chrome.tabs.sendMessage(tabId, {
                type: OVERLAY_AUTOMATION_BYPASS,
                enabled,
              });
            } catch {
              // Content script may be unavailable on restricted pages.
            }
          },
          signal,
        });
      case "tool.record_await":
-        return this.recording
+        return handleRecordAwait(this.sessions, req.params as RecordAwaitParams, {
-          ? handleRecordAwait(this.sessions, req.params as RecordAwaitParams, {
+          tabsApi: chromeTabsApi,
-              ...this.recording,
+          sendToTab: (tabId, msg) => chrome.tabs.sendMessage(tabId, msg),
-              signal,
+          signal,
-            })
+        });
          : recordingRuntimeUnavailable();
      default:
        return {
          code: "unknown_method",
@@ -763,13 +741,6 @@ function isRpcError(v: unknown): v is RpcError {
  );
 }
 function recordingRuntimeUnavailable(): RpcError {
  return {
    code: "protocol_error",
    message: "recording runtime is unavailable",
  };
 }
 function sessionIdForBrowserControlMethod(req: RequestFrame): string | null {
  switch (req.method) {
    case "tool.tab_create":
@@ -108,37 +108,13 @@ function captureError(
  });
 }
 async function cleanupClaimedDownload(downloads: DownloadsApi, downloadId: number): Promise<void> {
  const lookup = async () => (await downloads.search({ id: downloadId }))[0];
  const item = await lookup();
  if (!item || item.state === "interrupted") return;
  if (item.state === "complete") {
    await downloads.removeFile(downloadId);
    return;
  }
  try {
    await downloads.cancel(downloadId);
  } catch (cancelError) {
    // Completion can win the race after the lookup but before cancellation.
    // Reconcile against Chrome's authoritative state before declaring cleanup
    // failed so every terminal state has one explicit cleanup path.
    const reconciled = await lookup();
    if (!reconciled || reconciled.state === "interrupted") return;
    if (reconciled.state === "complete") {
      await downloads.removeFile(downloadId);
      return;
    }
    throw cancelError;
  }
 }
 export async function captureBrowserDownload(
  options: DownloadCaptureOptions,
 ): Promise<DownloadCaptureResult | RpcError> {
  let click: ClickResult | undefined;
  let intent: DownloadIntent | undefined;
  let capturedId: number | undefined;
  let capturedItem: chrome.downloads.DownloadItem | undefined;
  let settled = false;
  let succeeded = false;
  let failureResult: RpcError | undefined;
@@ -167,6 +143,7 @@ export async function captureBrowserDownload(
      return;
    }
    settled = true;
    capturedItem = item;
    resolveCompletion(item);
  };
  const suggestDefault = (candidate: DownloadCandidate) => {
@@ -198,6 +175,7 @@ export async function captureBrowserDownload(
    candidate.suggested = true;
    clearTimeout(candidate.graceTimer);
    capturedId = candidate.item.id;
    capturedItem = candidate.item;
    candidate.suggest({
      filename: `${options.browserRelativeDir}/${safeBasename(intent.suggestedFilename)}`,
      conflictAction: "overwrite",
@@ -247,6 +225,7 @@ export async function captureBrowserDownload(
  const createdListener = (item: chrome.downloads.DownloadItem) => {
    createdItems.set(item.id, item);
    if (capturedId !== item.id) return;
    capturedItem = item;
    if (item.state === "interrupted") {
      fail(new Error(item.error ?? "download interrupted"));
    } else if (item.state === "complete") {
@@ -307,6 +286,7 @@ export async function captureBrowserDownload(
      .search({ id: capturedId })
      .then(([item]) => {
        if (!item || settled) return;
        capturedItem = item;
        if (item.bytesReceived > (options.maxByteSize as number)) {
          fail(new Error(`download exceeds transfer limit ${options.maxByteSize}`));
        }
@@ -354,8 +334,13 @@ export async function captureBrowserDownload(
      if (candidate.item.id !== capturedId) suggestDefault(candidate);
    }
    if (!succeeded && capturedId !== undefined) {
      const item = capturedItem ?? createdItems.get(capturedId);
      try {
-        await cleanupClaimedDownload(options.downloads, capturedId);
+        if (item?.state === "complete") {
          await options.downloads.removeFile(capturedId);
        } else {
          await options.downloads.cancel(capturedId);
        }
      } catch {
        if (failureResult?.data) failureResult.data.cleanup_state = "failed";
      }
@@ -13,34 +13,6 @@ import type {
 export type { RpcErrorData, RpcErrorReason };
 /** Chrome checks the whole tab's frame tree, including other extensions' frames. */
 export function isCdpExtensionAccessDenied(error: unknown): boolean {
  const message = error instanceof Error ? error.message : String(error);
  return message.includes("Cannot access a chrome-extension:// URL of different extension");
 }
 /** Preserve more specific reasons, especially file-transfer outcome/cleanup details. */
 export function classifyCdpError(error: RpcError): RpcError {
  if (
    error.code !== "cdp_failed" ||
    error.data?.reason ||
    !isCdpExtensionAccessDenied(error.message)
  ) {
    return error;
  }
  return {
    ...error,
    data: { ...error.data, reason: "cdp_extension_access_denied" },
  };
 }
 export function cdpError(error: unknown): RpcError {
  return classifyCdpError({
    code: "cdp_failed",
    message: error instanceof Error ? error.message : String(error),
  });
 }
 export interface TransferErrorOptions {
  effectState: TransferEffectState;
  phase: string;
@@ -1,319 +0,0 @@
 // One native file-drop transaction bound to an explicit page target. CDP drag
 // events are sent to the target that owns the node: root targets use top-level
 // coordinates, while OOPIF targets require coordinates local to their session.
 import type { RpcError, TransferEffectState } from "@/transport/types";
 import { transferError } from "./errors";
 import { resolveNodeGeometry } from "./frame-geometry";
 import type { ResolvedActionTarget } from "./interaction";
 import { type CdpRunner, isRpcError, sendToCdpTarget } from "./shared";
 import { BoundedWaitError, waitBounded } from "./transfer-transaction";
 const CLEANUP_TIMEOUT_MS = 1_000;
 type FileDropPhase = "resolve_target" | "drag_enter" | "drag_over" | "drop" | "cleanup";
 interface RuntimeReply {
  result?: { value?: unknown; objectId?: string };
  exceptionDetails?: { text?: string; exception?: { description?: string } };
 }
 interface DragData {
  items: [];
  files: string[];
  dragOperationsMask: number;
 }
 export interface FileDropTransactionOptions {
  cdp: CdpRunner;
  actionTarget: ResolvedActionTarget;
  files: string[];
  timeoutMs: number;
  signal?: AbortSignal;
  withOverlayHidden: <T>(operation: () => Promise<T>) => Promise<T>;
 }
 export interface FileDropTransactionResult {
  x: number;
  y: number;
 }
 function failure(
  code: RpcError["code"],
  reason: "upload_mechanism_unsupported" | "file_drop_target_unavailable" | "file_drop_failed",
  message: string,
  effectState: TransferEffectState,
  phase: FileDropPhase,
 ): RpcError {
  const error = transferError(code, reason, message, { effectState, phase });
  error.data = { ...error.data, mechanism: "drop" };
  return error;
 }
 function enrichFailure(
  error: RpcError,
  effectState: TransferEffectState,
  phase: FileDropPhase,
 ): RpcError {
  return {
    ...error,
    data: {
      ...error.data,
      mechanism: "drop",
      effect_state: effectState,
      phase,
    },
  };
 }
 function messageOf(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
 }
 function methodUnavailable(error: unknown): boolean {
  return /(?:method|command).*(?:not found|wasn't found|unsupported)|wasn't found|-32601/i.test(
    messageOf(error),
  );
 }
 function runtimeError(reply: RuntimeReply, fallback: string): Error | null {
  if (!reply.exceptionDetails) return null;
  return new Error(
    reply.exceptionDetails.exception?.description ?? reply.exceptionDetails.text ?? fallback,
  );
 }
 async function pointBelongsToTarget(
  options: FileDropTransactionOptions,
  x: number,
  y: number,
  objectGroup: string,
 ): Promise<boolean> {
  const target = options.actionTarget.cdpTarget;
  const hit = await sendToCdpTarget<{ backendNodeId?: number; frameId?: string }>(
    options.cdp,
    target,
    "DOM.getNodeForLocation",
    { x: Math.round(x), y: Math.round(y), includeUserAgentShadowDOM: true },
  );
  if (typeof hit.backendNodeId !== "number") return false;
  if (options.actionTarget.frameId && hit.frameId !== options.actionTarget.frameId) return false;
  const [resolvedTarget, resolvedHit] = await Promise.all([
    sendToCdpTarget<{ object?: { objectId?: string } }>(options.cdp, target, "DOM.resolveNode", {
      backendNodeId: options.actionTarget.backendNodeId,
      objectGroup,
    }),
    sendToCdpTarget<{ object?: { objectId?: string } }>(options.cdp, target, "DOM.resolveNode", {
      backendNodeId: hit.backendNodeId,
      objectGroup,
    }),
  ]);
  const targetObjectId = resolvedTarget.object?.objectId;
  const hitObjectId = resolvedHit.object?.objectId;
  if (!targetObjectId || !hitObjectId) return false;
  const reply = await sendToCdpTarget<RuntimeReply>(options.cdp, target, "Runtime.callFunctionOn", {
    objectId: targetObjectId,
    functionDeclaration: `function(hit) {
        for (let node = hit; node; ) {
          if (node === this) return true;
          if (this.contains?.(node)) return true;
          const root = node.getRootNode?.();
          node = node.parentNode || (root && root !== node ? root.host : null);
        }
        return false;
      }`,
    arguments: [{ objectId: hitObjectId }],
    returnByValue: true,
  });
  const error = runtimeError(reply, "failed to verify file-drop target");
  if (error) throw error;
  return reply.result?.value === true;
 }
 export async function uploadThroughFileDrop(
  options: FileDropTransactionOptions,
 ): Promise<FileDropTransactionResult | RpcError> {
  const deadline = Date.now() + options.timeoutMs;
  const target = options.actionTarget.cdpTarget;
  const objectGroup = `bsk-file-drop-${crypto.randomUUID()}`;
  const dragData: DragData = {
    items: [],
    files: options.files,
    dragOperationsMask: 1,
  };
  let dragStarted = false;
  let dropSent = false;
  let dragPoint = { x: 0, y: 0 };
  let cleanupFailed = false;
  let outcome: FileDropTransactionResult | RpcError = failure(
    "protocol_error",
    "file_drop_failed",
    "file-drop transaction ended without an outcome",
    "none",
    "cleanup",
  );
  try {
    const geometry = await waitBounded(
      resolveNodeGeometry(
        options.cdp,
        options.actionTarget.tab.tabId,
        {
          target,
          backendNodeId: options.actionTarget.backendNodeId,
          ...(options.actionTarget.frameId ? { frameId: options.actionTarget.frameId } : {}),
        },
        { scrollIntoView: true },
      ),
      deadline,
      options.signal,
      "resolving file-drop target timed out",
    );
    if (isRpcError(geometry)) {
      outcome = enrichFailure(geometry, "none", "resolve_target");
      return outcome;
    }
    const point = geometry.targetActionPoint;
    dragPoint = point;
    outcome = await options.withOverlayHidden(async () => {
      try {
        try {
          const belongs = await waitBounded(
            pointBelongsToTarget(options, point.x, point.y, objectGroup),
            deadline,
            options.signal,
            "verifying file-drop target timed out",
          );
          if (!belongs) {
            return failure(
              "permission_denied",
              "file_drop_target_unavailable",
              "file-drop target is not the topmost element at its action point",
              "none",
              "resolve_target",
            );
          }
        } catch (error) {
          return failure(
            error instanceof BoundedWaitError ? "timeout" : "cdp_failed",
            "file_drop_target_unavailable",
            messageOf(error),
            "none",
            "resolve_target",
          );
        }
        for (const [type, phase] of [
          ["dragEnter", "drag_enter"],
          ["dragOver", "drag_over"],
        ] as const) {
          try {
            if (type === "dragEnter") dragStarted = true;
            await waitBounded(
              sendToCdpTarget(options.cdp, target, "Input.dispatchDragEvent", {
                type,
                x: point.x,
                y: point.y,
                data: dragData,
              }),
              deadline,
              options.signal,
              `${type} timed out`,
            );
          } catch (error) {
            const unsupported = methodUnavailable(error);
            if (type === "dragEnter" && unsupported) dragStarted = false;
            return failure(
              unsupported
                ? "unsupported"
                : error instanceof BoundedWaitError
                  ? "timeout"
                  : "cdp_failed",
              unsupported ? "upload_mechanism_unsupported" : "file_drop_failed",
              messageOf(error),
              "none",
              phase,
            );
          }
        }
        try {
          dropSent = true;
          await waitBounded(
            sendToCdpTarget(options.cdp, target, "Input.dispatchDragEvent", {
              type: "drop",
              x: point.x,
              y: point.y,
              data: dragData,
            }),
            deadline,
            options.signal,
            "file drop timed out",
          );
          return { x: point.x, y: point.y };
        } catch (error) {
          outcome = failure(
            error instanceof BoundedWaitError ? "timeout" : "cdp_failed",
            "file_drop_failed",
            messageOf(error),
            "unknown",
            "drop",
          );
          return outcome;
        }
      } finally {
        if (dragStarted && !dropSent) {
          try {
            await waitBounded(
              sendToCdpTarget(options.cdp, target, "Input.dispatchDragEvent", {
                type: "dragCancel",
                x: dragPoint.x,
                y: dragPoint.y,
                data: dragData,
              }),
              Date.now() + CLEANUP_TIMEOUT_MS,
              undefined,
              "cancelling file drag timed out",
            );
          } catch {
            cleanupFailed = true;
          }
        }
      }
    });
    return outcome;
  } catch (error) {
    outcome = failure(
      error instanceof BoundedWaitError ? "timeout" : "cdp_failed",
      "file_drop_target_unavailable",
      messageOf(error),
      "none",
      "resolve_target",
    );
    return outcome;
  } finally {
    try {
      await waitBounded(
        sendToCdpTarget(options.cdp, target, "Runtime.releaseObjectGroup", { objectGroup }),
        Date.now() + CLEANUP_TIMEOUT_MS,
        undefined,
        "releasing file-drop object group timed out",
      );
    } catch {
      cleanupFailed = true;
    }
    const effect = isRpcError(outcome)
      ? (outcome.data?.effect_state as TransferEffectState | undefined)
      : "committed";
    if (effect === "unknown" || cleanupFailed) {
      await options.cdp.detach?.(target.tabId);
    }
    if (cleanupFailed && isRpcError(outcome)) {
      outcome.data = { ...outcome.data, cleanup_state: "failed" };
    }
  }
 }
@@ -7,7 +7,6 @@ import type { ClickResult, RpcError, TransferEffectState } from "@/transport/typ
 import { transferError } from "./errors";
 import type { ResolvedActionTarget } from "./interaction";
 import { type CdpRunner, isRpcError, sendToCdpTarget } from "./shared";
 import { BoundedWaitError, remainingMs, waitBounded } from "./transfer-transaction";
 const CLEANUP_TIMEOUT_MS = 1_000;
 const ACTIVATION_GRACE_MS = 1_000;
@@ -46,6 +45,46 @@ export interface FileInputTransactionResult {
  multiple: boolean;
 }
 class BoundedWaitError extends Error {
  constructor(
    readonly kind: "timeout" | "aborted",
    message: string,
  ) {
    super(message);
  }
 }
 function remainingMs(deadline: number): number {
  return Math.max(0, deadline - Date.now());
 }
 async function waitBounded<T>(
  promise: Promise<T>,
  deadline: number,
  signal: AbortSignal | undefined,
  timeoutMessage: string,
 ): Promise<T> {
  const remaining = remainingMs(deadline);
  if (signal?.aborted) throw new BoundedWaitError("aborted", "upload transaction aborted");
  if (remaining === 0) throw new BoundedWaitError("timeout", timeoutMessage);
  let timer: ReturnType<typeof setTimeout> | undefined;
  let onAbort: (() => void) | undefined;
  const boundary = new Promise<never>((_resolve, reject) => {
    timer = setTimeout(() => reject(new BoundedWaitError("timeout", timeoutMessage)), remaining);
    if (signal) {
      onAbort = () => reject(new BoundedWaitError("aborted", "upload transaction aborted"));
      signal.addEventListener("abort", onAbort, { once: true });
    }
  });
  try {
    return await Promise.race([promise, boundary]);
  } finally {
    if (timer) clearTimeout(timer);
    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
  }
 }
 function runtimeError(reply: RuntimeReply, fallback: string): Error | null {
  if (!reply.exceptionDetails) return null;
  return new Error(
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Ljy-0827	ec62b8f0f2	fix(bsk): fix ci	2026-08-21 16:34:06 +08:00
Ljy-0827	9393f0e58b	feat(bsk): harden browser file transfer transactions	2026-08-21 16:31:47 +08:00
Ljy-0827	f9d395ee41	fix(bsk): fix ci	2026-08-21 14:32:29 +08:00
Ljy-0827	8f81c15656	fix(bsk): upload function safety	2026-08-21 14:11:13 +08:00
Ljy-0827	3cfa9eceef	feat(bsk): fix upload function that cannot bypass layout	2026-08-21 11:14:51 +08:00
Ljy-0827	34f47d7387	feat(bsk): fix different type of upload	2026-08-20 18:59:22 +08:00
Ljy-0827	0a184e33d1	feat(bsk): support upload and download	2026-08-20 16:51:50 +08:00