machine-bridge-mcp 0.17.0 → 0.18.0

package/docs/GETTING_STARTED.md

@@ -0,0 +1,404 @@
+# Installation and first-use guide
+
+This guide covers a clean installation, the first remote ChatGPT connection, local stdio clients, browser setup, routine operation, upgrades, troubleshooting, and removal.
+
+## 1. Decide which connection mode you need
+
+Machine Bridge has two transports. Choose one before installing:
+
+| Requirement | Use | Cloudflare required | Process that must remain available |
+|---|---|---:|---|
+| ChatGPT web, a hosted agent, or another device must reach this computer | Remote HTTPS/OAuth | Yes | Machine Bridge daemon or installed login service |
+| Claude Desktop, Cursor, Codex, ChatGPT Desktop, or another local host runs on this computer | Local stdio | No | The MCP host launches Machine Bridge as a subprocess |
+| The local coding client already has equivalent file, Git, patch, and terminal tools | Neither | No | None |
+
+Remote and stdio modes use the same local runtime and policy model. The remote Worker authenticates and relays calls; it does not read files or execute processes by itself.
+
+## 2. Understand the authority you are granting
+
+A new workspace uses the `full` profile unless another profile is selected explicitly. `full` exposes the complete tool catalog, shell execution, paths outside the selected workspace, absolute paths, and the complete parent process environment. It is intended for a trusted owner using a trusted MCP host.
+
+For a first connection to an unfamiliar host, start with a narrower profile:
+
+```sh
+machine-mcp --workspace /path/to/project --profile review
+```
+
+Profiles:
+
+| Profile | Reads | File changes | Direct processes | Shell | Direct filesystem scope |
+|---|---:|---:|---:|---:|---|
+| `full` | Yes | Yes | Yes | Yes | Unrestricted |
+| `agent` | Yes | Yes | Yes | No | Selected workspace |
+| `edit` | Yes | Yes | No | No | Selected workspace |
+| `review` | Yes | No | No | No | Selected workspace |
+
+A profile is a Machine Bridge policy ceiling. The MCP host, operating system, endpoint-security software, container, and cloud platform may impose additional restrictions.
+
+## 3. Prerequisites
+
+Required for every installation:
+
+- Node.js 26 or newer;
+- npm 12 or newer;
+- macOS, Linux, or Windows;
+- a local user account permitted to read or modify the selected workspace.
+
+Remote mode additionally requires:
+
+- a Cloudflare account permitted to deploy Workers and Durable Objects;
+- a browser available for Wrangler sign-in;
+- outbound HTTPS and WebSocket access from the computer running the daemon.
+
+Browser automation additionally requires:
+
+- a Chromium-based browser that can load an unpacked Manifest V3 extension;
+- the extension loaded into the browser profile whose tabs and login state should be controlled.
+
+Check the installed runtimes:
+
+```sh
+node --version
+npm --version
+```
+
+Do not continue with an older runtime. This repository intentionally rejects unsupported Node/npm versions.
+
+## 4. Install the released package
+
+Use a temporary package-free directory. An older npm front-end can inspect metadata in the current directory before it launches npm 12; the isolated bootstrap prevents an unrelated project configuration from breaking installation.
+
+### macOS and Linux
+
+```sh
+install_dir="$(mktemp -d)"
+(
+  cd "$install_dir"
+  npx --yes npm@12.0.1 install --global npm@12.0.1
+  npx --yes npm@12.0.1 install --global --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
+)
+rm -rf "$install_dir"
+
+npm --version
+machine-mcp doctor
+```
+
+### Windows Command Prompt
+
+```bat
+set "MBM_INSTALL_DIR=%TEMP%\machine-bridge-mcp-install-%RANDOM%-%RANDOM%"
+mkdir "%MBM_INSTALL_DIR%"
+pushd "%MBM_INSTALL_DIR%"
+npx --yes npm@12.0.1 install --global npm@12.0.1
+npx --yes npm@12.0.1 install --global --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
+popd
+rmdir /s /q "%MBM_INSTALL_DIR%"
+
+npm --version
+machine-mcp doctor
+```
+
+Reopen the terminal if `npm --version` still resolves to an older global installation.
+
+### Run from a source checkout
+
+macOS/Linux:
+
+```sh
+git clone https://github.com/YuLeiFuYun/machine-bridge-mcp.git
+cd machine-bridge-mcp
+npm install
+./mbm
+```
+
+Windows Command Prompt:
+
+```bat
+git clone https://github.com/YuLeiFuYun/machine-bridge-mcp.git
+cd machine-bridge-mcp
+npm install
+.\mbm.cmd
+```
+
+Source installs are for development or review. Released installations should normally use the global package command above.
+
+## 5. Interpret the initial doctor result
+
+Run:
+
+```sh
+machine-mcp doctor
+```
+
+The command checks the local runtime, package layout, Wrangler availability, Cloudflare login state, and known Worker health. Before the first remote deployment, a missing Cloudflare login or Worker is expected; local runtime failures are not.
+
+Common installation failures:
+
+| Message or symptom | Meaning | Corrective action |
+|---|---|---|
+| `Unknown cli config "--allow-scripts"` | npm 11 or older executed the install | Repeat the isolated npm 12 bootstrap |
+| `Invalid property "node"` or `Invalid property "devEngines.node"` | An old npm parser inspected incompatible project metadata | Run the install from a new empty temporary directory |
+| `machine-mcp: command not found` | The global npm binary directory is not on `PATH` | Reopen the terminal, inspect `npm prefix -g`, and add its binary directory to `PATH` |
+| Native package install warning | npm did not approve reviewed native build scripts | Use the documented `--allow-scripts` and `--omit=optional` command exactly |
+
+## 6. First remote start
+
+Choose the exact workspace to expose. Prefer an explicit path rather than relying on the current directory:
+
+```sh
+machine-mcp --workspace /path/to/project
+```
+
+For a narrower first run:
+
+```sh
+machine-mcp --workspace /path/to/project --profile review
+```
+
+The first start performs these operations:
+
+1. canonicalizes and remembers the workspace;
+2. creates owner-only per-workspace state and credentials;
+3. opens the Wrangler/Cloudflare sign-in flow when required;
+4. deploys a Worker and Durable Object for that workspace;
+5. installs a platform-native login service unless `--no-autostart` is supplied;
+6. starts an outbound authenticated WebSocket from the local daemon to the Worker;
+7. creates the initial `owner` account when no account exists and prints its generated password once;
+8. prints the remote `/mcp` URL.
+
+The foreground command remains attached to the terminal. Keep it running while testing. The remote Worker cannot execute local tools when no authenticated daemon is connected.
+
+To run only in the background after setup:
+
+```sh
+machine-mcp service start
+machine-mcp service status
+```
+
+To avoid installing autostart during a temporary test:
+
+```sh
+machine-mcp --workspace /path/to/project --no-autostart
+```
+
+## 7. Connect ChatGPT
+
+Machine Bridge prints the remote endpoint and, only when creating the first account, a one-time owner password:
+
+```text
+MCP Server URL: https://<worker>.<account>.workers.dev/mcp
+Account: owner
+Password: account_password_...
+```
+
+Save the generated password in a password manager. It is not stored locally or shown again. Do not place it in a repository, issue, screenshot, chat message, shell history note, or shared document.
+
+Current ChatGPT developer-mode flow, as documented in OpenAI's [Connect from ChatGPT](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt) guide:
+
+1. Open ChatGPT settings.
+2. Under **Security and login**, enable **Developer mode** if the account or workspace permits it.
+3. Open **Plugins** and create a developer-mode app.
+4. Enter a descriptive name and the exact printed `/mcp` URL.
+5. Start the connection.
+6. On the Machine Bridge authorization page, verify the displayed client name, redirect URI, and resource.
+7. Enter the Machine Bridge account name and password only after those values are recognized.
+8. Create a new chat and enable the app for that conversation.
+
+ChatGPT navigation labels can change. The invariant is that the client must connect to the public `/mcp` endpoint and complete the OAuth authorization page served by the Worker.
+
+## 8. Verify the first connection
+
+Ask the MCP host to call these tools in order:
+
+1. `server_info` — proves the request reached the Worker and reports whether a daemon is authenticated;
+2. `project_overview` — proves the relay reached the selected local runtime;
+3. `diagnose_runtime` — runs fixed policy, filesystem, process, shell, managed-job, and resource probes permitted by the active profile.
+
+For an explicit local acceptance test of the canonical `full` profile:
+
+```sh
+machine-mcp full-test --workspace /path/to/project
+```
+
+A successful local test does not prove that a hosted MCP client exposes every advertised tool. Hosts can independently hide tools or require approvals.
+
+## 9. Configure a local stdio client
+
+Generate configurations rather than manually guessing the Node path or package entrypoint:
+
+```sh
+machine-mcp client-config --client all --workspace /path/to/project
+```
+
+Use a narrower policy when appropriate:
+
+```sh
+machine-mcp client-config --client all --workspace /path/to/project --profile agent
+machine-mcp client-config --client all --workspace /path/to/project --profile edit
+machine-mcp client-config --client all --workspace /path/to/project --profile review
+```
+
+The generated command uses absolute executable paths so GUI applications do not depend on a shell-specific `PATH`.
+
+A generic stdio invocation is:
+
+```sh
+machine-mcp stdio --workspace /path/to/project --profile full
+```
+
+The host owns the model, conversation, tool-selection loop, and approvals. Machine Bridge supplies tools; it is not a model provider.
+
+## 10. Enable existing-browser automation
+
+Run once after installation:
+
+```sh
+machine-mcp browser setup
+machine-mcp browser status
+```
+
+Then:
+
+1. Open the extensions page in the Chromium profile you actually use.
+2. Enable Developer mode.
+3. Load the unpacked extension directory printed by `browser setup`.
+4. Complete the local pairing page.
+5. Confirm that `machine-mcp browser status` reports the expected packaged version, protocol, and an authenticated connection.
+
+Machine Bridge does not launch a separate browser profile. The extension controls the profile into which it was loaded, including its open tabs and logged-in sessions. Reload the unpacked extension after every Machine Bridge upgrade.
+
+## 11. Routine commands
+
+```sh
+machine-mcp status
+machine-mcp doctor
+machine-mcp workspace show
+machine-mcp service status
+machine-mcp browser status
+machine-mcp account list
+```
+
+Useful operational actions:
+
+```sh
+machine-mcp service stop
+machine-mcp service start
+machine-mcp rotate-secrets
+machine-mcp account add alice reviewer
+machine-mcp account rotate-password alice
+machine-mcp resource list
+machine-mcp job list
+```
+
+`rotate-secrets` invalidates every account access token and requires all clients to authorize again. For targeted revocation, disable an account, change its role, rotate its password, or remove it.
+
+## 12. Work with more than one workspace
+
+Each canonical workspace receives independent state, policy, credentials, Worker name, resource registry, job directory, startup lock, and daemon lock. Select workspaces explicitly:
+
+```sh
+machine-mcp --workspace /path/to/project-a
+machine-mcp --workspace /path/to/project-b
+```
+
+Do not point two logical trust domains at one broad parent directory merely to reduce configuration. A workspace is an authorization boundary for confined profiles and an operational identity even when `full` permits paths outside it.
+
+## 13. Upgrade
+
+Repeat the isolated global installation, then start Machine Bridge in the target workspace:
+
+```sh
+install_dir="$(mktemp -d)"
+(
+  cd "$install_dir"
+  npx --yes npm@12.0.1 install --global npm@12.0.1
+  npx --yes npm@12.0.1 install --global --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
+)
+rm -rf "$install_dir"
+
+machine-mcp --workspace /path/to/project --verbose
+```
+
+The foreground start performs bounded takeover of an earlier verified daemon when safe. If it refuses:
+
+```sh
+machine-mcp service status
+machine-mcp service stop
+machine-mcp --workspace /path/to/project --verbose
+```
+
+After upgrading, reload the unpacked browser extension before relying on browser tools.
+
+## 14. Troubleshooting by layer
+
+Use the first failing layer rather than changing unrelated settings.
+
+### Package or runtime layer
+
+```sh
+node --version
+npm --version
+which machine-mcp       # macOS/Linux
+where machine-mcp       # Windows
+machine-mcp doctor
+```
+
+### Cloudflare/deployment layer
+
+```sh
+machine-mcp doctor
+machine-mcp status
+machine-mcp --workspace /path/to/project --force-worker --verbose
+```
+
+A forced deployment changes cloud state. Use it only when the normal deployment hash/health reconciliation is insufficient.
+
+### Local service/daemon layer
+
+```sh
+machine-mcp service status
+machine-mcp service stop
+machine-mcp service start
+```
+
+A connected Worker with no authenticated daemon can authorize OAuth successfully but cannot execute local tools.
+
+### MCP-host layer
+
+If `server_info` or `project_overview` never returns a structured Machine Bridge result, the host may not have delivered the call. Check the host's plugin/app enablement, tool permissions, approval UI, and connection status.
+
+### Operating-system layer
+
+If `diagnose_runtime` reaches the daemon but a probe fails, inspect filesystem permissions, macOS TCC/SIP, Windows ACLs, endpoint-security policy, shell availability, or container restrictions. Changing Machine Bridge to `full` cannot override the operating system.
+
+### Browser layer
+
+```sh
+machine-mcp browser status
+machine-mcp browser setup
+```
+
+Verify that the extension is loaded in the intended profile, its version matches the installed package, and its badge reports authenticated readiness.
+
+For detailed recovery procedures, see [OPERATIONS.md](OPERATIONS.md).
+
+## 15. Remove Machine Bridge
+
+Remove the selected deployment, service, and local state:
+
+```sh
+machine-mcp uninstall
+npm uninstall -g machine-bridge-mcp
+```
+
+Keep the deployed Worker while removing local state and autostart:
+
+```sh
+machine-mcp uninstall --keep-worker
+```
+
+Uninstall is fail-closed. If a verified daemon, active managed job, unreadable lock, or service removal cannot be resolved safely, Machine Bridge retains state for diagnosis instead of deleting only part of the installation.
+
+## 16. Before sharing access
+
+The current release supports named accounts with targeted revocation and four roles: `reviewer`, `editor`, `operator`, and `owner`. Roles are enforced in the Worker and local runtime, but all accounts still share one daemon and OS user. Use separate deployments and external isolation for mutually untrusted users or hard tenant boundaries. Read [MULTI_ACCOUNT.md](MULTI_ACCOUNT.md) before sharing a deployment.

