@zhushanwen/subagent-core 0.8.0 → 0.9.0

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

@@ -1,11 +1,16 @@
-// doFinalizeRecord — manifest status 透传测试（M3: 4 态方案）。
+// doFinalizeRecord — manifest status 透传 + [U2a] 终态四件套归口 store 意图原语测试。
 //
 // 验证 finalize-record.ts 的 status 映射：done→completed, failed→failed, cancelled→cancelled
 // （cancelled 不再归并 failed）。crashed 不进 finalize 入参（TS 签名锁定 done/failed/cancelled）。
 //
-// 测试策略：record 不带 sessionFile/worktreeHandle,跳过 Step 0 (collectPatch) 和 Step 3
-// (finalized/tombstone/aliveMarker/worktree cleanup) 的文件操作,聚焦 Step 4 writeManifest
-// 的 status 产出。FinalizeDeps 用 stub 注入（manifestStore 为真实实例,指向 tmpDir）。
+// [U2a/B1] 终态持久化四件套（.state/binding/archive/manifest/.alive 删）归口
+// store.markFinalized / markCancelled——测试面相应切换为真实 RecordStore 承载
+// （manifestDir 接线第 4 构造参数 → 终态 manifest writeSync 同步落盘，D8 v7）；
+// manifest 写失败路径走缺省降级（manifestStore 异步 + mock 注入 throw）。
+// [B5] doFinalizeRoundToIdle 簿记归口 store.markRoundIdle：record 须先 register 进
+// store 内存（markRoundIdle 按 id 查内存），轮终 `.alive` 保留（D3a 跨轮延续）。
+//
+// FinalizeDeps 其余 stub 注入（manifestStore 为真实实例,指向 tmpDir）。
 
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -24,8 +29,23 @@ vi.mock("../../core/logger.ts", () => ({
   getLogger: () => loggerMock,
 }));
 
+// [B1] state-marker 写面 mock（默认透传真实实现）：终态写失败（重试耗尽返回 false）
+// 用例经 vi.mocked(writeFinalizedState).mockReturnValueOnce(false) 注入——绕开真实
+// 重试 3 次 ×100ms 指数退避的墙钟等待。
+vi.mock("../state-marker.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../state-marker.ts")>();
+  return {
+    ...actual,
+    writeFinalizedState: vi.fn(actual.writeFinalizedState),
+    writeCancelledState: vi.fn(actual.writeCancelledState),
+  };
+});
+
+import { writeFinalizedState } from "../state-marker.ts";
+
 import { doFinalizeRecord, doFinalizeRoundToIdle } from "../finalize-record.ts";
 import { ManifestStore } from "../manifest-store.ts";
+import { RecordStore } from "../record-store.ts";
 import { getSubagentSessionDir } from "../path-encoding.ts";
 import type { AgentResult, ExecutionRecord, WorktreeHandle } from "../types.ts";
 
@@ -80,14 +100,24 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
-  /** 构造最小 FinalizeDeps：record 无 sessionFile/worktreeHandle,跳过 Step 0/3 文件操作。 */
-  function makeDeps(): Parameters<typeof doFinalizeRecord>[0] {
-    return {
+  /** 构造最小 FinalizeDeps。[U2a/B1] store = 真实 RecordStore（manifestDir 第 4 参数
+   *  接线 → markFinalized/markCancelled 的终态 manifest writeSync 同步落盘）；pi 经
+   *  构造注入（reportRecordTransition/写失败 entry 上报可断言）。
+   *  @param opts.syncManifest false = 不接 manifestDir（manifest 走 manifestStore 异步
+   *  降级——manifest 写失败用例 mock manifestStore.writeManifest 注入 throw 用）。 */
+  function makeDeps(opts: { syncManifest?: boolean } = {}): Parameters<typeof doFinalizeRecord>[0] {
+    const pi = { appendEntry: vi.fn() };
+    const store = new RecordStore(
+      tmpDir,
       manifestStore,
+      pi,
+      opts.syncManifest === false ? undefined : tmpDir,
+    );
+    return {
       worktreeManager: {},
-      store: { archive: vi.fn(), reportRecordTransition: vi.fn() },
+      store,
       modelService: {},
-      pi: { appendEntry: vi.fn() },
+      pi,
       emitUnregister: vi.fn(),
     } as unknown as Parameters<typeof doFinalizeRecord>[0];
   }
@@ -118,9 +148,27 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     expect(manifest?.status).toBe("closed");
   });
 
