@zhushanwen/pi-subagent-workflow 8.14.7 → 9.0.0

package/src/host/__tests__/pi-host.test.ts

@@ -14,9 +14,10 @@
 
 import { join, dirname } from "node:path";
 import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, afterAll, describe, expect, it, vi } from "vitest";
 
 // ── hoisted mocks（vi.mock 工厂 hoisting 不能引用外部 let/const） ──
 
@@ -43,12 +44,31 @@ vi.mock("@zhushanwen/pi-extension-logger", () => extensionLoggerMock);
 vi.mock("@zhushanwen/pi-pending-notifications", () => pendingNotificationsMock);
 vi.mock("@zhushanwen/session-delivery", () => sessionDeliveryMock);
 
+// 端到端用例（P5 staged 入扫描面）隔离真实用户目录：resource-discovery 用 homedir()
+// 推导 user-agents 根（~/.agents/workflows），不 mock 会让「内置条目存在/两次一致」
+// 断言依赖本机用户资产状态（resource-discovery.test.ts 同款手法）。
+const mockHomeDir = vi.hoisted(() => {
+  const fs = require("node:fs");
+  const os = require("node:os");
+  const path = require("node:path");
+  return fs.mkdtempSync(path.join(os.tmpdir(), "pihost-p5-home-"));
+});
+vi.mock("node:os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:os")>();
+  return { ...actual, homedir: () => mockHomeDir };
+});
+
+import { discoverResources } from "@zhushanwen/subagent-core";
+// clearFileCache 仅测试消费（barrel 收窄面外）——测试深路径经 vitest alias 正则
+// 重写到 core src 物理路径（B-2/D3 既有先例形态；specifier 不含 src/ 段）
+import { clearFileCache } from "@zhushanwen/subagent-core/shared/resource-discovery.ts";
+
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { countActiveFromEntries } from "@zhushanwen/pi-pending-notifications";
 import { createDelivery } from "@zhushanwen/session-delivery";
 
