pi-pier 0.1.5 → 0.2.0

package/src/role-manifest.ts

@@ -1,44 +1,43 @@
 /**
- * 档2 Week1：role manifest 类型 + 校验器（D76 v2；2026-08-18）。
+ * Layer 2 Week 1: role manifest types and validator (D76 v2; 2026-08-18).
  *
- * 契约镜像 `schemas/role-manifest.schema.json`（JSON Schema 文件是合同文档，
- * 运行时用零依赖手写校验——不引 ajv，worker 侧不背包袱）。
+ * Mirrors the contract in `schemas/role-manifest.schema.json` (the JSON Schema is the contract document;
+ * runtime validation is hand-written with zero dependencies so workers carry no ajv overhead).
  *
- * 严格契约：未知顶层键报 issue（防 "rulez" 类 typo 静默失效）；
- * 错误收集式（一次报全，便于修档案）。
+ * Strict contract: report unknown top-level keys to prevent typos such as "rulez" from silently failing;
+ * collect all errors in one pass so manifests can be repaired efficiently.
  */
 export type PermissionAction = 'allow' | 'ask' | 'deny';
 export type TodosMode = 'serial' | 'parallel';
-/** D82：未知工具姿态——可见性=信任关系（用户→master 凭 install；master→被委派凭镜像）。 */
+/** D82: stance for unknown tools—visibility is a trust relationship (user→master via install; master→delegated via mirror). */
 export type UnknownToolStance = 'allow' | 'deny';
 
 export interface RoleManifest {
   role: string;
-  /** 语义版本 x.y.z（档案演化追溯；P2）。 */
+  /** Semantic version x.y.z (for tracing manifest evolution; P2). */
   version: string;
   /**
-   * WS-D10：按角色路由模型——`provider/model` 形态（advisor = 高级别第三方判断）。
-   * 可省略 = 跟随进程默认（master/worker 不设）。spawn 时注入 `--provider/--model`。
+   * WS-D10: route models by role using `provider/model` (advisor delegates higher-level third-party judgment).
+   * Omitted means follow the process default (master/worker leave it unset); spawn injects `--provider/--model`.
    */
   model?: string;
   description?: string;
   manifest: {
-    /** 基线工具（非空，必含 todo_write + ask_user_question——协调工具）。 */
+    /** Baseline tools (non-empty; must include todo_write + ask_user_question for coordination). */
     tools: string[];
-    /** 三态权限；`*` 通配符默认；可省略 = `{"*":"allow"}`。 */
+    /** Three-state permissions; `*` supplies the default; omitted means `{"*":"allow"}`. */
     rules?: Record<string, PermissionAction>;
     /**
-     * D82 unknownTools：清单外工具的姿态（缺省 deny = 安全默认）。
-     * master/worker = allow（用户安装的扩展默认可见可用——install 即授予）；
-     * 自定义角色缺省 deny。与 rules 的 `*` 通配分属两轴：可见性 vs 强制力。
-     * 排除族（如 worker 的 subagent/terminal）须显式 deny 才能在 allow 姿态下持禁令。
+     * D82 unknownTools: stance for tools outside the manifest (default deny is the safe default).
+     * master/worker = allow (user-installed extensions are visible and usable by default—install grants access);
+     * custom roles default to deny. `*` in rules and this stance cover separate axes: visibility vs enforcement.
+     * Excluded families (such as worker's subagent/terminal) need explicit deny to remain blocked under allow.
      */
     unknownTools?: UnknownToolStance;
   };
   services?: {
     todos?: {
       mode?: TodosMode;
-      reminderLimit?: number;
     };
   };
 }
@@ -47,7 +46,7 @@ export type ValidateResult =
   | { ok: true; value: RoleManifest }
   | { ok: false; code: 'INVALID_ROLE_CONFIG'; issues: string[] };
 
-/** 所有角色必需的协调工具（C7 边界约束 1）。 */
+/** Coordination tools required by every role (C7 boundary constraint 1). */
 export const COORDINATION_TOOLS = ['todo_write', 'ask_user_question'] as const;
 
 const ROLE_NAME_RE = /^[a-z0-9-]+$/;
@@ -69,30 +68,30 @@ export function validateRoleManifest(input: unknown): ValidateResult {
     return { ok: false, code: 'INVALID_ROLE_CONFIG', issues: ['role 档案必须是 JSON 对象'] };
   }
 
