pi-long-task 0.3.12 → 0.3.14

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+Notable changes to Pi Long Task are recorded here. This project follows semantic versioning.
+
+## 0.3.14 - 2026-08-20
+
+### Documentation and metadata
+
+- Improve npm and GitHub discoverability with a richer package description, expanded keywords, and added `repository`, `homepage`, `bugs`, and `engines` fields.
+- Add npm version, Node.js, and license badges, a keyword-rich introduction, and the embedded package preview image to the README.
+
+## 0.3.13 - 2026-07-22
+
+### Fixed
+
+- Require complete, machine-readable worker results and reject false completion after session errors, timeouts, or cancellation.
+- Bound worker and reviewer cancellation even when an SDK prompt or graceful follow-up does not settle.
+- Preserve checked TODO progress, durable attempt ordering, retry commit baselines, and accurate failure evidence.
+- Resume persisted goal-loop phases without repeating completed generation or execution work.
+- Enforce overall and iteration deadlines consistently across generation, execution, and review.
+- Retain structured terminal goal results and persisted cost totals across cancellation, failure, and resume paths.
+
+### Compatibility and maintenance
+
+- Declare the supported Node.js floor as 22.19.0 and document validation against Pi 0.80.7, 0.80.8, and 0.81.1.
+- Refresh the controllable transitive development lockfile resolutions for `brace-expansion` and `protobufjs`.

package/README.md

@@ -1,6 +1,12 @@
 # Pi Long Task
 
