# Test Matrix

## Commands

| Level | Command | Tests | Areas |
|---|---|---|---|
| Unit | `npm run test:unit` | 95 | Templates, paths, forks, mailbox, limiter, config, progress, failures, service tiers, inheritance metadata, listing budget, compaction, budget, retry, inventory, metrics, and bounds |
| Contract | `npm run test:contract` | 11 | Nine tool schemas, output shapes, and source error text |
| Integration | `npm run test:integration` | 101 | Graph, messages, templates, progress, models, limits, failures, restart, shutdown, residency, persistence, roles, tool inheritance, compaction, budget, retry, inventory, time reminders, and metrics |
| End-to-end | `npm run test:e2e` | 7 | Extension lifecycle, headless UI guards, commands, picker, and progress views |
| Pi steering gap | `npm run test:gap` | 2 | Pi steering does not abort the active tool signal. Extension tool API omits execute callbacks. |
| Live | `npm run smoke` | 1 | Installed Pi in RPC, print, and JSON modes. Checks `/subagents` command conflict. |
| Cross-provider live | `npm run smoke:cross-provider` | 1 | DeepSeek parent and child. Composite root `exec` projects to child `read`. |

`npm run check` runs format, lint, type, test, and package checks. All 216 tests use deterministic inputs.

The command needs no model API key.

`npm run smoke` needs an installed Pi release.

`npm run smoke:cross-provider` needs DeepSeek authentication.

## Coverage

| Area | Evidence files |
|---|---|
| Tool data contracts and errors | `test/contract/tools.test.ts`, `test/contract/errors.test.ts` |
| Paths, filtered forks, mailboxes, and hard bounds | `test/unit/core.test.ts` |
| Listing output budget under the tool cap | `test/unit/core.test.ts`, `test/integration/control-plane.test.ts` |
| Execution permit limits | `test/unit/core.test.ts`, `test/integration/control-plane.test.ts` |
| Messaging, wait, interrupt, steer, and cancellation | `test/integration/control-plane.test.ts` |
| Parent tool inheritance and reasoning defaults | `test/integration/control-plane.test.ts` |
| Scout full-registry role tools and plain-child role scoping (F-02) | `test/integration/control-plane.test.ts` |
| Effective model/reasoning in spawn results (F-03) | `test/integration/control-plane.test.ts` |
| Optional wait target existence validation (F-06) | `test/contract/tools.test.ts`, `test/integration/control-plane.test.ts` |
| Real extension tool loading | `test/integration/extension-tool-inheritance.test.ts`, `scripts/live-smoke.mjs` |
| Optional conversion metadata and child tool filtering | `test/unit/extension-inheritance.test.ts`, `test/integration/extension-tool-inheritance.test.ts`, `test/integration/control-plane.test.ts` |
| Models, roles, service tiers, persistence, and resume | `test/unit/service-tiers.test.ts`, `test/integration/control-plane.test.ts` |
| Residency, listener cleanup, and shutdown | `test/integration/control-plane.test.ts` |
| Terminal-status preservation across shutdown and restore (F-01) | `test/integration/control-plane.test.ts` |
| History compaction and rollup | `test/unit/compaction.test.ts`, `test/integration/control-plane.test.ts` |
| Tree spend budget, reminders, and hard stop | `test/unit/budget.test.ts`, `test/integration/control-plane.test.ts` |
| Child turn retry with exponential backoff | `test/unit/retry.test.ts`, `test/integration/control-plane.test.ts` |
| Sibling inventory lines in child instructions | `test/unit/inventory.test.ts`, `test/integration/control-plane.test.ts` |
| Lifecycle event journal and `chimera_stats` | `test/unit/metrics.test.ts`, `test/integration/control-plane.test.ts` |
| Time reminders for long-running turns | `test/integration/control-plane.test.ts` |
| Completion-notice error guidance | `test/integration/control-plane.test.ts` |
| Root mailbox restore, leaf message authority, and interrupt scope | `test/integration/control-plane.test.ts` |
| Talk-while-they-work: user envelope routing, wait previews, no child abort, tell/steer, persistence restore | `test/unit/input-routing.test.ts`, `test/integration/talk-while-they-work.test.ts`, `test/e2e/subagents-command.test.ts` |
| Structured child failure phases | `test/unit/failures.test.ts`, `test/integration/child-failure-isolation.test.ts` |
| Creation, load, prompt, steer, abort, disposal, and sibling continuity | `test/integration/child-failure-isolation.test.ts` |
| Extension binding cleanup | `test/integration/extension-tool-inheritance.test.ts`, `test/e2e/extension-load.test.ts` |
| Extension loading, session reload, input activity, and headless guards | `test/e2e/extension-load.test.ts`, `test/e2e/progress-headless.test.ts` |
| Built-in roles, trust propagation, live-parent fork snapshots, and `session_shutdown` cleanup | `test/integration/control-plane.test.ts`, `test/integration/extension-tool-inheritance.test.ts` |
| Read-only TUI picker and navigation | `test/e2e/navigation.test.ts` |
| Template parsing, trust, bounds, names, and resource paths | `test/unit/agent-templates.test.ts` |
| Canonical-path coordination guidance in child instructions (F-07) | `test/unit/core.test.ts` |
| Content-signature stripping before message bounding (F-08) | `test/unit/core.test.ts` |
| Template spawn overrides and child resource selection | `test/integration/agent-templates.test.ts` |
| Transient bounded progress and tool activity | `test/unit/progress.test.ts`, `test/integration/live-progress.test.ts` |
| Composite exec-to-built-in tool projection | `test/integration/extension-tool-inheritance.test.ts`, `test/fixtures/composite-exec-extension.ts`, `scripts/cross-provider-smoke.mjs` |
| Package contents | `npm run package:check` |