@zhushanwen/pi-subagent-workflow 0.1.0 → 0.3.0

package/src/execution/channel-registry-access.ts

@@ -0,0 +1,138 @@
+// src/execution/channel-registry-access.ts
+//
+// Channel registry 的访问入口（本扩展内部用 + 契约文档化导出）。
+//
+// ask-user 等扩展通过本模块注册 channel handler，让 subagent 子进程的 UI 请求
+// 能透传到主进程渲染。所有扩展各自直接读写
+// globalThis[Symbol.for("@zhushanwen/pi-subagents.channelHandshake")]，
+// 拿到结构兼容 ChannelRegistryHandshake 的同一握手对象。
+//
+// ── 升级说明（决策 D 修复 M4）─────────────────────────────────
+// 历史问题：原协议槽位直接存 UiChannelRegistry 实例，谁先 session_start 谁创建。
+// ask-user 先到时会自建简化 registry 占位，劫持 canonical 槽位，subagent-workflow
+// 后到时拿到的是 ask-user 的非 canonical 实例，行为不一致。
+//
+// 修复：槽位从「存 registry 实例」升级为「存握手对象 {version, registry?, pending[]}」。
+// canonical registry 实例永远由 subagent-workflow 单一创建点（本模块的
+// getOrCreateChannelRegistry）实例化。ask-user 先到时只往 pending 推 handler，
+// 等 subagent-workflow 来 flush；subagent-workflow 先到时直接创建 registry 并
+// 接收后续 ask-user 推入的 pending。
+//
+// ── 跨扩展协议契约（必须与 ask-user 侧严格一致）──────────────
+// key 字面量：     "@zhushanwen/pi-subagents.channelHandshake"
+//                  ↑ 必须与 ask-user/src/channel-registry-register.ts 完全一致
+// handshake 形状： ChannelRegistryHandshake（version=1）
+// version 守卫：    slot.version !== 1 时 console.warn + 丢弃重建（向前兼容未来升级）
+
+import { createUiChannelRegistry, type UiChannelRegistry, type ChannelHandler } from "./ui-channels.ts";
+
+/** 进程级 channel 握手的 globalThis key（Symbol.for 跨模块共享）。
+ *
+ *  **协议契约**：字面量 `"@zhushanwen/pi-subagents.channelHandshake"` 必须与
+ *  ask-user 扩展的 `ask-user/src/channel-registry-register.ts` 完全一致——
+ *  两边读写同一个 Symbol.for key 才能拿到同一握手对象。
+ *
+ *  改名历史：原 `CHANNEL_REGISTRY_KEY`（字面量 `...channelRegistry`）在决策 D
+ *  中升级为 `CHANNEL_HANDSHAKE_KEY`（字面量 `...channelHandshake`），槽位形状
+ *  从 registry 实例改为握手对象。 */
+export const CHANNEL_HANDSHAKE_KEY = Symbol.for("@zhushanwen/pi-subagents.channelHandshake");
+
+/** 握手版本。未来若形状不兼容升级，递增此常量并在 getOrCreateChannelRegistry
+ *  的 version 守卫里加迁移逻辑。 */
+const HANDSHAKE_VERSION = 1 as const;
+
+/** pending channel handler 条目。ask-user 先到、registry 未就绪时临时存放。 */
+export interface ChannelRegistryHandshakePendingEntry {
+  channel: string;
+  handler: ChannelHandler;
+}
+
+/** 跨扩展 channel registry 握手对象（globalThis 槽位形状）。
+ *
+ *  - `version`：协议版本，当前固定 1。读取时若 ≠1 视为不兼容，丢弃重建。
+ *  - `registry`：canonical UiChannelRegistry 实例。仅由 subagent-workflow 的
+ *    getOrCreateChannelRegistry 创建并填充。未就绪时为 undefined。
+ *  - `pending`：ask-user 在 registry 就绪前推入的 handler 条目。
+ *    subagent-workflow 创建 registry 后逐条 flush（注册），然后清空。 */
+export interface ChannelRegistryHandshake {
+  version: typeof HANDSHAKE_VERSION;
+  registry?: UiChannelRegistry;
+  pending: ChannelRegistryHandshakePendingEntry[];
+}
+
+/** 读取握手槽位；若 version 不匹配则视为缺失（warn + 返回 undefined）。
+ *  类型不安全的 globalThis 反射访问集中在本函数，外层逻辑保持类型严谨。 */
+function readHandshakeSlot(): ChannelRegistryHandshake | undefined {
+  const slot = Reflect.get(globalThis, CHANNEL_HANDSHAKE_KEY) as unknown;
+  if (slot === undefined) return undefined;
+  // 形状校验：必须是对象且 version===1，否则视为不兼容
+  if (typeof slot !== "object" || slot === null) {
+    console.warn(
+      "[pi-subagent-workflow] channel handshake slot is not an object; discarding and recreating.",
+    );
+    return undefined;
+  }
+  const version = (slot as { version?: unknown }).version;
+  if (version !== HANDSHAKE_VERSION) {
+    console.warn(
+      `[pi-subagent-workflow] channel handshake version mismatch (got ${String(
+        version,
+      )}, expected ${HANDSHAKE_VERSION}); discarding and recreating.`,
+    );
+    return undefined;
+  }
+  // version 正确，但 pending 可能被恶意/错误地塞了非数组；防御性处理
+  const candidate = slot as ChannelRegistryHandshake;
+  if (!Array.isArray(candidate.pending)) {
+    console.warn(
+      "[pi-subagent-workflow] channel handshake pending is not an array; discarding and recreating.",
+    );
+    return undefined;
+  }
+  return candidate;
+}
+
+/** 将 pending 条目逐个注册进 registry，注册完清空 pending。
+ *  pending 内部 entry 的形状由 ask-user 侧保证，此处不再二次校验。 */
+function flushPending(registry: UiChannelRegistry, pending: ChannelRegistryHandshakePendingEntry[]): void {
+  for (const entry of pending) {
+    registry.register(entry.channel, entry.handler);
+  }
+}
+
+/** 获取或创建进程级 channel registry（canonical 单例）。
+ *
+ *  **唯一创建点**：canonical UiChannelRegistry 实例仅由本函数创建。
+ *  ask-user 扩展绝不自建 registry——它在 registry 未就绪时只往 slot.pending 推条目。
+ *
+ *  行为分支：
+ *    1. 槽位不存在或 version ≠ 1 → warn（version 不匹配时）+ 建新 slot
+ *       `{version:1, pending:[], registry:<newly created>}`
+ *    2. 槽位存在但 registry 未就绪（ask-user 先到过，塞过 pending）→
+ *       创建 canonical registry + flush pending + 清空 pending
+ *    3. 槽位存在且 registry 已就绪（本函数已被调用过）→
+ *       直接返回同一实例引用（===），不重建、不重复 flush
+ *
+ *  @returns 进程级 canonical UiChannelRegistry 单例（永不返回 undefined） */
+export function getOrCreateChannelRegistry(): UiChannelRegistry {
+  let slot = readHandshakeSlot();
+  if (slot === undefined) {
+    // 分支 1：无合规槽位，新建并立即创建 canonical registry
+    const registry = createUiChannelRegistry();
+    slot = { version: HANDSHAKE_VERSION, registry, pending: [] };
+    Reflect.set(globalThis, CHANNEL_HANDSHAKE_KEY, slot);
+    return registry;
+  }
+  if (slot.registry === undefined) {
+    // 分支 2：ask-user 先到过，flush pending 进 canonical registry
+    const registry = createUiChannelRegistry();
+    flushPending(registry, slot.pending);
+    slot.pending = [];
+    slot.registry = registry;
+    return registry;
+  }
+  // 分支 3：registry 已就绪，返回同一实例
+  return slot.registry;
+}
+
+export type { UiChannelRegistry, ChannelHandler };

