machine-bridge-mcp 0.17.1 → 0.18.0

package/docs/MULTI_ACCOUNT.md

@@ -1,406 +1,123 @@
-# Multi-client, multi-account, and tenancy architecture
+# Multi-account authorization and tenancy
 
-## The actual question
+## What isolation means
 
-The important question is not whether several OAuth clients can obtain tokens. The important question is:
+Machine Bridge remote mode supports several named accounts on one workspace Worker. Each account has an independent password, role, active state, version, OAuth authorization codes, and access tokens. Account changes revoke only that account's outstanding credentials.
 
-> Can independently managed principals share one Machine Bridge deployment without inheriting the same local-machine authority or being able to affect one another?
+This is application-level authorization, not operating-system isolation. All accounts ultimately reach one local daemon running as one OS user. Roles limit which Machine Bridge tools can be listed and invoked; they do not create separate filesystems, browser profiles, process namespaces, keychains, network identities, or kernel security boundaries.
 
-The current release answers **no**. It supports multiple client registrations and multiple access tokens, but it does not model human or service accounts as independent security principals. Anyone who completes authorization with the shared workspace connection password receives the same workspace-level Machine Bridge authority.
+Use separate OS accounts, containers, VMs, state roots, Workers, and workspaces when users are mutually untrusted or require hard isolation.
 
-This distinction must remain explicit because an OAuth `client_id` identifies client software, not the person or service using it.
+## Roles
 
-## Terms
-
-| Term | Meaning in this document |
-|---|---|
-| OAuth client | A registered MCP host/application with redirect URIs and a `client_id` |
-| Principal/account | A human or service identity that may receive authority |
-| Grant | A named, versioned set of capabilities assigned to a principal for one bridge |
-| Bridge | One canonical workspace, local runtime, Worker, Durable Object, policy ceiling, and credential set |
-| Trust domain | Principals that may safely share the same local OS/runtime authority |
-| Tenant | An independently administered trust domain requiring isolation from other tenants |
-
-## Current behavior
-
-| Scenario | Current support | Security meaning |
-|---|---:|---|
-| Several MCP applications or installations connect to one Worker | Yes | Each can register a client and receive separate tokens |
-| Several ChatGPT accounts connect using the same connection password | Technically yes | They receive the same workspace authority; no account isolation |
-| Several active OAuth tokens for one client | Yes | Tokens are distinct but share the same authorization semantics |
-| Per-account roles, capability grants, suspension, or revocation | No | Only workspace-wide policy and token-version revocation exist |
-| Revoke one principal while preserving all others | No | The current emergency mechanism rotates the workspace token version and invalidates all access tokens |
-| Several independent workspaces | Yes | Each canonical workspace has independent state, policy, Worker name, secrets, resources, jobs, and locks |
-| Several mutually untrusted users in one local runtime | No | Process and browser authority remain local-user authority |
-| Multi-user tenancy in one Worker deployment | No | The architecture currently has one shared password, one policy, one active daemon, and one default Durable Object route |
-
-Relevant current implementation:
-
-- `src/worker/oauth-state.ts` stores OAuth clients, authorization codes, and tokens by `client_id` but has no principal or membership record.
-- `src/worker/index.ts` accepts one `MCP_OAUTH_PASSWORD`, validates one `OAUTH_TOKEN_VERSION`, routes the deployment to the Durable Object named `default`, and selects one authenticated daemon.
-- `src/local/state.mjs` creates independent credentials and state per canonical workspace.
-- [ARCHITECTURE.md](ARCHITECTURE.md) explicitly excludes multi-user tenancy in one Worker deployment.
-
-## Safe deployment choices today
-
-### Same owner and same trust domain
-
-Use one bridge and authorize multiple MCP clients. This is appropriate when every client/account is controlled by the same person or team and all may receive the same workspace authority.
-
-Examples:
-
-- the same owner connects ChatGPT web and a local Codex client;
-- one trusted team uses several MCP host installations with an identical role;
-- a user reconnects after replacing a device.
-
-The separate tokens improve protocol hygiene and cancellation correlation, but they are not separate authorization domains.
-
-### Different workspaces with the same owner
-
-Run one bridge identity per canonical workspace. This preserves independent state, credentials, Workers, policies, resources, and jobs. It is preferable to exposing one broad parent directory solely for convenience.
-
-### Different trust domains or mutually untrusted users
-
-Do not share one `full` runtime. Use a separate bridge instance per trust domain, preferably with:
-
-1. a dedicated low-privilege OS account, container, or VM;
-2. a narrow workspace mounted or accessible only to that identity;
-3. an independent state root and Worker credential set;
-4. a separate Worker/deployment identity where administrative separation matters;
-5. a profile no broader than the required workflow.
-
-This external boundary is necessary because direct processes, package scripts, shells, browser sessions, Accessibility actions, credential stores, and network access inherit the local user's authority. A per-account row in Worker storage cannot turn Node.js process execution into an OS sandbox.
-
-## Recommended future architecture
-
-The least coupled design is **principal-aware authorization inside one bridge, while retaining one bridge per workspace/trust domain**. Do not begin by turning the Worker into a global router for every workspace, machine, and tenant.
-
-```text
-MCP host / OAuth client
-        |
-        | authorization code + PKCE
-        v
-Principal authentication
-        |
-        v
-Bridge membership ------> named grant + revision
-        |
-        v
-OAuth code/token bound to principal + grant + resource
-        |
-        v
-Worker authorization gate
-        |
-        | bounded auth context + tool call
-        v
-Local daemon authorization gate
-        |
-        v
-Workspace / process / browser operation
-```
-
-The design has five distinct concepts:
-
-1. **Client registration** identifies the MCP application and its redirect URIs.
-2. **Principal authentication** establishes the human or service identity.
-3. **Membership** says that a principal may access one bridge.
-4. **Grant** defines the exact capabilities and constraints available to that membership.
-5. **OAuth tokens** carry a revocable reference to the principal, membership, grant revision, and protected resource.
-
-Keeping these concepts separate prevents `client_id`, email address, connection password, and policy profile from becoming overloaded pseudo-identities.
-
-## Data model
-
-A minimal Worker-side model can remain inside the existing per-bridge Durable Object:
-
-```text
-principals
-  principal_id
-  display_label
-  status
-  authentication_method
-  credential_reference_or_subject
-  revocation_version
-  created_at
-  last_authenticated_at
-
-memberships
-  membership_id
-  principal_id
-  bridge_id
-  grant_id
-  grant_revision
-  status
-  expires_at
-  created_at
-
-clients
-  client_id
-  client_name
-  redirect_uris
-  registration_identity
-  created_at
-  last_used_at
-
-authorization_codes
-  code_hash
-  client_id
-  principal_id
-  membership_id
-  grant_id
-  grant_revision
-  redirect_uri
-  code_challenge
-  scope
-  resource
-  expires_at
-
-access_tokens
-  token_hash
-  client_id
-  principal_id
-  membership_id
-  grant_id
-  grant_revision
-  principal_revocation_version
-  scope
-  resource
-  expires_at
-```
-
-Use random opaque identifiers. Do not use an email address, OAuth source address, client name, or browser fingerprint as the primary authorization key.
-
-The current `OAuthClient`, `OAuthCode`, and `OAuthToken` records can be migrated by adding optional principal/grant fields and treating legacy records as the single-owner principal until reauthorization. Avoid a flag day that silently changes existing users' authority.
-
-## Grant model
-
-A grant should reference capabilities rather than duplicate an arbitrary list of tool names. The current shared policy contract already provides the correct vocabulary and compound requirements.
-
-Example conceptual grants:
-
-| Grant | Capabilities | Typical use |
+| Role | Effective local profile | Typical use |
 |---|---|---|
