machine-bridge-mcp 1.1.5 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.2.0 - 2026-07-16
+
+### Typed evolution boundaries and project governance
+
+- Split the highest-change orchestration modules along real lifecycle boundaries. Worker OAuth storage, registration, authorization, account administration, token verification, and mutation serialization now live in `OAuthController`; local runtime reporting, fixed diagnostics, and capability composition have dedicated services; Agent configuration/path validation and browser MCP operation semantics no longer share files with discovery or loopback broker transport. Persisted state schema 6, policy revision 5, token records, browser pairing, resources, and managed-job data remain unchanged for an in-place upgrade from 1.1.5.
+- Make Worker TypeScript imports explicit and directly executable under Node 26, including `.ts` specifiers and JSON import attributes. Add a focused OAuth-controller state-machine suite covering registration throttling, authorization failure/success, resource-bound access tokens, expiry pruning, schema mismatch, and missing identity keys while retaining the real workerd OAuth/MCP integration.
+- Add a strict checked-JavaScript contract gate for local policy, call lifecycle, Agent configuration and path containment, browser handshake parsing, capability ranking, monotonic deadlines, record/number normalization, and bounded metadata reads. Expand correctness linting to reject async Promise executors, returned Promise-executor values, unsafe `finally`, useless catches, invalid `typeof`, self-assignment, and invalid NaN comparisons, and unused imports/variables; fix every newly detected occurrence rather than waiving the rules.
+- Raise risk-directed coverage gates and include Agent, browser, runtime-boundary, and OAuth-controller fixtures. Worker pending-call and policy modules now have branch floors; the extracted runtime reporting, diagnostics, capability, browser operation, browser protocol, Agent contract, and capability-ranking modules have independent function and branch minima. Lower architecture line caps prevent the orchestration modules from regaining the extracted responsibilities.
+- Add a five-minute README path, explicit Node 26/npm 12 support boundaries, a current-only upgrade and rollback contract, support/reporting guidance, project governance and succession rules, and a code of conduct. The first control required after a second active maintainer joins is non-author and last-push approval for security-sensitive code and release surfaces.
+- Preserve release and supply-chain behavior: no live npm publication, Worker deployment, secret rotation, or daemon/service replacement is performed by this source release. Trusted npm publishing with GitHub OIDC still requires the external package-owner trust relationship and remains the next publication-control improvement.
+
 ## 1.1.5 - 2026-07-16
 
 ### Windows autostart and persisted network environment

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,24 @@
+# Code of conduct
+
+## Expected behavior
+
+Project participation must remain technical, evidence-based, and respectful. Contributors and maintainers are expected to:
+
+- discuss the causal mechanism of a problem rather than attacking the person reporting it;
+- distinguish verified behavior from assumptions and speculation;
+- disclose relevant conflicts of interest;
+- avoid publishing credentials, private paths, account identifiers, or other sensitive environment data;
+- accept correction when tests, specifications, or reproducible evidence contradict a claim;
+- keep review focused on correctness, security, privacy, compatibility, and maintainability.
+
+Harassment, threats, discriminatory language, doxxing, deliberate disruption, and repeated bad-faith interaction are not accepted in project spaces.
+
+## Scope
+
+This policy applies to repository issues, pull requests, discussions, release channels, security-report interactions, and other spaces where a person represents this project.
+
+## Reporting and enforcement
+
+Security vulnerabilities must follow [SECURITY.md](SECURITY.md). Other conduct concerns should be reported privately to the repository owner through the contact method on the maintainer's GitHub profile. Do not open a public issue containing private conduct reports or personal information.
+
+The maintainer may edit or remove content, lock conversations, reject contributions, or temporarily or permanently restrict participation. Enforcement decisions should identify the violated rule and preserve private information. A maintainer who is directly involved in a report must seek review from another trusted maintainer when one is available.

package/CONTRIBUTING.md

@@ -4,7 +4,7 @@ This repository treats every Git-tracked or nonignored repository file as releas
 
 ## Development workflow
 
-Read [docs/PROJECT_STANDARDS.md](docs/PROJECT_STANDARDS.md) and the relevant domain documentation before changing behavior. This repository uses GitHub Flow: branch from current `main`, keep the change coherent, open a pull request, satisfy required checks, squash-merge, and delete the branch. Permanent `develop` or generic release integration branches are not used unless an independently maintained release line creates a concrete need. Repository automation performs GitHub operations only through local `git`, `gh`, and `gh api` commands executed by Machine Bridge; hosted GitHub connectors and ChatGPT GitHub plugins are prohibited for this repository.
+Read [docs/PROJECT_STANDARDS.md](docs/PROJECT_STANDARDS.md), [GOVERNANCE.md](GOVERNANCE.md), and the relevant domain documentation before changing behavior. This repository uses GitHub Flow: branch from current `main`, keep the change coherent, open a pull request, satisfy required checks, squash-merge, and delete the branch. Permanent `develop` or generic release integration branches are not used unless an independently maintained release line creates a concrete need. Repository automation performs GitHub operations only through local `git`, `gh`, and `gh api` commands executed by Machine Bridge; hosted GitHub connectors and ChatGPT GitHub plugins are prohibited for this repository.
 
 Branch names use a category and purpose such as `feat/browser-downloads`, `fix/relay-timeout`, or `chore/dependency-policy`.
 
