@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/src/execution/subprocess-agent-runner.ts

@@ -30,7 +30,10 @@ import type { AgentEvent } from "../shared/agent-event.ts";
 import { assertTaskShapeSupported } from "./engine/common/capability-gate.ts";
 import { HOST_TIMEOUT_ABORT_REASON } from "./engine/common/kill-chain.ts";
 import { JOURNAL_INITIAL_POOL_KEY, wireEventJournal } from "./engine/common/journal-wiring.ts";
-import { createPiEngine } from "./engine/engines/pi/registration.ts";
+// [W6 R1 MF-5] pi EnginePort 解析改经 host 公共面（engine/host/pi-host-binding.ts）：
+// registry cli 形态经 descriptor 路由（W3 双模 getEngine），inproc/未注册回落 per-session
+// DI 直构（行为与改线前 createPiEngine 逐点一致）。
+import { resolveHostPiEnginePort } from "./engine/host/pi-host-binding.ts";
 import type { EnginePort, RunContext } from "./engine/port.ts";
 import { validateModelForEngine } from "./engine/model-validation.ts";
 import { routeEngineForHost, type EngineRouteResult, type EngineRoutingInput } from "./engine/routing.ts";
@@ -39,7 +42,9 @@ import type { AgentOutcome } from "./engine/types.ts";
 import { getModelConfigService } from "./model-config-service.ts";
 import type { ModelInfo } from "./model-resolver.ts";
 import { modelRefFromVerified } from "../shared/model-ref";
-import { registerSpawnedChildForRecord } from "./engine/engines/pi/session-runner.ts";
+// [W6 R1 MF-5] 子进程注册改经 spawnedChildren 状态镜像公共面（engine/host/
+// spawned-children.ts——镜像 + inproc 过渡委托，不再深路径 import inproc pi 引擎目录）。
+import { registerSpawnedChildForRecord } from "./engine/host/spawned-children.ts";
 import type { SubagentStream } from "./stream-sink.ts";
 import type { SubagentService } from "./subagent-service.ts";
 import { toErrorMessage } from "../core/error-message.ts";
