fix(spawn): require the resolved task worktree to belong to the project

[jonathan-edgar]

What this fixes

fm-spawn.sh discovers a task's worktree by sending treehouse get to the new pane, then polling the pane's foreground cwd. It accepted the first path that merely differed from the project directory.

oh-my-zsh.sh runs builtin cd -q "$ZSH" on every shell startup to stamp the zcompdump revision. It is unconditional. So a freshly spawned pane transiently reports ~/.oh-my-zsh, the poll accepted it, and the agent launched in the user's shell framework directory with --dangerously-skip-permissions. This happened five times before it was diagnosed.

validate_spawn_worktree did not catch it either, because it asked the wrong question.

What the guard used to test, and what it now tests

Before	Is this a git repo whose root is itself, and which is not the primary checkout?
After	Does this share the project's --git-common-dir?

~/.oh-my-zsh satisfies the old rule completely: it is a git repo, its root is itself, and it is not the primary checkout. The old rule tested isolation from the primary when what it needed to test was identity with the project.

Every linked worktree of the project reports the project's --git-common-dir; an unrelated repository reports its own. That is the property that actually identifies a task worktree.

Enforced in two places:

1. The discovery poll - an impostor cwd is waited out rather than latched onto.
2. validate_spawn_worktree - a backstop that refuses the launch. This is the only enforcement on the Orca path, which has no poll.

The predicate fails open when the project's common dir cannot be read, so a git failure cannot make a spawn unlaunchable. That case now warns on stderr naming the cause rather than degrading silently.

Also

• FM_SPAWN_WORKTREE_TIMEOUT (default 60, unchanged behaviour) bounds the poll; the give-up error names the last cwd seen, which would have shown ~/.oh-my-zsh on the first bad launch rather than the fifth.
• docs/orca-backend.md records as a known unknown that real Orca's worktree shape is not smoke-proven, with the exact probe to settle it.

Tests

Extended tests/fm-tangle-guard.test.sh and tests/fm-backend-orca.test.sh rather than adding a runner. Covered: a genuine worktree accepted; a different repository rejected; a non-git path rejected; the primary checkout still rejected by the isolation rule; the fail-open branch; and the live shape where the pane sits in the foreign repo before landing in the real worktree.

Each new case was proven to fail against the unfixed script - unfixed, the foreign-repo spawn exits 0 and launches there.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 info

• ⚠️ bin/fm-spawn.sh:681 - The common-dir guard fails open silently. When git rev-parse --path-format=absolute --git-common-dir on the project returns nothing (git older than 2.31, where --path-format is unsupported, or any other rev-parse failure), PROJ_GIT_COMMON is empty and is_project_worktree returns success for every candidate at bin/fm-spawn.sh:681, so both the discovery poll and the validate_spawn_worktree backstop revert to the exact pre-fix rule that launched five agents into ~/.oh-my-zsh with --dangerously-skip-permissions. The fail-open itself is the author's deliberate, stated choice and should stay, but nothing anywhere - not stderr, not the spawn summary line, not the recorded meta - reveals that the guard is inert, and the crewmate brief's own isolation assertion (bin/fm-brief.sh:237) does not catch a foreign repo either, since the agent's toplevel does equal the directory it was launched in. Emit one stderr notice when PROJ_GIT_COMMON is empty (still launching), so an operator on an old git sees the guard is off instead of rediscovering it through another bad launch.
• ℹ️ bin/fm-spawn.sh:861 - FM_SPAWN_WORKTREE_TIMEOUT is documented only in the script header, but docs/configuration.md keeps an otherwise exhaustive tunables reference where every comparable knob is listed with a default and a one-line purpose (FM_CHECK_TIMEOUT, FM_CREW_STATE_NM_TIMEOUT, FM_ARM_CONFIRM_TIMEOUT, FM_FLEET_SYNC_BOOTSTRAP_TIMEOUT at docs/configuration.md:242-263). Since the intent describes this as an operator-facing knob for shortening the wait while debugging a spawn, an operator scanning that list will not find it. One line in that block would close the gap; this is additive to the existing list, not a new doc or a second owner of the contract.

🔧 Fix: report disabled worktree-identity check; document spawn timeout
3 infos still open:

