pi-crew 0.9.55 → 0.9.57

package/docs/README.md

@@ -0,0 +1,54 @@
+# docs/ — documentation index
+
+pi-crew's documentation. After the v0.9.x reorg the **living/active** docs
+stay at the root of this directory; historical/retired docs live in
+[`archive/`](./archive/). Cluster maps for the code live in
+[`src/runtime/README.md`](../src/runtime/README.md) and
+[`src/state/README.md`](../src/state/README.md).
+
+## Living docs (root)
+
+| Doc | Contents |
+|-----|----------|
+| [`usage.md`](./usage.md) | Usage patterns + config examples |
+| [`commands-reference.md`](./commands-reference.md) | Slash commands + `/team-api` |
+| [`actions-reference.md`](./actions-reference.md) | Full tool actions + examples |
+| [`resource-formats.md`](./resource-formats.md) | Agent/team/workflow file formats |
+| [`architecture.md`](./architecture.md) | Internal architecture + run flow |
+| [`runtime-flow.md`](./runtime-flow.md) | Runtime execution details |
+| [`dynamic-workflows.md`](./dynamic-workflows.md) | `.dwf.ts` script runtime + trust model |
+| [`goals.md`](./goals.md) | Autonomous goal loops (`team action='goal'`) |
+| [`live-mailbox-runtime.md`](./live-mailbox-runtime.md) | Mailbox + live-session runtime |
+| [`troubleshooting.md`](./troubleshooting.md) | Common errors, recovery, error-code reference (E001–E012) |
+| [`publishing.md`](./publishing.md) | Release & publish process |
+| [`migration-v0.4-v0.5.md`](./migration-v0.4-v0.5.md) | Migration guide: v0.4 → v0.5 |
+| [`HARNESS.md`](./HARNESS.md) | Agent-testing harness operating model |
+| [`HARNESS_BACKLOG.md`](./HARNESS_BACKLOG.md) | Harness capability backlog |
+| [`FEATURE_INTAKE.md`](./FEATURE_INTAKE.md) | Feature-intake gate for implementation prompts |
+| [`TEST_MATRIX.md`](./TEST_MATRIX.md) | Behavior→proof mapping (every row needs real evidence) |
+| [`TEST-STRATEGY-2026-07-30.md`](./TEST-STRATEGY-2026-07-30.md) | v0.9.56 test strategy (coverage × test type) |
+| [`COVERAGE-ASSESSMENT-2026-08-01.md`](./COVERAGE-ASSESSMENT-2026-08-01.md) | v0.9.56 coverage assessment + source-reorg history |
+| [`AUDIT-2026-07-30.md`](./AUDIT-2026-07-30.md) | v0.9.56 comprehensive audit (6 parallel streams) |
+| [`REMEDIATION-PLAN-2026-07-30.md`](./REMEDIATION-PLAN-2026-07-30.md) | v0.9.56 remediation plan |
+
+## Subdirectories
+
+| Subdir | Contents |
+|--------|----------|
+| [`archive/`](./archive/) | Historical/retired docs (flat; ~59 files — audits, research, superseded plans) |
+| [`bugs/`](./bugs/) | Bug write-ups + security audit/issues |
+| [`decisions/`](./decisions/) | Architecture decision records (ADRs, numbered) |
+| [`distillation/`](./distillation/) | Distilled pattern/skill references |
+| [`fixes/`](./fixes/) | Bug-fix reports |
+| [`migration/`](./migration/) | Migration guides (e.g. atomic-write v2) |
+| [`patterns/`](./patterns/) | Reusable pattern references |
+| [`perf/`](./perf/) | Performance audits, sprint reports, optimization plans |
+| [`product/`](./product/) | Product-domain docs |
+| [`skills/`](./skills/) | pi-crew skills reference |
+| [`stories/`](./stories/) | Story-sized work packets |
+| [`superpowers/`](./superpowers/) | Fallow-patterns adoption plans |
+| [`templates/`](./templates/) | Decision / story / validation-report templates |
+
+See also the top-level [README.md](../README.md) and the source cluster maps
+([`src/runtime/README.md`](../src/runtime/README.md),
+[`src/state/README.md`](../src/state/README.md)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.55",
+  "version": "0.9.57",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -29,11 +29,10 @@
     "orchestration"
   ],
   "files": [
-    "*.ts",
-    "*.mjs",
     "src/",
     "dist/index.mjs",
-    "dist/build-meta.json",
+    "index.ts",
+    "install.mjs",
     "agents/",
     "teams/",
     "workflows/",
@@ -72,12 +71,12 @@
     "check:bundle-size": "node scripts/check-bundle-size.mjs",
     "check:conflict-markers": "node scripts/check-conflict-markers.mjs",
     "typecheck": "tsc --noEmit && node --experimental-strip-types -e \"await import('./index.ts'); console.log('strip-types import ok')\"",
-    "lint": "biome check --linter-enabled=true --formatter-enabled=false --max-diagnostics=50 --diagnostic-level=error .",
+    "lint": "biome check --linter-enabled=true --formatter-enabled=false --max-diagnostics=50 .",
     "format:check": "biome format .",
     "test": "npm run test:unit && npm run test:integration",
-    "test:unit": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=180000 --test-force-exit test/unit/*.test.ts",
-    "test:critical": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/crew-broker-handshake.test.ts test/unit/crew-broker-stale-socket.test.ts test/unit/crew-broker-feature-flag.test.ts test/unit/crew-broker-server-gate.test.ts test/unit/crew-broker-client-fallback.test.ts test/unit/crew-broker-mailbox-observer.test.ts test/unit/crew-broker-close-during-reconnect.test.ts test/unit/crew-broker-steer-dedup.test.ts test/unit/crew-broker-symlink-steering.test.ts test/unit/keybinding-map.parity.test.ts test/unit/pi-tui-dispatch-probe.test.ts test/unit/session-utils-extract.test.ts test/unit/config-schema-sync.test.ts test/unit/child-pi-env-spread.test.ts",
-    "test:watch": "tsx --watch --test --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/*.test.ts",
+    "test:unit": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=180000 --test-force-exit 'test/unit/**/*.test.ts'",
+    "test:critical": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/runtime/broker/crew-broker-handshake.test.ts test/unit/runtime/broker/crew-broker-stale-socket.test.ts test/unit/runtime/broker/crew-broker-feature-flag.test.ts test/unit/runtime/broker/crew-broker-server-gate.test.ts test/unit/runtime/broker/crew-broker-client-fallback.test.ts test/unit/runtime/broker/crew-broker-mailbox-observer.test.ts test/unit/runtime/broker/crew-broker-close-during-reconnect.test.ts test/unit/runtime/broker/crew-broker-steer-dedup.test.ts test/unit/runtime/broker/crew-broker-symlink-steering.test.ts test/unit/ui/keybinding-map.parity.test.ts test/unit/ui/pi-tui-dispatch-probe.test.ts test/unit/utils/session-utils-extract.test.ts test/unit/config/config-schema-sync.test.ts test/unit/runtime/child-pi/child-pi-env-spread.test.ts",
+    "test:watch": "tsx --watch --test --test-concurrency=4 --test-timeout=30000 --test-force-exit 'test/unit/**/*.test.ts'",
     "test:integration": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=300000 test/integration/*.test.ts",
     "test:smoke": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 test/smoke/*.smoke.ts",
     "build:bundle": "node scripts/build-bundle.mjs",
@@ -90,7 +89,7 @@
     "build:crew-font": "python scripts/build-crew-vibes-font.py",
     "bench": "node scripts/run-bench.mjs",
     "bench:check": "node scripts/bench-check.mjs",
-    "test:new": "tsx --test --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/*.test.ts",
+    "test:new": "tsx --test --test-concurrency=4 --test-timeout=30000 --test-force-exit 'test/unit/**/*.test.ts'",
     "test:changed": "node scripts/test-changed.mjs",
     "bench:capture": "node scripts/run-bench.mjs && node -e \"require('node:fs').copyFileSync('test/bench/results.json','test/bench/baseline.json')\"",
     "profile:startup": "node scripts/profile-startup.mjs",
@@ -130,10 +129,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.3",
-    "@earendil-works/pi-agent-core": "^0.82.0",
-    "@earendil-works/pi-ai": "^0.82.0",
-    "@earendil-works/pi-coding-agent": "^0.82.0",
-    "@earendil-works/pi-tui": "^0.82.0",
+    "@earendil-works/pi-agent-core": "^0.83.0",
+    "@earendil-works/pi-ai": "^0.83.0",
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-tui": "^0.83.0",
     "@types/node": "^25.9.5",
     "tsx": "^4.23.0",
     "typescript": "^7.0.2"

package/skills/real-test-pi-crew/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: real-test-pi-crew
-description: "End-to-end verification for pi-crew changes: fast critical tests, 3-path kill-switch proof, bundle md5 sync, live TUI probing, and smoke team runs."
+description: "End-to-end verification for pi-crew changes: fast critical tests, 3-path kill-switch proof, bundle md5 sync, live TUI probing, smoke team runs, and a live feature-action battery (team tool + subagent tools)."
 origin: pi-crew
 triggers:
   - "test the change"
@@ -17,14 +17,20 @@ triggers:
   - "worker timeout"
   - "verifier hangs"
   - "rebuild and retry"
-  - "tier 1 / tier 2 / tier 3 / tier 4 / tier 5 / tier 6 / tier 7 / tier 8"
+  - "unknown type" tool error
+  - "validation failed for tool"
+  - "team tool broken"
+  - "schema fix"
+  - "feature battery"
+  - "full features of pi-crew"
+  - "tier 1 / tier 2 / tier 3 / tier 4 / tier 5 / tier 6 / tier 7 / tier 8 / tier 9"
 ---
 
 # real-test-pi-crew
 
 End-to-end verification discipline for pi-crew changes. Distilled from the broker Phase-4 rollout (commits `1cb2dca` → `d599578` → `612e18b` → `4186284`, July 2026). The pain this skill prevents: shipping code that compiles + unit-tests-green but breaks in the user's live Pi session, or hangs the verifier worker.
 
-**When to use**: after any change to `src/runtime/crew-broker*.ts`, `src/ui/`, `src/config/`, `src/extension/registration/lifecycle-handlers.ts`, `src/runtime/child-pi-spawn.ts`, `src/runtime/plan-templates.ts`, `workflows/*.workflow.md`, or before any commit touching these paths.
+**When to use**: after any change to `src/runtime/crew-broker*.ts`, `src/ui/`, `src/config/`, `src/extension/registration/lifecycle-handlers.ts`, `src/runtime/child-pi-spawn.ts`, `src/runtime/plan-templates.ts`, `src/schema/team-tool-schema.ts` (or any `Type.Unsafe({...})` schema definition), `src/extension/registration/team-tool.ts`, `workflows/*.workflow.md`, or before any commit touching these paths. Schema changes additionally require Tier 9 (feature battery) because the team tool's TypeBox schema is validated by pi-ai BEFORE the handler runs — a too-strict or malformed schema breaks every action silently.
 
 ## Core principle: disk ≠ live Pi
 
@@ -407,6 +413,8 @@ readlink ../node_modules/pi-crew/dist/index.mjs 2>/dev/null \
 
 If the two md5s match → session is on the latest code. If not → user must `/quit` + reopen Pi.
 
+> **Agent-inside-session caveat**: when the agent *doing the testing* runs inside the very Pi session under test, the agent **cannot restart its own session** — only the user can. Pattern that works: (1) edit source + rebuild bundle, (2) ask the user to `/quit` + reopen, (3) on resume, re-check `md5sum dist/index.mjs` then issue a probe tool call (e.g. `team action='list'`). If the probe returns the *old* error (e.g. `Unknown type`, `Validation failed for tool team`), the session did NOT reload — there may be multiple `pi` PIDs and the user reopened a different one. Verify with `ps -eo pid,lstart,tty,args | grep pi` which PID is yours (the one whose session log is being appended to right now).
+
 **References**:
 
 | What | Where |
@@ -416,6 +424,74 @@ If the two md5s match → session is on the latest code. If not → user must `/
 
 ---
 
+## Tier 9 — Feature battery (live action coverage)
+
+**What**: drive the team tool + subagent tools through a spread of actions from the parent Pi session to prove the full surface works end-to-end, not just one smoke run.
+
+**Why this exists**: Tier 7 proves one team run completes. But pi-crew has ~50 `team` actions plus 4 subagent tools (`Agent`, `crew_agent`, `get_subagent_result`, `crew_agent_steer`), dispatched through several code paths (sync run, async run, chain, parallel, direct subagent). A schema or registration regression can break *some* paths while others still pass. The battery catches path-specific breakage.
+
+**When required**: any change to `src/schema/team-tool-schema.ts`, `src/extension/registration/team-tool.ts`, `src/extension/team-tool/*.ts` (handler dispatch), or the subagent-tool registration. Optional but cheap for any change — the read-only actions are free.
+
+**How** (run from the parent Pi session — these are tool calls, not shell):
+
+1. **9a. Read-only actions** (free, no subagent spawn — run these first as a fast battery):
+   - `team action='list'` — teams/workflows/agents
+   - `team action='recommend' goal='...'` — planner routing
+   - `team action='health'` — run-state scan
+   - `team action='doctor' focus='zombies'` — orphan subagent scan (read-only)
+   - `team action='status' runId='<recent>' details=false` — compact
+   - `team action='events' runId='<recent>'` — full event lifecycle
+   - `team action='summary' runId='<recent>'` — cost/by-role report
+   - `team action='get' resource='workflow' team='implementation'` — resource inspect
+   - `team action='explain' runId='<recent>'` — markdown render
+   - `team action='worktrees' runId='<recent>'` — workspace listing
+2. **9b. Spawn paths** (cost tokens — one probe each is enough):
+   - `team action='run'` sync (fast-fix, trivial goal) — proves sync run + child-pi spawn + provider-extension loading
+   - `team action='run' async=true` — proves background dispatch
+   - `team action='run' chain='"A" -> "B"'` — proves sequential handoff (chain runner)
+   - `Agent` direct subagent — proves the direct-subagent tool
+   - `crew_agent` `run_in_background=true` then `get_subagent_result` — proves background subagent lifecycle
+3. **Acceptance**: every action returns without `Unknown type` / `Validation failed for tool team` / empty error text; every spawn path completes with `consistency=1` and the expected probe token in the agent output.
+
+**Real measured outcome** (this session, after the v0.9.57 schema fix): 9a (15 team actions) + 9b (4 subagent tools / 3 run paths) exercised; all green; the two silent-failure modes that motivated this tier (`Unknown type` from `Type.Unsafe` without Kind, and `Validation failed for tool team` from empty-string-strict schema) were caught ONLY by this battery — Tier 1-8 all passed while the team tool was broken live. The session also surfaced the unauthorized-agent-edit anti-pattern (a chain-run agent edited `chain-runner.ts` mid-smoke) — see Anti-patterns.
+
+**Not covered by the cheap battery above** — the actions below need extra setup, cost, or user confirmation. Run them only when the change touches their code path, and prefer a throwaway cwd / config so you don't mutate the user's real state. Organised by cost/safety:
+
+**9c. Lifecycle / recovery** (needs a *running* run — start an async run, then exercise these against its runId):
+- `team action='wait' runId='...'` — block until completion
+- `team action='steer' runId='...' message='...'` — inject a steering note mid-run
+- `team action='status' runId='...' details=true` — full dump mid-run
+- `team action='cache' subAction='...' runId='...'` — snapshot cache ops
+- `team action='checkpoint' runId='...'` — state checkpoint
+- `team action='cancel' runId='...'` — ⚠️ destructive (kills the run); use a throwaway run
+- `team action='invalidate' runId='...'` — cache invalidation
+- `team action='resume' runId='...'` / `retry` — resume a completed/failed run
+- `team action='respond' taskId='...' message='...'` — mailbox reply (needs a waiting task)
+- subagent steering: `crew_agent run_in_background=true` a long task (e.g. `sleep 60`), then `crew_agent_steer` while it runs, then `get_subagent_result` — proves the steer arrived (timing-sensitive; assert the agent's output reflects the steer)
+
+**9d. Destructive** (⚠️ **requires explicit user confirmation** per the delegation policy — never run unprompted):
+- `team action='prune' keep=<N>` — delete old finished runs
+- `team action='cleanup'` — sweep stale workspaces/state
+- `team action='forget' runId='...'` — delete one run's state
+- `team action='doctor' focus='zombies'` is READ-ONLY (safe) but the follow-up `kill <PID>` it suggests is destructive — confirm with the user before killing
+
+**9e. Admin / mutation** (mutates config or workflow files — use a scratch project cwd or back up first):
+- `team action='create' resource='team' ...` / `update` / `delete` — manage teams/agents/workflows
+- `team action='init'` / `config` / `validate` / `autonomy` / `settings` — project setup
+- `team action='workflow-create'` / `workflow-save` / `workflow-delete` / `workflow-get` / `workflow-list` — workflow CRUD
+- `team action='import'` / `imports` / `export` — run data portability
+- `team action='parallel' tasks=[...]` — parallel dispatch (spawn path, costs tokens per task)
+
+**9f. Background / scheduled** (expensive or niche):
+- `team action='run' runKind='goal-loop'` — the goal loop runs many turns judging an objective; smoke with a trivial objective + low `maxTurns` (e.g. 2) to prove dispatch without burning budget
+- `team action='schedule' cron='...' ...` / `scheduled` / `subAction='remove'` — cron; assert the job registers then remove it (cleanup)
+- `team action='auto-summarize'` / `anchor` / `auto_boomerang` — background features; assert no-throw on a completed run
+- `team action='api'` — programmatic surface
+
+**Acceptance for 9c–9f**: the action returns a structured result (not `Unknown type` / not an empty error), and for spawn/lifecycle paths the run reaches the expected terminal status. For 9d/9e, the mutation is reversible or confined to scratch state.
+
+---
+
 ## Anti-patterns (the cost is real, observed in this session)
 
 | Anti-pattern | Cost | Where fixed | Reference |
@@ -432,6 +508,9 @@ If the two md5s match → session is on the latest code. If not → user must `/
 | Test by reading code | Proves nothing about runtime | n/a (permanent) | All tiers above |
 | `makeFakeCtx({ flagOn: false })` without `brokerEnv: "0"` | `makeFakeCtx` deletes `PI_CREW_BROKER` env if `brokerEnv` is undefined | `612e18b` (test fix) | `test/unit/crew-broker-server-gate.test.ts:78` — pass `brokerEnv: "0"` to preserve env |
 | Trust green CI on one OS | macOS/Windows regressions slip through | n/a (permanent) | `.crew/knowledge.md` — "CI runs 3 OSes ... A flake on one OS IS a real bug" |
+| Trusting a team-run agent not to edit the repo under test | Agents spawned by `team`/`Agent`/`crew_agent` inherit the session cwd and have `edit`/`write` tools — a proactive LLM (observed with deepseek) will make **unauthorized source edits** to pi-crew during a trivial smoke run (e.g. "improving" `chain-runner.ts` while parsing a chain string). The edit can be correct + green-tested yet still be unintended scope creep that silently lands in your commit. | n/a (permanent) | After EVERY team/subagent run: `git status` and verify each changed file was authored by you. Diff + review any surprise change before staging. Consider `workspaceMode: 'worktree'` for parallel/risky runs to isolate mutations. |
+| `Type.Unsafe({ anyOf/type })` schema field **without** `[TypeBox.Kind]` symbol | `Value.Check` throws `Unknown type` the first time a model emits that field (e.g. `skill`, `config`) — every team action returns `isError:true` text `"Unknown type"`. Tier 1-8 stay green because unit tests never send the offending field. | v0.9.57 | `src/schema/team-tool-schema.ts` — `SkillOverride`/`FreeformConfig` switched from `Type.Unsafe` to TypeBox-native `Type.Union`/`Type.Record`. See Tier 9. |
+| Schema too strict for model-emitted empty strings (`runId:""`, `workspaceMode:""`, `budgetTotal:0`) | pi-ai `validateToolArguments` runs BEFORE the pi-crew handler and rejects `""` against Literal unions / patterns → `Validation failed for tool team` → model loops. | v0.9.57 | `src/schema/team-tool-schema.ts` — added `Literal("")` to unions, `^$|` pattern for runId, `""` to action enum, `0`/Boolean allowances. Handler-side `normalizeTeamParams` drops the empties. |
 
 ---
 
@@ -452,6 +531,9 @@ When a tier fails, the recovery is usually quick. Match the symptom to the cause
 | Smoke team: worker times out at 300s | Either verifier command slow OR LLM thinking cap | Check `RESPONSE_TIMEOUT_MS` (300s); bump only if you verified the command itself finishes <300s |
 | `stale-ctx` error in worker output | Extension ctx is stale after session replacement | This is runtime noise, not a regression; ignore. (Source: `.crew/knowledge.md` "Process Safety" notes) |
 | Bundle md5 not changing after rebuild | Stale `dist/` cache or esbuild no-op | `rm -rf dist/ && npm run build:bundle`; verify new md5 |
+| Team tool returns `Unknown type` (isError:true, short text) | `Value.Check` in the handler hit a `Type.Unsafe({...})` schema node with **no `[TypeBox.Kind]` symbol** — only triggered when the model actually sends that field. Tier 1-8 pass; only Tier 9 (feature battery) catches it. | Replace the `Type.Unsafe` with a TypeBox-native constructor (`Type.Union`, `Type.Record`, `Type.Any`). Reproduce with `node --input-type=module -e "import {Value} from '@sinclair/typebox/value'; import {TeamToolParams} from './src/schema/team-tool-schema.ts'; Value.Check(TeamToolParams, {action:'list', skill:'', config:{}})"` — a throw = the bug. |
+| `Validation failed for tool "team": ... must be equal to constant` | pi-ai `validateToolArguments` (`@earendil-works/pi-ai/dist/utils/validation.js`) rejects model-emitted `""`/`0`/`false` defaults against Literal unions / patterns / minimums — it runs BEFORE the pi-crew handler, so handler-side normalization is too late. | Loosen the schema to accept the unset marker (`Literal("")`, pattern `^$|...`, `Literal(0)`, add `Boolean()` to unions). Verify with the pi-ai validator directly: `import {validateToolArguments} from '@earendil-works/pi-ai'; validateToolArguments({name:'team',parameters:TeamToolParams},{name:'team',arguments:{...fullModelBlob}})`. |
+| User says "restarted" but the probe still shows the OLD error | Multiple `pi` PIDs open; the user reopened a different terminal than the one the agent runs in; the agent's session never reloaded the bundle. | `ps -eo pid,lstart,tty,args \| grep pi` to list PIDs; match the agent's session log (the `.jsonl` being appended right now) to its PID; have the user reopen THAT session, or move the work into the freshly-opened one. |
 
 ## Performance budget (per-tier soft limits)
 
@@ -465,6 +547,7 @@ When a tier fails, the recovery is usually quick. Match the symptom to the cause
 | 6 (pty probe) | 5s | 15s | `pi` not in PATH |
 | 7 (smoke team) | 60s (verifier only) | 300s (worker hard limit) | Worker killed by `RESPONSE_TIMEOUT_MS` |
 | 8 (final md5 sync) | <1s | 5s | Disk/symlink issue |
+| 9 (feature battery) | 30s (read-only batch) + ~120s per spawn probe | 300s per spawn probe (worker hard limit) | Spawn probe hung or returned `Unknown type`/`Validation failed` — a schema or registration regression; see Tier 9 + Failure symptoms |
 
 If a tier runs over the hard limit, **stop and investigate** — don't bump the budget silently. The budget exists precisely so regressions in test runtime (which usually means a regression in test setup/teardown) are caught early.
 
@@ -589,6 +672,12 @@ python3 scripts/pty_probe.py 2>&1 | tee /tmp/diag.log
 md5sum dist/index.mjs
 md5sum "$(npm root -g)"/pi-crew/dist/index.mjs 2>/dev/null \
   || md5sum ../node_modules/pi-crew/dist/index.mjs
+# Tier 9 (feature battery — from parent Pi session, tool calls not shell)
+#   read-only: team action=list / recommend / health / doctor / status / events / summary / get / explain / worktrees
+#   spawn:     team action=run (sync) ; team action=run async=true ; team action=run chain='"A" -> "B"'
+#              Agent (direct) ; crew_agent run_in_background=true + get_subagent_result
+#   reproduce the two silent schema failures:
+#   node --input-type=module -e "import {Value} from '@sinclair/typebox/value'; import {TeamToolParams} from './src/schema/team-tool-schema.ts'; Value.Check(TeamToolParams, {action:'list', skill:'', config:{}})"  # throws 'Unknown type' = Type.Unsafe-without-Kind bug
 ```
 
 ---
@@ -604,6 +693,7 @@ Before claiming "tested":
 - [ ] Tier 5/6: live TUI smoke for any `src/ui/` change — keystroke reached `handleInput`
 - [ ] Tier 7: smoke team run for any `src/runtime/plan-templates.ts` or `workflows/*.workflow.md` change — completed, no hang, verifier output under 60s
 - [ ] Tier 8: final md5 sync check passed
+- [ ] Tier 9: feature battery — **required if you touched `src/schema/team-tool-schema.ts`, `src/extension/registration/team-tool.ts`, or any `Type.Unsafe({...})` schema**. 9a read-only batch all return clean; one probe per 9b spawn path (sync / async / chain / `Agent` / `crew_agent`+`get_subagent_result`) completes with `consistency=1`. Run 9c–9f only when the change touches their code path; 9d (destructive) requires explicit user confirmation. **After every run: `git status` to catch unauthorized agent edits.**
 
 If any required item is unchecked, the answer to "is it tested?" is **no**.
 

package/src/agents/discover-agents.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { type LoadedPiTeamsConfig, loadConfig } from "../config/config.ts";
+import { discoverProviderExtensionPaths } from "../runtime/model/provider-extensions.ts";
 import { parseCsv, parseFrontmatter } from "../utils/frontmatter.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { findRepoRoot, packageRoot, projectCrewRoot, userPiRoot } from "../utils/paths.ts";
@@ -317,7 +318,9 @@ export function sanitizeAgentSystemPrompt(content: string, source: ResourceSourc
 	sanitized = sanitized.replace(/[\u200B-\u200F\u2028-\u202F\u2060-\u206F\uFEFF]/g, "");
 
 	// 2. Strip HTML/JS comments (instruction hiding) — all trust levels
-	sanitized = sanitized.replace(/<!--[\s\S]*?-->|<\/?script[^>]*>/gi, "");
+	// SEC-4: bounded quantifier {0,8192} prevents polynomial O(n²) backtracking
+	// DoS on pathological inputs (e.g. an unclosed `<!--` with no matching `-->`).
+	sanitized = sanitized.replace(/<!--[\s\S]{0,8192}?-->|<\/?script[^>]*>/gi, "");
 
 	// 3. Strip known prompt injection directive patterns — user and project
 	if (trustLevel !== "builtin") {
@@ -337,7 +340,8 @@ export function sanitizeAgentSystemPrompt(content: string, source: ResourceSourc
 		sanitized = sanitized.replace(/\b(eval|exec|spawn|subprocess)\s*\(\s*(?:base64|Buffer\.from)\s*\(/gi, "[suspicious-call-redacted]");
 
 		// Strip markdown that attempts to hide instructions
-		sanitized = sanitized.replace(/```\s*(?:system|instruction|prompt)\n[\s\S]*?```/gi, "");
+		// SEC-4: bounded quantifier {0,8192} prevents polynomial backtracking DoS.
+		sanitized = sanitized.replace(/```\s*(?:system|instruction|prompt)\n[\s\S]{0,8192}?```/gi, "");
 	}
 
 	// 4. Project-level strict sanitization
@@ -391,7 +395,7 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 		// runtime is the default child-process path. `contextMode: fork`
 		// is only effective in the live-session runtime (the experimental
 		// path that runs the agent IN the parent pi's session). The
-		// default child-process path (runChildPi in src/runtime/child-pi.ts)
+		// default child-process path (runChildPi in src/runtime/child-pi/child-pi.ts)
 		// spawns a NEW pi process and has no parent session to inherit,
 		// so the agent will behave as `fresh` regardless of the setting.
 		// We warn (not throw) so existing configs that predate live-session
@@ -401,7 +405,7 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 		// logInternalError below).
 		if (contextMode === "fork" && !warnedForkAgents.has(filePath)) {
 			console.warn(
-				"contextMode: 'fork' is only effective in live-session runtime; current default child-process will behave as 'fresh'. See docs/runtime-modes.md.",
+				"contextMode: 'fork' is only effective in live-session runtime; current default child-process will behave as 'fresh'. See docs/runtime-flow.md.",
 			);
 			warnedForkAgents.add(filePath);
 		}
@@ -417,8 +421,19 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 			fallbackModels: parseCsv(frontmatter.fallbackModels),
 			thinking: frontmatter.thinking === "false" ? undefined : frontmatter.thinking || undefined,
 			tools: parseToolsField(frontmatter.tools),
-			extensions: frontmatter.extensions === "" ? [] : parseCsv(frontmatter.extensions),
-			excludeExtensions: parseCsv(frontmatter.excludeExtensions ?? frontmatter.exclude_extensions),
+			// SEC-1: Strip extensions/excludeExtensions for untrusted project-sourced
+			// agents (RCE prevention). Both `project` (.crew/agents/) and
+			// `project-pi` (.pi/agents/) are repo-adjacent / untrusted sources —
+			// their frontmatter `extensions:` could point to attacker-controlled
+			// code. Bypass only when PI_CREW_TRUST_PROJECT_AGENT_EXTENSIONS=1 is
+			// explicitly set. buildPiWorkerArgs also enforces this as
+			// defense-in-depth.
+			...((source === "project" || source === "project-pi") && process.env.PI_CREW_TRUST_PROJECT_AGENT_EXTENSIONS !== "1"
+				? { extensions: [], excludeExtensions: [] }
+				: {
+						extensions: frontmatter.extensions === "" ? [] : parseCsv(frontmatter.extensions),
+						excludeExtensions: parseCsv(frontmatter.excludeExtensions ?? frontmatter.exclude_extensions),
+					}),
 			skills: parseCsv(frontmatter.skills ?? frontmatter.skill),
 			systemPromptMode: frontmatter.systemPromptMode === "append" ? "append" : "replace",
 			inheritProjectContext: frontmatter.inheritProjectContext === "true",
@@ -448,12 +463,31 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 	}
 }
 
+// SEC-4: Maximum agent file size. Files exceeding this are skipped to prevent
+// resource-exhaustion DoS (a 10MB agent file would block the event loop during
+// readFileSync + frontmatter parse + regex sanitization). 256KB is generous —
+// the largest builtin agent file is ~2KB.
+const MAX_AGENT_FILE_BYTES = 256 * 1024;
+
 function readAgentDir(dir: string, source: ResourceSource): AgentConfig[] {
 	if (!fs.existsSync(dir)) return [];
 	const agents = fs
 		.readdirSync(dir)
 		.filter((entry) => entry.endsWith(".md") && !entry.endsWith(".team.md") && !entry.endsWith(".workflow.md"))
-		.map((entry) => parseAgentFile(path.join(dir, entry), source))
+		.map((entry) => {
+			const fullPath = path.join(dir, entry);
+			// SEC-4: Skip files exceeding the size cap before reading/parsing.
+			try {
+				const stat = fs.statSync(fullPath);
+				if (stat.size > MAX_AGENT_FILE_BYTES) {
+					console.warn(`[pi-crew] Skipping oversized agent file (${stat.size} > ${MAX_AGENT_FILE_BYTES} bytes): ${fullPath}`);
+					return undefined;
+				}
+			} catch {
+				return undefined;
+			}
+			return parseAgentFile(fullPath, source);
+		})
 		.filter((agent): agent is AgentConfig => agent !== undefined)
 		.sort((a, b) => a.name.localeCompare(b.name));
 
@@ -471,13 +505,37 @@ function applyAgentOverrides(agents: AgentConfig[], cwd: string, loadedConfig?:
 	const loaded = loadedConfig ?? loadConfig(cwd);
 	const agentsConfig = loaded.config.agents;
 	const overrides = agentsConfig?.overrides ?? {};
+	// Provider extension allowlist (v0.9.57): auto-discovered from Pi's
+	// installed package registry (settings.json `packages` with `npm:` specs —
+	// e.g. pi-commandcode-provider). These are the sanctioned channels for
+	// provider extensions that register models, so provider models stay
+	// resolvable inside subagents despite `--no-extensions`. The explicit
+	// `runtime.agentExtensions` config list is merged on top for operators who
+	// want extra paths beyond installed packages. SEC-1 preserved: project /
+	// project-pi agents never receive any of these (env-gate unchanged).
+	const globalExtensions = [...discoverProviderExtensionPaths(), ...(loaded.config.runtime?.agentExtensions ?? [])];
+	const deduped = [...new Set(globalExtensions.map((p) => path.resolve(p)))];
+	// SEC-1 (defense-in-depth): do NOT merge the global extension allowlist into
+	// untrusted project / project-pi agents. Those agents already had their
+	// `extensions` stripped at parse time unless PI_CREW_TRUST_PROJECT_AGENT_EXTENSIONS=1;
+	// re-adding global extensions would bypass that gate. The global list is a
+	// user-trusted config knob (provider extensions like pi-commandcode-provider)
+	// and applies to builtin / user agents only.
+	const isUntrustedProject = (agent: AgentConfig) =>
+		(agent.source === "project" || agent.source === "project-pi") && process.env.PI_CREW_TRUST_PROJECT_AGENT_EXTENSIONS !== "1";
+	const withGlobalExtensions = (agent: AgentConfig): AgentConfig => {
+		if (isUntrustedProject(agent)) return agent;
+		return deduped.length > 0 || agent.extensions !== undefined
+			? { ...agent, extensions: [...deduped, ...(agent.extensions ?? [])] }
+			: agent;
+	};
 	return agents
 		.filter((agent) => !(agentsConfig?.disableBuiltins && agent.source === "builtin"))
 		.map((agent) => {
 			const overrideEntry = Object.entries(overrides).find(([name]) => name.toLowerCase() === agent.name.toLowerCase());
-			if (!overrideEntry) return agent;
+			if (!overrideEntry) return withGlobalExtensions(agent);
 			const [, override] = overrideEntry;
-			return {
+			return withGlobalExtensions({
 				...agent,
 				disabled: override.disabled ?? agent.disabled,
 				model: override.model === false ? undefined : (override.model ?? agent.model),
@@ -486,7 +544,7 @@ function applyAgentOverrides(agents: AgentConfig[], cwd: string, loadedConfig?:
 				tools: override.tools === false ? undefined : (override.tools ?? agent.tools),
 				skills: override.skills === false ? undefined : (override.skills ?? agent.skills),
 				override: { source: "config", path: loaded.path },
-			};
+			});
 		});
 }
 

package/src/benchmark/feedback-loop.ts

@@ -2,7 +2,7 @@
  * Feedback loop - continuous improvement cycle: evaluate → learn → apply → re-evaluate
  */
 
-import type { RunMetrics } from "../state/run-metrics.ts";
+import type { RunMetrics } from "../state/stores/run-metrics.ts";
 
 /** @internal */
 interface FeedbackLoopStats {

package/src/config/config.ts

@@ -5,7 +5,7 @@ import { type Static, type TSchema, Type } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
 import { PiTeamsAutonomyProfileSchema, PiTeamsConfigSchema } from "../schema/config-schema.ts";
 import { atomicWriteFile } from "../state/atomic-write.ts";
-import { withFileLockSync } from "../state/locks.ts";
+import { withFileLockSync } from "../state/coordination/locks.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { projectCrewRoot, projectPiRoot } from "../utils/paths.ts";
 import { DEFAULT_BROKER, resolveBrokerEnvOverride } from "./defaults.ts";
@@ -732,6 +732,7 @@ function parseRuntimeConfig(value: unknown): CrewRuntimeConfig | undefined {
 			return Object.values(parsed).some((v) => v !== undefined) ? parsed : undefined;
 		})(),
 		excludeContextBash: parseWithSchema(Type.Boolean(), obj.excludeContextBash),
+		agentExtensions: parseStringList(obj.agentExtensions),
 		isolationPolicy: parseIsolationPolicy(obj.isolationPolicy),
 	};
 	return Object.values(runtime).some((entry) => entry !== undefined) ? runtime : undefined;

