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

package/docs/ENGINEERING.md

@@ -2,6 +2,10 @@
 
 This document records project-wide decisions that must survive individual fixes, releases, and maintainers. It is normative for repository changes together with [PROJECT_STANDARDS.md](PROJECT_STANDARDS.md). Machine-specific observations belong in the ignored `.project-local/` directory instead.
 
+## Dependency save policy
+
+Repository npm saves must preserve exact versions (`save-exact=true`). Root production, development, and optional dependencies are architecture-gated to exact semantic versions and installs remain lockfile-driven. Do not add a blanket `min-release-age` project setting: npm applies it as a version-availability filter and can therefore block a newly published security fix. Supply-chain freshness is handled by explicit reviewed upgrades plus lockfile, audit, signature/attestation, lifecycle-script, and consumer-package gates rather than by making recent versions globally ineligible.
+
 ## Product and security invariants
 
 1. **The default profile is intentionally `full`.** This is an explicit product-owner decision prioritizing usability. It must not be changed to a narrower default as an incidental security cleanup. Documentation must continue to explain the authority and risks clearly.
@@ -9,24 +13,50 @@ This document records project-wide decisions that must survive individual fixes,
 3. **Machine Bridge authority and host authority are separate.** `full` removes Machine Bridge's own policy, path, shell, and environment restrictions. It cannot override an MCP host, connector gateway, operating system, endpoint-security product, cloud IAM, remote authentication, or `sudo`.
 4. **Publication surfaces contain no real environment metadata.** Source, tests, fixtures, examples, release notes, filenames, package contents, tags, and release assets use synthetic identifiers and reserved example domains.
 5. **Secrets are never operational log data.** Tool arguments, command text, stdin, stdout, stderr, file content, OAuth bodies, credentials, and local resource values are not logged.
-6. **A release is one owner-authorized, agent-operated and verified package with successful cross-platform evidence.** The repository owner explicitly authorizes the exact npm candidate and any same-name Worker update in the active conversation; the coding agent starts that candidate through Machine Bridge, verifies the connected candidate version, readiness, and representative functionality, and then records the package hashes before the first GitHub push. Package metadata, Worker version, browser-extension version/name, acceptance record, Git tag, GitHub Release, npm version, documentation, and deployed health version must agree, and the exact `origin/main` commit must have completed successful push-triggered CI, CodeQL, Governance, and OpenSSF Scorecard runs before a tag or release is created.
+6. **Stable release requires a published prerelease soak.** The owner runs one exact persistent candidate activation command; the coding agent verifies the real Worker and daemon before recording acceptance. Version 3 and later use `dev`, `beta`, or `rc`, publish under non-`latest` tags, and complete the policy minimum soak after registry-verified activation. Stable promotion may change only normalized release metadata and requires an identical promotion-content digest, a tracked soak record, repeated stable-candidate verification, and successful exact-commit CI, CodeQL, Governance, Workflow Policy Gate, and Scorecard.
 7. **Generic local automation is structured, not arbitrary evaluation.** Browser/application features may expose broad user authority under canonical `full`, but must not accept caller-provided JavaScript, AppleScript, JXA, or extension code.
 8. **Daily-browser integration uses the existing profile.** The supported primary browser path is the packaged authenticated extension and machine-level loopback broker, preserving current tabs/login state; a separate automation profile is not an equivalent replacement.
 9. **Pairing and resource secrets are not conversation or log data.** Tokens and injected local-resource values must not be returned, embedded in URLs, or written to operational logs.
 10. **Exclusive claims are complete before visible.** Never create a final lock/PID claim and then populate it. Use the shared exclusive-file primitive, ownership tokens, process-start identity, and snapshot-checked reclamation.
 11. **Service and state removal are fail-closed state machines.** Stop the platform provider and every verified daemon before removing definitions or recursive state. An unreadable lock, failed stop, active job, or ambiguous identity retains state for diagnosis.
-12. **Read failure is not empty state.** Permission, type, symbolic-link, size, encoding, and I/O errors must propagate. Corrupt backup/reconstruction applies only after a successful read proves that JSON content is invalid.
-13. **The public protocol contract is current-only.** Shared metadata advertises only the current MCP protocol version. Compatibility code for obsolete protocol dates, lock formats, or state schemas is not retained in the final runtime; upgrade safety comes from explicit version negotiation, fail-closed state validation, and bounded operator convergence.
+12. **Security, persistence, ownership, and reclamation read failure is not empty state.** Permission, type, symbolic-link, size, encoding, and I/O errors on evidence used to authorize, reclaim, delete, replace, or mutate state must propagate. Corrupt backup/reconstruction applies only after a successful read proves that JSON content is invalid. Documented read-only discovery may conservatively omit unavailable or unsupported optional metadata only when that omission cannot grant authority, justify reclamation/removal, or trigger a mutation.
+13. **MCP `2026-07-28` is the only native state model; remote initialization compatibility is stateless and bounded.** Shared metadata advertises `2026-07-28` as the native protocol and separately declares the remote-HTTP initialization compatibility dates `2025-06-18` and `2025-11-25`. stdio remains current-only. The compatibility adapter may answer only `initialize`, `notifications/initialized`, `ping`, `tools/list`, and `tools/call`; tool methods execute through the current request-scoped `McpController`. It never creates or accepts `Mcp-Session-Id`, recovery GET, `Last-Event-ID`, persisted replay/delivery state, legacy prepare/subscribe descriptors, or an initialization-owned authorization/session state machine. Other removed protocol behavior receives bounded no-side-effect rejection/upgrade guidance rather than execution.
 14. **Security analysis is a failing gate.** CodeQL or Scorecard execution alone is not success. Generated SARIF must contain no unaccepted result, and missing rule metadata fails closed rather than being interpreted as non-security. An intentional or externally constrained finding requires an exact rule/path record with a substantive rationale and an expiry date.
