<!-- BILINGUAL-EN-ZH -->
# Provider notes: verified behaviours by version / 提供方说明：按版本核验的行为

What this skill relies on, with how each item was verified. A row without a
verification is an assumption and says so. Re-verify a row when the provider
version changes; the helper prints the version it saw (`doctor`, `list`).

本技能所依赖的内容，以及每一项的核验方式。没有核验的行属于假设，并会如实标注。提供方版本变化时需重新核验；辅助工具会打印其观测到的版本（`doctor`、`list`）。

## Herdr / Herdr

| version | behaviour | verified how |
| --- | --- | --- |
| 0.9.0 | The socket API answers one request per connection and closes it; `events.subscribe` holds the connection open and streams `{"event","data"}` lines. | The helper's fake server mirrors it; live `events` runs (#36636 evidence) |
| 0.9.0 | Closing a workspace or tab emits ONE `workspace_closed` / `tab_closed` and no per-pane `pane_closed`; the helper folds the container event. | Measured live (#36636); `test_fleet_lifecycle.py` pins it |
| 0.9.0 | `pane.agent_status_changed` is scoped per pane: a pane that appears after the subscription needs its own subscription (the helper re-opens the stream). | Measured live (#36636) |
| 0.9.0 | `agent start` refuses a kind it does not manage with exit 2 and plain-text stderr `unsupported interactive agent kind: <kind>` (no JSON); the helper then runs the kind as the command in the pane and waits for detection. | Measured live (#36636) |
| 0.9.0 | `agent prompt` on a blocked agent is refused with `agent_blocked` before any input; `--wait` from a non-working state needs an observed working/blocked state within 5000 ms, else `agent_prompt_stalled`. | `herdr agent prompt --help` text and live drives |
| 0.9.0 | A freshly started agent can take a prompt into its composer without submitting (Muse 1.0.3, Claude Code): the helper verifies and presses Enter once (`needed_enter: true`). | Measured live (#31985) |
| 0.9.0 | A restored pane is not the prior process, and a pane id can be reissued after a server restart; the ids do not reliably restart from `w1` — after `herdr session stop <name>` and a restart over the master, a named session kept counting (`w5` → `w6`). The identity tuple (`server`, `ref`, `cwd`, `engine`) exists because of the reuse, not the numbering. | the herdr-projects stage-2/3 findings (restart from `w1`); the #38715 round-8 lane FM2 drive on a named session (continued numbering) |
| 0.9.0 | A saved machine whose ssh master is up can refuse a second ssh session (`Session open refused by peer`): the Herdr bridge holds the single slot. Reach it over the master (`ssh -O forward`), never with a fresh `ssh <host>`. | Measured on the fleet (#31985, the SLOT_FACT text) |
| 0.9.0 | `pane wait-output <pane> --regex <re> --timeout <ms>` searches the recent snapshot immediately, then polls; `--source recent-unwrapped` is available. | `herdr pane wait-output --help` |
| 0.9.0 | `notification show <TITLE> --body <TEXT>` shows a server-wide notification (no per-pane target). | `herdr notification show --help` |
| 0.9.0 | `worktree open --path <PATH> --label <TEXT> --no-focus` opens an existing git worktree as a workspace. | `herdr worktree open --help` |
| 0.9.0 | `workspace create --label <TEXT> --cwd <PATH> --no-focus` returns the root pane; `--env KEY=VALUE` exists but the helper never passes environment (launch-environment inheritance stays deferred). | `herdr workspace create --help`; `test_fleet.py` pins no `--env` |
| 0.9.1 | A prompt that arrives while text is half-typed merges with and submits it. The helper reads the composer first and refuses (exit 3) when it holds text. | Reported by the herdr-projects notes and adopted by the identity-and-safety rule; NOT re-verified here (this host runs 0.9.0) — treat as an assumption until a 0.9.1 drive confirms it |
| 0.9.0 | A fresh Muse session sitting on its workspace-trust dialog was `blocked` in one drive and `idle` in the next two (`agent wait --until blocked` returned idle); `dialog` shows the prompt either way. When Herdr did not flag it, `approve --force` answers what `dialog` showed. | Loopback black-box on this host, three runs |
| 0.9.0 | `machine add <SSH_TARGET> --label <LABEL> [--remote-session <NAME>]` prepares the remote server and saves the profile; the target comes FIRST — options-first argv gets `usage: herdr machine add <ssh-target> --label <label> [--remote-session <name>]` and exit 2, although `--help` prints clap-style `[OPTIONS] --label <LABEL> <SSH_TARGET>`. Its ssh runs over a private control socket (`-F /tmp/herdr-ssh-<pid>-0/config -S /tmp/herdr-ssh-<pid>-0/ctl`) that it `-O exit`s before returning, so nothing of its login survives for `connect` to ride. Its prompts and output go to the terminal, so `connect` routes them to stderr and keeps stdout one object. | Both argv orders run against the real binary in an isolated HOME (the fake in `test_fleet.py` rejects options-first the same way); the ssh argv captured with a logging `ssh` on PATH |
| any | An 0.8.x client has no `machine` verb (`unknown command`): the fleet is `local` only. | `list_machines` handles it; not re-verified since 0.9.0 |

| 版本 | 行为 | 核验方式 |
| --- | --- | --- |
| 0.9.0 | 套接字 API 对每个连接只应答一个请求然后关闭；`events.subscribe` 保持连接打开并流式输出 `{"event","data"}` 行。 | 辅助工具的假服务器复刻了该行为；实时 `events` 运行（#36636 证据） |
| 0.9.0 | 关闭工作区或标签页只会发出一条 `workspace_closed` / `tab_closed`，而没有按窗格的 `pane_closed`；辅助工具会折叠该容器事件。 | 实测（#36636）；`test_fleet_lifecycle.py` 将其固定 |
| 0.9.0 | `pane.agent_status_changed` 按窗格限定作用范围：订阅之后才出现的窗格需要自己的订阅（辅助工具会重新打开流）。 | 实测（#36636） |
| 0.9.0 | `agent start` 对其不管理的 kind 会拒绝执行，以退出码 2 和纯文本 stderr `unsupported interactive agent kind: <kind>`（无 JSON）；辅助工具随后把该 kind 作为命令在窗格中运行并等待检测。 | 实测（#36636） |
| 0.9.0 | 对被阻塞的代理执行 `agent prompt` 会在任何输入之前被以 `agent_blocked` 拒绝；从非工作状态使用 `--wait` 需要在 5000 ms 内观测到 working/blocked 状态，否则报 `agent_prompt_stalled`。 | `herdr agent prompt --help` 文本与实时驱动 |
| 0.9.0 | 新启动的代理可以把提示词放入其输入框而不提交（Muse 1.0.3、Claude Code）：辅助工具会核验并按一次回车（`needed_enter: true`）。 | 实测（#31985） |
| 0.9.0 | 恢复的窗格不是先前的进程，且窗格 id 在服务器重启后可能被重新签发；id 并不可靠地从 `w1` 重新开始——在 `herdr session stop <name>` 并通过 master 重启后，一个具名会话的编号继续递增（`w5` → `w6`）。身份元组（`server`、`ref`、`cwd`、`engine`）的存在是因为复用，而不是因为编号。 | herdr-projects 阶段 2/3 的发现（从 `w1` 重启）；#38715 第 8 轮 FM2 泳道对具名会话的驱动（编号延续） |
| 0.9.0 | ssh master 已建立的已保存机器可能拒绝第二个 ssh 会话（`Session open refused by peer`）：Herdr 桥占用了唯一的槽位。应通过 master 访问（`ssh -O forward`），绝不要用全新的 `ssh <host>`。 | 在机群上实测（#31985，SLOT_FACT 文本） |
| 0.9.0 | `pane wait-output <pane> --regex <re> --timeout <ms>` 先立即搜索最近的快照，然后轮询；`--source recent-unwrapped` 可用。 | `herdr pane wait-output --help` |
| 0.9.0 | `notification show <TITLE> --body <TEXT>` 显示服务器级通知（没有按窗格的目标）。 | `herdr notification show --help` |
| 0.9.0 | `worktree open --path <PATH> --label <TEXT> --no-focus` 把既有的 git worktree 作为工作区打开。 | `herdr worktree open --help` |
| 0.9.0 | `workspace create --label <TEXT> --cwd <PATH> --no-focus` 返回根窗格；`--env KEY=VALUE` 存在，但辅助工具从不传递环境变量（启动环境继承仍被搁置）。 | `herdr workspace create --help`；`test_fleet.py` 固定了不使用 `--env` |
| 0.9.1 | 在文本输入到一半时到达的提示词会与其合并并提交。辅助工具会先读取输入框，若其中已有文本则拒绝（退出码 3）。 | 由 herdr-projects 笔记报告并被身份与安全规则采纳；此处未重新核验（本主机运行 0.9.0）——在 0.9.1 驱动确认之前视为假设 |
| 0.9.0 | 停留在工作区信任对话框上的全新 Muse 会话，在一次驱动中为 `blocked`，在随后两次中为 `idle`（`agent wait --until blocked` 返回 idle）；无论哪种情况 `dialog` 都会显示该提示。当 Herdr 未标记它时，`approve --force` 依 `dialog` 所示内容作答。 | 本主机上的回环黑盒测试，三次运行 |
| 0.9.0 | `machine add <SSH_TARGET> --label <LABEL> [--remote-session <NAME>]` 准备远程服务器并保存配置；目标必须放在最前——选项在前的 argv 会得到 `usage: herdr machine add <ssh-target> --label <label> [--remote-session <name>]` 与退出码 2，尽管 `--help` 打印的是 clap 风格的 `[OPTIONS] --label <LABEL> <SSH_TARGET>`。其 ssh 通过私有控制套接字运行（`-F /tmp/herdr-ssh-<pid>-0/config -S /tmp/herdr-ssh-<pid>-0/ctl`），返回前会执行 `-O exit`，因此其登录不会为 `connect` 留下任何可复用的通道。它的提示与输出直接进入终端，因此 `connect` 把它们路由到 stderr，并保持 stdout 为单一对象。 | 两种 argv 顺序都在隔离 HOME 中对真实二进制运行（`test_fleet.py` 中的假实现以同样方式拒绝选项在前的顺序）；ssh argv 用 PATH 上带日志功能的 `ssh` 捕获 |
| any | 0.8.x 客户端没有 `machine` 动词（`unknown command`）：机群仅支持 `local`。 | `list_machines` 处理了该情况；自 0.9.0 起未再核验 |

## tmux / tmux

| version | behaviour | verified how |
| --- | --- | --- |
| 3.x | `list-panes -a -F …` with `#{window_activity}` (epoch seconds) is the liveness signal: activity within 60 s counts as `working`, else `idle`. No agent state exists. | tmux format docs; the tmux suite |
| 3.x | `new-session -d -s <name>` refuses an existing name (`duplicate session`); the helper refuses too and names `status` as the next command. `open` sets `remain-on-exit on` in the same call, so an engine that exits at once leaves a dead pane whose last line is the reason: the helper kills it and answers `failed` (exit 6), never `opened`. A session whose panes all exited later shows `status: exited`, `liveness: dead`. | tmux behaviour; the tmux suite |
| 3.x | The identity engine is `#{pane_start_command}` (first word, after the `env -u …` wrapper `open` adds), else `#{default-shell}`: stable for the pane's life. `#{pane_current_command}` is reported as `program` and decides liveness (`close` refuses while any pane of the session runs a non-shell program). `list-panes` uses a fresh random field separator per read, so no path or title can shift fields. | the tmux suite |
| 3.x | `open` starts the engine under `env -u HERDR_ENV -u HERDR_PANE_ID -u HERDR_SOCKET_PATH -u TMUX …`, so a session is nobody's pane; a Muse engine gets `--workspace <cwd>`, plus `--yolo` only with `open --unattended` (default: the engine's own permission prompts; owner ruling 2026-09-19). `--worktree` and `--label` are `unsupported_by_provider` on tmux. | the tmux suite |
| 3.x | `capture-pane -p -J -S -<n>` is the scrollback read. The composer check for guarded input reads the line under the cursor, for every engine alike: empty or a bare prompt (ends in a prompt character) is free, and so is a prompt glyph followed by exactly one of Muse's idle tips, whole on one row or soft-wrapped over the rows below it (the dim text the TUI draws in an EMPTY composer after a turn settles; the list is the TUI's `prompt_hint.rs` table, shared with host-manager); any other text is half-typed input and nothing is typed over it; a check that cannot run counts as busy. `send-keys -l -- <text>` and `display-message … -- <text>` so text that starts with a dash is text. | the tmux suite |
| 3.7b | A pane-level command (`send-keys`, `capture-pane`, `display-message`) with `-t =<session>` alone does not resolve ("can't find pane"); `-t =<session>:` (exact session, its current window) does. `kill-session -t =<session>` resolves as a session target. | Probed on this host's tmux 3.7b while building the suite |
| 3.x | `display-message -t =<session>: -d 0 <text>` is the notification form of `send`. | tmux behaviour |
| 3.x | `send-keys -l <text>` then `send-keys Enter` types a guarded line; `send-keys C-c` is `stop`; `kill-session -t =<session>` is `close` (refused while a non-shell program runs, unless confirmed). | the tmux suite |
| 3.x | `-L <socket>` selects a private server: tests and black-box runs never touch the user's own sessions (`FLEET_MANAGER_TMUX_SOCKET`). | the tmux suite |

| 版本 | 行为 | 核验方式 |
| --- | --- | --- |
| 3.x | `list-panes -a -F …` 配合 `#{window_activity}`（epoch 秒）是活性信号：60 秒内的活动计为 `working`，否则为 `idle`。不存在代理状态。 | tmux format 文档；tmux 测试套件 |
| 3.x | `new-session -d -s <name>` 会拒绝已存在的名称（`duplicate session`）；辅助工具同样拒绝并提示下一步用 `status`。`open` 在同一次调用中设置 `remain-on-exit on`，因此立即退出的引擎会留下一个死窗格，其最后一行就是原因：辅助工具会杀掉它并回答 `failed`（退出码 6），绝不会回答 `opened`。窗格随后全部退出的会话显示 `status: exited`、`liveness: dead`。 | tmux 行为；tmux 测试套件 |
| 3.x | 身份引擎取 `#{pane_start_command}`（第一个词，取自 `open` 添加的 `env -u …` 包装之后），否则取 `#{default-shell}`：在窗格生命周期内保持稳定。`#{pane_current_command}` 作为 `program` 上报并决定活性（当会话中任一窗格运行非 shell 程序时，`close` 会拒绝）。`list-panes` 每次读取都使用新的随机字段分隔符，因此任何路径或标题都无法移动字段。 | tmux 测试套件 |
| 3.x | `open` 在 `env -u HERDR_ENV -u HERDR_PANE_ID -u HERDR_SOCKET_PATH -u TMUX …` 下启动引擎，因此会话不属于任何人的窗格；Muse 引擎会获得 `--workspace <cwd>`，且只有 `open --unattended` 才附加 `--yolo`（默认：使用引擎自己的权限提示；所有者裁定 2026-09-19）。在 tmux 上 `--worktree` 与 `--label` 为 `unsupported_by_provider`。 | tmux 测试套件 |
| 3.x | `capture-pane -p -J -S -<n>` 用于读取回滚缓冲。对受保护输入的输入框检查读取光标所在行，对所有引擎一视同仁：空行或纯提示符（以提示符字符结尾）即为空闲；提示符符号后恰好跟着一条 Muse 空闲提示的情况同样算空闲（整条在一行，或软换行到下方几行；这是 TUI 在一轮结束后于空输入框中绘制的暗色文字；该清单即 TUI 的 `prompt_hint.rs` 表，与 host-manager 共享）；任何其他文字都是输入到一半的内容，不会在其上键入任何东西；无法运行的检查按忙对待。`send-keys -l -- <text>` 与 `display-message … -- <text>` 保证以破折号开头的文字仍被当作文字。 | tmux 测试套件 |
| 3.7b | 窗格级命令（`send-keys`、`capture-pane`、`display-message`）只带 `-t =<session>` 时无法解析（"can't find pane"）；`-t =<session>:`（确切会话，其当前窗口）可以。`kill-session -t =<session>` 作为会话目标可以解析。 | 构建测试套件时在本主机的 tmux 3.7b 上探测 |
| 3.x | `display-message -t =<session>: -d 0 <text>` 是 `send` 的通知形式。 | tmux 行为 |
| 3.x | `send-keys -l <text>` 然后 `send-keys Enter` 键入受保护的一行；`send-keys C-c` 是 `stop`；`kill-session -t =<session>` 是 `close`（当非 shell 程序在运行时会被拒绝，除非已确认）。 | tmux 测试套件 |
| 3.x | `-L <socket>` 选择私有服务器：测试与黑盒运行绝不接触用户自己的会话（`FLEET_MANAGER_TMUX_SOCKET`）。 | tmux 测试套件 |

## MSP (host-manager's mode C) / MSP（host-manager 的模式 C）

| version | behaviour | verified how |
| --- | --- | --- |
| transport CLI 2026-09 | `muse hosts --json` rows carry the host id, `msp_ready`, `availability` (online\|offline) and no `authorized` key (absent is authorized); a row without `msp_ready` is not a machine. The operator's directory can be wide: 20 advertising hosts on one devserver, 65 for the verifier. | the operator rows of the 2026-09-27 MSP acceptance and this PR's live rows |
| transport CLI 2026-09 | `muse sessions --host <host> --json` answers `result.sessions[]` of `{target: "<host>/<session id>", session: {sessionId, title, workspaceRoot, status: idle\|running\|notLoaded, activeTurnId}}`; `muse show <target>` adds `pendingRequests[]`. One `sessions --host` per online host per digest (in parallel), one `show` per running session. `--all-hosts` is a catalog scan with a 64-host budget: past it the answer is exit 4, `status: partial`, no rows and one `errors[]` entry per host — never the board's source. | live 2026-09-27 (row 24; verifier V-43535 raw envelope); the host-manager fake mirrors both shapes |
| host-manager | `open --host H --cwd P --name N [--prompt-file]` is `muse start` then the brief as `muse send --busy queue`; `send --steer` is `muse steer --turn <running>`; `close --confirm` is `muse interrupt --turn` then `muse task stop-all`, and the host keeps the session listed idle (no per-session end verb); `stop` on a session host-manager did not record is `no_such_session`, so this skill's `stop` names `close` instead. | host-manager's `test_msp_provider.py`; this skill's `test_msp.py` |

| 版本 | 行为 | 核验方式 |
| --- | --- | --- |
| 传输 CLI 2026-09 | `muse hosts --json` 的行带有主机 id、`msp_ready`、`availability`（online\|offline），并且没有 `authorized` 键（缺省即已授权）；没有 `msp_ready` 的行不是机器。操作员的目录可能很大：一台 devserver 上有 20 个通告主机，验证者那里有 65 个。 | 2026-09-27 MSP 验收的操作员行与本 PR 的实时行 |
| 传输 CLI 2026-09 | `muse sessions --host <host> --json` 以 `result.sessions[]` 应答，元素为 `{target: "<host>/<session id>", session: {sessionId, title, workspaceRoot, status: idle\|running\|notLoaded, activeTurnId}}`；`muse show <target>` 额外给出 `pendingRequests[]`。每份摘要对每台在线主机一次 `sessions --host`（并行执行），对每个运行中的会话一次 `show`。`--all-hosts` 是一次带 64 台主机预算的目录扫描：超出后应答为退出码 4、`status: partial`、无行，且每台主机一条 `errors[]` 条目——它绝不能作为看板的数据来源。 | 2026-09-27 实时（第 24 行；验证者 V-43535 原始信封）；host-manager 的假实现复刻了两种形态 |
| host-manager | `open --host H --cwd P --name N [--prompt-file]` 是先 `muse start` 再以 `muse send --busy queue` 发送任务简报；`send --steer` 是 `muse steer --turn <running>`；`close --confirm` 是先 `muse interrupt --turn` 再 `muse task stop-all`，且主机让该会话保持为 idle 列示（没有按会话的结束动词）；对 host-manager 未记录的会话执行 `stop` 会得到 `no_such_session`，因此本技能的 `stop` 改用 `close`。 | host-manager 的 `test_msp_provider.py`；本技能的 `test_msp.py` |