@zhushanwen/pi-subagent-workflow 8.4.0 → 8.5.0

package/src/execution/engine/types.ts

@@ -0,0 +1,304 @@
+// src/execution/engine/types.ts
+//
+// 引擎中立类型层（P1）。设计权威源：docs/architecture/subagent-engine-abstraction.md
+// §3.3.5（EnginePort 与中立类型完整契约）+ §3.3.6（EngineHandle/journal/SessionView 格式）。
+//
+// 为什么单独一层：执行层现有四个核心类型（ExecuteOptions/AgentEvent/AgentResult/AgentRunner
+// port）的中立是「碰巧的，不是设计的」——thinkingLevel 是 pi 7 档枚举、skillPath 假设引擎有
+// --skill flag、conversation/idleTimeoutMs 是 pi chatMode 专属形态（设计 §2.1）。本文件把
+// 「agent 调用」的引擎无关语义显式化为 AgentTaskSpec / AgentOutcome 等类型，EnginePort
+// （port.ts）与其下各引擎适配器都以本层为唯一契约点。
+//
+// 泛化原则（D2）：从现有类型泛化，不另起炉灶——字段与 execution/types.ts 的
+// ExecuteOptions、orchestration/models/types.ts 的 AgentResult 逐一锚定，标注「泛化」的
+// 条目语义有变，标注「新增」为引擎层新引入。
+//
+// AgentResult 消歧（设计 §2.1/§3.3.5）：仓内有两个同名 AgentResult——
+//   ① orchestration 层 workflow 消费的那份（orchestration/models/types.ts，主字段
+//      content/parsedOutput/usage/error）——中立层锚定这份，AgentOutcome 的字段就是它的
+//      超集（+ engineId/engineFallback/exitCode）；
+//   ② execution 层的同名类型（execution/types.ts，主字段 text/turns/sessionId/toolCalls）
+//      ——record 内部投影，保持原名不动。
+// 引擎层终态命名 AgentOutcome，与两者不同名，消除「同名不同义」。
+
+import type { AgentUsage, ToolCallEntry } from "../../orchestration/models/types.ts";
+import type { AgentUsageTotal, ToolCall, WorktreeHandle } from "../types.ts";
+
+// AgentEvent 8 种事件原样保留，唯一权威定义仍是 execution/types.ts——引擎层 re-export
+// 不复制第二份（设计 §3.3.5）；经 shared/agent-event.ts 的既有出口转发，维持「shared/
+// 是类型共享层」的架构约定。新增粗粒度约束（coarse 引擎至少合成一次 message_end +
+// 一次 turn_end）由 conformance 套件断言（P4），不在类型层编码。
+export type { AgentEvent } from "../../shared/agent-event.ts";
+
+// ============================================================
+// AgentTaskSpec（= 现有 ExecuteOptions 泛化，D2）
+// ============================================================
+
+/** 人设（persona）注入规格：原 skillPath + appendSystemPrompt 收拢进一个语义单元（D2）。 */
+export interface PersonaSpec {
+  /**
+   * agent 名/路径。与 AgentTaskSpec.agent 的分工：agent 是 resolveIdentity 的身份解析
+   * 键（模型/系统提示等身份语义）；agentRef 是 persona 注入通道的定位符——引擎按
+   * capabilities.personaInjection 决定注入通道（file/flag/prompt）时用它定位人设。
+   * pi 引擎不消费此字段（身份解析走 spec.agent），留给 flag/file 通道的引擎。
+   */
+  agentRef?: string;
+  /**
+   * 原 ExecuteOptions.skillPath。公共 persona 路由三策略（file/flag/prompt）的分流
+   * 载体（D4）——超长 prompt 时优先 file/flag 通道分流的落点。
+   */
+  skillPath?: string;
+  /** 追加系统提示内容数组（原样透传；schema 仿真段由公共降级层拼装后放入，P2）。 */
+  appendSystemPrompt?: string[];
+}
+
+/**
+ * 引擎无关的 agent 任务声明（= ExecuteOptions 泛化，字段逐条锚定设计 §3.3.5）。
+ *
+ * 与 ExecuteOptions 的差异（泛化点）：
+ *   - thinkingLevel（pi 7 档枚举语义）→ effort?: string，各引擎自行映射或忽略；
+ *   - skillPath + appendSystemPrompt → persona（PersonaSpec）；
+ *   - conversation/idleTimeoutMs 保留原名透传——属 interact 交互控制面的 task 标志（D1），
+ *     不是 pi 专有语义的泄漏，而是「任务声明里声明交互模式」的中立表达；
+ *   - 删字段去向：signal/ctxModel/onComplete 是运行期句柄，移入 RunContext（port.ts）；
+ *     schemaEnv 内化到 PiEngine（从 task.schema 派生，见 engines/pi/task-spec-mapper.ts）。
+ *
+ * 新增（为后续 wave 预留形状，P1 无生产写入方）：
+ *   - denyTools：中立工具 denylist（附录 A 该行的载体）；
+ *   - permissionMode：中立权限模式（映射按 capabilities.permissionMode）。
+ */
+export interface AgentTaskSpec {
+  /** 原样（ExecuteOptions.task）。 */
+  task: string;
+  /** 原样（ExecuteOptions.slug，≤35 字符）。 */
+  slug: string;
+  /** 原样（ExecuteOptions.agent，resolveIdentity 的 agent ref）。 */
+  agent?: string;
+  /** 原样（ExecuteOptions.model；在引擎 provider 体系内解释，D9②）。 */
+  model?: string;
+  /**
+   * 泛化：原 ExecuteOptions.thinkingLevel。引擎无关的推理投入档位字符串——
+   * pi 引擎把它原值映射回 thinkingLevel 7 档；其他引擎自行映射（CC 5 档）或忽略
+   * （kimi ❌）。不定义联合枚举：档位集合是引擎私有语义，中立层只透传字符串。
+   */
+  effort?: string;
+  /** 泛化：原 skillPath + appendSystemPrompt 收拢（D2）。 */
+  persona?: PersonaSpec;
+  /**
+   * 原样（ExecuteOptions.schema）。native/emulated 分流依据（D4 硬边界）：pi 的
+   * PI_WORKFLOW_SCHEMA env 注入链路按 native 直传，公共仿真层只服务 emulated 引擎。
+   */
+  schema?: Record<string, unknown>;
+  /** 原样（ExecuteOptions.maxTurns）。 */
+  maxTurns?: number;
+  /** 原样（ExecuteOptions.graceTurns）。 */
+  graceTurns?: number;
+  /** 原样（ExecuteOptions.fork）。pi 专属；其他引擎 prepare 期按 capabilities 拒绝。 */
+  fork?: boolean;
+  /**
+   * 原样（ExecuteOptions.worktree）。公共层职责（worktree-manager），非引擎职责——
+   * 引擎只把它当 spawn cwd 的来源之一。
+   */
+  worktree?: boolean | WorktreeHandle;
+  /** 原样（ExecuteOptions.cwd）。 */
+  cwd?: string;
+  /** 原样（ExecuteOptions.conversation，interact 控制面的 task 标志，D1）。 */
+  conversation?: boolean;
+  /** 原样（ExecuteOptions.idleTimeoutMs，同上）。 */
+  idleTimeoutMs?: number;
+  /** 新增：中立工具 denylist。各引擎做语法映射（附录 A「工具 denylist」行的载体）。 */
+  denyTools?: string[];
+  /** 新增：中立权限模式。映射按 capabilities.permissionMode（kimi fixed auto = ignored）。 */
+  permissionMode?: string;
+  /**
+   * [P4 形状预留，D9① 守卫 b 的独立载体] 任务对引擎能力的显式依赖声明。
+   * 首期无生产写入方：守卫 b 与守卫 a 合流（显式 engine 即能力依赖声明）——调用方
+   * 按引擎 id 表达依赖。下钻时机（AgentTaskSpec 泛化成熟后）：调用方改按能力表达
+   * （如 requires: { sandbox: 'native' }），路由层将本字段与各引擎 capabilities()
+   * 对照，无引擎满足时报 engine_capability_unsupported（调用前拒绝，D11 处置三级）。
+   */
+  requires?: Partial<EngineCapabilities>;
+}
+
+// ============================================================
+// AgentOutcome（锚定 orchestration 层 AgentResult，§3.3.5）
+// ============================================================
+
+/**
+ * 一次引擎执行的终态。锚定 orchestration/models/types.ts 的 AgentResult（workflow
+ * 引擎消费的那份——content/parsedOutput/usage/error）并追加引擎层字段；见文件头消歧说明。
+ */
+export interface AgentOutcome {
+  /** 原样（AgentResult.content）。 */
+  content: string;
+  /**
+   * 原样（AgentResult.parsedOutput）。native 引擎直传 / 仿真层 ajv 产出（D4 硬分流：
+   * native 路径公共层不做二次校验、不改写其结果）。
+   */
+  parsedOutput?: unknown;
+  /** 原样（AgentResult.usage，orchestration 版 AgentUsage：含 contextTokens/turns）。 */
+  usage?: AgentUsage;
+  /** 原样（AgentResult.durationMs）。 */
+  durationMs?: number;
+  /** 原样（AgentResult.error，错误码前缀格式见设计 §3.3.3 错误规格表）。 */
+  error?: string;
+  /** 原样（AgentResult.sessionId，引擎语义 session id）。 */
+  sessionId?: string;
+  /** 原样（AgentResult.sessionFile）。 */
+  sessionFile?: string;
+  /** 原样（AgentResult.worktreePath，仅诊断——目录可能已被 finalize 清理）。 */
+  worktreePath?: string;
+  /** 原样（AgentResult.toolCalls，ToolCallEntry[]）。 */
+  toolCalls?: ToolCallEntry[];
+  /** 新增：实际执行引擎（fallback 后可能 ≠ 请求值，D9①）。 */
+  engineId: string;
+  /** 新增：fallback 留痕（record 同步投影，GUI 警告条数据源）。P1 恒缺省（无 fallback 路由）。 */
+  engineFallback?: { from: string; reason: string };
+  /** 新增：null = 被信号杀死（杀链/abort 合成终态的判据）。P1 pi 链路不暴露 exit code，恒缺省。 */
+  exitCode?: number | null;
+}
+
+// ============================================================
+// EngineHandle（run/interact/read 三面的连接件，D1/§3.3.6）
+// ============================================================
+
+/**
+ * EngineHandle 的持久化形态（设计 §3.3.6，JSON v1）。
+ * 内存态 EngineHandle = 本数据 + 引擎运行时引用（各引擎自持）。
+ */
+export interface EngineHandleData {
+  v: 1;
+  /** 引擎 id（'pi' | 'zcode' | ...，registry key）。 */
+  engineId: string;
+  /**
+   * 引擎自定义键值（定位符）。pi = { recordId?, sessionFile? }——recordId 是
+   * interact 控制面的 key（subagent record id），sessionFile 是 read 第①级（JSONL
+   * 直读）的定位符；zcode = { sessionId, dbPath }。
+   */
+  sessionRef: Record<string, string>;
+  /** 隔离池定位（设计 §3.3.9）。pi 无池化（PI_CODING_AGENT_DIR 全局一份）恒 'shared'。 */
+  poolKey: string;
+  /**
+   * journal 绝对路径（read 第②级数据源；runtime 读前校验前缀白名单）。
+   * P2 event journal 落地后由宿主回填；P1 无 journal 写入者，缺省 undefined——
+   * read 降级链第②级不可达，直接走 ①/③。
+   */
+  journalPath?: string;
+  /** probe 实测版本（漂移排查锚点）。 */
+  engineVersion?: string;
+  /** 适配器版本（golden 样本对齐排查）。 */
+  adapterVersion: string;
+}
+
+/**
+ * 引擎会话句柄（run 返回、interact/read 入参）。
+ *
+ * 契约三条（D1）：不透明（上层不解构——唯一例外是 record 持久化层序列化 data 字段与
+ * read 降级链）、可持久化（data 是纯 JSON，主会话 reload 后 read/interact 仍可用）、
+ * 自描述（data 含 engineId + 引擎 session 定位符 + pool key + adapter 版本）。
+ *
+ * 对进程已死的 handle 调 interact 必须返回 engine_session_not_resumable（指向 cold
+ * resume 路径），而非笼统失败——由各引擎 interact 实现保证。
+ */
+export interface EngineHandle {
+  /** 持久化数据。上层不得解构其内部字段（见契约三条）。 */
+  readonly data: EngineHandleData;
+}
+
+// ============================================================
+// SessionView（read 返回，D6/§3.3.6）
+// ============================================================
+
+/**
+ * read(handle) 的返回：turns[] 派生数据。与 Turn 同构但无内部态（_status/startedTs
+ * 剥离，closed 恒 true）。
+ */
+export interface ReplayedTurn {
+  text: string;
+  thinking: string;
+  /** 导出的纯净形状（execution 层 ToolCall，无 _status）。 */
+  toolCalls: ToolCall[];
+  closed: true;
+}
+
+/**
+ * session 历史的引擎中立视图。降级链三级（D6）：①引擎原生读取（pi JSONL / zcode
+ * sqlite）→ ②宿主 event journal 重放（P2）→ ③outcome-only。source 字段是 GUI 降级
+ * 标记数据源（A8）。
+ */
+export interface SessionView {
+  engineId: string;
+  sessionId?: string;
+  /** turns[] 派生数据（重放/重建产物）。 */
+  turns: ReplayedTurn[];
+  /** 各 turn usageDelta 聚合（execution 层 AgentUsageTotal）。 */
+  usage?: AgentUsageTotal;
+  source: "native" | "journal" | "outcome-only";
+}
+
+// ============================================================
+// EngineCapabilities（D3，三级声明）
+// ============================================================
+
+/**
+ * 引擎能力声明（设计 D3 原样落地）。三级：native / emulated / unsupported。
+ *
+ * 易错点（D3）：声明的是**本仓 subagent 链路实际接通的能力**，不是引擎 RPC 层的理论
+ * 能力——pi 的 RPC 有 steer 但现有 spawn 链路未接通（session-runner steer no-op），
+ * 故 PiEngine 声明 unsupported，接通后再升级。上层据声明选择策略（schema 为 emulated
+ * 时自动走公共降级层；steer/conversation unsupported 时 UI 隐藏对应入口），而非
+ * try-catch 运行时试错。
+ */
+export interface EngineCapabilities {
+  /** native: --json-schema/--output-schema/env 注入（pi = PI_WORKFLOW_SCHEMA 链路）。 */
+  schemaEnforcement: "native" | "emulated";
+  /** 注意区分「引擎 RPC 层有此能力」与「subagent 链路已接通」。 */
+  steer: "native" | "emulated" | "unsupported";
+  /** interact 控制面（message/close/cancel + idle）。 */
+  conversation: "native" | "unsupported";
+  /** 决定 persona 路由策略（公共降级层按此选择 file/flag/prompt 通道）。 */
+  personaInjection: "file" | "flag" | "prompt";
+  /** 粗粒度引擎：GUI 显示降级为阶段态。 */
+  eventGranularity: "stream" | "coarse";
+  /** emulated = worktree 隔离（无 OS sandbox 的引擎用文件写维度隔离补齐）。 */
+  sandbox: "native" | "emulated" | "none";
+  /** 重建历史的能力（read 降级链第①级的保真度上限）。 */
+  sessionRead: "full" | "partial" | "outcome-only";
+  resume: "native" | "cold" | "unsupported";
+  /** 优雅中断 or 只能杀进程（公共杀链兜底，见 D1 abort 分级）。 */
+  interrupt: "native" | "kill-only";
+  /** kimi headless 固定 auto = ignored；GUI 据此隐藏/提示。 */
+  permissionMode: "native" | "fixed" | "ignored";
+}
+
+// ============================================================
+// probe（D7）与 interact（D1）的负载类型
+// ============================================================
+
+/** 引擎探针报告（probe() 返回）。探针在引擎 factory 初始化与版本变化检测时触发（P4 接线）。 */
+export interface ProbeReport {
+  ok: boolean;
+  /** 实测版本（handle.engineVersion 数据源）。探测不到时为空串。 */
+  engineVersion: string;
+  /** 二进制存在/版本解析/干跑回归逐项。 */
+  checks: Array<{ name: string; ok: boolean; detail?: string }>;
+  /** engine_probe_failed 的恢复指引（设计 §3.3.3 终态四样例；ok=false 时必填）。 */
+  error?: { code: string; recovery: string };
+}
+
+/**
+ * interact 的 action（D1 交互控制面）。pi 首期原生实现（现有 chatMode 行为直通）；
+ * 声明 conversation unsupported 的引擎调用前拒绝（engine_capability_unsupported）。
+ */
+export type InteractAction =
+  | { kind: "message"; payload: string }
+  | { kind: "close"; payload?: { force: boolean } }
+  | { kind: "cancel" };
+
+/**
+ * interact 的结果。失败码取自设计 §3.3.3：engine_session_not_resumable（死 handle）/
+ * engine_capability_unsupported（能力声明拒绝）等。
+ */
+export type InteractResult =
+  | { ok: true; delivered: true }
+  | { ok: false; code: string; message: string };

