pi-long-task 0.1.2 → 0.2.0

package/README.md

@@ -6,19 +6,22 @@ It is useful when you want Pi to handle a multi-step change without losing track
 
 ## What you get
 
-When you ask Pi to use `pi_long_task`, it will:
+When you ask Pi to run a long task, it will:
 
-1. Create or clean up a TODO plan from your request.
-2. Work through each unfinished TODO task in order.
-3. Record progress and final results under `tmp/pi-long-task/<run-id>/`.
-4. Return a summary with completed, failed, blocked, and remaining task counts.
-5. Optionally commit completed work after each task.
+1. Recognize natural-language requests like "run a long task with commits" and route them to `pi_long_task`.
+2. Create or clean up a TODO plan from your request.
+3. Work through each unfinished TODO task in order.
+4. Show the current task and inferred subtask progress while it runs.
+5. Record progress and final results under `tmp/pi-long-task/<run-id>/`.
+6. Return a summary with completed, failed, blocked, and remaining task counts.
+7. Optionally commit completed work after each task.
 
 A finished run gives you:
 
 - a concise status summary in Pi
 - a generated `TODO.md`
 - a generated `TASK_RESULT.md`
+- live progress for the active task and its `**Status:**` checkbox subtasks
 - commit hashes when commits were enabled and created
 - any remaining or blocked tasks clearly listed
 
@@ -42,10 +45,34 @@ Or install the local checkout so Pi can load it normally:
 pi install /path/to/pi-long-task
 ```
 
-After installing, start `pi` in your target project and ask it to use the `pi_long_task` tool.
+After installing, start `pi` in your target project and ask it to run a long task.
+
+To update an existing npm install:
+
+```bash
+pi update npm:pi-long-task
+```
+
+Or update all installed Pi extension packages:
+
+```bash
+pi update --extensions
+```
 
 ## Usage
 
+Use natural language; you do not need to mention `pi_long_task` explicitly:
+
+```text
+Run a long task without commits to add tests for the parser and fix any failures.
+```
+
+```text
+Run a long task with commits to implement the TODOs in @TODO.md.
+```
+
+You can also call the tool explicitly.
+
 Run without commits:
 
 ```text
@@ -78,8 +105,24 @@ The tool has two inputs:
 - `inputText` is the request or TODO markdown to work on.
 - `commit` controls whether Pi Long Task may create git commits.
 
+For natural-language requests, Pi Long Task routes phrases like "run a long task with commits" to the tool with commits enabled. If you ask for a long task without mentioning commits, commits stay disabled.
+
+Natural-language routing intentionally avoids informational questions, such as "How do I run a long task with commits?", and explicit tool calls are left unchanged.
+
 No other public options are required.
 
+## Progress display
+
+While a task is running, Pi Long Task shows the active TODO and subtasks parsed from that task's `**Status:**` checkbox list.
+
+Status markers are:
+
+- `○` not started
+- green `●` done
+- orange `●` inferred as in progress
+
+Because workers currently report structured results at the end of a task, in-progress subtask state is inferred: the first unchecked status item is shown as in progress while the task runs.
+
 ## Commits and files
 
 When `commit` is `false`, Pi Long Task never creates commits.