-| `reviewer` | read-only, workspace-confined | inspection and review |
-| `editor` | read/write, no process execution | deterministic file changes |
-| `agent` | workspace-confined writes and direct processes, isolated environment | trusted coding automation |
-| `operator` | canonical `full` | single-owner or highly trusted administration |
-
-The effective authorization must be the intersection of all applicable ceilings:
-
-```text
-local workspace policy ceiling
-AND principal membership grant
-AND OAuth scopes/resource binding
-AND any MCP-host-side restrictions
-```
-
-A grant must never widen the locally selected workspace policy. For example, assigning `operator` cannot make a daemon started under `review` execute a process.
-
-Do not create a second independently maintained permission matrix. Grant resolution should consume the same shared capability contract used by local policy, Worker tool advertisement, and runtime execution.
-
-## Dual enforcement without two sources of truth
-
-Worker-only filtering is insufficient because a protocol bug, stale token, alternate transport, or compromised relay must not bypass local authority. Local-only filtering is also insufficient because unauthorized tools should not be advertised or relayed.
-
-Use the following contract:
+| `reviewer` | `review` | Read-only workspace, Git, image, resource, and job inspection |
+| `editor` | `edit` | Reviewer access plus deterministic file mutation |
+| `operator` | `agent` | Editor access plus workspace-confined direct process execution and sessions |
+| `owner` | `full` | Complete bridge authority, including shell, unrestricted paths, browser, applications, resources, jobs, and account administration |
 
