machine-bridge-mcp 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.16.0 - 2026-07-13
+
+### Runtime boundaries and lifecycle
+
+- Replace the monolithic local tool dispatcher with a middleware-based execution pipeline covering policy authorization, bounded call registration, cancellation/deadlines, stable error normalization, structured lifecycle events, and per-tool metrics. Add explicit runtime lifecycle states and a process tracker so stop/cancel paths release calls and child ownership deterministically.
+- Extract workspace filesystem transactions, process/shell execution, Git operations, CLI option/policy parsing, local resource/browser/job administration, capability ranking, managed-job plan/resource validation, browser extension protocol handling, and browser pairing persistence into focused modules. Add executable line-count and dependency-direction limits so these responsibilities cannot silently return to `LocalRuntime`, the CLI entrypoint, or browser manager.
+- Split the Worker Durable Object into HTTP/CORS boundaries, OAuth state/PKCE helpers, shared policy evaluation, structured errors, pending-call indexing, and observability. Replace the linear pending-call scan with an atomic ID/request-key registry so completed, cancelled, timed-out, send-failed, and disconnected calls clear both indexes before settling; JSON-RPC request IDs can be reused immediately after completion.
+
+### Policy, errors, logging, and observability
+
+- Define policy revision 4 in one shared contract consumed by the local daemon, Worker, generated documentation, tests, and architecture checks. Fix `start_job` to require both write and direct-execution capabilities, keep `cancel_job` write-gated, and expose read-only resource/job inventory to review-mode clients without granting mutation authority.
+- Introduce typed `BridgeError`/Worker errors with allowlisted stable codes and retryability. Centralize legacy error classification at adapters instead of making transports and tests depend on free-form English messages. Unknown programming errors are no longer silently converted into ordinary managed-resource unavailability; a failing timeout callback still settles and clears its pending indexes.
+- Add structured JSON lifecycle logging and in-memory observability for calls, durations, errors, active processes, pending request indexes, daemon candidates, socket transitions, and per-tool outcomes. Autostart services now use warning-level JSON logs by default while foreground output remains human-readable; local and Worker structured-field redaction is behavior-tested.
+
+### Tests, documentation, and audit follow-up
+
+- Add behavior tests for policy parity, compound ACLs, middleware order, runtime lifecycle transitions, process ownership, pending-ID reuse, socket cleanup, Worker/local error serialization, structured log privacy, bilingual capability ranking, and generated policy documentation. Replace brittle source-string and monkeypatched happy-path tests with production-path deadline, process-tree, OAuth/MCP, and resource-reload coverage.
+- Add a critical-module V8 coverage gate with per-module function/branch baselines, rather than a single aggregate percentage that hides weak orchestration coverage. Generate `docs/POLICY_REFERENCE.md` from the shared policy contract and tool catalog; CI rejects stale generated documentation.
+- Correct an extraction defect where a re-exported resource inspector was not locally bound and a broad catch disguised the resulting `ReferenceError` as `resource_unavailable`. File availability now degrades only for classified filesystem conditions; unexpected implementation faults remain visible.
+
 ## 0.15.0 - 2026-07-13
 
 ### Daily-profile browser verification and protocol safety

package/README.md

@@ -32,7 +32,7 @@ A newly selected workspace starts with the maximum-permission `full` profile for
 - tool results may return absolute paths;
 - child processes inherit the complete parent environment.
 
-Policy state records whether it came from the default, an explicit named profile, or custom overrides. Named profiles are canonical contracts: a stored `full` profile is repaired on load to enable writes, shell execution, unrestricted paths, full parent environment, absolute path output, and the complete tool catalog. Any explicit per-capability narrowing is stored as `custom`. Policy revision 3 refreshes default/migrated state and preserves explicit restrictive/custom profiles.
+Policy state records whether it came from the default, an explicit named profile, or custom overrides. Named profiles are canonical contracts: a stored `full` profile is repaired on load to enable writes, shell execution, unrestricted paths, full parent environment, absolute path output, and the complete tool catalog. Any explicit per-capability narrowing is stored as `custom`. Policy revision 4 normalizes named profiles from the shared contract, refreshes default/migrated state, preserves explicit restrictive/custom profiles, and applies compound tool requirements consistently in the local daemon and Worker.
 
 | Profile | File edits | Direct argv processes | Shell commands | Filesystem scope | Process environment |
 |---|---:|---:|---:|---|---|
@@ -199,8 +199,17 @@ Load the printed unpacked-extension directory in the Chromium profile you actual
 
 Machine Bridge can discover, refresh, rank, and load capabilities automatically. The ChatGPT/MCP host still owns tool selection and approval, so the server cannot force a host to expose or invoke a recommended skill, command, app, or browser operation. Check `server_info.observability.capability_routing` or `project_overview.capabilityRouting` to distinguish “the host never called the resolver” from “the resolver ran but found no relevant capability.”
 
