pi-pier 0.2.4 → 0.2.5

package/src/core/terminal.ts

@@ -99,258 +99,226 @@ export default function terminalPlugin(ctx: Context): void {
   const errText = (msg: string) => ({ content: [{ type: 'text' as const, text: `Error: ${msg}` }], details: {} });
 
   scoped.registerTool({
-    name: 'terminal_open',
-    label: 'Terminal Open',
+    name: 'terminal',
+    label: 'Terminal',
     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.',
+      'Manage persistent interactive terminals (resident shells in dedicated herdr panes).',
+      'Operations: open (create session), send (type commands), read (capture output), signal (ctrl+c/ctrl+d/ctrl+z/esc/enter), close (kill shell), list (show all).',
+      'The shell keeps cwd, environment variables, and background processes across calls.',
+      'Use for dev servers, REPLs, or multi-step shell work — not one-shot bash calls.',
     ].join(' '),
     parameters: Type.Object({
-      cwd: Type.Optional(Type.String({ description: 'Working directory for the shell' })),
+      action: Type.Union([
+        Type.Literal('open'),
+        Type.Literal('send'),
+        Type.Literal('read'),
+        Type.Literal('signal'),
+        Type.Literal('close'),
+        Type.Literal('list'),
+      ], { description: 'Terminal operation to perform' }),
+      cwd: Type.Optional(Type.String({ description: '[open] Working directory for the shell (defaults to session cwd)' })),
+      terminal_id: Type.Optional(Type.String({ description: '[send|read|signal|close] Terminal id returned by open action' })),
+      text: Type.Optional(Type.String({ description: '[send] Command text to type and run (Enter appended automatically)' })),
+      pane_id: Type.Optional(Type.String({ description: '[read] Direct pane read (limited to own tab panes only)' })),
+      max_chars: Type.Optional(Type.Number({ description: '[read] Output cap for this read (default 10000)' })),
+      key: Type.Optional(Type.String({ description: '[signal] Control key: ctrl+c | ctrl+d | ctrl+z | esc | enter' })),
     }),
     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, // Reserve a valid id until split returns the terminal pane.
-        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();
-      const prompt = promptStrategyFor();
-      let readiness: 'prompt' | 'silent' | 'busy' = 'busy';
-      try {
-        const matched = await client.waitForOutput(paneId, { type: 'regex', value: prompt.waitPattern }, READINESS_TIMEOUT_MS);
-        if (matched) readiness = 'prompt';
-        else {
-          const read = await client.readPane(paneId, { stripAnsi: false });
-          readiness = classifyReadiness(stripAnsi(read.text), { silentMs: 0, prompt });
-        }
-      } catch {
-        /* Readiness is advisory, so probe failures still leave a usable terminal. */
+      const action = typeof params?.action === 'string' ? params.action : '';
+      switch (action) {
+        case 'open': return executeTerminalOpen(params, ctx);
+        case 'send': return executeTerminalSend(params);
+        case 'read': return executeTerminalRead(params);
+        case 'signal': return executeTerminalSignal(params);
+        case 'close': return executeTerminalClose(params);
+        case 'list': return executeTerminalList();
+        default:
+          return errText(action
+            ? `unknown action "${action}" (valid: open, send, read, signal, close, list)`
+            : 'action is required (open, send, read, signal, close, list)');
       }
-      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}`);
+  async function executeTerminalOpen(params, 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, // Reserve a valid id until split returns the terminal pane.
+      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();
+    const prompt = promptStrategyFor();
+    let readiness: 'prompt' | 'silent' | 'busy' = 'busy';
+    try {
+      const matched = await client.waitForOutput(paneId, { type: 'regex', value: prompt.waitPattern }, READINESS_TIMEOUT_MS);
+      if (matched) readiness = 'prompt';
+      else {
+        const read = await client.readPane(paneId, { stripAnsi: false });
+        readiness = classifyReadiness(stripAnsi(read.text), { silentMs: 0, prompt });
       }
-      touchTerminal(entry);
-      return { content: [{ type: 'text', text: `sent to ${entry.terminalId} (${v.text.length} chars)` }], details: { terminal_id: entry.terminalId } };
-    },
-  });
+    } catch {
+      /* Readiness is advisory, so probe failures still leave a usable terminal. */
+    }
+    const text = [
+      `terminal ${r.entry.terminalId} open (pane ${paneId})`,
+      `cwd: ${cwd}`,
+      `readiness: ${readiness}${readiness !== 'prompt' ? ' (prompt not detected yet — check with action read before sending)' : ''}`,
+    ].join('\n');
+    return { content: [{ type: 'text', text }], details: { terminal_id: r.entry.terminalId, pane_id: paneId, readiness } };
+  }
 
-  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 limits direct reads to this task tab or owned terminals to prevent cross-task access.
-        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 inspects raw output because ANSI stripping would erase alternate-screen evidence.
-      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 },
-      };
-    },
-  });
+  async function executeTerminalSend(params) {
+    const entry = findOpenTerminal(params?.terminal_id);
+    if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see action 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_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);
+  async function executeTerminalRead(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 action list)`);
+      paneId = entry.paneId;
+    } else if (typeof params?.pane_id === 'string') {
+      // T5 limits direct reads to this task tab or owned terminals to prevent cross-task access.
       try {
-        await client.sendPaneKeys(entry.paneId, [v.key]);
+        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(`signal failed (pane may be closed): ${(e as Error).message}`);
+        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 inspects raw output because ANSI stripping would erase alternate-screen evidence.
+    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);
-      return { content: [{ type: 'text', text: `signal ${v.key} sent to ${entry.terminalId}` }], details: { terminal_id: entry.terminalId, key: v.key } };
-    },
-  });
+    }
+    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_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 {
-          /* The pane may have been closed by a person or with its tab; record the terminal as closed anyway. */
-        }
-      }
-      terminals = closeTerminal(terminals, entry.terminalId, Date.now()).entries;
-      persistTerminals();
-      return { content: [{ type: 'text', text: `terminal ${entry.terminalId} closed` }], details: { terminal_id: entry.terminalId } };
-    },
-  });
+  async function executeTerminalSignal(params) {
+    const entry = findOpenTerminal(params?.terminal_id);
+    if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see action 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_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[] = [];
+  async function executeTerminalClose(params) {
+    const id = params?.terminal_id;
+    const entry = terminals.find((t) => t.terminalId === id);
+    if (!entry) return errText(`unknown terminal "${String(id)}" (see action list)`);
+    if (entry.status === 'open') {
       try {
-        livePaneIds = (await client.listPanes()).map((p) => p.paneId);
+        await client.closePane(entry.paneId);
       } catch {
-        /* Treat a failed query as unknown rather than closed, because an empty live set only affects stale detection. */
-      }
-      const s = summarizeSessions(terminals, livePaneIds);
-      // T6 check 3: record vanished panes as closed across restarts rather than reviving them; tell the user to persist state.
-      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();
+        /* The pane may have been closed by a person or with its tab; record the terminal as closed anyway. */
       }
-      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})` : ''}`,
+    }
+    terminals = closeTerminal(terminals, entry.terminalId, Date.now()).entries;
+    persistTerminals();
+    return { content: [{ type: 'text', text: `terminal ${entry.terminalId} closed` }], details: { terminal_id: entry.terminalId } };
+  }
+
+  async function executeTerminalList() {
+    let livePaneIds: string[] = [];
+    try {
+      livePaneIds = (await client.listPanes()).map((p) => p.paneId);
+    } catch {
+      /* Treat a failed query as unknown rather than closed, because an empty live set only affects stale detection. */
+    }
+    const s = summarizeSessions(terminals, livePaneIds);
+    // T6 check 3: record vanished panes as closed across restarts rather than reviving them; tell the user to persist state.
+    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,
       );
