docs(templates): warn before parallel background spawns in a shared worktree#1484
Merged
bradygaster merged 1 commit intoJul 19, 2026
Conversation
…orktree A real incident (bradygaster#1014): two background agents on one worktree, agent B's commit workflow ran a global git stash and swept agent A's three untracked files. Git doesn't complain — the files just vanish, and only the in-session context remembers they existed. This is the issue's Option A, warn-only: the Parallel Fan-Out section of the coordinator template now tells the coordinator to check worktree mode before spawning 2+ background agents in one turn and show the user a one-shot warning when isolation is off. Once per session, proceed after warning — a caution, not a gate. No behavior change, no auto-isolation (that's Option B, a possible follow-up). Also drops the worktree reference's claim that shared-worktree concurrency is safe when agents modify different files — untracked files were never covered by that safety argument. The issue's sample warning referenced a SQUAD_WORKTREES env var that doesn't exist in the codebase; the added text points at the real mechanism (worktree mode via Pre-Spawn: Worktree Setup) instead. Fixes bradygaster#1014 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
🟠 Impact Analysis — PR #1484Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affectedci-workflows (1 file)
root (3 files)
squad-cli (2 files)
squad-sdk (2 files)
templates (2 files)
tests (1 file)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ✅ | Single commit | 1 commit — clean history |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | No Copilot review threads |
| ❌ | CI passing | 6 check(s) still running |
Files Changed (11 files, +129 −4)
| File | +/− |
|---|---|
.changeset/fix-1014-parallel-spawn-warning.md |
+6 −0 |
.github/agents/squad.agent.md |
+11 −0 |
.squad-templates/squad.agent.md |
+11 −0 |
.squad-templates/worktree-reference.md |
+1 −1 |
packages/squad-cli/templates/squad.agent.md.template |
+11 −0 |
packages/squad-cli/templates/worktree-reference.md |
+1 −1 |
packages/squad-sdk/templates/squad.agent.md.template |
+11 −0 |
packages/squad-sdk/templates/worktree-reference.md |
+1 −1 |
templates/squad.agent.md.template |
+11 −0 |
templates/worktree-reference.md |
+1 −1 |
test/ci/parallel-spawn-warning.test.ts |
+64 −0 |
Total: +129 −4
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The coordinator template's Parallel Fan-Out section now includes a shared-worktree guard: before spawning 2+ background agents in one turn without worktree mode, the coordinator shows the user a one-shot warning about the git race, then proceeds. Warn-only — no behavior change, no auto-isolation.
Why
Closes #1014
The issue documents a real incident: two background agents on one worktree, agent B's commit workflow ran a global
git stash, and agent A's three untracked files vanished mid-session. Git doesn't error — only the in-session context remembers the files existed. The failure is probabilistic (fires only when one stream has untracked files at the exact moment another runs stash/clean/restore), so teams parallelize happily until it bites, then lose trust in parallelism entirely.This ships the issue author's own Option A. Option B (auto-enable worktree isolation at N≥2 spawns) stays a follow-up — it changes spawn behavior and costs coordination overhead, which deserves its own discussion.
One correction against the issue text: the sample warning there references
SQUAD_WORKTREES=1/worktrees: true, but no such flag exists in the codebase — worktree isolation is governance-driven (worktree mode via the Pre-Spawn: Worktree Setup section and worktree-reference.md). The added warning points at the real mechanism instead of inventing a config surface.How
.squad-templates/squad.agent.md(canonical): a**Shared-worktree guard.**block at the end of the Parallel Fan-Out MUST-list — check worktree mode, warn once per session when off, proceed after warning ("a caution, not a gate"). Warning text names the exact failure (stash/clean/restore eating another agent's untracked files)..squad-templates/worktree-reference.md: the "multiple agents can work in the same worktree concurrently if they modify different files" line now carries the untracked-files caveat — that safety claim never covered untracked files, which is exactly what the incident hit.node scripts/sync-templates.mjs --syncto all governed copies:.github/agents/squad.agent.md,templates/,packages/squad-cli/templates/,packages/squad-sdk/templates/(5 agent.md copies, 4 worktree-reference copies — byte-identical,test/template-sync.test.tsparity passes).Testing
test/ci/parallel-spawn-warning.test.ts(4 tests, same structural pattern astest/ci/datetime-template.test.ts): guard present inside the Parallel Fan-Out section specifically, stash/clean/restore named, the worktree-reference caveat present, and all governed copies carrying the guard.npx vitest run test/ci/parallel-spawn-warning.test.ts test/template-sync.test.ts— 253 passed..squad-templates/*.mdchanges call for an E2E template session on top of unit tests. Copilot CLI isn't available in this environment, so that run hasn't happened — flagging honestly rather than claiming it. The change is purely additive guidance text (no spawn-template variables, no conditional blocks touched), so the structural tests cover what's mechanically checkable; happy to run the E2E matrix on a machine with copilot if wanted before merge.git diffvsgit diff -widentical; the sync script's known CRLF churn on unrelated workflow-wiring files was reverted before commit — the diff is 11 files, +129/−4, all of it the guard, the caveat, the test, and the changeset..changeset/fix-1014-parallel-spawn-warning.md(patch, both packages — governed template paths ship in both)PR Readiness Checklist
Branch & Commit
devdevBuild & Test
npm run build— N/A for template text, passes regardlessnpm run lintpassesnpm run lint:eslint— 0 errors on the new test fileChangeset
Docs
Exports
Breaking Changes
None. Warn-only; shared-worktree mode keeps working exactly as before.
Waivers
E2E template session not run in this environment (no copilot CLI) — see Testing.