@getpipher/armory-todo 0.5.5 → 0.7.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,12 +39,22 @@ 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 {
+  gatherCandidates,
+  executeTriage,
+  executeSafeClass,
+  renderProposalTable,
+  renderReport,
+  type TriageDecision,
+} from "../src/triage";
+import { buildTriagePrompt, TRIAGE_PROMPT_VERSION } from "../src/triage-prompt";
 import { loadConfig, type TodoConfig } from "../src/config";
 import { projectsOverview } from "../src/projects";
 import { renameProject } from "../src/registry";
 import { readAndClearWipeAlert } from "../src/backup";
 
-const ACTIONS = ["list", "add", "update", "get", "complete", "delete", "clear", "park", "prune", "restore", "health", "projects", "project_rename"] as const;
+const ACTIONS = ["list", "add", "update", "get", "complete", "delete", "clear", "park", "prune", "restore", "health", "projects", "project_rename", "triage"] as const;
 
 function fmt(t: ReturnType<typeof listTodos>[number]): string {
   const tag = t.project ? ` (${t.project})` : "";
@@ -104,22 +114,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;
@@ -170,6 +196,7 @@ export default function (pi: ExtensionAPI) {
       "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:'projects') for a per-project scope overview (open/in_progress/parked/done counts + maxOpen + OVER/?typo markers). Run when the user asks 'which projects have open work' or to see backlog shape by project.",
       "Use todo (action:'project_rename', oldName, newName) to rename or merge a project (rewrites live + archive + registry). Use it to fix typo'd project strings (e.g. foo-bat → foo-bar). Rename onto an existing name merges (consolidates the old project into the new). Per-project maxOpen caps are ENFORCED (block-on-add); they also drive a PROJECT_OVER health flag when breached.",
+      "Use todo (action:'triage') for agent-validated pruning: phase 1 gathers candidates (stale 30d + orphans 14d + over-cap projects + agent-source debris) and returns them with the versioned rubric — NOTHING mutates. Validate each candidate with read-only probes (git log / gh / npm view), present the proposal table (verdict + evidence + confidence), get ONE batch approval from the user, then call phase 2: todo(action:'triage', approve:[{id, verdict:'close'|'park'|'keep', reason?, evidence?, confidence?, survivorId?}]). Closed items are archived (reversible) and filed as CLOSED issues in the private getpipher/todo-ledger. autoSafe:true (--yes) executes ONLY the mechanical safe class (fleet-run prompt debris) — never auto-close anything you could not verify (zero false-closes). Scope with scope:'<project>'.",
     ],
     parameters: Type.Object({
       action: StringEnum(ACTIONS),
@@ -201,6 +228,19 @@ export default function (pi: ExtensionAPI) {
       // project actions (v0.4.0)
       oldName: Type.Optional(Type.String({ description: "project_rename: current project name" })),
       newName: Type.Optional(Type.String({ description: "project_rename: new project name (merge if it already exists)" })),
+      // triage (PRD 2026-08-30) — two phases within one action:
+      //   phase 1 (no approve): gather candidates + return the versioned rubric. NOTHING mutates.
+      //   phase 2 (approve): execute exactly the approved decisions, then file closed items to the ledger.
+      scope: Type.Optional(Type.String({ description: "triage: restrict candidates to one project name (empty = all)" })),
+      autoSafe: Type.Optional(Type.Boolean({ description: "triage (--yes): auto-execute ONLY the mechanical safe class (fleet-run prompt debris). Everything else stays a proposal — never auto-closed (D2)." })),
+      approve: Type.Optional(Type.Array(Type.Object({
+        id: Type.String({ description: "Candidate todo id (td-…)" }),
+        verdict: StringEnum(["close", "park", "keep"] as const),
+        reason: Type.Optional(Type.String({ description: "close only: debris | duplicate | stale-unverified | verified-shipped" })),
+        evidence: Type.Optional(Type.String({ description: "One CHECKED line (git/gh/npm probe result). Required for verified-shipped closes." })),
+        confidence: Type.Optional(StringEnum(["high", "medium", "low"] as const)),
+        survivorId: Type.Optional(Type.String({ description: "duplicate closes: the surviving todo id" })),
+      }), { description: "triage phase 2: the user-approved decisions. Executes exactly these; nothing else." })),
     }),
     async execute(_toolCallId, params) {
       try {
@@ -374,6 +414,44 @@ export default function (pi: ExtensionAPI) {
             const r = renameProject(params.oldName, params.newName);
             return { content: [{ type: "text" as const, text: `Renamed ${params.oldName} → ${r.newName}: ${r.liveRenamed} live + ${r.archivedRenamed} archived${r.merged ? " (merged)" : ""}` }] };
           }
+          case "triage": {
+            // Phase 2: execute exactly the user-approved decisions (D2 gate).
+            if (params.approve?.length) {
+              const before = gatherCandidates(params.scope).before;
+              const report = await executeTriage(params.approve as TriageDecision[]);
+              return { content: [{ type: "text" as const, text: renderReport(report, before) }] };
+            }
+            // Phase 1: gather + propose. NOTHING mutates unless autoSafe (--yes),
+            // which executes ONLY the mechanical safe class (fleet-run debris).
+            let safeMsg = "";
+            if (params.autoSafe) {
+              const { report, remaining } = await executeSafeClass(params.scope);
+              safeMsg = report
+                ? `--yes executed the safe class ONLY (fleet-run debris). Everything else needs the batch approval.\n\n${renderReport(report)}\n`
+                : "--yes: no mechanical-safe debris found — nothing auto-closed.\n";
+              if (report && remaining === 0) {
+                return { content: [{ type: "text" as const, text: safeMsg + "No remaining candidates — triage complete." }] };
+              }
+            }
+            const g = gatherCandidates(params.scope);
+            if (g.candidates.length === 0) {
+              return { content: [{ type: "text" as const, text: `${safeMsg}${safeMsg ? "\n" : ""}Triage: no candidates (before: ${g.before.active} active / ${g.before.parked} parked / ${g.before.archive} archive${g.scope ? `, scope: ${g.scope}` : ""}). Nothing to propose, nothing mutated.` }] };
+            }
+            const lines = [
+              `## Triage — proposal (NOTHING mutated yet)`,
+              `before: ${g.before.active} active / ${g.before.parked} parked / ${g.before.archive} archive${g.scope ? ` · scope: ${g.scope}` : ""} · candidates: ${g.candidates.length} · rubric ${TRIAGE_PROMPT_VERSION}`,
+              "",
+              renderProposalTable(g),
+              "",
+              safeMsg,
+              `Validate each candidate against the rubric below (read-only probes: git log, gh, npm view — checked, not guessed). Then present the proposal table (verdict + evidence + confidence) to the user and get ONE batch approval. On approval execute all decisions in a single call:`,
+              `  todo(action:"triage", approve:[{ id, verdict:"close"|"park"|"keep", reason?, evidence?, confidence?, survivorId? }, ...])`,
+              `Safety: close needs reason (debris|duplicate|stale-unverified|verified-shipped); duplicate needs survivorId; verified-shipped needs evidence. Items you cannot verify stay proposals — zero false-closes is the metric. The safe-class column marks what --yes may close WITHOUT approval.`,
+              "",
+              buildTriagePrompt(g.candidates, g.scope),
+            ];
+            return { content: [{ type: "text" as const, text: lines.filter((l) => l !== "").join("\n") }] };
+          }
           default:
             return { content: [{ type: "text" as const, text: `Unknown action: ${params.action}` }] };
         }
@@ -389,7 +467,7 @@ export default function (pi: ExtensionAPI) {
       "Global cross-session TODO list. " +
       "/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 projects / /todo health / /todo clean / /todo path",
+      "/todo archive [project:X|text:Y] / /todo finished / /todo projects / /todo health / /todo triage [scope] [--yes] / /todo clean / /todo path",
     handler: async (args, ctx) => {
       const a = (args ?? "").trim();
       const [sub, ...rest] = a.split(/\s+/);
@@ -466,6 +544,33 @@ export default function (pi: ExtensionAPI) {
           }
           return;
         }
+        if (sub === "triage") {
+          // Thin mirror of todo(action:'triage') — humans get the proposal table;
+          // the validation loop runs through the agent (rubric ships in-package).
+          const yes = rest.includes("--yes");
+          const scopeArg = rest.find((r) => !r.startsWith("--"));
+          let safeMsg = "";
+          if (yes) {
+            const { report, remaining } = await executeSafeClass(scopeArg);
+            safeMsg = report ? renderReport(report) + `\nremaining candidates: ${remaining}\n` : "--yes: no mechanical-safe debris — nothing auto-closed.\n";
+          }
+          const g = gatherCandidates(scopeArg);
+          const head = `Triage (before: ${g.before.active} active / ${g.before.parked} parked / ${g.before.archive} archive${scopeArg ? `, scope: ${scopeArg}` : ""})`;
+          if (g.candidates.length === 0) {
+            if (ctx.hasUI) ctx.ui.notify(`${head}\n${safeMsg || "No candidates — nothing to propose, nothing mutated."}`, "info");
+            return;
+          }
+          const msg = [
+            head,
+            safeMsg,
+            `candidates (${g.candidates.length}) — NOTHING mutated${yes ? " beyond the safe class above" : ""}:`,
+            renderProposalTable(g),
+            "",
+            `Ask the agent to validate these against the triage rubric (${TRIAGE_PROMPT_VERSION}) using read-only probes, then approve the batch. The agent executes via todo(action:"triage", approve:[…]); closed items are filed to ${"getpipher/todo-ledger"} (private).`,
+          ].filter((l) => l !== "").join("\n");
+          if (ctx.hasUI) ctx.ui.notify(msg, "info");
+          return;
+        }
         if (sub === "health") {
           const report = healthReport();
           const projLines = report.projects.length
@@ -569,4 +674,4 @@ export default function (pi: ExtensionAPI) {
       }
     },
   });
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-todo",
-  "version": "0.5.5",
+  "version": "0.7.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 triage 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;
+  }
+}