machine-bridge-mcp 2.0.0 → 3.0.0-beta.11

package/docs/TESTING.md

@@ -23,6 +23,10 @@ The suite includes:
 - one-shot process output preview/continuation, completed-session paging, bounded nonzero-exit details, UTF-8-safe head/tail diagnostics, compact local/Worker MCP text mirrors, and quiet-success/bounded-failure verification-runner behavior;
 - GitHub backlog enforcement that paginates all open issues and pull requests, permits only the current branch PR, and requires standard closing keywords for every open issue before a guarded push;
 - release-impact enforcement requiring a new package version and CHANGELOG section for release-relevant changes;
+- strict dev/beta/rc/stable channel parsing and npm dist-tag enforcement;
+- persistent candidate relay/service handoff ordering and fault cleanup;
+- owner-only local and registry prerelease activation records;
+- npm/GitHub prerelease metadata validation, minimum soak timing, blocking-issue rejection, and stable-promotion content/file-mode identity;
 - release-state diagnostics distinguishing missing local/remote version tags from tags that point to the wrong commit, plus a release-CI gate that rejects missing, pending, failed, pull-request-only, stale, or wrong-commit runs;
 - generated Cloudflare Worker types under ignored `.wrangler/` state and strict TypeScript checking, including unused-local and unused-parameter rejection; packaging rejects generated declarations;
 - Conventional Commit title validation, shared Markdown escaping regression coverage, and generated MCP tool-reference drift detection;
@@ -32,7 +36,7 @@ The suite includes:
 - default working-agreement injection without user files, bounded automatic project metadata, script-body non-disclosure, user-global opt-out, repository opt-out rejection, global `model_instructions_file` injection in stdio/remote initialization, hierarchical precedence, `.agents/skills` and `.codex/skills` compatibility discovery, live project/skill rescanning and fingerprints, automatic task ranking/loading with English inflection normalization, bounded Chinese/English intent aliases, capability-name weighting, and selected-skill instruction loading; automatic `package.*` commands with English/Chinese workflow-intent matching and Windows command-shim execution, explicit command override/removal, direct argv handling, timeout ceilings, runtime-keyed routing-telemetry privacy, and execution-profile denial;
 - concurrent complete-before-visible lock claims, atomic replacement under active readers, malformed-lock grace, snapshot/token-safe reclamation, absolute-age expiry, PID-reuse detection, bounded startup-lock waiting, and wall-clock rollback injection proving duration deadlines remain monotonic;
 - foreground takeover of active and orphaned background daemons with current service-lock metadata, foreground-process protection, bounded final lock-handoff retry, actual-PID exit waiting, POSIX non-escalating timeout behavior, Windows verified-daemon stop semantics, daemon lock mode/version/process-start metadata, launchd service-target semantics, and silent idempotent duplicate service starts; daemon fixture subprocesses intentionally do not inherit V8 coverage because their purpose is ownership timing rather than code measurement;
-- fail-closed service lifecycle ordering for provider-stop, all-workspace daemon-stop, and definition removal, including platform/daemon/removal failure injection and normalized macOS/systemd/Windows results; Windows coverage reproduces an inline `/TR` command above 262 characters, proves the short launcher action remains bounded, verifies least-privilege logon registration, restart/log routing, language-independent `Ready`/`Running` observation, and state-observed stop/removal despite localized nonzero command output;
+- fail-closed service lifecycle ordering for provider-stop, all-workspace daemon-stop, and definition removal, including platform/daemon/removal failure injection and normalized macOS/systemd/Windows results; service-PATH coverage reproduces two nested npm run-script prefixes plus a stale prior candidate runtime and proves the current Node/runtime and inherited user tools remain while npm-private and inactive-runtime entries are removed; Windows coverage reproduces an inline `/TR` command above 262 characters, proves the short launcher action remains bounded, verifies least-privilege logon registration, restart/log routing, language-independent `Ready`/`Running` observation, and state-observed stop/removal despite localized nonzero command output;
 - private service-environment capture/load coverage for exact allowlisting, value bounds and control-character rejection, non-proxy secret exclusion, runtime-value precedence, Windows case-insensitive replacement, explicit empty-value clearing, and preservation across a later environment-free startup;
 - machine-level browser-broker ownership/client proxying, authenticated extension origin/subprotocol, non-cacheable local pairing, pairing-token non-disclosure, resource-backed upload routing, broker result redaction, pre-registered runtime-handshake listeners, bounded socket/HTTP waits, direct loopback health despite hostile environment-proxy settings, stop-during-start generation invalidation, frozen-wall-clock browser deadline coverage, installed-application discovery caching, and name-based task matching;
 - Worker health direct/proxy routing through a real local HTTP CONNECT proxy, `NO_PROXY` bypass, exact `workers.dev` origin/name validation, redirect rejection, body/deadline bounds, error classification, bounded propagation retry, and invalid proxy fail-fast behavior without endpoint or credential disclosure;
@@ -45,20 +49,22 @@ The suite includes:
 - UTF-8 and binary handling;
 - image content formatting;
 - nested Git repository detection and helper suppression;
+- explicit effective-policy versus daemon-ceiling fields in local/remote `project_overview`, reviewer/editor Git metadata through the fixed internal command boundary, and compatibility fallback for older daemon snapshots;
+- fixed internal command execution with validated argv, no shell, isolated HOME/temp/cache, bounded output/deadlines, and ordinary cancellation/process tracking while arbitrary delegated process tools remain sandbox-gated;
 - author-email privacy in `git_log`;
 - isolated command HOME/temp/cache behavior;
 - one-shot timeout, descendant process-group/tree termination including descendants that ignore graceful shutdown after the direct child has already exited, cancellation, and process-session interaction;
 - layered fixed runtime diagnostics for filesystem, direct process, shell, managed-job storage, and resource availability; machine-readable execution guardrails that must keep CPU, memory, and network isolation marked unenforced unless an actual OS boundary is added;
