machine-bridge-mcp 0.14.0 → 0.16.0

package/docs/AUDIT.md

@@ -1,6 +1,29 @@
 # Engineering and security audit
 
-This document records the cross-cutting audit initiated for version 0.12.0, the 0.12.2 cross-platform CI follow-up, and the 0.13.0 architecture/automatic-routing follow-up. It complements, but does not replace, the continuously enforced contracts in `SECURITY.md`, `docs/ENGINEERING.md`, and the test suite.
+This document records the cross-cutting audit initiated for version 0.12.0, the 0.12.2 cross-platform CI follow-up, and the 0.13.0 architecture/automatic-routing follow-up, the 0.15.0 daily-browser and cross-platform hardening review, and the 0.16.0 runtime-boundary review. It complements, but does not replace, the continuously enforced contracts in `SECURITY.md`, `docs/ENGINEERING.md`, and the test suite.
+
+
+## 2026-07-13 runtime-boundary and lifecycle follow-up
+
+This review confirmed that earlier safety controls existed but were distributed across duplicated policy checks, transport-specific pending maps, message-regex errors, and oversized composition files. It reproduced a production-visible Worker defect where a completed client JSON-RPC request key could remain indexed and cause unrelated later calls to fail as duplicate in-flight IDs. Pending calls now use one atomic double-index registry whose terminal `take` operation clears the internal ID, request key, and timer before resolution or rejection; success, daemon error, cancellation, timeout, send failure, and socket loss have behavior coverage.
+
+Policy revision 4 replaces local/Worker/manager interpretations with one contract. The audit found a concrete compound-ACL error: `start_job` was advertised by direct-exec alone even though it creates persistent files. It now requires write plus direct execution; read-only job/resource inspection no longer inherits mutation requirements. Typed errors, shared middleware, explicit runtime lifecycle, process ownership, structured JSON logs, and local/Worker metrics replace ad hoc message parsing and invisible pending state.
+
+The composition roots were reduced by extracting filesystem, process, Git, CLI parsing/admin, ranking, managed-job validation, browser protocol/pairing, Worker HTTP, OAuth, policy, errors, pending calls, and observability. Executable architecture limits prevent these responsibilities from returning. During extraction, a missing local ESM binding was initially hidden by a broad catch and surfaced only as `resource_unavailable`; the catch now rethrows unknown faults, and the stdio generated-resource test exercises the complete state reload path.
+
+Coverage review showed that a large test count had hidden weak orchestration coverage. CI now reports and enforces per-module baselines, while pure policy/CLI/ranking/state modules receive direct branch tests and Worker behavior still runs through workerd. Generated policy documentation eliminates a second hand-maintained ACL description.
+
+## 2026-07-13 daily-browser and cross-platform hardening follow-up
+
+The review first distinguished installation from actual connectivity. The user identified the target as their ordinary Chrome profile and manually loaded the unpacked extension there; it was initially unpaired. After opening the genuine loopback pairing page, a localhost-only live fixture verified that this connected Chrome instance could create and close a real tab, return semantic snapshot refs, traverse an open Shadow DOM, fill a multi-field form, issue trusted text and pointer input, wait for final DOM state, and capture a screenshot without reading unrelated tabs. The product now states the narrower machine-verifiable fact: Machine Bridge does not launch a browser, but an extension cannot infer whether its host profile is the user's daily or isolated profile.
+
+Fault injection then found several state-machine issues that a success-only smoke test could not reveal. WebSocket `open` was treated as extension readiness before protocol validation; pairing state was written before the candidate authenticated; `input_mode: auto` replayed a DOM action after any DevTools failure even when an Input command might already have taken effect; screenshot capture focused the browser window and did not restore the previous active tab; navigation wait used a hidden 30-second deadline independent of the request; and replacement could leave direct/proxied requests pending. Protocol 3 now requires `hello`/`hello_ack` with exact packaged-version/capability equality, persists pairing only after acknowledgement, validates a canonical extension ID plus matching loopback ports, propagates the request deadline, rejects ambiguous post-dispatch retries, restores tab state without stealing focus, and fails interrupted routes with retry guidance.
+
+Hostile-page analysis found that previous limits were result limits rather than work limits: every frame received the full source/element allowance, `outerHTML` was built before truncation, interactive elements and Shadow roots were fully enumerated before slicing, page-controlled strings were not uniformly bounded, and whole-page `innerText` was materialized for waits. Version 0.15.0 applies aggregate budgets across at most 64 frames, uses iterative bounded DOM serialization, limits each page scan to 100,000 nodes, reusable refs to a 10,000-entry LRU, and text search to 2 MiB, bounds metadata, removes URL userinfo, treats secret-like contenteditable controls as sensitive, and reports truncation explicitly. Multi-field failures now identify possible earlier mutations without returning values.
+
+The extension architecture was also corrected: the service worker now owns only pairing/transport/readiness/cancellation/response routing, while fixed `browser-operations.js` owns tab and page orchestration. An executable line-count invariant prevents those concerns from silently merging again. Outside the browser path, the review found that Windows Scheduled Task command construction did not implement CRT backslash-before-quote rules; drive-root or trailing-backslash arguments could be misparsed. A dedicated quoting primitive and platform regression test correct that boundary.
+
+The same pass rechecked Worker OAuth/PKCE, registration/code/token limits, process sessions, managed jobs, state deletion, log redaction/rotation, package contents, dependencies, open issues, and current CI. No additional high-impact code change was justified in those areas. Their documented residuals remain: canonical `full` intentionally exposes the local user's authority, service logs are trimmed at startup rather than continuously, and same-user malicious code or an MCP host can still operate outside Machine Bridge's control.
 
 ## 2026-07-13 architecture and automatic-routing follow-up
 

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/LOGGING.md

