diff options
Diffstat (limited to 'docs/multi-session.md')
| -rw-r--r-- | docs/multi-session.md | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/docs/multi-session.md b/docs/multi-session.md new file mode 100644 index 0000000..628aad9 --- /dev/null +++ b/docs/multi-session.md @@ -0,0 +1,46 @@ +# Multi-session: several sessions in one project + +Approved 2026-10-04. Problem: one work tree + `master` shared by sessions → a commit sweeps the +other's edits (`git add -A`), half-done code breaks the other's tests, two sessions of a lane pick +the same task. + +## 1. Claims +- `wf status ID progress …` writes `.wf/claims/ID.json` (who: socket, pid, lane, model); details in + `lanes.md` §4. `wf next` skips a task claimed by another live session. +- A second live session of a lane: `wf next` warns on its first line; the registry keeps the first one. + +- Task line `Sessions: solo` → picked only while no other session is live; while it is in progress + (claimed) every other session's `wf next` picks nothing (exit 1, names the holder); its `wf done` + prints `notify <lane> uds:…: solo <id> done, run wf next` for each other live session. + `Sessions: owner` → picked only by `wf next --owner` (owner present). + +## 2. Worktree mode (only while > 1 session is live, git projects) +- `wf next` prints `===== Multi-session =====`: from the main tree + `git worktree add .worktrees/<lane> -b <lane>/<task> master` (or `cd .worktrees/<lane> && git switch -c <lane>/<task> master` + when it exists), `&& wf setup` appended when workflow.toml has `worktree_setup`; inside a worktree a + reminder of where you are. +- `wf setup` (in a worktree) runs `worktree_setup` (cwd = worktree, env `WF_MAIN` = main tree): links / + copies git-ignored inputs (`out/…`). Idempotent; run after every worktree create/reuse. +- wf run inside a linked git worktree uses the main tree's project (same relative folder, when it + has `workflow.toml`): TASKS.md, archive, docs, `.wf/` are the main tree's. Bookkeeping never + conflicts; branches never touch TASKS.md. `wf check` there checks the main tree. +- One session alone: as before, on `master`. + +## 3. Done in worktree mode +`wf done` run inside a linked worktree prints, after verify/checklist: commit code (explicit paths), then +`wf merge`. `wf merge` (under the project lock, `.wf/lock`): worktree must be clean → `git rebase master` +(conflict → abort, branch untouched: rebase by hand, resolve, verify, `wf merge` again) → `merge --ff-only` +into the main tree → commit TASKS.md + archive there (`<id> done`, id from the branch `<lane>/<id>`) → +detach the worktree, delete the branch → push home if the remote exists (`--no-push` skips). +The ff-merge of one's own task branch is a standing owner permission (shared CLAUDE.md); never other branches. +`wf finish <id> -m ENTRY [--commit MSG PATH…]` does it in one call (workers): refuses first if files outside +PATHS are uncommitted or quick_gate is red (task stays open) → `wf done` → commit PATHS → `wf merge`. In a main tree +(no worktree) TASKS.md + archive join that commit and nothing is merged. Verify runs before it (`wf ctx` prints it). +Next task: new branch from master in the same worktree. + +## 3a. Project lock +Every wf write command and `wf merge` run under an exclusive flock on `.wf/lock` (main tree), so parallel +sessions/workers never lose a TASKS.md edit or race a merge-back. + +## 4. Commits +Shared rule: stage explicit paths, never `git add -A` / `git commit -a`. |