pi-long-task 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 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
+
+- Adaptively reuse healthy, compatible worker sessions for related sequential TODOs, with explicit assignment boundaries and a conservative 62.5% default context threshold.
+- Expose worker-session start, reuse, retention, rotation, context-usage, and reason diagnostics through progress updates, task artifacts, and coordinator metrics.
+
+### Changed
+
+- Attribute cumulative reused-session cost and token statistics as task/attempt-level deltas across reuse, retries, counter resets, and rotations.
+- Rotate to fresh sessions after unsafe outcomes, incompatible configuration, unavailable or excessive context usage, and independent retries; reuse may be disabled to retain isolated assignment behavior.
+
+### Fixed
+
+- Collapse repeated `Finished:` and `Failed:` prefixes defensively in both active-status renderers.
+
 ## 0.4.0 - 2026-08-31
 
 ### Added

package/README.md

@@ -4,17 +4,18 @@
 [![Node.js >= 22.19](https://img.shields.io/badge/node-%3E%3D22.19-brightgreen)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**Pi Long Task** is a long-running task runner and subagent orchestrator for the [Pi coding agent](https://github.com/earendil-works/pi). It is a Pi extension that breaks large coding requests into tracked TODOs, executes them in isolated AI worker sessions, registers a real Pi TUI progress sidebar while a run is active, and optionally commits completed work.
+**Pi Long Task** is a long-running task runner and subagent orchestrator for the [Pi coding agent](https://github.com/earendil-works/pi). It is a Pi extension that breaks large coding requests into tracked TODOs, executes them in bounded AI worker sessions, registers a real Pi TUI progress sidebar while a run is active, and optionally commits completed work.
 
 If you are looking for a way to run long-running, multi-step, autonomous coding tasks with Pi — refactors, test coverage pushes, full feature builds, or entire product goals — this extension handles the planning, delegation, progress tracking, retries, and safe git commits for you.
 
-Use it when a coding request is bigger than one focused interaction. Pi Long Task creates or cleans up the TODO plan, hands each TODO to a fresh worker session, tracks every attempt, and keeps the run artifacts so you can inspect what happened later.
+Use it when a coding request is bigger than one focused interaction. Pi Long Task creates or cleans up the TODO plan, gives every TODO a task-scoped assignment, adaptively reuses a healthy compatible worker session when safe, tracks every attempt, and keeps the run artifacts so you can inspect what happened later.
 
 ## Why use it
 
 - **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.
@@ -25,7 +26,7 @@ When you ask Pi to run a long task, Pi Long Task:
 
 1. Recognizes natural-language requests like "run a long task with commits" and routes them to `pi_long_task`.
 2. Creates or cleans up a TODO plan from your request, optionally guided by a high-level `goal`. Natural-language planning uses a bounded planner session; if generated TODO markdown is invalid, Pi Long Task asks the planner to repair it once before failing the run.
-3. Works through each unfinished TODO task in order using isolated worker sessions.
+3. Works through each unfinished TODO task in order, reusing a healthy compatible worker session when its context remains safely below the configured limit and rotating otherwise.
 4. Registers a Pi TUI sidebar/widget when UI support is available and updates it with the current task, inferred subtask progress, and full task timeline while the run is active.
 5. Retries unfinished tasks up to the configured attempt limit.
 6. Records progress, planner diagnostics, task artifacts, and final results under `tmp/pi-long-task/<run-id>/`.
@@ -200,7 +201,7 @@ Use `with commits` or `commit true` only when you want Pi Long Task to create el
 
 ### 3. Monitor progress and completion
 
-During execution, Pi Long Task creates `tmp/pi-long-task/<run-id>/TODO.md` and `TASK_RESULT.md`, runs one isolated worker session per unfinished TODO in order, and retries unfinished tasks up to the configured attempt limit. Checked progress in pasted TODO markdown is preserved, so completed tasks are skipped when that artifact is supplied again. A task is marked complete only after the worker returns every required `TASK_RESULT` field without a session error, timeout, or cancellation, and the attempt evidence is appended before the TODO completion marker. In Pi TUI, watch the Long Task sidebar/widget for the active task, subtask checklist, task timeline, counts, and worker spend when available. In headless or non-UI runs, watch the partial tool-result updates in the main output. When the run finishes, the final response lists completed, failed, blocked, and remaining task counts plus the result and TODO file paths.
+During execution, Pi Long Task creates `tmp/pi-long-task/<run-id>/TODO.md` and `TASK_RESULT.md`, runs unfinished TODOs in order with adaptive worker-session reuse, and retries unfinished tasks up to the configured attempt limit. Every assignment remains task-scoped even when its SDK session is reused. Checked progress in pasted TODO markdown is preserved, so completed tasks are skipped when that artifact is supplied again. A task is marked complete only after the worker returns every required `TASK_RESULT` field without a session error, timeout, or cancellation, and the attempt evidence is appended before the TODO completion marker. In Pi TUI, watch the Long Task sidebar/widget for the active task, subtask checklist, task timeline, counts, and worker spend when available. In headless or non-UI runs, watch the partial tool-result updates in the main output. When the run finishes, the final response lists completed, failed, blocked, and remaining task counts plus the result and TODO file paths.
 
 ### Steer a run in progress
 
@@ -251,14 +252,128 @@ The actual sidebar is a Pi TUI overlay anchored on the right when the terminal i
 Pi Long Task coordinates a long request from planning through task completion:
 
 1. **Plan the work:** it creates a TODO plan from your request, or normalizes pasted TODO markdown so each item can be tracked consistently.
-2. **Run isolated workers:** each TODO is assigned to its own fresh worker session with the relevant task text, global instructions, attempt history, and commit setting.
+2. **Run bounded workers:** each TODO receives a new task-scoped assignment with the relevant task text, global instructions, attempt history, and commit setting. A healthy compatible SDK worker session may carry sequential assignments; each reused prompt includes an explicit assignment boundary.
 3. **Stream progress back:** the active worker's activity streams into the main Pi thread as partial tool results, so you can follow commands, edits, verification, and the final `TASK_RESULT` as they happen.
 4. **Update the Pi TUI sidebar:** when Pi provides UI support, the extension uses Pi's TUI UI APIs to maintain a real sidebar/widget that lists the full run timeline, including completed, active, upcoming, failed, or blocked tasks and inferred subtask progress from each task's `**Status:**` checklist.
 5. **Write run artifacts:** the coordinator writes the generated/normalized `TODO.md`, `TASK_RESULT.md`, attempt summaries, and final run details to `tmp/pi-long-task/<run-id>/`.
 6. **Commit only when enabled:** if `commit` is `true`, Pi Long Task may create a commit after each completed task using only eligible task changes. If commits are disabled, no commits are created; even when enabled, commits can be skipped when there are no eligible changes or the task outcome is not commit-worthy.
 
+### Adaptive worker-session reuse
+
+Reuse is enabled by default. Related sequential TODOs in the same coordinator run and worktree may share one idle Pi `AgentSession`, which avoids repeated startup and repository exploration. Reuse does not merge task semantics: every TODO still gets its complete current assignment, an explicit boundary from the previous assignment, its own result extraction, attempts, progress, and `TASK_RESULT` outcome.
+
+The default context-usage threshold is **62.5%**. A session is retained only while Pi reports valid context usage below that threshold. It is rotated at or above the threshold, or conservatively when context usage is missing or invalid. Rotation also occurs after timeout, abort, cancellation, unrecoverable or invalid session state, an obsolete assignment caused by steering, or a compatibility change in the coordinator run, repository/worktree, provider/model, worker options, or session configuration. All retained sessions are disposed when rotated or when the coordinator ends.
+
+You can put runtime directives in `inputText` (including pasted TODO global instructions):
+
+```text
+Worker session reuse: enabled
+Worker session reuse context threshold: 60%
+```
+
+The threshold accepts a percentage greater than `0` and at most `100`. An absent or invalid value uses the safe `62.5%` default. To restore the previous one-session-per-assignment behavior:
+
+```text
+Worker session reuse: disabled
+```
+
+Programmatic callers of `runCoordinator()` can use the corresponding options:
+
+```ts
+await runCoordinator({
+  commit: false,
+  inputText: "implement the TODO plan",
+  workerSessionReuse: true,
+  workerSessionReuseContextThresholdPercent: 60,
+});
+```
+
+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:
+
+- `workerSessionEvent`: `session_started`, `session_reused`, `session_retained`, or `session_rotated`
+- `workerSessionReason`: a stable diagnostic reason such as `fresh_session`, `reuse_eligible`, `context_threshold_reached`, `health_timed_out`, `model_mismatch`, or `reuse_disabled`
+- `workerSessionContextUsagePercent`: the observed context percentage when available
+- `workerSessionContextThresholdPercent`: the configured rotation threshold
+
+Each coordinator outcome may also include `sessionDiagnostics` entries with `event`, `reasonCode`, optional `contextUsagePercent`, optional `contextThresholdPercent`, and optional `previousTaskId`. These diagnostics are appended to the run's `TASK_RESULT.md`. The programmatic `CoordinatorResult.workerSessionMetrics` summarizes `starts`, `reuses`, `rotations`, `retained`, and counts by `rotationReasons` without removing or changing existing result fields.
+
+Pi session statistics can be cumulative across reused assignments. `outcomes[].workerCostTotal` and `outcomes[].workerUsage` are therefore calculated as nonnegative **task/attempt-level deltas** between assignment boundaries, not as the cumulative session totals. `CoordinatorResult.workerCostTotal` and `workerUsageTotal` aggregate those deltas exactly once across reuse, retries, and rotation; a statistics reset starts a new baseline. This keeps sidebar spend and the cost added to the parent Pi message task-accurate even when one session performs several TODOs.
+
 ## 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.
@@ -347,7 +462,7 @@ For vague goals, the loop runs as:
 2. classify the goal as vague and run discovery
 3. persist `GOAL_SPEC.json`
 4. generate implementation TODO markdown from the persisted specification
-5. run that generated TODO as a normal long task in an isolated worker session
+5. run that generated TODO as a normal task-scoped long-task coordinator run
 6. run a separate reviewer session that decides `complete`, `incomplete`, `blocked`, or `failed` against the persisted specification
 7. if the reviewer says `incomplete`, generate another TODO using previous review context plus the same persisted specification and repeat
 
@@ -369,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:
 
@@ -401,6 +524,12 @@ Safety controls:
   reviewerTimeoutMs?: number;
   maxAttemptsPerTask?: number;
   maxBashTimeoutMs?: number;
+  networkRecovery?: {
+    enabled?: boolean;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    maxOutageMs?: number | null;
+  };
 }
 ```
 
@@ -481,16 +610,16 @@ That smoke test creates disposable git repos and verifies both `commit: false` a
 
 ## Limitations and expectations
 
-- Tasks run sequentially, one TODO at a time; Pi Long Task prioritizes isolation, progress tracking, and safe handoff over parallel execution.
+- 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>/`.
 
 ## Keywords
 
-Pi extension, Pi package, Pi coding agent, AI coding agent, AI coding assistant, LLM agent, agentic coding, subagent orchestration, long-running tasks, task runner, task orchestration, TODO planner, autonomous coding, background coding agent, isolated worker sessions, multi-step coding tasks.
+Pi extension, Pi package, Pi coding agent, AI coding agent, AI coding assistant, LLM agent, agentic coding, subagent orchestration, long-running tasks, task runner, task orchestration, TODO planner, autonomous coding, background coding agent, adaptive worker sessions, multi-step coding tasks.
 
 ## License
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pi-long-task",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
-  "description": "Pi coding agent extension that breaks large coding requests into tracked TODOs and runs them in isolated 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.",
+  "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": [
     "pi",
     "pi-package",