@@ -24,7 +24,7 @@ The CLI accepts:
 --verbose    # alias for debug
 ```
 
-Foreground mode defaults to `info`. Platform autostart services use `warn`.
+Foreground mode defaults to `info` and human-readable text. Platform autostart services use `warn` with newline-delimited JSON. Foreground operators can select JSON explicitly with `--log-format json`.
 
 | Level | Intended events |
 |---|---|
@@ -101,6 +101,12 @@ The logger exposes two intentional plain-output boundaries. `safePlain` sanitize
 
 This is defense in depth, not content classification. Unknown, split, transformed, encrypted, or application-specific secret formats can evade pattern matching, which is why tool arguments and outputs are omitted rather than merely filtered.
 
+## Structured lifecycle events
+
+The local execution middleware emits bounded events such as `tool.call.started`, `tool.call.completed`, `tool.call.failed`, `tool.call.slow`, and `tool.call.cancel_requested`. Stable fields include a shortened call ID, tool name, origin, duration, error code, and retryability. The Worker emits JSON events for HTTP failures and daemon socket errors. Structured values still pass through field-name and value redaction; JSON format is not permission to log arguments or results.
+
+`server_info` is the operational metrics surface. Local metrics include lifecycle state, active and maximum calls, oldest-call age, active-process ownership, per-tool duration buckets, and error-code counts. Worker metrics include HTTP status classes, pending internal/request-key indexes, per-tool outcomes, daemon candidate/authenticated/disconnected counts, and protocol-error counts. Metrics contain counts and bounded identifiers, not request arguments or result contents.
+
 ## Files
 
 Autostart logs are stored below the owner-only state root:

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,14 @@ 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.
+### Lifecycle and pending-call diagnosis
+
+`server_info.runtime.lifecycle` reports `ready`, `starting`, `running`, `failed`, `stopping`, or `stopped`. `runtime.observability.in_flight_calls` and `runtime.observability.processes` distinguish a blocked call from a surviving process. Worker `server_info.worker.pending_calls` reports both the internal-call index and client request-key index; they must return to zero after a terminal result, cancellation, timeout, send failure, or daemon disconnect. Nonzero request-key counts after active calls reach zero indicate a lifecycle defect rather than normal load.
+
+Stable errors include `policy_denied`, `invalid_request`, `timeout`, `cancelled`, `network_error`, `unavailable`, `limit_exceeded`, and `integrity_error`, with retryability metadata. Diagnose by code first; free-form messages are guidance, not an API contract.
+
+
+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`. Installed services pass `--log-level warn --log-format json`, so each active line is a bounded JSON event suitable for ingestion. 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,14 +207,14 @@ 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.
 
 ## Upgrade behavior
 
