machine-bridge-mcp 3.0.0-beta.21 → 3.0.0-beta.26

package/docs/TESTING.md

@@ -24,17 +24,29 @@ The suite includes:
 - GitHub backlog enforcement that paginates all open issues and pull requests, permits only the current branch PR, and requires standard closing keywords for every open issue before a guarded push;
 - release-impact enforcement requiring a new package version and CHANGELOG section for release-relevant changes;
 - strict dev/beta/rc/stable channel parsing and npm dist-tag enforcement;
-- persistent candidate relay/service handoff ordering, early-failure provider restoration after lock cleanup, and aggregated restoration failures;
+- persistent candidate relay/service handoff ordering; machine-service-before-startup lock acquisition and release; POSIX, XDG, and Windows separation of the ordinary profile state root from the machine-service control root; service-stop, ambiguous provider-state, and pre-mutation foreground/daemon-owner refusal; pending/committed machine-owner transactions; missing, corrupt, mismatched, and partial owner state; token-protected one-way daemon readiness; first-attempt device-authentication rejection; exactly one same-name/same-identity repair deployment; bounded repeated rejection; exact-version/entrypoint pre-remote provider restoration; post-remote compatible-service forward recovery; and aggregated cleanup/restoration failures;
 - owner-only local and registry prerelease activation records;
 - npm/GitHub prerelease metadata validation, minimum soak timing, blocking-issue rejection, and stable-promotion content/file-mode identity;
 - release-state diagnostics distinguishing missing local/remote version tags from tags that point to the wrong commit, plus a release-CI gate that rejects missing, pending, failed, pull-request-only, stale, or wrong-commit runs;
+- GitHub publication ownership: missing confirmation, non-TTY/background invocation, concurrent live owner, stale lock reclamation, and lock release after success/failure; remote tag/Release mutation remains outside ordinary automated tests;
 - generated Cloudflare Worker types under ignored `.wrangler/` state and strict TypeScript checking, including unused-local and unused-parameter rejection; packaging rejects generated declarations;
 - Conventional Commit title validation, shared Markdown escaping regression coverage, and generated MCP tool-reference drift detection;
+- phase-labelled local self-tests with scheduler-tolerant process/CLI success-path and convergence budgets, while explicit timeout/cancellation fixtures retain short deadlines, so failures identify the runtime, state, daemon takeover, CLI, service, shell, or Worker-source boundary;
 - direct tests for shared project-metadata reads, strict integer normalization, plain-record classification, and canonical profile/Worker/job/lock inventory;
 - recursive syntax validation for every JavaScript file under the shipped/runtime/test roots plus the shell wrapper;
 - shared tool-catalog schema, annotation, and profile-inventory checks;
-- default working-agreement injection without user files, bounded automatic project metadata, script-body non-disclosure, user-global opt-out, repository opt-out rejection, global `model_instructions_file` injection in stdio/remote initialization, hierarchical precedence, `.agents/skills` and `.codex/skills` compatibility discovery, live project/skill rescanning and fingerprints, automatic task ranking/loading with English inflection normalization, bounded Chinese/English intent aliases, capability-name weighting, and selected-skill instruction loading; automatic `package.*` commands with English/Chinese workflow-intent matching and Windows command-shim execution, explicit command override/removal, direct argv handling, timeout ceilings, runtime-keyed routing-telemetry privacy, and execution-profile denial;
+- default working-agreement injection without user files, bounded automatic project metadata, script-body non-disclosure, user-global opt-out, repository opt-out rejection, global `model_instructions_file` injection in stdio/remote initialization, hierarchical precedence, `.agents/skills` and `.codex/skills` compatibility discovery, live project/skill rescanning and fingerprints, conditional static-context omission through `known_refresh_fingerprint`, automatic task ranking/loading with English inflection normalization, bounded Chinese/English intent aliases, capability-name weighting, and selected-skill instruction loading; automatic `package.*` commands with English/Chinese workflow-intent matching and Windows command-shim execution, explicit command override/removal, direct argv handling, timeout ceilings, bilingual set-level route regression across Bash, commands, sessions, jobs, files/Git, browser, applications, resources, and diagnostics, effective-role filtering of application/browser/shell metadata, route ambiguity/fallback bounds, runtime-keyed routing-telemetry privacy, and execution-profile denial;
 - concurrent complete-before-visible lock claims, atomic replacement under active readers, malformed-lock grace, snapshot/token-safe reclamation, absolute-age expiry, PID-reuse detection, bounded startup-lock waiting, and wall-clock rollback injection proving duration deadlines remain monotonic;
+- managed-job timeout-tree fixtures with an explicit descendant-PID readiness checkpoint before timeout and cleanup assertions, preventing scheduler delay from being misclassified as a missing cleanup target;
+- managed-job non-timing approval, resource validation/redaction, output, discard, and cleanup/recovery steps with a named 120-second success budget; the aggregate-output proof uses four steps with a 600-second observer, while the managed-job tree fixture uses a 180-second timeout and 150-second descendant-readiness window; timeout/tree-kill and cancellation remain independent semantic tests;
+- deterministic child-settlement coverage for delayed `exit`/`close` delivery, including POSIX zombie detection and recovery of the real exit code without weakening genuine timeout/tree-kill semantics;
+- ordinary managed-job terminal observation uses 480 seconds, exceeding the longest three-phase 3×120-second fixture plan plus startup margin without changing production timeout semantics;
+- managed-job CLI list/inspect/submit/read success and rejection fixtures with a distinct 120-second subprocess budget plus structured status/signal/error diagnostics; explicit job-step timeout and cancellation contracts remain independently short;
+- local-self managed-job CLI subprocesses explicitly clear `NODE_V8_COVERAGE`; the top-level local-self remains instrumented, while dedicated CLI-entrypoint and managed-job fixtures provide the gated module evidence without recursive profiler startup;
+- shell timeout-tree fixtures with a separate descendant-PID readiness checkpoint and bounded coverage-tolerant timeout/exit windows, while a distinct 50 ms fixture preserves direct timeout classification coverage;
+- direct argv isolation success coverage with a named 30-second process budget, separate from short timeout fixtures, so scheduler delay cannot masquerade as shell interpretation or process-tracking failure;
+- maintenance-lock contention with an explicit child-ready checkpoint and parent-controlled release handshake, including pipe-close cleanup, rather than a short time-based holder that can expire before delayed assertions execute;
+- atomic exclusive-file creation with four simultaneously released Node processes, proving exactly one complete winner and only expected `EEXIST` losers without using a twelve-process cold-start stress test as a proxy for correctness;
 - foreground takeover of active and orphaned background daemons with current service-lock metadata, foreground-process protection, bounded final lock-handoff retry, actual-PID exit waiting, POSIX non-escalating timeout behavior, Windows verified-daemon stop semantics, daemon lock mode/version/process-start metadata, launchd service-target semantics, and silent idempotent duplicate service starts; daemon fixture subprocesses intentionally do not inherit V8 coverage because their purpose is ownership timing rather than code measurement;
 - fail-closed service lifecycle ordering for provider-stop, all-workspace daemon-stop, and definition removal, including platform/daemon/removal failure injection and normalized macOS/systemd/Windows results; service-PATH coverage reproduces two nested npm run-script prefixes plus a stale prior candidate runtime and proves the current Node/runtime and inherited user tools remain while npm-private and inactive-runtime entries are removed; Windows coverage reproduces an inline `/TR` command above 262 characters, proves the short launcher action remains bounded, verifies least-privilege logon registration, restart/log routing, language-independent `Ready`/`Running` observation, and state-observed stop/removal despite localized nonzero command output;
 - private service-environment capture/load coverage for exact allowlisting, value bounds and control-character rejection, non-proxy secret exclusion, runtime-value precedence, Windows case-insensitive replacement, explicit empty-value clearing, and preservation across a later environment-free startup;
