@zhushanwen/pi-subagent-workflow 8.2.0 → 8.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.2.0",
+  "version": "8.3.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -49,15 +49,15 @@
     "yaml": "^2.9.0",
     "@xyz-agent/extension-protocol": "0.6.0",
     "@xyz-agent/session-delivery": "0.2.0",
-    "@zhushanwen/pi-extension-logger": "0.2.2",
-    "@zhushanwen/pi-file-lock": "0.1.1"
+    "@zhushanwen/pi-extension-logger": "0.3.0",
+    "@zhushanwen/pi-file-lock": "0.1.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.1",
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@earendil-works/pi-tui": "^0.84.1",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.3.4",
+    "@zhushanwen/pi-pending-notifications": "0.3.5",
     "@zhushanwen/pi-structured-output": "5.0.2"
   },
   "peerDependenciesMeta": {

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

@@ -6,12 +6,24 @@
 //   - headless（json/print/undefined）：返回 undefined（不注入 handler）
 //   - TUI：fire-and-forget 回 ack 不透传；dialog 进 dialogQueue 串行
 //   - GUI（rpc）：fire-and-forget 直接调 realHandler；dialog 进 dialogQueue 串行
-// realHandler 路由：channel 命中 → channelHandler（经 coerceUiResponse 形变）；未命中 → defaultDialogForward（cancelled）。
+// realHandler 路由：channel 命中 → channelHandler（经 coerceUiResponse 形变）；未命中 → defaultDialogForward（dialog 转发结果，fire-and-forget 转发 ctx.ui.* 后回 ack，未知 method warn + ack）。
 // 测接口契约，不测实现细节。
 
 import type { ExtensionContext, ExtensionMode } from "@earendil-works/pi-coding-agent";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+  },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => loggerMock,
+}));
+
 import { DialogGlobalQueue, type UiRequest } from "../dialog-queue.ts";
 import { type ChannelHandler,createUiChannelRegistry } from "../ui-channels.ts";
 import { createUiRequestHandlerForMode } from "../ui-request-handler-factory.ts";
@@ -31,6 +43,35 @@ function makeCtx(mode: ExtensionMode): ExtensionContext {
   } as ExtensionContext;
 }
 
+/** 带 mock ctx.ui 的 ExtensionContext（GUI fire-and-forget 转发测试用）。
+ *  dialog method（select/confirm/input/editor）返回 undefined/true/"" 兜底，
+ *  fire-and-forget method（notify/setStatus/setWidget/setTitle/setEditorText）是 void spy。 */
+function makeCtxWithUi(mode: ExtensionMode = "rpc"): ExtensionContext & { ui: Record<string, ReturnType<typeof vi.fn>> } {
+  const ui: Record<string, ReturnType<typeof vi.fn>> = {
+    select: vi.fn(async () => undefined),
+    confirm: vi.fn(async () => true),
+    input: vi.fn(async () => ""),
+    editor: vi.fn(async () => ""),
+    notify: vi.fn(),
+    setStatus: vi.fn(),
+    setWidget: vi.fn(),
+    setTitle: vi.fn(),
+    setEditorText: vi.fn(),
+  };
+  return {
+    cwd: "/tmp/test",
+    mode,
+    sessionManager: {
+      getSessionId: () => "s1",
+      getSessionFile: () => undefined,
+      getSessionDir: () => "/tmp/test/sessions",
+    },
+    modelRegistry: undefined,
+    model: undefined,
+    ui,
+  } as unknown as ExtensionContext & { ui: Record<string, ReturnType<typeof vi.fn>> };
+}
+
 function dialogReq(id: string, channel?: string): UiRequest {
   return { method: "select", id, title: `q-${id}`, ...(channel ? { channel } : {}) };
 }
