Prepared with AI assistance from pinned documentation and selected source code. Recovery experiments were not run.
Pi Durable represents model generation and tool calls as durable tasks. After a process restart, committed state determines what can continue; recovery involves more than reloading chat history.
This review examines the experimental @earendil-works/pi-durable package independently. Its recovery contracts should not be assumed to apply to the ordinary Pi CLI.
Architecture: from an in-memory loop to task state machines
Enlarge diagram ↗
The diagram omits end hooks, additional inputs, and error branches.
| Object | Meaning |
|---|---|
| Submission | An admitted input whose completion or failure can be awaited |
| Entry | An immutable message or result record |
| Document | Structured state updated through commits |
| Task | Work organized into states and checkpoints |
| Generation | Calls the model and coordinates its child tool tasks |
| Tool task | One tool call and its result handling |
The main loop still connects the LLM, tools, and results, but its progression includes durable task state. The implementation builds on pi-ai and Chord.
Source: pinned specification.
Model input: stored history and model-visible context differ
Input is first admitted as a Submission and then becomes a conversation entry. Generation uses the conversation’s model, instructions, tools, and effective context.
Resubmitting the same requestId can find the original Submission rather than admit a duplicate. This does not guarantee exactly-once effects for every external tool.
| Data | Storage and use |
|---|---|
| Conversation entries | Retained after commit and used to construct model context |
| Model and extension selections | Names and configuration are stored; implementations are resolved at runtime |
| Compaction summary | A summary entry is added; older entries remain stored |
| Reset | Changes where the model’s visible history begins without deleting older records |
| Tool results | Become available to later generation after the corresponding tasks settle |
Stored information is not necessarily sent to the model. Reset, compaction, and request construction still determine visibility.
Source: concepts, input, and compaction.
Recovery resumes a phase, not an arbitrary line of code
Tasks have phases and checkpoints. When a process stops inside a phase, recovery re-enters that phase from its beginning.
Enlarge diagram ↗
This is the ordinary commit path. Specified deferred document updates may become visible in memory before persistence; a crash can lose the unsaved portion.
The transaction does not include arbitrary external effects. Sending mail, writing to a remote system, or starting a process is not automatically atomic with local task state.
Analysis: recovery boundaries become clearer, but tool authors still need to handle repetition between checkpoints.
Source: commit invariants and deferred exceptions.
The key design: may an interrupted tool be replayed?
Tool intent is committed before execution. Recovery uses saved state rather than automatically retrying every interrupted call.
Enlarge diagram ↗
The implementation checks both the stored replay policy and the current tool declaration. Merely changing the new declaration to safe does not authorize replay of an old unsafe call.
| Property | Is it obtained automatically? |
|---|---|
| Distinguishing replay-safe and replay-unsafe tools | An explicit mechanism exists |
| Avoiding blind replay of unsafe tools by default | A corresponding recovery path exists |
| Correctly declaring a tool safe | Requires independent validation |
| Exactly-once external effects, such as payments or email | Not automatically guaranteed |
replay: "safe" is a contract, not automatic idempotence. External effects require idempotency keys or another independently checkable mechanism.
Public tests cover stored/current policy combinations, partial output, interruption, and replay. This review inspected their code but did not run them.
Sources: tool-task implementation, recovery tests.
Model requests and cancellation have distinct states
A crash during a model request counts as a failed attempt. Partial answers are retained as aborted records, and subsequent processing follows the retry budget.
If a provider is already generating a deferred response, recovery continues polling it instead of creating another request.
| Mechanism | Reliability role | Remaining concern |
|---|---|---|
| Retry budget and backoff | Avoid immediate repeated failure | Cost and duplicate adoption of partial responses |
| restartLimit | Bound repeated interruptions of one task | Configuration can disable the limit |
| Persisted waiting state | Wait for time or children without an active phase | The host must wake the scheduler correctly |
| Task ownership | Associate parent work and child tasks | Background boundaries change cancellation propagation |
| Cancelling a wait | Stop the caller from waiting | This does not cancel the underlying work |
Code that ignores cancellation can still delay shutdown. Controlled termination requires cooperation from executing tasks.
Sources: generation task, recovery, waiting, and cancellation.
Extensions and RSI: new code must understand old state
Extensions can supply tools, prompt sections, hooks, wrappers, and task definitions. Conversations store extension names; the host provides registry implementations.
A prepared model request fixes its model, prompt, and offered tools. Tool phases resolve current configuration, so updates can affect calls the model already proposed.
| RSI change | Additional validation |
|---|---|
| Tool implementation | Can new code interpret old execution intent? |
| Replay policy | Are unsafe effects incorrectly declared safe? |
| Task phases | Do existing checkpoints need migration? |
| Removed extension | Are unfinished tasks blocked by missing definitions? |
| End hooks | Can repeated continuation escape a local budget? |
maxTurns bounds the tool rounds of a run, but continue and onYield continuation may restart counting. The host must bound total work.
Analysis: RSI validation must assess task outcomes and compatibility when new code takes over existing state.
Sources: task and extension contracts, configuration and limits.
Which conditions qualify the durability guarantee?
| Condition | Boundary |
|---|---|
| MemoryStorage | Memory only; no cross-process recovery guarantee |
| SQLite with default WAL/NORMAL | Documentation distinguishes process crashes from power or host failures |
| JSONL | fsync affects persistence; writable opening also performs repair |
| Write ownership | Documentation requires one writer process; no general cross-process write lock |
| Deferred updates | Visible state can lead storage; unsaved changes can be lost |
| Storage failure | The Harness fails and closes rather than pretending commits succeeded |
Durability is not a switch that prevents every loss. Storage, host lifecycle, and tool contracts must be validated together.
The ordinary Pi coding-agent dependency list does not establish adoption of this recovery runtime. This review treats it as a separate package.
Sources: storage and error rules, commit specification, CLI dependencies.
Relationship to Sentry and HarnessFix
| System | Main concern | Research role |
|---|---|---|
| Sentry | Detect behavioral failures and provide targeted recovery guidance | A baseline for behavioral recovery and experience learning |
| HarnessFix | Diagnose harness flaws from traces and generate patches | Direct prior work on implementation repair |
| Pi Durable | Organize recoverable execution through commits, task states, and replay policies | A concrete system for reliability contracts and fault injection |
These operate at different layers and cannot be ranked directly by task scores.
Suggested experiments, not yet executed
- Stop the process before and after committing tool intent.
- Crash after an external effect but before committing its result.
- Cross-test stored and new replay-safe declarations.
- Change extension versions, directories, or task definitions before recovery.
- Inject storage failures, model-stream interruptions, and cancellation separately.
- Compare visibility under ordinary and deferred commits.
Measure duplicate effects, incorrect replay, permanent blocking, lost constraints, and recovery cost. Resuming work does not establish exactly-once external effects.
Scope: commit 3c9a86bb08398a425f95a81ba4339aa76151f5a1; the README, specification, relevant tool/generation implementation, and recovery tests were inspected. The API is experimental. No recovery experiment was installed or run.