pi-pier 0.1.4 → 0.2.0

package/src/todo-read-hook.ts

@@ -1,32 +1,32 @@
 /**
- * D69：todo 阅读钩子规划（before_agent_start + display:false）。
- * 反冻结（stale-core）：全完成列表过期后不再复读——
- *  - stale（turns 维度）→ 警告 + 旧条目（供改写参照），每 N 轮一次、封顶；
- *  - archived（墙钟维度）→ 按不存在处理，归档通知与空列表共用守卫节奏。
+ * 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.
  */
 import { boundedView, currentActivity, type TodoItem } from './todo-core.ts';
 import { countTodos } from './vocab.ts';
 import { STALE_NOTICE_MAX, evaluateStaleness, formatAge } from './stale-core.ts';
 
-/** 空守卫 / stale 警告 / 归档通知共用的注入节奏（每 N 轮）。 */
+/** 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';
 
 export type TodoReadEffect =
-  | 'recite' // 正常复读（列表新鲜）
-  | 'empty-guard' // 空列表守卫
-  | 'stale-notice' // A：turns 维度过期警告
-  | 'archive-notice' // B：墙钟维度归档通知
-  | 'none'; // 限频/封顶跳过
+  | '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.
+  | 'none'; // Skip because of rate limits or caps.
 
 export interface TodoReadPlan {
   inject: boolean;
   effect: TodoReadEffect;
-  /** 当前归档态（与 inject 无关；调用方据此刷新 widget/title 投影）。 */
+  /** Current archive state, independent of injection, so callers can refresh widget/title projections. */
   archived: boolean;
