machine-bridge-mcp 0.6.2 → 0.8.0

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,53 +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":""}`.
+
+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}
+```
 
-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.
+With `--verbose`, the same incident may additionally include bounded transport diagnostics.
 
-The implementation intentionally omits:
+## Tool events
 
-- tool arguments;
-- command text or argv;
+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.
+
+## Adding or changing logs
+
+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.
 
-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.
+See [ENGINEERING.md](ENGINEERING.md) for the project-wide review rules.

package/docs/MANAGED_JOBS.md

@@ -46,10 +46,11 @@ A successful diagnostic response proves that particular request reached the loca
 Secrets and other local-only files should be registered from the user's terminal, not read into the model context:
 
 ```sh
-chmod 600 ~/.ssh/racknerd_ed25519
-machine-mcp resource add racknerd-key ~/.ssh/racknerd_ed25519
-machine-mcp resource list
-machine-mcp resource check racknerd-key
+chmod 600 ~/.ssh/example_maintenance_ed25519
+machine-mcp resource add maintenance-key ~/.ssh/example_maintenance_ed25519
+machine-mcp resource list                 # paths omitted by default
+machine-mcp resource list --show-paths    # explicit local-only disclosure
+machine-mcp resource check maintenance-key
 ```
 
 Registration stores only canonical path and bounded metadata in owner-only state. It reads the file locally to validate accessibility and size but does not print or send its contents. New jobs see registry changes immediately; the daemon does not need a restart.
@@ -59,7 +60,7 @@ Unix-like systems reject group/other-readable resource files by default. `--allo
 Remove an alias with:
 
 ```sh
-machine-mcp resource remove racknerd-key
+machine-mcp resource remove maintenance-key
 ```
 
 Removing an alias affects new jobs. A job already accepted has an owner-only resource snapshot specification and continues independently.
@@ -67,10 +68,10 @@ Removing an alias affects new jobs. A job already accepted has an owner-only res
 Generate a new Ed25519 resource rather than exposing a private-key creation command through a model-generated shell string:
 
 ```sh
-machine-mcp resource generate-ssh-key racknerd-key ~/.ssh/ai-racknerd-maint-ed25519
+machine-mcp resource generate-ssh-key maintenance-key ~/.ssh/machine-mcp-example-maint-ed25519
 ```
 
-Canonical-full MCP clients also receive `generate_ssh_key_resource`. It generates or reuses the pair locally, verifies correspondence, registers the private file, and returns no private bytes. Public-key installation in a cloud or remote account should be a separate reviewed step or managed job.
+Canonical-full MCP clients also receive `generate_ssh_key_resource`. It generates or reuses the pair locally, verifies correspondence, registers the private file, and returns neither private bytes nor local paths by default. Set `expose_paths=true` only for an explicit path-retrieval operation. Public-key installation in a cloud or remote account should be a separate reviewed step or managed job.
 
 ## Resource injection modes
 
@@ -80,7 +81,7 @@ A managed step is argv-based and supports three local resource modes:
 
 ```json
 {
-  "argv": ["ssh", "-i", "{{resource:racknerd-key}}", "root@example", "true"]
+  "argv": ["ssh", "-i", "{{resource:maintenance-key}}", "admin@server.example", "true"]
 }
 ```
 
@@ -152,8 +153,8 @@ For a remote shell program, avoid a remote helper entirely when possible:
       "argv": [
         "ssh",
         "-i",
-        "{{resource:racknerd-key}}",
-        "root@example",
+        "{{resource:maintenance-key}}",
+        "admin@server.example",
         "sh",
         "-s"
       ],
@@ -174,12 +175,12 @@ A job can contain ordered main steps and ordered `finally_steps`:
   "name": "remote maintenance",
   "steps": [
     {
-      "argv": ["ssh", "root@example", "perform-maintenance"]
+      "argv": ["ssh", "admin@server.example", "perform-maintenance"]
     }
   ],
   "finally_steps": [
     {
-      "argv": ["ssh", "root@example", "rm", "-f", "/tmp/maintenance-helper"],
+      "argv": ["ssh", "admin@server.example", "rm", "-f", "/tmp/maintenance-helper"],
       "allow_failure": true
     }
   ]
