@zhushanwen/pi-subagent-workflow 7.4.0 → 8.0.0

package/src/execution/__tests__/execute-and-await-worktree.test.ts

@@ -40,7 +40,15 @@ vi.mock("node:child_process", async () => {
 
   return {
     spawn: vi.fn(() => new FakeChild()),
-    execFileSync: vi.fn(() => ""),
+    // buildEnvBlock 的 git branch 调用（execFile 异步）：默认 err-first 兜底 → catch → branch=""
+    execFile: vi.fn(
+      (
+        _cmd: string,
+        _args: readonly string[],
+        _opts: unknown,
+        cb: (err: Error | null, stdout?: string, stderr?: string) => void,
+      ) => cb(new Error("execFile not configured in this test")),
+    ),
   };
 });
 
@@ -188,9 +196,48 @@ describe("executeAndAwait worktree 失败收尾", () => {
     expect(archiveSpy).toHaveBeenCalledTimes(1);
     // store 现已强类型为 RecordStore → archive 入参为 ExecutionRecord，无需 `as` 断言。
     const archivedRecord = archiveSpy.mock.calls[0]![0];
-    expect(archivedRecord.status).toBe("failed");
+    expect(archivedRecord.status).toBe("closed");
     // archive 后 record 已移出 running map → listRunning 空、getMutable 取不到。
     expect(store.listRunning()).toHaveLength(0);
     expect(store.getMutable(archivedRecord.id)).toBeUndefined();
   });
+
+  // ============================================================
+  // create-await 竞态守卫（Phase 2）：create await 窗口内 dispose 抢先把
+  // record CAS 成 closed → 守卫 cleanup + throw cancelled（失败 throw 语义，
+  // SAR.run 的 catch 会转 AgentResult.error）。守卫 throw 不落在 try 内
+  // （否则被上方 catch 当 create 失败再走 finalizeFailed，对已 closed record 语义未定义）。
+  // ============================================================
+  it("守卫：create await 窗口内 dispose 抢先 → cleanup 被调 + throw cancelled（不进 runAndFinalize）", async () => {
+    const { service, worktreeManager } = setup();
+
+    const handle = Object.freeze({
+      path: "/tmp/wt-guard2",
+      branch: "pi-sub-guard2",
+      baseCommit: "abc123",
+      mainCwd: "/repo",
+    }) as Parameters<WorktreeManager["cleanup"]>[0];
+    let resolveCreate!: (h: unknown) => void;
+    vi.spyOn(worktreeManager, "create").mockImplementation(
+      () => new Promise((r) => { resolveCreate = r; }) as ReturnType<WorktreeManager["create"]>,
+    );
+    const cleanupSpy = vi.spyOn(worktreeManager, "cleanup").mockResolvedValue(undefined);
+
+    const execP = service.executeAndAwait({
+      task: "guard test",
+      slug: "guard-test",
+      worktree: true,
+      fork: true,
+      ctxModel,
+    });
+    // 微任务推进：record 已建 + executeAndAwait 挂在 pending create 上
+    await new Promise((r) => { setTimeout(r, 0); });
+    // dispose 抢先：CAS running → closed（此刻 worktreeHandle 仍 undefined，
+    // dispose 的 fire-and-forget cleanup 跳过）——守卫是唯一清理点
+    service.disposeAllRecords("parent-shutdown");
+    resolveCreate(handle);
+
+    await expect(execP).rejects.toThrow("cancelled during worktree creation");
+    expect(cleanupSpy).toHaveBeenCalledWith(handle);
+  });
 });

package/src/execution/__tests__/execute-nesting.test.ts

@@ -5,8 +5,8 @@
 // 用例：
 //   D-032  background 进并发池（分层配额：max(1, maxConcurrent - depth)）
 //   D-033  execute 入口通用嵌套护栏（execCtxAls 计 fork+非 fork 嵌套，深度>MAX 拒）
-//   嵌套抑制 background onUpdate 恒 undefined（防 spinner 堆叠）
-//   节流清理 background finalize 后 throttleState 无残留（clearThrottle 生效）
+//   （原「嵌套抑制 onUpdate」「节流清理 throttleState」用例组已随 onEventThrottled
+//   死路径删除一并移除——swf-perf-impl ledger #22 / cleanup-slice TC4）
 //
 // ── mock 策略 ──
 //
