@getpipher/armory-todo 0.1.0 → 0.2.0

package/extensions/todo.ts

@@ -3,13 +3,20 @@
  *
  * Unlike the existing pi todo extensions (which are conversation-branch-scoped:
  * they survive compaction/reload *within one session* via appendEntry), this
- * one is backed by a single disk file (~/.pi/agent/todo.json) so a TODO added
- * in session A is visible in any session B. It also auto-injects an "Open
- * TODOs" block into the system prompt on every before_agent_start, so a fresh
- * session is proactively aware of pending work instead of starting blind.
+ * one is backed by disk files under ~/.pi/agent/todo/ so a TODO added in
+ * session A is visible in any session B. It also auto-injects an "Open TODOs"
+ * block into the system prompt on every before_agent_start, so a fresh session
+ * is proactively aware of pending work instead of starting blind.
  *
- * Surface: `todo` tool (model CRUD), `/todo` slash command (human triage).
- * See docs/todo-SPEC.md for the design.
+ * Lifecycle boxes (v0.2.0):
+ *   - active  (open, in_progress) → auto-injected into the prompt
+ *   - parked  (parked)            → NOT injected; one status flip from active
+ *   - archive (done, cancelled)   → NOT injected; sealed history in
+ *                                    todo-archive.json, recoverable via restore
+ *
+ * Surface: `todo` tool (model CRUD + lifecycle), `/todo` slash command (human
+ * triage). See docs/superpowers/specs/2026-07-20-lifecycle-boxes-prune-design.md
+ * for the design.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -23,10 +30,15 @@ import {
   listTodos,
   renderOpenBlock,
   updateTodo,
+  parkTodo,
   getStorePath,
 } from "../src/todo-store";
+import { pruneTodos, restoreTodo, listArchived, archiveSummary } from "../src/archive";
+import { healthReport } from "../src/health";
+import { hardPrune } from "../src/hard-prune";
+import { TodoPanel } from "../src/panel";
 
-const ACTIONS = ["list", "add", "update", "complete", "delete", "clear"] as const;
+const ACTIONS = ["list", "add", "update", "complete", "delete", "clear", "park", "prune", "restore", "health"] as const;
 
 function fmt(t: ReturnType<typeof listTodos>[number]): string {
   const tag = t.project ? ` (${t.project})` : "";
@@ -39,16 +51,24 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     try {
       const open = listTodos();
-      if (ctx.hasUI) {
-        ctx.ui.notify(`armory-todo: ${open.length} open TODO${open.length === 1 ? "" : "s"}`, "info");
+      let msg = `armory-todo: ${open.length} open TODO${open.length === 1 ? "" : "s"}`;
+      try {
+        const report = healthReport();
+        if (report.flags.length > 0) {
+          msg += ` — ⚠ ${report.flags.length} bloat signal${report.flags.length === 1 ? "" : "s"} (run /todo health)`;
+        }
+      } catch {
+        // health check optional — don't crash the session notify
       }
+      if (ctx.hasUI) ctx.ui.notify(msg, "info");
     } catch {
       // store unavailable — never crash the session
     }
   });
 
   // Auto-inject the open-TODO block into the system prompt every turn so the
