machine-bridge-mcp 0.14.0 → 0.15.0

package/docs/LOCAL_AUTOMATION.md

@@ -15,7 +15,7 @@ The extension works with the current profile and supports:
 
 - listing, creating, activating, and closing tabs;
 - reading the current serialized DOM HTML from the main frame or accessible subframes;
-- discovering interactive controls, stable per-document element references, actionability state, geometry, labels, roles, placeholders, and field metadata across accessible frames and open Shadow DOM roots;
+- discovering interactive controls, bounded per-document element references, actionability state, geometry, labels, roles, placeholders, and field metadata across accessible frames and open Shadow DOM roots;
 - waiting for bounded combinations of URL, load state, page text, and element state;
 - structured navigation, click, double-click, hover, focus, fill, type-text, select, check, uncheck, key press, scroll-into-view, and form submission;
 - automatic existence/visibility/enabled/editable/stability/hit-target checks before actions, with fixed DevTools mouse/keyboard input for top-frame interactions and a controlled DOM fallback;
@@ -23,7 +23,7 @@ The extension works with the current profile and supports:
 - populating file inputs from registered local resource files;
 - visible-tab screenshots.
 
-Current support targets Chrome, Chromium, Microsoft Edge, Brave, Vivaldi, and compatible Chromium browsers. After upgrading Machine Bridge, reload the unpacked extension from the browser extensions page so its packaged scripts and permissions match the new runtime. Version 0.14.0 adds the `debugger` permission for fixed trusted-input commands; the extension attaches only for the action and detaches afterward. The broker requires a versioned extension hello with the expected capability set, keeps the last compatible connection active until a replacement completes its handshake, and reports `extension_reload_required` instead of silently routing new tools to stale extension code. Browser-internal pages, extension stores, some PDF/plugin viewers, cross-origin frames denied to the extension, and pages restricted by enterprise policy may not be scriptable.
+Current support targets Chrome, Chromium, Microsoft Edge, Brave, Vivaldi, and compatible Chromium browsers. The extension must be loaded into the user profile to be controlled; it is not installed into Playwright or an isolated automation profile. After every Machine Bridge upgrade, reload the unpacked extension so packaged scripts, protocol, and permissions match the runtime. Version 0.15.0 requires protocol 3 with broker `hello_ack`; the badge and pairing page report success only after protocol/version/capability validation. Pairing material is persisted only after that acknowledgement, an invalid candidate cannot overwrite the previous pairing, and `browser status` reports the expected packaged build, authenticated connected build/protocol/capabilities, and `extension_reload_required`; exact version equality is required in addition to protocol and capabilities. Browser-internal pages, extension stores, some PDF/plugin viewers, inaccessible cross-origin frames, and pages restricted by enterprise policy remain unscriptable.
 
 ## One-time browser setup
 
@@ -55,17 +55,17 @@ The broker is machine-global rather than workspace-global. One local owner liste
 
 ## Browser tools
 
-- `browser_status` reports broker role, extension connection, supported operations, pairing URL, and extension path without returning the pairing token.
+- `browser_status` reports broker role, authenticated extension protocol/version/capabilities, reload state, supported operations, pairing URL, and extension path without returning the pairing token.
 - `pair_browser_extension` opens the local pairing page and returns setup steps.
 - `browser_list_tabs` lists current tabs.
 - `browser_manage_tabs` creates, activates, or closes a selected tab.
-- `browser_get_source` returns bounded current DOM HTML for selected frames.
-- `browser_inspect_page` returns a bounded semantic snapshot. Each control includes a stable `ref` for the lifetime of that document/frame plus visibility, enabled/editable state, and viewport geometry.
+- `browser_get_source` returns a bounded iterative DOM serialization. `max_bytes` is one aggregate request budget across at most 64 accessible frames; omitted frames and node/byte truncation are explicit.
+- `browser_inspect_page` returns snapshot version 2 with one aggregate `max_elements` budget, at most 64 accessible frames, a 100,000-node per-frame scan ceiling, bounded page-controlled strings, URL-userinfo redaction, and explicit scan/frame truncation. Each control includes a reusable `ref` plus visibility, enabled/editable state, and viewport geometry. References are held in a 10,000-entry per-frame LRU; navigation, element replacement, or bounded eviction makes an older ref stale and requires a new inspection.
 - `browser_wait` waits until all supplied URL, load-state, page-text, and element-state conditions are true.
