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

package/docs/OPERATIONS.md

@@ -57,11 +57,13 @@ Machine Bridge supports concurrent calls: the Worker admits up to 32 pending dae
 
 ### Relay interruption messages
 
+A reconnect warning is evidence of a transport outage, not proof that the daemon process exited. Compare daemon PID/process start, `connected_at`, `last_seen_at`, `runtime.relay.last_disconnected_at`, close category/code, and outage count. A system VPN/TUN may remain shown as connected while its internal route is unavailable; Machine Bridge reports that route only as `system-network-stack` with application-proxy scope. The reconnect schedule now tops out at fifteen seconds.
+
 A brief relay interruption is retried automatically and is visible only with `--verbose`. Default logs do not print raw WebSocket values such as `code=1006` with an empty reason. If a transient outage persists for 10 seconds, the daemon emits a readable duration/cause/reconnect summary; later reminders use autonomous exponential backoff capped at 15 minutes, and recovery produces one readable summary. Each transport connection attempt also has a deadline, so a socket stuck in `CONNECTING` cannot freeze retries. Identity/version mismatch, authentication rejection, and unexpected protocol messages are not retried as ordinary network faults: the daemon emits an immediate actionable error and exits, requiring upgrade/redeployment or credential repair. Worker-side hello and end-to-end readiness timeouts remain retryable. Authentication is not reported as usable service readiness until a session-bound probe result returns.
 
 Use `--verbose` only when close codes, close reasons, heartbeat timeouts, and retry delays are needed for diagnosis. A close code of 1006 means the transport ended without a normal close handshake; it does not by itself identify the cause.
 
-The daemon honors `HTTPS_PROXY`/`HTTP_PROXY` and `NO_PROXY` through standard environment-proxy resolution for remote Worker health and relay traffic. `wss:` targets use HTTPS proxy selection and `ws:` targets use HTTP proxy selection. Only HTTP and HTTPS proxy URLs are accepted. Invalid URLs or unsupported protocols fail startup with corrective guidance instead of entering the reconnect loop. `server_info.runtime.relay.network_route` reports only `direct`, `proxy`, or `invalid-proxy-configuration`; proxy endpoints and credentials are never returned or logged. The browser-broker CLI health probe is a separate loopback-only path: it accepts only canonical `127.0.0.1`, uses direct Node HTTP with no proxy agent, and does not depend on `NO_PROXY`.
+The daemon honors `HTTPS_PROXY`/`HTTP_PROXY` and `NO_PROXY` through standard environment-proxy resolution for remote Worker health and relay traffic. `wss:` targets use HTTPS proxy selection and `ws:` targets use HTTP proxy selection. Only HTTP and HTTPS proxy URLs are accepted. Invalid URLs or unsupported protocols fail startup with corrective guidance instead of entering the reconnect loop. `server_info.runtime.relay.network_route` reports `system-network-stack`, `application-http-proxy`, or `invalid-application-proxy-configuration`. This field describes only Machine Bridge application-level proxy selection: an operating-system VPN/TUN may still intercept `system-network-stack` traffic. `network_route_scope`, outage timestamps/durations, close category/code, transport error class, and next retry timing make that distinction explicit; proxy endpoints and credentials are never returned or logged. The browser-broker CLI health probe is a separate loopback-only path: it accepts only canonical `127.0.0.1`, uses direct Node HTTP with no proxy agent, and does not depend on `NO_PROXY`.
 
 ## Browser extension setup and diagnosis
 
@@ -123,9 +125,15 @@ machine-mcp --verbose
 
 After global installation, Windows users may open any `cmd.exe` window and run `machine-mcp`; they do not need to navigate to a project or package directory. On the first interactive start, the CLI asks for a workspace folder and displays `%USERPROFILE%\MachineBridge` as the default. Pressing Enter creates and remembers that folder. This avoids inheriting an arbitrary Command Prompt current directory such as `C:\Windows\System32`. Typing another folder in the prompt creates that folder when necessary. Explicit `--workspace PATH` remains a strict automation interface and requires an existing path.
 
-## Version 1 upgrade convergence
+### Start, restart, and cross-workspace ownership
+
+`service start` is an idempotent ensure-running operation. It does not stop a verified already-running daemon, so calling it through that daemon cannot destroy the control connection. `service restart` is separate: macOS and systemd-user use a detached service-manager handoff so the command can return before the old daemon exits. Windows restart is fail closed from inside the running task because Task Scheduler `/End` may terminate the helper with the daemon; use an independent terminal stop/start sequence until a behaviorally verified Windows handoff exists.
+
+A workspace/state selector does not grant authority over the machine-global service label. Stop, restart, foreground takeover, secret rotation, and uninstall require the exact live verified `service` daemon ownership record. Service status returns only provider, installed/loaded/active state, PID, bounded run count, and classified termination state; provider environment dumps are never returned.
+
+## Current upgrade convergence
 