@@ -207,7 +208,7 @@ machine-mcp job approve JOB_ID
 machine-mcp job approve JOB_ID --yes
 ```
 
-`job inspect` displays the reviewable plan, including argv, ordinary environment overrides, stdin, temporary helper content, and finally steps, while omitting registered resource source paths and per-resource hashes. The overall `plan_sha256` can be compared with the value returned by `stage_job`.
+`job inspect` displays the reviewable plan, including argv, ordinary environment overrides, stdin, temporary helper content, and finally steps, while omitting registered resource source paths and per-resource hashes. The overall `plan_sha256` is displayed for review and is revalidated atomically during approval and again by the runner before execution. A modified staged plan is rejected.
 
 Local approval is a new operator authorization. It intentionally does not depend on the current MCP execution profile: a plan staged under a write-capable profile can be reviewed and approved from the terminal even when the connector is not allowed to execute. The plan retains the filesystem scope and environment mode captured when it was staged.
 

package/docs/OPERATIONS.md

@@ -14,6 +14,7 @@ machine-mcp service status
 
 | Result | Interpretation |
 |---|---|
+| `server_info` reports full and all relay tools, but the current session UI exposes fewer tools | Host/connector post-relay filtering; Machine Bridge cannot enumerate or override that subset |
 | No structured result because the host rejects the call | Host/connector approval or safety layer, or transport before daemon delivery |
 | `mcp-host-to-daemon` passes but `local-filesystem` fails | Local state/runtime permissions, disk policy, sandbox, or endpoint security |
 | Filesystem passes but `local-process-spawn` fails | Local executable policy, endpoint security, OS permissions, or damaged Node runtime |
@@ -21,11 +22,17 @@ machine-mcp service status
 | `managed-job-storage` fails | Owner-only profile/job directory cannot be used |
 | Registered resource is unavailable | File moved, permissions changed, size exceeded, or local access denied |
 
-A successful diagnostic result applies only to that probe. An MCP host can still deny a later call based on its own request context.
+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 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.
+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.
 
 Logging is level-based:
 
@@ -58,7 +65,7 @@ Generate and register an operator key locally:
 machine-mcp resource generate-ssh-key NAME [PRIVATE_KEY_PATH]
 ```
 
-An authorized canonical-full MCP client can use `generate_ssh_key_resource`. Both paths validate the key pair and return only metadata and a public fingerprint. They do not install the public key in Google, modify `authorized_keys`, or grant remote `sudo`; those remain explicit managed-job/local-operator operations.
+An authorized canonical-full MCP client can use `generate_ssh_key_resource`. Both paths validate the key pair and return only metadata and the bare public fingerprint. Local paths are omitted unless `--show-paths` or `expose_paths=true` is explicitly requested; public-key comments are not included in the returned fingerprint. They do not install the public key in Google, modify `authorized_keys`, or grant remote `sudo`; those remain explicit managed-job/local-operator operations.
 
 ## Managed jobs and local recovery
 
@@ -66,7 +73,8 @@ Register local-only resources from the terminal:
 
 ```sh
 machine-mcp resource add NAME FILE_PATH
-machine-mcp resource list
+machine-mcp resource list                 # paths omitted by default
+machine-mcp resource list --show-paths    # explicit local-only disclosure
 machine-mcp resource check NAME
 machine-mcp resource remove NAME
 ```
@@ -102,8 +110,9 @@ Pending calls are bound to the socket that received them. Results from another s
 Defense-in-depth limits include:
 
 - Worker MCP body: 8 MiB by default, hard cap 16 MiB;
+- stdio JSON-RPC line: 8 MiB, enforced incrementally while reading;
 - OAuth body: 64 KiB;
-- daemon WebSocket message: 8 MiB;
+- daemon WebSocket message: 8 MiB, enforced by the local WebSocket parser before string conversion;
 - text writes and patch envelopes: 5 MiB;
 - images: 4 MiB before base64 encoding;
 - shell/argv envelope: 64 KiB;