-- local resource CLI registration, permission checks, dynamic reload, state-path redaction, and content non-disclosure;
+- local resource CLI registration, permission checks, dynamic reload, state-path redaction, content non-disclosure, and the extracted runtime-resource boundary for bounded binary/UTF-8 reads plus generation authorization;
 - real Ed25519 and RSA generation, idempotent reuse, public/private correspondence, mode enforcement, incomplete/mismatched/symlink rejection, and private-content non-disclosure;
 - real-machine canonical-full sandbox acceptance for outside-workspace I/O, direct/shell execution, full environment inheritance, SSH prerequisites, temporary authorized-key writing, and detached cleanup without external state changes;
 - deterministic injected atomic-replace failures, sustained transient Windows sharing contention beyond the old retry budget, bounded exponential delay selection, and repeated Windows full-sandbox runs;
 - canonical named-profile repair and full-only tool exposure parity between local and Worker policy filters;
-- managed-job staging/local approval/cancel-before-start, detachment, job-scoped temporary files, resource hash verification/redaction, discard capture, finally execution, descendant-tree escalation, token/snapshot-safe transition locks, runner process identity, spawn-without-PID rejection, asynchronous runner-error observability, plan scrubbing, PID-reuse-safe dead-runner recovery, and rejection of numeric-only runner records;
+- managed-job non-executing staging, rejection of the removed terminal promotion path, cancel-before-start, trusted direct start, detachment, job-scoped temporary files, resource hash verification/redaction, discard capture, finally execution, descendant-tree escalation, token/snapshot-safe transition locks, runner process identity, spawn-without-PID rejection, asynchronous runner-error observability, plan scrubbing, PID-reuse-safe dead-runner recovery, and rejection of numeric-only runner records;
 - daemon/startup locking, successfully-read corrupt-JSON recovery, and explicit propagation/preservation of oversized, symbolic-link, permission, and I/O failures;
 - guarded state-root removal, unsafe state-root/workspace overlap rejection before creation, all-profile lock/daemon scanning, strict current-schema validation, corrupt-JSON isolation, and policy-origin persistence;
 - no filename-based sensitive-file denial under unrestricted policy;
-- log redaction, control-character handling, message/field bounds, suppression of both successful and failed per-tool events outside debug, service warning-level configuration, current-schema reset, and bounded tail trimming;
+- shared local/Worker free-form log redaction, sensitive content under non-sensitive Worker keys, immutable local/Worker structured metadata, control-character handling, message/field bounds, suppression of both successful and failed per-tool events outside debug, service warning-level configuration, JSON-mode parity across event and direct logger methods with timestamp/stream/redaction assertions, current-schema reset, and bounded tail trimming;
 - deterministic relay connection lifecycle coverage for transport construction/error/deadline, pre-handshake `welcome` validation, separate `hello_ack` authentication and `ready_ack` end-to-end readiness, session-bound probe return, pre-ready tool rejection, premature-ready rejection, identity/version mismatch, retryable Worker hello/readiness errors, fatal protocol errors, autonomous outage-reminder backoff, handshake/readiness/heartbeat timeout, brief-outage suppression, sustained-outage escalation, recovery summaries, and supersession;
 - shared no-follow bounded-file reads for normal files, over-limit data, directories, and symbolic links;
 - owner-only directory enforcement rejecting final symlinks, failing closed on POSIX chmod errors, verifying `0700`, and retaining Windows portability; Worker temporary-secret lifecycle coverage for process-start-bound names, valid stale-owner reclamation, ambiguous-owner retention, `0600` mode, deletion failures, and simultaneous deployment/cleanup failures;
@@ -69,11 +75,12 @@ The suite includes:
 - byte-exact UTF-8 DOM-source truncation across emoji and Chinese partial-code-point boundaries, including equality between the reported byte count and the encoded returned source;
 - independently injected service CLI status/install/start/stop/uninstall/remove paths, including provider failure, no selected workspace, no deployed Worker, aliases, and default output/exit adapters;
 - CLI parsing, policy profiles, and client configuration boundaries;
+- installed-package zero-argument startup with an isolated HOME/state/workspace and a service-manager trap, proving the smoke test reaches the controlled Wrangler boundary without querying, stopping, or replacing the operator's machine-global launchd/systemd/Scheduled Task service;
 - live stdio MCP initialization with session instructions, capability resolution, discovery, calls, rich content, sessions, cancellation, managed-job acceptance, and a detached job/finally phase that survives stdio shutdown;