-1. The local daemon owns the machine policy ceiling and the canonical grant catalog it is willing to honor.
-2. On authenticated `hello`, the daemon advertises a bounded grant-catalog revision/digest plus the policy ceiling and tool catalog.
-3. The Worker owns principals, memberships, OAuth codes, and access tokens for that bridge.
-4. A membership references only a grant ID/revision present in the daemon-advertised catalog.
-5. The Worker filters `tools/list` and rejects `tools/call` using the membership grant.
-6. Every relayed call includes a bounded authorization context containing opaque principal, membership, grant, and revision identifiers plus scopes.
-7. The local daemon independently resolves the grant and rechecks the operation against the current local ceiling before execution.
-8. A missing grant, stale revision, digest mismatch, suspended membership, or revoked principal fails closed.
+The effective tool set is the intersection of:
 
-This is not duplicated policy: the shared contract defines capability semantics; the Worker and daemon enforce the same resolved grant at separate trust boundaries.
+1. the account role;
+2. the policy advertised by the connected local daemon;
+3. the tools actually available from that daemon.
 
-## Authentication choices
+The Worker filters `tools/list` and rejects unauthorized calls before relay. Every accepted relay call also carries `account_id`, `account_version`, and `role`; the local runtime validates the role again before dispatch. The shared policy contract remains the single source of capability semantics.
 
-Authentication should be an adapter behind the principal model, not embedded in tool authorization.
+## Account lifecycle
 
-Reasonable progression:
+List accounts:
 
-1. **Compatibility mode:** retain the existing shared connection password and map it to one owner principal.
-2. **Local managed accounts:** create separate high-entropy one-time invitations or passkey/WebAuthn credentials for principals.
-3. **External identity provider:** accept OIDC identities from a configured issuer and map stable issuer/subject pairs to principals.
-4. **Service principals:** use separately rotated non-human credentials with narrow grants and explicit expiry.
-
-Do not issue one static password per person while leaving tokens unbound to a principal. That changes credential distribution but does not create account semantics.
-
-For external identity, key principals by the pair `(issuer, subject)`, not by mutable email or display name. Keep identity-provider integration optional so a self-hosted single-owner installation remains simple.
-
-## OAuth and MCP authorization rules
-
-A principal-aware implementation should preserve the current authorization-code and PKCE flow and add these rules:
-
-- the authorization code is bound to the authenticated principal, membership, client, redirect URI, PKCE challenge, scope, and resource;
-- access tokens are audience/resource restricted to the exact bridge `/mcp` endpoint;
-- tokens contain no raw credentials and are stored only as hashes;
-- requested scopes are intersected with the membership grant rather than accepted as authority by themselves;
-- dynamic client registration limits remain independent of principal limits;
-- token and authorization-code quotas are enforced per principal and client as well as globally;
-- cancellation/request correlation includes the token identity but never treats it as the principal database key;
-- token validation checks principal status, membership status/expiry, principal revocation version, grant revision, token expiry, and resource binding.
-
-The MCP authorization specification uses OAuth protected-resource metadata and resource indicators; OAuth security best practice requires exact redirect matching, PKCE, and audience-restricted tokens. Preserve those properties when adding identity rather than inventing a parallel session protocol.
-
-## Revocation
-
-The current `OAUTH_TOKEN_VERSION` is useful as an emergency whole-bridge kill switch but too coarse for ordinary account management.
-
-Add four independent revocation levels:
-
-1. revoke one access token/session;
-2. revoke all tokens issued to one OAuth client for a principal;
-3. increment one principal's revocation version or suspend the principal;
-4. change or revoke one membership/grant revision.
-
-Keep whole-bridge secret rotation for suspected deployment compromise. Ordinary account removal should not disconnect every other principal.
-
-Managed jobs require separate treatment: a running job snapshots authority at acceptance and can outlive an MCP token. Revoking an account should block new calls immediately and provide an explicit option to cancel active jobs accepted by that membership. Silent automatic cancellation may be unsafe when cleanup/finally steps are required.
-
-## Administration surface
-
-Account management is an operator function, not an ordinary MCP tool available to every account. A future CLI could expose:
-
-```text
-machine-mcp account invite
+```sh
 machine-mcp account list
