machine-bridge-mcp 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.8.2 - 2026-07-11
+
+### Relay reliability and protocol correctness
+
+- Add a deadline for WebSocket connection establishment so a transport stuck in `CONNECTING` cannot freeze automatic reconnection indefinitely. Sustained-outage reminders now run on an independent exponential-backoff timer capped at 15 minutes instead of appearing only when another reconnect event happens.
+- Handle Worker `{type:"error"}` messages explicitly. A daemon hello timeout is classified as transient and retried; unknown protocol errors, duplicate hello messages, identity/version mismatch, and authentication rejection terminate with actionable guidance instead of becoming an `unknown websocket message` warning.
+- Validate daemon WebSocket JSON as a non-array object before field access. Invalid JSON closes with code 1007, non-object/unknown/duplicate protocol messages close with code 1002, and active daemon replacement semantics remain unchanged.
+
+### Logging, tests, and documentation
+
+- Replace default outage/recovery JSON field dumps with readable duration, attempt, cause, automatic-recovery, and long-outage action text. Exact seconds, error classes, retry delays, and raw transport details remain debug-only. Advance the autostart log schema so historical 0.8.1-format lines are separated into the bounded owner-only legacy snapshot. Treat a service-style daemon-only start that finds the workspace daemon already running as a silent idempotent success, preventing repeated lock warnings and duplicate readiness output from accumulating in service logs.
+- Add deterministic tests for stalled connection attempts, autonomous reminder backoff, retryable versus fatal relay error messages, close-reason classification, and runtime control-message routing. Extend live Worker integration coverage to invalid JSON, non-object messages, duplicate hello, and unknown authenticated messages. Enable TypeScript unused-local and unused-parameter checks to prevent dead Worker code from accumulating.
+- Update architecture, operations, logging, testing, and README guidance to match the implemented state machine and operator-facing behavior. Add a repository automation contract separating code/test/commit/push work from npm publication, global CLI installation, Worker deployment, credential rotation, and daemon/service operations; the owner performs those live release steps explicitly. Improve release-check diagnostics so a missing local or remote version tag is reported distinctly from a tag pointing at the wrong commit, with the required `release:publish` step named directly.
+
 ## 0.8.1 - 2026-07-11
 
 ### Fixed

package/CONTRIBUTING.md

@@ -4,15 +4,23 @@ This repository treats every Git-tracked or nonignored repository file as releas
 
 ## Required for every release-relevant change
 
-Before a change is merged to `main`:
+Before the reviewed code is pushed to `main`:
 
 1. bump `package.json` to a version newer than the latest reachable `v*` tag;
 2. add the matching dated section to `CHANGELOG.md`;
 3. run `npm run check`, `npm audit`, `npm audit --omit=dev`, and `npm run worker:dry-run`;
 4. inspect the complete diff and the npm package manifest;
-5. push the reviewed commit to GitHub;
-6. create the matching Git tag and GitHub Release;
-7. publish the same version to npm.
+5. commit and push the reviewed change to GitHub.
+
+The release operator then creates the matching Git tag and GitHub Release and publishes the same version to npm. These release actions are not implicit coding-agent tasks. Unless the user explicitly requests them in the current task, automation must not publish or alter npm versions, create tags or releases, install the CLI globally, deploy the Worker, rotate credentials, mutate live deployment state, or start/stop/install/remove the daemon or autostart service. See [AGENTS.md](AGENTS.md) for the repository automation contract.
+
+After npm publication, the standard machine update is:
+
+```bash
+npm install -g --allow-scripts=esbuild,workerd,sharp machine-bridge-mcp@latest && machine-mcp
+```
+
+The npm command updates the global CLI. Normal `machine-mcp` startup checks the Worker deployment hash, expected version, and health, redeploys when necessary, and reconciles the daemon/autostart flow.
 
 `npm run release-impact:check` enforces the version and changelog parts. It fails when release-relevant files changed after the latest version tag but the package version was not advanced.
 

package/README.md

