Chapter 7 · Experimental Backends: herdr, zellij, Orca, and cmux

Chapter goals: Master the selection rules, installation要点, and safety边界 for the four experimental session backends beyond tmux; learn to pick the right backend for different工作 environments and switch correctly.

7.1 Why Multiple Backends Exist

In Chapter 6 we learned the tmux reference backend — it is FirstMate's唯一的"reference implementation" (reference backend) with the most complete行为保证. But not everyone uses tmux: some prefer新一代终端管理器 like Herdr, some use cmux as their主力终端 on macOS, others are深度 users of zellij or Orca.

FirstMate's answer: session endpoints可替换, supervision协议不变. Regardless of which backend's window a crewmate runs in, the firstmate supervises通过统一的元数据路由接口 (bin/fm-peek.sh <id> to view, FM_HOME=<home> bin/fm-send.sh <id> '<text>' to send) — you don't需要学一套新指令 for each backend.

不过官方对这四个后端的定位很明确：它们都是实验性的 (experimental). tmux拥有最完整的维护者验证 (见 docs/verification/runtime-backends.md); the其余后端各有已记录的能力边界. Selection priority建议:

tmux        Reference default;最完整保证; pick it unless有特殊理由
herdr       Pick when you want原生 busy/idle/blocked状态信号
zellij      Pick when you already use zellij and接受其当前限制
orca        Pick for macOS users who want to连 worktree into Orca management
cmux        Pick for macOS GUI users who want tasks in the cmux sidebar

7.2 Selection Rules: Explicit Setting and Auto-Detection

All backends'共享选择语义由 docs/configuration.md统一拥有. Three ways to specify:

# Method 1: local gitignored config file (persistent)
echo "zellij" > config/backend

# Method 2: env var (effective for this launch only)
FM_BACKEND=zellij claude

# Method 3: explicitly request in conversation

The key区别在于谁能被自动检测 (runtime auto-detection):

Backend	Auto-detect	Note
tmux	✅	Reference default
herdr	✅	Selected when primary session runs natively under HERDR_ENV=1 and not in tmux
cmux	✅	Selected when primary session runs in cmux
zellij	❌	Never auto-detected; must be explicitly set
orca	❌	Never auto-detected; must be explicitly set
codex-app	—	Not yet a runtime backend (blocked boundary, see docs/codex-app-backend.md)

Auto-detection follows the "innermost multiplexer wins" principle. Take cmux as an example: detection order first查 tmux, then herdr, finally cmux — so a tmux pane nested in cmux is识别为 tmux. herdr同理: a tmux pane nested in Herdr解析为 tmux.

Another重要细节: auto-detection only决定 the backend; never grants credentials or bypasses safety settings. If cmux's socket access isn't configured, auto-detection won't help you绕过 — spawn refuses启动 with actionable setting指引.

7.3 herdr: Terminal Manager with Native Status Signals

herdr's最大卖点 is 原生 busy / idle / blocked状态信号 — no other backend has这种信号; supervision有 to靠屏幕截图哈希轮询加各 harness 自己的生命周期语义来判断忙碌状态.

基础要求: herdr, jq, and the协议版本底线. Its topology约定:

Herdr Session
└── home workspace (home label: firstmate or 2ndmate-<id>)
    ├── fm-<task-id-1>  task tab
    ├── fm-<task-id-2>  task tab
    └── ...

Each task tab是 placed in the完全一致 workspace as the launcher (parsed现场 from the injected socket identity, not trusting a snapshot). When identity cannot be精确解析, spawn直接拒绝 — never退化 to label-based search — because Herdr does not强制 workspace/tab label uniqueness; labels不能决定工人去向.

Presentation Spaces and Version底线

From herdr 0.8.0+, each新 crewmate/scout is默认 projected to a 一次性单任务工作区 (presentation space), visually one-column-per-task. But there's a version底线:

# Disable projection (write to local gitignored config)
echo "off" > config/herdr-presentation-spaces

# Force enable (accept已文档化的焦点移动代价 even below版本底线)
echo "on" > config/herdr-presentation-spaces

# File absent → decided by版本底线:
#   herdr >= 0.8.0 → projection enabled by default
#   herdr <  0.8.0 →普通 home平铺 layout; warn once

Why this底线? Before 0.8.0, herdr had a焦点缺陷: clearing a task briefly移走 then restores the active workspace (~1/7 second), and "clearing the entire workspace on each cleanup" is the唯一能避开该缺陷的删除形态. 0.8.0 fixed this, so unconfigured homes only default-enable projection on达标 versions.

The repo also自带两个辅助脚本 bin/backends/herdr-workspace-move.py and bin/backends/herdr-eventwait.py, handling workspace moves and event waits respectively.

7.4 zellij: Explicit-Only Shared Session Backend

zellij is an explicit-only backend: never auto-detected. It uses a shared session (default name firstmate), one tab per task:

# Use FM_ZELLIJ_SESSION for isolated验证 pick a different session name
FM_ZELLIJ_SESSION=fm-test zellij --session fm-test

# Attach to observe (日常监督不需要 attach)
zellij attach firstmate

Requires zellij 0.44+ and jq. Visible titles use the home-scoped format fm-<home-label>-<id> (e.g., fm-firstmate-42), plus a stable短哈希 of the FirstMate install path — so主家, secondmate homes, and even multiple FirstMate installs on the same machine don't混扰 tasks.

zellij has a famous坑: CLI action commands return exit 0 even for非存在的会话或 pane. The adapter's countermeasure: don't trust exit codes; do结构化校验 before and after each操作:

Before操作: verify session exists → verify terminal pane exists → verify expected scoped title
After操作: validate JSON/integer response shapes
Residual race: pane可能在校验后、操作前消失 → downstream reports this narrow race,
              rather than treating exit 0 as success

