machine-bridge-mcp 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.8.0 - 2026-07-11
+
+### Architecture
+
+- Rename the transport-independent tool engine from `LocalDaemon`/`daemon.mjs` to `LocalRuntime`/`runtime.mjs`, reserving daemon terminology for the background process and relay attachment.
+- Extract authenticated WebSocket lifecycle into `relay-connection.mjs`, separating transport state, handshake readiness, heartbeat liveness, reconnect backoff, and outage observability from local file/Git/process execution.
+- Add `docs/ENGINEERING.md` as the normative record for product invariants, architectural boundaries, logging semantics, resilience, testing, documentation, and public-versus-local project knowledge. Record the owner-required default `full` profile as an explicit invariant.
+
+### Logging and operator experience
+
+- Replace raw default-level relay close output such as `{"code":1006,"reason":""}` with a state-transition policy: brief self-healing interruptions are debug-only, sustained outages produce one rate-limited actionable warning, and recovery produces one duration/attempt summary.
+- Keep WebSocket close codes, reason strings, retry delays, heartbeat details, and brief recoveries at debug level. Expand coarse operational error classification for network and authentication failures; treat authentication and relay identity/version mismatch as immediate actionable fatal errors rather than retryable network outages.
+- Add an ignored `.project-local/` area for machine-specific maintenance notes while keeping reusable decisions in tracked documentation and credentials out of both.
+
+### Reliability and correctness
+
+- Treat a WebSocket `open` event only as transport availability; authenticated relay readiness now requires `hello_ack`. Remove the startup path that printed `Remote MCP bridge is ready` after a timeout even when authentication had not completed.
+- Terminate and retry candidates that do not acknowledge the daemon handshake, detect silent half-open connections through inbound heartbeat timeouts, and preserve bounded exponential reconnect backoff.
+- Handle Cloudflare Durable Object `webSocketError` as well as `webSocketClose`, immediately rejecting pending calls bound to the failed socket through one idempotent cleanup path.
+- Consolidate managed-job transition/recovery locking into one stale-PID-aware primitive and manager/runner regular-file reads into one no-follow bounded helper, with direct regression tests.
+- Replace mechanical runtime/CLI switch and conditional routing with catalog-checked handler tables and named command phases while preserving explicit patch, runner, and recovery state machines.
+- Replace technical Worker health warning details at default level with a user-facing reason while retaining the raw health code at debug.
+
+### Installation, tests, and documentation
+
+- Use the empirically verified npm 12 global install command with `--omit=optional` and the reviewed `esbuild,workerd,sharp,fsevents` script names. Add an isolated tarball/global-install smoke test that rejects blocked-script warnings, verifies `fsevents` is absent from the installed runtime, and executes the installed CLI.
+- Add deterministic relay lifecycle tests for authenticated readiness, brief-interruption suppression, persistent-outage escalation, recovery summaries, handshake/heartbeat timeout, transport construction/error paths, supersession, acknowledgement identity/version mismatch, and close-code classification. Add architecture/documentation regression checks for module cycles, obsolete naming, broken links, invisible ASCII controls, and retained engineering invariants.
+- Update architecture, operations, logging, privacy, testing, contribution, README, and CLI guidance to match the implemented behavior.
+
 ## 0.7.1 - 2026-07-11
 
 ### Fixed

package/CONTRIBUTING.md

@@ -21,3 +21,11 @@ A privacy or security correction is always release-relevant. Removing a private
 ## Privacy
 
 Use only synthetic names, reserved example domains, and generic paths. Maintain private local identifiers in the ignored `.privacy-denylist` and run `npm run privacy:check` before committing.
+
+## Engineering standards
+
+Read [docs/ENGINEERING.md](docs/ENGINEERING.md) before changing architecture, policy, logging, persistence, transport lifecycle, or release behavior. The default `full` profile is an explicit product invariant and must not be narrowed by an unrelated change.
+
+A log change is behavior: test its level, repetition policy, privacy fields, and recovery message. A transport change must distinguish low-level connectivity from authenticated readiness and test timeout/reconnect branches deterministically.
+
+Reusable decisions belong in tracked documentation. Keep only machine-specific observations in the ignored `.project-local/` directory, and never store credentials there.

package/README.md

@@ -48,10 +48,10 @@ This default prioritizes usability, not least privilege. `run_process` and proce
 Node.js 26 or newer and npm 12 or newer are required. The repository pins the active development versions in `.node-version`, `.nvmrc`, and `packageManager`; project installs fail on older Node runtimes.
 
 ```sh
-npm install -g --allow-scripts=esbuild,workerd,sharp machine-bridge-mcp@latest
+npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
 ```
 
