machine-bridge-mcp 0.5.0 → 0.6.2

package/docs/MANAGED_JOBS.md

@@ -0,0 +1,282 @@
+# Managed jobs and local resources
+
+## Problem addressed
+
+An MCP conversation is not a durable execution coordinator. A host or connector may reject a later tool call, an approval may be withdrawn, the network may disconnect, or local endpoint-security software may begin denying process creation. A sequence such as:
+
+1. create a helper script;
+2. connect to a remote server;
+3. repair the service;
+4. remove the helper;
+
+can therefore stop after step 2 or 3 and leave local or remote temporary state behind.
+
+Machine Bridge managed jobs reduce this failure mode by accepting the complete execution and cleanup plan in one call. After acceptance, an independent local runner owns the lifecycle. It does not depend on the MCP socket remaining connected.
+
+This mechanism does **not** bypass host, operating-system, or endpoint-security policy. A job snapshots its execution policy/environment at acceptance; later profile changes affect new jobs, while accepted jobs continue until completion or explicit cancellation. The initial `start_job` request must still be permitted, and every local child process remains subject to local security controls.
+
+## Diagnose the blocking layer
+
+Use the MCP tool:
+
+```text
+diagnose_runtime
+```
+
+or the local terminal:
+
+```sh
+machine-mcp doctor
+```
+
+Interpretation:
+
+| Observation | Likely boundary |
+|---|---|
+| The tool call is rejected before any structured response | MCP host, connector gateway, approval system, or transport |
+| `diagnose_runtime` responds, but `local-process-spawn` fails | Local OS permissions, endpoint security, executable policy, or broken runtime |
+| Process spawn passes but `local-shell` fails | Shell configuration or shell-specific local policy |
+| Managed-job storage fails | State-root permissions, disk, filesystem policy, or endpoint security |
+| A job was accepted and later MCP calls are rejected | The detached job continues; inspect it through local CLI |
+
+A successful diagnostic response proves that particular request reached the local daemon. It cannot retrospectively identify a request that the host blocked before delivery.
+
+## Register local resources
+
+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
+```
+
+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.
+
+Unix-like systems reject group/other-readable resource files by default. `--allow-insecure-permissions` is an explicit override. Windows ACLs and extended Unix ACLs cannot be fully represented by the portable mode check, so operators must still inspect platform permissions.
+
+Remove an alias with:
+
+```sh
+machine-mcp resource remove racknerd-key
+```
+
+Removing an alias affects new jobs. A job already accepted has an owner-only resource snapshot specification and continues independently.
+
+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
+```
+
+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.
+
+## Resource injection modes
+
+A managed step is argv-based and supports three local resource modes:
+
+### File-path placeholder
+
+```json
+{
+  "argv": ["ssh", "-i", "{{resource:racknerd-key}}", "root@example", "true"]
+}
+```
+
+The runner copies the resource into the private job runtime with mode `0600`, substitutes that copy's path, and removes the runtime after cleanup.
+
+### Standard input
+
+```json
+{
+  "argv": ["some-program", "--password-stdin"],
+  "stdin_resource": "service-password",
+  "capture_output": "discard"
+}
+```
+
+### Environment variable
+
+```json
+{
+  "argv": ["some-program"],
+  "env_resources": {
+    "SERVICE_TOKEN": "service-token"
+  },
+  "capture_output": "discard"
+}
+```
+
+Environment injection is convenient but may expose a value to same-user process inspection or child processes. Prefer a file path or stdin when the target program supports it.
+
+At job acceptance, referenced resources are reopened, bounded, hashed, and recorded in the owner-only active plan. The runner reopens and verifies the hash before copying. A changed resource causes the job to fail rather than silently using different content.
+
+## Job-scoped temporary files
+
+Do not create ad hoc helpers in the workspace when the file exists only for one operation. Include it in the job:
+
+```json
+{
+  "temporary_files": [
+    {
+      "name": "repair.js",
+      "content": "console.log('repair')"
+    }
+  ],
+  "steps": [
+    {
+      "argv": ["node", "{{temp:repair.js}}"]
+    }
+  ]
+}
+```
+
+Available placeholders are:
+
+```text
+{{temp:name}}
+{{resource:name}}
+{{job:runtime}}
+{{job:workspace}}
+```
+
+Temporary files live only below the private job runtime and are removed in the runner's final cleanup path. This is preferable to writing into `Codex/daily/ops`, `/tmp`, or a remote home directory and relying on a later MCP call to delete the file.
+
+For a remote shell program, avoid a remote helper entirely when possible:
+
+```json
+{
+  "steps": [
+    {
+      "argv": [
+        "ssh",
+        "-i",
+        "{{resource:racknerd-key}}",
+        "root@example",
+        "sh",
+        "-s"
+      ],
+      "stdin": "set -eu\n# repair commands here\n"
+    }
+  ]
+}
+```
+
+The script travels through the SSH process stdin and is not stored as a remote file.
+
+## Finally steps
+
+A job can contain ordered main steps and ordered `finally_steps`:
+
+```json
+{
+  "name": "remote maintenance",
+  "steps": [
+    {
+      "argv": ["ssh", "root@example", "perform-maintenance"]
+    }
+  ],
+  "finally_steps": [
+    {
+      "argv": ["ssh", "root@example", "rm", "-f", "/tmp/maintenance-helper"],
+      "allow_failure": true
+    }
+  ]
+}
+```
+
+Finally steps are attempted after success, failure, timeout, or cancellation. Cancellation is delivered through an owner-only marker polled by the runner; the runner terminates the current child process tree and remains alive to execute cleanup. This avoids platform-specific signal behavior killing the coordinator itself. If a runner is interrupted, the next daemon start or local `machine-mcp job ...` command detects the dead runner, removes stale private resource copies, and runs the finally phase in recovery mode.
+
+Automatic dead-runner recovery is attempted at most three times; persistent failure becomes `recovery_exhausted` to avoid an endless restart loop. Cleanup is best effort, not mathematically guaranteed. Power loss, disk failure, permanent account loss, or a local security product that denies the cleanup executable can still prevent it. Finally steps should therefore be idempotent and safe to run more than once.
+
+## Two-phase local approval
+
+If the MCP host rejects execution-class tools but still allows state changes, use:
+
+```text
+stage_job
+```
+
+This performs the same schema, cwd, resource, size, and permission validation as `start_job`, but records status `staged` and launches no process. The response includes the local approval command:
+
+```sh
+machine-mcp job inspect JOB_ID
+machine-mcp job approve JOB_ID
+# or after a separate review, non-interactively:
+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`.
+
+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.
+
+Before approval:
+
+- no main step runs;
+- no finally step runs;
+- no resource is copied into a runtime directory;
+- cancelling produces `cancelled_before_start` and deletes the plan.
+
+Staged plans count toward the 50-item retention limit and expire with the seven-day job retention policy. They are not considered active processes and do not independently block uninstall after the normal uninstall confirmation.
+
+## Submit and inspect
+
+Through MCP:
+
+```text
+stage_job
+start_job
+list_jobs
+read_job
+cancel_job
+```
+
+From the local terminal, including after an MCP host blocks further execution calls:
+
+```sh
+machine-mcp job list
+machine-mcp job inspect JOB_ID
+machine-mcp job approve JOB_ID [--yes]
+machine-mcp job cancel JOB_ID
+```
+
+A local JSON fallback is also available:
+
+```sh
+machine-mcp job submit plan.json
+```
+
+The plan format is the same object accepted by `start_job`.
+
+## Output and secret handling
+
+Step output is bounded to 64 KiB per stream and a shared 256 KiB capture budget per job, then stored in owner-only job results. Exact registered resource paths and exact resource content are replaced before results are returned. Common exact base64 and hexadecimal forms are also replaced for bounded resources.
+
+This redaction is defense in depth, not a data-loss-prevention guarantee. It cannot reliably detect:
+
+- partial secrets;
+- encrypted, compressed, hashed, or otherwise transformed values;
+- values copied from the full inherited environment rather than registered resources;
+- application-specific encodings.
+
+Use:
+
+```json
+{ "capture_output": "discard" }
+```
+
+for any step that may echo a credential. In discard mode stdout and stderr are consumed but not retained or returned.
+
+Never place a secret directly in `argv`, `env`, `stdin`, a temporary file's `content`, or a plan JSON file. Use a registered resource alias.
+
+## Persistence and privacy
+
+Per-workspace jobs are stored below the owner-only profile directory. Active jobs retain an owner-only plan for crash recovery. After a terminal status is committed, the full plan is deleted, including argv, stdin, embedded temporary-file content, and resource source paths.
+
+Retained public job data contains bounded status and redacted results. Up to 50 jobs are retained for up to seven days. Private runtime copies are removed after the finally phase. Runner stdout/stderr log files contain only runner-level diagnostics; step output is not written to those operational logs.
+
+Process sessions and managed jobs have different semantics:
+
+- process sessions are interactive, memory-only, and die with the daemon connection;
+- managed jobs are non-interactive, persistent, detached, and designed to survive MCP disconnection.

