@zhushanwen/pi-subagent-workflow 8.14.7 → 9.0.1

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

@@ -1,183 +0,0 @@
-// 提示词质量回归：subagent tool description 必须是"行为约束器"而非"功能说明书"。
-//
-// agent（LLM）决策时唯一能看到的 tool 元信息就是 description。审查发现旧版
-// description 把篇幅花在功能说明上，缺乏调用信号（何时委派 vs 自己做）、
-// 能力边界（cannot）、反模式密度（高风险要求 ≥4 条）、以及对 auto-injected
-// completion message 的注入防御。
-//
-// 本测试用源码断言（读 .ts 文件文本）锁定这些约束，防止后续重构把约束措辞
-// 删掉或弱化。读源码而非 import，避免 mock 链（subagent-tool.ts 依赖 pi-ai/
-// typebox/pi-tui/ExtensionAPI 等值导入）。
-
-import { readFileSync } from "node:fs";
-import { dirname,join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createRequire } from "node:module";
-
-import { describe, expect, it } from "vitest";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const SUBAGENT_TOOL_SRC = readFileSync(
-  join(__dirname, "../subagent-tool.ts"),
-  "utf-8",
-);
-
-/** 提取 description: `...` 模板字符串的原始内容。 */
-function extractDescription(src: string): string {
-  const m = src.match(/description:\s*`([\s\S]*?)`,/);
-  if (!m) throw new Error("description template literal not found");
-  return m[1];
-}
-
-const DESCRIPTION = extractDescription(SUBAGENT_TOOL_SRC);
-
-describe("subagent tool description — 行为约束器（非功能说明书）", () => {
-  it("词数 ≤ 850（高风险 description 密度上限）", () => {
-    // 高风险 tool 的 description 应聚焦约束而非功能铺陈；过长会稀释信号。
-    // 上限演进：400 → 550（补 start/list/cancel 三 action 完整 JSON 正例）→
-    // 650（M2-B3 新增 message/close 两 action + conversation 对话模式 + 例子）→
-    // 800（递归指导：树形判据 + 自包含 task + 独立验收 + fork 成本警告）→
-    // 850（C2 补 sync 批独立判据禁令句——adversarial-review-fixes §3.4：原 description
-    // 未定义 independent 且未交叉引用依赖链禁令，依赖任务入批缺判据拦截）。
-    // 逼近上限时优先精简正文而非再放宽断言。
-    // 每次 action 扩展必然增加必需描述；正例对弱模型首次用对参数的价值 > 节省 description 预算。
-    const words = DESCRIPTION.trim().split(/\s+/).filter(Boolean).length;
-    expect(words).toBeLessThanOrEqual(850);
-  });
-
-  it("含 'When to delegate' 调用条件段（何时委派 vs 自己做）", () => {
-    // 开篇必须给信号驱动的调用条件，而非纯功能说明。
-    expect(DESCRIPTION).toMatch(/When to delegate/i);
-  });
-
-  it("Anti-patterns 段含 ≥ 4 条 bullet", () => {
-    // 高风险 tool 要求 ≥ 4 条反模式，密度才足以覆盖主要误用路径。
-    const apIdx = DESCRIPTION.indexOf("## Anti-patterns");
-    expect(apIdx).toBeGreaterThan(-1);
-    const afterAp = DESCRIPTION.slice(apIdx);
-    // 截到下一个 ## 段
-    const nextSection = afterAp.indexOf("##", "## Anti-patterns".length);
-    const apSection =
-      nextSection > -1 ? afterAp.slice(0, nextSection) : afterAp;
-    const bullets = apSection.match(/^- .+/gm) || [];
-    expect(bullets.length).toBeGreaterThanOrEqual(4);
-  });
-
-  it("含能力边界段 'You cannot'", () => {
-    // 必须显式声明 tool 做不到的事，阻止 LLM 错误假设。
-    expect(DESCRIPTION).toMatch(/You cannot/);
-    expect(DESCRIPTION.toLowerCase()).toContain("cannot");
-  });
-
-  it("含注入防御：声明 completion message 为不可信数据", () => {
-    // completion message 是 auto-injected（F14 注入面），必须告诉 LLM
-    // 把它当作不可信数据，校验其中的指令后再执行。
-    const lower = DESCRIPTION.toLowerCase();
-    expect(
-      lower.includes("untrusted") || lower.includes("verify"),
-    ).toBe(true);
-  });
-
-  it("保留 nested spawning 段（允许 sub-subagent，仅深度限制）", () => {
-    // 这段防止 LLM 错误拒绝合法的 nested delegation。
-    expect(DESCRIPTION).toMatch(/Nested spawning/);
-    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);
-    expect(DESCRIPTION).toMatch(/sequential/);
-    expect(DESCRIPTION).toMatch(/SAME message/i);
-  });
-
-  it("Examples 段含平铺 JSON 正例（task/slug 在顶层，无 startParam envelope）", () => {
-    // 弱模型信任 schema 结构信号 > 文本信号，原本嵌套 startParam 容器经常被省略。
-    // 现已拍平：task/slug 等 13 字段直接放在顶层。description 必须有完整平铺 JSON 正例，
-    // 让模型能直接照抄。强约束：startParam envelope 必须从 description 中彻底消失。
-    expect(DESCRIPTION).toContain('"action":"start","task"');
-    expect(DESCRIPTION).not.toContain('"startParam"');
-  });
-
-  it("cancel 示例 subagentId 用 sa- 连字符前缀（与 subagent-service.ts 实际生成格式一致）", () => {
-    // subagent-service.ts:600 生成 `sa-${crypto.randomUUID()}`（连字符）。
-    // description 示例必须与实际生成格式一致——弱模型会照抄示例，前缀错（如 sa_ 下划线）
-    // 会导致 subagentId 永远匹配不到真实 record。
-    expect(DESCRIPTION).toContain('"subagentId":"sa-');
-    expect(DESCRIPTION).not.toContain('"sa_');
-  });
-
-  it("Examples 示例 agent 值必须是绝对路径 .md 形态（显式 ref 硬守卫拒绝裸名）", () => {
-    // 显式 agent ref 走硬守卫：getRequiredAgentConfig → loadByPath(ref, true)，
-    // 裸名（normalizeRef 非绝对路径 → null）同步 throw `Invalid agent ref` +
-    // <available_subagents> 恢复指引（explicit-agent-ref-guard.test.ts 锁定拒绝路径）。
-    // 示例若教裸名（历史漂移："agent":"coder"），弱模型照抄即必败调用——浪费一轮
-    // 并系统性教唆反模式。与 subagentId 格式测试同风格：示例必须与实际契约一致。
-    // ① 零裸名：任何 "agent":"<非/>" 形态都禁止
-    expect(DESCRIPTION).not.toMatch(/"agent":"(?!\/)[^"]*"/);
-    // ② 正例在位且为绝对路径 .md 形态（<available_subagents> 注入的 <location> 形态）
-    expect(DESCRIPTION).toMatch(/"agent":"\/[^"]*\.md"/);
-  });
-
-  it("agent 字段 description 不写死枚举，指向 <available_subagents>（通用化防漂移）", () => {
-    // 原实现把 9 个内置 agent 名写死在 schema field description（防漏），
-    // 但枚举与包内 agents/*.md 存在漂移风险（新增/删除 agent 要手改两处）。
-    // 现改为指向每 turn 动态注入的 <available_subagents> 列表——防漏职责由注入段承担，
-    // 工具描述只保留通用指引（2026-08 通用化重构）。
-    expect(SUBAGENT_TOOL_SRC).toContain("available_subagents");
-    // 通用化约束：不写死任何具体 agent 名（名字随 agents/*.md 动态变化）
-    expect(SUBAGENT_TOOL_SRC).not.toMatch(/orchestrator|code-reviewer|context-builder|worker/);
-  });
-
-  it("Anti-patterns 段明确 list/cancel 仍 nested（防过度泛化 flatten）", () => {
-    // PR 只拍平 start，listParam/cancelParam 仍 nested。description 必须明确这一不对称性，
-    // 否则弱模型学了「subagent tool 现在平铺」会过度泛化发 {"action":"list","includeFinished":true}。
-    const apIdx = DESCRIPTION.indexOf("## Anti-patterns");
-    expect(apIdx).toBeGreaterThan(-1);
-    const afterAp = DESCRIPTION.slice(apIdx);
-    const nextSection = afterAp.indexOf("##", "## Anti-patterns".length);
-    const apSection = nextSection > -1 ? afterAp.slice(0, nextSection) : afterAp;
-    expect(apSection).toMatch(/list.*nested.*listParam|listParam.*nested/i);
-  });
-});
-
-describe("subagent tool runtime handler — 错误文案含纠正正例", () => {
-  // 读源码文本断言 startHandler throw 含 Correct 正例，
-  // 让弱模型撞错后第二次能直接照抄正确形态。
-  // 拍平后：startParam envelope 删除，平铺 task/slug 是合法形态；
-  // 平铺检测 guard（hasFlattenedStartFields）已删除，源码不应再含此表达式。
-  it("startHandler throw 含 Correct 纠正正例（平铺形态）", () => {
-    // [D6②] startHandler 内核（含 Correct 文案）已下沉 core subagent-actions-core，
-    // 断言目标跟随文案权威源。锚点用 ./workflows/* 子入口（exports 映射包根真实目录，
-    // 随源码走不依赖 dist 构建——relay-env 锚在 require 条件下落 dist/，CI 不构建
-    // workspace 包时 resolve 直接 MODULE_NOT_FOUND）。
-    const coreRoot = join(
-      dirname(
-        createRequire(import.meta.url).resolve("@zhushanwen/subagent-core/workflows/README.md"),
-      ),
-      "..",
-    );
-    const actionsSrc = readFileSync(
-      join(coreRoot, "src/execution/assembly/subagent-actions-core.ts"),
-      "utf-8",
-    );
-    // 四处 throw（input 缺失 / task 空白 / slug 空白 / slug 超长）都应含 Correct 正例。
-    // 用 occurrences 计数——至少 3 处。
-    const occurrences = (actionsSrc.match(/Correct: \{"action":"start"/g) ?? []).length;
-    expect(occurrences).toBeGreaterThanOrEqual(3);
-  });
-
-  it("平铺检测 guard（hasFlattenedStartFields）已从 subagent-tool.ts 删除", () => {
-    expect(SUBAGENT_TOOL_SRC).not.toContain('params.action === "start" && !params.startParam');
-    expect(SUBAGENT_TOOL_SRC).not.toContain("hasFlattenedStartFields");
-  });
-});

package/src/interface/__tests__/tool-workflow-run-builtin-name.test.ts

@@ -1,219 +0,0 @@
-/**
- * C5③：actionRun 放开内置 workflow 名（convergence D-4 pi 半边）。
- *
- * 解析序：registry.get(name)（内置/已保存 workflow 名，按 tmp>project>user>npm
- * 优先级合并）→ 未命中 registry.getPath(name)（绝对路径 + ~/ 展开）→ 两者都 miss
- * 走原 not_found 报错（文案不变）。严格超集：现有路径用法零变化。
- *
- * 三视角：
- * - 使用者（黑盒）：run {"action":"run","name":"chain"} 直接可跑（内置名新能力）；
- *   传路径仍可跑（现行为）；两者都 miss 的报错与改造前逐字一致。
- * - 构建者（白盒）：解析序 get→getPath、get 未命中才穿透到 getPath。
- * - 观察者（真 registry）：WorkflowScriptRegistryImpl + fixture 目录经真实
- *   discoverWorkflows 按名命中（生产 lookup 链）。
- *
- * mock 策略：lifecycle 深路径 stub（runWorkflow/abortRun 为 vi.fn——不起真 Worker，
- * 只验证 run 启动面的脚本解析与 spec 组装）。框架：vitest（禁 node:test）。
- */
-import { mkdtempSync, readdirSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-/** 桩化 lifecycle——runWorkflow/abortRun 为 vi.fn，不起真 Worker（只测解析面）。 */
-vi.mock("@zhushanwen/subagent-core/orchestration/lifecycle.ts", () => ({
-  runWorkflow: vi.fn(),
-  abortRun: vi.fn(),
-}));
-
-// 被 mock 的模块——import 路径与被测源文件（tool-workflow.ts 深路径 import）一致
-import { runWorkflow } from "@zhushanwen/subagent-core/orchestration/lifecycle.ts";
-import { actionRun } from "../tool-workflow.ts";
-import { WorkflowScriptRegistryImpl } from "@zhushanwen/subagent-core";
-
-// ── fixture：可用 workflow 脚本（@pi-meta 新格式，无参数声明） ──
-
-const CHAIN_META = `/* @pi-meta
-name: chain
-description: 内置名测试用三步链
-phases: [a, b]
-*/
-const agent = require("./agent");
-agent("w", { task: $ARGS.task });
-`;
-
-/** fake registry 的最小 WorkflowScript stub。 */
-function makeScript(name: string, path: string, parameters?: object) {
-  return {
-    name,
-    path,
-    available: true,
-    sourceCode: `// ${name}`,
-    meta: { description: `${name} workflow`, parameters },
-    toExecutable: () => `// ${name}`,
-  };
-}
-
-/** 最小 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,
-  };
-}
-
-beforeEach(() => {
-  vi.mocked(runWorkflow).mockReset();
-  vi.mocked(runWorkflow).mockResolvedValue("run-id-1");
-});
-
-afterEach(() => {
-  vi.restoreAllMocks();
-});
-
-describe("C5③ run 内置名（fake registry）", () => {
-  it("run 传内置名 → registry.get 命中即启动（runWorkflow 收到该脚本，getPath 不被调用）", async () => {
-    const chain = makeScript("chain", "/builtin/workflows/chain.js");
-    const registry = {
-      get: vi.fn().mockResolvedValue(chain),
-      getPath: vi.fn().mockResolvedValue(undefined),
-      loadAll: vi.fn().mockResolvedValue([chain]),
-    };
-    const result = await actionRun(
-      { action: "run", name: "chain" } as never,
-      makeDeps(registry) as never,
-      undefined,
-    );
-
-    expect(registry.get).toHaveBeenCalledWith("chain");
-    expect(registry.getPath).not.toHaveBeenCalled();
-    expect(vi.mocked(runWorkflow)).toHaveBeenCalledTimes(1);
-    // spec 组装：scriptName/scriptPath 来自按名命中的脚本
-    const spec = vi.mocked(runWorkflow).mock.calls[0][0] as Record<string, unknown>;
-    expect(spec.scriptName).toBe("chain");
-    expect(spec.scriptPath).toBe("/builtin/workflows/chain.js");
-    expect(result.content[0]?.text).toContain("Started workflow 'chain'");
-    expect(result.details).toMatchObject({ action: "run", status: "running", name: "chain" });
-  });
-
-  it("严格超集：get 未命中的路径名 → 穿透 getPath（现有路径用法零变化）", async () => {
-    const byPath = makeScript("demo", "/abs/demo.js");
-    const registry = {
-      get: vi.fn().mockResolvedValue(undefined),
-      getPath: vi.fn().mockResolvedValue(byPath),
-      loadAll: vi.fn().mockResolvedValue([byPath]),
-    };
-    await actionRun(
-      { action: "run", name: "/abs/demo.js" } as never,
-      makeDeps(registry) as never,
-      undefined,
-    );
-
-    expect(registry.get).toHaveBeenCalledWith("/abs/demo.js");
-    expect(registry.getPath).toHaveBeenCalledWith("/abs/demo.js");
-    expect(vi.mocked(runWorkflow)).toHaveBeenCalledTimes(1);
-    const spec = vi.mocked(runWorkflow).mock.calls[0][0] as Record<string, unknown>;
-    expect(spec.scriptName).toBe("demo");
-  });
-
-  it("get 命中 available:false 的 stub → 不启动，走 not_found 报错（W4c 口径不回退）", async () => {
-    const ghost = { ...makeScript("ghost", "/builtin/ghost.js"), available: false };
-    const registry = {
-      get: vi.fn().mockResolvedValue(ghost),
-      getPath: vi.fn().mockResolvedValue(undefined),
-      loadAll: vi.fn().mockResolvedValue([]),
-    };
-    await expect(
-      actionRun(
-        { action: "run", name: "ghost" } as never,
-        makeDeps(registry) as never,
-        undefined,
-      ),
-    ).rejects.toThrow(/Workflow 'ghost' not found\./);
-    expect(vi.mocked(runWorkflow)).not.toHaveBeenCalled();
-  });
-
-  it("两者都 miss → 报错含建议清单且逐条附绝对路径 location（按名失败后的自救指引）", async () => {
-    const registry = {
-      get: vi.fn().mockResolvedValue(undefined),
-      getPath: vi.fn().mockResolvedValue(undefined),
-      loadAll: vi.fn().mockResolvedValue([makeScript("chain", "/builtin/workflows/chain.js")]),
-    };
-    const err = await actionRun(
-      { action: "run", name: "no-such" } as never,
-      makeDeps(registry) as never,
-      undefined,
-    ).catch((e: unknown) => e as Error);
-    // 逐条 location：模型按清单里的名字重试注定再 throw（8.6.0 getPath-only 时代
-    // 实测失败形态）——摘要必须直接给出可用的绝对路径，失败一次即自救。
-    expect(err.message).toContain(
-      "Workflow 'no-such' not found. Available (name — use the absolute location path as 'name' when the bare name is rejected):",
-    );
-    expect(err.message).toContain("  - chain: chain workflow");
-    expect(err.message).toContain("    location: /builtin/workflows/chain.js");
-  });
-});
-
-describe("C5③ run 内置名（真 registry：WorkflowScriptRegistryImpl + 真实发现链）", () => {
-  let fixtureDir: string;
-
-  beforeEach(() => {
-    fixtureDir = mkdtempSync(join(tmpdir(), "c5-run-builtin-"));
-    // WorkflowScanConfig 布局：projectDir = <fixture>/ws/.pi/workflows（反推 workspaceRoot）
-    const projectDir = join(fixtureDir, "ws", ".pi", "workflows");
-    mkdirSync(projectDir, { recursive: true });
-    writeFileSync(join(projectDir, "chain.js"), CHAIN_META, "utf-8");
-  });
-
-  afterEach(() => {
-    rmSync(fixtureDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
-  });
-
-  it("get('chain') 经真实 discoverWorkflows 命中 fixture 脚本 → actionRun 按名启动成功", async () => {
-    const registry = new WorkflowScriptRegistryImpl({
-      projectDir: join(fixtureDir, "ws", ".pi", "workflows"),
-      userDir: join(fixtureDir, "user", "workflows"),
-      tmpDir: join(fixtureDir, "ws", ".pi", "workflows", ".tmp"),
-      npmDirs: [],
-    });
-    // 前置自检：fixture 布局可被扫描（隔离 config 下 hostRoots 为空、仅 project 根命中）
-    const all = await registry.loadAll();
-    expect(all.filter((w) => w.available).map((w) => w.name)).toContain("chain");
-
-    const result = await actionRun(
-      { action: "run", name: "chain" } as never,
-      makeDeps(registry as unknown as Record<string, unknown>) as never,
-      undefined,
-    );
-
-    expect(vi.mocked(runWorkflow)).toHaveBeenCalledTimes(1);
-    const spec = vi.mocked(runWorkflow).mock.calls[0][0] as Record<string, unknown>;
-    expect(spec.scriptName).toBe("chain");
-    expect(String(spec.scriptPath)).toContain("chain.js");
-    expect(result.content[0]?.text).toContain("Started workflow 'chain'");
-  });
-
-  it("真 registry 下未知名（无路径形态）→ not_found（含 fixture 内可用清单）", async () => {
-    const registry = new WorkflowScriptRegistryImpl({
-      projectDir: join(fixtureDir, "ws", ".pi", "workflows"),
-      userDir: join(fixtureDir, "user", "workflows"),
-      tmpDir: join(fixtureDir, "ws", ".pi", "workflows", ".tmp"),
-      npmDirs: [],
-    });
-    await expect(
-      actionRun(
-        { action: "run", name: "not-a-workflow" } as never,
-        makeDeps(registry as unknown as Record<string, unknown>) as never,
-        undefined,
-      ),
-    ).rejects.toThrow(/Workflow 'not-a-workflow' not found\./);
-    expect(vi.mocked(runWorkflow)).not.toHaveBeenCalled();
-  });
-
-  it("fixture 卫生断言：fixture 目录无其他 .js 泄漏（避免 discoverWorkflows 误扫）", () => {
-    const projectDir = join(fixtureDir, "ws", ".pi", "workflows");
-    expect(readdirSync(projectDir).filter((f) => f.endsWith(".js"))).toEqual(["chain.js"]);
-  });
-});

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

@@ -1,251 +0,0 @@
-/**
- * actionGenerate 行为测试（m0 wave / TC1-TC7 + [P-generate-roundtrip]；C5② 改接 core 管线）
- *
- * C5② 起五道闸校验 + tmp 写盘在 core generateWorkflowScript（barrel import）——本测试
- * 验证宿主契约层（结构化结果 → execute-throw 转换、signal aborted、成功文案）+ 经
- * 真实 core 管线的校验行为回归。
- *
- * mock node:fs（mkdirSync/writeFileSync）避免真实落盘 .pi/workflows/.tmp/（builtin
- * 模块 mock 对 core 管线内的写盘同样生效）。save/delete 走 barrel mock（importActual
- * 展开覆写，其余 barrel 面（含 generateWorkflowScript）保持真实）。
- *
- * 框架：vitest（禁 node:test）。
- */
-import { mkdirSync, writeFileSync } from "node:fs";
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-import { actionGenerate, type ScriptParams, type TextContent, registerWorkflowScriptTool } from "../tool-workflow-script.ts";
-import { deleteWorkflow, saveWorkflow } from "@zhushanwen/subagent-core";
-
-// node:fs 只覆写两个写盘函数、其余保持真实——C5② 后被测链经 barrel 拉起完整 core
-// 依赖图（importActual），core 模块对 existsSync/statSync 等的消费不能被 2 函数工厂截断
-vi.mock("node:fs", async (importOriginal) => ({
-  ...(await importOriginal<typeof import("node:fs")>()),
-  mkdirSync: vi.fn(),
-  writeFileSync: vi.fn(),
-}));
-
-// C5②：被测模块经 barrel 消费 save/delete/generateWorkflowScript——mock 挂 barrel，
-// importActual 展开保持 generateWorkflowScript 真实（校验管线是被测回归面）
-vi.mock("@zhushanwen/subagent-core", async (importOriginal) => ({
-  ...(await importOriginal<typeof import("@zhushanwen/subagent-core")>()),
-  saveWorkflow: vi.fn(),
-  deleteWorkflow: vi.fn(),
-}));
-
-const mockedWriteFileSync = vi.mocked(writeFileSync);
-const mockedMkdirSync = vi.mocked(mkdirSync);
-
-function gen(script: string, name = "test-wf"): ScriptParams {
-  return { action: "generate", name, script } as ScriptParams;
-}
-
-/** TextContent.text 在 content[0].text。 */
-function textOf(r: TextContent): string {
-  return r.content[0]?.text ?? "";
-}
-
-const PI_META_VALID = `/* @pi-meta
-name: test-wf
-description: 合法新格式
-phases: [a, b]
-parameters:
-  type: object
-  properties:
-    task: { type: string }
-  required: [task]
-*/
-const agent = require("./agent");
-agent("worker", { task: $ARGS.task });
-`;
-
-const PI_META_MALFORMED = `/* @pi-meta
-name: test-wf
-description: bad
-  broken: indent
-phases: [a]
-*/
-const agent = require("./agent");
-agent("w");
-`;
-
-const PI_META_REGEX_SINGLE_BS = `/* @pi-meta
-name: test-wf
-description: regex
-phases: [A]
-parameters:
-  type: object
-  patternProperties:
-    "^batch\\d+$": { type: string }
-*/
-const agent = require("./agent");
-agent("w");
-`;
-
-const LEGACY_CONST_META = `const meta = {
-  name: test-wf,
-  description: legacy,
-  phases: ["a"]
-};
-const agent = require("./agent");
-agent("w");
-`;
-
-const NO_META = `const agent = require("./agent");
-agent("w");
-`;
-
-const ESM_IMPORT = `/* @pi-meta
-name: x
-description: d
-phases: [a]
-*/
-import { foo } from "bar";
-const agent = require("./agent");
-agent("w");
-`;
-
-const NO_AGENT = `/* @pi-meta
-name: x
-description: d
-phases: [a]
-*/
-const x = 1;
-`;
-
-describe("actionGenerate (m0: @pi-meta 认可 + round-trip)", () => {
-  beforeEach(() => {
-    mockedWriteFileSync.mockClear();
-    mockedMkdirSync.mockClear();
-  });
-  afterEach(() => {
-    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();
-    expect(textOf(r)).toMatch(/ready|generated|test-wf/i);
-    expect(mockedWriteFileSync).toHaveBeenCalledTimes(1);
-  });
-
-  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();
-  });
-
-  it("TC3: legacy const meta（过渡期）→ ready + writeFileSync 被调用", () => {
-    const r = actionGenerate(gen(LEGACY_CONST_META), undefined);
-    expect(r.isError).toBeFalsy();
-    expect(mockedWriteFileSync).toHaveBeenCalledTimes(1);
-  });
-
-  it("TC4: 无 meta → throw 提及 @pi-meta 新格式", () => {
-    expect(() => actionGenerate(gen(NO_META), undefined)).toThrow(/meta declaration/i);
-    expect(mockedWriteFileSync).not.toHaveBeenCalled();
-  });
-
-  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 → throw（保留现有行为）", () => {
-    expect(() => actionGenerate(gen(ESM_IMPORT), undefined)).toThrow(/ESM|import/i);
-  });
-
-  it("TC7: 无 agent() → throw（保留现有行为）", () => {
-    expect(() => actionGenerate(gen(NO_AGENT), undefined)).toThrow(/agent\(\)/i);
-  });
-
-  it("TC8: signal aborted → throw（保留现有行为）", () => {
-    const controller = new AbortController();
-    controller.abort();
-    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 });
-  });
-});