• ℹ️ bin/fm-spawn.sh:668 - The new spawn-time warning names only one cause. PROJ_GIT_COMMON comes back empty for ANY failure of git -C "$PROJ_ABS" rev-parse --path-format=absolute --git-common-dir, not just an old git: I verified a non-git project directory produces the same empty result (fatal: not a git repository), and git's safe.directory dubious-ownership refusal does too. In those cases the operator is told "needs git 2.31+ for rev-parse --path-format", which points at the wrong thing while the identity guard is silently off. Since the message exists purely for diagnosis - the incident's whole cost was five bad launches before anyone knew where to look - broaden it to state the observed fact and list the plausible causes, e.g. "...could not determine the git common dir of <path> (the directory may not be a git repo, git may have refused it, or git may predate 2.31's rev-parse --path-format)". No behavior change; the fail-open stays exactly as the intent requires.
• ℹ️ bin/fm-spawn.sh:667 - The fail-open branch is the one branch of the new guard with no test. The change covers a genuine worktree (accepted), a different repository (rejected), a non-git path (rejected), the primary-checkout subdir (rejected by the isolation rule), and the transient-then-real sequence - but not the case where PROJ_GIT_COMMON is empty, which is precisely the state in which the original oh-my-zsh incident becomes reachable again. It is hermetically testable with the fixtures already in tests/fm-tangle-guard.test.sh: shadow git on the fakebin PATH with a stub that fails rev-parse --path-format (or hand run_spawn a project directory that is not a git repo), point FM_FAKE_PANE_PATH at the foreign repo, and assert both halves of the deliberate contract - the warning text reaches stderr AND the spawn still proceeds (exit 0, meta recorded) rather than aborting. That pins the fail-open as intended behavior so a later hardening pass cannot silently flip it, and pins the warning so it cannot be dropped.
• ℹ️ bin/fm-spawn.sh:723 - The new backstop adds a precondition to the Orca path that is not covered by any recorded Orca smoke evidence. validate_spawn_worktree now requires the Orca-provided path to share the project's --git-common-dir, and for backend=orca this predicate is the only enforcement (there is no poll). That holds if orca worktree create --repo id:<repo> produces a linked git worktree of the registered repo; if Orca instead provisions from its own clone or mirror, every Orca spawn would now refuse with "NOT a worktree of". docs/orca-backend.md's verified-facts section records the smoke-proven shapes for repo registration, worktree creation, and terminal handles, but says nothing about the worktree's git identity relative to the registered repo, and Orca is not installed here so I could not check it. The test that covers this asserts the refusal, not the acceptance, so it would pass either way. Worth one git -C <orca worktree> rev-parse --path-format=absolute --git-common-dir against a real Orca worktree, with the result added to that doc's verified list - Orca is experimental, so this is not merge-blocking.

🔧 Fix: broaden common-dir warning, test fail-open, record Orca assumption
1 info still open:

• ℹ️ docs/orca-backend.md:112 - The new known-unknown record ends with a claim its own file contradicts three lines later. Line 112 states "The existing fake-Orca test asserts the refusal rather than the acceptance, so it passes either way", but test_spawn_writes_orca_metadata_and_launches_harness (tests/fm-backend-orca.test.sh:531) builds a genuine linked worktree via fm_git_worktree "$proj" "$wt" - which shares the project's --git-common-dir - feeds that path as Orca's result.worktree.path, and asserts exit 0 plus worktree=$wt in meta. That is the acceptance path of exactly this check, and the doc's own "Fake-Orca tests cover" list at line 118 names it ("fm-spawn.sh --backend orca metadata creation and harness launch"). The genuine gap is different and narrower: every fake-Orca worktree is hand-built with git worktree add, so the suite proves the predicate accepts a linked worktree but cannot prove real Orca provisions one. Since this paragraph exists specifically to be accurate about what is and is not proven, the closing sentence should say that instead - e.g. "The fake-Orca tests feed a hand-built linked worktree, so they pin the predicate's accept and refuse behaviour but cannot confirm the shape real Orca provisions." This sentence was prescribed verbatim in the round-2 instructions (carried over from my own round-2 wording, which was itself inaccurate), so it is flagged rather than corrected silently. No code change; the recorded probe, the fallback plan, and the guard itself are all correct.

