How to Handle Terminal Adapter Failures or Missing Window IDs in SwarmForge

SwarmForge handles terminal adapter failures and missing window IDs through capability flags that detect adapter health and a watchdog script that automatically reopens vanished terminal windows while preserving tmux sessions.

SwarmForge launches each agent in its own tmux session and relies on a terminal adapter script to open a visible terminal surface. When adapters fail to initialize or window IDs become stale, the framework uses a defensive contract system to maintain agent continuity. Understanding how to handle terminal adapter failures or missing window IDs in SwarmForge ensures your agent swarm remains resilient across different terminal environments.

Understanding the Terminal Adapter Contract

Each adapter in swarmforge/scripts/terminal-adapters/ implements a minimal contract defining its capabilities. The framework queries these capabilities before attempting to open sessions or track window state.

The contract consists of four shell functions:

• terminal_backend_label() – Returns the display name of the adapter
• terminal_backend_can_open_sessions() – Returns 0 if the adapter can create new terminal windows, non-zero otherwise
• terminal_backend_tracks_windows() – Returns 0 only if the adapter can reliably verify window existence later
• terminal_open_session <session> <title> – Opens a terminal and attaches to the specified tmux session
• terminal_window_exists <id> – Verifies whether a previously opened window is still available

Detecting Adapter Capabilities at Runtime

SwarmForge checks capability flags during startup to determine how to manage terminal surfaces. This detection flow is documented in the Terminal Behavior section of the repository's README.md.

Session Opening Failures

When terminal_backend_can_open_sessions returns non-zero, SwarmForge assumes the adapter cannot create new windows. This occurs when required binaries like wt.exe (Windows Terminal) or osascript (macOS) are missing from $PATH.

In this scenario, SwarmForge automatically falls back to the none adapter (swarmforge/scripts/terminal-adapters/none.sh), which attaches the cleanup tmux session directly in your current shell instead of opening a new window.

# Force the fallback adapter explicitly

SWARMFORGE_TERMINAL=none ./swarm

Window Tracking Limitations

The terminal_backend_tracks_windows function determines whether SwarmForge can monitor terminal health. Adapters return 0 to enable tracking or 1 to disable it.

For example, swarmforge/scripts/terminal-adapters/windows-terminal.sh returns 1 because Windows Terminal cannot reliably return stable window IDs. Conversely, swarmforge/scripts/terminal-adapters/terminal-app.sh returns 0, enabling full window monitoring.

Recovering Missing Window IDs with the Watchdog

For adapters that support window tracking, SwarmForge launches swarmforge/scripts/swarm-window-watchdog.sh to monitor terminal survival.

The watchdog maintains a list of active window IDs and periodically invokes terminal_window_exists <id> for each entry. If the function returns non-zero (indicating the window was closed or crashed), the watchdog automatically calls terminal_open_session to recreate the terminal surface while preserving the original tmux session.

# Watchdog logic from swarm-window-watchdog.sh

while read -r win_id; do
  if ! terminal_window_exists "$win_id"; then
    echo "Window $win_id vanished – reopening..."
    terminal_open_session "$SESSION_FOR_WIN_$win_id" "Recovered $win_id"
  fi
done < "$WINDOW_TRACK_FILE"

This mechanism ensures that if a user manually closes a terminal tab, the agent's state persists in tmux and the UI automatically restores within seconds.

Implementing Custom Recovery Logic

You can extend adapter behavior to handle specific failure modes or add diagnostics.

Creating a Resilient Custom Adapter

Follow this template to implement adapters that report failures gracefully:

# my-adapter.sh

terminal_backend_label() { echo "MyAdapter"; }

terminal_backend_can_open_sessions() { 
  command -v myterm >/dev/null || return 1; 
}

terminal_backend_tracks_windows() { return 0; }

terminal_open_session() {
  local session="$1" title="$2"
  myterm --title "$title" --command "cd \"$WORKING_DIR\" && exec tmux -S \"$TMUX_SOCKET\" attach -t \"$session\""
}

terminal_window_exists() {
  myterm --list-windows | grep -q "$1"
}

Place this file in swarmforge/scripts/terminal-adapters/ and set SWARMFORGE_TERMINAL=my-adapter to activate it.

Debugging Adapter Failures

To diagnose why an adapter fails, check the return values of the capability functions:

# Test if the current adapter can open sessions

source swarmforge/scripts/terminal-adapters/windows-terminal.sh
if terminal_backend_can_open_sessions; then
  echo "Adapter functional"
else
  echo "Adapter cannot open sessions - check binary availability"
fi

Summary

• Capability flags (terminal_backend_can_open_sessions, terminal_backend_tracks_windows) allow SwarmForge to detect adapter limitations before attempting operations
• Automatic fallback to the none adapter occurs when session creation is impossible, ensuring the swarm continues running inline
• Window watchdog (swarm-window-watchdog.sh) monitors adapters that return 0 from terminal_backend_tracks_windows and automatically reopens missing terminals
• State preservation is guaranteed because tmux sessions persist independently of terminal windows, allowing seamless reattachment
• Custom adapters can implement diagnostic logging by extending the standard contract while maintaining return code semantics

Frequently Asked Questions

What happens if my terminal adapter binary is missing?

SwarmForge detects the missing binary through terminal_backend_can_open_sessions and automatically falls back to the none adapter. The cleanup tmux session attaches directly to your current shell instead of opening a new window. To resolve this, ensure the required binary (wt.exe, osascript, kitty, etc.) is available on your $PATH or explicitly specify a working adapter using SWARMFORGE_TERMINAL.

How does SwarmForge recover from manually closed terminal windows?

For adapters that support window tracking (like terminal-app.sh), the swarm-window-watchdog.sh script polls window IDs every few seconds using terminal_window_exists. When it detects a closed window (non-zero return), it invokes terminal_open_session to create a new terminal surface attached to the same persistent tmux session. Adapters that cannot track windows (like windows-terminal.sh) disable this watchdog and proceed without monitoring.

Can I write a custom terminal adapter for SwarmForge?

Yes. Create a shell script in swarmforge/scripts/terminal-adapters/ implementing the five required functions: terminal_backend_label, terminal_backend_can_open_sessions, terminal_backend_tracks_windows, terminal_open_session, and terminal_window_exists. Maintain the return code semantics (0 for success/capability present, non-zero for failure/absent) to ensure compatibility with the watchdog and fallback systems.

Why does the Windows Terminal adapter behave differently from Terminal.app?

The windows-terminal.sh adapter sets terminal_backend_tracks_windows to return 1 because Windows Terminal cannot reliably provide stable window IDs for later verification. This disables the watchdog mechanism, meaning SwarmForge cannot detect if Windows Terminal windows close unexpectedly. The terminal-app.sh adapter returns 0 from this function, enabling full window lifecycle monitoring and automatic recovery through the watchdog script.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}