-- P-256 daemon identity generation, signed WebSocket preflight, one-time transactional nonce consumption, challenge transcript binding, wrong-key/tamper/expiry/replay rejection, and prevention of unauthenticated candidate churn;
-- local operation-risk classification and catalog-wide review coverage; authenticated-owner direct execution; account/client-bound compound capability leases for delegated accounts; ordinary workspace automation; external-sensitive path composition; sensitive/persistence writes; symbolic-link ancestor and patch-move destination canonicalization; browser-session/application-control plus data-export composition; process/job continuation; scoped/full approval; cross-process daemon/CLI mutation serialization; expiry/revocation; owner-only persistence; and malformed-record rejection;
-- signed account-administration requests with origin/method/path/body/time/nonce binding, transactional one-time nonce consumption, legacy bearer rejection, nonce replay rejection, and malformed nonce-state fail-closed behavior;
-- live local Worker OAuth registration, the unauthenticated `resource_metadata` challenge, protected-resource and authorization-server discovery, Streamable transport metadata, consent, URL-constructed `303` callbacks including the ChatGPT and hosted Claude redirect URIs with encoded state, PKCE, `offline_access`, form-encoded authorization-code and refresh-token exchanges, fifteen-minute access tokens, refresh-family idle/absolute limits, bounded consumed-token/revoked-family replay state, record-level schema validation, access/refresh rotation, stale refresh replay rejection with whole-family access/refresh revocation, account-version refresh revocation, authorization-code replay rejection, pending-registration throttling that excludes already authorized DCR clients, exact built-in ChatGPT/Grok browser origins, additive custom origins, unrelated-origin preflight rejection, no CORS response sharing for unrelated or opaque origins, opaque-origin authorization-form routing, exact per-request redirect-origin CSP with narrowly scoped Microsoft regional-consent and final Copilot Studio handoff exceptions, accessible credential-error rendering, protocol negotiation, HMAC-bound MCP session issuance, two-session same-id concurrency, sessionless same-id independence, session-scoped cancellation isolation, same-session duplicate rejection, daemon-backed session bootstrap, dynamic tool advertisement, rich content, candidate/probing/ready transitions, invalid readiness-result rejection, incumbent preservation until verified handover, daemon replacement, cancellation, malformed daemon JSON/non-object rejection, duplicate hello rejection, and unknown-message closure. The metadata/refresh contract is the path used by Claude DCR and Copilot Studio Dynamic discovery. The same integration runs an `editor` account against a canonical `full` daemon and proves that `server_info` and remote `project_overview` report effective `edit` authority while retaining the full daemon ceiling only in explicitly scoped fields.
+- P-256 root generation, root-certified ephemeral session issuance, macOS trust-broker build/signature checks, signed WebSocket preflight, one-time transactional nonce consumption, challenge transcript binding, wrong-root/session/tamper/expiry/replay rejection, and prevention of unauthenticated candidate churn;
+- request-scoped effective authority and catalog-wide risk review; non-escalatable reviewer/editor/operator ceilings; authenticated-owner direct execution; control-plane root denial; external and sensitive path composition; persistence-target rejection; symbolic-link ancestor and patch-move canonicalization; owner-only browser/application/data-export and persistent-plan effects; account/client/refresh-family ownership of processes, output sessions, and jobs; delegated sandbox fail-closed behavior; legacy-lease non-consumption; and malformed-record rejection;
+- root-certified ephemeral P-256 account-administration requests with origin/method/path/body/key/time/nonce binding, transactional one-time nonce consumption, removal of the long-lived administration secret, certificate/signature/body tamper rejection, nonce replay rejection, and malformed nonce-state fail-closed behavior;
+- live local Worker OAuth registration, the unauthenticated `resource_metadata` challenge, protected-resource and authorization-server discovery, Streamable transport metadata, consent, URL-constructed `303` callbacks including the ChatGPT and hosted Claude redirect URIs with encoded state, PKCE, `offline_access`, form-encoded authorization-code and refresh-token exchanges, fifteen-minute access tokens, trusted single-account client binding, optional DPoP proof and token-family binding, unsupported critical-header rejection, proof-verification non-consumption, post-authorization replay consumption, invalid-grant cache-exhaustion resistance, independent client revocation, refresh-family idle/absolute limits, bounded consumed-token/revoked-family replay state, record-level schema validation, access/refresh rotation, stale refresh replay rejection with whole-family access/refresh revocation, account-version refresh revocation, authorization-code replay rejection, pending-registration throttling that excludes already authorized DCR clients, exact built-in ChatGPT/Grok browser origins, additive custom origins, unrelated-origin preflight rejection, no CORS response sharing for unrelated or opaque origins, opaque-origin authorization-form routing, exact per-request redirect-origin CSP with narrowly scoped Microsoft regional-consent and final Copilot Studio handoff exceptions, accessible credential-error rendering, protocol negotiation, HMAC-bound MCP session issuance, two-session same-id concurrency, sessionless same-id independence, session-scoped cancellation isolation, same-session duplicate rejection, daemon-backed session bootstrap, dynamic tool advertisement, rich content, candidate/probing/ready transitions, invalid readiness-result rejection, incumbent preservation until verified handover, daemon replacement, cancellation, malformed daemon JSON/non-object rejection, duplicate hello rejection, and unknown-message closure. The metadata/refresh contract is the path used by Claude DCR and Copilot Studio Dynamic discovery. The same integration runs an `editor` account against a canonical `full` daemon and proves that `server_info` and remote `project_overview` report effective `edit` authority while retaining the full daemon ceiling only in explicitly scoped fields.
 - local runtime proof that one blocked tool handler does not serialize an independent handler, plus relay fault injection proving an undeliverable terminal result interrupts the ambiguous socket and enters reconnect backoff.
 - a real headless-Chrome OAuth navigation regression with four cases: `form-action 'self'` blocks the first cross-origin callback, allowing only the registered callback blocks the regional redirect, allowing the registered and regional callbacks blocks the final Copilot Studio redirect, and the complete policy preserves `code` and `state` through all three cross-origin hops. Linux CI fails if Chrome is unavailable; other environments skip only this browser executable check while retaining the Worker CSP assertions.
 
