pi-pier 0.1.5 → 0.2.1

package/src/subagent-spawn.ts

@@ -0,0 +1,156 @@
+/**
+ * Task-tab pane spawn, launch-line construction, and trust-flag decisions.
+ *
+ * Why: spawn mixed herdr layout I/O with the subagent tool body. Placement
+ * races (D26 mutex) and D86 worktree grouping belong in one adapter.
+ */
+import type { HerdrClientLike } from './herdr-client.ts';
+import { pingUntilReady, pipeNameCandidates } from './pipe-channel.ts';
+import { runtimePolicy } from './runtime-policy.ts';
+import {
+  Semaphore,
+  buildLaunchLine,
+  buildLaunchParts,
+  classifyWorktreeZone,
+  isPathUnder,
+  planTabPlacement,
+  type TabPlacementPlan,
+  type WorktreeZone,
+} from './subagent-core.ts';
+import { parseShapeTree, pickGridSplit } from './core/grid-shape.ts';
+import type { GitIo } from './subagent-git-io.ts';
+
+export interface SpawnEnv {
+  paneId: string;
+  tabId: string;
+  workspaceId: string;
+}
+
+export interface SpawnRuntime {
+  nodePath: string;
+  cliPath: string;
+  extPath: string;
+}
+
+export interface SpawnerHost {
+  client: HerdrClientLike;
+  env: SpawnEnv | null;
+  runtime: SpawnRuntime;
+  git: GitIo;
+}
+
+export interface Spawner {
+  spawnPaneInTaskTab(
+    placement: { desiredTab?: string | null; description: string; zone?: WorktreeZone },
+    cwd: string,
+    envOver: Record<string, string>,
+    launch: string,
+  ): Promise<{ tabId: string; paneId: string; tabName: string }>;
+  launchLine(resumeFile?: string | null, roleModel?: string | null, approve?: boolean): string;
+  approveFor(cwd: string, masterCwd: string): Promise<boolean>;
+  waitSubReady(cwd: string, paneId: string): Promise<boolean>;
+  liveTabs(): Promise<Array<{ tabName: string; tabId: string }>>;
+  findExistingPane(sessionFile: string | null): Promise<{ paneId: string; tabId: string } | null>;
+}
+
+export function createSpawner(h: SpawnerHost): Spawner {
+  const tabMutex = new Semaphore(1);
+  const readyTimeoutMs = runtimePolicy.readinessTimeoutMs;
+
+  async function liveTabs(): Promise<Array<{ tabName: string; tabId: string }>> {
+    try {
+      const ws = h.env?.workspaceId ?? '';
+      return (await h.client.tabList())
+        .filter((t) => !ws || t.workspaceId === ws)
+        .map((t) => ({ tabName: t.label, tabId: t.tabId }));
+    } catch {
+      return [];
+    }
+  }
+
+  function launchLine(resumeFile?: string | null, roleModel?: string | null, approve = false): string {
+    return buildLaunchLine(buildLaunchParts(h.runtime, { resumeFile, roleModel, approve }));
+  }
+
+  async function approveFor(cwd: string, masterCwd: string): Promise<boolean> {
+    if (isPathUnder(cwd, masterCwd)) return true;
+    const zone = classifyWorktreeZone({ cwd, masterCwd, worktrees: await h.git.listWorktrees(masterCwd) });
+    return zone.zone === 'worktree';
+  }
+
+  async function waitSubReady(cwd: string, paneId: string): Promise<boolean> {
+    return pingUntilReady(pipeNameCandidates(cwd, paneId), readyTimeoutMs);
+  }
+
+  async function spawnPaneInTaskTab(
+    placement: { desiredTab?: string | null; description: string; zone?: WorktreeZone },
+    cwd: string,
+    envOver: Record<string, string>,
+    launch: string,
+  ): Promise<{ tabId: string; paneId: string; tabName: string }> {
+    const release = await tabMutex.acquire();
+    try {
+      const allPanes = await h.client.listPanes();
+      const mainTabId = allPanes.find((p) => p.paneId === h.env?.paneId)?.tabId
+        ?? (h.env?.tabId ? h.env.tabId : null);
+      let plan: TabPlacementPlan = planTabPlacement({
+        desiredTab: placement.desiredTab,
+        description: placement.description,
+        knownTabs: await liveTabs(),
+        zone: placement.zone,
+        mainTabId,
+      });
+      if (plan.mode === 'append' && plan.tabId) {
+        const exclude = new Set(
+          allPanes.filter((p) => p.tabId === plan.tabId && p.agentStatus === 'unknown').map((p) => p.paneId),
+        );
+        let pick: { targetPaneId: string; direction: 'right' | 'down' } | null = null;
+        try {
+          const snapshot = await h.client.exportLayout({ tabId: plan.tabId });
+          const tree = snapshot?.root ? parseShapeTree(snapshot.root) : null;
+          if (tree) pick = pickGridSplit(tree, { exclude });
+        } catch { /* layout export failure → legacy anchor split */ }
+        const anchorPaneId = pick?.targetPaneId
+          ?? allPanes.find((p) => p.tabId === plan.tabId && p.agentStatus !== 'unknown')?.paneId
+          ?? allPanes.find((p) => p.tabId === plan.tabId)?.paneId;
+        if (anchorPaneId) {
+          const paneId = await h.client.splitPane({
+            direction: pick?.direction ?? 'down',
+            cwd,
+            env: envOver,
+            targetPaneId: anchorPaneId,
+          });
+          await h.client.sendPaneText(paneId, launch);
+          return { tabId: plan.tabId, paneId, tabName: plan.tabName };
+        }
+        plan = { mode: 'new', tabName: plan.tabName, tabId: null };
+      }
+      const created = await h.client.createTab({
+        workspaceId: h.env?.workspaceId ?? '',
+        label: plan.tabName,
+        cwd,
+        env: envOver,
+      });
+      await h.client.sendPaneText(created.paneId, launch);
+      return { tabId: created.tabId, paneId: created.paneId, tabName: plan.tabName };
+    } finally {
+      release();
+    }
+  }
+
+  async function findExistingPane(sessionFile: string | null): Promise<{ paneId: string; tabId: string } | null> {
+    if (!sessionFile) return null;
+    try {
+      const agents = await h.client.listAgents();
+      const match = agents.find((a) => a.session === sessionFile && a.status !== 'unknown');
+      if (!match) return null;
+      const panes = await h.client.listPanes();
+      const pane = panes.find((p) => p.paneId === match.paneId);
+      return pane ? { paneId: match.paneId, tabId: pane.tabId } : null;
+    } catch {
+      return null;
+    }
+  }
+
+  return { spawnPaneInTaskTab, launchLine, approveFor, waitSubReady, liveTabs, findExistingPane };
+}

