Linked-team teamRoot: the FAQ's ../team-repo/.squad form makes squad loop report "No squad found" #2107
Description
What happens
The FAQ ("squad doctor complains about absolute path for teamRoot") recommends pointing teamRoot at the team's .squad directory itself:
{ "teamRoot": "../team-repo/.squad" }With that config, squad loop exits with ✗ No squad found — run 'squad init' first. The same team linked as "teamRoot": "../team-repo" works.
Repro (dev 29e69f5; the same code ships in v0.13.0 and v0.13.1)
team-repo/.squad/team.md
project/.squad/config.json { "version": 1, "teamRoot": "../team-repo/.squad" }
cd project
squad loop # ✗ No squad found (exit 1)
# with teamRoot "../team-repo":
squad loop # 💤 No loop.md found ... (exit 0, team resolved)
Why
The CLI, the coordinator and the docs don't agree on what teamRoot points at:
| Where | Expects teamRoot to be |
|---|---|
CLI effectiveSquadDir() (08ceca6, #1877), used by loop/watch/health |
the parent of .squad/; reads {teamRoot}/.squad/team.md |
squad link, and init personal-squad linking |
the parent of .squad/ (link refuses a target without .squad/) |
Coordinator (squad.agent.md, Remote/satellite mode) |
either; {teamRoot}/.squad/team.md, or {teamRoot}/team.md "if teamRoot already points inside .squad/" |
FAQ, and guide/personal-squad.md (shows agents/ directly under the team dir) |
the .squad directory itself |
So a team linked the way the FAQ shows works in a Copilot session but not under squad loop.
Suggested fix
Either:
- Make the CLI match the coordinator: in
effectiveSquadDir(), use{teamRoot}/.squadwhen it exists, otherwise{teamRoot}when it holdsteam.md; or - Pick the parent-of-
.squadform as canonical: fix the FAQ and personal-squad docs, and drop the coordinator fallback (maybe with asquad doctorcheck that flags ateamRootending in.squad).
(1) is the smaller change and keeps existing links working.
Activity
cherie-q commentedon Sep 29, 2026
One more data point: this is a conflict inside the CLI itself, not only between the CLI and the docs. In v0.13.1 (
b448cd3),squad state-mcpandsquad loopread the sameteamRootin two different ways:squad state-mcp→createStateMcpToolRegistry()(state-mcp.ts:72) →new ToolRegistry(paths.teamDir){teamRoot}/decisions/inbox,{teamRoot}/agents/<name>/history.md,{teamRoot}/<key>(tools/index.ts:490, 595, 660)squad loop/watch→effectiveSquadDir()(effective-squad-dir.ts:55){teamRoot}/.squad/team.mdSo for a linked team:
teamRoot→ the.squaddir (the FAQ form):squad_statetools work,squad loopsays "No squad found".teamRoot→ the parent of.squad(thesquad linkform):squad loopworks, butsquad_statereads and writes{parent}/decisions/inboxetc., outside.squad/.No single value works for both. Option (1) above would fix
loopwithout changingsquad_state. Option (2) would also needToolRegistryto appendpaths.namein remote mode.fix(sdk,cli): resolve linked team state for both teamRoot forms
fix(sdk,cli): resolve linked team state for both teamRoot forms
fix(sdk,cli): resolve linked team state for both teamRoot forms (gith…
fix(doctor): preserve legacy stray casting/policy.json detection in l…
fix(state): transactional governed-memory migration and source-branch…