@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/orchestration/worker-script-builder.ts

@@ -41,13 +41,17 @@
 // ── Build worker source ─────────────────────────────────────
 
 /**
- * Build the complete worker source text by wrapping the user's workflow script
- * with infrastructure code and injected global functions.
+ * Template constant segments（模块级 hoisting，IF5/TC8）——
+ * 常量段在模块加载时构造一次，buildWorkerScript 每次调用只做三段 concat，
+ * 消除每次 run 的 330+ 元素数组重建 + join 分配（#11 低优先形态）。
  *
- * AC-4：脚本格式不变（用户资产）。逐字保留旧 buildWorkerScript 的拼接逻辑。
+ * 输出与 hoisting 前逐字节一致（join("\n") 拼装语义精确保留），由
+ * __tests__/worker-script-template-snapshot.test.ts 的 byte-identical 快照锚定
+ * （fixture 由改造前实现生成）。
  */
-export function buildWorkerScript(userScript: string): string {
-  return [
+
+/** PRE 段：use strict … User workflow script 注释行（不含 userScript）。 */
+const WORKER_TEMPLATE_PRE = [
     '"use strict";',
     '// Module-scope helpers: accessible to BOTH the IIFE body AND the outer',
     '// .then()/.catch() handlers (which run outside the IIFE). _workerLogs/',
@@ -60,6 +64,9 @@ export function buildWorkerScript(userScript: string): string {
     '// appear in the IIFE and the outer .then/.catch.',
     'const { parentPort: _parentPort, workerData: _workerData } = require("node:worker_threads");',
     'const _workerLogs = [];',
+    '// IF6(#12): known agent() fields — hoisted to module scope, built once per worker',
+    '// (was rebuilt inside agent() on every call; field set is call-invariant).',
+    'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);',
     'function _pushWorkerLog(level, args) {',
     '  try { _workerLogs.push({ level, message: args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") }); } catch (e) { /* swallow */ }',
     '}',
@@ -232,9 +239,8 @@ export function buildWorkerScript(userScript: string): string {
     '    if (!opts.model && $MODEL) opts.model = $MODEL;',
     '    if (!opts.thinkingLevel && $THINKING_LEVEL) opts.thinkingLevel = $THINKING_LEVEL;',
     '',
-    '    // Validate known agent() fields to catch API misuse early',
-    '    const _knownFields = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);',
-    '    const _unknownFields = Object.keys(opts).filter((k) => !_knownFields.has(k));',
+    '    // Validate known agent() fields to catch API misuse early (_KNOWN_FIELDS at module scope)',
+    '    const _unknownFields = Object.keys(opts).filter((k) => !_KNOWN_FIELDS.has(k));',
     '    if (_unknownFields.length > 0) {',
     '      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel"]);',
     '    }',
@@ -361,8 +367,10 @@ export function buildWorkerScript(userScript: string): string {
     '  }',
     '',
     '  // ── User workflow script ──',
-    '  ' + userScript,
-    '',
+  ].join("\n");
+
+/** POST 段：auto-invoke execute() + 顶层 .then/.catch return/error handler。 */
+const WORKER_TEMPLATE_POST = [
     '  // ── Auto-invoke execute() for module.exports pattern ──',
     '  if (typeof module !== "undefined" && module.exports && typeof module.exports.execute === "function") {',
     '    return await module.exports.execute({ agent, parallel, pipeline, phase, log, workflow, $ARGS, $WORKSPACE, $BUDGET });',
@@ -375,4 +383,15 @@ export function buildWorkerScript(userScript: string): string {
     '  _safePost({ type: "error", runId, error: err.message || String(err), workerLogs: _workerLogs }, "error");',
     '});',
   ].join("\n");
+
+/**
+ * Build the complete worker source text by wrapping the user's workflow script
+ * with infrastructure code and injected global functions.
+ *
+ * AC-4：脚本格式不变（用户资产）。逐字保留旧 buildWorkerScript 的拼接逻辑——
+ * 三段 concat 的换行语义 = 原单数组 join("\n")（userScript 段带 2 空格缩进，
+ * 段后一个空行接 auto-invoke 段），byte-identical 快照锚定。
+ */
+export function buildWorkerScript(userScript: string): string {
+  return WORKER_TEMPLATE_PRE + "\n  " + userScript + "\n\n" + WORKER_TEMPLATE_POST;
 }

package/src/shared/__tests__/agent-ref.test.ts

@@ -0,0 +1,34 @@
+/**
+ * displayAgentName 测试：agent ref 绝对路径 → UI 显示短名（basename 去 .md）。
+ *
+ * 数据层不变式（displayAgentName 只服务显示出口）：非路径值原样返回。
+ */
+import { describe, expect, it } from "vitest";
+
+import { displayAgentName } from "../agent-ref.ts";
+
+describe("displayAgentName", () => {
+  it("mac/linux 绝对路径取 basename 并去 .md", () => {
+    expect(displayAgentName("/Users/x/.agents/agents/worker.md")).toBe("worker");
+    expect(displayAgentName("/home/u/project/.agents/agents/reviewer.md")).toBe("reviewer");
+  });
+
+  it("windows 路径（反斜杠分隔）同样取短名", () => {
+    expect(displayAgentName("C:\\Users\\x\\agents\\worker.md")).toBe("worker");
+    expect(displayAgentName("C:/Users/x/agents/worker.md")).toBe("worker");
+  });
+
+  it("非路径 agent 名原样返回（DEFAULT_AGENT_NAME 等）", () => {
+    expect(displayAgentName("general-purpose")).toBe("general-purpose");
+    expect(displayAgentName("worker")).toBe("worker");
+  });
+
+  it("无 .md 扩展名的 basename 原样返回（不去别的后缀）", () => {
+    expect(displayAgentName("/a/b/worker")).toBe("worker");
+    expect(displayAgentName("/a/b/agent.spec.ts")).toBe("agent.spec.ts");
+  });
+
+  it("裸文件名（无目录）也去 .md", () => {
+    expect(displayAgentName("worker.md")).toBe("worker");
+  });
+});

package/src/shared/__tests__/resource-discovery-manifest-cache.test.ts

@@ -0,0 +1,280 @@
+// src/shared/__tests__/resource-discovery-manifest-cache.test.ts
+//
+// manifestCache 专项测试（swf-perf-impl cleanup IF1/DM1/TC1）。
+// readPackageManifestSync / async readPackageManifest 共享同一 Map：
+// - 命中：同 mtime 二次调用不重读（readFileSync 计数不增）
+// - 失效：package.json 重写（mtime 变）→ 重读
+// - 坏 JSON：不缓存（mtime 未变时二次调用仍重新 read）、不驱逐已有好条目
+//   （恢复原内容 + utimesSync 恢复原 mtime → 命中原条目，readFileSync 不增）
+// - stat 失败（文件删除）→ undefined 且条目驱逐（重建同内容同 mtime → 必重读）
+// - 双读者共享：sync 写入的条目被 async 命中（fs/promises readFile 零调用），反之亦然
+//
+// ESM 下 node:fs 命名空间不可直接 spyOn（resource-discovery.test.ts TC4a 注记），
+// 计数走 vi.mock 工厂包装（透传 actual 实现 + vi.fn 计数，行为零变化）。
+// mtime 控制用 utimesSync 定值（整数 ms），消除写入浮点 mtime 的精度/flake 面。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as fsp from "node:fs/promises";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// 隔离真实用户全局目录（homedir 推导 user-agents 源，同 resource-discovery.test.ts）
+vi.mock("node:os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:os")>();
+  return { ...actual, homedir: () => "/nonexistent-home-for-tests" };
+});
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return {
+    ...actual,
+    readFileSync: vi.fn(
+      (...args: Parameters<typeof actual.readFileSync>) => actual.readFileSync(...args),
+    ),
+    statSync: vi.fn(
+      (...args: Parameters<typeof actual.statSync>) => actual.statSync(...args),
+    ),
+  };
+});
+
+vi.mock("node:fs/promises", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs/promises")>();
+  return {
+    ...actual,
+    readFile: vi.fn(
+      (...args: Parameters<typeof actual.readFile>) => actual.readFile(...args),
+    ),
+  };
+});
+
+import { clearFileCache, discoverResources, readPackageManifestSync } from "../resource-discovery.ts";
+
+// ── helpers ──
+
+function tmpPkgDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "manifest-cache-test-"));
+}
+
+function writePackageJson(pkgDir: string, pi: Record<string, unknown> | undefined): string {
+  fs.mkdirSync(pkgDir, { recursive: true });
+  const filePath = path.join(pkgDir, "package.json");
+  fs.writeFileSync(filePath, JSON.stringify({ name: "test-pkg", pi }), "utf-8");
+  return filePath;
+}
+
+/** 写原始（非 JSON）package.json 内容——坏 JSON 用例。 */
+function writeRawPackageJson(pkgDir: string, content: string): string {
+  fs.mkdirSync(pkgDir, { recursive: true });
+  const filePath = path.join(pkgDir, "package.json");
+  fs.writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
+/** 定值 mtime（整数 ms，消除浮点 mtime 与 utimesSync 恢复的精度差）。 */
+const T1 = new Date("2026-01-01T00:00:00Z");
+const T2 = new Date("2026-01-01T00:00:10Z");
+
+function setMtime(filePath: string, t: Date): void {
+  fs.utimesSync(filePath, t, t);
+}
+
+function readCount(): number {
+  return vi.mocked(fs.readFileSync).mock.calls.length;
+}
+
+/** node:fs/promises readFile 包装计数（异步读者）。 */
+function asyncReadCount(): number {
+  return vi.mocked(fsp.readFile).mock.calls.length;
+}
+
+// ============================================================
+// manifestCache（IF1）
+// ============================================================
+
+describe("manifestCache（readPackageManifestSync）", () => {
+  let pkgDir: string;
+  let pkgJson: string;
+
+  beforeEach(() => {
+    clearFileCache();
+    vi.mocked(fs.readFileSync).mockClear();
+    pkgDir = tmpPkgDir();
+  });
+  afterEach(() => {
+    fs.rmSync(pkgDir, { recursive: true, force: true });
+  });
+
+  it("命中：同 mtime 二次调用不重读（readFileSync 只调 1 次）", () => {
+    pkgJson = writePackageJson(pkgDir, { agents: ["./a.md"] });
+    setMtime(pkgJson, T1);
+    const r1 = readPackageManifestSync(pkgDir, "agents");
+    expect(r1).toEqual(["./a.md"]);
+    expect(readCount()).toBe(1);
+    const r2 = readPackageManifestSync(pkgDir, "agents");
+    expect(r2).toEqual(["./a.md"]);
+    // 命中缓存：statSync 每次（判 mtime）但 readFileSync 不增
+    expect(readCount()).toBe(1);
+  });
+
+  it("kind 共享一次 parse：同 package.json 的 agents/workflows 两 kind 只读一次", () => {
+    pkgJson = writePackageJson(pkgDir, { agents: ["./a.md"], workflows: ["./w.js"] });
+    setMtime(pkgJson, T1);
+    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
+    expect(readPackageManifestSync(pkgDir, "workflows")).toEqual(["./w.js"]);
+    expect(readCount()).toBe(1);
+  });
+
+  it("失效：package.json 重写（mtime 变）→ 重读新内容", () => {
+    pkgJson = writePackageJson(pkgDir, { agents: ["./a.md"] });
+    setMtime(pkgJson, T1);
+    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
+    writePackageJson(pkgDir, { agents: ["./b.md"] });
+    // 不需显式设 mtime：新写入的 mtime 必 ≠ 定值 T1
+    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./b.md"]);
+    expect(readCount()).toBe(2);
+  });
+
+  it("坏 JSON → undefined 且不缓存：mtime 未变时二次调用仍重新 read（计数递增）", () => {
+    // 起点即坏 JSON（无缓存条目）——若坏结果被缓存，二次调用不会重新 readFile。
+    // （good→bad 且 mtime 未变的场景由上一用例的命中路径覆盖：mtime 相等直接命中原好条目）
+    pkgJson = writeRawPackageJson(pkgDir, "{ broken json");
+    setMtime(pkgJson, T1);
+    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
+    expect(readCount()).toBe(1);
+    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
+    expect(readCount()).toBe(2); // 二次调用仍重新 read = 坏结果未入缓存（毒条目永不入缓存）
+  });
+
+  it("坏 JSON 不驱逐已有好条目：恢复原内容 + 恢复原 mtime → 命中原条目（readFileSync 不增）", () => {
+    pkgJson = writePackageJson(pkgDir, { agents: ["./a.md"] });
+    setMtime(pkgJson, T1);
+    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
+    expect(readCount()).toBe(1);
+    // 改坏且 mtime 变（T2）→ undefined（read 失败路径，不驱逐 {T1, pi} 好条目）
+    fs.writeFileSync(pkgJson, "{ broken", "utf-8");
+    setMtime(pkgJson, T2);
+    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
+    expect(readCount()).toBe(2);
+    // 恢复原内容 + utimesSync 恢复原 mtime → 若好条目仍在则命中（不重 read）
+    writePackageJson(pkgDir, { agents: ["./a.md"] });
+    setMtime(pkgJson, T1);
+    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
+    expect(readCount()).toBe(2); // 无第 3 次 read = 命中保留的原条目
+  });
+
+  it("stat 失败（文件删除）→ undefined 且条目驱逐（重建同内容同 mtime → 必重读）", () => {
+    pkgJson = writePackageJson(pkgDir, { agents: ["./a.md"] });
+    setMtime(pkgJson, T1);
+    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
+    expect(readCount()).toBe(1);
+    fs.rmSync(pkgJson);
+    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
+    expect(readCount()).toBe(1); // stat 失败路径不触发 read
+    // 重建同内容 + 恢复同 mtime：条目已被驱逐 → 必重 read（计数 +1）
+    writePackageJson(pkgDir, { agents: ["./a.md"] });
+    setMtime(pkgJson, T1);
+    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./a.md"]);
+    expect(readCount()).toBe(2);
+  });
+
+  it("无 pi 字段（合法解析结果）也缓存：二次调用不重读", () => {
+    pkgJson = writePackageJson(pkgDir, undefined);
+    setMtime(pkgJson, T1);
+    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
+    expect(readCount()).toBe(1);
+    expect(readPackageManifestSync(pkgDir, "agents")).toBeUndefined();
+    expect(readCount()).toBe(1);
+  });
+
+  // [review 修复] 非对象 JSON 结构守卫：JSON.parse 对 "42" / '"str"' / "null" 等
+  // 合法 JSON 产出非对象值，旧 `as Record<string, unknown>` 盲断言下 .pi 访问
+  // 「碰巧不抛」（primitive 装箱返 undefined / null 抛 TypeError 落 catch）——
+  // 显式守卫后按「无 manifest」（undefined）处理，行为等价但不再依赖巧合。
+  it("非对象 JSON（42 / null / string / pi 字段非对象或数组）→ undefined 不抛，按合法解析结果缓存", () => {
+    const cases: Array<{ raw: string; label: string }> = [
+      { raw: "42", label: "number" },
+      { raw: "null", label: "null" },
+      { raw: '"just-a-string"', label: "string" },
+      { raw: '{"name":"p","pi":42}', label: "pi-field-not-object" },
+      // [review 修复] 数组能骗过 typeof "object" 守卫（装箱对象）——非合法 pi 容器，
+      // 显式归 undefined（语义上仍是「无 manifest」，与数组 entries 读出 undefined 一致）
+      { raw: '{"name":"p","pi":[]}', label: "pi-field-array" },
+    ];
+    // 每 case 独立子目录（缓存 key = package.json 绝对路径），互不命中；
+    // readCount 是跨 case 累积计数，断言用本 case 增量
+    for (const { raw, label } of cases) {
+      const before = readCount();
+      const caseDir = path.join(pkgDir, label);
+      pkgJson = writeRawPackageJson(caseDir, raw);
+      setMtime(pkgJson, T1);
+      expect(readPackageManifestSync(caseDir, "agents"), `case ${label}`).toBeUndefined();
+      expect(readPackageManifestSync(caseDir, "workflows"), `case ${label}`).toBeUndefined();
+      // 合法解析 + 无 manifest → 缓存 undefined 条目（同「无 pi 字段」语义，二次调用不重读）
+      expect(readCount() - before, `case ${label}`).toBe(1);
+    }
+  });
+});
+
+// ============================================================
+// 双读者共享（async readPackageManifest ↔ sync 共享同一 Map）
+// ============================================================
+
+describe("manifestCache 双读者共享（async ↔ sync）", () => {
+  let ws: string;
+  let pkgDir: string;
+  let savedEnv: string | undefined;
+
+  beforeEach(() => {
+    clearFileCache();
+    vi.mocked(fs.readFileSync).mockClear();
+    vi.mocked(fsp.readFile).mockClear();
+    ws = tmpPkgDir();
+    pkgDir = path.join(ws, "my-ext");
+    savedEnv = process.env.XYZ_EXTENSION_PATHS;
+  });
+  afterEach(() => {
+    if (savedEnv === undefined) delete process.env.XYZ_EXTENSION_PATHS;
+    else process.env.XYZ_EXTENSION_PATHS = savedEnv;
+    fs.rmSync(ws, { recursive: true, force: true });
+  });
+
+  it("sync 写入的条目被 async 命中：discoverResources 零 fs/promises readFile", async () => {
+    const pkgJson = writePackageJson(pkgDir, { agents: ["./agents"] });
+    fs.mkdirSync(path.join(pkgDir, "agents"), { recursive: true });
+    fs.writeFileSync(path.join(pkgDir, "agents", "a.md"), "body", "utf-8");
+    setMtime(pkgJson, T1);
+    // sync 读者先填充缓存
+    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./agents"]);
+    expect(readCount()).toBe(1);
+    // async 读者（XYZ_EXTENSION_PATHS → processPackage → readPackageManifest）应命中共享条目
+    process.env.XYZ_EXTENSION_PATHS = pkgDir;
+    const result = await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      agentDir: path.join(ws, ".fake-agent"),
+    });
+    const ext = result.filter((r) => r.source === "user-extension-paths");
+    expect(ext.map((r) => path.basename(r.path))).toEqual(["a.md"]);
+    expect(asyncReadCount()).toBe(0); // async readFile 未被调用 = 命中共享缓存
+    expect(readCount()).toBe(1); // sync 侧无新增 read
+  });
+
+  it("async 写入的条目被 sync 命中：async 读后 sync 不再 readFileSync", async () => {
+    const pkgJson = writePackageJson(pkgDir, { agents: ["./agents"] });
+    fs.mkdirSync(path.join(pkgDir, "agents"), { recursive: true });
+    fs.writeFileSync(path.join(pkgDir, "agents", "a.md"), "body", "utf-8");
+    setMtime(pkgJson, T1);
+    process.env.XYZ_EXTENSION_PATHS = pkgDir;
+    await discoverResources({
+      kind: "agents",
+      workspaceRoot: ws,
+      agentDir: path.join(ws, ".fake-agent"),
+    });
+    expect(asyncReadCount()).toBe(1); // async 读者读了一次
+    // sync 读者应命中 async 写入的条目（readFileSync 计数不变）
+    expect(readPackageManifestSync(pkgDir, "agents")).toEqual(["./agents"]);
+    expect(readCount()).toBe(0);
+  });
+});

