pi-pier 0.2.3 → 0.2.5

package/src/index.ts

@@ -7,10 +7,10 @@
  * Capabilities:
  *  - `todo_write`: replace the complete todo list; the current pi session JSONL is authoritative,
  *    and branches automatically roll back in DSH-aligned semantics.
- *  - `subagent`: foreground/background delegation. Each child pane is an interactive pi TUI
- *    with an independent session/context that humans can enter directly; the controller uses
- *    herdr for state-gated injection (idle only), waiting (agent.wait), and JSONL result reads.
- *  - `list_agents` / `send_message` (followUp queue semantics) / `interrupt_agent` (esc).
+ *  - `subagent`: foreground/background delegation plus resume/list/send/interrupt actions.
+ *    Each child pane is an interactive pi TUI with an independent session/context that humans
+ *    can enter directly; the controller uses herdr for state-gated injection (idle only),
+ *    waiting (agent.wait), and JSONL result reads.
  *  - `/todos`, TUI widget, and herdr title projection with graceful degradation without herdr.
  *
  * pi 0.84.2 contract (validated):
@@ -111,9 +111,14 @@ export default async function (pi: ExtensionAPI) {
 
   /** Tier 2: worker role badge parsed from the env manifest and kept visible while idle. */
   let roleBadge: string | null = null;
+  /** Human-gate depth; ask_user_question and external herdr:blocked events share it. */
+  let blockedDepth = 0;
 
   function reportAgent(state: 'working' | 'idle' | 'blocked', activity: string | null): void {
     if (!client.available) return;
+    // While a human gate is open, never let tool-badge / turn_start / settle overwrite blocked.
+    // Needed when herdr:pi is absent (pi-herdr is the authority); no-op under full-lifecycle herdr:pi.
+    if (blockedDepth > 0 && state !== 'blocked') return;
     const message = activity ?? (state === 'idle' ? roleBadge : null);
     client.reportAgent(state, message).catch(() => {});
   }
@@ -156,8 +161,8 @@ export default async function (pi: ExtensionAPI) {
       progressSuffix: suffix,
       lastWriteAt: todos.lastWriteAt,
     });
