@zhushanwen/pi-subagent-workflow 0.1.0

package/src/execution/finalized-marker.ts

@@ -0,0 +1,51 @@
+// src/runtime/execution/finalized-marker.ts
+//
+// Finalized 状态的 sidecar 持久化。
+//
+// 背景：subagent 执行完成（done/failed）后，session.jsonl 的最终写入可能因进程
+// 异常终止而丢失。`.finalized` sidecar 标记该 session 已正常结束，collectRecords
+// 重建时可用它区分「正常结束但文件截断」与「执行中断」。
+//
+// 设计：对称 cancelled sidecar（tombstone-store.ts）。`.finalized` 为空文件，
+// 存在性即信号（done/failed 的细分仍靠 recon.stopReason 推断）。与 `.cancelled`
+// 互斥——一个 session 要么 finalized 要么 cancelled，不可能两者兼有。
+//
+// best-effort：写 IO 错静默，不阻断主流程。
+
+import * as fs from "node:fs";
+
+// ============================================================
+// 公开函数
+// ============================================================
+
+/**
+ * 在 session.jsonl 旁写 `.finalized` sidecar（空文件）。
+ * best-effort：任何 I/O 错误静默（finalize 标记是次要信号，status 已在内存 record 上设好）。
+ *
+ * 与 `.cancelled` 互斥（BC-4）：写前删除 `.cancelled`（如存在），确保不会两者共存。
+ */
+export function writeFinalized(sessionFile: string): void {
+  try {
+    // BC-4 互斥：清理可能存在的 .cancelled。force:true 静默 ENOENT——
+    // 未 cancel 过的 session（done/failed/aborted）本就无 .cancelled，属正常路径。
+    // 此前用 unlinkSync+bestEffort 记 console.debug，取消嵌套链条时每层 ENOENT 刷屏。
+    fs.rmSync(`${sessionFile}.cancelled`, { force: true });
+    fs.writeFileSync(`${sessionFile}.finalized`, "", "utf-8");
+  } catch (_e) {
+    void _e; // 静默：写失败不阻断 finalize 主流程。
+  }
+}
+
+/**
+ * 读 session.jsonl 旁的 `.finalized` sidecar。
+ * 返回 true：sidecar 存在（内容不校验，存在性即信号）。
+ * 返回 false：sidecar 不存在 / 读取失败。
+ */
+export function readFinalized(sessionFile: string): boolean {
+  try {
+    fs.accessSync(`${sessionFile}.finalized`);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/execution/model-config-service.ts

@@ -0,0 +1,225 @@
+// src/runtime/model-config-service.ts
+//
+// 配置 + 模型解析领域 Service。"给定 agent 名 + 用户参数 + 主 agent 模型，用哪个模型？"
+//
+// 与 SubagentService（执行/记录/通知域）正交——本 Service 不碰 pool/store/notifier。
+// 上游：SubagentService.execute 内部调 resolveModel。
+// session_start 时经 initModel 注入 modelRegistry。
+
+import { findWorkspaceRoot } from "../shared/resource-discovery.ts";
+import { AgentRegistry, createPackageBuiltinRegistry } from "./agent-registry.ts";
+import {
+  loadGlobalConfig,
+} from "./config.ts";
+import {
+  type AgentConfig,
+  type ModelInfo,
+  type ModelRegistryLike,
+  type ResolvedModel,
+  resolveModel,
+} from "./model-resolver.ts";
+import type { SubagentsGlobalConfig } from "./types.ts";
+
+// ============================================================
+// 类型
+// ============================================================
+
+/** Service 构造参数（进程级，跨 session 不变）。 */
+export interface ModelConfigServiceInit {
+  agentDir: string;
+  /** 项目根目录（ctx.cwd，用于推导 workspaceRoot 扫描 project 级资源）。 */
+  cwd: string;
+}
+
+/** session_start 注入参数（session 级，每次重建）。 */
+export interface ModelServiceSessionInit {
+  /** 模型注册表（鉴权 + 发现）。null 立即抛错（fail-fast）。 */
+  modelRegistry: ModelRegistryLike | null;
+  /** 当前 session ID。 */
+  sessionId: string;
+  /**
+   * 主 agent 当前 model（session_start 时注入，model_select 时刷新）。
+   *
+   * renderCall 阶段的 ToolRenderContext 不含 model 字段（SDK 限制），无法直接拿到
+   * 主 agent model。缓存后 renderCall 的 resolveModel 能命中第三层（ctxModel），
+   * 让标题行恢复显示 model——即使未显式传 model 也能展示默认 model。
+   *
+   * [HISTORICAL] 99f20da1e 引入三层 fallback 后，renderCall 因拿不到 ctxModel
+   * 而 resolveModel 拗错→降级不显示 model。此缓存修复该降级。
+   */
+  ctxModel?: ModelInfo;
+}
+
+// ============================================================
+// ModelConfigService
+// ============================================================
+
+/**
+ * 配置 + 模型解析 Service。进程级单例。
+ *
+ *   ┌──────────────────────────────────────────────────────┐
+ *   │  globalConfig（~/.pi/.../config.json，仅 maxConcurrent）│
+ *   │  agentRegistry（agent .md 发现 + frontmatter）         │
+ *   │  modelRegistry（SDK 注入的可用模型）                    │
+ *   │                                                      │
+ *   │  resolveModel: override → agentConfig → 主 agent model │
+ *   └──────────────────────────────────────────────────────┘
+ */
+export class ModelConfigService {
+  private globalConfig: SubagentsGlobalConfig;
+  private readonly agentRegistry: AgentRegistry;
+  private readonly agentRegistryDir: string;
+  private readonly workspaceRoot: string;
+  private modelRegistry: ModelRegistryLike | null = null;
+  private _sessionId: string | undefined;
+  /** 主 agent 当前 model 缓存（session_start 注入，model_select 刷新）。 */
+  private _ctxModel: ModelInfo | undefined;
+
+  /** 包内 builtin agent（agents/*.md，优先级最低，被用户覆盖）。 */
+  private readonly builtinRegistry = createPackageBuiltinRegistry();
+
+  constructor(init: ModelConfigServiceInit) {
+    this.agentRegistryDir = init.agentDir;
+    this.workspaceRoot = findWorkspaceRoot(init.cwd);
+    this.globalConfig = loadGlobalConfig(init.agentDir);
+    // 统一资源发现（ADR-031）：扫描源由 workspaceRoot + agentDir 推导
+    this.agentRegistry = new AgentRegistry({
+      workspaceRoot: this.workspaceRoot,
+      agentDir: this.agentRegistryDir,
+    });
+    this.agentRegistry.discoverAll(this.builtinRegistry);
+  }
+
+  // ── 生命周期（index.ts 调）──────────────────────────────
+
+  /**
+   * session_start 注入。封装 3 步固定时序：
+   *   1. reloadGlobalConfig（复用时拿最新 config）
+   *   2. injectModelRegistry（fail-fast：null 抛错）
+   *   3. setSessionId
+   */
+  initModel(init: ModelServiceSessionInit): void {
+    // 1. 重载配置 + 重扫 agent（hot-reload：用户可能新增/修改 agent .md）
+    this.globalConfig = loadGlobalConfig(this.agentRegistryDir);
+    this.agentRegistry.discoverAll(this.builtinRegistry);
+
+    // 2. modelRegistry（fail-fast）
+    if (init.modelRegistry === null) {
+      throw new Error("modelRegistry is required but got null");
+    }
+    this.modelRegistry = init.modelRegistry;
+
+    // 3. sessionId + ctxModel 缓存（model_select 后续调 setCtxModel 刷新）
+    this._sessionId = init.sessionId;
+    this._ctxModel = init.ctxModel;
+  }
+
+  /**
+   * 刷新主 agent model 缓存。model_select 事件时调用。
+   * renderCall 的 resolveModel 读此缓存以显示标题行 model。
+   */
+  setCtxModel(model: ModelInfo | undefined): void {
+    this._ctxModel = model;
+  }
+
+  // ── 模型解析（SubagentService.execute 内部调）──────────────
+
+  /**
+   * 解析 agent 的模型（三层：override → agentConfig → 主 agent model）。
+   *
+   * @param agentName     agent 名（查 agentConfig.model override）
+   * @param override      调用方显式 override（最高优先级）
+   * @param ctxModel      主 agent 当前模型（兜底，直接透传）
+   */
+  resolveModel(
+    agentName: string,
+    override?: { model?: string; thinkingLevel?: string },
+    ctxModel?: ModelInfo,
+  ): ResolvedModel {
+    this.assertReady();
+    const agentConfig = this.agentRegistry.get(agentName);
+    // ctxModel 优先用显式传入（execute 路径），其次用 session 缓存（renderCall 路径）
+    return resolveModel(agentConfig, this.modelRegistry!, override, ctxModel ?? this._ctxModel);
+  }
+
+  /** 查询 agent 配置（SubagentService 内部判定 defaultBackground 用）。 */
+  getAgentConfig(name?: string): AgentConfig | undefined {
+    return name ? this.agentRegistry.get(name) : undefined;
+  }
+
+  // ── 配置读取（subagent-service 调）────────────────────────
+
+  /** 全局配置深拷贝（调用方拿到副本，改不影响 Service 内部）。 */
+  getGlobalConfig(): SubagentsGlobalConfig {
+    return structuredClone(this.globalConfig);
+  }
+
+  /** 内部：session id 缓存（initModel 注入；当前无消费者，保留供未来 session 作用域需求）。 */
+  get sessionId(): string | undefined {
+    return this._sessionId;
+  }
+
+  /** agent 配置目录（SubagentService 构造 store/SessionRunnerContext 时读）。 */
+  getAgentDir(): string {
+    return this.agentRegistryDir;
+  }
+
+  /**
+   * AgentRegistry 实例（workflow 域复用，F-4/D-003 统一）。
+   *
+   * workflow 域（resolveAgentOpts via LifecycleDeps.agentRegistry）需要与 subagents 域
+   * 完全相同的 agent 名→config 解析，复用本实例避免二次扫描。registry 在 initModel
+   * （每次 session_start）调 discoverAll hot-reload，两域共享同一份发现结果。
+   */
+  getAgentRegistry(): AgentRegistry {
+    return this.agentRegistry;
+  }
+
+  /** modelRegistry（SubagentService 构造 factoryCtx 时读）。已注入保证非 null。 */
+  getModelRegistry(): ModelRegistryLike {
+    if (this.modelRegistry === null) {
+      throw new Error("modelRegistry not injected (initModel not called?)");
+    }
+    return this.modelRegistry;
+  }
+
+  // ── 内部 ────────────────────────────────────────────────
+
+  /** 校验 modelRegistry 已注入。 */
+  private assertReady(): void {
+    if (this.modelRegistry === null) {
+      throw new Error("modelRegistry not injected (initModel not called?)");
+    }
+  }
+}
+
+// ============================================================
+// 进程单例访问器
+// ============================================================
+
+// 用 globalThis[Symbol.for] 持有进程单例，避免 jiti 因路径字符串不同加载多份模块
+// 导致单例分裂（详见 docs/standards.md §7.5）。
+const MODEL_SERVICE_SLOT_KEY = Symbol.for("@zhushanwen/pi-subagents.model-service");
+
+type ModelServiceSlot = { current: ModelConfigService | null };
+
+function getModelServiceSlot(): ModelServiceSlot {
+  // globalThis 无 symbol 索引签名，但运行时支持 symbol 键——用 Reflect 安全读写，
+  // 避免双重断言。ModelServiceSlot 是运行时保证的固定形状（同文件唯一写入点）。
+  let slot = Reflect.get(globalThis, MODEL_SERVICE_SLOT_KEY) as ModelServiceSlot | undefined;
+  if (!slot) {
+    slot = { current: null };
+    Reflect.set(globalThis, MODEL_SERVICE_SLOT_KEY, slot);
+  }
+  return slot;
+}
+
+/** 获取进程单例。session_start 前为 null。 */
+export function getModelConfigService(): ModelConfigService | null {
+  return getModelServiceSlot().current;
+}
+
+/** 设置进程单例（session_start 首次创建时）。 */
+export function setModelConfigService(service: ModelConfigService): void {
+  getModelServiceSlot().current = service;
+}

package/src/execution/model-resolver.ts

@@ -0,0 +1,247 @@
+// src/core/model-resolver.ts
+//
+// 模型解析（三层）：
+//   1. 用户显式 override（tool 参数 startParam.model）→ registry lookup + auth
+//   2. agent .md frontmatter model（agent 作者指定）→ registry lookup + auth
+//   3. 主 agent 当前模型（ctx.model）→ 直接透传，无需 lookup
+//
+// 设计：默认与主 agent 同模型（零配置）。只有「有人显式指定 model」时才查
+// registry 做解析 + 鉴权校验。thinkingLevel 同链路，无指定时 undefined。
+
+/**
+ * ModelRegistry 的最小接口（duck-typed，测试可 mock）。
+ * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐（见 shared/types stub）。
+ */
+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;
+}
+
+/** 解析结果（model 实例 + 生效的 thinkingLevel）。 */
+export interface ResolvedModel {
+  model: ModelInfo;
+  thinkingLevel: string | undefined;
+}
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** thinking level 支持顺序（低→高），用于 clamp 到 model 可用级别。 */
+const THINKING_ORDER = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+/** 解析失败时错误信息列出的可用模型上限（防超长错误信息）。 */
+const MODEL_LIST_LIMIT = 20;
+
+// ============================================================
+// 解析
+// ============================================================
+
+/**
+ * 三层模型解析：
+ *
+ *   ╔═══════════════════════════════════════════════════════════════╗
+//   ║  优先级（高→低）:                                              ║
+//   ║    1. paramOverride.model      （调用方显式指定，tool 参数）     ║
+//   ║    2. agentConfig.model        （agent .md frontmatter）        ║
+//   ║    3. ctxModel                 （主 agent 当前模型，直接透传）   ║
+//   ║                                                                ║
+//   ║  1/2 级查 registry + auth 校验；3 级无需 lookup（主 agent 在用  ║
+//   ║  说明 auth OK）。thinkingLevel 无指定时 undefined（model 默认） ║
+//   ║                                                                ║
+//   ║  显式指定但 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,
+      modelRegistry,
+      "paramOverride",
+    );
+  }
+
+  // 2. agentConfig.model（agent 作者指定）。同样显式 → 失败即抛错。
+  if (agentConfig?.model) {
+    return lookupAndResolve(
+      agentConfig.model,
+      agentConfig.thinkingLevel,
+      modelRegistry,
+      "agentConfig",
+    );
+  }
+
+  // 3. 主 agent model（直接透传，thinkingLevel 用 override 或 undefined）
+  if (ctxModel) {
+    return {
+      model: ctxModel,
+      thinkingLevel: paramOverride?.thinkingLevel ?? agentConfig?.thinkingLevel,
+    };
+  }
+
+  // 全部不可用 → 列出可用模型辅助调试
+  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。显式指定但失败 → 抛错（不降级）。
+ *
+ * 错误信息区分两种失败（避免误导排查方向）：
+ *   - model 不存在 → 提示检查拼写 + 列出相近可用 model
+ *   - model 存在但 auth 未配置 → 提示在 models.json 配置鉴权
+ */
+function lookupAndResolve(
+  modelStr: string,
+  requestedThinking: string | undefined,
+  registry: ModelRegistryLike,
+  source: "paramOverride" | "agentConfig",
+): ResolvedModel {
+  const model = lookupModel(modelStr, registry);
+  if (!model) {
+    throw new Error(
+      `Model "${modelStr}" (${source}) not found in registry. ` +
+        suggestSimilarModels(modelStr, registry),
+    );
+  }
+  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,
+    thinkingLevel: resolveThinkingLevel(model, requestedThinking),
+  };
+}
+
+/**
+ * 解析 "provider/modelId" 并查 registry。
+ *
+ * 容错：剥离尾部 ":thinkingLevel" 后缀（off/minimal/low/medium/high/xhigh）。
+ * 原因：LLM 常把平台复合标识 "provider/modelId:thinkingLevel"（如
+ * "deepseek-router/ds-pro:xhigh"）整体当 model 参数传入。registry 仅存
+ * "provider/modelId"（无后缀），不剥离则 modelId="ds-pro:xhigh" 查不到。
+ * 剥离后 thinkingLevel 仍由独立的 thinkingLevel 参数/resolveThinkingLevel 处理。
+ *
+ * modelId 可含 /，按第一个 / 分割 provider 与 modelId。
+ */
+function lookupModel(modelStr: string, registry: ModelRegistryLike): ModelInfo | undefined {
+  const cleanStr = stripThinkingSuffix(modelStr);
+  const idx = cleanStr.indexOf("/");
+  if (idx <= 0) return undefined;
+  return registry.find(cleanStr.slice(0, idx), cleanStr.slice(idx + 1));
+}
+
+/**
+ * 剥离模型字符串尾部 ":thinkingLevel" 后缀（如 "ds-pro:xhigh" → "ds-pro"）。
+ * 仅匹配合法 thinking level，避免误剥 "foo:bar" 这类无关冒号。
+ * 返回去除后缀的字符串；无后缀则原样返回。
+ */
+function stripThinkingSuffix(modelStr: string): string {
+  // THINKING_ORDER 含 off/minimal/low/medium/high/xhigh，按长度降序拼正则避免短串误匹配
+  const alt = THINKING_ORDER.slice().sort((a, b) => b.length - a.length).join("|");
+  return modelStr.replace(new RegExp(`:(${alt})$`), "");
+}
+
+/**
+ * 为 not-found 错误生成「相近可用 model」建议，辅助定位拼写错误。
+ * 策略：取 provider/modelId 的末段，与每个可用 model 的末段做小写包含匹配，
+ * 命中则列出。无命中则列出前 N 个全部可用 model（兜底）。空 registry 不列。
+ */
+function suggestSimilarModels(modelStr: string, registry: ModelRegistryLike): string {
+  const available = registry.getAvailable();
+  if (available.length === 0) return "Registry has no available models.";
+  const target = modelStr.split("/").pop()?.toLowerCase() ?? "";
+  // ponytail: 末段子串包含足够定位拼写错误，无需编辑距离/相似度库
+  const similar = available
+    .filter((m) => m.id.toLowerCase().includes(target) || target.includes(m.id.toLowerCase()))
+    .map((m) => `${m.provider}/${m.id}`)
+    .slice(0, MODEL_LIST_LIMIT);
+  const list = similar.length > 0 ? similar : available.slice(0, MODEL_LIST_LIMIT).map((m) => `${m.provider}/${m.id}`);
+  return `Check the model string (maybe a typo, or a ":thinkingLevel" suffix that should be passed via the thinkingLevel param instead). Similar available models:\n  ${list.join("\n  ")}`;
+}
+
+/**
+ * 从 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

@@ -0,0 +1,168 @@
+// src/execution/notifier.ts
+//
+// Background 完成回注主对话。sync 不用（调用方还在 await，结果直接返回）。
+//
+// 职责：
+//   - 合并窗口：MERGE_WINDOW_MS 内多个完成合并为一条通知
+//   - 去重 TTL：同 id 在 TTL 内不重复通知
+//   - 通过 pi.sendMessage({ deliverAs:"followUp", triggerTurn:true }) 注入——
+//     当前 turn 结束后唤醒父 agent 处理结果（followUp 不打断 streaming、不锁滚动）
+
+/** 一条待发送的完成通知记录。 */
+export interface BgNotifyRecord {
+  id: string;
+  status: "done" | "failed" | "cancelled";
+  agent: string;
+  /** 执行所用 model（RecordSnapshot.model），用于完成通知显示。 */
+  model?: string;
+  result?: string;
+  error?: string;
+  startedAt: number;
+  endedAt: number | undefined;
+  /** [MF#1] fork+worktree 模式下子 agent 改动的 patch 路径（worktree 外，cleanup 后留存）。
+   *  done 时通知文本显式提示 `git apply`，否则 background 子 agent 在隔离 worktree 的改动
+   *  会静默丢失——父 LLM 不知 patch 路径，无法应用。 */
+  patchFile?: string;
+}
+
+/** notifier 依赖的 pi 最小接口（解耦，便于测试）。 */
+export interface NotifierHost {
+  /** 注入消息到主对话。
+   *  triggerTurn:true + deliverAs:"followUp" → 当前 streaming 结束后唤醒父 agent
+   *  处理结果（不打断、不锁滚动）；空闲时立即 prompt 新 turn。 */
+  sendMessage(
+    message: { customType: string; content: string; display: boolean; details?: unknown },
+    options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+  ): void;
+  /** 是否还有 running 的 background 任务（用于滑动窗口立即 flush 判断）。 */
+  hasRunningBackground(): boolean;
+}
+
+/** 合并窗口（ms）。窗口内多个完成合并为一条消息。 */
+const MERGE_WINDOW_MS = 60_000;
+/** 去重 TTL（ms）。同 id 在此窗口内不重复通知。 */
+const DEDUP_TTL_MS = 60_000;
+
+/** 发送给主对话的 customType（bg-notify-render 消费）。 */
+const NOTIFY_CUSTOM_TYPE = "subagent-bg-notify";
+
+/**
+ * Background 完成通知器（滑动窗口合并）。
+ *
+ *   notify(record):
+ *     1. dedup TTL 检查：同 id 在 TTL 内 → 跳过
+ *     2. 入 pending 队列
+ *     3. 清除旧 timer（滑动窗口重置）
+ *     4. 已无 running background → 立即 flush（最后一批）
+ *     5. 否则重启 MERGE_WINDOW_MS timer（等后续完成合并）
+ *
+ *   flushPendingNotifications():  timer 到期 / 无 running / shutdown 触发
+ *     1. 取出 pending 全部 record
+ *     2. 合并为一条消息（多条时列 bullet list）
+ *     3. sendMessage({ customType:"subagent-bg-notify",
+ *                     content, display:true,
+ *                     triggerTurn:true, deliverAs:"followUp" })
+ *     4. 清空 pending + timer
+ *
+ * 滑动窗口：每次有新完成都重置 60s 计时器，密集完成的任务尽量合并到一条通知。
+ * 无 running 时立即 flush——避免最后一条等满窗口。
+ */
+export class BgNotifier {
+  private readonly pending: BgNotifyRecord[] = [];
+  /** dedup：id → 上次通知时间戳。 */
+  private readonly dedup = new Map<string, number>();
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private _disposed = false;
+
+  constructor(private readonly host: NotifierHost) {}
+
+  /**
+   * 入队一条完成通知（去重 + 滑动窗口合并）。dispose 后短路。
+   */
+  notify(record: BgNotifyRecord): void {
+    if (this._disposed) return;
+
+    const now = Date.now();
+    // sweep 过期 dedup 条目（防 Map 无限增长）
+    if (this.dedup.size > 0) {
+      for (const [id, ts] of this.dedup) {
+        if (now - ts >= DEDUP_TTL_MS) this.dedup.delete(id);
+      }
+    }
+    const lastSeen = this.dedup.get(record.id);
+    if (lastSeen !== undefined && now - lastSeen < DEDUP_TTL_MS) return;
+    this.dedup.set(record.id, now);
+
+    this.pending.push(record);
+
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+
+    if (!this.host.hasRunningBackground()) {
+      this.flushPendingNotifications();
+      return;
+    }
+
+    this.timer = setTimeout(() => this.flushPendingNotifications(), MERGE_WINDOW_MS);
+  }
+
+  /** 立即 flush（session_shutdown 调用，防丢失）。 */
+  flushPendingNotifications(): void {
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+    if (this.pending.length === 0) return;
+
+    const records = this.pending.splice(0);
+    const content = records.length === 1
+      ? this.buildLlmContent(records[0])
+      : records.map((r) => this.buildLlmContent(r)).join("\n\n---\n\n");
+    const details = records.length === 1
+      ? records[0]
+      : { batch: true, items: records };
+
+    this.host.sendMessage({
+      customType: NOTIFY_CUSTOM_TYPE,
+      content,
+      display: true,
+      details,
+    }, { triggerTurn: true, deliverAs: "followUp" });
+  }
+
+  private buildLlmContent(record: BgNotifyRecord): string {
+    const agent = record.agent;
+    const id = record.id;
+    switch (record.status) {
+      case "done": {
+        const base = `Subagent "${agent}" (${id}) completed. Result:\n${record.result ?? "(empty)"}`;
+        if (record.patchFile) {
+          return `${base}\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;
+      }
+      case "failed":
+        return `Subagent "${agent}" (${id}) failed: ${record.error ?? "(unknown error)"}`;
+      case "cancelled":
+        return `Subagent "${agent}" (${id}) cancelled.`;
+    }
+  }
+
+  /** session 结束：清 timer，丢弃 pending。 */
+  dispose(): void {
+    this._disposed = true;
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+    this.pending.length = 0;
+    this.dedup.clear();
+  }
+
+  /** /resume /fork /new 后复活。 */
+  revive(): void {
+    this._disposed = false;
+  }
+}