-- `browser_action` performs one structured navigation or page action. Navigation accepts absolute `http`, `https`, or `file` URLs; script/data schemes are rejected. Pointer and keyboard actions default to `input_mode: auto`, which attempts fixed trusted DevTools input in the top frame and falls back to DOM behavior. `trusted` forbids fallback; `dom` never attaches the debugger.
-- `browser_fill_form` fills up to 200 fields and can submit once.
+- `browser_action` performs one structured navigation or page action. Navigation accepts absolute `http`, `https`, or `file` URLs; script/data schemes are rejected. Pointer and keyboard actions default to `input_mode: auto`, which uses fixed trusted DevTools input in the top frame and falls back to DOM only when no `Input` command has started. Once dispatch begins, failure has an unknown outcome and must be inspected before retrying; automatic replay is forbidden. `trusted` always forbids fallback; `dom` never attaches the debugger.
+- `browser_fill_form` fills up to 200 fields and can submit once. If a later field fails, the error states how many earlier fields may already have changed without returning their values.
 - `browser_upload_files` sets a file input from up to eight registered local resources. Caller filenames must be safe single-component names; derived names have controls and separators removed. MIME overrides must be canonical media types.
-- `browser_screenshot` returns native MCP image content.
+- `browser_screenshot` returns native MCP image content, temporarily activates the selected tab only when required, restores the previous active tab when safe, and never focuses another browser window.
 
 Selectors can use the `ref` returned by inspection, CSS, ID, field name, label text, visible text, ARIA/implicit role, placeholder, and a zero-based match index. `ref` cannot be combined with other fields and becomes stale after navigation or element replacement. Non-ref selectors that match multiple controls fail explicitly unless `index` disambiguates them. The fixed page module traverses open Shadow DOM roots; closed shadow roots remain inaccessible. For frame-specific work, inspect all frames first and then pass `frame_id` to an action. Trusted input currently targets the top frame because DevTools coordinates are top-level; use `input_mode: dom` for an explicitly selected subframe.
 
@@ -105,12 +105,12 @@ The implementation reduces avoidable risk as follows:
 
 - all browser/app tools are `full`-only;
 - no arbitrary evaluation, caller-provided script source, or caller-selected DevTools method is accepted; trusted input exposes only fixed `Input.dispatchMouseEvent`, `Input.dispatchKeyEvent`, and `Input.insertText` sequences;
-- loopback HTTP validates `Host`; extension WebSockets require a random bearer subprotocol and a `chrome-extension://` origin;
+- loopback HTTP validates `Host`; extension WebSockets require a random bearer subprotocol and a canonical `chrome-extension://` origin whose host is a 32-character Chromium extension ID; pairing-page and broker ports must match;
 - runtime-to-broker connections require a separate authenticated subprotocol;
 - the pairing token is stored owner-only, embedded only in the non-cacheable local pairing page, and omitted from MCP results and logs;
 - an established extension pairing cannot be silently replaced by another localhost page; replacement requires clicking the extension action on the active pairing page;
 - arguments, form values, page source, screenshots, and results are not operational log data;
-- message, source, form-field, upload, traversal, concurrency, proxy-route, actionability, and timeout limits are enforced; ambiguous selectors, stale refs, hidden/disabled/edit-blocked controls, moving targets, and obscured pointer targets fail explicitly;
+- message, aggregate source/element/frame, form-field, upload, DOM-node/text, concurrency, proxy-route, actionability, and request-deadline limits are enforced; ambiguous selectors, stale refs, hidden/disabled/edit-blocked controls, moving targets, and obscured pointer targets fail explicitly;
 - MCP cancellation clears local and broker pending state and propagates a cancellation signal to the extension; an action already delivered to a page or application may still have completed;
 - resource-backed text and files are not returned after injection.
 

package/docs/OPERATIONS.md

