@zhushanwen/subagent-core 0.7.0 → 0.8.0

package/src/execution/engine/__tests__/inflight-snapshot.test.ts

@@ -0,0 +1,180 @@
+// inflight-snapshot.test.ts —— core→壳在途事件出口 + EnginePort.inFlightSnapshot? 缺省语义
+//（u7a，设计权威源：docs/design/crash-forensics-and-watchdog.md §3.3 D5）。
+//
+// 三视角：
+//   ①使用者（壳层 reporter 视角）——setInFlightListener 注册后，core 状态迁移点
+//     （子进程注册/移除、idle timer arm）推来最新绝对计数快照；getInFlightSnapshot
+//     随时可拉（初始上报数据源）。
+//   ②构建者——计数 = 双谓词过滤（hasLiveProcessHandle && !hasIdleTimer，与
+//     notify-host hasRunningBackground 同源）：活句柄且无 armed idle timer 才算在途，
+//     Path A 保活（timer armed）不算——D5 防推迟恒真的核心裁决。
+//   ③观察者——EnginePort 可选成员向后兼容：pi 引擎不实现（undefined = 无在途），
+//     zcode 引擎实现（快照面在场）；出口监听者抛错不反噬 core。
+
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "node:events";
+import type { ChildProcess } from "node:child_process";
+
+import {
+  armIdleTimer,
+  disarmIdleTimer,
+  _resetLifecycleState,
+} from "../../lifecycle-manager.ts";
+import {
+  getInFlightSnapshot,
+  notifyInFlightChanged,
+  setInFlightListener,
+  type InFlightSnapshot,
+} from "../inflight-snapshot.ts";
+import type { EnginePort } from "../port.ts";
+// W3 合并改写：inproc 引擎已删——句柄记账走 host/spawned-children 镜像（register +
+// reset 测试面）；「引擎无 inFlightSnapshot 可选成员」断言改桩（EnginePort 缺席形态）。
+import {
+  killRecordChildWithEscalation,
+  registerSpawnedChildForRecord,
+  _resetCoreSpawnedChildrenMirrorForTest,
+} from "../host/spawned-children.ts";
+import { createHostBridge } from "../host/host-bridge.ts";
+
+/** 最小 fake 子进程（EventEmitter + killed/pid 字段——hasLiveProcessHandle 消费面）。 */
+function makeFakeChild(): ChildProcess & EventEmitter {
+  const child = new EventEmitter() as ChildProcess & EventEmitter;
+  (child as { pid?: number }).pid = 4242;
+  (child as { killed: boolean }).killed = false;
+  return child;
+}
+
+beforeEach(() => {
+  _resetLifecycleState();
+  setInFlightListener(null);
+});
+
+afterEach(() => {
+  // 清理本测试注册的句柄镜像（W3 后记账在 host/spawned-children，reset 即清；close 事件
+  // 摘除路径已由「close 摘除自动触发通知」用例覆盖），防跨用例泄漏。
+  _resetCoreSpawnedChildrenMirrorForTest();
+  _resetLifecycleState();
+  setInFlightListener(null);
+});
+
+describe("getInFlightSnapshot：双谓词绝对计数（D5 求值位置 = 状态所在进程）", () => {
+  it("空态 → 0（无任何 subagent 的 session 初始上报数据源）", () => {
+    expect(getInFlightSnapshot()).toEqual({ inFlight: 0 });
+  });
+
+  it("注册活句柄 → 1；arm idle timer（Path A 保活）→ 0；disarm → 1", () => {
+    const id = "sa-inflight-arm";
+    registerSpawnedChildForRecord(id, makeFakeChild());
+    expect(getInFlightSnapshot().inFlight).toBe(1);
+
+    armIdleTimer(id, () => undefined, 60_000);
+    expect(getInFlightSnapshot().inFlight).toBe(0);
+
+    disarmIdleTimer(id);
+    expect(getInFlightSnapshot().inFlight).toBe(1);
+  });
+
+  it("killed 句柄不算活（hasLiveProcessHandle 的 !killed 子句）", () => {
+    const id = "sa-inflight-killed";
+    const child = makeFakeChild();
+    registerSpawnedChildForRecord(id, child);
+    // W3 镜像形态：killed 判据由镜像置死位承载（注册后改 child 引用字段不进镜像——
+    // 生产置死路径 = killRecordChildWithEscalation 杀链记账面 / 引擎反向通道）。
+    killRecordChildWithEscalation(id, "test");
+    expect(getInFlightSnapshot().inFlight).toBe(0);
+  });
+
+  it("多 record 混合形态：在途/保活/垂死并存时按谓词逐一过滤", () => {
+    const running = makeFakeChild();
+    const keepAlive = makeFakeChild();
+    const dying = makeFakeChild();
+    (dying as { killed: boolean }).killed = true;
+    registerSpawnedChildForRecord("sa-inflight-run", running);
+    registerSpawnedChildForRecord("sa-inflight-keep", keepAlive);
+    registerSpawnedChildForRecord("sa-inflight-dying", dying);
+    armIdleTimer("sa-inflight-keep", () => undefined, 60_000);
+    expect(getInFlightSnapshot().inFlight).toBe(1);
+  });
+});
+
+describe("notifyInFlightChanged：迁移点 → 壳层监听者（同步 fire-and-forget）", () => {
+  it("监听者收到最新快照（迁移时刻求值，非注册时刻）", () => {
+    const seen: InFlightSnapshot[] = [];
+    setInFlightListener((s) => seen.push({ ...s }));
+
+    notifyInFlightChanged();
+    expect(seen).toEqual([{ inFlight: 0 }]);
+
+    registerSpawnedChildForRecord("sa-inflight-notify", makeFakeChild());
+    notifyInFlightChanged();
+    expect(seen[seen.length - 1]).toEqual({ inFlight: 1 });
+  });
+
+  it("监听者抛错不反噬 core（壳层故障不打断生命周期主链）", () => {
+    setInFlightListener(() => {
+      throw new Error("shell reporter bug");
+    });
+    expect(() => notifyInFlightChanged()).not.toThrow();
+  });
+
+  it("无监听者时 no-op；注册覆盖语义（后注册者收到，先注册者不再收）", () => {
+    expect(() => notifyInFlightChanged()).not.toThrow();
+
+    const first: InFlightSnapshot[] = [];
+    const second: InFlightSnapshot[] = [];
+    setInFlightListener((s) => first.push(s));
+    setInFlightListener((s) => second.push(s));
+    notifyInFlightChanged();
+    expect(first).toEqual([]);
+    expect(second).toEqual([{ inFlight: 0 }]);
+  });
+
+  it("host-bridge armIdleTimer / disarmIdleTimer 委托点自动触发通知（迁移点接线证据）", () => {
+    // W3 镜像形态：register 本身不再通知（子进程终止经引擎反向通道），core 侧唯一挂
+    // notifyInFlightChanged 的委托面 = host-bridge 的 arm/disarm（u7a 迁移点新宿主）。
+    const seen: InFlightSnapshot[] = [];
+    setInFlightListener((s) => seen.push(s));
+    registerSpawnedChildForRecord("sa-inflight-auto", makeFakeChild());
+
+    const bridge = createHostBridge({
+      service: {} as Parameters<typeof createHostBridge>[0]["service"],
+      onIdleTimeout: () => undefined,
+    });
+    bridge.armIdleTimer("sa-inflight-auto", 60_000);
+    expect(seen.at(-1)).toEqual({ inFlight: 0 });
+
+    bridge.disarmIdleTimer("sa-inflight-auto");
+    expect(seen.at(-1)).toEqual({ inFlight: 1 });
+  });
+});
+
+describe("EnginePort.inFlightSnapshot? 可选成员缺省语义（D5：pi 不实现，zcode 实现）", () => {
+  it("未实现该成员的引擎桩 → undefined（= 无引擎侧在途面，pi 形态由 extension 聚合上报覆盖）", () => {
+    // 经 EnginePort 接口面访问（可选成员缺席的正当形态）；裸桩无此声明（W3 后 inproc
+    // pi 引擎已删，缺席形态以桩承载——zcode 真实现的断言移 zcode-subagent-cli 测试），
+    // 消费方必须走 port 类型——本身就是「缺席正当」契约的一部分。
+    const pi: EnginePort = { capabilities: () => ({ id: "pi-stub" }) } as unknown as EnginePort;
+    expect(pi.inFlightSnapshot).toBeUndefined();
+  });
+
+  it("实现该成员的引擎桩 → 同步快照；未初始化恒 0（空闲常驻≠在途——真实现断言在 zcode-subagent-cli 的 zcode-engine-inflight.test）", () => {
+    const engine: EnginePort = {
+      capabilities: () => ({ id: "zcode-stub" }),
+      inFlightSnapshot: () => ({ inFlight: 0 }),
+    } as unknown as EnginePort;
+    expect(typeof engine.inFlightSnapshot).toBe("function");
+    expect(engine.inFlightSnapshot?.()).toEqual({ inFlight: 0 });
+  });
+
+  it("未实现该成员的引擎对象仍满足 EnginePort（向后兼容，可选成员不强制）", () => {
+    // 结构化证据：EnginePort 的既有可选成员扩展先例（listModels/validateModel/dispose）
+    // 同款——缺席成员不破坏实现关系（裸桩承载缺席形态）。W3 后 inproc pi 引擎已删，
+    // id 不再由引擎身份推导断言（桩无 id 字面量），能力面 id 经 capabilities() 取。
+    const pi: EnginePort = { capabilities: () => ({ id: "pi-stub" }) } as unknown as EnginePort;
+    // EngineCapabilities 契约面无 id 成员（contract-types.ts）——运行期桩携带的 id 经
+    // 窄化读取断言（HEAD 既有类型红此处修复：pi.capabilities().id 直取 TS2339）。
+    expect((pi.capabilities() as unknown as { id: string }).id).toBe("pi-stub");
+    expect(typeof pi.capabilities).toBe("function");
+    expect(pi.inFlightSnapshot).toBeUndefined();
+  });
+});

