Getting started: nothing → first session in five steps / 快速上手：从零到首个会话的五步

<fleet> is python3 <skill-dir>/scripts/fleet_manager.py, with the
directory taken from the read that delivered this skill (skill-dir when
present, else the directory of the SKILL.md path it shows). Every command prints one
JSON object; text is the human-readable part, next is the one command to
run when something is missing, and <fleet> <verb> --help lists a verb's
flags.

<fleet> 即 python3 <skill-dir>/scripts/fleet_manager.py，目录取自交付本技能的那次读取（有 skill-dir 时用它，否则用其所示 SKILL.md 路径所在目录）。每个命令打印一个 JSON 对象；text 是人类可读部分，next 是缺少某物时应运行的那一条命令，<fleet> <verb> --help 列出某个动词的标志。

1–4. Doctor, open, context, steer / 1–4. 体检、打开、上下文、操控

<fleet> doctor                                   # provider, machines, next command
<fleet> open                                     # muse, this repository root, an auto name, this host
<fleet> open --engine claude --cwd ~/repo --name reviewer --prompt-file brief.md
<fleet> context                                  # the whole picture; read `text`, act on `groups`
<fleet> read s1                                  # what it is doing or said
<fleet> dialog s1                                # what it is asking (Herdr)
<fleet> approve s1                               # answer a y/N or numbered dialog
<fleet> send s1 "heads up: I'll close this in 5 min"   # a notification, nothing typed
<fleet> send s1 "run the tests" --type --wait    # typed in as a prompt; refused over a non-empty composer

doctor answers provider: herdr (server answering, started if it was
down) or provider: tmux (liveness, scrollback, guarded input,
open/stop/close only); needs_user_action means the tmux install needs a
password: run next, rerun. open answers opened with handle (s1),
addr, identity and a receipt. send --type with submitted: false
means read before sending again.

doctor 会应答 provider: herdr（服务器有响应，若原本未启动则将其启动）或 provider: tmux（存活检测、回滚缓冲、受保护输入，仅支持 open/stop/close）；needs_user_action 表示 tmux 安装需要密码：运行 next，然后重跑。open 会以 opened 应答，附带 handle（s1）、addr、identity 和一个 receipt。send --type 若返回 submitted: false，意味着再次发送前先 read。

5. Add a machine / 5. 添加一台机器

<fleet> connect me@buildbox --label buildbox

One command, one progress line per step; it stops at the first thing
wrong with next naming the fix. Without Herdr here it opens one ssh
master of its own (one login, at most one second-factor prompt), checks
what runs there, starts a stopped Herdr server and forwards its socket, or
records the machine as tmux-only. With Herdr here it adds the machine
through Herdr first (herdr machine add, Herdr's own login, closed before
it returns), then reuses an answering forward or ssh master, else opens one
ssh master of its own: a fresh host costs Herdr's login plus at most one of
this skill's; connect buildbox again usually costs none. Then
open buildbox --engine claude --cwd ~/repo, and context covers both
machines. A report the remote session wrote comes home with
<fleet> fetch buildbox /home/me/repo/report.md; unchanged content copies
nothing. A machine that advertises MSP (machines lists it with modes
msp when TBH_AGENTS_SESSION_PROTOCOL is on) needs no connect at all:
<fleet> open <host> --cwd /home/me/repo --prompt-file brief.md opens a
session there in one call; never ssh an MSP host id.

一条命令，每步一行 progress 输出；它在第一个出错之处停下，并用 next 指明修复方法。本机没有 Herdr 时，它会自行打开一个 ssh master（一次登录，至多一次二次验证提示），检查那边在运行什么，启动已停止的 Herdr 服务器并转发其套接字，或将该机器记录为仅 tmux。本机有 Herdr 时，它先通过 Herdr 添加机器（herdr machine add，使用 Herdr 自己的登录，返回前关闭），然后复用有响应的转发或 ssh master，否则自行打开一个 ssh master：一台全新主机的代价是 Herdr 登录加上至多一次本技能的登录；再次 connect buildbox 通常毫无代价。然后运行 open buildbox --engine claude --cwd ~/repo，context 即覆盖两台机器。远程会话写出的报告用 <fleet> fetch buildbox /home/me/repo/report.md 取回；内容未变时不复制任何东西。通告 MSP 的机器（当 TBH_AGENTS_SESSION_PROTOCOL 开启时，machines 会以 modes msp 列出它）完全不需要 connect：<fleet> open <host> --cwd /home/me/repo --prompt-file brief.md 一次调用即可在那里打开会话；绝不要对 MSP 主机 id 使用 ssh。

