machine-bridge-mcp 0.6.0 → 0.7.1

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,19 +22,19 @@ 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.
 
 ## 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:
 
 ```text
-error  unrecoverable local/transport failures
-warn   failed calls, disconnects, malformed relay events
-info   startup/deploy/connect transitions and calls slower than 30 seconds
-debug  routine successful calls, shortened correlation IDs, cancellation/reconnect details
+error  unrecoverable local/transport/service failures
+warn   relay disconnect/send failures, malformed relay events, supersession and service problems
+info   startup/deploy/connect transitions
+debug  all per-tool starts/successes/failures/cancellations/timing, correlation and reconnect details
 ```
 
 Foreground mode defaults to `info`; autostart uses `warn`. Use `--verbose` or `--log-level debug` only for diagnosis. `--quiet` is an alias for `--log-level error`.
@@ -42,13 +43,32 @@ Normal logs intentionally omit tool arguments, file/patch/image content, command
 
 See [LOGGING.md](LOGGING.md) for the event contract and MCP-host boundary. Cloudflare observability is sampled and is not a complete audit log.
 
+## Full capability acceptance
+
+Run:
+
+```sh
+machine-mcp full-test --workspace /path/to/project
+```
+
+The command uses disposable local directories and performs actual read/write, process, shell, environment, SSH-key, sandbox authorized-key, SSH-client, managed-job and finally-cleanup operations. It also checks whether the Google Cloud OS Login command exists and whether `sudo -n true` is currently permitted, without changing either system. `ok` covers core Machine Bridge functionality; `operator_workflow_ready` additionally reports the local SSH/Google CLI prerequisites. No external cloud, account, or server change is made.
+
+Generate and register an operator key locally:
+
+```sh
+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 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
 
 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
 ```
@@ -84,8 +104,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;
@@ -108,9 +129,9 @@ Defense-in-depth limits include:
 
 ## Upgrade behavior
 