+
+## Runtime lifecycle and observability
+
+Every tool call passes through one execution pipeline: bounded call registration and deadline/cancellation ownership, structured observability, shared policy authorization, then the typed handler. Errors use stable codes and retryability metadata instead of transport-specific message parsing. `server_info` exposes the local lifecycle state, in-flight calls, active process ownership, per-tool outcomes, durations, and error-code counts. The Worker adds pending internal/request-key indexes, daemon candidate/socket counters, and Worker-side per-tool outcomes.
+
+Foreground logging defaults to human-readable text. Installed background services use warning-level JSON events by default. Use `--log-format json` for machine-readable foreground logs; arguments, outputs, credentials, resource contents, and local paths remain excluded or redacted.
+
 ## Policy controls
 
+Policy revision 4 is defined once in `src/shared/policy-contract.json`. The local runtime, Worker advertisement filter, manager-level defense-in-depth checks, tests, and generated [policy reference](docs/POLICY_REFERENCE.md) consume that same contract. A custom policy is authorized by capabilities rather than its display name; compound classes such as `write+direct-exec` require every capability.
+
 The default is `full`. Narrow or customize it with explicit flags:
 
 ```text
@@ -212,6 +221,7 @@ The default is `full`. Narrow or customize it with explicit flags:
 --unrestricted-paths
 --absolute-paths
 --log-level error|warn|info|debug
+--log-format text|json
 --verbose
 --quiet
 ```
@@ -432,7 +442,7 @@ Remote mode supports:
 - Linux `systemd --user`, with best-effort lingering;
 - Windows Scheduled Task at logon.
 
-The service definition contains neither credentials nor a duplicate policy. It loads the selected policy from owner-only local state and uses the documented `full` default if policy state is absent. launchd/systemd definitions persist a sanitized absolute-only PATH captured during installation, including the stable Node/CLI directories, so background `full` mode does not lose Homebrew or other developer command locations. Background services run at log level `warn`: relay, protocol, and service problems are retained, while all per-tool success/failure/cancellation/timing events remain debug-only. Logs are owner-only where supported and bounded by tail trimming.
+The service definition contains neither credentials nor a duplicate policy. It loads the selected policy from owner-only local state and uses the documented `full` default if policy state is absent. launchd/systemd definitions persist a sanitized absolute-only PATH captured during installation, including the stable Node/CLI directories, so background `full` mode does not lose Homebrew or other developer command locations. Background services run at log level `warn` with JSON output: relay, protocol, and service problems are retained as bounded structured events, while all per-tool success/failure/cancellation/timing events remain debug-only. Logs are owner-only where supported and bounded by tail trimming.
 
 ## Secret rotation
 

package/SECURITY.md

@@ -79,6 +79,13 @@ Caller-supplied JavaScript, AppleScript, JXA source, and arbitrary DevTools meth
 
 Text and file resources can be injected locally so their contents do not appear in MCP arguments or results. The destination page/application still receives the value, and remote tool metadata/results still traverse the Worker and host. Page source and screenshots can themselves contain secrets. Source/inspection budgets are aggregate across frames, page-controlled metadata is bounded, URL userinfo is removed from semantic snapshots, and contenteditable controls with secret-like identity are treated as sensitive; these limits reduce accidental exposure but do not classify every possible secret. Browser/app tool arguments, source, screenshots, field values, and results are intentionally omitted from operational logs.
 
+
+## Shared authorization contract
+
+Policy revision 4 is a single source of truth shared by the local daemon and Worker. The catalog availability class controls both advertisement and execution; manager-level checks invoke the same gate as defense in depth. Custom policies are evaluated by capabilities, so a label cannot impersonate `full`. Persistent job start requires both write and direct-execution authority; read-only job/resource inventory does not imply mutation authority.
+
+Transport-visible failures use stable error codes and retryability. Unexpected implementation errors are not downgraded to ordinary resource state, and raw internal exceptions are not returned by the Worker. This reduces both authorization drift and accidental disclosure through error strings.
+
 ## Filesystem exposure
 
 Direct filesystem scope is profile-dependent. The default `full` profile is unrestricted. The `agent`, `edit`, and `review` profiles confine direct filesystem tools to the canonical selected workspace, including symbolic-link resolution.

package/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Machine Bridge Browser",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Connects the current Chromium browser profile to the local Machine Bridge runtime for user-authorized automation.",
   "permissions": [
     "tabs",
@@ -30,5 +30,5 @@
   "action": {
     "default_title": "Machine Bridge Browser"
   },
-  "version_name": "0.15.0"
+  "version_name": "0.16.0"
 }

package/docs/ARCHITECTURE.md