-Policy revision 3 makes named profiles canonical. A state entry labelled `full` is repaired to writes, direct processes, process sessions, shell execution, unrestricted direct filesystem paths, absolute path output, the complete parent environment, and the complete tool catalog. CLI capability overrides are stored as `custom`. The exact pre-0.4 implicit-default shape is still migrated to the current `full` default; explicit restrictive and identified custom profiles remain preserved.
+Policy revision 4 makes named profiles canonical and evaluates compound tool requirements from the shared contract. A state entry labelled `full` is repaired to writes, direct processes, process sessions, shell execution, unrestricted direct filesystem paths, absolute path output, the complete parent environment, and the complete tool catalog. CLI capability overrides are stored as `custom`. The exact pre-0.4 implicit-default shape is still migrated to the current `full` default; explicit restrictive and identified custom profiles remain preserved.
 
 `full` removes Machine Bridge's own profile/path/environment/shell denials and makes the complete catalog available to the relay. It does not force a connector host to expose every relayed tool, and the server cannot see the host's final subset. It also does not override operating-system access controls, endpoint security, remote authentication, cloud IAM, `sudo`, or independent MCP-host/platform policy.
 

package/docs/POLICY_REFERENCE.md

@@ -0,0 +1,88 @@
+# Policy reference
+
+> Generated from `src/shared/policy-contract.json` and `src/shared/tool-catalog.json`. Do not edit this file manually.
+
+Policy revision: **4**. Default profile: **full**.
+
+## Canonical profiles
+
+| Capability | review | edit | agent | full |
+|---|---|---|---|---|
+| Write | no | yes | yes | yes |
+| Execution mode | off | off | direct | shell |
+| Unrestricted paths | no | no | no | yes |
+| Minimal environment | yes | yes | yes | no |
+| Absolute paths | no | no | no | yes |
+
+## Availability classes
+
+| Class | Requirements |
+|---|---|
+| `always` | none |
+| `write` | write |
+| `direct-exec` | exec in direct/shell |
+| `write+direct-exec` | write, exec in direct/shell |
+| `shell-exec` | exec in shell |
+| `full` | profile = full, write, exec in shell, unrestricted paths = true, minimal env = false, absolute paths = true |
+
+## Tool access
+
+| Tool | Availability | review | edit | agent | full |
+|---|---|---|---|---|---|
+| `agent_context` | `always` | yes | yes | yes | yes |
+| `apply_patch` | `write` | no | yes | yes | yes |
+| `browser_action` | `full` | no | no | no | yes |
+| `browser_fill_form` | `full` | no | no | no | yes |
+| `browser_get_source` | `full` | no | no | no | yes |
+| `browser_inspect_page` | `full` | no | no | no | yes |
+| `browser_list_tabs` | `full` | no | no | no | yes |
+| `browser_manage_tabs` | `full` | no | no | no | yes |
+| `browser_screenshot` | `full` | no | no | no | yes |
+| `browser_status` | `full` | no | no | no | yes |
+| `browser_upload_files` | `full` | no | no | no | yes |
+| `browser_wait` | `full` | no | no | no | yes |
+| `cancel_job` | `write` | no | yes | yes | yes |
+| `diagnose_runtime` | `always` | yes | yes | yes | yes |
+| `edit_file` | `write` | no | yes | yes | yes |
+| `exec_command` | `shell-exec` | no | no | no | yes |
+| `generate_ssh_key_resource` | `full` | no | no | no | yes |
+| `git_diff` | `always` | yes | yes | yes | yes |
+| `git_log` | `always` | yes | yes | yes | yes |
+| `git_show` | `always` | yes | yes | yes | yes |
+| `git_status` | `always` | yes | yes | yes | yes |
+| `inspect_local_application` | `full` | no | no | no | yes |
+| `kill_process` | `direct-exec` | no | no | yes | yes |
+| `list_dir` | `always` | yes | yes | yes | yes |
+| `list_files` | `always` | yes | yes | yes | yes |
+| `list_jobs` | `always` | yes | yes | yes | yes |
+| `list_local_applications` | `full` | no | no | no | yes |
+| `list_local_commands` | `always` | yes | yes | yes | yes |
+| `list_local_resources` | `always` | yes | yes | yes | yes |
+| `list_local_skills` | `always` | yes | yes | yes | yes |
+| `list_roots` | `always` | yes | yes | yes | yes |
+| `load_local_skill` | `always` | yes | yes | yes | yes |
+| `open_local_application` | `full` | no | no | no | yes |
+| `operate_local_application` | `full` | no | no | no | yes |
+| `pair_browser_extension` | `full` | no | no | no | yes |
+| `project_overview` | `always` | yes | yes | yes | yes |
+| `read_file` | `always` | yes | yes | yes | yes |
+| `read_job` | `always` | yes | yes | yes | yes |
+| `read_process` | `direct-exec` | no | no | yes | yes |
+| `resolve_task_capabilities` | `always` | yes | yes | yes | yes |
+| `run_local_command` | `direct-exec` | no | no | yes | yes |
+| `run_process` | `direct-exec` | no | no | yes | yes |
+| `search_text` | `always` | yes | yes | yes | yes |
+| `server_info` | `always` | yes | yes | yes | yes |
+| `session_bootstrap` | `always` | yes | yes | yes | yes |
+| `stage_job` | `write` | no | yes | yes | yes |
+| `start_job` | `write+direct-exec` | no | no | yes | yes |
+| `start_process` | `direct-exec` | no | no | yes | yes |
+| `view_image` | `always` | yes | yes | yes | yes |
+| `write_file` | `write` | no | yes | yes | yes |
+| `write_process` | `direct-exec` | no | no | yes | yes |
+
+## Enforcement contract
+
+The local runtime and Cloudflare Worker both load the same policy contract. Tool advertisement and execution authorization use the catalog availability class; manager-level checks call the same gate rather than reimplementing profile logic.
+
+A custom policy is evaluated by capabilities, not by its display name. Compound classes such as `write+direct-exec` require every listed capability.

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,14 @@ 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.
+
+
+## Critical-module coverage gate
+
+`npm run coverage:test` runs selected in-process and lightweight entrypoint fixtures under V8 coverage and enforces per-module baselines for policy, typed errors, call registration, execution middleware, lifecycle/observability, logging, Runtime/CLI orchestration, and Worker pending/policy/error modules. The full stdio and Worker OAuth/MCP integrations run separately in the main suite and are not duplicated inside coverage collection. The gate deliberately reports each module rather than one aggregate percentage. JavaScript modules enforce function and branch minima; Node's direct TypeScript stripping does not expose trustworthy branch ranges, so TypeScript modules enforce function coverage plus explicit state-machine tests and the real workerd integration suite.
+
+The current CLI entrypoint remains the weakest covered orchestration surface; its baseline is therefore reported and locked independently, while extracted `cli-options` and `cli-policy` pure modules carry substantially higher thresholds. A refactor may raise a threshold, but must not lower one merely to make CI green without an explicit audit explanation.
 
 ## Additional release checks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.14.0",
