pi-pier 0.1.0

package/src/core/terminal.ts

@@ -0,0 +1,359 @@
+/**
+ * 档1 core/terminal（M14 六工具迁 loader entry —— D78 挂载树 / D81 三分法）。
+ *
+ * 形态：cordis 插件（loader entry，热换面 = 本文件）。依赖全部经服务注入：
+ *  - `pi-herdr.surface`：pi 注册面代理（D79 tombstone —— hmr reload 翻墓碑，
+ *    新版本同 key 重挂载、同重注册覆盖 pi 工具表 Map）；
+ *  - `pi-herdr.terminal-deps`：client/env（外层 createHerdrClient 产物）+
+ *    state 槽（index 的 GC 豁免查询 activePaneIds）。
+ *
+ * 本文件不 import index.ts（无环）；terminal-core 为纯逻辑层照旧。
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { Type } from 'typebox';
+import type { PiSurface } from '../pi-surface.ts';
+import type { HerdrClientLike } from '../herdr-client.ts';
+import {
+  READINESS_TIMEOUT_MS,
+  READ_MAX_CHARS,
+  TERMINALS_CUSTOM_TYPE,
+  activeTerminalPaneIds,
+  classifyReadiness,
+  closeTerminal,
+  computeIncrement,
+  detectFullscreenTUI,
+  foldTerminalsRegistry,
+  makeTerminalsRegistry,
+  registerTerminal,
+  stripAnsi,
+  summarizeSessions,
+  validateSendText,
+  validateSignal,
+  type ReadCursor,
+  type TerminalEntry,
+} from '../terminal-core.ts';
+
+export interface TerminalStateSlot {
+  /** index 的 GC 豁免查询（活跃终端 pane 不回收）。 */
+  activePaneIds: () => Set<string>;
+}
+
+export interface TerminalDeps {
+  client: HerdrClientLike;
+  env: { paneId: string; tabId: string } | null;
+  state: TerminalStateSlot;
+}
+
+export default function terminalPlugin(ctx: Context): void {
+  const surface = ctx.get('pi-herdr.surface') as PiSurface<object>;
+  const { client, env, state } = ctx.get('pi-herdr.terminal-deps') as TerminalDeps;
+  const pi = surface.raw as {
+    appendEntry?: (customType: string, data: unknown) => void;
+  };
+  // 模块 key = 本文件（hmr/reload 的 filename 与 ledger.disposeKey 规范化互比）
+  const scoped = surface.forModule(import.meta.url);
+
+  /* ── M14：常驻交互终端六工具（D71 / T1–T6；master 侧 v1，worker 不挂本 entry） ──
+   * 后端 = 独立 herdr pane（不复用 pi TUI pane）：open=pane.split 常驻 shell /
+   * send=pane.send_text+\r / read=pane.read(recent)+本地增量 / signal=pane.send_keys /
+   * close=pane.close。有活跃终端的 pane 豁免 GC（index gcPass 查 state.activePaneIds）。 */
+
+  let terminals: TerminalEntry[] = [];
+
+  function persistTerminals(): void {
+    try {
+      pi.appendEntry?.(TERMINALS_CUSTOM_TYPE, makeTerminalsRegistry(terminals));
+    } catch {
+      /* 持久化尽力而为 */
+    }
+  }
+
+  function rebuildTerminals(eventCtx: unknown): void {
+    try {
+      const entries = (eventCtx as { sessionManager?: { getBranch?: () => readonly unknown[] } })
+        ?.sessionManager?.getBranch?.() ?? [];
+      terminals = foldTerminalsRegistry(entries as Parameters<typeof foldTerminalsRegistry>[0]);
+    } catch {
+      /* 重建失败不影响主流程 */
+    }
+  }
+
+  function findOpenTerminal(id: unknown): TerminalEntry | null {
+    if (typeof id !== 'string') return null;
+    return terminals.find((t) => t.terminalId === id && t.status === 'open') ?? null;
+  }
+
+  function touchTerminal(entry: TerminalEntry): void {
+    entry.lastActivityAt = Date.now();
+    persistTerminals();
+  }
+
+  // GC 豁免槽回填（index gcPass 消费）
+  state.activePaneIds = () => activeTerminalPaneIds(terminals);
+
+  scoped.on('session_start', async (_event: unknown, eventCtx: unknown) => {
+    rebuildTerminals(eventCtx);
+  });
+  scoped.on('session_tree', async (_event: unknown, eventCtx: unknown) => {
+    rebuildTerminals(eventCtx);
+  });
+
+  const TERM_READ_MAX = Number(process.env.PI_HERDR_TERM_READ_MAX ?? READ_MAX_CHARS) || READ_MAX_CHARS;
+  const errText = (msg: string) => ({ content: [{ type: 'text' as const, text: `Error: ${msg}` }], details: {} });
+
+  scoped.registerTool({
+    name: 'terminal_open',
+    label: 'Terminal Open',
+    description: [
+      'Open a persistent interactive terminal (a resident shell in its own herdr pane, next to this session) and return its terminal_id.',
+      'The shell keeps its cwd, environment variables, and background processes across terminal_send/terminal_read calls — use it for dev servers, REPLs, or multi-step shell work instead of one-shot bash calls.',
+      '`cwd` (optional): working directory for the shell (defaults to this session cwd).',
+      'Readiness: waits for the shell prompt (up to 30s); on timeout the terminal still opens — check with terminal_read before sending.',
+      'A human can also type into the pane directly; terminal_close closes it.',
+    ].join(' '),
+    parameters: Type.Object({
+      cwd: Type.Optional(Type.String({ description: 'Working directory for the shell' })),
+    }),
+    async execute(_tc, params, _sig, _upd, ctx) {
+      if (!client.available || !env) return errText('terminal tools require a herdr-managed pane');
+      const cwd = typeof params?.cwd === 'string' && params.cwd ? params.cwd
+        : (ctx as { cwd?: string }).cwd ?? process.cwd();
+      const r = registerTerminal(terminals, {
+        paneId: env.paneId, // 占位：split 后回填真实 paneId
+        tabId: env.tabId,
+        cwd,
+        createdAt: Date.now(),
+      });
+      if (!r.ok) return errText(r.error);
+      let paneId: string;
+      try {
+        paneId = await client.splitPane({ direction: 'right', cwd, focus: false, targetPaneId: env.paneId });
+      } catch (e) {
+        return errText(`failed to split terminal pane: ${(e as Error).message}`);
+      }
+      r.entry.paneId = paneId;
+      terminals = r.entries;
+      persistTerminals();
+      // T3 readiness：PS1 尾匹配（server 端等待）；超时 → 本地兜底再判一次
+      let readiness: 'prompt' | 'silent' | 'busy' = 'busy';
+      try {
+        const matched = await client.waitForOutput(paneId, { type: 'regex', value: '[$>#❯]\\s*$' }, READINESS_TIMEOUT_MS);
+        if (matched) readiness = 'prompt';
+        else {
+          const read = await client.readPane(paneId, { stripAnsi: false });
+          readiness = classifyReadiness(stripAnsi(read.text), { silentMs: 0 });
+        }
+      } catch {
+        /* readiness 尽力而为 */
+      }
+      const text = [
+        `terminal ${r.entry.terminalId} open (pane ${paneId})`,
+        `cwd: ${cwd}`,
+        `readiness: ${readiness}${readiness !== 'prompt' ? ' (prompt not detected yet — check with terminal_read before sending)' : ''}`,
+      ].join('\n');
+      return { content: [{ type: 'text', text }], details: { terminal_id: r.entry.terminalId, pane_id: paneId, readiness } };
+    },
+  });
+
+  scoped.registerTool({
+    name: 'terminal_send',
+    label: 'Terminal Send',
+    description: [
+      'Send a text command (plain text only, no ANSI escapes) to a persistent terminal opened with terminal_open; Enter is appended automatically.',
+      'Returns after the keystrokes are delivered — poll terminal_read for output (long-running commands keep producing output across reads).',
+      'For control keys use terminal_signal instead. Interactive/fullscreen programs (vim, less, top) are outside this seam.',
+    ].join(' '),
+    parameters: Type.Object({
+      terminal_id: Type.String({ description: 'Terminal id from terminal_open' }),
+      text: Type.String({ description: 'Command text to type and run' }),
+    }),
+    async execute(_tc, params) {
+      const entry = findOpenTerminal(params?.terminal_id);
+      if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see terminal_list)`);
+      const v = validateSendText(typeof params?.text === 'string' ? params.text : '');
+      if (!v.ok) return errText(v.error);
+      try {
+        await client.sendPaneText(entry.paneId, v.text);
+      } catch (e) {
+        return errText(`send failed (pane may be closed): ${(e as Error).message}`);
+      }
+      touchTerminal(entry);
+      return { content: [{ type: 'text', text: `sent to ${entry.terminalId} (${v.text.length} chars)` }], details: { terminal_id: entry.terminalId } };
+    },
+  });
+
+  scoped.registerTool({
+    name: 'terminal_read',
+    label: 'Terminal Read',
+    description: [
+      'Read new output from a persistent terminal since your last read (cursor-based increment; the first read returns the recent buffer).',
+      '`terminal_id`: your terminal from terminal_open. Alternatively `pane_id`: a pane in this session\'s own tab (narrow scope by design).',
+      'Output is ANSI-stripped and bounded; if the buffer scrolled past your last read you get a reset marker plus the current tail.',
+      'Detecting a fullscreen TUI program (vim/less/top) returns an error with suggestions instead of garbage.',
+    ].join(' '),
+    parameters: Type.Object({
+      terminal_id: Type.Optional(Type.String({ description: 'Terminal id from terminal_open' })),
+      pane_id: Type.Optional(Type.String({ description: 'Direct pane read (own tab panes only)' })),
+      max_chars: Type.Optional(Type.Number({ description: 'Output cap for this read' })),
+    }),
+    async execute(_tc, params) {
+      let paneId: string | null = null;
+      let entry: TerminalEntry | null = null;
+      if (typeof params?.terminal_id === 'string') {
+        entry = findOpenTerminal(params.terminal_id);
+        if (!entry) return errText(`unknown or closed terminal "${params.terminal_id}" (see terminal_list)`);
+        paneId = entry.paneId;
+      } else if (typeof params?.pane_id === 'string') {
+        // T5 先窄：仅本任务 tab 的 pane 或自建终端 pane
+        try {
+          const panes = await client.listPanes();
+          const target = panes.find((p) => p.paneId === params.pane_id);
+          const ownTab = target?.tabId && target.tabId === env?.tabId;
+          const ownTerminal = activeTerminalPaneIds(terminals).has(params.pane_id);
+          if (!target || (!ownTab && !ownTerminal)) {
+            return errText('pane_id read is limited to panes in this session\'s own tab or self-created terminal panes');
+          }
+          paneId = params.pane_id;
+        } catch (e) {
+          return errText(`pane lookup failed: ${(e as Error).message}`);
+        }
+      } else {
+        return errText('provide terminal_id (or pane_id for a direct own-tab read)');
+      }
+      const maxChars = typeof params?.max_chars === 'number' && params.max_chars > 0
+        ? Math.min(params.max_chars, TERM_READ_MAX) : TERM_READ_MAX;
+      let read: { text: string; revision: number; truncated: boolean };
+      try {
+        read = await client.readPane(paneId, { stripAnsi: false });
+      } catch (e) {
+        return errText(`read failed (pane may be closed): ${(e as Error).message}`);
+      }
+      // T6 检测点1：全屏 TUI（alternate screen）——在 raw 上识别
+      const tui = detectFullscreenTUI(read.text);
+      if (tui.detected) {
+        const head = stripAnsi(read.text).slice(0, 200);
+        const text = [
+          'FULLSCREEN_TUI_DETECTED: this terminal is running a fullscreen program (e.g. vim/less/top); its screen output is not readable here.',
+          'Suggestions:',
+          '1. Run such programs in a native herdr pane where the human can interact directly.',
+          '2. Use non-interactive alternatives (cat/grep instead of less; edit/write tools instead of vim).',
+          `Raw head (first 200 chars): ${head}`,
+        ].join('\n');
+        return { content: [{ type: 'text', text }], details: { error: 'FULLSCREEN_TUI_DETECTED' } };
+      }
+      const prev: ReadCursor | null = entry
+        ? (entry.readRevision != null
+          ? { revision: entry.readRevision, len: entry.readLen, tail: entry.readTail, eoTail: entry.readEoTail }
+          : null)
+        : null;
+      const inc = computeIncrement(prev, { text: read.text, revision: read.revision }, maxChars);
+      if (entry) {
+        entry.readRevision = inc.cursor.revision;
+        entry.readLen = inc.cursor.len;
+        entry.readTail = inc.cursor.tail;
+        entry.readEoTail = inc.cursor.eoTail;
+        touchTerminal(entry);
+      }
+      if (inc.mode === 'none') {
+        return { content: [{ type: 'text', text: 'no new output' }], details: { mode: 'none', revision: read.revision } };
+      }
+      const output = stripAnsi(inc.text);
+      const text = output.length ? output : '(empty)';
+      return {
+        content: [{ type: 'text', text }],
+        details: { mode: inc.mode, revision: read.revision, hard_capped: inc.hardCapped, source_revision_truncated: read.truncated },
+      };
+    },
+  });
+
+  scoped.registerTool({
+    name: 'terminal_signal',
+    label: 'Terminal Signal',
+    description: [
+      'Send a control key to a persistent terminal: ctrl+c (interrupt), ctrl+d (EOF), ctrl+z (suspend), esc, enter.',
+      'Use ctrl+c to stop a running command; anything beyond this whitelist (complex key sequences) is outside the terminal seam.',
+    ].join(' '),
+    parameters: Type.Object({
+      terminal_id: Type.String({ description: 'Terminal id from terminal_open' }),
+      key: Type.String({ description: 'One of: ctrl+c, ctrl+d, ctrl+z, esc, enter' }),
+    }),
+    async execute(_tc, params) {
+      const entry = findOpenTerminal(params?.terminal_id);
+      if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see terminal_list)`);
+      const v = validateSignal(typeof params?.key === 'string' ? params.key : '');
+      if (!v.ok) return errText(v.error);
+      try {
+        await client.sendPaneKeys(entry.paneId, [v.key]);
+      } catch (e) {
+        return errText(`signal failed (pane may be closed): ${(e as Error).message}`);
+      }
+      touchTerminal(entry);
+      return { content: [{ type: 'text', text: `signal ${v.key} sent to ${entry.terminalId}` }], details: { terminal_id: entry.terminalId, key: v.key } };
+    },
+  });
+
+  scoped.registerTool({
+    name: 'terminal_close',
+    label: 'Terminal Close',
+    description: [
+      'Close a persistent terminal (kills its shell process tree and removes the pane).',
+      'Terminal state does not survive close — persist anything you need to files first.',
+    ].join(' '),
+    parameters: Type.Object({
+      terminal_id: Type.String({ description: 'Terminal id from terminal_open' }),
+    }),
+    async execute(_tc, params) {
+      const id = params?.terminal_id;
+      const entry = terminals.find((t) => t.terminalId === id);
+      if (!entry) return errText(`unknown terminal "${String(id)}" (see terminal_list)`);
+      if (entry.status === 'open') {
+        try {
+          await client.closePane(entry.paneId);
+        } catch {
+          /* pane 已消失（人关/随 tab 关）→ 直接补记 */
+        }
+      }
+      terminals = closeTerminal(terminals, entry.terminalId, Date.now()).entries;
+      persistTerminals();
+      return { content: [{ type: 'text', text: `terminal ${entry.terminalId} closed` }], details: { terminal_id: entry.terminalId } };
+    },
+  });
+
+  scoped.registerTool({
+    name: 'terminal_list',
+    label: 'Terminal List',
+    description: [
+      'List this session\'s persistent terminals with open/closed and pane-liveness status.',
+      'Entries whose pane is gone (human closed it, restart) are marked closed — terminal sessions do not survive pane closure or restarts; persist state to files instead of relying on terminal reuse.',
+    ].join(' '),
+    parameters: Type.Object({}),
+    async execute() {
+      let livePaneIds: string[] = [];
+      try {
+        livePaneIds = (await client.listPanes()).map((p) => p.paneId);
+      } catch {
+        /* 查询失败：全部按未知（不误标 closed）——live 集为空只影响 stale 判定 */
+      }
+      const s = summarizeSessions(terminals, livePaneIds);
+      // T6 检测点3：pane 消失 → 补记 closed（跨重启边界：不复活，提示持久化）
+      if (s.stalePaneIds.length > 0) {
+        terminals = terminals.map((t) =>
+          s.stalePaneIds.includes(t.paneId)
+            ? { ...t, status: 'closed' as const, closedAt: t.closedAt ?? Date.now() }
+            : t,
+        );
+        persistTerminals();
+      }
+      if (s.terminals.length === 0) {
+        return { content: [{ type: 'text', text: 'no terminals (open one with terminal_open)' }], details: { terminals: [] } };
+      }
+      const lines = s.terminals.map((t) =>
+        `- ${t.terminalId} [${t.live ? 'open' : 'closed'}] pane=${t.paneId} cwd=${t.cwd}${t.label ? ` (${t.label})` : ''}`,
+      );
+      const note = s.stalePaneIds.length > 0
+        ? '\nnote: terminal sessions do not survive pane closure/restart — persist results to files.'
+        : '';
+      return { content: [{ type: 'text', text: lines.join('\n') + note }], details: { terminals: s.terminals } };
+    },
+  });
+}