Sending messages也有类似严谨性: before Enter is sent, the adapter must prove the composer content增加恰好 the pasted text; unreadable composers, pastes landing elsewhere, unrelated output all fail without提交. Dead panes are永远 fail-safe — empty screens classified as unknown, never误认为 "确认送达".

7.5 orca: macOS-Exclusive Worktree-Integrated Backend

orca是 macOS-exclusive 后端: integrates directly with the Orca app's worktree management, letting each crewmate任务直接挂在一个独立 worktree 上——省去了 treehouse 的额外 abstraction.

要求 Orca app 已安装且运行中。选择方式与 zellij 相同: 显式设置 config/backend 或 FM_BACKEND=orca。

orca 的 supervisor 接口与 tmux 完全一致: bin/fm-peek.sh 和 bin/fm-send.sh 不需任何改动。区别只在底层: orca 直接把任务端点落在 Orca 的 worktree 里，省去了额外的 worktree 创建/销毁开销。

7.6 cmux: macOS GUI Sidebar Backend

cmux is a macOS GUI backend: tasks appear in the cmux sidebar rather than a traditional terminal window. It requires cmux to be running and Socket Control Mode configured.

要求 cmux ≥ 1.0 and Socket Control Mode enabled (automation模式推荐). 选择方式: config/backend 写入 cmux 或 FM_BACKEND=cmux.

workspace UUID changes on app restart — so恢复逻辑按作用域标题搜索再解析当前 surface id; UUID从不作为恢复权威. Runtime detection marker is CMUX_WORKSPACE_ID (CMUX_SOCKET_PATH doesn't count, as it may be set outside cmux).

Boundary: Why Codex App Is Not Yet a Backend

The official docs专门用一篇 docs/codex-app-backend.md 说明一个"负边界": Codex App is not an可选 runtime backend. Codex Desktop's host tool能创建并监督可见线程, but FirstMate's backend scripts都是 shell入口,无法调用这些宿主工具 — 缺少的是 Codex Desktop官方支持的 shell可调用传输 (CLI wrapper, documented JSON-RPC/MCP, or well-maintained helper), not another local ledger.

未来若要成为真正的后端, 必须满足与终端后端相同的生命周期契约: 创建任务端点并返回持久线程 id → 发送指令与后续消息 → 读取足够状态以监督 → 归档/终止同端点 → 线程必须回写 state/<id>.status 生命周期行. 状态回传通道是强制的: 一个无法向 FirstMate 汇报的可见线程不是完整后端. 在官方桥接落地前, codex-app 不会进入已知或可 spawn 的后端注册表 — 选型时不要被"能跑起来"的演示迷惑.

7.7 Switching Backends and Verification

Regardless of which backend you pick, the daily supervision接口完全一致:

bin/fm-peek.sh <id>                              # View crewmate screen
FM_HOME=<home> bin/fm-send.sh <id> 'steer text'  # Send a steer指令

To验证 the backend is生效, spawn a small task and check the backend= field and该后端专属 fields in the task metadata:

tmux     → backend=tmux     window=<session>:<window>
herdr    → backend=herdr    (tab/workspace identifier)
zellij   → backend=zellij   zellij_session= zellij_tab_id= zellij_pane_id=
orca     → backend=orca     orca_worktree_id= worktree=
cmux     → backend=cmux     cmux_workspace_id= cmux_surface_id=

Each backend's active维护者验证 (source code and实测证据, including socket modes, focus behavior etc.) is统一记录在 docs/verification/runtime-backends.md. Pre-switch checklist:

□ New backend's CLI and jq installed and version达标
□ Platform match (orca/cmux macOS-only)
□ Special settings completed (cmux socket mode / Orca app ready)
□ config/backend or FM_BACKEND written with the correct backend name
□ Spawn a small task and verify the backend= metadata field

7.8 Chapter Summary

• Four experimental backends (herdr/zellij/orca/cmux) each have tradeoffs; tmux remains the most行为保证完整的参考默认;
• Auto-detection only covers herdr and cmux; zellij and orca永远必须显式设置; codex-app is not yet a runtime backend;
• Detection order tmux → herdr → cmux ensures "innermost multiplexer wins"; auto-detection never grants credentials or bypasses safety settings;
• Each backend's safety边界要提前配好: cmux socket mode and password, herdr presentation spaces version底线, zellij structured校验弥补 exit 0陷阱;
• Regardless of backend switch, the supervision接口 fm-peek.sh / fm-send.sh and metadata routing remain不变.

🧪 随堂测验

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

1. Regarding auto-detection rules for the four experimental backends, which is correct?

2. What principle does auto-detection follow when multiple backends are nested?

3. Why does zellij require structured validation而非信任 exit 0?

4. Why is Codex App not yet a runtime backend?

🛠️ Hands-On Exercises

1. 对照 7.2 的表格检查你的环境: what terminal multiplexer are you using? If it's zellij or orca, write the two explicit-setting methods and explain why these two backends不能依赖 auto-detection.
2. On macOS, install cmux and complete Socket Control Mode setup (automation模式推荐): first故意保持默认的 cmuxOnly 模式尝试 spawn,观察拒绝信息中的设置指引; then switch to automation模式 and retry; finally spawn a small task and verify cmux_workspace_id and cmux_surface_id appear in the metadata.
3. Your herdr is version 0.7.x:实验 the three cases "no config file created", "write off", "write on"; observe the workspace layout difference when spawning a new task; note the one-time警告 content below 0.8.0; explain为什么 deleting the标记 file causes the警告 to reappear via the state/.herdr-presentation-floor-<release> marker.

Backends understood. Next, learn Subagents: expert delegation.