-machine-mcp account show ACCOUNT_ID
-machine-mcp account set-grant ACCOUNT_ID GRANT
-machine-mcp account suspend ACCOUNT_ID
-machine-mcp account revoke ACCOUNT_ID
-machine-mcp account sessions ACCOUNT_ID
-machine-mcp account revoke-session SESSION_ID
 ```
 
-These names are a design proposal, not current commands.
-
-Administrative mutations should require local operator access or a separately protected admin plane. Do not let a normal `full` MCP session implicitly create additional principals merely because it can execute shell commands; that would make account administration indistinguishable from local-machine takeover.
-
-## Concurrency and quotas
-
-The existing global bounds should remain. Add fair per-principal limits for:
+Create an account. The generated password is displayed once and is not stored locally:
 
-- concurrent relay calls;
-- OAuth clients and active tokens;
-- authorization failures;
-- process sessions;
-- accepted managed jobs;
-- response bytes and rate windows where needed.
-
-A principal limit must not replace a global limit. Otherwise many accounts can exhaust one daemon collectively.
-
-A single local daemon still serializes or coordinates operations that mutate shared workspace state. Account support does not make concurrent Git operations, patches, browser actions, or service changes conflict-free. Existing mutation locks and transactional checks remain authoritative.
-
-## Audit and privacy
-
-Operational logs must continue to omit credentials, tool arguments, file contents, process output, browser content, and personal identifiers.
-
-For account diagnosis, log only bounded pseudonymous identifiers such as an HMAC-derived principal handle, grant ID/revision, event class, and outcome. Store a separate owner-only administrative audit record only when there is a concrete operator requirement, with explicit retention and access controls.
-
-Do not expose account lists, emails, identity-provider subjects, or session inventories through ordinary `server_info`. A principal may see its own effective grant and token expiry; only the local administrator should see cross-account inventory.
-
-## Cloudflare Durable Object topology
-
-Retain one Durable Object instance per bridge/workspace. It already provides a serializable state and WebSocket coordination boundary for that bridge.
-
-Avoid these two extremes:
-
-- **One Durable Object per access token:** this fragments the one-daemon call registry and complicates global limits, cancellation, and grant updates.
-- **One global Durable Object for every workspace and tenant:** this increases blast radius, couples unrelated deployments, creates a central routing/credential registry, and makes local lifecycle operations harder to reason about.
-
-If a future shared control plane is required, keep it limited to account discovery/invitations and route each request to the bridge-specific Durable Object. Local tool calls should still terminate at the bridge boundary.
+```sh
+machine-mcp account add alice reviewer
+machine-mcp account add build-bot operator
+```
 
-## Rejected designs
+Change role or active state:
 
-### Treat `client_id` as the account
+```sh
+machine-mcp account role alice editor
+machine-mcp account disable build-bot
+machine-mcp account enable build-bot
+```
 
-Rejected because one application may serve many users and one user may use many applications. Client rotation or reinstall would also appear to create a new person.
+Rotate one account's password:
 
-### Give each user a different connection password only
+```sh
+machine-mcp account rotate-password alice
+```
 
-Rejected because credentials, tokens, grants, revocation, quotas, and audit events still lack a stable principal binding.
+Remove an account:
 
-### Enforce grants only in the Worker
+```sh
+machine-mcp account remove alice
+machine-mcp account remove alice --yes
+```
 
-Rejected because the local runtime is the final filesystem/process boundary and must fail closed independently.
+The final active owner cannot be disabled, demoted, or removed. This prevents an accidental administrative lockout.
 
-### Enforce grants only in the daemon
+## OAuth model
 
-Rejected because the Worker would advertise and relay tools to unauthorized callers, increasing leakage and attack surface.
+An OAuth `client_id` identifies client software and its registered redirect URIs. It is not an account. One OAuth client may be authorized by several Machine Bridge accounts, and one account may authorize several OAuth clients.
 
-### Put all machines and workspaces behind one tenant router immediately
+An authorization code records:
 
-Rejected as unnecessary coupling. The existing per-workspace lifecycle is a useful security and operational boundary.
+- OAuth client ID;
+- account ID and account version;
+- role;
+- redirect URI;
+- PKCE S256 challenge;
+- scope and protected resource;
+- expiration.
 
-### Share `full` among mutually untrusted accounts
+An access-token record contains the same account binding plus the deployment-wide token version. Token values are stored only as SHA-256 lookup keys. Account passwords are CLI-generated 256-bit tokens. The Worker stores independent salted HMAC-SHA-256 verifiers and rejects arbitrary human-chosen passwords; the token entropy, rather than a CPU-intensive dictionary-hardening loop, provides offline-guessing resistance within the Worker CPU budget.
 
-Rejected because `full` exposes local-user process, shell, browser, and filesystem authority. Application-level role checks cannot provide OS isolation.
+At each authenticated request, the Worker verifies that the account still exists, is active, and has the same version and role recorded in the token. A password rotation, role change, suspension, or removal increments or removes that account state and invalidates only its codes and tokens.
 
-## Incremental delivery plan
+`machine-mcp rotate-secrets` is intentionally broader. It rotates the account-administration secret, daemon secret, and deployment-wide token version, invalidating every account token and requiring all clients to authorize again.
 
-### Phase 0: make the boundary explicit
+## Administrative boundary
 
-- document current multi-client behavior and lack of account isolation;
-- recommend separate bridge/OS boundaries for different trust domains;
-- keep current behavior unchanged.
+Account administration is not exposed as an MCP tool. It uses an owner-only local secret to call private Worker administration endpoints from the CLI. The administration secret is stored only in owner-protected local state and Cloudflare Worker secrets; it is never printed by `status`, sent through MCP, or used as an account password.
 
-### Phase 1: principal records and targeted revocation
+The first start of a new deployment creates an `owner` account automatically and prints its generated password once. Subsequent starts do not display account passwords.
 
-- add owner principal migration;
-- bind codes/tokens to principal and membership IDs;
-- add per-principal suspension and revocation version;
-- preserve one common grant initially;
-- add migration, expiry, quota, and revocation tests.
+## Concurrency and revocation
 
-### Phase 2: named grants and dual enforcement
+Pending calls remain bound to the OAuth access token and JSON-RPC request ID. Duplicate in-flight IDs under one token are rejected. Account revocation blocks new requests immediately; calls already relayed remain subject to ordinary cancellation, deadlines, relay disconnect cleanup, and local role validation.
 
-- derive grant capabilities from the shared policy contract;
-- advertise grant catalog revision/digest in the daemon handshake;
-- filter tool lists/calls in the Worker and recheck locally;
-- add stale-revision, reconnect, policy-narrowing, cancellation, and managed-job tests.
+Remote relay loss cancels every relay-owned local call and terminates its child process tree. Process promises settle on cancellation even when a child does not emit `close`; process ownership remains tracked until actual exit.
 
-### Phase 3: operator account lifecycle
+## Audit and privacy
 
-- add invitation, list, suspension, grant, and session-revocation CLI commands;
-- add owner-only persistence and administrative audit retention;
-- add concurrent and fault-injection tests for account mutations.
+Operational metrics identify tools and stable error classes, not account passwords, bearer tokens, arguments, command text, file content, or results. `server_info` may return the authenticated account ID, role, and version to that account so the client can verify its authorization context.
 
-### Phase 4: optional external identity
+Account names and display names are operator-selected metadata. Do not use secrets, email addresses, customer identifiers, or other unnecessary personal data in account names.
 
-- add passkey/WebAuthn or configured OIDC adapters only after the principal/grant model is stable;
-- keep single-owner password compatibility simple;
-- do not require a central SaaS account service.
+## Deployment topology
 
-## Acceptance criteria for claiming multi-account support
+One workspace normally maps to one Worker name, one Durable Object instance, one local state profile, and one active daemon. Multiple accounts share this topology and its OS trust boundary.
 
-The project should not advertise isolated multi-account support until tests prove all of the following:
+Use a separate deployment when any of these differ:
 
-- two principals can authorize through the same client and receive different grants;
-- one principal can use two clients without becoming two accounts;
-- revoking one principal leaves another principal's sessions valid;
-- narrowing the local policy immediately prevents a broader account grant from executing;
-- a stale grant revision fails in both Worker and daemon paths;
-- `tools/list` and `tools/call` enforce the same effective grant;
-- disconnect, daemon replacement, token expiry, and secret rotation converge safely;
-- account quotas cannot bypass global bounds;
-- managed jobs are attributed to a membership and have an explicit revocation/cancellation policy;
-- logs and public status do not expose personal identifiers or credentials;
-- different trust domains remain externally isolated when process/browser authority is available.
+- OS user or machine owner;
+- workspace trust domain;
+- browser/profile trust;
+- network or credential-store authority;
+- billing or incident-response boundary;
+- requirement for hard tenant isolation.
 
-Until those conditions are implemented, the accurate product statement is:
+Do not place several unrelated machines or mutually untrusted teams behind one broad owner deployment merely to reduce administration.
 
-> Machine Bridge supports multiple OAuth clients and tokens for one trusted workspace owner or trust domain. It does not yet provide isolated multi-user tenancy in one deployment.
+## Security limits
 
-## Standards and implementation references
+A `reviewer` cannot invoke mutation or process tools through Machine Bridge, but data readable by the local OS user may still be exposed by a bug, compromised dependency, or incorrectly broad workspace. An `operator` can run interpreters, package managers, compilers, and repository scripts; direct argv execution therefore remains powerful even without a shell. An `owner` has effectively the authority of the local OS user and any browser or Accessibility permissions granted to the runtime.
 
-- [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
-- [OAuth 2.0 Security Best Current Practice (RFC 9700)](https://www.rfc-editor.org/rfc/rfc9700)
-- [OAuth 2.0 Authorization Server Issuer Identification (RFC 9207)](https://www.rfc-editor.org/rfc/rfc9207)
-- [OAuth 2.0 Resource Indicators (RFC 8707)](https://www.rfc-editor.org/rfc/rfc8707)
-- [OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://www.rfc-editor.org/rfc/rfc9728)
-- [Cloudflare Durable Objects documentation](https://developers.cloudflare.com/durable-objects/)
-- [Security policy](../SECURITY.md)
-- [Architecture](ARCHITECTURE.md)
+Roles are useful defense in depth and targeted revocation. They are not substitutes for least-privilege OS design, sandboxing, endpoint security, Cloudflare account protection, or careful review of untrusted repositories and instructions.

package/docs/OPERATIONS.md

@@ -67,7 +67,7 @@ Application UI inspection/actions require Accessibility permission for the Node/
 
 `machine-mcp` is a foreground command. It remains attached to the terminal, defaults to `info` logging, and stops on `Ctrl+C`. `machine-mcp service start` launches the installed platform service in the background and returns to the shell; that service uses `warn` logging.
 
-A global npm install changes the CLI files on disk but does not replace an already running Node process. Startup and other state-changing CLI operations use a token/process-identity lock and wait up to 30 seconds for a normal concurrent startup to finish; a short launchd/systemd overlap is therefore serialized rather than reported immediately as an error. On a normal foreground start, Machine Bridge unloads the platform service and then independently examines the workspace daemon lock. This second path handles a detached/orphan `--daemon-only` process that launchd/systemd/task scheduling no longer tracks, including legacy locks without mode/version metadata. Before sending `SIGTERM`, Machine Bridge verifies PID and process start time plus the live command line, entrypoint, canonical workspace, canonical state root, and daemon-only flag. It waits up to 15 seconds for both the PID and lock to disappear and does not add a later forced-kill escalation. On POSIX, a daemon that handles and ignores `SIGTERM` therefore reaches the bounded timeout and remains alive. Node maps the supported termination signals to immediate process termination on Windows, so the same verified-daemon stop normally completes rather than exercising the POSIX timeout branch. A foreground or unverifiable process is left untouched; stop a foreground instance with `Ctrl+C`.
+A global npm install changes the CLI files on disk but does not replace an already running Node process. Startup and other state-changing CLI operations use a token/process-identity lock and wait up to 30 seconds for a normal concurrent startup to finish; a short launchd/systemd overlap is therefore serialized rather than reported immediately as an error. On a normal foreground start, Machine Bridge unloads the platform service and then independently examines the workspace daemon lock. This second path handles a detached/orphan `--daemon-only` process that launchd, systemd, or Task Scheduler no longer tracks. Only current lock records containing service mode, version, PID, process start time, entrypoint, workspace, and state root are eligible for takeover. Before sending `SIGTERM`, Machine Bridge verifies PID and process start time plus the live command line, entrypoint, canonical workspace, canonical state root, and daemon-only flag. It waits up to 15 seconds for both the PID and lock to disappear and does not add a later forced-kill escalation. On POSIX, a daemon that handles and ignores `SIGTERM` therefore reaches the bounded timeout and remains alive. Node maps the supported termination signals to immediate process termination on Windows, so the same verified-daemon stop normally completes rather than exercising the POSIX timeout branch. A foreground or unverifiable process is left untouched; stop a foreground instance with `Ctrl+C`.
 
 `machine-mcp service status [WORKSPACE]` reports two independent layers: the platform service (`active`) and `workspace_daemon`, plus `effective_active` and `orphaned_workspace_daemon` summary flags. On macOS it is possible for launchd to report inactive while a prior Node process remains alive with parent PID 1; that is an orphan-daemon condition, not proof that the daemon stopped. `service stop` unloads the provider when present and then terminates only a verified service-style workspace daemon. `service uninstall` and full uninstall are ordered fail-closed operations: provider stop → verified daemon stop(s) → definition removal. A failed or ambiguous stop leaves definitions and state intact. If takeover reaches its deadline, run:
 
@@ -91,7 +91,7 @@ npm --version
 machine-mcp --verbose
 ```
 