package/docs/LOGGING.md

@@ -79,7 +79,7 @@ The implementation omits:
 - stdin, stdout, and stderr;
 - file, patch, image, and temporary-file content;
 - OAuth request bodies;
-- connection passwords, daemon secrets, authorization codes, and access tokens;
+- account passwords, account-administration secrets, daemon secrets, authorization codes, and access tokens;
 - registered resource values and source paths;
 - browser pairing tokens, page URLs/source, DOM metadata, form values, uploaded file bytes, and screenshots;
 - application names, Accessibility trees, selectors, and entered values;
@@ -118,7 +118,7 @@ logs/daemon.err.log
 
 Existing files are opened without following symbolic links where supported and tail-trimmed on UTF-8/line boundaries before startup. Background services use `warn`, so ordinary tool traffic and brief relay interruptions do not cause sustained growth.
 
-The log format has an explicit schema marker. When the schema changes, the daemon copies a bounded tail of each prior active log to an owner-only `daemon.out.legacy.log` or `daemon.err.legacy.log` snapshot, clears the active file, and advances the marker. The migration is idempotent and keeps historical transport-format lines visibly separate from current behavior.
+The log format has an explicit schema marker. If the marker differs from the current format, the daemon clears the active files before startup and writes the current marker. Runtime code recognizes only `daemon.out.log` and `daemon.err.log`; it does not parse or archive other log formats.
 
 Each managed job has owner-only runner diagnostic logs. Child-step output is retained only in bounded, redacted job results according to `capture_output`; it is not copied into daemon or runner operational logs.
 

