pi-jar 0.1.0

package/src/split-view.ts

@@ -0,0 +1,74 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export interface SplitTheme { fg(color: string, text: string): string }
+
+export interface SplitLayout {
+  /** First content row (0-based, local to the component). */
+  top: number;
+  /** Number of content rows. */
+  rows: number;
+  /** Width of the left pane content; 0 when collapsed to a single column. */
+  leftWidth: number;
+  /** Column where right-pane content starts. */
+  bodyX: number;
+  /** First footer row. */
+  footerTop: number;
+}
+
+const pad = (text: string, width: number) => {
+  const value = truncateToWidth(text, Math.max(0, width));
+  return value + " ".repeat(Math.max(0, width - visibleWidth(value)));
+};
+
+/** Sidebar width for a split view, or 0 when the terminal is too narrow for two panes. */
+export function sidebarWidth(width: number, min = 18, max = 32): number {
+  if (width < 64) return 0;
+  return Math.max(min, Math.min(max, Math.round(width * 0.26)));
+}
+
+/**
+ * Frame a two-pane view: `left` and `right` are already-windowed, styled rows.
+ * Left pane is omitted when `leftWidth` is 0. Every line fits `width` exactly.
+ */
+export function splitFrame(theme: SplitTheme, width: number, title: string, left: readonly string[], right: readonly string[],
+  footer: readonly string[], rows: number, leftWidth = sidebarWidth(width)): { lines: string[]; layout: SplitLayout } {
+  const w = Math.max(12, width);
+  const dim = (text: string) => theme.fg("dim", text);
+  const heading = " " + title + " ";
+  const top = theme.fg("accent", "╭─" + truncateToWidth(heading, Math.max(0, w - 6)) + "─".repeat(Math.max(0, w - 4 - visibleWidth(truncateToWidth(heading, Math.max(0, w - 6))))) + "×╮");
+  const lines = [top];
+  const split = leftWidth > 0;
+  const bodyWidth = split ? w - leftWidth - 6 : w - 4;
+  for (let row = 0; row < rows; row++) {
+    const body = pad(right[row] ?? "", bodyWidth);
+    lines.push(split
+      ? dim("│ ") + pad(left[row] ?? "", leftWidth) + dim("│ ") + body + dim(" │")
+      : dim("│ ") + body + dim(" │"));
+  }
+  lines.push(dim("├" + (split ? "─".repeat(leftWidth + 1) + "┴" + "─".repeat(Math.max(0, w - leftWidth - 4)) : "─".repeat(w - 2)) + "┤"));
+  const footerTop = lines.length;
+  for (const line of footer) lines.push(dim("│ ") + pad(line, w - 4) + dim(" │"));
+  lines.push(dim("╰" + "─".repeat(w - 2) + "╯"));
+  return {
+    lines: lines.map((line) => truncateToWidth(line, w)),
+    layout: { top: 1, rows, leftWidth: split ? leftWidth : 0, bodyX: split ? leftWidth + 4 : 2, footerTop }
+  };
+}
+
+/** Available content rows for a full-height overlay with `chrome` fixed rows. */
+export function contentRows(chrome: number, min = 4): number {
+  return Math.max(min, (process.stdout.rows ?? 24) - chrome);
+}
+
+/**
+ * Numbered options, one per row: `❯ 1  label` for the selected one (or none when `selected` is -1).
+ * Use for any set of choices so they read as a list rather than a crowded single line.
+ */
+export function optionList(theme: SplitTheme & { bold?: (text: string) => string }, labels: readonly string[], selected: number, keys?: readonly string[]): string[] {
+  return labels.map((label, index) => {
+    const active = index === selected;
+    const key = keys?.[index] ?? String(index + 1);
+    const text = `${active ? "❯" : " "} ${key.padEnd(2)} ${label}`;
+    return theme.fg(active ? "accent" : "muted", active ? theme.bold?.(text) ?? text : text);
+  });
+}

package/src/status.ts

