pi-pier 0.3.0 → 0.3.1

package/src/{core → plugins}/todo.ts

@@ -1,11 +1,9 @@
 /**
  * D78/D81 todo loader entry.
- *
- * A Cordis plugin keeps the master surface hot-swappable while allowing workers to mount the
- * one-shot subset directly. Injected services preserve the D79 registration boundary and keep
- * session-owned todo state in index. This module owns the tool, command, widget, read hook,
- * and master stop reminder; reconciliation, mirroring, and agent reporting stay with the
- * session state layer to avoid a dependency cycle.
+ * A Cordis plugin keeps the master surface hot-swappable while workers mount the one-shot subset directly;
+ * injected services preserve the D79 registration boundary and keep session-owned todo state in index. This
+ * module owns the tool, command, widget, read hook, and master stop reminder — reconciliation, mirroring, and
+ * agent reporting stay in the session state layer (cycle avoidance).
  */
 import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
@@ -14,31 +12,20 @@ import type { TodosService } from '../todos-service.ts';
 import { planTodoReadHook } from '../todo-read-hook.ts';
 import { TODO_REMINDER_CUSTOM_TYPE, planStopTodoReminder, todoReminderGraceMs } from '../todo-reminder-core.ts';
 import { makeProgressUpdate } from '../subagent-core.ts';
-import { TODO_DETAILS_KEY, TODO_TOOL_NAME, formatTodoConfirmation, type TodoItem } from '../vocab.ts';
-import { toolError } from '../tool-error.ts'
-
-/** Raw tool arguments: every field is validated inside the action handlers. */
-type ToolParams = Record<string, unknown> | undefined;;
+import { TODO_DETAILS_KEY, TODO_STATUSES, TODO_TOOL_NAME, formatTodoConfirmation, type TodoItem } from '../vocab.ts';
+import { toolError } from '../tool-error.ts';
 import { formatAge, isArchived } from '../stale-core.ts';
-import {
-  TODO_EDIT_CUSTOM_TYPE,
-  completionTransitions,
-  fuzzyFind,
-  listsEqual,
-  makeSnapshot,
-  normalizeStrict,
-  revertedCompleted,
-  validateTodos,
-} from '../todo-core.ts';
+import { TODO_EDIT_CUSTOM_TYPE, completionTransitions, fuzzyFind, listsEqual, makeSnapshot, normalizeStrict, revertedCompleted, validateTodos, type TodoEditOp } from '../todo-core.ts';
 import { anchorTodoRange, formatTodoSummary, renderTodoGroups } from '../todo-window.ts';
 import { swallow } from '../swallow.ts';
 
+type ToolParams = Record<string, unknown> | undefined;
+
 export interface TodoUiSlot {
   /** Lets index lifecycle events render through the currently mounted plugin. */
   renderWidget: (ctx: unknown) => void;
   /** Re-render from the last seen context without a fresh event (human-gate open/close). */
   rerenderWidget?: () => void;
-  /** Cancel any pending unfinished-todo reminder timer. */
   cancelReminder?: () => void;
 }
 
@@ -71,24 +58,28 @@ const TOOL_DESCRIPTION = [
   'Delegated work belongs on this list too. When you hand an entry to a subagent, append ` <sub>` to its content (the subagent is doing it, not you); when the subagent settles, a matching entry is auto-completed — you will see "Reconciled:" in the settlement note. If no auto-match fired, update the entry yourself.',
 ].join(' ');
 
