@nguyenquangthai/pi-todo 0.2.8 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.3.0 (2026-07-15)
+
+- **ID invariant hardening**: `validateTodoWrite` rejects items with explicit `id`
+  that doesn't exist in current list. New items must omit `id` (auto-assign).
+- **`ensureTodoIds` tuple matching**: Matches by `(content+status+priority)` first,
+  then by unique content-only. Duplicate-content items get fresh UUIDs instead
+  of risking mis-assignment.
+- **`todo_update` atomicity**: Stale-ctx returns error, real errors propagate,
+  setTodos after appendEntry — matching todo_write guarantees.
+- **Status-first shared sort**: `statusPrioritySort()` extracted and shared by
+  `formatTodoListText` (tool output) and `selectOverlayLayout` (overlay) —
+  in_progress → pending → terminal, regardless of overflow.
+- **Fixed double-count bug**: Terminal items no longer counted in both `+N done`
+  AND `+N more` on overlay overflow.
+- **Lifecycle E2E test**: Write → update → tree → compact → shutdown → restart,
+  verifying stable IDs and status throughout.
+- **125 tests**, typecheck clean, CI green (Node 20 + 22).
+
+## 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.3.0",
   "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/format.ts

@@ -14,6 +14,18 @@ function prioritySort(a: TodoItem, b: TodoItem): number {
   return (PRIORITY_RANK[a.priority] ?? 2) - (PRIORITY_RANK[b.priority] ?? 2);
 }
 