-  it("manifest write 抛错时 cleanup-first 顺序仍执行（Step 3 before Step 4 throw）", async () => {
-    // record 带 sessionFile 让 Step 3 finalized/aliveMarker 走真实路径；
-    // 不设 worktreeHandle → Step 0 (collectPatch) 和 Step 3 worktree cleanup 都跳过。
+  it("[M2 Gate B] closedReason 随 manifest 持久化（manifest 源快照三分流唯一依据）", async () => {
+    // 曾不携带 closedReason：sessionFile 未回填 / sidecar 缺席形态下，重启后 manifest
+    // 源重建的快照丢死因，endedMessageGuard 把 user-close/cancelled 误分流进
+    // 「reconnectable/fork-from」分支。
+    for (const closedReason of ["user-close", "cancelled", "parent-shutdown", "gc"] as const) {
+      const id = `rec-reason-${closedReason}`;
+      await doFinalizeRecord(makeDeps(), makeMinimalRecord({ id }), makeMinimalResult(), "closed", closedReason);
+      const manifest = await manifestStore.readManifest(id);
+      expect(manifest?.status).toBe("closed");
+      expect(manifest?.closedReason).toBe(closedReason);
+    }
+  });
+
+  it("manifest write 抛错时 cleanup-first 顺序仍执行（终态原语内 .state 先于 manifest）", async () => {
+    // record 带 sessionFile 让终态原语走真实 .state/.alive 路径；
+    // 不设 worktreeHandle → Step 0 (collectPatch) 和 worktree cleanup 都跳过。
+    // [U2a] manifest 写失败经 store 内部 fire-and-forget catch（record-store
+    // reportManifestWriteFailure：logger.error + subagent:manifest-write-failed entry），
+    // 不 throw 不跳过编排层后续步骤——对齐 [Critical #1]（manifest 是反查索引非正确性
+    // 依赖）。走异步降级（syncManifest:false——同步 writeAtomicFileSync 路径不经
+    // manifestStore.writeManifest，mock 无法注入）。
     const sessionFile = path.join(tmpDir, "session.jsonl");
     const record = makeMinimalRecord({ id: "rec-cleanup-first", sessionFile });
 
@@ -133,33 +181,35 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     );
 
     // mock writeManifest 抛错（模拟 disk full）。在 mock 内捕获「writeManifest 被调用时
-    // finalized marker 是否已存在」——这是 cleanup-first 顺序的关键断言：若有人把
-    // manifest write 前移到 cleanup 之前，本标志会是 false（[Critical #1] 反例）。
+    // finalized marker 是否已存在」——这是终态原语内部写序的关键断言：D8 v7 要求
+    // `.state` writeSync 先、manifest 后（若有人反转写序，本标志会是 false）。
     const finalizedBeforeManifestWrite = { value: false };
     vi.spyOn(manifestStore, "writeManifest").mockImplementation(async () => {
-      finalizedBeforeManifestWrite.value = fs.existsSync(`${sessionFile}.finalized`);
+      finalizedBeforeManifestWrite.value = fs.existsSync(`${sessionFile}.state`);
       throw new Error("disk full");
     });
     loggerMock.error.mockClear();
 
-    const deps = makeDeps();
+    const deps = makeDeps({ syncManifest: false });
 
-    // ── 核心 claim 1：不抛错（cleanup-first → manifest write 失败不 throw）──
+    // ── 核心 claim 1：不抛错（manifest 写失败在 store 内部被吞，不 throw）──
     await expect(
       doFinalizeRecord(deps, record, makeMinimalResult(), "closed"),
     ).resolves.toBeUndefined();
 
-    // ── 核心 claim 2：Step 3 cleanup 先执行 —— finalized marker 真实写入 ──
-    expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+    // ── 核心 claim 2：终态权威 .state 真实写入 ──
+    expect(fs.existsSync(`${sessionFile}.state`)).toBe(true);
 
-    // ── 核心 claim 3：Step 3 aliveMarker 被移除（预写的 .alive 不再存在）──
+    // ── 核心 claim 3：.alive 被移除（release 出口①——预写的 .alive 不再存在）──
     expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
 
     // ── 核心 claim 4：pending-notifications 注销仍触发（emitUnregister）──
     expect(deps.emitUnregister).toHaveBeenCalledWith("rec-cleanup-first", "closed");
 
-    // ── 核心 claim 5：manifest 写失败被 logger.error 记录（含 record id + error）──
-    expect(loggerMock.error).toHaveBeenCalledWith(expect.stringContaining("manifest 写入失败"));
+    // ── 核心 claim 5：manifest 写失败被 logger.error 记录（store 内 reportManifestWriteFailure）──
+    await vi.waitFor(() => {
+      expect(loggerMock.error).toHaveBeenCalledWith(expect.stringContaining("manifest write failed"));
+    });
     const errMsg = loggerMock.error.mock.calls[0]?.[0];
     expect(errMsg).toContain("rec-cleanup-first");
     expect(errMsg).toContain("disk full");
@@ -173,12 +223,57 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     // ── 核心 claim 7：manifest 实际未写入（writeManifest 抛错被吞咽）──
     expect(await manifestStore.readManifest("rec-cleanup-first")).toBeNull();
 
-    // ── 核心 claim 8：[Critical #1] cleanup 在 manifest 写之前 —— 顺序锁定 ──
-    // 若有人把 manifest write 前移到 cleanup 之前，本标志会是 false（mock 捕获时刻
-    // .finalized 尚未被 Step 3 写入），保护 Critical #1 时序不变量。
+    // ── 核心 claim 8：[D8 v7] 终态原语内部写序 —— .state 先于 manifest ──
+    // 若有人把 manifest 写前移到 .state 之前，mock 捕获时刻 .state 尚未写入，
+    // 本标志会是 false（D8 写序不变量：终态权威优先落）。
     expect(finalizedBeforeManifestWrite.value).toBe(true);
 
     // 清理 mock 调用记录防污染
+    vi.restoreAllMocks();
+    loggerMock.error.mockClear();
+  });
+
+  it("[B1/§3.4] markFinalized 返回 false（.state 重试耗尽）→ 响亮 entry 上报 + 零持久化副作用 + cleanup 编排不跳过", async () => {
+    // 终态写失败（磁盘满/权限）语义：record 留 running（磁盘无终态位、不 archive、
+    // 不删 .alive），GUI 通知面腿 = subagent:state-write-failed entry（日志 error 腿
+    // 由 state-marker/store 层完成，此处断言编排层接线）；worktree cleanup 等
+    // 副作用继续（幂等，不可被写失败跳过——否则 worktree 泄漏）。
+    vi.mocked(writeFinalizedState).mockReturnValueOnce(false);
+    const sessionFile = path.join(tmpDir, "session-fail.jsonl");
+    fs.writeFileSync(sessionFile, "{}\n", "utf-8");
+    fs.writeFileSync(
+      `${sessionFile}.alive`,
+      `${JSON.stringify({ pid: process.pid, id: "rec-write-fail", startedAt: 1000 })}\n`,
+      "utf-8",
+    );
+    const record = makeMinimalRecord({ id: "rec-write-fail", sessionFile });
+    const deps = makeDeps();
+    const cleanup = vi.fn().mockResolvedValue(undefined);
+    (deps as { worktreeManager: unknown }).worktreeManager = { cleanup };
+    // 「record 留 running」口径（U1 偏差 5）= 磁盘面（无 .state）+ 不 archive：
+    // record 未 register 进内存（doFinalizeRecord 不 register），未 archive 以 spy 钉。
+    const archiveSpy = vi.spyOn(deps.store as RecordStore, "archive");
+
+    await expect(
+      doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "gc"),
+    ).resolves.toBeUndefined();
+
+    // 响亮 entry 上报（§3.4 GUI 通知面——U1 偏差 6 的接线点）
+    expect(deps.pi!.appendEntry).toHaveBeenCalledWith(
+      "subagent:state-write-failed",
+      expect.objectContaining({ id: "rec-write-fail", status: "closed", closedReason: "gc" }),
+    );
+    expect(loggerMock.error).toHaveBeenCalledWith(
+      expect.stringContaining("terminal state write failed"),
+    );
+    // 零持久化副作用（D8 失败语义）：无 .state / 无 manifest / .alive 未删 / 未 archive
+    expect(fs.existsSync(`${sessionFile}.state`)).toBe(false);
+    expect(await manifestStore.readManifest("rec-write-fail")).toBeNull();
+    expect(fs.existsSync(`${sessionFile}.alive`)).toBe(true);
+    expect(archiveSpy).not.toHaveBeenCalled();
+    // 副作用编排继续：worktree cleanup / emitUnregister 不被写失败跳过
+    expect(cleanup).toHaveBeenCalledTimes(0); // 本用例 record 无 worktreeHandle
+    expect(deps.emitUnregister).toHaveBeenCalledWith("rec-write-fail", "closed");
     loggerMock.error.mockClear();
   });
 
