pi-pier 0.1.0

package/src/ledger.ts

@@ -0,0 +1,71 @@
+/**
+ * 档1 dispose 账本（D80⑤ + D79）。
+ *
+ * 背景：hmr partial reload **不跑旧 fiber 的 effect-disposers**（spike A 实证）——
+ * 模块持有的进程级资源（setInterval / pipe server / watcher）在热换后泄漏。
+ * 补偿：core 模块把进程级资源登记进账本（key = 模块文件）；hmr/reload 事件
+ * 按文件名触发 disposeKey，拆掉旧版本登记的资源；session_shutdown 走 disposeAll。
+ *
+ * D79 同构复用：未来 pi-surface proxy 的注册反清理（registerTool/on 的账本）
+ * 与本账本同一机制（key 可用 'pi-surface' 等逻辑名，不必是文件）。
+ *
+ * 纯逻辑零依赖；接缝在 bootstrap（hmr 事件）与 index（session_shutdown）。
+ */
+
+import { fileURLToPath } from 'node:url';
+
+/** 规范化 key：file:// URL 与普通路径统一为绝对路径（hmr filename 与 import.meta.url 可互比）。 */
+export function normalizeModuleKey(spec: string): string {
+  let s = String(spec);
+  try {
+    if (s.startsWith('file://')) s = fileURLToPath(s);
+  } catch {
+    /* 非法 URL 按原样使用 */
+  }
+  return s.replace(/\\/g, '/');
+}
+
+export class DisposeLedger {
+  /** 登记序（LIFO 拆除与 cordis effect 语义一致）。 */
+  private order: Array<{ key: string; dispose: () => void }> = [];
+
+  /** 登记一个待拆资源；返回撤销函数（资源自拆后从账本移除，防二次拆）。 */
+  add(spec: string, dispose: () => void): () => void {
+    const entry = { key: normalizeModuleKey(spec), dispose };
+    this.order.push(entry);
+    return () => {
+      const i = this.order.indexOf(entry);
+      if (i >= 0) this.order.splice(i, 1);
+    };
+  }
+
+  /** hmr 补偿（D80⑤）：只拆匹配 key 的登记项（LIFO），返回拆除数。 */
+  disposeKey(spec: string | string[]): number {
+    const keys = new Set((Array.isArray(spec) ? spec : [spec]).map(normalizeModuleKey));
+    let n = 0;
+    for (let i = this.order.length - 1; i >= 0; i--) {
+      if (keys.has(this.order[i].key)) {
+        const { dispose } = this.order[i];
+        this.order.splice(i, 1);
+        try { dispose(); } catch { /* 补偿拆除非致命 */ }
+        n++;
+      }
+    }
+    return n;
+  }
+
+  /** 全量 LIFO（session_shutdown 路径），返回拆除数。 */
+  disposeAll(): number {
+    let n = 0;
+    while (this.order.length > 0) {
+      const { dispose } = this.order.pop()!;
+      try { dispose(); } catch { /* 同上 */ }
+      n++;
+    }
+    return n;
+  }
+
+  get size(): number {
+    return this.order.length;
+  }
+}

package/src/lock-core.ts

