@zhushanwen/pi-subagent-workflow 0.2.0 → 0.3.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/finalize-record.ts

@@ -0,0 +1,160 @@
+// src/execution/finalize-record.ts
+//
+// 时序收尾逻辑（从 subagent-service.ts 提取，降低主文件行数 < 1000 上限）。
+//
+// D-017 时序：collectPatch → completeRecord → archive → cleanup(finalized+worktree+
+// aliveMarker+pending注销) → manifest(最后 best-effort)。
+//
+// [Critical #1 / PR #85] cleanup 全部在 manifest 写之前执行——manifest 是诊断辅助
+//（orphan recovery），写失败仅记录不阻断。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup，
+// 导致磁盘满/权限错时 worktree 泄漏 + finalized marker 不写 + alive marker 残留 +
+// pending 记账错乱。现 manifest 写移到 Step 4（最后），best-effort（console.error +
+// appendEntry，不 throw）。
+//
+// B9 兜底：completeRecord/archive 抛错→后续 cleanup/manifest 仍执行。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { removeAliveMarker } from "./alive-store.ts";
+import { bestEffort } from "./best-effort.ts";
+import { completeRecord } from "./execution-record.ts";
+import { writeFinalized } from "./finalized-marker.ts";
+import type { ManifestStore } from "./manifest-store.ts";
+import type { ModelConfigService } from "./model-config-service.ts";
+import { getSubagentSessionDir } from "./path-encoding.ts";
+import type { RecordStore } from "./record-store.ts";
+import { writeCancelledTombstone } from "./tombstone-store.ts";
+import type { AgentResult, ExecutionRecord } from "./types.ts";
+import type { WorktreeManager } from "./worktree-manager.ts";
+
+/** doFinalizeRecord 的依赖（从 SubagentService 注入，避免 this 绑定 + 解耦可测试）。 */
+export interface FinalizeDeps {
+  manifestStore: ManifestStore;
+  worktreeManager: WorktreeManager;
+  store: RecordStore;
+  modelService: ModelConfigService;
+  /** Pi ExtensionAPI（仅用 appendEntry 记录 manifest 写失败事件）。null 在 dispose 后。 */
+  pi: { appendEntry?: (type: string, data: unknown) => void } | null;
+  /** 清节流状态（防 trailing timer 在 record 归档后误发陈旧 onUpdate）。 */
+  clearThrottle(id: string): void;
+  /** pending-notifications 终态注销（绑定 pi.events.emit，由调用方闭包提供）。 */
+  emitUnregister(id: string, status: string): void;
+}
+
+/**
+ * 时序收尾（D-017）。步骤 0→4 全部 best-effort 互不阻断（除 manifest 外都幂等）。
+ *
+ * [Critical #1] Step 3 cleanup 全部在 Step 4 manifest 之前——manifest 写失败仅 console.error +
+ * appendEntry，不 throw 不跳过 cleanup。task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord
+ * 补字段），manifestToSubagent 投影真实值而非硬编码空串。
+ */
+export async function doFinalizeRecord(
+  deps: FinalizeDeps,
+  record: ExecutionRecord,
+  result: AgentResult,
+  status: "done" | "failed" | "cancelled",
+): Promise<void> {
+  // 终态清节流状态：防 trailing timer 在 record 归档后误发陈旧 onUpdate
+  deps.clearThrottle(record.id);
+
+  // ── Step 0: collectPatch（best-effort）──
+  // [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
+  //        路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
+  if (record.worktreeHandle) {
+    try {
+      const sessionsDir = getSubagentSessionDir(
+        deps.modelService.getAgentDir(),
+        record.worktreeHandle.mainCwd,
+      );
+      fs.mkdirSync(sessionsDir, { recursive: true });
+      const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
+      const patch = deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
+      if (patch.written) record.patchFile = patchFile;
+    } catch (pe: unknown) {
+      bestEffort(pe, "collectPatch (finalizeRecord Step0)");
+    }
+  }
+
+  // ── Step 1: completeRecord（B9: 抛错→后续仍执行）──
+  try {
+    completeRecord(record, result, status);
+  } catch (err) {
+    bestEffort(err, "completeRecord (finalizeRecord B9)", "error");
+  }
+
+  // ── Step 2: archive（B9: 抛错→后续仍执行）──
+  try {
+    deps.store.archive(record);
+  } catch (err) {
+    bestEffort(err, "store.archive (finalizeRecord B9)", "error");
+  }
+
+  // ── Step 3: finalized + cleanup + aliveMarker + pending注销（全部先执行，幂等）──
+  // [Critical] 清理必须在 manifest 写入之前：worktree cleanup / finalized marker / aliveMarker
+  //   都是幂等且不可跳过的副作用。绝不能因 manifest 写失败而跳过 worktree cleanup
+  //   （否则 worktree 泄漏）。各件独立 try/catch，互不阻断。
+  if (record.sessionFile) {
+    try {
+      // MF-1 fix: cancelled 状态写 tombstone 而非 finalized，防重建丢失 cancelled
+      if (status === "cancelled") {
+        writeCancelledTombstone(record.sessionFile, {
+          id: record.id,
+          status: "cancelled",
+          agent: record.agent,
+          startedAt: record.startedAt,
+          endedAt: record.endedAt ?? Date.now(),
+        });
+      } else {
+        writeFinalized(record.sessionFile);
+      }
+    } catch (err) {
+      bestEffort(err, "writeFinalized/tombstone (finalizeRecord Step3)");
+    }
+  }
+  if (record.worktreeHandle) {
+    try {
+      deps.worktreeManager.cleanup(record.worktreeHandle);
+    } catch (err) {
+      bestEffort(err, "worktree cleanup (finalizeRecord Step3)");
+    }
+  }
+  if (record.sessionFile) {
+    try {
+      removeAliveMarker(record.sessionFile);
+    } catch (err) {
+      bestEffort(err, "removeAliveMarker (finalizeRecord Step3)");
+    }
+  }
+
+  // pending-notifications：终态注销（只记 registry 状态，通知由 BgNotifier 发）
+  deps.emitUnregister(record.id, status);
+
+  // ── Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）──
+  // [Critical #1] manifest 是诊断辅助（orphan recovery），不是正确性依赖。写失败时
+  //   仅记录（console.error + appendEntry），绝不让 manifest 写失败跳过上面的 worktree
+  //   cleanup 或抛出打断 finalize 链。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup。
+  //   task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord 补字段），
+  //   manifestToSubagent 投影时用真实值而非硬编码空串。
+  try {
+    await deps.manifestStore.writeManifest({
+      id: record.id,
+      rootSessionId: record.rootSessionId ?? "",
+      agentName: record.agent,
+      status: status === "done" ? "completed" : status,
+      createdAt: record.startedAt,
+      completedAt: record.endedAt ?? Date.now(),
+      sessionFile: record.sessionFile,
+      task: record.task,
+      slug: record.slug,
+      model: record.model,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[subagent] manifest 写入失败 (record=${record.id}): ${msg}`);
+    deps.pi?.appendEntry?.("subagent:manifest-write-failed", {
+      id: record.id,
+      error: msg,
+    });
+  }
+}

package/src/execution/get-state-handshake.ts

@@ -0,0 +1,104 @@
+// src/execution/get-state-handshake.ts
+//
+// FR-4: get_state RPC 握手逻辑。
+//
+// 从 session-runner.ts 提取（保持文件 < 1000 行）。职责单一：通过 get_state RPC
+// 查询子进程 sessionFile/sessionId，带超时重试。session-runner spawn 后无条件调用。
+//
+// 设计要点：
+//   - 重试节奏：单次超时 GET_STATE_TIMEOUT_MS（2s）后，等 GET_STATE_RETRY_INTERVAL_MS（500ms）
+//     再发起下一次 get_state，最多 GET_STATE_MAX_RETRIES（3）次。修复点：旧实现超时后
+//     立即递归 tryOnce()，GET_STATE_RETRY_INTERVAL_MS 声明了却从未使用（eslint error 阻断），
+//     现在让常量名与行为一致——重试前真的等间隔。
+//   - 加速路径：sessionFile 一旦拿到立即 resolve（不等剩余重试）。
+//   - 全部超时：resolve 空对象（调用方走兜底查找）。
+
+import type { ChildProcess } from "node:child_process";
+
+import { sendGetStateCommand } from "./stdin-writer.ts";
+
+/** FR-4: get_state RPC 握手最大重试次数。 */
+const GET_STATE_MAX_RETRIES = 3;
+/** FR-4: get_state RPC 握手重试间隔（ms）——单次超时后等待此间隔再重试。 */
+const GET_STATE_RETRY_INTERVAL_MS = 500;
+/** FR-4: get_state RPC 握手单次超时（ms）。 */
+const GET_STATE_TIMEOUT_MS = 2000;
+
+/** get_state 握手结果。 */
+export interface GetStateResult {
+  sessionFile?: string;
+  sessionId?: string;
+}
+
+/**
+ * FR-4: 通过 get_state RPC 查询子进程获取 sessionFile/sessionId。
+ *
+ * 当 stdout header 未获取到 sessionFile 时，尝试通过 get_state RPC 查询。
+ * 最多重试 GET_STATE_MAX_RETRIES 次，单次超时 GET_STATE_TIMEOUT_MS 后等待
+ * GET_STATE_RETRY_INTERVAL_MS 再发起下一次重试。
+ *
+ * @param child 子进程（stdin 写入 get_state 命令）
+ * @param addResponseListener 注册 response 监听器的函数（stdout pump 中调用）
+ * @returns 握手结果（可能为空——所有重试均超时/失败）
+ */
+export function performGetStateHandshake(
+  child: ChildProcess,
+  addResponseListener: (id: string, resolver: (data: unknown) => void) => void,
+): Promise<GetStateResult> {
+  return new Promise<GetStateResult>((resolve) => {
+    const collected: GetStateResult = {};
+    let attempts = 0;
+    let resolved = false;
+
+    function tryOnce(): void {
+      if (resolved) return;
+      attempts++;
+      const reqId = sendGetStateCommand(child);
+
+      // [#15] 本次 tryOnce 私有的 timer（2s 超时 + 超时后派生的 retry）。
+      // 关键：response 回调通过闭包引用的是"本次 tryOnce 对应的 timer"，而非某个
+      // 外层共享变量——即便后续 tryOnce(#2) 重新发起请求，旧 reqId 的迟到 response 回调
+      // 闭包仍指向它自己那次 tryOnce 的 timer，不会误清新 reqId 的 timer。retry 句柄也
+      // 一并捕获，response 到达时同步取消"已在排队但尚未触发的下一次重试"。
+      let pendingRetry: ReturnType<typeof setTimeout> | undefined;
+      const timer: ReturnType<typeof setTimeout> = setTimeout(() => {
+        pendingRetry = undefined;
+        // 单次超时：等待间隔后重试，或放弃
+        if (attempts < GET_STATE_MAX_RETRIES && !resolved) {
+          // [Bug fix] 旧实现直接 tryOnce() 立即重试，GET_STATE_RETRY_INTERVAL_MS 声明却
+          // 从未使用（eslint error 阻断 commit）。现在重试前等待间隔，让常量名与行为一致。
+          pendingRetry = setTimeout(() => tryOnce(), GET_STATE_RETRY_INTERVAL_MS);
+          pendingRetry.unref();
+        } else if (!resolved) {
+          resolved = true;
+          resolve(collected);
+        }
+      }, GET_STATE_TIMEOUT_MS);
+      timer.unref();
+
+      addResponseListener(reqId, (data: unknown) => {
+        if (resolved) return;
+        // [#15] 闭包清理本次 tryOnce 的 timer（2s 超时 + 排队中的 retry），不碰其他 reqId 的 timer。
+        clearTimeout(timer);
+        if (pendingRetry) clearTimeout(pendingRetry);
+        if (data && typeof data === "object") {
+          const d = data as Record<string, unknown>;
+          if (typeof d.sessionFile === "string" && d.sessionFile.length > 0) {
+            collected.sessionFile = d.sessionFile;
+          }
+          if (typeof d.sessionId === "string" && d.sessionId.length > 0) {
+            collected.sessionId = d.sessionId;
+          }
+        }
+        // sessionFile 已获取——立即 resolve（无需更多重试）
+        if (collected.sessionFile) {
+          resolved = true;
+          resolve(collected);
+        }
+        // 否则等待超时重试
+      });
+    }
+
+    tryOnce();
+  });
+}

package/src/execution/host-mode.ts

@@ -0,0 +1,52 @@
+// src/execution/host-mode.ts
+//
+// 主进程运行模式分类工具。
+//
+// 将 Pi 的 ExtensionMode（"tui"|"rpc"|"json"|"print"）聚合为业务语义的
+// HostMode（"tui"|"gui"|"headless"），供 session-runner 的 W4 提示词守卫、
+// handler 工厂分流、stdio 选择等消费点统一调用。
+//
+// 判定依据见 AGENTS.md「运行时环境区分」章节 +
+// docs/pi-tui-development-guide.md 第四部分第 8 节。
+// ExtensionMode 来自 Pi 源码 packages/coding-agent/src/core/extensions/types.ts:299
+// （dist 中 core/extensions/types.d.ts:207）。
+//
+// 设计动机（.fix-plans/00-master-summary.md §一冲突 4）：
+//   - 把散落多处的 `ctx.mode === "tui" || ctx.mode === "rpc"` 字面量比较
+//     集中到单一修改点，未来 Pi 新增 mode 值时只改本文件。
+//   - 业务语义命名（"gui"/"headless"）比原始枚举值更清晰表达意图。
+
+import type { ExtensionMode } from "@mariozechner/pi-coding-agent";
+
+/** 主进程运行模式分类。基于 ExtensionMode 聚合为业务语义。
+ *  - "tui"：纯 Pi TUI，ctx.ui.custom 可用，用户在终端交互
+ *  - "gui"：xyz-agent GUI，通过 rpc sidecar 通道与前端 Vue 组件交互
+ *  - "headless"：无交互 UI 通道（json/print 输出模式，或 mode 未穿透） */
+export type HostMode = "tui" | "gui" | "headless";
+
+/** 从 ExtensionContext.mode 解析主进程模式分类。
+ *  - "tui" → tui（纯 Pi TUI，ctx.ui.custom 可用）
+ *  - "rpc" → gui（xyz-agent GUI，sidecar 通道可用）
+ *  - "json"/"print"/undefined → headless（无交互通道）
+ *
+ *  undefined 归入 headless 是向后兼容：mode 未穿透 SessionRunnerContext 时
+ *  按「无 UI」保守处理，避免误注入依赖 UI 的逻辑。 */
+export function resolveHostMode(mode: ExtensionMode | undefined): HostMode {
+  if (mode === "tui") return "tui";
+  if (mode === "rpc") return "gui";
+  return "headless"; // json/print/undefined
+}
+
+/** 主进程是否会响应子进程的 ask_user（UI 透传）。
+ *  tui + gui 都会（冲突 3 裁决：TUI 必须注入 handler；GUI 透传所有 UI），
+ *  headless 不会（无 UI 通道，注入 W4 提示词会误导 LLM）。 */
+export function willRespondToAskUser(mode: ExtensionMode | undefined): boolean {
+  const host = resolveHostMode(mode);
+  return host === "tui" || host === "gui";
+}
+
+/** 主进程是否有交互 UI 通道（TUI 组件 / GUI sidecar）。
+ *  非 headless 即有。用于 stdio 选择等不区分 tui/gui 的决策点。 */
+export function hasInteractiveUI(mode: ExtensionMode | undefined): boolean {
+  return resolveHostMode(mode) !== "headless";
+}