+/** Active work always leads the overlay, then pending, then terminal work. */
+function statusPrioritySort(a: TodoItem, b: TodoItem): number {
+  const statusRank: Record<TodoStatus, number> = {
+    in_progress: 0,
+    pending: 1,
+    completed: 2,
+    cancelled: 2,
+  };
+  const diff = statusRank[a.status] - statusRank[b.status];
+  return diff !== 0 ? diff : prioritySort(a, b);
+}
+
 export function getTodoMarker(status: TodoStatus): string {
   switch (status) {
     case "completed":
@@ -36,18 +48,7 @@ export function formatTodoListText(todos: readonly TodoItem[], summary: string):
   if (todos.length === 0) return summary;
 
   // in_progress first, then pending (sorted by priority), then terminal
-  const sorted = [...todos].sort((a, b) => {
-    const statusRank: Record<string, number> = {
-      in_progress: 0,
-      pending: 1,
-      completed: 2,
-      cancelled: 2,
-    };
-    const diff =
-      (statusRank[a.status] ?? 2) - (statusRank[b.status] ?? 2);
-    if (diff !== 0) return diff;
-    return prioritySort(a, b);
-  });
+  const sorted = [...todos].sort(statusPrioritySort);
 
   if (todos.length <= MAX_RESULT_LINES) {
     return [summary, ...sorted.map(formatPlainTodoLine)].join("\n");
@@ -99,7 +100,7 @@ export function selectOverlayLayout(
   const bodyBudget = Math.max(1, maxLines - 1);
   if (todos.length <= bodyBudget) {
     // All fit — show everything
-    return { visible: [...todos].sort(prioritySort), hiddenCount: 0, terminalCount: 0 };
+    return { visible: [...todos].sort(statusPrioritySort), hiddenCount: 0, terminalCount: 0 };
   }
 
   const innerBudget = Math.max(1, bodyBudget - 1);
@@ -125,7 +126,9 @@ export function selectOverlayLayout(
 
   const terminalCollapsed = terminal.length > 0 && picked.length >= innerBudget;
   const remaining = todos.length - picked.length;
-  const hiddenCount = terminalCollapsed ? remaining : Math.max(0, remaining - terminal.length);
+  const hiddenCount = terminalCollapsed
+    ? remaining - terminal.length
+    : Math.max(0, remaining - terminal.length);
 
   return { visible: picked, hiddenCount, terminalCount: terminalCollapsed ? terminal.length : 0 };
 }

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,13 @@ 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 { registerTodoUpdateTool } from "./tools/todoupdate.js";
+import { TOOL_DIAGNOSE, TOOL_READ, TOOL_UPDATE, 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_UPDATE, TOOL_DIAGNOSE]);
 
 const cadenceConfig: CadenceConfig = {
   reminderInterval: REMINDER_INTERVAL,
@@ -86,7 +88,9 @@ export default function (pi: ExtensionAPI): void {
   };
 
   registerTodoWriteTool(pi, { onCommit: refreshOverlay });
+  registerTodoUpdateTool(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

@@ -2,7 +2,8 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 import { TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
 
-export const TodoItemSchema = Type.Object({
+export const TodoItemSchema = Type.Object({
+  id: Type.Optional(Type.String({ minLength: 1, description: "Stable todo ID; preserve it when rewriting an existing item" })),
   content: Type.String({ description: "Brief description of the task" }),
   status: StringEnum([...TODO_STATUSES], {
     description: "pending | in_progress | completed | cancelled",
@@ -18,7 +19,22 @@ 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 const TodoUpdateParams = Type.Object({
+  updates: Type.Array(
+    Type.Object({
+      id: Type.String({ minLength: 1 }),
+      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" },
+  ),
+});
 
 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/todoupdate.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { TodoUpdateParams } from "../schema.js";
+import { getTodos, setTodos, withStoreLock } from "../store.js";
+import type { TodoWriteDetails } from "../types.js";
+import { TODO_STATE_ENTRY_TYPE, TOOL_UPDATE } from "../types.js";
+import { ensureTodoIds, validateTodoUpdate } from "../validate.js";
+
+export function registerTodoUpdateTool(pi: ExtensionAPI, options: { onCommit?: () => void }): void {
+  pi.registerTool({
+    name: TOOL_UPDATE,
+    label: "Todo Update",
+    description: "Patch existing todos by stable ID. Use todo_read first to obtain IDs. This never deletes items.",
+    promptSnippet: "Patch one or more existing todos by ID without replacing the full list",
+    parameters: TodoUpdateParams,
+    async execute(_toolCallId, params) {
+      return withStoreLock(() => {
+        const current = getTodos();
+        const result = validateTodoUpdate(params.updates, current);
+        if (!result.ok) return { content: [{ type: "text", text: `Error: ${result.error}` }], details: { todos: current, error: result.error } as TodoWriteDetails };
+        const todos = ensureTodoIds(result.todos, current);
+        if (!result.unchanged) {
+          try { pi.appendEntry(TODO_STATE_ENTRY_TYPE, { todos }); }
+          catch (e) {
+            if (/stale after session replacement/i.test(String(e))) {
+              return { content: [{ type: "text", text: "Error: session was replaced — state not committed. Please retry todo_update." }], details: { todos: current, error: "stale session replacement" } as TodoWriteDetails };
+            }
+            throw e;
+          }
+        }
+        setTodos(todos);
+        options.onCommit?.();
+        return { content: [{ type: "text", text: result.unchanged ? "No change" : `Updated ${params.updates.length} todo(s)` }], details: { todos, ...(result.unchanged ? { unchanged: true } : {}) } as TodoWriteDetails };
+      });
+    },
+    renderCall(args, theme) { return new Text(theme.fg("toolTitle", theme.bold("todo_update ")) + theme.fg("accent", `${Array.isArray(args.updates) ? args.updates.length : 0} patch(es)`), 0, 0); },
+    renderResult(result, _opts, theme) {
+      const details = result.details as TodoWriteDetails | undefined;
+      if (details?.error) return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+      return new Text(theme.fg("success", details?.unchanged ? "No change" : "✓ Saved"), 0, 0);
+    },
+  });
+}

package/src/tools/todowrite.ts

@@ -6,7 +6,7 @@ import { TodoWriteParams } from "../schema.js";
 import { getTodos, setTodos, withStoreLock } from "../store.js";
 import type { TodoWriteDetails } from "../types.js";
 import { TODO_STATE_ENTRY_TYPE, TOOL_WRITE } from "../types.js";
-import { countOpenTodos, validateTodoWrite } from "../validate.js";
+import { countOpenTodos, ensureTodoIds, todosEqual, validateTodoWrite } from "../validate.js";
 
 export function registerTodoWriteTool(
   pi: ExtensionAPI,
@@ -33,37 +33,48 @@ 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.
-        if (!result.unchanged) {
+          const todos = result.unchanged ? result.todos : ensureTodoIds(result.todos, current);
+          const unchanged = result.unchanged || todosEqual(todos, current);
+          // 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 (!unchanged) {
           try {
-            pi.appendEntry(TODO_STATE_ENTRY_TYPE, { todos: result.todos });
+              pi.appendEntry(TODO_STATE_ENTRY_TYPE, { 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(todos);
+
         options.onCommit?.();
 
-        const open = countOpenTodos(result.todos);
-        const summary = result.unchanged
+          const open = countOpenTodos(todos);
+          const summary = unchanged
           ? "No change"
-          : `${open} open / ${result.todos.length} total`;
+            : `${open} open / ${todos.length} total`;
         const body =
-          result.todos.length === 0 ? "Cleared todos" : formatTodoListText(result.todos, summary);
+            todos.length === 0 ? "Cleared todos" : formatTodoListText(todos, summary);
 
         const details: TodoWriteDetails = {
-          todos: result.todos,
-          ...(result.unchanged ? { unchanged: true } : {}),
+            todos,
+            ...(unchanged ? { unchanged: true } : {}),
         };
 
         return {
@@ -94,7 +105,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

@@ -7,6 +7,8 @@ export type TodoPriority = (typeof TODO_PRIORITIES)[number];
 export const TERMINAL_STATUSES: ReadonlySet<TodoStatus> = new Set(["completed", "cancelled"]);
 
 export interface TodoItem {
+  /** Stable identity; absent only in legacy session entries until their next mutation. */
+  id?: string;
   content: string;
   status: TodoStatus;
   priority: TodoPriority;
@@ -21,6 +23,8 @@ 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 TOOL_UPDATE = "todo_update";
 export const WIDGET_KEY = "pi-todo";
 export const MAX_OVERLAY_LINES = 12;
 /** Max characters per todo content after sanitize (context/tool safety). */

package/src/validate.ts

@@ -1,105 +1,201 @@
-import { sanitizeTodoText } from "./sanitize.js";
-import type { TodoItem, TodoPriority, TodoStatus } from "./types.js";
-import { MAX_CONTENT_LENGTH, TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
-
-export type ValidateOk = { ok: true; todos: TodoItem[]; unchanged: boolean };
-export type ValidateErr = { ok: false; error: string };
-export type ValidateResult = ValidateOk | ValidateErr;
-
-function isStatus(value: unknown): value is TodoStatus {
-  return typeof value === "string" && (TODO_STATUSES as readonly string[]).includes(value);
-}
-
-function isPriority(value: unknown): value is TodoPriority {
-  return typeof value === "string" && (TODO_PRIORITIES as readonly string[]).includes(value);
-}
-
-export function todosEqual(a: readonly TodoItem[], b: readonly TodoItem[]): boolean {
-  if (a.length !== b.length) return false;
-  return a.every(
-    (item, i) =>
-      item.content === b[i].content && item.status === b[i].status && item.priority === b[i].priority,
-  );
-}
-
-/**
- * Validate and normalize a full-replace payload.
- * Hard-enforces at most one `in_progress`. Does not mutate `current`.
- */
-export function validateTodoWrite(
-  rawTodos: unknown,
-  current: readonly TodoItem[],
-): ValidateResult {
-  if (!Array.isArray(rawTodos)) {
-    return { ok: false, error: "todos must be an array" };
-  }
-
-  const todos: TodoItem[] = [];
-  let inProgressCount = 0;
-
-  for (let i = 0; i < rawTodos.length; i++) {
-    const item = rawTodos[i];
-    if (!item || typeof item !== "object") {
-      return { ok: false, error: `todos[${i}] must be an object` };
-    }
-    const rec = item as Record<string, unknown>;
-
-    if (typeof rec.content !== "string") {
-      return { ok: false, error: `todos[${i}].content must be a string` };
-    }
-    let content = sanitizeTodoText(rec.content);
-    if (!content) {
-      return { ok: false, error: `todos[${i}].content must be non-empty` };
-    }
-    if (content.length > MAX_CONTENT_LENGTH) {
-      content = `${content.slice(0, MAX_CONTENT_LENGTH - 1)}…`;
-    }
-
-    if (!isStatus(rec.status)) {
-      return {
-        ok: false,
-        error: `todos[${i}].status must be one of: ${TODO_STATUSES.join(", ")}`,
-      };
-    }
-    if (!isPriority(rec.priority)) {
-      return {
-        ok: false,
-        error: `todos[${i}].priority must be one of: ${TODO_PRIORITIES.join(", ")}`,
-      };
-    }
-
-    if (rec.status === "in_progress") inProgressCount += 1;
-
-    todos.push({ content, status: rec.status, priority: rec.priority });
-  }
-
-  if (inProgressCount > 1) {
-    return {
-      ok: false,
-      error: `exactly one in_progress allowed (got ${inProgressCount}); keep only the active task in_progress`,
-    };
-  }
-
-  return { ok: true, todos, unchanged: todosEqual(todos, current) };
-}
-
-export function isTerminalStatus(status: TodoStatus): boolean {
-  return status === "completed" || status === "cancelled";
-}
-
-export function isOpenTodo(todo: TodoItem): boolean {
-  return !isTerminalStatus(todo.status);
-}
-
-export function hasOpenTodos(todos: readonly TodoItem[]): boolean {
-  return todos.some(isOpenTodo);
-}
-
-export function countOpenTodos(todos: readonly TodoItem[]): number {
-  return todos.filter(isOpenTodo).length;
-}
-
-/** Count of `in_progress` items (shown as "running" in the overlay heading). */
-export function countRunningTodos(todos: readonly TodoItem[]): number {
-  return todos.filter((t) => t.status === "in_progress").length;
-}
+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";
+
+export type ValidateOk = { ok: true; todos: TodoItem[]; unchanged: boolean };
+export type ValidateErr = { ok: false; error: string };
+export type ValidateResult = ValidateOk | ValidateErr;
+
+function isStatus(value: unknown): value is TodoStatus {
+  return typeof value === "string" && (TODO_STATUSES as readonly string[]).includes(value);
+}
+
+function isPriority(value: unknown): value is TodoPriority {
+  return typeof value === "string" && (TODO_PRIORITIES as readonly string[]).includes(value);
+}
+
+export function todosEqual(a: readonly TodoItem[], b: readonly TodoItem[]): boolean {
+  if (a.length !== b.length) return false;
+  return a.every(
+    (item, i) =>
+        item.id === b[i].id && item.content === b[i].content && item.status === b[i].status && item.priority === b[i].priority,
+  );
+}
+
+/**
+ * Validate and normalize a full-replace payload.
+ * Hard-enforces at most one `in_progress`. Does not mutate `current`.
+ */
+export function validateTodoWrite(
+  rawTodos: unknown,
+  current: readonly TodoItem[],
+): ValidateResult {
+  if (!Array.isArray(rawTodos)) {
+    return { ok: false, error: "todos must be an array" };
+  }
+
+  const todos: TodoItem[] = [];
+  let inProgressCount = 0;
+  const seenIds = new Set<string>();
+
+  for (let i = 0; i < rawTodos.length; i++) {
+    const item = rawTodos[i];
+    if (!item || typeof item !== "object") {
+      return { ok: false, error: `todos[${i}] must be an object` };
+    }
+    const rec = item as Record<string, unknown>;
+
+    if (typeof rec.content !== "string") {
+      return { ok: false, error: `todos[${i}].content must be a string` };
+    }
+    let content = sanitizeTodoText(rec.content);
+    if (!content) {
+      return { ok: false, error: `todos[${i}].content must be non-empty` };
+    }
+    if (content.length > MAX_CONTENT_LENGTH) {
+      content = `${content.slice(0, MAX_CONTENT_LENGTH - 1)}…`;
+    }
+
+    if (!isStatus(rec.status)) {
+      return {
+        ok: false,
+        error: `todos[${i}].status must be one of: ${TODO_STATUSES.join(", ")}`,
+      };
+    }
+    if (!isPriority(rec.priority)) {
+      return {
+        ok: false,
+        error: `todos[${i}].priority must be one of: ${TODO_PRIORITIES.join(", ")}`,
+      };
+    }
+
+    if (rec.status === "in_progress") inProgressCount += 1;
+
+    if (rec.id !== undefined) {
+      if (typeof rec.id !== "string" || !rec.id.trim()) {
+        return { ok: false, error: `todos[${i}].id must be a non-empty string when provided` };
+      }
+      if (seenIds.has(rec.id)) {
+        return { ok: false, error: `todos[${i}].id "${rec.id}" is duplicated` };
+      }
+      seenIds.add(rec.id);
+    }
+    todos.push({ ...(typeof rec.id === "string" ? { id: rec.id } : {}), content, status: rec.status, priority: rec.priority });
+  }
+
+  if (inProgressCount > 1) {
+    return {
+      ok: false,
+      error: `exactly one in_progress allowed (got ${inProgressCount}); keep only the active task in_progress`,
+    };
+  }
+
+  // Reject explicit IDs that don't exist in current list
+  // (caller must omit `id` for new items so the system auto-assigns).
+  const currentIds = new Set(current.map((t) => t.id).filter(Boolean));
+  for (let i = 0; i < todos.length; i++) {
+    if (todos[i].id && !currentIds.has(todos[i].id)) {
+      return {
+        ok: false,
+        error: `todos[${i}].id "${todos[i].id}" does not match any existing todo; omit id for new items`,
+      };
+    }
+  }
+
+  return { ok: true, todos, unchanged: todosEqual(todos, current) };
+}
+
+/** Assign IDs once at mutation time.
+ *
+ * - Items with an explicit `id` keep it (must already exist in `current`, verified
+ *   by `validateTodoWrite`).
+ * - 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[] {
+  const claimed = new Set<string>();
+
+  // Pre-index content uniqueness: content that appears only once in `current`
+  // is safe for content-only fallback.
+  const contentCounts = new Map<string, number>();
+  for (const c of current) {
+    contentCounts.set(c.content, (contentCounts.get(c.content) ?? 0) + 1);
+  }
+
+  return todos.map((todo) => {
+    let id = todo.id;
+    if (!id) {
+      // 1. Exact tuple match (content + status + priority)
+      const byTuple = current.find(
+        (c) => !!c.id && !claimed.has(c.id) &&
+          c.content === todo.content &&
+          c.status === todo.status &&
+          c.priority === todo.priority,
+      );
+      if (byTuple) {
+        id = byTuple.id;
+      } else {
+        // 2. Content-only fallback — only when content is unique in current
+        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,
+          );
+          if (byContent) id = byContent.id;
+        }
+      }
+      // 3. No match or ambiguous → fresh ID
+      if (!id) id = randomUUID();
+    }
+    claimed.add(id);
+    return { ...todo, id };
+  });
+}
+
+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" };
+  }
+  const next = current.map((todo) => ({ ...todo }));
+  const seen = new Set<string>();
+  for (let i = 0; i < rawUpdates.length; i++) {
+    const update = rawUpdates[i];
+    if (!update || typeof update !== "object") return { ok: false, error: `updates[${i}] must be an object` };
+    const rec = update as Record<string, unknown>;
+    if (typeof rec.id !== "string" || !rec.id) return { ok: false, error: `updates[${i}].id must be a non-empty string` };
+    if (seen.has(rec.id)) return { ok: false, error: `updates[${i}].id is duplicated` };
+    seen.add(rec.id);
+    const target = next.find((todo) => todo.id === rec.id);
+    if (!target) return { ok: false, error: `updates[${i}].id does not match an existing todo` };
+    if (rec.content === undefined && rec.status === undefined && rec.priority === undefined) {
+      return { ok: false, error: `updates[${i}] must change content, status, or priority` };
+    }
+    if (rec.content !== undefined) target.content = rec.content as string;
+    if (rec.status !== undefined) target.status = rec.status as TodoStatus;
+    if (rec.priority !== undefined) target.priority = rec.priority as TodoPriority;
+  }
+  return validateTodoWrite(next, current);
+}
+
+export function isTerminalStatus(status: TodoStatus): boolean {
+  return status === "completed" || status === "cancelled";
+}
+
+export function isOpenTodo(todo: TodoItem): boolean {
+  return !isTerminalStatus(todo.status);
+}
+
+export function hasOpenTodos(todos: readonly TodoItem[]): boolean {
+  return todos.some(isOpenTodo);
+}
+
+export function countOpenTodos(todos: readonly TodoItem[]): number {
+  return todos.filter(isOpenTodo).length;
+}
+
+/** Count of `in_progress` items (shown as "running" in the overlay heading). */
+export function countRunningTodos(todos: readonly TodoItem[]): number {
+  return todos.filter((t) => t.status === "in_progress").length;
+}