@@ -58,7 +58,7 @@ See [Session instructions, skills, commands, and capability discovery](AGENT_CON
 
 ### Browser extension and machine broker
 
-`BrowserBridgeManager` owns a loopback HTTP/WebSocket broker. The first runtime for the machine-level state root becomes broker owner; additional workspaces and stdio runtimes authenticate to `/runtime` and proxy through the same extension socket. This preserves one extension pairing while allowing multiple local MCP runtimes.
+`BrowserBridgeManager` owns connection orchestration for a loopback HTTP/WebSocket broker. Extension version/capability parsing lives in `browser-extension-protocol.mjs`; pairing files and local HTML/Host/Origin helpers live in `browser-pairing-store.mjs`. The first runtime for the machine-level state root becomes broker owner; additional workspaces and stdio runtimes authenticate to `/runtime` and proxy through the same extension socket. This preserves one extension pairing while allowing multiple local MCP runtimes.
 
 The packaged Manifest V3 extension runs in the user's existing Chromium profile. Its service worker is limited to pairing, transport, acknowledged protocol readiness, cancellation, and response routing. Fixed `browser-operations.js` owns tab lifecycle, aggregate frame/source budgets, waits, screenshots, and input-backend selection; fixed `page-automation.js` is injected into selected frames for snapshot-version-2 semantics, stable refs, bounded DOM/text traversal, actionability checks, open-Shadow-DOM traversal, structured DOM operations, multi-field forms, and resource-backed file inputs. Fixed `devtools-input.js` exposes only bounded mouse, keyboard, and text sequences through the Chromium debugger API; callers cannot select CDP methods. Trusted sessions attach for one action and detach in `finally`; DOM fallback is allowed only before any DevTools Input dispatch, preventing duplicate side effects after an ambiguous command failure. Protocol 3 requires bidirectional `hello`/`hello_ack` plus exact packaged-version and capability equality; pairing state and replacement are committed only after validation, so an invalid candidate cannot displace or overwrite the working configuration. The broker validates loopback hostnames, canonical extension IDs, matching pairing/broker ports, bearer subprotocols, message sizes, concurrency, and deadlines. Pairing material is owner-only and omitted from MCP/log output.
 
@@ -86,7 +86,9 @@ Local resource registrations remain in owner-only state and are reloaded for eve
 
 ### Canonical policy contracts
 
-Named profiles are normalized to their complete capability sets. In particular, `full` always means write enabled, shell execution, unrestricted paths, complete parent environment, absolute-path display, and every catalog tool. CLI flags that alter an individual capability deliberately change the profile identity to `custom`. Policy revision 3 repairs stale or manually edited named-profile fields rather than allowing a misleading partially restricted `full` label.
+Policy revision 4 is loaded from one shared JSON contract by both local and Worker policy evaluators. Tool advertisement and execution authorization use catalog availability classes; managers receive the same authorizer instead of reimplementing profile conditionals. Read-only job/resource inspection is `always`, job cancellation is write-gated, and starting a persistent job requires `write+direct-exec`.
+
+Named profiles are normalized to their complete capability sets. In particular, `full` always means write enabled, shell execution, unrestricted paths, complete parent environment, absolute-path display, and every catalog tool. CLI flags that alter an individual capability deliberately change the profile identity to `custom`. Policy revision 4 repairs stale or manually edited named-profile fields rather than allowing a misleading partially restricted `full` label, and applies compound availability requirements from the shared contract.
 
 The full-only `generate_ssh_key_resource` operation is implemented locally. The Worker only filters and relays its shared catalog definition. Local generation uses `ssh-keygen`, verifies public/private correspondence, registers the private file through the same owner-only state transaction as the CLI, and rolls back a newly created pair if state persistence fails.
 
@@ -111,7 +113,7 @@ The daemon attachment deliberately omits workspace path/name/hash and process ID
 
 ### Autostart layer
 
-The service layer emits launchd, systemd-user, or Windows Scheduled Task definitions. Credentials are not embedded in service definitions; the daemon loads owner-only state. The exact policy is stored in owner-only state. launchd/systemd definitions contain the workspace/state-root selectors, a `warn` log-level setting, and a sanitized absolute-only PATH captured at installation so background `full` mode can resolve the same developer tools without accepting relative PATH entries.
+The service layer emits launchd, systemd-user, or Windows Scheduled Task definitions. Credentials are not embedded in service definitions; the daemon loads owner-only state. The exact policy is stored in owner-only state. launchd/systemd definitions contain the workspace/state-root selectors, `warn` plus JSON log settings, and a sanitized absolute-only PATH captured at installation so background `full` mode can resolve the same developer tools without accepting relative PATH entries.
 
 The platform adapters normalize launchd, systemd, and Windows Scheduled Task operations to one `{ok, provider}` result contract. Removal is not a provider-specific sequence: `service-lifecycle.mjs` first stops the provider, then every verified workspace daemon in scope, and only then removes the definition. A failed stop or unverifiable process prevents definition/state deletion.
 

package/docs/AUDIT.md

@@ -1,6 +1,17 @@
 # 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, plus the 0.15.0 daily-browser and cross-platform hardening review. 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
 

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

@@ -101,7 +101,14 @@ Uninstall acquires a state-root `maintenance.lock` that blocks new profile/state
 
 ## Logs
 
-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.
+### 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:
 
@@ -207,7 +214,7 @@ Defense-in-depth limits include:
 
 ## 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

@@ -62,6 +62,13 @@ It opens Calculator, activates it through the fixed JXA helper, verifies structu
 
 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
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.15.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 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",
+    "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",
@@ -78,7 +78,18 @@
     "browser-devtools-input:test": "node tests/browser-devtools-input-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"
+    "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");
+}