-Version 0.5 records policy origin and revision. A state entry matching the exact legacy implicit-default shape—write enabled, shell enabled, workspace-confined paths, isolated environment, and relative output—is migrated once to the current `full` default. Explicit named profiles and identified custom policies are preserved.
+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` enables writes, direct processes, process sessions, shell execution, unrestricted direct filesystem paths, absolute path output, and the complete parent environment. It does not override operating-system access controls 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,37 @@
+# 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.
+
+## 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;
@@ -25,11 +28,15 @@ The suite includes:
 - one-shot timeout, descendant termination, cancellation, and process-session interaction;
 - layered fixed runtime diagnostics for filesystem, direct process, shell, managed-job storage, and resource availability;
 - local resource CLI registration, permission checks, dynamic reload, state-path redaction, and content non-disclosure;
+- real Ed25519 and RSA generation, idempotent reuse, public/private correspondence, mode enforcement, incomplete/mismatched/symlink rejection, and private-content non-disclosure;
+- real-machine canonical-full sandbox acceptance for outside-workspace I/O, direct/shell execution, full environment inheritance, SSH prerequisites, temporary authorized-key writing, and detached cleanup without external state changes;
+- deterministic injected atomic-replace failures and repeated Windows full-sandbox runs to catch transient file-sharing races;
+- canonical named-profile repair and full-only tool exposure parity between local and Worker policy filters;
 - managed-job staging/local approval/cancel-before-start, detachment, job-scoped temporary files, resource hash verification/redaction, discard capture, finally execution, cancellation escalation, plan scrubbing, and dead-runner recovery;
 - daemon/startup locking and state corruption recovery;
 - 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, default success-log suppression, and service warning-level configuration;
+- log redaction, control-character handling, message/field bounds, suppression of both successful and failed per-tool events outside debug, and service warning-level configuration;
 - 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.
@@ -40,11 +47,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, then performs a dry-run package build. Dependency and GitHub Actions updates are monitored by Dependabot.
 
 ## Test design rules
 
@@ -57,3 +67,13 @@ 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 guidance, contribution/release discipline, and both privacy/release-impact checkers are present in the published package.
+
+The stdio integration test also sends an oversized line, verifies bounded rejection, and confirms that the next valid request is still processed.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.6.0",
-  "description": "Cross-client MCP bridge for policy-controlled local files, Git, images, patches, and processes over stdio or OAuth-protected remote relay.",
+  "version": "0.7.1",
+  "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/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",
-    "check": "npm run typecheck && npm run syntax && npm run catalog:test && npm run self-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/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",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
@@ -48,15 +52,24 @@
     "release:backfill": "node scripts/github-release.mjs --backfill",
     "stdio:integration-test": "node tests/stdio-integration-test.mjs",
     "catalog:test": "node tests/catalog-test.mjs",
-    "managed-jobs:test": "node tests/managed-jobs-test.mjs"
+    "managed-jobs:test": "node tests/managed-jobs-test.mjs",
+    "ssh-key:test": "node tests/ssh-key-test.mjs",
+    "full-access:test": "node tests/full-access-test.mjs",
+    "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"
   },
   "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",
@@ -68,7 +81,10 @@
     "stdio",
     "coding-agent",
     "oauth",
-    "cross-platform"
+    "cross-platform",
+    "ssh",
+    "automation",
+    "managed-jobs"
   ],
   "repository": {
     "type": "git",
@@ -83,5 +99,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);
+}

package/scripts/privacy-check.mjs

@@ -0,0 +1,177 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const selfPath = "scripts/privacy-check.mjs";
+const candidates = collectCandidateFiles(root);
+const denylist = loadDenylist(path.join(root, ".privacy-denylist"));
+const findings = [];
+
+for (const relativePath of candidates) {
+  if (relativePath === ".privacy-denylist") continue;
+  scanDenylistPath(relativePath, denylist, findings);
+  const fullPath = path.join(root, relativePath);
+  let info;
+  try { info = lstatSync(fullPath); } catch { continue; }
+  if (info.isSymbolicLink()) {
+    findings.push({ path: relativePath, line: 1, rule: "symbolic link in publication surface" });
+    continue;
+  }
+  if (!info.isFile()) continue;
+  let buffer;
+  try { buffer = readFileSync(fullPath); } catch { continue; }
+  if (buffer.length > 5 * 1024 * 1024) {
+    findings.push({ path: relativePath, line: 1, rule: "file exceeds privacy scanner size limit and requires manual review" });
+    continue;
+  }
+  if (buffer.includes(0)) {
+    findings.push({ path: relativePath, line: 1, rule: "binary file in publication surface requires manual review" });
+    continue;
+  }
+  let text;
+  try { text = new TextDecoder("utf-8", { fatal: true }).decode(buffer); } catch {
+    findings.push({ path: relativePath, line: 1, rule: "non-UTF-8 file in publication surface requires manual review" });
+    continue;
+  }
+  if (relativePath !== selfPath) scanBuiltIn(relativePath, text, findings);
+  scanDenylist(relativePath, text, denylist, findings);
+}
+
+if (findings.length) {
+  for (const finding of findings.slice(0, 100)) {
+    process.stderr.write(`${redactReportPath(finding.path, denylist)}:${finding.line}: ${finding.rule}\n`);
+  }
+  if (findings.length > 100) process.stderr.write(`... ${findings.length - 100} additional findings omitted\n`);
+  process.stderr.write("Privacy check failed. Replace private identifiers with synthetic examples or review the local denylist.\n");
+  process.exit(1);
+}
+
+process.stderr.write(`privacy check ok (${candidates.length} tracked/unignored files; ${denylist.length} local denylist entries)\n`);
+
+function collectCandidateFiles(directory) {
+  try {
+    return execFileSync("git", ["-C", directory, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+      encoding: "buffer",
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).toString("utf8").split("\0").filter(Boolean).sort();
+  } catch {
+    const excluded = new Set([".git", ".wrangler", "node_modules"]);
+    const files = [];
+    const stack = [""];
+    while (stack.length) {
+      const relative = stack.pop();
+      const absolute = path.join(directory, relative);
+      let entries;
+      try { entries = readdirSync(absolute, { withFileTypes: true }); } catch { continue; }
+      for (const entry of entries) {
+        if (excluded.has(entry.name) || entry.name === ".privacy-denylist") continue;
+        const child = relative ? path.join(relative, entry.name) : entry.name;
+        if (entry.isDirectory()) stack.push(child);
+        else if (entry.isFile() || entry.isSymbolicLink()) files.push(child.split(path.sep).join("/"));
+      }
+    }
+    return files.sort();
+  }
+}
+
+function redactReportPath(relativePath, entries) {
+  let shown = String(relativePath);
+  for (const entry of entries) {
+    const expression = new RegExp(escapeRegExp(entry), "gi");
+    shown = shown.replace(expression, "<private>");
+  }
+  return shown;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function scanBuiltIn(relativePath, text, out) {
+  const rules = [
+    ["private key material", /-----BEGIN\s+(?:OPENSSH|RSA|EC|DSA)\s+PRIVATE\s+KEY-----/g],
+    ["AWS access key", /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g],
+    ["GitHub access token", /\bgh[pousr]_[A-Za-z0-9_]{30,}\b/g],
+    ["API secret token", /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g],
+    ["absolute macOS/Linux home path", /(?:^|[\s"'=(:,])\/(?:Users|home)\/([^/\s"'<>]+)\//gm],
+    ["absolute Windows home path", /(?:^|[\s"'=(:,])\b[A-Za-z]:\\Users\\([^\\\s"'<>]+)\\/gm],
+  ];
+  for (const [rule, expression] of rules) {
+    for (const match of text.matchAll(expression)) {
+      if (rule.includes("home path") && isSyntheticUser(String(match[1] || ""))) continue;
+      out.push({ path: relativePath, line: lineNumber(text, match.index || 0), rule });
+    }
+  }
+  const sshLike = /\b[A-Za-z_][A-Za-z0-9._-]*@([A-Za-z0-9.-]+)\b/g;
+  for (const match of text.matchAll(sshLike)) {
+    if (isReservedExampleHost(match[1]) || !hasNearbySshContext(text, match.index || 0)) continue;
+    out.push({ path: relativePath, line: lineNumber(text, match.index || 0), rule: "non-example SSH user@host identifier" });
+  }
+}
+
+function scanDenylistPath(relativePath, entries, out) {
+  const lower = relativePath.toLocaleLowerCase("en-US");
+  for (const entry of entries) {
+    if (lower.includes(entry)) out.push({ path: relativePath, line: 1, rule: "local private-identifier denylist match in file path" });
+  }
+}
+
+function scanDenylist(relativePath, text, entries, out) {
+  const lower = text.toLocaleLowerCase("en-US");
+  for (const entry of entries) {
+    let offset = 0;
+    while ((offset = lower.indexOf(entry, offset)) !== -1) {
+      out.push({ path: relativePath, line: lineNumber(text, offset), rule: "local private-identifier denylist match" });
+      offset += Math.max(1, entry.length);
+    }
+  }
+}
+
+function loadDenylist(file) {
+  if (!existsSync(file)) return [];
+  let text;
+  try { text = readFileSync(file, "utf8"); } catch { return []; }
+  return [...new Set(text.split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#") && line.length >= 3)
+    .map((line) => line.toLocaleLowerCase("en-US")))];
+}
+
+function isSyntheticUser(value) {
+  return /^(?:user|username|example|test|name|home|runner|workspace|tmp|private|path|package)$/i.test(value)
+    || /^<[^>]+>$/.test(value);
+}
+
+function hasNearbySshContext(text, offset) {
+  const lineStart = Math.max(0, text.lastIndexOf("\n", offset - 1));
+  let start = lineStart;
+  for (let count = 0; count < 4 && start > 0; count += 1) start = Math.max(0, text.lastIndexOf("\n", start - 1));
+  let end = offset;
+  for (let count = 0; count < 4 && end < text.length; count += 1) {
+    const next = text.indexOf("\n", end + 1);
+    end = next === -1 ? text.length : next;
+  }
+  return /\b(?:ssh|scp|sftp)\b/i.test(text.slice(start, end));
+}
+
+function isReservedExampleHost(host) {
+  const value = String(host || "").toLowerCase().replace(/\.$/, "");
+  return value === "localhost"
+    || value === "127.0.0.1"
+    || value === "::1"
+    || value === "example"
+    || value.endsWith(".example")
+    || value.endsWith(".example.com")
+    || value.endsWith(".example.net")
+    || value.endsWith(".example.org")
+    || value.endsWith(".invalid");
+}
+
+function lineNumber(text, offset) {
+  let line = 1;
+  for (let index = 0; index < offset; index += 1) if (text.charCodeAt(index) === 10) line += 1;
+  return line;
+}

package/scripts/release-impact-check.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+const VERSION_TAG = /^v(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const current = parseVersion(String(pkg.version || ""));
+if (!current) fail("package.json contains an invalid version");
+
+const tags = git(["tag", "--merged", "HEAD", "--sort=-version:refname", "--list", "v[0-9]*"])
+  .split("\n")
+  .map((value) => value.trim())
+  .filter((value) => VERSION_TAG.test(value));
+if (!tags.length) {
+  process.stderr.write("release impact check skipped: no reachable version tag\n");
+  process.exit(0);
+}
+
+const latestTag = tags[0];
+const latest = parseVersion(latestTag.slice(1));
+const changed = new Set([
+  ...lines(git(["diff", "--name-only", latestTag, "--"])),
+  ...lines(git(["ls-files", "--others", "--exclude-standard"])),
+]);
+const relevant = [...changed].sort();
+
+if (!relevant.length) {
+  process.stderr.write(`release impact check ok: no release-relevant changes since ${latestTag}\n`);
+  process.exit(0);
+}
+if (compareVersions(current, latest) <= 0) {
+  fail(`release-relevant changes exist since ${latestTag}, but package.json is still ${pkg.version}; bump the npm version and add a CHANGELOG section before merging`);
+}
+
+const changelog = readFileSync(new URL("../CHANGELOG.md", import.meta.url), "utf8");
+const heading = new RegExp(`^## ${escapeRegExp(pkg.version)}(?:\\s+-[^\\n]*)?$`, "m");
+if (!heading.test(changelog)) fail(`CHANGELOG.md has no section for ${pkg.version}`);
+
+process.stderr.write(`release impact check ok: ${relevant.length} release-relevant file(s) since ${latestTag}; next npm version ${pkg.version}\n`);
+
+function git(args) {
+  try {
+    return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch (error) {
+    const detail = String(error?.stderr || error?.message || error).trim();
+    fail(`git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+  }
+}
+
+function lines(value) {
+  return value ? value.split("\n").map((item) => item.trim()).filter(Boolean) : [];
+}
+
+function parseVersion(value) {
+  const match = String(value).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  return match ? { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), prerelease: match[4] || "" } : null;
+}
+
+function compareVersions(left, right) {
+  for (const key of ["major", "minor", "patch"]) {
+    if (left[key] !== right[key]) return left[key] - right[key];
+  }
+  if (left.prerelease === right.prerelease) return 0;
+  if (!left.prerelease) return 1;
+  if (!right.prerelease) return -1;
+  return left.prerelease.localeCompare(right.prerelease);
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function fail(message) {
+  process.stderr.write(`release impact check failed: ${message}\n`);
+  process.exit(1);
+}