# Crash-Recovery Harness Simulator

## PURPOSE
A SimPy + NumPy discrete-event simulation that compares two harness strategies under
random crashes: the plain Pi Coding Agent (JSONL sessions, truncated tool calls, manual
`continue`) versus Pi Durable (tasks with checkpoints, automatic resume). It quantifies
the difference the video describes using the "send my emails" example — how many emails
actually get sent, how many are duplicated, and how long recovery takes.

## WHY THIS MATTERS
The transcript's central claim is behavioural, not just architectural: when a crash
happens *mid tool call*, Durable continues "exactly at the point where it left off" while
the plain agent leaves a truncated tool call and waits for a human to type `continue`.
That claim is easiest to *feel* in a simulation where you can dial crash probability up
and down and watch the numbers move.

## HOW TO BUILD
1. Model each email send as a SimPy process with a small service time.
2. A `Crash` process samples inter-arrival times from an exponential distribution
   (NumPy `default_rng`, fixed seed for determinism).
3. Plain-harness mode: on crash the whole task restarts from step 0 and re-sends
   already-sent emails (duplicates), and no work resumes until a `continue` delay.
4. Durable mode: each completed send writes a checkpoint; after a crash the harness
   resumes at the next unsent email, with no human delay.
5. Run N trials, average, and print a comparison table.

```python
def send_emails(env, n, dur, crash_at):
    sent = 0
    while sent < n:
        yield env.timeout(dur)
        if crash_at and sent + 1 == crash_at:
            env.process(crash(env))       # durable: resume here; plain: restart
            crash_at = None
        sent += 1
    return sent
```

## WHEN TO USE IN PRODUCTION
Use this class of simulation before committing to a durable-harness design for agents
that make many irreversible side effects — sending emails, posting to Slack, filing
tickets — where a mid-operation crash could double-send. It sets recovery-time budgets
and expects the value of checkpoint granularity. Do NOT use it to benchmark raw model
latency; SimPy models the orchestration/recovery layer, not LLM inference. And do not
treat its crash model as real — it is an abstraction to build intuition.

## HOW IT HELPS STUDENTS
Students learn SimPy event scheduling, stochastic sampling with NumPy, and how to frame
a reliability question as a measurable experiment (duplicates, recovery time,
completion rate). It teaches the core durability lesson: checkpoint granularity trades
storage writes for less rework, and that trade-off is a design decision, not a footnote.

## STARTER CODE
See `starter/main.py` for a complete, deterministic SimPy simulation with both harness
modes, a seeded RNG, and a comparison summary. TODO markers show where to tune crash
rates and add checkpoint-cost accounting.
