feat: 支持通过 tmux 启动远程 session，以便本地终端可以 attach

[chenbojian]

背景

目前 runner 在远程 spawn session 时，直接通过 child_process.spawn 启动 agent 进程（detached 模式）。这样启动的 session 虽然可以通过 web 控制，但用户回到终端后无法直接 attach 到正在运行的 agent 进程。

提议

增加一个选项，让 runner 通过 tmux 来启动 agent 进程。例如：

tmux new-session -d -s hapi-<id> -- hapi claude --hapi-starting-mode remote ...

这样用户可以：

• 在 web/手机上远程创建 session
• 回到电脑后 tmux attach -t hapi-xxx 直接进入正在运行的 agent 交互界面
• 在本地终端和远程 web 之间无缝切换

控制方式

1. ~/.hapi/settings.json 中添加 "useTmux": true 作为全局默认值
2. Web 创建 session 页面增加一个 toggle，可以针对单个 session 控制是否使用 tmux

兼容性

• 默认关闭（false），不影响现有行为
• tmux 未安装时返回清晰的错误信息
• webhook 机制不受影响（HTTP 回调与终端无关）

实现思路

主要改动点：

• cli/src/runner/run.ts - spawn 时根据设置选择直接 spawn 或通过 tmux 启动
• cli/src/persistence.ts - Settings 增加 useTmux 字段
• Hub 层透传 useTmux 参数
• Web 创建 session 页面增加 toggle

如果觉得这个方向可行，我可以提交一个 PR 来实现。请问对这个功能有什么看法或建议？

[github-actions]

这个方向可行。当前代码里没有找到 tmux/screen 相关启动逻辑；runner 远程创建 session 时会构造 hapi <agent> --hapi-starting-mode remote --started-by runner 参数，然后用 detached 子进程启动，所以现在确实无法通过一个稳定的 tmux session attach 回去。

建议 PR 保持默认关闭，并把 useTmux 作为 spawn 参数一路透传到 CLI runner。实现时需要注意两点：

• tmux 启动后，runner 目前依赖子进程 PID 和启动 webhook 建立追踪；如果 tmux 命令返回的是 tmux 客户端/server 进程而不是实际 agent 进程，需要确认现有 PID 追踪、超时清理、停止 session 行为仍然正确。
• Web toggle 需要进 hub 的 spawn body schema，否则当前 API 会直接丢弃/拒绝未知字段。

Relevant code:

• cli/src/runner/run.ts:381 - runner 构造 agent CLI 参数。
• cli/src/runner/run.ts:402 - runner 当前通过 spawnHappyCLI(..., { detached: true }) 启动 session。
• cli/src/runner/run.ts:927 - runner-spawned session 固定带 --hapi-starting-mode remote --started-by runner。
• cli/src/modules/common/rpcTypes.ts:1 - SpawnSessionOptions 当前没有 useTmux 字段。
• cli/src/persistence.ts:13 - CLI settings 当前没有 useTmux 字段。
• hub/src/web/routes/machines.ts:7 - Web spawn API schema 当前只接受 directory/agent/model/yolo/sessionType/worktreeName 等字段。
• hub/src/sync/rpcGateway.ts:138 - hub 通过 machine RPC spawn-happy-session 转发 spawn 参数。
• cli/src/api/apiMachine.ts:301 - CLI machine RPC handler 接收 hub 参数并调用 runner spawnSession。
• web/src/components/NewSession/index.tsx:325 - 新建 session 页面提交 spawn 参数的位置。
• web/src/components/SpawnSession.tsx:92 - workspace browser 的创建 session 入口也会提交 spawn 参数。

---

HAPI Bot

[junxin367]

感觉增加一个命令获取hapi使用的session，这样就可以用claude或者是codex的命令直接恢复对话了

[tiann]

这个方式不一定行得通，因为 remote 模式并非直接启动 codex 的 TUI，而是用 app-server，用 tmux resume 后可能什么也看不到，你可以验证一下看看。我觉得更稳妥的方式是，支持 hapi resume [id]，如果没有指定 id，列出 session 列表供选择。