@@ -0,0 +1,71 @@
+import type { RoleStatus, RoleState } from "./roles.ts";
+
+export const ROLE_PREFIX = "pi-jar.role.";
+export const ACTIVE_STATES = new Set<RoleState>(["thinking", "working", "reviewing"]);
+export const ROLE_TTL_MS = 30_000;
+const STATES = new Set<RoleState>(["idle", "thinking", "working", "waiting", "reviewing", "done", "failed"]);
+
+/** Remove terminal controls from third-party status text before placing it in our footer. */
+export function cleanText(value: string, limit = 72): string {
+  return value.slice(0, 4096)
+    .replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)?|\x1b\[[0-?]*[ -/]*[@-~]|\x1b./g, "")
+    .replace(/[\x00-\x1f\x7f-\x9f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, limit);
+}
+
+export interface JarRole extends RoleStatus {
+  expiresAt?: number;
+}
+
+export interface JarStatus {
+  roles: JarRole[];
+  extras: string[];
+}
+
+/** Explicit opt-in contract; never guess teammate state from arbitrary status prose. */
+export function collectStatuses(statuses: ReadonlyMap<string, string>, now: number): JarStatus {
+  const roles: JarRole[] = [];
+  const extras: string[] = [];
+  for (const [rawKey, rawValue] of statuses) {
+    const key = cleanText(rawKey, 48);
+    if (!key || typeof rawValue !== "string") continue;
+    if (rawKey.startsWith("pi-jar.quota.")) continue;
+    if (!rawKey.startsWith(ROLE_PREFIX)) {
+      const value = cleanText(rawValue);
+      // pi-jar's own indicators (such as `role:default`) are already self-describing.
+      if (value) extras.push(rawKey.startsWith("pi-jar.") ? value : `${key}: ${value}`);
+      continue;
+    }
+    const id = rawKey.slice(ROLE_PREFIX.length);
+    if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(id)) continue;
+    try {
+      if (rawValue.length > 4096) throw new Error("oversized status");
+      const data: unknown = JSON.parse(rawValue);
+      if (!data || typeof data !== "object") throw new Error("invalid status");
+      const role = data as Record<string, unknown>;
+      if (typeof role.name !== "string" || typeof role.state !== "string" || !STATES.has(role.state as RoleState)) {
+        throw new Error("invalid role");
+      }
+      const state = role.state as RoleState;
+      const expiresAt = role.expiresAt;
+      if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt) || expiresAt <= now || expiresAt > now + ROLE_TTL_MS) {
+        extras.push(`${id}: unavailable`);
+        continue;
+      }
+      const name = cleanText(role.name, 32) || id;
+      roles.push({
+        id,
+        name,
+        label: cleanText(typeof role.label === "string" ? role.label : name, 12) || id,
+        state,
+        task: typeof role.task === "string" ? cleanText(role.task, 48) : undefined,
+        expiresAt: typeof expiresAt === "number" ? expiresAt : undefined
+      });
+    } catch {
+      extras.push(`${id}: unavailable`);
+    }
+  }
+  return { roles: roles.slice(0, 16), extras: extras.slice(0, 16) };
+}

package/src/suggest.ts