-Recent npm releases may otherwise warn that Wrangler's native dependencies (`esbuild`, `workerd`, and `sharp`) have install scripts awaiting approval. The scoped command above approves only those packages for this installation; it does not change the user's global npm policy. A plain install can still work when compatible prebuilt artifacts are already available, but `machine-mcp doctor` is the authoritative runtime check.
+Recent npm releases may otherwise warn that Wrangler's native dependencies (`esbuild`, `workerd`, and `sharp`) have install scripts awaiting approval. The scoped command approves the reviewed native script names that npm 12 evaluates during global resolution while `--omit=optional` keeps optional `fsevents` out of the installed runtime. `fsevents` is used for development-time filesystem watching rather than Machine Bridge runtime or deployment. It does not change the user's global npm policy. `machine-mcp doctor` remains the authoritative runtime check.
 
 From a source checkout, the checked-in exact-version `allowScripts` policy approves the reviewed native dependencies:
 
@@ -335,7 +335,7 @@ Default state roots:
 
 State/config writes use owner-only temporary files, flushes, and atomic rename. Malformed state is retained as a bounded corrupt backup before reconstruction. Resource source paths are redacted from `status` output. Active managed-job plans are owner-only and are deleted after a terminal result; bounded redacted results are retained temporarily. Uninstall validates markers, canonical paths, active locks, workspace/source exclusions, and known contents before recursive deletion.
 
-Default foreground logs show startup/deployment transitions, relay connectivity, and infrastructure warnings/errors. Every per-tool event—including success, failure, cancellation, and slow-call timing—appears only at `--log-level debug` or `--verbose`. Background services use `warn`, so ordinary tool outcomes never fill daemon logs. Log messages and structured fields are bounded, secret-like keys and known token formats are redacted, and tool arguments/results are not written. See [docs/LOGGING.md](docs/LOGGING.md) and [docs/OPERATIONS.md](docs/OPERATIONS.md).
+Default foreground logs report authenticated relay readiness, persistent degradation, and recovery summaries rather than raw WebSocket callbacks. Brief self-healing disconnects and close codes/reasons are debug-only. Every per-tool event—including success, failure, cancellation, and slow-call timing—also appears only at `--log-level debug` or `--verbose`. Background services use `warn`, so ordinary tool outcomes and brief network changes do not fill daemon logs. Log messages and structured fields are bounded, secret-like keys and known token formats are redacted, and tool arguments/results are not written. See [docs/LOGGING.md](docs/LOGGING.md) and [docs/OPERATIONS.md](docs/OPERATIONS.md).
 
 ## Development and verification
 
