pi-pier 0.1.0

package/src/todo-core.ts

@@ -0,0 +1,331 @@
+/**
+ * todo 纯逻辑：校验 / 折叠 / M10 增量（D34–D43）。
+ *
+ * 全部无副作用、无 pi API 依赖 → 可单测（node --test 直接跑 TS）。
+ * 语义 = DESIGN.md §5.1.1 + §15：全量替换（last-wins），五态 + blocker + phase。
+ */
+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';
+
+export type { TodoItem, TodoSnapshot, TodoStatus, TodoCounts };
+
+/** D43：phase 名长度上限。 */
+export const PHASE_MAX_LEN = 30;
+
+/** D38：人类编辑 custom 条目类型（/todos done/drop/rm 写回权威的通道）。 */
+export const TODO_EDIT_CUSTOM_TYPE = 'pi-herdr.todo-edit';
+
+/** 人类编辑操作（D38）：done=completed、drop=abandoned、rm=移除、unblock=blocked→pending（M17）。 */
+export type TodoEditOp = 'done' | 'drop' | 'rm' | 'unblock';
+
+export interface TodoEdit {
+  op: TodoEditOp;
+  content: string;
+}
+
+export interface TodoEditPayload {
+  version: 1;
+  edits: TodoEdit[];
+  ts: number;
+}
+
+export interface TodoValidationResult {
+  ok: boolean;
+  items?: TodoItem[];
+  error?: string;
+}
+
+/**
+ * 校验一次 todo_write 的入参并规范化为条目数组（D34/D43 扩展）。
+ * 规则：
+ *  - todos 必须是数组（空数组合法 = 清空列表）；
+ *  - 每条允许键 = content/status/blocker/phase，不允许其他键；
+ *  - content 非空且全局唯一；status ∈ 五态；
+ *  - blocker 仅 status==='blocked' 时允许（非空字符串），其他状态携带即拒绝；
+ *  - phase 可选：非空、≤30 字符；
+ *  - allowParallelInProgress=false 时，至多一条 in_progress（B2 严格模式的第一道闸）。
+ */
+export function validateTodos(
+  todos: unknown,
+  allowParallelInProgress = true,
+): TodoValidationResult {
+  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' };
+    }
+    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)` };
+      }
+    }
+    if (!('content' in entry) || !('status' in entry)) {
+      return { ok: false, error: 'invalid todos: each todo must have `content` and `status`' };
+    }
+    const content = entry.content;
+    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}"` };
+    }
+    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 };
+    if ('blocker' in entry) {
+      const blocker = entry.blocker;
+      if (status !== 'blocked') {
+        return { ok: false, error: `invalid todo: \`blocker\` is only allowed when status is "blocked" (got "${status}")` };
+      }
+      if (typeof blocker !== 'string' || blocker.trim() === '') {
+        return { ok: false, error: 'invalid todo: `blocker` must be a non-empty string' };
+      }
+      item.blocker = blocker;
+    }
+    if ('phase' in entry) {
+      const phase = entry.phase;
+      if (typeof phase !== 'string' || phase.trim() === '' || phase.length > PHASE_MAX_LEN) {
+        return { ok: false, error: `invalid todo: \`phase\` must be a non-empty string ≤ ${PHASE_MAX_LEN} chars` };
+      }
+      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})`,
+        };
+      }
+    }
+    items.push(item);
+  }
+  return { ok: true, items };
+}
+
+/**
+ * D42 严格模式归一化（OMP normalizeInProgressTask 语义，按 pane 角色自动推导）：
+ *  - 多余 in_progress（列表顺序第二条起）退回 pending；
+ *  - 无 in_progress 且有 pending → 晋升列表顺序第一条 pending；
+ *  - blocked/abandoned 不参与晋升。
+ * 返回新数组（不改入参）。
+ */
+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 (!kept) {
+    const firstPending = out.find((it) => it.status === 'pending');
+    if (firstPending) firstPending.status = 'in_progress';
+  }
+  return out;
+}
+
+/** D35：逐项全等比较（content/status/blocker/phase），用于 no-op 检测。 */
+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++) {
+    const x = a[i];
+    const y = b[i];
+    if (x.content !== y.content || x.status !== y.status || x.blocker !== y.blocker || x.phase !== y.phase) return false;
+  }
+  return true;
+}
+
+/** D36：本轮新变为 completed 的 content 列表（prev → next）。 */
+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;
+}
+
+/** D37：上轮 completed、本轮退回 pending/in_progress 的 content 列表（软警告用）。 */
+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;
+}
+
+/** 构造持久化快照（version 字段让消费方在未来形状变化时丢弃陈旧数据）。 */
+export function makeSnapshot(items: TodoItem[]): TodoSnapshot {
+  return { version: 1, items };
+}
+
+export interface BranchEntryLike {
+  /** pi 会话条目：type 为 'message' 的消息条目或 'custom' 的自定义条目。 */
+  type?: string;
+  message?: {
+    role?: string;
+    toolName?: string;
+    details?: Record<string, unknown> | unknown;
+  } | unknown;
+  customType?: string;
+  data?: unknown;
+}
+
+/**
+ * D38：在列表上应用人类编辑（幂等：目标不存在则 no-op）。
+ *  - done：pending/in_progress/blocked → completed；completed 保持（completed 不可逆，D37）；
+ *  - drop：非 completed/abandoned → abandoned；
+ *  - rm：移除（任意状态）；
+ *  - unblock（M17）：blocked → pending（清 blocker）；非 blocked 为 no-op。
+ */
+export function applyTodoEdits(items: readonly TodoItem[], edits: readonly TodoEdit[]): TodoItem[] {
+  let out = items.map((it) => ({ ...it }));
+  for (const edit of edits) {
+    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;
+        }
+        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);
+        break;
+      case 'unblock':
+        if (target.status === 'blocked') {
+          target.status = 'pending';
+          delete target.blocker;
+        }
+        break;
+    }
+  }
+  return out;
+}
+
+function extractEditPayload(data: unknown): TodoEditPayload | null {
+  if (typeof data !== 'object' || data === null) return null;
+  const raw = data as Partial<TodoEditPayload>;
+  if (raw.version !== 1 || !Array.isArray(raw.edits)) return null;
+  const edits: TodoEdit[] = [];
+  for (const e of raw.edits) {
+    if (
+      typeof e === 'object' && e !== null &&
+      (e.op === 'done' || e.op === 'drop' || e.op === 'rm' || e.op === 'unblock') &&
+      typeof (e as TodoEdit).content === 'string'
+    ) {
+      edits.push({ op: (e as TodoEdit).op, content: (e as TodoEdit).content });
+    }
+  }
+  if (edits.length === 0) return null;
+  return { version: 1, edits, ts: typeof raw.ts === 'number' ? raw.ts : 0 };
+}
+
+/**
+ * 从 pi 会话分支条目里折叠出最新 todo 列表（D38 双源）：
+ *  - toolResult(todo_write) → 快照替换（last-wins）；
+ *  - custom(pi-herdr.todo-edit) → 在当前列表上应用 edits（人类编辑）。
+ * 分支正确性 = 沿分支路径顺序折叠。
+ */
+export function foldLatestTodos(entries: readonly BranchEntryLike[]): TodoItem[] | null {
+  let found: TodoItem[] | null = null;
+  for (const entry of entries) {
+    if (entry.type === 'message') {
+      const msg = entry.message;
+      if (typeof msg !== 'object' || msg === null) continue;
+      if (msg.role !== 'toolResult' || msg.toolName !== TODO_TOOL_NAME) continue;
+      const snapshot = extractSnapshotFromDetails(msg.details);
+      if (snapshot) found = snapshot.items.map((it) => ({ ...it }));
+    } else if (entry.type === 'custom' && entry.customType === TODO_EDIT_CUSTOM_TYPE) {
+      const payload = extractEditPayload(entry.data);
+      if (payload && found) found = applyTodoEdits(found, payload.edits);
+    }
+  }
+  return found;
+}
+
+export 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;
+  const snap = raw as Partial<TodoSnapshot>;
+  if (snap.version !== 1 || !Array.isArray(snap.items)) return null;
+  return { version: 1, items: snap.items as TodoItem[] };
+}
+
+/** D38：模糊匹配（精确 → 前缀 → 子串），返回候选 content 列表（多候选 = 歧义）。 */
+export function fuzzyFind(items: readonly TodoItem[], query: string): string[] {
+  const q = query.trim();
+  if (!q) return [];
+  const exact = items.filter((it) => it.content === q);
+  if (exact.length > 0) return [exact[0].content];
+  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);
+}
+
+/** D39：有界视图选择——先丢 completed、再截断尾部；返回可见条目与摘要。 */
+export interface BoundedView {
+  visible: TodoItem[];
+  /** 被隐藏的数量按状态计数（completed 单独计，其余合并）。 */
+  hiddenCompleted: number;
+  hiddenOpen: number;
+}
+
+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');
+  let visible = open.slice(0, budget);
+  const hiddenOpen = open.length - visible.length;
+  let hiddenCompleted = completed.length;
+  if (hiddenOpen === 0 && visible.length < budget) {
+    const room = budget - visible.length;
+    visible = [...visible, ...completed.slice(0, room)];
+    hiddenCompleted = completed.length - room;
+  }
+  return { visible, hiddenCompleted, hiddenOpen };
+}
+
+/** 当前 in_progress 中的第一条（上报 agent 状态时作为 message，供侧边栏显示"正在做什么"）。 */
+export function currentActivity(items: TodoItem[]): string | null {
+  return items.find((it) => it.status === 'in_progress')?.content ?? null;
+}
+
+export { countTodos };

package/src/todo-read-hook.ts

@@ -0,0 +1,54 @@
+/**
+ * D69：todo 阅读钩子规划（before_agent_start + display:false）。
+ */
+import { boundedView, currentActivity, type TodoItem } from './todo-core.ts';
+import { countTodos } from './vocab.ts';
+
+export const EMPTY_GUARD_EVERY_N = 4;
+export const TODO_READ_CUSTOM_TYPE = 'pi-herdr.todo-read';
+
+export interface TodoReadPlan {
+  inject: boolean;
+  message: {
+    customType: string;
+    content: string;
+    display: false;
+  };
+}
+
+export function planTodoReadHook(opts: {
+  items: readonly TodoItem[];
+  turn: number;
+  lastEmptyGuardTurn: number | null;
+}): TodoReadPlan {
+  const empty = opts.items.length === 0;
+  if (empty) {
+    const due = opts.lastEmptyGuardTurn == null
+      || opts.turn - opts.lastEmptyGuardTurn >= EMPTY_GUARD_EVERY_N;
+    return {
+      inject: due,
+      message: {
+        customType: TODO_READ_CUSTOM_TYPE,
+        content: 'Your todo list is empty. If the current work needs tracking, call todo_write before stopping.',
+        display: false,
+      },
+    };
+  }
+  const c = countTodos(opts.items);
+  const view = boundedView(opts.items, 6);
+  const lines = view.visible.map((it) => {
+    const mark = it.status === 'in_progress' ? '▶' : it.status === 'blocked' ? '■' : it.status === 'completed' ? '✓' : '○';
+    return `${mark} ${it.content}`;
+  });
+  const activity = currentActivity(opts.items as TodoItem[]);
+  const head = `todos ▶${c.inProgress} ○${c.pending} ■${c.blocked} ✓${c.completed}`
+    + (activity ? ` · ${activity}` : '');
+  return {
+    inject: true,
+    message: {
+      customType: TODO_READ_CUSTOM_TYPE,
+      content: [head, ...lines].join('\n'),
+      display: false,
+    },
+  };
+}

package/src/todos-service.ts

@@ -0,0 +1,66 @@
+/**
+ * 档 0：todos 升为进程内 Service（D65 / D75 阶段 2）。
+ * 持久化仍是 pi 会话分支重放；D75 阶段 3：config 从 role manifest services 注入
+ * （无 manifest 的 master / 纯标签 worker 走默认——worker serial、master parallel）。
+ */
+import { EventEmitter } from 'node:events';
+import {
+  applyTodoEdits,
+  foldLatestTodos,
+  type TodoEdit,
+  type TodoItem,
+} from './todo-core.ts';
+import { countCompletedTransitions } from './progress-core.ts';
+import type { RuntimeRoleManifest } from './tool-gate.ts';
+
+export interface TodosConfig {
+  strict: boolean;
+  allowParallelInProgress: boolean;
+}
+
+export class TodosService extends EventEmitter {
+  items: TodoItem[] = [];
+  readonly config: TodosConfig;
+
+  constructor(config: TodosConfig) {
+    super();
+    this.config = config;
+  }
+
+  /** D75 阶段 3：role manifest services.todos（mode/reminderLimit）驱动；strict = 进程身份（worker）。 */
+  static configFromRuntime(manifest: RuntimeRoleManifest | null, isSubagent: boolean): TodosConfig {
+    const strict = isSubagent;
+    const mode = manifest?.services?.todos?.mode;
+    const allowParallelInProgress = mode === 'parallel' || mode === 'serial' ? mode === 'parallel' : !strict;
+    return { strict, allowParallelInProgress };
+  }
+
+  replace(items: readonly TodoItem[]): void {
+    const before = this.items;
+    this.items = items.map((it) => ({ ...it }));
+    this.emitCompletedTransitions(before, this.items);
+    this.emit('todo.updated', { items: this.items });
+  }
+
+  applyEdits(edits: readonly TodoEdit[]): void {
+    const before = this.items;
+    this.items = applyTodoEdits(this.items, edits);
+    this.emitCompletedTransitions(before, this.items);
+    this.emit('todo.edited', { edits, items: this.items });
+    this.emit('todo.updated', { items: this.items });
+  }
+
+  /** M16：completed 转换数（所有编辑路径统一 diff；速率估算的原料）。 */
+  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 会重新锚定）。
+    const folded = foldLatestTodos(entries as Parameters<typeof foldLatestTodos>[0]);
+    if (folded) this.items = folded;
+    this.emit('todo.updated', { items: this.items, reason: 'rebuild' });
+  }
+}

package/src/tool-gate.ts

@@ -0,0 +1,106 @@
+/**
+ * 档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。
+ */
+import type { PermissionAction, UnknownToolStance } from './role-manifest.ts';
+
+/** env 下发的运行时形态（PI_HERDR_ROLE_MANIFEST JSON）。 */
+export interface RuntimeRoleManifest {
+  role: string;
+  version?: string;
+  tools: string[];
+  permissions: Record<string, PermissionAction>;
+  /** D82：未知工具姿态（缺省 deny = 安全默认）。 */
+  unknownTools?: UnknownToolStance;
+  services?: {
+    todos?: {
+      mode?: 'serial' | 'parallel';
+      reminderLimit?: number;
+    };
+  };
+}
+
+/** 安全解析 PI_HERDR_ROLE_MANIFEST env（畸形 → null = 不强制，fail-open 到无角色态）。 */
+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
+    if (m.unknownTools !== undefined && m.unknownTools !== 'allow' && m.unknownTools !== 'deny') {
+      m.unknownTools = 'deny';
+    }
+    return m;
+  } catch {
+    return null;
+  }
+}
+
+export type ToolGatePlan =
+  | { kind: 'open' }
+  | { kind: 'allow' }
+  | { kind: 'ask'; notice: string }
+  | { kind: 'deny'; reason: string };
+
+export function planToolGate(toolName: string, manifest: RuntimeRoleManifest | null): ToolGatePlan {
+  if (!manifest) return { kind: 'open' };
+  const perm = manifest.permissions[toolName] ?? manifest.permissions['*'] ?? 'allow';
+  const known = manifest.tools.includes(toolName);
+  const stance = manifest.unknownTools ?? 'deny';
+  // D82：deny 规则最高优先；未知工具按姿态（deny=拒，allow=按规则走，* 兜底）
+  if (perm === 'deny' || (!known && stance === 'deny')) {
+    return {
+      kind: 'deny',
+      reason:
+        `role "${manifest.role}" does not permit tool "${toolName}" ` +
+        `(manifest tools: ${manifest.tools.join(', ')}). ` +
+        `If the task needs it, ask the master to delegate differently or adjust the role profile.`,
+    };
+  }
+  if (perm === 'ask') {
+    return { kind: 'ask', notice: `[APPROVAL_NEEDED] ${manifest.role}.${toolName}` };
+  }
+  return { kind: 'allow' };
+}
+
+/**
+ * D77 可见层：计算 setActiveTools 的下一状态。
+ * 交集语义（而非替换）——空交集返回 null（fail-open 保留现状），
+ * 防"manifest 列了但插件没装"把工具集清空（如 web_search 装之前的 websearch 档案）。
+ * 保持 currentActive 原顺序；与现状相同 → changed:false（调用方可跳过 set）。
+ *
+ * D82 姿态分支：unknownTools=allow → 不按 manifest 交集裁剪，只隐藏
+ * permissions 中显式 deny 的工具（worker 排除族在继承制下仍不可见）；
+ * 未知工具（用户装的扩展）保持可见。deny（缺省）→ 原交集语义。
+ */
+export function planActiveTools(
+  manifestTools: string[],
+  currentActive: string[],
+  opts?: { unknownTools?: UnknownToolStance; permissions?: Record<string, PermissionAction> },
+): { next: string[]; changed: boolean } | null {
+  if (manifestTools.length === 0 || currentActive.length === 0) return null;
+  if ((opts?.unknownTools ?? 'deny') === 'allow') {
+    const denied = new Set(
+      Object.entries(opts?.permissions ?? {})
+        .filter(([, v]) => v === 'deny')
+        .map(([k]) => k),
+    );
+    const next = currentActive.filter((t) => !denied.has(t));
+    if (next.length === 0) return null;
+    return { next, changed: next.length !== currentActive.length };
+  }
+  const wanted = new Set(manifestTools);
+  const next = currentActive.filter((t) => wanted.has(t));
+  if (next.length === 0) return null;
+  const changed = next.length !== currentActive.length;
+  return { next, changed };
+}
+

package/src/vocab.ts

@@ -0,0 +1,82 @@
+/**
+ * pi-herdr 桥接词汇（M22：标题即看板）。
+ *
+ * 这是 DESIGN.md §4.2 定义的"词汇约定"：不发明新传输协议。
+ * 传输层 = herdr socket API（NDJSON）；todo 权威 = pi 会话 JSONL。
+ * 显示投影 = pane.report_metadata 的 title / state_labels（见 pane-title.ts）。
+ */
+
+/** todo 条目五态（D34：三态 + blocked/abandoned，对齐 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（全量替换语义）。 */
+export interface TodoItem {
+  content: string;
+  status: TodoStatus;
+  /** 仅 status==='blocked' 时允许非空字符串（D34）。 */
+  blocker?: string;
+  /** 可选分组名（D43）；非空、≤30 字符。 */
+  phase?: string;
+}
+
+/** 完整 todo 快照（每次 todo_write 提交的就是它，last-wins）。 */
+export interface TodoSnapshot {
+  /** 语义版本，形状变化时递增；消费方据此丢弃陈旧数据。 */
+  version: 1;
+  items: TodoItem[];
+}
+
+/** 快照计数（反馈文案与标题投影都用它）。 */
+export interface TodoCounts {
+  pending: number;
+  inProgress: number;
+  completed: number;
+  /** D91：blocked 单列（title 四件套 ▶○■✓）。 */
+  blocked: number;
+}
+
+/** pi 扩展经 `pane.report-agent` 上报语义状态时使用的 source 名。 */
+export const REPORT_AGENT_SOURCE = 'pi-herdr';
+
+/** 升级后首次上报用来清掉旧 16-key 分块的头键（M13b 残留）。 */
+export const PI_HERDR_META_KEY = 'pi-herdr';
+
+/** todo 工具面向模型的名称（与 DSH 一致）。 */
+export const TODO_TOOL_NAME = 'todo_write';
+
+/** 工具结果 details 里存放快照的键（随 pi 会话 JSONL 持久化，分支正确）。 */
+export const TODO_DETAILS_KEY = 'pi-herdr.todo';
+
+/** 反馈文案（与 DSH 逐字一致，模型词汇可互迁移）。 */
+export function formatTodoConfirmation(items: TodoItem[]): string {
+  const c = countTodos(items);
+  return `Updated todo list: ${c.pending} pending, ${c.inProgress} in progress, ${c.completed} completed.`;
+}
+
+export function countTodos(items: TodoItem[]): TodoCounts {
+  let pending = 0;
+  let inProgress = 0;
+  let completed = 0;
+  let blocked = 0;
+  for (const it of items) {
+    if (it.status === 'pending') pending++;
+    else if (it.status === 'in_progress') inProgress++;
+    else if (it.status === 'completed') completed++;
+    else if (it.status === 'blocked') blocked++;
+    // abandoned 不计入计数（D34）；blocked 单列（D91 图标四件套进 title）
+  }
+  return { pending, inProgress, completed, blocked };
+}
+
+/** 子代理结算通知文案（对齐 DSH 的 settlement notice）。 */
+export function formatSettlementNotice(
+  agentId: string,
+  closingMessage: string | null,
+): string {
+  const head = `Background subagent ${agentId} finished and will do no further work unless you send it more.`;
+  return closingMessage
+    ? `${head} Its closing message: ${closingMessage}`
+    : `${head} It left no closing message.`;
+}