@nguyenquangthai/pi-todo 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuangThai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# pi-todo
+
+OpenCode-style session todo checklist for the [pi coding agent](https://pi.dev).
+
+Adds `todowrite` / `todoread`, a live `# Todos` overlay above the editor (`[ ]` / `[•]` / `[✓]` / `[×]`), and branch-replay persistence (survives `/reload`, tree nav, and custom-entry durability across compaction).
+
+## Install
+
+```bash
+pi install npm:@nguyenquangthai/pi-todo
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/QuangThai/pi-todo.git
+cd pi-todo
+pi install .
+```
+
+Then restart pi or run `/reload`.
+
+## Tools
+
+### `todowrite`
+
+Full-replace the session todo list. Each call must pass the **complete** list.
+
+```json
+{
+  "todos": [
+    { "content": "Wire overlay", "status": "completed", "priority": "high" },
+    { "content": "Add tests", "status": "in_progress", "priority": "high" },
+    { "content": "Write README", "status": "pending", "priority": "medium" }
+  ]
+}
+```
+
+Rules enforced by the tool:
+
+- Exactly **one** `in_progress` allowed (hard reject if more)
+- `content` required (non-empty after sanitize); max **500** chars (longer values truncated)
+- `priority` required: `high` | `medium` | `low`
+- Status: `pending` | `in_progress` | `completed` | `cancelled`
+- Tool text echo caps at **40** lines (`+N more` in the text body; full list still in `details` / JSON)
+
+### `todoread`
+
+Returns the current list as text + JSON. Prefer the overlay for at-a-glance status; avoid calling it in the same parallel batch as `todowrite`.
+
+## Overlay
+
+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, e.g. `# Todos (2 open, 1 running)`:
+
+- **open** = `pending` + `in_progress`
+- **running** = `in_progress` only (0 or 1 after a valid write)
+
+There is a blank line under the heading so it is not flush against the first todo row.
+
+## Development
+
+```bash
+git clone https://github.com/QuangThai/pi-todo.git
+cd pi-todo
+npm install
+npm test
+npm run typecheck
+pi -e ./src/index.ts
+```
+
+## License
+
+[MIT](./LICENSE) © QuangThai

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@nguyenquangthai/pi-todo",
+  "version": "0.2.0",
+  "description": "OpenCode-like session todo checklist for the pi coding agent — todowrite/todoread with a live TUI overlay",
+  "type": "module",
+  "author": "QuangThai",
+  "license": "MIT",
+  "homepage": "https://github.com/QuangThai/pi-todo#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QuangThai/pi-todo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/QuangThai/pi-todo/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "todo",
+    "todowrite",
+    "todoread",
+    "opencode",
+    "tui"
+  ],
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm test && npm run typecheck"
+  },
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.80.7",
+    "@earendil-works/pi-coding-agent": "^0.80.7",
+    "@earendil-works/pi-tui": "^0.80.7",
+    "@types/node": "^22.0.0",
+    "typebox": "1.1.38",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/format.ts