@@ -128,7 +137,7 @@ Defense-in-depth limits include:
 
 Policy revision 3 makes named profiles canonical. A state entry labelled `full` is repaired to writes, direct processes, process sessions, shell execution, unrestricted direct filesystem paths, absolute path output, the complete parent environment, and the complete tool catalog. CLI capability overrides are stored as `custom`. The exact pre-0.4 implicit-default shape is still migrated to the current `full` default; explicit restrictive and identified custom profiles remain preserved.
 
-`full` removes Machine Bridge's own profile/path/environment/shell denials. It does not override operating-system access controls, endpoint security, remote authentication, cloud IAM, `sudo`, or independent MCP-host/platform policy.
+`full` removes Machine Bridge's own profile/path/environment/shell denials and makes the complete catalog available to the relay. It does not force a connector host to expose every relayed tool, and the server cannot see the host's final subset. It also does not override operating-system access controls, endpoint security, remote authentication, cloud IAM, `sudo`, or independent MCP-host/platform policy.
 
 Inspect effective policy with:
 

package/docs/PRIVACY.md

@@ -0,0 +1,43 @@
+# Repository privacy hygiene
+
+Source code, tests, examples, release notes, and documentation are publication surfaces. Examples must use synthetic identifiers such as `maintenance-key`, `admin@server.example`, reserved example domains, and generic filesystem paths. Do not copy a real server alias, username, hostname, account name, workspace path, key filename, customer name, or internal codename into a fixture merely because the value is not itself a credential.
+
+## Automated check
+
+Run:
+
+```sh
+npm run privacy:check
+```
+
+The check scans tracked and unignored new UTF-8 files and their relative names for private-key material, common live-token forms, user-home paths, non-example `user@host` identifiers, and locally configured private identifiers. Publication-surface symbolic links are rejected rather than followed. Binary, invalid UTF-8, and files above the bounded scanner limit fail closed and require explicit manual review instead of being silently skipped. It reports only the file, line, and rule; it does not print the matched value.
+
+Maintain machine-specific names in an ignored owner-only file:
+
+```sh
+cp .privacy-denylist.example .privacy-denylist
+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:
+
+- inspect the complete staged diff, including tests, snapshots, examples, release notes, and generated metadata;
+- use reserved example domains and neutral aliases;
+- run `npm run privacy:check`, `npm run check`, and `npm pack --dry-run`;
+- treat paths, host aliases, usernames, and codenames as private metadata even when they are not authentication secrets.
+
+The scanner is heuristic. It cannot identify every personal or organizational name, transformed value, image, archive, binary fixture, or data already present in Git history.
+
+## Incident response
+
+For an accidental publication, remove the value from the current tree and release artifacts, determine whether it is merely identifying metadata or an active credential, and rotate/revoke any credential immediately. Public Git and npm history are immutable in ordinary workflows: replacing the current file does not erase old commits or a published package. A coordinated history rewrite, cache invalidation request, or replacement release may be appropriate, but those actions are disruptive and require an explicit repository-owner decision.

package/docs/RELEASING.md

@@ -7,6 +7,8 @@ The release invariant is:
 - A final GitHub Release exists for the tag.
 - The GitHub Release contains the npm tarball generated from that commit.
 - `package.json`, `package-lock.json`, and the Worker-reported version agree.
+- Every release-relevant change since the prior version tag has a higher package version and matching CHANGELOG section.
+- The same reviewed change is present on GitHub and in a new npm version.
 
 `npm publish` runs `release:check` through `prepublishOnly`, so npm publication is blocked until all GitHub state is synchronized.
 
@@ -18,8 +20,11 @@ The release invariant is:
    npm version <version> --no-git-tag-version
    ```
 
-2. Add the matching `CHANGELOG.md` section.
-3. Run `npm run check`, review the diff, and commit all release changes to `main`.
+2. Add the matching dated `CHANGELOG.md` section.
+3. Run `npm run release-impact:check`, `npm run privacy:check`, `npm run check`, both dependency audits, `npm audit signatures`, and generate a CycloneDX `npm sbom`.
+4. Inspect the complete diff and `npm pack --dry-run`, then commit and push all release changes to `main`.
+
+A privacy/security documentation correction is not “docs only” for release purposes. It requires a replacement npm version and, when appropriate, deprecation or unpublication of the affected version.
 
 ## Publish GitHub source and release
 