@@ -92,6 +135,8 @@ When `commit` is `true`, it may commit eligible task changes after a task report
 
 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 — ...`.
+
 ## Validate the install
 
 Run the local checks:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-long-task",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Pi extension for breaking down and running long coding tasks safely.",
   "keywords": [

package/src/coordinator.ts

@@ -11,13 +11,14 @@ import type {
 import { commitAfterSession, gitDirtyPaths, shouldCommitOutcome, type CommitAfterSessionResult } from "./git.ts";
 import { formatCoordinatorResultMessage } from "./render.ts";
 import { extractResultSummary } from "./result_writer.ts";
+import { buildTaskProgressModel, type TaskProgressModel, type TaskProgressStatus } from "./task_progress.ts";
 import {
   buildTodoCreationPrompt,
   extractTodoMarkdown,
   todoMarkdownFromString,
   validateTodoMarkdown,
 } from "./todo_generator.ts";
-import { incompleteTasks, markTaskDone, parseTasks, todoGlobalInstructions, type Task } from "./todo_parser.ts";
+import { markTaskDone, parseTasks, todoGlobalInstructions, type Task } from "./todo_parser.ts";
 import {
   createIsolatedWorkerSession,
   lastAssistantTextFromMessages,
@@ -49,7 +50,7 @@ export type CoordinatorProgressPhase =
   | "task_failed"
   | "complete";
 
-export type CoordinatorProgressItemStatus = "empty" | "in_progress" | "done";
+export type CoordinatorProgressItemStatus = "empty" | "in_progress" | "done" | "failed" | "blocked";
 
 export interface CoordinatorProgressTask {
   taskId: string;
@@ -81,6 +82,7 @@ export interface CoordinatorProgressUpdate {
   totalTasks?: number;
   currentTask?: CoordinatorProgressTask;
   subtasks?: CoordinatorProgressSubtask[];
+  taskProgress?: TaskProgressModel;
 }
 
 export type CoordinatorProgressHandler = (update: CoordinatorProgressUpdate) => void;
@@ -142,6 +144,7 @@ export interface CoordinatorResult {
   outcomes: SessionOutcome[];
   commits: CoordinatorCommitSummary[];
   attempts: TaskAttemptSummary[];
+  taskProgress: TaskProgressModel;
   commit: boolean;
   error?: string;
 }
@@ -184,13 +187,15 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
     emitProgress(runtime, `Created TODO plan with ${initialTasks.length} task(s).`, {
       phase: "planned",
       totalTasks: initialTasks.length,
+      taskProgress: buildTaskProgressModel({ tasks: initialTasks }),
     });
 
     const previousAttempts = new Map<string, string[]>();
     let failure: string | undefined;
 
     while (!runtime.abortSignal?.aborted) {
-      const nextTask = incompleteTasks(todoMarkdown)[0];
+      const tasksBeforeAttempt = parseTasks(todoMarkdown);
+      const nextTask = tasksBeforeAttempt.find((task) => !task.done);
       if (!nextTask) {
         break;
       }
@@ -205,6 +210,11 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
           title: nextTask.title,
           attempt,
           ...currentTaskProgress(nextTask, "in_progress"),
+          taskProgress: buildTaskProgressModel({
+            tasks: tasksBeforeAttempt,
+            attempts,
+            currentTaskId: nextTask.taskId,
+          }),
         },
       );
       const preExistingDirtyPaths = options.commit
@@ -224,7 +234,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         abortSignal: runtime.abortSignal,
         sessionFactory: runtime.workerSessionFactory,
         now: runtime.now,
-        onEvent: (event) => emitWorkerEventProgress(runtime, nextTask, attempt, event),
+        onEvent: (event) => emitWorkerEventProgress(runtime, tasksBeforeAttempt, nextTask, attempts, attempt, event),
       });
       outcomes.push(outcome);
 
@@ -270,7 +280,16 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         await appendCommitNote(runtime.taskResultPath, commitResult);
       }
 
-      emitTaskOutcomeProgress(runtime, nextTask, outcome, taskCommitHash, taskCommitError, taskCommitSkipped);
+      emitTaskOutcomeProgress(
+        runtime,
+        parseTasks(todoMarkdown),
+        nextTask,
+        attempts,
+        outcome,
+        taskCommitHash,
+        taskCommitError,
+        taskCommitSkipped,
+      );
 
       const attemptSummary = resultTextForPreviousAttempt(outcome);
       previousAttempts.set(nextTask.taskId, [...(previousAttempts.get(nextTask.taskId) ?? []), attemptSummary]);
@@ -304,6 +323,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       blockedTasks,
       failedTasks,
     });
+    const taskProgress = buildCompletionTaskProgressModel(finalTasks, attempts, status);
     const summary = failure
       ? `Pi Long Task ${status}: ${failure}`
       : `Pi Long Task completed ${completedTasks}/${finalTasks.length} task(s).`;
@@ -325,6 +345,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       outcomes,
       commits,
       attempts,
+      taskProgress,
       commit: options.commit,
       error: failure,
     };
@@ -333,6 +354,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       phase: "complete",
       status,
       totalTasks: finalTasks.length,
+      taskProgress,
     });
     return result;
   } catch (error) {
@@ -362,11 +384,16 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       outcomes,
       commits,
       attempts,
+      taskProgress: buildTaskProgressModel({ tasks: [], attempts }),
       commit: options.commit,
       error: message,
     };
     result.message = formatCoordinatorResultMessage(result);
-    emitProgress(runtime, "Pi Long Task failed.", { phase: "complete", status: "failed" });
+    emitProgress(runtime, "Pi Long Task failed.", {
+      phase: "complete",
+      status: "failed",
+      taskProgress: buildTaskProgressModel({ tasks: [], attempts }),
+    });
     return result;
   }
 }
@@ -475,14 +502,14 @@ function subtaskProgress(
   task: Pick<Task, "statusItems">,
   taskStatus: CoordinatorProgressItemStatus,
 ): CoordinatorProgressSubtask[] {
-  let markedInProgress = false;
+  let markedActive = false;
   return task.statusItems.map((item) => {
     if (item.done || taskStatus === "done") {
       return { text: item.text, status: "done" };
     }
-    if (taskStatus === "in_progress" && !markedInProgress) {
-      markedInProgress = true;
-      return { text: item.text, status: "in_progress" };
+    if ((taskStatus === "in_progress" || taskStatus === "failed" || taskStatus === "blocked") && !markedActive) {
+      markedActive = true;
+      return { text: item.text, status: taskStatus };
     }
     return { text: item.text, status: "empty" };
   });
@@ -490,7 +517,9 @@ function subtaskProgress(
 
 function emitWorkerEventProgress(
   runtime: RuntimeOptions,
+  tasks: readonly Task[],
   task: Pick<Task, "taskId" | "title" | "statusItems">,
+  attempts: readonly TaskAttemptSummary[],
   attempt: number,
   event: { type: string; toolName?: string; isError?: boolean },
 ): void {
@@ -508,6 +537,7 @@ function emitWorkerEventProgress(
     workerEventType: event.type,
     isError: event.isError,
     ...currentTaskProgress(task, "in_progress"),
+    taskProgress: buildTaskProgressModel({ tasks, attempts, currentTaskId: task.taskId }),
   };
   if (event.isError) {
     update.status = "failed";
@@ -517,7 +547,9 @@ function emitWorkerEventProgress(
 
 function emitTaskOutcomeProgress(
   runtime: RuntimeOptions,
+  tasks: readonly Task[],
   task: Pick<Task, "taskId" | "title" | "statusItems">,
+  attempts: readonly TaskAttemptSummary[],
   outcome: SessionOutcome,
   commitHash: string | undefined,
   commitError: string | undefined,
@@ -542,7 +574,13 @@ function emitTaskOutcomeProgress(
     title: task.title,
     attempt: outcome.attempt,
     status: outcome.reportedStatus,
-    ...currentTaskProgress(task, outcome.done ? "done" : "in_progress"),
+    ...currentTaskProgress(task, outcomeProgressItemStatus(outcome)),
+    taskProgress: buildTaskProgressModel({
+      tasks,
+      attempts,
+      currentTaskId: task.taskId,
+      currentTaskStatus: outcomeTaskProgressStatus(outcome),
+    }),
   };
   if (commitHash) {
     update.commitHash = commitHash;
@@ -556,6 +594,50 @@ function emitTaskOutcomeProgress(
   emitProgress(runtime, `TODO ${task.taskId} ${statusText}${commitText}.`, update);
 }
 
+function buildCompletionTaskProgressModel(
+  tasks: readonly Task[],
+  attempts: readonly TaskAttemptSummary[],
+  status: CoordinatorStatus,
+): TaskProgressModel {
+  if (status === "done") {
+    return buildTaskProgressModel({ tasks, attempts });
+  }
+
+  const lastIncompleteAttempt = [...attempts].reverse().find((attempt) => !attempt.done);
+  if (!lastIncompleteAttempt) {
+    return buildTaskProgressModel({ tasks, attempts });
+  }
+
+  return buildTaskProgressModel({
+    tasks,
+    attempts,
+    currentTaskId: lastIncompleteAttempt.taskId,
+    currentTaskStatus: outcomeTaskProgressStatus(lastIncompleteAttempt),
+  });
+}
+
+function outcomeTaskProgressStatus(outcome: Pick<SessionOutcome, "done" | "reportedStatus">): TaskProgressStatus {
+  if (outcome.done) {
+    return "completed";
+  }
+  if (outcome.reportedStatus === "blocked") {
+    return "blocked";
+  }
+  return "failed";
+}
+
+function outcomeProgressItemStatus(
+  outcome: Pick<SessionOutcome, "done" | "reportedStatus">,
+): CoordinatorProgressItemStatus {
+  if (outcome.done) {
+    return "done";
+  }
+  if (outcome.reportedStatus === "blocked") {
+    return "blocked";
+  }
+  return "failed";
+}
+
 function initialTaskResultMarkdown(runId: string): string {
   return `# Pi Long Task TASK_RESULT\n\nRun: ${runId}\n`;
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import { runCoordinator, type CoordinatorProgressUpdate, type CoordinatorResult } from "./coordinator.ts";
+import { longTaskInputTransform } from "./input_router.ts";
 import { renderLongTaskToolCall, renderLongTaskToolResult } from "./render.ts";
 import { PiLongTaskParams } from "./types.ts";
 