+  "version": "0.16.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 policy:test && npm run policy-docs:check && npm run runtime-infrastructure:test && npm run runtime-handlers:test && npm run cli-entrypoint:test && npm run lifecycle:test && npm run logging-structure:test && npm run coverage:test && npm run worker-runtime-infrastructure: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 capability-ranking: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,20 @@
     "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",
+    "policy:test": "node tests/policy-test.mjs",
+    "runtime-infrastructure:test": "node tests/runtime-infrastructure-test.mjs",
+    "worker-runtime-infrastructure:test": "node tests/worker-runtime-infrastructure-test.mjs",
+    "logging-structure:test": "node tests/logging-structure-test.mjs",
+    "policy-docs:generate": "node scripts/generate-policy-reference.mjs",
+    "policy-docs:check": "node scripts/generate-policy-reference.mjs --check",
+    "coverage:test": "node scripts/coverage-check.mjs",
+    "capability-ranking:test": "node tests/capability-ranking-test.mjs",
+    "lifecycle:test": "node tests/lifecycle-test.mjs",
+    "runtime-handlers:test": "node tests/runtime-handler-matrix-test.mjs",
+    "cli-entrypoint:test": "node tests/cli-entrypoint-test.mjs"
   },
   "dependencies": {
     "https-proxy-agent": "9.1.0",

package/scripts/coverage-check.mjs

@@ -0,0 +1,108 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const coverageDir = mkdtempSync(resolve(tmpdir(), "machine-bridge-coverage-"));
+const tests = [
+  "tests/policy-test.mjs",
+  "tests/runtime-infrastructure-test.mjs",
+  "tests/worker-runtime-infrastructure-test.mjs",
+  "tests/logging-structure-test.mjs",
+  "tests/runtime-handler-matrix-test.mjs",
+  "tests/cli-entrypoint-test.mjs",
+  "tests/local-self-test.mjs",
+];
+
+try {
+  for (const test of tests) {
+    const run = spawnSync(process.execPath, [test], {
+      cwd: root,
+      env: { ...process.env, NODE_V8_COVERAGE: coverageDir },
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    if (run.status !== 0) {
+      process.stdout.write(run.stdout || "");
+      process.stderr.write(run.stderr || "");
+      throw new Error(`coverage fixture failed: ${test}`);
+    }
+  }
+
+  const coverage = collectCoverage(coverageDir);
+  const thresholds = {
+    "src/local/policy.mjs": [75, 45],
+    "src/local/errors.mjs": [70, 50],
+    "src/local/call-registry.mjs": [80, 50],
+    "src/local/tool-executor.mjs": [90, 25],
+    "src/local/observability.mjs": [65, 35],
+    "src/local/process-tracker.mjs": [65, 35],
+    "src/local/log.mjs": [60, 40],
+    "src/local/runtime.mjs": [60, 35],
+    "src/local/cli.mjs": [40, 5],
+    "src/local/cli-options.mjs": [65, 35],
+    "src/local/cli-policy.mjs": [70, 35],
+    "src/worker/pending-calls.ts": [85, null],
+    "src/worker/policy.ts": [90, null],
+    "src/worker/errors.ts": [100, null],
+  };
+  const failures = [];
+  for (const [file, [minimumFunctions, minimumBlocks]] of Object.entries(thresholds)) {
+    const metric = coverage.get(file);
+    if (!metric) {
+      failures.push(`${file}: no coverage data`);
+      continue;
+    }
+    const functionPercent = percent(metric.functionsCovered, metric.functionsTotal);
+    const blockPercent = percent(metric.blocksCovered, metric.blocksTotal);
+    console.log(`${file}: functions ${functionPercent.toFixed(1)}% (${metric.functionsCovered}/${metric.functionsTotal}), blocks ${blockPercent.toFixed(1)}% (${metric.blocksCovered}/${metric.blocksTotal})`);
+    if (functionPercent < minimumFunctions) failures.push(`${file}: function coverage ${functionPercent.toFixed(1)}% < ${minimumFunctions}%`);
+    if (minimumBlocks !== null && blockPercent < minimumBlocks) failures.push(`${file}: block coverage ${blockPercent.toFixed(1)}% < ${minimumBlocks}%`);
+  }
+  if (failures.length) throw new Error(`coverage thresholds failed:\n- ${failures.join("\n- ")}`);
+  console.log("critical-module coverage thresholds passed");
+} finally {
+  rmSync(coverageDir, { recursive: true, force: true });
+}
+
+function collectCoverage(directory) {
+  const scripts = new Map();
+  for (const filename of readdirSync(directory)) {
+    const report = JSON.parse(readFileSync(resolve(directory, filename), "utf8"));
+    for (const script of report.result || []) {
+      if (!String(script.url).startsWith("file://")) continue;
+      const absolute = fileURLToPath(script.url);
+      const repositoryRelative = relative(root, absolute);
+      if (!repositoryRelative || repositoryRelative === ".." || repositoryRelative.startsWith(`..${sep}`) || isAbsolute(repositoryRelative)) continue;
+      const file = repositoryRelative.split(sep).join("/");
+      if (!file.startsWith("src/")) continue;
+      let entry = scripts.get(file);
+      if (!entry) {
+        entry = { functions: new Map(), blocks: new Map() };
+        scripts.set(file, entry);
+      }
+      for (const fn of script.functions || []) {
+        if (!fn.ranges?.length) continue;
+        const outer = fn.ranges[0];
+        const functionKey = `${outer.startOffset}:${outer.endOffset}:${fn.functionName}`;
+        entry.functions.set(functionKey, (entry.functions.get(functionKey) || false) || outer.count > 0);
+        for (const range of fn.ranges.slice(1)) {
+          const blockKey = `${range.startOffset}:${range.endOffset}`;
+          entry.blocks.set(blockKey, (entry.blocks.get(blockKey) || false) || range.count > 0);
+        }
+      }
+    }
+  }
+  return new Map([...scripts].map(([file, entry]) => [file, {
+    functionsTotal: entry.functions.size,
+    functionsCovered: [...entry.functions.values()].filter(Boolean).length,
+    blocksTotal: entry.blocks.size,
+    blocksCovered: [...entry.blocks.values()].filter(Boolean).length,
+  }]));
+}
+
+function percent(covered, total) {
+  return total ? covered * 100 / total : 100;
+}

package/scripts/generate-policy-reference.mjs

@@ -0,0 +1,95 @@
+import { readFile, writeFile } from "node:fs/promises";
+import process from "node:process";
+
+const root = new URL("../", import.meta.url);
+const contract = JSON.parse(await readFile(new URL("src/shared/policy-contract.json", root), "utf8"));
+const catalog = JSON.parse(await readFile(new URL("src/shared/tool-catalog.json", root), "utf8"));
+const target = new URL("docs/POLICY_REFERENCE.md", root);
+const generated = render(contract, catalog);
+
+if (process.argv.includes("--check")) {
+  const current = await readFile(target, "utf8").catch(() => "");
+  if (normalizeLineEndings(current) !== generated) {
+    console.error("docs/POLICY_REFERENCE.md is stale; run npm run policy-docs:generate");
+    process.exitCode = 1;
+  } else {
+    console.log("policy reference is up to date");
+  }
+} else {
+  await writeFile(target, generated, "utf8");
+  console.log("generated docs/POLICY_REFERENCE.md");
+}
+
+function render(value, tools) {
+  const profileNames = Object.keys(value.profiles);
+  const lines = [
+    "# Policy reference",
+    "",
+    "> Generated from `src/shared/policy-contract.json` and `src/shared/tool-catalog.json`. Do not edit this file manually.",
+    "",
+    `Policy revision: **${value.revision}**. Default profile: **${value.defaultProfile}**.`,
+    "",
+    "## Canonical profiles",
+    "",
+    `| Capability | ${profileNames.join(" | ")} |`,
+    `|---|${profileNames.map(() => "---").join("|")}|`,
+  ];
+  for (const [label, key] of [
+    ["Write", "allowWrite"],
+    ["Execution mode", "execMode"],
+    ["Unrestricted paths", "unrestrictedPaths"],
+    ["Minimal environment", "minimalEnv"],
+    ["Absolute paths", "exposeAbsolutePaths"],
+  ]) {
+    lines.push(`| ${label} | ${profileNames.map((name) => display(value.profiles[name][key])).join(" | ")} |`);
+  }
+  lines.push("", "## Availability classes", "", "| Class | Requirements |", "|---|---|");
+  for (const [name, requirement] of Object.entries(value.availability)) {
+    lines.push(`| \`${name}\` | ${requirementText(requirement)} |`);
+  }
+  lines.push("", "## Tool access", "", `| Tool | Availability | ${profileNames.join(" | ")} |`, `|---|---|${profileNames.map(() => "---").join("|")}|`);
+  for (const tool of [...tools].sort((left, right) => left.name.localeCompare(right.name))) {
+    const cells = profileNames.map((name) => allows(value.profiles[name], value.availability[tool.availability]) ? "yes" : "no");
+    lines.push(`| \`${tool.name}\` | \`${tool.availability}\` | ${cells.join(" | ")} |`);
+  }
+  lines.push(
+    "",
+    "## Enforcement contract",
+    "",
+    "The local runtime and Cloudflare Worker both load the same policy contract. Tool advertisement and execution authorization use the catalog availability class; manager-level checks call the same gate rather than reimplementing profile logic.",
+    "",
+    "A custom policy is evaluated by capabilities, not by its display name. Compound classes such as `write+direct-exec` require every listed capability.",
+    "",
+  );
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function allows(policy, requirement = {}) {
+  if (requirement.profile && policy.profile !== requirement.profile) return false;
+  if (requirement.allowWrite === true && policy.allowWrite !== true) return false;
+  if (Array.isArray(requirement.execModes) && !requirement.execModes.includes(policy.execMode)) return false;
+  if (typeof requirement.unrestrictedPaths === "boolean" && policy.unrestrictedPaths !== requirement.unrestrictedPaths) return false;
+  if (typeof requirement.minimalEnv === "boolean" && policy.minimalEnv !== requirement.minimalEnv) return false;
+  if (typeof requirement.exposeAbsolutePaths === "boolean" && policy.exposeAbsolutePaths !== requirement.exposeAbsolutePaths) return false;
+  return true;
+}
+
+function requirementText(requirement) {
+  const parts = [];
+  if (requirement.profile) parts.push(`profile = ${requirement.profile}`);
+  if (requirement.allowWrite === true) parts.push("write");
+  if (requirement.execModes) parts.push(`exec in ${requirement.execModes.join("/")}`);
+  if (typeof requirement.unrestrictedPaths === "boolean") parts.push(`unrestricted paths = ${requirement.unrestrictedPaths}`);
+  if (typeof requirement.minimalEnv === "boolean") parts.push(`minimal env = ${requirement.minimalEnv}`);
+  if (typeof requirement.exposeAbsolutePaths === "boolean") parts.push(`absolute paths = ${requirement.exposeAbsolutePaths}`);
+  return parts.length ? parts.join(", ") : "none";
+}
+
+function display(value) {
+  if (typeof value === "boolean") return value ? "yes" : "no";
+  return String(value);
+}
+
+function normalizeLineEndings(value) {
+  return String(value).replace(/\r\n/g, "\n");
+}