@nguyenquangthai/pi-todo 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.3.3 (2026-07-16)
+
+### Changed
+
+- **Overlay heading**: Shows open, running, and completed counts. Completed
+  counts include only `completed` todos; `cancelled` todos remain excluded.
+- **Simplified status display**: Removed the ANSI progress bar and `done/total`
+  counter from the overlay.
+- **Documentation and screenshot**: Updated the README, screenshot PNG, and
+  screenshot HTML source to match the new heading.
+
+## 0.3.2 (2026-07-16)
+
+### Fixed
+
+- **Todo ID integrity**: Prevented id-less todos from taking IDs explicitly
+  retained by another todo during a full `todo_write` replacement.
+- **Diagnostics**: Added ID-integrity reporting and `repair_needed` status to
+  `todo_diagnose`.
+- **Mutation bounds**: Capped todo mutations and persisted snapshots at 200
+  items.
+
 ## 0.3.1 (2026-07-15)
 
 ### Fixed

package/README.md

@@ -46,12 +46,18 @@ Rules enforced by the tool:
 - `content` required (non-empty after sanitize); max **500** chars (longer values truncated)
 - `priority` required: `high` | `medium` | `low`
 - Status: `pending` | `in_progress` | `completed` | `cancelled`
+- **ID rule:** omit `id` for a new item; the system assigns it. Only include an ID returned by `todo_read` when retaining an existing item. Never invent an ID. Replacing the list does not inherently reset IDs: matching existing items can retain them.
+- For changed, repeated, or long/truncated content, include the exact existing ID rather than relying on automatic content matching.
+- Do not call `todo_write` and a `todo_update` that needs its IDs in the same parallel batch. Wait for the write result, then use returned IDs or call `todo_read`.
+- A mutation can contain at most **200** todos/updates.
 - Array order is the workflow timeline. Keep existing positions when statuses change; only add or reorder items intentionally.
 - Tool text echo caps at **40** lines (`+N more` in the text body; full list still in `details` / JSON)
 
 ### `todo_update`
 
-Patch existing todos by stable ID without replacing the list or changing its order. Use `todo_read` first to obtain IDs; this tool never deletes items.
+Patch existing todos by stable ID without replacing the list or changing its order. `id` is required, must be a non-empty string, and must match a current todo; use `todo_read` first to obtain it. This tool never deletes items.
+
+If an older session returns a todo without `id`, it cannot be patched with `todo_update`. Call `todo_write` with that item but omit `id` to assign one, then use `todo_update` normally.
 
 ```json
 {
@@ -67,7 +73,7 @@ Returns the current list as text + JSON. Prefer the overlay for at-a-glance stat
 
 ### `todo_diagnose`
 
-Read-only persistence check for suspected reload, tree-navigation, or compaction drift. It compares the live in-memory snapshot against a replay of the durable session branch and reports `consistent` or `mismatch`; it never changes todos.
+Read-only persistence check for suspected reload, tree-navigation, or compaction drift. It compares the live in-memory snapshot against a replay of the durable session branch and reports `consistent`, `mismatch`, or `repair_needed` when duplicate/missing IDs are found; it never changes todos.
 
 ## Overlay
 
@@ -75,12 +81,12 @@ Shown above the editor while any **open** todo remains (`pending` / `in_progress
 
 Hidden when the list is empty or every item is `completed` / `cancelled`.
 
-Heading shows open + running counts + background-color progress bar, e.g. `# Todos (3 open, 1 running) ▓▓▓▓░░░░ 1/4`:
-
-- **open** = `pending` + `in_progress`
-- **running** = `in_progress` only (0 or 1 after a valid write)
-- **progress bar** = ANSI background color via reverse video, using theme `accent` (filled) and `muted` (empty)
-
+Heading shows open, running, and completed counts, e.g. `# Todos (3 open, 1 running, 1 completed)`:
+
+- **open** = `pending` + `in_progress`
+- **running** = `in_progress` only (0 or 1 after a valid write)
+- **completed** = `completed` only; `cancelled` todos are not counted
+
 Items always stay in the array's workflow order; status changes only their marker/color.
 When space is tight, the overlay shows the earliest checklist items and `+N more`. If the active item is outside that prefix, it is repeated as `Active: [•] …` rather than moved ahead of earlier work.
 A blank line separates the heading from the first todo row for visual breathing room.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nguyenquangthai/pi-todo",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "OpenCode-like session todo checklist for the pi coding agent — todowrite/todoread with a live TUI overlay",
   "type": "module",
   "author": "QuangThai",