-  /* ── 顶层键 ── */
+  /* ── Top-level keys ── */
   const KNOWN_TOP = new Set(['role', 'version', 'model', 'description', 'manifest', 'services']);
   for (const k of Object.keys(input)) {
     if (!KNOWN_TOP.has(k)) issues.push(`未知顶层键 "${k}"（契约外字段，检查拼写）`);
   }
 
-  /* ── role 名 ── */
+  /* ── role name ── */
   if (typeof input.role !== 'string' || !ROLE_NAME_RE.test(input.role)) {
     issues.push(`role 必须是 [a-z0-9-]+ 字符串，收到 ${JSON.stringify(input.role)}`);
   }
 
-  /* ── version（P2 semver） ── */
+  /* ── version (P2 semver) ── */
   if (typeof input.version !== 'string' || !SEMVER_RE.test(input.version)) {
     issues.push(`version 必须是 x.y.z 三段数字（如 1.0.0），收到 ${JSON.stringify(input.version)}`);
   }
 
-  /* ── model（WS-D10：provider/model 按角色路由；可选） ── */
+  /* ── model (WS-D10: provider/model role routing; optional) ── */
   if (input.model !== undefined) {
     if (typeof input.model !== 'string' || !/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(input.model)) {
       issues.push(`model 必须是 provider/model 形态（如 opencode-go/muse-spark-1.2-contributor），收到 ${JSON.stringify(input.model)}`);
     }
   }
 
-  /* ── description 可选 ── */
+  /* ── optional description ── */
   if (input.description !== undefined && typeof input.description !== 'string') {
     issues.push('description 必须是字符串');
   }
@@ -107,12 +106,12 @@ export function validateRoleManifest(input: unknown): ValidateResult {
       if (!KNOWN_MANIFEST.has(k)) issues.push(`manifest 内未知键 "${k}"`);
     }
 
-    // D82 unknownTools：enum 校验，缺省 = deny（安全默认）
+    // D82 unknownTools: enum validation; omitted means deny (safe default).
     if (m.unknownTools !== undefined && m.unknownTools !== 'allow' && m.unknownTools !== 'deny') {
       issues.push(`manifest.unknownTools 必须是 allow/deny，收到 ${JSON.stringify(m.unknownTools)}`);
     }
 
-    // tools：字符串数组、无重复、非空、含协调工具（空数组也要报缺协调工具）
+    // tools must be a unique, non-empty string array containing coordination tools; an empty array also reports the omissions.
     const tools = m.tools;
     if (!Array.isArray(tools) || !tools.every((t) => typeof t === 'string' && TOOL_KEY_RE.test(t))) {
       issues.push('manifest.tools 必须是非空字符串数组（工具名 [a-z0-9_-]）');
@@ -127,7 +126,7 @@ export function validateRoleManifest(input: unknown): ValidateResult {
       }
     }
 
-    // rules：三态值；键 = 工具名或 *
+    // rules accept three-state values; each key must be a tool name or *.
     if (m.rules !== undefined) {
       if (!isPlainObject(m.rules)) {
         issues.push('manifest.rules 必须是对象');
@@ -154,9 +153,6 @@ export function validateRoleManifest(input: unknown): ValidateResult {
         if (t.mode !== undefined && t.mode !== 'serial' && t.mode !== 'parallel') {
           issues.push(`services.todos.mode 必须是 serial/parallel，收到 ${JSON.stringify(t.mode)}`);
         }
-        if (t.reminderLimit !== undefined && !isPosInt(t.reminderLimit)) {
-          issues.push(`services.todos.reminderLimit 必须是正整数，收到 ${JSON.stringify(t.reminderLimit)}`);
-        }
       }
     }
   }

package/src/roles/master.json

@@ -1,6 +1,6 @@
 {
   "role": "master",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "主控角色（WS-D7 自应用；D83 镜像源）：自研核心全量（todos/协调/subagent 族/终端族）+ pi 内建检视执行 + web_search；D82 unknownTools=allow——用户安装的任意扩展默认可见可用（install 即授予）",
   "manifest": {
     "unknownTools": "allow",
@@ -16,6 +16,6 @@
     }
   },
   "services": {
-    "todos": { "mode": "parallel", "reminderLimit": 5 }
+    "todos": { "mode": "parallel" }
   }
 }

