@getpipher/armory-todo 0.2.0 → 0.3.1

package/extensions/todo.ts

@@ -27,38 +27,77 @@ import {
   completeTodo,
   deleteTodo,
   clearTodos,
+  getTodo,
   listTodos,
   renderOpenBlock,
   updateTodo,
   parkTodo,
   getStorePath,
 } from "../src/todo-store";
-import { pruneTodos, restoreTodo, listArchived, archiveSummary } from "../src/archive";
+import { pruneTodos, restoreTodo, listArchived, archiveSummary, listDoneUnified } from "../src/archive";
 import { healthReport } from "../src/health";
 import { hardPrune } from "../src/hard-prune";
 import { TodoPanel } from "../src/panel";
+import { autoPruneOnSessionStart } from "../src/auto-prune";
+import { loadConfig } from "../src/config";
 
-const ACTIONS = ["list", "add", "update", "complete", "delete", "clear", "park", "prune", "restore", "health"] as const;
+const ACTIONS = ["list", "add", "update", "get", "complete", "delete", "clear", "park", "prune", "restore", "health"] as const;
 
 function fmt(t: ReturnType<typeof listTodos>[number]): string {
   const tag = t.project ? ` (${t.project})` : "";
   const pins = t.tags.length ? ` #${t.tags.join(" #")}` : "";
-  return `- [${t.id}] (${t.priority}/${t.status}) ${t.text}${tag}${pins}`;
+  const dot = t.notes.trim() ? " •" : "";
+  return `- [${t.id}] (${t.priority}/${t.status})${dot} ${t.title}${tag}${pins}`;
+}
+
+function fmtFull(t: ReturnType<typeof getTodo>): string {
+  const tag = t.project ? ` (${t.project})` : "";
+  const tags = t.tags.length ? ` #${t.tags.join(" #")}` : "";
+  return [
+    `${t.id} [${t.priority}/${t.status}] ${t.title}${tag}${tags}`,
+    `created: ${t.createdAt}`,
+    `updated: ${t.updatedAt}`,
+    `closed: ${t.closedAt ?? "(open)"}`,
+    `source: ${t.source || "(none)"}`,
+    "",
+    "notes:",
+    t.notes || "(empty)",
+  ].join("\n");
+}
+
+function fmtDone(d: ReturnType<typeof listDoneUnified>[number]): string {
+  const tag = d.project ? ` (${d.project})` : "";
+  const loc = d.location === "archive" && d.archivedAt
+    ? ` [archived ${d.archivedAt.slice(0, 10)}]`
+    : ` [live ${d.closedAt ? Math.floor((Date.now() - Date.parse(d.closedAt)) / 86400_000) : 0}d]`;
+  return `- [${d.id}] (done)${tag} ${d.title}${loc}`;
 }
 
 export default function (pi: ExtensionAPI) {
   // Warm + report on session start (every new/resume/fork/reload).
   pi.on("session_start", async (_event, ctx) => {
     try {
+      let autoMsg = "";
+      let ageDays = 7;
+      try {
+        ageDays = loadConfig().prune.defaultAgeDays;
+        const ap = autoPruneOnSessionStart();
+        if (ap) {
+          const lines = ap.items.map((i) => `  [${i.id}] ${i.status}  ${i.title}`);
+          autoMsg = ` · auto-pruned ${ap.moved} stale done (>${ageDays}d):\n${lines.join("\n")}\nUndo any with: todo restore <id>`;
+        }
+      } catch {
+        // auto-prune optional — don't crash the session notify
+      }
       const open = listTodos();
-      let msg = `armory-todo: ${open.length} open TODO${open.length === 1 ? "" : "s"}`;
+      let msg = `armory-todo: ${open.length} open TODO${open.length === 1 ? "" : "s"}${autoMsg}`;
       try {
         const report = healthReport();
         if (report.flags.length > 0) {
-          msg += ` — ⚠ ${report.flags.length} bloat signal${report.flags.length === 1 ? "" : "s"} (run /todo health)`;
+          msg += `${autoMsg ? "\n" : " — "}` + `⚠ ${report.flags.length} bloat signal${report.flags.length === 1 ? "" : "s"} (run /todo health)`;
         }
       } catch {
-        // health check optional — don't crash the session notify
+        // health check optional
       }
       if (ctx.hasUI) ctx.ui.notify(msg, "info");
     } catch {
@@ -92,20 +131,25 @@ export default function (pi: ExtensionAPI) {
       "Never put secrets in a TODO — the text reaches the model provider.",
     promptSnippet: "Read/update the global cross-session TODO list (active / parked / archive) + bloat health",
     promptGuidelines: [
-      "Use todo (action:'list') when the user asks 'show me the TODO' / 'what's pending'.",
-      "Use todo (action:'add', text, project?, tags?, priority?, source?) when the user says 'put this in our TODO'.",
+      "Use todo (action:'add', title, notes?, project?, tags?, priority?, source?) when the user says 'put this in our TODO'. title max 120 chars (one-line summary); put long detail in notes.",
+      "Use todo (action:'get', id) to read a todo's full notes before acting on it (the bullet marker in lists means notes exist).",
+      "Use todo (action:'update', id, title?, notes?, project?, tags?, priority?, status?) to edit; notes empty string clears.",
+      "Use todo (action:'list') when the user asks 'show me the TODO' / 'what's pending' (text filter searches title+notes).",
       "Use todo (action:'complete', id) to mark a TODO done; (action:'delete', id) to cancel it.",
       "Use todo (action:'park', id) to defer a TODO (not injected, recoverable); (action:'update', id, status:'open') to un-park.",
       "Use todo (action:'prune') to move done/cancelled todos to the archive (reversible); (action:'prune', all:true) to prune all regardless of age.",
+      "Done/cancelled todos older than the prune age (default 7d) auto-archive on session start — you'll see a notify; reversible via todo restore <id>. Use /todo finished or todo list status:'done' to see all finished work (live + archived).",
       "Use todo (action:'restore', id) to bring an archived TODO back as open.",
-      "Use todo (action:'list', archived:true) to query the archive — bare call returns a summary; add a filter (project/text/since) for specific items.",
-      "Use todo (action:'health') to check bloat across all boxes — returns counts + flags + suggestions. Run this when the user asks about hygiene/bloat or before any hard-prune.",
-      "Use todo (action:'prune', hard:true, confirm:true, box?, olderThan?) for PERMANENT deletion — the only irreversible action. ALWAYS: run `health` first, show the user the report + the exact proposed command, and wait for an explicit 'yes' before passing confirm:true. Never hard-prune without explicit user confirmation.",
+      "Use todo (action:'list', archived:true) to query the archive; bare call returns a summary, add a filter (project/text/since) for specific items.",
+      "Use todo (action:'health') to check bloat across all boxes (counts + flags + suggestions). Run when the user asks about hygiene/bloat or before any hard-prune.",
+      "Use todo (action:'prune', hard:true, confirm:true, box?, olderThan?) for PERMANENT deletion (the only irreversible action). ALWAYS run health first, show the user the report + the exact proposed command, and wait for an explicit yes before passing confirm:true. Never hard-prune without explicit user confirmation.",
     ],
     parameters: Type.Object({
       action: StringEnum(ACTIONS),
-      id: Type.Optional(Type.String({ description: "Todo id (for update/complete/delete/park/restore)" })),
-      text: Type.Optional(Type.String({ description: "Todo text (add) or new text (update); or substring search (list)" })),
+      id: Type.Optional(Type.String({ description: "Todo id (for update/complete/delete/park/restore/get)" })),
+      title: Type.Optional(Type.String({ description: "Todo title (add required; update optional). Max 120 chars; put detail in notes." })),
+      notes: Type.Optional(Type.String({ description: "Todo notes/body (add/update optional; long-form, not injected). Pass empty string on update to clear." })),
+      text: Type.Optional(Type.String({ description: "Search query (list only). Substring match on title OR notes. Not used by add/update." })),
       project: Type.Optional(Type.String({ description: "Project tag, e.g. 'pi', 'sip', or '' for global" })),
       tags: Type.Optional(Type.Array(Type.String())),
       priority: Type.Optional(StringEnum(["low", "med", "high", "critical"] as const)),
@@ -132,6 +176,20 @@ export default function (pi: ExtensionAPI) {
       try {
         switch (params.action) {
           case "list": {
+            if (params.status === "done" && !params.archived) {
+              const items = listDoneUnified({
+                text: params.text,
+                project: params.projectFilter,
+                since: params.since,
+                before: params.before,
+                limit: params.limit,
+                page: params.page,
+              });
+              if (items.length === 0) {
+                return { content: [{ type: "text" as const, text: "No done TODOs (live or archive)." }] };
+              }
+              return { content: [{ type: "text" as const, text: `Done (${items.length}):\n${items.map(fmtDone).join("\n")}` }] };
+            }
             if (params.archived) {
               const res = listArchived({
                 project: params.projectFilter,
@@ -173,43 +231,50 @@ export default function (pi: ExtensionAPI) {
             return { content: [{ type: "text" as const, text: todos.map(fmt).join("\n") }] };
           }
           case "add": {
-            if (!params.text) {
-              return { content: [{ type: "text" as const, text: "Error: `text` is required for add." }] };
+            if (!params.title) {
+              return { content: [{ type: "text" as const, text: "Error: `title` is required for add." }] };
             }
             const t = addTodo({
-              text: params.text,
+              title: params.title,
+              notes: params.notes,
               project: params.project,
               tags: params.tags,
               priority: params.priority as any,
               source: params.source as any,
             });
-            return { content: [{ type: "text" as const, text: `Added ${t.id}: ${t.text}` }] };
+            return { content: [{ type: "text" as const, text: `Added ${t.id}: ${t.title}` }] };
           }
           case "update": {
             if (!params.id) return { content: [{ type: "text" as const, text: "Error: `id` is required for update." }] };
             const t = updateTodo(params.id, {
-              text: params.text,
+              title: params.title,
+              notes: params.notes,
               project: params.project,
               tags: params.tags,
               priority: params.priority as any,
               status: params.status as any,
             });
-            return { content: [{ type: "text" as const, text: `Updated ${t.id}: ${t.text} [${t.status}]` }] };
+            return { content: [{ type: "text" as const, text: `Updated ${t.id}: ${t.title} [${t.status}]` }] };
+          }
+          case "get": {
+            if (!params.id) return { content: [{ type: "text" as const, text: "Error: `id` is required for get." }] };
+            const t = getTodo(params.id);
+            return { content: [{ type: "text" as const, text: fmtFull(t) }] };
           }
           case "complete": {
             if (!params.id) return { content: [{ type: "text" as const, text: "Error: `id` is required for complete." }] };
             const t = completeTodo(params.id);
-            return { content: [{ type: "text" as const, text: `Completed ${t.id}: ${t.text}` }] };
+            return { content: [{ type: "text" as const, text: `Completed ${t.id}: ${t.title}` }] };
           }
           case "delete": {
             if (!params.id) return { content: [{ type: "text" as const, text: "Error: `id` is required for delete." }] };
             const t = deleteTodo(params.id);
-            return { content: [{ type: "text" as const, text: `Cancelled ${t.id}: ${t.text}` }] };
+            return { content: [{ type: "text" as const, text: `Cancelled ${t.id}: ${t.title}` }] };
           }
           case "park": {
             if (!params.id) return { content: [{ type: "text" as const, text: "Error: `id` is required for park." }] };
             const t = parkTodo(params.id);
-            return { content: [{ type: "text" as const, text: `Parked ${t.id}: ${t.text}` }] };
+            return { content: [{ type: "text" as const, text: `Parked ${t.id}: ${t.title}` }] };
           }
           case "prune": {
             if (params.hard) {
@@ -223,7 +288,11 @@ export default function (pi: ExtensionAPI) {
               return { content: [{ type: "text" as const, text: res.message + (res.refused ? "" : ` Deleted: ${res.ids.join(", ") || "(none)"}`) }] };
             }
             const res = pruneTodos({ ageDays: params.ageDays, all: params.all });
-            return { content: [{ type: "text" as const, text: `Pruned ${res.moved} todo${res.moved === 1 ? "" : "s"} to archive: ${res.ids.join(", ") || "(none)"}` }] };
+            if (res.moved === 0) {
+              return { content: [{ type: "text" as const, text: "Nothing to prune (no stale done/cancelled)." }] };
+            }
+            const prunedLines = res.items.map((i) => `  [${i.id}] ${i.status}  ${i.title}  (was ${i.ageDays}d old)`);
+            return { content: [{ type: "text" as const, text: `Pruned ${res.moved} todo${res.moved === 1 ? "" : "s"} to archive:\n${prunedLines.join("\n")}\nUndo any with: todo restore <id>` }] };
           }
           case "health": {
             const report = healthReport();
@@ -232,6 +301,7 @@ export default function (pi: ExtensionAPI) {
               `active:  ${report.active.open} open + ${report.active.in_progress} in_progress (${report.active.stale_30d} stale)`,
               `parked:  ${report.parked.count} (${report.parked.stale_60d} stale)`,
               `archive: ${report.archive.count} (${report.archive.older_180d} old)`,
+              `notes:   ${report.notesBytes.total}B total · max ${report.notesBytes.max}B · avg ${report.notesBytes.avg}B`,
               report.flags.length ? `flags: ${report.flags.join(", ")}` : "flags: (none — healthy)",
               ...report.suggestions.map((s) => `  → ${s}`),
             ];
@@ -240,7 +310,7 @@ export default function (pi: ExtensionAPI) {
           case "restore": {
             if (!params.id) return { content: [{ type: "text" as const, text: "Error: `id` is required for restore." }] };
             const t = restoreTodo(params.id);
-            return { content: [{ type: "text" as const, text: `Restored ${t.id}: ${t.text} [open]` }] };
+            return { content: [{ type: "text" as const, text: `Restored ${t.id}: ${t.title} [open]` }] };
           }
           case "clear": {
             const n = clearTodos((params.status as any) ?? "done");
@@ -259,9 +329,9 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("todo", {
     description:
       "Global cross-session TODO list. " +
-      "/todo · /todo all · /todo add <text> · /todo done <id> · /todo rm <id> · " +
-      "/todo park <id> · /todo restore <id> · /todo prune [--all|--hard --box <b> --older-than <d>] · " +
-      "/todo archive [project:X|text:Y] · /todo health · /todo clean · /todo path",
+      "/todo / /todo all / /todo add <title> / /todo done <id> / /todo rm <id> / " +
+      "/todo park <id> / /todo restore <id> / /todo prune [--all|--hard --box <b> --older-than <d>] / " +
+      "/todo archive [project:X|text:Y] / /todo finished / /todo health / /todo clean / /todo path",
     handler: async (args, ctx) => {
       const a = (args ?? "").trim();
       const [sub, ...rest] = a.split(/\s+/);
@@ -273,10 +343,10 @@ export default function (pi: ExtensionAPI) {
           return;
         }
         if (sub === "add") {
-          const text = rest.join(" ").trim();
-          if (!text) { if (ctx.hasUI) ctx.ui.notify("usage: /todo add <text>", "warning"); return; }
-          const t = addTodo({ text, source: "slash" });
-          if (ctx.hasUI) ctx.ui.notify(`Added ${t.id}: ${t.text}`, "info");
+          const title = rest.join(" ").trim();
+          if (!title) { if (ctx.hasUI) ctx.ui.notify("usage: /todo add <title>  (notes via the todo tool)", "warning"); return; }
+          const t = addTodo({ title, source: "slash" });
+          if (ctx.hasUI) ctx.ui.notify(`Added ${t.id}: ${t.title}`, "info");
           return;
         }
         if (sub === "done") {
@@ -297,14 +367,14 @@ export default function (pi: ExtensionAPI) {
           const id = rest[0];
           if (!id) { if (ctx.hasUI) ctx.ui.notify("usage: /todo park <id>", "warning"); return; }
           const t = parkTodo(id);
-          if (ctx.hasUI) ctx.ui.notify(`Parked ${t.id}: ${t.text}`, "info");
+          if (ctx.hasUI) ctx.ui.notify(`Parked ${t.id}: ${t.title}`, "info");
           return;
         }
         if (sub === "restore") {
           const id = rest[0];
           if (!id) { if (ctx.hasUI) ctx.ui.notify("usage: /todo restore <id>", "warning"); return; }
           const t = restoreTodo(id);
-          if (ctx.hasUI) ctx.ui.notify(`Restored ${t.id}: ${t.text}`, "info");
+          if (ctx.hasUI) ctx.ui.notify(`Restored ${t.id}: ${t.title}`, "info");
           return;
         }
         if (sub === "prune") {
@@ -330,7 +400,12 @@ export default function (pi: ExtensionAPI) {
           }
           const all = rest.includes("--all");
           const res = pruneTodos({ all });
-          if (ctx.hasUI) ctx.ui.notify(`Pruned ${res.moved} todo${res.moved === 1 ? "" : "s"} to archive: ${res.ids.join(", ") || "(none)"}`, "info");
+          if (ctx.hasUI) {
+            const msg = res.moved === 0
+              ? "Nothing to prune."
+              : `Pruned ${res.moved} to archive:\n${res.items.map((i) => `  [${i.id}] ${i.title} (${i.ageDays}d)`).join("\n")}\nUndo: todo restore <id>`;
+            ctx.ui.notify(msg, "info");
+          }
           return;
         }
         if (sub === "health") {
@@ -340,6 +415,7 @@ export default function (pi: ExtensionAPI) {
             `  active:  ${report.active.open} open + ${report.active.in_progress} in_progress (${report.active.stale_30d} stale)`,
             `  parked:  ${report.parked.count} (${report.parked.stale_60d} stale)`,
             `  archive: ${report.archive.count} (${report.archive.older_180d} old)`,
+            `  notes:   ${report.notesBytes.total}B total · max ${report.notesBytes.max}B · avg ${report.notesBytes.avg}B`,
             report.flags.length ? `  ⚠ ${report.flags.join(", ")}` : "  ✅ healthy",
             ...report.suggestions.map((s) => `  → ${s}`),
           ];
@@ -372,6 +448,12 @@ export default function (pi: ExtensionAPI) {
           if (ctx.hasUI) ctx.ui.notify(`Archived (${res.total} total):\n${msg}`, "info");
           return;
         }
+        if (sub === "finished") {
+          const items = listDoneUnified({ text: rest.join(" ").trim() || undefined, limit: 100 });
+          const msg = items.length ? `Done (${items.length}):\n${items.map(fmtDone).join("\n")}` : "(no done TODOs)";
+          if (ctx.hasUI) ctx.ui.notify(msg, "info");
+          return;
+        }
         if (sub === "clean") {
           const n = clearTodos("done");
           if (ctx.hasUI) ctx.ui.notify(`Cleared ${n} done TODOs.`, "info");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-todo",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Global, cross-session TODO for pi — persists across all sessions and is auto-injected into every prompt. The disk-backed counterpart to branch-scoped pi todo extensions.",
   "keywords": [
     "pi-package",
@@ -35,7 +35,7 @@
     ]
   },
   "scripts": {
-    "test": "for t in todo-store todo-archive todo-config todo-migrate todo-health todo-hard-prune panel-data; do node test/$t.test.mts || exit 1; done"
+    "test": "for t in todo-store todo-title-notes todo-archive todo-config todo-migrate todo-health todo-hard-prune todo-auto-prune panel-data; do node test/$t.test.mts || exit 1; done"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/archive.ts

@@ -8,12 +8,13 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { getArchivePath } from "./paths.ts";
+import { migrateV2ToV3 } from "./migrate.ts";
 import type { Todo } from "./todo-store.ts";
 import { loadConfig } from "./config.ts";
 import { loadStore, saveStore, TodoError } from "./todo-store.ts";
 
 export interface ArchiveStore {
-  version: 2;
+  version: 3;
   updatedAt: string;
   todos: Todo[];
 }
@@ -23,7 +24,7 @@ function now(): string {
 }
 
 function emptyArchive(): ArchiveStore {
-  return { version: 2, updatedAt: now(), todos: [] };
+  return { version: 3, updatedAt: now(), todos: [] };
 }
 
 /** Load the archive. Missing file → empty store (no file created). */
@@ -36,6 +37,15 @@ export function loadArchive(): ArchiveStore {
     if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.todos)) {
       throw new Error("invalid archive shape");
     }
+    if (parsed.version === 2) {
+      // v2 → v3: curated + fallback, persist once (symmetric with the live store).
+      const migrated = migrateV2ToV3(parsed as any) as unknown as ArchiveStore;
+      saveArchive(migrated);
+      return migrated;
+    }
+    if (parsed.version !== 3) {
+      throw new Error("invalid archive shape");
+    }
     return parsed;
   } catch {
     try {
@@ -69,9 +79,17 @@ export interface PruneInput {
   statuses?: ("done" | "cancelled")[];
 }
 
+export interface PruneItem {
+  id: string;
+  status: "done" | "cancelled";
+  title: string;
+  ageDays: number;
+}
+
 export interface PruneResult {
   moved: number;
   ids: string[];
+  items: PruneItem[];
 }
 
 /**
@@ -108,14 +126,20 @@ export function pruneTodos(opts: PruneInput = {}): PruneResult {
     moved.push(todo);
   }
 
-  if (moved.length === 0) return { moved: 0, ids: [] };
+  if (moved.length === 0) return { moved: 0, ids: [], items: [] };
 
   live.todos = kept;
   archive.todos.push(...moved);
   saveStore(live);
   saveArchive(archive);
 
-  return { moved: moved.length, ids: moved.map((t) => t.id) };
+  const items: PruneItem[] = moved.map((t) => ({
+    id: t.id,
+    status: t.status as "done" | "cancelled",
+    title: t.title,
+    ageDays: t.closedAt ? Math.floor((Date.now() - Date.parse(t.closedAt)) / 86400_000) : 0,
+  }));
+  return { moved: moved.length, ids: moved.map((t) => t.id), items };
 }
 
 /**
@@ -190,7 +214,7 @@ export function listArchived(filter: ArchiveListFilter = {}): ArchiveListResult
   if (filter.status) out = out.filter((t) => t.status === filter.status);
   if (filter.text) {
     const q = filter.text.toLowerCase();
-    out = out.filter((t) => t.text.toLowerCase().includes(q));
+    out = out.filter((t) => t.title.toLowerCase().includes(q) || t.notes.toLowerCase().includes(q));
   }
   if (filter.since) out = out.filter((t) => (t.closedAt ?? t.updatedAt) >= (filter.since as string));
   if (filter.before) out = out.filter((t) => (t.closedAt ?? t.updatedAt) < (filter.before as string));
@@ -201,4 +225,42 @@ export function listArchived(filter: ArchiveListFilter = {}): ArchiveListResult
   const page = filter.page ?? 1;
   const start = (page - 1) * limit;
   return { items: sorted.slice(start, start + limit), total };
-}
+}
+
+export interface DoneItem extends Todo {
+  location: "live" | "archive";
+  archivedAt: string | null;
+}
+
+export interface DoneFilter {
+  text?: string;       // title OR notes substring (case-insensitive)
+  project?: string;
+  since?: string;      // closedAt >= since
+  before?: string;     // closedAt < before
+  limit?: number;      // default 50
+  page?: number;       // default 1
+}
+
+/** Unified done todos across the live store + the archive. Excludes cancelled
+ *  (Done = finished work). Sorted newest-closed first. */
+export function listDoneUnified(filter: DoneFilter = {}): DoneItem[] {
+  const live = loadStore().todos.filter((t) => t.status === "done");
+  const arch = loadArchive().todos.filter((t) => t.status === "done");
+  const items: DoneItem[] = [
+    ...live.map((t) => ({ ...t, location: "live" as const, archivedAt: null })),
+    ...arch.map((t) => ({ ...t, location: "archive" as const, archivedAt: t.closedAt })),
+  ];
+  let out = items;
+  if (filter.text) {
+    const q = filter.text.toLowerCase();
+    out = out.filter((t) => t.title.toLowerCase().includes(q) || t.notes.toLowerCase().includes(q));
+  }
+  if (filter.project) out = out.filter((t) => t.project === filter.project);
+  if (filter.since) out = out.filter((t) => (t.closedAt ?? t.updatedAt) >= (filter.since as string));
+  if (filter.before) out = out.filter((t) => (t.closedAt ?? t.updatedAt) < (filter.before as string));
+  const sorted = out.slice().sort((a, b) => (b.closedAt ?? b.updatedAt).localeCompare(a.closedAt ?? a.updatedAt));
+  const limit = filter.limit ?? 50;
+  const page = filter.page ?? 1;
+  const start = (page - 1) * limit;
+  return sorted.slice(start, start + limit);
+}

package/src/auto-prune.ts

@@ -0,0 +1,15 @@
+// Auto-prune on session_start — the deterministic age-gated prune that runs
+// when the extension loads. Wraps pruneTodos with the config default age; never
+// --all (fresh done <defaultAgeDays stays). Returns the rich PruneResult if
+// anything moved, else null (caller stays silent). Reversible via restore.
+
+import { pruneTodos, type PruneResult } from "./archive.ts";
+import { loadConfig } from "./config.ts";
+
+/** Prune stale done/cancelled (older than config.prune.defaultAgeDays) on
+ *  session start. Returns the PruneResult if anything moved, else null. */
+export function autoPruneOnSessionStart(): PruneResult | null {
+  const config = loadConfig();
+  const res = pruneTodos({ ageDays: config.prune.defaultAgeDays });
+  return res.moved > 0 ? res : null;
+}

package/src/health.ts

@@ -23,6 +23,12 @@ export interface ArchiveHealth {
   older_180d: number;      // closedAt older than archiveOldDays
 }
 
+export interface NotesBytes {
+  total: number;
+  max: number;
+  avg: number;
+}
+
 export type HealthFlag =
   | "ACTIVE_LARGE" | "ACTIVE_STALE"
   | "PARKED_LARGE" | "PARKED_STALE"
@@ -32,6 +38,7 @@ export interface HealthReport {
   active: ActiveHealth;
   parked: ParkedHealth;
   archive: ArchiveHealth;
+  notesBytes: NotesBytes;
   flags: HealthFlag[];
   suggestions: string[];
 }
@@ -55,6 +62,15 @@ export function healthReport(): HealthReport {
   const parkedStale = parkedTodos.filter((t) => daysAgo(t.updatedAt) > h.parkedStaleDays).length;
   const archiveOld = archive.todos.filter((t) => t.closedAt && daysAgo(t.closedAt) > h.archiveOldDays).length;
 
+  // notes bytes across active + parked (archived excluded — sealed history).
+  const apTodos = [...openTodos, ...ipTodos, ...parkedTodos];
+  const notesSizes = apTodos.map((t) => Buffer.byteLength(t.notes, "utf8"));
+  const notesBytes: NotesBytes = {
+    total: notesSizes.reduce((a, b) => a + b, 0),
+    max: notesSizes.length ? Math.max(...notesSizes) : 0,
+    avg: notesSizes.length ? Math.round(notesSizes.reduce((a, b) => a + b, 0) / notesSizes.length) : 0,
+  };
+
   const active: ActiveHealth = {
     open: openTodos.length,
     in_progress: ipTodos.length,
@@ -77,5 +93,5 @@ export function healthReport(): HealthReport {
   if (parkedStale > 0) suggestions.push(`parked: ${parkedStale} parked > ${h.parkedStaleDays}d → restore or hard-prune`);
   if (actionable.length > h.activeMaxOpen) suggestions.push(`active: ${actionable.length} open+in_progress (max ${h.activeMaxOpen}) → close or park some before adding more`);
 
-  return { active, parked, archive: arch, flags, suggestions };
+  return { active, parked, archive: arch, notesBytes, flags, suggestions };
 }

package/src/migrate.ts

@@ -10,6 +10,36 @@
 import { copyFileSync, existsSync, mkdirSync, renameSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
+// v2 → v3 schema migration helpers. splitTextFallback is used by loadStore's
+// inline derivation (Task 1) and by migrateV2ToV3 (Task 2, with the curated
+// map). TITLE_MAX here must match the constant in todo-store.ts.
+const TITLE_MAX = 120;
+
+/** Truncate at the last word boundary ≤ TITLE_MAX (hard cut if none). No "…"
+ *  suffix — the cap is a hard rule, not a display truncation. */
+function truncateWordBoundary(s: string): string {
+  if (s.length <= TITLE_MAX) return s;
+  const slice = s.slice(0, TITLE_MAX);
+  const sp = slice.lastIndexOf(" ");
+  return sp > 0 ? slice.slice(0, sp) : slice;
+}
+
+/** Derive { title, notes } from a v2 `text` string (the fallback for any v2
+ *  todo not in the curated map). Deterministic + idempotent. */
+export function splitTextFallback(text: string): { title: string; notes: string } {
+  const raw = (text ?? "").trim();
+  if (!raw) return { title: "(untitled)", notes: "" };
+  const nl = raw.indexOf("\n");
+  if (nl < 0) {
+    if (raw.length <= TITLE_MAX) return { title: raw, notes: "" };
+    return { title: truncateWordBoundary(raw), notes: raw };
+  }
+  const firstLine = raw.slice(0, nl).trim();
+  const rest = raw.slice(nl + 1).trim();
+  if (firstLine.length <= TITLE_MAX) return { title: firstLine, notes: rest };
+  return { title: truncateWordBoundary(firstLine), notes: `${firstLine}\n${rest}` };
+}
+
 export interface MigrateInput {
   /** The v2 folder (e.g. ~/.pi/agent/todo/). */
   todoDir: string;
@@ -42,4 +72,83 @@ export function migrateIfNeeded(input: MigrateInput): void {
     try { copyFileSync(backup, input.legacyPath); } catch { /* best-effort */ }
     throw new Error(`migration failed: could not move ${input.legacyPath} → ${target}`);
   }
-}
+}
+// v2 → v3 schema migration: each todo gains title + notes (curated for the
+// 2 ids known at migration time; splitTextFallback for the rest), drops text.
+// Pure — does not touch disk. Deterministic + idempotent on v2 input.
+// (splitTextFallback + TITLE_MAX are defined above, alongside migrateIfNeeded.)
+
+/** A v2 todo (has `text`, no `title`/`notes`). */
+export interface V2Todo {
+  id: string;
+  text: string;
+  project: string;
+  tags: string[];
+  priority: string;
+  status: string;
+  source: string;
+  createdAt: string;
+  updatedAt: string;
+  closedAt: string | null;
+}
+
+/** v2 store shape (input to migrateV2ToV3). */
+export interface V2Store {
+  version: 2;
+  updatedAt: string;
+  todos: V2Todo[];
+}
+
+// Hand-curated title + notes for the 2 todos known at v2→v3 migration time
+// (the only survivors of the v0.2.0 incident). Any other v2 todo uses
+// splitTextFallback. Curated notes are reformatted for clarity, not a
+// mechanical split.
+const CURATED_V2_TO_V3: Record<string, { title: string; notes: string }> = {
+  "td-mrt3zp9fcnug3p": {
+    title: "ZeroClaw×Solana bounty — Phase 4-5: demo video (score bottleneck, unstarted)",
+    notes: `superteam.fun/earn/listing/zeroclaw · Superteam Brasil · 5,000 USDG pool / 1st=1,800 · winner Aug 21 2026 · TARGET #1.
+
+PHASE 0-2 DONE ✅. PHASE 3 (RESEARCH+SPEC+PLAN + impl alerts+custody+docs) DONE ✅ — slices A-F+H, 45 tests, committed 8fd7483→80614c8, PUSHED, PR #76 retitled "Palinurus — depin-attest + depin-rewards", 17 commits.
+
+claim_tx (G) DEFERRED — Helium hotspots are cNFTs → claim needs distribute_compression_rewards_v0 + DAS get_asset_proof (merkle proof), multi-session; PDAs verified, design in README.
+
+Decision (score-max): ship alerts core complete, pivot to DEMO track.
+
+NEXT (★ Phase 4-5, the score bottleneck — submission REQUIRES a demo video, currently unstarted):
+(1) ASYNC: RECTOR's free Relay Community key → real Helium fixtures + live smoke test;
+(2) Phase 4: wiring SVG (docs/wiring-diagram.svg, dark-mode, NOT ASCII) + marketing site (palinurus.rectorspace.com, Next.js+Tailwind+shadcn) + demo recording guide;
+(3) Phase 5: record demo ≤3min (real ZeroClaw+Telegram, terminal+phone) → ElevenLabs voiceover → ffmpeg → submit on Superteam Earn + engage #solana-bounty Discord.
+
+Test totals: 184 (71 palinurus-core + 68 depin-attest + 45 depin-rewards), all clippy+wasm clean.
+HANDOFF: ~/Documents/secret/strategy/zeroclaw-solana/session-handoff-2026-07-21.md
+Docs: {RESEARCH-3,SPEC-3,PLAN-3}-depin-rewards.md (SPEC-3 §4 + PLAN-3 G corrected for cNFT)
+Cwd: ~/local-dev/RECTOR-LABS/zeroclaw-plugins/plugins/depin-rewards
+PR: https://github.com/zeroclaw-labs/zeroclaw-plugins/pull/76`,
+  },
+  "td-mrt4e1qi9td6jz": {
+    title: "armory-todo v0.2.0 — Workstream A shipped (lifecycle boxes + prune + health + TUI)",
+    notes: `ALL 3 SPECS DONE ✅. SPEC-1 (store: parked+prune+archive+restore, 12 tasks), SPEC-2 (health+hard-prune, 6 tasks), SPEC-3 (interactive /todo TUI panel, 4 tasks). 147/147 tests across 7 suites. 24 commits on feat/spec-1-lifecycle-boxes, PR #3 retitled to full v0.2.0 scope. Auto-publish CI (release.yml, org NPM_TOKEN).
+
+INCIDENT (SPEC-1 Task 9): migration bug destroyed real 52KB/47-todo store (35 done + ~10 open lost, no backup). FIXED (c034509): migration guarded to only run when TODO_DIR is default. RECOVERED: 2 todos.
+
+Shipped: merge PR #3 → tag v0.2.0 → CI auto-publish → npm:@getpipher/armory-todo@0.2.0.
+Out of scope: B (title+notes split), C (preventive caps+project registry).`,
+  },
+};
+
+/** Transform a v2 store into a v3 store: each todo gains title + notes
+ *  (curated for the 2 known ids, splitTextFallback for the rest), drops text.
+ *  Pure — does not touch disk. Deterministic + idempotent on v2 input. */
+export function migrateV2ToV3(store: V2Store): { version: 3; updatedAt: string; todos: any[] } {
+  const todos = store.todos.map((t) => {
+    const curated = CURATED_V2_TO_V3[t.id];
+    if (curated) {
+      const { text: _drop, ...rest } = t;
+      return { ...rest, title: curated.title, notes: curated.notes };
+    }
+    const { title, notes } = splitTextFallback(t.text ?? "");
+    const { text: _drop, ...rest } = t;
+    return { ...rest, title, notes };
+  });
+  return { version: 3, updatedAt: store.updatedAt, todos };
+}