@@ -44,6 +85,7 @@ beforeEach(() => {
   vi.useFakeTimers();
   vi.spyOn(console, "warn").mockImplementation(() => {});
   vi.spyOn(console, "error").mockImplementation(() => {});
+  loggerMock.warn.mockClear();
 });
 
 afterEach(() => {
@@ -99,12 +141,14 @@ describe("createUiRequestHandlerForMode — GUI（rpc）模式透传", () => {
     const queue = new DialogGlobalQueue();
     const enqueueSpy = vi.spyOn(queue, "enqueue");
 
-    const handler = createUiRequestHandlerForMode(makeCtx("rpc"), registry, queue)!;
-    // notify 无 channel → realHandler → defaultDialogForward（cancelled）
+    const ctx = makeCtxWithUi("rpc");
+    const handler = createUiRequestHandlerForMode(ctx, registry, queue)!;
+    // notify 无 channel → realHandler → defaultDialogForward → case "notify" → {ack:true}
     const resp = await handler(fireAndForgetReq("f1"));
 
     expect(enqueueSpy).not.toHaveBeenCalled();
-    expect(resp).toEqual({ cancelled: true });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.notify).toHaveBeenCalledWith("n-f1", "info");
   });
 
   it("dialog（select 无 channel）→ 进 dialogQueue", async () => {
@@ -135,11 +179,14 @@ describe("createUiRequestHandlerForMode — channel 业务路由", () => {
     expect(resp).toEqual({ value: "from-channel" });
   });
 
-  it("channel 未命中 → defaultDialogForward（stub cancelled）", async () => {
+  it("channel 未命中 → defaultDialogForward（fire-and-forget 走 ack）", async () => {
+    const ctx = makeCtxWithUi("rpc");
     const handler = createUiRequestHandlerForMode(
-      makeCtx("rpc"), createUiChannelRegistry(), new DialogGlobalQueue())!;
+      ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
     const resp = await handler({ method: "notify", id: "f1", message: "m", channel: "unknown" });
-    expect(resp).toEqual({ cancelled: true });
+    // notify 是 fire-and-forget，channel miss 后走 defaultDialogForward 的 notify case → ack
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.notify).toHaveBeenCalledWith("m", "info");
   });
 });
 
@@ -164,3 +211,160 @@ describe("createUiRequestHandlerForMode — coerceUiResponse 形变", () => {
     expect(await callWithChannel(null)).toEqual({ cancelled: true });
   });
 });