-Version 1 advertises only MCP protocol `2025-11-25`. Upgrade the MCP client/host if it cannot negotiate that version; Machine Bridge does not retain an obsolete protocol dispatcher. The current local state schema is unchanged from the final 0.18.x release, so do not delete the state root merely to upgrade.
+The current release advertises only MCP protocol `2025-11-25`. Upgrade the MCP client or host if it cannot negotiate that version; Machine Bridge does not retain an obsolete protocol dispatcher. Version 3 also requires matching Worker, daemon, CLI, and browser-extension components and may perform a two-phase device-root migration. Preserve the state root and follow [UPGRADING.md](UPGRADING.md); do not delete state to force apparent convergence.
 
 Use this sequence:
 
@@ -154,7 +162,7 @@ Stable errors include `policy_denied`, `invalid_request`, `timeout`, `cancelled`
 
 Windows Task Scheduler limits the `/TR` action text, so the platform adapter writes a short private `service-launcher.cmd` under the state root rather than embedding the full Node, package, workspace, state, and logging argv in the task action. The launcher uses CRT-compatible argument quoting, sends stdout/stderr to the normal service logs, exits on a successful daemon exit, and restarts a nonzero exit after five seconds. Task creation is accepted only after a separate state query observes the task. Start, stop, and removal likewise query the Task Scheduler state through fixed PowerShell object properties instead of parsing localized `schtasks` messages; an installed `Ready` task is not mislabeled as currently running.
 
-The Windows trigger is current-user `ONLOGON` with `LIMITED` run level. After a reboot, signing in to that user is sufficient; no terminal command is required. Pre-login operation is intentionally not provided by the default design because it would require a different service-account/credential boundary. 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. A private allowlisted `service-environment.json` preserves `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, matching lowercase forms, optional `ALL_PROXY`, Node proxy selection, and custom-CA path variables. Existing saved values survive an environment-free reinstall, while explicitly supplied values replace case-insensitive prior variants. Values may include proxy credentials, so the file stays in owner-only state and is never returned or logged; status exposes key names only. Re-run `machine-mcp service install` after changing Node installation families, PATH layout, proxy, or CA configuration. Custom Windows state paths used for autostart must also remain within the Task Scheduler path limit and must not contain a literal `%`.
+The Windows trigger is current-user `ONLOGON` with `LIMITED` run level. After a reboot, signing in to that user is sufficient; no terminal command is required. Pre-login operation is intentionally not provided by the default design because it would require a different service-account/credential boundary. 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 current Node/package directories, the operator's inherited absolute PATH entries, and platform defaults. When installation runs through npm, all nested run-script prefixes through the final npm private `node-gyp-bin` marker are discarded; paths belonging to inactive candidate runtimes are also removed. This prevents prerelease activation from persisting source-repository shims or the prior runtime that activation subsequently prunes, while an ordinary user-supplied `node_modules/.bin` remains valid. A private allowlisted `service-environment.json` preserves `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, matching lowercase forms, optional `ALL_PROXY`, Node proxy selection, and custom-CA path variables. Existing saved values survive an environment-free reinstall, while explicitly supplied values replace case-insensitive prior variants. Values may include proxy credentials, so the file stays in owner-only state and is never returned or logged; status exposes key names only. Re-run `machine-mcp service install` after changing Node installation families, PATH layout, proxy, or CA configuration. Custom Windows state paths used for autostart must also remain within the Task Scheduler path limit and must not contain a literal `%`.
 
 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.
 
@@ -208,14 +216,13 @@ Inspect detached jobs even when the MCP host no longer permits execution tools:
 ```sh
 machine-mcp job list
 machine-mcp job inspect JOB_ID
-machine-mcp job approve JOB_ID [--yes]
 machine-mcp job cancel JOB_ID
 machine-mcp job submit plan.json
 ```
 
 Registry changes apply to newly submitted jobs without restarting the daemon. Active jobs use the resource snapshot accepted with their plan.
 
-Policy changes affect new direct submissions. Cancel accepted running jobs explicitly when revoking execution authority. A staged plan launches only after local `job approve`, which is an independent operator authorization. A managed job transitions through `queued`, `running`, `cleaning`, and a terminal status such as `succeeded`, `failed`, or `cancelled`. Cleanup-specific terminal variants report a failed finally phase. If a runner PID dies, the next daemon/job-CLI start marks the job interrupted, removes stale private runtime copies, and runs the finally phase in recovery mode. Automatic recovery is capped at three attempts; persistent failure becomes `recovery_exhausted`.
+Policy changes affect new submissions. Cancel accepted running jobs explicitly when revoking execution authority. A staged plan is a non-running draft and has no terminal promotion path. A trusted owner uses `start_job`; an explicit local operator may submit a reviewed JSON plan with `job submit`. A managed job transitions through `queued`, `running`, `cleaning`, and a terminal status such as `succeeded`, `failed`, or `cancelled`. Cleanup-specific terminal variants report a failed finally phase. If a runner PID dies, the next daemon/job-CLI start marks the job interrupted, removes stale private runtime copies, and runs the finally phase in recovery mode. Automatic recovery is capped at three attempts; persistent failure becomes `recovery_exhausted`.
 
 Use job-scoped `temporary_files` for local helpers. For remote maintenance, prefer `ssh ... sh -s` with the remote script in step `stdin`; this avoids remote temporary scripts. Explicit remote cleanup belongs in idempotent `finally_steps`.
 