@@ -29,7 +34,7 @@ From a clean `main` worktree:
 npm run release:publish
 ```
 
-The command validates the project, fast-forwards `origin/main`, creates or verifies the annotated version tag, pushes it, builds the npm tarball, creates or updates the GitHub Release, uploads the tarball, and verifies the resulting state.
+The command validates the project, including repository privacy checks, fast-forwards `origin/main`, creates or verifies the annotated version tag, pushes it, builds the npm tarball, creates or updates the GitHub Release, uploads the tarball, and verifies the resulting state. Read-only GitHub operations, Git pushes, and idempotent release updates use bounded retries only for classified transient network failures; ambiguous Release creation responses are resolved by querying server state before continuing.
 
 To verify without changing anything:
 
@@ -51,7 +56,7 @@ Only after `release:check` succeeds:
 npm publish --access public
 ```
 
-The npm lifecycle repeats the full project checks and the GitHub synchronization check before upload.
+The npm lifecycle repeats the full project checks and the GitHub synchronization check before upload. Do not leave a code or documentation fix only on GitHub; the corresponding npm version must be published, and the operator should be explicitly reminded until registry publication is confirmed.
 
 ## Authentication requirements
 

package/docs/TESTING.md

@@ -8,8 +8,11 @@ The project treats transport, authorization, local authority, and state removal
 npm run check
 ```
 
+The repository requires Node.js 26 and npm 12. `.node-version`, `.nvmrc`, `packageManager`, `devEngines`, and strict engine checks keep local and CI execution on the same baseline.
+
 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;
 - syntax validation for every shipped JavaScript entry point;
 - shared tool-catalog schema, annotation, and profile-inventory checks;
@@ -34,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.
@@ -44,11 +49,14 @@ The suite includes:
 npm run worker:dry-run
 npm audit --audit-level=high
 npm audit --omit=dev --audit-level=high
+npm audit signatures
+npm sbom --sbom-format cyclonedx
 npm pack --dry-run
 npm run version:check
+npm run release-impact:check
 ```
 
-GitHub Actions executes the main suite on Linux, macOS, and Windows. Node 22 and 24 are covered on Linux; Node 22 is covered on macOS and Windows. A separate package-audit job audits both the complete dependency graph and the production-only graph, 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
 
@@ -61,3 +69,17 @@ GitHub Actions executes the main suite on Linux, macOS, and Windows. Node 22 and
 - Secret-bearing resource tests must assert absence of raw, path, base64, and hex forms from MCP-visible results.
 - Logs and public metadata should be tested for absence of sensitive fields, arguments, outputs, and routine success noise—not only presence of expected fields.
 - Cross-platform tests must avoid shell syntax, URL-path conversion, and executable-shim assumptions specific to one operating system.
+
+## Privacy hygiene
+
+Run `npm run privacy:check` before committing and before packaging. Developers should maintain an ignored owner-only `.privacy-denylist` for machine aliases, usernames, internal codenames, and other private identifiers that a generic scanner cannot know. See [Repository privacy hygiene](PRIVACY.md).
+
+## 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/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,11 +1,11 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.6.2",
+  "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",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=26.0.0"
   },
   "bin": {
     "machine-bridge-mcp": "bin/machine-mcp.mjs",
@@ -20,11 +20,15 @@
     "src/shared",
     "src/worker/index.ts",
     "scripts/sync-worker-version.mjs",
+    "scripts/privacy-check.mjs",
+    "scripts/release-impact-check.mjs",
+    "scripts/network-retry.mjs",
     "wrangler.jsonc",
     "tsconfig.json",
     "README.md",
     "SECURITY.md",
     "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "docs",
     "LICENSE"
   ],
@@ -35,12 +39,12 @@
     "version:sync": "node scripts/sync-worker-version.mjs",
     "version:check": "node scripts/sync-worker-version.mjs --check",
     "version": "node scripts/sync-worker-version.mjs && git add package.json package-lock.json src/worker/index.ts",