@@ -44,14 +44,15 @@ machine-mcp browser setup
 machine-mcp browser status
 ```
 
-`browser setup` prints the unpacked-extension path and opens the local pairing page. Load that directory from the Chromium extensions page with Developer mode enabled. The pairing page contains the token only in non-cacheable loopback HTML; the CLI and MCP result do not print it. A first pairing is automatic. When local pairing state was reset or moved, click the extension icon on the active pairing page to authorize replacing the extension's previous broker configuration.
+`browser setup` prints the unpacked-extension path and opens the local pairing page. Load that directory into the Chromium profile you actually use; it is not installed into Playwright or a separate automation profile. `browser status` prints the authenticated extension build/protocol and the existing-profile backend. The pairing page contains the token only in non-cacheable loopback HTML; the CLI and MCP result do not print it. A first pairing is automatic. When local pairing state was reset or moved, click the extension icon on the active pairing page to authorize replacing the extension's previous broker configuration.
 
 Diagnosis:
 
 | Result | Interpretation |
 |---|---|
 | broker not reachable | no full-profile runtime owns the machine broker, state is stale, or a local security product blocked loopback listening |
-| broker running, extension disconnected | extension not loaded/enabled, pairing not completed, browser profile not running, or MV3 worker reconnect failed |
+| broker running, extension disconnected | extension not loaded/enabled in the intended Chromium profile, pairing not completed, browser profile not running, or MV3 worker reconnect failed |
+| extension reload required | unpacked files, permissions, protocol, or capability set differ from the running extension; reload it from the extensions page and revisit the pairing page |
 | tab list works but page action fails | restricted browser-internal page, inaccessible frame, stale selector, page navigation, enterprise policy, or page script interference |
 | `frame_id` action fails | frame was replaced or is not accessible; inspect frames again |
 | resource-backed upload fails | resource unavailable/too large, input is not `type=file`, page replaced the input, or the site rejects the file |
@@ -100,7 +101,7 @@ Uninstall acquires a state-root `maintenance.lock` that blocks new profile/state
 
 ## Logs
 
-Remote autostart definitions prefer a stable PATH alias that resolves to the currently running Node executable and persist a sanitized absolute-only service `PATH` containing the Node/CLI directories, the installer's absolute PATH entries, and platform defaults. This avoids versioned Homebrew-style paths becoming invalid after upgrades and prevents launchd/systemd from falling back to a minimal system-only PATH. Re-run `machine-mcp service install` after changing Node installation families or PATH layout. A service-style `--daemon-only` start that finds the same workspace daemon already running is an idempotent no-op: it exits successfully without repeating warnings or readiness output; explicit policy/secret/change requests still report that changes were not applied. Autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Files are owner-only where supported and tail-trimmed before daemon startup. On a logging-schema upgrade, bounded prior content is moved into `daemon.out.legacy.log` and `daemon.err.legacy.log`; use the active filenames when diagnosing current behavior.
+Windows Scheduled Task command lines use CRT-compatible quoting, including trailing backslashes and drive-root paths. Remote autostart definitions prefer a stable PATH alias that resolves to the currently running Node executable and persist a sanitized absolute-only service `PATH` containing the Node/CLI directories, the installer's absolute PATH entries, and platform defaults. This avoids versioned Homebrew-style paths becoming invalid after upgrades and prevents launchd/systemd from falling back to a minimal system-only PATH. Re-run `machine-mcp service install` after changing Node installation families or PATH layout. A service-style `--daemon-only` start that finds the same workspace daemon already running is an idempotent no-op: it exits successfully without repeating warnings or readiness output; explicit policy/secret/change requests still report that changes were not applied. Autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Files are owner-only where supported and tail-trimmed before daemon startup. On a logging-schema upgrade, bounded prior content is moved into `daemon.out.legacy.log` and `daemon.err.legacy.log`; use the active filenames when diagnosing current behavior.
 
 Logging is level-based:
 
@@ -199,7 +200,7 @@ Defense-in-depth limits include:
 - managed-job timeout: 1–3,600 seconds per step;
 - managed-job output: 64 KiB per stream and 256 KiB total captured across one job;
 - registered resources: 64, 1 MiB each, 8 MiB referenced per job;
-- browser source: 4 MiB; browser WebSocket messages: 8 MiB; pending browser requests: 32 per runtime;
+- browser source: 4 MiB aggregate across at most 64 accessible frames; semantic inspection: 1,000 elements aggregate, 100,000 scanned nodes, 10,000 reusable refs, and 2 MiB bounded page-text search per frame; browser WebSocket messages: 8 MiB; pending browser requests: 32 per runtime;
 - browser forms: 200 fields, 128 KiB per text value, and 4 MiB aggregate text; upload: eight resources and 5 MiB total;
 - application Accessibility inspection: 500 elements and depth 12; action text: 4,000 characters;
 - job-scoped temporary files: 16 files, 512 KiB total content.

package/docs/TESTING.md

@@ -52,7 +52,7 @@ The suite includes:
 
 ## Opt-in live desktop and browser validation
 
-The normal suite uses deterministic mocks for macOS Accessibility and an authenticated in-process extension peer for browser routing. Browser contract tests cover versioned extension handshakes, stale-extension rejection, compatible replacement without premature displacement, clean rejection of in-flight direct and proxied requests during replacement, keepalive handling, strict action/value validation, stable-ref validation, combined waits, tab commands, fixed trusted-input CDP sequences, attach/detach cleanup, semantic-ref stability, deterministic scrolling, obscured-target waiting, and stale-reference failure. Before a release that changes local UI automation, run the macOS live smoke test on a machine where the invoking Node/terminal process has Accessibility permission:
+The normal suite uses deterministic mocks for macOS Accessibility and an authenticated in-process extension peer for browser routing. Browser contract tests cover acknowledged protocol readiness, provisional pairing commit/rollback boundaries, strict extension IDs and matching loopback ports, stale-extension rejection, compatible replacement without premature displacement, clean rejection of in-flight direct and proxied requests, keepalive handling, trusted-input replay prevention after partial dispatch, focus-safe screenshots, aggregate 64-frame/source/element budgets, bounded hostile DOM/text processing, contenteditable-secret suppression, partial-form failure reporting, stable refs, combined waits, and actionability failures. Before a release that changes local UI automation, run the macOS live smoke test on a machine where the invoking Node/terminal process has Accessibility permission:
 
 ```sh
 npm run app-automation:live-test