@@ -348,9 +348,9 @@ npm audit --omit=dev --audit-level=high
 npm pack --dry-run
 ```
 
-`npm run check` covers privacy and release-impact gates, generated Worker types, TypeScript, JavaScript syntax, the shared tool catalog, local path/write/process/state/log/service invariants, Ed25519/RSA generation and key-pair validation, real-machine `full` sandbox acceptance, a clean npm package-manifest/sensitive-artifact check, managed-job detachment/resource redaction/finally/cancellation/recovery, a live stdio MCP flow, and a live local OAuth/Worker/WebSocket/MCP flow. GitHub Actions runs the suite on Linux, macOS, and Windows with the pinned Node 26/npm 12 baseline.
+`npm run check` covers privacy and release-impact gates, architecture/link invariants, generated Worker types, TypeScript, JavaScript syntax, catalog-to-runtime handler parity, deterministic relay lifecycle and secure-file tests, local path/write/process/state/log/service invariants, Ed25519/RSA generation and key-pair validation, real-machine `full` sandbox acceptance, a clean npm package-manifest/sensitive-artifact check, managed-job integrity/redaction/finally/cancellation/recovery, a live stdio MCP flow, and a live local OAuth/Worker/WebSocket/MCP flow. GitHub Actions runs the suite on Linux, macOS, and Windows with the pinned Node 26/npm 12 baseline; macOS and package-audit jobs also exercise the documented isolated global installation.
 
-See [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), and [SECURITY.md](SECURITY.md).
+See [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), and [SECURITY.md](SECURITY.md).
 
 ## Uninstall
 

package/docs/ARCHITECTURE.md

@@ -24,7 +24,7 @@ A canonical workspace receives an independent profile, Worker name, secret set,
 
 ### Local runtime
 
-`LocalDaemon` is transport-independent despite its historical name. It owns:
+`LocalRuntime` is the transport-independent local tool engine. It owns:
 
 - canonical path resolution and display-path privacy;
 - file, text search, image, patch, and Git operations;
@@ -36,7 +36,7 @@ A canonical workspace receives an independent profile, Worker name, secret set,
 - child-process tracking and cancellation;
 - output, traversal, concurrency, and time limits.
 
-Remote mode attaches WebSocket connection/reconnect behavior. Stdio mode invokes the same runtime directly.
+`RelayConnection` owns remote WebSocket transport, authenticated `hello_ack` readiness, heartbeat liveness, reconnect backoff, and outage logging. Stdio mode invokes `LocalRuntime` directly without that adapter.
 
 ### Managed job runner
 
@@ -177,13 +177,15 @@ Managed jobs use the same argv/environment primitives but a different lifecycle.
 
 ## Daemon reconnect and replacement
 
-The daemon sends heartbeats and reconnects with bounded exponential backoff and jitter. Only one socket is active. A new connection is a bounded candidate until it authenticates and completes `hello`; a Durable Object alarm enforces the deadline across hibernation. Only a completed candidate replaces the old socket.
+The local `RelayConnection` treats transport open, authenticated readiness, and outage recovery as separate states. It sends `hello` after WebSocket open and reports readiness only after `hello_ack`. A missing acknowledgement reaches a local handshake deadline and the candidate is terminated. Once ready, application heartbeats require inbound activity; a silent half-open socket is terminated and reconnected.
 
-Pending calls retain their originating socket reference. A stale socket cannot complete or cancel replacement-socket calls. Closing a socket rejects only calls assigned to it.
+Reconnect uses bounded exponential backoff with jitter. Brief self-healing interruptions are debug-only. An unresolved outage is promoted to a rate-limited warning after a grace period, and recovery produces one summary. Raw close codes and reason strings remain debug-only.
+
+The Worker also treats a new connection as a bounded candidate until it authenticates and completes `hello`; a Durable Object alarm enforces the deadline across hibernation. Only a completed candidate replaces the old socket. Pending calls retain their originating socket reference. A stale socket cannot complete or cancel replacement-socket calls. Closing a socket rejects only calls assigned to it.
 
 ## Persistence
 
-Local state and global config are owner-only, versioned, size-bounded, and written through temporary files, flushes, and atomic rename. State, managed-job manager, and detached runner commits share a bounded retrying atomic-replace primitive for transient Windows `EPERM`, `EACCES`, `EBUSY`, and `ENOTEMPTY` sharing failures. Reads reject symbolic links and use no-follow descriptors where supported. Malformed or oversized state becomes a bounded-count `.corrupt-*` backup. Resource paths are omitted from redacted status output. Custom roots are adopted only when empty or recognizable as legacy Machine Bridge state.
+Local state and global config are owner-only, versioned, size-bounded, and written through temporary files, flushes, and atomic rename. State, managed-job manager, and detached runner commits share a bounded retrying atomic-replace primitive for transient Windows `EPERM`, `EACCES`, `EBUSY`, and `ENOTEMPTY` sharing failures. Managed-job manager and detached runner use one shared no-follow, size-bounded regular-file reader; transition and recovery locks use one PID-lock primitive with bounded stale-lock reclamation and optional runner handoff. Malformed or oversized state becomes a bounded-count `.corrupt-*` backup. Resource paths are omitted from redacted status output. Custom roots are adopted only when empty or recognizable as legacy Machine Bridge state.
 
 Active managed jobs persist an owner-only plan, status, runner PID, and bounded runner diagnostics. Terminal jobs delete the full plan and retain only bounded status/redacted results for up to seven days. This balances crash cleanup with minimization of scripts, stdin, argv, environment overrides, and resource source paths.
 
@@ -195,7 +197,7 @@ OAuth metadata is pruned on access. Expired codes/tokens, old throttling records
 
 Public health exposes only server identity and version. Authenticated `server_info` exposes bounded runtime status, policy origin/revision, managed-job counts, resource alias names without paths or values, and the daemon/relay-advertised tool counts. It explicitly reports that the host-exposed subset is unknown to the server. `diagnose_runtime` runs fixed local probes and explicitly reports that its own request reached the daemon.
 
-Foreground logging defaults to `info`; autostart uses `warn`. All per-tool starts, successes, failures, cancellations, durations, and shortened random correlation IDs are debug-only. Normal logs retain deployment, connection, protocol, service, and infrastructure events rather than duplicating MCP tool outcomes. Unexpected local and Worker infrastructure errors are reduced to classes. Messages, strings, arrays, object depth/key counts, and serialized fields are bounded.
+Foreground logging defaults to `info`; autostart uses `warn`. Authenticated readiness, persistent degradation, and recovery are user-visible state transitions. Brief relay interruptions, raw transport close details, retry timing, and all per-tool starts/successes/failures/cancellations/durations are debug-only. Unexpected local and Worker infrastructure errors are reduced to classes. Messages, strings, arrays, object depth/key counts, and serialized fields are bounded.
 
 Cloudflare sampling is size control rather than an audit log. The project intentionally does not claim complete forensic logging. See [LOGGING.md](LOGGING.md).
 

package/docs/ENGINEERING.md

@@ -0,0 +1,159 @@
+# Engineering principles and maintenance rules
+
+This document records project-wide decisions that must survive individual fixes, releases, and maintainers. It is normative for repository changes. Machine-specific observations belong in the ignored `.project-local/` directory instead.
+
+## 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.
+2. **Named profiles are canonical contracts.** A state labelled `full`, `agent`, `edit`, or `review` must match the complete capability set for that name. Per-capability overrides produce `custom` rather than a misleading named profile.
+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 version across all surfaces.** Package metadata, Worker version, Git tag, GitHub Release, npm version, documentation, and deployed health version must agree before a release is considered complete.
+
+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.
+
+## Architectural boundaries
+
+The preferred dependency direction is:
+
+```text
+shared metadata and pure policy
+        |
+local runtime domain modules        Worker domain modules
+        |                                  |
+stdio adapter / relay connection     HTTP + OAuth + WebSocket adapter
+        |                                  |
+CLI, service, release, and deployment orchestration
+```
+
+Rules:
+
+- Transport lifecycle, domain execution, persistence, and presentation are separate modules.
+- Pure classification and normalization functions are exported and tested directly when practical.
+- Adapters may translate data but should not duplicate policy or schemas.
+- State transitions are explicit; readiness is not inferred from a lower-level event. For example, an open WebSocket is not an authenticated relay until `hello_ack` is received.
+- Every externally controlled input is bounded before expensive allocation, traversal, parsing, storage, or execution.
+- 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 reads, atomic replacement, and integrity checks appropriate to the data.
+- 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.
+- 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.
+
+## Logging contract
+
+Operational logs are a user interface, not a dump of protocol events.
+
+### Default-level rules
+
+- Describe user-relevant state and automatic remediation in plain language.
+- Prefer state transitions and recovery summaries over event pairs.
+- Suppress brief self-healing transport interruptions from `info` and `warn`.
+- Escalate a connection outage only after it remains unresolved for the configured grace period.
+- Rate-limit repeated degradation warnings and emit one recovery summary after a visible outage.
+- Do not expose WebSocket close codes, empty reason strings, stack traces, raw URLs with credentials, or internal identifiers at default levels.
+- Include fields only when they help a user decide what happened or what to do next.
+
+### Level meanings
+
+- `error`: the requested operation or long-lived service cannot continue without intervention.
+- `warn`: persistent degradation, rejected protocol data, supersession, or a service problem requiring attention.
+- `info`: successful startup, authenticated readiness, deployment, and recovery from a previously visible degradation.
+- `debug`: raw transport codes/reasons, retry timing, correlation identifiers, per-tool outcomes, and implementation diagnostics.
+
+A warning must answer at least one of these questions: what is degraded, whether recovery is automatic, and what action is required if recovery fails.
+
+### Review test
+
+Before adding a default-level log, ask:
+
+1. Is this a user-visible state change rather than an implementation callback?
+2. Is the severity correct if the system recovers automatically within seconds?
+3. Is every field understandable without consulting a protocol specification?
+4. Could the message reveal a path, identity, command, content, or credential?
+5. Will this line remain useful if the event repeats one hundred times?
+
+See [LOGGING.md](LOGGING.md) for the concrete event policy.
+
+## Complexity and state-machine exceptions
+
+Mechanical routing, option validation, and output formatting should be table-driven or split into named handlers. Catalog-to-handler parity must be executable, not inferred from a switch statement.
+
+A higher branch count is acceptable only when the function is an explicit state machine whose ordering is part of the safety argument, such as patch parsing, detached job execution, or recovery reconciliation. Such functions require focused transition and failure-path tests. Do not fragment them merely to satisfy a numeric complexity threshold; do not use this exception for ordinary command dispatch or mixed responsibilities.
+
+## Error handling and resilience
+
+- Preserve a stable coarse error class for automation and a concise human message for operators.
+- Do not retry an operation merely because it failed; retry only when the error is positively classified as transient and the operation is idempotent or server state is checked after ambiguity.
+- When a remote write may have succeeded before the response was lost, query authoritative state before repeating it.
+- Timeouts must terminate the relevant process or connection and clear delayed escalation timers after exit.
+- Half-open connections need liveness detection, not only periodic writes.
+- Lock reclamation must consider both process liveness and absolute age to defend against PID reuse.
+- A recovery path must be bounded and converge to a terminal state rather than retry forever.
+
+## Testing rules
+
+Every defect fix includes a regression test that fails for the original reason. Prefer two layers when applicable:
+
+1. a deterministic test of the extracted policy or lifecycle;
+2. an integration test proving the adapter uses it correctly.
+
+The required matrix includes:
+
+- Linux, macOS, and Windows on the pinned Node/npm baseline;
+- privacy and release-impact gates;
+- package-manifest and sensitive-artifact inspection;
+- type and syntax checks;
+- local runtime and real `full` acceptance tests;
+- 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.
+
+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.
+
+## Documentation rules
+
+- README explains the supported user path and major risks.
+- ARCHITECTURE describes boundaries, trust, and state machines.
+- SECURITY states guarantees and explicit non-guarantees.
+- LOGGING defines operator-facing event semantics.
+- OPERATIONS contains diagnosis and recovery procedures.
+- TESTING records executable coverage and regression expectations.
+- CHANGELOG records externally relevant changes, including documentation and workflow changes.
+
+Documentation that claims a guarantee must identify the code or test enforcing it. Do not document an aspirational behavior as implemented.
+
+## Public and local project knowledge
+
+Reusable decisions, invariants, incident lessons, and review rules belong in tracked documentation. Hiding them in local notes causes repeated mistakes.
+
+Use the ignored `.project-local/` directory only for machine-specific material such as:
+
+- local package-manager or service layout;
+- temporary release blockers and authentication state;
+- private deployment identifiers;
+- one-machine recovery steps;
+- observations that still require validation before becoming a general rule.
+
+Do not store passwords, tokens, private keys, authorization URLs, or copied secret-bearing logs there. Use `.privacy-denylist` for private vocabulary that the scanner should reject from publication surfaces.
+
+When a local observation becomes generally true, move the sanitized lesson into tracked documentation and delete the stale local note.
+
+## Review checklist
+
+A thorough review asks:
+
+- Can the module name and boundary be understood without historical context?
+- Is there one authoritative implementation of each policy and schema?
+- Are all success, failure, cancellation, timeout, disconnect, restart, and recovery branches bounded and tested?
+- Are logs actionable, rate-limited, and privacy-preserving?
+- Are persistent files atomic, owner-only, size-bounded, and symlink-aware?
+- Can a stale PID, stale socket, duplicate request, partial write, or ambiguous remote response violate integrity?
+- Are package, CI, Worker, service, and release behavior tested on every supported platform?
+- Does the complete diff contain any real identifier, path, host, account, or credential-shaped value?
+- 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.

package/docs/LOGGING.md

@@ -1,13 +1,16 @@
 # Logging and observability
 
+Operational logs are a user-facing diagnosis surface. They report meaningful service state without becoming a transcript of user activity or a dump of transport callbacks.
+
 ## Goals
 
-Operational logs should answer four questions without becoming a transcript of user activity:
+Logs should answer:
 
-1. Did deployment and relay connection succeed?
-2. Is the daemon reconnecting, superseded, or unhealthy?
-3. Is an infrastructure, protocol, deployment, or relay failure occurring?
-4. When debug logging is explicitly enabled, which bounded per-tool event should be correlated?
+1. Did deployment and authenticated relay readiness succeed?
+2. Is a service persistently degraded, and is recovery automatic?
+3. Did the service recover, and how long was it unavailable?
+4. Is an infrastructure, protocol, deployment, or local service problem requiring action?
+5. When debug logging is explicitly enabled, which bounded implementation event should be correlated?
 
 Logs are not a command history, content audit trail, or substitute for MCP client approvals.
 
@@ -21,57 +24,89 @@ The CLI accepts:
 --verbose    # alias for debug
 ```
 