-Pi Long Task is a Pi extension that breaks large coding requests into tracked TODOs, executes them in isolated worker sessions, registers a real Pi TUI progress sidebar while a run is active, and optionally commits completed work.
+[![npm version](https://img.shields.io/npm/v/pi-long-task.svg)](https://www.npmjs.com/package/pi-long-task)
+[![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.
+
+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.
 
@@ -194,10 +200,12 @@ 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. 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 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.
 
 ## What it looks like
 
+![Pi Long Task running in the Pi TUI with a live progress sidebar showing the task timeline, subtasks, and worker spend](docs/assets/package-preview.png)
+
 In Pi TUI, Pi Long Task keeps worker activity in the main tool result flow and registers a real right-side TUI sidebar for the run timeline:
 
 ```text
@@ -331,16 +339,16 @@ When a `pi_goal_task` goal is already concrete, existing direct behavior is pres
 
 `pi_long_task` behavior is unchanged. Discovery is only enabled by default for `pi_goal_task`; direct long-task planning, TODO normalization, worker execution, progress display, retries, artifacts, and commit behavior continue to work as before.
 
-Goal-loop artifacts are stored under `tmp/pi-goal-task/<goal-run-id>/`, including `GOAL_STATE.json`, `GOAL_TRACE.jsonl`, `GOAL_RESULT.md`, optional `GOAL_SPEC.json` for discovered goals, and per-iteration generated TODO, worker, and reviewer files. Child TODO execution still writes normal `tmp/pi-long-task/<run-id>/` artifacts.
+Goal-loop artifacts are stored under `tmp/pi-goal-task/<goal-run-id>/`, including `GOAL_STATE.json`, `GOAL_TRACE.jsonl`, `GOAL_RESULT.md`, optional `GOAL_SPEC.json` for discovered goals, and per-iteration generated TODO, worker, and reviewer files. Persisted `pending`, `todo_generated`, `todo_executed`, `failed`, and reviewed boundaries can be resumed by SDK callers without rerunning completed phases or rewriting existing result/trace history. Child TODO execution still writes normal `tmp/pi-long-task/<run-id>/` artifacts.
 
 Safety controls:
 
 - `minIterations` prevents early success before the requested number of loops; default is `1`.
 - `maxIterations` stops retry loops when the reviewer keeps finding remaining work; default is `50`. If explicitly provided without `minIterations`, it is also used as the minimum target.
 - `timeoutMs` caps the overall goal loop; default is `172800000` ms (48 hours).
-- `iterationTimeoutMs` caps each generated TODO worker iteration; default is `10800000` ms (3 hours).
-- `reviewerTimeoutMs` caps each reviewer session; default is `1800000` ms (30 minutes).
-- tool cancellation is passed through and stops the loop with `cancelled` status.
+- `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.
 - `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.
 
@@ -414,12 +422,18 @@ When `commit` is `true`, it may commit eligible task changes after a task report
 
 - generated run files under `tmp/pi-long-task/`
 - generated `TASK_RESULT.md` files
-- files that were already dirty before the task started
+- files that were already dirty before the task's first attempt (the same protected baseline is retained across retries)
 
 This lets you keep existing local work separate from Pi Long Task changes.
 
 Commit messages are generated from the task title and adjusted to resemble recent commit-message style in the repository. Pi Long Task does not prefix commits with generated labels like `Complete TODO 1 — ...`.
 
+## Runtime compatibility
+
+Pi Long Task requires Node.js 22.19 or newer, matching the supported runtime of the Pi SDK versions used by the package. The extension and isolated-worker setup are validated against Pi 0.80.7 (legacy `AuthStorage`/`ModelRegistry`), Pi 0.80.8 (the `ModelRuntime` transition), and Pi 0.81.1. Older Pi releases may use the legacy fallback but are not part of the validated matrix.
+
+The Pi TUI is optional: JSON and print modes run without sidebar registration, and RPC mode uses the non-component widget path. Git is required only when commit mode is enabled. Model credentials are not required to load the extension, but they are required to execute planner, worker, or reviewer model sessions.
+
 ## Development and validation
 
 Run the local development checks:
@@ -429,7 +443,7 @@ cd /path/to/pi-long-task
 npm run check
 ```
 
-The development SDK tracks current Pi releases. Pi Long Task uses Pi's `ModelRuntime` worker API on Pi 0.80.8 and newer, with a legacy worker-model fallback for older compatible Pi releases.
+The development SDK tracks current Pi releases. There is no separate build command: Pi loads the TypeScript extension directly through its supported package loader, while `npm run typecheck` validates the source without emitting JavaScript.
 
 Check that Pi can load the extension:
 
@@ -454,6 +468,10 @@ That smoke test creates disposable git repos and verifies both `commit: false` a
 - 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.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,16 +1,43 @@
 {
   "name": "pi-long-task",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "type": "module",
-  "description": "Pi extension for breaking down and running long coding tasks safely.",
+  "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.",
   "keywords": [
+    "pi",
     "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "coding-agent",
+    "ai-coding-agent",
+    "ai-coding-assistant",
+    "llm-agent",
+    "agentic-coding",
+    "subagent",
     "long-task",
+    "long-running-tasks",
     "task-runner",
-    "coding-agent",
-    "pi-extension"
+    "task-orchestration",
+    "todo-planner",
+    "autonomous-coding",
+    "background-agent",
+    "worker-sessions",
+    "ai-automation",
+    "developer-tools"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thestuntcoder/pi-long-task.git"
+  },
+  "homepage": "https://github.com/thestuntcoder/pi-long-task#readme",
+  "bugs": {
+    "url": "https://github.com/thestuntcoder/pi-long-task/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "files": [
+    "CHANGELOG.md",
     "LICENSE",
     "README.md",
     "scripts",
@@ -52,13 +79,5 @@
     "typescript-eslint": "^8.61.1"
   },
   "license": "MIT",
-  "author": "Dejan Jacimovic <dejan@stuntcoders.com>",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/thestuntcoder/pi-long-task.git"
-  },
-  "bugs": {
-    "url": "https://github.com/thestuntcoder/pi-long-task/issues"
-  },
-  "homepage": "https://github.com/thestuntcoder/pi-long-task#readme"
+  "author": "Dejan Jacimovic <dejan@stuntcoders.com>"
 }

package/src/coordinator.ts

@@ -228,14 +228,21 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
   await mkdir(runtime.runDir, { recursive: true });
   await writeFile(runtime.taskResultPath, initialTaskResultMarkdown(runtime.runId), "utf8");
   let planningComplete = false;
+  let latestTodoMarkdown: string | undefined;
+  let latestTasks: Task[] = [];
+  let activeTask: Task | undefined;
+  let activeAttempt: number | undefined;
+  const protectedDirtyPathsByTask = new Map<string, Set<string>>();
 
   try {
     emitProgress(runtime, "Creating TODO plan...", { phase: "planning" });
     let todoMarkdown = await generateOrNormalizeTodoMarkdown(inputText, runtime);
     validateTodoMarkdown(todoMarkdown);
     planningComplete = true;
+    latestTodoMarkdown = todoMarkdown;
     await writeFile(runtime.todoPath, todoMarkdown, "utf8");
     const initialTasks = parseTasks(todoMarkdown);
+    latestTasks = initialTasks;
     emitProgress(runtime, `Created TODO plan with ${initialTasks.length} task(s).`, {
       phase: "planned",
       totalTasks: initialTasks.length,
@@ -247,6 +254,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
 
     while (!runtime.abortSignal?.aborted) {
       const tasksBeforeAttempt = parseTasks(todoMarkdown);
+      latestTasks = tasksBeforeAttempt;
       const nextTask = tasksBeforeAttempt.find((task) => !task.done);
       if (!nextTask) {
         break;
@@ -269,9 +277,15 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
           }),
         },
       );
-      const preExistingDirtyPaths = options.commit
-        ? await gitDirtyPaths(runtime.cwd, runtime.taskResultPath, runtime.todoPath, runtime.runDir)
-        : new Set<string>();
+      let preExistingDirtyPaths = protectedDirtyPathsByTask.get(nextTask.taskId);
+      if (!preExistingDirtyPaths) {
+        preExistingDirtyPaths = options.commit
+          ? await gitDirtyPaths(runtime.cwd, runtime.taskResultPath, runtime.todoPath, runtime.runDir)
+          : new Set<string>();
+        protectedDirtyPathsByTask.set(nextTask.taskId, preExistingDirtyPaths);
+      }
+      activeTask = nextTask;
+      activeAttempt = attempt;
       const outcome = await runtime.workerRunner({
         cwd: runtime.cwd,
         todoPath: runtime.todoPath,
@@ -294,11 +308,6 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       outcomes.push(outcome);
       finalizeWorkerCost(runtime.workerCostState, outcome);
 
-      if (outcome.done) {
-        todoMarkdown = markTaskDone(todoMarkdown, nextTask.taskId);
-        await writeFile(runtime.todoPath, todoMarkdown, "utf8");
-      }
-
       const attemptDetails: TaskAttemptSummary = {
         taskId: nextTask.taskId,
         title: nextTask.title,
@@ -310,6 +319,14 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       attempts.push(attemptDetails);
       await appendTaskResult(runtime.taskResultPath, nextTask, outcome);
 
+      if (outcome.done) {
+        todoMarkdown = markTaskDone(todoMarkdown, nextTask.taskId);
+        latestTodoMarkdown = todoMarkdown;
+        await writeFile(runtime.todoPath, todoMarkdown, "utf8");
+      }
+      activeTask = undefined;
+      activeAttempt = undefined;
+
       let taskCommitHash: string | undefined;
       let taskCommitError: string | undefined;
       let taskCommitSkipped: string | undefined;
@@ -360,12 +377,13 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       }
     }
 
-    if (runtime.abortSignal?.aborted && !failure) {
-      failure = "Pi Long Task run aborted.";
-    }
-
     const finalTodoMarkdown = await readFile(runtime.todoPath, "utf8");
     const finalTasks = parseTasks(finalTodoMarkdown);
+    latestTodoMarkdown = finalTodoMarkdown;
+    latestTasks = finalTasks;
+    if (runtime.abortSignal?.aborted && !failure && finalTasks.some((task) => !task.done)) {
+      failure = "Pi Long Task run aborted.";
+    }
     const completedTasks = finalTasks.filter((task) => task.done).length;
     const remainingTasks = remainingTaskSummaries(finalTasks, attempts);
     const blockedTasks = remainingTasks.filter((task) => task.status === "blocked").length;
@@ -427,12 +445,41 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       ? `${message} See ${runtime.taskResultPath} for planner diagnostics.`
       : message;
     const summary = `Pi Long Task failed: ${resultError}`;
+    const failureNote =
+      planningComplete && activeTask
+        ? `TODO ${activeTask.taskId} — ${activeTask.title} (attempt ${activeAttempt ?? "unknown"}) failed: ${message}`
+        : message;
     try {
-      await appendFailureNote(runtime.taskResultPath, message, !planningComplete ? runtime.plannerDiagnostics : []);
+      await appendFailureNote(runtime.taskResultPath, failureNote, !planningComplete ? runtime.plannerDiagnostics : []);
     } catch {
       // Best effort only; the original error is returned below.
     }
 
+    if (planningComplete && activeTask && activeAttempt !== undefined) {
+      attempts.push({
+        taskId: activeTask.taskId,
+        title: activeTask.title,
+        attempt: activeAttempt,
+        reportedStatus: "failed",
+        done: false,
+        error: message,
+      });
+    }
+    if (planningComplete) {
+      try {
+        latestTodoMarkdown = await readFile(runtime.todoPath, "utf8");
+        latestTasks = parseTasks(latestTodoMarkdown);
+      } catch {
+        // Retain the last valid in-memory task snapshot.
+      }
+    }
+    const completedTasks = latestTasks.filter((task) => task.done).length;
+    const remainingTasks = remainingTaskSummaries(latestTasks, attempts);
+    const blockedTasks = remainingTasks.filter((task) => task.status === "blocked").length;
+    const failedTasks = remainingTasks.filter(
+      (task) => task.status !== "blocked" && task.status !== "not_started",
+    ).length;
+    const taskProgress = buildCompletionTaskProgressModel(latestTasks, attempts, "failed");
     const result: CoordinatorResult = {
       status: "failed",
       summary,
@@ -442,16 +489,16 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       todoPath: runtime.todoPath,
       resultPath: runtime.taskResultPath,
       taskResultPath: runtime.taskResultPath,
-      totalTasks: 0,
-      completedTasks: 0,
-      failedTasks: 0,
-      blockedTasks: 0,
+      totalTasks: latestTasks.length,
+      completedTasks,
+      failedTasks,
+      blockedTasks,
       attemptedTasks: attempts.length,
-      remainingTasks: [],
+      remainingTasks,
       outcomes,
       commits,
       attempts,
-      taskProgress: buildTaskProgressModel({ tasks: [], attempts }),
+      taskProgress,
       workerCostTotal: runtime.workerCostState.total,
       commit: options.commit,
       goal: runtime.goal,
@@ -461,7 +508,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
     emitProgress(runtime, "Pi Long Task failed.", {
       phase: "complete",
       status: "failed",
-      taskProgress: buildTaskProgressModel({ tasks: [], attempts }),
+      totalTasks: latestTasks.length,
+      taskProgress,
     });
     return result;
   }

package/src/goal_loop.ts

@@ -68,6 +68,7 @@ export interface GeneratedTodoState {
   generatorRunDir?: string;
   generatorResultPath?: string;
   generatorTaskResultPath?: string;
+  generatorWorkerCostTotal?: number;
 }
 
 export interface GoalWorkerResultState {
@@ -401,6 +402,35 @@ export function recordReviewerResult(
   });
 }
 
+export function failGoalLoop(
+  state: GoalLoopState,
+  reason: string,
+  options: { now?: Date; status?: "failed" | "partial" } = {},
+): GoalLoopState {
+  if (isTerminalGoalLoopStatus(state.status)) {
+    return state;
+  }
+  const timestamp = (options.now ?? new Date()).toISOString();
+  const status = options.status ?? "failed";
+  const phase: GoalLoopPhase = status === "failed" ? "failed" : "complete";
+  const completion: GoalCompletionState = { status, reason, completedAt: timestamp };
+  const iterations = state.iterations.map((iteration) =>
+    iteration.iteration === state.currentIteration && !isTerminalIterationStatus(iteration.status)
+      ? { ...iteration, status: "failed" as const, updatedAt: timestamp, completion }
+      : iteration,
+  );
+  return withTrace(
+    { ...state, status, phase, completion, iterations, updatedAt: timestamp },
+    {
+      timestamp,
+      phase,
+      event: status === "partial" ? "timeout" : "failed",
+      message: reason,
+      iteration: state.currentIteration || undefined,
+    },
+  );
+}
+
 export function cancelGoalLoop(
   state: GoalLoopState,
   reason = "Goal loop cancellation requested.",