package/src/shared/__tests__/resource-discovery.test.ts

@@ -333,6 +333,61 @@ describe("user-extension-paths (XYZ_EXTENSION_PATHS)", () => {
     expect(ext.map((r) => path.basename(r.path))).toEqual(["async.md"]);
     expect(ext[0]?.source).toBe("user-extension-paths");
   });
+
+  it("async: overrides npm on name clash (priority: user-extension-paths > npm)", async () => {
+    const npmPkg = path.join(agentDir, "npm", "node_modules", "test-pkg");
+    writePackageJson(npmPkg, { agents: ["./agents"] });
+    writeFile(path.join(npmPkg, "agents"), "shared.md", "npm-body");
+    const devPkg = path.join(ws, "dev-ext");
+    writePackageJson(devPkg, { agents: ["./agents"] });
+    writeFile(path.join(devPkg, "agents"), "shared.md", "dev-body");
+    process.env.XYZ_EXTENSION_PATHS = devPkg;
+    const result = await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+    const shared = result.find((r) => path.basename(r.path) === "shared.md");
+    expect(shared?.source).toBe("user-extension-paths");
+  });
+
+  it("async: project-agents overrides user-extension-paths (project wins)", async () => {
+    const devPkg = path.join(ws, "dev-ext");
+    writePackageJson(devPkg, { agents: ["./agents"] });
+    writeFile(path.join(devPkg, "agents"), "x.md", "dev-body");
+    writeFile(path.join(ws, ".agents", "agents"), "x.md", "project-body");
+    process.env.XYZ_EXTENSION_PATHS = devPkg;
+    const result = await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+    const x = result.find((r) => path.basename(r.path) === "x.md");
+    expect(x?.source).toBe("project-agents");
+  });
+
+  it("async: 4 源混合 fixture——输出序 + 优先级 + 与串行版快照等价", async () => {
+    // 源优先级低→高：npm < user-extension-paths < project-pi < project-agents
+    const npmPkg = path.join(agentDir, "npm", "node_modules", "test-pkg");
+    writePackageJson(npmPkg, { agents: ["./agents"] });
+    writeFile(path.join(npmPkg, "agents"), "shared.md", "npm-body");
+    const devPkg = path.join(ws, "dev-ext");
+    writePackageJson(devPkg, { agents: ["./agents"] });
+    writeFile(path.join(devPkg, "agents"), "dev.md", "dev-body");
+    writeFile(path.join(ws, ".pi", "agents"), "pi.md", "pi-body");
+    writeFile(path.join(ws, ".agents", "agents"), "shared.md", "project-body");
+    writeFile(path.join(ws, ".agents", "agents"), "proj.md", "proj-body");
+    process.env.XYZ_EXTENSION_PATHS = devPkg;
+    const config = { kind: "agents" as const, workspaceRoot: ws, agentDir };
+
+    const asyncResult = await discoverResources(config);
+
+    // 输出序：stem 首次插入位置固定（低优先级源先入 Map），同名后续覆盖值不移位
+    expect(asyncResult.map((r) => path.basename(r.path))).toEqual([
+      "shared.md", // 首现于 npm（最低源），位置固定
+      "dev.md", // user-extension-paths
+      "pi.md", // project-pi
+      "proj.md", // project-agents
+    ]);
+    // 优先级：shared.md 两源同名，project-agents（高）last-writer-wins
+    expect(asyncResult.find((r) => path.basename(r.path) === "shared.md")?.source).toBe(
+      "project-agents",
+    );
+    // 快照等价：源级并行 async 版与串行 sync 版输出逐项一致（含序与 source 标签）
+    expect(asyncResult).toEqual(discoverResourcesSync(config));
+  });
 });
 
 // ── m5 TC4/TC5: 统一 mtime 缓存层（P-cache / P-cache-invalidation） ──