-The default foreground level is `info`. Platform autostart services use `warn`.
+Foreground mode defaults to `info`. Platform autostart services use `warn`.
 
 | Level | Intended events |
 |---|---|
-| `error` | Broken request handlers, relay transport errors, unrecoverable local failures |
-| `warn` | Relay disconnections/send failures, malformed or oversized messages, superseded daemons, service/autostart problems |
-| `info` | Deployment/startup transitions and successful relay connection |
-| `debug` | Every per-tool start/success/failure/cancellation/timing event, shortened correlation IDs, reconnect timing |
+| `error` | The operation or service cannot continue without intervention |
+| `warn` | Persistent relay outage, malformed/oversized protocol data, supersession, or service/autostart degradation |
+| `info` | Deployment/startup transitions, authenticated relay readiness, and recovery after a visible outage |
+| `debug` | Transport open/close codes and reasons, brief self-healing interruptions, retry timing, per-tool outcomes, and shortened correlation IDs |
+
+## Relay connection event policy
+
+A TCP/WebSocket `open` event is only transport availability. The daemon is reported as connected only after the Worker returns `hello_ack` for the authenticated `hello` message.
+
+Brief network interruptions are expected on laptop network changes, Worker deployment, proxy rotation, and ordinary internet transport. They are handled as follows:
 