@@ -0,0 +1,155 @@
+/**
+ * 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² 文件量级可忽略）：软模式多一次无害警告；硬模式极小概率误拦。
+ */
+import { resolve, sep } from 'node:path';
+
+/** 硬启开关（env 名固定）。 */
+export const WRITE_LOCK_ENV = 'PI_HERDR_WRITE_LOCK';
+/** v1 参与写锁的工具（取 input.path）。 */
+export const WRITE_TOOLS = ['write', 'edit'] as const;
+/** 锁 token 键前缀（schema：^[A-Za-z0-9_-]{1,32}$）。 */
+export const LOCK_TOKEN_PREFIX = 'lock-';
+/** 单次 report_metadata 的 token 键上限（schema maxProperties=16）。 */
+export const LOCK_BATCH_LIMIT = 16;
+/** 锁 token TTL（pane 崩溃兜底；正常路径 settled 即释放）。 */
+export const LOCK_TTL_MS = 60 * 60 * 1000;
+
+/** agent.list 里与本模块相关的视图。 */
+export interface LockAgentView {
+  paneId: string;
+  tokens: Record<string, string | null>;
+}
+
+/* ── 路径归一 ─────────────────────────────────────────────────────── */
+
+export function normalizeLockPath(p: string, cwd: string): string {
+  const abs = resolve(cwd, p);
+  const unified = sep === '\\' ? abs.replace(/\\/g, '/') : abs;
+  return unified.toLowerCase().replace(/\/+$/, '');
+}
+
+/* ── token 编解码（key = 哈希；value = paneId|path） ─────────────── */
+
+/** FNV-1a 64 位 → 16 位 hex（BigInt 纯实现，无 node:crypto 依赖，可单测）。 */
+export function fnv1a64(s: string): string {
+  let h = 0xcbf29ce484222325n;
+  for (let i = 0; i < s.length; i++) {
+    h ^= BigInt(s.charCodeAt(i));
+    h = (h * 0x100000001b3n) & 0xffffffffffffffffn;
+  }
+  return h.toString(16).padStart(16, '0');
+}
+
+export function lockTokenKey(normPath: string): string {
+  return `${LOCK_TOKEN_PREFIX}${fnv1a64(normPath)}`;
+}
+
+export function lockTokenValue(normPath: string, paneId: string): string {
+  return `${paneId}|${normPath}`;
+}
+
+export function parseLockTokenValue(v: string): { holderPaneId: string; path: string } | null {
+  const i = v.indexOf('|');
+  if (i <= 0 || i === v.length - 1) return null;
+  return { holderPaneId: v.slice(0, i), path: v.slice(i + 1) };
+}
+
+/** token 键是否属于锁命名空间。 */
+export function isLockTokenKey(key: string): boolean {
+  return key.startsWith(LOCK_TOKEN_PREFIX) && key.length > LOCK_TOKEN_PREFIX.length;
+}
+
+/* ── 工具路径提取 ─────────────────────────────────────────────────── */
+
+export function writePathsOfTool(toolName: string, input: unknown): string[] {
+  if (!(WRITE_TOOLS as readonly string[]).includes(toolName)) return [];
+  const p = (input as { path?: unknown } | null | undefined)?.path;
+  return typeof p === 'string' && p.trim() ? [p] : [];
+}
+
+/* ── 冲突判定（value 解码持有人；同 pane 重入放行） ───────────────── */
+
+export function findLockConflict(
+  agents: readonly LockAgentView[],
+  ownPaneId: string,
+  normPath: string,
+): { holderPaneId: string } | null {
+  const key = lockTokenKey(normPath);
+  for (const a of agents) {
+    const v = a.tokens[key];
+    if (typeof v !== 'string' || !v) continue;
+    const parsed = parseLockTokenValue(v);
+    if (parsed && parsed.holderPaneId !== ownPaneId) return { holderPaneId: parsed.holderPaneId };
+  }
+  return null;
+}
+
+/* ── 决策 ─────────────────────────────────────────────────────────── */
+
+export type WriteGuardPlan =
+  | { kind: 'skip' }
+  | { kind: 'pass'; paths: string[] }
+  | { kind: 'warn'; paths: string[]; holderPaneId: string; warning: string }
+  | { kind: 'block'; paths: string[]; holderPaneId: string; reason: string };
+
+export function planWriteGuard(opts: {
+  toolName: string;
+  input: unknown;
+  agents: readonly LockAgentView[];
+  ownPaneId: string;
+  cwd: string;
+  hard: boolean;
+}): WriteGuardPlan {
+  const raw = writePathsOfTool(opts.toolName, opts.input);
+  if (raw.length === 0) return { kind: 'skip' };
+  const paths = raw.map((p) => normalizeLockPath(p, opts.cwd));
+  for (const norm of paths) {
+    const conflict = findLockConflict(opts.agents, opts.ownPaneId, norm);
+    if (!conflict) continue;
+    if (opts.hard) {
+      return {
+        kind: 'block',
+        paths,
+        holderPaneId: conflict.holderPaneId,
+        reason: `file locked by pane ${conflict.holderPaneId}: ${norm} is being edited in another pane. Wait for it to settle, or coordinate before writing.`,
+      };
+    }
+    return {
+      kind: 'warn',
+      paths,
+      holderPaneId: conflict.holderPaneId,
+      warning: formatConflictWarning(norm, conflict.holderPaneId),
+    };
+  }
+  return { kind: 'pass', paths };
+}
+
+/* ── token 构造（分批在 adapter） ─────────────────────────────────── */
+
+export function acquireTokensFor(normPaths: readonly string[], paneId: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const p of normPaths) out[lockTokenKey(p)] = lockTokenValue(p, paneId);
+  return out;
+}
+
+export function releaseTokensFor(normPaths: readonly string[]): Record<string, null> {
+  const out: Record<string, null> = {};
+  for (const p of normPaths) out[lockTokenKey(p)] = null;
+  return out;
+}
+
+export function formatConflictWarning(normPath: string, holderPaneId: string): string {
+  return `⚠️ write conflict: ${normPath} is locked by pane ${holderPaneId} (it edited this file and has not settled). This write went through (soft mode) — coordinate to avoid clobbering each other's changes.`;
+}

