@zhushanwen/pi-subagent-workflow 9.2.0 → 9.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "9.2.0",
+  "version": "9.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.",
@@ -58,22 +58,22 @@
     ]
   },
   "dependencies": {
-    "@zhushanwen/session-delivery": "1.0.0",
-    "@zhushanwen/extension-protocol": "0.17.0",
-    "@zhushanwen/pi-ext-guards": "0.4.2",
-    "@zhushanwen/pi-notify-ledger-host": "0.2.3",
-    "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/subagent-core": "1.2.0",
-    "@zhushanwen/pi-subagent-cli": "0.5.0",
-    "@zhushanwen/zcode-subagent-cli": "0.4.4"
+    "@zhushanwen/extension-protocol": "0.18.0",
+    "@zhushanwen/session-delivery": "1.1.0",
+    "@zhushanwen/pi-ext-guards": "0.4.3",
+    "@zhushanwen/pi-extension-logger": "0.6.2",
+    "@zhushanwen/pi-notify-ledger-host": "0.3.0",
+    "@zhushanwen/subagent-core": "1.3.0",
+    "@zhushanwen/pi-subagent-cli": "0.6.0",
+    "@zhushanwen/zcode-subagent-cli": "0.5.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.4",
-    "@earendil-works/pi-coding-agent": "^0.84.4",
-    "@earendil-works/pi-tui": "^0.84.4",
-    "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.8.1",
-    "@zhushanwen/pi-structured-output": "6.0.0"
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
+    "typebox": "1.3.27",
+    "@zhushanwen/pi-pending-notifications": "0.8.2",
+    "@zhushanwen/pi-structured-output": "6.1.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -87,7 +87,7 @@
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-engine-sdk": "0.8.0"
+    "@zhushanwen/subagent-engine-sdk": "0.9.0"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/src/host/__tests__/inflight-reporter.test.ts

@@ -3,10 +3,11 @@
 // 三视角：
 //   ①使用者（runtime event-adapter 视角）——帧形状：title=SUBAGENT_INFLIGHT_MARKER、
 //     options=[JSON 帧]（inFlight/sessionId/emittedAt）、控制面级 timeout 在场；
-//   ②构建者——初始上报（attachSession 触发，无需任何 subagent 调用）→ ack 清失败
-//     计数；失败折叠 + 延迟重试；推送在途期间多次迁移合并为单帧且携带最新绝对计数；
+//   ②构建者——初始上报（attachSession 触发，无需任何 subagent 调用）；失败折叠 +
+//     置脏（无 timer 自动重试，ADR-0122）；推送在途期间多次迁移合并为单帧且携带
+//     最新绝对计数；
 //   ③观察者——onInFlightChanged 同步返回（不 await select，不进生命周期链）；
-//     detachSession 停重试，session 死后通道静默。
+//     detachSession 后通道静默，session 死后不推帧。
 //
 // [HISTORICAL] 行为于 9f914b749 变更：kind='initial'|'delta' 帧字段与 initialAcked
 // 状态机作为死面删除（消费方 event-adapter 从不读 kind，绝对计数语义下帧间等价；
@@ -35,7 +36,6 @@ import { INFLIGHT_REPORT_ACK, SUBAGENT_INFLIGHT_MARKER } from "@zhushanwen/exten
 
 import { createInFlightReporter } from "../inflight-reporter.ts";
 
-const RETRY_MS = 50;
 const SELECT_TIMEOUT_MS = 1_000;
 
 type SelectCall = { title: string; payload: string; timeout: number | undefined };
@@ -93,7 +93,7 @@ async function advance(ms: number): Promise<void> {
 describe("初始上报（D5：触发时点 = extension 加载完成 / session 就绪）", () => {
   it("attachSession 即发初始帧（count=当下快照，无需任何 subagent 调用）", async () => {
     const channel = makeSelectChannel();
-    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS, selectTimeoutMs: SELECT_TIMEOUT_MS });
+    const reporter = createInFlightReporter({ selectTimeoutMs: SELECT_TIMEOUT_MS });
 
     reporter.attachSession(makeCtx(channel));
     await advance(0);
@@ -113,7 +113,7 @@ describe("初始上报（D5：触发时点 = extension 加载完成 / session
 
   it("初始未送达前发生的迁移不产生第二帧（合并为单帧，ack 后补推最新快照）", async () => {
     const channel = makeSelectChannel();
-    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    const reporter = createInFlightReporter();
     reporter.attachSession(makeCtx(channel));
     await advance(0);
 
@@ -135,7 +135,7 @@ describe("初始上报（D5：触发时点 = extension 加载完成 / session
 describe("绝对计数语义（每帧携带当下值，非增量）", () => {
   it("连续迁移各帧均为整值快照（2 → 0，不做加减）", async () => {
     const channel = makeSelectChannel();
-    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    const reporter = createInFlightReporter();
     reporter.attachSession(makeCtx(channel));
     await advance(0);
     channel.settleAll(INFLIGHT_REPORT_ACK);
@@ -158,27 +158,32 @@ describe("绝对计数语义（每帧携带当下值，非增量）", () => {
   });
 });
 
-describe("失败折叠 + 延迟重试（有界：累计 MAX_REPORT_ATTEMPTS 次放弃，D5 缺席语义②）", () => {
-  it("select resolve undefined（超时/旧版 runtime）→ 折叠重试；重试帧携带完整快照；ack 后停", async () => {
+describe("失败折叠（ADR-0122：无 timer 自动重试，事件驱动重推）", () => {
+  it("select resolve undefined（超时/旧版 runtime）→ 置脏不重试；下次迁移事件重推最新快照", async () => {
     const channel = makeSelectChannel();
-    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS, selectTimeoutMs: SELECT_TIMEOUT_MS });
+    const reporter = createInFlightReporter({ selectTimeoutMs: SELECT_TIMEOUT_MS });
     reporter.attachSession(makeCtx(channel));
     await advance(0);
     expect(channel.calls).toHaveLength(1);
 
-    // 首帧无人 ack，select 以 undefined 落定（超时形态）→ 折叠
+    // 首帧无人 ack，select 以 undefined 落定（超时形态）→ 折叠置脏
     channel.settle(0, undefined);
-    await advance(RETRY_MS - 1);
-    expect(channel.calls).toHaveLength(1); // 未到退避点不重试
-    await advance(1);
+    await advance(0);
+    // 推进远超原重试周期的时间：无 timer 自动重试（ADR-0122），零新帧
+    await advance(60_000);
+    expect(channel.calls).toHaveLength(1);
+
+    // 下一次 in-flight 变化事件驱动重推（携带最新绝对计数快照）
+    reporter.onInFlightChanged();
+    await advance(0);
     expect(channel.calls).toHaveLength(2);
     const retryFrame = parseFrame(channel.calls[1]);
-    expect(retryFrame.kind).toBeUndefined(); // kind 已删（9f914b749）：重试帧与普通帧等价
-    expect(retryFrame.inFlight).toBe(0); // 重试帧携带完整绝对计数快照
+    expect(retryFrame.kind).toBeUndefined(); // kind 已删（9f914b749）：重推帧与普通帧等价
+    expect(retryFrame.inFlight).toBe(0); // 重推帧携带完整绝对计数快照
 
-    // 重试帧得到 ack → 重试停止；随后迁移照常送达
+    // 重推帧得到 ack → 通道恢复；随后迁移照常送达
     channel.settle(1, INFLIGHT_REPORT_ACK);
-    await advance(RETRY_MS * 10);
+    await advance(60_000);
     expect(channel.calls).toHaveLength(2);
 
     reporter.onInFlightChanged();
@@ -188,81 +193,64 @@ describe("失败折叠 + 延迟重试（有界：累计 MAX_REPORT_ATTEMPTS 次
     channel.settleAll(INFLIGHT_REPORT_ACK);
   });
 
-  it("select 通道抛错同样折叠进重试路径", async () => {
+  it("select 通道抛错同样折叠置脏，由迁移事件重推", async () => {
     const channel = makeSelectChannel();
-    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    const reporter = createInFlightReporter();
     reporter.attachSession(makeCtx(channel));
     await advance(0);
     channel.settle(0, new Error("channel blew up"));
-    await advance(RETRY_MS);
-    expect(channel.calls.length).toBeGreaterThanOrEqual(2);
-    channel.settleAll(INFLIGHT_REPORT_ACK);
     await advance(0);
-  });
-
-  it("非确认回包（旧版 runtime 的任意字符串）不算送达，继续重试", async () => {
-    const channel = makeSelectChannel();
-    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
-    reporter.attachSession(makeCtx(channel));
+    await advance(60_000); // 无 timer 重试
+    expect(channel.calls).toHaveLength(1);
+    reporter.onInFlightChanged();
     await advance(0);
-    channel.settle(0, '{"ok":1}');
-    await advance(RETRY_MS);
     expect(channel.calls).toHaveLength(2);
     channel.settleAll(INFLIGHT_REPORT_ACK);
     await advance(0);
   });
 
-  it("累计失败达默认上限（3 次）即放弃：不再重试，后续迁移也不再发帧", async () => {
+  it("非确认回包（旧版 runtime 的任意字符串）不算送达，置脏等事件重推", async () => {
     const channel = makeSelectChannel();
-    // 未注入 maxAttempts：锁默认上限 MAX_REPORT_ATTEMPTS = 3（增强面降级语义）。
-    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS, selectTimeoutMs: SELECT_TIMEOUT_MS });
+    const reporter = createInFlightReporter();
     reporter.attachSession(makeCtx(channel));
     await advance(0);
+    channel.settle(0, '{"ok":1}');
+    await advance(0);
+    await advance(60_000); // 无 timer 重试
     expect(channel.calls).toHaveLength(1);
-
-    // 三帧全部失败落定：首帧 + 2 次退避重试；第 3 次失败触顶
-    channel.settle(0, undefined);
-    await advance(RETRY_MS);
-    expect(channel.calls).toHaveLength(2);
-    channel.settle(1, undefined);
-    await advance(RETRY_MS);
-    expect(channel.calls).toHaveLength(3);
-    channel.settle(2, undefined);
-
-    // 达到上限：放弃为 session 内终态——时间推进与后续迁移都不再发帧
-    await advance(RETRY_MS * 10);
-    expect(channel.calls).toHaveLength(3);
     reporter.onInFlightChanged();
-    await advance(RETRY_MS * 10);
-    expect(channel.calls).toHaveLength(3);
+    await advance(0);
+    expect(channel.calls).toHaveLength(2);
+    channel.settleAll(INFLIGHT_REPORT_ACK);
+    await advance(0);
   });
 });
 
 describe("不阻塞生命周期主链（D5 接线约束①）", () => {
   it("onInFlightChanged 同步返回：select 永不落定也不挂调用方（detach 可丢弃在途帧）", async () => {
     const channel = makeSelectChannel();
-    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    const reporter = createInFlightReporter();
     reporter.attachSession(makeCtx(channel));
     await advance(0);
 
     // 第一帧挂起（模拟 runtime 无响应）——迁移调用仍同步返回
     expect(() => reporter.onInFlightChanged()).not.toThrow();
 
-    // session 死后 detach：挂起帧被丢弃，重试链静止（时间推进零新调用）
+    // session 死后 detach：挂起帧被丢弃，通道静止（时间推进零新调用）
     reporter.detachSession();
     channel.settleAll(undefined);
-    await advance(RETRY_MS * 5);
+    await advance(60_000);
     expect(channel.calls).toHaveLength(1);
   });
 
-  it("detachSession 清掉待发重试定时器（session 已死，重试语义随之终结）", async () => {
+  it("detachSession 后失败落定不再发帧（ctx 已空，置脏无效果）", async () => {
     const channel = makeSelectChannel();
-    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS });
+    const reporter = createInFlightReporter();
     reporter.attachSession(makeCtx(channel));
     await advance(0);
     reporter.detachSession();
-    channel.settleAll(undefined); // 在途帧失败落定——ctx 已空，不排新重试
-    await advance(RETRY_MS * 10);
+    channel.settleAll(undefined); // 在途帧失败落定——ctx 已空，不排重推
+    await advance(60_000);
     expect(channel.calls).toHaveLength(1);
   });
 });

package/src/host/__tests__/journal-reporter.test.ts

@@ -0,0 +1,230 @@
+// journal-reporter.test.ts —— 壳层 journal 事件推送出口（event-push-channel W-P1）。
+//
+// 三视角：
+//   ①使用者（runtime event-adapter 视角）——帧形状：title=SUBAGENT_JOURNAL_MARKER、
+//     options=[JSON 报告]（domain/fileKey/events/sessionId/emittedAt）、控制面级
+//     timeout 在场；
+//   ②构建者——单帧单文件（fileKey 单数）；一次推送尝试在途时新事件并入待推缓冲，
+//     成功后逐组继续；失败（无 ack）→ 待推缓冲整体丢弃不重推（设计 D5，与 inflight
+//     的 dirty 重推刻意分叉——消费方有 seq 水位可判缺口）；
+//   ③观察者——onJournalAppended 同步返回（不 await select，不进落盘主链）；
+//     非 rpc 模式 no-op（不设 ctx，全程零帧）；detach 后通道静默。
+//
+// 与 inflight-reporter 的差异锚：无初始帧（报告语义是增量事件，空 session 无事件
+// 可报，缺席语义归消费方冷读——设计 §3.3）。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── hoisted mocks（依赖收窄：logger 防文件落盘） ──
+
+const extensionLoggerMock = vi.hoisted(() => ({
+  getLogger: vi.fn(() => ({
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  })),
+}));
+
+vi.mock("@zhushanwen/pi-extension-logger", () => extensionLoggerMock);
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { JOURNAL_REPORT_ACK, SUBAGENT_JOURNAL_MARKER } from "@zhushanwen/extension-protocol";
+
+import { createJournalReporter } from "../journal-reporter.ts";
+
+const SELECT_TIMEOUT_MS = 1_000;
+
+type SelectCall = { title: string; payload: string; timeout: number | undefined };
+
+/** 可控 select 通道：每次调用的应答由用例逐帧裁决（ack / undefined / 抛错 / 挂起）。 */
+function makeSelectChannel() {
+  const calls: SelectCall[] = [];
+  const pending: Array<(v: unknown) => void> = [];
+  const select = vi.fn(
+    (title: string, options: string[], opts?: { timeout?: number }): Promise<unknown> => {
+      calls.push({ title, payload: options[0] ?? "", timeout: opts?.timeout });
+      return new Promise((resolve) => pending.push(resolve));
+    },
+  );
+  return {
+    select,
+    calls,
+    /** resolve 第 N 帧（0 起）。 */
+    settle(index: number, value: unknown): void {
+      pending[index]?.(value);
+    },
+    settleAll(value: unknown): void {
+      while (pending.length > 0) pending.shift()?.(value);
+    },
+  };
+}
+
+function makeCtx(channel: ReturnType<typeof makeSelectChannel>, sessionId = "sess-journal"): ExtensionContext {
+  return {
+    cwd: "/w",
+    mode: "rpc",
+    sessionManager: { getSessionId: () => sessionId },
+    ui: { select: channel.select },
+  } as unknown as ExtensionContext;
+
+}
+
+function makeNonRpcCtx(channel: ReturnType<typeof makeSelectChannel>): ExtensionContext {
+  return {
+    cwd: "/w",
+    mode: "tui",
+    sessionManager: { getSessionId: () => "sess-journal" },
+    ui: { select: channel.select },
+  } as unknown as ExtensionContext;
+}
+
+function parseFrame(call: SelectCall): Record<string, unknown> {
+  return JSON.parse(call.payload) as Record<string, unknown>;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+/** 推进 fake 时间并排空微任务（attempt 的 await 链走完）。 */
+async function advance(ms: number): Promise<void> {
+  await vi.advanceTimersByTimeAsync(ms);
+}
+
+describe("帧形状与单文件单帧（①使用者契约）", () => {
+  it("onJournalAppended → 单帧报告（title/marker、domain/fileKey/events/sessionId、控制面 timeout）", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createJournalReporter({ selectTimeoutMs: SELECT_TIMEOUT_MS });
+    reporter.attachSession(makeCtx(channel));
+
+    reporter.onJournalAppended("run", "wf-1", [{ type: "run-created", ts: 1, seq: 1 }]);
+    await advance(0);
+
+    expect(channel.calls).toHaveLength(1);
+    expect(channel.calls[0].title).toBe(SUBAGENT_JOURNAL_MARKER);
+    expect(channel.calls[0].timeout).toBe(SELECT_TIMEOUT_MS);
+    const frame = parseFrame(channel.calls[0]);
+    expect(frame.domain).toBe("run");
+    expect(frame.fileKey).toBe("wf-1");
+    expect(frame.events).toEqual([{ type: "run-created", ts: 1, seq: 1 }]);
+    expect(frame.sessionId).toBe("sess-journal");
+    expect(typeof frame.emittedAt).toBe("number");
+
+    channel.settleAll(JOURNAL_REPORT_ACK);
+    await advance(0);
+  });
+
+  it("在途期间同文件新事件并入待推缓冲（成功后作为下一帧）；不同文件逐帧发送（fileKey 单数契约）", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createJournalReporter();
+    reporter.attachSession(makeCtx(channel));
+
+    reporter.onJournalAppended("run", "wf-1", [{ type: "run-created", ts: 1, seq: 1 }]);
+    // 第一帧在途：同文件第二事件并入待推缓冲组；另一文件组队
+    reporter.onJournalAppended("run", "wf-1", [{ type: "agent-started", ts: 2, seq: 2 }]);
+    reporter.onJournalAppended("run", "wf-1", [{ type: "agent-settled", ts: 3, seq: 3 }]);
+    reporter.onJournalAppended("record", "sa-1", [{ type: "record-created", ts: 4, seq: 1 }]);
+    await advance(0);
+    expect(channel.calls).toHaveLength(1); // 在途串行化：不并发发帧
+
+    // 帧 0（run-created）ack 落定 → 缓冲组 wf-1（两事件已合并为一组）先发
+    channel.settle(0, JOURNAL_REPORT_ACK);
+    await advance(0);
+    expect(channel.calls).toHaveLength(2);
+    expect(parseFrame(channel.calls[1]).fileKey).toBe("wf-1");
+    expect(parseFrame(channel.calls[1]).events).toEqual([
+      { type: "agent-started", ts: 2, seq: 2 },
+      { type: "agent-settled", ts: 3, seq: 3 },
+    ]);
+
+    // 组间 FIFO：record 组随后
+    channel.settle(1, JOURNAL_REPORT_ACK);
+    await advance(0);
+    expect(channel.calls).toHaveLength(3);
+    expect(parseFrame(channel.calls[2]).fileKey).toBe("sa-1");
+    expect(parseFrame(channel.calls[2]).domain).toBe("record");
+    channel.settle(2, JOURNAL_REPORT_ACK);
+    await advance(0);
+  });
+});
+
+describe("失败折叠（设计 D5：缓冲即弃不重推，完整性归消费方缺口补读）", () => {
+  it("无 ack（超时形态）→ 待推缓冲整体丢弃；时间推进零重推，新事件重新起推", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createJournalReporter();
+    reporter.attachSession(makeCtx(channel));
+
+    reporter.onJournalAppended("run", "wf-1", [{ type: "run-created", ts: 1, seq: 1 }]);
+    await advance(0);
+    channel.settle(0, undefined); // 首帧失败落定（超时形态）
+    await advance(0);
+    // 在途期间并入的事件随失败一并丢弃（缓冲即弃）
+    expect(channel.calls).toHaveLength(1);
+
+    await advance(60_000); // 无 timer 自动重试
+    expect(channel.calls).toHaveLength(1);
+
+    // 新的落盘事件重新起推（缓冲已清空，新事件是唯一载荷——不补发丢失事件）
+    reporter.onJournalAppended("run", "wf-1", [{ type: "agent-started", ts: 2, seq: 2 }]);
+    await advance(0);
+    expect(channel.calls).toHaveLength(2);
+    expect((parseFrame(channel.calls[1]).events as unknown[]).length).toBe(1);
+    channel.settleAll(JOURNAL_REPORT_ACK);
+    await advance(0);
+  });
+
+  it("非确认回包（任意字符串）不算送达，同款缓冲即弃", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createJournalReporter();
+    reporter.attachSession(makeCtx(channel));
+    reporter.onJournalAppended("record", "sa-1", [{ type: "record-created", ts: 1, seq: 1 }]);
+    await advance(0);
+    channel.settle(0, '{"ok":1}');
+    await advance(0);
+    await advance(60_000);
+    expect(channel.calls).toHaveLength(1);
+  });
+});
+
+describe("生命周期与环境门控（③观察者）", () => {
+  it("onJournalAppended 同步返回：select 永不落定也不挂调用方（detach 可丢弃在途帧与缓冲）", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createJournalReporter();
+    reporter.attachSession(makeCtx(channel));
+
+    reporter.onJournalAppended("run", "wf-1", [{ type: "run-created", ts: 1, seq: 1 }]);
+    await advance(0);
+    // 第一帧挂起（模拟 runtime 无响应）——落盘出口调用仍同步返回
+    expect(() => reporter.onJournalAppended("run", "wf-1", [{ type: "agent-started", ts: 2, seq: 2 }])).not.toThrow();
+
+    // session 死后 detach：挂起帧被丢弃、缓冲清空，通道静止
+    reporter.detachSession();
+    channel.settleAll(undefined);
+    await advance(60_000);
+    expect(channel.calls).toHaveLength(1);
+  });
+
+  it("非 rpc 模式 no-op：不设 ctx，落盘事件零帧（裸 pi TUI 下 marker select 会弹真框）", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createJournalReporter();
+    reporter.attachSession(makeNonRpcCtx(channel));
+
+    reporter.onJournalAppended("run", "wf-1", [{ type: "run-created", ts: 1, seq: 1 }]);
+    await advance(60_000);
+    expect(channel.calls).toHaveLength(0);
+  });
+
+  it("attach 前的落盘事件不进缓冲（无 ctx 直返——factory 阶段落盘点早于 session_start 的窗口）", async () => {
+    const channel = makeSelectChannel();
+    const reporter = createJournalReporter();
+    reporter.onJournalAppended("run", "wf-1", [{ type: "run-created", ts: 1, seq: 1 }]);
+    await advance(0);
+    reporter.attachSession(makeCtx(channel));
+    await advance(0);
+    expect(channel.calls).toHaveLength(0); // 丢失面归消费方冷读收敛
+  });
+});

package/src/host/__tests__/staged-discovery.test.ts

@@ -0,0 +1,147 @@
+// staged-discovery.test.ts — 打包态内置资产**发现结果**门禁（档 2，2026-10-03 B′）
+//
+// 为什么单独建这个文件：本次事故（打包版 `subagents` 批量工具报
+// "Built-in workflow 'fan-out' is not available"）的根因是**发现层面**——esbuild
+// 自包含 bundle 下 `require.resolve("@zhushanwen/subagent-core/…")` 必败，staged 布局
+// 又无 node_modules，于是孝在包里的 `workflows/` 无人能扫到。既有门禁全是“文件在不在”
+// 级断言（dry-run import 不调工厂、TC8 只比字节），对本类失效天然失明。
+//
+// 本文件的断言对象是**发现结果**（6 内置 workflow + 10 内置 agent 真的被列出来），
+// 而非“文件存在”：前者才能拦住“路径/产物层”回归。两条通路都被锁：
+//   ① 纯函数：bundle 形态模块路径 → scope 根；dev/异常形态 → undefined（不误触发）；
+//   ② 集成：以合成 bundle 模块路径调 `corePackageNpmRoot()`（resolve 必败 → 回退分支），
+//      再把回退根当 npm 槽根跑**真实** `discoverResources`，断言结果与源目录逐文件一致。
+//
+// 资产集不写死数量（口径：与 `packages/subagent-core/{workflows,agents}` 源目录集合比对，
+// 源增删自动跟随）。
+
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { discoverResources, isTargetFile } from "@zhushanwen/subagent-core";
+import { afterAll, describe, expect, it, vi } from "vitest";
+
+// pi 宿主协作件 mock：本文件只跑发现链，日志面给可调用桩（回退分支会走 debug）。
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  getAgentDir: () => process.env.PI_CODING_AGENT_DIR ?? "/mock/agent-dir",
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+}));
+
+const { corePackageNpmRoot, stagedScopeRootFromModuleUrl } = await import("../pi-host.ts");
+
+/** 本仓 `packages/subagent-core`（源单源：断言口径由此推导，不写死数量）。
+ *  路径经与生产同一锚点解析得出（禁止手数 `..` 层级）。 */
+const CORE_PKG = dirname(
+  dirname(createRequire(import.meta.url).resolve("@zhushanwen/subagent-core/workflows/README.md")),
+);
+
+const tmpDirs: string[] = [];
+function makeTmp(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  tmpDirs.push(dir);
+  return dir;
+}
+afterAll(() => {
+  for (const d of tmpDirs) {
+    // teardown 递归删除补 maxRetries：与在途异步写竞争时 ENOTEMPTY 满载 flake
+    rmSync(d, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  }
+});
+
+/** 合成 staged 布局：<tmp>/@zhushanwen/pi-subagent-workflow/{index.js,workflows,agents}。 */
+function makeStagedLayout(): { scopeDir: string; moduleUrl: string } {
+  const root = makeTmp("staged-discovery-");
+  const pkgDir = join(root, "@zhushanwen", "pi-subagent-workflow");
+  mkdirSync(pkgDir, { recursive: true });
+  const indexJs = join(pkgDir, "index.js");
+  writeFileSync(indexJs, "// staged bundle placeholder\n", "utf8");
+  for (const kind of ["workflows", "agents"] as const) {
+    cpSync(join(CORE_PKG, kind), join(pkgDir, kind), { recursive: true });
+  }
+  return { scopeDir: join(root, "@zhushanwen"), moduleUrl: pathToFileURL(indexJs).href };
+}
+
+/** 源目录内可发现文件的集合——判据直接复用发现层导出的 isTargetFile（同一份
+ *  函数，发现层口径变化时期望集自动跟随，无双源）。 */
+function sourceExpected(kind: "workflows" | "agents"): string[] {
+  return readdirSync(join(CORE_PKG, kind))
+    .filter((f) => isTargetFile(f, kind))
+    .sort();
+}
+
+describe("B′：staged/bundle 形态的 core 资产发现根", () => {
+  it("stagedScopeRootFromModuleUrl：bundle 形态（<scope>/<pkg>/index.js）→ 返回 scope 目录", () => {
+    const { scopeDir, moduleUrl } = makeStagedLayout();
+    expect(stagedScopeRootFromModuleUrl(moduleUrl)).toBe(scopeDir);
+  });
+
+  it("stagedScopeRootFromModuleUrl：dev 形态（非 scope 布局）→ undefined（不误触发回退）", () => {
+    const devLike = pathToFileURL(join(CORE_PKG, "workflows", "fan-out.js")).href;
+    expect(stagedScopeRootFromModuleUrl(devLike)).toBeUndefined();
+  });
+
+  it("corePackageNpmRoot：dev/workspace 形态走 resolve 通路（不回退）", () => {
+    const root = corePackageNpmRoot();
+    expect(root).toBeDefined();
+    // workspace 形态：scope 根下必须有 subagent-core 包目录（resolve 命中锚点的上三级）
+    expect(readdirSync(root as string)).toContain("subagent-core");
+  });
+
+  it("corePackageNpmRoot：bundle 形态 resolve 必败 → 回退到 scope 根", () => {
+    const { scopeDir, moduleUrl } = makeStagedLayout();
+    expect(corePackageNpmRoot(moduleUrl)).toBe(scopeDir);
+  });
+});
+
+describe("B′：回退根下的**发现结果**（本批防复发的核心断言）", () => {
+  it("workflows：发现结果与源目录集合逐文件一致（内置模板全部可派发）", async () => {
+    const { scopeDir } = makeStagedLayout();
+    const found = await discoverResources({
+      kind: "workflows",
+      workspaceRoot: scopeDir,
+      hostRoots: [{ dir: scopeDir, source: "npm" }],
+    });
+    // 只断言**回退根下**的发现结果（发现面还包括真实用户目录 ~/.agents/workflows
+    // 等宿主/约定根——本用例的主题是回退根本身，故按路径范围收窄，噪声不介入）
+    const names = found
+      .filter((r) => r.available && r.path.startsWith(scopeDir))
+      .map((r) => r.path.split("/").pop() as string)
+      .sort();
+    expect(names).toEqual(sourceExpected("workflows"));
+    // 回归锚：批量入口的固定执行体必须在列
+    expect(names).toContain("fan-out.js");
+  });
+
+  it("agents：发现结果与源目录集合逐文件一致（10 内置角色全部可选）", async () => {
+    const { scopeDir } = makeStagedLayout();
+    const found = await discoverResources({
+      kind: "agents",
+      workspaceRoot: scopeDir,
+      hostRoots: [{ dir: scopeDir, source: "npm" }],
+    });
+    const names = found
+      .filter((r) => r.available && r.path.startsWith(scopeDir))
+      .map((r) => r.path.split("/").pop() as string)
+      .sort();
+    expect(names).toEqual(sourceExpected("agents"));
+    expect(names).toContain("general-purpose.md");
+  });
+
+  it("负向：源资产缺席时发现结果为空（门禁失败方向正确，不会假绿）", async () => {
+    const root = makeTmp("staged-discovery-empty-");
+    const pkgDir = join(root, "@zhushanwen", "pi-subagent-workflow");
+    mkdirSync(pkgDir, { recursive: true });
+    writeFileSync(join(pkgDir, "index.js"), "// no assets\n", "utf8");
+    const found = await discoverResources({
+      kind: "workflows",
+      workspaceRoot: join(root, "@zhushanwen"),
+      hostRoots: [{ dir: join(root, "@zhushanwen"), source: "npm" }],
+    });
+    expect(found.filter((r) => r.available)).toEqual([]);
+  });
+});