docs(dsh): clarify observation subscription and snapshot contracts

fix: recover navigation from cross-extension CDP restrictions

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

@@ -49,6 +49,47 @@ describe("ToolDispatcher", () => {
     vi.unstubAllGlobals();
   });
 
+  it.each([
+    "tool.snapshot",
+    "tool.evaluate",
+    "tool.get_html",
+    "tool.console",
+  ])("annotates Chrome extension-access failures from %s", async (method) => {
+    const tab = { id: 7, windowId: 4242, active: true, url: "https://example.test" };
+    vi.stubGlobal("chrome", {
+      tabs: {
+        get: vi.fn(async () => tab),
+        query: vi.fn(async () => [tab]),
+      },
+    });
+    const { transport, sent, deliver } = fakeTransport();
+    const sessions = new SessionManager({
+      agentWindow: {
+        create: vi.fn(async () => 4242),
+        remove: vi.fn(),
+        ensureActiveTab: vi.fn(),
+      },
+    });
+    await sessions.start("test");
+    const error = new Error("Cannot access a chrome-extension:// URL of different extension");
+    const cdp = {
+      send: vi.fn().mockRejectedValue(error),
+      ensureConsoleCapture: vi.fn().mockRejectedValue(error),
+      consoleEntriesSince: vi.fn(),
+    } as unknown as TestDispatcherCdp;
+    const dispatcher = new ToolDispatcher({ transport, sessions, cdp });
+    dispatcher.start();
+    deliver(makeRequest(method, { session_id: "test", expression: "document.title" }));
+    await vi.waitFor(() => expect(sent).toHaveLength(1));
+    expect(sent[0]).toMatchObject({
+      error: {
+        code: "cdp_failed",
+        data: { reason: "cdp_extension_access_denied" },
+      },
+    });
+    dispatcher.stop();
+  });
+
   it("uses the configured recording runtime for start and stop", async () => {
     const { transport, sent, deliver } = fakeTransport();
     const sessions = new SessionManager({

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

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import type { RpcError } from "@/transport/types";
+import { cdpError, classifyCdpError } from "../errors";
+
+const denied = "Cannot access a chrome-extension:// URL of different extension";
+
+describe("CDP extension access errors", () => {
+  it("classifies both Chrome Error instances and string failures", () => {
+    for (const error of [new Error(denied), denied]) {
+      expect(cdpError(error)).toEqual({
+        code: "cdp_failed",
+        message: denied,
+        data: { reason: "cdp_extension_access_denied" },
+      });
+    }
+  });
+
+  it("preserves transfer outcome and cleanup instructions when CDP was denied", () => {
+    const error: RpcError = {
+      code: "cdp_failed",
+      message: denied,
+      data: {
+        reason: "transfer_outcome_unknown",
+        effect_state: "unknown",
+        cleanup_state: "failed",
+      },
+    };
+    expect(classifyCdpError(error)).toBe(error);
+  });
+
+  it("leaves other error codes and unrelated debugger failures unchanged", () => {
+    for (const error of [
+      { code: "permission_denied", message: denied },
+      { code: "cdp_failed", message: "Another debugger is already attached" },
+    ] satisfies RpcError[]) {
+      expect(classifyCdpError(error)).toBe(error);
+    }
+  });
+});

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

@@ -0,0 +1,573 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SessionManager } from "@/session-manager/manager";
+import type { CdpRunner } from "@/tools/shared";
+import { handleFill } from "../interaction";
+
+interface ScriptParams {
+  functionDeclaration: string;
+  arguments?: Array<{ value: unknown }>;
+}
+
+async function setup(markup = '<input value="old">') {
+  document.body.innerHTML = markup;
+  const element = document.body.firstElementChild as HTMLInputElement;
+  const manager = new SessionManager({
+    agentWindow: {
+      create: async () => 100,
+      remove: async () => {},
+      ensureActiveTab: async () => 4,
+    },
+  });
+  const ctx = await manager.start("aa11");
+  ctx.refStore.set("e1", 12, { tabId: 4 });
+  const script = vi.fn(async (params: ScriptParams): Promise<unknown> => {
+    try {
+      const fn = new Function(`return (${params.functionDeclaration})`)();
+      return {
+        result: {
+          value: await fn.apply(
+            element,
+            (params.arguments ?? []).map((arg) => arg.value),
+          ),
+        },
+      };
+    } catch {
+      return { exceptionDetails: { text: "test page script failed" } };
+    }
+  });
+  // Number/email controls have a browser caret even though their selection
+  // getters return null. Model that caret instead of assuming it is at the end.
+  const hiddenCaret = { start: 0, end: 0 };
+  const moveToEnd = vi.fn(async () => {
+    if (typeof element.selectionStart === "number") {
+      element.setSelectionRange(element.value.length, element.value.length);
+    } else {
+      hiddenCaret.start = hiddenCaret.end = element.value.length;
+    }
+  });
+  const insert = vi.fn(async (text: string) => {
+    const focused = document.activeElement as HTMLInputElement;
+    if (focused.readOnly || focused.disabled) return;
+    const start = focused.selectionStart ?? hiddenCaret.start;
+    const end = focused.selectionEnd ?? hiddenCaret.end;
+    const value = focused.value.slice(0, start) + text + focused.value.slice(end);
+    focused.value = focused.maxLength >= 0 ? value.slice(0, focused.maxLength) : value;
+    hiddenCaret.start = hiddenCaret.end = Math.min(start + text.length, focused.value.length);
+    focused.dispatchEvent(new Event("input", { bubbles: true }));
+  });
+  const release = vi.fn(async () => ({}));
+  const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
+    switch (method) {
+      case "DOM.describeNode":
+        return {
+          node: {
+            nodeName: element.tagName,
+            attributes: Array.from(element.attributes).flatMap((attr) => [attr.name, attr.value]),
+          },
+        };
+      case "DOM.scrollIntoViewIfNeeded":
+        return {};
+      case "DOM.focus":
+        element.focus();
+        return {};
+      case "DOM.resolveNode":
+        return { object: { objectId: "fill-target" } };
+      case "Runtime.callFunctionOn":
+        return script(params as ScriptParams);
+      case "Input.insertText":
+        await insert((params as { text: string }).text);
+        return {};
+      case "Input.dispatchKeyEvent":
+        if ((params as { commands?: string[] }).commands?.includes("moveToEndOfDocument")) {
+          await moveToEnd();
+        }
+        return {};
+      case "Runtime.releaseObject":
+        return release();
+      default:
+        throw new Error(`unexpected ${method}`);
+    }
+  });
+  return {
+    element,
+    hiddenCaret,
+    moveToEnd,
+    script,
+    insert,
+    release,
+    send,
+    fill: (value = "hello", clearBefore = true, signal?: AbortSignal) =>
+      handleFill(
+        manager,
+        { session_id: "aa11", ref: "e1", value, clear_before: clearBefore },
+        {
+          cdp: { send: send as CdpRunner["send"] },
+          tabsApi: {
+            get: async (id) => ({ id, windowId: 100, active: true }) as chrome.tabs.Tab,
+            query: async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab],
+          },
+          signal,
+        },
+      ),
+  };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  document.body.innerHTML = "";
+});
+
+describe("fill result verification", () => {
+  it.each([
+    "readonly",
+    "disabled",
+  ])("preserves a %s field before rejecting it", async (attribute) => {
+    const h = await setup(`<input ${attribute} value="old">`);
+    expect(await h.fill()).toMatchObject({
+      code: "invalid_params",
+      data: { reason: "target_not_fillable" },
+    });
+    expect(h.element.value).toBe("old");
+    expect(h.insert).not.toHaveBeenCalled();
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    "checkbox",
+    "radio",
+    "range",
+    "date",
+    "file",
+  ])("rejects an unsupported %s input before clearing", async (type) => {
+    const h = await setup(`<input type="${type}">`);
+    const before = h.element.value;
+    expect(await h.fill()).toMatchObject({
+      code: "invalid_params",
+      data: { reason: "target_not_fillable" },
+    });
+    expect(h.element.value).toBe(before);
+    expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it("rejects an overlong value before clearing", async () => {
+    const h = await setup('<input maxlength="3" value="old">');
+    expect(await h.fill()).toMatchObject({
+      code: "invalid_params",
+      message: /maxlength/,
+      data: { reason: "fill_value_invalid" },
+    });
+    expect(h.element.value).toBe("old");
+    expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    true,
+    false,
+  ])("classifies a DOM.focus rejection on a disabled=%s target", async (disabled) => {
+    const h = await setup(`<input ${disabled ? "disabled" : ""} value="old">`);
+    const send = h.send.getMockImplementation()!;
+    h.send.mockImplementation(async (tabId, method, params) => {
+      if (method === "DOM.focus") throw new Error("Element is not focusable");
+      return send(tabId, method, params);
+    });
+    expect(await h.fill()).toMatchObject({
+      code: disabled ? "invalid_params" : "cdp_failed",
+      data: { reason: disabled ? "target_not_fillable" : "fill_failed" },
+    });
+    expect(h.element.value).toBe("old");
+    expect(h.insert).not.toHaveBeenCalled();
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("fills a background document without requiring foreground browser focus", async () => {
+    const h = await setup();
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    expect(await h.fill()).toMatchObject({ value_length: 5 });
+    expect(h.element.value).toBe("hello");
+  });
+
+  it("restores focus once after clearing without typing into another field", async () => {
+    const h = await setup();
+    const other = document.createElement("input");
+    document.body.append(other);
+    h.element.addEventListener("input", () => other.focus());
+    expect(await h.fill()).toMatchObject({ value_length: 5 });
+    expect(h.element.value).toBe("hello");
+    expect(other.value).toBe("");
+    expect(h.send.mock.calls.filter(([, method]) => method === "DOM.focus")).toHaveLength(2);
+  });
+
+  it.each([
+    "focus",
+    "value",
+  ])("rechecks %s after restoring focus, without retrying again", async (action) => {
+    const h = await setup();
+    const other = document.createElement("input");
+    document.body.append(other);
+    h.element.addEventListener(
+      "input",
+      () => {
+        other.focus();
+        h.element.addEventListener("focus", () => {
+          if (action === "focus") queueMicrotask(() => other.focus());
+          else h.element.value = "changed";
+        });
+      },
+      { once: true },
+    );
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: action === "focus" ? "fill_focus_lost" : "fill_target_changed" },
+    });
+    expect(other.value).toBe("");
+    expect(h.insert).not.toHaveBeenCalled();
+    expect(h.send.mock.calls.filter(([, method]) => method === "DOM.focus")).toHaveLength(2);
+  });
+
+  it.each([
+    "remove",
+    "readonly",
+    "restore",
+    "microtask-restore",
+  ])("stops when clearing causes the page to %s the target", async (action) => {
+    const h = await setup();
+    h.element.addEventListener("input", () => {
+      if (action === "remove") h.element.remove();
+      if (action === "readonly") h.element.readOnly = true;
+      if (action === "restore") h.element.value = "restored";
+      if (action === "microtask-restore")
+        queueMicrotask(() => {
+          h.element.value = "restored";
+        });
+    });
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_target_changed" },
+    });
+    expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it("fails when insertText is acknowledged without changing the value", async () => {
+    const h = await setup();
+    h.insert.mockImplementation(async () => {});
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_value_mismatch" },
+    });
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("detects truncation when maxlength changes after preparation", async () => {
+    const h = await setup();
+    h.element.addEventListener(
+      "input",
+      () => {
+        h.element.maxLength = 3;
+      },
+      { once: true },
+    );
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_value_mismatch" },
+    });
+    expect(h.element.value).toBe("hel");
+  });
+
+  it.each([
+    "input",
+    "change",
+    "microtask-change",
+  ])("detects a value reverted by the %s handler", async (event) => {
+    const h = await setup();
+    h.element.addEventListener(event === "microtask-change" ? "change" : event, () => {
+      if (event === "microtask-change")
+        queueMicrotask(() => {
+          h.element.value = "";
+        });
+      else h.element.value = "";
+    });
+    expect(await h.fill()).toMatchObject({ code: "cdp_failed", message: /expected value/ });
+  });
+
+  it("compares content rather than length without including field values in the error", async () => {
+    const h = await setup('<input type="password">');
+    h.element.addEventListener("change", () => {
+      h.element.value = "other-secret";
+    });
+    const result = await h.fill("given-secret");
+    expect(result).toMatchObject({ code: "cdp_failed", message: /expected value/ });
+    expect(JSON.stringify(result)).not.toMatch(/given-secret|other-secret/);
+  });
+
+  it("does not report success for a target replaced by a change handler", async () => {
+    const h = await setup();
+    h.element.addEventListener("change", () => h.element.replaceWith(h.element.cloneNode()));
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_target_changed" },
+    });
+  });
+
+  it.each([
+    1, 2, 3, 4, 5,
+  ])("rejects script exceptions at phase %s and releases the target", async (phase) => {
+    const h = await setup();
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    const run = h.script.getMockImplementation()!;
+    let count = 0;
+    h.script.mockImplementation(async (params) =>
+      ++count === phase ? { exceptionDetails: { text: "page secret" } } : run(params),
+    );
+    const result = await h.fill();
+    expect(result).toMatchObject({ code: "cdp_failed", data: { reason: "fill_failed" } });
+    expect(JSON.stringify(result)).not.toContain("page secret");
+    if (phase <= 3) expect(h.insert).not.toHaveBeenCalled();
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it.each([1, 2, 3, 5])("rejects missing results at phase %s", async (phase) => {
+    const h = await setup();
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    const run = h.script.getMockImplementation()!;
+    let count = 0;
+    h.script.mockImplementation(async (params) =>
+      ++count === phase ? { result: { type: "undefined" } } : run(params),
+    );
+    expect(await h.fill()).toMatchObject({ code: "cdp_failed" });
+    if (phase <= 3) expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it.each(["input", "change"])("checks state after nested microtasks from %s", async (event) => {
+    const h = await setup();
+    h.element.addEventListener(event, () => {
+      queueMicrotask(() =>
+        queueMicrotask(() => {
+          h.element.value = "reverted";
+        }),
+      );
+    });
+    expect(await h.fill()).toMatchObject({ code: "cdp_failed" });
+    if (event === "input") expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    "<input>",
+    '<input type="password">',
+    "<textarea></textarea>",
+  ])("verifies successful text in %s", async (markup) => {
+    const h = await setup(markup);
+    expect(await h.fill("你好🙂")).toMatchObject({ value_length: 4 });
+    expect(h.element.value).toBe("你好🙂");
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("verifies append against the old value plus the requested text", async () => {
+    const h = await setup();
+    h.element.focus();
+    h.element.setSelectionRange(3, 3);
+    expect(await h.fill("!", false)).toMatchObject({ value_length: 4 });
+    expect(h.element.value).toBe("old!");
+  });
+
+  it.each([
+    ["<textarea></textarea>", "a\r\nb", "a\nb"],
+    ["<input>", "a\nb", "a b"],
+    ["<input>", "a\r\nb", "a b"],
+    [
+      '<input type="email" multiple>',
+      " a@example.com , b@example.com ",
+      "a@example.com,b@example.com",
+    ],
+  ])("accepts native normalization for %s", async (markup, requested, normalized) => {
+    if (markup.startsWith("<textarea")) {
+      // Happy DOM does not implement Chrome's textarea line-ending normalization.
+      const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")!.set!;
+      vi.spyOn(HTMLTextAreaElement.prototype, "value", "set").mockImplementation(function (
+        this: HTMLTextAreaElement,
+        value,
+      ) {
+        setter.call(this, value.replace(/\r\n?/g, "\n"));
+      });
+    }
+    const h = await setup(markup);
+    h.insert.mockImplementation(async () => {
+      h.element.value = normalized;
+    });
+    expect(await h.fill(requested)).toMatchObject({ value_length: normalized.length });
+  });
+
+  it("does not count an editable padding break as an extra typed character", async () => {
+    const h = await setup('<div contenteditable="true" tabindex="0"></div>');
+    // These two layout/editability properties are missing in Happy DOM.
+    let innerText = "";
+    Object.defineProperty(h.element, "isContentEditable", { get: () => true });
+    Object.defineProperty(h.element, "innerText", { get: () => innerText });
+    h.insert.mockImplementation(async () => {
+      h.element.innerHTML = "one<div><br></div>";
+      innerText = "one\n\n";
+    });
+    expect(await h.fill("one\n")).toMatchObject({ value_length: 4 });
+  });
+
+  it.each([
+    [0, 0],
+    [1, 1],
+    [0, 3],
+  ])("appends after moving selection %s:%s to the end", async (start, end) => {
+    const h = await setup();
+    h.element.focus();
+    h.element.setSelectionRange(start, end);
+    expect(await h.fill("🙂", false)).toMatchObject({ value_length: 5 });
+    expect(h.element.value).toBe("old🙂");
+  });
+
+  it.each(
+    ["number", "email"].flatMap((type) =>
+      [
+        [0, 0],
+        [1, 1],
+        [0, 2],
+      ].map(([start, end]) => ({ type, start, end })),
+    ),
+  )("appends to $type from selection $start:$end without using its unsupported API", async ({
+    type,
+    start,
+    end,
+  }) => {
+    const h = await setup(`<input type="${type}" value="12">`);
+    Object.assign(h.hiddenCaret, { start, end });
+    vi.spyOn(h.element, "selectionStart", "get").mockReturnValue(null);
+    vi.spyOn(h.element, "selectionEnd", "get").mockReturnValue(null);
+    const selection = vi.spyOn(h.element, "setSelectionRange").mockImplementation(() => {
+      throw new DOMException("unsupported", "InvalidStateError");
+    });
+    expect(await h.fill("3", false)).toMatchObject({ value_length: 3 });
+    expect(h.element.value).toBe("123");
+    expect(selection).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    "number",
+    "email",
+  ])("does not report successful %s append when the caret command is ignored", async (type) => {
+    const h = await setup(`<input type="${type}" value="12">`);
+    vi.spyOn(h.element, "selectionStart", "get").mockReturnValue(null);
+    vi.spyOn(h.element, "selectionEnd", "get").mockReturnValue(null);
+    h.moveToEnd.mockResolvedValueOnce(undefined);
+    expect(await h.fill("3", false)).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_value_mismatch" },
+    });
+    expect(h.element.value).toBe("312");
+    expect(h.insert).toHaveBeenCalledOnce();
+  });
+
+  it("rejects invalid number text before clearing", async () => {
+    const h = await setup('<input type="number" value="12">');
+    expect(await h.fill("abc")).toMatchObject({
+      code: "invalid_params",
+      data: { reason: "fill_value_invalid" },
+    });
+    expect(h.element.value).toBe("12");
+    expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it("reports page formatting as unconfirmed without retrying the write", async () => {
+    const h = await setup();
+    h.element.addEventListener("change", () => {
+      h.element.value = h.element.value.toUpperCase();
+    });
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_value_mismatch" },
+    });
+    expect(h.element.value).toBe("HELLO");
+    expect(h.insert).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    ["focus", false],
+    ["focus", true],
+    ["value", false],
+    ["value", true],
+    ["cancel", false],
+    ["cancel", true],
+    ["throw", false],
+    ["throw", true],
+  ] as const)("stops when positioning triggers %s (clear=%s) and releases the key", async (action, clearBefore) => {
+    const h = await setup();
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    const controller = new AbortController();
+    const other = document.createElement("input");
+    document.body.append(other);
+    const send = h.send.getMockImplementation()!;
+    h.send.mockImplementation(async (tabId, method, params) => {
+      const reply = await send(tabId, method, params);
+      if (
+        method === "Input.dispatchKeyEvent" &&
+        (params as { type: string }).type === "rawKeyDown"
+      ) {
+        if (action === "focus") other.focus();
+        if (action === "value") h.element.value = "changed";
+        if (action === "cancel") controller.abort();
+        if (action === "throw") throw new Error("dispatch failed");
+      }
+      return reply;
+    });
+    const result = await h.fill("!", clearBefore, controller.signal);
+    expect(result).toMatchObject({ code: action === "cancel" ? "cancelled" : "cdp_failed" });
+    expect(h.insert).not.toHaveBeenCalled();
+    expect(other.value).toBe("");
+    expect(h.send).toHaveBeenCalledWith(
+      4,
+      "Input.dispatchKeyEvent",
+      expect.objectContaining({ type: "keyUp" }),
+    );
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it.each([true, false])("verifies an empty request with clear_before=%s", async (clearBefore) => {
+    const h = await setup();
+    expect(await h.fill("", clearBefore)).toMatchObject({ value_length: clearBefore ? 0 : 3 });
+    expect(h.element.value).toBe(clearBefore ? "" : "old");
+    expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it("cancels after insertion without sending change events", async () => {
+    const h = await setup();
+    const controller = new AbortController();
+    h.insert.mockImplementation(async () => controller.abort());
+    expect(await h.fill("hello", true, controller.signal)).toMatchObject({ code: "cancelled" });
+    expect(h.script).toHaveBeenCalledTimes(2);
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("cancels after resolving the remote object without clearing the field", async () => {
+    const h = await setup();
+    const controller = new AbortController();
+    const send = h.send.getMockImplementation()!;
+    h.send.mockImplementation(async (tabId, method, params) => {
+      const result = await send(tabId, method, params);
+      if (method === "DOM.resolveNode") controller.abort();
+      return result;
+    });
+    expect(await h.fill("hello", true, controller.signal)).toMatchObject({ code: "cancelled" });
+    expect(h.element.value).toBe("old");
+    expect(h.script).not.toHaveBeenCalled();
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("honors cancellation during verification", async () => {
+    const h = await setup();
+    const controller = new AbortController();
+    h.element.addEventListener("change", () => controller.abort());
+    expect(await h.fill("hello", true, controller.signal)).toMatchObject({ code: "cancelled" });
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("keeps the verified outcome when releasing the remote object fails", async () => {
+    const h = await setup();
+    h.release.mockRejectedValueOnce(new Error("target closed"));
+    expect(await h.fill()).toMatchObject({ value_length: 5 });
+  });
+});

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

@@ -540,6 +540,21 @@ describe("handleHover", () => {
   });
 });
 
+function successfulFillScript(params: unknown) {
+  const script = params as { arguments?: Array<{ value: unknown }>; functionDeclaration: string };
+  const args = script.arguments ?? [];
+  return {
+    result: {
+      value:
+        args.length === 2
+          ? { before: "", expected: args[0].value }
+          : script.functionDeclaration.startsWith("function(expected)")
+            ? { connected: true, matches: true, valueLength: String(args[0].value).length }
+            : "ready",
+    },
+  };
+}
+
 describe("handleFill", () => {
   it("returns not_found for unknown ref", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
@@ -586,7 +601,8 @@ describe("handleFill", () => {
       "DOM.scrollIntoViewIfNeeded": () => ({}),
       "DOM.focus": () => ({}),
       "DOM.resolveNode": () => ({ object: { objectId: "obj-1" } }),
-      "Runtime.callFunctionOn": () => ({ result: { type: "undefined" } }),
+      "Runtime.callFunctionOn": successfulFillScript,
+      "Runtime.releaseObject": () => ({}),
       "Input.insertText": () => ({}),
     });
     const res = await handleFill(
@@ -600,13 +616,12 @@ describe("handleFill", () => {
     expect(res.used_ref).toBe("e1");
     const insert = fake.sent.find((c) => c.method === "Input.insertText");
     expect(insert?.params).toEqual({ text: "hello" });
-    // clear_before defaults to true → callFunctionOn invoked once to
-    // clear, once to fire input/change after typing.
+    // Foreground replacement needs no extra caret-positioning round trip.
     const callFns = fake.sent.filter((c) => c.method === "Runtime.callFunctionOn");
-    expect(callFns.length).toBeGreaterThanOrEqual(2);
+    expect(callFns).toHaveLength(4);
   });
 
-  it("clear_before=false skips the wipe call", async () => {
+  it("passes clear_before=false to preparation and verifies the result", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");
     ctx.refStore.set("e1", 1, { tabId: 4 });
@@ -618,12 +633,12 @@ describe("handleFill", () => {
       "DOM.focus": () => ({}),
       "DOM.resolveNode": () => ({ object: { objectId: "obj-2" } }),
       "Runtime.callFunctionOn": (p) => {
-        const fn = (p as { functionDeclaration?: string }).functionDeclaration ?? "";
-        // No "this.value = ''" clearing on a no-clear path; only the
-        // post-input dispatchEvent.
-        expect(fn).not.toMatch(/this\.value\s*=\s*''/);
-        return { result: { type: "undefined" } };
+        const args = (p as { arguments?: Array<{ value: unknown }> }).arguments ?? [];
+        if (args.length === 2) expect(args[1].value).toBe(false);
+        return successfulFillScript(p);
       },
+      "Input.dispatchKeyEvent": () => ({}),
+      "Runtime.releaseObject": () => ({}),
       "Input.insertText": () => ({}),
     });
     const res = await handleFill(
@@ -650,7 +665,8 @@ describe("handleFill", () => {
       "DOM.scrollIntoViewIfNeeded": () => ({}),
       "DOM.focus": () => ({}),
       "DOM.resolveNode": () => ({ object: { objectId: "obj-3" } }),
-      "Runtime.callFunctionOn": () => ({ result: { type: "undefined" } }),
+      "Runtime.callFunctionOn": successfulFillScript,
+      "Runtime.releaseObject": () => ({}),
       "Input.insertText": () => ({}),
     });
     const res = await handleFill(

apps/extension/src/tools/__tests__/navigation-recovery.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it, vi } from "vitest";
+import { SessionManager } from "@/session-manager/manager";
+import type { BrowserNavigationApi } from "../browser-navigation";
+import { handleNavigate, handleReload } from "../navigation";
+import type { CdpRunner } from "../shared";
+
+const denied = "Cannot access a chrome-extension:// URL of different extension";
+const url = "https://example.test/recovered";
+
+function event<T extends (...args: never[]) => void>() {
+  const listeners = new Set<T>();
+  return {
+    listeners,
+    addListener: (listener: T) => listeners.add(listener),
+    removeListener: (listener: T) => listeners.delete(listener),
+    fire: (...args: Parameters<T>) => {
+      for (const listener of [...listeners]) listener(...args);
+    },
+  };
+}
+
+async function fixture() {
+  const manager = new SessionManager({
+    agentWindow: {
+      create: vi.fn(async () => 100),
+      remove: vi.fn(async () => {}),
+      ensureActiveTab: vi.fn(async () => 4),
+    },
+  });
+  await manager.start("test");
+  type Listener = Parameters<BrowserNavigationApi["onCommitted"]["addListener"]>[0];
+  const events = {
+    onCommitted: event<Listener>(),
+    onDOMContentLoaded: event<Listener>(),
+    onCompleted: event<Listener>(),
+    onErrorOccurred: event<Listener>(),
+  };
+  const cdpEvents = event<Parameters<NonNullable<CdpRunner["onEvent"]>>[0]>();
+  const state = { blocked: true, destinationBlocked: false, emitIdle: true };
+  const send = vi.fn(async (_tabId: number, method: string) => {
+    if (state.blocked) throw new Error(denied);
+    if (method === "Page.getFrameTree") {
+      return { frameTree: { frame: { id: "main", loaderId: "new-loader" } } };
+    }
+    if (method === "Runtime.evaluate") return { result: { value: "complete" } };
+    if (method === "Page.setLifecycleEventsEnabled" && state.emitIdle) {
+      cdpEvents.fire({ tabId: 4 }, "Page.lifecycleEvent", {
+        frameId: "main",
+        loaderId: "new-loader",
+        name: "networkIdle",
+      });
+    }
+    if (method === "Page.navigate") return { frameId: "main", loaderId: "new-loader" };
+    return {};
+  });
+  const cdp: CdpRunner = {
+    send: send as CdpRunner["send"],
+    onEvent: (listener) => {
+      cdpEvents.addListener(listener);
+      return { dispose: () => cdpEvents.removeListener(listener) };
+    },
+  };
+  const main = { tabId: 4, frameId: 0, documentId: "new-document" };
+  const navigate = async () => {
+    state.blocked = state.destinationBlocked;
+    events.onCommitted.fire(main);
+    events.onDOMContentLoaded.fire(main);
+    events.onCompleted.fire(main);
+  };
+  const browserNavigation = { ...events, update: vi.fn(navigate), reload: vi.fn(navigate) };
+  const tab = { id: 4, windowId: 100, active: true, url } as chrome.tabs.Tab;
+  const tabsApi = { get: vi.fn(async () => tab), query: vi.fn(async () => [tab]) };
+  const deps = { cdp, tabsApi, browserNavigation, defaultTimeoutMs: 1000 };
+  const expectCleanedUp = () => {
+    for (const entry of Object.values(events)) expect(entry.listeners.size).toBe(0);
+    expect(cdpEvents.listeners.size).toBe(0);
+  };
+  return { manager, deps, state, send, events, main, cdpEvents, expectCleanedUp };
+}
+
+describe("navigation after Chrome denies extension-frame access", () => {
+  it.each([
+    "load",
+    "commit",
+    "domcontentloaded",
+    "networkidle",
+  ] as const)("recovers the same tab with the requested %s checkpoint", async (waitUntil) => {
+    const f = await fixture();
+    const result = await handleNavigate(
+      f.manager,
+      {
+        session_id: "test",
+        url,
+        wait_until: waitUntil,
+      },
+      f.deps,
+    );
+
+    expect(result).toMatchObject({ tab_id: 4, final_url: url, reached: waitUntil });
+    expect(f.deps.browserNavigation.update).toHaveBeenCalledExactlyOnceWith(4, { url });
+    expect(f.send.mock.calls.some(([, method]) => method === "Page.navigate")).toBe(false);
+    expect(f.send).toHaveBeenCalledWith(4, "Page.enable", {});
+    f.expectCleanedUp();
+  });
+
+  it("recovers reload through tabs.reload and preserves hard reload", async () => {
+    const f = await fixture();
+    const result = await handleReload(f.manager, { session_id: "test", hard: true }, f.deps);
+    expect(result).toMatchObject({ tab_id: 4, reached: "load" });
+    expect(f.deps.browserNavigation.reload).toHaveBeenCalledExactlyOnceWith(4, {
+      bypassCache: true,
+    });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("reports the restriction when reload leaves the conflicting frame present", async () => {
+    const f = await fixture();
+    f.state.destinationBlocked = true;
+    const result = await handleReload(f.manager, { session_id: "test" }, f.deps);
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "cdp_extension_access_denied" },
+    });
+    expect(f.deps.browserNavigation.reload).toHaveBeenCalledOnce();
+    f.expectCleanedUp();
+  });
+
+  it("does not fall back for unrelated debugger failures", async () => {
+    const f = await fixture();
+    f.send.mockRejectedValue(new Error("Another debugger is already attached"));
+    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      message: "Another debugger is already attached",
+    });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("does not replay navigation when a dispatched CDP command fails", async () => {
+    const f = await fixture();
+    f.state.blocked = false;
+    const send = f.send.getMockImplementation()!;
+    f.send.mockImplementation(async (tabId, method) => {
+      if (method === "Page.navigate") throw new Error(denied);
+      return send(tabId, method);
+    });
+    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "cdp_extension_access_denied" },
+    });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("keeps the Agent Window guard in front of the recovery", async () => {
+    const f = await fixture();
+    f.deps.tabsApi.get.mockResolvedValue({
+      id: 4,
+      windowId: 200,
+      active: true,
+      url,
+    } as chrome.tabs.Tab);
+    const result = await handleNavigate(f.manager, { session_id: "test", tab_id: 4, url }, f.deps);
+    expect(result).toMatchObject({ code: "permission_denied" });
+    expect(f.send).not.toHaveBeenCalled();
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+  });
+
+  it("ignores old-document, subframe, and other-tab completion events", async () => {
+    const f = await fixture();
+    f.deps.browserNavigation.update.mockImplementation(async () => {});
+    let settled = false;
+    const work = handleNavigate(f.manager, { session_id: "test", url }, f.deps).then((result) => {
+      settled = true;
+      return result;
+    });
+    await vi.waitFor(() => expect(f.deps.browserNavigation.update).toHaveBeenCalledOnce());
+    f.events.onCompleted.fire(f.main);
+    f.events.onCommitted.fire({ ...f.main, tabId: 9 });
+    f.events.onCommitted.fire({ ...f.main, frameId: 1 });
+    f.events.onCompleted.fire(f.main);
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    f.events.onCommitted.fire(f.main);
+    f.events.onCompleted.fire({ ...f.main, documentId: "old-document" });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    f.state.blocked = false;
+    f.events.onCompleted.fire(f.main);
+    expect(await work).toMatchObject({ reached: "load" });
+    f.expectCleanedUp();
+  });
+
+  it("does not infer network idle from a browser load event", async () => {
+    const f = await fixture();
+    f.state.emitIdle = false;
+    const result = await handleNavigate(
+      f.manager,
+      {
+        session_id: "test",
+        url,
+        wait_until: "networkidle",
+        timeout_ms: 10,
+      },
+      f.deps,
+    );
+    expect(result).toMatchObject({ reached: "timeout" });
+    f.expectCleanedUp();
+  });
+
+  it("cleans up browser listeners on timeout", async () => {
+    const f = await fixture();
+    f.deps.browserNavigation.update.mockImplementation(async () => {});
+    const result = await handleNavigate(
+      f.manager,
+      { session_id: "test", url, timeout_ms: 10 },
+      f.deps,
+    );
+    expect(result).toMatchObject({ reached: "timeout" });
+    f.expectCleanedUp();
+  });
+
+  it("does not navigate an already-cancelled request", async () => {
+    const f = await fixture();
+    const result = await handleNavigate(
+      f.manager,
+      { session_id: "test", url },
+      {
+        ...f.deps,
+        signal: AbortSignal.abort(),
+      },
+    );
+    expect(result).toMatchObject({ code: "cancelled" });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("cleans up browser listeners when cancelled after dispatch", async () => {
+    const f = await fixture();
+    const ac = new AbortController();
+    f.deps.browserNavigation.update.mockImplementation(async () => {
+      ac.abort();
+    });
+    const result = await handleNavigate(
+      f.manager,
+      { session_id: "test", url },
+      { ...f.deps, signal: ac.signal },
+    );
+    expect(result).toMatchObject({ code: "cancelled" });
+    expect(f.deps.browserNavigation.update).toHaveBeenCalledOnce();
+    f.expectCleanedUp();
+  });
+
+  it("reports browser navigation errors and releases listeners", async () => {
+    const f = await fixture();
+    f.deps.browserNavigation.update.mockImplementation(async () => {
+      f.events.onErrorOccurred.fire({ ...f.main, error: "net::ERR_NAME_NOT_RESOLVED" });
+    });
+    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
+    expect(result).toMatchObject({ code: "cdp_failed", message: "net::ERR_NAME_NOT_RESOLVED" });
+    f.expectCleanedUp();
+  });
+});

apps/extension/src/tools/browser-navigation.ts

@@ -0,0 +1,110 @@
+import type { RpcError, WaitUntil } from "@/transport/types";
+import { cdpError } from "./errors";
+
+interface NavigationEvent {
+  tabId: number;
+  frameId: number;
+  documentId?: string;
+  error?: string;
+}
+
+interface NavigationEvents {
+  addListener(listener: (details: NavigationEvent) => void): void;
+  removeListener(listener: (details: NavigationEvent) => void): void;
+}
+
+/** Normal browser navigation remains available when chrome.debugger is denied. */
+export interface BrowserNavigationApi {
+  update(tabId: number, props: { url: string }): Promise<unknown>;
+  reload(tabId: number, props: { bypassCache: boolean }): Promise<void>;
+  onCommitted: NavigationEvents;
+  onDOMContentLoaded: NavigationEvents;
+  onCompleted: NavigationEvents;
+  onErrorOccurred: NavigationEvents;
+}
+
+export const chromeBrowserNavigationApi: BrowserNavigationApi = {
+  update: (tabId, props) => chrome.tabs.update(tabId, props),
+  reload: (tabId, props) => chrome.tabs.reload(tabId, props),
+  get onCommitted() {
+    return chrome.webNavigation.onCommitted;
+  },
+  get onDOMContentLoaded() {
+    return chrome.webNavigation.onDOMContentLoaded;
+  },
+  get onCompleted() {
+    return chrome.webNavigation.onCompleted;
+  },
+  get onErrorOccurred() {
+    return chrome.webNavigation.onErrorOccurred;
+  },
+};
+
+export type NavigationOutcome =
+  | { reached: "match" | "timeout" | "cancelled"; lastLifecycle?: string }
+  | { reached: "failed"; error: RpcError };
+
+/** Subscribe before dispatch and ignore the departing document's load events. */
+export async function navigateWithBrowserApi(
+  api: BrowserNavigationApi,
+  tabId: number,
+  action: () => Promise<unknown>,
+  waitUntil: Exclude<WaitUntil, "networkidle">,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<NavigationOutcome> {
+  if (signal?.aborted) return { reached: "cancelled" };
+  if (timeoutMs <= 0) return { reached: "timeout" };
+  let committed = false;
+  let documentId: string | undefined;
+  let lastLifecycle: string | undefined;
+  let finish!: (outcome: NavigationOutcome) => void;
+  const outcome = new Promise<NavigationOutcome>((resolve) => {
+    finish = resolve;
+  });
+  const isMainFrame = (details: NavigationEvent) =>
+    details.tabId === tabId && details.frameId === 0;
+  const onCommitted = (details: NavigationEvent) => {
+    if (!isMainFrame(details)) return;
+    committed = true;
+    documentId = details.documentId;
+    lastLifecycle = "commit";
+    if (waitUntil === "commit") finish({ reached: "match", lastLifecycle });
+  };
+  const onDOMContentLoaded = (details: NavigationEvent) => {
+    if (!isMainFrame(details) || !committed || (documentId && details.documentId !== documentId))
+      return;
+    lastLifecycle = "DOMContentLoaded";
+    if (waitUntil === "domcontentloaded") finish({ reached: "match", lastLifecycle });
+  };
+  const onCompleted = (details: NavigationEvent) => {
+    if (!isMainFrame(details) || !committed || (documentId && details.documentId !== documentId))
+      return;
+    finish({ reached: "match", lastLifecycle: "load" });
+  };
+  const onError = (details: NavigationEvent) => {
+    if (!isMainFrame(details)) return;
+    finish({ reached: "failed", error: cdpError(details.error ?? "browser navigation failed") });
+  };
+  const onAbort = () => finish({ reached: "cancelled", lastLifecycle });
+  const subscriptions = [
+    [api.onCommitted, onCommitted],
+    [api.onDOMContentLoaded, onDOMContentLoaded],
+    [api.onCompleted, onCompleted],
+    [api.onErrorOccurred, onError],
+  ] as const;
+  for (const [event, listener] of subscriptions) event.addListener(listener);
+  signal?.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(() => finish({ reached: "timeout", lastLifecycle }), timeoutMs);
+  try {
+    if (signal?.aborted) return { reached: "cancelled" };
+    await action();
+    return await outcome;
+  } catch (error) {
+    return { reached: "failed", error: cdpError(error) };
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+    for (const [event, listener] of subscriptions) event.removeListener(listener);
+  }
+}

apps/extension/src/tools/dispatcher.ts

@@ -36,6 +36,7 @@ import { isRequestFrame } from "@/transport/types";
 import { handleConsole } from "./console";
 import { handleDownload } from "./download";
 import { type EmulateCdpRunner, handleEmulate } from "./emulate";
+import { classifyCdpError } from "./errors";
 import { handleEvaluate } from "./evaluate";
 import { handleRequestHelp } from "./human-loop";
 import { handleClick, handleFill, handleHover, handlePress, handleSelect } from "./interaction";
@@ -239,7 +240,7 @@ export class ToolDispatcher {
       if (sessionId) this.onBrowserControlResumed?.(sessionId);
       const result = await this.invoke(req, ac.signal);
       if (isRpcError(result)) {
-        body = { id: req.id, error: result };
+        body = { id: req.id, error: classifyCdpError(result) };
       } else {
         body = { id: req.id, result };
         if (req.method === "tool.session_start") {

apps/extension/src/tools/errors.ts

@@ -13,6 +13,34 @@ import type {
 
 export type { RpcErrorData, RpcErrorReason };
 
+/** Chrome checks the whole tab's frame tree, including other extensions' frames. */
+export function isCdpExtensionAccessDenied(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("Cannot access a chrome-extension:// URL of different extension");
+}
+
+/** Preserve more specific reasons, especially file-transfer outcome/cleanup details. */
+export function classifyCdpError(error: RpcError): RpcError {
+  if (
+    error.code !== "cdp_failed" ||
+    error.data?.reason ||
+    !isCdpExtensionAccessDenied(error.message)
+  ) {
+    return error;
+  }
+  return {
+    ...error,
+    data: { ...error.data, reason: "cdp_extension_access_denied" },
+  };
+}
+
+export function cdpError(error: unknown): RpcError {
+  return classifyCdpError({
+    code: "cdp_failed",
+    message: error instanceof Error ? error.message : String(error),
+  });
+}
+
 export interface TransferErrorOptions {
   effectState: TransferEffectState;
   phase: string;

apps/extension/src/tools/interaction.ts

@@ -609,6 +609,53 @@ type SelectMutationResult =
 // tool.fill
 // ---------------------------------------------------------------------------
 
+type FillFailureReason =
+  | "target_not_fillable"
+  | "fill_value_invalid"
+  | "fill_target_changed"
+  | "fill_focus_lost"
+  | "fill_value_mismatch"
+  | "fill_failed";
+
+type FillPreparation =
+  | { before: string; expected: string }
+  | { reason: FillFailureReason; error: string };
+
+type FillReadiness = "ready" | "background" | "fill_target_changed" | "fill_focus_lost";
+
+function fillError(reason: FillFailureReason, message: string): RpcError {
+  return rpcError(
+    reason === "target_not_fillable" || reason === "fill_value_invalid"
+      ? "invalid_params"
+      : "cdp_failed",
+    reason,
+    message,
+  );
+}
+
+interface FillScriptReply<T> {
+  result?: { value?: T };
+  exceptionDetails?: unknown;
+}
+
+const FILL_EDITABLE_FUNCTION = `function() {
+  const tag = this.tagName.toLowerCase();
+  const supported = tag === 'input'
+    ? ['text', 'search', 'tel', 'url', 'email', 'password', 'number'].includes(this.type)
+    : tag === 'textarea' || this.isContentEditable;
+  return this.isConnected && supported && !this.readOnly && !this.matches(':disabled');
+}`;
+
+// Chrome renders a trailing editable newline with an empty <div><br></div>.
+// innerText includes the padding break; it is not an extra typed character.
+const FILL_VALUE_FUNCTION = `function() {
+  if (!this.isContentEditable) return this.value;
+  const value = this.innerText;
+  const tail = this.lastChild;
+  const padding = tail && tail.nodeName === 'DIV' && tail.childNodes.length === 1 && tail.firstChild.nodeName === 'BR';
+  return padding && value.endsWith('\\n\\n') ? value.slice(0, -1) : value;
+}`;
+
 export async function handleFill(
   manager: SessionManager,
   params: FillParams,
@@ -660,12 +707,8 @@ export async function handleFill(
     if (throwIfAborted(deps.signal)) {
       return { code: "cancelled", message: "fill aborted" };
     }
-    await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
   } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
+    return fillError("fill_failed", err instanceof Error ? err.message : String(err));
   }
 
   if (throwIfAborted(deps.signal)) {
@@ -678,57 +721,252 @@ export async function handleFill(
   const clearBefore = params.clear_before ?? true;
 
   try {
-    if (clearBefore) {
-      // Clear input/textarea value or wipe contenteditable innerText,
-      // then fire `input` so frameworks observe the empty state.
-      await nodeCdp.send(target.tabId, "Runtime.callFunctionOn", {
-        objectId,
-        functionDeclaration: `function() {
-          if (this.isContentEditable) { this.textContent = ''; }
-          else {
-            const proto = this instanceof HTMLTextAreaElement
-              ? HTMLTextAreaElement.prototype
-              : HTMLInputElement.prototype;
-            const descriptor = Object.getOwnPropertyDescriptor(proto, 'value');
-            if (descriptor && descriptor.set) descriptor.set.call(this, '');
-            else this.value = '';
-          }
-          this.dispatchEvent(new Event('input', { bubbles: true }));
-        }`,
-        returnByValue: true,
-      });
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    try {
+      await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
+    } catch (error) {
+      // Chrome rejects DOM.focus for disabled controls, including inherited
+      // fieldset state. Classify the live target before treating this as a
+      // browser failure; the normal path needs no extra round trip.
+      const editable = await nodeCdp.send<FillScriptReply<boolean>>(
+        target.tabId,
+        "Runtime.callFunctionOn",
+        { objectId, functionDeclaration: FILL_EDITABLE_FUNCTION, returnByValue: true },
+      );
+      if (throwIfAborted(deps.signal)) {
+        return { code: "cancelled", message: "fill aborted" };
+      }
+      if (!editable.exceptionDetails && editable.result?.value === false) {
+        return fillError(
+          "target_not_fillable",
+          "fill target is not editable or its input type is unsupported",
+        );
+      }
+      throw error;
     }
     if (throwIfAborted(deps.signal)) {
       return { code: "cancelled", message: "fill aborted" };
     }
+    // Check editability before clearing. Keep the expected result tied to
+    // this object, including the existing value on the append path.
+    const prepared = await nodeCdp.send<FillScriptReply<FillPreparation>>(
+      target.tabId,
+      "Runtime.callFunctionOn",
+      {
+        objectId,
+        functionDeclaration: `function(value, clearBefore) {
+          const tag = this.tagName.toLowerCase();
+          const native = tag === 'input' || tag === 'textarea';
+          if (!(${FILL_EDITABLE_FUNCTION}).call(this)) return { reason: 'target_not_fillable', error: 'fill target is not editable or its input type is unsupported' };
+          if (this.getRootNode().activeElement !== this) return { reason: 'fill_focus_lost', error: 'fill target does not have focus' };
+          const before = clearBefore ? '' : (${FILL_VALUE_FUNCTION}).call(this);
+          let expected = before + value;
+          if (native) {
+            // Use the browser's own value sanitization (e.g. textarea
+            // line endings) without changing the live control.
+            const normalizer = this.ownerDocument.createElement(tag);
+            if (tag === 'input') {
+              normalizer.type = this.type;
+              normalizer.multiple = this.multiple;
+            }
+            // insertText treats line breaks in a single-line input as spaces.
+            if (tag === 'input') expected = expected.replace(/\\r\\n|\\r|\\n/g, ' ');
+            normalizer.value = expected;
+            if (expected !== '' && normalizer.value === '' && this.type === 'number') {
+              return { reason: 'fill_value_invalid', error: 'fill value is not valid for a number input' };
+            }
+            expected = normalizer.value;
+            if (this.type !== 'number' && this.maxLength >= 0 && expected.length > this.maxLength) {
+              return { reason: 'fill_value_invalid', error: 'fill value exceeds the target maxlength' };
+            }
+          } else {
+            expected = expected.replace(/\\r\\n?/g, '\\n');
+          }
+          if (clearBefore) {
+            if (native) {
+              const proto = tag === 'textarea' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+              Object.getOwnPropertyDescriptor(proto, 'value').set.call(this, '');
+            } else {
+              this.textContent = '';
+            }
+            this.dispatchEvent(new Event('input', { bubbles: true }));
+          }
+          return { before, expected };
+        }`,
+        arguments: [{ value: params.value }, { value: clearBefore }],
+        returnByValue: true,
+      },
+    );
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    if (prepared.exceptionDetails) {
+      return fillError("fill_failed", "fill preparation script failed");
+    }
+    const preparation = prepared.result?.value;
+    if (preparation && "error" in preparation) {
+      return fillError(preparation.reason, preparation.error);
+    }
+    if (typeof preparation?.before !== "string" || typeof preparation?.expected !== "string") {
+      return fillError("fill_failed", "fill preparation returned an unexpected result");
+    }
+    // A separate call runs after the clearing event's microtasks drain.
+    // DOM focus works in background tabs. Use document.hasFocus() only to
+    // detect deferred focus events, never to reject background input.
+    const checkReady = async (): Promise<FillReadiness | RpcError> => {
+      const reply = await nodeCdp.send<FillScriptReply<FillReadiness>>(
+        target.tabId,
+        "Runtime.callFunctionOn",
+        {
+          objectId,
+          functionDeclaration: `function(before) {
+            if (!(${FILL_EDITABLE_FUNCTION}).call(this) ||
+                (${FILL_VALUE_FUNCTION}).call(this) !== before) return 'fill_target_changed';
+            if (this.getRootNode().activeElement !== this) return 'fill_focus_lost';
+            return this.ownerDocument.hasFocus() ? 'ready' : 'background';
+          }`,
+          arguments: [{ value: preparation.before }],
+          returnByValue: true,
+        },
+      );
+      const state = reply.result?.value;
+      if (
+        reply.exceptionDetails ||
+        (state !== "ready" &&
+          state !== "background" &&
+          state !== "fill_target_changed" &&
+          state !== "fill_focus_lost")
+      ) {
+        return fillError(
+          "fill_failed",
+          "fill readiness script failed or returned an unexpected result",
+        );
+      }
+      return state;
+    };
+    let ready = await checkReady();
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    // Restore focus once only if clearing left this same target editable
+    // and unchanged. Recheck after focus handlers have run.
+    if (clearBefore && ready === "fill_focus_lost") {
+      await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
+      if (throwIfAborted(deps.signal)) {
+        return { code: "cancelled", message: "fill aborted" };
+      }
+      ready = await checkReady();
+    }
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    if (typeof ready !== "string") return ready;
+    if (ready !== "ready" && ready !== "background") {
+      return fillError(ready, "fill target changed or lost focus before typing");
+    }
+    if (params.value !== "" && (!clearBefore || ready === "background")) {
+      // Native editing commands also support number/email inputs, whose
+      // selection APIs cannot set a caret, and multiline contenteditables.
+      // Also do this for background replacement: CDP input focuses the
+      // renderer, delivering deferred focus events before it inserts text.
+      // Use a command-only event so this does not invoke an End shortcut.
+      try {
+        await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
+          type: "rawKeyDown",
+          commands: ["moveToEndOfDocument"],
+        });
+      } finally {
+        await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", { type: "keyUp" });
+      }
+      if (throwIfAborted(deps.signal)) {
+        return { code: "cancelled", message: "fill aborted" };
+      }
+      // Focus and key handlers can change the target or move focus too.
+      ready = await checkReady();
+      if (throwIfAborted(deps.signal)) {
+        return { code: "cancelled", message: "fill aborted" };
+      }
+      if (typeof ready !== "string") return ready;
+      if (ready !== "ready" && ready !== "background") {
+        return fillError(ready, "fill target changed or lost focus while positioning the caret");
+      }
+    }
     // CDP `Input.insertText` handles IME / multi-byte input out of the
     // box, much more reliably than per-key `dispatchKeyEvent`.
-    await deps.cdp.send(target.tabId, "Input.insertText", { text: params.value });
+    if (params.value !== "") {
+      await deps.cdp.send(target.tabId, "Input.insertText", { text: params.value });
+    }
     if (throwIfAborted(deps.signal)) {
       return { code: "cancelled", message: "fill aborted" };
     }
-    // Fire `input` + `change` so React / Vue controlled inputs commit.
-    await nodeCdp.send(target.tabId, "Runtime.callFunctionOn", {
+    // Keep the existing notifications, then read in a separate call so
+    // nested microtasks queued by the page cannot race the verification.
+    const notified = await nodeCdp.send<FillScriptReply<unknown>>(
+      target.tabId,
+      "Runtime.callFunctionOn",
+      {
+        objectId,
+        functionDeclaration: `function() {
+          this.dispatchEvent(new Event('input', { bubbles: true }));
+          this.dispatchEvent(new Event('change', { bubbles: true }));
+        }`,
+        returnByValue: true,
+      },
+    );
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    if (notified.exceptionDetails) {
+      return fillError("fill_failed", "fill notification script failed");
+    }
+    const verified = await nodeCdp.send<
+      FillScriptReply<{ connected: boolean; matches: boolean; valueLength: number }>
+    >(target.tabId, "Runtime.callFunctionOn", {
       objectId,
-      functionDeclaration: `function() {
-        this.dispatchEvent(new Event('input', { bubbles: true }));
-        this.dispatchEvent(new Event('change', { bubbles: true }));
-      }`,
+      functionDeclaration: `function(expected) {
+          const value = (${FILL_VALUE_FUNCTION}).call(this);
+          return { connected: this.isConnected, matches: value === expected, valueLength: value.length };
+        }`,
+      arguments: [{ value: preparation.expected }],
       returnByValue: true,
     });
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    const verification = verified.result?.value;
+    if (
+      verified.exceptionDetails ||
+      typeof verification?.connected !== "boolean" ||
+      typeof verification?.matches !== "boolean" ||
+      typeof verification?.valueLength !== "number"
+    ) {
+      return fillError(
+        "fill_failed",
+        "fill verification script failed or returned an unexpected result",
+      );
+    }
+    if (!verification.connected) {
+      return fillError("fill_target_changed", "fill target was removed or replaced during input");
+    }
+    if (!verification.matches) {
+      return fillError(
+        "fill_value_mismatch",
+        "fill could not verify the expected value; observe the page before deciding whether to retry",
+      );
+    }
+    return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
+      tab_id: target.tabId,
+      used_ref: node.usedRef,
+      used_selector: node.usedSelector,
+      value_length: verification.valueLength,
+    });
   } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
+    return fillError("fill_failed", err instanceof Error ? err.message : String(err));
+  } finally {
+    await nodeCdp.send(target.tabId, "Runtime.releaseObject", { objectId }).catch(() => undefined);
   }
-
-  return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
-    tab_id: target.tabId,
-    used_ref: node.usedRef,
-    used_selector: node.usedSelector,
-    value_length: params.value.length,
-  });
 }
 
 // ---------------------------------------------------------------------------

apps/extension/src/tools/navigation.ts

@@ -28,7 +28,13 @@ import type {
   RpcError,
   WaitUntil,
 } from "@/transport/types";
+import {
+  type BrowserNavigationApi,
+  chromeBrowserNavigationApi,
+  navigateWithBrowserApi,
+} from "./browser-navigation";
 import { attachDialogs, markDialogCursor } from "./dialogs";
+import { cdpError, isCdpExtensionAccessDenied } from "./errors";
 import {
   type CdpRunner,
   type ChromeTabsApi,
@@ -42,6 +48,7 @@ import {
 export interface NavigationDeps {
   cdp: CdpRunner;
   tabsApi: ChromeTabsApi;
+  browserNavigation?: BrowserNavigationApi;
   /** Optional AbortSignal — M7 abort hook (M10.2 will wire the full chain). */
   signal?: AbortSignal;
   /** Override default timeout when the caller omits `timeout_ms`. */
@@ -479,6 +486,81 @@ async function readTabUrl(api: ChromeTabsApi, tabId: number): Promise<string | u
   }
 }
 
+/** Recover only a failed preflight; never replay an already-dispatched navigation. */
+async function recoverBrowserNavigation(
+  deps: NavigationDeps,
+  tabId: number,
+  action: (api: BrowserNavigationApi) => Promise<unknown>,
+  waitUntil: WaitUntil,
+  timeoutMs: number,
+): Promise<ReloadResult | RpcError> {
+  const abort = linkedAbortSignal(deps.signal);
+  const deadline = Date.now() + timeoutMs;
+  const api = deps.browserNavigation ?? chromeBrowserNavigationApi;
+  try {
+    let outcome = await navigateWithBrowserApi(
+      api,
+      tabId,
+      () => action(api),
+      waitUntil === "networkidle" ? "commit" : waitUntil,
+      timeoutMs,
+      abort.signal,
+    );
+    if (outcome.reached === "failed") return outcome.error;
+    if (outcome.reached === "cancelled" || abort.signal.aborted) {
+      return { code: "cancelled", message: "navigation recovery aborted" };
+    }
+    if (outcome.reached === "match") {
+      // A completed reload is not a recovery if the restricted frame remains.
+      await deps.cdp.send(tabId, "Page.enable", {});
+      if (abort.signal.aborted)
+        return { code: "cancelled", message: "navigation recovery aborted" };
+      if (waitUntil === "networkidle") {
+        // webNavigation cannot prove network idle. Subscribe on the new
+        // document before enabling CDP lifecycle events after its commit.
+        const frame = await readMainFrameInfo(deps.cdp, tabId);
+        if (!frame.frameId) return cdpError("no main frame after navigation");
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+          outcome = { reached: "timeout", lastLifecycle: "commit" };
+        } else {
+          const wait = startLifecycleWait(
+            deps.cdp,
+            tabId,
+            frame.frameId,
+            "networkIdle",
+            remaining,
+            abort.signal,
+            { loaderId: frame.loaderId ?? undefined },
+          );
+          await deps.cdp.send(tabId, "Page.setLifecycleEventsEnabled", { enabled: true });
+          outcome = await wait.promise;
+        }
+      }
+    }
+    if (outcome.reached === "cancelled" || abort.signal.aborted) {
+      return { code: "cancelled", message: "navigation recovery aborted" };
+    }
+    return {
+      tab_id: tabId,
+      final_url: await readTabUrl(deps.tabsApi, tabId),
+      reached: outcome.reached === "match" ? waitUntil : "timeout",
+      ...(outcome.reached === "timeout"
+        ? {
+            error_text: `timed out waiting for ${waitUntil} during navigation recovery after ${timeoutMs}ms`,
+          }
+        : {}),
+    };
+  } catch (error) {
+    return abort.signal.aborted
+      ? { code: "cancelled", message: "navigation recovery aborted" }
+      : cdpError(error);
+  } finally {
+    abort.abort();
+    abort.cleanup();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // tool.navigate
 // ---------------------------------------------------------------------------
@@ -505,7 +587,20 @@ export async function handleNavigate(
 
   try {
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-    await ensureCdpReady(deps.cdp, target.tabId);
+    try {
+      await ensureCdpReady(deps.cdp, target.tabId);
+    } catch (error) {
+      if (!isCdpExtensionAccessDenied(error)) throw error;
+      const recovered = await recoverBrowserNavigation(
+        deps,
+        target.tabId,
+        (api) => api.update(target.tabId, { url: params.url }),
+        waitUntil,
+        timeoutMs,
+      );
+      if (isRpcError(recovered)) return recovered;
+      return attachDialogs(deps.cdp, target.tabId, dialogCursor, { ...recovered, url: params.url });
+    }
     const expected = cdpLifecycleName(waitUntil);
     const beforeReadyState = await probeMainFrameReadyState(deps.cdp, target.tabId);
     const beforeFrame = await readMainFrameInfo(deps.cdp, target.tabId);
@@ -574,10 +669,7 @@ export async function handleNavigate(
       }`,
     });
   } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
+    return cdpError(err);
   }
 }
 
@@ -727,7 +819,24 @@ export async function handleReload(
 
   try {
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-    await ensureCdpReady(deps.cdp, target.tabId);
+    try {
+      await ensureCdpReady(deps.cdp, target.tabId);
+    } catch (error) {
+      if (!isCdpExtensionAccessDenied(error)) throw error;
+      const previousUrl = await readTabUrl(deps.tabsApi, target.tabId);
+      const recovered = await recoverBrowserNavigation(
+        deps,
+        target.tabId,
+        (api) => api.reload(target.tabId, { bypassCache: ignoreCache }),
+        waitUntil,
+        timeoutMs,
+      );
+      if (isRpcError(recovered)) return recovered;
+      return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
+        ...recovered,
+        previous_url: previousUrl,
+      });
+    }
     const previousUrl = await readTabUrl(deps.tabsApi, target.tabId);
     const beforeFrame = await readMainFrameInfo(deps.cdp, target.tabId);
     const expected = cdpLifecycleName(waitUntil);
@@ -776,10 +885,7 @@ export async function handleReload(
       }`,
     });
   } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
+    return cdpError(err);
   }
 }
 

apps/extension/src/tools/vom/__tests__/capture.test.ts

@@ -215,21 +215,29 @@ function makeCdp(snapshot: unknown) {
       if (method === "Runtime.evaluate") {
         return {
           result: {
-            value: {
-              controls: [
+            deepSerializedValue: {
+              type: "array",
+              value: [
                 {
-                  state: "filled",
-                  sensitive: true,
-                  defaultValue: "hunter2",
-                  value: "hunter2",
-                  placeholder: "secret",
+                  type: "array",
+                  value: [
+                    { type: "node", value: { backendNodeId: 13 } },
+                    {
+                      type: "string",
+                      value: JSON.stringify({
+                        state: "filled",
+                        sensitive: true,
+                        placeholder: "secret",
+                      }),
+                    },
+                  ],
                 },
               ],
-              childFrames: [],
             },
           },
         };
       }
+      if (method === "Runtime.releaseObjectGroup") return {};
       throw new Error(`unexpected ${method}`);
     }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
   };
@@ -273,8 +281,11 @@ describe("captureViewModel", () => {
     expect(cdp.send).toHaveBeenCalledWith(
       4,
       "Runtime.evaluate",
-      expect.objectContaining({ returnByValue: true }),
+      expect.objectContaining({
+        serializationOptions: expect.objectContaining({ serialization: "deep" }),
+      }),
     );
+    expect(cdp.send).toHaveBeenCalledWith(4, "Runtime.releaseObjectGroup", expect.anything());
     expect(cdp.send).not.toHaveBeenCalledWith(4, "DOM.resolveNode", expect.anything());
     expect(cdp.send).not.toHaveBeenCalledWith(4, "Runtime.callFunctionOn", expect.anything());
   });

apps/extension/src/tools/vom/__tests__/form-state.test.ts

@@ -0,0 +1,270 @@
+import { describe, expect, it, vi } from "vitest";
+import { type CdpRunner, cdpRunnerForTarget } from "../../shared";
+import { captureViewModel } from "../capture";
+
+interface Control {
+  id: number;
+  value: string;
+  type?: string;
+}
+
+function snapshot(groups: Control[][]) {
+  const strings: string[] = [];
+  const str = (value: string) => {
+    let index = strings.indexOf(value);
+    if (index < 0) index = strings.push(value) - 1;
+    return index;
+  };
+  const documents = groups.map((controls, groupIndex) => ({
+    frameId: `frame-${groupIndex}`,
+    nodes: {
+      parentIndex: [-1, 0, ...controls.map(() => 1)],
+      nodeName: [str("html"), str("body"), ...controls.map(() => str("input"))],
+      backendNodeId: [8000 + groupIndex * 2, 8001 + groupIndex * 2, ...controls.map((c) => c.id)],
+      attributes: [
+        [],
+        [],
+        ...controls.map((c) => [
+          str("type"),
+          str(c.type ?? "text"),
+          str("placeholder"),
+          str("snapshot placeholder"),
+        ]),
+      ],
+      inputValue: {
+        index: controls.map((_, i) => i + 2),
+        value: controls.map((c) => str(c.value)),
+      },
+      contentDocumentIndex: { index: [] as number[], value: [] as number[] },
+    },
+  }));
+  const root = documents[0].nodes;
+  for (let i = 1; i < documents.length; i++) {
+    root.contentDocumentIndex.index.push(root.backendNodeId.length);
+    root.contentDocumentIndex.value.push(i);
+    root.parentIndex.push(1);
+    root.nodeName.push(str("iframe"));
+    root.backendNodeId.push(9000 + i);
+    root.attributes.push([]);
+  }
+  return { strings, documents };
+}
+
+function state(value: string) {
+  return {
+    value,
+    defaultValue: "",
+    placeholder: "live placeholder",
+    state: value ? "filled" : "empty",
+    sensitive: false,
+  };
+}
+
+function reply(entries: Array<[number, unknown]>) {
+  return {
+    result: {
+      deepSerializedValue: {
+        type: "array",
+        value: entries.map(([backendNodeId, fields]) => ({
+          type: "array",
+          value: [
+            { type: "node", value: { backendNodeId } },
+            { type: "string", value: JSON.stringify(fields) },
+          ],
+        })),
+      },
+    },
+  };
+}
+
+function fakeCdp(groups: Control[][], evaluate: (params: Record<string, unknown>) => unknown) {
+  const snap = snapshot(groups);
+  const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
+    if (method === "DOMSnapshot.captureSnapshot") return snap;
+    if (method === "Runtime.evaluate") return evaluate(params as Record<string, unknown>);
+    return {};
+  });
+  return { send, cdp: { send: send as CdpRunner["send"] } };
+}
+
+describe("form state identity", () => {
+  it("matches reordered controls by identity and preserves controls missing from the batch", async () => {
+    // The snapshot includes a shadow input. The runtime query skips it,
+    // encounters a new input, and sees the remaining inputs in a new order.
+    const { cdp } = fakeCdp(
+      [
+        [
+          { id: 10, value: "" },
+          { id: 11, value: "old email" },
+          { id: 12, value: "old city" },
+        ],
+      ],
+      () =>
+        reply([
+          [99, state("new control")],
+          [12, state("上海")],
+          [11, state("alice@example.com")],
+        ]),
+    );
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 10)).toMatchObject({
+      formValue: "",
+      formState: "empty",
+      formPlaceholder: "snapshot placeholder",
+    });
+    expect(captured.nodes.find((n) => n.backendNodeId === 11)).toMatchObject({
+      formValue: "alice@example.com",
+    });
+    expect(captured.nodes.find((n) => n.backendNodeId === 12)).toMatchObject({ formValue: "上海" });
+    expect(captured.nodes.some((n) => n.backendNodeId === 99)).toBe(false);
+  });
+
+  it("does not shift state between frames when one frame is absent from the runtime batch", async () => {
+    const { cdp } = fakeCdp(
+      [
+        [],
+        [{ id: 11, value: "inaccessible frame" }],
+        [{ id: 21, value: "old second" }],
+        [{ id: 31, value: "old third" }],
+      ],
+      () =>
+        reply([
+          [31, state("third frame")],
+          [21, state("second frame")],
+        ]),
+    );
+    const captured = await captureViewModel(cdp, 7);
+    const controls = [...captured.iframeNodes.values()].flat();
+    expect(controls.find((n) => n.backendNodeId === 11)?.formValue).toBe("inaccessible frame");
+    expect(controls.find((n) => n.backendNodeId === 21)?.formValue).toBe("second frame");
+    expect(controls.find((n) => n.backendNodeId === 31)?.formValue).toBe("third frame");
+  });
+
+  it("keeps identical backend ids in different OOPIF targets separate", async () => {
+    const sendToTarget = vi.fn(async (target, method) => {
+      if (method === "DOMSnapshot.captureSnapshot") return snapshot([[{ id: 11, value: "old" }]]);
+      if (method === "Runtime.evaluate") return reply([[11, state(target.sessionId)]]);
+      return {};
+    });
+    const send = vi.fn(async () => {
+      throw new Error("unexpected top-level target");
+    });
+    const cdp = { send, sendToTarget } as unknown as CdpRunner;
+    for (const sessionId of ["left-frame", "right-frame"]) {
+      const captured = await captureViewModel(cdpRunnerForTarget(cdp, { tabId: 7, sessionId }), 7);
+      expect(captured.nodes.find((n) => n.backendNodeId === 11)?.formValue).toBe(sessionId);
+      expect(sendToTarget).toHaveBeenCalledWith(
+        { tabId: 7, sessionId },
+        "Runtime.releaseObjectGroup",
+        expect.anything(),
+      );
+    }
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    "unsupported",
+    "legacy",
+    "malformed",
+    "invalid-state",
+  ])("preserves snapshot data when enrichment is %s", async (mode) => {
+    const { cdp, send } = fakeCdp([[{ id: 11, value: "snapshot value" }]], () => {
+      if (mode === "unsupported") throw new Error("serialization unsupported");
+      if (mode === "legacy") return { result: { value: { controls: [state("wrong value")] } } };
+      const result = reply([
+        [11, mode === "invalid-state" ? { value: "wrong value" } : state("wrong value")],
+      ]);
+      if (mode === "malformed")
+        result.result.deepSerializedValue.value[0].value[1].value = "not json";
+      return result;
+    });
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 11)).toMatchObject({
+      formValue: "snapshot value",
+      formPlaceholder: "snapshot placeholder",
+    });
+    expect(send).toHaveBeenCalledWith(7, "Runtime.releaseObjectGroup", expect.anything());
+  });
+
+  it("releases the batch's remote objects when capture is cancelled", async () => {
+    const controller = new AbortController();
+    const { cdp, send } = fakeCdp([[{ id: 11, value: "old" }]], () => {
+      controller.abort();
+      return reply([[11, state("new")]]);
+    });
+    await expect(captureViewModel(cdp, 7, { signal: controller.signal })).rejects.toMatchObject({
+      name: "AbortError",
+    });
+    expect(send).toHaveBeenCalledWith(7, "Runtime.releaseObjectGroup", expect.anything());
+  });
+
+  it("skips entries without node identity while still applying valid entries", async () => {
+    const { cdp } = fakeCdp(
+      [
+        [
+          { id: 11, value: "snapshot value" },
+          { id: 12, value: "old value" },
+        ],
+      ],
+      () => {
+        const result = reply([
+          [11, state("wrong value")],
+          [12, state("live value")],
+        ]);
+        const element = result.result.deepSerializedValue.value[0].value[0];
+        delete (element.value as { backendNodeId?: number }).backendNodeId;
+        return result;
+      },
+    );
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 11)?.formValue).toBe("snapshot value");
+    expect(captured.nodes.find((n) => n.backendNodeId === 12)?.formValue).toBe("live value");
+  });
+
+  it.each([
+    "password",
+    "text",
+  ])("redacts a sensitive %s control after identity matching", async (type) => {
+    const { cdp } = fakeCdp([[{ id: 11, value: "secret", type }]], () =>
+      reply([[11, { ...state("secret"), sensitive: true }]]),
+    );
+    const captured = await captureViewModel(cdp, 7);
+    const control = captured.nodes.find((n) => n.backendNodeId === 11);
+    expect(control?.formState).toBe("filled");
+    expect(control?.formValue).toBeUndefined();
+    expect(control?.formDefaultValue).toBeUndefined();
+    expect(control?.attrs.value).toBeUndefined();
+  });
+
+  it("keeps one bounded batch without per-control CDP queries", async () => {
+    const controls = Array.from({ length: 251 }, (_, i) => ({ id: i + 1, value: "old" }));
+    const elements = controls.map((c) => ({
+      backendNodeId: c.id,
+      tagName: "INPUT",
+      type: "text",
+      value: `live ${c.id}`,
+      defaultValue: "",
+      placeholder: "",
+    }));
+    const { cdp, send } = fakeCdp([controls], (params) => {
+      const doc = {
+        querySelectorAll: (selector: string) =>
+          selector === "input,textarea,select" ? elements : [],
+      };
+      const entries = new Function("document", `return ${params.expression}`)(doc) as Array<
+        [{ backendNodeId: number }, string]
+      >;
+      expect(entries).toHaveLength(250);
+      return reply(entries.map(([element, json]) => [element.backendNodeId, JSON.parse(json)]));
+    });
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 250)?.formValue).toBe("live 250");
+    expect(captured.nodes.find((n) => n.backendNodeId === 251)?.formValue).toBe("old");
+    expect(send.mock.calls.filter(([, method]) => method === "Runtime.evaluate")).toHaveLength(1);
+    expect(
+      send.mock.calls.filter(([, method]) => method === "Runtime.releaseObjectGroup"),
+    ).toHaveLength(1);
+    expect(send).not.toHaveBeenCalledWith(7, "DOM.resolveNode", expect.anything());
+    expect(send).not.toHaveBeenCalledWith(7, "Runtime.callFunctionOn", expect.anything());
+  });
+});

apps/extension/src/tools/vom/capture.ts

@@ -190,9 +190,9 @@ interface CapturedFormState {
   sensitive?: boolean;
 }
 
-interface CapturedFrameFormState {
-  controls: CapturedFormState[];
-  childFrames: CapturedFrameFormState[];
+interface DeepSerializedValue {
+  type: string;
+  value?: unknown;
 }
 
 function formStateBatchExpression(maxControls: number): string {
@@ -215,43 +215,63 @@ function formStateBatchExpression(maxControls: number): string {
         ...(sensitive ? {} : { value: rawValue, defaultValue }),
       };
     };
+    const controls = [];
     const collect = (doc) => {
-      const controls = [];
       for (const el of Array.from(doc.querySelectorAll(controlSelector))) {
         if (remaining <= 0) break;
-        controls.push(controlState(el));
+        // Deep serialization supplies the node's backend id. Keep the
+        // state as JSON so decoding needs no general-purpose V8 deserializer.
+        controls.push([el, JSON.stringify(controlState(el))]);
         remaining -= 1;
       }
-      const childFrames = [];
       for (const frame of Array.from(doc.querySelectorAll("iframe"))) {
+        if (remaining <= 0) break;
         let childDoc = null;
         try { childDoc = frame.contentDocument; } catch { childDoc = null; }
-        childFrames.push(childDoc && remaining > 0 ? collect(childDoc) : { controls: [], childFrames: [] });
+        if (childDoc) collect(childDoc);
       }
-      return { controls, childFrames };
     };
-    return collect(document);
+    collect(document);
+    return controls;
   })()`;
 }
 
-function flattenFrameFormStates(
-  frame: CapturedFrameFormState | undefined,
-  out: CapturedFormState[][] = [],
-): CapturedFormState[][] {
-  if (!frame) return out;
-  out.push(Array.isArray(frame.controls) ? frame.controls : []);
-  for (const child of Array.isArray(frame.childFrames) ? frame.childFrames : []) {
-    flattenFrameFormStates(child, out);
+function formStatesByBackendId(result: RuntimeEvaluateReply): Map<number, CapturedFormState> {
+  const states = new Map<number, CapturedFormState>();
+  const serialized = result.result?.deepSerializedValue;
+  if (serialized?.type !== "array" || !Array.isArray(serialized.value)) return states;
+  for (const entry of serialized.value as DeepSerializedValue[]) {
+    if (entry?.type !== "array" || !Array.isArray(entry.value)) continue;
+    const [element, json] = entry.value as DeepSerializedValue[];
+    if (element?.type !== "node" || json?.type !== "string" || typeof json.value !== "string") {
+      continue;
+    }
+    const backendNodeId = (element.value as { backendNodeId?: number } | undefined)?.backendNodeId;
+    if (typeof backendNodeId !== "number" || !Number.isSafeInteger(backendNodeId)) continue;
+    try {
+      const state = JSON.parse(json.value) as CapturedFormState | null;
+      if (
+        !state ||
+        !["empty", "filled", "default"].includes(state.state ?? "") ||
+        typeof state.sensitive !== "boolean" ||
+        typeof state.placeholder !== "string" ||
+        (!state.sensitive &&
+          (typeof state.value !== "string" || typeof state.defaultValue !== "string"))
+      ) {
+        continue;
+      }
+      states.set(backendNodeId, state);
+    } catch {
+      // A malformed entry must not overwrite the snapshot's own state.
+    }
   }
-  return out;
+  return states;
 }
 
-function applyFormStates(nodes: CapturedNode[], states: CapturedFormState[]): void {
-  let index = 0;
+function applyFormStates(nodes: CapturedNode[], states: Map<number, CapturedFormState>): void {
   for (const node of nodes) {
     if (!isFormControlTag(node.tag)) continue;
-    const state = states[index];
-    index += 1;
+    const state = states.get(node.backendNodeId);
     if (!state) continue;
     node.formState = state.state;
     node.formPlaceholder = state.placeholder ?? "";
@@ -276,26 +296,37 @@ async function enrichFormControlStates(
     nodes.some((node) => isFormControlTag(node.tag)),
   );
   if (!hasControls) return;
+  const objectGroup = `bsk-vom-forms-${crypto.randomUUID()}`;
   try {
     throwIfAborted(signal);
     const result = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
       expression: formStateBatchExpression(MAX_FORM_ENRICH_CONTROLS),
-      returnByValue: true,
+      objectGroup,
+      serializationOptions: {
+        serialization: "deep",
+        maxDepth: 3,
+        additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
+      },
     });
     throwIfAborted(signal);
-    const frameStates = flattenFrameFormStates(runtimeValue<CapturedFrameFormState>(result));
-    for (let i = 0; i < frameNodeGroups.length; i += 1) {
-      applyFormStates(frameNodeGroups[i], frameStates[i] ?? []);
+    // Backend ids are scoped to this capture's CDP target. OOPIF targets
+    // use their own captureViewModel call and never share this lookup.
+    const states = formStatesByBackendId(result);
+    for (const nodes of frameNodeGroups) {
+      applyFormStates(nodes, states);
     }
   } catch (error) {
     if (isAbortError(error)) throw error;
     // Best-effort enrichment. DOMSnapshot/AX data still carries the nodes.
+  } finally {
+    await cdp.send(tabId, "Runtime.releaseObjectGroup", { objectGroup }).catch(() => undefined);
   }
 }
 
 interface RuntimeEvaluateReply {
   result?: {
     value?: unknown;
+    deepSerializedValue?: DeepSerializedValue;
   };
 }
 

apps/extension/src/transport/types.ts

@@ -26,11 +26,17 @@ export type RpcErrorReason =
   | "ref_not_found"
   | "selector_not_found"
   | "target_not_fillable"
+  | "fill_value_invalid"
+  | "fill_target_changed"
+  | "fill_focus_lost"
+  | "fill_value_mismatch"
+  | "fill_failed"
   | "target_not_select"
   | "option_not_found"
   | "single_select_value_count"
   | "tab_not_active"
   | "restricted_tab_url"
+  | "cdp_extension_access_denied"
   | "borrow_conflict"
   | "screenshot_capture_failed"
   | "file_input_probe_failed"

crates/bsk-cli/skill/SKILL.md

@@ -172,6 +172,10 @@ intended. Read `bsk upload --help` and `bsk download --help` for all flags and e
 - Stale ref: observe again and retry the intended action once.
 - Unknown tab or session: list current tabs/sessions; never guess identifiers.
 - Timeout: inspect current page state before deciding whether one longer purposeful wait is useful.
+- Fill result unconfirmed (`fill_value_mismatch`): observe the field first; the page may have
+  formatted the value. Continue if the visible result satisfies the user's intent. Otherwise correct
+  the remaining difference; do not blindly repeat fill or immediately request human help. For other
+  fill errors, follow the returned hint and inspect current state before retrying.
 - Unsupported command: continue with available capabilities; suggest updating only when the missing
   command is necessary.
 - Unrecoverable failure: report the blocker and stop the session in a finally-style path.

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

@@ -43,10 +43,16 @@ pub mod reason {
     pub const REF_NOT_FOUND: &str = "ref_not_found";
     pub const SELECTOR_NOT_FOUND: &str = "selector_not_found";
     pub const TARGET_NOT_FILLABLE: &str = "target_not_fillable";
+    pub const FILL_VALUE_INVALID: &str = "fill_value_invalid";
+    pub const FILL_TARGET_CHANGED: &str = "fill_target_changed";
+    pub const FILL_FOCUS_LOST: &str = "fill_focus_lost";
+    pub const FILL_VALUE_MISMATCH: &str = "fill_value_mismatch";
+    pub const FILL_FAILED: &str = "fill_failed";
     pub const TARGET_NOT_SELECT: &str = "target_not_select";
     pub const OPTION_NOT_FOUND: &str = "option_not_found";
     pub const SINGLE_SELECT_VALUE_COUNT: &str = "single_select_value_count";
     pub const TAB_NOT_ACTIVE: &str = "tab_not_active";
+    pub const CDP_EXTENSION_ACCESS_DENIED: &str = "cdp_extension_access_denied";
     pub const BORROW_CONFLICT: &str = "borrow_conflict";
     pub const SCREENSHOT_CAPTURE_FAILED: &str = "screenshot_capture_failed";
     pub const FILE_INPUT_PROBE_FAILED: &str = "file_input_probe_failed";
@@ -206,6 +212,13 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
         return base;
     };
     match (code, reason) {
+        (ErrorCode::CdpFailed, reason::CDP_EXTENSION_ACCESS_DENIED) => RenderInfo {
+            summary: "Chrome blocked CDP access to another extension's content in this tab",
+            hint: Some(
+                "a web page can contain a restricted extension frame; disable the conflicting extension and reload, or use `bsk navigate <url>` to leave this page; reconnecting BrowserSkill alone does not remove the restriction",
+            ),
+            exit_code: base.exit_code,
+        },
         (_, reason::TRANSFER_OUTCOME_UNKNOWN) => RenderInfo {
             summary: "the file transfer outcome could not be confirmed",
             hint: Some(
@@ -247,7 +260,42 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
         (ErrorCode::InvalidParams, reason::TARGET_NOT_FILLABLE) => RenderInfo {
             summary: "target element is not fillable",
             hint: Some(
-                "choose an input, textarea, or contenteditable element from the latest snapshot",
+                "observe the page and choose an enabled, editable text input, textarea, or contenteditable; use the appropriate interaction for other control types",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::InvalidParams, reason::FILL_VALUE_INVALID) => RenderInfo {
+            summary: "the requested text does not fit the field constraints",
+            hint: Some(
+                "check the field's input type and maxlength; use a compatible value without silently truncating or changing the user's intended data",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::CdpFailed, reason::FILL_TARGET_CHANGED) => RenderInfo {
+            summary: "the fill target changed during the action",
+            hint: Some(
+                "observe the current page and field value; if the intended result is missing, use a fresh editable target before retrying",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::CdpFailed, reason::FILL_FOCUS_LOST) => RenderInfo {
+            summary: "the page moved focus away from the fill target",
+            hint: Some(
+                "observe the page for a dialog or rerender and resolve it before retrying; fill manages field focus and does not require bringing the browser to the foreground",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::CdpFailed, reason::FILL_VALUE_MISMATCH) => RenderInfo {
+            summary: "the fill result could not be confirmed",
+            hint: Some(
+                "observe the field before retrying; the page may have formatted the value. Continue if the visible result satisfies the user's intent; otherwise correct the remaining difference. Do not blindly repeat fill or immediately request human help",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::CdpFailed, reason::FILL_FAILED) => RenderInfo {
+            summary: "fill encountered a browser or page-script error",
+            hint: Some(
+                "observe the page before retrying because the field may already have changed; retry only if the intended result is missing and the target is still available",
             ),
             exit_code: base.exit_code,
         },
@@ -442,6 +490,56 @@ mod tests {
         ErrorCode::NoBrowserConnected,
     ];
 
+    #[test]
+    fn fill_reasons_provide_recovery_without_changing_exit_codes() {
+        for (code, reason, hint_fragment) in [
+            (
+                ErrorCode::InvalidParams,
+                reason::TARGET_NOT_FILLABLE,
+                "enabled, editable",
+            ),
+            (
+                ErrorCode::InvalidParams,
+                reason::FILL_VALUE_INVALID,
+                "maxlength",
+            ),
+            (
+                ErrorCode::CdpFailed,
+                reason::FILL_TARGET_CHANGED,
+                "fresh editable target",
+            ),
+            (
+                ErrorCode::CdpFailed,
+                reason::FILL_FOCUS_LOST,
+                "does not require bringing the browser",
+            ),
+            (
+                ErrorCode::CdpFailed,
+                reason::FILL_VALUE_MISMATCH,
+                "Continue if the visible result satisfies",
+            ),
+            (
+                ErrorCode::CdpFailed,
+                reason::FILL_FAILED,
+                "may already have changed",
+            ),
+        ] {
+            let data = serde_json::json!({ "reason": reason });
+            let info = info_for_error(code, Some(&data));
+            assert!(info.hint.unwrap().contains(hint_fragment), "{reason}");
+            assert_eq!(info.exit_code, info_for(code).exit_code);
+        }
+        let mismatch = serde_json::json!({ "reason": reason::FILL_VALUE_MISMATCH });
+        let info = info_for_error(ErrorCode::CdpFailed, Some(&mismatch));
+        assert_eq!(info.summary, "the fill result could not be confirmed");
+        assert!(info.hint.unwrap().contains("Do not blindly repeat fill"));
+        let unknown = serde_json::json!({ "reason": "future_fill_reason" });
+        assert_eq!(
+            info_for_error(ErrorCode::CdpFailed, Some(&unknown)),
+            info_for(ErrorCode::CdpFailed)
+        );
+    }
+
     #[test]
     fn element_not_visible_overrides_permission_denied_copy() {
         let data = serde_json::json!({ "reason": reason::ELEMENT_NOT_VISIBLE });
@@ -454,6 +552,18 @@ mod tests {
         assert!(!info.summary.contains("sandbox"));
     }
 
+    #[test]
+    fn extension_access_denied_explains_the_frame_restriction_and_navigation_recovery() {
+        let data = serde_json::json!({ "reason": reason::CDP_EXTENSION_ACCESS_DENIED });
+        let info = info_for_error(ErrorCode::CdpFailed, Some(&data));
+        assert!(info.summary.contains("another extension"));
+        let hint = info.hint.unwrap();
+        assert!(hint.contains("restricted extension frame"));
+        assert!(hint.contains("bsk navigate <url>"));
+        assert!(hint.contains("disable the conflicting extension"));
+        assert_eq!(info.exit_code, 3);
+    }
+
     #[test]
     fn session_busy_overrides_timeout_copy() {
         let data = serde_json::json!({ "reason": reason::SESSION_BUSY });

packages/dsh-plugin-browserskill/README.md

@@ -112,7 +112,7 @@ shell's theme cannot bleed back in.
 - **Lifecycle**: hidden while the plugin owns no sessions; appears on the first
   `browser_session` start action; disappears when all sessions stop (or the plugin unloads).
 - **Focus view**: status row (green/idle/red dot + session + action + mm:ss), the latest page
-  frame (refreshes every ~1.5s while active, ~8s when idle; the last good frame stays on
+  frame (while viewed, refreshes every ~1.5s while active, ~8s when idle; the last good frame stays on
   stage while the next one loads, and is kept on errors so the card does not flash),
   and a compact icon toolbar (Interrupt + Pop out, hover for the label).
 - **Interrupt**: one click kills the in-flight bsk command of the focus session (same semantics
@@ -129,11 +129,32 @@ shell's theme cannot bleed back in.
 - **Pop out (PiP)**: upgrades the card into a native Document PiP window (requires a user
   gesture, per browser rules), sized from the current card; closing the PiP falls back to the
   in-page card with state intact. Browsers without Document PiP simply hide the button.
-- **Wire**: the host serves `GET /bsk-observation/state`, `GET /bsk-observation/events` (SSE),
-  `POST /bsk-observation/interrupt`, and `GET /bsk-observation/thumbnail/<attachmentId>` over
-  the dsh `webServer` route seam (dsh 0.1's Typert Remote pipeline is closed to out-of-tree
-  packages). All commands for one session — tool calls and frame captures alike — run through a
-  per-session FIFO, because the daemon accepts only one unfinished command per session.
+- **Screenshot demand**: the client requests periodic screenshots while an observation view is
+  visible, using the PiP document's visibility when popped out. Hidden or collapsed views can
+  keep subscribing to state without requesting screenshots. The first screenshot subscriber
+  starts capture scheduling; the last one's departure cancels timers and skips queued captures.
+  An already running capture may finish. Demand applies to the service's owned sessions, not just
+  the selected session.
+- **Wire**: `GET /bsk-observation/events` is the live synchronization channel (SSE). Every connection,
+  including reconnects, starts with `{ type: "snapshot", sessions, available }`, followed by
+  `upsert`, `remove`, `reset`, and `availability` events on the same stream. Replace local state
+  with each snapshot before applying subsequent events. Use `?thumbnails=0` for state-only
+  subscriptions or `?thumbnails=1` to request screenshots; omitting the parameter defaults to
+  requesting screenshots for compatibility. Closing the stream releases its screenshot demand.
+  `GET /bsk-observation/state` remains a one-time `{ sessions, available }` read and does not
+  request screenshots. It has no ordering guarantee relative to a separate SSE connection;
+  live clients should initialize and resynchronize from the stream's snapshot instead.
+  The host also serves `POST /bsk-observation/interrupt`, `POST /bsk-observation/stop`, and
+  `GET /bsk-observation/thumbnail/<attachmentId>` through the dsh `webServer` route seam
+  (dsh 0.1's Typert Remote pipeline is closed to out-of-tree packages). All commands for one
+  session — tool calls and frame captures alike — run through a per-session FIFO, because the
+  daemon accepts only one unfinished command per session.
+- **Programmatic subscription**: `ObservationService.subscribe(listener, { thumbnails: false })`
+  subscribes to state without requesting screenshots. On an active service, the listener receives
+  the initial `snapshot` synchronously, before `subscribe` returns, then receives subsequent
+  changes. `thumbnails` defaults to `true`, so callers should choose it explicitly. The returned
+  unsubscribe function is safe to call repeatedly and releases this subscription's screenshot
+  demand. Subscribing after service disposal is a no-op.
 - **Trust model**: these routes expose live screenshots (and an interrupt write), so they
   replicate the browser-trust fence dsh applies to its own `/api` routes: the request Host
   must be a loopback authority (`localhost`, `127.0.0.0/8`, `[::1]`), a present Origin must

packages/dsh-plugin-browserskill/skill/SKILL.md

@@ -97,6 +97,10 @@ Continue from returned sequence cursors instead of rereading the same buffer.
 - Unknown tab: list tabs instead of guessing.
 - Unknown session: list owned sessions or start one; never try foreign ids.
 - Timeout: inspect current state before deciding whether one longer purposeful wait is useful.
+- Fill result unconfirmed: observe the field first; the page may have formatted the value. Continue
+  if the visible result satisfies the user's intent. Otherwise correct the remaining difference;
+  do not blindly repeat fill or immediately request human help. For other fill errors, follow the
+  returned hint and inspect current state before retrying.
 - Unrecoverable failure: report the blocker and stop the owned session.
 
 Arbitrary page-script evaluation and interaction recording are intentionally unsupported. Do not

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

@@ -142,6 +142,8 @@
   right: 6px;
   width: 16px;
   height: 16px;
+  padding: 0;
+  cursor: pointer;
   border-radius: 50%;
   display: inline-flex;
   align-items: center;

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

@@ -48,7 +48,13 @@ 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 {
+  focusOf,
+  statusOf,
+  useObservationView,
+  usePip,
+  useThumbnailObservation,
+} from "./observation-view";
 import { getSidebarMode, subscribeSidebarMode } from "./sidebar-mode";
 
 // The pure view helpers live in observation-view (shared with the sidebar
@@ -341,6 +347,7 @@ export function OverlayBody(props: {
     onHeaderPointerDown,
   } = props;
   const [interrupting, setInterrupting] = useState(false);
+  const viewRef = useThumbnailObservation(store, sessions.length > 0);
 
   const thumbId = focus?.thumbnailAttachmentId;
   useEffect(() => {
@@ -373,7 +380,12 @@ export function OverlayBody(props: {
   const state = !available ? "error" : focus !== undefined ? statusOf(focus) : "idle";
 
   return (
-    <div className={cn(css.body, "bsk-obs")} data-state={state} data-in-pip={inPip || undefined}>
+    <div
+      ref={viewRef}
+      className={cn(css.body, "bsk-obs")}
+      data-state={state}
+      data-in-pip={inPip || undefined}
+    >
       <div
         className={css.header}
         data-testid="obs-header"
@@ -421,9 +433,15 @@ export function OverlayBody(props: {
           </div>
         )}
         {thumb?.status === "error" ? (
-          <span className={css.badge} aria-label="thumbnail failed">
+          <button
+            type="button"
+            className={css.badge}
+            aria-label="Retry thumbnail"
+            title="Frame unavailable — retry"
+            onClick={() => store.retryThumbnail(thumbId)}
+          >
             <IconWarn size={12} />
-          </span>
+          </button>
         ) : null}
       </div>
       {sessions.length >= 2 ? (

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

@@ -1,10 +1,9 @@
 /**
- * Client-side data layer for the observation overlay: initial state fetch,
- * SSE increment stream (with a state refetch on every (re)open — events that
- * fired while the stream was down are otherwise lost forever), on-demand
- * thumbnail blob loading through the session-authorized readAttachment path,
+ * Client-side data layer for the observation overlay: an ordered SSE snapshot
+ * and increment stream (each reconnect starts with a fresh snapshot), on-demand
+ * thumbnail blob loading through the host's ephemeral-frame route,
  * and the interrupt call. The last ready blob per session is held until its
- * replacement decodes so the overlay can swap frames in place. All I/O is
+ * replacement loads so the overlay can swap frames in place. All I/O is
  * injected so tests never touch a network.
  */
 
@@ -12,8 +11,6 @@ import type { ObservationEvent, SessionObservation } from "../observation";
 
 export interface EventSourceLike {
   onmessage: ((event: { data: string }) => void) | null;
-  /** Fires on the initial connect AND on every automatic reconnect. */
-  onopen?: (() => void) | null;
   close(): void;
 }
 
@@ -50,10 +47,10 @@ export interface OverlaySnapshot {
   readonly available: boolean;
 }
 
-const STATE_URL = "/bsk-observation/state";
 const EVENTS_URL = "/bsk-observation/events";
 const INTERRUPT_URL = "/bsk-observation/interrupt";
 const STOP_URL = "/bsk-observation/stop";
+const THUMBNAIL_RETRY_DELAYS_MS = [1000, 3000];
 
 function revoke(url: string | undefined): void {
   if (url !== undefined && typeof URL.revokeObjectURL === "function") {
@@ -66,8 +63,10 @@ export class ObservationClientStore {
   private thumbs = new Map<string, ThumbnailState>();
   /** sessionId → the attachment id currently advertised for it. */
   private readonly thumbBySession = new Map<string, string>();
-  /** sessionId → last successfully decoded frame (held across the next load). */
+  /** sessionId → last successfully loaded frame (held across the next load). */
   private readonly lastReady = new Map<string, { attachmentId: string; url: string }>();
+  private readonly retryTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly retryCounts = new Map<string, number>();
   private listeners = new Set<() => void>();
   private events: EventSourceLike | undefined;
   private snapshot: OverlaySnapshot = {
@@ -81,6 +80,7 @@ export class ObservationClientStore {
   private started = false;
   /** Refcount of mounted consumers (overlay card, sidebar tab, sidebar fiber). */
   private consumers = 0;
+  private thumbnailConsumers = 0;
 
   constructor(private readonly deps: ObservationClientDeps) {}
 
@@ -133,37 +133,16 @@ export class ObservationClientStore {
     return undefined;
   }
 
-  /** (Re)pull the full state: initial load and every SSE (re)open. */
-  private refreshState(): void {
-    void this.deps
-      .fetchFn(STATE_URL)
-      .then(async (res) => {
-        if (!res.ok) return;
-        const body = (await res.json()) as {
-          sessions?: SessionObservation[];
-          available?: boolean;
-        };
-        const sessions = body.sessions ?? [];
-        this.sessions = new Map(sessions.map((s) => [s.sessionId, s]));
-        // Prune thumbnails of sessions that vanished while we were away.
-        const alive = new Set(sessions.map((s) => s.sessionId));
-        for (const sessionId of [...this.thumbBySession.keys()]) {
-          if (!alive.has(sessionId)) this.dropThumb(sessionId);
-        }
-        for (const s of sessions) this.trackThumb(s.sessionId, s.thumbnailAttachmentId);
-        if (typeof body.available === "boolean") this.available = body.available;
-        this.publish();
-      })
-      .catch(() => {});
-  }
-
-  /** Initial fetch + SSE subscription. Idempotent. */
-  start(): void {
-    if (this.started) return;
-    this.started = true;
-    this.refreshState();
-    const events = this.deps.eventSourceFactory(EVENTS_URL);
+  private connectEvents(): void {
+    const previous = this.events;
+    this.events = undefined;
+    previous?.close();
+    const events = this.deps.eventSourceFactory(
+      `${EVENTS_URL}?thumbnails=${this.thumbnailConsumers > 0 ? "1" : "0"}`,
+    );
+    this.events = events;
     events.onmessage = (message) => {
+      if (!this.started || this.events !== events) return;
       let event: ObservationEvent;
       try {
         event = JSON.parse(message.data) as ObservationEvent;
@@ -172,23 +151,24 @@ export class ObservationClientStore {
       }
       this.apply(event);
     };
-    events.onopen = () => {
-      // Reconnects lose every event fired during the outage — resync.
-      if (this.events === events) this.refreshState();
-    };
-    this.events = events;
+  }
+
+  /** Every initial connection and reconnect starts with the server's snapshot. */
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.connectEvents();
     this.publish();
   }
 
   stop(): void {
-    this.events?.close();
+    const previous = this.events;
     this.events = undefined;
     this.started = false;
-    for (const thumb of this.thumbs.values()) revoke(thumb.url);
-    this.thumbs.clear();
-    this.thumbBySession.clear();
-    this.lastReady.clear();
+    previous?.close();
+    this.clearThumbnails();
     this.sessions.clear();
+    this.available = true;
     this.publish();
   }
 
@@ -209,6 +189,33 @@ export class ObservationClientStore {
     if (this.consumers === 0) this.stop();
   }
 
+  /** Only visible image surfaces request screenshots; metadata watchers do not. */
+  watchThumbnails(): () => void {
+    this.thumbnailConsumers += 1;
+    if (this.thumbnailConsumers === 1 && this.started) this.connectEvents();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.thumbnailConsumers -= 1;
+      if (this.thumbnailConsumers === 0 && this.started) this.connectEvents();
+    };
+  }
+
+  private forgetThumbnail(attachmentId: string): void {
+    clearTimeout(this.retryTimers.get(attachmentId));
+    this.retryTimers.delete(attachmentId);
+    this.retryCounts.delete(attachmentId);
+    revoke(this.thumbs.get(attachmentId)?.url);
+    this.thumbs.delete(attachmentId);
+  }
+
+  private clearThumbnails(): void {
+    for (const attachmentId of this.thumbs.keys()) this.forgetThumbnail(attachmentId);
+    this.thumbBySession.clear();
+    this.lastReady.clear();
+  }
+
   /** Forget one session's tracked + held frames, revoking their blob URLs. */
   private dropThumb(sessionId: string): void {
     const attachmentId = this.thumbBySession.get(sessionId);
@@ -216,39 +223,45 @@ export class ObservationClientStore {
     this.thumbBySession.delete(sessionId);
     this.lastReady.delete(sessionId);
     if (attachmentId !== undefined) {
-      revoke(this.thumbs.get(attachmentId)?.url);
-      this.thumbs.delete(attachmentId);
+      this.forgetThumbnail(attachmentId);
     }
     if (held !== undefined && held.attachmentId !== attachmentId) {
-      revoke(held.url);
-      this.thumbs.delete(held.attachmentId);
+      this.forgetThumbnail(held.attachmentId);
     }
   }
 
   /**
    * Track the frame a session currently advertises. The last *ready* blob is
-   * kept until the replacement decodes — dropping it on the upsert is what
+   * kept until the replacement loads — dropping it on the upsert is what
    * made the overlay flash a placeholder between breaths.
    */
   private trackThumb(sessionId: string, attachmentId: string | undefined): void {
+    if (attachmentId === undefined) {
+      this.dropThumb(sessionId);
+      return;
+    }
     const previous = this.thumbBySession.get(sessionId);
     if (previous === attachmentId) return;
-    if (attachmentId !== undefined) this.thumbBySession.set(sessionId, attachmentId);
-    else this.thumbBySession.delete(sessionId);
+    this.thumbBySession.set(sessionId, attachmentId);
     const heldId = this.lastReady.get(sessionId)?.attachmentId;
     if (previous !== undefined && previous !== heldId) {
-      revoke(this.thumbs.get(previous)?.url);
-      this.thumbs.delete(previous);
+      this.forgetThumbnail(previous);
     }
   }
 
   private apply(event: ObservationEvent): void {
-    if (event.type === "reset") {
+    if (event.type === "snapshot") {
+      this.sessions = new Map(event.sessions.map((session) => [session.sessionId, session]));
+      for (const sessionId of this.thumbBySession.keys()) {
+        if (!this.sessions.has(sessionId)) this.dropThumb(sessionId);
+      }
+      for (const session of event.sessions) {
+        this.trackThumb(session.sessionId, session.thumbnailAttachmentId);
+      }
+      this.available = event.available;
+    } else if (event.type === "reset") {
       this.sessions.clear();
-      for (const thumb of this.thumbs.values()) revoke(thumb.url);
-      this.thumbs.clear();
-      this.thumbBySession.clear();
-      this.lastReady.clear();
+      this.clearThumbnails();
     } else if (event.type === "remove" && event.session !== undefined) {
       this.sessions.delete(event.session.sessionId);
       this.dropThumb(event.session.sessionId);
@@ -259,44 +272,77 @@ export class ObservationClientStore {
       this.available = event.available;
     }
     this.publish();
+    if (event.type === "snapshot") {
+      for (const session of event.sessions) this.retryThumbnail(session.thumbnailAttachmentId);
+    }
   }
 
   /**
    * Ensure a thumbnail load is in flight for one attachment reference. New
-   * frames replace the old URL only after they decode; failures keep the last
+   * frames replace the old URL only after they load; failures keep the last
    * good frame (the caller renders `status: 'error'` as a small badge over
    * the old image).
    */
   ensureThumbnail(attachmentId: string | undefined): void {
-    if (attachmentId === undefined || this.thumbs.has(attachmentId)) return;
-    this.thumbs.set(attachmentId, { status: "loading" });
+    if (
+      !this.started ||
+      attachmentId === undefined ||
+      this.sessionOf(attachmentId) === undefined ||
+      this.thumbs.has(attachmentId)
+    )
+      return;
+    const loading: ThumbnailState = { status: "loading" };
+    this.thumbs.set(attachmentId, loading);
     this.publish();
     this.deps.loadImage(attachmentId).then(
       (url) => {
-        if (!this.thumbs.has(attachmentId)) {
+        if (this.thumbs.get(attachmentId) !== loading) {
           // Replaced or removed while loading: never resurrect (or leak) it.
           revoke(url);
           return;
         }
+        this.retryCounts.delete(attachmentId);
         this.thumbs.set(attachmentId, { status: "ready", url });
         const sessionId = this.sessionOf(attachmentId);
         if (sessionId !== undefined) {
           const previous = this.lastReady.get(sessionId);
           if (previous !== undefined && previous.attachmentId !== attachmentId) {
-            revoke(previous.url);
-            this.thumbs.delete(previous.attachmentId);
+            this.forgetThumbnail(previous.attachmentId);
           }
           this.lastReady.set(sessionId, { attachmentId, url });
         }
         this.publish();
       },
       () => {
-        this.thumbs.set(attachmentId, { status: "error" });
+        if (this.thumbs.get(attachmentId) !== loading) return;
+        const failed: ThumbnailState = { status: "error" };
+        this.thumbs.set(attachmentId, failed);
+        const attempts = this.retryCounts.get(attachmentId) ?? 0;
+        const delay = THUMBNAIL_RETRY_DELAYS_MS[attempts];
+        if (delay !== undefined) {
+          this.retryCounts.set(attachmentId, attempts + 1);
+          this.retryTimers.set(
+            attachmentId,
+            setTimeout(() => {
+              this.retryTimers.delete(attachmentId);
+              if (this.thumbs.get(attachmentId) !== failed) return;
+              this.thumbs.delete(attachmentId);
+              this.ensureThumbnail(attachmentId);
+            }, delay),
+          );
+        }
         this.publish();
       },
     );
   }
 
+  /** Explicit retry (also used on a fresh connection after an outage). */
+  retryThumbnail(attachmentId: string | undefined): void {
+    if (attachmentId === undefined || this.thumbs.get(attachmentId)?.status !== "error") return;
+    this.forgetThumbnail(attachmentId);
+    this.ensureThumbnail(attachmentId);
+  }
+
   /** Interrupt the current or named session's in-flight call. */
   async interrupt(sessionId?: string): Promise<boolean> {
     try {

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

@@ -6,7 +6,7 @@
  * without duplicating hooks.
  */
 
-import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
 import type { SessionObservation } from "../observation";
 import type { ObservationClientStore, OverlaySnapshot } from "./observation-store";
 
@@ -114,6 +114,49 @@ export function useObservationView(
   };
 }
 
+/** A mounted metadata watcher is not necessarily a visible screenshot viewer. */
+export function useThumbnailObservation(store: ObservationClientStore, enabled: boolean) {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const element = ref.current;
+    if (!enabled || element === null) return;
+    // A portal uses its PiP document's visibility, independently of the main tab.
+    const doc = element.ownerDocument;
+    const Observer = doc.defaultView?.IntersectionObserver;
+    let active = true;
+    let intersecting = Observer === undefined;
+    let release: (() => void) | undefined;
+    const update = () => {
+      if (!active) return;
+      const visible = intersecting && doc.visibilityState !== "hidden";
+      if (visible && release === undefined) release = store.watchThumbnails();
+      else if (!visible && release !== undefined) {
+        release();
+        release = undefined;
+      }
+    };
+    const observer =
+      Observer === undefined
+        ? undefined
+        : new Observer((entries) => {
+            intersecting = entries.some(
+              (entry) => entry.target === element && entry.isIntersecting,
+            );
+            update();
+          });
+    observer?.observe(element);
+    doc.addEventListener("visibilitychange", update);
+    update();
+    return () => {
+      active = false;
+      observer?.disconnect();
+      doc.removeEventListener("visibilitychange", update);
+      release?.();
+    };
+  }, [store, enabled]);
+  return ref;
+}
+
 export interface PipHandle {
   /** The open PiP window, or null while the content renders in its carrier. */
   readonly pipWindow: Window | null;

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

@@ -5,12 +5,19 @@
  * the event allowlist lives in dsh-api-remotes), so the plugin serves its
  * observation channel through the documented `webServer` route seam instead:
  *
- *   GET  /bsk-observation/state      → { sessions, available }
- *   GET  /bsk-observation/events     → SSE stream of ObservationEvent
+ *   GET  /bsk-observation/state      → one-time { sessions, available } read
+ *   GET  /bsk-observation/events     → SSE snapshot, then ObservationEvent increments
+ *                                    (on every connection, including reconnects)
+ *                                    ?thumbnails=0: state only; =1: request screenshots
+ *                                    Omitted parameter defaults to screenshots.
  *   POST /bsk-observation/interrupt  → body {sessionId?} → {interrupted: boolean}
  *   POST /bsk-observation/stop       → body {sessionId} → {stopped: boolean}
  *   GET  /bsk-observation/thumbnail/<attachmentId> → image bytes
  *
+ * Live clients initialize/resynchronize from the SSE snapshot; a separate
+ * /state read has no ordering guarantee relative to the stream and does not
+ * request screenshots. Closing an SSE connection releases its screenshot demand.
+ *
  * Routes exist only when a webServer service is mounted (web composition);
  * headless deployments skip registration entirely.
  */
@@ -99,6 +106,7 @@ export function registerObservationRoutes(
   if (webServer === undefined) {
     return () => {};
   }
+  const streams = new Set<() => void>();
   const disposers = [
     webServer.register({
       kind: "exact",
@@ -129,14 +137,42 @@ export function registerObservationRoutes(
           "cache-control": "no-cache",
           connection: "keep-alive",
         });
-        const unsubscribe = observation.subscribe((event) => {
-          res.write(`data: ${JSON.stringify(event)}\n\n`);
-        });
-        const heartbeat = setInterval(() => res.write(": heartbeat\n\n"), SSE_HEARTBEAT_MS);
-        res.on("close", () => {
+        const thumbnails =
+          new URL(req.url ?? "/", "http://localhost").searchParams.get("thumbnails") !== "0";
+        let unsubscribe: (() => void) | undefined;
+        let heartbeat: ReturnType<typeof setInterval> | undefined;
+        let closed = false;
+        const close = () => {
+          if (closed) return;
+          closed = true;
           clearInterval(heartbeat);
-          unsubscribe();
-        });
+          unsubscribe?.();
+          streams.delete(close);
+          res.end();
+        };
+        const write = (data: string) => {
+          if (closed) return;
+          try {
+            res.write(data);
+          } catch {
+            close();
+          }
+        };
+        streams.add(close);
+        res.on("close", close);
+        res.on("error", close);
+        try {
+          unsubscribe = observation.subscribe(
+            (event) => {
+              write(`data: ${JSON.stringify(event)}\n\n`);
+            },
+            { thumbnails },
+          );
+          if (closed) unsubscribe();
+          else heartbeat = setInterval(() => write(": heartbeat\n\n"), SSE_HEARTBEAT_MS);
+        } catch {
+          close();
+        }
       },
     }),
     webServer.register({
@@ -228,6 +264,7 @@ export function registerObservationRoutes(
     }),
   ];
   return () => {
+    for (const close of streams) close();
     for (const dispose of disposers) dispose();
   };
 }

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

@@ -49,8 +49,9 @@ export interface SessionObservation {
   dshSessionIds?: string[];
 }
 
-/** Incremental event carried to subscribers (SSE on the wire). */
+/** Initial snapshot or incremental change carried to subscribers (SSE on the wire). */
 export type ObservationEvent =
+  | { type: "snapshot"; sessions: SessionObservation[]; available: boolean }
   | { type: "upsert" | "remove" | "reset"; session?: SessionObservation }
   | { type: "availability"; available: boolean };
 
@@ -89,6 +90,7 @@ export class ObservationService {
   private readonly scratchNamespace = randomUUID();
   private readonly observations = new Map<string, SessionObservation>();
   private readonly listeners = new Set<(event: ObservationEvent) => void>();
+  private thumbnailViewers = 0;
   private readonly captureTimers = new Map<string, unknown>();
   private readonly captureInFlight = new Set<string>();
   /** Captures intentionally cancelled to make way for foreground work. */
@@ -125,7 +127,7 @@ export class ObservationService {
     return this.deps.scheduler ?? DEFAULT_SCHEDULER;
   }
 
-  /** All current entries (client initial/resync snapshot). */
+  /** One-time state read; use subscribe for an ordered snapshot and subsequent changes. */
   getState(): SessionObservation[] {
     return [...this.observations.values()].map((entry) => ({ ...entry }));
   }
@@ -141,10 +143,42 @@ export class ObservationService {
     this.emit({ type: "availability", available });
   }
 
-  /** Subscribe to incremental changes; returns an unsubscribe function. */
-  subscribe(listener: (event: ObservationEvent) => void): () => void {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
+  /**
+   * Subscribe to an ordered initial snapshot and subsequent changes. On an
+   * active service, listener receives the snapshot synchronously before this
+   * method returns. Subscribing after disposal is a no-op.
+   *
+   * `thumbnails` defaults to true for compatibility: this subscription counts
+   * as a screenshot viewer for the service's owned sessions. Pass false for
+   * state-only observation. The first viewer starts capture scheduling.
+   *
+   * @returns An idempotent unsubscribe function releasing this subscription's
+   * screenshot demand. When the last viewer leaves, scheduled/queued captures
+   * are cancelled/skipped; an already running capture may finish.
+   */
+  subscribe(
+    listener: (event: ObservationEvent) => void,
+    { thumbnails = true }: { thumbnails?: boolean } = {},
+  ): () => void {
+    if (this.disposed) return () => {};
+    // Each subscription owns its lease, even if a caller reuses a callback.
+    const receive = (event: ObservationEvent) => listener(event);
+    this.listeners.add(receive);
+    try {
+      listener({ type: "snapshot", sessions: this.getState(), available: this.available });
+    } catch (error) {
+      this.listeners.delete(receive);
+      throw error;
+    }
+    if (thumbnails && ++this.thumbnailViewers === 1) {
+      for (const sessionId of this.observations.keys()) this.scheduleCapture(sessionId, 0);
+    }
+    return () => {
+      if (!this.listeners.delete(receive)) return;
+      if (thumbnails && --this.thumbnailViewers === 0) {
+        for (const sessionId of this.captureTimers.keys()) this.cancelCapture(sessionId);
+      }
+    };
   }
 
   private emit(event: ObservationEvent): void {
@@ -355,6 +389,7 @@ export class ObservationService {
     this.observations.clear();
     this.emit({ type: "reset" });
     this.listeners.clear();
+    this.thumbnailViewers = 0;
   }
 
   // ------------------------------------------------------------------
@@ -369,12 +404,21 @@ export class ObservationService {
     }
   }
 
+  private canCapture(sessionId: string): boolean {
+    const entry = this.observations.get(sessionId);
+    return (
+      this.deps.options.enabled &&
+      !this.disposed &&
+      this.thumbnailViewers > 0 &&
+      !this.foregroundDepth.has(sessionId) &&
+      entry !== undefined &&
+      entry.dead !== true
+    );
+  }
+
   /** Schedule the next capture for a session; `delayMs` 0 means "as soon as the event loop allows". */
   private scheduleCapture(sessionId: string, delayMs?: number): void {
-    if (!this.deps.options.enabled || this.disposed) return;
-    if (this.foregroundDepth.has(sessionId)) return;
-    const entry = this.observations.get(sessionId);
-    if (entry === undefined || entry.dead === true) return;
+    if (!this.canCapture(sessionId)) return;
     this.cancelCapture(sessionId);
     const now = this.scheduler.now();
     const lastSeen = this.lastActivity.get(sessionId) ?? 0;
@@ -399,9 +443,7 @@ export class ObservationService {
    * Failures keep the previous frame and back off silently.
    */
   private async capture(sessionId: string): Promise<void> {
-    if (this.disposed) return;
-    const current = this.observations.get(sessionId);
-    if (current === undefined || current.dead === true) return;
+    if (!this.canCapture(sessionId)) return;
     if (this.captureInFlight.has(sessionId)) return;
     this.captureInFlight.add(sessionId);
     // Stable within this service, isolated from captures owned by other instances.
@@ -410,8 +452,8 @@ export class ObservationService {
     let writtenPath = outPath;
     try {
       const result = await this.deps.queue.run(sessionId, () => {
-        // A foreground lease may have arrived while this capture was queued.
-        if (this.foregroundDepth.has(sessionId)) return Promise.resolve(undefined);
+        // The last viewer may have left, or foreground work arrived, while queued.
+        if (!this.canCapture(sessionId)) return Promise.resolve(undefined);
         return this.deps.runner.run(["screenshot", "--session", sessionId, "--out", outPath], {
           timeoutMs: 15_000,
           tag: `observation:${sessionId}`,
@@ -445,6 +487,7 @@ export class ObservationService {
       this.setAvailable(true);
       this.publishFrame(sessionId, entry, data);
     } catch {
+      if (this.disposed || !this.observations.has(sessionId)) return;
       // Foreground preemption is healthy scheduling, not browser/daemon
       // unavailability; do not let normal tool traffic trip capture backoff.
       if (!this.capturePreempted.delete(sessionId)) {

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

@@ -636,7 +636,9 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
         session: SESSION_PARAM,
         noClear: {
           type: "boolean",
-          description: "Skip the default wipe-the-field-first pass (append instead).",
+          description:
+            "Append to the end of the existing value instead of clearing it. " +
+            "The tool moves the caret automatically; no prior click or selection is needed.",
         },
       },
       output: {

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

@@ -19,10 +19,12 @@ interface Harness {
   emitRaw: (event: unknown) => void;
   fetches: { url: string; init?: { body?: string } }[];
   loadImage: ReturnType<typeof vi.fn>;
+  eventUrls: string[];
 }
 
 function makeHarness(initial: SessionObservation[]): Harness {
   const fetches: Harness["fetches"] = [];
+  const eventUrls: string[] = [];
   let es: EventSourceLike | undefined;
   let current = initial;
   const loadImage = vi.fn(async (id: string) => `blob:${id}`);
@@ -34,9 +36,16 @@ function makeHarness(initial: SessionObservation[]): Harness {
       }
       return { ok: true, json: async () => ({ interrupted: true }) };
     },
-    eventSourceFactory: () => {
-      es = { onmessage: null, close: vi.fn() };
-      return es;
+    eventSourceFactory: (url) => {
+      eventUrls.push(url);
+      const connection = { onmessage: null, close: vi.fn() } as EventSourceLike;
+      es = connection;
+      queueMicrotask(() =>
+        connection.onmessage?.({
+          data: JSON.stringify({ type: "snapshot", sessions: current, available: true }),
+        }),
+      );
+      return connection;
     },
     loadImage,
   });
@@ -58,10 +67,120 @@ function makeHarness(initial: SessionObservation[]): Harness {
     },
     fetches,
     loadImage,
+    eventUrls,
   };
 }
 
-afterEach(cleanup);
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("visible thumbnail demand", () => {
+  function intersections() {
+    const observers: Array<{
+      notify: (visible: boolean) => void;
+      disconnect: ReturnType<typeof vi.fn>;
+    }> = [];
+    vi.stubGlobal(
+      "IntersectionObserver",
+      class {
+        private target?: Element;
+        disconnect = vi.fn();
+        constructor(private callback: IntersectionObserverCallback) {
+          observers.push(this);
+        }
+        observe(target: Element) {
+          this.target = target;
+        }
+        notify(visible: boolean) {
+          this.callback(
+            [{ target: this.target, isIntersecting: visible } as IntersectionObserverEntry],
+            this as unknown as IntersectionObserver,
+          );
+        }
+      },
+    );
+    return observers;
+  }
+
+  it("pauses screenshots on collapse while keeping the metadata feed", async () => {
+    const observers = intersections();
+    const h = makeHarness([BUSY]);
+    const { unmount } = render(<ObservationOverlay store={h.store} />);
+    await screen.findByTestId("obs-card");
+    expect(h.eventUrls.at(-1)).toBe("/bsk-observation/events?thumbnails=0");
+    act(() => observers[0].notify(true));
+    expect(h.eventUrls.at(-1)).toBe("/bsk-observation/events?thumbnails=1");
+    fireEvent.click(screen.getByRole("button", { name: "Collapse" }));
+    expect(h.eventUrls.at(-1)).toBe("/bsk-observation/events?thumbnails=0");
+    expect(h.es().close).not.toHaveBeenCalled();
+    expect(observers[0].disconnect).toHaveBeenCalledOnce();
+    // A callback queued before disconnect must not reclaim screenshot demand.
+    act(() => observers[0].notify(true));
+    expect(h.eventUrls.at(-1)).toBe("/bsk-observation/events?thumbnails=0");
+    fireEvent.click(screen.getByRole("button", { name: /Expand browser observation/ }));
+    act(() => observers[1].notify(true));
+    expect(h.eventUrls.at(-1)).toBe("/bsk-observation/events?thumbnails=1");
+    unmount();
+    expect(h.es().close).toHaveBeenCalledOnce();
+  });
+
+  it("ignores an initial visibility notification delivered after collapse", async () => {
+    const observers = intersections();
+    const h = makeHarness([BUSY]);
+    render(<ObservationOverlay store={h.store} />);
+    await screen.findByTestId("obs-card");
+    fireEvent.click(screen.getByRole("button", { name: "Collapse" }));
+    act(() => observers[0].notify(true));
+    expect(h.eventUrls).toEqual(["/bsk-observation/events?thumbnails=0"]);
+  });
+
+  it("pauses for a hidden document or hidden panel and resumes when visible", async () => {
+    const observers = intersections();
+    let visibility: DocumentVisibilityState = "visible";
+    vi.spyOn(document, "visibilityState", "get").mockImplementation(() => visibility);
+    const h = makeHarness([BUSY]);
+    render(<ObservationOverlay store={h.store} />);
+    await screen.findByTestId("obs-card");
+    act(() => observers[0].notify(true));
+    expect(h.eventUrls.at(-1)).toContain("thumbnails=1");
+    act(() => {
+      visibility = "hidden";
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+    expect(h.eventUrls.at(-1)).toContain("thumbnails=0");
+    act(() => {
+      visibility = "visible";
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+    expect(h.eventUrls.at(-1)).toContain("thumbnails=1");
+    act(() => observers[0].notify(false));
+    expect(h.eventUrls.at(-1)).toContain("thumbnails=0");
+  });
+
+  it("keeps a visible PiP watching when the main document is hidden", async () => {
+    // The detached PiP test document has no window/IntersectionObserver.
+    vi.stubGlobal("IntersectionObserver", undefined);
+    let visibility: DocumentVisibilityState = "visible";
+    vi.spyOn(document, "visibilityState", "get").mockImplementation(() => visibility);
+    const pipDoc = document.implementation.createHTMLDocument("pip");
+    Object.defineProperty(pipDoc, "visibilityState", { value: "visible" });
+    (window as unknown as Record<string, unknown>).documentPictureInPicture = {
+      requestWindow: async () => ({ document: pipDoc, addEventListener: () => {}, close: vi.fn() }),
+    };
+    const h = makeHarness([BUSY]);
+    render(<ObservationOverlay store={h.store} />);
+    fireEvent.click(await screen.findByRole("button", { name: /Pop out/ }));
+    await waitFor(() => expect(pipDoc.body.textContent).toContain("s1"));
+    act(() => {
+      visibility = "hidden";
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+    expect(h.eventUrls.at(-1)).toContain("thumbnails=1");
+  });
+});
 
 describe("ObservationOverlay", () => {
   beforeEach(() => {
@@ -92,6 +211,16 @@ describe("ObservationOverlay", () => {
     await screen.findByRole("img", { name: "session s1 view" });
   });
 
+  it("offers a retry after a thumbnail fails without requiring a new frame id", async () => {
+    const h = makeHarness([{ ...BUSY, thumbnailAttachmentId: "att-9" }]);
+    h.loadImage.mockRejectedValueOnce(new Error("temporary failure"));
+    render(<ObservationOverlay store={h.store} />);
+    fireEvent.click(await screen.findByRole("button", { name: "Retry thumbnail" }));
+    await screen.findByRole("img", { name: "session s1 view" });
+    expect(h.loadImage).toHaveBeenCalledTimes(2);
+    expect(screen.queryByRole("button", { name: "Retry thumbnail" })).toBeNull();
+  });
+
   it("keeps the current frame on stage while the next thumbnail loads", async () => {
     let resolveNext: ((url: string) => void) | undefined;
     const h = makeHarness([{ ...BUSY, thumbnailAttachmentId: "att-1" }]);

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

@@ -53,8 +53,14 @@ function makeHarness(initial: SessionObservation[]): Harness {
       return { ok: true, json: async () => ({ interrupted: true }) };
     },
     eventSourceFactory: () => {
-      es = { onmessage: null, close: vi.fn() };
-      return es;
+      const connection = { onmessage: null, close: vi.fn() } as EventSourceLike;
+      es = connection;
+      queueMicrotask(() =>
+        connection.onmessage?.({
+          data: JSON.stringify({ type: "snapshot", sessions: current, available: true }),
+        }),
+      );
+      return connection;
     },
     loadImage: async (id: string) => `blob:${id}`,
   });

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

@@ -1,12 +1,19 @@
-// ObservationClientStore: initial fetch + SSE application, thumbnail loading
+// ObservationClientStore: ordered SSE snapshots/increments, thumbnail loading
 // lifecycle, interrupt wire shape. All I/O faked.
 
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { type EventSourceLike, ObservationClientStore } from "../../src/client/observation-store";
 import type { ObservationEvent, SessionObservation } from "../../src/observation";
 
 const OBS_IDLE: SessionObservation = { sessionId: "s1", action: "idle", since: 1000 };
 const OBS_BUSY: SessionObservation = { sessionId: "s1", action: "clicking", since: 2000 };
+const stores: ObservationClientStore[] = [];
+
+afterEach(() => {
+  for (const store of stores.splice(0)) store.stop();
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+});
 
 function harness(state: SessionObservation[] = []) {
   const fetches: {
@@ -14,6 +21,7 @@ function harness(state: SessionObservation[] = []) {
     init?: { method?: string; body?: string; headers?: Record<string, string> };
   }[] = [];
   const esInstances: EventSourceLike[] = [];
+  const eventUrls: string[] = [];
   const fetchFn = vi.fn(
     async (
       url: string,
@@ -29,11 +37,14 @@ function harness(state: SessionObservation[] = []) {
   const eventSourceFactory = (url: string) => {
     const es: EventSourceLike = { onmessage: null, close: vi.fn() };
     esInstances.push(es);
+    eventUrls.push(url);
+    queueMicrotask(() => emit(es, { type: "snapshot", sessions: state, available: true }));
     return es;
   };
   const loadImage = vi.fn(async (id: string) => `blob:url-${id}`);
   const store = new ObservationClientStore({ fetchFn, eventSourceFactory, loadImage });
-  return { store, fetches, esInstances, loadImage };
+  stores.push(store);
+  return { store, fetches, esInstances, eventUrls, loadImage };
 }
 
 function emit(es: EventSourceLike, event: ObservationEvent): void {
@@ -73,7 +84,9 @@ describe("ObservationClientStore", () => {
   });
 
   it("loads each thumbnail once and reports ready", async () => {
-    const { store, loadImage } = harness();
+    const { store, loadImage } = harness([{ ...OBS_IDLE, thumbnailAttachmentId: "att-1" }]);
+    store.start();
+    await Promise.resolve();
     store.ensureThumbnail("att-1");
     store.ensureThumbnail("att-1");
     expect(loadImage).toHaveBeenCalledTimes(1);
@@ -86,7 +99,9 @@ describe("ObservationClientStore", () => {
   });
 
   it("marks failed thumbnail loads as error", async () => {
-    const { store, loadImage } = harness();
+    const { store, loadImage } = harness([{ ...OBS_IDLE, thumbnailAttachmentId: "att-bad" }]);
+    store.start();
+    await Promise.resolve();
     loadImage.mockRejectedValueOnce(new Error("nope"));
     store.ensureThumbnail("att-bad");
     await vi.waitFor(() => expect(store.getSnapshot().thumbnails["att-bad"].status).toBe("error"));
@@ -124,9 +139,7 @@ describe("ObservationClientStore", () => {
 
 describe("thumbnail blob URL lifecycle", () => {
   function withRevokeSpy() {
-    const revoke = vi.fn();
-    (URL as unknown as { revokeObjectURL: unknown }).revokeObjectURL = revoke;
-    return revoke;
+    return vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {});
   }
 
   it("holds the last ready frame until the replacement decodes", async () => {
@@ -231,16 +244,216 @@ describe("thumbnail blob URL lifecycle", () => {
   });
 });
 
-describe("SSE (re)open resync", () => {
-  it("refetches the full state when the stream (re)opens", async () => {
+describe("SSE snapshot ordering", () => {
+  it("ignores events from a stopped connection after a restart", async () => {
+    const { store, esInstances } = harness([OBS_IDLE]);
+    store.start();
+    await Promise.resolve();
+    const old = esInstances[0];
+    store.stop();
+    emit(old, { type: "upsert", session: OBS_BUSY });
+    expect(store.getSnapshot().sessions).toEqual([]);
+    store.start();
+    await Promise.resolve();
+    emit(esInstances[1], { type: "upsert", session: OBS_BUSY });
+    emit(old, { type: "snapshot", sessions: [], available: false });
+    emit(old, { type: "remove", session: OBS_BUSY });
+    expect(store.getSnapshot()).toMatchObject({ sessions: [OBS_BUSY], available: true });
+  });
+
+  it("does not apply a queued initial snapshot after stop", async () => {
+    const { store } = harness([OBS_BUSY]);
+    store.start();
+    store.stop();
+    await Promise.resolve();
+    expect(store.getSnapshot()).toMatchObject({ sessions: [], thumbnails: {}, subscribed: false });
+  });
+
+  it("replaces state on reconnect before applying subsequent events, without a competing fetch", async () => {
     const { store, fetches, esInstances } = harness([OBS_IDLE]);
     store.start();
     await vi.waitFor(() => expect(store.getSnapshot().sessions).toHaveLength(1));
-    const before = fetches.filter((f) => f.url === "/bsk-observation/state").length;
-    esInstances[0].onopen?.();
-    await vi.waitFor(() =>
-      expect(fetches.filter((f) => f.url === "/bsk-observation/state").length).toBe(before + 1),
-    );
+    emit(esInstances[0], { type: "snapshot", sessions: [], available: false });
+    expect(store.getSnapshot()).toMatchObject({ sessions: [], available: false });
+    emit(esInstances[0], { type: "upsert", session: OBS_BUSY });
+    await Promise.resolve();
+    expect(store.getSnapshot().sessions).toEqual([OBS_BUSY]);
+    expect(fetches).toEqual([]);
     store.stop();
   });
 });
+
+describe("thumbnail recovery and stale loads", () => {
+  function deferred<T>() {
+    let resolve!: (value: T) => void;
+    let reject!: (reason: Error) => void;
+    const promise = new Promise<T>((yes, no) => {
+      resolve = yes;
+      reject = no;
+    });
+    return { promise, resolve, reject };
+  }
+
+  it("retries a transient failure without needing a different frame id", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const { store, loadImage } = harness([{ ...OBS_IDLE, thumbnailAttachmentId: "a1" }]);
+    store.start();
+    await Promise.resolve();
+    loadImage.mockRejectedValueOnce(new Error("temporary"));
+    store.ensureThumbnail("a1");
+    await Promise.resolve();
+    expect(store.getSnapshot().thumbnails.a1.status).toBe("error");
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(loadImage).toHaveBeenCalledTimes(2);
+    expect(store.getSnapshot().displayFrames.s1).toEqual({ status: "ready", url: "blob:url-a1" });
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("bounds automatic retries and allows an explicit recovery", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const { store, loadImage } = harness([{ ...OBS_IDLE, thumbnailAttachmentId: "a1" }]);
+    store.start();
+    await Promise.resolve();
+    loadImage.mockRejectedValue(new Error("offline"));
+    store.ensureThumbnail("a1");
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(loadImage).toHaveBeenCalledTimes(3);
+    expect(vi.getTimerCount()).toBe(0);
+    store.ensureThumbnail("a1");
+    expect(loadImage).toHaveBeenCalledTimes(3);
+    loadImage.mockResolvedValue("blob:recovered");
+    store.retryThumbnail("a1");
+    await Promise.resolve();
+    expect(store.getSnapshot().displayFrames.s1.url).toBe("blob:recovered");
+  });
+
+  it("cancels backoff when a reconnect retries the current frame", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const session = { ...OBS_IDLE, thumbnailAttachmentId: "a1" };
+    const { store, esInstances, loadImage } = harness([session]);
+    store.start();
+    await Promise.resolve();
+    loadImage.mockRejectedValueOnce(new Error("offline"));
+    store.ensureThumbnail("a1");
+    await Promise.resolve();
+    emit(esInstances[0], { type: "snapshot", sessions: [session], available: true });
+    await Promise.resolve();
+    expect(store.getSnapshot().thumbnails.a1.status).toBe("ready");
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(loadImage).toHaveBeenCalledTimes(2);
+  });
+
+  it.each([
+    "remove",
+    "reset",
+    "stop",
+    "missing-thumbnail",
+    "snapshot-removal",
+  ])("cleans frames and cancels retries on %s", async (action) => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const revoke = vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {});
+    const { store, esInstances, loadImage } = harness([
+      { ...OBS_IDLE, thumbnailAttachmentId: "a1" },
+    ]);
+    store.start();
+    await Promise.resolve();
+    store.ensureThumbnail("a1");
+    await Promise.resolve();
+    emit(esInstances[0], { type: "upsert", session: { ...OBS_IDLE, thumbnailAttachmentId: "a2" } });
+    loadImage.mockRejectedValueOnce(new Error("no frame"));
+    store.ensureThumbnail("a2");
+    await Promise.resolve();
+    expect(store.getSnapshot().displayFrames.s1).toEqual({ status: "error", url: "blob:url-a1" });
+    if (action === "stop") store.stop();
+    else if (action === "remove") emit(esInstances[0], { type: "remove", session: OBS_IDLE });
+    else if (action === "reset") emit(esInstances[0], { type: "reset" });
+    else if (action === "missing-thumbnail")
+      emit(esInstances[0], { type: "upsert", session: OBS_IDLE });
+    else emit(esInstances[0], { type: "snapshot", sessions: [], available: true });
+    expect(store.getSnapshot().thumbnails).toEqual({});
+    expect(store.getSnapshot().displayFrames).toEqual({});
+    expect(revoke).toHaveBeenCalledExactlyOnceWith("blob:url-a1");
+    expect(vi.getTimerCount()).toBe(0);
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(loadImage).toHaveBeenCalledTimes(2);
+  });
+
+  it.each([
+    "resolve",
+    "reject",
+  ])("ignores a stale load's %s even when the same id is loaded again", async (outcome) => {
+    const revoke = vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {});
+    const { store, esInstances, loadImage } = harness([
+      { ...OBS_IDLE, thumbnailAttachmentId: "a1" },
+    ]);
+    const old = deferred<string>();
+    loadImage.mockReturnValueOnce(old.promise);
+    store.start();
+    await Promise.resolve();
+    store.ensureThumbnail("a1");
+    emit(esInstances[0], { type: "upsert", session: { ...OBS_IDLE, thumbnailAttachmentId: "a2" } });
+    emit(esInstances[0], { type: "upsert", session: { ...OBS_IDLE, thumbnailAttachmentId: "a1" } });
+    store.ensureThumbnail("a1");
+    await Promise.resolve();
+    if (outcome === "resolve") old.resolve("blob:stale");
+    else old.reject(new Error("stale error"));
+    await Promise.resolve();
+    expect(store.getSnapshot().displayFrames.s1).toEqual({ status: "ready", url: "blob:url-a1" });
+    expect(revoke).not.toHaveBeenCalledWith("blob:url-a1");
+    if (outcome === "resolve") expect(revoke).toHaveBeenCalledWith("blob:stale");
+  });
+
+  it.each(["resolve", "reject"])("ignores an in-flight load's %s after stop", async (outcome) => {
+    const revoke = vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {});
+    const { store, loadImage } = harness([{ ...OBS_IDLE, thumbnailAttachmentId: "a1" }]);
+    const pending = deferred<string>();
+    loadImage.mockReturnValueOnce(pending.promise);
+    store.start();
+    await Promise.resolve();
+    store.ensureThumbnail("a1");
+    store.stop();
+    if (outcome === "resolve") pending.resolve("blob:late");
+    else pending.reject(new Error("late error"));
+    await Promise.resolve();
+    expect(store.getSnapshot()).toMatchObject({ sessions: [], thumbnails: {}, displayFrames: {} });
+    if (outcome === "resolve") expect(revoke).toHaveBeenCalledWith("blob:late");
+  });
+});
+
+describe("thumbnail viewer leases", () => {
+  it("keeps metadata subscribed while the last screenshot viewer leaves", async () => {
+    const { store, eventUrls, esInstances } = harness([OBS_IDLE]);
+    store.acquire();
+    await Promise.resolve();
+    expect(eventUrls).toEqual(["/bsk-observation/events?thumbnails=0"]);
+    const first = store.watchThumbnails();
+    expect(eventUrls.at(-1)).toBe("/bsk-observation/events?thumbnails=1");
+    const second = store.watchThumbnails();
+    expect(eventUrls).toHaveLength(2);
+    first();
+    first();
+    expect(eventUrls).toHaveLength(2);
+    second();
+    expect(eventUrls.at(-1)).toBe("/bsk-observation/events?thumbnails=0");
+    expect(store.getSnapshot().subscribed).toBe(true);
+    store.release();
+    expect(esInstances.at(-1)?.close).toHaveBeenCalledOnce();
+    expect(store.getSnapshot().subscribed).toBe(false);
+  });
+
+  it("ignores delayed snapshots from a replaced stream without clearing the displayed state", async () => {
+    const { store, esInstances } = harness([OBS_IDLE]);
+    store.start();
+    await Promise.resolve();
+    emit(esInstances[0], { type: "upsert", session: OBS_BUSY });
+    const release = store.watchThumbnails();
+    expect(store.getSnapshot().sessions).toEqual([OBS_BUSY]);
+    await Promise.resolve();
+    emit(esInstances[1], { type: "upsert", session: OBS_BUSY });
+    emit(esInstances[0], { type: "snapshot", sessions: [], available: false });
+    expect(store.getSnapshot()).toMatchObject({ sessions: [OBS_BUSY], available: true });
+    store.stop();
+    release();
+    expect(esInstances).toHaveLength(2);
+  });
+});

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

@@ -6,7 +6,7 @@ import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { tmpdir } from "node:os";
 import { basename, dirname } from "node:path";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
   actionForLabel,
   type ObservationEvent,
@@ -138,6 +138,8 @@ function setup(opts: {
   runner?: FakeRunner;
   registry?: SessionRegistry;
   scheduler?: ReturnType<typeof fakeScheduler>;
+  thumbnails?: boolean;
+  queue?: KeyedExecutor;
 }) {
   const registry = opts.registry ?? new SessionRegistry(5);
   const runner = opts.runner ?? fakeRunner();
@@ -146,13 +148,18 @@ function setup(opts: {
     ctx: fakeCtx(),
     runner,
     registry,
-    queue: new KeyedExecutor(),
+    queue: opts.queue ?? new KeyedExecutor(),
     options: OPTIONS,
     scheduler,
   });
   const events: ObservationEvent[] = [];
-  service.subscribe((event) => events.push(event));
-  return { service, registry, runner, scheduler, events };
+  const unsubscribe = service.subscribe(
+    (event) => {
+      if (event.type !== "snapshot") events.push(event);
+    },
+    { thumbnails: opts.thumbnails ?? true },
+  );
+  return { service, registry, runner, scheduler, events, unsubscribe };
 }
 
 /** Drive the registry through a real start so the session is owned. */
@@ -224,6 +231,111 @@ describe("state machine", () => {
 });
 
 describe("thumbnail cadence", () => {
+  it("keeps metadata current without screenshots and resumes when a viewer arrives", async () => {
+    const { service, scheduler, runner, events } = setup({ thumbnails: false });
+    service.addSession("s1");
+    service.beginAction("s1", "clicking");
+    service.endAction("s1");
+    const releaseForeground = service.acquireForeground("s1");
+    releaseForeground();
+    expect(service.getState()[0].action).toBe("idle");
+    expect(events).toHaveLength(3);
+    expect(scheduler.pending()).toEqual([]);
+    expect(runner.calls).toEqual([]);
+    const snapshots: ObservationEvent[] = [];
+    const leave = service.subscribe((event) => snapshots.push(event));
+    expect(snapshots[0]).toEqual({
+      type: "snapshot",
+      sessions: service.getState(),
+      available: true,
+    });
+    expect(scheduler.pending()).toEqual([0]);
+    scheduler.runNext();
+    await waitFor(() => scheduler.pending().length === 1);
+    expect(runner.calls).toHaveLength(1);
+    leave();
+    leave();
+    expect(scheduler.pending()).toEqual([]);
+    service.endAction("s1");
+    expect(scheduler.pending()).toEqual([]);
+    const resume = service.subscribe(() => {});
+    expect(scheduler.pending()).toEqual([0]);
+    resume();
+    service.dispose();
+  });
+
+  it("does not capture in a headless service with no subscribers", () => {
+    const { service, scheduler, unsubscribe } = setup({});
+    unsubscribe();
+    service.addSession("s1");
+    service.endAction("s1");
+    expect(scheduler.pending()).toEqual([]);
+    expect(service.getState()).toHaveLength(1);
+    service.dispose();
+  });
+
+  it("keeps capturing until the last viewer leaves, including reused callbacks", () => {
+    const { service, scheduler } = setup({ thumbnails: false });
+    service.addSession("s1");
+    const listener = () => {};
+    const first = service.subscribe(listener);
+    const second = service.subscribe(listener);
+    expect(scheduler.pending()).toEqual([0]);
+    first();
+    first();
+    expect(scheduler.pending()).toEqual([0]);
+    second();
+    expect(scheduler.pending()).toEqual([]);
+    service.dispose();
+  });
+
+  it("skips a queued screenshot if its last viewer leaves before execution", async () => {
+    const queue = new KeyedExecutor();
+    let unblock!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      unblock = resolve;
+    });
+    const busy = queue.run("s1", () => gate);
+    const { service, scheduler, runner, unsubscribe } = setup({ queue });
+    service.addSession("s1");
+    scheduler.runNext();
+    unsubscribe();
+    unblock();
+    await busy;
+    await queue.run("s1", async () => {});
+    expect(runner.calls).toEqual([]);
+    expect(scheduler.pending()).toEqual([]);
+    service.dispose();
+  });
+
+  it("lets an already running capture finish without restarting the loop after the last viewer leaves", async () => {
+    const runner = fakeRunner();
+    const run = runner.run.bind(runner);
+    let finish!: () => void;
+    let started = false;
+    runner.run = async (args, options) => {
+      started = true;
+      await new Promise<void>((resolve) => {
+        finish = resolve;
+      });
+      return run(args, options);
+    };
+    const { service, scheduler, unsubscribe } = setup({ runner });
+    service.addSession("s1");
+    scheduler.runNext();
+    await waitFor(() => started);
+    unsubscribe();
+    finish();
+    await waitFor(() => service.getState()[0]?.thumbnailAttachmentId !== undefined);
+    const args = runner.calls[0].args;
+    await waitFor(() => !existsSync(args[args.indexOf("--out") + 1]));
+    expect(scheduler.pending()).toEqual([]);
+    const leave = service.subscribe(() => {});
+    expect(scheduler.pending()).toEqual([0]);
+    leave();
+    service.dispose();
+  });
+
   it("gives foreground work priority and resumes with one fresh capture", async () => {
     const scheduler = fakeScheduler();
     let finishCapture: ((result: BskRunResult) => void) | undefined;
@@ -540,6 +652,12 @@ describe("HTTP/SSE interface", () => {
     const eventsRes = fakeRes();
     await eventsRoute?.handler(fakeReq(), eventsRes.res as never);
     service.beginAction("s1", "clicking");
+    const streamed = eventsRes.chunks.map((chunk) => JSON.parse(chunk.slice(6)));
+    expect(streamed.map((event) => event.type)).toEqual(["snapshot", "upsert"]);
+    expect(streamed[0]).toMatchObject({
+      sessions: [{ sessionId: "s1", action: "idle" }],
+      available: true,
+    });
     expect(eventsRes.res.body()).toContain('"action":"clicking"');
     eventsRes.res.close();
 
@@ -566,6 +684,47 @@ describe("HTTP/SSE interface", () => {
     service.dispose();
   });
 
+  it("state-only SSE does not capture, and route disposal releases every active viewer", async () => {
+    const { service, scheduler } = setup({ thumbnails: false });
+    service.addSession("s1");
+    const { routes, webServer } = routeHarness();
+    const dispose = registerObservationRoutes({ get: () => webServer } as never, service);
+    const route = routes.get("/bsk-observation/events")!;
+    const metadata = fakeRes();
+    await route.handler(fakeReq({ url: "/bsk-observation/events?thumbnails=0" }), metadata.res);
+    expect(scheduler.pending()).toEqual([]);
+    const viewing = fakeRes();
+    await route.handler(fakeReq({ url: "/bsk-observation/events?thumbnails=1" }), viewing.res);
+    expect(scheduler.pending()).toEqual([0]);
+    const endMetadata = vi.spyOn(metadata.res, "end");
+    const endViewing = vi.spyOn(viewing.res, "end");
+    dispose();
+    expect(endMetadata).toHaveBeenCalledOnce();
+    expect(endViewing).toHaveBeenCalledOnce();
+    expect(scheduler.pending()).toEqual([]);
+    viewing.res.close();
+    metadata.res.close();
+    expect(endViewing).toHaveBeenCalledOnce();
+    service.dispose();
+  });
+
+  it("releases a viewer when writing its initial snapshot fails", async () => {
+    const { service, scheduler } = setup({ thumbnails: false });
+    service.addSession("s1");
+    const { routes, webServer } = routeHarness();
+    const dispose = registerObservationRoutes({ get: () => webServer } as never, service);
+    const response = fakeRes();
+    vi.spyOn(response.res, "write").mockImplementation(() => {
+      throw new Error("closed socket");
+    });
+    const end = vi.spyOn(response.res, "end");
+    await routes.get("/bsk-observation/events")!.handler(fakeReq(), response.res);
+    expect(end).toHaveBeenCalledOnce();
+    expect(scheduler.pending()).toEqual([]);
+    dispose();
+    service.dispose();
+  });
+
   it("refuses a stop without a sessionId", async () => {
     const registry = new SessionRegistry(5);
     own(registry, "s1");

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

@@ -124,6 +124,28 @@ describe("parseBskJson", () => {
     expect(() => parseBskJson({ ...base, code: 1, stderr: "boom" }, "x")).toThrow(/boom/);
   });
 
+  it("surfaces fill recovery guidance to the model without retrying", async () => {
+    const hint =
+      "observe the field before retrying; the page may have formatted the value. Continue if the visible result satisfies the user's intent";
+    const reply = {
+      ...base,
+      code: 3,
+      stdout: JSON.stringify({
+        code: "cdp_failed",
+        message: "fill could not verify the expected value",
+        data: { reason: "fill_value_mismatch" },
+        hint,
+      }),
+    };
+    let calls = 0;
+    const result = await runWithSessionBusyRetry(async () => {
+      calls++;
+      return reply;
+    });
+    expect(calls).toBe(1);
+    expect(() => parseBskJson(result, "fill")).toThrow(hint);
+  });
+
   it("reports killed-by-interrupt children (null exit code) as interrupted", () => {
     expect(() => parseBskJson({ ...base, code: null }, "navigate")).toThrow(/interrupted/);
   });

skill/SKILL.md

@@ -172,6 +172,10 @@ intended. Read `bsk upload --help` and `bsk download --help` for all flags and e
 - Stale ref: observe again and retry the intended action once.
 - Unknown tab or session: list current tabs/sessions; never guess identifiers.
 - Timeout: inspect current page state before deciding whether one longer purposeful wait is useful.
+- Fill result unconfirmed (`fill_value_mismatch`): observe the field first; the page may have
+  formatted the value. Continue if the visible result satisfies the user's intent. Otherwise correct
+  the remaining difference; do not blindly repeat fill or immediately request human help. For other
+  fill errors, follow the returned hint and inspect current state before retrying.
 - Unsupported command: continue with available capabilities; suggest updating only when the missing
   command is necessary.
 - Unrecoverable failure: report the blocker and stop the session in a finally-style path.