pi-legion 0.16.0 → 2.0.1

package/CHANGELOG.md

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

package/CONTRIBUTING.md

@@ -4,6 +4,54 @@ This package is a Pi extension. The public surface is `index.ts` (the
 `subagent` tool) plus `src/api.ts` (programmatic imports). Please keep those
 two as the only things a downstream should need.
 
+## Project workflow
+
+**Issues first.** A bug or feature found while dogfooding starts as a GitHub
+issue. Include a repro, the expected behaviour, the actual behaviour, and the
+environment (Node version, OS, and the Pi / pi-legion version).
+
+**One concern per pull request.** Link the issue. Open the PR as a draft.
+Mark it **Ready for review** when the change is ready and you expect the
+required check `ci` to pass.
+
+**Merge gate.** Alice (the maintainer bot) merges only after code review has
+passed and the required GitHub Actions check `ci` is green. Do not push
+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
+```
+
+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.
+
+**Regression tests.** When you fix a bug, add a unit or integration test in
+the same PR when that is feasible: failing first, then passing. Do not
+`unref()` a timer that must keep the Node test runner alive. `unref()` drops
+the timer from the event-loop refcount, so `node --test` can exit before the
+callback runs. That is the rpc-supervisor retire-timer lesson (`waitForExit`
+and the descendant-sweep delay in `src/supervisor/rpc-supervisor.ts`): a
+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.
+
+**Communication.** Coordinate in the team channel, or with Alice. Do not ping
+the maintainer user for a routine review or merge ask.
+
 ## Setup
 
 ```bash
@@ -17,33 +65,68 @@ 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
+
+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
+```
+
+`test/docker/mock-llm.mjs` launches the same CLI (default scenario `tool-once`
+for legacy inside-*.sh). Point Pi at it with `writeMockPiHome({ baseUrl })` or
+the `providers.mock` block in that README. Never commit real API keys; the
+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
@@ -54,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`.
 
@@ -86,8 +176,9 @@ them by hand.
 | `src/extension/runtime.ts` | status widget, watch, auto-recycle |
 | `src/extension/blocked.ts` | `onBlocked` confirm / auto-approve / notify |
 | `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