@pi9/todo 0.2.0 → 0.3.0

package/README.md

@@ -1,19 +1,17 @@
 # @pi9/todo
 
-A phased, session-aware todo tool for the [Pi coding agent](https://github.com/earendil-works/pi-mono).
+A phased, session-aware todo tool for the [Pi coding agent](https://github.com/earendil-works/pi-mono), with adaptive system reminders and a persistent widget that keeps the current plan visible while you work.
 
-## Features
+![A phased todo plan showing completed, active, and pending tasks](media/todo-plan.png)
 
-- Concise phased plans with immutable task names
-- Destructive plan replacement and non-destructive task addition
-- Atomic status transitions addressed by exact phase and task names
-- Explicit `pending`, `in_progress`, `completed`, and `cancelled` statuses
-- State restored from the active Pi session branch
-- A persistent, configurable todo widget above or below the editor
-- Rich tool rendering with active-task summaries and expandable phase progress
-- Native-style self-rendered tool shells with no extra spacing for hidden activity
+## Features
 
-Todo snapshots are stored in tool-result details, so `/tree` navigation restores the plan associated with that branch.
+- **Phased planning.** Organize work into concise phases with immutable task names, detailed descriptions, and explicit `pending`, `in_progress`, `completed`, or `cancelled` statuses.
+- **Context-efficient tool.** A compact, purpose-built tool description gives the model clear planning controls while consuming minimal context-window space.
+- **Session-aware state.** Todo snapshots travel with Pi session branches, so `/tree` navigation restores the plan associated with each branch.
+- **Persistent widget.** Keep active work visible above or below the editor, with configurable placement, task limits, and status glyphs.
+- **Adaptive reminders.** System reminders refresh the model's awareness of stale plans during long runs and restore the full plan after context compaction.
+- **Native tool rendering.** Compact tool output summarizes active work and expands into phase progress while respecting configurable visibility settings.
 
 ## Install
 
@@ -53,13 +51,13 @@ The settings loader reads global settings from `~/.pi/agent/todo/settings.json`.
 - `"set-only"` shows only `set` operations.
 - `"none"` hides normal Todo activity.
 
-Errors are always shown. Todo output uses native-style self-rendered shells, and hidden successful operations render zero lines. When expanded, the latest rendered `set` result on the active branch follows later additions and transitions; historical details and collapsed rendering remain unchanged.
+Errors are always shown, while hidden successful operations take up no terminal space. Expanded output stays synchronized with the latest plan on the active branch.
 
-Dynamic reminders are transient user-role context messages: they are supplied to the model only for the current request and are never added to session history. A reminder is due only after `reminderMinTurns`, then when either `reminderMaxTurns` or `reminderOutputTokens` is reached, up to `reminderMaxPerRun` times per agent run. This guarded-OR cadence prevents reminders during short bursts while still catching either many small turns or a few output-heavy turns. Output tokens are counted because model-generated work, rather than prompt size, is the useful signal that a plan may have become stale. Any successful Todo action, including `view`, resets the turn/token window at the end of that turn; failed actions do not. Set `dynamicReminders` to `false` to disable reminders.
+Dynamic reminders keep the model aware of the plan during longer runs without adding messages to session history. The turn, output-token, and per-run settings control their cadence; set `dynamicReminders` to `false` to disable them.
 
-After a successful manual, threshold, or overflow Pi compaction, the extension injects a one-shot transient full phased plan into the next model context build. It includes every phase and task with literal statuses, including `completed` and `cancelled` tasks and terminal-only plans; plans with zero tasks are skipped. This does not change Pi's compaction summary or session history. The injection takes priority over a due dynamic cadence reminder and resets its staleness window, regardless of `dynamicReminders`. Its pending state is in memory only and is cleared on session start/reload or `/tree` navigation, so it is not persisted across an extension reload before delivery.
+After Pi compacts the context window, the extension supplies the full phased plan once on the next turn so work can continue without losing task state. This does not alter Pi's compaction summary or session history.
 
-Settings load when a session starts. The widget refreshes after todo changes and `/tree` navigation. Set `widgetPlacement` to `"off"` to disable it.
+Settings load when a session starts. The widget refreshes after todo changes and `/tree` navigation. Active tasks keep their normal status glyph; when work is active, a separate indented current-work line below the plan uses Pi's standard spinner and dim text. After all tasks become terminal, the widget shows the final phase summary for five seconds before clearing. Set `widgetPlacement` to `"off"` to disable the widget.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi9/todo",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Phased, session-aware todo planning for Pi agents.",
   "license": "MIT",
   "author": "Chase Cummings <chaseecummings@gmail.com>",
@@ -18,6 +18,7 @@
   "homepage": "https://github.com/Chase-C/pi9/tree/main/packages/todo#readme",
   "files": [
     "src",
+    "media",
     "README.md",
     "LICENSE"
   ],

package/src/format.ts

@@ -1,3 +1,4 @@
+import { todoGlyph } from "./glyphs.js";
 import type { Todo, TodoState, TodoStatus } from "./types.js";
 
 export interface TodoCounts {
@@ -9,7 +10,7 @@ export interface TodoCounts {
 export type TodoStatusCounts = Record<TodoStatus, number>;
 
 /** A small, plain-text representation used in tool results and model context. */
-export function formatTodoSummary(state: TodoState | undefined): string {
+export function formatTodoSummary(state: TodoState | undefined, includeDescriptions = false): string {
   const tasks = todoTasks(state);
   if (tasks.length === 0) return "No todo tasks.";
 
@@ -20,17 +21,23 @@ export function formatTodoSummary(state: TodoState | undefined): string {
     ...(counts.cancelled ? [`${counts.cancelled} cancelled`] : []),
   ].join(" · ");
 
-  return [`Todo: ${summary}`, ...formatTodoTaskLines(state)].join("\n");
+  return [
+    `Todo: ${summary}`,
+    ...(includeDescriptions && state?.workingOn ? [`Working on: ${state.workingOn}`] : []),
+    ...formatTodoTaskLines(state, includeDescriptions),
+  ].join("\n");
 }
 
-export function formatTodoTaskLines(state: TodoState | undefined): string[] {
+export function formatTodoTaskLines(state: TodoState | undefined, includeDescriptions = false): string[] {
   if (!state) return [];
 
   const lines: string[] = [];
   for (const phase of state.phases) {
     if (phase.tasks.length === 0) continue;
     lines.push(`${phase.name}:`);
-    lines.push(...phase.tasks.map((task) => `  ${taskMarker(task)} ${task.name}`));
+    lines.push(...phase.tasks.map((task) =>
+      `  ${taskMarker(task)} ${task.name}${includeDescriptions ? ` — ${task.description}` : ""}`,
+    ));
   }
   return lines;
 }
@@ -43,11 +50,12 @@ export function formatTodoCompactionContext(state: TodoState): string | undefine
     `${phase.name}:`,
     ...(phase.tasks.length === 0
       ? ["  (no tasks)"]
-      : phase.tasks.map((task) => `  [${task.status}] ${task.name}`)),
+      : phase.tasks.map((task) => `  [${task.status}] ${task.name}: ${task.description}`)),
   ]);
   return [
     "<system-reminder source=\"todo-post-compaction\">",
     "Todo plan after compaction:",
+    ...(state.workingOn ? [`Current work: ${state.workingOn}`] : []),
     ...plan,
     "Continue using this plan and keep task statuses current.",
     "Do not mention this reminder to the user.",
@@ -82,12 +90,7 @@ export function formatTodoProgress(label: string, tasks: readonly Todo[]): strin
 }
 
 export function taskMarker(task: Pick<Todo, "status">): string {
-  switch (task.status) {
-    case "completed": return "✓";
-    case "in_progress": return "▶";
-    case "cancelled": return "×";
-    default: return "○";
-  }
+  return todoGlyph(task.status, true);
 }
 
 export function todoTasks(state: TodoState | undefined): readonly Todo[] {

package/src/reminder.ts

@@ -1,21 +1,21 @@
 import { countTodoStatuses, todoTasks } from "./format.js";
 import { currentTodoPhaseIndex } from "./state.js";
-import type { TodoState } from "./types.js";
+import { isTerminalTodo, type TodoState } from "./types.js";
 
 /** Formats the transient model-context reminder for an unfinished todo plan. */
 export function formatTodoReminder(state: TodoState): string | undefined {
   const activePhase = state.phases[currentTodoPhaseIndex(state.phases)];
   if (!activePhase) return undefined;
 
-  const activeTasks = activePhase.tasks
-    .filter((task) => task.status === "in_progress")
-    .map((task) => task.name);
+  const openTasks = activePhase.tasks.filter((task) => !isTerminalTodo(task));
   const counts = countTodoStatuses(todoTasks(state));
 
   return [
     "<system-reminder>",
     `Active phase: ${activePhase.name}`,
-    activeTasks.length > 0 ? `In progress: ${activeTasks.join("; ")}` : "No task is in_progress.",
+    ...(state.workingOn ? [`Current work: ${state.workingOn}`] : []),
+    "Open tasks in this phase:",
+    ...openTasks.map((task) => `- [${task.status}] ${task.name}: ${task.description}`),
     `Counts: ${counts.in_progress} in_progress, ${counts.pending} pending, ${counts.completed} completed, ${counts.cancelled} cancelled.`,
     "Review and update the todo if task status has changed.",
     "Do not mention this reminder to the user.",

package/src/renderer.ts

@@ -4,7 +4,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { countTodos, formatTodoProgress, todoTasks } from "./format.js";
 import { todoGlyph } from "./glyphs.js";
 import { currentTodoPhaseIndex, todoAddressKey } from "./state.js";
-import type { Todo, TodoAddress, TodoToolDetails } from "./types.js";
+import { isTerminalTodo, todoTaskPriority, type Todo, type TodoAddress, type TodoToolDetails } from "./types.js";
 
 type ThemeLike = Partial<Pick<Theme, "fg" | "bold" | "strikethrough">>;
 type ThemeColor = Parameters<Theme["fg"]>[0];
@@ -56,27 +56,17 @@ function collapsedText(header: string, tasks: readonly Todo[], theme: ThemeLike
 function orderedTasks(tasks: readonly Todo[]): Todo[] {
   return tasks
     .map((task, index) => ({ task, index }))
-    .sort((left, right) => taskPriority(left.task) - taskPriority(right.task) || left.index - right.index)
+    .sort((left, right) => todoTaskPriority(left.task) - todoTaskPriority(right.task) || left.index - right.index)
     .map(({ task }) => task);
 }
 
-function taskPriority(task: Todo): number {
-  if (task.status === "in_progress") return 0;
-  if (task.status === "pending") return 1;
-  return 2;
-}
-
 function renderTask(phase: string, task: Todo, changed: Set<string>, theme: ThemeLike | undefined, options: TodoRendererOptions): string {
-  const text = isTerminal(task) && theme?.strikethrough ? theme.strikethrough(task.name) : task.name;
+  const text = isTerminalTodo(task) && theme?.strikethrough ? theme.strikethrough(task.name) : task.name;
   let line = `    ${todoGlyph(task.status, options.fallbackGlyphs)} ${text}`;
   if ((task.status === "in_progress" || changed.has(todoAddressKey(phase, task.name))) && theme?.bold) line = theme.bold(line);
   return paint(theme, statusColor(task.status), line);
 }
 
-function isTerminal(task: Todo): boolean {
-  return task.status === "completed" || task.status === "cancelled";
-}
-
 function addressKey(address: TodoAddress): string {
   return todoAddressKey(address.phase, address.task);
 }

package/src/schema.ts

@@ -2,24 +2,30 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { TODO_ACTIONS, TODO_STATUSES } from "./types.js";
 
+export const TodoTaskSchema = Type.Object({
+  name: Type.String({
+    description: "Unique immutable task name within the phase; ~5–10 words describing what, not how.",
+  }),
+  description: Type.String({
+    description: "1–3 sentences expanding on the name with relevant context, constraints, or expected outcome.",
+  }),
+}, { additionalProperties: false });
+
 export const TodoPhaseSchema = Type.Object({
-  name: Type.String({ minLength: 1, description: "Unique immutable phase name (1–2 words)." }),
-  tasks: Type.Array(Type.String({
-    minLength: 1,
-    description: "Unique immutable task name within its phase; ideally 5–10 words describing what, not how.",
-  })),
+  name: Type.String({ description: "Unique immutable phase name; 1–2 words." }),
+  tasks: Type.Array(TodoTaskSchema, { minItems: 1 }),
 }, { additionalProperties: false });
 
 export const TodoTransitionSchema = Type.Object({
-  phase: Type.String({ minLength: 1, description: "Exact phase name." }),
-  task: Type.String({ minLength: 1, description: "Exact task name within the phase." }),
-  status: StringEnum(TODO_STATUSES, { description: "New task status." }),
+  phase: Type.String({ description: "Exact name of an existing phase." }),
+  task: Type.String({ description: "Exact name of an existing task within the phase." }),
+  status: StringEnum(TODO_STATUSES, { description: "Status to assign to the task." }),
 }, { additionalProperties: false });
 
 /** Flat provider-facing schema. Action-specific requirements are enforced by the transition. */
 export const TodoParamsSchema = Type.Object({
   action: StringEnum(TODO_ACTIONS),
-  phases: Type.Optional(Type.Array(TodoPhaseSchema)),
+  phases: Type.Optional(Type.Array(TodoPhaseSchema, { minItems: 1 })),
   transitions: Type.Optional(Type.Array(TodoTransitionSchema, { minItems: 1 })),
-  phase: Type.Optional(Type.String({ minLength: 1, description: "Exact phase to view; omit for the full plan." })),
+  workingOn: Type.Optional(Type.String({ description: "Concise summary of the current work." })),
 }, { additionalProperties: false });

package/src/state.ts

@@ -22,6 +22,7 @@ export function cloneTodoState(state: TodoState): TodoState {
       name: phase.name,
       tasks: phase.tasks.map((task) => ({ ...task })),
     })),
+    ...(state.workingOn === undefined ? {} : { workingOn: state.workingOn }),
   };
 }
 
@@ -39,12 +40,10 @@ export function transitionTodoState(state: TodoState, value: unknown): TodoState
       next = addPhases(state, action.phases);
       break;
     case "transition":
-      next = applyTransitions(state, action.transitions);
+      next = applyTransitions(state, action.transitions, action.workingOn);
       break;
     case "view":
-      next = action.phase === undefined
-        ? state
-        : { phases: [findPhase(state.phases, action.phase)] };
+      next = state;
       break;
   }
 
@@ -55,15 +54,11 @@ export function transitionTodoState(state: TodoState, value: unknown): TodoState
 function newPhase(input: TodoPhaseInput): TodoPhase {
   return {
     name: input.name,
-    tasks: input.tasks.map((task) => ({ name: task, status: "pending" })),
+    tasks: input.tasks.map((task) => ({ ...task, status: "pending" })),
   };
 }
 
 function addPhases(state: TodoState, inputs: readonly TodoPhaseInput[]): TodoState {
-  if (!inputs.some((phase) => phase.tasks.length > 0)) {
-    throw new Error("add requires at least one task.");
-  }
-
   const existingPhases = new Map(state.phases.map((phase) => [phase.name, phase]));
   for (const input of inputs) {
     const phase = existingPhases.get(input.name);
@@ -71,26 +66,30 @@ function addPhases(state: TodoState, inputs: readonly TodoPhaseInput[]): TodoSta
 
     const taskNames = new Set(phase.tasks.map((task) => task.name));
     for (const task of input.tasks) {
-      if (taskNames.has(task)) throw new Error(`Duplicate task name in phase ${input.name}: ${task}.`);
-      taskNames.add(task);
+      if (taskNames.has(task.name)) throw new Error(`Duplicate task name in phase ${input.name}: ${task.name}.`);
+      taskNames.add(task.name);
     }
   }
 
   const additions = new Map(inputs.map((phase) => [phase.name, phase.tasks]));
   const phases = state.phases.map((phase) => {
     const tasks = additions.get(phase.name);
-    return !tasks || tasks.length === 0
+    return !tasks
       ? phase
-      : { ...phase, tasks: [...phase.tasks, ...tasks.map((name) => ({ name, status: "pending" as const }))] };
+      : { ...phase, tasks: [...phase.tasks, ...tasks.map((task) => ({ ...task, status: "pending" as const }))] };
   });
 
   for (const input of inputs) {
     if (!existingPhases.has(input.name)) phases.push(newPhase(input));
   }
-  return { phases };
+  return { ...state, phases };
 }
 
-function applyTransitions(state: TodoState, transitions: readonly TodoTransitionInput[]): TodoState {
+function applyTransitions(
+  state: TodoState,
+  transitions: readonly TodoTransitionInput[],
+  workingOn: string | undefined,
+): TodoState {
   if (transitions.length === 0) throw new Error("transition requires at least one status change.");
 
   const statuses = new Map<string, TodoStatus>();
@@ -108,15 +107,19 @@ function applyTransitions(state: TodoState, transitions: readonly TodoTransition
     statuses.set(key, transition.status);
   }
 
-  return {
-    phases: state.phases.map((phase) => ({
-      ...phase,
-      tasks: phase.tasks.map((task) => {
-        const status = statuses.get(todoAddressKey(phase.name, task.name));
-        return status === undefined ? task : { ...task, status };
-      }),
-    })),
-  };
+  const phases = state.phases.map((phase) => ({
+    ...phase,
+    tasks: phase.tasks.map((task) => {
+      const status = statuses.get(todoAddressKey(phase.name, task.name));
+      return status === undefined ? task : { ...task, status };
+    }),
+  }));
+  const hasActiveTasks = phases.some((phase) => phase.tasks.some((task) => task.status === "in_progress"));
+  if (!hasActiveTasks) return { phases };
+  if (workingOn === undefined) {
+    throw new Error("transition requires workingOn when tasks remain in_progress.");
+  }
+  return { phases, workingOn };
 }
 
 function parseTodoAction(value: unknown): TodoAction {
@@ -129,26 +132,39 @@ function parseTodoAction(value: unknown): TodoAction {
       assertOnlyFields(input, ["action", "phases"], action);
       return { action, phases: parsePhases(input.phases) };
     case "transition":
-      assertOnlyFields(input, ["action", "transitions"], action);
-      return { action, transitions: parseTransitions(input.transitions) };
-    case "view":
-      assertOnlyFields(input, ["action", "phase"], action);
+      assertOnlyFields(input, ["action", "transitions", "workingOn"], action);
       return {
         action,
-        ...(input.phase === undefined ? {} : { phase: name(input.phase, "view phase") }),
+        transitions: parseTransitions(input.transitions),
+        ...(input.workingOn === undefined
+          ? {}
+          : { workingOn: name(input.workingOn, "transition workingOn") }),
       };
+    case "view":
+      assertOnlyFields(input, ["action"], action);
+      return { action };
   }
 }
 
 function parsePhases(value: unknown): TodoPhaseInput[] {
   if (!Array.isArray(value)) throw new Error("phases must be an array.");
+  if (value.length === 0) throw new Error("phases must contain at least one phase.");
   const phases = value.map((item, phaseIndex) => {
     const input = record(item, `phases[${phaseIndex}]`);
     assertOnlyFields(input, ["name", "tasks"], `phases[${phaseIndex}]`);
     const phaseName = name(input.name, `phases[${phaseIndex}].name`);
     if (!Array.isArray(input.tasks)) throw new Error(`phases[${phaseIndex}].tasks must be an array.`);
-    const tasks = input.tasks.map((task, taskIndex) => name(task, `phases[${phaseIndex}].tasks[${taskIndex}]`));
-    assertUnique(tasks, (task) => `Duplicate task name in phase ${phaseName}: ${task}.`);
+    if (input.tasks.length === 0) throw new Error(`phases[${phaseIndex}].tasks must contain at least one task.`);
+    const tasks = input.tasks.map((task, taskIndex) => {
+      const label = `phases[${phaseIndex}].tasks[${taskIndex}]`;
+      const taskInput = record(task, label);
+      assertOnlyFields(taskInput, ["name", "description"], label);
+      return {
+        name: name(taskInput.name, `${label}.name`),
+        description: name(taskInput.description, `${label}.description`),
+      };
+    });
+    assertUnique(tasks.map((task) => task.name), (task) => `Duplicate task name in phase ${phaseName}: ${task}.`);
     return { name: phaseName, tasks };
   });
   assertUnique(phases.map((phase) => phase.name), (phase) => `Duplicate phase name: ${phase}.`);
@@ -202,12 +218,6 @@ function assertUnique(values: readonly string[], message: (value: string) => str
   }
 }
 
-function findPhase(phases: readonly TodoPhase[], phaseName: string): TodoPhase {
-  const phase = phases.find((candidate) => candidate.name === phaseName);
-  if (!phase) throw new Error(phaseNotFoundMessage(phases, phaseName));
-  return phase;
-}
-
 function phaseNotFoundMessage(phases: readonly TodoPhase[], phaseName: string): string {
   const names = phases.map((phase) => `- ${phase.name}`).join("\n");
   return names ? `Phase not found: ${phaseName}.\n\nCurrent phases:\n${names}` : `Phase not found: ${phaseName}. The todo plan is empty.`;
@@ -245,7 +255,8 @@ function assertTodoState(value: unknown): asserts value is TodoState {
     throw new Error("Invalid todo state.");
   }
 
-  const state = value as { phases: unknown[] };
+  const state = value as { phases: unknown[]; workingOn?: unknown };
+  const workingOn = state.workingOn === undefined ? undefined : name(state.workingOn, "workingOn");
   const phaseNames = new Set<string>();
   let activePhase: string | undefined;
 
@@ -254,6 +265,7 @@ function assertTodoState(value: unknown): asserts value is TodoState {
       throw new Error("Invalid todo state.");
     }
     const phase = value as { name?: unknown; tasks: unknown[] };
+    if (phase.tasks.length === 0) throw new Error("Invalid todo state: phases must contain at least one task.");
     const phaseName = name(phase.name, "phase name");
     if (phaseNames.has(phaseName)) throw new Error("Invalid todo state: duplicate phase name.");
     phaseNames.add(phaseName);
@@ -261,8 +273,9 @@ function assertTodoState(value: unknown): asserts value is TodoState {
     const taskNames = new Set<string>();
     for (const value of phase.tasks) {
       if (!value || typeof value !== "object") throw new Error("Invalid todo state.");
-      const task = value as { name?: unknown; status?: unknown };
+      const task = value as { name?: unknown; description?: unknown; status?: unknown };
       const taskName = name(task.name, "task name");
+      name(task.description, "task description");
       if (taskNames.has(taskName)) throw new Error("Invalid todo state: duplicate task name.");
       if (!isTodoStatus(task.status)) throw new Error("Invalid todo state.");
       if (task.status === "in_progress") {
@@ -274,4 +287,11 @@ function assertTodoState(value: unknown): asserts value is TodoState {
       taskNames.add(taskName);
     }
   }
+
+  if (activePhase !== undefined && workingOn === undefined) {
+    throw new Error("Invalid todo state: workingOn is required while tasks are in_progress.");
+  }
+  if (activePhase === undefined && workingOn !== undefined) {
+    throw new Error("Invalid todo state: workingOn requires an in_progress task.");
+  }
 }

package/src/tool.ts

@@ -172,20 +172,19 @@ export function registerTodoTool(pi: ExtensionAPI): void {
     name: "todo",
     label: "Todo",
     description: [
-      "Maintain a phased task plan.",
+      "Maintain a phased task plan for complex work with 3+ distinct steps.",
       "Actions:",
-      "  set(phases): Replace the plan; supplied tasks start pending.",
-      "  add(phases): Add phases or tasks; preserve existing tasks and statuses.",
-      "  transition(transitions): Set statuses by exact phase and task names.",
-      "  view(phase?): Return the full plan or one exact phase.",
+      "  set(phases): Replace the entire plan; all tasks start `pending`.",
+      "  add(phases): Add described tasks; preserve existing tasks and statuses.",
+      "  transition(transitions, workingOn?): Set statuses and current work by exact phase and task names.",
+      "  view(): Return the full plan with task descriptions.",
     ].join("\n"),
     promptSnippet: "Track multi-step work in a phased task plan",
     promptGuidelines: [
-      "Use todo for work with 3+ distinct steps; skip it for 1–2 steps.",
-      "Transition todo tasks immediately when work starts or ends; do not defer updates until the end.",
-      "Complete todo tasks only after the work is done and verified; cancel abandoned or obsolete tasks.",
-      "Add material new work to todo as new tasks rather than expanding existing task scope.",
-      "Keep `in_progress` todo tasks in one phase; complete or cancel them before starting another phase.",
+      "Update the todo plan immediately as work starts, finishes, or is abandoned; never defer status transitions to the end.",
+      "Mark todo tasks `completed` only after verification and `cancelled` when abandoned or obsolete; keep all `in_progress` tasks confined to one phase.",
+      "Include an accurate `workingOn` summary in every todo transition that leaves one or more tasks `in_progress`.",
+      "Use todo `add` for material new work rather than expanding the scope of existing tasks; use the destructive `set` action only for planning or replanning.",
     ],
     parameters: TodoParamsSchema,
     renderShell: "self",
@@ -210,7 +209,7 @@ export function registerTodoTool(pi: ExtensionAPI): void {
         updateTodoWidget(ctx, state, settings);
         interactedWithTodoThisTurn = true;
         return {
-          content: [{ type: "text" as const, text: formatTodoSummary(next) }],
+          content: [{ type: "text" as const, text: formatTodoSummary(next, params.action === "view") }],
           details,
         };
       });

package/src/types.ts

@@ -14,9 +14,20 @@ export function isTodoActionName(value: unknown): value is TodoActionName {
 
 export type Todo = {
   readonly name: string;
+  readonly description: string;
   readonly status: TodoStatus;
 };
 
+export function isTerminalTodo(todo: Pick<Todo, "status">): boolean {
+  return todo.status === "completed" || todo.status === "cancelled";
+}
+
+export function todoTaskPriority(todo: Pick<Todo, "status">): number {
+  if (todo.status === "in_progress") return 0;
+  if (todo.status === "pending") return 1;
+  return 2;
+}
+
 export type TodoPhase = {
   readonly name: string;
   readonly tasks: readonly Todo[];
@@ -24,6 +35,7 @@ export type TodoPhase = {
 
 export type TodoState = {
   readonly phases: readonly TodoPhase[];
+  readonly workingOn?: string;
 };
 
 export type TodoAddress = {
@@ -38,9 +50,14 @@ export type TodoToolDetails = {
   readonly changedTasks: readonly TodoAddress[];
 };
 
+export type TodoTaskInput = {
+  readonly name: string;
+  readonly description: string;
+};
+
 export type TodoPhaseInput = {
   readonly name: string;
-  readonly tasks: readonly string[];
+  readonly tasks: readonly TodoTaskInput[];
 };
 
 export type TodoTransitionInput = TodoAddress & {
@@ -60,11 +77,11 @@ export type AddTodoAction = {
 export type TransitionTodoAction = {
   readonly action: "transition";
   readonly transitions: readonly TodoTransitionInput[];
+  readonly workingOn?: string;
 };
 
 export type ViewTodoAction = {
   readonly action: "view";
-  readonly phase?: string;
 };
 
 export type TodoAction = SetTodoAction | AddTodoAction | TransitionTodoAction | ViewTodoAction;

package/src/widget-component.ts

@@ -4,8 +4,6 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { TodoState } from "./types.js";
 import { renderTodoWidgetLines, type TodoWidgetLayoutOptions } from "./widget-layout.js";
 
-const DROPLET_FRAMES = ["", "", "󰺕", "󰻃", ""] as const;
-const DROPLET_DURATIONS_MS = [220, 110, 80, 100, 420] as const;
 const PI_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
 const PI_SPINNER_INTERVAL_MS = 80;
 
@@ -24,7 +22,7 @@ export class TodoWidgetComponent implements Component {
     private readonly options: TodoWidgetComponentOptions = {},
     private readonly tui?: Pick<TUI, "requestRender">,
   ) {
-    if (tui && state.phases.some(phase => phase.tasks.some(task => task.status === "in_progress"))) {
+    if (tui && state.workingOn) {
       this.scheduleNextFrame();
     }
   }
@@ -36,7 +34,7 @@ export class TodoWidgetComponent implements Component {
     const { blankLineBelow, ...layoutOptions } = this.options;
     const lines = renderTodoWidgetLines(this.state, this.theme, safeWidth, {
       ...layoutOptions,
-      activeMarker: this.frames[this.frameIndex],
+      workingMarker: PI_SPINNER_FRAMES[this.frameIndex],
     });
     if (blankLineBelow && lines.length > 0) lines.push("");
     return lines;
@@ -47,18 +45,11 @@ export class TodoWidgetComponent implements Component {
     this.timer = undefined;
   }
 
-  private get frames(): readonly string[] {
-    return this.options.fallbackGlyphs ? PI_SPINNER_FRAMES : DROPLET_FRAMES;
-  }
-
   private scheduleNextFrame(): void {
-    const delay = this.options.fallbackGlyphs
-      ? PI_SPINNER_INTERVAL_MS
-      : DROPLET_DURATIONS_MS[this.frameIndex];
     this.timer = setTimeout(() => {
-      this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+      this.frameIndex = (this.frameIndex + 1) % PI_SPINNER_FRAMES.length;
       this.tui?.requestRender();
       this.scheduleNextFrame();
-    }, delay);
+    }, PI_SPINNER_INTERVAL_MS);
   }
 }

package/src/widget-layout.ts

@@ -1,15 +1,14 @@
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
-import { formatTodoProgress, todoTasks } from "./format.js";
 import { todoGlyph } from "./glyphs.js";
 import { currentTodoPhaseIndex } from "./state.js";
-import type { Todo, TodoPhase, TodoState } from "./types.js";
+import { isTerminalTodo, todoTaskPriority, type Todo, type TodoPhase, type TodoState } from "./types.js";
 
 export type TodoWidgetLayoutOptions = {
   maxVisible?: number;
   fallbackGlyphs?: boolean;
-  activeMarker?: string;
+  workingMarker?: string;
 };
 
 type ThemeLike = Partial<Pick<Theme, "bold" | "fg" | "strikethrough">>;
@@ -25,12 +24,15 @@ export function renderTodoWidgetLines(
 ): string[] {
   const safeWidth = Math.max(1, Math.floor(width) || 1);
   const phases = state?.phases ?? [];
-  const selectedPhaseIndex = currentTodoPhaseIndex(phases);
+  const currentPhaseIndex = currentTodoPhaseIndex(phases);
+  const selectedPhaseIndex = currentPhaseIndex >= 0
+    ? currentPhaseIndex
+    : lastNonEmptyPhaseIndex(phases);
   if (selectedPhaseIndex < 0) return [];
   const selectedPhase = phases[selectedPhaseIndex];
   const maxVisible = boundedMaxVisible(options.maxVisible);
   const selectedTasks = visibleTasks(selectedPhase.tasks, maxVisible);
-  const lines: string[] = [fit(toolTitle(formatTodoProgress("Todos", todoTasks(state)), theme), safeWidth)];
+  const lines: string[] = [fit(toolTitle("Todos", theme), safeWidth)];
 
   for (let phaseIndex = 0; phaseIndex < phases.length; phaseIndex++) {
     const phase = phases[phaseIndex];
@@ -39,9 +41,9 @@ export function renderTodoWidgetLines(
 
     if (selected) {
       for (const task of selectedTasks) {
-        lines.push(fit(taskLine(task, theme, options.fallbackGlyphs, options.activeMarker), safeWidth));
+        lines.push(fit(taskLine(task, theme, options.fallbackGlyphs), safeWidth));
       }
-      const openTasks = phase.tasks.filter(task => !isTerminal(task));
+      const openTasks = phase.tasks.filter(task => !isTerminalTodo(task));
       const hidden = openTasks.length - selectedTasks.length;
       if (hidden > 0) lines.push(fit(`    +${hidden} more`, safeWidth));
       const terminalSummary = terminalTaskSummary(phase.tasks);
@@ -52,18 +54,37 @@ export function renderTodoWidgetLines(
     }
   }
 
+  if (state?.workingOn) {
+    lines.push("");
+    const text = theme?.fg ? theme.fg("dim", state.workingOn) : state.workingOn;
+    lines.push(fit(`  ${options.workingMarker ?? "⠋"} ${text}`, safeWidth));
+  }
+
   return lines;
 }
 
+function lastNonEmptyPhaseIndex(phases: readonly TodoPhase[]): number {
+  for (let index = phases.length - 1; index >= 0; index -= 1) {
+    if (phases[index].tasks.length > 0) return index;
+  }
+  return -1;
+}
+
 function boundedMaxVisible(value: number | undefined): number {
   if (value === undefined || !Number.isFinite(value)) return 5;
   return Math.max(1, Math.floor(value));
 }
 
 function phaseTitle(phase: TodoPhase, phaseIndex: number, selected: boolean, theme: ThemeLike | undefined): string {
-  const title = `${phaseIndex + 1}. ${formatTodoProgress(phase.name, phase.tasks)}`;
-  if (selected) return toolTitle(`  ${title}`, theme);
-  return theme?.fg ? theme.fg("dim", `  ${title}`) : `  ${title}`;
+  const title = `  ${phaseIndex + 1}. ${phase.name}`;
+  const terminal = phase.tasks.filter(isTerminalTodo).length;
+  const progress = `· ${terminal}/${phase.tasks.length}`;
+  if (!selected) {
+    const line = `${title} ${progress}`;
+    return theme?.fg ? theme.fg("dim", line) : line;
+  }
+  const dimProgress = theme?.fg ? theme.fg("dim", progress) : progress;
+  return `${toolTitle(title, theme)} ${dimProgress}`;
 }
 
 function toolTitle(text: string, theme: ThemeLike | undefined): string {
@@ -74,29 +95,22 @@ function toolTitle(text: string, theme: ThemeLike | undefined): string {
 function visibleTasks(tasks: readonly Todo[], maxVisible: number): DisplayTask[] {
   const ordered = tasks
     .map((task, taskIndex) => ({ ...task, taskIndex }))
-    .filter(task => !isTerminal(task))
-    .sort((left, right) => taskPriority(left) - taskPriority(right) || left.taskIndex - right.taskIndex);
+    .filter(task => !isTerminalTodo(task))
+    .sort((left, right) => todoTaskPriority(left) - todoTaskPriority(right) || left.taskIndex - right.taskIndex);
   const active = ordered.filter(isActive);
   return active.length > maxVisible ? active : ordered.slice(0, maxVisible);
 }
 
-function taskLine(task: Todo, theme: ThemeLike | undefined, fallbackGlyphs = false, activeMarker?: string): string {
-  const marker = isActive(task) && activeMarker ? activeMarker : todoGlyph(task.status, fallbackGlyphs);
+function taskLine(task: Todo, theme: ThemeLike | undefined, fallbackGlyphs = false): string {
+  const marker = todoGlyph(task.status, fallbackGlyphs);
   const color = task.status === "in_progress" ? "text" : task.status === "completed" ? "success" : "dim";
-  const name = (task.status === "completed" || task.status === "cancelled") && theme?.strikethrough
+  const name = isTerminalTodo(task) && theme?.strikethrough
     ? theme.strikethrough(task.name)
     : task.name;
-  let line = `    ${marker} ${name}`;
-  if (isActive(task) && theme?.bold) line = theme.bold(line);
+  const line = `    ${marker} ${name}`;
   return theme?.fg ? theme.fg(color, line) : line;
 }
 
-function taskPriority(task: Todo): number {
-  if (isActive(task)) return 0;
-  if (task.status === "pending") return 1;
-  return 2;
-}
-
 function terminalTaskSummary(tasks: readonly Todo[]): string | undefined {
   const completed = tasks.filter(task => task.status === "completed").length;
   const cancelled = tasks.filter(task => task.status === "cancelled").length;
@@ -111,10 +125,6 @@ function isActive(task: Todo): boolean {
   return task.status === "in_progress";
 }
 
-function isTerminal(task: Todo): boolean {
-  return task.status === "completed" || task.status === "cancelled";
-}
-
 function fit(line: string, width: number): string {
   return visibleWidth(line) <= width ? line : truncateToWidth(line, width, "…");
 }

package/src/widget.ts

@@ -2,7 +2,7 @@ import type { Component, TUI } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
 import type { TodoSettings } from "./settings.js";
-import type { TodoState } from "./types.js";
+import { isTerminalTodo, type TodoState } from "./types.js";
 import { TodoWidgetComponent } from "./widget-component.js";
 
 export type TodoWidgetSettings = Partial<Pick<
@@ -11,31 +11,46 @@ export type TodoWidgetSettings = Partial<Pick<
 >>;
 
 type WidgetComponentFactory = (tui: TUI, theme: Theme) => Component & { dispose?(): void };
+type TodoWidgetUI = {
+  notify?: (message: string, level?: "info" | "warning" | "error") => void;
+  setWidget?: {
+    (id: string, content: string[] | undefined, options?: { placement?: "belowEditor" | "aboveEditor" }): void;
+    (id: string, content: WidgetComponentFactory | undefined, options?: { placement?: "belowEditor" | "aboveEditor" }): void;
+  };
+};
+
+const TERMINAL_WIDGET_DELAY_MS = 5_000;
+type TodoWidgetLifecycle = {
+  hadOpenTasks: boolean;
+  terminalClearTimer?: ReturnType<typeof setTimeout>;
+};
+const widgetLifecycles = new WeakMap<TodoWidgetUI, TodoWidgetLifecycle>();
 
 export type TodoWidgetContext = {
   hasUI?: boolean;
-  ui?: {
-    notify?: (message: string, level?: "info" | "warning" | "error") => void;
-    setWidget?: {
-      (id: string, content: string[] | undefined, options?: { placement?: "belowEditor" | "aboveEditor" }): void;
-      (id: string, content: WidgetComponentFactory | undefined, options?: { placement?: "belowEditor" | "aboveEditor" }): void;
-    };
-  };
+  ui?: TodoWidgetUI;
 };
 
 /** Update (or clear) the persistent todo widget without requiring the host UI at runtime. */
 export function updateTodoWidget(ctx: TodoWidgetContext | undefined, state: TodoState | undefined, settings: TodoWidgetSettings = {}): void {
   if (!ctx?.hasUI || !ctx.ui?.setWidget) return;
+  const ui = ctx.ui;
+  const lifecycle = widgetLifecycles.get(ui) ?? { hadOpenTasks: false };
+
   try {
     const placement = settings.widgetPlacement ?? "aboveEditor";
     if (placement === "off") {
-      ctx.ui.setWidget("todo", undefined);
+      cancelTerminalClear(lifecycle);
+      widgetLifecycles.delete(ui);
+      ui.setWidget!("todo", undefined);
       return;
     }
 
-    const visibleState = state?.phases.some(phase => phase.tasks.some(task =>
-      task.status === "pending" || task.status === "in_progress",
-    )) ? state : undefined;
+    const hasTasks = state?.phases.some((phase) => phase.tasks.length > 0) ?? false;
+    const hasOpenTasks = state?.phases.some((phase) => phase.tasks.some((task) => !isTerminalTodo(task))) ?? false;
+    const showFinalState = hasTasks && !hasOpenTasks
+      && (lifecycle.hadOpenTasks || lifecycle.terminalClearTimer !== undefined);
+    const visibleState = hasOpenTasks || showFinalState ? state : undefined;
     const factory: WidgetComponentFactory | undefined = visibleState
       ? (tui, theme) => new TodoWidgetComponent(visibleState, theme, {
           maxVisible: settings.maxVisibleTasks,
@@ -43,8 +58,45 @@ export function updateTodoWidget(ctx: TodoWidgetContext | undefined, state: Todo
           blankLineBelow: placement === "aboveEditor",
         }, tui)
       : undefined;
-    ctx.ui.setWidget("todo", factory, { placement });
+    ui.setWidget!("todo", factory, { placement });
+
+    if (hasOpenTasks) {
+      cancelTerminalClear(lifecycle);
+      lifecycle.hadOpenTasks = true;
+      widgetLifecycles.set(ui, lifecycle);
+    } else if (showFinalState) {
+      lifecycle.hadOpenTasks = false;
+      if (!lifecycle.terminalClearTimer) {
+        const timer = setTimeout(() => {
+          widgetLifecycles.delete(ui);
+          clearWidget(ui);
+        }, TERMINAL_WIDGET_DELAY_MS);
+        timer.unref?.();
+        lifecycle.terminalClearTimer = timer;
+      }
+      widgetLifecycles.set(ui, lifecycle);
+    } else {
+      cancelTerminalClear(lifecycle);
+      widgetLifecycles.delete(ui);
+    }
   } catch (error) {
-    ctx.ui.notify?.(`Todo widget update failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
+    notifyWidgetError(ui, error);
   }
 }
+
+function cancelTerminalClear(lifecycle: TodoWidgetLifecycle): void {
+  if (lifecycle.terminalClearTimer) clearTimeout(lifecycle.terminalClearTimer);
+  delete lifecycle.terminalClearTimer;
+}
+
+function clearWidget(ui: TodoWidgetUI): void {
+  try {
+    ui.setWidget?.("todo", undefined);
+  } catch (error) {
+    notifyWidgetError(ui, error);
+  }
+}
+
+function notifyWidgetError(ui: TodoWidgetUI, error: unknown): void {
+  ui.notify?.(`Todo widget update failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
+}