-  /** R1：归档通知本次注入即清空内存列表（调用方执行 todos.replace([]) + rm 全量
-   * 落 JSONL——死列表挡住空守卫的 before-stopping 驱动，01a03c0d 实证归档后
-   * 2h 多步工作零跟踪）。 */
+  /** 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). */
   clearArchived: boolean;
   message: {
     customType: string;
@@ -47,12 +47,12 @@ export function planTodoReadHook(opts: {
   items: readonly TodoItem[];
   turn: number;
   lastEmptyGuardTurn: number | null;
-  /** stale-core 时钟锚点（TodosService.lastWriteAt）。 */
+  /** stale-core clock anchor (TodosService.lastWriteAt). */
   lastWriteAt: number | null;
-  /** 距上次 todo 写入的轮数（本进程内已知时）。 */
+  /** Turns since the last todo write, when known in this process. */
   turnsSinceWrite: number | null;
   now: number;
-  /** 本停滞期已注入的 stale 警告数。 */
+  /** Number of stale warnings injected during the current idle period. */
   staleNotices: number;
   lastStaleGuardTurn: number | null;
 }): TodoReadPlan {
@@ -88,9 +88,12 @@ export function planTodoReadHook(opts: {
   if (st.kind === 'archived') {
     const c = countTodos(opts.items as TodoItem[]);
     const age = st.ageMs == null ? '' : ` ${formatAge(st.ageMs)} ago`;
-    // R2：重写窗口——本停滞期还没给过任何 stale 警告时，先给一次带旧条目参照的
-    // 重写机会（idle 期不消耗 turn，墙钟先到 1h 而 turns 警告从未触发，
-    // 01a03c0d 实证：回来后直接吃终态通知，todo_write 5 次被无视）。
+    // 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.
     if (opts.staleNotices === 0 && guardDue) {
       const lines = opts.items.map((it) => `  ${MARKS[it.status]} ${it.content}`);
       const head = `todos ✓${c.completed} (all completed, last updated${age}) — about to be archived`;
@@ -103,8 +106,9 @@ export function planTodoReadHook(opts: {
         message: msg([head, ...lines, warn].join('\n')),
       };
     }
-    // B + R1/R3：终态通知——明细不再注入，本次注入即清空；去掉 [] 豁免出口，
-    // 多步工作必须建清单（单步问答明确放行）。
+    // 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.
     return {
       inject: guardDue,
       effect: 'archive-notice',
@@ -119,7 +123,7 @@ export function planTodoReadHook(opts: {
   }
 
   if (st.kind === 'stale') {
-    // A：复读改警告；保留旧条目行供模型改写参照。封顶 STALE_NOTICE_MAX。
+    // 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) {
@@ -139,7 +143,7 @@ export function planTodoReadHook(opts: {
     };
   }
 
-  // fresh：原有每轮复读。
+  // 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}`);

package/src/todo-reminder-core.ts

@@ -0,0 +1,89 @@
+/**
+ * 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.
+ */
+import { ABORT_STOP_REASON } from './settle-wake-core.ts';
+
+/** Cap reminders for the lifetime of the process, matching the previous behavior. */
+export const TODO_REMINDERS_MAX = 3;
+
+/** Custom message type for reminder injection (registerMessageRenderer can customize its TUI appearance). */
+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.
+ */
+export function todoReminderGraceMs(): number {
+  return Number(process.env.PI_HERDR_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;
+  /** Number of reminders already injected. */
+  reminders: number;
+  /** Number of running background subagents; a positive value means the master is already waiting. */
+  runningSubs: number;
+  /** ask_user_question wait depth; a positive value means the master is waiting for a human response. */
+  blockedDepth: number;
+  /** Current todo list. */
+  items: ReadonlyArray<{ content: string; status: string }>;
+}
+
+export interface TodoReminderPlan {
+  /** Whether a reminder should be injected. */
+  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).
+ */
+export function planStopTodoReminder(input: TodoReminderInput): TodoReminderPlan {
+  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 open = input.items.filter((it) => it.status === 'pending' || it.status === 'in_progress');
+  if (open.length === 0) return noInject(input.reminders);
+  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}):`,
+    list,
+    'Reconcile the list instead of blindly continuing:',
+    '- work that is yours AND already authorized by the user → continue it;',
+    '- work waiting on a human (decision / approval / ops action) → mark it blocked with a blocker note, and ask the user via ask_user_question when you need their input — never execute it yourself just to clear the list;',
+    '- entries that no longer apply → remove them.',
+    'Update the list with todo_write in any case.</system-reminder>',
+  ].join('\n');
+  return { due: true, content, nextReminders: input.reminders + 1 };
+}

package/src/todos-service.ts

@@ -1,12 +1,9 @@
-/**
- * 档 0：todos 升为进程内 Service（D65 / D75 阶段 2）。
- * 持久化仍是 pi 会话分支重放；D75 阶段 3：config 从 role manifest services 注入
- * （无 manifest 的 master / 纯标签 worker 走默认——worker serial、master parallel）。
- */
+/** Why: Preserve the established compatibility and safety behavior (D65, D75). */
 import { EventEmitter } from 'node:events';
 import {
   applyTodoEdits,
   foldLatestTodosMeta,
+  listsEqual,
   type TodoEdit,
   type TodoItem,
 } from './todo-core.ts';
@@ -19,11 +16,14 @@ export interface TodosConfig {
 }
 
 export class TodosService extends EventEmitter {
-  items: TodoItem[] = [];
+  private _items: TodoItem[] = [];
   /**
-   * 列表最后一次真实变更时间（epoch ms）；分支重建取自条目时间戳，无则 null。
-   * 陈旧度判定（stale-core）的时钟锚点；null → 保守永不判 stale。
+   * Live list (read-only). Mutations must go through replace/applyEdits/rebuild.
    */
+  get items(): readonly TodoItem[] {
+    return this._items;
+  }
+  /** Why: Preserve the established compatibility and safety behavior. */
   lastWriteAt: number | null = null;
   readonly config: TodosConfig;
 
@@ -32,7 +32,7 @@ export class TodosService extends EventEmitter {
     this.config = config;
   }
 
-  /** D75 阶段 3：role manifest services.todos（mode/reminderLimit）驱动；strict = 进程身份（worker）。 */
+  /** Why: Preserve the established compatibility and safety behavior (D75). */
   static configFromRuntime(manifest: RuntimeRoleManifest | null, isSubagent: boolean): TodosConfig {
     const strict = isSubagent;
     const mode = manifest?.services?.todos?.mode;
@@ -40,37 +40,48 @@ export class TodosService extends EventEmitter {
     return { strict, allowParallelInProgress };
   }
 
-  replace(items: readonly TodoItem[]): void {
-    const before = this.items;
-    this.items = items.map((it) => ({ ...it }));
+  /** Defensive copy for callers that must not mutate service state. */
+  getSnapshot(): TodoItem[] {
+    return this._items.map((it) => ({ ...it }));
+  }
+
+  replace(items: readonly TodoItem[]): { 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.emit('todo.updated', { items: this.items });
+    this.emitCompletedTransitions(before, this._items);
+    this.emit('todo.updated', { items: this._items });
+    return { changed: true };
   }
 
-  applyEdits(edits: readonly TodoEdit[]): void {
-    const before = this.items;
-    this.items = applyTodoEdits(this.items, edits);
+  applyEdits(edits: readonly TodoEdit[]): { 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.emit('todo.edited', { edits, items: this.items });
-    this.emit('todo.updated', { items: this.items });
+    this.emitCompletedTransitions(before, this._items);
+    this.emit('todo.edited', { edits, items: this._items });
+    this.emit('todo.updated', { items: this._items });
+    return { changed: true };
   }
 
-  /** M16：completed 转换数（所有编辑路径统一 diff；速率估算的原料）。 */
+  /** Why: Preserve the established compatibility and safety behavior (M16). */
   private emitCompletedTransitions(before: readonly TodoItem[], after: readonly TodoItem[]): void {
     const count = countCompletedTransitions(before, after);
     if (count > 0) this.emit('todo.completed', { count, at: Date.now() });
   }
 
   rebuild(entries: readonly unknown[]): void {
-    // 与 v1.x rebuildFromBranch 同语义：分支上折叠不到快照时保留现值
-    //（重建失败不影响主流程；下次 todo_write 会重新锚定）。
+    // Why: Preserve the established compatibility and safety behavior.
+    // Why: Preserve the established compatibility and safety behavior.
     const folded = foldLatestTodosMeta(entries as Parameters<typeof foldLatestTodosMeta>[0]);
     if (folded) {
-      this.items = folded.items;
+      this._items = folded.items;
       this.lastWriteAt = folded.writtenAt;
     }
-    this.emit('todo.updated', { items: this.items, reason: 'rebuild' });
+    this.emit('todo.updated', { items: this._items, reason: 'rebuild' });
   }
 }

package/src/tool-gate.ts

@@ -1,40 +1,28 @@
-/**
- * 档2 Week4-5：worker 执行期强制（2026-08-18；C7 v2 / D76）。
- *
- * master 合成的 manifest 经 env 下发后，这里是 worker 侧的最后一道闸：
- *  - `planToolGate`：工具不在 manifest / 权限 deny → deny（安全护栏）；
- *    ask → 标记（v1 退化：放行 + APPROVAL_NEEDED 日志，硬审批留 v2 拍板）；
- *  - `planActiveTools`（D77 可见层）：manifest 外的工具从模型视野移除——
- *    不进 system prompt、不诱导尝试（上下文卫生，不止权限）。
- * 限速机制已整体移除（WS-D6）：权限边界是我们的职责，资源配额是
- * 插件引入者/provider 的职责（D79 声明式引入，用户自负责）。
- * 纯逻辑零依赖；接缝在 index.ts 的 tool_call 钩子与 session_start。
- */
+/** Why: Preserve the established compatibility and safety behavior (C7, D76, D77, D79, WS-D6). */
 import type { PermissionAction, UnknownToolStance } from './role-manifest.ts';
 
-/** env 下发的运行时形态（PI_HERDR_ROLE_MANIFEST JSON）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export interface RuntimeRoleManifest {
   role: string;
   version?: string;
   tools: string[];
   permissions: Record<string, PermissionAction>;
-  /** D82：未知工具姿态（缺省 deny = 安全默认）。 */
+  /** Why: Preserve the established compatibility and safety behavior (D82). */
   unknownTools?: UnknownToolStance;
   services?: {
     todos?: {
       mode?: 'serial' | 'parallel';
-      reminderLimit?: number;
     };
   };
 }
 
-/** 安全解析 PI_HERDR_ROLE_MANIFEST env（畸形 → null = 不强制，fail-open 到无角色态）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function parseRuntimeManifest(envValue: string | undefined): RuntimeRoleManifest | null {
   if (!envValue) return null;
   try {
     const m = JSON.parse(envValue) as RuntimeRoleManifest;
     if (!m || typeof m.role !== 'string' || !Array.isArray(m.tools)) return null;
-    // D82 硬化：姿态非枚举值 → 收敛为 deny（安全默认），不整个丢弃 manifest
+    // Why: Preserve the established compatibility and safety behavior (D82).
     if (m.unknownTools !== undefined && m.unknownTools !== 'allow' && m.unknownTools !== 'deny') {
       m.unknownTools = 'deny';
     }
@@ -55,7 +43,7 @@ export function planToolGate(toolName: string, manifest: RuntimeRoleManifest | n
   const perm = manifest.permissions[toolName] ?? manifest.permissions['*'] ?? 'allow';
   const known = manifest.tools.includes(toolName);
   const stance = manifest.unknownTools ?? 'deny';
-  // D82：deny 规则最高优先；未知工具按姿态（deny=拒，allow=按规则走，* 兜底）
+  // Why: Preserve the established compatibility and safety behavior (D82).
   if (perm === 'deny' || (!known && stance === 'deny')) {
     return {
       kind: 'deny',
@@ -71,16 +59,7 @@ export function planToolGate(toolName: string, manifest: RuntimeRoleManifest | n
   return { kind: 'allow' };
 }
 
-/**
- * D77 可见层：计算 setActiveTools 的下一状态。
- * 交集语义（而非替换）——空交集返回 null（fail-open 保留现状），
- * 防"manifest 列了但插件没装"把工具集清空（如 web_search 装之前的 websearch 档案）。
- * 保持 currentActive 原顺序；与现状相同 → changed:false（调用方可跳过 set）。
- *
- * D82 姿态分支：unknownTools=allow → 不按 manifest 交集裁剪，只隐藏
- * permissions 中显式 deny 的工具（worker 排除族在继承制下仍不可见）；
- * 未知工具（用户装的扩展）保持可见。deny（缺省）→ 原交集语义。
- */
+/** Why: Preserve the established compatibility and safety behavior (D77, D82). */
 export function planActiveTools(
   manifestTools: string[],
   currentActive: string[],

package/src/vocab.ts

@@ -1,55 +1,54 @@
 /**
- * pi-herdr 桥接词汇（M22：标题即看板）。
+ * pi-herdr bridge vocabulary (M22: title is the board).
  *
- * 这是 DESIGN.md §4.2 定义的"词汇约定"：不发明新传输协议。
- * 传输层 = herdr socket API（NDJSON）；todo 权威 = pi 会话 JSONL。
- * 显示投影 = pane.report_metadata 的 title / state_labels（见 pane-title.ts）。
+ * DESIGN.md §4.2: no new transport. Wire = herdr NDJSON; todo authority = pi
+ * session JSONL; display = pane.report_metadata title / state_labels.
  */
 
-/** todo 条目五态（D34：三态 + blocked/abandoned，对齐 OMP）。 */
+/** Todo five-state (D34: three-state + blocked/abandoned, aligned with OMP). */
 export type TodoStatus = 'pending' | 'in_progress' | 'completed' | 'blocked' | 'abandoned';
 
 export const TODO_STATUSES: readonly TodoStatus[] = ['pending', 'in_progress', 'completed', 'blocked', 'abandoned'];
 
-/** todo 条目形状：content + 五态 status；可选 blocker（仅 blocked）、可选 phase（D43 分组）。无稳定 id（全量替换语义）。 */
+/** Todo item: content + status; optional blocker (blocked only) and phase (D43). No stable id (last-write-wins). */
 export interface TodoItem {
   content: string;
   status: TodoStatus;
-  /** 仅 status==='blocked' 时允许非空字符串（D34）。 */
+  /** Non-empty string only when status==='blocked' (D34). */
   blocker?: string;
-  /** 可选分组名（D43）；非空、≤30 字符。 */
+  /** Optional group name (D43); non-empty, ≤30 chars. */
   phase?: string;
 }
 
-/** 完整 todo 快照（每次 todo_write 提交的就是它，last-wins）。 */
+/** Full todo snapshot (each todo_write submits this; last-wins). */
 export interface TodoSnapshot {
-  /** 语义版本，形状变化时递增；消费方据此丢弃陈旧数据。 */
+  /** Shape version; consumers drop stale snapshots. */
   version: 1;
   items: TodoItem[];
 }
 
-/** 快照计数（反馈文案与标题投影都用它）。 */
+/** Snapshot counts (confirmation copy and title projection). */
 export interface TodoCounts {
   pending: number;
   inProgress: number;
   completed: number;
-  /** D91：blocked 单列（title 四件套 ▶○■✓）。 */
+  /** D91: blocked as its own column (title quartet ▶○■✓). */
   blocked: number;
 }
 
-/** pi 扩展经 `pane.report-agent` 上报语义状态时使用的 source 名。 */
+/** Source name for pane.report-agent. */
 export const REPORT_AGENT_SOURCE = 'pi-herdr';
 
-/** 升级后首次上报用来清掉旧 16-key 分块的头键（M13b 残留）。 */
+/** First-upgrade key used to clear the old 16-key chunked tokens (M13b leftover). */
 export const PI_HERDR_META_KEY = 'pi-herdr';
 
-/** todo 工具面向模型的名称（与 DSH 一致）。 */
+/** Model-facing todo tool name (DSH-compatible). */
 export const TODO_TOOL_NAME = 'todo_write';
 
-/** 工具结果 details 里存放快照的键（随 pi 会话 JSONL 持久化，分支正确）。 */
+/** Snapshot key in tool-result details (persisted in session JSONL). */
 export const TODO_DETAILS_KEY = 'pi-herdr.todo';
 
-/** 反馈文案（与 DSH 逐字一致，模型词汇可互迁移）。 */
+/** Confirmation copy (byte-aligned with DSH so model vocab transfers). */
 export function formatTodoConfirmation(items: TodoItem[]): string {
   const c = countTodos(items);
   return `Updated todo list: ${c.pending} pending, ${c.inProgress} in progress, ${c.completed} completed.`;
@@ -65,12 +64,12 @@ export function countTodos(items: TodoItem[]): TodoCounts {
     else if (it.status === 'in_progress') inProgress++;
     else if (it.status === 'completed') completed++;
     else if (it.status === 'blocked') blocked++;
-    // abandoned 不计入计数（D34）；blocked 单列（D91 图标四件套进 title）
+    // abandoned is omitted (D34); blocked is its own column (D91)
   }
   return { pending, inProgress, completed, blocked };
 }
 
-/** 子代理结算通知文案（对齐 DSH 的 settlement notice）。 */
+/** Subagent settlement notice (aligned with DSH). */
 export function formatSettlementNotice(
   agentId: string,
   closingMessage: string | null,