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

> Learn how SwarmForge handles terminal adapter failures and missing window IDs using capability flags and a watchdog script to automatically reopen windows and preserve tmux sessions.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/none.sh)), which attaches the cleanup tmux session directly in your current shell instead of opening a new window.

```bash

# 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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.

```bash

# 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:

```bash

# 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:

```bash

# 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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/terminal-app.sh)), the [`swarm-window-watchdog.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/terminal-app.sh) adapter returns `0` from this function, enabling full window lifecycle monitoring and automatic recovery through the watchdog script.