package/docs/MANAGED_JOBS.md

@@ -277,7 +277,7 @@ Per-workspace jobs are stored below the owner-only profile directory. Active job
 
 Retained public job data contains bounded status and redacted results. Up to 50 jobs are retained for up to seven days. Private runtime copies are removed after the finally phase. Runner stdout/stderr log files contain only runner-level diagnostics; step output is not written to those operational logs.
 
-The detached runner records both PID and process start time. Recovery therefore rejects a reused PID instead of treating an unrelated process as the active runner; legacy numeric PID files remain readable during migration. Recovery-lock handoff preserves a random ownership token, and the runner removes only a lock whose PID, token, and file snapshot still match. Timeout and cancellation terminate the process group/tree, retain a referenced forced-escalation timer, and clean descendants that ignore graceful termination before the runner exits.
+The detached runner records a structured owner record containing PID and process start time. Recovery rejects a reused PID instead of treating an unrelated process as the active runner. Numeric-only runner records are invalid. Recovery-lock handoff preserves a random ownership token, and the runner removes only a lock whose PID, token, and file snapshot still match. Timeout and cancellation terminate the process group/tree, retain a referenced forced-escalation timer, and clean descendants that ignore graceful termination before the runner exits.
 
 Missing job JSON is distinct from unreadable or invalid job JSON. Permission, type, symbolic-link, size, UTF-8, I/O, and parse failures retain the job directory, produce an `unreadable` status for listing, skip automatic recovery/pruning, and block uninstall until an operator inspects the state.
 

