iTerm2 backend: split pane fails when referenced session is closed (no fallback)

Resolved 💬 2 comments Opened Mar 3, 2026 by iamchadarmstrong Closed Mar 3, 2026

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

  1. Start a team with iTerm2 pane backend
  2. Spawn multiple teammates over several iterations (e.g., 4-5 rounds of agents)
  3. Observe that dead agent panes accumulate — eventually 15+ tiny panes on the right side of the screen, each too small to read
  4. Close any one of the dead panes in iTerm2
  5. 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

  1. Try multiple sessions: Iterate through known session IDs (both in-memory and from team config) until finding one that's alive
  2. Validate before splitting: Check if the target session exists before attempting the split (e.g., it2 session list or similar)
  3. Fall back to active session: If all known sessions are dead, use ["session", "split"] (no -s flag) 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 tmux alias

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