@zhushanwen/subagent-core 0.5.1 → 0.7.0

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 };

package/src/index.ts

@@ -2,8 +2,8 @@
  * @zhushanwen/subagent-core — 公共 API barrel（D5 定稿 + post-convergence B-2 扩面）
  *
  * 公共 API 面 = 本文件导出 + package.json exports 的语义子入口
- * （./engines/zcode/reader、./engines/zcode/constants、./engine/paths、./relay-env）
- * + ./workflows/* 资产子入口。exports 面即 semver 契约（D5）：收窄不放宽——
+ * （./engine/paths、./engine/engine-discovery-scan、./relay-env——[W11/H3] 引擎
+ * 子入口 ./engines/zcode/* 已随内建引擎删除）+ ./workflows/* 资产子入口。exports 面即 semver 契约（D5）：收窄不放宽——
  * 新增导出走 minor，本文件刻意不使用 `export *`，逐名列出以使 diff 可审。
  * 内部实现细节（error-recovery / execute-agent-call / worker-script-builder 等
  * engine 编排件）不经 barrel 导出；host-surface 扩面（zsw 回接 U0，2026-08-30）
@@ -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.5.1";
+export const CORE_PACKAGE_VERSION = "0.7.0";
 
 // ── 宿主端口接线面（core/）────────────────────────────────────
 // HostServices：dataRoot / log / discoveryRoots 端口 + configureCore 注入；
@@ -88,34 +88,54 @@ export {
   type EngineRoutingInput,
   type EngineRoutingSource,
 } from "./execution/engine/routing.ts";
+// [W8 补扫接线面] setEngineDiscoveryRescanOptions：宿主登记 hasEngineWithRescan 的
+// 补扫发现参数（与 session_start 发现扫描同源）；壳消费 = runtime
+// subagent-engine-history 的 ensureRuntimeEngineWiring。
+export { setEngineDiscoveryRescanOptions } from "./execution/engine/routing.ts";
 
 // ── 引擎注册 / 发现与进程面（execution/engine）────────────────
 // 组合根 index.ts 接线消费（registerXxx 引擎注册、syncEnginesFile engines 文件
 // 同步、killAllSpawnedChildren session 派生进程兜底清理）。
 export { syncEnginesFile } from "./execution/engine/engine-discovery.ts";
-export { registerPiEngine } from "./execution/engine/engines/pi/registration.ts";
-export { killAllSpawnedChildren } from "./execution/engine/engines/pi/session-runner.ts";
-export { registerZcodeEngine } from "./execution/engine/engines/zcode/registration.ts";
+// [W11/DoD#5] registerPiEngine（inproc 'pi' 注册）已删；[W3 chat 域收口] chat 域 inproc
+// 引擎（inproc pi 引擎目录）与 SubagentService 自持 DI 实例一并删除——registry 'pi' 由三级发现
+// 装载 cli descriptor，chat 轮次与 run 域同路经协议客户端发往 pi-subagent-cli 引擎进程
+// （G1：pi 引擎单一 CLI 形态，core 壳侧零内建引擎）。
+// [W8 D8 薄壳] killAllSpawnedChildren：扩展 index.ts / zsw runner-core.js 的业务调用点
+// 零改动。语义（[F-7 注释纠偏，如实口径]）= **仅镜像记账**——core 侧 spawnedChildren
+// 镜像整体清空（engine/host/spawned-children.ts 公共面），不发任何进程信号；
+// 子进程活在引擎进程内，其回收链 = ① stdin-EOF 自灭（宿主退出 / EngineClient 销毁
+// → 引擎进程 stdin 断源自灭，正常路径）；② disposeEngines()（registry）显式触发全部
+// 已实例化引擎 dispose（cli 形态 = RemoteEngine.dispose → EngineClient 有界收口）——
+// 该入口为宿主 shutdown 链预留，现无生产接线。subagent-workflow 扩展的
+// reapSpawnedChildrenOnShutdown（process hook 调本函数）因此同为镜像置死 no-op，
+// 不构成真实收割（现状登记，workflow 包生产码不动）。
+export { killAllSpawnedChildren } from "./execution/engine/host/spawned-children.ts";
+
+// [W8 D8 兼容公共面薄壳]（设计 §3.6 D8 表）：registerZcodeEngine 确保cli descriptor
+// 注册（vendored 相对定位，失败回退 inproc 过渡）+ engineDataDir 记入；createZcodeEngine
+// 返回 RemoteEngine('zcode')（deps → 协议客户端映射，sources 不跨进程）。实现见
+// execution/engine/d8-compat.ts——engines/zcode/registration.ts 的同名符号不再经
+// barrel 导出（inproc 实现保留至 W11，仅内部测试/过渡消费）。
+export {
+  createZcodeEngine,
+  registerZcodeEngine,
+  type D8CompatZcodeEngineDeps,
+} from "./execution/engine/d8-compat.ts";
 
-// pi session-runner 内核件（merge 裁决：dev 侧旧深路径 execution/session-runner.ts
-// 终态已不存在，符号随 u-2a 迁移至 engine/engines/pi/session-runner.ts）：
 // maxTurnsToWatchdogMs 为 maxTurns→watchdog 毫秒换算（U3/U4 / D7，floor 语义
-// 文档化——两宿主预算一致性 S2 的函数级锚点）；killRecordChildWithEscalation 为
-// 单 record 子进程升级回收（session 派生进程清理的细粒度入口）。
+// 文档化——两宿主预算一致性 S2 的函数级锚点；[W3] 定义收敛在 pi-host-binding，
+// 原 inproc session-runner（已删） 定义随删件消亡）；killRecordChildWithEscalation 为
+// 单 record 子进程终止的镜像记账入口（[W3] 实际终止在引擎进程内经协议承载）。
 export {
   killRecordChildWithEscalation,
-  maxTurnsToWatchdogMs,
-} from "./execution/engine/engines/pi/session-runner.ts";
+} from "./execution/engine/host/spawned-children.ts";
+export { maxTurnsToWatchdogMs } from "./execution/engine/host/pi-host-binding.ts";
 
-// zcode 引擎注册面：registerZcodeEngine 把 'zcode' 引擎登记进 registry（组合根
-// 职责，幂等，上方已导出）；createZcodeEngine 为 DI 工厂（测试/宿主注入 deps）。
-// ZcodeEngineDeps 经 registration.ts 的 re-export 导出（避免与 zcode-engine.ts 双源）。
-export { createZcodeEngine } from "./execution/engine/engines/zcode/registration.ts";
-export type { ZcodeEngineDeps } from "./execution/engine/engines/zcode/registration.ts";
-
-// ZcodeTaskShapeError：zcode 任务形状错误类（instanceof 分流用）——
-// execution-runtime-face.test.ts:29 消费，barrel 保留导出（engines 域 A1 裁决）。
-export { ZcodeTaskShapeError } from "./execution/engine/engines/zcode/zcode-engine.ts";
+// zcode 引擎注册面（[W8 D8 薄壳] createZcodeEngine 已上移 d8-compat——上方导出）。
+// [W11 收口] ZcodeEngineDeps 与 D8CompatZcodeEngineDeps 合并为别名（zsw 调用面的
+// deps 形状契约保持）；barrel 不导出引擎错误类（引擎错误归各引擎包自持）。
+export type { ZcodeEngineDeps } from "./execution/engine/d8-compat.ts";
 
 // 引擎注册表原语 + 引擎感知提示面：engine-awareness injector 消费。
 export {
@@ -132,6 +152,11 @@ export {
 // 子入口（D9：每条子入口 bundle 多一份 host-services 副本）。
 export { parseEngineHandle } from "./execution/engine/common/session-view-types.ts";
 export { readSubagentHistoryMessages } from "./execution/engine/common/session-view-service.ts";
+// [W8] registerNativeSessionReader：runtime 成为协议客户端的①级接入点——宿主把
+// 「协议 read」注册为引擎原生 reader，core 三级降级链（①协议 read → ②journal →
+// ③outcome）自动编排（含投影），宿主零投影代码。壳消费 = runtime
+// subagent-engine-history 的协议 reader 注册。
+export { registerNativeSessionReader } from "./execution/engine/common/session-view-service.ts";
 
 // ── 执行域（execution/）──────────────────────────────────────
 // types.ts 领域类型族：record / 响应 / 列表项等 subagent 域公共契约（壳消费最高频面，
@@ -262,7 +287,7 @@ export {
 
 // 错误类型族（error-recovery.ts 计划路径实测不存在，实测散布于下列源文件）：
 // resurrect/fork-depth/dirty-worktree 为动作层守卫抛出点（types.ts），
-// GitRunError 见 worktree 内核组裁决，ZcodeTaskShapeError 见引擎注册面。
+// GitRunError 见 worktree 内核组裁决。
 export {
   DirtyWorktreeError,
   ForkDepthExceededError,
@@ -313,14 +338,14 @@ export {
 } from "./execution/concurrency-pool.ts";
 
 // 模型引用切分原语（U1 契约面批件）：provider/model 引用切分与缺省值（两宿主
-// maxTurns/model 换算同源）；实现体内聚 zcode preparer/constants 不挪文件，
-// barrel re-export（§5.3）。
+// maxTurns/model 换算同源）。[W11/H2] 实现体随 engines/zcode 删除迁至
+// shared/zcode-model-ref.ts（宿主侧原语，与引擎包各自单源）。
 export {
   DEFAULT_PROVIDER_ID,
   hasApiKey,
   splitZcodeModelRef,
-} from "./execution/engine/engines/zcode/preparer.ts";
-export { ZCODE_FALLBACK_DEFAULT_MODEL } from "./execution/engine/engines/zcode/constants.ts";
+  ZCODE_FALLBACK_DEFAULT_MODEL,
+} from "./shared/zcode-model-ref.ts";
 
 // ── worktree git 内核（U5 / D5）───────────────────────────────
 // git 语义纯函数单源：保真读（gitRun）、SafeId 校验、dirty 谓词、
@@ -484,10 +509,14 @@ export type {
 // LifecycleDeps.store 用；pi 壳继续用 session 锚定的 JsonlRunStore。
 // DEFAULT_* 两常量：壳 jsonl-run-store.ts 生产消费（D3 判定进 barrel），
 // u-2c 删 ./* 通配后深路径仅测试侧 vitest alias 可解析，生产消费必须走 barrel。
+// pruneStateFilesBeyondCap：磁盘 retention 裁剪单源（S4-A7）——壳 jsonl-run-store
+// 的同构私有实现已删，改 import 本函数并注入自身 logger tag / toErrorMessage。
 export {
   DEFAULT_SAVE_MIN_INTERVAL_MS,
   DEFAULT_STATE_MAX_RUNS,
   FileRunStore,
+  pruneStateFilesBeyondCap,
+  type PruneStateDeps,
 } from "./orchestration/file-run-store.ts";
 
 // ── 快照 codec（U8 / D4）──────────────────────────────────────

package/src/orchestration/__tests__/config-loader.test.ts

@@ -102,7 +102,7 @@ beforeEach(async () => {
 
 afterEach(async () => {
   vi.useRealTimers();
-  if (ws) await rm(ws.root, { recursive: true, force: true });
+  if (ws) await rm(ws.root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 /** 过滤掉可能从真实 homedir 泄漏进来的 user-agents 文件，只保留临时工作区内结果。 */

