@zhushanwen/subagent-core 0.2.0 → 0.4.0

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";
 
@@ -138,6 +138,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 同款定位逻辑，产出三态供分派）。 */
+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/agents-assembly.ts

@@ -0,0 +1,88 @@
+// src/execution/agents-assembly.ts
+//
+// agent 装配函数（sink 设计 U2 / A6）：发现 → parseAgentProfile → frontmatter name
+// 去重 → 码点序，warn 口径内聚。workflow 侧 discoverWorkflows（config-loader）的
+// 对称面——第三宿主仅凭该函数即可「列 agents」（G3/S5），无需复刻装配循环。
+//
+// 与 pi 壳装配循环（subagent-list-injector.discoverAllAgents）的等值口径：
+// - 清单可见性 = IF1 严格层（profile.meta !== null）——缺 name/description 的资产
+//   不进清单（注入投影「路由可见性」双轨语义，D3 定稿；宽容解析只服务执行消费面）；
+// - warn 口径内聚：仅「有 frontmatter 但严格校验未通过」才 warn——README 等无
+//   frontmatter 的 .md 静默跳过（每 turn 扫描不刷屏，pi m5 评审先例）；
+// - 扫描 / 遮蔽语义归 shared/resource-discovery（ADR-031），本文件零扫描逻辑。
+
+import type { AgentEntry } from "../shared/injection-render.ts";
+import { sortByCodepoint } from "../shared/injection-render.ts";
+import { discoverResources, getCachedFileContent } from "../shared/resource-discovery.ts";
+import type { DiscoveryRoot } from "../core/host-services.ts";
+import { getLogger } from "../core/logger.ts";
+import { parseAgentProfile } from "./agent-registry.ts";
+
+const logger = getLogger("agents-assembly");
+
+/**
+ * 发现并列出全部可用 agent（U2/A6 装配函数）。
+ *
+ * 流程：discoverResources（按优先级低→高，last-writer-wins）→ 逐文件
+ * parseAgentProfile → 仅 IF1 严格层通过（profile.meta !== null）的条目进清单 →
+ * 按 frontmatter name 去重（高优先级靠后覆盖，Map 后写胜）→ name 码点序输出
+ * （KV-cache 契约：顺序与 readdir 枚举序解耦，重建结果逐字节一致）。
+ *
+ * 抛错面（如实声明）：单文件读失败仅记日志跳过；目录不存在返回空列表；但底层
+ * discoverResources 的不可恢复扫描错误会原样向上传播（readdir 遇权限拒绝、
+ * EMFILE 竞态等——resource-discovery 自述 "Throws on unrecoverable scan errors"，
+ * Promise.all 首个 reject 即整体拒绝），调用方需自行兜底。
+ *
+ * @param workspaceRoot 项目根（findWorkspaceRoot 推导结果）
+ * @param hostRoots 宿主注入发现根（pi 壳 = getAgentDir 三根；无则传 []——
+ *                  user-agents/project-agents 硬编码槽仍生效，与 ScanConfig 语义一致）。
+ *                  注意：hostRoots 之外还有四个硬编码根恒进入扫描，无法经参数关闭——
+ *                  `~/.agents/agents`、`<workspaceRoot>/.pi/agents`、
+ *                  `<workspaceRoot>/.agents/agents` 与 `XYZ_EXTENSION_PATHS`
+ *                  环境变量展开的扩展源码路径（resource-discovery buildScanTargets
+ *                  固定槽位，注入 hostRoots 只是增列而非替换扫描面）
+ */
+export async function discoverAgents(
+  workspaceRoot: string,
+  hostRoots: DiscoveryRoot[],
+): Promise<AgentEntry[]> {
+  const resources = await discoverResources({
+    kind: "agents",
+    workspaceRoot,
+    hostRoots,
+  });
+
+  const agentMap = new Map<string, AgentEntry>();
+  for (const resource of resources) {
+    // manifest 校验失败的包整体占位（available=false），不进清单
+    if (!resource.available) continue;
+
+    const content = getCachedFileContent(resource.path);
+    if (content === null) {
+      // 单文件读失败不阻断整条 agent 列表装配
+      logger.error(`[agents-assembly] skip unreadable agent file ${resource.path}`);
+      continue;
+    }
+
+    // 宽容解析（执行消费面单点）；清单可见性按严格层 meta 判定
+    const profile = parseAgentProfile(content, resource.path);
+    if (profile.meta !== null) {
+      agentMap.set(profile.name, {
+        name: profile.name,
+        description: profile.description,
+        ...(profile.when !== undefined ? { when: profile.when } : {}),
+        ...(profile.examples !== undefined ? { examples: profile.examples } : {}),
+        path: resource.path,
+      });
+    } else if (content.trimStart().startsWith("---")) {
+      // 仅「有 frontmatter 但严格校验未通过」才 warn——无 frontmatter 的 README 等
+      // 普通 .md 静默跳过（pi m5 评审先例：缺 name/description 或单条 examples 非法
+      // 致整体 reject 时作者需要知道，普通文档不需要）。
+      logger.warn(
+        `[agents-assembly] ${resource.path}: agent frontmatter 解析失败（IF1 校验不通过）——agent 未进清单`,
+      );
+    }
+  }
+
+  return sortByCodepoint([...agentMap.values()], (a) => a.name);
+}