package/src/execution/execute-options-mapper.ts

@@ -6,6 +6,7 @@
 // 接线层级：[模块内直调] —— SAR.run 内调。
 
 import type { AgentCallOpts } from "../orchestration/models/types.ts";
+import { HOST_TIMEOUT_ABORT_REASON } from "./engine/common/kill-chain.ts";
 import type { ModelInfo } from "./model-resolver.ts";
 import type { ExecuteOptions } from "./types.ts";
 
@@ -84,7 +85,10 @@ export function mergeTimeoutSignal(
   }
 
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  // 超时 abort 带 reason 标记（对齐点④）：引擎合成终态时判别「宿主超时」
+  // （engine_timeout 公共合成）vs「外部 cancel」（中止标记）——pi 链路不读 reason，
+  // 行为不变。外部 signal abort 不带标记（用户/编排层 cancel 语义）。
+  const timer = setTimeout(() => controller.abort(HOST_TIMEOUT_ABORT_REASON), timeoutMs);
   timer.unref();
 
   const onExternalAbort = (): void => controller.abort();

package/src/execution/execution-record.ts

@@ -161,6 +161,10 @@ export function createRecord(
     chatMode?: boolean;
     /** 空闲超时毫秒数（仅 chatMode 有意义）。覆盖默认 5min。 */
     idleTimeoutMs?: number;
+    /** 实际执行引擎 id（P4 路由留痕，D9①）。缺省 = pi 投影（存量零迁移）。 */
+    engine?: string;
+    /** 引擎 fallback 留痕（probe 失败路由回默认引擎）。GUI 警告条数据源。 */
+    engineFallback?: { from: string; reason: string };
     controller?: AbortController;
   },
 ): ExecutionRecord {
@@ -178,6 +182,8 @@ export function createRecord(
     depth: identity.depth ?? 0,
     chatMode: identity.chatMode,
     idleTimeoutMs: identity.idleTimeoutMs,
+    engine: identity.engine,
+    engineFallback: identity.engineFallback,
 
     // 状态（实时更新）
     status: "running",

package/src/execution/model-resolver.ts

@@ -48,6 +48,12 @@ export interface AgentConfig {
   thinkingLevel?: string;
   /** 默认 background 模式（true 时无显式 wait 走 background）。 */
   defaultBackground?: boolean;
+  /**
+   * 执行引擎 id（agent .md frontmatter engine 字段，D9 per-agent 主通道）。
+   * 解析期已对注册表校验（未注册 id 在 agent-registry 抛 EngineNotFoundError）；
+   * 执行侧（P4 路由层）按 调用参数 > 本字段 > 全局默认 三层取值。
+   */
+  engine?: string;
 }
 
 /** 解析结果（model 实例 + 生效的 thinkingLevel）。 */

package/src/execution/pi-invocation.ts

@@ -1,4 +1,4 @@
-// src/core/pi-invocation.ts
+// src/execution/pi-invocation.ts
 //
 // 定位 pi 二进制并组装 spawn 调用。Core 叶子原语（仅依赖 node 内置）。
 //
@@ -16,6 +16,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+import { isRelayActive, RELAY_ENV_NODE, RELAY_ENV_SCRIPT } from "./relay-env.ts";
+
 /** spawn 调用描述符：command + args（透传给 child_process.spawn）。 */
 export interface PiInvocation {
   /** 可执行文件路径（node/bun/pi 二进制）。 */
@@ -24,6 +26,16 @@ export interface PiInvocation {
   args: string[];
 }
 
+/** getPiInvocation 可选项。 */
+export interface PiInvocationOptions {
+  /**
+   * false = 强制直连 spawn 真实 pi（不经 relay 代理）。唯一现役消费点是 PiEngine.probe
+   * ——探针意图是 pi 本体可解析性，经 relay 探到的是 runtime 健康，语义错位（E 方案 §5.1）。
+   * 缺省（undefined / true）时按 relay env 激活判定走代理。
+   */
+  relay?: boolean;
+}
+
 /**
  * bun 虚拟文件系统前缀。bun bundle 模式下 process.argv[1] 形如
  * /$bunfs/root/pi——这不是磁盘上的真实文件，不能直接 spawn。
@@ -43,9 +55,12 @@ function isGenericRuntime(execPath: string): boolean {
  * 组装 pi 子进程的 spawn 调用。
  *
  * @param userArgs pi CLI 参数（如 ["--mode", "rpc", "--session-dir", "..."]）
+ * @param opts 可选项（relay:false 强制直连——probe 用，见 PiInvocationOptions）
  * @returns spawn 描述符（command + 完整 args）
  *
  * 决策链（按优先级）：
+ *   0. relay 激活（三 env 齐备且未显式禁用）→ <RELAY_NODE> <RELAY_SCRIPT> <userArgs>
+ *      （E 方案 §5.1：xyz-agent runtime 存在时经代理 spawn，改的是进程拓扑不是 pi 语义）
  *   1. process.argv[1] 是真实磁盘文件且非 bun 虚拟路径 → <execPath> <argv[1]> <userArgs>
  *      （复现当前 pi 进程的启动方式，确保扩展/配置/版本一致）
  *   2. execPath 非通用运行时（pi standalone binary）→ <execPath> <userArgs>
@@ -71,10 +86,25 @@ function currentScriptExists(): boolean {
   return scriptExistsCache.exists;
 }
 
-export function getPiInvocation(userArgs: string[]): PiInvocation {
+export function getPiInvocation(userArgs: string[], opts?: PiInvocationOptions): PiInvocation {
   const currentScript = process.argv[1];
   const isBunVirtualScript = currentScript?.startsWith(BUN_VIRTUAL_PREFIX);
 
+  // 分支 0（前置）：relay 激活（E 方案 §5.1）——runtime 注入三 env 齐备且未显式禁用时，
+  // spawn 目标切换为 <RELAY_NODE> <RELAY_SCRIPT> <原 pi spawnArgs>，形态与分支 1「node +
+  // script」同构（command 是执行器、args[0] 是脚本）。ELECTRON_RUN_AS_NODE 不在此补：
+  // 打包态执行器为 Electron 时由 runtime 与三 env 同点注入主 pi 进程 env（E-2
+  // getRelaySpawnEnv），本进程 {...process.env} 继承即达代理进程，extension 不重复判定。
+  // isRelayActive 已保证三 env 非空，下方取局部变量仅为 TS 收窄（isRelayActive 的
+  // 收窄不跨函数边界传导）。
+  if (opts?.relay !== false && isRelayActive(process.env)) {
+    const relayNode = process.env[RELAY_ENV_NODE];
+    const relayScript = process.env[RELAY_ENV_SCRIPT];
+    if (relayNode !== undefined && relayScript !== undefined) {
+      return { command: relayNode, args: [relayScript, ...userArgs] };
+    }
+  }
+
   // 分支 1：有真实脚本路径 → 复现启动方式（node <pi-script> <args>）
   if (currentScript && !isBunVirtualScript && currentScriptExists()) {
     return { command: process.execPath, args: [currentScript, ...userArgs] };

package/src/execution/record-entry.ts

@@ -82,6 +82,17 @@ export interface SubagentRecordEntryData {
   chatMode?: boolean;
   /** 执行态信号（residual-fixes）：true = 无活进程驱动的 running（轮终/孤儿兜底）。 */
   resumable?: boolean;
+  /**
+   * 实际执行引擎 id（P4 路由留痕，D9①）。缺省（存量 entry）= pi 投影，消费方零迁移。
+   */
+  engine?: string;
+  /** 引擎 fallback 留痕（probe 失败路由回默认引擎）。GUI 警告条数据源。 */
+  engineFallback?: { from: string; reason: string };
+  /**
+   * 引擎自描述定位符（U1：read 降级链①②级数据源）。引擎无关——sessionRef 整体
+   * 透传不枚举内部键（zcode = { sessionId, dbPath }）；缺省 = pi（存量 entry 零迁移）。
+   */
+  engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
 }
 
 /** SubagentRecord → 自描述 entry data（快照投影，不 mutate 源）。 */
@@ -114,5 +125,8 @@ export function toSubagentRecordEntry(record: SubagentRecord): SubagentRecordEnt
     round: record.round,
     chatMode: record.chatMode,
     resumable: record.resumable,
+    engine: record.engine,
+    engineFallback: record.engineFallback,
+    engineHandle: record.engineHandle,
   };
 }

