pi-legion 4.0.0 → 5.0.1

package/CHANGELOG.md

@@ -11,8 +11,254 @@ summary so you can see **2.x vs 0.16** without leaving the tree.
 
 ## [Unreleased]
 
+## [5.0.1] — 2026-10-27
+
+Patch release. **This is the release where 5.0.0's extension-inheritance policy
+starts actually taking effect** — upgrading changes what a child loads, so read
+the first entry before rolling it out to a fleet.
+
+### Fixed
+
+- **Host extensions are inherited again (#280).** 5.0.0 declared "children inherit
+  every host extension by default" and documented the narrowing knobs, but the
+  policy never reached the spawn path: `discoverHostExtensions()` had no callers,
+  the sync getter it fed therefore returned `undefined`, and
+  `inheritedExtensions` was always handed an empty host list. Children kept
+  getting exactly the card's own `extensions` plus the child-guard — the
+  `--no-extensions` behaviour #280 set out to remove, under a new description.
+
+  Discovery is now warmed once per process before a child is spawned. The cache
+  lives on `globalThis` under `Symbol.for` rather than in a module-level `let`,
+  because pi re-evaluates an extension module with `moduleCache: false` for a
+  child's `--extension` load: a module-level variable is invisible across those
+  instances, so a child spawned from a re-loaded instance would have inherited
+  nothing. The same escape hatch already backs `child-context.ts`,
+  `inprocess-depth.ts` and `admission-queue.ts`.
+
+  The warm-up sits in each backend's `spawnChild` (and in `RoutingSupervisor`,
+  which sees both). It is deliberately not in `Orchestrator.launch`: that fast
+  path may not gain an await before the synchronous admission block
+  (`launch-admission-queue-v1` §13.7).
+
+- **`PI_LEGION_CHILD_INHERIT_EXTENSIONS=0` works on the inherited half (#280).**
+  `collectChildExtensions` accepted an `env` argument and then did not forward it
+  to `inheritedExtensions`, so the operator kill-switch applied everywhere except
+  the set it was meant to disable. Harmless while that set was always empty;
+  wrong the moment it is not.
+
+- **A manifest that names a directory no longer breaks rpc children (#280).**
+  `pi.extensions: ["./extensions"]` (what `pi-diff-review` ships) resolved to the
+  directory itself, and `pi -e <dir>` exits 1 with `Failed to load extension:
+  Cannot find module` — so wiring inheritance up would have failed every rpc
+  child of a session with that package installed. Declared entries now resolve the
+  way pi's own loader does: a file as-is, a directory through its own
+  `pi.extensions`, else its `index.ts` / `index.js`, else its `*.ts` / `*.js`
+  files. An entry that expands to nothing is dropped instead of leaving an
+  unloadable path.
+
+- **`extensions/<name>/index.ts` is discovered (#280).** The first sweep collected
+  only files directly inside a declared directory, so pi's documented
+  subdirectory layout resolved to nothing and the package silently contributed
+  zero extensions. The sweep now matches pi's `collectAutoExtensionEntries`:
+  `.`-prefixed names and `node_modules` are skipped, `*.ts` / `*.js` files are
+  collected, and a subdirectory is resolved as a package of its own (one level,
+  as pi does).
+
+- **A failing `pi list` is retried, and costs one probe per spawn (#280).** The
+  old shape cached the failure as `[]` permanently, so one transient error
+  disabled inheritance until the process restarted. Failures now stamp
+  `failedAt` and short-circuit for `FAILURE_TTL_MS` (5 s), which keeps a
+  three-point warm-up from probing twice on the same spawn while still retrying
+  once the window passes.
+
+- **A direct `RpcSupervisor` gets the same warm-up (#280).** `api.ts` documents
+  `new Orchestrator({ supervisor: new RpcSupervisor(), … })`, which never touches
+  `RoutingSupervisor`; warming only there left that path inheriting nothing.
+
+### Notes
+
+- **Cost now matches what 5.0.0 promised.** Inheriting everything includes
+  pi-lens (a ~5.7 MB bundle that starts an LSP stack) on every child. In-process
+  children share the host process, so this is host memory, not a new process.
+  Add `excludeExtensions: [pi-lens]` to a card (or
+  `PI_LEGION_CHILD_INHERIT_EXTENSIONS=0` globally) if a fleet does not need it —
+  before this release those knobs were inert.
+- **This package is never inherited into its own children.** In the source-tree
+  layout `pi list` and the child-guard name different files for the same code, so
+  dedupe could not collapse them and a child loaded two legion factories
+  (`Tool "subagent" conflicts with …`). The guard is still appended
+  unconditionally at the end.
+- Doctor output and the README described the intended behaviour, which is now the
+  actual behaviour; they were not rewritten for this release.
+
+## [5.0.0] — 2026-10-26
+
+Major because upgrading **can break an existing role card**: unknown frontmatter
+is now a hard error, and `spawnMode` / `placement` are gone. A card carrying
+either fails to load with a message naming the offending field. That is the point
+— the previous behaviour was to silently ignore them, so a setting that looked
+active did nothing.
+
+**Before upgrading**, remove `spawnMode:` and `placement:` from every card under
+`~/.pi/agent/agents/` and `.pi/agents/`. Nothing else about a card needs to
+change.
+
+### Breaking
+
+- **`spawnMode` is gone from role cards (#290).** The backend is a property of
+  the launch, not of a role: a launch that needs a worktree runs over rpc, and
+  everything else runs in-process. Since only a `centurion` may hold a worktree
+  (#214), a centurion is the only role that can reach rpc. There is no global
+  default to configure because there is no longer a choice to make per role.
+- **Unknown frontmatter is refused (#290).** A card with a field the runtime does
+  not honour is rejected at load, listing the bad keys and the full legal set. The
+  retiral of `placement` was previously "tolerated"; fourteen bundled and local
+  cards still carried it while it did nothing.
+- **Five bundled roles removed (#301).** `planner`, `reviewer`, `designer`,
+  `prototype`, and `advisor` are gone; `centurion`, `worker`, and `scout` remain.
+  They existed because the phase machine keyed its rules on role *names* — a role
+  that merely existed carried workflow meaning. See the declarative machine below.
+- **Children inherit every host extension by default (#280).** The old default was
+  `--no-extensions` plus whatever a card named, which meant a role silently lost
+  host capabilities (a provider extension, a guard) it never knew to name. Use
+  `excludeExtensions: [pi-lens]` on a card, or
+  `PI_LEGION_CHILD_INHERIT_EXTENSIONS=0` globally, to get the old isolation.
+  `inheritExtensions: false` loads only the card's own list.
+
+### Added
+
+- **Declarative phase machine (#298).** A team declares its own phases on its
+  lead's card:
+  ```yaml
+  phases:
+    - id: recon
+      next:
+        - to: build
+          require: [contract_file]
+    - id: build
+      next:
+        - to: done
+          require: [children_settled]
+  ```
+  Omitted means the built-in `planning → implementing → reviewing → verifying`.
+  Conditions are a closed vocabulary (`contract_file`, `children_present`,
+  `children_settled`, `children_none_failed`, `verdict_ok`, `verdict_not_ok`,
+  `verification_passed`, `verification_failed`, `rework_available`,
+  `children_all_failed`, `always`) and **none of them names a role**, which is
+  what lets a team reshape its workflow without touching source.
+  - Conditions live on the **edge**, not the phase: `planning → implementing`
+    needs a contract while `planning → failed` must not, or a team could not fail
+    before it had one.
+  - `done` / `failed` / `aborted` are injected when a card omits them. A team that
+    cannot be aborted is a safety hole. Reaching them is still gated: `failed`
+    needs a terminal reason, `aborted` needs a parent retire, `done` stays
+    supervisor-only. `aborted` is deliberately exempt from phase-level
+    requirements — an emergency stop must not wait for "everything settled".
+  - An invalid machine is rejected at load, reporting every problem at once
+    (unknown condition, duplicate id, unknown target, self-edge, unreachable
+    phase, terminal start).
+- **The tree shows a team's machine (#302).** Selecting a team root unfolds its
+  phases, the current one, and every transition with its conditions.
+- **`legion_phase` refusals name the legal exits (#299).** A refused transition
+  reports `legal next phases from 'recon': build, done, failed, aborted`. Measured:
+  without it a model invented plausible-but-nonexistent transitions and burned a
+  turn being refused.
+
+### Fixed
+
+- **In-process children enforce `toolBudget` / `turnBudget` (#295).** The parent
+  computed budgets into `SpawnInput.env`, which an rpc child receives as its real
+  environment — but an in-process child shares the *host's* `process.env`, so the
+  guard read the parent's (absent) values. A card with `toolBudget: {maxToolCalls:
+  3}` made 12 tool calls and finished normally. Budgets now travel in the
+  async-local child context, the same channel already used for lineage identity,
+  with `process.env` kept as the rpc fallback.
+- **A malformed budget is an error, not "no limit" (#293).** `{not json}` parsed to
+  `undefined` and `{"maxToolCalls": -3}` was accepted, so the guard would have
+  blocked the first call. Both now fail at load naming the file, field, and value.
+- **rpc is reserved for a centurion, and in-process keeps its ledger budget
+  (#279).** In-process launches had been exempted from every legion budget
+  (`Number.MAX_SAFE_INTEGER`), which made "run it in-process" a way to escape
+  depth/spawn/ledger caps. Admission and reservation now share one code path, so a
+  launch cannot be admitted and then rejected.
+- **Runtime handles are keyed by (ledger path, node id) (#283, #285, #287).** Keyed
+  by path alone, a second session sharing the ledger could close the parent's
+  database; the identity is now adopted per node.
+- **Extension inheritance discovery (#280).** `pi list` reports package
+  *directories*, resolved the way pi's own loader does (`package.json`'s
+  `pi.extensions`, else `index.ts` / `index.js`). Single-file `--extension`
+  arguments and builtins cannot be discovered this way — name them explicitly.
+- **One spelling for "unknown child" (#288).** The old message advised "pass the
+  same cwd used for launch", which stopped being actionable once cross-store
+  lookup landed.
+- **Prompt surfaces match the code again (#303, #304).** The parent playbook told a
+  centurion to "dispatch N centurions" — an instruction the runtime refuses
+  (only the root may dispatch one). The roster also listed a centurion to
+  itself. `worker` kept `subagent` in its tool list while its text said not to
+  spawn, and the README described every child as an rpc process.
+
+### Notes
+
+- `toolBudget` / `turnBudget` remain **optional and unused by the bundled cards**.
+  Time, depth, per-node child counts, active-node counts, and the memory floor are
+  the intended bounds; a tool budget is a scalpel for one stubborn role, not a
+  default.
+- Child extension inheritance includes heavy extensions. pi-lens starts an LSP
+  stack (~1 GB per child, #43); add `excludeExtensions: [pi-lens]` where a fleet
+  does not need it.
+
 ## [4.0.0] — 2026-10-24
 
+- **Renewal for a budget casualty (#270).** An agent whose turn budget (`timeoutMs`)
+  runs out no longer just reports `failed`. When it measurably progressed and its
+  role allows renewal, the completion notice ends with a ready-to-paste
+  `subagent({ action: "continue", … })` plus the evidence (`progressed: 47 tool
+  results, 12 assistant messages, 6 files changed`) and the remaining budget
+  (`renewals: 1/2`). Renewal reuses the existing `continue` path, so the child
+  resumes from its own session file with its context intact. Two dispatches in one
+  day motivated this: one worker was cut off with nothing on disk, another finished
+  its code but ran out during verification.
+  - **Never automatic.** An auto-renewed stuck child would hold a concurrency slot
+    indefinitely; the notice hands over the decision instead.
+  - "Progressed" = ≥ 3 new `toolResult` rows or ≥ 1 changed file since the last
+    baseline. `assistant` messages are shown but never count — a model looping on
+    the same sentence grows that number without doing work.
+  - New agent frontmatter: `renewable` (default **true**; a timed-out `scout` means
+    the task was mis-scoped) and `maxRenewals` (default **2**; `0` disables, each
+    renewal is a fresh full budget). Both are validated in the team-override path
+    like every other numeric/boolean field.
+  - `wait`/`collect` timeouts never propose a renewal: those return while the child
+    is still alive. Only a real termination does, judged by `stopReason: "toolUse"`
+    / missing assistant row (F29) / the host's `terminated` wording — a clean
+    `stop` from an ordinary retry does not spend the budget.
+
+- **Launch admission queue (#266).** A launch that exceeds a *concurrency* gate
+  (`maxChildrenPerNode`, `maxActive`, ledger `max_children_per_node` /
+  `max_active_nodes`) no longer fails with `BUDGET_EXCEEDED`. It is enqueued,
+  the caller gets `▶ scout-7 (scout) supervisor=inprocess queued(3)` and treats
+  the work as dispatched, and the child starts automatically when a slot frees.
+  Previously a 12-step fan-out against `maxChildrenPerNode: 8` ran 8 children and
+  reported 4 errors — and nothing ever retried them, because the parent was
+  already inside `wait` and the freed slot had no subscriber.
+  - New settings: `subagents.inprocess.maxQueuedLaunches` (default **32**) and
+    `subagents.inprocess.launchQueueTimeoutMs` (default **900000**). Both are
+    shared by the in-process and RPC paths — one scheduler, not two.
+  - Depth, spawn-per-session, memory, name-collision and config errors are still
+    refused synchronously, byte-identically to before: only gates that a slot
+    release can satisfy are queueable. `maxChildrenPerNode: 0` is a hard refusal
+    (0 means "no children", so waiting can never satisfy it).
+  - A queued launch reserves nothing: no ledger row, no child run directory, no
+    worktree, no session file. `timeout`/`overflow`/`stop` are reported by name;
+    `stop` dequeues without ever spawning, and a parent-turn abort flushes the
+    queue and says how many launches it dropped.
+  - `subagent({action:"status"})` shows `state=queued`, `collect`/`wait` block
+    until admission instead of reading the placeholder session path, and
+    `async: false` reports `↳ <name> waited Ns in the launch queue`.
+  - Two new process-only events (`launch_queued`, `launch_admitted`) and a
+    `legion-queue: N queued` status pill.
+
+## [4.0.0] — 2026-10-19
+
 A major line — but not only the pi-only collapse. Relative to 3.1.0 this release
 removes every non-`pi` agent kind and the archived Herdr backend behind it, along
 with the settings and error codes that only its transport read. It also carries
@@ -651,7 +897,8 @@ branch — pin `pi-legion@0.16.x` if you still need that model. See
 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/v4.0.0...HEAD
+[Unreleased]: https://github.com/zzjcool/pi-legion/compare/v5.0.0...HEAD
+[5.0.0]: https://github.com/zzjcool/pi-legion/compare/v4.0.0...v5.0.0
 [4.0.0]: https://github.com/zzjcool/pi-legion/compare/v3.1.0...v4.0.0
 [3.1.0]: https://github.com/zzjcool/pi-legion/compare/v3.0.3...v3.1.0
 [3.0.3]: https://github.com/zzjcool/pi-legion/compare/v3.0.2...v3.0.3

package/README.md

@@ -1,7 +1,7 @@
 ---
 name: pi-legion
 npm: "pi-legion"
-description: "Pi Legion v2: recursive centurion trees on headless Pi RPC; shared SQLite WAL legion.db. Four-stage planning/implementing/reviewing/verifying state machine, parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume."
+description: "Pi Legion v2: recursive centurion teams on Pi. Children run in-process by default (rpc only for a worktree-owning centurion); shared SQLite WAL legion.db. Declarative per-team phase machine (built-in default: planning/implementing/reviewing/verifying), parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume."
 ---
 
 # pi-legion
@@ -49,14 +49,16 @@ User (CEO) — root Pi session (TUI)
    └─ pi-legion in child mode
       ├─ LegionSupervisor for this squad
       ├─ `legion_mail` / `legion_tree` / `legion_phase` tools
-      ├─ worker / scout / reviewer … children (`worktree: false`)
+      ├─ worker / scout … children (`worktree: false`)
       └─ nested centurions → recursive squads
 ```
 
 Transport, state, decision-making, and display are separate layers:
 
-- **Transport:** each child is a headless Pi RPC process managed by a
-  `LegionSupervisor`; a centurion can supervise another squad recursively.
+- **Transport:** a child is an `AgentSession` inside the parent process by
+  default; only a worktree-owning centurion runs as a separate `pi --mode rpc`
+  process. A `LegionSupervisor` owns both backends, and a centurion can lead
+  another squad recursively.
 - **State:** all nodes in the tree share the `legion.db` SQLite ledger in WAL
   mode. Per-run `run.json` records and session files remain the resume source
   for each child.
@@ -65,36 +67,70 @@ Transport, state, decision-making, and display are separate layers:
 - **Display:** the event bus feeds the resident tree, the `/legion` full view,
   and an on-demand live overlay.
 
-## Spawn mode
+## Bundled roles
+
+Three roles ship with the package:
+
+| Role | Purpose | Tools | Default timeout |
+| --- | --- | --- | --- |
+| `centurion` | Team lead: freeze the contract, dispatch children, drive the phase machine, deliver a reviewable result. Holds the worktree. | pi defaults | 30 min |
+| `worker` | Implementation: write code and run tests against a frozen plan, report a verdict. | read/edit/write/grep/find/ls/bash/codemode | 45 min |
+| `scout` | Read-only recon: produce a fact list, no plan, no implementation. | read/grep/find/ls/bash/codemode | 10 min |
 
-`spawnMode` picks the backend that runs one child. Per role it comes from agent
-frontmatter → `subagents.agentOverrides.<role>` → team member override:
+`worker` cannot dispatch nested agents (`maxSubagentDepth: 1`). Anything a worker
+needs to escalate is a `verdict ok:false`, not another layer of children — one
+level keeps the tree's cost and blast radius bounded.
+
+Roles are not a fixed pipeline. Since the phase machine became declarative
+(#298), nothing in the runtime keys on a role being called "worker" or
+"reviewer"; a team shapes its workflow by declaring phases on its lead's card.
 
 ```yaml
-# agents/scout.md
----
-spawnMode: inprocess   # or: rpc
----
+# agents/centurion.md
+phases:
+  - id: recon
+    next:
+      - to: build
+        require: [contract_file]
+  - id: build
+    next:
+      - to: done
+        require: [children_settled]
 ```
 
-**Default:** omitting `spawnMode` means `inprocess` — the child runs as an
-`AgentSession` inside the parent Node process (`createAgentSession`), which
-trades process isolation for spawn latency.
+Omitted means the built-in four-phase pipeline
+(`planning → implementing → reviewing → verifying → done`). Conditions are a
+closed vocabulary — `contract_file`, `children_present`, `children_settled`,
+`children_none_failed`, `verdict_ok`, `verdict_not_ok`, `verification_passed`,
+`verification_failed`, `rework_available`, `children_all_failed`, `always` — and
+`done` / `failed` / `aborted` are always available terminals so a team can
+never lose the ability to complete or abort.
 
-**Automatic fallback to `rpc`:** when `spawnMode` is omitted *and* the resolved
-spawn cannot be in-process, Legion launches it over `pi --mode rpc` instead.
-That happens when the role needs an OS worktree (`worktree: true` — only the
-`centurion` role may hold this; see
-[Delivery and resume](#delivery-and-resume)).
+## Spawn mode
 
-**Explicit is strict:** `spawnMode: "inprocess"` with `worktree: true` is
-refused with `INVALID_PARAMS` (message prefers `set worktree: false`) rather
-than silently downgraded, so a role that asks for in-process never gets a
-different transport behind its back. Non-centurion requests for `worktree: true`
-are demoted to `false` with a once-per-run warning instead of throwing.
+The backend is a property of the **launch**, not of a role. There is no
+`spawnMode` frontmatter field — a card cannot pin itself to a process model —
+and the rule is simply:
 
-Limits for the in-process backend are separate (`subagents.inprocess.*`) and are
-not shared with the `legion.*` tree budgets — see
+| Launch needs a worktree? | Backend |
+| --- | --- |
+| yes | `rpc` — a separate `pi --mode rpc` process |
+| no | in-process `AgentSession` inside the parent Node process |
+
+**Why rpc still exists:** it is the only backend that can host a worktree
+child. Only the `centurion` role may hold a worktree (see
+[Delivery and resume](#delivery-and-resume)), so a centurion is the only role
+that can ever run on rpc — every other role runs in-process, where spawn latency
+is lower and no second process is involved.
+
+**A non-centurion asking for a worktree** is demoted to `worktree: false` with a
+once-per-run warning rather than throwing, so a stale card does not break every
+launch in the tree.
+
+**Both backends share the same budgets.** The legion tree limits
+(`maxDepth` / `maxChildrenPerNode` / `maxActiveNodes`) apply to every launch; the
+in-process pools (`subagents.inprocess.*`) apply on top, and the stricter gate
+wins. Avoiding rpc is never a way to escape a cap. See
 [docs/inprocess-supervisor.md](docs/inprocess-supervisor.md).
 
 ## Headless child contract
@@ -129,7 +165,7 @@ subagent({
 ```
 
 The centurion plans the work, writes the squad contract, dispatches ordinary
-roles such as `worker`, `scout`, and `reviewer`, and coordinates the squad
+roles such as `worker` and `scout`, and coordinates the squad
 through its phases. For a single leaf task, dispatch an ordinary role directly:
 
 ```text
@@ -230,11 +266,17 @@ legion_phase({ to, note?, evidence? })
 - **`legion_phase`** is available to centurions. It requests a state transition;
   the supervisor checks the transition's invariants and records the result.
 
-A squad moves through **planning → implementing → reviewing → verifying**.
-Planning produces a non-empty `.pi-legion/contract.md` with file ownership
-and acceptance commands. During reviewing, an independent reviewer supplies
-the judgment; in verifying, the supervisor runs the contract's `legion-verify`
-commands without an LLM. Passing verification advances the squad to `done`.
+A squad moves through whatever phases its lead declares. With no declaration
+that is the built-in **planning → implementing → reviewing → verifying**:
+planning produces a non-empty `.pi-legion/contract.md` with file ownership and
+acceptance commands; reviewing needs a settled child that returns `ok:true`; in
+verifying the supervisor runs the contract's `legion-verify` commands without an
+LLM. Passing verification advances the squad to `done`.
+
+Because the machine is data, no rule names a role: "the children are settled" and
+"a verdict came back ok" are conditions, not "the worker" and "the reviewer".
+That is what lets a team rename, reorder, or drop phases without touching code —
+and it is why the bundled roster is just `centurion`, `worker`, and `scout`.
 
 ## Three-layer visualization
 
@@ -428,20 +470,35 @@ Coverage:
 
 ### Child extensions
 
-Children start with `--no-extensions`, so they do not load the host's
-discovered extensions (settings `packages`, `~/.pi/agent/extensions`, project
-extensions). Each extension a child loads is a memory cost multiplied by every
-concurrent child; an LSP stack is ~1 GB (#43). A child still loads pi-legion
-itself (guard and nested spawning) and every path listed in the role's
-`extensions` / `subagentOnlyExtensions`.
+**A child inherits every extension the parent has**, minus anything it excludes.
+This is the opposite of the pre-4.0.1 default: children used to start with
+`--no-extensions` and load only what a card named, which meant a role silently
+lost host capabilities (a provider extension, a guard) it never knew to name.
+Children now run in-process by default, so "one more extension" no longer means
+another process's worth of memory.
 
 | Knob | Effect |
 | --- | --- |
-| role frontmatter `inheritExtensions: true` | That role loads all host extensions, as before. |
-| `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.
+| *(default)* | Inherit every host extension. |
+| role frontmatter `excludeExtensions: [pi-lens]` | Subtract specific ones. Accepts a package **name** (`pi-lens`, matches the package dir or a loose `pi-lens.ts`) or an exact **path** (`/abs/.../index.ts`, `~` expands). |
+| role frontmatter `inheritExtensions: false` | Load ONLY the card's own `extensions` / `subagentOnlyExtensions`. Nothing is inherited, so `excludeExtensions` has nothing to subtract. |
+| `PI_LEGION_CHILD_INHERIT_EXTENSIONS=0` | Same as `inheritExtensions: false`, for every child. `1` forces inheritance back on. |
+| `PI_LEGION_CHILD_EXTENSIONS=/a.ts,/b.ts` | Extra paths every child loads explicitly. |
+
+The child-guard is appended unconditionally and is not subject to either knob —
+a child without it breaks the prompt/format contract no matter what the card
+asked for.
+
+**Discovery limit.** Host extensions are found by reading `pi list` (which
+reports package *directories*) and resolving each one the way pi's own loader
+does: `package.json`'s `pi.extensions`, else `index.ts`/`index.js`. Single-file
+`--extension` arguments and builtins cannot be discovered this way; name them
+explicitly if a child needs them.
+
+**Cost note.** Inheriting everything includes heavy extensions. pi-lens starts an
+LSP stack (~1 GB per child, #43). If a fleet of children does not need it, add
+`excludeExtensions: [pi-lens]` to those cards. The bundled `worker` does not list
+`lens_*` tools; give a role those tools by adding the names to its `tools:` list.
 
 ### Extra agent directories
 
@@ -492,7 +549,7 @@ another connection holds the db.
 
 ## Delivery and resume
 
-A centurion owns a Git worktree for its subtree; its worker/scout/reviewer
+A centurion owns a Git worktree for its subtree; its worker/scout
 children work in that subtree (`worktree: false`, typically in-process), and a
 nested centurion gets a nested worktree. **Parallel isolated writers:** dispatch
 N centurions from the root (each owns one worktree); do not give every worker

package/agents/centurion.md

@@ -1,6 +1,6 @@
 ---
 name: centurion
-description: 百夫长/组长：携带一支团队递归派生的指挥角色，负责冻结契约、调度组员、推进四阶段状态机并整队交付。
+description: 百夫长/组长：带领一支子团队，负责冻结契约、调度组员、推进阶段状态机并整队交付。（仅根会话可派发）
 kind: pi
 allowNestedSubagents: true
 maxSubagentDepth: 3
@@ -19,35 +19,39 @@ acceptance:
 
 你是 centurion，一支子树团队的负责人。只负责自己的队伍；不得越级指挥、收割或绕过其他 centurion 管理其组员。你必须通过 `legion_phase` 请求阶段迁移，通过 `legion_mail` 沟通，通过 `legion_tree` 观察状态，不得把口头声明当作机器事实。
 
-## 四阶段职责
+## 阶段职责
 
-### planning
+阶段由本队的 `phases:` 声明（省略则是内置四阶段：planning → implementing → reviewing → verifying → done）。**不要假定阶段名**——先看系统提示里展开的状态机，或直接用 `legion_phase` 试，被拒时拒绝信息会列出当前合法的下一步。
+
+不论阶段怎么命名，职责是这样分层的：
+
+### 规划阶段（内置 `planning`）
 
 - 先完整理解目标与验收条件，再把接口、wire 字段、文件所有权、验收清单写入 `.pi-legion/contract.md`。
-- 契约未落盘且非空，不得请求进入 implementing；发现契约矛盾时停止派工并上报，不得自行解释或扩大文件归属。
+- 契约未落盘且非空，不得请求进入实现阶段；发现契约矛盾时停止派工并上报，不得自行解释或扩大文件归属。
 - 契约中的每个写入文件只能有一个 owner；共享文件必须串行分配。
 
-### implementing
+### 实现阶段（内置 `implementing`）
 
 - 按冻结契约和文件所有权并行派发互不冲突的工作；worker 任务必须逐项列出可写文件、验证要求和交付格式。
 - 子任务只用 `subagent` 工具派发；工具的并行任务必须各自有明确边界。实现过程中监控 `legion_tree`，通过邮件解决必要的协作，不以邮件取代共享工件。
-- 组员声明完成后，按结果收集 session/verdict；未收齐所有 worker 结果不得请求进入 reviewing。
+- 组员声明完成后，按结果收集 session/verdict；未收齐所有 worker 结果不得请求离开本阶段。
 
-### reviewing
+### 审查阶段（内置 `reviewing`）
 
-- 对实现做多角度、对抗式 review，至少覆盖正确性/回归、测试覆盖和简洁性；reviewer 必须独立于实现者。
-- `reviewer` verdict `ok:true` 才能请求进入 verifying。major finding 必须退回 implementing 修复并复审；若是计划本身错误，可退回 planning，但必须通过 `legion_phase` 记录并邮件告知上级。
-- 每个 `failed` worker 必须先 rework 重派或由父级明确收队；不得把失败 worker 声明为已处理来解锁 reviewing。
-- 被 `legion_phase` 拒绝时，先按拒绝理由核实机器事实，修正条件后重试；这不是 rework，不得伪造证据或绕过状态机。
+- 对抗式审查，至少覆盖正确性/回归、测试覆盖和简洁性，且必须由**未参与实现**的独立子节点做。
+- 通过条件看阶段声明里的 `verdict_ok`：需要一个 settled 子节点回报 `ok:true`。major finding 退回实现阶段修复并复审；若是计划本身错误，可退回规划阶段，但必须通过 `legion_phase` 记录并邮件告知上级。
+- 每个 `failed` 子节点必须先 rework 重派或由父级明确收队；不得把失败节点声明为已处理来解锁审查阶段。
+- 被 `legion_phase` 拒绝时，按拒绝理由核实机器事实，修正条件后重试；这不是 rework，不得伪造证据或绕过状态机。
 
-### verifying 与收队
+### 验证与收队（内置 `verifying` / `done`）
 
-- verifying 由 supervisor 自动运行契约中的 `legion-verify` 命令。全绿后状态机自动进入 done；不要自行宣称验证成功，也不要手动改数据库。
-- done 后汇总全部 worker/reviewer verdict、验证结果和未决问题；把子树工作 squash 成一个 MR/PR，开给父节点/目标分支审查，并把链接写入最终 verdict。绝不在本级自行合并。
+- 验证由 supervisor 自动运行契约中的 `legion-verify` 命令。全绿后状态机自动进入 done；不要自行宣称验证成功，也不要手动改数据库。
+- done 后汇总全部子节点 verdict、验证结果和未决问题；把子树工作 squash 成一个 MR/PR，开给父节点/目标分支审查，并把链接写入最终 verdict。绝不在本级自行合并。
 - 收队时保证组员结果已落盘；由父级 collect 本节点结果后 retire。worktree/session 是 resume 凭据，未获根级清理授权前不得删除。
 
 ## 止损与安全
 
-- 同一问题重试不超过 2 次；两次仍失败，立即通过 `advisor` 咨询止损。advisor 必须是 `kind: pi`。咨询要附已尝试方案及失败输出、当前假设、涉及文件，并按 advisor 裁决执行。
-- advisor 裁决回滚时回到上一个检查点并记录原因；不得硬扛第三次，不得为了绿灯绕过测试或修改冻结契约。
+- 同一问题重试不超过 2 次；两次仍失败，停止并向上报告（附已尝试方案、失败输出、当前假设、涉及文件），不要硬扛第三次，也不得为了绿灯绕过测试或修改冻结契约。
+- 回滚时回到上一个检查点并记录原因。
 - 只使用允许的工具和团队边界；不读写其他队的文件，不直接访问 legion.db，不使用越级邮件。

package/agents/scout.md

@@ -8,6 +8,9 @@ inheritProjectContext: true
 inheritSkills: false
 async: true
 timeoutMs: 600000
+# A timed-out scout means the question was too broad, not that work needs
+# finishing — renewing it would just re-run an over-scoped search (#270 D5).
+renewable: false
 acceptance:
   level: attested
   role: read-only
@@ -17,7 +20,6 @@ acceptance:
       evidence: [facts, open-questions]
       severity: required
 kind: pi
-placement: split-down
 steer: true
 maxSubagentDepth: 1
 ---

package/agents/worker.md

@@ -1,13 +1,12 @@
 ---
 name: worker
 description: 实现者：按冻结计划写代码、跑测试，完成后自报 verdict
-tools: read, edit, write, grep, find, ls, bash, subagent, codemode
+tools: read, edit, write, grep, find, ls, bash, codemode
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
 async: true
 timeoutMs: 2700000
-allowNestedSubagents: true
 acceptance:
   level: verified
   role: writer
@@ -17,10 +16,9 @@ acceptance:
       evidence: [verification-output]
       severity: required
 kind: pi
-placement: split-down
 steer: true
 worktree: false
-maxSubagentDepth: 3
+maxSubagentDepth: 1
 ---
 
 你是 worker，一个实现 agent。你按已冻结的计划把代码写出来并证明它能跑。
@@ -36,8 +34,8 @@ maxSubagentDepth: 3
 - **严格按计划**：接口/签名已被冻结，不要擅自更改。发现计划有错时，**停下来报告**（verdict `ok: false`，reason 写明冲突），不要自行"顺手修正"。
 - **只碰计划授权的文件**。其他模块的文件一律不动。
 - **跑不动的命令**（交互式、需要确认）走默认放行，不要挂起等待。
-- **禁止开新的 worker/写操作子 agent**。你唯一允许的嵌套派生是只读的 advisor，
-  且仅限失败升级场景（见 AGENTS.md「失败止损」：重试 2 次仍失败时咨询，按裁决执行）。
+- **不派任何子 agent**。失败止损靠自己重试与向上报告（verdict `ok: false` 写明冲突），
+  不要为了"咨询"再开一层。
 - **工作区**：在 centurion 子树 worktree（或父会话 cwd）**原地**改代码；隔离与 MR 由 centurion（或根会话）收队。不要本地 merge，不要 push 到 main/master。
 - **bugfix 先红后绿**：修 bug 类任务，第一步先写一个能复现该 bug 的失败测试并跑出失败，修复后同一测试必须转绿；两次输出都原样贴进报告。不复现就修复的，视为未验收。
 
@@ -47,7 +45,7 @@ maxSubagentDepth: 3
 2. **用项目自己的方式验证，分两档，别每轮都跑全量**：
    - 先发现项目怎么验证：看 `.pi/verify.sh`、Makefile/justfile target、CI 配置（.github/workflows 等）、package.json scripts、项目 README/CONTRIBUTING。项目明确的验证入口就是唯一权威，不要自己发明替代命令。
    - 每轮改动结束：跑项目的**轻量档**（typecheck/lint/vet 级别，如 `make lint`、`npm run typecheck`、`go vet ./...`）；秒级反馈，失败直接修，不计入重试升级。
-   - 全部步骤完成、交活前才跑一次项目的**全量档**（完整测试套件/CI 等效命令）；交活后插件会自动再验证一遍判定验收，不需要中途反复跑全量。全量失败按「失败止损」处理：重试不超过 2 次，仍失败升级咨询 advisor。
+   - 全部步骤完成、交活前才跑一次项目的**全量档**（完整测试套件/CI 等效命令）；交活后插件会自动再验证一遍判定验收，不需要中途反复跑全量。全量失败按「失败止损」处理：重试不超过 2 次，仍失败则 `ok: false` 上报。
    - 项目找不到任何验证入口时，在报告里写明依据（查过哪些地方），不要自己编命令冒充。
 3. 把最终那次 full 验证输出**原样**（含命令与结果）放进最终报告。
 4. 交活前逐文件重读完整 diff：检查遗留的调试代码、console.log/print、注释掉的老逻辑、无关改动混入；发现问题先修。