fix(record): rebase and dto policy

Wait for DOM quiet after actions, match targets to VOM refs, and reduce
drafts into deduped state-linked Trace v3 while keeping the v2 reducer.

Co-authored-by: Cursor <cursoragent@cursor.com>

Cargo.lock

@@ -134,7 +134,7 @@ dependencies = [
 
 [[package]]
 name = "bsk"
-version = "0.1.11"
+version = "0.1.10"
 dependencies = [
  "anyhow",
  "bsk-protocol",
@@ -168,7 +168,7 @@ dependencies = [
 
 [[package]]
 name = "bsk-protocol"
-version = "0.1.11"
+version = "0.1.10"
 dependencies = [
  "schemars",
  "semver",

Cargo.toml

@@ -7,7 +7,7 @@ members = [
 default-members = ["crates/bsk-cli"]
 
 [workspace.package]
-version = "0.1.11"
+version = "0.1.10"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT"

apps/extension/src/content/__tests__/record-capture.test.ts

@@ -1,12 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { RecordStepPayload } from "@/lib/record-bridge";
-import { startRecordCapture } from "../record-capture";
+import { RECORD_STOP, type RecordStepPayload } from "@/lib/record-bridge";
+import { handleRecordContentMessage, startRecordCapture } from "../record-capture";
 
 vi.stubGlobal("chrome", {
   runtime: {
-    sendMessage: vi.fn((message: { sequence?: number }) =>
-      Promise.resolve({ ok: true, sequence: message.sequence }),
-    ),
+    sendMessage: vi.fn(() => Promise.resolve()),
   },
 });
 
@@ -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",

apps/extension/src/content/__tests__/record-frame-agent.test.ts

@@ -1,102 +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(() => {
-    document.documentElement.removeAttribute(RECORD_DOCUMENT_ATTRIBUTE);
-    document.body.replaceChildren();
-  });
-
-  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);
-  });
-});

apps/extension/src/content/__tests__/record-step-delivery.test.ts

@@ -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);
-  });
-});

apps/extension/src/content/record-capture.ts

@@ -12,7 +12,21 @@ import {
   hasDirectHoverInteractiveSignal,
   hasStrongHoverExpansionSignal,
 } from "@/lib/hover-trigger-policy";
-import type { RecordStepPayload } from "@/lib/record-bridge";
+import {
+  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/recording/draft-policy";
 import {
   closestHoverSurfaceCandidate,
@@ -23,6 +37,28 @@ 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;
 }
@@ -32,7 +68,6 @@ interface FillSession {
   target: CaptureTargetDescriptor;
   baselineValue: string;
   lastValue: string;
-  pendingCommit?: "enter" | "suggestion" | "blur";
 }
 
 interface HoverCandidate {
@@ -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;
@@ -359,7 +376,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 +414,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 +627,6 @@ export function startRecordCapture(
     emitStep({
       op: "hover",
       target: hover.target,
-      geometry: captureGeometry(hover.element),
     });
     emittedHoverElements.add(hover.element);
   };
@@ -669,7 +681,6 @@ export function startRecordCapture(
     emitStep({
       op: "click",
       target,
-      geometry: geometryForEventTarget(eventTarget(event)),
       expects_navigation: true,
     });
   };
@@ -771,7 +782,7 @@ export function startRecordCapture(
       scheduleInputCompletionCommit(
         sessionElement,
         syncFillSessionValue,
-        () => commitFillSession("suggestion"),
+        commitFillSession,
         (el) => fillSession?.element === el,
       );
       return;
@@ -831,7 +842,6 @@ export function startRecordCapture(
       emitStep({
         op: "select",
         target: desc,
-        geometry: captureGeometry(target),
         values,
         labels,
         expects_navigation: true,
@@ -872,7 +882,7 @@ export function startRecordCapture(
       };
     }
     if (fillable) {
-      commitFillSession(event.key === "Enter" ? "enter" : "blur");
+      commitFillSession();
     }
     const desc = describeEventTarget(target);
     if (!desc && !event.key) return;
@@ -880,7 +890,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 +906,23 @@ export function startRecordCapture(
   document.addEventListener("change", onChange, true);
   document.addEventListener("keydown", onKeyDown, true);
 
-  const captureNavigation = options.captureNavigation ?? true;
-  const urlObserver = captureNavigation
-    ? new MutationObserver(() => emitNavigateIfChanged())
-    : null;
-  urlObserver?.observe(document, { subtree: true, childList: true });
+  const urlObserver = new MutationObserver(() => emitNavigateIfChanged());
+  urlObserver.observe(document, { subtree: true, childList: true });
   const onUrlEvent = () => emitNavigateIfChanged();
-  // Wrap: passing commitFillSession directly would forward the DOM event as
-  // the `commit` argument and stamp it onto the recorded fill step.
-  const onPageHide = () => commitFillSession();
-  if (captureNavigation) {
-    window.addEventListener("hashchange", onUrlEvent);
-    window.addEventListener("popstate", onUrlEvent);
-  }
-  window.addEventListener("pagehide", onPageHide);
+  window.addEventListener("hashchange", onUrlEvent);
+  window.addEventListener("popstate", onUrlEvent);
+  window.addEventListener("pagehide", commitFillSession);
 
   const originalPushState = history.pushState;
   const originalReplaceState = history.replaceState;
-  if (captureNavigation) {
-    history.pushState = function (...args: Parameters<History["pushState"]>) {
-      originalPushState.apply(this, args);
-      emitNavigateIfChanged(navigationActionPending ? true : undefined);
-    };
-    history.replaceState = function (...args: Parameters<History["replaceState"]>) {
-      originalReplaceState.apply(this, args);
-      emitNavigateIfChanged(navigationActionPending ? true : undefined);
-    };
-  }
+  history.pushState = function (...args: Parameters<History["pushState"]>) {
+    originalPushState.apply(this, args);
+    emitNavigateIfChanged(navigationActionPending ? true : undefined);
+  };
+  history.replaceState = function (...args: Parameters<History["replaceState"]>) {
+    originalReplaceState.apply(this, args);
+    emitNavigateIfChanged(navigationActionPending ? true : undefined);
+  };
 
   return {
     dispose() {
@@ -936,16 +936,93 @@ export function startRecordCapture(
       document.removeEventListener("compositionend", onCompositionEnd, true);
       document.removeEventListener("change", onChange, true);
       document.removeEventListener("keydown", onKeyDown, true);
-      urlObserver?.disconnect();
-      if (captureNavigation) {
-        window.removeEventListener("hashchange", onUrlEvent);
-        window.removeEventListener("popstate", onUrlEvent);
-      }
-      window.removeEventListener("pagehide", onPageHide);
-      if (captureNavigation) {
-        history.pushState = originalPushState;
-        history.replaceState = originalReplaceState;
-      }
+      urlObserver.disconnect();
+      window.removeEventListener("hashchange", onUrlEvent);
+      window.removeEventListener("popstate", onUrlEvent);
+      window.removeEventListener("pagehide", commitFillSession);
+      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 };

apps/extension/src/content/record-step-delivery.ts

@@ -1,65 +0,0 @@
-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 = crypto.randomUUID(),
-  ) {
-    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;
-      }
-    }
-  }
-}

apps/extension/src/content/recording/frame-agent.ts

@@ -1,209 +0,0 @@
-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 = crypto.randomUUID();
-    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();
-  };
-}

apps/extension/src/entrypoints/background.ts

@@ -21,7 +21,6 @@ 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";
@@ -39,7 +38,6 @@ import {
   attachRecordFinishListener,
   attachRecordQueryListener,
   attachRecordStepListener,
-  type RecordRuntimeDeps,
 } from "@/tools/record";
 import { detectBrowserMeta } from "@/transport/handshake";
 import type { Transport } from "@/transport/transport";
@@ -147,33 +145,10 @@ export default defineBackground(() => {
       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,
     approveBorrow: (ctx) =>
@@ -195,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,

apps/extension/src/entrypoints/content.ts

@@ -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)) {
-        activeRecordRequestId = message.requestId;
-        overlays.setAgentRecordRequest({
-          id: message.requestId,
-          ...(typeof message.startedAtMs === "number" ? { startedAtMs: message.startedAtMs } : {}),
-          onFinish: () => {
-            void chrome.runtime.sendMessage({
-              type: RECORD_FINISH,
-              requestId: message.requestId,
-            });
+      if (isRecordContentMessage(message)) {
+        const needsAsync = handleRecordContentMessage(
+          message,
+          {
+            activeRequestId: activeRecordRequestId,
+            capture: recordCapture,
+            setActiveRequestId: (id) => {
+              activeRecordRequestId = id;
+            },
+            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();
+            },
           },
-        });
-        renderAll();
-        (sendResponse as unknown as (response: RecordStartAck) => void)({ ok: true });
-        return false;
-      }
-
-      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;
+          sendResponse as unknown as
+            | ((response: RecordStartAck | RecordStopAck) => void)
+            | undefined,
+        );
+        return needsAsync;
       }
 
       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;
     });
   },

apps/extension/src/entrypoints/popup/App.test.tsx

@@ -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("已复制"));

apps/extension/src/entrypoints/record-frame.content.ts

@@ -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);
-  },
-});

apps/extension/src/lib/__tests__/connection-controller.test.ts

@@ -26,20 +26,20 @@ function handshake(
 }
 
 describe("computeConnectedState (protocol-based compat)", () => {
-  it("returns connected when daemon protocol equals extension protocol", () => {
-    expect(computeConnectedState(handshake("1.1", "1.0"), MIN_COMPATIBLE_PROTOCOL)).toEqual({
+  it("returns connected when protocol strings match", () => {
+    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"));
   });
 });

apps/extension/src/lib/__tests__/record-bridge.test.ts

@@ -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,
-    );
-  });
-});

apps/extension/src/lib/__tests__/record-frame-coordinator.test.ts

@@ -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();
-  });
-});

apps/extension/src/lib/__tests__/recording-document-marker.test.ts

@@ -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();
-  });
-});

apps/extension/src/lib/__tests__/recording-observation.test.ts

