shariq-pi-extensions 0.2.21 → 0.2.23

package/README.md

@@ -31,6 +31,7 @@ The package contains:
 - Firecrawl search and scraping
 - Git status UI
 - persistent task goals
+- branch-safe model-maintained task lists with live progress UI and compaction continuity
 - configurable steer, interrupt, or follow-up input behavior
 - dedicated multi-agent orchestration
 - Smart Compaction with high-fidelity checkpointing, delta-merging, and custom model routing

package/docs/ARCHITECTURE.md

@@ -43,6 +43,7 @@ Installed package directories are treated as immutable. Extensions resolve writa
 - Pi Memory state: `<agent-dir>/pi-memory/`
 - Subagent configuration and catalog: paths derived from `getAgentDir()`
 - Orchestration settings and run ledgers: `<agent-dir>/orchestration/`
+- Goal and Task List state: branch-local Pi session entries; neither writes a separate runtime-state file
 - project configuration: paths derived from Pi's `CONFIG_DIR_NAME`
 
 Credentials remain in Pi auth storage, environment variables, service credential stores, or ignored machine-local files. Package source never contains an API key, OAuth token, database, cache, or session.

package/docs/EXTENSIONS.md

@@ -34,6 +34,12 @@ The curated catalog intentionally excludes `-fast` variants and the removals doc
 
 The goal extension adds persistent, branch-safe objectives, progress evidence, budgets, pause/resume controls, and strict completion/blocker gates. Use `/goal` for the operator UI and the `create_goal`, `get_goal`, `update_goal_progress`, and `update_goal` tools for agent-controlled state.
 
+### [Task List](../extensions/task-list/README.md)
+
+`task_list` gives the active model a branch-safe ordered checklist for ordinary multi-step work; it is separate from persistent Goals and may be used alongside them. Writes replace the full list, retain stable IDs, support pending/in-progress/completed/blocked/cancelled states and priorities, and require an active item while pending work remains. The prompt contract requires same-message list/action calls and immediate verified status updates. Runtime reminders catch missing or stale bookkeeping, with at most one same-model follow-up if an active list is still stale when Pi settles.
+
+State is stored in Pi session entries and reconstructed on resume, reload, and tree navigation. Active work is re-injected when compaction removes the latest snapshot from model context. `/tasks` opens the interactive dashboard and direct editor; the compact live widget auto-hides after all work finishes. Subagents receive the same tool under every capability policy, but each child maintains its own session-local list rather than changing the parent's list.
+
 ### [Subagents](../extensions/subagents/README.md)
 
 The subagent extension runs flat Pi child agents with profiles, capability policies, continuation, result delivery, optional worktrees, pre-warmed task dispatch, instant cascading cancellation, cross-session persistence, and a dashboard. Configuration lives in `<agent-dir>/subagents.json`; trusted projects may override it through their Pi config directory. The configured concurrency ceiling is 50.

package/extensions/factory-provider/factory/api-keys.ts