package/src/manifest-compose.ts

@@ -0,0 +1,102 @@
+/**
+ * 档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）。
+ * 排序确定（便于测试与缓存比较）。
+ */
+import type { PermissionAction, RoleManifest, UnknownToolStance } from './role-manifest.ts';
+import { loadRoleConfig } from './role-loader.ts';
+
+export interface ManifestSources {
+  roleBaseline: readonly string[];
+  modelSuggested: readonly string[];
+  rulePermissions: Record<string, PermissionAction>;
+  /** D82：未知工具姿态（缺省 deny）。 */
+  unknownTools?: UnknownToolStance;
+}
+
+export interface ComposedManifest {
+  tools: string[];
+  permissions: Record<string, PermissionAction>;
+  /** D82：解析后的未知工具姿态（缺省 deny）。 */
+  unknownTools: UnknownToolStance;
+}
+
+export class ManifestError extends Error {
+  readonly code: 'EMPTY_MANIFEST' | 'INVALID_ROLE_CONFIG';
+  constructor(code: 'EMPTY_MANIFEST' | 'INVALID_ROLE_CONFIG', message: string) {
+    super(message);
+    this.name = 'ManifestError';
+    this.code = code;
+  }
+}
+
+export function composeManifest(sources: ManifestSources): ComposedManifest {
+  const baseline = sources.roleBaseline.filter((t): t is string => typeof t === 'string' && t.trim() !== '');
+  if (baseline.length === 0) {
+    throw new ManifestError(
+      'INVALID_ROLE_CONFIG',
+      'INVALID_ROLE_CONFIG: 基线工具不能为空，至少需包含 todo_write 和 ask_user_question',
+    );
+  }
+  const candidates = new Set<string>([
+    ...baseline,
+    ...sources.modelSuggested.filter((t): t is string => typeof t === 'string' && t.trim() !== ''),
+  ]);
+  const rules = sources.rulePermissions ?? {};
+  const defaultAction: PermissionAction = rules['*'] ?? 'allow';
+  const stance: UnknownToolStance = sources.unknownTools ?? 'deny';
+
+  const tools: string[] = [];
+  const permissions: Record<string, PermissionAction> = {};
+  // D82：规则键全量并入 permissions（含 deny 与基线外的排除族）——
+  // stance=allow 下闸门/可见层仍能对排除族持禁令（deny 记忆不丢）。
+  for (const [k, v] of Object.entries(rules)) {
+    if (k === '*') continue; // 通配是默认值不是逐工具记录
+    permissions[k] = v;
+  }
+  for (const tool of candidates) {
+    const action = rules[tool] ?? defaultAction;
+    permissions[tool] = action;
+    if (action === 'deny') continue; // 安全护栏：不进 manifest.tools
+    tools.push(tool);
+  }
+
+  if (tools.length === 0) {
+    throw new ManifestError(
+      'EMPTY_MANIFEST',
+      `裁剪后 manifest 为空（deny-all trap？）。基线: ${baseline.join(', ') || '(空)'}；` +
+        `模型建议: ${sources.modelSuggested.join(', ') || '(无)'}；` +
+        `规则: ${JSON.stringify(rules)}`,
+    );
+  }
+
+  tools.sort(); // 确定性
+  return { tools, permissions, unknownTools: stance };
+}
+
+/**
+ * 端到端：档案名 → loadRoleConfig → 合成（显式 tools/rules 即全部语义；
+ * roleType 自动约束已随 WS-D8 移除——"不配发即禁止"由 tools 列表本身表达）。
+ * master 侧 subagent 工具的调用缝；loadRole 可注入（测试替身）。
+ */
+export function composeForRole(
+  roleName: string,
+  modelSuggested: readonly string[],
+  opts?: { loadRole?: typeof loadRoleConfig; loadRoleOpts?: Parameters<typeof loadRoleConfig>[1] },
+): { role: RoleManifest; manifest: ComposedManifest } {
+  const load = opts?.loadRole ?? loadRoleConfig;
+  const role = load(roleName, opts?.loadRoleOpts);
+  const manifest = composeManifest({
+    roleBaseline: role.manifest.tools,
+    modelSuggested,
+    rulePermissions: role.manifest.rules ?? { '*': 'allow' },
+    unknownTools: role.manifest.unknownTools,
+  });
+  return { role, manifest };
+}