package/src/terminal-core.ts

@@ -1,47 +1,53 @@
-/**
- * M14 常驻交互终端纯核心（D71 / T1–T6，2026-08-18）。
- *
- * 六工具的判定逻辑全部在此（无 pi/herdr 依赖 → 可单测）：
- *  - 注册表：terminal_id 稳定（term-<n>）、上限、幂等关闭；
- *  - T6 检测：send 文本校验（拒 ANSI/控制字符）、signal 白名单、
- *    全屏 TUI（alternate screen 序列）识别；
- *  - 读增量：环形缓冲语义（append / reset / none）+ 有界输出；
- *  - T3 readiness：PS1 尾匹配 + 静默期两档（超时兜底在 adapter）；
- *  - 会话汇总：stale pane 检测（跨重启边界注记）；
- *  - 持久化：custom 条目 last-wins（与 subs 注册表同构）。
- *
- * 后端映射（adapter = index.ts + herdr-client）：
- *  open=pane.split 常驻 shell / send=pane.send_text+\r /
- *  read=pane.read(recent, strip_ansi:false)+本地 strip /
- *  signal=pane.send_keys / close=pane.close。
- */
+/** Why: Preserve the established compatibility and safety behavior (D71, M14, T1–T6, T3, T6). */
 import { basename } from 'node:path';
 
