pi-legion 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Published GitHub Release notes remain available at
+https://github.com/zzjcool/pi-legion/releases — this file is the in-repo
+summary so you can see **2.x vs 0.16** without leaving the tree.
+
+## [Unreleased]
+
+### Fixed
+
+- Dispatched children now receive `--provider` pinned from the parent's model
+  registry, so a bare model id (`workbuddy/…`) that also exists under a static
+  auth-less provider in `models.json` can no longer hijack the child start
+  (`No API key found for …`) (#123).
+- Scout-guard now counts first-class `grep` / `find` / `ls` tool calls as reads (#87).
+- Doctor diagnose help no longer repeats itself; storage section shows hygiene sweep state (#86).
+- Bundled roles no longer advertise unloaded `lens_*` tools (#75).
+- Non-interactive `pi --print` waits for async children before cascade retire (#77).
+- Roles load `builtin:codemode`; doctor diagnose shows a dedicated section (#89 / #90 → #93).
+- Doctor role-tool→extension gates are data-driven / extensible (#97 / #99).
+- Launch honors `name=` so `/legion status <name>` matches the railway label (#101 / #104).
+- Galaxy legend shows failed/retired glyphs only when those states are present (#102 / #103).
+- Live child status leads with `alive · quiet Ns`; long quiet emphasizes living over a stale execution snapshot (#81 / #92 / #105).
+- npm `package.json` description/keywords aligned with Legion 2.x RPC (no Herdr panes) (#106 / #111).
+
+### Added
+
+- `/legion status` human-readable summary; doctor slash list covers team / agents / on|off / summary (#76).
+- README documents scout-guard settings and `/scout-guard` / `/no-scout-guard` (#74 / #71).
+- Scout-guard mock-llm e2e: notify ×1, cooldown, and dispatch clear (#108 / #113).
+
+### Changed
+
+- Prefer `PI_LEGION_EXTRA_AGENT_DIRS` over legacy `PI_HERDR_SUBAGENTS_*` (alias; new name wins if both set) (#109 / #114).
+- CONTRIBUTING/CI docs aligned with 2.x RPC; verify-12/13 paths point at `test/legacy/docker/` (#95 / #100, #107 / #112).
+- README: remove duplicate Child extensions heading (#94 / #98).
+- `design.md` historical banner; landed F38–F46 marked ✅ / Historical (#80 / #83 → #91).
+- CI PR job runs `test:integration` (#79 / #88).
+
+## [2.0.0] - 2026-10-14
+
+First **Pi Legion** line on headless Pi RPC. Relative to the final Herdr-era
+**0.16.x** packages, this is a breaking transport and packaging change.
+
+### Breaking
+
+- **RPC-only transport:** children run as headless `pi --mode rpc` processes
+  under `LegionSupervisor`. Herdr pane execution is archived under
+  `src/backends/legacy/` and is **not** a v2 runtime option.
+- **Kinds:** only `kind: pi` is supported. Migrate non-Pi roles or stay on
+  `pi-legion@0.16.x`.
+- **Shared tree ledger:** squad state lives in SQLite WAL `legion.db` (phases,
+  mail, resume), not pane-centric session bookkeeping alone.
+- Bundled agent playbooks aligned with local RPC practice (#66).
+
+### Added
+
+- Recursive centurion trees, four-phase
+  planning / implementing / reviewing / verifying machine, `legion_mail`,
+  three-layer `/legion` UI (resident tree, full view, live overlay), railway
+  strip, tok/s / galaxy / log panels.
+- Scout-guard: remind the main session after a streak of read-class tools (#64).
+- Storage hygiene sweep on startup: prune idle runs, orphan temp dirs, abandoned
+  nodes, event retention, WAL checkpoint (#37 / #38 / #40 → #47).
+- `/legion doctor` (+ diagnose) self-check; auto-doctor snippets on gated spawn
+  failures (#52).
+- Child memory gate (`NODE_OPTIONS` V8 flags, pre-spawn gate) and tree-wide
+  verify concurrency limit (#50).
+- Children default to `--no-extensions` with explicit/role escape hatches (#43 / #48).
+- User stop controls for async children (`/legion stop`, idle Esc, `x` in view) (#41).
+- Mock LLM server for offline pi / legion smoke (`test/mock-llm`, #54 / #56).
+- GitHub Actions CI (typecheck + unit + integration) and stage-only npm publish
+  on tag (#65 / #68).
+- Project workflow docs in CONTRIBUTING (#69).
+
+### Changed
+
+- Slash commands consolidated under `/legion` (#57).
+- Status bar shows current-turn elapsed beside lifetime total (#62).
+- tok/s uses output tokens / generationMs (decode throughput) (#61).
+
+### Fixed
+
+- Railway: pin live spawn verticals when the strip scrolls left (#67); retire /
+  downward spawn connector regressions (#46).
+- Live worker no longer marked retired on a transient Connection blip (#63).
+- Session JSONL streamed + incrementally parsed (no full-file `readFileSync`) (#36 / #45).
+- Per-stream child output byte cap; kill on overflow (#35 / #44).
+- Bun SQLite `.get()` null treated as miss on root insert (#53).
+- Vexillatio sibling naming scoped to the current parent (#42 / #51).
+
+### Security / robustness (design.md F38–F46, already on master)
+
+- Model-scope globs use non-RegExp matching (ReDoS).
+- Session create uses `writeFileSync` with `wx` (no fd leak / TOCTOU).
+- Session decode swallows scalar JSON lines as torn.
+- `tasks[]` / blank task validated before launch.
+- Per-agent `timeoutMs`, pending criteria, nested YAML acceptance parsing;
+  `UNENFORCED_FIELDS` empty.
+
+## [0.16.x] - Herdr-era (final)
+
+Last line that runs children in Herdr panes. Not developed further on this
+branch — pin `pi-legion@0.16.x` if you still need that model. See
+[Herdr transition](README.md#herdr-transition-and-role-migration) in the README.
+
+Earlier 0.11–0.15 history (including the `pi-herdr-swarm` /
+`@zzjcool/pi-herdr-subagents` renames) lives in git tags and older Releases.
+
+[Unreleased]: https://github.com/zzjcool/pi-legion/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/zzjcool/pi-legion/releases/tag/v2.0.0
+[0.16.x]: https://github.com/zzjcool/pi-legion/releases

package/CONTRIBUTING.md

@@ -23,8 +23,14 @@ directly to `master`. Implementers do not merge their own pull requests.
 ```bash
 npm run typecheck
 npm test
+npm run test:integration   # or npm run test:all
 ```
 
+The required GitHub Actions check `ci` runs typecheck, unit, integration, and
+mock-llm. Run `npm run test:integration` (or `npm run test:all`) locally
+before you push, especially when the change touches `src/runs/`, `src/legion/`,
+or `src/extension/runtime.ts`.
+
 Add the unit tests the change needs. Prefer **TDD** (see [Checks](#checks)):
 a failing test in `test/unit` or `test/integration` first, then the production
 code.
@@ -59,20 +65,36 @@ there is no compile step to ship).
 
 ## Checks
 
+The required GitHub Actions check `ci` (`.github/workflows/ci.yml`, on pull
+requests and pushes to `master`) runs, in order:
+
+1. `npm run typecheck`
+2. `npm test` (unit)
+3. `npm run test:integration`
+4. `npm run test:mock-llm`
+
+A failing integration step fails `ci`, so nesting and orchestrator regressions
+are blocked before merge. `test:live` and `test:docker` stay out of that job.
+
 ```bash
 npm run typecheck
 npm test                 # test/unit/*.test.ts
-npm run test:integration # fake herdr, no live binary
+npm run test:integration # FakeSupervisor / nested fakes; no live `pi` binary
 npm run test:all         # typecheck + unit + integration
+npm run test:mock-llm    # also part of the required ci check
 ```
 
-`npm run test:live` talks to a real herdr. It skips itself unless `HERDR_ENV=1`
-and `herdr` is on `PATH`. Do not fail CI on it.
+`npm run test:live` is a **pi RPC live** smoke (`test/live/rpc-live.test.ts`).
+It skips itself when the `pi` binary is missing from `PATH` (see the probe at
+the top of that file). Do not fail CI on it.
 
 Prefer **TDD** for behaviour changes: a failing test in `test/unit` or
 `test/integration` first, then the production code. Integration tests should
-go through `createHerdrClient(createFakeRunner(fake))` so argv construction
-and JSON parsing stay covered.
+drive the orchestrator through `FakeSupervisor` (`test/helpers/fake-supervisor.ts`)
+so nesting / launch / collect stay covered without a live `pi`. The herdr-era
+helpers `createHerdrClient` / `createFakeRunner` remain as **deprecated legacy**
+exports (see `src/api.ts` and `test/legacy/`); use them only when touching the
+archived Herdr backend.
 
 ## Mock LLM
 
@@ -91,16 +113,20 @@ dummy key is always the literal `mock`.
 
 ## Docker verification
 
-`test/docker/` runs the package inside `pi-herdr-sandbox:latest` with a copy
-of the **host** Pi config (`~/.pi/agent/settings.json`, `models.json`,
-`auth.json` if present). The copy is disposable (`/tmp/pi-herdr-docker-home`
-by default); the container cannot write back to your real `~/.pi`.
+`test/docker/` runs the package inside the RPC / pi-legion sandbox image.
+Default image and staging path names are **historical** (`pi-herdr-sandbox:latest`,
+`/tmp/pi-herdr-docker-home`; override with `PI_DOCKER_IMAGE` / `DOCKER_PI_HOME`).
+Content is the 2.x RPC sandbox, not a live herdr pane host. The scripts copy
+the **host** Pi config (`~/.pi/agent/settings.json`, `models.json`, `auth.json`
+if present) into that disposable home; the container cannot write back to your
+real `~/.pi`.
 
 ```bash
-# image must already exist
+# image must already exist (historical default name; do not rename a local tag
+# just to match docs — override with PI_DOCKER_IMAGE if yours differs)
 docker image inspect pi-herdr-sandbox:latest >/dev/null
 
-bash test/docker/verify-1-child-guard.sh      # child herdr interceptor
+bash test/docker/verify-1-child-guard.sh      # RPC child-guard / ledger block
 bash test/docker/verify-2-task-appendix.sh    # frozen task appendix
 bash test/docker/verify-3-readonly.sh         # read-only bash denylist
 bash test/docker/verify-4-acceptance.sh       # collect → verified
@@ -111,19 +137,26 @@ bash test/docker/verify-8-verify-command.sh   # criterion.command + timeout
 bash test/docker/verify-9-worktree.sh         # git worktree cwd
 bash test/docker/verify-10-fallback.sh        # fallbackModels
 bash test/docker/verify-11-nested-alias.sh    # nested + alias + completionGuard
-bash test/docker/verify-12-workspace.sh       # pi install + child pinned to parent Space
-bash test/docker/verify-13-kinds.sh           # kind/model matrix; live CodeBuddy when mounted
 ```
 
-Or all at once:
+Or all at once (RPC mainline **1–11** only):
 
 ```bash
 npm run test:docker
 ```
 
-`verify-13-kinds.sh` is **not** in `npm run test:docker`: it bind-mounts host
-`codebuddy` / `cursor-agent` and (unless `LIVE_KIND_PROBES=0`) calls live
-CodeBuddy. The numbered 1–12 scripts stay offline/mock.
+**Legacy Herdr / Space / kind checks** live under `test/legacy/docker/` (need
+pi-legion **0.16.x** Herdr-era setup). They are **not** part of
+`npm run test:docker`:
+
+```bash
+bash test/legacy/docker/verify-12-workspace.sh  # Herdr Space pin (legacy)
+bash test/legacy/docker/verify-13-kinds.sh      # kind/model matrix; live CodeBuddy when mounted
+```
+
+`verify-13-kinds.sh` also bind-mounts host `codebuddy` / `cursor-agent` and
+(unless `LIVE_KIND_PROBES=0`) calls live CodeBuddy. The numbered 1–11 scripts
+under `test/docker/` stay offline/mock.
 
 Override paths with `HOST_PI_AGENT`, `DOCKER_PI_HOME`, `PI_DOCKER_IMAGE`.
 
@@ -145,7 +178,7 @@ them by hand.
 | `src/runs/acceptance.ts` | `verification-output` command |
 | `test/mock-llm/` | Scriptable OpenAI mock for offline pi / legion |
 | `agents/*.md` | bundled roles |
-| `docs/design.md` | measured herdr findings (F1–F46) |
+| `docs/design.md` | design notes / F1–F46 (incl. historical herdr-era measurements; see file banner) |
 | `README.md` | what is actually wired today |
 
 Do not import from `src/` in downstream packages — use

package/README.md

@@ -14,6 +14,8 @@ shared SQLite ledger records the whole tree.
 > `@zzjcool/pi-herdr-subagents` (through 0.14.3; renamed after an npm name
 > collision), then as `pi-herdr-swarm` (0.15.0), before becoming `pi-legion`
 > in 0.16.0. **2.0.0: the legion era — recursive centurion tree on pi RPC transport; herdr pane execution archived to legacy**
+>
+> **What changed in 2.x?** See [CHANGELOG.md](CHANGELOG.md) (Keep a Changelog). Published notes also land on [GitHub Releases](https://github.com/zzjcool/pi-legion/releases).
 
 ## Contents
 
@@ -22,10 +24,12 @@ shared SQLite ledger records the whole tree.
 - [Legion tools and phases](#legion-tools-and-phases)
 - [Three-layer visualization](#three-layer-visualization)
 - [Settings and budget gates](#settings-and-budget-gates)
+- [Scout guard](#scout-guard)
 - [Team 配置](#team-配置)
 - [Parent/child context conventions](#parentchild-context-conventions)
 - [Delivery and resume](#delivery-and-resume)
 - [Herdr transition and role migration](#herdr-transition-and-role-migration)
+- [Changelog](CHANGELOG.md)
 - [Development](#development)
 
 ## Architecture
@@ -87,12 +91,22 @@ subagent({ agent: "scout", task: "Map the export code path and report relevant f
 
 No manual child-process launch is needed. Use `/legion` to inspect the tree;
 see [Three-layer visualization](#three-layer-visualization) for navigation.
+`/legion status` prints that tree in the chat, and `/legion status <name>`
+prints one node — see [Status](#status-legion-status).
 
 The `subagent` control actions include event-driven `wait` and graceful `stop`:
 `subagent({ action: "wait", name: "worker-0" })` returns as soon as the child
 settles (or the parent turn is interrupted with Esc). Aborting a parent turn
 with Esc gracefully retires its tracked children, including those being waited
-on or collected; the cascade is silent. To stop children explicitly, use
+on or collected; the cascade is silent. Launch stays async by default. Under
+`pi --print` or JSON mode the process would otherwise exit at the end of the
+parent turn and retire those children before they write an assistant message.
+That shutdown waits for each live async child to settle, bounded by the
+child's turn timeout, and only then retires whatever is still running. A
+child killed by that shutdown is recorded as aborted because the parent
+session shut down, not because the model produced no reply. To include the
+child's result in the same print turn, call `wait` or `collect` before the
+turn ends, or launch with `async: false`. To stop children explicitly, use
 `subagent({ action: "stop", name: "worker-0" })` or
 `subagent({ action: "stop", all: true })`; this runs the normal graceful-retire
 sequence for each selected child.
@@ -117,6 +131,28 @@ While the main agent is idle and subagents are live, the railway header shows
 a dim `esc stop all · /legion stop [name]` hint (shortened on narrow terminals,
 hidden while the main agent is working).
 
+### Status (`/legion status`)
+
+The railway and `/legion` view are TUI surfaces. `/legion status` is the chat
+snapshot of the same tree:
+
+- `/legion status` prints every node with the same lines as `legion_tree`
+  (`id role=… status=… phase=… model=… depth=…`), plus a count of each status.
+  Live jobs that are not in the tree yet are listed under that summary.
+- `/legion status <name>` prints one node with the same text as
+  `subagent({ action: "status", name })`. Living children lead with
+  `alive · quiet Ns` (session JSONL mtime); after ~30s of silence the line
+  becomes `alive · quiet Ns (living)` so 「活着但安静」is obvious. Run-store
+  execution/acceptance fields are labeled snapshots, and collect-deadline /
+  transient-connection reasons are omitted from the snapshot line while the
+  child is alive so they do not steal attention from quiet age. A ledger-only
+  node still uses the same renderer with the fields the tree has.
+- Quiet age is not a heartbeat: there is no child-side progress ping. Minutes
+  of silence can still mean the model is reasoning (especially high-thinking
+  turns). Quiet alone does not mean the child is stuck; pair it with `alive`.
+- Both forms work outside the TUI. A short name that matches more than one
+  node needs the full node id (`/legion status <node-id>`).
+
 ## Legion tools and phases
 
 Child nodes receive these tree-aware tools:
@@ -208,6 +244,38 @@ subtree, including itself; when launched by a parent at depth `d`, it inherits
 `C_child = min(C_parent, d + R, 4)` (`R = 1` makes it a leaf), so it can tighten
 the inherited cap but cannot widen it.
 
+### Scout guard
+
+`subagents.scoutGuard` watches the main session. After `threshold` consecutive
+read-like tool calls with no `subagent` launch or `vexillatio` call in
+between, it injects one follow-up reminder and then waits out `cooldownMs`.
+It is on by default. Set it in `~/.pi/agent/settings.json` or the project
+`.pi/settings.json`; a project file overrides the same fields from the user
+file.
+
+```json
+{
+  "subagents": {
+    "scoutGuard": {
+      "enabled": true,
+      "threshold": 8,
+      "cooldownMs": 120000
+    }
+  }
+}
+```
+
+| Field | Default | Meaning |
+| --- | ---: | --- |
+| `enabled` | `true` | Count and remind. `false` skips the guard until it is turned back on. |
+| `threshold` | `8` | Consecutive read-like calls before one reminder. Positive integer. |
+| `cooldownMs` | `120000` | Quiet period after a reminder, in milliseconds. Integer ≥ 0. |
+
+`/scout-guard` turns the guard on for this session and `/no-scout-guard`
+turns it off. Both override `enabled` in memory only; settings files stay
+unchanged. Child sessions do not register these commands. Behavior in full
+is in [docs/design.md §6.4.1](docs/design.md#641-scout-guard-subagentsscoutguard).
+
 ### Team 配置
 
 Use `subagents.team` to select the default named team from `subagents.teams`.
@@ -245,10 +313,11 @@ gate, missing lens tools, orphan temps, …), ask Legion rather than guessing
 same idea as `pi list` / `pi auth check`.
 
 - `/legion doctor` — full report in the chat (works outside TUI too).
-- `/legion doctor <section>` — one of: `summary`, `extensions`, `models`,
+- `/legion doctor [section]` — one of: `summary`, `extensions`, `models`,
   `spawn`, `memory`, `tools`, `storage`, `runtime`, `next`.
 - `subagent({ action: "diagnose" })` — same full report as tool output so the
-  main agent can call it without waiting for you.
+  main agent can call it without waiting for you. The tool has no section
+  field; filter with `/legion doctor [section]`.
 
 The report is structured for the model: each section ends in **Issues** /
 **Next steps** with copy-pasteable fixes (env exports, role frontmatter,
@@ -268,11 +337,10 @@ Coverage:
 | models | Host vs child model lists, which package restores providers, team/roster gaps |
 | spawn | Sample child argv, recent spawn failures + stderr, nested-spawn flags |
 | memory | Free RAM, memory gate, child V8 flags, verify concurrency slots in use |
-| tools | `/legion` commands, stop / idle-Esc / strip hints, tool names |
-| storage | `legion.db` sizes, orphan `rpc-child-*` temps, last hygiene sweep marker |
+| tools | `/legion` slash list (status, team, agents, summary, on/off, scout-guard, doctor, stop), idle-Esc / strip hints, tool names |
+| storage | `legion.db` sizes, orphan `rpc-child-*` temps, effective hygiene limits (default vs env), last sweep marker plus a hint when it is missing or stale |
 | runtime | Live children, tree statuses, acceptance-ish / active nodes |
 
-### Child extensions
 ### Child extensions
 
 Children start with `--no-extensions`, so they do not load the host's
@@ -288,6 +356,20 @@ itself (guard and nested spawning) and every path listed in the role's
 | `PI_LEGION_CHILD_INHERIT_EXTENSIONS=1` | Every child loads all host extensions, as before. |
 | `PI_LEGION_CHILD_EXTENSIONS=/a.ts,/b.ts` | Extra extension paths every child loads explicitly, e.g. a provider extension the child's model needs. |
 
+Bundled planner, reviewer, and worker do not list `lens_*` tools. pi-lens starts an LSP stack (~1 GB per child, #43) and is not part of the default `--no-extensions` child. To give a role those tools, add the tool names to its `tools:` list and point `extensions:` / `subagentOnlyExtensions` (or `PI_LEGION_CHILD_EXTENSIONS`) at the pi-lens extension file. `/legion doctor` reports `ROLE_MISSING_LENS` when a role lists the tools without that path.
+
+### Extra agent directories
+
+PATH-style directories scanned for agent `*.md` definitions. They load as
+user-level, **below** the real user agents dir in precedence (a same-name file
+in `~/.pi/agent/agents` still wins). Useful for hermetic installs (Nix store,
+container, read-only mount).
+
+| Env | Effect |
+| --- | --- |
+| `PI_LEGION_EXTRA_AGENT_DIRS` | Canonical name. Colon-/semicolon-separated absolute dirs (`path.delimiter`). |
+| `PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS` | Deprecated compatibility alias (kept for at least one minor version). If **both** are set, `PI_LEGION_EXTRA_AGENT_DIRS` wins and the legacy value is ignored (one stderr warning). |
+
 ### Child memory controls
 
 | Env | Default | Effect |
@@ -341,7 +423,8 @@ Version **0.16.x is the final Herdr-era line**. Pi Legion 2.x is RPC-only:
 child execution uses headless `pi --mode rpc` processes, and the legacy backend
 is archived under `src/backends/legacy/`, not offered as a v2 runtime option.
 Pin to `pi-legion` 0.16.x if a workflow must stay on the former Herdr-based
-execution model.
+execution model. A short breaking-change summary lives in
+[CHANGELOG.md](CHANGELOG.md#200---2026-10-14).
 
 Pi Legion 2.x supports `kind: pi` only. Migrate a custom role that uses another
 CLI kind by changing its frontmatter, for example:
@@ -385,4 +468,7 @@ Use `writeMockPiHome()` from `test/mock-llm` to generate an isolated
 See [CONTRIBUTING.md](CONTRIBUTING.md#project-workflow) for the project
 workflow: issues, pull requests, the merge gate, and npm releases.
 
+Version history for consumers: [CHANGELOG.md](CHANGELOG.md). Tag-by-tag
+release bodies: [GitHub Releases](https://github.com/zzjcool/pi-legion/releases).
+
 MIT. See [LICENSE](LICENSE).

package/agents/planner.md

@@ -1,7 +1,7 @@
 ---
 name: planner
 description: 规划员：把任务拆成可并行/可验收的实施计划，冻结接口，指定文件归属
-tools: read, grep, find, ls, bash, codemode, lens_diagnostics, symbol_search, project_report, module_report, read_symbol, read_enclosing, pi_lens_activate_tools
+tools: read, grep, find, ls, bash, codemode
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false

package/agents/reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: reviewer
 description: 审查员：只读对抗式审查一个指定范围的改动——对照需求查漏、查正确性与测试覆盖，输出带路径与严重级别的发现
-tools: read, grep, find, ls, bash, codemode, lens_diagnostics, symbol_search, project_report, module_report, read_symbol, read_enclosing, pi_lens_activate_tools
+tools: read, grep, find, ls, bash, codemode
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
@@ -31,9 +31,8 @@ maxSubagentDepth: 1
 
 ## 工具纪律（读代码的正确姿势）
 
-- 你有 pi-lens 工具：看模块结构用 `module_report`，读单个函数/类的完整源码用 `read_symbol`（比 grep 片段读快且省 token），找符号位置用 `symbol_search`，改完的类型/错误检查用 `lens_diagnostics`。
 - `grep`/`find` 工具底层就是 ripgrep/fd，优先于 bash 管道。只在需要管道（如 `git show X | grep`）时才用 bash。
-- **禁止对同一文件碎片化 grep 超过 3 次**——超过说明该用 `module_report`/`read_symbol` 整体看了。
+- **禁止对同一文件碎片化 grep 超过 3 次**——超过就用 `read` 把相关段落整段读完。
 - 多个独立的读操作（批量读文件、批量检查）用 `codemode` 的 `Promise.allSettled` 并行发，不要串行。
 
 ## 先确定范围

package/agents/worker.md

@@ -1,7 +1,7 @@
 ---
 name: worker
 description: 实现者：按冻结计划写代码、跑测试，完成后自报 verdict
-tools: read, edit, write, grep, find, ls, bash, subagent, codemode, lens_diagnostics, symbol_search, project_report, module_report, read_symbol, read_enclosing, pi_lens_activate_tools
+tools: read, edit, write, grep, find, ls, bash, subagent, codemode
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
@@ -27,9 +27,8 @@ maxSubagentDepth: 3
 
 ## 工具纪律（读代码的正确姿势）
 
-- 你有 pi-lens 工具：看模块结构用 `module_report`，读单个函数/类的完整源码用 `read_symbol`（比 grep 片段读快且省 token），找符号位置用 `symbol_search`，改完后对涉及文件跑 `lens_diagnostics` 查类型/错误。
 - `grep`/`find` 工具底层就是 ripgrep/fd，优先于 bash 管道。只在需要管道（如 `git diff | grep`）时才用 bash。
-- **禁止对同一文件碎片化 grep 超过 3 次**——超过说明该用 `module_report`/`read_symbol` 整体看了。
+- **禁止对同一文件碎片化 grep 超过 3 次**——超过就用 `read` 把相关段落整段读完。
 - 多个独立的读操作（批量读文件、批量检查）用 `codemode` 的 `Promise.allSettled` 并行发，不要串行。
 
 ## 职责边界

package/docs/contracts/esc-cascade-v2.md

@@ -57,7 +57,8 @@ vexillatio 工具 execute 也要把 signal 传进来（找到它的 registerTool
 ## 语义边界（不变）
 
 - **stop action 不变**：显式停止仍走全链。
-- **主 pi 正常退出（quit）不变**：session_shutdown 已级联。
+- **主 pi 正常退出（quit）不变**：交互 TUI 的 session_shutdown 仍立即级联 retire。
+- **非交互 print/JSON（#72）**：`ctx.mode` 为 `print` 或 `json` 时，session_shutdown 先等仍活着的 async 子 agent 结算（上限为各子的 turn timeout），再 retire 尚未结束的。避免 `--print` 在首包前把刚 spawn 的子进程记成 `no assistant message for the last prompt`。父会话关机导致的无 assistant abort 原因改为 parent session shutdown，与模型自己没写出 assistant 区分。
 - **SIGKILL/崩溃不覆盖**：孤儿扫描 + resume 语义不变（这是既定接受的风险）。
 - **children 的 children**：retire 链本身递归（孙进程 sweep 在 rpc-supervisor 的 retireChild 里），无需额外处理。
 - **blocked children**：一并 retire（stop 语义一致）。

package/docs/design.md

@@ -1,5 +1,9 @@
 # pi-legion 设计文档
 
+> **⚠️ 历史实验笔记（非现行契约）**  
+> 本文记录 herdr / pane 时代的实测与设计推演。**运行时契约以 [README](../README.md) 与 [CONTRIBUTING](../CONTRIBUTING.md) 为准**（Pi Legion 2.x = headless Pi RPC + `legion.db`；herdr pane 执行已归档到 `src/backends/legacy/`）。  
+> 下文 F 条中标 **✅ landed** 的是已在当前 master 落地的修复；未标注的早期结论仍有参考价值，但不要当作「今日仍坏」的缺口清单。
+
 > 基于 10 组实测实验（exp1–exp10）得出的设计。所有结论都标注了实验依据，
 > 未经验证的假设明确标记为「待验证」。
 
@@ -20,7 +24,7 @@
 
 ### 实现状态（相对本文档）
 
-下面 F 条目里不少写的是「当时的缺口」。当前运行时已经钉死、以 [README](../README.md) 为准：
+下面 F 条目里不少写的是「当时的缺口」（文首 banner 已说明：契约以 README + CONTRIBUTING 为准）。当前运行时已经钉死：
 
 - 子进程强制加载 child-guard：拦 `herdr agent prompt|wait|send-keys|start`、外 pane read、只读角色写操作
 - 任务卡自动附录（禁止 wakeup、必须 `{"ok":…}`）
@@ -654,10 +658,11 @@ system prompt 不再注入 playbook/roster；bash 派发 guard 放行手动 herd
 ### 6.4.1 Scout guard `subagents.scoutGuard`
 
 只在主会话生效（子进程带 `PI_SUBAGENT_ROLE`，不计数、不注入）。连续 N 次
-读类工具调用（`read`，以及可判定为只读的 bash：`cat`/`head`/`tail`/`less`/
-`rg`/`grep`/`find`/`ls`/`stat`/`wc`/`file`/`jq`、`git show|log|diff|status|blame`、
-不带 `-i` 的 `sed`）且中间没有成功的 `subagent` / `vexillatio` 派发时，异步
-注入一条 follow-up 提醒，不挡住当前 `tool_call`。
+读类工具调用（first-class `read`/`grep`/`find`/`ls`，以及可判定为只读的 bash：
+`cat`/`head`/`tail`/`less`/`rg`/`grep`/`find`/`ls`/`stat`/`wc`/`file`/`jq`、
+`git show|log|diff|status|blame`、不带 `-i` 的 `sed`）且中间没有成功的
+`subagent` / `vexillatio` 派发时，异步注入一条 follow-up 提醒，不挡住当前
+`tool_call`。
 
 ```json
 { "subagents": { "scoutGuard": { "enabled": true, "threshold": 8, "cooldownMs": 120000 } } }
@@ -1132,12 +1137,24 @@ index.ts(132,4): error TS7006: Parameter 'signal' implicitly has an 'any' type.
 
 ---
 
-## 16. 交付前安全/健壮性审计（F38–F45）
+## 16. 交付前安全/健壮性审计（F38–F46）— Historical findings（✅ landed）
 
 对全部模块做了对抗式输入扫描（畸形会话文件、路径穿越、恶意配置、并发写）。
-以下 8 条是真缺陷，其余区域已验证健壮。
+以下条目**当时**是真缺陷；对照当前 master 均已落地（见各条 ✅），勿再当 open gap。
 
-### F38 — ReDoS：glob → RegExp 的嵌套量词（安全）
+| # | 当时缺口 | master 落点（摘要） |
+| --- | --- | --- |
+| F38 | glob→RegExp ReDoS | `matchesScopePattern` 双指针 glob，**不用 RegExp** |
+| F39 | `openSync`/`closeSync` fd 泄漏 | session 预创建改 `writeFileSync(..., { flag: "wx" })` |
+| F40 | `JSON.parse` 标量拖垮会话解析 | `decodeEvent` 非对象计入 `tornLines` |
+| F41 | `tasks[]` 条目未校验 | `firstInvalidStep` / 启动前校验 agent+task |
+| F42 | 空白 `task` 被 `Boolean` 放行 | 存在性按 `trim()` |
+| F43 | 角色 `timeoutMs` 被忽略 | launch 记入 `timeoutByName`，follow/wait 使用 |
+| F44 | `acceptance.criteria` 静默丢弃 | `pendingCriteria` + command 才升 `verified` |
+| F45 | 未生效配置看起来生效 | `UNENFORCED_FIELDS` 现为空；list 不再假警告 |
+| F46 | 嵌套 YAML acceptance 未解析 | `parseAcceptance` + `parseIndentedBlock` |
+
+### F38 — ✅ landed — ReDoS：glob → RegExp 的嵌套量词（安全）
 
 `modelScope.allow` 的 glob 被翻译成 `.*`，于是 `*a*a*a…b` 变成 `.*a.*a.*a…b`——
 嵌套量词在**不匹配**的输入上指数回溯。
@@ -1152,7 +1169,7 @@ index.ts(132,4): error TS7006: Parameter 'signal' implicitly has an 'any' type.
 **修法**：不用正则，改用双指针贪心 glob 匹配（只回溯最近一个 `*`）。
 修复后 n=6400 仅 2ms。
 
-### F39 — fd 泄漏：`openSync`/`closeSync` 无保护
+### F39 — ✅ landed — fd 泄漏：`openSync`/`closeSync` 无保护
 
 ```ts
 const fd = fs.openSync(file, "w", 0o600);
@@ -1165,7 +1182,7 @@ launcher 为**每个 child** 创建一个 session 文件，所以泄漏会随 fa
 **修法**：`fs.writeFileSync(file, "", { flag: "wx", mode: 0o600 })`——
 由 Node 自己管理描述符，并且 `wx` 顺带消除了 `existsSync` 检查留下的 TOCTOU 窗口。
 
-### F40 — `JSON.parse("null")` 拖垮整个会话解析
+### F40 — ✅ landed — `JSON.parse("null")` 拖垮整个会话解析
 
 `JSON.parse` 对标量是成功的：`null` / `42` / `true` / `"x"`。
 随后 `event.type` 在 `null` 上抛异常，**整个 `parseSessionText` 崩溃**，
@@ -1173,7 +1190,7 @@ launcher 为**每个 child** 创建一个 session 文件，所以泄漏会随 fa
 
 **修法**：非对象、非数组的标量按损坏行计入 `tornLines`，继续解析其余行。
 
-### F41 — `tasks[]` 的条目未校验
+### F41 — ✅ landed — `tasks[]` 的条目未校验
 
 单任务路径用 `Boolean(params.agent && params.task)` 把关，但数组路径直接放行：
 
@@ -1184,12 +1201,12 @@ tasks:[{task:"do it"}]            → 放行，agent 名为 undefined
 
 **修法**：每个 step 在分配任何资源之前校验 `agent` 与 `task`。
 
-### F42 — `Boolean("   ")` 为真：纯空白 task 被放行
+### F42 — ✅ landed — `Boolean("   ")` 为真：纯空白 task 被放行
 
 即使单任务路径，`task: "   "` 也会通过，生成一个毫无意义的 `Task:` prompt。
 **修法**：存在性按 `trim()` 后的内容判定，而非 `Boolean()`。
 
-### F43 — `timeoutMs` 被解析却从不生效
+### F43 — ✅ landed — `timeoutMs` 被解析却从不生效
 
 5 个自带角色都声明了预算，运行时却全部忽略，永远用全局默认 15 分钟：
 
@@ -1201,7 +1218,7 @@ DEFAULTS.turnTimeoutMs: 900000 (15min) ← 实际生效
 
 **修法**：`collect` 采用 `agent.timeoutMs`（按 child 记录，逐个子 agent 生效）。
 
-### F44 — `acceptance.criteria` 被静默丢弃
+### F44 — ✅ landed — `acceptance.criteria` 被静默丢弃
 
 角色可以声明 `must: "测试通过"` 这类**语义**验收条件，代码解析后就不管了。
 调用方无法知道「没有任何东西验证过它」。
@@ -1212,7 +1229,7 @@ DEFAULTS.turnTimeoutMs: 900000 (15min) ← 实际生效
 **修法**：criteria 作为**待验证清单**回传调用方（`pendingCriteria`），
 且 `level` 保持 `attested`——**`verified` 只留给真正被人核对过的证据**。
 
-### F45 — 配置字段「看起来生效、实际无效」
+### F45 — ✅ landed — 配置字段「看起来生效、实际无效」
 
 自带角色携带 `onBlocked` / `allowNestedSubagents` / `fallbackModels` / `toolTimeoutMs`，
 全部被解析、全部不生效。其中 `allowNestedSubagents: false` 最危险——
@@ -1227,7 +1244,7 @@ DEFAULTS.turnTimeoutMs: 900000 (15min) ← 实际生效
 **原则**：**一个被接受却不做事的键，比一个未知的键更危险**——
 用户会相信它已经在保护自己。
 
-### F46 — 嵌套 YAML 块从未被解析：自带角色的 acceptance 全部丢失
+### F46 — ✅ landed — 嵌套 YAML 块从未被解析：自带角色的 acceptance 全部丢失
 
 frontmatter 解析器是**扁平的**（只处理 `key: value`）；一个嵌套块会以
 **剥掉公共缩进后的原始文本**返回：

package/docs/vexillatio-contract.md

@@ -121,7 +121,7 @@ const VexillatioParams = Type.Object({
 
 **既有测试文件除 §3 明确授权的 `test/unit/child-mode.test.ts` 两处断言数字修订外一律不修改**；§4 要求的新增测试全部落在两个新文件里。
 
-**断言影响总则（REV-17.5）**：契约导致的注册行为变化若使某既有断言失效，属于本契约的影响面；授权范围以本 §3 该行所列为准，本行已全量扫描（grep `pi.tools\|tools.length\|tools.find\|tools.get\|herdrSubagents(` 全测试目录）并一次列尽。后续若再发现同类冲突，上报照旧。
+**断言影响总则（REV-17.5）**：契约导致的注册行为变化若使某既有断言失效，属于本契约的影响面；授权范围以本 §3 该行所列为准，本行已全量扫描（grep `pi.tools\|tools.length\|tools.find\|tools.get\|piLegion(` 全测试目录）并一次列尽。后续若再发现同类冲突，上报照旧。
 
 ## 4. 验收清单（可机器检查）