package/src/notice-buffer.ts

@@ -0,0 +1,28 @@
+/**
+ * D92 结算通知折叠器（followup 堆积修复的纯函数半）。
+ *
+ * 背景：结算通知原走 pi.sendUserMessage(deliverAs:'followUp')——pi 语义是
+ * 「agent 没有更多 tool call 时才投递」= 整个 run 结束才回填。master 长任务
+ * 执行中 N 个 subagent 结算/失败重启，通知全攒在队列里，run 结束瞬间洪水灌入。
+ *
+ * 修复分两半（另一半在 index.ts 接线）：
+ *  - 忙时入扩展自己的缓冲，turn_end（LLM 迭代边界）以 steer 折叠批量注入；
+ *  - 单次注入最多展示 max 条全文，其余收进尾行（全量走 history 台账/list_agents）。
+ */
+
+/** 折叠展示的最大条数（用户拍板：最多 3 条）。 */
+export const NOTICE_MAX_SHOWN = 3;
+
+/**
+ * 把一批通知折叠成单条消息体。
+ * - 空 → null（不注入）
+ * - ≤max 条 → 原文逐条（\n\n 连接），不套任何包装（单条时与旧格式逐字节一致）
+ * - >max 条 → 前 max 条原文 + 尾行汇总（指向 history 台账 / list_agents 查全量）
+ */
+export function collapseNotices(contents: readonly string[], max = NOTICE_MAX_SHOWN): string | null {
+  if (contents.length === 0) return null;
+  if (contents.length <= max) return contents.join('\n\n');
+  const hidden = contents.length - max;
+  const tail = `…另有 ${hidden} 条结算未逐条展示。全量结果看 history 台账（路径公式见 resume_subagent 工具描述）；在跑代理用 list_agents 查看。`;
+  return [...contents.slice(0, max), tail].join('\n\n');
+}

package/src/pane-title.ts