@@ -60,7 +60,7 @@ npm run app-automation:live-test
 
 It opens Calculator, activates it through the fixed JXA helper, verifies structured JSON output, inspects main-window Accessibility controls with menu recursion disabled, clicks the `One` control, and quits the application. It is intentionally excluded from CI because macOS TCC permission and a graphical login session are host state.
 
-For browser changes, perform an isolated-profile smoke test with the packaged unpacked extension: pair it to a temporary source runtime, navigate a local no-store page, inspect controls and reuse a returned `ref`, wait for an element state, fill multiple fields, exercise `input_mode: trusted` for click/key/text, verify the live DOM, create/activate/close a tab, and capture a screenshot. A Playwright persistent Chromium context is an acceptable harness because it loads the real MV3 service worker while keeping the user's daily browser profile untouched.
+For deterministic release validation, perform an isolated-profile smoke test with the packaged unpacked extension; a Playwright persistent Chromium context is acceptable only as that isolated harness. When the requirement is specifically to prove control of the user's ordinary browser, the user must load the same unpacked directory into that known daily Chromium profile; status can verify the extension version/protocol and that Machine Bridge did not launch a browser, but cannot infer profile identity. Then use a localhost no-store fixture in a newly created tab. Do not enumerate, read, or mutate unrelated existing tabs. In both modes, inspect and reuse refs, exercise waits/forms/trusted input/open Shadow DOM/screenshots, verify final live DOM, and close the fixture tab.
 
 ## Additional release checks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Cross-client MCP bridge for local agent context, structured browser and application automation, files, Git, processes, resources, and durable jobs over stdio or OAuth relay.",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "worker:types": "wrangler types src/worker/worker-configuration.d.ts",
     "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit",
     "syntax": "node scripts/syntax-check.mjs",
-    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run release-ci:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run process-lock:test && npm run service-lifecycle:test && npm run catalog:test && npm run agent-context:test && npm run browser-command:test && npm run browser-devtools-input:test && npm run browser-page-automation:test && npm run browser-bridge:test && npm run app-automation:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
+    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run release-ci:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run process-lock:test && npm run service-lifecycle:test && npm run service-platform:test && npm run catalog:test && npm run agent-context:test && npm run browser-command:test && npm run browser-devtools-input:test && npm run browser-service-worker:test && npm run browser-page-automation:test && npm run browser-bridge:test && npm run app-automation:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
@@ -76,7 +76,9 @@
     "app-automation:live-test": "node tests/app-automation-test.mjs --live-macos",
     "browser-command:test": "node tests/browser-command-test.mjs",
     "browser-devtools-input:test": "node tests/browser-devtools-input-test.mjs",