-import { createPiHostServices, createPiNotifyDomainPorts } from "../pi-host.ts";
+import { createPiHostServices, createPiNotifyDomainPorts, resolveGrandchildExtensionPaths } from "../pi-host.ts";
 
 beforeEach(() => {
   vi.mocked(getAgentDir).mockClear();
@@ -69,11 +89,23 @@ describe("createPiHostServices.discoveryRoots（与现推导逐项一致）", ()
   // skill-discovery.ts resolveSkillPath（join(getAgentDir(), "skills") +
   // join(getAgentDir(), "npm/node_modules")）。根列表按优先级低→高排列（D2）。
   const AGENT_DIR = "/fake/agent-dir";
+  const argvSaved = process.argv;
 
   function stubAgentDir(): void {
     vi.mocked(getAgentDir).mockReturnValue(AGENT_DIR);
   }
 
+  beforeEach(() => {
+    // 独立 pi 形态基线（argv 无 --extension）：P5 扫描根修正后 npm/npm-dev 根的
+    // 指向随形态分流——本 describe 全部锚定独立态推导，runner argv 形态不构成
+    // 契约，显式钉死防漂移（taiji 态断言见下方专属 describe）。
+    process.argv = ["node", "/pi", "--mode", "rpc"];
+  });
+
+  afterEach(() => {
+    process.argv = argvSaved;
+  });
+
   it("agents 四根：user-pi → npm → npm-dev → core 包父目录（C5⑥，source npm 追加末位）", () => {
     stubAgentDir();
     const roots = createPiHostServices().discoveryRoots?.().agents;
@@ -104,17 +136,33 @@ describe("createPiHostServices.discoveryRoots（与现推导逐项一致）", ()
     expect(existsSync(join(coreRoot!.dir, "subagent-core", "agents"))).toBe(true);
   });
 
-  it("workflows 三根：与 agents 同构，末级目录名切换为 workflows", () => {
+  it("workflows 四根：与 agents 同构，末级目录名切换为 workflows，第 4 根 core 包父目录（P5 staged 副本入扫描面）", () => {
     stubAgentDir();
     const roots = createPiHostServices().discoveryRoots?.().workflows;
 
+    const require = createRequire(import.meta.url);
+    const anchor = require.resolve("@zhushanwen/subagent-core/workflows/README.md");
+    const coreParent = dirname(dirname(dirname(anchor)));
+
     expect(roots).toEqual([
       { dir: join(AGENT_DIR, "workflows"), source: "user-pi" },
       { dir: join(AGENT_DIR, "npm", "node_modules"), source: "npm" },
       { dir: join(AGENT_DIR, "extensions"), source: "npm-dev" },
+      // P5：workflows kind 的「刻意不注入」禁区拆除——内置 workflow 随 core 包入
+      // 扫描面（P-C6 裁决见 pi-host.ts 注释）
+      { dir: coreParent, source: "npm" },
     ]);
   });
 
+  it("workflows 第 4 根下 subagent-core/workflows/ 存在内置 workflow 脚本（可派发前提）", () => {
+    stubAgentDir();
+    const roots = createPiHostServices().discoveryRoots?.().workflows;
+    const coreRoot = roots?.[3];
+
+    expect(coreRoot?.source).toBe("npm");
+    expect(existsSync(join(coreRoot!.dir, "subagent-core", "workflows"))).toBe(true);
+  });
+
   it("skills 两根：user-pi + npm，无 npm-dev（对齐 skill-discovery 现状）", () => {
     stubAgentDir();
     const roots = createPiHostServices().discoveryRoots?.().skills;
@@ -137,6 +185,78 @@ describe("createPiHostServices.discoveryRoots（与现推导逐项一致）", ()
   });
 });
 
+describe("createPiHostServices.discoveryRoots（P5 D4-2 扫描根修正：taiji 态形态感知）", () => {
+  const AGENT_DIR = "/fake/data-dir/agent";
+  const argvSaved = process.argv;
+
+  function stubAgentDir(): void {
+    vi.mocked(getAgentDir).mockReturnValue(AGENT_DIR);
+  }
+
+  afterEach(() => {
+    process.argv = argvSaved;
+  });
+
+  /** taiji 宿主注入态 argv（runtime spawn 主 pi 恒带 --extension staged 全量集）。 */
+  function withTaijiArgv(fn: () => void): void {
+    process.argv = [
+      "node", "/pi",
+      "--mode", "rpc",
+      "--extension", "/staged/resources/extensions/@zhushanwen/pi-subagent-workflow",
+    ];
+    fn();
+  }
+
+  it("taiji 态：npm/npm-dev 根改指 agentDir 父目录（= dataDir，实际安装目录）", () => {
+    stubAgentDir();
+    withTaijiArgv(() => {
+      const roots = createPiHostServices().discoveryRoots?.();
+      const installBase = dirname(AGENT_DIR); // /fake/data-dir
+
+      // agents kind
+      expect(roots?.agents).toEqual([
+        { dir: join(AGENT_DIR, "agents"), source: "user-pi" },
+        { dir: join(installBase, "npm", "node_modules"), source: "npm" },
+        { dir: join(installBase, "extensions"), source: "npm-dev" },
+        expect.objectContaining({ source: "npm" }), // core 根（锚点解析，见独立态用例）
+      ]);
+      // workflows kind（core 根注入同理）
+      expect(roots?.workflows?.slice(0, 3)).toEqual([
+        { dir: join(AGENT_DIR, "workflows"), source: "user-pi" },
+        { dir: join(installBase, "npm", "node_modules"), source: "npm" },
+        { dir: join(installBase, "extensions"), source: "npm-dev" },
+      ]);
+    });
+  });
+
+  it("独立态：npm/npm-dev 根保留 getAgentDir() 派生的 pi 语义根（现状不变）", () => {
+    stubAgentDir();
+    process.argv = ["node", "/pi", "--mode", "rpc"];
+    const roots = createPiHostServices().discoveryRoots?.();
+
+    expect(roots?.agents?.slice(0, 3)).toEqual([
+      { dir: join(AGENT_DIR, "agents"), source: "user-pi" },
+      { dir: join(AGENT_DIR, "npm", "node_modules"), source: "npm" },
+      { dir: join(AGENT_DIR, "extensions"), source: "npm-dev" },
+    ]);
+    expect(roots?.workflows?.slice(0, 3)).toEqual([
+      { dir: join(AGENT_DIR, "workflows"), source: "user-pi" },
+      { dir: join(AGENT_DIR, "npm", "node_modules"), source: "npm" },
+      { dir: join(AGENT_DIR, "extensions"), source: "npm-dev" },
+    ]);
+  });
+
+  it("user-pi 根两形态同指 agentDir（taiji 态布局迁移不动 user 级语义）", () => {
+    stubAgentDir();
+    withTaijiArgv(() => {
+      expect(createPiHostServices().discoveryRoots?.().workflows?.[0]).toEqual({
+        dir: join(AGENT_DIR, "workflows"),
+        source: "user-pi",
+      });
+    });
+  });
+});
+
 describe("createPiHostServices.dataRoot（每次现取 getAgentDir）", () => {
   it("返回 getAgentDir() 本身（env 覆盖段与 warn-once 留 core data-dir）", () => {
     vi.mocked(getAgentDir).mockReturnValue("/data/root");
@@ -196,6 +316,170 @@ describe("createPiHostServices.log（桥接 pi-extension-logger）", () => {
   });
 });
 
+describe("resolveGrandchildExtensionPaths / createPiHostServices.extensionPaths（[D2] 双形态注入源）", () => {
+  const argvSaved = process.argv;
+
+  function withArgv(argv: string[], fn: () => void): void {
+    process.argv = argv;
+    try {
+      fn();
+    } finally {
+      process.argv = argvSaved;
+    }
+  }
+
+  it("宿主形态：主进程 argv --extension 全量（extension-service 下发集）→ 白名单收窄仅 structured-output", () => {
+    // taiji 宿主形态：runtime spawn 主 pi 时 --extension = getExtensionPaths 全量 staged 集
+    const argv = [
+      "node", "/pi",
+      "--mode", "rpc", "--no-extensions", "--approve",
+      "--extension", "/staged/resources/extensions/@zhushanwen/pi-subagent-workflow",
+      "--extension=/staged/resources/extensions/@zhushanwen/pi-structured-output",
+      "--extension", "/staged/resources/extensions/@zhushanwen/pi-goal",
+      "--extension", "/staged/resources/extensions/@zhushanwen/pi-structured-output/index.js",
+    ];
+    expect(resolveGrandchildExtensionPaths(argv, () => undefined)).toEqual([
+      "/staged/resources/extensions/@zhushanwen/pi-structured-output",
+      "/staged/resources/extensions/@zhushanwen/pi-structured-output/index.js",
+    ]);
+  });
+
+  it("宿主形态 dev 源码布局：extensions/universal/structured-output（目录与入口文件形态）命中收窄集", () => {
+    // dev 下 runtime extension-service 下发的是源码目录（无 @zhushanwen scope 段）——
+    // L4 A1 根因回归锁：白名单须识别 dev 源码布局别名段，否则孙进程扩展集恒空。
+    const argv = [
+      "node", "/pi",
+      "--mode", "rpc", "--no-extensions", "--approve",
+      "--extension", "/repo/extensions/universal/subagent-workflow",
+      "--extension", "/repo/extensions/universal/structured-output",
+      "--extension", "/repo/extensions/universal/structured-output/index.js",
+      "--extension", "/repo/extensions/taiji/system-prompt",
+    ];
+    expect(resolveGrandchildExtensionPaths(argv, () => undefined)).toEqual([
+      "/repo/extensions/universal/structured-output",
+      "/repo/extensions/universal/structured-output/index.js",
+    ]);
+  });
+
+  it("宿主形态 dev 布局形似误报不命中（尾段同名前缀目录 / 同名异分组不误收）", () => {
+    const argv = [
+      "node", "/pi",
+      "--mode", "rpc",
+      "--extension", "/repo/extensions/universal/structured-output-lookalike",
+      "--extension", "/some/other/structured-output",
+      "--extension", "/repo/extensions/universal/structured-output-extra/index.js",
+    ];
+    expect(resolveGrandchildExtensionPaths(argv, () => undefined)).toEqual([]);
+  });
+
+  it("宿主形态解析不误吃其他 flag 值（--skill 值被跳过、真 flag 不吃值、单 - 路径是值）", () => {
+    const argv = [
+      "node", "/pi",
+      "--mode", "rpc",
+      "--skill", "@zhushanwen/pi-structured-output-skill-lookalike",
+      "--extension", "--approve", // 后跟真 flag 不吃值
+      "--extension", "-weird-dir/@zhushanwen/pi-structured-output", // 单 - 开头路径是值（原 MF-7a）
+      "some positional prompt",
+    ];
+    expect(resolveGrandchildExtensionPaths(argv, () => undefined)).toEqual([
+      "-weird-dir/@zhushanwen/pi-structured-output",
+    ]);
+  });
+
+  it("独立形态：argv 无 --extension → optional peerDep sibling 解析回退（resolvePeer 命中）", () => {
+    expect(resolveGrandchildExtensionPaths(["node", "/pi", "--mode", "rpc"], () => "/npm/node_modules/@zhushanwen/pi-structured-output")).toEqual([
+      "/npm/node_modules/@zhushanwen/pi-structured-output",
+    ]);
+  });
+
+  it("独立形态真实解析链：workspace 布局下 peerDep sibling 可解析（createRequire 实测命中包根）", () => {
+    withArgv(["node", "/pi", "--mode", "rpc"], () => {
+      const paths = createPiHostServices().extensionPaths?.();
+      expect(paths).toHaveLength(1);
+      // workspace 布局下 pnpm symlink 解析到源目录（目录名 structured-output，
+      // 无 @zhushanwen 段——npm 安装形态则命中 node_modules/@zhushanwen/… 布局）
+      expect(paths![0]).toMatch(/structured-output$/);
+    });
+  });
+
+  it("双源皆空（argv 无 --extension + peerDep 未安装）→ 空数组不炸", () => {
+    expect(resolveGrandchildExtensionPaths(["node", "/pi", "--mode", "rpc"], () => undefined)).toEqual([]);
+  });
+
+  // e2e 门（faux 轨装配）：TAIJI_E2E=1 且 <agentDir>/extensions/faux-llm-ext.ts 在盘
+  // 时追加进孙进程显式 --extension 集；非 e2e 环境该路径恒被收窄（生产语义不变）。
+  describe("e2e 门：faux-llm-ext 放行（TAIJI_E2E=1）", () => {
+    let fauxAgentDir: string;
+
+    beforeEach(() => {
+      fauxAgentDir = mkdtempSync(join(tmpdir(), "pihost-e2e-faux-"));
+    });
+
+    afterEach(() => {
+      rmSync(fauxAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+      vi.unstubAllEnvs();
+    });
+
+    function seedFauxExt(): string {
+      const extDir = join(fauxAgentDir, "extensions");
+      mkdirSync(extDir, { recursive: true });
+      const p = join(extDir, "faux-llm-ext.ts");
+      writeFileSync(p, "// faux provider stub\n");
+      return p;
+    }
+
+    it("TAIJI_E2E=1 + faux-llm-ext.ts 在盘 → 追加进白名单收窄集末尾", () => {
+      const fauxPath = seedFauxExt();
+      vi.mocked(getAgentDir).mockReturnValue(fauxAgentDir);
+      vi.stubEnv("TAIJI_E2E", "1");
+      const argv = [
+        "node", "/pi", "--mode", "rpc",
+        "--extension", "/staged/resources/extensions/@zhushanwen/pi-structured-output",
+      ];
+      expect(resolveGrandchildExtensionPaths(argv, () => undefined)).toEqual([
+        "/staged/resources/extensions/@zhushanwen/pi-structured-output",
+        fauxPath,
+      ]);
+    });
+
+    it("非 e2e（env 缺失）仍收窄：faux-llm-ext 在盘不追加，argv 显式携带也被白名单排除", () => {
+      seedFauxExt();
+      vi.mocked(getAgentDir).mockReturnValue(fauxAgentDir);
+      vi.stubEnv("TAIJI_E2E", "");
+      const argv = [
+        "node", "/pi", "--mode", "rpc",
+        "--extension", "/staged/resources/extensions/@zhushanwen/pi-structured-output",
+        "--extension", join(fauxAgentDir, "extensions", "faux-llm-ext.ts"),
+      ];
+      expect(resolveGrandchildExtensionPaths(argv, () => undefined)).toEqual([
+        "/staged/resources/extensions/@zhushanwen/pi-structured-output",
+      ]);
+    });
+
+    it("TAIJI_E2E=1 但 faux-llm-ext.ts 不在盘 → 不追加（非 faux e2e 用例行为不变）", () => {
+      vi.mocked(getAgentDir).mockReturnValue(fauxAgentDir);
+      vi.stubEnv("TAIJI_E2E", "1");
+      const argv = [
+        "node", "/pi", "--mode", "rpc",
+        "--extension", "/staged/resources/extensions/@zhushanwen/pi-structured-output",
+      ];
+      expect(resolveGrandchildExtensionPaths(argv, () => undefined)).toEqual([
+        "/staged/resources/extensions/@zhushanwen/pi-structured-output",
+      ]);
+    });
+  });
+
+  it("惰性求值：每次调用现解析（argv 变更后结果跟随，configureCore 只挂函数引用）", () => {
+    const host = createPiHostServices();
+    withArgv(["node", "/pi", "--mode", "rpc"], () => {
+      expect(host.extensionPaths?.()).not.toContain("/staged/x");
+    });
+    withArgv(["node", "/pi", "--extension", "/staged/@zhushanwen/pi-structured-output"], () => {
+      expect(host.extensionPaths?.()).toEqual(["/staged/@zhushanwen/pi-structured-output"]);
+    });
+  });
+});
+
 describe("createPiNotifyDomainPorts.countActiveFromEntries（适配读 .count）", () => {
 	it("拆 CountActiveResult.count 为 number（core 端口契约），entries 透传（缺省过滤基准 undefined = 不过滤）", () => {
 		const entries: unknown[] = [{ customType: "pending:register" }];
@@ -222,6 +506,51 @@ describe("createPiNotifyDomainPorts.countActiveFromEntries（适配读 .count）
 		vi.mocked(countActiveFromEntries).mockReturnValue({ count: 0, ids: [], entries: [] });
 		expect(createPiNotifyDomainPorts().countActiveFromEntries?.([])).toBe(0);
 	});
+
+	// ── 读侧过滤②（per-call 基准）装配冒烟（自 src/__tests__/pi-host-notify-ports.test.ts 迁入）──
+	// [W4 读侧过滤② / F1] countActiveFromEntries 第二参（core 端口契约 CountActivePortOptions）
+	// 透传 pending-notifications 的 currentSessionId——传入时按「register entry 的
+	// sessionId ≠ 基准 → 跳过」过滤（fork 继承的父级注册残留不进后代判定差集）；
+	// 缺省不过滤（向后兼容）。差集语义权威在 pending-notifications 包自身，这两条用
+	// 真实实现（importActual，文件级 mock 面内恢复）验证 createPiNotifyDomainPorts
+	// 装配贯通 + per-call 基准形态（本 describe 前三条的 mockReturnValue 在用例体内
+	// 后置覆盖，与该钩子不冲突）。基准来源 [F1]：core 读侧按「被读 entries 所属
+	// session」提供——本装配在扩展启动时一次定型，factory 定型表达不了 per-call 基准。
+	beforeEach(async () => {
+		const actual = await vi.importActual<typeof import("@zhushanwen/pi-pending-notifications")>(
+			"@zhushanwen/pi-pending-notifications",
+		);
+		vi.mocked(countActiveFromEntries).mockImplementation(actual.countActiveFromEntries);
+	});
+
+	/** pending:register entry 最小夹具（真实 countActiveFromEntries 可消费的形状）。 */
+	function registerEntry(id: string, type: string, sessionId: string): unknown {
+		return {
+			type: "custom",
+			customType: "pending:register",
+			data: { id, type, name: id, registeredAt: 1, sessionId },
+		};
+	}
+
+	it("调用时传 currentSessionId → 跨 session 残留不进后代判定差集", () => {
+		const entries = [
+			registerEntry("bg-parent", "subagent", "sess-parent"),
+			registerEntry("wf-parent", "workflow", "sess-parent"),
+			registerEntry("bg-own", "subagent", "sess-child"),
+		];
+		const ports = createPiNotifyDomainPorts();
+		expect(ports.countActiveFromEntries?.(entries, { currentSessionId: "sess-child" })).toBe(1);
+	});
+
+	it("调用时不传基准 → 不过滤（向后兼容：无基准调用方零改动）", () => {
+		const entries = [
+			registerEntry("bg-parent", "subagent", "sess-parent"),
+			registerEntry("wf-parent", "workflow", "sess-parent"),
+			registerEntry("bg-own", "subagent", "sess-child"),
+		];
+		const ports = createPiNotifyDomainPorts();
+		expect(ports.countActiveFromEntries?.(entries)).toBe(3);
+	});
 });
 
 describe("createPiNotifyDomainPorts.createDelivery（透传 session-delivery）", () => {
@@ -244,3 +573,88 @@ describe("createPiNotifyDomainPorts.createDelivery（透传 session-delivery）"
     expect(result).toBe(fakeHandle);
   });
 });
+
+// ──────────────────────────────────────────────────────────────
+// P5 staged workflows 入扫描面（端到端）：taiji 态 roots → discoverResources
+// 验收条款 b：location 可派发（<location> = 真实存在的脚本路径）+ 同环境两次
+// 扫描 location 形态确定（P-C6 裁决「实际路径直渲染」的稳定性构造性证据）。
+// ──────────────────────────────────────────────────────────────
+
+describe("P5 staged workflows 入扫描面（端到端）", () => {
+  const AGENT_DIR = "/fake/data-dir/agent";
+  const argvSaved = process.argv;
+  let ws: string;
+
+  function taijiWorkflowsRoots(): ReturnType<NonNullable<ReturnType<typeof createPiHostServices>["discoveryRoots"]>["workflows"]> {
+    vi.mocked(getAgentDir).mockReturnValue(AGENT_DIR);
+    process.argv = [
+      "node", "/pi",
+      "--mode", "rpc",
+      "--extension", "/staged/resources/extensions/@zhushanwen/pi-subagent-workflow",
+    ];
+    return createPiHostServices().discoveryRoots?.().workflows ?? [];
+  }
+
+  beforeEach(() => {
+    ws = mkdtempSync(join(tmpdir(), "pihost-p5-ws-"));
+  });
+
+  afterEach(() => {
+    process.argv = argvSaved;
+    rmSync(ws, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+    clearFileCache();
+  });
+
+  it("内置 workflow 条目被发现且 path 指向真实存在的脚本（location 可派发）", async () => {
+    const discovered = await discoverResources({
+      kind: "workflows",
+      workspaceRoot: ws,
+      hostRoots: taijiWorkflowsRoots(),
+      includeTmp: true,
+    });
+
+    const builtin = discovered.filter((r) => r.path.includes("subagent-core/workflows"));
+    expect(builtin.length).toBeGreaterThan(0);
+    for (const r of builtin) {
+      expect(r.available).toBe(true);
+      // <location> 渲染源 = r.path——可派发 = 文件真实存在
+      expect(existsSync(r.path)).toBe(true);
+      expect(r.path.endsWith(".js")).toBe(true);
+    }
+    // 内置代表脚本（review-fix-loop = workflow 域核心脚本）在扫描面内
+    expect(builtin.some((r) => r.path.endsWith("review-fix-loop.js"))).toBe(true);
+  });
+
+  it("同环境两次扫描（含缓存清空重建）location 形态确定（字节稳定断言）", async () => {
+    const scan = (): Promise<ReturnType<typeof discoverResources>> =>
+      discoverResources({
+        kind: "workflows",
+        workspaceRoot: ws,
+        hostRoots: taijiWorkflowsRoots(),
+        includeTmp: true,
+      });
+
+    const first = await scan();
+    clearFileCache(); // 强制重建（不走 mtime/workspaceRoot 缓存——重建路径也确定）
+    const second = await scan();
+
+    // readdir 枚举序无契约（discoverResources 返回按扫描插入序）——确定性断言
+    // 以 path 排序投影比较（条目集合与形态稳定，序不在契约内）
+    const sorted = (rs: Awaited<ReturnType<typeof discoverResources>>) =>
+      rs.map((r) => ({ path: r.path, source: r.source, available: r.available })).sort((a, b) => (a.path < b.path ? -1 : 1));
+    expect(sorted(second)).toEqual(sorted(first));
+    const builtinPaths = first
+      .filter((r) => r.path.includes("subagent-core/workflows"))
+      .map((r) => r.path)
+      .sort();
+    // 同环境两次扫描的 <location> 渲染源逐字节一致（staged 路径在 session 内不变——
+    // KV-cache 契约的构造性证据，P-C6 裁决「实际路径直渲染」的稳定性前提）
+    expect(
+      second.filter((r) => r.path.includes("subagent-core/workflows")).map((r) => r.path).sort(),
+    ).toEqual(builtinPaths);
+  });
+});
+
+afterAll(() => {
+  rmSync(mockHomeDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+});

package/src/host/inflight-reporter.ts

@@ -26,12 +26,12 @@
 // （session_start 是 pi 启动序列里最早带 ctx 的钩子 = 「session 就绪」，即设计所指
 // 加载完成时点；不挂任何懒触发（无 subagent 的 session 也必上报）。
 //
-// 失败语义（D5 缺席语义②，2026-09-13 oe-audit 修订）：select 失败（超时/通道异常/
-// 非确认回包）折叠后延迟重试，**累计 MAX_REPORT_ATTEMPTS 次放弃**（原「重试直至
-// 成功一次」的无界语义为「旧版 runtime」版本错配场景设计——该场景已被同 bundle
-// 发布 + pi 随 runtime 退出销毁两条事实证伪；有界化的防挂死兜底对齐 plugin-bridge
-// MAX_SYNC_ATTEMPTS 形态。session_start 首帧早于 runtime adapter attach 的竞态
-// （R2 实证）在 30×2s=60s 窗口内必然自愈）。送达判据 = runtime resolve 的确认回包
+// 失败语义（D5 缺席语义②）：select 失败（超时/通道异常/非确认回包）折叠后延迟重试，
+// **累计 MAX_REPORT_ATTEMPTS（3）次放弃**。上限刻意取小（增强面降级）：GUI live
+// 在途镜像短暂滞后可接受，重试 3 次封顶后放弃，不做长尾可达保证——子任务完成通知
+// 另有账本必达通道，不依赖此镜像。session_start 首帧早于 runtime adapter attach 的
+// 竞态（R2 实证）在 3×2s=6s 窗口内自愈，错过窗口即放弃。送达判据 = runtime resolve
+// 的确认回包
 // （INFLIGHT_REPORT_ACK）——fire-and-forget 下 resolve(undefined) 与超时不可区分，
 // 靠显式 ack 区分「已送达」与「无路由」；放弃后镜像按 absent-report 走 errs 推迟
 // （30min 有界），不丢 errs-safe 兜底。
@@ -44,15 +44,18 @@ import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 /** select 通道级超时（控制面单请求，秒级校准——超时默认原则规则 19）。取值对齐
  *  plugin-bridge 启动 sync 的 2s 自愈闸：session_start 首帧可能早于 runtime adapter
- *  attach（R2 实证），超时折叠后重试必然自愈；fire-and-forget 帧不留 pending 挂死面。 */
+ *  attach（R2 实证），超时折叠后靠有限次重试覆盖 attach 竞态窗口（约 6s，见
+ *  MAX_REPORT_ATTEMPTS）；fire-and-forget 帧不留 pending 挂死面。 */
 const SELECT_TIMEOUT_MS = 2_000;
 
 /** 失败重试退避（对齐 plugin-bridge SYNC_RETRY_MS 控制面节奏）。 */
 const RETRY_DELAY_MS = 2_000;
 
-/** 累计失败放弃上限（对齐 plugin-bridge MAX_SYNC_ATTEMPTS：60s 窗口覆盖 attach 竞态，
- *  有界防 rpc-but-非-taiji orchestrator 场景的永久空转）。 */
-const MAX_REPORT_ATTEMPTS = 30;
+/** 累计失败放弃上限（刻意取小——增强面降级）：GUI live 在途镜像短暂滞后可接受，
+ *  3 次封顶（约 6s）后放弃，不做长尾可达保证；完成通知另有账本必达通道，不依赖
+ *  此镜像。重试窗口同时覆盖 session_start 首帧早于 runtime adapter attach 的竞态
+ *  （R2 实证），并有界防 rpc-but-非-taiji orchestrator 场景的永久空转。 */
+const MAX_REPORT_ATTEMPTS = 3;
 
 /** 在途上报器（组合根 index.ts 持有；per-factory 实例，session_start/shutdown 驱动）。 */
 export interface InFlightReporter {