@@ -0,0 +1,84 @@
+/**
+ * pane todo → herdr 窗格头 / 侧栏投影（M22，D62/D68）。
+ *
+ * 权威仍在 pi 会话 JSONL；这里只把快照收成 title + blocked 徽标。
+ * herdr 把 title / state_label 截到 80 字符——本地先裁，避免半截 emoji。
+ */
+import { countTodos, PI_HERDR_META_KEY, type TodoItem } from './vocab.ts';
+
+/** herdr 对 title / state_label 的字符上限（官方文档 + schema 实测）。 */
+export const TITLE_MAX = 80;
+/** 空列表：调用方发 clear_title，不写空串。 */
+export const TITLE_EMPTY = null;
+/**
+ * state_labels 合法键只有 idle|working|blocked|done|unknown
+ * （herdr socket-api；WIRE 早期 `todo` 被拒 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`）。
+ */
+export const SIDEBAR_TODO_TOKEN = 'pi-todo';
+/** D95：ask_user_question 等待标志 token 名（workbench 热力分级读它区分 ask vs block）。 */
+export const SIDEBAR_ASK_TOKEN = 'pi-ask';
+
+/**
+ * D93：构造 report_metadata 的 pi-todo token 补丁。
+ * 有 title → 值 = title（侧边栏可排 `$pi-todo`）；无 todo → 空串（herdr patch 语义删除键，不留旧摘要）。
+ *
+ * D96 修正：**不再合并 stale**——stale（16 个 null）是一次性清理（reportMetadata 单独发），
+ * 合并会使总数 17 > herdr tokens maxProperties=16 → 整个请求被拒 → title/tokens 全丢
+ * （用户实机：pane title 消失 + 侧边栏 token 消失，D93 回归根因）。
+ */
+export function sidebarTodoTokens(title: string | null): Record<string, string> {
+  return { [SIDEBAR_TODO_TOKEN]: title ?? '' };
+}
+
+const STALE_CHUNK_COUNT = 15;
+
+function clipTitle(s: string): string {
+  return s.length <= TITLE_MAX ? s : s.slice(0, TITLE_MAX);
+}
+
+/**
+ * `▶i ○p ■b ✓c (N/M [~eta]) · <activity>`（D91 图标统一：黑白字符四件套）。
+ * activity = 第一条 in_progress，否则 fallbackDescription，再否则只报计数。
+ * 空列表 → null。progressSuffix（M16）= formatProgressSuffix 产物。
+ */
+export function formatPaneTitle(
+  items: readonly TodoItem[],
+  fallbackDescription?: string | null,
+  opts?: { progressSuffix?: string | null },
+): string | null {
+  if (items.length === 0) return TITLE_EMPTY;
+  const c = countTodos(items);
+  const activity =
+    items.find((it) => it.status === 'in_progress')?.content
+    ?? (fallbackDescription?.trim() ? fallbackDescription.trim() : null);
+  const head = `▶${c.inProgress} ○${c.pending} ■${c.blocked} ✓${c.completed}`;
+  const suffix = opts?.progressSuffix?.trim();
+  const withProgress = suffix ? `${head} (${suffix})` : head;
+  return clipTitle(activity ? `${withProgress} · ${activity}` : withProgress);
+}
+
+/** 第一条 blocked 的 blocker（缺则用 content）；无 blocked → null。 */
+export function formatBlockedLabel(items: readonly TodoItem[]): string | null {
+  const blocked = items.find((it) => it.status === 'blocked');
+  if (!blocked) return null;
+  const text = blocked.blocker?.trim() || blocked.content;
+  return clipTitle(text);
+}
+
+/**
+ * 升级后首次上报用来清掉旧 16-key 分块（herdr tokens 按 key 合并，
+ * 不写 null 会残留——M13b）。
+ */
+export function staleTokenClearance(): Record<string, null> {
+  const tokens: Record<string, null> = { [PI_HERDR_META_KEY]: null };
+  for (let i = 0; i < STALE_CHUNK_COUNT; i++) {
+    tokens[`${PI_HERDR_META_KEY}-${i}`] = null;
+  }
+  return tokens;
+}

package/src/pi-surface.ts

