@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.0

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

@@ -18,11 +18,12 @@ import * as path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { writeAliveMarker } from "../alive-store.ts";
-import { createRecord } from "../execution-record.ts";
+import { completeRecord, createRecord, tryTransition } from "../execution-record.ts";
 import { writeFinalized } from "../finalized-marker.ts";
 import type { ManifestRecord } from "../manifest-store.ts";
 import { ManifestStore } from "../manifest-store.ts";
 import { getSubagentRecordsDir, getSubagentSessionDir } from "../path-encoding.ts";
+import { SUBAGENT_RECORD_CUSTOM_TYPE } from "../record-entry.ts";
 import type { StatusFilter } from "../record-store.ts";
 import { RecordStore } from "../record-store.ts";
 import { writeCancelledTombstone } from "../tombstone-store.ts";
@@ -37,6 +38,8 @@ function makeRecord(over: Partial<ExecutionRecord> = {}): ExecutionRecord {
     task: "t",
     startedAt: 1000,
     rootSessionId: "sess-current",
+    // 对齐生产 register 路径（subagent-service createRecord：one-shot 显式 false）
+    chatMode: false,
   });
   return { ...base, ...over };
 }
@@ -47,7 +50,7 @@ function makeRecord(over: Partial<ExecutionRecord> = {}): ExecutionRecord {
  */
 function writeSessionJsonl(
   filePath: string,
-  identity: { id: string; agent: string; mode: "sync" | "background"; task: string; startedAt: number; rootSessionId?: string; parentRecordId?: string; depth?: number; lastTs?: number },
+  identity: { id: string; agent: string; mode: "sync" | "background"; task: string; startedAt: number; rootSessionId?: string; parentRecordId?: string; depth?: number; lastTs?: number; chatMode?: boolean },
   assistantText = "result text",
 ): void {
   const lastTs = identity.lastTs ?? identity.startedAt + 1000;
@@ -64,6 +67,7 @@ function writeSessionJsonl(
   if (identity.rootSessionId !== undefined) identityData.rootSessionId = identity.rootSessionId;
   if (identity.parentRecordId !== undefined) identityData.parentRecordId = identity.parentRecordId;
   if (identity.depth !== undefined) identityData.depth = identity.depth;
+  if (identity.chatMode !== undefined) identityData.chatMode = identity.chatMode;
   const identityEntry = JSON.stringify({
     type: "custom",
     id: "id-1",
@@ -89,13 +93,19 @@ function writeSessionJsonl(
 }
 
 describe("RecordStore", () => {
+  let rootDir: string;
   let tmpDir: string;
 
   beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "rs-test-"));
+    // [DS3] 两层布局：tmpDir 深一层（对齐生产 <enc> 段结构），sessions-index.json 落
+    // dirname(tmpDir)=rootDir 内随 afterEach 清理（含 MF-3/S-20 的嵌套 <enc> 段索引）。
+    rootDir = fs.mkdtempSync(path.join(os.tmpdir(), "rs-test-"));
+    tmpDir = path.join(rootDir, "sessions");
+    fs.mkdirSync(tmpDir);
   });
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    // maxRetries：fire-and-forget 的 sessions-index 写可能与删除并发（ENOTEMPTY 竞态）
+    fs.rmSync(rootDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   // ============================================================
@@ -104,7 +114,7 @@ describe("RecordStore", () => {
   describe("archive 立即移除", () => {
     it("archive 后 record 立即从内存移除（不再 linger）", () => {
       const store = new RecordStore(tmpDir);
-      const r = makeRecord({ id: "sync-1", mode: "sync", status: "done" });
+      const r = makeRecord({ id: "sync-1", mode: "sync", status: "closed" });
       store.register(r);
       expect(store.getMutable("sync-1")).toBeDefined();
       store.archive(r);
@@ -113,7 +123,7 @@ describe("RecordStore", () => {
 
     it("background record 同样立即移除（不再 FIFO）", () => {
       const store = new RecordStore(tmpDir);
-      const r = makeRecord({ id: "bg-1", mode: "background", status: "done" });
+      const r = makeRecord({ id: "bg-1", mode: "background", status: "closed" });
       store.register(r);
       store.archive(r);
       expect(store.getMutable("bg-1")).toBeUndefined();
@@ -131,20 +141,25 @@ describe("RecordStore", () => {
       expect(ids).toContain("run-1");
     });
 
-    it("磁盘 session.jsonl 重建的终态 record 出现在结果中（无 sidecar → crashed）", () => {
+    it("磁盘 session.jsonl 重建的 record 出现在结果中（无 sidecar → running, SP-2 跨重启可恢复）", () => {
       const sessionFile = path.join(tmpDir, "2026-01-01-uuid-a.jsonl");
       writeSessionJsonl(sessionFile, {
         id: "bg-1", agent: "worker", mode: "background", task: "do it", startedAt: 5000,
       });
-      // 无 sidecar → 四分支兜底 crashed
+      // 无 sidecar → 四分支兜底 running（v4 B-1：旧 idle 折入 running，SP-2 跨重启可恢复）
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === "bg-1");
       expect(found).toBeDefined();
-      expect(found?.status).toBe("crashed");
+      expect(found?.status).toBe("running");
       expect(found?.agent).toBe("worker");
-      expect(found?.turns).toBe(1);
-      expect(found?.totalTokens).toBe(30);
-      expect(found?.result).toBe("result text");
+      // [perf] 列表是 light（头部 identity，详情字段缺省）——turns/tokens/result 走 getFullRecord 懒加载
+      expect(found?.turns).toBe(0);
+      expect(found?.result).toBeUndefined();
+      const full = store.getFullRecord("bg-1");
+      expect(full?.turns).toBe(1);
+      expect(full?.totalTokens).toBe(30);
+      expect(full?.result).toBe("result text");
+      expect(full?.status).toBe("running"); // 状态矩阵在全量路径同样套用
     });
 
     it("磁盘 session.jsonl + .finalized sidecar → done", () => {
@@ -156,10 +171,10 @@ describe("RecordStore", () => {
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === "bg-2");
       expect(found).toBeDefined();
-      expect(found?.status).toBe("done");
+      expect(found?.status).toBe("closed");
     });
 
-    it("statusFilter='running' 只返回 running（磁盘终态被滤掉）", () => {
+    it("statusFilter='running' 含内存 + 磁盘跨重启 running（v4 B-1：旧 idle 折入 running）", () => {
       const sessionFile = path.join(tmpDir, "2026-01-01-uuid-a.jsonl");
       writeSessionJsonl(sessionFile, {
         id: "bg-1", agent: "worker", mode: "background", task: "do it", startedAt: 5000,
@@ -168,7 +183,8 @@ describe("RecordStore", () => {
       store.register(makeRecord({ id: "run-1", mode: "background", startedAt: 1000 }));
       const filter: StatusFilter = "running";
       const ids = store.collectRecords(100, filter).map((r) => r.id);
-      expect(ids).toEqual(["run-1"]); // 只有内存 running，磁盘 crashed 被滤
+      // 内存 run-1 + 磁盘跨重启 bg-1 都是 running（旧 idle 折入）；startedAt desc → bg-1(5000) 先
+      expect(ids).toEqual(["bg-1", "run-1"]);
     });
 
     it("statusFilter='all'（默认）返回内存 + 磁盘", () => {
@@ -191,7 +207,7 @@ describe("RecordStore", () => {
       const store = new RecordStore(tmpDir);
       store.register(makeRecord({ id: "dup-1", mode: "background", status: "running", startedAt: 5000 }));
       const found = store.collectRecords(100).find((r) => r.id === "dup-1");
-      expect(found?.status).toBe("running"); // 内存 running 覆盖磁盘 crashed
+      expect(found?.status).toBe("running"); // 内存 running 覆盖磁盘 idle（SP-2）
     });
 
     it("[MF-3/S-20] 跨进程组合：子进程（worktree）写入 enc(ROOT) 的深层 record 被 ROOT store 重建，同 rootSessionId 全树可见、他树被排除", () => {
@@ -235,7 +251,7 @@ describe("RecordStore", () => {
   // cancelled tombstone override
   // ============================================================
   describe("cancelled tombstone", () => {
-    it("有 .cancelled sidecar → status override 为 cancelled", () => {
+    it("有 .cancelled sidecar → status override 为 closed + closedReason=cancelled", () => {
       const sessionFile = path.join(tmpDir, "2026-01-01-uuid-a.jsonl");
       writeSessionJsonl(sessionFile, {
         id: "bg-1", agent: "worker", mode: "background", task: "do it", startedAt: 5000,
@@ -245,7 +261,9 @@ describe("RecordStore", () => {
       });
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === "bg-1");
-      expect(found?.status).toBe("cancelled");
+      // v4 B-1：cancelled 折入 closed，closedReason='cancelled' 保留用户取消语义
+      expect(found?.status).toBe("closed");
+      expect(found?.closedReason).toBe("cancelled");
       expect(found?.error).toBe("cancelled by user");
     });
   });
@@ -254,17 +272,19 @@ describe("RecordStore", () => {
   // compareRecords 排序稳定性（内存 running record）
   // ============================================================
   describe("compareRecords 排序", () => {
-    it("status priority（running < crashed）", () => {
+    it("status priority（running < closed）", () => {
       const store = new RecordStore(tmpDir);
-      // 内存 running record vs 磁盘无 sidecar → crashed
+      // 内存 running record
       const running = makeRecord({ id: "run-1", mode: "background", startedAt: 3000, status: "running" });
       store.register(running);
-      // 磁盘 crashed record（无 sidecar → 四分支兜底）
-      writeSessionJsonl(path.join(tmpDir, "a.jsonl"), {
+      // 磁盘 closed record（.finalized sidecar → closed，v4 B-1 统一终态）
+      const doneFile = path.join(tmpDir, "a.jsonl");
+      writeSessionJsonl(doneFile, {
         id: "done-1", agent: "w", mode: "background", task: "t", startedAt: 5000,
       });
+      writeFinalized(doneFile);
       const ids = store.collectRecords(100).map((r) => r.id);
-      expect(ids[0]).toBe("run-1"); // running 排前
+      expect(ids[0]).toBe("run-1"); // running(0) 排在 closed(3) 前
     });
 
     it("同 status 时 startedAt desc（新→旧）", () => {
@@ -275,30 +295,55 @@ describe("RecordStore", () => {
       writeSessionJsonl(path.join(tmpDir, "new.jsonl"), {
         id: "new", agent: "w", mode: "background", task: "t", startedAt: 9000,
       });
-      // 两个都是 crashed（磁盘重建，无 sidecar），按 startedAt desc
+      // 两个都是 running（磁盘重建，无 sidecar → SP-2 兜底 running，旧 idle 折入），按 startedAt desc
       const ids = store.collectRecords(100).map((r) => r.id);
       expect(ids).toEqual(["new", "old"]);
     });
   });
 
+  // ============================================================
+  // running 态 record（M2-A chatMode 续聊；v4 B-1：旧 idle 折入 running）
+  // ============================================================
+  describe("running 态 record（旧 idle 折入，等待续聊）", () => {
+    it("getMutable 能查到 running record（不筛 status，running record 留内存不 archive）", () => {
+      const store = new RecordStore(tmpDir);
+      const r = makeRecord({ id: "idle-1", status: "running" });
+      store.register(r);
+      // running record 不 archive → getMutable 仍可查（续聊定位依赖此）
+      expect(store.getMutable("idle-1")).toBe(r);
+    });
+
+    it("running record 经 collectRecords(statusFilter=all) 可见", () => {
+      const store = new RecordStore(tmpDir);
+      store.register(makeRecord({ id: "idle-2", status: "running" }));
+      const ids = store.collectRecords(100, "all").map((r) => r.id);
+      expect(ids).toContain("idle-2");
+    });
+
+    it("running record 经 collectRecords(statusFilter=running) 可见（v4 B-1：旧 idle 折入 running）", () => {
+      const store = new RecordStore(tmpDir);
+      store.register(makeRecord({ id: "idle-3", status: "running" }));
+      const ids = store.collectRecords(100, "running").map((r) => r.id);
+      expect(ids).toContain("idle-3");
+    });
+  });
+
+
   // ============================================================
   // 重建缓存
   // ============================================================
   describe("重建缓存", () => {
-    it("notifyChange 后缓存失效（新 session.jsonl 可见）", () => {
+    it("新 session.jsonl 无需内存事件即立即可见（[perf] stat 校验取代 notifyChange 整体失效）", () => {
       const store = new RecordStore(tmpDir);
       // 首次 collect：空目录
       expect(store.collectRecords(100)).toHaveLength(0);
-      // 写新 session.jsonl
+      // 写新 session.jsonl（模拟外部进程/子进程写入——不经本进程任何内存事件）
       writeSessionJsonl(path.join(tmpDir, "new.jsonl"), {
         id: "bg-1", agent: "w", mode: "background", task: "t", startedAt: 1000,
       });
-      // 缓存仍命中旧结果（notifyChange 未触发）
-      expect(store.collectRecords(100)).toHaveLength(0);
-      // register 触发 notifyChange → 缓存失效
-      store.register(makeRecord({ id: "trigger", mode: "sync", startedAt: 2000 }));
-      store.archive(makeRecord({ id: "trigger", mode: "sync", startedAt: 2000 }));
-      // 现在 bg-1 可见
+      // [perf] 旧实现：reconCache 建立后只能靠 register/archive 触发 notifyChange 失效，
+      // 否则永远 stale（外部进程写入的文件对本进程不可见）。新实现：每次 collectRecords
+      // 都 readdir + stat 校验，新文件立即可见（同时修复跨进程可见性）。
       const ids = store.collectRecords(100).map((r) => r.id);
       expect(ids).toContain("bg-1");
     });
@@ -336,14 +381,16 @@ describe("RecordStore", () => {
     }
 
     // ── 分支 1: .cancelled ──
-    it(".cancelled sidecar → cancelled", () => {
+    it(".cancelled sidecar → closed + closedReason=cancelled", () => {
       const sessionFile = writeBaseSession();
       writeCancelledTombstone(sessionFile, {
         id: SESSION_ID, status: "cancelled", agent: "worker", startedAt: STARTED_AT, endedAt: 6000,
       });
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
-      expect(found?.status).toBe("cancelled");
+      // v4 B-1：cancelled 折入 closed（closedReason='cancelled' 区分用户取消）
+      expect(found?.status).toBe("closed");
+      expect(found?.closedReason).toBe("cancelled");
       expect(found?.error).toBe("cancelled by user");
       expect(found?.endedAt).toBe(6000);
     });
@@ -354,7 +401,7 @@ describe("RecordStore", () => {
       writeFinalized(sessionFile);
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
-      expect(found?.status).toBe("done");
+      expect(found?.status).toBe("closed");
     });
 
     // ── 分支 2: .finalized failed ──
@@ -386,7 +433,7 @@ describe("RecordStore", () => {
       writeFinalized(sessionFile);
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
-      expect(found?.status).toBe("failed");
+      expect(found?.status).toBe("closed");
     });
 
     // ── 分支 3: .alive + 活 pid → running + externalInstance ──
@@ -401,27 +448,27 @@ describe("RecordStore", () => {
       expect(found?.externalInstance).toEqual(marker);
     });
 
-    // ── 分支 3→4: .alive + 死 pid → crashed ──
-    it(".alive + 死 pid → crashed", () => {
+    // ── 分支 3→4: .alive + 死 pid → running（SP-2：跨重启可恢复）──
+    it(".alive + 死 pid → running（SP-2 跨重启可恢复）", () => {
       const sessionFile = writeBaseSession();
       const marker: AliveMarker = { pid: 9999999, id: SESSION_ID, startedAt: STARTED_AT };
       writeAliveMarker(sessionFile, marker);
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
-      expect(found?.status).toBe("crashed");
+      expect(found?.status).toBe("running");
       expect(found?.externalInstance).toBeUndefined();
     });
 
-    // ── 分支 4: 都无 sidecar → crashed ──
-    it("无任何 sidecar → crashed", () => {
+    // ── 分支 4: 都无 sidecar → running（SP-2：跨重启可恢复）──
+    it("无任何 sidecar → running（SP-2 跨重启可恢复）", () => {
       writeBaseSession();
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
-      expect(found?.status).toBe("crashed");
+      expect(found?.status).toBe("running");
     });
 
-    // ── 分支 4: >24h 软超时 → crashed（无视探活）──
-    it(">24h 软超时 → crashed（即使 pid 存活）", () => {
+    // ── 分支 4: >24h 软超时 → running（SP-2：跨重启可恢复，无视探活）──
+    it(">24h 软超时 → running（SP-2，即使 pid 存活）", () => {
       const sessionFile = writeBaseSession();
       // startedAt 设为 25 小时前
       const oldStartedAt = Date.now() - 25 * 60 * 60 * 1000;
@@ -436,7 +483,7 @@ describe("RecordStore", () => {
 
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
-      expect(found?.status).toBe("crashed");
+      expect(found?.status).toBe("running");
       expect(found?.externalInstance).toBeUndefined();
     });
 
@@ -449,18 +496,21 @@ describe("RecordStore", () => {
       });
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
-      expect(found?.status).toBe("cancelled");
+      // v4 B-1：.cancelled 优先级不变，但 status 折入 closed（closedReason='cancelled'）
+      expect(found?.status).toBe("closed");
+      expect(found?.closedReason).toBe("cancelled");
     });
 
     // ── 回归：旧 .cancelled 单分支行为不变 ──
-    it("旧 .cancelled 单分支行为不变（回归）", () => {
+    it("旧 .cancelled 单分支行为不变（回归，status 折入 closed）", () => {
       const sessionFile = writeBaseSession();
       writeCancelledTombstone(sessionFile, {
         id: SESSION_ID, status: "cancelled", agent: "worker", startedAt: STARTED_AT, endedAt: 7000,
       });
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
-      expect(found?.status).toBe("cancelled");
+      expect(found?.status).toBe("closed");
+      expect(found?.closedReason).toBe("cancelled");
       expect(found?.error).toBe("cancelled by user");
       expect(found?.endedAt).toBe(7000);
     });
@@ -546,7 +596,7 @@ describe("RecordStore", () => {
   // endedAt 重建（问题 2 修复：终态耗时不再随墙钟增长）
   // ============================================================
   describe("endedAt 重建（耗时不再无限增长）", () => {
-    it(".finalized → endedAt 为最后 entry 时间戳（非 now）", () => {
+    it(".finalized → light endedAt 用 mtime 近似，全量 endedAt 为最后 entry 时间戳", () => {
       const sessionFile = path.join(tmpDir, "fin.jsonl");
       writeSessionJsonl(sessionFile, {
         id: "bg-1", agent: "w", mode: "background", task: "t",
@@ -555,10 +605,15 @@ describe("RecordStore", () => {
       writeFinalized(sessionFile);
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100, "all", "sess-A").find((r) => r.id === "bg-1");
-      expect(found?.endedAt).toBe(9000); // 不是 Date.now()
+      // [perf] light 分支 2：endedAt 用 jsonl mtime 近似（finalize 后文件不再变化，
+      // 与最后 entry ts 差 <1s）——不是 entry ts 9000，也不是随墙钟无限增长的 now 基准。
+      expect(found?.endedAt).toBeDefined();
+      expect(found?.endedAt).toBeGreaterThan(5000);
+      // 全量（getFullRecord）：精确用最后 entry 时间戳（非 now）。
+      expect(store.getFullRecord("bg-1")?.endedAt).toBe(9000);
     });
 
-    it("无 sidecar（crashed）→ endedAt 为最后 entry 时间戳（非 now）", () => {
+    it("无 sidecar（running, SP-2）→ endedAt 保持 undefined（非终态）", () => {
       const sessionFile = path.join(tmpDir, "crash.jsonl");
       writeSessionJsonl(sessionFile, {
         id: "bg-1", agent: "w", mode: "background", task: "t",
@@ -566,8 +621,9 @@ describe("RecordStore", () => {
       });
       const store = new RecordStore(tmpDir);
       const found = store.collectRecords(100, "all", "sess-A").find((r) => r.id === "bg-1");
-      expect(found?.status).toBe("crashed");
-      expect(found?.endedAt).toBe(9000);
+      expect(found?.status).toBe("running");
+      // SP-2: running 是非终态（旧 idle 折入），endedAt 保持 undefined（待续聊）
+      expect(found?.endedAt).toBeUndefined();
     });
 
     it(".alive running → endedAt 保持 undefined（running 耗时继续增长是正确的）", () => {
@@ -602,7 +658,7 @@ describe("RecordStore", () => {
         id: "broken-1",
         rootSessionId: "sess-current",
         agentName: "worker",
-        status: "crashed", // 越界值（union 不含 "crashed"）
+        status: "crashed", // 越界值（union 不含 "crashed"，SP-1 后 valid statuses = running/closed/cancelled）
         createdAt: 1000,
       } as unknown as ManifestRecord;
     }
@@ -666,4 +722,336 @@ describe("RecordStore", () => {
       );
     });
   });
+
+  // ============================================================
+  // SP-2: reconstructAll 兜底分支输出 running（非 crashed；v4 两态后旧 idle 折入 running）
+  // ============================================================
+  describe("SP-2: reconstructAll 兜底 running（跨重启恢复）", () => {
+    // TC-1: 兜底分支输出 running（非 crashed）
+    it("TC-1: 无 sidecar + 死 pid → reconstructAll 输出 running（可冷路径 resume）", () => {
+      const sessionFile = path.join(tmpDir, "sp2-tc1.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-sp2-1", agent: "worker", mode: "background", task: "cross-restart task",
+        startedAt: 1000, rootSessionId: "sess-sp2",
+      });
+      // 无任何 sidecar marker → 分支 4 兜底
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100, "all", "sess-sp2").find((r) => r.id === "sa-sp2-1");
+      expect(found).toBeDefined();
+      expect(found?.status).toBe("running");
+      // SP-2: running 是非终态（旧 idle 折入），endedAt 保持 undefined
+      expect(found?.endedAt).toBeUndefined();
+    });
+
+    // TC-2: 有 .finalized marker 的 record 仍归档为 done（不回归）
+    it("TC-2: .finalized marker → done（分支 1/2 不回归）", () => {
+      const sessionFile = path.join(tmpDir, "sp2-tc2.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-sp2-2", agent: "worker", mode: "background", task: "finalized task",
+        startedAt: 2000, rootSessionId: "sess-sp2",
+      });
+      writeFinalized(sessionFile);
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100, "all", "sess-sp2").find((r) => r.id === "sa-sp2-2");
+      expect(found).toBeDefined();
+      // 分支 2 仍归档为 done，不受 SP-2 影响
+      expect(found?.status).toBe("closed");
+      expect(found?.endedAt).toBeDefined();
+    });
+
+    // TC-2b: .cancelled marker → closed+cancelled（分支 1 不回归）
+    it("TC-2b: .cancelled marker → closed+cancelled reason（分支 1 不回归）", () => {
+      const sessionFile = path.join(tmpDir, "sp2-tc2b.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-sp2-2b", agent: "worker", mode: "background", task: "cancelled task",
+        startedAt: 3000, rootSessionId: "sess-sp2",
+      });
+      writeCancelledTombstone(sessionFile, {
+        id: "sa-sp2-2b", status: "cancelled", agent: "worker", startedAt: 3000, endedAt: 4000,
+      });
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100, "all", "sess-sp2").find((r) => r.id === "sa-sp2-2b");
+      expect(found).toBeDefined();
+      expect(found?.status).toBe("closed");
+      expect(found?.closedReason).toBe("cancelled");
+    });
+  });
+
+  // ============================================================
+  // 孤儿终态恢复（residual-fixes）：分支 4 兜底 record 的判定与落盘
+  // ============================================================
+  describe("recoverOrphanRecords 孤儿终态恢复", () => {
+    /** 带真实磁盘 fixture + appendEntry 捕获的 store。 */
+    function makeRecoveryStore(): { store: RecordStore; appended: Array<{ customType: string; data: Record<string, unknown> }> } {
+      const appended: Array<{ customType: string; data: Record<string, unknown> }> = [];
+      const store = new RecordStore(tmpDir, undefined, {
+        appendEntry: (customType: string, data: unknown) => {
+          appended.push({ customType, data: data as Record<string, unknown> });
+        },
+      } as never);
+      return { store, appended };
+    }
+
+    it("末行完整 → closed 终态 entry + .finalized sidecar（防重锚）", () => {
+      const sessionFile = path.join(tmpDir, "orphan-done.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-orphan-1", agent: "worker", mode: "background", task: "orphan done",
+        startedAt: 1000, rootSessionId: "sess-orphan",
+      });
+      const { store, appended } = makeRecoveryStore();
+      store.recoverOrphanRecords("sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-orphan-1");
+      expect(entry?.customType).toBe("subagent-record");
+      expect(entry?.data.status).toBe("closed");
+      expect(entry?.data.closedReason).toBe("gc");
+      expect(entry?.data.endedAt).toEqual(expect.any(Number));
+      expect(entry?.data.error).toBeUndefined();
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+      // 防重：sidecar 使下次重建走分支 2（closed），不再进判定
+      const again = [...appended];
+      store.recoverOrphanRecords("sess-orphan");
+      expect(appended.length).toBe(again.length);
+      const found = store.collectRecords(100, "all", "sess-orphan").find((r) => r.id === "sa-orphan-1");
+      expect(found?.status).toBe("closed");
+    });
+
+    it("末行截断 → closed + error（保守方向）", () => {
+      const sessionFile = path.join(tmpDir, "orphan-truncated.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-orphan-2", agent: "worker", mode: "background", task: "orphan truncated",
+        startedAt: 2000, rootSessionId: "sess-orphan",
+      });
+      // 制造截断：append 半行 JSON（无换行结尾）
+      fs.appendFileSync(sessionFile, '{"type":"message","id":"msg-2","pare', "utf-8");
+      const { store, appended } = makeRecoveryStore();
+      store.recoverOrphanRecords("sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-orphan-2");
+      expect(entry?.data.status).toBe("closed");
+      expect(entry?.data.error).toContain("truncated");
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+    });
+
+    it("末行 >64KB 完整 JSON → 不误判截断，判 done（V1 探针实测回归）", () => {
+      const sessionFile = path.join(tmpDir, "orphan-longline.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-orphan-5", agent: "worker", mode: "background", task: "orphan long line",
+        startedAt: 5000, rootSessionId: "sess-orphan",
+      });
+      // 真实库实测形态：末行为超长完整 entry（subagent-identity 的 task 内嵌大 payload，
+      // 28/4822 个文件末行 65KB-776KB）——固定 64KB 尾窗曾把这类行从中间切开误判截断。
+      const bigEntry = JSON.stringify({
+        type: "custom", id: "id-big", parentId: null,
+        timestamp: new Date(5000).toISOString(), customType: "subagent-identity",
+        data: { id: "sa-orphan-5", agent: "worker", mode: "background", task: "x".repeat(70 * 1024), startedAt: 5000 },
+      });
+      fs.appendFileSync(sessionFile, bigEntry + "\n", "utf-8");
+      const { store, appended } = makeRecoveryStore();
+      store.recoverOrphanRecords("sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-orphan-5");
+      expect(entry?.data.status).toBe("closed");
+      expect(entry?.data.error).toBeUndefined();
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+    });
+
+    it("chatMode 孤儿 → 不终态化，落 resumable entry（可续聊产品语义）", () => {
+      const sessionFile = path.join(tmpDir, "orphan-chat.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-orphan-3", agent: "worker", mode: "background", task: "orphan chat",
+        startedAt: 3000, rootSessionId: "sess-orphan", chatMode: true,
+      });
+      const { store, appended } = makeRecoveryStore();
+      store.recoverOrphanRecords("sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-orphan-3");
+      expect(entry?.data.status).toBe("running");
+      expect(entry?.data.resumable).toBe(true);
+      expect(entry?.data.chatMode).toBe(true);
+      // chat 分流不写终态 sidecar
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(false);
+      // orphanJudged 缓存：同 store 重复调用不重复 append
+      const count = appended.length;
+      store.recoverOrphanRecords("sess-orphan");
+      expect(appended.length).toBe(count);
+    });
+
+    it("非分支 4 record（closed / 活进程）不进判定", () => {
+      const closedFile = path.join(tmpDir, "orphan-closed.jsonl");
+      writeSessionJsonl(closedFile, {
+        id: "sa-orphan-4", agent: "worker", mode: "background", task: "already closed",
+        startedAt: 4000, rootSessionId: "sess-orphan",
+      });
+      writeFinalized(closedFile);
+      const { store, appended } = makeRecoveryStore();
+      store.recoverOrphanRecords("sess-orphan");
+      expect(appended.find((c) => c.data.id === "sa-orphan-4")).toBeUndefined();
+    });
+
+    /** 写主 session fixture（含指定 subagent-record entry 序列）。 */
+    function writeMainSession(entries: Array<Record<string, unknown>>): string {
+      const mainFile = path.join(tmpDir, "main-session.jsonl");
+      const lines = entries.map((d) => JSON.stringify({ type: "custom", id: `e-${Math.random()}`, parentId: null, customType: "subagent-record", data: d }));
+      fs.writeFileSync(mainFile, lines.join("\n") + "\n", "utf-8");
+      return mainFile;
+    }
+
+    it("entry-born 孤儿（无子文件，spawn 窗口期死亡）→ closed+gc+error（E2E 实测回归）", () => {
+      const mainFile = writeMainSession([
+        { v: 1, id: "sa-entryonly-1", agent: "worker", task: "spawn interrupted", slug: "s", status: "running", mode: "background", startedAt: 6000, rootSessionId: "sess-orphan", depth: 0, turns: 0, totalTokens: 0, model: "m", eventLog: [], displayItems: [] },
+      ]);
+      const { store, appended } = makeRecoveryStore();
+      store.recoverEntryOnlyOrphans(mainFile, "sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-entryonly-1");
+      expect(entry?.data.status).toBe("closed");
+      expect(entry?.data.closedReason).toBe("gc");
+      expect(entry?.data.error).toContain("no child session file");
+      // 防重：orphanJudged 缓存拦截二次判定
+      const count = appended.length;
+      store.recoverEntryOnlyOrphans(mainFile, "sess-orphan");
+      expect(appended.length).toBe(count);
+    });
+
+    it("entry-born chatMode 孤儿 → 不终态化，落 resumable entry", () => {
+      const mainFile = writeMainSession([
+        { v: 1, id: "sa-entryonly-2", agent: "worker", task: "chat spawn interrupted", slug: "s", status: "running", mode: "background", startedAt: 7000, rootSessionId: "sess-orphan", depth: 0, turns: 0, totalTokens: 0, model: "m", eventLog: [], displayItems: [], chatMode: true },
+      ]);
+      const { store, appended } = makeRecoveryStore();
+      store.recoverEntryOnlyOrphans(mainFile, "sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-entryonly-2");
+      expect(entry?.data.status).toBe("running");
+      expect(entry?.data.resumable).toBe(true);
+      expect(entry?.data.error).toBeUndefined();
+    });
+
+    it("有子文件锚 / 末条已终态 / 他 session 的 entry-born id 不进判定", () => {
+      const anchoredFile = path.join(tmpDir, "orphan-anchored.jsonl");
+      writeSessionJsonl(anchoredFile, {
+        id: "sa-anchored", agent: "worker", mode: "background", task: "has file",
+        startedAt: 8000, rootSessionId: "sess-orphan",
+      });
+      const mainFile = writeMainSession([
+        { v: 1, id: "sa-anchored", agent: "worker", task: "has file", slug: "s", status: "running", mode: "background", startedAt: 8000, rootSessionId: "sess-orphan", depth: 0, turns: 0, totalTokens: 0, model: "m", eventLog: [], displayItems: [] },
+        { v: 1, id: "sa-settled", agent: "worker", task: "settled", slug: "s", status: "closed", mode: "background", startedAt: 8100, rootSessionId: "sess-orphan", depth: 0, turns: 1, totalTokens: 0, model: "m", eventLog: [], displayItems: [] },
+        { v: 1, id: "sa-foreign", agent: "worker", task: "other session", slug: "s", status: "running", mode: "background", startedAt: 8200, rootSessionId: "sess-other", depth: 0, turns: 0, totalTokens: 0, model: "m", eventLog: [], displayItems: [] },
+      ]);
+      const { store, appended } = makeRecoveryStore();
+      store.recoverEntryOnlyOrphans(mainFile, "sess-orphan");
+      expect(appended.find((c) => c.data.id === "sa-anchored")).toBeUndefined();
+      expect(appended.find((c) => c.data.id === "sa-settled")).toBeUndefined();
+      expect(appended.find((c) => c.data.id === "sa-foreign")).toBeUndefined();
+    });
+  });
+
+  // ============================================================
+  // W16 [D4]：subagent-record 自描述 appendEntry 上报（状态迁移点）
+  // ============================================================
+  describe("W16 subagent-record 自描述 appendEntry 上报", () => {
+    /** appendEntry 捕获（RecordStorePi 最小实现）。 */
+    interface AppendedCall {
+      customType: string;
+      data: unknown;
+    }
+
+    /** 构造带 appendEntry 捕获的 store（pi 注入通道，对齐生产 setPi 后形态）。 */
+    function makeStoreWithPi(): { store: RecordStore; appended: AppendedCall[] } {
+      const appended: AppendedCall[] = [];
+      const store = new RecordStore(tmpDir, undefined, {
+        appendEntry: (customType: string, data: unknown) => {
+          appended.push({ customType, data });
+        },
+      });
+      return { store, appended };
+    }
+
+    /** unknown → 对象的运行时 guard（taste/no-unsafe-cast：断言前先收窄）。 */
+    function asEntryData(d: unknown): Record<string, unknown> {
+      if (typeof d !== "object" || d === null) throw new Error("entry data is not an object");
+      return d as Record<string, unknown>;
+    }
+
+    it("register：append subagent-record entry，data = v1 + SubagentRecord 完整快照 schema", () => {
+      const { store, appended } = makeStoreWithPi();
+      store.register(makeRecord());
+
+      expect(appended).toHaveLength(1);
+      // 写点字面量与 record-entry.ts 常量等值（钉住双源一致性）
+      expect(appended[0]?.customType).toBe(SUBAGENT_RECORD_CUSTOM_TYPE);
+      // [E2E 实测教训] 必须先 JSON 序列化再断言：appendEntry 捕获的是内存对象，
+      // undefined 值的键名仍在（旧 27-key 断言因此漏检 recordToSubagent 丢
+      // chatMode 的 bug）；真实 JSONL 会丢 undefined 值键，此处对齐生产行为。
+      const data = asEntryData(JSON.parse(JSON.stringify(appended[0]?.data)));
+      // register 时点序列化存活字段（undefined 值字段按生产序列化丢弃）：
+      // chatMode 必须显式在场（one-shot=false）——renderer isDone 判据依赖它。
+      expect(Object.keys(data).sort()).toEqual([
+        "agent", "chatMode", "depth", "displayItems", "eventLog",
+        "id", "mode", "model", "rootSessionId", "round", "startedAt",
+        "status", "task", "totalTokens", "turns", "v", "worktree",
+      ]);
+      expect(data).toMatchObject({
+        v: 1,
+        id: "r1",
+        agent: "worker",
+        task: "t",
+        status: "running",
+        mode: "sync",
+        startedAt: 1000,
+        rootSessionId: "sess-current",
+        chatMode: false,
+        turns: 0,
+        totalTokens: 0,
+        model: "m",
+        eventLog: [],
+        displayItems: [],
+      });
+    });
+
+    it("archive：append 终态完整快照（result/endedAt/closedReason）；one-shot 生命周期共 2 次 append", () => {
+      const { store, appended } = makeStoreWithPi();
+      const r = makeRecord();
+      store.register(r);
+      // 模拟正常终态路径：tryTransition CAS → completeRecord 冻结 → archive（D-017 时序）
+      tryTransition(r, "closed", "gc");
+      completeRecord(r, { text: "task done", turns: 1, durationMs: 500, success: true, sessionId: "r1", toolCalls: [] }, "closed", "gc");
+      store.archive(r);
+
+      // 探针基线（单测级）：one-shot 生命周期 = register + archive = 2 次 append
+      expect(appended).toHaveLength(2);
+      const data = asEntryData(appended[1]?.data);
+      expect(data).toMatchObject({
+        v: 1,
+        id: "r1",
+        status: "closed",
+        closedReason: "gc",
+        result: "task done",
+        endedAt: expect.any(Number) as number,
+      });
+    });
+
+    it("reportRecordTransition：类外恢复写点上报（chatMode 续轮 round 携带）", () => {
+      const { store, appended } = makeStoreWithPi();
+      const r = makeRecord({ chatMode: true, round: 1 });
+      store.reportRecordTransition(r);
+
+      expect(appended).toHaveLength(1);
+      expect(appended[0]?.customType).toBe(SUBAGENT_RECORD_CUSTOM_TYPE);
+      expect(asEntryData(appended[0]?.data)).toMatchObject({
+        v: 1,
+        id: "r1",
+        status: "running",
+        round: 1,
+      });
+    });
+
+    it("pi 未注入（session_start 前）：三写点均安全降级不抛错", () => {
+      const store = new RecordStore(tmpDir);
+      const r = makeRecord();
+      expect(() => store.register(r)).not.toThrow();
+      expect(() => store.archive(r)).not.toThrow();
+      expect(() => store.reportRecordTransition(r)).not.toThrow();
+    });
+  });
 });