Repository navigation
Description
Summary
Squad documents git worktree isolation for parallel agents in several templates and skills, but no runtime code creates, leases, or cleans up a worktree. Every spawned agent runs in the same working tree with no lock or mutex. This appears to be a regression against #525 / #529, which were closed as implemented.
Evidence
The guidance is markdown only. Every git worktree add in the repo lives in a template or skill file handed to the model as a prompt:
packages/squad-sdk/templates/issue-lifecycle.md:136
packages/squad-cli/templates/issue-lifecycle.md:136
packages/squad-sdk/templates/worktree-reference.md:108-109
packages/squad-cli/templates/worktree-reference.md:108-109
packages/squad-sdk/templates/skills/git-workflow/SKILL.md:83-84
packages/squad-cli/templates/skills/git-workflow/SKILL.md:83-84
No source file creates one. In packages/**/src/, every worktree hit is either a comment or a detection helper for the case where Squad is already running inside one:
squad-cli/src/cli/core/detect-squad-dir.ts:47- detection fallbacksquad-cli/src/cli/core/init.ts:210-216- warns if a worktree is detectedsquad-cli/src/cli/commands/doctor.ts:548- resolves hooks path correctly under worktreessquad-sdk/src/resolution.ts:180,218,285-.git-file handling
packages/squad-sdk/src/platform/ralph-commands.ts - the file #529 targeted - contains no worktree reference at all.
Spawns share one directory. watch/agent-spawn.ts:190-200 passes a single cwd straight to spawn(), and every caller passes context.teamRoot. execute.ts:135 builds one prompt containing all eligible issues and execute.ts:103 instructs the agent to "spawn agents for ALL actionable issues simultaneously" - concurrent work, one tree.
There is no lease, lock file, or mutex guarding the tree. #1014 ("detect concurrent background spawns on a shared worktree ... real-world git-race incident observed") documents this failure mode occurring in practice.
Impact
- Concurrent agents run
git checkout/git commitagainst a shared index. Interleaving produces cross-contaminated branches, lost edits, and commits containing another agent's changes. - The failure is nondeterministic and only shows up under the parallelism the prompts actively encourage, which makes it hard to reproduce and easy to misattribute to the model.
- Isolation currently depends on the model choosing to follow markdown. That is a reasonable way to express preference, but not a way to enforce a safety invariant.
Proposal
Move isolation from prompt guidance into the spawn flow:
- When dispatching more than one work item concurrently, create
git worktree add <path> -b squad/<id>-<slug> <base>per item and set that path as the child'scwd. - Hold a lease file per worktree so a second process cannot claim the same item, and so crashed runs can be detected and reclaimed.
- Serialise any operation that must touch the shared tree behind a single mutex.
- Clean up on completion, with
git worktree prunerecovery for the crash case. - Fall back to sequential execution in the same tree when worktree creation is unavailable, rather than silently running parallel agents in one tree.
Keeping the markdown guidance is still useful for the in-iteration behaviour, but the invariant itself should hold whether or not the model reads it.
Activity
swigerb commentedon Sep 16, 2026
Confirming this is still present in v0.12.0, and adding one detail that I think sharpens the "isolation is markdown only" framing, plus a mitigation that works today.
The guidance can be absent entirely, not merely unenforced
watch/capabilities/execute.jsprefixes the watch agent's charter to every spawned session:loadAgentCharterthrows when.squad/agents/ralph/charter.mdis missing, and the catch is silent. A team that has never created that file getscharterPrefix = ''.That matters for this issue because it means the isolation guidance is not just unenforced, it can be entirely absent at runtime.
squad initdoes not appear to scaffold a charter for the watch agent, and the roster template lists Ralph with an em dash in the charter column rather than a path, so the gap is easy to have without noticing. There is no warning: the session simply starts with no standing instructions at all.So the current state is arguably a step below "depends on the model choosing to follow markdown". For anyone who has not hand-written that file, the model is not shown the markdown in the first place.
A one-line
debugLogin that catch, or adoctorcheck for a missing charter on the configured watch agent, would at least make it visible.Mitigation for anyone hitting this now
Writing
.squad/agents/<watch-agent>/charter.mdwith explicit worktree instructions does get honoured, because of the prefix above. Verified against v0.12.0:It is still instruction-level and inherits every limitation described in the issue, so it is a workaround rather than a fix. But it is a meaningfully better starting point than an empty prefix, and it costs one file.
Corroborating the failure mode
I hit exactly what #1014 describes, on a private repo, with
--max-concurrent 2. An agent wrote its changes into the shared team root rather than a worktree and left the integration branch with an uncommitted tree that did not compile against its own HEAD. The work itself was fine once recovered onto a branch, but it was close to being discarded as local debris, because nothing distinguishes an interrupted agent's output from someone's abandoned experiment.Worth noting the concurrency setting was my own error: the repo's config pinned
maxConcurrentto 1 and its notes explained why. The point is only that the guard rail is a comment in a config file, and raising a number silently removes it.On the proposal
Creating the worktree in the spawn flow and passing that path as the child
cwdlooks right to me. Two things I would add from the recovery side:swigerb commentedon Sep 16, 2026
Separate from the worktree question, but found while investigating it:
spawnAgentdiscards everything the agent says, which makes any spawn-side failure invisible.watch/agent-spawn.ts:execFile's callback is(error, stdout, stderr). Taking onlyerrthrows both streams away. When the child exits 0 having done nothing,success: truepropagates, the round reports normally, and there is no record anywhere of what the agent actually did.What that hid
A watch loop here was reporting a healthy round every 8 minutes:
Eligible, dispatched, exit 0, no error, no branch, no PR, nothing. Four rounds of that before I stopped assuming it was working.
I patched the callback locally to tee both streams to a file. The spawned session's complete output turned out to be:
It had read the prompt, spent 86 reasoning tokens, acknowledged it, and exited.
copilot -pis one-shot, so the instructions it was waiting for were never coming.The cause in my case was self-inflicted: I had written a charter for the watch agent, and
execute.tsprefixes it asYOUR CHARTER: ...followed byADDITIONAL CONTEXT: Ralph, Go! .... The model read the whole thing as a briefing. Removing the charter and re-running, the same round was still going at 170 seconds instead of returning at 13, which is the control.That is my problem to solve. The reportable bug is that it took a local patch to
node_modulesto discover it. Nothing in the logs, at any verbosity, distinguished "agent did the work" from "agent said hello and exited".Suggestion
Capture both streams and act on them:
Two cheap additions on top:
.squad/agent-output/per spawn makes a failed overnight run diagnosable the next morning instead of gone.Happy to open a PR for the callback change if useful.