🔧 Fix: correct Orca doc claim about fake-Orca test coverage
1 info still open:

• ℹ️ bin/fm-spawn.sh:726 - The identity probe git -C <dir> rev-parse --path-format=absolute --git-common-dir is now written out three times in this file (line 660 for the project, line 694 inside is_project_worktree, and line 726 inside the refusal message), and the third is a second, independent read of the same candidate rather than a reuse of what the predicate just resolved. Nothing is functionally wrong today - both reads are the same command against the same path - but the refusal message prints a value it re-derived instead of the value the decision was actually made on, and three literal copies of a fiddly flag string can drift apart silently (a future edit to the flags in one place would leave the guard checking one thing and reporting another). Simplest fix: have is_project_worktree stash the candidate's resolved common dir in a script-level variable (e.g. CANDIDATE_GIT_COMMON) and print that in the error, collapsing three invocations to two. Non-functional, no behaviour change, and it leaves the fail-open and the warning exactly as the intent requires.

⚠️ **Test** - 1 warning

• 🚨 tests failed with exit code 1
• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"

🔧 Fix: no code change; tmux precondition met, targeted tests green
1 warning still open:

• ⚠️ docs/orca-backend.md:107 - The new identity check fails closed on the Orca backend path, but there is no evidence that real Orca's orca worktree create --repo id:<repo> yields a linked worktree sharing the project's --git-common-dir. The fake-Orca test pins the predicate's accept/refuse behaviour but cannot confirm the shape real Orca provisions, and no Orca runtime is available here to probe it. If Orca provisions from its own clone or mirror, every real Orca spawn would now be refused at validate_spawn_worktree. This is already recorded in docs/orca-backend.md as a known unknown; it is surfaced here only because it is the one acceptance criterion I could not produce evidence for. Settling it needs one probe on a real Orca worktree: git -C <orca worktree> rev-parse --path-format=absolute --git-common-dir compared against the same command in the project directory.
• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• bash tests/fm-tangle-guard.test.sh - 7 cases pass, including the new test_spawn_rejects_foreign_repo_cwd and test_spawn_fail_open_when_common_dir_unknown
• bash tests/fm-backend-orca.test.sh - 51 cases pass, including the new test_spawn_refuses_orca_foreign_repo_worktree
• Fail-before-fix: copied bin/+tests/ to a scratch tree, replaced bin/fm-spawn.sh with git show 0b9406d:bin/fm-spawn.sh, and ran both suites there - the foreign-repo spawn exits 0 (launches into the impostor) and the Orca backstop case gets past validation into the foreign repo
• Manual end-to-end repro repro-ohmyzsh-spawn.sh: fake tmux replays pane cwd ~/.oh-my-zsh, ~/.oh-my-zsh, <real worktree>; compared recorded worktree= in state/<id>.meta before vs after the fix
• Manual end-to-end repro repro-ohmyzsh-stuck.sh: pane never leaves the impostor; asserted exit 1, no meta recorded, and the give-up error naming the last pane cwd
• Manual repro repro-failopen.sh: shimmed git to reject rev-parse --path-format (pre-2.31 behaviour) and confirmed the spawn still launches while warning that the worktree-identity check is disabled
• Flakiness check: bash tests/fm-tangle-guard.test.sh run 3x consecutively, all exit 0
• git status --porcelain - worktree left clean, all evidence written outside it

🔧 **Document** - 1 issue found → auto-fixed ✅

• ℹ️ docs/zellij-backend.md:209 - docs/zellij-backend.md:209 is a past-tense E2E verification record stating that a pane which never left the project directory refused to launch with "did not yield an isolated worktree" via "the 60-second poll's own comparison". After this change that same shape no longer reaches validate_spawn_worktree: the discovery poll rejects the unmoved cwd and gives up with "did not enter a worktree of <project> within Ns" instead. I deliberately left it unchanged because it is a dated record of what actually happened during that run, not a statement of current behaviour, and rewriting verification history is worse than the residual hazard. The risk if left: a reader debugging a similar symptom looks for the isolation error and does not find it. If you would rather it not mislead, the minimal fix is a trailing clause noting which guard reports this case today.

🔧 Fix: note current guard for superseded zellij E2E record
✅ Re-checked - no issues remain.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.