@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

package/src/execution/model-resolver.ts

@@ -1,248 +0,0 @@
-// src/core/model-resolver.ts
-//
-// 模型解析（三层）：
-//   1. 用户显式 override（tool 参数 model，平铺在 subagent params 顶层）→ registry lookup + auth
-//   2. agent .md frontmatter model（agent 作者指定）→ registry lookup + auth
-//   3. 主 agent 当前模型（ctx.model）→ 直接透传，无需 lookup
-//
-// 设计：默认与主 agent 同模型（零配置）。只有「有人显式指定 model」时才查
-// registry 做解析 + 鉴权校验。thinkingLevel 同链路，无指定时 undefined。
-
-// [U1 ModelRef 全等裁决] THINKING_ORDER / ThinkingLevel / strip / 裁决入口收拢到
-// shared/model-ref.ts（单一权威），此处 re-export 保持既有 import 路径不变
-//（subagent-tool / tool-workflow 的 schema 枚举从本模块派生）。
-import {
-  THINKING_ORDER,
-  assertCanonicalModelRef,
-  modelRefFromVerified,
-} from "../shared/model-ref";
-
-export { THINKING_ORDER };
-export type { ThinkingLevel } from "../shared/model-ref";
-
-/** 解析失败时错误信息列出的可用模型上限（防超长错误信息）。 */
-const MODEL_LIST_LIMIT = 20;
-
-/**
- * ModelRegistry 的最小接口（duck-typed，测试可 mock）。
- * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐。
- */
-export interface ModelRegistryLike {
-  /** 返回所有已配置鉴权的可用模型。 */
-  getAvailable(): ModelInfo[];
-  /** 按 (provider, modelId) 查找。 */
-  find(provider: string, modelId: string): ModelInfo | undefined;
-  /** 校验模型鉴权是否就绪。 */
-  hasConfiguredAuth(model: unknown): boolean;
-}
-
-/**
- * 模型信息（registry 返回元素 / ctx.model 鸭子类型兼容）。
- * ctx.model（SDK Model<Api>）是此类型的超集，运行时直接当 ModelInfo 用。
- */
-export interface ModelInfo {
-  id: string;
-  name: string;
-  provider: string;
-  reasoning: boolean;
-  thinkingLevelMap?: Record<string, unknown>;
-  contextWindow?: number;
-}
-
-/** agent .md frontmatter 解析结果。 */
-export interface AgentConfig {
-  /** agent 名（文件名 basename）。 */
-  name: string;
-  /** system prompt（markdown 正文）。 */
-  systemPrompt: string;
-  /** tool allowlist（三层过滤之一）。 */
-  tools?: string[];
-  /** 默认模型 override（"provider/modelId"）。agent 作者显式指定。 */
-  model?: string;
-  /** 默认 thinkingLevel override。 */
-  thinkingLevel?: string;
-  /** 默认 background 模式（true 时无显式 wait 走 background）。 */
-  defaultBackground?: boolean;
-  /**
-   * 执行引擎 id（agent .md frontmatter engine 字段，D9 per-agent 主通道）。
-   * 解析期已对注册表校验（未注册 id 在 agent-registry 抛 EngineNotFoundError）；
-   * 执行侧（P4 路由层）按 调用参数 > 本字段 > 全局默认 三层取值。
-   */
-  engine?: string;
-}
-
-/** 解析结果（model 实例 + 生效的 thinkingLevel）。 */
-export interface ResolvedModel {
-  model: ModelInfo;
-  thinkingLevel: string | undefined;
-}
-
-// ============================================================
-// 常量
-// ============================================================
-
-// MODEL_LIST_LIMIT 与 THINKING_ORDER 随 suggestSimilarModels/lookupModel 一并迁入
-// shared/model-ref.ts（U1 裁决单一入口）。
-
-// ============================================================
-// 解析
-// ============================================================
-
-/**
- * 三层模型解析：
- *
- *   ╔═══════════════════════════════════════════════════════════════╗
-//   ║  优先级（高→低）:                                              ║
-//   ║    1. paramOverride.model      （调用方显式指定，tool 参数）     ║
-//   ║    2. agentConfig.model        （agent .md frontmatter）        ║
-//   ║    3. ctxModel                 （主 agent 当前模型，直接透传）   ║
-//   ║                                                                ║
-//   ║  1/2 级查 registry + auth 校验；3 级无需 lookup（主 agent 在用  ║
-//   ║  说明 auth OK）。thinkingLevel 无显式指定时兜底「模型最高可用档」║
-//   ║  （maxThinkingForModel，含 "max" 时用 max）——不落回 pi 默认      ║
-//   ║  medium，subagent 任务需要最大推理深度。                          ║
-//   ║                                                                ║
-//   ║  显式指定但 lookup/auth 失败 → 抛错（不静默降级到主 agent，     ║
-//   ║  因为用户明确要求了某个 model，降级会造成「以为用了 X 实际用 Y」║
-//   ╚════════════════════════════════════════════════════════════════╝
- *
- * @param agentConfig     agent .md 解析结果（查 model override + thinkingLevel）
- * @param modelRegistry   registry（仅 override 路径用）
- * @param paramOverride   调用方显式 override（最高优先级）
- * @param ctxModel        主 agent 当前模型（兜底，直接透传）
- */
-export function resolveModel(
-  agentConfig: AgentConfig | undefined,
-  modelRegistry: ModelRegistryLike,
-  paramOverride?: { model?: string; thinkingLevel?: string },
-  ctxModel?: ModelInfo,
-): ResolvedModel {
-  // 1. paramOverride（最高优先级）。显式指定但 lookup/auth 失败 → 直接抛错，
-  // 不降级到下层（避免「以为用了 X 实际用 Y」的静默错误）。
-  if (paramOverride?.model) {
-    return lookupAndResolve(
-      paramOverride.model,
-      paramOverride.thinkingLevel ?? agentConfig?.thinkingLevel,
-      modelRegistry,
-      "paramOverride",
-    );
-  }
-
-  // 2. agentConfig.model（agent 作者指定）。同样显式 → 失败即抛错。
-  if (agentConfig?.model) {
-    return lookupAndResolve(
-      agentConfig.model,
-      agentConfig.thinkingLevel,
-      modelRegistry,
-      "agentConfig",
-    );
-  }
-
-  // 3. 主 agent model（直接透传）。无显式 thinking → 兜底最高可用档。
-  // [U1 D2 豁免口径] ctxModel 是运行时已验证的 ModelInfo 对象，豁免 registry 存在性
-  // 复查与 auth 校验；但孪生守卫同等适用（registry 含大小写孪生时拒绝放行，modelRefFromVerified）。
-  if (ctxModel) {
-    modelRefFromVerified(ctxModel, modelRegistry);
-    return {
-      model: ctxModel,
-      thinkingLevel: paramOverride?.thinkingLevel ?? agentConfig?.thinkingLevel
-        ?? maxThinkingForModel(ctxModel),
-    };
-  }
-
-  // 全部不可用 → 列出可用模型辅助调试
-  const available = modelRegistry.getAvailable().map((m) => `${m.provider}/${m.id}`);
-  throw new Error(
-    `No available model. Main agent has no active model, and no override was resolved.` +
-      (available.length > 0
-        ? `\nAvailable models:\n  ${available.slice(0, MODEL_LIST_LIMIT).join("\n  ")}`
-        : ""),
-  );
-}
-
-/**
- * lookup + auth 校验 + thinkingLevel clamp。显式指定但失败 → 抛错（不降级）。
- *
- * [U1 D1] 模型串裁决经 assertCanonicalModelRef 单一入口（strip 后缀 → provider 精确 →
- * 全等匹配 → 孪生守卫；未命中同步抛错并附问句式纠错候选）。放行即与 registry 条目全等。
- *
- * 错误信息区分两种失败（避免误导排查方向）：
- *   - model 非全等（不存在/大小写不符/孪生歧义）→ assertCanonicalModelRef 的问句式报错
- *   - model 全等命中但 auth 未配置 → 提示在 models.json 配置鉴权
- */
-function lookupAndResolve(
-  modelStr: string,
-  requestedThinking: string | undefined,
-  registry: ModelRegistryLike,
-  source: "paramOverride" | "agentConfig",
-): ResolvedModel {
-  const ref = assertCanonicalModelRef(modelStr, registry, { source });
-  const model = registry.find(ref.provider, ref.id);
-  if (!model) {
-    // 裁决已按 getAvailable 全等命中；find 独立实现（duck-typed mock 可能不同源）时的
-    // 类型收窄兜底，非预期路径。
-    throw new Error(
-      `Model "${modelStr}" (${source}) passed the canonical ref check but registry.find missed it ` +
-        `(registry snapshot inconsistent). Retry with an exact entry from the available models list.`,
-    );
-  }
-  if (!registry.hasConfiguredAuth(model)) {
-    throw new Error(
-      `Model "${modelStr}" (${source}) exists but auth is not configured. ` +
-        `Configure auth in models.json or switch to an authorized model.`,
-    );
-  }
-  return {
-    model,
-    // 无显式请求时兜底「模型最高可用档」（不落 pi 默认 medium）。
-    thinkingLevel: resolveThinkingLevel(model, requestedThinking ?? maxThinkingForModel(model)),
-  };
-}
-
-/**
- * subagent 默认 thinking：模型最高可用档。
- *
- *   - thinkingLevelMap 配置了级别 → map 中最高档（模型显式配置 "max" 时即 max）
- *   - reasoning 但无 map → "xhigh"（pi 合法最高档；"max" 非 pi 合法值——
- *     spawn 侧 model:"max" 后缀会被 pi 判为非法 thinking 后缀导致 model 解析失败，
- *     故无 map 时不能直接用 "max"）
- *   - 非 reasoning 模型 → undefined（不支持 thinking）
- */
-function maxThinkingForModel(
-  model: { reasoning: boolean; thinkingLevelMap?: Record<string, unknown> },
-): string | undefined {
-  const levels = availableThinkingLevels(model);
-  if (levels.length > 0) return levels[levels.length - 1];
-  return model.reasoning ? "xhigh" : undefined;
-}
-
-/**
- * 从 model.thinkingLevelMap 提取可用级别，clamp 到最高可用。
- * model.reasoning === false → undefined（不支持 thinking）
- */
-function resolveThinkingLevel(
-  model: { reasoning: boolean; thinkingLevelMap?: Record<string, unknown> },
-  requested?: string,
-): string | undefined {
-  const levels = availableThinkingLevels(model);
-  if (levels.length === 0) return model.reasoning ? requested : undefined;
-  if (requested && levels.includes(requested)) return requested;
-  // requested 不可用 → 降级到最高可用
-  return levels[levels.length - 1];
-}
-
-/**
- * 列出 model 实际支持的 thinking level（升序）。
- *
- *   - model.reasoning === false → [] （不支持 thinking）
- *   - 无 thinkingLevelMap → [] （无级别信息，调用方按需透传）
- *   - 有 map → THINKING_ORDER 中 map[lvl] != null 的子集（保留升序）
- */
-export function availableThinkingLevels(
-  model: { reasoning: boolean; thinkingLevelMap?: Record<string, unknown> },
-): readonly string[] {
-  if (!model.reasoning) return [];
-  const map = model.thinkingLevelMap;
-  if (!map) return [];
-  return THINKING_ORDER.filter((lvl) => map[lvl] != null);
-}