-    // D97: narrow-frame static state shares inputs with the pane title; thinking tokens cannot reach it, so a static frame would freeze.
-    updateSlimFrame(title);
+    // D97: overlay content shares the todo snapshot; thinking tokens cannot reach it.
+    updateSlimFrame({ title, items: todos.items, lastWriteAt: todos.lastWriteAt });
     client.reportMetadata({
       session: label,
       items: todos.items,
@@ -369,15 +374,16 @@ export default async function (pi: ExtensionAPI) {
     if (plan.notice && !isSubagent) {
       const running = subagentPort.current?.listRunningSubs() ?? [];
       const brief = running.map((s) => `${s.paneId} (${s.description})`).join('、');
-      const notice = `注意：仍有 ${running.length} 个后台 subagent 在运行：${brief}。若你的任务依赖它们，请等待其结算（list_agents 查看状态）；若不等待，请说明放弃原因。`;
+      const notice = `注意：仍有 ${running.length} 个后台 subagent 在运行：${brief}。若你的任务依赖它们，请等待其结算（subagent list 查看状态）；若不等待，请说明放弃原因。`;
       void sendUserMessageIn(notice);
     }
   });
 
-  // v1.3 M8: report blocked state ourselves (D29's exemption relies on blocked visibility).
-  // Observed: pi 0.84.2 core emits no "herdr:blocked" (the official integration listener is dead code),
-  // so this extension manages enterBlocked/exitBlocked while ask_user_question waits for human input.
-  let blockedDepth = 0;
+  // Official herdr:pi is full-lifecycle authority when installed: it reports blocked
+  // only on the herdr:blocked event (pi core never emits it). Custom source=pi-herdr
+  // pane.report_agent is ignored while that authority is live
+  // (screen_detection_skip_reason=full_lifecycle_hook_authority). Emit the event so
+  // herdr:pi publishes blocked; keep report_agent as fallback when it is absent.
   function enterBlocked(label: string | null): void {
     blockedDepth += 1;
     reportAgent('blocked', label);
@@ -392,14 +398,34 @@ export default async function (pi: ExtensionAPI) {
       void client.reportAskFlag(null).catch(() => {});
     }
   }
-  (pi as { events?: { on?: (ev: string, cb: (data: unknown) => void) => void } }).events?.on?.(
-    'herdr:blocked',
-    (data) => {
-      const d = data as { active?: boolean; label?: string } | undefined;
-      if (d?.active) enterBlocked(typeof d.label === 'string' ? d.label : null);
+
+  // emit() is synchronous; this flag stops our own listener from double-counting depth.
+  let publishingHerdrBlocked = false;
+  function publishHerdrBlocked(active: boolean, label: string | null): void {
+    publishingHerdrBlocked = true;
+    try {
+      if (active) enterBlocked(label);
       else exitBlocked();
-    },
-  );
+      pi.events.emit(
+        'herdr:blocked',
+        active ? { active: true, ...(label ? { label } : {}) } : { active: false },
+      );
+    } finally {
+      publishingHerdrBlocked = false;
+    }
+  }
+  pi.events.on('herdr:blocked', (data) => {
+    if (publishingHerdrBlocked) return;
+    if (!data || typeof data !== 'object') {
+      exitBlocked();
+      return;
+    }
+    if (!('active' in data) || data.active !== true) {
+      exitBlocked();
+      return;
+    }
+    enterBlocked('label' in data && typeof data.label === 'string' ? data.label : null);
+  });
 
   /* ── Tool: ask_user_question (v1.3 M8 human gate, available to master and subagents) ── */
 
@@ -423,9 +449,10 @@ export default async function (pi: ExtensionAPI) {
       const ui = (ctx as {
         ui?: { input?: (title: string, placeholder?: string) => Promise<string | undefined> };
       }).ui;
-      enterBlocked(question);
-      // v1.3 M8 observed: herdr keeps detecting working while waiting for a human, overriding a one-shot blocked report;
-      // repeat it every 5s so the pane stays blocked and remains visible/GC-exempt.
+      publishHerdrBlocked(true, question);
+      // Fallback when herdr:pi is absent: a one-shot pi-herdr blocked report can lose
+      // to later working reports; refresh while the gate is open. Do not re-emit
+      // herdr:blocked here — official blockedCount is edge-triggered.
       const hb = setInterval(() => { reportAgent('blocked', question); }, 5000);
       try {
         const answer = await ui?.input?.(question, 'your answer');
@@ -435,7 +462,7 @@ export default async function (pi: ExtensionAPI) {
         };
       } finally {
         clearInterval(hb);
-        exitBlocked();
+        publishHerdrBlocked(false, null);
       }
     },
   });

package/src/notice-buffer.ts

@@ -12,12 +12,12 @@ export const NOTICE_MAX_SHOWN = 3;
  * Collapse a batch into one message body.
  * - empty → null (do not inject)
  * - ≤max → originals joined with `\n\n` (single-item byte-identical to the old format)
- * - >max → first max originals + a tail pointing at history / list_agents
+ * - >max → first max originals + a tail pointing at history / subagent list
  */
 export function collapseNotices(contents: readonly string[], max = NOTICE_MAX_SHOWN): string | null {
   if (contents.length === 0) return null;
   if (contents.length <= max) return contents.join('\n\n');
   const hidden = contents.length - max;
-  const tail = `…另有 ${hidden} 条结算未逐条展示。全量结果看 history 台账（路径公式见 resume_subagent 工具描述）；在跑代理用 list_agents 查看。`;
+  const tail = `…另有 ${hidden} 条结算未逐条展示。全量结果看 history 台账（路径公式见 subagent resume 工具描述）；在跑代理用 subagent list 查看。`;
   return [...contents.slice(0, max), tail].join('\n\n');
 }

package/src/roles/master.json

