@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/ui-channels.d.ts

@@ -0,0 +1,60 @@
+/** channel 提取结果。channel 无 NUL 前缀、字段缺失、JSON parse 失败时
+ *  channel 与 channelPayload 均为 undefined（返回 {}）。 */
+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]。 */
+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 分派。 */
+type ChannelHandler = (req: unknown) => Promise<unknown>;
+/** channel 注册表接口。职责单一：只管业务路由，不管排队、不管透传判定。
+ *  - register(channel, handler)：注册 channel 对应的 handler（同名覆盖）
+ *  - resolve(channel)：取 channel 对应的 handler，未注册返回 undefined
+ *  - list()：列举所有已注册 channel 名 */
+interface UiChannelRegistry {
+    register(channel: string, handler: ChannelHandler): void;
+    resolve(channel: string): ChannelHandler | undefined;
+    list(): string[];
+}
+/** 按 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 可选） */
+declare function parseChannel(req: ExtensionUiRequestLike): ParsedChannel;
+/** 创建 channel 注册表实例。
+ *  进程级单例（通常由 SubagentService 持有一个实例，跨所有子进程共享）。
+ *  register 同名 channel 会覆盖旧 handler。 */
+declare function createUiChannelRegistry(): UiChannelRegistry;
+
+export { type ChannelHandler, type ExtensionUiRequestLike, type ParsedChannel, type UiChannelRegistry, createUiChannelRegistry, parseChannel };

package/dist/ui-channels.js

@@ -0,0 +1,9 @@
+import {
+  createUiChannelRegistry,
+  parseChannel
+} from "./chunk-7I4XGL5J.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  createUiChannelRegistry,
+  parseChannel
+};

package/dist/ui-types.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/ui-types.ts
+var ui_types_exports = {};
+module.exports = __toCommonJS(ui_types_exports);

package/dist/ui-types.d.cts

@@ -0,0 +1,62 @@
+/** Pi extension_ui_request 的方法枚举（dialog + fire-and-forget 两类）。
+ *  dialog 类：select/confirm/input/editor（占输入焦点，等响应）。
+ *  fire-and-forget 类：notify/setStatus/setWidget/setTitle/set_editor_text（纯展示/写入）。
+ *  (string & {}) 兜底：Pi 未来新增 method 或未知 method 走字符串字面量类型。 */
+type UiMethod = "select" | "confirm" | "input" | "editor" | "notify" | "setStatus" | "setWidget" | "setTitle" | "set_editor_text" | (string & {});
+/** UI 请求（session-runner 构造后传给 handler）。
+ *
+ *  method 是判别字段，决定排队策略（dialog 排队）和业务路由（channel 分发）。
+ *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由 session-runner 从
+ *  ExtensionUiRequest 平铺构造）。channel/channelPayload 由 parseChannel 填充。
+ *
+ *  契约来源：.fix-plans/00-master-summary.md §二 2.2。 */
+interface UiRequest {
+    /** Pi rpc-types.ts 的 method（select/confirm/input/editor 为 dialog 类）。 */
+    method: UiMethod;
+    /** 请求 id（从 extension_ui_request envelope 顶层提取，用于 response 关联）。 */
+    id: string;
+    title?: string;
+    options?: string[];
+    message?: string;
+    placeholder?: string;
+    prefill?: string;
+    notifyType?: string;
+    statusKey?: string;
+    statusText?: string | undefined;
+    widgetKey?: string;
+    widgetLines?: string[] | undefined;
+    widgetPlacement?: "aboveEditor" | "belowEditor";
+    text?: string;
+    timeout?: number;
+    /** channel 名（从 method 对应字段的 NUL 前缀解析）。
+     *  select → 从 title 解析；setWidget → 从 widgetLines[0] 解析；其他 → undefined。
+     *  已知值："ask_user"（select）、"gui_widget"（setWidget）。handler 按 channel 分发。 */
+    channel?: string;
+    /** channel 解析后的结构化 payload（已 JSON.parse）。
+     *  ask_user: {questions, allowCancel}；gui_widget: {component}；无 channel: undefined。 */
+    channelPayload?: unknown;
+    /** 内部元数据字段：发起该 UI 请求的子进程 pid（由 session-runner.handleUiRequest 从
+     *  child.pid 填入）。L2 队列据此关联 rejectChildDialogs（child close 时批量 reject）。
+     *  下划线前缀表示内部字段，非 Pi 协议字段，不参与 stdin 回写。 */
+    _childPid?: number;
+}
+/** UI 响应（handler 返回，session-runner 按 shape 回写 stdin）。
+ *  - {value}: select/input/editor 的答案
+ *  - {confirmed}: confirm 的答案
+ *  - {cancelled}: 取消（child close / handler 抛错 / 用户取消）
+ *  - {ack}: fire-and-forget（当前不透传到 TUI，留作协议完整） */
+type UiResponse = {
+    value: string;
+} | {
+    confirmed: boolean;
+} | {
+    cancelled: true;
+} | {
+    ack: true;
+};
+/** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
+ *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
+ *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */
+type UiRequestHandler = (req: UiRequest) => Promise<UiResponse>;
+
+export type { UiMethod, UiRequest, UiRequestHandler, UiResponse };

