iTerm2 backend: split pane fails when referenced session is closed (no fallback)
Bug Description
When using the iTerm2 pane backend for teammate spawning, closing any previously-created teammate pane can permanently break the ability to spawn new teammates. The system picks a single session ID to split from and does not fall back to other available sessions.
Steps to Reproduce
- Start a team with iTerm2 pane backend
- Spawn multiple teammates over several iterations (e.g., 4-5 rounds of agents)
- Observe that dead agent panes accumulate — eventually 15+ tiny panes on the right side of the screen, each too small to read
- Close any one of the dead panes in iTerm2
- Attempt to spawn a new teammate
Result: Failed to create iTerm2 split pane: Error: Session '<UUID>' not found
Expected: The system should try other known session IDs or fall back to splitting from the active session.
Root Cause
The iTerm2 backend (ITermBackend) maintains an in-memory array (tN1) of created pane session IDs. When creating a new pane, it always uses tN1[tN1.length - 1] (the last entry).
When the team lead process restarts (e.g., after context compaction continuing a conversation), this in-memory array is lost. The system then reads tmuxPaneId values from the team config file (~/.claude/teams/<name>/config.json). If the referenced session has been closed by the user, the spawn fails with no recovery.
Relevant code path (minified):
let $ = tN1[tN1.length - 1];
if ($)
z = ["session", "split", "-s", $] // fails if this session was closed
else
z = ["session", "split"] // fallback exists but is never reached
Suggested Fix
- Try multiple sessions: Iterate through known session IDs (both in-memory and from team config) until finding one that's alive
- Validate before splitting: Check if the target session exists before attempting the split (e.g.,
it2 session listor similar) - Fall back to active session: If all known sessions are dead, use
["session", "split"](no-sflag) to split from the current active session
UX Impact
In long-running team sessions with multiple iterations, dead panes accumulate rapidly. With 15+ panes, each pane becomes 1-2 lines tall and completely unreadable. The user is forced to either:
- Never close any pane (impractical at scale)
- Delete and recreate the entire team (loses team context and config)
Environment
- Claude Code v2.1.63
- macOS Darwin 24.4.0
- iTerm2 with it2 CLI
--teammate-mode tmuxalias
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