@zhushanwen/pi-subagent-workflow 8.10.1 → 8.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.10.1",
+  "version": "8.11.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-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.1.2"
+    "@zhushanwen/zcode-subagent-cli": "0.2.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.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

@@ -20,7 +20,10 @@ 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 核心 + 运行时） ═══
@@ -146,6 +149,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 双路径/
@@ -288,6 +298,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 +426,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 的情况）。

package/src/interface/helpers.ts

@@ -9,11 +9,16 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { guardStaleCtx, toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 // bounded JSON pretty 序列化（IF13/#19，TC5/ES5）已下沉 core shared
 // （u-core-atomic 逐字平移，输出与原本地实现字节一致；本地实现已删）。
 import { boundedPrettySerialize } from "@zhushanwen/subagent-core";
 
+// 模块级 logger（与 session-lifecycle.ts / index.ts 同 component 名）
+const logger = getLogger("subagents");
+
 import type { WorkflowRun } from "@zhushanwen/subagent-core";
 import {
   guiComponent,
@@ -147,14 +152,31 @@ export function notifyDone(
     );
   }
 
-  pi.sendMessage(
+  // stale ctx 防御（crash-resilience D1 / ext-guards 审计 §7 blockers#1 收口）：
+  // notifyDone 经 index.ts onRunDone 在 workflow 完成链路异步触发，不在 pi emit() 的
+  // try/catch 内、无自有 try/catch——session 替换窗口触碰 stale pi 命中 assertActive
+  // （PS-30）即无人接 rejection 崩 pi（E1 同机制）。stale 静默降级（完成通知不投递，
+  // 用户可从 session 历史 / 工具结果看到 workflow 结果，判定见 stale-ctx-audit.md §4），
+  // 非 stale 错误原样上抛（守卫不吞真实 bug）。
+  guardStaleCtx(
+    () =>
+      pi.sendMessage(
+        {
+          customType: "workflow-result",
+          content,
+          display: true,
+          details,
+        },
+        { triggerTurn: true, deliverAs: "steer" }, // g4-allow: 存量待迁移——workflow 完成通知属结果语义，迁移切片复用 U2 账本设施（附录 B 待办）
+      ),
     {
-      customType: "workflow-result",
-      content,
-      display: true,
-      details,
+      label: "subagent-workflow:notifyDone",
+      onStale: (error) =>
+        logger.warn("workflow completion notice delivery skipped (stale ctx)", {
+          runId,
+          error: toErrorMessage(error),
+        }),
     },
-    { triggerTurn: true, deliverAs: "steer" }, // g4-allow: 存量待迁移——workflow 完成通知属结果语义，迁移切片复用 U2 账本设施（附录 B 待办）
   );
 }
 

package/src/session-lifecycle.ts

@@ -22,7 +22,7 @@ import * as path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
-import { oncePerProcess, toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { guardStaleCtx, oncePerProcess, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 // ═══ core 宿主端口消费（随迁块的依赖；production 默认实现住本文件） ═══
 import { getOrCreateChannelRegistry } from "@zhushanwen/subagent-core";
@@ -323,8 +323,12 @@ function appendSubagentIdentityEntry(pi: ExtensionAPI): void {
  * 随文件域隔离）。compaction 存活情况归 session_compact handler 的条件降级（P-B4
  * 探针阶段 5 实测，见 notify-ledger.ts compactionCheck）。装配失败不阻断
  * session_start（通知退回 notifier 的内核路径）。
+ *
+ * export + 返回装配的 NotifyLedgerHost = 测试直入 seam（可直调 sendDelivery 验证
+ * 守卫分诊）；生产调用方（setupSessionLifecycle）忽略返回值，行为不变。装配失败
+ * 返回 undefined。
  */
-function bindLedgerHostAndRecover(pi: ExtensionAPI, ctx: ExtensionContext): void {
+export function bindLedgerHostAndRecover(pi: ExtensionAPI, ctx: ExtensionContext): NotifyLedgerHost | undefined {
   try {
     const ledgerHost: NotifyLedgerHost = {
       appendLedgerEntry: (customType, data) => {
@@ -338,16 +342,31 @@ function bindLedgerHostAndRecover(pi: ExtensionAPI, ctx: ExtensionContext): void
       sendDelivery: (message) => {
         // D5 单通道：唯一发送形态 = sendCustomMessage({triggerTurn:true})，
         // courier 已在发送前二次复查 isIdle，多通道投递选项已删（D5）。
-        pi.sendMessage(message, { triggerTurn: true });
+        // stale ctx 防御（crash-resilience D1 / ext-guards 审计 §7 blockers#1 收口）：
+        // sendDelivery 经 settled 边沿 / 看门狗 / 恢复重放异步触发——session 替换窗口
+        // 触碰 stale pi 命中 assertActive（PS-30）即无人接 rejection（E1 同机制）。
+        // stale 静默降级（本条通知不投递，attemptDeliver 按已受理标 sentAt——session
+        // 替换后通知对旧 session 已无意义，与守卫前「留 pending 反复撞 stale 直到账本
+        // 重绑」终局一致），非 stale 错误原样上抛（attemptDeliver 既有 catch 走
+        // settleRejected 留账重试语义不变）。
+        guardStaleCtx(() => pi.sendMessage(message, { triggerTurn: true }), {
+          label: "subagent-workflow:sendDelivery",
+          onStale: (error) =>
+            logger.warn("notify delivery skipped (stale ctx)", {
+              error: toErrorMessage(error),
+            }),
+        });
       },
     };
     // U4：重放观测已内聚到 ledger 分桶日志（recoveryReplays 桶经 extensionLogger
     // 通道落盘），此处不再重复打日志。
     bindNotifyLedgerHost(ledgerHost).recoverFromSession();
+    return ledgerHost;
   } catch (err) {
     logger.warn("[subagents] notify ledger bind failed", {
       reason: toErrorMessage(err),
     });
+    return undefined;
   }
 }