package/src/format.ts

@@ -2,7 +2,7 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { TodoItem, TodoStatus } from "./types.js";
 import { MAX_OVERLAY_LINES, MAX_RESULT_LINES } from "./types.js";
-import { countOpenTodos, countRunningTodos, hasOpenTodos } from "./validate.js";
+import { countCompletedTodos, countOpenTodos, countRunningTodos, hasOpenTodos } from "./validate.js";
 
 
 export function getTodoMarker(status: TodoStatus): string {
@@ -107,13 +107,9 @@ export interface RenderOverlayOptions {
   maxLines?: number;
 }
 
-/**
- * Heading counts (when overlay is visible):
- * - open    = pending + in_progress
- * - running = in_progress only (0 or 1 after a valid todo_write)
- * Overlay is hidden when open === 0, so "(0 open, 0 running)" is never shown.
- * Includes a background-color progress bar using theme colors.
- */
+/**
+ * The overlay is hidden when no work remains open.
+ */
 export function renderOverlayLines(
   todos: readonly TodoItem[],
   theme: Theme,
@@ -123,27 +119,15 @@ export function renderOverlayLines(
   if (!shouldShowOverlay(todos)) return [];
 
   const maxLines = Math.max(1, options.maxLines ?? MAX_OVERLAY_LINES);
-  const truncate = (line: string) => truncateToWidth(line, width, "…");
-  const open = countOpenTodos(todos);
-  const running = countRunningTodos(todos);
-
-  // Background-color progress bar via reverse video — uses theme accent/dim
-  const total = todos.length;
-  const done = total - open;
-  const barWidth = Math.max(4, Math.min(10, Math.floor(width / 8)));
-  const filled = Math.round((barWidth * done) / total);
-  const REV = "\x1b[7m";
-  const filledBar = REV + theme.fg("accent", " ".repeat(filled));
-  const emptyBar =
-    filled < barWidth ? REV + theme.fg("muted", " ".repeat(barWidth - filled)) : "";
-  const bar = filledBar + emptyBar + "\x1b[0m";
-
-  const heading = truncate(
-    theme.fg("accent", theme.bold(`# Todos`)) +
-      theme.fg("dim", ` (${open} open, ${running} running)`) +
-      ` ${bar}` + theme.fg("dim", ` ${done}/${total}`),
-  );
-
+  const truncate = (line: string) => truncateToWidth(line, width, "…");
+  const open = countOpenTodos(todos);
+  const running = countRunningTodos(todos);
+  const completed = countCompletedTodos(todos);
+  const heading = truncate(
+    theme.fg("accent", theme.bold("# Todos")) +
+      theme.fg("dim", ` (${open} open, ${running} running, ${completed} completed)`),
+  );
+
   // Small gap between heading and first row — budget -1 to account for the blank line
   const layout = selectOverlayLayout(todos, Math.max(3, maxLines - 1));
   const lines: string[] = [heading, ""];

package/src/prompt.ts

@@ -32,6 +32,8 @@ Do **not** skip just because the request is "explain" or "review" — if the ans
 ## Rules
 
 - Each call **REPLACES** the entire list (full replace). Always pass the complete todos array.
+  - **ID rule:** omit \`id\` for every new item — the system assigns it. Only preserve an \`id\` returned by \`todo_read\` for an item that already exists; never invent an ID. For changed, repeated, or long/truncated content, preserve the exact existing ID instead of relying on content matching. Full replacement does not inherently reset IDs: matching existing items can retain them.
+  - Do not call \`todo_write\` and a dependent \`todo_update\` in the same parallel batch. Complete the write, then use its returned IDs (or \`todo_read\`) for the update.
 - Update status in real time; don't batch completions across multiple finished steps.
 - Mark \`completed\` only after the work is actually done (including verification) — never on intent alone.
 - Keep exactly one \`in_progress\` while actively working. Never leave a stale \`in_progress\` after that step is finished.
@@ -43,7 +45,7 @@ Do **not** skip just because the request is "explain" or "review" — if the ans
 - Prefer the live overlay for status; use todo_read only when you need the JSON snapshot.`;
 
 export const TODOREAD_DESCRIPTION =
-  "Read the current session todo list. Returns JSON of all todos with status and priority. Prefer the overlay for at-a-glance status; call after todo_write settles (not in the same parallel batch).";
+  "Read the current session todo list. Returns JSON of all todos with status, priority, and stable IDs. Prefer the overlay for at-a-glance status; call after todo_write settles (not in the same parallel batch). A legacy item without an ID cannot be patched by todo_update; rewrite it with todo_write and omit id to assign one.";
 
 export const TODODIAGNOSE_DESCRIPTION =
   "Read-only persistence diagnostic. Compares the current in-memory todo snapshot with the durable session-branch replay. Use only to investigate suspected reload, tree-navigation, or compaction state drift; it never changes todos.";
@@ -51,6 +53,8 @@ export const TODODIAGNOSE_DESCRIPTION =
 export const TODOWRITE_GUIDELINES = [
   "For multi-step work (3+ steps), codebase explain/explore/review, or when the user gives a list of tasks, call todo_write BEFORE starting — do not skip tracking.",
   "Pass the full list every todo_write call (full replace). Keep exactly one todo in_progress; mark completed immediately when a step finishes — never leave a stale in_progress.",
+  "ID rule: for todo_write, omit id for new items so the system assigns one. Supply an id only to preserve an existing item, using the exact ID from todo_read; never invent IDs. For changed, repeated, or long/truncated content, preserve that exact ID rather than relying on content matching. For todo_update, id is required and must match a current todo.",
+  "Never call todo_write and a todo_update that depends on its IDs in the same parallel batch. Wait for todo_write to finish, then use its returned IDs or call todo_read. If todo_read shows a legacy item without id, rewrite it with todo_write and omit id to assign one before using todo_update.",
   "When finishing a step or when the user confirms done, use todo_update for an ID-based patch when possible; use todo_write only when replacing the full checklist. Advance the next pending item in the same mutation if work continues.",
   "Treat todo array order as the workflow timeline: preserve positions when updating statuses, and only add or reorder items intentionally.",
   "Use todo_write for full replacement and todo_update for ID-based patches; todo_read exposes IDs and todo_diagnose is read-only troubleshooting.",
@@ -64,7 +68,7 @@ export const TODOWRITE_GUIDELINES = [
  */
 export const TASK_MANAGEMENT_SECTION = `
 <Task_Management>
-todo_write/todo_update/todo_read are the coordination layer for multi-step work. Use todo_write for the initial/full checklist and todo_update for a targeted patch by stable ID. The TUI overlay only appears after a todo mutation — without it the user cannot see plan/progress.
+todo_write/todo_update/todo_read are the coordination layer for multi-step work. Use todo_write for the initial/full checklist and todo_update for a targeted patch by stable ID. In todo_write, omit id for new items; only retain an exact ID returned by todo_read for an existing item. In todo_update, id is required and must match a current todo. Do not call a write and an update that depends on its IDs in the same parallel batch: wait for the write result first. The TUI overlay only appears after a todo mutation — without it the user cannot see plan/progress.
 
 Required cold start: for explain/explore/review/implement/refactor/audit/debug/fix/polish/setup of a codebase, feature, UI, or multi-file ask — your FIRST tool call must be todo_write with a short checklist (WHAT/WHERE), exactly one in_progress, then continue. Do not start with read/bash/search alone on those asks.
 

package/src/schema.ts

@@ -1,9 +1,9 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
-import { TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
+import { MAX_TODO_ITEMS, TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
 
 export const TodoItemSchema = Type.Object({
-  id: Type.Optional(Type.String({ minLength: 1, description: "Stable todo ID; preserve it when rewriting an existing item" })),
+  id: Type.Optional(Type.String({ minLength: 1, description: "Stable ID of an existing todo. Omit for new items; never invent an ID. Preserve only an ID returned by todo_read/current list." })),
   content: Type.String({ description: "Brief description of the task" }),
   status: StringEnum([...TODO_STATUSES], {
     description: "pending | in_progress | completed | cancelled",
@@ -14,8 +14,9 @@ export const TodoItemSchema = Type.Object({
 });
 
 export const TodoWriteParams = Type.Object({
-  todos: Type.Array(TodoItemSchema, {
-    description: "The complete updated todo list (full replace)",
+  todos: Type.Array(TodoItemSchema, {
+    maxItems: MAX_TODO_ITEMS,
+    description: `The complete updated todo list (full replace, at most ${MAX_TODO_ITEMS} items). Any supplied ID must already exist; omit ID for a new item.`,
   }),
 });
 
@@ -27,12 +28,12 @@ export const TodoDiagnoseParams = Type.Object({});
 export const TodoUpdateParams = Type.Object({
   updates: Type.Array(
     Type.Object({
-      id: Type.String({ minLength: 1 }),
+      id: Type.String({ minLength: 1, description: "Existing stable ID from todo_read; it must match a current todo" }),
       content: Type.Optional(Type.String()),
       status: Type.Optional(StringEnum([...TODO_STATUSES])),
       priority: Type.Optional(StringEnum([...TODO_PRIORITIES])),
     }),
-    { minItems: 1, description: "Patch existing todos by stable ID" },
+      { minItems: 1, maxItems: MAX_TODO_ITEMS, description: `Patch at most ${MAX_TODO_ITEMS} existing todos by stable ID` },
   ),
 });
 

package/src/tools/tododiagnose.ts

@@ -6,12 +6,13 @@ import { TodoDiagnoseParams } from "../schema.js";
 import { getTodos, withStoreLock } from "../store.js";
 import type { TodoItem } from "../types.js";
 import { TOOL_DIAGNOSE } from "../types.js";
-import { todosEqual } from "../validate.js";
+import { getTodoIntegrityIssues, todosEqual } from "../validate.js";
 
 interface TodoDiagnoseDetails {
-  status: "consistent" | "mismatch";
+  status: "consistent" | "mismatch" | "repair_needed";
   storeTodos: TodoItem[];
   replayedTodos: TodoItem[];
+  integrityIssues: string[];
 }
 
 /** Registers a read-only comparison between live state and durable branch replay. */
@@ -27,12 +28,20 @@ export function registerTodoDiagnoseTool(pi: ExtensionAPI): void {
       return withStoreLock(() => {
         const storeTodos = getTodos();
         const replayedTodos = replayFromBranch(ctx);
-        const status = todosEqual(storeTodos, replayedTodos) ? "consistent" : "mismatch";
-        const details: TodoDiagnoseDetails = { status, storeTodos, replayedTodos };
-        const text =
-          status === "consistent"
-            ? "Persistence check: consistent — current todo snapshot matches durable branch replay."
-            : "Persistence check: MISMATCH — current todo snapshot differs from durable branch replay. No state was changed.";
+          const integrityIssues = [
+            ...getTodoIntegrityIssues(storeTodos).map((issue) => `current: ${issue}`),
+            ...getTodoIntegrityIssues(replayedTodos).map((issue) => `durable: ${issue}`),
+          ];
+          const status = integrityIssues.length > 0
+            ? "repair_needed"
+            : todosEqual(storeTodos, replayedTodos) ? "consistent" : "mismatch";
+          const details: TodoDiagnoseDetails = { status, storeTodos, replayedTodos, integrityIssues };
+          const text =
+            status === "consistent"
+              ? "Persistence check: consistent — current todo snapshot matches durable branch replay."
+              : status === "repair_needed"
+                ? "Integrity check: REPAIR NEEDED — duplicate or missing IDs were found. Use todo_write with the complete list and omit ID for each affected item; no state was changed."
+              : "Persistence check: MISMATCH — current todo snapshot differs from durable branch replay. No state was changed.";
 
         return {
           content: [{ type: "text", text: `${text}\n\n${JSON.stringify(details, null, 2)}` }],
@@ -47,7 +56,7 @@ export function registerTodoDiagnoseTool(pi: ExtensionAPI): void {
 
     renderResult(result, _opts, theme) {
       const details = result.details as TodoDiagnoseDetails | undefined;
-      const text = details?.status === "consistent" ? "✓ Consistent" : "! Mismatch";
+        const text = details?.status === "consistent" ? "✓ Consistent" : details?.status === "repair_needed" ? "! Repair needed" : "! Mismatch";
       const color = details?.status === "consistent" ? "success" : "warning";
       return new Text(theme.fg(color, text), 0, 0);
     },

package/src/types.ts

@@ -29,5 +29,7 @@ export const WIDGET_KEY = "pi-todo";
 export const MAX_OVERLAY_LINES = 12;
 /** Max characters per todo content after sanitize (context/tool safety). */
 export const MAX_CONTENT_LENGTH = 500;
+/** Bound mutation payloads and persisted snapshots to keep tool context manageable. */
+export const MAX_TODO_ITEMS = 200;
 /** Max todo lines echoed in todowrite/todoread text (full list still in details/JSON). */
 export const MAX_RESULT_LINES = 40;

package/src/validate.ts

@@ -1,7 +1,7 @@
 import { sanitizeTodoText } from "./sanitize.js";
 import { randomUUID } from "node:crypto";
 import type { TodoItem, TodoPriority, TodoStatus } from "./types.js";
-import { MAX_CONTENT_LENGTH, TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
+import { MAX_CONTENT_LENGTH, MAX_TODO_ITEMS, TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
 
 export type ValidateOk = { ok: true; todos: TodoItem[]; unchanged: boolean };
 export type ValidateErr = { ok: false; error: string };
@@ -34,6 +34,9 @@ export function validateTodoWrite(
   if (!Array.isArray(rawTodos)) {
     return { ok: false, error: "todos must be an array" };
   }
+  if (rawTodos.length > MAX_TODO_ITEMS) {
+    return { ok: false, error: `todos must contain at most ${MAX_TODO_ITEMS} items` };
+  }
 
   const todos: TodoItem[] = [];
   let inProgressCount = 0;
@@ -110,11 +113,16 @@ export function validateTodoWrite(
  *
  * - Items with an explicit `id` keep it (must already exist in `current`, verified
  *   by `validateTodoWrite`).
+ * - Explicit IDs are reserved before matching so an id-less item cannot claim
+ *   an ID that another incoming item explicitly preserves.
  * - Items without `id` try to match a prior item: first by full tuple
  *   (content+status+priority), then by unique content.  If ambiguous (multiple
  *   same-content items) or no prior match, a new UUID is generated.
  */
 export function ensureTodoIds(todos: readonly TodoItem[], current: readonly TodoItem[]): TodoItem[] {
+  // Reserve every explicit ID up front. Incoming order must not decide whether an
+  // id-less item steals an ID that a later item explicitly retains.
+  const reserved = new Set(todos.flatMap((todo) => todo.id ? [todo.id] : []));
   const claimed = new Set<string>();
 
   // Pre-index content uniqueness: content that appears only once in `current`
@@ -129,7 +137,7 @@ export function ensureTodoIds(todos: readonly TodoItem[], current: readonly Todo
     if (!id) {
       // 1. Exact tuple match (content + status + priority)
       const byTuple = current.find(
-        (c) => !!c.id && !claimed.has(c.id) &&
+          (c) => !!c.id && !reserved.has(c.id) && !claimed.has(c.id) &&
           c.content === todo.content &&
           c.status === todo.status &&
           c.priority === todo.priority,
@@ -141,23 +149,44 @@ export function ensureTodoIds(todos: readonly TodoItem[], current: readonly Todo
         const count = contentCounts.get(todo.content) ?? 0;
         if (count === 1) {
           const byContent = current.find(
-            (c) => !!c.id && !claimed.has(c.id) && c.content === todo.content,
+              (c) => !!c.id && !reserved.has(c.id) && !claimed.has(c.id) && c.content === todo.content,
           );
           if (byContent) id = byContent.id;
         }
       }
       // 3. No match or ambiguous → fresh ID
-      if (!id) id = randomUUID();
+        if (!id) {
+          do id = randomUUID(); while (reserved.has(id) || claimed.has(id));
+        }
     }
     claimed.add(id);
     return { ...todo, id };
   });
 }
 
+/** Report persisted-state identity problems without mutating legacy snapshots. */
+export function getTodoIntegrityIssues(todos: readonly TodoItem[]): string[] {
+  const issues: string[] = [];
+  const seen = new Set<string>();
+  for (let i = 0; i < todos.length; i++) {
+    const id = todos[i].id;
+    if (typeof id !== "string" || !id.trim()) {
+      issues.push(`todos[${i}] has no stable ID`);
+      continue;
+    }
+    if (seen.has(id)) issues.push(`todos[${i}].id "${id}" is duplicated`);
+    seen.add(id);
+  }
+  return issues;
+}
+
 export function validateTodoUpdate(rawUpdates: unknown, current: readonly TodoItem[]): ValidateResult {
   if (!Array.isArray(rawUpdates) || rawUpdates.length === 0) {
     return { ok: false, error: "updates must be a non-empty array" };
   }
+  if (rawUpdates.length > MAX_TODO_ITEMS) {
+    return { ok: false, error: `updates must contain at most ${MAX_TODO_ITEMS} items` };
+  }
   const next = current.map((todo) => ({ ...todo }));
   const seen = new Set<string>();
   for (let i = 0; i < rawUpdates.length; i++) {
@@ -199,3 +228,8 @@ export function countOpenTodos(todos: readonly TodoItem[]): number {
 export function countRunningTodos(todos: readonly TodoItem[]): number {
   return todos.filter((t) => t.status === "in_progress").length;
 }
+
+/** Count successfully finished items; cancelled items are intentionally excluded. */
+export function countCompletedTodos(todos: readonly TodoItem[]): number {
+  return todos.filter((todo) => todo.status === "completed").length;
+}