package/docs/OPERATIONS.md

@@ -8,7 +8,20 @@ machine-mcp doctor
 machine-mcp service status
 ```
 
-`status` prints redacted profile state and verifies the deployed Worker version. `doctor` checks Node.js, the package-installed Wrangler binary, Cloudflare login, and Worker health. Public `/healthz` output contains only server identity and version; daemon details require an authenticated `server_info` call.
+`status` prints redacted profile state and verifies the deployed Worker version. Resource source paths remain redacted. `doctor` checks Node.js, the package-installed Wrangler binary, Cloudflare login, Worker health, and the same fixed local filesystem/process/shell/job-storage/resource probes exposed by `diagnose_runtime`. Public `/healthz` output contains only server identity and version; daemon details require an authenticated `server_info` call.
+
+### Blocking-layer decision table
+
+| Result | Interpretation |
+|---|---|
+| 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 |
+| Direct spawn passes but `local-shell` fails | Shell path/profile/policy problem |
+| `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.
 
 ## Logs
 
@@ -17,10 +30,10 @@ Remote autostart logs are stored under the state root in `logs/daemon.out.log` a
 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`.
@@ -29,6 +42,55 @@ 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 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.
+
+## 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 check NAME
+machine-mcp resource remove NAME
+```
+
+Inspect detached jobs even when the MCP host no longer permits execution tools:
+
+```sh
+machine-mcp job list
+machine-mcp job inspect JOB_ID
+machine-mcp job approve JOB_ID [--yes]
+machine-mcp job cancel JOB_ID
+machine-mcp job submit plan.json
+```
+
+Registry changes apply to newly submitted jobs without restarting the daemon. Active jobs use the resource snapshot accepted with their plan.
+
+Policy changes affect new direct submissions. Cancel accepted running jobs explicitly when revoking execution authority. A staged plan launches only after local `job approve`, which is an independent operator authorization. A managed job transitions through `queued`, `running`, `cleaning`, and a terminal status such as `succeeded`, `failed`, or `cancelled`. Cleanup-specific terminal variants report a failed finally phase. If a runner PID dies, the next daemon/job-CLI start marks the job interrupted, removes stale private runtime copies, and runs the finally phase in recovery mode. Automatic recovery is capped at three attempts; persistent failure becomes `recovery_exhausted`.
+
+Use job-scoped `temporary_files` for local helpers. For remote maintenance, prefer `ssh ... sh -s` with the remote script in step `stdin`; this avoids remote temporary scripts. Explicit remote cleanup belongs in idempotent `finally_steps`.
+
+Uninstall refuses to remove local state while any managed job remains active. Active plans are needed for recovery and are owner-only. Terminal jobs delete their full plans. Bounded redacted results and runner-level diagnostics remain for up to seven days/50 jobs. Step output is never copied to ordinary daemon logs.
+
+See [MANAGED_JOBS.md](MANAGED_JOBS.md).
+
 ## Reconnect and replacement
 
 The daemon sends heartbeats and reconnects with bounded exponential backoff and jitter. A new socket remains a candidate until it authenticates and sends a valid `hello`; only then does it replace the previous daemon.