-    "prepack": "npm run version:check",
+    "prepack": "npm run version:check && npm run privacy:check && npm run release-impact:check",
     "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/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",
-    "check": "npm run typecheck && npm run syntax && npm run catalog:test && npm run self-test && npm run atomic-fs: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",
@@ -51,15 +55,25 @@
     "managed-jobs:test": "node tests/managed-jobs-test.mjs",
     "ssh-key:test": "node tests/ssh-key-test.mjs",
     "full-access:test": "node tests/full-access-test.mjs",
-    "atomic-fs:test": "node tests/atomic-fs-test.mjs"
+    "atomic-fs:test": "node tests/atomic-fs-test.mjs",
+    "privacy:check": "node scripts/privacy-check.mjs",
+    "package:test": "node tests/package-test.mjs",
+    "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",
+    "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",
     "ws": "8.21.0"
   },
   "devDependencies": {
-    "@types/node": "^22.20.1",
-    "typescript": "^7.0.2"
+    "@types/node": "26.1.1",
+    "typescript": "7.0.2"
   },
   "keywords": [
     "mcp",
@@ -89,5 +103,18 @@
     "sharp@0.34.5": true,
     "workerd@1.20260708.1": true,
     "fsevents": false
+  },
+  "packageManager": "npm@12.0.1",
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=26.0.0",
+      "onFail": "error"
+    },
+    "packageManager": {
+      "name": "npm",
+      "version": ">=12.0.0",
+      "onFail": "error"
+    }
   }
 }

package/scripts/network-retry.mjs

@@ -0,0 +1,47 @@
+import { spawnSync } from "node:child_process";
+
+const WAIT_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+const TRANSIENT_NETWORK_FAILURE = /(?:SSL_ERROR_SYSCALL|SSL_connect|TLS handshake timeout|Client network socket disconnected before secure TLS connection was established|unexpected EOF|unexpected eof while reading|\bEOF\b|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|ECONNREFUSED|Could not resolve host|Failed to connect|connection (?:was )?reset|remote end hung up|unexpected disconnect|HTTP (?:429|5\d\d)|(?:502|503|504) (?:Bad Gateway|Service Unavailable|Gateway Timeout))/i;
+
+export function runNetworkCommand(command, args, options = {}) {
+  const attempts = clampInteger(options.attempts, 3, 1, 5);
+  const baseDelayMs = clampInteger(options.baseDelayMs, 750, 0, 10_000);
+  const actualArgs = networkCommandArgs(command, args);
+  let result;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    result = spawnSync(command, actualArgs, {
+      cwd: options.cwd,
+      encoding: "utf8",
+      stdio: "pipe",
+      env: options.env,
+      windowsHide: true,
+    });
+    result.attempts = attempt;
+    if (!isTransientNetworkFailure(result) || attempt === attempts) return result;
+    sleepSync(Math.min(baseDelayMs * attempt, 5_000));
+  }
+  return result;
+}
+
+export function networkCommandArgs(command, args) {
+  return command === "git" ? ["-c", "http.version=HTTP/1.1", ...args] : [...args];
+}
+
+export function isTransientNetworkFailure(result) {
+  if (result?.error) {
+    const code = String(result.error.code || "");
+    if (["ECONNRESET", "ETIMEDOUT", "EAI_AGAIN", "ENETUNREACH", "ECONNREFUSED"].includes(code)) return true;
+  }
+  const detail = `${result?.stdout ?? ""}\n${result?.stderr ?? ""}\n${result?.error?.message ?? ""}`;
+  return TRANSIENT_NETWORK_FAILURE.test(detail);
+}
+
+function sleepSync(milliseconds) {
+  if (milliseconds > 0) Atomics.wait(WAIT_BUFFER, 0, 0, milliseconds);
+}
+
+function clampInteger(value, fallback, minimum, maximum) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  const number = Number.isFinite(parsed) ? parsed : fallback;
+  return Math.min(Math.max(number, minimum), maximum);
+}