@zhushanwen/subagent-core 0.7.1 → 0.9.0

package/src/execution/engine/common/journal-wiring.ts

@@ -1,8 +1,9 @@
 // src/execution/engine/common/journal-wiring.ts
 //
-// [D3-③ journal 接线合一] host 侧 event journal 接线的共享 helper（唯一实现，两调用
-// 点——SubagentService.runEngineTask（chat 域）与 SubprocessAgentRunner.run（workflow
-// 域））。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-③（writer +
+// [D3-③ journal 接线合一] host 侧 event journal 接线的共享 helper（唯一实现，调用
+// 点全部在 SubagentService：workflow 域 runWorkflowEngineTask（wireEventJournal
+// taskId=record.id）+ chat 域 runEngineTask 与 tool 域 runAndFinalize 两处（同
+// record.id））。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-③（writer +
 // retarget + handle 回填两份提为 common 层共享 helper）+ 双轨清单 #6。
 //
 // 收敛前形态（两份同构接线）：
@@ -17,6 +18,7 @@
 // fsync 一次，§3.3.6 写入纪律；写失败已由 writer 内部 warn + failed 收口，close 不抛，
 // journal 是②级尽力而为数据源）。
 
+import { SHARED_POOL_KEY } from "@zhushanwen/subagent-engine-sdk";
 import type { AgentEvent } from "../../../shared/agent-event.ts";
 import { getEngineDataDir } from "./data-dir.ts";
 import { JournalWriter } from "./event-journal.ts";
@@ -26,16 +28,17 @@ import type { EngineHandle } from "../types.ts";
 /**
  * journal 初始占位池 key（= pi 的恒定池 key 'shared'）。pi 无隔离池
  * （PI_CODING_AGENT_DIR 全局一份，设计 §3.3.9），占位即终值；zcode 在 prepare 期
- * retarget 到实际池 key。值与 RunContext.poolKey 的初始占位同源——本常量是该值在
- * common 层的单一权威（原先 Service 用 'shared' 字面量、SAR 用 PI_POOL_KEY，等值异名）。
+ * retarget 到实际池 key。值与 RunContext.poolKey 的初始占位同源——值单源
+ * SDK SHARED_POOL_KEY（L3 收编：原先 Service 用 'shared' 字面量、SAR 用 PI_POOL_KEY，
+ * 等值异名；本名保留 journal 占位语义，值不再本地声明）。
  */