package/src/execution/concurrency-pool.ts

@@ -2,17 +2,22 @@
 //
 // 并发控制 + 优先级排队。background=1000（单一优先级，保留 priority 机制供未来扩展）。
 
-/** 队列条目：优先级 + resolver + 入队序号（同优先级 FIFO）。 */
+/** 队列条目：优先级 + resolver + rejecter + 入队序号（同优先级 FIFO）。 */
 interface QueueEntry {
   priority: number;
   resolve: () => void;
+  reject: (err: Error) => void;
   seq: number;
+  /** abort listener（用于 resolve/abort 时清理）。 */
+  onAbort?: () => void;
+  /** 关联的 signal（用于 resolve 时 removeEventListener）。 */
+  signal?: AbortSignal;
 }
 
 /** 并发池接口（可注入，便于测试 mock）。 */
 export interface ConcurrencyPool {
-  /** 按优先级排队获取槽位（0=最高）。可选 effectiveMaxConcurrent 覆盖实例级默认配额。 */
-  acquire(priority: number, effectiveMaxConcurrent?: number): Promise<void>;
+  /** 按优先级排队获取槽位（0=最高）。可选 effectiveMaxConcurrent 覆盖实例级默认配额。可选 AbortSignal 在 abort 时 reject 排队条目。 */
+  acquire(priority: number, effectiveMaxConcurrent?: number, signal?: AbortSignal): Promise<void>;
   /** 归还槽位。必须无条件执行（finally）。 */
   release(): void;
   /** 当前已占用槽位数（诊断/widget 用）。 */
@@ -45,7 +50,7 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
     this.maxConcurrent = Math.max(1, maxConcurrent);
   }
 