@@ -0,0 +1,89 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { cleanText } from "./status.ts";
+
+export const SUGGEST_TOOL = "jar_suggest";
+const REMINDER_TYPE = "pi-jar.suggest-reminder";
+const MAX_SUGGESTION = 160;
+
+/** The next-prompt suggestion shown as ghost text in an empty composer. Session-only, never persisted. */
+export class SuggestionState {
+  private value: string | undefined;
+  private readonly listeners = new Set<() => void>();
+  get text(): string | undefined { return this.value; }
+  set(text: string): boolean {
+    const next = cleanText(text.replace(/\s+/g, " "), MAX_SUGGESTION);
+    if (!next) return false;
+    if (next !== this.value) { this.value = next; this.emit(); }
+    return true;
+  }
+  clear(): void { if (this.value !== undefined) { this.value = undefined; this.emit(); } }
+  onChange(listener: () => void): () => void { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+  private emit(): void { for (const listener of this.listeners) listener(); }
+}
+
+export interface SuggestionOptions {
+  enabled: () => boolean;
+  /** Skip enforcement while another workflow owns the next step (plan review, goal loop). */
+  skip: () => boolean;
+}
+
+/** Ask the agent for one next-prompt suggestion per finished request, like an inline autocomplete. */
+export function registerSuggestions(pi: ExtensionAPI, state: SuggestionState, options: SuggestionOptions): { sync(): void } {
+  let suggested = false;
+  let reminded = false;
+  pi.registerTool?.({
+    name: SUGGEST_TOOL,
+    label: "suggest",
+    description: "Offer the user one short next prompt. It appears as dimmed ghost text in their input box; Tab accepts it for editing. Call it once, last, when you finish a request.",
+    promptSnippet: "Finish each completed request by calling jar_suggest with the most useful next prompt for the user.",
+    promptGuidelines: [
+      "When you finish the user's request, call jar_suggest exactly once as your final action with the single most useful next prompt the user could send (imperative, one line, under 120 characters, written as the user would type it, e.g. \"Run the full test suite\").",
+      "Do not mention jar_suggest or the suggestion in your reply, and do not call it mid-task or while waiting for an answer."
+    ],
+    parameters: Type.Object({ suggestion: Type.String({ description: "The user's likely next prompt, one line." }) }),
+    execute: async (_id, params) => {
+      const ok = state.set(params.suggestion ?? "");
+      suggested ||= ok;
+      return { content: [{ type: "text", text: ok ? "Suggestion shown to the user. End your turn now." : "Suggestion was empty; skipped." }], details: { suggestion: state.text }, terminate: true };
+    },
+    renderCall() { return new Text("", 0, 0); },
+    renderResult(result, _options, theme) {
+      const text = (result.details as { suggestion?: string } | undefined)?.suggestion;
+      return new Text(text ? theme.fg("dim", "↳ next: " + text + "  (Tab in the input box)") : "", 0, 0);
+    }
+  });
+
+  const sync = () => {
+    if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+    const active = pi.getActiveTools();
+    const has = active.includes(SUGGEST_TOOL);
+    if (options.enabled() && !has && pi.getAllTools().some((tool) => tool.name === SUGGEST_TOOL)) pi.setActiveTools([...active, SUGGEST_TOOL]);
+    else if (!options.enabled() && has) pi.setActiveTools(active.filter((name) => name !== SUGGEST_TOOL));
+    if (!options.enabled()) state.clear();
+  };
+
+  pi.on("input", (event) => {
+    if (event.source !== "interactive") return;
+    suggested = false;
+    reminded = false;
+    state.clear();
+  });
+  pi.on("agent_start", () => { state.clear(); });
+  pi.on("session_start", () => { suggested = false; reminded = false; state.clear(); });
+  pi.on("session_tree", () => { state.clear(); });
+  pi.on("context", async (event) => ({ messages: event.messages.filter((raw) => (raw as { customType?: string }).customType !== REMINDER_TYPE) }));
+
+  pi.on("agent_before_settle", (event) => {
+    if (!options.enabled() || options.skip() || event.continue || event.outcome !== "completed" || suggested || reminded) return;
+    if (typeof pi.getActiveTools === "function" && !pi.getActiveTools().includes(SUGGEST_TOOL)) return;
+    reminded = true;
+    return {
+      entries: [{ type: "custom_message", customType: REMINDER_TYPE, display: false,
+        content: "[PI-JAR] Call jar_suggest now with the single most useful next prompt for the user. Do not add any other text." }],
+      continue: true
+    };
+  });
+  return { sync };
+}

package/src/task-tool.ts

@@ -0,0 +1,135 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import type { Todo } from "./tasks.ts";
+import { TODO_STATUSES, TodoStore, todoMark } from "./tasks.ts";
+
+const ACTIONS = ["write", "list", "add", "start", "done", "open", "edit", "delete"] as const;
+const Action = Type.Unsafe<(typeof ACTIONS)[number]>({ type: "string", enum: ACTIONS as any });
+const Status = Type.Unsafe<(typeof TODO_STATUSES)[number]>({ type: "string", enum: TODO_STATUSES as any });
+
+const Parameters = Type.Object({
+  todos: Type.Optional(Type.Array(Type.Object({
+    content: Type.String({ description: "Imperative task title, e.g. \"Run the tests\"." }),
+    status: Status,
+    activeForm: Type.Optional(Type.String({ description: "Present-continuous form shown while it runs, e.g. \"Running the tests\"." }))
+  }), { description: "The complete, updated task list. Replaces the current list." })),
+  action: Type.Optional(Action),
+  id: Type.Optional(Type.String({ description: "Task id for start/done/open/edit/delete." })),
+  title: Type.Optional(Type.String({ description: "Concise actionable task title for add/edit." })),
+  details: Type.Optional(Type.String({ description: "Optional short task context for a new task." }))
+});
+
+interface TaskToolDetails {
+  action: string;
+  items: Todo[];
+  changed?: string;
+}
+
+const summary = (items: readonly Todo[]) => {
+  const done = items.filter((item) => item.done).length;
+  const current = items.find((item) => item.status === "in_progress");
+  return `${done}/${items.length} done` + (current ? ` · now: ${current.title}` : "");
+};
+
+const lines = (items: readonly Todo[]) => items.length
+  ? items.map((item) => `${todoMark(item)} [${item.status}] ${item.title} (${item.id})`).join("\n")
+  : "No tracked tasks.";
+
+const REMINDER = "Keep using jar_todo to track progress: mark the next task in_progress before starting it and completed as soon as it is verified.";
+
+export function registerTaskTool(
+  pi: ExtensionAPI,
+  store: () => TodoStore | undefined,
+  changed: (ctx: ExtensionContext) => void
+): void {
+  if (typeof (pi as ExtensionAPI & { registerTool?: unknown }).registerTool !== "function") return;
+  pi.registerTool({
+    name: "jar_todo",
+    label: "tasks",
+    description: "Maintain pi-jar's session task list, shown live to the user. Send `todos` with the complete updated list (each with content, status pending|in_progress|completed, and activeForm). Single-task actions (start, done, open, add, edit, delete, list) are also available.",
+    promptSnippet: "Track multi-step work with jar_todo: write the full list, keep exactly one task in_progress, complete tasks as they finish.",
+    promptGuidelines: [
+      "Use jar_todo proactively, without waiting for the user, for any task with three or more distinct steps, when the user gives several tasks, or right after receiving new instructions. Skip it for single trivial requests and pure questions.",
+      "Prefer jar_todo with `todos` (the full updated list). Each item has `content` (imperative, e.g. \"Run tests\"), `status`, and `activeForm` (present continuous, e.g. \"Running tests\"), which the user sees while it runs.",
+      "Keep exactly one task in_progress at a time. Mark a task in_progress before you start it and completed immediately after it is verified; do not batch completions.",
+      "Only mark a task completed when it is fully done. If tests fail, work is partial or you are blocked, keep it in_progress and add a task for what must be resolved. Remove tasks that are no longer relevant."
+    ],
+    parameters: Parameters,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const current = store();
+      const action = params.todos ? "write" : params.action ?? "list";
+      if (!current) {
+        return { content: [{ type: "text", text: "Task tracking is unavailable before a Pi session starts." }], details: { action, items: [] } satisfies TaskToolDetails };
+      }
+      let changedId: string | undefined;
+      let error: string | undefined;
+      switch (action) {
+        case "list":
+          break;
+        case "write":
+          if (!params.todos) { error = "write needs `todos`: the complete updated list."; break; }
+          error = current.write(params.todos.map((item) => ({ title: item.content, status: item.status, ...(item.activeForm ? { activeForm: item.activeForm } : {}) })));
+          break;
+        case "add": {
+          const item = params.title?.trim() ? current.add(params.title, params.details) : undefined;
+          if (!item) error = "add needs a short title.";
+          changedId = item?.id;
+          break;
+        }
+        case "start":
+        case "done":
+        case "open":
+          if (!params.id || !current.setStatus(params.id, action === "start" ? "in_progress" : action === "done" ? "completed" : "pending")) error = `${action} needs a valid id from jar_todo list.`;
+          else changedId = params.id;
+          break;
+        case "edit":
+          if (!params.id || !params.title?.trim() || !current.edit(params.id, params.title)) error = "edit needs a valid id and a title.";
+          else changedId = params.id;
+          break;
+        case "delete":
+          if (!params.id || !current.delete(params.id)) error = "delete needs a valid id from jar_todo list.";
+          else changedId = params.id;
+          break;
+      }
+      if (action !== "list" && !error) changed(ctx);
+      const items = current.all();
+      const message = error
+        ? `Could not ${action} tasks: ${error}\n${lines(items)}`
+        : `${action === "list" ? "Tasks" : "Task list updated"} (${summary(items)}):\n${lines(items)}${action === "list" ? "" : "\n" + REMINDER}`;
+      return {
+        content: [{ type: "text", text: message }],
+        details: { action, items, ...(changedId ? { changed: changedId } : {}) } satisfies TaskToolDetails
+      };
+    },
+    renderCall(args, theme) {
+      let text = theme.fg("toolTitle", theme.bold("tasks"));
+      if (args.todos) text += " " + theme.fg("accent", `update · ${args.todos.length} item${args.todos.length === 1 ? "" : "s"}`);
+      else {
+        text += " " + theme.fg("accent", args.action ?? "list");
+        if (args.title) text += " " + theme.fg("muted", args.title);
+      }
+      return new Text(text, 0, 0);
+    },
+    renderResult(result, { expanded, isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("warning", "Updating tasks…"), 0, 0);
+      const details = result.details as TaskToolDetails | undefined;
+      const items = details?.items ?? [];
+      if (!items.length) return new Text(theme.fg("dim", "No tracked tasks."), 0, 0);
+      // Like Claude: the checklist itself is the result. Collapsed shows up to 8 rows.
+      const shown = expanded ? items : items.slice(0, 8);
+      let text = theme.fg("dim", summary(items));
+      for (const item of shown) text += "\n" + todoRow(item, (color, value) => theme.fg(color, value), (value) => theme.bold(value));
+      if (shown.length < items.length) text += "\n" + theme.fg("dim", `  … +${items.length - shown.length} more (expand)`);
+      return new Text(text, 0, 0);
+    }
+  });
+}
+
+type TodoColor = "accent" | "muted" | "dim" | "success";
+/** One checklist row: completed rows are struck through, the running one is bold. */
+export function todoRow(item: Todo, fg: (color: TodoColor, text: string) => string, bold: (text: string) => string = (text) => text): string {
+  if (item.status === "completed") return fg("success", "  ✔ ") + fg("dim", "\x1b[9m" + item.title + "\x1b[29m");
+  if (item.status === "in_progress") return fg("accent", "  ◼ ") + fg("accent", bold(item.title));
+  return fg("muted", "  ☐ " + item.title);
+}

