@zhushanwen/pi-subagent-workflow 8.2.0 → 8.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.2.0",
+  "version": "8.4.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.",
@@ -47,17 +47,17 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "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",
+    "@xyz-agent/extension-protocol": "0.6.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/interface/command-actions.ts

@@ -8,10 +8,15 @@
  * 设计为纯函数（无 ctx / service 依赖），便于独立单测，handler 只做薄分发。
  */
 
-/** /subagents RPC action 判别联合。 */
+/** /subagents RPC action 判别联合。message/start 为 GUI 定向消息通道（设计 §3.3.3，
+ *  仅 RPC 分支消费；missing-args 携带 missing 字段供 handler 输出指明缺什么的 usage）。 */
 export type SubagentRpcAction =
   | { action: "cancel"; recordId: string }
   | { action: "cancel-missing-id" }
+  | { action: "message"; recordId: string; text: string }
+  | { action: "message-missing-args"; missing: "recordId" | "text" }
+  | { action: "start"; slug: string; task: string }
+  | { action: "start-missing-args"; missing: "slug" | "task" }
   | { action: "noop" };
 
 /** /workflows RPC action 判别联合。 */
@@ -46,25 +51,84 @@ function isRemovedLifecycleVerb(verb: string): verb is "pause" | "resume" {
   return REMOVED_LIFECYCLE_VERBS.has(verb as "pause" | "resume");
 }
 
+/**
+ * 还原转义协议（设计 §3.3.3 / 探针 P3）：字面 `\n`（反斜杠 + n 两字符）→ 真实换行、
+ * 字面 `\\`（两反斜杠）→ 单反斜杠。
+ *
+ * 与 runtime encodeDirectiveText（session-service.ts）互逆：composer 多行输入在
+ * client.prompt 传输前把真实换行编码为字面 \n、原生反斜杠编码为 \\（命令保持单行），
+ * extension 解析侧在此还原。反斜杠转义必须与换行转义在**单次遍历**里成对处理
+ * （交替分支 `\\\\|\\n`，两反斜杠优先匹配）——若只处理 \n，原文里的字面反斜杠+n
+ * （如路径 `C:\new`）会被误解码为换行，往返歧义。
+ */
+function decodeNewlineEscapes(s: string): string {
+  return s.replace(/\\\\|\\n/g, (m) => (m === "\\\\" ? "\\" : "\n"));
+}
+
+/**
+ * 提取首个非空白 token 与其后剩余原文。
+ *
+ * 与 split(/\s+/) 不同：rest 保留 token 之后的全部原文（含空格/引号/换行转义），
+ * 供 message text / start task 的「剩余全量到字符串末尾」语义使用（设计 §3.3.3——
+ * pi 以首个空格拆命令名后 args 为其后全文，文本内的空格/引号必须原样保留）。
+ * rest 跳过 token 后的分隔空白（分隔符不属文本），但保留其后全部内容原样。
+ */
+function splitFirstToken(s: string): { token: string; rest: string } | null {
+  const head = s.trimStart();
+  if (!head) return null;
+  const idx = head.search(/\s/);
+  if (idx === -1) return { token: head, rest: "" };
+  return { token: head.slice(0, idx), rest: head.slice(idx + 1).trimStart() };
+}
+
 /**
  * 解析 /subagents RPC 命令字符串。
  *
  * 支持格式：
  * - `cancel <id>` → { action: "cancel", recordId }
  * - `cancel`（无 id）→ { action: "cancel-missing-id" }
+ * - `message <recordId> <text...>` → { action: "message", recordId, text }
+ *   text 为第二 token 后的剩余全量（含空格/引号原样；字面 \n 还原为换行、字面 \\ 还原为
+ *   反斜杠——composer 定向消息经此协议编码，与 runtime encodeDirectiveText 互逆，设计 §3.3.3）
+ * - `message`（缺 recordId 或 text 为空白）→ { action: "message-missing-args", missing }
+ * - `start <slug> <task...>` → { action: "start", slug, task }（task 同 text 转义协议）
+ * - `start`（缺 slug 或 task 为空白）→ { action: "start-missing-args", missing }
  * - 其他（空 / 未知 action / 无参）→ { action: "noop" }
  *
- * noop 表示 GUI 端无对应程序化操作（GUI 已在 CommandPopover 屏蔽 /subagents 入口，
- * 此分支仅兜底手动 prompt）。
+ * missing-args 携带 missing 字段（缺哪个参数），handler 据此输出可操作的 usage
+ * 错误（全局规则：错误信息指向恢复动作）。noop 表示 GUI 端无对应程序化操作（GUI
+ * 已在 CommandPopover 屏蔽 /subagents 入口，此分支仅兜底手动 prompt）。
  */
 export function parseSubagentRpcCommand(argsStr: string): SubagentRpcAction {
-  const args = argsStr.trim().split(/\s+/).filter(Boolean);
-  if (args.length === 0) return { action: "noop" };
+  const first = splitFirstToken(argsStr);
+  if (!first) return { action: "noop" };
 
-  const [verb, recordId] = args;
+  const { token: verb, rest } = first;
   if (verb === "cancel") {
-    if (!recordId) return { action: "cancel-missing-id" };
-    return { action: "cancel", recordId };
+    const idToken = splitFirstToken(rest);
+    if (!idToken) return { action: "cancel-missing-id" };
+    return { action: "cancel", recordId: idToken.token };
+  }
+  if (verb === "message" || verb === "start") {
+    // message 与 start 共用解析骨架，仅结果字段名不同（recordId/text vs slug/task）
+    const isMessage = verb === "message";
+    // 第二 token：message→recordId / start→slug；其后剩余全量（还原换行转义）为 text/task
+    const second = splitFirstToken(rest);
+    if (!second) {
+      return isMessage
+        ? { action: "message-missing-args", missing: "recordId" }
+        : { action: "start-missing-args", missing: "slug" };
+    }
+    // 先还原再判空：纯字面 \n 还原后是真实换行（whitespace），应在解析层拦截为缺参
+    const payload = decodeNewlineEscapes(second.rest);
+    if (!payload.trim()) {
+      return isMessage
+        ? { action: "message-missing-args", missing: "text" }
+        : { action: "start-missing-args", missing: "task" };
+    }
+    return isMessage
+      ? { action: "message", recordId: second.token, text: payload }
+      : { action: "start", slug: second.token, task: payload };
   }
   return { action: "noop" };
 }

