@zhushanwen/pi-subagent-workflow 8.10.1 → 8.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.10.1",
+  "version": "8.12.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.8.2",
+    "@xyz-agent/extension-protocol": "0.9.0",
     "@xyz-agent/session-delivery": "0.3.1",
-    "@zhushanwen/pi-ext-guards": "0.2.1",
-    "@zhushanwen/pi-extension-logger": "0.4.1",
-    "@zhushanwen/subagent-core": "0.7.1",
-    "@zhushanwen/pi-subagent-cli": "0.1.2",
-    "@zhushanwen/zcode-subagent-cli": "0.1.2"
+    "@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"
   },
   "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.6.0",
-    "@zhushanwen/pi-structured-output": "5.1.4"
+    "@zhushanwen/pi-pending-notifications": "0.7.0",
+    "@zhushanwen/pi-structured-output": "5.1.5"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

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

@@ -0,0 +1,237 @@
+// inflight-reporter.test.ts —— 壳层在途上报出口（u7a，设计 §3.3 D5）。
+//
+// 三视角：
+//   ①使用者（runtime event-adapter 视角）——帧形状：title=SUBAGENT_INFLIGHT_MARKER、
+//     options=[JSON 帧]（kind/inFlight/sessionId/emittedAt）、控制面级 timeout 在场；
+//   ②构建者——初始上报（attachSession 触发，kind='initial'，无需任何 subagent 调用）
+//     → ack 成功一次后转 'delta'；失败折叠 + 延迟重试直至成功一次；推送在途期间
+//     多次迁移合并为单帧且携带最新绝对计数；
+//   ③观察者——onInFlightChanged 同步返回（不 await select，不进生命周期链）；
+//     detachSession 停重试，session 死后通道静默。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── hoisted mocks（依赖收窄：logger 防文件落盘；core barrel 只留快照函数可控点） ──
+
+const extensionLoggerMock = vi.hoisted(() => ({
+  getLogger: vi.fn(() => ({
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  })),
+}));
+
+const mockSnapshot = vi.hoisted(() => vi.fn((): { inFlight: number } => ({ inFlight: 0 })));
+
+vi.mock("@zhushanwen/pi-extension-logger", () => extensionLoggerMock);
+vi.mock("@zhushanwen/subagent-core", () => ({ getInFlightSnapshot: mockSnapshot }));
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { INFLIGHT_REPORT_ACK, SUBAGENT_INFLIGHT_MARKER } from "@xyz-agent/extension-protocol";
+
+import { createInFlightReporter } from "../inflight-reporter.ts";
+
+const RETRY_MS = 50;
+const SELECT_TIMEOUT_MS = 1_000;
+
+type SelectCall = { title: string; payload: string; timeout: number | undefined };
+
+/** 可控 select 通道：每次调用的应答由用例逐帧裁决（ack / undefined / 抛错 / 挂起）。 */
+function makeSelectChannel() {
+  const calls: SelectCall[] = [];
+  const pending: Array<(v: unknown) => void> = [];
+  const select = vi.fn(
+    (title: string, options: string[], opts?: { timeout?: number }): Promise<unknown> => {
+      calls.push({ title, payload: options[0] ?? "", timeout: opts?.timeout });
+      return new Promise((resolve) => pending.push(resolve));
+    },
+  );
+  return {
+    select,
+    calls,
+    /** resolve 第 N 帧（0 起）。 */
+    settle(index: number, value: unknown): void {
+      pending[index]?.(value);
+    },
+    settleAll(value: unknown): void {
+      while (pending.length > 0) pending.shift()?.(value);
+    },
+  };
+}
+
+function makeCtx(channel: ReturnType<typeof makeSelectChannel>, sessionId = "sess-u7a"): ExtensionContext {
+  return {
+    cwd: "/w",
+    mode: "rpc",
+    sessionManager: { getSessionId: () => sessionId },
+    ui: { select: channel.select },
+  } as unknown as ExtensionContext;
+}
+
+function parseFrame(call: SelectCall): Record<string, unknown> {
+  return JSON.parse(call.payload) as Record<string, unknown>;
+}
+
+beforeEach(() => {
+  mockSnapshot.mockImplementation(() => ({ inFlight: 0 }));
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+/** 推进 fake 时间并排空微任务（attempt 的 await 链走完）。 */
+async function advance(ms: number): Promise<void> {
+  await vi.advanceTimersByTimeAsync(ms);
+}
+
+describe("初始上报（D5：触发时点 = extension 加载完成 / session 就绪）", () => {
+  it("attachSession 即发 kind='initial' 帧（count=当下快照，无需任何 subagent 调用）", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS, selectTimeoutMs: SELECT_TIMEOUT_MS });
+
+    reporter.attachSession(makeCtx(channel));
+    await advance(0);
+
+    expect(channel.calls).toHaveLength(1);
+    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.inFlight).toBe(0);
+    expect(frame.sessionId).toBe("sess-u7a");
+    expect(typeof frame.emittedAt).toBe("number");
+
+    channel.settleAll(INFLIGHT_REPORT_ACK);
+    await advance(0);
+  });
+
+  it("初始未送达前发生的迁移不产生第二帧（合并进 initial，送达后转 delta）", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    reporter.attachSession(makeCtx(channel));
+    await advance(0);
+
+    mockSnapshot.mockImplementation(() => ({ inFlight: 2 }));
+    reporter.onInFlightChanged();
+    reporter.onInFlightChanged();
+    await advance(0);
+    expect(channel.calls).toHaveLength(1); // 推送在途 → 只置脏，无第二帧
+
+    channel.settleAll(INFLIGHT_REPORT_ACK);
+    await advance(0);
+    expect(channel.calls).toHaveLength(2);
+    const delta = parseFrame(channel.calls[1]);
+    expect(delta.kind).toBe("delta");
+    expect(delta.inFlight).toBe(2); // 补推帧携带最新绝对计数
+  });
+});
+
+describe("绝对计数语义（每帧携带当下值，非增量）", () => {
+  it("连续迁移各帧均为整值快照（2 → 0，不做加减）", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    reporter.attachSession(makeCtx(channel));
+    await advance(0);
+    channel.settleAll(INFLIGHT_REPORT_ACK);
+    await advance(0);
+
+    mockSnapshot.mockImplementation(() => ({ inFlight: 2 }));
+    reporter.onInFlightChanged();
+    await advance(0);
+    mockSnapshot.mockImplementation(() => ({ inFlight: 0 }));
+    reporter.onInFlightChanged(); // attempt(count=2) 仍在途 → 置脏合并
+    expect(channel.calls).toHaveLength(2);
+
+    // 前帧 ack 落定后，脏标记触发补推（携带此刻快照 0）
+    channel.settleAll(INFLIGHT_REPORT_ACK);
+    await advance(0);
+    expect(channel.calls).toHaveLength(3);
+    expect(parseFrame(channel.calls[1]).inFlight).toBe(2);
+    expect(parseFrame(channel.calls[2]).inFlight).toBe(0);
+    channel.settleAll(INFLIGHT_REPORT_ACK);
+  });
+});
+
+describe("失败折叠 + 延迟重试直至成功一次（D5 缺席语义②）", () => {
+  it("select resolve undefined（超时/旧版 runtime）→ 折叠重试；重试帧仍 kind='initial'；ack 后停", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS, selectTimeoutMs: SELECT_TIMEOUT_MS });
+    reporter.attachSession(makeCtx(channel));
+    await advance(0);
+    expect(channel.calls).toHaveLength(1);
+
+    // 首帧无人 ack，select 以 undefined 落定（超时形态）→ 折叠
+    channel.settle(0, undefined);
+    await advance(RETRY_MS - 1);
+    expect(channel.calls).toHaveLength(1); // 未到退避点不重试
+    await advance(1);
+    expect(channel.calls).toHaveLength(2);
+    expect(parseFrame(channel.calls[1]).kind).toBe("initial"); // 初始「成功一次」未达成
+
+    // 重试帧得到 ack → 重试停止；随后迁移以 delta 送达
+    channel.settle(1, INFLIGHT_REPORT_ACK);
+    await advance(RETRY_MS * 10);
+    expect(channel.calls).toHaveLength(2);
+
+    reporter.onInFlightChanged();
+    await advance(0);
+    expect(channel.calls).toHaveLength(3);
+    expect(parseFrame(channel.calls[2]).kind).toBe("delta");
+    channel.settleAll(INFLIGHT_REPORT_ACK);
+  });
+
+  it("select 通道抛错同样折叠进重试路径", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    reporter.attachSession(makeCtx(channel));
+    await advance(0);
+    channel.settle(0, new Error("channel blew up"));
+    await advance(RETRY_MS);
+    expect(channel.calls.length).toBeGreaterThanOrEqual(2);
+    channel.settleAll(INFLIGHT_REPORT_ACK);
+    await advance(0);
+  });
+
+  it("非确认回包（旧版 runtime 的任意字符串）不算送达，继续重试", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    reporter.attachSession(makeCtx(channel));
+    await advance(0);
+    channel.settle(0, '{"ok":1}');
+    await advance(RETRY_MS);
+    expect(channel.calls).toHaveLength(2);
+    channel.settleAll(INFLIGHT_REPORT_ACK);
+    await advance(0);
+  });
+});
+
+describe("不阻塞生命周期主链（D5 接线约束①）", () => {
+  it("onInFlightChanged 同步返回：select 永不落定也不挂调用方（detach 可丢弃在途帧）", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    reporter.attachSession(makeCtx(channel));
+    await advance(0);
+
+    // 第一帧挂起（模拟 runtime 无响应）——迁移调用仍同步返回
+    expect(() => reporter.onInFlightChanged()).not.toThrow();
+
+    // session 死后 detach：挂起帧被丢弃，重试链静止（时间推进零新调用）
+    reporter.detachSession();
+    channel.settleAll(undefined);
+    await advance(RETRY_MS * 5);
+    expect(channel.calls).toHaveLength(1);
+  });
+
+  it("detachSession 清掉待发重试定时器（session 已死，重试语义随之终结）", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    reporter.attachSession(makeCtx(channel));
+    await advance(0);
+    reporter.detachSession();
+    channel.settleAll(undefined); // 在途帧失败落定——ctx 已空，不排新重试
+    await advance(RETRY_MS * 10);
+    expect(channel.calls).toHaveLength(1);
+  });
+});

