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

package/docs/UPGRADING.md

@@ -1,38 +1,98 @@
 # Upgrading
 
+This file defines the **currently supported upgrade path only**. Older version notes in the repository are historical migration records, not a declaration of the current candidate. Historical prerelease migrations and blocked-candidate details belong in [CHANGELOG.md](../CHANGELOG.md) and [AUDIT.md](AUDIT.md), not in the live upgrade contract.
+
 ## Supported upgrade contract
 
-Machine Bridge does not retain parallel implementations for obsolete MCP protocol dates, policy revisions, state schemas, lock formats, or browser-extension protocols. The supported path is a direct upgrade from the immediately preceding published package while its state already uses the current schema.
+Machine Bridge supports direct upgrade from the immediately preceding published release. The repository may also need one bounded transition from the exact live owner-machine candidate named in the current changelog. Obsolete MCP transports, protocol sessions, replay stores, authorization workflows, and alternate runtime implementations are not retained as hidden compatibility paths.
+
+Version 3 is a coordinated Worker, daemon, CLI, and browser-extension system. Components are expected to converge on the same exact package version before an upgrade is considered healthy. Mixed 2.x/3.x operation is unsupported. MCP `2026-07-28` remains the only native request-scoped state model; remote HTTP has one bounded, stateless initialization-compatibility surface for `2025-06-18` and `2025-11-25` hosts, and that surface must not be confused with mixed-version daemon/Worker operation or restoration of the removed session/replay model.
+
+State migration is different from protocol compatibility. A narrowly bounded reader may still be required when valid state produced by the immediately preceding/live version must be transformed in place without deleting user credentials or creating split-brain ownership. Such migration must be one-way, fail closed on ambiguous state, and must not recreate the removed runtime behavior. beta.61's OAuth refresh persistence is one such forward migration: legacy schema-2/schema-3 main values are reconstructed in memory, consumed replay markers are moved into bounded hash shards, and the main value plus shards are committed atomically. An older runtime is not a supported reader for that migrated state; formal rollback therefore restores the complete pre-upgrade state-root backup together with the prior package, Worker, service definition, and browser extension as described below.
+
+## Historical beta.61 migration invariant retained by current readers
+
+This section records the origin of one persisted-state compatibility boundary; **beta.61 is not the current upgrade target**. During the beta.60 → beta.61 transition, the machine-user resource transaction lock established the wire shape that later runtimes may still need to recognize when migrating valid persisted state:
+
+- beta.60 used `transaction.lock/` plus `owner.json` as the cross-process mutex;
+- beta.61 deliberately kept that directory wire shape while beta.60 could still be live, so the final-name `mkdir` remained the cross-version atomic exclusion point;
+- an incomplete directory generation was not reclaimed until the bounded orphan grace elapsed and the exact filesystem generation was revalidated;
+- beta.61 also accepted the short-lived regular-file lock generation created by an earlier beta.61 implementation during that candidate cycle;
+- do **not** delete, rename, or hand-edit `transaction.lock` to force progress. Let the owner-identity and stale-recovery checks converge or stop and inspect the state.
+
+The historical channel/version snapshot that justified those migration readers belongs in the changelog and audit history, not in this live upgrade contract. Current code may retain only the bounded readers still required to consume reachable persisted state; those readers are one-way and do not make the producing runtime or protocol executable again. Do not infer support for arbitrary historical prerelease state from the presence of a migration parser, and do not treat this historical section as permission for mixed-version Worker/daemon operation.
+
+Existing browser pairing and OAuth state should be left in place. Machine Bridge rotates or normalizes supported persisted state when the relevant subsystem is first used and fails closed when the stored state cannot be validated. Do not delete pairing or OAuth state merely to make an upgrade succeed; doing so can force unnecessary re-pairing or reauthorization and can hide an ownership problem that should be diagnosed.
+
+## MCP client transition
+
+Machine Bridge uses MCP `2026-07-28` as its native protocol. Remote HTTP additionally accepts stateless initialization-era compatibility for `2025-06-18` and `2025-11-25` so hosted clients can negotiate without reviving the removed session/replay architecture. stdio remains current-only.
 
-Version 2.0.0 is a coordinated Worker/daemon security-protocol upgrade. It replaces the long-lived daemon bearer with a P-256 device identity, replaces network account-administration bearer requests with per-request HMAC signatures, shortens OAuth access tokens, introduces refresh-token families and replay revocation, and adds local capability leases for high-impact remote effects. The Worker and daemon must converge on 2.0.0 together; the removed daemon bearer protocol is not retained as a fallback.
+Current/native clients must:
 