-15. **Ambiguous health is not permission to repeat a remote write.** A successful Wrangler deployment is recorded before secondary health verification. Timeout, proxy, TLS, network, and temporary service failures preserve the deployment fingerprint and fail for diagnosis; only bounded evidence of a stale identity/version permits automatic same-name redeployment. Changing the Worker name is an explicit remote-resource transition, not a retry strategy.
+15. **Ambiguous health is not permission to repeat a remote write.** A successful Wrangler deployment is recorded before secondary health verification. Timeout, proxy, TLS, network, and temporary service failures preserve the deployment fingerprint and fail for diagnosis; only bounded evidence of a stale identity/version permits ordinary automatic same-name redeployment. During owner-authorized candidate activation, an explicit cryptographic device-authentication rejection after current-version health is separate positive evidence that deployment secrets did not converge; it permits one same-name redeployment with the unchanged selected identity, never rotation or resource renaming. Changing the Worker name remains an explicit remote-resource transition, not a retry strategy.
+16. **Execution continuity and delivery continuity are separate proof obligations.** Current request-scoped HTTP work treats response-stream closure as cancellation and retains no replay record. Same-daemon relay reconnect may rebind an already-dispatched transient call only because the verified daemon still owns that execution; it must never create a client-visible replay/session identity. Work that must survive client delivery loss uses an explicit durable managed-job handle rather than transport replay.
+17. **Remote compound commands are not persistence evidence.** When a remote edit and a long test share one relay call, a transport interruption can obscure whether the edit completed. High-impact writes must be followed by an independent read of stable anchors or a Git diff before tests and conclusions rely on them.
+18. **MCP delivery state is request-scoped, not durable.** One Durable Object fetch owns the current response, the outer Worker keeps an open SSE response observable with bounded comments, and a random private capability indexes only the already-active transient pending call so public stream closure can request cancellation. Public control headers are stripped and private cancel controls carry no OAuth/DPoP credential. MCP code must not add prepare/subscribe delivery descriptors, terminal-result retention, session stores, recovery GETs, replay IDs, or cross-event terminal Promise registries. Durable execution belongs to the managed-job subsystem, whose persisted state machine and deadlines are independent of MCP transport delivery.
+19. **Validation cost is part of the input contract.** Schema compilation and runtime validation have independent depth/node/pattern/issue/work budgets. Every traversed array item and own object property consumes work before recursive validation; code must not allocate an unbounded key/value inventory and only then check limits.
+20. **A pending release candidate is valid only against the current packaged source.** Candidate start/activation must compare package identity and promotion digest before tarball verification, installation, deployment, or service mutation. Tarball-to-manifest integrity alone is insufficient after later edits.
+21. **GitHub publication requires explicit current-task owner authorization and one publication process.** Candidate activation, acceptance, merge, and green CI are evidence, not standing permission to create a tag or Release. Publication must present the explicit `--owner-confirm` acknowledgement and hold the repository publication lock through tag/Release synchronization. The owner may execute the command directly or authorize an agent to do so; a TTY is optional and is not an authorization boundary. Automation must not infer publication permission from an earlier acceptance, merge, or conversation, and an agent must not race an operation the owner says they will execute themselves.
+22. **Capability routing advises; effective policy authorizes.** The resolver may shortlist tool sets, report ambiguity, and suggest fallbacks, but it must neither hide an allowed escape hatch nor recommend a tool outside the request's effective account/daemon intersection. Canonical full continues to expose direct Bash. A routing fallback is not a safety-policy bypass.
+23. **Capability fingerprints reduce repetition, not freshness checks.** A matching client-supplied fingerprint may omit unchanged static instructions, but task-specific ranking, application discovery, and route computation must still run. The fingerprint is not conversation identity, authorization, or a cached execution result.
+24. **Read-only fan-out may be concurrent only when observable order stays sequential.** Independent metadata/file reads may use a small bounded batch, but scheduling count and externally visible visited count are separate. Results and errors are consumed in canonical walk/enumeration order; work prefetched beyond an already-satisfied output/limit stop cannot retroactively fail the completed result. Cancellation is checked before scheduling and before consuming prefetched results.
+25. **Hot read models have semantic output budgets.** A compact/summary projection is computed only after canonical state and authorization decisions. Tests bind required semantic fields, forbidden cold/private fields, absolute size ceilings, and high-cardinality growth behavior. Do not satisfy a size budget by deleting the authority/readiness/inventory facts that make the projection useful.
+26. **Diagnose before changing semantics.** Production failures are classified from exact deployed identity plus privacy-bounded stage evidence before speculative behavior changes. Working notes distinguish observed fact, inference, falsified hypothesis, and unresolved external cause. A generic host error, successful compilation, or green local test is not root-cause evidence.
+27. **Falsified fixes do not silently accumulate.** A live-disproved hypothesis patch is removed before the final candidate unless an independent invariant and regression test justify retaining it. Security or identity mutations such as password/token/device rotation, authentication weakening, state deletion, forced redeployment, or remote-resource renaming are never generic diagnostic resets.
+28. **Hosted-runtime behavior requires hosted-runtime evidence.** Memory fakes and local Wrangler/workerd are necessary regression layers but do not prove deployed-edge storage, request-lifecycle, WebSocket, quota, proxy, or provider behavior. Changes in those domains require a bounded live canary or explicitly documented residual uncertainty before acceptance.
+29. **Multi-record authority state commits through one explicit transaction boundary.** OAuth/account/authority mutations that must become visible together write each named record inside one Durable Object storage transaction and fail atomically. Do not reintroduce a convenience bulk-object `put()` at this security boundary merely because the local emulator accepts it; the transaction path is the production-proven contract and its failure stages remain low-cardinality diagnostics.
+30. **Persistent-state size and cardinality are budgets, not implementation details.** Every high-cardinality map/queue has a hard count bound, a retention/pruning rule, and a serialized-size or row-budget regression where provider limits matter. Retry-only payload is compacted when its retry window ends; a nominal item-count cap is insufficient when one aggregated value can exceed the backend value limit. OAuth refresh consumed-token replay state therefore persists in 8 fixed hash shards with a 1024-record per-shard ceiling while the main refresh value retains active tokens and family tombstones only; all migration and mutation paths reconstruct the same in-memory state and commit main/shards atomically.
+31. **Verification runs require an immutable source snapshot.** A test or release gate that observes a source hot reload, concurrent packaged-file edit, regenerated artifact, or changed candidate identity is invalid evidence even if most tasks passed. Finish writes first, then run the complete gate against the final tree; any later packaged-byte change requires a clean rerun and a new candidate.
+32. **OAuth persistence is a deployed acceptance boundary.** Any change to OAuth grant handling, token storage, account/client trust, replay state, or Durable Object persistence must prove an authorization-code exchange, persisted access and refresh credentials, an authenticated MCP request, and successful refresh rotation against the deployed candidate before acceptance. Relevant TTL/soak survival is verified separately rather than inferred from the initial exchange.
+33. **Computer Use mutation authority is snapshot-bound and one-shot.** `computer_act` may mutate only from the exact bounded snapshot produced by `computer_observe`; preflight is read-only, and the snapshot generation is atomically consumed before backend mutation handoff. Browser document/frame/ref/backend identity and application process/window identity are private authority evidence, not caller-selected parameters. A snapshot ID alone is not authorization and never bypasses ordinary role/policy checks.
+34. **A PID or coercible scalar is never Computer Use authority.** Application snapshots bind PID to the exact public libproc process-birth generation and fail closed when that identity is unavailable or changes. Browser/application actions, coordinates, digests, window IDs/bounds, process generations, resource names, and settlement fields must retain their native producer type; arrays/objects that JavaScript could stringify or numerically coerce are malformed evidence, not alternate encodings.
+35. **Ambiguous UI mutation is never replay evidence.** Once a browser mutation has been handed to the extension transport, or a fixed launch/JXA/native helper has started its process, timeout, cancellation, connection loss, malformed response, process error, or missing settlement cannot be treated as definite non-execution. The public result is non-retryable unknown/pending settlement and the caller inspects post-state or observes again. Pre-dispatch validation and pre-spawn failure remain distinct definite failures. Result-size compaction must preserve this settlement and a usable continuation handle where available; it must not turn an already-issued mutation into a generic size error.
 
 A proposed change that conflicts with an invariant requires an explicit owner decision and corresponding documentation update. It must not be hidden inside an unrelated refactor.
 
 ## Change and release-operation ownership
 
