@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/orchestration/__tests__/error-recovery-handlers.test.ts

@@ -16,7 +16,6 @@
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { ConcurrencyGate } from "../concurrency-gate.ts";
 import {
   handleScriptError,
   handleWorkerError,
@@ -41,6 +40,8 @@ function makeRunningRun(opts: {
   scriptErrorCount?: number;
   budgetTimeMs?: number;
   postMessage?: ReturnType<typeof vi.fn>;
+  /** [F1] 预置本 runtime 代际已收到终态消息（return/error）。 */
+  receivedTerminalMessage?: boolean;
 } = {}): WorkflowRun {
   return {
     state: {
@@ -66,6 +67,7 @@ function makeRunningRun(opts: {
     },
     runtime: {
       worker: { postMessage: opts.postMessage ?? vi.fn() },
+      receivedTerminalMessage: opts.receivedTerminalMessage,
     },
     // transition 副作用——run.state.status 由调用方通过 mock 控制后再次断言
     transition(target: string, reason?: string): void {
@@ -125,8 +127,11 @@ afterEach(() => {
 // ── handleWorkerExit ─────────────────────────────────────────
 
 describe("handleWorkerExit", () => {
-  it("code=0 正常退出：no-op（不 transition、不 save）", async () => {
-    const run = makeRunningRun();
+  it("code=0 且已收到终态消息：no-op（不 transition、不 save）", async () => {
+    // [F1] 语义更新：exit(0) no-op 的前提是本代际已交付 return/error（正常收尾退出，
+    // 或 script-error 重试退避窗口）。无终态消息的 exit(0) 现转 done,failed，
+    // 见下方用例与 worker-exit-without-result.test.ts。
+    const run = makeRunningRun({ receivedTerminalMessage: true });
     const deps = makeDeps();
     const handle = makeHandle(true);
 
@@ -137,6 +142,20 @@ describe("handleWorkerExit", () => {
     expect(deps.eventBus.emit).not.toHaveBeenCalled();
   });
 
+  it("code=0 且无终态消息：[F1] 转 done,failed（不可克隆 return 被吞的悬挂防线）", async () => {
+    const run = makeRunningRun();
+    const deps = makeDeps();
+    const handle = makeHandle(true);
+
+    await handleWorkerExit(run, 0, handle, deps, makeHandlers());
+
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("failed");
+    expect(run.state.error).toContain("structured-cloneable");
+    expect(deps.store.save).toHaveBeenCalledTimes(1);
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+  });
+
   it("code!=0 异常退出：委托 handleWorkerError → 超 MAX 重试 → transition done,failed", async () => {
     // workerErrorCount 已达 MAX=3 → handleWorkerError 内 count=4 > 3 → failed
     const run = makeRunningRun({ workerErrorCount: 3 });
@@ -379,6 +398,72 @@ describe("rebuildRuntime", () => {
 // rebuildRuntime → replaceRuntime → release 的 abort 旧 controller / terminate 旧
 // worker / discardInFlightCalls 全链路需要真实聚合根行为才成立。
 
+// ── race-F3：rebuild 时间预算折算（已耗墙钟不重置） ─────────────
+//
+// 旧实现 rebuildRuntime 重排计时器用满额 budgetTimeMs——每吃一次 worker/script
+// 错误重试就重置一次预算，最坏 6 次重试放大 ~6× 墙钟。修复后：
+// - 重排值 = max(0, 原预算 - 已耗墙钟)（从 run.meta.startedAt 推算）
+// - 重试前已耗尽 → 不 rebuild，直接 done,time_limited 终态
+//
+// 确定性说明：本文件 beforeEach 已 useFakeTimers()（默认 fake Date）——Date.now
+// 冻结，startedAt 倒拨值即精确已耗墙钟，断言可精确等值。
+describe("race-F3: rebuild 时间预算折算", () => {
+  it("剩余 30% → 重排预算 = 30% 而非满额", () => {
+    const run = makeRunningRun({ budgetTimeMs: 5000 });
+    // 已耗 70%（3500ms）→ 剩余 1500ms；fake Date 冻结，elapsed 精确
+    run.meta.startedAt = new Date(Date.now() - 3500).toISOString();
+    const scheduleTimeBudget = vi.fn(() => undefined);
+    const deps = makeDeps({ scheduleTimeBudget });
+
+    rebuildRuntime(run, deps, makeHandlers());
+
+    expect(scheduleTimeBudget).toHaveBeenCalledTimes(1);
+    const args = scheduleTimeBudget.mock.calls[0]!;
+    expect(args[1]).toBe(1500);
+    // run 保持 running（正常 rebuild 路径不受影响）
+    expect(run.state.status).toBe("running");
+  });
+
+  it("重试前预算已耗尽（已耗 > 预算）→ 不 rebuild，直接 done,time_limited", async () => {
+    const run = makeRunningRun({ budgetTimeMs: 5000 });
+    // 已耗 6000ms > 预算 5000ms（退避 advance 1000ms 后已耗 7000ms，仍耗尽）
+    run.meta.startedAt = new Date(Date.now() - 6000).toISOString();
+    const scheduleTimeBudget = vi.fn(() => undefined);
+    const deps = makeDeps({ scheduleTimeBudget });
+
+    const p = handleScriptError(run, "boom", [], deps, makeHandlers());
+    await vi.advanceTimersByTimeAsync(1000); // 推进退避（1s）
+    await p;
+
+    // 不 rebuild：不启新 worker、不重排计时器
+    expect(deps.workerHost.start).not.toHaveBeenCalled();
+    expect(scheduleTimeBudget).not.toHaveBeenCalled();
+    // 直接 time_limited 终态 + 持久化 + 注销通知 + onRunDone
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("time_limited");
+    expect(deps.store.save).toHaveBeenCalled();
+    expect(deps.eventBus.emit).toHaveBeenCalledWith(
+      "pending:unregister",
+      expect.objectContaining({ reason: "time_limited" }),
+    );
+    expect(deps.onRunDone).toHaveBeenCalled();
+  });
+
+  it("预算未耗尽（fresh run）→ 照常 rebuild，不误转 time_limited（防误伤回归）", async () => {
+    const run = makeRunningRun({ budgetTimeMs: 5000 }); // startedAt ≈ now，remaining 满
+    const scheduleTimeBudget = vi.fn(() => undefined);
+    const deps = makeDeps({ scheduleTimeBudget });
+
+    const p = handleScriptError(run, "boom", [], deps, makeHandlers());
+    await vi.advanceTimersByTimeAsync(1000);
+    await p;
+
+    expect(deps.workerHost.start).toHaveBeenCalledTimes(1);
+    expect(scheduleTimeBudget).toHaveBeenCalledTimes(1);
+    expect(run.state.status).toBe("running");
+  });
+});
+
 /** 手动控制的 deferred——精确编排「dispatch 挂起 → rebuild → 旧 promise settle」交错。 */
 interface Deferred<T> {
   promise: Promise<T>;
@@ -429,7 +514,7 @@ function makeRealRun(runId: string, opts: { budgetTimeMs?: number } = {}): Workf
     postMessage: vi.fn(),
     terminate: vi.fn(async () => {}),
   } as unknown as WorkerHandle;
-  run.assignRuntime(new RunRuntime(initialWorker, new ConcurrencyGate(), new AbortController()));
+  run.assignRuntime(new RunRuntime(initialWorker, new AbortController()));
   return run;
 }
 

package/src/orchestration/__tests__/execute-agent-call.test.ts

@@ -6,13 +6,17 @@
 import { describe, expect, it, vi } from "vitest";
 
 import {
+  DETERMINISTIC_SCHEMA_FAILURE_PREFIX,
   executeAgentCall,
+  isDeterministicSchemaFailureMsg,
   isStaleContextErrorMsg,
   STALE_CONTEXT_PATTERNS,
 } from "../execute-agent-call.ts";
 import { AgentCall } from "../models/agent-call.ts";
 import { Budget } from "../models/budget.ts";
 import type { AgentRunner } from "../models/ports.ts";
+import { describeMissingParsedOutput } from "../../execution/output-collector.ts";
+import type { ToolCall } from "../../execution/types.ts";
 import { Trace } from "../models/trace.ts";
 import type { ExecutionTraceNode } from "../models/types.ts";
 import type { AgentCallOpts, AgentResult } from "../models/types.ts";
@@ -312,3 +316,136 @@ describe("W4b: stale 分诊对齐 pi 真实文案", () => {
     expect(isStaleContextErrorMsg(undefined)).toBe(false);
   });
 });
+
+// ── MF-1: 确定性 schema 失败不重试 ──
+//
+// 回归背景（第五轮实测）：gate 终止子进程后 collectResult F-1 置归因 error →
+// executeAgentCall 判非 stale 走可重试分支 → 不可满足 schema 下循环至
+// MAX_ATTEMPTS=3（实测 attempts=3、4 子进程、235s vs 修复前 67.3s）。
+// 修复：归因 error 带机器标记（SSOT = DETERMINISTIC_SCHEMA_FAILURE_PREFIX），
+// 分诊短路。用真实链路产物（describeMissingParsedOutput）作 error 输入，锁定
+// collectResult → executeAgentCall 全链路分诊行为。
+//
+// 三态可重试性矩阵（完整锁定在 output-collector.test 的 MF-1 describe）：
+//   态① 从未调用 SO → 不可重试；态② isError（gate 终止/不可满足 schema）→ 不可重试；
+//   态③ 调用过但无 details → 可重试（保留既有重试语义）。
+
+/** 构造态②真实产物（isError SO 调用，schema 校验失败——gate 终止回归场景）。 */
+function state2Attribution(): string {
+  const soCalls: ToolCall[] = [
+    {
+      toolName: "structured-output",
+      isError: true,
+      result: { details: {}, content: [{ type: "text", text: "Schema validation failed: /target is required" }] },
+    },
+  ];
+  const msg = describeMissingParsedOutput(soCalls);
+  expect(msg).toBeDefined();
+  return msg!;
+}
+
+describe("MF-1: 确定性 schema 失败不重试", () => {
+  it("态②真实产物（gate 终止/schema 校验失败归因）→ runner.run 恰 1 次 + 终态 failed", async () => {
+    const attribution = state2Attribution();
+    expect(isDeterministicSchemaFailureMsg(attribution)).toBe(true);
+
+    const { call, trace } = makeAgentCallAndTrace();
+    const runner = createMockRunner(
+      vi.fn().mockResolvedValue(makeMockResult({ error: attribution })),
+    );
+    const budget = new Budget();
+
+    await executeAgentCall(call, runner, budget, new AbortController().signal, trace);
+
+    // 修复前：循环至 MAX_ATTEMPTS=3（4 次子进程）；修复后：恰 1 次
+    expect(runner.run).toHaveBeenCalledTimes(1);
+    expect(call.attempts).toBe(1);
+    expect(call.status).toBe("done");
+    expect(trace.find(0)?.status).toBe("failed");
+  });
+
+  it("态①真实产物（never called，缺 extension 环境确定性）→ 同样不重试", async () => {
+    const attribution = describeMissingParsedOutput([])!;
+    const { call, trace } = makeAgentCallAndTrace();
+    const runner = createMockRunner(
+      vi.fn().mockResolvedValue(makeMockResult({ error: attribution })),
+    );
+    const budget = new Budget();
+
+    await executeAgentCall(call, runner, budget, new AbortController().signal, trace);
+
+    expect(runner.run).toHaveBeenCalledTimes(1);
+    expect(call.attempts).toBe(1);
+    expect(trace.find(0)?.status).toBe("failed");
+  });
+
+  it("MF-2 计数不再低估：retry 不发生 → usage consume 恰一次、totalCallCount=1", async () => {
+    const attribution = state2Attribution();
+    const { call, trace } = makeAgentCallAndTrace();
+    const runner = createMockRunner(
+      vi.fn().mockResolvedValue(
+        makeMockResult({ error: attribution, usage: { input: 100, output: 50, cost: 0.01 } }),
+      ),
+    );
+    const budget = new Budget();
+
+    await executeAgentCall(call, runner, budget, new AbortController().signal, trace);
+
+    // 修复前：3 attempts → consume×3（usedTokens×3）；修复后：恰一次加权消耗
+    // （input×1 + output×2 = 100 + 100 = 200，权重见 budget.ts）
+    expect(budget.usedTokens).toBe(200);
+    expect(budget.usedCost).toBeCloseTo(0.01);
+    expect(budget.totalCallCount).toBe(1);
+  });
+
+  it("MF-3 归因不再混合：终态 error 保持归因原文（不被重试轮次覆盖）", async () => {
+    const attribution = state2Attribution();
+    const { call, trace } = makeAgentCallAndTrace();
+    const runner = createMockRunner(
+      vi.fn().mockResolvedValue(makeMockResult({ error: attribution })),
+    );
+    const budget = new Budget();
+
+    await executeAgentCall(call, runner, budget, new AbortController().signal, trace);
+
+    expect(call.result?.error).toBe(attribution);
+  });
+
+  it("态③（no details，无标记）→ 照常重试（可重试语义保留）", async () => {
+    vi.useFakeTimers();
+    try {
+      // 态③真实文案（不带确定性标记）——矩阵执行面锁定：无标记 = 可重试
+      const msg = describeMissingParsedOutput([
+        { toolName: "structured-output", result: { content: [] } },
+      ])!;
+      expect(isDeterministicSchemaFailureMsg(msg)).toBe(false);
+
+      const { call, trace } = makeAgentCallAndTrace();
+      const runner = createMockRunner(
+        vi.fn()
+          .mockResolvedValueOnce(makeMockResult({ error: msg }))
+          .mockResolvedValueOnce(makeMockResult()),
+      );
+      const budget = new Budget();
+
+      const promise = executeAgentCall(call, runner, budget, new AbortController().signal, trace);
+      await vi.advanceTimersByTimeAsync(2000);
+      await promise;
+
+      expect(runner.run).toHaveBeenCalledTimes(2);
+      expect(call.status).toBe("done");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("分诊交叉锁定：标记词不命中任何 STALE_CONTEXT_PATTERNS（stale 分诊在前也不误吞）", () => {
+    const lower = DETERMINISTIC_SCHEMA_FAILURE_PREFIX.toLowerCase();
+    for (const pattern of STALE_CONTEXT_PATTERNS) {
+      expect(lower.includes(pattern)).toBe(false);
+    }
+    // 两个分诊只命中确定性分支，互不污染
+    expect(isStaleContextErrorMsg(DETERMINISTIC_SCHEMA_FAILURE_PREFIX)).toBe(false);
+    expect(isDeterministicSchemaFailureMsg(DETERMINISTIC_SCHEMA_FAILURE_PREFIX)).toBe(true);
+  });
+});

package/src/orchestration/__tests__/jsonl-run-store-corrupt-entry.test.ts

@@ -0,0 +1,150 @@
+// src/orchestration/__tests__/jsonl-run-store-corrupt-entry.test.ts
+//
+// [SO-DATA-2] collectRecordRun 的 per-entry 隔离：1 条残缺 workflow-record entry
+// 不得让整个 loadAll 返回空。
+//
+// 防的 bug：deserializeRun 在 v guard 之后直接读 snapshot.state.budget 等嵌套字段，
+// 残缺 entry（截断/手改/跨版本半写）抛 TypeError 会沿 collectEntrySources 穿透
+// loadAll 的 catch → 返回空——单条损坏让全部 run 不可见（读序优先 entry，state
+// 文件兜底也不再走）。修复：collectRecordRun 单条 try/catch，损坏 entry 跳过 +
+// logger.warn 留证（含 entry 索引与原因），其余 entry 正常重建。
+//
+// 好坏对照：2 条好 entry 经真实 save 通路产出（快照形态可信，与
+// jsonl-run-store-loadall-sources.test.ts 同一搭建方式），1 条坏 entry 手工构造
+//（模拟损坏正是本用例的目的——绕开 schema 契约即 corruption 的本质）。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({ getLogger: () => loggerMock }));
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import type { CustomEntry } from "@earendil-works/pi-coding-agent";
+
+import { Budget } from "../models/budget.ts";
+import { Trace } from "../models/trace.ts";
+import type { RunSpec } from "../models/run-spec.ts";
+import type { ExecutionTraceNode } from "../models/types.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+import { JsonlRunStore, SNAPSHOT_VERSION, WORKFLOW_RECORD_CUSTOM_TYPE } from "../jsonl-run-store.ts";
+import { mkCtx, mkPi } from "./test-mocks.ts";
+
+function makeSpec(): RunSpec {
+  return {
+    scriptSource: "module.exports = async () => {};",
+    args: {},
+    scriptName: "test-script",
+    scriptPath: "/tmp/test.js",
+    description: "test",
+  };
+}
+
+function makeTraceNode(stepIndex: number): ExecutionTraceNode {
+  return { stepIndex, agent: "worker", task: "do thing", model: "default", status: "pending" };
+}
+
+function makeRunningRun(runId: string): WorkflowRun {
+  const trace = new Trace();
+  trace.append(makeTraceNode(0));
+  return WorkflowRun.reconstruct(runId, makeSpec(), {
+    status: "running",
+    budget: new Budget(),
+    calls: new Map(),
+    trace,
+    errorLogs: [],
+  }, { startedAt: new Date().toISOString() });
+}
+
+/** running → done 的完整生命周期 save（终态快照可被 deserializeRun 重建）。 */
+async function saveDoneRun(
+  sessionDir: string,
+  entries: CustomEntry[],
+  runId: string,
+): Promise<void> {
+  const store = new JsonlRunStore({ sessionDir, pi: mkPi(entries) });
+  const run = makeRunningRun(runId);
+  await store.save(run);
+  run.transition("done", "completed");
+  await store.save(run);
+}
+
+/** 手工构造残缺 record entry：v1 guard 通过，但 snapshot.state 缺全部必读嵌套字段
+ *  → deserializeRun 读 snapshot.state.budget.maxTokens 抛 TypeError。 */
+function corruptRecordEntry(runId: string): CustomEntry {
+  return {
+    type: "custom",
+    customType: WORKFLOW_RECORD_CUSTOM_TYPE,
+    data: {
+      v: 1,
+      snapshot: { v: SNAPSHOT_VERSION, runId, state: {} },
+      updatedAt: new Date().toISOString(),
+    },
+    id: `seed-corrupt-${runId}`,
+    parentId: null,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+describe("SO-DATA-2: 残缺 record entry 的 per-entry 隔离", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-corrupt-entry-"));
+    loggerMock.warn.mockClear();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("3 条 entry（2 好 1 坏）→ 返回 2 条 + warn 留证（含 entry 索引与原因）", async () => {
+    const entries: CustomEntry[] = [];
+    await saveDoneRun(tmpDir, entries, "run-a");
+    await saveDoneRun(tmpDir, entries, "run-b");
+    const corrupt = corruptRecordEntry("run-corrupt");
+    const seedEntries: CustomEntry[] = [...entries, corrupt];
+
+    const store = new JsonlRunStore({ sessionDir: tmpDir, ctx: mkCtx(seedEntries) });
+    const loaded = await store.loadAll();
+
+    // 损坏 entry 只跳过自身，其余 run 全部可见
+    expect(loaded.map((r) => r.runId).sort()).toEqual(["run-a", "run-b"]);
+    // warn 留证：entry 索引 + 损坏原因
+    expect(loggerMock.warn).toHaveBeenCalledTimes(1);
+    const warnMsg = String(loggerMock.warn.mock.calls[0]?.[0] ?? "");
+    expect(warnMsg).toContain(`entry #${seedEntries.indexOf(corrupt)}`);
+    expect(warnMsg).toContain("corrupted");
+  });
+
+  it("全部 entry 均损坏 → 返回空（不再抛 TypeError 穿透）+ 每条各留一条 warn", async () => {
+    const seedEntries: CustomEntry[] = [
+      corruptRecordEntry("run-corrupt-1"),
+      corruptRecordEntry("run-corrupt-2"),
+    ];
+    const store = new JsonlRunStore({ sessionDir: tmpDir, ctx: mkCtx(seedEntries) });
+    const loaded = await store.loadAll();
+    expect(loaded).toEqual([]);
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
+  });
+
+  it("损坏 entry 位于同 runId 好 entry 之前 → 后写覆盖语义不受影响（好快照胜出）", async () => {
+    const corrupt = corruptRecordEntry("run-x");
+    const entries: CustomEntry[] = [corrupt];
+    await saveDoneRun(tmpDir, entries, "run-x");
+
+    const store = new JsonlRunStore({ sessionDir: tmpDir, ctx: mkCtx(entries) });
+    const loaded = await store.loadAll();
+    expect(loaded.map((r) => r.runId)).toEqual(["run-x"]);
+    expect(loaded[0]?.state.status).toBe("done");
+  });
+});

package/src/orchestration/__tests__/jsonl-run-store-retention.test.ts

@@ -0,0 +1,202 @@
+// src/orchestration/__tests__/jsonl-run-store-retention.test.ts
+//
+// [B1] workflow-state 磁盘保留清理（opt-in，默认关）。
+//
+// 锁定的语义：
+// - 默认关：XYZ_SUBAGENT_STATE_MAX_RUNS 未设/空/0/负数/非数值 → 永不删除
+//   （「limits 默认关」裁决基线，watchdog 风格解析）；
+// - opt-in：每次新 run state 文件首写成功后，目录内 wf-*.jsonl 按 mtime 升序
+//   裁剪到上限（删最旧）；上限 3 写 5 个 → 剩最新 3；
+// - glob 外文件（非 wf- 前缀 / 非 .jsonl）与父目录 session JSONL 永不误删；
+// - 单个删除失败（unlink 目录 → EPERM，非 ENOENT）logger.warn 留证不抛，
+//   save 主链路不受影响。
+//
+// mtime 确定性：每个文件落盘后立即 utimesSync 钉死 mtime（基线 + i 分钟，全部
+// 过去时），消除同毫秒写入的排序抖动——被删集合 = mtime 最旧的 (N - cap) 个，
+// 断言精确到文件名。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({ getLogger: () => loggerMock }));
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { Budget } from "../models/budget.ts";
+import { Trace } from "../models/trace.ts";
+import type { RunSpec } from "../models/run-spec.ts";
+import type { ExecutionTraceNode } from "../models/types.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+import { JsonlRunStore, STATE_MAX_RUNS_ENV } from "../jsonl-run-store.ts";
+
+function makeSpec(): RunSpec {
+  return {
+    scriptSource: "module.exports = async () => {};",
+    args: {},
+    scriptName: "test-script",
+    scriptPath: "/tmp/test.js",
+    description: "test",
+  };
+}
+
+function makeTraceNode(stepIndex: number): ExecutionTraceNode {
+  return { stepIndex, agent: "worker", task: "do thing", model: "default", status: "pending" };
+}
+
+function makeRunningRun(runId: string): WorkflowRun {
+  const trace = new Trace();
+  trace.append(makeTraceNode(0));
+  return WorkflowRun.reconstruct(runId, makeSpec(), {
+    status: "running",
+    budget: new Budget(),
+    calls: new Map(),
+    trace,
+    errorLogs: [],
+  }, { startedAt: new Date().toISOString() });
+}
+
+/** runId 形如 lifecycle 生成器（wf-<ts>-<rand>），i 只进 ts 段保证唯一。 */
+function runIdAt(i: number): string {
+  return `wf-${1719500000000 + i * 1000}-retent`;
+}
+
+function stateFile(stateDir: string, runId: string): string {
+  return path.join(stateDir, `${runId}.jsonl`);
+}
+
+/** 把文件/目录 mtime 钉到过去（基线 + i 分钟）——排序判定不依赖真实写入时序。 */
+function pinMtime(fullPath: string, i: number, base: number): void {
+  const t = new Date(base + i * 60_000);
+  fs.utimesSync(fullPath, t, t);
+}
+
+describe("B1: workflow-state 保留清理（opt-in XYZ_SUBAGENT_STATE_MAX_RUNS）", () => {
+  let tmpDir: string;
+  let stateDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-retention-"));
+    stateDir = path.join(tmpDir, "workflow-state");
+    // 双保险：vitest.setup 全局净化 + 本文件显式 delete（防用例间经 stub 栈泄漏）
+    delete process.env[STATE_MAX_RUNS_ENV];
+    loggerMock.warn.mockClear();
+    loggerMock.debug.mockClear();
+  });
+
+  afterEach(() => {
+    delete process.env[STATE_MAX_RUNS_ENV];
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("上限 3 写 5 个 → 剩最新 3（mtime 最旧的 2 个被删）", async () => {
+    process.env[STATE_MAX_RUNS_ENV] = "3";
+    const store = new JsonlRunStore({ sessionDir: tmpDir });
+    const base = Date.now() - 10 * 60_000;
+
+    for (let i = 0; i < 5; i++) {
+      const runId = runIdAt(i);
+      await store.save(makeRunningRun(runId));
+      // save 返回 = 首写 flush + 本轮 prune 已执行；此刻钉 mtime 供下一轮 prune 排序
+      pinMtime(stateFile(stateDir, runId), i, base);
+    }
+
+    // 最后一轮 prune 按钉死的 mtime（0<1<2<3<4 分钟）裁到 3：留 i=2,3,4，删 i=0,1
+    expect(fs.readdirSync(stateDir).sort()).toEqual(
+      [runIdAt(2), runIdAt(3), runIdAt(4)].map((id) => `${id}.jsonl`).sort(),
+    );
+    expect(loggerMock.warn).not.toHaveBeenCalled();
+  });
+
+  it("未设 / 空 / 0 / 负数 / 非数值 → 不清理（默认关语义锁定）", async () => {
+    const store = new JsonlRunStore({ sessionDir: tmpDir });
+
+    // 未设：写 5 个全保留（无上限即无删除）
+    for (let i = 0; i < 5; i++) {
+      await store.save(makeRunningRun(runIdAt(i)));
+    }
+    expect(fs.readdirSync(stateDir)).toHaveLength(5);
+
+    // 显式非法值同样不启用（解析回落 undefined）：继续写、文件只增不减
+    for (const value of ["", "0", "-2", "abc", "NaN", "Infinity"]) {
+      process.env[STATE_MAX_RUNS_ENV] = value;
+      await store.save(makeRunningRun(runIdAt(5)));
+    }
+    // runIdAt(5) 首写（冷路径）flush 落盘第 6 个文件；后续 5 次为 running 热路径
+    // 去抖批（未 flush）——磁盘 6 个文件且全程无删除
+    expect(fs.readdirSync(stateDir)).toHaveLength(6);
+    expect(loggerMock.warn).not.toHaveBeenCalled();
+    await store.dispose();
+  });
+
+  it("glob 外文件与父目录 session JSONL 不误删（只删本目录 wf-*.jsonl）", async () => {
+    fs.mkdirSync(stateDir, { recursive: true });
+    const bystanders = [
+      "notes.txt",
+      "keep-me.jsonl",
+      "wf-truncated-noext",
+      "xwf-1719500000000-notwf.jsonl",
+    ];
+    for (const name of bystanders) {
+      fs.writeFileSync(path.join(stateDir, name), "x");
+    }
+    // session JSONL 在父目录（sessionDir），结构性不在扫描范围，实测钉住
+    const sessionFile = path.join(tmpDir, "main-session.jsonl");
+    fs.writeFileSync(sessionFile, "{}\n");
+
+    process.env[STATE_MAX_RUNS_ENV] = "1";
+    const store = new JsonlRunStore({ sessionDir: tmpDir });
+    const base = Date.now() - 10 * 60_000;
+
+    await store.save(makeRunningRun(runIdAt(0)));
+    pinMtime(stateFile(stateDir, runIdAt(0)), 0, base); // 钉成最旧
+    await store.save(makeRunningRun(runIdAt(1)));
+
+    // 2 个 state 文件裁到 1：runIdAt(0) 被删，4 个旁观文件原封不动
+    expect(fs.readdirSync(stateDir).sort()).toEqual(
+      [...bystanders, `${runIdAt(1)}.jsonl`].sort(),
+    );
+    expect(fs.existsSync(sessionFile)).toBe(true);
+    expect(loggerMock.warn).not.toHaveBeenCalled();
+  });
+
+  it("删除失败（unlink 目录 → EPERM）→ logger.warn 留证不抛，save 正常 resolve", async () => {
+    fs.mkdirSync(stateDir, { recursive: true });
+    // 用「名字命中 glob 的目录」制造确定性 unlink 失败（unlink 目录 → EPERM）
+    const blockerDir = stateFile(stateDir, runIdAt(0));
+    fs.mkdirSync(blockerDir);
+    pinMtime(blockerDir, 0, Date.now() - 10 * 60_000); // 钉成最旧 → 成为删除受害者
+
+    process.env[STATE_MAX_RUNS_ENV] = "1";
+    const store = new JsonlRunStore({ sessionDir: tmpDir });
+
+    // save 1 的 prune：受害者 = blockerDir → EPERM → warn，但 save 正常 resolve
+    await store.save(makeRunningRun(runIdAt(1)));
+    expect(fs.existsSync(stateFile(stateDir, runIdAt(1)))).toBe(true);
+    expect(fs.existsSync(blockerDir)).toBe(true);
+
+    // save 2 的 prune：3 项裁到 1，受害者 = dir（最旧，重试仍 EPERM）+ file1（次旧，删成）
+    await store.save(makeRunningRun(runIdAt(2)));
+    expect(fs.existsSync(stateFile(stateDir, runIdAt(1)))).toBe(false);
+    expect(fs.existsSync(stateFile(stateDir, runIdAt(2)))).toBe(true);
+    expect(fs.existsSync(blockerDir)).toBe(true);
+
+    // 每轮 prune 独立重试受害者：save1 与 save2 各 warn 一次（均指向 blockerDir），
+    // 不抛错、不阻断其余文件删除
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
+    for (const call of loggerMock.warn.mock.calls) {
+      const msg = String(call[0] ?? "");
+      expect(msg).toContain("state retention");
+      expect(msg).toContain(blockerDir);
+    }
+    await store.dispose();
+  });
+});