package/src/config/types.ts

@@ -44,6 +44,18 @@ export interface CrewRuntimeConfig {
 	allowChildProcessFallback?: boolean;
 	maxTurns?: number;
 	graceTurns?: number;
+	/**
+	 * Global extension allowlist (default: none). Paths (file paths or npm
+	 * extension entry points) to load in EVERY spawned child-pi worker, on top
+	 * of pi-crew's own prompt-runtime extension. Despite `--no-extensions`
+	 * being set for child spawns (to prevent untrusted user extensions from
+	 * auto-loading), Pi loads explicitly-passed `--extension <path>` entries.
+	 * This is the sanctioned channel for provider extensions that register
+	 * models (e.g. `pi-commandcode-provider`) so those models stay resolvable
+	 * inside subagents. Applies to all agents; agent-level `extensions:`
+	 * frontmatter (user sources) can still add per-agent extensions.
+	 */
+	agentExtensions?: string[];
 	/**
 	 * W2 fix — wall-clock timeout per task in milliseconds. When the task
 	 * exceeds this limit, input.signal is aborted which triggers the existing

package/src/extension/action-suggestions.ts

@@ -7,75 +7,28 @@
  * (`src/config/suggestions.ts → suggestConfigKey`); this module applies it to
  * the known set of team actions.
  *
- * The known-action list mirrors the `action` enum in
- * `src/schema/team-tool-schema.ts`. Kept as a hand-maintained constant (not
- * derived from the TypeBox schema at runtime) so it is trivially testable and
- * avoids pulling the schema into low-level error paths.
+ * EXT-4/EXT-8: the known-action list is now derived from the single source of
+ * truth — `allActionLiterals` in `src/schema/team-tool-schema.ts` — so it can
+ * never drift from the schema's action enum. A drift test
+ * (`test/unit/action-list-single-source.test.ts`) guards against regression.
  */
 
 import { findClosestKey } from "../config/suggestions.ts";
+import { allActionLiterals } from "../schema/team-tool-schema.ts";
 
 /**
- * The complete set of valid top-level `team` actions (mirrors the action enum
- * in `src/schema/team-tool-schema.ts`). Exported so callers and tests can use
- * the single source of truth.
+ * The complete set of valid top-level `team` actions. EXT-4/EXT-8: derived from
+ * `allActionLiterals` (the schema's single source of truth), not hand-maintained.
+ * Each `allActionLiterals` entry is a `{ const: string }` produced by the domain
+ * `stringEnum` schemas; we map to the raw string for use with the fuzzy matcher.
+ *
+ * Sorted by (length desc, then alphabetical) so `findClosestKey` tie-breaking
+ * is deterministic and prefers longer (more specific) matches on equal
+ * Levenshtein distance — e.g. "cancle" → "cancel" over "cache".
  */
-export const KNOWN_TEAM_ACTIONS = [
-	"run",
-	"parallel",
-	"plan",
-	"status",
-	"wait",
-	"list",
-	"get",
-	"cancel",
-	"retry",
-	"resume",
-	"respond",
-	"create",
-	"update",
-	"delete",
-	"doctor",
-	"cleanup",
-	"events",
-	"artifacts",
-	"worktrees",
-	"forget",
-	"summary",
-	"prune",
-	"export",
-	"import",
-	"imports",
-	"help",
-	"validate",
-	"config",
-	"init",
-	"recommend",
-	"autonomy",
-	"api",
-	"settings",
-	"steer",
-	"invalidate",
-	"health",
-	"graph",
-	"onboard",
-	"explain",
-	"cache",
-	"checkpoint",
-	"search",
-	"orchestrate",
-	"schedule",
-	"scheduled",
-	"anchor",
-	"auto-summarize",
-	"auto_boomerang",
-	"goal",
-	"workflow-create",
-	"workflow-get",
-	"workflow-list",
-	"workflow-save",
-	"workflow-delete",
-] as const;
+export const KNOWN_TEAM_ACTIONS: readonly string[] = allActionLiterals
+	.map((l) => (l as { const: string }).const)
+	.sort((a, b) => b.length - a.length || a.localeCompare(b));
 
 /**
  * Suggest the closest known team action for a (likely typo'd) input.

package/src/extension/async-notifier.ts

@@ -1,9 +1,9 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { readCrewAgents, saveCrewAgents } from "../runtime/crew-agent-records.ts";
 import { checkProcessLiveness, isActiveRunStatus } from "../runtime/process-status.ts";
-import { appendEvent, readEvents, type TeamEvent } from "../state/event-log.ts";
-import { withRunLockSync } from "../state/locks.ts";
-import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
+import { withRunLockSync } from "../state/coordination/locks.ts";
+import { appendEvent, readEvents, type TeamEvent } from "../state/event-log/event-log.ts";
+import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { listRuns } from "./run-index.ts";

package/src/extension/command-completions.ts

@@ -68,8 +68,8 @@ export function suggestRunIds(_prefix: string, cwd?: string): AutocompleteItem[]
 export async function suggestTaskIds(runId: string, prefix: string, cwd?: string): Promise<AutocompleteItem[] | null> {
 	const resolvedCwd = cwd ?? process.cwd();
 	// Dynamic import to avoid pulling state-store into the hot command-registration path.
-	// LAZY: defer dynamic import of ../state/state-store.ts to its call site.
-	const { loadRunManifestById } = await import("../state/state-store.ts");
+	// LAZY: defer dynamic import of ../state/stores/state-store.ts to its call site.
+	const { loadRunManifestById } = await import("../state/stores/state-store.ts");
 	const loaded = loadRunManifestById(resolvedCwd, runId);
 	if (!loaded) return null;
 	const items: AutocompleteItem[] = loaded.tasks.map((task) => ({

package/src/extension/crew-cleanup.ts

@@ -1,11 +1,11 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { cleanupAllTrackedTempDirs } from "../runtime/pi-args.ts";
+import { cleanupAllTrackedTempDirs } from "../runtime/model/pi-args.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 
 // NOTE: globalProgressTracker import kept for documentation but not directly used
 // since we don't have agent IDs to untrack. Actual progress clearing should be
 // handled by the progress tracker itself on shutdown.
-// import { globalProgressTracker } from "../runtime/progress-tracker.ts";
+// import { globalProgressTracker } from "../runtime/output/progress-tracker.ts";
 
 /**
  * Registers cleanup handlers for graceful shutdown.
@@ -115,7 +115,7 @@ async function cleanupChildProcesses(): Promise<void> {
 	// extension load path (check-lazy-imports) AND to avoid a static import cycle
 	// (child-pi.ts already imports registerChildProcess from this module).
 	// LAZY: defer child-pi.ts load (heavy runtime chain) + avoid static import cycle.
-	const { killProcessPid } = await import("../runtime/child-pi.ts");
+	const { killProcessPid } = await import("../runtime/child-pi/child-pi.ts");
 	for (const pid of pids) {
 		// killProcessPid signals the whole process GROUP (-pid on POSIX, taskkill /T on
 		// Windows) and escalates to SIGKILL after HARD_KILL_MS. A bare