-Repository implementation, interactive candidate acceptance, source release completion, and live release operations are separate responsibilities. Under `AGENTS.md`, coding automation may edit, test, and commit locally, generate an exact candidate tarball, and, after explicit owner authorization in the active conversation, start the exact isolated candidate through Machine Bridge. The agent verifies the deployed Worker version/hash, remote health, relay readiness, and connected local candidate through Machine Bridge and may then record `release-acceptance/v<version>.json`, push only through `npm run github:push`, complete the pull request through local `git`/`gh`, and create the annotated version tag plus final GitHub Release with `npm run release` after the accepted package hash and exact `main` checks pass. The owner is not required to copy approval IDs or run release-authorization commands in a terminal. Automated checks without an observed live candidate do not authorize acceptance. `npm run release` never pushes `main`. Automation must not publish or alter npm packages, install globally outside the isolated candidate prefix, deploy or reconfigure a Worker as a release operation, rotate credentials, mutate live deployment state, or replace daemon/service state without explicit user authorization.
+Repository implementation, candidate preparation, observed live verification, acceptance recording, source pull requests, and explicitly authorized release operations are distinct workflow stages. External/live mutations are not inferred from a version change; they require a current explicit owner request, but they do not require a particular human-vs-agent execution surface.
+
+For each package change, automation runs one complete frozen-tree verification. A successful full run records an ignored owner-local receipt bound to the exact verification generation, package/runtime identity, and a short freshness window; beginning another full run clears prior evidence before tests start. `release:candidate` must consume that matching receipt and therefore does not repeat the same complete suite on the same machine. It then prepares the exact prerelease tarball, and immediately before live activation automation runs `node scripts/start-release-candidate.mjs --install-only` to re-prove current source/package modes, tarball integrity, and disposable installability without live activation. A stale receipt or failed preflight returns ownership to automation to repair, rerun full verification when required, and regenerate the candidate. Only after that succeeds and the owner explicitly authorizes activation may the owner or authorized agent execute `npm run release:candidate:activate -- --allow-worker-deploy`. After that command updates the Worker, verifies candidate relay readiness, replaces the login daemon, and verifies service handoff, the coding agent derives `<activated-runtime-package>` from activation `runtime_entry` and runs `node <activated-runtime-package>/scripts/release-oauth-canary.mjs --allow-live-oauth-canary` as direct argv from the checkout cwd. This bounded synthetic canary is candidate-bound, creates only a temporary reviewer account/client, retains no credential/token evidence, and must prove authorization-code exchange, authenticated MCP, refresh rotation, refreshed MCP, and cleanup. The coding agent then inspects the connected system through Machine Bridge. Only after both proofs may it record candidate acceptance and push through `npm run github:push`.
+
+After merge and exact-commit checks, GitHub tag/Release publication requires explicit owner authorization and uses `npm run prerelease:release -- --owner-confirm`. The command accepts local automation/Machine Bridge execution, but retains exact acceptance, CI, digest, main-head, remote-state reconciliation, and publication-lock gates. npm publication and registry activation are separate explicitly authorized operations through `npm run prerelease:publish` and `npm run prerelease:install -- --allow-worker-deploy`. The owner uses the prerelease for the required interval and explicitly reports whether blocking issues remain. Automation must not infer soak success from elapsed time.
 
-The normal handoff is: the repository owner publishes the reviewed npm version, then runs `npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest && machine-mcp`. The npm command updates the global CLI but cannot hot-reload an existing Node process. The subsequent normal foreground startup validates the Worker deployment hash, expected version, and health, requests shutdown of an active autostart daemon, waits a bounded interval for its lock, redeploys when necessary, and then takes over with the installed version. Live operations require explicit authorization even when they appear to be the obvious next release step.
+Stable promotion is content-preserving. `release:soak:verify` compares the packaged functional digest with the accepted prerelease. A mismatch requires another prerelease and a restarted soak. After stable candidate activation and observed verification, explicitly authorized source publication uses `npm run release -- --owner-confirm`; stable npm publication remains a separate explicit authorization through `npm run stable:publish`.
+
+GitHub/npm publication, global installation, Worker/service replacement, credential mutation, and unrelated live-state changes remain explicit owner decisions. Once a specific operation is explicitly authorized, automation may execute it through the repository's guarded local command unless the owner says they will perform it themselves. GitHub release commands never push `main`.
 
 ## Default instruction invariant
 
@@ -50,21 +80,44 @@ Rules:
 
 - Transport lifecycle, domain execution, persistence, and presentation are separate modules.
 - Domain modules must not import CLI, service, stdio, or relay adapters. Architecture tests enforce this dependency direction for agent context, package metadata, default instructions, capability observation, application automation, process sessions, and proxy selection.
+- Static package identity stays outside persistence ownership: `package-identity.mjs` is the single source for installed package name/version/root and the shared server name. State-root/profile/workspace path and hash semantics remain in `state.mjs` because they depend on platform/environment injection, canonical workspace identity, and case-folding rules used by persistence and locks. Do not create a parallel path helper unless real consumers migrate to it and parity tests bind it to the live persistence contract.
 - Pure classification and normalization functions are exported and tested directly when practical.
 - Adapters may translate data but should not duplicate policy or schemas.
 - Every protocol control message emitted by one side must be explicitly accepted, rejected, or version-gated by the other side, with an end-to-end contract test covering the message name and semantics.
 - State transitions are explicit; readiness is not inferred from a lower-level event. An open WebSocket is not authenticated until `hello_ack`, and authenticated transport is not service readiness until an end-to-end result probe has returned on the same relay session. Pre-ready work and premature readiness acknowledgements fail closed.
