pi-legion 3.1.0 → 5.0.0

package/CHANGELOG.md

@@ -11,6 +11,382 @@ summary so you can see **2.x vs 0.16** without leaving the tree.
 
 ## [Unreleased]
 
+## [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
+everything else that landed on `master` while that removal was held back: a
+launch admission queue that queues instead of refusing, one liveness verdict
+shared by every display surface, a status panel built on pid / rss /
+context-token data, and ten measured performance fixes.
+
+### Breaking
+
+- **Kinds collapse to `pi`.** `AGENT_KINDS` is now `["pi"]`; the
+  `cursor` / `claude` / `codex` / `gemini` and other third-party CLI kinds are
+  gone, and with them the `cursorModel` / `nativeModelFor` / `planKindStart`
+  model translation and the "model dropped, runs on its own default" notice
+  (a `pi` child expresses every model, so the case no longer exists). `kind` is
+  still a legal frontmatter key, but `pi` is the only accepted value: a non-`pi`
+  value is ignored — one note on stderr per role (deduplicated, because the
+  catalog is re-read on several UI paths) naming the role and the original
+  value — and the role launches as `kind: pi`. The same applies to
+  `subagents.presets.<role>.kind` and `subagents.agentOverrides.<role>.kind`,
+  the three places a role's `kind` can come from. No legacy prefix aliases.
+- **Herdr backend removed.** `src/backends/legacy/` and `test/legacy/` are
+  deleted, together with the deprecated `pi-legion/api` re-exports that only
+  served them (`createHerdrClient`, `parseHerdrResponse`, `mapHerdrErrorCode`,
+  `readPaneDiagnostic`, `createCommandRunner`, `resolveHerdrBin`, `HerdrClient`
+  and their types). `pi-legion@0.16.x` stays the pin for the Herdr-era
+  execution model; the `spawnMode: rpc` / `inprocess` backends are unaffected —
+  those are two ways of running **Pi**, not third-party transports.
+- **Dead `herdr.*` settings removed.** `subagents.herdr.*` is no longer parsed
+  (a leftover block is silently ignored, as it has been ignored since 2.0.0),
+  the seven `herdr` constants are gone from `DEFAULTS`, and
+  `ErrorCodes.HERDR_UNAVAILABLE` / `ErrorCodes.PANE_BUSY` are removed.
+  `RunRecord.herdr` and `StatusEntry.herdrStatus` stay: they carry live
+  `{supervisor, node_id}` state, not backend selection.
+
+### Added
+
+- **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.
+
+
+- **One liveness verdict for every display surface (#liveness).** The list, the
+  text view and the railway chart each decided "is this agent still working?"
+  their own way, and the railway one compared two clocks that no single writer
+  owned: `eventOverrides` vetoed an event against `node.updatedAt`, but the
+  event row is stamped by this process's event bus while `updatedAt` is stamped
+  by the child's heartbeat — and only `isAlive` children are heartbeaten, so a
+  dead child's `updatedAt` freezes. The comparison ranked two clocks and the
+  losing side was the truthful one: a finished node was repainted `running`,
+  forever, because the frozen row never moved again. `src/extension/liveness.ts`
+  replaces all three with one `liveness(facts)` in TOTAL ORDER — `live` /
+  `dead` / `unknown` — with no clock, no fs and no timer of its own. Unknown or
+  unrecognized states now render `unknown` instead of being guessed into
+  `retired`, and `queued` is a first-class display state.
+  - Contract: `docs/contracts/display-liveness-v1.md` (frozen first, then
+    implemented; D1-a and D5-a record two amendments found during the work).
+
+- **A status panel on the `/legion` board (#241, #245).** A fifth pane carries
+  the `/legion status` table onto the full-screen viewer — name · role · state ·
+  supervisor · ctx · rss · turns — graded down by absolute column count
+  (72/52/36/20) so a narrow board keeps name · state instead of a column of
+  stubs. A portrait layout gets a zero-area rect and Tab skips it rather than
+  painting a fifth pane that cannot fit. Only an `rpc` child owns a process, so
+  only it shows rss; an `inprocess` child shows `—` rather than a share of the
+  host figure it does not own, because a fabricated number would get used.
+  - `pid`, `spawnMode`, `contextTokens` and `rss` are optional on `VizNode` and
+    projected conditionally: a missing mode renders `unknown`, never a guessed
+    `rpc`. No new `legion.db` column and no schema-version bump — pid is
+    host-scoped and never persisted, so a rebuild from a `ChildRecord` invents
+    none.
+  - Context tokens are absolute only. Session JSONL carries no context window,
+    so no percentage is computed and none is displayed.
+  - `/legion status` also stopped dropping `spawnMode` and now supplies `owner`.
+
+- **`/legion stop --force` (#179).** The TUI slash command can now hard-retire a
+  child, equivalent to the tool's `force: true`; `--force` / `-f` is listed in
+  the doctor help and the README. This closes the "optional follow-up" that the
+  docs had been carrying.
+
+- **`vexillatio` accepts `tasks[]` on its own.** `task` was required, so a
+  `{tasks: [...]}` call was rejected by the host's typebox pre-validation before
+  Legion ever saw it, and callers had to send a dummy `task` and retry. It is
+  optional now; a `tasks[]`-only launch is legal.
+
+### Changed
+
+- **WAL is now an enforced startup precondition (#236).** `openLegionDb` used to
+  discard the value returned by `PRAGMA journal_mode = WAL`. That PRAGMA is a
+  *query*: the returned mode is the ground truth, and SQLite is entitled to
+  answer with the mode it settled on rather than to fail — which is how a
+  connection ends up on a rollback journal while every reader of the code
+  believes WAL is live. The ledger's durability reasoning (single-writer
+  serialisation, readers that never block the writer, the shutdown checkpoint)
+  rests entirely on WAL, so the observed mode is now captured and verified: a
+  file database that does not report `wal` throws at startup, with the observed
+  mode in the message, instead of surfacing later as data loss. `:memory:` is
+  exempt deliberately, keyed on `PRAGMA database_list` reporting an empty
+  `file` — not on a database name, and not by accident.
+  - The M2-(g) concurrency acceptance now runs as `npm run test:wal-stress`:
+    60 supervisor processes against one ledger, 9004 attempts, 9004 commits, 0
+    busy, p50 1.03 ms / p95 1.99 ms / p99 4.92 ms.
+
+- **The worker role's turn budget is 45 minutes, not 30.** The worker does the
+  heaviest per-dispatch work — several files, its own verification run, and a
+  report — yet it shared centurion's budget while scout gets 10 minutes and
+  reviewer 15. Two dispatches in this repository were cut off mid-work, one
+  with nothing on disk and one that ran out while verifying. 45 rather than 60
+  keeps a genuinely stuck child from holding a concurrency slot for an hour.
+  Only `timeoutMs` changed.
+
+### Fixed
+
+- **A poison event row no longer freezes the cross-process event poller
+  (#233).** `node_abandoned` was missing from the event-type closed set, so a
+  snapshot row of that type could not be decoded; the 250 ms poller then threw
+  on the same row forever, its cursor never advanced, and no later event was
+  ever delivered. The closed set now contains `node_abandoned` (15 types), and
+  the poller advances past a single poison row instead of freezing: the row is
+  reported once through `onError`, the cursor steps over it, and the remaining
+  events in that batch are still delivered.
+
+- **A finished supervisor's pid is no longer read as its successor's (#250).**
+  `rss` probes re-read `/proc/<pid>` after the child had exited, and Linux
+  reuses pids; the panel could attribute a stranger's memory to a retired node.
+  The probe now closes the race it was silently losing.
+
+- **The log view stays inside its rect on narrow panes (#251).** `drawLog` wrote
+  past its own `maxX` when the pane was squeezed, which corrupted the frame
+  beside it.
+
+- **The live overlay no longer scans the whole tree per token (#261).** A
+  per-token `getTreeNodes()` call made a long child turn quadratic in the number
+  of nodes; the scan is gone and re-opening the node that is already open is
+  guarded.
+
+- **Repository subdirectories are no longer mistaken for child worktrees
+  (#237 P10).** The probe treated any git-visible path below the repo root as an
+  existing worktree, so a dispatch from `src/` could reuse the wrong directory.
+  All git probes are now bounded: `GIT_PROBE_TIMEOUT_MS = 5_000` and
+  `GIT_WORKTREE_TIMEOUT_MS = 120_000`, so a hung `git` can no longer wedge a
+  launch forever.
+
+- **`SubagentError` is exported explicitly again.** It had reached
+  `pi-legion/api` only as a side effect of the legacy client re-exporting it, so
+  removing the Herdr backend silently dropped it from the public surface. It is
+  a deliberate export now, pinned by a test.
+
+### Performance
+
+Ten fixes measured against the baseline in `docs/performance-2026-10-19.md`,
+plus the harness that measured them (#239). Numbers below are the before/after
+from each fix's own commit.
+
+- **`collect()` no longer waits out a fixed settle-quiet window (#232).** An
+  already-settled turn cost a flat ~2.5 s of dead time; that wait is dropped when
+  the turn is settled (2509 ms → 503 ms).
+- **The settle polls back off instead of re-parsing every 500 ms (#232).** The
+  transient-connection wait re-parsed the whole session file on every tick. It
+  now keeps the last parse, re-parses only when the artifact size moved, and
+  backs off 500 ms → 4 s. On an unchanged file in a 900 s window: 1800
+  iterations / 1804 parses → 228 iterations / 5 parses. The blip tolerance is
+  unchanged — sleeps are clamped to the remaining budget and the loop still ends
+  exactly on the deadline.
+- **The `/legion` log view reads the session incrementally (#234).** It seeks
+  past the cached byte offset and projects only the new JSONL lines, instead of
+  re-parsing from the top on every refresh.
+- **`attachUsageTotals` is one batched query (#235/#248).** It accounted for
+  ~72% of the cost of a UI snapshot; it is now a chunked `IN` query instead of a
+  per-node round trip.
+- **Heartbeats are one transaction (#236 P1).** N children meant N commits;
+  eight children now cost one (3.83 ms → 0.99 ms, 3.9×).
+- **Prepared statements are cached per connection (#236 P2).** `getNode` ×400
+  drops 15.7 ms → 4.8 ms.
+- **Session parsing projects its result instead of `structuredClone` (#237 P7).**
+- **The DB event source seeds its cursor at attach instead of replaying the log
+  (#238).** Attaching used to block ~1027 ms on replay.
+- **Widget events are coalesced into one snapshot and one paint per tick
+  (#238).** `legion-tools` emits N `mail_sent` events in one synchronous loop, so
+  every burst cost 2N scans; a burst now costs a constant 2 snapshots — 2575 ms
+  → 4.4 ms for 1000 events over a 120-node ledger. `applyTreeEvent` itself still
+  runs synchronously, per event, in arrival order: it is an incremental state
+  machine, not a render, so deferring or reordering it would change the state it
+  computes.
+- **The messages rate-limit `COUNT` is covered by an index (#237 P9).** 50k rows
+  go from a `SCAN` to ~6.6 µs.
+
 ## [3.1.0] — 2026-10-19
 
 ### Added
@@ -436,12 +812,16 @@ First **Pi Legion** line on headless Pi RPC. Relative to the final Herdr-era
 
 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.
+[Herdr transition](README.md#supported-kinds) 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/v3.0.2...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
 [3.0.2]: https://github.com/zzjcool/pi-legion/compare/v3.0.1...v3.0.2
 [3.0.1]: https://github.com/zzjcool/pi-legion/compare/v3.0.0...v3.0.1
 [3.0.0]: https://github.com/zzjcool/pi-legion/compare/v2.0.4...v3.0.0

package/CONTRIBUTING.md

@@ -107,10 +107,10 @@ 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
 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.
+so nesting / launch / collect stay covered without a live `pi`. The old
+herdr-era `createHerdrClient` / `createFakeRunner` helpers are **gone** as of
+v4.0.0, together with `src/backends/legacy/` and `test/legacy/`; everything
+runs as `kind: pi`, in-process or over `pi --mode rpc`.
 
 ## Mock LLM
 
@@ -161,19 +161,6 @@ Or all at once (RPC mainline **1–11** only):
 npm run test:docker
 ```
 
-**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`.
 
 Each `inside-N-*.sh` is what actually runs **in** the container. Keep those