-  acquire(priority: number, effectiveMaxConcurrent?: number): Promise<void> {
+  acquire(priority: number, effectiveMaxConcurrent?: number, signal?: AbortSignal): Promise<void> {
     // effectiveMaxConcurrent 覆盖实例级默认配额（分层配额：调用方传 max(1, maxConcurrent - depth)）。
     // 不修改实例级 maxConcurrent——实例配额是全局共享上限，分层配额是本次 acquire 的局部上限。
     const effective = effectiveMaxConcurrent ?? this.maxConcurrent;
@@ -53,8 +58,31 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
       this._active += 1;
       return Promise.resolve();
     }
-    return new Promise<void>((resolve) => {
-      this.queue.push({ priority, resolve, seq: this.seqCounter++ });
+    return new Promise<void>((resolve, reject) => {
+      const entry: QueueEntry = { priority, resolve, reject, seq: this.seqCounter++ };
+      // H2: abort 时 reject 排队条目并从 queue 移除，防止永久挂起
+      if (signal) {
+        if (signal.aborted) {
+          // S1: abort reject 需带 name="AbortError"，对齐 concurrency-gate.ts 的 AbortError 语义
+          const err = new Error("acquire aborted");
+          err.name = "AbortError";
+          reject(err);
+          return;
+        }
+        entry.signal = signal;
+        entry.onAbort = (): void => {
+          const idx = this.queue.indexOf(entry);
+          if (idx >= 0) {
+            this.queue.splice(idx, 1);
+            // S1: abort reject 需带 name="AbortError"，与 pre-aborted 分支一致
+            const err = new Error("acquire aborted");
+            err.name = "AbortError";
+            reject(err);
+          }
+        };
+        signal.addEventListener("abort", entry.onAbort, { once: true });
+      }
+      this.queue.push(entry);
     });
   }
 
@@ -70,6 +98,10 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
         }
       }
       const next = this.queue.splice(bestIdx, 1)[0];
