pi-pier 0.1.5 → 0.2.0

package/src/ledger.ts

@@ -1,35 +1,33 @@
 /**
- * 档1 dispose 账本（D80⑤ + D79）。
+ * Disposal ledger shared by HMR and session shutdown (D80⑤ + D79).
  *
- * 背景：hmr partial reload **不跑旧 fiber 的 effect-disposers**（spike A 实证）——
- * 模块持有的进程级资源（setInterval / pipe server / watcher）在热换后泄漏。
- * 补偿：core 模块把进程级资源登记进账本（key = 模块文件）；hmr/reload 事件
- * 按文件名触发 disposeKey，拆掉旧版本登记的资源；session_shutdown 走 disposeAll。
+ * HMR partial reload can skip old fiber effect disposers, so process-level resources
+ * such as intervals, pipe servers, and watchers would leak without compensation.
+ * Core modules register those resources by module key; reload disposes matching keys,
+ * while session_shutdown disposes everything.
  *
- * D79 同构复用：未来 pi-surface proxy 的注册反清理（registerTool/on 的账本）
- * 与本账本同一机制（key 可用 'pi-surface' 等逻辑名，不必是文件）。
- *
- * 纯逻辑零依赖；接缝在 bootstrap（hmr 事件）与 index（session_shutdown）。
+ * D79 reuses this mechanism for pi-surface registration cleanup; logical keys need not
+ * be file paths. The ledger stays dependency-free and connects through bootstrap/index.
  */
 
 import { fileURLToPath } from 'node:url';
 