package/src/execution/engine/client/engine-client.ts

@@ -43,7 +43,7 @@ import {
   type RequestFrame,
 } from "@zhushanwen/subagent-engine-sdk";
 
-import { SpawnedChildrenMirror } from "./mirror.ts";
+import { SpawnedChildrenMirror, type MirrorChangeEvent } from "./mirror.ts";
 import {
   removePidfile,
   registerEnginePidfile,
@@ -56,9 +56,35 @@ import {
   type EngineClientOptions,
 } from "./client-options.ts";
 import { killProcessTree, waitForChildExit } from "./reaper.ts";
+// [u7a 生产补挂] 反向通道镜像 → core 侧镜像桥接：in-flight 计数与生命周期谓词读 core
+// 全局镜像（recordId 键），而引擎侧子进程上报只落 EngineClient 镜像——本桥接实现
+// spawned-children.ts 头注「数据源①：反向通道上报落本镜像」的既登记契约（W3 协议化
+// 后 ctx.onChildSpawned 不被调用，该数据面悬空致计数恒 0），见 crash-forensics §7 v7。
+import { coreSpawnedChildrenMirror } from "../host/spawned-children.ts";
+import { notifyInFlightChanged } from "../inflight-snapshot.ts";
 
 const logger = getLogger("subagents");
 
+/**
+ * 单条镜像事件 → core 镜像投影 + 在途推送（u7a 数据面桥接）：置死/退出 → markKilled，
+ * running → register（同 recordId 重 spawn 覆盖，与引擎侧 Map 同语义）。投影后必推送
+ * ——镜像事件本身就是在途迁移点（子进程注册/移除），首轮无任何 arm/disarm 推送，
+ * 不在此推则首轮在途窗口对 D5 不可见；notify 同步 fire-and-forget，异常不外溢。
+ * killedAll 空表单发（无 pid）与迟到事件（条目已清）为 no-op。
+ */
+function bridgeMirrorEventToCoreMirror(event: MirrorChangeEvent, mirror: SpawnedChildrenMirror): void {
+  if (event.recordId === undefined || event.pid === undefined) return;
+  const entry = mirror.getEntry(event.pid);
+  if (entry === undefined) return;
+  const core = coreSpawnedChildrenMirror();
+  if (entry.killed) {
+    core.markKilled(event.recordId);
+  } else {
+    core.register(event.recordId, { pid: entry.pid, killed: false });
+  }
+  notifyInFlightChanged();
+}
+
 /** dispose 帧等待上界（设计 §3.6：dispose 上界 3s，超时即杀）。 */
 const DISPOSE_GRACE_MS = 3_000;
 /** SIGKILL 后收尸等待上限（kill-chain 同型有界兜底，reaper.waitForChildExit 消费）。 */
@@ -171,6 +197,9 @@ export class EngineClient {
     };
     this.mirror.onChange((event) => {
       opts.onMirrorChanged?.(event);
+      // [u7a 生产补挂] 反向通道镜像事件同步投影进 core 侧镜像 + 推送在途计数
+      //（数据面桥接，见 bridgeMirrorEventToCoreMirror 与文件头 u7a 注释）。
+      bridgeMirrorEventToCoreMirror(event, this.mirror);
     });
   }
 

