# What changed in @earendil-works/pi-durable

> 71 changes in @earendil-works/pi-durable 1 from its official release notes, upgrade guides and advisories: 22 breaking, 38 new APIs and options. Each one cited. Sources checked 2026-11-01. HTML: https://unstale.sh/npm/@earendil-works/pi-durable/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @earendil-works/pi-durable 1

### Breaking changes

- Every defineDoc definition now requires an explicit checkpointWhen predicate; there is no default. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Every defineDocFamily definition now requires an explicit checkpointWhen predicate; there is no default. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Tasks now have a sleeping status; code handling every TaskState, TaskGraphState, or TaskInspection state needs a case for it. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Opening SQLite storage automatically migrates it to schema version 2 and rebuilds its task table. Migrated databases cannot be opened by 1.3.0 or earlier, preventing rollback past this release. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- The exemption is limited to reads: errors thrown by commit() or mintId() fail the Harness like any other storage error. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Removed because waiting inside a phase holds an invocation and can restart the wait after a restart. Use sleepUntil() or return sleeping from commit(), and move post-wait work into the next phase. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Its type is now boolean instead of true; false does not end the run. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Adds access to the Harness clock; hand-built TaskRuntime and ToolExecutionApi objects must include the new methods. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- After compaction, or when a first baseline follows earlier answers, the baseline leads model context when kept history includes an assistant message; other system messages after an assistant message stay in place. (1.3.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#130---2026-10-15)
- A nonzero exit now returns an error result with an exit_code diagnostic instead of throwing tool_error. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- A generation now fails with model_error if its blocking threshold compaction failed, faulted, was orphaned, or was directly aborted, rather than sending a request anyway. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- A submission containing only kind and data is appended and settled immediately, even while busy or queued; it does not change what the model sees. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- pi.tool is version 2 and migrates live version 1 tasks. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- A nonzero exit now returns an error result with an exit_code diagnostic instead of throwing tool_error. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Rejects waits that form a cycle through waits and held owners, naming the cycle, rather than leaving tasks waiting forever. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Any Storage method error, including a read, fails and closes the Session; later calls and pending waits reject with SessionFailed, and nothing is retried. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- StorageRejected is removed; StorageRequestError represents invalid requests and fails only that call. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Storage throws StorageRequestError for an invalid request, which fails only that call. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Throwing or rejected listener callbacks are reported through onReport instead of failing the operation that ran them. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Throwing or rejected listener callbacks are reported through onReport instead of failing the operation that ran them. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- The content field is replaced by output, alongside the new structuredOutput field. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- ToolTaskInput and ToolTaskResult are tagged unions: model-issued calls use kind: "model" and nested calls use kind: "nested". (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)

### New APIs and options

- SQLite drivers, portable interfaces, and the generic migration runner now come from this package; existing Durable SQLite entry points continue re-exporting their public names. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Runs a task again after the crash-loop guard parks it. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Reports whether work can run or the earliest sleep time, allowing hosts to schedule process wakeups. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Sets a pi-ai ClientIdentity for User-Agent and provider attribution on every model request through the Harness, including hooks and tools. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Notifies a host when the Session needs a process; when configured, the Harness keeps no timer for sleeps so hosts can hibernate and resume on an alarm. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Arms Session, scheduler, and task timers, including for createSession(); with now, timers use a host or fake clock. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Enables content-free telemetry for submissions, task phases, committed events, checkpoints, tool replay, reports, and optional metrics and trace propagation. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Adds browser storage backed by IndexedDB. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- The callback now receives a second argument, info, describing the report; callbacks written for one argument continue to work. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Controls whether inputs queued behind a run failing with model_error or no_model are kept, run next, or settled unanswered with reason run_failed. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Sets compaction thresholds per exact provider/modelId, so one Harness can serve models with different context-window sizes. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Sets how many consecutive cutoffs without a committed state are allowed before a task is parked; set it to Infinity to retain the old behavior. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Shows why a task cannot run, including missing_task, task_too_old, migration_failed, and restart_limit. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Tracks task restarts caused by a crash, eviction, or reset; a newly committed state starts the count over. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Accepts an optional from argument for reports. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Adds a way to pace work inside a phase without waiting for it. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Adds durable sleeping that ends a task phase; the task resumes at its checkpoint once the Harness clock reaches until. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Forwards the prefix option so Durable Object SQLite storage can namespace tables and indexes in a shared database. (1.3.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#130---2026-10-15)
- Forwards the prefix option so Node SQLite storage can namespace tables and indexes in a shared database. (1.3.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#130---2026-10-15)
- Accepts a prefix to namespace every table and index, allowing the database to be shared with host tables. (1.3.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#130---2026-10-15)
- Reads the bounded output the model will see. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Bounds the Session document cache by use; unobserved documents are released after the retention period, which defaults to ten minutes and can be set to 0. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Adds a codemode tool whose scripts call conversation tools as nested calls and replay deterministically from a journal across restarts. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Provides a Photon WebAssembly image processor with Node and Cloudflare loaders. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Provides the coding agent's tool_search tool, which searches deferred tools with BM25 and loads matches. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- ExecutionEnv optionally supports bounded, gitignore-aware tree listings, with ListFilesOptions, FileListing, and FileListEntry types. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Input submissions can place content in an entry of a specified kind and data instead of pi.user; the kind must not start with pi. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- pi.agent modelTools controls which tools a conversation offers the model; addTools also extends it. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Keeps the newest compaction failure until a compaction produces a summary; agent snapshots carry it as compactionFailure. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Session.closed settles after closure with either a closed reason or a failed reason and error. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Tools can declare a structured output schema; the Harness validates structuredOutput and provides it to programs calling the tool. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Aborts an in-memory-awaited task and its owned work when a later Harness starts scheduling, before any work runs again. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Aborts a task owned by this task and waits until it is terminal. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Returns copies of the live tasks directly owned by a task, regardless of which invocation created them. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Tools can call another tool as a nested call, with validation, hooks, output limits, replay policy, and a NestedToolExecutionResult returned to the caller. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Controls whether a tool may be called by the model, nested tools, or both; both is the default. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- Keeps a tool from the model until modelTools names it; deferred tools can be loaded through the new add mechanism. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)
- WatchEnd gains a session_failed variant carrying the error. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)

### Performance

- Encodes a 3 MiB image without using about 140 MB of heap, avoiding the Cloudflare Durable Object 128 MB memory limit. (1.3.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#130---2026-10-15)

### Behavior and default changes

- Generation retry backoffs, deferred-response polls, and compaction retry backoffs now sleep instead of waiting in a running phase, allowing a process to stop or hibernate during them. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Now accepts a function returning the current model value, evaluated at each use so hosts can replace model configuration without reopening the Harness. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Code mode now measures script deadlines and wall time using the Harness clock instead of Date.now(). (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Now accepts a function returning the current settings value, evaluated at each use so hosts can replace settings without reopening the Harness. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- A task phase that faults is now reported through onReport as task_faulted, rather than only being recorded in its outcome. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Adapters created for the same storage object now coordinate operations, allowing multiple Pi storages to safely share one Durable Object database. (1.3.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#130---2026-10-15)
- Returns supported PNG, JPEG, GIF, and WebP images as image blocks within model limits instead of an unsupported_image error. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)

### Fixes and other changes

- Idle document and context eviction timers are declined in Workers with nodejs_compat, allowing Durable Objects to hibernate; memory is freed at later commits. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- The Node environment now detects the legacy WSL bash.exe launcher from %SystemRoot% instead of assuming C:\Windows. (1.4.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#140---2026-10-21)
- Thinking is no longer included in the summarization request, avoiding requests that exceed the context being summarized. (1.2.0) — [release notes](https://github.com/earendil-works/pi/blob/35dfa757378bd7a8570670e99c2687bdd1039a06/packages/durable/CHANGELOG.md#120---2026-10-12)