package/src/interface/subagent-actions.ts

@@ -329,10 +329,13 @@ export interface MessageHandlerInput {
   interrupt?: boolean;
 }
 
-/** message 领域对象（adapter 包成 messageResponse）。 */
+/** message 领域对象（adapter 包成 messageResponse）。
+ *  slug 来自 record（GUI /subagents message 通道的留痕 details 需要，设计 §3.3.3），
+ *  避免调用方二次 getRecordForAction 查询。 */
 export type MessageHandlerResult = {
   kind: "message";
   subagentId: string;
+  slug: string;
   response: MessageResponse;
 };
 
@@ -393,7 +396,7 @@ export async function messageHandler(
       `Recovery: use action:'close' to clean up, then action:'start' a new subagent.`,
     );
   }
-  return { kind: "message", subagentId: id, response: { delivered: true } };
+  return { kind: "message", subagentId: id, slug: record.slug, response: { delivered: true } };
 }
 
 // ============================================================

package/src/interface/subagents.ts

@@ -3,16 +3,211 @@
 // /subagents 命令。薄壳——打开 list overlay（等同原 /subagents list [<id>]）。
 //
 // 解析：args[0] 直接作可选 <id>（聚焦该 record）。
-// RPC 模式（xyz-agent GUI）：解析 cancel action 直接执行，不打开 TUI。
+// RPC 模式（xyz-agent GUI）：解析 cancel/message/start action 直接执行，不打开 TUI。
+// message/start 为 GUI 定向消息通道（设计 §3.3.3）：GUI 经 client.prompt 短路
+// extension 命令（不经主 agent LLM），TUI 分支不消费这两个 verb（行为零变化）。
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 import { getSubagentService } from "../execution/subagent-service.ts";
+import type { SubagentService } from "../execution/subagent-service.ts";
 import { displayAgentName } from "../shared/agent-ref.ts";
+import { messageHandler, startHandler } from "./subagent-actions.ts";
 import { parseSubagentRpcCommand } from "./command-actions.ts";
+import type { SubagentRpcAction } from "./command-actions.ts";
 import { LIST_LIMIT } from "./list-shared.ts";
 import { createSubagentsView } from "./list-view.ts";
 
