pi-pier 0.3.0 → 0.4.1

package/src/todo-core.ts

@@ -1,24 +1,14 @@
-/** Why: Preserve the established compatibility and safety behavior (D34–D43, M10). */
-import {
-  TODO_DETAILS_KEY,
-  TODO_STATUSES,
-  TODO_TOOL_NAME,
-  type TodoCounts,
-  type TodoItem,
-  type TodoSnapshot,
-  type TodoStatus,
-} from './vocab.ts';
-import { countTodos } from './vocab.ts';
+/** Pure todo-list core: validation, diffing, edit and branch-replay folding (D34–D43, M10). */
+import { TODO_DETAILS_KEY, TODO_STATUSES, TODO_TOOL_NAME, type TodoItem, type TodoSnapshot, type TodoStatus } from './vocab.ts';
 
-export type { TodoItem, TodoSnapshot, TodoStatus, TodoCounts };
+export type { TodoItem, TodoSnapshot, TodoStatus };
 
-/** Why: Preserve the established compatibility and safety behavior (D43). */
-export const PHASE_MAX_LEN = 30;
+/** D43 phase label cap, mirrored by the todo_write tool description. */
+const PHASE_MAX_LEN = 30;
 
-/** Why: Preserve the established compatibility and safety behavior (D38). */
+/** Session entry type for human/automated edits, replayed during branch rebuild (D38). */
 export const TODO_EDIT_CUSTOM_TYPE = 'pi-herdr.todo-edit';
 
