# Runner command reference

The supported filesystem runner is `tooling/testing/plan.mts`. Run it from the pinned SnagBadger checkout after workspace setup/build. An adopting project's catalog and configuration can live elsewhere. Run `help` for the exact installed revision's usage.

```sh
node tooling/testing/plan.mts help
```

## Commands

| Command    | Arguments                                   | Purpose                                                            |
| ---------- | ------------------------------------------- | ------------------------------------------------------------------ |
| `inspect`  | `--catalog DIR`                             | Inspect selection metadata, alternatives and unselectable coverage |
| `start`    | `--catalog DIR --output DIR --runtime FILE` | Coordinate selected tests through the runtime bridge               |
| `next`     | `--output DIR`                              | Retrieve pending coordinator work                                  |
| `progress` | `--output DIR --response FILE`              | Persist observed partial work/evidence                             |
| `complete` | `--output DIR --response FILE`              | Complete the pending bridge request with validated output          |
| `cancel`   | `--output DIR`                              | Request cancellation; coordinator still services cleanup           |
| `report`   | `--output DIR --runtime FILE`               | Produce reviewed HTML from retained output                         |

`inspect` and `start` support `--catalog-id NAME`, `--tag TAG`, `--all A,B`, `--any A,B`, `--exclude A,B`, and `--ids CATALOG:SECTION/ID,...`. `start` also supports explicit `--retry`. Semantic validation occurs when a selected test is reached; inspect is not a whole-catalog validation gate. A new run needs a new output directory. Retry uses the existing directory and matching execution revisions. Without selection all tests run.

## Execution boundary

Keep `start` in a persistent session while an active coordinator services requests. These commands do not supply a browser automation runtime, fresh-agent host, or installed MCP client. [First test run](../getting-started/first-test-run.md) establishes those prerequisites.

Request/response details belong to [the host bridge contract](../../../integration/agent-testing.md#host-bridge). Do not invent a completion JSON shape from the command name; inspect the actual packet and send its supported response fields/identities.

## Output and recovery

`checkpoint.json` retains the validated run view, hierarchy, warnings/hook events and attachment index. Bytes live under `raw-evidence/` and are private execution state. Finished progress is persisted before moving to another test.

An interrupted coordinator may reconnect to a pending request in a still-running process or render saved partial output. Restarting in-memory shared fixtures is not promised. Unsupported/malformed checkpoints fail explicitly; legacy run/view output is readable where the canonical compatibility contract permits, without silent migration.

Read [selection/retry guidance](../guides/select-and-run-tests.md) and [formats](report-and-bundle-formats.md) before reusing a run directory.