@@ -133,9 +133,19 @@ function activeKeyEntries(modelId?: string) {
 
 export function classifyFactoryKeyCooldown(message: string): { ms: number; kind: "auth" | "rate" | "quota" } | null {
   const lower = message.toLowerCase();
-  // A bare 401/403 usually means our Factory transport or headers are wrong.
-  // Disable a credential only when Factory explicitly identifies the key itself.
-  if (lower.includes("invalid api key") || lower.includes("api key revoked") || lower.includes("api key expired")) return { ms: AUTH_COOLDOWN_MS, kind: "auth" };
+  if (
+    lower.includes("invalid api key") ||
+    lower.includes("api key revoked") ||
+    lower.includes("api key expired") ||
+    lower.includes("forbidden") ||
+    lower.includes("unauthorized") ||
+    lower.includes("permission") ||
+    lower.includes("access denied") ||
+    /\b401\b/.test(lower) ||
+    /\b403\b/.test(lower)
+  ) {
+    return { ms: AUTH_COOLDOWN_MS, kind: "auth" };
+  }
   if (/\b429\b/.test(lower) || lower.includes("rate limit")) return { ms: RATE_COOLDOWN_MS, kind: "rate" };
   if (lower.includes("quota") || lower.includes("billing") || lower.includes("credit") || lower.includes("usage limit") || lower.includes("exhaust")) return { ms: DEFAULT_COOLDOWN_MS, kind: "quota" };
   return null;
@@ -325,8 +335,8 @@ export function streamSimpleFactoryApiKeyResponses(model: any, context: any, opt
         const error = errorText(event);
         if (error) {
           lastError = error;
-          const retryNext = !hasStarted && markKeyFailure(key, error, model.id);
-          if (retryNext) {
+          markKeyFailure(key, error, model.id);
+          if (!hasStarted) {
             retriedBeforeStart = true;
             break;
           }

package/extensions/subagents/README.md

@@ -42,7 +42,7 @@ Capability modes:
 - `execute` — the read-only allowlist plus shell and background-terminal execution, without direct file edit tools
 - `all` — full child tool access
 
-Restrictive modes fail closed: newly registered extension tools remain unavailable until they are explicitly classified. This prevents another extension from silently bypassing the selected capability.
+Restrictive modes fail closed: newly registered extension tools remain unavailable until they are explicitly classified. This prevents another extension from silently bypassing the selected capability. The session-only `task_list` planning tool is explicitly classified as safe in every capability mode, so each child can maintain its own task list without receiving file-write or command-execution authority.
 
 Optional user profiles and personas can be defined in `~/.pi/agent/subagents.json`. Trusted projects may override them in `.pi/subagents.json`:
 
@@ -64,7 +64,7 @@ Optional user profiles and personas can be defined in `~/.pi/agent/subagents.jso
 }
 ```
 
-Project configuration is ignored when the project is not trusted. Concurrency is bounded to 1–50; this private package defaults to 50. `/subagents profiles` provides discovery, while `/subagents config` opens a validated editor for global or trusted-project configuration.
+Project configuration is ignored when the project is not trusted. Concurrency is bounded to 1–50; this suite defaults to 50. `/subagents profiles` provides discovery, while `/subagents config` opens a validated editor for global or trusted-project configuration.
 
 ## Context and continuation
 

package/extensions/subagents/src/backends/pi.ts

@@ -65,6 +65,7 @@ const READ_CAPABILITY_TOOLS = new Set([
   "pi_memory_read",
   "pi_memory_status",
   "get_goal",
+  "task_list",
   "read_terminal",
   "list_terminals",
   "message_parent",

package/extensions/task-list/README.md

@@ -0,0 +1,107 @@
+# Pi Task List
+
+A branch-safe task list for ordinary multi-step work. The active model creates and maintains the list while it works; there is no background planner or separate task-list agent.
+
+This extension is independent of the Goal extension. A normal task can use Task List without becoming a persistent goal, and an explicitly created goal can use its own evidence ledger and Task List at the same time.
+
+## Model tool
+
+`task_list` reads or replaces the current session list:
+
+- omit `tasks` to read the current list;
+- supply `tasks` to replace the entire ordered list;
+- send stable IDs so progress survives revisions;
+- use `explanation` when scope, order, or approach changes.
+
+Each item has:
+
+- `id` — stable letters/numbers/dots/underscores/hyphens identifier;
+- `content` — a concrete outcome, including exact user-provided commands or literals when relevant;
+- `status` — `pending`, `in_progress`, `completed`, `blocked`, or `cancelled`;
+- `priority` — `high`, `medium`, or `low` (`medium` by default);
+- `note` — optional evidence, blocker, cancellation reason, or execution detail.
+
+A list may contain up to 64 items. A model write with pending work must keep at least one item `in_progress`. Sequential work should have one active item; several are allowed only when work is genuinely running in parallel.
+
+## Update discipline
+
+The tool definition and Pi prompt guidance explicitly require the model to:
+
+1. create a list for requests with at least three distinct actions, multiple requested tasks, or meaningful phases;
+2. skip the list for direct answers and one- or two-action work;
+3. send the initial list in the same assistant message as the first real action;
+4. update the list as each step changes instead of batching bookkeeping at the end;
+5. mark work complete only after its outcome is verified;
+6. preserve every user-requested item and exact command, flag, path, and success condition;
+7. reconcile the full list before the final response.
+
+The runtime reinforces these instructions without assigning the list to another worker:
+
+- after two substantive tool calls with no list, the next model context receives a conditional reminder;
+- after substantive work makes an active list stale, the next model context asks for an immediate update paired with the next action;
+- if the model still stops with a stale active list, Pi starts at most one follow-up model turn so the same model can update it and continue or finish;
+- status-only inspection tools do not count as substantive progress.
+
+The list remains a coordination aid, not evidence that implementation or verification succeeded.
+
+## Continuity
+
+Every update stores a complete immutable snapshot in Pi custom session entries. State is reconstructed from the active branch on startup, resume, reload, and tree navigation, so branching restores the list that belonged to that point in history.
+
+Active items are injected into model context only when the current snapshot is no longer represented there, including after compaction. Completed and cancelled work is summarized by count in that continuity message so the model does not redo it.
+
+No external task database or writable package file is used.
+
+## Subagents
+
+Pi subagents load this extension with their normal child resources. `task_list` is explicitly allowed under every child capability policy because it changes only the child session's planning state. Each child owns an independent list in its own persistent Pi session; a child does not mutate the parent model's list.
+
+## User interface
+
+Run:
+
+```text
+/tasks
+```
+
+While work is active, a compact widget above the editor shows progress and the current items. A finished list lingers for four seconds so the final checkmark is visible, then clears from the live chrome while remaining available in session history.
+
+`/tasks` opens the full-width interactive dashboard:
+
+- `↑`/`↓` or `j`/`k` — select an item;
+- `space` — advance pending → in progress → completed;
+- `b` — block/unblock;
+- `c` — cancel/restore;
+- `p` — cycle priority;
+- `a` — add;
+- `e` — edit;
+- `d` — delete with confirmation;
+- `h` — hide/show completed and cancelled items;
+- `X` — clear the list with confirmation;
+- `Esc` or `q` — close.
+
+User edits automatically promote the next pending item when no task remains in progress. `/tasks clear` provides the same guarded clear action without opening the dashboard. In print, JSON, or RPC-oriented use, the tool remains fully functional and `/tasks status` falls back to a text summary where a custom terminal dashboard is unavailable.
+
+## Design inputs
+
+The implementation combines the strongest verified patterns from the compared harnesses:
+
+- Pi's branch-aware tool-result/session-entry model and custom TUI surfaces;
+- Codex's concise ordered plan, optional update explanation, and timely status transitions;
+- OpenCode's whole-list replacement and persistent session projection;
+- Grok Build's compact live panel, cancelled state, compaction continuity, and stale-list reminders;
+- DeepSeek Harness's strict input validation, parallel-active policy, and dedicated composer panel;
+- Hermes Agent's stable IDs, read-or-write tool, merge-informed state model, four-state UI, and post-compaction active-list injection;
+- Factory Droid's same-message task/action rule, three-action threshold, real-time completion discipline, stale-plan warning, and compact TodoWrite presentation.
+
+OpenClaw's inspected task/update surfaces do not provide a comparable model-maintained coding-session todo tool, so no incompatible lifecycle was copied from them.
+
+## Validation
+
+From the repository root:
+
+```bash
+bun test extensions/task-list extensions/subagents/context-config.test.ts
+bun x tsc --noEmit
+npm run validate
+```

package/extensions/task-list/index.ts

@@ -0,0 +1,471 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { StringEnum } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { oneLine } from "../shared/tui-dashboard.ts";
+import {
+  TASK_LIST_ENTRY,
+  TASK_LIST_TOOL,
+  MAX_TASKS,
+  MAX_TASK_CONTENT_CHARS,
+  buildUpdatedTaskList,
+  copyTaskListState,
+  emptyTaskListState,
+  hasActiveTasks,
+  restoreTaskList,
+  taskCounts,
+  taskListContext,
+  taskListText,
+} from "./state.ts";
+import type {
+  TaskItem,
+  TaskListDetails,
+  TaskListInput,
+  TaskListSnapshot,
+  TaskListState,
+  TaskPriority,
+  TaskStatus,
+} from "./types.ts";
+import { TASK_PRIORITIES, TASK_STATUSES } from "./types.ts";
+import { openTaskDashboard, taskGlyph } from "./ui.ts";
+
+const WIDGET_ID = "task-list";
+const FINISHED_LINGER_MS = 4_000;
+const WORK_TOOL_EXCLUSIONS = new Set([
+  TASK_LIST_TOOL,
+  "get_goal",
+  "list_agents",
+  "check_agent",
+  "wait_agent",
+  "list_terminals",
+  "pi_memory_status",
+]);
+
+const TaskListParams = Type.Object({
+  tasks: Type.Optional(Type.Array(
+    Type.Object({
+      id: Type.String({ minLength: 1, maxLength: 80, description: "Stable identifier using letters, numbers, dots, underscores, or hyphens." }),
+      content: Type.String({ minLength: 1, maxLength: 500, description: "Short, concrete task outcome. Preserve user-supplied commands and exact literals." }),
+      status: StringEnum(TASK_STATUSES, { description: "pending | in_progress | completed | blocked | cancelled" }),
+      priority: Type.Optional(StringEnum(TASK_PRIORITIES, { description: "Defaults to medium; use high only when order or urgency materially requires it." })),
+      note: Type.Optional(Type.String({ maxLength: 1_000, description: "Concise evidence, blocker, cancellation reason, or execution detail." })),
+    }, { additionalProperties: false }),
+    { maxItems: 64, description: "The complete ordered task list. Supplying this field replaces the previous list." },
+  )),
+  explanation: Type.Optional(Type.String({ maxLength: 1_000, description: "Why the list changed, especially after a scope or approach change." })),
+}, { additionalProperties: false });
+
+function statusColor(status: TaskStatus): "accent" | "success" | "warning" | "error" | "muted" {
+  if (status === "in_progress") return "accent";
+  if (status === "completed") return "success";
+  if (status === "blocked") return "error";
+  if (status === "cancelled") return "muted";
+  return "muted";
+}
+
+function terminal(status: TaskStatus): boolean {
+  return status === "completed" || status === "cancelled";
+}
+
+function summaryLine(state: TaskListState): string {
+  const counts = taskCounts(state.tasks);
+  return `${counts.completed}/${counts.total} completed · ${counts.inProgress} active · ${counts.pending} pending · ${counts.blocked} blocked · ${counts.cancelled} cancelled`;
+}
+
+function nextUniqueId(state: TaskListState, content: string): string {
+  const base = content
+    .normalize("NFKD")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40) || "task";
+  const existing = new Set(state.tasks.map((task) => task.id));
+  if (!existing.has(base)) return base;
+  for (let suffix = 2; suffix < 10_000; suffix++) {
+    const candidate = `${base}-${suffix}`;
+    if (!existing.has(candidate)) return candidate;
+  }
+  return `task-${Date.now()}`;
+}
+
+export default function taskListExtension(pi: ExtensionAPI) {
+  let state = emptyTaskListState();
+  let lastCtx: ExtensionContext | null = null;
+  let finishedTimer: ReturnType<typeof setTimeout> | undefined;
+  let sequence = 0;
+  let lastTaskSequence = 0;
+  let lastWorkSequence = 0;
+  let workCallsSinceUser = 0;
+  let taskCallsSinceUser = 0;
+  let nudgeCount = 0;
+  let staleAtAgentEnd = false;
+
+  function cancelFinishedTimer(): void {
+    if (!finishedTimer) return;
+    clearTimeout(finishedTimer);
+    finishedTimer = undefined;
+  }
+
+  function updatePresentation(ctx: ExtensionContext): void {
+    lastCtx = ctx;
+    cancelFinishedTimer();
+    if (!ctx.hasUI || state.tasks.length === 0) {
+      ctx.ui.setWidget(WIDGET_ID, undefined);
+      ctx.ui.setStatus(WIDGET_ID, undefined);
+      return;
+    }
+
+    const counts = taskCounts(state.tasks);
+    const active = hasActiveTasks(state);
+    const renderWidget = (_tui: unknown, theme: ExtensionContext["ui"]["theme"]) => ({
+      render(width: number): string[] {
+        const current = state.tasks.filter((task) => !terminal(task.status));
+        const finished = counts.completed + counts.cancelled;
+        const header = truncateToWidth(
+          `${theme.fg(active ? "accent" : "success", theme.bold("Tasks"))} ${theme.fg("muted", `${finished}/${counts.total}`)}${counts.blocked ? theme.fg("warning", ` · ${counts.blocked} blocked`) : ""}`,
+          width,
+        );
+        const source = active ? current : state.tasks;
+        const shown = (active ? source.slice(0, 5) : source.slice(-3));
+        const lines = shown.map((task) => {
+          const color = statusColor(task.status);
+          const label = `${theme.fg(color, taskGlyph(task.status))} ${theme.fg(terminal(task.status) ? "muted" : "text", oneLine(task.content))}`;
+          return truncateToWidth(label, width);
+        });
+        const hidden = source.length - shown.length;
+        if (hidden > 0) lines.push(truncateToWidth(theme.fg("dim", `… +${hidden} more · /tasks`), width));
+        return [header, ...lines];
+      },
+      invalidate() {},
+    });
+    ctx.ui.setWidget(WIDGET_ID, renderWidget);
+    if (active) {
+      const status = counts.blocked > 0
+        ? `Tasks ${counts.completed}/${counts.total} · ${counts.blocked} blocked`
+        : `Tasks ${counts.completed}/${counts.total} · ${counts.inProgress} active`;
+      ctx.ui.setStatus(WIDGET_ID, ctx.ui.theme.fg(counts.blocked > 0 ? "warning" : "accent", status));
+      return;
+    }
+
+    ctx.ui.setStatus(WIDGET_ID, ctx.ui.theme.fg("success", `Tasks complete ${counts.completed}/${counts.total}`));
+    finishedTimer = setTimeout(() => {
+      finishedTimer = undefined;
+      if (lastCtx !== ctx || hasActiveTasks(state)) return;
+      ctx.ui.setWidget(WIDGET_ID, undefined);
+      ctx.ui.setStatus(WIDGET_ID, undefined);
+    }, FINISHED_LINGER_MS);
+    finishedTimer.unref?.();
+  }
+
+  function persist(ctx: ExtensionContext): void {
+    lastCtx = ctx;
+    pi.appendEntry(TASK_LIST_ENTRY, { state: copyTaskListState(state) } satisfies TaskListSnapshot);
+    updatePresentation(ctx);
+  }
+
+  function replaceState(next: TaskListState, ctx: ExtensionContext): void {
+    state = next;
+    persist(ctx);
+  }
+
+  function ensureActiveTask(tasks: TaskItem[]): TaskItem[] {
+    if (tasks.some((task) => task.status === "in_progress")) return tasks;
+    const next = tasks.find((task) => task.status === "pending");
+    return next
+      ? tasks.map((task) => task.id === next.id ? { ...task, status: "in_progress" } : task)
+      : tasks;
+  }
+
+  function mutateState(ctx: ExtensionContext, mutate: (tasks: TaskItem[]) => TaskItem[], explanation?: string): void {
+    const timestamp = Date.now();
+    const previous = new Map(state.tasks.map((task) => [task.id, task]));
+    const next = ensureActiveTask(mutate(state.tasks.map((task) => ({ ...task }))));
+    state = {
+      revision: state.revision + 1,
+      tasks: next.map((task) => {
+        const prior = previous.get(task.id);
+        const unchanged = prior && prior.content === task.content && prior.status === task.status && prior.priority === task.priority && prior.note === task.note;
+        return { ...task, updatedAt: unchanged ? prior.updatedAt : timestamp };
+      }),
+      explanation,
+      updatedAt: timestamp,
+    };
+    persist(ctx);
+  }
+
+  function currentRevisionVisible(messages: ReadonlyArray<unknown>): boolean {
+    return messages.some((message) => {
+      if (!message || typeof message !== "object") return false;
+      const candidate = message as { role?: string; toolName?: string; details?: Partial<TaskListDetails> };
+      return candidate.role === "toolResult" && candidate.toolName === TASK_LIST_TOOL && (candidate.details?.state?.revision ?? -1) >= state.revision;
+    });
+  }
+
+  function reminderText(): string | null {
+    if (hasActiveTasks(state) && lastWorkSequence > lastTaskSequence) {
+      return "The task list is stale after substantive work. Before more narration, call task_list with the complete updated list: mark finished work completed only if verified, keep current work in_progress, and pair the update with the next action tool when work remains.";
+    }
+    if (state.tasks.length === 0 && taskCallsSinceUser === 0 && workCallsSinceUser >= 2) {
+      return "You have started multi-action work without task_list. If this request requires at least three distinct actions or contains multiple user tasks, create the complete list now and call task_list in the same assistant message as the next action. Do not create a retroactive list if the work is already complete or was genuinely trivial.";
+    }
+    return null;
+  }
+
+  pi.on("input", async (event) => {
+    if (event.source === "extension") return;
+    workCallsSinceUser = 0;
+    taskCallsSinceUser = 0;
+    lastTaskSequence = 0;
+    lastWorkSequence = 0;
+    staleAtAgentEnd = false;
+    nudgeCount = 0;
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    lastCtx = ctx;
+    state = restoreTaskList(ctx);
+    sequence = 0;
+    lastTaskSequence = 0;
+    lastWorkSequence = 0;
+    workCallsSinceUser = 0;
+    taskCallsSinceUser = 0;
+    nudgeCount = 0;
+    updatePresentation(ctx);
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    state = restoreTaskList(ctx);
+    updatePresentation(ctx);
+  });
+
+  pi.on("tool_execution_start", async (event, ctx) => {
+    lastCtx = ctx;
+    sequence++;
+    if (event.toolName === TASK_LIST_TOOL) {
+      lastTaskSequence = sequence;
+      taskCallsSinceUser++;
+    } else if (!WORK_TOOL_EXCLUSIONS.has(event.toolName)) {
+      lastWorkSequence = sequence;
+      workCallsSinceUser++;
+    }
+  });
+
+  pi.on("context", async (event) => {
+    const additions: AgentMessage[] = [];
+    if (hasActiveTasks(state) && !currentRevisionVisible(event.messages)) {
+      additions.push({
+        role: "custom",
+        customType: "task-list-context",
+        content: taskListContext(state),
+        display: false,
+        details: { revision: state.revision },
+        timestamp: Date.now(),
+      });
+    }
+    const reminder = reminderText();
+    if (reminder) {
+      additions.push({
+        role: "custom",
+        customType: "task-list-reminder",
+        content: `<task_list_reminder>${reminder}</task_list_reminder>`,
+        display: false,
+        details: { revision: state.revision },
+        timestamp: Date.now(),
+      });
+    }
+    return additions.length > 0 ? { messages: [...event.messages, ...additions] } : undefined;
+  });
+
+  pi.on("agent_end", async () => {
+    staleAtAgentEnd = hasActiveTasks(state) && lastWorkSequence > lastTaskSequence;
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    lastCtx = ctx;
+    if (!staleAtAgentEnd || nudgeCount >= 1 || ctx.hasPendingMessages()) return;
+    staleAtAgentEnd = false;
+    nudgeCount++;
+    pi.sendMessage({
+      customType: "task-list-reminder",
+      content: "You stopped with a stale active task list. Update task_list now. If work remains, pair that update with the next concrete action; if work is finished, mark verified items completed and cancelled items with a reason before the final response.",
+      display: false,
+      details: { revision: state.revision, kind: "settled-stale-list" },
+    }, { deliverAs: "followUp", triggerTurn: true });
+  });
+
+  pi.on("session_shutdown", async () => {
+    cancelFinishedTimer();
+  });
+
+  async function runDashboard(ctx: ExtensionCommandContext): Promise<void> {
+    if (ctx.mode !== "tui") {
+      ctx.ui.notify(taskListText(state), "info");
+      return;
+    }
+    while (true) {
+      const action = await openTaskDashboard(ctx, { getState: () => state });
+      if (action.kind === "close") return;
+      if (action.kind === "clear") {
+        if (!state.tasks.length) continue;
+        const confirmed = await ctx.ui.confirm("Clear task list?", "This removes every current task from this session branch.");
+        if (confirmed) mutateState(ctx, () => [], "Task list cleared by user.");
+        continue;
+      }
+      if (action.kind === "add") {
+        if (state.tasks.length >= MAX_TASKS) {
+          ctx.ui.notify(`A task list can contain at most ${MAX_TASKS} items.`, "warning");
+          continue;
+        }
+        const content = await ctx.ui.input("Add task", "Short, concrete outcome");
+        const cleaned = content?.trim().normalize("NFKC");
+        if (!cleaned) continue;
+        if (Array.from(cleaned).length > MAX_TASK_CONTENT_CHARS) {
+          ctx.ui.notify(`Task content exceeds ${MAX_TASK_CONTENT_CHARS} characters.`, "warning");
+          continue;
+        }
+        const id = nextUniqueId(state, cleaned);
+        mutateState(ctx, (tasks) => [...tasks, {
+          id,
+          content: cleaned,
+          status: tasks.some((task) => task.status === "in_progress") ? "pending" : "in_progress",
+          priority: "medium",
+          updatedAt: Date.now(),
+        }], "Task added by user.");
+        continue;
+      }
+      const task = state.tasks.find((item) => item.id === action.id);
+      if (!task) continue;
+      if (action.kind === "edit") {
+        const content = await ctx.ui.input("Edit task", task.content);
+        const cleaned = content?.trim().normalize("NFKC");
+        if (!cleaned) continue;
+        if (Array.from(cleaned).length > MAX_TASK_CONTENT_CHARS) {
+          ctx.ui.notify(`Task content exceeds ${MAX_TASK_CONTENT_CHARS} characters.`, "warning");
+          continue;
+        }
+        mutateState(ctx, (tasks) => tasks.map((item) => item.id === task.id ? { ...item, content: cleaned } : item), "Task edited by user.");
+      } else if (action.kind === "delete") {
+        const confirmed = await ctx.ui.confirm("Delete task?", task.content);
+        if (confirmed) mutateState(ctx, (tasks) => tasks.filter((item) => item.id !== task.id), "Task deleted by user.");
+      } else if (action.kind === "status") {
+        mutateState(ctx, (tasks) => tasks.map((item) => item.id === task.id ? { ...item, status: action.status } : item), "Task status changed by user.");
+      } else if (action.kind === "priority") {
+        mutateState(ctx, (tasks) => tasks.map((item) => item.id === task.id ? { ...item, priority: action.priority } : item), "Task priority changed by user.");
+      }
+    }
+  }
+
+  pi.registerCommand("tasks", {
+    description: "Open the current session task list",
+    getArgumentCompletions: (prefix) => {
+      const options = ["status", "clear"];
+      const matches = options.filter((option) => option.startsWith(prefix));
+      return matches.length ? matches.map((value) => ({ value, label: value })) : null;
+    },
+    handler: async (args, ctx) => {
+      lastCtx = ctx;
+      const command = args.trim().toLowerCase();
+      if (!command || command === "status") {
+        await runDashboard(ctx);
+        return;
+      }
+      if (command === "clear") {
+        if (!state.tasks.length) {
+          ctx.ui.notify("No tasks to clear.", "info");
+          return;
+        }
+        const confirmed = await ctx.ui.confirm("Clear task list?", "This removes every current task from this session branch.");
+        if (!confirmed) return;
+        mutateState(ctx, () => [], "Task list cleared by user.");
+        ctx.ui.notify("Task list cleared.", "info");
+        return;
+      }
+      ctx.ui.notify("Usage: /tasks [status|clear]", "warning");
+    },
+  });
+
+  pi.registerTool({
+    name: TASK_LIST_TOOL,
+    label: "Task List",
+    description: `Read or replace the ordered task list for this coding session. Omit tasks to read it. When tasks is supplied, it is the COMPLETE replacement list, not a patch.
+
+Use task_list for work with at least three distinct actions, multiple user-requested tasks, or meaningful phases that need visible progress. Skip it for a direct answer or one or two simple actions.
+
+Start the list before substantive work and call task_list in the SAME assistant message as the first action tool. Never spend a turn only announcing or updating the list when another action can run. Keep stable ids and preserve every user-requested item, exact command, flag, path, and success condition.
+
+Update the list as work happens, not after several steps: mark a finished item completed only after its outcome is verified, move the next sequential item to in_progress, and issue that next action in the same assistant message. Keep one in_progress task for sequential work; use several only when work is genuinely running in parallel. Use blocked only for a concrete unresolved dependency and cancelled only when an item is no longer required, with the reason in note.
+
+Before the final response, reconcile the whole list with actual results. No item may remain pending or in_progress if the requested work is finished. Do not claim completion from the list itself.`,
+    promptSnippet: "Read or replace the current session's complete task list and progress state.",
+    promptGuidelines: [
+      "Use task_list for requests with at least three distinct actions, multiple requested tasks, or meaningful phases; skip it for direct answers and one- or two-action work.",
+      "Create task_list before substantive multi-step work and send the update in the same assistant message as the first real action; never spend a turn on task bookkeeping alone when another action exists.",
+      "Every task_list write replaces the entire ordered list. Preserve stable ids, all unfinished and user-requested work, and exact commands, flags, paths, and success conditions.",
+      "Update task_list immediately as each step changes: complete only verified work, set the next sequential item in_progress, and pair the update with the next action. Multiple in_progress items require genuinely parallel work.",
+      "Before a final response, reconcile task_list with observed results and leave no stale pending or in_progress items when the requested work is finished. The list is not proof of completion.",
+    ],
+    parameters: TaskListParams,
+    async execute(_toolCallId, params: TaskListInput, _signal, _onUpdate, ctx) {
+      lastCtx = ctx;
+      if (params.tasks !== undefined) {
+        replaceState(buildUpdatedTaskList(state, params), ctx);
+        lastTaskSequence = Math.max(lastTaskSequence, sequence);
+      }
+      const action = params.tasks === undefined ? "read" : "update";
+      const details: TaskListDetails = {
+        action,
+        state: copyTaskListState(state),
+        counts: taskCounts(state.tasks),
+      };
+      return {
+        content: [{ type: "text", text: taskListText(state) }],
+        details,
+      };
+    },
+    renderCall(args, theme, context) {
+      const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+      const action = args.tasks === undefined ? "read" : "update";
+      const count = args.tasks?.length;
+      text.setText(
+        theme.fg("toolTitle", theme.bold("task_list ")) +
+        theme.fg("muted", action) +
+        (count == null ? "" : theme.fg("dim", ` · ${count} item${count === 1 ? "" : "s"}`)),
+      );
+      return text;
+    },
+    renderResult(result, { expanded, isPartial }, theme, context) {
+      const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+      if (isPartial) {
+        text.setText(theme.fg("warning", "Updating task list…"));
+        return text;
+      }
+      const details = result.details as TaskListDetails | undefined;
+      if (!details) {
+        const first = result.content[0];
+        text.setText(first?.type === "text" ? first.text : "");
+        return text;
+      }
+      const counts = details.counts;
+      const complete = counts.total > 0 && counts.completed + counts.cancelled === counts.total;
+      let output = theme.fg(complete ? "success" : "accent", complete ? "✓ " : "◆ ") + theme.fg("muted", summaryLine(details.state));
+      const visible = expanded
+        ? details.state.tasks
+        : details.state.tasks.filter((task) => task.status === "in_progress" || task.status === "blocked").slice(0, 3);
+      for (const task of visible) {
+        const color = statusColor(task.status);
+        const content = terminal(task.status) ? theme.strikethrough(oneLine(task.content)) : oneLine(task.content);
+        output += `\n${theme.fg(color, taskGlyph(task.status))} ${theme.fg(color, content)}${task.note && expanded ? theme.fg("dim", ` — ${oneLine(task.note)}`) : ""}`;
+      }
+      if (!expanded && visible.length === 0 && counts.total > 0) {
+        output += `\n${theme.fg("dim", complete ? "All tasks finished" : "No active task")}`;
+      }
+      text.setText(output);
+      return text;
+    },
+  });
+}

package/extensions/task-list/state.ts

@@ -0,0 +1,225 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  TaskCounts,
+  TaskItem,
+  TaskListDetails,
+  TaskListInput,
+  TaskListSnapshot,
+  TaskListState,
+  TaskPriority,
+  TaskStatus,
+} from "./types.ts";
+import { TASK_PRIORITIES, TASK_STATUSES } from "./types.ts";
+
+export const TASK_LIST_ENTRY = "task-list-state";
+export const TASK_LIST_TOOL = "task_list";
+export const MAX_TASKS = 64;
+export const MAX_TASK_CONTENT_CHARS = 500;
+export const MAX_TASK_NOTE_CHARS = 1_000;
+export const MAX_EXPLANATION_CHARS = 1_000;
+
+const statusSet = new Set<string>(TASK_STATUSES);
+const prioritySet = new Set<string>(TASK_PRIORITIES);
+
+function now(): number {
+  return Date.now();
+}
+
+export function emptyTaskListState(): TaskListState {
+  return { revision: 0, tasks: [], updatedAt: now() };
+}
+
+export function copyTaskListState(state: TaskListState): TaskListState {
+  return {
+    ...state,
+    tasks: state.tasks.map((task) => ({ ...task })),
+  };
+}
+
+function normalizeStoredState(value: unknown): TaskListState | null {
+  if (!value || typeof value !== "object") return null;
+  const candidate = value as Partial<TaskListState>;
+  if (!Array.isArray(candidate.tasks)) return null;
+
+  const tasks: TaskItem[] = [];
+  const ids = new Set<string>();
+  for (const raw of candidate.tasks) {
+    if (!raw || typeof raw !== "object") return null;
+    const task = raw as Partial<TaskItem>;
+    if (
+      typeof task.id !== "string" ||
+      typeof task.content !== "string" ||
+      typeof task.status !== "string" ||
+      !statusSet.has(task.status)
+    ) return null;
+    const id = task.id.trim();
+    const content = task.content.trim();
+    if (
+      !id ||
+      !content ||
+      !/^[A-Za-z0-9._-]+$/.test(id) ||
+      Array.from(id).length > 80 ||
+      Array.from(content).length > MAX_TASK_CONTENT_CHARS ||
+      ids.has(id)
+    ) return null;
+    ids.add(id);
+    const priority = typeof task.priority === "string" && prioritySet.has(task.priority)
+      ? task.priority as TaskPriority
+      : "medium";
+    const note = typeof task.note === "string" && task.note.trim() ? task.note.trim() : undefined;
+    if (note && Array.from(note).length > MAX_TASK_NOTE_CHARS) return null;
+    tasks.push({
+      id,
+      content,
+      status: task.status as TaskStatus,
+      priority,
+      note,
+      updatedAt: Number.isSafeInteger(task.updatedAt) ? task.updatedAt! : now(),
+    });
+  }
+
+  if (tasks.length > MAX_TASKS) return null;
+  const explanation = typeof candidate.explanation === "string" && candidate.explanation.trim()
+    ? candidate.explanation.trim()
+    : undefined;
+  if (explanation && Array.from(explanation).length > MAX_EXPLANATION_CHARS) return null;
+  return {
+    revision: Number.isSafeInteger(candidate.revision) && candidate.revision! >= 0
+      ? candidate.revision!
+      : 0,
+    tasks,
+    explanation,
+    updatedAt: Number.isSafeInteger(candidate.updatedAt) ? candidate.updatedAt! : now(),
+  };
+}
+
+export function restoreTaskList(ctx: ExtensionContext): TaskListState {
+  let restored: TaskListState | null = null;
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "custom" && entry.customType === TASK_LIST_ENTRY) {
+      const snapshot = entry.data as Partial<TaskListSnapshot> | undefined;
+      restored = normalizeStoredState(snapshot?.state) ?? restored;
+      continue;
+    }
+    if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
+    if (entry.message.toolName !== TASK_LIST_TOOL) continue;
+    const details = entry.message.details as Partial<TaskListDetails> | undefined;
+    restored = normalizeStoredState(details?.state) ?? restored;
+  }
+  return restored ?? emptyTaskListState();
+}
+
+function cleanBounded(value: string, field: string, max: number): string {
+  const cleaned = value.trim().normalize("NFKC");
+  if (!cleaned) throw new Error(`${field} must not be empty.`);
+  if (Array.from(cleaned).length > max) {
+    throw new Error(`${field} exceeds ${max.toLocaleString()} characters.`);
+  }
+  return cleaned;
+}
+
+export function buildUpdatedTaskList(current: TaskListState, input: TaskListInput): TaskListState {
+  if (input.tasks === undefined) return copyTaskListState(current);
+  if (input.tasks.length > MAX_TASKS) {
+    throw new Error(`A task list can contain at most ${MAX_TASKS} items.`);
+  }
+
+  const ids = new Set<string>();
+  const previous = new Map(current.tasks.map((task) => [task.id, task]));
+  const timestamp = now();
+  const tasks = input.tasks.map((raw, index): TaskItem => {
+    const id = cleanBounded(raw.id, `Task ${index + 1} id`, 80);
+    if (!/^[A-Za-z0-9._-]+$/.test(id)) {
+      throw new Error(`Task id "${id}" may contain only letters, numbers, dots, underscores, and hyphens.`);
+    }
+    if (ids.has(id)) throw new Error(`Duplicate task id "${id}".`);
+    ids.add(id);
+    if (!statusSet.has(raw.status)) throw new Error(`Invalid status for task "${id}".`);
+    const priority = raw.priority ?? previous.get(id)?.priority ?? "medium";
+    if (!prioritySet.has(priority)) throw new Error(`Invalid priority for task "${id}".`);
+    const content = cleanBounded(raw.content, `Task "${id}" content`, MAX_TASK_CONTENT_CHARS);
+    const note = raw.note == null || !raw.note.trim()
+      ? undefined
+      : cleanBounded(raw.note, `Task "${id}" note`, MAX_TASK_NOTE_CHARS);
+    const prior = previous.get(id);
+    const unchanged = prior && prior.content === content && prior.status === raw.status && prior.priority === priority && prior.note === note;
+    return {
+      id,
+      content,
+      status: raw.status,
+      priority,
+      note,
+      updatedAt: unchanged ? prior.updatedAt : timestamp,
+    };
+  });
+
+  const unfinished = tasks.filter((task) => task.status === "pending" || task.status === "in_progress");
+  if (unfinished.some((task) => task.status === "pending") && !unfinished.some((task) => task.status === "in_progress")) {
+    throw new Error("At least one task must be in_progress while pending work remains.");
+  }
+
+  const explanation = input.explanation == null || !input.explanation.trim()
+    ? undefined
+    : cleanBounded(input.explanation, "Task-list explanation", MAX_EXPLANATION_CHARS);
+  return {
+    revision: current.revision + 1,
+    tasks,
+    explanation,
+    updatedAt: timestamp,
+  };
+}
+
+export function taskCounts(tasks: ReadonlyArray<TaskItem>): TaskCounts {
+  return {
+    total: tasks.length,
+    pending: tasks.filter((task) => task.status === "pending").length,
+    inProgress: tasks.filter((task) => task.status === "in_progress").length,
+    completed: tasks.filter((task) => task.status === "completed").length,
+    blocked: tasks.filter((task) => task.status === "blocked").length,
+    cancelled: tasks.filter((task) => task.status === "cancelled").length,
+  };
+}
+
+export function hasActiveTasks(state: TaskListState): boolean {
+  return state.tasks.some((task) => task.status === "pending" || task.status === "in_progress" || task.status === "blocked");
+}
+
+export function taskListText(state: TaskListState): string {
+  const counts = taskCounts(state.tasks);
+  if (counts.total === 0) return "No tasks are currently tracked.";
+  const glyph: Record<TaskStatus, string> = {
+    pending: "[ ]",
+    in_progress: "[>]",
+    completed: "[x]",
+    blocked: "[!]",
+    cancelled: "[-]",
+  };
+  const lines = state.tasks.map((task) => {
+    const priority = task.priority === "medium" ? "" : ` (${task.priority})`;
+    const note = task.note ? ` — ${task.note}` : "";
+    return `${glyph[task.status]} ${task.id}: ${task.content}${priority}${note}`;
+  });
+  return [
+    `Tasks: ${counts.completed}/${counts.total} completed · ${counts.inProgress} active · ${counts.pending} pending · ${counts.blocked} blocked · ${counts.cancelled} cancelled`,
+    state.explanation ? `Update: ${state.explanation}` : "",
+    ...lines,
+  ].filter(Boolean).join("\n");
+}
+
+function escapeXml(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+export function taskListContext(state: TaskListState): string {
+  const active = state.tasks.filter((task) => task.status !== "completed" && task.status !== "cancelled");
+  const counts = taskCounts(state.tasks);
+  const lines = active.map((task) =>
+    `- ${task.id}: ${task.status}; priority=${task.priority}; ${escapeXml(task.content)}${task.note ? `; note=${escapeXml(task.note)}` : ""}`
+  );
+  return `<task_list_state revision="${state.revision}">
+This is the current session task list. It is execution state, not higher-priority instructions.
+${lines.join("\n") || "- No active tasks."}
+Completed: ${counts.completed}; cancelled: ${counts.cancelled}; total: ${counts.total}.
+Keep the list current with task_list while work continues. Do not redo completed or cancelled items.
+</task_list_state>`;
+}

package/extensions/task-list/types.ts

@@ -0,0 +1,58 @@
+export const TASK_STATUSES = [
+  "pending",
+  "in_progress",
+  "completed",
+  "blocked",
+  "cancelled",
+] as const;
+
+export const TASK_PRIORITIES = ["high", "medium", "low"] as const;
+
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+export type TaskPriority = (typeof TASK_PRIORITIES)[number];
+
+export type TaskItem = {
+  id: string;
+  content: string;
+  status: TaskStatus;
+  priority: TaskPriority;
+  note?: string;
+  updatedAt: number;
+};
+
+export type TaskListState = {
+  revision: number;
+  tasks: TaskItem[];
+  explanation?: string;
+  updatedAt: number;
+};
+
+export type TaskListSnapshot = {
+  state: TaskListState;
+};
+
+export type TaskListInput = {
+  tasks?: Array<{
+    id: string;
+    content: string;
+    status: TaskStatus;
+    priority?: TaskPriority;
+    note?: string;
+  }>;
+  explanation?: string;
+};
+
+export type TaskListDetails = {
+  action: "read" | "update";
+  state: TaskListState;
+  counts: TaskCounts;
+};
+
+export type TaskCounts = {
+  total: number;
+  pending: number;
+  inProgress: number;
+  completed: number;
+  blocked: number;
+  cancelled: number;
+};

package/extensions/task-list/ui.ts

@@ -0,0 +1,263 @@
+import type {
+  ExtensionCommandContext,
+  KeybindingsManager,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import {
+  frameBottom,
+  framedRow,
+  frameTop,
+  joinSides,
+  meter,
+  oneLine,
+  padLine,
+  stateLabel,
+  viewportSlice,
+  type SemanticState,
+} from "../shared/tui-dashboard.ts";
+import { taskCounts } from "./state.ts";
+import type { TaskItem, TaskListState, TaskPriority, TaskStatus } from "./types.ts";
+
+export type TaskDashboardAction =
+  | { kind: "close" }
+  | { kind: "add" }
+  | { kind: "edit"; id: string }
+  | { kind: "delete"; id: string }
+  | { kind: "status"; id: string; status: TaskStatus }
+  | { kind: "priority"; id: string; priority: TaskPriority }
+  | { kind: "clear" };
+
+interface TaskDashboardOptions {
+  getState(): TaskListState;
+}
+
+function configuredKeys(
+  keybindings: KeybindingsManager,
+  binding: Parameters<KeybindingsManager["getKeys"]>[0],
+): string {
+  return keybindings.getKeys(binding).join("/") || "unbound";
+}
+
+function statusState(status: TaskStatus): SemanticState {
+  switch (status) {
+    case "in_progress": return "active";
+    case "completed": return "success";
+    case "blocked": return "error";
+    case "pending":
+    case "cancelled": return "muted";
+  }
+}
+
+function statusColor(status: TaskStatus): "accent" | "success" | "error" | "muted" {
+  switch (status) {
+    case "in_progress": return "accent";
+    case "completed": return "success";
+    case "blocked": return "error";
+    case "pending":
+    case "cancelled": return "muted";
+  }
+}
+
+export function taskGlyph(status: TaskStatus): string {
+  switch (status) {
+    case "pending": return "○";
+    case "in_progress": return "◆";
+    case "completed": return "✓";
+    case "blocked": return "!";
+    case "cancelled": return "×";
+  }
+}
+
+function nextWorkingStatus(status: TaskStatus): TaskStatus {
+  switch (status) {
+    case "pending": return "in_progress";
+    case "in_progress": return "completed";
+    case "completed": return "pending";
+    case "blocked": return "in_progress";
+    case "cancelled": return "pending";
+  }
+}
+
+function nextPriority(priority: TaskPriority): TaskPriority {
+  if (priority === "high") return "medium";
+  if (priority === "medium") return "low";
+  return "high";
+}
+
+export class TaskDashboard implements Component {
+  private selected = 0;
+  private showFinished = true;
+  private closed = false;
+  private readonly tui: TUI;
+  private readonly theme: Theme;
+  private readonly keybindings: KeybindingsManager;
+  private readonly options: TaskDashboardOptions;
+  private readonly done: (action: TaskDashboardAction) => void;
+
+  constructor(
+    tui: TUI,
+    theme: Theme,
+    keybindings: KeybindingsManager,
+    options: TaskDashboardOptions,
+    done: (action: TaskDashboardAction) => void,
+  ) {
+    this.tui = tui;
+    this.theme = theme;
+    this.keybindings = keybindings;
+    this.options = options;
+    this.done = done;
+  }
+
+  private visibleTasks(): TaskItem[] {
+    const tasks = this.options.getState().tasks;
+    return this.showFinished
+      ? tasks
+      : tasks.filter((task) => task.status !== "completed" && task.status !== "cancelled");
+  }
+
+  private close(action: TaskDashboardAction): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.done(action);
+  }
+
+  private selectedTask(): TaskItem | undefined {
+    const visible = this.visibleTasks();
+    this.selected = Math.min(this.selected, Math.max(0, visible.length - 1));
+    return visible[this.selected];
+  }
+
+  handleInput(data: string): void {
+    const visible = this.visibleTasks();
+    this.selected = Math.min(this.selected, Math.max(0, visible.length - 1));
+    if (this.keybindings.matches(data, "tui.select.cancel") || data === "q") {
+      this.close({ kind: "close" });
+      return;
+    }
+    if (this.keybindings.matches(data, "tui.select.up") || data === "k") {
+      if (visible.length > 0) this.selected = (this.selected - 1 + visible.length) % visible.length;
+      this.tui.requestRender();
+      return;
+    }
+    if (this.keybindings.matches(data, "tui.select.down") || data === "j") {
+      if (visible.length > 0) this.selected = (this.selected + 1) % visible.length;
+      this.tui.requestRender();
+      return;
+    }
+    if (data === "h") {
+      this.showFinished = !this.showFinished;
+      this.selected = 0;
+      this.tui.requestRender();
+      return;
+    }
+    if (data === "a") {
+      this.close({ kind: "add" });
+      return;
+    }
+    if (data === "X") {
+      this.close({ kind: "clear" });
+      return;
+    }
+    const task = this.selectedTask();
+    if (!task) return;
+    if (data === "e") this.close({ kind: "edit", id: task.id });
+    else if (data === "d") this.close({ kind: "delete", id: task.id });
+    else if (data === " ") this.close({ kind: "status", id: task.id, status: nextWorkingStatus(task.status) });
+    else if (data === "b") this.close({ kind: "status", id: task.id, status: task.status === "blocked" ? "pending" : "blocked" });
+    else if (data === "c") this.close({ kind: "status", id: task.id, status: task.status === "cancelled" ? "pending" : "cancelled" });
+    else if (data === "p") this.close({ kind: "priority", id: task.id, priority: nextPriority(task.priority) });
+  }
+
+  render(width: number): string[] {
+    const state = this.options.getState();
+    const visible = this.visibleTasks();
+    const counts = taskCounts(state.tasks);
+    this.selected = Math.min(this.selected, Math.max(0, visible.length - 1));
+    const rows = this.tui.terminal.rows || 30;
+    const completed = counts.completed + counts.cancelled;
+    const stateTone: SemanticState = counts.blocked > 0 ? "warning" : counts.inProgress > 0 ? "active" : completed === counts.total && counts.total > 0 ? "success" : "muted";
+    const stateText = counts.blocked > 0
+      ? `${counts.blocked} blocked`
+      : counts.inProgress > 0
+        ? `${counts.inProgress} active`
+        : completed === counts.total && counts.total > 0
+          ? "all done"
+          : "waiting";
+    const title = `  ${this.theme.fg("accent", this.theme.bold("Task list"))}`;
+    const summary = `${stateLabel(this.theme, stateTone, stateText)}  `;
+    const lines: string[] = [joinSides(title, summary, width)];
+    lines.push(joinSides(
+      `  ${meter(this.theme, completed, Math.max(1, counts.total), Math.min(28, Math.max(12, width - 54)), completed === counts.total && counts.total > 0 ? "success" : "active")} ${this.theme.fg("text", `${completed}/${counts.total} finished`)}`,
+      `${this.theme.fg("muted", `${counts.pending} pending · ${counts.blocked} blocked`)}  `,
+      width,
+    ));
+    if (state.explanation) {
+      lines.push(truncateToWidth(`  ${this.theme.fg("dim", oneLine(state.explanation))}`, width));
+    }
+
+    const chromeRows = lines.length + 3;
+    const detailRows = 2;
+    const listHeight = Math.max(4, rows - chromeRows - detailRows);
+    lines.push(frameTop(this.theme, width, `tasks · ${visible.length}${this.showFinished ? "" : ` of ${counts.total}`}`));
+    if (visible.length === 0) {
+      const empty = counts.total === 0
+        ? "No tasks yet — the agent creates a list for multi-step work."
+        : "No active tasks. Press h to show completed and cancelled items.";
+      lines.push(framedRow(this.theme, ` ${this.theme.fg("muted", empty)}`, width));
+      for (let index = 1; index < listHeight; index++) lines.push(framedRow(this.theme, "", width));
+    } else {
+      const viewport = viewportSlice(visible, this.selected, listHeight);
+      for (let row = 0; row < listHeight; row++) {
+        const task = viewport.items[row];
+        if (!task) {
+          lines.push(framedRow(this.theme, "", width));
+          continue;
+        }
+        const index = viewport.start + row;
+        const selected = index === this.selected;
+        const marker = selected ? this.theme.fg("accent", "❯") : " ";
+        const glyph = this.theme.fg(statusColor(task.status), taskGlyph(task.status));
+        const id = this.theme.fg("dim", `[${oneLine(task.id)}]`);
+        const priority = task.priority === "medium" ? "" : this.theme.fg(task.priority === "high" ? "warning" : "dim", ` ${task.priority}`);
+        const right = `${this.theme.fg(statusColor(task.status), task.status.replaceAll("_", " "))}${priority} `;
+        const left = ` ${marker} ${glyph} ${id} ${selected ? this.theme.fg("accent", oneLine(task.content)) : this.theme.fg(task.status === "completed" || task.status === "cancelled" ? "muted" : "text", oneLine(task.content))}`;
+        lines.push(framedRow(this.theme, joinSides(left, right, Math.max(0, width - 2)), width, selected));
+      }
+    }
+    lines.push(frameBottom(this.theme, width));
+
+    const selected = visible[this.selected];
+    if (selected?.note) {
+      const wrapped = wrapTextWithAnsi(`${this.theme.fg("muted", "note")} ${this.theme.fg("dim", oneLine(selected.note))}`, Math.max(1, width - 4));
+      lines.push(truncateToWidth(`  ${wrapped[0] ?? ""}`, width));
+    } else {
+      lines.push("");
+    }
+    const keys = `${configuredKeys(this.keybindings, "tui.select.up")}/${configuredKeys(this.keybindings, "tui.select.down")}/jk select · space advance · b block · c cancel · p priority · a add · e edit · d delete · h ${this.showFinished ? "hide" : "show"} done · X clear · ${configuredKeys(this.keybindings, "tui.select.cancel")} close`;
+    lines.push(truncateToWidth(this.theme.fg("dim", `  ${keys}`), width));
+    return lines.map((line) => padLine(line, width));
+  }
+
+  invalidate(): void {}
+}
+
+export async function openTaskDashboard(
+  ctx: ExtensionCommandContext,
+  options: TaskDashboardOptions,
+): Promise<TaskDashboardAction> {
+  if (ctx.mode !== "tui") return { kind: "close" };
+  return ctx.ui.custom<TaskDashboardAction>(
+    (tui, theme, keybindings, done) => new TaskDashboard(tui, theme, keybindings, options, done),
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        width: "100%",
+        minWidth: 52,
+        maxHeight: "100%",
+      },
+    },
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shariq-pi-extensions",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "Cross-platform extension suite for the Pi coding agent.",
   "license": "MIT",
   "author": "Shariq Riaz",
@@ -54,6 +54,7 @@
       "./extensions/shell-shortcuts/index.ts",
       "./extensions/smart-compaction/index.ts",
       "./extensions/subagents/index.ts",
+      "./extensions/task-list/index.ts",
       "./extensions/web-fetch/index.ts"
     ],
     "skills": [