@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/orchestration/__tests__/launcher-nested-workflow.test.ts

@@ -7,7 +7,7 @@
  * 通过 vi.mock("../lifecycle.ts") 控制 runWorkflow：返回固定 runId + 把预构造的
  * child run 注入 deps.runs，使 pollRunToResult 首轮即命中 done 返回（无需真实 worker）。
  */
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { Budget } from "../models/budget.ts";
 import type { RunSpec } from "../models/run-spec.ts";
@@ -26,9 +26,9 @@ vi.mock("../lifecycle.ts", () => ({
 
 // import 在 vi.mock 之后（hoisting 保证拿到 mock 版本）。runWorkflow 从被 mock 的
 // lifecycle 模块导入，与 launcher.ts 内部引用的是同一 mock 实例。
-import { runWorkflow } from "../lifecycle.ts";
+import { runWorkflow, abortRun } from "../lifecycle.ts";
 import { ArgsValidationError } from "../args-validator.ts";
-import { executeNestedWorkflow } from "../launcher.ts";
+import { RUN_WATCHDOG_ENV, executeNestedWorkflow, runAndWait } from "../launcher.ts";
 
 const MOCK_RUN_ID = "wf-test-child";
 
@@ -69,12 +69,15 @@ function makeParentRun(opts: {
   parentWorkflowChain?: readonly string[];
   budget?: Budget;
   aborted?: boolean;
+  /** 预算语义对齐：父 run 级时间预算（deadline 传导测试用） */
+  budgetTimeMs?: number;
 } = {}): WorkflowRun {
   const controller = new AbortController();
   if (opts.aborted) controller.abort();
   const spec = {
     scriptName: opts.scriptName ?? "parent-wf",
     parentWorkflowChain: opts.parentWorkflowChain,
+    budgetTimeMs: opts.budgetTimeMs,
   };
   return {
     spec,
@@ -109,6 +112,24 @@ function makeDoneChildRun(opts: {
   } as unknown as WorkflowRun;
 }
 
+/**
+ * 构造 mock child WorkflowRun（running 态，pollRunToResult 持续轮询）。
+ * state 可变——deadline 测试中手动翻转为 done 模拟子 run 完成。
+ */
+function makeRunningChildRun(): WorkflowRun {
+  return {
+    runId: MOCK_RUN_ID,
+    spec: { scriptName: "child-wf" },
+    state: {
+      status: "running",
+      reason: undefined,
+      scriptResult: undefined,
+      error: undefined,
+      budget: { usedTokens: 0, usedCost: 0 },
+    },
+  } as unknown as WorkflowRun;
+}
+
 /** 构造 LauncherDeps mock：registry + runs（Map）+ 占位 port。 */
 function makeDeps(opts: {
   script?: WorkflowScript;
@@ -141,6 +162,17 @@ function setupRunWorkflow(childRun: WorkflowRun): void {
 
 beforeEach(() => {
   vi.clearAllMocks();
+  // [F-4 假红源修复] env 隔离对称化：本文件的「不限时」用例（deadline 传导 /
+  // runAndWait timeoutMs 语义）依赖「XYZ_SUBAGENT_RUN_WATCHDOG_MS 未设」基线，
+  // 宿主 shell export 即假红（U7 describe 内部 stubEnv 不覆盖同文件其他用例）。
+  // 空串 = 未设（getEnvRunWatchdogMs 的 raw falsy 判定）；SPAWN_WATCHDOG 同款
+  // 防御（launcher 不读，防未来接线后回归）。
+  vi.stubEnv(RUN_WATCHDOG_ENV, "");
+  vi.stubEnv("XYZ_SUBAGENT_SPAWN_WATCHDOG_MS", "");
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
 });
 
 // ── tests ────────────────────────────────────────────────────
@@ -274,4 +306,295 @@ describe("executeNestedWorkflow", () => {
     expect(result.content).toBe("");
     expect(result.error).toBe("agent exploded");
   });
+
+  // ── deadline 传导（预算语义对齐 2026-08）──
+  // 语义：父 spec.budgetTimeMs 显式设定 → 原样作为子 run 轮询 deadline（不 min(DEFAULT)
+  // 封顶）；父未设 → 无 deadline。旧实现 min(父, 10min) 把父 time:2h 截断到 10min。
+  describe("deadline 传导（预算语义对齐）", () => {
+    it("父 budgetTimeMs=2h → 子 deadline 传导 2h（不 min(10min) 封顶）", async () => {
+      vi.useFakeTimers();
+      try {
+        const parent = makeParentRun({ budgetTimeMs: 7_200_000 });
+        const childRun = makeRunningChildRun();
+        const deps = makeDeps({ script: makeScript(), childRun });
+        setupRunWorkflow(childRun);
+
+        const promise = executeNestedWorkflow("child-wf", {}, parent, deps);
+
+        // 越过旧 10min 默认：不应 abort（若回归 min 封顶，这里会触发 time_limited abort）
+        await vi.advanceTimersByTimeAsync(600_000 + 500);
+        expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+
+        // 2h deadline 到期：abortRun 收到完整 7200000ms 超时 + time_limited
+        await vi.advanceTimersByTimeAsync(7_200_000 + 1_000 - 600_500);
+        const result = await promise;
+        expect(vi.mocked(abortRun)).toHaveBeenCalledTimes(1);
+        expect(vi.mocked(abortRun)).toHaveBeenCalledWith(
+          MOCK_RUN_ID,
+          deps,
+          "Workflow timed out after 7200000ms",
+          "time_limited",
+        );
+        void result;
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("父未传 budgetTimeMs → 无 deadline（远超旧 10min 默认不 abort，子完成正常返回）", async () => {
+      vi.useFakeTimers();
+      try {
+        const parent = makeParentRun();
+        const childRun = makeRunningChildRun();
+        const deps = makeDeps({ script: makeScript(), childRun });
+        setupRunWorkflow(childRun);
+
+        const promise = executeNestedWorkflow("child-wf", {}, parent, deps);
+
+        // 旧实现 DEFAULT_RUNANDWAIT_TIMEOUT_MS=10min 会在此 abort；不限时则不 abort
+        await vi.advanceTimersByTimeAsync(10 * 60 * 1000 + 500);
+        expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+
+        // 子 run 完成 → 正常返回 completed（deadline 仍是 undefined）
+        childRun.state.status = "done";
+        childRun.state.reason = "completed";
+        childRun.state.scriptResult = "ok";
+        await vi.advanceTimersByTimeAsync(500);
+        const result = await promise;
+        // 成功分支返回 { content, parsedOutput? }（无 reason 字段）——string scriptResult 走 content
+        expect(result.content).toBe("ok");
+        expect(result.error).toBeUndefined();
+        expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    // [U2] 预算语义统一：budgetTimeMs <=0（含 0/负）与 undefined 同义 = 不限——
+    // 旧实现 0 传导给子 run 后 deadline=now 立即超时（"timed out after 0ms"），与
+    // lifecycle 的 0=不限（>0 才挂 scheduleTimeBudget）语义分裂。
+    it("父 budgetTimeMs=0 → 不限（旧实现立即超时；子 run 晚完成正常返回，U2）", async () => {
+      vi.useFakeTimers();
+      try {
+        const parent = makeParentRun({ budgetTimeMs: 0 });
+        const childRun = makeRunningChildRun();
+        const deps = makeDeps({ script: makeScript(), childRun });
+        setupRunWorkflow(childRun);
+
+        const promise = executeNestedWorkflow("child-wf", {}, parent, deps);
+
+        // 旧实现 0 落成 deadline=now：首轮轮询即 abort time_limited。不限时则不 abort
+        await vi.advanceTimersByTimeAsync(5_000);
+        expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+
+        childRun.state.status = "done";
+        childRun.state.reason = "completed";
+        childRun.state.scriptResult = "ok";
+        await vi.advanceTimersByTimeAsync(500);
+        const result = await promise;
+        expect(result.content).toBe("ok");
+        expect(result.error).toBeUndefined();
+        expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("父 budgetTimeMs=-5000 → 不限且错误串无 \"-5000ms\"（U2 负数同义不限）", async () => {
+      vi.useFakeTimers();
+      try {
+        const parent = makeParentRun({ budgetTimeMs: -5_000 });
+        const childRun = makeRunningChildRun();
+        const deps = makeDeps({ script: makeScript(), childRun });
+        setupRunWorkflow(childRun);
+
+        const promise = executeNestedWorkflow("child-wf", {}, parent, deps);
+
+        await vi.advanceTimersByTimeAsync(5_000);
+        expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+
+        childRun.state.status = "done";
+        childRun.state.reason = "completed";
+        childRun.state.scriptResult = "ok";
+        await vi.advanceTimersByTimeAsync(500);
+        const result = await promise;
+        expect(result.content).toBe("ok");
+        expect(result.error).toBeUndefined();
+        // 防御：任何路径都不产生 "timed out after -5000ms" 类错误串
+        const abortCalls = vi.mocked(abortRun).mock.calls.map((c) => String(c[2]));
+        expect(abortCalls.join(";")).not.toContain("-5000ms");
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+  });
+
+  // ── runAndWait timeoutMs 语义（预算语义对齐 2026-08）──
+  describe("runAndWait timeoutMs 语义（预算语义对齐）", () => {
+    it("未传 timeoutMs → 不限（远超旧 10min 默认不 abort，完成后正常返回）", async () => {
+      vi.useFakeTimers();
+      try {
+        const childRun = makeRunningChildRun();
+        const deps = makeDeps({ script: makeScript(), childRun });
+        setupRunWorkflow(childRun);
+
+        // 只传 3 参：不传 signal / timeoutMs
+        const promise = runAndWait("child-wf", {}, deps);
+
+        await vi.advanceTimersByTimeAsync(10 * 60 * 1000 + 500);
+        expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+
+        childRun.state.status = "done";
+        childRun.state.reason = "completed";
+        childRun.state.scriptResult = "ok";
+        await vi.advanceTimersByTimeAsync(500);
+        const result = await promise;
+        expect(result.status).toBe("done");
+        expect(result.reason).toBe("completed");
+        expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("显式 timeoutMs=1000 → 到期 abort time_limited（限时能力保留）", async () => {
+      vi.useFakeTimers();
+      try {
+        const childRun = makeRunningChildRun();
+        const deps = makeDeps({ script: makeScript(), childRun });
+        setupRunWorkflow(childRun);
+
+        const promise = runAndWait("child-wf", {}, deps, undefined, 1_000);
+
+        await vi.advanceTimersByTimeAsync(1_000 + 500);
+        const result = await promise;
+        expect(vi.mocked(abortRun)).toHaveBeenCalledTimes(1);
+        expect(vi.mocked(abortRun)).toHaveBeenCalledWith(
+          MOCK_RUN_ID,
+          deps,
+          "Workflow timed out after 1000ms",
+          "time_limited",
+        );
+        void result;
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    // [U2] 0/负 timeoutMs 与 undefined 同义 = 不限（旧实现 0 → 立即超时、
+    // 负数 → "timed out after -5000ms" 类错误串）。
+    it("timeoutMs=0 → 不限（旧实现立即超时；不产生 \"timed out after 0ms\"，U2）", async () => {
+      vi.useFakeTimers();
+      try {
+        const childRun = makeRunningChildRun();
+        const deps = makeDeps({ script: makeScript(), childRun });
+        setupRunWorkflow(childRun);
+
+        const promise = runAndWait("child-wf", {}, deps, undefined, 0);
+
+        await vi.advanceTimersByTimeAsync(5_000);
+        expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+
+        childRun.state.status = "done";
+        childRun.state.reason = "completed";
+        childRun.state.scriptResult = "ok";
+        await vi.advanceTimersByTimeAsync(500);
+        const result = await promise;
+        expect(result.reason).toBe("completed");
+        expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    // [U7] XYZ_SUBAGENT_RUN_WATCHDOG_MS：显式不限时 run 的绝对时限兑底（与
+    // spawn watchdog env 同款：未设 = 无兑底，设置 = opt-in 挂载）。
+    describe("XYZ_SUBAGENT_RUN_WATCHDOG_MS 兑底（U7）", () => {
+      it("env 设置 + 未传 timeoutMs → env 时限到期 abort time_limited，错误串含 env 值", async () => {
+        vi.useFakeTimers();
+        try {
+          vi.stubEnv(RUN_WATCHDOG_ENV, "1000");
+          const childRun = makeRunningChildRun();
+          const deps = makeDeps({ script: makeScript(), childRun });
+          setupRunWorkflow(childRun);
+
+          const promise = runAndWait("child-wf", {}, deps);
+
+          await vi.advanceTimersByTimeAsync(1_000 + 500);
+          const result = await promise;
+          expect(vi.mocked(abortRun)).toHaveBeenCalledWith(
+            MOCK_RUN_ID,
+            deps,
+            "Workflow timed out after 1000ms",
+            "time_limited",
+          );
+          // mock abortRun 不翻转 run 状态（对齐同组 timeoutMs=1000 用例）：result.reason
+          // 是 toResult 对 running run 的防御 fallback，不在此断言
+          void result;
+        } finally {
+          vi.useRealTimers();
+          vi.unstubAllEnvs();
+        }
+      });
+
+      it("env 设置 + 显式 timeoutMs → 显式值优先（env 不截断显式限时）", async () => {
+        vi.useFakeTimers();
+        try {
+          vi.stubEnv(RUN_WATCHDOG_ENV, "1000");
+          const childRun = makeRunningChildRun();
+          const deps = makeDeps({ script: makeScript(), childRun });
+          setupRunWorkflow(childRun);
+
+          const promise = runAndWait("child-wf", {}, deps, undefined, 60_000);
+
+          // env 1000ms 到期：不 abort（显式 60s 优先）
+          await vi.advanceTimersByTimeAsync(1_000 + 500);
+          expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+
+          // 显式 60s 到期：才 abort，错误串为显式值
+          await vi.advanceTimersByTimeAsync(60_000);
+          const result = await promise;
+          expect(vi.mocked(abortRun)).toHaveBeenCalledWith(
+            MOCK_RUN_ID,
+            deps,
+            "Workflow timed out after 60000ms",
+            "time_limited",
+          );
+          void result;
+        } finally {
+          vi.useRealTimers();
+          vi.unstubAllEnvs();
+        }
+      });
+
+      it("env 非法值（abc / -1）→ 视为未设（无兑底，不限）", async () => {
+        vi.useFakeTimers();
+        try {
+          const childRun = makeRunningChildRun();
+          const deps = makeDeps({ script: makeScript(), childRun });
+          setupRunWorkflow(childRun);
+
+          vi.stubEnv(RUN_WATCHDOG_ENV, "abc");
+          const promiseAbc = runAndWait("child-wf", {}, deps);
+          await vi.advanceTimersByTimeAsync(10 * 60 * 1000 + 500);
+          expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+          // 收尾完成，防用例间 promise 悬挂
+          childRun.state.status = "done";
+          childRun.state.reason = "completed";
+          childRun.state.scriptResult = "ok";
+          await vi.advanceTimersByTimeAsync(500);
+          await promiseAbc;
+
+          vi.mocked(abortRun).mockClear();
+          vi.stubEnv(RUN_WATCHDOG_ENV, "-1");
+          // childRun 已是 done 态：pollRunToResult 首轮即命中终态返回，无 deadline 可言
+          await runAndWait("child-wf", {}, deps);
+          expect(vi.mocked(abortRun)).not.toHaveBeenCalled();
+        } finally {
+          vi.useRealTimers();
+          vi.unstubAllEnvs();
+        }
+      });
+    });
+  });
 });

package/src/orchestration/__tests__/lifecycle.test.ts

@@ -90,7 +90,6 @@ function makeRunningRealRun(
   const worker = { terminate, postMessage: vi.fn() } as unknown as Parameters<typeof RunRuntime.prototype.constructor>[0];
   const runtime = new RunRuntime(
     worker as never,
-    { withSlot: vi.fn() } as never,
     controller,
     undefined,
   );
@@ -174,6 +173,16 @@ describe("scheduleTimeBudget", () => {
     expect(() => timer.unref()).not.toThrow();
     timer.unref();
   });
+
+  // [U1] setTimeout 2^31-1 溢出 fail-fast：溢出 budgetTimeMs 被 Node 置 1ms 立即触发
+  //（「不限时预算」变「立即超时」），arm 入口拦截且错误含上限值与恢复指引。
+  it("budgetTimeMs 溢出（>2^31-1）→ fail-fast throw（不挂 timer、不静默 clamp）", () => {
+    const deps = makeDeps();
+    expect(() => scheduleTimeBudget("wf-overflow", deps, 3_000_000_000)).toThrowError(/2147483647/);
+    expect(() => scheduleTimeBudget("wf-overflow", deps, Number.MAX_SAFE_INTEGER)).toThrowError(
+      /Recovery/,
+    );
+  });
 });
 
 // ── runWorkflow ──────────────────────────────────────────────
@@ -242,17 +251,42 @@ describe("runWorkflow", () => {
     expect(deps.eventBus.emit).not.toHaveBeenCalled();
   });
 
-  it("带 budgetTimeMs 时调度时间预算计时器", async () => {
+  it("带 budgetTimeMs 时调度时间预算计时器（真实消费：挂载 + 到期 time_limited）", async () => {
     const deps = makeDeps();
-    const scheduleTimeBudgetSpy = vi.fn(() => undefined);
-    (deps as LifecycleDeps & { scheduleTimeBudget?: unknown }).scheduleTimeBudget = scheduleTimeBudgetSpy;
     const spec = makeSpec({ budgetTimeMs: 3000 });
 
     const runId = await runWorkflow(spec, deps);
+    const run = deps.runs.get(runId)!;
 
-    // scheduleTimeBudget 在 lifecycle 内被调（runWorkflow 内联调，非走 deps.scheduleTimeBudget）
-    // 注意：runWorkflow 内直接调本文件的 scheduleTimeBudget，不读 deps.scheduleTimeBudget
-    expect(runId).toMatch(/^wf-/);
+    // 生产行为面①：budgetTimeMs>0 → RunRuntime.timeBudgetTimer 被真实挂载
+    //（scheduleTimeBudget 产出的 Node timer，非死代码 spy）
+    expect(run.runtime?.timeBudgetTimer).toBeDefined();
+
+    // 生产行为面②：到期后 abortRun(time_limited) 真实触发——run 转 done，
+    // reason/error/通知全部落位（文件级 beforeEach 已 fake timers）
+    await vi.advanceTimersByTimeAsync(3000);
+    await flushMicrotasks();
+
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("time_limited");
+    expect(run.state.error).toContain("Time budget exceeded");
+    expect(deps.eventBus.emit).toHaveBeenCalledWith("pending:unregister", {
+      id: runId,
+      reason: "time_limited",
+    });
+  });
+
+  it("未传 budgetTimeMs → 不挂时间预算计时器（对照：runtime.timeBudgetTimer undefined）", async () => {
+    const deps = makeDeps();
+    const runId = await runWorkflow(makeSpec(), deps);
+    const run = deps.runs.get(runId)!;
+
+    expect(run.runtime?.timeBudgetTimer).toBeUndefined();
+
+    // 无预算 → 不存在到期 abort：推进 10min 后 run 仍 running
+    await vi.advanceTimersByTimeAsync(10 * 60 * 1000);
+    await flushMicrotasks();
+    expect(run.state.status).toBe("running");
   });
 
   it("signal 已 abort → fail fast（抛错，不创建 run）", async () => {

package/src/orchestration/__tests__/non-cloneable-return-e2e.test.ts

@@ -0,0 +1,95 @@
+/**
+ * [F1] 端到端回归：execute() 返回不可克隆值 → run 收敛到 done,failed（非永久 running 悬挂）。
+ *
+ * 完整链路（真实 Worker 线程 + 真实 WorkerHostImpl，无 mock worker）：
+ *   脚本 return { fn: () => 1 } → postMessage DataCloneError → worker 侧 _safePost 记录 +
+ *   F1 fallback 回发可克隆 error 消息 → 主线程 handleScriptError（既有 script-error 重试
+ *   矩阵：3 次 rebuild + 指数退避 1s/2s/4s）→ 第 4 次 error 超限 → run done,failed。
+ *
+ * 修复前：return 消息被静默吞掉 → worker exit(0) → handleWorkerExit(0) no-op → run 永久
+ * running、runAndWait 无限挂起（本测试会超时红）。
+ *
+ * 主线程 belt（exit(0) 无终态消息 → 立即 failed）由 worker-exit-without-result.test.ts
+ * handler 级单测覆盖；两条防线共同保证「run 必达终态」不变式。
+ *
+ * 真实退避耗时 ~7s（1+2+4s）+ 4 次 worker 启动——per-test timeout 放宽到 30s。
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import { runWorkflow } from "../lifecycle.ts";
+import type { LifecycleDeps, RunStore } from "../models/ports.ts";
+import type { RunSpec } from "../models/run-spec.ts";
+import type { WorkflowRun } from "../models/workflow-run.ts";
+import { WorkerHostImpl } from "../worker-host.ts";
+
+/** 轮询直到 run 到达 done 终态或超时（挂起 → 超时红，即「非悬挂」断言本身）。 */
+async function waitForTerminal(
+  runs: Map<string, WorkflowRun>,
+  runId: string,
+  timeoutMs: number,
+): Promise<WorkflowRun> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const run = runs.get(runId);
+    if (run && run.state.status === "done") return run;
+    if (Date.now() > deadline) {
+      throw new Error(
+        `run ${runId} did not reach a terminal state within ${timeoutMs}ms ` +
+          `(status=${run?.state.status ?? "unknown"}) — hang regression`,
+      );
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+}
+
+describe("[F1] 不可克隆 return → run failed（非悬挂）— e2e", () => {
+  it(
+    "return { fn: () => 1 } → 经 script-error 重试矩阵收敛到 done,failed，归因含 structured-clone failed",
+    async () => {
+      const runs = new Map<string, WorkflowRun>();
+      const store: RunStore = {
+        save: vi.fn(async () => {}),
+        loadAll: async () => [],
+        stateFilePath: (id: string) => `/tmp/f1-e2e/${id}.jsonl`,
+      };
+      const deps = {
+        store,
+        workerHost: new WorkerHostImpl(),
+        runner: { run: vi.fn(async () => ({})) },
+        runs,
+        eventBus: { emit: vi.fn() },
+        onRunDone: vi.fn(),
+        log: vi.fn(),
+      } as unknown as LifecycleDeps & { onRunDone: ReturnType<typeof vi.fn> };
+
+      const spec: RunSpec = {
+        scriptSource: "return { ok: true, fn: () => 1 };",
+        args: {},
+        scriptName: "f1-non-cloneable",
+        scriptPath: "f1-non-cloneable.js",
+        slug: "f1-non-cloneable",
+      };
+
+      const runId = await runWorkflow(spec, deps);
+      expect(runs.get(runId)?.state.status).toBe("running");
+
+      // 挂起 → 此处超时 throw（修复前行为）；收敛 → done
+      const run = await waitForTerminal(runs, runId, 30_000);
+
+      expect(run.state.reason).toBe("failed");
+      // worker 侧 fallback 消息经 handleScriptError 超限路径写入归因
+      expect(run.state.error).toContain("structured-clone failed");
+      // 终态副作用齐全（对比 SW-DATA-3/F1 前的幽灵悬挂：无 unregister / 无 onRunDone）
+      expect(deps.eventBus.emit).toHaveBeenCalledWith(
+        "pending:unregister",
+        expect.objectContaining({ id: runId, reason: "failed" }),
+      );
+      expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+      // 终态已落盘（F1 不变式的持久化半边：非但收敛，且状态被记录可恢复）
+      expect(store.save).toHaveBeenCalled();
+      // workerLogs（DataCloneError 详情）随 error 消息落入 errorLogs，诊断不丢
+      expect(run.state.errorLogs.length).toBeGreaterThan(0);
+    },
+    35_000,
+  );
+});

package/src/orchestration/__tests__/review-fix-loop-e2e.test.ts

@@ -418,11 +418,12 @@ describe("review-fix-loop E2E（真实 worker + 场景化 mock runner）", () =>
       // m6：aggregator prompt 裁决段（5.4 ADJUDICATION）——裁决证据/降级保真/采信抽查
       const aggPrompt = prompts[kinds.indexOf("aggregate")];
       expect(aggPrompt).toContain("ADJUDICATION");
-      // m6：fix prompt 分流文案（trivial 直接修 / involved 标记 deferred）+ 自检要求
+      // m6：fix prompt 全等级修复文案（must-fix + minor 都修 / minor defer 需真实阻塞理由）+ 自检要求
       const fixPrompt = prompts[kinds.indexOf("fix")];
       expect(fixPrompt).toContain("Fix scope");
-      expect(fixPrompt).toContain("fix trivial ones");
-      expect(fixPrompt).toContain("mark involved ones as deferred");
+      expect(fixPrompt).toContain("across severity levels");
+      expect(fixPrompt).toContain("Minor (suggestion) issues are in fix scope too");
+      expect(fixPrompt).toContain("concrete blocker");
       expect(fixPrompt).toContain("self_check in each fixes[] entry MUST include");
       expect(fixPrompt).toContain("grep command + hit count + sync action");
       expect(reviewCalls.length).toBe(2);
@@ -430,6 +431,59 @@ describe("review-fix-loop E2E（真实 worker + 场景化 mock runner）", () =>
     RUN_TIMEOUT_MS,
   );
 
+  it(
+    "E2E-1b：suggestions-only 轮进 fix（全等级修复语义）→ R2 全清才 clean 终止",
+    async () => {
+      const runner = makeScenarioRunner({
+        review: [
+          // R1：suggestions-only（must_fix=0 + suggestion=2）——旧语义会在 all-clean break 提前终止（漏修）；
+          // 新语义必须走 aggregate → fix 修复建议级问题
+          () => ({ report_file: "/tmp/r1b-sugg.md", must_fix: 0, suggestion: 2, reconciliation: [] }),
+          // R2：全 0 → all-clean（must-fix 与 suggestion 双零）终止
+          () => ({ report_file: "/tmp/r2b-sugg.md", must_fix: 0, suggestion: 0, reconciliation: [] }),
+        ],
+        aggregate: () => ({
+          report_file: "/tmp/agg-sugg.md", must_fix: 0, suggestion: 2,
+          must_fix_ids: [], fixes_caution: [],
+        }),
+        fix: () => ({
+          fixed_count: 2,
+          fixes: [
+            { issue_id: "S-1", description: "fix suggestion 1", self_check: "grep: 1 hit; synced", affected_files: ["src/a.ts"] },
+            { issue_id: "S-2", description: "fix suggestion 2", self_check: "grep: 1 hit; synced", affected_files: ["src/b.ts"] },
+          ],
+          deferred: [],
+        }),
+      });
+      const deps = makeDeps(runner);
+
+      const result = await runAndWait(
+        wf("review-fix-loop"),
+        { targetType: "file", target: "README.md", agents: agentMd("reviewer"), _runId: RUN_ID() },
+        deps,
+        undefined,
+        RUN_TIMEOUT_MS,
+      );
+
+      expect(result.reason).toBe("completed");
+      expect(result.error).toBeUndefined();
+      const outcome = assertScriptOutcome(result.scriptResult);
+      expect(outcome.terminated).toBe("clean");
+      expect(outcome.totalFixed).toBe(2);
+
+      // 关键差异：suggestions-only 轮也派 fixer（旧语义 R1 即 all-clean break，0 次 fix）
+      const { kinds, reviewCalls, prompts } = runner.stats();
+      expect(reviewCalls.length).toBe(2);
+      expect(kinds.filter((k) => k === "fix").length).toBe(1);
+      expect(kinds.filter((k) => k === "aggregate").length).toBe(1);
+      // fix prompt 携带全等级修复指令
+      const fixPrompt = prompts[kinds.indexOf("fix")];
+      expect(fixPrompt).toContain("across severity levels");
+      expect(fixPrompt).toContain("Minor (suggestion) issues are in fix scope too");
+    },
+    RUN_TIMEOUT_MS,
+  );
+
   it(
     "E2E-2：skipCleanAgents 语义（clean agent 下轮跳过）+ fixAgent 参数接受（§7.2 2/3）",
     async () => {

package/src/orchestration/__tests__/skill-discovery.test.ts

@@ -155,3 +155,47 @@ describe("resolveSkillPath — 结果缓存（IF8/DM3）", () => {
     expect(existsSyncCalls.count).toBeGreaterThan(callsAfterFirst); // 重扫发生
   });
 });
+
+describe("resolveSkillPath — `..` 穿越守卫（三通道对称修复：skill 名是名字不是路径）", () => {
+  it("project 源：含 .. 逃逸 skills 根的名字 → not found（即使逃逸目标真实存在）", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    // 逃逸目标真实存在：projRoot/.agents/skills/../../escape-target = projRoot/escape-target。
+    // 旧实现 path.resolve 吸收 .. 后 existsSync 命中 → 返回树外目录；守卫后必须 undefined。
+    mkdirp(join(projRoot, "escape-target"));
+
+    expect(resolveSkillPath("../../escape-target")).toBeUndefined();
+  });
+
+  it("user 源：含 .. 逃逸的名字 → not found（同样不受 existsSync 命中误导）", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    // user skills 根 = homeRoot/.pi/agent/skills；../../escape-target → homeRoot/escape-target。
+    mkdirp(join(homeRoot, "escape-target"));
+
+    expect(resolveSkillPath("../../escape-target")).toBeUndefined();
+  });
+
+  it("npm 源：含 .. 逃逸包内 skills 根的名字 → not found", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    // npm skills 根 = homeRoot/.pi/agent/npm/node_modules/pkg/skills；"../steal" 逃逸到 node_modules/<pkg>/steal。
+    mkdirp(join(homeRoot, ".pi/agent/npm/node_modules/pkg-a/steal"));
+
+    expect(resolveSkillPath("../steal")).toBeUndefined();
+  });
+
+  it("根内归一化不被误拒：sub/../real 解析后仍在 skills 根内，正常命中", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const real = join(projRoot, ".agents/skills", "real");
+    mkdirp(real);
+
+    // 守卫只拒逃逸，不拒归一化：root/sub/../real = root/real（根内）→ 命中。
+    expect(resolveSkillPath("sub/../real")).toBe(real);
+  });
+
+  it("绝对路径形式的 skill 名 → not found（名字不具备绝对寻址能力）", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    mkdirp(join(projRoot, "outside-abs"));
+
+    // resolve(root, "/outside-abs") = /outside-abs —— 树外，拒。
+    expect(resolveSkillPath(join(projRoot, "outside-abs"))).toBeUndefined();
+  });
+});