@@ -54,13 +116,19 @@ Defense-in-depth limits include:
 - command timeout: 1–600 seconds;
 - process-session read wait: at most 30 seconds;
 - direct directory result: 10,000 entries and 4 MiB of path metadata;
-- recursive walk: 200,000 visited entries.
+- recursive walk: 200,000 visited entries;
+- managed jobs: 50 retained, seven-day retention;
+- managed-job steps: 16 main plus 16 finally;
+- managed-job timeout: 1–3,600 seconds per step;
+- managed-job output: 64 KiB per stream and 256 KiB total captured across one job;
+- registered resources: 64, 1 MiB each, 8 MiB referenced per job;
+- job-scoped temporary files: 16 files, 512 KiB total content.
 
 ## 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. It does not override operating-system access controls, endpoint security, remote authentication, cloud IAM, `sudo`, or independent MCP-host/platform policy.
 
 Inspect effective policy with:
 
@@ -85,5 +153,6 @@ After suspected credential or client compromise:
 1. stop foreground and autostart daemons;
 2. run `machine-mcp rotate-secrets`;
 3. restart without broad flags and redeploy;
-4. inspect Cloudflare account access, Worker configuration, local state permissions, and service logs;
-5. remove the Worker and local state if continued remote access is unnecessary.
+4. inspect Cloudflare account access, Worker configuration, local state/resource permissions, managed-job results, and service logs;
+5. cancel active managed jobs and remove compromised resource aliases;
+6. remove the Worker and local state if continued remote access is unnecessary.

