pi-pier 0.1.0

package/src/subagent-core.ts

@@ -0,0 +1,310 @@
+/**
+ * subagent 纯逻辑：子 pane 命令构造、并发信号量、注册表、进度回调。
+ * 无副作用、无 pi/herdr API 依赖 → 可单测。
+ *
+ * v1.1（DESIGN.md §12，方案 C）：子 pane 统一为交互式 pi TUI。
+ *  - 启动：常驻 shell 里 `node cli.js -e <本扩展>`（Windows 经 powershell 包裹、
+ *    POSIX 直启；无 prompt 参数，prompt 经扩展管道注入），herdr 自动检测 +
+ *    本扩展上报状态；
+ *  - 并发上限 4（D10）：信号量压制并行 spawn；
+ *  - 结果通道 = 子会话 JSONL（session-tail.ts），不再解析 pane 文本；
+ *  - 软锁：仅在 herdr agent_status ∈ {idle} 时注入（index.ts 的状态门）。
+ */
+import { normalizeEntryKind } from './history-store.ts';
+
+export interface SubagentSpec {
+  description: string;
+  prompt: string;
+}
+
+/** PowerShell 单引号转义（''）。 */
+export function psQuote(s: string): string {
+  return `'${String(s).replace(/'/g, "''")}'`;
+}
+
+/** POSIX sh 单引号转义（'\''）。 */
+export function shQuote(s: string): string {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * 子代理启动命令行（注入子 pane 的 shell，经 pane.send_text + CR 提交）。
+ * 片段 = 裸 argv 词（如 ['pi', '--session', '<file>']）；win32 输出 PowerShell
+ * 调用语法（`&` 引导 + `''` 转义），其余输出 POSIX sh 语法（单引号 + `'\''` 转义）。
+ */
+export function buildLaunchLine(parts: readonly string[], platform: NodeJS.Platform = process.platform): string {
+  const quoted = platform === 'win32'
+    ? parts.map((s) => psQuote(s))
+    : parts.map((s) => shQuote(s));
+  return (platform === 'win32' ? '& ' : '') + quoted.join(' ');
+}
+
+/** 计数信号量：并发上限内的 acquire 立即执行，超出排队（FIFO）。 */
+export class Semaphore {
+  private active = 0;
+  private queue: Array<() => void> = [];
+  private readonly cap: number;
+
+  constructor(cap: number) {
+    if (cap < 1) throw new Error('semaphore cap must be >= 1');
+    this.cap = cap;
+  }
+
+  get activeCount(): number {
+    return this.active;
+  }
+
+  acquire(): Promise<() => void> {
+    if (this.active < this.cap) {
+      this.active++;
+      return Promise.resolve(this.release.bind(this));
+    }
+    return new Promise((resolve) => {
+      this.queue.push(() => {
+        this.active++;
+        resolve(this.release.bind(this));
+      });
+    });
+  }
+
+  private release(): void {
+    this.active--;
+    const next = this.queue.shift();
+    if (next) next();
+  }
+}
+
+export interface SubagentOutcome {
+  kind: 'completed' | 'timeout' | 'no-output' | 'blocked' | 'spawn-failed';
+  /** 最终文本（completed 时为子代理最终回答；timeout/blocked 时为部分输出）。 */
+  text: string;
+}
+
+/** 把提取结果规范为工具返回文本。 */
+export function formatSubagentResult(outcome: SubagentOutcome, description: string): string {
+  switch (outcome.kind) {
+    case 'completed': {
+      const text = outcome.text;
+      return text ? text : 'Subagent finished but produced no output.';
+    }
+    case 'timeout':
+      return `Error: subagent "${description}" timed out. Partial output:\n${outcome.text || '(none)'}`;
+    case 'blocked':
+      return `Subagent "${description}" is blocked in its pane and needs a human decision. Partial output:\n${outcome.text || '(none)'}`;
+    case 'no-output':
+      return `Error: subagent "${description}" produced no readable output.`;
+    case 'spawn-failed':
+      return `Error: failed to spawn subagent "${description}": ${outcome.text}`;
+  }
+}
+
+/* ── 子代理注册表（custom 条目持久化） ────────────────────────────── */
+
+export const SUBS_CUSTOM_TYPE = 'pi-herdr.subs';
+
+export interface SubEntry {
+  taskId: string;
+  /** 'task' 或 role 名；旧 short/resident 读盘归一为 task，不参与 GC。 */
+  kind: string;
+  paneId: string;
+  tabId: string;
+  /** v1.3：任务 tab 名（D25/D26；tab.rename 后可能漂移，仅为显示/复活参考）。 */
+  tabName: string;
+  cwd: string;
+  description: string;
+  background: boolean;
+  status: 'running' | 'settled' | 'consumed' | 'closed';
+  /** 消费时间（GC 宽限期判据）。 */
+  consumedAt?: number | null;
+  sessionFile: string | null;
+  launchCommand: string[];
+  createdAt: number;
+  revivedFrom?: string | null;
+  /** D94：用户是否接管控制（暂停 master 管理）。 */
+  userTakeover?: boolean;
+  /** D94：接管检测时间（ms）；settled 后进入观察期开始计时。 */
+  observationStartedAt?: number | null;
+  /** D94：上次 agent 状态（用于检测 idle→working 的用户介入）。 */
+  lastAgentStatus?: string | null;
+}
+
+export interface SubsRegistry {
+  version: 2;
+  subs: SubEntry[];
+}
+
+export function makeRegistry(subs: SubEntry[] = []): SubsRegistry {
+  return { version: 2, subs };
+}
+
+/**
+ * 从会话分支条目折叠注册表（last-wins，与 todo 折叠同构）。
+ * custom 条目形状（session-format 实测）：{type:'custom', customType, data}。
+ * 兼容 v1 条目（缺字段按默认补齐：taskId=paneId、kind=task、tabId=''、launchCommand=[]）。
+ */
+export function foldSubsRegistry(entries: readonly BranchEntryLike2[]): SubsRegistry {
+  let found = makeRegistry();
+  for (const entry of entries) {
+    if (entry.type !== 'custom' || entry.customType !== SUBS_CUSTOM_TYPE) continue;
+    const data = entry.data as {
+      subs?: Array<Partial<SubEntry> & { paneId: string }>;
+    } | undefined;
+    if (!data || !Array.isArray(data.subs)) continue;
+    const subs: SubEntry[] = data.subs
+      .filter((s) => typeof s?.paneId === 'string')
+      .map((s) => ({
+        taskId: typeof s.taskId === 'string' ? s.taskId : s.paneId,
+        kind: normalizeEntryKind(typeof s.kind === 'string' ? s.kind : undefined),
+        paneId: s.paneId,
+        tabId: typeof s.tabId === 'string' ? s.tabId : '',
+        tabName: typeof s.tabName === 'string' ? s.tabName : '',
+        cwd: typeof s.cwd === 'string' ? s.cwd : '',
+        description: typeof s.description === 'string' ? s.description : '',
+        background: s.background === true,
+        status: s.status === 'closed' ? 'closed' : s.status === 'consumed' ? 'consumed' : s.status === 'settled' ? 'settled' : 'running',
+        consumedAt: typeof s.consumedAt === 'number' ? s.consumedAt : null,
+        sessionFile: typeof s.sessionFile === 'string' ? s.sessionFile : null,
+        launchCommand: Array.isArray(s.launchCommand) ? s.launchCommand : [],
+        createdAt: typeof s.createdAt === 'number' ? s.createdAt : 0,
+        revivedFrom: typeof s.revivedFrom === 'string' ? s.revivedFrom : null,
+        userTakeover: s.userTakeover === true ? true : undefined,
+        observationStartedAt: typeof s.observationStartedAt === 'number' ? s.observationStartedAt : null,
+        lastAgentStatus: typeof s.lastAgentStatus === 'string' ? s.lastAgentStatus : null,
+      }));
+    found = { version: 2, subs };
+  }
+  return found;
+}
+
+export interface BranchEntryLike2 {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+}
+
+/* ── 工具进度回调 ─────────────────────────────────────────────────── */
+
+export interface ProgressUpdate {
+  content: Array<{ type: 'text'; text: string }>;
+  details: Record<string, never>;
+}
+
+/**
+ * 构造 onUpdate 的合法负载。
+ *
+ * ⚠️ pi 0.84.2 实测：AgentToolUpdateCallback 期待 AgentToolResult（{content, details}），
+ * 传字符串会让交互式 TUI 在 getTextOutput 处崩溃（undefined.filter）并整个退出 pi。
+ * 所有进度回调必须经本助手构造。
+ */
+export function makeProgressUpdate(msg: string): ProgressUpdate {
+  return { content: [{ type: 'text', text: msg }], details: {} };
+}
+
+/* ── v1.3 任务 tab 放置（D25/D26 纯逻辑，可单测） ─────────────────── */
+
+export const TAB_NAME_MAX = 20;
+
+/** tab 名规范化：折叠空白、截断 ≤20 字符；空 → 'task'。 */
+export function tabNameForTask(description: string): string {
+  const cleaned = String(description ?? '').replace(/\s+/g, ' ').trim();
+  const truncated = cleaned.slice(0, TAB_NAME_MAX).trim();
+  return truncated || 'task';
+}
+
+/** 缺省放置撞名加序号后缀（-2、-3…），并保持总长 ≤20（D26：缺省永远开新 tab）。 */
+export function nextTaskTabName(base: string, existingNames: ReadonlySet<string>): string {
+  let name = base;
+  let n = 2;
+  while (existingNames.has(name)) {
+    const suffix = `-${n}`;
+    name = base.slice(0, TAB_NAME_MAX - suffix.length) + suffix;
+    n++;
+  }
+  return name;
+}
+
+export interface TabPlacementPlan {
+  /** append = 追加进既有 tab（锚 pane split）；new = 新命名 tab。 */
+  mode: 'append' | 'new';
+  tabName: string;
+  /** append 时的既有 tabId（须调用方再校验存活）；new 时为 null。 */
+  tabId: string | null;
+}
+
+/* ── D86：worktree 分组键（纯逻辑） ─────────────────────────────── */
+
+/** 路径包含判定（大小写不敏感 + 斜杠统一；cwd === wt 或 cwd 在 wt 之下）。D86 信任旗标也用它。 */
+export function isPathUnder(cwd: string, wt: string): boolean {
+  const n = (p: string) => p.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  const a = n(cwd);
+  const b = n(wt);
+  return a === b || a.startsWith(`${b}/`);
+}
+
+export interface WorktreeZone {
+  /** main = 主检出（split 进 main tab）；worktree = 命名 worktree tab；非 git/无关目录也兜底 main。 */
+  zone: 'main' | 'worktree';
+  /** zone=worktree 时的 tab 名（目录名原样，撞名后缀由 nextTaskTabName 处理）。 */
+  tabName: string | null;
+}
+
+/**
+ * D86 分类器：cwd 落在哪个 worktree 分组。
+ * `worktrees` = git porcelain 顺序（主检出在前，仅用于列表本身；归属判定按包含）；
+ * 非 git / 不属任何 worktree → main（「无新 worktree → 同 tab」的兜底）。
+ */
+export function classifyWorktreeZone(opts: {
+  cwd: string;
+  masterCwd: string;
+  worktrees: readonly string[];
+}): WorktreeZone {
+  for (const wt of opts.worktrees) {
+    if (!isPathUnder(opts.cwd, wt)) continue;
+    if (isPathUnder(opts.masterCwd, wt)) return { zone: 'main', tabName: null }; // 主检出 → main tab
+    const base = wt.replace(/\\/g, '/').split('/').filter(Boolean).pop() ?? 'worktree';
+    return { zone: 'worktree', tabName: base };
+  }
+  return { zone: 'main', tabName: null };
+}
+
+/**
+ * 放置决策（D26 显式层 + D86 缺省层）：
+ *  - 显式 `tab` 参数：规范名 → 已知 tab 同名则 append（用其 tabId），否则 new；
+ *  - 缺省（D86）：`zone` 给出分组——main → append 进 mainTabId；worktree →
+ *    join-or-create 该目录名 tab（已知同名 append，否则 new）。
+ * `knownTabs` = 调用时刻的存活 tab（label, id）。
+ */
+export function planTabPlacement(opts: {
+  desiredTab?: string | null;
+  description: string;
+  knownTabs: ReadonlyArray<{ tabName: string; tabId: string }>;
+  /** D86 缺省分组（classifyWorktreeZone 输出；不传 = 旧 description 派生路径，兼容用）。 */
+  zone?: WorktreeZone;
+  /** D86 main 分组的目标 tab（master 所在 tab）。 */
+  mainTabId?: string | null;
+}): TabPlacementPlan {
+  const known = new Map<string, string>();
+  for (const t of opts.knownTabs) if (t?.tabName && t?.tabId) known.set(t.tabName, t.tabId);
+  if (opts.desiredTab != null && String(opts.desiredTab).trim() !== '') {
+    const tabName = tabNameForTask(String(opts.desiredTab));
+    const tabId = known.get(tabName) ?? null;
+    return tabId ? { mode: 'append', tabName, tabId } : { mode: 'new', tabName, tabId: null };
+  }
+  const zone = opts.zone;
+  if (zone?.zone === 'main' && opts.mainTabId) {
+    // D86 R1：主检出 → split 进 main tab（锚 pane 由调用方选）
+    return { mode: 'append', tabName: 'main', tabId: opts.mainTabId };
+  }
+  if (zone?.zone === 'worktree' && zone.tabName) {
+    // D86 R1：worktree → join-or-create 目录名 tab（原样 label，大小写不敏感撞名 join）
+    const base = zone.tabName;
+    const existing = [...known.keys()].find((k) => k.toLowerCase() === base.toLowerCase());
+    if (existing) return { mode: 'append', tabName: existing, tabId: known.get(existing)! };
+    const tabName = nextTaskTabName(base, new Set(known.keys()));
+    return { mode: 'new', tabName, tabId: null };
+  }
+  // 兜底（无 zone 信息）：由 description 派生名 + 撞名加序号后缀 → 永远 new。
+  const base = tabNameForTask(opts.description);
+  const tabName = nextTaskTabName(base, new Set(known.keys()));
+  return { mode: 'new', tabName, tabId: null };
+}

package/src/subagent-scope.ts

@@ -0,0 +1,39 @@
+/**
+ * 档 0：master 进程内每个 subagent 一个 cordis fiber。
+ * pipe / poller / history 的清理走 ctx.effect，dispose LIFO。
+ * C3：worker 进程不引入本模块。
+ */
+import { Context } from '@deepseek-ai/cordis';
+
+export interface ScopeHooks {
+  onDispose?: () => void;
+}
+
+export function createSessionRoot(hooks: ScopeHooks = {}): Context {
+  const root = new Context();
+  if (hooks.onDispose) {
+    root.effect(() => () => { hooks.onDispose?.(); }, 'session-root');
+  }
+  return root;
+}
+
+export async function mountSubagentScope(
+  root: Context,
+  paneId: string,
+  hooks: ScopeHooks = {},
+) {
+  return root.plugin({
+    name: `subagent:${paneId}`,
+    apply(ctx: Context) {
+      ctx.effect(() => () => { hooks.onDispose?.(); }, `subagent:${paneId}`);
+    },
+  }, { paneId });
+}
+
+export async function disposeSessionRoot(root: Context): Promise<void> {
+  try {
+    await root.fiber.dispose();
+  } catch {
+    /* 二次 dispose 是 no-op */
+  }
+}

package/src/terminal-core.ts

@@ -0,0 +1,328 @@
+/**
+ * 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。
+ */
+import { basename } from 'node:path';
+
+/* ── 常量（v1 默认；env 可调点在 adapter 读） ───────────────────── */
+
+export const TERMINALS_CUSTOM_TYPE = 'pi-herdr.terminals';
+export const MAX_TERMINALS = 8;
+export const READ_MAX_CHARS = 8000;
+/** 读返回的硬截断长度（含截断标记自身的预算）。 */
+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 `❯` 结尾（允许尾空白）。 */
+export const PROMPT_TAIL_RE = /[$>#❯]\s*$/;
+/** T6 signal 白名单（Herdr key-combo 字符串；ctrl+c 中断 / ctrl+d EOF / ctrl+z 挂起 / esc / enter）。 */
+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 常见模式）
+] as const;
+
+export const RESET_MARKER = '…[buffer reset — earlier output scrolled away or cleared]…';
+export const TRUNCATE_MARKER = '…[truncated]…';
+
+/* ── 类型 ─────────────────────────────────────────────────────────── */
+
+export interface TerminalEntry {
+  terminalId: string;
+  paneId: string;
+  tabId: string;
+  cwd: string;
+  label: string | null;
+  createdAt: number;
+  lastActivityAt: number;
+  status: 'open' | 'closed';
+  closedAt: number | null;
+  /** pane.read 游标：revision（展示）+ 稳定区长度 + 尾段锚 + 缓冲尾探测器（增量判定用）。 */
+  readRevision: number | null;
+  readLen: number;
+  readTail: string;
+  readEoTail: string;
+}
+
+export interface TerminalsRegistry {
+  version: 1;
+  terminals: TerminalEntry[];
+}
+
+/* ── 注册表 ───────────────────────────────────────────────────────── */
+
+export function nextTerminalId(existingIds: readonly string[]): string {
+  let max = 0;
+  for (const id of existingIds) {
+    const m = /^term-(\d+)$/.exec(id);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return `term-${max + 1}`;
+}
+
+export function registerTerminal(
+  entries: readonly TerminalEntry[],
+  opts: {
+    paneId: string;
+    tabId: string;
+    cwd: string;
+    label?: string | null;
+    createdAt: number;
+  },
+): { ok: true; entries: TerminalEntry[]; entry: TerminalEntry } | { ok: false; error: string } {
+  const openCount = entries.filter((e) => e.status === 'open').length;
+  if (openCount >= MAX_TERMINALS) {
+    return {
+      ok: false,
+      error: `terminal limit reached (max ${MAX_TERMINALS} open terminals); close one with terminal_close before opening another`,
+    };
+  }
+  const entry: TerminalEntry = {
+    terminalId: nextTerminalId(entries.map((e) => e.terminalId)),
+    paneId: opts.paneId,
+    tabId: opts.tabId,
+    cwd: opts.cwd,
+    label: opts.label ?? (opts.cwd ? basename(opts.cwd.replace(/\\/g, '/')) || opts.cwd : null),
+    createdAt: opts.createdAt,
+    lastActivityAt: opts.createdAt,
+    status: 'open',
+    closedAt: null,
+    readRevision: null,
+    readLen: 0,
+    readTail: '',
+    readEoTail: '',
+  };
+  return { ok: true, entries: [...entries, entry], entry };
+}
+
+/** 幂等关闭（closedAt 不被二次覆盖）；不存在的 id 原样返回。 */
+export function closeTerminal(
+  entries: readonly TerminalEntry[],
+  terminalId: string,
+  now: number,
+): { entries: TerminalEntry[] } {
+  return {
+    entries: entries.map((e) =>
+      e.terminalId === terminalId && e.status === 'open'
+        ? { ...e, status: 'closed' as const, closedAt: now }
+        : e,
+    ),
+  };
+}
+
+/** 活跃（open）终端的 paneId 集合——GC 豁免判据（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 白名单 ───────────────────────────── */
+
+export function validateSendText(text: string): { ok: true; text: string } | { ok: false; error: string } {
+  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',
+    };
+  }
+  // 允许 \t；拒绝其余 C0 控制字符（\r\n 由发送方统一补 Enter，先剥尾部）
+  const stripped = text.replace(/[\r\n]+$/, '');
+  const bad = stripped.match(/[\x00-\x08\x0b-\x1f\x7f]/);
+  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.)`,
+    };
+  }
+  return { ok: true, text: stripped };
+}
+
+export function validateSignal(key: string): { ok: true; key: SignalKey } | { ok: false; error: string } {
+  const k = (SIGNAL_KEYS as readonly string[]).includes(key) ? (key as SignalKey) : null;
+  if (!k) {
+    return {
+      ok: false,
+      error: `unsupported signal "${key}"; allowed: ${SIGNAL_KEYS.join(', ')} (complex key sequences are outside the terminal seam — use herdr's native pane for interactive programs)`,
+    };
+  }
+  return { ok: true, key: k };
+}
+
+/* ── T6：全屏 TUI 检测 + ANSI 剥离 ───────────────────────────────── */
+
+export function detectFullscreenTUI(raw: string): { detected: boolean; sequence: string | null } {
+  for (const seq of FULLSCREEN_SEQUENCES) {
+    if (raw.includes(seq)) return { detected: true, sequence: seq };
+  }
+  return { detected: false, sequence: null };
+}
+
+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, ''); // 残余控制字符
+}
+
+/* ── 读增量（环形缓冲语义） ───────────────────────────────────────── */
+
+export interface ReadCursor {
+  revision: number;
+  /** 已消费长度（落在最后完整行边界：lastIndexOf('\n')+1；活动行不占）。 */
+  len: number;
+  /** 连续性锚：稳定区尾段（≤64 字符；与下次读按 trimEnd 比较——活动行行尾 \n 会变空格，实测）。 */
+  tail: string;
+  /** 无变化探测器：上次整个缓冲的尾段（trimEnd；相同 → none）。 */
+  eoTail: string;
+}
+
+export interface ReadIncrement {
+  mode: 'none' | 'append' | 'reset';
+  text: string;
+  cursor: ReadCursor;
+  /** 达到硬上限被截断（调用方应提示分页）。 */
+  hardCapped: boolean;
+}
+
+/** 游标指纹长度（tail 采样上限）。 */
+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 落在最后完整行边界。
+ */
+export function computeIncrement(
+  prev: ReadCursor | null,
+  next: { text: string; revision: number },
+  maxChars: number,
+): ReadIncrement {
+  const stableLen = next.text.lastIndexOf('\n') + 1;
+  const cursor: ReadCursor = {
+    revision: next.revision,
+    len: stableLen,
+    tail: next.text.slice(Math.max(0, stableLen - CURSOR_TAIL_CHARS), stableLen),
+    eoTail: next.text.slice(-CURSOR_TAIL_CHARS).trimEnd(),
+  };
+  if (prev && next.text.slice(-CURSOR_TAIL_CHARS).trimEnd() === prev.eoTail) {
+    return { mode: 'none', text: '', cursor: prev, hardCapped: false };
+  }
+  if (
+    prev &&
+    next.text.length >= prev.len &&
+    next.text.slice(Math.max(0, prev.len - prev.tail.length), prev.len).trimEnd() === prev.tail.trimEnd()
+  ) {
+    const suffix = next.text.slice(prev.len);
+    const bounded = boundText(suffix, maxChars);
+    return { mode: 'append', text: bounded.text, cursor, hardCapped: bounded.capped };
+  }
+  // 首读（prev=null）= 有界全量；缓冲回卷/清屏 = 有界全量 + reset 标记
+  const bounded = boundText(next.text, maxChars);
+  const text = prev ? `${RESET_MARKER}\n${bounded.text}` : bounded.text;
+  return { mode: 'reset', text, cursor, hardCapped: bounded.capped };
+}
+
+function boundText(text: string, maxChars: number): { text: string; capped: boolean } {
+  if (text.length <= maxChars) return { text, capped: false };
+  return { text: `${text.slice(text.length - maxChars)}\n${TRUNCATE_MARKER}`, capped: true };
+}
+
+/* ── T3 readiness（两档 + busy；超时兜底在 adapter） ─────────────── */
+
+export type ReadinessTier = 'prompt' | 'silent' | 'busy';
+
+export function classifyReadiness(
+  rawOrStripped: string,
+  opts: { silentMs: number; silenceThresholdMs?: number },
+): ReadinessTier {
+  const tail = rawOrStripped.trimEnd();
+  if (tail.length > 0 && PROMPT_TAIL_RE.test(tail)) return 'prompt';
+  if (opts.silentMs >= (opts.silenceThresholdMs ?? SILENCE_IDLE_MS)) return 'silent';
+  return 'busy';
+}
+
+/* ── 会话汇总（T6 跨重启边界） ───────────────────────────────────── */
+
+export interface TerminalSummary {
+  terminalId: string;
+  paneId: string;
+  cwd: string;
+  label: string | null;
+  status: 'open' | 'closed';
+  live: boolean;
+  lastActivityAt: number;
+}
+
+export function summarizeSessions(
+  entries: readonly TerminalEntry[],
+  livePaneIds: readonly string[],
+): { terminals: TerminalSummary[]; stalePaneIds: string[] } {
+  const live = new Set(livePaneIds);
+  const terminals: TerminalSummary[] = entries.map((e) => ({
+    terminalId: e.terminalId,
+    paneId: e.paneId,
+    cwd: e.cwd,
+    label: e.label,
+    status: e.status,
+    live: e.status === 'open' && live.has(e.paneId),
+    lastActivityAt: e.lastActivityAt,
+  }));
+  const stalePaneIds = terminals.filter((t) => t.status === 'open' && !t.live).map((t) => t.paneId);
+  return { terminals, stalePaneIds };
+}
+
+/* ── 持久化（custom 条目 last-wins，与 subs 同构） ────────────────── */
+
+export interface BranchEntryLike3 {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+}
+
+export function makeTerminalsRegistry(terminals: TerminalEntry[] = []): TerminalsRegistry {
+  return { version: 1, terminals };
+}
+
+export function foldTerminalsRegistry(entries: readonly BranchEntryLike3[]): TerminalEntry[] {
+  let found: TerminalEntry[] = [];
+  for (const entry of entries) {
+    if (entry.type !== 'custom' || entry.customType !== TERMINALS_CUSTOM_TYPE) continue;
+    const data = entry.data as { terminals?: Array<Partial<TerminalEntry> & { paneId: string }> } | undefined;
+    if (!data || !Array.isArray(data.terminals)) continue;
+    found = data.terminals
+      .filter((t) => typeof t?.paneId === 'string')
+      .map((t) => ({
+        terminalId: typeof t.terminalId === 'string' ? t.terminalId : `term-${t.paneId}`,
+        paneId: t.paneId,
+        tabId: typeof t.tabId === 'string' ? t.tabId : '',
+        cwd: typeof t.cwd === 'string' ? t.cwd : '',
+        label: typeof t.label === 'string' ? t.label : null,
+        createdAt: typeof t.createdAt === 'number' ? t.createdAt : 0,
+        lastActivityAt: typeof t.lastActivityAt === 'number' ? t.lastActivityAt : 0,
+        status: t.status === 'closed' ? ('closed' as const) : ('open' as const),
+        closedAt: typeof t.closedAt === 'number' ? t.closedAt : null,
+        readRevision: typeof t.readRevision === 'number' ? t.readRevision : null,
+        readLen: typeof t.readLen === 'number' ? t.readLen : 0,
+        readTail: typeof t.readTail === 'string' ? t.readTail : '',
+        readEoTail: typeof t.readEoTail === 'string' ? t.readEoTail : '',
+      }));
+  }
+  return found;
+}