package/src/execution/concurrency-pool.ts

@@ -14,9 +14,25 @@ interface QueueEntry {
   signal?: AbortSignal;
 }
 
+/**
+ * 排队策略（D7/U4）：release 时从等待队列放行哪个条目。策略差异是宿主声明的
+ * 有意决策（pi=priority / zsw=strict-fifo），保留为参数而非消灭（见 sink 设计
+ * subagent-core-sink-design.md §3.3 D7）。
+ *
+ * - `"priority"`（缺省）：priority 值最小（0=最高）者优先，同优先级按入队序（FIFO）。
+ *   与 pi 既有行为等值。
+ * - `"strict-fifo"`：忽略 priority，严格按入队顺序（seq）放行。纯 FIFO 语义，
+ *   供 zsw 侧等需要「先到先得、不许插队」语义的宿主消费。
+ */
+export type QueuePolicy = "priority" | "strict-fifo";
+
 /** 并发池接口（可注入，便于测试 mock）。 */
 export interface ConcurrencyPool {
-  /** 按优先级排队获取槽位（0=最高）。可选 effectiveMaxConcurrent 覆盖实例级默认配额。可选 AbortSignal 在 abort 时 reject 排队条目。 */
+  /**
+   * 排队获取槽位（priority 0=最高；"strict-fifo" 策略下该值仅记录不参与出队选择，
+   * 见 createConcurrencyPool）。可选 effectiveMaxConcurrent 覆盖实例级默认配额。
+   * 可选 AbortSignal 在 abort 时 reject 排队条目。
+   */
   acquire(priority: number, effectiveMaxConcurrent?: number, signal?: AbortSignal): Promise<void>;
   /** 归还槽位。必须无条件执行（finally）。 */
   release(): void;
@@ -27,27 +43,40 @@ export interface ConcurrencyPool {
 }
 
 /**
- * 默认实现：maxConcurrent 槽位 + 优先级队列。
+ * 默认实现：maxConcurrent 槽位 + 可策略化排队队列。
  *
  *   acquire(priority, effectiveMaxConcurrent?):
  *     effective = effectiveMaxConcurrent ?? maxConcurrent
  *     active < effective → active++, resolve
- *     否则 → 入队 { priority, resolve, seq }, 队列按 priority 升序 + seq FIFO
+ *     否则 → 入队 { priority, resolve, seq }
  *
  *   release():
- *     queue 非空 → 出队最高优先级 resolve（active 不变）
+ *     queue 非空 → 按 queuePolicy 选一个条目出队 resolve（active 不变）：
+ *       - "priority"：priority 升序 + 同优先级 seq FIFO
+ *       - "strict-fifo"：纯 seq FIFO（priority 仅记录）
  *     queue 空 → active--（防下溢）
+ *
+ *   已知契约边界（审查 S-2 登记）：分层配额（effectiveMaxConcurrent）仅在
+ *   acquire 时点判定；release 授予排队条目时不复查其 effective——即活跃数
+ *   仍 ≥ 条目 effective 时，单次释放也可能授予该条目（pi 运行时既有行为，
+ *   concurrency-pool.test T-A2 锚定）。需要严格分层隔离的宿主应在条目侧
+ *   自行保证，勿依赖 release 时点复查。
+ *
+ * 类保留内部消费（subagent-service 深路径）；对外导出面走 createConcurrencyPool
+ * 工厂（对象参数 + 策略枚举，不暴露本类名与位置参数构造——D7/U4 裁决）。
  */
 export class DefaultConcurrencyPool implements ConcurrencyPool {
   private _active = 0;
   private readonly queue: QueueEntry[] = [];
   private seqCounter = 0;
+  private readonly queuePolicy: QueuePolicy;
 
   /** 下限 1——maxConcurrent=0 会让 acquire 永久排队死锁（C3 修复）。 */
   readonly maxConcurrent: number;
 
-  constructor(maxConcurrent: number) {
+  constructor(maxConcurrent: number, queuePolicy: QueuePolicy = "priority") {
     this.maxConcurrent = Math.max(1, maxConcurrent);
+    this.queuePolicy = queuePolicy;
   }
 
   acquire(priority: number, effectiveMaxConcurrent?: number, signal?: AbortSignal): Promise<void> {
@@ -86,14 +115,24 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
     });
   }
 
+  /**
+   * 出队候选比较：cur 是否优于 best（release 时选谁获得释放的槽位）。
+   * 策略单一分派点——新增策略只需在此分支，acquire/abort/clamp 逻辑策略无关。
+   */
+  private isBetterCandidate(cur: QueueEntry, best: QueueEntry): boolean {
+    if (this.queuePolicy === "strict-fifo") {
+      // 纯 FIFO：seq 单调递增，先入队者 seq 必更小——priority 完全不参与
+      return cur.seq < best.seq;
+    }
+    // priority：取优先级最高（priority 最小）的；同优先级 FIFO（seq 最小）
+    return cur.priority < best.priority || (cur.priority === best.priority && cur.seq < best.seq);
+  }
+
   release(): void {
     if (this.queue.length > 0) {
-      // 取优先级最高（priority 最小）的；同优先级 FIFO（seq 最小）
       let bestIdx = 0;
       for (let i = 1; i < this.queue.length; i++) {
-        const cur = this.queue[i];
-        const best = this.queue[bestIdx];
-        if (cur.priority < best.priority || (cur.priority === best.priority && cur.seq < best.seq)) {
+        if (this.isBetterCandidate(this.queue[i], this.queue[bestIdx])) {
           bestIdx = i;
         }
       }
@@ -114,3 +153,26 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
     return this._active;
   }
 }
+
+/** createConcurrencyPool 选项（对象参数构造——导出面禁止位置参数歧义，D7/U4）。 */
+export interface CreateConcurrencyPoolOptions {
+  /** 实例级最大并发配额。0/负数 clamp 到 1（防 acquire 永久排队死锁，C3 修复语义）。 */
+  maxConcurrent: number;
+  /**
+   * 排队策略（见 QueuePolicy）。缺省 `"priority"`——与 pi 既有消费
+   * （`new DefaultConcurrencyPool(n)`）行为逐点等值，缺省即零回归。
+   */
+  queuePolicy?: QueuePolicy;
+}
+
+/**
+ * 并发池工厂（D7/U4 导出面）：宿主经此创建并发池，无需感知实现类。
+ *
+ * 返回 ConcurrencyPool 接口而非 DefaultConcurrencyPool——barrel 导出面只认
+ * 「对象参数 + 策略枚举」，实现类可内部替换，策略差异（pi=priority /
+ * zsw=strict-fifo）显式化为参数而非两份复刻实现（深度分层公式与下限常量单源，
+ * 公式见类注释与 slots 消费方）。
+ */
+export function createConcurrencyPool(options: CreateConcurrencyPoolOptions): ConcurrencyPool {
+  return new DefaultConcurrencyPool(options.maxConcurrent, options.queuePolicy ?? "priority");
+}