package/src/core/todo.ts

@@ -0,0 +1,313 @@
+/**
+ * 档1 core/todo（todo 族迁 loader entry —— D78 挂载树 / D81 融合核心）。
+ *
+ * 形态：cordis 插件（master 经 loader.create 挂 = 热换面；worker 裸根手动 mount，
+ * D81 one-shot 裁剪）。依赖全部经服务注入：
+ *  - `pi-herdr.surface`：pi 注册面代理（D79 tombstone）；
+ *  - `pi-herdr.todo-deps`：todos 服务（session 状态层，留在 index）+ options +
+ *    mirrorTodos 回调 + appendEntry + state 槽（renderWidget 回填给 index 生命周期）。
+ *
+ * 本文件承接：todo_write 工具 + /todos /todo 命令 + TUI widget（widgetLines/
+ * renderWidget/formatTodosMarkdown）+ 读钩（before_agent_start planTodoReadHook，
+ * 轮次计数器内聚）。reconcile / 镜像 / reportAgent 仍在 index（session 状态层）。
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { Type } from 'typebox';
+import { join } from 'node:path';
+import { writeFileSync } from 'node:fs';
+import type { PiSurface } from '../pi-surface.ts';
+import type { TodosService } from '../todos-service.ts';
+import { planTodoReadHook } from '../todo-read-hook.ts';
+import { makeProgressUpdate } from '../subagent-core.ts';
+import { TODO_DETAILS_KEY, TODO_TOOL_NAME, formatTodoConfirmation, type TodoItem, type TodoStatus } from '../vocab.ts';
+import {
+  TODO_EDIT_CUSTOM_TYPE,
+  boundedView,
+  completionTransitions,
+  fuzzyFind,
+  listsEqual,
+  makeSnapshot,
+  normalizeStrict,
+  revertedCompleted,
+  validateTodos,
+} from '../todo-core.ts';
+
+export interface TodoUiSlot {
+  /** index 的 session_start/session_tree 生命周期调用（plugin 回填）。 */
+  renderWidget: (ctx: unknown) => void;
+}
+
+export interface TodoDeps {
+  todos: TodosService;
+  allowParallelInProgress: boolean;
+  /** 软上限提示（不硬拒）。 */
+  maxItems: number;
+  mirrorTodos: () => void;
+  appendEntry: (customType: string, data: unknown) => void;
+  state: TodoUiSlot;
+}
+
+const TOOL_DESCRIPTION = [
+  'Record and update the complete task list for the current work. Every call REPLACES the entire list (last write wins), so always resend the full list.',
+  'Entries: `content` (non-empty, unique; short imperative, what-not-how; no numbering prefixes), `status` (pending | in_progress | completed | blocked | abandoned), optional `blocker` (only when blocked: what it is waiting for), optional `phase` (group name for multi-stage plans; omit for a flat list).',
+  'Keep the list short (at most 15 entries): one entry per meaningful unit of work, not per micro-step.',
+  'Mark tasks you are actively working on as in_progress; several may be in_progress when work genuinely runs in parallel.',
+  'Mark tasks done immediately after finishing. Never mark a task completed while its tests fail or its work is incomplete. If you cannot remember the exact content of an entry, re-derive it from the previous todo_write result instead of guessing.',
+  'Do not make todo_write the only tool call of a turn — batch it together with real work.',
+  '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(' ');
+
+const TODO_MARKS: Record<TodoStatus, string> = {
+  pending: '○',
+  in_progress: '▶',
+  completed: '✓',
+  blocked: '■',
+  abandoned: '✗',
+};
+
+function widgetLines(items: TodoItem[]): string[] {
+  if (items.length === 0) return [];
+  const counts = { pending: 0, inProgress: 0, completed: 0, blocked: 0 };
+  for (const it of items) {
+    if (it.status === 'pending') counts.pending++;
+    else if (it.status === 'in_progress') counts.inProgress++;
+    else if (it.status === 'completed') counts.completed++;
+    else if (it.status === 'blocked') counts.blocked++;
+  }
+  const lines = [`todo: ${counts.inProgress}▶ ${counts.pending}○ ${counts.blocked}■ ${counts.completed}✓`];
+  // D43 phase 分组 + D39 有界（每组预算 10 行）
+  const groups = new Map<string, TodoItem[]>();
+  for (const it of items) {
+    const key = it.phase ?? '';
+    const arr = groups.get(key) ?? [];
+    arr.push(it);
+    groups.set(key, arr);
+  }
+  for (const [phase, list] of groups) {
+    if (phase) lines.push(`  [${phase}]`);
+    const view = boundedView(list, 10);
+    for (const it of view.visible) {
+      const suffix = it.status === 'blocked' && it.blocker ? ` — ${it.blocker}` : '';
+      lines.push(`  ${TODO_MARKS[it.status]} ${it.content}${suffix}`);
+    }
+    if (view.hiddenCompleted > 0 || view.hiddenOpen > 0) {
+      lines.push(`   +${view.hiddenCompleted + view.hiddenOpen} more (${view.hiddenCompleted} completed, ${view.hiddenOpen} open)`);
+    }
+  }
+  return lines;
+}
+
+/** D38：TODO.md 导出（分组 + 任务列表语法）。 */
+function formatTodosMarkdown(items: TodoItem[]): string {
+  const groups = new Map<string, TodoItem[]>();
+  for (const it of items) {
+    const key = it.phase ?? '默认';
+    const arr = groups.get(key) ?? [];
+    arr.push(it);
+    groups.set(key, arr);
+  }
+  const lines = ['# TODO'];
+  for (const [phase, list] of groups) {
+    lines.push('', `## ${phase}`);
+    for (const it of list) {
+      const box = it.status === 'completed' ? 'x'
+        : it.status === 'in_progress' ? '/'
+        : it.status === 'blocked' ? '!'
+        : it.status === 'abandoned' ? '~'
+        : ' ';
+      const suffix = it.status === 'blocked' && it.blocker ? ` — blocker: ${it.blocker}` : '';
+      lines.push(`- [${box}] ${it.content}${suffix}`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export default function todoPlugin(ctx: Context): void {
+  const surface = ctx.get('pi-herdr.surface') as PiSurface<object>;
+  const { todos, allowParallelInProgress, maxItems, mirrorTodos, appendEntry, state } =
+    ctx.get('pi-herdr.todo-deps') as TodoDeps;
+  const scoped = surface.forModule(import.meta.url);
+
+  function renderWidget(eventCtx: unknown): void {
+    try {
+      (eventCtx as { ui?: { setWidget?: (id: string, lines: string[]) => void } })?.ui?.setWidget?.(
+        'todos',
+        widgetLines(todos.items),
+      );
+    } catch {
+      /* 无 widget 能力的 pi 版本静默降级 */
+    }
+  }
+
+  // 槽回填：index 的 session_start/session_tree 调用
+  state.renderWidget = renderWidget;
+
+  /* ── 读钩（轮次计数器内聚；D39 提示注入） ── */
+  let todoReadTurn = 0;
+  let lastEmptyGuardTurn: number | null = null;
+  scoped.on('before_agent_start', async () => {
+    const plan = planTodoReadHook({
+      items: todos.items,
+      turn: todoReadTurn,
+      lastEmptyGuardTurn,
+    });
+    todoReadTurn += 1;
+    if (!plan.inject) return;
+    if (todos.items.length === 0) lastEmptyGuardTurn = todoReadTurn - 1;
+    return {
+      message: {
+        customType: plan.message.customType,
+        content: plan.message.content,
+        display: false,
+      },
+    };
+  });
+
+  /* ── 工具：todo_write ── */
+  scoped.registerTool({
+    name: TODO_TOOL_NAME,
+    label: 'Todo',
+    description: TOOL_DESCRIPTION,
+    parameters: Type.Object({
+      todos: Type.Array(
+        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' }),
+            blocker: Type.Optional(Type.String({ description: 'Only when status is "blocked": what it is waiting for' })),
+            phase: Type.Optional(Type.String({ description: 'Optional group name (≤30 chars); omit for a flat list' })),
+          },
+          { additionalProperties: false },
+        ),
+        { description: 'The COMPLETE task list; this call replaces the previous list' },
+      ),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, eventCtx) {
+      void toolCallId;
+      void signal;
+      const result = validateTodos(params?.todos, allowParallelInProgress);
+      if (!result.ok) {
+        return {
+          content: [{ type: 'text', text: `Error: ${result.error}` }],
+          details: {},
+        };
+      }
+      const strictMode = todos.config.strict; // D75 阶段 2：策略进 service config
+      let next = result.items!;
+      const strictNotes: string[] = [];
+      if (strictMode) {
+        const strict = normalizeStrict(next);
+        const demoted = next
+          .filter((it, i) => it.status === 'in_progress' && strict[i]?.status === 'pending')
+          .map((it) => it.content);
+        const promoted = strict
+          .find((it, i) => it.status === 'in_progress' && next[i]?.status !== 'in_progress')?.content;
+        if (demoted.length > 0) strictNotes.push(`demoted to pending: ${demoted.join(', ')}`);
+        if (promoted) strictNotes.push(`auto-promoted to in_progress: ${promoted}`);
+        next = strict;
+      }
+      // D35：no-op（与当前列表全等 → 不落盘不镜像）
+      if (listsEqual(todos.items, next)) {
+        return { content: [{ type: 'text', text: 'No change: todo list already matches.' }], details: {} };
+      }
+      // D36/D37：过渡信号与回退警告
+      const completed = completionTransitions(todos.items, next);
+      const reverted = revertedCompleted(todos.items, next);
+      todos.replace(next);
+      if (todos.items.length > maxItems) {
+        onUpdate?.(makeProgressUpdate(`Note: list has ${todos.items.length} entries; consider keeping it under ${maxItems}.`));
+      }
+      mirrorTodos();
+      renderWidget(eventCtx);
+      const lines = [formatTodoConfirmation(todos.items)];
+      if (completed.length > 0) lines.push(`Completed: ${completed.join(' | ')}`);
+      if (reverted.length > 0) {
+        lines.push(`Warning: previously completed item(s) reverted to open: ${reverted.join(' | ')} — is that intentional?`);
+      }
+      for (const n of strictNotes) lines.push(`Normalized (strict mode): ${n}`);
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        details: {
+          [TODO_DETAILS_KEY]: makeSnapshot(todos.items),
+          ...(completed.length > 0 ? { completedTasks: completed } : {}),
+        },
+      };
+    },
+  });
+
+  /* ── 命令：/todos（查看 + done/drop/rm 人类编辑，D38）+ /todo export ── */
+  scoped.registerCommand('todos', {
+    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)) {
+        const query = raw.slice(1).join(' ').trim();
+        if (!query) {
+          ui?.notify?.('usage: /todos done|drop|rm|unblock <content>', 'warning');
+          return;
+        }
+        const candidates = fuzzyFind(todos.items, query);
+        if (candidates.length === 0) {
+          ui?.notify?.(`no todo matches "${query}"`, 'warning');
+          return;
+        }
+        if (candidates.length > 1) {
+          ui?.notify?.(`ambiguous — matches:\n${candidates.map((c) => `  - ${c}`).join('\n')}`, 'warning');
+          return;
+        }
+        const content = candidates[0];
+        const edit = { op: opArg as 'done' | 'drop' | 'rm' | 'unblock', content };
+        const before = todos.items;
+        todos.applyEdits([edit]);
+        if (listsEqual(before, todos.items)) {
+          ui?.notify?.(`no change: "${content}" is already in that state`, 'info');
+          return;
+        }
+        // D38：人类编辑写回权威（custom 条目，重启后分支回放生效）
+        try {
+          appendEntry(TODO_EDIT_CUSTOM_TYPE, { version: 1, edits: [edit], ts: Date.now() });
+        } catch {
+          /* 尽力而为 */
+        }
+        mirrorTodos();
+        renderWidget(eventCtx);
+        const verb = opArg === 'done' ? 'completed'
+          : opArg === 'drop' ? 'abandoned'
+          : opArg === 'unblock' ? 'unblocked (back to pending)'
+          : 'removed';
+        ui?.notify?.(`"${content}" ${verb}`, 'info');
+        return;
+      }
+      const lines = widgetLines(todos.items);
+      const text = lines.length ? lines.join('\n') : 'todo list is empty';
+      ui?.notify?.(text, 'info');
+    },
+  });
+
+  scoped.registerCommand('todo', {
+    description: 'Export the current todo list to TODO.md in the working directory',
+    handler: async (_args: unknown, eventCtx: unknown) => {
+      const ui = (eventCtx as { ui?: { notify?: (text: string, level?: string) => void } }).ui;
+      const cwd = (eventCtx as { cwd?: string }).cwd ?? process.cwd();
+      try {
+        const target = join(cwd, 'TODO.md');
+        writeFileSync(target, formatTodosMarkdown(todos.items));
+        ui?.notify?.(`TODO.md written: ${target} (${todos.items.length} items)`, 'info');
+      } catch (err) {
+        ui?.notify?.(`failed to write TODO.md: ${(err as Error).message}`, 'error');
+      }
+    },
+  });
+}