-- Every externally controlled input is bounded before expensive allocation, traversal, parsing, storage, or execution.
+- Every externally controlled input is bounded before expensive allocation, traversal, parsing, storage, or execution. A byte limit constrains bytes actually consumed and duration work, not only the subset retained in memory; once a declared or observed bound is crossed, cancel or close the source immediately.
 - Externally controlled string keys must not use prototype-chain membership or truthiness on ordinary objects. Use `Map`, `Set`, `Object.hasOwn`, or null-prototype records for command dispatch, enums, ACLs, form fields, registries, and other key-addressed contracts.
 - Repository text must not contain invisible ASCII controls other than tab, CR, and LF; architecture tests enforce this even when JavaScript syntax remains valid.
-- Persistent mutations use owner-only files, bounded no-follow reads, flushed atomic replacement, and integrity checks appropriate to the data.
-- Exclusive locks use the shared complete-before-visible hard-link claim. Reclamation requires process identity plus a matching file snapshot/token; do not unlink a path merely because an earlier read looked stale.
-- Service providers normalize success/failure to one result contract. Definition removal follows the shared platform-stop → verified-daemon-stop → remove order.
+- Validate authority and object identity before mutation. If a multi-step operation must compensate after partial success, rollback must act on a transaction token, descriptor/snapshot identity, or other object-specific proof; a pathname plus the fact that an earlier step succeeded is not deletion authority. State read-modify-write operations must load their authoritative state after acquiring the mutation lock rather than saving a snapshot read while waiting for the lock. Machine-global service definition/owner/environment mutation must additionally hold the machine-service lock at the actual mutation point; a prior takeover check does not authorize a later unlocked install after network work.
+- Complete-before-visible exclusive publication uses a flushed staging inode plus a no-replace hard link, so a legitimate competing reader can briefly observe the publisher's own second link before staging cleanup. Only readers that are explicitly coupled to this publication protocol may retry the stable `MBM_MULTIPLE_HARD_LINKS` classification, and only for the shared fixed four-attempt/1 ms budget. Persistent hard links remain invalid ownership evidence; ordinary/destructive readers must not convert this retry into general hard-link acceptance.
+- Persistent mutations use owner-only files, bounded no-follow reads, flushed atomic/no-overwrite publication, and integrity checks appropriate to the data. Filesystem device/inode identity is never routed through an unsafe JavaScript Number: security-sensitive comparisons use the shared lossless identity boundary with BigInt default observations, retain exact change-time generation when the platform exposes it, and fail closed when injected metadata cannot be represented exactly. Same `(dev, ino)` after unlink/recreate is not sufficient identity evidence when a generation is known.
+- A transport-surviving operation exposes either authenticated replay or a durable inspection handle. A response stream alone is not durable delivery.
+- After a remote mutation, inspect the persisted file/Git anchors in a separate call before treating a subsequent test as evidence for that exact change.
+- Exclusive locks use the shared complete-before-visible hard-link claim. Ownership bytes plus device/inode/change-time/size/mtime evidence come from one opened descriptor snapshot; ownership locks reject multiple hard links, and release/reclamation rechecks the path generation/identity/token before unlink. Do not combine bytes from one open with identity from a prior path stat, treat an inode number as a permanent generation, or unlink a path merely because an earlier read looked stale.
+- Lock/recovery and destructive-inventory readers distinguish absence, successfully read malformed metadata, and storage failure. Only ENOENT is absence; only bytes that were successfully read and then proved malformed may enter a documented stale-corruption policy. Size, permission, I/O, descriptor, hard-link, and identity failures must propagate and must never become evidence that an owner is absent, reclaimable, or safe to delete. A read path with a legitimate concurrent atomic publisher may explicitly retry the stable `MBM_IDENTITY_CHANGED` condition, but only with a fixed small attempt budget and only when the final stable snapshot is the intended authority; destructive pre-action snapshots must not silently slide to a later object generation.
+- Service providers normalize success/failure to one result contract. Definition removal follows the shared platform-stop → verified-daemon-stop → remove order. Destructive provider cleanup is decided from exit status plus structured pre/post provider state, never by matching localized stderr prose; a missing local definition is not evidence that an in-memory provider process is inactive.
 - Retry is limited to classified transient failures. Authentication, authorization, validation, integrity, and policy errors fail immediately.
-- Cleanup-only catches may be best effort, but primary failures must not be silently discarded.
+- Cleanup-only catches may be best effort only after the primary result is already unambiguous. Before commit, cleanup failure must preserve the primary failure and every relevant cleanup cause. After commit, cleanup failure must not retroactively report the side effect as failed; surface fixed bounded cleanup evidence instead, and fail closed before continuing whenever the leftover artifact can contain credentials, keys, or other sensitive bytes. Rollback of newly created credentials, keys, or other sensitive artifacts is part of the primary integrity result and must attempt every cleanup target.
 - New work should not increase an already broad orchestration module when the behavior has an independent lifecycle or test surface. Extract the domain first.
 
