---
name: runtime-state-reader
description: Safe read-only navigation of pi-crew run state. Use for inspecting manifests, tasks, events, agents, artifacts, health, and diagnostics without modifying state.
---

# runtime-state-reader

Use this skill when debugging or auditing a pi-crew run.

## Source patterns distilled

- `src/state/types.ts`, `src/state/contracts.ts`, `src/state/state-store.ts`
- `src/state/event-log.ts`, `src/state/artifact-store.ts`, `src/runtime/crew-agent-records.ts`
- `src/extension/run-index.ts`, `src/extension/team-tool/status.ts`, `src/extension/team-tool/inspect.ts`

## Rules

- Prefer exported state APIs over direct file parsing: `loadRunManifestById(cwd, runId)`, run index/list helpers, event readers, and agent readers.
- Treat state as append-mostly/durable. For review and debugging, do not mutate manifests/tasks/events.
- Validate run IDs and path-derived IDs; never concatenate untrusted path segments outside state helpers.
- Read events as JSONL; expect partial/corrupt trailing lines in crash scenarios and handle gracefully.
- Check status contracts before inferring behavior: terminal vs active run/task statuses matter.
- Agent aggregate records (`agents.json`) and per-agent status files can disagree briefly; prefer the latest loaded run state plus event log for final conclusions.
- Include exact paths inspected and distinguish direct evidence from inference.

## Common inspection order

1. Load manifest/tasks.
2. Check run/task statuses and timestamps.
3. Read recent events.
4. Read agent records and per-agent output/status if needed.
5. Inspect artifacts/diagnostics only through contained paths.
6. Report root cause and smallest safe remediation.

## Verification

For code changes to state readers:

```bash
cd pi-crew
npx tsc --noEmit
node --experimental-strip-types --test test/unit/run-index.test.ts test/unit/crew-contracts.test.ts test/unit/atomic-write.test.ts
npm test
```