feat(tester): initialize agent target from Orca selectors

skills/tester/references/run.md

@@ -2,6 +2,20 @@
 
 只在用户要跑测试时读本文件。
 
+Agent、执行目标和临时 terminal 的完整协议见 [execution.md](execution.md)。每轮运行
+都要先解析并更新 `agent`，输出生效配置列表，准备目标项目并创建一个全新的 terminal；不能复用
+已有 terminal。
+测试结束、失败、超时或中断时，都要关闭本轮创建的 terminal。
+
+## 0. 准备执行目标
+
+先按 `execution.md` 处理目标机器和项目目录，输出配置更新结果，再进入测试流程。目标项目必须包含
+可读取的 `.pouch/tester/`；如果目标目录没有测试目录，记为 `environment-fail`，不要
+偷偷回退到当前项目，也不要把测试文件复制过去。
+
+`catalog.py select` 输出的 `agent` 是本轮使用的配置快照。记录中要保留 Agent、目标
+环境、主机、项目、路径、worktree id、terminal handle，以及 terminal 是否成功关闭。
+
 ## 1. 选范围
 
 未指定范围 → `--tag smoke`，风险上限 = `default_max_risk`，`automation` 默认只跑 `automated`。
@@ -42,6 +56,66 @@ python3 <skill-dir>/scripts/catalog.py select --root <root> \
 - 探测不可达：用它的分类标 environment-fail，其余分类照跑。
 - 命中 `stop_if`：把用它的分类标 environment-fail 并记 `observed` 值，其余分类照跑；所有选中分类都被挡住时，整轮结论才是 environment-fail。
 
+## 2.1 移动端平台环境闸门与用户引导
+
+`driver=mobile` 不是一个可以互换的平台。运行前必须根据 catalog session、用例变量或用户指定，明确本轮是 Android 还是 iOS；无法判断时先停下询问平台，不得猜测。两类平台分别执行以下闸门：
+
+### Android
+
+按顺序确认：
+
+1. `adb` 可执行，且版本与当前 SDK 配置一致。
+2. `adb devices -l` 至少有一个状态为 `device` 的目标；`unauthorized`、`offline` 或空列表都不能继续。多个目标时必须显式设置 `ANDROID_SERIAL`。
+3. 被测 APK 已安装，包名与 catalog 的变量一致；可用 `adb -s "$ANDROID_SERIAL" shell pm path "$PACKAGE"` 验证。
+4. 测试所需的 HOST、端口、局域网/DNS 和权限可从设备访问。
+
+### iOS
+
+按顺序确认：
+
+1. 运行节点是 macOS，并且 `xcrun`、Xcode Command Line Tools 和 `simctl` 可用。Linux/Windows 节点不能伪装成 iOS 环境；需要 macOS 或可访问的远程 Mac。
+2. 模拟器用 `xcrun simctl list devices available` 确认目标存在且已启动，再用 `xcrun simctl bootstatus <UDID> -b` 确认完成启动；真机用 `xcrun xctrace list devices` 确认已连接、已信任且允许开发。
+3. 被测 IPA/App 已安装，Bundle ID 与 catalog 的变量一致；模拟器可用 `xcrun simctl get_app_container <UDID> <BUNDLE_ID>` 验证。
+4. 测试所需的 HOST、端口、局域网/DNS 和权限可从该模拟器/真机访问。
+
+任一项不满足，都要在执行记录中把受影响的移动用例标为 `environment-fail`，不能改成 API 测试、不能把它们标成产品 `fail`，也不要继续初始化后续移动 session。记录实际探测命令及简短输出，不要把整段设备日志塞进对话。
+
+### 环境缺失时的用户引导
+
+对话中必须输出一段可执行的引导，至少包含以下字段：
+
+```text
+## tester 环境引导：需要补齐
+
+平台: Android | iOS
+状态: environment-fail
+缺失: <具体探测项和观测结果>
+
+请完成:
+1. <修复动作；不要只写“检查设备”>
+2. <如需连接/启动/安装，写出动作>
+
+验证:
+<一条或多条可复制的验证命令>
+
+完成后: 回复“环境已就绪”，然后重跑原 tester 命令。
+```
+
+可按实际缺失替换为以下平台化提示：
+
+- Android 无设备：提示用户连接并解锁设备、开启 USB 调试、接受 RSA 授权；多个设备时设置 `ANDROID_SERIAL`；再运行 `adb devices -l`，直到目标状态为 `device`。
+- Android 未安装 APK：提示用户构建/安装与当前测试环境匹配的 APK，并用 `adb -s "$ANDROID_SERIAL" shell pm path "$PACKAGE"` 验证包名。
+- iOS 非 macOS 或无 Xcode：明确说明 iOS 测试需要 macOS + Xcode/Command Line Tools，提示用户切换到本机 Mac 或配置可访问的远程 Mac；不要建议在 Linux 上安装一个同名命令来绕过检查。
+- iOS 模拟器未启动：提示用户在 Xcode 或 `simctl` 中创建/启动可用设备，使用 `xcrun simctl bootstatus <UDID> -b` 验证。
+- iOS 真机未就绪：提示用户连接数据线、解锁并信任此电脑、开启开发者模式并确认设备出现在 `xcrun xctrace list devices`。
+
+以下是两个可复现的引导示例，测试 skill 行为时应得到同类结果：
+
+1. Android：`adb devices -l` 只有 `List of devices attached`。期望状态为 `environment-fail`，引导连接/授权设备并给出 `adb devices -l` 验证命令。
+2. iOS：Linux 节点没有 `xcrun`。期望状态为 `environment-fail`，引导切换到 macOS + Xcode 节点，并说明不能用 API 或 Android session 代替。
+
+环境引导只负责让用户补齐前置条件；除 catalog 已明确授权的 session 初始化外，不自动安装 SDK、配对真机、修改系统安全设置或上传产物。
+
 ## 3. Session
 
 看命中条用到的 `session` 键：
@@ -71,7 +145,11 @@ python3 <skill-dir>/scripts/catalog.py select --root <root> \
 python3 <skill-dir>/scripts/catalog.py run-script --root <root> --id <id>
 ```
 
-`run-script` 只跑命令，返回 `executed` + stdout/exit（或 skipped / environment-fail）。**pass/fail 仍由 Agent 对照 `expected` 判定**，不要把 curl 退出码 0 当成产品通过。
+这个命令必须发送到本轮创建的 terminal 中执行；`<root>` 是目标机器上的项目根，
+不是发起端当前目录。远程目标上的 skill 脚本不可用时，直接在该 terminal 中执行
+`how.run` 展开后的命令，并保留同样的 stdout/exit 证据。`run-script` 只跑命令，返回
+`executed` + stdout/exit（或 skipped / environment-fail）。**pass/fail 仍由 Agent 对照
+`expected` 判定**，不要把 curl 退出码 0 当成产品通过。
 
 没有 `run`：按 `how.steps` 做，证据对照 `expected`。不要发明 steps 里没有的调用。
 
@@ -100,6 +178,9 @@ python3 <skill-dir>/scripts/generate_run_csv.py --root <root> --run <yaml>
 范围: …
 风险上限: …
 session: browser=复用|新开|未用；mobile=…
+Agent: <cli> / <model> / <permissionMode>
+执行目标: <environment>/<host>:<project>:<path>
+terminal: 新建 <handle>，已关闭|清理失败
 计数: pass=N fail=N environment-fail=N skipped=N not-run=N
 失败: id + 一句证据
 跳过: id + 原因