Troubleshooting / 故障排查

you see	it means	do
`unsupported_by_provider` / `no_provider` (exit 4)	this provider cannot do that verb, or there is none	run the verb `next` names (tmux has no dialogs: `read`, then `send --type`)
`needs_user_action` (exit 5)	a step needs you: a password, a second factor, a confirmation	do the step in `next`, rerun
`provider_unreachable` (exit 6) with `connect …`	the ssh master is down or the Herdr socket does not answer	run the `connect` line in `next` with a terminal attached
`herdr_add_failed` (exit 6)	Herdr could not add the machine (its own output says why)	run the `herdr machine add …` line in `next`; a tmux-only box: `connect <target> --mode tmux`
`no_such_session` (exit 3)	the handle names a session that is gone	`list`; the session ended or was closed
`identity_mismatch` (exit 3) "not the session it was minted for"	the pane id or name now belongs to another process	`list`, use the new handle
`composer_not_empty` (exit 3)	someone is typing in that session	`read`, wait or finish the line, retry
`session_live` (exit 3) "is live; close refused"	the session still works	`stop` it first, or `close … --confirm "<the user's words>"`
a machine shows `stale` in `context`	it stopped answering, inside the skip window (`verbs.md`, Outage cadence)	nothing yet; the last group is kept; an `outage` item follows
`herdr machine list` fails	the Herdr client catalog is broken	`herdr machine list --json` by hand; `local/...` addresses keep working

你看到	它意味着	应对
`unsupported_by_provider` / `no_provider`（退出码 4）	该提供方无法执行该动词，或根本没有提供方	运行 `next` 所指名的动词（tmux 没有对话框：先 `read`，再 `send --type`）
`needs_user_action`（退出码 5）	某一步需要你：密码、二次验证或确认	完成 `next` 中的步骤，然后重跑
`provider_unreachable`（退出码 6）且带有 `connect …`	ssh master 已宕机或 Herdr 套接字无响应	在接好终端的情况下运行 `next` 中的 `connect` 行
`herdr_add_failed`（退出码 6）	Herdr 未能添加该机器（其自身输出会说明原因）	运行 `next` 中的 `herdr machine add …` 行；仅 tmux 的机器：`connect <target> --mode tmux`
`no_such_session`（退出码 3）	该句柄所指的会话已不存在	`list`；会话已结束或已被关闭
`identity_mismatch`（退出码 3）"not the session it was minted for"	该窗格 id 或名称现在属于另一个进程	`list`，改用新的句柄
`composer_not_empty`（退出码 3）	有人在那个会话中正在输入	`read`，等待或等那一行输入完成，然后重试
`session_live`（退出码 3）"is live; close refused"	会话仍在运行	先 `stop`，或 `close … --confirm "<the user's words>"`
某台机器在 `context` 中显示 `stale`	它停止应答，处于跳过窗口内（`verbs.md`，中断节奏）	暂时无需处理；最后一组结果被保留；随后会出现一个 `outage` 条目
`herdr machine list` 失败	Herdr 客户端目录已损坏	手动运行 `herdr machine list --json`；`local/...` 地址继续可用

State lives in ~/.local/share/muse/fleet-manager/state.json (handles,
outages, the last context, the last hash of every fetched file), fetched
files under ~/.local/share/muse/fleet-manager/home/<machine>/, machines in
~/.config/muse/machines.toml, forwards and ssh masters under
/tmp/fleet-manager-<uid>/. Deleting the state file loses handles only; the
next list mints new ones.

状态保存在 ~/.local/share/muse/fleet-manager/state.json（句柄、中断记录、最近一次 context、每个已取回文件的最近一次哈希），取回的文件位于 ~/.local/share/muse/fleet-manager/home/<machine>/ 下，机器记录在 ~/.config/muse/machines.toml，转发与 ssh master 位于 /tmp/fleet-manager-<uid>/ 下。删除状态文件只会丢失句柄；下一次 list 会铸造新的句柄。