@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/__tests__/worktree-reconcile-aging.test.ts

@@ -0,0 +1,204 @@
+// worktree-reconcile-aging.test.ts —— 对账「歧义跳过」老化升级（PS-12 措施⑤）。
+//
+// 环境模式对齐 worktree-reconcile.integration.test.ts：真实 git repo + TMPDIR
+// 重定向到测试私有目录（物理面扫描根 os.tmpdir()/pi-subagents 跟随 TMPDIR）；
+// 本文件额外 mock core logger 以断言升级 warn（消息含磁盘路径与人工清理指引）。
+//
+// 语义锁定：
+// - 阈值前（连续 N-1 周期内）：保持既有低信息聚合 warn，无升级、不清理（宁延迟勿误删）；
+// - 第 N 周期：升级 warn——消息含 checkout 磁盘路径 + git worktree list 查看、
+//   worktree remove --force / branch -D 手动清理、无主残留 rm -rf 指引；
+//   结构化字段带 branch/checkout/repo/skippedCycles；升级是提醒不是动作（资源不动）；
+// - 重置语义：路径「出现对应」（自愈补写）后计数清零，重现歧义需重新连续 N 周期。
+
+import { execFileSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+import { encodeCwd } from "../path-encoding.ts";
+import { WorktreeRegistry } from "../worktree-registry.ts";
+import { RECONCILE_SKIP_ESCALATION_CYCLES, WorktreeManager } from "../worktree-manager.ts";
+
+/** 原始 TMPDIR（beforeEach 重定向、afterEach 还原）。 */
+const ORIG_TMPDIR = os.tmpdir();
+
+/** git 辅助：repo 内执行（输出 trim）。 */
+function git(repo: string, ...args: string[]): string {
+  return execFileSync("git", ["-C", repo, ...args], { encoding: "utf-8" }).trim();
+}
+
+/** 升级 warn 调用（按消息锚文本过滤）。 */
+function escalationCalls(): Array<{ msg: string; data: Record<string, unknown> }> {
+  return loggerMock.warn.mock.calls
+    .filter((c) => typeof c[0] === "string" && c[0].includes("manual cleanup may be needed"))
+    .map((c) => ({ msg: c[0] as string, data: (c[1] ?? {}) as Record<string, unknown> }));
+}
+
+describe("WorktreeManager 对账歧义跳过老化（PS-12 措施⑤）", { timeout: 30_000 }, () => {
+  let outerDir: string;
+  let agentDir: string;
+  let repo: string;
+  let enc: string;
+  let registry: WorktreeRegistry;
+  let mgr: WorktreeManager;
+
+  beforeEach(() => {
+    outerDir = fs.mkdtempSync(path.join(ORIG_TMPDIR, "wt-reconcile-aging-"));
+    process.env.TMPDIR = outerDir;
+
+    agentDir = path.join(outerDir, "agent");
+    repo = path.join(outerDir, "repo");
+    fs.mkdirSync(repo, { recursive: true });
+    git(repo, "init", "-q");
+    git(repo, "config", "user.email", "test@test.local");
+    git(repo, "config", "user.name", "test");
+    fs.writeFileSync(path.join(repo, "a.txt"), "init\n", "utf-8");
+    git(repo, "add", "-A");
+    git(repo, "commit", "-q", "-m", "init");
+
+    enc = encodeCwd(repo);
+    registry = new WorktreeRegistry(agentDir);
+    mgr = new WorktreeManager(agentDir);
+    loggerMock.warn.mockClear();
+  });
+
+  afterEach(() => {
+    process.env.TMPDIR = ORIG_TMPDIR;
+    fs.rmSync(outerDir, { recursive: true, force: true });
+  });
+
+  /** 建一个物理 worktree（绕过 WorktreeManager.create 的脏树校验，路径布局同 create）。 */
+  function makePhysicalWorktree(branch: string): string {
+    const checkout = path.join(outerDir, "pi-subagents", enc, branch);
+    git(repo, "worktree", "add", "-q", "-b", branch, checkout, "HEAD");
+    return checkout;
+  }
+
+  /** 在 <agentDir>/subagents/<enc>/sessions/ 下写一个 .alive marker。 */
+  function writeAliveMarker(sessionId: string, pid: number): void {
+    const sessions = path.join(agentDir, "subagents", enc, "sessions");
+    fs.mkdirSync(sessions, { recursive: true });
+    fs.writeFileSync(
+      path.join(sessions, `${sessionId}.jsonl.alive`),
+      JSON.stringify({ pid, id: sessionId, startedAt: Date.now() }),
+      "utf-8",
+    );
+  }
+
+  /** 真实子进程等待：等 pid 死透（isProcessAlive 翻 false，SIGKILL 后的短暂窗口）。 */
+  async function waitPidDead(pid: number): Promise<void> {
+    for (let i = 0; i < 50; i++) {
+      try {
+        process.kill(pid, 0);
+      } catch {
+        return; // ESRCH = 已死
+      }
+      await new Promise((r) => setTimeout(r, 10));
+    }
+  }
+
+  it("阈值前保持普通 warn，第 N 周期升级含磁盘路径与清理指引（资源不动）", async () => {
+    const c1 = makePhysicalWorktree("pi-sub-a1");
+    const c2 = makePhysicalWorktree("pi-sub-a2");
+    const sleeper = spawn("sleep", ["60"]);
+    try {
+      expect(sleeper.pid).toBeTruthy();
+      writeAliveMarker("s-a1", process.pid);
+      writeAliveMarker("s-a2", sleeper.pid as number);
+
+      // 阈值前（N-1 周期）：无升级消息，资源原样（宁延迟勿误删语义不变）
+      for (let i = 0; i < RECONCILE_SKIP_ESCALATION_CYCLES - 1; i++) {
+        await mgr.scan();
+      }
+      expect(escalationCalls()).toEqual([]);
+      expect(fs.existsSync(c1)).toBe(true);
+      expect(fs.existsSync(c2)).toBe(true);
+
+      // 第 N 周期：升级 warn——每个残留路径一条，含路径与人工清理指引
+      await mgr.scan();
+      const calls = escalationCalls();
+      expect(calls.length).toBe(2); // c1 / c2 各一条
+      for (const checkout of [c1, c2]) {
+        const hit = calls.find((c) => c.msg.includes(checkout));
+        expect(hit).toBeDefined();
+        expect(hit?.msg).toContain("worktree list");
+        expect(hit?.msg).toContain("worktree remove --force");
+        expect(hit?.msg).toContain("branch -D");
+        expect(hit?.msg).toContain("rm -rf");
+        expect(hit?.msg).toContain(`skipped for ${RECONCILE_SKIP_ESCALATION_CYCLES} consecutive cycles`);
+      }
+      // 结构化字段：branch/checkout/skippedCycles 可机读
+      // （repo 是 git .git 指针解析产物，macOS 上为 realpath 形态 /private/var/...）
+      const data1 = calls.find((c) => c.data.checkout === c1)?.data;
+      expect(data1?.branch).toBe("pi-sub-a1");
+      expect(data1?.repo).toBe(fs.realpathSync(repo));
+      expect(data1?.skippedCycles).toBe(RECONCILE_SKIP_ESCALATION_CYCLES);
+
+      // 升级 warn 是提醒不是清理动作：物理资源与注册表未动
+      expect(fs.existsSync(c1)).toBe(true);
+      expect(fs.existsSync(c2)).toBe(true);
+      expect(registry.load()).toEqual([]);
+    } finally {
+      sleeper.kill("SIGKILL");
+    }
+  });
+
+  it("重置语义：自愈补写（出现对应）后计数清零，重现歧义需重新连续 N 周期", async () => {
+    const c1 = makePhysicalWorktree("pi-sub-r1");
+    const c2 = makePhysicalWorktree("pi-sub-r2");
+    const sleeper = spawn("sleep", ["60"]);
+    try {
+      writeAliveMarker("s-r1", process.pid);
+      writeAliveMarker("s-r2", sleeper.pid as number);
+
+      // 累计 N-1 周期歧义（未达阈值）
+      for (let i = 0; i < RECONCILE_SKIP_ESCALATION_CYCLES - 1; i++) {
+        await mgr.scan();
+      }
+      expect(escalationCalls()).toEqual([]);
+    } finally {
+      sleeper.kill("SIGKILL");
+    }
+
+    // 出现对应：s-r2 pid 死 + c2 删除 → 1 活 pid ↔ 1 残留 → 自愈补写 c1
+    await waitPidDead(sleeper.pid as number);
+    fs.rmSync(c2, { recursive: true, force: true });
+    await mgr.scan();
+    expect(registry.load().map((e) => e.branch)).toEqual(["pi-sub-r1"]);
+    expect(escalationCalls()).toEqual([]);
+
+    // 重现歧义：c1 退出注册表 + 新残留 c3 + 新活 pid。
+    // c1 的历史歧义计数已被自愈轮清零——若未清零（陈账 N-1），下面第 1 轮就达
+    // 阈值升级；断言 N-1 轮内无升级即证明重置生效。
+    await registry.remove("pi-sub-r1");
+    const c3 = makePhysicalWorktree("pi-sub-r3");
+    const sleeper2 = spawn("sleep", ["60"]);
+    try {
+      writeAliveMarker("s-r3", sleeper2.pid as number);
+      for (let i = 0; i < RECONCILE_SKIP_ESCALATION_CYCLES - 1; i++) {
+        await mgr.scan();
+      }
+      expect(escalationCalls()).toEqual([]);
+
+      // 第 N 轮：升级（新计数从 1 起步走满阈值）
+      await mgr.scan();
+      const msgs = escalationCalls().map((c) => c.msg);
+      expect(msgs.some((m) => m.includes(c1))).toBe(true);
+      expect(msgs.some((m) => m.includes(c3))).toBe(true);
+    } finally {
+      sleeper2.kill("SIGKILL");
+    }
+  });
+});

package/src/execution/agent-registry.ts

@@ -18,7 +18,7 @@ import {
 import { normalizeRef, AGENT_REF_EXT } from "../shared/agent-ref.ts";
 import { parseResourceMeta } from "../shared/meta-parser.ts";
 import { lintAgentMeta } from "../orchestration/script-lint.ts";
-import type { AgentMeta } from "../shared/resource-meta.ts";
+import type { AgentMeta, RoutingExample } from "../shared/resource-meta.ts";
 import type { AgentConfig } from "./model-resolver.ts";
 import { hasEngine, listEngines, EngineNotFoundError } from "./engine/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");
@@ -138,6 +182,230 @@ function extractYamlField(yaml: string, key: string): string | undefined {
   return value || undefined;
 }
 
+// ============================================================
+// 宽容解析（sink 设计 D3 / U2）
+// ============================================================
+
+/**
+ * agent .md 的宽容解析结果（执行消费面全字段投影）。
+ *
+ * 双轨语义（D3 定稿）：本结构是**执行可用性**面（可用即跑），严格路由面仍是
+ * AgentMeta（注入清单可见性：缺 name/description 不进清单，由 meta !== null 表达）。
+ * 两轨分离是两宿主既有设计，本类型只是把执行侧第三份手写实现（zsw mini parser）
+ * 收敛到 core 单点。
+ */
+export interface AgentProfile {
+  /** 宽容 name：frontmatter name，缺省文件 stem（宽松语义不拒）。 */
+  name: string;
+  /** 宽容 description：frontmatter description，缺省空串（宽松语义不拒）。 */
+  description: string;
+  /** frontmatter 后正文（trim）——即 systemPrompt。 */
+  body: string;
+  /** 路由提示（严格层投影；IF1 未通过时经 legacy fallback 也不取——该资产不进清单）。 */
+  when?: string;
+  examples?: RoutingExample[];
+  // ── 执行字段全量（与 AgentConfig / AgentMeta 同名同语义）──
+  model?: string;
+  tools?: string[];
+  /** 执行引擎 id（D9 per-agent）。 */
+  engine?: string;
+  thinkingLevel?: string;
+  defaultBackground?: boolean;
+  /** turn 预算上限（D3 可选执行字段；消费优先级：显式参数 > 本字段 > 缺省）。 */
+  maxTurns?: number;
+  /** tool denylist（D3 可选执行字段，与 tools allowlist 正交）。 */
+  disallowedTools?: string[];
+  /** agent 声明依赖的 skill 名清单（D3 可选执行字段）。 */
+  skills?: string[];
+  /**
+   * IF1 严格层 meta：null = 无 frontmatter / 未闭合 / 严格校验未通过。
+   * 注入清单可见性判定归它（discoverAgents 只放行 meta 非 null 的条目——
+   * 与 pi 现装配循环口径等值）。
+   */
+  meta: AgentMeta | null;
+  /**
+   * 宽容解析降级说明（legacy fallback 生效等）。宽容语义不抛——资产异常时
+   * 返回尽力解析结果 + warnings，调用方决定呈现（错误规格表：`{ name: stem, body,
+   * warnings[] }` 宽容降级）。
+   */
+  warnings: string[];
+}
+
+/**
+ * agent .md 宽容解析（D3/U2 定稿）：无 frontmatter 不拒、name 缺省 stem、
+ * description 缺省空串、返回 body 与执行字段全量，**永不抛**。
+ *
+ * 实现基础（D3 字段形态覆盖矩阵）：
+ * - 主路径 = parseResourceMeta（eemeli/yaml 全量解析）：原生支持单行 key:value、
+ *   行内数组、block-scalar、多行 `- item` 列表；
+ * - meta=null 时（无 frontmatter / 未闭合 / yaml 整体解析失败 / IF1 严格校验未通过）
+ *   经 extractYamlField legacy fallback（仅单行 key:value 形态）兜底取执行字段，
+ *   保证「可用即跑」不因资产格式瑕疵丢失配置（先例：parseAgentWithMeta 的 MF-3
+ *   fallback）。fallback 触达时写入 warnings（warn 可见，调用方决定呈现）。
+ *
+ * 与 parseAgentWithMeta 的关系：本函数是新增导出面（执行消费面），既有
+ * parseAgentWithMeta/loadByPath 语义零改动（含 engine 未注册 throw 的解析期校验）。
+ * 本函数宽容语义不抛，故不做 engine 注册校验（执行校验归执行路径）。
+ */
+export function parseAgentProfile(text: string, filePath: string): AgentProfile {
+  const stem = path.basename(filePath, ".md");
+  const warnings: string[] = [];
+
+  // 阶段 1：结构切分（无 frontmatter / 未闭合 / 闭合三态）
+  const fm = splitAgentFrontmatter(text);
+  // 无 frontmatter → 整个内容作为 body（宽容：README 等普通 .md 也是合法 profile）
+  if (fm.kind === "none") {
+    return {
+      name: stem,
+      description: "",
+      body: text.trim(),
+      meta: null,
+      warnings,
+    };
+  }
+  if (fm.kind === "unclosed") {
+    // 未闭合 frontmatter：name 经 legacy fallback，其余全文作 body（与 parseAgentWithMeta 同判）
+    warnings.push(
+      `[agent-registry] ${filePath}: frontmatter 未闭合——name 经 legacy fallback（仅单行 key:value），全文作 body`,
+    );
+    return {
+      name: extractYamlField(fm.yamlBlock, "name") ?? stem,
+      description: "",
+      body: text.trim(),
+      meta: null,
+      warnings,
+    };
+  }
+
+  // 阶段 2：主路径 = IF1 严格层（eemeli/yaml 全量解析）
+  const meta = parseResourceMeta(text, "agent");
+  const agentMeta = meta?.kind === "agent" ? meta : null;
+  if (agentMeta !== null) {
+    return profileFromStrictMeta(agentMeta, fm.yamlBlock, fm.body, warnings);
+  }
+
+  // 阶段 3：meta=null（yaml 解析失败或 IF1 未通过）→ legacy fallback 仅单行 key:value，
+  // 执行字段不静默丢失（MF-3 先例收敛）。宽松语义：name 缺省 stem、description 缺省空串。
+  warnings.push(
+    `[agent-registry] ${filePath}: agent frontmatter 未通过严格校验（IF1：yaml 解析失败或缺 name/description）` +
+      "——执行字段经 legacy fallback（仅单行 key:value 形态）生效，结构化路由不可见，建议补 name/description",
+  );
+  return profileFromLegacyFallback(fm.yamlBlock, fm.body, stem, filePath, warnings);
+}
+
+/** 宽容解析阶段 1 的切分产物（frontmatter 结构三态）。 */
+type AgentFrontmatterSlice =
+  | { kind: "none" }
+  | { kind: "unclosed"; yamlBlock: string }
+  | { kind: "closed"; yamlBlock: string; body: string };
+
+/** 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);
+  if (closeIdx === -1) {
+    return { kind: "unclosed", yamlBlock: text.slice(FM_DELIM.length) };
+  }
+  return {
+    kind: "closed",
+    yamlBlock: text.slice(FM_DELIM.length, closeIdx),
+    body: text.slice(closeIdx + FM_DELIM.length).trim(),
+  };
+}
+
+/** 严格层（IF1 通过）的 profile 投影：AgentMeta 路由/执行字段 + 单行提取的执行配置。 */
+function profileFromStrictMeta(
+  agentMeta: AgentMeta,
+  yamlBlock: string,
+  body: string,
+  warnings: string[],
+): AgentProfile {
+  // thinkingLevel/defaultBackground 是执行配置（非 AgentMeta 字段），与
+  // parseAgentWithMeta 同位经单行提取（严格层资产同样携带这两字段的现实先例）
+  const thinkingLevelRaw = extractYamlField(yamlBlock, "thinkingLevel");
+  const defaultBackgroundRaw = extractYamlField(yamlBlock, "defaultBackground");
+  return {
+    name: agentMeta.name,
+    description: agentMeta.description,
+    body,
+    ...(agentMeta.when !== undefined ? { when: agentMeta.when } : {}),
+    ...(agentMeta.examples !== undefined ? { examples: agentMeta.examples } : {}),
+    ...(agentMeta.model !== undefined ? { model: agentMeta.model } : {}),
+    ...nonEmptyArraySpread("tools", agentMeta.tools),
+    ...(agentMeta.engine !== undefined ? { engine: agentMeta.engine } : {}),
+    ...(thinkingLevelRaw !== undefined ? { thinkingLevel: thinkingLevelRaw } : {}),
+    ...(defaultBackgroundRaw === "true" ? { defaultBackground: true } : {}),
+    ...(agentMeta.maxTurns !== undefined ? { maxTurns: agentMeta.maxTurns } : {}),
+    ...nonEmptyArraySpread("disallowedTools", agentMeta.disallowedTools),
+    ...nonEmptyArraySpread("skills", agentMeta.skills),
+    meta: agentMeta,
+    warnings,
+  };
+}
+
+/** legacy fallback 的 profile 投影（仅单行 key:value 提取；warnings 同引用收集）。 */
+function profileFromLegacyFallback(
+  yamlBlock: string,
+  body: string,
+  stem: string,
+  filePath: string,
+  warnings: string[],
+): AgentProfile {
+  const nameFallback = extractYamlField(yamlBlock, "name") ?? stem;
+  const modelFallback = extractYamlField(yamlBlock, "model");
+  const toolsFallback = parseCommaListFallback(extractYamlField(yamlBlock, "tools"));
+  const maxTurnsFallback = parseNumberFallback(extractYamlField(yamlBlock, "maxTurns"), filePath, "maxTurns", warnings);
+  const disallowedToolsFallback = parseCommaListFallback(extractYamlField(yamlBlock, "disallowedTools"));
+  const skillsFallback = parseCommaListFallback(extractYamlField(yamlBlock, "skills"));
+  const thinkingLevelFallback = extractYamlField(yamlBlock, "thinkingLevel");
+  const defaultBackgroundRaw = extractYamlField(yamlBlock, "defaultBackground");
+  const engineFallback = extractYamlField(yamlBlock, "engine");
+
+  return {
+    name: nameFallback,
+    description: "",
+    body,
+    ...(modelFallback !== undefined ? { model: modelFallback } : {}),
+    ...nonEmptyArraySpread("tools", toolsFallback),
+    ...(engineFallback !== undefined ? { engine: engineFallback } : {}),
+    ...(thinkingLevelFallback !== undefined ? { thinkingLevel: thinkingLevelFallback } : {}),
+    ...(defaultBackgroundRaw === "true" ? { defaultBackground: true } : {}),
+    ...(maxTurnsFallback !== undefined ? { maxTurns: maxTurnsFallback } : {}),
+    ...nonEmptyArraySpread("disallowedTools", disallowedToolsFallback),
+    ...nonEmptyArraySpread("skills", skillsFallback),
+    meta: null,
+    warnings,
+  };
+}
+
+/** 可选数组字段非空才带键（tools/disallowedTools/skills 的条件展开收敛，键序随展开位不变）。 */
+function nonEmptyArraySpread<T>(key: string, v: T[] | undefined): Record<string, T[]> {
+  return v !== undefined && v.length > 0 ? { [key]: v } : {};
+}
+
+/** legacy fallback 的逗号分隔列表解析（`tools: read, bash` 约定，与 parseAgentWithMeta 同构）。 */
+function parseCommaListFallback(raw: string | undefined): string[] | undefined {
+  return raw
+    ? raw.split(",").map((s) => s.trim()).filter(Boolean)
+    : undefined;
+}
+
+/** legacy fallback 的数字解析（extractYamlField 只出字符串，`maxTurns: 2` 需换算）。 */
+function parseNumberFallback(
+  raw: string | undefined,
+  filePath: string,
+  field: string,
+  warnings: string[],
+): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) {
+    warnings.push(`[agent-registry] ${filePath}: ${field} 值 "${raw}" 不是有限数字，忽略`);
+    return undefined;
+  }
+  return n;
+}
+
 // ============================================================
 // AgentRegistry
 // ============================================================

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,