package/src/roles/worker-default.json

@@ -1,7 +1,7 @@
 {
   "role": "worker-default",
-  "version": "1.3.0",
-  "description": "默认worker角色（D83 继承制）：镜像 master.tools 减 subagent 族（禁嵌套）减 terminal 族（M14 资源归属）；排除族显式 deny——在 D82 unknownTools=allow 姿态下仍持禁令；todos serial/3",
+  "version": "1.3.1",
+  "description": "默认worker角色（D83 继承制）：镜像 master.tools 减 subagent 族（禁嵌套）减 terminal 族（M14 资源归属）；排除族显式 deny——在 D82 unknownTools=allow 姿态下仍持禁令；todos serial",
   "manifest": {
     "unknownTools": "allow",
     "tools": [
@@ -25,6 +25,6 @@
     }
   },
   "services": {
-    "todos": { "mode": "serial", "reminderLimit": 3 }
+    "todos": { "mode": "serial" }
   }
 }

package/src/runtime-policy.ts

@@ -0,0 +1,66 @@
+/**
+ * Centralized runtime policy and timeouts.
+ * 
+ * Why: Prevents drift between hardcoded literals and environment overrides;
+ * makes timing behavior explicit and testable.
+ */
+
+export interface RuntimePolicy {
+  /** Subagent overall timeout (ms) */
+  readonly subagentTimeoutMs: number
+  /** Subagent GC tick interval (ms) */
+  readonly gcTickMs: number
+  /** Poll interval for subagent state observation (ms) */
+  readonly pollIntervalMs: number
+  /** Stale check cadence (turns) */
+  readonly staleCadenceTurns: number
+  /** Settlement notice window / machine-inject grace / takeover idle (ms) */
+  readonly settlementWindowMs: number
+  /** Post-settle observation window before auto-consume (ms) */
+  readonly observationWindowMs: number
+  /** Foreground patience before background promotion (ms) */
+  readonly foregroundPatienceMs: number
+  /** Default session TTL (seconds) */
+  readonly sessionTtlSeconds: number
+  /** Terminal read maximum bytes */
+  readonly terminalReadMaxBytes: number
+  /** Git operation timeout (ms) */
+  readonly gitTimeoutMs: number
+  /** Subagent pane pipe readiness wait (ms) */
+  readonly readinessTimeoutMs: number
+}
+
+function parseEnvInt(key: string, defaultValue: number, min: number = 0): number {
+  const raw = process.env[key]
+  if (!raw) return defaultValue
+  
+  const parsed = Number.parseInt(raw, 10)
+  if (!Number.isFinite(parsed) || parsed < min) {
+    console.warn(`Invalid ${key}="${raw}", using default ${defaultValue}`)
+    return defaultValue
+  }
+  
+  return parsed
+}
+
+export function createRuntimePolicy(overrides?: Partial<RuntimePolicy>): RuntimePolicy {
+  return {
+    subagentTimeoutMs: overrides?.subagentTimeoutMs ?? parseEnvInt('PIER_SUBAGENT_TIMEOUT_MS', 600_000, 1000),
+    gcTickMs: overrides?.gcTickMs ?? parseEnvInt('PIER_GC_TICK_MS', 30_000, 1000),
+    pollIntervalMs: overrides?.pollIntervalMs ?? parseEnvInt('PIER_POLL_INTERVAL_MS', 30_000, 1000),
+    staleCadenceTurns: overrides?.staleCadenceTurns ?? parseEnvInt('PIER_STALE_CADENCE_TURNS', 3, 1),
+    settlementWindowMs: overrides?.settlementWindowMs ?? parseEnvInt('PIER_SETTLEMENT_WINDOW_MS', 60_000, 0),
+    observationWindowMs: overrides?.observationWindowMs ?? parseEnvInt('PIER_OBSERVATION_WINDOW_MS', 30_000, 0),
+    foregroundPatienceMs: overrides?.foregroundPatienceMs ?? parseEnvInt('PIER_FOREGROUND_PATIENCE_MS', 300_000, 0),
+    sessionTtlSeconds: overrides?.sessionTtlSeconds ?? parseEnvInt('PIER_SESSION_TTL_SECONDS', 600, 0),
+    terminalReadMaxBytes: overrides?.terminalReadMaxBytes ?? parseEnvInt('TERM_READ_MAX', 4096, 1),
+    gitTimeoutMs: overrides?.gitTimeoutMs ?? parseEnvInt('PIER_GIT_TIMEOUT_MS', 10_000, 1),
+    readinessTimeoutMs: overrides?.readinessTimeoutMs ?? parseEnvInt('PIER_READY_TIMEOUT_MS', 30_000, 1000),
+  }
+}
+
+/**
+ * Singleton runtime policy for production use.
+ * Tests should inject via createRuntimePolicy().
+ */
+export const runtimePolicy = createRuntimePolicy()

