pi-long-task 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 Notable changes to Pi Long Task are recorded here. This project follows semantic versioning.
 
+## 0.6.0 - 2026-09-05
+
+### Added
+
+- Add opt-in coordinator-level recovery after Pi exhausts its bounded provider retries, with configurable jittered backoff, a bounded five-minute outage window by default, and an indefinite wait-until-cancelled mode.
+- Show `Waiting for connection…` lifecycle status with retry and outage timing across worker, TODO planning, steering, goal planning/discovery, and review operations.
+- Classify transient transport, timeout, stream, overload, rate-limit, and retryable server failures while failing fast for authentication, authorization, billing, quota, invalid request/model, certificate, cancellation, and unknown failures.
+
+### Changed
+
+- Preserve TODO identity, ordinary attempt counts, durable evidence, accepted steering, working-tree changes, goal-loop state, and cost accounting while network recovery is active.
+- Exclude network-recovery time and retries from worker, planner, reviewer, goal-loop timeout and retry budgets; rotate interrupted sessions before safely resuming the same operation.
+
+### Security and reliability
+
+- Prevent blind replay of completed side-effectful worker actions by recording interruption evidence and requiring fresh continuation sessions to inspect durable state before acting.
+- Keep cancellation immediate during backoff and retry execution, with exact-once cleanup of recovery timers, listeners, sessions, and status resources.
+
 ## 0.5.0 - 2026-08-31
 
 ### Added

package/README.md

@@ -15,6 +15,7 @@ Use it when a coding request is bigger than one focused interaction. Pi Long Tas
 - **Take on bigger tasks:** split broad product, refactor, testing, or cleanup requests into smaller TODOs that Pi can complete one at a time.
 - **Track progress visibly:** in Pi TUI, see the active TODO, inferred `**Status:**` subtasks, completed/failed/blocked counts, and remaining work in the Pi Long Task sidebar while the run is active.
 - **Recover with retries:** tasks that do not report completion can be retried with context from previous attempts instead of losing the thread.
+- **Wait through transient outages:** optionally pause after Pi exhausts its bounded provider retries, show connection-wait status, and safely resume the interrupted coordinator phase.
 - **Commit safely when asked:** enable commits for completed task work, while generated run files and pre-existing dirty files are kept out of those commits.
 - **Keep task artifacts:** every run writes a generated `TODO.md`, generated `TASK_RESULT.md`, attempt summaries, and final status under `tmp/pi-long-task/<run-id>/`.
 - **Watch cost visibility:** worker spend is captured and surfaced in progress and final summaries when usage cost data is available.
