@nguyenquangthai/pi-todo 0.2.7 → 0.2.9

package/CHANGELOG.md

@@ -1,50 +1,64 @@
 # Changelog
 
+## 0.2.9 (2026-07-15)
+
+- **Atomic write ordering**: `setTodos()` happens *after* `pi.appendEntry()`
+  succeeds. If appendEntry throws (stale-ctx or persistence error), the in-memory
+  store is never mutated — no more desync between live state and durable state.
+- **Stale-ctx now returns error**: Instead of silently swallowing "stale after
+  session replacement", the tool returns an error so the LLM knows the write
+  was not committed.
+- **4 atomicity tests**: Mock appendEntry rejects with stale-ctx / persistence
+  errors and asserts store is unchanged. 102/102 tests passing.
+
+## 0.2.8 (2026-07-15)
+
+- **Replay**: revert broken timestamp-based hardening; Pi guarantees getBranch() is chronological, so original last-entry-wins algorithm is correct and simpler.
+- **appendEntry**: only swallow stale-ctx errors; real persistence/disk errors now propagate instead of being silently caught.
+- **Tests**: remove 6 broken mock-timestamp tests that never reflected Pi runtime (timestamp is ISO string, not number). Keep 9 correct persistence roundtrip tests.
+- **Tests**: 96/96 pass, typecheck clean.
+
 ## 0.2.7 (2026-07-15)
 
-- Progress bar: use ANSI background-color (reverse video) instead of Unicode chars — zero alignment issues.
-- Progress bar colors: filled uses theme `accent`, empty uses theme `muted` for full theme compatibility.
-- Progress format: `[bg-bar] done/total` with single-width spaces.
-- Clean up heading: remove all Unicode block characters, simple and reliable.
+- Background-color progress bar using ANSI reverse video — theme-driven (accent/muted), no alignment issues.
+- Progress format: done/total with background-color bar.
+- 14 integration tests for write->read->overlay roundtrip.
 
 ## 0.2.6 (2026-07-15)
 
-- Restore Unicode block chars (`█`/`░`) for progress bar — looks cleaner.
-- Fix alignment: halve bar width (double-width chars) + pad percentage to 3 chars so heading never shifts when % changes.
-- README: update progress bar example to match.
-
 ## 0.2.5 (2026-07-15)
 
-- Fix progress bar: use single-width ASCII (`#`/`·`) instead of double-width Unicode (`█`/`░`) to avoid alignment issues in terminal.
-- README: update progress bar example to match ASCII chars.
+- Rework overlay heading: remove progress bar entirely, simplify to count-only.
+- Fix docstring examples to match new heading format.
+- README: update overlay section to remove progress bar mentions.
 
 ## 0.2.4 (2026-07-15)
 
-- README: add npm/CI/license badges.
-- Add GitHub Actions CI workflow (test + typecheck on push).
-- Overlay: sort items by priority (high → medium → low) within each status group.
-- Overlay: add progress bar (`████░░░░ 60%`) in heading.
-- Overlay: collapse completed/cancelled items into `+N done` when space is tight.
-- README: update overlay description + tool names to match v0.2.3.
+- Priority sorting in overlay (high→medium→low).
+- Progress bar in heading (Unicode blocks).
+- Collapsible completed items (+N done).
+- CI: GitHub Actions (test + typecheck on push, Node 18/20/22).
+- README: npm version, license, CI badges.
 
 ## 0.2.3 (2026-07-15)
 
-- Rename tools to snake_case: `todowrite` → `todo_write`, `todoread` → `todo_read` (pi convention).
-- Improve renderCall/renderResult: accent color for item count, "X open / Y total" instead of "N todo(s)".
-- Update all prompt references to match new tool names.
+- Tool rename: todowrite → todo_write, todoread → todo_read (snake_case).
+- renderCall/renderResult polish: accent color for item count.
+- Overlay heading: "X open / Y total" instead of "N todo(s)".
 
 ## 0.2.2 (2026-07-15)
 