@@ -28,6 +28,8 @@ Before the reviewed code is pushed to `main`:
 
 After all required pull-request checks pass, repository automation completes the source release under [AGENTS.md](AGENTS.md): squash-merge through local `gh`, verify the exact `main` push CI, CodeQL, Governance, and Scorecard runs, create the annotated version tag, and create or update the matching final GitHub Release. The release operator separately publishes the same version to npm and performs any live machine update. Automation must not publish, deprecate, or unpublish npm packages; install the CLI globally; deploy the Worker; rotate credentials; mutate live deployment state; or start/stop/install/remove the daemon or autostart service without explicit user authorization.
 
+Supported upgrade and rollback behavior is defined in [docs/UPGRADING.md](docs/UPGRADING.md). Support requests must follow [SUPPORT.md](SUPPORT.md), and repository participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
 After npm publication, the standard machine update is:
 
 ```bash

package/GOVERNANCE.md

@@ -0,0 +1,50 @@
+# Project governance
+
+## Current ownership
+
+The project currently has one human maintainer, `@YuLeiFuYun`. Repository automation may complete reviewed source changes under [AGENTS.md](AGENTS.md), but automation is not an independent reviewer and cannot replace accountable human ownership.
+
+The maintainer owns product direction, security policy, repository administration, npm package ownership, Cloudflare deployment decisions, and release credentials. Live npm publication, Worker deployment, credential rotation, and daemon/service replacement remain explicit operator actions.
+
+## Decision model
+
+Changes are accepted on technical evidence. The deciding criteria are, in order:
+
+1. preservation of authorization, integrity, privacy, and recovery invariants;
+2. correctness across supported platforms and failure paths;
+3. clarity of public contracts and upgrade behavior;
+4. cohesion, coupling, and long-term maintenance cost;
+5. user value relative to operational complexity.
+
+A product or security invariant may change only through an explicit documented decision with tests, migration consequences, and release notes.
+
+## Maintainer admission and succession
+
+A second maintainer should have a sustained history of high-quality review or contributions, understand the trust boundaries in `SECURITY.md` and `docs/ARCHITECTURE.md`, and be able to operate the release process without access to another person's credentials.
+
+Before granting write or publication authority:
+
+- require hardware-backed multifactor authentication where the platform supports it;
+- add the person to CODEOWNERS for the areas they can review;
+- verify recovery access for GitHub and npm through separate principals;
+- rehearse a release from a protected branch and a non-production test deployment;
+- document how access is revoked if the maintainer becomes unavailable or leaves.
+
+Once a second active maintainer exists, branch protection must require one non-author approval and approval of the last push for changes affecting Worker authorization, policy contracts, process execution, browser automation, persistent state, workflows, security policy, or release tooling.
+
+## Release authority
+
+Source release completion requires the exact `main` commit to pass CI, CodeQL, Governance, and OpenSSF Scorecard gates. The annotated Git tag, GitHub Release, release asset, package version, Worker version, and extension version must identify the same source state.
+
+npm publication should move to trusted publishing with GitHub OIDC and a protected release environment. Until the external npm trust relationship is configured, publication remains a deliberate local operator action and no long-lived npm token may be stored in the repository.
+
+## Inactivity and transfer
+
+If the sole maintainer expects to be unavailable, the preferred order is:
+
+1. appoint and verify a successor before transferring publication or repository authority;
+2. publish a maintenance notice and freeze feature work;
+3. preserve security-report access and package deprecation/recovery capability;
+4. archive the repository only when no qualified successor exists.
+
+No contributor acquires release authority solely through commit volume. Access must be explicit, least-privilege, reviewable, and reversible.

package/README.md

@@ -2,6 +2,32 @@
 
 `machine-bridge-mcp` exposes a selected local workspace to MCP clients through one shared, policy-controlled runtime.
 
+> [!WARNING]
+> The default `full` profile can read and modify local-user-accessible files, run shell commands, control the existing browser profile, and inherit the parent environment. It is not an operating-system sandbox. Use `review`, `edit`, or `agent`, or an isolated OS account/VM, when any client or repository is not fully trusted.
+
+## Start here
+
+Machine Bridge requires **Node.js 26+ and npm 12+**. Older runtimes and obsolete MCP protocol versions are not supported.
+
+1. Follow [Installation and first use](docs/GETTING_STARTED.md).
+2. Run `machine-mcp doctor`.
+3. Start `machine-mcp` in the workspace you intend to expose.
+4. Connect the printed remote MCP URL, or configure [local stdio](#optional-local-stdio-mcp).
+5. For browser control, load and pair the packaged extension, then reload it after every package upgrade.
+
+Choose the documentation path that matches the task:
+
+| Role | Start with |
+|---|---|
+| New user | [Getting started](docs/GETTING_STARTED.md) |
+| Upgrading an installation | [Upgrading](docs/UPGRADING.md) |
+| MCP client integrator | [Clients](docs/CLIENTS.md) |
+| Operator or incident responder | [Operations](docs/OPERATIONS.md) |
+| Security reviewer | [Security policy](SECURITY.md) and [Architecture](docs/ARCHITECTURE.md) |
+| Contributor or maintainer | [Contributing](CONTRIBUTING.md), [Engineering](docs/ENGINEERING.md), and [Governance](GOVERNANCE.md) |
+
+Support boundaries and safe diagnostic requirements are in [SUPPORT.md](SUPPORT.md). Project participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
 It supports two transports:
 
 ```text

