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

Pi Durable organizes input, generation, and tool calls as durable tasks, continuing inference after results are committed.Enlarge diagram ↗
Pi Durable organizes input, generation, and tool calls as durable tasks, continuing inference after results are committed. Explanatory diagram based on pinned documentation and code.

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.

Ordinary commits are stored before publication; recovery re-enters saved phases rather than arbitrary code locations.Enlarge diagram ↗
Ordinary commits are stored before publication; recovery re-enters saved phases rather than arbitrary code locations. Explanatory diagram based on pinned documentation and code.

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.

An interrupted tool enters the replay path only when both its stored policy and current declaration permit safe replay.Enlarge diagram ↗
An interrupted tool enters the replay path only when both its stored policy and current declaration permit safe replay. Explanatory diagram based on pinned documentation and code.

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

  1. Stop the process before and after committing tool intent.
  2. Crash after an external effect but before committing its result.
  3. Cross-test stored and new replay-safe declarations.
  4. Change extension versions, directories, or task definitions before recovery.
  5. Inject storage failures, model-stream interruptions, and cancellation separately.
  6. 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.

Sentry close reading · HarnessFix close reading