在现有 Herdr 会话内创建一次性命名会话做隔离复现（避免…

当需要在真实 Herdr 服务器、pane、PTY、agent 或 socket API 上复现问题，又不能触碰用户默认会话时，用一次性命名会话驱动复现。

适用场景

解决思路

1. 先确认调用方在 Herdr 内并了解已安装接口：执行 `test "${HERDR_ENV:-}" = 1`、`herdr --version`、`herdr --help`、`herdr session`、`herdr pane`、`herdr agent`；在使用不熟悉或可能产生副作用的命令前先查看其嵌套帮助；不要直接运行裸 `herdr` 做探索，因为它会启动或附加 TUI；记录复现所测试的 Herdr 二进制与版本，若测试的是 checkout 构建，按仓库说明运行该构建，不要静默替换为已安装二进制。
2. 在当前 tab 创建一个兄弟 shell pane 且不移动焦点：优先用 harness 提供的 Herdr 布局工具，否则在查看帮助后用已安装的 pane split 命令；把新 pane 的 cwd 设为 `/var/tmp` 或专用复现目录；保存返回的外层 pane ID，这是清理时唯一允许关闭的父会话 pane。
3. 选择短的唯一会话名，如 `repro-<topic>-<timestamp>`；启动前在一次性客户端实际加载的配置中显式允许嵌套：因为 `HERDR_ENV=1` 会从外层 pane 继承，除非启用 `[experimental].allow_nested`，否则启动会被拒绝；注意隔离的 `XDG_CONFIG_HOME` 不会从用户全局配置继承该设置。
4. 用文件写入工具在复现目录下创建测试专用配置；默认配置复现时内容可为 `[experimental]\nallow_nested = true`；若要用用户配置复现，把该配置复制到测试目录并在其现有 `[experimental]` 表中启用 `allow_nested`（若表不存在则添加），不要创建重复的表或键；绝不编辑用户全局配置来允许复现，也不要通过 unset `HERDR_ENV` 绕过嵌套检查。
5. 启动时把测试配置的绝对路径作为 `HERDR_CONFIG_PATH` 传入，并在配置校验及任何需要加载该测试配置的命令中使用同一覆盖；该覆盖只选择配置文件，不隔离已保存的机器目录或其他全局状态；当复现会改动已保存机器时，同时使用测试专用的 `XDG_CONFIG_HOME` 和 `XDG_STATE_HOME`，并在所有针对该测试环境的命令上保留这些覆盖。
6. 在新外层 pane 内运行命名会话，清除继承的会话选择、socket 覆盖和调用方 ID，使嵌套运行时不会误指向父会话：`env -u HERDR_SOCKET_PATH -u HERDR_CLIENT_SOCKET_PATH -u HERDR_SESSION -u HERDR_WORKSPACE_ID -u HERDR_TAB_ID -u HERDR_PANE_ID HERDR_CONFIG_PATH=<absolute-test-config-path> herdr --session <session-name>`；需要时在该启动命令中加入复现专用环境变量；配置服务器的环境变量必须在命名服务器启动前就位。
7. 启动前用同一配置覆盖执行 `herdr config check` 校验测试配置；启动后读取外层 pane 以捕获启动错误（如 `nested herdr is disabled by default`），不要仅因 `pane run` 返回成功就假定启动成功。
8. 在命名会话 API 就绪前不要继续：从父会话寻址该会话并列出其 pane 来确认就绪。
9. 从父会话发出的每条控制命令都必须清除继承的 socket 覆盖并显式选择临时会话，例如：`env -u HERDR_SOCKET_PATH -u HERDR_CLIENT_SOCKET_PATH -u HERDR_WORKSPACE_ID -u HERDR_TAB_ID -u HERDR_PANE_ID HERDR_SESSION=<session-name> herdr pane list`；每条命令都重复该前缀，不要依赖 shell 状态在工具调用间保持。
10. 从 `pane list` 读取一次性根 pane ID，在向其启动任何东西前确认其 cwd 和前台进程。
11. 注意命名会话隔离运行时状态、socket、pane 和持久化，但默认仍共享全局 Herdr 配置和 agent manifest 覆盖；当配置来源可能影响复现时检查其来源，不要仅为让测试通过而修改共享配置。
12. 通过 API 驱动复现：shell 和普通进程用 pane 命令——`pane run` 在可用 shell 提示符启动命令、`pane wait-output` 等待确定性输出、`pane read` 捕获终端内容、`pane send-text` 发送字面输入、`pane send-keys` 发送支持的按键、`pane get`/`pane process-info`/`pane layout` 查看运行时状态。
13. 仅在 Herdr 识别出编码 agent 后使用 agent 命令：`agent start` 在已有 shell pane 启动受支持 agent、`agent prompt` 原子提交一个提示、`agent wait` 等待 `working`/`blocked`/`idle`/`done`/`unknown`、`agent read` 捕获 agent 终端、`agent get` 和 `agent explain` 检查状态与检测、`agent send-keys` 做交互响应；使用前先运行相关命令组的帮助，因为名称和选项可能变化。
14. 优先使用等待而非任意 sleep；当计时本身是被测对象时，记录时间戳并使用有界轮询；在被复现转换的前、中、后捕获状态。
15. 当所需终端按键不被高层命令支持时，仅在确认目标应用期望的按键后，通过一次性 pane 发送其终端序列；绝不向父 pane 发送原始控制序列。
16. 启动 agent 前检查其已安装的 `--version` 和 `--help`；在 Herdr 的参数分隔符之后传入 agent 原生参数；使用用户请求或批准的精确模型，从实时 agent 屏幕验证模型而不是信任别名；基线优先使用低 effort、安全模式和手动权限（若 agent 支持）；仅当疑似行为依赖 hooks、插件或设置时才用用户真实配置重复。
17. 权限状态测试使用无害操作；捕获证据后拒绝待处理动作，并验证未创建任何产物。
18. 收集足够证据供他人复现：Herdr 二进制与版本、命名会话与启动环境、目标应用或 agent 版本与参数、精确命令或提示、每次转换前后的 pane 与 agent 状态、相关 `pane read`/`agent read`/`agent explain`/API 输出/会话日志、以及当时生效的是全局配置还是本地 manifest 覆盖；从 `herdr session list` 读取命名会话目录和 socket，不要假设其路径；除非用户要求保留到别处，大证据放在 `/var/tmp` 下；区分观察到的事实与推测的原因，先复现原版行为，再每次只改一个变量。
19. 清理是复现的一部分，失败后也要执行：1) 拒绝待处理提示并在可行时干净停止测试应用；2) 验证无害探针文件或其他测试产物不存在，或只删除本次复现创建的产物；3) 用已安装的 session 命令停止临时命名会话；4) 删除同一已停止会话；5) 确认它不再显示为运行中；6) 等待外层 pane 返回其 shell；7) 只关闭本工作流创建的外层 pane；绝不因另一个命名会话看起来陈旧就删除它，绝不关闭运行当前 agent 的 pane 或任何非为复现创建的 pane。
20. 报告结果：说明复现了什么、未复现什么、失败的确切转换，包含清理状态，并提及可能影响结果的共享配置或 manifest 覆盖。

适用边界 · 注意事项

• 不要在默认会话中运行复现。
• 不要停止、重启、删除或杀死主 Herdr 服务器。
• 不要用 `pkill`、宽泛进程匹配或猜测的 PID 做清理。