@getpipher/armory-todo 0.5.5 → 0.6.0

package/docs/superpowers/specs/2026-07-29-reap-safety-protocol-design.md

@@ -0,0 +1,187 @@
+# v0.6.0 — Source-aware stale-active reaping ("safety protocol")
+
+**Date:** 2026-07-29
+**Status:** Approved + implemented (release verification pending)
+**Branch:** `feat/reap-safety-protocol` off `main`
+**Predecessor:** v0.5.3 (wiper fix + data-loss defense complete), PR #11, shipped 2026-07-21
+**Target ship:** v0.6.0, auto-published via `release.yml` on `v0.6.0` tag
+
+---
+
+## 1. Problem
+
+The v0.5.3 session closed armory-todo as "fully complete." Eight days of heavy
+dogfooding later, RECTOR flagged a new symptom: **"every day I see many todos in
+`/todo`."** Investigation of the live store (`~/.pi/agent/todo/todo.json`, 229
+todos, 688KB) found three mechanics producing the bloat:
+
+1. **`armory-fleet` auto-tracking (volume driver).** Every `subagent(...)` and
+   background fleet run auto-creates a tracked TODO (`source: "armory-fleet"`,
+   `tag: "fleet-run"`). 187 fleet todos created in 5 days — 82% of the live
+   store. By design, but high-volume under dogfooding.
+
+2. **Orphaned fleet runs (the real leak).** 42 fleet todos are
+   `open`/`in_progress` with no `updatedAt` movement in 3–7 days. These are
+   dead runs — background process killed, session closed, run abandoned —
+   where fleet only closed its tracked todo on the **happy path** (foreground
+   completion or `fleet_results` pull). Fleet never closes the todo when the
+   run dies. **Auto-prune (v0.3.1) only touches `done`/`cancelled`, so orphaned
+   active todos pile up indefinitely** — they never reach a terminal status.
+
+3. **Done-todos linger up to 7 days (working as designed).** 151 done todos in
+   the live store, all <3d old. Auto-prune archives them at the 7-day mark.
+   Correct behavior, but high volume makes the visible queue large.
+
+The user's hypothesis ("agents don't mark done") was **wrong** — the data shows
+151 done vs 65 open; agents close todos fine. The real bug is **producer
+discipline**: `armory-fleet` should close its todo on every terminal state, but
+relying on every consumer to behave correctly is fragile. A new extension, a
+sloppy agent, a crashed session — any can orphan a todo.
+
+**The fix belongs in armory-todo, not fleet.** Defense-in-depth: the store
+self-heals regardless of who wrote it. This is the "safety protocol" — any agent
+or extension using armory-todo gets orphan-leak protection for free, without
+coordinating with armory-todo's maintainers.
+
+## 2. Goals
+
+- **Self-heal orphaned active todos** from known-prolific producers
+  (`armory-fleet`) without cross-package coordination.
+- **Never auto-mutate real work.** Todos with no `source` (agent-managed,
+  real-work) are flagged-only — irreversible state changes stay human-driven.
+- **Immediate reversibility.** Reaping sets status to `cancelled` and moves the
+  todo directly from the live store to the archive (never deleted) →
+  `todo restore <id>` works immediately. Same `.bak-drop-<ts>` snapshot +
+  audit-log guardrails as the v0.5.1 backup system — a bad threshold or runaway
+  reap is recoverable.
+- **Config-driven, YAGNI-respecting.** The reap-able source list lives in
+  `todo.config.json`. Adding a new source later is a config edit, not a code
+  change. Ship with `armory-fleet` only; expand when there's a real second
+  producer.
+- **Zero migration.** Pure additive — one new config section, one new module,
+  two new health flags. Existing stores load unchanged.
+
+## 3. Non-goals (deferred / rejected)
+
+| Out of scope | Why |
+|---|---|
+| Auto-reap for non-fleet sources | Real work stays flag-only — irreversible actions stay human-driven |
+| `reapTo: "done"` option | Only `cancelled` — semantically "abandoned run," not "completed work" |
+| Per-project reap policy | `source` is the right discriminator (it identifies the producer), not `project` |
+| Background reaper (cron) | `session_start` is enough — RECTOR boots pi daily |
+| **Sub-todos** | Brainstormed and **rejected**. The diagnosed problem is orphan lifecycle, not hierarchy. Sub-todos add cascade semantics, break v0.5.0 caps counting, hit the pi-tui nested-UI blocker, and `notes`-as-checklist already covers 80% at zero schema cost. Revisit only if epic-level independent lifecycle tracking becomes a real pain. |
+| Fixing `armory-fleet` itself | Filed as a separate observation — fleet should close its todo on run death. This spec makes armory-todo resilient *regardless* of whether fleet is ever fixed. |
+
+## 4. Decisions log (from brainstorm Q&A)
+
+| # | Question | Decision |
+|---|---|---|
+| Q1 | Drop sub-todos? | **Yes** — not needed once orphans self-heal. Rejected for this release; see §3. |
+| Q2 | Safety posture (surface / source-aware reap / universal reap) | **B — source-aware auto-reap.** Fleet-source active todos are auto-`cancelled` at 2d; real (`source: undefined`) todos are flag-only at 14d. The `source` field cleanly separates producers (57 fleet = `armory-fleet`, ~22 real = no source). |
+| Q3 | Fleet reap threshold | **2d.** The 42 current orphans are 3–7d old; 2d catches the next wave before they pile up. Fleet runs that matter resolve in minutes, not days. |
+| Q4 | Non-fleet orphan-flag threshold | **14d.** RECTOR's dormant `zeroclaw-solana` sas-fix is 8d and intentionally paused — 14d gives it headroom so it doesn't nag. |
+| Q5 | Reap-able source list | **`["armory-fleet"]` only, for now.** Open list is YAGNI; config schema supports future additions without code change. |
+| Q6 | Reap target status | **`cancelled`** (reversible via `restore`); never deleted. |
+| Q7 | "Stale" signal | **`updatedAt`** — already on every todo, bumped on every `update`. No new `lastTouchedAt` field. |
+| Q8 | Reap timing | **`session_start`**, immediately after `autoPruneOnSessionStart()`. One self-healing pass per boot. |
+| Q9 | Audit/backup | Reuse v0.5.1 `snapshotOnDrop` + `appendAudit` — same guardrails, no new mechanism. |
+| Q10 | Reaped todo destination (implementation challenge, approved 2026-08-02) | **A — immediate archive.** A live `cancelled` todo is hidden from every panel tab and `restoreTodo` only accepts archived ids. Therefore reaping atomically partitions live→archive so `todo restore <id>` works immediately. Intentional count drops retain backup/drop-snapshot/audit but suppress the false wipe-alert sentinel. |
+
+## 5. Architecture
+
+| Layer | File | Change | New? |
+|---|---|---|---|
+| Config schema | `src/config.ts` | + `ReapConfig` interface + `DEFAULT_CONFIG.reap` + merge validation + corrupt recovery | extend |
+| Reap logic | `src/reap.ts` | New module — `reapStaleActive(): ReapResult \| null` (mirrors `auto-prune.ts` shape) | **new** |
+| Health flags | `src/health.ts` | + `ORPHAN` (flagged-not-reaped, real todos — advisory, transient) | extend |
+| Audit/notify | `extensions/todo.ts` | `REAPED` is an **audit-log marker** (not a `HealthFlag` — reaped todos become archived `cancelled` and leave the active box, so health never sees them). Surfaced via the reap notify line + a cumulative run count in the Archive tab. | extend |
+| Session_start wiring | `extensions/todo.ts` | Call `reapStaleActive()` after `autoPruneOnSessionStart()`; surface reap result in the existing notify block | extend |
+| Backup/audit | `src/backup.ts` | Reuse `snapshotOnDrop` + `appendAudit` (box `"todo"`, counts-only) — no new mechanism | reuse |
+| Store/archive | `src/todo-store.ts` + `src/archive.ts` | Reap batch-partitions matched todos from live into archive as `cancelled`; `saveStore(..., { intentionalDrop: "reap" })` keeps backup/drop-snapshot/audit while suppressing a false wipe alert | extend + reuse |
+| Panel | `src/panel-data.ts` / `panel.ts` | `ORPHAN` row indicator (⌛), cumulative `reaped=N` sum in Archive tab, and interactive Config rows for orphan/reap thresholds | extend |
+| Tests | `test/todo-reap.test.mts` | **new suite** + extend `todo-config` + `todo-health` + `todo-auto-prune` | new + extend |
+
+## 6. Config shape
+
+```ts
+interface ReapConfig {
+  /** Non-fleet active todos older than this (by updatedAt) → ORPHAN flag, no mutation. */
+  orphanFlagAfterDays: number;        // default 14
+  /** Per-source reap policy. Sources not listed are flagged-only (never auto-mutated). */
+  policy: Record<string, { reapAfterDays: number; reapTo: "cancelled" }>;
+}
+
+// DEFAULT_CONFIG.reap = {
+//   orphanFlagAfterDays: 14,
+//   policy: { "armory-fleet": { reapAfterDays: 2, reapTo: "cancelled" } }
+// }
+```
+
+`TodoConfig` gains a `reap: ReapConfig` field. The existing merge + corrupt-recovery
+path in `loadConfig` handles the new section with the same pattern: missing →
+defaults merged in; corrupt → bad file backed up to `todo.config.json.bad-<ts>`,
+defaults rewritten.
+
+## 7. Data flow (one `session_start` pass)
+
+| Step | Action | Mutates? | Audited? |
+|---|---|---|---|
+| 1 | `autoPruneOnSessionStart()` runs (existing) — moves done/cancelled >7d to archive | yes | yes (existing) |
+| 2 | **`reapStaleActive()` runs** — for each active todo: compute `staleDays = (now − updatedAt) / 86400000` | no (read) | — |
+| 3a | If `todo.source` ∈ `reap.policy` AND `staleDays ≥ reapAfterDays` → set `cancelled`, remove from live, append to archive, count it | yes (live → archive) | **yes** — live `.bak-drop-<ts>` snapshot + both-store audit + `REAP` marker; intentional drop suppresses false wipe sentinel |
+| 3b | Else if `staleDays ≥ orphanFlagAfterDays` → set transient `__orphanDays` (in-memory health pass, **not persisted**) → surfaces `ORPHAN` flag + panel ⌛ | no | flag only |
+| 4 | If any reaped → notify `♻ Reaped N stale <source> runs (oldest Kd) — restore via /todo` | — | — |
+| 5 | If any orphaned → existing "N open" notify appends `+ M orphaned (oldest Kd untouched)` | — | — |
+
+**Key invariants:**
+- A todo with `source: undefined` (real agent work) is **never** auto-mutated by
+  the reap sweep. It can only get the `ORPHAN` flag, which is advisory.
+- A todo with `source` not in `reap.policy` is also flag-only (same as no source).
+- Reap target is always archived `cancelled` — `restore` reverses it immediately. Nothing is ever deleted.
+- The orphan flag is **transient** — recomputed each session from `updatedAt`. It
+  is not written to disk (avoids a schema bump + migration just for a display hint).
+
+## 8. Error handling & safety
+
+| Risk | Guard |
+|---|---|
+| Cancelling real work by mistake | Only `source` ∈ `reap.policy` ever auto-mutates; real todos are flag-only forever |
+| Reap is irreversible | Reaped todos are immediately archived as `cancelled` (never deleted) → `todo restore <id>` reverses them immediately |
+| Bad threshold wipes a batch | `.bak-drop-<ts>` snapshot before the reap write (v0.5.1 pattern) + audit log line — same recovery path as the 2026-07-21 wipe incident |
+| Reap runs on a corrupt store | `loadConfig` already backs up corrupt config to `.bad-<ts>`; reap skips if store load throws |
+| Reap double-fires in one session | `session_start` is once-per-boot; idempotent anyway (already-cancelled todos aren't re-counted) |
+| New source added later | Config-driven — add to `policy` map, no code change |
+| Reap fires on a fresh store with no `reap` config | Merge installs defaults; `armory-fleet` policy present from first load |
+
+## 9. Testing
+
+| Suite | New/extend | Covers |
+|---|---|---|
+| `test/todo-reap.test.mts` | **new** | reap fleet at 2d ✓; immediate live→archive move ✓; immediate `restoreTodo` reversibility ✓; flag non-policy at 14d (no mutate) ✓; audit line + `.bak-drop` ✓; no false `.wipe-alert` ✓; corrupt-store skip ✓; idempotency ✓; `updatedAt` stale signal ✓ |
+| `test/todo-config.test.mts` | extend | `reap` defaults + merge + corrupt recovery |
+| `test/todo-health.test.mts` | extend | `ORPHAN` flag raised (transient, not persisted); no regression on existing flags |
+| `test/panel-data.test.mts` | extend | ⌛ formatter input; audit parser sums `reaped=N` values (not marker lines); orphan/reap Config rows |
+| `test/todo-auto-prune.test.mts` | extend | ordering: auto-prune then reap in the same `session_start` pass; both fire independently |
+
+All new suites use the existing `TODO_DIR=tmp` isolation pattern (the
+v0.5.3 wiper lesson — re-establish `process.env.TODO_DIR` at the start of any
+appended section that writes).
+
+## 10. Shipping
+
+- Version bump: `0.5.5` → `0.6.0` (`package.json`).
+- npm publish via CI on `v0.6.0` tag (`release.yml`).
+- `~/.pi/agent/settings.json` pin updated to `npm:@getpipher/armory-todo@0.6.0`.
+- GitHub Release v0.6.0 synced with npm.
+- AGENTS.md structure table + Notes section updated (new `reap` module + suite).
+- Memory: `~/.pi/agent/memory/-Users-rector-local-dev-getpipher-armory-todo/v0.6.0-shipped.md`.
+
+## 11. Resolved review decisions
+
+| Decision | Resolution |
+|---|---|
+| Notify copy | Accepted with lifecycle-correct immediate-archive restore guidance. |
+| Panel marker | `⌛` for advisory ORPHAN rows. |
+| First-run cleanup | No one-shot path; normal 2d policy catches existing fleet orphans. |
+| Reaped destination | Option A (approved 2026-08-02): immediate archive as `cancelled`, so `restore` works immediately. |
+| Reap metric placement | Archive tab, because reaped records are archived cancelled (Done intentionally excludes cancelled). |

package/extensions/todo.ts

@@ -39,6 +39,7 @@ import { healthReport } from "../src/health";
 import { hardPrune } from "../src/hard-prune";
 import { TodoPanel } from "../src/panel";
 import { autoPruneOnSessionStart } from "../src/auto-prune";
+import { reapStaleActive } from "../src/reap";
 import { loadConfig, type TodoConfig } from "../src/config";
 import { projectsOverview } from "../src/projects";
 import { renameProject } from "../src/registry";
@@ -104,22 +105,38 @@ export default function (pi: ExtensionAPI) {
       } catch {
         // auto-prune optional — don't crash the session notify
       }
+      // v0.6.0: source-aware stale-active reap runs AFTER auto-prune. Reaped
+      // todos enter the archive as cancelled (immediately restorable), never deleted.
+      let reapMsg = "";
+      try {
+        const rp = reapStaleActive();
+        if (rp) {
+          const shownIds = rp.ids.slice(0, 5).map((id) => `[${id}]`).join(" ");
+          const more = rp.ids.length > 5 ? ` +${rp.ids.length - 5} more` : "";
+          reapMsg = ` · ♻ reaped ${rp.reaped} stale ${rp.reaped === 1 ? "run" : "runs"} (oldest ${rp.oldestDays}d) · ${shownIds}${more} — restore via \`todo restore <id>\``;
+        }
+      } catch {
+        // reap optional — never crash the session notify
+      }
       const showCount = cfg?.notify?.sessionStartCount !== false;
       const open = listTodos();
       let msg = "";
       if (showCount) {
-        msg = `armory-todo: ${open.length} open TODO${open.length === 1 ? "" : "s"}${autoMsg}`;
+        msg = `armory-todo: ${open.length} open TODO${open.length === 1 ? "" : "s"}${autoMsg}${reapMsg}`;
         try {
           const report = healthReport();
           if (report.flags.length > 0) {
             msg += `${autoMsg ? "\n" : " — "}` + `⚠ ${report.flags.length} bloat signal${report.flags.length === 1 ? "" : "s"} (run /todo health)`;
           }
+          if (report.orphan.count > 0) {
+            msg += ` · ${report.orphan.count} orphaned (oldest ${report.orphan.oldestDays}d untouched, non-policy — review in /todo)`;
+          }
         } catch {
           // health check optional
         }
-      } else if (autoMsg) {
-        // Count line suppressed; still surface the auto-prune undo info.
-        msg = `armory-todo${autoMsg}`;
+      } else if (autoMsg || reapMsg) {
+        // Count line suppressed; still surface auto-prune/reap safety messages.
+        msg = `armory-todo${autoMsg}${reapMsg}`;
       }
       if (ctx.hasUI) {
         const out = (wipeMsg ? wipeMsg + "\n" : "") + msg;
@@ -569,4 +586,4 @@ export default function (pi: ExtensionAPI) {
       }
     },
   });
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-todo",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Global, cross-session TODO for pi \u2014 persists across all sessions and is auto-injected into every prompt. The disk-backed counterpart to branch-scoped pi todo extensions.",
   "keywords": [
     "pi-package",
@@ -41,7 +41,7 @@
     ]
   },
   "scripts": {
-    "test": "for t in todo-store todo-title-notes todo-archive todo-config todo-migrate todo-health todo-hard-prune todo-auto-prune registry projects panel-data todo-caps todo-backup public-api; 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 registry projects panel-data todo-caps todo-backup todo-reap public-api; do node test/$t.test.mts || exit 1; done"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/archive.ts

@@ -137,7 +137,7 @@ export function pruneTodos(opts: PruneInput = {}): PruneResult {
 
   live.todos = kept;
   archive.todos.push(...moved);
-  saveStore(live);
+  saveStore(live, { intentionalDrop: "prune" });
   saveArchive(archive);
 
   const items: PruneItem[] = moved.map((t) => ({

package/src/config.ts

@@ -30,16 +30,32 @@ export interface HealthConfig {
 
 export interface NotifyConfig {
   /** Show the `armory-todo: N open TODOs` session-start count line.
-   *  Safety messages (wipe-recovery alert, auto-prune undo info) still surface
-   *  when this is false. Default true. */
+   *  Safety messages (wipe recovery, auto-prune, reap) still surface when this
+   *  is false. Default true. */
   sessionStartCount: boolean;
 }
 
+export interface ReapPolicyEntry {
+  /** Active todos from this source older than this (by updatedAt) are auto-`reapTo`'d. */
+  reapAfterDays: number;
+  /** Terminal status applied. v0.6.0 only supports "cancelled" (reversible via restore). */
+  reapTo: "cancelled";
+}
+
+export interface ReapConfig {
+  /** Active todos whose `source` is NOT in `reap.policy`, older than this (by
+   *  updatedAt) → ORPHAN flag (advisory, transient — no mutation). */
+  orphanFlagAfterDays: number;
+  /** Per-source reap policy. Sources not listed are flag-only (never auto-mutated). */
+  policy: Record<string, ReapPolicyEntry>;
+}
+
 export interface TodoConfig {
   version: 1;
   prune: PruneConfig;
   health: HealthConfig;
   notify: NotifyConfig;
+  reap: ReapConfig;
 }
 
 export const DEFAULT_CONFIG: TodoConfig = {
@@ -62,6 +78,12 @@ export const DEFAULT_CONFIG: TodoConfig = {
   notify: {
     sessionStartCount: true,
   },
+  reap: {
+    orphanFlagAfterDays: 14,
+    policy: {
+      "armory-fleet": { reapAfterDays: 2, reapTo: "cancelled" },
+    },
+  },
 };
 
 /** Deep clone of DEFAULT_CONFIG (so callers can't mutate the constant). */
@@ -90,11 +112,22 @@ export function loadConfig(): TodoConfig {
     }
     const notify = { ...DEFAULT_CONFIG.notify, ...(parsed.notify ?? {}) };
     if (typeof notify.sessionStartCount !== "boolean") notify.sessionStartCount = true;
+    const reap = { ...DEFAULT_CONFIG.reap, ...(parsed.reap ?? {}) };
+    if (reap.orphanFlagAfterDays === undefined || typeof reap.orphanFlagAfterDays !== "number" || Number.isNaN(reap.orphanFlagAfterDays) || reap.orphanFlagAfterDays < 0) {
+      reap.orphanFlagAfterDays = DEFAULT_CONFIG.reap.orphanFlagAfterDays;
+    }
+    if (!reap.policy || typeof reap.policy !== "object") reap.policy = {};
+    for (const [src, entry] of Object.entries(reap.policy)) {
+      if (!entry || typeof entry.reapAfterDays !== "number" || entry.reapAfterDays < 0 || entry.reapTo !== "cancelled") {
+        delete reap.policy[src];
+      }
+    }
     return {
       version: 1,
       prune: { ...DEFAULT_CONFIG.prune, ...parsed.prune },
       health,
       notify,
+      reap,
     };
   } catch {
     try {

package/src/health.ts

@@ -37,7 +37,8 @@ export type HealthFlag =
   | "PARKED_LARGE" | "PARKED_STALE"
   | "ARCHIVE_LARGE" | "ARCHIVE_OLD"
   | "NOTES_OVER"
-  | "PROJECT_OVER" | "PROJECT_TYPO" | "PROJECT_LARGE" | "PROJECT_STALE";
+  | "PROJECT_OVER" | "PROJECT_TYPO" | "PROJECT_LARGE" | "PROJECT_STALE"
+  | "ORPHAN";
 
 export interface ProjectHealth {
   name: string;
@@ -55,6 +56,7 @@ export interface HealthReport {
   parked: ParkedHealth;
   archive: ArchiveHealth;
   notesBytes: NotesBytes;
+  orphan: { count: number; oldestDays: number; ids: string[] };
   flags: HealthFlag[];
   suggestions: string[];
   projects: ProjectHealth[];   // only projects with ≥1 flag, sorted open desc
@@ -81,6 +83,20 @@ export function healthReport(): HealthReport {
   const parkedTodos = live.todos.filter((t) => t.status === "parked");
   const actionable = [...openTodos, ...ipTodos];
 
+  // v0.6.0: policy-source stale actives are auto-reaped elsewhere; non-policy
+  // stale actives are advisory-only ORPHANs. Derived on every read, never persisted.
+  const policySources = new Set(Object.keys(config.reap.policy));
+  const orphanTodos = actionable.filter((t) =>
+    !policySources.has(t.source) && daysAgo(t.updatedAt) >= config.reap.orphanFlagAfterDays
+  );
+  const orphan = {
+    count: orphanTodos.length,
+    oldestDays: orphanTodos.length
+      ? Math.floor(Math.max(...orphanTodos.map((t) => daysAgo(t.updatedAt))))
+      : 0,
+    ids: orphanTodos.map((t) => t.id),
+  };
+
   const activeStale = openTodos.filter((t) => daysAgo(t.updatedAt) > h.activeStaleDays).length;
   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;
@@ -115,6 +131,7 @@ export function healthReport(): HealthReport {
   if (actionable.length > h.activeMaxOpen) flags.push("ACTIVE_LARGE");
   if (notesBytes.max > h.maxNotesBytes) flags.push("NOTES_OVER");
   if (activeStale > 0) flags.push("ACTIVE_STALE");
+  if (orphan.count > 0) flags.push("ORPHAN");
   if (parkedTodos.length > h.parkedMax) flags.push("PARKED_LARGE");
   if (parkedStale > 0) flags.push("PARKED_STALE");
   if (archive.todos.length > h.archiveMax) flags.push("ARCHIVE_LARGE");
@@ -123,6 +140,7 @@ export function healthReport(): HealthReport {
   const suggestions: string[] = [];
   if (archiveOld > 0) suggestions.push(`archive: ${archiveOld} items older than ${h.archiveOldDays}d → consider \`prune --hard --box archive --older-than ${h.archiveOldDays} --confirm\``);
   if (activeStale > 0) suggestions.push(`active: ${activeStale} open TODOs untouched for ${h.activeStaleDays}d → park or close them`);
+  if (orphan.count > 0) suggestions.push(`orphan: ${orphan.count} active TODOs untouched >= ${config.reap.orphanFlagAfterDays}d (non-policy source) → review + close/park (oldest ${orphan.oldestDays}d)`);
   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`);
   if (notesBytes.max > h.maxNotesBytes) {
@@ -167,5 +185,5 @@ export function healthReport(): HealthReport {
 
   const noProject = { open: live.todos.filter((t) => t.project.trim() === "" && t.status === "open").length };
 
-  return { active, parked, archive: arch, notesBytes, flags, suggestions, projects: projectHealth, noProject };
-}
+  return { active, parked, archive: arch, notesBytes, orphan, flags, suggestions, projects: projectHealth, noProject };
+}

package/src/index.d.ts

@@ -62,6 +62,10 @@ export interface Store {
   todos: Todo[];
 }
 
+export interface SaveStoreOptions {
+  intentionalDrop?: "reap" | "prune";
+}
+
 export class TodoError extends Error {}
 
 export function addTodo(input: AddInput): Todo;
@@ -75,4 +79,4 @@ export function clearTodos(status?: Status): number;
 export function renderOpenBlock(max?: number): string;
 export function getStorePath(): string;
 export function loadStore(): Store;
-export function saveStore(store: Store): void;
+export function saveStore(store: Store, options?: SaveStoreOptions): void;

package/src/index.ts

@@ -34,6 +34,7 @@ export type {
   Priority,
   Status,
   Store,
+  SaveStoreOptions,
 } from "./todo-store.ts";
 
 export { TodoError } from "./todo-store.ts";

package/src/panel-data.ts

@@ -2,8 +2,11 @@
 // panel.ts so they're unit-testable without a terminal — the panel component
 // itself is manual-gate only.
 
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { SelectItem, SettingItem } from "@earendil-works/pi-tui";
 import type { Todo } from "./todo-store.ts";
+import { getTodoDir } from "./paths.ts";
 import type { DoneItem } from "./archive.ts";
 import type { ArchiveSummary } from "./archive.ts";
 import type { TodoConfig } from "./config.ts";
@@ -12,13 +15,14 @@ import type { TodoConfig } from "./config.ts";
  *  title is already ≤120 chars (enforced at write time), so no truncation is
  *  needed. The • marker shows when notes is non-empty (signals "open the
  *  detail view / use `todo get` for context"). */
-export function todoToItem(t: Todo): SelectItem {
+export function todoToItem(t: Todo, orphan = false): SelectItem {
+  const warning = orphan ? "⌛ " : "";
   const pin = t.status === "in_progress" ? " ⏵" : "";
   const proj = t.project ? ` (${t.project})` : "";
   const dot = t.notes.trim() ? " •" : "";
   return {
     value: t.id,
-    label: `[${t.id}] (${t.priority})${pin}${proj}${dot} ${t.title}`,
+    label: `${warning}[${t.id}] (${t.priority})${pin}${proj}${dot} ${t.title}`,
   };
 }
 
@@ -56,6 +60,8 @@ export function configToSettingItems(cfg: TodoConfig): SettingItem[] {
     { id: "hardAgeDays", label: "Hard-prune age (days)", currentValue: String(cfg.prune.hardAgeDays), values: ["90", "180", "365"], description: "Archive items older than this → suggested for hard-prune." },
     { id: "activeMaxOpen", label: "Active max open", currentValue: String(cfg.health.activeMaxOpen), values: ["10", "15", "20", "25"], description: "Bloat flag when open+in_progress exceeds this." },
     { id: "activeStaleDays", label: "Active stale (days)", currentValue: String(cfg.health.activeStaleDays), values: ["14", "30", "60"], description: "Bloat flag when open todos untouched longer than this." },
+    { id: "orphanFlagAfterDays", label: "Orphan flag (days)", currentValue: String(cfg.reap.orphanFlagAfterDays), values: ["7", "14", "30", "60"], description: "Advisory ORPHAN flag for non-policy active todos; never auto-mutates." },
+    { id: "armoryFleetReapAfterDays", label: "Fleet reap (days)", currentValue: String(cfg.reap.policy["armory-fleet"]?.reapAfterDays ?? 2), values: ["1", "2", "3", "7"], description: "Stale armory-fleet runs → archived cancelled (immediately restorable)." },
     { id: "parkedMax", label: "Parked max", currentValue: String(cfg.health.parkedMax), values: ["5", "10", "15"], description: "Bloat flag when parked exceeds this." },
     { id: "parkedStaleDays", label: "Parked stale (days)", currentValue: String(cfg.health.parkedStaleDays), values: ["30", "60", "90"], description: "Bloat flag when parked longer than this." },
     { id: "archiveMax", label: "Archive max", currentValue: String(cfg.health.archiveMax), values: ["100", "200", "500"], description: "Bloat flag when archive exceeds this." },
@@ -111,3 +117,21 @@ export function actionsForProject(): { label: string; action: string }[] {
 export function noProjectSummaryItem(o: ProjectsOverview): SelectItem {
   return { value: "__noproject__", label: `(no project): ${o.noProject.count} total · ${o.noProject.open} open` };
 }
+
+/** Sum the number of runs auto-reaped across REAP audit markers. Best-effort;
+ *  malformed/missing logs report zero and never break the panel. */
+export function countReapedFromAudit(): number {
+  try {
+    const path = join(getTodoDir(), "todo-audit.log");
+    if (!existsSync(path)) return 0;
+    let total = 0;
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+      if (!line.startsWith("REAP ")) continue;
+      const match = line.match(/\breaped=(\d+)\b/);
+      if (match) total += Number(match[1]);
+    }
+    return total;
+  } catch {
+    return 0;
+  }
+}

package/src/panel.ts

@@ -26,7 +26,7 @@ import { loadConfig, saveConfig, type TodoConfig } from "./config.ts";
 import { healthReport } from "./health.ts";
 import { projectsOverview } from "./projects.ts";
 import { renameProject, setProjectMaxOpen, loadRegistry, saveRegistry } from "./registry.ts";
-import { todoToItem, archiveSummaryToItems, actionsForTodo, configToSettingItems, todoDoneItem, actionsForDoneTodo, projectOverviewToItems, actionsForProject, noProjectSummaryItem } from "./panel-data.ts";
+import { todoToItem, archiveSummaryToItems, actionsForTodo, configToSettingItems, todoDoneItem, actionsForDoneTodo, projectOverviewToItems, actionsForProject, noProjectSummaryItem, countReapedFromAudit } from "./panel-data.ts";
 
 export type Box = "active" | "parked" | "done" | "archive" | "projects" | "config";
 const BOXES: Box[] = ["active", "parked", "done", "archive", "projects", "config"];
@@ -54,6 +54,7 @@ export class TodoPanel extends Container {
   private settingsList: SettingsList | null = null;
   private config: TodoConfig;
   private healthFlags: string[] = [];
+  private orphanIds = new Set<string>();
   private projectFilterName = "";      // set by the "Filter active to project" action
   private projectEditKind: "rename" | "setmax" | null = null;
   private projectEditName = "";       // which project is being edited
@@ -64,7 +65,6 @@ export class TodoPanel extends Container {
     this.onDone = opts.onDone;
     this.onNotify = opts.onNotify;
     this.config = loadConfig();
-    try { this.healthFlags = healthReport().flags; } catch { /* optional */ }
 
     const accent = (s: string) => this.theme.fg("accent", s);
     this.addChild(new DynamicBorder(accent));
@@ -132,6 +132,11 @@ export class TodoPanel extends Container {
     } else if (this.currentBox === "config") {
       this.renderConfigBox();
     } else {
+      if (this.currentBox === "archive") {
+        const reaped = countReapedFromAudit();
+        this.addChild(new Text(this.theme.fg("muted", `  reaped: ${reaped} runs auto-cancelled · restore with todo restore <id>`), 0, 0));
+        this.addChild(new Spacer(1));
+      }
       this.addChild(this.selectList);
     }
 
@@ -144,13 +149,20 @@ export class TodoPanel extends Container {
 
   private refreshList(): void {
     const filter = this.filterInput.getValue();
+    try {
+      const report = healthReport();
+      this.healthFlags = report.flags;
+      this.orphanIds = new Set(report.orphan.ids);
+    } catch {
+      // health is advisory; retain the last successful snapshot
+    }
     if (this.currentBox === "active") {
       const project = this.projectFilterName || undefined;
       const todos = listTodos({ project, text: filter || undefined, limit: 50 });
-      this.setSelectItems(todos.map(todoToItem));
+      this.setSelectItems(todos.map((t) => todoToItem(t, this.orphanIds.has(t.id))));
     } else if (this.currentBox === "parked") {
       const todos = listTodos({ status: "parked", text: filter || undefined, limit: 50 });
-      this.setSelectItems(todos.map(todoToItem));
+      this.setSelectItems(todos.map((t) => todoToItem(t)));
     } else if (this.currentBox === "done") {
       const items = listDoneUnified({ text: filter || undefined, limit: 50 });
       this.setSelectItems(items.map(todoDoneItem));
@@ -160,7 +172,7 @@ export class TodoPanel extends Container {
         this.setSelectItems(archiveSummaryToItems(s));
       } else {
         const res = listArchived({ text: filter, limit: 50 });
-        this.setSelectItems(res.items.map(todoToItem));
+        this.setSelectItems(res.items.map((t) => todoToItem(t)));
       }
     } else if (this.currentBox === "projects") {
       const overview = projectsOverview();
@@ -388,6 +400,8 @@ export class TodoPanel extends Container {
       case "hardAgeDays": return String(c.prune.hardAgeDays);
       case "activeMaxOpen": return String(c.health.activeMaxOpen);
       case "activeStaleDays": return String(c.health.activeStaleDays);
+      case "orphanFlagAfterDays": return String(c.reap.orphanFlagAfterDays);
+      case "armoryFleetReapAfterDays": return String(c.reap.policy["armory-fleet"]?.reapAfterDays ?? 2);
       case "parkedMax": return String(c.health.parkedMax);
       case "parkedStaleDays": return String(c.health.parkedStaleDays);
       case "archiveMax": return String(c.health.archiveMax);
@@ -405,6 +419,8 @@ export class TodoPanel extends Container {
       case "hardAgeDays": this.config.prune.hardAgeDays = n; break;
       case "activeMaxOpen": this.config.health.activeMaxOpen = n; break;
       case "activeStaleDays": this.config.health.activeStaleDays = n; break;
+      case "orphanFlagAfterDays": this.config.reap.orphanFlagAfterDays = n; break;
+      case "armoryFleetReapAfterDays": this.config.reap.policy["armory-fleet"] = { reapAfterDays: n, reapTo: "cancelled" }; break;
       case "parkedMax": this.config.health.parkedMax = n; break;
       case "parkedStaleDays": this.config.health.parkedStaleDays = n; break;
       case "archiveMax": this.config.health.archiveMax = n; break;
@@ -483,4 +499,4 @@ export class TodoPanel extends Container {
     this.refreshList();
     this.invalidate();
   }
-}
+}