@@ -0,0 +1,135 @@
+/**
+ * 档1 pi-surface（D79）：包住 pi ExtensionAPI 的注册面。
+ *
+ * 背景（源码实证 pi dist/core/extensions/loader.js）：
+ *  - `registerTool(...): void`、`on(...): void` —— **pi 不提供反注册函数**；
+ *  - `extension.tools.set(tool.name, …)` —— 工具表按名覆盖：同名重注册 = 覆盖
+ *    （hmr 热换后新版本自然顶掉旧条目）；
+ *  - 事件监听是列表 —— 重注册会**双触发**（热换泄漏面）。
+ *
+ * 补偿策略（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 按文件名补偿即翻旗。
+ */
+import type { DisposeLedger } from './ledger.ts';
+
+/** pi 的 ToolResult 最小形态（inert 返回用）。 */
+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 实测语义，无需墓碑）。 */
+export interface ScopedSurface {
+  registerTool(def: Record<string, unknown> & { name: string }): void;
+  registerCommand(name: string, options: Record<string, unknown>): void;
+  on(event: string, handler: (...args: unknown[]) => unknown): void;
+}
+
+interface Group {
+  alive: boolean;
+  /** 挂载世代号（单射递增；账本 disposer 按此判定收割范围）。 */
+  epoch: number;
+}
+
+/** pi 注册面代理（D79）。raw 直通非注册方法（append/exec/setActiveTools…）。 */
+export class PiSurface<P extends object> {
+  private groups = new Map<string, Group>();
+  /** 每 key 的世代列表（挂载即自翻更旧 → 活口至多 1 个，死口待账本回收）。 */
+  private generations = new Map<string, Group[]>();
+  private epochCounter = 0;
+  /** 账本登记世代（disposer 只收割 epoch ≤ 此值；消费即删，下次挂载补登）。 */
+  private ledgerEntryEpoch = new Map<string, number>();
+  private readonly pi: P;
+  private readonly ledger?: DisposeLedger;
+
+  constructor(pi: P, ledger?: DisposeLedger) {
+    this.pi = pi;
+    this.ledger = ledger;
+  }
+
+  /** 原始 pi（不经包装的直通面；已迁移模块不应再用其注册）。 */
+  get raw(): P {
+    return this.pi;
+  }
+
+  /**
+   * 拿一个模块的 scoped 注册面。**每次调用 = 新世代**：挂载即自翻同 key 旧世代
+   * （新插件体执行意味着旧版本已死——hmr registry.delete 与手动重挂两态统一）。
+   * 账本登记按 key 单例（消费后下次挂载补登）。
+   */
+  forModule(key: string): ScopedSurface {
+    this.epochCounter += 1;
+    const epoch = this.epochCounter;
+    for (const g of this.generations.get(key) ?? []) g.alive = false;
+    const group: Group = { alive: true, epoch };
+    this.generations.set(key, [group]);
+    this.groups.set(key, group);
+    if (this.ledger && !this.ledgerEntryEpoch.has(key)) {
+      this.ledgerEntryEpoch.set(key, epoch);
+      this.ledger.add(key, () => {
+        const bound = this.ledgerEntryEpoch.get(key) ?? epoch;
+        this.ledgerEntryEpoch.delete(key);
+        this.generations.set(
+          key,
+          (this.generations.get(key) ?? []).filter((g) => {
+            if (g.epoch <= bound) {
+              g.alive = false;
+              return false;
+            }
+            return true;
+          }),
+        );
+      });
+    }
+    return {
+      registerTool: (def) => {
+        const original = def.execute as ((...a: unknown[]) => unknown) | undefined;
+        const wrapped = original
+          ? async (...a: unknown[]) => {
+            if (!group!.alive) return INERT_TOOL_RESULT;
+            return original(...a);
+          }
+          : undefined;
+        (this.pi as { registerTool?: (d: unknown) => void }).registerTool?.(
+          wrapped ? { ...def, execute: wrapped } : def,
+        );
+      },
+      registerCommand: (name, options) => {
+        // pi 的 commands 是 Map<name>（dist 实测 .set）——同名重注册覆盖，热换安全；
+        // handler 包墓碑仅为对称保险（覆盖语义下旧 handler 不会再被调）。
+        const handler = options.handler as ((...a: unknown[]) => unknown) | undefined;
+        const wrapped = handler
+          ? (...a: unknown[]) => (group!.alive ? handler(...a) : undefined)
+          : undefined;
+        (this.pi as { registerCommand?: (n: string, o: Record<string, unknown>) => void })
+          .registerCommand?.(name, wrapped ? { ...options, handler: wrapped } : options);
+      },
+      on: (event, handler) => {
+        const wrapped = (...a: unknown[]) => (group!.alive ? handler(...a) : undefined);
+        (this.pi as { on?: (e: string, h: (...a: unknown[]) => unknown) => void }).on?.(event, wrapped);
+      },
+    };
+  }
+
+  /** 翻墓碑（显式拆除，hmr 补偿不走这里）：翻该 key 全部世代；组不存在返回 false。 */
+  disposeModule(key: string): boolean {
+    const had = this.groups.has(key);
+    for (const g of this.generations.get(key) ?? []) g.alive = false;
+    this.generations.delete(key);
+    this.groups.delete(key);
+    this.ledgerEntryEpoch.delete(key);
+    return had;
+  }
+
+  /** 组数（测试/诊断）。 */
+  get moduleCount(): number {
+    return this.groups.size;
+  }
+}