-/* ── 常量（v1 默认；env 可调点在 adapter 读） ───────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export const TERMINALS_CUSTOM_TYPE = 'pi-herdr.terminals';
 export const MAX_TERMINALS = 8;
 export const READ_MAX_CHARS = 8000;
-/** 读返回的硬截断长度（含截断标记自身的预算）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export const READ_HARD_CAP_CHARS = 200;
 export const READINESS_TIMEOUT_MS = 30_000;
 export const SILENCE_IDLE_MS = 2000;
-/** T3 PS1 尾匹配：PowerShell `>` / POSIX `$` `#` / Nushell `❯` 结尾（允许尾空白）。 */
+/** POSIX / PowerShell / Nushell prompt tail. Why: herdr waitForOutput and local classify must share one pattern. */
 export const PROMPT_TAIL_RE = /[$>#❯]\s*$/;
-/** T6 signal 白名单（Herdr key-combo 字符串；ctrl+c 中断 / ctrl+d EOF / ctrl+z 挂起 / esc / enter）。 */
+
+export interface PromptStrategy {
+  /** herdr waitForOutput regex source. */
+  readonly waitPattern: string;
+  readonly tailRe: RegExp;
+}
+
+export const POSIX_PROMPT: PromptStrategy = {
+  waitPattern: '[$>#❯]\\s*$',
+  tailRe: PROMPT_TAIL_RE,
+};
+
+/** cmd.exe / PowerShell: `>` still matches POSIX; this also accepts `PS C:\\>` without a trailing `$`. */
+export const POWERSHELL_PROMPT: PromptStrategy = {
+  waitPattern: '(PS [^\\n>]+|>)\\s*$',
+  tailRe: /(PS [^\n>]+|>)\s*$/,
+};
+
+/** `PIER_TERMINAL_PROMPT=powershell` selects the Windows strategy; default stays POSIX so existing panes do not flip. */
+export function promptStrategyFor(env: NodeJS.ProcessEnv = process.env): PromptStrategy {
+  return env.PIER_TERMINAL_PROMPT === 'powershell' ? POWERSHELL_PROMPT : POSIX_PROMPT;
+}
+/** Why: Preserve the established compatibility and safety behavior (T6). */
 export const SIGNAL_KEYS = ['ctrl+c', 'ctrl+d', 'ctrl+z', 'esc', 'enter'] as const;
 export type SignalKey = (typeof SIGNAL_KEYS)[number];
 
 const FULLSCREEN_SEQUENCES = [
-  '\x1b[?1049h', // 进入 alternate screen（xterm）
-  '\x1b[?47h', // 老式进入 alternate screen
-  '\x1b[2J\x1b[H', // 清屏 + 光标归位（vim/less 常见模式）
+  '\x1b[?1049h', // Why: Preserve the established compatibility and safety behavior.
+  '\x1b[?47h', // Why: Preserve the established compatibility and safety behavior.
+  '\x1b[2J\x1b[H', // Why: Preserve the established compatibility and safety behavior.
 ] as const;
 
 export const RESET_MARKER = '…[buffer reset — earlier output scrolled away or cleared]…';
 export const TRUNCATE_MARKER = '…[truncated]…';
 
-/* ── 类型 ─────────────────────────────────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export interface TerminalEntry {
   terminalId: string;
@@ -53,7 +59,7 @@ export interface TerminalEntry {
   lastActivityAt: number;
   status: 'open' | 'closed';
   closedAt: number | null;
-  /** pane.read 游标：revision（展示）+ 稳定区长度 + 尾段锚 + 缓冲尾探测器（增量判定用）。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   readRevision: number | null;
   readLen: number;
   readTail: string;
@@ -65,7 +71,7 @@ export interface TerminalsRegistry {
   terminals: TerminalEntry[];
 }
 
-/* ── 注册表 ───────────────────────────────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export function nextTerminalId(existingIds: readonly string[]): string {
   let max = 0;
@@ -111,7 +117,7 @@ export function registerTerminal(
   return { ok: true, entries: [...entries, entry], entry };
 }
 
-/** 幂等关闭（closedAt 不被二次覆盖）；不存在的 id 原样返回。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function closeTerminal(
   entries: readonly TerminalEntry[],
   terminalId: string,
@@ -126,12 +132,12 @@ export function closeTerminal(
   };
 }
 
-/** 活跃（open）终端的 paneId 集合——GC 豁免判据（D71）。 */
+/** Why: Preserve the established compatibility and safety behavior (D71). */
 export function activeTerminalPaneIds(entries: readonly TerminalEntry[]): Set<string> {
   return new Set(entries.filter((e) => e.status === 'open').map((e) => e.paneId));
 }
 
-/* ── T6：send 文本校验 / signal 白名单 ───────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior (T6). */
 
 export function validateSendText(text: string): { ok: true; text: string } | { ok: false; error: string } {
   if (text.includes('\x1b')) {
@@ -140,7 +146,7 @@ export function validateSendText(text: string): { ok: true; text: string } | { o
       error: 'unsupported input: ANSI escape sequences cannot be sent as text; use terminal_signal for control keys, or plain commands only',
     };
   }
-  // 允许 \t；拒绝其余 C0 控制字符（\r\n 由发送方统一补 Enter，先剥尾部）
+  // Why: Preserve the established compatibility and safety behavior (C0).
   const stripped = text.replace(/[\r\n]+$/, '');
   const bad = stripped.match(/[\x00-\x08\x0b-\x1f\x7f]/);
   if (bad) {
@@ -163,7 +169,7 @@ export function validateSignal(key: string): { ok: true; key: SignalKey } | { ok
   return { ok: true, key: k };
 }
 
-/* ── T6：全屏 TUI 检测 + ANSI 剥离 ───────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior (T6). */
 
 export function detectFullscreenTUI(raw: string): { detected: boolean; sequence: string | null } {
   for (const seq of FULLSCREEN_SEQUENCES) {
@@ -174,21 +180,21 @@ export function detectFullscreenTUI(raw: string): { detected: boolean; sequence:
 
 export function stripAnsi(raw: string): string {
   return raw
-    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '') // CSI 序列
-    .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, '') // OSC 序列
-    .replace(/\x1b[@-Z\\-_]/g, '') // 其余两字符转义
-    .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ''); // 残余控制字符
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '') // Why: Preserve the established compatibility and safety behavior.
+    .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, '') // Why: Preserve the established compatibility and safety behavior.
+    .replace(/\x1b[@-Z\\-_]/g, '') // Why: Preserve the established compatibility and safety behavior.
+    .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ''); // Why: Preserve the established compatibility and safety behavior.
 }
 
