Chapter 6 · Session Backends: tmux Reference Backend

Chapter goals: Understand the role of session backends (runtime backends) in the fleet system, master tmux installation, window topology, supervision操作, and liveness probing mechanisms as the verified reference backend.

6.1 What a Session Backend Is

Each crewmate is an autonomous agent process, and agent processes need a visible,observable, interruptible session endpoint. The session backend is the terminal infrastructure hosting these endpoints:

                    ┌─ backend = tmux   ──► tmux window   (reference impl)
firstmate dispatch ──┼─ backend = herdr  ──► herdr tab     (experimental)
                    ├─ backend = zellij ──► zellij tab    (experimental)
                    ├─ backend = orca   ──► Orca terminal (experimental, macOS)
                    └─ backend = cmux   ──► cmux workspace (experimental, macOS)

The backend determines three things: where任务端点lands, how the captain watches (observes), and how the firstmate dispatches指令 and reads state. Chapter 7 covers the four experimental backends; this chapter深耕 the reference — tmux.

6.2 Backend Selection Chain

FirstMate决定 the backend in this priority order:

1. config/backend file explicit指定        ← highest priority (local gitignored config)
2. FM_BACKEND=<name> env var               ← effective for this launch only
3. runtime auto-detection                  ← auto-detect (only部分 backends participate, see Ch 7)
4. tmux                                    ← hard default fallback

In other words: with nothingconfigured, tmux is the default answer. Conversely, writing tmux in config/backend or using FM_BACKEND=tmux alsoacts as the switch退出 Herdr/cmux auto-detection — very实用 in mixed environments.

# Method 1: persistent choice (write to local config, gitignored)
echo "tmux" > config/backend

# Method 2: one-time choice
FM_BACKEND=tmux claude

# Method 3: ask the firstmate in natural language
> Please use tmux as the session backend

6.3 Installation and Prerequisites

tmux本体 is one command:

brew install tmux          # macOS
# Or your platform's package manager, e.g. apt install tmux

