pi-legion 2.0.3 → 3.0.0

package/docs/qa-hunting-round.md

@@ -0,0 +1,150 @@
+# QA 狩猎 round 编排手册（multi-agent orchestration）
+
+> **给谁看**：任何要在这个仓库组织「一轮」多子 agent 缺陷狩猎的主 agent（或人）。读完即可开跑。
+>
+> **和 `tui-qa-playbook.md` 的分工**：那份是**单人狩猎手册**——三层证据链、容器/tmux 基建、
+> 单个角度怎么取证、issue 怎么写。本手册是**round 级编排**——多角色怎么拆、派发顺序、
+> 判据纪律怎么跨角色执行、卡死了怎么止损。两份都要读，先读那份。
+>
+> **实战背书**：2026-10-16 round2（v2.0.4 @ b00d4c7）：4 角度并行 → 29 candidate →
+> 判 true 9（major 6 / minor 3）→ issue #172–#181，转化率 31%。全程含一次卡死事故处置（§5）。
+
+---
+
+## 0. 核心原则：四角色拆权，发现者不验证，验证者不提交
+
+单路 hunter 自搜自证，误报率高且慢。流水线把权力拆开：
+
+| 角色 | 只做 | 永不 |
+| --- | --- | --- |
+| 主 agent（你） | 冻结狩猎面、派发、steer 补给、裁决、收官 | 自己跑侦察读代码 |
+| `scout` | 冻结面事实清单（带 file:line） | 出方案、下结论 |
+| `qa-hunter` × N | 按一个角度找 candidate + 原始证据 + **detector 原文** + 自陈伪影风险 | 验证、自证、提 issue |
+| `qa-repro` × N | 独立复现，判 true / false / downgraded | 沿用 hunter 的判据、提 issue |
+| `qa-reporter` × 1 | 查重后按模板提交已判 true 的 finding | 提 candidate、并发多路提交 |
+
+角色卡在 `agents/`（`agents/qa-hunter.md` 等），团队编排在 `.pi/settings.json` 的
+`subagents.teams["qa-hunting"]`。切换团队：会话里 `/subagents` 或写 settings 后重启会话。
+
+## 1. Round 流程（按序，别跳步）
+
+```markdown
+0. 冻结基线：commit hash / 版本 / 容器 / 已 open issue 清单 / 上一轮已推翻的怀疑点
+1. 冻结面 scout（1 路，只读，先发）
+   └─ 产出：带 file:line 的事实清单——env 读取点 / 契约条款落点 / 跨面口径 /
+      状态机转移表 / 可执行复现入口
+2. hunter 并行派发（4 路足够，角度互斥见 §2）——不等 scout 完也可以先发，
+   但 scout 产出一到就 steer 补给各 hunter
+3. steer 补给：把 scout 事实按角度切给各 hunter，并声明「哪些怀疑点已被推翻，别再扫」
+4. 每路 hunter 交卷 → 立即派对应 qa-repro（流水线化，别攒齐）
+5. repro 判 true → 派 reporter（全轮只用 1 路串行提交，防查重竞态；
+   后续判 true 的追加 steer 给同一个 reporter）
+6. 收官：round notes 落库 `.qa-hunt/<date>-roundN/notes.md`（战果表 +
+   被推翻清单 + 事故 + 下轮改进 + 未覆盖）
+```
+
+**实测收益**：冻结面 scout 前置为每路 hunter 省 ~20 分钟定位时间，且常直接推翻
+主 agent 一半的怀疑点（round2：「env 全带 `Number.isFinite`，NaN 穿透 0 命中」）。
+
+## 2. 角度切法（互斥，4 路足够）
+
+| 角度 | 内容 | 边界（不做什么） |
+| --- | --- | --- |
+| A 契约 vs 实现 | 冻结契约（`docs/tui-viewer-contract.md` 等）逐条在真实 TUI 跑 | 不做非契约项的打磨建议 |
+| B 配置边界 | 每个 env / settings 字段喂 `""`/`0`/`-1`/`NaN`/`Infinity`/浮点/`abc`/`1e18` | 不做 TUI 视觉 |
+| C 跨面口径 + 单位混淆 | 同一数据在多处渲染是否同口径；截断按码点还是显示宽度 | 不做交互/键位 |
+| D 状态机 / 生命周期 / 清理 | 转移表交叉、槽位释放、清理阈值、子进程回收、doctor | 不做 A/B/C 已覆盖面 |
+
+角度数 >4 时 hunter 上下文互相重叠，总产出反而下降。
+
+## 3. 派发任务卡（hunter 模板，必填项别省）
+
+每路 hunter 的任务卡必须包含：
+
+```markdown
+## 环境
+- 仓库 / 版本 / commit
+- 容器：docker exec <name> bash -lc '<cmd>'（/plugin 挂载，pi/tmux 可用）
+- 先读 docs/tui-qa-playbook.md §3 铁律，再读相关契约章节
+
+## 你的角度（+ 明确边界：不做什么，撞到别的是别人的）
+## 时间预算（如 60min）+ candidate 上限（≤8，防跑飞）
+## 硬性规则
+- 每个 bash 调用必须 `timeout 60 <cmd>` 包裹（命令级 timeout 是必填项，
+  时间预算替代不了它——见 §5 事故）
+- 禁止调用 poll-loop 等待型 API（如 acquireVerifySlot）；长脚本内加
+  `setTimeout(() => process.exit(9), 30_000)` 自杀兜底
+- 产物落 .qa-hunt/<round>/<角度>/，issue 内联最小复现脚本
+
+## 输出格式
+- 每个 candidate：症状 + file:line + detector 原文（「我用什么表达式/符号判断状态成立」）
+  + 原始证据路径 + 自陈「我未排除的伪影可能」
+```
+
+**明确列出已提交 issue 的根因**，hunter 撞到同根因直接跳过。
+
+## 4. 判据纪律（决定转化率的关键）
+
+### hunter 侧
+- **detector 必须写进报告**，供 repro 独立审查——这是 repro 换判据的依据。
+- **禁止自证**：别用被测代码自己的查询去数被测代码。要验槽位上限，别用编排器内部那条
+  SQL 去数，把同一份 DB 状态喂给**已发布的** `checkLaunchBudget()` 交叉比对。
+- **报下游可观测后果**：别报「解析器返回了这个值」，报「用户实际看到的字节数 /
+  目录在不在 / 子进程起没起来」。
+
+### repro 侧
+- **判据必须与 hunter 不同**，否则等于自证。先 grep hunter 的 detector 是否有歧义，再自建。
+- 优先攻 hunter 自陈的伪影风险。不可达路径按 playbook §4 降级为理论风险。
+- **先读既有测试再判**：作者的测试可能已把某行为断言为设计意图（round2：
+  `state-machine.ts:108` `parent_decision` 直放被单测断言为设计意图，不报）。
+- 修过的历史行为要查 issue 历史，别把有意的两套语义判成不一致。
+
+### 高频证伪模式（round2 推翻 20 条中的代表，新 round 先对照这份清单）
+- 「A/B 两面不一致」→ 查契约是否**明文定义**了这个拆分（fanout vs maxActiveNodes，
+  契约 §11.1 明文，非缺陷）
+- 「状态字面冲突」→ 查**可达性**（`awaiting`/`unknown` 经 `runtime.ts:1210-1216`
+  映射掉，永不进 `node.status`）
+- 「边界系统性差 1」→ 实测是不是只有极窄边界带（round vs floor 仅 500ms 带）
+- 「截断/宽度有 bug」→ pi-tui 自己处理 ANSI/OSC8/宽字符/ZWJ，**先证伪再报**
+- 「某模式下功能静默」→ 用**非本仓库的对照扩展**证明是宿主行为还是本仓库行为
+  （`print` 下 `/legion` 静默 → 根因在 pi 宿主 `runner.js:132` noOpUIContext，本仓库无责）
+- 「敏感信息泄露」→ **必须真实触发**，别用构造的假密钥（round2 真实触发后结论反转）
+
+## 5. ⚠️ 卡死止损（round2 事故：130 分钟）
+
+**现象**：`subagent status` 一直 `working`，但零进展。
+
+**判据（三条同时成立即卡死，不是慢）**：
+1. 子会话 JSONL 静默 >60min（`stat` mtime）——改进阈值：**>15min 即查**
+2. 最后一条记录是 `toolCall` 而**无对应 toolResult**
+3. 产物目录 mtime 冻结，之后 0 个新文件
+
+**止损流程**：
+```text
+1. 取证不急着 kill：stat JSONL mtime / tail 最后一条 / 查产物 mtime / ps 找子进程
+2. subagent({ action: "stop", name: <child> }) → 确认 RPC 子进程回收（ps 复查 gone）
+3. 清理孤儿进程（mock-llm 等，ps -eo pid,cmd | grep "[m]ock-llm" 定点 kill，
+   禁 pkill -f 自杀）
+4. 补派接手者：任务卡带上已完成部分 + 防挂死硬性规则（§3），别从零重跑
+```
+
+round2 根因：hunter 调了 `acquireVerifySlot()`（轮询等槽位的阻塞 API），bash 调用无
+`timeout` 包裹 → 子进程挂死 → 永久 working。**根因是派发漏洞**：任务卡写了时间预算
+却没写命令级 timeout。这就是 §3 把它列为必填项的原因。
+
+## 6. 收官 checklist
+
+- [ ] 所有判 true 的 finding 已提交 issue（reporter 报告里有 # 号清单）
+- [ ] round notes 写入 `.qa-hunt/<date>-roundN/notes.md`：战果表 / 被推翻清单及原因 /
+      事故记录 / 下轮改进 / 未覆盖留给下轮
+- [ ] `.qa-hunt/` 目前 untracked：issue 里必须内联最小复现脚本，别只引用本地路径
+- [ ] 检查无遗留 mock-llm / pi 孤儿进程
+- [ ] 仓库 `git status` 干净（hunter/repro 只许写 `.qa-hunt/`，不许碰 `src/`）
+
+## 7. 角色卡与团队配置
+
+- 角色定义：`agents/qa-hunter.md`、`agents/qa-repro.md`（若有）、`agents/scout.md`、
+  `agents/advisor.md`
+- 团队编排示例：`docs/subagents-teams.md`；本仓库实配：`.pi/settings.json`
+  → `subagents.teams["qa-hunting"]`
+- 子 agent 卡死重试 2 次仍失败 → 升级咨询 `advisor`（见各角色卡的失败止损节）

