pi-pier 0.1.4 → 0.2.0

package/src/core/terminal.ts

@@ -1,13 +1,10 @@
 /**
- * 档1 core/terminal（M14 六工具迁 loader entry —— D78 挂载树 / D81 三分法）。
+ * M14 terminal loader entry for the D78 mount tree and D81 responsibility split.
  *
- * 形态：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 为纯逻辑层照旧。
+ * Keeping this as a Cordis loader plugin makes the terminal surface hot-swappable. Services
+ * provide the D79 tombstone-aware pi surface, herdr client/environment, and the state slot
+ * used by index GC. Avoiding an index.ts import preserves an acyclic dependency graph, while
+ * terminal-core remains independently testable pure logic.
  */
 import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
@@ -24,6 +21,7 @@ import {
   detectFullscreenTUI,
   foldTerminalsRegistry,
   makeTerminalsRegistry,
+  promptStrategyFor,
   registerTerminal,
   stripAnsi,
   summarizeSessions,
@@ -34,11 +32,11 @@ import {
 } from '../terminal-core.ts';
 
 export interface TerminalStateSlot {
-  /** index 的 GC 豁免查询（活跃终端 pane 不回收）。 */
+  /** Lets index GC preserve panes that host active terminals. */
   activePaneIds: () => Set<string>;
 }
 
-export interface TerminalDeps {
+interface TerminalDeps {
   client: HerdrClientLike;
   env: { paneId: string; tabId: string } | null;
   state: TerminalStateSlot;
@@ -50,13 +48,12 @@ export default function terminalPlugin(ctx: Context): void {
   const pi = surface.raw as {
     appendEntry?: (customType: string, data: unknown) => void;
   };
-  // 模块 key = 本文件（hmr/reload 的 filename 与 ledger.disposeKey 规范化互比）
+  // Keying the surface by this file lets HMR tombstone and replace exactly this registration.
   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）。 */
+  /* ── M14 resident terminal tools (D71 / T1–T6) ────────────────────
+   * Dedicated herdr panes preserve shell state without reusing the pi TUI pane, and active
+   * terminal panes remain exempt from index GC. Workers omit this master-side entry. */
 
   let terminals: TerminalEntry[] = [];
 
@@ -64,7 +61,7 @@ export default function terminalPlugin(ctx: Context): void {
     try {
       pi.appendEntry?.(TERMINALS_CUSTOM_TYPE, makeTerminalsRegistry(terminals));
     } catch {
-      /* 持久化尽力而为 */
+      /* Persistence is best-effort because terminal operation must not depend on session logging. */
     }
   }
 
@@ -74,7 +71,7 @@ export default function terminalPlugin(ctx: Context): void {
         ?.sessionManager?.getBranch?.() ?? [];
       terminals = foldTerminalsRegistry(entries as Parameters<typeof foldTerminalsRegistry>[0]);
     } catch {
-      /* 重建失败不影响主流程 */
+      /* A malformed snapshot must not block the live terminal surface. */
     }
   }
 
@@ -88,7 +85,7 @@ export default function terminalPlugin(ctx: Context): void {
     persistTerminals();
   }
 
-  // GC 豁免槽回填（index gcPass 消费）
+  // Expose active panes so index GC does not collect resident terminal shells.
   state.activePaneIds = () => activeTerminalPaneIds(terminals);
 
   scoped.on('session_start', async (_event: unknown, eventCtx: unknown) => {
@@ -119,7 +116,7 @@ export default function terminalPlugin(ctx: Context): void {
       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
+        paneId: env.paneId, // Reserve a valid id until split returns the terminal pane.
         tabId: env.tabId,
         cwd,
         createdAt: Date.now(),
@@ -134,17 +131,17 @@ export default function terminalPlugin(ctx: Context): void {
       r.entry.paneId = paneId;
       terminals = r.entries;
       persistTerminals();
-      // T3 readiness：PS1 尾匹配（server 端等待）；超时 → 本地兜底再判一次
+      const prompt = promptStrategyFor();
       let readiness: 'prompt' | 'silent' | 'busy' = 'busy';
       try {
-        const matched = await client.waitForOutput(paneId, { type: 'regex', value: '[$>#❯]\\s*$' }, READINESS_TIMEOUT_MS);
+        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 });
+          readiness = classifyReadiness(stripAnsi(read.text), { silentMs: 0, prompt });
         }
       } catch {
-        /* readiness 尽力而为 */
+        /* Readiness is advisory, so probe failures still leave a usable terminal. */
       }
       const text = [
         `terminal ${r.entry.terminalId} open (pane ${paneId})`,
@@ -204,7 +201,7 @@ export default function terminalPlugin(ctx: Context): void {
         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
+        // 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);
@@ -228,7 +225,7 @@ export default function terminalPlugin(ctx: Context): void {
       } catch (e) {
         return errText(`read failed (pane may be closed): ${(e as Error).message}`);
       }
-      // T6 检测点1：全屏 TUI（alternate screen）——在 raw 上识别
+      // 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);
@@ -310,7 +307,7 @@ export default function terminalPlugin(ctx: Context): void {
         try {
           await client.closePane(entry.paneId);
         } catch {
-          /* pane 已消失（人关/随 tab 关）→ 直接补记 */
+          /* 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;
@@ -332,10 +329,10 @@ export default function terminalPlugin(ctx: Context): void {
       try {
         livePaneIds = (await client.listPanes()).map((p) => p.paneId);
       } catch {
-        /* 查询失败：全部按未知（不误标 closed）——live 集为空只影响 stale 判定 */
+        /* Treat a failed query as unknown rather than closed, because an empty live set only affects stale detection. */
       }
       const s = summarizeSessions(terminals, livePaneIds);
-      // T6 检测点3：pane 消失 → 补记 closed（跨重启边界：不复活，提示持久化）
+      // 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)

package/src/core/todo.ts

@@ -1,15 +1,11 @@
 /**
- * 档1 core/todo（todo 族迁 loader entry —— D78 挂载树 / D81 融合核心）。
+ * D78/D81 todo loader entry.
  *
- * 形态：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 命令（查看/编辑）+ TUI widget（widgetLines/
- * renderWidget）+ 读钩（before_agent_start planTodoReadHook，
- * 轮次计数器内聚）。reconcile / 镜像 / reportAgent 仍在 index（session 状态层）。
+ * A Cordis plugin keeps the master surface hot-swappable while allowing workers to mount the
+ * one-shot subset directly. Injected services preserve the D79 registration boundary and keep
+ * session-owned todo state in index. This module owns the tool, command, widget, and read hook;
+ * reconciliation, mirroring, and agent reporting stay with the session state layer to avoid a
+ * dependency cycle.
  */
 import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
@@ -32,14 +28,14 @@ import {
 } from '../todo-core.ts';
 
 export interface TodoUiSlot {
-  /** index 的 session_start/session_tree 生命周期调用（plugin 回填）。 */
+  /** Lets index lifecycle events render through the currently mounted plugin. */
   renderWidget: (ctx: unknown) => void;
 }
 
-export interface TodoDeps {
+interface TodoDeps {
   todos: TodosService;
   allowParallelInProgress: boolean;
-  /** 软上限提示（不硬拒）。 */
+  /** Warn above this size without rejecting otherwise valid plans. */
   maxItems: number;
   mirrorTodos: () => void;
   appendEntry: (customType: string, data: unknown) => void;
@@ -51,7 +47,7 @@ const TOOL_DESCRIPTION = [
   '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.',
+  'Before stopping, reconcile open entries: anything waiting on a human (decision, approval, or an ops action you cannot perform) must be marked blocked with a blocker note — never left pending, and never executed just to clear the list; finished or obsolete entries must be completed or removed.',
   '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(' ');
@@ -64,10 +60,10 @@ const TODO_MARKS: Record<TodoStatus, string> = {
   abandoned: '✗',
 };
 
-/** pi TUI widget 硬上限（interactive-mode MAX_WIDGET_LINES=10，头部截断；我们自己控制在限内）。 */
+/** Stay within pi interactive mode's ten-line widget cap instead of relying on head truncation. */
 export const WIDGET_MAX_LINES = 10;
 
-/** 分组渲染（phase 头 + 条目行；不设预算，widget 与 /todos 共用）。 */
+/** 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) {
@@ -88,18 +84,15 @@ function renderGroups(items: readonly TodoItem[]): string[] {
 }
 
 /**
- * widget 行（活动锚定窗口，用户实证二修）：
- *  - 全局预算 = WIDGET_MAX_LINES（含摘要行与 +N 行）；
- *  - 窗口锚定第一条 in_progress：可见的条目是它前后的连续区段（正在做的
- *    上下文——前因后果可见），不再是固定头部/尾部（旧实现超窗时只剩尾部，
- *    正在执行的条目滚出视窗，01a03c0d 实证"显示最后几条，不管当前执行到哪"）；
- *  - 无 in_progress → 锚定最后一条 open；全完成 → 尾部切片（刚完成的可见）；
- *  - +N 行指路 /todos（全量视图）。
+ * 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
+ * completions. A +N line points to /todos when the full plan cannot fit. This fixes 01a03c0d,
+ * where active work scrolled out while only the final entries remained visible.
  */
 export function widgetLines(items: readonly TodoItem[], opts?: { archivedAgeMs?: number | null }): string[] {
   if (items.length === 0) return [];
   const c = countTodos(items);
-  // 反冻结：归档列表不逐条渲染，两行说明 + 指路 /todos（死计划不再占满视窗）。
+  // 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)}`,
@@ -107,8 +100,7 @@ export function widgetLines(items: readonly TodoItem[], opts?: { archivedAgeMs?:
     ];
   }
 
-  // 条目预算 = 总预算 - 摘要行 -（隐藏时的）+N 行。phase 头也占行——按渲染行数
-  // 迭代收缩：锚定窗口切片 → 超行则两端各收一格（保锚点），直到装得下。
+  // 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 kept = items.slice(start, end);
@@ -122,9 +114,8 @@ export function widgetLines(items: readonly TodoItem[], opts?: { archivedAgeMs?:
 }
 
 /**
- * 活动锚定窗口：锚点 = 第一条 in_progress（无则最后一条 open；全完成 → 尾部）。
- * 以渲染行数（含 phase 头）为预算，从锚点贪心扩张（尾部优先——后续工作先
- * 可见），装不下即停；锚点条目永远在窗内。
+ * 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];
@@ -133,7 +124,7 @@ function anchorRange(items: readonly TodoItem[], renderBudget: number): [number,
     ? 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];
@@ -155,7 +146,7 @@ function anchorRange(items: readonly TodoItem[], renderBudget: number): [number,
     } else {
       break;
     }
-    growTail = !growTail; // 严格交替：锚点前因与后果均衡可见（用户实证诉求）
+    growTail = !growTail; // Alternate sides so both context and upcoming work remain visible.
   }
   return [start, end];
 }
@@ -166,17 +157,17 @@ export default function todoPlugin(ctx: Context): void {
     ctx.get('pi-herdr.todo-deps') as TodoDeps;
   const scoped = surface.forModule(import.meta.url);
 
-  /** 归档年龄（非归档 → null）；widget / /todos 共用。 */
+  /** Share one archive-age decision between the widget and /todos. */
   function archivedAgeMs(now = Date.now()): number | null {
     return todos.lastWriteAt != null && isArchived(todos.items, todos.lastWriteAt, now)
       ? now - todos.lastWriteAt
       : null;
   }
 
-  /** 事件 ctx 里的 widget UI（有则 setWidget；守卫后具名使用，不做行内断言）。 */
+  /** Name the guarded event UI once so callers do not repeat unsafe inline assertions. */
   function widgetUi(eventCtx: unknown): { setWidget?: (id: string, lines: string[]) => void } | undefined {
     if (eventCtx === null || typeof eventCtx !== 'object' || !('ui' in eventCtx)) return undefined;
-    const ui = (eventCtx as { ui: unknown }).ui; // 'ui' in 已守卫
+    const ui = (eventCtx as { ui: unknown }).ui; // Safe after the property guard above.
     return ui !== null && typeof ui === 'object'
       ? (ui as { setWidget?: (id: string, lines: string[]) => void })
       : undefined;
@@ -186,23 +177,23 @@ export default function todoPlugin(ctx: Context): void {
     try {
       widgetUi(eventCtx)?.setWidget?.('todos', widgetLines(todos.items, { archivedAgeMs: archivedAgeMs() }));
     } catch {
-      /* 无 widget 能力的 pi 版本静默降级 */
+      /* Older pi versions may omit widget support without disabling todo tracking. */
     }
   }
 
-  // 槽回填：index 的 session_start/session_tree 调用
+  // Let index lifecycle hooks call the current plugin implementation.
   state.renderWidget = renderWidget;
 
-  /* ── 读钩（轮次计数器内聚；D39 提示注入 + 反冻结 stale-core） ── */
+  /* ── Read hook: D39 reminders and stale-plan thawing ────────────── */
   let todoReadTurn = 0;
   let lastEmptyGuardTurn: number | null = null;
-  // 反冻结状态：距上次写入轮数 / stale 警告计数与节奏 / 归档翻转检测
+  // Track writes and notice cadence so a stale plan cannot remain frozen indefinitely.
   let lastWriteTurn: number | null = null;
   let staleNotices = 0;
   let lastStaleGuardTurn: number | null = null;
   let lastArchivedMirror = false;
 
-  // 任何真实变更（todo_write / 人类编辑 / 对账 / 分支重建）都终结当前停滞期
+  // Any real edit ends the current stale period because the plan is active again.
   todos.on('todo.updated', () => {
     lastWriteTurn = todoReadTurn;
     staleNotices = 0;
@@ -223,20 +214,20 @@ export default function todoPlugin(ctx: Context): void {
       staleNotices += 1;
       lastStaleGuardTurn = todoReadTurn;
     }
-    // 空守卫 / 归档通知 / R2 重写窗口共用注入节奏（archived=true 的 stale 窗口同享，
-    // 否则终态通知会在窗口后紧跟一拍挤掉宽限）。
+    // Share cadence across empty, archive, and R2 rewrite notices so adjacent notices do not
+    // consume the grace window.
     if (plan.inject && (plan.effect === 'empty-guard' || plan.archived)) {
       lastEmptyGuardTurn = todoReadTurn;
     }
-    // R1：归档通知注入即清空——明细早已不再注入，保留死列表只会挡住空守卫的
-    // before-stopping 驱动（01a03c0d：归档后 2h 多步工作零跟踪）。rm 全量落
-    // JSONL，重启 rebuild 同样折叠得空表；历史明细仍在会话文件里。
+    // R1 clears archived entries after notice because retaining dead items suppresses the empty
+    // guard that restored tracking after the 01a03c0d two-hour gap. Persist removals for replay;
+    // the session log still retains history.
     if (plan.inject && plan.effect === 'archive-notice' && plan.clearArchived && todos.items.length > 0) {
       const edits = todos.items.map((it) => ({ op: 'rm' as const, content: it.content }));
       try {
         appendEntry(TODO_EDIT_CUSTOM_TYPE, { version: 1, edits, ts: Date.now() });
       } catch {
-        /* 尽力而为（内存清空照常） */
+        /* Persistence is best-effort because the in-memory clear must still proceed. */
       }
       todos.replace([]);
     }
@@ -251,11 +242,14 @@ export default function todoPlugin(ctx: Context): void {
     };
   });
 
-  /* ── 工具：todo_write ── */
+  /* ── todo_write tool ───────────────────────────────────────────── */
   scoped.registerTool({
     name: TODO_TOOL_NAME,
     label: 'Todo',
     description: TOOL_DESCRIPTION,
+    promptGuidelines: [
+      'Before stopping with open todo_write entries, reconcile them: entries waiting on a human decision, approval, or ops action must be marked blocked with a blocker note — never left pending, and never executed just to clear the list.',
+    ],
     parameters: Type.Object({
       todos: Type.Array(
         Type.Object(
@@ -286,7 +280,7 @@ export default function todoPlugin(ctx: Context): void {
           details: {},
         };
       }
-      const strictMode = todos.config.strict; // D75 阶段 2：策略进 service config
+      const strictMode = todos.config.strict; // D75 phase 2 keeps policy in the service config.
       let next = result.items!;
       const strictNotes: string[] = [];
       if (strictMode) {
@@ -300,11 +294,11 @@ export default function todoPlugin(ctx: Context): void {
         if (promoted) strictNotes.push(`auto-promoted to in_progress: ${promoted}`);
         next = strict;
       }
-      // D35：no-op（与当前列表全等 → 不落盘不镜像）
+      // D35 avoids persistence and mirroring when the authoritative list is unchanged.
       if (listsEqual(todos.items, next)) {
         return { content: [{ type: 'text', text: 'No change: todo list already matches.' }], details: {} };
       }
-      // D36/D37：过渡信号与回退警告
+      // D36/D37 surface completion transitions and regressions to the caller.
       const completed = completionTransitions(todos.items, next);
       const reverted = revertedCompleted(todos.items, next);
       todos.replace(next);
@@ -329,7 +323,7 @@ export default function todoPlugin(ctx: Context): void {
     },
   });
 
-  /* ── 命令：/todos（查看 + done/drop/rm/unblock 人类编辑，D38）── */
+  /* ── /todos command: D38 human viewing and edits ───────────────── */
   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) => {
@@ -362,11 +356,11 @@ export default function todoPlugin(ctx: Context): void {
           ui?.notify?.(`no change: "${content}" is already in that state`, 'info');
           return;
         }
-        // D38：人类编辑写回权威（custom 条目，重启后分支回放生效）
+        // D38 persists human edits so branch replay rebuilds the same authoritative state.
         try {
           appendEntry(TODO_EDIT_CUSTOM_TYPE, { version: 1, edits: [edit], ts: Date.now() });
         } catch {
-          /* 尽力而为 */
+          /* Persistence failure must not discard the live human edit. */
         }
         mirrorTodos();
         renderWidget(eventCtx);
@@ -377,7 +371,7 @@ export default function todoPlugin(ctx: Context): void {
         ui?.notify?.(`"${content}" ${verb}`, 'info');
         return;
       }
-      // 全量视图（/todos 不受 widget 行预算限制——"看整个列表"的正式入口）
+      // /todos is the unbounded view because the widget intentionally prioritizes active context.
       const body = renderGroups(todos.items);
       if (body.length === 0) {
         ui?.notify?.('todo list is empty', 'info');

package/src/gc-core.ts

@@ -1,15 +1,15 @@
 /**
- * 任务 tab GC 决策（D29 的判定规则抽成纯函数；M22 取消 resident 豁免）。
- * 无副作用、无 pi/herdr API 依赖 → 可单测。
+ * Task-tab GC decisions (D29 rules as a pure function; M22 dropped resident exemption).
+ * No I/O, no pi/herdr — unit-testable.
  */
 export type GcEntryKind = string;
 export type GcEntryStatus = 'running' | 'settled' | 'consumed' | 'closed';
 
 export interface GcEntryLike {
-  /** 'task' 或 role 名；旧值 short/resident 只作标签，不参与判定。 */
+  /** 'task' or a role name; legacy short/resident is a label only. */
   kind: GcEntryKind;
   status: GcEntryStatus;
-  /** 消费时间（GC 宽限期判据；closed 条目保留原值）。 */
+  /** Consume timestamp (GC grace); closed rows keep the original value. */
   consumedAt?: number | null;
 }
 
@@ -18,12 +18,12 @@ function isFinished(status: GcEntryStatus): boolean {
 }
 
 /**
- * D29 / M22：任务 tab 是否该关（全部条件同时成立）：
- *  - 含 ≥1 个工作 pane（主 tab 无委派条目 → 永不关）；
- *  - 全部工作 pane 已 settled/consumed/closed（kind 不再豁免）；
- *  - 宽限期已过（时间制 TTL；ttlMs=0 表示不自动关，由调用方把关）；
- *  - 无 blocked pane（人类闸门豁免）；
- *  - 其余 pane 全部 idle/done/unknown（非工作 pane 允许 unknown）。
+ * Close a task tab only when every condition holds:
+ *  - ≥1 work pane (the main tab with no delegated entries never closes);
+ *  - every work pane is settled/consumed/closed (kind is not an exemption);
+ *  - grace TTL elapsed (`ttlMs=0` means never auto-close);
+ *  - no blocked pane (human-gate exemption);
+ *  - remaining panes are idle/done/unknown (non-work panes may be unknown).
  */
 export function shouldCloseTaskTab(opts: {
   entries: readonly GcEntryLike[];
@@ -40,17 +40,17 @@ export function shouldCloseTaskTab(opts: {
 }
 
 /**
- * pane 级回收判定（孤儿/兼容路径，v1.2 语义）：
- *  - 消费于上一轮之前（宽限：结算通知那一轮人可看、模型可用）；
- *  - herdr 显式状态 idle/done（unknown/working/blocked → 下轮重试，#943 容错）；
- *  - pane 已消失（status undefined）→ 补记 closed（返回 true 由调用方处理）。
+ * Pane-level collection (orphan / compat path):
+ *  - consumed before the previous turn (grace so the settlement notice is still visible);
+ *  - herdr status idle/done (unknown/working/blocked retry next turn);
+ *  - missing pane (status undefined) → record closed (caller handles the write).
  */
 export function shouldClosePane(opts: {
   consumedAt: number | null;
   herdrStatus: string | undefined;
   prevTurnStart: number;
 }): boolean {
-  if (opts.herdrStatus === undefined) return true; // pane 没了 → 补记 closed
+  if (opts.herdrStatus === undefined) return true; // pane gone → record closed
   if (opts.herdrStatus !== 'idle' && opts.herdrStatus !== 'done') return false;
   return (opts.consumedAt ?? 0) > 0 && opts.consumedAt! < opts.prevTurnStart;
 }

package/src/git-adapter.ts

@@ -0,0 +1,104 @@
+import { execFile as nodeExecFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { runtimePolicy } from './runtime-policy.ts'
+
+const execFile = promisify(nodeExecFile)
+
+export interface GitResult {
+  readonly stdout: string
+  readonly stderr: string
+}
+
+export interface GitError extends Error {
+  readonly code?: string | number
+  readonly stdout?: string
+  readonly stderr?: string
+}
+
+/**
+ * Injectable execFile used by NodeGitAdapter.
+ * Why: tests drive git without a real process.
+ */
+export type GitExecFile = (
+  file: string,
+  args: readonly string[],
+  options: { timeout: number; encoding: 'utf8' },
+) => Promise<{ stdout: string; stderr: string }>
+
+/**
+ * Minimal Git adapter for worktree and status operations.
+ *
+ * Why: Centralizes platform-specific git executable resolution, timeout policy,
+ * and error normalization; makes tests independent of real git processes.
+ */
+export interface GitAdapter {
+  /**
+   * List worktrees in porcelain format.
+   * Returns stdout containing worktree entries.
+   */
+  listWorktrees(cwd: string): Promise<GitResult>
+
+  /**
+   * Get status of worktree in short format.
+   * Returns stdout containing status entries.
+   */
+  status(cwd: string): Promise<GitResult>
+
+  /**
+   * Run an arbitrary git command in `cwd` (`git -C <cwd> ...args`).
+   * Throws a GitError on failure/timeout — callers that want "null on error"
+   * (isolate sweep, placement) catch at the call site.
+   */
+  run(cwd: string, args: readonly string[]): Promise<GitResult>
+}
+export class NodeGitAdapter implements GitAdapter {
+  private readonly gitExecutable: string
+  private readonly timeoutMs: number
+  private readonly exec: GitExecFile
+
+  constructor(
+    gitExecutable: string = 'git',
+    timeoutMs: number = runtimePolicy.gitTimeoutMs,
+    exec: GitExecFile = execFile as unknown as GitExecFile,
+  ) {
+    this.gitExecutable = gitExecutable
+    this.timeoutMs = timeoutMs
+    this.exec = exec
+  }
+
+  listWorktrees(cwd: string): Promise<GitResult> {
+    return this.run(cwd, ['worktree', 'list', '--porcelain'])
+  }
+
+  status(cwd: string): Promise<GitResult> {
+    return this.run(cwd, ['status', '--short'])
+  }
+
+  async run(cwd: string, args: readonly string[]): Promise<GitResult> {
+    try {
+      const { stdout, stderr } = await this.exec(
+        this.gitExecutable,
+        ['-C', cwd, ...args],
+        { timeout: this.timeoutMs, encoding: 'utf8' },
+      )
+      return { stdout, stderr }
+    } catch (err) {
+      throw this.normalizeError(err, args[0] ?? 'command')
+    }
+  }
+
+  private normalizeError(err: unknown, operation: string): GitError {
+    if (err instanceof Error) {
+      const gitError = err as GitError
+      gitError.message = `Git ${operation} failed: ${gitError.message}`
+      return gitError
+    }
+    return new Error(`Git ${operation} failed: ${String(err)}`) as GitError
+  }
+}
+
+/**
+ * Default production git adapter.
+ * Tests should inject fake implementations or a fake exec.
+ */
+export const defaultGitAdapter = new NodeGitAdapter()