package/src/execution/record-store.ts

@@ -267,9 +267,39 @@ function rebuildEntryRecord(id: string, d: Record<string, unknown>): SubagentRec
     sessionFile: undefined,
     chatMode: d.chatMode === true,
     round: num("round"),
+    engine: str("engine"),
+    engineFallback:
+      isEngineFallbackShape(d.engineFallback) ? d.engineFallback : undefined,
+    engineHandle: isEngineHandleShape(d.engineHandle) ? d.engineHandle : undefined,
   };
 }
 
+/** engineFallback entry 值的运行时 guard（未知 JSON 不裸收）。 */
+function isEngineFallbackShape(v: unknown): v is { from: string; reason: string } {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v as Record<string, unknown>;
+  return typeof r.from === "string" && typeof r.reason === "string";
+}
+
+/** engineHandle entry 值的运行时 guard（未知 JSON 不裸收；形状与 runtime 读侧
+ *  subagent-engine-history 的 extractRecordEngineHandle 守卫语义对齐：poolKey
+ *  必有非空 string + sessionRef 值全 string 才收，journalPath 可选 string）。 */
+function isEngineHandleShape(
+  v: unknown,
+): v is { sessionRef: Record<string, string>; journalPath?: string; poolKey: string } {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const h = v as Record<string, unknown>;
+  if (typeof h.poolKey !== "string" || h.poolKey.length === 0) return false;
+  if (typeof h.sessionRef !== "object" || h.sessionRef === null || Array.isArray(h.sessionRef)) {
+    return false;
+  }
+  for (const value of Object.values(h.sessionRef as Record<string, unknown>)) {
+    if (typeof value !== "string") return false;
+  }
+  if (h.journalPath !== undefined && typeof h.journalPath !== "string") return false;
+  return true;
+}
+
 /** stat 戳（不存在 → null）。 */
 function statStamp(p: string): Stamp | null {
   try {
@@ -1195,6 +1225,10 @@ export class RecordStore {
       resumable: r.resumable,
       // [review round2] worktree 隔离标志：内存源有 handle 或跨重启重建带 hadWorktree 均为 true。
       worktree: r.worktreeHandle !== undefined || r.hadWorktree === true,
+      engine: r.engine,
+      engineFallback: r.engineFallback,
+      // U2：engineHandle 经 entry 持久化（register/archive 双写点均经本投影），无则 undefined 自然省略
+      engineHandle: r.engineHandle,
     };
   }
 }