-export const JOURNAL_INITIAL_POOL_KEY = "shared";
+export const JOURNAL_INITIAL_POOL_KEY = SHARED_POOL_KEY;
 
 /** wireEventJournal 的参数。 */
 export interface JournalWiringOptions {
   /** 实际执行引擎 id（journal 路径分段 + line 元数据）。 */
   engineId: string;
-  /** 宿主侧任务标识（journal 文件名与池引用计数 key：chat 域 = record.id；workflow 域 = 'sa-' 前缀占位）。 */
+  /** 宿主侧任务标识（journal 文件名与池引用计数 key；三处调用点统一 = record.id）。 */
   taskId: string;
   /**
    * journal 落盘后的事件转发（workflow 域的 liveRecord 通道）。缺省不转发（chat 域
@@ -77,9 +80,15 @@ export function wireEventJournal(opts: JournalWiringOptions): JournalWiring {
   });
   return {
     // 先落盘再转发（原 onEvent 未传时也恒传包装版——下游 onEvent 通道是事件生成后的
-    // 纯转发，无行为分支，仅多一次入队）
+    // 纯转发，无行为分支，仅多一次入队）。
+    //
+    // activity 豁免 append：纯活性信号不进持久/重放面——双侧 reducer（SDK
+    // journal-replay / core execution-record）对其 no-op，豁免不破坏 live≡reload
+    // 重放等价性；seq 由 append 铸造、过滤在 append 前故无 seq 空洞；
+    // forwardEvents 照发（workflow liveRecord reducer no-op，chat/守护刷新面在
+    // observedEvent 上游不受影响）；取证面由 pi stdout/stderr tee 覆盖。
     onEvent: (event) => {
-      journal.append(event);
+      if (event.type !== "activity") journal.append(event);
       opts.forwardEvents?.(event);
     },
     onPoolResolved: (poolKey) => {

package/src/execution/engine/common/run-signals.ts

@@ -0,0 +1,83 @@
+// src/execution/engine/common/run-signals.ts
+//
+// [H2 W2 迁移步⑥] 运行期 signal 合流公共 helper——原定义在 subprocess-agent-runner.ts
+// （模块内直调），随 service 统一编排入口 executeWorkflowAgent 接管 workflow 派发
+// （设计 docs/design/subagent-workflow-record-unification.md §5 W2 八步迁移表）提为
+// engine/common 公共面：SAR 与 SubagentService 两调用点共用同一实现（行为逐字节
+// 等价搬移，函数体不改）。SAR 侧经 re-export 保持既有 import 路径（测试消费面零
+// 改动），W4 掏空 SAR.run 后本文件成为唯一权威落点。
+
+import { HOST_TIMEOUT_ABORT_REASON } from "./kill-chain.ts";
+
+/** 合并 signal 的句柄：signal 供 engine.run 消费，dispose 移除桥接 listener（finally 必达）。 */
+export interface MergedRunSignalHandle {
+  signal: AbortSignal;
+  /** 移除全部桥接 listener（幂等）。run 正常收敛（merged 不 abort）时是唯一清理通道。 */
+  dispose(): void;
+}
+
+/**
+ * D-A9 + [M3] 运行期 signal 合流：外部 signal（run 级 abort）+ per-call 墙钟 timeoutMs
+ * + [M3] no-progress watchdog abort —— 任一 abort 都让返回 signal abort。
+ *
+ * reason 语义保持 D-A9 原样：timeoutMs 到期 abort 带 HOST_TIMEOUT_ABORT_REASON 标记
+ *（引擎合成终态时判别「宿主超时」vs「外部 cancel」）；外部 signal 与 watchdog 的
+ * abort 不带标记（wireAbortSignal 只消费 abort 事实，不读 reason）。
+ *
+ * 无任何信号源（timeoutMs 缺省/<=0 且无 watchdog）时原样返回 external signal（零新对象，
+ * 既有行为逐点不变）。
+ *
+ * dispose 的必要性：merged signal 正常收敛（不 abort）时，桥接在外部 run 级 signal 上的
+ * listener 不会自行移除——同一 run 多次 agent 调用会累积 listener 直至
+ * MaxListenersExceededWarning，故由调用方 finally 调 dispose。
+ */
+export function mergeRunSignals(
+  signal: AbortSignal,
+  timeoutMs?: number,
+  noProgressSignal?: AbortSignal,
+): MergedRunSignalHandle {
+  const hasTimeout = timeoutMs !== undefined && timeoutMs > 0;
+  if (!hasTimeout && noProgressSignal === undefined) {
+    return { signal, dispose: () => {} };
+  }
+
+  const controller = new AbortController();
+  const bridges: Array<{ source: AbortSignal; handler: () => void }> = [];
+  let timer: NodeJS.Timeout | undefined;
+
+  const dispose = (): void => {
+    for (const bridge of bridges) bridge.source.removeEventListener("abort", bridge.handler);
+    bridges.length = 0;
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  // 先挂清理 listener：任一信号源已 abort 时 bridge 会同步 abort controller，若清理
+  // listener 尚未就位，timeout timer / 已挂 listener 将不会被回收（原实现的既有时序盲区）。
+  controller.signal.addEventListener(
+    "abort",
+    () => dispose(),
+    { once: true },
+  );
+
+  if (hasTimeout) {
+    timer = setTimeout(() => controller.abort(HOST_TIMEOUT_ABORT_REASON), timeoutMs);
+    timer.unref();
+  }
+
+  const bridge = (source: AbortSignal): void => {
+    // 已 abort（前序信号源抢先 / 外部 signal 传入时已中止）后不再挂新 listener：
+    // 否则该 listener 永远等不到 controller 的清理（已过 abort 时点）。
+    if (controller.signal.aborted) return;
+    const handler = (): void => controller.abort();
+    bridges.push({ source, handler });
+    if (source.aborted) handler();
+    else source.addEventListener("abort", handler, { once: true });
+  };
+  bridge(signal);
+  if (noProgressSignal !== undefined) bridge(noProgressSignal);
+
+  return { signal: controller.signal, dispose };
+}

package/src/execution/engine/d8-compat.ts

@@ -32,7 +32,7 @@ import { EngineClient } from "./client/engine-client.ts";
 import { RemoteEngine, type RemoteEngineManifestSnapshot } from "./client/remote-engine.ts";
 import {
   readRelayForwardEnv,
-} from "../relay-env.ts";
+} from "@zhushanwen/subagent-engine-sdk";
 import { getEngineDataDir } from "./common/data-dir.ts";
 import {
   CONSERVATIVE_CAPABILITIES,

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

@@ -1,6 +1,6 @@
-// HostBridge 契约 + core 实现 单测（W6，impl-plan §2.6 第 2 条 / 设计 §3.8 最小示例 9 方法）。
-// 覆盖：9 方法委托行为、getRecordForAction 异常 → null、cancel 的 void 包装、
-// takeChatRound 未提供 → null、armIdleTimer/disarmIdleTimer 对 lifecycle-manager 的
+// HostBridge 契约 + core 实现 单测（W6；[H1 U6] takeChatRound 交接面用例随 chat 域
+// 退役删除）。覆盖：方法委托行为、getRecordForAction 异常 → null、cancel 的 void 包装、
+// armIdleTimer/disarmIdleTimer 对 lifecycle-manager 的
 // 接线（含超时回调 onIdleTimeout 触发，fake timers）。
 
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
@@ -9,7 +9,6 @@ import {
   createHostBridge,
   type HostBridge,
   type HostBridgeServiceFace,
-  type HostChatRoundTicket,
 } from "../host-bridge.ts";
 import {
   _resetLifecycleState,
@@ -32,7 +31,6 @@ function makeService(): HostBridgeServiceFace & {
     closeSubagent: vi.fn(async () => {}),
     cancel: vi.fn(() => true),
     collectRecords: vi.fn((): SubagentRecord[] => [{ id: "r1" } as SubagentRecord]),
-    takeChatRound: vi.fn(() => undefined),
     reportRecordTransition: vi.fn(() => {}),
   };
   return {
@@ -42,7 +40,6 @@ function makeService(): HostBridgeServiceFace & {
     closeSubagent: spies.closeSubagent,
     cancel: spies.cancel,
     collectRecords: spies.collectRecords,
-    takeChatRound: spies.takeChatRound as HostBridgeServiceFace["takeChatRound"],
     reportRecordTransition: spies.reportRecordTransition,
   };
 }
@@ -96,18 +93,6 @@ describe("HostBridge（W6，设计 §3.8 最小示例 9 方法）", () => {
     expect(service.spies.cancel).toHaveBeenCalledWith("r1");
   });
 
-  it("takeChatRound：有票 → 透传；无票 / 服务面未提供 → null", () => {
-    expect(bridge.takeChatRound("t1")).toBeNull();
-    const ticket: HostChatRoundTicket = {
-      record: fakeRecord("r1"),
-      opts: {} as HostChatRoundTicket["opts"],
-      signal: undefined,
-      priority: 1,
-    };
-    (service.spies.takeChatRound as ReturnType<typeof vi.fn>).mockReturnValue(ticket);
-    expect(bridge.takeChatRound("t1")).toBe(ticket);
-  });
-
   it("reportRecordTransition 委托（record 整体上报，无 patch 形态——见契约头注释）", () => {
     const record = fakeRecord("r1");
     bridge.reportRecordTransition(record);

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

@@ -2,12 +2,12 @@
 //
 // HostBridge 契约 + core 侧实现（W6，impl-plan §2.6 / 设计 §3.8 D2 表 + 最小示例）。
 //
-// 归属裁定（设计 §3.8 D2 表逐条）：PiEngineService 的 9 成员中——executeAndAwait /
-// getRecordForAction / collectRecords / closeSubagent / cancel / ChatRoundTicket /
-// record 状态回写 / idle+activate lock 定时器——都是「宿主执行链 / 数据所有权在宿主」，
-// 归 HostBridge（core）；pi 包（W7）经 host/* 反向请求消费本面。spawnedChildren 归
-// 引擎进程（core 镜像见同目录 spawned-children.ts）；sendPromptCommand / EPIPE 兜底 /
-// 冷续轮 resume（stdin-writer）归 pi 包（W7 迁移物）。
+// 归属裁定（设计 §3.8 D2 表逐条）：executeAndAwait / getRecordForAction /
+// collectRecords / closeSubagent / cancel / record 状态回写 / idle+activate lock
+// 定时器——都是「宿主执行链 / 数据所有权在宿主」，归 HostBridge（core）；pi 包（W7）
+// 经 host/* 反向请求消费本面。spawnedChildren 归引擎进程（core 镜像见同目录
+// spawned-children.ts）；sendPromptCommand / EPIPE 兜底归 pi 包（W7 迁移物）。
+// [H1 U6] ChatRoundTicket 交接面与冷续轮 resume（stdin-writer）已随 chat 域退役。
 //
 // 本文件只依赖 core 公共类型（types.ts / record-store / stream-sink /
 // lifecycle-manager / orchestration 类型），不 import inproc pi 引擎目录 内部——它是 pi 包
@@ -16,39 +16,31 @@
 // 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";
 import type {
   AgentEvent,
-  AgentResult,
   ExecuteOptions,
   ExecutionRecord,
   SubagentRecord,
 } from "../../types.ts";
 
-/**
- * chat 域轮次交接包的 core 契约基座（设计 §3.8 D2「ChatRoundTicket → HostBridge」）。
- * pi 专有扩展（identity / SessionRunnerContext / SpawnResumeOpts resume）在
- * pi-engine.ChatRoundTicket extends 本接口（W7 随包迁移；过渡期 record/opts/signal/
- * priority/stream 五字段的宿主编排语义在此单一权威）。
- */
-export interface HostChatRoundTicket {
-  record: ExecutionRecord;
-  opts: ExecuteOptions;
-  signal: AbortSignal | undefined;
-  priority: number;
-  stream?: SubagentStream;
-}
-
 /**
  * HostBridge 的服务实现面（SubagentService 的结构子集，鸭子类型——与原 pi-engine 的
- * PiEngineService 同一形态的协议化泛化：chat 域轮次面泛型参数化，pi 绑定 =
- * HostBridgeServiceFace<ChatRoundTicket>，见 pi-host-binding.ts 的 re-export）。
- * 为什么用结构接口而非 import SubagentService 类型：防 Service 内部演进连锁影响
- * 契约面 + 测试可注入 fake（PiEngineService 的既有先例，语义照搬）。
+ * PiEngineService 同一形态的协议化泛化）。为什么用结构接口而非 import SubagentService
+ * 类型：防 Service 内部演进连锁影响契约面 + 测试可注入 fake（PiEngineService 的既有
+ * 先例，语义照搬）。
+ * [H1 U6] chat 域轮次交接可选面（HostChatRoundTicket / takeChatRound / runChatRound /
+ * resumeChatRound）已随 chat 域退役删除——续聊 = Continuation → 新 run + resume，
+ * 引擎经协议 converse，不再回调宿主编排面。
  */
-export interface HostBridgeServiceFace<TTicket extends HostChatRoundTicket = HostChatRoundTicket> {
+export interface HostBridgeServiceFace {
   executeAndAwait(
     opts: ExecuteOptions,
     signal?: AbortSignal,
@@ -59,23 +51,18 @@ export interface HostBridgeServiceFace<TTicket extends HostChatRoundTicket = Hos
   closeSubagent(record: ExecutionRecord, force: boolean): Promise<void>;
   cancel(id: string): boolean;
   collectRecords(limit: number, statusFilter?: StatusFilter): SubagentRecord[];
-  /** chat 域轮次交接（run 的 chat 分支入口）：按 taskId 取走预备包（一次性消费）。 */
-  takeChatRound?(taskId: string): TTicket | undefined;
-  /** 执行预备的 chat 轮次（编排归 Service：pool 槽 + runSpawn + 终态迁移）。 */
-  runChatRound?(ticket: TTicket): Promise<AgentResult>;
-  /** 冷路径续轮（interact message 分支的编排回调：守卫 + record 迁移 + kick-off）。 */
-  resumeChatRound?(record: ExecutionRecord, text: string): void;
   /** record 状态迁移上报（热路径投递后让 runtime 派生缓存失效 / GUI 回流）。 */
   reportRecordTransition?(record: ExecutionRecord): void;
 }
 
 /**
- * HostBridge 接口（设计 §3.8 最小示例，9 方法）。core 侧实现；pi 包经 host/* 反向
- * 请求消费。签名与最小示例的两处实现级偏差（均按现状语义落地）：
+ * HostBridge 接口（设计 §3.8 最小示例的协议化视图）。core 侧实现；pi 包经 host/*
+ * 反向请求消费。签名与最小示例的实现级偏差（均按现状语义落地）：
  *   - getRecordForAction 返回 ExecutionRecord | null（现状实现面的活 record 形态；
  *     不存在 / 不可达 → null，引擎侧 resolveRecord 的 try/catch 语义内聚到本面）；
  *   - reportRecordTransition 收 record 对象（现状状态回写以 record 为单位整体上报，
  *     无 patch 增量形态——造 patch 形态属凭空造词，W7 反向通道载荷再议）。
+ * [H1 U6] takeChatRound（chat 域轮次交接）已随 chat 域退役删除。
  */
 export interface HostBridge {
   executeAndAwait(
@@ -88,7 +75,6 @@ export interface HostBridge {
   collectRecords(limit: number, filter?: StatusFilter): SubagentRecord[];
   closeSubagent(record: ExecutionRecord, force: boolean): Promise<void>;
   cancel(id: string): Promise<void>;
-  takeChatRound(taskId: string): HostChatRoundTicket | null;
   reportRecordTransition(record: ExecutionRecord): void;
   armIdleTimer(id: string, ms: number): void;
   disarmIdleTimer(id: string): void;
@@ -106,10 +92,8 @@ export interface HostBridgeDeps {
   onIdleTimeout: (recordId: string) => void;
   // [F-3 删除登记] 曾有的 waitForRoundTerminal / escalateKill 可选注入（W3 D3 cancel
   // 终态等待面）已删：createHostBridge 全仓无生产调用点，且该面与生产 cancel 链结构
-  // 冲突（cancelBackground 同步 unregisterChatRoundRoute 后，waitForRoundTerminal 再
-  // race 轮终相位恒等满 3s 超时）。D3 core 侧收敛语义由引擎面等价承接 =
-  // chat-session.cancel（waiter 先于 kill 注册 + killChain 有界升级），偏差登记见
-  // chat-domain-v1x-liveness-governance.impl-plan.md §5。
+  // 冲突（waitForRoundTerminal race 轮终相位恒等满 3s 超时）。[H1 U6] 注释内旧符号
+  // （chat 轮路由注销 / chat-session.cancel）已随 chat 域退役消亡。
 }
 
 /** HostBridge core 实现（SubagentService 编排面的协议化视图）。 */
@@ -131,20 +115,21 @@ export function createHostBridge(deps: HostBridgeDeps): HostBridge {
      * cancel 语义 = 受理即返回（service.cancel 同步布尔 → 契约 void）。
      * [F-3 删除登记] 终态等待/杀链升级面已删（无生产装配点 + 与 cancelBackground 的
      * 路由注销冲突，见 HostBridgeDeps 尾注）；生产收敛语义由引擎面承接 =
-     * chat-session.cancel（waiter 先于 kill 注册 → 等 roundLifecycle 终态相位 →
+     * chat-session.cancel（waiter 先于 kill 注册 → 等轮次终态相位 →
      * CANCEL_SETTLE_GRACE_MS 未收敛走 killChain 有界升级）。resolve 语义归引擎侧
      * 判 notResumable（契约注释，W6 起如此）。
      */
     cancel: async (id) => {
       service.cancel(id);
     },
-    takeChatRound: (taskId) => service.takeChatRound?.(taskId) ?? null,
     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/pi-host-binding.ts

@@ -23,11 +23,12 @@
 // （pi-subagent-cli spawn-runner 的 spawn watchdog）保持同源常量，漂移由 conformance
 // chat golden（spawn-args 断言）在引擎包侧守护。
 
+import { SHARED_POOL_KEY } from "@zhushanwen/subagent-engine-sdk";
 import type { EnginePort } from "../port.ts";
 import { EngineNotFoundError, getEngine, hasEngine, listEngines } from "../registry.ts";
 
 /** pi 无隔离池（PI_CODING_AGENT_DIR 全局一份，协议化设计 §3.3.9），poolKey 恒 'shared'。 */
-export const PI_POOL_KEY = "shared";
+export const PI_POOL_KEY = SHARED_POOL_KEY;
 
 /** watchdog 换算下限（分钟）：与引擎包 spawn-runner 的 floor 同源（30min）。 */
 const WATCHDOG_FLOOR_MINUTES = 30;
@@ -46,9 +47,9 @@ export function maxTurnsToWatchdogMs(maxTurns: number): number {
 }
 
 /**
- * 宿主侧 pi EnginePort 解析（SAR / chat 域路由）：registry 的 'pi'（发现器装载的
- * cli descriptor → RemoteEngine）直接返回——chat 轮次与 run 域同路（协议 run(interact)
- * 发往 pi-subagent-cli 引擎进程）。
+ * 宿主侧 pi EnginePort 解析（SAR / 会话形态轮路由）：registry 的 'pi'（发现器装载的
+ * cli descriptor → RemoteEngine）直接返回——续聊轮与 run 域同路（协议 run 帧发往
+ * pi-subagent-cli 引擎进程）。
  * [U-2 一致性修复] pi **未注册**（引擎包未装/发现失败）时返回不可用 stub，不静默
  * 直构任何本地实例——保留设计 D4「全不可用 → 派发期 engine_not_found + 安装指引」
  * 错误契约（zcode 侧 d8-compat 同语义，两引擎对称）。
@@ -85,7 +86,6 @@ function piUnavailableEnginePort(): EnginePort {
     }),
     probe: () => fail(),
     run: () => fail(),
-    interact: () => fail(),
     read: () => fail(),
   };
 }

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,21 +12,20 @@
 //     与 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 任务执行；
-//   interact   —— 交互控制面（chatMode 的 message/close/cancel + idle，可选能力面，
-//                 capabilities.conversation 声明接通与否）；
+// 三个能力面（D1；[H1 U6] interact 面已随 chat 域退役删除——续聊统一为新 run + resume）：
+//   run        —— 主语义：一次性 fire-to-completion 任务执行（会话形态续聊轮同走 run，
+//                 resume 锚点经 RunContext.resume 携带）；
 //   read       —— session 历史读取（D6 三级降级链）；
 //   probe      —— 探针（D7：二进制存在/版本解析/干跑校验）。
 // capabilities() 同步无副作用——「调用前拒绝」（D11 处置三级）的判据。
 
 import type { ChildProcess } from "node:child_process";
 
-import type {
-  HostRoundLifecycleParams,
-  ResumeAnchor,
-} from "@zhushanwen/subagent-engine-sdk";
+import type { ResumeAnchor } from "@zhushanwen/subagent-engine-sdk";
 
 import type { AgentCallOpts } from "../../orchestration/models/types.ts";
 import type { ModelInfo } from "../model-resolver.ts";
@@ -37,8 +36,6 @@ import type {
   EngineCapabilities,
   EngineHandle,
   EngineHandleData,
-  InteractAction,
-  InteractResult,
   ProbeReport,
   SessionView,
 } from "./types.ts";
@@ -93,6 +90,25 @@ export interface RunContext {
    * pi 引擎另经 ExecuteOptions 投影进 record）。
    */
   engineFallback?: { from: string; reason: string };
+  /**
+   * [F6] 根 session id（SubagentService.sessionRootId 注入）——pi 引擎 relay 归属键
+   * SESSION_ID 的权威来源（经 wire ctx.sessionRootId → server 还原 → SpawnRunParams
+   * → buildChildEnv）。刻意走 per-run ctx 而非 EngineClient 的进程级 env：客户端按
+   * 引擎缓存为惰性单例，进程级 env 在 pi fork 换 sessionId 后会陈旧；per-run ctx 恒
+   * 新鲜，且与 RECORD_ID 已有的 per-run 形态一致。additive：undefined/null/空串不
+   * 上 wire，zcode 等引擎忽略。
+   */
+  sessionRootId?: string;
+  /**
+   * [Option C 协议化] 权威 subagent session 目录（getSubagentSessionDir(agentDir,
+   * rootCwd) 宿主推导值）——经 wire ctx.sessionDir 送达 pi 引擎组装 `--session-dir`。
+   * 生产注入方 = RemoteEngine（cli 形态引擎的唯一宿主侧适配点，env 同源推导，见
+   * remote-engine buildRunParams）；编排层显式注入（ctx.sessionDir 有值）时优先于
+   * RemoteEngine 自推导。zcode 等不消费 session 目录的引擎忽略本字段。编排层可
+   * 不注入；RemoteEngine 缺省以同源 env 推导值补齐后恒上 wire；[LEGACY] fallback
+   * 仅旧宿主/独立运行引擎形态可达。
+   */
+  sessionDir?: string;
   /**
    * [P4 对齐点③] 引擎声明实际隔离池 key（journal 落盘路径权威）。宿主创建 journal
    * writer 时只能用缺省占位 poolKey（pi 恒 'shared'），非池化稳定的引擎（zcode 按
@@ -126,33 +142,16 @@ export interface RunContext {
    */
   onChildSpawned?: (child: ChildProcess) => void;
   /**
-   * [W3 v1.x] chat 会话形态参数（协议 run.params.chat 的 RunContext 承载位）：
-   *   - recordId：core 预建 record 的关联键（引擎据此上报首轮 runId 键之外的反向
-     *     载荷与 interact 定位）——task.conversation === true 的 chat 轮必传；
-   *   - resume：冷续锚点（重开已 idle 的 session 续聊；pi 消费 sessionRef.sessionFile
-     *     ——对照协议化设计前 SpawnResumeOpts.sessionFile 的锚点面）。
-   * 类型权威 = SDK RunChatParams（remote-engine 直传，结构互证由 implements 关系
-   * 在 typecheck 期承载）。非 chat 轮不传，wire 上不出现该键。
+   * [W3 v1.x → H1 U6 终态] 会话形态参数（协议 run.params.resume 的 RunContext
+   * 承载位，键已随 U6 键切换从 `chat` 泛化为 `resume`）：
+   *   - recordId：core 预建 record 的关联键（引擎据此上报 childSpawned/childStateChanged
+   *     的 record 键形态与 handle 锚定）——会话形态轮（task.conversation === true）必传；
+   *   - resume：续聊锚点（record.sessionFile 续写原文件；pi 消费
+   *     sessionRef.sessionFile——对照协议化设计前 SpawnResumeOpts.sessionFile 的锚点面）。
+   * 类型权威 = SDK RunResumeParams（remote-engine 直传，结构互证由 implements 关系
+   * 在 typecheck 期承载）。一次性轮不传，wire 上不出现该键。
    */
-  chat?: { recordId: string; resume?: ResumeAnchor };
-  /**
-   * [W3 v1.x] host/roundLifecycle 轮次生命周期消费口（第 9 反向通道，settled/idle/
-   * failed 三相位；关联键 runId|recordId 互斥）。首轮（run 会话形态）经 run 作用域
-   * 路由到达（runId 键）；续聊轮（interact）无 runId——经 EnginePort
-   * registerChatRoundRoute 的 recordId 键路由到达（见下）。消费语义（arm/disarm/
-   * settled 交棒）归宿主编排层（settled-watchdog 协议事件面接线，W4 三入口）。
-   */
-  onRoundLifecycle?: (phase: HostRoundLifecycleParams) => void;
-}
-
-/**
- * [W3 v1.x] chat 轮次反向通道路由（recordId 键）——interact 续聊轮的 streamDelta /
- * roundLifecycle 分发目标（协议关联键裁定 D1-A：续聊轮无独立 runId）。与 run 作用域
- * RunRoute 同构的薄消费面；注册/注销时机归宿主 chat 编排（轮开始注册、record 终态注销）。
- */
-export interface ChatRoundRoute {
-  onStreamDelta?: (delta: string) => void | Promise<void>;
-  onRoundLifecycle?: (phase: HostRoundLifecycleParams) => void | Promise<void>;
+  resume?: { recordId: string; resume?: ResumeAnchor };
 }
 
 // ============================================================
@@ -194,29 +193,13 @@ export interface EnginePort {
   probe(opts?: { force?: boolean }): Promise<ProbeReport>;
 
   /** D1 主语义：fire-to-completion。[D6 合流] task = AgentCallOpts（单一任务形状，
-   *  原 AgentTaskSpec 已并入——字段裁定见 orchestration/models/types.ts）。 */
+   *  原 AgentTaskSpec 已并入——字段裁定见 orchestration/models/types.ts）。会话形态
+   *  续聊轮同走本方法（resume 锚点经 ctx.resume 携带，[H1 U6] interact 面退役）。 */
   run(task: AgentCallOpts, ctx: RunContext): Promise<EngineRunResult>;
 
-  /**
-   * D1 可选面：交互控制面。pi 首期原生实现（现有 chatMode 行为直通）；不支持
-   * conversation 的引擎返回 engine_capability_unsupported（同步拒绝、不创建进程）。
-   */
-  interact(handle: EngineHandle, action: InteractAction): Promise<InteractResult>;
-
   /** D6 三级降级链：①引擎原生读取 → ②宿主 event journal（P2）→ ③outcome-only。 */
   read(handle: EngineHandle): Promise<SessionView>;
 
-  /**
-   * [W3 v1.x] 可选面：chat 轮次反向通道路由注册（recordId 键）。interact 续聊轮的
-   * streamDelta / roundLifecycle 按 recordId 关联（无 runId，D1-A），引擎进程发射后
-   * 经协议客户端分发到本路由。与 validateModel/listModels 同款的 additively-optional
-   * 演进：宿主 feature-detect（`typeof registerChatRoundRoute === "function"`），
-   * 未实现的引擎（不支持 chat 域或旧客户端）续聊轮 delta/生命周期静默不可达——
-   * conversation gate 已在派发前拦住无 chat 能力的引擎，本缺省只在「能力声明与
-   * 客户端实现错位」的诊断形态出现。返回注销函数（record 终态时宿主调用）。
-   */
-  registerChatRoundRoute?(recordId: string, route: ChatRoundRoute): () => void;
-
   /**
    * [U7] 可选面：模型可发现性——引擎自带 provider/model 体系时（如 zcode 的 v2 桌面
    * 登录态），列出当前环境实际可用的模型清单（带凭据校验），供 system prompt 引擎段
@@ -254,4 +237,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;
 }