-`Unknown cli config "--allow-scripts"` proves the package installation ran under npm 11 or older. `Invalid property "node"` or `Invalid property "devEngines.node"` means npm parsed a legacy `devEngines` object; inspect the npm debug log to identify its source rather than assuming it belongs to Machine Bridge. The published package declares both Node.js 26 and npm 12 in `engines`, and `machine-mcp doctor` checks both active versions. Keep `--omit=optional` in the install command. Without it npm may resolve optional `fsevents` and warn that its install script was not included in `allowScripts`; Machine Bridge does not require that development-time watcher at runtime.
+`Unknown cli config "--allow-scripts"` proves the package installation ran under npm 11 or older. `Invalid property "node"` or `Invalid property "devEngines.node"` means npm parsed an outdated `devEngines` object; inspect the npm debug log to identify its source rather than assuming it belongs to Machine Bridge. The published package declares both Node.js 26 and npm 12 in `engines`, and `machine-mcp doctor` checks both active versions. Keep `--omit=optional` in the install command. Without it npm may resolve optional `fsevents` and warn that its install script was not included in `allowScripts`; Machine Bridge does not require that development-time watcher at runtime.
 
 ## State-root safety and removal
 
@@ -108,7 +108,7 @@ Uninstall acquires a state-root `maintenance.lock` that blocks new profile/state
 Stable errors include `policy_denied`, `invalid_request`, `timeout`, `cancelled`, `network_error`, `unavailable`, `limit_exceeded`, and `integrity_error`, with retryability metadata. Diagnose by code first; free-form messages are guidance, not an API contract.
 
 