@@ -289,6 +290,73 @@ await runCoordinator({
 
 Explicit, complete `status: partial` results may continue in the same healthy, compatible, below-threshold session on the next attempt. All independent retries—including timeout, abort, cancellation, errors, invalid/incomplete results, and non-partial failures—start fresh. Existing retry limits and delays are unchanged. Setting `workerSessionReuse: false` (or the disabling directive) always isolates assignments.
 
+### Coordinator-level network recovery
+
+Network recovery is **disabled by default** for backward compatibility. When enabled, it begins only after Pi has exhausted its own bounded provider-request retries. Pi Long Task then uses jittered exponential backoff starting at **1 second**, capped at **30 seconds**, for a maximum continuous outage of **5 minutes**. During recovery, progress displays `Waiting for connection…` with the retry number, next retry delay, or elapsed outage time. Cancellation interrupts both backoff waits and in-flight recovery calls immediately.
+
+Add directives to `inputText` or to the global instructions of a pasted TODO plan. These examples cover every mode:
+
+```text
+# Default: recovery is disabled; the timing defaults below are dormant.
+Run a long task without commits to implement @TODO.md.
+```
+
+```text
+# Bounded recovery using the default 1s base, 30s cap, and 5m outage window.
+Network recovery: enabled
+```
+
+```text
+# Bounded recovery with explicit timing.
+Network recovery: enabled
+Network recovery base delay: 2s
+Network recovery maximum delay: 45s
+Network recovery maximum outage: 10m
+```
+
+```text
+# Explicitly retain fail-fast behavior after Pi's own request retries.
+Network recovery: disabled
+```
+
+To wait indefinitely while the provider or network remains unavailable, enable recovery and set the maximum outage to `unlimited`, `indefinite`, or `until cancelled`:
+
+```text
+Network recovery: enabled
+Network recovery maximum outage: until cancelled
+```
+
+Indefinite mode has no outage deadline; it always remains cancellable. It does not turn deterministic errors into recoverable ones.
+
+Programmatic `runCoordinator()` callers can pass the same policy as structured options; `pi_long_task` and `pi_goal_task` expose the same `networkRecovery` object in their tool parameters:
+
+```ts
+await runCoordinator({
+  commit: false,
+  inputText: "implement the TODO plan",
+  networkRecovery: {
+    enabled: true,
+    baseDelayMs: 2_000,
+    maxDelayMs: 45_000,
+    maxOutageMs: 10 * 60_000,
+  },
+});
+```
+
+Use `maxOutageMs: null` for indefinite waiting or `enabled: false` to disable recovery. Durations must be positive finite safe integers, `maxDelayMs` must be at least `baseDelayMs`, and a bounded `maxOutageMs` must be at least `baseDelayMs`.
+
+#### Recovery classification boundaries
+
+Recovery is deliberately narrow. Recoverable failures include failed fetches; DNS, connection, and socket failures such as `ENOTFOUND`, `ECONNRESET`, or `ETIMEDOUT`; premature HTTP/WebSocket/stream termination; request and gateway timeouts; temporary provider overload; HTTP 408, 425, and overload-style 429 responses; and retryable server responses such as HTTP 500, 502, 503, and 504. Provider errors and nested causes are inspected so useful status, code, request ID, and retry metadata can be retained.
+
+Authentication and authorization failures, billing or credit failures, exhausted account/usage quota, invalid models, malformed or unsupported requests, context-length and content-policy failures, most other 4xx responses, non-retryable server responses, certificate/configuration failures, coordinator timeouts, cancellation, and unknown errors fail immediately through the existing error path. Deterministic evidence wins over transient-looking wrapper text—for example, a 429 response that says the account quota is exhausted is not treated as temporary rate limiting.
+
+#### Timeouts, limits, and preserved state
+
+Network retries have their own counter and outage window. Recovery waits do not consume TODO attempts, planner repair retries, reviewer retries, or goal-loop iterations. Time attributed to network recovery is excluded from worker, TODO-planner, reviewer, goal-iteration, and overall goal-loop timeout budgets; while connectivity is unavailable, `maxOutageMs` (or cancellation in indefinite mode) is the recovery limit. Once the operation resumes, its ordinary timeout and retry rules still apply. If the outage window expires, the run fails with the last classified network failure retained as evidence.
+
+Completed TODOs, current TODO identity and ordinary attempt number, durable attempt evidence, working-tree changes, accepted steering revisions, accumulated costs, and persisted goal/review state remain intact across an outage. An interrupted worker resumes the same TODO in a fresh session: the errored session is rotated, and the continuation is told to inspect the result artifact and current files before acting. This avoids blindly replaying already completed tool calls. The coordinator does not roll back external side effects, so tasks that call non-idempotent external systems should record durable completion/idempotency evidence that a resumed worker can verify.
+
 ### Reuse diagnostics and accounting
 
 Programmatic progress callbacks receive lifecycle updates with `phase: "worker_session"`. The additive fields are:
@@ -305,6 +373,7 @@ Pi session statistics can be cumulative across reused assignments. `outcomes[].w
 ## Feature reference
 
 - **Adaptive worker-session reuse:** reuse healthy compatible sessions below the 62.5% default context threshold, while preserving task boundaries and rotating conservatively.
+- **Optional network recovery:** wait through classified transient provider/transport outages without consuming ordinary attempts, while keeping deterministic failures fail-fast and cancellation immediate.
 - **Real Pi TUI sidebar:** in TUI sessions, every TODO appears in a registered sidebar/widget with past, current, and future statuses so you can distinguish completed, active, upcoming, failed, blocked, and remaining work at a glance.
 - **Main-thread worker activity:** the active worker still streams commands, edits, verification, and its per-task `TASK_RESULT` back into the main Pi conversation; the sidebar does not replace tool-result rendering.
 - **Cost visibility:** worker spend is included in Pi Long Task progress and is added to the main Pi `$ spent` total when cost data is available.
@@ -415,24 +484,32 @@ Safety controls:
 - `iterationTimeoutMs` caps each generation, execution, and review sequence; default is `10800000` ms (3 hours).
 - `reviewerTimeoutMs` caps each reviewer session within the remaining overall and iteration budgets; default is `1800000` ms (30 minutes).
 - tool cancellation is passed through, bounded locally even if an SDK prompt does not settle after abort, and stops the loop with `cancelled` status.
+- `networkRecovery` applies the same coordinator recovery policy to discovery, TODO generation/execution, and review; its wait time is excluded from goal-loop deadlines and iteration counts.
 - `maxAttemptsPerTask` and `maxBashTimeoutMs` are forwarded to worker long-task runs.
 - `commit` controls whether implementation workers may commit; goal loops default to `commit true`, so pass `commit false` when you want to review all changes first.
 
 ## Options
 
-`pi_long_task` has one required input and two optional inputs:
+`pi_long_task` has one required input and three optional inputs:
 
 ```ts
 {
   commit: boolean;
   inputText?: string;
   goal?: string;
+  networkRecovery?: {
+    enabled?: boolean;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    maxOutageMs?: number | null;
+  };
 }
 ```
 
 - `commit` controls whether Pi Long Task may create git commits.
 - `inputText` optionally provides the request or TODO markdown to work on.
 - `goal` optionally provides a high-level desired outcome that is passed to TODO planning and worker task prompts. Coverage goals such as `have testing line coverage above 80%` add coverage-specific planning and verification guidance.
+- `networkRecovery` optionally enables and tunes coordinator-level transient network recovery. See [Coordinator-level network recovery](#coordinator-level-network-recovery) for defaults and safety behavior.
 
 `pi_goal_task` accepts a high-level goal plus safety controls:
 
@@ -447,6 +524,12 @@ Safety controls:
   reviewerTimeoutMs?: number;
   maxAttemptsPerTask?: number;
   maxBashTimeoutMs?: number;
+  networkRecovery?: {
+    enabled?: boolean;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    maxOutageMs?: number | null;
+  };
 }
 ```
 
@@ -530,7 +613,7 @@ That smoke test creates disposable git repos and verifies both `commit: false` a
 - Tasks run sequentially, one TODO at a time; Pi Long Task prioritizes task isolation, progress tracking, and safe handoff over parallel execution. Adaptive reuse may share the underlying SDK session only while policy checks remain safe.
 - Natural-language TODO planning has a bounded time budget (five minutes by default, with a short graceful-shutdown request). If planning times out or is aborted before a valid plan exists, the run fails before worker tasks start and records planner diagnostics in `TASK_RESULT.md`.
 - If the planner returns invalid TODO markdown, Pi Long Task makes one repair attempt. A second invalid response fails planning with diagnostics instead of guessing at a plan.
-- Real runs require usable Pi model credentials, such as a working Pi login or API key for the selected model.
+- Real runs require usable Pi model credentials, such as a working Pi login or API key for the selected model. Network recovery does not retry invalid or exhausted credentials, billing failures, or account quota exhaustion.
 - Worker spend is added to the main Pi `$ spent` total as cost-only usage. Token counts are not merged into the main thread because worker sessions have separate context windows, and merging their token usage would corrupt the main conversation's context statistics.
 - Run artifacts are written under `tmp/pi-long-task/<run-id>/`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-long-task",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Pi coding agent extension that breaks large coding requests into tracked TODOs and runs them in bounded, adaptively reused AI worker sessions. A long-running task runner and subagent orchestrator for Pi, with a live TUI progress sidebar, retries, goal loops, and optional per-task git commits.",
   "keywords": [