@@ -11,7 +11,7 @@ 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]',
+    rawVomText: '@vom 1\ntextbox "Password" value="••••••" [ref=e1]',
   });
   session.cursor.lastSettled = {
     stateId: state.id,
@@ -34,7 +34,7 @@ function sessionWithInput(redactValues = false): RecordingObservationSession {
   return session;
 }
 
-function finalizedFillTrace(value: string, redactValues: boolean) {
+function finalizedFillBody(value: string, redactValues: boolean): string {
   const session = sessionWithInput(redactValues);
   const draft: RecordingDraftStep = {
     op: "fill",
@@ -53,20 +53,15 @@ function finalizedFillTrace(value: string, redactValues: boolean) {
     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;
+  }).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);
+    const body = finalizedFillBody(secret, true);
+    expect(body).toContain("step 1: fill");
+    expect(body).not.toContain(secret);
   });
 
   it("keeps ordinary fill details", () => {
@@ -78,7 +73,7 @@ describe("record observation annotations", () => {
     const state = registry.register({
       url: "https://example.com/a\nb",
       title: "hello\nworld",
-      vomText: "@vom 1",
+      rawVomText: "@vom 1",
     });
     const trace = buildTraceV3({
       registry,
@@ -96,18 +91,18 @@ 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");
+    expect(first.register({ url: URL, rawVomText: "same" }).id).toBe("s1");
+    expect(first.register({ url: URL, rawVomText: "same" }).id).toBe("s1");
+    expect(second.register({ url: URL, rawVomText: "other" }).id).toBe("s1");
   });
 
   it("enriches metadata when a deduplicated observation becomes more complete", () => {
     const registry = new RecordingStateRegistry();
-    registry.register({ url: URL, vomText: "same" });
+    registry.register({ url: URL, rawVomText: "same" });
     const state = registry.register({
       url: URL,
       title: "Login",
-      vomText: "same",
+      rawVomText: "same",
       truncated: true,
     });
     expect(state).toMatchObject({ id: "s1", title: "Login", truncated: true });

apps/extension/src/lib/__tests__/recording-runtime.test.ts

@@ -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();
-  });
-});

apps/extension/src/lib/__tests__/step-buffer.test.ts

@@ -3,7 +3,7 @@ import { appendRecordedPayload, observeRecordedNavigation } from "../recording/s
 
 describe("recording-step-buffer", () => {
   it("stores semantic click without summary", () => {
-    const buffer = { steps: [], navigation: { pendingNavigation: false } };
+    const buffer = { steps: [], pendingNavigation: false };
     appendRecordedPayload(buffer, {
       op: "click",
       target: { tag: "button", role: "button", name: "发布" },
@@ -15,40 +15,7 @@ describe("recording-step-buffer", () => {
         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",
-          },
-        },
-      },
-    ]);
+    expect(buffer.pendingNavigation).toBe(true);
   });
 
   it("annotates navigated_to on action-caused navigation instead of wait_for_navigation", () => {
@@ -59,11 +26,9 @@ describe("recording-step-buffer", () => {
           captureTarget: { tag: "button", role: "button", name: "发布" },
         },
       ],
-      navigation: {
-        currentUrl: "https://example.com/a",
-        pendingNavigation: true,
-        pendingNavigationDeadline: Date.now() + 5_000,
-      },
+      currentUrl: "https://example.com/a",
+      pendingNavigation: true,
+      pendingNavigationDeadline: Date.now() + 5_000,
     };
     observeRecordedNavigation(buffer, "https://example.com/b", true);
     expect(buffer.steps).toEqual([
@@ -85,11 +50,9 @@ describe("recording-step-buffer", () => {
           values: ["tech"],
         },
       ],
-      navigation: {
-        currentUrl: "https://example.com/list",
-        pendingNavigation: true,
-        pendingNavigationDeadline: Date.now() + 5_000,
-      },
+      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([
@@ -105,60 +68,13 @@ describe("recording-step-buffer", () => {
   it("emits navigate for uncaused URL changes", () => {
     const buffer = {
       steps: [],
-      navigation: { currentUrl: "https://example.com/a", pendingNavigation: false },
+      currentUrl: "https://example.com/a",
+      pendingNavigation: false,
     };
-    const result = observeRecordedNavigation(buffer, "https://example.com/b", false);
-    expect(result).toEqual({ kind: "appended", index: 0 });
+    observeRecordedNavigation(buffer, "https://example.com/b", false);
     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" });
-  });
 });

apps/extension/src/lib/__tests__/tab-coordinator.test.ts

@@ -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");
-  });
-});

apps/extension/src/lib/__tests__/target-matcher.test.ts

@@ -69,23 +69,6 @@ describe("matchObservationTarget", () => {
     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(
@@ -98,21 +81,6 @@ describe("matchObservationTarget", () => {
     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(

apps/extension/src/lib/__tests__/trace-reducer-v2.test.ts

@@ -27,17 +27,6 @@ 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[] = [
       {
@@ -171,7 +160,7 @@ describe("reduceTraceSteps", () => {
     });
   });
 
-  it("drops hover steps, which only exist in trace v3", () => {
+  it("keeps hover steps before menu clicks", () => {
     const { steps } = reduceTraceSteps(
       [
         {
@@ -187,7 +176,12 @@ describe("reduceTraceSteps", () => {
       ],
       "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", () => {

apps/extension/src/lib/__tests__/trace-reducer-v3.test.ts

@@ -6,76 +6,6 @@ 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" },
@@ -106,7 +36,7 @@ describe("trace reducer v3", () => {
 
   it("builds the wire model from protocol constants", () => {
     const registry = new RecordingStateRegistry();
-    const state = registry.register({ url: "https://example.com", vomText: "@vom 1" });
+    const state = registry.register({ url: "https://example.com", rawVomText: "@vom 1" });
     const trace = buildTraceV3({
       registry,
       drafts: [

apps/extension/src/lib/record-bridge.ts

@@ -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 {
@@ -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 (
-    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;
-  }
+  if (m.type !== RECORD_STEP || typeof m.requestId !== "string") 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;
-}

apps/extension/src/lib/recording/document-marker.ts

@@ -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);
-    },
-  };
-}

apps/extension/src/lib/recording/frame-bridge.ts

@@ -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"
-  );
-}

apps/extension/src/lib/recording/frame-coordinator.ts

@@ -1,399 +0,0 @@
-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 = crypto.randomUUID();
-    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();

apps/extension/src/lib/recording/navigation-policy.ts

@@ -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));
-}

apps/extension/src/lib/recording/observation-capture.ts

@@ -1,5 +1,4 @@
 import type { RenderedRef } from "@browser-skill/vom";
-import type { CdpTarget } from "@/browser-driver/frame-graph";
 import {
   type CaptureVomMatchNode,
   type CaptureVomObservationResult,
@@ -29,11 +28,6 @@ export interface RegisteredObservation {
   url: string;
 }
 
-export interface RecordingDocumentScope {
-  frameId: string;
-  target: CdpTarget;
-}
-
 function nodeKey(frameId: string, backendNodeId: number): string {
   return `${frameId}:${backendNodeId}`;
 }
@@ -46,12 +40,8 @@ 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">>,
-  ) {
+  constructor(input: Pick<CaptureVomObservationResult, "rootFrameId" | "matchNodes" | "refs">) {
     const refByNode = new Map<string, RenderedRef>();
     for (const ref of input.refs) {
       const frameId = ref.frameId ?? input.rootFrameId;
@@ -61,16 +51,6 @@ export class ObservationNodeIndex {
       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 = {
@@ -96,10 +76,6 @@ export class ObservationNodeIndex {
   refs(frameId: string): readonly RenderedRef[] {
     return this.#refsByFrame.get(frameId) ?? [];
   }
-
-  documentScope(producerId: string): RecordingDocumentScope | undefined {
-    return this.#scopeByProducer.get(producerId) ?? undefined;
-  }
 }
 
 async function readTabMeta(

apps/extension/src/lib/recording/observation-session.ts

@@ -28,13 +28,7 @@ function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
 }
 
 function isTargeted(draft: RecordingDraftStep): draft is TargetedRecordingDraft {
-  return (
-    draft.op === "click" ||
-    draft.op === "hover" ||
-    draft.op === "fill" ||
-    draft.op === "press" ||
-    draft.op === "select"
-  );
+  return draft.op !== "navigate" && draft.op !== "scroll";
 }
 
 export class RecordingObservationSession {
@@ -80,7 +74,7 @@ export class RecordingObservationSession {
     const state = this.registry.register({
       url: captured.url,
       title: captured.title,
-      vomText: captured.vomText,
+      rawVomText: captured.vomText,
       truncated: captured.truncated,
     });
     const observation: RegisteredObservation = {

apps/extension/src/lib/recording/recording-runtime.ts

@@ -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,
-    });
-  }
-}

apps/extension/src/lib/recording/settle-controller.ts

@@ -212,7 +212,6 @@ export class SettleController {
       url: finalUrl,
       pageUrl: finalUrl,
       cause: "browser",
-      transitionQualifiers: ["server_redirect"],
       preStateId: this.#session.cursor.lastSettled?.stateId,
     };
     drafts.push(draft);

apps/extension/src/lib/recording/state-registry.ts

@@ -2,8 +2,7 @@ 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;
+  rawVomText: string;
   truncated: boolean;
   stepsHere: number[];
 }
@@ -20,10 +19,10 @@ export class RecordingStateRegistry {
   register(input: {
     url: string;
     title?: string;
-    vomText: string;
+    rawVomText: string;
     truncated?: boolean;
   }): RecordedStateEntry {
-    const identity = stateIdentity(input.url, input.vomText);
+    const identity = stateIdentity(input.url, input.rawVomText);
     const existingId = this.#idByIdentity.get(identity);
     if (existingId) {
       const existing = this.#entriesById.get(existingId)!;
@@ -36,7 +35,7 @@ export class RecordingStateRegistry {
       id: `s${this.#nextId}`,
       url: input.url,
       ...(input.title ? { title: input.title } : {}),
-      vomText: input.vomText,
+      rawVomText: input.rawVomText,
       truncated: input.truncated ?? false,
       stepsHere: [],
     };

apps/extension/src/lib/recording/step-buffer.ts

@@ -1,13 +1,8 @@
 import type { RecordStepPayload } from "../record-bridge";
-import { hasRedirectQualifier } from "./navigation-policy";
-import type { RecordingDraftStep, TargetMatchHint } from "./types";
+import type { RecordingDraftStep } from "./types";
 
 export interface RecordingStepBuffer {
   steps: RecordingDraftStep[];
-  navigation: RecordingNavigationCursor;
-}
-
-export interface RecordingNavigationCursor {
   currentUrl?: string;
   pendingNavigation: boolean;
   pendingNavigationDeadline?: number;
@@ -15,29 +10,33 @@ export interface RecordingNavigationCursor {
 
 const NAVIGATION_TRIGGER_WINDOW_MS = 3_000;
 
-function toDraftStep(
-  payload: RecordStepPayload,
-  targetHint?: TargetMatchHint,
-): RecordingDraftStep | null {
+function toDraftStep(payload: RecordStepPayload): 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;
+      return payload.target
+        ? {
+            op: "click",
+            captureTarget: payload.target,
+            ...(pageUrl ? { pageUrl } : {}),
+          }
+        : null;
     case "hover":
-      return payload.target ? { op: "hover", captureTarget: payload.target, ...common } : null;
+      return payload.target
+        ? {
+            op: "hover",
+            captureTarget: payload.target,
+            ...(pageUrl ? { pageUrl } : {}),
+          }
+        : null;
     case "fill":
       return payload.target
         ? {
             op: "fill",
             captureTarget: payload.target,
             value: payload.value ?? "",
-            ...(payload.commit ? { commit: payload.commit } : {}),
             ...(payload.redacted ? { redacted: true } : {}),
-            ...common,
+            ...(pageUrl ? { pageUrl } : {}),
           }
         : null;
     case "press":
@@ -47,7 +46,7 @@ function toDraftStep(
             key: payload.key,
             ...(payload.target ? { captureTarget: payload.target } : {}),
             ...(payload.modifiers?.length ? { modifiers: payload.modifiers } : {}),
-            ...common,
+            ...(pageUrl ? { pageUrl } : {}),
           }
         : null;
     case "select":
@@ -57,7 +56,7 @@ function toDraftStep(
             captureTarget: payload.target,
             values: payload.values,
             ...(payload.labels?.length ? { labels: payload.labels } : {}),
-            ...common,
+            ...(pageUrl ? { pageUrl } : {}),
           }
         : null;
     case "navigate":
@@ -65,91 +64,73 @@ function toDraftStep(
   }
 }
 
-function annotateLastStepNavigation(buffer: RecordingStepBuffer, url: string): number {
-  for (let index = buffer.steps.length - 1; index >= 0; index -= 1) {
-    const step = buffer.steps[index];
+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" || step.op === "fill") {
-      step.navigatedTo = url;
-      return index;
+    if (step.op === "click" || step.op === "press" || step.op === "select") {
+      buffer.steps[i] = { ...step, navigatedTo: url };
+      return true;
     }
     break;
   }
-  return -1;
+  return false;
 }
 
-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;
-
+): void {
+  if (!url || url === buffer.currentUrl) return;
+  buffer.currentUrl = url;
   const pendingIsCurrent =
-    navigation.pendingNavigation &&
-    (navigation.pendingNavigationDeadline === undefined ||
-      navigation.pendingNavigationDeadline >= Date.now());
+    buffer.pendingNavigation &&
+    (buffer.pendingNavigationDeadline === undefined ||
+      buffer.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;
+    buffer.pendingNavigation = false;
+    buffer.pendingNavigationDeadline = undefined;
+    if (!annotateLastStepNavigation(buffer, url)) {
+      buffer.steps.push({
+        op: "navigate",
+        url,
+        pageUrl: url,
+      });
+    }
+    return;
   }
 
-  if (hasRedirectQualifier(transitionQualifiers)) {
-    return { kind: "coalesce_redirect", url };
-  }
+  buffer.pendingNavigation = false;
+  buffer.pendingNavigationDeadline = undefined;
   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 {
+): void {
   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;
+    if (payload.url) {
+      observeRecordedNavigation(buffer, payload.url, payload.navigation_caused_by_action);
+    }
+    return;
   }
-  const step = toDraftStep(
-    { ...payload, page_url: payload.page_url ?? buffer.navigation.currentUrl },
-    targetHint,
-  );
-  if (!step) return null;
+  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.navigation.pendingNavigation = payload.expects_navigation === true;
-    buffer.navigation.pendingNavigationDeadline = buffer.navigation.pendingNavigation
+    buffer.pendingNavigation = payload.expects_navigation === true;
+    buffer.pendingNavigationDeadline = buffer.pendingNavigation
       ? Date.now() + NAVIGATION_TRIGGER_WINDOW_MS
       : undefined;
   }
-  return buffer.steps.length - 1;
 }

apps/extension/src/lib/recording/tab-coordinator.ts

@@ -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;
-  }
-}

apps/extension/src/lib/recording/target-matcher.ts

@@ -14,13 +14,8 @@ function rectMatches(a: TargetGeometry["rect"], b: TargetGeometry["rect"]): bool
   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);
+function candidateMatches(candidate: IndexedObservationNode, geometry: TargetGeometry): boolean {
+  return candidate.geometry.rect !== null && rectMatches(geometry.rect, candidate.geometry.rect);
 }
 
 export function unmatchedTarget(fallback?: CaptureTargetDescriptor): TargetDescriptorV3 {
@@ -58,17 +53,12 @@ export function matchObservationTarget(input: {
   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"),
-      );
+      .filter((candidate) => candidate.ref && candidateMatches(candidate, geometry));
     if (matches.length === 1) return descriptor(matches[0]!.ref!);
     const semanticMatches = matches.filter(
       (candidate) => candidate.ref && matchesSemantics(candidate.ref, input.fallback),

apps/extension/src/lib/recording/trace-builder-v3.ts

@@ -39,13 +39,8 @@ export function buildTraceV3(input: {
   startUrl?: string;
   stoppedBy: StopReason;
   bskVersion: string;
-  redactValues?: boolean;
-  includeTabSwitches?: boolean;
 }): TraceV3 {
-  const reduced = reduceTraceStepsV3(input.drafts, {
-    includeTabSwitches: input.includeTabSwitches,
-    redactValues: input.redactValues,
-  });
+  const reduced = reduceTraceStepsV3(input.drafts);
   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[]>();
@@ -70,7 +65,7 @@ export function buildTraceV3(input: {
         url: entry.url,
         title: entry.title,
         stepIds: remapDraftIds(entry.stepsHere, reduced.stepIdByDraftId),
-        vomText: entry.vomText,
+        vomText: entry.rawVomText,
         annotations: annotationsByState.get(entry.id) ?? [],
         stepIdByDraftId: reduced.stepIdByDraftId,
       }),

apps/extension/src/lib/recording/trace-reducer-v2.ts

@@ -119,6 +119,14 @@ function toV2Step(
         },
         effectForNavigation(step.navigatedTo, urlToId),
       );
+    case "hover":
+      if (!step.captureTarget) return null;
+      return {
+        op: "hover",
+        id,
+        page,
+        target: step.captureTarget,
+      };
     case "fill":
       if (!step.captureTarget) return null;
       return {
@@ -153,11 +161,7 @@ function toV2Step(
         },
         effectForNavigation(step.navigatedTo, 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;
   }
 }

apps/extension/src/lib/recording/trace-reducer-v3.ts

@@ -1,6 +1,5 @@
 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";
 
@@ -9,6 +8,7 @@ interface CollapsedDraft {
   draftIds: number[];
 }
 
+const REDIRECT_QUALIFIERS = new Set(["client_redirect", "server_redirect"]);
 const TRANSITION_CAUSES: Record<string, NavigationCause> = {
   typed: "user_typed",
   generated: "user_typed",
@@ -22,7 +22,7 @@ const TRANSITION_CAUSES: Record<string, NavigationCause> = {
 };
 
 function isRedirect(step: Extract<RecordingDraftStep, { op: "navigate" }>): boolean {
-  return hasRedirectQualifier(step.transitionQualifiers);
+  return (step.transitionQualifiers ?? []).some((qualifier) => REDIRECT_QUALIFIERS.has(qualifier));
 }
 
 function collapseRedirects(steps: RecordingDraftStep[]): CollapsedDraft[] {
@@ -58,26 +58,8 @@ function selection(values: string[], labels?: string[]): Array<{ value: string;
   }));
 }
 
-interface ReduceDraftOptions {
-  includeTabSwitches: boolean;
-  redactValues: boolean;
-}
-
-function reduceDraft(
-  draft: RecordingDraftStep,
-  id: number,
-  options: ReduceDraftOptions,
-): StepV3 | null {
+function reduceDraft(draft: RecordingDraftStep, id: number): 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;
@@ -99,14 +81,13 @@ function reduceDraft(
         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,
+        value: draft.value,
         commit: draft.commit ?? "blur",
-        ...(fillIsRedacted ? { redacted: true } : {}),
+        ...(draft.redacted ? { redacted: true } : {}),
       };
     case "press":
       return {
@@ -123,7 +104,7 @@ function reduceDraft(
         op: "select",
         ...common,
         target: draft.matchedTarget ?? unmatchedTarget(draft.captureTarget),
-        ...(!options.redactValues ? { selection: selection(draft.values, draft.labels) } : {}),
+        selection: selection(draft.values, draft.labels),
       };
     case "scroll":
       return { op: "scroll", ...common };
@@ -135,17 +116,11 @@ export interface ReducedTraceV3 {
   stepIdByDraftId: Map<number, number>;
 }
 
-export function reduceTraceStepsV3(
-  steps: RecordingDraftStep[],
-  options: { includeTabSwitches?: boolean; redactValues?: boolean } = {},
-): ReducedTraceV3 {
+export function reduceTraceStepsV3(steps: RecordingDraftStep[]): 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,
-    });
+    const step = reduceDraft(draft, output.length + 1);
     if (!step) continue;
     output.push(step);
     for (const draftId of draftIds) stepIdByDraftId.set(draftId, step.id);

apps/extension/src/lib/recording/types.ts

@@ -15,9 +15,8 @@ export interface TargetGeometry {
 
 export interface TargetMatchHint {
   geometry?: TargetGeometry;
-  /** Missing means top frame; null means the source Document could not be resolved. */
-  frameId?: string | null;
-  geometrySpace?: "top" | "local";
+  /** Missing means the current top frame, never an unrestricted frame search. */
+  frameId?: string;
 }
 
 export interface StepAnnotation {
@@ -70,7 +69,6 @@ export type RecordingDraftStep =
       DraftTarget &
       DraftNavigationEffect)
   | ({ op: "scroll" } & DraftStateLink)
-  | ({ op: "switch_tab" } & DraftStateLink)
   | ({
       op: "navigate";
       url: string;

apps/extension/src/shared/recording-document-identity.ts

@@ -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;
-}

apps/extension/src/tools/__tests__/dispatcher.test.ts

@@ -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,72 +44,9 @@ function makeRequest(method: string, params: unknown): RequestFrame {
 
 describe("ToolDispatcher", () => {
   afterEach(() => {
-    resetBrowserObservationForTests();
     vi.unstubAllGlobals();
   });
 
-  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 () => {}),
-      },
-    });
-    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({

apps/extension/src/tools/dispatcher.ts

@@ -51,12 +51,7 @@ import {
   handleScreenshot,
   handleSnapshot,
 } from "./observation";
-import {
-  handleRecordAwait,
-  handleRecordStart,
-  handleRecordStop,
-  type RecordRuntimeDeps,
-} from "./record";
+import { handleRecordAwait, handleRecordStart, handleRecordStop } from "./record";
 import {
   handleSessionStart,
   handleSessionStop,
@@ -104,7 +99,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
@@ -140,7 +134,6 @@ 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 approveBorrow?: BorrowConfirmationApprover;
@@ -160,7 +153,6 @@ 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.approveBorrow = deps.approveBorrow;
@@ -539,26 +531,44 @@ export class ToolDispatcher {
           signal,
         });
       case "tool.record_start":
-        return this.recording
-          ? handleRecordStart(this.sessions, req.params as RecordStartParams, {
-              ...this.recording,
-              signal,
-            })
-          : recordingRuntimeUnavailable();
+        return handleRecordStart(this.sessions, req.params as RecordStartParams, {
+          tabsApi: chromeTabsApi,
+          sendToTab: (tabId, msg) => chrome.tabs.sendMessage(tabId, msg),
+          bypassOverlay: async (tabId, enabled) => {
+            try {
+              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
-          ? handleRecordStop(this.sessions, req.params as RecordStopParams, {
-              ...this.recording,
-              signal,
-            })
-          : recordingRuntimeUnavailable();
+        return handleRecordStop(this.sessions, req.params as RecordStopParams, {
+          tabsApi: chromeTabsApi,
+          sendToTab: (tabId, msg) => chrome.tabs.sendMessage(tabId, msg),
+          bypassOverlay: async (tabId, enabled) => {
+            try {
+              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
-          ? handleRecordAwait(this.sessions, req.params as RecordAwaitParams, {
-              ...this.recording,
-              signal,
-            })
-          : recordingRuntimeUnavailable();
+        return handleRecordAwait(this.sessions, req.params as RecordAwaitParams, {
+          tabsApi: chromeTabsApi,
+          sendToTab: (tabId, msg) => chrome.tabs.sendMessage(tabId, msg),
+          signal,
+        });
       default:
         return {
           code: "unknown_method",
@@ -694,13 +704,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":

apps/extension/src/tools/record.ts

@@ -15,37 +15,22 @@ import {
   type RecordQueryResponse,
   type RecordStartAck,
   type RecordStartMessage,
-  type RecordStepAck,
   type RecordStopMessage,
 } from "@/lib/record-bridge";
-import {
-  type RecordFrameCoordinator,
-  type RecordingCaptureScope,
-  recordFrameCoordinator,
-} from "@/lib/recording/frame-coordinator";
-import { RecordingObservationRuntime } from "@/lib/recording/recording-runtime";
-import {
-  appendRecordedPayload,
-  observeRecordedNavigation,
-  type RecordingStepBuffer,
-} from "@/lib/recording/step-buffer";
-import { RecordingTabCoordinator, type TabActivation } from "@/lib/recording/tab-coordinator";
+import { appendRecordedPayload, observeRecordedNavigation } from "@/lib/recording/step-buffer";
 import { buildTraceV2 } from "@/lib/recording/trace-reducer-v2";
 import type { RecordingDraftStep } from "@/lib/recording/types";
 import type { SessionManager } from "@/session-manager/manager";
-import { EXTENSION_VERSION } from "@/transport/handshake";
 import type {
   RecordAwaitParams,
   RecordAwaitResult,
-  RecordedTrace,
   RecordStartParams,
   RecordStartResult,
   RecordStopParams,
   RecordStopResult,
   RpcError,
-  StopReason,
+  TraceV2,
 } from "@/transport/types";
-import { TRACE_VERSION_V3 } from "@/transport/types";
 import { handleNavigate } from "./navigation";
 import {
   type CdpRunner,
@@ -58,46 +43,21 @@ import {
 
 interface ActiveRecording {
   requestId: string;
-  tabs: RecordingTabCoordinator;
+  tabId: number;
   agentWindowId: number;
   startUrl?: string;
   purpose?: string;
   steps: RecordingDraftStep[];
   startedAt: string;
   startedAtMs: number;
-  traceVersion: 2 | 3;
-  supportsTabSwitchSteps: boolean;
-  finishPromise: Promise<RecordedTrace>;
-  resolveFinish: (trace: RecordedTrace) => void;
+  finishPromise: Promise<TraceV2>;
+  resolveFinish: (trace: TraceV2) => void;
   rejectFinish: (err: Error) => void;
   settled: boolean;
-  finishAttempt: Promise<RecordedTrace | null> | null;
-  observation: RecordingObservationRuntime | null;
-  stoppedBy: StopReason;
-  /** Navigation callbacks tracked from event receipt through action enqueue. */
-  navigationCallbacks: Set<Promise<void>>;
-  /** Synchronous intake gate closed only after finish drains to stability. */
-  acceptingNavigation: boolean;
-  /**
-   * Serializes step appends with navigation observation so a click is always
-   * in `steps` before a same-turn `webNavigation` tries to annotate it.
-   */
-  actionQueue: Promise<void>;
-  /** Last accepted sequence for each content-script document producer. */
-  lastStepSequenceByProducer: Map<string, number>;
-}
-
-function enqueueRecordingAction(
-  recording: ActiveRecording,
-  task: () => Promise<void>,
-): Promise<void> {
-  const queued = recording.actionQueue.then(task, task);
-  recording.actionQueue = queued.catch(() => {});
-  return queued;
-}
-
-function isRecordingFinishing(recording: ActiveRecording): boolean {
-  return recording.settled || recording.finishAttempt !== null;
+  finishing: boolean;
+  currentUrl?: string;
+  pendingNavigation: boolean;
+  pendingNavigationDeadline?: number;
 }
 
 const recordings = new Map<string, ActiveRecording>();
@@ -118,9 +78,6 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-/** Recording producer version mirrored into trace.recorder.bsk. */
-export const BSK_TRACE_VERSION = EXTENSION_VERSION;
-
 /** Injectable http(s) landing page when `tool.record_start` omits `url`. */
 export const RECORD_DEFAULT_START_URL = "https://example.com/";
 
@@ -180,11 +137,9 @@ async function sendRecordStartWithAck(
   tabId: number,
   msg: RecordStartMessage,
   sendToTab: RecordDeps["sendToTab"],
-  cancelled?: () => boolean,
 ): Promise<void> {
   let lastError: unknown;
   for (let attempt = 0; attempt < RECORD_START_RETRIES; attempt += 1) {
-    if (cancelled?.()) throw new Error("record start cancelled");
     try {
       const response = await sendToTab(tabId, msg);
       if (isRecordStartAck(response)) return;
@@ -192,7 +147,6 @@ async function sendRecordStartWithAck(
     } catch (err) {
       lastError = err;
     }
-    if (cancelled?.()) throw new Error("record start cancelled");
     if (attempt + 1 < RECORD_START_RETRIES) {
       await sleep(RECORD_START_RETRY_DELAY_MS);
     }
@@ -200,30 +154,7 @@ async function sendRecordStartWithAck(
   throw lastError ?? new Error("failed to start recording in content script");
 }
 
-function negotiatedTraceVersion(params: RecordStartParams): 2 | 3 | RpcError {
-  if (params.trace_version === undefined) return 2;
-  if (params.trace_version === TRACE_VERSION_V3) return 3;
-  return {
-    code: "invalid_params",
-    message: `unsupported trace_version ${params.trace_version}; supported values are omitted (v2) or ${TRACE_VERSION_V3} (v3)`,
-  };
-}
-
-function buildTrace(recording: ActiveRecording): RecordedTrace {
-  if (recording.traceVersion === 3 && recording.observation) {
-    return recording.observation.buildTrace({
-      drafts: recording.steps,
-      startedAt: recording.startedAt,
-      purpose: recording.purpose,
-      startUrl: recording.startUrl,
-      stoppedBy: recording.stoppedBy,
-      bskVersion: BSK_TRACE_VERSION,
-      includeTabSwitches: recording.supportsTabSwitchSteps,
-    });
-  }
-  if (recording.traceVersion === 3) {
-    throw new Error("trace v3 observation runtime is unavailable");
-  }
+function buildTrace(recording: ActiveRecording): TraceV2 {
   return buildTraceV2({
     steps: recording.steps,
     startedAt: recording.startedAt,
@@ -232,51 +163,6 @@ function buildTrace(recording: ActiveRecording): RecordedTrace {
   });
 }
 
-function stepBufferFor(
-  recording: ActiveRecording,
-  tabId: number,
-  fallbackUrl?: string,
-): RecordingStepBuffer {
-  return {
-    steps: recording.steps,
-    navigation: recording.tabs.navigation(tabId, fallbackUrl),
-  };
-}
-
-async function activateRecordingTab(
-  recording: ActiveRecording,
-  targetTabId: number,
-): Promise<void> {
-  const previousTabId = recording.tabs.currentTabId;
-  if (targetTabId === previousTabId) return;
-
-  const transition = recording.observation
-    ? await recording.observation.captureTabTransition(previousTabId, targetTabId)
-    : {};
-  const { targetUrl, ...stateLinks } = transition;
-  const draft: Extract<RecordingDraftStep, { op: "switch_tab" }> = {
-    op: "switch_tab",
-    ...stateLinks,
-  };
-  recording.steps.push(draft);
-  recording.observation?.bindTabTransition(draft, recording.steps.length);
-  recording.tabs.commit(targetTabId, targetUrl);
-}
-
-async function processRecordedStep(
-  recording: ActiveRecording,
-  draftIndex: number,
-  tabId: number,
-  producerId?: string,
-): Promise<void> {
-  if (!recording.observation) return;
-  try {
-    await recording.observation.processDraft(tabId, recording.steps, draftIndex, producerId);
-  } catch (err) {
-    console.warn(`[bsk record] observation failed for step ${draftIndex + 1}`, err);
-  }
-}
-
 export interface RecordDeps {
   tabsApi: ChromeTabsApi;
   sendToTab(
@@ -284,25 +170,16 @@ export interface RecordDeps {
     msg: RecordStartMessage | RecordStopMessage | RecordCancelMessage,
   ): Promise<unknown>;
   bypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
-  frameCoordinator?: Pick<
-    RecordFrameCoordinator,
-    "begin" | "armTab" | "sourceFor" | "stop" | "cancel"
-  >;
   cdp?: CdpRunner;
   signal?: AbortSignal;
 }
 
-export type RecordRuntimeDeps = Omit<RecordDeps, "frameCoordinator" | "signal"> & {
-  frameCoordinator: NonNullable<RecordDeps["frameCoordinator"]>;
-};
-
 let defaultDeps: RecordDeps | null = null;
 function getDefaultDeps(): RecordDeps {
   if (!defaultDeps) {
     defaultDeps = {
       tabsApi: chromeTabsApi,
       sendToTab: (tabId, msg) => chrome.tabs.sendMessage(tabId, msg),
-      frameCoordinator: recordFrameCoordinator,
     };
   }
   return defaultDeps;
@@ -360,58 +237,16 @@ export function releaseBrowserObservationListenersIfIdle(): void {
   detachBrowserObservation = null;
 }
 
-export function attachRecordStepListener(deps: RecordDeps = getDefaultDeps()): () => void {
+export function attachRecordStepListener(): () => void {
   const listener = (
     message: unknown,
-    sender: chrome.runtime.MessageSender,
-    sendResponse: (response: RecordStepAck) => void,
+    _sender: chrome.runtime.MessageSender,
+    _sendResponse: () => void,
   ) => {
     if (!isRecordStepMessage(message)) return false;
     for (const recording of recordings.values()) {
       if (recording.requestId !== message.requestId) continue;
-      const source: RecordingCaptureScope | null | undefined = deps.frameCoordinator
-        ? deps.frameCoordinator.sourceFor(message.requestId, message.producerId, sender)
-        : undefined;
-      if (deps.frameCoordinator && !source) return false;
-      const sourceTabId = source?.tabId ?? sender.tab?.id ?? recording.tabs.currentTabId;
-      const sourceWasActive = sender.tab?.active ?? sourceTabId === recording.tabs.activeTabId;
-      const producerKey = source
-        ? `${source.tabId}:${source.documentId}:${source.producerId}`
-        : `${sourceTabId}:${message.producerId}`;
-      const expectedSequence = (recording.lastStepSequenceByProducer.get(producerKey) ?? 0) + 1;
-      if (message.sequence < expectedSequence) {
-        sendResponse({ ok: true, sequence: message.sequence });
-        return false;
-      }
-      if (message.sequence > expectedSequence) {
-        sendResponse({
-          ok: false,
-          expectedSequence,
-          error: `out-of-order recorded step ${message.sequence}`,
-        });
-        return false;
-      }
-
-      recording.lastStepSequenceByProducer.set(producerKey, message.sequence);
-      enqueueRecordingAction(recording, async () => {
-        if (sourceTabId !== recording.tabs.currentTabId) {
-          if (!sourceWasActive) return;
-          if (sourceTabId !== recording.tabs.activeTabId)
-            recording.tabs.noteActivation(sourceTabId);
-          await activateRecordingTab(recording, sourceTabId);
-        }
-        await recording.observation?.flushRedirects(sourceTabId);
-        const targetHint = message.step.geometry ? { geometry: message.step.geometry } : undefined;
-        const draftIndex = appendRecordedPayload(
-          stepBufferFor(recording, sourceTabId, message.step.page_url),
-          message.step,
-          targetHint,
-        );
-        if (draftIndex !== null) {
-          await processRecordedStep(recording, draftIndex, sourceTabId, source?.producerId);
-        }
-      });
-      sendResponse({ ok: true, sequence: message.sequence });
+      appendRecordedPayload(recording, message.step);
       return false;
     }
     return false;
@@ -438,7 +273,7 @@ export function attachRecordFinishListener(deps: RecordDeps = getDefaultDeps()):
 
 function findRecordingByTabId(tabId: number): ActiveRecording | null {
   for (const recording of recordings.values()) {
-    if (recording.tabs.currentTabId === tabId && !recording.settled) return recording;
+    if (recording.tabId === tabId && !recording.settled) return recording;
   }
   return null;
 }
@@ -475,7 +310,7 @@ async function clearRearmTimersForRecording(
   recording: ActiveRecording,
   deps: RecordDeps,
 ): Promise<void> {
-  clearRearmTimer(recording.tabs.currentTabId);
+  clearRearmTimer(recording.tabId);
   try {
     const tabs = await deps.tabsApi.query({ windowId: recording.agentWindowId });
     for (const tab of tabs) {
@@ -490,16 +325,13 @@ async function stopRecordingOnAllAgentTabs(
   recording: ActiveRecording,
   deps: RecordDeps,
 ): Promise<void> {
-  if (deps.frameCoordinator && !(await deps.frameCoordinator.stop(recording.requestId))) {
-    throw new Error("failed to flush one or more recording documents");
-  }
   const stopMsg: RecordStopMessage = { type: RECORD_STOP, requestId: recording.requestId };
-  let tabIds = [recording.tabs.currentTabId];
+  let tabIds = [recording.tabId];
   try {
     const tabs = await deps.tabsApi.query({ windowId: recording.agentWindowId });
     tabIds = [
       ...new Set([
-        recording.tabs.currentTabId,
+        recording.tabId,
         ...tabs.flatMap((tab) => (typeof tab.id === "number" ? [tab.id] : [])),
       ]),
     ];
@@ -510,11 +342,11 @@ async function stopRecordingOnAllAgentTabs(
   for (const tabId of tabIds) {
     try {
       const response = await deps.sendToTab(tabId, stopMsg);
-      if (tabId === recording.tabs.currentTabId && !isRecordStartAck(response)) {
+      if (tabId === recording.tabId && !isRecordStartAck(response)) {
         throw new Error("content script did not confirm recorded steps");
       }
     } catch {
-      if (tabId === recording.tabs.currentTabId) {
+      if (tabId === recording.tabId) {
         throw new Error("failed to flush recorded steps");
       }
     }
@@ -532,39 +364,22 @@ async function rearmRecording(
   recording: ActiveRecording,
   targetTabId: number,
   deps: RecordDeps,
-  activation?: TabActivation,
 ): Promise<boolean> {
   // Do NOT toggle automation-bypass here: each retry used to increment the
   // content-script counter, and a single stop decrement left the ControlOverlay
   // stuck with pointer-events:none (page usable, Interrupt dead). RecordOverlay
   // already hides the control chrome while activeRecord is set.
-  const isFinishing = () => isRecordingFinishing(recording);
   for (let attempt = 0; attempt < RECORD_REARM_MAX_ATTEMPTS; attempt += 1) {
-    if (isFinishing()) return false;
     const startMsg: RecordStartMessage = {
       type: RECORD_START,
       requestId: recording.requestId,
       startedAtMs: recording.startedAtMs,
     };
     try {
-      if (deps.frameCoordinator) {
-        const frameStarted = await deps.frameCoordinator.armTab(recording.requestId, targetTabId);
-        if (!frameStarted) throw new Error("recording document did not start");
-      }
-      await sendRecordStartWithAck(targetTabId, startMsg, deps.sendToTab, isFinishing);
-      if (isFinishing()) return false;
-      if (activation) {
-        if (!recording.tabs.isLatest(activation)) return true;
-        await enqueueRecordingAction(recording, async () => {
-          if (isFinishing() || !recording.tabs.isLatest(activation)) {
-            return;
-          }
-          await activateRecordingTab(recording, targetTabId);
-        });
-      }
+      await sendRecordStartWithAck(targetTabId, startMsg, deps.sendToTab);
+      recording.tabId = targetTabId;
       return true;
     } catch {
-      if (isFinishing()) return false;
       if (attempt + 1 < RECORD_REARM_MAX_ATTEMPTS) {
         await sleep(RECORD_REARM_RETRY_DELAY_MS);
       }
@@ -573,7 +388,7 @@ async function rearmRecording(
   return false;
 }
 
-function scheduleRearmForTab(tabId: number, deps: RecordDeps, activation?: TabActivation): void {
+function scheduleRearmForTab(tabId: number, deps: RecordDeps): void {
   const existing = rearmTimers.get(tabId);
   if (existing) clearTimeout(existing);
   rearmTimers.set(
@@ -582,7 +397,7 @@ function scheduleRearmForTab(tabId: number, deps: RecordDeps, activation?: TabAc
       rearmTimers.delete(tabId);
       void (async () => {
         const current = await findRecordingForTab(tabId, deps);
-        if (current) await rearmRecording(current, tabId, deps, activation);
+        if (current) await rearmRecording(current, tabId, deps);
       })();
     }, RECORD_REARM_DEBOUNCE_MS),
   );
@@ -594,20 +409,14 @@ export function attachRecordTabListener(deps: RecordDeps = getDefaultDeps()): ()
     const windowId = tab.windowId;
     if (tabId === undefined || windowId === undefined) return;
     for (const recording of recordings.values()) {
-      if (isRecordingFinishing(recording) || recording.agentWindowId !== windowId) continue;
+      if (recording.settled || recording.agentWindowId !== windowId) continue;
       scheduleRearmForTab(tabId, deps);
       return;
     }
   };
 
   const onActivated = (activeInfo: chrome.tabs.TabActiveInfo) => {
-    for (const recording of recordings.values()) {
-      if (isRecordingFinishing(recording) || recording.agentWindowId !== activeInfo.windowId)
-        continue;
-      const activation = recording.tabs.noteActivation(activeInfo.tabId);
-      scheduleRearmForTab(activeInfo.tabId, deps, activation);
-      return;
-    }
+    scheduleRearmForTab(activeInfo.tabId, deps);
   };
 
   chrome.tabs.onCreated.addListener(onCreated);
@@ -619,47 +428,13 @@ export function attachRecordTabListener(deps: RecordDeps = getDefaultDeps()): ()
 }
 
 export function attachRecordNavigationListener(deps: RecordDeps = getDefaultDeps()): () => void {
-  const observeMainFrame = (
-    tabId: number,
-    url?: string,
-    causedByAction?: boolean,
-    transitionType?: string,
-    transitionQualifiers?: string[],
-  ) => {
-    if (!url) return;
-    const candidates = [...recordings.values()].filter(
-      (recording) =>
-        !recording.settled && recording.acceptingNavigation && recording.tabs.activeTabId === tabId,
-    );
-    for (const recording of candidates) {
-      const queued = enqueueRecordingAction(recording, async () => {
-        if (tabId !== recording.tabs.currentTabId) {
-          await activateRecordingTab(recording, tabId);
-        }
-        const result = observeRecordedNavigation(
-          stepBufferFor(recording, tabId, url),
-          url,
-          causedByAction,
-          transitionType,
-          transitionQualifiers,
-        );
-        if (result.kind === "coalesce_redirect") {
-          recording.observation?.scheduleRedirect(tabId, recording.steps, result.url);
-          return;
-        }
-
-        if (result.kind === "noop") return;
-        recording.observation?.clearRedirect(tabId);
-        if (result.kind === "appended") {
-          await processRecordedStep(recording, result.index, tabId);
-        } else {
-          recording.observation?.scheduleSettle(tabId, recording.steps, result.index);
-        }
-      });
-      const tracked = queued.catch(() => {});
-      recording.navigationCallbacks.add(tracked);
-      void tracked.finally(() => recording.navigationCallbacks.delete(tracked));
-    }
+  const observeMainFrame = (tabId: number, url?: string, causedByAction?: boolean) => {
+    void (async () => {
+      const recording = await findRecordingForTab(tabId, deps);
+      if (recording && url) {
+        observeRecordedNavigation(recording, url, causedByAction);
+      }
+    })();
   };
   const onMainFrameComplete = (tabId: number, url?: string) => {
     void (async () => {
@@ -679,13 +454,18 @@ export function attachRecordNavigationListener(deps: RecordDeps = getDefaultDeps
       details: chrome.webNavigation.WebNavigationTransitionCallbackDetails,
     ) => {
       if (details.frameId !== 0) return;
-      observeMainFrame(
-        details.tabId,
-        details.url,
-        undefined,
-        details.transitionType,
-        details.transitionQualifiers,
-      );
+      const causedByAction =
+        details.transitionType === "link" || details.transitionType === "form_submit"
+          ? true
+          : details.transitionType === "typed" ||
+              details.transitionType === "auto_bookmark" ||
+              details.transitionType === "generated" ||
+              details.transitionType === "keyword" ||
+              details.transitionType === "keyword_generated" ||
+              details.transitionType === "reload"
+            ? false
+            : undefined;
+      observeMainFrame(details.tabId, details.url, causedByAction);
     };
     chrome.webNavigation.onCompleted.addListener(completedListener);
     chrome.webNavigation.onCommitted?.addListener(committedListener);
@@ -703,26 +483,6 @@ export function attachRecordNavigationListener(deps: RecordDeps = getDefaultDeps
   return () => chrome.tabs.onUpdated.removeListener(listener);
 }
 
-const MAX_FINISH_DRAIN_ROUNDS = 10;
-
-async function drainRecordingToStability(recording: ActiveRecording): Promise<boolean> {
-  for (let round = 0; round < MAX_FINISH_DRAIN_ROUNDS; round += 1) {
-    await Promise.all([...recording.navigationCallbacks]);
-    const actionTail = recording.actionQueue;
-    await actionTail;
-    await recording.observation?.flush();
-
-    if (recording.navigationCallbacks.size === 0 && recording.actionQueue === actionTail) {
-      // No event or promise continuation can interleave with this synchronous
-      // check-and-close, so work accepted before the cutoff is fully drained.
-      recording.acceptingNavigation = false;
-      return true;
-    }
-  }
-  console.warn("[bsk record] navigation/action queues did not stabilize at stop");
-  return false;
-}
-
 export function attachRecordQueryListener(deps: RecordDeps = getDefaultDeps()): () => void {
   const listener = (
     message: unknown,
@@ -741,8 +501,7 @@ export function attachRecordQueryListener(deps: RecordDeps = getDefaultDeps()):
         sendResponse({ active: false });
         return;
       }
-      const activation = sender.tab?.active ? recording.tabs.noteActivation(tabId) : undefined;
-      await rearmRecording(recording, tabId, deps, activation);
+      await rearmRecording(recording, tabId, deps);
       sendResponse({
         active: true,
         requestId: recording.requestId,
@@ -764,50 +523,23 @@ async function finishRecordingByRequest(
     if (recording.requestId !== requestId || recording.settled) continue;
     const match = await findRecordingForTab(tabId, deps);
     if (match !== recording) continue;
-    await finishRecording(sessionId, deps, "user_finish");
+    await finishRecording(sessionId, deps);
     return;
   }
 }
 
-async function finishRecording(
-  sessionId: string,
-  deps: RecordDeps,
-  stoppedBy: StopReason,
-): Promise<RecordedTrace | null> {
+async function finishRecording(sessionId: string, deps: RecordDeps): Promise<TraceV2 | null> {
   const recording = recordings.get(sessionId);
-  if (!recording || recording.settled) return null;
-  if (recording.finishAttempt) return recording.finishAttempt;
-  recording.stoppedBy = stoppedBy;
+  if (!recording || recording.settled || recording.finishing) return null;
+  recording.finishing = true;
 
-  const attempt = finishRecordingAttempt(sessionId, recording, deps);
-  recording.finishAttempt = attempt;
-  try {
-    return await attempt;
-  } finally {
-    if (!recording.settled) {
-      recording.finishAttempt = null;
-    }
-  }
-}
-
-async function finishRecordingAttempt(
-  sessionId: string,
-  recording: ActiveRecording,
-  deps: RecordDeps,
-): Promise<RecordedTrace | null> {
   await clearRearmTimersForRecording(recording, deps);
   try {
-    // Disposing content capture may commit a final dirty fill. Flush content
-    // first so all resulting RECORD_STEP messages enter actionQueue before it
-    // and the observation queues are drained.
     await stopRecordingOnAllAgentTabs(recording, deps);
   } catch {
+    recording.finishing = false;
     return null;
   }
-  if (!(await drainRecordingToStability(recording))) {
-    return null;
-  }
-  await recording.observation?.settleTrailing(recording.tabs.currentTabId, recording.steps);
 
   recording.settled = true;
   recordings.delete(sessionId);
@@ -822,15 +554,6 @@ export async function handleRecordStart(
   params: RecordStartParams,
   deps: RecordDeps = getDefaultDeps(),
 ): Promise<RecordStartResult | RpcError> {
-  const traceVersionOrErr = negotiatedTraceVersion(params);
-  if (typeof traceVersionOrErr !== "number") return traceVersionOrErr;
-  if (traceVersionOrErr === 3 && !deps.cdp) {
-    return {
-      code: "protocol_error",
-      message: "trace v3 recording requires an active CDP connection",
-    };
-  }
-
   const ctxOrErr = lookupSession(manager, params, "record_start");
   if (isRpcError(ctxOrErr)) return ctxOrErr;
   const ctx = ctxOrErr;
@@ -847,64 +570,37 @@ export async function handleRecordStart(
   // on the destination page can RECORD_QUERY → rearm → show RecordOverlay
   // instead of flashing ControlOverlay ("Agent 正在控制").
   const requestId = makeRequestId(target.tabId);
-  let resolveFinish!: (trace: RecordedTrace) => void;
+  let resolveFinish!: (trace: TraceV2) => void;
   let rejectFinish!: (err: Error) => void;
-  const finishPromise = new Promise<RecordedTrace>((resolve, reject) => {
+  const finishPromise = new Promise<TraceV2>((resolve, reject) => {
     resolveFinish = resolve;
     rejectFinish = reject;
   });
   const navigateUrl = params.url ?? RECORD_DEFAULT_START_URL;
   const startedAtMs = Date.now();
-  const maxPageTokens = params.max_page_tokens;
-  const redactValues = params.redact_values ?? false;
   recordings.set(params.session_id, {
     requestId,
-    tabs: new RecordingTabCoordinator(target.tabId, navigateUrl),
+    tabId: target.tabId,
     agentWindowId: ctx.agentWindowId,
     startUrl: navigateUrl,
     ...(params.purpose ? { purpose: params.purpose } : {}),
     steps: [],
     startedAt: new Date(startedAtMs).toISOString(),
     startedAtMs,
-    traceVersion: traceVersionOrErr,
-    supportsTabSwitchSteps: params.supports_tab_switch_steps === true,
     finishPromise,
     resolveFinish,
     rejectFinish,
     settled: false,
-    finishAttempt: null,
-    observation:
-      traceVersionOrErr === 3 && deps.cdp
-        ? new RecordingObservationRuntime({
-            cdp: deps.cdp,
-            tabsApi: deps.tabsApi,
-            maxTokens: maxPageTokens,
-            redactValues,
-          })
-        : null,
-    stoppedBy: "user_finish",
-    navigationCallbacks: new Set(),
-    acceptingNavigation: true,
-    actionQueue: Promise.resolve(),
-    lastStepSequenceByProducer: new Map(),
-  });
-  deps.frameCoordinator?.begin(requestId, startedAtMs, target.tabId, async (scope) => {
-    const recording = recordings.get(params.session_id);
-    if (!recording || recording.requestId !== requestId || recording.settled) return;
-    try {
-      await recording.observation?.refreshDocument(scope.tabId, scope.producerId);
-    } catch {
-      // The normal action-time capture remains available if a child Document
-      // is replaced while its readiness refresh is in flight.
-    }
+    finishing: false,
+    currentUrl: navigateUrl,
+    pendingNavigation: false,
+    pendingNavigationDeadline: undefined,
   });
   // Observe navigations for the whole recording lifetime; attach before
   // optional navigate so the destination load can rearm capture.
   ensureBrowserObservationListeners(deps);
 
   const abortPending = async (notifyContent: boolean) => {
-    recordings.get(params.session_id)?.observation?.cancel();
-    deps.frameCoordinator?.cancel(requestId);
     recordings.delete(params.session_id);
     releaseBrowserObservationListenersIfIdle();
     if (notifyContent) {
@@ -986,7 +682,7 @@ export async function handleRecordStart(
     return cancelledError();
   }
   active.startUrl = startUrl;
-  active.tabs.navigation(target.tabId, startUrl).currentUrl = startUrl;
+  active.currentUrl = startUrl;
 
   if (isContentScriptRestrictedUrl(startUrl)) {
     await abortPending(false);
@@ -994,7 +690,7 @@ export async function handleRecordStart(
       code: "invalid_params",
       message: params.url
         ? `cannot record on restricted URL (${startUrl}); use an http(s) page`
-        : `cannot record on restricted URL (${startUrl}); default start page https://example.com/ did not load — pass --url with a page you can open`,
+        : `cannot record on restricted URL (${startUrl}); default start page must be injectable http(s)`,
     };
   }
 
@@ -1021,10 +717,6 @@ export async function handleRecordStart(
   const startMsg: RecordStartMessage = { type: RECORD_START, requestId, startedAtMs };
 
   try {
-    if (deps.frameCoordinator) {
-      const frameStarted = await deps.frameCoordinator.armTab(requestId, target.tabId);
-      if (!frameStarted) throw new Error("top recording document did not start");
-    }
     await sendRecordStartWithAck(target.tabId, startMsg, deps.sendToTab);
   } catch {
     await abortPending(true);
@@ -1035,17 +727,6 @@ export async function handleRecordStart(
     };
   }
 
-  if (active.observation) {
-    const activeRecording = recordings.get(params.session_id);
-    if (activeRecording) {
-      try {
-        await activeRecording.observation?.captureInitial(target.tabId);
-      } catch {
-        // Proceed without initial observation; steps may be dropped by reducer.
-      }
-    }
-  }
-
   {
     const cancelled = await abortIfCancelled(true);
     if (cancelled) return cancelled;
@@ -1070,7 +751,7 @@ export async function handleRecordStop(
     };
   }
 
-  const trace = await finishRecording(params.session_id, deps, "cli_stop");
+  const trace = await finishRecording(params.session_id, deps);
   if (!trace) {
     return {
       code: "protocol_error",
@@ -1100,9 +781,9 @@ export async function handleRecordAwait(
     return { code: "cancelled", message: "record_await aborted" };
   }
 
-  const outcome = await new Promise<{ trace: RecordedTrace } | { error: RpcError }>((resolve) => {
+  const outcome = await new Promise<{ trace: TraceV2 } | { error: RpcError }>((resolve) => {
     let settled = false;
-    const finish = (result: { trace: RecordedTrace } | { error: RpcError }) => {
+    const finish = (result: { trace: TraceV2 } | { error: RpcError }) => {
       if (settled) return;
       settled = true;
       if (timer) clearTimeout(timer);
@@ -1144,8 +825,6 @@ export function clearRecordingForSession(sessionId: string): void {
   }
   void clearRearmTimersForRecording(recording, getDefaultDeps());
   if (!recording.settled) {
-    getDefaultDeps().frameCoordinator?.cancel(recording.requestId);
-    recording.observation?.cancel();
     recording.settled = true;
     recording.rejectFinish(new Error("recording cleared"));
   }

apps/extension/src/tools/vom/__tests__/record-safe-observation.test.ts

@@ -1,82 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  RECORD_DOCUMENT_ATTRIBUTE,
-  recordingDocumentMarkerValue,
-} from "@/shared/recording-document-identity";
-import { projectRecordSafeObservation } from "../record-safe-observation";
-
-describe("projectRecordSafeObservation", () => {
-  it("projects the opaque recording identity without exposing captured attributes", () => {
-    const recordingDocumentId = "123e4567-e89b-42d3-a456-426614174000";
-    const result = projectRecordSafeObservation({
-      rootFrameId: "child",
-      frameDocuments: [
-        {
-          frameId: "child",
-          target: { tabId: 4, sessionId: "oopif-session" },
-          contextScopeId: "scope-1",
-          axNodes: [],
-          domNodes: [
-            {
-              backendNodeId: 1,
-              parentBackendNodeId: null,
-              tag: "html",
-              attrs: {
-                [RECORD_DOCUMENT_ATTRIBUTE]: recordingDocumentMarkerValue(recordingDocumentId),
-                value: "user@example.com",
-              },
-              rect: null,
-              paintOrder: 0,
-              position: "static",
-              pointerEvents: "auto",
-            },
-          ],
-        },
-      ],
-      rendered: { text: '@vom 1\nRootWebArea "Example"', refs: [], truncated: false },
-    });
-
-    expect(result.frames).toEqual([
-      {
-        frameId: "child",
-        target: { tabId: 4, sessionId: "oopif-session" },
-        recordingDocumentId,
-      },
-    ]);
-    const dumped = JSON.stringify(result);
-    expect(dumped).not.toContain("user@example.com");
-    expect(dumped).not.toContain("attrs");
-    expect(dumped).not.toContain("domNodes");
-    expect(dumped).not.toContain("axNodes");
-  });
-
-  it("does not project a page-controlled marker value as recording identity", () => {
-    const result = projectRecordSafeObservation({
-      rootFrameId: "root",
-      frameDocuments: [
-        {
-          frameId: "root",
-          target: { tabId: 4 },
-          contextScopeId: "scope-1",
-          axNodes: [],
-          domNodes: [
-            {
-              backendNodeId: 1,
-              parentBackendNodeId: null,
-              tag: "html",
-              attrs: { [RECORD_DOCUMENT_ATTRIBUTE]: "bsk:user@example.com" },
-              rect: null,
-              paintOrder: 0,
-              position: "static",
-              pointerEvents: "auto",
-            },
-          ],
-        },
-      ],
-      rendered: { text: '@vom 1\nRootWebArea "Example"', refs: [], truncated: false },
-    });
-
-    expect(result.frames).toEqual([{ frameId: "root", target: { tabId: 4 } }]);
-    expect(JSON.stringify(result)).not.toContain("user@example.com");
-  });
-});

apps/extension/src/tools/vom/record-safe-observation.ts

@@ -1,6 +1,5 @@
 import type { Rect, RenderedRef, VomResult } from "@browser-skill/vom";
 import type { CdpTarget } from "@/browser-driver/frame-graph";
-import { readRecordingDocumentIdentity } from "@/shared/recording-document-identity";
 import type { CapturedSurfaceProbe } from "./capture";
 import type { CapturedFrameDocument, FrameAxNode } from "./frame-capture";
 
@@ -10,8 +9,6 @@ export interface CaptureVomFrame {
   target: CdpTarget;
   parentFrameId?: string;
   ownerBackendNodeId?: number;
-  /** BrowserSkill-generated identity for the recording agent in this Document. */
-  recordingDocumentId?: string;
 }
 
 /** Allowlisted geometry used to match a recorded action to a rendered ref. */
@@ -40,22 +37,14 @@ export interface CaptureVomObservationResult {
 }
 
 function projectFrames(documents: CapturedFrameDocument<FrameAxNode>[]): CaptureVomFrame[] {
-  return documents.map((document) => {
-    let recordingDocumentId: string | undefined;
-    for (const node of document.domNodes) {
-      recordingDocumentId = readRecordingDocumentIdentity(node.attrs);
-      if (recordingDocumentId) break;
-    }
-    return {
-      frameId: document.frameId,
-      target: document.target,
-      ...(document.parentFrameId ? { parentFrameId: document.parentFrameId } : {}),
-      ...(document.ownerBackendNodeId !== undefined
-        ? { ownerBackendNodeId: document.ownerBackendNodeId }
-        : {}),
-      ...(recordingDocumentId ? { recordingDocumentId } : {}),
-    };
-  });
+  return documents.map((document) => ({
+    frameId: document.frameId,
+    target: document.target,
+    ...(document.parentFrameId ? { parentFrameId: document.parentFrameId } : {}),
+    ...(document.ownerBackendNodeId !== undefined
+      ? { ownerBackendNodeId: document.ownerBackendNodeId }
+      : {}),
+  }));
 }
 
 function projectMatchNodes(documents: CapturedFrameDocument<FrameAxNode>[]): CaptureVomMatchNode[] {

apps/extension/src/transport/__tests__/handshake.test.ts

@@ -65,11 +65,6 @@ function deferredFakeTransport(): { transport: Transport; emit: (frame: Protocol
 }
 
 describe("performHandshake", () => {
-  it("advertises the protocol compatibility boundary", () => {
-    expect(PROTOCOL_VERSION).toBe("1.1");
-    expect(MIN_COMPATIBLE_PROTOCOL).toBe("1.0");
-  });
-
   it("sends system.handshake with identity and both compat fields", async () => {
     let sentFrame: ProtocolFrame | null = null;
     const transport = fakeTransport((req) => {
@@ -79,7 +74,7 @@ describe("performHandshake", () => {
         result: {
           server: "browser-skill-daemon",
           version: "0.1.0",
-          protocol_version: "1.1",
+          protocol_version: "1.0",
           min_compatible_peer: "0.0.0",
           min_compatible_protocol: "1.0",
         },
@@ -134,8 +129,8 @@ describe("performHandshake", () => {
     const response = {
       server: "browser-skill-daemon",
       version: "0.1.0",
-      protocol_version: "1.1",
-      min_compatible_protocol: "1.1",
+      protocol_version: "1.0",
+      min_compatible_protocol: "1.0",
     } satisfies HandshakeResult;
     const transport = fakeTransport((req) => ({
       id: (req as { id: string }).id,
@@ -150,7 +145,7 @@ describe("performHandshake", () => {
     });
 
     expect(outcome.result.min_compatible_peer).toBeUndefined();
-    expect(outcome.result.min_compatible_protocol).toBe("1.1");
+    expect(outcome.result.min_compatible_protocol).toBe("1.0");
   });
 
   it("rejects when the daemon responds with an error", async () => {
@@ -183,9 +178,9 @@ describe("performHandshake", () => {
       result: {
         server: "browser-skill-daemon",
         version: "0.1.0",
-        protocol_version: "1.1",
+        protocol_version: "1.0",
         min_compatible_peer: "0.0.0",
-        min_compatible_protocol: "1.1",
+        min_compatible_protocol: "1.0",
       },
     });
     emit({
@@ -193,14 +188,14 @@ describe("performHandshake", () => {
       result: {
         server: "browser-skill-daemon",
         version: "0.1.0",
-        protocol_version: "1.1",
+        protocol_version: "1.0",
         min_compatible_peer: "0.0.0",
-        min_compatible_protocol: "1.1",
+        min_compatible_protocol: "1.0",
       },
     });
 
     await expect(pending).resolves.toMatchObject({
-      result: { server: "browser-skill-daemon", protocol_version: "1.1" },
+      result: { server: "browser-skill-daemon", protocol_version: "1.0" },
     });
   });
 

apps/extension/src/transport/handshake.ts

@@ -7,7 +7,7 @@ import type {
   ResponseFrame,
 } from "./types";
 
-export const PROTOCOL_VERSION = "1.1";
+export const PROTOCOL_VERSION = "1.0";
 /**
  * Extension semver, injected at build time from `package.json` via
  * Vite's `define` (see `wxt.config.ts` and `vitest.config.ts`).

apps/extension/src/transport/types.ts

@@ -780,7 +780,6 @@ export interface SelectedOptionV3 {
 
 export type StepV3 =
   | ({ op: "navigate" } & StepCommonV3 & { to: string; cause: NavigationCause })
-  | ({ op: "switch_tab" } & StepCommonV3)
   | ({ op: "click" } & StepCommonV3 & { target: TargetDescriptorV3 })
   | ({ op: "hover" } & StepCommonV3 & { target: TargetDescriptorV3 })
   | ({ op: "fill" } & StepCommonV3 & {
@@ -820,12 +819,6 @@ export interface RecordStartParams {
   tab_id?: number;
   url?: string;
   purpose?: string;
-  max_page_tokens?: number;
-  redact_values?: boolean;
-  /** Omitted means v2; `3` requests a state-linked v3 trace. */
-  trace_version?: number;
-  /** Client can decode the v3 `switch_tab` step variant. */
-  supports_tab_switch_steps?: boolean;
 }
 
 export interface RecordStartResult {

crates/bsk-cli/skill/SKILL.md

@@ -265,27 +265,19 @@ retry — complete the task autonomously or stop gracefully.
 
 ### Recording — `bsk record`
 
-Capture the user's own actions in the Agent Window to a **trace bundle**, for later LLM-driven automation. New CLI builds request **trace v3** (page observations + action chain); older extensions may still return **trace v2** (actions only), which the CLI exports as a single `trace.json` without `states/`.
+Capture the user's own actions in the Agent Window to a `trace.json`, for later LLM-driven automation:
 
 ```bash
-bsk record start --browser <instance-id-or-label> \
-  [--url https://…] [--purpose "publish a wiki doc"] \
-  [--max-page-tokens 3000] [--redact-values] \
-  [--output trace]
+bsk record start --browser <instance-id-or-label> [--url https://…] [--purpose "publish a wiki doc"] [--output trace.json]
 # `--url` is optional; default https://example.com/ when omitted (must be http(s)).
-# Blocks until the user clicks Finish in the recording panel, then writes:
-#   trace/trace.json    — action chain (+ state index when v3)
-#   trace/states/       — v3 only: one `sN.txt` observe snapshot per settled page state
+# Blocks until the user clicks Finish in the recording panel, then writes ./trace.json and closes the window.
 
-bsk record stop [--output trace]   # terminal fallback if the browser panel is unavailable
+bsk record stop [--output trace.json]   # terminal fallback if the browser panel is unavailable
 ```
 
-- **v3 bundle (preferred):** `--output` is a directory (default `./trace`) containing `trace.json` and `states/`. `trace.json` lists `states[]` (page observation ids) and `steps[]` (each step binds `state` = observe snapshot *before* the action and `result.state` = snapshot *after* settle). Page bodies live in `states/sN.txt` using the same VOM format as `bsk observe`.
-- **v2 fallback:** when the connected extension is older, export may contain only legacy `trace.json` with `pages[]` action context and no `states/` observation files. Update the extension for full v3 bundles.
-- Each `states[]` entry is one **settled page observation** (captured after recording start, navigation landing, or action settle — not on a timer).
-- `target.ref` values like `@e12` exist **only inside** the bundle for disambiguation; do **not** copy `@eN` refs into SKILL.md or agent runbooks — use visible names from the observation text instead.
+- The trace is a **record-only action log** (a `pages[]` dictionary + `navigate`/`click`/`fill`/`select`/`press` steps with `target` descriptors). It records *what the user did*; deciding which inputs are variable is left to the executing agent.
 - `--purpose` is optional context metadata; it does **not** change what gets captured.
-- `--redact-values` masks all form values in page files as `[filled]` / `[empty]`.
+- There is **no** `bsk replay` — to redo a flow, read the trace and reuse the existing `session` / `snapshot` / `@eN` / `click` / `fill` tools. Follow **Stop when the goal is met**.
 - Do **not** record on banking/SSO/password-manager pages; passwords are redacted but traces may still contain sensitive text.
 
 ## Error handling

crates/bsk-cli/src/cli/mod.rs

@@ -22,7 +22,6 @@ pub mod navigate;
 pub mod network;
 pub mod observe;
 pub mod record;
-pub mod record_recovery;
 pub mod record_state;
 pub mod render_error;
 pub mod screenshot;

crates/bsk-cli/src/cli/record.rs

@@ -1,30 +1,23 @@
 //! `bsk record start|stop` — capture user actions in the Agent Window.
 
-use std::path::{Path, PathBuf};
+use std::fs;
+use std::path::PathBuf;
 use std::time::Duration;
 
 use anyhow::Context;
+use bsk_protocol::Method;
 use bsk_protocol::tools::{
     RecordAwaitParams, RecordAwaitResult, RecordStartParams, RecordStartResult, RecordStopParams,
-    RecordStopResult, RecordedTrace, TRACE_VERSION_V3,
+    RecordStopResult, RecordedTrace,
 };
-use bsk_protocol::{ErrorCode, Method};
 use clap::{Args, Subcommand};
 
 use crate::cli::TOOL_IPC_TIMEOUT;
-
-mod export;
-
 use crate::cli::business_rpc;
 use crate::cli::ensure_daemon::ensure_daemon;
 use crate::cli::error::{CliError, Format};
-use crate::cli::record_recovery;
 use crate::cli::record_state;
 use crate::cli::session::{SessionStartOptions, start_session, stop_session};
-use export::{
-    ExportMeta, export_with_recovery, states_dir_for_output, trace_json_path,
-    validate_record_output,
-};
 
 /// Max wait for the user to click 结束 in the browser (24 hours).
 const RECORD_AWAIT_TIMEOUT_MS: u32 = 86_400_000;
@@ -57,8 +50,7 @@ pub struct RecordStartArgs {
     pub tab_id: Option<i64>,
 
     /// Navigate to this http(s) URL before recording. When omitted, defaults
-    /// to `https://example.com/`. If that page does not load, pass `--url`
-    /// with a site you can open in this browser.
+    /// to `https://example.com/`.
     #[arg(long)]
     pub url: Option<String>,
 
@@ -66,25 +58,15 @@ pub struct RecordStartArgs {
     #[arg(long)]
     pub purpose: Option<String>,
 
-    /// Max VOM tokens per page observation file (default 3000).
-    #[arg(long = "max-page-tokens")]
-    pub max_page_tokens: Option<u32>,
-
-    /// Redact all form values in page observations (`[filled]` only).
-    #[arg(long = "redact-values")]
-    pub redact_values: bool,
-
-    /// Output directory for the trace bundle (default `./trace`).
-    /// Writes `<dir>/trace.json` and `<dir>/states/*.txt`.
-    #[arg(long, default_value = "trace")]
+    /// Output path for the trace JSON (default `./trace.json`).
+    #[arg(long, default_value = "trace.json")]
     pub output: PathBuf,
 }
 
 #[derive(Debug, Clone, Args)]
 pub struct RecordStopArgs {
-    /// Output directory for the trace bundle (default `./trace`).
-    /// Writes `<dir>/trace.json` and `<dir>/states/*.txt`.
-    #[arg(long, default_value = "trace")]
+    /// Output path for the trace JSON (default `./trace.json`).
+    #[arg(long, default_value = "trace.json")]
     pub output: PathBuf,
 }
 
@@ -96,7 +78,11 @@ pub fn dispatch(cmd: RecordCmd, format: Format) -> Result<(), CliError> {
 }
 
 fn dispatch_start(args: RecordStartArgs, format: Format) -> Result<(), CliError> {
-    prepare_record_start(&args.output)?;
+    if record_state::read().is_ok() {
+        return Err(CliError::Local(anyhow::anyhow!(
+            "a recording is already in progress; run `bsk record stop` first"
+        )));
+    }
 
     let info = ensure_daemon().context("ensure daemon is running")?;
     let session = start_session(
@@ -110,12 +96,8 @@ fn dispatch_start(args: RecordStartArgs, format: Format) -> Result<(), CliError>
     let start_params = RecordStartParams {
         session_id: session.session_id.clone(),
         tab_id: args.tab_id,
-        url: args.url.clone(),
+        url: args.url,
         purpose: args.purpose.clone(),
-        max_page_tokens: args.max_page_tokens,
-        redact_values: Some(args.redact_values),
-        trace_version: Some(TRACE_VERSION_V3),
-        supports_tab_switch_steps: Some(true),
     };
     let start_result = business_rpc::call::<RecordStartParams, RecordStartResult>(
         info.sock_path.clone(),
@@ -129,7 +111,7 @@ fn dispatch_start(args: RecordStartArgs, format: Format) -> Result<(), CliError>
         Ok(result) => result,
         Err(err) => {
             let _ = stop_session(info.sock_path, &session.session_id);
-            return Err(annotate_default_start_page_error(err, args.url.as_deref()));
+            return Err(err);
         }
     };
 
@@ -160,8 +142,8 @@ fn dispatch_start(args: RecordStartArgs, format: Format) -> Result<(), CliError>
     // Keep write/render inside a Result so `?` cannot skip session teardown.
     let run_result: Result<(), CliError> = match await_result {
         Ok(result) => (|| {
-            let exported = export_with_recovery(&args.output, &result.trace)?;
-            render_finish(&result.trace, &args.output, &exported, format)
+            write_trace_file(&args.output, &result.trace)?;
+            render_finish(&result.trace, &args.output, format)
         })(),
         Err(err) => Err(err),
     };
@@ -175,12 +157,11 @@ fn dispatch_start(args: RecordStartArgs, format: Format) -> Result<(), CliError>
 }
 
 fn dispatch_stop(args: RecordStopArgs, format: Format) -> Result<(), CliError> {
-    validate_record_output(&args.output)?;
-
-    if let Ok(state) = record_state::read() {
-        let info = ensure_daemon().context("ensure daemon is running")?;
-        let session_id = state.session_id.clone();
+    let state = record_state::read().map_err(CliError::Local)?;
+    let info = ensure_daemon().context("ensure daemon is running")?;
+    let session_id = state.session_id.clone();
 
+    let run_result: Result<(), CliError> = (|| {
         let params = RecordStopParams {
             session_id: session_id.clone(),
         };
@@ -191,85 +172,16 @@ fn dispatch_stop(args: RecordStopArgs, format: Format) -> Result<(), CliError> {
             Some(params),
             TOOL_IPC_TIMEOUT,
         )?;
+        write_trace_file(&args.output, &result.trace)?;
+        render_stop(&result, &args.output, format)
+    })();
 
-        let run_result: Result<(), CliError> = (|| {
-            let exported = export_with_recovery(&args.output, &result.trace)?;
-            render_stop(&result, &args.output, &exported, format)
-        })();
+    let session_stop_result = stop_session(info.sock_path, &session_id);
+    record_state::clear();
 
-        let session_stop_result = stop_session(info.sock_path, &session_id);
-        record_state::clear();
-
-        run_result?;
-        session_stop_result?;
-        return Ok(());
-    }
-
-    let Some(trace) = record_recovery::load().map_err(CliError::Local)? else {
-        return Err(CliError::Local(anyhow::anyhow!(
-            "no recording in progress; run `bsk record start` first"
-        )));
-    };
-
-    let exported = export_with_recovery(&args.output, &trace)?;
-    render_finish(&trace, &args.output, &exported, format)
-}
-
-/// When `record start` omitted `--url` and the default example.com page
-/// never loaded, rewrite the RPC error so the CLI hint points at `--url`.
-fn annotate_default_start_page_error(err: CliError, user_url: Option<&str>) -> CliError {
-    if user_url.is_some() {
-        return err;
-    }
-    let CliError::Rpc {
-        code,
-        message,
-        data,
-        source,
-    } = err
-    else {
-        return err;
-    };
-    if !is_default_start_page_failure(code, &message) {
-        return CliError::Rpc {
-            code,
-            message,
-            data,
-            source,
-        };
-    }
-    CliError::Rpc {
-        code,
-        message,
-        data: Some(serde_json::json!({
-            "reason": crate::cli::render_error::reason::RECORD_START_PAGE_UNREACHABLE
-        })),
-        source,
-    }
-}
-
-fn is_default_start_page_failure(code: ErrorCode, message: &str) -> bool {
-    match code {
-        ErrorCode::CdpFailed | ErrorCode::Timeout => true,
-        ErrorCode::InvalidParams => {
-            message.contains("restricted URL") || message.contains("about:blank")
-        }
-        _ => false,
-    }
-}
-
-fn prepare_record_start(output: &Path) -> Result<(), CliError> {
-    if record_state::read().is_ok() {
-        return Err(CliError::Local(anyhow::anyhow!(
-            "a recording is already in progress; run `bsk record stop` first"
-        )));
-    }
-    if record_recovery::exists() {
-        return Err(CliError::Local(anyhow::anyhow!(
-            "a previous recording was not exported; run `bsk record stop --output <dir>` to recover it first"
-        )));
-    }
-    validate_record_output(output)
+    run_result?;
+    session_stop_result?;
+    Ok(())
 }
 
 fn record_await_ipc_timeout(timeout_ms: u32) -> Duration {
@@ -278,66 +190,43 @@ fn record_await_ipc_timeout(timeout_ms: u32) -> Duration {
         .unwrap_or(Duration::from_secs(u64::from(timeout_ms / 1_000) + 15))
 }
 
-fn render_finish(
-    trace: &RecordedTrace,
-    output_dir: &PathBuf,
-    exported: &ExportMeta,
-    format: Format,
-) -> Result<(), CliError> {
-    let trace_path = trace_json_path(output_dir);
+fn write_trace_file(output: &PathBuf, trace: &RecordedTrace) -> Result<(), CliError> {
+    let json = serde_json::to_string_pretty(trace)
+        .context("serialize trace JSON")
+        .map_err(CliError::Local)?;
+    if let Some(parent) = output.parent() {
+        if !parent.as_os_str().is_empty() {
+            fs::create_dir_all(parent)
+                .with_context(|| format!("create output directory {}", parent.display()))
+                .map_err(CliError::Local)?;
+        }
+    }
+    fs::write(output, format!("{json}\n"))
+        .with_context(|| format!("write trace to {}", output.display()))
+        .map_err(CliError::Local)?;
+    Ok(())
+}
+
+fn render_finish(trace: &RecordedTrace, output: &PathBuf, format: Format) -> Result<(), CliError> {
     match format {
         Format::Json => {
-            let payload = match trace {
-                RecordedTrace::V3(t) => serde_json::json!({
-                    "output": output_dir,
-                    "trace_json": trace_path,
-                    "trace_version": exported.trace_version,
-                    "states_dir": exported.states_dir,
-                    "trace": t,
-                    "window_closed": true,
-                }),
-                RecordedTrace::V2(t) => serde_json::json!({
-                    "output": output_dir,
-                    "trace_json": trace_path,
-                    "trace_version": exported.trace_version,
-                    "states_dir": null,
-                    "trace": t,
-                    "window_closed": true,
-                }),
-            };
             println!(
                 "{}",
-                serde_json::to_string(&payload).map_err(|e| CliError::Local(anyhow::anyhow!(e)))?
+                serde_json::to_string(&serde_json::json!({
+                    "output": output,
+                    "trace": trace,
+                    "window_closed": true,
+                }))
+                .map_err(|e| CliError::Local(anyhow::anyhow!(e)))?
             );
         }
-        Format::Human => match trace {
-            RecordedTrace::V3(t) => {
-                let states_dir = exported
-                    .states_dir
-                    .as_ref()
-                    .map(|p| p.display().to_string())
-                    .unwrap_or_else(|| states_dir_for_output(output_dir).display().to_string());
-                println!(
-                    "saved {} steps to {} and {} states to {}",
-                    t.steps.len(),
-                    trace_path.display(),
-                    t.states.len(),
-                    states_dir
-                );
-            }
-            RecordedTrace::V2(t) => {
-                if exported.v2_fallback {
-                    eprintln!(
-                        "note: extension returned trace v2 (no page observations); update the BrowserSkill extension for v3 bundles"
-                    );
-                }
-                println!(
-                    "saved {} steps to {} (trace v2)",
-                    t.steps.len(),
-                    trace_path.display()
-                );
-            }
-        },
+        Format::Human => {
+            let step_count = match trace {
+                RecordedTrace::V2(trace) => trace.steps.len(),
+                RecordedTrace::V3(trace) => trace.steps.len(),
+            };
+            println!("saved {step_count} steps to {}", output.display());
+        }
     }
     Ok(())
 }
@@ -345,89 +234,33 @@ fn render_finish(
 fn render_stop(
     result: &RecordStopResult,
     output: &PathBuf,
-    exported: &ExportMeta,
     format: Format,
 ) -> Result<(), CliError> {
-    render_finish(&result.trace, output, exported, format)
+    render_finish(&result.trace, output, format)
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
-    fn with_temp_home<F: FnOnce()>(f: F) {
-        let _lock = record_recovery::test_env_lock();
-        let tmp = tempfile::tempdir().unwrap();
-        unsafe {
-            std::env::set_var(crate::daemon::paths::BSK_HOME_ENV, tmp.path());
-        }
-        f();
-        record_recovery::clear();
-        record_state::clear();
-        unsafe {
-            std::env::remove_var(crate::daemon::paths::BSK_HOME_ENV);
-        }
-    }
-
     #[test]
-    fn prepare_record_start_rejects_existing_trace_json_file() {
-        with_temp_home(|| {
-            let dir = tempfile::tempdir().unwrap();
-            let output = dir.path().join("trace.json");
-            std::fs::write(&output, "{}\n").unwrap();
-
-            let err = prepare_record_start(&output).unwrap_err();
-            let msg = err.to_string();
-            assert!(
-                msg.contains("JSON file") || msg.contains("json file"),
-                "{msg}"
-            );
-            assert!(
-                msg.contains("states/") || msg.contains("--output trace"),
-                "{msg}"
-            );
-        });
-    }
-
-    #[test]
-    fn prepare_record_start_rejects_unexported_recovery() {
-        with_temp_home(|| {
-            crate::daemon::paths::ensure_bsk_home().unwrap();
-            std::fs::write(
-                crate::daemon::paths::record_recovery_path().unwrap(),
-                "{}\n",
-            )
-            .unwrap();
-
-            let err = prepare_record_start(Path::new("trace")).unwrap_err();
-            let msg = err.to_string();
-            assert!(
-                msg.contains("not exported") || msg.contains("recover"),
-                "{msg}"
-            );
-        });
-    }
-
-    #[test]
-    fn default_output_is_trace_dir() {
+    fn default_output_is_trace_json() {
         let args = RecordStopArgs {
-            output: PathBuf::from("trace"),
+            output: PathBuf::from("trace.json"),
         };
-        assert_eq!(args.output, PathBuf::from("trace"));
+        assert_eq!(args.output, PathBuf::from("trace.json"));
     }
 
     #[test]
-    fn start_args_default_output_is_trace_dir() {
+    fn start_args_default_output_is_trace_json() {
         let args = RecordStartArgs {
             browser: None,
             tab_id: None,
             url: None,
             purpose: None,
-            max_page_tokens: None,
-            redact_values: false,
-            output: PathBuf::from("trace"),
+            output: PathBuf::from("trace.json"),
         };
-        assert_eq!(args.output, PathBuf::from("trace"));
+        assert_eq!(args.output, PathBuf::from("trace.json"));
     }
 
     #[test]
@@ -435,35 +268,4 @@ mod tests {
         let got = record_await_ipc_timeout(RECORD_AWAIT_TIMEOUT_MS);
         assert!(got >= Duration::from_secs(86_400));
     }
-
-    #[test]
-    fn annotate_default_start_page_error_adds_url_reason() {
-        let err = CliError::from_rpc(bsk_protocol::RpcError {
-            code: ErrorCode::CdpFailed,
-            message: "Page.navigate rejected: net::ERR_ABORTED".into(),
-            data: None,
-        });
-        let annotated = annotate_default_start_page_error(err, None);
-        assert_eq!(
-            crate::cli::render_error::reason_for_data(annotated.data()),
-            Some(crate::cli::render_error::reason::RECORD_START_PAGE_UNREACHABLE)
-        );
-        let info =
-            crate::cli::render_error::info_for_error(annotated.code().unwrap(), annotated.data());
-        assert!(info.hint.unwrap().contains("--url"));
-    }
-
-    #[test]
-    fn annotate_default_start_page_error_skips_when_user_passed_url() {
-        let err = CliError::from_rpc(bsk_protocol::RpcError {
-            code: ErrorCode::CdpFailed,
-            message: "Page.navigate rejected: net::ERR_ABORTED".into(),
-            data: None,
-        });
-        let annotated = annotate_default_start_page_error(err, Some("https://www.example.org/"));
-        assert_eq!(
-            crate::cli::render_error::reason_for_data(annotated.data()),
-            None
-        );
-    }
 }

crates/bsk-cli/src/cli/record/export.rs

@@ -1,976 +0,0 @@
-use std::collections::HashSet;
-use std::fs::{self, OpenOptions};
-use std::io;
-use std::path::{Path, PathBuf};
-
-use anyhow::Context;
-use bsk_protocol::tools::{RecordedTrace, TRACE_VERSION_V2, TRACE_VERSION_V3, TraceV2, TraceV3};
-use serde::Serialize;
-
-use crate::cli::error::CliError;
-
-#[derive(Debug)]
-pub(super) struct ExportMeta {
-    pub(super) states_dir: Option<PathBuf>,
-    pub(super) trace_version: u32,
-    /// True when the CLI requested v3 but the extension returned legacy v2.
-    pub(super) v2_fallback: bool,
-}
-
-pub(super) fn export_recorded_trace(
-    output_dir: &Path,
-    trace: &RecordedTrace,
-) -> Result<ExportMeta, CliError> {
-    match trace {
-        RecordedTrace::V3(trace) => {
-            let states_dir = write_trace_bundle(output_dir, trace)?;
-            Ok(ExportMeta {
-                states_dir: Some(states_dir),
-                trace_version: TRACE_VERSION_V3,
-                v2_fallback: false,
-            })
-        }
-        RecordedTrace::V2(trace) => {
-            write_trace_v2(output_dir, trace)?;
-            Ok(ExportMeta {
-                states_dir: None,
-                trace_version: TRACE_VERSION_V2,
-                v2_fallback: true,
-            })
-        }
-    }
-}
-
-/// Save the completed Trace first, then write the bundle. Recovery is
-/// removed only after the export commits so a bad `--output` cannot drop
-/// a recording the extension already returned.
-pub(super) fn export_with_recovery(
-    output_dir: &Path,
-    trace: &RecordedTrace,
-) -> Result<ExportMeta, CliError> {
-    let save_result = crate::cli::record_recovery::save(trace);
-    match export_recorded_trace(output_dir, trace) {
-        Ok(meta) => {
-            crate::cli::record_recovery::clear();
-            Ok(meta)
-        }
-        Err(export_err) => {
-            let export_err = annotate_recovery_hint(export_err, save_result.is_ok());
-            if let Err(save_err) = save_result {
-                return Err(match export_err {
-                    CliError::Local(inner) => CliError::Local(
-                        inner.context(format!("also failed to save recovery data: {save_err}")),
-                    ),
-                    other => other,
-                });
-            }
-            Err(export_err)
-        }
-    }
-}
-
-fn annotate_recovery_hint(err: CliError, recovery_saved: bool) -> CliError {
-    if !recovery_saved {
-        return err;
-    }
-    match err {
-        CliError::Local(inner) => CliError::Local(inner.context(
-            "export failed; the recorded trace was saved and can be recovered with `bsk record stop --output <dir>`",
-        )),
-        other => other,
-    }
-}
-
-fn looks_like_json_output(path: &Path) -> bool {
-    path.extension()
-        .and_then(|ext| ext.to_str())
-        .is_some_and(|ext| ext.eq_ignore_ascii_case("json"))
-}
-
-fn legacy_json_output_error(path: &Path) -> CliError {
-    CliError::Local(anyhow::anyhow!(
-        "--output {} is a JSON file path; Trace v3 writes a bundle directory \
-         (`<dir>/trace.json` and `<dir>/states/`), not a single file. \
-         Use `--output trace` or another directory.",
-        path.display()
-    ))
-}
-
-/// Reject legacy `--output trace.json` (and any existing non-directory)
-/// before a recording starts, so the user is not blocked only after Finish.
-pub(super) fn validate_record_output(path: &Path) -> Result<(), CliError> {
-    match fs::symlink_metadata(path) {
-        Ok(metadata) if metadata.file_type().is_symlink() => Err(CliError::Local(anyhow::anyhow!(
-            "--output {} must not be a symlink",
-            path.display()
-        ))),
-        Ok(metadata) if metadata.is_dir() => Ok(()),
-        Ok(_) if looks_like_json_output(path) => Err(legacy_json_output_error(path)),
-        Ok(_) => Err(CliError::Local(anyhow::anyhow!(
-            "--output {} is not a directory; Trace v3 writes a bundle directory \
-             (`<dir>/trace.json` and `<dir>/states/`). Use `--output trace`.",
-            path.display()
-        ))),
-        Err(err) if err.kind() == io::ErrorKind::NotFound => {
-            if looks_like_json_output(path) {
-                Err(legacy_json_output_error(path))
-            } else {
-                Ok(())
-            }
-        }
-        Err(err) => Err(CliError::Local(
-            anyhow::Error::new(err).context(format!("inspect --output {}", path.display())),
-        )),
-    }
-}
-
-fn acquire_export_lock(output_dir: &Path) -> Result<std::fs::File, CliError> {
-    validate_bundle_directory(output_dir, "output bundle directory")?;
-    fs::create_dir_all(output_dir)
-        .with_context(|| format!("create output dir {}", output_dir.display()))
-        .map_err(CliError::Local)?;
-    let lock_path = output_dir.join(".bsk-record-export.lock");
-    let lock_file = OpenOptions::new()
-        .read(true)
-        .write(true)
-        .create(true)
-        .truncate(false)
-        .open(&lock_path)
-        .with_context(|| format!("open export lock {}", lock_path.display()))
-        .map_err(CliError::Local)?;
-    fs2::FileExt::lock_exclusive(&lock_file)
-        .with_context(|| format!("lock export bundle {}", output_dir.display()))
-        .map_err(CliError::Local)?;
-    Ok(lock_file)
-}
-
-pub(super) fn write_trace_v2(output_dir: &Path, trace: &TraceV2) -> Result<(), CliError> {
-    let trace_path = trace_json_path(output_dir);
-    let states_dir = states_dir_for_output(output_dir);
-    let json = serde_json::to_string_pretty(trace)
-        .context("serialize trace JSON")
-        .map_err(CliError::Local)?;
-
-    let _lock = acquire_export_lock(output_dir)?;
-    validate_replaceable_file(&trace_path, "trace JSON")?;
-
-    let transaction_id = uuid::Uuid::new_v4();
-    let staging_dir = output_dir.join(format!(".bsk-record-stage-{transaction_id}"));
-    fs::create_dir_all(&staging_dir)
-        .with_context(|| format!("create staging dir {}", staging_dir.display()))
-        .map_err(CliError::Local)?;
-
-    let staged_trace = staging_dir.join("trace.json");
-    let stage_result: Result<(), CliError> = (|| {
-        fs::write(&staged_trace, format!("{json}\n"))
-            .with_context(|| format!("write staged trace to {}", staged_trace.display()))
-            .map_err(CliError::Local)?;
-        Ok(())
-    })();
-    if let Err(err) = stage_result {
-        let _ = fs::remove_dir_all(&staging_dir);
-        return Err(err);
-    }
-
-    commit_export_transaction(
-        &staging_dir,
-        &states_dir,
-        &HashSet::new(),
-        transaction_id,
-        vec![(
-            staged_trace,
-            trace_path,
-            output_dir.join(format!(".trace.json.{transaction_id}.bak")),
-        )],
-    )?;
-
-    Ok(())
-}
-
-pub(super) fn states_dir_for_output(output_dir: &Path) -> PathBuf {
-    output_dir.join("states")
-}
-
-pub(super) fn trace_json_path(output_dir: &Path) -> PathBuf {
-    output_dir.join("trace.json")
-}
-
-fn is_canonical_state_id(id: &str) -> bool {
-    let Some(number) = id.strip_prefix('s') else {
-        return false;
-    };
-    let mut digits = number.bytes();
-    matches!(digits.next(), Some(b'1'..=b'9')) && digits.all(|byte| byte.is_ascii_digit())
-}
-
-fn validate_bundle_directory(path: &Path, description: &str) -> Result<(), CliError> {
-    match fs::symlink_metadata(path) {
-        Ok(metadata) if metadata.file_type().is_symlink() => Err(CliError::Local(anyhow::anyhow!(
-            "{description} {} must not be a symlink",
-            path.display()
-        ))),
-        Ok(metadata) if metadata.is_dir() => Ok(()),
-        Ok(_) if looks_like_json_output(path) => Err(legacy_json_output_error(path)),
-        Ok(_) => Err(CliError::Local(anyhow::anyhow!(
-            "{description} {} is not a directory; Trace v3 writes `<dir>/trace.json` and `<dir>/states/`. Use `--output trace`.",
-            path.display()
-        ))),
-        Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(()),
-        Err(err) => Err(CliError::Local(
-            anyhow::Error::new(err).context(format!("inspect {description} {}", path.display())),
-        )),
-    }
-}
-
-fn validate_replaceable_file(path: &Path, description: &str) -> Result<(), CliError> {
-    match fs::symlink_metadata(path) {
-        Ok(metadata) if metadata.file_type().is_file() => Ok(()),
-        Ok(_) => Err(CliError::Local(anyhow::anyhow!(
-            "{description} {} is not a regular file",
-            path.display()
-        ))),
-        Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(()),
-        Err(err) => Err(CliError::Local(
-            anyhow::Error::new(err).context(format!("inspect {description} {}", path.display())),
-        )),
-    }
-}
-
-fn commit_staged_file(staged: &Path, target: &Path, backup: &Path) -> io::Result<Option<PathBuf>> {
-    let old_file = match fs::symlink_metadata(target) {
-        Ok(_) => {
-            fs::rename(target, backup)?;
-            Some(backup.to_path_buf())
-        }
-        Err(err) if err.kind() == io::ErrorKind::NotFound => None,
-        Err(err) => return Err(err),
-    };
-
-    if let Err(err) = fs::rename(staged, target) {
-        if let Some(old_file) = old_file.as_deref() {
-            if let Err(restore_err) = fs::rename(old_file, target) {
-                return Err(io::Error::new(
-                    restore_err.kind(),
-                    format!(
-                        "{err}; additionally failed to restore {}: {restore_err}",
-                        target.display()
-                    ),
-                ));
-            }
-        }
-        return Err(err);
-    }
-
-    Ok(old_file)
-}
-
-fn rollback_installed_files(installed: &[(PathBuf, Option<PathBuf>)]) -> io::Result<()> {
-    let mut rollback_error = None;
-    for (target, backup) in installed.iter().rev() {
-        match fs::remove_file(target) {
-            Ok(()) => {}
-            Err(err) if err.kind() == io::ErrorKind::NotFound => {}
-            Err(err) => {
-                rollback_error.get_or_insert(err);
-                continue;
-            }
-        }
-        if let Some(backup) = backup {
-            if let Err(err) = fs::rename(backup, target) {
-                rollback_error.get_or_insert(err);
-            }
-        }
-    }
-    match rollback_error {
-        Some(err) => Err(err),
-        None => Ok(()),
-    }
-}
-
-fn is_generated_state_name(name: &str) -> bool {
-    name.strip_suffix(".txt").is_some_and(is_canonical_state_id)
-}
-
-fn restore_staged_stale_states(staged: &[(PathBuf, PathBuf)]) -> io::Result<()> {
-    let mut restore_error = None;
-    for (original, backup) in staged.iter().rev() {
-        if let Err(err) = fs::rename(backup, original) {
-            restore_error.get_or_insert(err);
-        }
-    }
-    match restore_error {
-        Some(err) => Err(err),
-        None => Ok(()),
-    }
-}
-
-/// Move stale generated states aside so replacement and cleanup form one
-/// rollback boundary. User-owned files, including arbitrary non-`sN.txt`, stay.
-fn stage_stale_states(
-    states_dir: &Path,
-    keep: &HashSet<String>,
-    transaction_id: uuid::Uuid,
-) -> Result<Vec<(PathBuf, PathBuf)>, CliError> {
-    let entries = match fs::read_dir(states_dir) {
-        Ok(entries) => entries,
-        Err(err) if err.kind() == io::ErrorKind::NotFound => return Ok(Vec::new()),
-        Err(err) => {
-            return Err(CliError::Local(
-                anyhow::Error::new(err)
-                    .context(format!("read states dir {}", states_dir.display())),
-            ));
-        }
-    };
-
-    let mut staged = Vec::new();
-    for entry in entries {
-        let entry = match entry {
-            Ok(entry) => entry,
-            Err(err) => {
-                let restore_result = restore_staged_stale_states(&staged);
-                let message = match restore_result {
-                    Ok(()) => format!("read stale state entry: {err}"),
-                    Err(restore_err) => {
-                        format!("read stale state entry: {err}; restore also failed: {restore_err}")
-                    }
-                };
-                return Err(CliError::Local(anyhow::anyhow!(message)));
-            }
-        };
-        let name = entry.file_name();
-        let Some(name) = name.to_str() else { continue };
-        if !is_generated_state_name(name) || keep.contains(name) {
-            continue;
-        }
-
-        let original = entry.path();
-        let file_type = match entry.file_type() {
-            Ok(file_type) => file_type,
-            Err(err) => {
-                let restore_result = restore_staged_stale_states(&staged);
-                let message = match restore_result {
-                    Ok(()) => format!("inspect stale state {}: {err}", original.display()),
-                    Err(restore_err) => format!(
-                        "inspect stale state {}: {err}; restore also failed: {restore_err}",
-                        original.display()
-                    ),
-                };
-                return Err(CliError::Local(anyhow::anyhow!(message)));
-            }
-        };
-        if file_type.is_dir() {
-            let restore_result = restore_staged_stale_states(&staged);
-            let message = match restore_result {
-                Ok(()) => format!("stale state {} is a directory", original.display()),
-                Err(restore_err) => format!(
-                    "stale state {} is a directory; restore also failed: {restore_err}",
-                    original.display()
-                ),
-            };
-            return Err(CliError::Local(anyhow::anyhow!(message)));
-        }
-
-        let backup = states_dir.join(format!(".{name}.{transaction_id}.stale"));
-        if let Err(err) = fs::rename(&original, &backup) {
-            let restore_result = restore_staged_stale_states(&staged);
-            let message = match restore_result {
-                Ok(()) => format!("stage stale state {}: {err}", original.display()),
-                Err(restore_err) => format!(
-                    "stage stale state {}: {err}; restore also failed: {restore_err}",
-                    original.display()
-                ),
-            };
-            return Err(CliError::Local(anyhow::anyhow!(message)));
-        }
-        staged.push((original, backup));
-    }
-    Ok(staged)
-}
-
-fn commit_export_transaction(
-    staging_dir: &Path,
-    states_dir: &Path,
-    keep_states: &HashSet<String>,
-    transaction_id: uuid::Uuid,
-    replacements: Vec<(PathBuf, PathBuf, PathBuf)>,
-) -> Result<(), CliError> {
-    let mut installed = Vec::with_capacity(replacements.len());
-    for (staged, target, backup) in replacements {
-        match commit_staged_file(&staged, &target, &backup) {
-            Ok(old_file) => installed.push((target, old_file)),
-            Err(err) => {
-                let rollback_result = rollback_installed_files(&installed);
-                let _ = fs::remove_dir_all(staging_dir);
-                let message = match rollback_result {
-                    Ok(()) => format!("commit replacement {}: {err}", target.display()),
-                    Err(rollback_err) => format!(
-                        "commit replacement {}: {err}; rollback also failed: {rollback_err}",
-                        target.display()
-                    ),
-                };
-                return Err(CliError::Local(anyhow::anyhow!(message)));
-            }
-        }
-    }
-
-    let stale_states = match stage_stale_states(states_dir, keep_states, transaction_id) {
-        Ok(stale) => stale,
-        Err(err) => {
-            let rollback_result = rollback_installed_files(&installed);
-            let _ = fs::remove_dir_all(staging_dir);
-            let message = match rollback_result {
-                Ok(()) => err.to_string(),
-                Err(rollback_err) => {
-                    format!("{err}; replacement rollback also failed: {rollback_err}")
-                }
-            };
-            return Err(CliError::Local(anyhow::anyhow!(message)));
-        }
-    };
-
-    for (_, backup) in &installed {
-        if let Some(backup) = backup {
-            let _ = fs::remove_file(backup);
-        }
-    }
-    for (_, backup) in stale_states {
-        let _ = fs::remove_file(backup);
-    }
-    let _ = fs::remove_dir_all(staging_dir);
-    Ok(())
-}
-
-#[derive(Serialize)]
-struct BundleState<'a> {
-    id: &'a str,
-    url: &'a str,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    title: Option<&'a str>,
-    page: String,
-    #[serde(skip_serializing_if = "std::ops::Not::not")]
-    truncated: bool,
-}
-
-#[derive(Serialize)]
-struct BundleTrace<'a> {
-    version: u32,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    purpose: Option<&'a str>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    started_at: Option<&'a str>,
-    recorded_at: &'a str,
-    stopped_by: &'a bsk_protocol::tools::StopReason,
-    entry: &'a bsk_protocol::tools::TraceEntry,
-    recorder: &'a bsk_protocol::tools::RecorderInfo,
-    states: Vec<BundleState<'a>>,
-    steps: &'a [bsk_protocol::tools::StepV3],
-}
-
-pub(super) fn write_trace_bundle(output_dir: &Path, trace: &TraceV3) -> Result<PathBuf, CliError> {
-    let states_dir = states_dir_for_output(output_dir);
-    let trace_path = trace_json_path(output_dir);
-
-    if trace.version != TRACE_VERSION_V3 {
-        return Err(CliError::Local(anyhow::anyhow!(
-            "trace version {} is not supported (expected {})",
-            trace.version,
-            TRACE_VERSION_V3
-        )));
-    }
-
-    let mut state_ids = HashSet::with_capacity(trace.states.len());
-    for state in &trace.states {
-        if !is_canonical_state_id(&state.id) {
-            return Err(CliError::Local(anyhow::anyhow!(
-                "state id {:?} is not canonical (expected s1, s2, ...)",
-                state.id
-            )));
-        }
-        if !state_ids.insert(state.id.as_str()) {
-            return Err(CliError::Local(anyhow::anyhow!(
-                "duplicate state id {:?}",
-                state.id
-            )));
-        }
-    }
-
-    let mut disk_states = Vec::with_capacity(trace.states.len());
-    let mut state_writes = Vec::new();
-    let mut keep = HashSet::new();
-    for state in &trace.states {
-        let filename = format!("{}.txt", state.id);
-        let state_path = states_dir.join(&filename);
-        if state_path.parent() != Some(states_dir.as_path()) {
-            return Err(CliError::Local(anyhow::anyhow!(
-                "state path {} escapes states directory {}",
-                state_path.display(),
-                states_dir.display()
-            )));
-        }
-        keep.insert(filename.clone());
-        state_writes.push((filename.clone(), state.body.as_str()));
-        disk_states.push(BundleState {
-            id: &state.id,
-            url: &state.url,
-            title: state.title.as_deref(),
-            page: filename,
-            truncated: state.truncated,
-        });
-    }
-
-    let disk_trace = BundleTrace {
-        version: trace.version,
-        purpose: trace.purpose.as_deref(),
-        started_at: trace.started_at.as_deref(),
-        recorded_at: &trace.recorded_at,
-        stopped_by: &trace.stopped_by,
-        entry: &trace.entry,
-        recorder: &trace.recorder,
-        states: disk_states,
-        steps: &trace.steps,
-    };
-    let json = serde_json::to_string_pretty(&disk_trace)
-        .context("serialize trace JSON")
-        .map_err(CliError::Local)?;
-
-    validate_bundle_directory(output_dir, "output bundle directory")?;
-    fs::create_dir_all(output_dir)
-        .with_context(|| format!("create output dir {}", output_dir.display()))
-        .map_err(CliError::Local)?;
-
-    validate_bundle_directory(&states_dir, "states directory")?;
-
-    let _lock = acquire_export_lock(output_dir)?;
-
-    fs::create_dir_all(&states_dir)
-        .with_context(|| format!("create states dir {}", states_dir.display()))
-        .map_err(CliError::Local)?;
-
-    for (filename, _) in &state_writes {
-        validate_replaceable_file(&states_dir.join(filename), "state observation")?;
-    }
-    validate_replaceable_file(&trace_path, "trace JSON")?;
-
-    let transaction_id = uuid::Uuid::new_v4();
-    let staging_dir = output_dir.join(format!(".bsk-record-stage-{transaction_id}"));
-    let staging_states = staging_dir.join("states");
-    fs::create_dir_all(&staging_states)
-        .with_context(|| format!("create staging dir {}", staging_states.display()))
-        .map_err(CliError::Local)?;
-
-    let stage_result: Result<(), CliError> = (|| {
-        for (filename, body) in &state_writes {
-            let staged_path = staging_states.join(filename);
-            fs::write(&staged_path, body)
-                .with_context(|| {
-                    format!("write staged state observation {}", staged_path.display())
-                })
-                .map_err(CliError::Local)?;
-        }
-        let staged_trace = staging_dir.join("trace.json");
-        fs::write(&staged_trace, format!("{json}\n"))
-            .with_context(|| format!("write staged trace to {}", staged_trace.display()))
-            .map_err(CliError::Local)?;
-        Ok(())
-    })();
-    if let Err(err) = stage_result {
-        let _ = fs::remove_dir_all(&staging_dir);
-        return Err(err);
-    }
-
-    let mut replacements: Vec<(PathBuf, PathBuf, PathBuf)> =
-        Vec::with_capacity(state_writes.len() + 1);
-    for (filename, _) in &state_writes {
-        replacements.push((
-            staging_states.join(filename),
-            states_dir.join(filename),
-            states_dir.join(format!(".{filename}.{transaction_id}.bak")),
-        ));
-    }
-    replacements.push((
-        staging_dir.join("trace.json"),
-        trace_path.clone(),
-        output_dir.join(format!(".trace.json.{transaction_id}.bak")),
-    ));
-
-    commit_export_transaction(
-        &staging_dir,
-        &states_dir,
-        &keep,
-        transaction_id,
-        replacements,
-    )?;
-
-    Ok(states_dir)
-}
-
-#[cfg(test)]
-mod tests {
-    use std::fs;
-
-    use super::*;
-    use bsk_protocol::tools::{
-        NavigationCause, PageRefV2 as PageRef, RecorderInfo, StepCommonV3 as StepCommon,
-        StepResultV3 as StepResult, StepV3 as Step, StopReason, TRACE_VERSION_V2, TRACE_VERSION_V3,
-        TraceEntry, TraceStateV3, TraceV2, TraceV3, VOM_FORMAT_VERSION,
-    };
-
-    fn sample_trace(state_id: &str, body: &str) -> TraceV3 {
-        TraceV3 {
-            version: TRACE_VERSION_V3,
-            recorded_at: "2026-08-10T02:12:55.360Z".into(),
-            stopped_by: StopReason::UserFinish,
-            entry: TraceEntry {
-                start_url: "https://example.com/".into(),
-            },
-            recorder: RecorderInfo {
-                bsk: "0.1.10".into(),
-                vom: VOM_FORMAT_VERSION,
-            },
-            states: vec![TraceStateV3 {
-                id: state_id.into(),
-                url: "https://example.com/".into(),
-                title: Some("Example".into()),
-                body: body.into(),
-                truncated: false,
-            }],
-            steps: vec![Step::Navigate {
-                common: StepCommon {
-                    id: 1,
-                    state: state_id.into(),
-                    result: StepResult {
-                        state: state_id.into(),
-                    },
-                },
-                to: "https://example.com/".into(),
-                cause: NavigationCause::UserTyped,
-            }],
-            purpose: None,
-            started_at: None,
-        }
-    }
-
-    #[test]
-    fn write_trace_bundle_writes_dir_layout() {
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("flow");
-        let trace = sample_trace("s1", "@vom 1\nL1 page");
-        let states_dir = write_trace_bundle(&output, &trace).unwrap();
-        let trace_path = output.join("trace.json");
-        assert!(trace_path.exists());
-        assert_eq!(states_dir, output.join("states"));
-        assert!(states_dir.join("s1.txt").exists());
-        let disk: serde_json::Value =
-            serde_json::from_str(&fs::read_to_string(&trace_path).unwrap()).unwrap();
-        assert_eq!(disk["states"][0]["page"], "s1.txt");
-        assert!(disk["states"][0].get("body").is_none());
-        assert_eq!(
-            fs::read_to_string(states_dir.join("s1.txt")).unwrap(),
-            "@vom 1\nL1 page"
-        );
-
-        // Re-exporting drops states from the previous run but keeps the
-        // directory in place for the concurrent writer.
-        fs::write(states_dir.join("s9.txt"), "stale").unwrap();
-        fs::write(states_dir.join("notes.md"), "keep me").unwrap();
-        fs::write(states_dir.join("reference.txt"), "user file").unwrap();
-        write_trace_bundle(&output, &trace).unwrap();
-        assert!(!states_dir.join("s9.txt").exists());
-        assert!(states_dir.join("s1.txt").exists());
-        assert!(states_dir.join("notes.md").exists());
-        assert_eq!(
-            fs::read_to_string(states_dir.join("reference.txt")).unwrap(),
-            "user file"
-        );
-    }
-
-    #[test]
-    fn write_trace_bundle_rejects_traversal_state_id() {
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("flow");
-        let trace = sample_trace("../escaped", "@vom 1\nL1 page");
-
-        let err = write_trace_bundle(&output, &trace).unwrap_err();
-
-        assert!(err.to_string().contains("state id"));
-        assert!(!output.join("escaped.txt").exists());
-        assert!(!output.join("trace.json").exists());
-    }
-
-    #[test]
-    fn write_trace_bundle_rejects_duplicate_state_id() {
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("flow");
-        let mut trace = sample_trace("s1", "@vom 1\nL1 first");
-        trace.states.push(TraceStateV3 {
-            body: "@vom 1\nL1 duplicate".into(),
-            ..trace.states[0].clone()
-        });
-
-        let err = write_trace_bundle(&output, &trace).unwrap_err();
-
-        assert!(err.to_string().contains("duplicate state id"));
-        assert!(!output.exists());
-    }
-
-    #[test]
-    fn unsupported_version_preserves_existing_bundle() {
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("flow");
-        write_trace_bundle(&output, &sample_trace("s1", "original")).unwrap();
-        let original_json = fs::read(output.join("trace.json")).unwrap();
-
-        let mut replacement = sample_trace("s2", "replacement");
-        replacement.version += 1;
-        let err = write_trace_bundle(&output, &replacement).unwrap_err();
-
-        assert!(err.to_string().contains("not supported"));
-        assert_eq!(fs::read(output.join("trace.json")).unwrap(), original_json);
-        assert_eq!(
-            fs::read_to_string(output.join("states/s1.txt")).unwrap(),
-            "original"
-        );
-        assert!(!output.join("states/s2.txt").exists());
-    }
-
-    #[test]
-    fn state_replacement_failure_preserves_existing_bundle() {
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("flow");
-        write_trace_bundle(&output, &sample_trace("s1", "original")).unwrap();
-        let original_json = fs::read(output.join("trace.json")).unwrap();
-        fs::write(output.join("states/notes.md"), "keep me").unwrap();
-        fs::create_dir(output.join("states/s2.txt")).unwrap();
-
-        let err = write_trace_bundle(&output, &sample_trace("s2", "replacement")).unwrap_err();
-
-        assert!(err.to_string().contains("state"));
-        assert_eq!(fs::read(output.join("trace.json")).unwrap(), original_json);
-        assert_eq!(
-            fs::read_to_string(output.join("states/s1.txt")).unwrap(),
-            "original"
-        );
-        assert_eq!(
-            fs::read_to_string(output.join("states/notes.md")).unwrap(),
-            "keep me"
-        );
-    }
-
-    #[test]
-    fn stale_state_cleanup_failure_rolls_back_replacement() {
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("flow");
-        write_trace_bundle(&output, &sample_trace("s1", "original")).unwrap();
-        let original_json = fs::read(output.join("trace.json")).unwrap();
-        fs::create_dir(output.join("states/s9.txt")).unwrap();
-
-        let err = write_trace_bundle(&output, &sample_trace("s2", "replacement")).unwrap_err();
-
-        assert!(err.to_string().contains("stale state"));
-        assert_eq!(fs::read(output.join("trace.json")).unwrap(), original_json);
-        assert_eq!(
-            fs::read_to_string(output.join("states/s1.txt")).unwrap(),
-            "original"
-        );
-        assert!(!output.join("states/s2.txt").exists());
-        assert!(output.join("states/s9.txt").is_dir());
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn write_trace_bundle_rejects_symlinked_states_directory() {
-        use std::os::unix::fs::symlink;
-
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("flow");
-        let external_states = dir.path().join("external-states");
-        fs::create_dir_all(&output).unwrap();
-        fs::create_dir_all(&external_states).unwrap();
-        fs::write(external_states.join("s9.txt"), "external").unwrap();
-        symlink(&external_states, output.join("states")).unwrap();
-
-        let err = write_trace_bundle(&output, &sample_trace("s1", "replacement")).unwrap_err();
-
-        assert!(err.to_string().contains("symlink"));
-        assert_eq!(
-            fs::read_to_string(external_states.join("s9.txt")).unwrap(),
-            "external"
-        );
-        assert!(!external_states.join("s1.txt").exists());
-        assert!(!output.join("trace.json").exists());
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn write_trace_bundle_rejects_symlinked_output_directory() {
-        use std::os::unix::fs::symlink;
-
-        let dir = tempfile::tempdir().unwrap();
-        let external_output = dir.path().join("external-output");
-        let output = dir.path().join("flow");
-        fs::create_dir_all(&external_output).unwrap();
-        fs::write(external_output.join("notes.md"), "external").unwrap();
-        symlink(&external_output, &output).unwrap();
-
-        let err = write_trace_bundle(&output, &sample_trace("s1", "replacement")).unwrap_err();
-
-        assert!(err.to_string().contains("symlink"));
-        assert_eq!(
-            fs::read_to_string(external_output.join("notes.md")).unwrap(),
-            "external"
-        );
-        assert!(!external_output.join("trace.json").exists());
-        assert!(!external_output.join("states").exists());
-    }
-
-    #[test]
-    fn write_trace_v2_writes_single_json_and_prunes_stale_states() {
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("flow");
-        fs::create_dir_all(output.join("states")).unwrap();
-        fs::write(output.join("states/s1.txt"), "stale").unwrap();
-
-        let trace = TraceV2 {
-            recorded_at: "2026-08-10T02:12:55.360Z".into(),
-            started_at: None,
-            purpose: None,
-            entry: bsk_protocol::tools::TraceEntry {
-                start_url: "https://example.com/".into(),
-            },
-            pages: vec![PageRef {
-                id: "p1".into(),
-                url: "https://example.com/".into(),
-                title: None,
-            }],
-            steps: vec![],
-        };
-        write_trace_v2(&output, &trace).unwrap();
-        assert!(output.join("trace.json").exists());
-        assert!(!output.join("states/s1.txt").exists());
-    }
-
-    #[test]
-    fn write_trace_v2_stale_cleanup_failure_rolls_back_trace() {
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("flow");
-        write_trace_bundle(&output, &sample_trace("s1", "original")).unwrap();
-        let original_json = fs::read(output.join("trace.json")).unwrap();
-        fs::create_dir(output.join("states/s9.txt")).unwrap();
-        let trace = TraceV2 {
-            recorded_at: "2026-08-10T02:12:55.360Z".into(),
-            started_at: None,
-            purpose: None,
-            entry: bsk_protocol::tools::TraceEntry {
-                start_url: "https://example.com/".into(),
-            },
-            pages: vec![],
-            steps: vec![],
-        };
-
-        let err = write_trace_v2(&output, &trace).unwrap_err();
-
-        assert!(err.to_string().contains("stale state"));
-        assert_eq!(fs::read(output.join("trace.json")).unwrap(), original_json);
-        assert_eq!(
-            fs::read_to_string(output.join("states/s1.txt")).unwrap(),
-            "original"
-        );
-        assert!(output.join("states/s9.txt").is_dir());
-    }
-
-    #[test]
-    fn export_recorded_trace_accepts_v2() {
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("flow");
-        let trace = RecordedTrace::V2(TraceV2 {
-            recorded_at: "2026-08-10T02:12:55.360Z".into(),
-            started_at: None,
-            purpose: None,
-            entry: bsk_protocol::tools::TraceEntry {
-                start_url: "https://example.com/".into(),
-            },
-            pages: vec![],
-            steps: vec![],
-        });
-        let exported = export_recorded_trace(&output, &trace).unwrap();
-        assert_eq!(exported.trace_version, TRACE_VERSION_V2);
-        assert!(exported.states_dir.is_none());
-        assert!(output.join("trace.json").exists());
-    }
-
-    #[test]
-    fn existing_trace_json_file_is_rejected_with_bundle_usage() {
-        let dir = tempfile::tempdir().unwrap();
-        let output = dir.path().join("trace.json");
-        fs::write(&output, "{}\n").unwrap();
-
-        let err = validate_record_output(&output).unwrap_err();
-        let msg = err.to_string();
-        assert!(
-            msg.contains("JSON file") || msg.contains("json file"),
-            "should name the legacy JSON file usage: {msg}"
-        );
-        assert!(
-            msg.contains("states/") || msg.contains("--output trace"),
-            "should hint at the new bundle directory usage: {msg}"
-        );
-        assert_eq!(fs::read_to_string(&output).unwrap(), "{}\n");
-    }
-
-    #[test]
-    fn missing_trace_json_path_is_rejected_as_legacy_output() {
-        let err = validate_record_output(Path::new("trace.json")).unwrap_err();
-        let msg = err.to_string();
-        assert!(
-            msg.contains("JSON file") || msg.contains("json file"),
-            "{msg}"
-        );
-        assert!(
-            msg.contains("states/") || msg.contains("--output trace"),
-            "{msg}"
-        );
-    }
-
-    #[test]
-    fn export_failure_keeps_recovery_for_retry() {
-        let _lock = crate::cli::record_recovery::test_env_lock();
-        let tmp = tempfile::tempdir().unwrap();
-        unsafe {
-            std::env::set_var(crate::daemon::paths::BSK_HOME_ENV, tmp.path());
-        }
-
-        let dir = tempfile::tempdir().unwrap();
-        let bad_output = dir.path().join("trace.json");
-        fs::write(&bad_output, "{}\n").unwrap();
-        let trace = RecordedTrace::V3(sample_trace("s1", "@vom 1\nL1 page"));
-
-        let err = export_with_recovery(&bad_output, &trace).unwrap_err();
-        let msg = err.to_string();
-        assert!(
-            msg.contains("recover") || msg.contains("record stop"),
-            "export failure should tell the user how to recover: {msg}"
-        );
-        assert!(
-            crate::cli::record_recovery::exists(),
-            "recovery data must survive a failed bundle export"
-        );
-        let recovered = crate::cli::record_recovery::load()
-            .unwrap()
-            .expect("recovery file");
-        assert_eq!(recovered, trace);
-        assert_eq!(fs::read_to_string(&bad_output).unwrap(), "{}\n");
-
-        let good_output = dir.path().join("bundle");
-        export_with_recovery(&good_output, &recovered).unwrap();
-        assert!(good_output.join("trace.json").exists());
-        assert!(good_output.join("states/s1.txt").exists());
-        assert!(
-            !crate::cli::record_recovery::exists(),
-            "successful export must delete recovery data"
-        );
-
-        unsafe {
-            std::env::remove_var(crate::daemon::paths::BSK_HOME_ENV);
-        }
-    }
-}

crates/bsk-cli/src/cli/record_recovery.rs

@@ -1,112 +0,0 @@
-//! Persist a completed Trace so a failed bundle export can be retried.
-
-use std::fs;
-
-use anyhow::{Context, Result};
-use bsk_protocol::tools::RecordedTrace;
-
-use crate::daemon::paths;
-
-pub fn save(trace: &RecordedTrace) -> Result<()> {
-    let path = paths::record_recovery_path()?;
-    paths::ensure_bsk_home()?;
-    let json = serde_json::to_string_pretty(trace).context("serialize record recovery")?;
-    let tmp = path.with_extension("tmp");
-    fs::write(&tmp, format!("{json}\n")).with_context(|| format!("write {}", tmp.display()))?;
-    fs::rename(&tmp, &path).with_context(|| format!("commit {}", path.display()))?;
-    Ok(())
-}
-
-pub fn load() -> Result<Option<RecordedTrace>> {
-    let path = paths::record_recovery_path()?;
-    if !path.exists() {
-        return Ok(None);
-    }
-    let raw = fs::read_to_string(&path).with_context(|| format!("read {}", path.display()))?;
-    let trace = serde_json::from_str(&raw).with_context(|| format!("parse {}", path.display()))?;
-    Ok(Some(trace))
-}
-
-pub fn exists() -> bool {
-    paths::record_recovery_path()
-        .map(|path| path.exists())
-        .unwrap_or(false)
-}
-
-pub fn clear() {
-    if let Ok(path) = paths::record_recovery_path() {
-        let _ = fs::remove_file(path);
-    }
-}
-
-#[cfg(test)]
-pub(crate) fn test_env_lock() -> std::sync::MutexGuard<'static, ()> {
-    crate::daemon::paths::test_env_lock()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use bsk_protocol::tools::{
-        RecorderInfo, StopReason, TRACE_VERSION_V3, TraceEntry, TraceStateV3, TraceV3,
-        VOM_FORMAT_VERSION,
-    };
-
-    fn sample_trace() -> RecordedTrace {
-        RecordedTrace::V3(TraceV3 {
-            version: TRACE_VERSION_V3,
-            recorded_at: "2026-08-10T02:12:55.360Z".into(),
-            stopped_by: StopReason::UserFinish,
-            entry: TraceEntry {
-                start_url: "https://example.com/".into(),
-            },
-            recorder: RecorderInfo {
-                bsk: "0.1.10".into(),
-                vom: VOM_FORMAT_VERSION,
-            },
-            states: vec![TraceStateV3 {
-                id: "s1".into(),
-                url: "https://example.com/".into(),
-                title: Some("Example".into()),
-                body: "@vom 1\nL1 page".into(),
-                truncated: false,
-            }],
-            steps: vec![],
-            purpose: None,
-            started_at: None,
-        })
-    }
-
-    fn with_temp_home<F: FnOnce()>(f: F) {
-        let _lock = test_env_lock();
-        let tmp = tempfile::tempdir().unwrap();
-        unsafe {
-            std::env::set_var(crate::daemon::paths::BSK_HOME_ENV, tmp.path());
-        }
-        f();
-        clear();
-        unsafe {
-            std::env::remove_var(crate::daemon::paths::BSK_HOME_ENV);
-        }
-    }
-
-    #[test]
-    fn save_load_round_trips() {
-        with_temp_home(|| {
-            let trace = sample_trace();
-            save(&trace).unwrap();
-            assert!(exists());
-            assert_eq!(load().unwrap(), Some(trace));
-        });
-    }
-
-    #[test]
-    fn clear_removes_recovery_file() {
-        with_temp_home(|| {
-            save(&sample_trace()).unwrap();
-            clear();
-            assert!(!exists());
-            assert_eq!(load().unwrap(), None);
-        });
-    }
-}

crates/bsk-cli/src/cli/record_state.rs

@@ -59,9 +59,15 @@ fn started_at_unix_ms() -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::sync::Mutex;
+
+    fn env_guard() -> &'static Mutex<()> {
+        static GUARD: Mutex<()> = Mutex::new(());
+        &GUARD
+    }
 
     fn with_temp_home<F: FnOnce()>(f: F) {
-        let _lock = crate::daemon::paths::test_env_lock();
+        let _lock = env_guard().lock().unwrap_or_else(|e| e.into_inner());
         let tmp = tempfile::tempdir().unwrap();
         unsafe {
             std::env::set_var(crate::daemon::paths::BSK_HOME_ENV, tmp.path());

crates/bsk-cli/src/cli/render_error.rs

@@ -50,7 +50,6 @@ pub mod reason {
     pub const BORROW_CONFLICT: &str = "borrow_conflict";
     pub const SCREENSHOT_CAPTURE_FAILED: &str = "screenshot_capture_failed";
     pub const SESSION_BUSY: &str = crate::rpc_reason::SESSION_BUSY;
-    pub const RECORD_START_PAGE_UNREACHABLE: &str = "record_start_page_unreachable";
 }
 
 /// Per-code rendering metadata. The `summary` is what the CLI prints
@@ -270,16 +269,6 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
             ),
             exit_code: base.exit_code,
         },
-        (
-            ErrorCode::CdpFailed | ErrorCode::Timeout | ErrorCode::InvalidParams,
-            reason::RECORD_START_PAGE_UNREACHABLE,
-        ) => RenderInfo {
-            summary: "default start page https://example.com/ could not be opened",
-            hint: Some(
-                "that site may be unreachable from your network. Pass --url with a page you can open, e.g. `bsk record start --url https://<site>/`",
-            ),
-            exit_code: base.exit_code,
-        },
         _ => base,
     }
 }
@@ -389,22 +378,6 @@ mod tests {
         assert_eq!(info.exit_code, 4);
     }
 
-    #[test]
-    fn record_start_page_unreachable_overrides_cdp_failed_copy() {
-        let data = serde_json::json!({ "reason": reason::RECORD_START_PAGE_UNREACHABLE });
-        let info = info_for_error(ErrorCode::CdpFailed, Some(&data));
-        assert_eq!(
-            info.summary,
-            "default start page https://example.com/ could not be opened"
-        );
-        assert!(
-            info.hint.unwrap().contains("--url"),
-            "expected --url hint, got {:?}",
-            info.hint
-        );
-        assert_eq!(info.exit_code, 3);
-    }
-
     #[test]
     fn screenshot_capture_failed_overrides_cdp_failed_copy() {
         let data = serde_json::json!({ "reason": reason::SCREENSHOT_CAPTURE_FAILED });

crates/bsk-cli/src/daemon/paths.rs

@@ -100,14 +100,6 @@ pub fn record_session_path() -> Result<PathBuf> {
     Ok(bsk_home()?.join("record-session.json"))
 }
 
-/// Path to a completed Trace saved before bundle export (`record-recovery.json`).
-///
-/// Kept until export succeeds so a failed `--output` write cannot drop the
-/// recording the extension already returned.
-pub fn record_recovery_path() -> Result<PathBuf> {
-    Ok(bsk_home()?.join("record-recovery.json"))
-}
-
 /// Windows named-pipe name. Include the resolved `BSK_HOME` path in the
 /// token so test homes and custom installs do not share a predictable
 /// per-username pipe.
@@ -127,13 +119,6 @@ pub fn pipe_name() -> String {
     render_pipe_name(&user, &home)
 }
 
-/// Process-wide lock for tests that mutate `BSK_HOME`.
-#[cfg(test)]
-pub(crate) fn test_env_lock() -> std::sync::MutexGuard<'static, ()> {
-    static GUARD: std::sync::Mutex<()> = std::sync::Mutex::new(());
-    GUARD.lock().unwrap_or_else(|e| e.into_inner())
-}
-
 /// Render the Windows named-pipe name for a user/home pair. Kept
 /// platform-agnostic so unit tests on any host can pin the output
 /// character set.
@@ -151,12 +136,19 @@ fn render_pipe_name(user: &str, home: &str) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::sync::Mutex;
     use tempfile::TempDir;
 
+    /// Serialise tests that mutate the global `BSK_HOME` env var.
+    fn env_guard() -> &'static Mutex<()> {
+        static GUARD: Mutex<()> = Mutex::new(());
+        &GUARD
+    }
+
     fn with_temp_home<F: FnOnce(&Path)>(f: F) {
-        let _lock = test_env_lock();
+        let _lock = env_guard().lock().unwrap_or_else(|e| e.into_inner());
         let tmp = TempDir::new().unwrap();
-        // SAFETY: serialised by test_env_lock above.
+        // SAFETY: serialised by env_guard above.
         unsafe {
             std::env::set_var(BSK_HOME_ENV, tmp.path().join("bsk"));
         }
@@ -195,10 +187,6 @@ mod tests {
                 record_session_path().unwrap(),
                 home.join("record-session.json")
             );
-            assert_eq!(
-                record_recovery_path().unwrap(),
-                home.join("record-recovery.json")
-            );
         });
     }
 

crates/bsk-cli/src/daemon/start.rs

@@ -15,6 +15,7 @@ use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 use std::path::Path;
 use std::sync::Arc;
 use std::sync::Mutex;
+use std::sync::atomic::{AtomicUsize, Ordering};
 use std::time::{Duration, Instant};
 
 use anyhow::{Context, Result};
@@ -26,7 +27,7 @@ use crate::daemon::{
     browsers::{BROWSER_LIVENESS_TICK, BROWSER_LIVENESS_TIMEOUT, EXTENSION_CONNECT_WAIT},
     info as daemon_info, ipc, lockfile, paths,
     sessions::{StopSessionError, forget_session, stop_session},
-    state::{DaemonState, PROTOCOL_VERSION},
+    state::DaemonState,
     ws,
 };
 
@@ -290,14 +291,15 @@ pub fn run_foreground(cfg: DaemonConfig) -> Result<()> {
         });
 
         let started_at = Instant::now();
-        let activity = Arc::new(Mutex::new(IpcActivityState::new(started_at)));
+        let activity: Arc<Mutex<Instant>> = Arc::new(Mutex::new(started_at));
+        let active_ipc_connections = Arc::new(AtomicUsize::new(0));
         let (ipc_shutdown_tx, ipc_shutdown_rx) = tokio::sync::oneshot::channel::<()>();
         let status = ipc::DaemonStatus {
             started_at,
             ws_port,
             sock_path: sock_path.clone(),
             daemon_version: env!("CARGO_PKG_VERSION"),
-            protocol_version: PROTOCOL_VERSION,
+            protocol_version: "1.0",
         };
         let handler = ipc::full_handler(status, Arc::clone(&state));
 
@@ -312,14 +314,18 @@ pub fn run_foreground(cfg: DaemonConfig) -> Result<()> {
             let handler = handler.clone();
             let ipc_open = {
                 let activity = activity.clone();
+                let active = active_ipc_connections.clone();
                 move || {
-                    record_ipc_open(&activity);
+                    active.fetch_add(1, Ordering::SeqCst);
+                    record_activity(&activity);
                 }
             };
             let ipc_close = {
                 let activity = activity.clone();
+                let active = active_ipc_connections.clone();
                 move || {
-                    record_ipc_close(&activity);
+                    active.fetch_sub(1, Ordering::SeqCst);
+                    record_activity(&activity);
                 }
             };
             tokio::spawn(ipc::serve(
@@ -338,6 +344,7 @@ pub fn run_foreground(cfg: DaemonConfig) -> Result<()> {
         let idle_task = {
             let activity = activity.clone();
             let state = Arc::clone(&state);
+            let active_ipc_connections = active_ipc_connections.clone();
             let daemon_idle = cfg.daemon_idle;
             tokio::spawn(async move {
                 let tick = (daemon_idle / 4).max(Duration::from_millis(250));
@@ -345,19 +352,22 @@ pub fn run_foreground(cfg: DaemonConfig) -> Result<()> {
                 ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
                 loop {
                     ticker.tick().await;
-                    let ipc_is_idle =
-                        lock_activity(&activity).should_exit_for_idle(Instant::now(), daemon_idle);
-                    if !ipc_is_idle {
+                    let last = match activity.lock() {
+                        Ok(a) => *a,
+                        Err(p) => *p.into_inner(),
+                    };
+                    if last.elapsed() < daemon_idle {
                         continue;
                     }
-                    // IPC liveness (open-connection count + idle window) is already
-                    // enforced above by `should_exit_for_idle`, which reads
-                    // `IpcActivityState` under one lock and returns true only when
-                    // there are zero connections AND the idle interval has elapsed.
-                    // Here we additionally hold the daemon alive while any browser
-                    // is paired or any session is live (design §3.2, M4/M5
-                    // registries).
-                    if !state.browsers.is_empty() || !state.sessions.is_empty() {
+                    // Bridge from M2/M3 (which only knew about connection
+                    // counts) to M4/M5 (browser + session registries):
+                    // hold the daemon alive while any IPC client is
+                    // connected, any browser is paired, or any session
+                    // is live (design §3.2).
+                    if active_ipc_connections.load(Ordering::SeqCst) > 0
+                        || !state.browsers.is_empty()
+                        || !state.sessions.is_empty()
+                    {
                         continue;
                     }
                     info!(
@@ -672,55 +682,10 @@ fn restart_start_args(cfg: &DaemonConfig) -> StartArgs {
     }
 }
 
-#[derive(Debug)]
-struct IpcActivityState {
-    last_activity: Instant,
-    active_connections: usize,
-}
-
-impl IpcActivityState {
-    fn new(now: Instant) -> Self {
-        Self {
-            last_activity: now,
-            active_connections: 0,
-        }
+fn record_activity(activity: &Arc<Mutex<Instant>>) {
+    if let Ok(mut a) = activity.lock() {
+        *a = Instant::now();
     }
-
-    fn touch(&mut self, now: Instant) {
-        self.last_activity = now;
-    }
-
-    fn opened(&mut self, now: Instant) {
-        self.active_connections = self.active_connections.saturating_add(1);
-        self.last_activity = now;
-    }
-
-    fn closed(&mut self, now: Instant) {
-        self.active_connections = self.active_connections.saturating_sub(1);
-        self.last_activity = now;
-    }
-
-    fn should_exit_for_idle(&self, now: Instant, idle: Duration) -> bool {
-        self.active_connections == 0 && now.saturating_duration_since(self.last_activity) >= idle
-    }
-}
-
-fn lock_activity(
-    activity: &Arc<Mutex<IpcActivityState>>,
-) -> std::sync::MutexGuard<'_, IpcActivityState> {
-    activity.lock().unwrap_or_else(|poison| poison.into_inner())
-}
-
-fn record_activity(activity: &Arc<Mutex<IpcActivityState>>) {
-    lock_activity(activity).touch(Instant::now());
-}
-
-fn record_ipc_open(activity: &Arc<Mutex<IpcActivityState>>) {
-    lock_activity(activity).opened(Instant::now());
-}
-
-fn record_ipc_close(activity: &Arc<Mutex<IpcActivityState>>) {
-    lock_activity(activity).closed(Instant::now());
 }
 
 /// Initialise tracing for the daemon: write a daily-rotated file in
@@ -1103,37 +1068,4 @@ mod tests {
         assert_eq!(args.session_idle, Some(Duration::from_secs(11)));
         assert_eq!(args.daemon_idle, Some(Duration::from_secs(22)));
     }
-
-    #[test]
-    fn ipc_close_restarts_the_idle_window_atomically() {
-        let started = Instant::now();
-        let idle = Duration::from_secs(10);
-        let mut activity = IpcActivityState::new(started);
-
-        activity.opened(started);
-        let closed_at = started + Duration::from_secs(30);
-        assert!(
-            !activity.should_exit_for_idle(closed_at, idle),
-            "an open IPC connection must hold the daemon alive"
-        );
-
-        activity.closed(closed_at);
-        assert_eq!(activity.active_connections, 0);
-        assert_eq!(activity.last_activity, closed_at);
-        assert!(!activity.should_exit_for_idle(closed_at, idle));
-        assert!(!activity.should_exit_for_idle(closed_at + idle - Duration::from_millis(1), idle));
-        assert!(activity.should_exit_for_idle(closed_at + idle, idle));
-    }
-
-    #[test]
-    fn ipc_activity_keeps_the_daemon_alive_until_a_full_idle_interval_passes() {
-        let started = Instant::now();
-        let idle = Duration::from_secs(10);
-        let mut activity = IpcActivityState::new(started);
-        let request_at = started + Duration::from_secs(20);
-
-        activity.touch(request_at);
-        assert!(!activity.should_exit_for_idle(request_at + Duration::from_secs(9), idle));
-        assert!(activity.should_exit_for_idle(request_at + idle, idle));
-    }
 }

crates/bsk-cli/src/daemon/state.rs

@@ -16,7 +16,7 @@ use super::start::DaemonConfig;
 use super::ws::WsHandle;
 
 pub const DAEMON_VERSION: &str = env!("CARGO_PKG_VERSION");
-pub const PROTOCOL_VERSION: &str = "1.1";
+pub const PROTOCOL_VERSION: &str = "1.0";
 /// Lowest **protocol** version peers must speak (e.g. `"1.0"`).
 pub const MIN_COMPATIBLE_PROTOCOL: &str = "1.0";
 /// Legacy app-semver floor used only when `HandshakeResult.min_compatible_peer`

crates/bsk-cli/tests/handshake_compat.rs

@@ -108,12 +108,12 @@ async fn send_handshake_with_floors(
 async fn handshake_ok_when_protocol_matches() {
     let (handle, _sock) = spawn_daemon().await;
     let mut ws = open_ws(handle.ws_addr()).await;
-    let resp = send_handshake(&mut ws, "1.1", env!("CARGO_PKG_VERSION")).await;
+    let resp = send_handshake(&mut ws, "1.0", env!("CARGO_PKG_VERSION")).await;
     let result: HandshakeResult = match resp.body {
         ResponseBody::Ok(v) => serde_json::from_value(v).unwrap(),
         ResponseBody::Err(e) => panic!("expected ok handshake, got {e:?}"),
     };
-    assert_eq!(result.protocol_version, "1.1");
+    assert_eq!(result.protocol_version, "1.0");
     assert_eq!(
         result
             .min_compatible_peer
@@ -135,7 +135,7 @@ async fn handshake_ok_when_app_versions_differ_but_protocol_matches() {
     let (handle, _sock) = spawn_daemon().await;
     let mut ws = open_ws(handle.ws_addr()).await;
     let resp =
-        send_handshake_with_floors(&mut ws, "1.1", "9.9.9", Some("0.0.0"), Some("1.1")).await;
+        send_handshake_with_floors(&mut ws, "1.0", "9.9.9", Some("0.0.0"), Some("1.0")).await;
     match resp.body {
         ResponseBody::Ok(_) => {}
         other => panic!("expected ok when protocol matches, got {other:?}"),
@@ -149,10 +149,10 @@ async fn handshake_skew_when_protocol_minor_differs() {
     let mut ws = open_ws(handle.ws_addr()).await;
     let resp = send_handshake_with_floors(
         &mut ws,
-        "1.2",
+        "1.1",
         env!("CARGO_PKG_VERSION"),
         Some("0.0.0"),
-        Some("1.1"),
+        Some("1.0"),
     )
     .await;
     match resp.body {
@@ -210,7 +210,7 @@ async fn handshake_legacy_ext_without_protocol_floor_still_ok() {
     let mut ws = open_ws(handle.ws_addr()).await;
     let resp = send_handshake_with_floors(
         &mut ws,
-        "1.1",
+        "1.0",
         env!("CARGO_PKG_VERSION"),
         Some("0.1.0"),
         None,
@@ -235,7 +235,7 @@ async fn status_surfaces_version_skew_for_skewed_browser() {
         browser_name: "chrome".into(),
         browser_version: "131.0".into(),
         extension_version: "9.9.9".into(),
-        extension_protocol_version: "1.2".into(),
+        extension_protocol_version: "1.1".into(),
         label: "Older".into(),
         sink: bsk::daemon::browsers::BrowserSink { tx },
         pending: Mutex::new(bsk::daemon::browsers::Pending::default()),
@@ -263,8 +263,8 @@ async fn status_surfaces_version_skew_for_skewed_browser() {
         .iter()
         .find(|s| s.instance_id == "skew-only-test")
         .expect("status must list our skew client");
-    assert_eq!(skew.client_protocol_version, "1.2");
-    assert_eq!(skew.server_protocol_version, "1.1");
+    assert_eq!(skew.client_protocol_version, "1.1");
+    assert_eq!(skew.server_protocol_version, "1.0");
     assert_eq!(skew.client_version, "9.9.9");
     let entry = status
         .browsers
@@ -281,7 +281,7 @@ async fn handshake_rejects_when_local_below_peer_min_compatible_protocol() {
     let mut ws = open_ws(handle.ws_addr()).await;
     let resp = send_handshake_with_floors(
         &mut ws,
-        "1.1",
+        "1.0",
         env!("CARGO_PKG_VERSION"),
         Some("0.0.0"),
         Some("99.0.0"),

crates/bsk-cli/tests/record_export_recovery.rs

@@ -1,327 +0,0 @@
-use std::path::{Path, PathBuf};
-use std::sync::Arc;
-use std::sync::atomic::{AtomicUsize, Ordering};
-use std::time::Duration;
-
-use bsk::daemon::info::DaemonInfo;
-use bsk::daemon::paths::BSK_HOME_ENV;
-use bsk::daemon::{self, DaemonConfig};
-use bsk::ipc_client::IpcClient;
-use bsk_protocol::system::{HandshakeParams, HandshakeResult};
-use bsk_protocol::tools::{
-    RecordStopResult, RecordedTrace, RecorderInfo, SessionStartParams, SessionStartResult,
-    StopReason, TraceEntry, TraceStateV3, TraceV3, VOM_FORMAT_VERSION,
-};
-use bsk_protocol::{BrowserPeerInfo, Frame, Method, RequestFrame, ResponseBody, ResponseFrame};
-use futures_util::{SinkExt, StreamExt};
-use serde_json::json;
-use tokio::process::Command;
-use tokio_tungstenite::tungstenite::handshake::client::generate_key;
-use tokio_tungstenite::tungstenite::http::Request;
-use tokio_tungstenite::tungstenite::protocol::Message;
-
-const TEST_EXT_ID: &str = "abcdefghijklmnopabcdefghijklmnop";
-
-type Ws =
-    tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>;
-
-fn bsk_bin() -> PathBuf {
-    PathBuf::from(env!("CARGO_BIN_EXE_bsk"))
-}
-
-async fn connect_extension(addr: std::net::SocketAddr) -> Ws {
-    let origin = format!("chrome-extension://{TEST_EXT_ID}");
-    let request = Request::builder()
-        .method("GET")
-        .uri(format!("ws://{addr}/"))
-        .header("Host", addr.to_string())
-        .header("Upgrade", "websocket")
-        .header("Connection", "Upgrade")
-        .header("Sec-WebSocket-Version", "13")
-        .header("Sec-WebSocket-Key", generate_key())
-        .header("Origin", origin)
-        .body(())
-        .unwrap();
-    tokio_tungstenite::connect_async(request).await.unwrap().0
-}
-
-async fn handshake(ws: &mut Ws) {
-    let request = RequestFrame {
-        id: "handshake".into(),
-        method: Method::SystemHandshake,
-        params: Some(
-            serde_json::to_value(HandshakeParams {
-                client: "browser-skill-extension".into(),
-                version: "0.1.10".parse().unwrap(),
-                protocol_version: "1.1".into(),
-                instance_id: TEST_EXT_ID.into(),
-                browser: BrowserPeerInfo {
-                    name: "chrome".into(),
-                    version: "131.0".into(),
-                },
-                min_compatible_peer: Some("0.1.10".parse().unwrap()),
-                min_compatible_protocol: Some("1.1".into()),
-                label: "Record export recovery test".into(),
-            })
-            .unwrap(),
-        ),
-    };
-    ws.send(Message::Text(serde_json::to_string(&request).unwrap()))
-        .await
-        .unwrap();
-    let Message::Text(response) = ws.next().await.unwrap().unwrap() else {
-        panic!("expected text handshake response");
-    };
-    let response: ResponseFrame = serde_json::from_str(&response).unwrap();
-    let ResponseBody::Ok(value) = response.body else {
-        panic!("handshake failed");
-    };
-    let _: HandshakeResult = serde_json::from_value(value).unwrap();
-}
-
-fn sample_trace() -> TraceV3 {
-    TraceV3 {
-        version: 3,
-        purpose: Some("export recovery".into()),
-        started_at: Some("2026-08-12T10:00:00Z".into()),
-        recorded_at: "2026-08-12T10:01:00Z".into(),
-        stopped_by: StopReason::CliStop,
-        entry: TraceEntry {
-            start_url: "https://example.com/".into(),
-        },
-        recorder: RecorderInfo {
-            bsk: "0.1.10".into(),
-            vom: VOM_FORMAT_VERSION,
-        },
-        states: vec![TraceStateV3 {
-            id: "s1".into(),
-            url: "https://example.com/".into(),
-            title: Some("Example".into()),
-            body: "@vom 1\nL1 page".into(),
-            truncated: false,
-        }],
-        steps: vec![],
-    }
-}
-
-fn run_extension(
-    mut ws: Ws,
-    record_stop_calls: Arc<AtomicUsize>,
-    session_stop_calls: Arc<AtomicUsize>,
-) {
-    tokio::spawn(async move {
-        while let Some(Ok(Message::Text(text))) = ws.next().await {
-            let Ok(Frame::Request(request)) = serde_json::from_str::<Frame>(&text) else {
-                continue;
-            };
-            let body = match request.method {
-                Method::ToolSessionStart => {
-                    let _: SessionStartParams =
-                        serde_json::from_value(request.params.clone().unwrap()).unwrap();
-                    ResponseBody::Ok(
-                        serde_json::to_value(SessionStartResult {
-                            agent_window_id: Some(100),
-                        })
-                        .unwrap(),
-                    )
-                }
-                Method::ToolRecordStop => {
-                    record_stop_calls.fetch_add(1, Ordering::SeqCst);
-                    ResponseBody::Ok(
-                        serde_json::to_value(RecordStopResult {
-                            trace: RecordedTrace::V3(sample_trace()),
-                        })
-                        .unwrap(),
-                    )
-                }
-                Method::ToolSessionStop => {
-                    session_stop_calls.fetch_add(1, Ordering::SeqCst);
-                    ResponseBody::Ok(json!({}))
-                }
-                _ => ResponseBody::Err(bsk_protocol::RpcError {
-                    code: bsk_protocol::ErrorCode::ProtocolError,
-                    message: format!("unexpected method {:?}", request.method),
-                    data: None,
-                }),
-            };
-            let response = ResponseFrame {
-                id: request.id,
-                body,
-            };
-            ws.send(Message::Text(serde_json::to_string(&response).unwrap()))
-                .await
-                .unwrap();
-        }
-    });
-}
-
-async fn start_session(sock: &Path) -> String {
-    #[derive(serde::Deserialize)]
-    struct StartResult {
-        session_id: String,
-    }
-
-    let mut client = IpcClient::connect(sock).await.unwrap();
-    client
-        .call::<(), StartResult>(
-            "session-start",
-            Method::SessionStart,
-            None,
-            Duration::from_secs(5),
-        )
-        .await
-        .unwrap()
-        .unwrap()
-        .session_id
-}
-
-fn write_record_session(home: &Path, session_id: &str) {
-    std::fs::create_dir_all(home).unwrap();
-    std::fs::write(
-        home.join("record-session.json"),
-        format!("{{\"session_id\":\"{session_id}\",\"started_at\":\"1\"}}\n"),
-    )
-    .unwrap();
-}
-
-async fn run_record_stop(home: &Path, output: &Path) -> std::process::Output {
-    Command::new(bsk_bin())
-        .arg("record")
-        .arg("stop")
-        .arg("--output")
-        .arg(output)
-        .env(BSK_HOME_ENV, home)
-        .output()
-        .await
-        .unwrap()
-}
-
-async fn setup_daemon(temp: &Path) -> (bsk::daemon::DaemonHandle, PathBuf, PathBuf) {
-    let home = temp.join("bsk-home");
-    let sock = temp.join("daemon.sock");
-    let daemon = daemon::run(DaemonConfig::new(0), Some(sock.clone()))
-        .await
-        .unwrap();
-    bsk::daemon::info::write_to_path(
-        &DaemonInfo::now(
-            std::process::id(),
-            sock.clone(),
-            daemon.ws_addr().port(),
-            env!("CARGO_PKG_VERSION"),
-        ),
-        &home.join("daemon.json"),
-    )
-    .unwrap();
-    (daemon, home, sock)
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn existing_trace_json_file_is_rejected_before_record_stop() {
-    let temp = tempfile::Builder::new()
-        .prefix("bsk-record-json-")
-        .tempdir()
-        .unwrap();
-    let (daemon, home, sock) = setup_daemon(temp.path()).await;
-    let output = temp.path().join("trace.json");
-    std::fs::write(&output, "{}\n").unwrap();
-
-    let mut extension = connect_extension(daemon.ws_addr()).await;
-    handshake(&mut extension).await;
-    let record_stop_calls = Arc::new(AtomicUsize::new(0));
-    let session_stop_calls = Arc::new(AtomicUsize::new(0));
-    run_extension(
-        extension,
-        Arc::clone(&record_stop_calls),
-        Arc::clone(&session_stop_calls),
-    );
-
-    let session_id = start_session(&sock).await;
-    write_record_session(&home, &session_id);
-
-    let first = run_record_stop(&home, &output).await;
-    let stderr = String::from_utf8_lossy(&first.stderr);
-    assert!(
-        !first.status.success(),
-        "legacy JSON --output should fail: {stderr}"
-    );
-    assert!(
-        stderr.contains("JSON file") || stderr.contains("bundle directory"),
-        "{stderr}"
-    );
-    let state: serde_json::Value =
-        serde_json::from_str(&std::fs::read_to_string(home.join("record-session.json")).unwrap())
-            .unwrap();
-    assert_eq!(state["session_id"], session_id);
-    assert_eq!(
-        record_stop_calls.load(Ordering::SeqCst),
-        0,
-        "existing trace.json must be rejected before the extension returns the Trace"
-    );
-    assert_eq!(session_stop_calls.load(Ordering::SeqCst), 0);
-    assert_eq!(std::fs::read_to_string(&output).unwrap(), "{}\n");
-
-    daemon.shutdown().await;
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn failed_bundle_export_can_be_recovered() {
-    let temp = tempfile::Builder::new()
-        .prefix("bsk-record-recov-")
-        .tempdir()
-        .unwrap();
-    let (daemon, home, sock) = setup_daemon(temp.path()).await;
-    let output = temp.path().join("trace");
-    std::fs::create_dir_all(&output).unwrap();
-    std::fs::write(output.join("states"), "not a directory\n").unwrap();
-
-    let mut extension = connect_extension(daemon.ws_addr()).await;
-    handshake(&mut extension).await;
-    let record_stop_calls = Arc::new(AtomicUsize::new(0));
-    let session_stop_calls = Arc::new(AtomicUsize::new(0));
-    run_extension(
-        extension,
-        Arc::clone(&record_stop_calls),
-        Arc::clone(&session_stop_calls),
-    );
-
-    let session_id = start_session(&sock).await;
-    write_record_session(&home, &session_id);
-
-    let first = run_record_stop(&home, &output).await;
-    let stderr = String::from_utf8_lossy(&first.stderr);
-    assert!(
-        !first.status.success(),
-        "blocked states path should fail export: {stderr}"
-    );
-    assert!(
-        home.join("record-recovery.json").exists(),
-        "completed Trace must be saved before the failed export"
-    );
-    assert!(
-        !home.join("record-session.json").exists(),
-        "session state is cleared after the extension returns the Trace"
-    );
-    assert_eq!(record_stop_calls.load(Ordering::SeqCst), 1);
-    assert_eq!(session_stop_calls.load(Ordering::SeqCst), 1);
-
-    std::fs::remove_file(output.join("states")).unwrap();
-    let second = run_record_stop(&home, &output).await;
-    assert!(
-        second.status.success(),
-        "recovery export failed: {}",
-        String::from_utf8_lossy(&second.stderr)
-    );
-    assert_eq!(
-        record_stop_calls.load(Ordering::SeqCst),
-        1,
-        "recovery must not call the extension again"
-    );
-    assert!(output.join("trace.json").exists());
-    assert!(output.join("states/s1.txt").exists());
-    assert!(
-        !home.join("record-recovery.json").exists(),
-        "successful export must delete recovery data"
-    );
-
-    daemon.shutdown().await;
-}

crates/bsk-cli/tests/record_stop_retry.rs

@@ -1,271 +0,0 @@
-use std::path::{Path, PathBuf};
-use std::sync::Arc;
-use std::sync::atomic::{AtomicUsize, Ordering};
-use std::time::Duration;
-
-use bsk::cli::record_state;
-use bsk::daemon::info::DaemonInfo;
-use bsk::daemon::paths::BSK_HOME_ENV;
-use bsk::daemon::{self, DaemonConfig};
-use bsk::ipc_client::IpcClient;
-use bsk_protocol::system::{HandshakeParams, HandshakeResult};
-use bsk_protocol::tools::{
-    RecordStopResult, RecordedTrace, RecorderInfo, SessionStartParams, SessionStartResult,
-    StopReason, TraceEntry, TraceStateV3, TraceV3, VOM_FORMAT_VERSION,
-};
-use bsk_protocol::{
-    BrowserPeerInfo, ErrorCode, Frame, Method, RequestFrame, ResponseBody, ResponseFrame, RpcError,
-};
-use futures_util::{SinkExt, StreamExt};
-use serde_json::json;
-use tokio::process::Command;
-use tokio_tungstenite::tungstenite::handshake::client::generate_key;
-use tokio_tungstenite::tungstenite::http::Request;
-use tokio_tungstenite::tungstenite::protocol::Message;
-
-const TEST_EXT_ID: &str = "abcdefghijklmnopabcdefghijklmnop";
-
-type Ws =
-    tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>;
-
-fn bsk_bin() -> PathBuf {
-    PathBuf::from(env!("CARGO_BIN_EXE_bsk"))
-}
-
-async fn connect_extension(addr: std::net::SocketAddr) -> Ws {
-    let origin = format!("chrome-extension://{TEST_EXT_ID}");
-    let request = Request::builder()
-        .method("GET")
-        .uri(format!("ws://{addr}/"))
-        .header("Host", addr.to_string())
-        .header("Upgrade", "websocket")
-        .header("Connection", "Upgrade")
-        .header("Sec-WebSocket-Version", "13")
-        .header("Sec-WebSocket-Key", generate_key())
-        .header("Origin", origin)
-        .body(())
-        .unwrap();
-    tokio_tungstenite::connect_async(request).await.unwrap().0
-}
-
-async fn handshake(ws: &mut Ws) {
-    let request = RequestFrame {
-        id: "handshake".into(),
-        method: Method::SystemHandshake,
-        params: Some(
-            serde_json::to_value(HandshakeParams {
-                client: "browser-skill-extension".into(),
-                version: "0.1.10".parse().unwrap(),
-                protocol_version: "1.1".into(),
-                instance_id: TEST_EXT_ID.into(),
-                browser: BrowserPeerInfo {
-                    name: "chrome".into(),
-                    version: "131.0".into(),
-                },
-                min_compatible_peer: Some("0.1.10".parse().unwrap()),
-                min_compatible_protocol: Some("1.1".into()),
-                label: "Record stop retry test".into(),
-            })
-            .unwrap(),
-        ),
-    };
-    ws.send(Message::Text(serde_json::to_string(&request).unwrap()))
-        .await
-        .unwrap();
-    let Message::Text(response) = ws.next().await.unwrap().unwrap() else {
-        panic!("expected text handshake response");
-    };
-    let response: ResponseFrame = serde_json::from_str(&response).unwrap();
-    let ResponseBody::Ok(value) = response.body else {
-        panic!("handshake failed");
-    };
-    let _: HandshakeResult = serde_json::from_value(value).unwrap();
-}
-
-fn sample_trace() -> TraceV3 {
-    TraceV3 {
-        version: 3,
-        purpose: Some("retry record stop".into()),
-        started_at: Some("2026-08-12T10:00:00Z".into()),
-        recorded_at: "2026-08-12T10:01:00Z".into(),
-        stopped_by: StopReason::CliStop,
-        entry: TraceEntry {
-            start_url: "https://example.com/".into(),
-        },
-        recorder: RecorderInfo {
-            bsk: "0.1.10".into(),
-            vom: VOM_FORMAT_VERSION,
-        },
-        states: vec![TraceStateV3 {
-            id: "s1".into(),
-            url: "https://example.com/".into(),
-            title: Some("Example".into()),
-            body: "@vom 1\nL1 page".into(),
-            truncated: false,
-        }],
-        steps: vec![],
-    }
-}
-
-fn run_extension(
-    mut ws: Ws,
-    record_stop_calls: Arc<AtomicUsize>,
-    session_stop_calls: Arc<AtomicUsize>,
-) {
-    tokio::spawn(async move {
-        while let Some(Ok(Message::Text(text))) = ws.next().await {
-            let Ok(Frame::Request(request)) = serde_json::from_str::<Frame>(&text) else {
-                continue;
-            };
-            let body = match request.method {
-                Method::ToolSessionStart => {
-                    let _: SessionStartParams =
-                        serde_json::from_value(request.params.clone().unwrap()).unwrap();
-                    ResponseBody::Ok(
-                        serde_json::to_value(SessionStartResult {
-                            agent_window_id: Some(100),
-                        })
-                        .unwrap(),
-                    )
-                }
-                Method::ToolRecordStop => {
-                    if record_stop_calls.fetch_add(1, Ordering::SeqCst) == 0 {
-                        ResponseBody::Err(RpcError {
-                            code: ErrorCode::ProtocolError,
-                            message: "recording remains active; retry record stop".into(),
-                            data: Some(json!({ "recording": true, "retryable": true })),
-                        })
-                    } else {
-                        ResponseBody::Ok(
-                            serde_json::to_value(RecordStopResult {
-                                trace: RecordedTrace::V3(sample_trace()),
-                            })
-                            .unwrap(),
-                        )
-                    }
-                }
-                Method::ToolSessionStop => {
-                    session_stop_calls.fetch_add(1, Ordering::SeqCst);
-                    ResponseBody::Ok(json!({}))
-                }
-                _ => ResponseBody::Err(RpcError {
-                    code: ErrorCode::ProtocolError,
-                    message: format!("unexpected method {:?}", request.method),
-                    data: None,
-                }),
-            };
-            let response = ResponseFrame {
-                id: request.id,
-                body,
-            };
-            ws.send(Message::Text(serde_json::to_string(&response).unwrap()))
-                .await
-                .unwrap();
-        }
-    });
-}
-
-async fn start_session(sock: &Path) -> String {
-    #[derive(serde::Deserialize)]
-    struct StartResult {
-        session_id: String,
-    }
-
-    let mut client = IpcClient::connect(sock).await.unwrap();
-    client
-        .call::<(), StartResult>(
-            "session-start",
-            Method::SessionStart,
-            None,
-            Duration::from_secs(5),
-        )
-        .await
-        .unwrap()
-        .unwrap()
-        .session_id
-}
-
-async fn run_record_stop(home: &Path, output: &Path) -> std::process::Output {
-    Command::new(bsk_bin())
-        .arg("record")
-        .arg("stop")
-        .arg("--output")
-        .arg(output)
-        .env(BSK_HOME_ENV, home)
-        .output()
-        .await
-        .unwrap()
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn failed_record_stop_keeps_state_and_session_for_retry() {
-    // Keep the Unix-domain socket below macOS's SUN_LEN even from a deep worktree.
-    let temp = tempfile::Builder::new()
-        .prefix("bsk-record-stop-")
-        .tempdir()
-        .unwrap();
-    let home = temp.path().join("bsk-home");
-    let sock = temp.path().join("daemon.sock");
-    let output = temp.path().join("trace");
-
-    let daemon = daemon::run(DaemonConfig::new(0), Some(sock.clone()))
-        .await
-        .unwrap();
-    bsk::daemon::info::write_to_path(
-        &DaemonInfo::now(
-            std::process::id(),
-            sock.clone(),
-            daemon.ws_addr().port(),
-            env!("CARGO_PKG_VERSION"),
-        ),
-        &home.join("daemon.json"),
-    )
-    .unwrap();
-
-    let mut extension = connect_extension(daemon.ws_addr()).await;
-    handshake(&mut extension).await;
-    let record_stop_calls = Arc::new(AtomicUsize::new(0));
-    let session_stop_calls = Arc::new(AtomicUsize::new(0));
-    run_extension(
-        extension,
-        Arc::clone(&record_stop_calls),
-        Arc::clone(&session_stop_calls),
-    );
-
-    let session_id = start_session(&sock).await;
-    unsafe {
-        std::env::set_var(BSK_HOME_ENV, &home);
-    }
-    record_state::write(&session_id).unwrap();
-
-    let first = run_record_stop(&home, &output).await;
-    assert!(
-        !first.status.success(),
-        "first stop unexpectedly succeeded: {}",
-        String::from_utf8_lossy(&first.stdout)
-    );
-    assert_eq!(record_state::read().unwrap().session_id, session_id);
-    assert_eq!(record_stop_calls.load(Ordering::SeqCst), 1);
-    assert_eq!(
-        session_stop_calls.load(Ordering::SeqCst),
-        0,
-        "failed record stop must leave the session active"
-    );
-
-    let second = run_record_stop(&home, &output).await;
-    assert!(
-        second.status.success(),
-        "retry failed: {}",
-        String::from_utf8_lossy(&second.stderr)
-    );
-    assert!(record_state::read().is_err());
-    assert_eq!(record_stop_calls.load(Ordering::SeqCst), 2);
-    assert_eq!(session_stop_calls.load(Ordering::SeqCst), 1);
-    assert!(output.join("trace.json").exists());
-    assert!(output.join("states/s1.txt").exists());
-
-    unsafe {
-        std::env::remove_var(BSK_HOME_ENV);
-    }
-    daemon.shutdown().await;
-}

crates/bsk-cli/tests/status_cmd.rs

@@ -61,7 +61,7 @@ fn bsk_status_json_returns_structured_payload() {
 
     assert!(parsed["pid"].as_u64().unwrap() > 0);
     assert!(!parsed["daemon_version"].as_str().unwrap().is_empty());
-    assert_eq!(parsed["protocol_version"], "1.1");
+    assert_eq!(parsed["protocol_version"], "1.0");
     assert!(parsed["sock_path"].as_str().is_some());
     assert_eq!(parsed["browsers"], serde_json::json!([]));
     assert_eq!(parsed["sessions"], serde_json::json!([]));

crates/bsk-cli/tests/ws_handshake.rs

@@ -53,7 +53,7 @@ pub async fn send_handshake(
     let params = HandshakeParams {
         client: "browser-skill-extension".into(),
         version: "0.1.0-dev.0".parse().unwrap(),
-        protocol_version: "1.1".into(),
+        protocol_version: "1.0".into(),
         instance_id: instance_id.into(),
         browser: BrowserPeerInfo {
             name: "chrome".into(),
@@ -91,7 +91,7 @@ async fn ws_handshake_registers_browser_in_state() {
     let mut ws = connect_ext(handle.ws_addr(), &origin).await;
     let result = send_handshake(&mut ws, TEST_EXT_ID).await;
     assert_eq!(result.server, "browser-skill-daemon");
-    assert_eq!(result.protocol_version, "1.1");
+    assert_eq!(result.protocol_version, "1.0");
 
     let state = handle.state();
     let browsers = state.browsers.snapshot();

crates/bsk-protocol/schema/tool_record_await_result.json

@@ -480,36 +480,6 @@
             }
           }
         },
-        {
-          "description": "Fields shared by every step variant (flattened in JSON).",
-          "type": "object",
-          "required": [
-            "id",
-            "op",
-            "result",
-            "state"
-          ],
-          "properties": {
-            "id": {
-              "type": "integer",
-              "format": "uint32",
-              "minimum": 0.0
-            },
-            "op": {
-              "type": "string",
-              "enum": [
-                "switch_tab"
-              ]
-            },
-            "result": {
-              "$ref": "#/definitions/StepResultV3"
-            },
-            "state": {
-              "description": "Observation id immediately before this action.",
-              "type": "string"
-            }
-          }
-        },
         {
           "description": "Fields shared by every step variant (flattened in JSON).",
           "type": "object",

crates/bsk-protocol/schema/tool_record_start_params.json

@@ -6,36 +6,15 @@
     "session_id"
   ],
   "properties": {
-    "max_page_tokens": {
-      "type": [
-        "integer",
-        "null"
-      ],
-      "format": "uint32",
-      "minimum": 0.0
-    },
     "purpose": {
       "type": [
         "string",
         "null"
       ]
     },
-    "redact_values": {
-      "type": [
-        "boolean",
-        "null"
-      ]
-    },
     "session_id": {
       "type": "string"
     },
-    "supports_tab_switch_steps": {
-      "description": "Client can decode the v3 `switch_tab` step variant.",
-      "type": [
-        "boolean",
-        "null"
-      ]
-    },
     "tab_id": {
       "type": [
         "integer",
@@ -43,15 +22,6 @@
       ],
       "format": "int64"
     },
-    "trace_version": {
-      "description": "Desired trace export format. Omitted means v2; `3` requests v3.",
-      "type": [
-        "integer",
-        "null"
-      ],
-      "format": "uint32",
-      "minimum": 0.0
-    },
     "url": {
       "type": [
         "string",

crates/bsk-protocol/schema/tool_record_stop_result.json

@@ -480,36 +480,6 @@
             }
           }
         },
-        {
-          "description": "Fields shared by every step variant (flattened in JSON).",
-          "type": "object",
-          "required": [
-            "id",
-            "op",
-            "result",
-            "state"
-          ],
-          "properties": {
-            "id": {
-              "type": "integer",
-              "format": "uint32",
-              "minimum": 0.0
-            },
-            "op": {
-              "type": "string",
-              "enum": [
-                "switch_tab"
-              ]
-            },
-            "result": {
-              "$ref": "#/definitions/StepResultV3"
-            },
-            "state": {
-              "description": "Observation id immediately before this action.",
-              "type": "string"
-            }
-          }
-        },
         {
           "description": "Fields shared by every step variant (flattened in JSON).",
           "type": "object",

crates/bsk-protocol/schema/trace.json

@@ -469,36 +469,6 @@
             }
           }
         },
-        {
-          "description": "Fields shared by every step variant (flattened in JSON).",
-          "type": "object",
-          "required": [
-            "id",
-            "op",
-            "result",
-            "state"
-          ],
-          "properties": {
-            "id": {
-              "type": "integer",
-              "format": "uint32",
-              "minimum": 0.0
-            },
-            "op": {
-              "type": "string",
-              "enum": [
-                "switch_tab"
-              ]
-            },
-            "result": {
-              "$ref": "#/definitions/StepResultV3"
-            },
-            "state": {
-              "description": "Observation id immediately before this action.",
-              "type": "string"
-            }
-          }
-        },
         {
           "description": "Fields shared by every step variant (flattened in JSON).",
           "type": "object",

crates/bsk-protocol/schema/trace_step.json

@@ -431,36 +431,6 @@
             }
           }
         },
-        {
-          "description": "Fields shared by every step variant (flattened in JSON).",
-          "type": "object",
-          "required": [
-            "id",
-            "op",
-            "result",
-            "state"
-          ],
-          "properties": {
-            "id": {
-              "type": "integer",
-              "format": "uint32",
-              "minimum": 0.0
-            },
-            "op": {
-              "type": "string",
-              "enum": [
-                "switch_tab"
-              ]
-            },
-            "result": {
-              "$ref": "#/definitions/StepResultV3"
-            },
-            "state": {
-              "description": "Observation id immediately before this action.",
-              "type": "string"
-            }
-          }
-        },
         {
           "description": "Fields shared by every step variant (flattened in JSON).",
           "type": "object",

crates/bsk-protocol/schema/trace_step_v3.json

@@ -41,36 +41,6 @@
         }
       }
     },
-    {
-      "description": "Fields shared by every step variant (flattened in JSON).",
-      "type": "object",
-      "required": [
-        "id",
-        "op",
-        "result",
-        "state"
-      ],
-      "properties": {
-        "id": {
-          "type": "integer",
-          "format": "uint32",
-          "minimum": 0.0
-        },
-        "op": {
-          "type": "string",
-          "enum": [
-            "switch_tab"
-          ]
-        },
-        "result": {
-          "$ref": "#/definitions/StepResultV3"
-        },
-        "state": {
-          "description": "Observation id immediately before this action.",
-          "type": "string"
-        }
-      }
-    },
     {
       "description": "Fields shared by every step variant (flattened in JSON).",
       "type": "object",

crates/bsk-protocol/schema/trace_v3.json

@@ -173,36 +173,6 @@
             }
           }
         },
-        {
-          "description": "Fields shared by every step variant (flattened in JSON).",
-          "type": "object",
-          "required": [
-            "id",
-            "op",
-            "result",
-            "state"
-          ],
-          "properties": {
-            "id": {
-              "type": "integer",
-              "format": "uint32",
-              "minimum": 0.0
-            },
-            "op": {
-              "type": "string",
-              "enum": [
-                "switch_tab"
-              ]
-            },
-            "result": {
-              "$ref": "#/definitions/StepResultV3"
-            },
-            "state": {
-              "description": "Observation id immediately before this action.",
-              "type": "string"
-            }
-          }
-        },
         {
           "description": "Fields shared by every step variant (flattened in JSON).",
           "type": "object",

crates/bsk-protocol/src/tools/record.rs

@@ -32,16 +32,6 @@ pub struct RecordStartParams {
     pub url: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub purpose: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub max_page_tokens: Option<u32>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub redact_values: Option<bool>,
-    /// Desired trace export format. Omitted means v2; `3` requests v3.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub trace_version: Option<u32>,
-    /// Client can decode the v3 `switch_tab` step variant.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub supports_tab_switch_steps: Option<bool>,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
@@ -277,249 +267,6 @@ mod tests {
     use super::*;
     use serde_json::json;
 
-    fn sample_common(id: u32, state: &str, result_state: &str) -> StepCommonV3 {
-        StepCommonV3 {
-            id,
-            state: state.into(),
-            result: StepResultV3 {
-                state: result_state.into(),
-            },
-        }
-    }
-
-    fn sample_target() -> TargetDescriptorV3 {
-        TargetDescriptorV3 {
-            element_ref: Some("e21".into()),
-            role: Some("button".into()),
-            name: Some("发布".into()),
-            ctx: Some("金桔柠檬 6 号".into()),
-            unmatched: false,
-        }
-    }
-
-    fn sample_trace() -> TraceV3 {
-        TraceV3 {
-            version: TRACE_VERSION_V3,
-            purpose: Some("把草稿商品发布上架".into()),
-            started_at: Some("2026-08-10T02:10:41.080Z".into()),
-            recorded_at: "2026-08-10T02:12:55.360Z".into(),
-            stopped_by: StopReason::UserFinish,
-            entry: TraceEntry {
-                start_url: "https://example.com/".into(),
-            },
-            recorder: RecorderInfo {
-                bsk: "0.1.10".into(),
-                vom: VOM_FORMAT_VERSION,
-            },
-            states: vec![
-                TraceStateV3 {
-                    id: "s1".into(),
-                    url: "https://example.com/".into(),
-                    title: Some("Example Domain".into()),
-                    body: "@vom 1\nRootWebArea \"Example Domain\"".into(),
-                    truncated: false,
-                },
-                TraceStateV3 {
-                    id: "s2".into(),
-                    url: "https://shop.example.com/products?status=draft".into(),
-                    title: Some("商品管理".into()),
-                    body: "@vom 1\nRootWebArea \"商品管理\"".into(),
-                    truncated: false,
-                },
-            ],
-            steps: vec![
-                StepV3::Navigate {
-                    common: sample_common(1, "s1", "s2"),
-                    to: "https://shop.example.com/products?status=draft".into(),
-                    cause: NavigationCause::UserTyped,
-                },
-                StepV3::Fill {
-                    common: sample_common(2, "s2", "s2"),
-                    target: TargetDescriptorV3 {
-                        element_ref: Some("e12".into()),
-                        role: Some("textbox".into()),
-                        name: Some("搜索商品".into()),
-                        ctx: None,
-                        unmatched: false,
-                    },
-                    value: "金桔柠檬".into(),
-                    commit: FillCommit::Enter,
-                    redacted: false,
-                },
-                StepV3::Click {
-                    common: sample_common(3, "s2", "s2"),
-                    target: sample_target(),
-                },
-            ],
-        }
-    }
-
-    #[test]
-    fn step_click_round_trips() {
-        let step = StepV3::Click {
-            common: sample_common(1, "s1", "s2"),
-            target: sample_target(),
-        };
-        let v = serde_json::to_value(&step).unwrap();
-        assert_eq!(v.get("op").and_then(|v| v.as_str()), Some("click"));
-        assert_eq!(v.get("state").and_then(|v| v.as_str()), Some("s1"));
-        assert_eq!(v["result"]["state"], "s2");
-        assert_eq!(v["target"]["ref"], "e21");
-        let round: StepV3 = serde_json::from_value(v).unwrap();
-        assert_eq!(round, step);
-    }
-
-    #[test]
-    fn step_fill_with_commit_round_trips() {
-        let step = StepV3::Fill {
-            common: sample_common(2, "s2", "s3"),
-            target: TargetDescriptorV3 {
-                element_ref: Some("e12".into()),
-                role: Some("textbox".into()),
-                name: Some("搜索商品".into()),
-                ctx: None,
-                unmatched: false,
-            },
-            value: "browser skill".into(),
-            commit: FillCommit::Enter,
-            redacted: false,
-        };
-        let v = serde_json::to_value(&step).unwrap();
-        assert_eq!(v["op"], "fill");
-        assert_eq!(v["commit"], "enter");
-        assert!(v.get("redacted").is_none());
-        let round: StepV3 = serde_json::from_value(v).unwrap();
-        assert_eq!(round, step);
-    }
-
-    #[test]
-    fn step_fill_password_is_redacted() {
-        let step = StepV3::Fill {
-            common: sample_common(1, "s1", "s1"),
-            target: TargetDescriptorV3 {
-                element_ref: Some("e3".into()),
-                role: Some("textbox".into()),
-                name: Some("密码".into()),
-                ctx: None,
-                unmatched: false,
-            },
-            value: "***".into(),
-            commit: FillCommit::Blur,
-            redacted: true,
-        };
-        let v = serde_json::to_value(&step).unwrap();
-        assert_eq!(v["value"], "***");
-        assert_eq!(v["redacted"], true);
-    }
-
-    #[test]
-    fn step_navigate_with_cause_round_trips() {
-        let step = StepV3::Navigate {
-            common: sample_common(1, "s1", "s2"),
-            to: "https://example.com".into(),
-            cause: NavigationCause::UserTyped,
-        };
-        let v = serde_json::to_value(&step).unwrap();
-        assert_eq!(v["op"], "navigate");
-        assert_eq!(v["cause"], "user_typed");
-        let round: StepV3 = serde_json::from_value(v).unwrap();
-        assert_eq!(round, step);
-    }
-
-    #[test]
-    fn step_switch_tab_round_trips() {
-        let step = StepV3::SwitchTab {
-            common: sample_common(2, "s2", "s5"),
-        };
-        let v = serde_json::to_value(&step).unwrap();
-        assert_eq!(v["op"], "switch_tab");
-        assert_eq!(v["state"], "s2");
-        assert_eq!(v["result"]["state"], "s5");
-        let round: StepV3 = serde_json::from_value(v).unwrap();
-        assert_eq!(round, step);
-    }
-
-    #[test]
-    fn trace_v3_round_trips() {
-        let trace = sample_trace();
-        let v = serde_json::to_value(&trace).unwrap();
-        assert_eq!(v.get("version").and_then(|v| v.as_u64()), Some(3));
-        assert!(v.get("pages").is_none());
-        assert_eq!(v["recorder"]["vom"], 1);
-        assert_eq!(v["states"].as_array().unwrap().len(), 2);
-        let round: TraceV3 = serde_json::from_value(v).unwrap();
-        assert_eq!(round, trace);
-    }
-
-    #[test]
-    fn default_fields_are_omitted() {
-        let step = StepV3::Click {
-            common: sample_common(1, "s1", "s1"),
-            target: TargetDescriptorV3 {
-                element_ref: Some("e1".into()),
-                role: Some("button".into()),
-                name: Some("OK".into()),
-                ctx: None,
-                unmatched: false,
-            },
-        };
-        let v = serde_json::to_value(&step).unwrap();
-        assert!(v.get("unmatched").is_none());
-        assert!(v["target"].get("ctx").is_none());
-        assert!(v["target"].get("unmatched").is_none());
-    }
-
-    #[test]
-    fn record_start_trace_options_are_explicit_and_optional() {
-        let legacy = RecordStartParams {
-            session_id: "session".into(),
-            tab_id: None,
-            url: None,
-            purpose: None,
-            max_page_tokens: None,
-            redact_values: None,
-            trace_version: None,
-            supports_tab_switch_steps: None,
-        };
-        let legacy_value = serde_json::to_value(legacy).unwrap();
-        assert!(legacy_value.get("trace_version").is_none());
-        assert!(legacy_value.get("max_page_tokens").is_none());
-        assert!(legacy_value.get("supports_tab_switch_steps").is_none());
-
-        let v3 = RecordStartParams {
-            session_id: "session".into(),
-            tab_id: None,
-            url: None,
-            purpose: None,
-            max_page_tokens: Some(4_000),
-            redact_values: Some(true),
-            trace_version: Some(TRACE_VERSION_V3),
-            supports_tab_switch_steps: Some(true),
-        };
-        let v3_value = serde_json::to_value(v3).unwrap();
-        assert_eq!(v3_value["trace_version"], TRACE_VERSION_V3);
-        assert_eq!(v3_value["max_page_tokens"], 4_000);
-        assert_eq!(v3_value["redact_values"], true);
-        assert_eq!(v3_value["supports_tab_switch_steps"], true);
-    }
-
-    #[test]
-    fn unmatched_target_serializes_flag() {
-        let step = StepV3::Click {
-            common: sample_common(1, "s1", "s2"),
-            target: TargetDescriptorV3 {
-                element_ref: None,
-                role: Some("button".into()),
-                name: Some("发布".into()),
-                ctx: None,
-                unmatched: true,
-            },
-        };
-        let v = serde_json::to_value(&step).unwrap();
-        assert_eq!(v["target"]["unmatched"], true);
-        assert!(v["target"].get("ref").is_none());
-    }
-
     #[test]
     fn recorded_trace_classifies_v2_and_v3() {
         let v2 = json!({
@@ -705,43 +452,4 @@ mod tests {
         assert!(schema["definitions"].get("StepV2").is_some());
         assert!(schema["definitions"].get("StepV3").is_some());
     }
-
-    #[test]
-    fn extension_trace_deserializes() {
-        let v = json!({
-            "version": 3,
-            "recorded_at": "2026-07-21T08:00:00Z",
-            "started_at": "2026-07-21T07:59:00Z",
-            "purpose": "demo",
-            "stopped_by": "user_finish",
-            "entry": { "start_url": "https://example.com/editor" },
-            "recorder": { "bsk": "0.1.10", "vom": 1 },
-            "states": [
-                { "id": "s1", "url": "https://example.com/editor", "body": "@vom 1" },
-                { "id": "s2", "url": "https://example.com/p/99", "body": "@vom 1" }
-            ],
-            "steps": [
-                {
-                    "op": "fill",
-                    "id": 1,
-                    "state": "s1",
-                    "result": { "state": "s1" },
-                    "target": { "ref": "e1", "role": "textbox", "name": "标题" },
-                    "value": "hello",
-                    "commit": "blur"
-                },
-                {
-                    "op": "click",
-                    "id": 2,
-                    "state": "s1",
-                    "result": { "state": "s2" },
-                    "target": { "ref": "e2", "role": "button", "name": "发布" }
-                }
-            ]
-        });
-        let trace: TraceV3 = serde_json::from_value(v).unwrap();
-        assert_eq!(trace.version, 3);
-        assert_eq!(trace.states.len(), 2);
-        assert_eq!(trace.steps.len(), 2);
-    }
 }

crates/bsk-protocol/src/tools/record_v3.rs

@@ -126,10 +126,6 @@ pub enum StepV3 {
         to: String,
         cause: NavigationCause,
     },
-    SwitchTab {
-        #[serde(flatten)]
-        common: StepCommonV3,
-    },
     Click {
         #[serde(flatten)]
         common: StepCommonV3,
@@ -344,19 +340,6 @@ mod tests {
         assert_eq!(round, step);
     }
 
-    #[test]
-    fn step_switch_tab_round_trips() {
-        let step = StepV3::SwitchTab {
-            common: sample_common(2, "s2", "s5"),
-        };
-        let v = serde_json::to_value(&step).unwrap();
-        assert_eq!(v["op"], "switch_tab");
-        assert_eq!(v["state"], "s2");
-        assert_eq!(v["result"]["state"], "s5");
-        let round: StepV3 = serde_json::from_value(v).unwrap();
-        assert_eq!(round, step);
-    }
-
     #[test]
     fn trace_v3_round_trips() {
         let trace = sample_trace();

packages/dsh-plugin-browserskill/src/archive-cleanup.ts

@@ -1,108 +0,0 @@
-/**
- * Archive-triggered bsk session cleanup. DSH conversation archival writes
- * the workspace registry's durable global state, which the storage domain
- * broadcasts as `domain/changed` ({domain: 'workspace', table: ''}) with
- * the new `archivedSessionIds`. The watcher diffs that set and stops every
- * bsk session owned by a freshly archived conversation — archived sessions
- * are hidden from every surface, so their Agent Windows would otherwise
- * linger with no way back to them.
- *
- * Ownership lineage: browser_session_start records the calling agent's
- * session id PLUS every ancestor along `header.parentSession` (a subagent's
- * browsers are reaped when any ancestor is archived, the root conversation
- * included). Lineage is resolved through the host session store; an
- * unloaded ancestor simply ends the walk.
- */
-
-import type { Context } from "@deepseek-ai/cordis";
-import type { ObservationService } from "./observation";
-import type { SessionRegistry } from "./sessions";
-
-/** The wire shape of a `domain/changed` frame (see dsh-storage-domain). */
-interface DomainChange {
-  domain?: string;
-  table?: string;
-  value?: unknown;
-}
-
-/** The workspace registry's durable global singleton slice we read. */
-interface WorkspaceGlobal {
-  archivedSessionIds?: unknown;
-}
-
-/** Structural host session store face: only the lineage read is needed. */
-interface SessionStoreLike {
-  get(id: string): { header: { parentSession?: string } } | undefined;
-}
-
-/** Cap on lineage walks — defensive against a malformed parent chain. */
-const MAX_LINEAGE_DEPTH = 16;
-
-/**
- * The DSH session ids that own a tool call's browser sessions: the calling
- * agent's own session plus every ancestor along the seed lineage. Empty
- * when the call carried no agent identity (those sessions outlive any
- * archive cleanup by design — nothing can name their owner).
- */
-export function ownerSessionIds(ctx: Context, agentId: string | undefined): string[] {
-  if (agentId === undefined) return [];
-  const store = ctx.get("sessions") as SessionStoreLike | undefined;
-  const ids: string[] = [];
-  let current: string | undefined = agentId;
-  for (let depth = 0; current !== undefined && depth < MAX_LINEAGE_DEPTH; depth += 1) {
-    if (ids.includes(current)) break; // a cycle in stored headers must not loop
-    ids.push(current);
-    current = store?.get(current)?.header.parentSession;
-  }
-  return ids;
-}
-
-/**
- * Watch conversation archival and stop the bsk sessions it opened. Returns
- * the disposer (plugin unload). In compositions without the workspace
- * domain (headless), the event simply never fires — and a context without
- * the events mixin degrades to a no-op like the other optional seams.
- */
-export function armArchiveCleanup(
-  ctx: Context,
-  registry: SessionRegistry,
-  observation: ObservationService,
-): () => void {
-  // 'domain/changed' lives outside the vendored Events type map, so the
-  // listener goes through a structural view of the events mixin.
-  const on = (
-    ctx as { on?: (event: string, listener: (change: DomainChange) => void) => () => void }
-  ).on;
-  if (typeof on !== "function") return () => {};
-
-  /** Archived ids already accounted for; lazily seeded from the registry. */
-  let seen: Set<string> | undefined;
-  const initialize = (): Set<string> => {
-    if (seen === undefined) {
-      const registryService = ctx.get("workspaceRegistry") as
-        | { archivedSessionIds?: readonly string[] }
-        | undefined;
-      seen = new Set(registryService?.archivedSessionIds ?? []);
-    }
-    return seen;
-  };
-
-  return on.call(ctx, "domain/changed", (change: DomainChange) => {
-    if (change?.domain !== "workspace" || change?.table !== "") return;
-    const archived = (change.value as WorkspaceGlobal | undefined)?.archivedSessionIds;
-    if (!Array.isArray(archived)) return;
-    const previous = initialize();
-    const fresh = archived.filter(
-      (id): id is string => typeof id === "string" && !previous.has(id),
-    );
-    seen = new Set(archived.filter((id): id is string => typeof id === "string"));
-    for (const dshSessionId of fresh) {
-      for (const sessionId of registry.ownedByDsh(dshSessionId)) {
-        // stopSession owns the full teardown (kill in-flight tools, queue
-        // the daemon stop, drop registry + observation entries); a failure
-        // just leaves the session for idle timeout or unload cleanup.
-        void observation.stopSession(sessionId).catch(() => {});
-      }
-    }
-  });
-}

packages/dsh-plugin-browserskill/src/client/ObservationOverlay.module.css

@@ -30,51 +30,17 @@
   color: var(--card-foreground);
 }
 
-/* Sidebar carrier: fill the better-sidebar tab area and let the body flex
-   (the tab content container owns the outer sizing). */
-.sidebar-tab {
-  display: flex;
-  flex-direction: column;
-  height: 100%;
-  min-height: 0;
-}
-
-.sidebar-tab > * {
-  flex: 1;
-  min-height: 0;
-}
-
-/* The BSK product mark in the sidebar tab strip (the source artwork already
-   carries rounded corners — just soften the square to match). */
-.brand-icon {
-  display: block;
-  border-radius: 22%;
-}
-
 .header {
   display: flex;
   align-items: center;
   gap: 6px;
   padding: 6px 8px;
+  cursor: move;
   user-select: none;
   touch-action: none;
   border-bottom: 1px solid var(--border);
 }
 
-/* Only the floating card drags by its header — the sidebar tab does not. */
-.header[data-draggable] {
-  cursor: move;
-}
-
-/* In the sidebar the status row is chrome, not a card edge: drop its bottom
-   border. A fixed-height bordered row can never track the shell header's
-   hairline across the panel boundary (its height varies per window), and
-   the BSK warm border tint clashes with the sidebar's neutral hairlines —
-   borderless, the stage's own background provides the separation. */
-.sidebar-tab .header {
-  border-bottom: none;
-}
-
 .status-text {
   flex: 1;
   min-width: 0;
@@ -165,12 +131,6 @@
   border-top: 1px solid var(--border);
 }
 
-.actions-group {
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-}
-
 .tool-wrap {
   position: relative;
   display: inline-flex;
@@ -205,14 +165,8 @@
   color: var(--destructive);
 }
 
-/* Stop session: danger-tinted like interrupt. */
-.tool-stop {
-  color: var(--destructive);
-}
-
-/* Hover the wrap (not just :hover on the button) so the tooltip target
-   lights the icon up too. The corner resize handles sit above this bar, so
-   the outer sliver of the corner-most buttons starts a resize instead. */
+/* Hover the wrap (not just :hover on the button) so the tooltip target and
+   the left-corner resize overlay still light the icon up. */
 .tool-wrap:hover .tool-button:not(:disabled) {
   color: var(--foreground);
   background: var(--accent);
@@ -227,15 +181,6 @@
   background: var(--accent);
 }
 
-/* The armed (confirm) state of the stop button: solid destructive fill so
-   the second click reads as final. Written at the wrap-hover specificity so
-   the hover rules above never wash it out. */
-.tool-button.tool-stop-armed,
-.tool-wrap:hover .tool-button.tool-stop-armed {
-  color: var(--destructive-foreground);
-  background: var(--destructive);
-}
-
 .hint {
   position: absolute;
   bottom: calc(100% + 4px);
@@ -258,16 +203,13 @@
   right: 0;
 }
 
-/* Invisible hit targets — no grip glyph; all four corners resize. Must sit
-   above the bottom .actions bar (z-index 3): it spans the full card width
-   and would otherwise swallow every pointer event aimed at the sw/se
-   corners. The top corners already win because .header is not positioned. */
+/* Invisible hit targets — no grip glyph; all four corners resize. */
 .resize-handle {
   position: absolute;
   width: 16px;
   height: 16px;
   touch-action: none;
-  z-index: 4;
+  z-index: 2;
 }
 
 .resize-handle[data-corner="nw"] {

packages/dsh-plugin-browserskill/src/client/ObservationOverlay.tsx

@@ -3,18 +3,13 @@
 // composer's way); collapsed = a status capsule; "pop out" upgrades the same
 // content to a native Document PiP window (user gesture required by the
 // browser). Multi-session renders a meeting-style strip under the focus view.
-// When the dsh-better-sidebar plugin is installed the tracking view moves
-// into a sidebar tab instead (see observation-sidebar.tsx) and this floating
-// card hides itself via the sidebar-mode flag. Visuals follow the
-// BrowserSkill product family: @browser-skill/ui components and oklch tokens
-// on a .bsk-obs scope root, so the card reads as BSK's own surface without
-// leaking styles into (or inheriting themes from) the shell.
+// Visuals follow the BrowserSkill product family: @browser-skill/ui components
+// and oklch tokens on a .bsk-obs scope root, so the card reads as BSK's own
+// surface without leaking styles into (or inheriting themes from) the shell.
 
 import { cn } from "@browser-skill/ui";
 import {
   RiArrowDownSLine,
-  RiCheckLine,
-  RiCloseCircleLine,
   RiErrorWarningLine,
   RiPictureInPicture2Line,
   RiPushpinFill,
@@ -30,8 +25,6 @@ const IconPip = asIcon(RiPictureInPicture2Line);
 const IconDown = asIcon(RiArrowDownSLine);
 const IconWarn = asIcon(RiErrorWarningLine);
 const IconPin = asIcon(RiPushpinFill);
-const IconCloseSession = asIcon(RiCloseCircleLine);
-const IconCheck = asIcon(RiCheckLine);
 
 import {
   type ReactNode,
@@ -46,12 +39,11 @@ import { createPortal } from "react-dom";
 import type { SessionObservation } from "../observation";
 import css from "./ObservationOverlay.module.css";
 import type { ObservationClientStore } from "./observation-store";
-import { focusOf, statusOf, useObservationView, usePip } from "./observation-view";
-import { getSidebarMode, subscribeSidebarMode } from "./sidebar-mode";
 
-// The pure view helpers live in observation-view (shared with the sidebar
-// tab); re-export so existing imports of this module keep working.
-export { focusOf, statusOf };
+/** Minimal Document PiP surface (TS lib.dom lacks it). */
+interface DocumentPip {
+  requestWindow(options?: { width?: number; height?: number }): Promise<Window>;
+}
 
 interface Point {
   x: number;
@@ -69,6 +61,11 @@ const EDGE_MARGIN = 16;
 /** Default dock: top-right, just under the shell's top bar (no spacing tokens exist in dsh 0.1). */
 const TOP_OFFSET = 64;
 
+function pipApi(): DocumentPip | undefined {
+  if (typeof window === "undefined") return undefined;
+  return (window as unknown as { documentPictureInPicture?: DocumentPip }).documentPictureInPicture;
+}
+
 function clampSize(size: Size, viewport: Size): Size {
   const maxW = viewport.w * 0.8;
   const maxH = viewport.h * 0.8;
@@ -117,6 +114,23 @@ function formatElapsed(sinceMs: number, nowMs: number): string {
   return `${mm}:${ss}`;
 }
 
+/**
+ * Auto-follow focus: the most recently touched session, but never yank focus
+ * to a session whose latest action failed (errors flag the strip item, they
+ * do not steal the stage) or one already reported dead.
+ */
+export function focusOf(sessions: readonly SessionObservation[]): SessionObservation | undefined {
+  if (sessions.length === 0) return undefined;
+  const byRecency = [...sessions].sort((a, b) => b.since - a.since);
+  const healthy = byRecency.find((s) => s.lastError === undefined && s.dead !== true);
+  return healthy ?? byRecency[0];
+}
+
+export function statusOf(obs: SessionObservation): "active" | "idle" | "error" {
+  if (obs.lastError !== undefined && obs.action === "idle") return "error";
+  return obs.action === "idle" ? "idle" : "active";
+}
+
 /** Compact toolbar icon: no label, hover bubble for the name / semantics. */
 function IconAction(props: {
   label: string;
@@ -152,83 +166,6 @@ function IconAction(props: {
   );
 }
 
-/** How long the stop button stays armed before the confirm click expires. */
-const STOP_ARM_MS = 3000;
-
-/**
- * Stop-session button with a lightweight two-click confirm: the first click
- * arms the button (solid red, check icon, short expiry), the second executes
- * the stop. No dialog, no layout shift — and a stray single click can never
- * close an Agent Window.
- */
-function StopSessionAction(props: {
-  sessionId: string | undefined;
-  onStop: (sessionId: string) => Promise<boolean>;
-}) {
-  const { sessionId, onStop } = props;
-  const [hover, setHover] = useState(false);
-  const [armed, setArmed] = useState(false);
-  const [stopping, setStopping] = useState(false);
-
-  useEffect(() => {
-    if (!armed) return;
-    const timer = setTimeout(() => setArmed(false), STOP_ARM_MS);
-    return () => clearTimeout(timer);
-  }, [armed]);
-
-  // The focused session can vanish mid-arm (stopped elsewhere): disarm.
-  useEffect(() => {
-    if (sessionId === undefined) setArmed(false);
-  }, [sessionId]);
-
-  const disabled = sessionId === undefined || stopping;
-  const label = stopping
-    ? "Stopping session…"
-    : armed
-      ? `Confirm stop session ${sessionId ?? ""}`
-      : `Stop session ${sessionId ?? ""}`;
-  const hint = stopping
-    ? "Closing the Agent Window…"
-    : armed
-      ? `Click again to stop session ${sessionId ?? ""} and close its Agent Window.`
-      : `Stop session ${sessionId ?? ""} and close its Agent Window.`;
-
-  return (
-    <span
-      className={css["tool-wrap"]}
-      onPointerEnter={() => setHover(true)}
-      onPointerLeave={() => setHover(false)}
-    >
-      <button
-        type="button"
-        className={cn(css["tool-button"], css["tool-stop"], armed && css["tool-stop-armed"])}
-        disabled={disabled}
-        aria-label={label}
-        aria-pressed={armed}
-        data-armed={armed || undefined}
-        onClick={() => {
-          if (sessionId === undefined || stopping) return;
-          if (!armed) {
-            setArmed(true);
-            return;
-          }
-          setArmed(false);
-          setStopping(true);
-          const target = sessionId;
-          void onStop(target).finally(() => setStopping(false));
-        }}
-      >
-        {armed ? <IconCheck size={16} /> : <IconCloseSession size={16} />}
-      </button>
-      {hover ? (
-        <span className={css.hint} role="tooltip">
-          {hint}
-        </span>
-      ) : null}
-    </span>
-  );
-}
-
 /** Flat status dot, specced after the BSK popup's ConnectionStatusIndicator. */
 function StatusDot({ state }: { state: "active" | "idle" | "error" | "dead" }) {
   const color =
@@ -309,8 +246,8 @@ function StripItem(props: {
   );
 }
 
-/** The floating card / PiP / sidebar-tab shared content. */
-export function OverlayBody(props: {
+/** The floating card / PiP shared content. */
+function OverlayBody(props: {
   store: ObservationClientStore;
   focus: SessionObservation | undefined;
   sessions: readonly SessionObservation[];
@@ -373,7 +310,6 @@ export function OverlayBody(props: {
       <div
         className={css.header}
         data-testid="obs-header"
-        data-draggable={onHeaderPointerDown !== undefined || undefined}
         onPointerDown={onHeaderPointerDown}
         role="presentation"
       >
@@ -427,21 +363,15 @@ export function OverlayBody(props: {
         </div>
       ) : null}
       <div className={css.actions}>
-        <div className={css["actions-group"]}>
-          <IconAction
-            label={interrupting ? "Interrupting…" : "Interrupt the current browser action"}
-            hint="Stop the current browser action."
-            disabled={!canInterrupt}
-            danger
-            onClick={onInterrupt}
-          >
-            <IconStop size={16} />
-          </IconAction>
-          <StopSessionAction
-            sessionId={focus?.sessionId}
-            onStop={(sessionId) => store.stopSession(sessionId)}
-          />
-        </div>
+        <IconAction
+          label={interrupting ? "Interrupting…" : "Interrupt the current browser action"}
+          hint="Stop the current browser action."
+          disabled={!canInterrupt}
+          danger
+          onClick={onInterrupt}
+        >
+          <IconStop size={16} />
+        </IconAction>
         {onPopOut !== undefined ? (
           <IconAction
             label="Pop out into a mini window"
@@ -457,17 +387,25 @@ export function OverlayBody(props: {
   );
 }
 
+/** Clone the host document's style/link nodes into a PiP window. */
+function cloneStylesInto(pipWindow: Window): void {
+  for (const node of document.querySelectorAll('link[rel="stylesheet"], style')) {
+    pipWindow.document.head.appendChild(node.cloneNode(true));
+  }
+}
+
 export function ObservationOverlay({ store }: { store: ObservationClientStore }) {
-  const { snapshot, focus, pinnedId, onTogglePin, now } = useObservationView(store);
-  // While the better-sidebar plugin carries the tracking view, this floating
-  // card (and its capsule) stays out of the way; an already-open PiP window
-  // keeps its portal until the user closes it.
-  const sidebarMode = useSyncExternalStore(subscribeSidebarMode, getSidebarMode);
+  const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot);
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
 
   const [collapsed, setCollapsed] = useState(false);
   const [pos, setPos] = useState<Point | null>(null);
   const [size, setSize] = useState<Size>(DEFAULT_SIZE);
-  const { pipWindow, pipSupported, popOut } = usePip();
+  const [pipWindow, setPipWindow] = useState<Window | null>(null);
+  const [pinnedId, setPinnedId] = useState<string | null>(null);
   const dragRef = useRef<{
     kind: "move" | "resize";
     corner?: ResizeCorner;
@@ -476,6 +414,23 @@ export function ObservationOverlay({ store }: { store: ObservationClientStore })
     base: Point & Size;
   } | null>(null);
 
+  // Elapsed-time ticker: 1s while anything is active.
+  const anyActive = snapshot.sessions.some((s) => s.action !== "idle");
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (!anyActive) return;
+    const timer = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(timer);
+  }, [anyActive]);
+
+  // Focus: the pinned session wins while it still exists; otherwise auto-follow.
+  const pinned =
+    pinnedId !== null ? snapshot.sessions.find((s) => s.sessionId === pinnedId) : undefined;
+  const focus = pinned ?? focusOf(snapshot.sessions);
+  const onTogglePin = useCallback((sessionId: string) => {
+    setPinnedId((current) => (current === sessionId ? null : sessionId));
+  }, []);
+
   const viewport = (): Size => ({ w: window.innerWidth, h: window.innerHeight });
 
   const onPointerMove = useCallback((event: PointerEvent) => {
@@ -556,21 +511,34 @@ export function ObservationOverlay({ store }: { store: ObservationClientStore })
     document.addEventListener("pointerup", onPointerUp);
   };
 
+  const popOut = async (): Promise<void> => {
+    const pip = pipApi();
+    if (pip === undefined) return;
+    try {
+      const win = await pip.requestWindow({ width: size.w, height: size.h });
+      cloneStylesInto(win);
+      win.addEventListener("pagehide", () => setPipWindow(null));
+      setPipWindow(win);
+    } catch {
+      // requestWindow rejects without a user gesture (or when the window was
+      // closed mid-request): stay on the in-page card, no state change.
+    }
+  };
+
+  // Hidden while no owned session exists (and no PiP is up).
+  if (snapshot.sessions.length === 0 && pipWindow === null) return null;
+
   const body = (
     <OverlayBody
       store={store}
       focus={focus}
       sessions={snapshot.sessions}
       available={snapshot.available}
-      pinnedId={pinnedId}
+      pinnedId={pinned !== undefined ? pinnedId : null}
       onTogglePin={onTogglePin}
       now={now}
       inPip={pipWindow !== null}
-      onPopOut={
-        pipWindow === null && pipSupported
-          ? () => popOut({ width: size.w, height: size.h })
-          : undefined
-      }
+      onPopOut={pipWindow === null && pipApi() !== undefined ? () => void popOut() : undefined}
       onCollapse={pipWindow === null ? () => setCollapsed(true) : undefined}
       onHeaderPointerDown={pipWindow === null ? beginMove : undefined}
     />
@@ -580,12 +548,6 @@ export function ObservationOverlay({ store }: { store: ObservationClientStore })
     return createPortal(body, pipWindow.document.body);
   }
 
-  // The sidebar tab is the carrier now — no floating card, no capsule.
-  if (sidebarMode) return null;
-
-  // Hidden while no owned session exists (and no PiP is up).
-  if (snapshot.sessions.length === 0) return null;
-
   if (collapsed) {
     const state = focus !== undefined ? statusOf(focus) : "idle";
     return (

packages/dsh-plugin-browserskill/src/client/brand-icon.ts

@@ -1,8 +0,0 @@
-/**
- * The BrowserSkill product mark (apps/extension/assets/logo.png, downscaled
- * to 32px and inlined): the sidebar tab icon, so the tracking view reads as
- * BSK's own surface next to better-sidebar's built-in "browser" tab.
- * Regenerate with: resize the source to 32x32 PNG and replace the payload.
- */
-export const BSK_LOGO_URL =
-  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAJGklEQVR42m2X248c2V3HP79zTlV19/TcPOOZWY+vsdmQFdngTQJswgs3hQ15iCJslAey+8xDAIHgH+CBNxIpj0gkEXnAKyKQWITEJlKWXSssEMfJRmuMHa/W9njHMz3Tl+nprsv5/XiomlugpdN16lR1n9/1e75fAbAbeLlO3Pz2ly4vjO7+sRbF58oiP49FEREOPwaIYQjS3IvUy0fP66kAZoYJIM7SpPVY0uy14cyzXzn9u9+4c+MG/vp1otiNa16uvxr7X/+1L3bK3lcTyU9P80ilR/uKCGYHOxxd6s2kmdaGIVYb1qyY1e8HD63UUblstwirf9J95fW/sRvXvAD0v/6Z6/O68Xf5/pS8kigiTsTkuCfIwfzAxQN37chjaAyt594JIXE4gbKMhog6Nd/qthi7lVe6L3/nG7Jz4/fPJ9u3b4U4WSwiKog/EcsTLh+PSuO3GXYs/D44QnBgyniQs7OV0+8bOxPPM6c9l660VEyF0Nmrlp9/IYT+/S/PUJ4a5C46EW8HnjVhBKjXaHJfz9Xq95xzhMThHZR5xXBrwtPNnP6eRzvzhJWzrF1d5UI759//9iYra5lrt1ycDeXsaOf+n4Y4HX8+r9SciasLS/6P12LHoyF47wipYKpM9gqePpyyvVMxjBn+1DILH17l0rkZlhYcLetT3n/A5FGfTtvTCh4ibjpVI81/J0il62V1rNStLp6j4jowxwiJh2iMevtsbU3pjYQim6Nz9hJLH13i8mrGbJgSxjuUvQfEjT2GOw4Zddh0BakPtFPH/jRKqaCSrwetKi9mKIIYhyFuOg6TurCcF7ae5ty5t48/vcTiz3+Ei+szLC06WnGA7TykfNCnmObk5nAtj+53yDcTZteMwZOChbkMVa3/14DCJBBBFBxyopndUUBqwwxu/XjAJ778Bc4ul+R3fgyj9yg/GDMpFZxHgoe0hQ9QDRzFI48zqHzJeKhcvNKiLAyiQ1BwgsOcqNZ9Xo96rgaVgmqdiBACH740y/1/+j4b7w1x80tUkwLM4VptJAQMcN6o+p7iYQIqhBQmsUIrR7cd0NI12ODAwJnWTpvZoRGqdRrS1CECeR7Z2NzHRBjeecgbX/kut39UUlx5ATe3gFUlAM5Tb/4oHCJl0oadUcFsK8E5sFh7ZaqgEFBr3KyhxAySxDMplDv3BuztlmhhZC6QqONDrXkW28Kbf/1d7A9+i6vPr7N/e5vQDZQ7jvxxUqdPwFRwHaP3sGR1boZYGabWwHdd7MHMMBUMh5mRJp6tnZx33tllJbS53J1jZj6BKpKPpkhZ8e5mj3Nf/FV+8ZOnmNz6Pr6TUvUcxeOAc0cN6xwUoWIyUhZXMqqq6bKmrQ0hWBQzdXX+nGOwV3LnJ30+trjE8mxGUUVG/Qn7owkt7/hpb5fwmat84qXz5P95EwmOqh8oNkKTSkFqICTJYDgpCOppZYGyjIfgdoApQRScCtEgDZ5b93dxuWd3OuWD8T5pqbSLyEyWcHdrh+S3r/Kpz15i/z/eQhIh9hOKjQRTyBYgFhAndSpDW+gNC+ZbGR6jjM3BVsNsXQNqhqpiOPIicuXcLFvdKT7xtNXTG+X0Bopt9Wi9dJUXX7rI5O23kNQRB4F8I0CEzgr0/B7t2YB/2iJOQDrK8HHJ+dkZqqI+JfUAYRXMGc6pM1MBBa2Ubttz5ews51c6XFjr8OJHT5N0HPIbz/Ppz11h/+03IXVUg4T8ccAidFaNp7LHzdd2uXdvj866gQq5L8nHMD+TUJUG0aAyJBqidZQcUfFqeK2vlEo1rYh5iUXl6eMB5eoKv37tOUb/9q+4LBD7gXKj3ry7Ak/iHrdeH/ArC7P07ykPekMWzkFvkNMmkHkgagNoDciogYKzaGg0YgSNYLEJj0ndfiGj6o/Z3i5or5+j2BTKJwlawcwKbMQ9fvK9Ib+QtgitQMg8d384wVYLdocls1mCad1+Fg1TDgeV4UxFTB2ow44NjQ5rwcwZ+MjqmLe/dZOBLOHHCeUUZteED+Ie73xvyHNpmyx1TERozXieW1/mO/+yzWhTWVtsU5aCqKvRT4+GmRDEHGJ6yPPMBHNGeqbCdwqs02X9l14g/a8H3PzWm/zyp1ZZXgn8tDfgnbeGPN/qIEDSyhh7w2OcPZWRsESWCq3EoVFPksZDMuUIps7qLjDUQBxkZ0tcu8KSGdIXPo3OLbOSdfj4YMIPbg6ZXxux9wRmWimFKe0k0J7v8H5vQHchpSoiC536bKhKEDlCJzM7JLJqhqtxoEYoUcEFw/Yduh8Jl38OP7eAlBOm29ssziV87JlluqMOL15ZZWVlhu0yMrfYxQQmZUU3TbCmnog1mRE1xOp9xOoaEwVRI9QnUGOECLoPNlcRlucJ6xeIgx3K/3kX23pINWnRdnBxtYNWkbkkMJ5JSLKEwaSgRFlsJWh1mNBDfsEBzZGaYIiBIgRtImCmmArhlBFOR1Q9xZ3b6OOHWFnifEq1U/84TpXgHL4hUh7hv3t91pY6eCeUpTYs2o6RisYEO6B5hpoSRCWaanNAGP5UVZ+r+YB4dxcbZ4QVx/Q9wSYg/uDYNvKyoorwgyfbtDuBC6c65HmFa5Jsh56f3NgO4iGeYC68n8Ty2WkphAUVv2hoLuggoXgUcJkRh0rVF7wHi3Vw1YxuSMh1zMpcmw8tdynzCmmCL1JjzQG3lpNU37xAdNnjYC79xywUfzbJNboEX214iqeeuN/IrkKw6BAvNUiJ1a2K0HKOT144jQBFoTWRayrc9LhWa1TTUTNqJ038wCf/LO//xZfWWw9u/zCt8uWpSiTixZ3UeJzQPkerdkyq1RryZwVN87CJBALR0ExULMtG4/VnPy4AG3/4m19YGG/9fT7NmZpEhzg5lCNHOo//774u7UYp2WEt1XrSftYMTcF32ynbrfmXz3ztjW86u3bNn/nq69/eaZ/6PUlbm/PB+YSapUozMG2uB0M5fI7WSKoKasjBu6qHczEjwWQ2iJc03XmaLb5y5mtvfNOuNeLUruHlVeK7f/7yxbXBu39U5sXnq7I8L2pH6rwRgCZyUpeKnZSOB5K2EbT1l5hPk0c+zV7bXXzmry7/5T/cvXENf/1V4v8CSYIrURx3kHgAAAAASUVORK5CYII=";

packages/dsh-plugin-browserskill/src/client/index.ts

@@ -1,9 +1,7 @@
 /**
  * dsh-plugin-browserskill browser half: the `browser_screenshot` keyed
- * toolview plus the observation overlay (live thumbnails + interrupt). The
- * default carrier is a floating card on the `shell.overlay` seat; when the
- * dsh-better-sidebar plugin provides its `betterSidebar` service, the view
- * moves into a sidebar tab instead (see observation-sidebar.tsx).
+ * toolview plus the observation overlay (live thumbnails + interrupt) floating
+ * over the shell via the `shell.overlay` seat.
  */
 
 import type { ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
@@ -17,7 +15,6 @@ import { createElement } from "react";
 import "./bsk-tokens.nomodule.css";
 import "./bsk-ui.nomodule.css";
 import { ObservationOverlay } from "./ObservationOverlay";
-import { type BetterSidebarLike, registerObservationSidebar } from "./observation-sidebar";
 import { type EventSourceLike, ObservationClientStore } from "./observation-store";
 import { ScreenshotToolView } from "./ScreenshotToolView";
 
@@ -84,14 +81,4 @@ export function apply(ctx: ClientContext): void {
       createElement(ObservationOverlay, { store }),
     ),
   );
-  // Optional carrier upgrade: when the dsh-better-sidebar plugin is installed,
-  // its service moves the tracking view into a sidebar tab (the floating
-  // overlay hides itself through the sidebar-mode flag). In profiles without
-  // the sidebar plugin this fiber never runs and nothing changes.
-  ctx.inject(["betterSidebar"], (injected) =>
-    registerObservationSidebar(
-      (injected as unknown as { betterSidebar: BetterSidebarLike }).betterSidebar,
-      store,
-    ),
-  );
 }

packages/dsh-plugin-browserskill/src/client/observation-sidebar.tsx

@@ -1,256 +0,0 @@
-// better-sidebar carrier for the observation view. When the
-// dsh-better-sidebar plugin is installed its client publishes a
-// `betterSidebar` cordis service; the client entry then runs the
-// registration below and the tracking view moves from the floating card
-// into a single-instance sidebar tab (Document PiP pop-out stays available
-// from inside the tab). Detection is purely service-based — profiles
-// without the sidebar plugin never start this fiber and keep the floating
-// overlay.
-
-import { createElement, type ReactNode } from "react";
-import { createPortal } from "react-dom";
-import { BSK_LOGO_URL } from "./brand-icon";
-import { OverlayBody } from "./ObservationOverlay";
-import css from "./ObservationOverlay.module.css";
-import type { ObservationClientStore } from "./observation-store";
-import { useObservationView, usePip, visibleToScope } from "./observation-view";
-import { setSidebarMode } from "./sidebar-mode";
-
-/** The tab title — "Browser Skill", distinct from the sidebar's built-in "browser" tab. */
-const TAB_TITLE = "Browser Skill";
-
-/** Tab strip icon: the BrowserSkill product mark at the requested size. */
-function TabIcon({ size }: { size: number }) {
-  return (
-    <img
-      src={BSK_LOGO_URL}
-      width={size}
-      height={size}
-      alt=""
-      aria-hidden
-      className={css["brand-icon"]}
-    />
-  );
-}
-
-/**
- * Structural mirrors of dsh-better-sidebar's client service surface (only
- * the slices this integration touches — see the upstream
- * lib/types/client/service.d.ts). Declared locally so the plugin carries no
- * dependency on the sidebar package; the service contract has been stable
- * since v0.4.0 and newer capabilities arrive behind its `features` list.
- */
-export interface SidebarTabLike {
-  id: string;
-  type: string;
-  title: string;
-}
-
-export interface SidebarLeafLike {
-  kind: "leaf";
-  id: string;
-  tabs: SidebarTabLike[];
-  active: string | null;
-}
-
-export interface SidebarSplitLike {
-  kind: "split";
-  id: string;
-  dir: "row" | "col";
-  sizes: number[];
-  children: SidebarNodeLike[];
-}
-
-export type SidebarNodeLike = SidebarLeafLike | SidebarSplitLike;
-
-export interface SidebarStateLike {
-  splits: SidebarNodeLike;
-  bottomSplits: SidebarNodeLike;
-  /** Whether the right panel is expanded (the merged drawer on narrow screens). */
-  panelOpen?: boolean;
-}
-
-export interface SidebarSnapshotLike {
-  sessionId?: string;
-  state?: SidebarStateLike;
-}
-
-/** Props every tab component receives (the slices we read). */
-export interface TabComponentPropsLike {
-  /** The conversation this sidebar instance belongs to. */
-  scope: { sessionId: string };
-}
-
-export interface TabDescriptorLike {
-  id: string;
-  title: string | (() => string);
-  icon?: ReactNode | ((size: number) => ReactNode);
-  order?: number;
-  /** Single-instance: opening focuses the existing tab instead of duplicating. */
-  single?: boolean;
-  /** Small pill on the tab strip; null/undefined hides it. */
-  badge?: (
-    ctx: unknown,
-    scope: { sessionId: string },
-    state: unknown,
-  ) => string | number | null | undefined;
-  component: (props: TabComponentPropsLike) => ReactNode;
-}
-
-export interface BetterSidebarLike {
-  registerTab(descriptor: TabDescriptorLike): () => void;
-  openTab(seed: {
-    type: string;
-    title?: string;
-    /** Content seed (lands on tab.path); content opens expand the panel. */
-    path?: string;
-  }): void;
-  getSnapshot(): SidebarSnapshotLike;
-  /** Sidebar state feed (v0.12+): session switches, state and prefs changes. */
-  subscribeState?: (listener: () => void) => () => void;
-  isTabEnabled(id: string): boolean;
-}
-
-/** The registered tab type id (also the SidebarTab.type value). */
-export const OBSERVATION_TAB_TYPE = "browserskill:observation";
-
-/**
- * Inert content seed carried on auto-opened tabs: its mere presence makes
- * the sidebar treat the open as a content open (expanding the hosting panel
- * so the tracking view lands in sight). Never read by our component.
- */
-export const OBSERVATION_TAB_PATH = "browser-skill:observation";
-
-/**
- * The observation tab body: the same OverlayBody the floating card renders,
- * minus the card chrome (no drag header, no collapse — the sidebar tab bar
- * owns those), plus the PiP pop-out upgrade. The view is scoped to the
- * sidebar's conversation: only browser sessions started by it (or its
- * descendants) show here — the floating card keeps the global view.
- */
-export function ObservationSidebarTab({
-  store,
-  scopeId,
-}: {
-  store: ObservationClientStore;
-  scopeId: string;
-}) {
-  const { snapshot, focus, pinnedId, onTogglePin, now } = useObservationView(store, scopeId);
-  const { pipWindow, pipSupported, popOut } = usePip();
-
-  const body = (
-    <OverlayBody
-      store={store}
-      focus={focus}
-      sessions={snapshot.sessions}
-      available={snapshot.available}
-      pinnedId={pinnedId}
-      onTogglePin={onTogglePin}
-      now={now}
-      inPip={pipWindow !== null}
-      onPopOut={pipWindow === null && pipSupported ? () => popOut() : undefined}
-    />
-  );
-
-  if (pipWindow !== null) {
-    return createPortal(body, pipWindow.document.body);
-  }
-  return <div className={css["sidebar-tab"]}>{body}</div>;
-}
-
-function* leafNodes(node: SidebarNodeLike): Generator<SidebarLeafLike> {
-  if (node.kind === "leaf") {
-    yield node;
-    return;
-  }
-  for (const child of node.children) yield* leafNodes(child);
-}
-
-/** Whether a tab of our type is already open in either sidebar workbench. */
-export function observationTabOpen(state: SidebarStateLike | undefined): boolean {
-  if (state === undefined) return false;
-  for (const root of [state.splits, state.bottomSplits]) {
-    for (const leaf of leafNodes(root)) {
-      if (leaf.tabs.some((tab) => tab.type === OBSERVATION_TAB_TYPE)) return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Register the observation sidebar tab and flip the carrier flag. Returns
- * the disposer the cordis fiber invokes when the sidebar service goes away
- * (plugin unload/HMR): the floating overlay then resumes as the carrier.
- */
-export function registerObservationSidebar(
-  service: BetterSidebarLike,
-  store: ObservationClientStore,
-): () => void {
-  setSidebarMode(true);
-  // Hold the feed for the whole sidebar lifetime so the auto-open watcher
-  // sees new sessions even while the tab itself is closed.
-  store.acquire();
-  const disposeTab = service.registerTab({
-    id: OBSERVATION_TAB_TYPE,
-    title: TAB_TITLE,
-    icon: (size: number) => createElement(TabIcon, { size }),
-    single: true,
-    // The badge counts only sessions visible to the tab strip's own
-    // conversation (global sessions from other conversations stay hidden,
-    // mirroring the tab body's scoped view).
-    badge: (_ctx, scope) => {
-      const count = store
-        .getSnapshot()
-        .sessions.filter((s) => visibleToScope(s, scope.sessionId)).length;
-      return count > 0 ? count : null;
-    },
-    component: (props) =>
-      createElement(ObservationSidebarTab, { store, scopeId: props.scope.sessionId }),
-  });
-
-  // Auto-open the tab when a browser session VISIBLE TO the active
-  // conversation appears (and right away when one is already live). The
-  // evaluation runs on observation publishes AND on sidebar state changes:
-  // the latter covers the sidebar store's async init (its state is
-  // undefined for the first beats after page load) and conversation
-  // switches. The open carries a content seed (`path`): only content opens
-  // land in sight — the sidebar expands the hosting panel for them. While
-  // the panel is OPEN an existing tab is never re-focused — the user may
-  // be reading another page on purpose; while it is collapsed a NEW
-  // session (0→N) nudges the tab back into sight, mirroring how the
-  // floating card used to reappear.
-  const activeVisibleCount = (): number => {
-    const activeId = service.getSnapshot().sessionId;
-    if (activeId === undefined) return 0;
-    return store.getSnapshot().sessions.filter((s) => visibleToScope(s, activeId)).length;
-  };
-  let previousVisible = activeVisibleCount();
-  const evaluate = (): void => {
-    const count = activeVisibleCount();
-    const { state, sessionId } = service.getSnapshot();
-    if (
-      state !== undefined &&
-      sessionId !== undefined &&
-      service.isTabEnabled(OBSERVATION_TAB_TYPE)
-    ) {
-      const open = observationTabOpen(state);
-      if (count > 0 && !open) {
-        service.openTab({ type: OBSERVATION_TAB_TYPE, path: OBSERVATION_TAB_PATH });
-      } else if (previousVisible === 0 && count > 0 && open && state.panelOpen === false) {
-        service.openTab({ type: OBSERVATION_TAB_TYPE, path: OBSERVATION_TAB_PATH });
-      }
-    }
-    previousVisible = count;
-  };
-  evaluate();
-  const unsubscribe = store.subscribe(evaluate);
-  const unsubscribeState = service.subscribeState?.(evaluate);
-
-  return () => {
-    unsubscribe();
-    unsubscribeState?.();
-    disposeTab();
-    store.release();
-    setSidebarMode(false);
-  };
-}

packages/dsh-plugin-browserskill/src/client/observation-store.ts

@@ -53,7 +53,6 @@ export interface OverlaySnapshot {
 const STATE_URL = "/bsk-observation/state";
 const EVENTS_URL = "/bsk-observation/events";
 const INTERRUPT_URL = "/bsk-observation/interrupt";
-const STOP_URL = "/bsk-observation/stop";
 
 function revoke(url: string | undefined): void {
   if (url !== undefined && typeof URL.revokeObjectURL === "function") {
@@ -79,8 +78,6 @@ export class ObservationClientStore {
   };
   private available = true;
   private started = false;
-  /** Refcount of mounted consumers (overlay card, sidebar tab, sidebar fiber). */
-  private consumers = 0;
 
   constructor(private readonly deps: ObservationClientDeps) {}
 
@@ -192,23 +189,6 @@ export class ObservationClientStore {
     this.publish();
   }
 
-  /**
-   * Hold the feed for one consumer's lifetime: the stream starts with the
-   * first holder and stops with the last release. Several carriers can share
-   * the store (the floating card, the better-sidebar tab, and the sidebar
-   * integration fiber) without one unmount killing the others' updates.
-   */
-  acquire(): void {
-    this.consumers += 1;
-    if (this.consumers === 1) this.start();
-  }
-
-  release(): void {
-    if (this.consumers === 0) return;
-    this.consumers -= 1;
-    if (this.consumers === 0) this.stop();
-  }
-
   /** Forget one session's tracked + held frames, revoking their blob URLs. */
   private dropThumb(sessionId: string): void {
     const attachmentId = this.thumbBySession.get(sessionId);
@@ -312,23 +292,4 @@ export class ObservationClientStore {
       return false;
     }
   }
-
-  /**
-   * Stop one session and close its Agent Window. The session's removal
-   * arrives through the SSE remove event — no local state is touched here.
-   */
-  async stopSession(sessionId: string): Promise<boolean> {
-    try {
-      const res = await this.deps.fetchFn(STOP_URL, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ sessionId }),
-      });
-      if (!res.ok) return false;
-      const body = (await res.json()) as { stopped?: boolean };
-      return body.stopped === true;
-    } catch {
-      return false;
-    }
-  }
 }

packages/dsh-plugin-browserskill/src/client/observation-view.ts

@@ -1,148 +0,0 @@
-/**
- * Shared view logic for the observation carriers (the floating overlay card
- * and the better-sidebar tab): the store-backed view model (snapshot, focus
- * pinning, elapsed ticker) and the Document PiP pop-out. Extracted from
- * ObservationOverlay so both carriers run the same focus/interrupt behavior
- * without duplicating hooks.
- */
-
-import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
-import type { SessionObservation } from "../observation";
-import type { ObservationClientStore, OverlaySnapshot } from "./observation-store";
-
-/**
- * Auto-follow focus: the most recently touched session, but never yank focus
- * to a session whose latest action failed (errors flag the strip item, they
- * do not steal the stage) or one already reported dead.
- */
-export function focusOf(sessions: readonly SessionObservation[]): SessionObservation | undefined {
-  if (sessions.length === 0) return undefined;
-  const byRecency = [...sessions].sort((a, b) => b.since - a.since);
-  const healthy = byRecency.find((s) => s.lastError === undefined && s.dead !== true);
-  return healthy ?? byRecency[0];
-}
-
-export function statusOf(obs: SessionObservation): "active" | "idle" | "error" {
-  if (obs.lastError !== undefined && obs.action === "idle") return "error";
-  return obs.action === "idle" ? "idle" : "active";
-}
-
-/** Minimal Document PiP surface (TS lib.dom lacks it). */
-export interface DocumentPip {
-  requestWindow(options?: { width?: number; height?: number }): Promise<Window>;
-}
-
-export function pipApi(): DocumentPip | undefined {
-  if (typeof window === "undefined") return undefined;
-  return (window as unknown as { documentPictureInPicture?: DocumentPip }).documentPictureInPicture;
-}
-
-/** Clone the host document's style/link nodes into a PiP window. */
-export function cloneStylesInto(pipWindow: Window): void {
-  for (const node of document.querySelectorAll('link[rel="stylesheet"], style')) {
-    pipWindow.document.head.appendChild(node.cloneNode(true));
-  }
-}
-
-export interface ObservationView {
-  readonly snapshot: OverlaySnapshot;
-  /** Pinned session wins while it still exists; otherwise auto-follow. */
-  readonly focus: SessionObservation | undefined;
-  readonly pinnedId: string | null;
-  readonly onTogglePin: (sessionId: string) => void;
-  /** 1s ticker while anything is active (drives the elapsed readout). */
-  readonly now: number;
-}
-
-/**
- * Whether one session is visible on a surface scoped to one DSH
- * conversation: sessions started by that conversation or its descendants
- * (the lineage ancestors ride along on the entry). Untracked sessions (no
- * owner recorded) are hidden from scoped surfaces but stay in global views.
- */
-export function visibleToScope(obs: SessionObservation, scopeId: string): boolean {
-  return obs.dshSessionIds?.includes(scopeId) === true;
-}
-
-/**
- * The store-backed observation view model. Holds the feed for the component
- * lifetime (refcounted — overlapping carriers never kill each other's
- * stream). `scopeId` narrows the view to one DSH conversation's sessions
- * (the better-sidebar tab); undefined keeps the global view (floating
- * card, PiP).
- */
-export function useObservationView(
-  store: ObservationClientStore,
-  scopeId?: string,
-): ObservationView {
-  const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot);
-  useEffect(() => {
-    store.acquire();
-    return () => store.release();
-  }, [store]);
-
-  const scopedSnapshot: OverlaySnapshot =
-    scopeId === undefined
-      ? snapshot
-      : {
-          ...snapshot,
-          sessions: snapshot.sessions.filter((s) => visibleToScope(s, scopeId)),
-        };
-
-  const [pinnedId, setPinnedId] = useState<string | null>(null);
-  const pinned =
-    pinnedId !== null ? scopedSnapshot.sessions.find((s) => s.sessionId === pinnedId) : undefined;
-  const focus = pinned ?? focusOf(scopedSnapshot.sessions);
-  const onTogglePin = useCallback((sessionId: string) => {
-    setPinnedId((current) => (current === sessionId ? null : sessionId));
-  }, []);
-
-  const anyActive = scopedSnapshot.sessions.some((s) => s.action !== "idle");
-  const [now, setNow] = useState(() => Date.now());
-  useEffect(() => {
-    if (!anyActive) return;
-    const timer = setInterval(() => setNow(Date.now()), 1000);
-    return () => clearInterval(timer);
-  }, [anyActive]);
-
-  return {
-    snapshot: scopedSnapshot,
-    focus,
-    pinnedId: pinned !== undefined ? pinnedId : null,
-    onTogglePin,
-    now,
-  };
-}
-
-export interface PipHandle {
-  /** The open PiP window, or null while the content renders in its carrier. */
-  readonly pipWindow: Window | null;
-  /** Whether the browser exposes Document PiP (Chrome-only today). */
-  readonly pipSupported: boolean;
-  /**
-   * Upgrade the content into a native PiP window. Rejects silently without a
-   * user gesture (or when closed mid-request): the carrier keeps the content.
-   */
-  readonly popOut: (size?: { width: number; height: number }) => void;
-}
-
-export function usePip(): PipHandle {
-  const [pipWindow, setPipWindow] = useState<Window | null>(null);
-  const popOut = useCallback((size?: { width: number; height: number }): void => {
-    const pip = pipApi();
-    if (pip === undefined) return;
-    void pip
-      .requestWindow(size)
-      .then((win) => {
-        cloneStylesInto(win);
-        win.addEventListener("pagehide", () => setPipWindow(null));
-        setPipWindow(win);
-      })
-      .catch(() => {});
-  }, []);
-  // Unmounting the carrier (tab close, conversation switch, plugin HMR) does
-  // not destroy the PiP browsing context: close it ourselves or it survives
-  // as a blank window. close() on an already-closed window is a no-op.
-  useEffect(() => () => pipWindow?.close(), [pipWindow]);
-  return { pipWindow, pipSupported: pipApi() !== undefined, popOut };
-}

packages/dsh-plugin-browserskill/src/client/sidebar-mode.ts

@@ -1,26 +0,0 @@
-/**
- * Carrier switch for the observation view: while the better-sidebar
- * integration fiber is alive (the dsh-better-sidebar plugin provides its
- * `betterSidebar` service), the tracking view lives in a sidebar tab and the
- * floating overlay card/capsule hides itself. The flag is a tiny external
- * store so the overlay can read it through useSyncExternalStore and flip
- * without a remount when the sidebar plugin (un)loads.
- */
-
-let active = false;
-const listeners = new Set<() => void>();
-
-export function getSidebarMode(): boolean {
-  return active;
-}
-
-export function subscribeSidebarMode(listener: () => void): () => void {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}
-
-export function setSidebarMode(next: boolean): void {
-  if (active === next) return;
-  active = next;
-  for (const listener of [...listeners]) listener();
-}

packages/dsh-plugin-browserskill/src/index.ts

@@ -12,7 +12,6 @@
 
 import type { Context } from "@deepseek-ai/cordis";
 import Schema from "@deepseek-ai/schemastery";
-import { armArchiveCleanup } from "./archive-cleanup";
 import { armLazyTools } from "./lazy-tools";
 import { ObservationService } from "./observation";
 import { registerObservationRoutes } from "./observation-http";
@@ -108,10 +107,6 @@ export function apply(
     removeRoutes = registerObservationRoutes(injected, observation);
     return () => removeRoutes();
   });
-  // Reap a conversation's browsers when the conversation itself is archived:
-  // archived sessions are hidden from every surface, so their Agent Windows
-  // would otherwise linger unreachable until idle timeout or unload.
-  const disarmArchiveCleanup = armArchiveCleanup(ctx, registry, observation);
 
   // Non-blocking install probe: warn early when bsk is missing instead of
   // failing the first tool call with a bare spawn error. Uses --version on
@@ -137,7 +132,6 @@ export function apply(
       removeSuite();
       unregisterSkill();
       removeRoutes();
-      disarmArchiveCleanup();
       observation.dispose();
       runner.killAll();
       const stops = registry
@@ -150,7 +144,6 @@ export function apply(
   });
 }
 
-export { armArchiveCleanup, ownerSessionIds } from "./archive-cleanup";
 export type { ObservationEvent, ObservationOptions, SessionObservation } from "./observation";
 export { ObservationService } from "./observation";
 export { registerObservationRoutes } from "./observation-http";

packages/dsh-plugin-browserskill/src/observation-http.ts

@@ -8,7 +8,6 @@
  *   GET  /bsk-observation/state      → { sessions, available }
  *   GET  /bsk-observation/events     → SSE stream of ObservationEvent
  *   POST /bsk-observation/interrupt  → body {sessionId?} → {interrupted: boolean}
- *   POST /bsk-observation/stop       → body {sessionId} → {stopped: boolean}
  *   GET  /bsk-observation/thumbnail/<attachmentId> → image bytes
  *
  * Routes exist only when a webServer service is mounted (web composition);
@@ -167,42 +166,6 @@ export function registerObservationRoutes(
         });
       },
     }),
-    webServer.register({
-      kind: "exact",
-      path: `${ROUTE_BASE}/stop`,
-      handler: (req, res) => {
-        if (req.method !== "POST") {
-          sendJson(res, 405, { error: "method not allowed" });
-          return;
-        }
-        if (fenceRejected(req, res)) return;
-        let body = "";
-        req.on("data", (chunk: Buffer | string) => {
-          body += chunk;
-        });
-        req.on("end", () => {
-          let sessionId: string | undefined;
-          try {
-            const parsed = JSON.parse(body || "{}") as { sessionId?: unknown };
-            if (typeof parsed.sessionId === "string" && parsed.sessionId !== "") {
-              sessionId = parsed.sessionId;
-            }
-          } catch {
-            sendJson(res, 400, { error: "invalid JSON body" });
-            return;
-          }
-          // A destructive call always names its target (never "current").
-          if (sessionId === undefined) {
-            sendJson(res, 400, { error: "sessionId required" });
-            return;
-          }
-          void observation.stopSession(sessionId).then(
-            (stopped) => sendJson(res, 200, { stopped }),
-            () => sendJson(res, 500, { error: "stop failed" }),
-          );
-        });
-      },
-    }),
     webServer.register({
       kind: "prefix",
       path: `${ROUTE_BASE}/thumbnail`,

packages/dsh-plugin-browserskill/src/observation.ts

@@ -39,13 +39,6 @@ export interface SessionObservation {
    * greys it out until it is stopped/removed. No more frames are requested.
    */
   dead?: boolean;
-  /**
-   * The DSH conversations this session belongs to (the starting agent's
-   * session plus its seed-lineage ancestors), recorded at start. Scoped
-   * surfaces (the better-sidebar tab) filter by it; absent means untracked
-   * ownership — visible only in the global (unscoped) view.
-   */
-  dshSessionIds?: string[];
 }
 
 /** Incremental event carried to subscribers (SSE on the wire). */
@@ -160,13 +153,11 @@ export class ObservationService {
   /** Register a fresh owned session (called from browser_session_start). */
   addSession(sessionId: string, url?: string): void {
     if (!this.deps.options.enabled || this.disposed) return;
-    const dshSessionIds = this.deps.registry.dshOwnersOf(sessionId);
     this.put({
       sessionId,
       ...(url !== undefined ? { url } : {}),
       action: "idle",
       since: this.scheduler.now(),
-      ...(dshSessionIds.length > 0 ? { dshSessionIds } : {}),
     });
     this.lastActivity.set(sessionId, this.scheduler.now());
     this.scheduleCapture(sessionId, 0);
@@ -237,36 +228,6 @@ export class ObservationService {
     return this.deps.runner.killFor(target) > 0;
   }
 
-  /**
-   * Stop one owned session and close its Agent Window (the overlay's stop
-   * button — same end state as `browser_session_stop`). Never waits behind a
-   * hung in-flight command: tool children are killed first so the session's
-   * keyed queue drains immediately, and no further captures queue up. A
-   * session the daemon already forgot (dead strip entries) stops
-   * idempotently — the goal state (entry gone) is identical.
-   * @returns whether the session ended up stopped/removed.
-   */
-  async stopSession(sessionId: string): Promise<boolean> {
-    if (!this.deps.registry.isOwned(sessionId)) return false;
-    this.cancelCapture(sessionId);
-    this.deps.runner.killFor(sessionId);
-    const result = await this.deps.queue.run(sessionId, () =>
-      this.deps.runner.run(["session", "stop", sessionId], { timeoutMs: 30_000 }),
-    );
-    if (result.code !== 0) {
-      let code: string | undefined;
-      try {
-        code = (JSON.parse(result.stdout) as { code?: string }).code;
-      } catch {
-        code = undefined;
-      }
-      if (code !== "session_not_found") return false;
-    }
-    this.deps.registry.remove(sessionId);
-    this.removeSession(sessionId);
-    return true;
-  }
-
   /**
    * Read one captured thumbnail from the in-process ring. Powers the plugin's
    * own HTTP thumbnail route — frames are plugin-owned runtime data, never

packages/dsh-plugin-browserskill/src/sessions.ts

@@ -24,13 +24,6 @@ export interface TrackedSession {
 export class SessionRegistry {
   private readonly sessions = new Map<string, TrackedSession>();
   private currentId: string | undefined;
-  /**
-   * bsk session id → the DSH session ids that may clean it up: the agent
-   * session that started it plus every ancestor along the seed lineage, so
-   * archiving a conversation at ANY level of the chain reaps its browsers
-   * (see archive-cleanup.ts).
-   */
-  private readonly dshOwners = new Map<string, ReadonlySet<string>>();
   /**
    * Slots reserved by in-flight starts. reserveStart/completeStart/abandonStart
    * run synchronously around the async spawn, so concurrent starts can never
@@ -79,37 +72,12 @@ export class SessionRegistry {
   /** Forget a session; falls back to the most recent remaining one. */
   remove(sessionId: string): void {
     this.sessions.delete(sessionId);
-    this.dshOwners.delete(sessionId);
     if (this.currentId === sessionId) {
       const rest = [...this.sessions.values()];
       this.currentId = rest.length > 0 ? rest[rest.length - 1].sessionId : undefined;
     }
   }
 
-  /**
-   * Record which DSH conversation(s) a freshly started bsk session belongs
-   * to (the starting agent's session plus its ancestors). No-op without ids
-   * — e.g. a start whose caller carried no agent identity.
-   */
-  trackOwner(sessionId: string, dshSessionIds: readonly string[]): void {
-    if (dshSessionIds.length === 0 || !this.sessions.has(sessionId)) return;
-    this.dshOwners.set(sessionId, new Set(dshSessionIds));
-  }
-
-  /** bsk session ids owned by the given DSH conversation (or its descendants). */
-  ownedByDsh(dshSessionId: string): string[] {
-    const owned: string[] = [];
-    for (const [sessionId, owners] of this.dshOwners) {
-      if (owners.has(dshSessionId)) owned.push(sessionId);
-    }
-    return owned;
-  }
-
-  /** The DSH conversation ids owning one bsk session (empty when untracked). */
-  dshOwnersOf(sessionId: string): string[] {
-    return [...(this.dshOwners.get(sessionId) ?? [])];
-  }
-
   /** Mark an owned session as most recently used (recency order refresh). */
   private touch(sessionId: string): void {
     const existing = this.sessions.get(sessionId);

packages/dsh-plugin-browserskill/src/tools.ts

@@ -17,7 +17,6 @@ import {
   type ToolResult,
   type ToolRunContext,
 } from "@deepseek-ai/dsh-tools";
-import { ownerSessionIds } from "./archive-cleanup";
 import { trySaveScreenshot } from "./image";
 import { actionForLabel, type ObservationService } from "./observation";
 import type { KeyedExecutor } from "./queue";
@@ -246,9 +245,6 @@ export function registerTools(deps: ToolDeps): () => void {
           browserInstanceId: reply.browser_instance_id,
           startedAtMs: Date.now(),
         });
-        // Ownership for archive cleanup: the calling conversation and its
-        // ancestors reap this session when any of them is archived.
-        registry.trackOwner(reply.session_id, ownerSessionIds(deps.ctx, exec.agent?.id));
         deps.observation.addSession(reply.session_id, args.url);
         try {
           if (args.device !== undefined) {

packages/dsh-plugin-browserskill/tests/archive-cleanup.test.ts

@@ -1,157 +0,0 @@
-// Archive-triggered cleanup: lineage resolution for browser-session
-// ownership, the registry's owner index, and the domain/changed watcher
-// that reaps a freshly archived conversation's bsk sessions.
-
-import { describe, expect, it, vi } from "vitest";
-import { armArchiveCleanup, ownerSessionIds } from "../src/archive-cleanup";
-import type { ObservationService } from "../src/observation";
-import { SessionRegistry } from "../src/sessions";
-
-/** A ctx stub carrying a session store with the given lineage headers. */
-function ctxWithSessions(headers: Record<string, { parentSession?: string }>) {
-  return {
-    get: (key: string) =>
-      key === "sessions"
-        ? {
-            get: (id: string) => (headers[id] === undefined ? undefined : { header: headers[id] }),
-          }
-        : undefined,
-  } as never;
-}
-
-describe("ownerSessionIds", () => {
-  it("walks the seed lineage to the root; empty without an agent identity", () => {
-    expect(ownerSessionIds(ctxWithSessions({}), undefined)).toEqual([]);
-    const ctx = ctxWithSessions({
-      child: { parentSession: "parent" },
-      parent: { parentSession: "root" },
-      root: {},
-    });
-    expect(ownerSessionIds(ctx, "child")).toEqual(["child", "parent", "root"]);
-  });
-
-  it("stops the walk at an unloaded ancestor", () => {
-    const ctx = ctxWithSessions({ child: { parentSession: "gone" } });
-    expect(ownerSessionIds(ctx, "child")).toEqual(["child", "gone"]);
-  });
-
-  it("never loops on a malformed parent cycle", () => {
-    const ctx = ctxWithSessions({
-      a: { parentSession: "b" },
-      b: { parentSession: "a" },
-    });
-    expect(ownerSessionIds(ctx, "a")).toEqual(["a", "b"]);
-  });
-});
-
-describe("SessionRegistry owner tracking", () => {
-  function start(registry: SessionRegistry, sessionId: string): void {
-    registry.reserveStart();
-    registry.completeStart({ sessionId, startedAtMs: 1 });
-  }
-
-  it("indexes owners and forgets them on remove; ignores empty/unknown ownership", () => {
-    const registry = new SessionRegistry(5);
-    start(registry, "bsk1");
-    start(registry, "bsk2");
-    registry.trackOwner("bsk1", ["conv-a", "root"]);
-    registry.trackOwner("bsk2", ["conv-b"]);
-    expect(registry.ownedByDsh("root")).toEqual(["bsk1"]);
-    expect(registry.ownedByDsh("conv-a")).toEqual(["bsk1"]);
-    expect(registry.ownedByDsh("conv-b")).toEqual(["bsk2"]);
-    expect(registry.ownedByDsh("nobody")).toEqual([]);
-    registry.remove("bsk1");
-    expect(registry.ownedByDsh("root")).toEqual([]);
-    // Empty owner lists and unknown session ids record nothing.
-    registry.trackOwner("bsk2", []);
-    registry.trackOwner("ghost", ["conv-c"]);
-    expect(registry.ownedByDsh("conv-c")).toEqual([]);
-  });
-});
-
-describe("armArchiveCleanup", () => {
-  function harness(opts: { archived?: string[] } = {}) {
-    const registry = new SessionRegistry(5);
-    const observation = { stopSession: vi.fn(async () => true) };
-    const listeners = new Set<(change: unknown) => void>();
-    const ctx = {
-      get: (key: string) =>
-        key === "workspaceRegistry" ? { archivedSessionIds: opts.archived ?? [] } : undefined,
-      on: (event: string, listener: (change: unknown) => void) => {
-        if (event === "domain/changed") listeners.add(listener);
-        return () => listeners.delete(listener);
-      },
-    };
-    const emit = (change: unknown) => {
-      for (const listener of [...listeners]) listener(change);
-    };
-    return {
-      registry,
-      observation: observation as unknown as ObservationService,
-      stopSession: observation.stopSession,
-      emit,
-      arm: () =>
-        armArchiveCleanup(ctx as never, registry, observation as unknown as ObservationService),
-    };
-  }
-
-  function startOwned(registry: SessionRegistry, bskId: string, owners: string[]): void {
-    registry.reserveStart();
-    registry.completeStart({ sessionId: bskId, startedAtMs: 1 });
-    registry.trackOwner(bskId, owners);
-  }
-
-  it("stops every bsk session owned by a freshly archived conversation, until disarmed", () => {
-    const h = harness();
-    startOwned(h.registry, "bsk1", ["conv-a", "root"]);
-    startOwned(h.registry, "bsk2", ["conv-b"]);
-    const disarm = h.arm();
-    h.emit({
-      domain: "workspace",
-      table: "",
-      value: { archivedSessionIds: ["root"] },
-    });
-    expect(h.stopSession).toHaveBeenCalledTimes(1);
-    expect(h.stopSession).toHaveBeenCalledWith("bsk1");
-    // After the disposer runs the watcher is silent again.
-    disarm();
-    h.emit({
-      domain: "workspace",
-      table: "",
-      value: { archivedSessionIds: ["root", "conv-b"] },
-    });
-    expect(h.stopSession).toHaveBeenCalledTimes(1);
-  });
-
-  it("ignores pre-archived ids, foreign domains, and malformed frames", () => {
-    const h = harness({ archived: ["old-conv"] });
-    startOwned(h.registry, "bsk1", ["old-conv"]);
-    startOwned(h.registry, "bsk2", ["conv-a"]);
-    h.arm();
-    // Seeded from the registry: the pre-archived id must not retro-fire.
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: ["old-conv"] } });
-    h.emit({ domain: "settings", table: "", value: { archivedSessionIds: ["conv-a"] } });
-    h.emit({ domain: "workspace", table: "rows", value: { archivedSessionIds: ["conv-a"] } });
-    h.emit({ domain: "workspace", table: "", value: {} });
-    expect(h.stopSession).not.toHaveBeenCalled();
-    // A genuinely new archive still fires.
-    h.emit({
-      domain: "workspace",
-      table: "",
-      value: { archivedSessionIds: ["old-conv", "conv-a"] },
-    });
-    expect(h.stopSession).toHaveBeenCalledWith("bsk2");
-  });
-
-  it("treats a re-archived session as fresh again after unarchive", () => {
-    const h = harness();
-    startOwned(h.registry, "bsk1", ["conv-a"]);
-    h.arm();
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: ["conv-a"] } });
-    expect(h.stopSession).toHaveBeenCalledTimes(1);
-    // Unarchive, then re-archive: the second archival cleans up again.
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: [] } });
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: ["conv-a"] } });
-    expect(h.stopSession).toHaveBeenCalledTimes(2);
-  });
-});

packages/dsh-plugin-browserskill/tests/client/observation-overlay.test.tsx

@@ -4,7 +4,7 @@
 // upgrade/fallback (mocked documentPictureInPicture). NOTE: use RTL's waitFor
 // (act-flushing), not vi.waitFor, when asserting store-driven UI updates.
 
-import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { applyResize, ObservationOverlay } from "../../src/client/ObservationOverlay";
 import { type EventSourceLike, ObservationClientStore } from "../../src/client/observation-store";
@@ -157,45 +157,6 @@ describe("ObservationOverlay", () => {
     await screen.findByText(/s1 · clicking/);
   });
 
-  it("stop session: the first click only arms the confirm, the second posts", async () => {
-    const h = makeHarness([{ sessionId: "s1", action: "idle", since: Date.now() }]);
-    render(<ObservationOverlay store={h.store} />);
-    await screen.findByText(/s1 · idle/);
-    const stop = screen.getByRole("button", { name: "Stop session s1" });
-    fireEvent.click(stop);
-    // Armed: a plain click must never close an Agent Window by itself.
-    expect(h.fetches.some((f) => f.url === "/bsk-observation/stop")).toBe(false);
-    const confirm = await screen.findByRole("button", { name: "Confirm stop session s1" });
-    expect(confirm.getAttribute("aria-pressed")).toBe("true");
-    fireEvent.click(confirm);
-    await waitFor(() =>
-      expect(
-        h.fetches.some(
-          (f) => f.url === "/bsk-observation/stop" && f.init?.body === '{"sessionId":"s1"}',
-        ),
-      ).toBe(true),
-    );
-  });
-
-  it("disarms the stop confirm after the expiry window", async () => {
-    const h = makeHarness([{ sessionId: "s1", action: "idle", since: Date.now() }]);
-    render(<ObservationOverlay store={h.store} />);
-    const stop = await screen.findByRole("button", { name: "Stop session s1" });
-    vi.useFakeTimers();
-    try {
-      fireEvent.click(stop);
-      // Synchronous queries only: waitFor-style finds hang under fake timers.
-      expect(screen.getByRole("button", { name: "Confirm stop session s1" })).toBeTruthy();
-      act(() => {
-        vi.advanceTimersByTime(3100);
-      });
-      expect(screen.getByRole("button", { name: "Stop session s1" })).toBeTruthy();
-      expect(h.fetches.some((f) => f.url === "/bsk-observation/stop")).toBe(false);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
   it("resizes within min/max clamps", async () => {
     const h = makeHarness([BUSY]);
     render(<ObservationOverlay store={h.store} />);
@@ -261,7 +222,6 @@ describe("ObservationOverlay", () => {
         addEventListener: (name: string, fn: () => void) => {
           listeners.set(name, [...(listeners.get(name) ?? []), fn]);
         },
-        close: vi.fn(),
       } as unknown as Window;
     });
     (window as unknown as Record<string, unknown>).documentPictureInPicture = { requestWindow };
@@ -276,28 +236,6 @@ describe("ObservationOverlay", () => {
     await screen.findByTestId("obs-card");
   });
 
-  it("closes the PiP window when the carrier unmounts", async () => {
-    const h = makeHarness([BUSY]);
-    const pipDoc = document.implementation.createHTMLDocument("pip");
-    const close = vi.fn();
-    const requestWindow = vi.fn(async () => {
-      return {
-        document: pipDoc,
-        addEventListener: () => {},
-        close,
-      } as unknown as Window;
-    });
-    (window as unknown as Record<string, unknown>).documentPictureInPicture = { requestWindow };
-    const { unmount } = render(<ObservationOverlay store={h.store} />);
-    const popout = await screen.findByRole("button", { name: /Pop out/ });
-    fireEvent.click(popout);
-    await waitFor(() => expect(pipDoc.body.textContent).toContain("s1"));
-    // Unmounting (tab close, conversation switch, plugin HMR) closes the PiP
-    // instead of leaving a blank window behind.
-    unmount();
-    expect(close).toHaveBeenCalledTimes(1);
-  });
-
   it("renders the strip for two sessions and pins focus on click", async () => {
     const older: SessionObservation = {
       sessionId: "s1",

packages/dsh-plugin-browserskill/tests/client/observation-sidebar.test.tsx

@@ -1,331 +0,0 @@
-// @vitest-environment happy-dom
-// better-sidebar carrier: tab registration + auto-open, the sidebar-mode
-// flag hiding the floating overlay, PiP pop-out from the tab, and the
-// store's refcounted acquire/release across overlapping carriers.
-
-import { cleanup, render, screen, waitFor } from "@testing-library/react";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { ObservationOverlay } from "../../src/client/ObservationOverlay";
-import {
-  type BetterSidebarLike,
-  OBSERVATION_TAB_PATH,
-  OBSERVATION_TAB_TYPE,
-  ObservationSidebarTab,
-  observationTabOpen,
-  registerObservationSidebar,
-  type SidebarNodeLike,
-  type SidebarStateLike,
-  type TabDescriptorLike,
-} from "../../src/client/observation-sidebar";
-import { type EventSourceLike, ObservationClientStore } from "../../src/client/observation-store";
-import { getSidebarMode, setSidebarMode } from "../../src/client/sidebar-mode";
-import type { SessionObservation } from "../../src/observation";
-
-// Owned by the sidebar mock's active conversation ("conv-1") so the scoped
-// visibility logic lets it through; FOREIGN belongs to another conversation.
-const BUSY: SessionObservation = {
-  sessionId: "s1",
-  action: "clicking",
-  since: Date.now() - 7000,
-  dshSessionIds: ["conv-1"],
-};
-const FOREIGN: SessionObservation = {
-  sessionId: "s9",
-  action: "clicking",
-  since: Date.now() - 5000,
-  dshSessionIds: ["other-conv"],
-};
-
-interface Harness {
-  store: ObservationClientStore;
-  es: () => EventSourceLike | undefined;
-  push: (sessions: SessionObservation[]) => void;
-}
-
-function makeHarness(initial: SessionObservation[]): Harness {
-  let es: EventSourceLike | undefined;
-  let current = initial;
-  const store = new ObservationClientStore({
-    fetchFn: async (url: string) => {
-      if (url === "/bsk-observation/state") {
-        return { ok: true, json: async () => ({ sessions: current }) };
-      }
-      return { ok: true, json: async () => ({ interrupted: true }) };
-    },
-    eventSourceFactory: () => {
-      es = { onmessage: null, close: vi.fn() };
-      return es;
-    },
-    loadImage: async (id: string) => `blob:${id}`,
-  });
-  return {
-    store,
-    es: () => es,
-    push: (sessions) => {
-      current = sessions;
-      for (const s of sessions) {
-        es?.onmessage?.({ data: JSON.stringify({ type: "upsert", session: s }) });
-      }
-      if (sessions.length === 0) es?.onmessage?.({ data: JSON.stringify({ type: "reset" }) });
-    },
-  };
-}
-
-function leafWith(type: string, panelOpen = true): SidebarStateLike {
-  return {
-    panelOpen,
-    splits: {
-      kind: "split",
-      id: "root",
-      dir: "row",
-      sizes: [1],
-      children: [
-        {
-          kind: "leaf",
-          id: "pane-1",
-          active: type,
-          tabs: [{ id: type, type, title: type }],
-        },
-      ],
-    },
-    bottomSplits: { kind: "leaf", id: "pane-2", active: null, tabs: [] },
-  };
-}
-
-interface SidebarMock {
-  service: BetterSidebarLike;
-  descriptor: () => TabDescriptorLike;
-  openTab: ReturnType<typeof vi.fn>;
-  disposeTab: ReturnType<typeof vi.fn>;
-  setState: (state: SidebarStateLike | undefined) => void;
-}
-
-/** Insert a tab into the first leaf of the main tree (mirrors a real open). */
-function withTabOpened(state: SidebarStateLike, type: string): SidebarStateLike {
-  let done = false;
-  const walk = (node: SidebarNodeLike): SidebarNodeLike => {
-    if (done) return node;
-    if (node.kind === "leaf") {
-      done = true;
-      return { ...node, active: type, tabs: [...node.tabs, { id: type, type, title: type }] };
-    }
-    return { ...node, children: node.children.map(walk) };
-  };
-  return { ...state, splits: walk(state.splits) };
-}
-
-function makeSidebar(
-  initialState: SidebarStateLike | undefined = leafWith("explorer"),
-): SidebarMock {
-  let descriptor: TabDescriptorLike | undefined;
-  let state: SidebarStateLike | undefined = initialState;
-  const openTab = vi.fn((seed: { type: string }) => {
-    // Mirror the real feedback loop: a created tab lands in the state, so
-    // later evaluations see it open (single-instance dedupe re-focuses).
-    if (state !== undefined && !observationTabOpen(state)) {
-      state = withTabOpened(state, seed.type);
-    }
-  });
-  const disposeTab = vi.fn();
-  const service: BetterSidebarLike = {
-    registerTab: (next) => {
-      descriptor = next;
-      return disposeTab;
-    },
-    openTab,
-    getSnapshot: () => ({ sessionId: "conv-1", state }),
-    isTabEnabled: () => true,
-  };
-  return {
-    service,
-    descriptor: () => {
-      if (descriptor === undefined) throw new Error("no tab registered");
-      return descriptor;
-    },
-    openTab,
-    disposeTab,
-    setState: (next) => {
-      state = next;
-    },
-  };
-}
-
-afterEach(() => {
-  cleanup();
-  setSidebarMode(false);
-});
-
-describe("registerObservationSidebar", () => {
-  it("registers a single-instance tab and holds the feed for its lifetime", () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    expect(getSidebarMode()).toBe(false);
-    const dispose = registerObservationSidebar(sidebar.service, h.store);
-    expect(getSidebarMode()).toBe(true);
-    // The fiber holds the observation feed itself, so the auto-open watcher
-    // sees new sessions even while the tab is closed.
-    expect(h.es()).toBeDefined();
-    const descriptor = sidebar.descriptor();
-    expect(descriptor.id).toBe(OBSERVATION_TAB_TYPE);
-    expect(descriptor.single).toBe(true);
-    expect(descriptor.title).toBe("Browser Skill");
-    dispose();
-    expect(getSidebarMode()).toBe(false);
-    expect(sidebar.disposeTab).toHaveBeenCalledTimes(1);
-    expect(h.es()?.close).toHaveBeenCalled?.();
-  });
-
-  it("opens the tab right away when a session is already live at activation", async () => {
-    const h = makeHarness([BUSY]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    // The initial state fetch lands asynchronously; the 0→N watcher then fires.
-    await waitFor(() =>
-      expect(sidebar.openTab).toHaveBeenCalledWith({
-        type: OBSERVATION_TAB_TYPE,
-        path: OBSERVATION_TAB_PATH,
-      }),
-    );
-  });
-
-  it("auto-opens on the first session but never re-focuses an open tab", async () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    expect(sidebar.openTab).not.toHaveBeenCalled();
-    // First session arrives: the tab lands in the sidebar.
-    h.push([BUSY]);
-    await waitFor(() => expect(sidebar.openTab).toHaveBeenCalledTimes(1));
-    // The sidebar now reports the tab open (persisted/restored): further
-    // session arrivals must not steal focus from whatever the user reads.
-    sidebar.setState(leafWith(OBSERVATION_TAB_TYPE));
-    h.push([]);
-    h.push([{ ...BUSY, sessionId: "s2" }]);
-    h.push([]);
-    h.push([{ ...BUSY, sessionId: "s3" }]);
-    await waitFor(() => expect(h.store.getSnapshot().sessions.length).toBe(1));
-    expect(sidebar.openTab).toHaveBeenCalledTimes(1);
-  });
-
-  it("does not open while the sidebar has no active session state", () => {
-    const h = makeHarness([BUSY]);
-    const sidebar = makeSidebar(undefined);
-    registerObservationSidebar(sidebar.service, h.store);
-    expect(sidebar.openTab).not.toHaveBeenCalled();
-  });
-
-  it("nudges an existing tab back into sight when the panel is collapsed", async () => {
-    const h = makeHarness([]);
-    // Tab already open (persisted), but the panel is collapsed: a new
-    // session should surface the tracking view again (focus + expand via a
-    // content open), like the floating card reappearing.
-    const sidebar = makeSidebar(leafWith(OBSERVATION_TAB_TYPE, false));
-    registerObservationSidebar(sidebar.service, h.store);
-    h.push([BUSY]);
-    await waitFor(() =>
-      expect(sidebar.openTab).toHaveBeenCalledWith({
-        type: OBSERVATION_TAB_TYPE,
-        path: OBSERVATION_TAB_PATH,
-      }),
-    );
-  });
-
-  it("shows the visible session count as the tab badge", () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    const badge = sidebar.descriptor().badge;
-    const scope = { sessionId: "conv-1" };
-    expect(badge?.(undefined, scope, undefined)).toBeNull();
-    h.store.acquire();
-    h.push([BUSY, FOREIGN]);
-    expect(badge?.(undefined, scope, undefined)).toBe(1);
-    expect(badge?.(undefined, { sessionId: "other-conv" }, undefined)).toBe(1);
-    expect(badge?.(undefined, { sessionId: "nobody" }, undefined)).toBeNull();
-    h.store.release();
-  });
-
-  it("does not auto-open for sessions owned by other conversations", async () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    h.push([FOREIGN]);
-    await waitFor(() => expect(h.store.getSnapshot().sessions.length).toBe(1));
-    expect(sidebar.openTab).not.toHaveBeenCalled();
-    // A session visible to the active conversation does open the tab.
-    h.push([BUSY]);
-    await waitFor(() => expect(sidebar.openTab).toHaveBeenCalledTimes(1));
-  });
-});
-
-describe("observationTabOpen", () => {
-  it("finds the tab in either workbench tree", () => {
-    expect(observationTabOpen(undefined)).toBe(false);
-    expect(observationTabOpen(leafWith("explorer"))).toBe(false);
-    expect(observationTabOpen(leafWith(OBSERVATION_TAB_TYPE))).toBe(true);
-    const inBottom: SidebarStateLike = {
-      splits: { kind: "leaf", id: "p1", active: null, tabs: [] },
-      bottomSplits: {
-        kind: "leaf",
-        id: "p2",
-        active: OBSERVATION_TAB_TYPE,
-        tabs: [{ id: OBSERVATION_TAB_TYPE, type: OBSERVATION_TAB_TYPE, title: "Browser" }],
-      },
-    };
-    expect(observationTabOpen(inBottom)).toBe(true);
-  });
-});
-
-describe("ObservationSidebarTab", () => {
-  it("renders the tracking view without card chrome (no collapse, no drag header)", async () => {
-    const h = makeHarness([BUSY]);
-    render(<ObservationSidebarTab store={h.store} scopeId="conv-1" />);
-    await screen.findByText(/s1 · clicking/);
-    expect(screen.queryByRole("button", { name: "Collapse" })).toBeNull();
-    expect(screen.getByTestId("obs-header").dataset.draggable).toBeUndefined();
-    // No resize handles — the sidebar owns the geometry.
-    expect(screen.queryByTestId("obs-resize-se")).toBeNull();
-    // Session controls ride along: interrupt + stop-with-confirm.
-    expect(screen.getByRole("button", { name: "Stop session s1" })).toBeTruthy();
-  });
-
-  it("scopes the view to the sidebar's conversation", async () => {
-    const h = makeHarness([BUSY, FOREIGN]);
-    render(<ObservationSidebarTab store={h.store} scopeId="conv-1" />);
-    // Focus and content belong to the owned session; the foreign one never
-    // reaches the stage, the status line, or the strip (which needs 2+).
-    await screen.findByText(/s1 · clicking/);
-    expect(screen.queryByText(/s9/)).toBeNull();
-    expect(screen.queryByTestId("obs-strip")).toBeNull();
-    // Scoping to the other conversation swaps what's visible.
-    render(<ObservationSidebarTab store={h.store} scopeId="other-conv" />);
-    await screen.findByText(/s9 · clicking/);
-  });
-});
-
-describe("carrier switching", () => {
-  it("hides the floating overlay while sidebar mode is active", async () => {
-    const h = makeHarness([]);
-    const { container } = render(<ObservationOverlay store={h.store} />);
-    h.push([BUSY]);
-    await screen.findByTestId("obs-card");
-    setSidebarMode(true);
-    await waitFor(() => expect(container.firstChild).toBeNull());
-    setSidebarMode(false);
-    await screen.findByTestId("obs-card");
-  });
-
-  it("keeps the feed alive across overlapping carriers (refcount)", async () => {
-    const h = makeHarness([]);
-    const overlay = render(<ObservationOverlay store={h.store} />);
-    await waitFor(() => expect(h.es()).toBeDefined());
-    // A second carrier mounts (the sidebar tab), then the overlay unmounts:
-    // the stream must survive for the remaining consumer.
-    const tab = render(<ObservationSidebarTab store={h.store} scopeId="conv-1" />);
-    overlay.unmount();
-    h.push([BUSY]);
-    await screen.findByText(/s1 · clicking/);
-    expect(h.es()?.close ?? vi.fn()).not.toHaveBeenCalled();
-    tab.unmount();
-  });
-});

packages/dsh-plugin-browserskill/tests/client/screenshot-toolview.test.tsx

@@ -137,9 +137,6 @@ describe("client plugin registration", () => {
     const sessions = { binding: () => undefined };
     const ctx = {
       get: (key: string) => (key === "sessions" ? sessions : undefined),
-      // cordis ctx.inject: the betterSidebar carrier upgrade stays dormant in
-      // this composition (the callback only runs once the service exists).
-      inject: (_deps: string[], _fn: (injected: unknown) => unknown) => {},
       slots: {
         inject: (_name: string, fn: () => unknown) => fn(),
         register: (slot: { name: string; key?: string; id?: string }, view: unknown) => {

packages/dsh-plugin-browserskill/tests/observation.test.ts

@@ -61,8 +61,6 @@ function fakeRunner(
   opts: {
     screenshotFails?: boolean;
     screenshotNotFound?: boolean;
-    stopNotFound?: boolean;
-    stopFails?: boolean;
     killCount?: number;
     screenshotBytes?: () => Uint8Array;
   } = {},
@@ -74,21 +72,6 @@ function fakeRunner(
     killed,
     async run(args: string[], options: BskRunOptions = {}): Promise<BskRunResult> {
       calls.push({ args, options });
-      if (args[0] === "session" && args[1] === "stop") {
-        if (opts.stopNotFound) {
-          return {
-            code: 4,
-            stdout: JSON.stringify({ code: "session_not_found", message: "no such session" }),
-            stderr: "",
-            timedOut: false,
-            aborted: false,
-          };
-        }
-        if (opts.stopFails) {
-          return { code: 1, stdout: "", stderr: "boom", timedOut: false, aborted: false };
-        }
-        return { code: 0, stdout: "{}", stderr: "", timedOut: false, aborted: false };
-      }
       if (args[0] === "screenshot") {
         if (opts.screenshotNotFound) {
           return {
@@ -197,23 +180,6 @@ describe("state machine", () => {
     expect(events[events.length - 1].type).toBe("reset");
   });
 
-  it("stamps the registry-recorded DSH owners onto new entries", () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    own(registry, "s2");
-    registry.trackOwner("s1", ["conv-a", "root"]);
-    const { service } = setup({ registry });
-    service.addSession("s1");
-    service.addSession("s2");
-    expect(service.getState()).toEqual([
-      { sessionId: "s1", action: "idle", since: 1_000_000, dshSessionIds: ["conv-a", "root"] },
-      { sessionId: "s2", action: "idle", since: 1_000_000 },
-    ]);
-    // The owner stamp survives later upserts (action/url/frame churn).
-    service.beginAction("s1", "clicking");
-    expect(service.getState()[0].dshSessionIds).toEqual(["conv-a", "root"]);
-  });
-
   it("ignores instrumentation for unknown sessions (owned-only by construction)", () => {
     const { service } = setup({});
     service.beginAction("foreign", "clicking");
@@ -341,57 +307,6 @@ describe("interrupt routing", () => {
   });
 });
 
-describe("stopSession", () => {
-  it("stops an owned session: kills in-flight tools, runs session stop, removes the entry", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner();
-    const { service, events } = setup({ registry, runner });
-    service.addSession("s1");
-    expect(registry.isOwned("s1")).toBe(true);
-
-    await expect(service.stopSession("s1")).resolves.toBe(true);
-    expect(runner.killed).toEqual(["s1"]);
-    const stop = runner.calls.find((c) => c.args[0] === "session" && c.args[1] === "stop");
-    expect(stop?.args).toEqual(["session", "stop", "s1"]);
-    expect(registry.isOwned("s1")).toBe(false);
-    expect(service.getState()).toEqual([]);
-    expect(events[events.length - 1]).toMatchObject({ type: "remove" });
-  });
-
-  it("refuses foreign sessions without touching the runner", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner();
-    const { service } = setup({ registry, runner });
-    await expect(service.stopSession("foreign")).resolves.toBe(false);
-    expect(runner.killed).toEqual([]);
-    expect(runner.calls).toEqual([]);
-  });
-
-  it("stops idempotently when the daemon already forgot the session (dead entries)", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner({ stopNotFound: true });
-    const { service, events } = setup({ registry, runner });
-    service.addSession("s1");
-    await expect(service.stopSession("s1")).resolves.toBe(true);
-    expect(registry.isOwned("s1")).toBe(false);
-    expect(events[events.length - 1]).toMatchObject({ type: "remove" });
-  });
-
-  it("returns false and keeps the entry when the stop itself fails", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner({ stopFails: true });
-    const { service } = setup({ registry, runner });
-    service.addSession("s1");
-    await expect(service.stopSession("s1")).resolves.toBe(false);
-    expect(registry.isOwned("s1")).toBe(true);
-    expect(service.getState().map((s) => s.sessionId)).toEqual(["s1"]);
-  });
-});
-
 describe("HTTP/SSE interface", () => {
   interface RecordedRoute {
     path: string;
@@ -490,45 +405,11 @@ describe("HTTP/SSE interface", () => {
     await interruptRoute?.handler(postReq, interruptRes.res as never);
     expect(JSON.parse(interruptRes.res.body())).toEqual({ interrupted: true });
 
-    // stop (POST {sessionId}): owned session stops and leaves the state
-    const stopRoute = routes.get("/bsk-observation/stop");
-    const stopRes = fakeRes();
-    await stopRoute?.handler(postReq, stopRes.res as never);
-    // The stop is async behind the response-less handler — poll the state.
-    await waitFor(() => service.getState().length === 0);
-    expect(JSON.parse(stopRes.res.body())).toEqual({ stopped: true });
-
     dispose();
     expect(routes.size).toBe(0);
     service.dispose();
   });
 
-  it("refuses a stop without a sessionId", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const { service } = setup({ registry });
-    const { routes, webServer } = routeHarness();
-    const ctx = { get: (key: string) => (key === "webServer" ? webServer : undefined) } as never;
-    const dispose = registerObservationRoutes(ctx, service);
-
-    const stopRoute = routes.get("/bsk-observation/stop");
-    const res = fakeRes();
-    const emptyReq = fakeReq({
-      method: "POST",
-      headers: { host: "127.0.0.1:3999", "content-type": "application/json" },
-      on: (event: string, fn: (chunk?: string) => void) => {
-        if (event === "data") fn("{}");
-        if (event === "end") fn();
-      },
-    });
-    await stopRoute?.handler(emptyReq, res.res as never);
-    expect(res.res.status).toBe(400);
-    expect(registry.isOwned("s1")).toBe(true);
-
-    dispose();
-    service.dispose();
-  });
-
   it("fences off non-loopback, cross-site, and simple-request traffic", async () => {
     const registry = new SessionRegistry(5);
     own(registry, "s1");

packages/i18n/src/locales/en-US/extension.json

@@ -48,7 +48,7 @@
     "record": {
       "sectionTitle": "Action recording",
       "cardDesc": "Record your actions for Agent reference",
-      "sectionHint": "Generates a recording instruction — send it to your Agent to start recording your actions; the Agent can then use the resulting trace bundle to automate similar tasks.",
+      "sectionHint": "Generates a recording instruction — send it to your Agent to start recording your actions; the Agent can then use the recording to automate similar tasks.",
       "topicLabel": "Topic (optional)",
       "topicPlaceholder": "e.g. Publish an article",
       "startUrlLabel": "Starting URL (optional)",
@@ -56,7 +56,7 @@
       "copyButton": "Copy recording instructions",
       "copied": "Copied",
       "hintDisconnected": "Available when connected",
-      "promptTemplate": "Use BrowserSkill's `bsk` CLI to record the browser actions I'm about to demonstrate.\n\nSteps:\n1. Run: {{command}}\n2. Once you confirm it's started, I'll operate in the opened window myself.\n3. After I click Finish, read the written `./trace` bundle (`trace.json` + `states/`) and summarize what I did."
+      "promptTemplate": "Use BrowserSkill's `bsk` CLI to record the browser actions I'm about to demonstrate.\n\nSteps:\n1. Run: {{command}}\n2. Once you confirm it's started, I'll operate in the opened window myself.\n3. After I click Finish, read the returned trace.json and summarize the actions (pages + steps); don't re-run or \"verify\"."
     }
   },
   "controlOverlay": {

packages/i18n/src/locales/zh-CN/extension.json

@@ -48,7 +48,7 @@
     "record": {
       "sectionTitle": "操作录制",
       "cardDesc": "录制你的操作，供 Agent 参考",
-      "sectionHint": "生成一段录制指令，发给 Agent 后可以启动插件录制用户操作，之后 Agent 可以参考写出的 trace 目录包自动完成同类任务。",
+      "sectionHint": "生成一段录制指令，发给 Agent 后可以启动插件录制用户操作，之后 Agent 可以参考录制结果自动完成同类任务。",
       "topicLabel": "操作主题（可选）",
       "topicPlaceholder": "例如：发布一篇文章",
       "startUrlLabel": "起始网址（可选）",
@@ -56,7 +56,7 @@
       "copyButton": "复制录制指令",
       "copied": "已复制",
       "hintDisconnected": "连接后可用",
-      "promptTemplate": "用 BrowserSkill 的 `bsk` CLI 录制我接下来的浏览器操作。\n\n步骤：\n1. 执行：{{command}}\n2. 你确认已开始后，我会在打开的窗口里自己操作。\n3. 我点“结束”后，读取写出的 `./trace` 目录包（`trace.json` + `states/`），总结我做了什么。"
+      "promptTemplate": "用 BrowserSkill 的 `bsk` CLI 录制我接下来的浏览器操作。\n\n步骤：\n1. 执行：{{command}}\n2. 你确认已开始后，我会在打开的窗口里自己操作。\n3. 我点“结束”后，读取返回的 trace.json 并总结操作（pages + steps），不要重跑或“验证”。"
     }
   },
   "controlOverlay": {

skill/SKILL.md

@@ -265,27 +265,19 @@ retry — complete the task autonomously or stop gracefully.
 
 ### Recording — `bsk record`
 
-Capture the user's own actions in the Agent Window to a **trace bundle**, for later LLM-driven automation. New CLI builds request **trace v3** (page observations + action chain); older extensions may still return **trace v2** (actions only), which the CLI exports as a single `trace.json` without `states/`.
+Capture the user's own actions in the Agent Window to a `trace.json`, for later LLM-driven automation:
 
 ```bash
-bsk record start --browser <instance-id-or-label> \
-  [--url https://…] [--purpose "publish a wiki doc"] \
-  [--max-page-tokens 3000] [--redact-values] \
-  [--output trace]
+bsk record start --browser <instance-id-or-label> [--url https://…] [--purpose "publish a wiki doc"] [--output trace.json]
 # `--url` is optional; default https://example.com/ when omitted (must be http(s)).
-# Blocks until the user clicks Finish in the recording panel, then writes:
-#   trace/trace.json    — action chain (+ state index when v3)
-#   trace/states/       — v3 only: one `sN.txt` observe snapshot per settled page state
+# Blocks until the user clicks Finish in the recording panel, then writes ./trace.json and closes the window.
 
-bsk record stop [--output trace]   # terminal fallback if the browser panel is unavailable
+bsk record stop [--output trace.json]   # terminal fallback if the browser panel is unavailable
 ```
 
-- **v3 bundle (preferred):** `--output` is a directory (default `./trace`) containing `trace.json` and `states/`. `trace.json` lists `states[]` (page observation ids) and `steps[]` (each step binds `state` = observe snapshot *before* the action and `result.state` = snapshot *after* settle). Page bodies live in `states/sN.txt` using the same VOM format as `bsk observe`.
-- **v2 fallback:** when the connected extension is older, export may contain only legacy `trace.json` with `pages[]` action context and no `states/` observation files. Update the extension for full v3 bundles.
-- Each `states[]` entry is one **settled page observation** (captured after recording start, navigation landing, or action settle — not on a timer).
-- `target.ref` values like `@e12` exist **only inside** the bundle for disambiguation; do **not** copy `@eN` refs into SKILL.md or agent runbooks — use visible names from the observation text instead.
+- The trace is a **record-only action log** (a `pages[]` dictionary + `navigate`/`click`/`fill`/`select`/`press` steps with `target` descriptors). It records *what the user did*; deciding which inputs are variable is left to the executing agent.
 - `--purpose` is optional context metadata; it does **not** change what gets captured.
-- `--redact-values` masks all form values in page files as `[filled]` / `[empty]`.
+- There is **no** `bsk replay` — to redo a flow, read the trace and reuse the existing `session` / `snapshot` / `@eN` / `click` / `fill` tools. Follow **Stop when the goal is met**.
 - Do **not** record on banking/SSO/password-manager pages; passwords are redacted but traces may still contain sensitive text.
 
 ## Error handling