feat(sessions): isolate parallel sessions from each other's working tree

[adolfousier]

Problem

Parallel sessions (multiple TUI panes, or an agent working alongside another) all operate on the same working tree. Two sessions editing the same file clobber each other, with no arbitration.

Live evidence: two concurrent sessions modified src/channels/telegram/agent.rs and src/channels/voice/voicebox_stt.rs in the same tree within seconds of each other, uncommitted edits racing. A third session had to avoid both files by hand for the rest of the day to stay out of the way.

State of the code, verified

The original text of this issue said worktree isolation "exists and works, wired only to sub-agents", citing WorktreeManager::create_worktree at src/agents/subagent.rs:192. That is not the case, and the work is larger than wiring:

• No WorktreeManager exists. Zero references to it anywhere in src/. No create_worktree. No src/agents/subagent.rs.
• The only occurrences of the word "worktree" in the codebase are two doc comments in src/utils/git_branch.rs explaining that .git may be a file rather than a directory.
• Sub-agents are not isolated either. src/brain/tools/subagent/spawn.rs:235 calls .with_working_directory(context.working_dir()), so a child inherits the parent's directory.

What DOES exist, and why it is not enough

AgentService::working_dir_handle_for_session (src/brain/agent/service/builder.rs:763) gives each session its own Arc<RwLock<PathBuf>>, seeded from the global working directory. That is #703: a cd in one session cannot move another session's cwd.

It isolates which directory a session is pointed at, not the files themselves. Two sessions pointed at the same path still write to the same bytes on disk. This is the answer to the open question the previous text left unresolved.

Scope

Building isolation from scratch, not wiring an existing component. Design decisions that need answering before implementation:

• Lifecycle. When is a worktree created, and what happens to uncommitted work when a session ends? Discarding it silently is unacceptable; keeping it forever leaks disk.
• Opt-in or default. Two panes on the same branch are sometimes deliberate collaboration. Isolating every session by default breaks that workflow, so this likely needs to be a choice rather than automatic.
• Cost. A worktree per session means a checkout per session. On a repo with a multi-GB target/, that matters, and cargo cannot share a build cache across worktrees without extra configuration.
• Merging back. A session that produced good work in its own lane needs a path to land it. Without one, isolation converts a clobbering problem into a stranded-work problem.

Acceptance criteria

• Two concurrent sessions can edit the same logical file without clobbering each other
• Uncommitted work in a session's lane is never silently discarded
• Worktrees are pruned on session end, with no orphans after a crash
• Sessions that should share a tree still can
• Disk and build-cache cost is measured, not assumed

Note

The failure this issue describes is real and reproducible. Only the diagnosis was wrong: it is absence of a feature, not a broken connection to an existing one. Anyone starting from the previous text would have gone looking for code that is not there.

[adolfousier]

Audited against current code. Every absence claim in the issue text still holds, and the audit turned up three things that change how this should be approached.

Verified

Claim	Result
No WorktreeManager, no create_worktree	0 references in src/
No src/agents/subagent.rs	src/agents/ does not exist
"worktree" appears only in doc comments	2 occurrences, both src/utils/git_branch.rs (lines 4, 46)
Sub-agents inherit the parent's directory	subagent/spawn.rs:257 — .with_working_directory(context.working_dir())

working_dir_handle_for_session is at builder.rs:821 and does what the issue says: per-session Arc<RwLock<PathBuf>>, seeded from the global working directory (#703, 68f52039). It isolates which directory a session points at, not the bytes on disk.

1. The cost, measured

The issue lists "disk and build-cache cost is measured, not assumed" as acceptance. For this repo:

.git                    176M
target                   52G
tracked files            19M   (1,224 files)
total                    53G

git worktree checks out tracked files only — 19MB — and shares .git with the primary. So a worktree per session costs ~19MB, not 53GB. The 52GB is target/, gitignored and not copied.

The real cost is the opposite shape to the issue's phrasing: a new worktree starts with no target/, so the first cargo build in each lane is a full cold rebuild — minutes of CPU and tens of GB per session. Mitigable by pointing CARGO_TARGET_DIR at a shared path, at the price of serialising builds on cargo's lock. That is the number to decide on.

2. The problem is concurrent agents, not parallel sessions

Framing this as session isolation understates it. Every one of these builds its own AgentService pointed at the same working directory:

Site	Writer
cli/ui.rs:1005	TUI agent
cli/ui.rs:413	daemon agent
channels/factory.rs:144	every channel agent — Telegram, Discord, Slack, WhatsApp each get one
tui/app/state.rs:1590	provider-swap rebuild
subagent/spawn.rs:257	every spawned sub-agent
subagent/resume.rs:210	every resumed sub-agent
subagent/team/create.rs:234	every team member

team_create exists to "spawn multiple sub-agents at once… as one atomic team", each inheriting the parent's directory, and agent.max_concurrent defaults to 4. Four writers in one tree is the default configuration before anyone opens a second pane.

3. Worktrees do not fit the main case

A sub-agent or team member is supposed to be working in the parent's tree on the parent's task. Giving each its own worktree does not isolate them usefully — it strands N half-finished lanes of one job with no merge path, which is the "stranded work" failure the issue already anticipates.

Worktrees fit independent sessions well. They fit teams and sub-agents badly. That distinction is worth settling before any implementation, because it decides whether this is opt-in per session or automatic.

The reported pain is now addressed separately

The concrete failure in this issue — "two concurrent sessions modified agent.rs and voicebox_stt.rs within seconds of each other, uncommitted edits racing" — was a lost update in write_file, and is fixed in #954 (529ec20f).

write_file never read the file; it replaced it wholesale with content composed from a read in an earlier tool call, so anything written in between was destroyed silently. It now records what a session last saw and refuses a whole-file write when the file has moved, telling the agent to re-read. edit_file was never affected — it re-reads inside the call.

That needed no checkout, no lifecycle, no merge-back and no opt-in, and it covers every writer in the table above.

What that leaves for this issue

#954 stops edits being lost. It does not give sessions independent lanes — two agents still contend for the same files, they just find out about it now instead of discovering it later in a diff.

So this issue is still real, but its justification changes: it is no longer "we are losing work", it is "we want genuinely parallel workstreams". That is a feature decision rather than a bug fix, and the four open design questions in the issue text (lifecycle, opt-in, cost, merge-back) all still need answering — merge-back most of all, since without it isolation converts clobbering into stranding.

One precedent that did not exist when this was written: b22d18fc added agent.plan_isolated_execution — a master switch, default off, routing execution through a resolve_task_execution decision table with an explicit isolated request path. That is the codebase already answering "opt-in or default" for the analogous choice, and worth mirroring.

Leaving open — nothing here is a reason to close it.

[adolfousier]

Fixed on #1151

#1151