package/src/session-tail.ts

@@ -1,13 +1,17 @@
 /**
- * pi 会话 JSONL 尾部解析（纯函数库，v1.1 结果通道）。
+ * Tail parsing for pi session JSONL (pure library, v1.1 result channel).
  *
- * v1.1（DESIGN.md §12）起，子代理的结果不再从 pane 文本解析，而是读子代理的
- * 会话文件（pi 会话 JSONL，权威、机器精确、无回声污染/滚动盲区）。
- * 本模块只依赖 pi 会话格式（session-format 文档实测形状）：
- *   行 = {type, id, parentId, message:{role, content:[{type:'text',text}...], timestamp, stopReason}}
+ * Since v1.1 (DESIGN.md §12), child-agent results come from the child session file
+ * rather than pane text, keeping the authoritative machine-readable source free of
+ * echo contamination and scrollback blind spots. This module depends only on the
+ * empirically observed pi session format (session-format documentation):
+ *   line = {type, id, parentId, message:{role, content:[{type:'text',text}...], timestamp, stopReason}}
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { sessionDirCandidates, sessionDirName } from './storage-layout.ts';
+
+export { sessionDirName };
 
 export interface SessionMessageLike {
   role?: string;
@@ -21,8 +25,7 @@ export interface SessionEntryLike {
   message?: SessionMessageLike | unknown;
   [k: string]: unknown;
 }
-
-/** 容忍式逐行解析（损坏行/非 JSON 行跳过）。 */
+/** Parse line by line tolerantly, skipping malformed or non-JSON records. */
 export function parseSessionEntries(text: string): SessionEntryLike[] {
   const entries: SessionEntryLike[] = [];
   for (const line of (text ?? '').split(/\r?\n/)) {
@@ -32,7 +35,7 @@ export function parseSessionEntries(text: string): SessionEntryLike[] {
       const obj = JSON.parse(t);
       if (obj && typeof obj === 'object') entries.push(obj as SessionEntryLike);
     } catch {
-      /* 截断/损坏行跳过 */
+      /* Skip truncated or malformed records. */
     }
   }
   return entries;
@@ -58,10 +61,9 @@ function textOf(m: SessionMessageLike): string {
     .join('\n')
     .trim();
 }
-
 /**
- * 取最后一次"已定稿"的 assistant 文本（stopReason === 'stop'，排除 toolUse 中间态）。
- * sinceTs 用于过滤注入时间点之前的旧消息。
+ * Return the latest finalized assistant text (stopReason === 'stop'), excluding toolUse intermediates.
+ * sinceTs filters out messages that predate the injection point.
  */
 export function lastAssistantText(
   entries: readonly SessionEntryLike[],
@@ -78,8 +80,7 @@ export function lastAssistantText(
   }
   return best;
 }
-
-/** 会话是否出现注入时间点之后的 assistant 消息（任意 stopReason，探测活跃）。 */
+/** Return whether any assistant message occurs after the injection point, regardless of stopReason. */
 export function hasAssistantAfter(
   entries: readonly SessionEntryLike[],
   sinceTs: number,
@@ -89,10 +90,10 @@ export function hasAssistantAfter(
     return !!m && m.role === 'assistant' && (typeof m.timestamp === 'number' ? m.timestamp : 0) >= sinceTs;
   });
 }