-All per-tool outcomes are deliberately absent from `info`, `warn`, and `error`. The MCP response already reports success or failure to the caller; duplicating ordinary failures in daemon logs creates noise without adding operational information. A normal sequence of hundreds of successful or failed tool invocations should not fill the user's terminal or service logs.
+- the raw close code, close reason, error class, connected duration, and retry delay are debug-only;
+- a brief interruption that reconnects within the grace period produces no `info` or `warn` line;
+- an outage that remains unresolved for 10 seconds produces one rate-limited warning stating that automatic reconnection is in progress;
+- relay identity/version mismatch and authentication rejection are non-transient: they produce an immediate actionable error and terminate that daemon instead of entering the reconnect loop;
+- repeated warnings are rate-limited;
+- recovery after a visible outage produces one information summary with outage duration and attempt count;
+- an authenticated replacement is a distinct warning and permanently stops the older daemon;
+- failure to receive `hello_ack` within the handshake deadline terminates the candidate socket and retries;
+- lack of inbound heartbeat activity terminates a half-open socket and reconnects.
 
-## Event fields
+A WebSocket close code such as `1006` means the transport ended without a normal close handshake. It is useful for debug diagnosis but not useful as the default user message. Default logs therefore describe the effect and recovery behavior rather than printing `{"code":1006,"reason":""}`.
 