package/docs/TESTING.md

@@ -23,12 +23,19 @@ The suite includes:
 - author-email privacy in `git_log`;
 - isolated command HOME/temp/cache behavior;
 - 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, and continued responsiveness;
+- 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.
 
 ## Additional release checks
@@ -50,5 +57,7 @@ GitHub Actions executes the main suite on Linux, macOS, and Windows. Node 22 and
 - Every bounded resource needs an over-limit test.
 - Every multi-stage mutation needs a no-partial-commit test.
 - Every remote call correlation change needs daemon replacement and cancellation coverage.
+- Every durable workflow needs disconnect, cancellation, cleanup-failure, dead-runner, and plan-scrubbing coverage.
+- 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.5.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.6.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",
   "engines": {
@@ -39,15 +39,19 @@
     "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 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",
-    "check": "npm run typecheck && npm run syntax && npm run catalog:test && npm run self-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/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",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
     "release:publish": "node scripts/github-release.mjs --publish",
     "release:backfill": "node scripts/github-release.mjs --backfill",
     "stdio:integration-test": "node tests/stdio-integration-test.mjs",
-    "catalog:test": "node tests/catalog-test.mjs"
+    "catalog:test": "node tests/catalog-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"
   },
   "dependencies": {
     "wrangler": "4.110.0",
@@ -67,7 +71,10 @@
     "stdio",
     "coding-agent",
     "oauth",
-    "cross-platform"
+    "cross-platform",
+    "ssh",
+    "automation",
+    "managed-jobs"
   ],
   "repository": {
     "type": "git",

package/src/local/atomic-fs.mjs

@@ -0,0 +1,37 @@
+import { renameSync } from "node:fs";
+
+const TRANSIENT_REPLACE_ERRORS = new Set(["EACCES", "EBUSY", "EPERM", "ENOTEMPTY"]);
+const WAIT_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+
+export function replaceFileSync(source, target, options = {}) {
+  const rename = typeof options.rename === "function" ? options.rename : renameSync;
+  const attempts = clampInteger(options.attempts, 8, 1, 32);
+  const baseDelayMs = clampInteger(options.baseDelayMs, 15, 0, 1000);
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      rename(source, target);
+      return { attempts: attempt };
+    } catch (error) {
+      lastError = error;
+      if (!isTransientReplaceError(error) || attempt === attempts) throw error;
+      sleepSync(Math.min(baseDelayMs * attempt, 250));
+    }
+  }
+  throw lastError || new Error("atomic file replacement failed");
+}
+
+export function isTransientReplaceError(error) {
+  return TRANSIENT_REPLACE_ERRORS.has(String(error?.code || ""));
+}
+
+function sleepSync(milliseconds) {
+  if (milliseconds <= 0) return;
+  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);
+}