# How the Swarm-Forge Cleanup Window Shutdown Sequence Works

> Discover how the swarm-forge cleanup window shutdown sequence works. Learn how swarm-cleanup.sh gracefully terminates daemons, kills sessions, and closes terminals.

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

---

**The cleanup window shutdown sequence is orchestrated by [`swarm-cleanup.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm-cleanup.sh), which gracefully terminates the hand-off daemon, kills tmux sessions, and closes terminal windows via backend-specific adapters.**

The `unclebob/swarm-forge` repository provides a scripted framework for managing persistent terminal workflows across macOS. When a window completes its task, the **cleanup window shutdown sequence** ensures that background processes, tmux sessions, and UI resources are reclaimed in a specific order to prevent resource leaks. This sequence is implemented primarily in [`swarmforge/scripts/swarm-cleanup.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-cleanup.sh) and delegates window management to adapter scripts.

## Load the Terminal Backend

The script begins by determining which terminal backend to use—defaulting to `terminal-app`—and sourcing the generic adapter code from [`swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm-terminal-adapter.sh). It calls `load_terminal_backend` to import backend-specific functions such as `terminal_close_window`, which abstracts how the actual terminal window is closed.

Source: [swarm-cleanup.sh#L11-L23](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-cleanup.sh#L11-L23)

## Stop the Hand-Off Daemon

The next step halts the background hand-off daemon through a prioritized two-tier approach:

- **Babashka path**: If the `bb` command is available, the script executes `stop_handoff_daemon.bb` to gracefully terminate the daemon process.
- **Fallback path**: If Babashka is unavailable, the script reads the PID from `.swarmforge/daemon/handoffd.pid` and sends `SIGTERM` directly to that process, then removes the stale PID file.

This dual approach ensures the daemon stops cleanly regardless of which tooling is installed on the host system.

Source: [swarm-cleanup.sh#L24-L35](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-cleanup.sh#L24-L35)

## Terminate Tmux Sessions

For each session name passed as a command-line argument, the script executes `tmux -S "$TMUX_SOCKET" kill-session -t "$session"`. Errors are suppressed using `|| true` so the sequence continues even if a session was already destroyed. A `sleep 1` follows to allow the system to release file descriptors and process handles before proceeding to UI teardown.

Source: [swarm-cleanup.sh#L37-L42](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-cleanup.sh#L37-L42)

## Close the Terminal Window

Finally, if a window IDs file exists, the script iterates through each ID and invokes `terminal_close_window`. For the default `terminal-app` backend, this function runs an AppleScript that locates the Terminal window by its numeric ID and closes it without prompting to save changes, ensuring the UI disappears immediately.

Source: [terminal-app.sh#L58-L71](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/terminal-app.sh#L58-L71)

## Code Implementation Examples

The following snippets demonstrate the key mechanics of the shutdown sequence.

**Stopping the hand-off daemon (fallback implementation):**

```bash
DAEMON_PID_FILE="$WORKING_DIR/.swarmforge/daemon/handoffd.pid"
if [[ -f "$DAEMON_PID_FILE" ]]; then
  daemon_pid="$(< "$DAEMON_PID_FILE")"
  kill -TERM "$daemon_pid" 2>/dev/null || true
  rm -f "$DAEMON_PID_FILE"
fi

```

**Closing a terminal window via AppleScript:**

```bash
terminal_close_window() {
  local window_id="$1"
  osascript - "$window_id" <<'APPLESCRIPT' >/dev/null 2>&1 || true
  on run argv
    set targetId to item 1 of argv as integer
    tell application "Terminal"
      try
        close (first window whose id is targetId) saving no
      end try
    end tell
  end run
  APPLESCRIPT
}

```

**Invoking the cleanup script:**

```bash

# Usage: swarm-cleanup.sh <tmux-socket> <window-ids-file> [session-names...]

swarm-cleanup.sh /tmp/tmux-12345 /tmp/window-ids.txt session-1 session-2

```

## Summary

- The **cleanup window shutdown sequence** is centralized in [`swarmforge/scripts/swarm-cleanup.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-cleanup.sh) within the `unclebob/swarm-forge` repository.
- It uses a **terminal backend adapter** pattern to abstract window management across different terminal applications.
- The script stops the **hand-off daemon** via Babashka when available, falling back to direct PID termination for compatibility.
- It force-closes **tmux sessions** while suppressing errors to handle already-closed sessions gracefully.
- Terminal windows are closed using **backend-specific logic**—for macOS Terminal, this means AppleScript executed via `osascript`.

## Frequently Asked Questions

### What triggers the cleanup window shutdown sequence?

The sequence is triggered when a Swarm-Forge window finishes its assigned task or when [`swarm-window-watchdog.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm-window-watchdog.sh) detects that a window has become idle or closed. The watchdog monitors process lifetimes and invokes the cleanup script to ensure resources are reclaimed promptly.

### Why does the script include a PID file fallback for daemon termination?

The PID file fallback ensures the cleanup works on systems where Babashka (`bb`) is not installed. By reading `.swarmforge/daemon/handoffd.pid` and sending `SIGTERM`, the script maintains cross-platform compatibility while still supporting the preferred graceful shutdown method when the Babashka helper is present.

### How does the terminal adapter pattern abstract window closing?

[`swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm-terminal-adapter.sh) defines a common interface, while concrete implementations like [`terminal-app.sh`](https://github.com/unclebob/swarm-forge/blob/main/terminal-app.sh) provide the actual `terminal_close_window` function. For macOS Terminal, this uses AppleScript; other backends could use escape sequences or CLI tools. This abstraction allows [`swarm-cleanup.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm-cleanup.sh) to close windows without hardcoding terminal-specific logic.

### Is it safe to run the cleanup script multiple times?

Yes. The script is designed to be idempotent. Tmux kill commands and daemon stop operations use `|| true` and redirect errors to `/dev/null`, allowing the sequence to complete successfully even if resources were already released in a previous run.