# 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`.

## Split projects
Code worktrees come from `wf start <id> --worktree <path> --branch <b>` run in the private project: it creates them in the
code repo (`code_root`) and writes `.wf-home` there. Inside such a worktree wf resolves the private project via `.wf-home`.