package/docs/MULTI_ACCOUNT.md

@@ -0,0 +1,123 @@
+# Multi-account authorization and tenancy
+
+## What isolation means
+
+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.
+
+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.
+
+Use separate OS accounts, containers, VMs, state roots, Workers, and workspaces when users are mutually untrusted or require hard isolation.
+
+## Roles
+
+| Role | Effective local profile | Typical use |
+|---|---|---|
+| `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 |
+
+The effective tool set is the intersection of:
+
+1. the account role;
+2. the policy advertised by the connected local daemon;
+3. the tools actually available from that daemon.
+
+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.
+
+## Account lifecycle
+
+List accounts:
+
+```sh
+machine-mcp account list
+```
+
+Create an account. The generated password is displayed once and is not stored locally:
+
+```sh
+machine-mcp account add alice reviewer
+machine-mcp account add build-bot operator
+```
+
+Change role or active state:
+
+```sh
+machine-mcp account role alice editor
+machine-mcp account disable build-bot
+machine-mcp account enable build-bot
+```
+
+Rotate one account's password:
+
+```sh
+machine-mcp account rotate-password alice
+```
+
+Remove an account:
+
+```sh
+machine-mcp account remove alice
+machine-mcp account remove alice --yes
+```
+
+The final active owner cannot be disabled, demoted, or removed. This prevents an accidental administrative lockout.
+
+## OAuth model
+
+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.
+
+An authorization code records:
+
+- OAuth client ID;
+- account ID and account version;
+- role;
+- redirect URI;
+- PKCE S256 challenge;
+- scope and protected resource;
+- expiration.
+
+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.
+
+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.
+
+`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.
+
+## Administrative boundary
+
+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.
+
+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.
+
+## Concurrency and revocation
+
+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.
+
+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.
+
+## Audit and privacy
+
+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.
+
+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.
+
+## Deployment topology
+
+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.
+
+Use a separate deployment when any of these differ:
+
+- 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.
+
+Do not place several unrelated machines or mutually untrusted teams behind one broad owner deployment merely to reduce administration.
+
+## Security limits
+
+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.
+
+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.