-`runtime.mjs` owns local tool semantics. `relay-connection.mjs` owns authenticated relay connection lifecycle. The CLI orchestrates them; it must not become the second implementation of either.
+`runtime.mjs` owns local tool orchestration, not filesystem lock mechanics. A tool handler returning successfully is the local settlement point: cancellation must be observed at explicit safe/cancellable checkpoints before that point, not used afterward to retroactively replace a completed result. Relay/result ownership may still suppress delivery when a remote caller has stopped waiting; that transport fact is separate from whether local work committed.  File mutations coordinate on already-resolved canonical paths: the same path is serialized, independent paths may proceed concurrently, and a multi-path transaction must reserve every source/destination before awaiting any prior reservation. A cancellation signal must not release a reservation while an already-started filesystem operation can still settle. `relay-connection.mjs` owns authenticated relay connection lifecycle, while `relay-connection-classification.mjs` owns close/error classification, handshake/readiness validation, user-facing relay causes, and reconnect backoff. The CLI orchestrates them; it must not become the second implementation of either.
+
+## MCP and tool-schema contract
+
+MCP protocol identity is request-scoped. Domain execution must not depend on connection history, an HTTP socket, or a process as conversation identity. Native requests are interpreted solely from current per-request metadata. The declared remote-HTTP initialization compatibility may recognize `2025-06-18`/`2025-11-25` initialize-era metadata and dispatch only its bounded stateless method set through the current controller; it must not create protocol state, participate in request identity/cancellation/caching as a session, or reintroduce a second domain protocol implementation. All other removed initialization/session shapes receive bounded upgrade guidance only.
+
+The shared tool catalog is executable schema:
+
+- absent `$schema` means JSON Schema 2020-12;
+- only the explicitly implemented bounded keyword set may be used;
+- unsupported dialects/keywords fail process/module initialization rather than being ignored;
+- external `$ref` values are rejected and never fetched;
+- schema depth, total nodes, regular-expression length, and returned issue count are bounded;
+- Worker validation occurs before daemon dispatch, and local validation remains defense in depth for every transport;
+- validation errors contain paths and constraints, never argument values;
+- a schema or validation change requires direct validator tests plus Worker and stdio integration when observable protocol behavior changes.
+
+`structuredContent` is arbitrary JSON, not object-only. Code must distinguish absence from the valid value `null`; truthiness is not a presence check for structured protocol fields.
 
 ## Logging contract
 
@@ -142,7 +195,7 @@ The required matrix includes:
 - stdio JSON-RPC integration;
 - Worker OAuth/WebSocket/MCP integration;
 - managed-job integrity, recovery, cancellation, cleanup, and redaction;
-- dependency audit, registry signatures/attestations, SBOM, and Worker dry run.
+- dependency audit, registry signatures/attestations, the first-party `sbom:test` CycloneDX identity/graph/privacy check, and Worker dry run.
 
 Cross-platform tests must not depend on shell syntax, case-sensitive Windows paths, Unix-only executable shims, or timing races when a deterministic scheduler can be injected. Local success cannot substitute for the required Linux/macOS/Windows push CI result used by the release gate.
 
@@ -197,3 +250,9 @@ A thorough review asks:
 - Does the change require a new npm version and deployment?
 
 The goal is not cleverness or minimum line count. The goal is explicit boundaries, small state machines, predictable failure behavior, and tests that make future regressions difficult.
+
+### Validation-before-allocation and validation-before-destruction
+
+Security-sensitive state transitions follow two related ordering rules. First, prove authority before allocating scarce state: browser HMAC authentication validates a client init proof before reserving a pending challenge slot, and identical retries are idempotent. Second, validate ownership before destructive mutation: file/service/SSH rollback paths bind deletion to descriptor/generation identity rather than pathname alone. Do not move validation after pending-state insertion, unlink, rename, chmod, or other externally visible mutation merely to simplify control flow.
+
+Approval and authorization parsers also distinguish omission from malformed explicit input. Optional fields may receive documented defaults only when absent; a provided value of the wrong type or unsupported enum must be rejected rather than silently coerced. Persisted security/recovery markers whose `false` value relaxes a safety gate must be type-checked explicitly instead of normalized with `=== true`.

package/docs/GETTING_STARTED.md

@@ -16,7 +16,7 @@ Remote and stdio modes use the same local runtime and policy model. The remote W
 
 ## 2. Understand the authority you are granting
 
-A new workspace uses the `full` profile unless another profile is selected explicitly. `full` preserves the complete tool catalog, shell execution, paths outside the selected workspace, absolute paths, browser/application automation, and the complete parent process environment. It is intended for a trusted owner using a trusted MCP host. An authenticated owner account may use the `full` ceiling directly without terminal approval. Delegated non-owner accounts require local time-bounded capability leases for high-impact effects; their normal workspace reads/edits and project inspection remain automatic. See [LOCAL_AUTHORIZATION.md](LOCAL_AUTHORIZATION.md).
+A new workspace uses the `full` profile unless another profile is selected explicitly. `full` preserves the complete tool catalog, shell execution, paths outside the selected workspace, absolute paths, browser/application automation, and the complete parent process environment. It is intended for a trusted owner using a trusted MCP host. Delegated accounts remain permanently inside their role ceilings; unsupported effects are denied and cannot be enabled by a terminal approval or lease. The default portable root does not access Keychain or request user presence. A separately installed and provisioned macOS trust broker may request user presence once when its Secure Enclave root signs an ephemeral daemon session. See [LOCAL_AUTHORIZATION.md](LOCAL_AUTHORIZATION.md).
 
 For a first connection to an unfamiliar host, start with a narrower profile:
 
@@ -159,17 +159,18 @@ machine-mcp --workspace /path/to/project --profile review
 The first start performs these operations:
 
 1. canonicalizes and remembers the workspace;
-2. creates owner-only per-workspace state and credentials;
-3. opens the Wrangler/Cloudflare sign-in flow when required;
-4. deploys a Worker and Durable Object for that workspace;
-5. installs a platform-native login service unless `--no-autostart` is supplied;
-6. starts an outbound authenticated WebSocket from the local daemon to the Worker;
-7. creates the initial `owner` account when no account exists and prints its generated password once;
-8. prints the remote `/mcp` URL.
+2. creates owner-only per-workspace state and a deployment token version;
+3. retains or creates the owner-only portable device root; when `MBM_MACOS_TRUST_BROKER` explicitly selects a validated provisioned broker, performs the optional two-phase Secure Enclave enrollment and requests user presence only when that root signs the ephemeral daemon session;
+4. opens the Wrangler/Cloudflare sign-in flow when required;
+5. deploys the Worker with the active or pending root public key and verifies health before promoting a pending root;
+6. installs a platform-native login service unless `--no-autostart` is supplied;
+7. starts an outbound WebSocket authenticated by the root-certified in-memory session key;
+8. creates the initial `owner` account when no account exists and prints its generated password once;
+9. prints the remote `/mcp` URL.
 
 The foreground command remains attached to the terminal. Keep it running while testing. The remote Worker cannot execute local tools when no authenticated daemon is connected.
 
-The Worker name is a persistent workspace identity, not a retry counter. A successful Wrangler upload is recorded before health verification, so a later timeout does not require a new name and does not make the next start upload again. Supplying a different `--worker-name` for an initialized workspace requires `--force-worker` because it intentionally creates/replaces a separate Cloudflare Worker identity.
+The Worker name is a persistent workspace identity, not a retry counter. A successful Wrangler upload is recorded before health verification, so a later timeout does not require a new name and does not make the next start upload again. Supplying a different `--worker-name` for an initialized workspace requires `--force-worker` because it intentionally creates/replaces a separate Cloudflare Worker identity. The printed `workers.dev` MCP URL is the standard public endpoint and requires no separately owned domain.
 
 To run only in the background after setup:
 