-/** 规范化 key：file:// URL 与普通路径统一为绝对路径（hmr filename 与 import.meta.url 可互比）。 */
+/** Normalize file URLs and paths to comparable absolute keys for HMR matching. */
 export function normalizeModuleKey(spec: string): string {
   let s = String(spec);
   try {
     if (s.startsWith('file://')) s = fileURLToPath(s);
   } catch {
-    /* 非法 URL 按原样使用 */
+    /* Keep malformed URLs unchanged so disposal can still use the caller's key. */
   }
   return s.replace(/\\/g, '/');
 }
 
 export class DisposeLedger {
-  /** 登记序（LIFO 拆除与 cordis effect 语义一致）。 */
+  /** LIFO order matches Cordis effect disposal semantics. */
   private order: Array<{ key: string; dispose: () => void }> = [];
 
-  /** 登记一个待拆资源；返回撤销函数（资源自拆后从账本移除，防二次拆）。 */
+  /** Register a resource and return cancellation so self-disposal cannot run twice. */
   add(spec: string, dispose: () => void): () => void {
     const entry = { key: normalizeModuleKey(spec), dispose };
     this.order.push(entry);
@@ -39,7 +37,7 @@ export class DisposeLedger {
     };
   }
 
-  /** hmr 补偿（D80⑤）：只拆匹配 key 的登记项（LIFO），返回拆除数。 */
+  /** HMR compensation disposes only matching keys in LIFO order. */
   disposeKey(spec: string | string[]): number {
     const keys = new Set((Array.isArray(spec) ? spec : [spec]).map(normalizeModuleKey));
     let n = 0;
@@ -47,19 +45,19 @@ export class DisposeLedger {
       if (keys.has(this.order[i].key)) {
         const { dispose } = this.order[i];
         this.order.splice(i, 1);
-        try { dispose(); } catch { /* 补偿拆除非致命 */ }
+        try { dispose(); } catch { /* Compensation failures are non-fatal. */ }
         n++;
       }
     }
     return n;
   }
 
-  /** 全量 LIFO（session_shutdown 路径），返回拆除数。 */
+  /** Dispose every entry in LIFO order during session_shutdown. */
   disposeAll(): number {
     let n = 0;
     while (this.order.length > 0) {
       const { dispose } = this.order.pop()!;
-      try { dispose(); } catch { /* 同上 */ }
+      try { dispose(); } catch { /* Compensation failures are non-fatal. */ }
       n++;
     }
     return n;

package/src/lock-core.ts

@@ -1,38 +1,24 @@
-/**
- * M18 文件级写锁纯核心（S2 拍板：默认软 veto；PI_HERDR_WRITE_LOCK=1 硬启；2026-08-18）。
- *
- * 通道（D3 无新协议，schema 实测约束）：锁登记 = herdr `pane.report_metadata` tokens
- * ——键必须匹配 `^[A-Za-z0-9_-]{1,32}$`（路径进不了键！）→ **键 = `lock-<FNV-1a 64位哈希>`，
- * 值 = `<paneId>|<归一路径>`**（值无模式限制，路径放值里保可读性）；
- * 每次上报 ≤16 键（adapter 分批）。冲突检查 = `agent.list` 读全 pane tokens；
- * pane 关闭 → agent 条目消失 = 锁失效；settled → 显式置 null 释放。
- *
- * 语义：
- *  - 参与工具：write / edit（`{path}`；bash 文件目标提取不可靠，v1 声明为 seam）；
- *  - 同 pane 重入放行；异 pane 持有 → 软 warn（工具照跑，结果附警告）/ 硬 block；
- *  - 归一：resolve(cwd) + 反斜杠→斜杠 + 小写（Windows 大小写不敏感）+ 去尾斜杠；
- *  - 哈希碰撞（64 位，~10² 文件量级可忽略）：软模式多一次无害警告；硬模式极小概率误拦。
- */
+/** Why: Preserve the established compatibility and safety behavior (D3, M18, S2). */
 import { resolve, sep } from 'node:path';
 
-/** 硬启开关（env 名固定）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export const WRITE_LOCK_ENV = 'PI_HERDR_WRITE_LOCK';
-/** v1 参与写锁的工具（取 input.path）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export const WRITE_TOOLS = ['write', 'edit'] as const;
-/** 锁 token 键前缀（schema：^[A-Za-z0-9_-]{1,32}$）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export const LOCK_TOKEN_PREFIX = 'lock-';
-/** 单次 report_metadata 的 token 键上限（schema maxProperties=16）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export const LOCK_BATCH_LIMIT = 16;
-/** 锁 token TTL（pane 崩溃兜底；正常路径 settled 即释放）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export const LOCK_TTL_MS = 60 * 60 * 1000;
 
-/** agent.list 里与本模块相关的视图。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export interface LockAgentView {
   paneId: string;
   tokens: Record<string, string | null>;
 }
 
-/* ── 路径归一 ─────────────────────────────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export function normalizeLockPath(p: string, cwd: string): string {
   const abs = resolve(cwd, p);
@@ -40,9 +26,9 @@ export function normalizeLockPath(p: string, cwd: string): string {
   return unified.toLowerCase().replace(/\/+$/, '');
 }
 
-/* ── token 编解码（key = 哈希；value = paneId|path） ─────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
-/** FNV-1a 64 位 → 16 位 hex（BigInt 纯实现，无 node:crypto 依赖，可单测）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function fnv1a64(s: string): string {
   let h = 0xcbf29ce484222325n;
   for (let i = 0; i < s.length; i++) {
@@ -66,12 +52,12 @@ export function parseLockTokenValue(v: string): { holderPaneId: string; path: st
   return { holderPaneId: v.slice(0, i), path: v.slice(i + 1) };
 }
 
-/** token 键是否属于锁命名空间。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function isLockTokenKey(key: string): boolean {
   return key.startsWith(LOCK_TOKEN_PREFIX) && key.length > LOCK_TOKEN_PREFIX.length;
 }
 
-/* ── 工具路径提取 ─────────────────────────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export function writePathsOfTool(toolName: string, input: unknown): string[] {
   if (!(WRITE_TOOLS as readonly string[]).includes(toolName)) return [];
@@ -79,7 +65,7 @@ export function writePathsOfTool(toolName: string, input: unknown): string[] {
   return typeof p === 'string' && p.trim() ? [p] : [];
 }
 
-/* ── 冲突判定（value 解码持有人；同 pane 重入放行） ───────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export function findLockConflict(
   agents: readonly LockAgentView[],
@@ -96,7 +82,7 @@ export function findLockConflict(
   return null;
 }
 
-/* ── 决策 ─────────────────────────────────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export type WriteGuardPlan =
   | { kind: 'skip' }
@@ -136,7 +122,7 @@ export function planWriteGuard(opts: {
   return { kind: 'pass', paths };
 }
 
-/* ── token 构造（分批在 adapter） ─────────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export function acquireTokensFor(normPaths: readonly string[], paneId: string): Record<string, string> {
   const out: Record<string, string> = {};

package/src/manifest-compose.ts

@@ -1,14 +1,4 @@
-/**
- * 档2 Week2-3：manifest 三态合成（C7 v2；2026-08-18）。
- *
- * `manifest.tools = (roleBaseline ∪ modelSuggested) \ {tool | rule(tool) = deny}`
- * `manifest.permissions[tool] = rule(tool) ?? rule['*'] ?? 'allow'`
- *
- * 规则最高优先（安全护栏不可被模型建议绕过）；deny 排除、ask 标记、allow 放行；
- * 合成后为空 = 配置错误（EMPTY_MANIFEST，防 deny-all trap，照抄 DSH 纪律）；
- * 基线为空 = INVALID_ROLE_CONFIG（协调工具强制，档案级校验在 role-manifest.ts）。
- * 排序确定（便于测试与缓存比较）。
- */
+/** Why: Preserve the established compatibility and safety behavior (C7). */
 import type { PermissionAction, RoleManifest, UnknownToolStance } from './role-manifest.ts';
 import { loadRoleConfig } from './role-loader.ts';
 
@@ -16,14 +6,14 @@ export interface ManifestSources {
   roleBaseline: readonly string[];
   modelSuggested: readonly string[];
   rulePermissions: Record<string, PermissionAction>;
-  /** D82：未知工具姿态（缺省 deny）。 */
+  /** Why: Preserve the established compatibility and safety behavior (D82). */
   unknownTools?: UnknownToolStance;
 }
 
 export interface ComposedManifest {
   tools: string[];
   permissions: Record<string, PermissionAction>;
-  /** D82：解析后的未知工具姿态（缺省 deny）。 */
+  /** Why: Preserve the established compatibility and safety behavior (D82). */
   unknownTools: UnknownToolStance;
 }
 
@@ -54,16 +44,16 @@ export function composeManifest(sources: ManifestSources): ComposedManifest {
 
   const tools: string[] = [];
   const permissions: Record<string, PermissionAction> = {};
-  // D82：规则键全量并入 permissions（含 deny 与基线外的排除族）——
-  // stance=allow 下闸门/可见层仍能对排除族持禁令（deny 记忆不丢）。
+  // Why: Preserve the established compatibility and safety behavior (D82).
+  // Why: Preserve the established compatibility and safety behavior.
   for (const [k, v] of Object.entries(rules)) {
-    if (k === '*') continue; // 通配是默认值不是逐工具记录
+    if (k === '*') continue; // Why: Preserve the established compatibility and safety behavior.
     permissions[k] = v;
   }
   for (const tool of candidates) {
     const action = rules[tool] ?? defaultAction;
     permissions[tool] = action;
-    if (action === 'deny') continue; // 安全护栏：不进 manifest.tools
+    if (action === 'deny') continue; // Why: Preserve the established compatibility and safety behavior.
     tools.push(tool);
   }
 
@@ -76,15 +66,11 @@ export function composeManifest(sources: ManifestSources): ComposedManifest {
     );
   }
 
-  tools.sort(); // 确定性
+  tools.sort(); // Why: Preserve the established compatibility and safety behavior.
   return { tools, permissions, unknownTools: stance };
 }
 
-/**
- * 端到端：档案名 → loadRoleConfig → 合成（显式 tools/rules 即全部语义；
- * roleType 自动约束已随 WS-D8 移除——"不配发即禁止"由 tools 列表本身表达）。
- * master 侧 subagent 工具的调用缝；loadRole 可注入（测试替身）。
- */
+/** Why: Preserve the established compatibility and safety behavior (WS-D8). */
 export function composeForRole(
   roleName: string,
   modelSuggested: readonly string[],

package/src/notice-buffer.ts

@@ -1,23 +1,18 @@
 /**
- * D92 结算通知折叠器（followup 堆积修复的纯函数半）。
+ * D92 settlement-notice collapser (pure half of the followup-flood fix).
  *
- * 背景：结算通知原走 pi.sendUserMessage(deliverAs:'followUp')——pi 语义是
- * 「agent 没有更多 tool call 时才投递」= 整个 run 结束才回填。master 长任务
- * 执行中 N 个 subagent 结算/失败重启，通知全攒在队列里，run 结束瞬间洪水灌入。
- *
- * 修复分两半（另一半在 index.ts 接线）：
- *  - 忙时入扩展自己的缓冲，turn_end（LLM 迭代边界）以 steer 折叠批量注入；
- *  - 单次注入最多展示 max 条全文，其余收进尾行（全量走 history 台账/list_agents）。
+ * Why: `sendUserMessage(followUp)` only delivers when the agent has no more
+ * tool calls, so a long master run queues every settlement and floods at the
+ * end. Buffer while busy; collapse at turn_end. The other half is the index
+ * notice buffer.
  */
-
-/** 折叠展示的最大条数（用户拍板：最多 3 条）。 */
 export const NOTICE_MAX_SHOWN = 3;
 
 /**
- * 把一批通知折叠成单条消息体。
- * - 空 → null（不注入）
- * - ≤max 条 → 原文逐条（\n\n 连接），不套任何包装（单条时与旧格式逐字节一致）
- * - >max 条 → 前 max 条原文 + 尾行汇总（指向 history 台账 / list_agents 查全量）
+ * Collapse a batch into one message body.
+ * - empty → null (do not inject)
+ * - ≤max → originals joined with `\n\n` (single-item byte-identical to the old format)
+ * - >max → first max originals + a tail pointing at history / list_agents
  */
 export function collapseNotices(contents: readonly string[], max = NOTICE_MAX_SHOWN): string | null {
   if (contents.length === 0) return null;

package/src/pane-title.ts

@@ -1,37 +1,38 @@
 /**
- * pane todo → herdr 窗格头 / 侧栏投影（M22，D62/D68）。
+ * Projects the pane todo snapshot into a herdr pane header/sidebar (M22, D62/D68).
  *
- * 权威仍在 pi 会话 JSONL；这里只把快照收成 title + blocked 徽标。
- * herdr 把 title / state_label 截到 80 字符——本地先裁，避免半截 emoji。
+ * The pi session JSONL remains authoritative; this layer only condenses the snapshot into a title and blocked badge.
+ * herdr truncates title/state_label to 80 characters, so truncate locally to avoid cutting an emoji in half.
  */
 import { countTodos, PI_HERDR_META_KEY, type TodoItem } from './vocab.ts';
 import { formatAge, isArchived } from './stale-core.ts';
 
-/** herdr 对 title / state_label 的字符上限（官方文档 + schema 实测）。 */
+/** herdr's character limit for title/state_label (from official documentation and schema measurements). */
 export const TITLE_MAX = 80;
-/** 空列表：调用方发 clear_title，不写空串。 */
+/** Empty list: callers send clear_title rather than an empty string. */
 export const TITLE_EMPTY = null;
 /**
- * state_labels 合法键只有 idle|working|blocked|done|unknown
- * （herdr socket-api；WIRE 早期 `todo` 被拒 invalid_state_label）。
+ * Valid state_labels keys are only idle|working|blocked|done|unknown
+ * (herdr socket-api; the early WIRE `todo` value was rejected as invalid_state_label).
  */
 export const BLOCKED_LABEL_KEY = 'blocked';
 
 /**
- * D93：todo 摘要的侧边栏 custom token 名（herdr `[ui.sidebar.agents]` 里以 `$pi-todo` 引用）。
- * 值与 pane title 同源同格式（`▶i ○p ■b ✓c (N/M) · activity`）。
+ * D93: custom sidebar token for the todo summary (referenced as `$pi-todo` by herdr `[ui.sidebar.agents]`).
+ * Keep its value in the same format and source as the pane title (`▶i ○p ■b ✓c (N/M) · activity`).
  */
 export const SIDEBAR_TODO_TOKEN = 'pi-todo';
-/** D95：ask_user_question 等待标志 token 名（workbench 热力分级读它区分 ask vs block）。 */
+/** D95: token marking an ask_user_question wait (the workbench heat scale uses it to distinguish ask from block). */
 export const SIDEBAR_ASK_TOKEN = 'pi-ask';
 
 /**
- * D93：构造 report_metadata 的 pi-todo token 补丁。
- * 有 title → 值 = title（侧边栏可排 `$pi-todo`）；无 todo → 空串（herdr patch 语义删除键，不留旧摘要）。
+ * D93: build the pi-todo token patch for report_metadata.
+ * A title becomes the token value so the sidebar can render `$pi-todo`; no todo becomes an empty string so herdr's
+ * patch semantics remove the key rather than retaining an old summary.
  *
- * D96 修正：**不再合并 stale**——stale（16 个 null）是一次性清理（reportMetadata 单独发），
- * 合并会使总数 17 > herdr tokens maxProperties=16 → 整个请求被拒 → title/tokens 全丢
- * （用户实机：pane title 消失 + 侧边栏 token 消失，D93 回归根因）。
+ * D96 correction: **do not merge stale**. Stale (16 nulls) is a one-time cleanup sent separately via reportMetadata;
+ * merging would make 17 entries exceed herdr's tokens maxProperties=16, rejecting the entire request and dropping
+ * both title and tokens (observed on the user's machine: pane title and sidebar token disappeared; D93 regression root cause).
  */
 export function sidebarTodoTokens(title: string | null): Record<string, string> {
   return { [SIDEBAR_TODO_TOKEN]: title ?? '' };
@@ -44,13 +45,13 @@ function clipTitle(s: string): string {
 }
 
 /**
- * `▶i ○p ■b ✓c (N/M [~eta]) · <activity>`（D91 图标统一：黑白字符四件套）。
- * activity = 第一条 in_progress，否则 fallbackDescription，再否则只报计数。
- * 空列表 → null。progressSuffix（M16）= formatProgressSuffix 产物。
+ * `▶i ○p ■b ✓c (N/M [~eta]) · <activity>` (D91 unifies the four black-and-white status glyphs).
+ * activity is the first in_progress item, then fallbackDescription, then only the counts.
+ * Empty list → null. progressSuffix (M16) is produced by formatProgressSuffix.
  *
- * 反冻结（stale-core D）：全完成 + 墙钟过期（archived）→ 死列表降权为
- * `✓N done <age>`，不再以 ▶○■✓ 满权重视窗冒充当前状态；"在干嘛"由
- * report_agent 的工具徽标/活动行承担，todo token 只报计划真实状态。
+ * Anti-freeze behavior (stale-core D): once all work is complete and the wall clock expires (archived), lower the
+ * dead list to `✓N done <age>` instead of presenting it as a fully weighted current-state view; report_agent's tool
+ * badge/activity line explains what is happening, while the todo token reports only the plan's actual state.
  */
 export function formatPaneTitle(
   items: readonly TodoItem[],
@@ -73,7 +74,7 @@ export function formatPaneTitle(
   return clipTitle(activity ? `${withProgress} · ${activity}` : withProgress);
 }
 
-/** 第一条 blocked 的 blocker（缺则用 content）；无 blocked → null。 */
+/** First blocked item's blocker (fall back to content); no blocked item → null. */
 export function formatBlockedLabel(items: readonly TodoItem[]): string | null {
   const blocked = items.find((it) => it.status === 'blocked');
   if (!blocked) return null;
@@ -82,8 +83,7 @@ export function formatBlockedLabel(items: readonly TodoItem[]): string | null {
 }
 
 /**
- * 升级后首次上报用来清掉旧 16-key 分块（herdr tokens 按 key 合并，
- * 不写 null 会残留——M13b）。
+ * The first post-upgrade report clears the old 16-key chunks (herdr merges tokens by key, so omitted nulls remain—M13b).
  */
 export function staleTokenClearance(): Record<string, null> {
   const tokens: Record<string, null> = { [PI_HERDR_META_KEY]: null };

package/src/pi-surface.ts

@@ -1,31 +1,23 @@
 /**
- * 档1 pi-surface（D79）：包住 pi ExtensionAPI 的注册面。
+ * Proxy the pi ExtensionAPI registration surface (D79).
  *
- * 背景（源码实证 pi dist/core/extensions/loader.js）：
- *  - `registerTool(...): void`、`on(...): void` —— **pi 不提供反注册函数**；
- *  - `extension.tools.set(tool.name, …)` —— 工具表按名覆盖：同名重注册 = 覆盖
- *    （hmr 热换后新版本自然顶掉旧条目）；
- *  - 事件监听是列表 —— 重注册会**双触发**（热换泄漏面）。
+ * pi exposes registration without unregister APIs: tools overwrite by name, but event
+ * listeners accumulate. HMR therefore needs tombstoned, generation-scoped wrappers so
+ * old listeners become inert while the latest generation remains active.
  *
- * 补偿策略（tombstone，世代化）：每个 core 模块经 `forModule(key)` 拿到scoped 面，
- * 其 registerTool/on 都包 alive 旗标。**世代规则**（d87 修，源读 cordis-plugin-hmr）：
- * hmr partialReload 真实时序 = 重挂新插件**之后**才 emit('hmr/reload') → bootstrap
- * hook 才 disposeKey——若按「翻当前组」实现，翻掉的是新版本正引用的组（死到货）。
- * 故：挂载即自翻同 key 更旧世代（新插件体执行 = 旧版本确定已死）；账本 disposer
- * 只收割「登记世代及之前」，登记后新挂的豁免；disposeModule（显式）翻全部。
- *
- * 与 dispose 账本（D80⑤ 修正后定位）咬合：构造时传入 ledger，forModule
- * 自动登记 `disposeModule(key)`——hmr/reload 按文件名补偿即翻旗。
+ * Because HMR emits reload after mounting the replacement (d87), mounting a key retires
+ * older generations immediately. The ledger then collects only generations registered
+ * through the reload boundary; explicit disposal retires every generation.
  */
 import type { DisposeLedger } from './ledger.ts';
 
-/** pi 的 ToolResult 最小形态（inert 返回用）。 */
+/** Minimal pi ToolResult shape used when a disposed tool is invoked. */
 const INERT_TOOL_RESULT = {
   content: [{ type: 'text' as const, text: 'Error: tool module disposed (hot-reloaded away); the new version has re-registered it.' }],
   details: {},
 };
 
-/** 模块级 scoped 面：registerTool/on 都带 alive 墓碑；registerCommand 走 Map 覆盖（pi 实测语义，无需墓碑）。 */
+/** Module-scoped surface: tombstone tools and events, while command replacement is safe because pi stores commands in a Map. */
 export interface ScopedSurface {
   registerTool(def: Record<string, unknown> & { name: string }): void;
   registerCommand(name: string, options: Record<string, unknown>): void;
@@ -34,17 +26,17 @@ export interface ScopedSurface {
 
 interface Group {
   alive: boolean;
-  /** 挂载世代号（单射递增；账本 disposer 按此判定收割范围）。 */
+  /** Monotonic mount generation used by the ledger disposer to determine its collection boundary. */
   epoch: number;
 }
 
-/** pi 注册面代理（D79）。raw 直通非注册方法（append/exec/setActiveTools…）。 */
+/** Proxy for pi's registration surface (D79); non-registration methods (append/exec/setActiveTools, etc.) pass through raw. */
 export class PiSurface<P extends object> {
   private groups = new Map<string, Group>();
-  /** 每 key 的世代列表（挂载即自翻更旧 → 活口至多 1 个，死口待账本回收）。 */
+  /** Generation history per key; mounting retires older generations so at most one stays alive until ledger collection. */
   private generations = new Map<string, Group[]>();
   private epochCounter = 0;
-  /** 账本登记世代（disposer 只收割 epoch ≤ 此值；消费即删，下次挂载补登）。 */
+  /** Ledger generation boundary; disposal collects epochs up to this value, then the next mount registers again. */
   private ledgerEntryEpoch = new Map<string, number>();
   private readonly pi: P;
   private readonly ledger?: DisposeLedger;
@@ -54,15 +46,15 @@ export class PiSurface<P extends object> {
     this.ledger = ledger;
   }
 
-  /** 原始 pi（不经包装的直通面；已迁移模块不应再用其注册）。 */
+  /** Raw pi surface, bypassing wrappers; migrated modules must not use it for registration. */
   get raw(): P {
     return this.pi;
   }
 
   /**
-   * 拿一个模块的 scoped 注册面。**每次调用 = 新世代**：挂载即自翻同 key 旧世代
-   * （新插件体执行意味着旧版本已死——hmr registry.delete 与手动重挂两态统一）。
-   * 账本登记按 key 单例（消费后下次挂载补登）。
+   * Get a module-scoped registration surface. Each call creates a new generation, retiring older
+   * generations for the same key so HMR replacement and manual remounting share one lifecycle.
+   * The ledger registers each key once and registers it again only after its entry is consumed.
    */
   forModule(key: string): ScopedSurface {
     this.epochCounter += 1;
@@ -102,8 +94,9 @@ export class PiSurface<P extends object> {
         );
       },
       registerCommand: (name, options) => {
-        // pi 的 commands 是 Map<name>（dist 实测 .set）——同名重注册覆盖，热换安全；
-        // handler 包墓碑仅为对称保险（覆盖语义下旧 handler 不会再被调）。
+        // pi stores commands as Map<name> (verified in the dist implementation), so same-name
+        // registration replaces safely; the handler tombstone is a symmetry safeguard even though
+        // replacement means the old handler will no longer be called.
         const handler = options.handler as ((...a: unknown[]) => unknown) | undefined;
         const wrapped = handler
           ? (...a: unknown[]) => (group!.alive ? handler(...a) : undefined)
@@ -118,7 +111,7 @@ export class PiSurface<P extends object> {
     };
   }
 
-  /** 翻墓碑（显式拆除，hmr 补偿不走这里）：翻该 key 全部世代；组不存在返回 false。 */
+  /** Retire all generations for a key during explicit disposal; return false when the key is absent. */
   disposeModule(key: string): boolean {
     const had = this.groups.has(key);
     for (const g of this.generations.get(key) ?? []) g.alive = false;
@@ -128,7 +121,7 @@ export class PiSurface<P extends object> {
     return had;
   }
 
-  /** 组数（测试/诊断）。 */
+  /** Number of live module groups, for tests and diagnostics. */
   get moduleCount(): number {
     return this.groups.size;
   }