@zhushanwen/pi-subagent-workflow 8.14.3 → 8.14.4

package/src/injectors/workflow-list-injector.ts

@@ -36,9 +36,14 @@ import { createResourceListInjector } from "./resource-list-injector.ts";
  *
  * 引导语与具体 workflow 解耦：不写死内置名（列表本身已含全部 workflow，名字/描述
  * 每 turn 由 @pi-meta 动态注入），只给通用路由指引 + read location 参数指针。
+ *
+ * 末句 = 批量入口的 pi 壳附加句（D5③）：条目侧 when/notFor 走 fan-out.js 的 @pi-meta
+ * （宿主中立、双宿主共享，注入面只渲染 name/description/location，元数据经 read
+ * <location> 取）；「subagents tool 是 fan-out 的执行体」是 pi 壳专属表述，故放这里
+ * 而不进模板 meta——zsw 宿主清单注入不会照搬本句。
  */
 export const WORKFLOW_LIST_GUIDE =
-	"The following workflows are available. Do NOT call list to discover available workflows — they are listed below; use list only for running state. All listed workflows run directly via action:run — do NOT use workflow-script generate for any listed workflow. For parameter details, read the <location> script file (script header has @pi-meta parameters + usage).";
+	"The following workflows are available. Do NOT call list to discover available workflows — they are listed below; use list only for running state. All listed workflows run directly via action:run — do NOT use workflow-script generate for any listed workflow. For parameter details, read the <location> script file (script header has @pi-meta parameters + usage). For 2+ independent tasks dispatched together, prefer the `subagents` tool — it drives the fan-out workflow for you.";
 
 /**
  * 解析 workflow .js 文件的 meta（name + description），经 IF1 parseResourceMeta。

package/src/interface/__tests__/tool-subagents.test.ts

@@ -0,0 +1,494 @@
+// src/interface/__tests__/tool-subagents.test.ts
+//
+// u2 契约测试：`subagents` 批量 tool（schema 平铺 D2 / handler 转译 D3 / 错误规格 D9 /
+// 集合收录 D1 / 渲染不构造 __gui__ D8）。
+//
+// 三视角（docs/TEST-STRATEGY.md §3）：
+// - 构建者（白盒）：注册面 schema 形态（顶层键集/类型/必填形态）+ 转译 spec 组装。
+// - 使用者（黑盒）：模型看到的 tool description/guidelines 分工句；execute 的返回文案
+//   （一条通知 + 单次 status 恢复出口 + abort 指引）与错误文案（Correct 示例）。
+// - 观察者（真值源）：packages/shared/src/constants.ts 真模块（集合收录 SSOT）——
+//   动态 import 真文件，不用文本断言。
+//
+// mock 策略：lifecycle 深路径 stub（runWorkflow 为 vi.fn——不起真 Worker、真 worker
+// 线程只验证转译与 spec 组装）；registry/store 用最小 stub。框架：vitest（禁 node:test）。
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+/** 桩化 lifecycle——runWorkflow 为 vi.fn（只测入口转译面，不起 Worker）。 */
+vi.mock("@zhushanwen/subagent-core/orchestration/lifecycle.ts", () => ({
+  runWorkflow: vi.fn(),
+  abortRun: vi.fn(),
+}));
+
+import { runWorkflow } from "@zhushanwen/subagent-core/orchestration/lifecycle.ts";
+import { MAX_TIMER_DELAY_MS, SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core";
+import {
+  FAN_OUT_SCRIPT_NAME,
+  generateBatchSlug,
+  registerSubagentsTool,
+  runSubagentsBatch,
+} from "../tool-subagents.ts";
+import { REENTRY_BUSY_MESSAGE, type ReentryGuardRef } from "../reentry-guard.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TOOL_SRC = readFileSync(join(__dirname, "../tool-subagents.ts"), "utf-8");
+
+// ── 注册面最小类型（单层 cast：目标类型全必填，非 no-unsafe-cast 命中的全可选结构断言）──
+
+interface CapturedProperty {
+  type?: string;
+  optional?: boolean;
+}
+
+interface CapturedTool {
+  name: string;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: { type?: string; properties: Record<string, CapturedProperty> };
+  execute: (
+    toolCallId: string,
+    params: unknown,
+    signal: undefined,
+    onUpdate: unknown,
+    ctx: unknown,
+  ) => Promise<{ content: Array<{ type: string; text: string }>; details: Record<string, unknown> }>;
+  renderCall: (args: Record<string, unknown>, theme: ThemeStub, ctx?: unknown) => { render(width: number): string[] };
+  renderResult: (result: { content?: Array<{ type: string; text?: string }> }, options: unknown, theme: ThemeStub) => { render(width: number): string[] };
+}
+
+interface ThemeStub {
+  fg(token: string, text: string): string;
+  bold(text: string): string;
+}
+
+/** 注册并取回 tool 定义（fake pi 捕获 registerTool 入参）。 */
+function captureTool(reentryRef: ReentryGuardRef, registry: Record<string, unknown>): CapturedTool {
+  const captured: unknown[] = [];
+  const pi = {
+    registerTool: (tool: unknown): void => {
+      captured.push(tool);
+    },
+  };
+  registerSubagentsTool(pi as never, makeDeps(registry) as never, reentryRef);
+  expect(captured).toHaveLength(1);
+  return captured[0] as CapturedTool;
+}
+
+// ── registry / deps stubs ──
+
+/** fan-out 执行体 stub（toExecutable 形态与真 WorkflowScript 同签名）。 */
+function makeFanOutScript() {
+  return {
+    name: FAN_OUT_SCRIPT_NAME,
+    path: "/builtin/workflows/fan-out.js",
+    available: true,
+    sourceCode: "// fan-out source",
+    meta: {
+      description: "N 个已知独立任务并行派发并全量收集",
+      parameters: { type: "object", properties: { tasks: { type: "array" } } },
+    },
+    toExecutable: () => "// fan-out executable",
+  };
+}
+
+function makeRegistry(script?: ReturnType<typeof makeFanOutScript>): Record<string, unknown> {
+  return {
+    get: vi.fn().mockResolvedValue(script ?? makeFanOutScript()),
+    getPath: vi.fn().mockResolvedValue(undefined),
+    loadAll: vi.fn().mockResolvedValue([script ?? makeFanOutScript()]),
+    invalidate: vi.fn(),
+  };
+}
+
+/** 最小 deps stub（runWorkflow 已 mock；store 只消费 stateFilePath）。 */
+function makeDeps(registry: Record<string, unknown>): Record<string, unknown> {
+  return {
+    runs: new Map(),
+    store: { stateFilePath: (id: string) => `/tmp/state/${id}.jsonl` },
+    registry,
+  };
+}
+
+// ── theme stub（renderCall 只用 fg/bold）──
+
+function makeTheme(): ThemeStub {
+  return {
+    fg: (token, text) => `<${token}>${text}</${token}>`,
+    bold: (text) => `<b>${text}</b>`,
+  };
+}
+
+/** 取 TUI 组件构造时传入的文本（Text mock 把首参存为实例字段）。 */
+function renderedText(component: { render(width: number): string[] }): string {
+  const obj: Record<string, unknown> = component as unknown as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return "";
+}
+
+// ── 真值源：packages/shared/src/constants.ts（集合收录 SSOT）──
+
+interface SharedConstantsModule {
+  WORKFLOW_TOOL_NAMES: ReadonlySet<string>;
+  SUBAGENT_TOOL_NAMES: ReadonlySet<string>;
+}
+
+/** 动态 import 真 constants 模块（文本断言会漏「值被改」的漂移，故取真值）。 */
+async function loadSharedConstants(): Promise<SharedConstantsModule> {
+  const url = pathToFileURL(join(__dirname, "../../../../../../packages/shared/src/constants.ts")).href;
+  const mod: Record<string, unknown> = await import(/* @vite-ignore */ url);
+  const workflows = mod.WORKFLOW_TOOL_NAMES;
+  const subagents = mod.SUBAGENT_TOOL_NAMES;
+  if (!(workflows instanceof Set) || !(subagents instanceof Set)) {
+    throw new Error("packages/shared/src/constants.ts 缺 WORKFLOW_TOOL_NAMES / SUBAGENT_TOOL_NAMES 集合导出");
+  }
+  return { WORKFLOW_TOOL_NAMES: workflows, SUBAGENT_TOOL_NAMES: subagents };
+}
+
+// ── 公共夹具 ──
+
+const TWO_TASKS = ["count .ts files under src", "count .md files under src"];
+
+beforeEach(() => {
+  vi.mocked(runWorkflow).mockReset();
+  vi.mocked(runWorkflow).mockResolvedValue("wf-1700000000000-abcd");
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+/** 取最近一次 runWorkflow 的 spec（vi.fn 调用记录）。 */
+function lastSpec(): Record<string, unknown> {
+  expect(vi.mocked(runWorkflow)).toHaveBeenCalledTimes(1);
+  const call = vi.mocked(runWorkflow).mock.calls[0];
+  return call[0] as unknown as Record<string, unknown>;
+}
+
+// ══════════════════════════════════════════════════════════════
+describe("schema 契约：一跳扁平 + tasks 必填（D2）", () => {
+  it("注册名/label/description 存在，且以 batch 语义自述（one-shot 成员 + 一条通知）", () => {
+    const tool = captureTool({ isProcessing: false }, makeRegistry());
+    expect(tool.name).toBe("subagents");
+    expect(tool.label.length).toBeGreaterThan(0);
+    expect(tool.description).toContain("one-shot batch member");
+    expect(tool.description).toContain("ONE notification");
+    // 分工句（D5①）：单数 tool 指路 + 依赖链场景指路 workflow
+    expect(tool.description).toContain("`subagent` tool");
+    expect(tool.description).toContain("`workflow` tool");
+  });
+
+  it("参数全平铺：无 action 分发、无 args 嵌套、无嵌套 object 参数", () => {
+    const tool = captureTool({ isProcessing: false }, makeRegistry());
+    const keys = Object.keys(tool.parameters.properties);
+    expect(keys.sort()).toEqual(
+      ["agents", "aggregate", "model", "slug", "tasks", "thinkingLevel", "time", "tokens"].sort(),
+    );
+    expect(keys).not.toContain("action");
+    expect(keys).not.toContain("args");
+    for (const key of keys) {
+      expect(["string", "number", "boolean", "array"]).toContain(tool.parameters.properties[key]?.type);
+    }
+  });
+
+  it("tasks 为必填形态（未经 Type.Optional 构造）且类型为数组", () => {
+    const tool = captureTool({ isProcessing: false }, makeRegistry());
+    expect(tool.parameters.properties.tasks?.type).toBe("array");
+    // mock typebox 的 Optional 标记：tasks 不得带该标记（真 typebox 下即 required）
+    expect(tool.parameters.properties.tasks?.optional).toBeUndefined();
+    // 源码级：tasks 未经 Type.Optional 包裹（防 mock 失真面丢失 required 语义）
+    expect(TOOL_SRC).toContain("tasks: Type.Array(");
+    expect(TOOL_SRC).not.toContain("Type.Optional(Type.Array(");
+  });
+
+  it("slug 走 SLUG_MAX_LENGTH 上界（schema 第一道关卡 + 运行时第二道）", () => {
+    expect(TOOL_SRC).toContain("maxLength: SLUG_MAX_LENGTH");
+    expect(TOOL_SRC).toContain("SLUG_MAX_LENGTH");
+  });
+
+  it("文件头与 interface/subagents.ts（/subagents 命令壳）互指防混淆", () => {
+    expect(TOOL_SRC).toContain("interface/subagents.ts");
+    // 指认对面是 slash 命令（同名不同命名空间）
+    expect(TOOL_SRC.toLowerCase()).toContain("slash");
+  });
+
+  it("不构造 details.__gui__（D8：isWorkflow 块分支恒折叠不消费，构造即死代码）", () => {
+    // 文件头注释会提到 __gui__（记录 D8 裁决），故断言构造面：无 GUI 协议依赖 +
+    // 无描述符构造（属性赋值/工厂调用）。
+    expect(TOOL_SRC).not.toContain("@zhushanwen/extension-protocol");
+    expect(TOOL_SRC).not.toContain("__gui__:");
+    expect(TOOL_SRC).not.toContain("guiResult(");
+    expect(TOOL_SRC).not.toContain("isGuiCapable");
+  });
+
+  it("promptGuidelines 含分工句/调用正例/预算默认（弱模型结构信号依赖面）", () => {
+    const tool = captureTool({ isProcessing: false }, makeRegistry());
+    const guidelines = tool.promptGuidelines.join("\n");
+    expect(guidelines).toContain("2+ independent tasks in one dispatch");
+    expect(guidelines).toContain('{"tasks":[');
+    expect(guidelines).toContain("Do NOT set tokens/time unless the user explicitly requests");
+    expect(guidelines).toContain("workflow tool");
+  });
+});
+
+// ══════════════════════════════════════════════════════════════
+describe("handler 转译：runWorkflow('fan-out') 确定性映射（D3）", () => {
+  it("全参数调用 → spec 逐字段映射（scriptSource/budget/slug/model/thinkingLevel/args）", async () => {
+    const registry = makeRegistry();
+    const result = await runSubagentsBatch(
+      {
+        tasks: TWO_TASKS,
+        agents: "/abs/security.md,/abs/perf.md",
+        aggregate: true,
+        slug: "foo-tri-review",
+        model: "zai-coding-cn/glm-5.3-flash",
+        thinkingLevel: "max",
+        tokens: 100000,
+        time: 600000,
+      },
+      makeDeps(registry) as never,
+      undefined,
+    );
+
+    expect(registry.get).toHaveBeenCalledWith(FAN_OUT_SCRIPT_NAME);
+    const spec = lastSpec();
+    expect(spec.scriptSource).toBe("// fan-out executable");
+    expect(spec.scriptName).toBe(FAN_OUT_SCRIPT_NAME);
+    expect(spec.scriptPath).toBe("/builtin/workflows/fan-out.js");
+    expect(spec.parameters).toEqual({ type: "object", properties: { tasks: { type: "array" } } });
+    expect(spec.args).toEqual({
+      tasks: TWO_TASKS,
+      agents: "/abs/security.md,/abs/perf.md",
+      aggregate: true,
+    });
+    expect(spec.budgetTokens).toBe(100000);
+    expect(spec.budgetTimeMs).toBe(600000);
+    expect(spec.slug).toBe("foo-tri-review");
+    expect(spec.model).toBe("zai-coding-cn/glm-5.3-flash");
+    expect(spec.thinkingLevel).toBe("max");
+    // details：无 __gui__，携带 runId/stateFile（程序化消费面）
+    expect(Object.keys(result.details)).not.toContain("__gui__");
+    expect(result.details).toMatchObject({
+      runId: "wf-1700000000000-abcd",
+      status: "running",
+      scriptName: FAN_OUT_SCRIPT_NAME,
+      slug: "foo-tri-review",
+      taskCount: 2,
+      stateFile: "/tmp/state/wf-1700000000000-abcd.jsonl",
+    });
+  });
+
+  it("缺省参数不写入 args（不制造「都传/都缺」歧义形态）+ 预算缺省 undefined", async () => {
+    await runSubagentsBatch({ tasks: TWO_TASKS }, makeDeps(makeRegistry()) as never, undefined);
+    const spec = lastSpec();
+    expect(spec.args).toEqual({ tasks: TWO_TASKS });
+    expect(spec.budgetTokens).toBeUndefined();
+    expect(spec.budgetTimeMs).toBeUndefined();
+    expect(spec.model).toBeUndefined();
+    expect(spec.thinkingLevel).toBeUndefined();
+  });
+
+  it("返回文案：一条通知 + 单次 status 恢复出口 + abort 指引（设计 §3.1 全文）", async () => {
+    const result = await runSubagentsBatch(
+      { tasks: TWO_TASKS, slug: "foo-tri-review" },
+      makeDeps(makeRegistry()) as never,
+      undefined,
+    );
+    const text = result.content[0].text;
+    expect(text).toContain("Started batch 'foo-tri-review' (wf-1700000000000-abcd) as workflow run 'fan-out' — 2 subagents dispatched in parallel (allSettled).");
+    expect(text).toContain("Results arrive as ONE notification when the run settles. Do NOT poll.");
+    expect(text).toContain("make a SINGLE status check: workflow tool with runId wf-1700000000000-abcd (recovery exit, not a poll loop).");
+    expect(text).toContain("To abort: workflow tool, action abort, runId wf-1700000000000-abcd");
+    // status/abort 不复制：本 tool 无 action 参数（schema 已断言），文案只指路 workflow tool
+    expect(text).not.toContain('"action":"status"');
+    expect(text).not.toContain('"action":"abort"');
+  });
+});
+
+// ══════════════════════════════════════════════════════════════
+describe("slug 缺省生成 fan-out-<时间短码>（D8 状态面辨识）", () => {
+  it("generateBatchSlug 形态稳定且 ≤ SLUG_MAX_LENGTH(35)", () => {
+    expect(generateBatchSlug(0)).toBe("fan-out-0");
+    const slug = generateBatchSlug(1700000000000);
+    expect(slug).toMatch(/^fan-out-[0-9a-z]+$/);
+    expect(slug.length).toBeLessThanOrEqual(SLUG_MAX_LENGTH);
+  });
+
+  it("未提供 slug → spec.slug 为生成值（不是 undefined/空）", async () => {
+    await runSubagentsBatch({ tasks: TWO_TASKS }, makeDeps(makeRegistry()) as never, undefined);
+    expect(String(lastSpec().slug)).toMatch(/^fan-out-[0-9a-z]+$/);
+  });
+
+  it("空白 slug 按缺省处理；显式 slug 原样透传", async () => {
+    await runSubagentsBatch({ tasks: TWO_TASKS, slug: "   " }, makeDeps(makeRegistry()) as never, undefined);
+    expect(String(lastSpec().slug)).toMatch(/^fan-out-[0-9a-z]+$/);
+
+    vi.mocked(runWorkflow).mockClear();
+    await runSubagentsBatch({ tasks: TWO_TASKS, slug: "tri-review" }, makeDeps(makeRegistry()) as never, undefined);
+    expect(lastSpec().slug).toBe("tri-review");
+  });
+
+  it("生成的 slug 出现在启动文案与 details（状态面/文本面可对账）", async () => {
+    const result = await runSubagentsBatch({ tasks: TWO_TASKS }, makeDeps(makeRegistry()) as never, undefined);
+    const generated = result.details.slug;
+    expect(String(generated)).toMatch(/^fan-out-[0-9a-z]+$/);
+    expect(result.content[0].text).toContain(`Started batch '${String(generated)}'`);
+  });
+});
+
+// ══════════════════════════════════════════════════════════════
+describe("错误规格（D9）", () => {
+  it("tasks 缺失 → throw 带 Correct 示例（runWorkflow 未被调用）", async () => {
+    const err = await runSubagentsBatch({} as never, makeDeps(makeRegistry()) as never, undefined)
+      .catch((e: unknown) => e as Error);
+    expect(err.message).toBe('tasks is required (non-empty string array). Correct: {"tasks":["...","..."]}');
+    expect(vi.mocked(runWorkflow)).not.toHaveBeenCalled();
+  });
+
+  it("tasks 空数组 → 同一 Correct 文案", async () => {
+    const err = await runSubagentsBatch({ tasks: [] }, makeDeps(makeRegistry()) as never, undefined)
+      .catch((e: unknown) => e as Error);
+    expect(err.message).toContain("tasks is required (non-empty string array)");
+    expect(vi.mocked(runWorkflow)).not.toHaveBeenCalled();
+  });
+
+  it("time 超上界 → 入口 fail-fast（含上限与实际值，可自纠）", async () => {
+    const err = await runSubagentsBatch(
+      { tasks: TWO_TASKS, time: MAX_TIMER_DELAY_MS + 1 },
+      makeDeps(makeRegistry()) as never,
+      undefined,
+    ).catch((e: unknown) => e as Error);
+    expect(err.message).toContain(`time budget ${MAX_TIMER_DELAY_MS + 1} ms exceeds the maximum of ${MAX_TIMER_DELAY_MS} ms`);
+    expect(vi.mocked(runWorkflow)).not.toHaveBeenCalled();
+  });
+
+  it("slug 超长 → throw（含上限与建议形态）", async () => {
+    const err = await runSubagentsBatch(
+      { tasks: TWO_TASKS, slug: "x".repeat(SLUG_MAX_LENGTH + 1) },
+      makeDeps(makeRegistry()) as never,
+      undefined,
+    ).catch((e: unknown) => e as Error);
+    expect(err.message).toContain(`slug exceeds ${SLUG_MAX_LENGTH} chars`);
+    expect(vi.mocked(runWorkflow)).not.toHaveBeenCalled();
+  });
+
+  it("fan-out 执行体缺席/不可用 → throw 带恢复动作 + 可用清单（按名解析失败的自救指引）", async () => {
+    const registry = {
+      get: vi.fn().mockResolvedValue(undefined),
+      getPath: vi.fn().mockResolvedValue(undefined),
+      loadAll: vi.fn().mockResolvedValue([makeFanOutScript()]),
+      invalidate: vi.fn(),
+    };
+    const err = await runSubagentsBatch({ tasks: TWO_TASKS }, makeDeps(registry) as never, undefined)
+      .catch((e: unknown) => e as Error);
+    expect(err.message).toContain(`Built-in workflow 'fan-out' is not available`);
+    expect(err.message).toContain("Recovery:");
+    expect(err.message).toContain("  - fan-out:");
+    expect(vi.mocked(runWorkflow)).not.toHaveBeenCalled();
+  });
+
+  it("available:false stub 同样走 fail-fast（不静默空源码启动）", async () => {
+    const ghost = { ...makeFanOutScript(), available: false };
+    const registry = {
+      get: vi.fn().mockResolvedValue(ghost),
+      getPath: vi.fn().mockResolvedValue(undefined),
+      loadAll: vi.fn().mockResolvedValue([]),
+      invalidate: vi.fn(),
+    };
+    await expect(
+      runSubagentsBatch({ tasks: TWO_TASKS }, makeDeps(registry) as never, undefined),
+    ).rejects.toThrow(/not available/);
+    expect(vi.mocked(runWorkflow)).not.toHaveBeenCalled();
+  });
+});
+
+// ══════════════════════════════════════════════════════════════
+describe("reentry guard：与 workflow tool 共用同一实例", () => {
+  it("guard 被占用 → throw busy 文案，且不触达 runWorkflow", async () => {
+    const tool = captureTool({ isProcessing: true }, makeRegistry());
+    await expect(
+      tool.execute("call-1", { tasks: TWO_TASKS }, undefined, undefined, undefined),
+    ).rejects.toThrow(REENTRY_BUSY_MESSAGE);
+    expect(vi.mocked(runWorkflow)).not.toHaveBeenCalled();
+  });
+
+  it("成功路径释放 guard（同一 guard 可再次进入）", async () => {
+    const guard: ReentryGuardRef = { isProcessing: false };
+    const tool = captureTool(guard, makeRegistry());
+    await tool.execute("call-1", { tasks: TWO_TASKS }, undefined, undefined, undefined);
+    expect(guard.isProcessing).toBe(false);
+    await tool.execute("call-2", { tasks: TWO_TASKS }, undefined, undefined, undefined);
+    expect(vi.mocked(runWorkflow)).toHaveBeenCalledTimes(2);
+  });
+
+  it("失败路径经 finally 释放 guard（错误不粘住批量入口）", async () => {
+    const guard: ReentryGuardRef = { isProcessing: false };
+    const tool = captureTool(guard, makeRegistry());
+    const err = await tool.execute("call-1", {}, undefined, undefined, undefined).catch((e: unknown) => e as Error);
+    expect(err.message).toContain("tasks is required");
+    expect(guard.isProcessing).toBe(false);
+  });
+
+  it("signal 已 abort → 起步即 throw（不占 guard）", async () => {
+    const guard: ReentryGuardRef = { isProcessing: false };
+    const tool = captureTool(guard, makeRegistry());
+    const aborted = AbortSignal.abort();
+    await expect(
+      tool.execute("call-1", { tasks: TWO_TASKS }, aborted as never, undefined, undefined),
+    ).rejects.toThrow("Operation aborted before start");
+    expect(guard.isProcessing).toBe(false);
+    expect(vi.mocked(runWorkflow)).not.toHaveBeenCalled();
+  });
+});
+
+// ══════════════════════════════════════════════════════════════
+describe("集合收录（D1：单收录 WORKFLOW，不进 SUBAGENT）", () => {
+  it("'subagents' ∈ WORKFLOW_TOOL_NAMES 且 ∉ SUBAGENT_TOOL_NAMES", async () => {
+    const constants = await loadSharedConstants();
+    expect(constants.WORKFLOW_TOOL_NAMES.has("subagents")).toBe(true);
+    expect(constants.SUBAGENT_TOOL_NAMES.has("subagents")).toBe(false);
+    // 既有成员不回归
+    expect(constants.WORKFLOW_TOOL_NAMES.has("workflow")).toBe(true);
+    expect(constants.SUBAGENT_TOOL_NAMES.has("subagent")).toBe(true);
+  });
+});
+
+// ══════════════════════════════════════════════════════════════
+describe("TUI 渲染（renderCall/renderResult 既有惯例）", () => {
+  it("renderCall 单行：subagents + 任务数 + slug", () => {
+    const tool = captureTool({ isProcessing: false }, makeRegistry());
+    const text = renderedText(tool.renderCall(
+      { tasks: TWO_TASKS, slug: "foo-tri-review" },
+      makeTheme(),
+    ));
+    expect(text).toContain("subagents");
+    expect(text).toContain("2 tasks");
+    expect(text).toContain("foo-tri-review");
+    expect(text).not.toContain("\n");
+  });
+
+  it("renderCall 无 slug/无 tasks 时不崩（streaming partial args 形态）", () => {
+    const tool = captureTool({ isProcessing: false }, makeRegistry());
+    expect(() => tool.renderCall({}, makeTheme())).not.toThrow();
+    expect(() => tool.renderCall({ tasks: "not-an-array" }, makeTheme())).not.toThrow();
+  });
+
+  it("renderResult 透出返回文案（多行保留）", () => {
+    const tool = captureTool({ isProcessing: false }, makeRegistry());
+    const text = renderedText(tool.renderResult(
+      { content: [{ type: "text", text: "Started batch 'x' (wf-1) as workflow run 'fan-out'" }] },
+      undefined,
+      makeTheme(),
+    ));
+    expect(text).toContain("Started batch 'x'");
+  });
+});

package/src/interface/bg-notify-render.ts

@@ -79,9 +79,10 @@ interface BgNotifyRecord {
  *   display:true 时 Pi 调本方法，返回 BorderedBgBox（紫色背景 + 圆角边框）。
  *   details 异常 → 返回 undefined 走 Pi 默认渲染（兜底）。
  *
- *   details 两种形态：
- *     - 单条：BgNotifyRecord（status/agent/id/result/error）
- *     - 批量：{ batch: true, items: BgNotifyRecord[] }（notifier 合并窗口内多条完成）
+ *   details 形态（单条）：BgNotifyRecord（status/agent/id/result/error）。
+ *   [collect 退役] 批量形态的生产方（sync 批通知 notifyBatch）已删除，但 ledger 合并
+ *   投递（同边沿多条 pending 合批）仍会产 { batch: true, items } 批载荷——details
+ *   非单条形态走 Pi 默认渲染兜底（数据不丢，TUI 外观降级）。
  */
 export function renderBgNotifyMessage(
   message: { details?: unknown },
@@ -90,14 +91,6 @@ export function renderBgNotifyMessage(
 ): Component | undefined {
   const t = theme as ThemeLike;
 
-  // 批量分支：多条合并，各自渲染一行
-  const batch = extractBatch(message.details);
-  if (batch) {
-    const lines = batch.flatMap((r) => renderRecordLines(r, t));
-    return new BorderedBgBox(lines, t);
-  }
-
-  // 单条分支
   const record = extractBgNotifyRecord(message.details);
   if (!record) return undefined;
   return new BorderedBgBox(renderRecordLines(record, t), t);
@@ -262,22 +255,6 @@ function renderRecordLines(record: BgNotifyRecord, t: ThemeLike): string[] {
   }
 }
 
-/**
- * 从 message.details 防御性提取批量 record。
- * 形态：{ batch: true, items: BgNotifyRecord[] }。结构不全返回 undefined。
- */
-function extractBatch(details: unknown): BgNotifyRecord[] | undefined {
-  if (typeof details !== "object" || details === null) return undefined;
-  const d = details as Record<string, unknown>;
-  if (d.batch !== true || !Array.isArray(d.items)) return undefined;
-  const records: BgNotifyRecord[] = [];
-  for (const item of d.items) {
-    const r = extractBgNotifyRecord(item);
-    if (r) records.push(r);
-  }
-  return records.length > 0 ? records : undefined;
-}
-
 /**
  * details.closedReason 防御性收窄：任意字符串 → ClosedReason | undefined。
  * 旧数据/外部构造的非法值按缺失处理，交由 deriveOutcome 兑底（消费方不崩溃）。

package/src/interface/commands.ts

@@ -28,9 +28,7 @@ import { parseWorkflowRpcCommand, type WorkflowRpcAction } from "./command-actio
 import { createWorkflowsView, type ViewActions } from "./views/WorkflowsView.ts";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { LIST_LIMIT } from "./list-shared.ts";
-
-/** runId 截断长度（显示用）。 */
-const RUNID_SHORT = 8;
+import { ID_PREVIEW_LENGTH } from "./id-preview.ts";
 
 /** status 显示顺序：running 优先（活跃态在前），再 startedAt 倒序。 */
 const STATUS_ORDER: Record<string, number> = {
@@ -161,7 +159,7 @@ async function handleRpcMode(
       ctx.ui.notify(`Usage: /workflows ${parsed.verb} <runId>`, "warning");
       return;
     case "noop":
-      ctx.ui.notify("View workflows in the sidebar Flows tab", "info");
+      ctx.ui.notify("View workflows in the composer task tray", "info");
       return;
     default: {
       // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错
@@ -219,7 +217,7 @@ async function openFromList(
 
   // 多 run——select 选择
   const entries = all.map(
-    (r) => `${r.spec.scriptName} [${r.state.status}] (${r.runId.slice(0, RUNID_SHORT)})`,
+    (r) => `${r.spec.scriptName} [${r.state.status}] (${r.runId.slice(0, ID_PREVIEW_LENGTH)})`,
   );
   const selected = await ctx.ui.select("Select workflow:", entries);
   if (!selected) return;

package/src/interface/format.ts

@@ -2,7 +2,7 @@
 //
 // 纯格式化函数.零 Pi 依赖、零 runtime 依赖,可单测.
 //
-// 分隔符语义体系(tui-format.md §1,impeccable 审查裁定):
+// 分隔符语义体系(impeccable 审查裁定):
 //   `·` 同级并列字段/thinking 图标;`()` 元数据分组;`›` 工具;`>` 输出;`·` thinking.
 //   禁用 `│` 做 stats 分隔、`├─`/`└─` 做 eventLog 前缀.
 //
@@ -234,7 +234,7 @@ export function extractAgentName(args: unknown): string {
 /**
  * 格式化单条 eventLog 条目(带类型图标 + 着色,不含 `⎿` 前缀——前缀由调用方加).
  *
- * 标签语义(tui-conversation.md §7):
+ * 标签语义:
  *   tool:    tool_start/tool_end(尾部追加 ✓/✗)
  *   ── turn ──  turn_end(仅 expanded)
  *   error:   tool label + ✗