-Windows Scheduled Task command lines use CRT-compatible quoting, including trailing backslashes and drive-root paths. Remote autostart definitions prefer a stable PATH alias that resolves to the currently running Node executable and persist a sanitized absolute-only service `PATH` containing the Node/CLI directories, the installer's absolute PATH entries, and platform defaults. This avoids versioned Homebrew-style paths becoming invalid after upgrades and prevents launchd/systemd from falling back to a minimal system-only PATH. Re-run `machine-mcp service install` after changing Node installation families or PATH layout. A service-style `--daemon-only` start that finds the same workspace daemon already running is an idempotent no-op: it exits successfully without repeating warnings or readiness output; explicit policy/secret/change requests still report that changes were not applied. Autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Installed services pass `--log-level warn --log-format json`, so each active line is a bounded JSON event suitable for ingestion. Files are owner-only where supported and tail-trimmed before daemon startup. On a logging-schema upgrade, bounded prior content is moved into `daemon.out.legacy.log` and `daemon.err.legacy.log`; use the active filenames when diagnosing current behavior.
+Windows Scheduled Task command lines use CRT-compatible quoting, including trailing backslashes and drive-root paths. Remote autostart definitions prefer a stable PATH alias that resolves to the currently running Node executable and persist a sanitized absolute-only service `PATH` containing the Node/CLI directories, the installer's absolute PATH entries, and platform defaults. This avoids versioned Homebrew-style paths becoming invalid after upgrades and prevents launchd/systemd from falling back to a minimal system-only PATH. Re-run `machine-mcp service install` after changing Node installation families or PATH layout. A service-style `--daemon-only` start that finds the same workspace daemon already running is an idempotent no-op: it exits successfully without repeating warnings or readiness output; explicit policy/secret/change requests still report that changes were not applied. Autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Installed services pass `--log-level warn --log-format json`, so each active line is a bounded JSON event suitable for ingestion. Files are owner-only where supported and tail-trimmed before daemon startup. If the log schema marker does not match the current format, the active files are cleared before startup and the current marker is written. Runtime code reads and maintains only the active filenames.
 
 Logging is level-based:
 
