How the Swarm-Forge Cleanup Window Shutdown Sequence Works

The cleanup window shutdown sequence is orchestrated by 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 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. 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

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

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

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

Code Implementation Examples

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

Stopping the hand-off daemon (fallback implementation):

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:

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:

# 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 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 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 defines a common interface, while concrete implementations like 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 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.

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