+      // H2: 条目已获槽位——移除 abort listener（防 listener 泄漏到长生命周期 signal）
+      if (next.onAbort && next.signal) {
+        next.signal.removeEventListener("abort", next.onAbort);
+      }
       next.resolve();
       // active 不变（一个离开队列立即进入活跃）
     } else if (this._active > 0) {

package/src/execution/dialog-queue.ts

@@ -0,0 +1,329 @@
+// src/execution/dialog-queue.ts
+//
+// L2 跨子进程全局 dialog 串行队列。
+//
+// 进程单例语义：跨所有子进程共享，串行所有 dialog 类 UI 请求
+//（isDialogMethod(method)===true，即 select/confirm/input/editor）。
+//
+// 设计动机（.fix-plans/00-master-summary.md §一 冲突 3）：
+//   - L1 per-child 队列（session-runner.createUiRequestQueue）只解决同一子进程内的串行，
+//     多个并行子进程仍可同时把 dialog 请求涌向父 UI（争输入焦点）。
+//   - L2 全局队列在主 agent handler 入口前再串行一次，保证同一时刻主 agent 只呈现一个 dialog。
+//   - 排队绑定 method 交互模型（dialog 才排队），不绑定 channel——排队是 Pi 协议固有属性。
+//
+// SR-4（child close reject）：入队项带 child 引用，child close 时把该 child 的 pending dialog
+//   全部 resolve 为 {cancelled:true}，防 Promise 永挂 + 内存泄漏。
+//
+// handler 抛错兜底：catch → 回 {cancelled:true} → 继续处理下一个。不能让一个失败卡死队列。
+//
+// 调用方约定：只对 dialog 类（isDialogMethod===true）调 enqueue；fire-and-forget 由调用方
+//   直接调 handler（见 ui-request-handler-factory.ts），不经过本队列。enqueue 内仍防御性兼容
+//   fire-and-forget（万一调用方未判）：直接调 handler 返回，不入队串行。调用方不应依赖此防御。
+
+import { isDialogMethod } from "./ui-interaction-model.ts";
+
+// ── 类型定义（本模块是 UiRequest/UiResponse/UiRequestHandler 的规范来源） ──
+// session-runner.ts 和 ui-channels.ts 复用这些类型（session-runner 再导出供测试 import）。
+
+/** Pi extension_ui_request 的方法枚举（dialog + fire-and-forget 两类）。
+ *  dialog 类：select/confirm/input/editor（占输入焦点，等响应）。
+ *  fire-and-forget 类：notify/setStatus/setWidget/setTitle/set_editor_text（纯展示/写入）。
+ *  (string & {}) 兜底：Pi 未来新增 method 或未知 method 走字符串字面量类型。 */
+export type UiMethod =
+  | "select"
+  | "confirm"
+  | "input"
+  | "editor"
+  | "notify"
+  | "setStatus"
+  | "setWidget"
+  | "setTitle"
+  | "set_editor_text"
+  | (string & {});
+
+/** UI 请求（session-runner 构造后传给 handler）。
+ *
+ *  method 是判别字段，决定排队策略（dialog 排队）和业务路由（channel 分发）。
+ *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由 session-runner 从
+ *  ExtensionUiRequest 平铺构造）。channel/channelPayload 由 parseChannel 填充。
+ *
+ *  契约来源：.fix-plans/00-master-summary.md §二 2.2。 */
+export interface UiRequest {
+  /** Pi rpc-types.ts 的 method（select/confirm/input/editor 为 dialog 类）。 */
+  method: UiMethod;
+  /** 请求 id（从 extension_ui_request envelope 顶层提取，用于 response 关联）。 */
+  id: string;
+  // method 特定字段（按 method 可选，与 ExtensionUiRequest 1:1）
+  title?: string;
+  options?: string[];
+  message?: string;
+  placeholder?: string;
+  prefill?: string;
+  notifyType?: string;
+  statusKey?: string;
+  statusText?: string | undefined;
+  widgetKey?: string;
+  widgetLines?: string[] | undefined;
+  widgetPlacement?: "aboveEditor" | "belowEditor";
+  text?: string;
+  timeout?: number;
+  /** channel 名（从 method 对应字段的 NUL 前缀解析）。
+   *  select → 从 title 解析；setWidget → 从 widgetLines[0] 解析；其他 → undefined。
+   *  已知值："ask_user"（select）、"gui_widget"（setWidget）。handler 按 channel 分发。 */
+  channel?: string;
+  /** channel 解析后的结构化 payload（已 JSON.parse）。
+   *  ask_user: {questions, allowCancel}；gui_widget: {component}；无 channel: undefined。 */
+  channelPayload?: unknown;
+  /** 内部元数据字段：发起该 UI 请求的子进程 pid（由 session-runner.handleUiRequest 从
+   *  child.pid 填入）。L2 队列据此关联 rejectChildDialogs（child close 时批量 reject）。
+   *  下划线前缀表示内部字段，非 Pi 协议字段，不参与 stdin 回写。 */
+  _childPid?: number;
+}
+
+/** UI 响应（handler 返回，session-runner 按 shape 回写 stdin）。
+ *  - {value}: select/input/editor 的答案
+ *  - {confirmed}: confirm 的答案
+ *  - {cancelled}: 取消（child close / handler 抛错 / 用户取消）
+ *  - {ack}: fire-and-forget（当前不透传到 TUI，留作协议完整） */
+export type UiResponse =
+  | { value: string }
+  | { confirmed: boolean }
+  | { cancelled: true }
+  | { ack: true };
+
+/** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
+ *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
+ *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */
+export type UiRequestHandler = (req: UiRequest) => Promise<UiResponse>;
+
+// ── DialogGlobalQueue 实现 ──
+
+/** 入队项的 child 引用形状（只取 pid 用于 rejectChildDialogs 匹配）。 */
+export interface DialogChildRef {
+  pid: number;
+}
+
+/** enqueue 的可选项。child 用于 rejectChildDialogs 关联（child close 时批量 reject）。 */
+export interface EnqueueOptions {
+  child?: DialogChildRef;
+}
+
+/** 队列内一项：请求 + handler + resolve + 所属 child。
+ *  pending 状态持有 resolve，handler 完成 / rejectChildDialogs 时调它 settle Promise。
+ *  settled 标志保证只 settle 一次（rejectChildDialogs 与 handler 完成可能竞争）。 */
+interface QueueItem {
+  req: UiRequest;
+  handler: UiRequestHandler;
+  resolve: (resp: UiResponse) => void;
+  childPid: number | undefined;
+  /** 是否已 settle（防 handler 完成 / rejectChildDialogs 重复 resolve）。 */
+  settled: boolean;
+}
+
+/**
+ * L2 跨子进程全局 dialog 串行队列（进程单例）。
+ *
+ * 用法（createUiRequestHandlerForMode 返回的总 handler 内）：
+ * ```ts
+ * const dialogQueue = new DialogGlobalQueue();
+ * return async (req: UiRequest) => {
+ *   // 调用方负责判断：dialog 入队，fire-and-forget 直接调 realHandler
+ *   if (isDialogMethod(req.method)) return dialogQueue.enqueue(req, realHandler);
+ *   return realHandler(req);
+ * };
+ * ```
+ *
+ * 语义保证：
+ *   - FIFO 串行：前一个 handler settle 后才处理下一个
+ *   - SR-4：rejectChildDialogs(child) 把该 child 的 pending 全部 resolve 为 {cancelled:true}
+ *   - handler 抛错兜底：catch → {cancelled:true} → 继续下一个（队列不卡死）
+ *   - 调用方约定只对 dialog 类调 enqueue；fire-and-forget 由调用方直接调 handler 不入队
+ *（enqueue 内仍防御性兼容 fire-and-forget，但不保证行为）
+ *
+ * 线程模型：纯 Promise + 微任务驱动，无锁。Node 单线程 event loop 保证队列状态一致。
+ *
+ * 单 session 假设（M-2，与 index.ts lastSessionId 同源）：本队列是进程级单例（实例挂在
+ * globalThis[Symbol.for("@zhushanwen/pi-subagents.dialogQueue")]，见 getOrCreateDialogQueue）。
+ * rejectAll()/clear() 清空所有 pending dialog——无 per-session 隔离。Pi 当前架构保证单进程
+ * 单 session 串行（同进程不会并发多个 session），故 session_shutdown 调 rejectAll() 只会清掉
+ * 当前 session 的 pending。若未来 Pi 支持同进程多 session 并发，session A 退出会误清 session B
+ * 的 pending dialog——届时需改为 per-session 隔离（入队项 QueueItem 带 sessionId，rejectAll
+ * 改 rejectAllForSession(sessionId)，session_shutdown 只清当前 session）。
+ */
+export class DialogGlobalQueue {
+  /** 等待处理的队列（FIFO）。正在处理的项从 queue shift 出后由 current 持有。 */
+  private queue: QueueItem[] = [];
+  /** 正在处理的项（handler 已调、未 settle）。用于 rejectChildDialogs 取消占位中的 dialog。 */
+  private current: QueueItem | undefined;
+  private processing = false;
+
+  /**
+   * 入队一个 UI 请求，返回 Promise<UiResponse>。
+   *
+   * 调用方约定：只对 dialog 类（isDialogMethod===true）调 enqueue。fire-and-forget 由
+   * 调用方（ui-request-handler-factory.ts）在 enqueue 前判 isDialogMethod 后直接调 handler，
+   * 不经过本队列。enqueue 内仍防御性兼容 fire-and-forget（万一调用方未判）：直接调 handler 返回，
+   * 不入队串行，但调用方不应依赖此防御行为。
+   *
+   * dialog 项处理（TC-E4 case 1）：进队列 FIFO 串行，等前一个 settle 后才调 handler
+   *（争输入焦点，防并发弹窗）。
+   *
+   * handler 抛错兜底：catch → 回 {cancelled:true}（dialog 路径，队列不卡死）。
+   * SR-4：opts.child 用于 rejectChildDialogs 关联（dialog 项会被批量 reject，含 current）。
+   *
+   * @param req UI 请求（约定只传 dialog 类；fire-and-forget 防御性兼容）
+   * @param handler 真正执行请求的 handler（TUI/GUI 模式分流后的 realHandler）
+   * @param opts 可选 child 引用（用于 rejectChildDialogs 关联）
+   * @returns handler 的响应；dialog 抛错时回 {cancelled:true}；child close 时回 {cancelled:true}
+   */
+  enqueue(
+    req: UiRequest,
+    handler: UiRequestHandler,
+    opts?: EnqueueOptions,
+  ): Promise<UiResponse> {
+    // 防御性兼容 fire-and-forget：调用方约定不应传此类 req 进 enqueue（factory 层已判
+    // isDialogMethod 直接调 handler），但万一调用方未判，这里直接调 handler 不入队，避免阻塞。
+    // 直接返回 handler 真实结果（不做兜底形变为 cancelled——fire-and-forget 无串行语义）。
+    if (!isDialogMethod(req.method)) {
+      return handler(req);
+    }
+    // dialog：入队 FIFO 串行
+    return new Promise<UiResponse>((resolve) => {
+      this.queue.push({
+        req,
+        handler,
+        resolve,
+        childPid: opts?.child?.pid,
+        settled: false,
+      });
+      void this.processNext();
+    });
+  }
+
+  /**
+   * settle 一个 item（幂等）。handler 完成 / rejectChildDialogs / rejectAll 都通过本方法，
+   * settled 标志保证只 settle 一次（防竞争）。
+   *
+   * #19 单一推进点：本方法 settle Promise + 清状态后，**唯一**调 processNext 推进队列。
+   * processNext 尾部不再调 processNext（旧代码双重推进，虽靠 processing 标志幂等，但语义混乱）。
+   * 为什么推进必须在 settleItem 而非 processNext 尾部：rejectChildDialogs 取消一个永不 settle
+   * 的 current（handler 等用户输入卡死）时，processNext 的 `await item.handler` 永不 resume，
+   * 尾部不会执行；只有 settleItem 里的 processNext 才能打破死锁，推进下一个。
+   */
+  private settleItem(item: QueueItem, resp: UiResponse): void {
+    if (item.settled) return;
+    item.settled = true;
+    item.resolve(resp);
+    // 若是正在处理的项，清空 current/processing 并推进队列（唯一推进点）。
+    // 非当前项（队列中被 reject）只 settle Promise，不影响 current/推进。
+    if (this.current === item) {
+      this.current = undefined;
+      this.processing = false;
+      void this.processNext();
+    }
+  }
+
+  /**
+   * SR-4：把指定 child 的所有 pending dialog resolve 为 {cancelled:true}。
+   *
+   * 触发场景：子进程 close（用户取消 / crash / 超时 kill）时，其 pending dialog 的 handler
+   * 可能永不 settle（等用户输入），导致 Promise 永挂 + 内存泄漏。本方法批量清理。
+   *
+   * 处理范围（TC-E4 case 2）：
+   *   - 正在处理中（current）的该 child 项：settle {cancelled:true}，解阻塞队列推进下一个
+   *     （关键：handler 可能永不 settle，必须由这里打破死锁）
+   *   - 队列中等待处理的该 child 项：settle {cancelled:true} 并移除
+   *
+   * 不影响其他 child 的 pending dialog（TC-E4 case 2 子测试 2）。
+   */
+  rejectChildDialogs(child: DialogChildRef): void {
+    // 先处理正在处理的项（可能永不 settle，必须由这里解阻塞）
+    if (this.current && this.current.childPid === child.pid) {
+      this.settleItem(this.current, { cancelled: true });
+    }
+    // 再处理队列中等待的项
+    if (this.queue.length === 0) return;
+    const remaining: QueueItem[] = [];
+    for (const item of this.queue) {
+      if (item.childPid === child.pid) {
+        // settle 该 child 的 pending Promise 为 cancelled
+        this.settleItem(item, { cancelled: true });
+      } else {
+        remaining.push(item);
+      }
+    }
+    this.queue = remaining;
+  }
+
+  /**
+   * 处理队列下一项（FIFO）。
+   *
+   * processing 标志保证串行：handler 运行期间 processing=true，新的 processNext 调用直接返回；
+   * handler settle 后由 settleItem 清 processing=false 并推进下一项（#19 单一推进点）。
+   *
+   * handler 抛错兜底（TC-E4 case 3）：catch → settle {cancelled:true} → 继续。
+   * 不能让一个失败卡死队列（processing 永远 true）。
+   */
+  private async processNext(): Promise<void> {
+    if (this.processing) return;
+    if (this.queue.length === 0) return;
+    this.processing = true;
+    const item = this.queue.shift()!;
+    this.current = item;
+    try {
+      const resp = await item.handler(item.req);
+      // handler 完成：settle（若已被 rejectChildDialogs 抢先 settle 则 noop）。
+      // settleItem 内会清 current/processing 并推进队列（#19 单一推进点）。
+      this.settleItem(item, resp);
+    } catch {
+      // handler 抛错兜底：回 cancelled，不向上抛（队列不能卡死）
+      this.settleItem(item, { cancelled: true });
+    }
+    // #19：不在尾部再调 processNext——推进统一由 settleItem 负责（避免双重推进）。
+  }
+
+  /**
+   * #10：把所有 pending dialog（queue + current）全部 settle 为 {cancelled:true}，
+   * 并清空 queue/current/processing 状态。session_shutdown 调用，保证不留永挂 Promise。
+   *
+   * 约定签名：rejectAll(): void（无参，返 void）。Group C 的 index.ts session_shutdown 依赖此契约。
+   *
+   * 幂等：依赖 settleItem 的 settled 标志——重复调用只会对已 settled 项 noop。
+   * 顺序敏感（#19 推进点在 settleItem）：必须先清空 queue 数组再 settle current，
+   * 否则 settleItem(current) 同步触发的 processNext 会从旧 queue 抢占下一项作为新 current，
+   * 避开本方法的 cancel 语义。清空后 processNext 看到空队列直接返回，新 current 不会被抢占。
+   *
+   * 单 session 假设（M-2）：见类注释。本方法清空所有 pending 不分 session——依赖 Pi 单进程
+   * 单 session 串行保证。session_shutdown handler（index.ts）调用本方法时，进程内只会有当前
+   * session 的 pending dialog。多 session 并发场景的迁移策略（rejectAllForSession）见类注释。
+   */
+  rejectAll(): void {
+    // 先捕获并清空队列——防 settleItem(current) 触发的 processNext 抢占同队列下一项
+    const items = this.queue;
+    this.queue = [];
+    // 再 settle current（processNext 此时看到空队列，不会抢占）
+    if (this.current) {
+      this.settleItem(this.current, { cancelled: true });
+    }
+    // settle 所有原队列项（Promise 必须 resolve，不能挂）
+    for (const item of items) {
+      this.settleItem(item, { cancelled: true });
+    }
+    // 状态清理（幂等：settleItem(current) 可能已清）
+    this.current = undefined;
+    this.processing = false;
+  }
+
+  /** 清空队列（dispose 用）。pending 项的 Promise 不 settle（dispose 时调用方已不关心）。
+   *  如需 settle，dispose 前应先 rejectChildDialogs 或 rejectAll。 */
+  clear(): void {
+    this.queue = [];
+    this.current = undefined;
+    this.processing = false;
+  }
+
+  /** 当前队列长度（测试/诊断用）。含等待处理项（不含 current）。 */
+  get size(): number {
+    return this.queue.length;
+  }
+}

package/src/execution/execute-options-mapper.ts

@@ -9,6 +9,12 @@ import type { AgentCallOpts } from "../orchestration/models/types.ts";
 import type { ModelInfo } from "./model-resolver.ts";
 import type { ExecuteOptions } from "./types.ts";
 
+/**
+ * slug 最大长度（字符）。subagent/workflow 创建时 slug 超过此值会被截断。
+ * 与 subagent tool schema 的 maxLength: 20 保持一致。
+ */
+export const SLUG_MAX_LENGTH = 20;
+
 /**
  * D-A2: AgentCallOpts → ExecuteOptions 映射。
  *
@@ -17,30 +23,41 @@ import type { ExecuteOptions } from "./types.ts";
  *
  * 映射规则：
  *   prompt          → task
+ *   description     → slug（≤20 字符，超长截断。缺失时回落 agent 名）
  *   agent           → agent
  *   schema          → schema
  *   schemaEnv       → schemaEnv（D-A6 bridge）
  *   cwd             → cwd
- *   model           → model ?? ctxModel（D-008 填底）
+ *   model           → model（显式 override 透传，ctxModel 不再压扁为 id 填底）
+ *   ctxModel        → ctxModel（完整 ModelInfo 对象透传，让 resolveModel 走第 3 层透明传递）
  *   skillPath       → skillPath
+ *   thinkingLevel   → thinkingLevel（M1: 否则下游 subagent-service 读到 undefined）
+ *   systemPromptFiles → appendSystemPrompt（M2: resolveAgentOpts 写盘的临时文件需被 session-runner 消费）
  *
  * 忽略字段（委托后由 executeAndAwait 内部机制替代）：
- *   systemPromptFiles —— resolveIdentity 从 agentConfig.systemPrompt 读
  *   timeoutMs         —— mergeTimeoutSignal 单独处理
- *   scene/description —— subagents 不消费
+ *   scene             —— subagents 不消费
+ *
+ * description 原先被忽略，现作为 slug 透传（ExecuteOptions.slug 必填）。
  */
 export function mapToExecuteOptions(
   opts: AgentCallOpts,
   ctxModel?: ModelInfo,
 ): ExecuteOptions {
+  // slug：优先 description，缺失回落 agent 名（保证非空）。超长截断。
+  const rawSlug = opts.description ?? opts.agent ?? "workflow-agent";
   return {
     task: opts.prompt,
+    slug: rawSlug.length > SLUG_MAX_LENGTH ? rawSlug.slice(0, SLUG_MAX_LENGTH) : rawSlug,
     agent: opts.agent,
     schema: opts.schema,
     schemaEnv: opts.schemaEnv,
     cwd: opts.cwd,
-    model: opts.model ?? ctxModel?.id,
+    model: opts.model,
+    ctxModel,
     skillPath: opts.skillPath,
+    thinkingLevel: opts.thinkingLevel,
+    appendSystemPrompt: opts.systemPromptFiles,
   };
 }
 

package/src/execution/execution-record.ts

@@ -147,6 +147,8 @@ export function createRecord(
     thinkingLevel?: string;
     mode: ExecutionMode;
     task: string;
+    /** 短标签（≤20 字符），必填。持久化兜底空串。 */
+    slug: string;
     startedAt: number;
     /** 根 Pi session ID（session 隔离过滤用）。递归链上所有层同值。 */
     rootSessionId?: string;
@@ -164,6 +166,7 @@ export function createRecord(
     thinkingLevel: identity.thinkingLevel,
     mode: identity.mode,
     task: identity.task,
+    slug: identity.slug,
     startedAt: identity.startedAt,
     rootSessionId: identity.rootSessionId,
     parentRecordId: identity.parentRecordId,
@@ -607,6 +610,7 @@ export function project(record: ExecutionRecord): SubagentToolDetails {
     agent: record.agent,
     model: record.model,
     thinkingLevel: record.thinkingLevel,
+    slug: record.slug,
     turns: record.turnCount,
     totalTokens: record.totalTokens,
     elapsedSeconds: computeElapsedSeconds(record),
@@ -657,6 +661,7 @@ export function snapshot(record: ExecutionRecord): RecordSnapshot {
     thinkingLevel: record.thinkingLevel,
     mode: record.mode,
     task: record.task,
+    slug: record.slug,
     status: record.status,
     turns: record.turnCount,
     totalTokens: record.totalTokens,