@@ -1,13 +1,13 @@
 {
   "role": "master",
-  "version": "1.3.1",
-  "description": "主控角色（WS-D7 自应用；D83 镜像源）：自研核心全量（todos/协调/subagent 族/终端族）+ pi 内建检视执行 + web_search；D82 unknownTools=allow——用户安装的任意扩展默认可见可用（install 即授予）",
+  "version": "1.4.0",
+  "description": "主控角色（WS-D7 自应用；D83 镜像源）：核心工具（todos/协调/subagent/terminal）+ pi 内建 + web_search；D82 unknownTools=allow。v1.4.0: 工具合并 terminal 6→1, subagent 5→1",
   "manifest": {
     "unknownTools": "allow",
     "tools": [
       "todo_write", "ask_user_question",
-      "subagent", "resume_subagent", "list_agents", "send_message", "interrupt_agent",
-      "terminal_open", "terminal_send", "terminal_read", "terminal_signal", "terminal_close", "terminal_list",
+      "subagent",
+      "terminal",
       "read", "grep", "glob", "bash", "pwsh", "edit", "write",
       "web_search"
     ],

package/src/roles/worker-default.json

@@ -1,7 +1,7 @@
 {
   "role": "worker-default",
-  "version": "1.3.1",
-  "description": "默认worker角色（D83 继承制）：镜像 master.tools 减 subagent 族（禁嵌套）减 terminal 族（M14 资源归属）；排除族显式 deny——在 D82 unknownTools=allow 姿态下仍持禁令；todos serial",
+  "version": "1.4.0",
+  "description": "默认worker角色（D83 继承制）：镜像 master.tools 减 subagent/terminal（禁嵌套、资源归属）；排除族显式 deny——在 D82 unknownTools=allow 姿态下仍持禁令；todos serial。v1.4.0: 工具合并后更新 deny 列表",
   "manifest": {
     "unknownTools": "allow",
     "tools": [
@@ -11,16 +11,7 @@
     ],
     "rules": {
       "subagent": "deny",
-      "resume_subagent": "deny",
-      "list_agents": "deny",
-      "send_message": "deny",
-      "interrupt_agent": "deny",
-      "terminal_open": "deny",
-      "terminal_send": "deny",
-      "terminal_read": "deny",
-      "terminal_signal": "deny",
-      "terminal_close": "deny",
-      "terminal_list": "deny",
+      "terminal": "deny",
       "*": "allow"
     }
   },

package/src/slim-frame.ts

@@ -1,6 +1,7 @@
 /**
  * D97 slim frame: when a pane is too narrow or short for the minimum usable TUI,
- * cover it with a non-capturing full-screen overlay containing a static frame sourced from the pane title.
+ * cover it with a non-capturing overlay. Content is three-tier: full TUI (overlay
+ * hidden), an activity-anchored todo window when ≥3 rows fit, else the pane title.
  *
  * Why (observed by the user): after the heat view compresses an unfocused pane, streaming worker thinking
  * continuously repaints the entire screen in the narrow pane, causing flicker. The static frame updates only on
@@ -22,11 +23,21 @@
  * flow. PI_HERDR_SLIM_FRAME=0 is the escape hatch.
  */
 
+import { isArchived } from './stale-core.ts';
+import type { TodoItem } from './vocab.ts';
+import { anchorTodoRange, formatTodoSummary, renderTodoGroups } from './todo-window.ts';
+
 /** Minimum usable TUI dimensions (pi interactive-mode layout: editor 3 rows + footer 1 + transcript ≥3 + spacing).
- * Below either threshold the pane cannot display a readable TUI, so it renders the title as a static frame. */
+ * Below either threshold the pane cannot display a readable TUI, so the overlay covers it. */
 
 export const SLIM_MIN_COLS = 24;
 export const SLIM_MIN_ROWS = 12;
+/** Overlay todo window needs this many rows after wrap; below that, fall back to the title frame. */
+export const SLIM_TODO_MIN_ROWS = 3;
+/** Narrower than this, todo lines wrap into a column; keep the title frame instead. */
+export const SLIM_TODO_MIN_COLS = 16;
+/** Empty-list copy: the pane is alive but has no plan yet (replaces a lone ·). */
+export const SLIM_EMPTY_COPY = 'no todos yet';
 
 /** Visibility predicate (overlayOptions.visible invokes it on every render frame). */
 export function isSlimFrame(cols: number, rows: number): boolean {
@@ -115,6 +126,93 @@ export function frameLines(
   return out;
 }
 
+function padFrame(
+  content: readonly string[],
+  opts: { width: number; rows: number; colorize: (s: string) => string; vAlign: 'center' | 'top' },
+): string[] {
+  const width = Math.max(1, Math.floor(opts.width));
+  const rows = Math.max(1, Math.floor(opts.rows));
+  const pad = (s: string) => s + ' '.repeat(Math.max(0, width - displayWidth(s)));
+  const body = content.slice(0, rows);
+  const top = opts.vAlign === 'center' ? Math.max(0, Math.floor((rows - body.length) / 2)) : 0;
+  const out: string[] = [];
+  for (let i = 0; i < rows; i++) {
+    const idx = i - top;
+    out.push(idx >= 0 && idx < body.length ? pad(opts.colorize(body[idx])) : ' '.repeat(width));
+  }
+  return out;
+}
+
+function wrapTodoBody(items: readonly TodoItem[], width: number): string[] {
+  return renderTodoGroups(items).flatMap((line) => wrapByWidth(line, width));
+}
+
+function itemsEqual(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;
+}
+
+export interface SlimFrameInput {
+  title?: string | null;
+  items?: readonly TodoItem[];
+  lastWriteAt?: number | null;
+  now?: number;
+}
+
+/**
+ * Choose overlay content: todo window when the pane can show ≥3 wrapped rows at ≥16 cols;
+ * otherwise the pane title (or SLIM_EMPTY_COPY when the list is empty).
+ */
+export function slimContentLines(
+  input: SlimFrameInput & { width: number; rows: number; colorize?: (s: string) => string },
+): string[] {
+  const width = Math.max(1, Math.floor(input.width));
+  const rows = Math.max(1, Math.floor(input.rows));
+  const colorize = input.colorize ?? ((s: string) => s);
+  const items = input.items ?? [];
+  const title = (input.title ?? '').trim();
+  const fallback = title || SLIM_EMPTY_COPY;
+  const titleFrame = () => frameLines(fallback, { width, rows, colorize });
+
+  if (rows < SLIM_TODO_MIN_ROWS || width < SLIM_TODO_MIN_COLS) return titleFrame();
+  if (items.length === 0) return titleFrame();
+  if (isArchived(items, input.lastWriteAt ?? null, input.now ?? Date.now())) return titleFrame();
+
+  const header = wrapByWidth(formatTodoSummary(items), width);
+  const fullBody = wrapTodoBody(items, width);
+  if (header.length + fullBody.length <= rows) {
+    const packed = [...header, ...fullBody];
+    if (packed.length < SLIM_TODO_MIN_ROWS) return titleFrame();
+    return padFrame(packed, { width, rows, colorize, vAlign: 'top' });
+  }
+
+  const footerProbe = wrapByWidth('   +99 hidden (99✓) · /todos', width);
+  const itemBudget = rows - header.length - footerProbe.length;
+  if (itemBudget < 1) return titleFrame();
+
+  const [start, end] = anchorTodoRange(
+    items,
+    (s, e) => wrapTodoBody(items.slice(s, e), width).length <= itemBudget,
+  );
+  const kept = items.slice(start, end);
+  const body = wrapTodoBody(kept, width);
+  if (body.length === 0 || body.length > itemBudget) return titleFrame();
+
+  const hidden = items.filter((_, i) => i < start || i >= end);
+  const hiddenCompleted = hidden.filter((it) => it.status === 'completed').length;
+  const footer = wrapByWidth(`   +${hidden.length} hidden (${hiddenCompleted}✓) · /todos`, width);
+  const packed = [...header, ...body, ...footer];
+  if (packed.length < SLIM_TODO_MIN_ROWS) return titleFrame();
+  return padFrame(packed, { width, rows, colorize, vAlign: 'top' });
+}
+
 /* ── Overlay component plus registration/update (process-local singleton) ─────────────────────────── */
 
 interface FrameTui {
@@ -122,7 +220,9 @@ interface FrameTui {
 }
 
 class SlimFrameComponent {
-  private text = '';
+  private title = '';
+  private items: readonly TodoItem[] = [];
+  private lastWriteAt: number | null = null;
   private lastRows = 0;
   private cache: { width: number; lines: string[] } | null = null;
   private readonly tui: FrameTui;
@@ -137,21 +237,30 @@ class SlimFrameComponent {
   onViewport(cols: number, rows: number): boolean {
     if (this.lastRows !== rows) {
       this.lastRows = rows;
-      this.cache = null; // A row-count change requires re-centering.
+      this.cache = null; // A row-count change requires re-layout.
     }
     return isSlimFrame(cols, rows);
   }
 
-  setText(text: string): void {
-    if (this.text === text) return;
-    this.text = text;
+  setSnapshot(title: string, items: readonly TodoItem[], lastWriteAt: number | null): void {
+    if (this.title === title && this.lastWriteAt === lastWriteAt && itemsEqual(this.items, items)) return;
+    this.title = title;
+    this.items = items;
+    this.lastWriteAt = lastWriteAt;
     this.cache = null;
     this.tui.requestRender();
   }
 
   render(width: number): string[] {
     if (this.cache && this.cache.width === width) return this.cache.lines;
-    const lines = frameLines(this.text, { width, rows: this.lastRows, colorize: this.colorize });
+    const lines = slimContentLines({
+      title: this.title,
+      items: this.items,
+      lastWriteAt: this.lastWriteAt,
+      width,
+      rows: this.lastRows,
+      colorize: this.colorize,
+    });
     this.cache = { width, lines };
     return lines;
   }
@@ -214,7 +323,7 @@ export function registerSlimFrame(eventCtx: unknown): void {
   }
 }
 
-/** Update static-frame content (same arguments/source as the pane-title projection; null means no plan). */
-export function updateSlimFrame(title: string | null): void {
-  active?.setText(title ?? '');
+/** Update overlay snapshot. Title remains the fallback; items drive the todo window. */
+export function updateSlimFrame(input: SlimFrameInput): void {
+  active?.setSnapshot(input.title ?? '', input.items ?? [], input.lastWriteAt ?? null);
 }

package/src/subagent-core.ts

@@ -122,13 +122,13 @@ export function buildAliveNotice(
       `Subagent "${description}" is still running in pane ${paneId} (agent_status=${status}${activity}).`,
       'The foreground wait has moved it to background so this call returns now.',
       'Do NOT redo its work. When it settles you will receive a notification with its closing output.',
-      'Use list_agents to check its live state; send_message to give it follow-up work.',
+      'Use subagent(action: "list") to check its live state; subagent(action: "send") to give it follow-up work.',
     ].join(' ');
   }
   return [
     `The subagent "${description}" is ALIVE in pane ${paneId} (agent_status=${status}${activity}) — this "no readable output" result only means its final answer could not be read yet, NOT that the task failed.`,
     'Do NOT redo its work. It is being moved to background; you will be notified when it settles.',
-    'Use list_agents to check its live state.',
+    'Use subagent(action: "list") to check its live state.',
   ].join(' ');
 }
 
@@ -141,7 +141,7 @@ export function buildBlockedGateNotice(opts: { paneId: string; description: stri
     'It keeps running in background; once the human answers it resumes, and you will be notified when it settles.',
     'Do NOT take over its work and do NOT answer on the human\'s behalf.',
     'Tell the user to open that pane in herdr and answer directly.',
-    'Only if the user explicitly authorizes you: relay their decision to the subagent via send_message — do not redo the work yourself.',
+    'Only if the user explicitly authorizes you: relay their decision to the subagent via subagent(action: "send") — do not redo the work yourself.',
   ].join(' ');
 }
 

package/src/subagent-poll-loop.ts

@@ -245,7 +245,7 @@ export function createPoller(h: PollerHost): Poller {
           h.writeHistory(entry, { outcome: 'observation timeout' }, 'poll-timeout');
           const notes = h.reconcileOnSettlement(description, 'failed');
           const notice = h.withReconcileNotes(
-            `Background subagent ${paneId} (${description}) has shown no progress for ${Math.round((Date.now() - lastActivityAt) / 1000)}s (observed since ${new Date(startedAt).toISOString()}). Run list_agents to check its live state; if it is working, let it run — its settlement notice will arrive automatically. Do not sleep-wait.`,
+            `Background subagent ${paneId} (${description}) has shown no progress for ${Math.round((Date.now() - lastActivityAt) / 1000)}s (observed since ${new Date(startedAt).toISOString()}). Run subagent(action: "list") to check its live state; if it is working, let it run — its settlement notice will arrive automatically. Do not sleep-wait.`,
             notes,
           );
           try {

package/src/subagent-session-io.ts

@@ -122,7 +122,11 @@ export function createSessionIo(h: SessionIoHost): SessionIo {
   ): Promise<{ text: string | null; pendingTool: boolean; activity: boolean }> {
     for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
       const entries = readSessionFile(file);
-      if (entries.length === 0) continue;
+      // readSessionFile returns null when the path is missing or unreadable.
+      // herdr often reports a .jsonl path before the worker creates the file;
+      // waitAgent(idle) then returns immediately and this path used to throw
+      // `Cannot read properties of null (reading 'length')` (session 01a055c5).
+      if (!entries?.length) continue;
       const r = lastAssistantText(entries, { sinceTs });
       if (r?.text) return { text: r.text, pendingTool: false, activity: true };
       if (hasPendingToolCall(entries, sinceTs)) return { text: null, pendingTool: true, activity: true };

package/src/terminal-core.ts

@@ -96,7 +96,7 @@ export function registerTerminal(
   if (openCount >= MAX_TERMINALS) {
     return {
       ok: false,
-      error: `terminal limit reached (max ${MAX_TERMINALS} open terminals); close one with terminal_close before opening another`,
+      error: `terminal limit reached (max ${MAX_TERMINALS} open terminals); close one with terminal(action: "close") before opening another`,
     };
   }
   const entry: TerminalEntry = {
@@ -143,7 +143,7 @@ export function validateSendText(text: string): { ok: true; text: string } | { o
   if (text.includes('\x1b')) {
     return {
       ok: false,
-      error: 'unsupported input: ANSI escape sequences cannot be sent as text; use terminal_signal for control keys, or plain commands only',
+      error: 'unsupported input: ANSI escape sequences cannot be sent as text; use terminal(action: "signal") for control keys, or plain commands only',
     };
   }
   // Why: Preserve the established compatibility and safety behavior (C0).
@@ -152,7 +152,7 @@ export function validateSendText(text: string): { ok: true; text: string } | { o
   if (bad) {
     return {
       ok: false,
-      error: `unsupported input: control character 0x${bad[0].charCodeAt(0).toString(16)}; terminal_send accepts plain text commands only (use terminal_signal for ctrl+c etc.)`,
+      error: `unsupported input: control character 0x${bad[0].charCodeAt(0).toString(16)}; terminal send accepts plain text commands only (use terminal(action: "signal") for ctrl+c etc.)`,
     };
   }
   return { ok: true, text: stripped };

package/src/todo-window.ts

@@ -0,0 +1,82 @@
+/**
+ * Activity-anchored todo window used by the pi widget and the slim overlay.
+ *
+ * Why: both surfaces must keep the in-progress row visible instead of a fixed
+ * head/tail slice. The widget budgets unwrapped render lines; the overlay
+ * supplies its own `fits` so wrapping can consume extra rows.
+ */
+import { countTodos, type TodoItem, type TodoStatus } from './vocab.ts';
+
+export const TODO_MARKS: Record<TodoStatus, string> = {
+  pending: '○',
+  in_progress: '▶',
+  completed: '✓',
+  blocked: '■',
+  abandoned: '✗',
+};
+
+export function formatTodoSummary(items: readonly TodoItem[]): string {
+  const c = countTodos(items as TodoItem[]);
+  return `todo: ${c.inProgress}▶ ${c.pending}○ ${c.blocked}■ ${c.completed}✓`;
+}
+
+/** Share phase rendering so widget and overlay order entries identically. */
+export function renderTodoGroups(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;
+}
+
+/**
+ * Expand around the active anchor while `fits(start, end)` remains true.
+ * Prefers upcoming work; the anchor stays visible. All-completed lists keep
+ * the original head-shrink (widget-compatible).
+ */
+export function anchorTodoRange(
+  items: readonly TodoItem[],
+  fits: (start: number, end: number) => boolean,
+): [number, number] {
+  if (items.length === 0) return [0, 0];
+  if (fits(0, items.length)) 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) {
+    let end = items.length;
+    while (end > 1 && !fits(0, end)) end -= 1;
+    return [0, end];
+  }
+  let start = anchorIdx;
+  let end = anchorIdx + 1;
+  let growTail = true;
+  while ((end < items.length || start > 0) && (end - start) < items.length) {
+    if (growTail && end < items.length) {
+      end += 1;
+      if (!fits(start, end)) { end -= 1; break; }
+    } else if (start > 0) {
+      start -= 1;
+      if (!fits(start, end)) { start += 1; break; }
+    } else if (end < items.length) {
+      end += 1;
+      if (!fits(start, end)) { end -= 1; break; }
+    } else {
+      break;
+    }
+    growTail = !growTail;
+  }
+  return [start, end];
+}