@@ -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 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).
+Default foreground logs report authenticated relay readiness, readable persistent-degradation summaries, and recovery rather than raw WebSocket callbacks or JSON field dumps. Brief self-healing disconnects and close codes/reasons are debug-only. Stalled connection attempts have a deadline, and sustained-outage reminders use autonomous exponential backoff. 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
 

package/docs/ARCHITECTURE.md

@@ -177,11 +177,11 @@ Managed jobs use the same argv/environment primitives but a different lifecycle.
 
 ## Daemon reconnect and replacement
 
-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.
+The local `RelayConnection` treats transport construction, transport open, authenticated readiness, and outage recovery as separate states. A connection-attempt deadline terminates sockets stuck in `CONNECTING`; after WebSocket open it sends `hello` and reports readiness only after `hello_ack`. A missing acknowledgement reaches a distinct handshake deadline and the candidate is terminated. Once ready, application heartbeats require inbound activity; a silent half-open socket is terminated and reconnected. Outage reminders run on their own exponential-backoff timer rather than depending on another transport callback.
 
 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.
+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. Daemon messages must be valid JSON objects, duplicate `hello` and unknown message types are rejected with explicit protocol errors, and protocol violations close with standard WebSocket status codes. 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
 

package/docs/ENGINEERING.md

@@ -13,6 +13,12 @@ This document records project-wide decisions that must survive individual fixes,
 
 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 changes and live release operations are separate responsibilities. Unless the current task explicitly authorizes a broader scope, coding automation may edit source, tests, documentation, package metadata, and changelog entries; run repository-local checks; commit; and push to GitHub. It must not publish or alter npm releases, create tags or GitHub Releases, install the package globally, deploy or reconfigure a Cloudflare Worker, rotate credentials, mutate live deployment state, or start/stop/install/remove the daemon or autostart service.
+
+The normal handoff is: the repository owner publishes the reviewed npm version, then runs `npm install -g --allow-scripts=esbuild,workerd,sharp machine-bridge-mcp@latest && machine-mcp`. The npm command updates the global CLI. The subsequent normal startup validates the Worker deployment hash, expected version, and health, redeploys when necessary, and reconciles the daemon/autostart flow. Live operations require explicit authorization even when they appear to be the obvious next release step.
+
 ## Architectural boundaries
 
 The preferred dependency direction is:

package/docs/LOGGING.md

@@ -41,10 +41,12 @@ Brief network interruptions are expected on laptop network changes, Worker deplo
 
 - 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 outage that remains unresolved for 10 seconds produces a user-readable warning stating the duration, reconnect attempt count, classified cause, and automatic recovery behavior;
+- while the outage remains unresolved, reminders are scheduled independently of reconnect callbacks and use exponential backoff capped at 15 minutes;
+- a WebSocket that remains in `CONNECTING` beyond its deadline is terminated so one stalled network attempt cannot freeze the reconnect loop;
+- relay identity/version mismatch, authentication rejection, and unexpected protocol messages are non-transient: they produce an immediate actionable error and terminate that daemon instead of entering the reconnect loop;
+- a Worker `daemon_hello_timeout` error is transient and follows the normal reconnect path rather than being misclassified as authentication rejection;
+- recovery after a visible outage produces one information summary with a human-readable duration and attempt count; exact seconds and error classes remain debug-only;
 - 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.