@@ -90,6 +97,11 @@ 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.
 
 
+- relay outage diagnostics and recovery: application-proxy versus OS-network scope, timestamped close/outage/recovery fields, fifteen-second maximum reconnect delay, heartbeat timeout, same-instance call continuation, Worker pong/welcome send failure, and `diagnose_runtime` relay history;
+- recoverable managed-job terminal commits under injected result/status/delete/confirmation failures, result-only terminal reconstruction, private runtime/plan scrubbing, 24-hour staged-plan expiry, and minimal/full runner-environment inheritance;
+- cross-process security-audit serialization, continuous hash-chain sequence, uninstall blocking for audit/authorization/job transition/recovery locks, workspace recovery-envelope validation, and symlink/multiple-hard-link rejection at owner state and operational logs;
+- browser fixed identity, role-separated credentials, legacy migration, socket replacement/reconnect/timer cleanup, duplicate request rejection, response-delivery failure, and read-only broker load projection;
+
 ## Critical-module coverage gate
 
 `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 includes policy, typed errors, call registration, execution middleware, lifecycle/observability, logging, Runtime/CLI orchestration, state persistence, relay lifecycle, managed-job lifecycle/runner/storage/projection, browser broker/direct-request/runtime-client routing and loopback upgrade handling, the independently injected service CLI adapter, Agent configuration/projection/skill discovery and bounded text reads, capability ranking, runtime path redaction, browser protocol/operation boundaries, runtime reporting/diagnostics/capability composition, and Worker OAuth state/authorization-page/pending/policy/error/JSON-RPC/WebSocket protocol modules. The full stdio and workerd OAuth/MCP integration still runs separately.
@@ -134,7 +146,7 @@ Run `npm run privacy:check` before committing and before packaging. Run and revi
 
 ## Package manifest
 
-`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts, credential-like file classes, and generated Worker type declarations, validates every packaged mode as `0644` or `0755`, and verifies that required runtime, script, browser-extension, privacy, governance, and release files are present. `npm run install:test` requires npm 12, installs the real tarball from a package-free directory into an isolated global prefix with the documented options, verifies the packaged npm engine requirement, rejects blocked-script warnings, confirms optional `fsevents` is absent, verifies `--version`, then runs the installed CLI with zero arguments from an isolated workspace/state root. A fake Wrangler JavaScript entrypoint terminates at a controlled deployment boundary, so the probe exercises startup without mutating a live account. Package testing is full-plan-only; installation smoke runs in the Ubuntu full plan, the macOS/Windows platform plan, and package audit.
+`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts, credential-like file classes, and generated Worker type declarations, validates every packaged mode as `0644` or `0755`, and verifies that required runtime, script, browser-extension, privacy, governance, and release files are present. Exact runtime install-script approvals are version-bound, so a Wrangler/workerd refresh must also update the reviewed allowlist and pass a clean npm install without blocked-script warnings. `npm run install:test` requires npm 12, installs the real tarball from a package-free directory into an isolated global prefix with the documented options, verifies the packaged npm engine requirement, rejects blocked-script warnings, confirms optional `fsevents` is absent, verifies `--version`, then runs the installed CLI with zero arguments from an isolated workspace/state root. A fake Wrangler JavaScript entrypoint terminates at a controlled deployment boundary, so the probe exercises startup without mutating a live account. Package testing is full-plan-only; installation smoke runs in the Ubuntu full plan, the macOS/Windows platform plan, and package audit.
 
 `npm run lint` uses ESLint as a semantic JavaScript correctness gate rather than a style formatter. It covers the Node CLI/runtime, repository scripts, tests, and packaged browser extension and rejects undefined identifiers in function bodies that `node --check` cannot detect. A dedicated lint-gate self-test proves that both Node and browser configurations reject a synthetic undefined binding while accepting the service-worker `importScripts` global. A focused `shell:test` requires Wrangler to run through the current Node executable and its package JavaScript entrypoint rather than a `.cmd` or shell shim. Architecture tests require `shell:test`, `lint:test`, `lint`, and `install:test` to remain in the complete check pipeline and reject non-exact direct dependency ranges.
 

package/docs/THREAT_MODEL.md

@@ -1,142 +1,213 @@
 # Threat model
 
-This document defines the security claims Machine Bridge is designed to make and the claims it explicitly does not make. It complements [SECURITY.md](../SECURITY.md) and the implementation detail in [ARCHITECTURE.md](ARCHITECTURE.md).
+This document defines the security claims Machine Bridge is designed to make and the claims it explicitly does not make. It complements [SECURITY.md](../SECURITY.md), [LOCAL_AUTHORIZATION.md](LOCAL_AUTHORIZATION.md), and [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## Scope
 
-Machine Bridge combines a remote OAuth relay, a high-authority local runtime, optional local stdio transport, persistent managed jobs, and a browser extension. The primary security objective is to ensure that only explicitly authorized, policy-permitted operations cross those boundaries, with bounded inputs, fail-closed state transitions, and minimal sensitive observability.
+Machine Bridge combines:
 
-The local runtime executes as the current OS user. Policy profiles restrict Machine Bridge behavior; they do not replace kernel, account, VM, container, browser-profile, or endpoint-security isolation.
+- a public OAuth and MCP endpoint on a Cloudflare Worker;
+- an authenticated relay to a high-authority local daemon;
+- optional local stdio transport;
+- filesystem, Git, process, browser, and application automation;
+- persistent managed jobs and registered local resources;
+- a browser extension operating in an existing user profile.
+
+The local runtime executes as the current OS user. Application policies restrict Machine Bridge behavior, but they do not replace kernel, account, VM, container, browser-profile, or endpoint-security isolation.
 
 ## Assets
 
-The main protected assets are:
+Protected assets include:
 
-- workspace and local-user-accessible files;
-- process execution authority and inherited environment values;
-- daemon device private key, account-administration HMAC key, account password verifiers, OAuth authorization codes, access tokens, refresh tokens, and local capability leases;
-- Worker and Durable Object routing state;
-- owner-only profile, lock, resource, service, and managed-job state;
-- registered local resource contents and paths;
-- browser pairing token, browser cookies, authenticated sessions, tabs, page content, and file-upload authority;
-- release candidate hashes, observed-verification acceptance records, package contents, and source-release integrity;
-- logs and diagnostics that could reveal paths, credentials, arguments, results, or user content.
+- workspace files and other files reachable by the local OS user;
+- process execution authority, process sessions, retained output, and inherited environment values;
+- the device root, root-certified ephemeral session keys, OAuth account password verifiers, authorization codes, access tokens, refresh-token families, DPoP bindings, and trusted-client records;
+- Machine Bridge state, locks, service metadata, native broker files, audit-chain state, registered-resource metadata, and managed-job plans/output;
+- browser pairing state, cookies, authenticated sessions, tabs, page content, form values, screenshots, and upload authority;
+- Worker and Durable Object routing, nonce, account, client, token, and pending-call state;
+- release candidate hashes, package contents, acceptance records, and source-release integrity;
+- logs and diagnostics that could reveal paths, credentials, arguments, output, or user content.
 
 ## Trust boundaries
 
 ### Hosted client to Worker
 
-The hosted client and its prompts, tools, extensions, and retrieved content are not automatically trusted. The Worker must validate OAuth state, PKCE, redirect and resource binding, account role/version, token expiry/rotation, MCP session state, request shape, body bounds, and allowed tool exposure.
+The hosted MCP client, its prompts, tools, extensions, and retrieved content are not automatically trusted. The Worker validates:
+
+- OAuth state, PKCE, redirect URI, resource binding, and request size;
+- account status, account version, account role, trusted client binding, token expiry, and refresh-family state;
+- DPoP proof method, target URL, timestamp, unique identifier, access-token hash, and key thumbprint when DPoP is used;
+- MCP session state, protocol version, method shape, request IDs, cancellation, and allowed tool exposure.
+
+A client registration is not authority. Authority begins only after successful account authorization binds the client to one account and role version.
 
 ### Worker to local daemon
 
-The Worker is a relay and authorization layer, not a source of local authority. The daemon accepts only a version-compatible relay that proves possession of the enrolled P-256 device key in both a signed upgrade preflight and a Worker challenge. End-to-end readiness requires a local probe result through the active session. Every remote tool call carries bounded account and OAuth-client identity that is rechecked locally, followed by effect-level local transaction authorization.
+The Worker is a relay and authorization layer, not the source of local OS authority.
+
+The daemon connection requires:
+
+1. a root-signed ephemeral device-session certificate;
+2. a signed, nonce-bound WebSocket preflight using that session key;
+3. a fresh Worker challenge bound to the daemon instance;
+4. version compatibility;
+5. an end-to-end readiness probe delivered through the same result path as real calls.
+
+A replacement candidate does not displace a healthy daemon until those checks complete.
+
+Each remote tool call carries account ID, account version, OAuth client ID, refresh-family ID, and role. The local runtime recomputes effective authority and applies object ownership and operation classification before dispatch.
 
 ### MCP host to local stdio process
 
-A local MCP host can invoke every tool allowed by the selected daemon policy. The host, model output, repository instructions, and retrieved content may be malicious or prompt-injected. A permissive policy therefore grants meaningful local-user authority.
+Stdio is a local-owner transport. It does not use remote OAuth accounts or the relay device root. The local MCP host can invoke every tool allowed by the selected local policy.
+
+The host, model output, repository instructions, and retrieved content may be malicious or prompt-injected. A permissive local policy therefore grants meaningful local-user authority.
 
 ### Local runtime to operating system
 
-The runtime relies on the OS account, filesystem permissions, macOS TCC/SIP, Windows ACLs, container/VM boundaries, and endpoint controls. Canonical workspace checks prevent path escape only when unrestricted paths are disabled. They do not protect against a malicious process already running with the same OS-user authority.
+The runtime relies on OS-user identity, filesystem permissions, process controls, macOS TCC/SIP, Windows ACLs, endpoint controls, and any VM/container boundary.
+
+For delegated process execution, Machine Bridge requires a behaviorally verified OS sandbox. If the negative boundary cannot be demonstrated, delegated execution fails closed. Owner execution is not sandboxed by Machine Bridge. Fixed implementation-owned Git metadata probes are not caller-selected process authority: they use code-constructed argv, no shell, an isolated minimal environment, bounded deadlines/output, and ordinary cancellation/process tracking.
 
 ### Local runtime to browser extension
 
-The broker is loopback-only and pairing-token protected. The extension origin, protocol version, build version, capabilities, and handshake state are validated. The extension still runs inside a real browser profile and can reach the tabs, sessions, and origins granted by browser permissions.
+The broker is loopback-only and pairing-token protected. Extension origin, protocol/build version, capabilities, owner/client route, and handshake state are validated.
+
+The extension still operates inside a real browser profile. It can reach tabs, authenticated sessions, and origins granted by browser permissions. Only the `owner` role may use browser-session control or export local data into it.
 
 ### Local runtime to persistent state
 
-State paths, locks, plans, resources, and service definitions are security-sensitive. Reads are bounded and symlink-aware; writes use owner-only modes where supported and atomic replacement; locks bind tokens to process identity and start time; destructive removal validates ownership and expected layout.
+State paths, roots, locks, plans, resources, native broker files, and service definitions are security-sensitive.
+
+Machine Bridge uses bounded reads, canonical path resolution, owner-only modes where supported, atomic replacement, process-identity locks, schema validation, and explicit lifecycle transitions. Generic path-based tools cannot target Machine Bridge control-plane roots, even under `owner/full`. An authorized owner shell remains equivalent to same-user code execution and is outside that path boundary.
+
+### Device root to ephemeral session
+
+The default root is portable owner-only P-256 material, including on macOS, and is therefore readable by a determined same-user process. A non-exportable Secure Enclave root is available only through an explicitly configured app-like broker with provisioning-profile-validated Keychain access, a strict Apple code signature, stable Team ID, canonical non-symlink path with no group/other write access, and a successful real key probe. Either root signs one bounded ephemeral session certificate at daemon startup. WebSocket reconnect and account-administration requests use the in-memory session key, not the root.
+
+The portable provider stores an exportable private JWK in owner-only state and therefore provides weaker theft resistance. `server_info` reports the provider and exportability.
+
+Broker binding detects path, identifier, Team ID, signature, and capability drift. It does not protect against a malicious replacement signed by the same trusted Apple team and identifier. Production broker installations should therefore be root-owned or otherwise non-writable by the daemon user, with signing-key protection and update governance treated as external trust dependencies.
 
 ### Maintainer to release infrastructure
 
-Repository checks reduce accidental or malicious package drift, but source hosting, npm ownership, protected environments, maintainer accounts, and human review remain external trust dependencies. Repository automation cannot manufacture independent review or claim live candidate success without observing the explicitly owner-authorized candidate. It may record acceptance after that observed verification.
+Repository checks reduce package drift and accidental release mistakes. Source hosting, npm ownership, Apple signing identities, protected environments, maintainer accounts, and independent review remain external trust dependencies.
+
+The local signature binds the self-hosted broker bytes used by this installation. Public third-party binary distribution would be a separate trust model and is outside the current package workflow.
 
 ## Attacker models
 
-Machine Bridge considers the following attackers and failure sources:
+Machine Bridge considers:
 
-1. **Malicious or compromised hosted MCP client** attempting unauthorized tools, token replay, OAuth redirect abuse, request smuggling, duplicate IDs, cancellation races, or excessive resource use.
-2. **Malicious local MCP host or model output** attempting to use allowed tools for destructive actions, credential discovery, shell injection, or persistence.
-3. **Malicious repository content** including instructions, package scripts, Git configuration, paths, symlinks, generated metadata, or files designed to influence an agent or execution boundary.
-4. **Malicious webpage or browser content** attempting prompt injection, deceptive selectors, sensitive-field disclosure, unsafe navigation, replay after ambiguous input dispatch, or extension-protocol abuse.
-5. **Local same-user process** attempting to race locks, replace files, impersonate stale processes, read local state, or interfere with loopback services.
-6. **Network attacker or misconfigured proxy** attempting interception, redirect manipulation, credential disclosure, stale deployment evidence, or ambiguous timeout outcomes.
-7. **Compromised dependency or build input** attempting package substitution, mutable workflow execution, install-script abuse, release drift, or sensitive artifact inclusion.
-8. **Operational failure** such as abrupt termination, PID reuse, clock rollback, partial writes, disk/permission errors, service-manager races, stale browser builds, or daemon replacement during active calls.
+1. **A malicious or compromised hosted MCP client** attempting unauthorized tools, account switching, token theft/replay, OAuth redirect abuse, request duplication, cancellation races, or resource exhaustion.
+2. **A malicious local MCP host or model output** attempting destructive operations, credential access, shell injection, persistence, or data export through an allowed local-owner policy.
+3. **Malicious repository content** including instructions, package scripts, Git hooks/configuration, symlinks, generated metadata, or files designed to influence an agent or execution boundary.
+4. **Malicious web or browser content** attempting prompt injection, deceptive selectors, sensitive-field disclosure, unsafe navigation, ambiguous input dispatch, or extension-protocol abuse.
+5. **A local same-user process** attempting to read state, race locks, replace files, inspect memory, impersonate stale processes, or interfere with loopback services.
+6. **A network attacker or misconfigured proxy** attempting interception, redirect manipulation, stale deployment evidence, connection truncation, replay, or ambiguous timeout outcomes.
+7. **A compromised dependency or build input** attempting package substitution, install-script abuse, workflow mutation, release drift, or sensitive artifact inclusion.
+8. **Operational faults** including abrupt termination, PID reuse, clock anomalies, partial writes, permission errors, Keychain failures, service-manager races, stale extension builds, and daemon replacement during active calls.
 
 ## Security objectives
 
 The implementation aims to preserve these invariants:
 
-- deny unknown, malformed, stale, duplicated, unauthorized, or over-limit requests;
-- intersect remote account authority with the daemon capability ceiling in both Worker and local runtime;
-- permit authenticated owner automation directly within the daemon ceiling while binding delegated high-impact effects to local account/client-scoped, time-bounded capability leases;
-- keep transport authentication, account/tool authorization, transaction authorization, and OS authority separate;
-- use direct argv execution without shell interpretation unless the explicit shell tool is authorized;
-- canonicalize confined paths and reject symlink-based write escape;
-- bound request bodies, messages, files, output, logs, state, retained results, and concurrency;
-- ensure cancellation, timeout, disconnect, replacement, and shutdown have explicit process ownership and cleanup semantics;
-- prevent a candidate daemon or extension from displacing a healthy incumbent before compatibility/readiness validation;
-- avoid exposing secrets, arguments, results, resource contents, account credentials, or raw local paths in default logs and public metadata;
-- make multi-stage state and file mutations atomic or recoverable without silent partial success;
-- bind managed-job plans and release acceptance to cryptographic content hashes;
-- fail closed when state, ownership, permissions, process identity, or destructive cleanup cannot be verified;
-- keep supply-chain actions pinned, minimally permissioned, reviewed, and separately gated.
+- unknown, malformed, stale, replayed, duplicated, unauthorized, and over-limit input is rejected;
+- remote authority is the intersection of daemon policy and account role, never the union;
+- no approval record, token refresh, or local migration state can elevate a delegated role;
+- OAuth clients are bound to one account/version/role and can be revoked independently;
+- long-lived runtime objects are bound to account, account version, OAuth client, and refresh family;
+- generic path-based remote tools cannot target Machine Bridge control-plane state;
+- sensitive paths, persistence targets, browser/desktop control, data export, and persistent job creation are owner-only;
+- delegated process execution is accepted only when an OS sandbox is behaviorally verified;
+- direct argv execution is used unless the explicit shell tool is authorized;
+- confined paths are canonicalized and symbolic-link write escape is rejected;
+- request bodies, files, messages, output, logs, state, retained results, and concurrency are bounded;
+- cancellation, timeout, disconnect, replacement, and shutdown have explicit process ownership and cleanup semantics;
+- candidate daemons and browser extensions cannot replace healthy incumbents before compatibility and readiness verification;
+- default logs and audit records omit secrets, arguments, contents, raw paths, form values, and output;
+- multi-stage mutations are atomic or recoverable and do not silently claim partial success;
+- device-root rotation is two-phase and does not promote an undeployed key;
+- supply-chain actions are pinned, minimally permissioned, reviewed, and separately gated.
 
 ## Non-goals
 
-Machine Bridge does **not** claim to provide:
+Machine Bridge does not claim to provide:
 
-- kernel-enforced sandboxing, CPU/memory quotas, syscall filtering, or network isolation;
-- hard multi-tenant isolation between mutually untrusted users sharing one daemon and OS account;
+- kernel-enforced sandboxing for `owner`, universal syscall filtering, or universal network isolation;
+- OS CPU, memory, disk, or bandwidth quotas;
+- hard multi-tenant isolation between mutually untrusted humans sharing one daemon and OS account;
 - protection from root, an administrator, or a fully compromised same-user account;
-- complete prevention of prompt injection or malicious instructions when an authorized tool can perform the requested action;
+- complete prevention of prompt injection when an authorized tool can perform the requested action;
 - semantic detection of every secret, transformed credential, private document, or dangerous command;
-- proof that the browser extension is loaded in a safe or isolated profile;
-- rollback of a browser or external-system action after an ambiguous dispatch failure;
+- proof that the browser extension is loaded in an isolated profile;
+- rollback of a browser or external-system action after ambiguous dispatch;
+- an atomic rollback transaction spanning Cloudflare Worker deployment and every local service manager;
+- repair or node selection inside a third-party system VPN/TUN;
 - guaranteed cleanup after power loss, kernel failure, filesystem corruption, or an uncooperative external platform;
-- independent human code review while the project has only one active maintainer;
-- npm trusted publishing until the package owner configures external OIDC trust and a protected publication environment.
+- hardware-backed key storage on every operating system;
+- third-party public binary-store identity or independent distributor attestations;
+- independent human review while the project has only one active maintainer.
 
 ## Residual risks
 
-### Canonical `full` profile
+### Owner and canonical `full`
 
-`full` intentionally preserves the complete catalog, unrestricted local-user paths, shell execution, parent environment, browser/application authority, and absolute path output. Version 2.0 treats the authenticated owner role as authorization to use that ceiling without a second terminal prompt. This prioritizes uninterrupted owner automation: compromise of an active owner OAuth client can exercise the complete daemon ceiling. Delegated accounts remain lease-bound for higher-impact effects. A malicious delegated client holding both valid OAuth credentials and an active matching lease can still act destructively within that lease. A temporary `full` lease is therefore an explicit automation window, not a sandbox or an endorsement of untrusted instructions. Use a narrower profile or a separate low-privilege OS boundary for mutually untrusted workloads.
+`full` intentionally preserves the complete catalog, unrestricted local-user paths, shell execution, parent environment, browser/application authority, managed jobs, and absolute path output.
 
-### Application and browser automation
+A compromised active owner client can exercise the daemon ceiling without a second per-operation prompt. The design reduces prompt fatigue and avoids insecure copy-and-retry approval ceremonies, but it makes client trust, token protection, DPoP support, account revocation, and endpoint isolation critical.
 
-UI state can change between inspection and action. Pages can present deceptive content, and an authenticated browser profile may contain high-value sessions. Trusted input and replay controls reduce specific failure modes but do not make arbitrary web content trustworthy.
+Use a narrower profile, separate OS account, container, or VM when prompts, repositories, clients, or workloads are mutually untrusted.
 
-### Package scripts and registered commands
+### Bearer clients
 
-Automatic command discovery does not inject script bodies into prompts, but invoking a package script still executes repository-controlled code. The active policy and human approval remain decisive.
+DPoP is optional for interoperability. A Bearer token can be used by whoever possesses it until expiry or revocation. Short access-token lifetime, rotating refresh families, client binding, account versioning, and replay-family revocation reduce but do not eliminate token theft risk.
 
 ### Same-user interference
 
-Owner-only permissions and process-identity locks reduce accidental and cross-account interference. They cannot reliably defend against a determined process running as the same OS user with equivalent filesystem and process rights.
+Owner-only permissions, optional provisioned Secure Enclave roots, control-plane path denial, process-identity locks, and audit chains reduce several attacks. They cannot prevent a determined same-user process from reading portable credentials, inspecting process memory, changing source before execution, or interfering with local services.
+
+### Delegated sandbox availability
+
+Delegated execution is unavailable when the platform sandbox cannot pass the negative-boundary probe. This is an intentional availability trade-off. Replacing fail-closed behavior with an unverified path blacklist would create false isolation.
+
+### Browser and application automation
+
+UI state can change between inspection and action. Pages can present deceptive content, and authenticated profiles may contain high-value sessions. Protocol checks and trusted-input handling do not make arbitrary web content trustworthy.
+
+### Managed jobs
+
+Managed jobs outlive MCP calls and daemon reconnects. Plans and resources are validated and ownership-bound, but an authorized owner plan can still consume resources or perform destructive work. Finally steps must be idempotent because recovery may retry them.
 
 ### Availability and resource exhaustion
 
-Concurrency, message, output, and timeout limits bound many application-level resources. The daemon does not enforce OS CPU, memory, disk, or network quotas, so an authorized process can still consume host resources.
+Application-level limits bound many requests and outputs. An authorized owner process can still exhaust CPU, memory, disk, network, or external service quotas.
+
+### System VPN/TUN and distributed activation
+
+A system VPN/TUN can remain administratively connected while its selected upstream route, synthetic DNS mapping, or transport path is temporarily unusable. Machine Bridge can detect missing inbound relay traffic, classify the socket close, bound retry delay, and report outage history, but it cannot select or repair a third-party VPN node. `system-network-stack` is therefore not a claim of direct routing.
+
+Candidate activation verifies the foreground candidate before service handoff and records exact package/deployment evidence. It does not provide an atomic transaction spanning Cloudflare deployment and every local service manager. If the Worker changes and the local handoff later fails, the operator may need the recorded previous runtime/deployment evidence to complete rollback. Local cleanup errors are aggregated rather than hidden, but remote rollback is not fabricated.
 
 ### External governance and publication
 
-Code cannot create a second independent reviewer, npm OIDC trust relationship, protected environment, or OpenSSF Best Practices registration. Those controls remain explicit external work rather than simulated repository compliance.
+Code cannot create a second independent reviewer, npm OIDC trust relationship, protected publication environment, Apple Developer identity, or external certification. These remain explicit operational requirements.
 
 ## Validation map
 
-The main regression suites cover:
+Regression suites cover:
 
-- OAuth, refresh-family replay revocation, signed administration requests, account, policy, device-authenticated daemon readiness, relay replacement, and local capability leases;
-- path confinement, atomic writes, state locks, service lifecycle, managed-job recovery, and destructive cleanup;
-- direct process boundaries, shell separation, process-tree termination, timeout, cancellation, and disconnect;
-- browser pairing, version/capability handshake, owner/client broker routing, sensitive-field handling, trusted input, and CSP navigation;
-- privacy redaction, package contents, release impact, interactive candidate acceptance, dependency integrity, CodeQL, and Scorecard findings;
+- account roles, trusted clients, account-version revocation, refresh-family rotation/replay, DPoP proofs, and non-escalatable effective authority;
+- root-certified ephemeral sessions, preflight nonce replay, daemon challenge binding, readiness, reconnect, and candidate replacement;
+- signed account administration, client revocation, and removal of the long-lived administration secret;
+- control-plane path denial, path canonicalization, symlink handling, sensitive/persistence targets, and object ownership;
+- delegated sandbox behavior and fail-closed platform detection;
+- process/session cleanup, managed-job lifecycle and recovery, state locks, atomic persistence, and destructive removal;
+- browser pairing, version/capability handshake, broker routing, sensitive input, and navigation controls;
+- audit-chain integrity, privacy redaction, package contents, installation, release impact, dependency integrity, CodeQL, and Scorecard findings;
 - malformed, over-limit, concurrent, replayed, stale, and fault-injected inputs.
 
-See [TESTING.md](TESTING.md) for the complete test inventory and [AUDIT.md](AUDIT.md) for reviewed failures and residual limitations.
+See [TESTING.md](TESTING.md) for the test inventory and [AUDIT.md](AUDIT.md) for historical findings and residual limitations.
 
 ## Reporting
 

package/docs/TOOL_REFERENCE.md

@@ -2293,9 +2293,9 @@ Generate or reuse an Ed25519 SSH key pair on the local machine and register the
 
 ## `stage_job`
 
-**Stage managed job for local approval**
+**Stage managed job draft**
 
-Validate and persist a managed-job plan without starting any process. Use this when execution tools are unavailable or local operator review is required; launch later with machine-mcp job approve JOB_ID.
+Validate and persist a durable managed-job draft without starting any process. This is a non-executing record only; a trusted owner client starts work with start_job after reviewing or reconstructing the plan.
 
 | Contract field | Value |
 |---|---|