@@ -0,0 +1,139 @@
+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, isTerminalStatus } from "./validate.js";
+
+export function getTodoMarker(status: TodoStatus): string {
+  switch (status) {
+    case "completed":
+      return "[✓]";
+    case "in_progress":
+      return "[•]";
+    case "cancelled":
+      return "[×]";
+    default:
+      return "[ ]";
+  }
+}
+
+export function formatPlainTodoLine(todo: TodoItem): string {
+  return `${getTodoMarker(todo.status)} ${todo.content}`;
+}
+
+/** Compact checklist for tool responses; caps lines to keep LLM context small. */
+export function formatTodoListText(todos: readonly TodoItem[], summary: string): string {
+  if (todos.length === 0) return summary;
+  if (todos.length <= MAX_RESULT_LINES) {
+    return [summary, ...todos.map(formatPlainTodoLine)].join("\n");
+  }
+  const shown = todos.slice(0, MAX_RESULT_LINES);
+  const hidden = todos.length - MAX_RESULT_LINES;
+  return [
+    summary,
+    ...shown.map(formatPlainTodoLine),
+    `… and ${hidden} more (full list in details/JSON)`,
+  ].join("\n");
+}
+
+export function formatThemedTodoLine(todo: TodoItem, theme: Theme): string {
+  const marker = getTodoMarker(todo.status);
+  if (todo.status === "in_progress") {
+    return `${theme.fg("warning", marker)} ${theme.fg("warning", todo.content)}`;
+  }
+  if (todo.status === "completed" || todo.status === "cancelled") {
+    return `${theme.fg("dim", marker)} ${theme.fg("dim", todo.content)}`;
+  }
+  return `${theme.fg("muted", marker)} ${theme.fg("muted", todo.content)}`;
+}
+
+/** Show overlay while any pending/in_progress remains. */
+export function shouldShowOverlay(todos: readonly TodoItem[]): boolean {
+  return hasOpenTodos(todos);
+}
+
+export interface OverlayLayout {
+  visible: TodoItem[];
+  hiddenCount: number;
+}
+
+/**
+ * Fit into maxLines (includes heading). On overflow, drop terminal first,
+ * then pending from the end; keep in_progress. Preserve original order.
+ */
+export function selectOverlayLayout(
+  todos: readonly TodoItem[],
+  maxLines: number = MAX_OVERLAY_LINES,
+): OverlayLayout {
+  if (!shouldShowOverlay(todos)) {
+    return { visible: [], hiddenCount: 0 };
+  }
+
+  const bodyBudget = Math.max(1, maxLines - 1);
+  if (todos.length <= bodyBudget) {
+    return { visible: [...todos], hiddenCount: 0 };
+  }
+
+  const innerBudget = Math.max(1, bodyBudget - 1);
+  const inProgress = todos.filter((t) => t.status === "in_progress");
+  const pending = todos.filter((t) => t.status === "pending");
+  const terminal = todos.filter((t) => isTerminalStatus(t.status));
+
+  const picked = new Set<TodoItem>();
+  for (const t of inProgress) {
+    if (picked.size >= innerBudget) break;
+    picked.add(t);
+  }
+  for (const t of pending) {
+    if (picked.size >= innerBudget) break;
+    picked.add(t);
+  }
+  for (const t of terminal) {
+    if (picked.size >= innerBudget) break;
+    picked.add(t);
+  }
+
+  const visible = todos.filter((t) => picked.has(t));
+  return { visible, hiddenCount: todos.length - visible.length };
+}
+
+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 todowrite)
+ * Overlay is hidden when open === 0, so "(0 open, 0 running)" is never shown.
+ */
+export function renderOverlayLines(
+  todos: readonly TodoItem[],
+  theme: Theme,
+  width: number,
+  options: RenderOverlayOptions = {},
+): string[] {
+  if (!shouldShowOverlay(todos)) return [];
+
+  const maxLines = options.maxLines ?? MAX_OVERLAY_LINES;
+  const truncate = (line: string) => truncateToWidth(line, width, "…");
+  const open = countOpenTodos(todos);
+  const running = countRunningTodos(todos);
+  const heading = truncate(
+    theme.fg("accent", theme.bold(`# Todos`)) +
+      theme.fg("dim", ` (${open} open, ${running} running)`),
+  );
+
+  // Reserve heading + blank gap under heading so the title isn't flush with rows.
+  const layout = selectOverlayLayout(todos, Math.max(3, maxLines - 1));
+  const lines: string[] = [heading, ""];
+
+  for (const todo of layout.visible) {
+    lines.push(truncate(formatThemedTodoLine(todo, theme)));
+  }
+  if (layout.hiddenCount > 0) {
+    lines.push(truncate(theme.fg("dim", `+${layout.hiddenCount} more`)));
+  }
+  lines.push("");
+  return lines;
+}

package/src/index.ts

