@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.3.0",
+  "version": "8.5.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -23,6 +23,7 @@
     "skills/",
     "workflows/",
     "scripts/",
+    "relay/",
     "src/index.ts",
     "src/execution/",
     "src/injectors/",
@@ -31,7 +32,20 @@
     "src/shared/"
   ],
   "xyz-agent": {
-    "role": "universal"
+    "role": "universal",
+    "subagentEngines": [
+      "pi",
+      "zcode"
+    ],
+    "startupConfig": [
+      {
+        "path": "subagents/config.json",
+        "content": {
+          "version": 1,
+          "maxConcurrent": 6
+        }
+      }
+    ]
   },
   "pi": {
     "extensions": [
@@ -47,9 +61,9 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.6.0",
     "@xyz-agent/session-delivery": "0.2.0",
     "@zhushanwen/pi-extension-logger": "0.3.0",
+    "@xyz-agent/extension-protocol": "0.7.0",
     "@zhushanwen/pi-file-lock": "0.1.2"
   },
   "peerDependencies": {
@@ -57,7 +71,7 @@
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@earendil-works/pi-tui": "^0.84.1",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.3.5",
+    "@zhushanwen/pi-pending-notifications": "0.4.0",
     "@zhushanwen/pi-structured-output": "5.0.2"
   },
   "peerDependenciesMeta": {

package/relay/relay.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+/**
+ * subagent relay 代理 CLI（E-1，docs/architecture/subagent-realtime-channel.md §3）。
+ *
+ * 角色：双面字节泵——extension 眼中的 pi 子进程（stdio 与 spawn 真实 pi 字节级同构：
+ * 逐行 JSONL RPC / get_state 握手由 extension 侧 session-runner 原样驱动，代理只搬运字节）
+ * × runtime 眼中的 relay 客户端（本地 socket，先握手后转发）。协议不假设 stdio 是文本
+ * 通道，payload 一律 base64 封装保字节精确。
+ *
+ * ============================ 镜像常量表 ============================
+ * SSOT = src/execution/relay-env.ts（零依赖脚本不能 import workspace 包，只能内嵌镜像；
+ * 改名/改值必须双侧同步，一致性由 E-3 conformance relay 变体断言锁定——设计 §10-5）：
+ *
+ *   | relay-env.ts 常量         | 本文件常量                | 值                          |
+ *   |---------------------------|---------------------------|-----------------------------|
+ *   | RELAY_ENV_SOCKET          | RELAY_ENV_SOCKET          | 'XYZ_SUBAGENT_RELAY_SOCKET' |
+ *   | RELAY_ENV_SESSION_ID      | RELAY_ENV_SESSION_ID      | 'XYZ_SUBAGENT_RELAY_SESSION_ID' |
+ *   | RELAY_ENV_RECORD_ID       | RELAY_ENV_RECORD_ID       | 'XYZ_SUBAGENT_RELAY_RECORD_ID' |
+ *   | RELAY_PROTOCOL_VERSION    | RELAY_PROTOCOL_VERSION    | 1                           |
+ *   | RELAY_EXIT_CODES.*        | RELAY_EXIT_CODES.*        | 10/11/12/13                 |
+ *
+ * 不镜像：RELAY_ENV_NODE / RELAY_ENV_SCRIPT 由 runtime（注入）与 extension（激活判定 +
+ * spawn 组装）消费，代理零消费（不解析自身执行器路径）——镜像无消费方只会积累
+ * unused 代码；激活契约的锁定由 pi-invocation 侧测试与 conformance relay 变体承担。
+ *
+ * ============================ 协议摘要（§3.1） ============================
+ * - 握手：连接后第一帧（单行 JSONL，代理 → runtime）
+ *   {"v":1,"kind":"handshake","mainSessionId":...,"recordId":...,"argv":[...],"env":{...},"cwd":...}
+ * - runtime 回 {"v":1,"kind":"accept"}（进入泵模式）或
+ *   {"kind":"reject","reason":"version","supported":[1]}（→ 退出码 10）
+ * - 数据帧 {"v":1,"kind":"data","dir":...,"b64":...}：
+ *   dir="down"（代理 stdin → runtime → 真实 pi stdin）/ "up"（→ 代理 stdout）/
+ *   "up-stderr"（→ 代理 stderr）。方向以「数据流向真实 pi」为参照：下行 = 流向 pi。
+ * - 退出帧 {"kind":"exit","code":C,"signal":S} → 代理以相同 code/signal 退出
+ * - socket 断（close/error/EOF）→ 退出码 12：socket 是代理的生命线，断 = runtime
+ *   崩溃等场景下 extension 侧感知「子进程死亡」的机制（崩溃矩阵②），不自杀会变孤儿。
+ *
+ * ============================ 零依赖约束 ============================
+ * 禁 import 任何非 node-builtin 模块：本脚本被 ELECTRON_RUN_AS_NODE（打包版 Electron
+ * 内嵌 node）或 dev node 独立执行，无 node_modules 解析保障（设计 §3.2 形态 B）。
+ * 同理不读配置文件、不写文件系统（pid 文件归 runtime 侧注册表）。
+ */
+
+import net from "node:net";
+import os from "node:os";
+
+// ---- 镜像常量（与 relay-env.ts 逐字一致，见头部对照表）----
+const RELAY_ENV_SOCKET = "XYZ_SUBAGENT_RELAY_SOCKET";
+const RELAY_ENV_SESSION_ID = "XYZ_SUBAGENT_RELAY_SESSION_ID";
+const RELAY_ENV_RECORD_ID = "XYZ_SUBAGENT_RELAY_RECORD_ID";
+
+const RELAY_PROTOCOL_VERSION = 1;
+
+const RELAY_EXIT_CODES = {
+  VERSION_MISMATCH: 10,
+  SOCKET_UNREACHABLE: 11,
+  SOCKET_CLOSED: 12,
+  MISSING_IDENTITY: 13,
+};
+
+/** 首次连接失败到重试的间隔（毫秒）。设计未定值；取短值——只需覆盖 runtime 建 socket 与主 pi spawn 的毫秒级窗口。 */
+const CONNECT_RETRY_DELAY_MS = 200;
+/** 退出前等待 stderr/stdout flush 的兜底上限（毫秒）：pipe 写是异步的，process.exit 会丢未 flush 数据。 */
+const FLUSH_TIMEOUT_MS = 1000;
+
+const stdin = process.stdin;
+const stdout = process.stdout;
+const stderr = process.stderr;
+
+/** 当前 socket 连接（connect 成功后赋值；重试期间为 null）。 */
+let sock = null;
+/** 握手已被 runtime accept，进入双向泵模式。 */
+let handshakeAccepted = false;
+/** 退出流程已启动（幂等守卫——error 后必发 close，防双退出路径竞态）。 */
+let exiting = false;
+/** socket 按行解析的残留缓冲（JSONL 帧）。 */
+let lineBuf = "";
+
+// 崩溃矩阵③（代理自身异常死）的兜底：任何未捕获异常也走 12 语义退出 + stderr 留诊断，
+// 保证 extension 侧看到确定的非零退出而非挂死。必须在 main() 调用前注册——main 同步
+// 执行期（模块加载阶段）的异常不会触发「之后」才注册的 handler，会直接以裸 code 1 崩溃。
+process.on("uncaughtException", (err) => {
+  fail(
+    RELAY_EXIT_CODES.SOCKET_CLOSED,
+    `uncaught exception: ${err instanceof Error ? err.stack : String(err)}`,
+  );
+});
+
+main();
+
+function main() {
+  // 启动自检（独立防御）：激活三 env 由 extension 的 isRelayActive 保证（全有或全无），
+  // 归属两 env 由 buildChildEnv 注入——代理不信任上游，缺失即拒绝启动，防无归属帧污染广播。
+  const missing = [];
+  if (!process.env[RELAY_ENV_SESSION_ID]) missing.push(RELAY_ENV_SESSION_ID);
+  if (!process.env[RELAY_ENV_RECORD_ID]) missing.push(RELAY_ENV_RECORD_ID);
+  if (missing.length > 0) {
+    fail(
+      RELAY_EXIT_CODES.MISSING_IDENTITY,
+      `identity env missing: ${missing.join(", ")}（应由 extension buildChildEnv 注入；` +
+        `缺失时继续运行会产生无归属的 tee 帧）`,
+    );
+    return;
+  }
+  const socketPath = process.env[RELAY_ENV_SOCKET];
+  if (!socketPath) {
+    fail(
+      RELAY_EXIT_CODES.MISSING_IDENTITY,
+      `${RELAY_ENV_SOCKET} not set（应由 runtime 注入；缺失意味着 relay 激活条件不完整）`,
+    );
+    return;
+  }
+  connectWithRetry(socketPath);
+}
+
+/** 连接 socket：失败重试一次，再失败退出码 11（runtime 未就绪/路径过期）。 */
+function connectWithRetry(socketPath) {
+  let attempt = 0;
+  const tryConnect = () => {
+    attempt += 1;
+    const s = net.createConnection(socketPath);
+    let connected = false;
+    s.once("connect", () => {
+      connected = true;
+      sock = s;
+      onConnected(s, socketPath);
+    });
+    // 未 connect 的 error 走重试/失败；已 connect 的 close = 生命线断（退出码 12）。
+    s.once("error", (err) => {
+      s.destroy();
+      if (attempt <= 1) {
+        setTimeout(() => {
+          if (!exiting) tryConnect();
+        }, CONNECT_RETRY_DELAY_MS);
+      } else {
+        fail(
+          RELAY_EXIT_CODES.SOCKET_UNREACHABLE,
+          `relay socket unreachable after retry: ${socketPath} (${err.message}). ` +
+            `Recovery: 重试任务；持续失败请重启 xyz-agent（runtime 未运行或已重启）`,
+        );
+      }
+    });
+    s.on("close", () => {
+      if (connected && !exiting) {
+        fail(
+          RELAY_EXIT_CODES.SOCKET_CLOSED,
+          "relay socket closed by runtime（生命线断，可能是 runtime 崩溃/重启）. " +
+            "Recovery: 重启 xyz-agent 后重试任务",
+        );
+      }
+    });
+  };
+  tryConnect();
+}
+
+/** 连接建立：发握手帧 + 挂 socket 侧监听（数据泵监听在 accept 后才挂，见 startPump）。 */
+function onConnected(s) {
+  const handshake = {
+    v: RELAY_PROTOCOL_VERSION,
+    kind: "handshake",
+    mainSessionId: process.env[RELAY_ENV_SESSION_ID],
+    recordId: process.env[RELAY_ENV_RECORD_ID],
+    argv: process.argv.slice(2),
+    env: { ...process.env },
+    cwd: process.cwd(),
+  };
+  s.write(JSON.stringify(handshake) + "\n");
+
+  // 帧本体是 JSON 文本（payload 已 b64 化），utf8 安全；setEncoding 按字符边界切分，
+  // 多字节 UTF-8（中文 argv/env/cwd 值）跨 chunk 不撕裂——与 session-runner.ts stdout 同款先例。
+  s.setEncoding("utf8");
+  s.on("data", (chunk) => {
+    lineBuf += chunk;
+    let nl;
+    while ((nl = lineBuf.indexOf("\n")) >= 0) {
+      const line = lineBuf.slice(0, nl);
+      lineBuf = lineBuf.slice(nl + 1);
+      handleLine(line);
+    }
+  });
+  // 背压方向 1 的恢复：socket 写缓冲排空后恢复读 stdin。
+  s.on("drain", () => {
+    if (!exiting) stdin.resume();
+  });
+}
+
+/** 逐帧分发：握手期是严格状态机（必须先 accept/reject），泵期宽容（转发优先）。 */
+function handleLine(line) {
+  if (!line.trim()) return;
+  let frame;
+  try {
+    frame = JSON.parse(line);
+  } catch {
+    fail(
+      RELAY_EXIT_CODES.SOCKET_CLOSED,
+      `unparseable relay frame (len ${line.length}): ${line.slice(0, 80)}`,
+    );
+    return;
+  }
+  if (!handshakeAccepted) {
+    if (frame.kind === "reject") {
+      if (frame.reason === "version") {
+        fail(
+          RELAY_EXIT_CODES.VERSION_MISMATCH,
+          `relay protocol version mismatch: agent v${RELAY_PROTOCOL_VERSION}, ` +
+            `runtime supports ${JSON.stringify(frame.supported)}. ` +
+            "Recovery: 升级 xyz-agent（runtime 与代理资产同包分发，版本不一致意味着安装损坏，重装应用）",
+        );
+        return;
+      }
+      // 非 version 的 reject（如握手校验失败）无专用退出码：socket 语义不可用，归 12。
+      fail(
+        RELAY_EXIT_CODES.SOCKET_CLOSED,
+        `handshake rejected by runtime: ${String(frame.reason)}`,
+      );
+      return;
+    }
+    if (frame.kind === "accept") {
+      handshakeAccepted = true;
+      startPump();
+      return;
+    }
+    fail(
+      RELAY_EXIT_CODES.SOCKET_CLOSED,
+      `unexpected frame before accept: ${String(frame.kind)}`,
+    );
+    return;
+  }
+  if (frame.kind === "data" && (frame.dir === "up" || frame.dir === "up-stderr")) {
+    if (typeof frame.b64 === "string") {
+      writeUp(Buffer.from(frame.b64, "base64"), frame.dir);
+    }
+    return;
+  }
+  if (frame.kind === "exit") {
+    exitByFrame(frame.code, frame.signal);
+    return;
+  }
+  // 未知帧 kind / down 方向回发：同包同版本下不应出现。宽容忽略保转发——编排通路
+  //（extension 的 RPC 消费）优先于严格协议报错，留前向兼容演进余地。
+  stderr.write(`[relay] ignoring unexpected frame: kind=${String(frame.kind)} dir=${String(frame.dir)}\n`);
+}
+
+/**
+ * 双向泵启动（accept 后）：
+ * - down：stdin chunk → base64 帧 → socket；socket 写缓冲高水位时 pause stdin、drain 恢复。
+ * - up：见 writeUp。
+ */
+function startPump() {
+  stdin.on("data", (chunk) => {
+    if (exiting || !sock || sock.destroyed) return;
+    const ok = sock.write(
+      JSON.stringify({
+        v: RELAY_PROTOCOL_VERSION,
+        kind: "data",
+        dir: "down",
+        b64: chunk.toString("base64"),
+      }) + "\n",
+    );
+    if (!ok) stdin.pause();
+  });
+  // stdin error = 宿主侧管道断（extension 死了）——生命线同类，归 12。
+  stdin.on("error", (err) => {
+    fail(RELAY_EXIT_CODES.SOCKET_CLOSED, `stdin broken (host may have exited): ${err.message}`);
+  });
+  // extension 关闭代理 stdin（EOF）：协议无 stdin-EOF 帧且不新增（演进克制）——现状
+  // spawn 语义下 stdin 生命周期与进程 kill 绑定，runtime 的 exit 帧才是权威退出信号，
+  // 此处保持连接等待，不自行退出。
+  stdin.on("end", () => {});
+  stdin.resume();
+}
+
+/**
+ * up 帧写出（stdout/stderr）。背压：write 返回 false = 该出口高水位 → 暂停 socket 读
+ * （数据滞留 socket 接收缓冲，不丢字节不撑内存）；该出口 drain 且另一出口也无 pending
+ * drain 时恢复读。pending drain 监听的存在性即该出口的拥堵标志。
+ */
+function writeUp(buf, dir) {
+  if (exiting) return;
+  const target = dir === "up-stderr" ? stderr : stdout;
+  if (target.write(buf)) return;
+  target.once("drain", maybeResumeSocket);
+  sock.pause();
+}
+
+function maybeResumeSocket() {
+  if (stdout.listenerCount("drain") === 0 && stderr.listenerCount("drain") === 0 && !exiting && sock) {
+    sock.resume();
+  }
+}
+
+/** exit 帧处理：signal 优先（extension 侧 close(code, signal) 与真实 pi 死法对齐），否则按 code。 */
+function exitByFrame(code, signal) {
+  const sig = typeof signal === "string" && signal ? signal : null;
+  if (sig) {
+    const signum = os.constants.signals[sig];
+    if (typeof signum === "number") {
+      exiting = true;
+      try {
+        stdin.destroy();
+      } catch {}
+      try {
+        sock?.destroy();
+      } catch {}
+      // 真实信号自杀：未注册 handler 的终止类信号必然终止进程，spawn 方观察到
+      // (code=null, signal=sig)，与真实 pi 被信号杀死完全同构。信号路径不等 stdout
+      // flush——内核 pipe 缓冲中已 write 的字节对端仍可读，node 内部队列丢弃与真实
+      // 进程被杀的行为一致。万一信号被环境截胡（理论不发生），fallback 128+signum。
+      process.kill(process.pid, sig);
+      process.exit(128 + signum);
+    }
+    fail(RELAY_EXIT_CODES.SOCKET_CLOSED, `exit frame carried unmappable signal: ${sig}`);
+    return;
+  }
+  exitGracefully(typeof code === "number" ? code : 1);
+}
+
+/** 失败退出：先确保 stderr 诊断行 flush 到对端，再走通用退出清理。 */
+function fail(code, message) {
+  if (exiting) return;
+  exiting = true;
+  writeFlushed(stderr, `[relay] ${message}\n`, () => flushStdoutThenExit(code));
+}
+
+/** 正常退出（exit 帧 code 路径）：尽力 flush stdout 已排队字节后退出。 */
+function exitGracefully(code) {
+  if (exiting) return;
+  exiting = true;
+  flushStdoutThenExit(code);
+}
+
+/**
+ * 写一段数据并等它 flush（callback / 1s 兜底 / 写异常三路都推进）。
+ * 为什么必须等：process.exit 立即返回，pipe 模式的异步写会丢——错误诊断丢了对端就
+ * 只剩裸退出码，违反「错误信息必须可操作」。
+ */
+function writeFlushed(stream, data, next) {
+  let advanced = false;
+  const advance = () => {
+    if (advanced) return;
+    advanced = true;
+    next();
+  };
+  // 定时器保持 ref：进程因未销毁的流而存活，到期必触发；unref 的 timer 在无其他
+  // 事件源时不会执行，会导致静默以 code 0 自然退出（误导 extension「成功」）。
+  const timer = setTimeout(advance, FLUSH_TIMEOUT_MS);
+  try {
+    stream.write(data, () => {
+      clearTimeout(timer);
+      advance();
+    });
+  } catch {
+    clearTimeout(timer);
+    advance();
+  }
+}
+
+/** stdout 队列已空则立即退，否则等 drain（1s 兜底防对端停读挂死）。 */
+function flushStdoutThenExit(code) {
+  if (stdout.writableLength === 0) {
+    forceExit(code);
+    return;
+  }
+  let advanced = false;
+  const advance = () => {
+    if (advanced) return;
+    advanced = true;
+    forceExit(code);
+  };
+  // 定时器保持 ref（理由同 writeFlushed）：进程因未销毁的流而存活，到期必触发。
+  const timer = setTimeout(advance, FLUSH_TIMEOUT_MS);
+  stdout.once("drain", () => {
+    clearTimeout(timer);
+    advance();
+  });
+}
+
+/**
+ * 最终退出：destroy stdin 与 socket（防流句柄悬挂阻塞退出）；stdout/stderr 不 destroy
+ * ——destroy 会丢弃已排队未 flush 的转发字节，协议保真优先（flush 等待已在上游完成）。
+ */
+function forceExit(code) {
+  try {
+    stdin.destroy();
+  } catch {}
+  try {
+    sock?.destroy();
+  } catch {}
+  process.exit(code);
+}

package/skills/subagent-ext-config/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: subagent-ext-config
+description: "使用或排查 @zhushanwen/pi-subagent-workflow 的引擎路由配置时加载。说明 config.json 三环境路径与动态推导方法、字段表（defaultEngine / engineRouting.strict / maxConcurrent）、三层路由优先级、生效时机（新 session 生效）、probe 缓存语义、验证步骤与常见错误。触发词：subagent 引擎配置、切换 subagent 引擎、defaultEngine、zcode 派发、subagent 配置在哪、engineFallback、engine_not_found、subagent-ext-config。"
+---
+
+# subagent-workflow 引擎路由配置指南
+
+> @zhushanwen/pi-subagent-workflow：subagent 派发扩展。P4 起支持多引擎路由（pi / zcode），路由偏好来自 config.json + 调用点覆盖。本指南讲清配置位置、字段语义、生效时机与排查路径。
+
+**重要前提**：配置在 pi 子进程启动与每次 `session_start` 时读取——**改完 config.json 后必须新建 session 才生效**，当前 session 内不重读。用户问「改了没生效」时先确认这一点，不要怀疑文件路径。
+
+## 配置文件在哪（三环境）
+
+config.json 位于 pi agent 目录下的 `subagents/config.json`，随环境不同：
+
+| 环境 | 路径 |
+|------|------|
+| 独立 pi CLI | `~/.pi/agent/subagents/config.json` |
+| xyz-agent dev | `~/.xyz-agent-dev/pi/agent/subagents/config.json` |
+| xyz-agent prod | `~/.xyz-agent/pi/agent/subagents/config.json` |
+
+**动态推导（推荐）**：agentDir 由 pi 核心 `getAgentDir()` 决定（读 `PI_CODING_AGENT_DIR`，默认 `~/.pi/agent`）；xyz-agent 通过 `XYZ_AGENT_DATA_DIR` 隔离数据目录。排查时先查这两个 env 变量组合出实际路径（`<agentDir>/subagents/config.json`），不要假设单一环境——写错环境的配置文件改了也不生效。
+
+文件不存在 / JSON 解析失败 / 字段缺失时全部回默认配置，不报错。旧版 `categories` / `fallback` / `yoloByDefault` 等字段读取时忽略（模型解析已退化为「主 agent model 优先」）。
+
+## 字段表（sanitize 语义）
+
+| 字段 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `defaultEngine` | string | 缺省由路由层落 `'pi'` | 全局默认引擎。合法值 `'pi'` / `'zcode'`。坏值（非字符串/空串）**静默忽略**回缺省 pi，不报错——排查「改了 defaultEngine 却还在用 pi」时先检查 JSON 值合法性 |
+| `engineRouting.strict` | boolean | `false` | `true` = 一切 probe 失败直接报错、不做兜底回退。仅认 strict 布尔键，其余键忽略 |
+| `maxConcurrent` | number | `6` | subagent 并发池大小。正整数，非正整数/非整数回默认 |
+
+示例（最小可用）：
+
+```json
+{
+  "version": 1,
+  "defaultEngine": "zcode",
+  "engineRouting": { "strict": false },
+  "maxConcurrent": 6
+}
+```
+
+## 三层路由优先级
+
+一次 subagent 派发用哪个引擎，按以下顺序决定（高优先级覆盖低优先级）：
+
+| 优先级 | 来源 |
+|------|------|
+| 1 | `subagents` 工具调用的 `engine` 参数（单次指定） |
+| 2 | agent `.md` frontmatter 的 `engine` 字段 |
+| 3 | config.json 的 `defaultEngine` |
+
+显式指定（层级 1/2）属「守卫命中」——probe 失败**不兜底**、直接报 `engine_probe_failed`；仅全局默认任务才走 fallback 兜底回 pi。
+
+## 生效时机与 probe 缓存
+
+- **配置读取**：pi 子进程启动 + 每次 `session_start` 各读一次，session 内不重读。改配置 → 新建 session 生效。
+- **probe 缓存**：引擎探针（zcode CLI 存在性/版本检查）成功或失败均缓存直返，**进程存活期内不重探**。
+- **engineFallback 留痕条件**：兜底回 pi（record 带 `engineFallback` 标记）只在探针**未缓存**时触发。同一 session 内先 probe 成功后 CLI 损坏，不会再触发兜底。要复现/验证 fallback 场景，必须新建 session 重置缓存。
+
+## 验证步骤
+
+改完配置后：
+
+1. **新建 session**（必须——当前 session 不重读配置）。
+2. 让主 agent 派一个 subagent（例：用 `subagents` 工具发个简单任务）。
+3. xyz-agent 侧边栏 **Agents tab** 看该项最左的引擎 icon（pi / zcode）——这是统一验证面。
+4. journal 落点 `~/.xyz-agent-dev/engines/<engineId>/` **仅适用非 pi 引擎**（zcode 分支建 journal）；pi 分支不建 journal，pi 任务以 icon 为验证面。
+
+## 常见错误排查
+
+| 症状 | 原因与处置 |
+|------|------|
+| `engine_not_found` | engine id 未注册。检查拼写，合法值仅 `pi` / `zcode` |
+| zcode 任务传 `conversation` / `fork` / `worktree` 被预检拒绝 | 这些是 pi 专属能力，zcode 不支持。改用 `engine: pi` 或不传该参数重试（预检在 record 创建前同步拒绝，可立即换引擎） |
+| 改了 `defaultEngine` 没生效 | 两种可能：① 当前 session 不重读配置——新建 session；② 值非法被静默忽略回 pi——核对 JSON 值 |
+| 期望 fallback 回 pi 却报错 | 显式指定引擎（工具参数/frontmatter）属守卫命中，probe 失败不兜底直接报错；只有走 `defaultEngine` 的任务才兜底 |
+| probe 结果与 CLI 实际状态不符 | 探针进程存活期内缓存——CLI 刚装好/刚损坏，需新建 session 重置缓存 |

package/src/execution/__tests__/agent-registry.test.ts

@@ -22,6 +22,8 @@ vi.mock("node:os", async (importOriginal) => {
 import { lintAgentMeta } from "../../orchestration/script-lint.ts";
 import { parseResourceMeta } from "../../shared/meta-parser.ts";
 import { AgentRegistry, parseAgentFrontmatter, parseAgentWithMeta } from "../agent-registry.ts";
+import type { EnginePort } from "../engine/port.ts";
+import { clearEngines, registerEngine } from "../engine/registry.ts";
 
 // ============================================================
 // helpers
@@ -251,3 +253,111 @@ describe("builtin agents 数据合规", () => {
     expect(reg.loadByPath(path.join(AGENTS_DIR, "doc-reviewer.md"))?.tools).toEqual(["read", "grep", "structured-output"]);
   });
 });
+
+// ============================================================
+// engine 字段（P4 D9：frontmatter 主通道 + 解析期注册表校验）
+// ============================================================
+
+describe("parseAgentWithMeta engine 字段（P4 路由）", () => {
+  beforeEach(() => {
+    // 解析期校验消费注册表——测试内注册假引擎（惰性工厂无副作用）
+    clearEngines();
+    // 工厂恒 throw：解析期校验只查注册表存在性，不实例化（惰性工厂契约）
+    const neverInstantiate = (): EnginePort => {
+      throw new Error("parse-time validation must not instantiate engines");
+    };
+    registerEngine("pi", neverInstantiate);
+    registerEngine("zcode", neverInstantiate);
+  });
+  afterEach(() => {
+    clearEngines();
+  });
+
+  it("frontmatter engine 进 config.engine（结构化路径，IF1）", () => {
+    const { config, meta } = parseAgentWithMeta(
+      "/x/reviewer.md",
+      `---
+name: reviewer
+description: review agent
+engine: zcode
+---
+body`,
+    );
+    expect(config.engine).toBe("zcode");
+    expect(meta?.kind === "agent" && meta.engine).toBe("zcode");
+  });
+
+  it("IF1 未通过（缺 description）时 legacy fallback 取 engine（配置不丢，与 model 同判）", () => {
+    const { config } = parseAgentWithMeta(
+      "/x/reviewer.md",
+      `---
+name: reviewer
+engine: zcode
+---
+body`,
+    );
+    expect(config.engine).toBe("zcode");
+  });
+
+  it("未注册 engine id：解析期抛 EngineNotFoundError，文案含注册清单与文件路径", () => {
+    expect(() =>
+      parseAgentWithMeta(
+        "/x/reviewer.md",
+        `---
+name: reviewer
+description: review agent
+engine: nonexistent-engine
+---
+body`,
+      ),
+    ).toThrowError(/engine_not_found: engine 'nonexistent-engine'/);
+    expect(() =>
+      parseAgentWithMeta(
+        "/x/reviewer.md",
+        `---
+name: reviewer
+description: review agent
+engine: nonexistent-engine
+---
+body`,
+      ),
+    ).toThrowError(/Registered engines: pi, zcode/);
+    expect(() =>
+      parseAgentWithMeta(
+        "/x/my-agent.md",
+        `---
+name: my-agent
+description: d
+engine: nonexistent-engine
+---
+body`,
+      ),
+    ).toThrowError(/Source: \/x\/my-agent\.md/);
+  });
+
+  it("已注册 id（pi/zcode）：解析通过，不抛", () => {
+    expect(() =>
+      parseAgentWithMeta(
+        "/x/reviewer.md",
+        `---
+name: reviewer
+description: review agent
+engine: pi
+---
+body`,
+      ),
+    ).not.toThrow();
+  });
+
+  it("无 engine 字段：config.engine 缺省（走全局默认层）", () => {
+    const { config } = parseAgentWithMeta(
+      "/x/worker.md",
+      `---
+name: worker
+description: d
+---
+body`,
+    );
+    expect(config.engine).toBeUndefined();
+  });
+});