@@ -196,18 +197,15 @@ Password: account_password_...
 
 Save the generated password in a password manager. It is not stored locally or shown again. Do not place it in a repository, issue, screenshot, chat message, shell history note, or shared document.
 
-Current ChatGPT developer-mode flow, as documented in OpenAI's [Connect from ChatGPT](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt) guide:
+Current ChatGPT custom-app flow, as documented in OpenAI's Apps/Apps SDK guidance:
 
-1. Open ChatGPT settings.
-2. Under **Security and login**, enable **Developer mode** if the account or workspace permits it.
-3. Open **Plugins** and create a developer-mode app.
-4. Enter a descriptive name and the exact printed `/mcp` URL.
-5. Start the connection.
-6. On the Machine Bridge authorization page, verify the displayed client name, redirect URI, and resource.
-7. Enter the Machine Bridge account name and password only after those values are recognized.
-8. Create a new chat and enable the app for that conversation.
+1. In the ChatGPT workspace app settings, create a custom app for the exact printed `/mcp` URL if one does not already exist.
+2. Complete the Machine Bridge OAuth flow. On the authorization page, verify the displayed client name, redirect URI, and resource before entering the Machine Bridge account name and password.
+3. Publish/enable the app for the intended workspace users and review its allowed actions according to workspace policy.
+4. In a supported chat surface, invoke the enabled app using the host's current app-selection or explicit app-routing affordance. ChatGPT UI labels and whether the app is visibly attached before the first invocation can vary by surface and host version.
+5. After changing the MCP tool catalog or input schemas, use the workspace app's refresh/review flow so the host action snapshot matches the running server before relying on new actions.
 
-ChatGPT navigation labels can change. The invariant is that the client must connect to the public `/mcp` endpoint and complete the OAuth authorization page served by the Worker. The same public `/mcp` URL can be entered in Grok where remote MCP configuration is available. Machine Bridge grants CORS response access to the exact `https://grok.com` and `https://x.com` browser origins as well as ChatGPT's current and legacy origins without requiring a Wrangler command. OAuth navigation and form POST requests are not failed solely because an embedded authorization container reports an opaque or different origin. After validation, the consent page CSP includes only the exact registered callback origin so the browser can complete the `303` return.
+An enabled workspace app is not evidence that every existing conversation has the same host-side app route or cached action/tool snapshot. If a fresh supported conversation can call `server_info` but an older conversation fails before any structured Machine Bridge response, do not diagnose the local daemon as platform-disabled; inspect the host conversation/surface route and app/action snapshot first. The transport invariant remains that ChatGPT connects to the public `/mcp` endpoint and completes the OAuth authorization page served by the Worker. The same public `/mcp` URL can be entered in Grok where remote MCP configuration is available. Machine Bridge grants CORS response access to the exact `https://chatgpt.com`, `https://grok.com`, and `https://x.com` browser origins without requiring a Wrangler command. OAuth navigation and form POST requests are not failed solely because an embedded authorization container reports an opaque or different origin. After validation, the consent page CSP includes only the exact registered callback origin so the browser can complete the `303` return.
 
 ### Claude custom connector
 
@@ -336,7 +334,7 @@ Do not point two logical trust domains at one broad parent directory merely to r
 
 ## 13. Upgrade
 
-Version 1 supports only MCP protocol `2025-11-25`; upgrade or reconnect clients that still request an older date. The current 0.18.x state schema remains valid and should be preserved.
+Version 3 supports the current MCP protocol contract advertised by the server and rejects incompatible mixed-version Worker/daemon combinations. Preserve the owner-only state root when upgrading from the immediately preceding supported release; malformed, obsolete, or ambiguous trust state fails closed instead of being guessed or silently regenerated. Follow [UPGRADING.md](UPGRADING.md) for blocked prereleases and coordinated Worker/daemon/browser-extension replacement.
 
 
 Repeat the isolated global installation, then start Machine Bridge in the target workspace:

package/docs/LOCAL_AUTHORIZATION.md

@@ -1,111 +1,154 @@
-# Local transaction authorization
+# Local authorization model
 
-Machine Bridge separates **available capability** from **current remote authority**.
+Machine Bridge treats **capability**, **identity**, and **object ownership** as separate controls. A tool is executable only when every control permits it.
 
-The canonical `full` profile still exposes the complete tool catalog, unrestricted local-user paths, shell execution, browser and application automation, managed jobs, absolute paths, and the complete parent environment. It remains the default for a trusted owner. Version 2.0 does not redefine or narrow that profile.
+For a remote request, effective authority is:
 
-An authenticated `owner` account activates the capabilities permitted by the daemon policy ceiling without a second terminal approval step. This preserves uninterrupted owner automation while retaining OAuth identity binding, account-version revocation, device authentication, and the daemon policy as hard boundaries.
-
-For delegated `reviewer`, `editor`, and `operator` accounts, the local daemon applies a final transaction gate after the Worker and local runtime have checked the account role and daemon policy. Ordinary project work remains automatic; an operation that crosses a consequential boundary requires a short-lived local capability lease.
-
-Local stdio calls are not affected by this remote transaction gate. They remain governed by the selected local policy and the MCP host's own approval model.
-
-## What remains automatic
-
-Remote calls do not require a lease for:
+```text
+daemon capability ceiling
+∩ authenticated account role
+∩ trusted OAuth client binding
+∩ current account version and refresh-token family
+∩ per-object ownership checks
+```
 
-- project discovery, status, diagnostics, ordinary metadata, and owner-configured Machine Bridge Agent guidance intended for MCP clients;
-- reads inside the selected workspace, except credential-sensitive paths;
-- ordinary source and configuration writes inside the selected workspace, excluding credential- and persistence-sensitive targets;
-- transactional patches whose source, destination, and move targets remain inside the selected workspace and outside sensitive targets;
-- Git inspection;
-- browser broker status without reading profile content;
-- installed-application discovery without inspecting an application UI;
-- registered-resource metadata inspection.
+No approval record, token refresh, client reconnect, or local command can expand the account role. A narrower layer always wins.
 
-This is the normal delegated-account coding and review path. A trusted owner is not interrupted by local approval prompts. For non-owner browser work, one reusable profile-session lease covers the session rather than prompting per page read, field, or click.
+Local stdio does not use remote OAuth accounts. It runs as the local owner under the selected local policy and remains subject to the MCP host and operating-system controls.
 