@@ -0,0 +1,185 @@
+/**
+ * pi-todo — OpenCode-like session todo checklist for Pi.
+ *
+ * Tools: todowrite (full replace), todoread
+ * Overlay: # Todos with [ ]/[•]/[✓]/[×] above the editor
+ * Persistence: toolResult details + custom entry, replayed from branch
+ * Reminder: pi-tasks-style cadence → transient <system-reminder> via context
+ * Cold start: pi-todotools section + prompt-aware one-shot context nudge
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { formatPlainTodoLine } from "./format.js";
+import { TodoOverlay } from "./overlay.js";
+import {
+  buildColdStartReminder,
+  buildCompletionUpdateReminder,
+  shouldNudgeColdStart,
+  shouldNudgeCompletionUpdate,
+} from "./prompt-intent.js";
+import { COLD_START_BOOST, TASK_MANAGEMENT_SECTION } from "./prompt.js";
+import {
+  buildSystemReminder,
+  createCadenceState,
+  drainReminderForContext,
+  evaluateToolResult,
+  onTurnStart,
+  REMINDER_INTERVAL,
+  resetCadenceState,
+  type CadenceConfig,
+} from "./reminder-cadence.js";
+import { replayFromBranch } from "./replay.js";
+import { clearTodos, getTodos, setTodos } from "./store.js";
+import { registerTodoReadTool } from "./tools/todoread.js";
+import { registerTodoWriteTool } from "./tools/todowrite.js";
+import { TOOL_READ, TOOL_WRITE } from "./types.js";
+import { hasOpenTodos, isOpenTodo } from "./validate.js";
+
+const TODO_TOOL_NAMES = new Set([TOOL_WRITE, TOOL_READ]);
+
+const cadenceConfig: CadenceConfig = {
+  reminderInterval: REMINDER_INTERVAL,
+  todoToolNames: TODO_TOOL_NAMES,
+};
+
+function isStaleCtxError(e: unknown): boolean {
+  return /stale after session replacement/i.test(String(e));
+}
+
+function syncFromSession(ctx: ExtensionContext, overlay: TodoOverlay | undefined): void {
+  try {
+    setTodos(replayFromBranch(ctx));
+  } catch (e) {
+    if (!isStaleCtxError(e)) throw e;
+    return;
+  }
+  if (ctx.hasUI && overlay) {
+    overlay.setUICtx(ctx.ui);
+    overlay.update();
+  }
+}
+
+function injectReminderMessage(
+  messages: unknown[],
+  text: string,
+): { messages: unknown[] } {
+  return {
+    messages: [
+      ...messages,
+      {
+        role: "user" as const,
+        content: [{ type: "text" as const, text }],
+        timestamp: Date.now(),
+      },
+    ],
+  };
+}
+
+export default function (pi: ExtensionAPI): void {
+  let overlay: TodoOverlay | undefined;
+  const cadence = createCadenceState();
+  /** One-shot transient nudge for the next LLM context (cold start or completion). */
+  let pendingIntentNudge: string | null = null;
+
+  const refreshOverlay = (): void => {
+    overlay?.update();
+  };
+
+  registerTodoWriteTool(pi, { onCommit: refreshOverlay });
+  registerTodoReadTool(pi);
+
+  // Cold-start + completion nudges. Tool description alone is often ignored;
+  // prompt-aware section + one-shot context reminder (pi-tasks style) is stronger.
+  pi.on("before_agent_start", async (event) => {
+    const prompt = typeof event.prompt === "string" ? event.prompt : "";
+    const open = hasOpenTodos(getTodos());
+    let systemPrompt = `${event.systemPrompt}\n${TASK_MANAGEMENT_SECTION}`;
+
+    if (shouldNudgeColdStart(prompt, open)) {
+      systemPrompt += `\n${COLD_START_BOOST}`;
+      pendingIntentNudge = buildColdStartReminder(prompt);
+    } else if (shouldNudgeCompletionUpdate(prompt, open)) {
+      const openLines = getTodos().filter(isOpenTodo).map(formatPlainTodoLine);
+      pendingIntentNudge = buildCompletionUpdateReminder(openLines);
+    }
+
+    return { systemPrompt };
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    resetCadenceState(cadence);
+    pendingIntentNudge = null;
+    if (ctx.hasUI && !overlay) {
+      overlay = new TodoOverlay();
+    }
+    syncFromSession(ctx, overlay);
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    syncFromSession(ctx, overlay);
+  });
+
+  pi.on("session_compact", async (_event, ctx) => {
+    syncFromSession(ctx, overlay);
+  });
+
+  pi.on("session_shutdown", async () => {
+    try {
+      overlay?.dispose();
+    } finally {
+      // Clear in-memory store so a stale session_start (early return) cannot
+      // briefly expose the previous session's todos to reminders/tools.
+      clearTodos();
+      overlay = undefined;
+      pendingIntentNudge = null;
+      resetCadenceState(cadence);
+    }
+  });
+
+  pi.on("turn_start", async () => {
+    onTurnStart(cadence);
+  });
+
+  // Cadence tracking only — never mutate tool result content.
+  // Gate on open work (pending/in_progress), not all-terminal lists.
+  pi.on("tool_result", async (event) => {
+    const isTodoTool = TODO_TOOL_NAMES.has(event.toolName);
+    if (
+      !isTodoTool &&
+      cadence.currentTurn - cadence.lastTodoToolUseTurn < REMINDER_INTERVAL
+    ) {
+      return;
+    }
+    if (!isTodoTool && cadence.reminderInjectedThisCycle) return;
+
+    const hasOpenWork = isTodoTool ? false : hasOpenTodos(getTodos());
+    evaluateToolResult(cadence, event.toolName, hasOpenWork, cadenceConfig);
+  });
+
+  // Transient injection for one LLM call — not persisted in the session store.
+  // Intent nudge (cold start / user-said-done) takes priority over idle cadence.
+  // Peer typings sometimes omit "context" from the overloaded `on` signature.
+  const onEvent = pi.on.bind(pi) as (event: string, handler: (...args: never[]) => unknown) => void;
+  onEvent("context", async (event: { messages: unknown[] }) => {
+    if (pendingIntentNudge) {
+      const text = pendingIntentNudge;
+      pendingIntentNudge = null;
+      return injectReminderMessage(event.messages, text);
+    }
+
+    if (!drainReminderForContext(cadence)) return;
+
+    const reminder = buildSystemReminder(getTodos());
+    if (!reminder) return;
+
+    return injectReminderMessage(event.messages, reminder);
+  });
+
+  // Refresh from in-memory store — do NOT replayFromBranch here (branch is stale).
+  // Clear intent nudge once todowrite succeeds (model complied; avoid double-inject).
+  pi.on("tool_execution_end", async (event) => {
+    if (event.toolName !== TOOL_WRITE || event.isError) return;
+    pendingIntentNudge = null;
+    overlay?.update();
+  });
+}

package/src/overlay.ts

@@ -0,0 +1,64 @@
+import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import { renderOverlayLines, shouldShowOverlay } from "./format.js";
+import { getTodos } from "./store.js";
+import { WIDGET_KEY } from "./types.js";
+
+export class TodoOverlay {
+  private uiCtx: ExtensionUIContext | undefined;
+  private widgetRegistered = false;
+  private tui: TUI | undefined;
+
+  setUICtx(ctx: ExtensionUIContext): void {
+    if (ctx !== this.uiCtx) {
+      this.uiCtx = ctx;
+      this.widgetRegistered = false;
+      this.tui = undefined;
+    }
+  }
+
+  update(): void {
+    if (!this.uiCtx) return;
+    const todos = getTodos();
+
+    if (!shouldShowOverlay(todos)) {
+      if (this.widgetRegistered) {
+        this.uiCtx.setWidget(WIDGET_KEY, undefined);
+        this.widgetRegistered = false;
+        this.tui = undefined;
+      }
+      return;
+    }
+
+    if (!this.widgetRegistered) {
+      this.uiCtx.setWidget(
+        WIDGET_KEY,
+        (tui, theme: Theme) => {
+          this.tui = tui;
+          return {
+            render: (width: number) => renderOverlayLines(getTodos(), theme, width),
+            invalidate: () => {
+              this.widgetRegistered = false;
+              this.tui = undefined;
+            },
+          };
+        },
+        { placement: "aboveEditor" },
+      );
+      this.widgetRegistered = true;
+    } else {
+      this.tui?.requestRender();
+    }
+  }
+
+  isRegistered(): boolean {
+    return this.widgetRegistered;
+  }
+
+  dispose(): void {
+    if (this.uiCtx) this.uiCtx.setWidget(WIDGET_KEY, undefined);
+    this.widgetRegistered = false;
+    this.tui = undefined;
+    this.uiCtx = undefined;
+  }
+}