-
 /**
- * 注入后是否存在"已发起但尚无结果"的 toolCall（工具执行中，如 ask_user_question
- * 等人类输入）→ 未真正结算（v1.3 M8 结算竞态修复）。并行调用按深度计数。
+ * Return whether an initiated toolCall still lacks a result after injection (for example,
+ * ask_user_question waiting on human input), meaning settlement has not actually completed
+ * (v1.3 M8 settlement-race fix). Parallel calls are tracked by depth.
  */
 export function hasPendingToolCall(entries: readonly SessionEntryLike[], sinceTs: number): boolean {
   let depth = 0;
@@ -112,29 +113,27 @@ export function hasPendingToolCall(entries: readonly SessionEntryLike[], sinceTs
   return depth > 0;
 }
 
-/** pi 会话目录名：cwd → `--F--herdr-pi--` 形态（实测命名约定）。 */
-export function sessionDirName(cwd: string): string {
-  const flat = cwd.replace(/[\\/]/g, '-').replace(/:/g, '-');
-  return `--${flat}--`;
-}
 
-/** cwd 会话目录下按 mtime 倒序取最新 limit 个会话文件（v1.3 M7 候选定位）。 */
+
+/** Newest `limit` session files under cwd's session dir (new encoding, then legacy). */
 export function listSessionFiles(cwd: string, agentDir: string, limit = 4): string[] {
-  const dir = path.join(agentDir, sessionDirName(cwd));
-  let names: string[];
-  try {
-    names = fs.readdirSync(dir);
-  } catch {
-    return [];
-  }
   const files: Array<{ file: string; mtime: number }> = [];
-  for (const name of names) {
-    if (!name.endsWith('.jsonl')) continue;
-    const full = path.join(dir, name);
+  for (const name of sessionDirCandidates(cwd)) {
+    const dir = path.join(agentDir, name);
+    let names: string[];
     try {
-      files.push({ file: full, mtime: fs.statSync(full).mtimeMs });
+      names = fs.readdirSync(dir);
     } catch {
-      /* 跳过消失文件 */
+      continue;
+    }
+    for (const fileName of names) {
+      if (!fileName.endsWith('.jsonl')) continue;
+      const full = path.join(dir, fileName);
+      try {
+        files.push({ file: full, mtime: fs.statSync(full).mtimeMs });
+      } catch {
+        /* vanished between readdir and stat */
+      }
     }
   }
   files.sort((a, b) => b.mtime - a.mtime);
@@ -142,20 +141,22 @@ export function listSessionFiles(cwd: string, agentDir: string, limit = 4): stri
 }
 
 /**
- * 按 session id 定位会话文件（文件名形如 `<ts>_<id>.jsonl`，pi 实测命名）。
- * 官方 herdr 集成上报 agent_session 为 kind 'id' 时用它还原路径。
+ * Locate a session file by id (`<ts>_<id>.jsonl`).
+ * Searches the new encoding dir first, then the legacy flattened dir.
  */
 export function sessionFileById(cwd: string, agentDir: string, id: string): string | null {
-  const dir = path.join(agentDir, sessionDirName(cwd));
   const suffix = `_${id}.jsonl`;
-  let names: string[];
-  try {
-    names = fs.readdirSync(dir);
-  } catch {
-    return null;
-  }
-  for (const name of names) {
-    if (name.endsWith(suffix)) return path.join(dir, name);
+  for (const name of sessionDirCandidates(cwd)) {
+    const dir = path.join(agentDir, name);
+    let names: string[];
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const fileName of names) {
+      if (fileName.endsWith(suffix)) return path.join(dir, fileName);
+    }
   }
   return null;
 }

package/src/settle-wake-core.ts

@@ -1,40 +1,41 @@
 /**
- * settled 唤醒决策纯核心（反唤醒风暴；session 01a03bf0 实证）。
+ * Pure core for the settled-wake decision (prevents wake storms; evidenced by session 01a03bf0).
  *
- * 实证链：ESC 中止 → agent_settled → D96「仍有后台 subagent」提醒
- * sendUserMessage(followUp)（空闲时必触发新 run）→ master 重启 → 用户再 ESC → …
- * 30 连 abort，ESC 永远打不断，Ctrl+C 杀进程才停。
- * 且自然 settle 也有自激励环：settle → 提醒 → 新 run → settle → 提醒……
+ * Evidence chain: ESC abort → agent_settled → D96 "background subagents still running" notice
+ * → sendUserMessage(followUp) (always starts a new run while idle) → master restarts → user presses ESC again → …
+ * After 30 aborts, ESC never breaks the cycle; only Ctrl+C stops the process.
+ * Natural settlement also forms a self-triggering loop: settle → notice → new run → settle → notice …
  *
- * 规则：
- *  - abort 抑制：上次 assistant stopReason === 'aborted' → 本次 settled 不做任何
- *    唤醒型注入（用户显式叫停；结算缓冲保留待下次自然 turn 投递）；
- *  - D96 去重：同一组 running paneId 只提醒一次；集合变化（新 sub / 结算）重置；
- *  - D96 冷却：同集合重提醒至少间隔 REPEAT_NOTICE_MS（集合没变却再提醒 = 噪音）。
+ * Rules:
+ *  - Abort suppression: when the previous assistant stopReason === 'aborted', this settled event injects no
+ *    wake-up message (the user explicitly stopped it; settlement-buffered content waits for the next natural turn);
+ *  - D96 deduplication: notify once for a given running paneId set; any set change (new subagent/settlement) resets it;
+ *  - D96 cooldown: repeat a notice for the same set only after REPEAT_NOTICE_MS (otherwise the unchanged set is noise).
  */
+
 export const ABORT_STOP_REASON = 'aborted';
 
-/** D96：同一 running 集合的重提醒冷却。 */
+/** D96: cooldown before repeating a notice for the same running set. */
 export const D96_REPEAT_NOTICE_MS = 10 * 60_000;
 
 export interface SettleWakeInput {
-  /** 本次 settled 前最后一次 assistant turn 的 stopReason（未知 = null，视作自然结束）。 */
+  /** stopReason of the last assistant turn before this settlement (unknown = null, treated as natural completion). */
   lastStopReason: string | null;
-  /** 仍在 running 的后台 subagent（空数组 = 无）。 */
+  /** Background subagents still running (empty means none). */
   running: ReadonlyArray<{ paneId: string }>;
-  /** 上次 D96 提醒时的集合键（无 = null）。 */
+  /** Set key recorded for the previous D96 notice (none = null). */
   lastNoticeKey: string | null;
-  /** 上次 D96 提醒时间（epoch ms）。 */
+  /** Timestamp of the previous D96 notice (epoch ms). */
   lastNoticeAt: number;
   now: number;
 }
 
 export interface SettleWakePlan {
-  /** false = 本次 settled 静默：不投任何唤醒型消息。 */
+  /** false means this settlement stays silent and emits no wake-up message. */
   wake: boolean;
-  /** 是否注入 D96「仍在运行」提醒。 */
+  /** Whether to inject the D96 "still running" notice. */
   notice: boolean;
-  /** 新的集合键（提醒时更新；running 空 → null）。 */
+  /** New set key (updated when notifying; empty running set → null). */
   noticeKey: string | null;
   noticeAt: number;
 }

package/src/slim-frame.ts

@@ -1,47 +1,48 @@
 /**
- * D97 窄格静帧（slim frame）：pane 长宽放不下最小可用 TUI 时，用非捕获
- * 全屏 overlay 盖一张 pane title 同源静帧。
+ * 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.
  *
- * 动机（用户实证）：热力把非焦点格压窄后，worker 的流式 thinking 在窄格
- * 里持续整屏重绘 → 闪烁。静帧只在 todo_write / 状态上报时更新（与
- * formatPaneTitle 同参同源），thinking token 碰不到它 → alt-screen 行级
- * 差分下 PTY 零输出，闪烁物理消失。
+ * 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
+ * todo_write/status reports (sharing arguments and source with formatPaneTitle), so thinking tokens cannot reach it;
+ * alt-screen row-level diffing then produces zero PTY output and physically eliminates the flicker.
  *
- * 前提：worker/master 以 --tui-mode fullscreen 运行（buildLaunchParts 默认
- * 注入）。regular 主屏的整屏 dump 路径（tui-main-screen firstChanged <
- * viewportTop → 全量重倒）overlay 盖不住——composite 在文档之上，dump 在
- * 文档之内。
+ * Prerequisite: worker/master run with --tui-mode fullscreen (injected by default by buildLaunchParts).
+ * The regular main-screen full dump path (tui-main-screen firstChanged < viewportTop → full redraw) cannot be
+ * covered by the overlay: composite is above the document, while the dump is inside the document.
  *
- * 注册闸：仅 herdr pane 内（index.ts 以 env 判定）——普通小终端窗口里盖住
- * 交互面是事故；herdr 窄格点击聚焦即被热力放大，visible 谓词随 SIGWINCH
- * 每帧重估，静帧自动消失、真 TUI 原样在底下（agent/会话/widget 从未停）。
+ * Registration gate: only inside a herdr pane (index.ts checks the environment), because covering an interactive
+ * normal terminal window would be hazardous. Clicking a narrow herdr pane focuses it and the heat view expands it;
+ * the visible predicate re-evaluates on every frame as SIGWINCH arrives, so the frame disappears automatically and
+ * the real TUI remains underneath (agent/session/widget execution never stops).
  *
- * 生命周期：进程内单例，session_start（非 resume）注册一次；overlay 常驻
- * （done() 永不调用 → Promise 永挂，吞 rejection，绝不 await）。pi 会话
- * 切换若拆掉 overlay（resetExtensionUI）则静帧自然退场，不影响主流程。
- * PI_HERDR_SLIM_FRAME=0 逃生口。
+ * Lifecycle: one process-local singleton, registered once on session_start (not resume); the overlay stays resident
+ * (done() is never called, leaving the Promise pending, swallowing rejection, and never awaiting it). If switching
+ * pi sessions removes the overlay (resetExtensionUI), the static frame naturally exits without affecting the main
+ * flow. PI_HERDR_SLIM_FRAME=0 is the escape hatch.
  */
 
-/** TUI 可用下限（pi interactive-mode 布局：editor 3 行 + footer 1 + transcript ≥3 + 间距）。
- * 任一轴低于此值 → 该格读不了 TUI，画 title 静帧。 */
+/** 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. */
+
 export const SLIM_MIN_COLS = 24;
 export const SLIM_MIN_ROWS = 12;
 
-/** 静帧可见性谓词（overlayOptions.visible 每渲染帧回调）。 */
+/** Visibility predicate (overlayOptions.visible invokes it on every render frame). */
 export function isSlimFrame(cols: number, rows: number): boolean {
   return cols < SLIM_MIN_COLS || rows < SLIM_MIN_ROWS;
 }
 
-/* ── 宽度感知折行（保守 East Asian 宽度；▶○■✓ 等歧义宽字符按 1 记，仅影响折点位置） ── */
+/* ── Width-aware wrapping (conservative East Asian width; ambiguous glyphs such as ▶○■✓ count as 1, affecting only break positions) ── */
 
 function isWide(cp: number): boolean {
   return (
-    (cp >= 0x1100 && cp <= 0x115f) // 谚文兼容字母
-    || (cp >= 0x2e80 && cp <= 0xa4cf) // CJK 部首～彝文（含假名）
-    || (cp >= 0xac00 && cp <= 0xd7a3) // 谚文音节
-    || (cp >= 0xf900 && cp <= 0xfaff) // CJK 兼容表意
-    || (cp >= 0xfe30 && cp <= 0xfe4f) // CJK 兼容形式
-    || (cp >= 0xff00 && cp <= 0xff60) // 全角形式
+    (cp >= 0x1100 && cp <= 0x115f) // Hangul compatibility jamo
+    || (cp >= 0x2e80 && cp <= 0xa4cf) // CJK radicals through Yi (including kana)
+    || (cp >= 0xac00 && cp <= 0xd7a3) // Hangul syllables
+    || (cp >= 0xf900 && cp <= 0xfaff) // CJK compatibility ideographs
+    || (cp >= 0xfe30 && cp <= 0xfe4f) // CJK compatibility forms
+    || (cp >= 0xff00 && cp <= 0xff60) // Fullwidth forms
     || (cp >= 0xffe0 && cp <= 0xffe6)
   );
 }
@@ -53,8 +54,8 @@ export function displayWidth(s: string): number {
 }
 
 /**
- * 按可见宽度折行：词折行（行内有空格则退到最后一个空格断，英文短语不腰斩；
- * CJK 无空格自然硬折）。折行处吞掉断点空格。
+ * Wrap at visible width: prefer word breaks (retreat to the last space instead of cutting an English phrase);
+ * CJK text without spaces hard-wraps naturally. Consume the space at the break point.
  */
 export function wrapByWidth(text: string, width: number): string[] {
   const w = Math.max(1, Math.floor(width));
@@ -89,9 +90,9 @@ export function wrapByWidth(text: string, width: number): string[] {
 }
 
 /**
- * 静帧行：title 折行 → 垂直居中 → 钳到 rows。每行都补齐到满宽（可见宽度）：
- * overlay 的合成按行覆盖，空行会让底下的 TUI 透出来（漏 flicker），
- * 满宽空格行才是真正的不透明冻结。无 title → 居中一枚 `·`（活着、没计划）。
+ * Frame lines: wrap the title, center it vertically, and clamp to rows. Pad every line to full visible width:
+ * row-wise overlay compositing would let the TUI underneath show through blank lines (leaking flicker),
+ * while full-width spaces make the freeze genuinely opaque. Without a title, center one `·` (alive, no plan).
  */
 export function frameLines(
   text: string,
@@ -114,7 +115,7 @@ export function frameLines(
   return out;
 }
 
-/* ── overlay 组件 + 注册/更新（进程内单例） ─────────────────────────── */
+/* ── Overlay component plus registration/update (process-local singleton) ─────────────────────────── */
 
 interface FrameTui {
   requestRender(): void;
@@ -132,11 +133,11 @@ class SlimFrameComponent {
     this.colorize = colorize;
   }
 
-  /** visible 谓词每帧回调：顺手记录行数（render(width) 拿不到高度，居中布局靠它）。 */
+  /** The visible predicate runs each frame; record row count because render(width) lacks height for centered layout. */
   onViewport(cols: number, rows: number): boolean {
     if (this.lastRows !== rows) {
       this.lastRows = rows;
-      this.cache = null; // 行数变了 → 居中重排
+      this.cache = null; // A row-count change requires re-centering.
     }
     return isSlimFrame(cols, rows);
   }
@@ -159,14 +160,14 @@ class SlimFrameComponent {
     this.cache = null;
   }
 
-  /** pi 拆 overlay（会话切换/退出）时回收模块单例，重注册不被 no-op。 */
+  /** Reclaim the module singleton when pi tears down the overlay (session switch/exit), allowing re-registration. */
   dispose(): void {
     if (active === this) active = null;
   }
 }
 
 
-/** 测试注入点（module state 重置）。 */
+/** Test injection point (reset module state). */
 export function resetForTest(): void {
   active = null;
 }
@@ -174,8 +175,8 @@ export function resetForTest(): void {
 let active: SlimFrameComponent | null = null;
 
 /**
- * 注册静帧 overlay（幂等：进程一次）。eventCtx = pi 生命周期事件上下文
- * （session_start 的 ctx，与 todo widget 的 widgetUi 同来源）。
+ * Register the static-frame overlay (idempotent: once per process). eventCtx is the pi lifecycle event context
+ * (the session_start ctx, sourced from the same place as the todo widget's widgetUi).
  */
 export function registerSlimFrame(eventCtx: unknown): void {
   if (active) return;
@@ -187,8 +188,8 @@ export function registerSlimFrame(eventCtx: unknown): void {
     ? ui.custom
     : undefined;
   try {
-    // overlay: true = 浮层不清屏（pi ctx.ui.custom 默认替换编辑器区，必须显式盖）；
-    // nonCapturing = 键盘仍归编辑器（人点进窄格也能打字，热力放大后静帧自动消失）。
+    // overlay: true keeps the floating layer from clearing the screen (pi ctx.ui.custom replaces the editor area by default, so cover it explicitly);
+    // nonCapturing leaves the keyboard with the editor (typing in a focused narrow pane remains possible, and the expanded heat view hides the frame).
     const pending = custom(
       (tui, theme) => {
         const comp = new SlimFrameComponent(tui, (s) => theme.fg('accent', s));
@@ -206,14 +207,14 @@ export function registerSlimFrame(eventCtx: unknown): void {
         },
       },
     );
-    // done() 永不调用 → Promise 永挂（overlay 常驻）；吞 rejection，绝不 await。
+    // Never call done(), leaving the Promise pending so the overlay stays resident; swallow rejection and never await it.
     Promise.resolve(pending).catch(() => {});
   } catch {
-    /* 无 overlay 能力的 pi 版本静默降级 */
+    /* Silently degrade on pi versions without overlay support. */
   }
 }
 
-/** 静帧内容更新（title 与 pane 标题投影同参同源；null = 无计划）。 */
+/** 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 ?? '');
 }