@zhushanwen/pi-subagent-workflow 8.12.0 → 8.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.12.0",
+  "version": "8.14.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -54,21 +54,21 @@
     ]
   },
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.9.0",
-    "@xyz-agent/session-delivery": "0.3.1",
-    "@zhushanwen/pi-ext-guards": "0.3.0",
-    "@zhushanwen/pi-extension-logger": "0.6.0",
-    "@zhushanwen/subagent-core": "0.9.0",
-    "@zhushanwen/pi-subagent-cli": "0.2.0",
-    "@zhushanwen/zcode-subagent-cli": "0.2.1"
+    "@xyz-agent/extension-protocol": "0.11.0",
+    "@xyz-agent/session-delivery": "0.4.1",
+    "@zhushanwen/pi-ext-guards": "0.4.0",
+    "@zhushanwen/subagent-core": "0.10.1",
+    "@zhushanwen/pi-subagent-cli": "0.4.0",
+    "@zhushanwen/zcode-subagent-cli": "0.3.1",
+    "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.4",
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.7.0",
-    "@zhushanwen/pi-structured-output": "5.1.5"
+    "@zhushanwen/pi-pending-notifications": "0.7.2",
+    "@zhushanwen/pi-structured-output": "5.1.7"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/src/host/__tests__/inflight-reporter.test.ts

@@ -2,12 +2,16 @@
 //
 // 三视角：
 //   ①使用者（runtime event-adapter 视角）——帧形状：title=SUBAGENT_INFLIGHT_MARKER、
-//     options=[JSON 帧]（kind/inFlight/sessionId/emittedAt）、控制面级 timeout 在场；
-//   ②构建者——初始上报（attachSession 触发，kind='initial'，无需任何 subagent 调用）
-//     → ack 成功一次后转 'delta'；失败折叠 + 延迟重试直至成功一次；推送在途期间
-//     多次迁移合并为单帧且携带最新绝对计数；
+//     options=[JSON 帧]（inFlight/sessionId/emittedAt）、控制面级 timeout 在场；
+//   ②构建者——初始上报（attachSession 触发，无需任何 subagent 调用）→ ack 清失败
+//     计数；失败折叠 + 延迟重试；推送在途期间多次迁移合并为单帧且携带最新绝对计数；
 //   ③观察者——onInFlightChanged 同步返回（不 await select，不进生命周期链）；
 //     detachSession 停重试，session 死后通道静默。