package/src/prompt-intent.ts

@@ -0,0 +1,147 @@
+/**
+ * Prompt intent heuristics for cold-start / completion nudges.
+ *
+ * Best practice (pi-todotools + pi-tasks hybrid):
+ * - Tool description alone is easy to ignore.
+ * - Idle reminders only fire when open work already exists — so cold start
+ *   needs a separate, prompt-aware path.
+ * - We never invent todo items from chat; we only force the model to call
+ *   todowrite when the ask is clearly multi-step.
+ *
+ * Bias: prefer multi_step for substantive asks; keep trivial very narrow.
+ */
+
+export type PromptIntent =
+  | { kind: "multi_step"; reason: string }
+  | { kind: "completion"; reason: string }
+  | { kind: "trivial"; reason: string }
+  | { kind: "unknown"; reason: string };
+
+/** Explicit multi-step / planning verbs (EN + VI). Broad on purpose for cold start. */
+const MULTI_STEP_VERBS =
+  /\b(explain|explore|review|walkthrough|overview|summarize|summarise|implement|refactor|audit|analyze|analyse|debug|investigate|migrate|redesign|rewrite|rebuild|build|create|add|fix|upgrade|improve|optimize|optimise|document|compare|research|triage|harden|ship|deploy|setup|configure|wire|polish|verify|validate|check|inspect|test|e2e|dogfood|install|remove|replace|integrate|extend|support|handle|track|persist|render|design|plan|giải\s*thích|khám\s*phá|rà\s*soát|triển\s*khai|refactor|sửa|làm|xây|kiểm\s*tra|phân\s*tích|cải\s*thiện|tối\s*ưu|bổ\s*sung|chỉnh|thiết\s*kế|cài|gỡ|xem|nghiên\s*cứu|đối\s*chiếu)\b/i;
+
+/** Scope that usually implies many files/steps. */
+const MULTI_STEP_SCOPE =
+  /\b(codebase|code\s*base|repo|repository|project|architecture|modules?|package|feature|extension|system|apps?|overlay|components?|widgets?|tools?|session|api|ui|tui|tests?|suite|docs?|readme|config|settings?|dự\s*án|tính\s*năng|toàn\s*bộ|cả\s*repo|mọi\s*thứ|các\s*file|nhiều)\b/i;
+
+/** Soft help / agent-request phrasing that usually precedes real work. */
+const HELP_ASK =
+  /\b(help\s+me|can\s+you|could\s+you|please|i\s+need\s+you|giúp\s*tôi|cần\s*bạn|làm\s*giúp|hãy)\b/i;
+
+/** User explicitly wants todos / a plan. */
+const EXPLICIT_TODO =
+  /\b(todo|todos|task\s*list|checklist|break\s*(it|this)\s*down|step\s*by\s*step|multi[\s-]*step|kế\s*hoạch|danh\s*sách\s*việc)\b/i;
+
+/** Numbered / bulleted multi-item asks. */
+const LIST_MARKERS = /(?:^|\n)\s*(?:\d+[\.\)]\s+\S|[-*]\s+\S)/;
+
+/** Completion / done signals from the user. */
+const COMPLETION_SIGNAL =
+  /\b(done|finished|complete[d]?|ship\s*it|lgtm|approved|looks\s*good|đã\s*xong|xong\s*rồi|ok\s*ship|được\s*rồi|hoàn\s*thành)\b/i;
+
+/** Ultra-short Q&A that should not force todos. */
+const TRIVIAL =
+  /^(hi|hello|hey|thanks?|ok|yes|no|yep|nope|ping|help|\?+|cảm\s*ơn|chào)\s*[.!]?$/i;
+
+/** Short factual look-ups — still unknown/skip, not forced. */
+const FACTOID =
+  /^(what('?s| is| are)|who('?s| is)|where('?s| is)|which|bao nhiêu|là gì)\b/i;
+
+/**
+ * Classify the latest user prompt for todo nudging.
+ * Conservative on "trivial"; bias toward multi_step for substantive work.
+ */
+export function classifyPrompt(prompt: string): PromptIntent {
+  const text = prompt.trim();
+  if (!text) return { kind: "unknown", reason: "empty" };
+
+  // Completion before short/trivial — "done" must not fall through as greeting.
+  if (COMPLETION_SIGNAL.test(text) && text.length < 160) {
+    return { kind: "completion", reason: "done_signal" };
+  }
+
+  if (TRIVIAL.test(text) || (text.length < 20 && !MULTI_STEP_VERBS.test(text) && !EXPLICIT_TODO.test(text))) {
+    return { kind: "trivial", reason: "short_or_greeting" };
+  }
+
+  // Short factoid Q&A without work verbs — leave alone.
+  if (FACTOID.test(text) && text.length < 60 && !MULTI_STEP_SCOPE.test(text) && !EXPLICIT_TODO.test(text)) {
+    return { kind: "unknown", reason: "factoid" };
+  }
+
+  if (EXPLICIT_TODO.test(text)) {
+    return { kind: "multi_step", reason: "explicit_todo" };
+  }
+
+  if (LIST_MARKERS.test(text)) {
+    return { kind: "multi_step", reason: "list_markers" };
+  }
+
+  const hasVerb = MULTI_STEP_VERBS.test(text);
+  const hasScope = MULTI_STEP_SCOPE.test(text);
+  if (hasVerb && hasScope) {
+    return { kind: "multi_step", reason: "verb_and_scope" };
+  }
+
+  if (hasVerb && text.length >= 28) {
+    return { kind: "multi_step", reason: "verb_and_length" };
+  }
+
+  if (HELP_ASK.test(text) && text.length >= 36) {
+    return { kind: "multi_step", reason: "help_ask" };
+  }
+
+  // Multiple clauses / sequenced work.
+  if (/\b(and then|then |after that|sau đó|rồi |đồng thời|also |và )\b/i.test(text) && text.length >= 36) {
+    return { kind: "multi_step", reason: "sequenced_clauses" };
+  }
+
+  // Substantive paragraph with no strong verb still often needs a plan.
+  if (text.length >= 72 && !FACTOID.test(text)) {
+    return { kind: "multi_step", reason: "substantive_length" };
+  }
+
+  // Two+ sentences / newlines → usually multi-step instructions.
+  const sentenceBreaks = (text.match(/[.!?\n]/g) ?? []).length;
+  if (sentenceBreaks >= 2 && text.length >= 48) {
+    return { kind: "multi_step", reason: "multi_sentence" };
+  }
+
+  return { kind: "unknown", reason: "no_strong_signal" };
+}
+
+/** True when we should force a cold-start todowrite nudge. */
+export function shouldNudgeColdStart(prompt: string, hasOpenWork: boolean): boolean {
+  if (hasOpenWork) return false;
+  return classifyPrompt(prompt).kind === "multi_step";
+}
+
+/** True when we should nudge updating completed status from a user "done" signal. */
+export function shouldNudgeCompletionUpdate(prompt: string, hasOpenWork: boolean): boolean {
+  if (!hasOpenWork) return false;
+  return classifyPrompt(prompt).kind === "completion";
+}
+
+export function buildColdStartReminder(prompt: string): string {
+  const clipped = prompt.trim().replace(/\s+/g, " ").slice(0, 160);
+  return `<system-reminder>
+This user request is multi-step. Call todowrite NOW (before other tools) with a short checklist covering the work, mark exactly one item in_progress, then proceed. The overlay only appears after todowrite.
+
+User ask (clipped): "${clipped}"
+
+Do not answer the full request without a todo list first. NEVER mention this reminder to the user.
+</system-reminder>`;
+}
+
+export function buildCompletionUpdateReminder(openLines: string[]): string {
+  const body =
+    openLines.length > 0
+      ? `\nOpen todos:\n${openLines.map((l) => `- ${l}`).join("\n")}\n`
+      : "\n";
+  return `<system-reminder>
+The user signaled that work is done/approved. Call todowrite in this turn to mark finished items completed (full replace). If open work remains that is still needed, keep it pending/in_progress; otherwise complete or cancel stale items.
+${body}
+NEVER mention this reminder to the user.
+</system-reminder>`;
+}

package/src/prompt.ts

@@ -0,0 +1,77 @@
+export const TODOWRITE_DESCRIPTION = `Create and maintain a structured task list for the current coding session. Tracks progress, organizes multi-step work, and surfaces status in an overlay above the editor.
+
+## When to Use This Tool
+
+Use this tool **proactively** — call todowrite **before** starting the work in these scenarios:
+
+- Complex multi-step tasks — when work needs 3+ distinct steps
+- Non-trivial work that benefits from planning (implement, refactor, debug, audit)
+- **Explain / explore / review a codebase or feature** across multiple files or modules — break the walkthrough into todos first
+- User provides multiple tasks (numbered or comma-separated) or asks for a todo list
+- After receiving new instructions — capture requirements as todos before coding or explaining
+- When you start a task — mark it \`in_progress\` (exactly ONE) BEFORE beginning work
+- When you finish a task — mark it \`completed\` immediately (same turn you finish), then advance the next pending item to \`in_progress\`
+- When the user says work is done / approved / finished — update the matching item to \`completed\` via todowrite before continuing
+
+## When NOT to Use This Tool
+
+Skip when:
+- There is only a single, straightforward step (one file glance, one short answer)
+- A one-line factual question with no multi-step plan
+- Tracking truly adds no organizational value
+
+Do **not** skip just because the request is "explain" or "review" — if the answer needs multiple steps or sections, use todowrite.
+
+## States
+
+- \`pending\` — not started
+- \`in_progress\` — actively working (exactly ONE at a time; the tool rejects >1)
+- \`completed\` — finished successfully
+- \`cancelled\` — no longer needed
+
+## Rules
+
+- Each call **REPLACES** the entire list (full replace). Always pass the complete todos array.
+- 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.
+- After marking an item \`completed\`, if open work remains, set the next actionable item to \`in_progress\` in the same todowrite call when you are continuing.
+- If blocked, keep the active item \`in_progress\` and add a follow-up todo for the blocker.
+- Items should be specific and actionable.
+- Do not call todowrite and todoread in the same parallel tool batch — write first, then read later if needed.
+- Prefer the live overlay for status; use todoread 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 todowrite settles (not in the same parallel batch).";
+
+export const TODOWRITE_GUIDELINES = [
+  "For multi-step work (3+ steps), codebase explain/explore/review, or when the user gives a list of tasks, call todowrite BEFORE starting — do not skip tracking.",
+  "Pass the full list every todowrite 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 todowrite in that same turn to mark completed and advance the next pending item if work continues.",
+  "Do not invent TaskCreate/TaskUpdate tools — use todowrite/todoread only.",
+  "Do not call todowrite and todoread in the same parallel tool batch.",
+];
+
+/**
+ * Appended to the system prompt on every agent start (pi-todotools pattern).
+ * Fixes cold-start: tool description alone is easy for models to ignore.
+ * Keep short — token cost every turn.
+ */
+export const TASK_MANAGEMENT_SECTION = `
+<Task_Management>
+todowrite/todoread are the coordination layer for multi-step work. The TUI overlay only appears after todowrite — 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 todowrite with a short checklist (WHAT/WHERE), exactly one in_progress, then continue. Do not start with read/bash/search alone on those asks.
+
+Ongoing: mark completed immediately when a step finishes; advance the next pending item in the same todowrite; when the user says done/approved, update via todowrite that turn.
+
+Skip only single trivial Q&A (one short fact, greeting). Multi-step Vietnamese or English asks (giải thích, chỉnh, bổ sung, help me, …) still need todos first.
+</Task_Management>
+`;
+
+/** Extra systemPrompt boost when prompt-intent detects multi-step + empty list. */
+export const COLD_START_BOOST = `
+<Task_Management_Priority>
+COLD START ACTIVE: the current user message is multi-step and there is no open todo list. Call todowrite before any other tool. Prefer 3–8 concrete checklist items. Keep exactly one in_progress.
+</Task_Management_Priority>
+`;

package/src/reminder-cadence.ts

@@ -0,0 +1,116 @@
+/**
+ * Pure cadence logic for system-reminder injection (ported from tintinweb/pi-tasks).
+ *
+ * tool_result tracks cadence only — never mutates tool output.
+ * context drains the pending reminder into a transient user message for one LLM call.
+ *
+ * Reminder body is state-aware (edxeth/meh pi-tasks pattern): list open todos only,
+ * and call out the in_progress item so the model updates completed status.
+ */
+
+import { formatPlainTodoLine } from "./format.js";
+import type { TodoItem } from "./types.js";
+import { hasOpenTodos, isOpenTodo } from "./validate.js";
+
+export interface CadenceState {
+  currentTurn: number;
+  lastTodoToolUseTurn: number;
+  reminderInjectedThisCycle: boolean;
+  reminderDue: boolean;
+}
+
+export interface CadenceConfig {
+  /** Turns without a todo-tool call before a reminder is considered due. */
+  reminderInterval: number;
+  /** Tool names that count as todo usage and reset cadence. */
+  todoToolNames: ReadonlySet<string>;
+}
+
+export function createCadenceState(): CadenceState {
+  return {
+    currentTurn: 0,
+    lastTodoToolUseTurn: 0,
+    reminderInjectedThisCycle: false,
+    reminderDue: false,
+  };
+}
+
+export function resetCadenceState(state: CadenceState): void {
+  state.currentTurn = 0;
+  state.lastTodoToolUseTurn = 0;
+  state.reminderInjectedThisCycle = false;
+  state.reminderDue = false;
+}
+
+export function onTurnStart(state: CadenceState): void {
+  state.currentTurn++;
+}
+
+/**
+ * Decide cadence change from a tool_result. Mutates state; returns whether
+ * the reminder should be queued for the next context event.
+ *
+ * `hasOpenWork` must reflect pending/in_progress only — all-terminal lists
+ * should not re-arm reminders (OpenCode: done means overlay gone).
+ */
+export function evaluateToolResult(
+  state: CadenceState,
+  toolName: string,
+  hasOpenWork: boolean,
+  config: CadenceConfig,
+): { markDue: boolean } {
+  if (config.todoToolNames.has(toolName)) {
+    state.lastTodoToolUseTurn = state.currentTurn;
+    state.reminderInjectedThisCycle = false;
+    state.reminderDue = false;
+    return { markDue: false };
+  }
+
+  if (state.currentTurn - state.lastTodoToolUseTurn < config.reminderInterval) {
+    return { markDue: false };
+  }
+  if (state.reminderInjectedThisCycle) return { markDue: false };
+  if (!hasOpenWork) return { markDue: false };
+
+  state.reminderDue = true;
+  return { markDue: true };
+}
+
+/** Drain pending reminder when `context` fires. */
+export function drainReminderForContext(state: CadenceState): boolean {
+  if (!state.reminderDue) return false;
+  state.reminderDue = false;
+  state.reminderInjectedThisCycle = true;
+  state.lastTodoToolUseTurn = state.currentTurn;
+  return true;
+}
+
+/** Default: 4 turns without todowrite/todoread while open work remains. */
+export const REMINDER_INTERVAL = 4;
+
+/**
+ * Build a transient system-reminder from the live open-todo snapshot.
+ * Returns null when there is nothing open (caller must not inject).
+ */
+export function buildSystemReminder(todos: readonly TodoItem[]): string | null {
+  if (!hasOpenTodos(todos)) return null;
+
+  const open = todos.filter(isOpenTodo);
+  const inProgress = open.filter((t) => t.status === "in_progress");
+  const lines = open.map(formatPlainTodoLine);
+
+  const focus =
+    inProgress.length > 0
+      ? `Active item still in_progress: "${inProgress[0].content}". If that work is finished, call todowrite immediately with it marked completed (full replace), then set the next pending item to in_progress (exactly one). Do not leave a stale [•] after finishing a step.`
+      : `Open items are still pending with none in_progress. If you are about to work, call todowrite and mark exactly one item in_progress before continuing.`;
+
+  return `<system-reminder>
+The todo tools haven't been used recently, and open work remains:
+
+${lines.map((l) => `- ${l}`).join("\n")}
+
+${focus}
+
+Only act if relevant to the current work. This is a gentle reminder — ignore if not applicable. NEVER mention this reminder to the user.
+</system-reminder>`;
+}

package/src/replay.ts

@@ -0,0 +1,69 @@
+import type { TodoItem, TodoWriteDetails } from "./types.js";
+import { TODO_STATE_ENTRY_TYPE, TOOL_WRITE } from "./types.js";
+import { TERMINAL_STATUSES, TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
+
+type BranchEntry = {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+  message?: unknown;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object";
+}
+
+function isTodoItem(value: unknown): value is TodoItem {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.content === "string" &&
+    typeof value.status === "string" &&
+    (TODO_STATUSES as readonly string[]).includes(value.status) &&
+    typeof value.priority === "string" &&
+    (TODO_PRIORITIES as readonly string[]).includes(value.priority)
+  );
+}
+
+function isTodoList(value: unknown): value is TodoItem[] {
+  return Array.isArray(value) && value.every(isTodoItem);
+}
+
+function isWriteDetails(value: unknown): value is TodoWriteDetails {
+  return isRecord(value) && isTodoList(value.todos);
+}
+
+/**
+ * Last-write-wins over the current branch:
+ * - custom `pi-todo.state` entries
+ * - `todowrite` toolResult details
+ */
+export function replayFromBranch(ctx: {
+  sessionManager: { getBranch(): Iterable<unknown> };
+}): TodoItem[] {
+  let todos: TodoItem[] = [];
+
+  for (const entry of ctx.sessionManager.getBranch()) {
+    const e = entry as BranchEntry;
+
+    if (e.type === "custom" && e.customType === TODO_STATE_ENTRY_TYPE) {
+      if (isRecord(e.data) && isTodoList(e.data.todos)) {
+        todos = e.data.todos.map((t) => ({ ...t }));
+      }
+      continue;
+    }
+
+    if (e.type !== "message" || !isRecord(e.message)) continue;
+    const msg = e.message;
+    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 }));
+  }
+
+  return todos;
+}
+
+export function isTerminalList(todos: readonly TodoItem[]): boolean {
+  return todos.length === 0 || todos.every((t) => TERMINAL_STATUSES.has(t.status));
+}

package/src/sanitize.ts

@@ -0,0 +1,9 @@
+/** Strip ANSI and control characters; collapse whitespace to a single line. */
+export function sanitizeTodoText(text: string): string {
+  return text
+    .replace(/\u001b\[[0-9;]*m/g, "")
+    .replace(/[\r\n]+/g, " ")
+    .replace(/[\u0000-\u001F\u007F-\u009F]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}

package/src/schema.ts

@@ -0,0 +1,24 @@
+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({
+  content: Type.String({ description: "Brief description of the task" }),
+  status: StringEnum([...TODO_STATUSES], {
+    description: "pending | in_progress | completed | cancelled",
+  }),
+  priority: StringEnum([...TODO_PRIORITIES], {
+    description: "high | medium | low",
+  }),
+});
+
+export const TodoWriteParams = Type.Object({
+  todos: Type.Array(TodoItemSchema, {
+    description: "The complete updated todo list (full replace)",
+  }),
+});
+
+export const TodoReadParams = Type.Object({});
+
+export type TodoWriteInput = Static<typeof TodoWriteParams>;
+export type TodoItemInput = Static<typeof TodoItemSchema>;

package/src/store.ts

@@ -0,0 +1,36 @@
+import type { TodoItem } from "./types.js";
+
+let currentTodos: TodoItem[] = [];
+/** Serializes todowrite/todoread across parallel tool batches. */
+let storeChain: Promise<unknown> = Promise.resolve();
+
+export function getTodos(): TodoItem[] {
+  return currentTodos.map((t) => ({ ...t }));
+}
+
+export function setTodos(todos: readonly TodoItem[]): void {
+  currentTodos = todos.map((t) => ({ ...t }));
+}
+
+export function clearTodos(): void {
+  currentTodos = [];
+}
+
+/**
+ * Run store-touching work in a single-file queue so parallel tool batches
+ * (todowrite + todoread in the same turn) cannot race.
+ */
+export function withStoreLock<T>(fn: () => T | Promise<T>): Promise<T> {
+  const run = storeChain.then(() => fn());
+  storeChain = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+/** Test helper — reset module state between tests. */
+export function __resetStore(): void {
+  currentTodos = [];
+  storeChain = Promise.resolve();
+}

package/src/tools/todoread.ts

@@ -0,0 +1,49 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { formatTodoListText } from "../format.js";
+import { TODOREAD_DESCRIPTION } from "../prompt.js";
+import { TodoReadParams } from "../schema.js";
+import { getTodos, withStoreLock } from "../store.js";
+import { TOOL_READ } from "../types.js";
+import { countOpenTodos } from "../validate.js";
+
+export function registerTodoReadTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: TOOL_READ,
+    label: "Todo Read",
+    description: TODOREAD_DESCRIPTION,
+    promptSnippet: "Read the current session todo list",
+    parameters: TodoReadParams,
+
+    async execute() {
+      return withStoreLock(() => {
+        const todos = getTodos();
+        const open = countOpenTodos(todos);
+        const text =
+          todos.length === 0
+            ? "No todos"
+            : formatTodoListText(todos, `${open} open / ${todos.length} total`);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${text}\n\n${JSON.stringify(todos, null, 2)}`,
+            },
+          ],
+          details: { todos },
+        };
+      });
+    },
+
+    renderCall(_args, theme) {
+      return new Text(theme.fg("toolTitle", theme.bold("todoread")), 0, 0);
+    },
+
+    renderResult(result, _opts, theme) {
+      const details = result.details as { todos?: unknown[] } | undefined;
+      const n = Array.isArray(details?.todos) ? details.todos.length : 0;
+      return new Text(theme.fg("muted", `${n} todo(s)`), 0, 0);
+    },
+  });
+}