package/docs/subagents-teams.md

@@ -1,17 +1,25 @@
 # Team configuration examples
 
-`subagents.teams` maps team names to an ordered roster. A member can be a role
-name string or an object with an `agent` name and per-member overrides. The
-examples below mirror the four local practice teams; replace every model
-placeholder with an ID available from your provider. No provider-specific
-model is required by these templates.
+`subagents.teams` maps team names to an ordered roster **and optional
+team-scoped parent/child context**. A member can be a role name string or an
+object with an `agent` name and per-member overrides. Each team may also set
+`parentContext` / `childContext` (same forms as the global keys: inline
+markdown, `@path`, or a string array; `false` disables that side). Team
+context **replaces** the global value for that side — it never merges.
+
+The examples below show two squads with **different operating workflows**, not
+just different models. Replace every model placeholder with an ID available
+from your provider.
 
 ```json
 {
   "subagents": {
+    "parentContext": "Global fallback: prefer named teams for real workflows.",
     "teams": {
       "fe-premium": {
         "description": "Frontend · complex projects",
+        "parentContext": "FE premium parent workflow:\n1. Scout UX surface and design tokens first.\n2. Prototype before planner locks the slice.\n3. Designer gate before worker lands UI.\n4. Reviewer checks a11y + visual regress; escalate to advisor on product ambiguity.\n5. Stop when designer+reviewer both approve; do not expand scope mid-flight.",
+        "childContext": "FE premium child guardrails: stay in the assigned component tree; no API shape changes without planner; hand off diffs with screenshot notes.",
         "members": [
           { "agent": "scout", "model": "your-provider/strong-model", "thinking": "high" },
           { "agent": "prototype", "model": "your-provider/strong-model", "thinking": "high" },
@@ -23,8 +31,21 @@ model is required by these templates.
           "centurion"
         ]
       },
+      "be-value": {
+        "description": "Backend · standard projects",
+        "parentContext": "BE value parent workflow:\n1. Scout existing handlers and data model only — no greenfield redesign.\n2. Planner writes a thin acceptance list (tests + curl).\n3. Worker implements behind feature flags; one PR-sized slice.\n4. Reviewer focuses on contracts/errors; advisor only on cross-service risk.\n5. Stop when acceptance tests pass; escalate early if schema migration is required.",
+        "childContext": "BE value child guardrails: do not touch frontend; prefer existing patterns; document migration needs instead of applying them.",
+        "members": [
+          { "agent": "scout", "model": "your-provider/value-model", "thinking": "high" },
+          { "agent": "planner", "model": "your-provider/strong-model", "thinking": "xhigh" },
+          { "agent": "worker", "model": "your-provider/value-model", "thinking": "xhigh" },
+          { "agent": "reviewer", "model": "your-provider/value-model", "thinking": "max" },
+          { "agent": "advisor", "model": "your-provider/strong-model", "thinking": "xhigh" },
+          "centurion"
+        ]
+      },
       "fe-value": {
-        "description": "Frontend · standard projects",
+        "description": "Frontend · standard projects (roster only — context falls back to global)",
         "members": [
           { "agent": "scout", "model": "your-provider/value-model", "thinking": "high" },
           { "agent": "prototype", "model": "your-provider/value-model", "thinking": "high" },
@@ -38,6 +59,8 @@ model is required by these templates.
       },
       "be-premium": {
         "description": "Backend · complex projects",
+        "parentContext": false,
+        "childContext": "@be-premium-child.md",
         "members": [
           { "agent": "scout", "model": "your-provider/strong-model", "thinking": "high" },
           { "agent": "planner", "model": "your-provider/strong-model", "thinking": "max" },
@@ -46,23 +69,23 @@ model is required by these templates.
           { "agent": "advisor", "model": "your-provider/strong-model", "thinking": "xhigh" },
           "centurion"
         ]
-      },
-      "be-value": {
-        "description": "Backend · standard projects",
-        "members": [
-          { "agent": "scout", "model": "your-provider/value-model", "thinking": "high" },
-          { "agent": "planner", "model": "your-provider/strong-model", "thinking": "xhigh" },
-          { "agent": "worker", "model": "your-provider/value-model", "thinking": "xhigh" },
-          { "agent": "reviewer", "model": "your-provider/value-model", "thinking": "max" },
-          { "agent": "advisor", "model": "your-provider/strong-model", "thinking": "xhigh" },
-          "centurion"
-        ]
       }
     }
   }
 }
 ```
 