-Default operational events may include component, relay close code, bounded reconnect delay, provider name, or a coarse infrastructure error class. Per-tool fields—tool name, duration, outcome class, and shortened call identifier—are debug-only. Call identifiers are useful only for correlating adjacent local events and are not stable audit identifiers.
+Examples:
+
+```text
+[info] daemon: remote relay connected
+[warn] daemon: remote relay is unavailable; automatic reconnection is still in progress {"outage_seconds":12,"attempts":3,"cause":"connection interrupted"}
+[info] daemon: remote relay connection restored {"outage_seconds":18,"attempts":4}
+```
 
-The implementation intentionally omits:
+With `--verbose`, the same incident may additionally include bounded transport diagnostics.
 
-- tool arguments;
-- command text or argv;
+## Tool events
+
+All per-tool starts, successes, failures, cancellations, and timing are debug-only. The MCP response already reports the outcome to the caller; duplicating routine tool traffic at default levels creates noise and can reveal activity patterns.
+
+Debug per-tool fields may include tool name, duration, coarse outcome class, and a shortened random call identifier. The identifier is for correlating adjacent local events and is not a stable audit identifier.
+
+## Data that is never logged
+
+The implementation omits:
+
+- tool arguments and command text or argv;
 - stdin, stdout, and stderr;
-- file, patch, or image content;
+- file, patch, image, and temporary-file content;
 - OAuth request bodies;
-- connection passwords, daemon secrets, authorization codes, and access tokens.
+- connection passwords, daemon secrets, authorization codes, and access tokens;
+- registered resource values and source paths.
 
-Unexpected daemon, service, and Worker infrastructure failures are reduced to coarse error classes in normal logs. Client-facing tool errors may contain more detail according to the active path-display policy, but ordinary tool failures and those details are not copied into normal operational logs.
+Unexpected infrastructure failures are reduced to coarse error classes in normal logs. Client-facing tool errors may contain more detail according to the active path-display policy, but those details are not copied into operational logs.
 
 ## Bounding and redaction
 
-Messages, strings, object depth, object key counts, array item counts, and serialized field payloads are bounded. Control characters are neutralized. Fields with secret-like names and known token formats are recursively redacted.
+Messages, strings, object depth, object key counts, array item counts, and serialized field payloads are bounded. Control characters and Unicode display controls are neutralized. Fields with secret-like names, path-like keys, and known token formats are recursively redacted.
 
-This is defense in depth, not content classification. A previously unknown secret format embedded in an ordinary non-secret-named field may evade pattern redaction. For that reason, tool arguments and outputs are omitted rather than merely filtered.
+This is defense in depth, not content classification. Unknown secret formats can evade pattern matching, which is why tool arguments and outputs are omitted rather than merely filtered.
 
 ## Files
 
-Autostart logs are stored below the state root:
+Autostart logs are stored below the owner-only state root:
 
 ```text
 logs/daemon.out.log
 logs/daemon.err.log
 ```
 
-They are owner-only where the platform supports Unix-style permissions. Existing files are tail-trimmed on UTF-8/line boundaries before daemon startup. Because background services use `warn` and per-tool events are debug-only, neither successful nor failed ordinary tool traffic should cause sustained log growth.
+Existing files are opened without following symbolic links where supported and tail-trimmed on UTF-8/line boundaries before startup. Background services use `warn`, so ordinary tool traffic and brief relay interruptions do not cause sustained growth.
 
-Each managed job also has owner-only `runner.out.log` and `runner.err.log` files for runner startup/crash diagnostics. Child-step stdout and stderr are captured into bounded job results according to `capture_output`; they are not copied into runner or daemon operational logs. Runner logs are retained with the bounded job directory and removed by job retention cleanup.
+Each managed job has owner-only runner diagnostic logs. Child-step output is retained only in bounded, redacted job results according to `capture_output`; it is not copied into daemon or runner operational logs.
 
 ## MCP host boundary
 