@@ -213,7 +308,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
       return sessionFile;
     }
 
-    it("sessionFile 缺失 + 反查命中 → .finalized 落盘 + .alive 清理 + record/manifest 回填", async () => {
+    it("sessionFile 缺失 + 反查命中 → .state 落盘 + .alive 清理 + record/manifest 回填", async () => {
       const sessionFile = writeSessionFileWithIdentity("20260901T12000000_ps9.jsonl", "rec-ps9");
       // 预写 .alive 残留（模拟 running 期崩溃恢复窗口的 marker）
       fs.writeFileSync(
@@ -228,9 +323,11 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
 
       // 反查回填 record.sessionFile
       expect(record.sessionFile).toBe(sessionFile);
-      // 终态原因持久化不再丢失（closedReason gc 写入 .finalized 内容）
-      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
-      expect(fs.readFileSync(`${sessionFile}.finalized`, "utf-8")).toBe("gc");
+      // 终态原因持久化不再丢失（closedReason gc 写入 .state 的 reason 字段）
+      expect(JSON.parse(fs.readFileSync(`${sessionFile}.state`, "utf-8"))).toEqual({
+        status: "finalized",
+        reason: "gc",
+      });
       // alive marker 不再残留
       expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
       // manifest 拿到真实 sessionFile（诊断/重建源不再失真）
@@ -238,7 +335,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
       expect(manifest?.sessionFile).toBe(sessionFile);
     });
 
-    it("cancelled + 反查命中 → tombstone 写到反查路径（cancelled 语义不因 sessionFile 缺失丢失）", async () => {
+    it("cancelled + 反查命中 → cancelled 终态写反查路径（语义不因 sessionFile 缺失丢失）", async () => {
       const sessionFile = writeSessionFileWithIdentity("20260901T12000001_ps9c.jsonl", "rec-ps9c");
       const record = makeMinimalRecord({ id: "rec-ps9c", sessionFile: undefined });
       const deps = { ...makeDeps(), sessionDir };
@@ -246,12 +343,12 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
       await doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "cancelled");
 
       expect(record.sessionFile).toBe(sessionFile);
-      expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(true);
-      const tomb = JSON.parse(
-        fs.readFileSync(`${sessionFile}.cancelled`, "utf-8"),
-      ) as { id: string; status: string };
-      expect(tomb.id).toBe("rec-ps9c");
-      expect(tomb.status).toBe("cancelled");
+      const marker = JSON.parse(fs.readFileSync(`${sessionFile}.state`, "utf-8")) as {
+        status: string;
+        endedAt: number;
+      };
+      expect(marker.status).toBe("cancelled");
+      expect(typeof marker.endedAt).toBe("number");
     });
 
     it("反查未命中（目录无 identity 匹配文件）→ 不抛、sessionFile 保持缺失、无 marker（行为退回修复前）", async () => {
@@ -272,14 +369,14 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     });
   });
 
-  // ── Step 3a 判别 wiring：closedReason → tombstone vs finalized（MF-1 fix / v4 B-1）──
+  // ── Step 3a 判别 wiring：closedReason → .state 单一终态 sidecar（L4 合并后）──
   //
-  // record 带 sessionFile 直接命中 writeFinalizedOrTombstone 的核心判别分支：
-  //   cancelled → writeCancelledTombstone（防重建丢失 cancelled 语义）
-  //   其余 reason → writeFinalized（真实 reason 进 sidecar 内容，磁盘重建还原 closedReason）
-  // 两路 sidecar 互斥（BC-4）：断言「写了哪个 + 没写哪个」双向锁定。
-  describe("writeFinalizedOrTombstone 判别 wiring（closedReason → tombstone vs finalized）", () => {
-    it("closedReason=cancelled → tombstone sidecar 携带 id/status/agent/startedAt/endedAt 且不写 .finalized", async () => {
+  // record 带 sessionFile 直接命中 writeTerminalState 的判别分支：
+  //   cancelled → .state {status:"cancelled", endedAt}（重建还原 cancelled 语义 + 精确结束时间）
+  //   其余 reason → .state {status:"finalized", reason}（真实 reason 进 sidecar，重建还原 closedReason）
+  // 单文件单 status 字段 → 互斥构造性成立；兼容期旧名（.finalized/.cancelled）不再被写。
+  describe("writeTerminalState 判别 wiring（closedReason → .state status）", () => {
+    it("closedReason=cancelled → .state 携带 status/endedAt 且不写旧名 sidecar", async () => {
       const sessionFile = path.join(tmpDir, "session.jsonl");
       const record = makeMinimalRecord({
         id: "rec-wire-cancelled",
@@ -290,42 +387,41 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
 
       await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", "cancelled");
 
-      // tombstone 写出且内容为完整 CancelledTombstone（经 readCancelledTombstone 形态校验的
-      // 字段逐项断言，不用 objectContaining 放宽——重建链路靠这些字段还原）
-      expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(true);
-      const tomb = JSON.parse(fs.readFileSync(`${sessionFile}.cancelled`, "utf-8")) as {
-        id: string;
+      // .state 写出且内容为终态 marker（字段逐项断言，不用 objectContaining 放宽——
+      // 重建链路靠这些字段还原）
+      expect(fs.existsSync(`${sessionFile}.state`)).toBe(true);
+      const marker = JSON.parse(fs.readFileSync(`${sessionFile}.state`, "utf-8")) as {
         status: string;
-        agent: string;
-        startedAt: number;
         endedAt: number;
       };
-      expect(tomb.id).toBe("rec-wire-cancelled");
-      expect(tomb.status).toBe("cancelled");
-      expect(tomb.agent).toBe("worker");
-      expect(tomb.startedAt).toBe(1000);
+      expect(marker.status).toBe("cancelled");
       // endedAt 来自 completeRecord 冻结后的 record.endedAt（Step 1 先于 Step 3a，
-      // record 预设的 endedAt 会被冻结值覆盖）——tombstone 携带真实收尾时间戳
-      expect(tomb.endedAt).toBe(record.endedAt);
-      expect(typeof tomb.endedAt).toBe("number");
-      // 互斥：cancelled 路径绝不写 finalized（否则重建判「正常结束」，cancelled 语义丢失）
+      // record 预设的 endedAt 会被冻结值覆盖）——sidecar 携带真实收尾时间戳
+      expect(marker.endedAt).toBe(record.endedAt);
+      expect(typeof marker.endedAt).toBe("number");
+      // 兼容期旧名不再被写（写侧单点收敛）
       expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(false);
+      expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(false);
     });
 
     it.each(["user-close", "gc"] as const)(
-      "closedReason=%s → .finalized 内容携带真实 reason 且不写 tombstone",
+      "closedReason=%s → .state 内容携带真实 reason 且不写旧名 sidecar",
       async (reason) => {
         const sessionFile = path.join(tmpDir, "session.jsonl");
         const record = makeMinimalRecord({ id: `rec-wire-${reason}`, sessionFile });
 
         await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", reason);
 
-        // finalized sidecar 写出且内容 = 真实 reason（磁盘重建用它还原 closedReason，
+        // .state 写出且 reason = 真实关因（磁盘重建用它还原 closedReason，
         // 不再一律硬编码 gc）
-        expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
-        expect(fs.readFileSync(`${sessionFile}.finalized`, "utf-8")).toBe(reason);
-        // 互斥：非 cancelled 路径不写 tombstone
+        expect(fs.existsSync(`${sessionFile}.state`)).toBe(true);
+        expect(JSON.parse(fs.readFileSync(`${sessionFile}.state`, "utf-8"))).toEqual({
+          status: "finalized",
+          reason,
+        });
+        // 兼容期旧名不再被写
         expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(false);
+        expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(false);
       },
     );
   });
@@ -419,7 +515,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
       ).resolves.toBeUndefined();
 
       // Step 0 失败不影响后续步骤：finalized sidecar 与 manifest 照常落地
-      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+      expect(fs.existsSync(`${sessionFile}.state`)).toBe(true);
       const manifest = await manifestStore.readManifest("rec-patch-err");
       expect(manifest?.status).toBe("closed");
       expect(deps.worktreeManager.cleanup).toHaveBeenCalledTimes(1);
@@ -446,165 +542,237 @@ describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () =>
     fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
-  /** 构造 FinalizeDeps：worktreeManager.cleanup / store.archive 为 vi.fn 以断言「不调」。 */
-  function makeDeps(): Parameters<typeof doFinalizeRoundToIdle>[0] {
-    return {
-      manifestStore,
+  /** 构造 FinalizeDeps + 真实 RecordStore（markRoundIdle 按 id 查内存——record 须先
+   *  register；返回 store 供 register/断言用）。worktreeManager.cleanup / store.archive
+   *  为 spy 以断言「不调」。 */
+  function makeDeps(): { deps: Parameters<typeof doFinalizeRoundToIdle>[0]; store: RecordStore } {
+    const pi = { appendEntry: vi.fn() };
+    const store = new RecordStore(tmpDir, manifestStore, pi, tmpDir);
+    const deps = {
       worktreeManager: { cleanup: vi.fn(), collectPatch: vi.fn() },
-      store: { archive: vi.fn(), reportRecordTransition: vi.fn() },
+      store,
       modelService: {},
-      pi: { appendEntry: vi.fn() },
+      pi,
       emitUnregister: vi.fn(),
     } as unknown as Parameters<typeof doFinalizeRoundToIdle>[0];
+    return { deps, store };
   }
 
-  it("record 带 sessionFile → 删 .alive + record.status=running + round 0→1", async () => {
+  it("[B5/D3a] record 带 sessionFile → 轮终后 .alive marker 仍在（写权声明跨轮延续）+ record.status=running + round 0→1", async () => {
     const sessionFile = path.join(tmpDir, "session.jsonl");
-    // 预写 .alive marker（验证 doFinalizeRoundToIdle 删除它——进程已回收）
+    // 预写 .alive marker（[B5] 行为变化锚点：轮终**保留** marker——release = 终态原语
+    // 或 idle-GC 归档两出口，轮终 record 仍 resumable 随时续聊 spawn 写同一
+    // sessionFile，删则轮后跨进程防御空窗，D3a）
     fs.writeFileSync(
       `${sessionFile}.alive`,
       `${JSON.stringify({ pid: 99999, id: "rec-idle", startedAt: 1000 })}\n`,
       "utf-8",
     );
+    const { deps, store } = makeDeps();
     const record = makeMinimalRecord({ id: "rec-idle", sessionFile, chatMode: true, round: 0 });
     // tryTransition 已把 status 设为 done，模拟 runAndFinalize 调用前的状态
     record.status = "closed";
+    store.register(record);
 
-    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "done" });
 
-    // 状态机（v4 B-1：旧 idle 折入 running，finalizeRoundToIdle 设 running）
+    // 状态机（v4 B-1：旧 idle 折入 running，markRoundIdle 设 running）
     expect(record.status).toBe("running");
     expect(record.round).toBe(1);
-    // .alive marker 被删（进程已 SIGTERM 回收）
-    expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
+    // [B5] .alive marker 轮终保留（旧行为「删 marker」随 D3a 跨轮延续退役）
+    expect(fs.existsSync(`${sessionFile}.alive`)).toBe(true);
   });
 
-  it("W16: 轮终上报 reportRecordTransition（record-store 类外恢复写点迁移落 entry）", async () => {
-    const deps = makeDeps();
+  it("[A3] 终态簿记已冻结（endedAt 已设 = completeRecord 已跑）→ store 内硬断言 throw（S7：禁复活已终态化 record）", async () => {
+    const { deps, store } = makeDeps();
+    const record = makeMinimalRecord({ id: "rec-frozen", chatMode: true });
+    // closeChatIdle / disposeAllRecords 等完整终态化路径的产物：completeRecord 已跑
+    //（endedAt 冻结）+ status=closed。迟到的轮末分流调用必须被断言拒绝。
+    record.status = "closed";
+    record.closedReason = "user-close";
+    record.endedAt = 12345;
+    store.register(record);
+    const transitionSpy = vi.spyOn(store, "reportRecordTransition");
+
+    await expect(doFinalizeRoundToIdle(deps, record, { kind: "success", content: "late" })).rejects.toThrow(
+      /terminal bookkeeping already frozen/,
+    );
+    // 断言先于任何簿记副作用：round 不推进、状态不回滚、无迁移上报
+    expect(record.round).toBeUndefined();
+    expect(record.status).toBe("closed");
+    expect(transitionSpy).not.toHaveBeenCalled();
+    expect(deps.emitUnregister).not.toHaveBeenCalled();
+  });
+
+  it("W16: 轮终上报 reportRecordTransition（markRoundIdle 簿记⑨，entry 携带新轮计数）", async () => {
+    const { deps, store } = makeDeps();
+    const transitionSpy = vi.spyOn(store, "reportRecordTransition");
     const record = makeMinimalRecord({ id: "rec-report", chatMode: true, round: 2 });
     record.status = "closed";
-    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
-    expect(deps.store.reportRecordTransition).toHaveBeenCalledTimes(1);
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "done" });
+    expect(transitionSpy).toHaveBeenCalledTimes(1);
     // 上报发生在 round 推进之后（entry 携带新轮计数，重建源不滞后）
     expect(record.round).toBe(3);
     expect(record.status).toBe("running");
   });
 
   it("record.round 已为 N → round 变 N+1", async () => {
+    const { deps, store } = makeDeps();
     const record = makeMinimalRecord({ id: "rec-round", round: 3 });
     record.status = "closed";
-    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "done" });
     expect(record.round).toBe(4);
     expect(record.status).toBe("running");
   });
 
   it("不调 store.archive（record 留内存，getMutable 仍可查）", async () => {
-    const deps = makeDeps();
+    const { deps, store } = makeDeps();
+    const archiveSpy = vi.spyOn(store, "archive");
     const record = makeMinimalRecord({ id: "rec-noarchive" });
     record.status = "closed";
-    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
-    expect(deps.store.archive).not.toHaveBeenCalled();
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "done" });
+    expect(archiveSpy).not.toHaveBeenCalled();
+    expect(store.getMutable("rec-noarchive")).toBeDefined();
   });
 
   it("不 cleanup worktree（即使 record 带 worktreeHandle——保留对话模式工作目录）", async () => {
-    const deps = makeDeps();
+    const { deps, store } = 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());
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "done" });
     expect(deps.worktreeManager.cleanup).not.toHaveBeenCalled();
   });
 
-  it("emitUnregister 被调（status=running，进程已死从 pending 活跃差集移除）", async () => {
-    const deps = makeDeps();
+  it("轮终注销经 store 簿记⑧发射（setPendingUnregister 注入闭包，status=running）", async () => {
+    const { deps, store } = makeDeps();
+    // [B5/U5 收口] 注销由 store.markRoundIdle 簿记⑧统一发射（SubagentService 构造点
+    // 注入 emitPendingUnregister；调用方薄壳不再双轨重复发）。
+    const unregisterSpy = vi.fn();
+    store.setPendingUnregister(unregisterSpy);
     const record = makeMinimalRecord({ id: "rec-emit" });
     record.status = "closed";
-    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
-    expect(deps.emitUnregister).toHaveBeenCalledWith("rec-emit", "running");
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "done" });
+    expect(unregisterSpy).toHaveBeenCalledWith("rec-emit", "running");
   });
 
   it("不调 completeRecord：record 不冻结（endedAt / agentResult 仍 undefined）", async () => {
+    const { deps, store } = makeDeps();
     const record = makeMinimalRecord({ id: "rec-nofreeze" });
     record.status = "closed";
-    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "done" });
     expect(record.endedAt).toBeUndefined();
     expect(record.agentResult).toBeUndefined();
   });
 
   it("不写 manifest（idle 非终态，manifest 是终态诊断辅助）", async () => {
+    const { deps, store } = makeDeps();
     const record = makeMinimalRecord({ id: "rec-nomanifest" });
     record.status = "closed";
-    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "done" });
     const manifest = await manifestStore.readManifest("rec-nomanifest");
     expect(manifest).toBeNull();
   });
 