package/src/execution/engine/host/host-bridge.ts

@@ -16,6 +16,11 @@
 // chat-session.cancel 等价承接，偏差登记见 chat-domain impl-plan §5。
 
 import { armIdleTimer, disarmIdleTimer } from "../../lifecycle-manager.ts";
+// u7a D5 在途记账迁移点（crash-forensics §3.3 D5）：idle timer arm/disarm 是「保活 ↔
+// 正在执行」翻转的全部迁移点（agent_settled arm / 新 turn disarm / 热路径 re-arm 均经
+// 本委托），迁移后推最新绝对计数给壳层监听者（同步 fire-and-forget，不进投递 await 面；
+// 环规避同 inflight-snapshot.ts 头注释——挂桥层而非 lifecycle-manager）。
+import { notifyInFlightChanged } from "../inflight-snapshot.ts";
 import type { AgentResult as WorkflowAgentResult } from "../../../orchestration/models/types.ts";
 import type { StatusFilter } from "../../record-store.ts";
 import type { SubagentStream } from "../../stream-sink.ts";
@@ -142,9 +147,11 @@ export function createHostBridge(deps: HostBridgeDeps): HostBridge {
     reportRecordTransition: (record) => service.reportRecordTransition?.(record),
     armIdleTimer: (id, ms) => {
       armIdleTimer(id, () => deps.onIdleTimeout(id), ms);
+      notifyInFlightChanged();
     },
     disarmIdleTimer: (id) => {
       disarmIdleTimer(id);
+      notifyInFlightChanged();
     },
   };
 }

