pi-pier 0.2.7 → 0.3.0

package/src/todo-core.ts

@@ -171,8 +171,9 @@ export function revertedCompleted(prev: readonly TodoItem[], next: readonly Todo
 }
 
 /** Why: Preserve the established compatibility and safety behavior. */
-export function makeSnapshot(items: TodoItem[]): TodoSnapshot {
-  return { version: 1, items };
+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 {
@@ -263,7 +264,7 @@ export function foldLatestTodosMeta(entries: readonly BranchEntryLike[]): Folded
   let writtenAt: number | null = null;
   for (const entry of entries) {
     if (entry.type === 'message') {
-      const msg = entry.message;
+      const msg = entry.message as { role?: unknown; toolName?: unknown; details?: unknown } | null | undefined;
       if (typeof msg !== 'object' || msg === null) continue;
       if (msg.role !== 'toolResult' || msg.toolName !== TODO_TOOL_NAME) continue;
       const snapshot = extractSnapshotFromDetails(msg.details);
@@ -338,7 +339,7 @@ export function boundedView(items: readonly TodoItem[], budget: number): Bounded
 }
 
 /** Why: Preserve the established compatibility and safety behavior. */
-export function currentActivity(items: TodoItem[]): string | null {
+export function currentActivity(items: readonly TodoItem[]): string | null {
   return items.find((it) => it.status === 'in_progress')?.content ?? null;
 }
 

package/src/todo-reminder-core.ts

@@ -17,6 +17,7 @@
  *    running, a human gate is blocked, or no open items remain.
  */
 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;
@@ -31,12 +32,17 @@ export const TODO_REMINDER_CUSTOM_TYPE = 'pi-herdr.todo-reminder';
  * can use a small value rather than freezing configuration at module load.
  */
 export function todoReminderGraceMs(): number {
-  return Number(process.env.PI_HERDR_TODO_GRACE_MS ?? 30_000) || 30_000;
+  // B10: canonical PIER_TODO_GRACE_MS, legacy PI_HERDR_TODO_GRACE_MS.
+  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). */
   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. */
@@ -67,6 +73,7 @@ function noInject(reminders: number): TodoReminderPlan {
  * (the missing guard in the 01a040cc incident).
  */
 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);

package/src/todos-service.ts

@@ -15,6 +15,14 @@ export interface TodosConfig {
   allowParallelInProgress: boolean;
 }
 
+export type TodoCompletionSource = 'tool' | 'reconcile' | 'human' | 'archive';
+
+export interface TodoCompletedEvent {
+  count: number;
+  at: number;
+  source: TodoCompletionSource;
+}
+
 export class TodosService extends EventEmitter {
   private _items: TodoItem[] = [];
   /**
@@ -45,33 +53,37 @@ export class TodosService extends EventEmitter {
     return this._items.map((it) => ({ ...it }));
   }
 
-  replace(items: readonly TodoItem[]): { changed: boolean } {
+  replace(items: readonly TodoItem[], opts?: { source?: TodoCompletionSource }): { changed: boolean } {
     const next = items.map((it) => ({ ...it }));
     if (listsEqual(this._items, next)) return { changed: false };
     const before = this._items;
     this._items = next;
     this.lastWriteAt = Date.now();
-    this.emitCompletedTransitions(before, this._items);
+    this.emitCompletedTransitions(before, this._items, opts?.source ?? 'tool');
     this.emit('todo.updated', { items: this._items });
     return { changed: true };
   }
 
-  applyEdits(edits: readonly TodoEdit[]): { changed: boolean } {
+  applyEdits(edits: readonly TodoEdit[], opts?: { source?: TodoCompletionSource }): { changed: boolean } {
     const before = this._items;
     const next = applyTodoEdits(this._items, edits);
     if (listsEqual(before, next)) return { changed: false };
     this._items = next;
     this.lastWriteAt = Date.now();
-    this.emitCompletedTransitions(before, this._items);
+    this.emitCompletedTransitions(before, this._items, opts?.source ?? 'reconcile');
     this.emit('todo.edited', { edits, items: this._items });
     this.emit('todo.updated', { items: this._items });
     return { changed: true };
   }
 
   /** Why: Preserve the established compatibility and safety behavior (M16). */
-  private emitCompletedTransitions(before: readonly TodoItem[], after: readonly TodoItem[]): void {
+  private emitCompletedTransitions(
+    before: readonly TodoItem[],
+    after: readonly TodoItem[],
+    source: TodoCompletionSource = 'tool',
+  ): void {
     const count = countCompletedTransitions(before, after);
-    if (count > 0) this.emit('todo.completed', { count, at: Date.now() });
+    if (count > 0) this.emit('todo.completed', { count, at: Date.now(), source });
   }
 
   rebuild(entries: readonly unknown[]): void {

package/src/tool-error.ts

@@ -0,0 +1,26 @@
+/**
+ * A1: pi only marks a tool result as failed when `execute()` throws — "Returning a value never sets
+ * the error flag regardless of what properties you include in the return object"
+ * (pi docs/extensions.md, "Signaling errors").
+ *
+ * The round-2 audit found 20+ real failures in pier's tools returned as plain text, so neither the
+ * model nor pi's own hooks keyed on `event.isError` could see them (pier's B1 "subagent alive but
+ * reported no output" self-heal was dead code for exactly that reason). Every hard failure now goes
+ * through `toolError()`; deliberate non-failures (empty result set, "no match within Xms", a pane
+ * that simply has not produced output yet) stay normal results.
+ *
+ * The "Error: " prefix the old text returns carried is dropped: the provider's tool-result error
+ * channel and pi's red rendering already mark it, and keeping it would double the prefix once pi
+ * formats a thrown error.
+ */
+export class ToolError extends Error {
+  constructor(message: string) {
+    super(String(message).replace(/^Error:\s*/, ''));
+    this.name = 'ToolError';
+  }
+}
+
+/** Throw a tool failure (never returns). */
+export function toolError(message: string): never {
+  throw new ToolError(message);
+}

package/src/vocab.ts

@@ -48,13 +48,16 @@ export const TODO_TOOL_NAME = 'todo_write';
 /** Snapshot key in tool-result details (persisted in session JSONL). */
 export const TODO_DETAILS_KEY = 'pi-herdr.todo';
 
-/** Confirmation copy (byte-aligned with DSH so model vocab transfers). */
-export function formatTodoConfirmation(items: TodoItem[]): string {
+/** Confirmation copy (byte-aligned with DSH so model vocab transfers; blocked is appended only when present). */
+export function formatTodoConfirmation(items: readonly TodoItem[]): string {
   const c = countTodos(items);
-  return `Updated todo list: ${c.pending} pending, ${c.inProgress} in progress, ${c.completed} completed.`;
+  const base = `Updated todo list: ${c.pending} pending, ${c.inProgress} in progress, ${c.completed} completed.`;
+  // A4: blocked items used to be invisible here (the model read "nothing pending" while items sat
+  // blocked waiting on a human). Appending only when non-zero keeps the DSH-aligned wording intact.
+  return c.blocked > 0 ? `${base.slice(0, -1)}, ${c.blocked} blocked.` : base;
 }
 
-export function countTodos(items: TodoItem[]): TodoCounts {
+export function countTodos(items: readonly TodoItem[]): TodoCounts {
   let pending = 0;
   let inProgress = 0;
   let completed = 0;