@zhushanwen/pi-subagent-workflow 8.11.0 → 8.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.11.0",
+  "version": "8.13.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,20 +54,20 @@
     ]
   },
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.9.0",
+    "@xyz-agent/extension-protocol": "0.10.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.8.0",
-    "@zhushanwen/pi-subagent-cli": "0.1.2",
-    "@zhushanwen/zcode-subagent-cli": "0.2.0"
+    "@zhushanwen/subagent-core": "0.10.0",
+    "@zhushanwen/pi-subagent-cli": "0.3.0",
+    "@zhushanwen/zcode-subagent-cli": "0.3.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-pending-notifications": "0.7.1",
     "@zhushanwen/pi-structured-output": "5.1.5"
   },
   "peerDependenciesMeta": {

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,21 +15,26 @@
 //   ② 事件产生点在 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";
@@ -44,11 +49,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 +72,8 @@ export interface InFlightReporterOpts {
   selectTimeoutMs?: number;
   /** 测试注入：重试退避（ms）。缺省 RETRY_DELAY_MS。 */
   retryDelayMs?: number;
+  /** 测试注入：累计失败放弃上限。缺省 MAX_REPORT_ATTEMPTS。 */
+  maxAttempts?: number;
 }
 
 /**
@@ -80,19 +92,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 +117,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,11 +135,9 @@ 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(),
@@ -139,15 +152,25 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
     }
     attemptInFlight = false;
     if (typeof value === "string" && isInFlightReportAck(value)) {
-      // 送达确认：清重试；初始上报「成功一次」达成后，后续帧一律 delta。
-      initialAcked = true;
+      // 送达确认：清重试与失败计数，补推积压脏帧。
+      failureCount = 0;
       clearRetryTimer();
       if (dirty && ctx !== null) kick();
       return;
     }
-    // 失败折叠（resolve undefined = 超时/取消/旧版无路由）→ 延迟重试直至成功一次
-    //（D5 缺席语义②：使「从未收到」只覆盖缺席/旧版形态，不覆盖一次性丢包）。
+    // 失败折叠（resolve undefined = 超时/取消/无路由）→ 延迟重试，累计到顶放弃
+    //（放弃后镜像按 absent-report 走 errs 推迟，30min 有界，errs-safe 兜底不丢）。
     logFailure("no ack (timeout, cancelled, or runtime without marker routing)", value);
+    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;
@@ -161,7 +184,7 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
   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`, {
+      logger.warn(`[subagent-inflight] in-flight report failed (${reason}); retrying every ${retryDelayMs}ms (bounded at ${maxAttempts} attempts)`, {
         detail: detail instanceof Error ? detail.message : String(detail),
       });
       return;
@@ -171,6 +194,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

@@ -5,10 +5,13 @@
  * 注册项：3 tool（subagent + workflow + workflow-script）+ 2 command（subagents + workflows）
  * + messageRenderer（subagent-bg-notify）+ pi.__workflowRun + session 事件。
  *
- * 三层架构：
- *   interface/ → 注册胶水（tools/commands/tui）
- *   orchestration/ → workflow engine（launcher/lifecycle/error-recovery）
- *   execution/ → subagents 执行运行时（SubagentService/session-runner/concurrency-pool）
+ * 包内结构（执行运行时已迁 packages/subagent-core，本包只留注册面与宿主适配）：
+ *   interface/ → 注册胶水（tools / commands / TUI 渲染 / GUI mappers）
+ *   host/      → pi 宿主端口实现（HostServices / NotifyDomain 的 pi 侧兑现）
+ *   injectors/ → 提示注入器（engine-awareness / model-list / resource-list …）
+ *   session-lifecycle.ts → 会话生命周期装配 seam（测试可注入 fake 依赖）
+ *
+ * 架构导航见 docs/extensions/subagents/architecture.md。
  *
  * 设计基线：D-004（旧包不动）/ ADR-025（进程内执行）/ D-8（pi.__workflowRun 签名）。
  */
@@ -26,7 +29,7 @@ import { createPiHostServices, createPiNotifyDomainPorts } from "./host/pi-host.
 import { createInFlightReporter } from "./host/inflight-reporter.ts";
 
 import { bestEffort } from "@zhushanwen/subagent-core";
-// ═══ execution/ 层（subagents 核心 + 运行时） ═══
+// ═══ 经 core barrel 消费执行域（执行运行时住 packages/subagent-core） ═══
 // [U7] 引擎列表状态文件（registry → engines.json，GUI 引擎选择器数据源）
 import { syncEnginesFile } from "@zhushanwen/subagent-core";
 // [W11/DoD#5] registerPiEngine（inproc 'pi' 注册）已随内建引擎删除：registry 'pi'
@@ -53,7 +56,7 @@ import { registerSubagentTool } from "./interface/subagent-tool.ts";
 import { registerSubagentsCommand } from "./interface/subagents.ts";
 import { registerWorkflowTool } from "./interface/tool-workflow.ts";
 import { registerWorkflowScriptTool } from "./interface/tool-workflow-script.ts";
-// ═══ orchestration/ 层（workflow engine + infra） ═══
+// ═══ 经 core barrel 消费 workflow 域（引擎与 worker 住 packages/subagent-core） ═══
 import type { LauncherDeps } from "@zhushanwen/subagent-core";
 import { executeNestedWorkflow, runAndWait, type WorkflowRunResult } from "@zhushanwen/subagent-core";
 import {
@@ -96,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 {
@@ -273,7 +279,18 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
         scheduleTimeBudget(runId, deps, budgetTimeMs),
       onWorkflowCall: (name: string, args: Record<string, unknown>, parentRun: WorkflowRun) =>
         executeNestedWorkflow(name, args, parentRun, deps),
-      streamSink: getSubagentService()?.getStreamSink() ?? undefined,
+      // [H2 W3] workflow agent() 统一派发入口（设计 §3.5）：pump 侧 dispatchAgentCall
+      // 经此转调 SubagentService.executeWorkflowAgent——真实 record（origin:"workflow"
+      // + parentRunId）进 store、共享池/守护/journal 归 service 编排；parentRunId 由
+      // pump 补 run.runId。service 单例在 session_start 后必在（run 只能于 session 内
+      // 派发）；null 时抛错由 pump 的 dispatchCall catch 兜底回发 failed result。
+      workflowAgentDispatch: (opts, parentRunId, signal) => {
+        const service = getSubagentService();
+        if (!service) {
+          throw new Error("workflow agent dispatch unavailable: subagent service not initialized");
+        }
+        return service.executeWorkflowAgent(opts, parentRunId, signal);
+      },
       log,
     };
     return deps;
@@ -486,9 +503,11 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   //  - beforeExit 是退出前最后事件，不 exit（自然退出）。
   //  - idempotent guard（reapSpawnedChildrenOnShutdown 内）防多信号叠加重复 kill。
   //
-  //  防线 iii（activate 互斥）已接入：subagent-service.ts 冷路径 resume 调
-  //  acquireActivateLock（含 30s 超时兜底，见 lifecycle-manager.ts ACTIVATE_LOCK_TIMEOUT_MS）。
-  //  防线 ii（启动 scanOrphanProcesses）骨架就位，启动时接入待实现。
+  //  防线 iii（activate 互斥）：未接线——acquireActivateLock 机制已随简化清扫删除
+  //  （历史接线点随协议化重构消失，仅余自持单测）。当前的双写者防护由
+  //  subagent-service 的 resumesInFlight 集合守卫承担。
+  //  防线 ii（启动孤儿扫描）：未接线，骨架已随 L2 死代码清扫删除（当前 piped stdio
+  //  下 stdin-EOF 自灭链覆盖崩溃路径，见 docs/design/v2-defense-ii-iii-resolution.md）。
   // ════════════════════════════════════════════════════════════
   process.on("SIGTERM", () => {
     reapSpawnedChildrenOnShutdown();
@@ -654,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 前缀指纹归因兼容）。
@@ -110,9 +110,6 @@ function fakeEngine(id: string, models: Array<{ id: string; name?: string }>): E
 		run: async () => {
 			throw new Error("not used in this test");
 		},
-		interact: async () => {
-			throw new Error("not used in this test");
-		},
 		read: async () => ({ engineId: id, turns: [], source: "outcome-only" }),
 		// 每次调用返回新数组实例（模拟 registry 每 turn 现值）——渲染必须与实例无关
 		listModels: () => models.map((m) => ({ ...m })),

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/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/commands.ts

@@ -22,11 +22,12 @@
 import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 
 import type { LauncherDeps } from "@zhushanwen/subagent-core";
-import { abortRun } from "@zhushanwen/subagent-core";
+import { abortRun, getSubagentService } from "@zhushanwen/subagent-core";
 import type { WorkflowRun } from "@zhushanwen/subagent-core";
 import { parseWorkflowRpcCommand, type WorkflowRpcAction } from "./command-actions.ts";
 import { createWorkflowsView, type ViewActions } from "./views/WorkflowsView.ts";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { LIST_LIMIT } from "./list-shared.ts";
 
 /** runId 截断长度（显示用）。 */
 const RUNID_SHORT = 8;
@@ -248,6 +249,12 @@ function sortedRuns(runs: Map<string, WorkflowRun>): WorkflowRun[] {
  *
  * ViewActions 通过 deps 调 lifecycle（abort），与 view 解耦——
  * view 单测可注入 mock actions（见 views/__tests__/WorkflowsView-signature.test.ts）。
+ *
+ * [H2 W3] live 进度数据源（设计 D2 进度源切换）：view 经 store 查询
+ * collectRecordsByParentRunId(run.runId)（内存 ∪ 磁盘重建 ∪ manifest，LIST_LIMIT
+ * 口径）配对 running trace node 渲染实时进度。service 单例未就绪（理论上 run 只能
+ * 于 session 内存在，session_start 后必在；防御分支）时不注入——view 走终态
+ * result 渲染路径。
  */
 async function openView(
   run: WorkflowRun,
@@ -256,7 +263,11 @@ async function openView(
   deps: LauncherDeps,
 ): Promise<void> {
   const actions: ViewActions = {
-    abort: (runId: string) => abortRun(runId, deps),
+    abort: (runId) => abortRun(runId, deps),
   };
-  await createWorkflowsView(run, theme, ctx, actions, deps.store.stateFilePath(run.runId));
+  const service = getSubagentService();
+  const liveRecords = service
+    ? () => service.queries.collectRecordsByParentRunId(run.runId, LIST_LIMIT)
+    : undefined;
+  await createWorkflowsView(run, theme, ctx, actions, deps.store.stateFilePath(run.runId), liveRecords);
 }

package/src/interface/format.ts

@@ -138,16 +138,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" };
   }
 }
@@ -494,6 +502,22 @@ export function formatElapsed(startedAt?: string, now: number = Date.now()): str
   return formatElapsedSeconds(Math.max(0, secs));
 }
 
+/**
+ * Run status 行的 elapsed（[H2 A2] done 后冻结）。
+ *
+ * 与 formatElapsed 的差异仅在 now 基准：completedAt 有值（run 已终态）时以
+ * completedAt 为基准 → elapsed 恒等于 completedAt - startedAt，不再随墙钟增长；
+ * running（completedAt 缺省）沿用 Date.now() 缺省实时跳动。时钟异常
+ * （completedAt < startedAt）由 formatElapsed 钳 0 兜底（"0s"）。
+ */
+export function formatRunStatusElapsed(
+  startedAt?: string,
+  completedAt?: string,
+  now: number = Date.now(),
+): string {
+  return formatElapsed(startedAt, completedAt ? new Date(completedAt).getTime() : now);
+}
+
 /**
  * Format a live eventLog entry（live 路径 Activity 区用）。
  *

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 + 领域类型（签名不变，消费方零改动）