@@ -17,15 +18,30 @@ function toolDetails(result: CoordinatorResult) {
     failedTasks: result.failedTasks,
     blockedTasks: result.blockedTasks,
     remainingTasks: result.remainingTasks,
+    taskProgress: result.taskProgress,
     summary: result.summary,
   };
 }
 
 export default function registerPiLongTaskExtension(pi: ExtensionAPI) {
+  pi.on("input", (event) => {
+    if (event.source === "extension") {
+      return { action: "continue" as const };
+    }
+
+    const transformed = longTaskInputTransform(event.text);
+    if (!transformed) {
+      return { action: "continue" as const };
+    }
+
+    return { action: "transform" as const, text: transformed };
+  });
+
   pi.registerTool({
     name: "pi_long_task",
     label: "Pi Long Task",
-    description: "Break down and run long coding tasks from a request or TODO plan.",
+    description:
+      "Run long or multi-step coding tasks from a request or TODO plan. Use this when the user asks to run/start/handle a long task; set commit true only when they ask for commits or committing as work progresses.",
     parameters: PiLongTaskParams,
     renderCall: renderLongTaskToolCall,
     renderResult: renderLongTaskToolResult,

package/src/input_router.ts

@@ -0,0 +1,57 @@
+const LONG_TASK_RE = /\b(?:long[-\s]?task|longtask|large[-\s]?task|big[-\s]?task|multi[-\s]?step(?:\s+task)?)\b/i;
+const DIRECT_LONG_TASK_REQUEST_RE =
+  /\b(?:run|start|do|handle|execute|launch|kick\s+off|use)\s+(?:a\s+|the\s+)?(?:long[-\s]?task|longtask|large[-\s]?task|big[-\s]?task|multi[-\s]?step(?:\s+task)?)\b/i;
+const WANT_LONG_TASK_RE =
+  /\b(?:please|can\s+you|could\s+you|i\s+want|i\s+need|i'd\s+like|i\s+would\s+like|let's|lets)\b[\s\S]*\b(?:long[-\s]?task|longtask|large[-\s]?task|big[-\s]?task|multi[-\s]?step(?:\s+task)?)\b/i;
+const NEGATED_LONG_TASK_RE =
+  /\b(?:do\s+not|don't|dont|never)\s+(?:run|start|do|handle|execute|launch|kick\s+off|use)\s+(?:a\s+|the\s+)?(?:long[-\s]?task|longtask|large[-\s]?task|big[-\s]?task|multi[-\s]?step(?:\s+task)?)\b/i;
+const INFORMATION_QUESTION_RE = /^\s*(?:how|what|why|when|where|who)\b/i;
+const EXPLICIT_TOOL_RE = /\bpi_long_task\b/i;
+
+const COMMIT_FALSE_RE =
+  /\b(?:without|no|disable|disabled|off)\s+commits?\b|\bcommits?\s*(?:false|off|disabled)\b|\bcommit\s*:\s*(?:false|off|no)\b|\b(?:do\s+not|don't|dont)\s+commit\b/i;
+const COMMIT_TRUE_RE =
+  /\bwith\s+commits?\b|\bcommits?\s*(?:true|on|enabled)\b|\bcommit\s*:\s*(?:true|on|yes)\b|\bcommit(?:ting)?\s+as\s+(?:you|we)\s+go\b|\b(?:make|create|include|allow|enable)\s+commits?\b/i;
+
+export function longTaskInputTransform(text: string): string | undefined {
+  if (!isNaturalLanguageLongTaskRequest(text)) {
+    return undefined;
+  }
+
+  const commit = inferCommitSetting(text) ?? false;
+  return buildLongTaskToolPrompt(text, commit);
+}
+
+export function isNaturalLanguageLongTaskRequest(text: string): boolean {
+  const trimmed = text.trim();
+  if (!trimmed || trimmed.startsWith("/") || EXPLICIT_TOOL_RE.test(trimmed)) {
+    return false;
+  }
+  if (!LONG_TASK_RE.test(trimmed) || INFORMATION_QUESTION_RE.test(trimmed) || NEGATED_LONG_TASK_RE.test(trimmed)) {
+    return false;
+  }
+  return DIRECT_LONG_TASK_REQUEST_RE.test(trimmed) || WANT_LONG_TASK_RE.test(trimmed);
+}
+
+export function inferCommitSetting(text: string): boolean | undefined {
+  if (COMMIT_FALSE_RE.test(text)) {
+    return false;
+  }
+  if (COMMIT_TRUE_RE.test(text)) {
+    return true;
+  }
+  return undefined;
+}
+
+function buildLongTaskToolPrompt(originalText: string, commit: boolean): string {
+  return [
+    "Use the pi_long_task tool for this request.",
+    `Set commit to ${commit ? "true" : "false"}.`,
+    "Set inputText to the user's original request below. Do not perform the work directly outside pi_long_task.",
+    "",
+    "Original request:",
+    "```text",
+    originalText.trim(),
+    "```",
+  ].join("\n");
+}

package/src/render.ts

@@ -1,6 +1,7 @@
 import type { AgentToolResult, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { Text, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
 
+import type { TaskProgressModel, TaskProgressStatus, TaskProgressTask } from "./task_progress.ts";
 import type { CoordinatorCommitSummary, CoordinatorRemainingTask, CoordinatorStatus } from "./types.ts";
 
 export interface CoordinatorResultForRendering {
@@ -15,6 +16,7 @@ export interface CoordinatorResultForRendering {
   taskResultPath?: string;
   commits?: CoordinatorCommitSummary[];
   remainingTasks?: CoordinatorRemainingTask[];
+  taskProgress?: TaskProgressModel;
   error?: string;
 }
 
@@ -22,7 +24,7 @@ export interface CoordinatorToolRenderDetails extends CoordinatorResultForRender
   runId?: string;
 }
 
-type ProgressItemStatus = "empty" | "in_progress" | "done";
+type ProgressItemStatus = "empty" | "in_progress" | "done" | "failed" | "blocked";
 
 interface ProgressTaskRenderDetails {
   taskId: string;
@@ -35,6 +37,70 @@ interface ProgressSubtaskRenderDetails {
   status: ProgressItemStatus;
 }
 
+const SIDEBAR_MIN_SIDE_BY_SIDE_WIDTH = 84;
+const SIDEBAR_MIN_WIDTH = 26;
+const SIDEBAR_MAX_WIDTH = 40;
+const SIDEBAR_GAP = 2;
+
+class LongTaskSidebarShell implements Component {
+  private readonly mainText: string;
+  private readonly taskProgress: TaskProgressModel;
+  private readonly theme: Theme;
+
+  constructor(mainText: string, taskProgress: TaskProgressModel, theme: Theme) {
+    this.mainText = mainText;
+    this.taskProgress = taskProgress;
+    this.theme = theme;
+  }
+
+  render(width: number): string[] {
+    if (width < SIDEBAR_MIN_SIDE_BY_SIDE_WIDTH) {
+      return this.renderStacked(width);
+    }
+
+    const sidebarWidth = clamp(Math.floor(width * 0.32), SIDEBAR_MIN_WIDTH, SIDEBAR_MAX_WIDTH);
+    const mainWidth = width - sidebarWidth - SIDEBAR_GAP;
+    if (mainWidth < 40) {
+      return this.renderStacked(width);
+    }
+
+    const mainLines = renderWrappedLines(this.mainText, mainWidth);
+    const sidebarLines = this.renderSidebar(sidebarWidth);
+    const height = Math.max(mainLines.length, sidebarLines.length);
+    const lines: string[] = [];
+    for (let idx = 0; idx < height; idx += 1) {
+      const main = padLine(mainLines[idx] ?? "", mainWidth);
+      const sidebar = sidebarLines[idx] ?? "";
+      lines.push(truncateToWidth(`${main}${" ".repeat(SIDEBAR_GAP)}${sidebar}`, width));
+    }
+    return lines;
+  }
+
+  invalidate(): void {
+    // Rendering is computed from current state on each pass.
+  }
+
+  private renderStacked(width: number): string[] {
+    const mainLines = renderWrappedLines(this.mainText, width);
+    const sidebarLines = this.renderSidebar(width);
+    return [...mainLines, ...sidebarLines].map((line) => truncateToWidth(line, width));
+  }
+
+  private renderSidebar(width: number): string[] {
+    if (width < 8) {
+      return [];
+    }
+
+    const innerWidth = Math.max(0, width - 2);
+    const rows = sidebarRows(this.taskProgress, this.theme);
+    return [
+      sidebarBorder("Long Task", width, this.theme),
+      ...rows.map((row) => sidebarRow(row, innerWidth, this.theme)),
+      this.theme.fg("borderMuted", `└${"─".repeat(innerWidth)}┘`),
+    ];
+  }
+}
+
 export function formatCoordinatorResultMessage(result: CoordinatorResultForRendering): string {
   const resultPath = result.resultPath ?? result.taskResultPath ?? "unknown";
   const remaining = result.remainingTasks ?? [];
@@ -84,10 +150,12 @@ export function renderLongTaskToolResult(
   result: AgentToolResult<unknown>,
   options: ToolRenderResultOptions,
   theme: Theme,
-): Text {
+): Component {
   const details = recordOrUndefined(result.details);
   if (options.isPartial) {
-    return new Text(renderLongTaskProgress(details, contentText(result), theme), 0, 0);
+    const taskProgress = taskProgressModel(details?.taskProgress);
+    const main = renderLongTaskProgress(details, contentText(result), theme);
+    return taskProgress ? new LongTaskSidebarShell(main, taskProgress, theme) : new Text(main, 0, 0);
   }
 
   const finalDetails = longTaskDetails(details);
@@ -95,7 +163,10 @@ export function renderLongTaskToolResult(
     return new Text(contentText(result), 0, 0);
   }
 
-  return new Text(renderLongTaskSummary(finalDetails, options.expanded, theme), 0, 0);
+  const main = renderLongTaskSummary(finalDetails, options.expanded, theme);
+  return finalDetails.taskProgress
+    ? new LongTaskSidebarShell(main, finalDetails.taskProgress, theme)
+    : new Text(main, 0, 0);
 }
 
 function renderLongTaskProgress(details: Record<string, unknown> | undefined, fallback: string, theme: Theme): string {
@@ -173,6 +244,171 @@ function renderLongTaskSummary(details: CoordinatorToolRenderDetails, expanded:
   return lines.join("\n");
 }
 
+function renderWrappedLines(text: string, width: number): string[] {
+  return new Text(text, 0, 0).render(Math.max(1, width)).map((line) => truncateToWidth(line, Math.max(1, width)));
+}
+
+function padLine(line: string, width: number): string {
+  return truncateToWidth(line, width, "…", true);
+}
+
+function sidebarRows(taskProgress: TaskProgressModel, theme: Theme): string[] {
+  const summary = normalizedTaskProgressSummary(taskProgress);
+  const rows = [theme.fg("toolTitle", theme.bold("Task sidebar")), theme.fg("dim", "Centered timeline")];
+  if (summary.totalTasks === 0) {
+    rows.push("", theme.fg("muted", "Waiting for TODO plan..."));
+    return rows;
+  }
+
+  rows.push("", progressBarLine(summary.completedTasks, summary.totalTasks, summary.completedPercent, theme));
+  rows.push(progressCountsLine(summary, theme));
+
+  const currentIndex = focusedTaskIndex(taskProgress);
+  if (currentIndex >= 0) {
+    rows.push(theme.fg("warning", `Focus: TODO ${taskProgress.tasks[currentIndex]?.taskId ?? "?"}`));
+  } else {
+    rows.push(theme.fg("success", "No active task"));
+  }
+
+  rows.push("", theme.fg("muted", "Timeline"));
+  for (const [index, task] of taskProgress.tasks.entries()) {
+    if (currentIndex >= 0 && index === currentIndex && index > 0) {
+      rows.push(theme.fg("dim", "──── current ────"));
+    }
+    rows.push(renderSidebarTaskRow(task, theme));
+    if (currentIndex >= 0 && index === currentIndex && index < taskProgress.tasks.length - 1) {
+      rows.push(theme.fg("dim", "──── future ─────"));
+    }
+  }
+
+  return rows;
+}
+
+interface NormalizedTaskProgressSummary {
+  totalTasks: number;
+  completedTasks: number;
+  failedTasks: number;
+  blockedTasks: number;
+  pendingTasks: number;
+  currentTasks: number;
+  completedPercent: number;
+}
+
+function normalizedTaskProgressSummary(taskProgress: TaskProgressModel): NormalizedTaskProgressSummary {
+  const totalTasks = taskProgress.summary?.totalTasks ?? taskProgress.tasks.length;
+  const completedTasks = taskProgress.summary?.completedTasks ?? countTasksByStatus(taskProgress.tasks, "completed");
+  const failedTasks = taskProgress.summary?.failedTasks ?? countTasksByStatus(taskProgress.tasks, "failed");
+  const blockedTasks = taskProgress.summary?.blockedTasks ?? countTasksByStatus(taskProgress.tasks, "blocked");
+  const pendingTasks = taskProgress.summary?.pendingTasks ?? countTasksByStatus(taskProgress.tasks, "pending");
+  const currentTasks = taskProgress.summary?.currentTasks ?? countTasksByStatus(taskProgress.tasks, "current");
+  const completedPercent =
+    taskProgress.summary?.completedPercent ??
+    (totalTasks === 0 ? 100 : Math.round((completedTasks / totalTasks) * 100));
+
+  return {
+    totalTasks,
+    completedTasks,
+    failedTasks,
+    blockedTasks,
+    pendingTasks,
+    currentTasks,
+    completedPercent,
+  };
+}
+
+function countTasksByStatus(tasks: readonly TaskProgressTask[], status: TaskProgressStatus): number {
+  return tasks.filter((task) => task.status === status).length;
+}
+
+function progressBarLine(completedTasks: number, totalTasks: number, percent: number, theme: Theme): string {
+  const width = 10;
+  const filled = clamp(totalTasks === 0 ? width : Math.round((completedTasks / totalTasks) * width), 0, width);
+  const empty = Math.max(0, width - filled);
+  return `${theme.fg("muted", "Progress")} [${theme.fg("success", "#".repeat(filled))}${theme.fg(
+    "dim",
+    "-".repeat(empty),
+  )}] ${completedTasks}/${totalTasks} ${percent}%`;
+}
+
+function progressCountsLine(summary: NormalizedTaskProgressSummary, theme: Theme): string {
+  const parts = [
+    theme.fg("success", `✓ ${summary.completedTasks}`),
+    summary.currentTasks ? theme.fg("warning", `▶ ${summary.currentTasks}`) : undefined,
+    summary.pendingTasks ? theme.fg("dim", `○ ${summary.pendingTasks}`) : undefined,
+    summary.failedTasks ? theme.fg("error", `✗ ${summary.failedTasks}`) : undefined,
+    summary.blockedTasks ? theme.fg("warning", `! ${summary.blockedTasks}`) : undefined,
+  ].filter(Boolean);
+  return parts.join(" · ");
+}
+
+function focusedTaskIndex(taskProgress: TaskProgressModel): number {
+  if (typeof taskProgress.currentIndex === "number" && taskProgress.currentIndex >= 0) {
+    return taskProgress.currentIndex;
+  }
+
+  const currentIndex = taskProgress.tasks.findIndex((task) => task.status === "current" || task.position === "current");
+  if (currentIndex >= 0) {
+    return currentIndex;
+  }
+
+  if (typeof taskProgress.nextIndex === "number" && taskProgress.nextIndex >= 0) {
+    return taskProgress.nextIndex;
+  }
+  return taskProgress.tasks.findIndex((task) => task.status === "pending");
+}
+
+function renderSidebarTaskRow(task: TaskProgressTask, theme: Theme): string {
+  const { icon, color, label } = sidebarTaskStatusDetails(task.status);
+  const attempts =
+    task.attempts > 0 && task.status !== "completed"
+      ? ` · ${task.attempts} attempt${task.attempts === 1 ? "" : "s"}`
+      : "";
+  const text = `${icon} [${label}] TODO ${task.taskId} — ${task.title}${attempts}`;
+  return task.status === "current" ? theme.fg(color, theme.bold(text)) : theme.fg(color, text);
+}
+
+function sidebarTaskStatusDetails(status: TaskProgressStatus): {
+  icon: string;
+  color: "success" | "warning" | "error" | "dim" | "muted";
+  label: string;
+} {
+  switch (status) {
+    case "completed":
+      return { icon: "✓", color: "success", label: "completed" };
+    case "current":
+      return { icon: "▶", color: "warning", label: "current" };
+    case "failed":
+      return { icon: "✗", color: "error", label: "failed" };
+    case "blocked":
+      return { icon: "!", color: "warning", label: "blocked" };
+    case "pending":
+      return { icon: "○", color: "dim", label: "pending" };
+  }
+}
+
+function sidebarBorder(title: string, width: number, theme: Theme): string {
+  const innerWidth = Math.max(0, width - 2);
+  const titleText = truncateToWidth(` ${title} `, innerWidth, "");
+  const remaining = Math.max(0, innerWidth - visibleWidth(titleText));
+  return theme.fg("borderMuted", `┌${titleText}${"─".repeat(remaining)}┐`);
+}
+
+function sidebarRow(row: string, innerWidth: number, theme: Theme): string {
+  return `${theme.fg("borderMuted", "│")}${truncateToWidth(row, innerWidth, "…", true)}${theme.fg("borderMuted", "│")}`;
+}
+
+function taskProgressModel(value: unknown): TaskProgressModel | undefined {
+  const record = recordOrUndefined(value);
+  if (!record || !Array.isArray(record.tasks)) {
+    return undefined;
+  }
+  return value as TaskProgressModel;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
 function progressTaskDetails(value: unknown): ProgressTaskRenderDetails | undefined {
   const record = recordOrUndefined(value);
   const taskId = stringValue(record?.taskId);
@@ -200,18 +436,32 @@ function progressSubtaskDetails(value: unknown): ProgressSubtaskRenderDetails[]
 }
 
 function progressItemStatus(value: unknown): ProgressItemStatus | undefined {
-  return value === "empty" || value === "in_progress" || value === "done" ? value : undefined;
+  return value === "empty" || value === "in_progress" || value === "done" || value === "failed" || value === "blocked"
+    ? value
+    : undefined;
 }
 
 function progressBubble(status: ProgressItemStatus, theme: Theme): string {
-  return status === "empty" ? theme.fg("dim", "○") : theme.fg(progressTextColor(status), "●");
+  switch (status) {
+    case "empty":
+      return theme.fg("dim", "○");
+    case "failed":
+      return theme.fg("error", "✗");
+    case "blocked":
+      return theme.fg("warning", "!");
+    default:
+      return theme.fg(progressTextColor(status), "●");
+  }
 }
 
-function progressTextColor(status: ProgressItemStatus): "success" | "warning" | "dim" {
+function progressTextColor(status: ProgressItemStatus): "success" | "warning" | "dim" | "error" {
   if (status === "done") {
     return "success";
   }
-  if (status === "in_progress") {
+  if (status === "failed") {
+    return "error";
+  }
+  if (status === "in_progress" || status === "blocked") {
     return "warning";
   }
   return "dim";
@@ -252,6 +502,7 @@ function longTaskDetails(details: Record<string, unknown> | undefined): Coordina
     runId: stringValue(details.runId),
     commits: commitSummaries(details.commits),
     remainingTasks: remainingTaskSummaries(details.remainingTasks),
+    taskProgress: taskProgressModel(details.taskProgress),
     error: stringValue(details.error),
   };
 }

package/src/task_progress.ts

@@ -0,0 +1,187 @@
+import type { Task, TaskStatusItem } from "./todo_parser.ts";
+
+export const TASK_PROGRESS_STATUS_VALUES = ["pending", "current", "completed", "failed", "blocked"] as const;
+export type TaskProgressStatus = (typeof TASK_PROGRESS_STATUS_VALUES)[number];
+
+export const TASK_PROGRESS_POSITION_VALUES = ["past", "current", "future"] as const;
+export type TaskProgressPosition = (typeof TASK_PROGRESS_POSITION_VALUES)[number];
+
+export interface TaskProgressAttempt {
+  taskId: string;
+  attempt?: number;
+  reportedStatus?: string;
+  done?: boolean;
+}
+
+export type TaskProgressTaskStatusItem = TaskStatusItem;
+
+export interface TaskProgressTask {
+  taskId: string;
+  title: string;
+  status: TaskProgressStatus;
+  position: TaskProgressPosition;
+  done: boolean;
+  statusItems: TaskProgressTaskStatusItem[];
+  attempts: number;
+  lastReportedStatus?: string;
+}
+
+export interface TaskProgressSummary {
+  totalTasks: number;
+  completedTasks: number;
+  failedTasks: number;
+  blockedTasks: number;
+  pendingTasks: number;
+  currentTasks: number;
+  attemptedTasks: number;
+  completionRatio: number;
+  completedPercent: number;
+}
+
+export interface TaskProgressModel {
+  tasks: TaskProgressTask[];
+  summary: TaskProgressSummary;
+  currentTaskId?: string;
+  currentIndex?: number;
+  currentTask?: TaskProgressTask;
+  nextTaskId?: string;
+  nextIndex?: number;
+  nextTask?: TaskProgressTask;
+}
+
+export interface BuildTaskProgressModelOptions {
+  tasks: readonly Task[];
+  attempts?: readonly TaskProgressAttempt[];
+  currentTaskId?: string;
+  currentTaskStatus?: TaskProgressStatus;
+}
+
+export function buildTaskProgressModel(options: BuildTaskProgressModelOptions): TaskProgressModel {
+  const attempts = options.attempts ?? [];
+  const attemptStats = attemptsByTask(attempts);
+  const activeIndex = activeTaskIndex(options.tasks, options.currentTaskId);
+
+  const progressTasks = options.tasks.map((task, index) => {
+    const stats = attemptStats.get(task.taskId);
+    const isActive = index === activeIndex;
+    const status = taskProgressStatus(task, stats?.lastAttempt, isActive, options.currentTaskStatus);
+
+    const progressTask: TaskProgressTask = {
+      taskId: task.taskId,
+      title: task.title,
+      status,
+      position: taskProgressPosition(index, activeIndex, status),
+      done: status === "completed",
+      statusItems: task.statusItems.map((item) => ({ ...item })),
+      attempts: stats?.attempts ?? 0,
+    };
+    if (stats?.lastAttempt.reportedStatus) {
+      progressTask.lastReportedStatus = stats.lastAttempt.reportedStatus;
+    }
+    return progressTask;
+  });
+
+  const currentIndex = progressTasks.findIndex((task) => task.position === "current");
+  const nextIndex = progressTasks.findIndex((task) => task.status === "pending");
+  const summary = taskProgressSummary(progressTasks, attempts.length);
+
+  const model: TaskProgressModel = {
+    tasks: progressTasks,
+    summary,
+  };
+  if (currentIndex >= 0) {
+    model.currentIndex = currentIndex;
+    model.currentTask = progressTasks[currentIndex];
+    model.currentTaskId = progressTasks[currentIndex].taskId;
+  }
+  if (nextIndex >= 0) {
+    model.nextIndex = nextIndex;
+    model.nextTask = progressTasks[nextIndex];
+    model.nextTaskId = progressTasks[nextIndex].taskId;
+  }
+  return model;
+}
+
+interface TaskAttemptStats {
+  attempts: number;
+  lastAttempt: TaskProgressAttempt;
+}
+
+function attemptsByTask(attempts: readonly TaskProgressAttempt[]): Map<string, TaskAttemptStats> {
+  const stats = new Map<string, TaskAttemptStats>();
+  for (const attempt of attempts) {
+    const existing = stats.get(attempt.taskId);
+    stats.set(attempt.taskId, {
+      attempts: (existing?.attempts ?? 0) + 1,
+      lastAttempt: attempt,
+    });
+  }
+  return stats;
+}
+
+function activeTaskIndex(tasks: readonly Task[], currentTaskId: string | undefined): number {
+  if (!currentTaskId) {
+    return -1;
+  }
+  return tasks.findIndex((task) => task.taskId === currentTaskId);
+}
+
+function taskProgressStatus(
+  task: Task,
+  lastAttempt: TaskProgressAttempt | undefined,
+  isActive: boolean,
+  currentTaskStatus: TaskProgressStatus | undefined,
+): TaskProgressStatus {
+  if (task.done || lastAttempt?.done || (isActive && currentTaskStatus === "completed")) {
+    return "completed";
+  }
+  if (isActive) {
+    if (currentTaskStatus === "failed" || currentTaskStatus === "blocked") {
+      return currentTaskStatus;
+    }
+    return "current";
+  }
+  if (lastAttempt?.reportedStatus === "blocked") {
+    return "blocked";
+  }
+  if (lastAttempt) {
+    return "failed";
+  }
+  return "pending";
+}
+
+function taskProgressPosition(index: number, activeIndex: number, status: TaskProgressStatus): TaskProgressPosition {
+  if (activeIndex >= 0) {
+    if (index < activeIndex) {
+      return "past";
+    }
+    if (index === activeIndex) {
+      return "current";
+    }
+    return "future";
+  }
+
+  return status === "pending" || status === "current" ? "future" : "past";
+}
+
+function taskProgressSummary(tasks: readonly TaskProgressTask[], attemptedTasks: number): TaskProgressSummary {
+  const totalTasks = tasks.length;
+  const completedTasks = tasks.filter((task) => task.status === "completed").length;
+  const failedTasks = tasks.filter((task) => task.status === "failed").length;
+  const blockedTasks = tasks.filter((task) => task.status === "blocked").length;
+  const pendingTasks = tasks.filter((task) => task.status === "pending").length;
+  const currentTasks = tasks.filter((task) => task.status === "current").length;
+  const completionRatio = totalTasks === 0 ? 1 : completedTasks / totalTasks;
+
+  return {
+    totalTasks,
+    completedTasks,
+    failedTasks,
+    blockedTasks,
+    pendingTasks,
+    currentTasks,
+    attemptedTasks,
+    completionRatio,
+    completedPercent: Math.round(completionRatio * 100),
+  };
+}

package/src/types.ts

@@ -1,12 +1,18 @@
 import type { Static } from "typebox";
 import { Type } from "typebox";
 
+import type { TaskProgressModel } from "./task_progress.ts";
 import type { SessionOutcome } from "./worker_session.ts";
 
 export const PiLongTaskParams = Type.Object(
   {
-    inputText: Type.String({ description: "TODO file content or long-task instructions to process." }),
-    commit: Type.Boolean({ description: "Whether Pi Long Task may commit completed worker changes." }),
+    inputText: Type.String({
+      description: "TODO file content or the user's long-task instructions to process.",
+    }),
+    commit: Type.Boolean({
+      description:
+        "Whether Pi Long Task may commit completed worker changes. Use true when the user asks for commits or committing as work progresses; otherwise use false.",
+    }),
   },
   { additionalProperties: false },
 );
@@ -55,6 +61,7 @@ export interface PiLongTaskResult {
     commitError?: string;
     commitSkipped?: string;
   }>;
+  taskProgress: TaskProgressModel;
   commit: boolean;
   error?: string;
 }