-On the first 2.0.0 state load, a workspace without a device identity generates one locally, removes the legacy daemon secret, and rotates the deployment-wide OAuth token version. Existing pre-2.0 access and refresh credentials therefore fail closed and every client must authorize again. The device private JWK remains in owner-only local state; only the public JWK is deployed to the Worker. Subsequent ordinary starts preserve both the device identity and token version.
+- send `io.modelcontextprotocol/protocolVersion: "2026-07-28"` and `io.modelcontextprotocol/clientCapabilities` in every request `_meta`;
+- use `server/discover` instead of `initialize`;
+- include both `application/json` and `text/event-stream` in HTTP `Accept`;
+- send the required `MCP-Protocol-Version`, `Mcp-Method`, and applicable `Mcp-Name` / `Mcp-Param-*` headers on HTTP requests;
+- treat each HTTP response stream as request-scoped and cancelled when the public stream is closed;
+- use explicit `session_bootstrap` / `resolve_task_capabilities` calls when refreshed project or routing context is needed;
+- not use `Mcp-Session-Id`, recovery `GET /mcp`, SSE event IDs, `Last-Event-ID`, or protocol-session replay.
 
-The canonical `full` profile is unchanged as a capability ceiling. Authenticated owner operations use that ceiling directly without terminal approval. High-impact operations from delegated non-owner accounts require a local account/client-bound lease, while their normal workspace-contained reads and edits and project inspection remain automatic. Because the packaged extension controls an existing browser profile, one `browser-session` lease covers profile reads and actions; registered-resource input or file upload uses the separate `data-export` scope. An operator may approve the requested scope or explicitly open a temporary `full` window for at most eight hours. Lease state is independent of the policy profile and does not migrate into OAuth credentials.
+For remote HTTP only, a `2025-06-18` or `2025-11-25` `initialize` may receive a bounded stateless compatibility response. After that response, the compatibility surface accepts only `notifications/initialized`, `ping`, `tools/list`, and `tools/call`; tool methods execute through the current controller and no initialization-owned session is retained. `Mcp-Session-Id`, recovery `GET /mcp`, SSE event IDs, `Last-Event-ID`, and protocol-session replay remain rejected. An initialize request outside the two declared compatibility dates, a removed session marker, or any other removed method receives bounded rejection/upgrade guidance and cannot reconstruct old state.
 
-Version 1.2.0 could accept prototype-shaped account roles through malformed administration input. On the first 1.2.1 or later Worker access, such an account is preserved for recovery but repaired fail-closed: its role becomes `reviewer`, it is disabled, its account version advances, and its authorization codes and tokens are removed. An operator can then assign a valid role, enable the account, and rotate its password through the normal account administration flow. A local policy record with an unknown profile label is normalized to `custom` while retaining its explicit capability fields; an invalid explicit `--profile` is rejected.
+Unknown/future protocol versions are also rejected. Machine Bridge does not guess that a newer client is wire-compatible with the current server.
 
-A state file from an older unsupported schema is rejected rather than guessed or silently rewritten. Upgrade an old installation through the last release that understands its schema, or initialize a new workspace and re-register resources. Do not edit schema numbers by hand.
+The tool catalog is enforced with bounded schema validation at the Worker and local runtime boundaries. Requests with unknown fields, wrong scalar types, fractional integer values, out-of-range values, malformed metadata, or mismatched mirrored headers fail before tool side effects. Fix the request rather than retrying it unchanged.
 
 ## Normal upgrade
 