package/SUPPORT.md

@@ -0,0 +1,31 @@
+# Support policy
+
+## Supported environment
+
+The supported runtime is the pinned Node.js 26 and npm 12 baseline on current GitHub-hosted Linux, macOS, and Windows environments. Older Node/npm releases and obsolete MCP protocol versions are not compatibility targets.
+
+The project supports the current package version and a direct upgrade from the immediately preceding published version when both use the current local state and policy schemas. See [Upgrading](docs/UPGRADING.md).
+
+## Where to ask
+
+- Reproducible defects: use the bug report template.
+- Feature proposals: use the feature request template.
+- Security vulnerabilities or suspected credential exposure: follow [SECURITY.md](SECURITY.md), not a public issue.
+- General installation and recovery: consult [Getting started](docs/GETTING_STARTED.md) and [Operations](docs/OPERATIONS.md) before filing an issue.
+
+## Required diagnostic information
+
+A useful report includes:
+
+- package version, operating system, Node version, and npm version;
+- whether the transport is remote OAuth relay or local stdio;
+- the active policy profile;
+- the exact command or MCP operation that failed;
+- sanitized output from `machine-mcp doctor` and, when available, `diagnose_runtime`;
+- a minimal reproduction and whether the failure persists in a fresh disposable workspace.
+
+Never include passwords, bearer tokens, private keys, browser pairing material, raw state files, real home/workspace paths, or unredacted logs. Replace them with synthetic values before posting.
+
+## Response expectations
+
+This is currently a single-maintainer project. There is no guaranteed response time or commercial support commitment. Security reports and regressions affecting data integrity, authorization, or release integrity receive priority over feature requests.

package/browser-extension/browser-operations.js

@@ -496,7 +496,7 @@
   }
   
   function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return new Promise((resolve) => { setTimeout(resolve, ms); });
   }
 
   function boundedRequestTimeout(value) {

package/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Machine Bridge Browser",
-  "version": "1.1.5",
+  "version": "1.2.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": "1.1.5"
+  "version_name": "1.2.0"
 }

package/browser-extension/page-automation.js

