@zhushanwen/subagent-core 0.4.0 → 0.5.1

package/src/execution/__tests__/turn-limiter.test.ts

@@ -1,7 +1,7 @@
 // src/__tests__/turn-limiter.test.ts
 import { describe, expect, it, vi } from "vitest";
 
-import { createTurnLimiter } from "../turn-limiter.ts";
+import { createTurnLimiter } from "../engine/engines/pi/turn-limiter.ts";
 
 describe("createTurnLimiter", () => {
   it("does nothing before maxTurns", () => {

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

@@ -9,7 +9,10 @@
 // realHandler 路由：channel 命中 → channelHandler（经 coerceUiResponse 形变）；未命中 → defaultDialogForward（dialog 转发结果，fire-and-forget 转发 ctx.ui.* 后回 ack，未知 method warn + ack）。
 // 测接口契约，不测实现细节。
 
-import type { ExtensionContext, ExtensionMode } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+
+// ExtensionMode 未从 pi 包根 re-export（实装 0.84.4 核对），从权威 ExtensionContext 派生
+type ExtensionMode = ExtensionContext["mode"];
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const { loggerMock } = vi.hoisted(() => ({
@@ -39,14 +42,17 @@ function makeCtx(mode: ExtensionMode): ExtensionContext {
     },
     modelRegistry: undefined,
     model: undefined,
-  } as ExtensionContext;
+  } as unknown as ExtensionContext;
 }
 
 /** 带 mock ctx.ui 的 ExtensionContext（GUI fire-and-forget 转发测试用）。
  *  dialog method（select/confirm/input/editor）返回 undefined/true/"" 兜底，
  *  fire-and-forget method（notify/setStatus/setWidget/setTitle/setEditorText）是 void spy。 */
-function makeCtxWithUi(mode: ExtensionMode = "rpc"): ExtensionContext & { ui: Record<string, ReturnType<typeof vi.fn>> } {
-  const ui: Record<string, ReturnType<typeof vi.fn>> = {
+// ui 成员 = 真实签名 & vi.fn 能力（映射交叉）：调用点走真实签名，mock 打点方法可达
+type MockedUi = { [K in keyof ExtensionUIContext]: ExtensionUIContext[K] & ReturnType<typeof vi.fn> };
+
+function makeCtxWithUi(mode: ExtensionMode = "rpc"): Omit<ExtensionContext, "ui"> & { ui: MockedUi } {
+  const ui = {
     select: vi.fn(async () => undefined),
     confirm: vi.fn(async () => true),
     input: vi.fn(async () => ""),
@@ -67,8 +73,8 @@ function makeCtxWithUi(mode: ExtensionMode = "rpc"): ExtensionContext & { ui: Re
     },
     modelRegistry: undefined,
     model: undefined,
-    ui,
-  } as unknown as ExtensionContext & { ui: Record<string, ReturnType<typeof vi.fn>> };
+    ui: ui as unknown as MockedUi,
+  } as unknown as Omit<ExtensionContext, "ui"> & { ui: MockedUi };
 }
 
 function dialogReq(id: string, channel?: string): UiRequest {

package/src/execution/__tests__/ui-request-handler.test.ts

@@ -18,8 +18,8 @@ import { PassThrough } from "node:stream";
 
 import { describe, expect, it, vi } from "vitest";
 
-import { ASK_USER_RPC_PROMPT } from "../session-runner.ts";
-import { parseSpawnLine } from "../spawn-event-adapter.ts";
+import { ASK_USER_RPC_PROMPT } from "../engine/engines/pi/session-runner.ts";
+import { parseSpawnLine } from "../engine/engines/pi/spawn-event-adapter.ts";
 import { parseChannel } from "../ui-channels.ts";
 import { createUiRequestQueue, type UiRequest, type UiRequestHandler } from "../ui-request-queue.ts";
 
@@ -69,7 +69,8 @@ describe("parseSpawnLine — ask_user 请求解析（Pi 原生格式）", () =>
   it("request.title === ASK_USER_MARKER（NUL 前缀 marker 原样保留，由 parseChannel 提取）", () => {
     const result = parseSpawnLine(askUserLine("ui-req-001"));
     if (result?.kind !== "extension_ui_request") return;
-    expect(result.request.title).toBe(ASK_USER_MARKER);
+    if (result.request.method !== "select") return expect.fail("request.method 应为 select");
+    expect((result.request as { title?: string }).title).toBe(ASK_USER_MARKER);
   });
 
   it("id 被正确提取（用于 response 关联）", () => {

package/src/execution/__tests__/ui-request-queue.test.ts

@@ -55,7 +55,7 @@ describe("UI 请求队列", () => {
   it("多个 extension_ui_request 按 FIFO 顺序处理", async () => {
     const callOrder: string[] = [];
     // 每个请求返回独立的可控 Promise
-    const resolvers: Array<(v: unknown) => void> = [];
+    const resolvers: Array<(v: UiResponse) => void> = [];
 
     const handler: UiRequestHandler = vi.fn((req: UiRequest) => {
       callOrder.push(req.title ?? "");
@@ -94,7 +94,7 @@ describe("UI 请求队列", () => {
 
   it("第一个请求未 resolve 时第二个不调用 uiRequestHandler", async () => {
     const callOrder: string[] = [];
-    let firstResolve: (v: unknown) => void;
+    let firstResolve: (v: UiResponse) => void;
 
     const handler: UiRequestHandler = vi.fn((req: UiRequest) => {
       callOrder.push(req.title ?? "");
@@ -156,3 +156,143 @@ describe("UI 请求队列 — timeout 字段透传（LC-3/T2⑦）", () => {
     expect(received[0].timeout).toBe(5000);
   });
 });
+
+// ── extractMethodFields 字段复制链路（经 createUiRequestQueue → handleUiRequest 锁定）──
+// 13 个 method-specific 字段的复制语义：typed 守卫字段（string/number/array）验型通过才复制、
+// presence-only 字段（statusText/widgetLines/widgetPlacement）仅 in 检查直赋、缺失字段不复制。
+// 协议形状来自 JSON 反序列化，坏类型运行时可达——用例以 as unknown as 构造越界形状做防御锁定。
+
+describe("UI 请求队列 — method-specific 字段复制（extractMethodFields 链路）", () => {
+  function makeQueue(handler: UiRequestHandler): { enqueue: ReturnType<typeof createUiRequestQueue> } {
+    const child = makeFakeChild();
+    const ctx = { uiRequestHandler: handler } as Parameters<
+      typeof createUiRequestQueue
+    >[1];
+    return { enqueue: createUiRequestQueue(child, ctx) };
+  }
+
+  it("全字段请求：typed 守卫字段与 presence-only 字段全部复制到 UiRequest", async () => {
+    const received: UiRequest[] = [];
+    const { enqueue } = makeQueue((req) => {
+      received.push(req);
+      return Promise.resolve<UiResponse>({ ack: true });
+    });
+
+    // 13 字段全量形状（协议 union 无单变体携带全部字段，运行时平铺可达）
+    const req = {
+      method: "select",
+      title: "t",
+      options: ["a", "b"],
+      message: "m",
+      placeholder: "p",
+      prefill: "pf",
+      notifyType: "warning",
+      statusKey: "sk",
+      statusText: "st",
+      widgetKey: "wk",
+      widgetLines: ["l1"],
+      widgetPlacement: "belowEditor",
+      text: "tx",
+      timeout: 2500,
+    } as unknown as Parameters<ReturnType<typeof createUiRequestQueue>>[1];
+
+    enqueue("r1", req);
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(received).toHaveLength(1);
+    expect(received[0]).toMatchObject({
+      title: "t",
+      options: ["a", "b"],
+      message: "m",
+      placeholder: "p",
+      prefill: "pf",
+      notifyType: "warning",
+      statusKey: "sk",
+      statusText: "st",
+      widgetKey: "wk",
+      widgetLines: ["l1"],
+      widgetPlacement: "belowEditor",
+      text: "tx",
+      timeout: 2500,
+    });
+  });
+
+  it("typed 守卫字段类型不符时跳过复制，其余字段照常", async () => {
+    const received: UiRequest[] = [];
+    const { enqueue } = makeQueue((req) => {
+      received.push(req);
+      return Promise.resolve<UiResponse>({ ack: true });
+    });
+
+    const req = {
+      method: "select",
+      title: "kept-title", // 合法（title 非法值会在链路上游 startsWith 处炸掉整条请求，见下一条用例）
+      options: "not-array", // string ≠ array → 跳过
+      timeout: "5000", // string ≠ number → 跳过
+      message: "kept",
+    } as unknown as Parameters<ReturnType<typeof createUiRequestQueue>>[1];
+
+    enqueue("r1", req);
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(received).toHaveLength(1);
+    expect(received[0].title).toBe("kept-title");
+    expect("options" in received[0]).toBe(false);
+    expect("timeout" in received[0]).toBe(false);
+    expect(received[0].message).toBe("kept");
+  });
+
+  it("typed 非法 title（number）在上游 startsWith 处炸链路 → handler 不被调、单请求失败被吞不阻塞队列", async () => {
+    // HEAD 真实行为锚定（探针实证）：title: 42 在 extractMethodFields 之前的环节
+    // 触发 str.startsWith is not a function，异常被 handleUiRequest 的 .catch 吞掉
+    //（注释声明的「单个请求失败不阻塞后续」语义）——守卫的「跳过该字段」对 title 不可达。
+    const received: UiRequest[] = [];
+    const { enqueue } = makeQueue((req) => {
+      received.push(req);
+      return Promise.resolve<UiResponse>({ ack: true });
+    });
+
+    const badReq = {
+      method: "select",
+      title: 42,
+      message: "kept",
+    } as unknown as Parameters<ReturnType<typeof createUiRequestQueue>>[1];
+    enqueue("r1", badReq);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(received).toHaveLength(0); // handler 未被调（链路在上游失败）
+
+    // 队列不阻塞：后续合法请求照常处理
+    enqueue("r2", {
+      method: "select",
+      title: "Q2",
+      options: [JSON.stringify({ question: "Q2", options: [{ label: "A" }] })],
+    });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(received).toHaveLength(1);
+    expect(received[0].title).toBe("Q2");
+  });
+
+  it("presence-only 字段仅 in 检查直赋；未声明的字段不复制（保持 UiRequest 可选）", async () => {
+    const received: UiRequest[] = [];
+    const { enqueue } = makeQueue((req) => {
+      received.push(req);
+      return Promise.resolve<UiResponse>({ ack: true });
+    });
+
+    // statusText 存在但值为 undefined（statusText: string | undefined 变体合法形态）→ 仍复制
+    const req = {
+      method: "setStatus",
+      statusKey: "k",
+      statusText: undefined,
+      unknownField: "should-not-copy",
+    } as unknown as Parameters<ReturnType<typeof createUiRequestQueue>>[1];
+
+    enqueue("r1", req);
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(received).toHaveLength(1);
+    expect("statusText" in received[0]).toBe(true);
+    expect(received[0].statusText).toBeUndefined();
+    expect("unknownField" in received[0]).toBe(false);
+  });
+});

package/src/execution/__tests__/worktree-manager.test.ts

@@ -80,7 +80,16 @@ import { isProcessAlive } from "../alive-store.ts";
 import { encodeCwd } from "../path-encoding.ts";
 import { WorktreeManager } from "../worktree-manager.ts";
 
-const mockExecFile = vi.mocked(execFile);
+// 被测链路（gitRunAsync）调用四参形态（file, args, options, callback）；vi.mocked
+// 直接包 execFile 会推导到无 options 重载，显式绑定四参签名
+const mockExecFile = vi.mocked(
+  execFile as unknown as (
+    file: string,
+    args: readonly string[],
+    options: unknown,
+    callback: (err: Error | null, stdout: string, stderr: string) => void,
+  ) => void,
+);
 const mockExistsSync = vi.mocked(fs.existsSync);
 const mockIsProcessAlive = vi.mocked(isProcessAlive);
 
@@ -95,7 +104,7 @@ type ExecFileResult = {
 };
 function setupExecFile(impl?: (args: readonly string[]) => ExecFileResult): void {
   mockExecFile.mockImplementation(
-    (_cmd: string, args: readonly string[], _opts: unknown, cb: (err: Error | null, stdout?: string, stderr?: string) => void) => {
+    (_cmd: string, args: readonly string[], _opts: unknown, cb: (err: Error | null, stdout: string, stderr: string) => void) => {
       const r = impl ? impl(args) : { stdout: "" };
       if (r.err) cb(r.err, r.stdout ?? "", r.stderr ?? "");
       else cb(null, r.stdout ?? "", r.stderr ?? "");
@@ -178,7 +187,7 @@ describe("WorktreeManager", () => {
       await mgr.create(MAIN_CWD, RECORD_ID);
 
       expect(mockAdd).toHaveBeenCalledTimes(1);
-      const entry = mockAdd.mock.calls[0][0] as { repo: string; branch: string; pid: number };
+      const entry = mockAdd.mock.calls[0]![0] as { repo: string; branch: string; pid: number };
       expect(entry.repo).toBe(MAIN_CWD);
       expect(entry.branch).toBe(`pi-sub-${RECORD_ID}`);
       expect(entry.pid).toBe(0);
@@ -266,7 +275,7 @@ describe("WorktreeManager", () => {
       let maxWriteActive = 0;
       let addCount = 0;
       mockExecFile.mockImplementation(
-        (_cmd: string, args: readonly string[], _opts: unknown, cb: (err: Error | null, stdout?: string, stderr?: string) => void) => {
+        (_cmd: string, args: readonly string[], _opts: unknown, cb: (err: Error | null, stdout: string, stderr: string) => void) => {
           const isAdd = args[0] === "worktree" && args[1] === "add";
           if (isAdd) {
             // 只对写命令（worktree add）计并发——读命令（status/rev-parse）无锁可并行是设计预期
@@ -442,7 +451,7 @@ describe("WorktreeManager", () => {
       let maxActive = 0;
       // 异步完成 cb：若队列失效，后继命令的 impl 入口会先于前驱 cb 到达 → active=2
       mockExecFile.mockImplementation(
-        (_cmd: string, args: readonly string[], _opts: unknown, cb: (err: Error | null, stdout?: string, stderr?: string) => void) => {
+        (_cmd: string, args: readonly string[], _opts: unknown, cb: (err: Error | null, stdout: string, stderr: string) => void) => {
           active++;
           maxActive = Math.max(maxActive, active);
           setTimeout(() => {

package/src/execution/__tests__/worktree-pid-registration.integration.test.ts

@@ -52,7 +52,7 @@ vi.mock("./pi-invocation.ts", () => ({
 
 import { WorktreeManager } from "../worktree-manager.ts";
 import { WorktreeRegistry, SPAWN_GRACE_MS } from "../worktree-registry.ts";
-import { runSpawn } from "../session-runner.ts";
+import { runSpawn } from "../engine/engines/pi/session-runner.ts";
 import type { WorktreeHandle } from "../types.ts";
 import { makeCtx, makeOpts, makeRecord } from "./helpers/spawn-mock.ts";
 
@@ -118,7 +118,7 @@ async function cleanup(): Promise<void> {
     handle = undefined;
   }
   try {
-    fs.rmSync(tmpRoot, { recursive: true, force: true });
+    fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   } catch {
     // best-effort
   }
@@ -213,7 +213,8 @@ describe("worktree pid 注册链路（真实 spawn 集成）", { timeout: 30_000
       makeOpts({ worktree: handle }),
       ctx,
     );
-    expect(result.status).not.toBe("error"); // 进程正常退出（exit 0），非 spawn 失败
+    // 历史「status !== error」弱断言：AgentResult 无 status 字段，经视图访问保持断言语义不变
+    expect((result as { status?: string }).status).not.toBe("error"); // 进程正常退出（exit 0），非 spawn 失败
 
     // 3. pid 已补全（短命进程退出后 pid 仍有效，registerPid 同步执行不受退出影响）
     const entry = readEntry(handle.branch);

package/src/execution/agent-registry.ts

@@ -56,41 +56,64 @@ export function parseAgentWithMeta(
   content: string,
 ): { config: AgentConfig; meta: AgentMeta | null } {
   const name = path.basename(filePath, ".md");
+  // 结构切分三态（与 parseAgentProfile 共用 splitAgentFrontmatter，切分逻辑逐字节一致）
+  const fm = splitAgentFrontmatter(content);
 
   // 无 frontmatter → 整个内容作为 systemPrompt
-  if (!content.startsWith(FM_DELIM)) {
+  if (fm.kind === "none") {
     return { config: { name, systemPrompt: content.trim() }, meta: null };
   }
 
-  const closeIdx = content.indexOf(FM_DELIM, FM_DELIM.length);
-  if (closeIdx === -1) {
-    // 未闭合 frontmatter：提取 name，其余作为 systemPrompt
-    const yamlBlock = content.slice(FM_DELIM.length);
+  // 未闭合 frontmatter：提取 name，其余作为 systemPrompt
+  if (fm.kind === "unclosed") {
     return {
       config: {
-        name: extractYamlField(yamlBlock, "name") ?? name,
+        name: extractYamlField(fm.yamlBlock, "name") ?? name,
         systemPrompt: content.trim(),
       },
       meta: null,
     };
   }
 
-  const yamlBlock = content.slice(FM_DELIM.length, closeIdx);
-  const body = content.slice(closeIdx + FM_DELIM.length).trim();
+  return parseClosedFrontmatterAgent(filePath, name, content, fm.yamlBlock, fm.body);
+}
 
+/** closed frontmatter 的主路径：IF1 严格层 + legacy fallback 字段解析 + config 投影。
+ *  字段解析/warn/throw 时序与提取前一致（parseResourceMeta → fallback+warn → engine+校验 → 投影）。 */
+function parseClosedFrontmatterAgent(
+  filePath: string,
+  name: string,
+  content: string,
+  yamlBlock: string,
+  body: string,
+): { config: AgentConfig; meta: AgentMeta | null } {
   // m2：结构化路由字段（name/model/tools）经 IF1 parseResourceMeta（统一 parser），
   // 消灭本地 frontmatter parser 与 subagent-list-injector 的重复。thinkingLevel/defaultBackground
   // 是执行配置（非 AgentMeta 路由字段），仍用 extractYamlField 取。
   const meta = parseResourceMeta(content, "agent");
   const agentMeta = meta?.kind === "agent" ? meta : null;
+  const legacyFallbacks = resolveLegacyRoutingFallbacks(agentMeta, yamlBlock, filePath);
+  // engine 字段（D9）：结构化优先（IF1），legacy fallback 与 model/tools 同判——
+  // agentMeta 未通过 IF1 时配置不丢
+  const engine = resolveAgentEngine(agentMeta, yamlBlock, filePath);
+
+  return {
+    config: projectAgentConfig(name, body, agentMeta, legacyFallbacks, engine, yamlBlock),
+    meta: agentMeta,
+  };
+}
+
+/** legacy fallback 路由字段（model/tools）：IF1 未通过时不静默丢失（MF-3），并按需 warn。 */
+function resolveLegacyRoutingFallbacks(
+  agentMeta: AgentMeta | null,
+  yamlBlock: string,
+  filePath: string,
+): { modelFallback: string | undefined; toolsFallback: string[] | undefined } {
   // MF-3 regression fix：agentMeta=null（IF1 要求 name/description 必填，缺则 parseResourceMeta
   // 返 null）时，model/tools 不能静默丢失——fallback 用 extractYamlField 取（保留重构前行为）。
   // 注入路由可见性由 discovery/injector 按 available 标志决定，与本处（direct-path loadByPath）无关。
   const modelFallback = extractYamlField(yamlBlock, "model");
-  const toolsFallbackRaw = extractYamlField(yamlBlock, "tools");
-  const toolsFallback = toolsFallbackRaw
-    ? toolsFallbackRaw.split(",").map((s) => s.trim()).filter(Boolean)
-    : undefined;
+  const toolsFallback = parseCommaListFallback(extractYamlField(yamlBlock, "tools"));
   if (!agentMeta && /^model:|^tools:/m.test(yamlBlock)) {
     // m2 exec-review MINOR-2 + MF-3：IF1 未通过（缺 name/description）→ model/tools 经 legacy
     // fallback 取（direct-path loadByPath 不丢配置，与重构前一致）；但结构化路由注入不可见，
@@ -100,32 +123,53 @@ export function parseAgentWithMeta(
         "model/tools 经 legacy fallback 生效（直接路径不丢配置），但结构化路由不可见——请补充 description",
     );
   }
-  const defaultBackgroundRaw = extractYamlField(yamlBlock, "defaultBackground");
-  // engine 字段（D9）：结构化优先（IF1），legacy fallback 与 model/tools 同判——
-  // agentMeta 未通过 IF1 时配置不丢
+  return { modelFallback, toolsFallback };
+}
+
+/** engine 字段解析 + 解析期注册校验（D9：未注册 id 前置暴露，不留到运行时神秘失败）。
+ *  为什么在解析期而非路由期：配置错误的根源在 .md 文件，越早报错定位越准（错误含文件路径 + 注册清单）。 */
+function resolveAgentEngine(
+  agentMeta: AgentMeta | null,
+  yamlBlock: string,
+  filePath: string,
+): string | undefined {
   const engine = agentMeta?.engine ?? extractYamlField(yamlBlock, "engine");
-  // 解析期校验（D9：未注册 id 前置暴露，不留到运行时神秘失败）。为什么在解析期而非
-  // 路由期：配置错误的根源在 .md 文件，越早报错定位越准（错误含文件路径 + 注册清单）
   if (engine !== undefined && !hasEngine(engine)) {
     throw new EngineNotFoundError(engine, listEngines(), filePath);
   }
+  return engine;
+}
 
+/** closed frontmatter 的 AgentConfig 投影（IF1 严格层优先，逐字段 legacy fallback）。 */
+function projectAgentConfig(
+  name: string,
+  body: string,
+  agentMeta: AgentMeta | null,
+  fallbacks: { modelFallback: string | undefined; toolsFallback: string[] | undefined },
+  engine: string | undefined,
+  yamlBlock: string,
+): AgentConfig {
   return {
-    config: {
-      name: agentMeta?.name ?? name,
-      systemPrompt: body,
-      model: agentMeta?.model ?? modelFallback ?? undefined,
-      thinkingLevel: extractYamlField(yamlBlock, "thinkingLevel") ?? undefined,
-      ...(engine !== undefined ? { engine } : {}),
-      tools: agentMeta?.tools && agentMeta.tools.length > 0
-        ? agentMeta.tools
-        : (toolsFallback && toolsFallback.length > 0 ? toolsFallback : undefined),
-      defaultBackground: defaultBackgroundRaw === "true" ? true : undefined,
-    },
-    meta: agentMeta,
+    name: agentMeta?.name ?? name,
+    systemPrompt: body,
+    model: agentMeta?.model ?? fallbacks.modelFallback ?? undefined,
+    thinkingLevel: extractYamlField(yamlBlock, "thinkingLevel") ?? undefined,
+    ...(engine !== undefined ? { engine } : {}),
+    tools: resolveAgentTools(agentMeta, fallbacks.toolsFallback),
+    defaultBackground: extractYamlField(yamlBlock, "defaultBackground") === "true" ? true : undefined,
   };
 }
 
+/** tools 投影：IF1 严格层非空清单优先，否则 legacy fallback 非空清单，均缺省 undefined。 */
+function resolveAgentTools(
+  agentMeta: AgentMeta | null,
+  toolsFallback: string[] | undefined,
+): string[] | undefined {
+  return agentMeta?.tools && agentMeta.tools.length > 0
+    ? agentMeta.tools
+    : (toolsFallback && toolsFallback.length > 0 ? toolsFallback : undefined);
+}
+
 /** 提取简单 `key: value` 字段，剥离引号。 */
 function extractYamlField(yaml: string, key: string): string | undefined {
   const regex = new RegExp(`^${key}:\\s*(.+)$`, "m");
@@ -255,7 +299,7 @@ type AgentFrontmatterSlice =
   | { kind: "unclosed"; yamlBlock: string }
   | { kind: "closed"; yamlBlock: string; body: string };
 
-/** frontmatter 结构切分（与 parseAgentWithMeta 同款定位逻辑，产出三态供分派）。 */
+/** frontmatter 结构切分（产出三态供分派；parseAgentWithMeta 与 parseAgentProfile 共用单点）。 */
 function splitAgentFrontmatter(text: string): AgentFrontmatterSlice {
   if (!text.startsWith(FM_DELIM)) return { kind: "none" };
   const closeIdx = text.indexOf(FM_DELIM, FM_DELIM.length);

package/src/execution/agent-result-mapper.ts

@@ -35,6 +35,9 @@ export function mapToWorkflowAgentResult(
 ): WorkflowAgentResult {
   return {
     content: r.text,
+    // [D5-③] 失败分诊标签透传（产出侧 output-collector 写入，消费侧
+    // executeAgentCall 读字段分诊）。成功路径 undefined 不落键。
+    ...(r.failureKind !== undefined ? { failureKind: r.failureKind } : {}),
     parsedOutput: r.parsedOutput,
     error: r.success ? undefined : (r.error || "Agent call failed (aborted or unknown error)"),
     durationMs: r.durationMs,