-Machine Bridge does not classify filenames as sensitive and does not block `.env`, password, key, or credential-looking names. The active local policy, local OS permissions, and endpoint-security controls determine what the server itself can read or execute.
+Machine Bridge does not classify filenames as sensitive and does not block credential-looking names under canonical `full`. An MCP host, connector, model provider, desktop application, operating system, or endpoint-security layer may independently reject a request before it reaches Machine Bridge.
+
+Use `server_info`, `machine-mcp status`, `machine-mcp doctor`, and `diagnose_runtime` to distinguish local policy from host-side enforcement. Changing the Machine Bridge profile cannot override another layer.
 
-An MCP host, model provider, desktop application, or platform execution layer may independently deny a request involving credentials or sensitive files. Such a denial occurs before or outside Machine Bridge's file resolver and cannot be disabled by selecting the local `full` profile. Use `server_info`, `machine-mcp status`, and `machine-mcp doctor` to distinguish the active local policy from host-side enforcement.
+## Adding or changing logs
 
-## Privacy filtering
+A default-level message must be actionable, privacy-preserving, and resistant to repetition. Add a regression test for severity and field visibility. Raw protocol values belong at debug unless a user can act on them without external documentation.
 
-Structured fields whose names indicate a local path, workspace, working directory, home, or state root are replaced with `<local-path>`. Free-form log text removes known home-directory prefixes, email addresses, common bearer/cloud/API token forms, private-key headers, control characters, and Unicode bidirectional/zero-width formatting controls. Explicit command output and JSON command results are not operational logs and retain their documented opt-in disclosure semantics.
+See [ENGINEERING.md](ENGINEERING.md) for the project-wide review rules.

package/docs/OPERATIONS.md

@@ -24,6 +24,12 @@ machine-mcp service status
 
 A successful diagnostic result applies only to that probe. An MCP host can still deny a later call based on its own request context. This is expected layering, not a defect in the `full` profile: `full` removes Machine Bridge's own denials, while host delivery remains independent.
 
+### Relay interruption messages
+
+A brief relay interruption is retried automatically and is visible only with `--verbose`. Default logs do not print raw WebSocket values such as `code=1006` with an empty reason. If a transient outage persists for 10 seconds, one warning is emitted and repeated warnings are rate-limited; a later recovery produces one summary with outage duration and attempt count. Identity/version mismatch and authentication rejection are not retried as ordinary network faults: the daemon emits an immediate actionable error and exits, requiring upgrade/redeployment or credential repair.
+
+Use `--verbose` only when close codes, close reasons, heartbeat timeouts, and retry delays are needed for diagnosis. A close code of 1006 means the transport ended without a normal close handshake; it does not by itself identify the cause.
+
 ## Logs
 
 Remote autostart definitions prefer a stable PATH alias that resolves to the currently running Node executable and persist a sanitized absolute-only service `PATH` containing the Node/CLI directories, the installer's absolute PATH entries, and platform defaults. This avoids versioned Homebrew-style paths becoming invalid after upgrades and prevents launchd/systemd from falling back to a minimal system-only PATH. Re-run `machine-mcp service install` after changing Node installation families or PATH layout. Autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Files are owner-only where supported and tail-trimmed before daemon startup.

package/docs/PRIVACY.md

@@ -21,6 +21,12 @@ chmod 600 .privacy-denylist
 
 Add one identifier per line. The denylist is deliberately local and must never be committed. CI still runs the built-in generic checks; a developer's local check adds their private vocabulary.
 
+## Local maintenance notes
+
+Machine-specific operational notes may be kept under the ignored `.project-local/` directory. Use it for temporary environment state and one-machine recovery observations, not for reusable engineering decisions. General lessons belong in tracked documentation such as `ENGINEERING.md`.
+
+Ignored does not mean safe for secrets: do not store passwords, tokens, private keys, authorization URLs, or copied secret-bearing logs there. `.privacy-denylist` remains the dedicated local vocabulary gate.
+
 ## Review rules
 
 Before committing or publishing:

package/docs/TESTING.md

@@ -37,6 +37,8 @@ The suite includes:
 - guarded state-root removal, schema migration, policy-origin persistence, and legacy implicit-default migration;
 - no filename-based sensitive-file denial under unrestricted policy;
 - log redaction, control-character handling, message/field bounds, suppression of both successful and failed per-tool events outside debug, and service warning-level configuration;