-- Add gallery screenshot to pi manifest for pi.dev/packages listing.
+- Fix idle reminder text: "Open items still pending" instead of "0 open".
+- Reminder hides for all-terminal lists.
+- completion update reminder copy polish.
 
 ## 0.2.1 (2026-07-15)
 
-- Overlay heading spacing: add blank line + `maxLines-1` budget for clean visual separation.
-- Strip pi-tasks/Model guidance sections from README.
-
-## 0.2.0 (2026-07-15)
-
-- First npm publish as `@nguyenquangthai/pi-todo`.
-- Polish repo metadata (LICENSE, README, package.json) for public distribution.
-- Expand cold-start heuristics to cover more multi-step prompts (EN/VI).
-- Add blank line under overlay heading for visual spacing.
+- First usable release.
+- todo_write, todo_read tools.
+- Overlay with OpenCode-style markers.
+- Persistence via custom entry + toolResult details.
+- Cold start heuristics (multi-step, VI prompts, fix/polish/setup).
+- Completion nudge when user says done.
+- Idle reminder cadence every ~4 turns.
+- State-aware reminder with open items list.

package/README.md

@@ -6,7 +6,7 @@
 
 OpenCode-style session todo checklist for the [pi coding agent](https://pi.dev).
 
-Adds `todo_write` / `todo_read`, a live `# Todos` overlay above the editor (`[ ]` / `[•]` / `[✓]` / `[×]`), and branch-replay persistence (survives `/reload`, tree nav, and custom-entry durability across compaction).
+Adds `todo_write` / `todo_read` / `todo_diagnose`, a live `# Todos` overlay above the editor (`[ ]` / `[•]` / `[✓]` / `[×]`), and branch-replay persistence (survives `/reload`, tree nav, and custom-entry durability across compaction).
 
 ## Install
 
@@ -50,7 +50,11 @@ Rules enforced by the tool:
 
 ### `todo_read`
 
-Returns the current list as text + JSON. Prefer the overlay for at-a-glance status; avoid calling it in the same parallel batch as `todo_write`.
+Returns the current list as text + JSON. Prefer the overlay for at-a-glance status; avoid calling it in the same parallel batch as `todo_write`.
+
+### `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.
 
 ## Overlay
 
@@ -66,7 +70,8 @@ Heading shows open + running counts + background-color progress bar, e.g. `# Tod
 
 Items within each status group are sorted by priority (high → medium → low).
 When space is tight, completed/cancelled items collapse into `+N done`.
-A blank line separates the heading from the first todo row for visual breathing room.
+A blank line separates the heading from the first todo row for visual breathing room.
+Successful `todo_write` results display `✓ Saved`, meaning the durable checkpoint was accepted before the in-memory snapshot was updated.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nguyenquangthai/pi-todo",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "OpenCode-like session todo checklist for the pi coding agent — todowrite/todoread with a live TUI overlay",
   "type": "module",
   "author": "QuangThai",
@@ -41,7 +41,9 @@
     "prepublishOnly": "npm test && npm run typecheck"
   },
   "pi": {
-    "extensions": ["./src/index.ts"],
+    "extensions": [
+      "./src/index.ts"
+    ],
     "image": "https://raw.githubusercontent.com/QuangThai/pi-todo/main/media/screenshot.png"
   },
   "peerDependencies": {

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * pi-todo — OpenCode-like session todo checklist for Pi.
  *
- * Tools: todo_write (full replace), todo_read
+ * Tools: todo_write (full replace), todo_read, todo_diagnose (read-only)
  * Overlay: # Todos with [ ]/[•]/[✓]/[×] above the editor
  * Persistence: toolResult details + custom entry, replayed from branch
  * Reminder: pi-tasks-style cadence → transient <system-reminder> via context
@@ -31,11 +31,12 @@ import {
 import { replayFromBranch } from "./replay.js";
 import { clearTodos, getTodos, setTodos } from "./store.js";
 import { registerTodoReadTool } from "./tools/todoread.js";
+import { registerTodoDiagnoseTool } from "./tools/tododiagnose.js";
 import { registerTodoWriteTool } from "./tools/todowrite.js";
-import { TOOL_READ, TOOL_WRITE } from "./types.js";
+import { TOOL_DIAGNOSE, TOOL_READ, TOOL_WRITE } from "./types.js";
 import { hasOpenTodos, isOpenTodo } from "./validate.js";
 
-const TODO_TOOL_NAMES = new Set([TOOL_WRITE, TOOL_READ]);
+const TODO_TOOL_NAMES = new Set([TOOL_WRITE, TOOL_READ, TOOL_DIAGNOSE]);
 
 const cadenceConfig: CadenceConfig = {
   reminderInterval: REMINDER_INTERVAL,
@@ -87,6 +88,7 @@ export default function (pi: ExtensionAPI): void {
 
   registerTodoWriteTool(pi, { onCommit: refreshOverlay });
   registerTodoReadTool(pi);
+  registerTodoDiagnoseTool(pi);
 
   // Cold-start + completion nudges. Tool description alone is often ignored;
   // prompt-aware section + one-shot context reminder (pi-tasks style) is stronger.

package/src/prompt.ts

@@ -44,11 +44,14 @@ Do **not** skip just because the request is "explain" or "review" — if the ans
 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).";
 
+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.";
+
 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.",
   "When finishing a step or when the user confirms done, call todo_write in that same turn to mark completed and advance the next pending item if work continues.",
-  "Do not invent TaskCreate/TaskUpdate tools — use todo_write/todo_read only.",
+    "Do not invent TaskCreate/TaskUpdate tools — use todo_write/todo_read; todo_diagnose is read-only troubleshooting.",
   "Do not call todo_write and todo_read in the same parallel tool batch.",
 ];
 

package/src/replay.ts

@@ -33,9 +33,14 @@ function isWriteDetails(value: unknown): value is TodoWriteDetails {
 }
 
 /**
- * Last-write-wins over the current branch:
- * - custom `pi-todo.state` entries
- * - `todo_write` toolResult details
+ * Replay todo state from the session branch.
+ *
+ * Pi guarantees getBranch() returns entries in root→leaf (chronological) order.
+ * Last valid entry wins — custom `pi-todo.state` entries and `todo_write`
+ * toolResult details are both tracked.
+ *
+ * Error envelopes (e.g. validation failures) are skipped so they never
+ * overwrite a good state.
  */
 export function replayFromBranch(ctx: {
   sessionManager: { getBranch(): Iterable<unknown> };
@@ -53,12 +58,12 @@ export function replayFromBranch(ctx: {
     }
 
     if (e.type !== "message" || !isRecord(e.message)) continue;
-    const msg = e.message;
+    const msg = e.message as Record<string, unknown>;
     if (msg.role !== "toolResult" || msg.toolName !== TOOL_WRITE) continue;
     if (!isWriteDetails(msg.details)) continue;
     // Skip error envelopes — they did not commit
-    if (msg.details.error) continue;
-    todos = msg.details.todos.map((t) => ({ ...t }));
+    if ((msg.details as TodoWriteDetails).error) continue;
+    todos = (msg.details as TodoWriteDetails).todos.map((t) => ({ ...t }));
   }
 
   return todos;

package/src/schema.ts

@@ -18,7 +18,10 @@ export const TodoWriteParams = Type.Object({
   }),
 });
 
-export const TodoReadParams = Type.Object({});
+export const TodoReadParams = Type.Object({});
+
+/** Read-only persistence check; deliberately accepts no mutation input. */
+export const TodoDiagnoseParams = Type.Object({});
 
 export type TodoWriteInput = Static<typeof TodoWriteParams>;
 export type TodoItemInput = Static<typeof TodoItemSchema>;

package/src/tools/tododiagnose.ts

@@ -0,0 +1,55 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { TODODIAGNOSE_DESCRIPTION } from "../prompt.js";
+import { replayFromBranch } from "../replay.js";
+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";
+
+interface TodoDiagnoseDetails {
+  status: "consistent" | "mismatch";
+  storeTodos: TodoItem[];
+  replayedTodos: TodoItem[];
+}
+
+/** Registers a read-only comparison between live state and durable branch replay. */
+export function registerTodoDiagnoseTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: TOOL_DIAGNOSE,
+    label: "Todo Diagnose",
+    description: TODODIAGNOSE_DESCRIPTION,
+    promptSnippet: "Diagnose todo persistence without changing todos",
+    parameters: TodoDiagnoseParams,
+
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      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.";
+
+        return {
+          content: [{ type: "text", text: `${text}\n\n${JSON.stringify(details, null, 2)}` }],
+          details,
+        };
+      });
+    },
+
+    renderCall(_args, theme) {
+      return new Text(theme.fg("toolTitle", theme.bold("todo_diagnose")), 0, 0);
+    },
+
+    renderResult(result, _opts, theme) {
+      const details = result.details as TodoDiagnoseDetails | undefined;
+      const text = details?.status === "consistent" ? "✓ Consistent" : "! Mismatch";
+      const color = details?.status === "consistent" ? "success" : "warning";
+      return new Text(theme.fg(color, text), 0, 0);
+    },
+  });
+}

package/src/tools/todowrite.ts

@@ -33,18 +33,34 @@ export function registerTodoWriteTool(
           };
         }
 
-        setTodos(result.todos);
-
-        // Durable custom entry (not sent to LLM) — survives compaction better than tool details alone.
-        // Skip no-op rewrites to avoid session noise.
+        // 1. Persist durable state BEFORE updating in-memory store.
+        //    If appendEntry fails (stale ctx, persistence error), we abort
+        //    so in-memory store never diverges from durable state.
         if (!result.unchanged) {
           try {
             pi.appendEntry(TODO_STATE_ENTRY_TYPE, { todos: result.todos });
-          } catch {
-            // Host may reject; toolResult details still provide branch replay.
+          } catch (e) {
+            // Stale session: discard this write entirely — returning error
+            // so the LLM knows the state was not committed.
+            if (/stale after session replacement/i.test(String(e))) {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: "Error: session was replaced — state not committed. Please retry todo_write.",
+                  },
+                ],
+                details: { todos: current, error: "stale session replacement" } satisfies TodoWriteDetails,
+              };
+            }
+            // Real persistence/disk/runtime error: propagate.
+            throw e;
           }
         }
 
+        // 2. Durable write succeeded (or no-op) — now update in-memory store.
+        setTodos(result.todos);
+
         options.onCommit?.();
 
         const open = countOpenTodos(result.todos);
@@ -87,7 +103,11 @@ export function registerTodoWriteTool(
       if (!details?.error && !details?.unchanged) {
         const open = details?.todos ? details.todos.filter((t: any) => t.status === "pending" || t.status === "in_progress").length : 0;
         const total = details?.todos?.length ?? 0;
-        return new Text(theme.fg("success", "✓ ") + theme.fg("muted", `${open} open / ${total} total`), 0, 0);
+          return new Text(
+            theme.fg("success", "✓ Saved") + theme.fg("muted", ` · ${open} open / ${total} total`),
+            0,
+            0,
+          );
       }
       const msg = text?.type === "text" ? text.text.split("\n")[0] ?? "Updated" : "Updated";
       return new Text(theme.fg("success", "✓ ") + theme.fg("muted", msg), 0, 0);

package/src/types.ts

@@ -21,6 +21,7 @@ export interface TodoWriteDetails {
 export const TODO_STATE_ENTRY_TYPE = "pi-todo.state";
 export const TOOL_WRITE = "todo_write";
 export const TOOL_READ = "todo_read";
+export const TOOL_DIAGNOSE = "todo_diagnose";
 export const WIDGET_KEY = "pi-todo";
 export const MAX_OVERLAY_LINES = 12;
 /** Max characters per todo content after sanitize (context/tool safety). */