@ricsam/r5d-worker 0.0.137 → 0.0.138

package/README.md

@@ -1,100 +1,10 @@
 # r5d-worker
 
-`r5d-worker` connects a local or remote machine to r5d.dev so the agent can run host commands through the live worker.
+Bun CLI for the durable host executor and independently supervised adapter manager used by the runtime. Provision private environment-scoped configuration with `r5dinfra`.
 
 ```sh
-r5d-worker start --label macos
-r5d-worker start --label macos --root /Volumes/r5d
-r5d-worker --version
+r5d-worker executor /absolute/private/executor-config.json
+r5d-worker manager /absolute/private/manager-config.json
 ```
 
-Authorize the exact worker label before starting it:
-
-```sh
-r5dctl auth login --worker-label macos
-```
-
-The worker uses that label-bound credential from the existing `r5dctl` config file or `R5D_WORKER_TOKEN`. `R5D_API_KEY` remains an accepted legacy environment-variable name, but its value must still be the exact label-bound worker credential; a general API key or device credential cannot connect a worker.
-
-Worker-managed data has one configurable root. Pass it with `--root`, set `R5D_ROOT`, or use the default `~/.r5d`. The worker creates a fixed layout beneath it:
-
-```text
-$R5D_ROOT/
-├── projects/<namespace>/<project>/<branch-name>
-├── sync/
-├── artifacts/<session-id>/
-└── plans/
-```
-
-Agent commands receive `R5D_ROOT` and derive those same four directories from it.
-
-Web shells and agent shell commands receive a server-issued `r5dctl` credential automatically. The credential is scoped to the signed-in user and revoked when the shell or command finishes, so every `r5dctl` command can use the user's account without a separate login on the worker host. Worker-specific process and session operations remain bound to the worker that received the credential.
-
-Commands, streaming commands, and PTYs never inherit the token or API key that bootstrapped the worker. Only the server-issued per-run `r5dctl` credential and the currently committed GitHub credential generation are added explicitly. A process-lifetime SQLite/OS file lock rejects a second worker credential authority under the same OS account and releases automatically after a crash. Keep the worker's credential/config home on one host; sharing or copying that home is unsupported.
-
-On direct macOS and Linux workers, a changed credential generation is published only after a proved reboot of that same machine. Linux containers expose the host kernel's boot ID, so restarting a container is not enough. Direct Windows credential rotation is currently unsupported and fails closed; use the verified systemd service path or reprovision a clean worker host for a changed generation.
-
-When the user has signed in with GitHub, web shells and agent commands also receive that OAuth credential through `GH_TOKEN`. GitHub CLI commands such as `gh pr`, `gh issue`, and `gh workflow` therefore use the signed-in user's permissions without a separate `gh auth login` on the worker host. Signing in again refreshes the granted OAuth scopes for subsequently started commands and shells.
-
-Project folders are the user/agent workbench. The primary branch is an ordinary clone and every sibling branch is a linked Git worktree, so branches share objects and refs and can cherry-pick or merge each other's commits directly. Connected projects keep GitHub as `origin`; greenfield projects use the r5d project repository. HTTP credentials are supplied through a worker-managed credential helper and are never written into synchronized files.
-
-A `create_project_branch` message cuts a new linked worktree from the source branch's current commit and carries a required `workingTree`: `carry` also materializes the source checkout's Git-visible working state, uncommitted changes included, while `clean` populates the new worktree from that commit alone. The worker advertises the option through the `projectBranchWorkingTreeModeV1` capability; a server refuses a `clean` request for a worker without it, because such a worker would carry instead. The result reports the base commit to the server only, which never forwards it to agents: a hash is stale as soon as the source commits again, so agents read branch state with git in the branch folder.
-
-The hidden clone at `$R5D_ROOT/sync/workspace` synchronizes working trees through ordinary Git: after five quiet seconds (or a process boundary), the worker commits mounted project and plan trees, rebases onto `origin/main`, and pushes. It retries push races, blocks oversized diffs for confirmation, and snapshots both heads when a rebase conflicts. A 60-second cycle catches out-of-band edits. Inner `.git` data is always excluded. After the outer workspace tree is reachable, changed project HEADs are force-pushed by explicit URL to the hidden per-project mirror; this tree-first ordering ensures a newly connected worker never observes a head newer than its synchronized tree.
-
-Every finished agent command asks the worker for a synchronization, and eight concurrent sessions can ask faster than one cycle runs. Ordinary requests therefore share cycles: requests that arrive while a cycle is queued join it, requests that arrive while one is running form the next one, and every request receives its own result carrying the shared outcome. A request for a project checkout that no recorded mutation touched since the last completed cycle is answered from that cycle without running one, and a cycle skips copying checkouts whose recorded mutation token is unchanged. Large-diff confirmations, canonical resets, and remediation cycles never share. Branch creation and deletion use their own lane in the workspace mutation gate: they wait only for a running cycle, never behind queued ones, and the worker sends `operation_queued` with the number of operations ahead as soon as the request is received.
-
-Branch names managed by r5d use lowercase letters, numbers, internal hyphens, and slash-separated segments, for example `ft/esm-support`. They may contain at most 45 characters.
-
-Releases that change the worker protocol are explicitly documented as breaking server/worker cutovers. For those releases, run the release-specific preflight and backfill against the production database, stop and upgrade workers to the required version, deploy the matching server, and then reconnect workers. Older workers are rejected before WebSocket upgrade rather than receiving incompatible workspace configuration messages. Protocol-compatible releases use the ordinary worker update flow.
-
-Worker labels are mandatory and unique per user. Choose labels that describe host capabilities, such as `macos`, `linux`, `ios`, or `ec2-build`.
-
-`r5d-worker start` keeps a lightweight supervisor process attached to the launching terminal or service. When both r5d CLIs are updated from User Settings, the connected runtime verifies the installed versions, exits with a reload signal, and the supervisor reconnects using the new worker package. Updates only run while the worker has no active commands or shells.
-
-Before every new agent generation (including subagents, queued work that starts a new generation, and resumed sessions), the server requires the connected runtime to be at least the worker release offered in User Settings. This is the server's `packages/VERSION.txt` release, or its configured `R5D_WORKER_PACKAGE_*` override; admission does not query the npm registry. Missing or invalid runtime versions also block starts. The error includes the running and required versions plus the exact update command. Update in User Settings, or install the packages on the worker host and restart `r5d-worker`: a newer package on disk does not update an already connected process. From 0.0.116 onward, a runtime keeps its startup version across reconnections even if the package on disk changes. Existing agent generations are allowed to finish, and connected workers remain available for updates and synchronization. Protocol cutover checks still apply separately when connecting. Publish the matching packages before deploying a server that requires their new version.
-
-The supervisor also reconnects automatically after server rollouts and transient network failures. A brief bounded delay prevents a tight retry loop while the server is unavailable. Pressing Ctrl+C still stops the worker, and agent-managed processes retain their existing in-process recovery path while disconnected. In-process reconnects retain initialized project configurations alongside those processes, so an unchanged checkout can reconnect while a dev server is running. Changed layouts and checkouts that need initialization still wait for active commands to finish.
-
-The runtime opens its control connection before recovering interrupted project snapshots. During recovery and initial project configuration it remains connected but non-dispatchable, reports its current phase plus branch/byte progress to the server, and prints the same progress locally. Recovery runs in a credential-sanitized helper process so the control loop can continue answering heartbeats. A durable `restoring` transaction state permits same-filesystem snapshots to be restored with one atomic directory move; cross-filesystem layouts retain the copy-and-fsync fallback.
-
-Both sides use monotonic, two-stage heartbeat recovery. The server sends pings, grants bounded leases to synchronous workspace and command-preparation work, and requires a fresh missed probe window before force-evicting a stale socket. The worker answers pings and uses a deliberately slower backup watchdog only for a half-open connection; reconnect delays are jittered across workers. A delayed watchdog sweep renews the probe instead of disconnecting, so synchronous local work or a stalled server event loop cannot turn one overdue timer callback into a mass disconnect.
-
-Credential-generation restart fencing protects against stale or accidentally detached descendants. It is not a hostile same-UID sandbox: code running as the worker's OS user can read or tamper with that user's config and auth files, install a persistent user service, or return after reboot. Run untrusted agents in a disposable VM that is reset at the boundary, or use a separately privileged credential broker/service account. When rotating the worker's own local `r5dctl` credential, stop the worker and reboot/reset the host before writing the replacement credential so an old same-UID descendant cannot read the new config.
-
-One-click updates use the current user's global npm prefix and never invoke `sudo`. If that prefix is not writable, User Settings provides the exact command to run manually.
-
-The agent runs commands through the virtual shell command:
-
-```sh
-worker exec macos docker compose up -d
-worker exec macos bun test
-```
-
-Agent shell commands receive no stdin by default: prompts read immediate EOF instead of hanging. A command started with `interactive: true` is spawned with a writable stdin pipe, and the agent's `shell_write` tool delivers input through the `exec_stdin` protocol message. The worker acknowledges each write with an `operation_result` carrying the delivered byte count, closes stdin on an explicit `eof`, on cancellation, on timeout, and at process exit, and advertises this support through the `execStdinV1` capability in its hello message. Servers refuse interactive runs and stdin writes for workers without the capability, so this is a protocol-compatible release that uses the ordinary worker update flow. Delivered stdin is audited server-side in the run's `process-runs/<runId>/stdin.log`.
-
-### Optional command launcher
-
-By default the worker launches commands and terminals directly on every platform. It imposes no memory limit, concurrency limit, or OS setup requirement. The operating system may terminate a command or the worker itself under memory pressure; a killed process alone is not evidence of an OOM. Inline RPC output is limited to 8 MiB per stream to bound worker-side buffering; use streaming execution for larger output.
-
-Operators may set `R5D_WORKER_COMMAND_LAUNCHER` to a JSON argv array, such as `["node", "/opt/worker/launcher.mjs", "/etc/worker/policy.json"]`. The worker starts this trusted executable once after acquiring credential authority and keeps it alive across websocket reconnects. Configuration is read from the worker's environment, never from command message environments, and the controller inherits only basic non-secret host environment fields. Arguments are passed literally without shell splitting.
-
-The launcher owns admission, OS isolation, budgets, and diagnostic evidence. Its JSONL protocol uses `{requestId, method, ...fields}` requests and `{requestId, result}` or `{requestId, error}` replies:
-
-- `initialize` returns `{}` once ready; failure prevents command admission. A launcher that bounds concurrency may return `{capacity: {generalSlots, utilitySlots, controlSlots, controlRuntimeMs, queueTimeoutMs}}` so the worker can report lane totals.
-- `acquire` receives `{id, kind, workspaceEffect?, commandClass?, sessionId?}` and returns `{argvPrefix: string[]}`. The worker prepends this argv to the command or terminal shell without interpreting it. `commandClass: "control"` is sent only for an `exec_start` whose argv is one plain `r5dctl` coordination command (validated against the worker's own allowlist, spawned without a shell, resolved from the worker's own `PATH`, with code-loading environment variables removed, and stopped by the worker after `controlRuntimeMs`); a launcher may give such commands a small reserved lane.
-- `status` returns `{capacity, lanes: {general|utility|control: {slots, active: [{id, sessionId?, since}], queued: [...]}}}`; optional, for operator inspection.
-- `cancel` receives `{id}` and irreversibly revokes queued or acquired work. `release` receives `{id}` and acknowledges only after cleanup. Both must be idempotent, including release before a delayed acquisition response.
-- `diagnose` receives `{id}` and returns `{message?: string}` with launcher-specific evidence. The worker does not infer a memory failure from an exit signal.
-
-Requests must be processed concurrently so cancellation and cleanup cannot wait behind queued admission. Controller RPCs are bounded (10 seconds, or 90 seconds for acquisition); external policy must reject excessive queue waits within that bound. Controller loss or protocol failure stops command admission, preserves uncertain outcomes for recovery, reaps ordinary children, and restarts the runtime through its supervisor. It never falls back to direct spawning. Shutdown closes controller stdin; the controller must reap its jobs before exiting.
-
-Cancellation is checked again immediately before spawn. A `cancel` carrying `scope: "unstarted"` is the server giving up on a start whose budget expired: it revokes only a launch that has not spawned (capacity queue, mount hold, preparation) and leaves a running process alone; `cancel_result.outcome` reports `unstarted`, `started`, `stopped`, or `unknown` (no record of the run; the cancellation is remembered so a later arrival is refused). Transient disconnects preserve commands and terminals; expiry of the five-minute execution lease cancels agent work and closes terminals. File operations, communication recovery, and cancellation do not enter launcher admission. Internal worker maintenance subprocesses are also outside this hook. The worker reports its own view of every lane (holders and queue, by run id) to the server with `capacity_report` whenever an admission changes; the platform exposes it through `r5dctl ps list` and `r5dctl workspace status`. Deployment-specific limits and service protection are documented in [Worker deployment resources](../../docs/worker-deployment-resources.md).
-
-When the connected `r5d-browser` requests a port forward, the worker opens each relayed connection only to `127.0.0.1` on the requested worker port. Browser-side and worker-side ports may differ. The worker never opens a public listener, and a disconnected worker leaves the browser's long-lived mapping unavailable until the same worker label reconnects.
-
-Control execution requires an initialized launcher that explicitly declares its control capacity (or direct execution without an external launcher), an updated worker, and r5dctl installed on the worker's own PATH. Missing control support is an update error; a control request never falls back to a general shell. Deploy the app and worker support assets, update the CLI/worker, and reconnect before resuming paused work.
-
-## Uploading files to the signed-in browser
-
-`browser_upload_files` transfers regular files from this worker to the connected r5d-browser and attaches them to the selected file input in one agent operation. Source paths may be anywhere this worker can read, including outside the project; relative paths resolve from the session working directory. `$R5D_ROOT`, `$R5D_SESSION_ID`, and `~/` are expanded without executing a shell. File reads are bounded to 1 MiB per RPC, and source metadata is checked throughout the transfer. These transient reads and binary responses bypass recovery journals. Uploads interrupted by a disconnect must be retried as a new operation.
+The executor retains processes and durable receipts independently of application releases. The manager authenticates the approved workspace keeper and retains old adapters until their delivery receipts are settled. Configuration and host roots belong exclusively to one installation. Never share an executor's state directory, credentials or workspace root between environments.

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.137",
+  "version": "0.0.138",
   "type": "commonjs"
 }