@@ -293,40 +300,44 @@ machine-mcp --workspace /path/to/project --profile agent
 
 A remote policy change is saved locally, propagated in the daemon handshake, and loaded by autostart from owner-only state.
 
-### Remote authority and optional delegated-account leases
+### Remote authority and client trust
 
-The saved profile defines the capability ceiling. An authenticated owner account may use that ceiling directly and is never required to approve a pending ID in a terminal. Delegated reviewer, editor, and operator accounts still require bounded leases for consequential remote effects. Inspect their pending requests and active leases with:
+The saved profile defines the daemon capability ceiling. Remote authority additionally requires the authenticated account role, trusted OAuth client binding, current account version and refresh family, and ownership of any long-lived object.
+
+Inspect accounts and trusted clients with:
 
 ```sh
-machine-mcp --workspace /path/to/project approval list
+machine-mcp --workspace /path/to/project account list
+machine-mcp --workspace /path/to/project account clients
 ```
 
-Approve the requested scope for ordinary work, or explicitly open a temporary full automation window:
+Revoke a compromised or stale client independently:
 
 ```sh
-machine-mcp --workspace /path/to/project approval approve APPROVAL_ID --duration 1h
-machine-mcp --workspace /path/to/project approval approve APPROVAL_ID --full
+machine-mcp --workspace /path/to/project account revoke-client CLIENT_ID --yes
 ```
 
-Revoke one lease or all leases:
+Delegated roles cannot be elevated by an approval ID or lease. Legacy version 2 leases may be inspected or removed only for migration cleanup:
 
 ```sh
+machine-mcp --workspace /path/to/project approval list
 machine-mcp --workspace /path/to/project approval revoke LEASE_ID
-machine-mcp --workspace /path/to/project approval clear
+machine-mcp --workspace /path/to/project approval clear --yes
 ```
 
-The pending and lease files are owner-only and contain identity bindings, scope, timestamps, and target digests rather than command or content text. Full details are in [LOCAL_AUTHORIZATION.md](LOCAL_AUTHORIZATION.md).
+The current runtime never consumes legacy leases. Full details are in [LOCAL_AUTHORIZATION.md](LOCAL_AUTHORIZATION.md).
 
 ## Incident response
 
-After suspected credential or client compromise:
+After suspected credential, client, or device compromise:
 
 1. stop foreground and autostart daemons;
-2. run `machine-mcp approval clear` for every affected workspace;
-3. disable or rotate the affected account, or run `machine-mcp rotate-secrets` for deployment-wide revocation;
-4. restart without broad flags and redeploy;
-5. inspect Cloudflare account access, Worker configuration, local state/resource permissions, process-lock owners, managed-job results, and service logs;
-6. cancel active managed jobs and remove compromised resource aliases;
-7. remove the Worker and local state if continued remote access is unnecessary.
+2. revoke the affected OAuth client, or disable/rotate the affected account;
+3. clear any legacy version 2 leases as migration hygiene;
+4. run `machine-mcp rotate-secrets` when device-root or deployment-wide token compromise is possible;
+5. restart with the intended profile, deploy the matching Worker, and reconnect only trusted clients;
+6. inspect Cloudflare access, Worker configuration, device-root provider, audit-chain health, local state/resource permissions, process-lock owners, managed-job results, and service logs;
+7. cancel active managed jobs and remove compromised resource aliases;
+8. remove the Worker and local state if continued remote access is unnecessary.
 
 The detailed 0.12.0 audit record and residual operational limits are in [AUDIT.md](AUDIT.md).

package/docs/OVERVIEW.md

@@ -4,7 +4,7 @@ Machine Bridge is one local authority surface with two MCP transports. The archi
 
 1. **Who may request an operation?** Remote OAuth account/client identity and role, or the local process identity that launched stdio.
 2. **Which tools are exposed?** The shared tool catalog, policy profile, and account-role intersection.
-3. **Is this remote effect currently authorized?** Direct authenticated-owner authority within the daemon ceiling, automatic delegated workspace-safe behavior, or an account/client-bound delegated capability lease.
+3. **Is this remote effect inside the current authority?** The daemon ceiling, account role, trusted client, account version, refresh family, operation invariants, and object owner must all agree.
 4. **What can an authorized tool actually do?** The local runtime, workspace/path rules, operating-system user authority, and platform security controls.
 
 Transport authentication does not create an operating-system sandbox. The local daemon executes with the authority of its OS user.
@@ -15,7 +15,7 @@ Transport authentication does not create an operating-system sandbox. The local
 flowchart LR
   HC[Hosted MCP client] -->|HTTPS + OAuth 2.1 / PKCE| W[Cloudflare Worker]
   W --> DO[Durable Object room]