package/src/tasks-ui.ts

@@ -0,0 +1,73 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { promptChoice, promptText, todoView, type TodoFilter } from "./dialogs.ts";
+import { TodoStore } from "./tasks.ts";
+
+const help = "Usage: /jar tasks [list|add TITLE|done ID|open ID|edit ID TITLE|delete ID]";
+
+export async function manageTasks(args: string, ctx: ExtensionContext, store: TodoStore, changed: () => void): Promise<void> {
+  const notify = (text: string, severity: "info" | "error" = "info") => {
+    if (ctx.hasUI) ctx.ui.notify(text, severity);
+    else console.log(text);
+  };
+  const list = () => {
+    const items = store.all();
+    notify(items.length ? items.map((item) => `${item.done ? "[x]" : "[ ]"} ${item.title} (${item.id})`).join("\n") : "pi-jar to-do: empty (separate from other task managers)");
+  };
+  if (!args && ctx.hasUI && ctx.mode === "tui") {
+    const filter: { value: TodoFilter } = { value: "all" };
+    while (true) {
+      const action = await todoView(ctx, () => store.all(), filter);
+      if (!action) break;
+      let success = false;
+      if (action.kind === "add") {
+        const title = await promptText(ctx, "Add pi-jar to-do", "What needs doing?");
+        if (title) success = !!store.add(title);
+      } else if (action.id && action.kind === "toggle") success = store.toggle(action.id);
+      else if (action.id && action.kind === "edit") {
+        const previous = store.get(action.id);
+        const title = previous && await promptText(ctx, "Edit pi-jar to-do", "Update the title", previous.title);
+        if (title) success = store.edit(action.id, title);
+      } else if (action.id && action.kind === "delete") {
+        const item = store.get(action.id);
+        const choice = item && await promptChoice(ctx, "Delete to-do?", item.title, ["Delete item", "Keep item"], 1);
+        if (choice === 0) success = store.delete(action.id);
+      }
+      if (success) changed();
+    }
+    return;
+  }
+  const [verb = "list", id, ...titleParts] = args.split(/\s+/);
+  switch (verb.toLowerCase()) {
+    case "list": list(); return;
+    case "add": {
+      const title = args.slice(4).trim();
+      if (store.add(title)) { changed(); notify("Added pi-jar to-do"); }
+      else notify(help, "error");
+      return;
+    }
+    case "done":
+    case "open": {
+      const item = id && store.get(id);
+      if (item && item.done !== (verb === "done") && store.toggle(id)) { changed(); notify("Updated pi-jar to-do"); }
+      else notify("To-do not found or already in that state", "error");
+      return;
+    }
+    case "edit": {
+      const title = titleParts.join(" ");
+      if (id && store.edit(id, title)) { changed(); notify("Edited pi-jar to-do"); }
+      else notify(help, "error");
+      return;
+    }
+    case "delete": {
+      if (!id || !store.get(id)) { notify("To-do not found", "error"); return; }
+      if (ctx.hasUI && ctx.mode === "tui") {
+        const choice = await promptChoice(ctx, "Delete pi-jar to-do?", store.get(id)!.title, ["Delete item", "Keep item"], 1);
+        if (choice !== 0) return;
+      }
+      // Headless deletion is explicit and requires the full ID; TUI deletion asks for confirmation.
+      if (store.delete(id)) { changed(); notify("Deleted pi-jar to-do"); }
+      return;
+    }
+    default: notify(help, "error");
+  }
+}

