Upgrading from v0.24.1 to v0.25.0

v0.25.0 hardens the private attempt pipeline and fixes accounting when provider exceptions are reused. Public signatures, result schemas, artifact formats, replay semantics, and cleanup contracts remain unchanged. Existing JSONL and SQLite checkpoints need no migration or invalidation.

Exception reuse and failed usage

Classification and failed-attempt token accounting now belong to each attempt and item. Reusing an exception across retries, strategies, or concurrent items no longer carries stale classification or accumulated tokens into later work. The original exception instance is preserved on raising surfaces.

Provider and custom _failed_token_usage stamps remain supported, including read-only mappings. They describe that exception's reported usage. The executor no longer adds or overwrites _failed_token_usage on any exception, including framework-created ones such as RateLimitRetriesExceeded, FrameworkTimeoutError, and deadline/abort errors. It also no longer attaches private classification and timing metadata. Read WorkItemResult.token_usage and WorkItemResult.timing for item accounting. Code that inspected private executor attributes on exceptions should use those result fields instead.

Late usage supplied by on_error remains included in reported item totals. Quota reconciliation still completes before that hook, so those late reports do not retroactively change admission accounting. An explicit all-zero usage stamp means known zero; copying an unknown zero-filled compatibility dictionary into a stamp loses its provenance. See token-aware admission for the complete usage rules.

Failed results now preserve accumulated admission wait when an item deadline interrupts retry backoff. admission_wait_seconds agrees with the timing record on that path, rather than incorrectly reporting zero.

SQLite maintenance

The SQLite wait helper keeps its 50 ms backup wakeup, and all three indexes stay in place. No schema change is required. The new maintenance evidence explains those retention decisions, the unresolved historical wait report, and how to reproduce the measurements. This release makes no SQLite speedup claim.

Upgrading from an earlier version

Applications upgrading from before v0.24 should also read the v0.24 migration guide, particularly its cleanup, cancellation, stream-terminal, and middleware-before-replay changes. v0.25 does not change those contracts.