-  DO -->|P-256 device-authenticated WebSocket| R[LocalRuntime]
+  DO -->|root-certified ephemeral P-256 session| R[LocalRuntime]
 
   LC[Local MCP client] -->|stdio| S[stdio adapter]
   S --> R
@@ -42,9 +42,9 @@ flowchart LR
 
 1. The Worker validates OAuth client, token, account state, role, resource binding, and MCP session state.
 2. The Worker filters advertised tools by account role and the daemon-reported capability ceiling.
-3. The Durable Object relays a bounded tool envelope carrying account and OAuth client identity over the device-authenticated daemon socket.
+3. The Durable Object relays a bounded tool envelope carrying account, account-version, OAuth-client, refresh-family, and role identity over the root-certified ephemeral daemon socket.
 4. The local runtime revalidates account authorization, policy, call lifecycle, timeout, and cancellation.
-5. The local transaction gate directly permits authenticated owner work within the daemon ceiling; delegated accounts receive automatic workspace-safe behavior or require a matching bounded capability lease for a high-impact effect.
+5. The local authority gate permits work only inside the immutable role ceiling. Consequential effects are classified for hard enforcement and audit; they never create a temporary elevation path.
 6. The selected local service executes with the daemon OS user's authority.
 
 The Worker never receives ambient filesystem or process authority. It receives only explicit request/result messages.
@@ -68,7 +68,7 @@ Local and Worker code consume these contracts. Generated references and drift te
 `LocalRuntime` is an orchestrator, not a low-level implementation module. It composes:
 
 - policy and account authorization;
-- authenticated-owner direct authority plus delegated effect classification and local capability leases;
+- request-scoped effective authority, hard role ceilings, operation classification, and principal-bound object ownership;
 - call registration, timeout, cancellation, and observability;
 - workspace and path services;
 - direct and shell process execution;
@@ -82,9 +82,9 @@ Low-level responsibilities remain in focused modules. Architecture tests enforce
 
 ## State and lifecycle
 
-Each canonical workspace has independent profile state, Worker identity, credentials, local capability leases, locks, service metadata, and managed jobs. State mutations use owner-only files where supported, bounded reads, atomic replacement, and process-identity-aware locks.
+Each canonical workspace has independent profile state, Worker identity, trusted clients, account/token state, legacy-lease cleanup state, audit-chain state, locks, service metadata, and managed jobs. State mutations use owner-only files where supported, bounded reads, atomic replacement, and process-identity-aware locks.
 
-The relay distinguishes signed preflight, challenge authentication, readiness probing, and active service. A candidate daemon must prove possession of the enrolled P-256 key and complete an end-to-end probe before replacing an incumbent. Disconnect cancels relay-owned calls and terminates associated local processes.
+The relay distinguishes a root-certified ephemeral session, signed preflight, challenge authentication, readiness probing, and active service. A candidate daemon must prove possession of the certified session key and complete an end-to-end probe before replacing an incumbent. Disconnect cancels relay-owned calls and terminates associated local processes.
 
 Managed jobs use a separate durable lifecycle. Their plans are integrity-bound, runners are process-identity checked, transitions are lock-protected, terminal plans are scrubbed, and recovery is bounded.
 

package/docs/PROJECT_STANDARDS.md

