refactor(tools): declare concurrency in the tool definition

serialized: true was applied in registry.ts, away from the tools it
describes. Now a required concurrency field on each definition, with a
test pinning the serialized set so the classes cannot drift.

The lock check defaults to taking the mutex for any class that is not
explicitly "parallel", so a definition that bypasses defineBrowserTool at
runtime fails safe rather than racing on shared CDP state.

The test script gains --conditions=import: pi-coding-agent publishes no
"require" condition, so importing any tool definition from a CJS-loaded
test could not resolve it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

21 files changed, 42 insertions, 0 deletions

diff --git a/src/domains/click.ts b/src/domains/click.ts
index db340a8..81bd7ca 100644
--- a/src/domains/click.ts
+++ b/src/domains/click.ts
@@ -67,6 +67,7 @@ export const clickTool = defineBrowserTool({
     "If a click doesn't register, set BH_DEBUG_CLICKS=1 to get annotated screenshots (debug only). For React/Vue components ignoring clicks, try browser_dispatch_key.",
   ],
   parameters: ClickArgs,
+  concurrency: "serialized",
   renderCall: (a) => new Text(`🖱️ Click ${a.ref ? `[${a.ref}]` : `(${a.x}, ${a.y})`}`, 0, 0),
   async handler(args, { client }) {
     const button = args.button ?? "left";
diff --git a/src/domains/console.ts b/src/domains/console.ts
index f9814d6..9696cd9 100644
--- a/src/domains/console.ts
+++ b/src/domains/console.ts
@@ -119,6 +119,7 @@ export const consoleTool = defineBrowserTool({
     "Don't use as a default observation tool — prefer browser_snapshot for page structure.",
   ],
   parameters: ConsoleArgs,
+  concurrency: "parallel",
 
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const session = client.session();
diff --git a/src/domains/dialog.ts b/src/domains/dialog.ts
index c30e70c..7038c64 100644
--- a/src/domains/dialog.ts
+++ b/src/domains/dialog.ts
@@ -18,6 +18,7 @@ export const handleDialogTool = defineBrowserTool({
     "For prompt() dialogs, supply promptText with the value to submit.",
   ],
   parameters: HandleDialogArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.session().call("Page.handleJavaScriptDialog", {
       accept: args.accept,
diff --git a/src/domains/drag.ts b/src/domains/drag.ts
index 9075fd0..9ad2ada 100644
--- a/src/domains/drag.ts
+++ b/src/domains/drag.ts
@@ -24,6 +24,7 @@ export const dragAndDropTool = defineBrowserTool({
     "dataTransfer is an optional MIME→data map (e.g., { 'text/plain': 'hello' }).",
   ],
   parameters: DragArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const data = args.dataTransfer
       ? {
diff --git a/src/domains/files.ts b/src/domains/files.ts
index cf9393e..4e0195d 100644
--- a/src/domains/files.ts
+++ b/src/domains/files.ts
@@ -109,6 +109,7 @@ export const uploadFileTool = defineBrowserTool({
     "File path must be absolute and readable.",
   ],
   parameters: UploadArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const readable = await verifyReadable(args.filePath);
     if (!readable.success) return readable;
@@ -160,6 +161,7 @@ export const downloadTool = defineBrowserTool({
     "Affects all subsequent downloads on this browser.",
   ],
   parameters: DownloadArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     try {
       await mkdir(args.downloadPath, { recursive: true });
@@ -205,6 +207,7 @@ export const printToPdfTool = defineBrowserTool({
   promptSnippet: "Print the current page to PDF",
   promptGuidelines: ["Default output path is in tmpdir; pass outputPath to control."],
   parameters: PrintPdfArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.session().call("Page.printToPDF", {
       printBackground: true,
diff --git a/src/domains/form.ts b/src/domains/form.ts
index 95516c5..6e3285a 100644
--- a/src/domains/form.ts
+++ b/src/domains/form.ts
@@ -136,6 +136,7 @@ export const fillTool = defineBrowserTool({
     "The result reports the field's value after writing and an appended page-changes diff — confirm both match what you intended before moving on.",
   ],
   parameters: FillArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await runOnElement(client, { ref: args.ref, selector: args.selector, fnBody: FILL_FN, arg: args.value });
     if (!r.success) return r;
@@ -198,6 +199,7 @@ export const focusTool = defineBrowserTool({
     "For simply setting a value, prefer browser_fill (it doesn't need a separate focus step).",
   ],
   parameters: FocusArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await runOnElement(client, { ref: args.ref, selector: args.selector, fnBody: FOCUS_FN, arg: "" });
     if (!r.success) return r;
@@ -277,6 +279,7 @@ export const selectOptionTool = defineBrowserTool({
     "If no option matches, the error details list the available options so you can retry.",
   ],
   parameters: SelectOptionArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     if (args.value === undefined && args.label === undefined && args.index === undefined) {
       return err({ kind: "invalid_state", message: "Provide one of value, label, or index." });
diff --git a/src/domains/forms.ts b/src/domains/forms.ts
index e38af9a..ed64a74 100644
--- a/src/domains/forms.ts
+++ b/src/domains/forms.ts
@@ -231,6 +231,7 @@ export const fillTool = defineBrowserTool({
     "If a ref no longer resolves, re-run browser_snapshot to get fresh refs.",
   ],
   parameters: FillArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await resolveAndCall(client, args.ref, FILL_FN, [args.value]);
     if (!r.success) return r;
@@ -278,6 +279,7 @@ export const fillFormTool = defineBrowserTool({
     "Re-run browser_snapshot afterwards to verify the form state if needed.",
   ],
   parameters: FillFormArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const results: Array<Readonly<Record<string, unknown>>> = [];
     let okCount = 0;
@@ -323,6 +325,7 @@ export const selectOptionTool = defineBrowserTool({
     "Use this for native <select> elements — clicking coordinates does not work for OS dropdowns.",
   ],
   parameters: SelectOptionArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     if (args.value === undefined && args.label === undefined) {
       return err({ kind: "invalid_state", message: "Provide value or label to select an option." });
@@ -356,6 +359,7 @@ export const setCheckedTool = defineBrowserTool({
     "For radios, set checked:true on the option you want; the group deselects the others.",
   ],
   parameters: SetCheckedArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await resolveAndCall(client, args.ref, CHECK_FN, [args.checked]);
     if (!r.success) return r;
diff --git a/src/domains/history.ts b/src/domains/history.ts
index 96036ba..fbab376 100644
--- a/src/domains/history.ts
+++ b/src/domains/history.ts
@@ -19,6 +19,7 @@ export const goBackTool = defineBrowserTool({
   promptSnippet: "Go back one page",
   promptGuidelines: ["Use to return to the previous page after navigating."],
   parameters: Type.Object({}),
+  concurrency: "serialized",
   async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
     const h = await fetchHistory(client);
     if (!h.success) return h;
@@ -38,6 +39,7 @@ export const goForwardTool = defineBrowserTool({
   promptSnippet: "Go forward one page",
   promptGuidelines: ["Use to undo a browser_go_back."],
   parameters: Type.Object({}),
+  concurrency: "serialized",
   async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
     const h = await fetchHistory(client);
     if (!h.success) return h;
@@ -57,6 +59,7 @@ export const reloadTool = defineBrowserTool({
   promptSnippet: "Reload the page",
   promptGuidelines: ["Use to refresh the page, e.g. after server-side changes."],
   parameters: Type.Object({}),
+  concurrency: "serialized",
   async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.session().call("Page.reload");
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
diff --git a/src/domains/js.ts b/src/domains/js.ts
index 14862e8..b4a5b4c 100644
--- a/src/domains/js.ts
+++ b/src/domains/js.ts
@@ -51,6 +51,7 @@ export const executeJsTool = defineBrowserTool({
     "Result must be JSON-serializable (Runtime.evaluate returnByValue=true).",
   ],
   parameters: ExecuteJsArgs,
+  concurrency: "parallel",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.evaluateJs(args.expression, args.targetId);
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -158,6 +159,7 @@ export const runScriptTool = defineBrowserTool({
     "Script MUST return { content: [{ type: 'text', text: '...' }], details?: {...} }. Throw on errors.",
   ],
   parameters: RunScriptArgs,
+  concurrency: "parallel",
   async handler(args, { client, signal, onUpdate, extensionCtx }): Promise<Result<ToolOk, ToolErr>> {
     if (!isAbsolute(args.path)) {
       return err({ kind: "invalid_state", message: "Script path must be absolute" });
diff --git a/src/domains/keyboard.ts b/src/domains/keyboard.ts
index 6722ffb..473f633 100644
--- a/src/domains/keyboard.ts
+++ b/src/domains/keyboard.ts
@@ -26,6 +26,7 @@ export const typeTool = defineBrowserTool({
     "For special keys (Enter, Tab, Escape, arrows), use browser_press_key instead.",
   ],
   parameters: TypeArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const focused = await client.evaluateJs(safeJs`
       (() => {
@@ -79,6 +80,7 @@ export const pressKeyTool = defineBrowserTool({
     "Modifiers: 1=Alt, 2=Ctrl, 4=Meta(Cmd), 8=Shift. Combine with bitwise OR: Ctrl+Shift = 2|8 = 10.",
   ],
   parameters: PressKeyArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const k = args.key;
     const code = virtualKeyCode(k);
@@ -136,6 +138,7 @@ export const dispatchKeyTool = defineBrowserTool({
     "eventType defaults to 'keydown'.",
   ],
   parameters: DispatchKeyArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const eventType = args.eventType ?? "keydown";
     const target = args.ref ?? args.selector ?? "";
diff --git a/src/domains/navigate.ts b/src/domains/navigate.ts
index 98a2c13..ba86751 100644
--- a/src/domains/navigate.ts
+++ b/src/domains/navigate.ts
@@ -28,6 +28,7 @@ export const navigateTool = defineBrowserTool({
     "Note: Google and some sites with strict anti-bot detection may reject CDP navigation. Use browser_http_get for search results.",
   ],
   parameters: NavigateArgs,
+  concurrency: "serialized",
   renderCall: (a) => new Text(`🌐 Navigate to ${a.url}`, 0, 0),
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const tabs = await client.listTabs(false);
@@ -82,6 +83,7 @@ export const openUrlsTool = defineBrowserTool({
     "Use browser_wait_for_load on a tab before extracting data from SPAs.",
   ],
   parameters: OpenUrlsArgs,
+  concurrency: "serialized",
   renderCall: (a) => new Text(`🌐 Opening ${a.urls.length} URL${a.urls.length !== 1 ? "s" : ""}…`, 0, 0),
   async handler(args, { client, onUpdate }): Promise<Result<ToolOk, ToolErr>> {
     const total = args.urls.length;
diff --git a/src/domains/network.ts b/src/domains/network.ts
index ca46664..dc23c6d 100644
--- a/src/domains/network.ts
+++ b/src/domains/network.ts
@@ -25,6 +25,7 @@ export const httpGetTool = defineBrowserTool({
     "No JS rendering — for SPAs use browser_navigate.",
   ],
   parameters: HttpGetArgs,
+  concurrency: "parallel",
   ensureAlive: false,
   async handler(args): Promise<Result<ToolOk, ToolErr>> {
     const ac = new AbortController();
@@ -180,6 +181,7 @@ export const networkRequestsTool = defineBrowserTool({
     "If bufferOverflowed:true in the result, older events were dropped (capacity 500 records/tab).",
   ],
   parameters: NetworkRequestsArgs,
+  concurrency: "parallel",
 
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const session = client.session();
diff --git a/src/domains/page.ts b/src/domains/page.ts
index 8e674cb..0d7aa8b 100644
--- a/src/domains/page.ts
+++ b/src/domains/page.ts
@@ -17,6 +17,7 @@ export const pageInfoTool = defineBrowserTool({
     "browser_page_info auto-detects alert, confirm, prompt, and beforeunload dialogs.",
   ],
   parameters: Type.Object({}),
+  concurrency: "parallel",
   async handler(_args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.pageInfo();
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -46,6 +47,7 @@ export const waitTool = defineBrowserTool({
   promptSnippet: "Wait N seconds",
   promptGuidelines: ["Use sparingly — prefer browser_wait_for_load when waiting for a page load."],
   parameters: WaitArgs,
+  concurrency: "parallel",
   async handler(args, { signal }): Promise<Result<ToolOk, ToolErr>> {
     try {
       await sleep(Math.round(args.seconds * 1000), signal);
@@ -71,6 +73,7 @@ export const waitForLoadTool = defineBrowserTool({
     "Returns when readyState becomes 'complete' OR the timeout elapses.",
   ],
   parameters: WaitForLoadArgs,
+  concurrency: "serialized",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     const timeoutMs = (args.timeout ?? 15) * 1000;
     const start = Date.now();
@@ -106,6 +109,7 @@ export const waitForTool = defineBrowserTool({
     "Returns a typed timeout error if the condition isn't met within the timeout.",
   ],
   parameters: WaitForArgs,
+  concurrency: "parallel",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     if (args.selector === undefined && args.text === undefined) {
       return err({ kind: "invalid_state", message: "Provide a selector or text to wait for." });
diff --git a/src/domains/readpage/read-page.ts b/src/domains/readpage/read-page.ts
index c21b264..453c347 100644
--- a/src/domains/readpage/read-page.ts
+++ b/src/domains/readpage/read-page.ts
@@ -109,6 +109,7 @@ export const readPageTool = defineBrowserTool({
     "Boilerplate-heavy or structure-less pages fall back to bounded body text rather than erroring.",
   ],
   parameters: ReadPageArgs,
+  concurrency: "parallel",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     if (args.url !== undefined && args.url.length > 0) return readOpenedUrl(client, args.url, signal);
     if (args.targetId !== undefined && args.targetId.length > 0) return readOwnedTab(client, args.targetId);
diff --git a/src/domains/screenshot.ts b/src/domains/screenshot.ts
index a30d336..e3b3615 100644
--- a/src/domains/screenshot.ts
+++ b/src/domains/screenshot.ts
@@ -74,6 +74,7 @@ export const screenshotTool = defineBrowserTool({
     "format='jpeg' with quality 60-90 keeps screenshots small for photo-heavy pages. Use maxDim if the page is huge.",
   ],
   parameters: ScreenshotArgs,
+  concurrency: "parallel",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const cap = await captureBase(client, args);
     if (!cap.success) return cap;
diff --git a/src/domains/scroll.ts b/src/domains/scroll.ts
index 2bd2ed1..f29e931 100644
--- a/src/domains/scroll.ts
+++ b/src/domains/scroll.ts
@@ -23,6 +23,7 @@ export const scrollTool = defineBrowserTool({
     "Pass x/y to target a specific scrollable region (e.g., a div with overflow); otherwise scrolls the page at viewport center.",
   ],
   parameters: ScrollArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const info = await client.pageInfo();
     if (!info.success) return err({ kind: "cdp_error", message: info.error.message });
diff --git a/src/domains/search/web-search.ts b/src/domains/search/web-search.ts
index 8908e29..69677b4 100644
--- a/src/domains/search/web-search.ts
+++ b/src/domains/search/web-search.ts
@@ -50,6 +50,7 @@ export const webSearchTool = defineBrowserTool({
     "Runs in its own isolated tab and never disturbs the user's current tab.",
   ],
   parameters: WebSearchArgs,
+  concurrency: "serialized",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     const limit = args.limit ?? 10;
     const serpUrl = buildSerpUrl(args.query, limit);
diff --git a/src/domains/setup.ts b/src/domains/setup.ts
index 2ddd739..c2d8a4f 100644
--- a/src/domains/setup.ts
+++ b/src/domains/setup.ts
@@ -28,6 +28,7 @@ export const setupTool = defineBrowserTool({
     "After browser_setup succeeds, retry the browser tool that failed.",
   ],
   parameters: SetupArgs,
+  concurrency: "parallel",
   // ensureAlive:false — this tool IS the setup; it must bypass the socket guard
   ensureAlive: false,
   renderCall: () => new Text("🔧 Initializing browser...", 0, 0),
diff --git a/src/domains/snapshot.ts b/src/domains/snapshot.ts
index e1c66d3..bfc475c 100644
--- a/src/domains/snapshot.ts
+++ b/src/domains/snapshot.ts
@@ -313,6 +313,7 @@ export const snapshotTool = defineBrowserTool({
     "format:'json' returns the raw slim structure (with `ref` and `box` per node) for programmatic use; default 'outline' is human/LLM-readable.",
   ],
   parameters: SnapshotArgs,
+  concurrency: "parallel",
 
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const session = client.session();
diff --git a/src/domains/tabs.ts b/src/domains/tabs.ts
index e3e2623..2971a6b 100644
--- a/src/domains/tabs.ts
+++ b/src/domains/tabs.ts
@@ -24,6 +24,7 @@ export const listTabsTool = defineBrowserTool({
     "Internal tabs (chrome://) included by default; pass includeInternal=false to exclude them.",
   ],
   parameters: ListTabsArgs,
+  concurrency: "parallel",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.listTabs(args.includeInternal ?? true);
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -50,6 +51,7 @@ export const currentTabTool = defineBrowserTool({
   promptSnippet: "Get current tab info",
   promptGuidelines: ["Returns targetId, url, title, and whether the tab is owned by this harness session."],
   parameters: Type.Object({}),
+  concurrency: "parallel",
   async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
     const cur = client.current();
     if (!cur) return err({ kind: "invalid_state", message: "No tab attached." });
@@ -83,6 +85,7 @@ export const switchTabTool = defineBrowserTool({
     "Refuses tabs not owned by this session — use browser_new_tab to open a controllable tab instead.",
   ],
   parameters: SwitchTabArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     // Resolve to a concrete targetId (exact, or unique hex prefix). We resolve
     // first so the ownership check sees the canonical id, not the prefix.
@@ -141,6 +144,7 @@ export const newTabTool = defineBrowserTool({
     "Pass url to navigate immediately.",
   ],
   parameters: NewTabArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.newTab(args.url);
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -167,6 +171,7 @@ export const closeTabTool = defineBrowserTool({
     "Accepts exact targetId or a unique hex prefix (>=8 chars).",
   ],
   parameters: CloseTabArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     let resolved = args.targetId;
     if (!client.owns(resolved)) {
diff --git a/src/domains/viewport.ts b/src/domains/viewport.ts
index 015ac68..9e9ac07 100644
--- a/src/domains/viewport.ts
+++ b/src/domains/viewport.ts
@@ -20,6 +20,7 @@ export const viewportResizeTool = defineBrowserTool({
     "Pass deviceScaleFactor=2 to simulate retina displays.",
   ],
   parameters: ViewportArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.session().call("Emulation.setDeviceMetricsOverride", {
       width: args.width,