package/src/host/inflight-reporter.ts

@@ -0,0 +1,193 @@
+// src/host/inflight-reporter.ts
+//
+// 壳层在途上报出口（u7a，设计权威源：docs/design/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 接线）。
+//
+// 链路：core 状态迁移点（session-runner 子进程注册/移除、idle timer arm/disarm）
+// → notifyInFlightChanged（同步回调）→ 本 reporter（绝对计数快照 → select 通道帧，
+// title = SUBAGENT_INFLIGHT_MARKER）→ runtime event-adapter（u7b）。
+//
+// D5 接线三约束的落点：
+//   ① 不阻塞生命周期主链——onInFlightChanged 同步返回，推送全部 void fire-and-forget，
+//      绝不进 agent_settled handler await 链；
+//   ② 事件产生点在 core、上报出口在壳层——本文件即出口（core 零 pi SDK）；
+//   ③ marker 路由不广播前端是 u7b（runtime 侧）的约束，本文件不涉及。
+//
+// 语义（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 也必上报）。
+//
+// 失败语义（D5 缺席语义②）：select 失败（超时/通道异常/非确认回包）折叠后**延迟重试
+// 直至成功一次**。送达判据 = runtime resolve 的确认回包（INFLIGHT_REPORT_ACK）——
+// fire-and-forget 下 resolve(undefined) 与超时不可区分，必须靠显式 ack 区分「已送达」
+// 与「旧版 runtime 无路由」，否则 errs 判别（「从未收到上报」只覆盖缺席/旧版）失效。
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { SUBAGENT_INFLIGHT_MARKER, isInFlightReportAck } from "@xyz-agent/extension-protocol";
+import { getInFlightSnapshot } from "@zhushanwen/subagent-core";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+/** select 通道级超时（控制面单请求，秒级校准——超时默认原则规则 19）。取值对齐
+ *  plugin-bridge 启动 sync 的 2s 自愈闸：session_start 首帧可能早于 runtime adapter
+ *  attach（R2 实证），超时折叠后重试必然自愈；fire-and-forget 帧不留 pending 挂死面。 */
+const SELECT_TIMEOUT_MS = 2_000;
+
+/** 失败重试退避（对齐 plugin-bridge SYNC_RETRY_MS 控制面节奏）。 */
+const RETRY_DELAY_MS = 2_000;
+
+/** 在途上报器（组合根 index.ts 持有；per-factory 实例，session_start/shutdown 驱动）。 */
+export interface InFlightReporter {
+  /**
+   * session_start 注入当前 ctx 并发起初始上报（fire-and-forget——本方法同步返回，
+   * 不阻塞 session_start 装配链；初始帧 kind='initial'，count 为当下绝对计数）。
+   */
+  attachSession(ctx: ExtensionContext): void;
+  /** session_shutdown 摘除 ctx 并停止重试（session 已死，上报通道随之终结）。 */
+  detachSession(): void;
+  /** core 出口回调（notifyInFlightChanged 直连）：同步返回，内部合并 + void 推送。 */
+  onInFlightChanged(): void;
+}
+
+export interface InFlightReporterOpts {
+  /** 测试注入：select 超时（ms）。缺省 SELECT_TIMEOUT_MS。 */
+  selectTimeoutMs?: number;
+  /** 测试注入：重试退避（ms）。缺省 RETRY_DELAY_MS。 */
+  retryDelayMs?: number;
+}
+
+/**
+ * sessionId 从 ctx 取（plugin-bridge getSessionId 同款防御）：pi session 文件延迟写入
+ * 窗口内取失败不阻断上报——sessionId 缺席时 runtime 按无法归属丢弃整帧（契约
+ * SubagentInFlightReport.sessionId 可选语义），不视为协议错误。
+ */
+function getSessionId(ctx: ExtensionContext): string | undefined {
+  try {
+    return ctx.sessionManager.getSessionId();
+  } catch {
+    return undefined;
+  }
+}
+
+export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFlightReporter {
+  const selectTimeoutMs = opts.selectTimeoutMs ?? SELECT_TIMEOUT_MS;
+  const retryDelayMs = opts.retryDelayMs ?? RETRY_DELAY_MS;
+  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 场景会长期重试）。 */
+  let firstFailureLogged = false;
+
+  function clearRetryTimer(): void {
+    if (retryTimer !== null) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+  }
+
+  /** 推送在途或无 ctx 时仅置脏；否则发起一次尝试（void，不阻塞调用方）。 */
+  function kick(): void {
+    if (attemptInFlight || ctx === null) {
+      dirty = true;
+      return;
+    }
+    dirty = false;
+    attemptInFlight = true;
+    void attempt();
+  }
+
+  async function attempt(): Promise<void> {
+    const active = ctx;
+    if (active === null) {
+      attemptInFlight = false;
+      return;
+    }
+    // 帧内容在发送时刻现取：绝对计数 = 此刻快照（「当前非 idle 句柄数」）、
+    // 产生时点 = 此刻、kind 按初始上报是否已送达裁决（初始未送达前，脏帧也以
+    // initial 语义送达——对 errs 判别等价：runtime 收到任何帧即「在场」）。
+    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);
+    }
+    attemptInFlight = false;
+    if (typeof value === "string" && isInFlightReportAck(value)) {
+      // 送达确认：清重试；初始上报「成功一次」达成后，后续帧一律 delta。
+      initialAcked = true;
+      clearRetryTimer();
+      if (dirty && ctx !== null) kick();
+      return;
+    }
+    // 失败折叠（resolve undefined = 超时/取消/旧版无路由）→ 延迟重试直至成功一次
+    //（D5 缺席语义②：使「从未收到」只覆盖缺席/旧版形态，不覆盖一次性丢包）。
+    logFailure("no ack (timeout, cancelled, or runtime without marker routing)", value);
+    if (ctx !== null && retryTimer === null) {
+      retryTimer = setTimeout(() => {
+        retryTimer = null;
+        kick();
+      }, retryDelayMs);
+      // unref：不阻塞进程退出（退出收割由既有 process hook 负责，与 plugin-bridge 同款）。
+      retryTimer.unref?.();
+    }
+  }
+
+  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),
+      });
+      return;
+    }
+    logger.debug(`[subagent-inflight] in-flight report retry failed (${reason})`);
+  }
+
+  return {
+    attachSession(target: ExtensionContext): void {
+      ctx = target;
+      clearRetryTimer();
+      // 初始上报（count=当下绝对计数；session 就绪时点恒为 0——子进程只会在后续
+      // subagent 调用里出现）。fire-and-forget：不阻塞 session_start 装配链。
+      kick();
+    },
+
+    detachSession(): void {
+      ctx = null;
+      dirty = false;
+      clearRetryTimer();
+    },
+
+    onInFlightChanged(): void {
+      // 同步返回（D5 约束①）：core 迁移点直连本方法，任何 await 都会进
+      // agent_settled 等生命周期链——这里只置脏 + void 发起。
+      kick();
+    },
+  };
+}

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 签名）。
  */
