@zhushanwen/subagent-core 0.7.1 → 0.9.0

package/dist/{chunk-VURUAGMM.js → chunk-LZJOEDGQ.js}

@@ -1,5 +1,5 @@
 // src/execution/engine/engine-discovery-scan.ts
-import * as path5 from "path";
+import * as path6 from "path";
 
 // src/execution/engine/engine-manifest.ts
 import * as path from "path";
@@ -247,7 +247,7 @@ function describeValue(value) {
 
 // src/execution/engine/engine-inspect-package.ts
 import * as fs from "fs";
-import * as path2 from "path";
+import * as path3 from "path";
 import { isProtocolVersionCompatible as isProtocolVersionCompatible2 } from "@zhushanwen/subagent-engine-sdk";
 
 // src/execution/engine/common/data-dir.ts
@@ -293,7 +293,239 @@ import {
 
 // src/execution/engine/client/mirror.ts
 import { getLogger as getLogger2 } from "@zhushanwen/subagent-engine-sdk";
-var logger3 = getLogger2("subagents");
+
+// src/shared/timer-delay.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
+function assertSafeTimerDelay(ms, source) {
+  if (!Number.isFinite(ms)) {
+    throw new Error(
+      `[subagent-workflow] ${source} = ${ms} is not a finite number (NaN/\xB1Infinity). Non-finite delays collapse to 1ms in Node setTimeout and fire immediately. Recovery: fix the upstream computation that produced this value (e.g. guard division/parse results before passing them in) and retry.`
+    );
+  }
+  if (ms > MAX_TIMER_DELAY_MS) {
+    throw new Error(
+      `[subagent-workflow] ${source} = ${ms} exceeds the Node setTimeout limit (${MAX_TIMER_DELAY_MS} ms = 2^31-1); larger delays silently collapse to 1ms and fire immediately. Recovery: clamp the value to <= ${MAX_TIMER_DELAY_MS} (e.g. omit the option for "unlimited" semantics, or clamp explicitly) and retry.`
+    );
+  }
+}
+
+// src/execution/ui-interaction-model.ts
+var DIALOG_METHODS = /* @__PURE__ */ new Set([
+  "select",
+  "confirm",
+  "input",
+  "editor"
+]);
+function isDialogMethod(method) {
+  return DIALOG_METHODS.has(method);
+}
+
+// src/execution/dialog-queue.ts
+var logger3 = getLogger("subagents");
+var SECONDS_PER_MINUTE = 60;
+var MS_PER_SECOND = 1e3;
+var DEFAULT_DIALOG_TIMEOUT_MINUTES = 30;
+var DEFAULT_DIALOG_TIMEOUT_MS = DEFAULT_DIALOG_TIMEOUT_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND;
+function resolveDialogTimeoutMs(timeout) {
+  const resolved = isValidDialogTimeout(timeout) ? timeout : DEFAULT_DIALOG_TIMEOUT_MS;
+  return Math.min(resolved, MAX_TIMER_DELAY_MS);
+}
+function isValidDialogTimeout(timeout) {
+  return typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0;
+}
+function dialogTimeoutLogMessage(req, waitedMs) {
+  return `[subagents] dialog timed out after ${waitedMs}ms without response (id=${req.id}, method=${req.method}) \u2014 settled as cancelled. Recovery: the requesting agent can continue and re-issue the question (\u91CD\u65B0\u53D1\u8D77\u63D0\u95EE); to wait longer, pass an explicit timeout (ms) on the request.`;
+}
+var DialogGlobalQueue = class {
+  /** 等待处理的队列（FIFO）。正在处理的项从 queue shift 出后由 current 持有。 */
+  queue = [];
+  /** 正在处理的项（handler 已调、未 settle）。用于 rejectChildDialogs 取消占位中的 dialog。 */
+  current;
+  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, handler, opts) {
+    if (!isDialogMethod(req.method)) {
+      return handler(req);
+    }
+    return new Promise((resolve4) => {
+      this.queue.push({
+        req,
+        handler,
+        resolve: resolve4,
+        childPid: opts?.child?.pid,
+        settled: false
+      });
+      void this.processNext();
+    });
+  }
+  /**
+   * settle 一个 item（幂等）。handler 完成 / rejectChildDialogs / rejectAll / 超时 timer
+   * 都通过本方法，settled 标志保证只 settle 一次（防竞争）。
+   *
+   * #19 单一推进点：本方法 settle Promise + 清状态后，**唯一**调 processNext 推进队列。
+   * processNext 尾部不再调 processNext（旧代码双重推进，虽靠 processing 标志幂等，但语义混乱）。
+   * 为什么推进必须在 settleItem 而非 processNext 尾部：rejectChildDialogs 取消一个永不 settle
+   * 的 current（handler 等用户输入卡死）时，processNext 的 `await item.handler` 永不 resume，
+   * 尾部不会执行；只有 settleItem 里的 processNext 才能打破死锁，推进下一个。
+   *
+   * [A2-2] 超时 timer 清理也统一收口在这里：任何路径抢先 settle（reject/rejectAll/超时
+   * 自身）都必须撤下 armed timer——handler 永挂时 processNext 内联的 clearTimeout 不可达，
+   * 不在这里清则 timer 到期触发虚假「dialog timed out」warn 且句柄滞留至超时点。
+   */
+  settleItem(item, resp) {
+    if (item.settled) return;
+    item.settled = true;
+    if (item.timeoutTimer) {
+      clearTimeout(item.timeoutTimer);
+      item.timeoutTimer = void 0;
+    }
+    item.resolve(resp);
+    if (this.current === item) {
+      this.current = void 0;
+      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) {
+    const matched = [];
+    if (this.queue.length > 0) {
+      const remaining = [];
+      for (const item of this.queue) {
+        if (item.childPid === child.pid) {
+          matched.push(item);
+        } else {
+          remaining.push(item);
+        }
+      }
+      this.queue = remaining;
+    }
+    if (this.current && this.current.childPid === child.pid) {
+      this.settleItem(this.current, { cancelled: true });
+    }
+    for (const item of matched) {
+      this.settleItem(item, { cancelled: true });
+    }
+  }
+  /**
+   * 处理队列下一项（FIFO）。
+   *
+   * processing 标志保证串行：handler 运行期间 processing=true，新的 processNext 调用直接返回；
+   * handler settle 后由 settleItem 清 processing=false 并推进下一项（#19 单一推进点）。
+   *
+   * handler 抛错兜底（TC-E4 case 3）：catch → settle {cancelled:true} → 继续。
+   * 不能让一个失败卡死队列（processing 永远 true）。
+   *
+   * LC-3/T2⑦ 超时上界：`await item.handler` 原本无上界——host UI promise 挂死或用户
+   * 永不回答时 processing 恒 true（全局 dialog 死锁）。现在每项挂队列级 timer：
+   * req.timeout（请求方显式传值）优先，未传/非法挂 DEFAULT_DIALOG_TIMEOUT_MS。
+   * 到点 settle {cancelled:true}（完整错误消息落父进程日志，含恢复指引与等待时长），
+   * settleItem 的 settled 标志保证与 handler 完成 / rejectChildDialogs 三方竞态下
+   * 恰 settle 一次。timer 回调闭包捕获 item（非读 this.current）：迟到触发时
+   * settled 标志已置位，直接 noop，不误伤后继项。
+   */
+  async processNext() {
+    if (this.processing) return;
+    if (this.queue.length === 0) return;
+    this.processing = true;
+    const item = this.queue.shift();
+    this.current = item;
+    const timeoutMs = resolveDialogTimeoutMs(item.req.timeout);
+    const timer = setTimeout(() => {
+      if (item.settled) return;
+      logger3.warn(dialogTimeoutLogMessage(item.req, timeoutMs));
+      this.settleItem(item, { cancelled: true });
+    }, timeoutMs);
+    item.timeoutTimer = timer;
+    try {
+      const resp = await item.handler(item.req);
+      clearTimeout(timer);
+      this.settleItem(item, resp);
+    } catch {
+      clearTimeout(timer);
+      this.settleItem(item, { cancelled: true });
+    }
+  }
+  /**
+   * #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() {
+    const items = this.queue;
+    this.queue = [];
+    if (this.current) {
+      this.settleItem(this.current, { cancelled: true });
+    }
+    for (const item of items) {
+      this.settleItem(item, { cancelled: true });
+    }
+    this.current = void 0;
+    this.processing = false;
+  }
+  /** 清空队列状态（仅在 rejectAll 之后调用）。pending Promise 必须先由 rejectAll settle。
+   *  不 settle Promise 的纯状态重置——单独调用会导致 Promise 永挂（footgun），故设为 private。
+   *  外部调用方应使用 rejectAll()（它 settle 所有 pending + 重置状态，是原子操作）。 */
+  resetState() {
+    this.queue = [];
+    this.current = void 0;
+    this.processing = false;
+  }
+  /** 当前队列长度（测试/诊断用）。含等待处理项（不含 current）。 */
+  get size() {
+    return this.queue.length;
+  }
+};
+var activeDialogQueue;
+function registerActiveDialogQueue(queue) {
+  activeDialogQueue = queue;
+}
+function notifyChildProcessExited(pid) {
+  activeDialogQueue?.rejectChildDialogs({ pid });
+}
+
+// src/execution/engine/client/mirror.ts
+var logger4 = getLogger2("subagents");
 var SpawnedChildrenMirror = class {
   entries = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
@@ -322,6 +554,7 @@ var SpawnedChildrenMirror = class {
     };
     this.entries.set(patch.pid, entry);
     this.emit({ reason: "childStateChanged", pid: patch.pid, recordId: patch.recordId });
+    if (patch.state === "exited") notifyChildProcessExited(patch.pid);
   }
   /**
    * 失效语义 2 + 3：全部镜像项整体置死（killed=true + state=exited）→ 逐项广播 →
@@ -337,6 +570,7 @@ var SpawnedChildrenMirror = class {
       entry.state = "exited";
       entry.updatedAt = Date.now();
       this.emit({ reason: "killedAll", pid: entry.pid, recordId: entry.recordId });
+      notifyChildProcessExited(entry.pid);
     }
     this.entries.clear();
   }
@@ -367,18 +601,18 @@ var SpawnedChildrenMirror = class {
     return this.entries.size;
   }
   /** 订阅状态广播（W6 notify/谓词接线点）。返回退订函数。 */
-  onChange(listener) {
-    this.listeners.add(listener);
+  onChange(listener2) {
+    this.listeners.add(listener2);
     return () => {
-      this.listeners.delete(listener);
+      this.listeners.delete(listener2);
     };
   }
   emit(event) {
-    for (const listener of this.listeners) {
+    for (const listener2 of this.listeners) {
       try {
-        listener(event);
+        listener2(event);
       } catch (err) {
-        logger3.debug(
+        logger4.debug(
           `[spawned-children-mirror] listener threw for ${event.reason}: ${err instanceof Error ? err.message : String(err)}`
         );
       }
@@ -391,22 +625,22 @@ import { spawnSync } from "child_process";
 import { readdirSync, readFileSync, renameSync, rmSync, writeFileSync, mkdirSync } from "fs";
 import { join as join2 } from "path";
 import { getLogger as getLogger3, resolveEngineDir } from "@zhushanwen/subagent-engine-sdk";
-var logger4 = getLogger3("subagents");
+var logger5 = getLogger3("subagents");
 var CMDLINE_PROBE_TIMEOUT_MS = 3e3;
 var PIDFILE_JSON_INDENT = 2;
 function pidfilePath(engineDataDir, engineId, hostKind, hostPid) {
   return join2(resolveEngineDir(engineDataDir, engineId), `engine.${hostKind}.${hostPid}.pid`);
 }
-function writePidfileAtomic(path6, content) {
-  mkdirSync(join2(path6, ".."), { recursive: true });
-  const tmp = `${path6}.${process.pid}.${Date.now()}.tmp`;
+function writePidfileAtomic(path7, content) {
+  mkdirSync(join2(path7, ".."), { recursive: true });
+  const tmp = `${path7}.${process.pid}.${Date.now()}.tmp`;
   writeFileSync(tmp, `${JSON.stringify(content, null, PIDFILE_JSON_INDENT)}
 `, "utf-8");
-  renameSync(tmp, path6);
+  renameSync(tmp, path7);
 }
-function readPidfile(path6) {
+function readPidfile(path7) {
   try {
-    const raw = readFileSync(path6, "utf-8");
+    const raw = readFileSync(path7, "utf-8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.enginePid !== "number" || typeof parsed.hostPid !== "number" || typeof parsed.engineId !== "string" || typeof parsed.hostKind !== "string") {
       return void 0;
@@ -420,21 +654,21 @@ function readPidfile(path6) {
       writtenAt: typeof parsed.writtenAt === "string" ? parsed.writtenAt : ""
     };
   } catch (err) {
-    logger4.debug(`[pid-file] readPidfile(${path6}) failed, treating as stale: ${err instanceof Error ? err.message : String(err)}`);
+    logger5.debug(`[pid-file] readPidfile(${path7}) failed, treating as stale: ${err instanceof Error ? err.message : String(err)}`);
     return void 0;
   }
 }
-function removePidfile(path6) {
+function removePidfile(path7) {
   try {
-    rmSync(path6, { force: true });
+    rmSync(path7, { force: true });
   } catch (err) {
-    logger4.debug(`[pid-file] removePidfile(${path6}) failed (concurrent sweep = expected): ${err instanceof Error ? err.message : String(err)}`);
+    logger5.debug(`[pid-file] removePidfile(${path7}) failed (concurrent sweep = expected): ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 function registerEnginePidfile(reg) {
-  const path6 = pidfilePath(reg.engineDataDir, reg.engineId, reg.hostKind, reg.hostPid);
+  const path7 = pidfilePath(reg.engineDataDir, reg.engineId, reg.hostKind, reg.hostPid);
   try {
-    writePidfileAtomic(path6, {
+    writePidfileAtomic(path7, {
       enginePid: reg.enginePid,
       hostPid: reg.hostPid,
       engineStartTime: readProcessStartTime(reg.enginePid) ?? null,
@@ -442,9 +676,9 @@ function registerEnginePidfile(reg) {
       hostKind: reg.hostKind,
       writtenAt: (/* @__PURE__ */ new Date()).toISOString()
     });
-    return path6;
+    return path7;
   } catch (err) {
-    logger4.warn(
+    logger5.warn(
       `[pid-file] pidfile write failed for ${reg.engineId} (sweep coverage degraded): ${err instanceof Error ? err.message : String(err)}`
     );
     return void 0;
@@ -454,7 +688,7 @@ function sweepEnginePidfiles(args) {
   try {
     return sweepStalePidfiles(args);
   } catch (err) {
-    logger4.warn(
+    logger5.warn(
       `[pid-file] pidfile sweep failed for ${args.engineId} (conservative skip): ${err instanceof Error ? err.message : String(err)}`
     );
     return { killed: [], removed: [], skipped: [] };
@@ -512,10 +746,10 @@ function sweepStalePidfiles(opts) {
   }
   return result;
 }
-function sweepOnePidfile(path6, file, opts, platform, result) {
-  const content = readPidfile(path6);
+function sweepOnePidfile(path7, file, opts, platform, result) {
+  const content = readPidfile(path7);
   if (content === void 0) {
-    removePidfile(path6);
+    removePidfile(path7);
     result.removed.push({ file, reason: "unreadable-or-corrupt" });
     return;
   }
@@ -532,11 +766,11 @@ function sweepOnePidfile(path6, file, opts, platform, result) {
     result.skipped.push({ file, reason: "host-pid-alive" });
     return;
   }
-  reapDeadHostEngine(path6, file, content, opts, platform, result);
+  reapDeadHostEngine(path7, file, content, opts, platform, result);
 }
-function reapDeadHostEngine(path6, file, content, opts, platform, result) {
+function reapDeadHostEngine(path7, file, content, opts, platform, result) {
   if (platform === "win32") {
-    removePidfile(path6);
+    removePidfile(path7);
     result.removed.push({ file, reason: "stale (host dead); win32 never kills" });
     return;
   }
@@ -546,7 +780,7 @@ function reapDeadHostEngine(path6, file, content, opts, platform, result) {
     return;
   }
   if (!engineAlive) {
-    removePidfile(path6);
+    removePidfile(path7);
     result.removed.push({ file, reason: "engine-pid-dead" });
     return;
   }
@@ -556,7 +790,7 @@ function reapDeadHostEngine(path6, file, content, opts, platform, result) {
     return;
   }
   if (!opts.matchesEngineCmdline(cmdline)) {
-    removePidfile(path6);
+    removePidfile(path7);
     result.removed.push({ file, reason: "cmdline-mismatch (pid reused by unrelated process)" });
     return;
   }
@@ -566,13 +800,13 @@ function reapDeadHostEngine(path6, file, content, opts, platform, result) {
     return;
   }
   if (content.engineStartTime === null || content.engineStartTime !== startTime) {
-    removePidfile(path6);
+    removePidfile(path7);
     result.removed.push({ file, reason: "engine-start-time-mismatch (pid reused)" });
     return;
   }
   const killEngine = opts.killEngine ?? defaultKillEngineProcessGroup;
   killEngine(content.enginePid);
-  removePidfile(path6);
+  removePidfile(path7);
   result.killed.push(content.enginePid);
   result.removed.push({ file, reason: "swept after kill (stale orphan)" });
 }
@@ -581,12 +815,12 @@ function defaultKillEngineProcessGroup(enginePid) {
     process.kill(-enginePid, "SIGKILL");
     return;
   } catch (groupErr) {
-    logger4.debug(`[pid-file] process-group kill(-${enginePid}) failed, falling back to single kill: ${groupErr instanceof Error ? groupErr.message : String(groupErr)}`);
+    logger5.debug(`[pid-file] process-group kill(-${enginePid}) failed, falling back to single kill: ${groupErr instanceof Error ? groupErr.message : String(groupErr)}`);
   }
   try {
     process.kill(enginePid, "SIGKILL");
   } catch (err) {
-    logger4.debug(`[pid-file] single kill(${enginePid}) failed (already dead = expected): ${err instanceof Error ? err.message : String(err)}`);
+    logger5.debug(`[pid-file] single kill(${enginePid}) failed (already dead = expected): ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
@@ -596,7 +830,7 @@ import {
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS
 } from "@zhushanwen/subagent-engine-sdk";
-var logger5 = getLogger4("subagents");
+var logger6 = getLogger4("subagents");
 function routeReverseRequest(deps, frame) {
   if (frame.method === "host/askUser") {
     handleInteractionRequest(deps, frame, deps.uiRequestHandler, (params) => params.request);
@@ -631,7 +865,7 @@ function handleInteractionRequest(deps, frame, handler, extract) {
       const result = await handler(input);
       if (!deps.isDisposed()) deps.sendResponse(frame.id, result);
     } catch (err) {
-      logger5.warn(
+      logger6.warn(
         `[engine-client:${deps.engineId}] ${frame.method} handler failed, answering cancelled: ${err instanceof Error ? err.message : String(err)}`
       );
       if (!deps.isDisposed()) deps.sendResponse(frame.id, { cancelled: true });
@@ -642,7 +876,7 @@ function handleDataPlaneRequest(deps, frame) {
   let settled = false;
   const guardTimer = setTimeout(() => {
     if (settled) return;
-    logger5.error(
+    logger6.error(
       `[engine-client:${deps.engineId}] data-plane reverse request ${frame.method} unanswered for ${REVERSE_REQUEST_TIMEOUT_MS}ms \u2014 treating as engine fault`
     );
     void deps.failEngine(
@@ -658,7 +892,7 @@ function handleDataPlaneRequest(deps, frame) {
     (err) => {
       settled = true;
       clearTimeout(guardTimer);
-      logger5.warn(
+      logger6.warn(
         `[engine-client:${deps.engineId}] ${frame.method} dispatch failed (answering ok, host-side bug): ${err instanceof Error ? err.message : String(err)}`
       );
       deps.sendResponse(frame.id, { ok: true });
@@ -668,7 +902,6 @@ function handleDataPlaneRequest(deps, frame) {
 var DATA_PLANE_HANDLERS = {
   "host/log": (deps, params) => dispatchLog(deps, params),
   "host/streamDelta": (deps, params) => dispatchStreamDelta(deps, params),
-  "host/roundLifecycle": (deps, params) => dispatchRoundLifecycle(deps, params),
   "host/poolResolved": (deps, params) => dispatchPoolResolved(deps, params),
   "host/handleReady": (deps, params) => dispatchHandleReady(deps, params),
   "host/childSpawned": (deps, params) => dispatchChildSpawned(deps, params),
@@ -679,22 +912,12 @@ async function dispatchDataPlane(deps, method, params) {
 }
 function dispatchLog(deps, p) {
   if (deps.log !== void 0) deps.log(p);
-  else logger5[p.level](`[engine:${p.component}] ${p.message}`, p.data);
+  else logger6[p.level](`[engine:${p.component}] ${p.message}`, p.data);
 }
 async function dispatchStreamDelta(deps, p) {
-  if (p.recordId !== void 0) {
-    await deps.recordRoutes.get(p.recordId)?.onStreamDelta?.(p.delta);
-    return;
-  }
+  if (p.runId === void 0) return;
   await deps.runRoutes.get(p.runId)?.onStreamDelta?.(p.delta);
 }
-async function dispatchRoundLifecycle(deps, p) {
-  if (p.recordId !== void 0) {
-    await deps.recordRoutes.get(p.recordId)?.onRoundLifecycle?.(p);
-    return;
-  }
-  await deps.runRoutes.get(p.runId)?.onRoundLifecycle?.(p);
-}
 async function dispatchPoolResolved(deps, p) {
   await deps.runRoutes.get(p.runId)?.onPoolResolved?.(p.poolKey);
 }
@@ -710,11 +933,11 @@ function dispatchChildSpawned(deps, p) {
   if (process.platform !== "win32" && typeof p.pid === "number") {
     try {
       process.kill(-p.pid, 0);
-      logger5.warn(
+      logger6.warn(
         `[engine-client:${deps.engineId}] childSpawned pid ${p.pid} leads its own process group (not in the engine harvest group \u2014 one-generation children + in-group descendants only; engine-detached descendants are an accepted cost per design \xA73.9)`
       );
     } catch (err) {
-      logger5.debug(
+      logger6.debug(
         `[engine-client:${deps.engineId}] childSpawned pid ${p.pid} group probe settled (${err instanceof Error ? err.message : String(err)})`
       );
     }
@@ -736,7 +959,7 @@ import { basename } from "path";
 import {
   getLogger as getLogger5
 } from "@zhushanwen/subagent-engine-sdk";
-var logger6 = getLogger5("subagents");
+var logger7 = getLogger5("subagents");
 function defaultEngineCmdlineMatcher(command) {
   const base = basename(command);
   return (cmdline) => {
@@ -749,7 +972,7 @@ function warnOnManifestDiagnostics(engineId, diag, result) {
     const answered = JSON.stringify(result.capabilities ?? null);
     const declared = JSON.stringify(diag.capabilities);
     if (answered !== declared) {
-      logger6.warn(
+      logger7.warn(
         `[engine-client:${engineId}] initialize capabilities differ from manifest (diagnostic only): manifest=${declared} answered=${answered}`
       );
     }
@@ -758,7 +981,7 @@ function warnOnManifestDiagnostics(engineId, diag, result) {
     const answered = JSON.stringify(result.models ?? null);
     const declared = JSON.stringify(diag.models ?? null);
     if (answered !== declared) {
-      logger6.warn(
+      logger7.warn(
         `[engine-client:${engineId}] initialize models differ from manifest (diagnostic only): manifest=${declared} answered=${answered}`
       );
     }
@@ -768,13 +991,13 @@ function warnOnManifestDiagnostics(engineId, diag, result) {
 // src/execution/engine/client/reaper.ts
 import { spawnSync as spawnSync2 } from "child_process";
 import { getLogger as getLogger6 } from "@zhushanwen/subagent-engine-sdk";
-var logger7 = getLogger6("subagents");
+var logger8 = getLogger6("subagents");
 var KILL_GRACE_MS = 5e3;
 function killProcessTree(pid, reason, opts) {
   if (process.platform === "win32") {
     const r = spawnSync2("taskkill", ["/PID", String(pid), "/T", "/F"], { timeout: 1e4 });
     if (r.error || r.status !== 0) {
-      logger7.warn(
+      logger8.warn(
         `[engine-client:${opts.engineId}] taskkill failed for pid ${pid} (${reason}): ${r.error?.message ?? `exit ${r.status}`}`
       );
     }
@@ -785,7 +1008,7 @@ function killProcessTree(pid, reason, opts) {
       process.kill(-pid, signal);
       return true;
     } catch (err) {
-      logger7.debug(
+      logger8.debug(
         `[engine-client:${opts.engineId}] process.kill(-${pid}, ${signal}) failed: ${err instanceof Error ? err.message : String(err)}`
       );
       return false;
@@ -795,7 +1018,7 @@ function killProcessTree(pid, reason, opts) {
     try {
       process.kill(pid, "SIGTERM");
     } catch (err) {
-      logger7.debug(
+      logger8.debug(
         `[engine-client:${opts.engineId}] single SIGTERM to ${pid} failed (already dead = expected): ${err instanceof Error ? err.message : String(err)}`
       );
       return;
@@ -807,7 +1030,7 @@ function killProcessTree(pid, reason, opts) {
         try {
           process.kill(pid, "SIGKILL");
         } catch (err) {
-          logger7.debug(
+          logger8.debug(
             `[engine-client:${opts.engineId}] SIGKILL to ${pid} failed (already dead = expected): ${err instanceof Error ? err.message : String(err)}`
           );
         }
@@ -831,8 +1054,143 @@ function waitForChildExit(child, timeoutMs) {
   });
 }
 
+// src/execution/engine/host/spawned-children.ts
+var CoreSpawnedChildrenMirror = class {
+  entries = /* @__PURE__ */ new Map();
+  /** 落项 / 覆盖（同 recordId 重 spawn = 覆盖旧句柄，与引擎侧 Map 同语义）。 */
+  register(recordId, child) {
+    this.entries.set(recordId, {
+      pid: child.pid,
+      killed: child.killed,
+      updatedAt: Date.now()
+    });
+  }
+  /** 单项置死（杀链入口：killRecordChildWithEscalation 途经）。 */
+  markKilled(recordId) {
+    const entry = this.entries.get(recordId);
+    if (entry !== void 0) {
+      entry.killed = true;
+      entry.updatedAt = Date.now();
+    }
+  }
+  /** 整体置死 + 清空（失效语义 2+3：引擎 exit / 重建 / dispose / killAll）。 */
+  killAll() {
+    this.entries.clear();
+  }
+  getChildByRecord(recordId) {
+    return this.entries.get(recordId);
+  }
+  /** 句柄存活谓词（镜像面；判据与引擎侧 `!child.killed` 同构）。 */
+  hasLiveProcessHandle(recordId) {
+    const entry = this.entries.get(recordId);
+    return entry !== void 0 && !entry.killed;
+  }
+  /** 快照（诊断/测试）。 */
+  snapshot() {
+    return [...this.entries.entries()].map(([recordId, entry]) => ({ recordId, ...entry }));
+  }
+  /** 测试隔离专用（生产禁用——进程级全局状态）。 */
+  clear() {
+    this.entries.clear();
+  }
+};
+var MIRROR_SLOT_KEY = /* @__PURE__ */ Symbol.for(
+  "@zhushanwen/pi-subagent-workflow.coreSpawnedChildrenMirror"
+);
+function coreMirrorSlot() {
+  let slot = Reflect.get(globalThis, MIRROR_SLOT_KEY);
+  if (!slot) {
+    slot = new CoreSpawnedChildrenMirror();
+    Reflect.set(globalThis, MIRROR_SLOT_KEY, slot);
+  }
+  return slot;
+}
+function coreSpawnedChildrenMirror() {
+  return coreMirrorSlot();
+}
+function registerSpawnedChildForRecord(recordId, child) {
+  coreMirrorSlot().register(recordId, { pid: child.pid, killed: child.killed });
+}
+function killRecordChildWithEscalation(recordId, _source) {
+  coreMirrorSlot().markKilled(recordId);
+}
+function killAllSpawnedChildren(_signal = "SIGTERM") {
+  const before = coreMirrorSlot().snapshot().length;
+  coreMirrorSlot().killAll();
+  return before;
+}
+function hasLiveProcessHandleCore(recordId) {
+  return coreMirrorSlot().hasLiveProcessHandle(recordId);
+}
+
+// src/execution/lifecycle-manager.ts
+var logger9 = getLogger("subagents");
+var MS_PER_SECOND2 = 1e3;
+var SECONDS_PER_MINUTE2 = 60;
+var IDLE_TIMEOUT_MINUTES = 5;
+var DEFAULT_IDLE_TIMEOUT_MS = IDLE_TIMEOUT_MINUTES * SECONDS_PER_MINUTE2 * MS_PER_SECOND2;
+var idleTimers = /* @__PURE__ */ new Map();
+function disarmIdleTimer(recordId) {
+  const entry = idleTimers.get(recordId);
+  if (!entry) {
+    return;
+  }
+  clearTimeout(entry.timer);
+  idleTimers.delete(recordId);
+}
+function hasIdleTimer(recordId) {
+  return idleTimers.has(recordId);
+}
+
+// src/execution/lifecycle-predicates.ts
+function hasLiveProcessHandle(recordId) {
+  return hasLiveProcessHandleCore(recordId);
+}
+function isIdle(record) {
+  return hasIdleTimer(record.id);
+}
+function isResumable(record) {
+  return record.status === "running" && !hasLiveProcessHandle(record.id);
+}
+
+// src/execution/engine/inflight-snapshot.ts
+var listener = null;
+function setInFlightListener(next) {
+  listener = next;
+}
+function getInFlightSnapshot() {
+  return { inFlight: countInFlight() };
+}
+function notifyInFlightChanged() {
+  if (listener === null) return;
+  try {
+    listener(getInFlightSnapshot());
+  } catch {
+  }
+}
+function countInFlight() {
+  let count = 0;
+  for (const entry of coreSpawnedChildrenMirror().snapshot()) {
+    const recordId = entry.recordId;
+    if (hasLiveProcessHandle(recordId) && !hasIdleTimer(recordId)) count++;
+  }
+  return count;
+}
+
 // src/execution/engine/client/engine-client.ts
-var logger8 = getLogger7("subagents");
+var logger10 = getLogger7("subagents");
+function bridgeMirrorEventToCoreMirror(event, mirror) {
+  if (event.recordId === void 0 || event.pid === void 0) return;
+  const entry = mirror.getEntry(event.pid);
+  if (entry === void 0) return;
+  const core = coreSpawnedChildrenMirror();
+  if (entry.killed) {
+    core.markKilled(event.recordId);
+  } else {
+    core.register(event.recordId, { pid: entry.pid, killed: false });
+  }
+  notifyInFlightChanged();
+}
 var DISPOSE_GRACE_MS = 3e3;
 var SIGKILL_REAP_TIMEOUT_MS = 1e4;
 var FRAME_ECHO_MAX_CHARS = 200;
@@ -862,9 +1220,6 @@ var EngineClient = class {
   nextRequestId = 1;
   pending = /* @__PURE__ */ new Map();
   runRoutes = /* @__PURE__ */ new Map();
-  /** [W3 v1.x] chat 轮次路由（recordId 键，D1-A——续聊轮无 runId）；注册经
-   *  RemoteEngine.registerChatRoundRoute，record 终态注销。 */
-  recordRoutes = /* @__PURE__ */ new Map();
   stderrTail = "";
   unavailableReason;
   connectInFlight;
@@ -884,7 +1239,6 @@ var EngineClient = class {
       permissionHandler: opts.permissionHandler,
       log: opts.log,
       runRoutes: this.runRoutes,
-      recordRoutes: this.recordRoutes,
       mirror: this.mirror,
       setPartialHandle: (partial) => {
         this.lastPartialHandle = partial;
@@ -895,6 +1249,7 @@ var EngineClient = class {
     };
     this.mirror.onChange((event) => {
       opts.onMirrorChanged?.(event);
+      bridgeMirrorEventToCoreMirror(event, this.mirror);
     });
   }
   get currentState() {
@@ -957,19 +1312,19 @@ var EngineClient = class {
         matchesEngineCmdline: this.opts.engineCmdlineMatcher ?? defaultEngineCmdlineMatcher(this.opts.command)
       });
       if (sweep.killed.length > 0) {
-        logger8.warn(
+        logger10.warn(
           `[engine-client:${this.engineId}] startup sweep killed stale orphan engine pids: ${sweep.killed.join(",")}`
         );
       }
       for (const removed of sweep.removed) {
-        logger8.debug(`[engine-client:${this.engineId}] swept stale pidfile ${removed.file}: ${removed.reason}`);
+        logger10.debug(`[engine-client:${this.engineId}] swept stale pidfile ${removed.file}: ${removed.reason}`);
       }
     }
     let attempt = 0;
     while (attempt <= CRASH_REBUILD_MAX_ATTEMPTS) {
       if (attempt > 0) {
         const backoff = CRASH_REBUILD_BACKOFF_MS[attempt - 1];
-        logger8.warn(
+        logger10.warn(
           `[engine-client:${this.engineId}] rebuild attempt ${attempt}/${CRASH_REBUILD_MAX_ATTEMPTS} after ${backoff}ms backoff`
         );
         await delay(backoff);
@@ -1002,7 +1357,7 @@ var EngineClient = class {
   markUnavailable(reason) {
     this.state = "unavailable";
     this.unavailableReason = reason;
-    logger8.error(`[engine-client:${this.engineId}] marked unavailable: ${reason.message}`);
+    logger10.error(`[engine-client:${this.engineId}] marked unavailable: ${reason.message}`);
   }
   /** spawn 引擎 CLI + initialize 握手 + 版本协商 + 诊断留痕。 */
   async spawnAndInitialize() {
@@ -1032,13 +1387,13 @@ var EngineClient = class {
     });
     const child = this.child;
     child.on("error", (err) => {
-      logger8.warn(`[engine-client:${this.engineId}] spawn error: ${err.message}`);
+      logger10.warn(`[engine-client:${this.engineId}] spawn error: ${err.message}`);
       this.appendStderrTail(`spawn error: ${err.message}
 `);
     });
     for (const pipe of ["stdin", "stdout", "stderr"]) {
       child[pipe]?.on("error", (err) => {
-        logger8.debug(`[engine-client:${this.engineId}] ${pipe} pipe error (engine died concurrently = expected): ${err.message}`);
+        logger10.debug(`[engine-client:${this.engineId}] ${pipe} pipe error (engine died concurrently = expected): ${err.message}`);
       });
     }
     child.stdout?.setEncoding("utf-8");
@@ -1107,7 +1462,7 @@ var EngineClient = class {
     try {
       frame = JSON.parse(line);
     } catch {
-      logger8.warn(
+      logger10.warn(
         `[engine-client:${this.engineId}] dropped non-NDJSON stdout line (protocol contract: stdout is NDJSON-only): ${truncate(line, FRAME_ECHO_MAX_CHARS)}`
       );
       return;
@@ -1124,7 +1479,7 @@ var EngineClient = class {
       this.onReverseRequest(frame);
       return;
     }
-    logger8.warn(
+    logger10.warn(
       `[engine-client:${this.engineId}] dropped unrecognized frame: ${truncate(line, FRAME_ECHO_MAX_CHARS)}`
     );
   }
@@ -1205,14 +1560,6 @@ var EngineClient = class {
       if (this.runRoutes.get(runId) === route) this.runRoutes.delete(runId);
     };
   }
-  /** [W3 v1.x] 注册 chat 轮次路由（recordId 键）；分发见 reverse-router.ts
-   *  （与 runRoutes 同构，键空间互斥：runId=run 帧分配 / recordId=宿主铸造）。 */
-  registerRecordRoute(recordId, route) {
-    this.recordRoutes.set(recordId, route);
-    return () => {
-      if (this.recordRoutes.get(recordId) === route) this.recordRoutes.delete(recordId);
-    };
-  }
   /** 健康检查（ADR-0047：静默 ≠ 卡死，不据此杀任务）。 */
   async ping() {
     await this.ensureConnected();
@@ -1248,7 +1595,7 @@ var EngineClient = class {
       try {
         await this.request("dispose", {}, { timeoutMs: DISPOSE_GRACE_MS });
       } catch (err) {
-        logger8.debug(
+        logger10.debug(
           `[engine-client:${this.engineId}] dispose frame failed, falling back to kill chain: ${err instanceof Error ? err.message : String(err)}`
         );
       }
@@ -1260,18 +1607,20 @@ var EngineClient = class {
   onEngineExit(code, signal) {
     const detail = signal !== null ? `signal ${signal}` : `exit code ${code}`;
     if (this.intentionalKill) {
-      logger8.debug(`[engine-client:${this.engineId}] engine exited after intentional kill (${detail}) \u2014 expected`);
+      logger10.debug(`[engine-client:${this.engineId}] engine exited after intentional kill (${detail}) \u2014 expected`);
     } else {
-      logger8.warn(`[engine-client:${this.engineId}] engine process exited unexpectedly (${detail})`);
+      logger10.warn(`[engine-client:${this.engineId}] engine process exited unexpectedly (${detail})`);
     }
     this.teardownProcess(detail);
     this.state = "exited";
   }
   /**
-   * 进程死亡 / 失败后的统一清理：镜像整体置死（失效语义 2+3：killed=true 广播后
-   * 清空）→ pidfile 删 → 在途请求 engine_crashed（附 stderr 尾）→ run 路由清空。
+   * 进程死亡 / 失败后的统一清理（收割/组杀分支各成子函数，此处只做顺序编排）：
+   * 孤儿收割（镜像置死前）→ 镜像置死（失效语义 2+3）→ pidfile 删 → 在途请求
+   * engine_crashed（附 stderr 尾）→ run 路由清空 → 活引擎组杀兜底。
    */
   teardownProcess(detail) {
+    this.reapOrphansAfterUnexpectedDeath(detail);
     this.mirror.killAll();
     if (this.pidfileWritten !== void 0) {
       removePidfile(this.pidfileWritten);
@@ -1284,8 +1633,46 @@ var EngineClient = class {
     }
     this.pending.clear();
     this.runRoutes.clear();
-    this.recordRoutes.clear();
     this.lastPartialHandle = void 0;
+    this.killLeakedAliveChild(detail);
+    if (this.state !== "unavailable" && this.state !== "disposed") {
+      this.state = "exited";
+    }
+  }
+  /**
+   * [H1 U2 / 红线①收割链] 非主动死亡且引擎已死的路径，在镜像置死**之前**补发收割
+   * 信号：孤儿真因 = 引擎意外死时宿主未发收割信号（原先 alreadyDead 分支直接跳过
+   * killProcessTree），任务子进程留在无主进程组继续写 session 文件。插入点约束：
+   *   - 位置 = mirror.killAll() 置死清空之前——Windows 通道依赖镜像快照过滤活孤儿
+   *     （置死后全量项 killed=true 不可过滤）；
+   *   - 条件 = !intentionalKill && alreadyDead——主动 dispose 链已有两层杀（引擎
+   *     killAllActiveChildren SIGTERM+30s + 宿主 killAll 组杀 5s 升级），跳过即不叠加、
+   *     优雅窗零压缩、pi trap-flush 零截断；进程仍活的路径（握手失败重建）由
+   *     killLeakedAliveChild 组杀兜底承接。
+   */
+  reapOrphansAfterUnexpectedDeath(detail) {
+    if (!this.intentionalKill && this.child !== void 0) {
+      const dying = this.child;
+      const alreadyDead = dying.exitCode !== null || dying.signalCode !== null;
+      if (alreadyDead && dying.pid !== void 0) {
+        if (process.platform === "win32") {
+          this.reapOrphansViaMirrorSnapshot(detail);
+        } else {
+          killProcessTree(
+            dying.pid,
+            `reap orphaned children after unexpected engine death (${detail})`,
+            { engineId: this.engineId }
+          );
+        }
+      }
+    }
+  }
+  /**
+   * 握手失败路径（版本越界/握手超时/启动僵死）引擎进程仍活着：必须组杀，否则
+   * crash 重建循环每次 spawn 泄漏一个常驻孤儿（测试机实测积累 370+）。主动杀
+   * （intentionalKill=true）与进程已死（exitCode/signalCode 非空）跳过重复发信号。
+   */
+  killLeakedAliveChild(detail) {
     if (this.child !== void 0) {
       const child = this.child;
       this.child = void 0;
@@ -1295,8 +1682,30 @@ var EngineClient = class {
       }
       child.removeAllListeners();
     }
-    if (this.state !== "unavailable" && this.state !== "disposed") {
-      this.state = "exited";
+  }
+  /**
+   * [H1 U2 / 红线①Windows 通道] 镜像快照收割活孤儿：镜像快照同步抓清单（置死前，
+   * 全量项含引擎一生历史死 pid——镜像对已退出子进程只改 state 不删项、唯一清空点 =
+   * killAll）→ 过滤活孤儿（state === "running" && !killed，活孤儿 ≤ 并发数）→ 逐 pid
+   * **异步 spawn** taskkill /T /F fire-and-forget（树根 = 活着的任务子进程自身，树杀
+   * 有效；快照同步抓、杀动作异步发——与 POSIX fire-and-forget 对称；禁 spawnSync：
+   * 逐个同步 N×10s 上界会冻结 onEngineExit 同步回调、推迟 pending reject（Continuation
+   * 失败通知链源头）与宿主事件循环）。
+   */
+  reapOrphansViaMirrorSnapshot(detail) {
+    const liveOrphans = this.mirror.snapshot().filter((e) => e.state === "running" && !e.killed);
+    if (liveOrphans.length === 0) return;
+    logger10.warn(
+      `[engine-client:${this.engineId}] reaping ${liveOrphans.length} orphaned task child(ren) via mirror snapshot after unexpected engine death (${detail})`
+    );
+    for (const entry of liveOrphans) {
+      const killer = spawn("taskkill", ["/PID", String(entry.pid), "/T", "/F"], { stdio: "ignore" });
+      killer.unref();
+      killer.on("error", (err) => {
+        logger10.debug(
+          `[engine-client:${this.engineId}] taskkill spawn failed for orphan pid ${entry.pid} (${err.message})`
+        );
+      });
     }
   }
   // ── pidfile ──────────────────────────────────────────────────────────────
@@ -1311,7 +1720,7 @@ var EngineClient = class {
 `);
       return true;
     } catch (err) {
-      logger8.debug(
+      logger10.debug(
         `[engine-client:${this.engineId}] stdin write failed: ${err instanceof Error ? err.message : String(err)}`
       );
       return false;
@@ -1334,11 +1743,25 @@ function truncate(text, max) {
 }
 
 // src/execution/engine/client/remote-engine.ts
+import { homedir as homedir2 } from "os";
+import { join as join4 } from "path";
 import {
   CANCEL_SETTLE_GRACE_MS as CANCEL_SETTLE_GRACE_MS2,
   EngineSdkError as EngineSdkError2
 } from "@zhushanwen/subagent-engine-sdk";
 
+// src/execution/path-encoding.ts
+import * as path2 from "path";
+function encodeCwd(cwd) {
+  return "--" + cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-") + "--";
+}
+function getSubagentSessionDir(agentDir, mainCwd) {
+  return path2.join(agentDir, "subagents", encodeCwd(mainCwd), "sessions");
+}
+function getSubagentRecordsDir(agentDir, mainCwd) {
+  return path2.join(agentDir, "subagents", encodeCwd(mainCwd), "records");
+}
+
 // src/execution/engine/common/capability-gate.ts
 import { engineConversationUnsupportedError } from "@zhushanwen/subagent-engine-sdk";
 
@@ -1353,7 +1776,7 @@ var EngineError = class extends Error {
     this.code = code;
     this.recovery = recovery;
   }
-  /** 结构化投影（InteractResult.code/message 与 GUI 警告条共用形态）。 */
+  /** 结构化投影（code/message 与 GUI 警告条共用形态）。 */
   toStructured() {
     return { code: this.code, message: this.message, recovery: this.recovery };
   }
@@ -1410,6 +1833,13 @@ function assertGateCapabilitiesMatched(engineId, manifestCaps, answeredCaps) {
     throw gateMismatchError(engineId, "sandbox\uFF08worktree\uFF09", manifestCaps.sandbox, answeredCaps.sandbox);
   }
 }
+function engineConversationUpgradeUnsupportedError(engineId) {
+  return new EngineError(
+    "engine_capability_unsupported",
+    `subagent completed as one-shot on engine '${engineId}' (capabilities.conversation = 'unsupported') \u2014 it cannot be upgraded to a resumable conversation, so the message is rejected.`,
+    `Recovery: re-dispatch the follow-up as a new subagent (action:'start'), or branch from its session history with action:'fork-from', or pick an engine that declares the conversation capability.`
+  );
+}
 function gateMismatchError(engineId, cap, declared, answered) {
   return new EngineError(
     "engine_capability_mismatch",
@@ -1531,22 +1961,6 @@ var RemoteEngine = class {
       unregister();
     }
   }
-  async interact(handle, action) {
-    await this.opts.client.ensureConnected();
-    const result = await this.opts.client.request("interact", {
-      handle: handle.data,
-      action
-    });
-    return result;
-  }
-  /**
-   * [W3 v1.x] chat 轮次反向通道路由注册（recordId 键，EnginePort 可选面实现）：
-   * interact 续聊轮的 streamDelta / roundLifecycle 分发目标。薄委托 EngineClient
-   * 的 recordRoutes（键分发见 reverse-router.ts）。
-   */
-  registerChatRoundRoute(recordId, route) {
-    return this.opts.client.registerRecordRoute(recordId, route);
-  }
   /** 协议 read（dataDir 必填——引擎数据根，构造注入）。 */
   async read(handle) {
     await this.opts.client.ensureConnected();
@@ -1578,6 +1992,15 @@ function isTransientRunFailure(err) {
   if (!(err instanceof EngineSdkError2)) return false;
   return err.code === "engine_crashed" || err.code === "engine_request_timeout" || err.code === "engine_handshake_timeout";
 }
+var PI_AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+var PI_ROOT_CWD_ENV = "PI_SUBAGENT_ROOT_CWD";
+function deriveHostSubagentSessionDir() {
+  const agentDir = process.env[PI_AGENT_DIR_ENV];
+  const resolvedAgentDir = agentDir !== void 0 && agentDir !== "" ? agentDir : join4(homedir2(), ".pi", "agent");
+  const rootCwd = process.env[PI_ROOT_CWD_ENV];
+  const resolvedRootCwd = rootCwd !== void 0 && rootCwd !== "" ? rootCwd : process.cwd();
+  return getSubagentSessionDir(resolvedAgentDir, resolvedRootCwd);
+}
 function buildRunParams(task, ctx, runId) {
   const ctxModelRef = ctx.ctxModel ? `${ctx.ctxModel.provider}/${ctx.ctxModel.id}` : void 0;
   return {
@@ -1590,9 +2013,16 @@ function buildRunParams(task, ctx, runId) {
       schemaEnv: ctx.schemaEnv ?? task.schemaEnv,
       ctxModel: ctxModelRef,
       engineFallback: ctx.engineFallback,
-      streamMode: ctx.stream !== void 0 ? "stream" : void 0
+      streamMode: ctx.stream !== void 0 ? "stream" : void 0,
+      // [F6] 根 session id（relay 归属键 SESSION_ID 权威源）——undefined 不上 wire
+      //（additive 语义，与顶层 chat 参数同写法）。
+      ...ctx.sessionRootId !== void 0 ? { sessionRootId: ctx.sessionRootId } : {},
+      // [Option C 协议化] 权威 subagent session 目录（Gate B S6）：宿主注入值优先，
+      // 缺省同源 env 推导（deriveHostSubagentSessionDir）——恒有值恒上 wire，引擎
+      // 据此组装 --session-dir 不自推导（引擎本地推导降级 [LEGACY] fallback）。
+      sessionDir: ctx.sessionDir ?? deriveHostSubagentSessionDir()
     },
-    ...ctx.chat !== void 0 ? { chat: ctx.chat } : {}
+    ...ctx.resume !== void 0 ? { resume: ctx.resume } : {}
   };
 }
 function buildRunRouteHandlers(ctx) {
@@ -1600,9 +2030,7 @@ function buildRunRouteHandlers(ctx) {
     onEvent: (event) => ctx.onEvent?.(event),
     onStreamDelta: (delta) => ctx.stream?.onDelta(delta),
     onPoolResolved: (poolKey) => ctx.onPoolResolved?.(poolKey),
-    onHandleReady: (partial) => ctx.onHandleReady?.(partial),
-    // [W3 v1.x] 首轮（run 会话形态）轮次生命周期帧（runId 键）→ 宿主消费口。
-    onRoundLifecycle: (phase) => ctx.onRoundLifecycle?.(phase)
+    onHandleReady: (partial) => ctx.onHandleReady?.(partial)
   };
 }
 function wireAbortSignal(client, runId, ctx) {
@@ -1695,11 +2123,11 @@ function getHostUiRequestEndpoint() {
 }
 
 // src/execution/engine/engine-inspect-package.ts
-var logger9 = getLogger("subagents");
+var logger11 = getLogger("subagents");
 function readEnginePackageJson(pkgDir) {
   let raw;
   try {
-    raw = fs.readFileSync(path2.join(pkgDir, "package.json"), "utf8");
+    raw = fs.readFileSync(path3.join(pkgDir, "package.json"), "utf8");
   } catch (err) {
     return { status: "skip", reason: `package.json unreadable: ${errorMessage(err)}` };
   }
@@ -1774,12 +2202,12 @@ function parseOptionalDisplayFields(m, id) {
     if (typeof rawDisplayName === "string" && rawDisplayName.trim() !== "") {
       displayName = rawDisplayName;
     } else {
-      logger9.warn(`[engine-discovery] engine '${id}': displayName must be a non-empty string \u2014 ignoring`);
+      logger11.warn(`[engine-discovery] engine '${id}': displayName must be a non-empty string \u2014 ignoring`);
     }
   }
   const rawDescription = m["description"];
   if (rawDescription !== void 0 && typeof rawDescription !== "string") {
-    logger9.warn(`[engine-discovery] engine '${id}': description must be a string \u2014 ignoring`);
+    logger11.warn(`[engine-discovery] engine '${id}': description must be a string \u2014 ignoring`);
   }
   return displayName;
 }
@@ -1867,19 +2295,19 @@ function errorMessage(err) {
 
 // src/execution/engine/engine-discovery-roots.ts
 import * as fs2 from "fs";
-import * as path3 from "path";
-var logger10 = getLogger("subagents");
+import * as path4 from "path";
+var logger12 = getLogger("subagents");
 var ENGINE_ROOTS_ENV = "XYZ_AGENT_ENGINE_ROOTS";
 function parseEngineRootsEnv(env) {
   const raw = env[ENGINE_ROOTS_ENV];
   if (raw === void 0 || raw.trim() === "") return [];
   const out = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const part of raw.split(path3.delimiter)) {
+  for (const part of raw.split(path4.delimiter)) {
     const dir = part.trim();
     if (dir === "") continue;
-    if (!path3.isAbsolute(dir)) {
-      logger10.warn(
+    if (!path4.isAbsolute(dir)) {
+      logger12.warn(
         `[engine-discovery] ${ENGINE_ROOTS_ENV} entry '${dir}' is not an absolute path \u2014 dropping entry`
       );
       continue;
@@ -1893,11 +2321,11 @@ function parseEngineRootsEnv(env) {
 function deriveNodeModuleRoots(argvEntry = process.argv[1]) {
   if (!argvEntry || argvEntry.trim() === "") return [];
   const roots = [];
-  let dir = path3.dirname(path3.resolve(argvEntry));
+  let dir = path4.dirname(path4.resolve(argvEntry));
   while (true) {
-    const nm = path3.join(dir, "node_modules");
+    const nm = path4.join(dir, "node_modules");
     if (isDirectory(nm)) roots.push(nm);
-    const parent = path3.dirname(dir);
+    const parent = path4.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -1912,8 +2340,8 @@ function scanEngineRoot(root, visit) {
   }
   for (const item of entries) {
     if (!item.isDirectory()) continue;
-    const dir = path3.join(root, item.name);
-    if (isFile(path3.join(dir, "package.json"))) {
+    const dir = path4.join(root, item.name);
+    if (isFile(path4.join(dir, "package.json"))) {
       visit(dir);
       continue;
     }
@@ -1925,8 +2353,8 @@ function scanEngineRoot(root, visit) {
     }
     for (const child of sub) {
       if (!child.isDirectory()) continue;
-      const subDir = path3.join(dir, child.name);
-      if (isFile(path3.join(subDir, "package.json"))) visit(subDir);
+      const subDir = path4.join(dir, child.name);
+      if (isFile(path4.join(subDir, "package.json"))) visit(subDir);
     }
   }
 }
@@ -1947,10 +2375,10 @@ function isFile(p) {
 
 // src/execution/engine/config.ts
 import * as fs3 from "fs";
-import * as path4 from "path";
-var logger11 = getLogger("subagents");
+import * as path5 from "path";
+var logger13 = getLogger("subagents");
 function readExplicitEngines(agentDir) {
-  const configPath = path4.join(agentDir, "subagents", "config.json");
+  const configPath = path5.join(agentDir, "subagents", "config.json");
   let parsed;
   try {
     parsed = JSON.parse(fs3.readFileSync(configPath, "utf8"));
@@ -1961,7 +2389,7 @@ function readExplicitEngines(agentDir) {
   const engines = parsed["engines"];
   if (typeof engines !== "object" || engines === null || Array.isArray(engines)) {
     if (engines !== void 0) {
-      logger11.warn(
+      logger13.warn(
         `[engine-discovery] config.json engines section must be an object keyed by engine id, got ${jsonKindOf(engines)} \u2014 ignoring L3 explicit engines`
       );
     }
@@ -1989,7 +2417,7 @@ function sanitizeExplicitEntry(id, raw) {
 }
 function requireEntryObject(id, raw) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    logger11.warn(
+    logger13.warn(
       `[engine-discovery] config.json engines.${id} must be an object, got ${jsonKindOf(raw)} \u2014 skipping entry`
     );
     return void 0;
@@ -1998,7 +2426,7 @@ function requireEntryObject(id, raw) {
 }
 function requireCommand(id, command) {
   if (typeof command !== "string" || command.trim() === "") {
-    logger11.warn(
+    logger13.warn(
       `[engine-discovery] config.json engines.${id}.command is required (non-empty string) \u2014 skipping entry`
     );
     return void 0;
@@ -2007,7 +2435,7 @@ function requireCommand(id, command) {
 }
 function normalizeArgs(id, args) {
   if (args !== void 0 && !isStringArray(args)) {
-    logger11.warn(
+    logger13.warn(
       `[engine-discovery] config.json engines.${id}.args must be a string array \u2014 ignoring args`
     );
   }
@@ -2015,7 +2443,7 @@ function normalizeArgs(id, args) {
 }
 function normalizeConfig(id, config) {
   if (config !== void 0 && !isStringRecord(config)) {
-    logger11.warn(
+    logger13.warn(
       `[engine-discovery] config.json engines.${id}.config must be a Record<string, string> \u2014 ignoring config`
     );
   }
@@ -2023,7 +2451,7 @@ function normalizeConfig(id, config) {
 }
 function normalizeCwd(id, cwd) {
   if (cwd !== void 0 && typeof cwd !== "string") {
-    logger11.warn(
+    logger13.warn(
       `[engine-discovery] config.json engines.${id}.cwd must be a string \u2014 ignoring cwd`
     );
   }
@@ -2043,7 +2471,7 @@ function jsonKindOf(value) {
 }
 
 // src/execution/engine/registry.ts
-var logger12 = getLogger("subagents");
+var logger14 = getLogger("subagents");
 var DEFAULT_ENGINE_ID = "pi";
 function normalizeEngineId(engine) {
   return engine?.trim() || DEFAULT_ENGINE_ID;
@@ -2083,12 +2511,12 @@ function triggerEngineDispose(engine, source) {
   if (typeof engine.dispose !== "function") return;
   try {
     engine.dispose().then(void 0, (err) => {
-      logger12.warn(
+      logger14.warn(
         `[engine-registry] engine '${engine.id}' dispose rejected (${source}, best-effort continue): ${err instanceof Error ? err.message : String(err)}`
       );
     });
   } catch (err) {
-    logger12.warn(
+    logger14.warn(
       `[engine-registry] engine '${engine.id}' dispose threw synchronously (${source}, best-effort continue): ${err instanceof Error ? err.message : String(err)}`
     );
   }
@@ -2131,14 +2559,14 @@ function listEnginesByDisplayName() {
 }
 
 // src/execution/engine/engine-discovery-scan.ts
-var logger13 = getLogger("subagents");
+var logger15 = getLogger("subagents");
 function scanEngines(opts) {
   const env = opts.env ?? process.env;
   const result = { discovered: [], skipped: [], unusable: [] };
   const present = (entry) => {
     const idx = result.discovered.findIndex((d) => d.id === entry.id);
     if (idx >= 0) {
-      logger13.debug(
+      logger15.debug(
         `[engine-discovery] engine id '${entry.id}' from '${entry.source}' overrides earlier discovery from '${result.discovered[idx].source}' \u2014 same-id override`
       );
       result.discovered[idx] = entry;
@@ -2150,13 +2578,13 @@ function scanEngines(opts) {
     const inspection = inspectEnginePackage(pkgDir, source, opts.hostKind, env);
     if (inspection.status === "skip") {
       if (!inspection.reason.includes("not an engine package")) {
-        logger13.warn(`[engine-discovery] skipping ${pkgDir} (${source}): ${inspection.reason}`);
+        logger15.warn(`[engine-discovery] skipping ${pkgDir} (${source}): ${inspection.reason}`);
         result.skipped.push({ pkgDir, reason: inspection.reason });
       }
       return;
     }
     if (inspection.status === "unusable") {
-      logger13.warn(`[engine-discovery] engine unavailable: ${inspection.reason}`);
+      logger15.warn(`[engine-discovery] engine unavailable: ${inspection.reason}`);
       result.unusable.push({ pkgDir, id: inspection.id, reason: inspection.reason });
       return;
     }
@@ -2181,7 +2609,7 @@ function scanEngines(opts) {
       const command = resolveExplicitCommand(entry.command, env);
       if (command === void 0) {
         const reason = `engine '${id}' (config.json engines.${id}): command '${entry.command}' not found or not executable`;
-        logger13.warn(`[engine-discovery] ${reason} \u2014 not registering`);
+        logger15.warn(`[engine-discovery] ${reason} \u2014 not registering`);
         result.unusable.push({ pkgDir: `config.json engines.${id}`, id, reason });
         continue;
       }
@@ -2198,7 +2626,7 @@ function discoverAndRegisterEngines(opts) {
     registerEngineDescriptor(entry.id, entry.descriptor);
     loadedDiscoveryIdSet.add(entry.id);
     if (existed) {
-      logger13.debug(
+      logger15.debug(
         `[engine-discovery] engine '${entry.id}' descriptor overwritten in registry (source '${entry.source}') \u2014 same-id override`
       );
     }
@@ -2215,20 +2643,20 @@ function ensureEngineDiscovered(id, opts) {
 }
 function resolveExplicitCommand(command, env) {
   if (command.includes("/") || command.includes("\\")) {
-    const p = path5.isAbsolute(command) ? command : path5.resolve(command);
+    const p = path6.isAbsolute(command) ? command : path6.resolve(command);
     return canExecute(p) ? p : void 0;
   }
   const pathVar = env["PATH"] ?? env["Path"] ?? "";
-  for (const dir of pathVar.split(path5.delimiter)) {
+  for (const dir of pathVar.split(path6.delimiter)) {
     if (dir === "") continue;
-    const p = path5.join(dir, command);
+    const p = path6.join(dir, command);
     if (canExecute(p)) return p;
   }
   return void 0;
 }
 function buildExplicitDescriptor(id, command, entry, opts) {
   const env = opts.env ?? process.env;
-  logger13.debug(
+  logger15.debug(
     `[engine-discovery] engine '${id}' registered from config.json engines section with conservative capabilities (no manifest)`
   );
   const caps = { ...CONSERVATIVE_CAPABILITIES };
@@ -2290,8 +2718,29 @@ export {
   parseEnvPrefixes,
   parseModelCatalog,
   getEngineDataDir,
+  MAX_TIMER_DELAY_MS,
+  assertSafeTimerDelay,
+  isDialogMethod,
+  isValidDialogTimeout,
+  DialogGlobalQueue,
+  registerActiveDialogQueue,
+  registerSpawnedChildForRecord,
+  killRecordChildWithEscalation,
+  killAllSpawnedChildren,
+  DEFAULT_IDLE_TIMEOUT_MS,
+  disarmIdleTimer,
+  hasIdleTimer,
+  hasLiveProcessHandle,
+  isIdle,
+  isResumable,
+  setInFlightListener,
+  getInFlightSnapshot,
   EngineClient,
+  encodeCwd,
+  getSubagentSessionDir,
+  getSubagentRecordsDir,
   assertTaskShapeSupported,
+  engineConversationUpgradeUnsupportedError,
   RemoteEngine,
   setHostUiRequestEndpoint,
   inspectEnginePackage,