@@ -95,7 +100,8 @@ export class SubprocessAgentRunner implements AgentRunner {
     this.subagentService = deps.subagentService;
     this.ctxModel = deps.ctxModel;
     // [D4 聚合连带] 经 asEngineService 显式视图适配（原结构化直绑依赖查询面 public）。
-    this.piEngine = createPiEngine(() => this.subagentService.asEngineService);
+    // [W6] 解析经 host 公共面（descriptor 路由 / inproc DI，见 pi-host-binding 注释）。
+    this.piEngine = resolveHostPiEnginePort(() => this.subagentService.asEngineService);
   }
 
   /**
@@ -138,10 +144,12 @@ export class SubprocessAgentRunner implements AgentRunner {
 
     // ── P4 路由（D3-② 单点：routeEngineForHost）+ D3-④ 预检 ──
     // 路由在最前——引擎身份决定 journal 路径与后续一切执行面。pi 快路径同步短路
-    //（routed 非 Promise，零微任务——缺省路径时序与 P1 接线前完全一致，下游依赖
-    // 「run 内首个 await 前已触达 executeAndAwait」的时序契约）。路由失败（未注册
-    // id / probe 失败 + strict/守卫）与预检命中（capabilities 驱动，含 worktree——
-    // workflow 域漏拦缺口修复）一并按「不 reject」契约转 result.error。
+    //（routed 非 Promise，零微任务）——首个 await 前完成**路由决策**（engine id 已定，
+    // A2 观测点）；其后的执行经进程边界（cli 形态 spawn + 握手 + 帧往返必经 await），
+    // 旧「run 内首个 await 前已触达 executeAndAwait」时序契约由引擎协议化设计
+    // §3.5.3 作废放宽。路由失败（未注册 id / probe 失败 + strict/守卫）与预检命中
+    //（capabilities 驱动，含 worktree——workflow 域漏拦缺口修复）一并按「不 reject」
+    // 契约转 result.error。
     let route: EngineRouteResult;
     try {
       const routed = routeEngineForHost({
@@ -227,7 +235,7 @@ export class SubprocessAgentRunner implements AgentRunner {
       const { handle, outcome } = await route.engine.run(
         // [D6 合流] opts 直传——AgentCallOpts 即 EnginePort 任务形状（缺省路径零映射；
         // pi 边界一次直出由 PiEngine.agentCallToExecuteOptions 承担，逐字段等值由
-        // engines/pi/__tests__/spawn-opts-direct.test.ts 对照表锁定）
+        // inproc pi 引擎目录/__tests__/spawn-opts-direct.test.ts 对照表锁定）
         opts,
         runCtx,
       );

package/src/execution/types.ts

@@ -8,6 +8,14 @@
 //   - TUI 只读 Record/Details 快照，永不持有可变引用
 
 import type { GuiRenderResult } from "@xyz-agent/extension-protocol";
+import type {
+  AgentUsage,
+  AgentUsageTotal,
+  ToolCall,
+  ToolCallResult,
+  Turn,
+  WorktreeHandle,
+} from "@zhushanwen/subagent-engine-sdk";
 
 import type { AgentFailureKind } from "../orchestration/models/types.ts";
 import type { ModelInfo, ModelRegistryLike } from "./model-resolver.ts";
@@ -146,47 +154,35 @@ export type ExecutionMode = "background";
 // Agent 事件流（Core → Record 的唯一更新驱动）
 // ============================================================
 
-/**
- * Pi session.subscribe 上报的事件。Runtime 把它喂给 updateFromEvent。
- *
- * 设计：AgentEvent 携带 updateFromEvent 收口进 record 所需的**全部数据**——
- * tool_end 带 result（供 turn.toolCalls 存完整 ToolCall），无需翻译层旁路累积。
- *
- * ACP 词汇对照（D11 注记级校准，零行为变更；新引擎实现者按本表对齐语义，
- * 详见 docs/architecture/subagent-engine-gui-visibility.md §3.3 D11）：
- *   text_delta / thinking_delta ↔ ACP content blocks（text / thinking）
- *   tool_start / tool_end      ↔ ACP tool_call / tool_call_update
- *   turn_end / message_end     ↔ ACP prompt turn 终态（stop_reason + usage）
- *   compaction                 ↔ ACP session/compaction
- * 本协议以 pi 为语义锚点（D3）——命名不迁移，对照表仅保证未来 AcpEngine 适配器
- * 与跨引擎 trace 映射的翻译成本最低。
- */
-export type AgentEvent =
-  | { type: "tool_start"; toolName: string; args?: unknown }
-  | { type: "tool_end"; toolName: string; args?: unknown; result?: ToolCallResult; isError?: boolean }
-  | { type: "text_delta"; delta: string }
-  | { type: "thinking_delta"; delta: string }
-  | { type: "turn_end"; summary?: string }
-  | { type: "message_end"; usage?: AgentUsage; error?: string }
-  | { type: "compaction" }
-  | { type: "error"; message: string };
-
-/** token 用量（message_end 时由 Core 累加进 record.totalTokens）。 */
-export interface AgentUsage {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  /** 本 message 的成本（USD，来自 SDK usage.cost.total）。可选——无成本数据时缺省。 */
-  cost?: number;
-}
-
-export interface AgentUsageTotal extends AgentUsage {
-  /** 上述四项之和。投影时不再手工求和。 */
-  total: number;
-  /** 累计成本（USD，来自 SdkEvent.message.usage.cost.total 求和）。无成本数据时为 0。 */
-  cost: number;
-}
+// [S4 簇 3 收编] 事件面契约类型单源化（type-only）：AgentEvent / AgentUsage /
+// AgentUsageTotal / ToolCallResult / ToolCall / InternalToolCall / Turn 的本地定义
+// 已删除，自 @zhushanwen/subagent-engine-sdk re-export（SDK protocol/contract-types.ts
+// 是类型闭包 SSOT，core 反向 re-export 保上层消费面——import 方路径零改动；
+// shared/agent-event.ts 转发层链条保持）。结构等价由 protocol-closure.test.ts
+// 断言族守卫。
+//
+// AgentEvent 语义锚定（SDK 侧注释指向本处的对照权威源，勿删）：
+//   - Pi session.subscribe 上报的事件。Runtime 把它喂给 updateFromEvent。
+//   - 设计：AgentEvent 携带 updateFromEvent 收口进 record 所需的**全部数据**——
+//     tool_end 带 result（供 turn.toolCalls 存完整 ToolCall），无需翻译层旁路累积。
+//
+//   ACP 词汇对照（D11 注记级校准，零行为变更；新引擎实现者按本表对齐语义，
+//   详见 docs/architecture/subagent-engine-gui-visibility.md §3.3 D11）：
+//     text_delta / thinking_delta ↔ ACP content blocks（text / thinking）
+//     tool_start / tool_end      ↔ ACP tool_call / tool_call_update
+//     turn_end / message_end     ↔ ACP prompt turn 终态（stop_reason + usage）
+//     compaction                 ↔ ACP session/compaction
+//   本协议以 pi 为语义锚点（D3）——命名不迁移，对照表仅保证未来 AcpEngine 适配器
+//   与跨引擎 trace 映射的翻译成本最低。
+export type {
+  AgentEvent,
+  AgentUsage,
+  AgentUsageTotal,
+  InternalToolCall,
+  ToolCall,
+  ToolCallResult,
+  Turn,
+} from "@zhushanwen/subagent-engine-sdk";
 
 /**
  * eventLog 条目（getEventLog 派生产出的元素）。所有字段 readonly。
@@ -249,69 +245,6 @@ export type SdkEvent = {
   reason?: string;
 };
 
-/** tool 调用结果（tool_execution_end 时累积，含 structured-output 的 details）。 */
-export interface ToolCallResult {
-  content?: unknown[];
-  details?: unknown;
-}
-
-/**
- * tool 调用（导出的纯净数据形状，不含内部状态）。
- *
- *   tool_start 到达但 tool_end 未到时，调用为进行中；一旦 tool_end 到达，
- *   result/isError 填充完成。对外投影（AgentResult.toolCalls / getAllToolCalls）
- *   一律返回此类型——**不泄漏 running/done/failed 内部状态机**。
- *
- * 进行中状态由 execution-record 内部的 `InternalToolCall`（= ToolCall + _status）承载，
- * 只存在于 record.turns[].toolCalls，跨边界导出时由 getAllToolCalls strip _status。
- */
-export interface ToolCall {
-  toolName: string;
-  args?: unknown;
-  result?: ToolCallResult;
-  isError?: boolean;
-}
-
-/**
- * 内部 ToolCall：在 ToolCall 基础上追加 _status 进行中状态标记与 startedTs 时间戳。
- *
- *   running = tool_start 已收到但 tool_end 未到；
- *   done/failed = tool_end 已到。
- *
- * 仅存在于 ExecutionRecord.turns[].toolCalls（Core 内部可变状态）。
- * 跨边界导出（getAllToolCalls → AgentResult.toolCalls / 持久化）由 getAllToolCalls
- * 映射回 ToolCall（丢弃 _status / startedTs），保证导出形状清洁。
- */
-export interface InternalToolCall extends ToolCall {
-  _status: "running" | "done" | "failed";
-  /** tool_start 到达时的墙钟时间戳（Date.now()，ms）。getEventLog 派生 tool 条目 ts 用。 */
-  startedTs: number;
-}
-
-/**
- * 一个 turn 的完整内容（ExecutionRecord.turns[] 的元素）。
- *
- * 收口设计：text/thinking 流式累积**完整内容**（非 100 字切片），
- * toolCalls 存完整 ToolCall（含 result + _status 内部状态）。turn_end 到达后 closed=true，
- * 下次 text/thinking/tool 时开新 turn。
- *
- * eventLog / currentActivity / result 均从 turns[] 派生，不再独立存储。
- */
-export interface Turn {
-  /** 本 turn assistant 正文（text_delta 流式累积，完整）。 */
-  text: string;
-  /** 本 turn 推理（thinking_delta 流式累积，完整）。 */
-  thinking: string;
-  /** 本 turn 工具调用（InternalToolCall：含完整 result + _status 进行中标记）。 */
-  toolCalls: InternalToolCall[];
-  /** 本 turn message_end 的 token 增量（聚合得 totalUsage）。 */
-  usageDelta?: AgentUsage;
-  /** turn_end 是否已到达。false=正在进行；true=已闭合，下次内容开新 turn。 */
-  closed: boolean;
-  /** turn_end 到达时的墙钟时间戳（Date.now()，ms）。getEventLog 派生 turn_end 条目 ts 用。 */
-  closedTs?: number;
-}
-
 /** 一次 session 执行的完整结果。collectResult 产出，写入 Record.outcome。 */
 export interface AgentResult {
   text: string;
@@ -341,19 +274,10 @@ export interface AgentResult {
 // 本 section 先声明 ExecutionRecord 的组成值对象（WorktreeHandle / AliveMarker /
 // PatchResult 等），ExecutionRecord 本体及其文档注释在 section 末尾。
 
-/**
- * worktree handle 值对象。仅 worktree:true 时持有——worktree 是独立维度，
- * 需显式开启，fork alone 不创建 worktree。
- * Object.freeze 守卫保证不可变。
- */
-export interface WorktreeHandle {
-  /** checkout 目录（子 agent 工作目录，tmpdir 下）。 */
-  readonly path: string;
-  readonly branch: string;
-  readonly baseCommit: string;
-  /** 主仓库根目录（cleanup/scan 需要，不再靠路径反推）。 */
-  readonly mainCwd: string;
-}
+// [S4 簇 3 收编] WorktreeHandle 本地定义已删除，自 SDK re-export（原为结构等价
+// 副本，单源化后 SDK contract-types 是唯一定义点；「仅 worktree:true 时持有、
+// Object.freeze 守卫不可变」的语义注释见消费方 worktree-manager / worktree-git-ops）。
+export type { WorktreeHandle } from "@zhushanwen/subagent-engine-sdk";
 
 /** alive marker：子进程存活标记，用于心跳检测和 crash 推断。 */
 export interface AliveMarker {

package/src/execution/ui-channels.ts

@@ -1,216 +1,15 @@
 // src/execution/ui-channels.ts
 //
-// UI channel 提取（marker 解析）+ channel 注册表。
-//
-// channel 是扩展协议自定义的业务路由标识，由 NUL 前缀 marker 标记。
-// 已知 marker（来自 @xyz-agent/extension-protocol）：
-//   - ASK_USER_MARKER   = "\0XYZ_ASK_USER"     走 select method，出现在 title
-//     （options[0] = JSON payload {questions, allowCancel}）
-//   - GUI_WIDGET_MARKER = "\0XYZ_GUI_WIDGET:"  走 setWidget method，出现在 widgetLines[0]
-//     （同行 marker 后紧跟 JSON payload {component}）
-//
-// channel 提取位置随 method 变（.fix-plans/00-master-summary.md §一冲突 2）：
-//   - select   → 从 title 解析 NUL 前缀（payload 从 options[0] 取）
-//   - setWidget → 从 widgetLines[0] 解析 NUL 前缀（payload 从同行 marker 后取）
-//   - 其他 method → 无 channel（返回 {}）
-//
-// channel 名规范化：去 "XYZ_" 命名空间前缀，去尾部 ":"，小写化。
-//   XYZ_ASK_USER   → ask_user
-//   XYZ_GUI_WIDGET → gui_widget
-//
-// 本模块是协议层工具（method/marker 都是协议概念），不感知业务。
-
-/** NUL 前缀字符。Pi extension-protocol 用 NUL（\0）标记控制行，
- *  避免与用户可见文本冲突。 */
-const NUL = "\0";
-
-/** channel 提取结果。channel 无 NUL 前缀、字段缺失、JSON parse 失败时
- *  channel 与 channelPayload 均为 undefined（返回 {}）。 */
-export interface ParsedChannel {
-  /** 规范化后的 channel 名（如 "ask_user"、"gui_widget"）。
-   *  无 marker 或解析失败时为 undefined。 */
-  channel?: string;
-  /** marker 标记的结构化 payload（已 JSON.parse）。
-   *  ask_user: {questions, allowCancel}；gui_widget: {component}。
-   *  payload 来源缺失或 JSON parse 失败时为 undefined（channel 仍可解析）。 */
-  channelPayload?: unknown;
-}
-
-/** parseChannel 入参的最小形状。
- *  method 是判别字段；按 method 不同，对应字段（select 的 title/options、
- *  setWidget 的 widgetLines）可选出现。其他 method 的字段统称 [key:string]。 */
-export interface ExtensionUiRequestLike {
-  method: string;
-  /** select method：title 字段（可能含 ASK_USER_MARKER NUL 前缀）。 */
-  title?: string;
-  /** select method：options 数组（options[0] 可能是 channel payload 的 JSON）。 */
-  options?: string[];
-  /** setWidget method：widgetKey 字段。 */
-  widgetKey?: string;
-  /** setWidget method：widgetLines 数组（widgetLines[0] 可能含 GUI_WIDGET_MARKER）。 */
-  widgetLines?: string[] | undefined;
-  /** 其他 method 的任意字段（容错：允许测试和未来扩展传入额外字段）。 */
-  [key: string]: unknown;
-}
-
-/** channel handler 签名：接收 UiRequest，返回 UiResponse。
- *  具体类型定义在 session-runner.ts（W2 工作），此处用最小形状避免循环依赖。
- *  handler 实现方按 channel 注册，由 session-runner 按 req.channel 分派。 */
-export type ChannelHandler = (req: unknown) => Promise<unknown>;
-
-/** channel 注册表接口。职责单一：只管业务路由，不管排队、不管透传判定。
- *  - register(channel, handler)：注册 channel 对应的 handler（同名覆盖）
- *  - resolve(channel)：取 channel 对应的 handler，未注册返回 undefined
- *  - list()：列举所有已注册 channel 名 */
-export interface UiChannelRegistry {
-  register(channel: string, handler: ChannelHandler): void;
-  resolve(channel: string): ChannelHandler | undefined;
-  list(): string[];
-}
-
-/** 规范化 channel 名。
- *  输入是 NUL 前缀后的字面量（如 "XYZ_ASK_USER"、"XYZ_GUI_WIDGET:"）。
- *  规则：
- *    1. 去 "XYZ_" 命名空间前缀（协议命名空间标识，非业务语义）
- *    2. 去尾部 ":"（GUI_WIDGET 等"行内 payload"型 marker 的分隔符）
- *    3. 小写化（XYZ_ASK_USER → ask_user）
- *
- *  例：
- *    "XYZ_ASK_USER"    → "ask_user"
- *    "XYZ_GUI_WIDGET:" → "gui_widget"
- *    "FOO_BAR"         → "foo_bar"（无 XYZ_ 前缀也容忍，去前缀仅当字面量以 XYZ_ 开头） */
-function normalizeChannelName(markerLiteral: string): string {
-  let name = markerLiteral;
-  // 去 "XYZ_" 命名空间前缀（仅当以此开头）
-  if (name.startsWith("XYZ_")) {
-    name = name.slice("XYZ_".length);
-  }
-  // 去尾部 ":"（行内 payload 型 marker 的分隔符）
-  if (name.endsWith(":")) {
-    name = name.slice(0, -1);
-  }
-  return name.toLowerCase();
-}
-
-/** 从 marker 字面量字符串解析 channel 名。
- *  输入 str 形如 "\0XYZ_ASK_USER"（marker 占满整个字段，payload 在别处）。
- *  无 NUL 前缀返回 undefined。 */
-function parseMarkerFromField(str: string): string | undefined {
-  if (!str.startsWith(NUL)) return undefined;
-  // 去掉 NUL 前缀，取剩余字面量作为 marker literal
-  const literal = str.slice(NUL.length);
-  if (literal === "") return undefined;
-  return normalizeChannelName(literal);
-}
-
-/** 从 marker + 行内 payload 字符串解析 channel 名 + payload。
- *  输入 str 形如 "\0XYZ_GUI_WIDGET:{...json...}"（marker 与 payload 在同一行）。
- *  无 NUL 前缀返回 undefined。
- *  payload 解析失败时不抛（返回 channel 名，payload 由调用方处理）。 */
-function parseInlineMarkerFromField(str: string): { channel: string } | undefined {
-  if (!str.startsWith(NUL)) return undefined;
-  const rest = str.slice(NUL.length);
-  // marker literal 与 payload 的分界：第一个 ":" 或行尾
-  // GUI_WIDGET_MARKER 格式为 "\0XYZ_GUI_WIDGET:" + json，分界是 ":"
-  const colonIdx = rest.indexOf(":");
-  let literal: string;
-  if (colonIdx >= 0) {
-    literal = rest.slice(0, colonIdx + 1); // 含 ":"，normalizeChannelName 会去尾部 ":"
-  } else {
-    literal = rest;
-  }
-  if (literal === "") return undefined;
-  return { channel: normalizeChannelName(literal) };
-}
-
-/** 从 select.title 解析 channel（payload 从 options[0] 取）。
- *  - title 无 NUL 前缀 → undefined
- *  - title 含 marker → channel 名；payload 从 options[0] JSON.parse（失败/缺失 → undefined） */
-function parseFromMarkerString(
-  title: string | undefined,
-  options: string[] | undefined,
-): ParsedChannel {
-  if (title === undefined) return {};
-  const channel = parseMarkerFromField(title);
-  if (channel === undefined) return {};
-  // payload 从 options[0] 取（ask_user 协议：title 是 marker，options[0] 是 JSON payload）
-  let payload: unknown;
-  if (options !== undefined && options.length > 0) {
-    try {
-      payload = JSON.parse(options[0]);
-    } catch {
-      payload = undefined; // JSON parse 失败：不抛，channel 仍解析
-    }
-  }
-  return { channel, channelPayload: payload };
-}
-
-/** 从 setWidget.widgetLines[0] 解析 channel（payload 从同行 marker 后取）。
- *  - widgetLines 缺失/空数组/首行无 NUL 前缀 → undefined
- *  - 首行含 marker → channel 名；payload 从 marker 后的 JSON 取（失败 → undefined） */
-function parseFromMarkerArray(
-  widgetLines: string[] | undefined,
-): ParsedChannel {
-  if (widgetLines === undefined || widgetLines.length === 0) return {};
-  const firstLine = widgetLines[0];
-  if (typeof firstLine !== "string") return {};
-  const parsed = parseInlineMarkerFromField(firstLine);
-  if (parsed === undefined) return {};
-  // payload 从 marker 后的 JSON 取（GUI_WIDGET 协议：marker 与 payload 同行）
-  let payload: unknown;
-  const rest = firstLine.slice(NUL.length);
-  const colonIdx = rest.indexOf(":");
-  if (colonIdx >= 0) {
-    const jsonStr = rest.slice(colonIdx + 1);
-    if (jsonStr !== "") {
-      try {
-        payload = JSON.parse(jsonStr);
-      } catch {
-        payload = undefined; // JSON parse 失败：不抛，channel 仍解析
-      }
-    }
-  }
-  return { channel: parsed.channel, channelPayload: payload };
-}
-
-/** 按 method 分派解析 channel。
- *
- *  - select → 从 title 解析 NUL 前缀（payload 从 options[0]）
- *  - setWidget → 从 widgetLines[0] 解析 NUL 前缀（payload 从同行 marker 后）
- *  - 其他 method → {}（无 channel 提取位置）
- *
- *  边界（均不抛错）：
- *    - title/widgetLines 字段缺失 → {}
- *    - 无 NUL 前缀 → {}
- *    - JSON parse 失败 → channel 仍解析，channelPayload 为 undefined
- *
- *  @param req ExtensionUiRequestLike（method + 对应字段）
- *  @returns ParsedChannel（channel/channelPayload 可选） */
-export function parseChannel(req: ExtensionUiRequestLike): ParsedChannel {
-  switch (req.method) {
-    case "select":
-      return parseFromMarkerString(req.title, req.options);
-    case "setWidget":
-      return parseFromMarkerArray(req.widgetLines);
-    default:
-      return {};
-  }
-}
-
-/** 创建 channel 注册表实例。
- *  进程级单例（通常由 SubagentService 持有一个实例，跨所有子进程共享）。
- *  register 同名 channel 会覆盖旧 handler。 */
-export function createUiChannelRegistry(): UiChannelRegistry {
-  const handlers = new Map<string, ChannelHandler>();
-  return {
-    register(channel: string, handler: ChannelHandler): void {
-      handlers.set(channel, handler);
-    },
-    resolve(channel: string): ChannelHandler | undefined {
-      return handlers.get(channel);
-    },
-    list(): string[] {
-      return Array.from(handlers.keys());
-    },
-  };
-}
+// UI channel 提取（marker 解析）+ channel 注册表的 re-export shim：实现体单源
+// @zhushanwen/subagent-engine-sdk（自本文件逐字等价移入 SDK，round1-reuse R1；
+// core → SDK 边界正向合法）。core 内消费方（channel-registry-access /
+// ui-request-handler-factory）import 路径保持不变，barrel 导出面零变化。
+
+export {
+  type ChannelHandler,
+  createUiChannelRegistry,
+  type ExtensionUiRequestLike,
+  parseChannel,
+  type ParsedChannel,
+  type UiChannelRegistry,
+} from "@zhushanwen/subagent-engine-sdk";

package/src/execution/ui-request-handler-factory.ts

@@ -2,10 +2,13 @@
 //
 // UI 请求 handler 工厂（透传 + 排队总控）。
 //
-// 按 ctx.mode（ExtensionMode）创建合适的 UiRequestHandler，让 SubagentService 持有后
-// 经 session-runner 透传给子进程的 extension_ui_request。本模块是「handler 注入链路」的
-// 组装点：把 channel registry（业务路由）+ dialog queue（L2 跨子进程串行）+ mode 分流
-//（TUI/GUI/headless）粘合成一个 handler。
+// 按 ctx.mode（ExtensionMode）创建合适的 UiRequestHandler，SubagentService 持有后经
+// host-ui-endpoint 登记处注入协议客户端——引擎进程的 extension_ui_request 经
+// host/askUser 反向通道到达本 handler（[W3] inproc L1 队列 inproc UI 请求队列（已删） 随
+// inproc pi 引擎目录 删除消亡，「run 生命周期内闭包队列」语义由引擎包内等价物 +
+// 协议应答路径承接）。本模块是「handler 注入链路」的组装点：把 channel registry
+//（业务路由）+ dialog queue（L2 跨子进程串行）+ mode 分流（TUI/GUI/headless）
+// 粘合成一个 handler。
 //
 // 设计依据（.fix-plans/00-master-summary.md）：
 //   - §一冲突 2「透传矩阵」：

package/src/execution/ui-request-observability.ts

@@ -9,9 +9,9 @@ import type { ExtensionMode } from "./host-mode.ts";
 
 const logger = getLogger("subagents");
 
-// ── 跨模块桥接（ui-request-queue 无 ctx.service 引用时走这里） ──
+// ── 跨模块桥接（inproc UI 请求队列（已删） 无 ctx.service 引用时走这里） ──
 //
-// ui-request-queue.handleUiRequest 在 ctx.uiRequestHandler 缺失时需要触发去重告警，
+// inproc UI 请求队列 handleUiRequest（已删） 在 ctx.uiRequestHandler 缺失时需要触发去重告警，
 // 但 SessionRunnerContext 不持有 service 引用（改 ctx 签名超出本组 4 文件范围）。
 // 解法：SubagentService 构造后调 registerGlobalObservability(this.uiObservability)
 // 把进程单例挂到 globalThis；queue 走 notifyMissingHandlerGlobal 路径调到同一实例，

package/src/execution/workflow-state-root.ts

@@ -0,0 +1,67 @@
+// src/execution/workflow-state-root.ts
+//
+// [F-1 修复] pi 宿主 WorkflowRun state 目录解析（与 pi 壳 JsonlRunStore 同源布局）。
+//
+// 为什么存在：pi 宿主 workflow 域的 run state 真实落盘 = JsonlRunStore 的
+// `<sessionDir>/workflow-state/<runId>.jsonl`，sessionDir 由 extension 侧
+// `extensions/universal/subagent-workflow/src/session-lifecycle.ts` 的
+// resolveSessionDir() 推导。core 侧两个读侧装配点（round-supervisor 的注册对账
+// sweep、idle-gc 的 WorkflowRun GC）曾用 FileRunStore 缺省根
+// `<dataRoot>/workflow-state`（zcode 宿主布局）——两目录生产不相交，读侧恒 ENOENT：
+// sweep 把活跃 run 判 missing 补注销（误注销活跃 run），WorkflowRun GC 恒空转。
+//
+// core 不能 import extension——本文件按 resolveSessionDir 同规则在 core 侧重写推导，
+// 两处注释互指锚定（[同步纪律] 改 sessionDir 布局时必须同批改本文件与
+// session-lifecycle.ts，漂移信号 = sweep 补注销活跃 run / GC 空转）。
+//
+// agentDir 推导锚定 pi 实装版 0.84.4 dist config.js getAgentDir：
+// `process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent")`
+// （ENV_AGENT_DIR = PI_CODING_AGENT_DIR、CONFIG_DIR_NAME = piConfig.configDir = ".pi"，
+// 无 piConfig.name 覆盖）。pi 升级若改 getAgentDir 语义 → 本推导漂移，可见信号同上。
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** pi SDK getAgentDir 的 env 覆盖通道（实装版 dist config.js ENV_AGENT_DIR）。 */
+const PI_AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+
+/** pi SDK 缺省 agent 目录分量（实装版 dist config.js：CONFIG_DIR_NAME + "agent"）。 */
+const DEFAULT_PI_AGENT_DIR_PARTS = [".pi", "agent"] as const;
+
+/** resolvePiWorkflowStateDir 的注入面（测试用；生产缺省全走真实推导）。 */
+export interface PiWorkflowStateDirOptions {
+  /** agent 配置目录覆盖（缺省 = PI_CODING_AGENT_DIR env 或 ~/.pi/agent）。 */
+  agentDir?: string;
+  /** cwd 覆盖（缺省 process.cwd()——对齐 session-lifecycle 用进程 cwd 而非 ctx.cwd）。 */
+  cwd?: string;
+}
+
+/**
+ * 解析 pi 宿主 WorkflowRun state 目录（`<sessionDir>/workflow-state`）。
+ *
+ * sessionDir 推导（与 session-lifecycle.resolveSessionDir 逐段同构，见文件头注）：
+ *   - cwd-slug = `--<cwd 去开头分隔符、`/`→`-`>--`（extension 侧字面规则——core 的
+ *     encodeCwd 额外折叠 `:` 与 `\`，与建目录方不一致，此处不共用）；
+ *   - `<agentDir>/sessions/<slug>` 目录存在则用之（该目录由 workflow 域首次落盘
+ *     创建——cwd 有过 workflow run 才存在），否则回退 agentDir 根
+ *     （JsonlRunStore 的 mkdir recursive 使首写直接落 agentDir 根，两侧探测一致）。
+ *
+ * 只读解析（existsSync 探测），无目录创建副作用——与 FileRunStore 的 save 侧
+ * mkdir 职责分离。
+ */
+export function resolvePiWorkflowStateDir(opts?: PiWorkflowStateDirOptions): string {
+  const agentDir = opts?.agentDir ?? resolvePiAgentDir();
+  const cwd = opts?.cwd ?? process.cwd();
+  const sessionSlug = `--${cwd.replace(/^\//, "").replace(/\//g, "-")}--`;
+  const sessionScopedDir = join(agentDir, "sessions", sessionSlug);
+  const sessionDir = existsSync(sessionScopedDir) ? sessionScopedDir : agentDir;
+  return join(sessionDir, "workflow-state");
+}
+
+/** pi agent 目录（getAgentDir 同语义；推导锚定见文件头注）。 */
+function resolvePiAgentDir(): string {
+  const envDir = process.env[PI_AGENT_DIR_ENV];
+  if (envDir !== undefined && envDir !== "") return envDir;
+  return join(homedir(), ...DEFAULT_PI_AGENT_DIR_PARTS);
+}

package/src/execution/worktree-git-ops.ts

@@ -25,6 +25,8 @@
 // 职责，不在纯内核复刻——git index.lock 冲突瞬时态正好落降级路径②，而非内核故障。
 
 import { execFile } from "node:child_process";
+
+import { buildOutboundChildEnv } from "@zhushanwen/subagent-engine-sdk";
 import * as fs from "node:fs";
 
 import { getLogger } from "../core/logger.ts";
@@ -115,6 +117,9 @@ export function gitRun(
         timeout: opts.timeout ?? GIT_TIMEOUT_MS,
         ...(opts.maxBuffer !== undefined ? { maxBuffer: opts.maxBuffer } : {}),
         encoding: "utf-8",
+        // 出站卫生（R3 MF-C，impl-plan §2.12）：同 worktree-manager.ts gitRunAsync——
+        // deny 键不进 git 子进程，git hooks 后代不再可能消费 deny 键。
+        env: buildOutboundChildEnv({ parentEnv: process.env }),
       },
       (err, stdout, stderr) => {
         if (err) {

package/src/execution/worktree-manager.ts

@@ -23,6 +23,8 @@
 // 声称的「tmpdir + 分支对账兜底」由此成为代码。
 
 import { execFile } from "node:child_process";
+
+import { buildOutboundChildEnv } from "@zhushanwen/subagent-engine-sdk";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -713,7 +715,15 @@ export class WorktreeManager {
         execFile(
           "git",
           args,
-          { cwd: opts.cwd, timeout: opts.timeout ?? GIT_TIMEOUT_MS, encoding: "utf-8" },
+          {
+            cwd: opts.cwd,
+            timeout: opts.timeout ?? GIT_TIMEOUT_MS,
+            encoding: "utf-8",
+            // 出站卫生（R3 MF-C，impl-plan §2.12）：deny 键不进 git 子进程——
+            // git hooks 等后代不再可能消费生命周期标志 / WS 令牌。SDK 版缺省
+            // 全量继承父 env + deny 剥除，行为差异仅 deny 键剥除。
+            env: buildOutboundChildEnv({ parentEnv: process.env }),
+          },
           (err, stdout, stderr) => {
             if (err) {
               const execErr = err as Error & { code?: unknown; killed?: boolean; signal?: string };