@@ -214,7 +214,7 @@ Defense-in-depth limits include:
 
 ## Upgrade behavior
 
-Policy revision 4 makes named profiles canonical and evaluates compound tool requirements from the shared contract. A state entry labelled `full` is repaired to writes, direct processes, process sessions, shell execution, unrestricted direct filesystem paths, absolute path output, the complete parent environment, and the complete tool catalog. CLI capability overrides are stored as `custom`. The exact pre-0.4 implicit-default shape is still migrated to the current `full` default; explicit restrictive and identified custom profiles remain preserved.
+Policy revision 5 makes named profiles canonical and evaluates compound tool requirements from the shared contract. A state entry labelled `full` means writes, direct processes, process sessions, shell execution, unrestricted direct filesystem paths, absolute path output, the complete parent environment, and the complete tool catalog. CLI capability overrides are stored as `custom`. Persisted policies from another revision are rejected rather than interpreted.
 
 `full` removes Machine Bridge's own profile/path/environment/shell denials and makes the complete catalog available to the relay. It does not force a connector host to expose every relayed tool, and the server cannot see the host's final subset. It also does not override operating-system access controls, endpoint security, remote authentication, cloud IAM, `sudo`, or independent MCP-host/platform policy.
 

package/docs/POLICY_REFERENCE.md

