pi-legion 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# 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]
+
+## [2.0.2] — 2026-10-16
+
+### Fixed
+
+- Child worktree launches are suppressed when the parent checkout is itself a
+  linked git worktree (`git-dir` ≠ `git-common-dir`): role defaults and unset
+  launch flags collapse to `worktree: false`, matching the centurion-child
+  precedent. Explicit `launch: true` / per-child `step` flags still win.
+- `worktreeBootstrap: "npm-install"` no longer fires `npm install` on a stray
+  `package.json` without a lockfile (observed: Java/Maven repos carrying
+  package.json for docs/tooling); without a lockfile the mode records the
+  marker and skips, so non-npm worktrees launch instead of failing after the
+  10-minute bootstrap budget.
+
+### Fixed in 2.0.1 (inherited from prior entries)
+
+- Railway / `/legion` header "now" tok/s is 0 when no agent is running; only live nodes count toward now (chart buckets still use the full trailing window) (#136).
+- Narrow/stacked `/legion` header truncates long run + selection badges without overwriting `⚔ /legion`; galaxy legend reserves room for failed/retired glyphs before roles (#125).
+- Galaxy legend `statusBudget` counts grapheme cells (not `String.length`); selection badge min width unified for portrait + landscape (#128).
+- 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
+
+- Esc no longer retires children; only `/legion stop` or session exit retires (esc-no-retire-v3, #134).
+- Status strip shows a persistent `/legion stop` hint while children are live (railway + tree; width may truncate) (#134).
+- 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,35 +91,64 @@ 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
+settles (or the parent turn is interrupted with Esc). Esc only ends the parent
+wait — children keep running and settle still notifies; retire them with
+`/legion stop` or by exiting the session. 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.
 
 ### Stopping async subagents yourself
 
-Async children keep running after the main turn ends, so Esc-abort no longer
-reaches them. Three user controls run the same graceful `stop` (a stopped
-parent retires its own subtree on shutdown):
+Esc never retires children (see `docs/contracts/esc-no-retire-v3.md`). Two user
+controls run graceful `stop` (a stopped parent retires its own subtree on
+shutdown); process exit / session shutdown also retires:
 
 - **`/legion stop`** stops every live subagent; **`/legion stop <name>`** stops
   one (`all` is an alias for no name). Names complete from the live children;
   nested agents complete as `parent/name` and are reported as owned by their
   parent (stop the parent to retire them).
-- **Esc** while the main agent is idle, the editor is empty, no dialog or
-  overlay is open and subagents are live asks "Stop N running subagents?".
-  In every other state Esc keeps pi's normal behaviour.
 - **`x`** on the selected live agent in the `/legion` view or its live
   overlay asks `y` to confirm in place, then stops it.
 
-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).
+While subagents are live, the railway header can show a dim
+`/legion stop [name|all]` hint (shortened on narrow terminals; idle gating /
+tree-strip coverage is a TUI follow-up).
+
+### 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
 
@@ -208,6 +241,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 +310,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 +334,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 +353,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 +420,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 +465,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-abort-v1.md

@@ -2,6 +2,8 @@
 
 > **v2 修订（2026-10-13）**：ESC / 父 turn abort 的语义已改为级联优雅关闭由该 turn 拥有的 children，推翻 v1 下文的「ESC ≠ 杀 children」决定。下文保留 v1 冻结原文，仅供历史考古；当前语义以 `docs/contracts/esc-cascade-v2.md` 为准。
 
+> **v3 说明（2026-10-15）**：v3（`esc-no-retire-v3.md`）再次回到 v1 的「ESC ≠ 杀 children」原则；与 v1 不同的是保留 session_shutdown drain/归因与显式 `/legion stop`。v2 级联语义已推翻。
+
 ## 目标
 
 1. 主 pi 按 ESC（或 RPC abort）打断当前 turn 时，正在执行的 `subagent` 工具调用必须尽快感知并优雅收场，不能钉住事件循环。

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

@@ -1,5 +1,8 @@
 # ESC 级联关闭契约（v2，2026-10-13 冻结）
 
+> **v3 推翻（2026-10-15）**：ESC / 父 turn abort **不再**级联 retire children。当前语义以 `docs/contracts/esc-no-retire-v3.md` 为准。下文保留 v2 冻结原文，仅供历史考古。
+
+
 ## 背景
 
 v1（esc-abort-v1.md，已随 e66c85f 合入）冻结了「ESC ≠ 杀 children」语义。用户裁决推翻：turn 是 children 的 owner，turn 被 abort 时 children 应级联关闭，否则是资源泄漏。
@@ -57,7 +60,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/contracts/esc-no-retire-v3.md

@@ -0,0 +1,57 @@
+# ESC 不再 retire children（v3，2026-10-15 冻结）
+
+## 背景
+
+v2（`esc-cascade-v2.md`）把「父 turn abort → 级联 retire children」冻结为产品语义。2026-10-15 实测事故：主会话异步派了多个 child 后用 `wait` 阻塞，用户按 Esc 打断父 turn，级联 retire 把整棵仍在生长的 legion 树抹掉（含尚未派生子 agent 的 centurion）。Esc 是高频误触键，后果不可恢复。
+
+用户裁决推翻 v2：**Esc 只打断父 turn 的等待，不杀 children；停止 subagent 只有两条路——显式 `/legion stop`，或主进程退出。**
+
+## 冻结决定
+
+### A. Esc ≠ retire
+
+1. **Idle Esc stop 删除**：不再有 `createIdleEscStop` / `onTerminalInput` 接线。裸 Esc 在 idle 时也不再 stop all。
+2. **父 turn abort 不再级联**：工具 execute 各 `signal?.aborted` 分支只返回 interrupted 文案，**不**调用 `cascadeRetireAll`。`cascadeRetireAll` / `cascadePromise` / `agent_settled{aborted}` 级联钩子全部删除。
+3. **`abandonLaunchedChild`**：spawn 后 abort 时 **不 retire**；`followLaunched(..., { watch: true })`，child 继续跑，settle 仍通知父会话。
+4. **`runtime.waitOne` WAIT_INTERRUPTED**：**必须 re-arm watch**（`consumedByTool = false` + `watch`），否则 child 完成后无人收割、无完成通知。
+
+### B. 中断文案
+
+统一为：
+
+```text
+interrupted (parent turn ended; children still running)
+```
+
+不再使用 `interrupted (parent turn aborted)`（易误导为已 abort children）。
+
+### C. 保留的 retire 路径（不变）
+
+- 显式 `stop` action / `/legion stop` / `/legion` 视图 `x`
+- `session_shutdown` → `shutdownRetireAll`（交互立刻 retire；`--print` / JSON 先 `drainBeforeShutdown` 再 retire）
+- SIGINT / 进程退出 = 主进程退出 = retire
+
+### D. TUI 提示
+
+有 live child 时，aboveEditor 状态栏常驻 `/legion stop [name|all]`（短版 `/legion stop`）：railway header 在宽度挤压下可截断摘要以保短 hint；`PI_LEGION_STRIP=tree` 在 header 下另起一行短提示。无 idle 门控。
+
+## 语义边界
+
+| 动作 | children |
+|---|---|
+| Esc 打断 wait / 父 turn | 继续跑；re-arm watch；settle 通知 |
+| `/legion stop` / `stop` action | graceful retire |
+| 主进程退出 / session_shutdown | drain（print/json）+ retire |
+| SIGINT | 进程退出 → retire |
+
+## 与 v1 / v2 的关系
+
+- **v1**（`esc-abort-v1.md`）主张「ESC ≠ 杀 children」——v3 回到这一原则，但保留 v1 没有的 drain / shutdown 归因与显式 stop。
+- **v2**（`esc-cascade-v2.md`）级联 retire —— **v3 推翻**；原文保留供考古。
+
+## 验收锚点
+
+- 无 `cascadeRetireAll` / idle Esc 接线
+- wait abort → children still alive + watching；完成通知仍达
+- launch abort mid-spawn → child watched, not retired
+- print-shutdown / session_shutdown / stop 回归绿