+//
+// [HISTORICAL] 行为于 9f914b749 变更：kind='initial'|'delta' 帧字段与 initialAcked
+// 状态机作为死面删除（消费方 event-adapter 从不读 kind，绝对计数语义下帧间等价；
+// 该 commit 漏改本文件致断言失效）。断言已对齐现行协议形状——SubagentInFlightReport
+// 无 kind 字段，kind 断言改为 undefined 锁形（防字段悄悄回流）。
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -87,7 +91,7 @@ async function advance(ms: number): Promise<void> {
 }
 
 describe("初始上报（D5：触发时点 = extension 加载完成 / session 就绪）", () => {
-  it("attachSession 即发 kind='initial' 帧（count=当下快照，无需任何 subagent 调用）", async () => {
+  it("attachSession 即发初始帧（count=当下快照，无需任何 subagent 调用）", async () => {
     const channel = makeSelectChannel();
     const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS, selectTimeoutMs: SELECT_TIMEOUT_MS });
 
@@ -98,7 +102,7 @@ describe("初始上报（D5：触发时点 = extension 加载完成 / session
     expect(channel.calls[0].title).toBe(SUBAGENT_INFLIGHT_MARKER);
     expect(channel.calls[0].timeout).toBe(SELECT_TIMEOUT_MS);
     const frame = parseFrame(channel.calls[0]);
-    expect(frame.kind).toBe("initial");
+    expect(frame.kind).toBeUndefined(); // kind 已删（9f914b749）：锁现行协议形状，防字段回流
     expect(frame.inFlight).toBe(0);
     expect(frame.sessionId).toBe("sess-u7a");
     expect(typeof frame.emittedAt).toBe("number");
@@ -107,7 +111,7 @@ describe("初始上报（D5：触发时点 = extension 加载完成 / session
     await advance(0);
   });
 
-  it("初始未送达前发生的迁移不产生第二帧（合并进 initial，送达后转 delta）", async () => {
+  it("初始未送达前发生的迁移不产生第二帧（合并为单帧，ack 后补推最新快照）", async () => {
     const channel = makeSelectChannel();
     const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
     reporter.attachSession(makeCtx(channel));
@@ -123,7 +127,7 @@ describe("初始上报（D5：触发时点 = extension 加载完成 / session
     await advance(0);
     expect(channel.calls).toHaveLength(2);
     const delta = parseFrame(channel.calls[1]);
-    expect(delta.kind).toBe("delta");
+    expect(delta.kind).toBeUndefined(); // kind 已删（9f914b749）：帧间等价，无 initial/delta 之分
     expect(delta.inFlight).toBe(2); // 补推帧携带最新绝对计数
   });
 });
@@ -155,7 +159,7 @@ describe("绝对计数语义（每帧携带当下值，非增量）", () => {
 });
 
 describe("失败折叠 + 延迟重试直至成功一次（D5 缺席语义②）", () => {
-  it("select resolve undefined（超时/旧版 runtime）→ 折叠重试；重试帧仍 kind='initial'；ack 后停", async () => {
+  it("select resolve undefined（超时/旧版 runtime）→ 折叠重试；重试帧携带完整快照；ack 后停", async () => {
     const channel = makeSelectChannel();
     const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS, selectTimeoutMs: SELECT_TIMEOUT_MS });
     reporter.attachSession(makeCtx(channel));
@@ -168,9 +172,11 @@ describe("失败折叠 + 延迟重试直至成功一次（D5 缺席语义②）"
     expect(channel.calls).toHaveLength(1); // 未到退避点不重试
     await advance(1);
     expect(channel.calls).toHaveLength(2);
-    expect(parseFrame(channel.calls[1]).kind).toBe("initial"); // 初始「成功一次」未达成
+    const retryFrame = parseFrame(channel.calls[1]);
+    expect(retryFrame.kind).toBeUndefined(); // kind 已删（9f914b749）：重试帧与普通帧等价
+    expect(retryFrame.inFlight).toBe(0); // 重试帧携带完整绝对计数快照
 
-    // 重试帧得到 ack → 重试停止；随后迁移以 delta 送达
+    // 重试帧得到 ack → 重试停止；随后迁移照常送达
     channel.settle(1, INFLIGHT_REPORT_ACK);
     await advance(RETRY_MS * 10);
     expect(channel.calls).toHaveLength(2);
@@ -178,7 +184,7 @@ describe("失败折叠 + 延迟重试直至成功一次（D5 缺席语义②）"
     reporter.onInFlightChanged();
     await advance(0);
     expect(channel.calls).toHaveLength(3);
-    expect(parseFrame(channel.calls[2]).kind).toBe("delta");
+    expect(parseFrame(channel.calls[2]).inFlight).toBe(0);
     channel.settleAll(INFLIGHT_REPORT_ACK);
   });
 

package/src/host/inflight-reporter.ts

@@ -1,6 +1,6 @@
 // src/host/inflight-reporter.ts
 //
-// 壳层在途上报出口（u7a，设计权威源：docs/design/crash-forensics-and-watchdog.md
+// 壳层在途上报出口（u7a，设计权威源：docs/architecture/crash-forensics-and-watchdog.md
 // §3.3 D5「extension 聚合上报」）。本文件属壳侧（shell），对 pi SDK（ExtensionContext
 // 的 ctx.ui.select 通道）的消费收敛在 host/ 层——core 闭包红线只约束 core（出口回调
 // 由 core 的 inflight-snapshot 注入，见组合根 index.ts 的 setInFlightListener 接线）。
@@ -15,26 +15,32 @@
 //   ② 事件产生点在 core、上报出口在壳层——本文件即出口（core 零 pi SDK）；
 //   ③ marker 路由不广播前端是 u7b（runtime 侧）的约束，本文件不涉及。
 //
+// 环境门控（2026-09-13 oe-audit + 裸 TUI 闪框事故）：上报的消费方是 xyz-agent
+// runtime 的 event-adapter marker 路由，而 runtime spawn pi 恒为 --mode rpc——
+// ctx.mode !== 'rpc' 即无拦截方（裸 pi TUI 下 marker select 会弹真框超时，2026-09-12
+// 实测无限闪框），此时不启动上报（ask-user channel-handler 的 mode 二值判定同款
+// 先例）。非 rpc 会话的 inFlight 判定归 runtime 侧镜像（spawn 预置 0），无信息损失。
+//
 // 语义（D5）：每帧携带**绝对计数**（getInFlightSnapshot，谓词与 core 内
-// hasRunningBackground 同源），非增量；初始上报（initial）触发时点 = extension 加载
-// 完成——factory 阶段拿不到 ctx/ui（pi 0.84.4 实装：dist/core/extensions/loader.js:463
-// await factory(load.api) 只收静态注册面 API（registerTool/events.on…，
-// createExtensionAPI :209 函数体无 ui 字段）；per-session ctx 由
-// dist/core/extensions/runner.js createContext() :503（get ui :508）在事件派发时点
-// 构造，emit :624 每次现场建 ctx）——session_start 是 pi 启动序列里最早带 ctx 的钩子
-// （dist/core/agent-session.js:1919 _extensionRunner.emit(_sessionStartEvent)，默认
-// 事件 :152）= 「session 就绪」，即设计所指加载完成时点；不挂任何懒触发（无 subagent
-// 的 session 也必上报）。
+// hasRunningBackground 同源），非增量；初始上报触发时点 = extension 加载完成
+// （session_start 是 pi 启动序列里最早带 ctx 的钩子 = 「session 就绪」，即设计所指
+// 加载完成时点；不挂任何懒触发（无 subagent 的 session 也必上报）。
 //
-// 失败语义（D5 缺席语义②）：select 失败（超时/通道异常/非确认回包）折叠后**延迟重试
-// 直至成功一次**。送达判据 = runtime resolve 的确认回包（INFLIGHT_REPORT_ACK）——
-// fire-and-forget 下 resolve(undefined) 与超时不可区分，必须靠显式 ack 区分「已送达」
-// 与「旧版 runtime 无路由」，否则 errs 判别（「从未收到上报」只覆盖缺席/旧版）失效。
+// 失败语义（D5 缺席语义②，2026-09-13 oe-audit 修订）：select 失败（超时/通道异常/
+// 非确认回包）折叠后延迟重试，**累计 MAX_REPORT_ATTEMPTS 次放弃**（原「重试直至
+// 成功一次」的无界语义为「旧版 runtime」版本错配场景设计——该场景已被同 bundle
+// 发布 + pi 随 runtime 退出销毁两条事实证伪；有界化的防挂死兜底对齐 plugin-bridge
+// MAX_SYNC_ATTEMPTS 形态。session_start 首帧早于 runtime adapter attach 的竞态
+// （R2 实证）在 30×2s=60s 窗口内必然自愈）。送达判据 = runtime resolve 的确认回包
+// （INFLIGHT_REPORT_ACK）——fire-and-forget 下 resolve(undefined) 与超时不可区分，
+// 靠显式 ack 区分「已送达」与「无路由」；放弃后镜像按 absent-report 走 errs 推迟
+// （30min 有界），不丢 errs-safe 兜底。
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { SUBAGENT_INFLIGHT_MARKER, isInFlightReportAck } from "@xyz-agent/extension-protocol";
+import { SUBAGENT_INFLIGHT_MARKER, callMarkerRpc, isInFlightReportAck } from "@xyz-agent/extension-protocol";
 import { getInFlightSnapshot } from "@zhushanwen/subagent-core";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 /** select 通道级超时（控制面单请求，秒级校准——超时默认原则规则 19）。取值对齐
  *  plugin-bridge 启动 sync 的 2s 自愈闸：session_start 首帧可能早于 runtime adapter
@@ -44,11 +50,16 @@ const SELECT_TIMEOUT_MS = 2_000;
 /** 失败重试退避（对齐 plugin-bridge SYNC_RETRY_MS 控制面节奏）。 */
 const RETRY_DELAY_MS = 2_000;
 
+/** 累计失败放弃上限（对齐 plugin-bridge MAX_SYNC_ATTEMPTS：60s 窗口覆盖 attach 竞态，
+ *  有界防 rpc-but-非-xyz orchestrator 场景的永久空转）。 */
+const MAX_REPORT_ATTEMPTS = 30;
+
 /** 在途上报器（组合根 index.ts 持有；per-factory 实例，session_start/shutdown 驱动）。 */
 export interface InFlightReporter {
   /**
    * session_start 注入当前 ctx 并发起初始上报（fire-and-forget——本方法同步返回，
-   * 不阻塞 session_start 装配链；初始帧 kind='initial'，count 为当下绝对计数）。
+   * 不阻塞 session_start 装配链；初始帧 count 为当下绝对计数）。非 rpc 模式
+   * （ctx.mode !== 'rpc'）下为 no-op：无 runtime 拦截方，上报通道不该启动。
    */
   attachSession(ctx: ExtensionContext): void;
   /** session_shutdown 摘除 ctx 并停止重试（session 已死，上报通道随之终结）。 */
@@ -62,6 +73,8 @@ export interface InFlightReporterOpts {
   selectTimeoutMs?: number;
   /** 测试注入：重试退避（ms）。缺省 RETRY_DELAY_MS。 */
   retryDelayMs?: number;
+  /** 测试注入：累计失败放弃上限。缺省 MAX_REPORT_ATTEMPTS。 */
+  maxAttempts?: number;
 }
 
 /**
@@ -80,19 +93,22 @@ function getSessionId(ctx: ExtensionContext): string | undefined {
 export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFlightReporter {
   const selectTimeoutMs = opts.selectTimeoutMs ?? SELECT_TIMEOUT_MS;
   const retryDelayMs = opts.retryDelayMs ?? RETRY_DELAY_MS;
+  const maxAttempts = opts.maxAttempts ?? MAX_REPORT_ATTEMPTS;
   const logger = getLogger("subagents");
 
   // 闭包状态（per-factory 实例；禁模块级 let——同进程多 factory 实例会串台）。
   let ctx: ExtensionContext | null = null;
-  /** 初始上报是否已送达（送达后所有帧 kind='delta'）。 */
-  let initialAcked = false;
   /** 一次推送尝试在途（串行化——绝对计数语义下中间值可安全合并丢弃）。 */
   let attemptInFlight = false;
   /** 有待推帧（onInFlightChanged 在推送在途期间置位，成功后立即补推最新值）。 */
   let dirty = false;
   /** 重试定时器句柄（单飞；成功/dispose 即清）。 */
   let retryTimer: ReturnType<typeof setTimeout> | null = null;
-  /** 首次失败已 warn 留痕（重试循环不刷屏——旧版 runtime 场景会长期重试）。 */
+  /** 累计失败次数（成功清零；达 maxAttempts 放弃——本 session 不再重试）。 */
+  let failureCount = 0;
+  /** 已放弃（累计到顶；session 内终态，成功路径永不触及）。 */
+  let givenUp = false;
+  /** 首次失败已 warn 留痕（重试循环不刷屏）。 */
   let firstFailureLogged = false;
 
   function clearRetryTimer(): void {
@@ -102,9 +118,9 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
     }
   }
 
-  /** 推送在途或无 ctx 时仅置脏；否则发起一次尝试（void，不阻塞调用方）。 */
+  /** 推送在途、已放弃或无 ctx 时仅置脏；否则发起一次尝试（void，不阻塞调用方）。 */
   function kick(): void {
-    if (attemptInFlight || ctx === null) {
+    if (attemptInFlight || givenUp || ctx === null) {
       dirty = true;
       return;
     }
@@ -120,34 +136,53 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
       return;
     }
     // 帧内容在发送时刻现取：绝对计数 = 此刻快照（「当前非 idle 句柄数」）、
-    // 产生时点 = 此刻、kind 按初始上报是否已送达裁决（初始未送达前，脏帧也以
-    // initial 语义送达——对 errs 判别等价：runtime 收到任何帧即「在场」）。
+    // 产生时点 = 此刻（runtime 收到任何帧即「在场」，errs 判别按帧到达置位）。
     const snapshot = getInFlightSnapshot();
     const payload = JSON.stringify({
-      kind: initialAcked ? "delta" : "initial",
       inFlight: snapshot.inFlight,
       sessionId: getSessionId(active),
       emittedAt: Date.now(),
     });
-    let value: unknown;
-    try {
-      value = await active.ui.select(SUBAGENT_INFLIGHT_MARKER, [payload], { timeout: selectTimeoutMs });
-    } catch (err) {
-      // 通道异常折叠（plugin-bridge callBridge 同款：不静默吞，但只首败 warn）。
-      value = undefined;
-      logFailure("select channel threw", err);
-    }
+    // 发送+折叠半边走 protocol 的 callMarkerRpc 原语（D8，fire-and-forget：void 发起
+    // 不变）：ok:false 四态（cancelled/timeout/channel-error/non-json）统一折叠进下方
+    // 延迟重试路径；送达判据 = ack 全等匹配（不是 JSON 消费），留在本侧。原语的失败
+    // 留痕经注入的 log 承载本侧「首败 warn / 后续 debug」防刷屏策略。
+    // guiCtx = ExtensionContext 的 GuiContext 最小子集（ask-user runRpcInteraction 同款
+    // 先例：ui.custom 泛型签名静态不兼容，callMarkerRpc 只读 ui.select）。
+    const guiCtx = {
+      mode: active.mode,
+      hasUI: active.hasUI,
+      ui: { select: active.ui.select.bind(active.ui) },
+    };
+    const result = await callMarkerRpc(guiCtx, SUBAGENT_INFLIGHT_MARKER, payload, {
+      timeout: selectTimeoutMs,
+      log: primitiveLog,
+    });
     attemptInFlight = false;
-    if (typeof value === "string" && isInFlightReportAck(value)) {
-      // 送达确认：清重试；初始上报「成功一次」达成后，后续帧一律 delta。
-      initialAcked = true;
+    if (result.ok && isInFlightReportAck(result.value)) {
+      // 送达确认：清重试与失败计数，补推积压脏帧。
+      failureCount = 0;
       clearRetryTimer();
       if (dirty && ctx !== null) kick();
       return;
     }
-    // 失败折叠（resolve undefined = 超时/取消/旧版无路由）→ 延迟重试直至成功一次
-    //（D5 缺席语义②：使「从未收到」只覆盖缺席/旧版形态，不覆盖一次性丢包）。
-    logFailure("no ack (timeout, cancelled, or runtime without marker routing)", value);
+    // 失败折叠（resolve undefined = 超时/取消/无路由 / 回包非 ack / 通道异常）→ 延迟
+    // 重试，累计到顶放弃（放弃后镜像按 absent-report 走 errs 推迟，30min 有界，
+    // errs-safe 兜底不丢）。
+    logFailure(
+      result.ok ? "no ack (non-ack response)" : `no ack (${result.reason})`,
+      result.ok ? result.value : undefined,
+    );
+    failureCount += 1;
+    if (failureCount >= maxAttempts) {
+      givenUp = true;
+      clearRetryTimer();
+      logger.warn(
+        `[subagent-inflight] in-flight report gave up after ${failureCount} attempts; ` +
+          `mirror will treat this session as absent-report (errs-deferred, bounded)`,
+      );
+      return;
+    }
     if (ctx !== null && retryTimer === null) {
       retryTimer = setTimeout(() => {
         retryTimer = null;
@@ -158,11 +193,17 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
     }
   }
 
+  /** 原语留痕注入（D8）：msg/detail 由 callMarkerRpc 产出；防刷屏策略（首败 warn /
+   * 后续 debug）留本侧 logFailure。detail 是原语侧小对象，序列化保信息。 */
+  function primitiveLog(msg: string, detail?: object): void {
+    logFailure(msg, detail === undefined ? undefined : JSON.stringify(detail));
+  }
+
   function logFailure(reason: string, detail: unknown): void {
     if (!firstFailureLogged) {
       firstFailureLogged = true;
-      logger.warn(`[subagent-inflight] in-flight report failed (${reason}); retrying every ${retryDelayMs}ms until acked`, {
-        detail: detail instanceof Error ? detail.message : String(detail),
+      logger.warn(`[subagent-inflight] in-flight report failed (${reason}); retrying every ${retryDelayMs}ms (bounded at ${maxAttempts} attempts)`, {
+        detail: toErrorMessage(detail),
       });
       return;
     }
@@ -171,6 +212,15 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
 
   return {
     attachSession(target: ExtensionContext): void {
+      // 环境门控：非 rpc 模式（裸 pi TUI / json / print）无 runtime 拦截方，marker
+      // select 会弹真框（2026-09-12 裸 TUI 无限闪框事故根因）——不设 ctx，本 session
+      // 全程 no-op。ask-user 的 ctx.mode === "rpc" 二值判定同款先例。
+      if (target.mode !== "rpc") return;
+      // attach = 新 reporting epoch（新 session / respawn 后重载）：放弃态与失败计数
+      // 随旧 session 终结，重置重试资格（同一 session 内放弃不恢复——absent-report 兜底）。
+      givenUp = false;
+      failureCount = 0;
+      firstFailureLogged = false;
       ctx = target;
       clearRetryTimer();
       // 初始上报（count=当下绝对计数；session 就绪时点恒为 0——子进程只会在后续

package/src/host/pi-host.ts

@@ -1,7 +1,7 @@
 // src/host/pi-host.ts
 //
 // pi 壳宿主实现（subagent-core 包抽离 u0-wire）。设计权威源：
-// docs/design/subagent-core-package-extraction.md §3.3 D2（含计划期契约细化 3 条）。
+// docs/architecture/subagent-core-package-extraction.md §3.3 D2（含计划期契约细化 3 条）。
 //
 // 本文件属壳侧（shell），不进 core 切面——对 pi SDK 与 pi 宿主协作件
 // （@earendil-works/pi-coding-agent / @zhushanwen/pi-extension-logger /

package/src/index.ts

@@ -99,8 +99,11 @@ const logger = getLogger("subagents");
 //
 // session_shutdown 是 pi 的 async hook，进程被 SIGTERM/SIGINT 强杀或崩溃时来不及
 // 触发；sync 子进程（controller 为 undefined，abortRunningControllers 跳过它们）会
-// 泄漏为孤儿。process.on 兜底显式 killAllSpawnedChildren 收割全部活子进程。
-// guard 防多信号叠加（如 SIGINT 后又 beforeExit）重复 kill。
+// 泄漏为孤儿。process.on 兜底调 killAllSpawnedChildren——[如实口径] core 侧该入口
+// 为镜像置死 no-op（仅清空 core spawnedChildren 镜像记账，不发任何进程信号），真实
+// 回收链 = 子进程 stdin-EOF 自灭（宿主退出 / EngineClient 销毁）+ dispose 链；本调用
+// 保留兜底占位（镜像一致性），不构成真实收割。guard 防多信号叠加（如 SIGINT 后又
+// beforeExit）重复触发。
 let processShutdownHookFired = false;
 
 function reapSpawnedChildrenOnShutdown(): void {
@@ -670,7 +673,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
 // session_shutdown），Symbol key 单定义点随迁，避免双份定义漂移。
 
 // 跨扩展 channel handler 注册入口已收口到 core 深路径
-// `@zhushanwen/subagent-core/execution/channel-registry-access.ts`
+// `@zhushanwen/subagent-core/execution/assembly/channel-registry-access.ts`
 // （getOrCreateChannelRegistry / UiChannelRegistry / ChannelHandler）。
 // 历史上的包根 re-export 已删：ask-user 等跨扩展消费者经 globalThis 握手
 // （DIALOG_QUEUE_KEY 同款进程级单例），不再经包根 import 消费本模块。

package/src/injectors/__tests__/engine-awareness.test.ts

@@ -1,6 +1,6 @@
 // engine-awareness 单测（[engine-awareness U3]）
 //
-// 覆盖（设计 docs/design/subagent-engine-awareness-injection.md 验收挂钩 D1/D1b/D2/D3/D5）：
+// 覆盖（设计 docs/design/subagent-engine-awareness-injection.md（已删除，git 可追溯）验收挂钩 D1/D1b/D2/D3/D5）：
 // 1. normalizeEngineId：缺省/空白归一到 'pi'（单一权威源 registry.ts，直连导入）
 // 2. buildEngineChangeNotice：§3.1 文案骨架、pi/非 pi 指路段分界、不含任何模型清单（D4）
 // 3. runEngineAwarenessTurn 编排：

package/src/injectors/__tests__/engine-section-stability.test.ts

@@ -1,6 +1,6 @@
 // engine-section-stability.test.ts —— [engine-awareness U4 stability-guard]
 //
-// 字节稳定守护（设计 docs/design/subagent-engine-awareness-injection.md §3.3 D7 /
+// 字节稳定守护（设计 docs/design/subagent-engine-awareness-injection.md（已删除，git 可追溯）§3.3 D7 /
 // §4 A8 的代码级前置）：engine 段延续注入纪律——确定性渲染、链尾位置，引擎切换只断
 // system prompt 尾部 cache 前缀（与 provider models 段变更同判，不新增 cache 破坏面，
 // cache-probe 前缀指纹归因兼容）。

package/src/injectors/engine-awareness.ts

@@ -1,7 +1,7 @@
 // src/injectors/engine-awareness.ts
 //
 // [engine-awareness U3] 引擎感知检测编排。设计权威源：
-// docs/design/subagent-engine-awareness-injection.md §2.3 物理数据流 /
+// docs/design/subagent-engine-awareness-injection.md（已删除，git 可追溯）§2.3 物理数据流 /
 // §3.3 D1（per-turn poll）、D1b（lastEngine 初始化与静默基线化）、D2（reload 先行）、
 // D3（通知通道）、D5（三态读取语义）。
 //

package/src/injectors/model-list-injector.ts

@@ -42,6 +42,7 @@ import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 // C5①/C5⑦：渲染统一走 core barrel（formatModelList + ModelEntry 类型为 barrel 导出面）
 import { formatModelList, type ModelEntry } from "@zhushanwen/subagent-core";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 const logger = getLogger("injector");
 
@@ -87,7 +88,7 @@ export function setupModelListInjector(pi: ExtensionAPI): void {
 				return { systemPrompt: event.systemPrompt + injection };
 			} catch (err) {
 				logger.error("[model-list-injector] before_agent_start failed", {
-					reason: err instanceof Error ? err.message : String(err),
+					reason: toErrorMessage(err),
 				});
 			}
 		},

package/src/injectors/subagent-list-injector.ts

@@ -14,7 +14,7 @@
  *   core barrel（渲染骨架与条目模板逐字节同 pi 旧本地实现——CA2 快照验收前提）；
  *   guide 文案是 pi 宿主注入（core 不内嵌平台文案）。
  * - U11（sink 设计）：装配循环（发现→解析→去重→排序 + warn/error 口径）整体改
- *   消费 core discoverAgents（execution/agents-assembly，U2/A6）——经工厂 assemble
+ *   消费 core discoverAgents（execution/assembly/agents-assembly，U2/A6）——经工厂 assemble
  *   覆写槽委托，壳侧收缩为「宿主注入根现取 + 委托」，语义等值口径见
  *   agents-assembly.ts 头注（⛔1 探针对照注入 XML diff 为空验收）。
  *

package/src/interface/__tests__/subagent-tool-prompt.test.ts

@@ -167,7 +167,7 @@ describe("subagent tool runtime handler — 错误文案含纠正正例", () =>
       "..",
     );
     const actionsSrc = readFileSync(
-      join(coreRoot, "src/execution/subagent-actions-core.ts"),
+      join(coreRoot, "src/execution/assembly/subagent-actions-core.ts"),
       "utf-8",
     );
     // 四处 throw（input 缺失 / task 空白 / slug 空白 / slug 超长）都应含 Correct 正例。

package/src/interface/format.ts

@@ -13,6 +13,8 @@ import os from "node:os";
 
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
+import { firstContentText } from "@xyz-agent/extension-protocol";
+
 import type { AgentEventLogEntry, DisplayItem, ExecutionStatus } from "@zhushanwen/subagent-core";
 import { DEFAULT_AGENT_NAME } from "@zhushanwen/subagent-core";
 import type {
@@ -138,16 +140,24 @@ export function shortId(id: string): string {
  *   running → { icon: undefined, color: "accent" }
  *     icon 留空是因为 running 的 spinner 需 seed 驱动,
  *     调用方用 detailsSeed(details) 算 seed 后调 spinnerGlyph(seed).
- *   done      → { "✓", "success" }
- *   failed    → { "✗", "error" }
- *   cancelled → { "■", "muted" }
+ *   idle     → { "✓", "success" }
+ *
+ * [U2 两态迁移] 永久会话模型（subagent-permanent-session-model §3.2.2）状态机收敛为
+ * running | idle 两态，终态概念删除——旧 closed 分支（v4 B-1 统一终态 ✓ success 色）
+ * 迁移为 idle（已收口/等续聊，语义上「上一轮有产出」保留 ✓ success 色；stopReason
+ * 派生词的渲染细化归 U8 投影面）。签名兼容 BgNotifyRecord 的通知词汇 "closed"
+ * （通知文案载体的本地类型不受 ExecutionStatus 两态约束，桥接映射同 idle）。
  */
-export function statusGlyph(status: ExecutionStatus): { icon: string | undefined; color: string } {
+export function statusGlyph(
+  status: ExecutionStatus | "closed",
+): { icon: string | undefined; color: string } {
   switch (status) {
     case "running":
       return { icon: undefined, color: "accent" };
+    case "idle":
     case "closed":
-      // v4 B-1: closed 统一终态（含 cancelled）。默认 ✓ success 色。
+      // 已收口/等续聊（closed = BgNotifyRecord 通知词汇桥接）。默认 ✓ success 色
+      // （承接旧 closed 分支的视觉基线）。
       return { icon: "✓", color: "success" };
   }
 }
@@ -554,12 +564,13 @@ export function formatTokenStat(
 /**
  * renderResult 的文本兜底：从 result.content[0] 提取纯文本。
  * 多处 tool 的 renderResult 曾各自内联此逻辑，提取后统一调用。
+ * 内核收敛至 extension-protocol firstContentText（ext-simplify-17 D9）；
+ * 本包装保留 content 可选的宽入参形态（tool renderResult 回调契约 content 可缺省）。
  */
 export function renderTextFallback(
   result: { content?: Array<{ type: string; text?: string }> },
 ): string {
-  const first = result.content?.[0];
-  return first?.type === "text" ? (first.text ?? "") : "";
+  return firstContentText({ content: result.content ?? [] });
 }
 
 /** Format a single activity line: ToolName(argsPreview). */

package/src/interface/gui-mappers.ts

@@ -48,12 +48,16 @@ function isFailedStatus(s: string): boolean {
  * 把 workflow/subagent 状态字符串映射到 list-tree 的三态 status。
  *
  * 输入可能是纯 RunStatus（running/done）、RunStatus+reason 组合
- * （如 "done (failed)"），或 subagent status（running/done/failed/cancelled/crashed）。
+ * （如 "done (failed)"），或 subagent status（running/idle/legacy done/failed/
+ * cancelled/crashed）。
  *
  * 映射规则：
  *   - running → running
  *   - failed / aborted / error / crashed / cancelled / budget_limited / time_limited → failed
- *   - 其他（done / completed / success / pending）→ done
+ *   - 其他（done / completed / success / pending / idle）→ done
+ *
+ * [U8 两态] subagent 的 idle（无任务在飞可续聊）在协议三态里落 done（空闲 = 无
+ * 进行中工作，check 图标）；「为什么停」不进树形状态（协议无该维度）。
  */
 export function mapRunStatus(status: string): TreeStatus {
   const s = status.toLowerCase();

package/src/interface/list-component.ts

@@ -602,12 +602,18 @@ export class SubagentsListComponent implements Component {
     }
   }
 
-  /** 元数据段：id/mode/status/turns/tokens 行 + model/thinking 行 + parent/children 层级行。 */
+  /** 元数据段：id/mode/status/stopReason/turns/tokens 行 + model/thinking 行 + parent/children 层级行。 */
   private pushMetaSection(content: string[], record: SubagentRecord, width: number): void {
     const t = this.theme;
-    // 元数据：第 1 行 id + 状态 + turns + tokens
+    // 元数据：第 1 行 id + 状态 + turns + tokens。stopReason（上一轮为什么停）只在
+    // 详情面板出现（§3.2.1 展示层词汇收敛：列表主展示用状态词，停因是排障信息）；
+    // 有值即追加 `stopped: <reason>` 段（与 SubagentTab 同判据——A-lite 轮终
+    // running-resumable 也携带合法停因），缺省省略（在飞首轮 / 存量无字段）。
+    const stopPart = record.stopReason
+      ? ` · stopped: ${record.stopReason}`
+      : "";
     content.push(truncLine(
-      t.fg("dim", `${record.id} · ${record.mode} · ${record.status} · ${record.turns} turns · ${formatTokens(record.totalTokens)}`),
+      t.fg("dim", `${record.id} · ${record.mode} · ${record.status}${stopPart} · ${record.turns} turns · ${formatTokens(record.totalTokens)}`),
       width,
     ));
     // 元数据：第 2 行 model + thinking（括号分组）

package/src/interface/list-view.ts

@@ -17,7 +17,7 @@
 //     └────────────────────────────┘  ← overlay 底空白行
 //   （外层框线仅为示意，实际是空白行/空格列）
 //
-// 契约（ctx.ui.custom overlay，对照 pi-tui-development-guide.md §3.2）：
+// 契约（ctx.ui.custom overlay，对照 tui-rendering-pitfalls.md §3.2）：
 //   custom<void>((tui, theme, kb, done) => Component, {overlay:true, overlayOptions})
 //   Component: render(width):string[] + invalidate() + handleInput?(data)
 //

package/src/interface/subagent-actions.ts

@@ -3,7 +3,7 @@
 // subagent tool 六 action 的 pi adapter 壳（sink 设计 D6② 消费收缩）。
 //
 // 领域内核（入参校验 / message 拒绝文案分流 / fork-from 拒绝链 / 终态映射 /
-// list 投影）已下沉 core @zhushanwen/subagent-core/execution/subagent-actions-core——
+// list 投影）已下沉 core @zhushanwen/subagent-core/execution/assembly/subagent-actions-core——
 // ⛔4 行为快照等值锚定见 core __tests__/subagent-actions-core.test.ts（期望值硬编码自
 // 本文件迁移前实测输出，含错误文案逐字锚）。本壳按设计仅保留三类职责：
 //   1. core 调用面 re-export：六 handler + 领域类型（签名不变，消费方零改动）

package/src/interface/subagent-tool-schema.ts

@@ -28,7 +28,7 @@ export { SLUG_MAX_LENGTH };
 
 // Params schema（跨包契约测试的真实 typebox 校验入口）。
 //
-// action:"start" 的 17 字段（task/slug/agent/model/...）拍平在顶层，不再用 startParam
+// action:"start" 的 16 字段（task/slug/agent/model/...）拍平在顶层，不再用 startParam
 // 嵌套容器包。原因：弱模型（GLM/DeepSeek）信任 schema 结构信号 > 文本信号，经常省略
 // startParam 嵌套层把 task/slug 直接平铺到顶层导致调用失败。拍平后 schema 结构与模型
 // 的自然倾向一致，消除这层误用。task/slug 必填性由 startHandler runtime 校验（flat
@@ -40,7 +40,7 @@ export { SLUG_MAX_LENGTH };
 // 反映必填性。勿在此基础上继续堆 action 条件逻辑——要加就拆 tool。
 export const SubagentParams = Type.Object({
   action: StringEnum(["start", "list", "cancel", "message", "close", "fork-from"], {
-    description: "Operation: 'start' runs a subagent, 'list' shows subagents, 'cancel' stops a background subagent, 'message' sends a follow-up to a running subagent (one-shot subagents are auto-upgraded to conversation mode on first message), 'close' ends a running subagent (conversation-mode or one-shot), 'fork-from' spawns a NEW subagent inheriting an older one's history (recovery for restart-disconnected subagents; the old record is untouched).",
+    description: "Operation: 'start' runs a subagent, 'list' shows subagents, 'cancel' stops a background subagent, 'message' sends a follow-up to any of your subagents (running or idle — an idle one transparently revives and continues on its original session file), 'close' archives a subagent (immediately when idle; after the current round, or immediately with force:true, when running), 'fork-from' spawns a NEW subagent inheriting an older one's history (recovery for restart-disconnected subagents; the old record is untouched).",
   }),
   // ── action:"start" fields (flattened to top level). task/slug REQUIRED for start. ──
   // Missing/empty task or slug throws at runtime (startHandler).
@@ -88,40 +88,34 @@ export const SubagentParams = Type.Object({
     description: 'Override the working directory for the subagent execution. Must be an absolute path (no "~" shorthand, no relative paths); ".." segments are rejected. Defaults to the parent session\'s cwd.',
     pattern: "^/",
   })),
-  conversation: Type.Optional(Type.Boolean({
-    description:
-      "Enable continuous chat with this subagent. When true, the subagent stays available after each reply — you can send follow-up messages (action:'message') and it keeps the full conversation context across rounds, with no need to re-spawn or re-explain. " +
-      "\nUse conversation:true for: multi-round collaboration (iterative review-fix loops, back-and-forth refinement), any task where you expect to send follow-up messages after the initial result. " +
-      "\nOmit (or false) for: one-shot tasks — single exploration, lookup, file read, code generation that needs no follow-up. The subagent runs once, notifies on completion, and is cleaned up automatically (default). " +
-      "\nFor long-interval collaboration (each round spaced >5min apart), set conversation:true AND increase idleTimeoutMs to avoid premature timeout. " +
-      "Cost: a conversation-mode subagent holds resources (memory, and a worktree if enabled) until you explicitly end it with action:'close'. Always close when done.",
-  })),
+  // [modeless 波5] conversation 参数已删除：chatMode 字段消亡后「模式」不存在——
+  // 一切 record 永续可续聊（idle 后 message 即续、fork-from 可继承），无模式开关可表达。
   idleTimeoutMs: Type.Optional(Type.Number({
     description:
-      "Idle timeout in milliseconds for conversation-mode subagents. Controls how long an idle subagent (between rounds) stays alive before automatic cleanup. " +
-      "Default: 300000 (5min). Override for long-interval collaboration where each round is spaced >5min apart. " +
-      "Pass 0 or a negative value to DISABLE idle cleanup entirely (subagent stays alive until explicitly closed). " +
-      "Only meaningful with conversation:true; ignored for one-shot subagents.",
+      "Idle-recycle cadence for ALL subagents (modeless: every subagent stays continuable — this is NOT a mode switch). Controls how long an idle subagent (between rounds, no activity) stays before being automatically archived. " +
+      "Default: 300000 (5min). Raise it for long-interval collaboration where your next message may arrive more than 5min after a round ends. " +
+      "Pass 0 or a negative value to DISABLE idle recycling entirely (subagent stays available until you close it). " +
+      "Priority: this param > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > default.",
   })),
   engine: Type.Optional(StringEnum(["pi", "zcode"], {
     description:
       "Execution engine for this subagent. Omit to inherit the global config. " +
       "Three-layer priority: this parameter > agent .md frontmatter engine > config.json defaultEngine. " +
-      "Non-pi engines do not support conversation/fork/worktree (rejected before the subagent is created).",
+      "Non-pi engines do not support fork/worktree (rejected before the subagent is created).",
   })),
   collect: Type.Optional(StringEnum(["async", "sync"], {
     description:
-      "Completion-notification collection mode for one-shot subagents (subagent-sync-collect). " +
+      "Completion-notification routing (NOT a record mode — batch membership is routing bookkeeping only). " +
       "Omit to use the config default (currently async). " +
-      "Use 'sync' when you dispatch >=2 independent one-shot subagents whose results you will combine: " +
-      "their completions are held until ALL pending sync subagents finish, then delivered as ONE batch " +
-      "notification (single wake-up, results inline). You may keep dispatching more sync subagents in " +
-      "later turns — they join the same pending batch. " +
-      "Independent means no member's prompt or work depends on another member's output — dependent " +
-      "tasks must be chained across messages (one start after the prior completes), never batched. " +
-      "Use 'async' (or omit) for immediate per-subagent completion notifications. " +
-      "Incompatible with conversation:true — that combination is rejected immediately before start; " +
-      "remove either conversation or collect.",
+      "'async' = each subagent's completion notifies immediately. " +
+      "'sync' = batch wake-up: when you dispatch >=2 independent subagents whose results you will " +
+      "combine, their completions are held until ALL pending sync members finish, then delivered as " +
+      "ONE batch notification (single wake-up, results inline); when the batch closes, its members " +
+      "are automatically archived. Batch members cannot be messaged — use action:'fork-from' to " +
+      "continue from one instead. You may keep dispatching more sync subagents in later turns — " +
+      "they join the same pending batch. Independent means no member's prompt or work depends on " +
+      "another member's output — dependent tasks must be chained across messages (one start after " +
+      "the prior completes), never batched.",
   })),
   // action:"list" → listParam OPTIONAL (all fields optional, defaults apply). Ignored by other actions.
   listParam: Type.Optional(Type.Object({
@@ -145,24 +139,30 @@ export const SubagentParams = Type.Object({
       description: "REQUIRED for action:'cancel'. The subagentId to cancel. Throws if missing. Only background subagents can be cancelled.",
     }),
   })),
-  // action:"message" → messageParam.subagentId + text REQUIRED. Any RUNNING subagent works —
-  // one-shot subagents are auto-upgraded to conversation mode on first message (SP-5); ended ones throw.
+  // action:"message" → messageParam.subagentId + text REQUIRED. Any reachable subagent works —
+  // running joins the in-flight round (D2 打断入队)；idle transparently revives on the same
+  // session file（[U4 §3.2.3] 万物可续——形态枚举 gate 与 SP-5 升级路径均消亡，message 直接
+  // 续聊任何 idle record）。引擎续聊能力轴 gate 保留（core messageHandler 入口）。
+  // description 与实现锚点见 messageHandler。
   messageParam: Type.Optional(Type.Object({
     subagentId: Type.String({
-      description: "REQUIRED for action:'message'. The subagentId to message (any running subagent; a one-shot subagent is auto-upgraded to conversation mode on first message, so you may also message one-shot subagents that are still running).",
+      description: "REQUIRED for action:'message'. The subagentId to message. Any subagent reachable in this session tree works, running or idle: an idle subagent transparently revives on the same id and continues writing its original session file; a running subagent has your message interrupt-and-join its in-flight round. Rejections: unknown id, session file held by another live process, a record from a different session tree, workflow-origin records (their results belong to the workflow run), and records on engines that do not support continuation (fork-from or re-dispatch instead).",
     }),
     text: Type.String({
       description: "REQUIRED for action:'message'. The message to send. Whitespace-only throws.",
     }),
     interrupt: Type.Optional(Type.Boolean({
-      description: "If true, interrupt the subagent's current work immediately (in-progress output stops, it switches to your new message). If false (default), the message is queued and processed after the current round completes. When the subagent is idle (between rounds), interrupt has no effect — the message always starts a new round.",
+      // [H1 U6 / D2] 参数已退役（messageHandler 零消费）：在途轮存在即打断入队，
+      // 不区分抢占/排队——字段保留防存量调用 schema 报错，description 据实声明 no-op。
+      description: "Deprecated, no effect: a message to a running subagent always interrupts its in-flight round (the round aborts and your message is processed next) regardless of this flag; an idle subagent always starts a new round.",
     })),
   })),
-  // action:"close" → closeParam.subagentId REQUIRED. Ends a running subagent (conversation-mode
-  // or one-shot — closeSubagent behavior split covers both).
+  // action:"close" → closeParam.subagentId REQUIRED. 归档（archived）：列表隐藏、可寻回、
+  // 非终态化（[U5 §3.2.5]）。idle 立即归档收口；running 默认等当前轮收口后归档，
+  // force:true 立即终止随即归档（closeHandler 头注行为分流）。
   closeParam: Type.Optional(Type.Object({
     subagentId: Type.String({
-      description: "REQUIRED for action:'close'. The subagentId to close (any running subagent, conversation-mode or one-shot).",
+      description: "REQUIRED for action:'close'. The subagentId to close (any reachable subagent — running or idle). Close archives the record: hidden from list, recoverable, not a terminal state. Idle subagents close immediately; running ones finish the current round first, or terminate immediately when force:true.",
     }),
     force: Type.Optional(Type.Boolean({
       description: "If true, terminate immediately even if mid-round (in-progress work is lost). If false (default), let the current round finish, then close. When idle, the subagent closes immediately regardless.",
@@ -173,7 +173,7 @@ export const SubagentParams = Type.Object({
   // 源文件只读不续写）；旧记录/状态机不动。pi 引擎限定（非 pi 在 execute 层拒绝）。
   forkFromParam: Type.Optional(Type.Object({
     sourceSubagentId: Type.String({
-      description: "REQUIRED for action:'fork-from'. The OLD subagentId whose conversation history becomes the inherited context of the new subagent. Works for records disconnected by a session restart or already finished; cancelled/worktree-bound/still-running ones are rejected with guidance.",
+      description: "REQUIRED for action:'fork-from'. The OLD subagentId whose conversation history becomes the inherited context of the new subagent. Works for any idle record — disconnected by a session restart, already finished, or previously closed/cancelled. Rejections: still-running sources (message them instead), sources held by another live process, worktree-bound sources, and unknown ids; an unparseable history anchor is guided to action:'message' (same-id reopen) instead.",
     }),
     prompt: Type.Optional(Type.String({
       description: "Continuation instruction for the new subagent (what to do next on top of the inherited history). When omitted, a standard handover frame is injected: reconstruct done/decided/remaining from the inherited history, then continue to completion. Whitespace-only treated as omitted.",

package/src/interface/subagent-tool.ts

@@ -162,12 +162,12 @@ action:"list" before action:"start" — a reusable subagent may exist; compactio
 
 ## Actions
 
-- action:"start" — run a subagent. Pass task and slug as top-level fields (REQUIRED). Optional: agent, model, thinkingLevel, engine, collect, skillPath, appendSystemPrompt, schema, maxTurns, graceTurns, fork, worktree, cwd, conversation, idleTimeoutMs. Background only: returns a subagentId immediately, notifies on completion.
-- action:"message" — send a follow-up to a running subagent (conversation-mode or one-shot); full context retained. REQUIRED messageParam: { subagentId, text }. Optional: interrupt (default false). The reply auto-notifies.
-- action:"close" — end a running subagent and release its resources. REQUIRED closeParam: { subagentId }. Optional: force (default false = let the current round finish; true terminates mid-round).
+- action:"start" — run a subagent. Pass task and slug as top-level fields (REQUIRED). Optional: agent, model, thinkingLevel, engine, collect, skillPath, appendSystemPrompt, schema, maxTurns, graceTurns, fork, worktree, cwd, idleTimeoutMs. Background only: returns a subagentId immediately, notifies on completion.
+- action:"message" — send a follow-up to any of your subagents — running or idle (idle revives in place; full context retained). REQUIRED messageParam: { subagentId, text }. The reply auto-notifies.
+- action:"close" — archive a subagent (hidden from list, recoverable): idle closes immediately; running finishes the current round first unless force:true (then terminates mid-round). REQUIRED closeParam: { subagentId }.
 - action:"list" — list subagents. listParam: { includeFinished?, includeWorkflow?, limit? } (all optional; includeWorkflow defaults false — workflow-dispatched subagents are hidden unless true). Read an item's sessionFile for full detail.
-- action:"cancel" — stop a background subagent (for conversation-mode use close). REQUIRED cancelParam: { subagentId }.
-- action:"fork-from" — restart-disconnect recovery: spawn a NEW subagent inheriting the old one's history via --fork. REQUIRED forkFromParam: { sourceSubagentId }. Optional: prompt (continuation; default handover frame). Returns { newSubagentId, sourceSessionFile }. Rejects cancelled / worktree-bound / still-running sources.
+- action:"cancel" — stop a background subagent (to archive it instead, use close). REQUIRED cancelParam: { subagentId }.
+- action:"fork-from" — restart-disconnect recovery: spawn a NEW subagent inheriting the old one's history via --fork. REQUIRED forkFromParam: { sourceSubagentId }. Optional: prompt (continuation; default handover frame). Returns { newSubagentId, sourceSessionFile }. Rejects still-running / foreign-live / worktree-bound sources; unparseable history anchors are guided to action:"message" (same-id reopen).
 
 ## Examples
 
@@ -191,8 +191,8 @@ Completion auto-notifies you (steer wakes the next turn):
 
 ## Batch collection (collect)
 
-- collect:"sync" — >=2 independent one-shot subagents whose results you will combine: completions are held until every pending sync member finishes, then ONE batch notification delivers all results inline (one wake-up). Later sync starts join the same batch; each sync start response reports {"collect":{"mode":"sync","pendingSyncCount":N}}.
-- collect:"async" (default, omit) — immediate per-subagent completion; for conversational work or when each result is needed early.
+- collect:"sync" — >=2 independent subagents whose results you will combine: completions are held until every pending sync member finishes, then ONE batch notification delivers all results inline (one wake-up) and batch members auto-archive. Later sync starts join the same batch; each sync start response reports {"collect":{"mode":"sync","pendingSyncCount":N}}. Batch members cannot be messaged — fork-from continues from one.
+- collect:"async" (default, omit) — immediate per-subagent completion; use when each result is needed early.
 - Subagents in one sync batch must not depend on each other's output — dependent tasks must be chained across messages (see Calling patterns), never batched.
 Items over budget are truncated with a pointer: session_read {"action":"result","session":"<id>"} fetches the full text.
 
@@ -204,16 +204,15 @@ Items over budget are truncated with a pointer: session_read {"action":"result",
 - Treating subagent results as authoritative without verification.
 - Canceling by guessing a subagentId instead of using action:"list" first.
 
-## Continuous chat (conversation mode)
+## Continuing a subagent (modeless)
 
-conversation:true keeps a subagent available across replies — action:"message" continues with full context, action:"close" releases it (always close when done). For review/fix loops and long-interval rounds (>5min apart, raise idleTimeoutMs); omit for one-shot tasks.
-idleTimeoutMs: idle timeout before auto-cleanup (default 300000 / 5min; env XYZ_SUBAGENT_IDLE_TIMEOUT_MS overrides globally, per-call wins).
+Every subagent stays continuable — no mode switch: action:"message" revives an idle record in place (or joins a running one's round), action:"fork-from" branches a new subagent from old history, action:"close" archives it.
+idleTimeoutMs: idle-recycle cadence for ALL subagents — idle records auto-archive on expiry (default 300000 / 5min; 0/negative disables; env XYZ_SUBAGENT_IDLE_TIMEOUT_MS: global default, per-call wins).
 
 ## You cannot
 
 - Get a synchronous/inline result — start always returns a subagentId immediately (background).
 - Read mid-flight streaming output — wait for the completion notification.
-- Combine collect:"sync" with conversation:true — rejected before start; sync is one-shot only (remove one).
 - See intermediate signals while a sync batch waits — nothing arrives until the whole batch closes. Hung member: action:"list" shows what is still running; action:"cancel" it — cancelled members count as terminal and the batch closes.
 
 ## Calling patterns

package/src/interface/tool-workflow.ts

@@ -431,7 +431,7 @@ export async function actionRun(
   const args = params.args ?? {};
   const tokens = params.tokens;
   const time = params.time;
-  // OR-1 入口 fail-fast（unbounded-wait-audit §7.2 T3①）：schema 的 time 是
+  // OR-1 入口 fail-fast（crash-forensics-and-watchdog.md 附录 E（原 unbounded-wait-audit §7.2 T3①））：schema 的 time 是
   // Type.Number 直通（无上界）——超 setTimeout 安全域的值会穿透到 lifecycle 内层
   // 防线（assertSafeTimerDelay），而入口拦截让它永不进入副作用链。错误带合法上限
   // 与实际传入值，LLM 可据消息自纠（clamp 或省略走 unlimited 语义）。

package/src/interface/views/WorkflowsView.ts

@@ -11,7 +11,7 @@
  *
  * SDK 集成：ctx.ui.custom factory 返回 Component{render(width), handleInput(data),
  * invalidate}，第二参数 `{overlay:true, overlayOptions}`（全屏 overlay，对齐 main +
- * subagents 扩展 + docs/pi-tui-development-guide.md §3.2）。按键经
+ * subagents 扩展 + docs/extensions/tui-rendering-pitfalls.md §3.2）。按键经
  * matchesKey(data, KeyId) 解析（兼容 xterm/iTerm/kitty 转义序列差异）。
  * escape/ctrl+c 在 keybindings 同映射到 exit。
  *

package/src/interface/views/__tests__/record-progress.test.ts

@@ -19,7 +19,8 @@
  */
 import { describe, it, expect } from "vitest";
 
-import { computeElapsedSeconds, getAllToolCalls, projectLiveProgress } from "@zhushanwen/subagent-core";
+import { computeElapsedSeconds, getAllToolCalls } from "@zhushanwen/subagent-core";
+import { projectLiveProgress } from "@zhushanwen/subagent-core/execution/persistence/execution-record.ts";
 import type { ExecutionRecord, SubagentRecord, WorkflowRun } from "@zhushanwen/subagent-core";
 import { collectNodeLiveProgress } from "../WorkflowsView.ts";
 import { projectRecordProgress } from "../detail-content.ts";

package/src/jsonl-run-store.ts

@@ -90,7 +90,7 @@ import {
   pruneStateFilesBeyondCap,
   type RunSnapshot,
 } from "@zhushanwen/subagent-core";
-import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { isEnoentError, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 // ── Workflow-record self-describing entry (W17, D4) ─────────
 
@@ -226,16 +226,6 @@ async function loadRunFromStateFile(filePath: string): Promise<WorkflowRun | nul
 
 // ── JsonlRunStore ────────────────────────────────────────────
 
-/** Node fs 错误 code 判定（ENOENT = 路径不存在，并发删除场景）。 */
-function isEnoentError(err: unknown): boolean {
-  return (
-    typeof err === "object" &&
-    err !== null &&
-    "code" in err &&
-    (err as { code: unknown }).code === "ENOENT"
-  );
-}
-
 const logger = getLogger("subagents");
 
 /**

package/src/session-lifecycle.ts

@@ -300,7 +300,6 @@ function appendSubagentIdentityEntry(pi: ExtensionAPI): void {
         process.env.PI_SUBAGENT_FORK_DEPTH !== undefined
           ? Number(process.env.PI_SUBAGENT_FORK_DEPTH)
           : undefined,
-      chatMode: process.env.PI_SUBAGENT_CHAT_MODE === "true",
       // [review round2] worktree 隔离标志（session-runner 注入）：跨重启重建路径据此
       // 拒绝续聊（handle 不可序列化，reattach 不可行）。
       worktree: process.env.PI_SUBAGENT_WORKTREE === "true",
@@ -373,7 +372,8 @@ export function bindLedgerHostAndRecover(pi: ExtensionAPI, ctx: ExtensionContext
 /**
  * 随迁块 4 的进程级维护三连（各 try-catch「失败记日志不阻断」，设计 §3.4）：
  * 过期 session 文件清理 / ADR-035 manifest tmp 恢复 / ADR-035 worktree reaper 扫描。
- * 另含 [E1] sync 批崩溃恢复（per-session 域，不用 oncePerProcess——见块内注释）。
+ * （[modeless 波5] 原 [E1] sync 批崩溃恢复接线已摘除——collectMode 记录态消亡后
+ * core 侧 recoverSyncCollectBatch 已是 accepted-no-op，调用点随之退役。）
  */
 async function runProcessLevelMaintenance(
   agentDir: string,
@@ -381,22 +381,6 @@ async function runProcessLevelMaintenance(
   service: SubagentService,
   deps: SessionLifecycleDeps,
 ): Promise<void> {
-  // [E1] sync 批崩溃恢复（subagent-sync-collect 设计 §3.1.5 E1，U5 接线）：扫描主
-  // session 末条 entry 重建批缓冲；全员终态未投递 → notifyBatch 补发 + 统一补
-  // batchFinalized 标记（账本同 hash 幂等拒绝也算已投递）。须晚于 initSession（孤儿
-  // 终态恢复先行收敛 running 成员，createOrReuseServices 内部同步完成）与 ledger
-  // bind（补发走 notifyBatch 写账链，见上方 bindNotifyLedgerHost）。per-session 域
-  // （主 session 文件），不用 oncePerProcess；best-effort 不阻断 session_start。
-  // 时序约束在调用点 setupSessionLifecycle 已满足（bindLedgerHostAndRecover 与
-  // createOrReuseServices 均先于本 helper 调用）。
-  try {
-    service.recoverSyncCollectBatch();
-  } catch (err) {
-    logger.warn("[subagents] sync collect batch recovery failed", {
-      reason: toErrorMessage(err),
-    });
-  }
-
   try {
     // 递归扫描 <agentDir>/subagents + unlink 超 TTL 跨 session 文件属进程级维护
     // ——oncePerProcess 守卫防双跑（u-audit-fix）。