@@ -20,10 +23,13 @@ import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 // ═══ core 宿主端口接线（subagent-core 包抽离 u0-wire；实现见 src/host/pi-host.ts） ═══
 import { configureCore } from "@zhushanwen/subagent-core";
 import { configureNotifyDomain } from "@zhushanwen/subagent-core";
+import { setInFlightListener } from "@zhushanwen/subagent-core";
 import { createPiHostServices, createPiNotifyDomainPorts } from "./host/pi-host.ts";
+// [u7a D5] 壳层在途上报出口：core 状态迁移 → 本出口 → select 通道（marker 帧）→ runtime。
+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'
@@ -50,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 {
@@ -146,6 +152,13 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // [P3 引擎接线] 登记 'zcode'（幂等同上）。D8 薄壳：vendored 定位 cli descriptor。
   registerZcodeEngine();
 
+  // [u7a D5] 在途聚合上报接线：core 状态迁移（spawn/close/arm/disarm）→ 出口回调 →
+  // 本 reporter 经 select 通道推绝对计数帧。出口为进程级单监听（在途记账本身是 pi
+  // 进程级模块状态），后注册覆盖先注册（jiti 重载幂等）；回调同步 void，不进任何
+  // 生命周期 await 链（D5 接线约束①）。ctx 由 session_start 注入（factory 阶段无 ui）。
+  const inflightReporter = createInFlightReporter();
+  setInFlightListener(inflightReporter.onInFlightChanged);
+
   // [U7b] 引擎列表在 extension 模块加载时即同步 engines.json（不等 session_start——
   // 用户体验拍板 2026-08-25：xyz-agent 打开后激活任意 session 的第一时间（含 TUI 等价
   // 场景）GUI 引擎选择器就该有数据；session_start 处保留幂等重写兜底 jiti 双路径/
@@ -263,7 +276,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;
@@ -288,6 +312,10 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // ════════════════════════════════════════════════════════════
   pi.on("session_start", async (_event: SessionStartEvent, ctx: ExtensionContext) => {
     lsRef.lastSessionId = ctx.sessionManager.getSessionId();
+    // [u7a D5] 初始上报（count=当下绝对计数）：触发时点 = extension 加载完成 / session
+    // 就绪（factory 无 ctx/ui，session_start 是最早带 ctx 的钩子——plugin-bridge 同款
+    // 事实）。fire-and-forget 在 await 装配链之前发起，不阻塞也不被阻塞。
+    inflightReporter.attachSession(ctx);
     const result = await setupSessionLifecycle(pi, ctx, makeLifecycleDeps());
     sessionState.set(result.sessionId, result);
   });
@@ -412,6 +440,10 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     // ── subagents 域：dispose SubagentService ──
     getSubagentService()?.dispose();
 
+    // [u7a D5] 在途上报通道随 session 终结：摘 ctx + 停重试（session 已死，重试直至
+    // 成功的语义只对活 session 成立；进程级出口监听保留——后续 /new 重新 attach）。
+    inflightReporter.detachSession();
+
     // ── workflow 域：terminate 所有 running run + store 收尾 + 清理 temp files ──
     // H-5: 遍历所有 sessionState 条目清理（而不只 lastSessionId——
     // 防御 session 切换但 session_tree 未先触发导致 lastSessionId 指向已删除 session 的情况）。
@@ -468,9 +500,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();

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

@@ -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/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

@@ -494,6 +494,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 区用）。
  *