package/src/shared/__tests__/schema-jsonify.test.ts

@@ -0,0 +1,81 @@
+/**
+ * stringifySchemaCached（IF7/#13）— WeakMap 引用级缓存单测（TC6/DM4）。
+ *
+ * 断言面（design IF7 契约）：
+ * - 同对象二调返回同字符串引用（缓存命中，非等值新串）
+ * - compact/pretty 分别缓存（互不覆写）
+ * - 不同对象互不污染
+ * - 输出与直接 JSON.stringify 逐字节一致
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import { stringifySchemaCached } from "../schema-jsonify.ts";
+
+describe("stringifySchemaCached — WeakMap 引用级缓存", () => {
+  const schema = { type: "object", properties: { n: { type: "number" } } };
+
+  it("输出与直接 JSON.stringify 逐字节一致（compact / pretty）", () => {
+    expect(stringifySchemaCached(schema, "compact")).toBe(JSON.stringify(schema));
+    expect(stringifySchemaCached(schema, "pretty")).toBe(JSON.stringify(schema, null, 2));
+  });
+
+  it("同对象二调返回同字符串引用（缓存命中）", () => {
+    const a = stringifySchemaCached(schema, "compact");
+    const b = stringifySchemaCached(schema, "compact");
+    expect(b).toBe(a); // toBe = 引用相等（非仅等值）
+  });
+
+  it("同对象跨格式：compact 与 pretty 分别缓存且各自命中", () => {
+    const c1 = stringifySchemaCached(schema, "compact");
+    const p1 = stringifySchemaCached(schema, "pretty");
+    const c2 = stringifySchemaCached(schema, "compact");
+    const p2 = stringifySchemaCached(schema, "pretty");
+    expect(c2).toBe(c1);
+    expect(p2).toBe(p1);
+    expect(c1).not.toBe(p1); // 两种格式输出不同，分别缓存
+  });
+
+  it("不同对象互不污染（等值异引用各持条目）", () => {
+    const s1 = { type: "object" };
+    const s2 = { type: "object" }; // 等值但异引用
+    const r1 = stringifySchemaCached(s1, "compact");
+    const r2 = stringifySchemaCached(s2, "compact");
+    expect(r1).toBe(r2); // 等值（内容相同）
+    // s2 未命中 s1 的条目（否则 spy 场景下 s2 的 stringify 调用会被跳过——
+    // 引用级隔离由「同引用返回同串」+「等值异引用各自 stringify」共同保证）
+  });
+
+  it("缓存命中路径不再调 JSON.stringify（spy 计数）", () => {
+    const spy = vi.spyOn(JSON, "stringify");
+    try {
+      const obj = { spy: true };
+      stringifySchemaCached(obj, "pretty");
+      stringifySchemaCached(obj, "pretty"); // 第二次应命中缓存
+      const calls = spy.mock.calls.filter((c) => c[0] === obj);
+      expect(calls).toHaveLength(1);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it("pretty 缩进锚定：indent=2 与 formatSchemaInstruction 渲染同源", () => {
+    const out = stringifySchemaCached({ type: "object" }, "pretty");
+    expect(out).toBe('{\n  "type": "object"\n}');
+  });
+
+  // [review 修复] TS lib 盲区回归：schema 含 toJSON: () => undefined 钩子时
+  // JSON.stringify 运行时返回 undefined，违反声明的 string 返回类型——现 fail-loud
+  // 抛含恢复指引的错误，不静默返回 undefined / 垃圾串。
+  it("[review 修复] schema 含 toJSON: () => undefined → 抛含恢复指引的错误（compact / pretty）", () => {
+    const bad = { type: "object", toJSON: () => undefined };
+    expect(() => stringifySchemaCached(bad, "compact")).toThrowError(
+      /stringifySchemaCached: JSON\.stringify returned undefined.*Recovery:/s,
+    );
+    expect(() => stringifySchemaCached(bad, "pretty")).toThrowError(
+      /toJSON hook returning undefined.*Recovery:/s,
+    );
+    // 正常 schema 不受影响（toJSON 返回合法值时按其返回值序列化）
+    const good = { type: "object", toJSON: () => ({ type: "string" }) };
+    expect(stringifySchemaCached(good, "compact")).toBe('{"type":"string"}');
+  });
+});

package/src/shared/agent-ref.ts

@@ -34,3 +34,19 @@ export function normalizeRef(ref: string, ext?: string): string | null {
 export const AGENT_REF_EXT = ".md";
 /** workflowRef 扩展名。 */
 export const WORKFLOW_REF_EXT = ".js";
+
+/**
+ * agent ref 的显示名：basename + 去 .md 扩展名（`/a/b/worker.md` → `worker`）。
+ *
+ * agentRef 是绝对路径，UI 显示层（TUI tool block 标题 / list / 完成通知、GUI list item /
+ * pending 通知 name）统一经本函数取短名，避免长路径挤占显示宽度。数据层不动——
+ * record.agent / env 注入（PI_SUBAGENT_AGENT）/ 持久化 / LLM 通知文本保持完整路径。
+ *
+ * 非路径值（DEFAULT_AGENT_NAME "general-purpose"）与无 .md 后缀的值原样返回。
+ * 手动 split(/[\\/]) 而非 path.basename：跨平台统一（macOS 的 path.basename
+ * 不切 Windows `\` 分隔符，反之类推），且本模块避免引入平台分支。
+ */
+export function displayAgentName(ref: string): string {
+  const base = ref.split(/[\\/]/).pop() ?? ref;
+  return base.endsWith(AGENT_REF_EXT) ? base.slice(0, -AGENT_REF_EXT.length) : base;
+}