# Durable Checkpoint Inspector CLI

## PURPOSE
A Click + Pandas command-line tool that reads a Pi Durable storage backend (SQLite or
the JSONL file set) and reports on task health: how many tasks completed, how many were
interrupted mid-tool-call, and how many checkpoints each task wrote. It answers the
question the video raises — "did it finish, or did it crash in the middle of a tool
call?" — without opening a database browser.

## WHY THIS MATTERS
The transcript's whole argument is about what happens when a process crashes *during* a
tool call: the plain Pi Coding Agent leaves a truncated tool call in a JSONL session and
forces you to send a `continue` message, while Pi Durable persists checkpoints so the
harness resumes automatically. To trust that mechanism you need to *see* the tasks and
checkpoints. This tool makes the durable storage legible as a tidy DataFrame.

## HOW TO BUILD
1. `click.group()` with two subcommands: `inspect` and `summary`.
2. `load_sqlite(path)` reads tasks + checkpoints into two DataFrames via `sqlite3`.
3. `load_jsonl(dir)` chains the multiple JSONL files into the same schema.
4. `summary` groups by status and prints `to_string()`; `inspect` filters to
   interrupted tasks and shows the last checkpoint name and whether it was `done`.
5. A `--backend {sqlite,jsonl,memory}` flag selects the reader.

```python
@cli.command()
@click.option("--backend", type=click.Choice(["sqlite", "jsonl", "memory"]))
@click.option("--db", default="durable.db")
def summary(backend, db):
    tasks, _ = load_tasks(backend, db)
    print(tasks.groupby("status").size().to_string())
```

## WHEN TO USE IN PRODUCTION
Wire it into an ops runbook so an on-call engineer can confirm whether an always-on
assistant resumed after a restart, and how many emails/messages were sent before the
crash. Useful for post-incident reviews of long-running jobs. Do NOT use it as a live
control plane — it is read-only reporting. For interactive terminal coding sessions use
your coding agent's own session viewer instead; Durable's JSONL storage is a *different*
multi-file format and this tool exists specifically to read that one.

## HOW IT HELPS STUDENTS
Students get hands-on practice with Click command design, Pandas `groupby`/aggregation,
and reading both SQLite and JSONL into one normalized schema. They learn why recovery
metadata (checkpoint name + done flag) is the real product of a durable harness, and how
to expose that as a decision-ready summary.

## STARTER CODE
See `starter/main.py` for a working Click CLI with a deterministic seeded sample dataset
so it runs without a live agent, plus TODO markers for the real SQLite/JSONL readers.