package/src/execution/relay-env.ts

@@ -0,0 +1,37 @@
+/**
+ * subagent relay 通道 env 名与协议常量 SSOT（docs/architecture/subagent-realtime-channel.md §5.1/§5.2/§3.1）。
+ *
+ * 为什么独立成模块：三方消费同一份常量——extension 侧（pi-invocation 激活判定 /
+ * buildChildEnv 归属写入）、runtime 侧（env 注入与镜像校验）、代理脚本 relay.mjs
+ * （零依赖脚本不能 import workspace 包，只能内嵌镜像，镜像一致性由 conformance
+ * relay 变体断言锁定）。禁各处手写字符串。
+ *
+ * env 语义：SOCKET/NODE/SCRIPT 三者同时非空 = relay 激活（全有或全无，无中间态）；
+ * SESSION_ID/RECORD_ID 是 tee 帧归属键（缺失由代理握手前自检拒绝，退出码 13）。
+ */
+
+export const RELAY_ENV_SOCKET = 'XYZ_SUBAGENT_RELAY_SOCKET';
+export const RELAY_ENV_NODE = 'XYZ_SUBAGENT_RELAY_NODE';
+export const RELAY_ENV_SCRIPT = 'XYZ_SUBAGENT_RELAY_SCRIPT';
+export const RELAY_ENV_SESSION_ID = 'XYZ_SUBAGENT_RELAY_SESSION_ID';
+export const RELAY_ENV_RECORD_ID = 'XYZ_SUBAGENT_RELAY_RECORD_ID';
+
+/** relay 协议版本（握手帧 v 字段；runtime 与代理同包分发，不匹配=安装损坏）。 */
+export const RELAY_PROTOCOL_VERSION = 1;
+
+/** 代理专用退出码（extension 侧表现为「子进程非零退出」→ engine_run_failed 语义）。 */
+export const RELAY_EXIT_CODES = {
+  /** 握手被拒：协议版本不匹配（安装损坏，重装应用）。 */
+  VERSION_MISMATCH: 10,
+  /** relay socket 不可达（runtime 未运行或已重启）。 */
+  SOCKET_UNREACHABLE: 11,
+  /** socket 中途断开（runtime 崩溃等）——代理生命线断即退。 */
+  SOCKET_CLOSED: 12,
+  /** 归属 env（SESSION_ID/RECORD_ID）缺失——防无归属帧污染广播。 */
+  MISSING_IDENTITY: 13,
+} as const;
+
+/** 激活判定：三 env 同时非空才走 relay，任一缺失回落直连 spawn 真实 pi（TUI/独立 pi 零回归）。 */
+export function isRelayActive(env: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean {
+  return Boolean(env[RELAY_ENV_SOCKET] && env[RELAY_ENV_NODE] && env[RELAY_ENV_SCRIPT]);
+}

package/src/execution/session-runner.ts

@@ -25,6 +25,7 @@ import type { AgentConfig, ResolvedModel } from "./model-resolver.ts";
 import { collectResult } from "./output-collector.ts";
 import { getSubagentSessionDir } from "./path-encoding.ts";
 import { getPiInvocation } from "./pi-invocation.ts";
+import { isRelayActive, RELAY_ENV_RECORD_ID, RELAY_ENV_SESSION_ID } from "./relay-env.ts";
 import { stringifySchemaCached } from "../shared/schema-jsonify.ts";
 import { MAX_FORK_DEPTH } from "./session-context-resolver.ts";
 import { EPIPE_FAILURE_THRESHOLD, recordEpipeFailure, sendPromptCommand } from "./stdin-writer.ts";
@@ -335,6 +336,20 @@ function removeChildRegistration(recordId: string, child: ChildProcess): void {
   }
 }
 
