@ricsam/r5d-worker 0.0.100 → 0.0.103

package/README.md

@@ -4,6 +4,7 @@
 
 ```sh
 r5d-worker start --label macos
+r5d-worker start --label macos --root /Volumes/r5d
 r5d-worker --version
 ```
 
@@ -13,12 +14,20 @@ Authorize the exact worker label before starting it:
 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. Project checkouts are managed under:
+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/projects/<namespace>/<project>/<branch-name>
+$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.
@@ -29,7 +38,11 @@ When the user has signed in with GitHub, web shells and agent commands also rece
 
 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.
 
-The hidden clone at `~/.r5d/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.
+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.