+- deterministic relay connection lifecycle coverage for transport construction/error, authenticated `hello_ack` readiness, identity/version mismatch, handshake and heartbeat timeout, brief-outage suppression, sustained-outage escalation, recovery summaries, and supersession;
+- shared no-follow bounded-file reads for normal files, over-limit data, directories, and symbolic links;
 - CLI parsing, policy profiles, and client configuration boundaries;
 - live stdio MCP initialization, discovery, calls, rich content, sessions, cancellation, managed-job acceptance, and a detached job/finally phase that survives stdio shutdown;
 - live local Worker OAuth registration, consent, PKCE, token replay rejection, throttling, CORS, protocol negotiation, dynamic tool advertisement, rich content, daemon replacement, and cancellation.
@@ -54,7 +56,7 @@ npm run version:check
 npm run release-impact:check
 ```
 
-GitHub Actions executes the main suite on Linux, macOS, and Windows using the pinned Node 26/npm 12 baseline. Because Node 26 currently bundles npm 11, CI explicitly disables setup-node's automatic package-manager cache and upgrades npm from the runner temporary directory before any project-local npm command can trigger strict `devEngines`. Checkout fetches version tags so the release-impact gate can compare the branch with the latest release. A separate package-audit job audits both the complete dependency graph and the production-only graph, verifies registry signatures and attestations, validates a CycloneDX SBOM written under the runner temporary directory, then performs a dry-run package build. Dependency and GitHub Actions updates are monitored by Dependabot.
+GitHub Actions executes the main suite on Linux, macOS, and Windows using the pinned Node 26/npm 12 baseline. Because Node 26 currently bundles npm 11, CI explicitly disables setup-node's automatic package-manager cache and upgrades npm from the runner temporary directory before any project-local npm command can trigger strict `devEngines`. Checkout fetches version tags so the release-impact gate can compare the branch with the latest release. A separate package-audit job audits both the complete dependency graph and the production-only graph, verifies registry signatures and attestations, validates a CycloneDX SBOM written under the runner temporary directory, exercises the documented isolated global installation, then performs a dry-run package build. The macOS matrix job also runs the installation smoke test because Wrangler's optional `fsevents` resolution is platform-specific. Dependency and GitHub Actions updates are monitored by Dependabot.
 
 ## Test design rules
 
@@ -74,6 +76,10 @@ Run `npm run privacy:check` before committing and before packaging. Developers s
 
 ## Package manifest
 
-`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts and credential-like file classes, and verifies that privacy guidance, contribution/release discipline, and both privacy/release-impact checkers are present in the published package.
+`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts and credential-like file classes, and verifies that privacy/engineering guidance, the runtime/relay/secure-file modules, contribution discipline, and privacy/release-impact checkers are present in the published package. `npm run install:test` packs the real tarball, installs it into an isolated global prefix with the documented npm 12 options, rejects blocked-script warnings, confirms optional `fsevents` is absent, and runs the installed CLI.
 
 The stdio integration test also sends an oversized line, verifies bounded rejection, and confirms that the next valid request is still processed.
+
+## Architecture and documentation regression checks
+
+`npm run architecture:test` rejects local-module dependency cycles, missing relative imports, obsolete `LocalDaemon`/`daemon.mjs` naming, broken relative Markdown links, invisible ASCII control bytes in repository text, removal of the owner-required default-`full` engineering invariant, and accidental publication of `.project-local/` notes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Cross-client MCP bridge for canonical local automation, files, Git, SSH resources, managed jobs, and processes over stdio or an OAuth-protected remote relay.",
   "type": "module",
   "license": "MIT",
@@ -43,8 +43,8 @@
     "prepublishOnly": "npm run check && npm run version:check && npm run release:check",
     "worker:types": "wrangler types src/worker/worker-configuration.d.ts",
     "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit",
-    "syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/daemon.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/local-self-test.mjs && node --check tests/daemon-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs",
-    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run network-retry:test && npm run typecheck && npm run syntax && npm run catalog:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
+    "syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/runtime.mjs && node --check src/local/relay-connection.mjs && node --check src/local/secure-file.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/local-self-test.mjs && node --check tests/runtime-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs && node --check tests/relay-connection-test.mjs && node --check tests/install-smoke-test.mjs && node --check tests/secure-file-test.mjs && node --check tests/architecture-test.mjs",
+    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run catalog:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
@@ -61,7 +61,11 @@
     "release-impact:check": "node scripts/release-impact-check.mjs",
     "release-impact:test": "node tests/release-impact-test.mjs",
     "privacy:test": "node tests/privacy-test.mjs",
-    "network-retry:test": "node tests/network-retry-test.mjs"
+    "network-retry:test": "node tests/network-retry-test.mjs",
+    "relay:test": "node tests/relay-connection-test.mjs",
+    "install:test": "node tests/install-smoke-test.mjs",
+    "secure-file:test": "node tests/secure-file-test.mjs",
+    "architecture:test": "node tests/architecture-test.mjs"
   },
   "dependencies": {
     "wrangler": "4.110.0",