docs(eval): clarify agent-neutral scope

fix(dsh-plugin): stabilize skill loading and browser sessions

.gitignore

@@ -11,6 +11,10 @@ dist/
 # Logs
 *.log
 
+# Local browser evaluation artifacts
+evals/browser/results/
+evals/browser/agents.local.json
+
 # macOS
 .DS_Store
 

Cargo.lock

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

Cargo.toml

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

README.md

@@ -208,6 +208,7 @@ The repository is a Cargo + pnpm workspace:
 - `apps/extension` — browser extension
 - `packages/ui` and `packages/i18n` — shared extension UI support
 - `packages/dsh-plugin-browserskill` — DeepSeek Harness plugin (`@wxg-prc-cpg/browser-skill-dsh-plugin`)
+- [`evals/browser`](evals/browser/README.md) — deterministic local pages and agent-neutral browser capability evaluation
 
 ## License
 

README.zh-CN.md

@@ -178,6 +178,7 @@ Agent 不直接与浏览器通信。它通过 `bsk` CLI 下发浏览器任务；
 - `apps/extension` — 浏览器扩展
 - `packages/ui` 和 `packages/i18n` — 扩展 UI 共享支持
 - `packages/dsh-plugin-browserskill` — DeepSeek Harness 插件（`@wxg-prc-cpg/browser-skill-dsh-plugin`）
+- [`evals/browser`](evals/browser/README.zh-CN.md) — 确定性本地页面与 Agent 无关的浏览器能力测试台
 
 ## 许可证
 

apps/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browser-skill/extension",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "scripts": {

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

@@ -1656,7 +1656,7 @@ describe("buildVomScene", () => {
 
     const scene = buildVomScene(axNodes, captured);
     expect(scene.nodes.find((n) => n.id === 20)).toEqual(
-      expect.objectContaining({ id: 20, role: "generic", cursor: "pointer" }),
+      expect.objectContaining({ id: 20, role: "button", name: "close", cursor: "pointer" }),
     );
     const rendered = renderVom(scene);
     expect(rendered.text).toContain('@e1 button "close"');
@@ -1732,7 +1732,7 @@ describe("buildVomScene", () => {
     };
 
     const scene = buildVomScene(axNodes, captured);
-    expect(scene.nodes.find((n) => n.id === 20)?.role).toBe("generic");
+    expect(scene.nodes.find((n) => n.id === 20)).toBeUndefined();
     expect(scene.nodes.find((n) => n.id === 30)?.role).toBe("link");
   });
 
@@ -1801,9 +1801,9 @@ describe("buildVomScene", () => {
 
     const scene = buildVomScene(axNodes, captured);
     expect(scene.nodes.find((n) => n.id === 20)).toEqual(
-      expect.objectContaining({ id: 20, role: "generic", attrs: { "aria-label": "收藏" } }),
+      expect.objectContaining({ id: 20, role: "button", attrs: { "aria-label": "收藏" } }),
     );
-    expect(scene.nodes.find((n) => n.id === 30)?.role).toBe("generic");
+    expect(scene.nodes.find((n) => n.id === 30)).toBeUndefined();
     const rendered = renderVom(scene);
     expect(rendered.text).toContain('@e1 button "收藏"');
     expect(rendered.refs.map(({ ref, backendNodeId }) => ({ ref, backendNodeId }))).toEqual([
@@ -2131,7 +2131,7 @@ describe("buildVomScene", () => {
     });
 
     expect(scene.surfaces).toEqual([
-      { triggerId: 21, triggerAction: "hover", subItems: ["My profile", "Sign out"] },
+      { triggerId: 20, triggerAction: "hover", subItems: ["My profile", "Sign out"] },
     ]);
     expect(renderVom(scene).text).toContain(
       '@e1 button "image" [hover first: My profile | Sign out]',
@@ -3155,6 +3155,98 @@ describe("handleSnapshot", () => {
     });
   });
 
+  it("decorates live observations with active controlled content", async () => {
+    const strings = [
+      "html",
+      "body",
+      "button",
+      "div",
+      "#text",
+      "role",
+      "tab",
+      "aria-selected",
+      "true",
+      "aria-controls",
+      "reviews-panel",
+      "id",
+      "static",
+      "auto",
+      "visible",
+      "1",
+      "A detailed review",
+    ];
+    const index = (value: string) => strings.indexOf(value);
+    const style = [index("static"), index("auto"), index("auto"), index("visible"), index("1")];
+    const snapshot = {
+      strings,
+      documents: [
+        {
+          nodes: {
+            parentIndex: [-1, 0, 1, 1, 3],
+            nodeName: [index("html"), index("body"), index("button"), index("div"), index("#text")],
+            backendNodeId: [10, 11, 12, 13, 14],
+            attributes: [
+              [],
+              [],
+              [
+                index("role"),
+                index("tab"),
+                index("aria-selected"),
+                index("true"),
+                index("aria-controls"),
+                index("reviews-panel"),
+              ],
+              [index("id"), index("reviews-panel")],
+              [],
+            ],
+            nodeValue: [-1, -1, -1, -1, index("A detailed review")],
+          },
+          layout: {
+            nodeIndex: [0, 1, 2, 3, 4],
+            styles: [style, style, style, style, style],
+            bounds: [
+              [0, 0, 1000, 800],
+              [0, 0, 1000, 800],
+              [20, 20, 120, 40],
+              [20, 80, 500, 200],
+              [20, 80, 200, 20],
+            ],
+            paintOrders: [0, 0, 1, 1, 1],
+          },
+        },
+      ],
+    };
+    const ax: CdpAxNode[] = [
+      {
+        nodeId: "root",
+        backendDOMNodeId: 11,
+        role: { type: "role", value: "RootWebArea" },
+        childIds: ["reviews"],
+      },
+      {
+        nodeId: "reviews",
+        parentId: "root",
+        backendDOMNodeId: 12,
+        role: { type: "role", value: "tab" },
+        name: { type: "computedString", value: "Reviews" },
+        properties: [
+          { name: "selected", value: { value: true } },
+          { name: "controls", value: { value: "reviews-panel" } },
+        ],
+      },
+    ];
+
+    const result = await captureVomObservation(
+      makeOverlayDeps(ax, snapshot, VP_METRICS).cdp,
+      4,
+      "https://example.com",
+    );
+
+    expect(result.text).toContain('@e1 tab "Reviews"');
+    expect(result.text).toContain("[§ active: Reviews]");
+    expect(result.text).toContain("A detailed review");
+  });
+
   it("does not leak form secrets through the record-safe observation payload", async () => {
     const secrets = {
       email: "user@example.com",

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

@@ -36,7 +36,7 @@ function fakeSnapshotReply() {
         },
         layout: {
           nodeIndex: [1, 2, 3],
-          // styles columns follow requested computedStyles order: [position, pointer-events]
+          // Legacy fixture: omitted style columns fall back to visible defaults.
           styles: [
             [i("static"), i("auto")],
             [i("fixed"), i("auto")],
@@ -682,6 +682,46 @@ describe("captureViewModel", () => {
     expect(nodes.find((n) => n.backendNodeId === 11)?.cursor).toBe("auto");
   });
 
+  it("captures painted visibility as DOM fallback evidence", async () => {
+    const S = ["html", "body", "button", "static", "auto", "visible", "hidden", "1", "0"];
+    const i = (value: string) => S.indexOf(value);
+    const snapshot = {
+      strings: S,
+      documents: [
+        {
+          nodes: {
+            parentIndex: [-1, 0, 1, 1, 1],
+            nodeName: [i("html"), i("body"), i("button"), i("button"), i("button")],
+            backendNodeId: [10, 11, 12, 13, 14],
+            attributes: [[], [], [], [], []],
+          },
+          layout: {
+            nodeIndex: [1, 2, 3, 4],
+            styles: [
+              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("hidden"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("visible"), i("0")],
+            ],
+            bounds: [
+              [0, 0, 1000, 800],
+              [10, 10, 100, 30],
+              [10, 50, 100, 30],
+              [10, 90, 100, 30],
+            ],
+            paintOrders: [0, 1, 2, 3],
+          },
+        },
+      ],
+    };
+
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
+
+    expect(nodes.find((node) => node.backendNodeId === 12)?.rendered).toBe(true);
+    expect(nodes.find((node) => node.backendNodeId === 13)?.rendered).toBe(false);
+    expect(nodes.find((node) => node.backendNodeId === 14)?.rendered).toBe(false);
+  });
+
   it("subtracts scroll offset to make rects viewport-relative", async () => {
     const cdp = {
       send: vi.fn(async (_t: number, method: string) => {

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

@@ -132,4 +132,67 @@ describe("captureFrameData", () => {
       ]),
     );
   });
+
+  it("keeps OOPIF semantics when viewport projection is unavailable", async () => {
+    const owner = { ...ownerNode(10, 50), rect: null, localRect: null };
+    const captured: CapturedViewModel = {
+      nodes: [owner],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(),
+      frameNodes: new Map([["main", [owner]]]),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method) => {
+        if (method === "Accessibility.enable") return {};
+        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+        if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
+        if (method === "Page.getLayoutMetrics") {
+          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+        }
+        throw new Error(`unexpected root ${method}`);
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Page.getLayoutMetrics") throw new Error("viewport unavailable");
+        if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
+        if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("child", 101);
+        if (method === "Accessibility.getFullAXTree") {
+          return {
+            nodes: [
+              {
+                nodeId: "button",
+                backendDOMNodeId: 101,
+                role: { type: "role", value: "button" },
+                name: { type: "computedString", value: "Continue" },
+              },
+            ],
+          };
+        }
+        throw new Error(`unexpected ${method}`);
+      }) as unknown as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4, sessionId: "child-session" },
+          },
+        ],
+      })),
+    };
+
+    const documents = await captureFrameData(cdp, 4, captured);
+    const childDocument = documents.find((document) => document.frameId === "child");
+
+    expect(childDocument?.axNodes).toEqual([
+      expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
+    ]);
+    expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
+      expect.objectContaining({ rect: null, localRect: { x: 10, y: 20, w: 100, h: 40 } }),
+    );
+  });
 });

apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it, vi } from "vitest";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import type { CdpRunner } from "../../shared";
+import type { CapturedNode } from "../capture";
+import type { FrameDocument, FrameOwnedAxNode } from "../frame-document";
+import { probeTooltipNames } from "../name-enrichment";
+import { buildSemanticGraph, resolveSemanticGraph } from "../semantic-graph";
+import { stableIdentifierName } from "../semantic-graph/name-evidence";
+import { frameBackendKey } from "../semantic-graph/types";
+
+function document(
+  target: CdpTarget,
+  backendNodeId: number,
+  accessibleName?: string,
+  frameId = "child",
+  x = 10,
+): FrameDocument<FrameOwnedAxNode> {
+  const node: CapturedNode = {
+    backendNodeId,
+    parentBackendNodeId: null,
+    frameId,
+    tag: "button",
+    attrs: {
+      id: "toolInsertRecord",
+      "data-test-id": "toolInsertRecord",
+      ...(accessibleName ? { "aria-label": accessibleName } : {}),
+    },
+    rect: { x, y: 20, w: 40, h: 30 },
+    localRect: { x: 2, y: 3, w: 40, h: 30 },
+    paintOrder: 1,
+    position: "static",
+    pointerEvents: "auto",
+    cursor: "pointer",
+  };
+  return {
+    frameId,
+    parentFrameId: "main",
+    contextScopeId: "child",
+    target,
+    axNodes: [],
+    domNodes: [node],
+    url: "https://example.com/frame",
+  };
+}
+
+function semantics(documents: FrameDocument<FrameOwnedAxNode>[]) {
+  return resolveSemanticGraph(
+    buildSemanticGraph({
+      documents,
+      viewport: { width: 800, height: 600 },
+      rootFrameId: documents[0]?.frameId,
+    }),
+    { identifierFallback: false },
+  );
+}
+
+describe("tooltip name enrichment", () => {
+  it("uses the owning frame target and upgrades an identifier name from a tooltip", async () => {
+    const target = { tabId: 7, sessionId: "oopif-session" };
+    let hovered = false;
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        if (method === "Input.dispatchMouseEvent") {
+          hovered = (params as { x?: number }).x === 30;
+        }
+        return {};
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Page.createIsolatedWorld") return { executionContextId: 11 };
+        if (method === "DOM.resolveNode") return { object: { objectId: "button-501" } };
+        if (method === "Runtime.callFunctionOn") {
+          return { result: { value: hovered ? ["插入行"] : [] } };
+        }
+        return {};
+      }) as CdpRunner["sendToTarget"],
+    };
+
+    const documents = [document(target, 501)];
+    const graph = semantics(documents);
+    const names = await probeTooltipNames(cdp, 7, documents, graph);
+
+    expect(names.get(frameBackendKey("child", 501))).toBe("插入行");
+    expect(cdp.sendToTarget).toHaveBeenCalledWith(
+      target,
+      "Page.createIsolatedWorld",
+      expect.objectContaining({ frameId: "child" }),
+    );
+
+    const sendsBeforeCache = vi.mocked(cdp.send).mock.calls.length;
+    const targetSendsBeforeCache = vi.mocked(
+      cdp.sendToTarget as NonNullable<CdpRunner["sendToTarget"]>,
+    ).mock.calls.length;
+    const cached = await probeTooltipNames(cdp, 7, documents, graph);
+    expect(cached.get(frameBackendKey("child", 501))).toBe("插入行");
+    expect(cdp.send).toHaveBeenCalledTimes(sendsBeforeCache);
+    expect(cdp.sendToTarget).toHaveBeenCalledTimes(targetSendsBeforeCache);
+  });
+
+  it("does not probe controls that already have a higher-confidence name", async () => {
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      sendToTarget: vi.fn(async () => ({ executionContextId: 12 })) as CdpRunner["sendToTarget"],
+    };
+
+    const documents = [document({ tabId: 8 }, 601, "Add a new record")];
+    const names = await probeTooltipNames(cdp, 8, documents, semantics(documents));
+
+    expect(names.size).toBe(0);
+    expect(cdp.send).not.toHaveBeenCalled();
+    expect(cdp.sendToTarget).not.toHaveBeenCalled();
+  });
+
+  it("does not collect supplemental names from form controls", async () => {
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      sendToTarget: vi.fn(async () => ({ executionContextId: 12 })) as CdpRunner["sendToTarget"],
+    };
+    const inputDocument = document({ tabId: 8 }, 602);
+    inputDocument.domNodes[0] = {
+      ...inputDocument.domNodes[0],
+      tag: "input",
+      attrs: { type: "email" },
+      formValue: "user@example.com",
+      formDefaultValue: "",
+      formState: "filled",
+    };
+
+    const names = await probeTooltipNames(cdp, 8, [inputDocument], semantics([inputDocument]));
+
+    expect(names.size).toBe(0);
+    expect(cdp.send).not.toHaveBeenCalled();
+    expect(cdp.sendToTarget).not.toHaveBeenCalled();
+  });
+
+  it("keeps tooltip evidence isolated across sibling frame sessions", async () => {
+    let hoveredX = -10;
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        if (method === "Input.dispatchMouseEvent") {
+          hoveredX = (params as { x: number }).x;
+        }
+        return {};
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (target, method, params) => {
+        if (method === "Page.createIsolatedWorld") {
+          return { executionContextId: target.sessionId === "left-session" ? 21 : 22 };
+        }
+        if (method === "DOM.resolveNode") {
+          return { object: { objectId: target.sessionId === "left-session" ? "left" : "right" } };
+        }
+        if (method === "Runtime.callFunctionOn") {
+          const objectId = (params as { objectId: string }).objectId;
+          const value =
+            objectId === "left" && hoveredX === 30
+              ? ["Left action"]
+              : objectId === "right" && hoveredX === 130
+                ? ["Right action"]
+                : [];
+          return { result: { value } };
+        }
+        return {};
+      }) as CdpRunner["sendToTarget"],
+    };
+    const documents = [
+      document({ tabId: 9, sessionId: "left-session" }, 701, undefined, "left", 10),
+      document({ tabId: 9, sessionId: "right-session" }, 701, undefined, "right", 110),
+    ];
+
+    const names = await probeTooltipNames(cdp, 9, documents, semantics(documents));
+
+    expect(names.get(frameBackendKey("left", 701))).toBe("Left action");
+    expect(names.get(frameBackendKey("right", 701))).toBe("Right action");
+  });
+});
+
+describe("stable identifier evidence", () => {
+  it("accepts readable action identifiers and rejects framework-generated ids", () => {
+    expect(stableIdentifierName({ id: "toolInsertRecord" })).toBe("Insert record");
+    expect(stableIdentifierName({ id: "reactivateAccount" })).toBe("Reactivate account");
+    expect(stableIdentifierName({ id: "headlessui-menu-button-r1" })).toBeUndefined();
+    expect(stableIdentifierName({ id: "7f15a3bc91" })).toBeUndefined();
+  });
+});

apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts

@@ -0,0 +1,782 @@
+import { isVomReferenceNode, renderVom } from "@browser-skill/vom";
+import { describe, expect, it } from "vitest";
+import type { CapturedNode } from "../capture";
+import type { FrameDocument } from "../frame-document";
+import { buildSemanticVomScene, type SemanticAxNode } from "../semantic-graph";
+
+function dom(
+  backendNodeId: number,
+  parentBackendNodeId: number | null,
+  tag: string,
+  attrs: Record<string, string> = {},
+  textContent?: string,
+): CapturedNode {
+  return {
+    backendNodeId,
+    parentBackendNodeId,
+    tag,
+    attrs,
+    rect: { x: 0, y: 0, w: 100, h: 30 },
+    paintOrder: backendNodeId,
+    position: "static",
+    pointerEvents: "auto",
+    ...(textContent ? { textContent } : {}),
+  };
+}
+
+function document(
+  frameId: string,
+  axNodes: SemanticAxNode[],
+  domNodes: CapturedNode[],
+  frame?: Pick<FrameDocument<SemanticAxNode>, "parentFrameId" | "ownerBackendNodeId">,
+): FrameDocument<SemanticAxNode> {
+  return {
+    frameId,
+    contextScopeId: frameId,
+    target: { tabId: 1 },
+    axNodes,
+    domNodes,
+    ...frame,
+  };
+}
+
+describe("semantic VOM graph", () => {
+  it("preserves backend-less AX structure without making it referenceable", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["toolbar"],
+            },
+            {
+              nodeId: "toolbar",
+              parentId: "root",
+              role: { type: "role", value: "toolbar" },
+              name: { type: "computedString", value: "Formatting" },
+              childIds: ["bold", "italic"],
+            },
+            {
+              nodeId: "bold",
+              parentId: "toolbar",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Bold" },
+            },
+            {
+              nodeId: "italic",
+              parentId: "toolbar",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Italic" },
+            },
+          ],
+          [dom(1, null, "body"), dom(2, 1, "button"), dom(3, 1, "button")],
+        ),
+      ],
+    });
+
+    const toolbar = scene.nodes.find((node) => node.role === "toolbar");
+    const buttons = scene.nodes.filter((node) => node.role === "button");
+    expect(toolbar).toEqual(expect.objectContaining({ name: "Formatting", referenceable: false }));
+    expect(buttons.map((node) => node.parentId)).toEqual([toolbar?.id, toolbar?.id]);
+    expect(toolbar && isVomReferenceNode(toolbar)).toBe(false);
+    expect(renderVom(scene).refs.map((ref) => ref.backendNodeId)).toEqual([2, 3]);
+  });
+
+  it("resolves missing AX names through one DOM naming pipeline", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["labelled", "titled", "text"],
+            },
+            {
+              nodeId: "labelled",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "button" },
+            },
+            {
+              nodeId: "titled",
+              parentId: "root",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+            },
+            {
+              nodeId: "text",
+              parentId: "root",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "button", { "aria-label": "Add row" }),
+            dom(3, 1, "button", { title: "Settings" }),
+            dom(4, 1, "button"),
+            dom(5, 4, "span", {}, "Save"),
+          ],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.filter((node) => node.role === "button").map((node) => node.name)).toEqual([
+      "Add row",
+      "Settings",
+      "Save",
+    ]);
+  });
+
+  it("aggregates AX text at the semantic text frontier", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["covered", "inline-only", "repeated", "labelled"],
+            },
+            {
+              nodeId: "covered",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "paragraph" },
+              childIds: ["covered-static"],
+            },
+            {
+              nodeId: "covered-static",
+              parentId: "covered",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Covered text" },
+              childIds: ["covered-inline"],
+            },
+            {
+              nodeId: "covered-inline",
+              parentId: "covered-static",
+              role: { type: "role", value: "InlineTextBox" },
+              name: { type: "computedString", value: "Covered text" },
+            },
+            {
+              nodeId: "inline-only",
+              parentId: "root",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "paragraph" },
+              childIds: ["inline-leaf"],
+            },
+            {
+              nodeId: "inline-leaf",
+              parentId: "inline-only",
+              role: { type: "role", value: "InlineTextBox" },
+              name: { type: "computedString", value: "Inline fallback" },
+            },
+            {
+              nodeId: "repeated",
+              parentId: "root",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "paragraph" },
+              childIds: ["first-go", "second-go"],
+            },
+            {
+              nodeId: "first-go",
+              parentId: "repeated",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Go" },
+            },
+            {
+              nodeId: "second-go",
+              parentId: "repeated",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Go" },
+            },
+            {
+              nodeId: "labelled",
+              parentId: "root",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              childIds: ["visible-label"],
+            },
+            {
+              nodeId: "visible-label",
+              parentId: "labelled",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Visible text" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "p"),
+            dom(3, 1, "p"),
+            dom(4, 1, "p"),
+            dom(5, 1, "button", { "aria-label": "Explicit action" }),
+          ],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("Covered text");
+    expect(scene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe("Inline fallback");
+    expect(scene.nodes.find((node) => node.backendNodeId === 4)?.name).toBe("Go Go");
+    expect(scene.nodes.find((node) => node.backendNodeId === 5)?.name).toBe("Explicit action");
+    expect(renderVom(scene).text).not.toContain("Covered text Covered text");
+  });
+
+  it("uses stable identifiers only as a final name fallback", () => {
+    const base = document(
+      "main",
+      [
+        {
+          nodeId: "root",
+          backendDOMNodeId: 1,
+          role: { type: "role", value: "RootWebArea" },
+          childIds: ["fallback", "labelled", "container"],
+        },
+        {
+          nodeId: "fallback",
+          parentId: "root",
+          backendDOMNodeId: 2,
+          role: { type: "role", value: "button" },
+        },
+        {
+          nodeId: "labelled",
+          parentId: "root",
+          backendDOMNodeId: 3,
+          role: { type: "role", value: "button" },
+          name: { type: "computedString", value: "Localized name" },
+        },
+        {
+          nodeId: "container",
+          parentId: "root",
+          backendDOMNodeId: 4,
+          role: { type: "role", value: "generic" },
+        },
+      ],
+      [
+        dom(1, null, "body"),
+        dom(2, 1, "button", { "data-test-id": "toolInsertRecord" }),
+        dom(3, 1, "button", { id: "toolIgnoredFallback" }),
+        dom(4, 1, "div", { id: "toolbarContainer" }),
+      ],
+    );
+    const staticScene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [base],
+    });
+    const enrichedScene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [base],
+      supplementalNames: new Map([["main\u00002", "插入行"]]),
+    });
+
+    expect(staticScene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("Insert record");
+    expect(staticScene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe("Localized name");
+    expect(staticScene.nodes.find((node) => node.backendNodeId === 4)?.name).toBeUndefined();
+    expect(enrichedScene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("插入行");
+    expect(enrichedScene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe(
+      "Localized name",
+    );
+  });
+
+  it("isolates equal backend node ids in sibling frames", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 1000, height: 800 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["owner-a", "owner-b"],
+            },
+            {
+              nodeId: "owner-a",
+              parentId: "root",
+              backendDOMNodeId: 10,
+              role: { type: "role", value: "Iframe" },
+            },
+            {
+              nodeId: "owner-b",
+              parentId: "root",
+              backendDOMNodeId: 20,
+              role: { type: "role", value: "Iframe" },
+            },
+          ],
+          [dom(1, null, "body"), dom(10, 1, "iframe"), dom(20, 1, "iframe")],
+        ),
+        document(
+          "frame-a",
+          [
+            {
+              nodeId: "button-a",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              childIds: ["text-a"],
+            },
+            {
+              nodeId: "text-a",
+              parentId: "button-a",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Accept" },
+              childIds: ["inline-a"],
+            },
+            {
+              nodeId: "inline-a",
+              parentId: "text-a",
+              role: { type: "role", value: "InlineTextBox" },
+              name: { type: "computedString", value: "Accept" },
+            },
+          ],
+          [dom(5, null, "button")],
+          { parentFrameId: "main", ownerBackendNodeId: 10 },
+        ),
+        document(
+          "frame-b",
+          [
+            {
+              nodeId: "button-b",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              childIds: ["text-b"],
+            },
+            {
+              nodeId: "text-b",
+              parentId: "button-b",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Decline" },
+              childIds: ["inline-b"],
+            },
+            {
+              nodeId: "inline-b",
+              parentId: "text-b",
+              role: { type: "role", value: "InlineTextBox" },
+              name: { type: "computedString", value: "Decline" },
+            },
+          ],
+          [dom(5, null, "button")],
+          { parentFrameId: "main", ownerBackendNodeId: 20 },
+        ),
+      ],
+    });
+
+    const frameButtons = scene.nodes.filter((node) => node.backendNodeId === 5);
+    const owners = new Map(
+      scene.nodes
+        .filter((node) => node.backendNodeId === 10 || node.backendNodeId === 20)
+        .map((node) => [node.backendNodeId, node.id]),
+    );
+    expect(frameButtons.map((node) => node.frameId)).toEqual(["frame-a", "frame-b"]);
+    expect(frameButtons.map((node) => node.name)).toEqual(["Accept", "Decline"]);
+    expect(frameButtons.map((node) => node.parentId)).toEqual([owners.get(10), owners.get(20)]);
+    expect(renderVom(scene).refs.map((ref) => [ref.frameId, ref.backendNodeId])).toEqual([
+      ["frame-a", 5],
+      ["frame-b", 5],
+    ]);
+  });
+
+  it("requires render evidence before promoting DOM fallback semantics", () => {
+    const hiddenOwner = {
+      ...dom(10, 1, "iframe", { hidden: "" }),
+      rect: null,
+      localRect: null,
+      rendered: false,
+    };
+    const hiddenButton = {
+      ...dom(2, 1, "button", { "aria-label": "Hidden action" }),
+      rendered: false,
+    };
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+            },
+          ],
+          [dom(1, null, "body"), hiddenButton, hiddenOwner],
+        ),
+        document("hidden-frame", [], [dom(20, null, "button", {}, "Frame action")], {
+          parentFrameId: "main",
+          ownerBackendNodeId: 10,
+        }),
+      ],
+    });
+
+    expect(scene.nodes.some((node) => node.backendNodeId === 2)).toBe(false);
+    expect(scene.nodes.some((node) => node.backendNodeId === 10)).toBe(false);
+    expect(scene.nodes.some((node) => node.frameId === "hidden-frame")).toBe(false);
+    expect(renderVom(scene).refs).toEqual([]);
+  });
+
+  it("retains rendered DOM fallback controls when AX semantics are unavailable", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [],
+          [dom(1, null, "body"), { ...dom(2, 1, "button", {}, "Save"), rendered: true }],
+        ),
+      ],
+    });
+
+    expect(renderVom(scene).refs).toEqual([
+      expect.objectContaining({ backendNodeId: 2, role: "button", name: "Save" }),
+    ]);
+  });
+
+  it("lets explicit DOM structure override ignored AX metadata", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["toolbar"],
+            },
+            {
+              nodeId: "toolbar",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              ignored: true,
+              role: { type: "role", value: "generic" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "toolbar",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "generic" },
+              childIds: ["bold", "italic"],
+            },
+            {
+              nodeId: "bold",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Bold" },
+            },
+            {
+              nodeId: "italic",
+              parentId: "wrapper",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Italic" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "div", { role: "toolbar" }),
+            dom(5, 2, "div"),
+            dom(3, 5, "button"),
+            dom(4, 5, "button"),
+          ],
+        ),
+      ],
+    });
+
+    const toolbar = scene.nodes.find((node) => node.backendNodeId === 2);
+    const buttons = scene.nodes.filter((node) => [3, 4].includes(node.backendNodeId ?? -1));
+    expect(toolbar).toEqual(expect.objectContaining({ role: "toolbar" }));
+    expect(toolbar && isVomReferenceNode(toolbar)).toBe(false);
+    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
+    expect(buttons.map((node) => node.parentId)).toEqual([toolbar?.id, toolbar?.id]);
+  });
+
+  it("infers an unnamed group only from independent interaction branches", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["first", "second"],
+            },
+            {
+              nodeId: "first",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "First" },
+            },
+            {
+              nodeId: "second",
+              parentId: "wrapper",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Second" },
+            },
+          ],
+          [dom(1, null, "body"), dom(2, 1, "div"), dom(3, 2, "button"), dom(4, 2, "button")],
+        ),
+      ],
+    });
+
+    const group = scene.nodes.find((node) => node.backendNodeId === 2);
+    const buttons = scene.nodes.filter((node) => [3, 4].includes(node.backendNodeId ?? -1));
+    expect(group).toEqual(expect.objectContaining({ role: "group" }));
+    expect(group?.name).toBeUndefined();
+    expect(group && isVomReferenceNode(group)).toBe(false);
+    expect(buttons.map((node) => node.parentId)).toEqual([group?.id, group?.id]);
+
+    const rendered = renderVom(scene);
+    const lines = rendered.text.split("\n");
+    const groupLine = lines.findIndex((line) => line.trim() === "group");
+    expect(groupLine).toBeGreaterThanOrEqual(0);
+    for (const ref of rendered.refs) {
+      expect(ref.line).toBeGreaterThan(groupLine);
+      expect(lines[ref.line]).toMatch(/^\s+@e\d+ button/);
+    }
+  });
+
+  it("never promotes a form value into its semantic name through supplemental evidence", () => {
+    const secret = "user@example.com";
+    const input = {
+      ...dom(2, 1, "input", { type: "email" }),
+      formValue: secret,
+      formDefaultValue: "",
+      formState: "filled" as const,
+    };
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      supplementalNames: new Map([["main\u00002", secret]]),
+      identifierFallback: false,
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["email"],
+            },
+            {
+              nodeId: "email",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "textbox" },
+              value: { value: secret },
+            },
+          ],
+          [dom(1, null, "body"), input],
+        ),
+      ],
+    });
+
+    const field = scene.nodes.find((node) => node.backendNodeId === 2);
+    expect(field?.name).toBeUndefined();
+    const rendered = renderVom(scene, { redactValues: true });
+    expect(rendered.text).toContain("•••");
+    expect(JSON.stringify(rendered)).not.toContain(secret);
+  });
+
+  it("keeps uncertain single-branch wrappers flat", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["button"],
+            },
+            {
+              nodeId: "button",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Only action" },
+            },
+          ],
+          [dom(1, null, "body"), dom(2, 1, "div"), dom(3, 2, "button")],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
+    expect(scene.nodes.find((node) => node.backendNodeId === 3)?.parentId).toBe(
+      scene.nodes.find((node) => node.backendNodeId === 1)?.id,
+    );
+  });
+
+  it("does not infer across mixed content boundaries", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["first", "second", "paragraph"],
+            },
+            {
+              nodeId: "first",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "First" },
+            },
+            {
+              nodeId: "second",
+              parentId: "wrapper",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Second" },
+            },
+            {
+              nodeId: "paragraph",
+              parentId: "wrapper",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "paragraph" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "div"),
+            dom(3, 2, "button"),
+            dom(4, 2, "button"),
+            dom(5, 2, "p", {}, "Description"),
+          ],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
+  });
+
+  it("keeps only the innermost reliable inferred group", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["outer"],
+            },
+            {
+              nodeId: "outer",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["inner", "third"],
+            },
+            {
+              nodeId: "inner",
+              parentId: "outer",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "generic" },
+              childIds: ["first", "second"],
+            },
+            {
+              nodeId: "first",
+              parentId: "inner",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "First" },
+            },
+            {
+              nodeId: "second",
+              parentId: "inner",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Second" },
+            },
+            {
+              nodeId: "third",
+              parentId: "outer",
+              backendDOMNodeId: 6,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Third" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "div"),
+            dom(3, 2, "div"),
+            dom(4, 3, "button"),
+            dom(5, 3, "button"),
+            dom(6, 2, "button"),
+          ],
+        ),
+      ],
+    });
+
+    const groups = scene.nodes.filter((node) => node.role === "group");
+    expect(groups.map((node) => node.backendNodeId)).toEqual([3]);
+    expect(scene.nodes.find((node) => node.backendNodeId === 6)?.parentId).not.toBe(groups[0]?.id);
+  });
+});

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

@@ -1,16 +1,17 @@
 // CDP capture adapter: DOMSnapshot.captureSnapshot + Page.getLayoutMetrics
 // → CapturedNode[] + Viewport. This is the ONLY VOM module that touches
 // raw CDP. The captureSnapshot reply is columnar (parallel arrays + a
-// shared string table); we request exactly three computed styles so the
-// `styles` columns are [position, pointer-events, cursor] in that order.
+// shared string table); requested computed styles are decoded through
+// STYLE_COL so capture and visibility policy share one explicit contract.
 
 import type { Rect, Viewport } from "@browser-skill/vom";
 import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
 import { isOverlayHostNode, OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
 import { childFrameProjection, type GeometryProjection, projectRectToViewport } from "../geometry";
 import type { CdpRunner } from "../shared";
+import { clearHover, waitForHover } from "./hover-perception";
 
-const REQUESTED_STYLES = ["position", "pointer-events", "cursor"] as const;
+const REQUESTED_STYLES = ["position", "pointer-events", "cursor", "visibility", "opacity"] as const;
 const STYLE_COL = Object.fromEntries(
   REQUESTED_STYLES.map((name, index) => [name, index]),
 ) as Record<(typeof REQUESTED_STYLES)[number], number>;
@@ -38,6 +39,12 @@ export interface CapturedNode {
    * `textContent`: the live parser always sets it, hand-built fixtures may not.
    */
   cursor?: string;
+  /**
+   * Whether the live DOM snapshot provides a painted, non-hidden box for this
+   * node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
+   * nodes remain authoritative even when they are outside the viewport.
+   */
+  rendered?: boolean;
   textContent?: string;
   formState?: "empty" | "filled" | "default";
   formValue?: string;
@@ -460,36 +467,6 @@ function hoverStateExpression(): string {
   })()`;
 }
 
-async function wait(ms: number, signal?: AbortSignal): Promise<void> {
-  throwIfAborted(signal);
-  await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = () => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-      reject(captureAbortError());
-    };
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-async function clearHover(cdp: CdpRunner, tabId: number): Promise<void> {
-  await cdp
-    .send(tabId, "Input.dispatchMouseEvent", {
-      type: "mouseMoved",
-      x: -10,
-      y: -10,
-    })
-    .catch(() =>
-      cdp.send(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x: 0, y: 0 }).catch(() => {
-        // best effort
-      }),
-    );
-}
-
 function capturedText(node: CapturedNode): string | undefined {
   const value =
     node.attrs["aria-label"] ?? node.attrs.title ?? node.attrs.alt ?? node.textContent ?? "";
@@ -669,7 +646,7 @@ async function probeHoverSurfaces(
         try {
           await clearHover(cdp, tabId);
           throwIfAborted(options.signal);
-          await wait(HOVER_SETTLE_MS, options.signal);
+          await waitForHover(HOVER_SETTLE_MS, options.signal);
           const baselineReply = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
             expression: hoverStateExpression(),
             returnByValue: true,
@@ -684,7 +661,7 @@ async function probeHoverSurfaces(
             y: candidate.y,
           });
           throwIfAborted(options.signal);
-          await wait(HOVER_SETTLE_MS, options.signal);
+          await waitForHover(HOVER_SETTLE_MS, options.signal);
           const collected = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
             expression: hoverStateExpression(),
             returnByValue: true,
@@ -817,6 +794,8 @@ function parseDocumentNodes(
   const posCol = STYLE_COL.position;
   const peCol = STYLE_COL["pointer-events"];
   const cursorCol = STYLE_COL.cursor;
+  const visibilityCol = STYLE_COL.visibility;
+  const opacityCol = STYLE_COL.opacity;
   const inputValues = sparseIndexMap(dn.inputValue);
   const textValues = sparseIndexMap(dn.textValue);
   const checkedInputs = new Set(dn.inputChecked?.index ?? []);
@@ -861,6 +840,7 @@ function parseDocumentNodes(
     let position = "static";
     let pointerEvents = "auto";
     let cursor = "auto";
+    let rendered = false;
     const li = layoutByNode.get(n);
     if (li !== undefined) {
       const b = dl?.bounds?.[li];
@@ -881,6 +861,13 @@ function parseDocumentNodes(
       position = str(strings, styleRow[posCol]) || "static";
       pointerEvents = str(strings, styleRow[peCol]) || "auto";
       cursor = str(strings, styleRow[cursorCol]) || "auto";
+      const visibility = str(strings, styleRow[visibilityCol]) || "visible";
+      const opacity = str(strings, styleRow[opacityCol]) || "1";
+      rendered =
+        localRect !== null &&
+        visibility !== "hidden" &&
+        visibility !== "collapse" &&
+        (Number.parseFloat(opacity) || 0) > 0;
     }
 
     // Skip non-element nodes (#text, #cdata-section, etc.) — they carry no
@@ -916,6 +903,7 @@ function parseDocumentNodes(
       position,
       pointerEvents,
       cursor,
+      rendered,
       textContent,
       ...(formValue !== undefined ? { formValue } : {}),
       ...(tag === "input" || tag === "textarea"
@@ -1020,7 +1008,13 @@ export async function captureViewModel(
   options: CaptureViewModelOptions = {},
 ): Promise<CapturedViewModel> {
   throwIfAborted(options.signal);
-  const metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
+  let metrics: LayoutMetricsReply = {};
+  try {
+    metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    console.debug("[bsk capture] layout metrics unavailable", error);
+  }
   throwIfAborted(options.signal);
   const dpr = devicePixelRatio(metrics);
   const vpSrc = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};

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

@@ -33,25 +33,19 @@ async function discoverFrameGraph(cdp: CdpRunner, tabId: number): Promise<CdpFra
 
 function transformFrameNodes(
   nodes: CapturedNode[],
-  projection: GeometryProjection,
+  projection: GeometryProjection | null,
 ): CapturedNode[] {
   return nodes.map((node) => ({
     ...node,
-    rect: (() => {
-      const bounds = projectRectToViewport(node.rect, projection);
-      return bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
-    })(),
+    rect: projection
+      ? (() => {
+          const bounds = projectRectToViewport(node.rect, projection);
+          return bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
+        })()
+      : null,
   }));
 }
 
-function frameOwnerNode(captured: CapturedViewModel, frame: CdpFrame): CapturedNode | undefined {
-  if (frame.ownerBackendNodeId === undefined) return undefined;
-  const parentNodes = frame.parentFrameId
-    ? captured.frameNodes?.get(frame.parentFrameId)
-    : captured.nodes;
-  return parentNodes?.find((node) => node.backendNodeId === frame.ownerBackendNodeId);
-}
-
 async function captureMissingFrameDocuments(
   cdp: CdpRunner,
   tabId: number,
@@ -65,14 +59,20 @@ async function captureMissingFrameDocuments(
 
   for (const frame of graph.frames) {
     if (!frame.target.sessionId || captured.frameNodes.has(frame.frameId)) continue;
-    const owner = frameOwnerNode(captured, frame);
-    if (!owner?.rect || frame.ownerBackendNodeId === undefined) continue;
     try {
       const child = await captureViewModel(cdpRunnerForTarget(cdp, frame.target), tabId, {
         signal,
       });
-      const projection = await resolveFrameProjection(cdp, graph, frame.frameId);
-      if (!projection) continue;
+      let projection: GeometryProjection | null = null;
+      try {
+        projection = await resolveFrameProjection(cdp, graph, frame.frameId);
+      } catch (err) {
+        if (isAbortError(err)) throw err;
+        console.debug("[bsk observation] child frame geometry projection failed", {
+          frameId: frame.frameId,
+          err,
+        });
+      }
       const rootFrameId = child.rootFrameId ?? frame.frameId;
       const childFrames = child.frameNodes ?? new Map<string, CapturedNode[]>();
       if (!childFrames.has(rootFrameId)) childFrames.set(rootFrameId, child.nodes);
@@ -85,11 +85,13 @@ async function captureMissingFrameDocuments(
       for (const [childFrameId, nodes] of childFrames) {
         captured.frameNodes.set(childFrameId, transformFrameNodes(nodes, projection));
       }
-      captured.iframeNodes.set(
-        frame.ownerBackendNodeId,
-        captured.frameNodes.get(frame.frameId) ?? [],
-      );
-      captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
+      if (frame.ownerBackendNodeId !== undefined) {
+        captured.iframeNodes.set(
+          frame.ownerBackendNodeId,
+          captured.frameNodes.get(frame.frameId) ?? [],
+        );
+        captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
+      }
       if (frame.parentFrameId) captured.frameParentIds.set(frame.frameId, frame.parentFrameId);
       for (const [childFrameId, ownerBackendNodeId] of child.frameOwnerBackendNodeIds ?? []) {
         captured.frameOwnerBackendNodeIds.set(childFrameId, ownerBackendNodeId);

apps/extension/src/tools/vom/hover-perception.ts

@@ -0,0 +1,37 @@
+import type { CdpRunner } from "../shared";
+
+function abortError(): Error {
+  const error = new Error("hover perception aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+export async function waitForHover(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) throw abortError();
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(abortError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export async function clearHover(cdp: CdpRunner, tabId: number): Promise<void> {
+  await cdp
+    .send(tabId, "Input.dispatchMouseEvent", {
+      type: "mouseMoved",
+      x: -10,
+      y: -10,
+    })
+    .catch(() =>
+      cdp.send(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x: 0, y: 0 }).catch(() => {
+        // Best effort cleanup.
+      }),
+    );
+}

apps/extension/src/tools/vom/name-enrichment.ts

@@ -0,0 +1,296 @@
+import { isVomReferenceNode } from "@browser-skill/vom";
+import { type CdpRunner, sendToCdpTarget } from "../shared";
+import type { FrameDocument, FrameOwnedAxNode } from "./frame-document";
+import { clearHover, waitForHover } from "./hover-perception";
+import { stableIdentifierName } from "./semantic-graph/name-evidence";
+import { frameBackendKey, type ResolvedSemanticGraph } from "./semantic-graph/types";
+
+const MAX_TOOLTIP_CANDIDATES = 8;
+const MAX_TOOLTIP_PROBE_MS = 2_400;
+const TOOLTIP_SETTLE_MS = 250;
+const CACHE_TTL_MS = 5 * 60_000;
+const MAX_CACHE_ENTRIES = 500;
+const FORM_CONTROL_TAGS = new Set(["input", "select", "textarea"]);
+
+interface TooltipCacheEntry {
+  name: string;
+  expiresAt: number;
+}
+
+interface TooltipCandidate<T extends FrameOwnedAxNode> {
+  document: FrameDocument<T>;
+  backendNodeId: number;
+  x: number;
+  y: number;
+  stableIdentifier: boolean;
+}
+
+export interface TooltipNameProbeOptions {
+  signal?: AbortSignal;
+  hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
+}
+
+const tooltipCache = new Map<string, TooltipCacheEntry>();
+
+function cacheKey<T extends FrameOwnedAxNode>(
+  document: FrameDocument<T>,
+  backendNodeId: number,
+): string {
+  return `${document.target.tabId}\u0000${document.frameId}\u0000${document.url ?? ""}\u0000${backendNodeId}`;
+}
+
+function cachedName<T extends FrameOwnedAxNode>(
+  document: FrameDocument<T>,
+  backendNodeId: number,
+): string | undefined {
+  const key = cacheKey(document, backendNodeId);
+  const entry = tooltipCache.get(key);
+  if (!entry) return undefined;
+  if (entry.expiresAt <= Date.now()) {
+    tooltipCache.delete(key);
+    return undefined;
+  }
+  return entry.name;
+}
+
+function storeName<T extends FrameOwnedAxNode>(
+  document: FrameDocument<T>,
+  backendNodeId: number,
+  name: string,
+): void {
+  if (tooltipCache.size >= MAX_CACHE_ENTRIES) {
+    const oldest = tooltipCache.keys().next().value;
+    if (oldest !== undefined) tooltipCache.delete(oldest);
+  }
+  tooltipCache.set(cacheKey(document, backendNodeId), {
+    name,
+    expiresAt: Date.now() + CACHE_TTL_MS,
+  });
+}
+
+function tooltipCollectorFunction(): string {
+  return `function() {
+    const ownRoot = this && typeof this.getRootNode === "function" ? this.getRootNode() : null;
+    const roots = ownRoot && ownRoot !== document ? [ownRoot, document] : [document];
+    const items = [];
+    const seen = new Set();
+    for (const root of roots) {
+      for (const el of Array.from(root.querySelectorAll("[role='tooltip']"))) {
+        const style = getComputedStyle(el);
+        const rect = el.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) continue;
+        if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") continue;
+        const text = String(el.getAttribute("aria-label") || el.getAttribute("title") || el.textContent || "")
+          .replace(/\\s+/g, " ")
+          .trim();
+        if (!text || text.length > 160 || seen.has(text)) continue;
+        seen.add(text);
+        items.push(text);
+      }
+    }
+    return items.slice(0, 20);
+  }`;
+}
+
+function cleanTooltipDiff(before: string[], after: string[]): string | undefined {
+  const existing = new Set(before.map((value) => value.toLowerCase()));
+  const added = [...new Set(after.map((value) => value.replace(/\s+/g, " ").trim()))].filter(
+    (value) => value && !existing.has(value.toLowerCase()),
+  );
+  return added.length === 1 ? added[0] : undefined;
+}
+
+function candidates<T extends FrameOwnedAxNode>(
+  documents: FrameDocument<T>[],
+  graph: ResolvedSemanticGraph,
+): TooltipCandidate<T>[] {
+  const documentByFrame = new Map(documents.map((document) => [document.frameId, document]));
+  const byFrame = new Map<string, TooltipCandidate<T>[]>();
+  for (const node of graph.nodes.values()) {
+    if (
+      node.vom.name ||
+      FORM_CONTROL_TAGS.has(node.dom?.tag.toLowerCase() ?? "") ||
+      !node.referenceable ||
+      node.backendNodeId === undefined ||
+      !isVomReferenceNode({
+        ...node.vom,
+        id: 0,
+        parentId: null,
+        backendNodeId: node.backendNodeId,
+        frameId: node.frameId,
+        referenceable: true,
+      })
+    ) {
+      continue;
+    }
+    const document = documentByFrame.get(node.frameId);
+    const rect = node.dom?.rect;
+    if (!document || !rect || rect.w <= 0 || rect.h <= 0) continue;
+    if (
+      rect.x + rect.w <= 0 ||
+      rect.y + rect.h <= 0 ||
+      rect.x >= graph.viewport.width ||
+      rect.y >= graph.viewport.height
+    ) {
+      continue;
+    }
+    if (
+      node.vom.disabled ||
+      node.vom.inert ||
+      node.vom.pointerEvents === "none" ||
+      node.vom.sensitive
+    ) {
+      continue;
+    }
+    const frameCandidates = byFrame.get(node.frameId) ?? [];
+    frameCandidates.push({
+      document,
+      backendNodeId: node.backendNodeId,
+      x: (Math.max(0, rect.x) + Math.min(graph.viewport.width, rect.x + rect.w)) / 2,
+      y: (Math.max(0, rect.y) + Math.min(graph.viewport.height, rect.y + rect.h)) / 2,
+      stableIdentifier: stableIdentifierName(node.dom?.attrs ?? {}) !== undefined,
+    });
+    byFrame.set(node.frameId, frameCandidates);
+  }
+
+  const out: TooltipCandidate<T>[] = [];
+  for (const stableIdentifier of [true, false]) {
+    const queues = documents.map((document) =>
+      (byFrame.get(document.frameId) ?? []).filter(
+        (candidate) => candidate.stableIdentifier === stableIdentifier,
+      ),
+    );
+    for (let index = 0; queues.some((queue) => index < queue.length); index += 1) {
+      for (const queue of queues) {
+        const candidate = queue[index];
+        if (candidate) out.push(candidate);
+      }
+    }
+  }
+  return out;
+}
+
+async function executionContextId<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+): Promise<number | undefined> {
+  const result = await sendToCdpTarget<{ executionContextId?: number }>(
+    cdp,
+    document.target,
+    "Page.createIsolatedWorld",
+    {
+      frameId: document.frameId,
+      worldName: "bsk-vom-tooltip",
+      grantUniveralAccess: false,
+    },
+  );
+  return result.executionContextId;
+}
+
+async function resolvedObjectId<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+  contextId: number,
+  backendNodeId: number,
+): Promise<string | undefined> {
+  const result = await sendToCdpTarget<{
+    object?: { objectId?: string };
+  }>(cdp, document.target, "DOM.resolveNode", {
+    backendNodeId,
+    executionContextId: contextId,
+  });
+  return result.object?.objectId;
+}
+
+async function tooltipTexts<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+  objectId: string,
+): Promise<string[]> {
+  const result = await sendToCdpTarget<{
+    result?: { value?: string[] };
+  }>(cdp, document.target, "Runtime.callFunctionOn", {
+    functionDeclaration: tooltipCollectorFunction(),
+    objectId,
+    returnByValue: true,
+  });
+  return result.result?.value ?? [];
+}
+
+async function releaseObject<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+  objectId: string,
+): Promise<void> {
+  await sendToCdpTarget(cdp, document.target, "Runtime.releaseObject", { objectId }).catch(
+    () => undefined,
+  );
+}
+
+export async function probeTooltipNames<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  tabId: number,
+  documents: FrameDocument<T>[],
+  graph: ResolvedSemanticGraph,
+  options: TooltipNameProbeOptions = {},
+): Promise<Map<string, string>> {
+  const names = new Map<string, string>();
+  const pending: TooltipCandidate<T>[] = [];
+  for (const candidate of candidates(documents, graph)) {
+    const cached = cachedName(candidate.document, candidate.backendNodeId);
+    if (cached) {
+      names.set(frameBackendKey(candidate.document.frameId, candidate.backendNodeId), cached);
+    } else if (pending.length < MAX_TOOLTIP_CANDIDATES) {
+      pending.push(candidate);
+    }
+  }
+  if (pending.length === 0) return names;
+
+  const started = Date.now();
+  const contexts = new Map<string, number>();
+  await options.hoverProbeBypassOverlay?.(tabId, true).catch(() => undefined);
+  try {
+    for (const candidate of pending) {
+      if (options.signal?.aborted) throw new DOMException("observation aborted", "AbortError");
+      if (Date.now() - started >= MAX_TOOLTIP_PROBE_MS) break;
+      let objectId: string | undefined;
+      try {
+        let contextId = contexts.get(candidate.document.frameId);
+        if (contextId === undefined) {
+          contextId = await executionContextId(cdp, candidate.document);
+          if (contextId === undefined) continue;
+          contexts.set(candidate.document.frameId, contextId);
+        }
+        objectId = await resolvedObjectId(
+          cdp,
+          candidate.document,
+          contextId,
+          candidate.backendNodeId,
+        );
+        if (!objectId) continue;
+        await clearHover(cdp, tabId);
+        const before = await tooltipTexts(cdp, candidate.document, objectId);
+        await cdp.send(tabId, "Input.dispatchMouseEvent", {
+          type: "mouseMoved",
+          x: candidate.x,
+          y: candidate.y,
+        });
+        await waitForHover(TOOLTIP_SETTLE_MS, options.signal);
+        const after = await tooltipTexts(cdp, candidate.document, objectId);
+        const name = cleanTooltipDiff(before, after);
+        if (!name) continue;
+        names.set(frameBackendKey(candidate.document.frameId, candidate.backendNodeId), name);
+        storeName(candidate.document, candidate.backendNodeId, name);
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") throw error;
+      } finally {
+        if (objectId) await releaseObject(cdp, candidate.document, objectId);
+        await clearHover(cdp, tabId);
+      }
+    }
+  } finally {
+    await clearHover(cdp, tabId);
+    await options.hoverProbeBypassOverlay?.(tabId, false).catch(() => undefined);
+  }
+  return names;
+}

apps/extension/src/tools/vom/semantic-graph/build.ts

@@ -0,0 +1,154 @@
+import type { Viewport } from "@browser-skill/vom";
+import type { FrameDocument } from "../frame-document";
+import {
+  frameAxKey,
+  frameBackendKey,
+  type SemanticAxNode,
+  type SemanticFrame,
+  type SemanticGraph,
+  type SemanticGraphNode,
+  type SemanticNodeId,
+} from "./types";
+
+export interface BuildSemanticGraphInput {
+  documents: FrameDocument<SemanticAxNode>[];
+  viewport: Viewport;
+  rootFrameId?: string;
+  excludedBackendNodeIds?: ReadonlySet<number>;
+}
+
+function domNodeId(frameId: string, backendNodeId: number): SemanticNodeId {
+  return JSON.stringify([frameId, "dom", backendNodeId]);
+}
+
+function axNodeId(frameId: string, nodeId: string): SemanticNodeId {
+  return JSON.stringify([frameId, "ax", nodeId]);
+}
+
+export function buildSemanticGraph(input: BuildSemanticGraphInput): SemanticGraph {
+  const rootFrameId =
+    input.rootFrameId ??
+    input.documents.find((document) => !document.parentFrameId)?.frameId ??
+    input.documents[0]?.frameId ??
+    "root";
+  const frames = new Map<string, SemanticFrame>();
+  const nodes = new Map<SemanticNodeId, SemanticGraphNode>();
+  const nodeIdsByFrame = new Map<string, SemanticNodeId[]>();
+  const nodeByFrameBackend = new Map<string, SemanticNodeId>();
+  const nodeByFrameAx = new Map<string, SemanticNodeId>();
+
+  for (const [frameOrder, document] of input.documents.entries()) {
+    frames.set(document.frameId, {
+      frameId: document.frameId,
+      ...(document.parentFrameId ? { parentFrameId: document.parentFrameId } : {}),
+      ...(document.ownerBackendNodeId !== undefined
+        ? { ownerBackendNodeId: document.ownerBackendNodeId }
+        : {}),
+      contextScopeId: document.contextScopeId,
+      target: document.target,
+      ...(document.url ? { url: document.url } : {}),
+      order: frameOrder,
+    });
+
+    const frameNodeIds: SemanticNodeId[] = [];
+    nodeIdsByFrame.set(document.frameId, frameNodeIds);
+    for (const [index, dom] of document.domNodes.entries()) {
+      const id = domNodeId(document.frameId, dom.backendNodeId);
+      const node: SemanticGraphNode = {
+        id,
+        frameId: document.frameId,
+        backendNodeId: dom.backendNodeId,
+        dom,
+        sourceOrder: index,
+        excluded:
+          document.frameId === rootFrameId &&
+          input.excludedBackendNodeIds?.has(dom.backendNodeId) === true,
+      };
+      nodes.set(id, node);
+      frameNodeIds.push(id);
+      nodeByFrameBackend.set(frameBackendKey(document.frameId, dom.backendNodeId), id);
+    }
+
+    for (const [index, ax] of document.axNodes.entries()) {
+      const joinedId =
+        typeof ax.backendDOMNodeId === "number"
+          ? nodeByFrameBackend.get(frameBackendKey(document.frameId, ax.backendDOMNodeId))
+          : undefined;
+      const id = joinedId ?? axNodeId(document.frameId, ax.nodeId);
+      const existing = nodes.get(id);
+      if (existing) {
+        existing.ax = ax;
+        existing.axNodeId = ax.nodeId;
+      } else {
+        nodes.set(id, {
+          id,
+          frameId: document.frameId,
+          ...(typeof ax.backendDOMNodeId === "number"
+            ? { backendNodeId: ax.backendDOMNodeId }
+            : {}),
+          axNodeId: ax.nodeId,
+          ax,
+          sourceOrder: document.domNodes.length + index,
+          excluded:
+            document.frameId === rootFrameId &&
+            typeof ax.backendDOMNodeId === "number" &&
+            input.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true,
+        });
+        frameNodeIds.push(id);
+      }
+      nodeByFrameAx.set(frameAxKey(document.frameId, ax.nodeId), id);
+    }
+  }
+
+  for (const document of input.documents) {
+    for (const dom of document.domNodes) {
+      const id = nodeByFrameBackend.get(frameBackendKey(document.frameId, dom.backendNodeId));
+      const node = id ? nodes.get(id) : undefined;
+      if (!node || dom.parentBackendNodeId === null) continue;
+      node.domParentId = nodeByFrameBackend.get(
+        frameBackendKey(document.frameId, dom.parentBackendNodeId),
+      );
+    }
+    for (const ax of document.axNodes) {
+      const id = nodeByFrameAx.get(frameAxKey(document.frameId, ax.nodeId));
+      const node = id ? nodes.get(id) : undefined;
+      if (!node || !ax.parentId) continue;
+      node.axParentId = nodeByFrameAx.get(frameAxKey(document.frameId, ax.parentId));
+    }
+  }
+
+  const axChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
+  const excludedQueue: SemanticNodeId[] = [];
+  for (const node of nodes.values()) {
+    if (node.axParentId) {
+      const children = axChildren.get(node.axParentId) ?? [];
+      children.push(node.id);
+      axChildren.set(node.axParentId, children);
+    }
+    if (node.excluded) excludedQueue.push(node.id);
+  }
+  for (let index = 0; index < excludedQueue.length; index += 1) {
+    for (const childId of axChildren.get(excludedQueue[index]) ?? []) {
+      const child = nodes.get(childId);
+      if (!child || child.excluded) continue;
+      child.excluded = true;
+      excludedQueue.push(childId);
+    }
+  }
+
+  for (const frame of frames.values()) {
+    if (!frame.parentFrameId || frame.ownerBackendNodeId === undefined) continue;
+    frame.ownerNodeId = nodeByFrameBackend.get(
+      frameBackendKey(frame.parentFrameId, frame.ownerBackendNodeId),
+    );
+  }
+
+  return {
+    viewport: input.viewport,
+    rootFrameId,
+    frames,
+    nodes,
+    nodeIdsByFrame,
+    nodeByFrameBackend,
+  };
+}

apps/extension/src/tools/vom/semantic-graph/index.ts

@@ -0,0 +1,59 @@
+import type { Viewport, VomScene } from "@browser-skill/vom";
+import type { FrameDocument } from "../frame-document";
+import { buildSemanticGraph as buildGraph } from "./build";
+import { projectSemanticGraph as projectGraph } from "./project";
+import { resolveSemanticGraph as resolveGraph } from "./resolve";
+import { normalizeSemanticStructure as normalizeStructure } from "./structure";
+import type {
+  ResolvedSemanticGraph,
+  SemanticAxNode,
+  SemanticGraph,
+  StructuredSemanticGraph,
+} from "./types";
+
+export type { SemanticAxNode } from "./types";
+
+export interface SemanticVomInput {
+  documents: FrameDocument<SemanticAxNode>[];
+  viewport: Viewport;
+  rootFrameId?: string;
+  excludedBackendNodeIds?: ReadonlySet<number>;
+}
+
+export function buildSemanticGraph(input: SemanticVomInput): SemanticGraph {
+  return buildGraph(input);
+}
+
+export function resolveSemanticGraph(
+  graph: SemanticGraph,
+  options: {
+    supplementalNames?: ReadonlyMap<string, string>;
+    identifierFallback?: boolean;
+  } = {},
+): ResolvedSemanticGraph {
+  return resolveGraph(graph, options);
+}
+
+export function normalizeSemanticStructure(graph: ResolvedSemanticGraph): StructuredSemanticGraph {
+  return normalizeStructure(graph);
+}
+
+export function projectSemanticGraph(graph: StructuredSemanticGraph): VomScene {
+  return projectGraph(graph);
+}
+
+export function buildSemanticVomScene(
+  input: SemanticVomInput & {
+    supplementalNames?: ReadonlyMap<string, string>;
+    identifierFallback?: boolean;
+  },
+): VomScene {
+  return projectSemanticGraph(
+    normalizeSemanticStructure(
+      resolveSemanticGraph(buildSemanticGraph(input), {
+        supplementalNames: input.supplementalNames,
+        identifierFallback: input.identifierFallback,
+      }),
+    ),
+  );
+}

apps/extension/src/tools/vom/semantic-graph/name-evidence.ts

@@ -0,0 +1,34 @@
+const IDENTIFIER_ATTRS = ["data-testid", "data-test-id", "id"] as const;
+const GENERIC_TOKENS = new Set(["btn", "button", "control", "icon", "item", "test", "tool"]);
+const GENERATED_PREFIXES = new Set(["ember", "headlessui", "mui", "radix", "react", "rc"]);
+
+function identifierTokens(value: string): string[] {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^a-zA-Z0-9]+/)
+    .map((token) => token.toLowerCase())
+    .filter(Boolean);
+}
+
+function readableIdentifier(value: string | undefined): string | undefined {
+  const raw = value?.trim();
+  if (!raw || raw.length < 3 || raw.length > 80) return undefined;
+  if (/^[a-f0-9]{8,}$/i.test(raw)) return undefined;
+
+  const tokens = identifierTokens(raw);
+  if (GENERATED_PREFIXES.has(tokens[0])) return undefined;
+  while (tokens.length > 1 && GENERIC_TOKENS.has(tokens[0])) tokens.shift();
+  while (tokens.length > 1 && GENERIC_TOKENS.has(tokens[tokens.length - 1])) tokens.pop();
+  if (tokens.length === 0 || !tokens.some((token) => /[a-z]{3,}/.test(token))) return undefined;
+  return tokens
+    .map((token, index) => (index === 0 ? `${token[0].toUpperCase()}${token.slice(1)}` : token))
+    .join(" ");
+}
+
+export function stableIdentifierName(attrs: Readonly<Record<string, string>>): string | undefined {
+  for (const name of IDENTIFIER_ATTRS) {
+    const label = readableIdentifier(attrs[name]);
+    if (label) return label;
+  }
+  return undefined;
+}

apps/extension/src/tools/vom/semantic-graph/project.ts

@@ -0,0 +1,85 @@
+import type { VomNode, VomScene } from "@browser-skill/vom";
+import type { SemanticNodeId, StructuredSemanticGraph, StructuredSemanticNode } from "./types";
+
+function retained(node: StructuredSemanticNode): boolean {
+  return node.structure.kind === "keep" || node.structure.kind === "inferred-group";
+}
+
+function connectedFrameIds(graph: StructuredSemanticGraph): Set<string> {
+  const connected = new Set<string>([graph.rootFrameId]);
+  const childrenByParent = new Map<string, string[]>();
+  for (const frame of graph.frames.values()) {
+    if (!frame.parentFrameId) continue;
+    const children = childrenByParent.get(frame.parentFrameId) ?? [];
+    children.push(frame.frameId);
+    childrenByParent.set(frame.parentFrameId, children);
+  }
+  const queue = [graph.rootFrameId];
+  for (let index = 0; index < queue.length; index += 1) {
+    for (const frameId of childrenByParent.get(queue[index]) ?? []) {
+      if (connected.has(frameId)) continue;
+      const frame = graph.frames.get(frameId);
+      if (!frame?.ownerNodeId) continue;
+      const owner = graph.nodes.get(frame.ownerNodeId);
+      if (!owner || !retained(owner)) continue;
+      connected.add(frame.frameId);
+      queue.push(frame.frameId);
+    }
+  }
+  return connected;
+}
+
+function domAncestors(
+  graph: StructuredSemanticGraph,
+  node: StructuredSemanticNode,
+  numericId: ReadonlyMap<SemanticNodeId, number>,
+): number[] {
+  const ancestors: number[] = [];
+  const seen = new Set<SemanticNodeId>();
+  let current = node.domParentId;
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    const id = numericId.get(current);
+    if (id !== undefined) ancestors.push(id);
+    current = graph.nodes.get(current)?.domParentId;
+  }
+  return ancestors;
+}
+
+export function projectSemanticGraph(graph: StructuredSemanticGraph): VomScene {
+  const connectedFrames = connectedFrameIds(graph);
+  const orderedNodes = [...graph.frames.values()]
+    .filter((frame) => connectedFrames.has(frame.frameId))
+    .sort((a, b) => a.order - b.order)
+    .flatMap((frame) =>
+      (graph.nodeIdsByFrame.get(frame.frameId) ?? [])
+        .map((id) => graph.nodes.get(id))
+        .filter((node): node is StructuredSemanticNode => node !== undefined && retained(node))
+        .sort((a, b) => a.sourceOrder - b.sourceOrder),
+    );
+
+  const numericId = new Map<SemanticNodeId, number>();
+  orderedNodes.forEach((node, index) => numericId.set(node.id, index + 1));
+  const nodes: VomNode[] = orderedNodes.map((node) => ({
+    ...node.vom,
+    id: numericId.get(node.id) as number,
+    parentId: node.semanticParentId ? (numericId.get(node.semanticParentId) ?? null) : null,
+    ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
+    frameId: node.frameId,
+    contextScopeId: graph.frames.get(node.frameId)?.contextScopeId ?? node.frameId,
+    referenceable: node.referenceable,
+    ...(node.dom
+      ? {
+          domParentId:
+            node.domParentId === undefined ? null : (numericId.get(node.domParentId) ?? null),
+          domAncestorIds: domAncestors(graph, node, numericId),
+        }
+      : {}),
+  }));
+
+  return {
+    viewport: graph.viewport,
+    nodes,
+    rootFrameId: graph.rootFrameId,
+  };
+}

apps/extension/src/tools/vom/semantic-graph/resolve.ts

@@ -0,0 +1,521 @@
+import type { VomNode } from "@browser-skill/vom";
+import { stableIdentifierName } from "./name-evidence";
+import type {
+  ResolvedSemanticGraph,
+  ResolvedSemanticNode,
+  SemanticAxNode,
+  SemanticGraph,
+  SemanticGraphNode,
+  SemanticNodeId,
+} from "./types";
+import { frameBackendKey } from "./types";
+
+const FORM_TAGS = new Set(["input", "textarea", "select"]);
+const NATIVE_CONTROL_TAGS = new Set(["button", "input", "select", "textarea"]);
+const TEXT_AX_ROLES = new Set(["statictext", "inlinetextbox", "labeltext", "text"]);
+const INTERACTIVE_ROLES = new Set([
+  "button",
+  "checkbox",
+  "combobox",
+  "link",
+  "listbox",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "radio",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "switch",
+  "tab",
+  "textbox",
+  "treeitem",
+]);
+const SENSITIVE_INPUT_TYPES = new Set([
+  "password",
+  "credit-card",
+  "one-time-code",
+  "current-password",
+  "new-password",
+]);
+
+function clean(value: string | undefined): string | undefined {
+  const normalized = value?.replace(/\s+/g, " ").trim();
+  return normalized || undefined;
+}
+
+function axValue(field?: { value?: string | number | boolean }): string | undefined {
+  return field?.value === undefined ? undefined : clean(String(field.value));
+}
+
+function axProperty(node: SemanticAxNode | undefined, name: string): string | undefined {
+  return axValue(node?.properties?.find((property) => property.name === name)?.value);
+}
+
+function normalizeRole(value: string | undefined): string | undefined {
+  const role = clean(value)?.toLowerCase();
+  return role || undefined;
+}
+
+function nativeRole(tag: string, attrs: Record<string, string>): string | undefined {
+  if (tag === "button") return "button";
+  if (tag === "textarea") return "textbox";
+  if (tag === "select") return attrs.multiple === undefined ? "combobox" : "listbox";
+  if (tag === "a" && attrs.href) return "link";
+  if (tag === "iframe") return "Iframe";
+  if (tag === "dialog") return "dialog";
+  if (tag === "img") return "img";
+  if (tag === "table") return "table";
+  if (tag === "tr") return "row";
+  if (tag === "th") return "columnheader";
+  if (tag === "td") return "cell";
+  if (tag === "ul" || tag === "ol") return "list";
+  if (tag === "li") return "listitem";
+  if (/^h[1-6]$/.test(tag)) return "heading";
+  if (tag === "nav") return "navigation";
+  if (tag === "main") return "main";
+  if (tag === "form") return "form";
+  if (tag === "input") {
+    const type = (attrs.type ?? "text").toLowerCase();
+    if (type === "hidden") return undefined;
+    if (type === "checkbox") return "checkbox";
+    if (type === "radio") return "radio";
+    if (type === "range") return "slider";
+    if (type === "number") return "spinbutton";
+    if (type === "search") return "searchbox";
+    if (["button", "submit", "reset", "image"].includes(type)) return "button";
+    return "textbox";
+  }
+  return undefined;
+}
+
+function domRole(tag: string, attrs: Record<string, string>): string | undefined {
+  return normalizeRole(attrs.role) ?? nativeRole(tag, attrs);
+}
+
+function resolvedRole(node: SemanticGraphNode): {
+  value?: string;
+  source: ResolvedSemanticNode["roleSource"];
+} {
+  const rawAxRole = clean(axValue(node.ax?.role));
+  const axRole = normalizeRole(rawAxRole);
+  const attrs = node.dom?.attrs ?? {};
+  const explicitDomRole = normalizeRole(attrs.role);
+  const nativeDomRole = nativeRole(node.dom?.tag.toLowerCase() ?? "", attrs);
+  const usableAxRole = node.ax?.ignored !== true;
+  if (usableAxRole && axRole && !["generic", "none", "presentation"].includes(axRole)) {
+    return { value: rawAxRole, source: "ax" };
+  }
+  if (explicitDomRole) return { value: explicitDomRole, source: "dom-explicit" };
+  if (nativeDomRole) return { value: nativeDomRole, source: "dom-native" };
+  if (rawAxRole) {
+    return { value: rawAxRole, source: usableAxRole ? "ax" : "ax-ignored" };
+  }
+  return { source: "none" };
+}
+
+function sensitive(node: SemanticGraphNode): boolean {
+  const attrs = node.dom?.attrs ?? {};
+  const type = (attrs.type ?? "").toLowerCase();
+  const autocomplete = (attrs.autocomplete ?? "").toLowerCase();
+  return (
+    type === "password" ||
+    autocomplete.startsWith("cc-") ||
+    SENSITIVE_INPUT_TYPES.has(autocomplete) ||
+    SENSITIVE_INPUT_TYPES.has(axProperty(node.ax, "inputType") ?? "")
+  );
+}
+
+function inputState(
+  node: SemanticGraphNode,
+  role: string | undefined,
+  value: string | undefined,
+  isSensitive: boolean,
+): VomNode["inputState"] {
+  if (node.dom?.formState) return node.dom.formState;
+  const tag = node.dom?.tag.toLowerCase() ?? "";
+  if (!FORM_TAGS.has(tag) && !["textbox", "searchbox"].includes(role ?? "")) return undefined;
+  if (isSensitive) return value ? "filled" : "empty";
+  if (node.dom?.formValue !== undefined) {
+    if (node.dom.formValue === "") return "empty";
+    return node.dom.formValue === (node.dom.formDefaultValue ?? "") ? "default" : "filled";
+  }
+  return value ? "filled" : "empty";
+}
+
+function externalHrefHost(
+  href: string | undefined,
+  pageUrl: string | undefined,
+): string | undefined {
+  if (!href || !pageUrl) return undefined;
+  try {
+    const page = new URL(pageUrl);
+    const target = new URL(href, page);
+    return target.origin === page.origin ? undefined : target.hostname;
+  } catch {
+    return undefined;
+  }
+}
+
+interface ResolveIndexes {
+  domChildren: Map<SemanticNodeId, SemanticNodeId[]>;
+  axChildren: Map<SemanticNodeId, SemanticNodeId[]>;
+  domIdIndex: Map<string, SemanticNodeId>;
+  labelForIndex: Map<string, SemanticNodeId[]>;
+  domText: (nodeId: SemanticNodeId) => string | undefined;
+  axText: (nodeId: SemanticNodeId) => string | undefined;
+  hasNativeDescendant: (nodeId: SemanticNodeId) => boolean;
+}
+
+function buildIndexes(graph: SemanticGraph): ResolveIndexes {
+  const domChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
+  const axChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
+  const domIdIndex = new Map<string, SemanticNodeId>();
+  const labelForIndex = new Map<string, SemanticNodeId[]>();
+  for (const node of graph.nodes.values()) {
+    if (node.domParentId) {
+      const children = domChildren.get(node.domParentId) ?? [];
+      children.push(node.id);
+      domChildren.set(node.domParentId, children);
+    }
+    if (node.axParentId) {
+      const children = axChildren.get(node.axParentId) ?? [];
+      children.push(node.id);
+      axChildren.set(node.axParentId, children);
+    }
+    const id = clean(node.dom?.attrs.id);
+    if (id) domIdIndex.set(`${node.frameId}\u0000${id}`, node.id);
+    const targetId = clean(node.dom?.attrs.for);
+    if (node.dom?.tag.toLowerCase() === "label" && targetId) {
+      const key = `${node.frameId}\u0000${targetId}`;
+      const labels = labelForIndex.get(key) ?? [];
+      labels.push(node.id);
+      labelForIndex.set(key, labels);
+    }
+  }
+
+  for (const [parentId, children] of axChildren) {
+    const order = graph.nodes.get(parentId)?.ax?.childIds ?? [];
+    const orderByAxId = new Map(order.map((nodeId, index) => [nodeId, index]));
+    children.sort((a, b) => {
+      const aIndex = orderByAxId.get(graph.nodes.get(a)?.axNodeId ?? "") ?? -1;
+      const bIndex = orderByAxId.get(graph.nodes.get(b)?.axNodeId ?? "") ?? -1;
+      return (
+        (aIndex < 0 ? Number.MAX_SAFE_INTEGER : aIndex) -
+        (bIndex < 0 ? Number.MAX_SAFE_INTEGER : bIndex)
+      );
+    });
+  }
+
+  const textMemo = new Map<SemanticNodeId, string | undefined>();
+  const resolvingText = new Set<SemanticNodeId>();
+  const domText = (nodeId: SemanticNodeId): string | undefined => {
+    if (textMemo.has(nodeId)) return textMemo.get(nodeId);
+    if (resolvingText.has(nodeId)) return undefined;
+    resolvingText.add(nodeId);
+    const node = graph.nodes.get(nodeId);
+    const parts: string[] = [];
+    const own = clean(node?.dom?.textContent);
+    if (own) parts.push(own);
+    for (const childId of domChildren.get(nodeId) ?? []) {
+      const child = graph.nodes.get(childId);
+      const childRole = child
+        ? domRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {})
+        : undefined;
+      if (childRole && INTERACTIVE_ROLES.has(childRole.toLowerCase())) continue;
+      const childText = domText(childId);
+      if (childText) parts.push(childText);
+      if (parts.join(" ").length >= 240) break;
+    }
+    resolvingText.delete(nodeId);
+    const result = clean(parts.join(" ").slice(0, 240));
+    textMemo.set(nodeId, result);
+    return result;
+  };
+
+  const axTextMemo = new Map<SemanticNodeId, string | undefined>();
+  const resolvingAxText = new Set<SemanticNodeId>();
+  const axText = (nodeId: SemanticNodeId): string | undefined => {
+    if (axTextMemo.has(nodeId)) return axTextMemo.get(nodeId);
+    if (resolvingAxText.has(nodeId)) return undefined;
+    resolvingAxText.add(nodeId);
+    const complete = (value: string | undefined): string | undefined => {
+      resolvingAxText.delete(nodeId);
+      axTextMemo.set(nodeId, value);
+      return value;
+    };
+    const node = graph.nodes.get(nodeId);
+    const role = normalizeRole(axValue(node?.ax?.role)) ?? "";
+    if (TEXT_AX_ROLES.has(role)) {
+      const own = clean(axValue(node?.ax?.name) ?? axValue(node?.ax?.value));
+      if (own) return complete(own);
+    }
+    const parts: string[] = [];
+    for (const childId of axChildren.get(nodeId) ?? []) {
+      const child = graph.nodes.get(childId);
+      const childRole = normalizeRole(axValue(child?.ax?.role)) ?? "";
+      if (INTERACTIVE_ROLES.has(childRole)) continue;
+      const childText = axText(childId);
+      if (childText) parts.push(childText);
+      if (parts.join(" ").length >= 240) break;
+    }
+    return complete(clean(parts.join(" ").slice(0, 240)));
+  };
+
+  const nativeMemo = new Map<SemanticNodeId, boolean>();
+  const hasNativeDescendant = (nodeId: SemanticNodeId): boolean => {
+    const cached = nativeMemo.get(nodeId);
+    if (cached !== undefined) return cached;
+    nativeMemo.set(nodeId, false);
+    for (const childId of domChildren.get(nodeId) ?? []) {
+      const child = graph.nodes.get(childId);
+      const childRole =
+        (child?.ax?.ignored === true ? undefined : normalizeRole(axValue(child?.ax?.role))) ??
+        (child ? domRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {}) : undefined);
+      if (
+        (child?.dom && NATIVE_CONTROL_TAGS.has(child.dom.tag.toLowerCase())) ||
+        INTERACTIVE_ROLES.has(childRole ?? "") ||
+        hasNativeDescendant(childId)
+      ) {
+        nativeMemo.set(nodeId, true);
+        return true;
+      }
+    }
+    return false;
+  };
+
+  return {
+    domChildren,
+    axChildren,
+    domIdIndex,
+    labelForIndex,
+    domText,
+    axText,
+    hasNativeDescendant,
+  };
+}
+
+function ariaLabelledText(node: SemanticGraphNode, indexes: ResolveIndexes): string | undefined {
+  const ids = (node.dom?.attrs["aria-labelledby"] ?? "").split(/\s+/).filter(Boolean);
+  const parts = ids.flatMap((id) => {
+    const target = indexes.domIdIndex.get(`${node.frameId}\u0000${id}`);
+    return target ? (indexes.domText(target) ?? []) : [];
+  });
+  return clean(parts.join(" "));
+}
+
+function nativeLabelText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  const id = clean(node.dom?.attrs.id);
+  if (id) {
+    const labels = indexes.labelForIndex.get(`${node.frameId}\u0000${id}`) ?? [];
+    const explicit = clean(
+      labels
+        .map((labelId) => indexes.domText(labelId))
+        .filter(Boolean)
+        .join(" "),
+    );
+    if (explicit) return explicit;
+  }
+  let parentId = node.domParentId;
+  let guard = 0;
+  while (parentId && guard <= graph.nodes.size) {
+    const parent = graph.nodes.get(parentId);
+    if (!parent) break;
+    if (parent.dom?.tag.toLowerCase() === "label") return indexes.domText(parentId);
+    parentId = parent.domParentId;
+    guard += 1;
+  }
+  return undefined;
+}
+
+function precedingAxText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  if (!node.axParentId) return undefined;
+  const siblings = indexes.axChildren.get(node.axParentId) ?? [];
+  const index = siblings.indexOf(node.id);
+  for (let offset = 1; offset <= 4 && index - offset >= 0; offset += 1) {
+    const sibling = graph.nodes.get(siblings[index - offset]);
+    const role = normalizeRole(axValue(sibling?.ax?.role)) ?? "";
+    if (INTERACTIVE_ROLES.has(role)) break;
+    if (!TEXT_AX_ROLES.has(role) && role !== "generic") continue;
+    const text = clean(axValue(sibling?.ax?.name) ?? axValue(sibling?.ax?.value))?.replace(
+      /[：:]\s*$/,
+      "",
+    );
+    if (text && text.length <= 80) return text;
+  }
+  return undefined;
+}
+
+function precedingDomText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  if (!node.domParentId) return undefined;
+  const siblings = indexes.domChildren.get(node.domParentId) ?? [];
+  const index = siblings.indexOf(node.id);
+  for (let offset = 1; offset <= 4 && index - offset >= 0; offset += 1) {
+    const sibling = graph.nodes.get(siblings[index - offset]);
+    const siblingRole = sibling
+      ? domRole(sibling.dom?.tag.toLowerCase() ?? "", sibling.dom?.attrs ?? {})
+      : undefined;
+    if (siblingRole && INTERACTIVE_ROLES.has(siblingRole.toLowerCase())) break;
+    const text = indexes.domText(siblings[index - offset])?.replace(/[：:]\s*$/, "");
+    if (text && text.length <= 80) return text;
+  }
+  return undefined;
+}
+
+function resolvedName(
+  node: SemanticGraphNode,
+  role: string | undefined,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+  supplementalNames: ReadonlyMap<string, string>,
+  identifierFallback: boolean,
+): string | undefined {
+  const attrs = node.dom?.attrs ?? {};
+  const formControl = FORM_TAGS.has(node.dom?.tag.toLowerCase() ?? "");
+  const descendantText = indexes.domText(node.id);
+  const interactive =
+    INTERACTIVE_ROLES.has(role?.toLowerCase() ?? "") ||
+    NATIVE_CONTROL_TAGS.has(node.dom?.tag.toLowerCase() ?? "");
+  const candidates = [
+    node.ax?.ignored === true ? undefined : axValue(node.ax?.name),
+    ariaLabelledText(node, indexes),
+    clean(attrs["aria-label"]),
+    nativeLabelText(node, graph, indexes),
+    clean(attrs.title),
+    clean(attrs.alt),
+    node.ax?.ignored === true ? undefined : indexes.axText(node.id),
+    descendantText,
+    formControl ? precedingAxText(node, graph, indexes) : undefined,
+    formControl ? precedingDomText(node, graph, indexes) : undefined,
+    formControl ? clean(node.dom?.formPlaceholder ?? attrs.placeholder) : undefined,
+    formControl || !interactive || node.backendNodeId === undefined
+      ? undefined
+      : clean(supplementalNames.get(frameBackendKey(node.frameId, node.backendNodeId))),
+    identifierFallback && interactive ? stableIdentifierName(attrs) : undefined,
+  ];
+  let name = candidates.find((candidate) => candidate !== undefined);
+  const hasPopup = axProperty(node.ax, "hasPopup");
+  if (name && hasPopup && hasPopup !== "false") {
+    name =
+      axProperty(node.ax, "expanded") === "true" ? `${name} [expanded]` : `${name} [has-submenu]`;
+  }
+  if (!name && role?.toLowerCase() === "iframe") return clean(attrs.id);
+  return name;
+}
+
+function insideNative(node: SemanticGraphNode, graph: SemanticGraph): boolean {
+  let parentId = node.domParentId;
+  let guard = 0;
+  while (parentId && guard <= graph.nodes.size) {
+    const parent = graph.nodes.get(parentId);
+    if (!parent) break;
+    if (parent.dom && NATIVE_CONTROL_TAGS.has(parent.dom.tag.toLowerCase())) return true;
+    parentId = parent.domParentId;
+    guard += 1;
+  }
+  return false;
+}
+
+function nearbyText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  if (!node.domParentId) return undefined;
+  const siblings = indexes.domChildren.get(node.domParentId) ?? [];
+  const index = siblings.indexOf(node.id);
+  if (index < 0) return undefined;
+  const texts = siblings
+    .slice(Math.max(0, index - 3), index + 4)
+    .filter((id) => id !== node.id)
+    .flatMap((id) => indexes.domText(id) ?? [])
+    .slice(0, 3);
+  return clean(texts.join(" "));
+}
+
+export function resolveSemanticGraph(
+  graph: SemanticGraph,
+  options: {
+    supplementalNames?: ReadonlyMap<string, string>;
+    identifierFallback?: boolean;
+  } = {},
+): ResolvedSemanticGraph {
+  const indexes = buildIndexes(graph);
+  const supplementalNames = options.supplementalNames ?? new Map<string, string>();
+  const identifierFallback = options.identifierFallback ?? true;
+  const nodes = new Map<SemanticNodeId, ResolvedSemanticNode>();
+  for (const node of graph.nodes.values()) {
+    const roleResolution = resolvedRole(node);
+    const role = roleResolution.value;
+    const name = resolvedName(node, role, graph, indexes, supplementalNames, identifierFallback);
+    const isSensitive = sensitive(node);
+    const sourceValue = node.dom?.formValue ?? axValue(node.ax?.value);
+    const value = isSensitive ? undefined : sourceValue;
+    const attrs = { ...(node.dom?.attrs ?? {}) };
+    if (isSensitive) delete attrs.value;
+    const frame = graph.frames.get(node.frameId);
+    const tag = node.dom?.tag.toLowerCase() ?? "";
+    const vom: ResolvedSemanticNode["vom"] = {
+      tag,
+      rect: node.dom?.rect ?? null,
+      paintOrder: node.dom?.paintOrder ?? 0,
+      position: node.dom?.position || "static",
+      pointerEvents: node.dom?.pointerEvents || "auto",
+      ...(node.dom?.cursor ? { cursor: node.dom.cursor } : {}),
+      ...(role ? { role } : {}),
+      ...(name ? { name } : {}),
+      ...(value !== undefined ? { value } : {}),
+      ...(clean(node.dom?.formPlaceholder ?? attrs.placeholder)
+        ? { placeholder: clean(node.dom?.formPlaceholder ?? attrs.placeholder) }
+        : {}),
+      attrs,
+      ...(clean(node.dom?.textContent) ? { text: clean(node.dom?.textContent) } : {}),
+      ...(nearbyText(node, graph, indexes) ? { nearbyText: nearbyText(node, graph, indexes) } : {}),
+      inputState: inputState(node, role, sourceValue, isSensitive),
+      sensitive: isSensitive,
+      modal:
+        ["dialog", "alertdialog"].includes(role?.toLowerCase() ?? "") ||
+        tag === "dialog" ||
+        (attrs["aria-modal"] ?? "").toLowerCase() === "true",
+      disabled:
+        Object.prototype.hasOwnProperty.call(attrs, "disabled") ||
+        (attrs["aria-disabled"] ?? "").toLowerCase() === "true",
+      inert: Object.prototype.hasOwnProperty.call(attrs, "inert"),
+      hasNativeDescendant: indexes.hasNativeDescendant(node.id),
+      insideNative: insideNative(node, graph),
+      ...(role?.toLowerCase() === "link" ? { href: externalHrefHost(attrs.href, frame?.url) } : {}),
+    };
+    const selected = node.ax?.ignored === true ? undefined : axProperty(node.ax, "selected");
+    const expanded = node.ax?.ignored === true ? undefined : axProperty(node.ax, "expanded");
+    const controls = node.ax?.ignored === true ? undefined : axProperty(node.ax, "controls");
+    if (selected === "true" && !vom.attrs?.["aria-selected"]) {
+      vom.attrs = { ...(vom.attrs ?? {}), "aria-selected": "true" };
+    }
+    if (expanded === "true" && !vom.attrs?.["aria-expanded"]) {
+      vom.attrs = { ...(vom.attrs ?? {}), "aria-expanded": "true" };
+    }
+    if (controls && !vom.attrs?.["aria-controls"]) {
+      vom.attrs = { ...(vom.attrs ?? {}), "aria-controls": controls };
+    }
+    nodes.set(node.id, {
+      ...node,
+      vom,
+      referenceable: node.backendNodeId !== undefined,
+      roleSource: roleResolution.source,
+    });
+  }
+  return { ...graph, nodes };
+}

apps/extension/src/tools/vom/semantic-graph/structure.ts

@@ -0,0 +1,456 @@
+import {
+  applyVomInteractionRecovery,
+  isVomReferenceNode,
+  isVomStructuralRole,
+  type VomNode,
+} from "@browser-skill/vom";
+import type {
+  ResolvedSemanticGraph,
+  ResolvedSemanticNode,
+  SemanticNodeId,
+  StructureDecision,
+  StructuredSemanticGraph,
+  StructuredSemanticNode,
+} from "./types";
+
+const TRANSPARENT_ROLES = new Set(["", "generic", "none", "presentation", "inlinetextbox"]);
+const ROOT_ROLES = new Set(["rootwebarea", "webarea"]);
+const CONTENT_BOUNDARY_ROLES = new Set([
+  "article",
+  "dialog",
+  "document",
+  "feed",
+  "form",
+  "grid",
+  "heading",
+  "iframe",
+  "list",
+  "main",
+  "navigation",
+  "paragraph",
+  "region",
+  "section",
+  "table",
+  "tree",
+]);
+
+function hasMeaningfulRelations(node: ResolvedSemanticNode): boolean {
+  const attrs = node.vom.attrs ?? {};
+  return ["aria-controls", "aria-labelledby", "aria-owns", "aria-describedby"].some((name) =>
+    attrs[name]?.trim(),
+  );
+}
+
+function explicitStructural(node: ResolvedSemanticNode): boolean {
+  return (
+    isVomStructuralRole(node.vom.role) &&
+    node.roleSource !== "none" &&
+    node.roleSource !== "ax-ignored"
+  );
+}
+
+function hasUsableAxSemantics(node: ResolvedSemanticNode): boolean {
+  return node.ax !== undefined && node.ax.ignored !== true;
+}
+
+function isRenderedDomFallback(node: ResolvedSemanticNode): boolean {
+  if (!node.dom) return false;
+  const attrs = node.dom.attrs;
+  if (
+    Object.prototype.hasOwnProperty.call(attrs, "hidden") ||
+    Object.prototype.hasOwnProperty.call(attrs, "inert") ||
+    (attrs["aria-hidden"] ?? "").toLowerCase() === "true"
+  ) {
+    return false;
+  }
+  return node.dom.rendered ?? (node.dom.localRect != null || node.dom.rect != null);
+}
+
+function initialParentId(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+): SemanticNodeId | undefined {
+  let parentId = node.axParentId ?? node.domParentId;
+  if (node.axParentId && node.domParentId && node.axParentId !== node.domParentId) {
+    const axParent = graph.nodes.get(node.axParentId);
+    const axRole = axParent?.vom.role?.toLowerCase() ?? "";
+    const meaningfulAxParent =
+      axParent !== undefined &&
+      !ROOT_ROLES.has(axRole) &&
+      (explicitStructural(axParent) ||
+        !TRANSPARENT_ROLES.has(axRole) ||
+        Boolean(axParent.vom.name || axParent.vom.text || hasMeaningfulRelations(axParent)));
+    parentId = meaningfulAxParent ? node.axParentId : node.domParentId;
+  }
+  if (parentId) return parentId;
+  if (node.frameId === graph.rootFrameId) return undefined;
+  return graph.frames.get(node.frameId)?.ownerNodeId;
+}
+
+function orderedNodes(graph: ResolvedSemanticGraph): ResolvedSemanticNode[] {
+  return [...graph.frames.values()]
+    .sort((a, b) => a.order - b.order)
+    .flatMap((frame) =>
+      (graph.nodeIdsByFrame.get(frame.frameId) ?? [])
+        .map((id) => graph.nodes.get(id))
+        .filter((node): node is ResolvedSemanticNode => node !== undefined)
+        .sort((a, b) => a.sourceOrder - b.sourceOrder),
+    );
+}
+
+function recoveredNodes(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+): Map<SemanticNodeId, VomNode> {
+  const numericId = new Map(nodes.map((node, index) => [node.id, index + 1]));
+  const semanticId = new Map([...numericId].map(([id, numeric]) => [numeric, id]));
+  const provisional = nodes.map((node) => ({
+    ...node.vom,
+    id: numericId.get(node.id) as number,
+    parentId: (() => {
+      const parent = initialParentId(graph, node);
+      return parent ? (numericId.get(parent) ?? null) : null;
+    })(),
+    ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
+    frameId: node.frameId,
+    contextScopeId: graph.frames.get(node.frameId)?.contextScopeId ?? node.frameId,
+    referenceable: node.referenceable,
+  }));
+  return new Map(
+    applyVomInteractionRecovery(provisional).flatMap((node) => {
+      const id = semanticId.get(node.id);
+      return id ? [[id, node] as const] : [];
+    }),
+  );
+}
+
+function redundantSourceNodes(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+  recovered: ReadonlyMap<SemanticNodeId, VomNode>,
+): Set<SemanticNodeId> {
+  const byKey = new Map<string, ResolvedSemanticNode[]>();
+  for (const node of nodes) {
+    const output = recovered.get(node.id) as VomNode;
+    const name = output.name?.trim().toLowerCase() ?? "";
+    if (!name || !isVomReferenceNode({ ...output, referenceable: true })) continue;
+    const key = `${node.frameId}\u0000${initialParentId(graph, node) ?? ""}\u0000${output.role?.toLowerCase() ?? ""}\u0000${name}\u0000${output.sensitive === true}`;
+    const matches = byKey.get(key) ?? [];
+    matches.push(node);
+    byKey.set(key, matches);
+  }
+  const redundant = new Set<SemanticNodeId>();
+  for (const matches of byKey.values()) {
+    const axOnly = matches.filter((node) => node.ax && !node.dom);
+    const domOnly = matches.filter((node) => node.dom && !node.ax);
+    if (matches.length === 2 && axOnly.length === 1 && domOnly.length === 1) {
+      redundant.add(domOnly[0].id);
+    }
+  }
+  return redundant;
+}
+
+function baseDecision(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+  output: VomNode,
+  frameOwnerIds: ReadonlySet<SemanticNodeId>,
+  redundant: ReadonlySet<SemanticNodeId>,
+): StructureDecision {
+  if (node.excluded) return { kind: "excluded", reason: "excluded" };
+  if (redundant.has(node.id)) return { kind: "excluded", reason: "redundant-source" };
+  if (!hasUsableAxSemantics(node) && !isRenderedDomFallback(node)) {
+    return { kind: "excluded", reason: "non-rendered-dom-fallback" };
+  }
+  if (frameOwnerIds.has(node.id)) return { kind: "keep", reason: "frame-owner" };
+  if (node.frameId !== graph.rootFrameId && ROOT_ROLES.has(output.role?.toLowerCase() ?? "")) {
+    return { kind: "transparent", reason: "child-document-root" };
+  }
+  if (node.ax?.ignored === true && !node.dom) {
+    return { kind: "transparent", reason: "ax-ignored" };
+  }
+  const role = output.role?.toLowerCase() ?? "";
+  if (!TRANSPARENT_ROLES.has(role)) return { kind: "keep", reason: "semantic" };
+  if (
+    output.name ||
+    output.text ||
+    output.value ||
+    output.placeholder ||
+    hasMeaningfulRelations(node) ||
+    (output.rect && ["fixed", "sticky"].includes(output.position))
+  ) {
+    return { kind: "keep", reason: "semantic" };
+  }
+  return { kind: "transparent", reason: "wrapper" };
+}
+
+function buildChildren(
+  nodes: ResolvedSemanticNode[],
+  relation: "axParentId" | "domParentId",
+): Map<SemanticNodeId, SemanticNodeId[]> {
+  const children = new Map<SemanticNodeId, SemanticNodeId[]>();
+  for (const node of nodes) {
+    const parentId = node[relation];
+    if (!parentId) continue;
+    const siblings = children.get(parentId) ?? [];
+    siblings.push(node.id);
+    children.set(parentId, siblings);
+  }
+  return children;
+}
+
+function explicitDomAncestors(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
+): Set<SemanticNodeId> {
+  const inside = new Set<SemanticNodeId>();
+  const roots = nodes.filter((node) => !node.domParentId);
+  const queue = roots.map((node) => node.id);
+  for (let index = 0; index < queue.length; index += 1) {
+    const parentId = queue[index];
+    const parent = graph.nodes.get(parentId);
+    const parentIsBoundary =
+      parent !== undefined &&
+      explicitStructural(parent) &&
+      !ROOT_ROLES.has(parent.vom.role?.toLowerCase() ?? "");
+    for (const childId of domChildren.get(parentId) ?? []) {
+      if (inside.has(parentId) || parentIsBoundary) inside.add(childId);
+      queue.push(childId);
+    }
+  }
+  return inside;
+}
+
+function reliableGroupCandidates(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+  recovered: ReadonlyMap<SemanticNodeId, VomNode>,
+  decisions: ReadonlyMap<SemanticNodeId, StructureDecision>,
+  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
+): Set<SemanticNodeId> {
+  const insideExplicitStructure = explicitDomAncestors(graph, nodes, domChildren);
+  const remainingChildren = new Map(
+    nodes.map((node) => [node.id, domChildren.get(node.id)?.length ?? 0]),
+  );
+  const summaries = new Map<SemanticNodeId, { blocked: boolean; interactions: number }>();
+  const queue = nodes
+    .filter((node) => (remainingChildren.get(node.id) ?? 0) === 0)
+    .map((node) => node.id);
+  for (let index = 0; index < queue.length; index += 1) {
+    const nodeId = queue[index];
+    const node = graph.nodes.get(nodeId);
+    const output = recovered.get(nodeId);
+    if (!node || !output) continue;
+    const role = output.role?.toLowerCase() ?? "";
+    const excluded = decisions.get(nodeId)?.kind === "excluded";
+    const blocked = excluded || explicitStructural(node) || CONTENT_BOUNDARY_ROLES.has(role);
+    const summary = excluded
+      ? { blocked: true, interactions: 0 }
+      : isVomReferenceNode(output)
+        ? { blocked: false, interactions: 1 }
+        : blocked
+          ? { blocked: true, interactions: 0 }
+          : (domChildren.get(nodeId) ?? []).reduce(
+              (combined, childId) => {
+                const child = summaries.get(childId);
+                return {
+                  blocked: combined.blocked || !child || child.blocked,
+                  interactions: Math.min(2, combined.interactions + (child?.interactions ?? 0)),
+                };
+              },
+              { blocked: false, interactions: 0 },
+            );
+    summaries.set(nodeId, summary);
+    const parentId = node.domParentId;
+    if (!parentId) continue;
+    const remaining = (remainingChildren.get(parentId) ?? 1) - 1;
+    remainingChildren.set(parentId, remaining);
+    if (remaining === 0) queue.push(parentId);
+  }
+
+  const candidates = new Set<SemanticNodeId>();
+  for (const node of nodes) {
+    const output = recovered.get(node.id) as VomNode;
+    const role = output.role?.toLowerCase() ?? "";
+    if (
+      !node.dom ||
+      node.dom.tag.toLowerCase() !== "div" ||
+      !TRANSPARENT_ROLES.has(role) ||
+      insideExplicitStructure.has(node.id) ||
+      decisions.get(node.id)?.kind === "excluded" ||
+      node.dom.attrs.hidden !== undefined ||
+      (node.dom.attrs["aria-hidden"] ?? "").toLowerCase() === "true" ||
+      node.dom.attrs.inert !== undefined
+    ) {
+      continue;
+    }
+
+    const branches = (domChildren.get(node.id) ?? []).map((id) => summaries.get(id));
+    const blocked = branches.some((summary) => !summary || summary.blocked);
+    const contributingBranches = branches.filter(
+      (summary) => (summary?.interactions ?? 0) > 0,
+    ).length;
+    const interactions = branches.reduce(
+      (count, summary) => Math.min(2, count + (summary?.interactions ?? 0)),
+      0,
+    );
+    if (!blocked && contributingBranches >= 2 && interactions >= 2) {
+      candidates.add(node.id);
+    }
+  }
+  return candidates;
+}
+
+function leafCandidates(
+  nodes: ResolvedSemanticNode[],
+  candidates: ReadonlySet<SemanticNodeId>,
+  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
+): Set<SemanticNodeId> {
+  const parentById = new Map(
+    nodes.flatMap((node) => (node.domParentId ? ([[node.id, node.domParentId]] as const) : [])),
+  );
+  const childCount = new Map(nodes.map((node) => [node.id, domChildren.get(node.id)?.length ?? 0]));
+  const containsCandidate = new Set<SemanticNodeId>();
+  const queue = nodes.filter((node) => (childCount.get(node.id) ?? 0) === 0).map((node) => node.id);
+  const selected = new Set<SemanticNodeId>();
+  for (let index = 0; index < queue.length; index += 1) {
+    const nodeId = queue[index];
+    if (candidates.has(nodeId) && !containsCandidate.has(nodeId)) selected.add(nodeId);
+    const parentId = parentById.get(nodeId);
+    if (!parentId) continue;
+    if (candidates.has(nodeId) || containsCandidate.has(nodeId)) containsCandidate.add(parentId);
+    const remaining = (childCount.get(parentId) ?? 1) - 1;
+    childCount.set(parentId, remaining);
+    if (remaining === 0) queue.push(parentId);
+  }
+  return selected;
+}
+
+function nearestKept(
+  graph: ResolvedSemanticGraph,
+  startId: SemanticNodeId | undefined,
+  relation: "axParentId" | "domParentId",
+  kept: ReadonlySet<SemanticNodeId>,
+  memo: Map<SemanticNodeId, SemanticNodeId | undefined>,
+): SemanticNodeId | undefined {
+  let currentId = startId;
+  const path: SemanticNodeId[] = [];
+  const seen = new Set<SemanticNodeId>();
+  let result: SemanticNodeId | undefined;
+  while (currentId && !seen.has(currentId)) {
+    if (kept.has(currentId)) {
+      result = currentId;
+      break;
+    }
+    if (memo.has(currentId)) {
+      result = memo.get(currentId);
+      break;
+    }
+    seen.add(currentId);
+    path.push(currentId);
+    currentId = graph.nodes.get(currentId)?.[relation];
+  }
+  for (const id of path) memo.set(id, result);
+  return result;
+}
+
+function finalParentId(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+  kept: ReadonlySet<SemanticNodeId>,
+  decisions: ReadonlyMap<SemanticNodeId, StructureDecision>,
+  axParentMemo: Map<SemanticNodeId, SemanticNodeId | undefined>,
+  domParentMemo: Map<SemanticNodeId, SemanticNodeId | undefined>,
+): SemanticNodeId | undefined {
+  const axParent = nearestKept(graph, node.axParentId, "axParentId", kept, axParentMemo);
+  const domParent = nearestKept(graph, node.domParentId, "domParentId", kept, domParentMemo);
+  const axNode = axParent ? graph.nodes.get(axParent) : undefined;
+  const domNode = domParent ? graph.nodes.get(domParent) : undefined;
+  const axIsRoot = ROOT_ROLES.has(axNode?.vom.role?.toLowerCase() ?? "");
+  const axIsExplicit = axNode ? explicitStructural(axNode) && !axIsRoot : false;
+  const domIsStructural =
+    domNode !== undefined &&
+    (explicitStructural(domNode) || decisions.get(domNode.id)?.kind === "inferred-group");
+  if (axIsExplicit) return axParent;
+  if (domIsStructural) return domParent;
+  if (axParent && !axIsRoot) return axParent;
+  if (domParent) return domParent;
+  if (axParent) return axParent;
+  if (node.frameId === graph.rootFrameId) return undefined;
+  return graph.frames.get(node.frameId)?.ownerNodeId;
+}
+
+function recoveredVom(node: VomNode, inferredGroup: boolean): ResolvedSemanticNode["vom"] {
+  const {
+    id: _id,
+    parentId: _parentId,
+    backendNodeId: _backendNodeId,
+    frameId: _frameId,
+    contextScopeId: _contextScopeId,
+    referenceable: _referenceable,
+    ...vom
+  } = node;
+  if (!inferredGroup) return vom;
+  const { name: _name, text: _text, nearbyText: _nearbyText, ...groupVom } = vom;
+  return { ...groupVom, role: "group" };
+}
+
+export function normalizeSemanticStructure(graph: ResolvedSemanticGraph): StructuredSemanticGraph {
+  const nodes = orderedNodes(graph);
+  const recovered = recoveredNodes(graph, nodes);
+  const redundant = redundantSourceNodes(graph, nodes, recovered);
+  const frameOwnerIds = new Set(
+    [...graph.frames.values()].flatMap((frame) => frame.ownerNodeId ?? []),
+  );
+  const decisions = new Map<SemanticNodeId, StructureDecision>();
+  for (const node of nodes) {
+    decisions.set(
+      node.id,
+      baseDecision(graph, node, recovered.get(node.id) as VomNode, frameOwnerIds, redundant),
+    );
+  }
+
+  const domChildren = buildChildren(nodes, "domParentId");
+  const candidates = reliableGroupCandidates(graph, nodes, recovered, decisions, domChildren);
+  for (const nodeId of leafCandidates(nodes, candidates, domChildren)) {
+    decisions.set(nodeId, {
+      kind: "inferred-group",
+      reason: "independent-interaction-branches",
+    });
+  }
+
+  const kept = new Set(
+    nodes
+      .filter((node) => {
+        const kind = decisions.get(node.id)?.kind;
+        return kind === "keep" || kind === "inferred-group";
+      })
+      .map((node) => node.id),
+  );
+  const axParentMemo = new Map<SemanticNodeId, SemanticNodeId | undefined>();
+  const domParentMemo = new Map<SemanticNodeId, SemanticNodeId | undefined>();
+  const structuredNodes = new Map<SemanticNodeId, StructuredSemanticNode>();
+  for (const node of nodes) {
+    const structure = decisions.get(node.id) as StructureDecision;
+    const inferredGroup = structure.kind === "inferred-group";
+    structuredNodes.set(node.id, {
+      ...node,
+      vom: recoveredVom(recovered.get(node.id) as VomNode, inferredGroup),
+      structure,
+      ...(kept.has(node.id)
+        ? {
+            semanticParentId: finalParentId(
+              graph,
+              node,
+              kept,
+              decisions,
+              axParentMemo,
+              domParentMemo,
+            ),
+          }
+        : {}),
+    });
+  }
+  return { ...graph, nodes: structuredNodes };
+}

apps/extension/src/tools/vom/semantic-graph/types.ts

@@ -0,0 +1,88 @@
+import type { Viewport, VomNode } from "@browser-skill/vom";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import type { CapturedNode } from "../capture";
+
+export interface SemanticAxNode {
+  nodeId: string;
+  frameId?: string;
+  parentId?: string;
+  backendDOMNodeId?: number;
+  ignored?: boolean;
+  role?: { type: string; value?: string };
+  name?: { type: string; value?: string };
+  description?: { value?: string };
+  value?: { value?: string | number | boolean };
+  properties?: Array<{ name?: string; value?: { value?: string | number | boolean } }>;
+  childIds?: string[];
+}
+
+export type SemanticNodeId = string;
+
+export interface SemanticFrame {
+  frameId: string;
+  parentFrameId?: string;
+  ownerBackendNodeId?: number;
+  ownerNodeId?: SemanticNodeId;
+  contextScopeId: string;
+  target: CdpTarget;
+  url?: string;
+  order: number;
+}
+
+export interface SemanticGraphNode {
+  id: SemanticNodeId;
+  frameId: string;
+  backendNodeId?: number;
+  axNodeId?: string;
+  ax?: SemanticAxNode;
+  dom?: CapturedNode;
+  axParentId?: SemanticNodeId;
+  domParentId?: SemanticNodeId;
+  sourceOrder: number;
+  excluded: boolean;
+}
+
+export interface SemanticGraph {
+  viewport: Viewport;
+  rootFrameId: string;
+  frames: Map<string, SemanticFrame>;
+  nodes: Map<SemanticNodeId, SemanticGraphNode>;
+  nodeIdsByFrame: Map<string, SemanticNodeId[]>;
+  nodeByFrameBackend: Map<string, SemanticNodeId>;
+}
+
+export interface ResolvedSemanticNode extends SemanticGraphNode {
+  vom: Omit<VomNode, "id" | "parentId" | "backendNodeId" | "frameId" | "contextScopeId">;
+  referenceable: boolean;
+  roleSource: "ax" | "ax-ignored" | "dom-explicit" | "dom-native" | "none";
+}
+
+export interface ResolvedSemanticGraph extends Omit<SemanticGraph, "nodes"> {
+  nodes: Map<SemanticNodeId, ResolvedSemanticNode>;
+}
+
+export type StructureDecision =
+  | { kind: "keep"; reason: "semantic" | "frame-owner" }
+  | { kind: "inferred-group"; reason: "independent-interaction-branches" }
+  | { kind: "transparent"; reason: "wrapper" | "child-document-root" | "ax-ignored" }
+  | {
+      kind: "excluded";
+      reason: "excluded" | "redundant-source" | "non-rendered-dom-fallback";
+    };
+
+export interface StructuredSemanticNode extends ResolvedSemanticNode {
+  structure: StructureDecision;
+  semanticParentId?: SemanticNodeId;
+}
+
+export interface StructuredSemanticGraph extends Omit<ResolvedSemanticGraph, "nodes"> {
+  nodes: Map<SemanticNodeId, StructuredSemanticNode>;
+}
+
+export function frameBackendKey(frameId: string, backendNodeId: number): string {
+  return `${frameId}\u0000${backendNodeId}`;
+}
+
+export function frameAxKey(frameId: string, axNodeId: string): string {
+  return `${frameId}\u0000${axNodeId}`;
+}

biome.json

@@ -44,6 +44,7 @@
       "!packages/dsh-plugin-browserskill/src/client/bsk-ui.nomodule.css",
       "!packages/dsh-plugin-browserskill/.bsk-ui.raw.css",
       "!packages/dsh-plugin-browserskill/.bsk-ui.input.css",
+      "!evals/browser/results/**",
       "!**/target/**",
       "!**/.wxt/**",
       "!**/.output/**",

evals/browser/README.md

@@ -0,0 +1,259 @@
+# Browser capability evaluation corpus
+
+This directory is a deterministic, local browser evaluation environment for BrowserSkill, DSH,
+and other command-line agents. Cases, fixture pages, direct `bsk` workflows, and assertions are
+data-driven and discovered automatically. Adding a case does not require editing a central switch.
+
+[中文说明](README.zh-CN.md)
+
+## Design goals
+
+- Agent-neutral: prompts describe observable page goals so the same cases can run through different
+  agents and adapters.
+- Deterministic: pages run locally and use stable markers and run-scoped events.
+- Extensible: manifests, fixture modules, and workflows are auto-discovered.
+- Reproducible: generated cases record a seed and derive every DOM variation from it.
+- Honest verification: page-observable results, response markers, and adapter evidence are reported
+  separately. Missing adapter evidence is `unverified`, never silently treated as passed.
+- Privacy-safe: user badcases must be reduced to synthetic DOM and anonymized data before commit.
+
+The corpus currently has six stable `core` cases and one seeded `matrix` case. The operation
+inventory contains 28 browser operations; that count is capability coverage, not the number of
+cases. Cases can grow independently and many cases may cover the same operation under different
+page conditions.
+
+## Quick start
+
+These commands validate manifests and run unit/integration tests without launching a browser:
+
+```sh
+pnpm eval:browser validate
+pnpm eval:browser list
+pnpm eval:browser coverage
+pnpm eval:browser:test
+```
+
+Build the repository CLI and exercise the real CLI, daemon, extension, Agent Window, and pages:
+
+```sh
+cargo build -p bsk
+BSK_AUTO_UPDATE=off pnpm eval:browser smoke --suite core --bsk ./target/debug/bsk
+BSK_AUTO_UPDATE=off pnpm eval:browser smoke --suite matrix --seed 4,7,14 --bsk ./target/debug/bsk
+```
+
+Every smoke case starts a fresh browser session and stops it in a `finally` cleanup path. Reports
+and screenshots are written to the ignored `evals/browser/results/` directory.
+
+`pnpm run eval:browser -- coverage` is also supported. The CLI intentionally accepts pnpm's leading
+`--` separator.
+
+## Suites and selection
+
+| Suite | Intended use | Default execution |
+| --- | --- | --- |
+| `core` | Small stable acceptance set for everyday smoke and CI | Yes |
+| `matrix` | Seeded DOM, timing, and layout variations | Explicit |
+| `regression` | Minimized user badcases tied to an issue or fix | Explicit |
+| `stress` | Higher volume or slower boundary testing | Explicit |
+| `manual` | Human-dependent capabilities that cannot be deterministic | Explicit |
+
+`smoke` and `run-agent` default to `core`, so adding a stress or regression case cannot silently
+slow down existing CI. `list`, `coverage`, and `validate` inspect the full corpus by default.
+
+```sh
+pnpm eval:browser list --suite core
+pnpm eval:browser list --tag form
+pnpm eval:browser smoke --case form-controls
+pnpm eval:browser smoke --case form-controls,generated-form
+pnpm eval:browser smoke --case all
+```
+
+Filters from different dimensions are combined. Repeated/comma-separated suites or case ids are
+alternatives; every requested tag must be present. `--task` remains a backward-compatible alias for
+`--case`.
+
+## Directory and discovery model
+
+```text
+evals/browser/
+  cases/
+    core/*.case.json
+    matrix/*.case.json
+    regression/<case-id>/
+      <case-id>.case.json
+      <case-id>.fixture.mjs
+      README.md
+  fixtures/pages/*.fixture.mjs
+  schemas/case.schema.json
+  lib/
+  tests/
+```
+
+- Any `cases/**/*.case.json` file is loaded as a case manifest.
+- Any `fixtures/**/*.fixture.mjs` or `cases/**/*.fixture.mjs` file is registered as a fixture.
+- Manifests are ordered by suite, optional numeric `order`, then id.
+- `validate` rejects duplicate case ids, duplicate routes, missing fixture routes, unknown
+  operations/actions, invalid workflow variables, and adapter assertions with no evidence producer.
+
+## Case manifest
+
+A case owns all information needed by both an agent evaluation and direct CLI smoke:
+
+```json
+{
+  "$schema": "../../schemas/case.schema.json",
+  "schemaVersion": 1,
+  "id": "example-case",
+  "title": "Example browser behavior",
+  "order": 10,
+  "suite": "core",
+  "tags": ["form", "keyboard"],
+  "seed": 17,
+  "fixture": { "startPath": "/example" },
+  "prompts": { "en": "Open {url} ...", "zh-CN": "打开 {url}……" },
+  "coverage": ["page.navigate", "interact.press"],
+  "assertions": { "site": [], "response": [], "adapter": [] },
+  "smoke": { "steps": [{ "action": "navigate" }] }
+}
+```
+
+Prompt placeholders are `{url}`, `{baseUrl}`, `{runId}`, and `{seed}`. Agent adapter arguments also
+support `{prompt}`, `{caseId}` / `{taskId}`, and `{variant}`.
+
+Assertions have three independent sources:
+
+- `site`: events emitted by the local page, such as submitted values or a history navigation.
+- `response`: stable text that must appear in the agent or CLI output.
+- `adapter`: facts outside page JavaScript, such as a non-empty screenshot or confirmed session
+  cleanup.
+
+The declarative smoke workflow supports navigation/history, waits, observe/snapshot/HTML,
+screenshot/console/network, click/hover/fill/select/press, tabs, resize/emulation, and the manual
+ownership/help operations. A step may `saveAs` its JSON result and later reference values such as
+`{child.tab_id}`. A step may set `evidence` for an adapter assertion. See existing manifests for
+complete examples.
+
+## Adding a normal case
+
+1. Add a `*.fixture.mjs` module exporting `{ id, routes, render(context) }`. It can live in shared
+   `fixtures/pages/` or beside a self-contained regression case.
+2. Add a `*.case.json` manifest with prompts, operation coverage, assertions, and smoke steps.
+3. Make all page events run-scoped using the shared `browserEval.send(...)` client helper.
+4. Run `pnpm eval:browser validate` and `pnpm eval:browser:test`.
+5. Run the new case against the real local build with `smoke --case <id>`.
+
+Prefer one behavior or failure mechanism per case. Stable synthetic markers make failures easier to
+diagnose than assertions against incidental prose.
+
+## Turning a user badcase into a regression
+
+Create a self-contained starting point:
+
+```sh
+pnpm eval:browser scaffold reported-timeout \
+  --title "Navigation settles after a late frame" \
+  --source "issue-123"
+```
+
+The command creates a manifest, fixture, and reproduction notes under
+`cases/regression/reported-timeout/`. Then reduce the report to the smallest relevant mechanism:
+
+- Keep DOM structure, timing, redirects, frames, or browser state that triggers the bug.
+- Replace names, account data, URLs, tokens, screenshots, and page copy with synthetic values.
+- Do not commit HAR files, cookies, credentials, production HTML, or proprietary assets.
+- Record the issue/PR reference, seed when relevant, expected result, and the fixing PR.
+- Confirm the new case fails on the known-bad build and passes on the fixed build when practical.
+
+## Seeded matrix cases
+
+`generated-form` varies label association, nesting depth, hydration delay, decoy controls, field
+order, and element ids while keeping the task and oracle stable. Inspect a seed without a browser:
+
+```sh
+pnpm eval:browser generate --seed user-badcase-42
+pnpm eval:browser prompt generated-form --seed user-badcase-42 --run-id manual-42
+pnpm eval:browser smoke --case generated-form --seed user-badcase-42
+pnpm eval:browser smoke --case generated-form --seed 4,7,14
+```
+
+Repeated/comma-separated seeds run as independent results. Reports store every normalized seed, so
+a failure can be replayed exactly and promoted into a named regression case if it represents a
+distinct bug.
+
+## Run any command-line agent
+
+Copy `agents.example.json` to the ignored `agents.local.json` and adapt its command. Arguments are
+passed directly to the executable without a shell.
+
+```sh
+pnpm eval:browser run-agent \
+  --config evals/browser/agents.local.json \
+  --agent dsh-local \
+  --suite core \
+  --repeat 3
+```
+
+An adapter may define `command`, `args`, `cwd`, `env`, `timeoutMs`, `variant`, free-form `metadata`,
+and optional `metrics.errorPattern` / `metrics.toolCallPattern` regular expressions.
+
+To compare 28 granular tools with domain tools, create two isolated adapter entries and run both
+against the same selected cases and seeds:
+
+```sh
+pnpm eval:browser run-agent \
+  --config evals/browser/agents.local.json \
+  --agent dsh-granular,dsh-domain \
+  --suite core \
+  --repeat 10
+```
+
+Keep browser runs sequential to avoid session contention. Use fresh profiles and alternate adapter
+order in larger experiments to reduce warm-cache bias.
+
+## Reading results
+
+```sh
+pnpm eval:browser summarize evals/browser/results/*.json
+```
+
+The summary groups by adapter and variant and reports pass rate, fully verified rate, process
+failures, matched error count, average tool calls, and average duration. The raw JSON retains case,
+suite, tags, seed, prompt, command output, page event count, and individual oracle checks.
+
+A healthy run has:
+
+- no execution timeout or non-zero exit;
+- no `executionError` in direct smoke;
+- `verification.status` equal to `passed` (or intentionally `passed-with-unverified` for an agent
+  adapter that cannot expose external evidence);
+- every session cleanup assertion verified;
+- no unexpected increase in errors, tool calls, or duration versus the chosen baseline.
+
+## Development baseline
+
+Use these lanes as commit and PR gates:
+
+| Change | Required checks |
+| --- | --- |
+| Any case, fixture, oracle, or harness change | `pnpm eval:browser:check` |
+| CLI, daemon, extension, DSH plugin, or browser-operation change | The check above, `cargo build -p bsk`, then real-browser `smoke --suite core` |
+| DOM discovery, form interaction, timing, or waiting change | The checks above, then `smoke --suite matrix --seed 4,7,14` |
+| A bug fix with a known reproduction | Add a `regression` case and run that case on the fixed build |
+
+Before committing this harness, the complete acceptance sequence is:
+
+```sh
+pnpm eval:browser:check
+cargo build -p bsk
+BSK_AUTO_UPDATE=off pnpm eval:browser smoke --case all --bsk ./target/debug/bsk
+BSK_AUTO_UPDATE=off pnpm eval:browser smoke --suite matrix --seed 4,7,14 --bsk ./target/debug/bsk
+```
+
+All commands must exit zero. The smoke summary must have 100% pass and fully verified rates, zero
+execution failures/errors, and `bsk session list --json` must be `[]` afterward. Do not weaken an
+oracle or replace a stable marker merely to make a regression pass; behavior changes should update
+the case and expected baseline in the same reviewed change.
+
+The direct smoke lane covers 25 of 28 operations. `tabs.borrow`, `tabs.return`, and
+`assist.request-help` stay manual because they require a real user tab or human interaction and
+would make the default suite destructive or non-deterministic.

evals/browser/README.zh-CN.md

@@ -0,0 +1,197 @@
+# 浏览器能力测试语料库
+
+这里是一套供 BrowserSkill、DSH 以及其他命令行 Agent 共用的本地确定性浏览器测试环境。
+case、测试页面、`bsk` 直连流程和断言都会自动发现；新增 case 不需要修改中央 `switch`。
+
+[English](README.md)
+
+## 核心原则
+
+- 与 Agent 无关：prompt 只描述可观察的页面目标，同一套 case 可以被不同 Agent 和
+  adapter 使用。
+- 本地且确定：页面只依赖本地服务，使用稳定 marker 和按 run 隔离的事件。
+- 可扩展：manifest、fixture 和 workflow 都从目录自动发现。
+- 可复现：生成式页面的所有变化由 seed 决定，报告会保留 seed。
+- 如实验证：页面事件、回答文本和 adapter 外部证据分别统计；拿不到的证据标为
+  `unverified`，不会冒充通过。
+- 隐私安全：用户 badcase 必须先缩减为合成 DOM 和匿名数据，再进入仓库。
+
+当前有 6 个稳定的 `core` case 和 1 个 seed 驱动的 `matrix` case。28 表示浏览器操作能力
+清单，并不是 case 数量；同一种操作可以在不同页面结构、时序和浏览器状态下由多个 case
+重复覆盖。
+
+## 快速使用
+
+不启动浏览器的校验：
+
+```sh
+pnpm eval:browser validate
+pnpm eval:browser list
+pnpm eval:browser coverage
+pnpm eval:browser:test
+```
+
+使用仓库当前代码编译 `bsk`，再跑真实 CLI、daemon、扩展、小窗和页面链路：
+
+```sh
+cargo build -p bsk
+BSK_AUTO_UPDATE=off pnpm eval:browser smoke --suite core --bsk ./target/debug/bsk
+BSK_AUTO_UPDATE=off pnpm eval:browser smoke --suite matrix --seed 4,7,14 --bsk ./target/debug/bsk
+```
+
+每个 smoke case 都会创建独立 session，并在 `finally` 中关闭。JSON 报告和截图输出到已被
+Git 忽略的 `evals/browser/results/`。
+
+也可以写成 `pnpm run eval:browser -- coverage`；CLI 已兼容 pnpm 传入的前导 `--`。
+
+## Suite 与筛选
+
+| Suite | 用途 | 默认执行 |
+| --- | --- | --- |
+| `core` | 日常 smoke 和 CI 使用的小而稳定的验收集 | 是 |
+| `matrix` | seed 驱动的 DOM、时序、布局组合 | 显式选择 |
+| `regression` | 从用户 badcase 缩减并与 issue/修复关联的回归 | 显式选择 |
+| `stress` | 更高次数或更慢的边界测试 | 显式选择 |
+| `manual` | 必须依赖真人或真实用户标签页的能力 | 显式选择 |
+
+`smoke` 和 `run-agent` 不带筛选时只跑 `core`，所以以后新增 stress/badcase 不会突然拖慢
+已有 CI。`list`、`coverage`、`validate` 默认检查全部语料。
+
+```sh
+pnpm eval:browser list --suite core
+pnpm eval:browser list --tag form
+pnpm eval:browser smoke --case form-controls
+pnpm eval:browser smoke --case form-controls,generated-form
+pnpm eval:browser smoke --case all
+```
+
+不同维度的筛选会叠加；逗号分隔的 suite/case 是“或”，多个 tag 必须全部命中。旧参数
+`--task` 仍作为 `--case` 的兼容别名。
+
+## 自动发现结构
+
+```text
+evals/browser/
+  cases/
+    core/*.case.json
+    matrix/*.case.json
+    regression/<case-id>/
+      <case-id>.case.json
+      <case-id>.fixture.mjs
+      README.md
+  fixtures/pages/*.fixture.mjs
+  schemas/case.schema.json
+  lib/
+  tests/
+```
+
+- `cases/**/*.case.json` 都会作为 case manifest 加载。
+- `fixtures/**/*.fixture.mjs` 和 `cases/**/*.fixture.mjs` 都会注册为页面 fixture。
+- 顺序按 suite、可选的数字 `order`、id 排列。
+- `validate` 会阻止重复 case id、重复路由、缺失 fixture、未知操作/action、无效 workflow
+  变量，以及没有任何步骤产出的 adapter evidence。
+
+一个 manifest 同时描述：中英文 prompt、能力 coverage、页面事件/回答/adapter 三类断言，以及
+`bsk` 直连 smoke 的声明式步骤。prompt 可用 `{url}`、`{baseUrl}`、`{runId}`、`{seed}`；
+workflow 可以用 `saveAs` 保存 JSON 结果，并用 `{child.tab_id}` 之类的变量引用后续步骤。
+完整写法可直接参考 `cases/core/` 和 `cases/matrix/`。
+
+## 新增普通 case
+
+1. 新增导出 `{ id, routes, render(context) }` 的 `*.fixture.mjs`，可放共享 fixture 目录，也可
+   和 regression case 放在一起。
+2. 新增 `*.case.json`，写好 prompt、operation coverage、断言和 smoke steps。
+3. 页面使用共享的 `browserEval.send(...)` 上报按 run 隔离的事件。
+4. 执行 `pnpm eval:browser validate` 和 `pnpm eval:browser:test`。
+5. 用 `smoke --case <id>` 验证真实本地编译链路。
+
+建议一个 case 只表达一种行为或故障机制，并使用稳定的合成 marker，避免断言偶然文案。
+
+## 把用户 badcase 固化成回归
+
+先生成一个自包含模板：
+
+```sh
+pnpm eval:browser scaffold reported-timeout \
+  --title "Navigation settles after a late frame" \
+  --source "issue-123"
+```
+
+它会在 `cases/regression/reported-timeout/` 下生成 manifest、fixture 和复现说明。随后只保留
+真正触发问题的 DOM 结构、时序、跳转、frame 或浏览器状态，并遵守：
+
+- 所有姓名、账号、网址、token、截图和文案都替换为合成值。
+- 不提交 HAR、cookie、凭据、生产 HTML 或私有素材。
+- 记录 issue/PR 来源、相关 seed、期望行为和后续修复 PR。
+- 条件允许时，证明新 case 在旧版本失败、修复版本通过。
+
+## Seed 矩阵
+
+`generated-form` 会确定性改变 label 关联方式、DOM 嵌套、hydration 延迟、干扰控件、字段
+顺序和 element id，但任务和 oracle 保持不变：
+
+```sh
+pnpm eval:browser generate --seed user-badcase-42
+pnpm eval:browser prompt generated-form --seed user-badcase-42 --run-id manual-42
+pnpm eval:browser smoke --case generated-form --seed user-badcase-42
+pnpm eval:browser smoke --case generated-form --seed 4,7,14
+```
+
+逗号分隔或重复的 seed 会生成相互独立的结果。任何失败都能按报告中的规范化 seed 精确重放；
+若它代表独立 bug，再提升为命名 regression case。
+
+## 测任意 Agent 与比较 28/6 工具
+
+把 `agents.example.json` 复制为已被 Git 忽略的 `agents.local.json`，分别配置两个隔离的 Agent
+profile/build。参数以数组直接传给可执行程序，不经过 shell。
+
+```sh
+pnpm eval:browser run-agent \
+  --config evals/browser/agents.local.json \
+  --agent dsh-granular,dsh-domain \
+  --suite core \
+  --repeat 10
+```
+
+浏览器任务应串行运行，避免 session 竞争；更大实验中使用干净 profile 并轮换 adapter 顺序，
+降低缓存偏差。
+
+## 如何看结果
+
+```sh
+pnpm eval:browser summarize evals/browser/results/*.json
+```
+
+汇总按 adapter/variant 展示通过率、完全验证率、进程失败、错误数、平均工具调用数和耗时。
+原始 JSON 会保留 case、suite、tag、seed、prompt、命令输出、页面事件数和每条 oracle 结果。
+
+健康运行应满足：没有 timeout/非零退出，direct smoke 没有 `executionError`，验证状态为
+`passed`（无法暴露外部证据的 Agent adapter 可明确为 `passed-with-unverified`），session cleanup
+通过，并且错误数、调用数和耗时没有相对基线异常上涨。
+
+## 开发基准线
+
+后续开发统一按下面的门禁执行：
+
+| 改动范围 | 必跑检查 |
+| --- | --- |
+| 任意 case、fixture、oracle 或 harness 改动 | `pnpm eval:browser:check` |
+| CLI、daemon、扩展、DSH 插件或浏览器操作改动 | 上述检查、`cargo build -p bsk`、真实浏览器 `smoke --suite core` |
+| DOM 发现、表单交互、时序或等待逻辑改动 | 上述检查，再跑 `smoke --suite matrix --seed 4,7,14` |
+| 修复已有明确复现的 bug | 新增 `regression` case，并在修复版本单独运行该 case |
+
+提交这套 harness 前，完整验收命令为：
+
+```sh
+pnpm eval:browser:check
+cargo build -p bsk
+BSK_AUTO_UPDATE=off pnpm eval:browser smoke --case all --bsk ./target/debug/bsk
+BSK_AUTO_UPDATE=off pnpm eval:browser smoke --suite matrix --seed 4,7,14 --bsk ./target/debug/bsk
+```
+
+所有命令必须以 0 退出；smoke 汇总必须达到 100% pass、100% fully verified、0 execution
+failure/error，结束后 `bsk session list --json` 必须为 `[]`。不能为了让回归通过而削弱 oracle
+或替换稳定 marker；如果产品行为确实改变，case 与预期基线必须在同一个受审查改动中更新。
+
+直连 smoke 自动覆盖 28 项中的 25 项。`tabs.borrow`、`tabs.return`、`assist.request-help` 需要
+真实用户标签页或真人交互，因此保留在 manual lane，避免默认测试具有破坏性或不确定性。

evals/browser/agents.example.json

@@ -0,0 +1,17 @@
+{
+  "agents": {
+    "dsh-local": {
+      "variant": "granular-28",
+      "command": "dsh",
+      "args": ["--profile", "headless", "{prompt}"],
+      "cwd": "../..",
+      "timeoutMs": 300000,
+      "metadata": {
+        "toolCount": 28
+      },
+      "metrics": {
+        "toolCallPattern": "browser[_-][a-z_-]+"
+      }
+    }
+  }
+}

evals/browser/cases/README.md

@@ -0,0 +1,9 @@
+# Browser evaluation cases
+
+Cases are discovered recursively from `*.case.json`; colocated `*.fixture.mjs` files are discovered
+as fixtures. Use `core` for small deterministic acceptance checks, `matrix` for seeded variations,
+and `regression/<case-id>/` for privacy-safe minimized user badcases.
+
+Run `pnpm eval:browser validate` after every case change. See the parent
+[`README.md`](../README.md) for the manifest contract, workflow actions, scaffolding, and acceptance
+criteria.

evals/browser/cases/core/diagnostics.case.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "../../schemas/case.schema.json",
+  "schemaVersion": 1,
+  "id": "diagnostics",
+  "title": "Console and network inspection",
+  "order": 50,
+  "suite": "core",
+  "tags": ["console", "network", "diagnostics"],
+  "fixture": { "startPath": "/diagnostics" },
+  "prompts": {
+    "en": "Open {url}. Use browser diagnostics to inspect the page console and recent network activity. Report the console marker and the token returned by the ping request, then close the browser session.",
+    "zh-CN": "打开 {url}。使用浏览器诊断能力检查页面 console 和最近的 network 活动，报告 console marker 以及 ping 请求返回的 token，最后关闭浏览器会话。"
+  },
+  "coverage": [
+    "session.start",
+    "session.stop",
+    "page.navigate",
+    "inspect.console",
+    "inspect.network"
+  ],
+  "assertions": {
+    "site": [
+      {
+        "label": "diagnostic ping completed",
+        "type": "network.ping",
+        "minCount": 1
+      }
+    ],
+    "response": [
+      { "label": "reported console marker", "includes": "CONSOLE-61" },
+      { "label": "reported network token", "includes": "NETWORK-73" }
+    ],
+    "adapter": [
+      { "label": "console inspection was executed", "key": "consoleRead" },
+      { "label": "network inspection was executed", "key": "networkRead" },
+      { "label": "browser session was closed", "key": "sessionStopped" }
+    ]
+  },
+  "smoke": {
+    "steps": [
+      { "action": "navigate" },
+      { "action": "wait", "duration": "300ms" },
+      { "action": "console", "evidence": "consoleRead" },
+      { "action": "network", "evidence": "networkRead" },
+      { "action": "observe" }
+    ]
+  }
+}

evals/browser/cases/core/form-controls.case.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "../../schemas/case.schema.json",
+  "schemaVersion": 1,
+  "id": "form-controls",
+  "title": "Form, select, keyboard, and screenshot",
+  "order": 20,
+  "suite": "core",
+  "tags": ["form", "keyboard", "screenshot", "select"],
+  "fixture": { "startPath": "/form" },
+  "prompts": {
+    "en": "Open {url}. Fill Text input with \"agent-parity\" and Textarea with \"BrowserSkill works\". Select the visible option \"Two\" from Dropdown. Capture a screenshot of the form, focus Submit, and press Enter to submit. Confirm that the result says \"Received!\", then close the browser session.",
+    "zh-CN": "打开 {url}。把 Text input 填成“agent-parity”，Textarea 填成“BrowserSkill works”，Dropdown 选择可见选项“Two”。截取表单截图，然后聚焦 Submit 并按 Enter 提交。确认结果页出现“Received!”，最后关闭浏览器会话。"
+  },
+  "coverage": [
+    "session.start",
+    "session.stop",
+    "page.navigate",
+    "interact.fill",
+    "interact.select",
+    "interact.press",
+    "inspect.screenshot"
+  ],
+  "assertions": {
+    "site": [
+      {
+        "label": "Enter was pressed on Submit",
+        "type": "form.enter_pressed",
+        "minCount": 1
+      },
+      {
+        "label": "form values were submitted",
+        "type": "form.submitted",
+        "where": {
+          "data.text": "agent-parity",
+          "data.notes": "BrowserSkill works",
+          "data.choice": "two"
+        },
+        "minCount": 1
+      },
+      {
+        "label": "result page was displayed",
+        "type": "page.shown",
+        "where": { "data.path": "/result" },
+        "minCount": 1
+      }
+    ],
+    "response": [{ "label": "confirmed result", "includes": "Received!" }],
+    "adapter": [
+      { "label": "screenshot artifact was created", "key": "screenshotCreated" },
+      { "label": "browser session was closed", "key": "sessionStopped" }
+    ]
+  },
+  "smoke": {
+    "steps": [
+      { "action": "navigate" },
+      {
+        "action": "fill",
+        "selector": "#text-input",
+        "value": "agent-parity"
+      },
+      {
+        "action": "fill",
+        "selector": "#notes",
+        "value": "BrowserSkill works"
+      },
+      { "action": "select", "selector": "#choice", "values": ["two"] },
+      {
+        "action": "screenshot",
+        "artifactName": "form.png",
+        "evidence": "screenshotCreated"
+      },
+      { "action": "press", "key": "Enter", "selector": "#submit" },
+      {
+        "action": "wait-site-event",
+        "type": "page.shown",
+        "where": { "path": "/result" }
+      },
+      { "action": "wait", "duration": "200ms" },
+      { "action": "observe" }
+    ]
+  }
+}

evals/browser/cases/core/hover-inspect.case.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "../../schemas/case.schema.json",
+  "schemaVersion": 1,
+  "id": "hover-inspect",
+  "title": "Hover, local HTML, and screenshot",
+  "order": 30,
+  "suite": "core",
+  "tags": ["hover", "html", "screenshot"],
+  "fixture": { "startPath": "/hover-inspect" },
+  "prompts": {
+    "en": "Open {url}. Hover over Account, then choose Profile beta from the revealed menu. Inspect the local HTML around the Inspection card and capture a screenshot. Report both marker codes you find, then close the browser session.",
+    "zh-CN": "打开 {url}。把鼠标悬停在“Account”上，然后点击展开菜单中的“Profile beta”。检查 Inspection card 附近的局部 HTML，并截取页面截图。报告找到的两个标记代码，最后关闭浏览器会话。"
+  },
+  "coverage": [
+    "session.start",
+    "session.stop",
+    "page.navigate",
+    "interact.hover",
+    "interact.click",
+    "inspect.html",
+    "inspect.screenshot"
+  ],
+  "assertions": {
+    "site": [
+      {
+        "label": "Account menu was hovered",
+        "type": "hover.menu_opened",
+        "minCount": 1
+      },
+      {
+        "label": "Profile beta was selected",
+        "type": "hover.profile_clicked",
+        "minCount": 1
+      }
+    ],
+    "response": [
+      { "label": "reported hover marker", "includes": "HOVER-17" },
+      { "label": "reported HTML marker", "includes": "INSPECT-27" }
+    ],
+    "adapter": [
+      { "label": "HTML inspection was executed", "key": "htmlInspected" },
+      { "label": "screenshot artifact was created", "key": "screenshotCreated" },
+      { "label": "browser session was closed", "key": "sessionStopped" }
+    ]
+  },
+  "smoke": {
+    "steps": [
+      { "action": "navigate" },
+      { "action": "hover", "selector": "#account-menu" },
+      { "action": "click", "selector": "#profile-link" },
+      { "action": "html", "evidence": "htmlInspected" },
+      {
+        "action": "screenshot",
+        "artifactName": "hover-inspect.png",
+        "evidence": "screenshotCreated"
+      }
+    ]
+  }
+}

evals/browser/cases/core/mobile-emulation.case.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "../../schemas/case.schema.json",
+  "schemaVersion": 1,
+  "id": "mobile-emulation",
+  "title": "Mobile emulation",
+  "order": 60,
+  "suite": "core",
+  "tags": ["emulation", "mobile", "viewport"],
+  "fixture": { "startPath": "/responsive" },
+  "prompts": {
+    "en": "Open {url}, emulate an iPhone 14, and report the viewport marker shown on the page. Close the browser session when finished.",
+    "zh-CN": "打开 {url}，模拟 iPhone 14，并报告页面显示的 viewport marker。完成后关闭浏览器会话。"
+  },
+  "coverage": ["session.start", "session.stop", "page.navigate", "assist.emulate"],
+  "assertions": {
+    "site": [
+      {
+        "label": "iPhone-sized viewport was observed",
+        "type": "viewport.sample",
+        "where": { "data.width": 390, "data.height": 844 },
+        "minCount": 1
+      }
+    ],
+    "response": [{ "label": "reported viewport marker", "includes": "VIEWPORT-84" }],
+    "adapter": [
+      { "label": "device emulation was executed", "key": "emulatedDevice" },
+      { "label": "browser session was closed", "key": "sessionStopped" }
+    ]
+  },
+  "smoke": {
+    "steps": [
+      { "action": "navigate" },
+      { "action": "resize", "width": 900, "height": 700 },
+      {
+        "action": "emulate",
+        "device": "iphone-14",
+        "evidence": "emulatedDevice"
+      },
+      { "action": "wait", "duration": "300ms" },
+      { "action": "html" }
+    ]
+  }
+}

evals/browser/cases/core/navigation-history.case.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "../../schemas/case.schema.json",
+  "schemaVersion": 1,
+  "id": "navigation-history",
+  "title": "Navigation, history, and reload",
+  "order": 10,
+  "suite": "core",
+  "tags": ["navigation", "history", "reload"],
+  "fixture": { "startPath": "/navigation/start" },
+  "prompts": {
+    "en": "Open {url}. Read the main heading, follow the Details link, and report the code shown there. Then go back, go forward, reload the page, and close the browser session. Use only the browser capability for page operations.",
+    "zh-CN": "打开 {url}。读取页面主标题，点击“详情”，并报告详情页上的代码。然后依次后退、前进、刷新页面，最后关闭浏览器会话。页面操作只使用浏览器能力。"
+  },
+  "coverage": [
+    "session.start",
+    "session.stop",
+    "page.navigate",
+    "page.back",
+    "page.forward",
+    "page.reload",
+    "interact.click"
+  ],
+  "assertions": {
+    "site": [
+      {
+        "label": "details link was clicked",
+        "type": "navigation.detail.clicked",
+        "minCount": 1
+      },
+      {
+        "label": "back returned to the start page",
+        "type": "page.shown",
+        "where": { "data.path": "/navigation/start" },
+        "minCount": 2
+      },
+      {
+        "label": "forward returned to the detail page",
+        "type": "page.shown",
+        "where": { "data.path": "/navigation/detail" },
+        "minCount": 2
+      },
+      {
+        "label": "detail page was reloaded",
+        "type": "page.shown",
+        "where": {
+          "data.path": "/navigation/detail",
+          "data.navigationType": "reload"
+        },
+        "minCount": 1
+      }
+    ],
+    "response": [{ "label": "reported detail code", "includes": "NAV-42" }],
+    "adapter": [{ "label": "browser session was closed", "key": "sessionStopped" }]
+  },
+  "smoke": {
+    "steps": [
+      { "action": "navigate" },
+      { "action": "observe" },
+      { "action": "snapshot" },
+      { "action": "click", "selector": "#details-link" },
+      { "action": "html" },
+      { "action": "back" },
+      { "action": "forward" },
+      { "action": "reload" }
+    ]
+  }
+}

evals/browser/cases/core/tabs.case.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "../../schemas/case.schema.json",
+  "schemaVersion": 1,
+  "id": "tabs",
+  "title": "Create, select, and close a tab",
+  "order": 40,
+  "suite": "core",
+  "tags": ["tabs", "ownership", "lifecycle"],
+  "fixture": { "startPath": "/tabs" },
+  "prompts": {
+    "en": "Open {url}. Create a new browser tab at {baseUrl}/tabs/child?run={runId}, read its token, click \"Mark child visited\", close the child tab, return to the original tab, and close the browser session.",
+    "zh-CN": "打开 {url}。新建一个浏览器标签页并访问 {baseUrl}/tabs/child?run={runId}，读取其中的 token，点击“Mark child visited”，关闭子标签页，回到原标签页，最后关闭浏览器会话。"
+  },
+  "coverage": [
+    "session.start",
+    "session.stop",
+    "page.navigate",
+    "interact.click",
+    "tabs.create",
+    "tabs.select",
+    "tabs.close"
+  ],
+  "assertions": {
+    "site": [
+      {
+        "label": "child tab page was displayed",
+        "type": "page.shown",
+        "where": { "data.path": "/tabs/child" },
+        "minCount": 1
+      },
+      {
+        "label": "child tab action ran",
+        "type": "tabs.child_marked",
+        "minCount": 1
+      }
+    ],
+    "response": [{ "label": "reported child token", "includes": "TAB-29" }],
+    "adapter": [
+      { "label": "child tab was closed", "key": "childTabClosed" },
+      { "label": "browser session was closed", "key": "sessionStopped" }
+    ]
+  },
+  "smoke": {
+    "steps": [
+      { "action": "navigate", "saveAs": "original" },
+      { "action": "tab-list" },
+      {
+        "action": "tab-create",
+        "url": "{baseUrl}/tabs/child?run={runId}",
+        "saveAs": "child"
+      },
+      {
+        "action": "navigate",
+        "url": "{baseUrl}/tabs/child?run={runId}",
+        "tabId": "{child.tab_id}"
+      },
+      {
+        "action": "click",
+        "selector": "#mark-child",
+        "tabId": "{child.tab_id}"
+      },
+      { "action": "html", "tabId": "{child.tab_id}" },
+      {
+        "action": "tab-close",
+        "tabId": "{child.tab_id}",
+        "evidence": "childTabClosed"
+      },
+      { "action": "tab-select", "tabId": "{original.tab_id}" }
+    ]
+  }
+}

evals/browser/cases/matrix/README.md

@@ -0,0 +1,5 @@
+# Seeded matrix cases
+
+Matrix cases vary page structure or timing deterministically from a recorded seed. The task,
+assertions, and success marker remain stable so a failed seed can be replayed exactly. A seed that
+exposes a distinct product bug should be minimized and promoted to a named regression case.

evals/browser/cases/matrix/generated-form.case.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "../../schemas/case.schema.json",
+  "schemaVersion": 1,
+  "id": "generated-form",
+  "title": "Seeded form structure and hydration variants",
+  "order": 10,
+  "suite": "matrix",
+  "tags": ["dynamic-dom", "form", "hydration", "seeded"],
+  "seed": 20260827,
+  "fixture": { "startPath": "/matrix/generated-form" },
+  "prompts": {
+    "en": "Open {url}. Wait for the seeded form to finish hydrating. Fill Text input with \"seeded-agent\", select the visible option \"Two\", submit with Enter, and report the result marker and seed. Close the browser session.",
+    "zh-CN": "打开 {url}。等待 seeded form 完成 hydration，把 Text input 填成“seeded-agent”，选择可见选项“Two”，用 Enter 提交，并报告结果 marker 和 seed。最后关闭浏览器会话。"
+  },
+  "coverage": [
+    "session.start",
+    "session.stop",
+    "page.navigate",
+    "page.wait",
+    "inspect.observe",
+    "interact.fill",
+    "interact.select",
+    "interact.press"
+  ],
+  "assertions": {
+    "site": [
+      { "label": "generated form hydrated", "type": "matrix.ready", "minCount": 1 },
+      {
+        "label": "Enter was pressed on generated form",
+        "type": "matrix.enter_pressed",
+        "minCount": 1
+      },
+      {
+        "label": "generated values were submitted",
+        "type": "matrix.submitted",
+        "where": { "data.text": "seeded-agent", "data.choice": "two" },
+        "minCount": 1
+      },
+      {
+        "label": "matrix result page was displayed",
+        "type": "page.shown",
+        "where": { "data.path": "/matrix/generated-result" },
+        "minCount": 1
+      }
+    ],
+    "response": [
+      { "label": "reported matrix result", "includes": "MATRIX-OK" },
+      { "label": "reported selected seed", "includes": "SEED-" }
+    ],
+    "adapter": [{ "label": "browser session was closed", "key": "sessionStopped" }]
+  },
+  "smoke": {
+    "steps": [
+      { "action": "navigate" },
+      {
+        "action": "wait-site-event",
+        "type": "matrix.ready",
+        "timeoutMs": 5000
+      },
+      { "action": "observe" },
+      { "action": "fill", "selector": "[name=text]", "value": "seeded-agent" },
+      { "action": "select", "selector": "[name=choice]", "values": ["two"] },
+      {
+        "action": "press",
+        "key": "Enter",
+        "selector": "button[type=submit]"
+      },
+      {
+        "action": "wait-site-event",
+        "type": "page.shown",
+        "where": { "path": "/matrix/generated-result" }
+      },
+      { "action": "wait", "duration": "200ms" },
+      { "action": "observe" }
+    ]
+  }
+}

evals/browser/cases/regression/README.md

@@ -0,0 +1,12 @@
+# Regression cases
+
+Each user-reported badcase should live in its own directory with a manifest, synthetic fixture, and
+README describing the symptom, minimal reproduction, expected behavior, source reference, and fix.
+Never commit credentials, cookies, HAR files, production HTML, private screenshots, or proprietary
+assets.
+
+Create a starting point with:
+
+```sh
+pnpm eval:browser scaffold <case-id> --title "..." --source "issue-or-pr"
+```

evals/browser/cli.mjs

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { loadAgentConfig, runCommandTask } from "./lib/agent-runner.mjs";
+import { runBskSmokeTask } from "./lib/bsk-runner.mjs";
+import { buildOperationCoverage } from "./lib/coverage.mjs";
+import { loadFixtureRegistry } from "./lib/fixture-registry.mjs";
+import { verifyTask } from "./lib/oracle.mjs";
+import { resultsDirectory } from "./lib/paths.mjs";
+import { repositorySummary, validateRepositoryCases } from "./lib/repository-validation.mjs";
+import { scaffoldCase } from "./lib/scaffold-case.mjs";
+import { describeSeed, normalizeSeed } from "./lib/seeded-generator.mjs";
+import { createEvalServer } from "./lib/server.mjs";
+import { printSummary, summarizeReports } from "./lib/summary.mjs";
+import { allTasks, getTask, listTasks, renderPrompt } from "./lib/tasks.mjs";
+
+const booleanOptions = new Set(["help", "json"]);
+
+function parseArguments(argv) {
+  const normalized = argv[0] === "--" ? argv.slice(1) : argv;
+  let [command, ...rest] = normalized;
+  const options = new Map();
+  const positionals = [];
+  if (command === "--help" || command === "-h") {
+    command = undefined;
+    options.set("help", [true]);
+  }
+  for (let index = 0; index < rest.length; index += 1) {
+    const argument = rest[index];
+    if (!argument.startsWith("--")) {
+      positionals.push(argument);
+      continue;
+    }
+    const equals = argument.indexOf("=");
+    const name = argument.slice(2, equals === -1 ? undefined : equals);
+    let value = equals === -1 ? undefined : argument.slice(equals + 1);
+    if (value === undefined && !booleanOptions.has(name)) {
+      const candidate = rest[index + 1];
+      if (candidate === undefined || candidate.startsWith("--")) {
+        throw new Error(`--${name} requires a value`);
+      }
+      value = candidate;
+      index += 1;
+    }
+    const values = options.get(name) ?? [];
+    values.push(value ?? true);
+    options.set(name, values);
+  }
+  return { command, options, positionals };
+}
+
+function option(parsed, name, fallback) {
+  return parsed.options.get(name)?.at(-1) ?? fallback;
+}
+
+function optionList(parsed, name) {
+  return (parsed.options.get(name) ?? [])
+    .flatMap((value) => String(value).split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+function numericOption(parsed, name, fallback) {
+  const value = Number(option(parsed, name, fallback));
+  if (!Number.isFinite(value) || value < 0) throw new Error(`--${name} must be non-negative`);
+  return value;
+}
+
+function seedOptions(parsed, fallback) {
+  const requested = optionList(parsed, "seed");
+  return requested.length > 0 ? unique(requested.map(normalizeSeed)) : [fallback];
+}
+
+function seedOption(parsed, fallback) {
+  const seeds = seedOptions(parsed, fallback);
+  if (seeds.length > 1) throw new Error("this command accepts only one --seed value");
+  return seeds[0];
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function selectCases(cases, parsed, { defaultSuite } = {}) {
+  const requestedIds = unique([...optionList(parsed, "case"), ...optionList(parsed, "task")]);
+  const requestedSuites = unique(optionList(parsed, "suite"));
+  const requestedTags = unique(optionList(parsed, "tag"));
+  const hasSelector =
+    requestedIds.length > 0 || requestedSuites.length > 0 || requestedTags.length > 0;
+
+  if (requestedIds.includes("all") && requestedIds.length > 1) {
+    throw new Error("--case all cannot be combined with named cases");
+  }
+  if (requestedSuites.includes("all") && requestedSuites.length > 1) {
+    throw new Error("--suite all cannot be combined with named suites");
+  }
+
+  const caseIds = requestedIds.includes("all") ? [] : requestedIds;
+  const suites = requestedSuites.includes("all")
+    ? []
+    : requestedSuites.length > 0
+      ? requestedSuites
+      : !hasSelector && defaultSuite
+        ? [defaultSuite]
+        : [];
+
+  const knownIds = new Set(cases.map(({ id }) => id));
+  const missingIds = caseIds.filter((id) => !knownIds.has(id));
+  if (missingIds.length > 0) throw new Error(`unknown case(s): ${missingIds.join(", ")}`);
+  const knownSuites = new Set(cases.map(({ suite }) => suite));
+  const missingSuites = suites.filter((suite) => !knownSuites.has(suite));
+  if (missingSuites.length > 0) throw new Error(`unknown suite(s): ${missingSuites.join(", ")}`);
+  const knownTags = new Set(cases.flatMap(({ tags }) => tags));
+  const missingTags = requestedTags.filter((tag) => !knownTags.has(tag));
+  if (missingTags.length > 0) throw new Error(`unknown tag(s): ${missingTags.join(", ")}`);
+
+  const selected = cases.filter(
+    (testCase) =>
+      (caseIds.length === 0 || caseIds.includes(testCase.id)) &&
+      (suites.length === 0 || suites.includes(testCase.suite)) &&
+      requestedTags.every((tag) => testCase.tags.includes(tag)),
+  );
+  if (selected.length === 0) throw new Error("case selectors matched no cases");
+  return selected;
+}
+
+function reportFilename(mode) {
+  return `${new Date().toISOString().replaceAll(/[:.]/g, "-")}-${mode}.json`;
+}
+
+async function saveReport(report, outputDirectory) {
+  await mkdir(outputDirectory, { recursive: true });
+  const path = join(outputDirectory, reportFilename(report.mode));
+  await writeFile(path, `${JSON.stringify(report, null, 2)}\n`);
+  return path;
+}
+
+async function loadValidatedCorpus() {
+  const [cases, fixtureRegistry] = await Promise.all([allTasks(), loadFixtureRegistry()]);
+  const errors = validateRepositoryCases(cases, fixtureRegistry);
+  if (errors.length > 0) throw new Error(`browser eval validation failed:\n${errors.join("\n")}`);
+  return { cases, fixtureRegistry };
+}
+
+function selectionMetadata(cases) {
+  return {
+    cases: cases.map(({ id }) => id),
+    suites: unique(cases.map(({ suite }) => suite)),
+    tags: unique(cases.flatMap(({ tags }) => tags)).sort(),
+  };
+}
+
+function usage() {
+  console.log(`BrowserSkill local browser evaluation
+
+Usage:
+  node evals/browser/cli.mjs validate [--json]
+  node evals/browser/cli.mjs list [--suite NAME] [--tag NAME] [--case ID] [--json]
+  node evals/browser/cli.mjs coverage [--suite NAME] [--tag NAME] [--case ID] [--json]
+  node evals/browser/cli.mjs serve [--host 127.0.0.1] [--port 4173]
+  node evals/browser/cli.mjs prompt <case> [--base-url URL] [--run-id ID] [--seed VALUE]
+  node evals/browser/cli.mjs verify <case> --base-url URL --run-id ID [--response TEXT]
+  node evals/browser/cli.mjs smoke [--bsk bsk] [--suite core] [--case ID] [--seed VALUE]
+  node evals/browser/cli.mjs run-agent --config FILE --agent NAME [--suite core] [--case ID]
+  node evals/browser/cli.mjs generate --seed VALUE [--json]
+  node evals/browser/cli.mjs scaffold <case-id> [--suite regression] [--title TEXT]
+  node evals/browser/cli.mjs summarize <report.json> [more reports...]
+
+Selection:
+  --case ID[,ID]       Select case ids; --task is a backward-compatible alias
+  --suite NAME[,NAME]  Select suites
+  --tag NAME[,NAME]    Require every selected tag
+  --case all           Explicitly include every suite (run commands default to core)
+  --seed VALUE[,VALUE] Run one or more reproducible matrix seeds
+
+run-agent options:
+  --agent NAME[,NAME]  One or more entries from the config file
+  --variant NAME       Override the report label (does not switch plugin code)
+  --locale en|zh-CN    Prompt language (default zh-CN)
+  --repeat N           Repeat every selected case (default 1)
+  --timeout MS         Per-agent timeout (default 300000)
+  --out DIRECTORY      Report/artifact directory
+`);
+}
+
+async function commandValidate(parsed) {
+  const { cases, fixtureRegistry } = await loadValidatedCorpus();
+  const summary = { ok: true, ...repositorySummary(cases, fixtureRegistry) };
+  if (option(parsed, "json", false)) console.log(JSON.stringify(summary, null, 2));
+  else {
+    console.log(`Validated ${summary.cases} cases and ${summary.fixtureRoutes} fixture routes.`);
+    console.log(
+      `Suites: ${Object.entries(summary.suites)
+        .map(([suite, count]) => `${suite}=${count}`)
+        .join(", ")}`,
+    );
+  }
+}
+
+async function commandList(parsed) {
+  const cases = selectCases(await allTasks(), parsed);
+  const tasks = listTasks(cases);
+  if (option(parsed, "json", false)) console.log(JSON.stringify(tasks, null, 2));
+  else {
+    for (const task of tasks) {
+      console.log(`${task.id}\t${task.suite}\t${task.tags.join(",")}\t${task.title}`);
+    }
+  }
+}
+
+async function commandCoverage(parsed) {
+  const cases = selectCases(await allTasks(), parsed);
+  const coverage = buildOperationCoverage(cases);
+  if (option(parsed, "json", false)) {
+    console.log(JSON.stringify(coverage, null, 2));
+  } else {
+    console.table(
+      coverage.map(({ operation, agentCases, smokeCases, directSmoke, note }) => ({
+        operation,
+        agent_cases: agentCases.join(", ") || "-",
+        smoke_cases: smokeCases.join(", ") || "-",
+        direct_smoke: directSmoke ? "yes" : "manual",
+        note: note ?? "",
+      })),
+    );
+  }
+}
+
+async function commandServe(parsed) {
+  const { fixtureRegistry } = await loadValidatedCorpus();
+  const server = createEvalServer({
+    host: option(parsed, "host", "127.0.0.1"),
+    port: numericOption(parsed, "port", 4173),
+    fixtureRegistry,
+  });
+  const info = await server.start();
+  console.log(`Browser eval server listening at ${info.baseUrl}`);
+  console.log("Press Ctrl-C to stop.");
+  await new Promise((resolveSignal) => {
+    process.once("SIGINT", resolveSignal);
+    process.once("SIGTERM", resolveSignal);
+  });
+  await server.stop();
+}
+
+async function commandPrompt(parsed) {
+  const cases = await allTasks();
+  const task = getTask(parsed.positionals[0], cases);
+  const prompt = renderPrompt(task, {
+    baseUrl: option(parsed, "base-url", "http://127.0.0.1:4173"),
+    runId: option(parsed, "run-id", randomUUID()),
+    locale: option(parsed, "locale", "zh-CN"),
+    seed: seedOption(parsed, task.seed),
+  });
+  console.log(prompt);
+}
+
+async function commandVerify(parsed) {
+  const task = getTask(parsed.positionals[0], await allTasks());
+  const baseUrl = option(parsed, "base-url");
+  const runId = option(parsed, "run-id");
+  if (!baseUrl || !runId) throw new Error("verify requires --base-url and --run-id");
+  let responseText = option(parsed, "response", "");
+  const responseFile = option(parsed, "response-file");
+  if (responseFile) responseText = await readFile(resolve(responseFile), "utf8");
+  const stateResponse = await fetch(`${baseUrl}/api/runs/${encodeURIComponent(runId)}`);
+  if (!stateResponse.ok) throw new Error(`oracle request failed with ${stateResponse.status}`);
+  const state = await stateResponse.json();
+  const verification = verifyTask(task, { events: state.events, responseText });
+  console.log(JSON.stringify(verification, null, 2));
+  if (verification.status === "failed") process.exitCode = 1;
+}
+
+async function commandRunAgent(parsed) {
+  const configPath = option(parsed, "config");
+  const agentNames = optionList(parsed, "agent");
+  if (!configPath || agentNames.length === 0) {
+    throw new Error("run-agent requires --config and at least one --agent");
+  }
+  const { cases, fixtureRegistry } = await loadValidatedCorpus();
+  const selected = selectCases(cases, parsed, { defaultSuite: "core" });
+  const repeat = numericOption(parsed, "repeat", 1);
+  if (!Number.isInteger(repeat) || repeat < 1) throw new Error("--repeat must be at least 1");
+  const outputDirectory = resolve(option(parsed, "out", resultsDirectory));
+  const server = createEvalServer({ fixtureRegistry });
+  const serverInfo = await server.start();
+  const results = [];
+  const startedAt = new Date().toISOString();
+  try {
+    for (const agentName of agentNames) {
+      const { adapter, configDirectory } = await loadAgentConfig(configPath, agentName);
+      for (let iteration = 1; iteration <= repeat; iteration += 1) {
+        for (const task of selected) {
+          for (const seed of seedOptions(parsed, task.seed)) {
+            const seedLabel = seed === undefined ? "" : ` seed=${seed}`;
+            console.log(`[run] ${agentName} ${task.id}${seedLabel} (${iteration}/${repeat})`);
+            const result = await runCommandTask({
+              server,
+              serverInfo,
+              task,
+              adapter,
+              adapterName: agentName,
+              configDirectory,
+              iteration,
+              locale: option(parsed, "locale", "zh-CN"),
+              seed,
+              timeoutMs: numericOption(parsed, "timeout", 300_000),
+              variantOverride: option(parsed, "variant"),
+            });
+            results.push(result);
+            console.log(`  ${result.verification.status} in ${result.execution.durationMs}ms`);
+          }
+        }
+      }
+    }
+  } finally {
+    await server.stop();
+  }
+  const report = {
+    schemaVersion: 1,
+    mode: "agent",
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    selection: selectionMetadata(selected),
+    seeds: unique(results.map(({ seed }) => seed).filter((seed) => seed !== undefined)),
+    results,
+  };
+  const path = await saveReport(report, outputDirectory);
+  printSummary(summarizeReports([report]));
+  console.log(`Report: ${path}`);
+  if (
+    results.some(
+      (result) =>
+        result.verification.status === "failed" ||
+        result.execution.timedOut ||
+        result.execution.exitCode !== 0,
+    )
+  ) {
+    process.exitCode = 1;
+  }
+}
+
+async function commandSmoke(parsed) {
+  const { cases, fixtureRegistry } = await loadValidatedCorpus();
+  const selected = selectCases(cases, parsed, { defaultSuite: "core" });
+  const outputDirectory = resolve(option(parsed, "out", resultsDirectory));
+  const server = createEvalServer({ fixtureRegistry });
+  const serverInfo = await server.start();
+  const results = [];
+  const startedAt = new Date().toISOString();
+  try {
+    for (const task of selected) {
+      for (const seed of seedOptions(parsed, task.seed)) {
+        const runId = `bsk-${task.id}-${randomUUID().slice(0, 8)}`;
+        const seedLabel = seed === undefined ? "" : ` seed=${seed}`;
+        console.log(`[smoke] ${task.id}${seedLabel}`);
+        const result = await runBskSmokeTask({
+          bskCommand: option(parsed, "bsk", "bsk"),
+          outputDirectory,
+          server,
+          serverInfo,
+          task,
+          runId,
+          seed,
+          timeoutMs: numericOption(parsed, "timeout", 60_000),
+        });
+        results.push(result);
+        console.log(
+          `  ${result.verification.status}${result.executionError ? `: ${result.executionError}` : ""}`,
+        );
+      }
+    }
+  } finally {
+    await server.stop();
+  }
+  const report = {
+    schemaVersion: 1,
+    mode: "bsk-smoke",
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    selection: selectionMetadata(selected),
+    seeds: unique(results.map(({ seed }) => seed).filter((seed) => seed !== undefined)),
+    results,
+  };
+  const path = await saveReport(report, outputDirectory);
+  printSummary(summarizeReports([report]));
+  console.log(`Report: ${path}`);
+  if (results.some((result) => result.executionError || result.verification.status === "failed")) {
+    process.exitCode = 1;
+  }
+}
+
+async function commandGenerate(parsed) {
+  if (!parsed.options.has("seed")) throw new Error("generate requires --seed");
+  const dimensions = unique(optionList(parsed, "seed").map(normalizeSeed)).map(describeSeed);
+  const output = dimensions.length === 1 ? dimensions[0] : dimensions;
+  if (option(parsed, "json", false)) console.log(JSON.stringify(output, null, 2));
+  else console.table(dimensions);
+}
+
+async function commandScaffold(parsed) {
+  const id = parsed.positionals[0];
+  if (!id) throw new Error("scaffold requires a case id");
+  const result = await scaffoldCase({
+    id,
+    title: option(parsed, "title", id),
+    suite: option(parsed, "suite", "regression"),
+    source: option(parsed, "source"),
+  });
+  if (option(parsed, "json", false)) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`Created ${result.directory}`);
+    console.log(
+      "Edit the fixture, prompt, workflow, and assertions, then run eval:browser validate.",
+    );
+  }
+}
+
+async function commandSummarize(parsed) {
+  const paths = [...parsed.positionals, ...optionList(parsed, "input")];
+  if (paths.length === 0) throw new Error("summarize requires at least one report path");
+  const reports = await Promise.all(
+    paths.map(async (path) => JSON.parse(await readFile(resolve(path), "utf8"))),
+  );
+  const rows = summarizeReports(reports);
+  if (option(parsed, "json", false)) console.log(JSON.stringify(rows, null, 2));
+  else printSummary(rows);
+}
+
+async function main() {
+  const parsed = parseArguments(process.argv.slice(2));
+  if (!parsed.command || option(parsed, "help", false)) return usage();
+  switch (parsed.command) {
+    case "validate":
+      return commandValidate(parsed);
+    case "list":
+      return commandList(parsed);
+    case "coverage":
+      return commandCoverage(parsed);
+    case "serve":
+      return commandServe(parsed);
+    case "prompt":
+      return commandPrompt(parsed);
+    case "verify":
+      return commandVerify(parsed);
+    case "run-agent":
+      return commandRunAgent(parsed);
+    case "smoke":
+      return commandSmoke(parsed);
+    case "generate":
+      return commandGenerate(parsed);
+    case "scaffold":
+      return commandScaffold(parsed);
+    case "summarize":
+      return commandSummarize(parsed);
+    default:
+      throw new Error(`unknown command ${JSON.stringify(parsed.command)}`);
+  }
+}
+
+main().catch((error) => {
+  console.error(`browser eval: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});

evals/browser/fixtures/pages/diagnostics.fixture.mjs

@@ -0,0 +1,18 @@
+import { page } from "../../lib/fixtures.mjs";
+
+export default {
+  id: "diagnostics",
+  routes: ["/diagnostics"],
+  render() {
+    return page({
+      title: "Diagnostics Lab",
+      body: `<section class="card"><h1>Diagnostics Lab</h1><p>Inspect console and network buffers.</p><p id="network-status" class="muted">Ping pending</p></section>`,
+      script: `
+        console.log("Browser eval console marker: CONSOLE-61");
+        fetch("/api/ping?run=" + encodeURIComponent(browserEval.runId))
+          .then((response) => response.json())
+          .then(({ token }) => { document.querySelector("#network-status").textContent = "Ping completed: " + token; });
+      `,
+    });
+  },
+};

evals/browser/fixtures/pages/form.fixture.mjs

@@ -0,0 +1,25 @@
+import { escapeHtml, page } from "../../lib/fixtures.mjs";
+
+export default {
+  id: "form",
+  routes: ["/form", "/result"],
+  render({ pathname, runId, query, record }) {
+    if (pathname === "/form") {
+      return page({
+        title: "Browser Eval Form",
+        body: `<section class="card"><h1>Web form</h1><form action="/result" method="get"><input type="hidden" name="run" value="${escapeHtml(runId)}"><label>Text input<input id="text-input" name="text" autocomplete="off"></label><label>Textarea<textarea id="notes" name="notes"></textarea></label><label>Dropdown<select id="choice" name="choice"><option value="one">One</option><option value="two">Two</option><option value="three">Three</option></select></label><button id="submit" type="submit">Submit</button></form></section>`,
+        script: `document.querySelector("#submit").addEventListener("keydown", (event) => { if (event.key === "Enter") browserEval.send("form.enter_pressed"); });`,
+      });
+    }
+    const values = {
+      text: query.get("text") ?? "",
+      notes: query.get("notes") ?? "",
+      choice: query.get("choice") ?? "",
+    };
+    record("form.submitted", values, { path: pathname });
+    return page({
+      title: "Form Result",
+      body: `<section class="card"><h1>Received!</h1><p id="submitted-values" class="marker">${escapeHtml(values.text)} | ${escapeHtml(values.notes)} | ${escapeHtml(values.choice)}</p></section>`,
+    });
+  },
+};

evals/browser/fixtures/pages/generated-form.fixture.mjs

@@ -0,0 +1,71 @@
+import { escapeHtml, page } from "../../lib/fixtures.mjs";
+import { describeSeed } from "../../lib/seeded-generator.mjs";
+
+function nest(content, depth) {
+  let nested = content;
+  for (let index = 0; index < depth; index += 1) {
+    nested = `<div data-depth="${index + 1}">${nested}</div>`;
+  }
+  return nested;
+}
+
+function textField(dimensions) {
+  const id = `matrix-text-${dimensions.idSuffix}`;
+  const input = `<input id="${id}" name="text" autocomplete="off">`;
+  if (dimensions.labelMode === "wrapped") return `<label>Text input${input}</label>`;
+  if (dimensions.labelMode === "for") return `<label for="${id}">Text input</label>${input}`;
+  return `<span id="${id}-label">Text input</span><input id="${id}" name="text" aria-labelledby="${id}-label" autocomplete="off">`;
+}
+
+function formMarkup(dimensions, runId) {
+  const text = textField(dimensions);
+  const select = `<label>Dropdown<select name="choice"><option value="one">One</option><option value="two">Two</option><option value="three">Three</option></select></label>`;
+  const fields = dimensions.fieldOrder === "text-first" ? `${text}${select}` : `${select}${text}`;
+  const decoy =
+    dimensions.decoy === "disabled-input"
+      ? `<label>Text input<input disabled value="decoy"></label>`
+      : dimensions.decoy === "duplicate-text"
+        ? `<p class="muted">Text input is intentionally repeated in helper copy.</p>`
+        : "";
+  return nest(
+    `<form action="/matrix/generated-result" method="get"><input type="hidden" name="run" value="${escapeHtml(runId)}"><input type="hidden" name="seed" value="${dimensions.seed}">${decoy}${fields}<button type="submit">Submit matrix form</button></form>`,
+    dimensions.nestingDepth,
+  );
+}
+
+export default {
+  id: "generated-form",
+  routes: ["/matrix/generated-form", "/matrix/generated-result"],
+  render({ pathname, runId, query, record }) {
+    const dimensions = describeSeed(query.get("seed") ?? 1);
+    if (pathname === "/matrix/generated-form") {
+      const markup = JSON.stringify(formMarkup(dimensions, runId));
+      const dimensionsJson = JSON.stringify(dimensions);
+      return page({
+        title: "Seeded Matrix Form",
+        body: `<section class="card"><h1>Seeded Matrix Form</h1><p class="marker">SEED-${dimensions.seed}</p><div id="matrix-root">Hydrating…</div></section>`,
+        script: `
+          const hydrate = () => {
+            const root = document.querySelector("#matrix-root");
+            root.innerHTML = ${markup};
+            root.querySelector("button[type=submit]").addEventListener("keydown", (event) => {
+              if (event.key === "Enter") browserEval.send("matrix.enter_pressed");
+            });
+            browserEval.send("matrix.ready", ${dimensionsJson});
+          };
+          setTimeout(hydrate, ${dimensions.hydrationDelayMs});
+        `,
+      });
+    }
+    const values = {
+      seed: dimensions.seed,
+      text: query.get("text") ?? "",
+      choice: query.get("choice") ?? "",
+    };
+    record("matrix.submitted", values, { path: pathname });
+    return page({
+      title: "Matrix Result",
+      body: `<section class="card"><h1>Matrix Result</h1><p class="marker">MATRIX-OK</p><p>${escapeHtml(values.text)} | ${escapeHtml(values.choice)} | seed ${values.seed}</p></section>`,
+    });
+  },
+};

evals/browser/fixtures/pages/hover-inspect.fixture.mjs

@@ -0,0 +1,17 @@
+import { page } from "../../lib/fixtures.mjs";
+
+export default {
+  id: "hover-inspect",
+  routes: ["/hover-inspect"],
+  render() {
+    return page({
+      title: "Hover and Inspect",
+      body: `<section class="card"><h1>Hover and Inspect</h1><div id="account-menu" tabindex="0"><button id="account-button" type="button">Account</button><div id="hover-panel"><button id="profile-link" type="button">Profile beta</button></div></div><p id="hover-result" class="marker" hidden>HOVER-17</p><article id="inspect-card" class="card" data-build="2026.08" data-marker="INSPECT-27"><h2>Inspection card</h2><p>Local HTML marker: <code>INSPECT-27</code></p></article></section>`,
+      script: `
+        const menu = document.querySelector("#account-menu");
+        menu.addEventListener("mouseenter", () => { menu.classList.add("open"); browserEval.send("hover.menu_opened"); });
+        document.querySelector("#profile-link").addEventListener("click", () => { document.querySelector("#hover-result").hidden = false; browserEval.send("hover.profile_clicked"); });
+      `,
+    });
+  },
+};

evals/browser/fixtures/pages/index.fixture.mjs

@@ -0,0 +1,12 @@
+import { page } from "../../lib/fixtures.mjs";
+
+export default {
+  id: "fixture-index",
+  routes: ["/"],
+  render() {
+    return page({
+      title: "Browser Eval Fixtures",
+      body: `<section class="card"><h1>Browser Eval Fixtures</h1><p class="muted">Deterministic local pages for agent-neutral browser evaluation.</p></section>`,
+    });
+  },
+};

evals/browser/fixtures/pages/navigation.fixture.mjs

@@ -0,0 +1,19 @@
+import { page, withRun } from "../../lib/fixtures.mjs";
+
+export default {
+  id: "navigation",
+  routes: ["/navigation/start", "/navigation/detail"],
+  render({ pathname, runId }) {
+    if (pathname === "/navigation/start") {
+      return page({
+        title: "Navigation Start",
+        body: `<section class="card"><h1>Navigation Start</h1><p>Use the link to open the deterministic detail page.</p><a id="details-link" class="button" href="${withRun("/navigation/detail", runId)}">Details</a></section>`,
+        script: `document.querySelector("#details-link").addEventListener("click", () => browserEval.send("navigation.detail.clicked"));`,
+      });
+    }
+    return page({
+      title: "Navigation Detail",
+      body: `<section class="card"><h1>Navigation Detail</h1><p>Stable detail code:</p><p id="navigation-code" class="marker">NAV-42</p></section>`,
+    });
+  },
+};

evals/browser/fixtures/pages/responsive.fixture.mjs

@@ -0,0 +1,21 @@
+import { page } from "../../lib/fixtures.mjs";
+
+export default {
+  id: "responsive",
+  routes: ["/responsive"],
+  render() {
+    return page({
+      title: "Responsive Lab",
+      body: `<section class="card"><h1>Responsive Lab</h1><p id="viewport-marker" class="marker">VIEWPORT-84</p><p id="viewport-value"></p></section>`,
+      script: `
+        const sample = () => {
+          const data = { width: innerWidth, height: innerHeight, touchPoints: navigator.maxTouchPoints, userAgent: navigator.userAgent };
+          document.querySelector("#viewport-value").textContent = data.width + "x" + data.height;
+          browserEval.send("viewport.sample", data);
+        };
+        window.addEventListener("resize", sample);
+        sample();
+      `,
+    });
+  },
+};

evals/browser/fixtures/pages/tabs.fixture.mjs

@@ -0,0 +1,19 @@
+import { escapeHtml, page, withRun } from "../../lib/fixtures.mjs";
+
+export default {
+  id: "tabs",
+  routes: ["/tabs", "/tabs/child"],
+  render({ pathname, runId }) {
+    if (pathname === "/tabs") {
+      return page({
+        title: "Tab Lab",
+        body: `<section class="card"><h1>Tab Lab</h1><p>Keep this original tab open while visiting the child page in a new tab.</p><p class="muted">Child URL: <code>${escapeHtml(withRun("/tabs/child", runId))}</code></p></section>`,
+      });
+    }
+    return page({
+      title: "Child Tab",
+      body: `<section class="card"><h1>Child Tab</h1><p id="tab-token" class="marker">TAB-29</p><button id="mark-child" type="button">Mark child visited</button><p id="child-status" hidden>Marked</p></section>`,
+      script: `document.querySelector("#mark-child").addEventListener("click", () => { document.querySelector("#child-status").hidden = false; browserEval.send("tabs.child_marked"); });`,
+    });
+  },
+};

evals/browser/lib/agent-runner.mjs

@@ -0,0 +1,99 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+import { verifyTask } from "./oracle.mjs";
+import { countPattern, runProcess, substituteArgs } from "./process.mjs";
+import { renderPrompt } from "./tasks.mjs";
+
+function safeRunPart(value) {
+  return value.replaceAll(/[^A-Za-z0-9._-]/g, "-").slice(0, 48);
+}
+
+export async function loadAgentConfig(configPath, agentName) {
+  const absolute = resolve(configPath);
+  const config = JSON.parse(await readFile(absolute, "utf8"));
+  const adapter = config.agents?.[agentName];
+  if (!adapter) {
+    const names = Object.keys(config.agents ?? {}).join(", ");
+    throw new Error(`unknown agent ${JSON.stringify(agentName)}; configured agents: ${names}`);
+  }
+  if (typeof adapter.command !== "string" || !Array.isArray(adapter.args)) {
+    throw new Error(`agent ${JSON.stringify(agentName)} must define command and args`);
+  }
+  return { adapter, configDirectory: dirname(absolute) };
+}
+
+export async function runCommandTask({
+  server,
+  serverInfo,
+  task,
+  adapter,
+  adapterName,
+  configDirectory,
+  iteration,
+  locale,
+  seed = task.seed,
+  timeoutMs,
+  variantOverride,
+}) {
+  const variant = variantOverride ?? adapter.variant ?? "unspecified";
+  const runId = [
+    safeRunPart(adapterName),
+    safeRunPart(variant),
+    safeRunPart(task.id),
+    iteration,
+    randomUUID().slice(0, 8),
+  ].join("-");
+  server.reset(runId);
+  const prompt = renderPrompt(task, { baseUrl: serverInfo.baseUrl, runId, locale, seed });
+  const values = {
+    prompt,
+    caseId: task.id,
+    taskId: task.id,
+    runId,
+    baseUrl: serverInfo.baseUrl,
+    seed: seed ?? "",
+    variant,
+  };
+  const args = substituteArgs(adapter.args, values);
+  const execution = await runProcess(adapter.command, args, {
+    cwd: adapter.cwd ? resolve(configDirectory, adapter.cwd) : configDirectory,
+    env: adapter.env,
+    timeoutMs: adapter.timeoutMs ?? timeoutMs,
+  });
+
+  await new Promise((resolveDelay) => setTimeout(resolveDelay, 250));
+  const responseText = execution.stdout;
+  const combinedOutput = `${execution.stdout}\n${execution.stderr}`;
+  const verification = verifyTask(task, {
+    events: server.snapshot(runId).events,
+    responseText,
+  });
+  const defaultErrorPattern = "(?:\\bError:|timed out|unfinished command|session already has)";
+  return {
+    runId,
+    caseId: task.id,
+    taskId: task.id,
+    suite: task.suite,
+    tags: task.tags,
+    seed,
+    iteration,
+    adapter: adapterName,
+    variant,
+    adapterMetadata: adapter.metadata ?? {},
+    locale,
+    prompt,
+    execution,
+    metrics: {
+      errorCount: countPattern(
+        combinedOutput,
+        adapter.metrics?.errorPattern ?? defaultErrorPattern,
+      ),
+      toolCallCount: countPattern(combinedOutput, adapter.metrics?.toolCallPattern),
+      responseChars: responseText.length,
+    },
+    eventCount: server.snapshot(runId).events.length,
+    verification,
+  };
+}

evals/browser/lib/bsk-runner.mjs

@@ -0,0 +1,309 @@
+import { mkdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import { verifyTask } from "./oracle.mjs";
+import { runProcess } from "./process.mjs";
+import { taskUrl } from "./tasks.mjs";
+
+function parseJsonOutput(step) {
+  try {
+    return JSON.parse(step.stdout);
+  } catch (error) {
+    throw new Error(`could not parse bsk JSON output: ${error.message}`);
+  }
+}
+
+function renderStepError(step) {
+  const raw = step.stderr.trim() || step.stdout.trim();
+  if (!raw) return `exit ${step.exitCode}`;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed.hint ? `${parsed.message} (hint: ${parsed.hint})` : parsed.message;
+  } catch {
+    return raw;
+  }
+}
+
+async function hasNonemptyFile(path) {
+  try {
+    return (await stat(path)).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+function readPath(value, path) {
+  return path.split(".").reduce((current, part) => current?.[part], value);
+}
+
+function resolveValue(value, variables) {
+  if (typeof value !== "string") return value;
+  const exact = value.match(/^\{([^{}]+)}$/);
+  if (exact) {
+    const resolved = readPath(variables, exact[1]);
+    if (resolved === undefined) throw new Error(`unknown workflow variable ${exact[1]}`);
+    return resolved;
+  }
+  return value.replaceAll(/\{([^{}]+)\}/g, (_match, path) => {
+    const resolved = readPath(variables, path);
+    if (resolved === undefined) throw new Error(`unknown workflow variable ${path}`);
+    return String(resolved);
+  });
+}
+
+function targetArgs(step, variables) {
+  if (step.selector) return ["--selector", String(resolveValue(step.selector, variables))];
+  if (step.ref) return ["--ref", String(resolveValue(step.ref, variables))];
+  return [];
+}
+
+function tabArgs(step, variables) {
+  return step.tabId === undefined ? [] : ["--tab-id", String(resolveValue(step.tabId, variables))];
+}
+
+function matchesWhere(value, where = {}) {
+  return Object.entries(where).every(([path, expected]) => readPath(value, path) === expected);
+}
+
+export async function runBskSmokeTask({
+  bskCommand,
+  outputDirectory,
+  server,
+  serverInfo,
+  task,
+  runId,
+  seed = task.seed,
+  timeoutMs = 60_000,
+}) {
+  const steps = [];
+  const evidence = {};
+  const variables = {
+    baseUrl: serverInfo.baseUrl,
+    runId,
+    seed: seed ?? "",
+    url: taskUrl(task, serverInfo.baseUrl, runId, seed),
+  };
+  let sessionId;
+  let executionError;
+  await mkdir(outputDirectory, { recursive: true });
+
+  async function bsk(args, { timeout = timeoutMs } = {}) {
+    const execution = await runProcess(bskCommand, [...args, "--json"], { timeoutMs: timeout });
+    steps.push(execution);
+    if (execution.exitCode !== 0 || execution.timedOut || execution.error) {
+      throw new Error(
+        `bsk ${args.join(" ")} failed: ${execution.error ?? renderStepError(execution)}`,
+      );
+    }
+    return parseJsonOutput(execution);
+  }
+
+  async function waitForSiteEvent(step) {
+    const timeout = step.timeoutMs ?? 3_000;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      if (
+        server
+          .snapshot(runId)
+          .events.some(
+            (event) => event.type === step.type && matchesWhere(event.data ?? {}, step.where ?? {}),
+          )
+      ) {
+        return { observed: true };
+      }
+      await new Promise((resolveDelay) => setTimeout(resolveDelay, 50));
+    }
+    throw new Error(`local fixture did not report ${step.type} within ${timeout}ms`);
+  }
+
+  async function executeWorkflowStep(step) {
+    const session = ["--session", sessionId];
+    let result;
+    switch (step.action) {
+      case "navigate":
+        result = await bsk([
+          "navigate",
+          String(resolveValue(step.url ?? "{url}", variables)),
+          ...session,
+          ...tabArgs(step, variables),
+        ]);
+        break;
+      case "back":
+      case "forward":
+        result = await bsk([`navigate-${step.action}`, ...session, ...tabArgs(step, variables)]);
+        break;
+      case "reload":
+        result = await bsk(["reload", ...session, ...tabArgs(step, variables)]);
+        break;
+      case "wait":
+        result = await bsk(["wait-ms", String(resolveValue(step.duration, variables))]);
+        break;
+      case "wait-site-event":
+        result = await waitForSiteEvent(step);
+        break;
+      case "observe":
+      case "snapshot":
+      case "html": {
+        const command = step.action === "html" ? "get-html" : step.action;
+        result = await bsk([command, ...session, ...tabArgs(step, variables)]);
+        break;
+      }
+      case "screenshot": {
+        const name = resolveValue(step.artifactName ?? "screenshot.png", variables);
+        const path = join(outputDirectory, `${runId}-${name}`);
+        result = await bsk(["screenshot", ...session, ...tabArgs(step, variables), "--out", path]);
+        if (step.evidence) evidence[step.evidence] = await hasNonemptyFile(path);
+        break;
+      }
+      case "console":
+      case "network":
+        result = await bsk([step.action, ...session, ...tabArgs(step, variables)]);
+        break;
+      case "click":
+      case "hover":
+        result = await bsk([
+          step.action,
+          ...targetArgs(step, variables),
+          ...session,
+          ...tabArgs(step, variables),
+        ]);
+        break;
+      case "fill":
+        result = await bsk([
+          "fill",
+          ...targetArgs(step, variables),
+          "--value",
+          String(resolveValue(step.value, variables)),
+          ...session,
+          ...tabArgs(step, variables),
+        ]);
+        break;
+      case "select":
+        result = await bsk([
+          "select",
+          ...targetArgs(step, variables),
+          ...step.values.flatMap((value) => ["--value", String(resolveValue(value, variables))]),
+          ...session,
+          ...tabArgs(step, variables),
+        ]);
+        break;
+      case "press":
+        result = await bsk([
+          "press",
+          String(resolveValue(step.key, variables)),
+          ...targetArgs(step, variables),
+          ...session,
+          ...tabArgs(step, variables),
+        ]);
+        break;
+      case "tab-list":
+        result = await bsk(["tab", "list", ...session]);
+        break;
+      case "tab-create":
+        result = await bsk([
+          "tab",
+          "create",
+          ...session,
+          ...(step.url ? ["--url", String(resolveValue(step.url, variables))] : []),
+        ]);
+        break;
+      case "tab-select":
+      case "tab-close":
+        result = await bsk([
+          "tab",
+          step.action.slice(4),
+          String(resolveValue(step.tabId, variables)),
+          ...session,
+        ]);
+        break;
+      case "borrow":
+      case "return":
+        result = await bsk([
+          "tab",
+          step.action,
+          String(resolveValue(step.tabId, variables)),
+          ...session,
+        ]);
+        break;
+      case "resize":
+        result = await bsk([
+          "window",
+          "resize",
+          ...session,
+          "--width",
+          String(step.width),
+          "--height",
+          String(step.height),
+        ]);
+        break;
+      case "emulate":
+        result = await bsk([
+          "emulate",
+          ...session,
+          ...tabArgs(step, variables),
+          "--device",
+          String(resolveValue(step.device, variables)),
+        ]);
+        break;
+      case "request-help":
+        result = await bsk([
+          "request-help",
+          ...session,
+          "--prompt",
+          String(resolveValue(step.prompt, variables)),
+          ...(step.title ? ["--title", String(resolveValue(step.title, variables))] : []),
+          ...(step.timeout ? ["--timeout", String(step.timeout)] : []),
+        ]);
+        break;
+      default:
+        throw new Error(`unsupported smoke workflow action ${step.action}`);
+    }
+    if (step.saveAs) variables[step.saveAs] = result;
+    if (step.evidence && step.action !== "screenshot") evidence[step.evidence] = true;
+  }
+
+  server.reset(runId);
+  try {
+    if (task.smokeSteps.length === 0) throw new Error(`case ${task.id} has no smoke workflow`);
+    const started = await bsk(["session", "start", "--no-focus"], { timeout: 90_000 });
+    sessionId = started.session_id;
+    variables.sessionId = sessionId;
+    await bsk(["session", "list"]);
+    for (const step of task.smokeSteps) await executeWorkflowStep(step);
+  } catch (error) {
+    executionError = error instanceof Error ? error.message : String(error);
+  } finally {
+    if (sessionId) {
+      try {
+        const stopped = await bsk(["session", "stop", sessionId], { timeout: 90_000 });
+        evidence.sessionStopped =
+          stopped.stopped?.includes(sessionId) === true && (stopped.failed?.length ?? 0) === 0;
+        if (!evidence.sessionStopped) {
+          executionError ??= `bsk did not confirm that session ${sessionId} stopped`;
+        }
+      } catch (error) {
+        evidence.sessionStopped = false;
+        executionError ??= error instanceof Error ? error.message : String(error);
+      }
+    }
+  }
+
+  await new Promise((resolveDelay) => setTimeout(resolveDelay, 350));
+  const responseText = steps.map(({ stdout }) => stdout).join("\n");
+  const events = server.snapshot(runId).events;
+  return {
+    runId,
+    caseId: task.id,
+    taskId: task.id,
+    suite: task.suite,
+    tags: task.tags,
+    seed,
+    adapter: "bsk-direct",
+    variant: "cli-direct",
+    executionError,
+    steps,
+    evidence,
+    eventCount: events.length,
+    verification: verifyTask(task, { events, responseText, adapterEvidence: evidence }),
+  };
+}

evals/browser/lib/case-loader.mjs

@@ -0,0 +1,216 @@
+import { readFile } from "node:fs/promises";
+
+import { discoverFiles } from "./discovery.mjs";
+import { OPERATION_NAMES, WORKFLOW_ACTIONS } from "./operations.mjs";
+import { casesDirectory as defaultCasesDirectory } from "./paths.mjs";
+
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const EVIDENCE_PATTERN = /^[A-Za-z][A-Za-z0-9]*$/;
+const TOP_LEVEL_KEYS = new Set([
+  "$schema",
+  "schemaVersion",
+  "id",
+  "title",
+  "order",
+  "suite",
+  "tags",
+  "seed",
+  "source",
+  "fixture",
+  "prompts",
+  "coverage",
+  "assertions",
+  "smoke",
+]);
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function checkString(errors, value, path) {
+  if (typeof value !== "string" || value.trim() === "") errors.push(`${path} must be a string`);
+}
+
+function validateAssertion(errors, assertion, path, kind) {
+  if (!isObject(assertion)) {
+    errors.push(`${path} must be an object`);
+    return;
+  }
+  checkString(errors, assertion.label, `${path}.label`);
+  if (kind === "site") {
+    checkString(errors, assertion.type, `${path}.type`);
+    if (!Number.isInteger(assertion.minCount) || assertion.minCount < 1) {
+      errors.push(`${path}.minCount must be a positive integer`);
+    }
+    if (assertion.where !== undefined && !isObject(assertion.where)) {
+      errors.push(`${path}.where must be an object`);
+    }
+  } else if (kind === "response") {
+    checkString(errors, assertion.includes, `${path}.includes`);
+  } else {
+    checkString(errors, assertion.key, `${path}.key`);
+  }
+}
+
+function validateWorkflowStep(errors, step, path) {
+  if (!isObject(step)) {
+    errors.push(`${path} must be an object`);
+    return;
+  }
+  if (!WORKFLOW_ACTIONS.has(step.action)) {
+    errors.push(`${path}.action is unsupported: ${JSON.stringify(step.action)}`);
+  }
+  if (step.saveAs !== undefined && !ID_PATTERN.test(step.saveAs)) {
+    errors.push(`${path}.saveAs must use lowercase kebab-case`);
+  }
+  if (step.evidence !== undefined && !EVIDENCE_PATTERN.test(step.evidence)) {
+    errors.push(`${path}.evidence must be an identifier`);
+  }
+  if (["click", "hover", "fill", "select"].includes(step.action) && !step.selector && !step.ref) {
+    errors.push(`${path} requires selector or ref`);
+  }
+  if (step.action === "fill") checkString(errors, step.value, `${path}.value`);
+  if (step.action === "select") {
+    if (!Array.isArray(step.values) || step.values.length === 0) {
+      errors.push(`${path}.values must be a non-empty array`);
+    } else if (step.values.some((value) => typeof value !== "string")) {
+      errors.push(`${path}.values must contain only strings`);
+    }
+  }
+  if (step.action === "press") checkString(errors, step.key, `${path}.key`);
+  if (step.action === "wait") checkString(errors, step.duration, `${path}.duration`);
+  if (step.action === "wait-site-event") checkString(errors, step.type, `${path}.type`);
+  if (["tab-select", "tab-close", "borrow", "return"].includes(step.action)) {
+    checkString(errors, step.tabId, `${path}.tabId`);
+  }
+  if (step.action === "resize") {
+    if (
+      !Number.isInteger(step.width) ||
+      step.width < 1 ||
+      !Number.isInteger(step.height) ||
+      step.height < 1
+    ) {
+      errors.push(`${path}.width and height must be positive integers`);
+    }
+  }
+  if (step.action === "emulate") checkString(errors, step.device, `${path}.device`);
+  if (step.action === "request-help") checkString(errors, step.prompt, `${path}.prompt`);
+  if (step.timeoutMs !== undefined && (!Number.isInteger(step.timeoutMs) || step.timeoutMs < 1)) {
+    errors.push(`${path}.timeoutMs must be a positive integer`);
+  }
+}
+
+export function validateCaseManifest(manifest, { source = "case manifest" } = {}) {
+  const errors = [];
+  if (!isObject(manifest)) return [`${source} must contain a JSON object`];
+  for (const key of Object.keys(manifest)) {
+    if (!TOP_LEVEL_KEYS.has(key)) errors.push(`unknown top-level property ${key}`);
+  }
+  if (manifest.schemaVersion !== 1) errors.push("schemaVersion must equal 1");
+  if (!ID_PATTERN.test(manifest.id ?? "")) errors.push("id must use lowercase kebab-case");
+  checkString(errors, manifest.title, "title");
+  if (manifest.order !== undefined && (!Number.isInteger(manifest.order) || manifest.order < 0)) {
+    errors.push("order must be a non-negative integer");
+  }
+  if (!ID_PATTERN.test(manifest.suite ?? "")) errors.push("suite must use lowercase kebab-case");
+  if (!Array.isArray(manifest.tags) || manifest.tags.some((tag) => !ID_PATTERN.test(tag))) {
+    errors.push("tags must be an array of lowercase kebab-case strings");
+  } else if (new Set(manifest.tags).size !== manifest.tags.length) {
+    errors.push("tags must not contain duplicates");
+  }
+  if (!isObject(manifest.fixture)) errors.push("fixture must be an object");
+  else if (
+    typeof manifest.fixture.startPath !== "string" ||
+    !manifest.fixture.startPath.startsWith("/")
+  ) {
+    errors.push("fixture.startPath must be an absolute URL path");
+  }
+  if (!isObject(manifest.prompts)) errors.push("prompts must be an object");
+  else {
+    checkString(errors, manifest.prompts.en, "prompts.en");
+    checkString(errors, manifest.prompts["zh-CN"], "prompts.zh-CN");
+  }
+  if (!Array.isArray(manifest.coverage)) errors.push("coverage must be an array");
+  else {
+    for (const operation of manifest.coverage) {
+      if (!OPERATION_NAMES.has(operation))
+        errors.push(`coverage contains unknown operation ${operation}`);
+    }
+    if (new Set(manifest.coverage).size !== manifest.coverage.length) {
+      errors.push("coverage must not contain duplicates");
+    }
+  }
+  if (!isObject(manifest.assertions)) errors.push("assertions must be an object");
+  else {
+    for (const kind of ["site", "response", "adapter"]) {
+      if (!Array.isArray(manifest.assertions[kind])) {
+        errors.push(`assertions.${kind} must be an array`);
+      } else {
+        manifest.assertions[kind].forEach((assertion, index) =>
+          validateAssertion(errors, assertion, `assertions.${kind}[${index}]`, kind),
+        );
+      }
+    }
+  }
+  if (!isObject(manifest.smoke) || !Array.isArray(manifest.smoke.steps)) {
+    errors.push("smoke.steps must be an array");
+  } else {
+    manifest.smoke.steps.forEach((step, index) =>
+      validateWorkflowStep(errors, step, `smoke.steps[${index}]`),
+    );
+  }
+  if (manifest.seed !== undefined && !Number.isSafeInteger(manifest.seed)) {
+    errors.push("seed must be a safe integer");
+  }
+  if (manifest.source !== undefined && !isObject(manifest.source)) {
+    errors.push("source must be an object");
+  }
+  return errors.map((error) => `${source}: ${error}`);
+}
+
+function normalizeCase(manifest, sourceFile) {
+  return Object.freeze({
+    ...manifest,
+    startPath: manifest.fixture.startPath,
+    siteAssertions: manifest.assertions.site,
+    responseAssertions: manifest.assertions.response,
+    adapterAssertions: manifest.assertions.adapter,
+    smokeSteps: manifest.smoke.steps,
+    sourceFile,
+  });
+}
+
+export async function loadCaseManifests({ casesDirectory = defaultCasesDirectory } = {}) {
+  const files = await discoverFiles(casesDirectory, (path) => path.endsWith(".case.json"));
+  const cases = [];
+  const ids = new Map();
+  const errors = [];
+  for (const file of files) {
+    let manifest;
+    try {
+      manifest = JSON.parse(await readFile(file, "utf8"));
+    } catch (error) {
+      errors.push(`${file}: invalid JSON: ${error.message}`);
+      continue;
+    }
+    const manifestErrors = validateCaseManifest(manifest, { source: file });
+    errors.push(...manifestErrors);
+    if (typeof manifest?.id === "string") {
+      if (ids.has(manifest.id)) {
+        errors.push(`${file}: duplicate id also declared by ${ids.get(manifest.id)}`);
+      } else {
+        ids.set(manifest.id, file);
+      }
+    }
+    if (manifestErrors.length === 0) cases.push(normalizeCase(manifest, file));
+  }
+  if (files.length === 0) errors.push(`${casesDirectory}: no .case.json files found`);
+  if (errors.length > 0) throw new Error(`case validation failed:\n${errors.join("\n")}`);
+  cases.sort(
+    (left, right) =>
+      left.suite.localeCompare(right.suite) ||
+      (left.order ?? Number.MAX_SAFE_INTEGER) - (right.order ?? Number.MAX_SAFE_INTEGER) ||
+      left.id.localeCompare(right.id),
+  );
+  return Object.freeze(cases);
+}

evals/browser/lib/coverage.mjs

@@ -0,0 +1,26 @@
+import { OPERATION_CATALOG, WORKFLOW_ACTION_OPERATIONS } from "./operations.mjs";
+
+export function buildOperationCoverage(cases) {
+  return OPERATION_CATALOG.map(({ operation, manualNote }) => {
+    const agentCases = cases
+      .filter((testCase) => testCase.coverage.includes(operation))
+      .map(({ id }) => id);
+    let smokeCases;
+    if (["session.start", "session.stop", "session.list"].includes(operation)) {
+      smokeCases = cases.filter(({ smokeSteps }) => smokeSteps.length > 0).map(({ id }) => id);
+    } else {
+      smokeCases = cases
+        .filter(({ smokeSteps }) =>
+          smokeSteps.some((step) => WORKFLOW_ACTION_OPERATIONS[step.action] === operation),
+        )
+        .map(({ id }) => id);
+    }
+    return {
+      operation,
+      agentCases,
+      smokeCases,
+      directSmoke: smokeCases.length > 0,
+      note: smokeCases.length === 0 && manualNote ? `manual lane: ${manualNote}` : undefined,
+    };
+  });
+}

evals/browser/lib/discovery.mjs

@@ -0,0 +1,24 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function discoverFiles(root, predicate) {
+  const files = [];
+
+  async function visit(directory) {
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw error;
+    }
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) await visit(path);
+      else if (entry.isFile() && predicate(path)) files.push(path);
+    }
+  }
+
+  await visit(root);
+  return files;
+}

evals/browser/lib/fixture-registry.mjs

@@ -0,0 +1,68 @@
+import { pathToFileURL } from "node:url";
+
+import { discoverFiles } from "./discovery.mjs";
+import { casesDirectory, fixturesDirectory } from "./paths.mjs";
+
+export async function loadFixtureRegistry({ roots = [fixturesDirectory, casesDirectory] } = {}) {
+  const files = (
+    await Promise.all(
+      roots.map((root) => discoverFiles(root, (path) => path.endsWith(".fixture.mjs"))),
+    )
+  ).flat();
+  const routes = new Map();
+  const definitions = [];
+  const errors = [];
+
+  for (const file of files.sort()) {
+    let definition;
+    try {
+      definition = (await import(pathToFileURL(file).href)).default;
+    } catch (error) {
+      errors.push(`${file}: could not import fixture: ${error.message}`);
+      continue;
+    }
+    if (!definition || typeof definition.id !== "string") {
+      errors.push(`${file}: default export must define id`);
+      continue;
+    }
+    if (!Array.isArray(definition.routes) || definition.routes.length === 0) {
+      errors.push(`${file}: default export must define non-empty routes`);
+      continue;
+    }
+    if (typeof definition.render !== "function") {
+      errors.push(`${file}: default export must define render(context)`);
+      continue;
+    }
+    definitions.push({ ...definition, sourceFile: file });
+    for (const route of definition.routes) {
+      if (typeof route !== "string" || !route.startsWith("/")) {
+        errors.push(`${file}: invalid route ${JSON.stringify(route)}`);
+      } else if (routes.has(route)) {
+        errors.push(
+          `${file}: route ${route} is already registered by ${routes.get(route).sourceFile}`,
+        );
+      } else {
+        routes.set(route, { definition, sourceFile: file });
+      }
+    }
+  }
+
+  if (errors.length > 0) throw new Error(`fixture validation failed:\n${errors.join("\n")}`);
+  return Object.freeze({
+    definitions: Object.freeze(definitions),
+    routes: Object.freeze([...routes.keys()].sort()),
+    hasRoute(pathname) {
+      return routes.has(pathname);
+    },
+    render(pathname, context) {
+      const entry = routes.get(pathname);
+      return entry ? entry.definition.render({ ...context, pathname }) : null;
+    },
+  });
+}
+
+export function validateCaseFixtureLinks(cases, fixtureRegistry) {
+  return cases
+    .filter(({ startPath }) => !fixtureRegistry.hasRoute(startPath))
+    .map(({ id, startPath }) => `case ${id} references unregistered fixture route ${startPath}`);
+}

evals/browser/lib/fixtures.mjs

@@ -0,0 +1,78 @@
+const stylesheet = `
+:root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
+body { margin: 0; background: #f4f7fb; color: #182033; }
+main { width: min(760px, calc(100% - 40px)); margin: 48px auto; }
+.card { background: white; border: 1px solid #d9e1ef; border-radius: 14px; padding: 24px; box-shadow: 0 8px 28px #20304a12; }
+h1 { margin-top: 0; }
+a, button { font: inherit; }
+button, .button { display: inline-block; border: 0; border-radius: 8px; padding: 10px 16px; background: #3157d5; color: white; cursor: pointer; text-decoration: none; }
+label { display: block; margin: 16px 0; font-weight: 600; }
+input, textarea, select { display: block; box-sizing: border-box; width: 100%; margin-top: 6px; border: 1px solid #9caac2; border-radius: 7px; padding: 9px; font: inherit; }
+textarea { min-height: 90px; }
+.marker { border-left: 4px solid #3157d5; padding: 8px 12px; background: #eef2ff; font-family: ui-monospace, monospace; }
+.muted { color: #5c667a; }
+#account-menu { position: relative; display: inline-block; padding-bottom: 12px; }
+#hover-panel { display: none; position: absolute; z-index: 2; top: 34px; left: 0; width: 190px; padding: 10px; background: white; border: 1px solid #9caac2; border-radius: 8px; box-shadow: 0 8px 24px #20304a22; }
+#account-menu:hover #hover-panel, #account-menu.open #hover-panel { display: block; }
+#hover-panel button { width: 100%; }
+#inspect-card { margin-top: 80px; }
+code { font-family: ui-monospace, monospace; }
+`;
+
+const clientScript = `
+(() => {
+  const runId = new URLSearchParams(location.search).get("run");
+  const navigation = performance.getEntriesByType("navigation")[0];
+  const send = (type, data = {}) => {
+    if (!runId) return Promise.resolve();
+    return fetch("/api/events", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ runId, type, path: location.pathname, data }),
+      keepalive: true,
+    }).catch(() => undefined);
+  };
+  window.browserEval = { runId, send };
+  window.addEventListener("pageshow", (event) => {
+    send("page.shown", {
+      path: location.pathname,
+      persisted: event.persisted,
+      navigationType: navigation?.type ?? "unknown",
+    });
+  });
+})();
+`;
+
+export function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+export function withRun(path, runId, extra = {}) {
+  const url = new URL(path, "http://browser-eval.local");
+  url.searchParams.set("run", runId);
+  for (const [name, value] of Object.entries(extra)) {
+    if (value !== undefined) url.searchParams.set(name, String(value));
+  }
+  return `${url.pathname}${url.search}`;
+}
+
+export function page({ title, body, script = "" }) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>${escapeHtml(title)}</title>
+  <style>${stylesheet}</style>
+</head>
+<body>
+  <main>${body}</main>
+  <script>${clientScript}</script>
+  ${script ? `<script>${script}</script>` : ""}
+</body>
+</html>`;
+}

evals/browser/lib/operations.mjs

@@ -0,0 +1,68 @@
+export const OPERATION_CATALOG = [
+  { operation: "session.start" },
+  { operation: "session.stop" },
+  { operation: "session.list" },
+  { operation: "page.navigate" },
+  { operation: "page.back" },
+  { operation: "page.forward" },
+  { operation: "page.reload" },
+  { operation: "page.wait" },
+  { operation: "inspect.observe" },
+  { operation: "inspect.snapshot" },
+  { operation: "inspect.html" },
+  { operation: "inspect.screenshot" },
+  { operation: "inspect.console" },
+  { operation: "inspect.network" },
+  { operation: "interact.click" },
+  { operation: "interact.hover" },
+  { operation: "interact.fill" },
+  { operation: "interact.select" },
+  { operation: "interact.press" },
+  { operation: "tabs.list" },
+  { operation: "tabs.create" },
+  { operation: "tabs.select" },
+  { operation: "tabs.close" },
+  {
+    operation: "tabs.borrow",
+    manualNote: "requires an existing user tab and ownership confirmation",
+  },
+  { operation: "tabs.return", manualNote: "paired with borrowing a real user tab" },
+  { operation: "assist.resize" },
+  { operation: "assist.emulate" },
+  { operation: "assist.request-help", manualNote: "intentionally waits for human interaction" },
+];
+
+export const WORKFLOW_ACTION_OPERATIONS = {
+  navigate: "page.navigate",
+  back: "page.back",
+  forward: "page.forward",
+  reload: "page.reload",
+  wait: "page.wait",
+  observe: "inspect.observe",
+  snapshot: "inspect.snapshot",
+  html: "inspect.html",
+  screenshot: "inspect.screenshot",
+  console: "inspect.console",
+  network: "inspect.network",
+  click: "interact.click",
+  hover: "interact.hover",
+  fill: "interact.fill",
+  select: "interact.select",
+  press: "interact.press",
+  "tab-list": "tabs.list",
+  "tab-create": "tabs.create",
+  "tab-select": "tabs.select",
+  "tab-close": "tabs.close",
+  borrow: "tabs.borrow",
+  return: "tabs.return",
+  resize: "assist.resize",
+  emulate: "assist.emulate",
+  "request-help": "assist.request-help",
+};
+
+export const WORKFLOW_ACTIONS = new Set([
+  ...Object.keys(WORKFLOW_ACTION_OPERATIONS),
+  "wait-site-event",
+]);
+
+export const OPERATION_NAMES = new Set(OPERATION_CATALOG.map(({ operation }) => operation));

evals/browser/lib/oracle.mjs

@@ -0,0 +1,63 @@
+function readPath(value, path) {
+  return path.split(".").reduce((current, part) => current?.[part], value);
+}
+
+function eventMatches(event, assertion) {
+  if (event.type !== assertion.type) return false;
+  return Object.entries(assertion.where ?? {}).every(
+    ([path, expected]) => readPath(event, path) === expected,
+  );
+}
+
+export function verifyTask(task, { events = [], responseText = "", adapterEvidence = {} } = {}) {
+  const site = task.siteAssertions.map((assertion) => {
+    const actual = events.filter((event) => eventMatches(event, assertion)).length;
+    return {
+      kind: "site",
+      label: assertion.label,
+      status: actual >= assertion.minCount ? "passed" : "failed",
+      expected: `at least ${assertion.minCount}`,
+      actual,
+    };
+  });
+
+  const response = task.responseAssertions.map((assertion) => ({
+    kind: "response",
+    label: assertion.label,
+    status: responseText.includes(assertion.includes) ? "passed" : "failed",
+    expected: `response includes ${JSON.stringify(assertion.includes)}`,
+  }));
+
+  const adapter = task.adapterAssertions.map((assertion) => {
+    if (!Object.hasOwn(adapterEvidence, assertion.key)) {
+      return {
+        kind: "adapter",
+        label: assertion.label,
+        status: "unverified",
+        expected: assertion.key,
+      };
+    }
+    return {
+      kind: "adapter",
+      label: assertion.label,
+      status: adapterEvidence[assertion.key] ? "passed" : "failed",
+      expected: assertion.key,
+      actual: adapterEvidence[assertion.key],
+    };
+  });
+
+  const checks = [...site, ...response, ...adapter];
+  const failed = checks.filter(({ status }) => status === "failed").length;
+  const unverified = checks.filter(({ status }) => status === "unverified").length;
+  return {
+    taskId: task.id,
+    status: failed > 0 ? "failed" : unverified > 0 ? "passed-with-unverified" : "passed",
+    summary: {
+      passed: checks.length - failed - unverified,
+      failed,
+      unverified,
+      total: checks.length,
+    },
+    checks,
+  };
+}

evals/browser/lib/paths.mjs

@@ -0,0 +1,8 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const evalDirectory = dirname(dirname(fileURLToPath(import.meta.url)));
+export const casesDirectory = join(evalDirectory, "cases");
+export const fixturesDirectory = join(evalDirectory, "fixtures");
+export const schemasDirectory = join(evalDirectory, "schemas");
+export const resultsDirectory = join(evalDirectory, "results");

evals/browser/lib/process.mjs

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+
+const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
+
+function appendCaptured(current, chunk) {
+  if (current.length >= MAX_CAPTURE_BYTES) return current;
+  return `${current}${chunk}`.slice(0, MAX_CAPTURE_BYTES);
+}
+
+export function runProcess(command, args, { cwd, env, timeoutMs = 300_000 } = {}) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    const child = spawn(command, args, {
+      cwd,
+      env: { ...process.env, ...env },
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    child.stdout.on("data", (chunk) => {
+      stdout = appendCaptured(stdout, chunk.toString());
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr = appendCaptured(stderr, chunk.toString());
+    });
+
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 2_000).unref();
+    }, timeoutMs);
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve({
+        command,
+        args,
+        stdout,
+        stderr,
+        timedOut,
+        durationMs: Date.now() - startedAt,
+        ...result,
+      });
+    };
+
+    child.once("error", (error) => finish({ exitCode: null, signal: null, error: error.message }));
+    child.once("close", (exitCode, signal) => finish({ exitCode, signal }));
+  });
+}
+
+export function substituteArgs(args, values) {
+  return args.map((argument) => {
+    let result = argument;
+    for (const [key, value] of Object.entries(values)) {
+      result = result.replaceAll(`{${key}}`, String(value));
+    }
+    return result;
+  });
+}
+
+export function countPattern(text, pattern) {
+  if (!pattern) return null;
+  const matches = text.match(new RegExp(pattern, "g"));
+  return matches?.length ?? 0;
+}

evals/browser/lib/repository-validation.mjs

@@ -0,0 +1,64 @@
+import { relative, sep } from "node:path";
+
+import { validateCaseFixtureLinks } from "./fixture-registry.mjs";
+import { casesDirectory } from "./paths.mjs";
+
+function templateRoots(value) {
+  if (typeof value === "string") {
+    return [...value.matchAll(/\{([^{}]+)\}/g)].map((match) => match[1].split(".")[0]);
+  }
+  if (Array.isArray(value)) return value.flatMap(templateRoots);
+  if (value && typeof value === "object") return Object.values(value).flatMap(templateRoots);
+  return [];
+}
+
+export function validateRepositoryCases(cases, fixtureRegistry) {
+  const errors = [...validateCaseFixtureLinks(cases, fixtureRegistry)];
+  for (const testCase of cases) {
+    const relativePath = relative(casesDirectory, testCase.sourceFile);
+    const suiteDirectory = relativePath.split(sep)[0];
+    if (suiteDirectory !== testCase.suite) {
+      errors.push(
+        `case ${testCase.id} declares suite ${testCase.suite} but is stored under ${suiteDirectory}`,
+      );
+    }
+
+    const availableVariables = new Set(["baseUrl", "runId", "seed", "sessionId", "url"]);
+    const evidence = new Set(["sessionStopped"]);
+    for (const [index, step] of testCase.smokeSteps.entries()) {
+      for (const root of templateRoots(step)) {
+        if (!availableVariables.has(root)) {
+          errors.push(
+            `case ${testCase.id} smoke.steps[${index}] references unavailable variable ${root}`,
+          );
+        }
+      }
+      if (step.saveAs) availableVariables.add(step.saveAs);
+      if (step.evidence) evidence.add(step.evidence);
+    }
+    for (const assertion of testCase.adapterAssertions) {
+      if (!evidence.has(assertion.key)) {
+        errors.push(
+          `case ${testCase.id} expects adapter evidence ${assertion.key} but no smoke step produces it`,
+        );
+      }
+    }
+  }
+  return errors;
+}
+
+export function repositorySummary(cases, fixtureRegistry) {
+  const suites = Object.fromEntries(
+    [...new Set(cases.map(({ suite }) => suite))]
+      .sort()
+      .map((suite) => [suite, cases.filter((testCase) => testCase.suite === suite).length]),
+  );
+  const tags = [...new Set(cases.flatMap(({ tags }) => tags))].sort();
+  return {
+    cases: cases.length,
+    suites,
+    tags: tags.length,
+    fixtureModules: fixtureRegistry.definitions.length,
+    fixtureRoutes: fixtureRegistry.routes.length,
+  };
+}

evals/browser/lib/scaffold-case.mjs

@@ -0,0 +1,120 @@
+import { mkdir, realpath, stat, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+
+import { casesDirectory, evalDirectory } from "./paths.mjs";
+
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function moduleSpecifier(fromDirectory, target) {
+  const path = relative(await realpath(fromDirectory), await realpath(target))
+    .split(sep)
+    .join("/");
+  return path.startsWith(".") ? path : `./${path}`;
+}
+
+export async function scaffoldCase({
+  id,
+  title = id,
+  suite = "regression",
+  source,
+  rootCasesDirectory = casesDirectory,
+}) {
+  if (!ID_PATTERN.test(id ?? "")) throw new Error("case id must use lowercase kebab-case");
+  if (!ID_PATTERN.test(suite ?? "")) throw new Error("suite must use lowercase kebab-case");
+  const directory = join(rootCasesDirectory, suite, id);
+  if (await exists(directory)) throw new Error(`case directory already exists: ${directory}`);
+  await mkdir(directory, { recursive: true });
+
+  const marker = `CASE-${id.toUpperCase().replaceAll("-", "_")}`;
+  const startPath = `/cases/${id}`;
+  const manifest = {
+    $schema: "../../../schemas/case.schema.json",
+    schemaVersion: 1,
+    id,
+    title,
+    order: 10,
+    suite,
+    tags: ["badcase", "regression"],
+    ...(source ? { source: { type: "user-badcase", reference: source } } : {}),
+    fixture: { startPath },
+    prompts: {
+      en: `Open {url}, complete the minimal regression scenario, report ${marker}, and close the browser session.`,
+      "zh-CN": `打开 {url}，完成最小回归场景，报告 ${marker}，最后关闭浏览器会话。`,
+    },
+    coverage: ["session.start", "session.stop", "page.navigate", "inspect.observe"],
+    assertions: {
+      site: [
+        {
+          label: "regression fixture was displayed",
+          type: "page.shown",
+          where: { "data.path": startPath },
+          minCount: 1,
+        },
+      ],
+      response: [{ label: "reported regression marker", includes: marker }],
+      adapter: [{ label: "browser session was closed", key: "sessionStopped" }],
+    },
+    smoke: { steps: [{ action: "navigate" }, { action: "observe" }] },
+  };
+
+  const fixtureHelper = await moduleSpecifier(
+    directory,
+    join(evalDirectory, "lib", "fixtures.mjs"),
+  );
+  const fixture = `import { escapeHtml, page } from ${JSON.stringify(fixtureHelper)};
+
+const title = ${JSON.stringify(title)};
+
+export default {
+  id: ${JSON.stringify(id)},
+  routes: [${JSON.stringify(startPath)}],
+  render() {
+    return page({
+      title,
+      body: \`<section class="card"><h1>\${escapeHtml(title)}</h1><p class="marker">${marker}</p><p>Replace this page with a privacy-safe minimal reproduction.</p></section>\`,
+    });
+  },
+};
+`;
+  const readme = `# ${title}
+
+## Original symptom
+
+Describe what the user observed without including private data or proprietary page content.
+
+## Minimal reproduction
+
+Explain the smallest DOM, timing, or browser-state condition that reproduces the failure.
+
+## Expected behavior
+
+Describe the observable success condition and update the case assertions accordingly.
+
+## Regression history
+
+- Source: ${source ?? "add issue, PR, or anonymized user report reference"}
+- Fix: add the fixing PR when available
+`;
+
+  const files = {
+    manifest: join(directory, `${id}.case.json`),
+    fixture: join(directory, `${id}.fixture.mjs`),
+    readme: join(directory, "README.md"),
+  };
+  await Promise.all([
+    writeFile(files.manifest, `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" }),
+    writeFile(files.fixture, fixture, { flag: "wx" }),
+    writeFile(files.readme, readme, { flag: "wx" }),
+  ]);
+  return { directory, files };
+}

evals/browser/lib/seeded-generator.mjs

@@ -0,0 +1,40 @@
+function hashSeed(value) {
+  const text = String(value);
+  let hash = 2166136261;
+  for (const character of text) {
+    hash ^= character.codePointAt(0);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+function mulberry32(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state += 0x6d2b79f5;
+    let value = state;
+    value = Math.imul(value ^ (value >>> 15), value | 1);
+    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+    return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296;
+  };
+}
+
+export function normalizeSeed(value) {
+  const numeric = Number(value);
+  return Number.isSafeInteger(numeric) ? numeric : hashSeed(value);
+}
+
+export function describeSeed(value) {
+  const seed = normalizeSeed(value);
+  const random = mulberry32(seed);
+  const choose = (values) => values[Math.floor(random() * values.length)];
+  return {
+    seed,
+    labelMode: choose(["wrapped", "for", "aria"]),
+    nestingDepth: 1 + Math.floor(random() * 4),
+    hydrationDelayMs: choose([0, 40, 120, 250]),
+    decoy: choose(["none", "disabled-input", "duplicate-text"]),
+    fieldOrder: choose(["text-first", "select-first"]),
+    idSuffix: hashSeed(`${seed}:id`).toString(36).slice(0, 6),
+  };
+}

evals/browser/lib/server.mjs

@@ -0,0 +1,152 @@
+import { createServer } from "node:http";
+
+import { loadFixtureRegistry } from "./fixture-registry.mjs";
+
+const RUN_ID_PATTERN = /^[A-Za-z0-9._-]{1,120}$/;
+
+function validRunId(value) {
+  return typeof value === "string" && RUN_ID_PATTERN.test(value);
+}
+
+function json(response, status, value) {
+  response.writeHead(status, {
+    "cache-control": "no-store",
+    "content-type": "application/json; charset=utf-8",
+  });
+  response.end(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function html(response, status, value) {
+  response.writeHead(status, {
+    "cache-control": "no-store",
+    "content-type": "text/html; charset=utf-8",
+  });
+  response.end(value);
+}
+
+async function readJson(request) {
+  let raw = "";
+  for await (const chunk of request) {
+    raw += chunk;
+    if (raw.length > 64 * 1024) {
+      throw new Error("request body exceeds 64 KiB");
+    }
+  }
+  return raw ? JSON.parse(raw) : {};
+}
+
+export function createEvalServer({ host = "127.0.0.1", port = 0, fixtureRegistry } = {}) {
+  const runs = new Map();
+  let sequence = 0;
+  let server;
+  let registry = fixtureRegistry;
+
+  function eventsFor(runId) {
+    if (!runs.has(runId)) runs.set(runId, []);
+    return runs.get(runId);
+  }
+
+  function record(runId, type, data = {}, metadata = {}) {
+    if (!validRunId(runId)) return null;
+    const event = {
+      sequence: ++sequence,
+      timestamp: new Date().toISOString(),
+      type,
+      data,
+      ...metadata,
+    };
+    eventsFor(runId).push(event);
+    return event;
+  }
+
+  function snapshot(runId) {
+    return { runId, events: [...(runs.get(runId) ?? [])] };
+  }
+
+  function reset(runId) {
+    runs.set(runId, []);
+  }
+
+  async function handle(request, response) {
+    const origin = `http://${request.headers.host ?? `${host}:${port}`}`;
+    const url = new URL(request.url ?? "/", origin);
+
+    if (request.method === "GET" && url.pathname === "/healthz") {
+      return json(response, 200, { ok: true });
+    }
+
+    if (request.method === "POST" && url.pathname === "/api/events") {
+      const body = await readJson(request);
+      if (!validRunId(body.runId) || typeof body.type !== "string") {
+        return json(response, 400, { error: "runId and type are required" });
+      }
+      const event = record(body.runId, body.type, body.data ?? {}, {
+        path: typeof body.path === "string" ? body.path : undefined,
+      });
+      return json(response, 202, { accepted: true, sequence: event.sequence });
+    }
+
+    const runMatch = url.pathname.match(/^\/api\/runs\/([^/]+)$/);
+    if (runMatch) {
+      const runId = decodeURIComponent(runMatch[1]);
+      if (!validRunId(runId)) return json(response, 400, { error: "invalid run id" });
+      if (request.method === "GET") return json(response, 200, snapshot(runId));
+      if (request.method === "DELETE") {
+        reset(runId);
+        return json(response, 200, { runId, reset: true });
+      }
+    }
+
+    if (request.method === "GET" && url.pathname === "/api/ping") {
+      const runId = url.searchParams.get("run");
+      if (!validRunId(runId)) return json(response, 400, { error: "invalid run id" });
+      record(runId, "network.ping", { token: "NETWORK-73" }, { path: url.pathname });
+      return json(response, 200, { ok: true, token: "NETWORK-73" });
+    }
+
+    if (request.method !== "GET") return json(response, 405, { error: "method not allowed" });
+
+    const runId = url.searchParams.get("run") ?? "manual";
+    if (!validRunId(runId)) return json(response, 400, { error: "invalid run id" });
+
+    const fixture = registry.render(url.pathname, {
+      runId,
+      query: url.searchParams,
+      record: (type, data, metadata) => record(runId, type, data, metadata),
+    });
+    if (!fixture) return html(response, 404, "<!doctype html><h1>Not found</h1>");
+    record(runId, "page.request", { path: url.pathname }, { path: url.pathname });
+    return html(response, 200, fixture);
+  }
+
+  return {
+    record,
+    reset,
+    snapshot,
+    async start() {
+      if (server) throw new Error("eval server is already running");
+      registry ??= await loadFixtureRegistry();
+      server = createServer((request, response) => {
+        handle(request, response).catch((error) => {
+          json(response, 500, { error: error instanceof Error ? error.message : String(error) });
+        });
+      });
+      await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, resolve);
+      });
+      const address = server.address();
+      if (!address || typeof address === "string") throw new Error("unexpected server address");
+      return { host, port: address.port, baseUrl: `http://${host}:${address.port}` };
+    },
+    async stop() {
+      if (!server) return;
+      const active = server;
+      server = undefined;
+      await new Promise((resolve, reject) => {
+        active.close((error) => (error ? reject(error) : resolve()));
+        active.closeAllConnections?.();
+      });
+    },
+  };
+}

evals/browser/lib/summary.mjs

@@ -0,0 +1,73 @@
+function durationFor(result) {
+  if (result.execution?.durationMs !== undefined) return result.execution.durationMs;
+  return (result.steps ?? []).reduce((sum, step) => sum + step.durationMs, 0);
+}
+
+export function summarizeReports(reports) {
+  const groups = new Map();
+  for (const report of reports) {
+    for (const result of report.results ?? []) {
+      const adapter = result.adapter ?? report.adapter ?? "unknown";
+      const variant = result.variant ?? report.variant ?? "unspecified";
+      const key = `${adapter}\u0000${variant}`;
+      if (!groups.has(key)) {
+        groups.set(key, {
+          adapter,
+          variant,
+          runs: 0,
+          passed: 0,
+          fullyVerified: 0,
+          executionFailures: 0,
+          errors: 0,
+          durationMs: 0,
+          toolCalls: 0,
+          toolCallSamples: 0,
+        });
+      }
+      const group = groups.get(key);
+      group.runs += 1;
+      group.durationMs += durationFor(result);
+      group.errors += result.metrics?.errorCount ?? (result.executionError ? 1 : 0);
+      if (result.metrics?.toolCallCount !== null && result.metrics?.toolCallCount !== undefined) {
+        group.toolCalls += result.metrics.toolCallCount;
+        group.toolCallSamples += 1;
+      }
+      const executionFailed =
+        Boolean(result.executionError) ||
+        result.execution?.timedOut ||
+        (result.execution?.exitCode !== undefined && result.execution.exitCode !== 0);
+      if (executionFailed) group.executionFailures += 1;
+      if (result.verification?.status !== "failed" && !executionFailed) group.passed += 1;
+      if (result.verification?.status === "passed" && !executionFailed) group.fullyVerified += 1;
+    }
+  }
+
+  return [...groups.values()].map((group) => ({
+    adapter: group.adapter,
+    variant: group.variant,
+    runs: group.runs,
+    passRate: group.runs ? group.passed / group.runs : 0,
+    fullyVerifiedRate: group.runs ? group.fullyVerified / group.runs : 0,
+    executionFailures: group.executionFailures,
+    errors: group.errors,
+    averageToolCalls: group.toolCallSamples
+      ? Math.round((group.toolCalls / group.toolCallSamples) * 10) / 10
+      : null,
+    averageDurationMs: group.runs ? Math.round(group.durationMs / group.runs) : 0,
+  }));
+}
+
+export function printSummary(rows) {
+  const printable = rows.map((row) => ({
+    adapter: row.adapter,
+    variant: row.variant,
+    runs: row.runs,
+    pass: `${Math.round(row.passRate * 100)}%`,
+    verified: `${Math.round(row.fullyVerifiedRate * 100)}%`,
+    exec_failures: row.executionFailures,
+    errors: row.errors,
+    avg_tools: row.averageToolCalls ?? "-",
+    avg_ms: row.averageDurationMs,
+  }));
+  console.table(printable);
+}

evals/browser/lib/tasks.mjs

@@ -0,0 +1,48 @@
+import { loadCaseManifests } from "./case-loader.mjs";
+
+let casesPromise;
+
+export function allTasks({ reload = false } = {}) {
+  if (reload || !casesPromise) casesPromise = loadCaseManifests();
+  return casesPromise;
+}
+
+export function listTasks(cases) {
+  return cases.map(({ id, title, suite, tags, seed }) => ({ id, title, suite, tags, seed }));
+}
+
+export function getTask(taskId, cases) {
+  const task = cases.find(({ id }) => id === taskId);
+  if (!task) {
+    const ids = cases.map(({ id }) => id).join(", ");
+    throw new Error(`unknown case ${JSON.stringify(taskId)}; expected one of: ${ids}`);
+  }
+  return task;
+}
+
+export function taskUrl(task, baseUrl, runId, seed = task.seed) {
+  const url = new URL(task.startPath, baseUrl);
+  url.searchParams.set("run", runId);
+  if (seed !== undefined) url.searchParams.set("seed", String(seed));
+  return url.toString();
+}
+
+function expandTemplate(template, values) {
+  return Object.entries(values).reduce(
+    (result, [name, value]) => result.replaceAll(`{${name}}`, String(value)),
+    template,
+  );
+}
+
+export function renderPrompt(task, { baseUrl, runId, locale = "zh-CN", seed = task.seed }) {
+  const template = task.prompts[locale];
+  if (!template) {
+    throw new Error(`unsupported locale ${JSON.stringify(locale)}; expected en or zh-CN`);
+  }
+  return expandTemplate(template, {
+    baseUrl,
+    runId: encodeURIComponent(runId),
+    seed: seed ?? "",
+    url: taskUrl(task, baseUrl, runId, seed),
+  });
+}

evals/browser/schemas/case.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://browser-skill.local/schemas/browser-eval-case.schema.json",
+  "title": "BrowserSkill browser evaluation case",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "id",
+    "title",
+    "suite",
+    "tags",
+    "fixture",
+    "prompts",
+    "coverage",
+    "assertions",
+    "smoke"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "title": { "type": "string", "minLength": 1 },
+    "order": { "type": "integer", "minimum": 0 },
+    "suite": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+      "uniqueItems": true
+    },
+    "fixture": {
+      "type": "object",
+      "required": ["startPath"],
+      "properties": { "startPath": { "type": "string", "pattern": "^/" } },
+      "additionalProperties": false
+    },
+    "prompts": {
+      "type": "object",
+      "required": ["en", "zh-CN"],
+      "properties": {
+        "en": { "type": "string", "minLength": 1 },
+        "zh-CN": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "coverage": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "assertions": {
+      "type": "object",
+      "required": ["site", "response", "adapter"],
+      "properties": {
+        "site": { "type": "array", "items": { "type": "object" } },
+        "response": { "type": "array", "items": { "type": "object" } },
+        "adapter": { "type": "array", "items": { "type": "object" } }
+      },
+      "additionalProperties": false
+    },
+    "smoke": {
+      "type": "object",
+      "required": ["steps"],
+      "properties": {
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["action"],
+            "properties": { "action": { "type": "string" } },
+            "additionalProperties": true
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "seed": { "type": "integer" },
+    "source": { "type": "object" }
+  },
+  "additionalProperties": false
+}

evals/browser/tests/eval.test.mjs

@@ -0,0 +1,328 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import test from "node:test";
+
+import { runCommandTask } from "../lib/agent-runner.mjs";
+import { loadCaseManifests, validateCaseManifest } from "../lib/case-loader.mjs";
+import { buildOperationCoverage } from "../lib/coverage.mjs";
+import { loadFixtureRegistry } from "../lib/fixture-registry.mjs";
+import { verifyTask } from "../lib/oracle.mjs";
+import { runProcess } from "../lib/process.mjs";
+import { repositorySummary, validateRepositoryCases } from "../lib/repository-validation.mjs";
+import { scaffoldCase } from "../lib/scaffold-case.mjs";
+import { describeSeed } from "../lib/seeded-generator.mjs";
+import { createEvalServer } from "../lib/server.mjs";
+import { summarizeReports } from "../lib/summary.mjs";
+import { allTasks, getTask, renderPrompt } from "../lib/tasks.mjs";
+
+const cases = await allTasks();
+const fixtureRegistry = await loadFixtureRegistry();
+
+async function withServer(run) {
+  const server = createEvalServer({ fixtureRegistry });
+  const info = await server.start();
+  try {
+    await run(server, info);
+  } finally {
+    await server.stop();
+  }
+}
+
+test("case manifests are discovered, ordered, and grouped into suites", () => {
+  assert.deepEqual(
+    cases.map(({ id }) => id),
+    [
+      "navigation-history",
+      "form-controls",
+      "hover-inspect",
+      "tabs",
+      "diagnostics",
+      "mobile-emulation",
+      "generated-form",
+    ],
+  );
+  assert.deepEqual(repositorySummary(cases, fixtureRegistry).suites, { core: 6, matrix: 1 });
+});
+
+test("repository validation links every case to a fixture and valid workflow evidence", () => {
+  assert.deepEqual(validateRepositoryCases(cases, fixtureRegistry), []);
+  const summary = repositorySummary(cases, fixtureRegistry);
+  assert.equal(summary.cases, 7);
+  assert.equal(summary.fixtureModules, 8);
+  assert.equal(summary.fixtureRoutes, 12);
+});
+
+test("manifest validation rejects unknown operations and incomplete workflow steps", () => {
+  const invalid = {
+    schemaVersion: 1,
+    id: "invalid-case",
+    title: "Invalid",
+    suite: "regression",
+    tags: ["regression"],
+    fixture: { startPath: "/invalid" },
+    prompts: { en: "Open {url}", "zh-CN": "打开 {url}" },
+    coverage: ["page.teleport"],
+    assertions: { site: [], response: [], adapter: [] },
+    smoke: { steps: [{ action: "select", selector: "#choice", values: [] }] },
+    typo: true,
+  };
+  const errors = validateCaseManifest(invalid);
+  assert.ok(errors.some((error) => error.includes("unknown top-level property typo")));
+  assert.ok(errors.some((error) => error.includes("unknown operation page.teleport")));
+  assert.ok(errors.some((error) => error.includes("values must be a non-empty array")));
+});
+
+test("fixture server exposes deterministic task and seeded matrix markers", async () => {
+  await withServer(async (_server, { baseUrl }) => {
+    const fixtures = [
+      ["/navigation/detail?run=test-markers", "NAV-42"],
+      ["/form?run=test-markers", '<option value="two">Two</option>'],
+      ["/hover-inspect?run=test-markers", "INSPECT-27"],
+      ["/tabs/child?run=test-markers", "TAB-29"],
+      ["/diagnostics?run=test-markers", "CONSOLE-61"],
+      ["/responsive?run=test-markers", "VIEWPORT-84"],
+      ["/matrix/generated-form?run=test-markers&seed=17", "SEED-17"],
+    ];
+    for (const [path, marker] of fixtures) {
+      const response = await fetch(`${baseUrl}${path}`);
+      assert.equal(response.status, 200);
+      assert.match(await response.text(), new RegExp(marker));
+    }
+  });
+});
+
+test("server records and resets run-scoped events", async () => {
+  await withServer(async (server, { baseUrl }) => {
+    const response = await fetch(`${baseUrl}/api/events`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ runId: "event-test", type: "example", data: { value: 7 } }),
+    });
+    assert.equal(response.status, 202);
+    assert.equal(server.snapshot("event-test").events[0].data.value, 7);
+    const resetResponse = await fetch(`${baseUrl}/api/runs/event-test`, { method: "DELETE" });
+    assert.equal(resetResponse.status, 200);
+    assert.deepEqual(server.snapshot("event-test").events, []);
+  });
+});
+
+test("form case oracle checks submitted values and separates adapter evidence", () => {
+  const task = getTask("form-controls", cases);
+  const events = [
+    { type: "form.enter_pressed", data: {} },
+    {
+      type: "form.submitted",
+      data: { text: "agent-parity", notes: "BrowserSkill works", choice: "two" },
+    },
+    { type: "page.shown", data: { path: "/result" } },
+  ];
+  const partial = verifyTask(task, { events, responseText: "The page says Received!" });
+  assert.equal(partial.status, "passed-with-unverified");
+  assert.equal(partial.summary.unverified, 2);
+
+  const complete = verifyTask(task, {
+    events,
+    responseText: "The page says Received!",
+    adapterEvidence: { screenshotCreated: true, sessionStopped: true },
+  });
+  assert.equal(complete.status, "passed");
+});
+
+test("navigation case fails when reload is missing", () => {
+  const task = getTask("navigation-history", cases);
+  const verification = verifyTask(task, {
+    events: [
+      { type: "navigation.detail.clicked", data: {} },
+      { type: "page.shown", data: { path: "/navigation/start" } },
+      { type: "page.shown", data: { path: "/navigation/start" } },
+      { type: "page.shown", data: { path: "/navigation/detail" } },
+      { type: "page.shown", data: { path: "/navigation/detail" } },
+    ],
+    responseText: "NAV-42",
+  });
+  assert.equal(verification.status, "failed");
+  assert.equal(
+    verification.checks.find(({ label }) => label === "detail page was reloaded").status,
+    "failed",
+  );
+});
+
+test("prompt rendering is run-scoped, localized, and seed-aware", () => {
+  const task = getTask("generated-form", cases);
+  const input = { baseUrl: "http://127.0.0.1:4173", runId: "prompt-test", seed: 17 };
+  assert.match(renderPrompt(task, { ...input, locale: "en" }), /seed=17/);
+  assert.match(renderPrompt(task, { ...input, locale: "zh-CN" }), /seeded form/);
+});
+
+test("command adapter carries a run from process launch through oracle verification", async () => {
+  await withServer(async (server, serverInfo) => {
+    const script = `
+      const [baseUrl, runId] = process.argv.slice(1);
+      const send = (type, data) => fetch(baseUrl + "/api/events", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ runId, type, data }),
+      });
+      await send("navigation.detail.clicked", {});
+      await send("page.shown", { path: "/navigation/start" });
+      await send("page.shown", { path: "/navigation/start" });
+      await send("page.shown", { path: "/navigation/detail" });
+      await send("page.shown", { path: "/navigation/detail" });
+      await send("page.shown", { path: "/navigation/detail", navigationType: "reload" });
+      console.log("NAV-42");
+    `;
+    const result = await runCommandTask({
+      server,
+      serverInfo,
+      task: getTask("navigation-history", cases),
+      adapter: {
+        command: process.execPath,
+        args: ["--input-type=module", "-e", script, "{baseUrl}", "{runId}"],
+        variant: "fake-test",
+      },
+      adapterName: "fake-agent",
+      configDirectory: process.cwd(),
+      iteration: 1,
+      locale: "en",
+      timeoutMs: 5_000,
+    });
+    assert.equal(result.execution.exitCode, 0);
+    assert.equal(result.verification.status, "passed-with-unverified");
+    assert.equal(result.eventCount, 6);
+  });
+});
+
+test("report summary keeps partial verification distinct from full verification", () => {
+  const rows = summarizeReports([
+    {
+      results: [
+        {
+          adapter: "agent-a",
+          variant: "granular-28",
+          execution: { exitCode: 0, durationMs: 100 },
+          metrics: { errorCount: 0, toolCallCount: 4 },
+          verification: { status: "passed-with-unverified" },
+        },
+        {
+          adapter: "agent-a",
+          variant: "granular-28",
+          execution: { exitCode: 0, durationMs: 300 },
+          metrics: { errorCount: 1, toolCallCount: 6 },
+          verification: { status: "passed" },
+        },
+      ],
+    },
+  ]);
+  assert.equal(rows[0].passRate, 1);
+  assert.equal(rows[0].fullyVerifiedRate, 0.5);
+  assert.equal(rows[0].averageDurationMs, 200);
+  assert.equal(rows[0].averageToolCalls, 5);
+  assert.equal(rows[0].errors, 1);
+});
+
+test("coverage inventory contains all 28 operations and three manual lanes", () => {
+  const coverage = buildOperationCoverage(cases);
+  const operations = coverage.map(({ operation }) => operation);
+  assert.equal(operations.length, 28);
+  assert.equal(new Set(operations).size, 28);
+  assert.deepEqual(
+    coverage.filter(({ directSmoke }) => !directSmoke).map(({ operation }) => operation),
+    ["tabs.borrow", "tabs.return", "assist.request-help"],
+  );
+  assert.deepEqual(coverage.find(({ operation }) => operation === "interact.fill").smokeCases, [
+    "form-controls",
+    "generated-form",
+  ]);
+});
+
+test("seeded dimensions are reproducible and vary across seeds", () => {
+  assert.deepEqual(describeSeed("badcase-17"), describeSeed("badcase-17"));
+  assert.notDeepEqual(describeSeed("badcase-17"), describeSeed("badcase-18"));
+  assert.equal(describeSeed(17).seed, 17);
+});
+
+test("badcase scaffold creates a loadable, escaped, self-contained case", async () => {
+  const temporaryRoot = await mkdtemp(join(tmpdir(), "browser-eval-scaffold-"));
+  try {
+    const title = "Quoted `title` ${notCode} <unsafe>";
+    const result = await scaffoldCase({
+      id: "reported-timeout",
+      title,
+      suite: "regression",
+      source: "issue-123",
+      rootCasesDirectory: temporaryRoot,
+    });
+    const loaded = await loadCaseManifests({ casesDirectory: temporaryRoot });
+    assert.equal(loaded[0].id, "reported-timeout");
+    assert.equal(loaded[0].source.reference, "issue-123");
+
+    const generatedRegistry = await loadFixtureRegistry({ roots: [temporaryRoot] });
+    const html = generatedRegistry.render("/cases/reported-timeout", {
+      runId: "scaffold-test",
+      query: new URLSearchParams(),
+      record() {},
+    });
+    assert.match(html, /Quoted `title` \$\{notCode\} &lt;unsafe&gt;/);
+    assert.match(await readFile(result.files.readme, "utf8"), /issue-123/);
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+});
+
+test("CLI accepts pnpm separator and supports suite and tag filters", async () => {
+  const cli = resolve("evals/browser/cli.mjs");
+  const coverageResult = await runProcess(process.execPath, [cli, "--", "coverage", "--json"], {
+    timeoutMs: 5_000,
+  });
+  assert.equal(coverageResult.exitCode, 0, coverageResult.stderr);
+  assert.equal(JSON.parse(coverageResult.stdout).length, 28);
+
+  const coreResult = await runProcess(
+    process.execPath,
+    [cli, "list", "--suite", "core", "--json"],
+    {
+      timeoutMs: 5_000,
+    },
+  );
+  assert.equal(coreResult.exitCode, 0, coreResult.stderr);
+  assert.equal(JSON.parse(coreResult.stdout).length, 6);
+
+  const formResult = await runProcess(process.execPath, [cli, "list", "--tag", "form", "--json"], {
+    timeoutMs: 5_000,
+  });
+  assert.equal(formResult.exitCode, 0, formResult.stderr);
+  assert.deepEqual(
+    JSON.parse(formResult.stdout).map(({ id }) => id),
+    ["form-controls", "generated-form"],
+  );
+});
+
+test("CLI validation and seed generation are machine-readable", async () => {
+  const cli = resolve("evals/browser/cli.mjs");
+  const validation = await runProcess(process.execPath, [cli, "validate", "--json"], {
+    timeoutMs: 5_000,
+  });
+  assert.equal(validation.exitCode, 0, validation.stderr);
+  assert.equal(JSON.parse(validation.stdout).ok, true);
+
+  const generated = await runProcess(
+    process.execPath,
+    [cli, "generate", "--seed", "known-badcase", "--json"],
+    { timeoutMs: 5_000 },
+  );
+  assert.equal(generated.exitCode, 0, generated.stderr);
+  assert.equal(typeof JSON.parse(generated.stdout).hydrationDelayMs, "number");
+
+  const generatedSet = await runProcess(
+    process.execPath,
+    [cli, "generate", "--seed", "4,7,14", "--json"],
+    { timeoutMs: 5_000 },
+  );
+  assert.equal(generatedSet.exitCode, 0, generatedSet.stderr);
+  assert.deepEqual(
+    JSON.parse(generatedSet.stdout).map(({ seed }) => seed),
+    [4, 7, 14],
+  );
+});

package.json

@@ -4,6 +4,9 @@
   "packageManager": "pnpm@10.17.0",
   "scripts": {
     "cli:build": "cargo run -p bsk-protocol --bin dump-schema --locked && pnpm -r build",
+    "eval:browser": "node evals/browser/cli.mjs",
+    "eval:browser:check": "node evals/browser/cli.mjs validate && node --test evals/browser/tests/*.test.mjs",
+    "eval:browser:test": "node --test evals/browser/tests/*.test.mjs",
     "ext:build": "pnpm --filter @browser-skill/extension build",
     "ext:build:zip": "pnpm --filter @browser-skill/extension zip",
     "ext:dev": "pnpm --filter @browser-skill/extension dev",

packages/dsh-plugin-browserskill/README.md

@@ -20,22 +20,43 @@ extension keep owning the actual browser control — this package is a thin, wel
 | `browser_snapshot` | `bsk snapshot` | Indented aria-tree snapshot with `@eN` refs for interaction tools. |
 | `browser_observe` | `bsk observe` | Semantic VOM observation (read-only) with `@eN` refs. |
 | `browser_click` | `bsk click` | Click a snapshot ref or CSS selector (button / click-count options). |
+| `browser_hover` | `bsk hover` | Hover a ref or selector and allow hover-triggered UI to settle. |
 | `browser_fill` | `bsk fill` | Fill an input / textarea / contenteditable (clears first by default). |
+| `browser_select` | `bsk select` | Select one or more option values on a `<select>`. |
 | `browser_press` | `bsk press` | Dispatch a key or combo, optionally focusing a target first. |
 | `browser_screenshot` | `bsk screenshot` | PNG capture of the tab or a ref-cropped element; inlines the image when the deployment supports image input, otherwise returns a file path. |
 | `browser_emulate` | `bsk emulate` | Apply or clear mobile device emulation on the active tab. |
+| `browser_tab_list` | `bsk tab list` | List user and/or Agent Window tabs visible to an owned session. |
+| `browser_tab_create` | `bsk tab create` | Create a foreground or background tab in the Agent Window. |
+| `browser_tab_select` | `bsk tab select` | Focus an Agent Window tab. |
+| `browser_tab_close` | `bsk tab close` | Close an Agent Window tab. |
+| `browser_tab_borrow` | `bsk tab borrow` | Move a user tab into the Agent Window for controlled interaction. |
+| `browser_tab_return` | `bsk tab return` | Return a borrowed tab to its original user window. |
+| `browser_navigate_back` / `browser_navigate_forward` | `bsk navigate-back` / `bsk navigate-forward` | Traverse tab history and wait for a lifecycle phase. |
+| `browser_reload` | `bsk reload` | Reload the active tab, optionally bypassing cache. |
+| `browser_wait_for_navigation` | `bsk wait-for-navigation` | Wait explicitly for a page lifecycle event. |
+| `browser_request_help` | `bsk request-help` | Pause for login, captcha, OTP, confirmation, or another human browser step. |
+| `browser_get_html` | `bsk get-html` | Read raw document or ref-scoped HTML after semantic observation is insufficient. |
+| `browser_console` | `bsk console` | Read buffered console/log/exception entries without evaluating JavaScript. |
+| `browser_network` | `bsk network` | Read buffered network response/failure metadata. |
+| `browser_window_resize` | `bsk window resize` | Resize the owned session's Agent Window. |
+
+`bsk evaluate` and `bsk record` are intentionally not exposed by this plugin: arbitrary page
+evaluation is a higher-risk capability, while recording is long-running and needs a dedicated
+DeepSeek Harness lifecycle before it can be added safely.
 
 ## Agent skill (progressive disclosure)
 
 Beyond the tools, the plugin publishes the **`browser-skill` agent skill** through the harness's
 official skill seam (`ctx.skills.register`): the catalog entry (name + routing description) is
 resident in `<available_skills>`, and the body is loaded only when the model invokes the `skill`
-tool. The body is assembled at build time from two parts, so there is exactly one source of
-truth: a dsh-specific prelude (`skill/prelude.md` — tool↔CLI map, owned-session semantics,
-plugin-only overrides) followed verbatim by the canonical CLI skill (`skill/SKILL.md` at the
-repo root — the same file `crates/bsk-cli/build.rs` mirrors for the CLI package; workflows,
-stop-when-done rules, refs usage, sandbox rules). Registration and every pre-step catalog
-snapshot are pure in-memory reads (no disk/process/daemon); compositions without the skill
+tool. Its single source is the DSH-specific `skill/SKILL.md`, which documents only structured
+`browser_*` calls and their plugin semantics. The repository-root CLI skill is intentionally not
+concatenated: its command examples belong to a different execution interface and would bypass
+the plugin's ownership, live observation UI, cancellation, and cleanup path if followed directly.
+The build rejects internal CLI-name leakage, command-line code blocks, unknown browser tools, and
+missing supported browser tools before embedding the Markdown. Registration and every pre-step
+catalog snapshot are pure in-memory reads (no disk/process/daemon); compositions without the skill
 seam degrade silently.
 
 ## Multi-session model
@@ -88,7 +109,7 @@ All fields are optional and validated through the plugin's Schemastery `Config`:
         # lazyTools: true              # reveal browser_* tools only after the skill is invoked
 ```
 
-- **`lazyTools` (default `true`)** — the final progressive-disclosure stage: the eleven
+- **`lazyTools` (default `true`)** — the final progressive-disclosure stage: the 28
   `browser_*` tool schemas stay OUT of the system prompt (zero schema tokens) until the
   `browser-skill` skill is actually invoked — the skill catalog entry is the only
   advertisement. One successful invocation (model tool call, or a `/browser-skill` user
@@ -152,7 +173,7 @@ shell's theme cannot bleed back in.
   card). Screenshots additionally attach the image itself when the host mounts an attachment store
   and the active model route declares image input; otherwise the PNG path is returned.
 - **Web UI toolview (browser half)**: the package is dual-face. `dsh.client` (platform `web`) ships
-  `lib/client.js`, which registers a keyed `tool.call.toolview` view for `browser_screenshot`. The
+  `lib/client.cjs`, which registers a keyed `tool.call.toolview` view for `browser_screenshot`. The
   custom view keeps the terminal block (command + output) and, when the settled result carries an
   image block, resolves the durable attachment through the client session's authorized
   `readAttachment` RPC and renders it with the shared `MessageImage` thumbnail/lightbox atoms.
@@ -183,8 +204,8 @@ as `@wxg-prc-cpg/browser-skill-dsh-plugin`. The Cordis plugin id stays
 Trigger it by pushing a tag that matches `package.json`'s `version`:
 
 ```sh
-git tag dsh-plugin-v0.1.0
-git push origin dsh-plugin-v0.1.0
+git tag dsh-plugin-v0.1.2
+git push origin dsh-plugin-v0.1.2
 ```
 
 Or run the workflow from the Actions tab (`workflow_dispatch`). The job reads the

packages/dsh-plugin-browserskill/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wxg-prc-cpg/browser-skill-dsh-plugin",
-  "description": "DeepSeek Harness tool plugin that exposes BrowserSkill (bsk) browser automation to the model",
-  "version": "0.1.1",
+  "description": "DeepSeek Harness tool plugin that exposes BrowserSkill browser automation (browser_* tools) to the model",
+  "version": "0.1.2",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -107,6 +107,8 @@
     "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-tool": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@tailwindcss/cli": "^4.3.3",

packages/dsh-plugin-browserskill/scripts/build-skill-content.mjs

@@ -1,20 +1,15 @@
-// Assemble the plugin's skill content: a dsh-specific routing prelude, the
-// canonical CLI skill body verbatim (repo-root skill/SKILL.md — the same source
-// crates/bsk-cli's build.rs mirrors), then a dsh routing reminder postlude. The
-// original's YAML frontmatter is stripped: name/description are supplied by the
-// registration.
+// Embed the DeepSeek Harness-specific browser skill at build time. The model-facing
+// skill deliberately documents only injected browser_* tools; the repository's CLI
+// skill is a separate interface and must never be concatenated here.
 // Output: src/skill-content.generated.ts (gitignored, built before tsdown and
-// before vitest) so the markdown ships inlined in the bundle and registration
-// is a pure in-memory read — never a per-step disk access.
+// before vitest), so registration is a pure in-memory read.
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const pkg = join(here, "..");
-const prelude = readFileSync(join(pkg, "skill", "prelude.md"), "utf8");
-const upstream = readFileSync(join(pkg, "..", "..", "skill", "SKILL.md"), "utf8");
-const postlude = readFileSync(join(pkg, "skill", "postlude.md"), "utf8");
+const source = readFileSync(join(pkg, "skill", "SKILL.md"), "utf8");
 
 function stripFrontmatter(markdown) {
   if (!markdown.startsWith("---\n")) return markdown;
@@ -22,18 +17,69 @@ function stripFrontmatter(markdown) {
   return end === -1 ? markdown : markdown.slice(end + 5).replace(/^\s*\n/, "");
 }
 
+const SUPPORTED_BROWSER_TOOLS = [
+  "browser_session_start",
+  "browser_session_stop",
+  "browser_session_list",
+  "browser_navigate",
+  "browser_navigate_back",
+  "browser_navigate_forward",
+  "browser_reload",
+  "browser_wait_for_navigation",
+  "browser_snapshot",
+  "browser_observe",
+  "browser_get_html",
+  "browser_screenshot",
+  "browser_console",
+  "browser_network",
+  "browser_click",
+  "browser_hover",
+  "browser_fill",
+  "browser_select",
+  "browser_press",
+  "browser_tab_list",
+  "browser_tab_create",
+  "browser_tab_select",
+  "browser_tab_close",
+  "browser_tab_borrow",
+  "browser_tab_return",
+  "browser_request_help",
+  "browser_emulate",
+  "browser_window_resize",
+];
+
+function validateModelFacingSkill(markdown) {
+  if (/\bbsk\b/i.test(markdown)) {
+    throw new Error("DSH skill must not expose the internal CLI name");
+  }
+  if (/```(?:bash|sh|shell)\b/i.test(markdown)) {
+    throw new Error("DSH skill must not contain command-line code blocks");
+  }
+
+  const mentioned = new Set(markdown.match(/\bbrowser_[a-z][a-z_]*\b/g) ?? []);
+  const supported = new Set(SUPPORTED_BROWSER_TOOLS);
+  const unknown = [...mentioned].filter((name) => !supported.has(name));
+  const missing = SUPPORTED_BROWSER_TOOLS.filter((name) => !mentioned.has(name));
+  if (unknown.length > 0) {
+    throw new Error(`DSH skill mentions unsupported browser tools: ${unknown.join(", ")}`);
+  }
+  if (missing.length > 0) {
+    throw new Error(`DSH skill omits supported browser tools: ${missing.join(", ")}`);
+  }
+}
+
 const NAME = "browser-skill";
 const DESCRIPTION =
-  "Browser automation against the user's logged-in Chromium through this plugin's injected browser_* tools; never invoke bsk through bash or shell. " +
-  "tools (bsk engine): visit and read pages, fill forms, click through flows, scrape data, " +
-  "smoke-test UI changes. Use when a task needs a real browser; requires the bsk CLI and the " +
-  "browser-skill extension connected.";
+  "Browser automation against the user's logged-in Chromium through this plugin's injected " +
+  "browser_* tools. Use to visit and read pages, fill forms, click through flows, inspect tabs, " +
+  "debug page activity, or smoke-test UI changes in a managed Agent Window.";
 
-const content = `${prelude.trim()}\n\n${stripFrontmatter(upstream).trim()}\n\n${postlude.trim()}\n`;
+const content = `${stripFrontmatter(source).trim()}\n`;
+validateModelFacingSkill(content);
 
 const banner =
   "// GENERATED by scripts/build-skill-content.mjs — do not edit.\n" +
-  "// Sources: skill/prelude.md + ../../../skill/SKILL.md + skill/postlude.md.\n";
+  "// Source: skill/SKILL.md (DeepSeek Harness browser_* tool instructions).\n";
 
 writeFileSync(
   join(pkg, "src", "skill-content.generated.ts"),

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

@@ -0,0 +1,271 @@
+---
+name: browser-skill
+description: |
+  Use the injected browser_* tools to automate the user's logged-in Chromium
+  browser in a managed Agent Window.
+---
+
+# browser-skill for DeepSeek Harness
+
+Drive the user's real Chromium browser through the structured `browser_*` tools provided by this
+plugin. The browser keeps the user's existing logins and cookies while isolating automation in an
+Agent Window. Use the tool schemas exactly as exposed by DeepSeek Harness; arguments are structured
+fields, not command-line flags.
+
+## Tool availability
+
+Loading this skill reveals the browser tools for the rest of the conversation. If the tools were
+hidden before this skill was loaded, start browser work only after the skill invocation succeeds.
+
+All browser operations must use the injected tools directly. Do not translate the examples in this
+document into terminal commands or invoke another process to control the browser. Direct tool calls
+preserve session ownership, the live observation window, tool cards, cancellation, and cleanup.
+
+## When to use
+
+- Visit and read pages that require the user's existing browser session.
+- Fill forms, select options, click through bounded flows, or smoke-test a web UI.
+- Inspect tabs, page structure, screenshots, console messages, or network metadata.
+- Work with a user tab after explicitly borrowing it into the Agent Window.
+
+Do not use browser automation for tasks that need only local files, a purpose-built API, or an
+explanation. Never extract credentials, cookies, tokens, or other secrets. Do not keep control of a
+personal tab longer than the immediate task requires.
+
+## Mandatory workflow
+
+Every browser task follows this lifecycle:
+
+1. Call `browser_session_start` and retain its returned `sessionId`.
+2. Use that session for every browser operation. Pass `session` explicitly when more than one
+   session exists.
+3. Call `browser_session_stop` when the bounded goal is reached or an error ends the task. Treat
+   cleanup like a `finally` path unless the user explicitly asks to keep the session open.
+
+Conceptual tool-call sequence:
+
+```text
+browser_session_start({ url: "https://example.com" })
+browser_observe({ session: sessionId })
+browser_click({ session: sessionId, target: "@e4" })
+browser_observe({ session: sessionId })
+browser_session_stop({ session: sessionId })
+```
+
+The plugin owns only sessions created by `browser_session_start`. `browser_session_list` reports
+only those owned sessions. Never guess or reuse a session id from another program. When `session`
+is omitted, most tools use the most recently started or used owned session; explicit ids are safer
+for multi-session work.
+
+## Stop when the goal is met
+
+Browser work is a bounded task, not open-ended browsing.
+
+1. Define one observable success condition from the user's request.
+2. Take the shortest path: observe, act, then perform at most one relevant check.
+3. Stop immediately when success is visible. Do not refresh, navigate, click, or perform extra
+   verification after success.
+4. If a human-only step appears, use `browser_request_help`. If an action fails twice without
+   progress, pause instead of brute-forcing.
+5. When uncertain, make at most one fresh observation. If the state is still ambiguous, ask the
+   user rather than continuing to click.
+
+## Core interaction loop
+
+Use `browser_navigate` to open a destination in the active Agent Window tab, then inspect the page
+before interacting:
+
+1. `browser_observe` is the primary semantic view. It returns roles, states, text, and `@eN` refs,
+   including hints about conditional hover or focus surfaces.
+2. `browser_snapshot` is the static accessibility-tree fallback when the semantic view is
+   insufficient or a stricter tree is useful.
+3. Prefer a fresh `@eN` ref over a raw CSS selector for `browser_click`, `browser_hover`,
+   `browser_fill`, `browser_select`, and targeted `browser_press` calls.
+4. Observe again after navigation or a meaningful DOM change before using another ref.
+
+Refs invalidate after navigation and may also become stale after large DOM changes. Never carry a
+ref to a new page. If an observation marks a control as hover-triggered, call `browser_hover` on the
+trigger, observe again, and then act on the newly visible ref.
+
+Use interaction tools according to their schemas:
+
+- `browser_click`: click a ref or selector; optionally choose mouse button and click count.
+- `browser_hover`: move to a ref or selector and allow hover UI to settle; then observe again.
+- `browser_fill`: clear and fill a text-capable element; set `noClear` only when appending is
+  intentional.
+- `browser_select`: pass `values` as an array, including for a single option.
+- `browser_press`: send a key or combo, optionally focusing `target` first.
+
+Actions may trigger a navigation after the action itself returns. Use
+`browser_wait_for_navigation` only when that lifecycle wait is actually needed, then observe the
+new page.
+
+## Observation and page reading priority
+
+Escalate page reading only as needed:
+
+1. `browser_observe` for normal semantic understanding and interaction refs.
+2. `browser_snapshot` for a stricter static accessibility tree.
+3. `browser_get_html` for hidden DOM, metadata, or exact markup that the semantic views cannot
+   provide. A `ref` must come from a fresh observation; keep `maxBytes` bounded.
+4. `browser_screenshot` for layout, styling, canvas, image content, or another genuinely visual
+   question. Pass a fresh `ref` to crop to one element, or omit it for the visible tab.
+
+Do not start with raw HTML or a screenshot merely to discover ordinary controls. Screenshots may
+return an inline image or a saved path depending on the deployment.
+
+## Tabs and the Agent Window boundary
+
+Write actions normally affect only Agent Window tabs.
+
+- `browser_tab_list` lists `agent`, `user`, or `all` tabs visible to the owned session. Use
+  `scope: "user"` to locate a user tab before borrowing it.
+- `browser_tab_create` creates an Agent Window tab. It is active by default; set `active: false`
+  for a background tab.
+- `browser_tab_select` focuses an Agent Window tab.
+- `browser_tab_close` closes an Agent Window tab.
+- `browser_tab_borrow` moves a chosen user tab into the Agent Window before any write action.
+- `browser_tab_return` returns a borrowed tab to its original window and position. Return it as
+  soon as the immediate task is finished; stopping the session is only the fallback cleanup.
+
+Use only a `tabId` returned by `browser_tab_list` or `browser_tab_create`. Do not assume a tab id
+from page position or title.
+
+## Navigation and lifecycle
+
+- `browser_navigate` opens a URL and can wait for a requested lifecycle phase.
+- `browser_navigate_back` and `browser_navigate_forward` move one history entry.
+- `browser_reload` reloads the current tab; use `hard: true` only when bypassing cache is necessary.
+- `browser_wait_for_navigation` waits for a lifecycle event after an action that did not already
+  wait. Avoid speculative waits when no navigation is expected.
+
+After navigation, history traversal, or reload, discard old refs and call `browser_observe` or
+`browser_snapshot` again.
+
+## Ask the user for browser help
+
+Call `browser_request_help` for login, captcha, OTP, payment confirmation, consent, or another step
+that requires the user. Give a clear `prompt`; when the prompt refers to a concrete control, pass
+its fresh ref or selector in `targets` so the overlay can highlight it. Use `title` only when it
+adds clarity.
+
+Optional `completionCriteria` can finish the pause automatically when the page has an explicit,
+stable success signal. It supports `any` or `all` conditions using `urlContains`, `urlMatches`,
+`selectorExists`, `selectorMissing`, `textExists`, or `textMissing`, plus `stableForMs`.
+
+```text
+browser_request_help({
+  session: sessionId,
+  title: "Sign in required",
+  prompt: "Complete sign-in, then return control after the account page appears.",
+  targets: ["@e7"],
+  timeoutMs: 300000,
+  completionCriteria: {
+    any: [{ urlContains: "/account" }, { selectorExists: "[data-testid='account-menu']" }],
+    stableForMs: 1000
+  }
+})
+```
+
+Interpret outcomes deliberately:
+
+- `continued` or `completed`: the user returned control or the explicit detector matched. Observe
+  again before reasoning about the new state or using refs.
+- `cancelled`: stop the requested flow.
+- `timed_out`: report the timeout; do not repeatedly reopen the prompt.
+- `disabled`: unattended mode does not allow help; proceed only if safe or stop gracefully.
+- `navigated`: legacy outcome; do not treat navigation alone as proof of success.
+
+## Debugging without page scripting
+
+Use the read-only debugging tools only when relevant to the user's task:
+
+- `browser_console` reads buffered console messages, browser logs, and JavaScript exceptions.
+  Set `includeStack: true` when stack frames are useful.
+- `browser_network` reads buffered response and failure metadata. It does not return request or
+  response headers or bodies and does not modify traffic.
+
+Both tools accept `tabId`, `since`, `limit`, and `maxTextChars`. Their result returns `nextSince`;
+pass that value as the next `since` cursor instead of repeatedly requesting the same entries.
+
+Arbitrary page script evaluation and interaction recording are intentionally unsupported in this
+DeepSeek Harness plugin. Do not invent tool names or route around this limitation. If the task
+strictly requires either capability, explain that it is not available in this phase.
+
+## Window and device controls
+
+- `browser_window_resize` changes the Agent Window's outer `width` and `height`; each dimension
+  must be from 100 through 7680 CSS pixels.
+- `browser_emulate` applies a built-in device preset or explicit viewport settings to the active
+  tab. Explicit `width` and `height` must be supplied together. `mobile: true` also requires both
+  dimensions. Use `off: true` alone to clear emulation. Emulation is per-tab and new tabs do not
+  inherit it.
+
+## Tool reference
+
+### Sessions
+
+| Tool | Purpose |
+| --- | --- |
+| `browser_session_start` | Start an owned Agent Window session, optionally with URL, size, browser instance, focus behavior, or device preset. |
+| `browser_session_stop` | Stop an owned session and close its Agent Window. |
+| `browser_session_list` | List owned sessions and identify the current one. |
+
+### Navigation and reading
+
+| Tool | Purpose |
+| --- | --- |
+| `browser_navigate` | Navigate the active tab to a URL. |
+| `browser_navigate_back` | Go back one history entry. |
+| `browser_navigate_forward` | Go forward one history entry. |
+| `browser_reload` | Reload the active tab, optionally bypassing cache. |
+| `browser_wait_for_navigation` | Wait for an expected page lifecycle event. |
+| `browser_observe` | Read the primary semantic page representation with refs. |
+| `browser_snapshot` | Read the static accessibility-tree fallback with refs. |
+| `browser_get_html` | Read raw document or ref-scoped HTML as a last resort. |
+| `browser_screenshot` | Capture the visible tab or a ref-cropped element. |
+
+### Interaction
+
+| Tool | Purpose |
+| --- | --- |
+| `browser_click` | Click a ref or CSS selector. |
+| `browser_hover` | Hover a ref or selector to reveal conditional UI. |
+| `browser_fill` | Fill a text-capable element. |
+| `browser_select` | Select one or more option values. |
+| `browser_press` | Send a keyboard key or combo. |
+
+### Tabs
+
+| Tool | Purpose |
+| --- | --- |
+| `browser_tab_list` | List visible user and Agent Window tabs. |
+| `browser_tab_create` | Create an Agent Window tab. |
+| `browser_tab_select` | Focus an Agent Window tab. |
+| `browser_tab_close` | Close an Agent Window tab. |
+| `browser_tab_borrow` | Move a user tab into the Agent Window. |
+| `browser_tab_return` | Return a borrowed tab to its original window. |
+
+### Assistance, diagnostics, and display
+
+| Tool | Purpose |
+| --- | --- |
+| `browser_request_help` | Pause for an explicit user browser step. |
+| `browser_console` | Read buffered console and exception entries. |
+| `browser_network` | Read buffered response and failure metadata. |
+| `browser_window_resize` | Resize the Agent Window. |
+| `browser_emulate` | Apply or clear per-tab device emulation. |
+
+## Error handling and final checklist
+
+On a stale ref, observe again and retry once with a fresh ref. On a closed or unknown tab, list
+tabs instead of guessing. On an unknown session, list owned sessions or start a new one; never try
+foreign ids. On timeout, decide whether one longer, purposeful wait is justified. Avoid repeated
+actions with unchanged state.
+
+Before finishing a browser task, verify that:
+
+- The user's observable goal is met, or the blocker is clearly reported.
+- Any borrowed tab has been returned when practical.
+- The owned session has been stopped unless the user explicitly asked to keep it open.
+- No further page action is taken after success.

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

@@ -1,10 +0,0 @@
----
-
-## DSH routing reminder
-
-The CLI-oriented reference above describes behavior, not the execution mechanism in
-DeepSeek Harness. For every browser operation, call the injected `browser_*` model
-tool. Do not translate these examples into `bash` commands and do not execute `bsk`
-directly; the plugin invokes `bsk` internally. In particular, always begin with
-`browser_session_start`, pass its returned session id to subsequent `browser_*`
-tools, and finish with `browser_session_stop`.

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

@@ -1,71 +0,0 @@
-# browser-skill (dsh edition)
-
-## DSH tool-routing requirement (highest priority)
-
-This skill is running inside DeepSeek Harness, where the plugin has injected
-structured `browser_*` model tools. **Always call those injected `browser_*` tools
-for browser work. Never use `bash`, `shell`, `exec`, or another tool to invoke the
-`bsk` CLI directly.** The CLI command names shown below are only conceptual
-mappings for understanding the tools; they are not instructions to run commands.
-If a `browser_*` tool is available, using the CLI directly is incorrect because it
-bypasses plugin session ownership, observation UI, tool cards, and cleanup.
-
-Use the injected tool whose name matches the operation, for example:
-`browser_session_start`, `browser_navigate`, `browser_observe`, `browser_snapshot`,
-`browser_click`, `browser_fill`, `browser_press`, `browser_screenshot`, and
-`browser_session_stop`. Pass arguments as the tool schema specifies (not CLI flags).
-
-Drive the user's **real Chromium browser** (logins, cookies, Agent Window isolation)
-through this plugin's `browser_*` tools. Each injected tool is implemented by the
-plugin using the `bsk` engine internally — the model must not invoke that engine
-itself. The workflow, judgment rules, and safety constraints remain identical to
-the canonical CLI skill.
-
-> **Tool availability**: invoking this skill (which you just did) makes the plugin's
-> `browser_*` tools available for the rest of the session — they are injected on
-> successful skill load. Until then they are deliberately hidden, so do not attempt
-> a browser action before loading this skill.
-
-## Tool ↔ CLI map
-
-The tools below are thin, structured wrappers over the bsk CLI verbs of the same
-name; `session` parameters take the 4-letter session id (no `--session` flag
-spelling here):
-
-| dsh tool | bsk equivalent |
-|---|---|
-| `browser_session_start` / `browser_session_stop` / `browser_session_list` | `bsk session start/stop/list` |
-| `browser_navigate` | `bsk navigate` |
-| `browser_snapshot` / `browser_observe` | `bsk snapshot` / `bsk observe` |
-| `browser_click` / `browser_fill` / `browser_press` | `bsk click` / `bsk fill` / `bsk press` |
-| `browser_screenshot` | `bsk screenshot` |
-| `browser_emulate` | `bsk emulate` |
-
-(`bsk console` / `bsk network` have no tool counterpart in this plugin yet.)
-
-Plugin-specific semantics that override or narrow the CLI rules below:
-
-- **Owned sessions only**: this plugin sees and acts on just the sessions IT
-  started via `browser_session_start`. `browser_session_list` shows only those
-  (with the current marker); passing a session id created by another program
-  (or person) sharing the bsk daemon is refused outright — never retry those
-  with the same id.
-- **Current session**: omitted `session` parameters resolve to the most
-  recently started or used OWNED session. With several sessions in flight,
-  pass `session` explicitly to avoid surprises.
-- **Screenshots**: when the model route accepts images, `browser_screenshot`
-  returns the PNG inline as an image attachment; otherwise it returns the
-  saved file path.
-- **`browser_emulate mobile`**: requires `width`+`height` — the bsk daemon
-  refuses `--mobile` without viewport dimensions.
-- **Live observation**: in the dsh Web UI, every owned session is watched by
-  the floating overlay (thumbnails, action, interrupt) — observational side
-  traffic is free and never steals your command turn; just keep acting.
-
-The canonical CLI skill body follows verbatim (source of truth: `skill/SKILL.md`
-in the BrowserSkill repo, mirrored by build into `crates/bsk-cli/skill/SKILL.md`).
-Read `bsk <verb> --session <id>` as "the `browser_<verb>` tool with
-`session: <id>`"; everything else — when to use, the stop-when-done rules, the
-interaction loop, refs, sandbox rules — applies unchanged.
-
----

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -12,13 +12,14 @@
 
 import type { Context } from "@deepseek-ai/cordis";
 import Schema from "@deepseek-ai/schemastery";
+import { armArchiveCleanup } from "./archive-cleanup";
 import { armLazyTools } from "./lazy-tools";
 import { ObservationService } from "./observation";
 import { registerObservationRoutes } from "./observation-http";
 import { KeyedExecutor } from "./queue";
 import { type BskRunner, createBskRunner } from "./runner";
 import { SessionRegistry } from "./sessions";
-import { registerBskSkill } from "./skill";
+import { armAgentScopedBskSkill, registerBskSkill } from "./skill";
 import { type PluginConfig, registerTools } from "./tools";
 
 export const name = "dsh-plugin-browserskill";
@@ -94,6 +95,11 @@ export function apply(
   // ONLY model-visible advertisement — the tool suite reveals itself on a
   // successful skill invocation (or a session whose history already has one).
   const unregisterSkill = registerBskSkill(ctx);
+  // A same-name CLI skill left in ~/.agents is discovered in the nearer preset
+  // layer and shadows the global registration above. Re-register through every
+  // exact agent context at startup so DSH always loads the browser_* protocol
+  // instructions; the shared CLI skill remains untouched for other agents.
+  const disarmAgentSkill = armAgentScopedBskSkill(ctx);
   const removeSuite = resolved.lazyTools
     ? armLazyTools(ctx, () =>
         registerTools({ ctx, runner, registry, config: resolved, observation, queue }),
@@ -107,6 +113,10 @@ export function apply(
     removeRoutes = registerObservationRoutes(injected, observation);
     return () => removeRoutes();
   });
+  // Reap a conversation's browsers when the conversation itself is archived:
+  // archived sessions are hidden from every surface, so their Agent Windows
+  // would otherwise linger unreachable until idle timeout or unload.
+  const disarmArchiveCleanup = armArchiveCleanup(ctx, registry, observation);
 
   // Non-blocking install probe: warn early when bsk is missing instead of
   // failing the first tool call with a bare spawn error. Uses --version on
@@ -130,20 +140,20 @@ export function apply(
   ctx.effect(() => {
     return () => {
       removeSuite();
+      disarmAgentSkill();
       unregisterSkill();
       removeRoutes();
-      observation.dispose();
+      disarmArchiveCleanup();
       runner.killAll();
       const stops = registry
         .ownedIds()
-        .map((sessionId) =>
-          runner.run(["session", "stop", sessionId], { timeoutMs: 15_000 }).catch(() => {}),
-        );
-      return Promise.all(stops).then(() => {});
+        .map((sessionId) => observation.stopSession(sessionId).catch(() => false));
+      return Promise.all(stops).then(() => observation.dispose());
     };
   });
 }
 
+export { armArchiveCleanup, ownerSessionIds } from "./archive-cleanup";
 export type { ObservationEvent, ObservationOptions, SessionObservation } from "./observation";
 export { ObservationService } from "./observation";
 export { registerObservationRoutes } from "./observation-http";

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

@@ -1,6 +1,6 @@
 /**
  * Lazy tool-schema injection ("progressive disclosure", final stage): with
- * `lazyTools` on (the default), the 11 browser_* tool schemas stay OUT of the
+ * `lazyTools` on (the default), the 28 browser_* tool schemas stay OUT of the
  * system prompt until the `browser-skill` skill has actually been invoked —
  * the skill catalog entry is the only advertisement. One successful
  * invocation (model tool call, or a user's `/browser-skill` gesture) reveals
@@ -96,7 +96,7 @@ export function hasSuccessfulSkillInvocation(events: readonly SessionEventLike[]
 /**
  * Arm the lazy reveal. Returns a disposer tearing down listeners and — when
  * the reveal already happened — the tool suite itself.
- * @param registerSuite - registers the 11 browser_* tools, returns their disposer.
+ * @param registerSuite - registers the 28 browser_* tools, returns their disposer.
  */
 export function armLazyTools(ctx: Context, registerSuite: () => () => void): () => void {
   let suiteDisposer: (() => void) | undefined;

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

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

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

@@ -18,7 +18,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import type { KeyedExecutor } from "./queue";
-import type { BskRunner } from "./runner";
+import { BskError, type BskRunner, parseBskJson, runWithSessionBusyRetry } from "./runner";
 import type { SessionRegistry } from "./sessions";
 
 /** One owned session's live observation record (wire-stable shape). */
@@ -39,6 +39,13 @@ export interface SessionObservation {
    * greys it out until it is stopped/removed. No more frames are requested.
    */
   dead?: boolean;
+  /**
+   * The DSH conversations this session belongs to (the starting agent's
+   * session plus its seed-lineage ancestors), recorded at start. Scoped
+   * surfaces (the better-sidebar tab) filter by it; absent means untracked
+   * ownership — visible only in the global (unscoped) view.
+   */
+  dshSessionIds?: string[];
 }
 
 /** Incremental event carried to subscribers (SSE on the wire). */
@@ -83,6 +90,10 @@ export class ObservationService {
   private readonly listeners = new Set<(event: ObservationEvent) => void>();
   private readonly captureTimers = new Map<string, unknown>();
   private readonly captureInFlight = new Set<string>();
+  /** Captures intentionally cancelled to make way for foreground work. */
+  private readonly capturePreempted = new Set<string>();
+  /** Number of queued/running model-facing calls that currently outrank thumbnails. */
+  private readonly foregroundDepth = new Map<string, number>();
   private readonly captureFailures = new Map<string, number>();
   private readonly lastActivity = new Map<string, number>();
   /** Ephemeral frame id → PNG bytes. Only the live ring members are present. */
@@ -153,11 +164,13 @@ export class ObservationService {
   /** Register a fresh owned session (called from browser_session_start). */
   addSession(sessionId: string, url?: string): void {
     if (!this.deps.options.enabled || this.disposed) return;
+    const dshSessionIds = this.deps.registry.dshOwnersOf(sessionId);
     this.put({
       sessionId,
       ...(url !== undefined ? { url } : {}),
       action: "idle",
       since: this.scheduler.now(),
+      ...(dshSessionIds.length > 0 ? { dshSessionIds } : {}),
     });
     this.lastActivity.set(sessionId, this.scheduler.now());
     this.scheduleCapture(sessionId, 0);
@@ -166,6 +179,8 @@ export class ObservationService {
   /** Drop a session (called from browser_session_stop). */
   removeSession(sessionId: string): void {
     this.cancelCapture(sessionId);
+    this.foregroundDepth.delete(sessionId);
+    this.capturePreempted.delete(sessionId);
     this.captureFailures.delete(sessionId);
     this.lastActivity.delete(sessionId);
     this.dropSessionFrames(sessionId);
@@ -177,6 +192,37 @@ export class ObservationService {
     }
   }
 
+  /**
+   * Give model-facing work priority over the best-effort thumbnail lane.
+   * The first lease cancels a pending timer and gracefully interrupts an
+   * active bsk screenshot; the last release schedules one fresh frame.
+   */
+  acquireForeground(sessionId: string): () => void {
+    if (!this.deps.options.enabled || this.disposed || !this.observations.has(sessionId)) {
+      return () => {};
+    }
+    const depth = this.foregroundDepth.get(sessionId) ?? 0;
+    this.foregroundDepth.set(sessionId, depth + 1);
+    if (depth === 0) {
+      this.cancelCapture(sessionId);
+      if (this.deps.runner.killFor(`observation:${sessionId}`) > 0) {
+        this.capturePreempted.add(sessionId);
+      }
+    }
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const remaining = (this.foregroundDepth.get(sessionId) ?? 1) - 1;
+      if (remaining > 0) {
+        this.foregroundDepth.set(sessionId, remaining);
+        return;
+      }
+      this.foregroundDepth.delete(sessionId);
+      if (!this.disposed && this.observations.has(sessionId)) this.scheduleCapture(sessionId, 0);
+    };
+  }
+
   /** Mark an action starting on a session (tool entry instrumentation). */
   beginAction(sessionId: string, action: string): void {
     if (!this.deps.options.enabled || this.disposed) return;
@@ -204,7 +250,7 @@ export class ObservationService {
     if (error !== undefined) next.lastError = error;
     else delete next.lastError;
     this.put(next);
-    this.scheduleCapture(sessionId, 0);
+    if (!this.foregroundDepth.has(sessionId)) this.scheduleCapture(sessionId, 0);
   }
 
   /** Record the settled page URL (navigate success / start with url). */
@@ -228,6 +274,55 @@ export class ObservationService {
     return this.deps.runner.killFor(target) > 0;
   }
 
+  /**
+   * Stop one owned session and close its Agent Window (the overlay's stop
+   * button — same end state as `browser_session_stop`). Never waits behind a
+   * hung in-flight command: tool children are killed first so the session's
+   * keyed queue drains immediately, and no further captures queue up. A
+   * session the daemon already forgot stops idempotently — the goal state
+   * (entry gone) is identical.
+   * @returns false only for a foreign session; bsk failures reject so callers
+   * can preserve the structured error instead of silently leaving a ghost.
+   */
+  async stopSession(sessionId: string, signal?: AbortSignal): Promise<boolean> {
+    if (!this.deps.registry.isOwned(sessionId)) return false;
+    const releaseForeground = this.acquireForeground(sessionId);
+    let actionError: string | undefined;
+    this.beginAction(sessionId, "stopping");
+    try {
+      this.deps.runner.killFor(sessionId);
+      const result = await this.deps.queue.run(
+        sessionId,
+        () =>
+          runWithSessionBusyRetry(
+            () =>
+              this.deps.runner.run(["session", "stop", sessionId], {
+                signal,
+                timeoutMs: 30_000,
+                tag: sessionId,
+              }),
+            signal,
+          ),
+        signal,
+      );
+      if (result.aborted) throw abortError();
+      try {
+        parseBskJson(result, "session stop");
+      } catch (error) {
+        if (!isSessionNotFoundError(error)) throw error;
+      }
+      this.deps.registry.remove(sessionId);
+      this.removeSession(sessionId);
+      return true;
+    } catch (error) {
+      actionError = error instanceof Error ? error.message.split("\n")[0] : String(error);
+      throw error;
+    } finally {
+      this.endAction(sessionId, actionError);
+      releaseForeground();
+    }
+  }
+
   /**
    * Read one captured thumbnail from the in-process ring. Powers the plugin's
    * own HTTP thumbnail route — frames are plugin-owned runtime data, never
@@ -248,6 +343,8 @@ export class ObservationService {
     for (const sessionId of [...this.captureTimers.keys()]) this.cancelCapture(sessionId);
     this.captureTimers.clear();
     this.captureInFlight.clear();
+    this.capturePreempted.clear();
+    this.foregroundDepth.clear();
     this.captureFailures.clear();
     this.lastActivity.clear();
     this.frames.clear();
@@ -274,6 +371,7 @@ export class ObservationService {
   /** 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;
     this.cancelCapture(sessionId);
@@ -310,12 +408,15 @@ export class ObservationService {
     const outPath = join(tmpdir(), `bsk-obs-${this.scratchNamespace}-${sessionKey}.png`);
     let writtenPath = outPath;
     try {
-      const result = await this.deps.queue.run(sessionId, () =>
-        this.deps.runner.run(["screenshot", "--session", sessionId, "--out", outPath], {
+      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);
+        return this.deps.runner.run(["screenshot", "--session", sessionId, "--out", outPath], {
           timeoutMs: 15_000,
           tag: `observation:${sessionId}`,
-        }),
-      );
+        });
+      });
+      if (result === undefined) return;
       if (result.code !== 0) {
         let code: string | undefined;
         try {
@@ -323,8 +424,12 @@ export class ObservationService {
         } catch {
           code = undefined;
         }
-        if (code === "session_not_found") {
-          this.markDead(sessionId);
+        if (isSessionNotFoundCode(code)) {
+          // Observation entries are owned sessions. If the daemon has already
+          // forgotten one (external close / restart), reconcile both stores so
+          // the PiP cannot retain a ghost strip or keep retrying screenshots.
+          this.deps.registry.remove(sessionId);
+          this.removeSession(sessionId);
           return;
         }
         throw new Error(`screenshot exited ${result.code}`);
@@ -339,12 +444,17 @@ export class ObservationService {
       this.setAvailable(true);
       this.publishFrame(sessionId, entry, data);
     } catch {
-      // Silent by design: keep the previous frame, count toward backoff.
-      this.captureFailures.set(sessionId, (this.captureFailures.get(sessionId) ?? 0) + 1);
-      this.globalFailures += 1;
-      if (this.globalFailures >= FAILURE_BACKOFF_THRESHOLD) this.setAvailable(false);
+      // Foreground preemption is healthy scheduling, not browser/daemon
+      // unavailability; do not let normal tool traffic trip capture backoff.
+      if (!this.capturePreempted.delete(sessionId)) {
+        // Silent by design: keep the previous frame, count toward backoff.
+        this.captureFailures.set(sessionId, (this.captureFailures.get(sessionId) ?? 0) + 1);
+        this.globalFailures += 1;
+        if (this.globalFailures >= FAILURE_BACKOFF_THRESHOLD) this.setAvailable(false);
+      }
     } finally {
       await unlink(writtenPath).catch(() => {});
+      this.capturePreempted.delete(sessionId);
       this.captureInFlight.delete(sessionId);
       if (!this.disposed && this.observations.has(sessionId)) this.scheduleCapture(sessionId);
     }
@@ -375,14 +485,20 @@ export class ObservationService {
     this.hashes.delete(sessionId);
     this.seqs.delete(sessionId);
   }
+}
 
-  /** Mark a session dead: grey it out, stop asking for frames, keep the entry for the strip. */
-  private markDead(sessionId: string): void {
-    const entry = this.observations.get(sessionId);
-    if (entry === undefined || entry.dead === true) return;
-    this.cancelCapture(sessionId);
-    this.put({ ...entry, dead: true, action: "idle" });
-  }
+function isSessionNotFoundCode(code: string | undefined): boolean {
+  return code === "not_found" || code === "session_not_found";
+}
+
+function isSessionNotFoundError(error: unknown): boolean {
+  return error instanceof BskError && isSessionNotFoundCode(error.code);
+}
+
+function abortError(): Error {
+  const error = new Error("tool call aborted");
+  error.name = "AbortError";
+  return error;
 }
 
 /** Map a bsk command label onto its observation action verb. */
@@ -400,14 +516,48 @@ export function actionForLabel(label: string): string {
       return "observing";
     case "click":
       return "clicking";
+    case "hover":
+      return "hovering";
     case "fill":
       return "filling";
+    case "select":
+      return "selecting";
     case "press":
       return "pressing";
     case "screenshot":
       return "capturing";
     case "emulate":
       return "emulating";
+    case "tab list":
+      return "listing tabs";
+    case "tab create":
+      return "creating tab";
+    case "tab close":
+      return "closing tab";
+    case "tab select":
+      return "selecting tab";
+    case "tab borrow":
+      return "borrowing tab";
+    case "tab return":
+      return "returning tab";
+    case "navigate-back":
+      return "navigating back";
+    case "navigate-forward":
+      return "navigating forward";
+    case "reload":
+      return "reloading";
+    case "wait-for-navigation":
+      return "waiting for navigation";
+    case "request-help":
+      return "waiting for user";
+    case "get-html":
+      return "reading HTML";
+    case "console":
+      return "reading console";
+    case "network":
+      return "reading network";
+    case "window resize":
+      return "resizing window";
     default:
       return label;
   }

packages/dsh-plugin-browserskill/src/phase-one-runtime.ts

@@ -0,0 +1,58 @@
+import type { ToolDefinition, ToolResult, ToolRunContext } from "@deepseek-ai/dsh-tools";
+import type { ToolDeps } from "./tools";
+
+export type ToolRegistrar = (definition: ToolDefinition) => () => void;
+
+type TerminalPresentation = { card: "terminal"; output: string; exitCode: number } | undefined;
+
+/** Existing tool runtime seams reused by the phase-one capability modules. */
+export interface PhaseOneRuntime {
+  run(
+    exec: ToolRunContext,
+    args: string[],
+    label: string,
+    observeSession?: string,
+    runnerTimeoutMs?: number,
+  ): Promise<unknown>;
+  commandLine(args: string[]): string;
+  presentTerminalResult: (_args: never, result: ToolResult) => TerminalPresentation;
+}
+
+export function requireNonEmpty(value: string, name: string): void {
+  if (value.trim().length === 0) throw new Error(`${name} must be a non-empty string`);
+}
+
+export function requirePositive(value: number | undefined, name: string): void {
+  if (value !== undefined && value <= 0) throw new Error(`${name} must be greater than zero`);
+}
+
+/** CLI positional target detection is shared by hover/select/request-help. */
+export function isSnapshotRef(target: string): boolean {
+  return /^@?e\d+$/.test(target);
+}
+
+/**
+ * Give the child enough time to honour a command-level timeout plus IPC
+ * settlement slack, without shortening the plugin's configured default.
+ */
+export function runnerTimeout(deps: ToolDeps, commandTimeoutMs: number | undefined): number {
+  if (commandTimeoutMs === undefined) return deps.config.defaultTimeoutMs;
+  return Math.max(deps.config.defaultTimeoutMs, commandTimeoutMs + 15_000);
+}
+
+export function appendTarget(args: string[], target: string): void {
+  args.push(target);
+}
+
+export function appendTabId(args: string[], tabId: number | undefined): void {
+  if (tabId !== undefined) args.push("--tab-id", String(tabId));
+}
+
+export function appendWaitOptions(
+  args: string[],
+  waitUntil: string | undefined,
+  timeoutMs: number | undefined,
+): void {
+  if (waitUntil !== undefined) args.push("--wait-until", waitUntil);
+  if (timeoutMs !== undefined) args.push("--timeout", `${timeoutMs}ms`);
+}

packages/dsh-plugin-browserskill/src/phase-one-tools-interaction.ts

@@ -0,0 +1,197 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import {
+  appendTabId,
+  appendTarget,
+  type PhaseOneRuntime,
+  requireNonEmpty,
+  requirePositive,
+  runnerTimeout,
+  type ToolRegistrar,
+} from "./phase-one-runtime";
+import { SESSION_PARAM, TAB_ID_PARAM, TIMEOUT_MS_PARAM } from "./tool-params";
+import type { ToolDeps } from "./tools";
+
+const MODIFIERS = ["alt", "ctrl", "meta", "shift"] as const;
+
+/** Add hover and select without bypassing session ownership or observation. */
+export function registerPhaseOneInteractionTools(
+  deps: ToolDeps,
+  register: ToolRegistrar,
+  runtime: PhaseOneRuntime,
+): void {
+  const { registry } = deps;
+
+  register(
+    defineTool({
+      name: "browser_hover",
+      description:
+        "Move the mouse over a snapshot ref or CSS selector to reveal hover-triggered UI. " +
+        "Run browser_observe or browser_snapshot again afterwards to discover newly visible refs.",
+      parameters: {
+        target: {
+          type: "string",
+          required: true,
+          description: "Snapshot ref (@e3 / e3) or CSS selector of the element to hover.",
+        },
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        modifiers: {
+          type: "array",
+          items: { type: "string", enum: MODIFIERS },
+          description: "Keyboard modifiers held during the mouse move.",
+        },
+        settleMs: {
+          type: "integer",
+          description: "Milliseconds to wait for hover-triggered UI to settle (default: 200).",
+        },
+        timeoutMs: TIMEOUT_MS_PARAM,
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            x: { type: "number", required: true },
+            y: { type: "number", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text: `[session ${value.session}] hovered at (${value.x}, ${value.y}) on tab ${value.tabId}`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        requireNonEmpty(args.target, "target");
+        requirePositive(args.timeoutMs, "timeoutMs");
+        requirePositive(args.settleMs, "settleMs");
+        const sessionId = registry.resolve(args.session, "browser_hover");
+        const cmdArgs = ["hover", "--session", sessionId];
+        appendTabId(cmdArgs, args.tabId);
+        if (args.modifiers !== undefined && args.modifiers.length > 0) {
+          cmdArgs.push("--modifiers", args.modifiers.join(","));
+        }
+        if (args.settleMs !== undefined) cmdArgs.push("--settle", `${args.settleMs}ms`);
+        if (args.timeoutMs !== undefined) cmdArgs.push("--timeout", `${args.timeoutMs}ms`);
+        appendTarget(cmdArgs, args.target);
+        const reply = (await runtime.run(
+          exec,
+          cmdArgs,
+          "hover",
+          sessionId,
+          runnerTimeout(deps, args.timeoutMs),
+        )) as { tab_id: number; x: number; y: number };
+        return { session: sessionId, tabId: reply.tab_id, x: reply.x, y: reply.y };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "hover",
+          args.target,
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Hover an element",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_select",
+      description:
+        "Set a select element's option values. Pass one value for a normal select or multiple " +
+        "values for a multi-select; values replace the current selection.",
+      parameters: {
+        target: {
+          type: "string",
+          required: true,
+          description: "Snapshot ref (@e3 / e3) or CSS selector of the select element.",
+        },
+        values: {
+          type: "array",
+          required: true,
+          items: { type: "string" },
+          description: "Option value attributes to select; at least one value is required.",
+        },
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        timeoutMs: TIMEOUT_MS_PARAM,
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            multiple: { type: "boolean", required: true },
+            selectedValues: {
+              type: "array",
+              required: true,
+              items: { type: "string" },
+            },
+            selectedLabels: {
+              type: "array",
+              required: true,
+              items: { type: "string" },
+            },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] selected ` +
+              `${value.selectedValues.join(", ") || "(none)"} on tab ${value.tabId}`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        requireNonEmpty(args.target, "target");
+        requirePositive(args.timeoutMs, "timeoutMs");
+        if (args.values.length === 0) throw new Error("values must contain at least one option");
+        const sessionId = registry.resolve(args.session, "browser_select");
+        const cmdArgs = ["select", "--session", sessionId];
+        appendTabId(cmdArgs, args.tabId);
+        for (const value of args.values) cmdArgs.push("--value", value);
+        if (args.timeoutMs !== undefined) cmdArgs.push("--timeout", `${args.timeoutMs}ms`);
+        appendTarget(cmdArgs, args.target);
+        const reply = (await runtime.run(
+          exec,
+          cmdArgs,
+          "select",
+          sessionId,
+          runnerTimeout(deps, args.timeoutMs),
+        )) as {
+          tab_id: number;
+          multiple: boolean;
+          selected_values: string[];
+          selected_labels: string[];
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          multiple: reply.multiple,
+          selectedValues: reply.selected_values,
+          selectedLabels: reply.selected_labels,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "select",
+          args.target,
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: `Select ${args.values.length} option${args.values.length === 1 ? "" : "s"}`,
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+}

packages/dsh-plugin-browserskill/src/phase-one-tools-navigation.ts

@@ -0,0 +1,230 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import {
+  appendTabId,
+  appendWaitOptions,
+  type PhaseOneRuntime,
+  requirePositive,
+  runnerTimeout,
+  type ToolRegistrar,
+} from "./phase-one-runtime";
+import { SESSION_PARAM, TAB_ID_PARAM, TIMEOUT_MS_PARAM, WAIT_UNTIL_PARAM } from "./tool-params";
+import type { ToolDeps } from "./tools";
+
+interface RawHistoryResult {
+  tab_id: number;
+  previous_url?: string;
+  final_url?: string;
+  reached: string;
+  error_text?: string;
+}
+
+const HISTORY_OUTPUT = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    session: { type: "string", required: true },
+    tabId: { type: "integer", required: true },
+    previousUrl: { type: "string" },
+    finalUrl: { type: "string" },
+    reached: { type: "string", required: true },
+    errorText: { type: "string" },
+  },
+} as const;
+
+function mapHistory(sessionId: string, reply: RawHistoryResult) {
+  return {
+    session: sessionId,
+    tabId: reply.tab_id,
+    ...(reply.previous_url !== undefined ? { previousUrl: reply.previous_url } : {}),
+    ...(reply.final_url !== undefined ? { finalUrl: reply.final_url } : {}),
+    reached: reply.reached,
+    ...(reply.error_text !== undefined ? { errorText: reply.error_text } : {}),
+  };
+}
+
+/** Add browser history, reload, and explicit lifecycle waiting. */
+export function registerPhaseOneNavigationTools(
+  deps: ToolDeps,
+  register: ToolRegistrar,
+  runtime: PhaseOneRuntime,
+): void {
+  const { registry } = deps;
+
+  const registerHistory = (direction: "back" | "forward") => {
+    const toolName = `browser_navigate_${direction}` as const;
+    const command = `navigate-${direction}`;
+    register(
+      defineTool({
+        name: toolName,
+        description: `Navigate the active Agent Window tab ${direction} by one history entry.`,
+        parameters: {
+          session: SESSION_PARAM,
+          tabId: TAB_ID_PARAM,
+          waitUntil: WAIT_UNTIL_PARAM,
+          timeoutMs: TIMEOUT_MS_PARAM,
+        },
+        output: {
+          schema: HISTORY_OUTPUT,
+          render: (_args, value) => [
+            {
+              type: "text",
+              text:
+                `[session ${value.session}] navigated ${direction} on tab ${value.tabId}` +
+                (value.finalUrl !== undefined ? ` to ${value.finalUrl}` : "") +
+                ` (reached: ${value.reached})` +
+                (value.errorText !== undefined ? ` — ${value.errorText}` : ""),
+            },
+          ],
+        },
+        async execute(args, exec) {
+          requirePositive(args.timeoutMs, "timeoutMs");
+          const sessionId = registry.resolve(args.session, toolName);
+          const cmdArgs = [command, "--session", sessionId];
+          appendTabId(cmdArgs, args.tabId);
+          appendWaitOptions(cmdArgs, args.waitUntil, args.timeoutMs);
+          const reply = (await runtime.run(
+            exec,
+            cmdArgs,
+            command,
+            sessionId,
+            runnerTimeout(deps, args.timeoutMs),
+          )) as RawHistoryResult;
+          if (reply.final_url !== undefined) deps.observation.setUrl(sessionId, reply.final_url);
+          return mapHistory(sessionId, reply);
+        },
+        presentCall: (args) => ({
+          card: "terminal",
+          title: runtime.commandLine([command, "--session", args.session ?? "(current)"]),
+          description: `Navigate ${direction}`,
+        }),
+        presentResult: runtime.presentTerminalResult,
+      }),
+    );
+  };
+  registerHistory("back");
+  registerHistory("forward");
+
+  register(
+    defineTool({
+      name: "browser_reload",
+      description:
+        "Reload the active Agent Window tab and wait for a lifecycle phase. Set hard=true to " +
+        "bypass the HTTP cache.",
+      parameters: {
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        waitUntil: WAIT_UNTIL_PARAM,
+        timeoutMs: TIMEOUT_MS_PARAM,
+        hard: { type: "boolean", description: "Bypass the HTTP cache while reloading." },
+      },
+      output: {
+        schema: HISTORY_OUTPUT,
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] reloaded tab ${value.tabId}` +
+              (value.finalUrl !== undefined ? ` at ${value.finalUrl}` : "") +
+              ` (reached: ${value.reached})` +
+              (value.errorText !== undefined ? ` — ${value.errorText}` : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        requirePositive(args.timeoutMs, "timeoutMs");
+        const sessionId = registry.resolve(args.session, "browser_reload");
+        const cmdArgs = ["reload", "--session", sessionId];
+        appendTabId(cmdArgs, args.tabId);
+        appendWaitOptions(cmdArgs, args.waitUntil, args.timeoutMs);
+        if (args.hard === true) cmdArgs.push("--hard");
+        const reply = (await runtime.run(
+          exec,
+          cmdArgs,
+          "reload",
+          sessionId,
+          runnerTimeout(deps, args.timeoutMs),
+        )) as RawHistoryResult;
+        if (reply.final_url !== undefined) deps.observation.setUrl(sessionId, reply.final_url);
+        return mapHistory(sessionId, reply);
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "reload",
+          "--session",
+          args.session ?? "(current)",
+          ...(args.hard === true ? ["--hard"] : []),
+        ]),
+        description: "Reload the active tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_wait_for_navigation",
+      description:
+        "Wait for a page lifecycle event on the active Agent Window tab. Use after an action " +
+        "that may navigate when the action result itself does not wait for navigation.",
+      parameters: {
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        waitUntil: WAIT_UNTIL_PARAM,
+        timeoutMs: TIMEOUT_MS_PARAM,
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            reached: { type: "string", required: true },
+            errorText: { type: "string" },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] navigation wait on tab ${value.tabId}: ${value.reached}` +
+              (value.errorText !== undefined ? ` — ${value.errorText}` : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        requirePositive(args.timeoutMs, "timeoutMs");
+        const sessionId = registry.resolve(args.session, "browser_wait_for_navigation");
+        const timeoutMs = args.timeoutMs ?? 30_000;
+        const cmdArgs = ["wait-for-navigation", "--session", sessionId];
+        appendTabId(cmdArgs, args.tabId);
+        if (args.waitUntil !== undefined) cmdArgs.push("--wait-until", args.waitUntil);
+        cmdArgs.push("--timeout", `${timeoutMs}ms`);
+        const reply = (await runtime.run(
+          exec,
+          cmdArgs,
+          "wait-for-navigation",
+          sessionId,
+          runnerTimeout(deps, timeoutMs),
+        )) as { tab_id: number; reached: string; error_text?: string };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          reached: reply.reached,
+          ...(reply.error_text !== undefined ? { errorText: reply.error_text } : {}),
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "wait-for-navigation",
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Wait for page navigation",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+}

packages/dsh-plugin-browserskill/src/phase-one-tools-support.ts

@@ -0,0 +1,672 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import {
+  appendTabId,
+  isSnapshotRef,
+  type PhaseOneRuntime,
+  requireNonEmpty,
+  requirePositive,
+  runnerTimeout,
+  type ToolRegistrar,
+} from "./phase-one-runtime";
+import { SESSION_PARAM, TAB_ID_PARAM, TIMEOUT_MS_PARAM } from "./tool-params";
+import type { ToolDeps } from "./tools";
+
+interface HelpConditionInput {
+  urlContains?: string;
+  urlMatches?: string;
+  selectorExists?: string;
+  selectorMissing?: string;
+  textExists?: string;
+  textMissing?: string;
+}
+
+interface CompletionCriteriaInput {
+  any?: HelpConditionInput[];
+  all?: HelpConditionInput[];
+  stableForMs?: number;
+}
+
+interface RawConsoleFrame {
+  function_name?: string;
+  url?: string;
+  line?: number;
+  column?: number;
+}
+
+interface RawConsoleEntry {
+  sequence: number;
+  kind: string;
+  level: string;
+  text: string;
+  url?: string;
+  line?: number;
+  column?: number;
+  timestamp?: number;
+  stack_trace?: RawConsoleFrame[];
+  truncated?: boolean;
+}
+
+interface RawNetworkEntry {
+  sequence: number;
+  kind: "response" | "failure";
+  method?: string;
+  url?: string;
+  status?: number;
+  status_text?: string;
+  mime_type?: string;
+  resource_type?: string;
+  error_text?: string;
+  timestamp?: number;
+  truncated?: boolean;
+}
+
+const HELP_CONDITION_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    urlContains: { type: "string" },
+    urlMatches: { type: "string" },
+    selectorExists: { type: "string" },
+    selectorMissing: { type: "string" },
+    textExists: { type: "string" },
+    textMissing: { type: "string" },
+  },
+} as const;
+
+const DEBUG_PARAMETERS = {
+  session: SESSION_PARAM,
+  tabId: TAB_ID_PARAM,
+  since: {
+    type: "integer",
+    description: "Return entries with a sequence strictly greater than this cursor.",
+  },
+  limit: {
+    type: "integer",
+    description: "Maximum entries to return (default: 50, daemon cap: 200).",
+  },
+  maxTextChars: {
+    type: "integer",
+    description: "Maximum characters per entry text/URL (default: 1000, daemon cap: 4096).",
+  },
+} as const;
+
+function mapCondition(condition: HelpConditionInput) {
+  return {
+    ...(condition.urlContains !== undefined ? { url_contains: condition.urlContains } : {}),
+    ...(condition.urlMatches !== undefined ? { url_matches: condition.urlMatches } : {}),
+    ...(condition.selectorExists !== undefined
+      ? { selector_exists: condition.selectorExists }
+      : {}),
+    ...(condition.selectorMissing !== undefined
+      ? { selector_missing: condition.selectorMissing }
+      : {}),
+    ...(condition.textExists !== undefined ? { text_exists: condition.textExists } : {}),
+    ...(condition.textMissing !== undefined ? { text_missing: condition.textMissing } : {}),
+  };
+}
+
+function mapCompletionCriteria(criteria: CompletionCriteriaInput) {
+  return {
+    ...(criteria.any !== undefined ? { any: criteria.any.map(mapCondition) } : {}),
+    ...(criteria.all !== undefined ? { all: criteria.all.map(mapCondition) } : {}),
+    ...(criteria.stableForMs !== undefined ? { stable_for_ms: criteria.stableForMs } : {}),
+  };
+}
+
+function validateDebugArgs(args: { since?: number; limit?: number; maxTextChars?: number }): void {
+  if (args.since !== undefined && args.since < 0) {
+    throw new Error("since must be zero or greater");
+  }
+  requirePositive(args.limit, "limit");
+  requirePositive(args.maxTextChars, "maxTextChars");
+}
+
+function appendDebugOptions(
+  args: string[],
+  options: { tabId?: number; since?: number; limit?: number; maxTextChars?: number },
+): void {
+  appendTabId(args, options.tabId);
+  if (options.since !== undefined) args.push("--since", String(options.since));
+  if (options.limit !== undefined) args.push("--limit", String(options.limit));
+  if (options.maxTextChars !== undefined) {
+    args.push("--max-text-chars", String(options.maxTextChars));
+  }
+}
+
+/** Human help, raw HTML, diagnostics, and Agent Window sizing. */
+export function registerPhaseOneSupportTools(
+  deps: ToolDeps,
+  register: ToolRegistrar,
+  runtime: PhaseOneRuntime,
+): void {
+  const { registry } = deps;
+
+  register(
+    defineTool({
+      name: "browser_request_help",
+      description:
+        "Pause browser automation and ask the user to complete an in-page step such as login, " +
+        "captcha, OTP, or confirmation. After continued/completed, observe again before using refs.",
+      parameters: {
+        prompt: {
+          type: "string",
+          required: true,
+          description: "Clear instructions shown to the user in the browser help overlay.",
+        },
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        title: { type: "string", description: "Optional title for the help overlay." },
+        targets: {
+          type: "array",
+          items: { type: "string" },
+          description: "Snapshot refs or CSS selectors to scroll to and highlight for the user.",
+        },
+        timeoutMs: {
+          ...TIMEOUT_MS_PARAM,
+          description: "Maximum wait for the user in milliseconds (default: 300000).",
+        },
+        completionCriteria: {
+          type: "object",
+          additionalProperties: false,
+          description: "Optional explicit success detector for automatic completion.",
+          properties: {
+            any: { type: "array", items: HELP_CONDITION_SCHEMA },
+            all: { type: "array", items: HELP_CONDITION_SCHEMA },
+            stableForMs: {
+              type: "integer",
+              description: "How long criteria must remain true before completing.",
+            },
+          },
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            outcome: {
+              type: "string",
+              required: true,
+              enum: ["continued", "cancelled", "timed_out", "completed", "navigated", "disabled"],
+            },
+            completedBy: { type: "string" },
+            note: { type: "string" },
+            resolvedTargets: {
+              type: "array",
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  matched: { type: "boolean", required: true },
+                  ref: { type: "string" },
+                  selector: { type: "string" },
+                },
+              },
+            },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] user help outcome on tab ${value.tabId}: ${value.outcome}` +
+              (value.note !== undefined ? ` — ${value.note}` : "") +
+              (value.resolvedTargets !== undefined
+                ? `\ntargets: ${value.resolvedTargets
+                    .map(
+                      (target) =>
+                        `${target.ref ?? target.selector ?? "(unknown)"}=${target.matched ? "matched" : "not found"}`,
+                    )
+                    .join(", ")}`
+                : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        requireNonEmpty(args.prompt, "prompt");
+        if (args.title !== undefined) requireNonEmpty(args.title, "title");
+        requirePositive(args.timeoutMs, "timeoutMs");
+        for (const target of args.targets ?? []) requireNonEmpty(target, "target");
+        const criteria = args.completionCriteria as CompletionCriteriaInput | undefined;
+        if (criteria?.stableForMs !== undefined && criteria.stableForMs < 0) {
+          throw new Error("completionCriteria.stableForMs must be zero or greater");
+        }
+        const sessionId = registry.resolve(args.session, "browser_request_help");
+        const timeoutMs = args.timeoutMs ?? 300_000;
+        const cmdArgs = [
+          "request-help",
+          "--session",
+          sessionId,
+          "--prompt",
+          args.prompt,
+          "--timeout",
+          `${timeoutMs}ms`,
+        ];
+        appendTabId(cmdArgs, args.tabId);
+        if (args.title !== undefined) cmdArgs.push("--title", args.title);
+        for (const target of args.targets ?? []) cmdArgs.push("--target", target);
+        if (criteria !== undefined) {
+          cmdArgs.push("--completion-criteria", JSON.stringify(mapCompletionCriteria(criteria)));
+        }
+        const reply = (await runtime.run(
+          exec,
+          cmdArgs,
+          "request-help",
+          sessionId,
+          runnerTimeout(deps, timeoutMs),
+        )) as {
+          outcome: "continued" | "cancelled" | "timed_out" | "completed" | "navigated" | "disabled";
+          completed_by?: string;
+          note?: string;
+          tab_id: number;
+          resolved_targets?: { matched: boolean; ref?: string; selector?: string }[];
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          outcome: reply.outcome,
+          ...(reply.completed_by !== undefined ? { completedBy: reply.completed_by } : {}),
+          ...(reply.note !== undefined ? { note: reply.note } : {}),
+          ...(reply.resolved_targets !== undefined
+            ? { resolvedTargets: reply.resolved_targets }
+            : {}),
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine(["request-help", "--session", args.session ?? "(current)"]),
+        description: "Ask the user for browser help",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_get_html",
+      description:
+        "Read raw DOM HTML from the active Agent Window tab, optionally scoped to a fresh " +
+        "snapshot ref. Use only when browser_observe/browser_snapshot cannot answer the question.",
+      parameters: {
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        ref: { type: "string", description: "Fresh snapshot ref that scopes the HTML subtree." },
+        maxBytes: {
+          type: "integer",
+          description: "Maximum returned HTML bytes before truncation (default: 524288).",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            html: { type: "string", required: true },
+            truncated: { type: "boolean", required: true },
+            byteSize: { type: "integer", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              value.html +
+              (value.truncated ? `\n(HTML truncated; original size ${value.byteSize} bytes)` : ""),
+          },
+        ],
+      },
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        if (args.ref !== undefined) {
+          requireNonEmpty(args.ref, "ref");
+          if (!isSnapshotRef(args.ref)) throw new Error("ref must be a snapshot ref such as @e3");
+        }
+        requirePositive(args.maxBytes, "maxBytes");
+        const sessionId = registry.resolve(args.session, "browser_get_html");
+        const cmdArgs = ["get-html", "--session", sessionId];
+        appendTabId(cmdArgs, args.tabId);
+        if (args.ref !== undefined) cmdArgs.push("--ref", args.ref);
+        if (args.maxBytes !== undefined) cmdArgs.push("--max-bytes", String(args.maxBytes));
+        const reply = (await runtime.run(exec, cmdArgs, "get-html", sessionId)) as {
+          tab_id: number;
+          html: string;
+          truncated?: boolean;
+          byte_size: number;
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          html: reply.html,
+          truncated: reply.truncated ?? false,
+          byteSize: reply.byte_size,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "get-html",
+          "--session",
+          args.session ?? "(current)",
+          ...(args.ref !== undefined ? ["--ref", args.ref] : []),
+        ]),
+        description: "Read raw page HTML",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_console",
+      description:
+        "Read buffered console messages, browser log entries, and JavaScript exceptions from a tab. " +
+        "This is read-only and does not evaluate JavaScript.",
+      parameters: {
+        ...DEBUG_PARAMETERS,
+        includeStack: {
+          type: "boolean",
+          description: "Include structured stack frames in returned console entries.",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            entries: {
+              type: "array",
+              required: true,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  sequence: { type: "integer", required: true },
+                  kind: { type: "string", required: true },
+                  level: { type: "string", required: true },
+                  text: { type: "string", required: true },
+                  url: { type: "string" },
+                  line: { type: "integer" },
+                  column: { type: "integer" },
+                  timestamp: { type: "number" },
+                  stackTrace: {
+                    type: "array",
+                    required: true,
+                    items: {
+                      type: "object",
+                      additionalProperties: false,
+                      properties: {
+                        functionName: { type: "string" },
+                        url: { type: "string" },
+                        line: { type: "integer" },
+                        column: { type: "integer" },
+                      },
+                    },
+                  },
+                  truncated: { type: "boolean", required: true },
+                },
+              },
+            },
+            nextSince: { type: "integer", required: true },
+            truncated: { type: "boolean", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              value.entries.length === 0
+                ? "(no console messages captured)"
+                : value.entries
+                    .map((entry) => {
+                      const location =
+                        entry.url === undefined
+                          ? ""
+                          : ` ${entry.url}${entry.line !== undefined ? `:${entry.line}` : ""}${entry.column !== undefined ? `:${entry.column}` : ""}`;
+                      const stack = entry.stackTrace
+                        .map(
+                          (frame) =>
+                            `\n  at ${frame.functionName ?? "<anonymous>"} ${frame.url ?? ""}` +
+                            `${frame.line !== undefined ? `:${frame.line}` : ""}` +
+                            `${frame.column !== undefined ? `:${frame.column}` : ""}`,
+                        )
+                        .join("");
+                      return `#${entry.sequence} ${entry.level} ${entry.kind}${location} ${entry.text}${stack}`;
+                    })
+                    .join("\n") +
+                  (value.truncated
+                    ? `\n(output truncated; continue with since=${value.nextSince})`
+                    : ""),
+          },
+        ],
+      },
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        validateDebugArgs(args);
+        const sessionId = registry.resolve(args.session, "browser_console");
+        const cmdArgs = ["console", "--session", sessionId];
+        appendDebugOptions(cmdArgs, args);
+        if (args.includeStack === true) cmdArgs.push("--include-stack");
+        const reply = (await runtime.run(exec, cmdArgs, "console", sessionId)) as {
+          tab_id: number;
+          entries?: RawConsoleEntry[];
+          next_since: number;
+          truncated?: boolean;
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          entries: (reply.entries ?? []).map((entry) => ({
+            sequence: entry.sequence,
+            kind: entry.kind,
+            level: entry.level,
+            text: entry.text,
+            ...(entry.url !== undefined ? { url: entry.url } : {}),
+            ...(entry.line !== undefined ? { line: entry.line } : {}),
+            ...(entry.column !== undefined ? { column: entry.column } : {}),
+            ...(entry.timestamp !== undefined ? { timestamp: entry.timestamp } : {}),
+            stackTrace: (entry.stack_trace ?? []).map((frame) => ({
+              ...(frame.function_name !== undefined ? { functionName: frame.function_name } : {}),
+              ...(frame.url !== undefined ? { url: frame.url } : {}),
+              ...(frame.line !== undefined ? { line: frame.line } : {}),
+              ...(frame.column !== undefined ? { column: frame.column } : {}),
+            })),
+            truncated: entry.truncated ?? false,
+          })),
+          nextSince: reply.next_since,
+          truncated: reply.truncated ?? false,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine(["console", "--session", args.session ?? "(current)"]),
+        description: "Read browser console messages",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_network",
+      description:
+        "Read buffered network responses and failures from a tab. Returns metadata only; request " +
+        "and response headers and bodies are not captured.",
+      parameters: DEBUG_PARAMETERS,
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            entries: {
+              type: "array",
+              required: true,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  sequence: { type: "integer", required: true },
+                  kind: { type: "string", required: true, enum: ["response", "failure"] },
+                  method: { type: "string" },
+                  url: { type: "string" },
+                  status: { type: "integer" },
+                  statusText: { type: "string" },
+                  mimeType: { type: "string" },
+                  resourceType: { type: "string" },
+                  errorText: { type: "string" },
+                  timestamp: { type: "number" },
+                  truncated: { type: "boolean", required: true },
+                },
+              },
+            },
+            nextSince: { type: "integer", required: true },
+            truncated: { type: "boolean", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              value.entries.length === 0
+                ? "(no network activity captured)"
+                : value.entries
+                    .map((entry) =>
+                      entry.kind === "failure"
+                        ? `#${entry.sequence} FAILED ${entry.method ?? "?"} ${entry.url ?? "(unknown)"} — ${entry.errorText ?? "failed"}`
+                        : `#${entry.sequence} ${entry.status ?? "?"} ${entry.method ?? "?"} ${entry.url ?? "(unknown)"}`,
+                    )
+                    .join("\n") +
+                  (value.truncated
+                    ? `\n(output truncated; continue with since=${value.nextSince})`
+                    : ""),
+          },
+        ],
+      },
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        validateDebugArgs(args);
+        const sessionId = registry.resolve(args.session, "browser_network");
+        const cmdArgs = ["network", "--session", sessionId];
+        appendDebugOptions(cmdArgs, args);
+        const reply = (await runtime.run(exec, cmdArgs, "network", sessionId)) as {
+          tab_id: number;
+          entries?: RawNetworkEntry[];
+          next_since: number;
+          truncated?: boolean;
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          entries: (reply.entries ?? []).map((entry) => ({
+            sequence: entry.sequence,
+            kind: entry.kind,
+            ...(entry.method !== undefined ? { method: entry.method } : {}),
+            ...(entry.url !== undefined ? { url: entry.url } : {}),
+            ...(entry.status !== undefined ? { status: entry.status } : {}),
+            ...(entry.status_text !== undefined ? { statusText: entry.status_text } : {}),
+            ...(entry.mime_type !== undefined ? { mimeType: entry.mime_type } : {}),
+            ...(entry.resource_type !== undefined ? { resourceType: entry.resource_type } : {}),
+            ...(entry.error_text !== undefined ? { errorText: entry.error_text } : {}),
+            ...(entry.timestamp !== undefined ? { timestamp: entry.timestamp } : {}),
+            truncated: entry.truncated ?? false,
+          })),
+          nextSince: reply.next_since,
+          truncated: reply.truncated ?? false,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine(["network", "--session", args.session ?? "(current)"]),
+        description: "Read browser network activity",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_window_resize",
+      description: "Resize the owned session's Agent Window using outer CSS-pixel dimensions.",
+      parameters: {
+        width: {
+          type: "integer",
+          required: true,
+          description: "Agent Window outer width in CSS pixels (100..=7680).",
+        },
+        height: {
+          type: "integer",
+          required: true,
+          description: "Agent Window outer height in CSS pixels (100..=7680).",
+        },
+        session: SESSION_PARAM,
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            windowId: { type: "integer", required: true },
+            width: { type: "integer", required: true },
+            height: { type: "integer", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text: `[session ${value.session}] resized window ${value.windowId} to ${value.width}x${value.height}`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        if (args.width < 100 || args.width > 7680 || args.height < 100 || args.height > 7680) {
+          throw new Error("width and height must each be in the range 100..=7680");
+        }
+        const sessionId = registry.resolve(args.session, "browser_window_resize");
+        const reply = (await runtime.run(
+          exec,
+          [
+            "window",
+            "resize",
+            "--session",
+            sessionId,
+            "--width",
+            String(args.width),
+            "--height",
+            String(args.height),
+          ],
+          "window resize",
+          sessionId,
+        )) as { window_id: number; width: number; height: number };
+        return {
+          session: sessionId,
+          windowId: reply.window_id,
+          width: reply.width,
+          height: reply.height,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "window",
+          "resize",
+          "--session",
+          args.session ?? "(current)",
+          "--width",
+          String(args.width),
+          "--height",
+          String(args.height),
+        ]),
+        description: "Resize the Agent Window",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+}

packages/dsh-plugin-browserskill/src/phase-one-tools-tabs.ts

@@ -0,0 +1,402 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import type { PhaseOneRuntime, ToolRegistrar } from "./phase-one-runtime";
+import { requireNonEmpty } from "./phase-one-runtime";
+import { SESSION_PARAM } from "./tool-params";
+import type { ToolDeps } from "./tools";
+
+const TAB_ID_REQUIRED = {
+  type: "integer",
+  required: true,
+  description: "Chrome tab id returned by browser_tab_list or browser_tab_create.",
+} as const;
+
+interface RawTabInfo {
+  tab_id: number;
+  title?: string;
+  url?: string;
+  window_id?: number;
+  active?: boolean;
+  scope?: "user" | "agent";
+}
+
+/** Add Agent Window tab management while preserving the owned-session boundary. */
+export function registerPhaseOneTabTools(
+  deps: ToolDeps,
+  register: ToolRegistrar,
+  runtime: PhaseOneRuntime,
+): void {
+  const { registry } = deps;
+
+  register(
+    defineTool({
+      name: "browser_tab_list",
+      description:
+        "List tabs visible to an owned browser session. Other sessions' Agent Windows remain " +
+        "hidden; use scope=user to find a user tab before borrowing it.",
+      parameters: {
+        session: SESSION_PARAM,
+        scope: {
+          type: "string",
+          enum: ["user", "agent", "all"],
+          description: "Which tabs to list (default: all).",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabs: {
+              type: "array",
+              required: true,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  tabId: { type: "integer", required: true },
+                  title: { type: "string" },
+                  url: { type: "string" },
+                  windowId: { type: "integer" },
+                  active: { type: "boolean" },
+                  scope: { type: "string", enum: ["user", "agent"] },
+                },
+              },
+            },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              value.tabs.length === 0
+                ? `[session ${value.session}] no matching tabs`
+                : value.tabs
+                    .map(
+                      (tab) =>
+                        `${tab.tabId} [${tab.scope ?? "unknown"}]${tab.active === true ? " [active]" : ""} ` +
+                        `${tab.title ?? "(untitled)"} — ${tab.url ?? "(unknown URL)"}`,
+                    )
+                    .join("\n"),
+          },
+        ],
+      },
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        const sessionId = registry.resolve(args.session, "browser_tab_list");
+        const cmdArgs = ["tab", "list", "--session", sessionId];
+        if (args.scope !== undefined) cmdArgs.push("--scope", args.scope);
+        const reply = (await runtime.run(exec, cmdArgs, "tab list", sessionId)) as {
+          tabs: RawTabInfo[];
+        };
+        return {
+          session: sessionId,
+          tabs: reply.tabs.map((tab) => ({
+            tabId: tab.tab_id,
+            ...(tab.title !== undefined ? { title: tab.title } : {}),
+            ...(tab.url !== undefined ? { url: tab.url } : {}),
+            ...(tab.window_id !== undefined ? { windowId: tab.window_id } : {}),
+            ...(tab.active !== undefined ? { active: tab.active } : {}),
+            ...(tab.scope !== undefined ? { scope: tab.scope } : {}),
+          })),
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "list",
+          "--session",
+          args.session ?? "(current)",
+          ...(args.scope !== undefined ? ["--scope", args.scope] : []),
+        ]),
+        description: "List browser tabs",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_tab_create",
+      description:
+        "Create a tab inside the owned session's Agent Window. The tab is focused by default; " +
+        "set active=false to open it in the background.",
+      parameters: {
+        session: SESSION_PARAM,
+        url: { type: "string", description: "Initial URL (default: chrome://newtab/)." },
+        active: { type: "boolean", description: "Whether to focus the new tab (default: true)." },
+        index: { type: "integer", description: "Insertion index in the Agent Window tab strip." },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            windowId: { type: "integer", required: true },
+            url: { type: "string", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text: `[session ${value.session}] created tab ${value.tabId} in window ${value.windowId} (${value.url || "pending URL"})`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        if (args.url !== undefined) requireNonEmpty(args.url, "url");
+        const sessionId = registry.resolve(args.session, "browser_tab_create");
+        const cmdArgs = ["tab", "create", "--session", sessionId];
+        if (args.url !== undefined) cmdArgs.push("--url", args.url);
+        if (args.active === false) cmdArgs.push("--no-active");
+        if (args.index !== undefined) cmdArgs.push("--index", String(args.index));
+        const reply = (await runtime.run(exec, cmdArgs, "tab create", sessionId)) as {
+          tab_id: number;
+          window_id: number;
+          url: string;
+        };
+        if (args.active !== false && reply.url.length > 0) {
+          deps.observation.setUrl(sessionId, reply.url);
+        }
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          windowId: reply.window_id,
+          url: reply.url,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "create",
+          "--session",
+          args.session ?? "(current)",
+          ...(args.url !== undefined ? ["--url", args.url] : []),
+        ]),
+        description: "Create an Agent Window tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_tab_close",
+      description: "Close a tab in the owned session's Agent Window.",
+      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+          },
+        },
+        render: (_args, value) => [
+          { type: "text", text: `[session ${value.session}] closed tab ${value.tabId}` },
+        ],
+      },
+      async execute(args, exec) {
+        const sessionId = registry.resolve(args.session, "browser_tab_close");
+        const reply = (await runtime.run(
+          exec,
+          ["tab", "close", String(args.tabId), "--session", sessionId],
+          "tab close",
+          sessionId,
+        )) as { tab_id: number };
+        return { session: sessionId, tabId: reply.tab_id };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "close",
+          String(args.tabId),
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Close an Agent Window tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_tab_select",
+      description: "Focus a tab in the owned session's Agent Window.",
+      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            windowId: { type: "integer", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text: `[session ${value.session}] selected tab ${value.tabId} in window ${value.windowId}`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        const sessionId = registry.resolve(args.session, "browser_tab_select");
+        const reply = (await runtime.run(
+          exec,
+          ["tab", "select", String(args.tabId), "--session", sessionId],
+          "tab select",
+          sessionId,
+        )) as { tab_id: number; window_id: number };
+        return { session: sessionId, tabId: reply.tab_id, windowId: reply.window_id };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "select",
+          String(args.tabId),
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Select an Agent Window tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_tab_borrow",
+      description:
+        "Move a user-window tab into the owned session's Agent Window for controlled interaction. " +
+        "Return it with browser_tab_return when finished; stopping the session also auto-returns it.",
+      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            originalWindowId: { type: "integer", required: true },
+            originalIndex: { type: "integer", required: true },
+            agentWindowId: { type: "integer", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] borrowed tab ${value.tabId} from window ` +
+              `${value.originalWindowId} into Agent Window ${value.agentWindowId}`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        const sessionId = registry.resolve(args.session, "browser_tab_borrow");
+        const reply = (await runtime.run(
+          exec,
+          ["tab", "borrow", String(args.tabId), "--session", sessionId],
+          "tab borrow",
+          sessionId,
+        )) as {
+          tab_id: number;
+          original_window_id: number;
+          original_index: number;
+          agent_window_id: number;
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          originalWindowId: reply.original_window_id,
+          originalIndex: reply.original_index,
+          agentWindowId: reply.agent_window_id,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "borrow",
+          String(args.tabId),
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Borrow a user tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_tab_return",
+      description: "Return a borrowed tab to its original user window and tab-strip position.",
+      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            returnedToWindowId: { type: "integer", required: true },
+            returnedToIndex: { type: "integer", required: true },
+            fallback: { type: "boolean", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] returned tab ${value.tabId} to window ` +
+              `${value.returnedToWindowId} at index ${value.returnedToIndex}` +
+              (value.fallback ? " (original window unavailable; used fallback)" : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        const sessionId = registry.resolve(args.session, "browser_tab_return");
+        const reply = (await runtime.run(
+          exec,
+          ["tab", "return", String(args.tabId), "--session", sessionId],
+          "tab return",
+          sessionId,
+        )) as {
+          tab_id: number;
+          returned_to_window_id: number;
+          returned_to_index: number;
+          fallback?: boolean;
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          returnedToWindowId: reply.returned_to_window_id,
+          returnedToIndex: reply.returned_to_index,
+          fallback: reply.fallback ?? false,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "return",
+          String(args.tabId),
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Return a borrowed tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+}

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

@@ -0,0 +1,18 @@
+import type { PhaseOneRuntime, ToolRegistrar } from "./phase-one-runtime";
+import { registerPhaseOneInteractionTools } from "./phase-one-tools-interaction";
+import { registerPhaseOneNavigationTools } from "./phase-one-tools-navigation";
+import { registerPhaseOneSupportTools } from "./phase-one-tools-support";
+import { registerPhaseOneTabTools } from "./phase-one-tools-tabs";
+import type { ToolDeps } from "./tools";
+
+/** Register the first DSH capability-parity tranche on the existing runtime. */
+export function registerPhaseOneTools(
+  deps: ToolDeps,
+  register: ToolRegistrar,
+  runtime: PhaseOneRuntime,
+): void {
+  registerPhaseOneInteractionTools(deps, register, runtime);
+  registerPhaseOneTabTools(deps, register, runtime);
+  registerPhaseOneNavigationTools(deps, register, runtime);
+  registerPhaseOneSupportTools(deps, register, runtime);
+}

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

@@ -64,14 +64,17 @@ export interface BskRunner {
   killFor(tag: string): number;
 }
 
-const KILL_GRACE_MS = 2000;
+// Business RPCs translate SIGINT into the daemon's cancel(rpc_id) protocol.
+// Give that bounded reconciliation path time to settle before the hard kill.
+const KILL_GRACE_MS = 3000;
+const SESSION_BUSY_RETRY_DELAY_MS = 100;
 
 export function createBskRunner(bskPath: string, spawnImpl: SpawnImpl = spawn): BskRunner {
   const live = new Map<ChildProcess, string | undefined>();
 
   function killChild(child: ChildProcess): void {
     if (child.exitCode !== null || child.signalCode !== null) return;
-    child.kill("SIGTERM");
+    child.kill("SIGINT");
     const force = setTimeout(() => {
       if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
     }, KILL_GRACE_MS);
@@ -163,6 +166,60 @@ export function isCommandNotFound(error: unknown): boolean {
   );
 }
 
+/** True only for the daemon's transient per-session reconciliation window. */
+export function isSessionBusyResult(result: BskRunResult): boolean {
+  if (result.code === 0) return false;
+  try {
+    const body = JSON.parse(result.stdout) as BskErrorBody;
+    const reason =
+      typeof body.data === "object" && body.data !== null && "reason" in body.data
+        ? (body.data as { reason?: unknown }).reason
+        : undefined;
+    return reason === "session_busy";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Retry exactly once after the tiny daemon-settlement race that can follow a
+ * graceful SIGINT cancellation. Other errors and persistent busy states stay
+ * visible to callers.
+ */
+export async function runWithSessionBusyRetry(
+  run: () => Promise<BskRunResult>,
+  signal?: AbortSignal,
+): Promise<BskRunResult> {
+  const first = await run();
+  if (!isSessionBusyResult(first)) return first;
+  await abortableDelay(SESSION_BUSY_RETRY_DELAY_MS, signal);
+  return run();
+}
+
+function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.reject(abortError());
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, ms);
+    timer.unref();
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(abortError());
+    };
+    function done() {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function abortError(): Error {
+  const error = new Error("tool call aborted");
+  error.name = "AbortError";
+  return error;
+}
+
 /** Install guidance shown when the bsk CLI cannot be spawned. */
 export function bskInstallMessage(bskPath: string): string {
   return (
@@ -182,7 +239,7 @@ export function parseBskJson(result: BskRunResult, commandLabel: string): unknow
     throw new BskError(`bsk ${commandLabel} timed out`, { timedOut: true });
   }
   const body = result.stdout.trim();
-  // Killed by our own interrupt (SIGTERM from killFor), not by the abort path:
+  // Killed by our own interrupt (SIGINT from killFor), not by the abort path:
   // say so instead of doubling the generic label into the message.
   if (result.code === null && !result.aborted && !result.timedOut) {
     throw new BskError(`bsk ${commandLabel} was interrupted (process killed)`);

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

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

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

@@ -2,13 +2,14 @@
  * Progressive disclosure of the BrowserSkill agent skill through the harness's
  * official skill seam (`ctx.skills`). The catalog entry (name + description)
  * is resident; the body is loaded only when the model invokes the `skill`
- * tool. The markdown is build-time assembled into a static module (dsh
- * prelude + the canonical CLI skill body verbatim), so registration and every
- * pre-step catalog snapshot are pure in-memory reads — no disk, no process,
- * no daemon.
+ * tool. The dedicated DeepSeek Harness markdown is embedded into a static
+ * module at build time, so registration and every pre-step catalog snapshot
+ * are pure in-memory reads — no disk, no process, no daemon. The CLI-oriented
+ * repository skill is intentionally a separate interface.
  */
 
 import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
 import {
   BSK_SKILL_DESCRIPTION,
   BSK_SKILL_MARKDOWN,
@@ -25,8 +26,13 @@ interface SkillsLike {
   }): () => void;
 }
 
+/** Structural view of the live-agent registry (absent in bare compositions). */
+interface AgentsLike {
+  list(): Agent[];
+}
+
 /**
- * Publish the BSK skill as an embedded runtime skill. Returns the unregistration
+ * Publish the browser skill as an embedded runtime skill. Returns the unregistration
  * disposer. A composition without the `skills` service (or with dsh-tool-skill
  * retired) leaves the rest of the plugin unaffected — the no-op is silent.
  */
@@ -43,3 +49,54 @@ export function registerBskSkill(ctx: Context): () => void {
     source: "bundled",
   });
 }
+
+/**
+ * Install the DSH-specific browser skill into every exact agent scope.
+ *
+ * DSH merges skill layers nearest-first (`agent -> preset -> global`). A legacy
+ * CLI skill installed at `~/.agents/skills/browser-skill` is discovered by the
+ * preset filesystem provider and therefore shadows a plugin-level registration.
+ * Registering the embedded skill through `agent.ctx` makes the DSH protocol
+ * contract authoritative for that agent without touching the shared CLI skill.
+ *
+ * New agents are handled at `agent/session-start`, the first supported startup
+ * injection point and still before the first prompt assembly. Existing agents
+ * are registered immediately so plugin reloads take effect without recreating
+ * the conversation. Returns a disposer for all plugin-owned registrations.
+ */
+export function armAgentScopedBskSkill(ctx: Context): () => void {
+  const registrations = new Map<Agent, () => void>();
+  let active = true;
+
+  const registerForAgent = (agent: Agent): void => {
+    if (!active || registrations.has(agent)) return;
+    registrations.set(agent, registerBskSkill(agent.ctx));
+  };
+
+  let stopSessionStart = () => {};
+  let stopDisposed = () => {};
+  if (typeof ctx.on === "function") {
+    stopSessionStart = ctx.on("agent/session-start", ({ agent }) => {
+      registerForAgent(agent);
+    });
+    stopDisposed = ctx.on("agent/disposed", ({ agent }) => {
+      // Agent-scoped effects have already unwound at this lifecycle edge. Drop
+      // the retained disposer without invoking it against a disposed context.
+      registrations.delete(agent);
+    });
+  }
+
+  const agents = ctx.get("agents") as AgentsLike | undefined | null;
+  if (agents != null && typeof agents.list === "function") {
+    for (const agent of agents.list()) registerForAgent(agent);
+  }
+
+  return () => {
+    if (!active) return;
+    active = false;
+    stopDisposed();
+    stopSessionStart();
+    for (const unregister of [...registrations.values()].reverse()) unregister();
+    registrations.clear();
+  };
+}

packages/dsh-plugin-browserskill/src/tool-params.ts

@@ -0,0 +1,24 @@
+/** Shared model-facing parameter schemas for browser tools. */
+
+export const SESSION_PARAM = {
+  type: "string",
+  description:
+    "bsk session id to act on; must be one created by this plugin's browser_session_start. " +
+    "Omit to use the current session (the one most recently started or used).",
+} as const;
+
+export const TAB_ID_PARAM = {
+  type: "integer",
+  description: "Target tab id. Omit to use the Agent Window's active tab.",
+} as const;
+
+export const WAIT_UNTIL_PARAM = {
+  type: "string",
+  enum: ["load", "domcontentloaded", "networkidle", "commit"],
+  description: "Page lifecycle phase to wait for (default: load).",
+} as const;
+
+export const TIMEOUT_MS_PARAM = {
+  type: "integer",
+  description: "Command timeout in milliseconds; must be greater than zero.",
+} as const;

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

@@ -17,11 +17,20 @@ import {
   type ToolResult,
   type ToolRunContext,
 } from "@deepseek-ai/dsh-tools";
+import { ownerSessionIds } from "./archive-cleanup";
 import { trySaveScreenshot } from "./image";
 import { actionForLabel, type ObservationService } from "./observation";
+import { registerPhaseOneTools } from "./phase-one-tools";
 import type { KeyedExecutor } from "./queue";
-import { type BskRunner, bskInstallMessage, isCommandNotFound, parseBskJson } from "./runner";
+import {
+  type BskRunner,
+  bskInstallMessage,
+  isCommandNotFound,
+  parseBskJson,
+  runWithSessionBusyRetry,
+} from "./runner";
 import type { SessionRegistry } from "./sessions";
+import { SESSION_PARAM } from "./tool-params";
 
 /** Plugin configuration resolved from the Schemastery schema in index.ts. */
 export interface PluginConfig {
@@ -61,13 +70,6 @@ const DEVICE_PRESETS = [
   "galaxy-tab-s8",
 ] as const;
 
-const SESSION_PARAM = {
-  type: "string",
-  description:
-    "bsk session id to act on; must be one created by this plugin's browser_session_start. " +
-    "Omit to use the current session (the one most recently started or used).",
-} as const;
-
 /**
  * Run one bsk command and return its parsed JSON payload, or throw.
  * `observeSession` marks the run as model-facing work on that session: it is
@@ -81,7 +83,10 @@ async function runBsk(
   args: string[],
   label: string,
   observeSession?: string,
+  runnerTimeoutMs?: number,
 ): Promise<unknown> {
+  const releaseForeground =
+    observeSession !== undefined ? deps.observation.acquireForeground(observeSession) : undefined;
   // beginAction must fire only when the task actually starts inside the
   // per-session queue — marking it while still queued would overwrite the
   // in-flight action's label (and flash it idle on a queued abort).
@@ -95,11 +100,15 @@ async function runBsk(
           began = true;
           deps.observation.beginAction(observeSession, actionForLabel(label));
         }
-        return deps.runner.run(args, {
-          signal: exec.signal,
-          timeoutMs: deps.config.defaultTimeoutMs,
-          ...(observeSession !== undefined ? { tag: observeSession } : {}),
-        });
+        return runWithSessionBusyRetry(
+          () =>
+            deps.runner.run(args, {
+              signal: exec.signal,
+              timeoutMs: runnerTimeoutMs ?? deps.config.defaultTimeoutMs,
+              ...(observeSession !== undefined ? { tag: observeSession } : {}),
+            }),
+          exec.signal,
+        );
       };
       result =
         observeSession !== undefined
@@ -124,6 +133,7 @@ async function runBsk(
     if (observeSession !== undefined && began) {
       deps.observation.endAction(observeSession, actionError);
     }
+    releaseForeground?.();
   }
 }
 
@@ -245,6 +255,9 @@ export function registerTools(deps: ToolDeps): () => void {
           browserInstanceId: reply.browser_instance_id,
           startedAtMs: Date.now(),
         });
+        // Ownership for archive cleanup: the calling conversation and its
+        // ancestors reap this session when any of them is archived.
+        registry.trackOwner(reply.session_id, ownerSessionIds(deps.ctx, exec.agent?.id));
         deps.observation.addSession(reply.session_id, args.url);
         try {
           if (args.device !== undefined) {
@@ -267,22 +280,15 @@ export function registerTools(deps: ToolDeps): () => void {
           }
         } catch (error) {
           // A half-initialized session must not leak: stop it before surfacing.
-          // The stop funnels through the session's queue (an in-flight command
-          // — e.g. an observation capture — would otherwise make the daemon
-          // refuse it), with one retry for good measure.
-          for (let attempt = 0; attempt < 2; attempt++) {
-            try {
-              const stopped = await deps.queue.run(reply.session_id, () =>
-                deps.runner.run(["session", "stop", reply.session_id], { timeoutMs: 30_000 }),
-              );
-              if (stopped.code === 0) break;
-            } catch {
-              // retry once, then give up quietly (registry/observation are
-              // cleaned below either way; the daemon reaps orphans).
-            }
+          // Reuse the same capture-preempting, idempotent path as explicit and
+          // overlay stops; local ownership is dropped even when daemon cleanup
+          // itself fails, because this start never becomes usable to the model.
+          try {
+            await deps.observation.stopSession(reply.session_id);
+          } catch {
+            registry.remove(reply.session_id);
+            deps.observation.removeSession(reply.session_id);
           }
-          registry.remove(reply.session_id);
-          deps.observation.removeSession(reply.session_id);
           throw error;
         }
         return {
@@ -326,9 +332,15 @@ export function registerTools(deps: ToolDeps): () => void {
       },
       async execute(args, exec) {
         const sessionId = registry.resolveForStop(args.session);
-        await runBsk(deps, exec, ["session", "stop", sessionId], "session stop", sessionId);
-        registry.remove(sessionId);
-        deps.observation.removeSession(sessionId);
+        try {
+          const stopped = await deps.observation.stopSession(sessionId, exec.signal);
+          if (!stopped) throw new Error(`browser session ${sessionId} is not owned by this plugin`);
+        } catch (error) {
+          if (isCommandNotFound(error)) {
+            throw new Error(bskInstallMessage(deps.config.bskPath));
+          }
+          throw error;
+        }
         return { stopped: sessionId };
       },
       presentCall: (args) => ({
@@ -955,6 +967,12 @@ export function registerTools(deps: ToolDeps): () => void {
       presentResult: presentTerminalResult,
     }),
   );
+  registerPhaseOneTools(deps, register, {
+    run: (exec, args, label, observeSession, runnerTimeoutMs) =>
+      runBsk(deps, exec, args, label, observeSession, runnerTimeoutMs),
+    commandLine: (args) => cmdline(deps, args),
+    presentTerminalResult,
+  });
   return () => {
     for (const dispose of disposers.splice(0)) dispose();
   };

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

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

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

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

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

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

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

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