-  it("MF-2: record.result 设为 result.text（否则 notifier idle 回复恒为 (empty)，G1/G2 不成立）", async () => {
+  it("MF-2: record.result 设为轮终 content（否则 notifier idle 回复恒为 (empty)，G1/G2 不成立）", async () => {
+    const { deps, store } = makeDeps();
     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 分支读取后携带回复正文
+    store.register(record);
+    // [H1 U2 / D7] outcome 入参适配：成功轮正文 = content
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "review done, found 3 issues" });
+    // MF-2：record.result 被 content 填充，notifier idle 分支读取后携带回复正文
     expect(record.result).toBe("review done, found 3 issues");
   });
 
-  it("MF-2 兑底：失败轮次 result.text 为空时用 result.error 填 record.result（MF-6 回退 idle 路径）", async () => {
+  it("MF-2 兑底：失败轮次（无前值）record.result 用失败摘要填充（D7 outcome 入参：前值 ?? 失败摘要）", async () => {
+    const { deps, store } = makeDeps();
     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
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "failed", reason: "spawn timeout" });
+    // 失败轮次的 notify 需可读：无前值可保 → 兜底失败摘要
     expect(record.result).toBe("round did not complete: spawn timeout");
   });
 
-  it("T2-③/LC-1: 失败轮 text 与 error 并存时 error 优先——collectResult 恒带 getFullText 正文，text 优先会覆盖恢复指引（S-B-1 首轮 settled watchdog 实测）", async () => {
+  it("D7 失败轮前值保留：有最后成功正文时 result 不被失败摘要覆盖（GUI record 视图不被失败污染）+ lastError 写失败原因", async () => {
+    const { deps, store } = makeDeps();
+    const record = makeMinimalRecord({ id: "rec-fail-keep-prev", chatMode: true });
+    record.status = "closed";
+    record.result = "last successful round output"; // 前值（有最后成功正文则保留）
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "failed", reason: "watchdog kill" });
+    // 前值 ?? 失败摘要 → 前值保留；失败原因归 lastError 字段与失败通知（可达性迁移）
+    expect(record.result).toBe("last successful round output");
+    expect(record.lastError).toBe("watchdog kill");
+  });
+
+  it("D7 失败轮 lastError 写失败原因（排障面——renderer 在 result 非 undefined 时不显示 error，无视觉影响）", async () => {
+    const { deps, store } = makeDeps();
+    const record = makeMinimalRecord({ id: "rec-fail-last-error", chatMode: true });
+    record.status = "closed";
+    record.lastError = undefined;
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "failed", reason: "engine_round_crashed: x" });
+    expect(record.lastError).toBe("engine_round_crashed: x");
+    expect(record.result).toBe("round did not complete: engine_round_crashed: x");
+  });
+
+  it("D7 成功轮 lastError 不混入正文：空 content 成功轮兜底 '(no output this round)'（旧 lastError 混入形态退役）", async () => {
+    const { deps, store } = makeDeps();
+    const record = makeMinimalRecord({ id: "rec-success-no-mix", chatMode: true });
+    record.status = "closed";
+    record.lastError = "stale error from previous round";
+    store.register(record);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "" });
+    expect(record.result).toBe("(no output this round)");
+    expect(record.result).not.toContain("stale error");
+  });
+
+  it("T2-③/LC-1: 失败轮 record.result 写失败摘要、不回显轮内旧正文（D7：可达性从 result 字段迁移到通知 outcome——失败通知由 Continuation 独立承载失败原因 + 恢复指引）", async () => {
+    const { deps, store } = makeDeps();
     const record = makeMinimalRecord({ id: "rec-result-err-text", chatMode: true });
     record.status = "closed";
-    const result = makeMinimalResult();
-    // runSpawn settledWatchdogFired 分支的 collectResult 形态：正文（T1 回补采集）与
-    // watchdog 错误并存
-    result.text = "DONE";
-    result.success = false;
-    result.error =
+    store.register(record);
+    const failureReason =
       "subagent did not reach agent_settled within 10 min (settled watchdog); the process was terminated to bound the wait. Recovery: check state with subagents action:'list', then re-send your message to continue.";
-    await doFinalizeRoundToIdle(makeDeps(), record, result);
-    // 失败的 record.result（= 通知正文）必须携带失败原因与恢复指引，不得回显轮内旧正文
-    expect(record.result).toBe(`round did not complete: ${result.error}`);
+    await doFinalizeRoundToIdle(deps, record, { kind: "failed", reason: failureReason });
+    // 失败轮 record.result 携带失败摘要（前值 undefined → 失败摘要），不构成成功谎报
+    expect(record.result).toBe(`round did not complete: ${failureReason}`);
     expect(record.result).not.toBe("DONE");
   });
 
   it("C1TC10: chatMode 空增量轮占位——record.result 固定 (no output this round)，不含上一轮文本（D5）", async () => {
+    const { deps, store } = makeDeps();
     const record = makeMinimalRecord({ id: "rec-increment-empty", chatMode: true });
     record.status = "closed";
+    store.register(record);
     // 预置上一轮通知文本（模拟增量语义前的 record.result 残留）
     record.result = "PREV-ROUND-TEXT";
-    const result = makeMinimalResult();
-    result.text = "";
-    result.success = true;
-    result.error = undefined;
-    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "" });
     // 空增量轮通知不含上一轮文本：沿用旧值会让父 agent 误读为原样重复回复（D5 判定）
     expect(record.result).toBe("(no output this round)");
     expect(record.result).not.toContain("PREV-ROUND-TEXT");
   });
 
   it("C1TC11 [R2-1]: one-shot 首轮空文本成功完成 → record.result 补占位「(empty)」（非 undefined）", async () => {
+    const { deps, store } = makeDeps();
     const record = makeMinimalRecord({ id: "rec-oneshot-empty", chatMode: false });
     record.status = "closed";
+    store.register(record);
     // 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);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "" });
     // [R2-1] 轮终信号优先：占位非 undefined 是 renderer hasRunning 排除轮终 running 的
     // 判据——保持 undefined 会让完成注入后末位 turn 永久「工作中」
     expect(record.result).toBe("(empty)");
@@ -614,15 +782,13 @@ describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () =>
   });
 
   it("C1TC11b [R2-1]: one-shot 续轮空文本 → 沿用前值（one-shot 无增量语义，不覆盖为占位）", async () => {
+    const { deps, store } = makeDeps();
     const record = makeMinimalRecord({ id: "rec-oneshot-cont", chatMode: false });
     record.status = "closed";
+    store.register(record);
     // 上一轮真实产出（续轮 record.result 前值）
     record.result = "first round output";
-    const result = makeMinimalResult();
-    result.text = "";
-    result.success = true;
-    result.error = undefined;
-    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    await doFinalizeRoundToIdle(deps, record, { kind: "success", content: "" });
     // one-shot record.result = 该 subagent 最终输出：空文本续轮沿用前值，不被 "(empty)" 覆盖
     expect(record.result).toBe("first round output");
   });