TmuxBackend: teammate spawn permanently fails after tmux topology change (process-level state corruption)

Bug: TmuxBackend teammate spawn permanently fails with "Could not determine pane count for current window"

Related: #24261, #24385, #23615

Summary

After spawning 5+ teammates successfully in a single team session, all subsequent teammate spawns from the same leader process fail permanently with:

Could not determine pane count for current window

A different Claude Code process can spawn into the same team without error. The failure is process-level state corruption in TmuxBackend, not a tmux or team configuration issue.

Environment

• Claude Code v2.1.63
• macOS Darwin 24.6.0 (arm64)
• tmux 3.6a (standard mode, not iTerm2 -CC)

Reproduction

1. Start Claude Code inside tmux, create a team, spawn 5+ teammates — succeeds
2. Kill a concurrent tmux session (e.g., stale session from a prior run)
3. Attempt to spawn a new teammate from the same leader process — fails permanently
4. Launch a separate Claude Code process and spawn into the same team — succeeds

Step 4 confirms the team config and tmux state are fine. The corruption is process-internal.

Isolation Tests

All tests run against the same team (athena-debug-2026-03-03) and tmux session:

| # | Test | Process | team_name | Result |
|---|------|---------|-----------|--------|
| 1 | Agent tool, standalone | Process B | none | PASS |
| 2 | Agent tool, existing team | Leader (Process A) | athena-debug | FAIL — "pane count" |
| 3 | Agent tool, same team | Process B | athena-debug | PASS |
| 4 | Agent tool, fresh team | Process B | spawn-test | PASS |
| 5 | 8 retries varying params | Leader (Process A) | athena-debug | FAIL — all identical |

Conclusion: The bug is process-specific. The leader's TmuxBackend instance has corrupted state that persists for the process lifetime. The team, tmux session, and agent type are all irrelevant — a different process succeeds on the identical team.

Diagnosis

tmux commands work from the affected process

The leader's Bash tool executes all three commands the spawn mechanism needs:

$ echo $TMUX_PANE
%61                              # ✓

$ tmux display-message -p "#{session_name}:#{window_index}"
athena-team-2026-03-03:1         # ✓

$ tmux list-panes -t "athena-team-2026-03-03:1" -F "#{pane_id}"
%61                              # ✓
%62

Process environment is valid: TMUX_PANE=%61, TMUX=.../default,6129,11 (session $11 = athena-team-2026-03-03).

Source analysis (v2.1.63 binary)

getCurrentWindowTarget() caches its result in a module-scoped variable (GPR in the bundle). This cache never invalidates:

async getCurrentWindowTarget() {
  if (GPR) return GPR;           // Returns cached value unconditionally
  // ...
  return GPR = A.stdout.trim();  // Set once, never cleared
}

The spawn call chain:

Agent tool → createTeammatePaneWithLeader(name, color)
  → getCurrentPaneId()            // reads process.env.TMUX_PANE
  → getCurrentWindowTarget()      // cached or resolved via tmux
  → getCurrentWindowPaneCount()   // tmux list-panes → FAILS
  → throws "Could not determine pane count for current window"

Since the Bash tool runs the same tmux commands successfully from the same process, the divergence is between TmuxBackend's internal exec path and the shell's exec path. The module-scoped cache (GPR) is the most likely candidate — it may hold a value that was valid at first spawn but became stale after the tmux topology changed.

Impact

• Severity: High — permanently blocks teammate spawns from the leader process
• Recovery: Restart the leader (loses all accumulated context)
• Trigger: Observed after killing a concurrent tmux session, but likely any tmux topology change after GPR is cached
• Long-running multi-agent sessions are disproportionately affected

Suggested Fix

Option A — Remove the cache. tmux display-message completes in <1ms. The performance benefit is negligible relative to the cost of spawning an agent.

Option B — Invalidate on failure. Clear GPR when getCurrentWindowPaneCount returns null and retry once.

Workaround

Launch a separate Claude Code process and spawn into the team:

claude --agent <name> --model sonnet

This works but the agent can't join the team (no --team CLI flag), so SendMessage coordination is unavailable.

Additional Context

• The team leader's tmuxPaneId in the config is always "" (empty). Manually setting it did not resolve the issue.
• Distinct from #24261 (iTerm2 -CC mode, cross-lifecycle). Same error, different environment, but the process-specific nature suggests a shared root cause in TmuxBackend state management.