+/**
+ * subagent-directive custom_message 的 customType。
+ *
+ * 定向消息留痕载体（设计 §3.3.3）：message/start 成功派发后落主 session 的
+ * custom_message entry，一 entry 双消费——
+ * 1. 主 agent 上下文（custom_message 进 context，主 agent 下次 turn 可见定向对话）
+ * 2. renderer 定向气泡渲染源（§3.3.3a live/reload 双链路，后续 wave 消费）
+ * 字段形状是 GUI 契约，改动需与 renderer 侧同步。
+ */
+export const SUBAGENT_DIRECTIVE_CUSTOM_TYPE = "subagent-directive";
+
+/** subagent-directive entry 的 details 形状（GUI 定向气泡渲染契约）。 */
+export interface SubagentDirectiveDetails {
+  subagentId: string;
+  slug: string;
+  /** 消息方向：'user' = 用户 → subagent 定向（当前唯一方向，命名预留双向扩展）。 */
+  direction: "user";
+}
+
+/**
+ * 定向消息留痕：向主 session 落 subagent-directive custom_message entry。
+ *
+ * 按主 agent streaming 状态分流 sendMessage options。pi 0.84.1 sendCustomMessage
+ * 实装（agent-session.js）：isStreaming 且无 deliverAs 时默认 agent.steer()——会把
+ * 定向消息注入正在运行的主 agent LLM turn，违反「不经主 agent LLM 直达 subagent」。
+ * 故按调用时刻的权威 streaming 状态（ctx.isIdle()，与 sendCustomMessage 内部
+ * isStreaming 判据精确互补，含 agent_end 后 retry/continuation 窗口）分流：
+ * - streaming（isMainAgentIdle=false）：传 { deliverAs: "nextTurn" }——消息入
+ *   pi 内存 _pendingNextTurnMessages 队列，下个 turn 注入主 agent 上下文；不打断、
+ *   不 steer 当前 turn。注意：该队列不落 entry，留痕延迟到下个 turn
+ * - 非 streaming（isMainAgentIdle=true）：不传 options——立即 append entry 留痕
+ *   + message_start/end 双发（renderer live 链路即时可见，现状行为）
+ * 两者都不传 triggerTurn——不产生新 turn（§3.3.8「留痕 ≠ 处理」的结构性保证）；
+ * display:false 使 pi TUI 不渲染该 entry（GUI 侧由 §3.3.3a 定向气泡通路渲染）。
+ */
+function emitSubagentDirective(
+  pi: Pick<ExtensionAPI, "sendMessage">,
+  details: SubagentDirectiveDetails,
+  text: string,
+  isMainAgentIdle: boolean,
+): void {
+  pi.sendMessage(
+    {
+      customType: SUBAGENT_DIRECTIVE_CUSTOM_TYPE,
+      content: text,
+      display: false,
+      details,
+    },
+    isMainAgentIdle ? undefined : { deliverAs: "nextTurn" },
+  );
+}
+
+/** RPC cancel 执行体（行为等价拆分自 handler，复杂度治理）。 */
+async function rpcCancel(
+  service: SubagentService,
+  recordId: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  try {
+    const ok = service.cancel(recordId);
+    ctx.ui.notify(
+      ok ? `Cancelled subagent ${recordId}` : `Subagent ${recordId} not found or already finished`,
+      ok ? "info" : "warning",
+    );
+  } catch (err) {
+    // service.cancel 内部 assertReady 在 session_shutdown 并发 dispose 时会抛
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to cancel subagent ${recordId}: ${msg}`, "warning");
+  }
+}
+
+/** RPC message 执行体（行为等价拆分自 handler，复杂度治理）。 */
+async function rpcMessage(
+  pi: ExtensionAPI,
+  service: SubagentService,
+  recordId: string,
+  text: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  // GUI 定向消息（设计 §3.3.3）：不经主 agent LLM 直达 subagent。
+  // one-shot 首条 message 自动升级 chatMode 的机制在 messageHandler 内（勿在此重复）。
+  try {
+    const result = await messageHandler(service, {
+      subagentId: recordId,
+      text,
+    });
+    // 留痕（§3.3.3）：成功派发后才留痕——失败时不留痕，GUI 按 toast 错误重发。
+    // ctx.isIdle() 按调用时刻分流（streaming → nextTurn 队列延迟留痕，见
+    // emitSubagentDirective JSDoc），保证任何时刻都不 steer 主 agent 当前 turn
+    emitSubagentDirective(
+      pi,
+      { subagentId: result.subagentId, slug: result.slug, direction: "user" },
+      text,
+      ctx.isIdle(),
+    );
+    ctx.ui.notify(`Message delivered to subagent ${result.slug} (${result.subagentId})`, "info");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to message subagent ${recordId}: ${msg}`, "warning");
+  }
+}
+
+/** RPC start 执行体（行为等价拆分自 handler，复杂度治理）。 */
+async function rpcStart(
+  pi: ExtensionAPI,
+  service: SubagentService,
+  slug: string,
+  task: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  // GUI 定向新建（设计 §3.3.3）：conversation 固定 true（GUI 定向对话场景需要可续聊）
+  try {
+    const result = await startHandler(
+      service,
+      {
+        slug,
+        task,
+        conversation: true,
+      },
+      // RPC 命令无外层 AbortSignal（GUI 请求生命周期不映射到 subagent 取消——
+      // start 是 detached 后台语义，取消走 /subagents cancel）
+      undefined,
+    );
+    emitSubagentDirective(
+      pi,
+      { subagentId: result.subagentId, slug: result.slug, direction: "user" },
+      task,
+      ctx.isIdle(),
+    );
+    ctx.ui.notify(`Started subagent ${result.slug} (${result.subagentId})`, "info");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to start subagent ${slug}: ${msg}`, "warning");
+  }
+}
+
+/**
+ * RPC 模式（xyz-agent GUI）：解析后的 action 分发执行，不打开 TUI。
+ * 行为等价拆分自 handler（fallow 圈复杂度 21 > 15）：三个执行体
+ * （cancel/message/start）各自成函数，本函数只做 switch 分发 +
+ * usage notify + exhaustiveness 断言。
+ */
+async function executeRpcAction(
+  pi: ExtensionAPI,
+  service: SubagentService,
+  parsed: SubagentRpcAction,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  switch (parsed.action) {
+    case "cancel":
+      await rpcCancel(service, parsed.recordId, ctx);
+      return;
+    case "cancel-missing-id":
+      ctx.ui.notify("Usage: /subagents cancel <id>", "warning");
+      return;
+    case "message":
+      await rpcMessage(pi, service, parsed.recordId, parsed.text, ctx);
+      return;
+    case "message-missing-args":
+      // 错误可操作：指明缺什么 + 完整 usage（全局规则 16）
+      ctx.ui.notify(
+        parsed.missing === "recordId"
+          ? "Usage: /subagents message <recordId> <text> — recordId is missing"
+          : "Usage: /subagents message <recordId> <text> — text is missing",
+        "warning",
+      );
+      return;
+    case "start":
+      await rpcStart(pi, service, parsed.slug, parsed.task, ctx);
+      return;
+    case "start-missing-args":
+      ctx.ui.notify(
+        parsed.missing === "slug"
+          ? "Usage: /subagents start <slug> <task> — slug is missing"
+          : "Usage: /subagents start <slug> <task> — task is missing",
+        "warning",
+      );
+      return;
+    case "noop":
+      // 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
+      ctx.ui.notify("View subagents in the sidebar Agents tab", "info");
+      return;
+    default: {
+      // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错
+      const _exhaustive: never = parsed;
+      throw new Error(`Unhandled subagent RPC action: ${String(_exhaustive)}`);
+    }
+  }
+}
+
 /** 注册 /subagents 命令（= list overlay）。 */
 export function registerSubagentsCommand(pi: ExtensionAPI): void {
   pi.registerCommand("subagents", {
@@ -59,35 +254,8 @@ export function registerSubagentsCommand(pi: ExtensionAPI): void {
       // ── RPC 模式（xyz-agent GUI）：解析 action 直接执行，不打开 TUI ──
       // hasUI 在 TUI 和 RPC 都为 true，不能用于区分；用 ctx.mode === "rpc" 判定 GUI 通道。
       if (ctx.mode === "rpc") {
-        const parsed = parseSubagentRpcCommand(argsStr);
-        switch (parsed.action) {
-          case "cancel": {
-            try {
-              const ok = service.cancel(parsed.recordId);
-              ctx.ui.notify(
-                ok ? `Cancelled subagent ${parsed.recordId}` : `Subagent ${parsed.recordId} not found or already finished`,
-                ok ? "info" : "warning",
-              );
-            } catch (err) {
-              // service.cancel 内部 assertReady 在 session_shutdown 并发 dispose 时会抛
-              const msg = err instanceof Error ? err.message : String(err);
-              ctx.ui.notify(`Failed to cancel subagent ${parsed.recordId}: ${msg}`, "warning");
-            }
-            return;
-          }
-          case "cancel-missing-id":
-            ctx.ui.notify("Usage: /subagents cancel <id>", "warning");
-            return;
-          case "noop":
-            // 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
-            ctx.ui.notify("View subagents in the sidebar Agents tab", "info");
-            return;
-          default: {
-            // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错
-            const _exhaustive: never = parsed;
-            throw new Error(`Unhandled subagent RPC action: ${String(_exhaustive)}`);
-          }
-        }
+        await executeRpcAction(pi, service, parseSubagentRpcCommand(argsStr), ctx);
+        return;
       }
 
       // ── print/json 模式（headless）：不可交互 ──

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);
     }