-/* ── 读增量（环形缓冲语义） ───────────────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export interface ReadCursor {
   revision: number;
-  /** 已消费长度（落在最后完整行边界：lastIndexOf('\n')+1；活动行不占）。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   len: number;
-  /** 连续性锚：稳定区尾段（≤64 字符；与下次读按 trimEnd 比较——活动行行尾 \n 会变空格，实测）。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   tail: string;
-  /** 无变化探测器：上次整个缓冲的尾段（trimEnd；相同 → none）。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   eoTail: string;
 }
 
@@ -196,19 +202,14 @@ export interface ReadIncrement {
   mode: 'none' | 'append' | 'reset';
   text: string;
   cursor: ReadCursor;
-  /** 达到硬上限被截断（调用方应提示分页）。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   hardCapped: boolean;
 }
 
-/** 游标指纹长度（tail 采样上限）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 const CURSOR_TAIL_CHARS = 64;
 
-/**
- * 实测（M14 live）两条屏幕缓冲语义，决定了本实现：
- *  1) pane.read 的 revision 不随输出增长（恒 0）→ 变化探测用 eoTail，不用 revision；
- *  2) `recent` 是屏幕重建而非追加日志：活动行行尾 \n 在续写时变空格
- *     （"PS>x\n" → "PS>x echo"）→ 连续性锚按 trimEnd 比较，len 落在最后完整行边界。
- */
+/** Why: Preserve the established compatibility and safety behavior (M14). */
 export function computeIncrement(
   prev: ReadCursor | null,
   next: { text: string; revision: number },
@@ -233,7 +234,7 @@ export function computeIncrement(
     const bounded = boundText(suffix, maxChars);
     return { mode: 'append', text: bounded.text, cursor, hardCapped: bounded.capped };
   }
-  // 首读（prev=null）= 有界全量；缓冲回卷/清屏 = 有界全量 + reset 标记
+  // Why: Preserve the established compatibility and safety behavior.
   const bounded = boundText(next.text, maxChars);
   const text = prev ? `${RESET_MARKER}\n${bounded.text}` : bounded.text;
   return { mode: 'reset', text, cursor, hardCapped: bounded.capped };
@@ -244,21 +245,22 @@ function boundText(text: string, maxChars: number): { text: string; capped: bool
   return { text: `${text.slice(text.length - maxChars)}\n${TRUNCATE_MARKER}`, capped: true };
 }
 
-/* ── T3 readiness（两档 + busy；超时兜底在 adapter） ─────────────── */
+/** Why: Preserve the established compatibility and safety behavior (T3). */
 
 export type ReadinessTier = 'prompt' | 'silent' | 'busy';
 
 export function classifyReadiness(
   rawOrStripped: string,
-  opts: { silentMs: number; silenceThresholdMs?: number },
+  opts: { silentMs: number; silenceThresholdMs?: number; prompt?: PromptStrategy },
 ): ReadinessTier {
   const tail = rawOrStripped.trimEnd();
-  if (tail.length > 0 && PROMPT_TAIL_RE.test(tail)) return 'prompt';
+  const re = opts.prompt?.tailRe ?? PROMPT_TAIL_RE;
+  if (tail.length > 0 && re.test(tail)) return 'prompt';
   if (opts.silentMs >= (opts.silenceThresholdMs ?? SILENCE_IDLE_MS)) return 'silent';
   return 'busy';
 }
 
-/* ── 会话汇总（T6 跨重启边界） ───────────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior (T6). */
 
 export interface TerminalSummary {
   terminalId: string;
@@ -288,7 +290,7 @@ export function summarizeSessions(
   return { terminals, stalePaneIds };
 }
 
-/* ── 持久化（custom 条目 last-wins，与 subs 同构） ────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export interface BranchEntryLike3 {
   type?: string;

package/src/todo-core.ts

@@ -1,9 +1,4 @@
-/**
- * todo 纯逻辑：校验 / 折叠 / M10 增量（D34–D43）。
- *
- * 全部无副作用、无 pi API 依赖 → 可单测（node --test 直接跑 TS）。
- * 语义 = DESIGN.md §5.1.1 + §15：全量替换（last-wins），五态 + blocker + phase。
- */
+/** Why: Preserve the established compatibility and safety behavior (D34–D43, M10). */
 import {
   TODO_DETAILS_KEY,
   TODO_STATUSES,
@@ -17,13 +12,13 @@ import { countTodos } from './vocab.ts';
 
 export type { TodoItem, TodoSnapshot, TodoStatus, TodoCounts };
 
-/** D43：phase 名长度上限。 */
+/** Why: Preserve the established compatibility and safety behavior (D43). */
 export const PHASE_MAX_LEN = 30;
 
-/** D38：人类编辑 custom 条目类型（/todos done/drop/rm 写回权威的通道）。 */
+/** Why: Preserve the established compatibility and safety behavior (D38). */
 export const TODO_EDIT_CUSTOM_TYPE = 'pi-herdr.todo-edit';
 
-/** 人类编辑操作（D38）：done=completed、drop=abandoned、rm=移除、unblock=blocked→pending（M17）。 */
+/** Why: Preserve the established compatibility and safety behavior (D38, M17). */
 export type TodoEditOp = 'done' | 'drop' | 'rm' | 'unblock';
 
 export interface TodoEdit {
@@ -43,16 +38,7 @@ export interface TodoValidationResult {
   error?: string;
 }
 
-/**
- * 校验一次 todo_write 的入参并规范化为条目数组（D34/D43 扩展）。
- * 规则：
- *  - todos 必须是数组（空数组合法 = 清空列表）；
- *  - 每条允许键 = content/status/blocker/phase，不允许其他键；
- *  - content 非空且全局唯一；status ∈ 五态；
- *  - blocker 仅 status==='blocked' 时允许（非空字符串），其他状态携带即拒绝；
- *  - phase 可选：非空、≤30 字符；
- *  - allowParallelInProgress=false 时，至多一条 in_progress（B2 严格模式的第一道闸）。
- */
+/** Why: Preserve the established compatibility and safety behavior (B2, D34, D43). */
 export function validateTodos(
   todos: unknown,
   allowParallelInProgress = true,
@@ -93,9 +79,9 @@ export function validateTodos(
     const item: TodoItem = { content, status: status as TodoStatus };
     if ('blocker' in entry) {
       const blocker = entry.blocker;
-      // 容忍归一（用户实证修复）：Optional 字段用空串/null 填充是常见模型行为
-      //（grok 实测 9 连拒死循环）；status 是权威——非 blocked 态的 blocker 一律视为
-      // 缺省丢弃（无论是否有值），空值同样丢弃。仅类型畸形仍硬拒。
+      // Why: Preserve the established compatibility and safety behavior.
+      // Why: Preserve the established compatibility and safety behavior.
+      // Why: Preserve the established compatibility and safety behavior.
       if (blocker != null && typeof blocker !== 'string') {
         return { ok: false, error: 'invalid todo: `blocker` must be a non-empty string' };
       }
@@ -111,7 +97,7 @@ export function validateTodos(
       if (phase != null && typeof phase !== 'string') {
         return { ok: false, error: `invalid todo: \`phase\` must be a non-empty string ≤ ${PHASE_MAX_LEN} chars` };
       }
-      // 空串/纯空白 = 缺省（实证循环里 phase:"" 同样是被掩盖的雷）；超长是真实约束仍硬拒
+      // Why: Preserve the established compatibility and safety behavior.
       if (typeof phase === 'string') {
         if (phase.length > PHASE_MAX_LEN) {
           return { ok: false, error: `invalid todo: \`phase\` must be a non-empty string ≤ ${PHASE_MAX_LEN} chars` };
@@ -133,13 +119,7 @@ export function validateTodos(
   return { ok: true, items };
 }
 
-/**
- * D42 严格模式归一化（OMP normalizeInProgressTask 语义，按 pane 角色自动推导）：
- *  - 多余 in_progress（列表顺序第二条起）退回 pending；
- *  - 无 in_progress 且有 pending → 晋升列表顺序第一条 pending；
- *  - blocked/abandoned 不参与晋升。
- * 返回新数组（不改入参）。
- */
+/** Why: Preserve the established compatibility and safety behavior (D42). */
 export function normalizeStrict(items: readonly TodoItem[]): TodoItem[] {
   if (items.length === 0) return [];
   const out = items.map((it) => ({ ...it }));
@@ -157,7 +137,7 @@ export function normalizeStrict(items: readonly TodoItem[]): TodoItem[] {
   return out;
 }
 
-/** D35：逐项全等比较（content/status/blocker/phase），用于 no-op 检测。 */
+/** Why: Preserve the established compatibility and safety behavior (D35). */
 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++) {
@@ -168,7 +148,7 @@ export function listsEqual(a: readonly TodoItem[], b: readonly TodoItem[]): bool
   return true;
 }
 
-/** D36：本轮新变为 completed 的 content 列表（prev → next）。 */
+/** Why: Preserve the established compatibility and safety behavior (D36). */
 export function completionTransitions(prev: readonly TodoItem[], next: readonly TodoItem[]): string[] {
   const prevMap = new Map(prev.map((it) => [it.content, it.status]));
   const out: string[] = [];
@@ -178,7 +158,7 @@ export function completionTransitions(prev: readonly TodoItem[], next: readonly
   return out;
 }
 
-/** D37：上轮 completed、本轮退回 pending/in_progress 的 content 列表（软警告用）。 */
+/** Why: Preserve the established compatibility and safety behavior (D37). */
 export function revertedCompleted(prev: readonly TodoItem[], next: readonly TodoItem[]): string[] {
   const nextMap = new Map(next.map((it) => [it.content, it.status]));
   const out: string[] = [];
@@ -190,15 +170,15 @@ export function revertedCompleted(prev: readonly TodoItem[], next: readonly Todo
   return out;
 }
 
-/** 构造持久化快照（version 字段让消费方在未来形状变化时丢弃陈旧数据）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function makeSnapshot(items: TodoItem[]): TodoSnapshot {
   return { version: 1, items };
 }
 
 export interface BranchEntryLike {
-  /** pi 会话条目：type 为 'message' 的消息条目或 'custom' 的自定义条目。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   type?: string;
-  /** 会话 JSONL 顶层时间戳（ISO 字符串或 epoch ms；重建 lastWriteAt 用）。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   timestamp?: unknown;
   message?: {
     role?: string;
@@ -209,13 +189,7 @@ export interface BranchEntryLike {
   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。
- */
+/** Why: Preserve the established compatibility and safety behavior (D37, D38, M17). */
 export function applyTodoEdits(items: readonly TodoItem[], edits: readonly TodoEdit[]): TodoItem[] {
   let out = items.map((it) => ({ ...it }));
   for (const edit of edits) {
@@ -266,15 +240,10 @@ function extractEditPayload(data: unknown): TodoEditPayload | 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（人类编辑）。
- * 分支正确性 = 沿分支路径顺序折叠。
- */
+/** Why: Preserve the established compatibility and safety behavior (D38). */
 export interface FoldedTodos {
   items: TodoItem[];
-  /** 产生该列表的最后一个条目时间戳（epoch ms）；条目无时间戳 → null。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   writtenAt: number | null;
 }
 
@@ -288,13 +257,7 @@ function entryTimestamp(entry: BranchEntryLike): number | null {
   return null;
 }
 
-/**
- * 从 pi 会话分支条目里折叠出最新 todo 列表（D38 双源）：
- *  - toolResult(todo_write) → 快照替换（last-wins）；
- *  - custom(pi-herdr.todo-edit) → 在当前列表上应用 edits（人类编辑）。
- * 分支正确性 = 沿分支路径顺序折叠。writtenAt = 最后一次触碰该列表的条目时间戳
- * （无时间戳的旧条目 → null，陈旧度判定保守判 fresh）。
- */
+/** Why: Preserve the established compatibility and safety behavior (D38). */
 export function foldLatestTodosMeta(entries: readonly BranchEntryLike[]): FoldedTodos | null {
   let found: TodoItem[] | null = null;
   let writtenAt: number | null = null;
@@ -319,7 +282,7 @@ export function foldLatestTodosMeta(entries: readonly BranchEntryLike[]): Folded
   return found ? { items: found, writtenAt } : null;
 }
 
-/** foldLatestTodosMeta 的条目-only 视图（兼容既有调用方）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function foldLatestTodos(entries: readonly BranchEntryLike[]): TodoItem[] | null {
   return foldLatestTodosMeta(entries)?.items ?? null;
 }
@@ -333,7 +296,7 @@ export function extractSnapshotFromDetails(details: unknown): TodoSnapshot | nul
   return { version: 1, items: snap.items as TodoItem[] };
 }
 
-/** D38：模糊匹配（精确 → 前缀 → 子串），返回候选 content 列表（多候选 = 歧义）。 */
+/** Why: Preserve the established compatibility and safety behavior (D38). */
 export function fuzzyFind(items: readonly TodoItem[], query: string): string[] {
   const q = query.trim();
   if (!q) return [];
@@ -346,10 +309,10 @@ export function fuzzyFind(items: readonly TodoItem[], query: string): string[] {
   return substr.map((it) => it.content);
 }
 
-/** D39：有界视图选择——先丢 completed、再截 open；两端都超额时保最新（尾部切片）。 */
+/** Why: Preserve the established compatibility and safety behavior (D39). */
 export interface BoundedView {
   visible: TodoItem[];
-  /** 被隐藏的数量按状态计数（completed 单独计，其余合并）。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   hiddenCompleted: number;
   hiddenOpen: number;
 }
@@ -360,8 +323,8 @@ export function boundedView(items: readonly TodoItem[], budget: number): Bounded
   }
   const completed = items.filter((it) => it.status === 'completed');
   const open = items.filter((it) => it.status !== 'completed');
-  // 修正（用户实证）：widget 是头部可见窗口——超预算必须隐最老（丢头部），保最新可见；
-  // 旧实现 slice(0, budget) 保最老，最新任务永远落在窗口外。
+  // Why: Preserve the established compatibility and safety behavior.
+  // Why: Preserve the established compatibility and safety behavior.
   const visible = open.length > budget ? open.slice(-budget) : open;
   const hiddenOpen = open.length - visible.length;
   let hiddenCompleted = completed.length;
@@ -374,7 +337,7 @@ export function boundedView(items: readonly TodoItem[], budget: number): Bounded
   return { visible: final, hiddenCompleted, hiddenOpen };
 }
 
-/** 当前 in_progress 中的第一条（上报 agent 状态时作为 message，供侧边栏显示"正在做什么"）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function currentActivity(items: TodoItem[]): string | null {
   return items.find((it) => it.status === 'in_progress')?.content ?? null;
 }