@@ -55,11 +57,11 @@ 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}
+[warn] daemon: remote relay unavailable for 12 seconds; reconnecting automatically (3 reconnect attempts; connection interrupted).
+[info] daemon: remote relay connection restored after 18 seconds (4 reconnect attempts)
 ```
 
-With `--verbose`, the same incident may additionally include bounded transport diagnostics.
+With `--verbose`, the same incident additionally includes bounded structured fields such as exact seconds, coarse error class, retry delay, and transport close diagnostics.
 
 ## Tool events
 

package/docs/OPERATIONS.md

@@ -26,19 +26,19 @@ A successful diagnostic result applies only to that probe. An MCP host can still
 
 ### 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.
+A brief relay interruption is retried automatically and is visible only with `--verbose`. Default logs do not print raw WebSocket values such as `code=1006` with an empty reason. If a transient outage persists for 10 seconds, the daemon emits a readable duration/cause/reconnect summary; later reminders use autonomous exponential backoff capped at 15 minutes, and recovery produces one readable summary. Each transport connection attempt also has a deadline, so a socket stuck in `CONNECTING` cannot freeze retries. Identity/version mismatch, authentication rejection, and unexpected protocol messages are not retried as ordinary network faults: the daemon emits an immediate actionable error and exits, requiring upgrade/redeployment or credential repair. A Worker-side daemon handshake timeout remains retryable.
 
 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. On a logging-schema upgrade, bounded prior content is moved into `daemon.out.legacy.log` and `daemon.err.legacy.log`; use the active filenames when diagnosing current behavior.
+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. A service-style `--daemon-only` start that finds the same workspace daemon already running is an idempotent no-op: it exits successfully without repeating warnings or readiness output; explicit policy/secret/change requests still report that changes were not applied. Autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Files are owner-only where supported and tail-trimmed before daemon startup. On a logging-schema upgrade, bounded prior content is moved into `daemon.out.legacy.log` and `daemon.err.legacy.log`; use the active filenames when diagnosing current behavior.
 
 Logging is level-based:
 
 ```text
 error  unrecoverable local/transport/service failures
-warn   relay disconnect/send failures, malformed relay events, supersession and service problems
+warn   persistent retryable relay degradation, supersession, and service problems
 info   startup/deploy/connect transitions
 debug  all per-tool starts/successes/failures/cancellations/timing, correlation and reconnect details
 ```

package/docs/TESTING.md

@@ -13,7 +13,8 @@ The repository requires Node.js 26 and npm 12. `.node-version`, `.nvmrc`, `packa
 The suite includes:
 
 - release-impact enforcement requiring a new package version and CHANGELOG section for release-relevant changes;
-- generated Cloudflare Worker types and strict TypeScript checking;
+- release-state diagnostics distinguishing missing local/remote version tags from tags that point to the wrong commit, including the required publication order;
+- generated Cloudflare Worker types and strict TypeScript checking, including unused-local and unused-parameter rejection;
 - syntax validation for every shipped JavaScript entry point;
 - shared tool-catalog schema, annotation, and profile-inventory checks;
 - canonical path and symbolic-link escape tests;
@@ -37,11 +38,11 @@ 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, service warning-level configuration, and idempotent bounded migration of legacy log formats;
-- deterministic relay connection lifecycle coverage for transport construction/error, pre-handshake `welcome` validation, authenticated `hello_ack` readiness, identity/version mismatch, handshake and heartbeat timeout, brief-outage suppression, sustained-outage escalation, recovery summaries, and supersession;
+- deterministic relay connection lifecycle coverage for transport construction/error/deadline, pre-handshake `welcome` validation, authenticated `hello_ack` readiness, identity/version mismatch, retryable Worker handshake errors, fatal protocol errors, autonomous outage-reminder backoff, 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.
+- live local Worker OAuth registration, consent, PKCE, token replay rejection, throttling, CORS, protocol negotiation, dynamic tool advertisement, rich content, daemon replacement, cancellation, malformed daemon JSON/non-object rejection, duplicate hello rejection, and unknown-message closure.
 
 ## Additional release checks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "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/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",
+    "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/release-state.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/release-state-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 release-state: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",
@@ -65,7 +65,8 @@
     "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"