package/src/execution/notifier.ts

@@ -1,330 +0,0 @@
-// src/execution/notifier.ts
-//
-// Background 完成回注主对话。sync 不用（调用方还在 await，结果直接返回）。
-//
-// 职责（U2 后）：
-//   - buildLlmContent：格式化通知文案（本文件唯一逻辑职责）
-//   - createNotifier：薄工厂——ledger 装配时（bindNotifyLedgerHost 已注入）走
-//     四步生命周期（写账 → courier 边沿投递 → 回执销账 → notifyId 幂等重放，
-//     notify-ledger.ts）；未装配时退回 @xyz-agent/session-delivery 内核路径
-//     （合并窗口 / 去重 / 退避 / flush 委托内核，旧装配 / 无 ledger 测试兼容）
-//
-// 投递通道（D5 单通道化）：ledger 路径经 courier 在 settled 边沿直达
-// pi.sendMessage({triggerTurn:true})；内核路径的 port.send 同样只传
-// {triggerTurn:true}——steer / followUp / nextTurn 通道已全部删除（nextTurn 的
-// 唯一 drain 点在 session.prompt() 内，主 agent 长 streaming 场景下无限期滞留，
-// 设计 D5 实测证伪）；busy 场景由 ledger（settled 边沿 + isIdle 二次复查）或内核
-// settled 订阅驱动在空闲边沿投递。
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-import { createDelivery, type DeliveryHandle, type DeliveryPort } from "@xyz-agent/session-delivery";
-
-import { deriveOutcome } from "./execution-record.ts";
-import { getBoundNotifyLedger, NOTIFY_CUSTOM_TYPE } from "./notify-ledger.ts";
-import type { ClosedReason, ExecutionOutcome } from "./types.ts";
-
-/** U4：delivery warn 出口注入用——与 index.ts 共享同一具名 logger 单例。 */
-const notifyLogger = getLogger("subagents");
-
-/**
- * 一条待发送的完成通知记录。
- * SP-1: done/failed/crashed 合并为 closed + closedReason L2 子枚举。
- */
-export interface BgNotifyRecord {
-  id: string;
-  /**
-   * 完成状态。v4 B-1 两态收敛：closed（终态，含 cancelled，closedReason 表达 L2 原因）
-   * 或 running（对话模式轮次完成，旧 idle 折入 running，携带本轮结果送回主 agent）。
-   * toNotifyRecord 守卫放行后经此联合穷尽。
-   */
-  status: "running" | "closed";
-  /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。内部诊断 + outcome 兑底派生输入。 */
-  closedReason?: ClosedReason;
-  /**
-   * 终态三态对外语义（U3 C-outcome）。notify() 投影边界物化：closed 入参缺省时按
-   * deriveOutcome(closedReason, error) 兑底填充（所有可达流程下与 completeRecord
-   * 冻结的 record.outcome 等价——toNotifyRecord 构造点在 completeRecord 之后；该
-   * 构造点属 U3 领地外，不透传本字段）。buildLlmContent 与 bg-notify-render 只读本字段。
-   */
-  outcome?: ExecutionOutcome;
-  agent: string;
-  /** 执行所用 model（RecordSnapshot.model），用于完成通知显示。 */
-  model?: string;
-  result?: string;
-  error?: string;
-  startedAt: number;
-  endedAt: number | undefined;
-  /**
-   * 对话轮次计数（仅 idle 有意义）。dedup key 按 `id:round` 去重——对话模式每轮 round
-   * 不同，60s 内多轮不被吞；非 chatMode round 恒定（0/undefined），key 同旧 id 行为不变。
-   */
-  round?: number;
-  /** [MF#1] worktree 模式下子 agent 改动的 patch 路径（worktree 外，cleanup 后留存）。
-   *  done 时通知文本显式提示 `git apply`，否则 background 子 agent 在隔离 worktree 的改动
-   *  会静默丢失——父 LLM 不知 patch 路径，无法应用。 */
-  patchFile?: string;
-  /** [wave2] 子 agent session 文件路径（增量语义的全文恢复通道）。
-   *  仅 chatMode 透传（toNotifyRecord 条件透传）——轮次/完成通知末尾追加
-   *  "Full transcript: <path>" 指针行，父 LLM 可按需读全文；one-shot 不透传，
-   *  通知输出逐字节不变。缺失时 buildLlmContent 省略整行。 */
-  sessionFile?: string;
-  /** [U2] 通知身份键（投影边界物化 = dedupe key：`id` / `id:round`）。账本条目 /
-   *  回执匹配 / 幂等去重共用——details 携带（不进文案，G4 字节锁定不受影响），
-   *  重复注入条目凭此可识别为同一条（G2 at-least-once 幂等键）。 */
-  notifyId?: string;
-  /** [C-2] close 终态通知的轮次统计（文案 "completed after N rounds." 用）。
-   *  仅 chatMode close 语义（notifyClosed）构造时携带——此时 dedup 身份 round 已被
-   *  置 undefined（与轮次通知的 id:round key 区分，终态不被吞），轮数改由本字段进
-   *  文案。one-shot 完成通知不设置，文案保持 "completed. Result:" 逐字节（G4）。 */
-  totalRounds?: number;
-}
-
-/** notifier 依赖的宿主最小接口（解耦，便于测试）。
- *  迁移后：仅用于构造 DeliveryPort 的底层依赖。 */
-export interface NotifierHost {
-  /** 注入消息到主对话（U2 单通道：options 只接受 triggerTurn——多通道投递已删）。 */
-  sendMessage(
-    message: { customType: string; content: string; display: boolean; details?: unknown },
-    options?: { triggerTurn?: boolean },
-  ): void;
-  /** 是否还有 running 的 background 任务（用于滑动窗口立即 flush 判断）。 */
-  hasRunningBackground(): boolean;
-  /** 主 agent 是否空闲（非 streaming）。可选：未注入时 flush 不 gate。 */
-  isIdle?: () => boolean;
-  /**
-   * 原生 settled 事件订阅能力（D8）：注册 handler 监听主 agent settled 边沿。
-   * 无退订语义（pi 0.84.1 的 `pi.on(...)` 全部重载返回 void、无 off——实装锚点：
-   * node_modules `@earendil-works/pi-coding-agent` dist/core/extensions/types.d.ts
-   * `on()` 系列重载，0.84.1 实测）——退订由本模块的 disposed
-   * 标志包装兑现（见下方 port 装配）。可选：未注入时内核退化退避轮询（busy 消息
-   * 靠退避达上限强发，不走 settled 边沿驱动）。
-   */
-  onAgentSettled?(handler: () => void): void;
-}
-
-/**
- * 将 BgNotifyRecord 格式化为 LLM 可读的 notification content。
- *
- * 模块内唯一消费方是下方 createNotifier 的 notify()（预格式化后传 delivery.send，
- * 内核只做拼接——多条以 "\n\n---\n\n" join）。
- */
-function buildLlmContent(record: BgNotifyRecord): string {
-  const agent = record.agent;
-  const id = record.id;
-  // [wave2 指针行] 增量语义下轮次通知只携带本轮增量，异步 flush 窗口丢失时不可重发
-  //（见 subagent-service.ts onRoundSettled 注释），恢复通道是 session 文件全文。
-  // 仅 chatMode 透传 sessionFile，one-shot 通知不含该行；cancelled/gc-failed 不追加
-  //（无成功结果可读，指针无意义）；缺失时省略整行（追加空串 = 输出逐字节不变）。
-  const transcriptPointer = record.sessionFile
-    ? `\n\nFull transcript: ${record.sessionFile}`
-    : "";
-  switch (record.status) {
-    case "closed": {
-      // U3 C-outcome：终态文案只读 outcome（notify() 投影边界已物化；?? 兑底为防御
-      // 完整性——单一权威函数，非同构重写）。判定先于 patchFile——失败轮也会写
-      // patchFile（doFinalizeRecord Step 0 对 worktreeHandle 无条件 collectPatch），
-      // failed 分支不展示 patch 提示，否则 worktree 失败并存时 LLM 被告知 completed
-      // （历史 bug 存档见 deriveOutcome 注释）。
-      const outcome = record.outcome ?? deriveOutcome(record.closedReason, record.error);
-      if (outcome === "cancelled") {
-        return `Subagent "${agent}" (${id}) cancelled.`;
-      }
-      if (outcome === "failed") {
-        return `Subagent "${agent}" (${id}) failed: ${record.error}`;
-      }
-      // 成功完成或通用结束：展示结果。
-      // [C-2] chatMode close 终态通知附轮次统计（设计 D2 路径①"completed after N rounds"）。
-      // totalRounds 仅 close 语义携带（notifyClosed）；one-shot 完成通知不设置（round 无轮次
-      // 语义），文案保持 "completed. Result:" 逐字节（G4 硬约束，one-shot 字节锁测试锚定）。
-      const roundsSuffix =
-        record.totalRounds != null && record.totalRounds > 0
-          ? ` after ${record.totalRounds} round${record.totalRounds === 1 ? "" : "s"}`
-          : "";
-      const base = `Subagent "${agent}" (${id}) completed${roundsSuffix}. Result:\n${record.result ?? "(empty)"}`;
-      if (record.patchFile) {
-        // [wave2 review] 长 return 拆行：模板串内不可直接换行（会改变输出内容），提取 patchHint 中转变量
-        const patchHint = `\n\nThis subagent ran in an isolated worktree; its file changes were captured as a patch:\n  ${record.patchFile}\nTo bring these changes into the current repo, run: \`git apply ${record.patchFile}\``;
-        return `${base}${patchHint}${transcriptPointer}`;
-      }
-      return `${base}${transcriptPointer}`;
-    }
-    case "running":
-      // v4 B-1: 对话模式轮次完成（旧 idle 折入 running）：携带本轮结果送回主 agent，等待下一轮 message。
-      return `Subagent "${agent}" (${id}) finished a round. Reply:\n${record.result ?? "(empty)"}${transcriptPointer}`;
-  }
-}
-
-/**
- * Background 完成通知器接口（迁移后由内核实现）。
- *
- * 保持与旧 BgNotifier 类相同的公共 API，避免消费方（subagent-service）改动面过大。
- */
-export interface BgNotifier {
-  /** 入队一条完成通知（去重 + 合批窗口合并）。dispose 后短路。 */
-  notify(record: BgNotifyRecord): void;
-  /** 立即 flush（session_shutdown 调用，防丢失）。 */
-  flushPendingNotifications(): void;
-  /** session 结束：清队列，dispose 内核 handle。 */
-  dispose(): void;
-  /** /resume /fork /new 后复活。 */
-  revive(): void;
-}
-
-/**
- * 创建 Background 完成通知器（薄工厂）。
- *
- * ledger 装配时（bindNotifyLedgerHost）：四步生命周期接线（写账 → courier 边沿
- * 投递 → 回执销账 → notifyId 幂等，见 notify-ledger.ts）。未装配时：装配
- * @xyz-agent/session-delivery 内核——gate（isIdle 退避）/ 合批窗口（滑动 60s）/
- * dedup（按 id:round）/ flush / shutdown flush 均委托内核。
- * 本函数职责：BgNotifyRecord → 预格式化 content + notifyId 物化。
- *
- * @param host 宿主能力注入（pi.sendMessage + hasRunningBackground + isIdle）
- * @returns BgNotifier 接口（与旧类同形）
- */
-export function createNotifier(host: NotifierHost): BgNotifier {
-  let disposed = false;
-
-  // 构造 DeliveryPort：intent → pi 参数翻译在适配器内（D3）
-  const port: DeliveryPort = {
-    supportedPayloads: ["custom"],
-    isIdle: () => {
-      if (host.isIdle) {
-        return host.isIdle();
-      }
-      // 未注入 isIdle → 视为 idle（不 gate，向后兼容旧 host）
-      return true;
-    },
-    hasPendingMessages: () => false, // notifier 不关心 hasPendingMessages
-    // D8（must-fix #4）：settled 边沿驱动装配——内核 busy 入队后由 settled 事件唤醒
-    // flush（watch-dog 兜底事件丢失），替代无订阅时的退避轮询。host 只注入原生订阅
-    // 能力；disposed 标志包装（兑现退订语义——pi.on 返回 void 且无 off）在此完成。
-    subscribeSettled:
-      host.onAgentSettled === undefined
-        ? undefined
-        : (cb) => {
-            let disposed = false;
-            host.onAgentSettled?.(() => {
-              if (!disposed) cb();
-            });
-            return () => {
-              disposed = true;
-            };
-          },
-    send: (msg, _intent) => {
-      // D5 单通道：投递意图唯一化——steer/followUp/nextTurn 多通道全部删除，
-      // 唯一发送形态 = sendCustomMessage({triggerTurn:true})。busy 场景由 ledger
-      //（settled 边沿 + isIdle 二次复查）或内核 settled 订阅在空闲边沿驱动，
-      // 不在此层分流。返回 void = 受理成功（同步无异常；SendReceipt 扩展位留待
-      // 升级方接入）。
-      host.sendMessage(
-        {
-          customType: NOTIFY_CUSTOM_TYPE,
-          content: msg.payload.content,
-          display: true,
-          details: msg.payload.kind === "custom" ? msg.payload.details : undefined,
-        },
-        { triggerTurn: true },
-      );
-    },
-  };
-
-  // #5（must-fix）：内核 handle 的 disposed 不可逆——dispose 后 revive 必须重建 handle，
-  // 否则 revive 后所有 notify() 被内核静默吞（外层标志复位救不回已销毁的内核）。
-  // revive = 新生命周期：合批窗口 / 在途批次 / dedup LRU 随重建自然复位（可接受）。
-  const createHandle = (): DeliveryHandle =>
-    createDelivery(port, {
-      intent: "interrupt-at-turn-boundary",    // D3：turn 边界抢占（F1 教训内化）
-      mergeWindowMs: 60_000,                   // 滑动窗口合批（继承 MERGE_WINDOW_MS=60s）
-      mergeHoldActive: () => host.hasRunningBackground(), // D4 must-fix #1：禁止用 isIdle 代替
-      busyPolicy: "retry-force",               // settled 边沿驱动 + 退避达上限强发
-      backoff: { ms: 100, max: 50 },           // 继承 FLUSH_BACKOFF_MS/MAX
-      // dedup LRU：语义与旧 DEDUP_TTL_MS=60s **不同**——按 key 永久去重（仅 LRU 逐出后
-      // 同 key 可再入）。当前 key 空间（id / id:round，id 每 spawn 唯一）无实际差异；
-      // 后续复用方勿按「60s 内不重复」假设接入（同 key 通知会被永久吞）。
-      dedupe: { maxKeys: 1000 },
-      // U4 warn 出口参数化：内核投递失败警告接 extensionLogger（appendEntry 落
-      // session JSONL + XYZ_AGENT_DEBUG 落 <dataDir>/logs/），不再走 console.warn
-      // （stderr tee 不到日志盘——排查无痕，设计 §5 U4）。
-      warn: (msg, err) => notifyLogger.warn(msg, err),
-    });
-  let handle: DeliveryHandle = createHandle();
-
-  return {
-    notify(record: BgNotifyRecord): void {
-      if (disposed) return;
-
-      // U3 C-outcome：投影边界物化 outcome——closed payload 缺省时按单一权威
-      // deriveOutcome 兑底填充，content 与 details（GUI pane 消费）均携带一等 outcome；
-      // 所有可达流程下与 record.outcome 等价（toNotifyRecord 在 completeRecord 之后
-      // 构造）。running（轮次通知）语义上无 outcome，不物化。消源自 record 的浅拷贝
-      // ——不改写入方对象（BgNotifyRecord 由调用方持有）。notifyId 同批物化（U2：
-      // dedupe key 与账本身份键同源，details 携带供回执匹配）。
-      const notifyId = record.round != null ? `${record.id}:${record.round}` : record.id;
-      const payload: BgNotifyRecord =
-        record.status === "closed"
-          ? { ...record, outcome: record.outcome ?? deriveOutcome(record.closedReason, record.error), notifyId }
-          : { ...record, notifyId };
-
-      const content = buildLlmContent(payload);
-
-      // U2 B-ledger 四步接线（设计 D4/D5）：账本装配时①写账（appendEntry 先于一切
-      // 投递尝试）→ ②courier 边沿投递（settled 边沿 + 120s 看门狗 + isIdle 二次
-      // 复查）→ ③回执销账 / ④重放幂等均在 ledger 内。record 返回 false = 同
-      // notifyId 已在账或已销账（幂等去重，含重启恢复后的已送达账号零重发）。
-      const ledger = getBoundNotifyLedger();
-      if (ledger) {
-        if (!ledger.record(notifyId, content, payload)) return;
-        ledger.attemptDeliver();
-        return;
-      }
-
-      // 无 ledger 装配（旧装配 / 部分测试）：内核路径——合批窗口 / settled 边沿 /
-      // dedupe（按 notifyId，key 规则与旧 dedupeKey 一致：id 或 id:round）不变。
-      // [C-ext-06 配套] 降级留痕：bind 缺失（含 jiti 单例分裂致跨模块读不到绑定的
-      // 失效形态）本是无声分岔，U2 at-least-once 在此退化为内核路径——warn 一条
-      // 供诊断检索，不改变向后兼容行为。
-      notifyLogger.warn("notify ledger not bound, falling back to delivery kernel path (at-most-once)", {
-        notifyId,
-      });
-      handle.send({
-        payload: {
-          kind: "custom",
-          customType: NOTIFY_CUSTOM_TYPE,
-          content,
-          display: true,
-          details: payload,
-        },
-        dedupeKey: notifyId,
-      });
-    },
-
-    flushPendingNotifications(): void {
-      // ledger 路径：立即投递尝试（isIdle 复查，busy 则挂 pending 等边沿——账已落盘，
-      // 重启恢复兑底）；内核路径：flush。
-      const ledger = getBoundNotifyLedger();
-      if (ledger) {
-        ledger.attemptDeliver();
-        return;
-      }
-      handle.flush();
-    },
-
-    dispose(): void {
-      disposed = true;
-      handle.dispose();
-      // ledger 销毁（清看门狗 + 摘模块级绑定；settled 回调由 disposed 标志静默）。
-      // 未 bind 时 no-op。bind 归 index.ts session_start 装配，对称免受。
-      getBoundNotifyLedger()?.dispose();
-    },
-
-    revive(): void {
-      disposed = false;
-      // #5：内核 disposed 不可逆——revive 必须重建 handle（/resume /fork /new 后的
-      // session_start 时序：disposeAll → initSession → revive）。旧 handle 若仍存活
-      // （首次 session_start 的 revive）dispose 为幂等清理，无副作用。
-      handle.dispose();
-      handle = createHandle();
-    },
-  };
-}