package/dist/ui-types.d.ts

@@ -0,0 +1,62 @@
+/** Pi extension_ui_request 的方法枚举（dialog + fire-and-forget 两类）。
+ *  dialog 类：select/confirm/input/editor（占输入焦点，等响应）。
+ *  fire-and-forget 类：notify/setStatus/setWidget/setTitle/set_editor_text（纯展示/写入）。
+ *  (string & {}) 兜底：Pi 未来新增 method 或未知 method 走字符串字面量类型。 */
+type UiMethod = "select" | "confirm" | "input" | "editor" | "notify" | "setStatus" | "setWidget" | "setTitle" | "set_editor_text" | (string & {});
+/** UI 请求（session-runner 构造后传给 handler）。
+ *
+ *  method 是判别字段，决定排队策略（dialog 排队）和业务路由（channel 分发）。
+ *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由 session-runner 从
+ *  ExtensionUiRequest 平铺构造）。channel/channelPayload 由 parseChannel 填充。
+ *
+ *  契约来源：.fix-plans/00-master-summary.md §二 2.2。 */
+interface UiRequest {
+    /** Pi rpc-types.ts 的 method（select/confirm/input/editor 为 dialog 类）。 */
+    method: UiMethod;
+    /** 请求 id（从 extension_ui_request envelope 顶层提取，用于 response 关联）。 */
+    id: string;
+    title?: string;
+    options?: string[];
+    message?: string;
+    placeholder?: string;
+    prefill?: string;
+    notifyType?: string;
+    statusKey?: string;
+    statusText?: string | undefined;
+    widgetKey?: string;
+    widgetLines?: string[] | undefined;
+    widgetPlacement?: "aboveEditor" | "belowEditor";
+    text?: string;
+    timeout?: number;
+    /** channel 名（从 method 对应字段的 NUL 前缀解析）。
+     *  select → 从 title 解析；setWidget → 从 widgetLines[0] 解析；其他 → undefined。
+     *  已知值："ask_user"（select）、"gui_widget"（setWidget）。handler 按 channel 分发。 */
+    channel?: string;
+    /** channel 解析后的结构化 payload（已 JSON.parse）。
+     *  ask_user: {questions, allowCancel}；gui_widget: {component}；无 channel: undefined。 */
+    channelPayload?: unknown;
+    /** 内部元数据字段：发起该 UI 请求的子进程 pid（由 session-runner.handleUiRequest 从
+     *  child.pid 填入）。L2 队列据此关联 rejectChildDialogs（child close 时批量 reject）。
+     *  下划线前缀表示内部字段，非 Pi 协议字段，不参与 stdin 回写。 */
+    _childPid?: number;
+}
+/** UI 响应（handler 返回，session-runner 按 shape 回写 stdin）。
+ *  - {value}: select/input/editor 的答案
+ *  - {confirmed}: confirm 的答案
+ *  - {cancelled}: 取消（child close / handler 抛错 / 用户取消）
+ *  - {ack}: fire-and-forget（当前不透传到 TUI，留作协议完整） */
+type UiResponse = {
+    value: string;
+} | {
+    confirmed: boolean;
+} | {
+    cancelled: true;
+} | {
+    ack: true;
+};
+/** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
+ *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
+ *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */
+type UiRequestHandler = (req: UiRequest) => Promise<UiResponse>;
+
+export type { UiMethod, UiRequest, UiRequestHandler, UiResponse };

package/dist/ui-types.js

