pi-legion 2.0.4 → 3.0.1

package/CHANGELOG.md

@@ -11,6 +11,100 @@ summary so you can see **2.x vs 0.16** without leaving the tree.
 
 ## [Unreleased]
 
+## [3.0.1] — 2026-10-18
+
+### Fixed
+
+- **Published manifest no longer ships a `preinstall` hook.** 3.0.0 added a
+  pnpm-only `preinstall` guard meant for repository contributors, and npm always
+  packs `package.json`, so the hook shipped to every consumer. Pi installs
+  extensions with `npm install <spec> --prefix <agentDir>/npm --legacy-peer-deps`,
+  so `pi update --extensions` failed with
+  `Use pnpm to install dependencies (see CONTRIBUTING.md).` — npm exited 1 and
+  rolled the previously installed version back, which left the
+  "Package Updates Available" notice pointing at the same outdated version on
+  every start. The pnpm-only intent now lives in `devEngines.packageManager`,
+  which npm enforces for the repository root (`EBADDEVENGINES`) and ignores when
+  the package is installed as a dependency. The repository keeps all of its
+  contributor tooling declarations: `packageManager`, `engines.pnpm` and
+  CONTRIBUTING.md are unchanged. (Note: `pnpm pack` omits `packageManager` from
+  the tarball, which only affects that dev-only field in the published manifest —
+  npm consumers install and load the extension normally.)
+- `test/unit/publish-manifest.test.ts` guards the published manifest against
+  install-phase scripts (`preinstall` / `install` / `postinstall`) and asserts the
+  pnpm requirement stays declared, so this cannot ship again silently.
+- `release.yml` now fails the tag build when a published install-phase script was
+  reintroduced, before anything is staged.
+
+## [3.0.0] — 2026-10-18
+
+### Added
+
+- In-process `AgentSession` spawn mode (#197): `spawnMode: "rpc" | "inprocess"`,
+  `InProcessSupervisor` + `RoutingSupervisor`, and separate
+  `subagents.inprocess.*` limit keys. See `docs/inprocess-supervisor.md`.
+
+### Changed
+
+- **BREAKING (#197):** `spawnMode` now defaults to `inprocess`, not `rpc`.
+  When the key is omitted and the resolved spawn needs an OS worktree
+  (`worktree: true` — the writer/centurion default), Legion falls back to
+  `rpc` automatically. Non-`pi` roles are unaffected by this fallback: they
+  are refused with `INVALID_PARAMS` before the backend is chosen, because
+  only `kind: pi` children are supported at all. An explicit
+  `spawnMode: "inprocess"` combined with `worktree: true` is still refused
+  with `INVALID_PARAMS` — the fallback only covers the implicit default.
+- **BREAKING (#197):** omitting the whole `subagents.inprocess` block no
+  longer means "unlimited". The in-process supervisor now falls back to the
+  `legion.*` defaults (`maxDepth: 4`, `maxChildrenPerNode: 8`,
+  `maxActive: 30`); an explicit block that omits `maxActive` still gets 8.
+  `maxSpawnsPerSession` / `waitTimeoutMs` keep no default.
+- #197 in-process children read their identity (node id, db path, acceptance
+  role, nesting budget) from an AsyncLocalStorage child context instead of
+  `PI_SUBAGENT_*` / `PI_LEGION_*` env. In-process sessions share the parent's
+  `process.env`, so the env channel delivered the parent's values — or none at
+  all in a root parent — and mis-scoped read-only role enforcement. ALS does
+  not cross `spawn()`, so `bash` subprocesses can no longer inherit a tree
+  identity.
+- TUI: drop the footer `N agents running` segment (#192); the aboveEditor
+  widget already shows the same count. `STATUS_FOOTER_KEY` / `formatFooterStatus`
+  remain exported but `@deprecated` (soft-land).
+- Railway lane clock: the leading clock is now "time since the last task
+  started" — it keeps ticking through the quiet gap after a turn settles
+  (previously it froze at that turn's end, i.e. the *previous* task's elapsed)
+  and freezes only when the agent itself ends.
+- Railway lane clocks show from round 1. #159 gated them behind `turns >= 2`,
+  but a child is usually dispatched with a single user message, so that gate
+  hid the clocks almost always and starved the detail column.
+- Round 1 prints one clock, not two: that turn starts with the agent, so
+  `16s / 17s` was one fact plus the spawn gap.
+- Railway column is content-driven: the right-hand name/detail block takes what
+  the labels need and the time axis absorbs the rest (floor
+  `RAIL_AXIS_MIN_COLS`), so a row fills the line instead of trailing blanks.
+
+### Fixed
+
+- Dropped the `now` / `live` wording from every tok/s surface. "now" meant two
+  different things at once (the live-only header rate vs. the chart's x-axis
+  right edge), which read as a bug; the stat row key is now `rate`.
+- Rail lane detail drops a field for *every* lane when it fits none, instead of
+  stripping the role from one long-named row only.
+- `make rebuild` rebuilds the sandbox image and swaps the container.
+- Real-model sandbox: children get `PI_LEGION_CHILD_EXTENSIONS` so they load
+  the provider package (#43) — without it every subagent failed with
+  `Unknown provider "any-endpoint"`.
+- Subagent detail modal: the area around the frame is no longer black. It was
+  mounted as a full-screen overlay, and pi-tui composites an overlay by
+  discarding every base cell in its rectangle (there is no transparency option),
+  so the viewer's own dim-mask spaces were erasing the host chat / `/legion`
+  view and leaving the terminal's default background. The overlay now covers the
+  frame rect only, so the host paints everything around it (#193).
+  - Geometry is a percentage width with no `maxHeight`, so pi-tui re-derives the
+    rect every frame; absolute cells froze at the open-time terminal size and
+    clipped the frame's bottom border and Esc hint after a resize.
+  - "Click the mask to dismiss" is gone — clicks outside the frame now reach the
+    host, as they should. Esc and the title-bar Esc hint still close the modal.
+
 ## [2.0.4] — 2026-10-15
 
 ### Added
@@ -164,7 +258,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/v2.0.4...HEAD
+[Unreleased]: https://github.com/zzjcool/pi-legion/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/zzjcool/pi-legion/compare/v2.0.4...v3.0.0
 [2.0.4]: https://github.com/zzjcool/pi-legion/compare/v2.0.3...v2.0.4
 [2.0.3]: https://github.com/zzjcool/pi-legion/compare/v2.0.2...v2.0.3
 [2.0.2]: https://github.com/zzjcool/pi-legion/compare/v2.0.1...v2.0.2

package/CONTRIBUTING.md

@@ -21,13 +21,13 @@ directly to `master`. Implementers do not merge their own pull requests.
 **Before you push.** Run:
 
 ```bash
-npm run typecheck
-npm test
-npm run test:integration   # or npm run test:all
+pnpm run typecheck
+pnpm test
+pnpm run test:integration   # or pnpm 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
+mock-llm. Run `pnpm run test:integration` (or `pnpm run test:all`) locally
 before you push, especially when the change touches `src/runs/`, `src/legion/`,
 or `src/extension/runtime.ts`.
 
@@ -45,9 +45,10 @@ timeout the caller is awaiting stays referenced, as with the wait timer in
 `src/extension/runtime.ts`.
 
 **npm release.** A `v*.*.*` tag runs the release workflow
-(`.github/workflows/release.yml`). Publish from that workflow with
-`npm stage publish` and a stage-only token. A maintainer promotes the staged
-version on npm with 2FA. Do not use plain `npm publish` in GitHub Actions.
+(`.github/workflows/release.yml`). Dependencies are installed with **pnpm**;
+staging still uses the npm CLI (`npm stage publish`) and a stage-only token.
+A maintainer promotes the staged version on npm with 2FA. Do not use plain
+`npm publish` in GitHub Actions.
 
 **Communication.** Coordinate in the team channel, or with Alice. Do not ping
 the maintainer user for a routine review or merge ask.
@@ -57,34 +58,36 @@ the maintainer user for a routine review or merge ask.
 ```bash
 git clone https://github.com/zzjcool/pi-legion.git
 cd pi-legion
-npm install
+pnpm install
 ```
 
-Requires Node.js 22+ (`node --experimental-strip-types` is how tests run;
-there is no compile step to ship).
+Requires Node.js 22+ and **pnpm** 9+ (`packageManager` in `package.json`;
+`node --experimental-strip-types` is how tests run; there is no compile step
+to ship). Prefer Corepack (`corepack enable`) or install pnpm 9.x. Do not use
+`npm install` in this repo.
 
 ## 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`
+1. `pnpm run typecheck`
+2. `pnpm test` (unit)
+3. `pnpm run test:integration`
+4. `pnpm 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 # 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
+pnpm run typecheck
+pnpm test                 # test/unit/*.test.ts
+pnpm run test:integration # FakeSupervisor / nested fakes; no live `pi` binary
+pnpm run test:all         # typecheck + unit + integration
+pnpm run test:mock-llm    # also part of the required ci check
 ```
 
-`npm run test:live` is a **pi RPC live** smoke (`test/live/rpc-live.test.ts`).
+`pnpm 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.
 
@@ -102,8 +105,8 @@ For offline Pi / legion smoke without provider quota, start the scriptable
 OpenAI-compatible mock (see [`test/mock-llm/README.md`](test/mock-llm/README.md)):
 
 ```bash
-npm run mock-llm                 # default scenario=echo on :8765
-npm run test:mock-llm            # engine + HTTP + optional pi --print smoke
+pnpm run mock-llm                 # default scenario=echo on :8765
+pnpm run test:mock-llm            # engine + HTTP + optional pi --print smoke
 ```
 
 `test/docker/mock-llm.mjs` launches the same CLI (default scenario `tool-once`
@@ -142,12 +145,12 @@ bash test/docker/verify-11-nested-alias.sh    # nested + alias + completionGuard
 Or all at once (RPC mainline **1–11** only):
 
 ```bash
-npm run test:docker
+pnpm 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`:
+`pnpm run test:docker`:
 
 ```bash
 bash test/legacy/docker/verify-12-workspace.sh  # Herdr Space pin (legacy)

package/README.md

@@ -20,6 +20,8 @@ shared SQLite ledger records the whole tree.
 ## Contents
 
 - [Architecture](#architecture)
+- [Spawn mode](#spawn-mode)
+- [Headless child contract](#headless-child-contract)
 - [Quick start](#quick-start)
 - [Legion tools and phases](#legion-tools-and-phases)
 - [Three-layer visualization](#three-layer-visualization)
@@ -63,6 +65,50 @@ 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
+
+`spawnMode` picks the backend that runs one child. Per role it comes from agent
+frontmatter → `subagents.agentOverrides.<role>` → team member override:
+
+```yaml
+# agents/scout.md
+---
+spawnMode: inprocess   # or: rpc
+---
+```
+
+**Default:** omitting `spawnMode` means `inprocess` — the child runs as an
+`AgentSession` inside the parent Node process (`createAgentSession`), which
+trades process isolation for spawn latency.
+
+**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` — the writer
+and centurion default). A `kind !== "pi"` role is rejected earlier with
+`INVALID_PARAMS` (only `kind: pi` children are supported at all), so it never
+reaches this fallback.
+
+**Explicit is strict:** `spawnMode: "inprocess"` with `worktree: true` is
+refused with `INVALID_PARAMS` rather than silently downgraded, so a role that
+asks for in-process never gets a different transport behind its back.
+
+Limits for the in-process backend are separate (`subagents.inprocess.*`) and are
+not shared with the `legion.*` tree budgets — see
+[docs/inprocess-supervisor.md](docs/inprocess-supervisor.md).
+
+## Headless child contract
+
+Legion children on the **`rpc` backend** are rpc only (`pi --mode rpc`).
+Headless modes have no
+interactive tool-approval UI. Project `.pi/settings.json` / project extensions
+load under headless only after `/trust` (or `defaultProjectTrust=always`), or
+when you opt in with `subagents.rpc.approve: true` (appends `--approve`). Legion
+`onBlocked` is a parent subagent block strategy — **not** a pi tool-approval
+replacement; keep the layers separate.
+
+Full mapping (exit → `SettleResult` → node state) and the three upstream headless
+modes vs legion: [docs/headless-child-contract.md](docs/headless-child-contract.md).
+
 ## Quick start
 
 Install and load the extension in Pi:
@@ -109,7 +155,8 @@ 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.
+sequence for each selected child. Pass `force: true` to escalate to hard retire
+when a child ignores soft steer / graceful close.
 
 ### Stopping async subagents yourself
 
@@ -123,6 +170,16 @@ shutdown); process exit / session shutdown also retires:
   parent (stop the parent to retire them).
 - **`x`** on the selected live agent in the `/legion` view or its live
   overlay asks `y` to confirm in place, then stops it.
+- **Tool**: `subagent({ action: "stop", name })` is graceful; pass
+  `force: true` for hard retire (SIGTERM → SIGKILL + descendant sweep per
+  `docs/retire-hardening-contract.md`). Example:
+  `subagent({ action: "stop", name: "worker-0", force: true })`.
+  TUI `/legion stop --force` is an optional follow-up (same `force: true`).
+
+**`wait` ≠ stop.** A `wait` timeout (or still-running result) does **not**
+retire children. The tool result includes live child names, elapsed ms, and
+suggested decisions (`extend` / `steer_again` / `stop` / `force_stop`); the
+parent chooses the next tool call. See `docs/contracts/wait-not-stop.md`.
 
 While subagents are live, the railway header can show a dim
 `/legion stop [name|all]` hint (shortened on narrow terminals; idle gating /
@@ -182,10 +239,15 @@ commands without an LLM. Passing verification advances the squad to `done`.
 1. **Railway strip above the input:** one git-graph lane per live subagent
    (max 4, 3 below 80 columns; oldest/shallowest first, `+N` for the rest).
    When an agent ends its lane merges back and lower lanes shift up. The
-   header shows the live count and tok/s (trailing 60s average). Hidden when
-   no subagent is live. Set `PI_LEGION_STRIP=tree` for the classic roster.
+   header shows the live count and tok/s (trailing 60s average). The lane
+   label reads `role · <time since the last task started> / <lifetime> · <age
+   of last activity>`; the leading clock keeps ticking through the quiet gap
+   after a turn settles and freezes only when the agent itself ends. The lane
+   column is measured from what the labels need and the time axis takes the
+   rest (down to a floor), so a row always fills the line. Hidden when no
+   subagent is live. Set `PI_LEGION_STRIP=tree` for the classic roster.
 2. **`/legion` full view:** galaxy graph of the agent tree, stacked tok/s
-   chart by agent type (peak marker, now/avg/peak/total, per-role share), and
+   chart by agent type (peak marker, rate/avg/peak/total, per-role share), and
    a scrollable `log --graph` history. Tab switches panes, arrows scroll or
    move the selection, Enter selects an agent (its own rate line, tok/s,
    tokens and share are overlaid), `o` opens its live overlay, `x` stops it
@@ -285,9 +347,20 @@ per-member overrides. Object member overrides (for example `model` or
 omitted override fields continue to use their normal role/configuration
 values.
 
-See [docs/subagents-teams.md](docs/subagents-teams.md) for four editable
-frontend/backend × premium/value team templates. The model IDs in that template
-are placeholders for your provider, not required defaults.
+Teams may also set optional `parentContext` / `childContext` (same value forms
+as the global keys, including `@path` and `false`). When the active team
+defines a side, that value **replaces** the global context for that side — it
+does not merge. Omit the field to fall back to global (or convention files);
+set `false` to disable that side with no fallthrough. Unknown team names keep
+today's warn + full roster behaviour and still use global context.
+
+See [docs/subagents-teams.md](docs/subagents-teams.md) for editable
+frontend/backend team templates with **distinct workflow text** (not only
+different models). The model IDs in that template are placeholders for your
+provider, not required defaults. For running a multi-agent QA hunting round in
+this repo, see [docs/qa-hunting-round.md](docs/qa-hunting-round.md) (round
+orchestration) and [docs/tui-qa-playbook.md](docs/tui-qa-playbook.md)
+(evidence rules).
 
 ### Parent/child context conventions
 
@@ -296,8 +369,11 @@ inline or through `@path` references. If either setting is omitted, Legion
 looks for `subagents-parent-context.md` or `subagents-child-context.md`
 respectively in the directory containing that settings file. These are
 convention-based fallbacks: an explicit setting takes precedence, and setting
-either field to `false` disables its context. The convention filenames are
-`PARENT_CONTEXT_CONVENTION` and `CHILD_CONTEXT_CONVENTION` in
+either field to `false` disables its context. Named teams can override each
+side via `subagents.teams.<name>.parentContext` /
+`childContext` (replace, never merge; see [Team 配置](#team-配置)). The
+convention filenames are `PARENT_CONTEXT_CONVENTION` and
+`CHILD_CONTEXT_CONVENTION` in
 [`src/agents/settings.ts`](src/agents/settings.ts#L30-L31); missing convention
 files simply contribute no context. The repository examples are
 [`examples/subagents-parent-context.md`](examples/subagents-parent-context.md)
@@ -311,7 +387,7 @@ 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`,
-  `spawn`, `memory`, `tools`, `storage`, `runtime`, `next`.
+  `spawn`, `memory`, `tools`, `storage`, `runtime`, `errors`, `next`.
 - `subagent({ action: "diagnose" })` — same full report as tool output so the
   main agent can call it without waiting for you. The tool has no section
   field; filter with `/legion doctor [section]`.
@@ -326,6 +402,12 @@ snippet (relevant sections + Next steps) so the main agent can self-fix
 without anyone typing `/legion doctor`. Full `/legion doctor` remains for
 manual deep dives.
 
+**Session errors (#160):** tool validation / call failures from `subagent`
+(and similar) append to `.pi-subagents/session-errors.jsonl` (JSONL, rotated
+to ~500 lines). `/legion doctor` / `diagnose` show counts, by-code tallies,
+and the last few one-line titles under the `errors` section; when the log is
+large they print only that summary plus the log path.
+
 Coverage:
 
 | Section | What it checks |
@@ -337,6 +419,7 @@ Coverage:
 | 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 |
+| errors | Recent session/tool errors (validation failures, etc.) as a short summary; full journal at `.pi-subagents/session-errors.jsonl` (rotated ~500 lines). Large logs: summary + path only — doctor never dumps the whole file |
 
 ### Child extensions
 
@@ -439,11 +522,11 @@ another CLI, keep it on the 0.16.x line or replace it with a Pi role.
 ## Development
 
 ```bash
-npm install
-npm run typecheck
-npm test                  # unit tests
-npm run test:integration  # integration tests
-npm run test:all          # typecheck + unit + integration tests
+pnpm install
+pnpm run typecheck
+pnpm test                  # unit tests
+pnpm run test:integration  # integration tests
+pnpm run test:all          # typecheck + unit + integration tests
 ```
 
 ### Mock LLM (offline pi / legion smoke)
@@ -453,9 +536,9 @@ It registers with Pi like any local gateway (`models.json` → `api: "openai-com
 so spawn / stop / doctor / verify paths can run without real API keys:
 
 ```bash
-npm run mock-llm                 # http://127.0.0.1:8765/v1  scenario=echo
-npm run test:mock-llm            # unit + integration smoke for the mock
-MOCK_LLM_SCENARIO=spawn-scout npm run mock-llm
+pnpm run mock-llm                 # http://127.0.0.1:8765/v1  scenario=echo
+pnpm run test:mock-llm            # unit + integration smoke for the mock
+MOCK_LLM_SCENARIO=spawn-scout pnpm run mock-llm
 ```
 
 Use `writeMockPiHome()` from `test/mock-llm` to generate an isolated
@@ -463,7 +546,8 @@ Use `writeMockPiHome()` from `test/mock-llm` to generate an isolated
 `auth.json` into fixtures.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md#project-workflow) for the project
-workflow: issues, pull requests, the merge gate, and npm releases.
+workflow: issues, pull requests, the merge gate, and releases
+(deps via pnpm; npm stage publish for staging).
 
 Version history for consumers: [CHANGELOG.md](CHANGELOG.md). Tag-by-tag
 release bodies: [GitHub Releases](https://github.com/zzjcool/pi-legion/releases).

package/docs/contracts/osc-busy-plugin.md

@@ -0,0 +1,72 @@
+# OSC 7501 busy / plugin contract (pi-legion #156)
+
+Legion keeps the **root** program-status record `working` while any live child
+or registered extension activity remains. OSC truth is owned by Pi's
+`ProgramStatusReporter` — **plugins and legion must not `printf` OSC 7501**.
+
+## Handshake
+
+- Terminals may answer `OSC 7501;?` / `PI_PROGRAM_STATUS=1`.
+- Prefer Pi APIs (`ui.setActivity`, `ui.setProgramRecord`). Do not emit raw OSC.
+
+## Plugin / child-side rules
+
+1. **Raise**: while async work is unfinished →
+   `ui.setActivity(source, { message })` and/or
+   `ui.setProgramRecord({ id, state: "working", message })`.
+2. **Clear**: on settle / cancel / error →
+   `ui.setActivity(source, undefined)` and
+   `ui.setProgramRecord({ id, state: "clear" })`.
+3. **Ids**: use a stable hierarchical id (`plugin/<name>/…` or
+   `legion/<slug>`). Do **not** write an id-less root `working` that steals
+   Pi's root semantics — register an activity source or a child id.
+4. **RPC children**: in RPC mode, Pi forwards `ui.setActivity` /
+   `ui.setProgramRecord` as `extension_activity` to the parent. Legion folds
+   those into the parent reporter (`legion/<child>/<source>`). **Do not**
+   parse child PTY OSC bytes.
+
+## Legion aggregation
+
+| Source | Mechanism |
+|--------|-----------|
+| Live RPC child | `emitBusy` → `ui.setActivity("legion", …)` + per-child `id=legion/<slug>` |
+| Child-side plugin busy | RPC `extension_activity` → parent `setActivity` / `setProgramRecord` |
+| Same-process plugin | Direct `ui.setActivity` / `setProgramRecord` |
+
+Root stays `working` while any activity source or uncleared `legion/*` child
+id remains. `/legion stop` and runtime dispose clear the legion source and
+child ids. **Esc** (wait interrupt) does **not** clear activity.
+
+Priority inside Pi (unchanged): `blocked` > compacting > (`runActive` OR
+`activities.size > 0` → root `working`) > resting (`done`/`idle`/`error`).
+
+## Mock example (copy-paste)
+
+```ts
+// Same-process plugin / test double
+ui.setActivity?.("plugin/bg-tasks", { message: "2 background tasks" });
+ui.setProgramRecord?.({
+  id: "plugin/bg-tasks/job-1",
+  state: "working",
+  message: "job-1",
+});
+
+// …work finishes…
+ui.setProgramRecord?.({ id: "plugin/bg-tasks/job-1", state: "clear" });
+ui.setActivity?.("plugin/bg-tasks", undefined);
+```
+
+Parent-side mock of a child fan-in (what legion does after RPC):
+
+```ts
+// Child "scout" raised setActivity("bg", { message: "compiling" })
+ui.setActivity("legion/scout/bg", { message: "compiling" });
+// Child cleared
+ui.setActivity("legion/scout/bg", undefined);
+```
+
+## Non-goals
+
+- Herdr / inbox OSC consumers
+- Parsing child stdout for OSC 7501
+- Big TUI railway/footer changes in this wave