# T10.9 — CLI: runs list/episode/transcript

| Field | Value |
|---|---|
| Phase | P10 — Orchestration |
| Size | S — under 1 day |
| Status | Not started |
| Flags | — |
| Spec | inlined below |
| Blocks | — |

## Goal

Three thin CLI wrappers over the HTTP API — `poimen runs list --goal <id>`,
`poimen runs episode <run_id>`, `poimen runs transcript <run_id> <step>
<attempt>` — the whole troubleshooting UX, no dashboard.

## Facts (inlined — no spec read needed)

- Thin HTTP clients, not a second implementation of the query logic already
  in T10.1/T1.7/T1.6 — the CLI calls the same routes T10.4 exposes.
- Rides the eventual shared `poimen` binary (T9.3); workable as a standalone
  binary if T9.3 hasn't landed yet — soft dependency, not a hard block.
- `episode` output must include failed attempts by default — T1.7's own
  rule. A CLI that hides them defeats the purpose of the command.
- `transcript` dereferences the `BlobRef` server-side, via the HTTP route
  (T10.4) — the CLI never talks to `BlobStore` directly.

## Steps

1. `poimen runs list [--goal <id>] [--status <state>]` → `GET /v1/runs`,
   table output (`run_id`, `status`, `goal_id`, age).
2. `poimen runs episode <run_id>` → `GET /v1/runs/{id}/episode`,
   human-readable rendering of `EpisodeView` including failed attempts,
   clearly marked.
3. `poimen runs transcript <run_id> <step> <attempt>` → `GET .../transcript`,
   prints prompt/output text, dereferenced server-side.
4. Exit codes: non-zero on API error, distinct code for "run not found" vs
   "transport error" — operator scripting depends on this distinction.
5. Test against a live embedded API instance (T10.4's test harness) with a
   run that has a retry and a rewind.

## Acceptance

- `episode` on a run with two failed attempts and one success shows all
  three, visually distinguishable.
- `transcript` returns the same text content as reading the `BlobRef`
  directly through `BlobStore` in a test assertion.

## Verify

**Harness:** T10.4's `axum` test instance, one run with a retry (two
attempts, one failed) and a rewind.

**Integration test** — `tests/it_cli_runs_ux.rs`:
1. `runs list --goal G`; assert output contains exactly the runs tagged G,
   none untagged.
2. `runs episode <id>`; assert both the failed and successful attempt
   appear — count them explicitly, not just non-empty output.
3. `runs transcript <id> <step> 1` (the failed attempt) and `... 2` (the
   retry); assert distinct content for each, matching their respective
   `BlobRef`s byte-for-byte.
4. Run-not-found case; assert a distinct exit code from a transport-down
   case.

**Command:** `cargo test -p cli runs_ux`

**False pass:**
- Step 2 checking only that output is non-empty — a CLI silently filtering
  to the winning attempt (T1.7's own named trap) passes a non-empty check
  while hiding exactly the debugging signal requested.

## Traps

- Filtering episode output to "just the successful attempt for clarity" —
  T1.7's trap restated at the CLI layer; the failed attempts are the reason
  this command exists.
- Fetching transcripts client-side by resolving `BlobRef` directly instead
  of through the HTTP route. Bypasses the tenant auth checks the API
  enforces.

---

Background (not required to do this task):
[T10.4-http-api-surface.md](T10.4-http-api-surface.md) ·
[T1.7-episode-query-surface.md](T1.7-episode-query-surface.md) ·
[T1.6-prompt-and-output-blob-capture.md](T1.6-prompt-and-output-blob-capture.md) ·
[T8.2-metrics.md](T8.2-metrics.md)