+Notes on the examples:
+
+- **`fe-premium` vs `be-value`**: different parent/child workflow text so
+  switching `subagents.team` / `PI_SUBAGENTS_TEAM` changes operating
+  discipline, not only the roster/models.
+- **`fe-value`**: omits team context → falls back to global
+  `parentContext` / `childContext` (or convention files).
+- **`be-premium`**: `parentContext: false` disables parent injection for that
+  team (no fallthrough to global). `childContext: "@be-premium-child.md"` is
+  resolved relative to the settings file that declares the team.
+
 Each team's `description` and `members` shape follows
 `subagents.teams.<name>`. Member objects apply their own `model` and
 `thinking` values to that role in this team; those values override the same
@@ -73,4 +96,18 @@ plain roster entry with no member-level override.
 To make one team the settings default, add a sibling `"team": "be-value"`
 under `"subagents"`. `PI_SUBAGENTS_TEAM` takes precedence over that configured
 `subagents.team` value when selecting the team. See the README's [Team
-配置](../README.md#team-配置) section for the selection and override semantics.
+配置](../README.md#team-配置) section for the selection, context resolve order,
+and override semantics.
+
+## spawnMode (rpc | inprocess)
+
+Omitted → `inprocess`, with an automatic `rpc` fallback when the resolved spawn
+needs an OS worktree (`worktree: true`, the writer/centurion default). A
+non-`pi` role is rejected before this point, so it never reaches the fallback.
+An explicit `spawnMode: "inprocess"` + `worktree: true` is
+still refused with `INVALID_PARAMS`. Precedence: frontmatter →
+`subagents.agentOverrides.<role>` → team member override.
+
+See [inprocess-supervisor.md](./inprocess-supervisor.md) (#197) for the backend
+details, the separate `subagents.inprocess.*` limits, and the
+AsyncLocalStorage identity channel.

package/docs/tui-qa-playbook.md

@@ -0,0 +1,284 @@
+# TUI 缺陷狩猎手册（QA playbook）
+
+> **给谁看**：任何要在本仓库做「视觉/交互验证」的 agent 或人。读完即可执行。
+>
+> **为什么有这份文档**：`CONTRIBUTING.md` 只覆盖 `typecheck` / `test` / `test:docker`，而本仓库有冻结的 TUI 契约（`docs/tui-viewer-contract.md`），其验收项（T1 渲染对齐主上下文、T5 follow-end、T12 流式去重）本质是**渲染与交互**断言，无法用普通单测覆盖。本手册补上这一段：如何在容器里跑真实 TUI、如何截图取证、如何造确定性复现、如何把发现变成 issue。多 agent 整轮狩猎的编排见 `docs/qa-hunting-round.md`。
+
+---
+
+## 0. 核心原则：三层证据链
+
+**每个缺陷必须有这三层，缺一层就别报。**
+
+| 层 | 目的 | 手段 |
+| --- | --- | --- |
+| ① 纯函数最小复现 | 精确定位，无需环境 | `node --experimental-strip-types` 直调被测函数 |
+| ② 无头端到端 | 证明真实调用路径可达 | 直驱组件 / registry / orchestrator（不起 TUI） |
+| ③ TUI 截图/帧 | 证明用户可见 | tmux 捕获 ANSI → 渲染 PNG 给我看 |
+
+**只做 ③ 会误报**（把测试环境噪声当产品缺陷）。**只做 ① 会漏报**（函数本身正确但调用方错）。
+
+**无视觉能力时**：如果你的模型看不了图，以明文帧/码点断言为准（见 §3 铁律 1），PNG 只作为附给有视觉能力的会话/人的辅助证据。不要因为"看不了图"就跳过第 ③ 层——明文帧同样能证明用户可见性。
+
+---
+
+## 1. 基建：容器 + 可脚本化 LLM
+
+### 1.1 为什么必须容器化
+
+- TUI 渲染依赖终端宽度/高度，本地终端不可控；容器里可精确设 `tmux -x <cols> -y <rows>`。
+- 本仓库改 TUI 行为会动 `ctx.ui.custom()`；容器快照可重建。
+
+### 1.2 用仓库自带的 mock LLM（已存在，别自造）
+
+`test/mock-llm/` 已是**可脚本化的 OpenAI 兼容端点**（`npm run mock-llm`，默认 `:8765`，scenario 可选，见 `test/mock-llm/README.md` 的 `MOCK_LLM_SCENARIO=spawn-scout`）。
+
+- 模型名固定为 `--provider mock --model flash --thinking off`（`writeMockPiHome` 已把 provider 配好，dummy key 恒为 `mock`）。
+- 驱动指令用 `MOCK_SAY: <text>` 等 inline directives（README「Inline directives」一节）。
+
+### 1.3 端口纪律（血泪）
+
+**永远用随机端口**，不要硬编码 `8765`：旧进程残留会静默串台，产物看起来干净但跑的是错的 scenario。
+
+```bash
+PORT=$(python3 -c 'import socket,random
+for _ in range(300):
+    p=random.randint(20000,29999); s=socket.socket()
+    try: s.bind(("127.0.0.1",p)); s.close(); print(p); break
+    except OSError: s.close()')
+# 起 mock 后必须等就绪再启动 pi
+for _ in $(seq 1 40); do curl -sf -m2 "http://127.0.0.1:$PORT/v1/models" >/dev/null && break; sleep 0.5; done
+```
+
+**禁止 `pkill -f mock-llm`**（会匹配到自己的 shell 把自己杀掉）。用：
+
+```bash
+ps -eo pid,cmd | grep "[m]ock-llm" | awk '{print $1}' | xargs -r kill -9
+```
+
+### 1.4 tmux 捕获（本仓库尚缺的一环）
+
+`test/docker/` 已有容器基建；需要补一个 tmux 捕获步骤拿到真像素。建议新增 `test/docker/verify-tui-visual.sh`（**当前尚未落库，见 §11 状态表**）：
+
+```bash
+# 在容器内
+tmux new-session -d -s qa -x 120 -y 40
+tmux send-keys -t qa "HOME=$PIHOME TERM=xterm-256color pi --provider mock --model flash --thinking off" C-m
+sleep 12
+tmux capture-pane -p -t qa -e > /tmp/frame.ansi
+python3 /opt/tui/ansi2png.py /tmp/frame.ansi /tmp/frame.png --cols 120
+```
+
+渲染注意：然后交给宿主渲染成 PNG（镜像内置 `test/tui/ansi2png.py`，PIL 逐单元格）：
+
+- **不要用 ImageMagick 的 Pango**——它吞掉嵌套 `foreground` 颜色，会让颜色类取证失真。
+- **渲染器必须支持 CJK 字体回退**，否则中文渲染成方框，**会掩盖 CJK 宽度/溢出缺陷本身**。
+
+---
+
+## 2. 执行循环
+
+```bash
+# 1) 起隔离 home + 随机端口 mock（见 §10 快速开始）
+# 2) tmux 起 pi，按场景送键
+# 3) 每步 capture-pane，需要时渲染 PNG 核对渲染与交互
+```
+
+**等待要基于"渲染稳定"而不是拍脑袋 sleep**。推荐 capture-until-stable：连续两次捕获（间隔 ≥1s）diff 为空才算渲染完成，再送下一键。
+
+```bash
+# capture-until-stable：稳定才返回，最多等 30s
+stable() {
+  local prev="" cur=""
+  for _ in $(seq 1 30); do
+    sleep 1
+    cur=$(tmux capture-pane -p -t qa -e)
+    [ "$cur" = "$prev" ] && { printf '%s' "$cur"; return 0; }
+    prev="$cur"
+  done
+  printf '%s' "$cur"; return 1   # 超时：视为异常，记录后处理
+}
+```
+
+连续送键不给渲染周期 = 误判为缺陷（曾把连按两次 Esc 判成"面板没关"，其实是时序太快；放慢后正确：Esc 从详情→列表→关闭）。
+
+tmux 特有的坑：
+
+- `send-keys Escape` 与后续按键之间同样要等稳定，tmux 不做合并。
+- `tmux -x 120 -y 40` 是**初始**尺寸；若程序随后收到 resize 事件（如进入备用屏幕），以程序日志/探测输出里的实际宽高为准，别假设仍是 120×40。
+
+---
+
+## 3. 铁律（踩过的坑，别再犯）
+
+1. **先读明文再读图**。低分辨率下 `▶`(U+25B6) 会被误读成 `◀`，差点误报。下结论前先 `sed 's/\x1b\[[0-9;]*m//g'` 看明文或查码点。
+2. **区分环境噪声 vs 产品缺陷**。截图里的 `â`/`Ã` 是 xterm 没开 UTF-8（用 `-u8` + `LANG=C.utf8`）；root 绕过权限位（`chmod 500` 仍可写）。都不是产品问题。
+3. **工具执行要查请求日志/产物，不能只看回复**。模型完全可能回复"I started the task"却没调用工具。判据：`mock` 请求数 + 产物文件存在。
+4. **报之前先查重**。先 `gh issue list --search <关键词>` 确认没报过，再在当前 main 上复跑最小复现确认缺陷仍在（§9 列的类别尤甚，可能已修）。
+
+---
+
+## 4. 判定标准（报不报）
+
+| 报 issue | 只记录 |
+| --- | --- |
+| 可复现的功能/数据/安全缺陷 | 理论风险（无法复现） |
+| 契约明文与实现不符 | 契约未规定的设计取舍 |
+| API 语义误导 | 低价值打磨 |
+| 跨面口径不一致（同一数据多解释） | 环境限制导致的观察 |
+
+**必须能复现才报。** 不可复现的一律降级为"记录为风险"。
+
+怀疑回归类缺陷时，加一步**负向对照**：在已知 good commit（`git log` 找缺陷引入前的版本）上跑同样步骤。以前没有 → 新回归（更紧急）；以前也有 → 一直如此的设计，回到 §4 表格判定。
+
+---
+
+## 5. 高 ROI 角度（按序）
+
+1. **跨面口径一致**：同一数据在多处（tree / viewer / status）是否同口径。
+2. **契约 vs 实现逐条对照**：把冻结契约（如 `tui-viewer-contract.md` 的 T1–T13）grep 出来逐条验证。
+3. **单位混淆**：字节/码点/显示宽度。
+4. **配置边界**：每个 env 变量试 `""`/`0`/`-1`/`NaN`/`Infinity`/浮点。
+5. **UI 状态模型**：滚动/过滤/选中是否有统一模型。
+
+---
+
+## 6. 写 issue 的结构（接 CONTRIBUTING 的 "Issues first"）
+
+CONTRIBUTING 要求 issue 含 repro / 期望 / 实际 / 环境（Node / OS / pi-legion 版本）。渲染类 issue 再加一段：
+
+```markdown
+## Summary
+一句话说清症状 + 影响。
+## Severity
+critical / major / minor + 一句理由（维护者据此分诊，49 个 issue 没有分级无法排优先级）。
+## Where
+精确到 `file:line` + 关键代码。
+## Reproduction
+**实测输出**（不是"应该看到什么"）。贴 `tmux capture-pane / strings / ps` 的真实结果。
+最小复现脚本路径（见 §7 产物落库，随 issue 提交或附 PR）。
+## Through the TUI
+渲染/交互问题附帧内容（明文或 PNG）。
+## Impact
+为什么值得修（用户/模型/数据视角）。
+## Environment
+pi-legion 版本、Node、终端尺寸、容器/宿主、mock scenario。
+```
+
+---
+
+## 7. 产物落库（不要只写 /tmp）
+
+容器一销毁，`/tmp` 里的帧/PNG/脚本全丢——issue 里的证据链就断了。每个发现固定一个产物目录：
+
+```text
+test/tui/artifacts/<YYYYMMDD>-<issue-slug>/
+  ├─ frame.ansi      # 关键帧（capture-pane -e 原始输出）
+  ├─ repro.mjs       # ① 层最小复现脚本，node repro.mjs 直接跑
+  ├─ frame.png       # 可选，渲染后的取证图
+  └─ notes.md        # 复现步骤、码点分析、结论
+```
+
+- issue 的 Reproduction 一节引用上述相对路径；修复 PR 把 `repro.mjs` 转成正式回归测试（先失败再修，见 §8）。
+- 如果产物含敏感路径/密钥，写之前先检查（CONTRIBUTING：never commit real keys）。
+
+---
+
+## 8. 与 CONTRIBUTING 的衔接
+
+- 本手册产出的 issue 走同一流程：issue → 一个 PR 一个 concern → draft → Ready for review（`ci` 绿）。
+- 修复时按 CONTRIBUTING 的回归测试要求：**先失败测试，再生产代码**。本手册的三层证据天然提供了测试用例（`repro.mjs` → 测试）。
+- 涉及 `src/tui/` 的改动，务必跑 `npm run test:integration`（`FakeSupervisor`），因为本手册发现的多数缺陷是「调用方错」而非「组件错」——单测覆盖不到。
+
+---
+
+## 9. 已验证的生效案例（pi-async，49 issues）
+
+本方法论在 `zzjcool/pi-async` 上跑通，产出 49 个 issue。代表性几类：
+
+- **渲染层**：`rail` 未剥离裸 C0（`\x07`/`\x08`/`\x0c`）——控制字符破坏布局（可复现最小用例 + TUI 帧）。
+- **宽度单位**：截断按**码点**而非显示宽度 → CJK/emoji 溢出挤掉 `elapsed` 字段。
+- **状态语义**：`sync + abort` 返回 `mode:"sync"` + `status:"running"` 自相矛盾（作者的测试已断言 `status:"running"` 是设计意图，`mode` 才是缺陷——**先读测试再报**）。
+- **安全**：正则缺 `m` flag → 契约建议的锚定 `^READY$` **永不匹配**；且 **JS 无内联 `?m`**（我最初的 workaround 错了，已更正）
+- **架构根因**：4 组概念 9 份副本（`stripAnsi`×2、duration×2、env×3、width×2），由并行开发计划解释，直接产生 4 组缺陷。合并为共享助手可关闭整类。
+
+**关键教训**：建议（修复方案/workaround）**必须先跑一遍**再写进 issue。我曾把 `(?m)` 当 workaround 写进去，而 JS 正则不支持内联 flag——差点误导维护者。
+
+---
+
+## 10. 快速开始（复制即用）
+
+```bash
+# ── 0. 随机端口起 mock ──────────────────────────────
+PORT=$(python3 -c 'import socket,random
+for _ in range(300):
+    p=random.randint(20000,29999); s=socket.socket()
+    try: s.bind(("127.0.0.1",p)); s.close(); print(p); break
+    except OSError: s.close()')
+MOCK_LLM_SCENARIO=spawn-scout npm run mock-llm -- --port "$PORT" &
+for _ in $(seq 1 40); do curl -sf -m2 "http://127.0.0.1:$PORT/v1/models" >/dev/null && break; sleep 0.5; done
+
+# ── 1. 生成隔离 pi home（打印路径，后续要用）──────────
+PIHOME=$(node --experimental-strip-types -e '
+import { writeMockPiHome } from "./test/mock-llm/index.ts";
+import { mkdtempSync } from "node:fs"; import { tmpdir } from "node:os";
+const dir = mkdtempSync(`${tmpdir()}/qa-`);
+writeMockPiHome({ dir, baseUrl: `http://127.0.0.1:${process.env.PORT}/v1` });
+console.log(dir);
+')
+echo "PIHOME=$PIHOME"
+
+# ── 2. tmux 起 pi ────────────────────────────────────
+tmux new-session -d -s qa -x 120 -y 40
+tmux send-keys -t qa "HOME=$PIHOME TERM=xterm-256color PI_CODING_AGENT_DIR=$PIHOME pi --provider mock --model flash --thinking off" C-m
+# 等启动稳定（连续两帧相同，见 §2 stable()）
+sleep 12; tmux capture-pane -p -t qa -e > /tmp/boot.ansi
+
+# ── 3. 交互 + 捕获 ───────────────────────────────────
+tmux send-keys -t qa "MOCK_SAY: hello" C-m
+sleep 2
+tmux capture-pane -p -t qa -e > /tmp/frame.ansi
+# 渲染 PNG（ansi2png.py 尚未落库，见 §11 状态表）
+# python3 test/tui/ansi2png.py /tmp/frame.ansi /tmp/frame.png --cols 120
+
+# ── 4. 清理 ─────────────────────────────────────────
+tmux kill-session -t qa
+ps -eo pid,cmd | grep "[m]ock-llm" | awk '{print $1}' | xargs -r kill -9
+```
+
+---
+
+## 11. 维护
+
+### 基建状态表（改一处，同步此处）
+
+| 资产 | 位置 | 状态 |
+| --- | --- | --- |
+| 脚本化 mock LLM | `test/mock-llm/` | ✅ 已有 |
+| 隔离 pi home | `writeMockPiHome({ dir, baseUrl })` | ✅ 已有 |
+| 沙箱镜像 | `ghcr.io/zzjcool/pi-legion/tui-sandbox`（Dockerfile: `test/docker/Dockerfile.tui-sandbox`，CI 自动发布） | ✅ 已有 |
+| tmux 捕获 harness | `test/docker/verify-tui-visual.sh`（`npm run test:tui-visual` 一键跑） | ✅ 已有 |
+| ANSI→PNG 渲染器 | `test/tui/ansi2png.py`（镜像内置 `/opt/tui/`） | ✅ 已有 |
+| 容器基建 | `test/docker/` | ✅ 已有 |
+| 冻结契约 | `docs/tui-viewer-contract.md` | ✅ 已有 |
+
+镜像发布：push 到 master 且上述文件变更时 CI 自动构建推送（`.github/workflows/docker-tui-sandbox.yml`）；本地修改 Dockerfile 后想立即验证可直接 `npm run test:tui-visual`（本地 build，无需 push）。要手动 push 需要 `write:packages` scope 的 token（`gh auth token` 默认没有）：`echo <TOKEN> | docker login ghcr.io -u zzjcool --password-stdin && docker push ghcr.io/zzjcool/pi-legion/tui-sandbox:latest`。
+
+证据产物（`test/tui/artifacts/`）已 gitignore，不进仓库；issue 里引用时贴关键帧明文/PNG 内容而非路径。
+
+### 其他维护项
+
+- 新增 tmux 捕获脚本后，把它纳入 `npm run test:docker`（或单独 `test:tui-visual`，**不进必需 `ci`**，因为依赖容器与像素）——已落 `test:tui-visual`，同样不进 `ci`。
+- 每次发现新的"陷阱"（环境噪声/判定边界）补进 §3/§4。
+- 渲染器与 harness 保持单一实现，**不要 sed 派生副本**（派生副本会与主版本漂移）。
+
+---
+
+## 12. 停止条件（防止无限狩猎）
+
+开放式狩猎没有自然终点，agent 必须主动收尾：
+
+- **角度穷尽即停**：§5 五个角度各跑完一轮后收尾，不要在同一角度反复深挖。
+- **零发现止损**：连续 2 个角度零新发现（查重后），提前结束本轮。
+- **时间预算**：单轮狩猎建议 ≤60 分钟容器时间；超时把已完成的部分按 §7 落库，未跑完的角度写进 notes.md 留给下一轮。
+- **发现量上限**：单轮报 ≤10 个 issue（pi-async 一轮 49 个已属极限，多数维护者一次消化不了）；超出部分落库为 notes.md 里的 candidate 列表，下轮先查重再升级为 issue。