@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.0

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

@@ -51,6 +51,19 @@ const logger = getLogger("injector");
  */
 let agentCache: AgentEntry[] | null = null;
 
+/**
+ * 注入块渲染缓存（与 agentCache 同步更新）：before_agent_start 每个 turn 都要注入，
+ * formatAgentList（escapeXml 多趟正则 × 全部字段）在数据不变时输出完全相同——渲染
+ * 一次随缓存复用，turn 热路径零重复计算。
+ */
+let agentInjectionCache: string | null = null;
+
+/** agentCache 唯一写点：数据与渲染缓存同步更新（null 清空两者）。 */
+function setAgentCache(entries: AgentEntry[] | null): void {
+	agentCache = entries;
+	agentInjectionCache = entries !== null ? formatAgentList(entries) : null;
+}
+
 /** 从 .md frontmatter 提取的最小 agent 信息（m5：+ when/examples 路由样本；S1：+ path） */
 export interface AgentEntry {
 	name: string;
@@ -189,9 +202,11 @@ export function setupSubagentListInjector(pi: ExtensionAPI): void {
 		"session_start",
 		async (_event: SessionStartEvent, ctx: ExtensionContext): Promise<void> => {
 			try {
-				agentCache = await discoverAllAgents(
-					findWorkspaceRoot(ctx.cwd),
-					getAgentDir(),
+				setAgentCache(
+					await discoverAllAgents(
+						findWorkspaceRoot(ctx.cwd),
+						getAgentDir(),
+					),
 				);
 			} catch (err) {
 				// fail-safe：发现异常不阻断 session，缓存保持 null（before_agent_start 会 fallback）
@@ -211,12 +226,15 @@ export function setupSubagentListInjector(pi: ExtensionAPI): void {
 			try {
 				// 读缓存；miss（session_start 未触发/缓存被清）则 fallback 重新发现+赋值
 				if (agentCache === null) {
-					agentCache = await discoverAllAgents(
-						findWorkspaceRoot(ctx.cwd),
-						getAgentDir(),
+					setAgentCache(
+						await discoverAllAgents(
+							findWorkspaceRoot(ctx.cwd),
+							getAgentDir(),
+						),
 					);
 				}
-				const injection = formatAgentList(agentCache);
+				// agentInjectionCache 与 agentCache 不变量同步（setAgentCache 保证），直接复用
+				const injection = agentInjectionCache;
 				if (!injection) return;
 				return { systemPrompt: event.systemPrompt + injection };
 			} catch (err) {
@@ -230,7 +248,7 @@ export function setupSubagentListInjector(pi: ExtensionAPI): void {
 	pi.on(
 		"session_shutdown",
 		(_event: SessionShutdownEvent, _ctx: ExtensionContext): void => {
-			agentCache = null;
+			setAgentCache(null);
 		},
 	);
 }

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

@@ -43,6 +43,18 @@ const logger = getLogger("injector");
  */
 let workflowCache: WorkflowEntry[] | null = null;
 
+/**
+ * 注入块渲染缓存（与 workflowCache 同步更新）：before_agent_start 每个 turn 都要注入，
+ * formatWorkflowList 在数据不变时输出完全相同——渲染一次随缓存复用。
+ */
+let workflowInjectionCache: string | null = null;
+
+/** workflowCache 唯一写点：数据与渲染缓存同步更新（null 清空两者）。 */
+function setWorkflowCache(entries: WorkflowEntry[] | null): void {
+	workflowCache = entries;
+	workflowInjectionCache = entries !== null ? formatWorkflowList(entries) : null;
+}
+
 /** 注入段中单个 workflow 的最大描述长度（控制每 turn prompt 体积） */
 const MAX_DESC_LEN = 160;
 
@@ -172,9 +184,11 @@ export function setupWorkflowListInjector(pi: ExtensionAPI): void {
 		"session_start",
 		async (_event: SessionStartEvent, ctx: ExtensionContext): Promise<void> => {
 			try {
-				workflowCache = await discoverAllWorkflows(
-					findWorkspaceRoot(ctx.cwd),
-					getAgentDir(),
+				setWorkflowCache(
+					await discoverAllWorkflows(
+						findWorkspaceRoot(ctx.cwd),
+						getAgentDir(),
+					),
 				);
 			} catch (err) {
 				// fail-safe：发现异常不阻断 session，缓存保持 null（before_agent_start 会 fallback）
@@ -194,12 +208,15 @@ export function setupWorkflowListInjector(pi: ExtensionAPI): void {
 			try {
 				// 读缓存；miss（session_start 未触发/缓存被清）则 fallback 重新发现+赋值
 				if (workflowCache === null) {
-					workflowCache = await discoverAllWorkflows(
-						findWorkspaceRoot(ctx.cwd),
-						getAgentDir(),
+					setWorkflowCache(
+						await discoverAllWorkflows(
+							findWorkspaceRoot(ctx.cwd),
+							getAgentDir(),
+						),
 					);
 				}
-				const injection = formatWorkflowList(workflowCache);
+				// workflowInjectionCache 与 workflowCache 不变量同步（setWorkflowCache 保证），直接复用
+				const injection = workflowInjectionCache;
 				if (!injection) return;
 				return { systemPrompt: event.systemPrompt + injection };
 			} catch (err) {
@@ -213,7 +230,7 @@ export function setupWorkflowListInjector(pi: ExtensionAPI): void {
 	pi.on(
 		"session_shutdown",
 		(_event: SessionShutdownEvent, _ctx: ExtensionContext): void => {
-			workflowCache = null;
+			setWorkflowCache(null);
 		},
 	);
 }

package/src/interface/__tests__/subagent-tool-prompt.test.ts

@@ -31,12 +31,16 @@ function extractDescription(src: string): string {
 const DESCRIPTION = extractDescription(SUBAGENT_TOOL_SRC);
 
 describe("subagent tool description — 行为约束器（非功能说明书）", () => {
-  it("词数 ≤ 550（高风险 description 密度上限）", () => {
+  it("词数 ≤ 800（高风险 description 密度上限）", () => {
     // 高风险 tool 的 description 应聚焦约束而非功能铺陈；过长会稀释信号。
-    // 上限从 400 放宽到 550：补了 JSON 调用正例段（start/list/cancel 三 action 完整 JSON），
-    // 正例对弱模型首次调用用对参数的价值 > 节省这点 description 预算。
+    // 上限演进：400 → 550（补 start/list/cancel 三 action 完整 JSON 正例）→
+    // 650（M2-B3 新增 message/close 两 action + conversation 对话模式 + 例子）→
+    // 800（递归指导：树形判据 + 自包含 task + 独立验收 + fork 成本警告）。
+    // 800 是断言的真实预算（标题与本值一致）；留 ≥60 词余量供后续措辞微调，
+    // 逼近上限时优先精简正文而非再放宽断言。
+    // 每次 action 扩展必然增加必需描述；正例对弱模型首次用对参数的价值 > 节省 description 预算。
     const words = DESCRIPTION.trim().split(/\s+/).filter(Boolean).length;
-    expect(words).toBeLessThanOrEqual(550);
+    expect(words).toBeLessThanOrEqual(800);
   });
 
   it("含 'When to delegate' 调用条件段（何时委派 vs 自己做）", () => {
@@ -78,6 +82,15 @@ describe("subagent tool description — 行为约束器（非功能说明书）"
     expect(DESCRIPTION).toMatch(/Depth: N\/10/);
   });
 
+  it("递归指导含树形判据 + 自包含 task + 独立验收 + 深度定位", () => {
+    // 递归不是「能套就套」，必须有明确使用判据，否则 LLM 会滥用深递归。
+    const lower = DESCRIPTION.toLowerCase();
+    expect(lower).toContain("tree-shaped");          // 树形判据
+    expect(lower).toContain("self-contained");        // task 自包含
+    expect(lower).toContain("acceptance criteria");   // 独立验收
+    expect(lower).toContain("safety rail");           // 深度定位：10 是护栏非预算
+  });
+
   it("保留 executionMode sequential 的 CRITICAL 说明", () => {
     // sequential 是关键执行语义，删了会导致 LLM 误以为并行可用。
     expect(DESCRIPTION).toMatch(/CRITICAL/i);

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

@@ -80,39 +80,41 @@ describe("renderSubagentCall — 拍平形态提取（regression for wave 3 flat
     expect(out).toContain("fix-login");
   });
 
-  it("从顶层 args 提取 task 作为 preview 行（含换行）", () => {
+  it("task 不再渲染为 preview 行（标题块只有单行）", () => {
     const out = renderText(renderSubagentCall(
       { action: "start", agent: "coder", task: "Analyze the bug in parser", slug: "fix-parser" },
       makeTheme() as never,
       CTX,
     ));
-    // task preview 出现在结果里（首行非空，截断到 60 字符）
-    expect(out).toContain("Analyze the bug in parser");
+    // task 预览行已移除——task 内容不进对话流（完整 task 在 /subagents 详情可见）
+    expect(out).not.toContain("Analyze the bug in parser");
+    expect(out).not.toContain("\n");
   });
 
-  it("task 含换行时只取首个非空行（不破坏单行渲染）", () => {
+  it("task 含换行时不进渲染（无 preview 泄漏）", () => {
     const out = renderText(renderSubagentCall(
       { action: "start", task: "first line\nsecond line", slug: "x" },
       makeTheme() as never,
       CTX,
     ));
-    expect(out).toContain("first line");
+    expect(out).not.toContain("first line");
     expect(out).not.toContain("second line");
+    expect(out).not.toContain("\n");
   });
 
   // 关键回归：若有人把提取路径改回 args.startParam，这些顶层调用都会失败
-  // （agent/slug/task 取不到，全用默认值）。此测试用顶层数据形态锁住 flatten。
+  // （agent/slug 取不到，全用默认值）。此测试用顶层数据形态锁住 flatten。
+  // task 不在断言里——task 已不渲染（上方用例锁定）。
   it("REGRESSION: 顶层 args 形态完整提取（防止回退到 startParam envelope）", () => {
     const out = renderText(renderSubagentCall(
       { action: "start", agent: "researcher", task: "search docs", slug: "search-docs" },
       makeTheme() as never,
       CTX,
     ));
-    // 三个字段都应被提取（默认值 fallback 也能过单字段断言，但同时命中的
+    // agent + slug 都应被提取（默认值 fallback 也能过单字段断言，但同时命中的
     // 概率只有联合 fallback 才有——researcher/search-docs 都不是默认值）
     expect(out).toContain("researcher");
     expect(out).toContain("search-docs");
-    expect(out).toContain("search docs");
   });
 
   it("args 缺所有字段时不崩（最防御）", () => {

package/src/interface/__tests__/tool-workflow-script-generate.test.ts

@@ -10,13 +10,19 @@ import { mkdirSync, writeFileSync } from "node:fs";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { actionGenerate, type ScriptParams, type TextContent } from "../tool-workflow-script.ts";
+import { actionGenerate, type ScriptParams, type TextContent, registerWorkflowScriptTool } from "../tool-workflow-script.ts";
+import { deleteWorkflow, saveWorkflow } from "../../orchestration/workflow-files.ts";
 
 vi.mock("node:fs", () => ({
   mkdirSync: vi.fn(),
   writeFileSync: vi.fn(),
 }));
 
+vi.mock("../../orchestration/workflow-files.ts", () => ({
+  saveWorkflow: vi.fn(),
+  deleteWorkflow: vi.fn(),
+}));
+
 const mockedWriteFileSync = vi.mocked(writeFileSync);
 const mockedMkdirSync = vi.mocked(mkdirSync);
 
@@ -106,6 +112,12 @@ describe("actionGenerate (m0: @pi-meta 认可 + round-trip)", () => {
     vi.clearAllMocks();
   });
 
+  /**
+   * W4b：generate 校验族错误路径从 return {isError:true} 改为 throw（pi 只对
+   * execute throw 置 isError:true，返回值 isError 被 agent-loop 丢弃）。
+   * actionGenerate 是同步函数——断言用同步 toThrow。
+   */
+
   it("TC1: 合法 @pi-meta → ready + writeFileSync 被调用", () => {
     const r = actionGenerate(gen(PI_META_VALID), undefined);
     expect(r.isError).toBeFalsy();
@@ -113,10 +125,10 @@ describe("actionGenerate (m0: @pi-meta 认可 + round-trip)", () => {
     expect(mockedWriteFileSync).toHaveBeenCalledTimes(1);
   });
 
-  it("TC2: malformed @pi-meta YAML → error + writeFileSync 未调用 [P-generate-roundtrip]", () => {
-    const r = actionGenerate(gen(PI_META_MALFORMED), undefined);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/cannot be parsed|无法解析|line/i);
+  it("TC2: malformed @pi-meta YAML → throw + writeFileSync 未调用 [P-generate-roundtrip]", () => {
+    expect(() => actionGenerate(gen(PI_META_MALFORMED), undefined)).toThrow(
+      /cannot be parsed/i,
+    );
     expect(mockedWriteFileSync).not.toHaveBeenCalled();
   });
 
@@ -126,38 +138,103 @@ describe("actionGenerate (m0: @pi-meta 认可 + round-trip)", () => {
     expect(mockedWriteFileSync).toHaveBeenCalledTimes(1);
   });
 
-  it("TC4: 无 meta → error 提及 @pi-meta 新格式", () => {
-    const r = actionGenerate(gen(NO_META), undefined);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/meta declaration/i);
-    expect(textOf(r)).toMatch(/pi-meta/i);
+  it("TC4: 无 meta → throw 提及 @pi-meta 新格式", () => {
+    expect(() => actionGenerate(gen(NO_META), undefined)).toThrow(/meta declaration/i);
     expect(mockedWriteFileSync).not.toHaveBeenCalled();
   });
 
-  it("TC5: @pi-meta 单反斜杠正则 → error（LLM 高频错）[P-generate-roundtrip]", () => {
-    const r = actionGenerate(gen(PI_META_REGEX_SINGLE_BS), undefined);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/escape|cannot be parsed|无法解析|line/i);
+  it("TC5: @pi-meta 单反斜杠正则 → throw（LLM 高频错）[P-generate-roundtrip]", () => {
+    expect(() => actionGenerate(gen(PI_META_REGEX_SINGLE_BS), undefined)).toThrow(
+      /escape|cannot be parsed/i,
+    );
     expect(mockedWriteFileSync).not.toHaveBeenCalled();
   });
 
-  it("TC6: ESM import → reject（保留现有行为）", () => {
-    const r = actionGenerate(gen(ESM_IMPORT), undefined);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/ESM|import/i);
+  it("TC6: ESM import → throw（保留现有行为）", () => {
+    expect(() => actionGenerate(gen(ESM_IMPORT), undefined)).toThrow(/ESM|import/i);
   });
 
-  it("TC7: 无 agent() → reject（保留现有行为）", () => {
-    const r = actionGenerate(gen(NO_AGENT), undefined);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/agent\(\)/i);
+  it("TC7: 无 agent() → throw（保留现有行为）", () => {
+    expect(() => actionGenerate(gen(NO_AGENT), undefined)).toThrow(/agent\(\)/i);
   });
 
-  it("TC8: signal aborted → reject（保留现有行为）", () => {
+  it("TC8: signal aborted → throw（保留现有行为）", () => {
     const controller = new AbortController();
     controller.abort();
-    const r = actionGenerate(gen(PI_META_VALID), controller.signal);
-    expect(r.isError).toBe(true);
-    expect(textOf(r)).toMatch(/abort/i);
+    expect(() => actionGenerate(gen(PI_META_VALID), controller.signal)).toThrow(/abort/i);
+  });
+
+  it("TC9: 缺 name/script 参数 → throw 'generate requires'（防御性，schema 先拦）", () => {
+    expect(() => actionGenerate({ action: "generate" } as ScriptParams, undefined)).toThrow(
+      "generate requires 'name' and 'script' parameters",
+    );
+  });
+
+  it("TC10: ESM export（非 meta）→ throw（W4b 收敛路径）", () => {
+    const script = `/* @pi-meta
+name: x
+description: d
+phases: [a]
+*/
+const agent = require("./agent");
+export const foo = 1;
+agent("w");
+`;
+    expect(() => actionGenerate(gen(script), undefined)).toThrow(/ESM 'export'/i);
+  });
+});
+
+describe("actionSave/actionDelete error paths (W4: throw 范式)", () => {
+  /**
+   * W4：save/delete 失败路径从 return {isError:true} 改为 throw——pi 只对 execute
+   * throw 置 isError:true（agent-loop.js:453-483 丢弃返回值里的 isError）。
+   * 经 registerWorkflowScriptTool 注册层测（mock workflow-files 的 FS 依赖）。
+   */
+  interface CapturedTool {
+    execute: (
+      toolCallId: string,
+      params: Record<string, unknown>,
+      signal: AbortSignal | undefined,
+      onUpdate: unknown,
+      ctx: unknown,
+    ) => Promise<TextContent>;
+  }
+  function captureTool(): CapturedTool {
+    const tools: CapturedTool[] = [];
+    const pi = { registerTool: (t: unknown) => tools.push(t as CapturedTool) };
+    // registry 最小 stub：delete 成功路径会调 invalidate（失败路径 throw 前不触达）
+    const registry = { invalidate: vi.fn() };
+    registerWorkflowScriptTool(pi as never, registry as never, () => false);
+    if (!tools[0]) throw new Error("registerWorkflowScriptTool did not register");
+    return tools[0];
+  }
+  const ctx = { mode: "tui" as const, hasUI: true };
+
+  it("save 失败 → throw 'Save failed: <原因>'（pi catch 后置 isError:true）", async () => {
+    vi.mocked(saveWorkflow).mockRejectedValueOnce(new Error("disk full"));
+    const tool = captureTool();
+    await expect(
+      tool.execute("id", { action: "save", name: "tmp-wf" }, undefined, undefined, ctx),
+    ).rejects.toThrow("Save failed: disk full");
+  });
+
+  it("delete 失败 → throw 'Delete failed: <原因>'", async () => {
+    // deleteWorkflow 是同步函数——mock 用同步 throw（mockRejectedValue 不会被
+    // actionDelete 的同步 try/catch 捕获）
+    vi.mocked(deleteWorkflow).mockImplementationOnce(() => {
+      throw new Error("script is running");
+    });
+    const tool = captureTool();
+    await expect(
+      tool.execute("id", { action: "delete", name: "tmp-wf" }, undefined, undefined, ctx),
+    ).rejects.toThrow("Delete failed: script is running");
+  });
+
+  it("save 成功路径不受影响（ok details 正常返回）", async () => {
+    vi.mocked(saveWorkflow).mockResolvedValueOnce("saved tmp-wf");
+    const tool = captureTool();
+    const r = await tool.execute("id", { action: "save", name: "tmp-wf" }, undefined, undefined, ctx);
+    expect(r.isError).toBeFalsy();
+    expect(r.details).toMatchObject({ action: "save", name: "tmp-wf", ok: true });
   });
 });

package/src/interface/__tests__/tool-workflow-throw-paths.test.ts

@@ -0,0 +1,179 @@
+/**
+ * W4b：workflow tool 错误路径 throw 语义（代表路径）。
+ *
+ * pi 只对 execute throw 置 isError:true——返回值里的 isError 被 agent-loop 丢弃
+ * （agent-loop.js:453-483），故错误路径必须 throw。本文件抽 4 个代表路径
+ * （W4b 验收交付物 3）：
+ * - not_found（abort 目标 runId 不存在）
+ * - reentry-busy（guard 占用，throw 前未 acquire）
+ * - 平铺检测（args 子字段平铺到顶层，LLM 常见错误）
+ * - slug 护栏（schema maxLength 之后的运行时第二道）
+ * generate 校验族（第 5 代表路径）见 tool-workflow-script-generate.test.ts。
+ *
+ * 经 registerWorkflowTool 注册层测（capture tool + 最小 deps stub），
+ * 与 W4 save/delete 测试同范式。框架：vitest。
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import { SLUG_MAX_LENGTH } from "../../execution/execute-options-mapper.ts";
+import { REENTRY_BUSY_MESSAGE, type ReentryGuardRef } from "../reentry-guard.ts";
+import { registerWorkflowTool } from "../tool-workflow.ts";
+
+// ── capture helper ──
+
+interface CapturedTool {
+  name: string;
+  execute: (
+    toolCallId: string,
+    params: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    ctx: unknown,
+  ) => Promise<unknown>;
+}
+
+function captureTool(deps: unknown, reentryRef: ReentryGuardRef): CapturedTool {
+  const tools: CapturedTool[] = [];
+  const pi = { registerTool: (t: unknown) => tools.push(t as CapturedTool) };
+  registerWorkflowTool(pi as never, deps as never, reentryRef);
+  if (!tools[0] || tools[0].name !== "workflow") {
+    throw new Error("registerWorkflowTool did not register the workflow tool");
+  }
+  return tools[0];
+}
+
+/** 最小 LauncherDeps stub：被测路径只触 registry / runs。 */
+function makeDeps(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    runs: new Map(),
+    registry: {
+      getPath: vi.fn().mockResolvedValue(undefined),
+      loadAll: vi.fn().mockResolvedValue([]),
+    },
+    ...overrides,
+  };
+}
+
+/** 平铺检测 / slug 护栏路径的 registry script stub（meta.parameters 驱动已知键集）。 */
+function makeScript(parameters?: object): Record<string, unknown> {
+  return {
+    name: "demo-wf",
+    path: "/abs/demo-wf.js",
+    available: true,
+    sourceCode: "// demo",
+    meta: { description: "demo workflow", parameters },
+    toExecutable: () => "// demo",
+  };
+}
+
+// ── 代表路径 ──
+
+describe("W4b: workflow tool 错误路径 throw 语义", () => {
+  it("not_found：abort 目标 runId 不存在 → throw（pi catch 后置 isError:true）", async () => {
+    const tool = captureTool(makeDeps(), { isProcessing: false });
+    await expect(
+      tool.execute("id", { action: "abort", runId: "no-such-run" }, undefined, undefined, {}),
+    ).rejects.toThrow(
+      "Workflow 'no-such-run' not found. Use action:status to list active runs and their runIds.",
+    );
+  });
+
+  it("W4c not_found：run 目标路径不可读（getPath 返回 available:false stub 而非 undefined）→ throw，不假启动", async () => {
+    // config-loader.toCachedMeta 对不存在/不可读文件返回 available:false 的空壳实体
+    // （非 undefined）——旧判定仅 !script 绕过 not_found，空 sourceCode 的 run 假启动
+    // （W4b verifier 探针实测复现）。registry 层真行为见 config-loader.ts:143-151。
+    const deps = makeDeps({
+      registry: {
+        getPath: vi.fn().mockResolvedValue({
+          name: "ghost-wf",
+          path: "/tmp/no-such-workflow.js",
+          available: false,
+          sourceCode: "",
+          meta: { description: "", parameters: undefined },
+          toExecutable: () => "",
+        }),
+        loadAll: vi.fn().mockResolvedValue([]),
+      },
+    });
+    const tool = captureTool(deps, { isProcessing: false });
+    await expect(
+      tool.execute("id", { action: "run", name: "/tmp/no-such-workflow.js" }, undefined, undefined, {}),
+    ).rejects.toThrow("Workflow '/tmp/no-such-workflow.js' not found.");
+    // 未假启动：runs 注册表不出现该 run
+    expect(deps.runs).toBeInstanceOf(Map);
+    expect((deps.runs as Map<string, unknown>).size).toBe(0);
+  });
+
+  it("reentry-busy：guard 占用 → throw REENTRY_BUSY_MESSAGE，且 guard 状态不被污染", async () => {
+    const guard: ReentryGuardRef = { isProcessing: true };
+    const tool = captureTool(makeDeps(), guard);
+    await expect(
+      tool.execute("id", { action: "status" }, undefined, undefined, {}),
+    ).rejects.toThrow(REENTRY_BUSY_MESSAGE);
+    // throw 发生在 acquire 之前——占用方语义保持，不产生双重 release
+    expect(guard.isProcessing).toBe(true);
+  });
+
+  it("平铺检测：args 子字段提到顶层 → throw 'Detected ... at top level'（含 Correct 正例）", async () => {
+    const deps = makeDeps({
+      registry: {
+        getPath: vi.fn().mockResolvedValue(
+          makeScript({
+            type: "object",
+            properties: { task: { type: "string" }, items: { type: "array" } },
+            required: ["task"],
+          }),
+        ),
+      },
+    });
+    const tool = captureTool(deps, { isProcessing: false });
+    await expect(
+      tool.execute(
+        "id",
+        { action: "run", name: "/abs/demo-wf.js", task: "do work" },
+        undefined,
+        undefined,
+        {},
+      ),
+    ).rejects.toThrow(
+      /Detected task at top level — they belong inside 'args'\. Correct: \{"action":"run","name":"\/abs\/demo-wf\.js","args":\{"task": "<value>"\}\}/,
+    );
+  });
+
+  it("slug 护栏：slug 超 SLUG_MAX_LENGTH → throw 'slug exceeds ...'（运行时第二道）", async () => {
+    const deps = makeDeps({
+      registry: {
+        getPath: vi.fn().mockResolvedValue(
+          makeScript({
+            type: "object",
+            properties: { task: { type: "string" } },
+            required: ["task"],
+          }),
+        ),
+      },
+    });
+    const tool = captureTool(deps, { isProcessing: false });
+    const longSlug = "a".repeat(SLUG_MAX_LENGTH + 1);
+    await expect(
+      tool.execute(
+        "id",
+        { action: "run", name: "/abs/demo-wf.js", slug: longSlug, args: {} },
+        undefined,
+        undefined,
+        {},
+      ),
+    ).rejects.toThrow(
+      `slug exceeds ${SLUG_MAX_LENGTH} chars (got ${longSlug.length}). Shorten to a kebab-case label, e.g. "fix-login", "extract-urls".`,
+    );
+  });
+
+  it("throw 后 reentry guard 经 finally 正常释放（成功路径回归）", async () => {
+    // abort not_found throw 穿透 execute try/finally：guard 必须复位，否则后续命令全部 busy
+    const guard: ReentryGuardRef = { isProcessing: false };
+    const tool = captureTool(makeDeps(), guard);
+    await expect(
+      tool.execute("id", { action: "abort", runId: "no-such-run" }, undefined, undefined, {}),
+    ).rejects.toThrow(/not found/);
+    expect(guard.isProcessing).toBe(false);
+  });
+});

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

@@ -22,6 +22,7 @@
 import type { Component } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
+import { displayAgentName } from "../shared/agent-ref.ts";
 import {
   firstLine,
   padToVisible,
@@ -52,11 +53,16 @@ const MIN_BORDER_WIDTH = BORDER_CHARS + INNER_PAD_TOTAL + 1;
  */
 interface BgNotifyRecord {
   id: string;
-  status: "done" | "failed" | "cancelled";
+  /** v4 B-1: closed（终态，含 cancelled）或 running（对话模式轮次完成，旧 idle）。 */
+  status: "running" | "closed";
+  /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。 */
+  closedReason?: string;
   agent: string;
   model?: string;
   result?: string;
   error?: string;
+  /** 对话轮次计数（仅 idle 有意义）。 */
+  round?: number;
   /** [MF#1] worktree background 完成通知携带的 patch 文件路径。 */
   patchFile?: string;
 }
@@ -207,17 +213,34 @@ function sanitizeAnsiForBg(text: string): string {
 function renderRecordLines(record: BgNotifyRecord, t: ThemeLike): string[] {
   const glyph = statusGlyph(record.status);
   const icon = glyph.icon ?? "•";
-  const agent = truncLine(record.agent, AGENT_MAX_WIDTH);
+  const agent = truncLine(displayAgentName(record.agent), AGENT_MAX_WIDTH);
   // model 段：agent 后、状态描述前，accent 色。空则省略（向后兼容旧 record）。
   const modelPart = record.model
     ? ` ${t.fg("dim", "·")} ${t.fg("accent", truncLine(record.model, MODEL_MAX_WIDTH))}`
     : "";
-  const verb = record.status === "done" ? "finished" : record.status === "failed" ? "failed" : "cancelled";
+  // v4 B-1: closed 统一终态（含 cancelled）。按 closedReason 派生文案。
+  const reason = record.closedReason ?? "gc";
+  let verb: string;
+  if (reason === "cancelled") {
+    verb = "cancelled";
+  } else if (reason === "gc" && record.error) {
+    verb = "failed";
+  } else {
+    verb = "finished";
+  }
   const idShort = shortId(record.id);
   const head = `${t.fg(glyph.color, icon)} ${t.bold(agent)}${modelPart}${t.fg("dim", ` — background subagent ${verb} - ${idShort}`)}`;
 
   switch (record.status) {
-    case "done": {
+    case "closed": {
+      // v4 B-1: closed 统一终态（含 cancelled）。cancelled 无正文；失败显示错误；否则结果/patch。
+      const r = record.closedReason ?? "gc";
+      if (r === "cancelled") {
+        return [head];
+      }
+      if (r === "gc" && record.error) {
+        return [head, t.fg("dim", truncLine(`Error: ${firstLineSanitized(record.error)}`, BODY_MAX_WIDTH))];
+      }
       if (!record.result && !record.patchFile) return [head];
       const lines: string[] = [];
       if (record.result) {
@@ -229,10 +252,9 @@ function renderRecordLines(record: BgNotifyRecord, t: ThemeLike): string[] {
       }
       return [head, ...lines];
     }
-    case "failed":
-      return [head, t.fg("dim", truncLine(`Error: ${record.error ? firstLineSanitized(record.error) : "(unknown)"}`, BODY_MAX_WIDTH))];
-    case "cancelled":
+    case "running":
     default:
+      // v4 B-1: 对话模式轮次完成（旧 idle 折入 running）——仅标题行。
       return [head];
   }
 }
@@ -263,7 +285,7 @@ function extractBgNotifyRecord(details: unknown): BgNotifyRecord | undefined {
   const status = d.status;
   const agent = d.agent;
   if (
-    (status !== "done" && status !== "failed" && status !== "cancelled") ||
+    (status !== "closed" && status !== "running") ||
     typeof agent !== "string"
   ) {
     return undefined;
@@ -275,6 +297,8 @@ function extractBgNotifyRecord(details: unknown): BgNotifyRecord | undefined {
     model: typeof d.model === "string" ? d.model : undefined,
     result: typeof d.result === "string" ? d.result : undefined,
     error: typeof d.error === "string" ? d.error : undefined,
+    closedReason: typeof d.closedReason === "string" ? d.closedReason : undefined,
+    round: typeof d.round === "number" ? d.round : undefined,
     // [MF#1] 提取 patchFile（worktree background 完成通知携带）。
     patchFile: typeof d.patchFile === "string" ? d.patchFile : undefined,
   };