-    "browser-page-automation:test": "node tests/browser-page-automation-test.mjs"
+    "browser-page-automation:test": "node tests/browser-page-automation-test.mjs",
+    "browser-service-worker:test": "node tests/browser-service-worker-test.mjs",
+    "service-platform:test": "node tests/service-platform-test.mjs"
   },
   "dependencies": {
     "https-proxy-agent": "9.1.0",

package/src/local/browser-bridge.mjs

@@ -1,6 +1,6 @@
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { WebSocket, WebSocketServer } from "ws";
@@ -23,8 +23,11 @@ const MAX_FIELD_VALUE_CHARS = 128 * 1024;
 const MAX_FORM_VALUE_BYTES = 4 * 1024 * 1024;
 const PAIRING_FILE = "browser-bridge.json";
 const RESOURCE_NAME = /^[a-z][a-z0-9._-]{0,63}$/;
-const BROWSER_EXTENSION_PROTOCOL = 2;
+const BROWSER_EXTENSION_PROTOCOL = 3;
 const EXTENSION_HANDSHAKE_MS = 3_000;
+const EXTENSION_MANIFEST = JSON.parse(readFileSync(resolve(packageRoot, "browser-extension", "manifest.json"), "utf8"));
+const EXPECTED_EXTENSION_VERSION = String(EXTENSION_MANIFEST.version_name || EXTENSION_MANIFEST.version || "");
+if (!EXPECTED_EXTENSION_VERSION) throw new Error("packaged browser extension version is missing");
 const REQUIRED_EXTENSION_CAPABILITIES = Object.freeze([
   "semantic_snapshot_refs", "actionability_waits", "trusted_input", "tab_management", "explicit_waits",
 ]);
@@ -48,6 +51,7 @@ export class BrowserBridgeManager {
     this.extensionInfo = null;
     this.proxyExtensionInfo = null;
     this.proxyExtensionReloadRequired = false;
+    this.extensionReloadRequiredFlag = false;
     this.recoveryTimer = null;
     this.stopping = false;
     this.pending = new Map();
@@ -66,12 +70,17 @@ export class BrowserBridgeManager {
       endpoint: `ws://127.0.0.1:${this.port}/extension`,
       pairing_url: `http://127.0.0.1:${this.port}/pair`,
       extension_path: this.extensionPath,
+      expected_extension_version: EXPECTED_EXTENSION_VERSION,
       extension_protocol: this.extensionStatusInfo()?.protocol || null,
       extension_version: this.extensionStatusInfo()?.version || "",
       extension_capabilities: this.extensionStatusInfo()?.capabilities || [],
       extension_reload_required: this.extensionReloadRequired(),
       supported_browsers: ["Chrome", "Chromium", "Microsoft Edge", "Brave", "Vivaldi", "other Chromium browsers with Manifest V3"],
       controls_existing_profile: true,
+      controls_extension_profile: true,
+      launches_browser_process: false,
+      launches_separate_automation_profile: false,
+      profile_identity_verifiable: false,
       uses_existing_tabs_and_login_state: true,
       source_access: true,
       semantic_snapshot_refs: true,
@@ -363,7 +372,7 @@ export class BrowserBridgeManager {
         const protocol = String(request.headers["sec-websocket-protocol"] || "");
         const origin = String(request.headers.origin || "");
         let role = "";
-        if (url.pathname === "/extension" && protocol === `mbm.${this.token}` && origin.startsWith("chrome-extension://")) role = "extension";
+        if (url.pathname === "/extension" && protocol === `mbm.${this.token}` && isAllowedExtensionOrigin(origin)) role = "extension";
         if (url.pathname === "/runtime" && protocol === `mbm-runtime.${this.token}` && !origin) role = "runtime";
         if (!role) {
           socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
@@ -472,7 +481,10 @@ export class BrowserBridgeManager {
     this.pendingExtensionSocket = ws;
     this.broadcastRuntimeStatus(this.extensionConnected());
     ws.extensionReady = false;
-    ws.handshakeTimer = setTimeout(() => closeProtocolSocket(ws, 1002, "extension hello required; reload the extension"), EXTENSION_HANDSHAKE_MS);
+    ws.handshakeTimer = setTimeout(() => {
+      this.markExtensionReloadRequired();
+      closeProtocolSocket(ws, 1002, "extension hello required; reload the extension");
+    }, EXTENSION_HANDSHAKE_MS);
     ws.handshakeTimer.unref?.();
     ws.on("message", (data) => this.handleExtensionMessage(ws, data));
     ws.on("close", () => {
@@ -497,22 +509,30 @@ export class BrowserBridgeManager {
     if (this.socket !== socket && this.pendingExtensionSocket !== socket) return;
     const parsed = parseBrowserSocketMessage(data);
     if (!parsed.ok) {
+      this.markExtensionReloadRequired();
       closeProtocolSocket(socket, parsed.code, parsed.reason);
       return;
     }
     const message = parsed.message;
     if (message.type === "hello") {
       if (socket.extensionReady) {
+        this.markExtensionReloadRequired();
         closeProtocolSocket(socket, 1002, "duplicate extension hello");
         return;
       }
       let info;
       try { info = parseExtensionHello(message); }
       catch (error) {
+        this.markExtensionReloadRequired();
         closeProtocolSocket(socket, 1002, String(error?.message || error).slice(0, 120));
         return;
       }
       clearTimeout(socket.handshakeTimer);
+      if (!safeSocketSend(socket, { type: "hello_ack", role: "extension", protocol: BROWSER_EXTENSION_PROTOCOL })) {
+        closeProtocolSocket(socket, 1011, "extension acknowledgement failed");
+        return;
+      }
+      this.extensionReloadRequiredFlag = false;
       socket.extensionReady = true;
       if (this.pendingExtensionSocket === socket) this.pendingExtensionSocket = null;
       const previous = this.socket;
@@ -527,11 +547,13 @@ export class BrowserBridgeManager {
       return;
     }
     if (!socket.extensionReady) {
+      this.markExtensionReloadRequired();
       closeProtocolSocket(socket, 1002, "extension hello required; reload the extension");
       return;
     }
     if (message.type === "ping") return;
     if (message.type !== "response" || typeof message.id !== "string") {
+      this.markExtensionReloadRequired();
       closeProtocolSocket(socket, 1002, "invalid extension protocol message");
       return;
     }
@@ -654,7 +676,21 @@ export class BrowserBridgeManager {
       return;
     }
     if (url.pathname === "/healthz") {
-      sendJson(response, { ok: true, connected: this.extensionConnected(), broker: "machine-bridge-browser" });
+      const extension = this.extensionStatusInfo();
+      sendJson(response, {
+        ok: true,
+        connected: this.extensionConnected(),
+        broker: "machine-bridge-browser",
+        expected_extension_version: EXPECTED_EXTENSION_VERSION,
+        extension_protocol: extension?.protocol || null,
+        extension_version: extension?.version || "",
+        extension_capabilities: extension?.capabilities || [],
+        extension_reload_required: this.extensionReloadRequired(),
+        controls_existing_profile: true,
+        controls_extension_profile: true,
+        machine_bridge_launches_browser: false,
+        profile_identity_verifiable: false,
+      });
       return;
     }
     if (url.pathname === "/pair") {
@@ -711,6 +747,7 @@ export class BrowserBridgeManager {
     this.proxyExtensionConnected = false;
     this.proxyExtensionInfo = null;
     this.proxyExtensionReloadRequired = false;
+    this.extensionReloadRequiredFlag = false;
     this.runtimeClients.clear();
     for (const route of this.proxyRoutes.values()) clearTimeout(route.timeout);
     this.proxyRoutes.clear();
@@ -720,6 +757,11 @@ export class BrowserBridgeManager {
     this.server = null;
   }
 
+  markExtensionReloadRequired() {
+    this.extensionReloadRequiredFlag = true;
+    this.broadcastRuntimeStatus(this.extensionConnected());
+  }
+
   extensionConnected() {
     return this.server
       ? this.socket?.readyState === 1 && Boolean(this.extensionInfo)
@@ -732,7 +774,7 @@ export class BrowserBridgeManager {
 
   extensionReloadRequired() {
     return this.server
-      ? this.pendingExtensionSocket?.readyState === 1 && !this.extensionConnected()
+      ? this.extensionReloadRequiredFlag || (this.pendingExtensionSocket?.readyState === 1 && !this.extensionConnected())
       : this.proxyExtensionReloadRequired;
   }
 
@@ -745,7 +787,7 @@ export class BrowserBridgeManager {
 
 function normalizeCompatibleExtensionInfo(value) {
   const info = normalizeExtensionInfo(value);
-  if (!info || info.protocol !== BROWSER_EXTENSION_PROTOCOL) return null;
+  if (!info || info.protocol !== BROWSER_EXTENSION_PROTOCOL || info.version !== EXPECTED_EXTENSION_VERSION) return null;
   if (REQUIRED_EXTENSION_CAPABILITIES.some((capability) => !info.capabilities.includes(capability))) return null;
   return info;
 }
@@ -756,6 +798,7 @@ function parseExtensionHello(message) {
   }
   const info = normalizeExtensionInfo(message);
   if (!info) throw new Error("invalid extension hello; reload the extension");
+  if (info.version !== EXPECTED_EXTENSION_VERSION) throw new Error(`extension version mismatch; expected ${EXPECTED_EXTENSION_VERSION}; reload the extension`);
   const missing = REQUIRED_EXTENSION_CAPABILITIES.filter((capability) => !info.capabilities.includes(capability));
   if (missing.length) throw new Error(`extension capability mismatch; reload the extension (${missing.join(",")})`);
   return info;
@@ -809,7 +852,20 @@ async function savePairing(stateRoot, value) {
 }
 
 function pairingHtml(port, token) {
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="machine-bridge-browser-pair" content="1"><meta name="machine-bridge-browser-port" content="${port}"><meta name="machine-bridge-browser-token" content="${token}"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Machine Bridge browser pairing</title></head><body><h1>Machine Bridge browser pairing</h1><p>The installed extension reads pairing material from this loopback-only page and stores it in browser-local extension storage. It is not sent to any website.</p><p id="status">Waiting for the Machine Bridge extension.</p></body></html>`;
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="machine-bridge-browser-pair" content="1"><meta name="machine-bridge-browser-port" content="${port}"><meta name="machine-bridge-browser-token" content="${token}"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Machine Bridge browser pairing</title></head><body><h1>Machine Bridge browser pairing</h1><p>Expected extension build: <strong>${EXPECTED_EXTENSION_VERSION}</strong>. Reload the unpacked extension after every Machine Bridge upgrade.</p><p>The installed extension reads pairing material from this loopback-only page and stores it in browser-local extension storage. It is not sent to any website.</p><p id="status">Waiting for the Machine Bridge extension.</p></body></html>`;
+}
+
+function isAllowedExtensionOrigin(origin) {
+  let parsed;
+  try { parsed = new URL(String(origin || "")); } catch { return false; }
+  return parsed.protocol === "chrome-extension:"
+    && /^[a-p]{32}$/.test(parsed.hostname)
+    && !parsed.username
+    && !parsed.password
+    && !parsed.port
+    && (parsed.pathname === "" || parsed.pathname === "/")
+    && !parsed.search
+    && !parsed.hash;
 }
 
 function isAllowedLoopbackHost(host, port) {

package/src/local/cli.mjs

@@ -753,13 +753,26 @@ async function browserCommand(args) {
     connected: health?.broker === "machine-bridge-browser" && health?.connected === true,
     extension_path: extensionPath,
     pairing_url: pairingUrl,
+    expected_extension_version: typeof health?.expected_extension_version === "string" ? health.expected_extension_version : "",
+    extension_protocol: Number.isInteger(health?.extension_protocol) ? health.extension_protocol : null,
+    extension_version: typeof health?.extension_version === "string" ? health.extension_version : "",
+    extension_capabilities: Array.isArray(health?.extension_capabilities) ? health.extension_capabilities : [],
+    extension_reload_required: health?.extension_reload_required === true,
+    controls_existing_profile: health?.controls_existing_profile === true,
+    controls_extension_profile: health?.controls_extension_profile === true,
+    machine_bridge_launches_browser: health?.machine_bridge_launches_browser === true,
+    profile_identity_verifiable: health?.profile_identity_verifiable === true,
     token_exposed: false,
   };
   if (action === "status") {
     if (args.json) console.log(JSON.stringify(result, null, 2));
     else {
       console.log(`Browser bridge: ${result.running ? "running" : "not reachable"}`);
-      console.log(`Extension: ${result.connected ? "connected" : "not connected"}`);
+      console.log(`Extension: ${result.connected ? "connected" : result.extension_reload_required ? "reload required" : "not connected"}`);
+      if (result.expected_extension_version) console.log(`Expected extension build: ${result.expected_extension_version}`);
+      if (result.extension_version || result.extension_protocol) console.log(`Connected extension build: ${result.extension_version || "unknown"} (protocol ${result.extension_protocol ?? "unknown"})`);
+      console.log(`Browser profile: ${result.controls_extension_profile ? "the Chromium profile where this extension is installed" : "unknown"}`);
+      if (result.controls_extension_profile) console.log(`Profile provenance: Machine Bridge did not launch the browser; daily-vs-isolated profile identity is not machine-verifiable.`);
       console.log(`Extension path: ${extensionPath}`);
     }
     return;
@@ -769,7 +782,8 @@ async function browserCommand(args) {
   if (args.json) console.log(JSON.stringify({ ...result, pairing_page_opened: true }, null, 2));
   else {
     console.log(`Extension path: ${extensionPath}`);
-    console.log("Load this directory once from the Chromium extensions page with Developer mode enabled.");
+    console.log("Load this directory in the Chromium profile you use every day; Machine Bridge does not install it into Playwright or a separate automation profile.");
+    console.log("Enable Developer mode, choose Load unpacked, and reload the extension after each Machine Bridge upgrade.");
     console.log(`Pairing page opened: ${pairingUrl}`);
   }
 }

package/src/local/service.mjs

@@ -465,11 +465,15 @@ async function statusWindowsTask() {
 }
 
 function windowsCommand(spec) {
-  return [spec.node, ...daemonArgs(spec)].map(winQuote).join(" ");
+  return [spec.node, ...daemonArgs(spec)].map(windowsCommandLineArgument).join(" ");
 }
 
-function winQuote(value) {
-  return `"${String(value).replaceAll('"', '\\"')}"`;
+export function windowsCommandLineArgument(value) {
+  const text = String(value);
+  if (text.includes("\0")) throw new Error("Windows command-line argument contains a NUL byte");
+  const escapedQuotes = text.replace(/(\\*)"/g, (_match, slashes) => `${slashes}${slashes}\\"`);
+  const escapedTrailingSlashes = escapedQuotes.replace(/(\\+)$/, (slashes) => `${slashes}${slashes}`);
+  return `"${escapedTrailingSlashes}"`;
 }
 
 export function systemdQuote(value) {

package/src/shared/tool-catalog.json

@@ -318,7 +318,7 @@
   {
     "name": "browser_status",
     "title": "Browser bridge status",
-    "description": "Start or inspect the loopback browser-extension bridge used to automate the user's existing Chromium profile, windows, tabs, and login state.",
+    "description": "Start or inspect the loopback bridge for the Chromium profile where the extension is installed. Machine Bridge does not launch Playwright or another browser process, but cannot infer whether that profile is the user's daily or isolated profile; status reports authenticated extension version, protocol, capabilities, and reload state.",
     "availability": "full",
     "annotations": {
       "readOnlyHint": false,
@@ -334,7 +334,7 @@
   {
     "name": "pair_browser_extension",
     "title": "Pair browser extension",
-    "description": "Open the local pairing page and return the packaged unpacked-extension path for one-time browser installation and pairing.",
+    "description": "Open the local pairing page and return the packaged unpacked-extension path for installation in the user's intended Chromium profile. Pairing is persisted only after an acknowledged version/capability handshake.",
     "availability": "full",
     "annotations": {
       "readOnlyHint": false,
@@ -437,7 +437,7 @@
   {
     "name": "browser_get_source",
     "title": "Read browser page source",
-    "description": "Read bounded serialized current DOM HTML from the active or selected browser tab and optionally from all accessible frames.",
+    "description": "Read bounded serialized current DOM HTML from the active or selected browser tab. max_bytes is one aggregate budget across at most 64 accessible frames, with explicit frame, node, and byte truncation metadata.",
     "availability": "full",
     "annotations": {
       "readOnlyHint": true,
@@ -479,7 +479,7 @@
   {
     "name": "browser_inspect_page",
     "title": "Inspect browser page",
-    "description": "Inspect bounded interactive DOM metadata across accessible frames for links, controls, form fields, accessible names, labels, and roles.",
+    "description": "Inspect a bounded snapshot-version-2 semantic representation across at most 64 accessible frames, with one aggregate element budget, bounded reusable refs, actionability state, bounded page-controlled metadata, and explicit scan/frame truncation.",
     "availability": "full",
     "annotations": {
       "readOnlyHint": true,
@@ -630,7 +630,7 @@
   {
     "name": "browser_action",
     "title": "Operate browser page",
-    "description": "Perform one structured navigation or page action in the user's existing browser tab, with automatic actionability waits and optional fixed DevTools input, without accepting arbitrary JavaScript.",
+    "description": "Perform one structured navigation or page action in the user's existing browser tab without arbitrary JavaScript. Automatic trusted-input fallback occurs only before any DevTools Input command starts; ambiguous post-dispatch failures require inspection before retry.",
     "availability": "full",
     "annotations": {
       "readOnlyHint": false,
@@ -771,7 +771,7 @@
   {
     "name": "browser_fill_form",
     "title": "Fill complex browser form",
-    "description": "Fill multiple fields and optionally submit a complex form in one structured browser transaction. Sensitive values can come from registered local resources and are not returned.",
+    "description": "Fill multiple fields and optionally submit a complex form. Sensitive values can come from registered local resources; errors identify possible earlier mutations without returning field values.",
     "availability": "full",
     "annotations": {
       "readOnlyHint": false,
@@ -950,7 +950,7 @@
   {
     "name": "browser_screenshot",
     "title": "Capture browser screenshot",
-    "description": "Capture the visible area of the active or selected tab from the paired existing browser profile and return it as MCP image content.",
+    "description": "Capture the visible area of the active or selected tab from the paired existing browser profile, restore the previous active tab when safe, avoid focusing another window, and return native MCP image content.",
     "availability": "full",
     "annotations": {
       "readOnlyHint": false,

package/src/worker/index.ts

@@ -3,7 +3,7 @@ import toolCatalog from "../shared/tool-catalog.json";
 import serverMetadata from "../shared/server-metadata.json";
 
 const SERVER_NAME = String(serverMetadata.name);
-const SERVER_VERSION = "0.14.0";
+const SERVER_VERSION = "0.15.0";
 const MCP_PROTOCOL_VERSION = String(serverMetadata.protocolVersion);
 const MCP_SUPPORTED_PROTOCOL_VERSIONS = serverMetadata.supportedProtocolVersions.map((value) => String(value));
 const JSONRPC_VERSION = "2.0";