@@ -18,7 +18,8 @@
 //   mock 模式参考 run-spawn-integration.test.ts（该文件是 spawn 改造后的正确 mock 范式）：
 //     - node:child_process.spawn → FakeChild（EventEmitter + PassThrough），测试控制器
 //       emit stdout JSON 行（header + SdkEvent）/ stderr / close 时序。
-//     - node:child_process.execFileSync → ""（buildEnvBlock 的 git branch 调用避免副作用）。
+//     - node:child_process.execFile → err-first callback 默认兜底（buildEnvBlock 的 git
+//       branch 调用失败 → catch → branch=""，避免副作用）。
 //     - node:fs 同步方法 → mock（mkdirSync/existsSync/appendFileSync/writeFileSync/readdirSync），
 //       避免 sessionDir/sessionFile 触碰真实文件系统。
 //     - fs.promises.* → 保留真实实现（temp-prompt 整体被 mock，不触发真实 I/O）。
@@ -26,7 +27,7 @@
 //     - alive-store.writeAliveMarker → mock（避免写 .alive sidecar）。
 //
 //   所有断言语义不变：它们测的是 SubagentService 的 **编排逻辑**
-//   （pool.acquire / execCtxAls 深度 / onUpdate 抑制 / throttle 清理），这些逻辑
+//   （pool.acquire / execCtxAls 深度），这些逻辑
 //   无论事件来自 fakeSession.subscribe 还是 FakeChild.stdout 都一致。
 
 import type { PassThrough } from "node:stream";
@@ -60,7 +61,15 @@ vi.mock("node:child_process", async () => {
 
   return {
     spawn: vi.fn(() => new FakeChild()),
-    execFileSync: vi.fn(() => ""), // buildEnvBlock 的 git branch 调用，返回空避免副作用
+    // buildEnvBlock 的 git branch 调用（execFile 异步）：默认 err-first 兜底 → catch → branch=""
+    execFile: vi.fn(
+      (
+        _cmd: string,
+        _args: readonly string[],
+        _opts: unknown,
+        cb: (err: Error | null, stdout?: string, stderr?: string) => void,
+      ) => cb(new Error("execFile not configured in this test")),
+    ),
   };
 });
 
