@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/orchestration/__tests__/script-generate.test.ts

@@ -0,0 +1,314 @@
+// src/orchestration/__tests__/script-generate.test.ts
+//
+// C4-core-script-pipeline（convergence W4）单元测试：generate 校验管线下沉的
+// 行为锁定。覆盖 §4.2 W4 门全部条目：
+// - 五道闸逐字文案（期望串按 pi 现版 actionGenerate 源码逻辑手工构造——
+//   pi 侧行为不变是 CA2 前提，文案改动必须同步两处）；
+// - round-trip 失败报错含 YAML 诊断与 line/col（parseResourceMetaDetailed
+//   真实调用不 mock，与 pi 测试 TC2/TC5 同原则）；
+// - 合法样本落 tmp：目录参数注入生效（真实落盘断言，非 mock fs）；
+// - 缺省目录 = pi 布局（相对 cwd resolve，pi 现行为不变）；
+// - barrel 逐名探针（红线 9）。
+// 设计权威源：docs/design/subagent-core-convergence.md §3.2 D-6。
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { describe, expect, it, vi } from "vitest";
+
+import type {
+  GenerateWorkflowScriptOptions,
+  GenerateWorkflowScriptResult,
+  WorkflowDirOptions,
+} from "../../index.ts";
+import * as subagentCore from "../../index.ts";
+import { parseResourceMetaDetailed } from "../../shared/meta-parser.ts";
+import { generateWorkflowScript } from "../script-generate.ts";
+
+// ============================================================
+// 样本（构造逻辑对齐 pi 侧 tool-workflow-script-generate.test.ts）
+// ============================================================
+
+const PI_META_VALID = `/* @pi-meta
+name: test-wf
+description: valid new format
+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: "legacy-wf",
+  description: "legacy format",
+  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 ESM_EXPORT_NON_META = `/* @pi-meta
+name: x
+description: d
+phases: [a]
+*/
+const agent = require("./agent");
+export const foo = 1;
+agent("w");
+`;
+
+const NO_AGENT = `/* @pi-meta
+name: x
+description: d
+phases: [a]
+*/
+const x = 1;
+`;
+
+const SYNTAX_ERROR = `/* @pi-meta
+name: x
+description: d
+phases: [a]
+*/
+const agent = require("./agent");
+agent("w";
+`;
+
+// ============================================================
+// 期望串（pi 现版 actionGenerate 文案逐字手工构造）
+// ============================================================
+
+/**
+ * round-trip 报错文案模板——pi 版 tool-workflow-script.ts actionGenerate
+ * 的模板逐字复制（含源码字面 `(\\d not \d)` 的历史形态：模板字符串里 `\\d`
+ * 渲染 `\d`、`\d` 渲染 `d`；两处字符级一致即运行时逐字一致）。
+ */
+function expectedRoundtripError(detailed: {
+  error: string;
+  linePos?: { line: number; col: number };
+}): string {
+  const loc = "linePos" in detailed && detailed.linePos
+    ? ` (line ${detailed.linePos.line}, col ${detailed.linePos.col})`
+    : "";
+  return `Generated /* @pi-meta */ YAML cannot be parsed${loc}: ${detailed.error}. Common causes: YAML indent errors, patternProperties regex must use double backslash (\\d not \d), or a stray star-slash inside the YAML body. Fix the meta block and retry.`;
+}
+
+/** 非.ok 分支的错误文案（窄化辅助：ok 分支直接 fail）。 */
+function errorOf(r: GenerateWorkflowScriptResult): string {
+  if (r.ok) throw new Error("expected failure result, got success");
+  return r.error;
+}
+
+function makeTmpRoot(): string {
+  return mkdtempSync(join(tmpdir(), "subagent-core-gen-"));
+}
+
+// ============================================================
+// 五道闸（文案逐字对齐 pi 现版）
+// ============================================================
+
+describe("generateWorkflowScript 校验闸（文案逐字对齐 pi 现版）", () => {
+  it("缺 name/script → 拒（防御性文案逐字）", () => {
+    expect(errorOf(generateWorkflowScript("", "x"))).toBe(
+      "generate requires 'name' and 'script' parameters",
+    );
+    expect(errorOf(generateWorkflowScript("x", ""))).toBe(
+      "generate requires 'name' and 'script' parameters",
+    );
+  });
+
+  it("ESM import → 拒（文案逐字）", () => {
+    const tmpRoot = makeTmpRoot();
+    try {
+      const r = generateWorkflowScript("esm-wf", ESM_IMPORT, { tmpDir: tmpRoot });
+      expect(errorOf(r)).toBe(
+        "Script uses ESM 'import' syntax. Workflow scripts run in a CJS Worker — use require() instead.",
+      );
+      expect(existsSync(join(tmpRoot, "esm-wf.js"))).toBe(false);
+    } finally {
+      rmSync(tmpRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("ESM export（非 meta）→ 拒（文案逐字）", () => {
+    const r = generateWorkflowScript("exp-wf", ESM_EXPORT_NON_META);
+    expect(errorOf(r)).toBe(
+      "Script uses ESM 'export' (non-meta). Use 'const meta = {...}' at top level instead.",
+    );
+  });
+
+  it("无 meta 声明 → 拒（文案逐字）", () => {
+    const r = generateWorkflowScript("nometa-wf", NO_META);
+    expect(errorOf(r)).toBe(
+      "Script must contain a meta declaration: a /* @pi-meta */ YAML block comment (preferred) or legacy const meta = { ... }. The block has the form: a block comment starting with /* @pi-meta followed by YAML (name/description/phases/parameters?/usage?), closed by */ on its own line.",
+    );
+  });
+
+  it("无 agent() 调用 → 拒（文案逐字）", () => {
+    const r = generateWorkflowScript("noagent-wf", NO_AGENT);
+    expect(errorOf(r)).toBe(
+      "Script does not contain any agent() calls. A workflow must call agent() at least once.",
+    );
+  });
+
+  it("语法错误 → 拒（前缀逐字 + V8 诊断非空）", () => {
+    const r = generateWorkflowScript("synerr-wf", SYNTAX_ERROR);
+    const err = errorOf(r);
+    expect(err.startsWith("Syntax error in script: ")).toBe(true);
+    expect(err.length > "Syntax error in script: ".length).toBe(true);
+  });
+
+  it("malformed @pi-meta YAML → round-trip 拒，报错含 line/col + 未落盘", () => {
+    const tmpRoot = makeTmpRoot();
+    try {
+      const r = generateWorkflowScript("bad-wf", PI_META_MALFORMED, { tmpDir: tmpRoot });
+      const err = errorOf(r);
+      // 行列信息保留（ERR4：LLM 自纠正依赖）
+      expect(err).toMatch(/ \(line \d+, col \d+\)/);
+      // 期望串 = 同一 parser 实测值 + pi 源码模板手工展开 → 逐字一致
+      const detailed = parseResourceMetaDetailed(PI_META_MALFORMED, "workflow");
+      expect(detailed.ok).toBe(false);
+      if (!detailed.ok) {
+        expect(detailed.linePos).toBeDefined();
+        expect(err).toBe(expectedRoundtripError(detailed));
+      }
+      expect(existsSync(join(tmpRoot, "bad-wf.js"))).toBe(false);
+    } finally {
+      rmSync(tmpRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("patternProperties 单反斜杠正则 → round-trip 拒（LLM 高频错，含行列）", () => {
+    const r = generateWorkflowScript("regex-wf", PI_META_REGEX_SINGLE_BS);
+    const err = errorOf(r);
+    expect(err).toMatch(/ \(line \d+, col \d+\)/);
+    const detailed = parseResourceMetaDetailed(PI_META_REGEX_SINGLE_BS, "workflow");
+    expect(detailed.ok).toBe(false);
+    if (!detailed.ok) {
+      expect(err).toBe(expectedRoundtripError(detailed));
+    }
+  });
+});
+
+// ============================================================
+// 合法样本落 tmp（目录参数注入生效）
+// ============================================================
+
+describe("generateWorkflowScript 合法样本落 tmp", () => {
+  it("注入 tmpDir：真实落盘指定目录，内容逐字节一致", () => {
+    const tmpRoot = makeTmpRoot();
+    try {
+      const r = generateWorkflowScript("my-wf", PI_META_VALID, { tmpDir: tmpRoot });
+      expect(r.ok).toBe(true);
+      if (!r.ok) throw new Error(r.error);
+      expect(r.path).toBe(resolve(tmpRoot, "my-wf.js"));
+      expect(existsSync(r.path)).toBe(true);
+      expect(readFileSync(r.path, "utf-8")).toBe(PI_META_VALID);
+    } finally {
+      rmSync(tmpRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("legacy const meta（过渡期）→ 过闸落盘（无 @pi-meta 跳过 round-trip）", () => {
+    const tmpRoot = makeTmpRoot();
+    try {
+      const r = generateWorkflowScript("legacy-wf", LEGACY_CONST_META, { tmpDir: tmpRoot });
+      expect(r.ok).toBe(true);
+      if (!r.ok) throw new Error(r.error);
+      expect(existsSync(r.path)).toBe(true);
+    } finally {
+      rmSync(tmpRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("缺省 tmpDir = pi 布局 <cwd>/.pi/workflows/.tmp（pi 现行为不变）", () => {
+    const fakeCwd = mkdtempSync(join(tmpdir(), "subagent-core-cwd-"));
+    const cwdSpy = vi.spyOn(process, "cwd").mockReturnValue(fakeCwd);
+    try {
+      const r = generateWorkflowScript("def-wf", PI_META_VALID);
+      expect(r.ok).toBe(true);
+      if (!r.ok) throw new Error(r.error);
+      expect(r.path).toBe(join(fakeCwd, ".pi", "workflows", ".tmp", "def-wf.js"));
+      expect(existsSync(r.path)).toBe(true);
+    } finally {
+      cwdSpy.mockRestore();
+      rmSync(fakeCwd, { recursive: true, force: true });
+    }
+  });
+});
+
+// ============================================================
+// barrel 逐名探针（红线 9：新增导出必须进 barrel，逐名列出）
+// ============================================================
+
+describe("barrel exports probe", () => {
+  it("值导出逐名可达（typeof function）", () => {
+    const valueExports = [
+      "generateWorkflowScript",
+      "saveWorkflow",
+      "deleteWorkflow",
+    ] as const;
+    const barrel = subagentCore as Record<string, unknown>;
+    for (const name of valueExports) {
+      expect(typeof barrel[name], `barrel 缺值导出: ${name}`).toBe("function");
+    }
+  });
+
+  it("缺省目录常量经 barrel 可达（值 = pi 布局）", () => {
+    const barrel = subagentCore as Record<string, unknown>;
+    expect(barrel["DEFAULT_WORKFLOW_TMP_DIR"]).toBe(".pi/workflows/.tmp");
+    expect(barrel["DEFAULT_WORKFLOW_SAVED_DIR"]).toBe(".pi/workflows");
+  });
+
+  it("类型导出经 barrel 可引用（typecheck 即探针）", () => {
+    const genOpts: GenerateWorkflowScriptOptions = { tmpDir: "/tmp/x" };
+    const dirOpts: WorkflowDirOptions = { tmpDir: "/tmp/x", savedDir: "/tmp/y" };
+    let result: GenerateWorkflowScriptResult = { ok: true, path: "/p" };
+    result = { ok: false, error: "e" };
+    expect(genOpts.tmpDir).toBe("/tmp/x");
+    expect(dirOpts.savedDir).toBe("/tmp/y");
+    expect(result.ok).toBe(false);
+  });
+});

package/src/orchestration/__tests__/script-lint.test.ts

@@ -16,6 +16,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { lintAgentMeta, lintScript } from "../script-lint.ts";
+import type { LintFinding } from "../script-lint.ts";
 import { parseResourceMeta } from "../../shared/meta-parser.ts";
 
 const WORKFLOWS_DIR = join(__dirname, "../../../workflows");
@@ -491,6 +492,22 @@ describe("MF-4 回归：非字面量实参 agent(callVar) / agent(expr()) 跳过
     expect(descWarnings).toHaveLength(1);
     expect(descWarnings[0].line).toBe(2);
   });
+
+  it("`agent(` 换行 `{` 的多行字面量调用保留追踪（argTail 为空分支）", () => {
+    // agent( 与 { 分离两行：argTail 为空不跳过，范围跨三行闭合——缺 description
+    // 报 1 条且行号落在调用起点（锚定 matchAgentCallHead 的空 argTail 保留路径）
+    const src = [
+      `await agent(`,
+      `  { prompt: "x" }`,
+      `);`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    const descWarnings = warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message));
+    expect(descWarnings).toHaveLength(1);
+    expect(descWarnings[0].line).toBe(1);
+  });
 });
 
 // ── MF-4 回归：checkAgentDescription 的两个跳过分支 ────────────────

package/src/orchestration/__tests__/test-mocks.ts

@@ -68,6 +68,7 @@ export function mkCtx(
     ui: mkUi(),
     // pi 在 xyz-agent 下以 rpc 子进程模式运行；rpc 模式 hasUI 为 true（SDK 契约注释）
     mode: "rpc",
+    scopedModels: [],
     hasUI: true,
     cwd: "/tmp",
     sessionManager: {
@@ -168,6 +169,7 @@ export function mkPi(
     registerTool: vi.fn(),
     registerCommand: vi.fn(),
     registerShortcut: vi.fn(),
+    registerMarkdownTransformer: vi.fn(),
     registerFlag: vi.fn(),
     getFlag: vi.fn(() => undefined),
     registerMessageRenderer: vi.fn(),

package/src/orchestration/__tests__/worker-exit-without-result.test.ts

@@ -18,7 +18,7 @@
  * `void handlers.onXxx(...)` 无人接 → unhandledRejection + pending:unregister / onRunDone
  * 不执行（pending 通知幽灵注销）。修复后 save 失败仅 logger.error，状态机继续推进。
  *
- * mock 构建参考 error-recovery-handlers.test.ts（plain-object WorkflowRun mock）。
+ * mock 构建参考 worker-message-pump-handlers.test.ts（plain-object WorkflowRun mock）。
  */
 import { describe, expect, it, vi } from "vitest";
 
@@ -27,16 +27,17 @@ import {
   handleWorkerMessage,
   handleScriptError,
   handleWorkerError,
-} from "../error-recovery.ts";
+} from "../worker-message-pump.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
+import type { DoneReason, RunStatus } from "../models/types.ts";
 import type { WorkflowRun } from "../models/workflow-run.ts";
 import type { WorkerHandle } from "../worker-handle.ts";
 
-/** [F1] 归因文案——与 error-recovery.ts 常量一致（不直接 import 常量以锚定对外文案）。 */
+/** [F1] 归因文案——与 worker-message-pump.ts 常量一致（不直接 import 常量以锚定对外文案）。 */
 const EXITED_WITHOUT_RESULT_MSG =
   "worker exited before delivering a result (return value may not be structured-cloneable)";
 
-// ── helpers（对齐 error-recovery-handlers.test.ts）─────────────────
+// ── helpers（对齐 worker-message-pump-handlers.test.ts）─────────────────
 
 interface RunMockOpts {
   workerErrorCount?: number;
@@ -70,11 +71,11 @@ function makeRunningRun(opts: RunMockOpts = {}): WorkflowRun {
       worker: { postMessage: vi.fn() },
       receivedTerminalMessage: opts.receivedTerminalMessage,
     },
-    transition(target: string, reason?: string): void {
+    transition(this: WorkflowRun, target: RunStatus, reason?: DoneReason): void {
       this.state.status = target;
       if (target === "done") this.state.reason = reason;
     },
-    replaceRuntime(rt: unknown): void {
+    replaceRuntime(this: WorkflowRun, rt: NonNullable<WorkflowRun["runtime"]>): void {
       this.runtime = rt;
     },
   } as unknown as WorkflowRun;

package/src/orchestration/__tests__/worker-message-pump-finalize-run.test.ts

@@ -0,0 +1,229 @@
+/**
+ * finalizeRun — D5-② 终态 coda 单写点测试。
+ *
+ * 「transition → save → pending:unregister → onRunDone」四步终态序列的唯一
+ * 定义点（worker-message-pump.ts）。收敛前 8 处逐字复制（本文件 6 处 + lifecycle
+ * 2 处）——本文件锁定：
+ * 1. 四步恰好一次且有序（transition 先于 save 先于 unregister 先于 onRunDone）
+ * 2. notifyDone:false 真差异承载（terminateRunningRuns 不发 onRunDone、unregister 仍发）
+ * 3. transition 让位（并发终态化）→ 后三步全不执行
+ * 4. save best-effort（SW-DATA-3）→ unregister/onRunDone 不被落盘失败短路
+ *
+ * 其余终态路径的「恰好一次四步」行为断言（save×1 + unregister + onRunDone×1）
+ * 已由既有测试覆盖：handleWorkerError/handleScriptError/handleWorkerExit 超限
+ * （worker-message-pump-handlers / worker-exit-without-result）、time_limited
+ * （worker-message-pump-handlers race-F3 describe）、abortRun（lifecycle.test）、
+ * handleReturn（worker-exit-without-result SW-DATA-3 describe）。本文件补齐
+ * budget_limited 路径（dispatchAgentCall coda）与 notifyDone:false 路径。
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  finalizeRun,
+  handleWorkerMessage,
+} from "../worker-message-pump.ts";
+import { Budget } from "../models/budget.ts";
+import { RunRuntime } from "../models/run-runtime.ts";
+import { Trace } from "../models/trace.ts";
+import type { AgentResult } from "../models/types.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
+import type { WorkerHandle } from "../worker-handle.ts";
+
+// ── helpers ──────────────────────────────────────────────────
+
+/** 构造真实 WorkflowRun（真实状态机 transition）+ 初始 runtime。 */
+function makeRealRun(runId: string): WorkflowRun {
+  const run = new WorkflowRun(
+    runId,
+    {
+      scriptName: "test-wf",
+      scriptSource: "agent('hi')",
+      args: {},
+      scriptPath: "/tmp/test-wf.js",
+    },
+    {
+      status: "running",
+      budget: new Budget(),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+    },
+    { startedAt: new Date().toISOString() },
+  );
+  const worker = {
+    postMessage: vi.fn(),
+    terminate: vi.fn(async () => {}),
+  } as unknown as WorkerHandle;
+  run.assignRuntime(new RunRuntime(worker, new AbortController()));
+  return run;
+}
+
+/** deps mock：副作用打点进单一顺序数组（断言四步顺序）。 */
+function makeTracingDeps(): LifecycleDeps & {
+  order: string[];
+  store: { save: ReturnType<typeof vi.fn> };
+} {
+  const order: string[] = [];
+  return {
+    order,
+    store: {
+      save: vi.fn(async () => {
+        order.push("save");
+      }),
+    },
+    workerHost: { start: vi.fn(() => ({ postMessage: vi.fn() })) },
+    runner: { run: vi.fn(async () => ({}) as AgentResult) },
+    runs: new Map(),
+    eventBus: {
+      emit: vi.fn((event: string) => {
+        order.push(`emit:${event}`);
+      }),
+    },
+    onRunDone: vi.fn(() => {
+      order.push("onRunDone");
+    }),
+    log: vi.fn(),
+  } as unknown as ReturnType<typeof makeTracingDeps>;
+}
+
+/** flush 微任务队列（void finalizeRun 的 async 链推进到稳定态）。 */
+async function flushMicrotasks(ticks = 20): Promise<void> {
+  for (let i = 0; i < ticks; i++) {
+    // eslint-disable-next-line no-await-in-loop -- 排空微任务队列的固定 tick 循环，非逐项等待
+    await Promise.resolve();
+  }
+}
+
+// ── finalizeRun 直测 ─────────────────────────────────────────
+
+describe("finalizeRun（D5-② 单写点直测）", () => {
+  it("四步恰好一次且有序：transition → save → pending:unregister → onRunDone", async () => {
+    const run = makeRealRun("wf-fin-1");
+    const deps = makeTracingDeps();
+
+    const transitionSpy = vi.spyOn(run, "transition");
+    const ok = await finalizeRun(run, deps, "completed", { context: "test" });
+
+    expect(ok).toBe(true);
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("completed");
+    // 四步各恰好一次
+    expect(transitionSpy).toHaveBeenCalledTimes(1);
+    expect(deps.store.save).toHaveBeenCalledTimes(1);
+    expect(deps.eventBus!.emit).toHaveBeenCalledTimes(1);
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+    // 顺序：save → unregister → onRunDone（transition 已同步先行）
+    expect(deps.order).toEqual(["save", "emit:pending:unregister", "onRunDone"]);
+    // unregister reason = transition 后的 state.reason
+    expect(deps.eventBus!.emit).toHaveBeenCalledWith("pending:unregister", {
+      id: "wf-fin-1",
+      reason: "completed",
+    });
+  });
+
+  it("notifyDone:false → onRunDone 不调、unregister 仍发（terminateRunningRuns 真差异经参数承载）", async () => {
+    const run = makeRealRun("wf-fin-2");
+    const deps = makeTracingDeps();
+
+    const ok = await finalizeRun(run, deps, "failed", {
+      context: "terminateRunningRuns",
+      notifyDone: false,
+    });
+
+    expect(ok).toBe(true);
+    expect(run.state.reason).toBe("failed");
+    expect(deps.eventBus!.emit).toHaveBeenCalledTimes(1);
+    expect(deps.eventBus!.emit).toHaveBeenCalledWith("pending:unregister", {
+      id: "wf-fin-2",
+      reason: "failed",
+    });
+    expect(deps.onRunDone).not.toHaveBeenCalled();
+    expect(deps.order).toEqual(["save", "emit:pending:unregister"]);
+  });
+
+  it("transition 抛错（并发 abort 抢先终态化）→ 返回 false，后三步全不执行", async () => {
+    const run = makeRealRun("wf-fin-3");
+    // 抢先终态化——此后 running→done 转移抛 illegal-transition
+    run.transition("done", "aborted");
+    const deps = makeTracingDeps();
+
+    const ok = await finalizeRun(run, deps, "failed", { context: "test" });
+
+    expect(ok).toBe(false);
+    // 抢先方已兑现 unregister/onRunDone——本路径让位，不重复执行
+    expect(deps.store.save).not.toHaveBeenCalled();
+    expect(deps.eventBus!.emit).not.toHaveBeenCalled();
+    expect(deps.onRunDone).not.toHaveBeenCalled();
+    expect(run.state.reason).toBe("aborted");
+  });
+
+  it("save 抛错（ENOSPC）→ best-effort：unregister + onRunDone 照常（SW-DATA-3 统一）", async () => {
+    const run = makeRealRun("wf-fin-4");
+    const deps = makeTracingDeps();
+    deps.store.save = vi.fn(async () => {
+      throw new Error("ENOSPC: no space left on device");
+    });
+
+    const ok = await finalizeRun(run, deps, "failed", { context: "test" });
+
+    expect(ok).toBe(true);
+    expect(run.state.status).toBe("done");
+    expect(deps.eventBus!.emit).toHaveBeenCalledTimes(1);
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+  });
+
+  it("onRunDone 抛错 → 被捕获记日志（M12：真实副作用错误不静默吞、不上抛）", async () => {
+    const run = makeRealRun("wf-fin-5");
+    const deps = makeTracingDeps();
+    deps.onRunDone = vi.fn(() => {
+      throw new Error("interface notify blew up");
+    });
+
+    await expect(
+      finalizeRun(run, deps, "completed", { context: "test" }),
+    ).resolves.toBe(true);
+    expect(deps.eventBus!.emit).toHaveBeenCalledTimes(1);
+    expect(run.state.status).toBe("done");
+  });
+});
+
+// ── budget_limited 路径（dispatchAgentCall coda）四步恰好一次 ────────────
+
+describe("budget_limited 终态路径（dispatchAgentCall → finalizeRun）", () => {
+  it("agent call 后预算超限 → 四步恰好一次（unregister reason=budget_limited + onRunDone）", async () => {
+    const run = makeRealRun("wf-budget-1");
+    const deps = makeTracingDeps();
+    // budget.isExceeded 恒 true——runner.run 成功返回后命中 C-2 coda
+    (run.state.budget as unknown as { isExceeded: () => boolean }).isExceeded =
+      () => true;
+    deps.runner.run = vi.fn(async () =>
+      ({ content: "ok", durationMs: 1, error: undefined, toolCalls: [] }) as AgentResult,
+    );
+    const handlers: WorkerHandlers = {
+      onMessage: vi.fn(async () => {}),
+      onError: vi.fn(async () => {}),
+      onExit: vi.fn(async () => {}),
+    };
+
+    await handleWorkerMessage(
+      run,
+      { type: "agent-call", callId: 1, opts: { prompt: "p", description: "d" } },
+      deps,
+      handlers,
+    );
+    await flushMicrotasks();
+
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("budget_limited");
+    // save 2 次 = call 完成快照（dispatchAgentCall .then 的常规持久化）+ budget
+    // 终态快照（finalizeRun 内）——两次语义不同，收敛前后一致
+    expect(deps.store.save).toHaveBeenCalledTimes(2);
+    expect(deps.eventBus!.emit).toHaveBeenCalledTimes(1);
+    expect(deps.eventBus!.emit).toHaveBeenCalledWith("pending:unregister", {
+      id: "wf-budget-1",
+      reason: "budget_limited",
+    });
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+  });
+});