docs: worker git workflow — daemon worktree + config parity + worker-opened PR
Worktree is code-only isolation; SessionManager hydrates it to full config parity (overlay untracked local settings/.mcp.json/.env) so a worker is a full peer of the primary, differing only in the LLM provider. Worker commits, pushes over SSH, and opens its own PR (gitea REST + repo-scoped token).
This commit is contained in:
Dai Ha
@@ -0,0 +1,182 @@
|
||||
# Worker Git Workflow — worktree · branch · PR
|
||||
|
||||
**Status:** design (defining the fleet's working model). Builds on the
|
||||
[CB-301 session manager](CB-301-Session-Manager.md) and the one-shot/no-reuse decision.
|
||||
|
||||
## Guiding principle — a worker is a full peer of the primary
|
||||
|
||||
The whole point of the bridge is **the same Claude Code agent running against a different LLM
|
||||
provider**. A worker must be **functionally identical to the primary in context and knowledge** —
|
||||
same project + user `CLAUDE.md`, same skills, same memory, same MCP tools, **same local/private
|
||||
settings** — and differ **only** in `ANTHROPIC_BASE_URL`/`ANTHROPIC_MODEL`. The worktree exists
|
||||
*solely* for git isolation (a branchable checkout for commits + code reference). It must **never**
|
||||
strip the worker of the configuration a main-tree session has. **Config parity is a hard
|
||||
requirement, not a nice-to-have.**
|
||||
|
||||
## Decisions
|
||||
|
||||
- **One-shot, no reuse** (CB-301) — each task gets a fresh worker, torn down after. The **PR is the
|
||||
durable artifact**; no context is carried across workers.
|
||||
- **Worktree provisioned by the daemon** — `SessionManager` creates a dedicated git worktree +
|
||||
branch per session, **hydrates it to full config parity** (below), and tears it down on release.
|
||||
- **Worker opens its own PR** — the worker commits, pushes its branch, and opens the PR/MR itself,
|
||||
returning the PR URL in its `bridge_reply`.
|
||||
|
||||
## Why worktrees (the hazard being fixed)
|
||||
|
||||
Today every bridge worker inherits the **primary's own working tree** as its cwd
|
||||
(`WorkerService` cwd resolution → caller cwd). A single worker editing at a time is safe, but two
|
||||
**parallel implementers** would stomp each other's files. A worktree per session gives each worker
|
||||
an isolated checkout on its own branch — the precondition for fanning out implementation work.
|
||||
|
||||
## Config parity — the worktree is code-only; it must NOT strip the worker
|
||||
|
||||
**The trap:** `git worktree add` creates a checkout of **tracked files only**. Untracked / gitignored
|
||||
files do **not** come along. So a worker moved from the primary's main tree into a bare worktree
|
||||
**silently loses** exactly the local/private configuration that makes it a full peer — while the
|
||||
shared-tree it runs in *today* gives it all of this for free. Moving to worktrees must **preserve**
|
||||
that, not regress it.
|
||||
|
||||
Classify every source of "what a main session knows", by whether a worktree keeps it:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph keeps["Inherited automatically — no action"]
|
||||
A["User-global config<br/>~/.claude/CLAUDE.md, ~/.ccs memory"]:::ok
|
||||
B["Tracked project config<br/>CLAUDE.md, committed .claude/skills, committed .mcp.json"]:::ok
|
||||
C["CLAUDE_CONFIG_DIR<br/>(daemon already injects per profile)"]:::ok
|
||||
D["Bridge MCP<br/>(injected via --mcp-config launch flag)"]:::ok
|
||||
end
|
||||
subgraph gap["LOST by a bare worktree — must be hydrated"]
|
||||
E["settings.local.json<br/>local .claude/* overrides"]:::warn
|
||||
F["local .mcp.json mods<br/>(the M .mcp.json in git status)"]:::warn
|
||||
G[".env / .envrc / direnv<br/>local secrets + tokens"]:::warn
|
||||
H["any other gitignored local config"]:::warn
|
||||
end
|
||||
keeps --> R["Worker = full peer of primary"]:::goal
|
||||
gap -->|"overlay step at provision"| R
|
||||
classDef ok fill:#2f855a,stroke:#22543d,color:#ffffff;
|
||||
classDef warn fill:#b7791f,stroke:#7b341e,color:#ffffff;
|
||||
classDef goal fill:#2b6cb0,stroke:#2a4365,color:#ffffff;
|
||||
```
|
||||
|
||||
*Green is inherited by path (home dir / `CLAUDE_CONFIG_DIR`) or lives in tracked files that the
|
||||
worktree checks out anyway. Amber is the real gap — untracked local config the worktree drops.*
|
||||
|
||||
**Mechanism — worktree hydration (part of `SessionManager.acquire`, after `git worktree add`):**
|
||||
|
||||
1. **Inherit by path, don't copy** — keep the worker's `$HOME`, `CLAUDE_CONFIG_DIR`, and memory dir
|
||||
identical to the primary's. Everything home-scoped (user `CLAUDE.md`, memory, auth, global
|
||||
skills) is already parity for free; only *cwd-relative* project-local files are the gap.
|
||||
2. **Overlay the untracked project-local set** from the primary tree into the worktree — a defined,
|
||||
configurable list: `settings.local.json` (+ any local `.claude/*`), the locally-modified
|
||||
`.mcp.json`, `.env`/`.envrc`, and any other gitignored config the primary depends on. **Symlink**
|
||||
(read-only parity, stays live, nothing to go stale) rather than copy where possible; copy only
|
||||
what a worker may write.
|
||||
3. **Never overlay the git plumbing** — the worktree's own `.git` file/branch is what gives
|
||||
isolation; that's the *one* thing that must differ from the main tree.
|
||||
|
||||
The overlay set lives in config (`BridgedConfig.Worker.parityOverlay` — a list of repo-relative
|
||||
paths, with sane defaults) so it's auditable and per-repo tunable.
|
||||
|
||||
> **Trust note (deliberate).** Hydrating local config means the primary's local secrets/tokens
|
||||
> (`.env`, `.mcp.json` auth, gitea token) become visible to an **off-subscription** worker running
|
||||
> against a third-party model endpoint. That is the accepted consequence of "workers must be full
|
||||
> peers" — but it is a real trust expansion over a worker that only sees tracked code. Keep the
|
||||
> overlay list **explicit and minimal**; don't blanket-symlink the whole tree. `.mcp.json` and
|
||||
> `wiki/` remain **excluded from all worker commits** regardless of being present for reference.
|
||||
|
||||
## Lifecycle
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant P as Primary
|
||||
participant SM as SessionManager (daemon)
|
||||
participant G as git / gitea
|
||||
participant W as Worker
|
||||
|
||||
P->>SM: acquire(ticket, profile)
|
||||
SM->>G: git worktree add wt -b worker/ticket-nonce main
|
||||
SM->>SM: overlay parity config into wt
|
||||
SM->>W: spawn (cwd = wt, on its branch)
|
||||
Note over W: implement in the isolated worktree
|
||||
W->>G: git commit + git push (SSH, same user)
|
||||
W->>G: open PR (branch to main)
|
||||
W-->>P: bridge_reply (prUrl, branch, summary, tests)
|
||||
P->>SM: release(paneId)
|
||||
SM->>G: git worktree remove wt
|
||||
Note over G: branch + PR persist for review/merge
|
||||
P->>G: review PR, merge on green
|
||||
```
|
||||
|
||||
*The worker's "checkpoint" (CB-302) is exactly steps 6–8: commit → push → open PR. This replaces the
|
||||
earlier `STATE.md` idea — a PR is reviewable, mergeable, and self-describing.*
|
||||
|
||||
## Infra facts (verified this session)
|
||||
|
||||
- **Remote:** `ssh://git@git.ltms.dev:2224/lms/claude-bridge.git` (gitea). Push is over **SSH** —
|
||||
a worker running as the same user with the same keys can `git push` **with no extra credential**.
|
||||
- **gitea is NOT in the project `.mcp.json`** (only `jetbrains`, `intellij-index`, `bridged`). The
|
||||
primary's gitea MCP comes from a global/user config, so **workers do not inherit it**. A worker
|
||||
gets only the `bridge` MCP mounted (via `--mcp-config` launch flag).
|
||||
- **No gitea CLI** (`tea`) installed; `glab` is present but is the GitLab CLI (wrong backend).
|
||||
|
||||
**Implication:** `git push` is free for workers; only **PR creation** needs a new mechanism.
|
||||
|
||||
## Open decision — how the worker creates the PR
|
||||
|
||||
| Option | Mechanism | Trade-off |
|
||||
|---|---|---|
|
||||
| **A. gitea REST + token** | Worker `curl`s `POST /api/v1/repos/lms/claude-bridge/pulls` with a scoped token injected by the daemon into the worker env | Minimal, no new server; token lives in the off-subscription worker's env (scope it tightly) |
|
||||
| **B. mount gitea MCP into workers** | Add the gitea MCP to the worker's `--mcp-config` alongside `bridge` | Clean tool call, but the gitea MCP's own auth/token must be provisioned per worker; more moving parts |
|
||||
| **C. install `tea` CLI** | Worker runs `tea pr create` with a token | Another dependency to install + configure; same token question as A |
|
||||
|
||||
**Recommendation: A (gitea REST + a repo-scoped token).** Smallest surface, reuses SSH for push,
|
||||
and the token is a single scoped secret the daemon injects like it already injects
|
||||
`ANTHROPIC_AUTH_TOKEN`. The implementer skill wraps the `curl` in one documented step.
|
||||
|
||||
### Trust / token scope (the real cost of "worker opens its own PR")
|
||||
|
||||
- Off-subscription workers already *could* push (SSH, same user). The **incremental grant is
|
||||
PR-create**, i.e. a gitea API token.
|
||||
- Scope the token **minimally**: the `lms/claude-bridge` repo, `write:repository` (create branch +
|
||||
PR), **not** merge/admin/org. A leaked token can open PRs, not merge them — the primary/human is
|
||||
still the merge gate.
|
||||
- Inject via the daemon (env var, e.g. `GITEA_TOKEN`), never written to the worker's config dir —
|
||||
same non-invasive pattern as the ANTHROPIC token. Guard is unaffected (it concerns
|
||||
`ANTHROPIC_BASE_URL`, not git).
|
||||
|
||||
## Implementation plan
|
||||
|
||||
| Piece | Where | Notes |
|
||||
|---|---|---|
|
||||
| Worktree provision/teardown | **CB-301 ext** — `SessionManager.acquire`/`release`; `WorkerSession` gains `worktree`, `branch` | daemon shells out to `git worktree add/remove` |
|
||||
| **Config-parity overlay** | **CB-301 ext** — `SessionManager.acquire`, after `git worktree add` | symlink/copy the `parityOverlay` set into the worktree so the worker is a full peer; **this is what makes worktrees viable, not a dead-end** |
|
||||
| Overlay config | `BridgedConfig.Worker.parityOverlay` — repo-relative paths, sane defaults | auditable, per-repo tunable; keep explicit + minimal (trust) |
|
||||
| Branch naming | `worker/<ticket-slug>-<nonce>` off `main` (or a configured base) | one branch per session |
|
||||
| Commit + push + PR handoff | **CB-302** — worker-driven, guided by the skill | push = SSH; PR = option A |
|
||||
| Implementer skill | `.claude/skills/implementer/SKILL.md` | worktree-aware playbook (see below); mounts automatically since workers inherit repo cwd |
|
||||
| gitea token injection | `WorkerService` env + `BridgedConfig` | repo-scoped, minimal perms |
|
||||
| PR review + merge | Primary (has gitea MCP + judgment) | merge on green; the human/primary gate stays |
|
||||
|
||||
## Implementer skill (outline)
|
||||
|
||||
A worker-facing playbook (sibling to the existing `reviewer` skill):
|
||||
|
||||
1. **You are in a git worktree on a dedicated branch** — check `git status`/`git branch`; do all
|
||||
work here, never on `main`.
|
||||
2. **Implement the task**; keep commits focused and message them clearly.
|
||||
3. **Push** your branch (`git push -u origin HEAD`).
|
||||
4. **Open a PR** to `main` (option A `curl`, or the decided mechanism) with a title/body describing
|
||||
the change and referencing the ticket.
|
||||
5. **Reply** via `bridge_reply` with the **PR URL**, branch name, files changed, and test names —
|
||||
that reply is the whole handoff.
|
||||
6. Do **not** merge; do **not** touch `.mcp.json` or `wiki/`.
|
||||
|
||||
## Sequencing
|
||||
|
||||
1. Finish + verify **CB-301 core** (in flight) — registry/FSM.
|
||||
2. Extend CB-301 with **worktree provisioning** (this doc) once the PR mechanism is chosen.
|
||||
3. Add the **implementer skill** + **token injection**.
|
||||
4. **CB-302** = wire the worker checkpoint (commit/push/PR) as the release-time handoff.
|
||||
Reference in New Issue
Block a user