package/src/orchestration/__tests__/execute-agent-call.test.ts

@@ -12,7 +12,7 @@ import {
   isDeterministicSchemaFailureMsg,
   isStaleContextErrorMsg,
   STALE_CONTEXT_PATTERNS,
-} from "../../execution/engine/engines/pi/output-collector.ts";
+} from "@zhushanwen/pi-subagent-cli";
 import { executeAgentCall } from "../execute-agent-call.ts";
 import { AgentCall } from "../models/agent-call.ts";
 import { Budget } from "../models/budget.ts";

package/src/orchestration/__tests__/file-run-store-prune.test.ts

@@ -41,7 +41,7 @@ beforeEach(() => {
 
 afterEach(() => {
   resetCoreForTests();
-  rmSync(dataRoot, { recursive: true, force: true });
+  rmSync(dataRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   delete process.env[ENV_NAME];
 });
 

package/src/orchestration/__tests__/file-run-store-throttle.test.ts

@@ -39,7 +39,7 @@ beforeEach(() => {
 afterEach(() => {
   vi.useRealTimers();
   resetCoreForTests();
-  rmSync(dataRoot, { recursive: true, force: true });
+  rmSync(dataRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 /** 构造可持久化的 WorkflowRun（对齐 file-run-store.test.ts makeRun 模式）。 */

package/src/orchestration/__tests__/review-fix-loop-scriptpath-failfast.test.ts

@@ -67,7 +67,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  rmSync(sandboxDir, { recursive: true, force: true });
+  rmSync(sandboxDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 /** cwd 植入件：若任一脚本回退 process.cwd() 加载依赖，本文件被 require 即抛标记错误。 */

package/src/orchestration/__tests__/script-generate.test.ts

@@ -168,7 +168,7 @@ describe("generateWorkflowScript 校验闸（文案逐字对齐 pi 现版）", (
       );
       expect(existsSync(join(tmpRoot, "esm-wf.js"))).toBe(false);
     } finally {
-      rmSync(tmpRoot, { recursive: true, force: true });
+      rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -216,7 +216,7 @@ describe("generateWorkflowScript 校验闸（文案逐字对齐 pi 现版）", (
       }
       expect(existsSync(join(tmpRoot, "bad-wf.js"))).toBe(false);
     } finally {
-      rmSync(tmpRoot, { recursive: true, force: true });
+      rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -247,7 +247,7 @@ describe("generateWorkflowScript 合法样本落 tmp", () => {
       expect(existsSync(r.path)).toBe(true);
       expect(readFileSync(r.path, "utf-8")).toBe(PI_META_VALID);
     } finally {
-      rmSync(tmpRoot, { recursive: true, force: true });
+      rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -259,7 +259,7 @@ describe("generateWorkflowScript 合法样本落 tmp", () => {
       if (!r.ok) throw new Error(r.error);
       expect(existsSync(r.path)).toBe(true);
     } finally {
-      rmSync(tmpRoot, { recursive: true, force: true });
+      rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -274,7 +274,7 @@ describe("generateWorkflowScript 合法样本落 tmp", () => {
       expect(existsSync(r.path)).toBe(true);
     } finally {
       cwdSpy.mockRestore();
-      rmSync(fakeCwd, { recursive: true, force: true });
+      rmSync(fakeCwd, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 });

package/src/orchestration/__tests__/skill-discovery.test.ts

@@ -73,8 +73,8 @@ beforeEach(() => {
 afterEach(() => {
   vi.restoreAllMocks();
   resetCoreForTests();
-  rmSync(projRoot, { recursive: true, force: true });
-  rmSync(homeRoot, { recursive: true, force: true });
+  rmSync(projRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  rmSync(homeRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 /** mkdir -p（目录存在即 resolveSkillPath 命中——检查的是目录而非 SKILL.md）。 */