@@ -2,7 +2,7 @@
 
 > Generated from `src/shared/policy-contract.json` and `src/shared/tool-catalog.json`. Do not edit this file manually.
 
-Policy revision: **4**. Default profile: **full**.
+Policy revision: **5**. Default profile: **full**.
 
 ## Canonical profiles
 

package/docs/PRIVACY.md

@@ -13,7 +13,7 @@ npm run privacy:history
 
 `privacy:check` scans tracked and unignored new UTF-8 files and relative names for generic/encrypted/algorithm-specific private-key headers, AWS/GitHub/GitLab/npm/Slack/Google/live-payment/API token forms, JWT-shaped bearer values, embedded-credential URLs, absolute user-home paths, non-example email/`user@host` identifiers, credential-shaped filenames, and locally configured private identifiers. A tracked `.npmrc` is parsed: non-secret repository settings such as `engine-strict=true` are allowed, while authentication/identity keys, environment interpolation, and embedded credentials fail closed. Publication-surface symbolic links are rejected rather than followed. Binary, invalid UTF-8, and files above the bounded scanner limit require explicit manual review instead of being silently skipped. Findings report only file, line, and rule; the matched value is never printed.
 
-`privacy:history` first runs the same current-tree checks, then scans every reachable historical blob path and bounded UTF-8 blob plus every reachable commit message. It catches values that were committed and later deleted. Standard public Dependabot signing trailers are ignored only in that exact commit-message context; the same non-example address remains disallowed in ordinary files. The local `.privacy-denylist` is also applied to history, so a developer may discover legacy identifiers that CI cannot know. Such a finding is real publication history, but ordinary commits cannot erase it.
+`privacy:history` first runs the same current-tree checks, then scans every reachable historical blob path and bounded UTF-8 blob plus every reachable commit message. It catches values that were committed and later deleted. Standard public Dependabot signing trailers are ignored only in that exact commit-message context; the same non-example address remains disallowed in ordinary files. The local `.privacy-denylist` is also applied to history, so a developer may discover older identifiers that CI cannot know. Such a finding is real publication history, but ordinary commits cannot erase it.
 
 Git author and committer identity headers are canonical Git metadata rather than blob or commit-message content and are not automatically rejected. Audit them separately with `git log`; changing historical identity metadata requires a coordinated history rewrite and force-update of affected refs.
 

package/docs/PROJECT_STANDARDS.md

@@ -36,7 +36,7 @@ Commit and squash-merge subjects follow Conventional Commits:
 <type>[optional scope][optional !]: <imperative description>
 ```
 
-Allowed types are `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `security`, `release`, and `revert`. `feat` and `fix` carry their normal semantic-version meaning. A breaking change uses `!` and explains migration impact in the body or a `BREAKING CHANGE:` footer.
+Allowed types are `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `security`, `release`, and `revert`. `feat` and `fix` carry their normal semantic-version meaning. A breaking change uses `!` and explains upgrade impact in the body or a `BREAKING CHANGE:` footer.
 
 A good change explains both **what changed and why**. Commits should be logically coherent, but intermediate branch history may be amended because the final pull request is squash-merged. Pull-request titles must satisfy the same format because they become the `main` commit subject.
 

package/docs/TESTING.md

@@ -21,7 +21,7 @@ The suite includes:
 - shared tool-catalog schema, annotation, and profile-inventory checks;
 - 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, and bounded startup-lock waiting;
-- foreground takeover of active and orphaned background daemons, legacy lock identification from canonicalized process arguments, 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;
+- 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;
 - 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, installed-application discovery caching, and name-based task matching;
 - relay environment-proxy direct/bypass/agent selection, unsupported proxy rejection, fail-fast invalid configuration, and route observability without endpoint or credential disclosure;
@@ -41,11 +41,11 @@ The suite includes:
 - 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, plan scrubbing, PID-reuse-safe dead-runner recovery, and legacy PID-file compatibility;
+- 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, 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, schema migration, policy-origin persistence, and legacy implicit-default migration;
+- 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, and idempotent bounded migration of legacy log formats;
+- 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;
 - deterministic relay connection lifecycle coverage for transport construction/error/deadline, pre-handshake `welcome` validation, authenticated `hello_ack` readiness, identity/version mismatch, retryable Worker handshake errors, fatal protocol errors, autonomous outage-reminder backoff, handshake and 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;
 - CLI parsing, policy profiles, and client configuration boundaries;