@nguyenquangthai/pi-todo 0.2.8 → 0.2.9

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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.

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.8",
+  "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/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,25 +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 (e) {
-            // Only swallow host-reject errors (stale context, unsupported custom entry).
-            // Let real runtime/disk/persistence errors propagate so they surface to the user.
+            // 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))) {
-              // Expected: session was replaced, this append is discarded.
-              // toolResult details still provide branch replay.
-            } else {
-              throw 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);
@@ -94,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). */