+    "architecture:test": "node tests/architecture-test.mjs",
+    "release-state:test": "node tests/release-state-test.mjs"
   },
   "dependencies": {
     "wrangler": "4.110.0",

package/src/local/cli.mjs

@@ -337,6 +337,10 @@ async function prepareStartMode(args, state, logger) {
 
 function reportExistingDaemon(args, state, owner, logger) {
   const pid = owner?.pid ? `pid ${owner.pid}` : "unknown pid";
+  if (isIdempotentDaemonOnlyStart(args)) {
+    logger.debug?.("local daemon already running; daemon-only start completed as an idempotent no-op", { owner_pid_known: Boolean(owner?.pid) });
+    return;
+  }
   logger.warn(`local daemon already running for this workspace (${pid}); requested changes were not applied`);
   if (args.json) {
     printStartJson(state, {
@@ -354,6 +358,24 @@ function reportExistingDaemon(args, state, owner, logger) {
   });
 }
 
+function isIdempotentDaemonOnlyStart(args) {
+  if (!args.daemonOnly || args.json) return false;
+  return !Boolean(
+    args.profile
+    || args.execMode
+    || args.rotateSecrets
+    || args.forceWorker
+    || args.workerName
+    || args.noWrite
+    || args.noExec
+    || args.fullEnv
+    || args.unrestrictedPaths
+    || args.absolutePaths
+    || args.printMcpCredentials
+    || args.printCredentials
+  );
+}
+
 async function startRemoteRuntime({ args, workspace, state, daemonLock, logger }) {
   let runtime = null;
   try {

package/src/local/relay-connection.mjs

@@ -3,10 +3,13 @@ import { classifyOperationalError } from "./log.mjs";
 
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
 const DEFAULT_HEARTBEAT_TIMEOUT_MS = 75_000;
+const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
 const DEFAULT_OUTAGE_WARN_AFTER_MS = 10_000;
 const DEFAULT_OUTAGE_WARN_REPEAT_MS = 60_000;
+const DEFAULT_OUTAGE_WARN_MAX_REPEAT_MS = 15 * 60_000;
 const MAX_CLOSE_REASON_CHARS = 128;
+const MAX_PROTOCOL_ERROR_CODE_CHARS = 64;
 
 const DEFAULT_SCHEDULER = Object.freeze({
   setTimeout: (callback, delay) => setTimeout(callback, delay),
@@ -35,9 +38,14 @@ export class RelayConnection {
     this.maxPayload = boundedPositiveInteger(options.maxPayload, 8 * 1024 * 1024);
     this.heartbeatIntervalMs = boundedPositiveInteger(options.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS);
     this.heartbeatTimeoutMs = boundedPositiveInteger(options.heartbeatTimeoutMs, DEFAULT_HEARTBEAT_TIMEOUT_MS);
+    this.connectTimeoutMs = boundedPositiveInteger(options.connectTimeoutMs, DEFAULT_CONNECT_TIMEOUT_MS);
     this.handshakeTimeoutMs = boundedPositiveInteger(options.handshakeTimeoutMs, DEFAULT_HANDSHAKE_TIMEOUT_MS);
     this.outageWarnAfterMs = boundedPositiveInteger(options.outageWarnAfterMs, DEFAULT_OUTAGE_WARN_AFTER_MS);
     this.outageWarnRepeatMs = boundedPositiveInteger(options.outageWarnRepeatMs, DEFAULT_OUTAGE_WARN_REPEAT_MS);
+    this.outageWarnMaxRepeatMs = Math.max(
+      this.outageWarnRepeatMs,
+      boundedPositiveInteger(options.outageWarnMaxRepeatMs, DEFAULT_OUTAGE_WARN_MAX_REPEAT_MS),
+    );
 
     this.closed = true;
     this.socket = null;
@@ -47,12 +55,14 @@ export class RelayConnection {
     this.lastInboundAt = 0;
     this.reconnectAttempt = 0;
     this.reconnectTimer = null;
+    this.connectTimer = null;
     this.heartbeatTimer = null;
     this.handshakeTimer = null;
     this.outageWarnTimer = null;
     this.outageStartedAt = 0;
     this.outageAttempts = 0;
     this.outageNoticeEmitted = false;
+    this.outageWarningCount = 0;
     this.lastOutageWarnAt = 0;
     this.lastCloseCategory = "connection_interrupted";
     this.lastTransportErrorClass = "";
@@ -77,6 +87,7 @@ export class RelayConnection {
     this.closed = true;
     this.ready = false;
     this.clearTimer("heartbeatTimer", "clearInterval");
+    this.clearTimer("connectTimer", "clearTimeout");
     this.clearTimer("handshakeTimer", "clearTimeout");
     this.clearTimer("reconnectTimer", "clearTimeout");
     this.clearTimer("outageWarnTimer", "clearTimeout");
@@ -128,7 +139,8 @@ export class RelayConnection {
     } else if (this.outageStartedAt > 0) {
       const outageMs = Math.max(0, this.connectedAt - this.outageStartedAt);
       if (this.outageNoticeEmitted) {
-        this.logger.info?.("remote relay connection restored", {
+        this.logger.info?.(`remote relay connection restored after ${formatDuration(outageMs)} (${formatAttempts(this.outageAttempts)})`);
+        this.logger.debug?.("remote relay outage recovery details", {
           outage_seconds: roundSeconds(outageMs),
           attempts: this.outageAttempts,
         });
@@ -150,6 +162,20 @@ export class RelayConnection {
     return true;
   }
 
+  handleServerError(message = {}) {
+    const errorCode = sanitizeProtocolErrorCode(message?.error);
+    this.logger.debug?.("remote relay reported a protocol error", { error_code: errorCode });
+    if (errorCode === "daemon_hello_timeout" && !this.ready) {
+      const socket = this.socket;
+      if (this.closed || !socket) return true;
+      this.pendingCloseCategory = "relay_handshake_timeout";
+      terminateSocket(socket);
+      return true;
+    }
+    this.failPermanently("relay_protocol_error");
+    return true;
+  }
+
   connect() {
     if (this.closed || this.socket) return;
     const wsUrl = `${this.workerUrl.replace(/^http/i, "ws")}/daemon/ws`;
@@ -167,8 +193,17 @@ export class RelayConnection {
       return;
     }
     this.socket = socket;
+    this.clearTimer("connectTimer", "clearTimeout");
+    this.connectTimer = this.scheduler.setTimeout(() => {
+      if (this.socket !== socket || this.closed || this.isSocketOpen(socket)) return;
+      this.logger.debug?.("remote relay transport connection timed out", { timeout_ms: this.connectTimeoutMs });
+      this.pendingCloseCategory = "relay_connect_timeout";
+      terminateSocket(socket);
+    }, this.connectTimeoutMs);
+    this.connectTimer?.unref?.();
 
     socket.on("open", () => {
+      this.clearTimer("connectTimer", "clearTimeout");
       if (this.socket !== socket || this.closed) {
         try { socket.close(1000, "stale daemon connection"); } catch {}
         return;
@@ -204,6 +239,7 @@ export class RelayConnection {
       const wasReady = this.ready;
       this.socket = null;
       this.ready = false;
+      this.clearTimer("connectTimer", "clearTimeout");
       this.clearTimer("heartbeatTimer", "clearInterval");
       this.clearTimer("handshakeTimer", "clearTimeout");
       const reasonText = sanitizeCloseReason(reason);
@@ -265,6 +301,7 @@ export class RelayConnection {
     this.closed = true;
     this.ready = false;
     this.socket = null;
+    this.clearTimer("connectTimer", "clearTimeout");
     this.clearTimer("heartbeatTimer", "clearInterval");
     this.clearTimer("handshakeTimer", "clearTimeout");
     this.clearTimer("reconnectTimer", "clearTimeout");
@@ -286,7 +323,8 @@ export class RelayConnection {
       reject(error);
       return;
     }
-    this.logger.error?.(message, { cause: relayCloseUserCause(category) });
+    this.logger.error?.(message);
+    this.logger.debug?.("remote relay fatal details", { category, cause: relayCloseUserCause(category) });
     queueMicrotask(() => {
       try { this.onFatal(error); } catch (callbackError) {
         this.logger.error?.("relay fatal callback failed", { error_class: classifyOperationalError(callbackError) });
@@ -299,7 +337,6 @@ export class RelayConnection {
     this.recordOutage(category);
     const delay = this.reconnectDelay(this.reconnectAttempt++);
     this.scheduleOutageWarning();
-    this.maybeRepeatOutageWarning();
     this.logger.debug?.("scheduling daemon reconnect", { delay_ms: delay, attempt: this.outageAttempts });
     this.reconnectTimer = this.scheduler.setTimeout(() => {
       this.reconnectTimer = null;
@@ -352,31 +389,39 @@ export class RelayConnection {
   }
 
   scheduleOutageWarning() {
-    if (this.outageNoticeEmitted || this.outageWarnTimer || this.outageStartedAt === 0) return;
-    const elapsed = Math.max(0, this.now() - this.outageStartedAt);
-    const delay = Math.max(0, this.outageWarnAfterMs - elapsed);
+    if (this.outageWarnTimer || this.outageStartedAt === 0 || this.closed || this.ready) return;
+    const dueAt = this.outageNoticeEmitted
+      ? this.lastOutageWarnAt + this.nextOutageWarningDelay()
+      : this.outageStartedAt + this.outageWarnAfterMs;
+    const delay = Math.max(0, dueAt - this.now());
     this.outageWarnTimer = this.scheduler.setTimeout(() => {
       this.outageWarnTimer = null;
       if (this.closed || this.ready || this.outageStartedAt === 0) return;
       this.emitOutageWarning();
+      this.scheduleOutageWarning();
     }, delay);
     this.outageWarnTimer?.unref?.();
   }
 
-  maybeRepeatOutageWarning() {
-    if (!this.outageNoticeEmitted || this.lastOutageWarnAt === 0) return;
-    if (this.now() - this.lastOutageWarnAt < this.outageWarnRepeatMs) return;
-    this.emitOutageWarning();
+  nextOutageWarningDelay() {
+    const exponent = Math.max(0, Math.min(this.outageWarningCount - 1, 20));
+    return Math.min(this.outageWarnRepeatMs * (2 ** exponent), this.outageWarnMaxRepeatMs);
   }
 
   emitOutageWarning() {
     const outageMs = Math.max(0, this.now() - this.outageStartedAt);
     this.outageNoticeEmitted = true;
+    this.outageWarningCount += 1;
     this.lastOutageWarnAt = this.now();
-    this.logger.warn?.(relayOutageWarningMessage(), {
+    const cause = relayCloseUserCause(this.lastCloseCategory);
+    const action = outageMs >= 5 * 60_000
+      ? " If this persists, check internet access and the deployed Worker."
+      : "";
+    this.logger.warn?.(`remote relay unavailable for ${formatDuration(outageMs)}; reconnecting automatically (${formatAttempts(this.outageAttempts)}; ${cause}).${action}`);
+    this.logger.debug?.("remote relay outage details", {
       outage_seconds: roundSeconds(outageMs),
       attempts: this.outageAttempts,
-      cause: relayCloseUserCause(this.lastCloseCategory),
+      cause,
       ...(this.lastTransportErrorClass ? { error_class: this.lastTransportErrorClass } : {}),
     });
   }
@@ -386,6 +431,7 @@ export class RelayConnection {
     this.outageStartedAt = 0;
     this.outageAttempts = 0;
     this.outageNoticeEmitted = false;
+    this.outageWarningCount = 0;
     this.lastOutageWarnAt = 0;
     this.lastCloseCategory = "connection_interrupted";
     this.lastTransportErrorClass = "";
@@ -406,10 +452,15 @@ export class RelayConnection {
 
 export function relayCloseCategory(code, reason = "") {
   const numeric = Number(code);
-  if (isSupersededClose(numeric, reason)) return "superseded";
+  const reasonText = String(reason || "");
+  if (isSupersededClose(numeric, reasonText)) return "superseded";
+  if (numeric === 1008 && reasonText === "daemon hello timeout") return "relay_handshake_timeout";
+  if (numeric === 1008 && ["stale daemon candidate", "expired daemon candidate"].includes(reasonText)) return "relay_restarting_or_unavailable";
+  if (numeric === 1008 && ["daemon hello required", "missing daemon attachment", "invalid daemon candidate timestamp"].includes(reasonText)) return "relay_protocol_error";
   if (numeric === 1000) return "normal_close";
   if (numeric === 1001 || numeric === 1012 || numeric === 1013) return "relay_restarting_or_unavailable";
   if (numeric === 1006) return "connection_interrupted";
+  if (numeric === 1002) return "relay_protocol_error";
   if (numeric === 1007) return "invalid_transport_payload";
   if (numeric === 1008) return "relay_policy_rejected";
   if (numeric === 1009) return "message_too_large";
@@ -421,13 +472,12 @@ function relayFatalMessage(category) {
   if (category === "relay_protocol_mismatch") {
     return "remote relay identity or version does not match this daemon; upgrade and redeploy both components";
   }
+  if (category === "relay_protocol_error") {
+    return "remote relay protocol error; upgrade and redeploy both components, then restart the daemon";
+  }
   return "remote relay rejected the daemon connection; verify credentials or redeploy the Worker";
 }
 
-function relayOutageWarningMessage() {
-  return "remote relay is unavailable; automatic reconnection is still in progress";
-}
-
 function relayCloseUserCause(category) {
   const causes = {
     connection_interrupted: "connection interrupted",
@@ -436,9 +486,11 @@ function relayCloseUserCause(category) {
     relay_internal_error: "relay internal error",
     relay_protocol_mismatch: "relay identity or version mismatch",
     relay_authentication_failed: "relay authentication failed",
+    relay_connect_timeout: "relay connection attempt timed out",
     relay_handshake_timeout: "relay authentication acknowledgement timed out",
     relay_heartbeat_timeout: "relay stopped responding",
     relay_transport_error: "relay transport error",
+    relay_protocol_error: "relay protocol error",
     invalid_transport_payload: "invalid transport payload",
     message_too_large: "message exceeded the relay limit",
     normal_close: "connection closed",
@@ -512,6 +564,37 @@ function boundedPositiveInteger(value, fallback) {
   return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
 }
 
+function sanitizeProtocolErrorCode(value) {
+  const code = String(value || "unknown_error").replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_PROTOCOL_ERROR_CODE_CHARS);
+  return code || "unknown_error";
+}
+
+function formatAttempts(value) {
+  const attempts = Math.max(1, Math.floor(Number(value) || 1));
+  return `${attempts} reconnect attempt${attempts === 1 ? "" : "s"}`;
+}
+
+function formatDuration(milliseconds) {
+  let seconds = Math.max(1, Math.round(Number(milliseconds) / 1000));
+  const units = [
+    ["day", 86_400],
+    ["hour", 3_600],
+    ["minute", 60],
+    ["second", 1],
+  ];
+  const parts = [];
+  for (const [label, size] of units) {
+    if (seconds < size && parts.length === 0) continue;
+    const amount = Math.floor(seconds / size);
+    if (amount > 0) {
+      parts.push(`${amount} ${label}${amount === 1 ? "" : "s"}`);
+      seconds -= amount * size;
+    }
+    if (parts.length === 2) break;
+  }
+  return parts.join(" ") || "1 second";
+}
+
 function roundSeconds(milliseconds) {
   return Math.max(1, Math.round(milliseconds / 1000));
 }

package/src/local/runtime.mjs

@@ -176,12 +176,16 @@ export class LocalRuntime {
   async handleMessage(raw) {
     let message;
     try { message = JSON.parse(raw); } catch {
-      this.logger.warn?.("invalid websocket JSON");
+      this.handleRelayProtocolViolation("invalid_server_json");
+      return;
+    }
+    if (!isPlainRecord(message)) {
+      this.handleRelayProtocolViolation("invalid_server_message");
       return;
     }
     if (this.handleRelayControlMessage(message)) return;
     if (message.type !== "tool_call") {
-      this.logger.warn?.("unknown websocket message", { type: String(message.type || "") });
+      this.handleRelayProtocolViolation("unexpected_server_message_type");
       return;
     }
     await this.handleRelayToolCall(message);
@@ -197,6 +201,10 @@ export class LocalRuntime {
       return true;
     }
     if (message.type === "pong") return true;
+    if (message.type === "error") {
+      this.relay?.handleServerError(message);
+      return true;
+    }
     if (message.type === "cancel_call") {
       if (typeof message.id === "string") this.cancelCall(message.id, "remote cancellation");
       return true;
@@ -204,6 +212,14 @@ export class LocalRuntime {
     return false;
   }
 
+  handleRelayProtocolViolation(errorCode) {
+    if (this.relay) {
+      this.relay.handleServerError({ type: "error", error: errorCode });
+      return;
+    }
+    this.logger.error?.("remote relay protocol error; upgrade and redeploy both components, then restart the daemon");
+  }
+
   async handleRelayToolCall(message) {
     const envelope = normalizeRelayToolCall(message);
     if (!envelope.ok) {
@@ -1154,7 +1170,7 @@ function createRelayConnection(runtime, { workerUrl, secret, expectedVersion, on
 function handleRelayData(runtime, data) {
   const raw = typeof data === "string" ? data : Buffer.from(data).toString("utf8");
   if (Buffer.byteLength(raw) > MAX_WS_MESSAGE_BYTES) {
-    runtime.logger.warn?.("oversized websocket message rejected");
+    runtime.handleRelayProtocolViolation("server_message_too_large");
     return;
   }
   return runtime.handleMessage(raw);

package/src/local/service.mjs

@@ -9,7 +9,7 @@ import { readBoundedRegularFileSync } from "./secure-file.mjs";
 const LABEL = "dev.machine-bridge-mcp.daemon";
 const WINDOWS_TASK = "MachineBridgeMCP";
 const SERVICE_COMMAND_OUTPUT_BYTES = 64 * 1024;
-const AUTOSTART_LOG_SCHEMA_VERSION = 2;
+const AUTOSTART_LOG_SCHEMA_VERSION = 3;
 
 function serviceRun(command, args) {
   return run(command, args, {

package/src/worker/index.ts

@@ -3,7 +3,7 @@ import toolCatalog from "../shared/tool-catalog.json";
 import serverMetadata from "../shared/server-metadata.json";
 
 const SERVER_NAME = String(serverMetadata.name);
-const SERVER_VERSION = "0.8.1";
+const SERVER_VERSION = "0.8.2";
 const MCP_PROTOCOL_VERSION = String(serverMetadata.protocolVersion);
 const MCP_SUPPORTED_PROTOCOL_VERSIONS = serverMetadata.supportedProtocolVersions.map((value) => String(value));
 const JSONRPC_VERSION = "2.0";
@@ -217,13 +217,18 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
       try { ws.close(1007, "invalid UTF-8"); } catch {}
       return;
     }
-    let body: Record<string, unknown>;
+    let parsed: unknown;
     try {
-      body = JSON.parse(text) as Record<string, unknown>;
+      parsed = JSON.parse(text);
     } catch {
-      ws.send(JSON.stringify({ type: "error", error: "invalid_json" }));
+      rejectDaemonMessage(ws, "invalid_json", 1007, "invalid JSON");
+      return;
+    }
+    if (!isObjectRecord(parsed)) {
+      rejectDaemonMessage(ws, "invalid_message", 1002, "daemon message must be an object");
       return;
     }
+    const body = parsed;
 
     const socketAttachment = this.socketAttachment(ws);
     if (!socketAttachment) {
@@ -237,6 +242,10 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
     }
 
     if (body.type === "hello") {
+      if (socketAttachment.role === "daemon") {
+        rejectDaemonMessage(ws, "duplicate_hello", 1002, "duplicate daemon hello");
+        return;
+      }
       const previousDaemons = this.daemonSockets().filter((socket) => socket !== ws);
       if (socketAttachment.role === "candidate") {
         if (!isFreshDaemonCandidate(socketAttachment.connectedAt)) {
@@ -280,7 +289,7 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
     }
 
     if (body.type !== "tool_result" || typeof body.id !== "string") {
-      ws.send(JSON.stringify({ type: "error", error: "unknown_message_type" }));
+      rejectDaemonMessage(ws, "unknown_message_type", 1002, "unknown daemon message type");
       return;
     }
 
@@ -912,6 +921,15 @@ export default {
   },
 } satisfies ExportedHandler<BridgeEnv>;
 
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function rejectDaemonMessage(ws: WebSocket, error: string, closeCode: number, closeReason: string): void {
+  try { ws.send(JSON.stringify({ type: "error", error })); } catch {}
+  try { ws.close(closeCode, closeReason); } catch {}
+}
+
 function isJsonRpcRequest(value: unknown): value is JsonRpcRequest {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const candidate = value as Record<string, unknown>;

package/tsconfig.json

@@ -9,6 +9,8 @@
     ],
     "strict": true,
     "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true