-## What requires a lease
+## Account roles
 
-The daemon requests local authorization for these remote effects:
+| Role | Effective purpose | Important limits |
+|---|---|---|
+| `reviewer` | Read-only inspection of the selected workspace | No mutation or process execution |
+| `editor` | Workspace reads and deterministic file mutation | No process execution |
+| `operator` | Workspace-confined editing and direct process execution | No unrestricted paths, credentials, browser/desktop control, or persistent job creation |
+| `owner` | Complete bridge authority within the daemon policy ceiling | Generic path-based tools cannot target Machine Bridge control-plane state; owner shell remains OS-user authority |
 
-| Scope | Examples |
-|---|---|
-| `shell` | shell commands, direct process launch, process output continuation, interactive process input or termination, registered local commands |
-| `external-read` | reading, searching, imaging, or inspecting a path outside the selected workspace |
-| `sensitive-read` | reading credential-sensitive locations or names such as SSH/AWS/Keychain state, `.env`, tokens, secrets, or private keys |
-| `external-write` | writing, editing, patching, or moving a patch target outside the selected workspace |
-| `sensitive-write` | writing credentials, live `.env` files, SSH/privilege files, shell startup files, Git hooks, LaunchAgents/LaunchDaemons, or other persistence-sensitive paths even when they are inside the selected workspace |
-| `browser-session` | listing or reading tabs, source, screenshots, waits, navigation, form input, clicks, submission, tab management, or extension pairing in the existing browser profile |
-| `data-export` | uploading a file, inserting a registered local resource into a browser or desktop application, or filling an explicitly sensitive browser field |
-| `persistent-job` | staging, starting, listing, reading output from, or cancelling a managed job |
-| `application-control` | opening, inspecting, or operating a desktop application |
-| `credential-operation` | generating an SSH key resource |
-| `full` | all of the above for one explicit temporary automation window |
+The package catalog defines the stable discovery surface. The Worker filters `tools/list` by account role without rewriting it during a brief daemon outage. The live daemon advertisement remains the execution ceiling, and the local runtime independently recomputes and validates the role and policy boundary before dispatch.
 
-Classification uses canonicalized paths and bounded operation metadata. A single operation may require more than one scope: for example, a browser upload requires both `browser-session` and `data-export`, and an external credential read requires both `external-read` and `sensitive-read`. Existing leases may satisfy those scopes independently. A pending approval contains only the scopes still missing, and approving it creates one compound lease for those missing scopes. Pending records contain a SHA-256 target digest, not command text, file contents, form values, or uploaded bytes.
+## Trusted OAuth clients
 
-Write targets are canonicalized through their nearest existing ancestor even under `full`. A path that enters an in-workspace symbolic-link directory is classified by the real destination, while overwriting a final symbolic link is rejected. Patch `Move to` destinations are classified alongside add/update/delete paths. This preserves unrestricted-path capability without allowing path aliases to weaken the lease boundary.
+Dynamic OAuth registration creates an untrusted client record. The first successful account authorization binds that client to:
 
-The browser boundary is intentionally session-granular. The packaged extension controls whichever Chromium profile the user loaded it into; Machine Bridge cannot prove that the profile is isolated. Requiring one `browser-session` lease protects tab metadata and authenticated page content without degrading into per-click prompts. Once granted, ordinary browser reads, navigation, filling, and clicks proceed continuously until expiry. Exporting registered local data remains separately gated.
+- one account ID;
+- the account version at authorization time;
+- the account role;
+- the OAuth client ID.
 
-## Optional delegated-account approval flow
+A client cannot silently switch to another account. Account disablement, role changes, password rotation, client revocation, token-version rotation, and refresh-token replay outside the bounded concurrent-refresh window invalidate the relevant credentials.
 
-Owner requests never create pending approval IDs. When a lease is missing for a non-owner account, the tool call fails with `local_approval_required` and a command containing a random pending approval ID. List pending requests and active leases locally:
+Inspect trusted clients locally:
 
 ```sh
-machine-mcp --workspace /path/to/project approval list
+machine-mcp account clients --workspace /path/to/project
 ```
 
-Approve only the requested scope for one hour:
+Revoke one client and all of its authorization codes, access tokens, and refresh tokens:
 
 ```sh
-machine-mcp --workspace /path/to/project approval approve APPROVAL_ID --duration 1h
+machine-mcp account revoke-client CLIENT_ID --workspace /path/to/project
 ```
 
-Then retry the original task. Further matching operations from the same account and OAuth client run without interruption until the lease expires.
+Account-management requests are signed by a root-certified ephemeral device session. Machine Bridge does not deploy or retain a long-lived account-administration bearer or HMAC secret.
 
-For a trusted, intensive automation session, convert the same pending request into an explicit temporary `full` window:
+## Automatic execution
 
-```sh
-machine-mcp --workspace /path/to/project approval approve APPROVAL_ID --full
-```
+There is no per-operation approval prompt in the current runtime.
 
-`--full` defaults to eight hours and cannot exceed eight hours. It is local, account-bound, client-bound, time-bounded, and revocable. It does not change the saved policy profile or extend itself remotely.
+Within the effective role and daemon ceiling, calls execute automatically. Outside that intersection, calls fail immediately with `authorization_denied`; the response does not contain an approval ID or a command to retry.
 
-A specific scope can also be granted in advance. Account and OAuth client IDs are available from `approval list --json` after the client has produced a pending request. Wildcards are supported only when entered explicitly:
+Examples:
 
-```sh
-machine-mcp --workspace /path/to/project approval grant shell \
-  --account ACCOUNT_ID --client CLIENT_ID --duration 2h
-```
+- a reviewer may inspect files inside the selected workspace;
+- an editor may update ordinary workspace files;
+- an operator may run a workspace-confined process only when the delegated process sandbox is behaviorally verified;
+- an owner may use shell, unrestricted paths, browser/application automation, resources, and managed jobs when enabled by the daemon policy.
 
-## Revocation
+Risk classification still runs for every consequential request. It supplies structured audit metadata and enforces hard boundaries; it is not a mechanism for temporary privilege escalation.
 
-Revoke one lease:
+## Hard boundaries
 
-```sh
-machine-mcp --workspace /path/to/project approval revoke LEASE_ID
-```
+### Machine Bridge control plane
 