-  // agent is always aware of pending cross-session work.
+  // agent is always aware of pending cross-session work. Only open + in_progress
+  // are injected — parked and archived are excluded (the lifecycle-box boundary).
   pi.on("before_agent_start", async (event: any) => {
     try {
       const base = (event?.systemPrompt as string | undefined) ?? "";
@@ -65,36 +85,87 @@ export default function (pi: ExtensionAPI) {
     label: "TODO",
     description:
       "Global cross-session TODO store (persists across ALL pi sessions, not just this one). " +
-      "Use when the user says 'put this in our TODO', 'show me the TODO', 'mark <id> done', etc. " +
-      "Open TODOs are also auto-injected into your context each turn. " +
+      "Use when the user says 'put this in our TODO', 'show me the TODO', 'mark <id> done', 'park <id>', 'prune', 'restore <id>', 'how is my todo hygiene?', etc. " +
+      "Open TODOs are auto-injected each turn; parked todos are NOT injected (deferred/someday). " +
+      "Done/cancelled todos are moved to an archive by `prune` (reversible via `restore`). " +
+      "`prune --hard` (hard:true, confirm:true) is the ONLY irreversible action — always run `health` first, surface the report + proposed command, and wait for explicit user confirmation. " +
       "Never put secrets in a TODO — the text reaches the model provider.",
-    promptSnippet: "Read/update the global cross-session TODO list",
+    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:'complete', id) to mark a TODO done, and (action:'update', id, …) to edit one.",
+      "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.",
+      "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.",
     ],
     parameters: Type.Object({
       action: StringEnum(ACTIONS),
-      id: Type.Optional(Type.String({ description: "Todo id (for update/complete/delete)" })),
-      text: Type.Optional(Type.String({ description: "Todo text (add) or new text (update)" })),
+      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)" })),
       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)),
-      status: Type.Optional(StringEnum(["open", "in_progress", "done", "cancelled"] as const)),
+      status: Type.Optional(StringEnum(["open", "in_progress", "parked", "done", "cancelled"] as const)),
       // list filters
-      statusFilter: Type.Optional(StringEnum(["open", "in_progress", "done", "cancelled", "all"] as const)),
+      statusFilter: Type.Optional(StringEnum(["open", "in_progress", "parked", "done", "cancelled", "all"] as const)),
       projectFilter: Type.Optional(Type.String()),
       tagFilter: Type.Optional(Type.String()),
+      archived: Type.Optional(Type.Boolean({ description: "If true, query the archive instead of the live store. Bare archived:true (no other filter) returns a summary." })),
+      since: Type.Optional(Type.String({ description: "ISO date filter (createdAt for live, closedAt for archive)" })),
+      before: Type.Optional(Type.String({ description: "ISO date filter (createdAt for live, closedAt for archive)" })),
+      limit: Type.Optional(Type.Number({ description: "Page size (default 20)" })),
+      page: Type.Optional(Type.Number({ description: "1-indexed page number (default 1)" })),
+      // prune options
+      ageDays: Type.Optional(Type.Number({ description: "prune: closedAt older than this many days (default from config)" })),
+      all: Type.Optional(Type.Boolean({ description: "prune: ignore age, move all done/cancelled" })),
+      // hard-prune options (SPEC-2)
+      hard: Type.Optional(Type.Boolean({ description: "prune: if true, execute a HARD prune (permanent deletion). Requires confirm:true. The only irreversible action." })),
+      confirm: Type.Optional(Type.Boolean({ description: "hard-prune: must be true to execute. Always surface the health report + proposed command and wait for explicit user confirmation first." })),
+      box: Type.Optional(StringEnum(["archive", "active", "parked"] as const, { description: "hard-prune: which box to target (default archive)" })),
+      olderThan: Type.Optional(Type.Number({ description: "hard-prune: delete items older than this many days (by closedAt for archive, updatedAt for active/parked)" })),
     }),
     async execute(_toolCallId, params) {
       try {
         switch (params.action) {
           case "list": {
+            if (params.archived) {
+              const res = listArchived({
+                project: params.projectFilter,
+                tag: params.tagFilter,
+                status: params.statusFilter as any,
+                text: params.text,
+                since: params.since,
+                before: params.before,
+                limit: params.limit,
+                page: params.page,
+              });
+              if (res.summary) {
+                const lines = [
+                  `## Archive summary (${res.total} total)`,
+                  "By project:",
+                  ...Object.entries(res.summary.byProject).map(([p, n]) => `  ${p}: ${n}`),
+                  "By month:",
+                  ...Object.entries(res.summary.byMonth).map(([m, n]) => `  ${m}: ${n}`),
+                  "Use a filter (project/tag/text/since/before) to list specific items.",
+                ];
+                return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+              }
+              const lines = res.items.map(fmt);
+              return { content: [{ type: "text" as const, text: `Archived (${res.total} total, page ${params.page ?? 1}):\n${lines.join("\n")}` }] };
+            }
             const todos = listTodos({
               status: params.statusFilter as any,
               project: params.projectFilter,
               tag: params.tagFilter,
+              text: params.text,
+              since: params.since,
+              before: params.before,
+              limit: params.limit,
+              page: params.page,
             });
             if (todos.length === 0) {
               return { content: [{ type: "text" as const, text: "No matching TODOs." }] };
@@ -135,6 +206,42 @@ export default function (pi: ExtensionAPI) {
             const t = deleteTodo(params.id);
             return { content: [{ type: "text" as const, text: `Cancelled ${t.id}: ${t.text}` }] };
           }
+          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}` }] };
+          }
+          case "prune": {
+            if (params.hard) {
+              const res = hardPrune({
+                confirm: params.confirm === true,
+                box: params.box,
+                olderThan: params.olderThan,
+                project: params.projectFilter,
+                tag: params.tagFilter,
+              });
+              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)"}` }] };
+          }
+          case "health": {
+            const report = healthReport();
+            const lines = [
+              `## TODO Health Report`,
+              `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)`,
+              report.flags.length ? `flags: ${report.flags.join(", ")}` : "flags: (none — healthy)",
+              ...report.suggestions.map((s) => `  → ${s}`),
+            ];
+            return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+          }
+          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]` }] };
+          }
           case "clear": {
             const n = clearTodos((params.status as any) ?? "done");
             return { content: [{ type: "text" as const, text: `Cleared ${n} '${params.status ?? "done"}' TODOs.` }] };
@@ -148,9 +255,13 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  // Human slash command: /todo [all|add <text>|done <id>|rm <id>|clean|path]
+  // Human slash command.
   pi.registerCommand("todo", {
-    description: "Global cross-session TODO list. /todo · /todo all · /todo add <text> · /todo done <id> · /todo rm <id> · /todo clean · /todo path",
+    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",
     handler: async (args, ctx) => {
       const a = (args ?? "").trim();
       const [sub, ...rest] = a.split(/\s+/);
@@ -182,6 +293,85 @@ export default function (pi: ExtensionAPI) {
           if (ctx.hasUI) ctx.ui.notify(`Cancelled ${t.id}`, "info");
           return;
         }
+        if (sub === "park") {
+          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");
+          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");
+          return;
+        }
+        if (sub === "prune") {
+          const isHard = rest.includes("--hard");
+          if (isHard) {
+            const boxIdx = rest.indexOf("--box");
+            const olderIdx = rest.indexOf("--older-than");
+            const projIdx = rest.indexOf("--project");
+            const box = boxIdx >= 0 ? rest[boxIdx + 1] : undefined;
+            const olderThan = olderIdx >= 0 ? Number(rest[olderIdx + 1]) : undefined;
+            const project = projIdx >= 0 ? rest[projIdx + 1] : undefined;
+            const preview = hardPrune({ confirm: false, box: box as any, olderThan, project });
+            if (ctx.hasUI) {
+              const yes = await ctx.ui.confirm(
+                "Hard Prune",
+                `HARD PRUNE (permanent deletion)\n${preview.message}\nBox: ${box ?? "archive"}${olderThan ? `, older than ${olderThan}d` : ""}${project ? `, project: ${project}` : ""}\n\nProceed?`,
+              );
+              if (!yes) { ctx.ui.notify("Hard-prune cancelled.", "info"); return; }
+            }
+            const res = hardPrune({ confirm: true, box: box as any, olderThan, project });
+            if (ctx.hasUI) ctx.ui.notify(res.message + ` Deleted: ${res.ids.join(", ") || "(none)"}`, res.refused ? "warning" : "info");
+            return;
+          }
+          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");
+          return;
+        }
+        if (sub === "health") {
+          const report = healthReport();
+          const lines = [
+            `TODO Health:`,
+            `  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)`,
+            report.flags.length ? `  ⚠ ${report.flags.join(", ")}` : "  ✅ healthy",
+            ...report.suggestions.map((s) => `  → ${s}`),
+          ];
+          if (ctx.hasUI) ctx.ui.notify(lines.join("\n"), "info");
+          return;
+        }
+        if (sub === "archive") {
+          const filterArg = rest.join(" ").trim();
+          if (!filterArg) {
+            const s = archiveSummary();
+            const lines = [
+              `Archive summary (${s.total} total):`,
+              "By project:",
+              ...Object.entries(s.byProject).map(([p, n]) => `  ${p}: ${n}`),
+              "By month:",
+              ...Object.entries(s.byMonth).map(([m, n]) => `  ${m}: ${n}`),
+              "Use /todo archive project:<name> or text:<query> to list specific items.",
+            ];
+            if (ctx.hasUI) ctx.ui.notify(lines.join("\n"), "info");
+            return;
+          }
+          // parse "project:foo" or "text:query" (simple key:value)
+          const parts = filterArg.split(":");
+          const key = parts[0]?.trim();
+          const val = parts.slice(1).join(":").trim();
+          const res = key === "project" ? listArchived({ project: val, limit: 50 })
+            : key === "text" ? listArchived({ text: val, limit: 50 })
+            : listArchived({ text: filterArg, limit: 50 });
+          const msg = res.items.length ? res.items.map(fmt).join("\n") : "(no archived items match)";
+          if (ctx.hasUI) ctx.ui.notify(`Archived (${res.total} total):\n${msg}`, "info");
+          return;
+        }
         if (sub === "clean") {
           const n = clearTodos("done");
           if (ctx.hasUI) ctx.ui.notify(`Cleared ${n} done TODOs.`, "info");
@@ -191,7 +381,24 @@ export default function (pi: ExtensionAPI) {
           if (ctx.hasUI) ctx.ui.notify(`store: ${getStorePath()}`, "info");
           return;
         }
-        // default: list open
+        // default: open the interactive panel (TUI) or list open (non-TUI)
+        if (ctx.mode === "tui") {
+          await ctx.ui.custom<boolean>((_tui, theme, _kb, done) => {
+            const panel = new TodoPanel({
+              theme: theme as any,
+              onDone: () => done(true),
+              onNotify: (msg, type) => ctx.ui.notify(msg, type ?? "info"),
+            });
+            return {
+              render: (width: number) => panel.render(width),
+              invalidate: () => panel.invalidate(),
+              handleInput: (data: string) => panel.handleInput(data),
+              dispose: () => { panel.dispose?.(); },
+            } as any;
+          });
+          return;
+        }
+        // non-TUI fallback: list open as text
         const todos = listTodos();
         const msg = todos.length ? todos.map(fmt).join("\n") : "(no open TODOs)";
         if (ctx.hasUI) ctx.ui.notify(msg, "info");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-todo",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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": "node test/todo-store.test.mts"
+    "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"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/archive.ts

@@ -0,0 +1,204 @@
+// Sealed history store for armory-todo — holds done/cancelled todos moved
+// here by `prune`. Recoverable via `restore`; permanently deletable only via
+// `prune --hard` (SPEC-2). Never auto-injected into the system prompt.
+//
+// File: <TODO_DIR>/todo-archive.json (0600, atomic write). Missing on disk
+// → empty store returned; the file is created on first save, not first load.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { getArchivePath } from "./paths.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;
+  updatedAt: string;
+  todos: Todo[];
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function emptyArchive(): ArchiveStore {
+  return { version: 2, updatedAt: now(), todos: [] };
+}
+
+/** Load the archive. Missing file → empty store (no file created). */
+export function loadArchive(): ArchiveStore {
+  const path = getArchivePath();
+  if (!existsSync(path)) return emptyArchive();
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw) as ArchiveStore;
+    if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.todos)) {
+      throw new Error("invalid archive shape");
+    }
+    return parsed;
+  } catch {
+    try {
+      renameSync(path, `${path}.bad-${Date.now()}`);
+    } catch {
+      // best-effort backup
+    }
+    return emptyArchive();
+  }
+}
+
+/** Atomic, 0600 write. */
+export function saveArchive(store: ArchiveStore): void {
+  store.updatedAt = now();
+  const path = getArchivePath();
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  try {
+    chmodSync(tmp, 0o600);
+  } catch {
+    // some filesystems ignore mode bits
+  }
+  renameSync(tmp, path);
+}
+
+export interface PruneInput {
+  ageDays?: number;
+  all?: boolean;
+  statuses?: ("done" | "cancelled")[];
+}
+
+export interface PruneResult {
+  moved: number;
+  ids: string[];
+}
+
+/**
+ * Move done/cancelled todos from the live store to the archive.
+ *
+ * A todo qualifies when:
+ *   - its status is in `statuses` (default: config.prune.statuses = done+cancelled), AND
+ *   - `all` is true, OR its `closedAt` is older than `ageDays` days ago
+ *     (default: config.prune.defaultAgeDays).
+ *
+ * Both stores are saved atomically. Reversible via `restoreTodo`.
+ */
+export function pruneTodos(opts: PruneInput = {}): PruneResult {
+  const config = loadConfig();
+  const ageDays = opts.ageDays ?? config.prune.defaultAgeDays;
+  const statuses = new Set(opts.statuses ?? config.prune.statuses);
+  const cutoff = opts.all ? null : Date.now() - ageDays * 86400_000;
+
+  const live = loadStore();
+  const archive = loadArchive();
+
+  const moved: Todo[] = [];
+  const kept: Todo[] = [];
+  for (const todo of live.todos) {
+    if (!statuses.has(todo.status as "done" | "cancelled")) {
+      kept.push(todo);
+      continue;
+    }
+    if (cutoff !== null && todo.closedAt && Date.parse(todo.closedAt) > cutoff) {
+      // too fresh — keep in live
+      kept.push(todo);
+      continue;
+    }
+    moved.push(todo);
+  }
+
+  if (moved.length === 0) return { moved: 0, ids: [] };
+
+  live.todos = kept;
+  archive.todos.push(...moved);
+  saveStore(live);
+  saveArchive(archive);
+
+  return { moved: moved.length, ids: moved.map((t) => t.id) };
+}
+
+/**
+ * Move an archived todo back to the live store as `open` (closedAt cleared).
+ * Throws TodoError if the id is not in the archive. Both stores are saved.
+ */
+export function restoreTodo(id: string): Todo {
+  const archive = loadArchive();
+  const idx = archive.todos.findIndex((t) => t.id === id);
+  if (idx < 0) throw new TodoError(`not in archive: ${id}`);
+  const [todo] = archive.todos.splice(idx, 1);
+  const live = loadStore();
+  todo.status = "open";
+  todo.closedAt = null;
+  todo.updatedAt = now();
+  live.todos.push(todo);
+  saveStore(live);
+  saveArchive(archive);
+  return todo;
+}
+
+export interface ArchiveListFilter {
+  project?: string;
+  tag?: string;
+  status?: "done" | "cancelled";
+  text?: string;
+  since?: string;    // by closedAt
+  before?: string;   // by closedAt
+  limit?: number;    // default 20
+  page?: number;     // default 1
+}
+
+export interface ArchiveSummary {
+  total: number;
+  byProject: Record<string, number>;
+  byMonth: Record<string, number>;
+}
+
+export interface ArchiveListResult {
+  items: Todo[];
+  total: number;       // total matching the filter (before pagination)
+  summary?: ArchiveSummary;  // present only on a bare call (no filters)
+}
+
+/** Counts by project + by closedAt-month, for the summary-first default. */
+export function archiveSummary(): ArchiveSummary {
+  const archive = loadArchive();
+  const byProject: Record<string, number> = {};
+  const byMonth: Record<string, number> = {};
+  for (const t of archive.todos) {
+    const proj = t.project || "(none)";
+    byProject[proj] = (byProject[proj] ?? 0) + 1;
+    const month = t.closedAt ? t.closedAt.slice(0, 7) : "(none)"; // YYYY-MM
+    byMonth[month] = (byMonth[month] ?? 0) + 1;
+  }
+  return { total: archive.todos.length, byProject, byMonth };
+}
+
+/**
+ * Query the archive with filters + pagination. A bare call (no filters)
+ * returns summary-only (items: []) — drill down with a filter to get rows.
+ */
+export function listArchived(filter: ArchiveListFilter = {}): ArchiveListResult {
+  const hasFilter = Boolean(filter.project || filter.tag || filter.status || filter.text || filter.since || filter.before);
+  if (!hasFilter) {
+    const summary = archiveSummary();
+    return { items: [], total: summary.total, summary };
+  }
+  let out = loadArchive().todos;
+  if (filter.project) out = out.filter((t) => t.project === filter.project);
+  if (filter.tag) out = out.filter((t) => t.tags.includes(filter.tag as string));
+  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));
+  }
+  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));
+  // sort newest-closed first
+  const sorted = out.slice().sort((a, b) => (b.closedAt ?? b.updatedAt).localeCompare(a.closedAt ?? a.updatedAt));
+  const total = sorted.length;
+  const limit = filter.limit ?? 20;
+  const page = filter.page ?? 1;
+  const start = (page - 1) * limit;
+  return { items: sorted.slice(start, start + limit), total };
+}

package/src/config.ts

@@ -0,0 +1,101 @@
+// Prune + health configuration for armory-todo.
+//
+// Stored at <TODO_DIR>/todo.config.json. Missing or corrupt → defaults are
+// rewritten (the bad file is backed up to todo.config.json.bad-<ts>). All
+// values are editable (later, via the SPEC-3 /todo Config panel).
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { getConfigPath } from "./paths.ts";
+
+export interface PruneConfig {
+  /** Closed todos older than this (by closedAt) are moved to archive on `prune`. */
+  defaultAgeDays: number;
+  /** Archive items older than this are flagged for hard-prune suggestion. */
+  hardAgeDays: number;
+  /** Which terminal statuses get pruned. */
+  statuses: ("done" | "cancelled")[];
+}
+
+export interface HealthConfig {
+  activeMaxOpen: number;
+  activeStaleDays: number;
+  parkedMax: number;
+  parkedStaleDays: number;
+  archiveMax: number;
+  archiveOldDays: number;
+}
+
+export interface TodoConfig {
+  version: 1;
+  prune: PruneConfig;
+  health: HealthConfig;
+}
+
+export const DEFAULT_CONFIG: TodoConfig = {
+  version: 1,
+  prune: {
+    defaultAgeDays: 7,
+    hardAgeDays: 180,
+    statuses: ["done", "cancelled"],
+  },
+  health: {
+    activeMaxOpen: 15,
+    activeStaleDays: 30,
+    parkedMax: 10,
+    parkedStaleDays: 60,
+    archiveMax: 200,
+    archiveOldDays: 180,
+  },
+};
+
+/** Deep clone of DEFAULT_CONFIG (so callers can't mutate the constant). */
+function freshDefaults(): TodoConfig {
+  return JSON.parse(JSON.stringify(DEFAULT_CONFIG)) as TodoConfig;
+}
+
+export function loadConfig(): TodoConfig {
+  const path = getConfigPath();
+  if (!existsSync(path)) {
+    const cfg = freshDefaults();
+    saveConfig(cfg);
+    return cfg;
+  }
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw) as TodoConfig;
+    if (!parsed || typeof parsed !== "object" || !parsed.prune || !parsed.health) {
+      throw new Error("invalid config shape");
+    }
+    // Merge with defaults so new fields get filled in on upgrade.
+    return {
+      version: 1,
+      prune: { ...DEFAULT_CONFIG.prune, ...parsed.prune },
+      health: { ...DEFAULT_CONFIG.health, ...parsed.health },
+    };
+  } catch {
+    try {
+      renameSync(path, `${path}.bad-${Date.now()}`);
+    } catch {
+      // best-effort backup
+    }
+    const cfg = freshDefaults();
+    saveConfig(cfg);
+    return cfg;
+  }
+}
+
+/** Atomic, 0600 write. */
+export function saveConfig(config: TodoConfig): void {
+  const path = getConfigPath();
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  try {
+    chmodSync(tmp, 0o600);
+  } catch {
+    // some filesystems ignore mode bits
+  }
+  renameSync(tmp, path);
+}