+/**
+ * [U0 D10] 非 pi 引擎路径的子进程记账注册入口（宿主经 RunContext.onChildSpawned 调用）。
+ *
+ * 与 pi runSpawn 内联注册同构：set 进 Map + close/error 按句守卫移除（M4 竞态守卫语义
+ * 复用 removeChildRegistration）。pi 路径保持内联不动（其 close/error handler 还承担
+ * EPIPE 记账等 pi 专属副作用，不适合收敛到本函数）——两入口写同一 Map，dispose 的
+ * killAllSpawnedChildren / cancelBackground 的 getChildByRecord 对两域 record 均生效。
+ */
+export function registerSpawnedChildForRecord(recordId: string, child: ChildProcess): void {
+  spawnedChildren.set(recordId, child);
+  child.once("close", () => removeChildRegistration(recordId, child));
+  child.once("error", () => removeChildRegistration(recordId, child));
+}
+
 // ============================================================
 // 依赖注入容器 + 入参
 // ============================================================
@@ -963,6 +978,15 @@ function buildChildEnv(
   //（同进程内保留），子进程 identity entry 据此记 worktree:true——跨重启重建时据此拒绝续聊
   //（WorktreeHandle 不可序列化，reattach 不可行，静默回落主 repo 会破坏隔离）。
   childEnv.PI_SUBAGENT_WORKTREE = opts.worktree !== undefined ? "true" : undefined;
+  // [E 方案 §5.2-2] relay 帧归属 env：tee 帧路由键（→ 虚拟分区 subagent:<sid>:<rid>）。
+  // 仅 relay 激活时写入实际值——未激活环境下子 pi 进程携带 record 值 env 是误导噪声
+  //（归属 env 无消费者）；{...process.env} 继承值照旧保持。同源性对齐上方 PI_SUBAGENT_*
+  // 四元组：SESSION_ID = ctx.sessionRootId（嵌套 spawn 时孙进程仍归属真 ROOT 会话），
+  // RECORD_ID = record.id。
+  if (isRelayActive(process.env)) {
+    childEnv[RELAY_ENV_SESSION_ID] = ctx.sessionRootId;
+    childEnv[RELAY_ENV_RECORD_ID] = record.id;
+  }
   // D-A6 bridge: schema 激活 structured-output 扩展注册 tool（workflow 编排层需要）
   applySchemaEnvToChildEnv(childEnv, opts.schemaEnv);
   return childEnv;

package/src/execution/stream-sink.ts

@@ -16,6 +16,10 @@
  * - dispose 清除 widget + 清 timer
  */
 
+import type { ExtensionMode } from "./host-mode.ts";
+import { resolveHostMode } from "./host-mode.ts";
+import { isRelayActive } from "./relay-env.ts";
+
 /** UI streaming sink 的最小接口（ctx.ui.setWidget 的 duck-typed 子集）。
  *
  * 当前只有一个 adapter（index.ts session_start 包装 ctx.ui.setWidget）。
@@ -98,3 +102,25 @@ export class SubagentStream {
     ]);
   }
 }
+
+/**
+ * background stream 创建策略（widget 私货通道退役步骤 2，E 方案 §6.3）。
+ *
+ * GUI（mode=rpc）+ relay 激活时不创建——drawer 实时改由 runtime tee 供数
+ * （session.subagentEntriesAppended 帧），extension 停发 setWidget 私货，主 pi stdout
+ * 卸载。TUI（widget 行是 TUI 用户的实时预览）与 relay 未激活环境（独立 pi / 无
+ * xyz-agent runtime）原样创建——universal 包自足性不绑架。
+ *
+ * env/mode 显式入参而非内部读 process.env：调用方语义（本 record 的宿主形态）一次
+ * 确定，测试可注入，函数保持纯判定。
+ */
+export function createBackgroundStream(
+  recordId: string,
+  sink: StreamSink | null,
+  mode: ExtensionMode | undefined,
+  env: NodeJS.ProcessEnv | Record<string, string | undefined>,
+): SubagentStream | undefined {
+  if (sink === null) return undefined;
+  if (isRelayActive(env) && resolveHostMode(mode) === "gui") return undefined;
+  return new SubagentStream(recordId, sink);
+}