@@ -53,8 +65,9 @@ The suite includes:
 - fixed internal command execution with validated argv, no shell, isolated HOME/temp/cache, bounded output/deadlines, and ordinary cancellation/process tracking while arbitrary delegated process tools remain sandbox-gated;
 - author-email privacy in `git_log`;
 - isolated command HOME/temp/cache behavior;
-- one-shot timeout, descendant process-group/tree termination including descendants that ignore graceful shutdown after the direct child has already exited, post-`SIGTERM` ownership refresh, targeted PID identity fallback when full process-table inspection is unavailable, PID-reuse denial, repeated leak checks, cancellation, and process-session interaction;
-- layered fixed runtime diagnostics for filesystem, direct process, shell, managed-job storage, and resource availability; machine-readable execution guardrails that must keep CPU, memory, and network isolation marked unenforced unless an actual OS boundary is added;
+- one-shot timeout, descendant process-group/tree termination including descendants that ignore graceful shutdown after the direct child has already exited, post-`SIGTERM` ownership refresh, one shared monotonic budget across full and targeted ownership probes, observation deadlines derived from the exported graceful-termination and ownership-budget constants with bounded scheduling margin, a real uncooperative-child regression proving hard `spawnSync` timeout termination, synchronous smoke/self-test timeout hard termination, targeted PID identity fallback when full process-table inspection is unavailable, empty-snapshot fail-closed behavior, exact start-time/PID-reuse denial, deterministic `close`/post-`exit` fallback races, managed-job terminal persistence and runner exit, repeated leak checks, cancellation, and process-session interaction;
+- layered fixed runtime diagnostics for filesystem, direct process, shell, managed-job storage, and resource availability, with a separate bounded 30-second process/shell health budget rather than reuse of user-command or short timeout-test deadlines; machine-readable execution guardrails that must keep CPU, memory, and network isolation marked unenforced unless an actual OS boundary is added;
+- Git operation setup under scheduler contention: runtime Git success fixtures and the fail-closed read-only repository-root probe use a bounded 30-second metadata budget, avoiding a hidden 10-second subdeadline beneath 30-60 second status/log/diff/show operations;
 - local resource CLI registration, permission checks, dynamic reload, state-path redaction, content non-disclosure, and the extracted runtime-resource boundary for bounded binary/UTF-8 reads plus generation authorization;
 - real Ed25519 and RSA generation, idempotent reuse, public/private correspondence, mode enforcement, incomplete/mismatched/symlink rejection, and private-content non-disclosure;
 - real-machine canonical-full sandbox acceptance for outside-workspace I/O, direct/shell execution, full environment inheritance, SSH prerequisites, temporary authorized-key writing, and detached cleanup without external state changes;
@@ -69,7 +82,7 @@ The suite includes:
 - shared no-follow bounded-file reads for normal files, over-limit data, directories, and symbolic links;
 - owner-only directory enforcement rejecting final symlinks, failing closed on POSIX chmod errors, verifying `0700`, and retaining Windows portability; Worker temporary-secret lifecycle coverage for process-start-bound names, valid stale-owner reclamation, ambiguous-owner retention, `0600` mode, deletion failures, and simultaneous deployment/cleanup failures;
 - SARIF security-gate behavior for unknown findings, exact accepted rule/path matches, path mismatch rejection, rationale quality, and exception expiry;
-- deterministic property tests over hostile browser-protocol byte strings, canonical/custom policy combinations, argv bounds/NULs, and a real direct process proving shell metacharacters remain literal argv;
+- deterministic property tests over hostile browser-protocol byte strings, canonical/custom policy combinations, argv bounds/NULs, and a real direct process proving shell metacharacters remain literal argv; process-tree tests also assert Darwin uses a target-PGID `ps` query, preserve the global inspection budget, and repeatedly prove anti-`SIGTERM` descendants exit after foreground timeout;
 - prototype-shaped command, action, role, profile, form-field, keyboard, and resource names proving that inherited object properties are never interpreted as dispatch or authority; current-schema malformed OAuth roles are repaired to disabled reviewer accounts with credential revocation;
 - canonical Worker deployment URL extraction proving unrelated `/mcp`, `/healthz`, path-bearing, and wrong-name URLs cannot be persisted as upload evidence;
 - byte-exact UTF-8 DOM-source truncation across emoji and Chinese partial-code-point boundaries, including equality between the reported byte count and the encoded returned source;
@@ -80,7 +93,7 @@ The suite includes:
 - P-256 root generation, root-certified ephemeral session issuance, macOS trust-broker build/signature checks, signed WebSocket preflight, one-time transactional nonce consumption, challenge transcript binding, wrong-root/session/tamper/expiry/replay rejection, and prevention of unauthenticated candidate churn;
 - request-scoped effective authority and catalog-wide risk review; non-escalatable reviewer/editor/operator ceilings; authenticated-owner direct execution; control-plane root denial; external and sensitive path composition; persistence-target rejection; symbolic-link ancestor and patch-move canonicalization; owner-only browser/application/data-export and persistent-plan effects; account/client/refresh-family ownership of processes, output sessions, and jobs; delegated sandbox fail-closed behavior; legacy-lease non-consumption; and malformed-record rejection;
 - root-certified ephemeral P-256 account-administration requests with origin/method/path/body/key/time/nonce binding, transactional one-time nonce consumption, removal of the long-lived administration secret, certificate/signature/body tamper rejection, nonce replay rejection, malformed nonce-state fail-closed behavior, one-megabyte response bounds, immediate oversized-response cancellation, and strict successful JSON-object validation;