package/src/tasks.ts

@@ -0,0 +1,147 @@
+import { randomUUID } from "node:crypto";
+import { cleanText } from "./status.ts";
+
+export const TASK_ENTRY = "pi-jar.task";
+export const TODO_STATUSES = ["pending", "in_progress", "completed"] as const;
+export type TodoStatus = (typeof TODO_STATUSES)[number];
+/** `done` mirrors `status === "completed"` for callers that only need open/closed. */
+export interface Todo { id: string; title: string; done: boolean; status: TodoStatus; activeForm?: string; details?: string }
+export interface TodoInput { title: string; status: TodoStatus; activeForm?: string }
+export const MAX_TODOS = 50;
+
+interface WrittenTodo { id: string; title: string; status: TodoStatus; activeForm?: string }
+export type TodoEvent =
+  | { v: 1; op: "add"; id: string; title: string; details?: string }
+  | { v: 1; op: "edit"; id: string; title: string }
+  | { v: 1; op: "toggle"; id: string; done: boolean }
+  | { v: 1; op: "status"; id: string; status: TodoStatus }
+  | { v: 1; op: "delete"; id: string }
+  /** Full-list replacement, like a Claude todo write. */
+  | { v: 1; op: "write"; items: WrittenTodo[] };
+
+const validId = (id: unknown): id is string => typeof id === "string" && /^[a-zA-Z0-9-]{1,64}$/.test(id);
+const validTitle = (title: unknown): title is string => typeof title === "string" && title.length <= 256 && !!cleanText(title, 120);
+const validStatus = (status: unknown): status is TodoStatus => TODO_STATUSES.includes(status as TodoStatus);
+const make = (id: string, title: string, status: TodoStatus, activeForm?: unknown, details?: unknown): Todo => ({
+  id, title: cleanText(title, 120), status, done: status === "completed",
+  ...(typeof activeForm === "string" && cleanText(activeForm, 80) ? { activeForm: cleanText(activeForm, 80) } : {}),
+  ...(typeof details === "string" && cleanText(details, 240) ? { details: cleanText(details, 240) } : {})
+});
+
+/** Session-local, append-only changes: only the current Pi branch is replayed. */
+export class TodoStore {
+  private items = new Map<string, Todo>();
+  private readonly append: (event: TodoEvent) => void;
+  constructor(append: (event: TodoEvent) => void) { this.append = append; }
+  all(): Todo[] { return [...this.items.values()].map((item) => ({ ...item })); }
+  get(id: string): Todo | undefined { const item = this.items.get(id); return item && { ...item }; }
+  /** The task being worked on right now, if any. */
+  current(): Todo | undefined { const item = [...this.items.values()].find((todo) => todo.status === "in_progress"); return item && { ...item }; }
+
+  private setItemStatus(item: Todo, status: TodoStatus): void {
+    // Exactly one task is in progress: starting one parks the previous one.
+    if (status === "in_progress") for (const other of this.items.values()) if (other !== item && other.status === "in_progress") { other.status = "pending"; other.done = false; }
+    item.status = status;
+    item.done = status === "completed";
+  }
+
+  apply(raw: unknown): boolean {
+    if (!raw || typeof raw !== "object") return false;
+    const event = raw as Record<string, unknown>;
+    if (event.v !== 1) return false;
+    if (event.op === "write") {
+      if (!Array.isArray(event.items) || event.items.length > MAX_TODOS) return false;
+      const next = new Map<string, Todo>();
+      for (const raw of event.items as unknown[]) {
+        const item = raw as Record<string, unknown> | null;
+        if (!item || !validId(item.id) || !validTitle(item.title) || !validStatus(item.status) || next.has(item.id)) return false;
+        next.set(item.id, make(item.id, item.title, item.status, item.activeForm, this.items.get(item.id)?.details));
+      }
+      if ([...next.values()].filter((item) => item.status === "in_progress").length > 1) return false;
+      this.items = next;
+      return true;
+    }
+    if (!validId(event.id)) return false;
+    const item = this.items.get(event.id);
+    switch (event.op) {
+      case "add":
+        if (!validTitle(event.title) || item) return false;
+        this.items.set(event.id, make(event.id, event.title, "pending", undefined, event.details));
+        return true;
+      case "edit":
+        if (!validTitle(event.title) || !item) return false;
+        item.title = cleanText(event.title, 120);
+        return true;
+      case "toggle":
+        if (typeof event.done !== "boolean" || !item) return false;
+        this.setItemStatus(item, event.done ? "completed" : "pending");
+        return true;
+      case "status":
+        if (!validStatus(event.status) || !item) return false;
+        this.setItemStatus(item, event.status);
+        return true;
+      case "delete": return this.items.delete(event.id);
+      default: return false;
+    }
+  }
+  restore(branch: readonly unknown[]): void {
+    this.items.clear();
+    for (const raw of branch) {
+      if (!raw || typeof raw !== "object") continue;
+      const entry = raw as Record<string, unknown>;
+      if (entry.type === "custom" && entry.customType === TASK_ENTRY) this.apply(entry.data);
+    }
+  }
+  private commit(event: TodoEvent): boolean {
+    const before = new Map([...this.items].map(([id, item]) => [id, { ...item }]));
+    if (!this.apply(event)) return false;
+    try { this.append(event); return true; }
+    catch { this.items = before; return false; }
+  }
+  add(title: string, details?: string): Todo | undefined {
+    if (!validTitle(title)) return undefined;
+    const id = randomUUID();
+    const cleanDetails = typeof details === "string" && details.trim() ? cleanText(details, 240) : undefined;
+    return this.commit({ v: 1, op: "add", id, title, ...(cleanDetails ? { details: cleanDetails } : {}) }) ? this.get(id) : undefined;
+  }
+  /**
+   * Replace the whole list. Items keep their id when an existing task has the same title,
+   * so history and the goal loop see continuity. Returns an error message on invalid input.
+   */
+  write(inputs: readonly TodoInput[]): string | undefined {
+    if (inputs.length > MAX_TODOS) return `At most ${MAX_TODOS} tasks.`;
+    if (inputs.some((item) => !validTitle(item.title))) return "Every task needs a short, non-empty title.";
+    if (inputs.some((item) => !validStatus(item.status))) return `status must be one of ${TODO_STATUSES.join(", ")}.`;
+    if (inputs.filter((item) => item.status === "in_progress").length > 1) return "Only one task may be in_progress at a time.";
+    const free = new Map<string, string[]>();
+    for (const item of this.items.values()) {
+      const key = cleanText(item.title, 120).toLowerCase();
+      free.set(key, [...(free.get(key) ?? []), item.id]);
+    }
+    const items = inputs.map((item): WrittenTodo => {
+      const id = free.get(cleanText(item.title, 120).toLowerCase())?.shift() ?? randomUUID();
+      const activeForm = typeof item.activeForm === "string" && item.activeForm.trim() ? item.activeForm : undefined;
+      return { id, title: item.title, status: item.status, ...(activeForm ? { activeForm } : {}) };
+    });
+    return this.commit({ v: 1, op: "write", items }) ? undefined : "Could not save the task list.";
+  }
+  edit(id: string, title: string): boolean { return this.commit({ v: 1, op: "edit", id, title }); }
+  setStatus(id: string, status: TodoStatus): boolean {
+    const item = this.items.get(id);
+    if (!item) return false;
+    return item.status === status || this.commit({ v: 1, op: "status", id, status });
+  }
+  setDone(id: string, done: boolean): boolean {
+    const item = this.items.get(id);
+    if (!item) return false;
+    return item.done === done || this.setStatus(id, done ? "completed" : "pending");
+  }
+  toggle(id: string): boolean {
+    const item = this.items.get(id);
+    return !!item && this.setDone(id, !item.done);
+  }
+  delete(id: string): boolean { return this.commit({ v: 1, op: "delete", id }); }
+}
+
+/** Claude-style checkbox glyph for a task. */
+export const todoMark = (item: Pick<Todo, "status">) => item.status === "completed" ? "✔" : item.status === "in_progress" ? "◼" : "☐";