@@ -703,7 +703,7 @@
   }
 
   function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return new Promise((resolve) => { setTimeout(resolve, ms); });
   }
 
   Object.defineProperty(globalThis, "__machineBridgePageAutomation", {

package/docs/ARCHITECTURE.md

@@ -25,27 +25,22 @@ A canonical workspace receives an independent profile, Worker name, secret set,
 
 ### Local runtime
 
-`LocalRuntime` is the transport-independent local tool engine. It owns:
-
-- canonical path resolution and display-path privacy;
-- file, text search, image, patch, and Git operations;
-- direct and shell process execution;
-- process-session buffers and stdin lifecycle;
-- layered fixed runtime diagnostics;
-- local resource aliases and detached managed-job coordination;
-- session/bootstrap instruction discovery, live capability ranking, and registered-command execution coordination;
-- structured local application and existing-profile browser automation coordination;
-- mutation serialization;
-- child-process tracking and cancellation;
-- output, traversal, concurrency, and time limits.
-
-`RelayConnection` owns remote WebSocket transport, authenticated `hello_ack` readiness, heartbeat liveness, reconnect backoff, and outage logging. Stdio mode invokes `LocalRuntime` directly without that adapter.
+`LocalRuntime` is the transport-independent local tool orchestrator. It owns the shared authorization/execution pipeline, manager construction, mutation serialization, cancellation, and the narrow delegation surface used by stdio and relay transports. Domain behavior remains in focused services:
+
+- `workspace-file-service.mjs` and `git-service.mjs` own canonical filesystem/Git operations;
+- `process-execution.mjs`, `process-sessions.mjs`, and `process-tracker.mjs` own child-process authority and lifecycle;
+- `runtime-reporting.mjs` builds privacy-aware runtime and project snapshots;
+- `runtime-diagnostics.mjs` owns fixed local probes and their stable interpretation;
+- `runtime-capabilities.mjs` composes agent, application, and browser capability results;
+- managed jobs, local resources, application automation, and browser automation remain separate managers.
+
+Architecture tests cap the orchestration module and each extracted service independently and reject a return of low-level process, patch, diagnostic, or capability-scoring logic to `LocalRuntime`. `RelayConnection` owns remote WebSocket transport, authenticated `hello_ack` readiness, heartbeat liveness, reconnect backoff, and outage logging. Stdio mode invokes `LocalRuntime` directly without that adapter.
 
 `daemon-process.mjs` owns workspace-daemon inspection and takeover. It distinguishes platform service state from the lock-owning Node process, validates PID and process-start identity, canonicalizes workspace/state paths before comparison, parses bounded process command lines without executing them, and sends `SIGTERM` only to a verified same-workspace `--daemon-only` process. POSIX daemons may ignore that signal and reach the bounded non-escalating timeout; Node's Windows signal mapping terminates the verified process directly. CLI orchestration never treats a missing launchd/systemd job as proof that the process exited.
 
 ### Agent context and capability resolver
 
-`AgentContextManager` discovers the nearest Git/workspace scope, applies the user configuration and hierarchical `.machine-bridge/agent.json` files, selects built-in/user/root-to-target instructions, discovers bounded filesystem skills, and resolves registered commands. `project-package.mjs` owns no-follow package metadata parsing, package-manager selection (including fail-closed conflicting-lockfile handling), script-name normalization, bounded workflow-intent aliases, and automatic `package.*` command construction so instruction rendering and command execution do not duplicate package parsing. `default-instructions.mjs` supplies a versioned in-package working-agreement block and derives a small virtual project-context block from root filenames and bounded metadata. It reads package script names but not bodies, does not inspect dependency values or source contents, executes nothing, and writes no user/repository files. A global `model_instructions_file` is a separate user-designated session source and cannot be overridden by a project.
+`AgentContextManager` discovers the nearest Git/workspace scope, applies the user configuration and hierarchical `.machine-bridge/agent.json` files, selects built-in/user/root-to-target instructions, discovers bounded filesystem skills, and resolves registered commands. `agent-contract.mjs` is the strict checked-JavaScript boundary for configuration shape, registered-command normalization, encoded-size limits, and configured-path containment; the manager does not maintain a second parser. `project-package.mjs` owns no-follow package metadata parsing, package-manager selection (including fail-closed conflicting-lockfile handling), script-name normalization, bounded workflow-intent aliases, and automatic `package.*` command construction so instruction rendering and command execution do not duplicate package parsing. `default-instructions.mjs` supplies a versioned in-package working-agreement block and derives a small virtual project-context block from root filenames and bounded metadata. It reads package script names but not bodies, does not inspect dependency values or source contents, executes nothing, and writes no user/repository files. A global `model_instructions_file` is a separate user-designated session source and cannot be overridden by a project.
 
 `session_bootstrap` is requested during both stdio and remote MCP initialization. The Worker delegates this read to the connected daemon with a short bounded timeout; failure falls back to static server instructions rather than blocking initialization indefinitely. `resolve_task_capabilities` performs a fresh deterministic scan, rebuilds automatic project facts, and ranks skill/command metadata for the current task. Application and browser capability metadata is added by `LocalRuntime`; installed application inventory uses a short bounded cache. `CapabilityObserver` records only counts, timestamps, source flags, selected metadata, match counts, recommended tool names, and a runtime-keyed task fingerprint so operators can verify routing without creating a task-content log.
 
@@ -59,7 +54,7 @@ See [Session instructions, skills, commands, and capability discovery](AGENT_CON
 
 ### Browser extension and machine broker
 
-`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.
+`BrowserBridgeManager` owns only connection orchestration for the loopback HTTP/WebSocket broker, owner/client failover, routed requests, cancellation, and extension replacement. `browser-operation-service.mjs` owns MCP-facing browser argument normalization, resource-backed values/uploads, form semantics, screenshot conversion, and status presentation. Extension version/capability parsing lives in the strict checked `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.
 
@@ -108,6 +103,8 @@ All requests for a deployed Worker route to one named Durable Object. It owns:
 - policy/tool metadata attached to the active socket;
 - a bounded in-memory map of pending daemon calls.
 
+`BridgeRoom` owns Durable Object routing, MCP dispatch, daemon WebSocket lifecycle, and pending relay calls. `OAuthController` owns OAuth-store pruning, registration throttling, authorization pages/submission, account-admin routing, token exchange, access-token verification, and the serialization queue for OAuth mutations. Worker-internal TypeScript imports use explicit `.ts` specifiers and JSON import attributes, so the same modules are directly executable under the pinned Node runtime for focused state-machine tests as well as bundled by Wrangler.
+
 The Worker verifies OAuth, validates MCP envelopes and optional protocol headers, converts `tools/call` into WebSocket messages, correlates cancellation by access-token hash and JSON-RPC ID, and formats text/structured/image results. It has no local filesystem or process API.
 
 The primary OAuth store separates client registrations and named accounts from authorization codes and access-token records. A separate Durable Object key owns refresh-token records so refresh support can be added without rewriting the live primary-store schema. A `client_id` identifies an MCP application and redirect URIs; account records identify the authorized human or service identity. Codes, access tokens, and refresh tokens bind client ID, account ID, account version, role, scope, resource, token version, and expiration. Only hashes of bearer tokens are persisted, and every public-client refresh invalidates the presented refresh token while returning a replacement. The Worker intersects the role with the active daemon policy before advertising or relaying tools, and the local runtime validates the relayed role again. One bridge-specific Durable Object and one local runtime remain the normal topology for a workspace/trust domain; see [MULTI_ACCOUNT.md](MULTI_ACCOUNT.md).

package/docs/AUDIT.md

@@ -1,5 +1,19 @@
 # Engineering and security audit
 
+## 2026-07-16 version 1.2 trustworthy-evolution audit
+
+The review began from clean released commit `58d54c21a0ac37f8e5f82a6f895738508efad0c6` (`v1.1.5`). The complete local gate, exact-commit Linux/macOS/Windows CI, CodeQL, Governance, and OpenSSF Scorecard were green; dependency audits reported zero vulnerabilities; and the GitHub Release asset, npm registry tarball, and a fresh local pack were byte-identical. That evidence ruled out an immediate release-integrity incident but did not answer whether the project could continue evolving safely: the main Worker, runtime, Agent-context, and browser-broker modules were all above ninety-seven percent of their own architecture limits, while high-authority local JavaScript had almost no static shape checking and several critical Worker modules had no branch floor.
+
+The causal correction is responsibility extraction rather than a line-count shuffle. `OAuthController` now owns OAuth persistence, pruning, registration throttling, authorization UI/submission, account administration, exchange delegation, token verification, and its mutation queue. `LocalRuntime` delegates privacy-aware reporting, fixed diagnostics, and capability composition to dedicated services. Agent configuration/path validation and browser MCP action semantics moved into their own domain modules, leaving discovery and loopback transport with one reason to change. Architecture tests lower the old composition-root limits and independently cap every extracted module; source guards reject a return of OAuth, diagnostics, capability scoring, browser operation validation, low-level process, or patch responsibilities to the orchestrators.
+
+Static assurance now follows authority rather than file extension. A focused strict checked-JavaScript gate covers local policy, call registration/cancellation, Agent configuration and path containment, browser handshake parsing, capability ranking, monotonic deadlines, basic normalization, and bounded metadata reads. Worker imports use explicit `.ts` specifiers and JSON attributes, allowing the same OAuth state machine to run directly under the pinned Node 26 baseline and under Wrangler. The new test reproduces registration throttling, invalid and valid authorization, HMAC source identity, resource-bound token authority, token expiry deletion, schema mismatch, and missing identity configuration. No `@ts-ignore`, implicit-`any` waiver, alternative TypeScript runtime, or duplicate test-only implementation was introduced.
+
+Risk-directed coverage now includes the extracted Agent, browser, and runtime services. The runtime composition root rose to roughly eighty-one percent function and sixty-five percent branch coverage; reporting, diagnostics, and capability composition have independent thresholds; Worker pending calls and policy gained branch floors. A new lint pass found thirty-eight concise Promise executors that accidentally returned timer/listener handles and one cleanup throw inside `finally`; all were corrected rather than excepted. The first remote CodeQL pass then found four extraction leftovers; they were removed and `no-unused-vars` became a local failing gate so this class no longer waits for remote analysis. The cleanup test now records a final best-effort deletion failure without replacing the primary browser-test result.
+
+Upgrade safety is intentionally current-only. Version 1.2 retains local state schema 6 and policy revision 5, and does not alter OAuth record formats, resource registrations, managed-job envelopes, Worker identity, or browser pairing. A normal 1.1.5 installation therefore upgrades in place; unsupported older schemas remain rejected rather than guessed. The new upgrade document defines the daemon/Worker/extension as one rollback unit and prohibits hand-editing version fields. No npm publication, Worker deployment, credential rotation, global installation, or live service replacement was performed during source work.
+
+The remaining controls cannot be completed honestly by repository automation alone. npm trusted publishing needs the package owner's external OIDC trust configuration and protected publication environment. Independent review needs a second active human maintainer. Governance now defines admission, succession, and the exact protected paths that must require non-author and last-push approval once that person exists; the existing expiring Scorecard exceptions remain visible until those external conditions change.
+
 ## 2026-07-16 Windows autostart, restart, and workspace-identity incident
 
 The reported transcript combined two distinct questions that the previous Worker fix did not answer. The first ordinary `machine-mcp` invocation addressed the remembered workspace, while the next command explicitly supplied another `--workspace`. Machine Bridge intentionally assigns one profile and one Worker to each canonical workspace, so that sequence is not by itself evidence that a retry duplicated the same resource. The existing deployment code did persist successful Wrangler evidence before health verification, but its regression reused one in-memory object. The new test performs an actual atomic state write, reconstructs state from disk as a new process would, repeats an ambiguous timeout, and proves Wrangler deploy is still called exactly once. Documentation now requires comparing canonical workspace, profile, Worker name, and URL before deleting any apparent duplicate.

package/docs/ENGINEERING.md

@@ -130,8 +130,8 @@ The required matrix includes:
 - Linux, macOS, and Windows on the pinned Node/npm baseline;
 - current-tree and reachable-history privacy gates, release-impact enforcement, and exact-commit CI/CodeQL/Governance/Scorecard release gating;
 - package-manifest and sensitive-artifact inspection;
-- generated type checks and recursively discovered JavaScript/shell syntax checks;
-- static undefined-identifier/redeclaration checks over all production JavaScript, tests, scripts, and browser-extension code;
+- generated Worker type checks plus strict opt-in checked-JavaScript contracts for high-risk local policy, lifecycle, configuration, path, protocol, and timing boundaries;
+- recursively discovered JavaScript/shell syntax checks and static correctness lint over all production JavaScript, tests, scripts, and browser-extension code;
 - a real packed-tarball isolated global installation whose zero-argument CLI startup initializes state and reaches a controlled external Worker-deployment boundary; `--version` or import-only smoke tests are insufficient release evidence;
 - concurrent exclusive-lock/atomic-replacement tests, PID-reuse/age tests, and fail-closed service-lifecycle tests;
 - real process-tree timeout/cancellation tests with descendants that ignore graceful termination;
@@ -151,6 +151,9 @@ Cross-platform tests must not depend on shell syntax, case-sensitive Windows pat
 - LOGGING defines operator-facing event semantics.
 - OPERATIONS contains diagnosis and recovery procedures.
 - TESTING records executable coverage and regression expectations.
+- UPGRADING defines the only supported state/protocol transition and rollback unit.
+- SUPPORT defines supported runtimes, diagnostic requirements, and public/private reporting boundaries.
+- GOVERNANCE defines accountable ownership, succession, review, and release authority.
 - CHANGELOG records externally relevant changes, including documentation and workflow changes.
 - PROJECT_STANDARDS defines collaboration, contract, testing, supply-chain, review, and exception policy.
 - TOOL_REFERENCE is generated from the shared MCP tool catalog and must never be maintained by hand.

package/docs/PROJECT_STANDARDS.md

@@ -94,6 +94,7 @@ Tests follow risk rather than a repository-wide aggregate percentage:
 - Protocol changes include producer-consumer contract tests and malformed-input tests.
 - Supported operating systems run the required suite in CI.
 - Critical modules have explicit function and branch baselines. Thresholds may rise after better tests or extraction; lowering one requires an audit note explaining why the old measurement was misleading.
+- High-risk JavaScript contract modules opt into strict TypeScript checking through `tsconfig.local.json`; implicit `any`, `@ts-ignore`, and untyped duplicate protocol/configuration shapes are not acceptable substitutes for a defined boundary.
 
 An 80% aggregate coverage target is not a repository requirement: it can hide untested critical branches behind trivial files. New or materially changed pure business modules should normally achieve at least 80% function coverage and meaningful branch coverage, but risk-specific tests remain the acceptance criterion.
 
@@ -124,7 +125,7 @@ Flaky tests are defects. A retry may diagnose environmental instability but may
 ## 8. Documentation and comments
 
 - README covers supported setup, operation, major capabilities, limitations, and risk.
-- Architecture, security, testing, operations, logging, policy, and release documents each own their designated concern; avoid repeating whole procedures across files.
+- Architecture, security, testing, operations, logging, policy, upgrade, support, governance, and release documents each own their designated concern; avoid repeating whole procedures across files.
 - Documentation claims a guarantee only when code, configuration, or a test enforces it.
 - Public behavior changes update the changelog and relevant user documentation in the same pull request.
 - Comments explain non-obvious **why**, invariants, external constraints, and safety ordering. They do not narrate self-explanatory syntax.
@@ -136,7 +137,7 @@ Flaky tests are defects. A retry may diagnose environmental instability but may
 
 Review examines correctness, causal completeness, security/privacy boundaries, compatibility, failure paths, observability, test evidence, and maintainability. Style preferences do not override a simpler correct design without a documented project rule.
 
-This repository currently has one human maintainer. Requiring one independent approval would deadlock maintenance and therefore is not enabled. The first governance priority when another active maintainer is added is to require one non-author approval for security-sensitive, release, policy, Worker, browser, and execution changes.
+This repository currently has one human maintainer. Requiring one independent approval would deadlock maintenance and therefore is not enabled. [GOVERNANCE.md](../GOVERNANCE.md) defines admission, succession, release authority, and the first mandatory control after another active maintainer is added: one non-author approval plus last-push approval for security-sensitive, release, policy, Worker, browser, state, and execution changes.
 
 ## 10. Exceptions and evolution
 

package/docs/TESTING.md

@@ -75,9 +75,11 @@ For deterministic release validation, perform an isolated-profile smoke test wit
 
 ## 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.
+`npm run coverage:test` runs selected in-process and lightweight entrypoint fixtures under V8 coverage and enforces per-module function and branch baselines. The measured set now includes policy, typed errors, call registration, execution middleware, lifecycle/observability, logging, Runtime/CLI orchestration, Agent configuration, capability ranking, browser protocol/operation boundaries, runtime reporting/diagnostics/capability composition, and Worker pending/policy/error modules. The full stdio and workerd OAuth/MCP integration still runs separately; a focused direct Node test covers `OAuthController` registration throttling, authorization failure/success, resource-bound access tokens, expiry pruning, invalid-state rejection, and identity-key failure.
 
-The current CLI entrypoint remains the weakest covered orchestration surface; its baseline is therefore reported and locked independently, while extracted `cli-options`, `cli-policy`, `records`, `state-inventory`, `network-proxy`, `worker-health`, and `worker-deployment` modules carry substantially higher thresholds. The Worker convergence extraction and expanded command fixtures raised the CLI function floor from 40% to 45% and branch floor from 10% to 20%; a refactor may raise a threshold, but must not lower one merely to make CI green without an explicit audit explanation.
+The gate deliberately reports each module rather than one aggregate percentage. New extracted pure/domain modules carry explicit branch floors, while the broad CLI entrypoint remains reported and locked independently. Worker pending calls and policy now have branch minima instead of function-only gates. A refactor may raise a threshold, but must not lower one merely to make CI green without an explicit audit explanation.
+
+`npm run typecheck` combines strict Worker TypeScript with a focused `tsconfig.local.json` gate. High-risk JavaScript contracts opt in with `// @ts-check` and JSDoc types; the gate currently covers policy, call lifecycle, Agent configuration/path resolution, browser handshake parsing, capability ranking, monotonic deadlines, number/record normalization, and bounded metadata reads. `@ts-ignore`, implicit `any`, or unchecked parallel contract shapes are not accepted as migration shortcuts.
 
 ## Additional release checks
 

package/docs/UPGRADING.md

@@ -0,0 +1,30 @@
+# Upgrading
+
+## Supported upgrade contract
+
+Machine Bridge does not retain parallel implementations for obsolete MCP protocol dates, policy revisions, state schemas, lock formats, or browser-extension protocols. The supported path is a direct upgrade from the immediately preceding published package while its state already uses the current schema.
+
+Version 1.2 keeps local state schema version 6 and policy revision 5 unchanged. Existing 1.1.5 workspaces, named accounts, resource registrations, managed-job history, Worker identity, and browser pairing state are reused without conversion. The architecture refactor changes module ownership, not persisted formats or authority.
+
+A state file from an older unsupported schema is rejected rather than guessed or silently rewritten. Upgrade an old installation through the last release that understands its schema, or initialize a new workspace and re-register resources. Do not edit schema numbers by hand.
+
+## Normal upgrade
+
+1. Finish or cancel ordinary interactive process sessions. Accepted managed jobs may continue independently, but inspect them before replacing the daemon.
+2. Install the new package with the pinned npm procedure in [Getting started](GETTING_STARTED.md).
+3. Run `machine-mcp doctor`.
+4. Start `machine-mcp` normally for each workspace. Startup verifies state, stops only a verified same-workspace daemon, converges the Worker deployment, and takes over using the installed version.
+5. Reload the unpacked browser extension. Protocol and packaged-version equality are mandatory; an old extension cannot replace a working compatible connection.
+6. Reconnect MCP clients if they retain stale tool or session metadata.
+
+## Upgrade safety
+
+Before replacing live software, copy the owner-only state directory using operating-system tools that preserve permissions. Do not publish or attach that backup: it contains credentials and private resource metadata.
+
+Machine Bridge never treats an unreadable or foreign-schema state file as empty state. It also records a successful Worker upload before secondary health verification, so a network or proxy failure after deployment does not trigger an uncontrolled repeated write.
+
+## Rollback
+
+Rollback is supported only when the older package understands every persisted schema and protocol already written by the newer package. Version 1.2 does not advance local state or policy schemas, so rollback to 1.1.5 remains structurally possible, but the preferred recovery is to fix forward because the browser extension and deployed Worker must match the running package exactly.
+
+Never roll back by copying only selected state files or changing version fields. Restore one complete verified state backup, package version, Worker build, and browser extension as a single operational unit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "1.1.5",
+  "version": "1.2.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",
@@ -24,11 +24,15 @@
     "scripts",
     "wrangler.jsonc",
     "tsconfig.json",
+    "tsconfig.local.json",
     "README.md",
     "SECURITY.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "docs",
+    "CODE_OF_CONDUCT.md",
+    "SUPPORT.md",
+    "GOVERNANCE.md",
     "LICENSE"
   ],
   "scripts": {
@@ -41,9 +45,9 @@
     "prepack": "npm run version:check && npm run privacy:check && npm run release-impact:check",
     "prepublishOnly": "npm run check && npm run version:check && npm run release:check",
     "worker:types": "node scripts/generate-worker-types.mjs",
-    "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit",
+    "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit && npm run typecheck:local",
     "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 worker-deployment:test && npm run relay:test && npm run secure-file:test && npm run worker-secret-file:test && npm run sarif-security:test && npm run security-properties:test && npm run shell:test && npm run architecture:test && npm run markdown:test && npm run project-metadata:test && npm run numbers:test && npm run records:test && npm run state-inventory:test && npm run commit-message:test && npm run policy:test && npm run account:test && npm run policy-docs:check && npm run tool-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 lint:test && npm run lint && npm run typecheck && npm run syntax && npm run deadline:test && npm run process-lock:test && npm run service-lifecycle:test && npm run service-environment: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 install: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 && npm run oauth-browser: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 worker-deployment:test && npm run relay:test && npm run secure-file:test && npm run worker-secret-file:test && npm run sarif-security:test && npm run security-properties:test && npm run shell:test && npm run architecture:test && npm run markdown:test && npm run project-metadata:test && npm run numbers:test && npm run records:test && npm run state-inventory:test && npm run commit-message:test && npm run policy:test && npm run account:test && npm run worker-oauth-controller:test && npm run policy-docs:check && npm run tool-docs:check && npm run runtime-infrastructure:test && npm run runtime-boundaries: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 lint:test && npm run lint && npm run typecheck && npm run syntax && npm run deadline:test && npm run process-lock:test && npm run service-lifecycle:test && npm run service-environment: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 install: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 && npm run oauth-browser: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",
@@ -109,7 +113,10 @@
     "shell:test": "node tests/shell-test.mjs",
     "deadline:test": "node tests/monotonic-deadline-test.mjs",
     "oauth-browser:test": "node tests/oauth-browser-navigation-test.mjs",
-    "worker-deployment:test": "node tests/worker-deployment-test.mjs"
+    "worker-deployment:test": "node tests/worker-deployment-test.mjs",
+    "typecheck:local": "tsc -p tsconfig.local.json --noEmit",
+    "runtime-boundaries:test": "node tests/runtime-boundaries-test.mjs",
+    "worker-oauth-controller:test": "node tests/worker-oauth-controller-test.mjs"
   },
   "dependencies": {
     "https-proxy-agent": "9.1.0",

package/scripts/coverage-check.mjs

@@ -9,16 +9,23 @@ const coverageDir = mkdtempSync(resolve(tmpdir(), "machine-bridge-coverage-"));
 const tests = [
   "tests/policy-test.mjs",
   "tests/runtime-infrastructure-test.mjs",
+  "tests/runtime-boundaries-test.mjs",
   "tests/worker-runtime-infrastructure-test.mjs",
+  "tests/worker-oauth-controller-test.mjs",
   "tests/logging-structure-test.mjs",
   "tests/runtime-handler-matrix-test.mjs",
   "tests/cli-entrypoint-test.mjs",
   "tests/local-self-test.mjs",
+  "tests/runtime-self-test.mjs",
   "tests/numbers-test.mjs",
   "tests/records-test.mjs",
   "tests/project-metadata-test.mjs",
   "tests/state-inventory-test.mjs",
   "tests/worker-deployment-test.mjs",
+  "tests/agent-context-test.mjs",
+  "tests/capability-ranking-test.mjs",
+  "tests/browser-bridge-test.mjs",
+  "tests/monotonic-deadline-test.mjs",
 ];
 
 try {
@@ -38,27 +45,35 @@ try {
 
   const coverage = collectCoverage(coverageDir);
   const thresholds = {
-    "src/local/policy.mjs": [75, 45],
+    "src/local/policy.mjs": [90, 65],
     "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/call-registry.mjs": [85, 55],
+    "src/local/tool-executor.mjs": [90, 40],
+    "src/local/observability.mjs": [95, 40],
     "src/local/process-tracker.mjs": [65, 35],
     "src/local/log.mjs": [60, 40],
-    "src/local/runtime.mjs": [60, 35],
+    "src/local/runtime.mjs": [75, 55],
     "src/local/cli.mjs": [45, 20],
     "src/local/cli-options.mjs": [65, 35],
     "src/local/cli-policy.mjs": [70, 35],
     "src/local/numbers.mjs": [100, 100],
     "src/local/records.mjs": [100, 100],
-    "src/local/project-metadata.mjs": [85, 55],
+    "src/local/project-metadata.mjs": [95, 55],
     "src/local/state-inventory.mjs": [85, 55],
     "src/local/network-proxy.mjs": [90, 65],
     "src/local/worker-health.mjs": [85, 60],
     "src/local/worker-deployment.mjs": [80, 55],
-    "src/worker/pending-calls.ts": [85, null],
-    "src/worker/policy.ts": [90, null],
-    "src/worker/errors.ts": [100, null],
+    "src/local/agent-contract.mjs": [95, 40],
+    "src/local/capability-ranking.mjs": [95, 70],
+    "src/local/browser-extension-protocol.mjs": [95, 35],
+    "src/local/browser-operation-service.mjs": [80, 50],
+    "src/local/runtime-reporting.mjs": [95, 75],
+    "src/local/runtime-diagnostics.mjs": [75, 65],
+    "src/local/runtime-capabilities.mjs": [75, 45],
+    "src/local/monotonic-deadline.mjs": [100, 100],
+    "src/worker/pending-calls.ts": [90, 35],
+    "src/worker/policy.ts": [100, 25],
+    "src/worker/errors.ts": [100, 40],
   };
   const failures = [];
   for (const [file, [minimumFunctions, minimumBlocks]] of Object.entries(thresholds)) {