-- live local Worker OAuth registration, the unauthenticated `resource_metadata` challenge, protected-resource and authorization-server discovery, Streamable transport metadata, consent, URL-constructed `303` callbacks including the ChatGPT and hosted Claude redirect URIs with encoded state, PKCE, `offline_access`, form-encoded authorization-code and refresh-token exchanges, fifteen-minute access tokens, trusted single-account client binding, optional DPoP proof and token-family binding, unsupported critical-header rejection, proof-verification non-consumption, post-authorization replay consumption, invalid-grant cache-exhaustion resistance, independent client revocation, refresh-family idle/absolute limits, bounded consumed-token/revoked-family replay state, record-level schema validation, access/refresh rotation, idempotent identity-equivalent concurrent refresh recovery with identical replacement credentials and expiration, retry-budget throttling, post-grace replay with whole-family access/refresh revocation, account-version refresh revocation, authorization-code replay rejection, pending-registration throttling that excludes already authorized DCR clients, exact built-in ChatGPT/Grok browser origins, additive custom origins, unrelated-origin preflight rejection, no CORS response sharing for unrelated or opaque origins, opaque-origin authorization-form routing, exact per-request redirect-origin CSP with narrowly scoped Microsoft regional-consent and final Copilot Studio handoff exceptions, accessible credential-error rendering, protocol negotiation, HMAC-bound MCP session issuance, SSE content negotiation including `q=0`, immediate stream priming, keepalive and terminal-event framing, HTTP abort without implicit cancellation, explicit cancellation after response disconnect, shared Worker/local timeout ceilings, two-session same-id concurrency, sessionless same-id independence, session-scoped cancellation isolation, same-session duplicate rejection, daemon-backed session bootstrap, dynamic tool advertisement, rich content, candidate/probing/ready transitions, invalid readiness-result rejection, incumbent preservation until verified handover, daemon replacement, cancellation, malformed daemon JSON/non-object rejection, duplicate hello rejection, and unknown-message closure. The metadata/refresh contract is the path used by Claude DCR and Copilot Studio Dynamic discovery. The same integration runs an `editor` account against a canonical `full` daemon and proves that `server_info` and remote `project_overview` report effective `edit` authority while retaining the full daemon ceiling only in explicitly scoped fields.
+- live local Worker OAuth registration and authorization metadata; PKCE, DCR, refresh rotation/replay, account/client/family revocation, DPoP, actual `/mcp` Origin checks, bounded CORS/CSP, exact callback handling, and bounded OAuth persistence; modern MCP `2026-07-28` per-request `_meta`, open-JSON structural budgets, bounded resource subscriptions, strict dual-media `Accept` quality values, mirrored header/body validation, `server/discover`, result identity, cache hints, same-token/same-request-ID concurrency, role-hidden/unknown/schema `-32602` non-dispatch, credential-free private cancellation (including public-header forgery and DPoP replay controls), request-scoped streaming, filtered `subscriptions/listen`, removed-method 404 behavior, and no session/replay leakage; plus the complete legacy MCP `2025-11-25` initialize, pre-persistence raw-argument validation, signed-session cancellation, sequence event, recovery GET, `Last-Event-ID`, duplicate-domain, and replay-isolation suite. The same integration covers shared Worker/local timeout ceilings, daemon candidate/probing/ready replacement, malformed daemon messages, rich content, account-role projection, and stable catalog behavior before/during/after daemon availability.
 - local runtime proof that one blocked tool handler does not serialize an independent handler, plus relay fault injection proving an undeliverable terminal result interrupts the ambiguous socket and enters reconnect backoff.
 - a real headless-Chrome OAuth navigation regression with four cases: `form-action 'self'` blocks the first cross-origin callback, allowing only the registered callback blocks the regional redirect, allowing the registered and regional callbacks blocks the final Copilot Studio redirect, and the complete policy preserves `code` and `state` through all three cross-origin hops. Linux CI fails if Chrome is unavailable; other environments skip only this browser executable check while retaining the Worker CSP assertions.
 
@@ -106,11 +119,14 @@ For deterministic release validation, perform an isolated-profile smoke test wit
 
 ## Critical-module coverage gate
 
-`npm run coverage:test` runs selected in-process and lightweight entrypoint fixtures under V8 coverage and enforces per-module function and branch baselines. The measured set includes policy, typed errors, call registration, execution middleware, lifecycle/observability, logging, Runtime/CLI orchestration, state persistence, relay lifecycle, managed-job lifecycle/runner/storage/projection, browser broker/direct-request/runtime-client routing and loopback upgrade handling, the independently injected service CLI adapter, Agent configuration/projection/skill discovery and bounded text reads, capability ranking, runtime path redaction, browser protocol/operation boundaries, runtime reporting/diagnostics/capability composition, and Worker OAuth state/authorization-page/pending/policy/error/JSON-RPC/WebSocket protocol modules. The full stdio and workerd OAuth/MCP integration still runs separately.
+`npm run coverage:test` runs selected in-process and lightweight entrypoint fixtures under V8 coverage and enforces per-module function and branch baselines. The measured set includes policy, typed errors, call registration, bounded child-process settlement, execution middleware, lifecycle/observability, logging, Runtime/CLI orchestration, persistent candidate activation, state persistence, relay lifecycle, managed-job lifecycle/runner/storage/projection, browser broker/direct-request/runtime-client routing and loopback upgrade handling, the independently injected service CLI adapter, Agent configuration/projection/skill discovery and bounded text reads, capability ranking, runtime path redaction, browser protocol/operation boundaries, runtime reporting/diagnostics/capability composition, and Worker OAuth state/authorization-page/pending/policy/error/JSON-RPC/WebSocket protocol modules. The full stdio and workerd OAuth/MCP integration still runs separately.
 
-The gate deliberately reports each module rather than one aggregate percentage. New extracted pure/domain modules carry explicit branch floors, while the broad CLI entrypoint remains reported and locked independently. Worker pending calls and policy now have branch minima instead of function-only gates. A refactor may raise a threshold, but must not lower one merely to make CI green without an explicit audit explanation.
+Coverage belongs to the selected top-level fixtures. Concurrency, process-identity, and daemon-takeover helpers explicitly set `NODE_V8_COVERAGE` to an empty value: Node reinjects the parent coverage directory when the variable is merely deleted, which would start a profiler in every helper and distort both runtime and host load without improving the gated module evidence. Helper scripts assert this isolation where practical.
+Managed-job runners remain instrumented because their lifecycle modules are gated; only test-plan business steps clear coverage, preventing nested profiler startup from replacing the behavior the test is intended to observe. The suite also holds a queued status beyond the recovery grace period while a provisional runner claim is live, verifies that no recovery occurs, and checks that the child upgrades the one-time-token claim to an exact token-free process identity.
 
-`npm run typecheck` combines strict Worker TypeScript with a focused `tsconfig.local.json` gate. High-risk JavaScript contracts opt in with `// @ts-check` and JSDoc types; the gate currently covers policy, call lifecycle, Agent configuration/path resolution, public projection, skill discovery, bounded Agent text reads, runtime path redaction, browser handshake parsing, capability ranking, monotonic deadlines, number/record normalization, and bounded metadata reads. `@ts-ignore`, implicit `any`, or unchecked parallel contract shapes are not accepted as migration shortcuts.
+The gate deliberately reports each module rather than one aggregate percentage. New extracted pure/domain modules carry explicit branch floors, while the broad CLI entrypoint remains reported and locked independently. The machine-service owner, owner-aware service runtime, and Windows convergence modules require 100% function coverage with high branch floors; runtime activation remains independently gated. Worker pending calls and policy have branch minima instead of function-only gates. A refactor may raise a threshold, but must not lower one merely to make CI green without an explicit audit explanation.
+
+`npm run typecheck` combines strict Worker TypeScript with a focused `tsconfig.local.json` gate. High-risk JavaScript contracts opt in with `// @ts-check` and JSDoc types; the gate currently covers policy, call lifecycle, Agent configuration/path resolution, public projection, skill discovery, bounded Agent text reads, runtime path redaction, browser handshake parsing, capability ranking, monotonic deadlines, number/record normalization, bounded metadata reads, the machine-service owner transaction, owner-aware service convergence, Windows service convergence, child settlement, and process-tree ownership. `@ts-ignore`, implicit `any`, or unchecked parallel contract shapes are not accepted as migration shortcuts.
 
 ## Additional release checks
 
@@ -120,14 +136,14 @@ npm run worker:dry-run
 npm audit --audit-level=high
 npm audit --omit=dev --audit-level=high
 npm audit signatures