-1. Finish or cancel ordinary interactive process sessions. Accepted managed jobs may continue independently, but inspect them before replacing the daemon.
-2. Install the new package with the pinned npm procedure in [Getting started](GETTING_STARTED.md).
-3. Run `machine-mcp doctor`.
-4. Start `machine-mcp` normally in the foreground for each workspace. Startup generates the device identity if needed, rotates the old deployment token version, deploys the matching public key and 2.0.0 Worker, verifies end-to-end readiness, and only then may replace the prior service daemon.
-5. Reauthorize every remote MCP client. Pre-2.0 access and refresh tokens are intentionally invalid.
-6. Reload the unpacked browser extension. Protocol and packaged-version equality are mandatory; an old extension cannot replace a working compatible connection.
-7. Exercise one safe read and one high-impact operation. Approve the resulting scope or an explicit temporary `--full` window through the local CLI, then retry the operation.
-8. Restore or reinstall background service operation only after the foreground path is healthy.
+1. Inspect interactive process sessions and managed jobs. Cancel work that should not survive daemon replacement; durable managed jobs that are intentionally left running keep their own persisted lifecycle.
+2. Back up the owner-only Machine Bridge state with an operating-system tool that preserves permissions. Do not upload or publish that backup.
+3. Install the new package through the supported package/release channel.
+4. Run `machine-mcp doctor` and resolve state, toolchain, service-owner, or network errors before forcing any mutation.
+5. Start the target workspace in the foreground so the package can verify/deploy the matching Worker and complete end-to-end daemon readiness.
+6. Reconnect hosted MCP clients. Remote HTTP clients still using one of the two declared stateless initialization compatibility dates may continue through that bounded adapter, but clients requiring session/replay semantics must upgrade. Complete OAuth authorization again only when the current authorization state requires it.
+7. Reload the packaged browser extension from the same path reported by `browser status` so its protocol/version handshake matches the daemon. Local release candidates publish into a stable owner-only release-channel directory before old candidate runtimes are pruned. If the extension was originally loaded from a beta.72-or-earlier versioned candidate-runtime directory, perform one **Load unpacked** migration to the current `extension_path`, then use Reload for later upgrades. If pairing migration reports that an older broker still owns the migrated port, restart the prior Machine Bridge runtime rather than starting a second broker on another port.
+8. Verify a safe workspace read, one ordinary edit, one representative current MCP tool call, and one owner-only action appropriate for the deployment.
+9. Restore persistent/background service operation only after the foreground path is healthy.
+
+When `MBM_MACOS_TRUST_BROKER` is intentionally configured, verify that provisioned broker before activation. Do not replace failed trust material with an ad-hoc helper or hand-edit the device-root state.
+
+## Verification
+
+After upgrade, `server_info` should show or allow you to establish:
+
+- exact Worker and daemon version convergence;
+- end-to-end relay readiness with one verified ready daemon for the workspace;
+- the authenticated account role and effective policy/tool intersection;
+- healthy pending-call and relay capacity without detached work left beyond its bounded reconnect window;
+- current device-authentication and OAuth state;
+- healthy local security-audit and managed-job state where those subsystems are enabled.
+
+`server/discover` should advertise only `2026-07-28`. A full daemon policy is not proof that a delegated account has full authority; use `authorization.effective_policy` and `authorization.effective_tools` for the current request.
+
+For a source-release candidate, follow [RELEASING.md](RELEASING.md). Candidate generation, owner activation, soak acceptance, npm publication, and stable promotion have separate evidence gates; a later healthy service does not retroactively turn a failed activation command into valid release evidence.
 
 ## Upgrade safety
 
-Before replacing live software, copy the owner-only state directory using operating-system tools that preserve permissions. Do not publish or attach that backup: it contains credentials and private resource metadata.
+Machine Bridge rejects unreadable, malformed, foreign-schema, symbolic-link, hard-link, ownership-ambiguous, or generation-ambiguous control state rather than silently creating replacement authority.
+
+Do not solve an upgrade failure by deleting state, rotating credentials, copying selected state files between workspaces, editing schema/version fields, or running an older daemon against a newer Worker. Preserve the evidence and diagnose the failing boundary.
+
+Worker deployment records upload success separately from health convergence. A successful upload is not enough: the matching daemon must authenticate and reach end-to-end readiness. Likewise, service-manager PID/activity is not a substitute for verified Machine Bridge readiness.
 
-Machine Bridge never treats an unreadable or foreign-schema state file as empty state. It also records a successful Worker upload before secondary health verification, so a network or proxy failure after deployment does not trigger an uncontrolled repeated write.
+Execution continuity and client delivery continuity are separate. A brief relay interruption may rebind an already-dispatched call to the same daemon instance and may retain an unacknowledged completed result in daemon memory for the bounded reconnect window. This is not an MCP replay promise. Work that must survive daemon/process/machine replacement belongs in the managed-job subsystem.
 
 ## Rollback
 
-Rollback is supported only from a complete pre-upgrade backup. Version 2.0.0 changes Worker/daemon authentication, OAuth refresh state, administration authentication, and local credential material. An older package cannot use the new device protocol or refresh-family state. Rolling back package files alone therefore produces an unavailable or incorrectly authenticated mixed system. Restore the complete owner-only profile backup, prior Worker secret set/build, package version, service definition, and browser extension as one unit, or fix forward.
+Rollback is supported only as a complete unit from a verified pre-upgrade backup.
+
+A rollback must restore together:
+
+- the complete prior owner-only state root;
+- the prior package;
+- the prior Worker build and secrets;
+- the prior service definition;
+- the prior browser extension.
 
-Never roll back by copying only selected state files or changing version fields. Restore one complete verified state backup, package version, Worker build, and browser extension as a single operational unit.
+Do not roll back by editing version/schema fields, copying selected credential files, or restoring only the Worker. If a complete consistent backup is unavailable, prefer diagnosing and fixing forward rather than manufacturing a mixed-version system.