-/** Stay within pi interactive mode's ten-line widget cap instead of relying on head truncation. */
-export const WIDGET_MAX_LINES = 10;
+/** pi interactive mode renders at most ten widget lines. */
+const WIDGET_MAX_LINES = 10;
+
+/** `/todos <op> <query>` verbs; the value is the user-facing past-tense feedback. */
+const OP_VERBS: Record<TodoEditOp, string> = {
+  done: 'completed',
+  drop: 'abandoned',
+  unblock: 'unblocked (back to pending)',
+  rm: 'removed',
+};
 
 /**
- * Keep the active task visible within WIDGET_MAX_LINES instead of truncating to a fixed head or
- * tail. The window anchors on the first in-progress item, then the last open item, then recent
- * completions. A +N line points to /todos when the full plan cannot fit. This fixes 01a03c0d,
- * where active work scrolled out while only the final entries remained visible.
+ * Keep the active task visible within WIDGET_MAX_LINES rather than truncating to a fixed head or tail:
+ * the window anchors on the first in-progress item, then the last open item, then recent completions.
  */
 export function widgetLines(
   items: readonly TodoItem[],
   opts?: { archivedAgeMs?: number | null; blockedDepth?: number | null },
 ): string[] {
   if (items.length === 0) return [];
-  // Human gate open (ask_user_question waiting): the question + editor own the fixed area, so the
-  // widget collapses to the one-line summary — /todos still reaches the full list. Without this,
-  // a 10-line widget plus a multi-line question leaves almost no scrollable transcript
-  // (user-reported: both blocks visible ⇒ history range too small).
+  // Human gate open (ask_user_question waiting): the question and editor own the fixed area, so the widget
+  // collapses to one summary line — a 10-line widget plus a multi-line question would leave no scrollable transcript.
   if ((opts?.blockedDepth ?? 0) > 0) {
     return [`${formatTodoSummary(items)} · /todos 全量`];
   }
@@ -100,8 +91,8 @@ export function widgetLines(
     ];
   }
 