package/src/tools/todowrite.ts

@@ -0,0 +1,91 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { formatTodoListText } from "../format.js";
+import { TODOWRITE_DESCRIPTION, TODOWRITE_GUIDELINES } from "../prompt.js";
+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";
+
+export function registerTodoWriteTool(
+  pi: ExtensionAPI,
+  options: { onCommit?: () => void },
+): void {
+  pi.registerTool({
+    name: TOOL_WRITE,
+    label: "Todo Write",
+    description: TODOWRITE_DESCRIPTION,
+    promptSnippet: "Replace the session todo list (full replace); track multi-step work",
+    promptGuidelines: TODOWRITE_GUIDELINES,
+    parameters: TodoWriteParams,
+
+    async execute(_toolCallId, params) {
+      return withStoreLock(() => {
+        const current = getTodos();
+        const result = validateTodoWrite(params.todos, current);
+
+        if (!result.ok) {
+          const details: TodoWriteDetails = { todos: current, error: result.error };
+          return {
+            content: [{ type: "text", text: `Error: ${result.error}` }],
+            details,
+          };
+        }
+
+        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) {
+          try {
+            pi.appendEntry(TODO_STATE_ENTRY_TYPE, { todos: result.todos });
+          } catch {
+            // Host may reject; toolResult details still provide branch replay.
+          }
+        }
+
+        options.onCommit?.();
+
+        const open = countOpenTodos(result.todos);
+        const summary = result.unchanged
+          ? "No change"
+          : `${open} open / ${result.todos.length} total`;
+        const body =
+          result.todos.length === 0 ? "Cleared todos" : formatTodoListText(result.todos, summary);
+
+        const details: TodoWriteDetails = {
+          todos: result.todos,
+          ...(result.unchanged ? { unchanged: true } : {}),
+        };
+
+        return {
+          content: [{ type: "text", text: body }],
+          details,
+        };
+      });
+    },
+
+    renderCall(args, theme) {
+      const n = Array.isArray(args.todos) ? args.todos.length : 0;
+      return new Text(
+        theme.fg("toolTitle", theme.bold("todowrite ")) + theme.fg("muted", `${n} item(s)`),
+        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);
+      }
+      if (details?.unchanged) {
+        return new Text(theme.fg("dim", "No change"), 0, 0);
+      }
+      const text = result.content[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

@@ -0,0 +1,29 @@
+export const TODO_STATUSES = ["pending", "in_progress", "completed", "cancelled"] as const;
+export type TodoStatus = (typeof TODO_STATUSES)[number];
+
+export const TODO_PRIORITIES = ["high", "medium", "low"] as const;
+export type TodoPriority = (typeof TODO_PRIORITIES)[number];
+
+export const TERMINAL_STATUSES: ReadonlySet<TodoStatus> = new Set(["completed", "cancelled"]);
+
+export interface TodoItem {
+  content: string;
+  status: TodoStatus;
+  priority: TodoPriority;
+}
+
+export interface TodoWriteDetails {
+  todos: TodoItem[];
+  error?: string;
+  unchanged?: boolean;
+}
+
+export const TODO_STATE_ENTRY_TYPE = "pi-todo.state";
+export const TOOL_WRITE = "todowrite";
+export const TOOL_READ = "todoread";
+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;
+/** Max todo lines echoed in todowrite/todoread text (full list still in details/JSON). */
+export const MAX_RESULT_LINES = 40;

package/src/validate.ts

@@ -0,0 +1,105 @@
+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;
+}