@@ -133,6 +142,7 @@ vi.mock("../temp-prompt.ts", () => ({
 
 import { spawn } from "node:child_process";
 
+import { waitForSpawn } from "./helpers/spawn-mock.ts";
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
 import { MAX_FORK_DEPTH } from "../session-context-resolver.ts";
@@ -162,23 +172,6 @@ function lastSpawnedChild(): FakeChild {
   return result.value as FakeChild;
 }
 
-/**
- * 等待 execute → runSpawn 内部调到 spawn（拿到 child 控制器）。
- *
- * runSpawn 是 async，spawn 在 mkdirSync + writePromptToTempFile 之后才调（均有微任务/
- * I/O 延迟）。用 setInterval 轮询 mockSpawn.mock.results，比 vi.waitFor 在该 vitest 版本
- * 下更可靠（vi.waitFor 偶发过早 resolve 导致后续读取竞态）。
- */
-async function waitForSpawn(timeoutMs = 1000): Promise<void> {
-  const start = Date.now();
-  while (mockSpawn.mock.results.length === 0) {
-    if (Date.now() - start > timeoutMs) {
-      throw new Error(`spawn was not called within ${timeoutMs}ms`);
-    }
-    await new Promise((r) => setTimeout(r, 2));
-  }
-}
-
 // ============================================================
 // 辅助：FakeChild stdout 驱动（替代旧 fakeSession.subscribe 的事件注入）
 // ============================================================
@@ -271,7 +264,7 @@ describe("嵌套护栏 / 并发池 / 节流（D-030~D-033 回归锁）", () => {
 
     const execPromise = service.execute({ task: "bg in pool", ctxModel });
     // detached runAndFinalize → acquire。等 spawn 拿到 child 再驱动完成。
-    await waitForSpawn();
+    await waitForSpawn(mockSpawn);
     await driveChildToCompletion(lastSpawnedChild());
 
     // 等 detached promise 链跑完（kickOffBackground 的 .then notify）
@@ -312,7 +305,7 @@ describe("嵌套护栏 / 并发池 / 节流（D-030~D-033 回归锁）", () => {
     const execPromise = execCtxAls.run({ recordId: "parent", depth: MAX_FORK_DEPTH - 1 }, () =>
       service.execute({ task: "at limit", ctxModel }),
     );
-    await waitForSpawn();
+    await waitForSpawn(mockSpawn);
     await driveChildToCompletion(lastSpawnedChild(), [
       { type: "turn_end" },
       { type: "message_end", message: { usage: { input: 1 } } },
@@ -323,53 +316,8 @@ describe("嵌套护栏 / 并发池 / 节流（D-030~D-033 回归锁）", () => {
   });
 
   // ============================================================
-  // 嵌套 sync onUpdate 抑制（nestingDepth>0 → onUpdate undefined）
+  // 原嵌套抑制 onUpdate / 节流清理 throttleState 用例组（:322-355）已删除——
+  // onEventThrottled 死路径删除（swf-perf-impl ledger #22 / cleanup-slice TC4/IF14，
+  // 详见 .cw/swf-perf-impl/cleanup-slice-design.json）。恢复点：本 slice 前的 git 历史。
   // ============================================================
-
-  it("[嵌套抑制] 嵌套 sync（execCtxAls depth>0）不回流 onUpdate", async () => {
-    const { service } = setup();
-
-    const execCtxAls = Reflect.get(service, "execCtxAls") as ExecCtxAls;
-
-    const updates: unknown[] = [];
-    const execPromise = execCtxAls.run({ recordId: "parent", depth: 1 }, () =>
-        service.execute({ task: "nested sync", ctxModel, onUpdate: (d) => updates.push(d) }),
-    );
-    await waitForSpawn();
-    // emit 会触发 onUpdate 的事件（tool_start/tool_end 是 TRIGGERING_EVENT），
-    // 但嵌套层 onUpdate 被抑制（undefined）→ onEventThrottled 包装不挂载 → 0 次
-    await driveChildToCompletion(lastSpawnedChild(), [
-      { type: "tool_execution_start", toolCallId: "t1", toolName: "read" },
-      { type: "tool_execution_end", toolCallId: "t1", toolName: "read" },
-      { type: "message_end", message: { usage: { input: 1 } } },
-    ]);
-    await execPromise;
-
-    // tool_end 是 TRIGGERING_EVENT，但嵌套层 onUpdate 被抑制（undefined）→ 0 次
-    expect(updates).toHaveLength(0);
-  });
-
-  // ============================================================
-  // clearThrottle：sync 完成后 throttleState 清理
-  // ============================================================
-
-  it("[节流清理] sync 完成后 throttleState 无残留（clearThrottle 生效）", async () => {
-    const { service } = setup();
-
-    const execPromise = service.execute({
-      task: "throttle clear",
-      ctxModel,
-      onUpdate: () => {},
-    });
-    await waitForSpawn();
-    await driveChildToCompletion(lastSpawnedChild(), [
-      { type: "tool_execution_end", toolCallId: "t1", toolName: "read" },
-      { type: "message_end", message: { usage: { input: 1 } } },
-    ]);
-    await execPromise;
-
-    // finalizeRecord → clearThrottle 清掉该 record 的节流 entry（防 Map 无限增长 + trailing 误发陈旧）
-    const throttleState = Reflect.get(service, "throttleState") as Map<string, unknown>;
-    expect(throttleState.size).toBe(0);
-  });
 });

package/src/execution/__tests__/execution-record.test.ts

@@ -10,8 +10,10 @@ import {
   getCurrentActivity,
   getEventLog,
   getFullText,
+  getFullTextFrom,
   getTotalUsage,
   markReconstructedStatus,
+  nextRoundBaseTurnIndex,
   project,
   projectLiveProgress,
   snapshot,
@@ -576,6 +578,152 @@ describe("getFullText", () => {
   });
 });
 
+// ============================================================
+// getFullTextFrom — 增量文本派生（round-base-increment wave1）
+// ============================================================
+describe("getFullTextFrom", () => {
+  it("C1TC2: from=0 与 getFullText 逐字节等价（fresh / 单 turn / 多 turn 混空 turn 三形态）", () => {
+    // 形态 1：fresh record（turns=[emptyTurn()]）
+    const fresh = makeRecord();
+    expect(getFullTextFrom(fresh, 0)).toBe(getFullText(fresh));
+    expect(getFullTextFrom(fresh, 0)).toBe("");
+
+    // 形态 2：单 turn 有文本
+    const single = makeRecord();
+    updateFromEvent(single, { type: "text_delta", delta: "Hello world" });
+    expect(getFullTextFrom(single, 0)).toBe(getFullText(single));
+    expect(getFullTextFrom(single, 0)).toBe("Hello world");
+
+    // 形态 3：多 turn 混空 turn（closed 空 turn + 空白串 turn + 未闭合尾 turn）
+    const mixed = makeRecord();
+    updateFromEvent(mixed, { type: "text_delta", delta: "Turn 1" });
+    updateFromEvent(mixed, { type: "turn_end" });
+    updateFromEvent(mixed, { type: "turn_end" }); // 空 turn 2（closed）
+    updateFromEvent(mixed, { type: "text_delta", delta: " " }); // 空白串 turn 3
+    updateFromEvent(mixed, { type: "turn_end" });
+    updateFromEvent(mixed, { type: "text_delta", delta: "Turn 4" }); // 未闭合尾 turn
+    expect(getFullTextFrom(mixed, 0)).toBe(getFullText(mixed));
+    expect(getFullTextFrom(mixed, 0)).toBe("Turn 1\n\n \n\nTurn 4");
+  });
+
+  it("C1TC3: 多 turn 单轮增量——from=1 只含 Turn 2，对照全量含 Turn 1\\n\\nTurn 2", () => {
+    const r = makeRecord();
+    updateFromEvent(r, { type: "text_delta", delta: "Turn 1" });
+    updateFromEvent(r, { type: "turn_end" });
+    updateFromEvent(r, { type: "text_delta", delta: "Turn 2" });
+    expect(getFullTextFrom(r, 1)).toBe("Turn 2");
+    // 对照：全量 vs 增量差异锁定
+    expect(getFullText(r)).toBe("Turn 1\n\nTurn 2");
+  });
+
+  it("C1TC4: 空文本轮过滤（join 不多出空段）+ 空白串按非空计入增量", () => {
+    // turns: ["A"(closed), ""(closed), " "(closed), "B"(open)]
+    const r = makeRecord();
+    updateFromEvent(r, { type: "text_delta", delta: "A" });
+    updateFromEvent(r, { type: "turn_end" });
+    updateFromEvent(r, { type: "turn_end" }); // 空 turn（closed）
+    updateFromEvent(r, { type: "text_delta", delta: " " });
+    updateFromEvent(r, { type: "turn_end" });
+    updateFromEvent(r, { type: "text_delta", delta: "B" });
+    // from=2 起：空 turn 在 from 之前不参与；" " 按非空处理计入增量（filter 判据与 getFullText 逐字对齐）
+    expect(getFullTextFrom(r, 2)).toBe(" \n\nB");
+    // 空 turn 过滤：from=0 时不产出空段（join 不多出 \n\n 空段）
+    expect(getFullTextFrom(r, 0)).toBe("A\n\n \n\nB");
+  });
+
+  it("C1TC5: from >= turns.length 越界返回空串（不抛错、不回绕）", () => {
+    const r = makeRecord();
+    updateFromEvent(r, { type: "text_delta", delta: "Turn 1" });
+    updateFromEvent(r, { type: "turn_end" });
+    updateFromEvent(r, { type: "text_delta", delta: "Turn 2" });
+    expect(getFullTextFrom(r, r.turns.length)).toBe("");
+    expect(getFullTextFrom(r, r.turns.length + 5)).toBe("");
+  });
+
+  it("C1TC6: from 为负规范化为 0（与 from=0 / getFullText 等价，无 slice 负偏移语义）", () => {
+    const r = makeRecord();
+    updateFromEvent(r, { type: "text_delta", delta: "Turn 1" });
+    updateFromEvent(r, { type: "turn_end" });
+    updateFromEvent(r, { type: "text_delta", delta: "Turn 2" });
+    expect(getFullTextFrom(r, -1)).toBe(getFullTextFrom(r, 0));
+    expect(getFullTextFrom(r, -100)).toBe(getFullText(r));
+    expect(getFullTextFrom(r, -100)).toBe("Turn 1\n\nTurn 2");
+  });
+});
+
+// ============================================================
+// nextRoundBaseTurnIndex — 轮次边界推进公式（round-base-increment wave1）
+// ============================================================
+describe("nextRoundBaseTurnIndex", () => {
+  it("C1TC7: 全闭合推进 length / fresh record（[emptyTurn()] 单未闭合空 turn）返回 0", () => {
+    // 全闭合：2 个 closed turn → length
+    const r = makeRecord();
+    updateFromEvent(r, { type: "text_delta", delta: "Turn 1" });
+    updateFromEvent(r, { type: "turn_end" });
+    updateFromEvent(r, { type: "text_delta", delta: "Turn 2" });
+    updateFromEvent(r, { type: "turn_end" });
+    expect(r.turns.length).toBe(2);
+    expect(nextRoundBaseTurnIndex(r)).toBe(2);
+
+    // fresh 形态（createRecord：turns=[emptyTurn()] 单个未闭合空 turn）→ 0（ES6 重建回退语义）
+    const fresh = createRecord("fresh-1", {
+      agent: "worker",
+      model: "test-model",
+      thinkingLevel: undefined,
+      mode: "sync",
+      task: "t",
+      slug: "t",
+      startedAt: 1000,
+      rootSessionId: "sess-main",
+      parentRecordId: undefined,
+      depth: 0,
+    });
+    expect(fresh.turns).toHaveLength(1);
+    expect(nextRoundBaseTurnIndex(fresh)).toBe(0);
+  });
+
+  it("C1TC8 ⛔ ES1 探针: 滞后空 turn（防御分支）边界不丢下轮首段文本", () => {
+    // 防御分支构造（pi 现事件序下不可达——带 usage 的 message_end 恒先于 turn_end；探针
+    // 按防御分支构造仍有效，锁住公式在滞后交错下的正确性，防 pi 未来事件序变化）。
+    // 两层 usage 守卫：session-runner.ts 转发层 if (msg?.usage)（bare message_end 不转发）
+    // + execution-record.ts 累积层 if (event.usage)（bare message_end 不开 turn）——
+    // 故本探针的 message_end 必须携带 usage（如 { input: 10, output: 5, cacheRead: 0, cacheWrite: 0 }）才能开出空 turn。
+    const r = makeRecord();
+    updateFromEvent(r, { type: "text_delta", delta: "R1" });
+    updateFromEvent(r, { type: "turn_end" }); // 闭合本轮
+    updateFromEvent(r, {
+      type: "message_end",
+      usage: { input: 10, output: 5, cacheRead: 0, cacheWrite: 0 },
+    }); // 滞后 message_end 开新空 turn
+    expect(r.turns.length).toBe(2);
+    expect(r.turns[1]!.closed).toBe(false);
+    expect(r.turns[1]!.text).toBe("");
+
+    // 推进：滞后空 turn 不计入边界（turns.length - 1，留在下一轮增量内）
+    const base = nextRoundBaseTurnIndex(r);
+    expect(base).toBe(1);
+
+    // 新轮 text_delta 复用该空 turn → 文本落在增量范围内，不丢
+    updateFromEvent(r, { type: "text_delta", delta: "R2" });
+    expect(r.turns.length).toBe(2); // 复用，未新开
+    expect(getFullTextFrom(r, base)).toBe("R2");
+
+    // 对照组：若直用 turns.length 推进，R2 被挤出 slice——被防住的丢文本负面行为锁定
+    expect(getFullTextFrom(r, r.turns.length)).toBe("");
+  });
+
+  it("C1TC9: 末 turn 未闭合且非空计入本轮（防御形态公式锁定，R1 观测哨触发条件）", () => {
+    // pi 现序不可达（agent_settled 在 agent_end 之后，error/aborted 也先 emit turn_end）；
+    // 构造该防御形态锁死公式行为：非空文本计入本轮增量、不 defer 到下轮。
+    const r = makeRecord();
+    updateFromEvent(r, { type: "text_delta", delta: "Turn 1" });
+    updateFromEvent(r, { type: "turn_end" });
+    updateFromEvent(r, { type: "text_delta", delta: "Unclosed tail" }); // 未闭合非空尾 turn
+    expect(nextRoundBaseTurnIndex(r)).toBe(r.turns.length);
+    expect(nextRoundBaseTurnIndex(r)).toBe(2);
+  });
+});
+
 // ============================================================
 // getAllToolCalls / getTotalUsage — 聚合派生
 // ============================================================
@@ -957,3 +1105,54 @@ describe("projectLiveProgress (T3.21)", () => {
     expect(result.lastError).toBe("something went wrong");
   });
 });
+
+// ============================================================
+// tool_end running 索引 [perf]
+// ============================================================
+// 索引弹尾必须与旧实现「倒序全扫找最后一个 running 同名」语义等价：
+// 同名并发 toolCall 的 tool_end 交错到达时按 LIFO 配对，配对结果写回正确槽位。
+describe("tool_end running index [perf]", () => {
+  const start = (record: ExecutionRecord, name: string, args: Record<string, unknown> = {}) =>
+    updateFromEvent(record, { type: "tool_start", toolName: name, args });
+
+  const end = (record: ExecutionRecord, name: string, result: string) =>
+    updateFromEvent(record, { type: "tool_end", toolName: name, result, isError: false });
+
+  it("同名并发两个 toolCall：tool_end LIFO 配对，结果写回各自槽位", () => {
+    const record = makeRecord();
+    start(record, "bash", { cmd: "first" });
+    start(record, "bash", { cmd: "second" });
+
+    // 第一个 end 配对最后 push 的 running 同名（second）——与旧倒序全扫一致
+    end(record, "bash", "result-for-second");
+    const calls = record.turns[0]!.toolCalls;
+    expect(calls).toHaveLength(2);
+    expect(calls[0]).toMatchObject({ args: { cmd: "first" }, _status: "running" });
+    expect(calls[1]).toMatchObject({ result: "result-for-second", _status: "done" });
+
+    // 第二个 end 配对剩下的 first
+    end(record, "bash", "result-for-first");
+    expect(calls[0]).toMatchObject({ result: "result-for-first", _status: "done" });
+    expect(calls[1]).toMatchObject({ result: "result-for-second", _status: "done" });
+  });
+
+  it("索引 miss（无 tool_start 的外部注入 tool_end）→ fallback 全扫后 push 幽灵条目", () => {
+    const record = makeRecord();
+    end(record, "external_tool", "injected");
+    const calls = record.turns[0]!.toolCalls;
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({ toolName: "external_tool", result: "injected", _status: "done" });
+  });
+
+  it("跨 turn 滞后 tool_end：索引跨 turn 命中（与旧全扫语义一致）", () => {
+    const record = makeRecord();
+    start(record, "read");            // turn 0 内 running
+    updateFromEvent(record, { type: "turn_end" }); // 闭合 turn 0，开 turn 1
+    start(record, "write");           // turn 1
+    end(record, "write", "w-done");   // 正常配对 turn 1
+    end(record, "read", "r-done");    // 滞后 end 配对 turn 0（跨 turn 兜底）
+
+    expect(record.turns[0]!.toolCalls[0]).toMatchObject({ toolName: "read", result: "r-done", _status: "done" });
+    expect(record.turns[1]!.toolCalls[0]).toMatchObject({ toolName: "write", result: "w-done", _status: "done" });
+  });
+});

package/src/execution/__tests__/finalize-record.test.ts

@@ -25,7 +25,7 @@ vi.mock("@zhushanwen/pi-extension-logger", () => ({
   getLogger: () => loggerMock,
 }));
 
-import { doFinalizeRecord } from "../finalize-record.ts";
+import { doFinalizeRecord, doFinalizeRoundToIdle } from "../finalize-record.ts";
 import { ManifestStore } from "../manifest-store.ts";
 import type { AgentResult, ExecutionRecord } from "../types.ts";
 
@@ -89,35 +89,34 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
       store: { archive: vi.fn() } as never,
       modelService: {} as never,
       pi: { appendEntry: vi.fn() },
-      clearThrottle: vi.fn(),
       emitUnregister: vi.fn(),
     };
   }
 
-  it("status=cancelled → manifest 写 cancelled（不再归并 failed）", async () => {
+  it("status=closed + cancelled reason → manifest 写 closed（v4 B-1：cancelled 折入 closed）", async () => {
     const record = makeMinimalRecord({ id: "rec-cancelled" });
-    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "cancelled");
+    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", "cancelled");
 
     const manifest = await manifestStore.readManifest("rec-cancelled");
     expect(manifest).not.toBeNull();
-    // 关键断言：cancelled 直接透传,不是 "failed"
-    expect(manifest?.status).toBe("cancelled");
+    // 关键断言：v4 B-1 manifest status 恒写 closed（cancelled 区分靠 tombstone sidecar）
+    expect(manifest?.status).toBe("closed");
   });
 
-  it("status=done → manifest 写 completed", async () => {
+  it("status=closed + user-close → manifest 写 closed", async () => {
     const record = makeMinimalRecord({ id: "rec-done" });
-    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "done");
+    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", "user-close");
 
     const manifest = await manifestStore.readManifest("rec-done");
-    expect(manifest?.status).toBe("completed");
+    expect(manifest?.status).toBe("closed");
   });
 
-  it("status=failed → manifest 写 failed", async () => {
+  it("status=closed + gc → manifest 写 closed", async () => {
     const record = makeMinimalRecord({ id: "rec-failed" });
-    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "failed");
+    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", "gc");
 
     const manifest = await manifestStore.readManifest("rec-failed");
-    expect(manifest?.status).toBe("failed");
+    expect(manifest?.status).toBe("closed");
   });
 
   it("manifest write 抛错时 cleanup-first 顺序仍执行（Step 3 before Step 4 throw）", async () => {
@@ -148,7 +147,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
 
     // ── 核心 claim 1：不抛错（cleanup-first → manifest write 失败不 throw）──
     await expect(
-      doFinalizeRecord(deps, record, makeMinimalResult(), "done"),
+      doFinalizeRecord(deps, record, makeMinimalResult(), "closed"),
     ).resolves.toBeUndefined();
 
     // ── 核心 claim 2：Step 3 cleanup 先执行 —— finalized marker 真实写入 ──
@@ -158,7 +157,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
 
     // ── 核心 claim 4：pending-notifications 注销仍触发（emitUnregister）──
-    expect(deps.emitUnregister).toHaveBeenCalledWith("rec-cleanup-first", "done");
+    expect(deps.emitUnregister).toHaveBeenCalledWith("rec-cleanup-first", "closed");
 
     // ── 核心 claim 5：manifest 写失败被 logger.error 记录（含 record id + error）──
     expect(loggerMock.error).toHaveBeenCalledWith(expect.stringContaining("manifest 写入失败"));
@@ -184,3 +183,160 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     loggerMock.error.mockClear();
   });
 });
+
+// ============================================================
+// doFinalizeRoundToIdle — chatMode 轮次完成进 idle（M2-A）
+// ============================================================
+
+describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () => {
+  let tmpDir: string;
+  let manifestStore: ManifestStore;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "finalize-idle-test-"));
+    manifestStore = new ManifestStore(tmpDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  /** 构造 FinalizeDeps：worktreeManager.cleanup / store.archive 为 vi.fn 以断言「不调」。 */
+  function makeDeps() {
+    return {
+      manifestStore,
+      worktreeManager: { cleanup: vi.fn(), collectPatch: vi.fn() } as never,
+      store: { archive: vi.fn() } as never,
+      modelService: {} as never,
+      pi: { appendEntry: vi.fn() } as never,
+      emitUnregister: vi.fn(),
+    };
+  }
+
+  it("record 带 sessionFile → 删 .alive + record.status=running + round 0→1", async () => {
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+    // 预写 .alive marker（验证 doFinalizeRoundToIdle 删除它——进程已回收）
+    fs.writeFileSync(
+      `${sessionFile}.alive`,
+      `${JSON.stringify({ pid: 99999, id: "rec-idle", startedAt: 1000 })}\n`,
+      "utf-8",
+    );
+    const record = makeMinimalRecord({ id: "rec-idle", sessionFile, chatMode: true, round: 0 });
+    // tryTransition 已把 status 设为 done，模拟 runAndFinalize 调用前的状态
+    record.status = "closed";
+
+    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+
+    // 状态机（v4 B-1：旧 idle 折入 running，finalizeRoundToIdle 设 running）
+    expect(record.status).toBe("running");
+    expect(record.round).toBe(1);
+    // .alive marker 被删（进程已 SIGTERM 回收）
+    expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
+  });
+
+  it("record.round 已为 N → round 变 N+1", async () => {
+    const record = makeMinimalRecord({ id: "rec-round", round: 3 });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+    expect(record.round).toBe(4);
+    expect(record.status).toBe("running");
+  });
+
+  it("不调 store.archive（record 留内存，getMutable 仍可查）", async () => {
+    const deps = makeDeps();
+    const record = makeMinimalRecord({ id: "rec-noarchive" });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
+    expect(deps.store.archive).not.toHaveBeenCalled();
+  });
+
+  it("不 cleanup worktree（即使 record 带 worktreeHandle——保留对话模式工作目录）", async () => {
+    const deps = makeDeps();
+    const record = makeMinimalRecord({
+      id: "rec-noworktree",
+      worktreeHandle: { path: "/tmp/x", branch: "b", baseCommit: "c", mainCwd: "/tmp" } as never,
+    });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
+    expect(deps.worktreeManager.cleanup).not.toHaveBeenCalled();
+  });
+
+  it("emitUnregister 被调（status=running，进程已死从 pending 活跃差集移除）", async () => {
+    const deps = makeDeps();
+    const record = makeMinimalRecord({ id: "rec-emit" });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
+    expect(deps.emitUnregister).toHaveBeenCalledWith("rec-emit", "running");
+  });
+
+  it("不调 completeRecord：record 不冻结（endedAt / agentResult 仍 undefined）", async () => {
+    const record = makeMinimalRecord({ id: "rec-nofreeze" });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+    expect(record.endedAt).toBeUndefined();
+    expect(record.agentResult).toBeUndefined();
+  });
+
+  it("不写 manifest（idle 非终态，manifest 是终态诊断辅助）", async () => {
+    const record = makeMinimalRecord({ id: "rec-nomanifest" });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+    const manifest = await manifestStore.readManifest("rec-nomanifest");
+    expect(manifest).toBeNull();
+  });
+
+  it("MF-2: record.result 设为 result.text（否则 notifier idle 回复恒为 (empty)，G1/G2 不成立）", async () => {
+    const record = makeMinimalRecord({ id: "rec-result" });
+    record.status = "closed";
+    const result = makeMinimalResult();
+    result.text = "review done, found 3 issues";
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // MF-2：record.result 被 result.text 填充，notifier idle 分支读取后携带回复正文
+    expect(record.result).toBe("review done, found 3 issues");
+  });
+
+  it("MF-2 兑底：失败轮次 result.text 为空时用 result.error 填 record.result（MF-6 回退 idle 路径）", async () => {
+    const record = makeMinimalRecord({ id: "rec-result-err" });
+    record.status = "closed";
+    const result = makeMinimalResult();
+    result.text = "";
+    result.success = false;
+    result.error = "spawn timeout";
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // 失败轮次的 notify 需可读：result.text 空 → 兑底用 error
+    expect(record.result).toBe("round did not complete: spawn timeout");
+  });
+
+  it("C1TC10: chatMode 空增量轮占位——record.result 固定 (no output this round)，不含上一轮文本（D5）", async () => {
+    const record = makeMinimalRecord({ id: "rec-increment-empty", chatMode: true });
+    record.status = "closed";
+    // 预置上一轮通知文本（模拟增量语义前的 record.result 残留）
+    record.result = "PREV-ROUND-TEXT";
+    const result = makeMinimalResult();
+    result.text = "";
+    result.success = true;
+    result.error = undefined;
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // 空增量轮通知不含上一轮文本：沿用旧值会让父 agent 误读为原样重复回复（D5 判定）
+    expect(record.result).toBe("(no output this round)");
+    expect(record.result).not.toContain("PREV-ROUND-TEXT");
+  });
+
+  it("C1TC11: 非 chatMode 空文本沿用旧值——one-shot 空文本完成 record.result 保持 undefined（G2/G4）", async () => {
+    const record = makeMinimalRecord({ id: "rec-oneshot-empty", chatMode: false });
+    record.status = "closed";
+    // one-shot 成功空文本完成路径（collectResult getFullText 返回 ""、success=true）：
+    // result 前值 undefined
+    record.result = undefined;
+    const result = makeMinimalResult();
+    result.text = "";
+    result.success = true;
+    result.error = undefined;
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // 非 chatMode 侧维持现状（第三分支 record.chatMode ? 占位 : record.result）
+    expect(record.result).toBeUndefined();
+    // notifier buildLlmContent 的 record.result ?? "(empty)" 确定性链保 G4：
+    // 通知文案逐字节产出 "completed. Result:\n(empty)"，不漂移为 "(no output this round)"
+    expect(record.result ?? "(empty)").toBe("(empty)");
+  });
+});