+
+// ── P1：GUI fire-and-forget 分类转发（§3.2 映射表 + §3.7 D1/D2） ──
+describe("defaultDialogForward — fire-and-forget 分类转发", () => {
+  function makeHandler(ctx: ExtensionContext) {
+    return createUiRequestHandlerForMode(
+      ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
+  }
+
+  // (a) 五个 case 转发调用与 ack 返回
+  it("notify → ctx.ui.notify + {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "notify", id: "n1", message: "hello" });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.notify).toHaveBeenCalledTimes(1);
+    expect(ctx.ui.notify).toHaveBeenCalledWith("hello", "info");
+  });
+
+  it("setStatus → ctx.ui.setStatus + {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "setStatus", id: "s1", statusKey: "progress", statusText: "50%" });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.setStatus).toHaveBeenCalledTimes(1);
+    expect(ctx.ui.setStatus).toHaveBeenCalledWith("progress", "50%");
+  });
+
+  it("setWidget（channel=undefined）→ ctx.ui.setWidget 含 placement + {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({
+      method: "setWidget", id: "w1",
+      widgetKey: "my-widget", widgetLines: ["line1", "line2"],
+      widgetPlacement: "belowEditor",
+    });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.setWidget).toHaveBeenCalledTimes(1);
+    expect(ctx.ui.setWidget).toHaveBeenCalledWith("my-widget", ["line1", "line2"], { placement: "belowEditor" });
+  });
+
+  it("setTitle → ctx.ui.setTitle + {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "setTitle", id: "t1", title: "My Title" });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.setTitle).toHaveBeenCalledTimes(1);
+    expect(ctx.ui.setTitle).toHaveBeenCalledWith("My Title");
+  });
+
+  it("set_editor_text → ctx.ui.setEditorText + {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "set_editor_text", id: "e1", text: "some code" });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.setEditorText).toHaveBeenCalledTimes(1);
+    expect(ctx.ui.setEditorText).toHaveBeenCalledWith("some code");
+  });
+
+  // (b) notifyType 收窄三档 + 非法值 fallback info
+  it.each([
+    ["info", "info"],
+    ["warning", "warning"],
+    ["error", "error"],
+  ] as const)("notifyType='%s' → 透传 '%s'", async (input, expected) => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    await handler({ method: "notify", id: "n1", message: "m", notifyType: input });
+    expect(ctx.ui.notify).toHaveBeenCalledWith("m", expected);
+  });
+
+  it("notifyType 非法值 → fallback 'info'", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    await handler({ method: "notify", id: "n1", message: "m", notifyType: "debug" });
+    expect(ctx.ui.notify).toHaveBeenCalledWith("m", "info");
+  });
+
+  it("notifyType undefined → fallback 'info'", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    await handler({ method: "notify", id: "n1", message: "m" });
+    expect(ctx.ui.notify).toHaveBeenCalledWith("m", "info");
+  });
+
+  // (c) setWidget 两分支
+  it("setWidget channel='gui_widget' → 不调 ctx.ui.setWidget，回 {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({
+      method: "setWidget", id: "w1",
+      widgetKey: "gui-w", widgetLines: ["\0XYZ_GUI_WIDGET:{...}"],
+      channel: "gui_widget",
+    });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.setWidget).not.toHaveBeenCalled();
+  });
+
+  it("setWidget channel=undefined → 转发含 placement", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    await handler({
+      method: "setWidget", id: "w1",
+      widgetKey: "k", widgetLines: ["a"],
+      widgetPlacement: "aboveEditor",
+    });
+    expect(ctx.ui.setWidget).toHaveBeenCalledWith("k", ["a"], { placement: "aboveEditor" });
+  });
+
+  // (d) 未知 method warn + ack
+  it("未知 method → logger.warn + {ack:true}（非 cancelled）", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "futureMethod", id: "x1" });
+    expect(resp).toEqual({ ack: true });
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining("unknown method"),
+      expect.objectContaining({ detail: { method: "futureMethod", id: "x1" } }),
+    );
+  });
+
+  // (e) dialog 既有 case 不回归（select/confirm 代表）
+  it("select 无 channel → 调 ctx.ui.select + 透传 value", async () => {
+    const ctx = makeCtxWithUi();
+    ctx.ui.select.mockResolvedValueOnce("picked");
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "select", id: "d1", title: "Choose", options: ["a", "b"] });
+    expect(resp).toEqual({ value: "picked" });
+    expect(ctx.ui.select).toHaveBeenCalledWith("Choose", ["a", "b"]);
+  });
+
+  it("confirm 无 channel → 调 ctx.ui.confirm + 透传 confirmed", async () => {
+    const ctx = makeCtxWithUi();
+    ctx.ui.confirm.mockResolvedValueOnce(false);
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "confirm", id: "d2", title: "Sure?", message: "Go?" });
+    expect(resp).toEqual({ confirmed: false });
+    expect(ctx.ui.confirm).toHaveBeenCalledWith("Sure?", "Go?");
+  });
+});
+
+// ── 确认 createUiRequestHandlerForMode 未改动（TUI 行为零变化） ──
+describe("createUiRequestHandlerForMode — TUI 零回归", () => {
+  it("TUI 下所有 fire-and-forget method 均回 ack 且不调 ctx.ui", async () => {
+    const methods = ["notify", "setStatus", "setWidget", "setTitle", "set_editor_text"];
+    for (const method of methods) {
+      const ctx = makeCtxWithUi("tui");
+      const handler = createUiRequestHandlerForMode(
+        ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
+      const resp = await handler({ method, id: "t1" });
+      expect(resp).toEqual({ ack: true });
+      // TUI 不透传，ctx.ui 方法不应被调用
+      for (const fn of Object.values(ctx.ui)) {
+        expect(fn).not.toHaveBeenCalled();
+      }
+    }
+  });
+});

package/src/execution/session-pending.ts

@@ -16,6 +16,9 @@
 import * as fs from "node:fs";
 
 import { countActiveFromEntries } from "@zhushanwen/pi-pending-notifications";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("subagents");
 
 /** 后代刚完成（unregister）后，notify 唤醒父 agent 可能仍在路上（triggerTurn 的
  *  steer/followUp 经 sendMessage → agent 队列排空（agent-session.js:1081-1087），
@@ -147,7 +150,7 @@ export function readActivePendingFromSessionFile(
       }
     } catch {
       // 截断行/坏行跳过——不影响其余 entry 的差集判定（罕见：append 中途崩溃）
-      console.debug("[session-pending] skipped malformed pending line in", sessionFile);
+      logger.debug("skipped malformed pending line", { sessionFile });
     }
   }
 

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

@@ -163,13 +163,50 @@ async function defaultDialogForward(
         return { cancelled: true };
       }
     }
+    // ── fire-and-forget 类（§3.2 映射表：GUI 模式下由 createUiRequestHandlerForMode 直接转发）
+    // 子进程 rpc-mode 发出的 fire-and-forget method，channel miss 后落到此处。
+    // 全部回 {ack:true}（fire-and-forget 语义：子进程不等响应）。
+    case "notify": {
+      // notifyType 运行时收窄：UiRequest.notifyType 是宽 string，ctx.ui.notify 要字面量联合。
+      // 非法值 fallback "info"（pi 侧也会静默降级 info，此处显式 fallback 避免类型不安全）。
+      const rawType = req.notifyType;
+      const notifyType = rawType === "info" || rawType === "warning" || rawType === "error"
+        ? rawType
+        : "info";
+      ui.notify(req.message ?? "", notifyType);
+      return { ack: true };
+    }
+    case "setStatus": {
+      ui.setStatus(req.statusKey ?? "", req.statusText);
+      return { ack: true };
+    }
+    case "setWidget": {
+      // setWidget channel-miss 语义（§3.2 D1）：
+      //   req.channel === "gui_widget"（带 marker 但 channel 未注册）→ 不转发（marker 行无渲染意义）
+      //   req.channel === undefined（普通 widget）→ 转发文本行到主 agent
+      // channel 命中 registry 时由 createRealHandler 优先走 channel handler，不进这里。
+      if (req.channel === "gui_widget") {
+        return { ack: true };
+      }
+      ui.setWidget(req.widgetKey ?? "", req.widgetLines, { placement: req.widgetPlacement });
+      return { ack: true };
+    }
+    case "setTitle": {
+      ui.setTitle(req.title ?? "");
+      return { ack: true };
+    }
+    case "set_editor_text": {
+      ui.setEditorText(req.text ?? "");
+      return { ack: true };
+    }
     default: {
-      // 未知 dialog method（非 select/confirm/input/editor）——保守 cancelled 不阻塞子进程
+      // 未知 method（非 dialog 非 fire-and-forget）——保留 warn（协议演进信号，P3 限流兜底），
+      // 回 ack（落到 default 的一定不是 dialog，fire-and-forget 正确应答是 ack，与 TUI 分支先例一致）。
       logger.warn(
-        "[subagents] defaultDialogForward: unknown dialog method",
+        "[subagents] defaultDialogForward: unknown method",
         { detail: { method: req.method, id: req.id } },
       );
-      return { cancelled: true };
+      return { ack: true };
     }
   }
 }

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

@@ -11,9 +11,18 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 // 隔离真实用户全局目录：resource-discovery 用 homedir() 推导 user-agents 源
 // （~/.agents/agents/），测试环境可能存在真实 agent 文件（如 tech-design-review.md），
 // 不 mock 会导致「期望空列表/精确列表」用例被环境污染（2026-08 实测 4 个失败）。
+// 用真实 tmpdir 下的子目录作 mock homedir（macOS SIP 禁止 mkdir /nonexistent-*）。
+const mockHomeDir = vi.hoisted(() => {
+  const fs = require("node:fs");
+  const os = require("node:os");
+  const path = require("node:path");
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "res-disc-home-"));
+  return dir;
+});
+
 vi.mock("node:os", async (importOriginal) => {
   const actual = await importOriginal<typeof import("node:os")>();
-  return { ...actual, homedir: () => "/nonexistent-home-for-tests" };
+  return { ...actual, homedir: () => mockHomeDir };
 });
 
 import {
@@ -23,6 +32,9 @@ import {
   processPackageSync,
   getCachedFile,
   getCachedFileContent,
+  __testResetShadowDedup,
+  __testInjectShadowDedupKey,
+  isMachineSource,
   getCachedParsed,
   clearFileCache,
 } from "../resource-discovery.ts";
@@ -218,6 +230,7 @@ describe("discoverResources (async)", () => {
   });
   afterEach(() => {
     fs.rmSync(ws, { recursive: true, force: true });
+    __testResetShadowDedup();
   });
 
   it("discovers agents from project .pi/agents/ (async)", async () => {
@@ -262,6 +275,7 @@ describe("user-extension-paths (XYZ_EXTENSION_PATHS)", () => {
     if (savedEnv === undefined) delete process.env.XYZ_EXTENSION_PATHS;
     else process.env.XYZ_EXTENSION_PATHS = savedEnv;
     fs.rmSync(ws, { recursive: true, force: true });
+    __testResetShadowDedup();
   });
 
   it("discovers agents from XYZ_EXTENSION_PATHS via pi.agents manifest", () => {
@@ -392,26 +406,204 @@ describe("user-extension-paths (XYZ_EXTENSION_PATHS)", () => {
     expect(asyncResult).toEqual(discoverResourcesSync(config));
   });
 
-  it("async: 同名遮蔽时输出 warn（D8d 有检测必有报告）", async () => {
+  it("async: 同名遮蔽时机器源×机器源降 debug 不产生 warn（D8d 分级）", async () => {
     const npmPkg = path.join(agentDir, "npm", "node_modules", "test-pkg");
     writePackageJson(npmPkg, { agents: ["./agents"] });
     const npmFile = writeFile(path.join(npmPkg, "agents"), "dup.md", "npm-body");
     const projFile = writeFile(path.join(ws, ".agents", "agents"), "dup.md", "project-body");
     const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+    const debugSpy = vi.spyOn(getLogger("subagents"), "debug");
 
     try {
       const result = await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
 
       // 遮蔽仍生效（last-writer-wins 语义不变）
       expect(result.find((r) => path.basename(r.path) === "dup.md")?.source).toBe("project-agents");
-      // 但不再静默：warn 报告被遮蔽方与保留方路径（D8d「有检测无报告」修复）
-      expect(warnSpy).toHaveBeenCalledTimes(1);
-      const [msg, data] = warnSpy.mock.calls[0];
+      // npm 与 project-agents 均为机器源 → 降级 debug，不产生 warn
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(debugSpy).toHaveBeenCalledTimes(1);
+      const [msg, data] = debugSpy.mock.calls[0];
       expect(String(msg)).toContain('duplicate agents "dup"');
       expect(String(msg)).toContain("project-agents shadows npm");
       expect(data).toMatchObject({ shadowed: npmFile, kept: projFile });
     } finally {
       warnSpy.mockRestore();
+      debugSpy.mockRestore();
+    }
+  });
+
+  it("(a) 机器源×用户源降 debug：npm vs user-pi 不产生 warn", async () => {
+    // npm 源（机器源）与 user-pi 源（用户源）——任一侧为机器源即降 debug
+    const npmPkg = path.join(agentDir, "npm", "node_modules", "test-pkg");
+    writePackageJson(npmPkg, { agents: ["./agents"] });
+    writeFile(path.join(npmPkg, "agents"), "dup.md", "npm-body");
+    // user-pi 源 = agentDir/<kind>/（agentDir 是独立于 homedir mock 的入参，
+    // mockHomeDir 由 vi.hoisted mkdtempSync 创建真实 tmpdir）
+    writeFile(path.join(agentDir, "agents"), "dup.md", "user-pi-body");
+    const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+    const debugSpy = vi.spyOn(getLogger("subagents"), "debug");
+
+    try {
+      await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(debugSpy).toHaveBeenCalled();
+      const [msg] = debugSpy.mock.calls[0];
+      expect(String(msg)).toContain('duplicate agents "dup"');
+    } finally {
+      warnSpy.mockRestore();
+      debugSpy.mockRestore();
+    }
+  });
+
+  it("(a) npm vs user-extension-paths 机器源×机器源降 debug", async () => {
+    // 两个机器源同名（npm 包 vs XYZ_EXTENSION_PATHS 注入的 dev 包，后者 source 标签为 user-extension-paths）
+    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 warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+    const debugSpy = vi.spyOn(getLogger("subagents"), "debug");
+
+    try {
+      await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(debugSpy).toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+      debugSpy.mockRestore();
+    }
+  });
+
+  it("(b) 双用户源重复产生 warn 且同进程第二次 discoverResources 不重复（去重生效）", async () => {
+    // user-pi 与 user-agents 都是用户源——需要构造两个源都有同名文件
+    // user-pi = agentDir/agents/（buildScanTargets 第一个 target）
+    // user-agents = mockHomeDir/.agents/agents/（vi.hoisted 创建的真实 tmpdir）
+    const userAgentsDir = path.join(mockHomeDir, ".agents", "agents");
+    fs.mkdirSync(userAgentsDir, { recursive: true });
+    try {
+      // user-pi: agentDir/agents/dup.md
+      writeFile(path.join(agentDir, "agents"), "dup.md", "user-pi-body");
+      // user-agents: mockHomeDir/.agents/agents/dup.md
+      fs.writeFileSync(path.join(userAgentsDir, "dup.md"), "user-agents-body", "utf-8");
+
+      const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+
+      try {
+        // 第一次调用——应产生 warn（双用户源）
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        const [msg] = warnSpy.mock.calls[0];
+        expect(String(msg)).toContain('duplicate agents "dup"');
+
+        // 第二次调用——同进程去重，不再报
+        warnSpy.mockClear();
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).not.toHaveBeenCalled();
+      } finally {
+        warnSpy.mockRestore();
+      }
+    } finally {
+      fs.rmSync(userAgentsDir, { recursive: true, force: true });
+    }
+  });
+
+  it("(c) path 变化（新 key）重新报 warn", async () => {
+    const userAgentsDir = path.join(mockHomeDir, ".agents", "agents");
+    fs.mkdirSync(userAgentsDir, { recursive: true });
+    try {
+      writeFile(path.join(agentDir, "agents"), "dup.md", "user-pi-body");
+      fs.writeFileSync(path.join(userAgentsDir, "dup.md"), "user-agents-body", "utf-8");
+
+      const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+
+      try {
+        // 第一次调用——报 warn
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+
+        // 第二次调用——同 key 去重，不报
+        warnSpy.mockClear();
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).not.toHaveBeenCalled();
+
+        // 真实 path 变化产生新 key：双用户目录各加一个不同 stem（dup2.md）
+        // → 新遮蔽对（新 stem 新 path）→ 新 key → 重新报
+        writeFile(path.join(agentDir, "agents"), "dup2.md", "user-pi-body-2");
+        fs.writeFileSync(path.join(userAgentsDir, "dup2.md"), "user-agents-body-2", "utf-8");
+        warnSpy.mockClear();
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        const [newMsg] = warnSpy.mock.calls[0];
+        expect(String(newMsg)).toContain('duplicate agents "dup2"');
+      } finally {
+        warnSpy.mockRestore();
+      }
+    } finally {
+      fs.rmSync(userAgentsDir, { recursive: true, force: true });
+    }
+  });
+
+  it("分级穷举：全部 8 个 ResourceSource 的机器/用户归属与 D3 一致", () => {
+    // 封闭枚举逐值断言，防止未来新增/修改枚举值时分级边界漂移
+    const machine: ResourceSource[] = ["npm", "npm-dev", "user-extension-paths", "project-pi", "project-pi-tmp", "project-agents"];
+    const user: ResourceSource[] = ["user-pi", "user-agents"];
+    for (const s of machine) expect(isMachineSource(s), `${s} 应为机器源`).toBe(true);
+    for (const s of user) expect(isMachineSource(s), `${s} 应为用户源`).toBe(false);
+  });
+
+  it("(d) cap 清空行为：超限后 clear 再 add，之前报过的 key 可重新报", async () => {
+    const userAgentsDir = path.join(mockHomeDir, ".agents", "agents");
+    fs.mkdirSync(userAgentsDir, { recursive: true });
+    try {
+      writeFile(path.join(agentDir, "agents"), "dup.md", "user-pi-body");
+      fs.writeFileSync(path.join(userAgentsDir, "dup.md"), "user-agents-body", "utf-8");
+
+      const warnSpy = vi.spyOn(getLogger("subagents"), "warn");
+
+      try {
+        // 步骤 1：首次调用——报 warn，dedup key 加入 set
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        warnSpy.mockClear();
+
+        // 步骤 2：重置 set，注入 1024 个虚拟 key（不含 dedup key）
+        // 使 set.size = MAX，dedup key 不在 set 中
+        __testResetShadowDedup();
+        for (let i = 0; i < 1024; i++) {
+          __testInjectShadowDedupKey(`fake|key${i}|/a|/b`);
+        }
+
+        // 步骤 3：第二次调用——dedup key 不在 set → 进 else 分支 →
+        // size(1024) >= MAX(1024) → clear() → set 空 → add dedup key → warn
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        warnSpy.mockClear();
+
+        // 步骤 4：第三次调用——dedup key 在 set 中 → 去重跳过 warn
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).not.toHaveBeenCalled();
+
+        // 步骤 5：再次填充到 cap——重置 + 注入 1024 个虚拟 key
+        // dedup key（步骤 3 add 的）已被 reset 清除
+        __testResetShadowDedup();
+        for (let i = 0; i < 1024; i++) {
+          __testInjectShadowDedupKey(`fake2|key${i}|/a|/b`);
+        }
+
+        // 步骤 6：第四次调用——cap 再次触发 clear → dedup key 重新报
+        await discoverResources({ kind: "agents", workspaceRoot: ws, agentDir });
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+      } finally {
+        warnSpy.mockRestore();
+        __testResetShadowDedup();
+      }
+    } finally {
+      fs.rmSync(userAgentsDir, { recursive: true, force: true });
     }
   });
 });

package/src/shared/resource-discovery.ts

@@ -21,6 +21,22 @@ import { getLogger } from "@zhushanwen/pi-extension-logger";
 // 模块级 logger（setPiHandle 注入后自动走 appendEntry，未注入时 console 兜底）
 const logger = getLogger("subagents");
 
+// [D8d] warn 路径进程内去重集合：key=(kind, stem, shadowedPath, keptPath)，
+// cap 1024 超限先清空再 add（对齐 ui-request-observability 的 MAX_WARNED_SESSIONS 范式）。
+// debug 路径不去重（默认 no-op，无成本）。
+const shadowWarnDedup = new Set<string>();
+const MAX_SHADOW_WARN_DEDUP = 1024;
+
+/** @internal 测试辅助：重置 warn 去重集合（cap 测试用，生产代码不调用）。 */
+export function __testResetShadowDedup(): void {
+  shadowWarnDedup.clear();
+}
+
+/** @internal 测试辅助：向 warn 去重集合注入 key（cap 测试用）。 */
+export function __testInjectShadowDedupKey(key: string): void {
+  shadowWarnDedup.add(key);
+}
+
 // ── 类型 ─────────────────────────────────────────────────────
 
 /** 资源种类：agent 或 workflow */
@@ -53,6 +69,23 @@ export interface ScanConfig {
 
 // ── 常量 ─────────────────────────────────────────────────────
 
+/** 机器源集合：包管理/工程配置产物，其同名重复是安装拓扑常态（非用户配置错误）。
+ *  用户个人源（user-pi / user-agents）不在此列——双个人源同名重复保留 warn。 */
+const MACHINE_SOURCES: ReadonlySet<ResourceSource> = new Set<ResourceSource>([
+  "npm",
+  "npm-dev",
+  "user-extension-paths",
+  "project-pi",
+  "project-pi-tmp",
+  "project-agents",
+]);
+
+/** 判断 source 是否属于机器源（安装拓扑常态，同名重复降 debug）。
+ *  导出仅为测试穷举断言用（封闭 8 值枚举 × 分级边界）。 */
+export function isMachineSource(source: ResourceSource): boolean {
+  return MACHINE_SOURCES.has(source);
+}
+
 /** workspace root 向上查找的最大深度 */
 const WORKSPACE_ROOT_MAX_DEPTH = 20;
 
@@ -579,13 +612,29 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
       if (!r.available && existing) {
         continue;
       }
-      // [D8d] 同名遮蔽可观测：高优先级源覆盖低优先级同名资源时 warn——此前
-      // 「有检测无报告」，用户自定义 agent/workflow 被静默遮蔽后排查无从下手。
+      // [D8d] 同名遮蔽可观测：高优先级源覆盖低优先级同名资源时分级报告——
+      // 机器源重复是安装拓扑常态（npm 包与用户目录结构性同名），降 debug 默认静默
+      // （XYZ_AGENT_DEBUG=1 文件日志可查）；双用户源重复是配置错误，保留 warn 首报。
+      // warn 路径进程内去重（Set cap 1024，对齐 ui-request-observability 范式）：
+      // 每 session 独立进程（process-manager.ts L142-143），进程级去重 ≈ session 级首报。
       if (existing && existing.path !== r.path) {
-        logger.warn(
-          `[resource-discovery] duplicate ${config.kind} "${key}" from ${r.source} shadows ${existing.source}`,
-          { shadowed: existing.path, kept: r.path },
-        );
+        const msg =
+          `[resource-discovery] duplicate ${config.kind} "${key}" from ${r.source} shadows ${existing.source}`;
+        const data = { shadowed: existing.path, kept: r.path };
+        if (isMachineSource(existing.source) || isMachineSource(r.source)) {
+          // 任一侧为机器源 → 降级 debug（安装拓扑常态，排查走 XYZ_AGENT_DEBUG=1）
+          logger.debug(msg, data);
+        } else {
+          // 双侧均为用户源 → 保持 warn，进程内去重（同 key 只报首次）
+          const dedupKey = `${config.kind}|${key}|${existing.path}|${r.path}`;
+          if (!shadowWarnDedup.has(dedupKey)) {
+            if (shadowWarnDedup.size >= MAX_SHADOW_WARN_DEDUP) {
+              shadowWarnDedup.clear();
+            }
+            shadowWarnDedup.add(dedupKey);
+            logger.warn(msg, data);
+          }
+        }
       }
       merged.set(key, r);
     }