-      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 } };
-    },
-  });
+      persistTerminals();
+    }
+    if (s.terminals.length === 0) {
+      return { content: [{ type: 'text', text: 'no terminals (open one with action 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

@@ -13,12 +13,11 @@ 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_DETAILS_KEY, TODO_TOOL_NAME, formatTodoConfirmation, type TodoItem } from '../vocab.ts';
 import { formatAge, isArchived } from '../stale-core.ts';
 import {
   TODO_EDIT_CUSTOM_TYPE,
   completionTransitions,
-  countTodos,
   fuzzyFind,
   listsEqual,
   makeSnapshot,
@@ -26,6 +25,7 @@ import {
   revertedCompleted,
   validateTodos,
 } from '../todo-core.ts';
+import { anchorTodoRange, formatTodoSummary, renderTodoGroups } from '../todo-window.ts';
 
 export interface TodoUiSlot {
   /** Lets index lifecycle events render through the currently mounted plugin. */
@@ -52,37 +52,9 @@ const TOOL_DESCRIPTION = [
   '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: '✗',
-};
-
 /** Stay within pi interactive mode's ten-line widget cap instead of relying on head truncation. */
 export const WIDGET_MAX_LINES = 10;
 
-/** Share phase rendering between the widget and /todos so both views order entries identically. */
-function renderGroups(items: readonly 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: string[] = [];
-  for (const [phase, list] of groups) {
-    if (phase) lines.push(`  [${phase}]`);
-    for (const it of list) {
-      const suffix = it.status === 'blocked' && it.blocker ? ` — ${it.blocker}` : '';
-      lines.push(`  ${TODO_MARKS[it.status]} ${it.content}${suffix}`);
-    }
-  }
-  return lines;
-}
-
 /**
  * Keep the active task visible within WIDGET_MAX_LINES instead of truncating to a fixed head or
  * tail. The window anchors on the first in-progress item, then the last open item, then recent
@@ -91,21 +63,23 @@ function renderGroups(items: readonly TodoItem[]): string[] {
  */
 export function widgetLines(items: readonly TodoItem[], opts?: { archivedAgeMs?: number | null }): string[] {
   if (items.length === 0) return [];
-  const c = countTodos(items);
   // Collapse archived plans to two lines so stale work cannot monopolize the widget.
   if (opts?.archivedAgeMs != null) {
     return [
-      `todo: ${c.inProgress}▶ ${c.pending}○ ${c.blocked}■ ${c.completed}✓ · archived ${formatAge(opts.archivedAgeMs)}`,
+      `${formatTodoSummary(items)} · archived ${formatAge(opts.archivedAgeMs)}`,
       '  archived — /todos 全量',
     ];
   }
 
   // Reserve summary and overflow lines, then shrink around the anchor because phase headers also consume the budget.
   const renderBudget = WIDGET_MAX_LINES - 1 - 1;
-  const [start, end] = anchorRange(items, renderBudget);
+  const [start, end] = anchorTodoRange(
+    items,
+    (s, e) => renderTodoGroups(items.slice(s, e)).length <= renderBudget,
+  );
   const kept = items.slice(start, end);
   const hidden = items.filter((_, i) => i < start || i >= end);
-  const lines = [`todo: ${c.inProgress}▶ ${c.pending}○ ${c.blocked}■ ${c.completed}✓`, ...renderGroups(kept)];
+  const lines = [formatTodoSummary(items), ...renderTodoGroups(kept)];
   if (hidden.length > 0) {
     const hiddenCompleted = hidden.filter((it) => it.status === 'completed').length;
     lines.push(`   +${hidden.length} hidden (${hiddenCompleted}✓) · /todos 全量`);
@@ -113,44 +87,6 @@ export function widgetLines(items: readonly TodoItem[], opts?: { archivedAgeMs?:
   return lines;
 }
 
-/**
- * Expand around the active anchor within the rendered-line budget, favoring upcoming work while
- * guaranteeing that the anchor remains visible.
- */
-function anchorRange(items: readonly TodoItem[], renderBudget: number): [number, number] {
-  if (renderGroups(items).length <= renderBudget) return [0, items.length];
-  const anchor = items.findIndex((it) => it.status === 'in_progress');
-  const anchorIdx = anchor >= 0
-    ? anchor
-    : items.reduce((acc, it, i) => (it.status !== 'completed' ? i : acc), -1);
-  if (anchorIdx < 0) {
-    // Completed plans keep the most recent tail visible within the line budget.
-    let end = items.length;
-    while (renderGroups(items.slice(0, end)).length > renderBudget && end > 1) end -= 1;
-    return [0, end];
-  }
-  let start = anchorIdx;
-  let end = anchorIdx + 1;
-  const fits = () => renderGroups(items.slice(start, end)).length <= renderBudget;
-  let growTail = true;
-  while ((end < items.length || start > 0) && (end - start) < items.length) {
-    if (growTail && end < items.length) {
-      end += 1;
-      if (!fits()) { end -= 1; break; }
-    } else if (start > 0) {
-      start -= 1;
-      if (!fits()) { start += 1; break; }
-    } else if (end < items.length) {
-      end += 1;
-      if (!fits()) { end -= 1; break; }
-    } else {
-      break;
-    }
-    growTail = !growTail; // Alternate sides so both context and upcoming work remain visible.
-  }
-  return [start, end];
-}
-
 export default function todoPlugin(ctx: Context): void {
   const surface = ctx.get('pi-herdr.surface') as PiSurface<object>;
   const { todos, allowParallelInProgress, maxItems, mirrorTodos, appendEntry, state } =
@@ -372,14 +308,13 @@ export default function todoPlugin(ctx: Context): void {
         return;
       }
       // /todos is the unbounded view because the widget intentionally prioritizes active context.
-      const body = renderGroups(todos.items);
+      const body = renderTodoGroups(todos.items);
       if (body.length === 0) {
         ui?.notify?.('todo list is empty', 'info');
         return;
       }
-      const c = countTodos(todos.items);
       const age = archivedAgeMs();
-      const head = `todo: ${c.inProgress}▶ ${c.pending}○ ${c.blocked}■ ${c.completed}✓`
+      const head = formatTodoSummary(todos.items)
         + (age != null ? ` · archived ${formatAge(age)}（不再注入）` : '');
       ui?.notify?.([head, ...body].join('\n'), 'info');
     },