-/** Why: Preserve the established compatibility and safety behavior (D38, M17). */
 export type TodoEditOp = 'done' | 'drop' | 'rm' | 'unblock';
 
 export interface TodoEdit {
@@ -38,28 +28,20 @@ export interface TodoValidationResult {
   error?: string;
 }
 
-/** Why: Preserve the established compatibility and safety behavior (B2, D34, D43). */
 export function validateTodos(
   todos: unknown,
   allowParallelInProgress = true,
 ): TodoValidationResult {
-  if (!Array.isArray(todos)) {
-    return { ok: false, error: 'invalid todos: `todos` must be an array' };
-  }
+  if (!Array.isArray(todos)) return { ok: false, error: 'invalid todos: `todos` must be an array' };
   const seen = new Set<string>();
   let inProgress = 0;
   const items: TodoItem[] = [];
   for (const raw of todos) {
-    if (typeof raw !== 'object' || raw === null) {
-      return { ok: false, error: 'invalid todos: each todo must be an object' };
-    }
+    if (typeof raw !== 'object' || raw === null) return { ok: false, error: 'invalid todos: each todo must be an object' };
     const entry = raw as Record<string, unknown>;
-    const allowed = ['content', 'status', 'blocker', 'phase'];
-    const keys = Object.keys(entry);
-    for (const k of keys) {
-      if (!allowed.includes(k)) {
-        return { ok: false, error: `invalid todos: unknown field "${k}" (allowed: content, status, blocker, phase)` };
-      }
+    const unknownField = Object.keys(entry).find((k) => !['content', 'status', 'blocker', 'phase'].includes(k));
+    if (unknownField) {
+      return { ok: false, error: `invalid todos: unknown field "${unknownField}" (allowed: content, status, blocker, phase)` };
     }
     if (!('content' in entry) || !('status' in entry)) {
       return { ok: false, error: 'invalid todos: each todo must have `content` and `status`' };
@@ -68,20 +50,17 @@ export function validateTodos(
     if (typeof content !== 'string' || content.trim() === '') {
       return { ok: false, error: 'invalid todo: `content` must be a non-empty string' };
     }
-    if (seen.has(content)) {
-      return { ok: false, error: `invalid todos: duplicate content "${content}"` };
-    }
+    if (seen.has(content)) return { ok: false, error: `invalid todos: duplicate content "${content}"` };
     seen.add(content);
     const status = entry.status;
     if (typeof status !== 'string' || !(TODO_STATUSES as readonly string[]).includes(status)) {
       return { ok: false, error: `invalid todo: \`status\` must be one of ${TODO_STATUSES.join('|')}` };
     }
     const item: TodoItem = { content, status: status as TodoStatus };
+    // blocker/phase tolerate empty-string filler (models fill optional fields with ''), but a
+    // malformed type is a hard reject: it would hide intent.
     if ('blocker' in entry) {
       const blocker = entry.blocker;
-      // Why: Preserve the established compatibility and safety behavior.
-      // Why: Preserve the established compatibility and safety behavior.
-      // Why: Preserve the established compatibility and safety behavior.
       if (blocker != null && typeof blocker !== 'string') {
         return { ok: false, error: 'invalid todo: `blocker` must be a non-empty string' };
       }
@@ -94,41 +73,30 @@ export function validateTodos(
     }
     if ('phase' in entry) {
       const phase = entry.phase;
-      if (phase != null && typeof phase !== 'string') {
-        return { ok: false, error: `invalid todo: \`phase\` must be a non-empty string ≤ ${PHASE_MAX_LEN} chars` };
-      }
-      // Why: Preserve the established compatibility and safety behavior.
+      const phaseError = { ok: false, error: `invalid todo: \`phase\` must be a non-empty string ≤ ${PHASE_MAX_LEN} chars` };
+      if (phase != null && typeof phase !== 'string') return phaseError;
       if (typeof phase === 'string') {
-        if (phase.length > PHASE_MAX_LEN) {
-          return { ok: false, error: `invalid todo: \`phase\` must be a non-empty string ≤ ${PHASE_MAX_LEN} chars` };
-        }
+        if (phase.length > PHASE_MAX_LEN) return phaseError;
         if (phase.trim() !== '') item.phase = phase;
       }
     }
-    if (status === 'in_progress') {
-      inProgress++;
-      if (!allowParallelInProgress && inProgress > 1) {
-        return {
-          ok: false,
-          error: `invalid todos: at most one task may be in_progress (got ${inProgress})`,
-        };
-      }
+    if (status === 'in_progress' && ++inProgress > 1 && !allowParallelInProgress) {
+      return { ok: false, error: `invalid todos: at most one task may be in_progress (got ${inProgress})` };
     }
     items.push(item);
   }
   return { ok: true, items };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D42). */
+/** Keep exactly one in_progress item, promoting the first pending one when none exists (D42). */
 export function normalizeStrict(items: readonly TodoItem[]): TodoItem[] {
   if (items.length === 0) return [];
   const out = items.map((it) => ({ ...it }));
   let kept = false;
   for (const it of out) {
-    if (it.status === 'in_progress') {
-      if (kept) it.status = 'pending';
-      else kept = true;
-    }
+    if (it.status !== 'in_progress') continue;
+    if (kept) it.status = 'pending';
+    else kept = true;
   }
   if (!kept) {
     const firstPending = out.find((it) => it.status === 'pending');
@@ -137,7 +105,6 @@ export function normalizeStrict(items: readonly TodoItem[]): TodoItem[] {
   return out;
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D35). */
 export function listsEqual(a: readonly TodoItem[], b: readonly TodoItem[]): boolean {
   if (a.length !== b.length) return false;
   for (let i = 0; i < a.length; i++) {
@@ -148,38 +115,34 @@ export function listsEqual(a: readonly TodoItem[], b: readonly TodoItem[]): bool
   return true;
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D36). */
+/** Items completed by this write (D36: surfaced back to the caller). */
 export function completionTransitions(prev: readonly TodoItem[], next: readonly TodoItem[]): string[] {
   const prevMap = new Map(prev.map((it) => [it.content, it.status]));
-  const out: string[] = [];
-  for (const it of next) {
-    if (it.status === 'completed' && prevMap.get(it.content) !== 'completed') out.push(it.content);
-  }
-  return out;
+  return next
+    .filter((it) => it.status === 'completed' && prevMap.get(it.content) !== 'completed')
+    .map((it) => it.content);
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D37). */
+/** Completed items pushed back to open by this write (D37: reversible, but warn). */
 export function revertedCompleted(prev: readonly TodoItem[], next: readonly TodoItem[]): string[] {
   const nextMap = new Map(next.map((it) => [it.content, it.status]));
-  const out: string[] = [];
-  for (const it of prev) {
-    if (it.status !== 'completed') continue;
-    const now = nextMap.get(it.content);
-    if (now === 'pending' || now === 'in_progress') out.push(it.content);
-  }
-  return out;
+  return prev
+    .filter((it) => {
+      if (it.status !== 'completed') return false;
+      const now = nextMap.get(it.content);
+      return now === 'pending' || now === 'in_progress';
+    })
+    .map((it) => it.content);
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export function makeSnapshot(items: readonly TodoItem[]): TodoSnapshot {
   // Copy: the snapshot is persisted, the service list stays owned by TodosService.
   return { version: 1, items: [...items] };
 }
 
-export interface BranchEntryLike {
-  /** Why: Preserve the established compatibility and safety behavior. */
+/** Loose shape of pi session JSONL entries we fold over; only the fields we read. */
+interface BranchEntryLike {
   type?: string;
-  /** Why: Preserve the established compatibility and safety behavior. */
   timestamp?: unknown;
   message?: {
     role?: string;
@@ -190,33 +153,31 @@ export interface BranchEntryLike {
   data?: unknown;
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D37, D38, M17). */
+/** Edit semantics (D37/D38): done/drop keep completed|abandoned terminal; unblock returns blocked to pending. */
 export function applyTodoEdits(items: readonly TodoItem[], edits: readonly TodoEdit[]): TodoItem[] {
   let out = items.map((it) => ({ ...it }));
   for (const edit of edits) {
+    if (edit.op === 'rm') {
+      out = out.filter((it) => it.content !== edit.content);
+      continue;
+    }
     const target = out.find((it) => it.content === edit.content);
     if (!target) continue;
     switch (edit.op) {
       case 'done':
-        if (target.status !== 'completed') {
-          target.status = 'completed';
-          delete target.blocker;
-        }
+        if (target.status === 'completed') break;
+        target.status = 'completed';
+        delete target.blocker;
         break;
       case 'drop':
-        if (target.status !== 'completed' && target.status !== 'abandoned') {
-          target.status = 'abandoned';
-          delete target.blocker;
-        }
-        break;
-      case 'rm':
-        out = out.filter((it) => it.content !== edit.content);
+        if (target.status === 'completed' || target.status === 'abandoned') break;
+        target.status = 'abandoned';
+        delete target.blocker;
         break;
       case 'unblock':
-        if (target.status === 'blocked') {
-          target.status = 'pending';
-          delete target.blocker;
-        }
+        if (target.status !== 'blocked') break;
+        target.status = 'pending';
+        delete target.blocker;
         break;
     }
   }
@@ -241,10 +202,9 @@ function extractEditPayload(data: unknown): TodoEditPayload | null {
   return { version: 1, edits, ts: typeof raw.ts === 'number' ? raw.ts : 0 };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D38). */
 export interface FoldedTodos {
   items: TodoItem[];
-  /** Why: Preserve the established compatibility and safety behavior. */
+  /** Timestamp of the last write that shaped these items; null when the entry carried none. */
   writtenAt: number | null;
 }
 
@@ -258,7 +218,7 @@ function entryTimestamp(entry: BranchEntryLike): number | null {
   return null;
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D38). */
+/** Fold the branch to the authoritative list: last todo snapshot, then interleaved edits (D38). */
 export function foldLatestTodosMeta(entries: readonly BranchEntryLike[]): FoldedTodos | null {
   let found: TodoItem[] | null = null;
   let writtenAt: number | null = null;
@@ -283,12 +243,7 @@ export function foldLatestTodosMeta(entries: readonly BranchEntryLike[]): Folded
   return found ? { items: found, writtenAt } : null;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-export function foldLatestTodos(entries: readonly BranchEntryLike[]): TodoItem[] | null {
-  return foldLatestTodosMeta(entries)?.items ?? null;
-}
-
-export function extractSnapshotFromDetails(details: unknown): TodoSnapshot | null {
+function extractSnapshotFromDetails(details: unknown): TodoSnapshot | null {
   if (typeof details !== 'object' || details === null) return null;
   const raw = (details as Record<string, unknown>)[TODO_DETAILS_KEY];
   if (typeof raw !== 'object' || raw === null) return null;
@@ -297,7 +252,7 @@ export function extractSnapshotFromDetails(details: unknown): TodoSnapshot | nul
   return { version: 1, items: snap.items as TodoItem[] };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D38). */
+/** Exact match, then unique prefix, then substring candidates (D38 `/todos <verb> <query>`). */
 export function fuzzyFind(items: readonly TodoItem[], query: string): string[] {
   const q = query.trim();
   if (!q) return [];
@@ -306,26 +261,22 @@ export function fuzzyFind(items: readonly TodoItem[], query: string): string[] {
   const prefix = items.filter((it) => it.content.startsWith(q));
   if (prefix.length === 1) return [prefix[0].content];
   if (prefix.length > 1) return prefix.map((it) => it.content);
-  const substr = items.filter((it) => it.content.includes(q));
-  return substr.map((it) => it.content);
+  return items.filter((it) => it.content.includes(q)).map((it) => it.content);
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D39). */
 export interface BoundedView {
   visible: TodoItem[];
-  /** Why: Preserve the established compatibility and safety behavior. */
   hiddenCompleted: number;
   hiddenOpen: number;
 }
 
+/** Keep the newest open items, then fill leftover budget with the newest completions (D39). */
 export function boundedView(items: readonly TodoItem[], budget: number): BoundedView {
   if (items.length <= budget) {
     return { visible: items.map((it) => ({ ...it })), hiddenCompleted: 0, hiddenOpen: 0 };
   }
   const completed = items.filter((it) => it.status === 'completed');
   const open = items.filter((it) => it.status !== 'completed');
-  // Why: Preserve the established compatibility and safety behavior.
-  // Why: Preserve the established compatibility and safety behavior.
   const visible = open.length > budget ? open.slice(-budget) : open;
   const hiddenOpen = open.length - visible.length;
   let hiddenCompleted = completed.length;
@@ -338,9 +289,6 @@ export function boundedView(items: readonly TodoItem[], budget: number): Bounded
   return { visible: final, hiddenCompleted, hiddenOpen };
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export function currentActivity(items: readonly TodoItem[]): string | null {
   return items.find((it) => it.status === 'in_progress')?.content ?? null;
 }
-
-export { countTodos };

package/src/todo-read-hook.ts

@@ -1,32 +1,55 @@
 /**
- * D69: Plan the todo read hook (before_agent_start + display:false).
- * Stale-core prevents a fully completed list from being recited forever:
- *  - stale (turn-based) → warn with old entries for rewriting, rate-limited and capped;
- *  - archived (wall-clock based) → treat it as absent, sharing the guard cadence with empty lists.
+ * Plan the todo read hook (before_agent_start + display:false). Stale-core keeps a fully completed list
+ * from being recited forever: stale (turn-based) warns with the old entries as rewrite references,
+ * rate-limited and capped; archived (wall-clock) treats the list as absent, sharing the guard cadence
+ * with empty lists.
  */
 import { boundedView, currentActivity, type TodoItem } from './todo-core.ts';
 import { countTodos } from './vocab.ts';
 import { STALE_NOTICE_MAX, evaluateStaleness, formatAge } from './stale-core.ts';
+import { todoMark } from './todo-window.ts';
 
-/** Share one injection cadence across empty-list guards, stale warnings, and archive notices. */
-export const EMPTY_GUARD_EVERY_N = 4;
-export const TODO_READ_CUSTOM_TYPE = 'pi-herdr.todo-read';
+/** Cadence shared by empty-list guards, stale warnings, and archive notices. */
+const EMPTY_GUARD_EVERY_N = 4;
+const TODO_READ_CUSTOM_TYPE = 'pi-herdr.todo-read';
 
-export type TodoReadEffect =
+/**
+ * pi 1.2 fires `before_agent_start` for runs started by `sendMessage(..., { triggerTurn: true })`
+ * too. The todo hook wants the plan in every *user* run and after a compaction continuation (the
+ * model needs the plan to resume), but not in its own stop reminder or the config guide: those
+ * already carry their own text, and counting them as turns would advance the guard cadence.
+ * Keep this list in sync with COMPACTION_CONTINUE_TYPE in compact-coordinator.ts.
+ */
+export const TODO_READ_CUSTOM_TYPES: readonly string[] = ['pi-herdr.compaction-continue'];
+
+/** Whether this run should receive the todo read hook. Missing `messageType` is pi < 1.2, where
+ *  only user runs fired `before_agent_start`; treat it as a user run for compatibility. */
+export function shouldRunTodoRead(event: unknown): boolean {
+  if (event === null || typeof event !== 'object' || !('messageType' in event)) return true;
+  const messageType = (event as { messageType?: unknown }).messageType;
+  if (messageType === 'user') return true;
+  if (messageType !== 'custom') return false;
+  const message = (event as { message?: unknown }).message;
+  const customType = message !== null && typeof message === 'object' && 'customType' in message
+    ? (message as { customType?: unknown }).customType
+    : undefined;
+  return typeof customType === 'string' && TODO_READ_CUSTOM_TYPES.includes(customType);
+}
+
+type TodoReadEffect =
   | 'recite' // Recite normally while the list is fresh.
   | 'empty-guard' // Guard against an empty list.
-  | 'stale-notice' // A: warn when the list is stale by turns.
-  | 'archive-notice' // B: notify when the list is archived by wall-clock age.
+  | 'stale-notice' // Warn when the list is stale by turns, or when archiving is one window away.
+  | 'archive-notice' // Notify once the list is archived by wall-clock age.
   | 'none'; // Skip because of rate limits or caps.
 
-export interface TodoReadPlan {
+interface TodoReadPlan {
   inject: boolean;
   effect: TodoReadEffect;
   /** Current archive state, independent of injection, so callers can refresh widget/title projections. */
   archived: boolean;
-  /** R1: Clear the in-memory list when injecting the archive notice; callers persist the empty JSONL
-   * so a dead list cannot block the before-stopping empty guard (01a03c0d observed 2h of untracked
-   * multi-step work after archiving). */
+  /** Clear the in-memory list when injecting the archive notice (the caller persists the empty JSONL);
+   * a kept dead list would suppress the empty guard that resumes tracking after an idle gap. */
   clearArchived: boolean;
   message: {
     customType: string;
@@ -35,24 +58,14 @@ export interface TodoReadPlan {
   };
 }
 
-const MARKS: Record<TodoItem['status'], string> = {
-  pending: '○',
-  in_progress: '▶',
-  completed: '✓',
-  blocked: '■',
-  abandoned: '✗',
-};
-
 export function planTodoReadHook(opts: {
   items: readonly TodoItem[];
   turn: number;
   lastEmptyGuardTurn: number | null;
   /** stale-core clock anchor (TodosService.lastWriteAt). */
   lastWriteAt: number | null;
-  /** Turns since the last todo write, when known in this process. */
   turnsSinceWrite: number | null;
   now: number;
-  /** Number of stale warnings injected during the current idle period. */
   staleNotices: number;
   lastStaleGuardTurn: number | null;
 }): TodoReadPlan {
@@ -86,16 +99,12 @@ export function planTodoReadHook(opts: {
   });
 
   if (st.kind === 'archived') {
-    const c = countTodos(opts.items as TodoItem[]);
+    const c = countTodos(opts.items);
     const age = st.ageMs == null ? '' : ` ${formatAge(st.ageMs)} ago`;
-    // R2: Preserve one rewrite window with old entries as a reference before archiving.
-    // Idle periods do not consume turns, so the wall clock can reach one hour before a turns-based
-    // warning fires; 01a03c0d showed that the final notice then caused five todo_write calls to be ignored.
-    // B + R1/R3: The terminal notice no longer injects details and clears the list in the same
-    // injection; removing the [] escape hatch ensures multi-step work gets tracked while single-step
-    // Q&A remains explicitly allowed.
+    // Idle periods do not consume turns, so give one rewrite window with the old entries as reference
+    // before the terminal notice.
     if (opts.staleNotices === 0 && guardDue) {
-      const lines = opts.items.map((it) => `  ${MARKS[it.status]} ${it.content}`);
+      const lines = opts.items.map((it) => `  ${todoMark(it.status)} ${it.content}`);
       const head = `todos ✓${c.completed} (all completed, last updated${age}) — about to be archived`;
       const warn = 'One rewrite window before archiving: if the work you are doing now is multi-step, rewrite the full list with todo_write to track it (old entries below as reference — reuse what still applies). Single-step Q&A may skip tracking. If the list stays untouched, it will be archived and cleared on the next reminder.';
       return {
@@ -106,9 +115,8 @@ export function planTodoReadHook(opts: {
         message: msg([head, ...lines, warn].join('\n')),
       };
     }
-    // B + R1/R3: The terminal notice no longer injects details and clears the list in the same
-    // injection; removing the [] escape hatch ensures multi-step work gets tracked while single-step
-    // Q&A remains explicitly allowed.
+    // The terminal notice carries no details and no "skip tracking" escape hatch — multi-step work
+    // must get a fresh list, single-step Q&A may proceed untracked.
     return {
       inject: guardDue,
       effect: 'archive-notice',
@@ -123,16 +131,15 @@ export function planTodoReadHook(opts: {
   }
 
   if (st.kind === 'stale') {
-    // A: Turn recitation into a warning while retaining old entries as rewrite references; cap at STALE_NOTICE_MAX.
     const staleDue = opts.lastStaleGuardTurn == null
       || opts.turn - opts.lastStaleGuardTurn >= EMPTY_GUARD_EVERY_N;
     if (!staleDue || opts.staleNotices >= STALE_NOTICE_MAX) {
       return { inject: false, effect: 'none', archived: false, clearArchived: false, message: msg('') };
     }
-    const c = countTodos(opts.items as TodoItem[]);
+    const c = countTodos(opts.items);
     const head = `todos ▶${c.inProgress} ○${c.pending} ■${c.blocked} ✓${c.completed}`
       + ` · unchanged for ${opts.turnsSinceWrite} turns, nothing open`;
-    const lines = opts.items.map((it) => `  ${MARKS[it.status]} ${it.content}`);
+    const lines = opts.items.map((it) => `  ${todoMark(it.status)} ${it.content}`);
     const warn = 'This list no longer reflects the work you are doing. Rewrite the full list with todo_write to match current work, or send [] to clear it.';
     return {
       inject: true,
@@ -146,7 +153,7 @@ export function planTodoReadHook(opts: {
   // Fresh lists are recited every turn to keep current work visible.
   const c = countTodos(opts.items);
   const view = boundedView(opts.items, 6);
-  const lines = view.visible.map((it) => `${MARKS[it.status]} ${it.content}`);
+  const lines = view.visible.map((it) => `${todoMark(it.status)} ${it.content}`);
   const activity = currentActivity(opts.items);
   const head = `todos ▶${c.inProgress} ○${c.pending} ■${c.blocked} ✓${c.completed}`
     + (activity ? ` · ${activity}` : '');

package/src/todo-reminder-core.ts

@@ -1,90 +1,65 @@
 /**
- * Pure decision core for reminders about unfinished todos when stopping (D41 revision 2;
- * evidenced by session 01a040cc).
- *
- * Evidence: the model's closing prose said that pushing should be left to the user,
- * yet the todo list still contained `[pending] push to repository`. The old D41 injected
- * “Continue working on them before stopping” as a user-role message 116 ms after agent_settled;
- * that channel overrode the model's judgment from 20 seconds earlier, and git push ran within
- * 12 seconds without authorization.
- *
- * Revision 3 keeps the decision and wording here while the timing grace period is wired in
- * core/subagent:
- *  - use sendMessage(custom), not the user role, so the reminder source is identifiable rather than impersonating the user;
- *  - replace “keep working” with a reconciliation request, making human-blocked items a first-class
- *    outcome alongside continuing authorized work and deleting obsolete entries;
- *  - preserve the guard matrix: suppress on abort, cap reminders, and skip while a subagent is
- *    running, a human gate is blocked, or no open items remain.
+ * Reminders about unfinished todos when stopping go out as sendMessage(custom) and ask for
+ * reconciliation rather than continuation, so human-blocked items are a first-class outcome. Guards:
+ * suppress on abort, cap reminders, skip while a subagent runs, a human gate is blocked, or no open
+ * item remains.
  */
 import { ABORT_STOP_REASON } from './settle-wake-core.ts';
 import { pierOption } from './pier-options.ts';
 
-/** Cap reminders for the lifetime of the process, matching the previous behavior. */
-export const TODO_REMINDERS_MAX = 3;
+/** Cap reminders for the lifetime of the process. */
+const REMINDERS_MAX = 3;
 
-/** Custom message type for reminder injection (registerMessageRenderer can customize its TUI appearance). */
+/** Custom-type renderer hook so the TUI appearance can be customized. */
 export const TODO_REMINDER_CUSTOM_TYPE = 'pi-herdr.todo-reminder';
 
 /**
- * B3 grace window (milliseconds): delay from settled to injection, giving the user a chance to
- * read the closing answer and intervene; starting any agent during the window cancels it. This
- * follows the MACHINE_INJECT_GRACE_MS pattern; PI_HERDR_TODO_GRACE_MS is read per call so tests
- * can use a small value rather than freezing configuration at module load.
+ * Delay from settled to injection so the user can read the closing answer and intervene; starting
+ * any agent during the window cancels it. Read per call, not at module load, so tests can shrink it.
  */
 export function todoReminderGraceMs(): number {
-  // B10: canonical PIER_TODO_GRACE_MS, legacy PI_HERDR_TODO_GRACE_MS.
+  // Legacy PI_HERDR_TODO_GRACE_MS is accepted as a fallback by pierOption.
   return Number(pierOption('PIER_TODO_GRACE_MS') ?? 30_000) || 30_000;
 }
 
-export interface TodoReminderInput {
-  /** Stop reason of the last assistant turn before this settlement (null means treat it as natural completion). */
+interface TodoReminderInput {
+  /** Stop reason of the last assistant turn (null = natural completion). */
   lastStopReason: string | null;
-  /** True when abort was triggered intentionally by internal mechanisms like OCC. */
   intentionalAbort?: boolean;
-  /** True when compaction is currently in-flight. */
   compactionInFlight?: boolean;
-  /** Number of reminders already injected. */
   reminders: number;
-  /** Number of running background subagents; a positive value means the master is already waiting. */
+  /** Positive means the master is already waiting on a subagent. */
   runningSubs: number;
-  /** ask_user_question wait depth; a positive value means the master is waiting for a human response. */
+  /** ask_user_question wait depth; positive means the master waits on a human. */
   blockedDepth: number;
-  /** Current todo list. */
   items: ReadonlyArray<{ content: string; status: string }>;
 }
 
-export interface TodoReminderPlan {
-  /** Whether a reminder should be injected. */
+interface TodoReminderPlan {
   due: boolean;
-  /** Complete injected content, or null when due is false. */
   content: string | null;
-  /** New count after successful injection, or the original count when due is false. */
   nextReminders: number;
 }
 
-function noInject(reminders: number): TodoReminderPlan {
-  return { due: false, content: null, nextReminders: reminders };
-}
-
 /**
- * A stop reminder is due only when every guard passes and at least one open (pending/in_progress)
- * item exists. blocked, abandoned, and completed items are not unfinished: once human-waiting work
- * is modeled correctly, reminding again would only pressure the model to act without authorization
- * (the missing guard in the 01a040cc incident).
+ * Due only when every guard passes and at least one open (pending/in_progress) item exists.
+ * blocked/abandoned/completed are not unfinished: pressuring the model here would push it to act
+ * while it waits on a human.
  */
 export function planStopTodoReminder(input: TodoReminderInput): TodoReminderPlan {
-  if (input.intentionalAbort || input.compactionInFlight) return noInject(input.reminders);
-  if (input.lastStopReason === ABORT_STOP_REASON) return noInject(input.reminders);
-  if (input.reminders >= TODO_REMINDERS_MAX) return noInject(input.reminders);
-  if (input.runningSubs > 0) return noInject(input.reminders);
-  if (input.blockedDepth > 0) return noInject(input.reminders);
+  const noInject: TodoReminderPlan = { due: false, content: null, nextReminders: input.reminders };
+  if (input.intentionalAbort || input.compactionInFlight) return noInject;
+  if (input.lastStopReason === ABORT_STOP_REASON) return noInject;
+  if (input.reminders >= REMINDERS_MAX) return noInject;
+  if (input.runningSubs > 0) return noInject;
+  if (input.blockedDepth > 0) return noInject;
   const open = input.items.filter((it) => it.status === 'pending' || it.status === 'in_progress');
-  if (open.length === 0) return noInject(input.reminders);
+  if (open.length === 0) return noInject;
   const list = open
     .map((it) => (it.status === 'in_progress' ? `▶ ${it.content}` : `· ${it.content}`))
     .join('\n');
   const content = [
-    `<system-reminder>You stopped with unfinished todos (Reminder ${input.reminders + 1}/${TODO_REMINDERS_MAX}):`,
+    `<system-reminder>You stopped with unfinished todos (Reminder ${input.reminders + 1}/${REMINDERS_MAX}):`,
     list,
     'Reconcile the list instead of blindly continuing:',
     '- work that is yours AND already authorized by the user → continue it;',