-npm sbom --sbom-format cyclonedx
+npm run sbom:test
 npm pack --dry-run
 npm run version:check
 npm run release-impact:check
 npm run release:acceptance:verify
 ```
 
-GitHub Actions uses the pinned Node 26/npm 12 baseline in three execution paths. Ubuntu runs `check:full` and verifies interactive candidate acceptance. macOS and Windows run `check:platform` plus the installed-package smoke test, preserving platform coverage without repeating every Worker, browser, and package integration fixture three times. A separate package-audit job scans reachable Git history, audits complete and production dependency graphs, verifies registry signatures and attestations, validates a CycloneDX SBOM under the runner temporary directory, repeats the isolated installation test, and performs a package dry run. Because Node 26 currently bundles npm 11, every npm execution job downloads the exact npm 12.0.1 tarball, rejects redirects, verifies its recorded SHA-512 SRI, and exposes that verified CLI through `GITHUB_PATH`. Separate pinned workflows validate governance titles, dependency changes, CodeQL, and OpenSSF Scorecard. Third-party Actions remain pinned to immutable commits, SARIF findings fail closed unless exactly reviewed, and source release creation requires successful push-triggered CI, CodeQL, Governance, and Scorecard runs for the exact `main` commit.
+GitHub Actions uses the pinned Node 26/npm 12 baseline in three execution paths. Ubuntu runs `check:full` and verifies interactive candidate acceptance. macOS and Windows run `check:platform` plus the installed-package smoke test, preserving platform coverage without repeating every Worker, browser, and package integration fixture three times. A separate package-audit job scans reachable Git history, audits complete and production dependency graphs, verifies registry signatures and attestations, validates a CycloneDX SBOM under the runner temporary directory; the local/full gate independently runs `sbom:test` through the pinned npm CLI, repeats the isolated installation test, and performs a package dry run. Because Node 26 currently bundles npm 11, every npm execution job downloads the exact npm 12.0.1 tarball, rejects redirects, verifies its recorded SHA-512 SRI, and exposes that verified CLI through `GITHUB_PATH`. Separate pinned workflows validate governance titles, dependency changes, CodeQL, and OpenSSF Scorecard. Third-party Actions remain pinned to immutable commits, SARIF findings fail closed unless exactly reviewed, and source release creation requires successful push-triggered CI, CodeQL, Governance, and Scorecard runs for the exact `main` commit.
 
 ## Test design rules
 
@@ -148,7 +164,7 @@ Run `npm run privacy:check` before committing and before packaging. Run and revi
 
 ## Package manifest
 
-`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts, credential-like file classes, and generated Worker type declarations, validates every packaged mode as `0644` or `0755`, and verifies that required runtime, script, browser-extension, privacy, governance, and release files are present. Exact runtime install-script approvals are version-bound, so a Wrangler/workerd refresh must also update the reviewed allowlist and pass a clean npm install without blocked-script warnings. `npm run install:test` requires npm 12, installs the real tarball from a package-free directory into an isolated global prefix with the documented options, verifies the packaged npm engine requirement, rejects blocked-script warnings, confirms optional `fsevents` is absent, verifies `--version`, then runs the installed CLI with zero arguments from an isolated workspace/state root. A fake Wrangler JavaScript entrypoint terminates at a controlled deployment boundary, so the probe exercises startup without mutating a live account. Package testing is full-plan-only; installation smoke runs in the Ubuntu full plan, the macOS/Windows platform plan, and package audit.
+`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts, credential-like file classes, and generated Worker type declarations, validates every packaged mode as `0644` or `0755`, and verifies that required runtime, script, browser-extension, privacy, governance, and release files are present. Exact runtime install-script approvals are version-bound, so a Wrangler/workerd refresh must also update the reviewed allowlist when the resolved workerd build changes and must pass a clean npm install without blocked-script warnings. A Wrangler-only or Miniflare-only patch that retains the same workerd build must prove that the existing single exact approval still matches the lockfile. `npm run install:test` requires npm 12, installs the real tarball from a package-free directory into an isolated global prefix with the documented options, verifies the packaged npm engine requirement, rejects blocked-script warnings, confirms optional `fsevents` is absent, verifies `--version`, then runs the installed CLI with zero arguments from an isolated workspace/state root. A fake Wrangler JavaScript entrypoint terminates at a controlled deployment boundary, so the probe exercises startup without mutating a live account. Package testing is full-plan-only; installation smoke runs in the Ubuntu full plan, the macOS/Windows platform plan, and package audit.
 
 `npm run lint` uses ESLint as a semantic JavaScript correctness gate rather than a style formatter. It covers the Node CLI/runtime, repository scripts, tests, and packaged browser extension and rejects undefined identifiers in function bodies that `node --check` cannot detect. A dedicated lint-gate self-test proves that both Node and browser configurations reject a synthetic undefined binding while accepting the service-worker `importScripts` global. A focused `shell:test` requires Wrangler to run through the current Node executable and its package JavaScript entrypoint rather than a `.cmd` or shell shim. Architecture tests require `shell:test`, `lint:test`, `lint`, and `install:test` to remain in the complete check pipeline and reject non-exact direct dependency ranges.
 
@@ -156,11 +172,15 @@ The stdio integration test also sends an oversized line, verifies bounded reject
 
 ## Architecture and documentation regression checks
 
-`npm run architecture:test` runs independent module-boundary, repository-hygiene, browser/security-structure, and release/documentation-contract checks. It validates the explicit fast/full check plans, local import graph, domain/adapter direction, module headroom budgets, immutable workflow references, package-script targets, documentation links, publication inventory, and selected security-shape invariants. Critical coverage thresholds include every extracted OAuth refresh, token issuance, stream subscription, static metadata/routing, quota guard, edge logger, and filesystem-state module. These source-shape checks are deliberately supplementary: behavior, denial, race, and fault-injection tests remain authoritative for semantic guarantees. Tests must not depend on a fixed CI job count when the actual invariant is that every npm job uses the same verified bootstrap.
-## Resumable MCP delivery coverage
+`npm run architecture:test` runs independent module-boundary, repository-hygiene, browser/security-structure, and release/documentation-contract checks. It validates the explicit fast/full check plans, local import graph, domain/adapter direction, module headroom budgets, immutable workflow references, package-script targets, documentation links, publication inventory, and selected security-shape invariants. Critical coverage thresholds include every extracted OAuth refresh, token issuance, stream subscription, static metadata/routing, quota guard, edge logger, filesystem-state module, system-route classifier, and remote timeout/catalog projection. These source-shape checks are deliberately supplementary: behavior, denial, race, and fault-injection tests remain authoritative for semantic guarantees. Tests must not depend on a fixed CI job count when the actual invariant is that every npm job uses the same verified bootstrap.
+## MCP delivery and conformance coverage
 
 `npm run mcp-resumption:test` directly exercises stream cursor parsing, OAuth-token/MCP-session isolation, immediate pending/terminal polls, active and completed replay, orphaned-stream restart ambiguity, persisted-call restart recovery, strict call-record validation, request-key uniqueness, operation/reconnect deadlines, repeated detach/rebind retention extension, stale-generation rejection, prototype-safe aggregation, exactly-once completion, result-size fallback, SHA-256 tamper detection, transient persistence failure, expiry, capacity, completed-record eviction, the four-row plain-stream budget, and the fixed six-row durable-call lifecycle budget.
 
-`npm run worker-runtime-infrastructure:test` verifies outer-Worker stream ownership, stripping of caller-supplied internal headers, bounded descriptor/subscribe adaptation, fixed request budgets, bounded transient subscription retries, outer metadata/404/invalid-method bypass, stateful burst limiting, structured and duplicate-suppressed gateway failures, coalesced alarm writes, sequence-zero/sequence-one framing, subscription-error closure, subscriber replacement, non-daemon socket isolation, and the shared two-minute/64-stream/1.5-MiB contract. It models the production durable-call boundary: initiation persists ownership without retaining a terminal Promise, later success or daemon rejection settles once, send failure cleans the record, capacity fails closed, and same-instance reconnect moves ownership to a new generation while rejecting the stale one. Deadline tests prove both JSON-only timer/sweep behavior and persisted-call alarm expiry without leaking request keys. A direct runtime-alarm coordinator test verifies the earliest transient-or-durable deadline, alarm removal when no deadline remains, event-entry expiry before rescheduling, and bounded reporting when Durable Object alarm storage fails. The same suite also proves that direct same-instance handover preserves the remaining timeout budget. `npm run worker:integration-test` performs the real Wrangler path: the role-filtered catalog remains stable before, during, and after daemon availability changes; execution still fails closed without a ready daemon; an open SSE stream coexists with concurrent `server_info` and explicit cancellation; verified same-instance replacement transfers an in-flight call before incumbent close; disconnect/recovery remains token/session isolated; and sequence-one acknowledgement is not delivered twice. Managed-job integration treats `__proto__`, `constructor`, `toString`, and `valueOf` environment/resource-map keys as ordinary own data while retaining duplicate-key rejection. Static architecture checks forbid a stream-initiation `dispatchJsonRpc` Promise, `resumption.attach`, Durable Object `waitUntil`, Promise-valued recovery state, or return of the obsolete transient `registerEvent` branch. The parser accumulates complete SSE events and does not assume network chunk boundaries. CORS coverage requires both `DPoP` and `Last-Event-ID`.
+`npm run worker-runtime-infrastructure:test` verifies both delivery eras. Modern coverage proves private prepare/subscribe/cancel control headers are stripped at the public edge, transient ownership is memory-only, cancellation releases it exactly once, no event ID or replay record is created, and already-attached internal settlement cannot make a cancelled stream reusable. Legacy coverage retains descriptor/subscriber adaptation, sequence-zero/sequence-one framing, hibernatable subscription replacement, durable ownership/settlement, timeout/reconnect alarms, two-minute/64-stream/1.5-MiB bounds, stale-generation rejection, result acknowledgement/replay, and same-instance handover. Shared checks cover stateful burst limiting, gateway failures, daemon call deadlines, socket isolation, output/log maintenance, and no request-key leaks.
+
+`npm run worker:integration-test` exercises the real Wrangler/OAuth/daemon path. It runs ordinary modern and legacy regression cases by default. When `MBM_OFFICIAL_CONFORMANCE_CHECKOUT` and `MBM_OFFICIAL_CONFORMANCE_SCENARIOS` are set, it also drives the pinned official MCP conformance checkout through a test-only loopback proxy that injects the already-created short-lived test bearer token. The production OAuth endpoint is unchanged, the alpha conformance package is not added to the dependency graph, and `tests/mcp-conformance-baseline.yml` contains only check-scoped exclusions for capabilities the production server intentionally does not advertise. A new unrelated failure or a stale expected-failure entry fails the run. The checkout must be a real directory with a committed lockfile and installed dependencies; missing or cleaned checkouts fail before Worker startup rather than surfacing as an ambiguous spawn error. Treat the alpha runner as an external audit tool: record its exact commit, inspect its own `npm audit` result, run it only against the loopback proxy, and remove the checkout afterward.
+
+`npm run tool-arguments:test` compiles all tool schemas under the bounded JSON Schema 2020-12 subset and covers type, range, length, array, object, pattern, enum, conditional/composition, unsupported dialect/keyword, external `$ref`, depth, node-count, issue-count, and value-redaction behavior. Worker and stdio integration additionally prove malformed calls are rejected before daemon/local side effects.
 
-Beta.21 closeout requires a fresh pass of the complete 63-task fast plan and 91-task full plan after the final relay error-classification changes; an earlier green run cannot be reused as terminal evidence.
+Every candidate closeout requires fresh fast and full plans after the final packaged-source change; an earlier green run from another prerelease or pre-documentation tree is not terminal evidence.

package/docs/THREAT_MODEL.md

@@ -37,10 +37,17 @@ The hosted MCP client, its prompts, tools, extensions, and retrieved content are
 - OAuth state, PKCE, redirect URI, resource binding, and request size;
 - account status, account version, account role, trusted client binding, token expiry, and refresh-family state;
 - DPoP proof method, target URL, timestamp, unique identifier, access-token hash, and key thumbprint when DPoP is used;
-- MCP session state, protocol version, method shape, request IDs, cancellation, and allowed tool exposure.
+- modern per-request protocol metadata, valid positive `Accept` quality values, actual `/mcp` Origin, header/body consistency for version/method/name/declared primitive parameters, request IDs, role-visible tool exposure, raw argument schemas, and response-stream cancellation;
+- legacy initialization, signed session, explicit cancellation, and bounded replay state when the client selects MCP `2025-11-25`.
 
 A client registration is not authority. Authority begins only after successful account authorization binds the client to one account and role version.
 
+Capability discovery is also an authorization boundary. Task routing and application/browser metadata are built from the effective account/daemon policy intersection, not from the daemon ceiling. Route scores and fallbacks are advisory and cannot manufacture authority; direct Bash remains available only when the effective policy already exposes it. A restricted account must not learn hidden local application inventory or receive names of unavailable execution tools through the resolver.
+
+Mirrored MCP headers are an intermediary-routing boundary. The Worker compares every required modern header with the JSON-RPC body before authorization-dependent dispatch; a mismatch fails with `-32020` before the daemon can observe the call. Tool schemas are compiled from a bounded JSON Schema 2020-12 subset at startup and runtime traversal charges every array item and own object property to a fixed work budget. Open metadata/capability/subscription JSON also has a fixed structural-node/depth/key budget, and resource subscriptions are count/length bounded. Unsupported dialects or keywords fail closed, external network `$ref` values are not dereferenced, and validation diagnostics omit argument values and unbounded caller identifiers.
+
+Modern cancellation deliberately crosses the OAuth boundary only through an unguessable internal stream capability. The public Worker strips caller-provided control headers before the service binding, the cancellation request contains no bearer token or DPoP proof, and the Durable Object consumes the capability before OAuth only to cancel a currently indexed call. Guessing remains bounded by 256-bit randomness; a compromised service binding or Worker runtime is already inside this trust boundary.
+
 ### Worker to local daemon
 
 The Worker is a relay and authorization layer, not the source of local OS authority.
@@ -113,6 +120,8 @@ Machine Bridge considers:
 The implementation aims to preserve these invariants:
 
 - unknown, malformed, stale, replayed, duplicated, unauthorized, and over-limit input is rejected;
+- an intermediary cannot authorize or route one modern method/name while the Worker executes another body; mirrored-header mismatch is rejected before dispatch;
+- modern request IDs are not global identities across clients sharing one bearer token, while legacy duplicate and cancellation domains remain bound to the signed session;
 - the stable account-role discovery catalog is not treated as execution authority; every call is intersected with the current end-to-end-ready daemon policy and fails closed when that authority is absent;
 - remote authority is the intersection of daemon policy and account role, never the union;
 - no approval record, token refresh, or local migration state can elevate a delegated role;
@@ -182,7 +191,9 @@ UI state can change between inspection and action. Pages can present deceptive c
 
 ### Managed jobs
 
-Managed jobs outlive MCP calls and daemon reconnects. Plans and resources are validated and ownership-bound, but an authorized owner plan can still consume resources or perform destructive work. Finally steps must be idempotent because recovery may retry them.
+Synchronous identity and sandbox probes use `SIGKILL` when their declared deadline expires; a soft timeout signal is not treated as a bound because the caller can otherwise remain blocked. POSIX forced process-tree escalation requires a non-empty captured ownership set and exact PID/start-time continuity. If process inspection is unavailable or ambiguous, Machine Bridge may leave a resistant descendant for operator cleanup rather than risk signaling a reused process group.
+
+Managed jobs outlive MCP calls and daemon reconnects. Plans and resources are validated and ownership-bound, but an authorized owner plan can still consume resources or perform destructive work. Finally steps must be idempotent because recovery may retry them. Process-tree escalation revalidates captured PID, start-time, and process-group identity so PID reuse cannot redirect `SIGKILL` to an unrelated process. Full and targeted process snapshots share one monotonic budget per ownership decision, preventing descendant count or a stalled process-table query from expanding shutdown latency without bound. Darwin additionally queries only the target PGID, reducing the chance that unrelated process-table load erases all ownership evidence and forces fail-closed descendant retention. A missing ChildProcess `close` event after observed `exit` receives a bounded output-drain fallback and cannot leave a managed-job runner permanently unresolved.
 
 ### Availability and resource exhaustion
 
@@ -190,12 +201,16 @@ Application-level limits bound many requests and outputs. An authorized owner pr
 
 ### System VPN/TUN and distributed activation
 
-A system VPN/TUN can remain administratively connected while its selected upstream route, synthetic DNS mapping, or transport path is temporarily unusable. Machine Bridge can detect missing inbound relay traffic, classify the socket close, bound retry delay, and report outage history, but it cannot select or repair a third-party VPN node. `system-network-stack` is therefore not a claim of direct routing. A Worker transport/liveness invalidation is treated as a retryable socket-generation failure; elevating it to a permanent protocol error would let an ordinary network fault restart the daemon and amplify the outage. Unknown protocol messages and authentication or version mismatch remain fail-closed.
+A system VPN/TUN can remain administratively connected while its selected upstream route, synthetic DNS mapping, or transport path is temporarily unusable. Machine Bridge can detect missing inbound relay traffic, classify the socket close, bound retry delay, report outage history, and on macOS classify the default route as tunnel/VPN versus a coarse non-tunnel category. It cannot identify the failing upstream node or repair a third-party VPN. `system-network-stack` is therefore not a claim of direct routing. The route diagnostic deliberately omits interface identity, addresses, DNS answers, and endpoints. A Worker transport/liveness invalidation is treated as a retryable socket-generation failure; elevating it to a permanent protocol error would let an ordinary network fault restart the daemon and amplify the outage. Unknown protocol messages and authentication or version mismatch remain fail-closed.
+
+Candidate activation verifies the foreground candidate before service handoff and records exact package/deployment evidence. It does not provide an atomic transaction spanning Cloudflare deployment and every local service manager. The machine-global service definition therefore has an owner-only pending/committed ledger, all service writers share one fixed per-user lock, and any path that also acquires a workspace startup lock uses machine-service-first ordering. Provider-active state is not authenticity evidence: the exact owner-bound service daemon must publish a token-protected readiness checkpoint after device authentication, relay probe, and `ready_ack`. Missing, corrupt, pending, mismatched, or unready ownership fails closed.
 
-Candidate activation verifies the foreground candidate before service handoff and records exact package/deployment evidence. It does not provide an atomic transaction spanning Cloudflare deployment and every local service manager. If the Worker changes and the local handoff later fails, the operator may need the recorded previous runtime/deployment evidence to complete rollback. Local cleanup errors are aggregated rather than hidden, but remote rollback is not fabricated.
+An explicit candidate device-authentication rejection permits one same-name redeployment with the unchanged selected identity; ambiguous network or health failure does not. After remote preparation, local compensation installs and starts the compatible candidate service rather than reviving a known-incompatible old daemon. Before remote preparation, restoration of an older service requires the same version and entrypoint to reappear as a verified service-mode daemon. The wrapper intentionally has no transaction-wide hard kill, because killing the parent could bypass cleanup and leave detached deployment helpers; each internal stage has its own deadline instead. Persistent Cloudflare, service-manager, filesystem, or process-inspection failure can still require operator diagnosis. Local cleanup errors are aggregated rather than hidden, and remote rollback is not fabricated.
 
 ### External governance and publication
 
+GitHub tag/Release publication requires an explicit confirmation flag, TTY-backed stdin/stdout/stderr, and one process-identity lock shared through the common Git directory. This blocks the supported MCP, managed-job, CI, redirected, and ordinary background paths and prevents concurrent publication from separate linked worktrees. It is a workflow and accountability boundary, not cryptographic user-presence authentication: arbitrary code already executing as the same OS user can allocate a pseudo-terminal and invoke the same command. A protected release environment, hardware-backed user presence, or a separately isolated principal is required when adversarial same-user separation is part of the threat model.
+
 Code cannot create a second independent reviewer, npm OIDC trust relationship, protected publication environment, Apple Developer identity, or external certification. These remain explicit operational requirements.
 
 ## Validation map
@@ -209,7 +224,7 @@ Regression suites cover:
 - delegated sandbox behavior and fail-closed platform detection;
 - process/session cleanup, generated-key rollback including cleanup failure, managed-job lifecycle and recovery, state locks, atomic persistence, and destructive removal;
 - browser pairing, version/capability handshake, broker routing, independent concurrency limits, public-error redaction, sensitive input, and navigation controls;
-- audit-chain integrity, privacy redaction, package contents, installation, release impact, dependency integrity, CodeQL, and Scorecard findings;
+- audit-chain integrity, privacy redaction, package contents, installation, release impact, dependency integrity, CodeQL, Scorecard findings, and GitHub publication guard/lock behavior;
 - malformed, over-limit, concurrent, replayed, stale, and fault-injected inputs.
 
 See [TESTING.md](TESTING.md) for the test inventory and [AUDIT.md](AUDIT.md) for historical findings and residual limitations.

package/docs/TOOL_REFERENCE.md

@@ -66,7 +66,7 @@ Tool count: **51**.
 
 **Server information**
 
-Return authenticated account authority, effective policy/tools, daemon capability ceiling, runtime metadata, and protocol status. Treat authorization.effective_policy and authorization.effective_tools as authoritative; daemon.policy is only a ceiling.
+Return live authorization, effective tools, daemon/relay health, runtime state, and protocol status. Use this for authority or connectivity diagnosis, not for repository inventory. Treat authorization.effective_policy and authorization.effective_tools as authoritative; daemon.policy is only a ceiling.
 
 | Contract field | Value |
 |---|---|
@@ -89,7 +89,7 @@ Return authenticated account authority, effective policy/tools, daemon capabilit
 
 **Project overview**
 
-Summarize the connected workspace and repository. Remote responses report the authenticated account effective policy/tools at policy and tools, with the daemon capability ceiling preserved separately as daemonPolicy and daemonTools.
+Summarize the connected workspace, repository root, top-level entries, and project-facing runtime context. Use this for repository inventory, not as the primary live relay-health check. Remote responses report authenticated-account effective policy/tools separately from the daemon capability ceiling.
 
 | Contract field | Value |
 |---|---|
@@ -112,7 +112,7 @@ Summarize the connected workspace and repository. Remote responses report the au
 
 **Load session bootstrap**
 
-Load built-in working agreements, bounded automatic project facts, user-global and root workspace instructions, and capability refresh metadata for MCP session initialization.
+Load built-in working agreements, bounded automatic project facts, user-global and root workspace instructions, and capability refresh metadata. Modern clients call it explicitly; legacy initialize clients receive the same bounded guidance through the compatibility adapter.
 
 | Contract field | Value |
 |---|---|
@@ -142,7 +142,7 @@ Load built-in working agreements, bounded automatic project facts, user-global a
 
 **Resolve task capabilities**
 
-Rescan built-in and automatic project context, local instruction files, skills, explicit and automatic package commands, installed applications, and browser capability metadata; rank the capabilities relevant to the current task and optionally load the best skill.
+Rescan task-relevant instructions, skills, registered commands, installed applications, browser metadata, and the effective tool catalog. Return bounded set-level execution routes, ranked tools, routing ambiguity, and an optional selected skill. Pass known_refresh_fingerprint to omit unchanged static instructions while recomputing task-specific ranking. The result is advisory: direct Bash and every other policy-allowed tool remain available.
 
 | Contract field | Value |
 |---|---|
@@ -178,6 +178,12 @@ Rescan built-in and automatic project context, local instruction files, skills,
     "include_selected_skill": {
       "type": "boolean",
       "default": true
+    },
+    "known_refresh_fingerprint": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "maxLength": 64,
+      "description": "Previous refresh fingerprint. When it still matches, unchanged static instructions are omitted while task-specific ranking is recomputed."
     }
   },
   "required": [
@@ -490,7 +496,7 @@ Open the local pairing page and return the packaged unpacked-extension path for
 
 **List browser tabs**
 
-List tabs from the paired user's existing Chromium browser profile.
+Read the tab inventory from the paired existing Chromium profile without creating, activating, or closing a tab. Use browser_manage_tabs for tab mutations.
 
 | Contract field | Value |
 |---|---|
@@ -529,7 +535,7 @@ List tabs from the paired user's existing Chromium browser profile.
 
 **Manage browser tabs**
 
-Create, activate, or close tabs in the paired existing browser profile.
+Create, activate, or close tabs in the paired existing Chromium profile. Use browser_list_tabs when only a read-only tab inventory is needed.
 
 | Contract field | Value |
 |---|---|
@@ -585,7 +591,7 @@ Create, activate, or close tabs in the paired existing browser profile.
 
 **Read browser page source**
 
-Read bounded serialized current DOM HTML from the active or selected browser tab. max_bytes is one aggregate budget across at most 64 accessible frames, with explicit frame, node, and byte truncation metadata.
+Read bounded raw serialized DOM HTML from the active or selected tab when source markup is required. Use browser_inspect_page for semantic elements, actionability, reusable refs, and structured interaction planning. max_bytes is one aggregate budget across at most 64 accessible frames.
 
 | Contract field | Value |
 |---|---|
@@ -634,7 +640,7 @@ Read bounded serialized current DOM HTML from the active or selected browser tab
 
 **Inspect browser page**
 
-Inspect a bounded snapshot-version-2 semantic representation across at most 64 accessible frames, with one aggregate element budget, bounded reusable refs, actionability state, bounded page-controlled metadata, and explicit scan/frame truncation.
+Inspect a bounded semantic/actionability snapshot with reusable element refs for structured browser decisions and actions. This is not raw page source; use browser_get_source when serialized DOM HTML is required. The aggregate element budget spans at most 64 accessible frames.
 
 | Contract field | Value |
 |---|---|
@@ -1300,7 +1306,7 @@ Populate a browser file input from registered local resource files without retur
 
 **Load agent context**
 
-Discover built-in defaults, bounded automatic project facts, Codex-compatible global/root-to-target instruction precedence, progressively disclosed local skills, explicit commands, and safe automatic package-script command aliases for a target path.
+Discover the instruction, skill, and registered-command inventory for a target path, including precedence and provenance. Use this when the caller needs the context itself; use resolve_task_capabilities when it needs task-specific ranking and execution-route advice.
 
 | Contract field | Value |
 |---|---|
@@ -1455,7 +1461,7 @@ List effective direct-argv commands from project manifests and safe automatic pa
 
 **Run registered local command**
 
-Run an effective manifest or automatic package-script command through its fixed argv, cwd, timeout ceiling, and extra-argument policy. Large stdout/stderr is previewed inline and retained temporarily for paged read_process continuation.
+Prefer this when the repository already defines the desired operation as a registered command or package script. It runs the fixed argv/cwd/timeout contract without shell reinterpretation; use exec_command for ad hoc pipelines or run_process for an unregistered executable argv. Large output is retained for read_process.
 
 | Contract field | Value |
 |---|---|
@@ -1988,7 +1994,7 @@ Return bounded metadata and patch output for one revision without running reposi
 
 **Run process directly**
 
-Execute an argv array without a command shell. This avoids shell parsing but does not sandbox the executable or code it launches. Large stdout/stderr is previewed inline and retained temporarily for paged read_process continuation.
+Run an explicit executable plus argv when no shell syntax is needed and no registered command fits. This avoids quoting, globbing, pipelines, and redirection, but it is not a sandbox; use exec_command when Bash composition is the convenient choice. Large output is retained for read_process.
 
 | Contract field | Value |
 |---|---|
@@ -2796,7 +2802,7 @@ Request cancellation of a detached managed job. The runner terminates the active
 
 **Execute shell command**
 
-Execute a shell command with workspace cwd. This is not a sandbox and has the operating-system authority of the local user. Large stdout/stderr is previewed inline and retained temporarily for paged read_process continuation.
+Run Bash-compatible shell composition in the workspace: pipelines, redirection, globbing, conditionals, or compact multi-command probes. This is the convenient general escape hatch, not a sandbox, and has the local user's operating-system authority. Prefer run_local_command for an existing fixed project command and run_process when no shell syntax is needed. Large output is retained for read_process.
 
 | Contract field | Value |
 |---|---|

package/docs/UPGRADING.md

@@ -67,6 +67,38 @@ Legacy version 2 lease state may be listed, revoked, or cleared for cleanup, but
 
 `ACCOUNT_ADMIN_SECRET` is deleted from local state and is no longer deployed to the Worker. Account and OAuth-client administration uses the same root-certified ephemeral session established for daemon startup or an independently authorized local administration command.
 
+## Version 3.0.0-beta.25 MCP 2026-07-28 transition
+
+Beta.25 makes MCP `2026-07-28` primary while retaining MCP `2025-11-25` as a compatibility adapter.
+
+Modern clients must:
+
+- send `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities` in every request `_meta`;
+- include both `application/json` and `text/event-stream` in HTTP `Accept` and the required `MCP-Protocol-Version`, `Mcp-Method`, and applicable `Mcp-Name`/`Mcp-Param-*` headers;
+- use `server/discover` instead of `initialize`;
+- treat each HTTP response stream as request-scoped and cancelled when closed;
+- not use `Mcp-Session-Id`, recovery GET, SSE event IDs, or `Last-Event-ID`.
+
+Legacy MCP `2025-11-25` clients may continue to initialize and use the signed-session resumable path. Reconnect modern clients by rediscovering and issuing fresh requests; reconnect legacy clients by reinitializing. Existing OAuth accounts, daemon identity, service state, managed jobs, resources, and browser pairing do not require migration solely because of the protocol change.
+
+The tool catalog is now enforced as bounded JSON Schema 2020-12 at both Worker and local runtime boundaries. Clients that previously sent unknown fields, wrong scalar types, fractional integer values, or out-of-range values will receive `-32602` before side effects rather than handler-specific fallback behavior. Fix the request; do not retry unchanged.
+
+## Version 3.0.0-beta.24 candidate-activation convergence
+
+Beta.23 is blocked and must not be accepted, published, or promoted. Owner-machine activation proved that a Worker could report the expected version and pass health verification while rejecting the candidate daemon before WebSocket admission because the active device-authentication material had not converged. The failed transaction then restarted an older service definition that could not authenticate to the already advanced Worker.
+
+Beta.24 treats candidate device authentication and end-to-end readiness as required deployment evidence. One explicit authentication rejection triggers exactly one same-name redeployment with the unchanged selected identity; it does not rotate the device root, OAuth token version, account credentials, or Worker name. Candidate startup is bounded to three attempts. If remote preparation has occurred and activation still fails, local recovery installs and starts the compatible candidate service instead of restoring an incompatible old daemon. Before remote preparation, an older service is restored only when the same version and entrypoint reappear as a verified service daemon. Provider stop and start results must include verified inactive/active state; ambiguous systemd states and non-persistent Windows task completion fail closed. The original failure remains visible for diagnosis.
+
+Beta.24 also introduces an owner-only machine-service ledger and an explicit readiness checkpoint. Service installation binds the canonical workspace, state root, exact runtime entrypoint, and version in a pending-to-committed transaction. Start/restart refuse missing, corrupt, pending, or mismatched ownership and do not accept a provider PID as proof of readiness; the exact service daemon must complete authentication, relay probing, and `ready_ack`. All machine-global service writers use one fixed per-user lock before any workspace startup lock, eliminating cross-workspace definition races and lock-order cycles. Existing beta.23 service definitions do not have this ledger; exact candidate activation installs and commits the beta.24 owner before the final handoff. Do not manually fabricate or copy `service-owner.json`.
+
+No state-schema, OAuth-store, browser-pairing, resource, or managed-job migration is introduced. Upgrade through the exact candidate workflow. Do not delete state or rotate secrets in response to an isolated activation rejection.
+
+## Version 3.0.0-beta.23 foreground-contract change
+
+Beta.23 requires coordinated Worker and daemon/CLI metadata convergence. The Worker-specific `tools/list` schema narrows configurable foreground timeouts to 85 seconds while preserving each tool’s 30- or 60-second default and rejects larger values before daemon dispatch. Local/stdio callers retain the 1–600 second schema. Work that can exceed the remote foreground boundary must use process sessions, managed jobs, or independently terminal mutation/validation calls.
+
+`machine-mcp doctor` and `diagnose_runtime` also gain a macOS-only coarse default-route check. A `tunnel-or-vpn` result is evidence that an operating-system packet tunnel carries the route; it does not identify a failing node and is not authority to modify third-party VPN settings. Upgrade through the normal exact-version candidate flow and reload the packaged extension because its `version_name` is synchronized with the package.
+
 ## Version 3 beta.21 relay-continuity change
 
 Beta.21 changes the Worker-side stream-call record and MCP discovery contract. `tools/list` is stable for an authenticated account role; `server_info.authorization.effective_tools` remains the live execution authority. Streamed calls persist their daemon instance, WebSocket generation, request correlation, and deadlines so Durable Object hibernation or restart does not itself orphan an active call. JSON-only requests retain the prior bounded in-event path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "3.0.0-beta.21",
+  "version": "3.0.0-beta.26",
   "description": "Cross-client MCP bridge for local agent context, structured browser and application automation, files, Git, processes, resources, and durable jobs over stdio or OAuth relay.",
   "type": "module",
   "license": "MIT",
@@ -56,6 +56,7 @@
     "release:backfill": "node scripts/github-release.mjs --backfill",
     "stdio:integration-test": "node tests/stdio-integration-test.mjs",
     "catalog:test": "node tests/catalog-test.mjs",
+    "tool-arguments:test": "node tests/tool-argument-validation-test.mjs",
     "managed-jobs:test": "node tests/managed-jobs-test.mjs",
     "ssh-key:test": "node tests/ssh-key-test.mjs",
     "full-access:test": "node tests/full-access-test.mjs",
@@ -100,6 +101,7 @@
     "policy-docs:check": "node scripts/generate-policy-reference.mjs --check",
     "coverage:test": "node scripts/coverage-check.mjs",
     "capability-ranking:test": "node tests/capability-ranking-test.mjs",
+    "execution-routing:test": "node tests/execution-routing-test.mjs",
     "lifecycle:test": "node tests/lifecycle-test.mjs",
     "runtime-handlers:test": "node tests/runtime-handler-matrix-test.mjs",
     "cli-entrypoint:test": "node tests/cli-entrypoint-test.mjs",
@@ -164,19 +166,26 @@
     "candidate-runtime-store:test": "node tests/candidate-runtime-store-test.mjs",
     "service-restart:test": "node tests/service-restart-handoff-test.mjs",
     "browser-identity:test": "node tests/browser-extension-identity-test.mjs",
-    "mcp-resumption:test": "node tests/mcp-resumption-test.mjs"
+    "mcp-resumption:test": "node tests/mcp-resumption-test.mjs",
+    "mcp-protocol:test": "node tests/mcp-protocol-test.mjs",
+    "mcp-modern-controller:test": "node tests/mcp-modern-controller-test.mjs",
+    "mcp:conformance": "node scripts/official-mcp-conformance.mjs",
+    "mcp:conformance:test": "node tests/official-mcp-conformance-test.mjs",
+    "sbom-check:test": "node tests/sbom-check-test.mjs",
+    "sbom:test": "node scripts/sbom-check.mjs",
+    "release-publication-guard:test": "node tests/release-publication-guard-test.mjs"
   },
   "dependencies": {
     "https-proxy-agent": "9.1.0",
     "proxy-from-env": "2.1.0",
-    "wrangler": "4.114.0",
+    "wrangler": "4.115.0",
     "ws": "8.21.1"
   },
   "devDependencies": {
-    "@types/node": "26.1.1",
-    "eslint": "10.7.0",
+    "@types/node": "26.1.2",
+    "eslint": "10.8.0",
     "fast-check": "4.9.0",
-    "globals": "17.7.0",
+    "globals": "17.8.0",
     "typescript": "7.0.2"
   },
   "keywords": [

package/scripts/check-plan.mjs

@@ -13,6 +13,7 @@ export const FAST_CHECK_TASKS = Object.freeze([
   "runtime-activation:test",
   "candidate-runtime-store:test",
   "release-state:test",
+  "release-publication-guard:test",
   "release-ci:test",
   "network-retry:test",
   "check-runner:test",
@@ -26,6 +27,7 @@ export const FAST_CHECK_TASKS = Object.freeze([
   "dpop:test",
   "security-audit:test",
   "sarif-security:test",
+  "sbom-check:test",
   "shell:test",
   "architecture:test",
   "markdown:test",
@@ -51,13 +53,18 @@ export const FAST_CHECK_TASKS = Object.freeze([
   "logging-structure:test",
   "worker-runtime-infrastructure:test",
   "mcp-resumption:test",
+  "mcp-protocol:test",
+  "mcp-modern-controller:test",
+  "mcp:conformance:test",
   "lint:test",
   "lint",
   "typecheck",
   "syntax",
   "deadline:test",
   "catalog:test",
+  "tool-arguments:test",
   "capability-ranking:test",
+  "execution-routing:test",
   "agent-boundaries:test",
   "browser-identity:test",
   "browser-command:test",
@@ -92,6 +99,7 @@ export const FULL_ONLY_CHECK_TASKS = Object.freeze([
   "coverage:test",
   "browser-bridge:test",
   "package:test",
+  "sbom:test",
   "install:test",
   "stdio:integration-test",
   "worker:integration-test",