@@ -0,0 +1 @@
+import "./chunk-2DIMPZCQ.js";

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@zhushanwen/subagent-engine-sdk",
+  "version": "0.2.0",
+  "description": "Engine-side SDK for the subagent engine protocol: NDJSON stdio contract types, engine primitives (schema emulation, nesting guard, kill chain, journal replay projection, data-dir/paths resolution) — the shared contract root between subagent-core and engine CLI packages (engines import SDK only, never core)",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "import": {
+        "types": "./dist/protocol/index.d.ts",
+        "default": "./dist/protocol/index.js"
+      },
+      "require": {
+        "types": "./dist/protocol/index.d.cts",
+        "default": "./dist/protocol/index.cjs"
+      },
+      "default": "./dist/protocol/index.js"
+    }
+  },
+  "$comment": "W1 骨架（docs/design/subagent-engine-protocolization.impl-plan.md §2.1）。双形态同 subagent-core 先例（D4）：workspace 消费走 import 条件 -> src；npm 消费走 publishConfig -> dist。exports 面先收窄到 ./ 与 ./protocol（exports = semver 契约，收窄不放宽；引擎包 W5/W7 消费经主 barrel）。协议版本独立于包版本：ENGINE_PROTOCOL_VERSION = 1（src/protocol/engine-protocol.ts）。不变量：本包禁止 import @zhushanwen/subagent-core（守卫 .githooks/check-engine-sdk-boundary.mjs）。src/env.ts 与 src/spawn.ts 是 W12 领地（impl-plan §2.12），本单元仅空骨架占位。tsup entry 逐模块具名登记（§2.1 末行），新增模块必须同步登记。",
+  "files": [
+    "src/",
+    "!src/__tests__",
+    "dist/"
+  ],
+  "dependencies": {
+    "ajv": "^8.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/best-effort.ts

@@ -0,0 +1,37 @@
+// src/best-effort.ts
+//
+// best-effort IO 清理的错误吞咽 helper 单源（round1-reuse R11 微副本收编，实现体
+// 自 core src/execution/best-effort.ts 迁移；pi 引擎包 best-effort.ts 副本自本模块
+// re-export 收编。core 版保留自持：其 logger 经 configureCore HostServices 通道解析，
+// 与 SDK LoggerSink 通道是真差异，非可消副本）。
+//
+// 用途：sidecar 写入 / worktree remove / alive marker 删除等次要 IO，失败不影响
+// 主流程（session 已完成或正在收尾）。这类 catch 故意吞错——但 taste/no-silent-catch
+// 规则禁止空 catch 或仅 console 的 catch。本 helper 提供一条「实质调用语句」让
+// catch 合规，同时把错误记录到 debug/error 便于排查（经共享 logger 路由，不裸 console）。
+
+import { getLogger } from "./logger.ts";
+
+const logger = getLogger("subagents");
+
+/** 错误日志级别。debug = 次要清理（默认）；error = 关键步骤但需继续后续清理。 */
+export type BestEffortLevel = "debug" | "error";
+
+/**
+ * 吞咽 best-effort IO 的错误，按 level 经共享 logger 记录。
+ *
+ *   - debug（默认）：次要清理（sidecar/worktree/alive marker），失败属预期路径
+ *   - error：关键步骤抛错但需继续后续清理（如 finalizeRecord 的 B9 链：completeRecord
+ *     抛错后仍要执行 finalized/cleanup，错误需可见但不阻断）
+ *
+ * 错误对象优先取 message（避免打印巨大堆栈/对象），其他类型原样传入。
+ */
+export function bestEffort(err: unknown, context: string, level: BestEffortLevel = "debug"): void {
+  const detail = err instanceof Error ? err.message : err;
+  const msg = `[subagents] best-effort ${context} failed`;
+  if (level === "error") {
+    logger.error(msg, { detail });
+  } else {
+    logger.debug(msg, { detail });
+  }
+}

package/src/cli-entry.ts

@@ -0,0 +1,77 @@
+// src/cli-entry.ts
+//
+// 引擎 CLI 进程入口样板单源（S4 簇 2 收编：pi/zcode 两包 main.ts 的逐字同构段
+// 迁移——差异仅 component 字符串与各包自己的 EngineProtocolServer；实现以 pi
+// main.ts 为基线逐字迁移，坏行截断长度 200、日志格式、启动序逐字节保持）。
+//
+// 职界分割：armEngineSelfDestruct 与 EngineProtocolServer 构造留调用方薄层——
+// server 构造需要 arm 产出的 ReverseRequestClock，实例传入后无法回补。本入口承接
+// 其余启动序：configureLoggerSink（stderr 兜底 + host/log 反向请求）→ readline
+// NDJSON 行循环 → close 留痕。
+//
+// stdout/stdin 用 process 全局（与 spawn.ts 同款先例——入口函数只在进程入口调用）。
+// 进程退出面：宿主 stdin EOF → 自灭守卫（薄层 arm）杀进程组；正常 dispose 不退进程。
+
+import * as readline from "node:readline";
+
+import { configureLoggerSink, getLogger } from "./logger.ts";
+
+/**
+ * 引擎协议服务器的结构化最小接口（调用方薄层注入本包 EngineProtocolServer 实例；
+ * 结构子集避免 SDK 反向依赖各包 server 类型）。
+ */
+export interface CliProtocolServerSink {
+  /** 入站协议帧处理（readline 已拆行 + JSON.parse 后的帧）。 */
+  handleFrame(frame: unknown): void;
+  /** 数据面反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
+  reverseRequest(method: string, params: unknown): Promise<unknown>;
+}
+
+/** runEngineCliEntry 参数。 */
+export interface RunEngineCliEntryOptions {
+  /** logger component 标签（如 "pi-engine-cli" / "zcode-engine-cli"）。 */
+  component: string;
+  /** 调用方构造的协议服务器实例（构造参数含 armEngineSelfDestruct 产出的 reverseClock）。 */
+  server: CliProtocolServerSink;
+}
+
+/** 坏行进日志的截断长度（够诊断、不刷屏）。 */
+const INBOUND_LOG_CHARS = 200;
+
+/**
+ * 引擎 CLI 进程入口样板（行为与收编前两包 main.ts 逐字节等价）：
+ * configureLoggerSink → stdin 行解析（NDJSON）→ server.handleFrame → close 留痕。
+ */
+export function runEngineCliEntry(opts: RunEngineCliEntryOptions): void {
+  const logger = getLogger(opts.component);
+  const server = opts.server;
+
+  // stdout 是协议独占通道：应用日志一律走 host/log 反向请求 + stderr 兜底，禁写 stdout。
+  configureLoggerSink({
+    log(level, component, message, data) {
+      // stderr 兜底先落（反向通道未就绪/失败时日志不丢）；host/log 为数据面反向请求
+      // （10s 应答分类），失败吞掉——日志面不能拖垮主链路。
+      process.stderr.write(`[${level}] [${component}] ${message}${data !== undefined ? ` ${JSON.stringify(data)}` : ""}\n`);
+      void server.reverseRequest("host/log", { level, component, message }).catch(() => undefined);
+    },
+  });
+
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  rl.on("line", (line) => {
+    const text = line.trim();
+    if (text === "") return;
+    try {
+      server.handleFrame(JSON.parse(text));
+    } catch (err) {
+      // 坏行跳过不断流（对端 EngineClient 同款纪律）；stdout 协议通道不回显坏行。
+      logger.warn(`unparseable inbound protocol line (ignored): ${text.slice(0, INBOUND_LOG_CHARS)}`, {
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  });
+  rl.on("close", () => {
+    // stdin EOF：自灭守卫已挂（armEngineSelfDestruct 的 once('close') 杀进程组）；
+    // 此处仅留痕（守卫先注册，杀链不依赖本 handler）。
+    logger.debug("stdin closed (host exit path)");
+  });
+}

package/src/data-dir.ts

@@ -0,0 +1,88 @@
+// src/data-dir.ts
+//
+// 引擎数据目录解析（引擎侧原语，自 core execution/engine/common/data-dir.ts 迁入
+// @zhushanwen/subagent-engine-sdk）。迁移处置（impl-plan §2.1 data-dir 行）：**拆
+// seam**——今天 core 版缺 env 时回退 getHostServices().dataRoot()（引擎进程无
+// configureCore 通道，不可复制）；SDK 版 = **参数化/env 优先**，core 侧保留
+// getHostServices() 绑定（core 文件不动，引用切换归 W2+）。
+//
+// SDK 版缺省语义（impl-plan §2.9 数据根注入矩阵，写死）：env 优先；缺 env 且调用方
+// 未显式注入 fallback → **显式报错**（错误信息可操作：env 名 + 期望注入动作），不留
+// 静默漂目录。带 fallback 注入（pi 扩展宿主 = core 侧解析后显式传入）时保留
+// warn-once 语义（回退非权威通道必须可观测），与 core 版行为逐字对齐。
+//
+// 通道调查结论（2026-08-25，P2 实测证据链，自 core 版头部保留）：
+//   - runtime spawn pi 主会话时 RpcClient.buildSafeEnv 从 runtime process.env 继承
+//     XYZ_ 前缀白名单变量（rpc-client.ts:14-30），且显式设置 PI_CODING_AGENT_DIR；
+//   - dev 模式 Electron main 设置 XYZ_AGENT_DATA_DIR（apps/electron/main/main.ts:122），
+//     经 process-control.ts:262 透传给 runtime → 透传链成立；
+//   - prod 默认路径（~/.xyz-agent 缺省）下 runtime 进程 env 中**没有**该变量
+//     → runtime 侧 process-manager.ts spawn env 补注入 XYZ_AGENT_DATA_DIR 修复。
+
+import { getLogger } from "./logger.ts";
+
+const logger = getLogger("subagents");
+
+/** xyz-agent 数据目录 env 名（与 packages/shared/src/paths.ts 的 SSOT 变量同名）。 */
+export const XYZ_DATA_DIR_ENV = "XYZ_AGENT_DATA_DIR";
+
+// warn-once 配置态：globalThis[Symbol.for] slot（core host-services 同款范式）——
+// CJS 多 entry 内联副本下模块级 `let` 会分裂成多份（每份各 warn 一次），slot 跨副本一致。
+const WARNED_SLOT_KEY = Symbol.for("@zhushanwen/subagent-engine-sdk.data-dir-warned");
+
+function getWarnedSlot(): { current: boolean } {
+  let slot = Reflect.get(globalThis, WARNED_SLOT_KEY) as { current: boolean } | undefined;
+  if (!slot) {
+    slot = { current: false };
+    Reflect.set(globalThis, WARNED_SLOT_KEY, slot);
+  }
+  return slot;
+}
+
+/** 测试隔离专用：重置 warn-once 标记（生产禁用）。 */
+export function resetDataDirWarnForTests(): void {
+  getWarnedSlot().current = false;
+}
+
+/**
+ * 解析引擎数据目录（journal 落盘 / 隔离池的根）：
+ *   1. env[XYZ_AGENT_DATA_DIR]（宿主注入，权威通道）；
+ *   2. 缺失 + opts.fallbackDataRoot 显式传入（宿主解析过的数据根）→ 用之 + warn 一次
+ *      （非权威通道回退必须可观测——journal 落点变化不留静默漂移）；
+ *   3. 两者皆缺 → 抛错（engine_not_found 语义：错误含 env 名、期望值示例与恢复动作；
+ *      impl-plan §2.9「缺 env 且无注入 → 显式报错（附期望路径）」）。
+ *
+ * 每次调用重新解析（env 读取是零成本操作，不缓存路径防测试/宿主切换时读到旧值）。
+ */
+export function resolveEngineDataDir(
+  env: NodeJS.ProcessEnv,
+  opts: { fallbackDataRoot?: string; warn?: (msg: string) => void } = {},
+): string {
+  const fromEnv = env[XYZ_DATA_DIR_ENV]?.trim();
+  if (fromEnv !== undefined && fromEnv !== "") return fromEnv;
+
+  const fallback = opts.fallbackDataRoot?.trim();
+  if (fallback === undefined || fallback === "") {
+    throw new Error(
+      `[subagent-engine-sdk] engine_not_found: ${XYZ_DATA_DIR_ENV} is not set and no fallback data root was injected. ` +
+        `Recovery: the host must inject ${XYZ_DATA_DIR_ENV} into the engine process env ` +
+        `(xyz-agent runtime / pi extension host do this at spawn), or pass ` +
+        `{ fallbackDataRoot } when calling resolveEngineDataDir from a host that resolves the data root itself.`,
+    );
+  }
+
+  if (!getWarnedSlot().current) {
+    getWarnedSlot().current = true;
+    const warn = opts.warn ?? defaultWarn;
+    warn(
+      `[engine-data-dir] ${XYZ_DATA_DIR_ENV} is not set; engine journal/pool fall back to the injected data root ` +
+        `(${fallback}). The xyz-agent host normally injects this env — if you are running inside xyz-agent, ` +
+        `check the runtime spawn env; standalone installs intentionally use the injected root.`,
+    );
+  }
+  return fallback;
+}
+
+function defaultWarn(msg: string): void {
+  logger.warn(msg);
+}