package/src/execution/engine/host/spawned-children.ts

@@ -71,7 +71,7 @@ class CoreSpawnedChildrenMirror {
   }
 
   /** 快照（诊断/测试）。 */
-  snapshot(): SpawnedChildMirrorEntry[] {
+  snapshot(): Array<SpawnedChildMirrorEntry & { recordId: string }> {
     return [...this.entries.entries()].map(([recordId, entry]) => ({ recordId, ...entry }));
   }
 

package/src/execution/engine/inflight-snapshot.ts

@@ -0,0 +1,92 @@
+// src/execution/engine/inflight-snapshot.ts
+//
+// core→壳在途事件出口（u7a，设计权威源：docs/design/crash-forensics-and-watchdog.md
+// §3.3 D5「在途判定谓词 + 求值位置」）。
+//
+// 在途状态（spawnedChildren Map / idleTimers Map）真实存在于本包（随 subagent-workflow
+// extension 加载进 pi 进程），runtime 无法直查——D5 裁决为 extension 聚合上报：壳层
+// （extensions/universal/subagent-workflow 的 host/inflight-reporter）经 select 通道
+// 把绝对计数推给 runtime。本模块是这条通道的 core 侧出口：
+//   - 求值位置 = 状态所在的 pi 进程（本模块 getInFlightSnapshot——谓词与
+//     notify-host.ts hasRunningBackground 的双谓词过滤同源：hasLiveProcessHandle &&
+//     !hasIdleTimer，只把「正在执行」计为在途，Path A 保活（idle timer armed）不计）；
+//   - 事件产生点 = 引擎域内的状态迁移点（session-runner 子进程注册/移除、idle timer
+//     arm/disarm），迁移后调 notifyInFlightChanged() 把最新快照推给壳层监听者；
+//   - core 闭包红线：本模块零 pi SDK import（只 import 本包 lifecycle 记账面），
+//     壳层经包根 barrel 消费 setInFlightListener / getInFlightSnapshot（exports 面
+//     收窄后壳侧生产消费必须走 barrel，无深路径豁免）。
+//
+// 回调注入形态（RunContext 回调先例）：监听者由壳层注册，core 同步调用、绝不 await
+// 返回值——满足 D5 接线约束①「上报不阻塞生命周期主链、不 await 进 agent_settled
+// handler 链」（该链有时序保护约束 armIdleTimer 先于 notify）。
+
+import { hasIdleTimer } from "../lifecycle-manager.ts";
+import { hasLiveProcessHandle } from "../lifecycle-predicates.ts";
+// 环声明：session-runner（迁移点）import 本模块的 notifyInFlightChanged，本模块经
+// lifecycle-predicates → session-runner.getChildByRecord 读句柄记账 + 直接取
+// spawnedChildren 键集——双向仅函数体内取值（ESM 活绑定，调用期解析），模块求值序
+// 无依赖，环安全；esbuild bundle（builtin 打包）同规则成立。
+// W3 合并改写：inproc 引擎已删，句柄记账唯一源 = engine/host/spawned-children 镜像
+//（coreSpawnedChildrenMirror().snapshot() 返回 [{recordId, ...}]，键集等价旧 Map.keys()）。
+import { coreSpawnedChildrenMirror } from "./host/spawned-children.ts";
+
+/** 在途快照（与 EnginePort.inFlightSnapshot? 返回形状一致——runtime 侧统一消费形状）。 */
+export interface InFlightSnapshot {
+  /** 当前非 idle 句柄数（绝对计数，非增量）。 */
+  inFlight: number;
+}
+
+/** 壳层注册的监听回调（同步、fire-and-forget；core 不 await 不重试）。 */
+export type InFlightListener = (snapshot: InFlightSnapshot) => void;
+
+/**
+ * 进程级单监听者（非 per-session 状态——在途计数本身是 pi 进程级模块状态
+ * （spawnedChildren/idleTimers 均模块级 Map），出口与之同域；壳层 reporter 持有
+ * 当前 session 上下文负责归属，与本出口无关）。后注册覆盖先注册（jiti 模块重载
+ * /多 factory 实例场景幂等），null 注销。
+ */
+let listener: InFlightListener | null = null;
+
+/** 壳层注册监听（extension factory 装配点调用；传 null 注销）。 */
+export function setInFlightListener(next: InFlightListener | null): void {
+  listener = next;
+}
+
+/**
+ * 当前在途快照（纯读，无副作用）：遍历活句柄记账（spawnedChildren 的 recordId 键集），
+ * 按双谓词过滤——活句柄（child 存在且未 killed）且无 armed idle timer。
+ *
+ * SSOT 复用：谓词取 lifecycle-predicates/lifecycle-manager 既有导出，与 notify-host
+ * hasRunningBackground 完全同源，不复制判定逻辑。活句柄记账里天然覆盖 pi 引擎进程内
+ * 与 relay 形态 child 两种宿主（relay spawn 经同一 runSpawn/spawnedChildren 记账——
+ * D5「extension 是两形态派生的共同属主」）。
+ */
+export function getInFlightSnapshot(): InFlightSnapshot {
+  return { inFlight: countInFlight() };
+}
+
+/**
+ * 状态迁移点调用：把最新快照同步推给监听者。约束（D5 接线①）：
+ *   - 同步 void 语义——调用方（含 agent_settled handler 链内的 armIdleTimer 迁移点）
+ *     不 await 本函数的任何下游（监听者内部自行 fire-and-forget）；
+ *   - 监听者异常不反噬 core（壳层 bug 不得打断生命周期主链），catch 后照常返回。
+ */
+export function notifyInFlightChanged(): void {
+  if (listener === null) return;
+  try {
+    listener(getInFlightSnapshot());
+  // eslint-disable-next-line taste/no-silent-catch -- 上报出口故障刻意静默（D5 约束①）：壳层 bug 不得打断生命周期主链；绝对计数语义下后续事件自愈，丢失单帧无累积误差，记日志徒增 core logger 噪音面
+  } catch {
+    // 同上：静默是接受的。
+  }
+}
+
+/** 双谓词过滤的绝对计数（getInFlightSnapshot 与 notifyInFlightChanged 共用）。 */
+function countInFlight(): number {
+  let count = 0;
+  for (const entry of coreSpawnedChildrenMirror().snapshot()) {
+    const recordId = entry.recordId;
+    if (hasLiveProcessHandle(recordId) && !hasIdleTimer(recordId)) count++;
+  }
+  return count;
+}

package/src/execution/engine/port.ts

@@ -12,6 +12,9 @@
 //     与 onPoolResolved 分立两个时点）。
 //   - [u-h2 已实施 2026-09-05] EnginePort.validateModel?()——派发同步期 model 校验面。
 //     权威源：docs/design/timeout-audit-hygiene-batch.md §3.2 D2-2。
+//   - [u7a 已实施 2026-09-10] EnginePort.inFlightSnapshot?()——引擎在途只读快照面
+//     （滚动重启推迟谓词输入）。权威源：
+//     docs/design/crash-forensics-and-watchdog.md §3.3 D5。
 //
 // 四个能力面（D1）：
 //   run        —— 主语义：一次性 fire-to-completion 任务执行；
@@ -254,4 +257,19 @@ export interface EnginePort {
    * Promise 前完成；grace→SIGKILL 升级序列属异步面（promise 段）。
    */
   dispose?(): Promise<void>;
+
+  /**
+   * [u7a D5] 可选面：引擎在途任务只读快照（滚动重启推迟谓词的引擎侧输入——
+   * 权威源：docs/design/crash-forensics-and-watchdog.md §3.3 D5「推迟判定源 =
+   * relay ∪ 引擎池在途 ∪ pi 侧 extension 聚合上报」）。同步纯读、无副作用。
+   *
+   * 返回 null = 引擎不提供快照；成员缺席（undefined，pi 引擎不实现）= 无引擎侧
+   * 在途面——pi 形态的在途由 subagent-workflow extension 聚合上报覆盖（EnginePort
+   * 之外的第 4 通道，两通道互不替代）。可选成员保持向后兼容（port.ts 既有扩展
+   * 先例：listModels / validateModel / dispose 全为可选成员）。
+   *
+   * zcode 实现语义（显式裁决）：在途 = activeSessions 非空——poolKey 'shared' 的
+   * app-server 空闲常驻进程恒活，**禁止按进程存在判定**（会恒真、推迟常态化）。
+   */
+  inFlightSnapshot?(): { inFlight: number } | null;
 }

package/src/execution/path-encoding.ts

@@ -19,6 +19,12 @@ export function encodeCwd(cwd: string): string {
 /**
  * 获取 subagent session 持久化目录路径。
  *
+ * C-ext-21（跨包隐式契约）：本函数产出的 `subagents/<enc>/sessions` 路径形态被
+ * extensions/universal/rename-session/src/llm.ts 的 isSubagentSession 嗅探
+ * （路径含 `<sep>subagents<sep>` 段 → 判为 subagent 会话并跳过重命名）——改本布局
+ * （移动/改名 subagents 段）必须同步该嗅探逻辑，反之亦然；约束登记见
+ * docs/constraints.json C-ext-21，设计依据 rename-session-three-modes.md §3.3 D7。
+ *
  * D-004: 用主 cwd 编码——保证同一主 cwd 下所有 subagent 的 session 文件
  * 存放在同一目录，便于 session-file-gc 统一清理。
  * [MF-3] worktree 模式下调用方必须传树根 cwd（ROOT mainCwd，经 PI_SUBAGENT_ROOT_CWD

package/src/execution/subagent-service.ts

@@ -78,6 +78,13 @@ import {
   killRecordChildWithEscalation,
   registerSpawnedChildForRecord,
 } from "./engine/host/spawned-children.ts";
+// [u7a 生产补挂] D5 在途推送的迁移点出口：本模块的裸 arm/disarm 与镜像置死是
+// 「保活 ↔ 正在执行」的全部生产翻转点，翻转后同步推最新绝对计数给壳层监听者
+// （extension reporter → runtime 镜像）。挂点在调用方而非 lifecycle-manager——环规避
+// 同 host-bridge.ts 头注（inflight-snapshot 反向读 lifecycle-manager 记账，lifecycle
+// 层不得依赖 engine 域出口）；createHostBridge 无生产装配点，本文件的直调点才是
+// 生产迁移点（dev-0.9.17 合并后 u7a 推送链悬空的根因，见 crash-forensics impl-plan §7 v6）。
+import { notifyInFlightChanged } from "./engine/inflight-snapshot.ts";
 // [u-t2a T2②/T2③ + W4 协议事件面] settled watchdog：chatMode 轮 settled 等待两段守护。
 // W3 起事件接线 = 协议事件流（arm 点 = 轮开始；refresh 源 = streamDelta/轮次生命周期
 // 帧；W4 三入口与旧原语逐一同构，见 settled-watchdog.ts 尾段）。
@@ -797,6 +804,9 @@ export class SubagentService {
       this.notifyHost.emitPendingUnregister(record.id, "closed");
       count++;
     }
+    // [u7a 生产补挂] 批量 dispose 收敛点推一次终态快照（绝对计数语义下循环内逐条推
+    // 与收敛后单推等价，单推省 N-1 次同步派发）。此刻镜像已由上方 kill/disarm 全量清零。
+    notifyInFlightChanged();
     return count;
   }
 
@@ -1355,6 +1365,8 @@ export class SubagentService {
     // 新 turn 开跑先 disarm idle timer（防 turn 期间误杀活进程——V2 决策 4，
     // 原 PiEngine.deliverPrompt 入口语义，编排侧承接）。
     disarmIdleTimer(record.id);
+    // [u7a 生产补挂] disarm = 该 record 翻入「正在执行」，迁移后推最新在途计数（D5）。
+    notifyInFlightChanged();
     const engine = this.resolveChatEnginePort();
     // recordId 键路由兜底注册（首轮已注册时幂等跳过——kickOffChatRound 注册面）：
     // 续聊轮 delta/生命周期帧的分发目标。stream 缺省（首轮流已 dispose——widget 清除后
@@ -1557,6 +1569,9 @@ export class SubagentService {
         `terminating (LC-1 wedge recovery)`,
     );
     killRecordChildWithEscalation(record.id, "settled watchdog (hot path)");
+    // [u7a 生产补挂] 镜像置死 = 在途 −1 的迁移点（本路径无相邻 disarm——轮中守护
+    // 击杀，timer 早已 disarm），置死后推最新在途计数（D5）。
+    notifyInFlightChanged();
     // [W3] 子进程在引擎进程内——终止经协议 interact cancel（SIGTERM → 引擎侧
     // settle 等待 → 杀链升级）；镜像置死位由上方 killRecordChildWithEscalation 记账。
     this.terminateChatSession(record, "cancel", "settled watchdog (hot path)");
@@ -1717,6 +1732,8 @@ export class SubagentService {
     // [W3] 实际终止在引擎进程内（协议 interact close force → 引擎侧杀链）；
     // killRecordChildWithEscalation 只做镜像置死记账。
     disarmIdleTimer(record.id);
+    // [u7a 生产补挂] 终态化 disarm = 该 record 翻出「正在执行」，迁移后推最新在途计数。
+    notifyInFlightChanged();
     disarmSettledWatchdog(record.id);
     disarmRoundFromProtocol(record.id);
     killRecordChildWithEscalation(record.id, "closeChatIdle");
@@ -1779,6 +1796,8 @@ export class SubagentService {
     // settled 等待窗口同步终结（disarm 幂等）。[W3] 实际终止经协议 interact close
     // force（引擎进程内的子进程），镜像置死位由 killRecordChildWithEscalation 记账。
     disarmIdleTimer(record.id);
+    // [u7a 生产补挂] 终态化 disarm = 该 record 翻出「正在执行」，迁移后推最新在途计数。
+    notifyInFlightChanged();
     disarmSettledWatchdog(record.id);
     disarmRoundFromProtocol(record.id);
     killRecordChildWithEscalation(record.id, "closeAfterRoundSettled");
@@ -2800,6 +2819,10 @@ export class SubagentService {
         bestEffort(fallbackErr, "armIdleTimer fallback (chat idle phase)", "error");
       }
     }
+    // [u7a 生产补挂] arm = 该 record 翻入「保活」（Path A，不计在途），迁移后推最新
+    // 在途计数（D5）。置于降级链之后：配置值/DEFAULT 两分支任一成功或双失败（状态
+    // 未变）都统一推终态快照——绝对计数语义下重复推幂等无害。
+    notifyInFlightChanged();
   }
 
   /** [W3] idle 帧锚点回填（冷续锚点 = 引擎侧会话滚动/compaction 后的最新定位）。 */
@@ -2994,6 +3017,8 @@ export class SubagentService {
     // cancel 分级另行承载，两路幂等）。
     killRecordChildWithEscalation(record.id, "cancelBackground");
     disarmIdleTimer(record.id);
+    // [u7a 生产补挂] cancel 的 kill+disarm = 在途/保活双态翻出，迁移后推最新在途计数。
+    notifyInFlightChanged();
     disarmSettledWatchdog(record.id);
     disarmRoundFromProtocol(record.id);
     this.unregisterChatRoundRoute(record.id);

package/src/execution/worktree-registry.ts

@@ -38,10 +38,12 @@ export const SPAWN_GRACE_MS = 60_000;
 const JSON_INDENT = 2;
 
 /**
- * 锁参数：逐项对齐 extensions/shared/file-lock/src/file-lock.ts 的 withFileLock
- * 包装默认值（stale 30s / retries 10）。两侧参数漂移会破坏「同一把
- * <worktrees.json>.lock」的跨进程互斥语义（协议登记 data-source-registry.md §6），
- * 与旧包装共存/替换期间尤其如此。
+ * 锁参数：对齐三方同一磁盘协议的既有默认值——runtime 侧
+ * packages/runtime/src/utils/file-lock.ts 的 withFileLockAsync、pi auth-storage
+ * 范本、本文件 proper-lockfile 调用（retry 库参数：stale 30s / retries 10 /
+ * factor 2 / 100ms~10s randomize）。互斥由 lockfile 路径（<worktrees.json>.lock）
+ * + mkdir 原子协议保证；默认值对齐锚定的是各写方夺取时机（stale）与失败速度
+ * （重试参数）行为一致（协议登记 data-source-registry.md §6）。
  */
 const LOCK_STALE_MS = 30_000;
 const LOCK_RETRIES = 10;
@@ -184,9 +186,11 @@ export class WorktreeRegistry {
 
   /**
    * proper-lockfile 直用的跨进程锁（取代已删除的共享 file-lock 包装，抽包去依赖）。
-   * 锁协议逐项对齐 extensions/shared/file-lock/src/file-lock.ts 的 withFileLock：
-   *   - lockfile 路径 = <目标文件>.lock（proper-lockfile 默认，与包装/runtime 侧
-   *     同一路径才互斥）
+   * 锁协议对齐现存三方同协议实现——runtime 侧 packages/runtime/src/utils/file-lock.ts
+   * 的 withFileLockAsync（范本 pi FileAuthStorageBackend，参数对齐 proper-lockfile
+   * 内部 retry 库）与 extension 侧 @zhushanwen/pi-file-lock：
+   *   - lockfile 路径 = <目标文件>.lock（proper-lockfile 默认，与 runtime 侧/
+   *     extension 侧同一路径才互斥）
    *   - realpath:false —— 目标文件不存在也可锁（realpath 默认 true 时 ENOENT）
    *   - stale 30s：持锁进程崩溃后锁可被夺取
    *   - async retries 指数退避：10 次 / factor 2 / 100ms~10s / randomize，耗尽抛

package/src/index.ts

@@ -24,7 +24,7 @@
 // 0.4.0 = 首个公开发布的收敛收口面（0.3.0 为 2026-08-30 裁决的跳号占位，永不单独
 // 发布；+ minor changeset 收口面落本号）；与 package.json version 的一致性由
 // src/__tests__/smoke.test.ts 动态守护，改版本须两处同步。
-export const CORE_PACKAGE_VERSION = "0.7.0";
+export const CORE_PACKAGE_VERSION = "0.8.0";
 
 // ── 宿主端口接线面（core/）────────────────────────────────────
 // HostServices：dataRoot / log / discoveryRoots 端口 + configureCore 注入；
@@ -123,6 +123,16 @@ export {
   type D8CompatZcodeEngineDeps,
 } from "./execution/engine/d8-compat.ts";
 
+// 在途事件出口（u7a，D5）：壳层（subagent-workflow host/inflight-reporter）注册
+// 监听 + 求值绝对计数快照——core→壳回调出口的 barrel 消费面（exports 面收窄后
+// 壳侧生产消费必须经 barrel，无深路径豁免）。
+export {
+  setInFlightListener,
+  getInFlightSnapshot,
+  type InFlightSnapshot,
+  type InFlightListener,
+} from "./execution/engine/inflight-snapshot.ts";
+// W3 后内核宿主 = engine/host（host-bridge arm/disarm 委托点为在途迁移点），模块本体不经 engines/pi。
 // maxTurnsToWatchdogMs 为 maxTurns→watchdog 毫秒换算（U3/U4 / D7，floor 语义
 // 文档化——两宿主预算一致性 S2 的函数级锚点；[W3] 定义收敛在 pi-host-binding，
 // 原 inproc session-runner（已删） 定义随删件消亡）；killRecordChildWithEscalation 为