@@ -18,15 +18,19 @@ Branch names use a short category and purpose, for example `feat/browser-downloa
 
 Direct pushes to `main`, force pushes, and branch deletion are blocked by repository protection. An exception requires an incident record and an explicit owner decision.
 
-### Completion ownership and local acceptance
+### Completion ownership, prerelease activation, and soak
 
-Repository automation owns implementation, local validation, observed candidate verification, acceptance recording, and pull-request completion. For every npm-package change, automation generates the exact candidate tarball with `npm run release:candidate` and stops before the first GitHub push. The repository owner explicitly authorizes the live candidate Worker update in the active conversation. The coding agent starts the exact candidate through Machine Bridge with `npm run release:candidate:start -- --allow-worker-deploy`, verifies the deployed Worker version/hash, remote health, relay readiness, connected local version, and representative functionality, then records a passing decision with `npm run release:accept -- --confirm "I VERIFIED machine-bridge-mcp <version> CANDIDATE ON THE OWNER MACHINE AND IT WORKS"`. No owner terminal approval command is part of the standard workflow. Automated checks or an unobserved process are not sufficient evidence.
+Repository automation owns implementation, local validation, candidate preparation, observed verification, acceptance recording, and pull-request completion. Package work for version 3 or later must use a `dev`, `beta`, or `rc` version before stable promotion. Direct implementation-to-stable release is prohibited.
 
-The tracked `release-acceptance/v<version>.json` record binds the observed result to the npm tarball SHA-1 and SHA-512 integrity value. The record is excluded from the package, so a content-preserving squash merge does not invalidate it; any source, executable script, package metadata, or packaged-documentation change produces a different package hash and requires a regenerated candidate and another observed live verification. `npm run github:push`, pull-request CI, and `npm run release` verify the record. Raw direct pushes of release-relevant branches are prohibited.
+`npm run release:candidate` creates the exact tarball. The repository owner executes `npm run release:candidate:activate -- --allow-worker-deploy`; the command installs that tarball under the private state root, updates the same-name Worker, verifies candidate relay readiness, replaces the login daemon, verifies the background handoff, and exits. The coding agent then performs observed live verification through Machine Bridge and records acceptance only after that observed success. No per-operation terminal approval is involved.
 
-After interactive acceptance, repository automation may push only through `npm run github:push`, open and complete the pull request, verify the resulting `main` commit, remove the merged branch, and run `npm run release`. Every npm-package change advances the package version and is completed by an annotated `v<version>` tag plus a final GitHub Release for the exact successful `main` commit. GitHub-only repository infrastructure changes that do not alter npm package contents do not require a synthetic npm version or local runtime acceptance, but they still require review and their applicable CI/security checks.
+The tracked `release-acceptance/v<version>.json` binds npm hashes, a portable package digest, and a version-normalized promotion digest. Any packaged change invalidates acceptance. `npm run github:push`, CI, and source-release commands verify the record. Raw pushes of package branches are prohibited.
 
-The coding agent performs the acceptance-record, tag, and GitHub Release work only after observed live verification and exact-commit checks succeed. npm publication, Worker deployment, credential mutation, non-isolated global installation, and daemon/service replacement remain separate live operations performed by the repository owner.
+The accepted prerelease is released with `npm run prerelease:release`; npm publication remains an explicit owner operation through `npm run prerelease:publish`. The owner installs the exact registry version with `npm run prerelease:install -- --allow-worker-deploy`. Formal soak begins only from this registry-verified activation. Minimum soak is seven days for major, three days for minor, and one day for patch releases. A blocking defect increments the prerelease number and restarts the soak interval.
+
+Stable promotion requires a tracked `release-soak/v<stable>.json` and identical promotion-content digest. Only normalized release metadata may differ from the soaked prerelease. The stable candidate is activated and observed again before `npm run release`; npm stable publication remains an explicit owner operation through `npm run stable:publish`.
+
+GitHub-only repository infrastructure changes that do not alter npm package contents do not require a synthetic version, candidate activation, or soak. They still require review and applicable checks.
 
 ### Local GitHub control plane
 

package/docs/RELEASING.md

@@ -1,124 +1,231 @@
 # Release process
 
-The release invariant is:
+Machine Bridge uses a mandatory prerelease-and-soak process. A release candidate is not a stable release, and a green automated suite is not evidence that a real Worker, daemon, browser extension, service manager, and ordinary client remain healthy over time.
 
-- the repository owner started the exact npm tarball represented by `release-acceptance/v<version>.json` on the maintainer machine, and the coding agent observed the live candidate through Machine Bridge before recording a passing result;
-- the current package produces the same SHA-1 and SHA-512 integrity values as that accepted tarball;
-- `main` points to the release commit, and that exact commit has completed successful push-triggered CI, CodeQL, Governance, and OpenSSF Scorecard runs;
-- `v<package version>` points to that same commit locally and on GitHub;
-- a final GitHub Release exists for the tag and contains the accepted npm tarball;
-- `package.json`, `package-lock.json`, the Worker-reported version, and `browser-extension/manifest.json` (`version`/`version_name`) agree;
-- every npm-package change since the prior version tag has a higher package version and matching CHANGELOG section;
-- the same accepted package content is present on GitHub and in a new npm version.
+The invariant for version 3 and later is:
 
-A green automated suite is necessary but is not evidence that the maintainer's ordinary installation path works. The repository therefore separates automated validation from observed live candidate verification and binds both to the final package bytes.
+1. every package change is first assigned a `dev`, `beta`, or `rc` semantic version;
+2. the exact npm tarball is activated on the owner machine with one command that updates the same-name Worker and persistently replaces the login daemon;
+3. the coding agent verifies the connected candidate through Machine Bridge before recording package acceptance;
+4. the accepted prerelease is published under a non-`latest` npm dist-tag and as a GitHub Prerelease;
+5. the owner installs that exact published prerelease and uses it for the required soak period;
+6. every blocking defect produces a new prerelease version and restarts the soak clock;
+7. stable promotion is allowed only when the packaged functional content matches the soaked prerelease; only synchronized version metadata may differ;
+8. the exact stable commit must pass cross-platform CI, CodeQL, Governance, and OpenSSF Scorecard before the stable tag and final GitHub Release are created.
 
-## Change classification
+## Release channels
 
-A change is **npm-package relevant** when it alters `package.json`, `package-lock.json`, or a path included by the package `files` manifest. Source, runtime scripts, browser extension files, shared contracts, shipped documentation, and package metadata therefore require a new version and local acceptance.
+Supported versions and registry channels are:
 
-A repository-only change under paths such as `.github/` may be merged without a synthetic npm version when the package bytes are unchanged. It still requires review and all applicable GitHub checks. `scripts/release-impact-check.mjs` implements this distinction from the package manifest rather than from a duplicated path list.
+| Version form | npm dist-tag | GitHub release type | Purpose |
+|---|---|---|---|
+| `x.y.z-dev.n` | `dev` | Prerelease | short-lived development integration |
+| `x.y.z-beta.n` | `beta` | Prerelease | normal real-world testing channel |
+| `x.y.z-rc.n` | `next` | Prerelease | optional final candidate after beta |
+| `x.y.z` | `latest` | final release | stable users only |
 
-## Prepare the candidate locally
+Do not assign the final `x.y.z` version while implementation is still under candidate testing. A major or behaviorally risky change normally starts at `beta.1`. A release candidate may use `rc.n` after beta when a final freeze checkpoint is useful.
 
-1. Set the new version without creating a tag. The npm version hook synchronizes the Worker and browser-extension versions:
+Minimum published-prerelease soak periods are:
 
-   ```sh
-   npm version <version> --no-git-tag-version
-   ```
+- major release: seven days;
+- minor release: three days;
+- patch release: one day.
 
-2. Add the matching dated `CHANGELOG.md` section and update affected documentation and audit notes.
-3. Run the required dependency, privacy, Worker, and package checks while iterating.
-4. Inspect the complete diff.
-5. Generate the final candidate:
+These are lower bounds, not automatic approval. Continue the soak when use has been too light to exercise the changed behavior.
 
-   ```sh
-   npm run release:candidate
-   ```
+## 1. Prepare an exact prerelease candidate
 
-`release:candidate` runs the complete repository suite and then writes the exact npm tarball plus a bounded pending manifest under ignored `.release-candidate/`. Do not modify a packaged file after generating the candidate without regenerating and retesting it.
+Complete implementation, tests, documentation, audit notes, and changelog. Set the prerelease version without creating a Git tag:
 
-## Interactive local candidate acceptance
+```sh
+npm version 3.0.0-beta.1 --no-git-tag-version
+```
+
+The version hook synchronizes package metadata, Worker version, and browser-extension metadata.
+
+Run the complete local gate and inspect the diff:
+
+```sh
+npm run check
+npm audit --audit-level=high
+npm audit --omit=dev --audit-level=high
+npm run worker:dry-run
+npm pack --dry-run
+```
 
-The repository owner explicitly authorizes the exact `.release-candidate/*.tgz` artifact and any configured same-name Worker update in the active conversation. The coding agent then runs the candidate startup helper through Machine Bridge:
+Generate the exact tarball:
 
 ```sh
-npm run release:candidate:start -- --allow-worker-deploy
+npm run release:candidate
 ```
 
-The helper verifies the pending tarball hashes, installs it into the ignored `.release-candidate/runtime/` prefix without replacing the normal global installation, updates the configured same-name Worker when its version or deployment hash differs, and starts the installed candidate in the foreground. This is an in-place live candidate deployment, not an isolated staging Worker. The owner does not need to execute a terminal authorization command. The coding agent then verifies at minimum:
+The candidate manifest records npm SHA-1/SHA-512 values and a promotion-content digest. Any packaged-file change invalidates the candidate.
 
-- the remote Worker reports the candidate version and the persisted deployment hash matches the candidate Worker bundle;
-- the remote health route succeeds without redirect;
-- the connected runtime reports the candidate package version;
-- relay readiness is healthy through the deployed Worker for the intended transport;
-- one representative read-only operation succeeds;
-- representative changed functionality succeeds, including browser, application, service, proxy, credential, or platform-specific behavior when relevant.
+## 2. Owner activates the exact candidate
 
-The owner does not run the acceptance command. After the coding agent has observed the live candidate passing those checks, the agent records the decision using the exact phrase printed by `release:candidate`, for example:
+The coding agent must stop and present this command. The repository owner executes it:
 
 ```sh
-npm run release:accept -- --confirm "I VERIFIED machine-bridge-mcp 1.2.9 CANDIDATE ON THE OWNER MACHINE AND IT WORKS"
+npm run release:candidate:activate -- --allow-worker-deploy
 ```
 
-This creates `release-acceptance/v<version>.json` containing package identity, npm tarball hashes, a portable Git-content digest, timestamp, result, and a fixed observed-verification marker. The portable digest is computed with a temporary Git index containing `HEAD` plus the complete working tree; the real staging area is not modified. The record does not store a personal name, machine path, command output, credential, or user content. It is intentionally excluded from the npm package, so adding it does not change the tested tarball.
+The command:
+
+- verifies the exact pending tarball;
+- installs it under the owner-only Machine Bridge state root, separate from the normal global installation;
+- stops only a verified existing service daemon;
+- updates the configured same-name Worker;
+- starts the candidate in-process and verifies device authentication plus relay readiness;
+- installs the candidate as the login service runtime;
+- performs a controlled foreground-to-service handoff;
+- verifies that both the Worker and verified background daemon report the candidate version;
+- exits while the background daemon continues running.
+
+It may request one macOS user-presence or Touch ID operation to certify the daemon session key. It does not ask for per-tool approval.
+
+The private candidate runtime is not stored under the Git checkout, so cleaning `.release-candidate/`, switching branches, or regenerating a candidate cannot delete the daemon currently under test. The previous global installation remains available as recovery information.
+
+## 3. Coding agent verifies the live candidate
+
+After the owner command completes, the coding agent verifies through Machine Bridge:
 
-The command repacks the current tree and refuses to record acceptance if any packaged byte changed after candidate preparation. Automated tests alone, a prepared tarball, a process the agent did not observe, or an ambiguous owner response do not authorize acceptance. Version 1.2.8 owner-recorded acceptance and the 1.2.9 owner-started marker remain supported as historical formats; version 2.0.0 and later require explicit owner authorization plus agent-operated, agent-observed verification.
+- `server_info` reports the exact candidate version;
+- Worker health reports the same version and deployment identity;
+- the connected daemon is the verified login-service process;
+- relay readiness succeeds through the deployed Worker;
+- a representative read succeeds;
+- changed functionality and relevant failure paths succeed;
+- browser, application, proxy, credential, service, and platform-specific behavior are tested when affected;
+- logs contain no sensitive arguments, output, tokens, or raw user paths.
 
-## Push and review
+Only observed live evidence counts. A green unit suite, prepared tarball, unobserved process, or ambiguous response does not count.
 
-Commit the candidate changes and acceptance record, then push the branch only through:
+After successful verification, the coding agent records acceptance using the exact phrase emitted by `release:candidate`:
+
+```sh
+npm run release:accept -- --confirm "I VERIFIED machine-bridge-mcp <version> CANDIDATE ON THE OWNER MACHINE AND IT WORKS"
+```
+
+The resulting `release-acceptance/v<version>.json` binds the exact tarball hashes, portable Git package digest, promotion-content digest, timestamp, and fixed verification marker. It contains no personal machine path, command output, account credential, or user content.
+
+## 4. Review and publish the prerelease
+
+Commit the prerelease changes and acceptance record. Push only through:
 
 ```sh
 npm run github:push
 ```
 
-The command requires a clean non-`main` branch, fetches `origin/main`, paginates all open GitHub issues and pull requests, and refuses to push while an unrelated PR remains open or an issue is not covered by a standard closing keyword in `origin/main..HEAD`. An already-open PR for the current branch is allowed so it can be updated. The command then verifies that the acceptance record is tracked, rebuilds the npm package, compares both hashes, and only then executes a non-force push of the current branch. Direct pushes to `main` remain prohibited. Any packaged-file change after acceptance invalidates the hash and blocks the next push until the owner retests a regenerated candidate.
+Create/update the pull request, satisfy required checks, squash-merge, fetch, and fast-forward local `main`.
 
-Open a pull request, satisfy the required checks, and squash-merge. Pull-request CI repeats the acceptance verification. A content-preserving squash changes the Git commit but not the package bytes, so the accepted hash remains valid.
+Create the annotated prerelease tag, GitHub Prerelease, and exact tarball asset:
 
-## Complete the GitHub source release
+```sh
+npm run prerelease:release
+```
 
-From a clean, fast-forwarded `main` worktree whose `HEAD` exactly equals `origin/main`:
+Publish npm through the repository-controlled channel command:
 
 ```sh
-npm run release
+npm run prerelease:publish
 ```
 
-`npm run release` never pushes `main`. `release:publish` remains a compatibility alias. It verifies the interactive candidate acceptance, runs the complete project and version checks, requires successful exact-commit push runs for CI, CodeQL, Governance, and Scorecard, creates or verifies the annotated version tag, pushes only the version tag when absent, builds the npm tarball, creates or updates the final GitHub Release, uploads the tarball, and verifies the resulting state.
+The command derives `dev`, `beta`, or `next` from the package version. `prepublishOnly` rejects an incorrect or implicit `latest` tag and rechecks the package, GitHub prerelease, exact commit, and candidate acceptance.
 
-To verify an already completed source release without changing anything:
+## 5. Activate the published prerelease and begin soak
+
+From the exact accepted source checkout, the owner runs:
 
 ```sh
-npm run release:check
+npm run prerelease:install -- --allow-worker-deploy
 ```
 
-To create GitHub Release records for historical remote tags that lack releases:
+This command verifies that the npm registry tarball SHA-1/SHA-512 and dist-tag match the locally accepted candidate, installs that exact published version globally, updates the Worker and login daemon, verifies both versions, and writes an owner-only `npm-prerelease` activation record. The formal soak clock starts from this activation record, not from a local unpublished candidate.
+
+Use the prerelease normally. Exercise the changed areas under real workloads. A crash, authorization anomaly, data-loss risk, repeated relay failure, incorrect service lifecycle, significant compatibility regression, or security/privacy defect is blocking.
+
+When a blocking problem is found:
+
+1. fix it on a new branch;
+2. increment `beta.n` or `rc.n`;
+3. regenerate and reactivate the exact candidate;
+4. repeat live verification and prerelease publication;
+5. install the new published prerelease;
+6. restart the full minimum soak interval.
+
+Never edit or replace an already published prerelease version.
+
+## 6. Record successful soak
+
+After the minimum interval and adequate real use, the owner reports that no blocking issue remains. The coding agent records that explicit result with the exact phrase printed by the command, for example:
+
+```sh
+npm run prerelease:soak:accept -- --confirm "I SOAK-TESTED machine-bridge-mcp 3.0.0-beta.1 FOR AT LEAST 7d WITH NO BLOCKING ISSUES"
+```
+
+The command verifies:
+
+- the installed activation came from the published npm prerelease, not a local candidate;
+- the published npm hashes and dist-tag match the accepted tarball;
+- the GitHub release is marked prerelease;
+- the required elapsed time has passed;
+- the promotion-content digest still matches;
+- no blocking issue is recorded.
+
+It writes `release-soak/v<stable-version>.json`. This record is reviewable, contains no private machine path, and is excluded from the npm package.
+
+## 7. Promote to stable
+
+Create a stable-promotion branch. Change only synchronized release metadata from `x.y.z-beta.n` or `x.y.z-rc.n` to `x.y.z`, retain the same functional package content, add the tracked soak record, and update release wording only where it is normalized by the promotion digest.
+
+Any source, runtime, dependency, packaged documentation, script, policy, browser-extension behavior, or Worker behavior change causes `release:soak:verify` to fail. Such a change requires a new prerelease and a new soak period.
+
+Verify the promotion:
 
 ```sh
-npm run release:backfill
+npm run release:soak:verify
+npm run check
+npm run release:candidate
 ```
 
-Backfill is historical metadata repair. It does not retroactively claim that releases predating the 1.2.8 acceptance policy had a recorded local acceptance.
+The owner activates the exact stable candidate with the same persistent command:
 
-## Publish npm
+```sh
+npm run release:candidate:activate -- --allow-worker-deploy
+```
 
-Only after `release:check` succeeds:
+The coding agent verifies the live stable candidate and records its exact acceptance. Then commit, push with `npm run github:push`, merge, and run:
 
 ```sh
-npm publish --access public
+npm run release
+npm run stable:publish
 ```
 
-`prepublishOnly` repeats the complete checks and GitHub synchronization check. npm publication remains a deliberate release-operator action and is not authorized by an ordinary source change.
+`npm run release` creates the final annotated tag and GitHub Release only after the soak record, promotion digest, exact candidate acceptance, exact `origin/main`, and all required push-triggered checks pass. `stable:publish` always uses `latest` and repeats the same gates.
+
+## Rollback and recovery
+
+Candidate and prerelease activation retain the previous global installation metadata, but rollback across a state or protocol migration is not assumed safe. If activation fails:
+
+- preserve the state root and service logs;
+- do not delete locks or edit versions by hand;
+- inspect `machine-mcp service status`, `machine-mcp status`, and `machine-mcp doctor` using the intended runtime;
+- fix forward when Worker/state protocol has changed;
+- restore a complete pre-upgrade backup only when package, Worker, browser extension, service definition, and local state can be restored as one unit.
+
+The activation state machine verifies candidate relay readiness before service handoff and cleans up its temporary runtime and locks on installation failure. A failure after the Worker has changed is reported explicitly rather than hidden by an unsafe automatic downgrade.
 
-## Authentication and external controls
+## External credentials and controls
 
-Required local access:
+Live npm publication, global installation, and Worker/service replacement require explicit owner authorization. Repository automation does not infer that authorization from a version change.
 
-- Git push access to `origin` for the accepted branch and version tag;
-- an authenticated GitHub CLI session with pull-request and release permission;
-- an npm account that owns the package or has maintainer permission for the separate registry publication step.
+Required external controls remain:
 
-GitHub Actions remains a required cross-platform boundary. Missing, pending, cancelled, skipped, failed, pull-request-only, stale, or wrong-commit runs do not satisfy release publication. Observed local candidate acceptance and successful GitHub checks are complementary evidence; neither substitutes for the other.
+- authenticated local `git`/`gh` access;
+- npm package-owner or maintainer access;
+- Cloudflare account protection;
+- successful exact-commit CI, CodeQL, Governance, and Scorecard;
+- protected npm publication credentials or trusted publishing when configured.
 
-The preferred registry target remains npm trusted publishing from a narrowly scoped GitHub Actions workflow using OIDC and a protected GitHub environment. Enabling it requires package-owner configuration in npm and a reviewed workflow change. Until then, never place an npm token in repository files, workflow YAML, logs, local acceptance records, or project notes.
+Never place npm, GitHub, Cloudflare, OAuth, account, or device credentials in source files, workflow YAML, acceptance/soak records, logs, screenshots, or project notes.