-Revoke every active remote capability lease for the workspace:
+Generic path-based file, image, search, and patch tools cannot target Machine Bridge state, device-root metadata, account-management state, audit-chain state, service metadata, or other protected roots. This applies to `owner` as well as delegated accounts.
 
-```sh
-machine-mcp --workspace /path/to/project approval clear
-```
+This is an application-level path boundary, not an arbitrary-code sandbox. An authorized `owner` shell or interpreter has the daemon OS user's ambient filesystem authority. Control-plane administration uses local CLI interfaces; mutually untrusted owner execution requires external OS isolation.
+
+### Sensitive and persistent targets
+
+Non-owner accounts cannot access credential- or persistence-sensitive targets, including live environment files, private keys, token stores, shell startup files, Git hooks, privilege configuration, LaunchAgents, LaunchDaemons, and equivalent persistence locations.
+
+Final symbolic-link overwrites are rejected. Existing ancestors and patch move destinations are canonicalized before classification so a workspace alias cannot conceal an external or sensitive destination.
+
+### Browser, desktop, and data export
+
+Only `owner` may control the existing browser profile or desktop applications, upload local files, or inject registered resources into an interactive session. Browser and application actions operate on the user's logged-in session and therefore are not delegated to lower roles.
+
+### Persistent jobs
 
-Stopping the daemon prevents execution while it is offline, but leases remain in owner-only state until expiry or explicit revocation. Incident response should therefore stop the daemon, clear leases, revoke or rotate affected OAuth credentials, and inspect account/client state.
+Only `owner` may create persistent execution plans with `start_job` or non-executing drafts with `stage_job`.
 
-## Binding and storage
+`stage_job` does not execute and is not an approval workflow. The removed `machine-mcp job approve` path cannot turn a draft into a running job. Execution requires a trusted owner request through `start_job`, or an explicit local `job submit` operation performed by the machine operator.
 
-Every lease binds:
+## Delegated process isolation
+
+An `operator` process is not accepted merely because its current directory and environment are restricted. Machine Bridge requires a behaviorally verified OS sandbox that:
+
+- exposes the selected workspace and an isolated runtime directory;
+- blocks the real user home and Machine Bridge state;
+- blocks Keychain and desktop automation access;
+- preserves the minimum system runtime needed by ordinary tools.
+
+The probe is fail-closed. The presence of a sandbox executable is not sufficient.
+
+On platforms where the negative security boundary cannot be verified, delegated process execution is unavailable. Owner execution remains governed by the selected daemon policy. For mutually untrusted workloads, use a separate OS account, container, or VM.
+
+Implementation-owned metadata probes are a separate boundary from delegated arbitrary execution. `project_overview` and the read-only Git tools use fixed argv selected by Machine Bridge, never a caller-provided executable or shell string. Those probes run with a minimal isolated environment, bounded output and deadlines, cancellation/process-tree tracking, and the request’s path-visibility rules. They do not grant `run_process`, registered-command, or shell authority to reviewer/editor accounts.
+
+## Object ownership
+
+Long-lived runtime objects bind to the principal that created them:
 
 - account ID;
+- account version;
 - OAuth client ID;
-- one or more explicitly approved scopes, or the standalone `full` scope;
-- creation and expiration times;
-- an optional source pending-approval ID.
+- refresh-token family ID.
+
+The binding applies to interactive processes, retained command-output sessions, and managed jobs. Another account, client, or refresh family cannot read, continue, send input to, cancel, or terminate those objects.
+
+## Device-root authorization
+
+The default root on every platform is a portable owner-only P-256 key. It signs the 24-hour ephemeral session certificate without Keychain access or a user-presence prompt. On macOS, `MBM_MACOS_TRUST_BROKER` may explicitly select a separately provisioned app-like broker; only after its code signature, Team ID, canonical non-symlink path with no group/other write access, and real Secure Enclave key probe validate does a non-exportable root replace the portable provider. That provider requests user presence once when signing the daemon session certificate. The private session key remains in memory and handles WebSocket preflight, challenge authentication, reconnects, and local account administration for that daemon lifetime.
+
+Expected interaction frequency:
+
+- ordinary tool calls: no local prompt;
+- portable-root daemon startup: no prompt;
+- provisioned Secure Enclave daemon startup: one user-presence prompt;
+- network reconnect: no prompt;
+- an independent account-management command: no prompt with a portable root, or one prompt with a provisioned Secure Enclave root;
+- root rotation: one explicit operation, with user presence only when the provisioned broker requires it.
+
+Every platform uses the portable P-256 provider unless an explicitly configured non-exportable platform provider has been installed and validated. `server_info.security.device_root` reports the active provider and whether the root key is exportable.
+
+## DPoP
+
+OAuth clients that support DPoP may bind access and refresh tokens to their own P-256 key. The Worker validates the proof method, URL, timestamp, nonce identifier, access-token hash, and key thumbprint. A copied token is insufficient without the client private key.
+
+Bearer remains available for MCP hosts that do not implement DPoP. Client trust, account versioning, refresh-family rotation, and role ceilings still apply.
+
+## Audit and incident response
+
+The local security audit is a bounded SHA-256 hash chain. It records operation class, outcome, duration, byte counts, and pseudonymous target/principal references. Target and account/client/family identifiers are HMAC-keyed with fresh per-daemon runtime keys before persistent state applies its per-file salt; the resulting references remain useful for within-runtime correlation without making the stored public salt sufficient for offline identifier/path enumeration. They are not stable cross-restart identities. The audit does not record command text, file paths, file contents, form values, or tool output.
+
+For incident response:
 
-Normal scopes may last at most twelve hours. `full` may last at most eight hours. Pending requests expire after ten minutes. Lease and pending files are size-bounded, owner-only, atomically replaced, schema-validated, and validated record by record. Daemon-created pending requests and separate CLI approval/revocation processes serialize mutations through an owner-only process-identity lock, preventing lost updates during concurrent use. Malformed state or lock metadata fails closed.
+1. stop the daemon;
+2. revoke the affected OAuth client or disable the account;
+3. rotate the account password or global token version when appropriate;
+4. rotate the device root when device identity may be compromised;
+5. inspect the audit-chain health and local endpoint logs;
+6. restart and reconnect only trusted clients.
 
-This is an application-level control, not an OS sandbox. A process already running as the same OS user can interfere with local files and memory. Use a separate OS account, VM, or container when the client, repository, or instructions are mutually untrusted.
+Legacy capability-lease files from version 2 may still be listed, revoked, or cleared by the local CLI for migration cleanup. The version 3 runtime never consumes them and never creates pending approval IDs.