feat(pi): drain pi durable actors across upgrades

[eersnington]

A deploy stops actors in the middle of runs. Pi Durable resumes from its checkpoints, but the model call or tool call that was running is lost and starts again. piDurable() now lets live work finish before the actor moves.

sequenceDiagram
  participant E as Engine
  participant A as piDurable actor
  E->>A: stop (deploy, version drain)
  A->>A: take the drain deadline
  A->>A: app onSleep
  A->>A: drain: wait until no run is active, or the deadline passes
  A->>A: harness.close(), suspend the sandbox
  Note over E: requests are held until the next generation is ready
  E->>A: next generation starts
  A->>A: open, app onWake, harness.resume()

Loading

Event	Behavior
Idle sleep	Nothing to wait for: keepAwake already blocks idle sleep while work runs
Forced stop (deploy)	Drain, then close and suspend the sandbox, all inside sleepGracePeriod
Run outlives the drain	Close still runs. Pi's records are stored, and the run resumes on the next wake
Destroy	No drain: stop at once, there is no next generation

RivetKit's grace deadline covers all of onSleep. The drain deadline is taken before the app's own onSleep, and keeps time back for closing:

// src/drain.ts
const closeReserve = Math.min(30_000, gracePeriodMs / 4);
return Date.now() + gracePeriodMs - closeReserve;

• sleepGracePeriod defaults to 15 minutes for piDurable(). The engine's actor_stop_threshold (30 minutes by default) is the hard limit.
• Blocked tasks and waits over 60 s do not hold the drain.
• Input sent during the stop reaches the next generation. A retry with the same requestId is deduplicated by Pi Durable.
• A failed open on wake does not fail the wake. Actions report Pi's error, and c.pi in the app's onWake throws it.

Upgrades use Pi Durable's own versioning, with nothing added on top:

• A task stored by version 1 runs under version 2 through its migrate. Without one, it is reported blocked in harness.inspect().
• Storage written by a newer Pi Durable schema is refused by Pi, and actions fail with internal_error. Schema upgrades are roll forward only.

---

This is part 5 of 11 in a stack:

•  11  fix(pi): persist migrated pi() session entries #330
•  10  feat(pi): expose the pi session to actor code as c.pi #329
•  9  perf(pi): connect the pi() sandbox on first use #328
•  8  feat(pi): drain and resume pi() runs #327
•  7  chore(examples): bump the docs examples to pi-coding-agent 1.0.2 #326
•  6  test(pi): let a run finish and the actor sleep when its caller disconnects #325
•  5  feat(pi): drain pi durable actors across upgrades #324 👈
•  4  feat(pi): stream pi durable conversations to clients #323
•  3  feat(pi): add piDurable actor #322
•  2  feat(pi): store pi durable sessions in actor sqlite #321
•  1  feat(pi): add piDurable() and drain, resume, and c.pi for pi() #320