Beyond tmux, the通用工具链 requirements (统一约定的 in configuration.md's toolchain section) alsoapply:

• A validated primary harness CLI: Claude Code, Grok, Pi (or pi-signed), Codex, OpenCode, Cursor Agent CLI — one of these;
• Git and GitHub CLI, authenticated via gh auth login;
• The selected backend's own dependencies (tmux itself in the tmux scenario).

One advantage of the tmux backend: zero provisioning steps — the official docs明确 "No provisioning is required before the first task." Install and跑.

6.4 Window Topology: Tasks Are Windows

The recommended experience with the tmux backend is to启动 the primary harness inside a tmux session:

tmux new -s firstmate     # Create and enter a session named firstmate
claude                     # Launch the primary harness inside it (or grok --trust / pi etc.)

Thereafter each crew task becomes a window in this session, named fm-<id>:

# List all current task windows in the fleet
tmux list-windows -t firstmate

# Sample output:
# 0: main*    1: fm-a1b2-   2: fm-c3d4

If the primary harness runs outside tmux — no problem. FirstMate自动创建 or复用 a detached session named firstmate:

tmux attach -t firstmate   # Attach anytime to observe the fleet

6.5 Supervising Without Attaching

Daily supervision does not require attaching to each window one by one. FirstMate provides两个轻量入口:

# Peek at a task's recent output (bounded tail, no screen flooding)
bin/fm-peek.sh <task-id>

# Dispatch a steer指令 to the task endpoint (requires explicit FM_HOME)
FM_HOME=<home> bin/fm-send.sh <task-id> 'Switch to plan B; keep existing tests'

Here's a红线呼应ing to Hard Rule 4: if you亲自 attach to a task window and type, that's an authoritative direct intervention —你的输入立即生效, but the firstmate reconciles this场外指挥 at the next supervision review. In日常, stick to fm-send.sh to keep通信 on the single-liaison model.

6.6 Agent Liveness Probe

"Window exists" ≠ "agent is alive." The tmux backend's liveness probe分两层:

Layer 1: target existence check — does the pane exist?
Layer 2: process name identity recognition — is the pane running a harness or a裸 shell?

Layer 2 is the key. The probe组合多个独立来源读取进程名: #{pane_current_command}, the pane tty foreground process group's kernel comm value, even the argv[0] installation path成分. Multiple sources交叉验证 because which field保留 the真实 executable name varies by平台.

Five判定 categories:

Verdict	Meaning	Triggers recovery?
alive	Recognized a known harness process (Claude/Codex/OpenCode/Pi/pi-signed/Grok/Kimi/Cursor/Muse)	No
dead	Foreground is just a普通 shell	✅ Yes
missing	Window definitively不存在	✅ Yes
unreadable	State unreadable	No
ambiguous	Otherunknown process	No

注意一个精妙的设计约束:只有 dead 和 missing 授权恢复. Because a误判的 "dead" could导致在同一个 worktree上再拉起一个重复 agent — far worse than missing a recovery. So no single source alone gives a negative verdict; the foreground process group must be readable且证据一致.

Another反直觉 detail: the probe限定 in the foreground process group not all descendant processes of the pane. This is deliberate — a残留的 harness同名进程 in the background should not make a actually idle pane读作 "agent alive."

6.7 Current Behavior and Limitations Summary

The official docs记录完整的回归测试入口 for the tmux backend, including冒烟测试, liveness probe测试, composer ghost文本测试 etc.:

tests/fm-backend-tmux-smoke.test.sh      # Backend smoke
tests/fm-tmux-agent-liveness.test.sh     # Liveness probe
tests/fm-composer-ghost.test.sh          # Composer judgment
tests/fm-tmux-submit-busy.test.sh        # Submit and busy state

Limitations and定位 to remember:

• tmux is the reference path and the only baseline fully supporting secondmate homes;
• Busy state does not guess from rendered text; it走 the semantic busy-state contract (bin/fm-busy-lib.sh);
• Dispatch确认采用严格标准: only a proven-empty composer counts as successful dispatch; ambiguous states一律保守处理, never重打文本.

6.8 Verification

Once everything is就绪, validate the full链路 with a最小任务: dispatch a small task and confirm its fm-<id> window appears in the expected session.

$ tmux list-windows -t firstmate
0: bash  1: fm-e5f6*

New window appears and bin/fm-peek.sh <id> can read the agent output — the tmux backend is working正常.

6.9 Chapter Summary

• Session backends决定 crewmate endpoints'位置与监督方式; tmux is the verified reference backend and hard default;
• Selection chain: config/backend explicit > FM_BACKEND one-time > auto-detect > tmux fallback; explicit tmux选择 also exits auto-detection;
• Recommended: run the primary harness in tmux new -s firstmate; tasks named fm-<id>; if the harness is outside tmux, a detached firstmate session is created/复用;
• Daily supervision uses bin/fm-peek.sh and bin/fm-send.sh; no need to attach; attaching and typing is authoritative intervention, reconciled at the next supervision review;
• Liveness probe outputs alive/dead/missing/unreadable/ambiguous five verdicts; only dead and missing trigger recovery, avoiding the重复 agent风险.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. When nothing is configured, which session backend does FirstMate use?

2. When the primary harness is NOT running inside tmux, how does FirstMate handle it?

3. Of the five liveness probe verdicts, which trigger recovery actions?

4. Why does the liveness probe限定 the process name source to the foreground process group而非所有后代?

🛠️ Hands-On Exercises

1. Install tmux and run tmux new -s firstmate;启动 your常用 harness inside it; then另开一个终端 and use tmux list-windows -t firstmate to observe the session structure.
2. Dispatch a极 small scout task through firstmate (e.g., "调查某仓库的 LICENSE 类型");跟踪 it with bin/fm-peek.sh <id>;记录 the fm-<id> window出现时机.
3. Read the Agent liveness probe section of docs/tmux-backend.md;画 the five-verdict decision flowchart;解释为什么 ambiguous does not authorize recovery.

Backend mastered. Next, experimental backends: herdr, zellij, Orca, and cmux.