-  // Reserve summary and overflow lines, then shrink around the anchor because phase headers also consume the budget.
-  const renderBudget = WIDGET_MAX_LINES - 1 - 1;
+  // Reserve summary and overflow lines; phase headers consume the budget too, hence the shrink loop.
+  const renderBudget = WIDGET_MAX_LINES - 2;
   const [start, end] = anchorTodoRange(
     items,
     (s, e) => renderTodoGroups(items.slice(s, e)).length <= renderBudget,
@@ -129,21 +120,13 @@ export default function todoPlugin(ctx: Context): void {
       : null;
   }
 
-  /** Name the guarded event UI once so callers do not repeat unsafe inline assertions. */
-  function widgetUi(eventCtx: unknown): { setWidget?: (id: string, lines: string[]) => void } | undefined {
-    if (eventCtx === null || typeof eventCtx !== 'object' || !('ui' in eventCtx)) return undefined;
-    const ui = (eventCtx as { ui: unknown }).ui; // Safe after the property guard above.
-    return ui !== null && typeof ui === 'object'
-      ? (ui as { setWidget?: (id: string, lines: string[]) => void })
-      : undefined;
-  }
-
   /** Gate transitions fire outside lifecycle events; remember one ctx so rerenderWidget can target the live ui. */
   let lastEventCtx: unknown = null;
   function renderWidget(eventCtx: unknown): void {
     if (eventCtx !== null && eventCtx !== undefined) lastEventCtx = eventCtx;
+    const ui = (eventCtx as { ui?: { setWidget?: (id: string, lines: string[]) => void } } | null | undefined)?.ui;
     try {
-      widgetUi(eventCtx)?.setWidget?.('todos', widgetLines(todos.items, {
+      ui?.setWidget?.('todos', widgetLines(todos.items, {
         archivedAgeMs: archivedAgeMs(),
         blockedDepth: getBlockedDepth?.() ?? 0,
       }));
@@ -152,7 +135,6 @@ export default function todoPlugin(ctx: Context): void {
     }
   }
 
-  // Let index lifecycle hooks call the current plugin implementation.
   state.renderWidget = renderWidget;
   state.rerenderWidget = () => renderWidget(lastEventCtx);
 
@@ -164,7 +146,6 @@ export default function todoPlugin(ctx: Context): void {
   let staleNotices = 0;
   let lastStaleGuardTurn: number | null = null;
 
-  // Any real edit ends the current stale period because the plan is active again.
   todos.on('todo.updated', () => {
     lastWriteTurn = todoReadTurn;
     staleNotices = 0;
@@ -185,21 +166,18 @@ export default function todoPlugin(ctx: Context): void {
       staleNotices += 1;
       lastStaleGuardTurn = todoReadTurn;
     }
-    // Share cadence across empty, archive, and R2 rewrite notices so adjacent notices do not
-    // consume the grace window.
+    // Empty, archive, and R2 rewrite notices share one cadence so adjacent notices do not each consume the grace window.
     if (plan.inject && (plan.effect === 'empty-guard' || plan.archived)) {
       lastEmptyGuardTurn = todoReadTurn;
     }
-    // R1 clears archived entries after notice because retaining dead items suppresses the empty
-    // guard that restored tracking after the 01a03c0d two-hour gap. Persist removals for replay;
-    // the session log still retains history.
+    // R1: persist the clear as one rm-per-item edit so replay folds to an empty list. The session
+    // log keeps the history; a dead in-memory list would suppress the empty guard.
     if (plan.inject && plan.effect === 'archive-notice' && plan.clearArchived && todos.items.length > 0) {
       const edits = todos.items.map((it) => ({ op: 'rm' as const, content: it.content }));
       try {
         appendEntry(TODO_EDIT_CUSTOM_TYPE, { version: 1, edits, ts: Date.now() });
       } catch (err) {
-        // Persistence is best-effort because the in-memory clear must still proceed, but a silent
-        // failure here is exactly how the archive/replay path broke unnoticed before (SA-13).
+        // The in-memory clear must proceed even when this persistence fails.
         swallow('todo.persist-archive', err);
       }
       todos.replace([], { source: 'archive' });
@@ -220,7 +198,7 @@ export default function todoPlugin(ctx: Context): void {
       sendMessage?: (
         message: { customType: string; content: string; display?: boolean; details?: Record<string, unknown> },
         opts?: { deliverAs?: string; triggerTurn?: boolean },
-      ) => Promise<void>;
+      ) => void;
     };
     let todoReminders = 0;
     let lastAssistantStopReason: string | null = null;
@@ -233,24 +211,18 @@ export default function todoPlugin(ctx: Context): void {
     }
     state.cancelReminder = cancelTodoReminder;
     scoped.on('turn_end', async (event: unknown) => {
-      if (event === null || typeof event !== 'object' || !('message' in event)) return;
-      const msg = (event as { message: unknown }).message;
+      const msg = (event as { message?: unknown } | null | undefined)?.message;
       if (msg === null || typeof msg !== 'object') return;
       const { role, stopReason } = msg as { role?: unknown; stopReason?: unknown };
-      if (role === 'assistant' && typeof stopReason === 'string') {
-        lastAssistantStopReason = stopReason;
-      }
+      if (role === 'assistant' && typeof stopReason === 'string') lastAssistantStopReason = stopReason;
     });
-    scoped.on('agent_start', () => cancelTodoReminder());
-    scoped.on('session_shutdown', () => cancelTodoReminder());
+    for (const ev of ['agent_start', 'session_shutdown']) scoped.on(ev, () => cancelTodoReminder());
     scoped.on('agent_settled', async () => {
       cancelTodoReminder();
-      const inFlight = stopReminder.isCompactionInFlight?.() ?? false;
-      const intentional = stopReminder.isIntentionalAbort?.() ?? false;
       const plan = planStopTodoReminder({
         lastStopReason: lastAssistantStopReason,
-        intentionalAbort: intentional,
-        compactionInFlight: inFlight,
+        intentionalAbort: stopReminder.isIntentionalAbort?.() ?? false,
+        compactionInFlight: stopReminder.isCompactionInFlight?.() ?? false,
         reminders: todoReminders,
         runningSubs: stopReminder.getRunningSubs(),
         blockedDepth: stopReminder.getBlockedDepth(),
@@ -261,19 +233,20 @@ export default function todoPlugin(ctx: Context): void {
       todoReminderTimer = setTimeout(() => {
         todoReminderTimer = null;
         if (stopReminder.isCompactionInFlight?.()) return;
-        void (async () => {
-          const send = pi.sendMessage;
-          if (typeof send !== 'function') return;
-          try {
-            await send(
-              { customType: TODO_REMINDER_CUSTOM_TYPE, content, display: true },
-              { deliverAs: 'followUp', triggerTurn: true },
-            );
-            todoReminders += 1;
-          } catch {
-            /* Delivery failure is non-fatal. */
-          }
-        })();
+        const send = pi.sendMessage;
+        if (typeof send !== 'function') return;
+        try {
+          // pi's sendMessage is fire-and-forget (it returns void), so the cap counter must advance
+          // synchronously: `send(...).then(...)` threw, got swallowed here, and every settle re-sent
+          // "Reminder 1/3" forever.
+          send(
+            { customType: TODO_REMINDER_CUSTOM_TYPE, content, display: true },
+            { deliverAs: 'followUp', triggerTurn: true },
+          );
+          todoReminders += 1;
+        } catch {
+          /* A synchronous send failure must not escape the timer callback. */
+        }
       }, todoReminderGraceMs());
       todoReminderTimer.unref?.();
     });
@@ -292,13 +265,10 @@ export default function todoPlugin(ctx: Context): void {
         Type.Object(
           {
             content: Type.String({ description: 'What the task is — a short imperative line' }),
-            status: Type.Union([
-              Type.Literal('pending'),
-              Type.Literal('in_progress'),
-              Type.Literal('completed'),
-              Type.Literal('blocked'),
-              Type.Literal('abandoned'),
-            ], { description: 'pending | in_progress | completed | blocked | abandoned' }),
+            status: Type.Union(
+              TODO_STATUSES.map((status) => Type.Literal(status)),
+              { description: TODO_STATUSES.join(' | ') },
+            ),
             blocker: Type.Optional(Type.String({ description: 'Only when status is "blocked": what it is waiting for. Omit the field entirely (never an empty string) for other statuses' })),
             phase: Type.Optional(Type.String({ description: 'Optional group name (≤30 chars); omit for a flat list (never an empty string)' })),
           },
@@ -315,10 +285,9 @@ export default function todoPlugin(ctx: Context): void {
         // A1: an invalid list is a hard failure — throw so pi flags isError for the model.
         return toolError(result.error ?? 'invalid todo list');
       }
-      const strictMode = todos.config.strict; // D75 phase 2 keeps policy in the service config.
       let next = result.items!;
       const strictNotes: string[] = [];
-      if (strictMode) {
+      if (todos.config.strict) {
         const strict = normalizeStrict(next);
         const demoted = next
           .filter((it, i) => it.status === 'in_progress' && strict[i]?.status === 'pending')
@@ -329,11 +298,10 @@ export default function todoPlugin(ctx: Context): void {
         if (promoted) strictNotes.push(`auto-promoted to in_progress: ${promoted}`);
         next = strict;
       }
-      // D35 avoids persistence and mirroring when the authoritative list is unchanged.
+      // D35: skip persistence and mirroring when the authoritative list is unchanged.
       if (listsEqual(todos.items, next)) {
         return { content: [{ type: 'text', text: 'No change: todo list already matches.' }], details: {} };
       }
-      // D36/D37 surface completion transitions and regressions to the caller.
       const completed = completionTransitions(todos.items, next);
       const reverted = revertedCompleted(todos.items, next);
       todos.replace(next, { source: 'tool' });
@@ -363,12 +331,11 @@ export default function todoPlugin(ctx: Context): void {
     description: 'Show the todo list, or edit it: /todos done|drop|rm|unblock <fuzzy content match>',
     handler: async (args: unknown, eventCtx: unknown) => {
       const ui = (eventCtx as { ui?: { notify?: (text: string, level?: string) => void } }).ui;
-      const ops = ['done', 'drop', 'rm', 'unblock'] as const;
       const raw = typeof args === 'string'
         ? args.split(/\s+/).filter(Boolean)
         : Array.isArray(args) ? args.map(String) : [];
       const opArg = raw[0];
-      if (opArg && (ops as readonly string[]).includes(opArg)) {
+      if (opArg && Object.hasOwn(OP_VERBS, opArg)) {
         const query = raw.slice(1).join(' ').trim();
         if (!query) {
           ui?.notify?.('usage: /todos done|drop|rm|unblock <content>', 'warning');
@@ -384,14 +351,14 @@ export default function todoPlugin(ctx: Context): void {
           return;
         }
         const content = candidates[0];
-        const edit = { op: opArg as 'done' | 'drop' | 'rm' | 'unblock', content };
+        const edit = { op: opArg as TodoEditOp, content };
         const before = todos.items;
         todos.applyEdits([edit], { source: 'human' });
         if (listsEqual(before, todos.items)) {
           ui?.notify?.(`no change: "${content}" is already in that state`, 'info');
           return;
         }
-        // D38 persists human edits so branch replay rebuilds the same authoritative state.
+        // D38: persist human edits so branch replay rebuilds the same authoritative state.
         try {
           appendEntry(TODO_EDIT_CUSTOM_TYPE, { version: 1, edits: [edit], ts: Date.now() });
         } catch {
@@ -399,14 +366,9 @@ export default function todoPlugin(ctx: Context): void {
         }
         mirrorTodos();
         renderWidget(eventCtx);
-        const verb = opArg === 'done' ? 'completed'
-          : opArg === 'drop' ? 'abandoned'
-          : opArg === 'unblock' ? 'unblocked (back to pending)'
-          : 'removed';
-        ui?.notify?.(`"${content}" ${verb}`, 'info');
+        ui?.notify?.(`"${content}" ${OP_VERBS[edit.op]}`, 'info');
         return;
       }
-      // /todos is the unbounded view because the widget intentionally prioritizes active context.
       const body = renderTodoGroups(todos.items);
       if (body.length === 0) {
         ui?.notify?.('todo list is empty', 'info');
@@ -419,4 +381,3 @@ export default function todoPlugin(ctx: Context): void {
     },
   });
 }
-

package/src/progress-core.ts

@@ -1,41 +1,27 @@
 /**
- * M16 pure core for progress visibility (development plan §M16; prioritize conservative output, with no new D3 protocol).
- *
- * Channels in the post-M22 world:
- *  - Progress badge (N/M plus optional ETA) is embedded in the pane title (state_labels has only five keys, so it cannot fit there);
- *  - Tool badge (🔧 tool) is sent through report_agent.message;
- *  - Rate estimates follow kimi estimator semantics: rate window, unfinished cap, and confidence gate.
- *
- * Conservative principle (risk ⑥ decision): when an estimate is not trustworthy, fall back to plain `N/M` and
- * never display a misleading ETA.
+ * M16 progress visibility: conservative output only, no new D3 protocol. The progress badge
+ * (N/M plus optional ETA) rides in the pane title, the tool badge (🔧 tool) goes through
+ * report_agent.message, and an untrustworthy estimate falls back to plain `N/M` — never a
+ * misleading ETA.
  */
 
 import { countTodos, type TodoItem } from './vocab.ts';
 
 /** Minimum completed points needed for an ETA (<2 cannot establish a rate). */
 export const ETA_MIN_SAMPLES = 2;
-/** Rate sample window (kimi rate-window semantics; use the most recent K completion points). */
-export const RATE_WINDOW_MS = 45_000;
-/** Cap for displayed unfinished progress (kimi unfinished-cap semantics; prevent a false "almost done" impression). */
-export const UNFINISHED_CAP = 0.85;
-/** Completion freshness gate: if the most recent completion is older than this, data is stale and no ETA is estimated. */
+/** An older latest completion means the data is stale and no ETA is estimated. */
 export const PROGRESS_STALE_MS = 5 * 60_000;
-/** Number of recent completion points used for rate fitting. */
 const RATE_SAMPLE_POINTS = 5;
 
 export interface EtaEstimate {
-  /** Remaining steps. */
   remaining: number;
-  /** Estimated remaining time (milliseconds). */
   etaMs: number;
   confidence: 'ok';
 }
 
 /**
- * Estimate ETA from completion timestamps and remaining steps.
- *  - Fewer than 2 completion points → null (no rate can be inferred);
- *  - Most recent completion older than PROGRESS_STALE_MS → null (stale after a burst followed by a pause or manual hold);
- *  - Rate = use the latest K(≤5) points, (k-1) / (t_k - t_1); eta = remaining / rate.
+ * Fewer than 2 points, or a stale latest point, → null.
+ * Rate = latest K(≤5) points, (k-1) / (t_k - t_1); eta = remaining / rate.
  */
 export function estimateEta(opts: {
   completedAt: readonly number[];
@@ -54,11 +40,10 @@ export function estimateEta(opts: {
   const span = sample[sample.length - 1] - sample[0];
   const steps = sample.length - 1;
   if (steps < 1 || span <= 0) return null;
-  const ratePerMs = steps / span;
-  return { remaining, etaMs: Math.round(remaining / ratePerMs), confidence: 'ok' };
+  return { remaining, etaMs: Math.round(remaining / (steps / span)), confidence: 'ok' };
 }
 
-/** Title progress suffix: conservative `3/7`; trusted ETA gives `3/7 ~4m`; total=0 → empty; all complete → `5/5 ✓`. */
+/** Title suffix: `3/7`; trusted ETA gives `3/7 ~4m`; total=0 → empty; all complete → `5/5 ✓`. */
 export function formatProgressSuffix(opts: {
   completed: number;
   total: number;
@@ -68,44 +53,22 @@ export function formatProgressSuffix(opts: {
   if (total <= 0) return '';
   const base = completed >= total ? `${completed}/${total} ✓` : `${completed}/${total}`;
   if (!eta || eta.etaMs <= 0) return base;
-  const human = eta.etaMs < 60_000 ? '<1m'
-    : (() => {
-      const mins = Math.ceil(eta.etaMs / 60_000);
-      return mins < 60 ? `~${mins}m` : `~${Math.round((mins / 60) * 10) / 10}h`;
-    })();
+  const human = eta.etaMs < 60_000 ? '<1m' : (() => {
+    const mins = Math.ceil(eta.etaMs / 60_000);
+    return mins < 60 ? `~${mins}m` : `~${Math.round((mins / 60) * 10) / 10}h`;
+  })();
   return `${base} ${human}`;
 }
 
-/** Tool badge (report_agent.message): one tool name; multiple use the first plus a count; empty → null (do not overwrite). */
+/** Tool badge for report_agent.message: one name, or the first plus a count; empty → null (do not overwrite). */
 export function planToolBadge(runningToolNames: readonly string[]): string | null {
   if (runningToolNames.length === 0) return null;
   const first = runningToolNames[0];
   return runningToolNames.length === 1 ? `🔧 ${first}` : `🔧 ${first} +${runningToolNames.length - 1}`;
 }
 
-/** Derive progress input from a list (completed count / total open-work count). */
+/** Completed count over all tracked work (abandoned excluded). */
 export function progressOf(items: readonly TodoItem[]): { completed: number; total: number } {
   const c = countTodos(items);
-  const blockedCount = items.filter((it) => it.status === 'blocked').length;
-  return { completed: c.completed, total: c.completed + c.pending + c.inProgress + blockedCount };
-}
-
-/** Hide the progress badge after it has been marked for the full lifecycle (avoid persistent completed-state noise; callers compare this). */
-export const PROGRESS_HIDE_MS = 60_000;
-
-/**
- * Count completed transitions between two lists (match by content; an item completed in the new list whose old status
- * was not completed, including items newly added as completed). M16 ETA estimation uses this as input: every edit path
- * (todo_write / human edit / M17 reconciliation) passes through TodosService, so the diff is centralized here.
- */
-export function countCompletedTransitions(
-  before: readonly TodoItem[],
-  after: readonly TodoItem[],
-): number {
-  const oldStatus = new Map(before.map((it) => [it.content, it.status]));
-  let n = 0;
-  for (const it of after) {
-    if (it.status === 'completed' && oldStatus.get(it.content) !== 'completed') n += 1;
-  }
-  return n;
+  return { completed: c.completed, total: c.completed + c.pending + c.inProgress + c.blocked };
 }

package/src/reconcile-core.ts

@@ -1,35 +1,31 @@
 /**
- * M17: pure planner for automatic todo↔subagent reconciliation (development plan §M17; P2 = do not check off low-confidence matches, only prompt).
+ * Pure planner for automatic todo↔subagent reconciliation, run after a settlement push and before
+ * the followUp is injected.
  *
- * Timing (adapter): after the controller receives a settlement push (pollLoop / pipe reply), before injecting followUp.
- * Semantics (aligned with omp reconcileTodosWithSubagents):
- *  - Match description ↔ todo.content: normalize (lowercase + collapse whitespace), then exact → bidirectional prefix
- *    → substring, in the same family as D38 fuzzyFind;
- *  - Auto-complete only when settled and the unique best tier is in {exact, prefix}; at most one item per settlement;
- *  - Unblock blocked items whose blocker ↔ description matches at any tier (exact/prefix)
- *    (multiple allowed; failed/low-confidence matches do not unblock);
- *  - Low confidence/ambiguity/failure: leave the list unchanged and add a noteLines prompt to the settlement notice (P2 decision);
- *  - Persistence: edits use the D38 authoritative path (pi-herdr.todo-edit custom entry, effective during branch replay).
+ * Match description ↔ todo.content after normalize (lowercase + collapse whitespace) at tiers
+ * exact → prefix → substring, the same family as D38 fuzzyFind.
+ *  - Auto-complete only a settled subagent's unique best candidate at exact/prefix, at most one item;
+ *  - Unblock blocked items whose blocker matches at any tier (blockers are phrases like "waiting for
+ *    X to finish", so substring matters and a soft return to pending is safe);
+ *  - Low confidence / ambiguity / failure leaves the list untouched and adds a prompt line (never
+ *    check off a guess);
+ *  - Edits persist through the authoritative pi-herdr.todo-edit path, so branch replay reproduces them.
  */
 
 import { applyTodoEdits, type TodoEdit, type TodoItem } from './todo-core.ts';
 
-export type ReconcileOutcome = 'settled' | 'failed';
-export type MatchTier = 'exact' | 'prefix' | 'substring' | null;
-export interface ReconcilePlan {
-  /** List after applying edits (original reference when there are no edits). */
+type ReconcileOutcome = 'settled' | 'failed';
+type MatchTier = 'exact' | 'prefix' | 'substring' | null;
+interface ReconcilePlan {
   items: TodoItem[];
   /** Edits persisted through the authoritative path (at most one done plus any unblocks). */
   edits: TodoEdit[];
   /** Item automatically checked off (at most one). */
   completed: TodoItem | null;
-  /** Best matching tier for auto-completion (null when there are no candidates). */
   tier: MatchTier;
-  /** Items unblocked by a blocker match. */
   unblocked: TodoItem[];
-  /** Prompt lines injected into the settlement notice (aligned with D36 feedback tone; empty when none). */
   noteLines: string[];
-  /** Match-rate metric (P2: collected with the settlement notice in session JSONL). */
+  /** Match-rate metric, collected with the settlement notice in session JSONL. */
   metric: {
     description: string;
     outcome: ReconcileOutcome;
@@ -64,9 +60,9 @@ export function reconcileTodos(
   const edits: TodoEdit[] = [];
   const noteLines: string[] = [];
 
-  // 1) Check-off candidates: pending / in_progress (completed/abandoned never participate).
-  const matchable = prev.filter((t) => t.status === 'pending' || t.status === 'in_progress');
-  const scored = matchable
+  // Check-off candidates: completed/abandoned never participate.
+  const scored = prev
+    .filter((t) => t.status === 'pending' || t.status === 'in_progress')
     .map((t) => ({ item: t, tier: matchTier(description, t.content) }))
     .filter((c): c is { item: TodoItem; tier: Exclude<MatchTier, null> } => c.tier !== null)
     .sort((a, b) => TIER_ORDER[a.tier] - TIER_ORDER[b.tier]);
@@ -80,35 +76,30 @@ export function reconcileTodos(
       edits.push({ op: 'done', content: completed.content });
       noteLines.push(`Reconciled: completed "${completed.content}" (${bestTier} match with subagent description).`);
     } else if (best.length > 1) {
-      // Ambiguous match: list candidates and leave the decision to a person.
       noteLines.push(
         `Todo match ambiguous between: ${best.map((c) => `"${c.item.content}"`).join(', ')} — update todo_write yourself.`,
       );
-    } else if (outcome === 'failed') {
-      // High-confidence candidate, but the subagent did not settle successfully: keep it open and prompt.
+    } else {
+      // High-confidence candidate, but the subagent did not settle successfully: keep it open.
       for (const c of best) {
         noteLines.push(`Todo kept open: "${c.item.content}" (subagent did not settle successfully).`);
       }
     }
   } else if (bestTier === 'substring') {
-    // Low-confidence match (P2): do not check it off; prompt with the candidate.
     for (const c of best) {
       noteLines.push(`Todo not auto-completed (low-confidence match): "${c.item.content}" — update todo_write if this work is done.`);
     }
   }
 
-  // 2) Unblock on any blocker match, including substring—real blockers are phrases such as "waiting for X to finish",
-  //    so the description may be embedded in the middle and prefix would miss it. The low-confidence gate applies only
-  //    to check-offs; returning an unblocked item to pending is a soft operation. Only settled subagents can unblock (possibly multiple).
+  // Unblocking is a soft operation, so any tier counts; only a settled subagent can unblock.
   const unblocked: TodoItem[] = [];
   if (outcome === 'settled') {
     for (const t of prev) {
       if (t.status !== 'blocked' || typeof t.blocker !== 'string') continue;
-      if (matchTier(description, t.blocker) !== null) {
-        unblocked.push(t);
-        edits.push({ op: 'unblock', content: t.content });
-        noteLines.push(`Unblocked "${t.content}" (was waiting on: ${t.blocker}).`);
-      }
+      if (matchTier(description, t.blocker) === null) continue;
+      unblocked.push(t);
+      edits.push({ op: 'unblock', content: t.content });
+      noteLines.push(`Unblocked "${t.content}" (was waiting on: ${t.blocker}).`);
     }
   }