@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,1057 @@
+// src/__tests__/record-store.test.ts
+//
+// RecordStore 专属测试。
+// 覆盖：
+//   - archive 立即移除（终态 record 不留内存，读时从 session.jsonl 重建）
+//   - collectRecords 合并内存(running) + 磁盘(session.jsonl 重建)
+//   - collectRecords statusFilter（"running" vs "all"）
+//   - cancelled tombstone override
+//   - compareRecords 排序（status priority + startedAt desc）
+//   - 重建缓存（notifyChange 失效）
+//
+// 用 tmpdir + 真实 .jsonl fixture（隔离真实文件系统，同 session-reconstructor.test.ts 模式）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { writeAliveMarker } from "../alive-store.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";
+import type { AliveMarker, ExecutionRecord } from "../types.ts";
+
+/** 构造 ExecutionRecord（base 默认 running，over 覆盖任意字段）。 */
+function makeRecord(over: Partial<ExecutionRecord> = {}): ExecutionRecord {
+  const base = createRecord("r1", {
+    agent: "worker",
+    model: "m",
+    mode: "sync",
+    task: "t",
+    startedAt: 1000,
+    rootSessionId: "sess-current",
+    // 对齐生产 register 路径（subagent-service createRecord：one-shot 显式 false）
+    chatMode: false,
+  });
+  return { ...base, ...over };
+}
+
+/**
+ * 写一个最小合法的 session.jsonl（含 identity custom entry + 1 个 assistant message）。
+ * 用于 collectRecords 磁盘源重建测试。
+ */
+function writeSessionJsonl(
+  filePath: string,
+  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;
+  const header = JSON.stringify({
+    type: "session", version: 3, id: "sess-uuid", timestamp: new Date(identity.startedAt).toISOString(), cwd: "/tmp",
+  });
+  const identityData: Record<string, unknown> = {
+    id: identity.id,
+    agent: identity.agent,
+    mode: identity.mode,
+    task: identity.task,
+    startedAt: identity.startedAt,
+  };
+  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",
+    parentId: null,
+    timestamp: new Date(identity.startedAt).toISOString(),
+    customType: "subagent-identity",
+    data: identityData,
+  });
+  const assistantMsg = JSON.stringify({
+    type: "message",
+    id: "msg-1",
+    parentId: "id-1",
+    timestamp: new Date(lastTs).toISOString(),
+    message: {
+      role: "assistant",
+      content: [{ type: "text", text: assistantText }],
+      usage: { input: 10, output: 20, cacheRead: 0, cacheWrite: 0, totalTokens: 30, cost: { total: 0 } },
+      stopReason: "stop",
+      timestamp: lastTs,
+    },
+  });
+  fs.writeFileSync(filePath, `${header}\n${identityEntry}\n${assistantMsg}\n`, "utf-8");
+}
+
+describe("RecordStore", () => {
+  let rootDir: string;
+  let tmpDir: string;
+
+  beforeEach(() => {
+    // [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(() => {
+    // maxRetries：fire-and-forget 的 sessions-index 写可能与删除并发（ENOTEMPTY 竞态）
+    fs.rmSync(rootDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  // ============================================================
+  // archive 立即移除
+  // ============================================================
+  describe("archive 立即移除", () => {
+    it("archive 后 record 立即从内存移除（不再 linger）", () => {
+      const store = new RecordStore(tmpDir);
+      const r = makeRecord({ id: "sync-1", mode: "sync", status: "closed" });
+      store.register(r);
+      expect(store.getMutable("sync-1")).toBeDefined();
+      store.archive(r);
+      expect(store.getMutable("sync-1")).toBeUndefined();
+    });
+
+    it("background record 同样立即移除（不再 FIFO）", () => {
+      const store = new RecordStore(tmpDir);
+      const r = makeRecord({ id: "bg-1", mode: "background", status: "closed" });
+      store.register(r);
+      store.archive(r);
+      expect(store.getMutable("bg-1")).toBeUndefined();
+    });
+  });
+
+  // ============================================================
+  // collectRecords：内存(running) + 磁盘(重建) 合并
+  // ============================================================
+  describe("collectRecords 合并", () => {
+    it("内存 running record 出现在结果中", () => {
+      const store = new RecordStore(tmpDir);
+      store.register(makeRecord({ id: "run-1", mode: "background", startedAt: 1000 }));
+      const ids = store.collectRecords(100).map((r) => r.id);
+      expect(ids).toContain("run-1");
+    });
+
+    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 → 四分支兜底 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("running");
+      expect(found?.agent).toBe("worker");
+      // [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", () => {
+      const sessionFile = path.join(tmpDir, "2026-01-01-uuid-b.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "bg-2", agent: "worker", mode: "background", task: "do it", startedAt: 5000,
+      });
+      writeFinalized(sessionFile);
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100).find((r) => r.id === "bg-2");
+      expect(found).toBeDefined();
+      expect(found?.status).toBe("closed");
+    });
+
+    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,
+      });
+      const store = new RecordStore(tmpDir);
+      store.register(makeRecord({ id: "run-1", mode: "background", startedAt: 1000 }));
+      const filter: StatusFilter = "running";
+      const ids = store.collectRecords(100, filter).map((r) => r.id);
+      // 内存 run-1 + 磁盘跨重启 bg-1 都是 running（旧 idle 折入）；startedAt desc → bg-1(5000) 先
+      expect(ids).toEqual(["bg-1", "run-1"]);
+    });
+
+    it("statusFilter='all'（默认）返回内存 + 磁盘", () => {
+      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,
+      });
+      const store = new RecordStore(tmpDir);
+      store.register(makeRecord({ id: "run-1", mode: "background", startedAt: 1000 }));
+      const ids = store.collectRecords(100).map((r) => r.id);
+      expect(ids).toContain("run-1");
+      expect(ids).toContain("bg-1");
+    });
+
+    it("内存 running 优先于磁盘同 id（内存覆盖）", () => {
+      const sessionFile = path.join(tmpDir, "2026-01-01-uuid-a.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "dup-1", agent: "worker", mode: "background", task: "from disk", startedAt: 5000,
+      });
+      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 覆盖磁盘 idle（SP-2）
+    });
+
+    it("[MF-3/S-20] 跨进程组合：子进程（worktree）写入 enc(ROOT) 的深层 record 被 ROOT store 重建，同 rootSessionId 全树可见、他树被排除", () => {
+      // MF-3 修复后：worktree 子进程把其子 record 的 session 文件写到统一 enc(ROOT cwd) 段，
+      // ROOT 进程的 store 扫同一目录重建（旧实现子进程写到 enc(checkout) 段，此处为空）。
+      const rootCwd = "/Users/x/root-proj";
+      const sessionsDir = getSubagentSessionDir(tmpDir, rootCwd);
+      const recordsDir = getSubagentRecordsDir(tmpDir, rootCwd);
+
+      // 父 record A（ROOT 自己 spawn，parentRecordId 缺省=顶层）+ 孙 record C（B 子进程写入，
+      // 同 rootSessionId、parentRecordId=A、depth=2）+ 他树 record X（rootSessionId 不同）
+      fs.mkdirSync(sessionsDir, { recursive: true });
+      writeSessionJsonl(path.join(sessionsDir, "2026-01-01-uuid-a.jsonl"), {
+        id: "sa-A", agent: "worker", mode: "background", task: "level1", startedAt: 1000, rootSessionId: "root-main",
+      });
+      writeSessionJsonl(path.join(sessionsDir, "2026-01-01-uuid-c.jsonl"), {
+        id: "sa-C", agent: "worker", mode: "background", task: "level3", startedAt: 3000,
+        rootSessionId: "root-main", parentRecordId: "sa-A", depth: 2,
+      });
+      writeSessionJsonl(path.join(sessionsDir, "2026-01-01-uuid-x.jsonl"), {
+        id: "sa-X", agent: "worker", mode: "background", task: "other root", startedAt: 4000, rootSessionId: "root-other",
+      });
+
+      // ROOT 进程的 store：sessionsDir/recordsDir 与子进程写盘目录同段（getSubagentSessionDir 同源）
+      const store = new RecordStore(sessionsDir, new ManifestStore(recordsDir), undefined);
+      const recs = store.collectRecords(10, "all", "root-main");
+      const ids = recs.map((r) => r.id);
+
+      // 全树可见：A（顶层）与 C（深度 2，跨进程写入）都在列表，身份字段正确
+      expect(ids).toContain("sa-A");
+      expect(ids).toContain("sa-C");
+      const c = recs.find((r) => r.id === "sa-C");
+      expect(c?.parentRecordId).toBe("sa-A");
+      expect(c?.depth).toBe(2);
+      // 他树 record 被 rootSessionFilter 排除（隔离不破坏）
+      expect(ids).not.toContain("sa-X");
+    });
+  });
+
+  // ============================================================
+  // cancelled tombstone override
+  // ============================================================
+  describe("cancelled tombstone", () => {
+    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,
+      });
+      writeCancelledTombstone(sessionFile, {
+        id: "bg-1", status: "cancelled", agent: "worker", startedAt: 5000, endedAt: 6000,
+      });
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100).find((r) => r.id === "bg-1");
+      // v4 B-1：cancelled 折入 closed，closedReason='cancelled' 保留用户取消语义
+      expect(found?.status).toBe("closed");
+      expect(found?.closedReason).toBe("cancelled");
+      expect(found?.error).toBe("cancelled by user");
+    });
+  });
+
+  // ============================================================
+  // compareRecords 排序稳定性（内存 running record）
+  // ============================================================
+  describe("compareRecords 排序", () => {
+    it("status priority（running < closed）", () => {
+      const store = new RecordStore(tmpDir);
+      // 内存 running record
+      const running = makeRecord({ id: "run-1", mode: "background", startedAt: 3000, status: "running" });
+      store.register(running);
+      // 磁盘 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(0) 排在 closed(3) 前
+    });
+
+    it("同 status 时 startedAt desc（新→旧）", () => {
+      const store = new RecordStore(tmpDir);
+      writeSessionJsonl(path.join(tmpDir, "old.jsonl"), {
+        id: "old", agent: "w", mode: "background", task: "t", startedAt: 1000,
+      });
+      writeSessionJsonl(path.join(tmpDir, "new.jsonl"), {
+        id: "new", agent: "w", mode: "background", task: "t", startedAt: 9000,
+      });
+      // 两个都是 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("新 session.jsonl 无需内存事件即立即可见（[perf] stat 校验取代 notifyChange 整体失效）", () => {
+      const store = new RecordStore(tmpDir);
+      // 首次 collect：空目录
+      expect(store.collectRecords(100)).toHaveLength(0);
+      // 写新 session.jsonl（模拟外部进程/子进程写入——不经本进程任何内存事件）
+      writeSessionJsonl(path.join(tmpDir, "new.jsonl"), {
+        id: "bg-1", agent: "w", mode: "background", task: "t", startedAt: 1000,
+      });
+      // [perf] 旧实现：reconCache 建立后只能靠 register/archive 触发 notifyChange 失效，
+      // 否则永远 stale（外部进程写入的文件对本进程不可见）。新实现：每次 collectRecords
+      // 都 readdir + stat 校验，新文件立即可见（同时修复跨进程可见性）。
+      const ids = store.collectRecords(100).map((r) => r.id);
+      expect(ids).toContain("bg-1");
+    });
+  });
+
+  // ============================================================
+  // dispose / revive
+  // ============================================================
+  describe("dispose / revive", () => {
+    it("dispose 后 notifyChange 不再触发 listener", () => {
+      const store = new RecordStore(tmpDir);
+      let count = 0;
+      store.onChange(() => { count++; });
+      store.register(makeRecord({ id: "r1", startedAt: 1000 }));
+      expect(count).toBe(1);
+      store.dispose();
+      store.register(makeRecord({ id: "r2", startedAt: 2000 }));
+      expect(count).toBe(1); // dispose 后不再通知
+    });
+  });
+
+  // ============================================================
+  // 四分支 sidecar 矩阵（D-006 + D-021）
+  // ============================================================
+  describe("四分支 sidecar 矩阵", () => {
+    const SESSION_ID = "bg-1";
+    const STARTED_AT = 1000;
+
+    function writeBaseSession(): string {
+      const sessionFile = path.join(tmpDir, "2026-01-01-uuid-sidecar.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: SESSION_ID, agent: "worker", mode: "background", task: "do it", startedAt: STARTED_AT,
+      });
+      return sessionFile;
+    }
+
+    // ── 分支 1: .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);
+      // 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);
+    });
+
+    // ── 分支 2: .finalized done ──
+    it(".finalized sidecar + stopReason=stop → done", () => {
+      const sessionFile = writeBaseSession();
+      writeFinalized(sessionFile);
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
+      expect(found?.status).toBe("closed");
+    });
+
+    // ── 分支 2: .finalized failed ──
+    it(".finalized sidecar + stopReason=error → failed", () => {
+      // 写一个 stopReason=error 的 session.jsonl
+      const sessionFile = path.join(tmpDir, "2026-01-01-uuid-fail.jsonl");
+      const header = JSON.stringify({
+        type: "session", version: 3, id: "sess-uuid", timestamp: new Date(STARTED_AT).toISOString(), cwd: "/tmp",
+      });
+      const identityEntry = JSON.stringify({
+        type: "custom", id: "id-1", parentId: null, timestamp: new Date(STARTED_AT).toISOString(),
+        customType: "subagent-identity",
+        data: { id: SESSION_ID, agent: "worker", mode: "background", task: "do it", startedAt: STARTED_AT },
+      });
+      const assistantMsg = JSON.stringify({
+        type: "message", id: "msg-1", parentId: "id-1",
+        timestamp: new Date(STARTED_AT + 1000).toISOString(),
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "error output" }],
+          usage: { input: 10, output: 20, cacheRead: 0, cacheWrite: 0, totalTokens: 30, cost: { total: 0 } },
+          stopReason: "error",
+          errorMessage: "something went wrong",
+          timestamp: STARTED_AT + 1000,
+        },
+      });
+      fs.writeFileSync(sessionFile, `${header}\n${identityEntry}\n${assistantMsg}\n`, "utf-8");
+
+      writeFinalized(sessionFile);
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
+      expect(found?.status).toBe("closed");
+    });
+
+    // ── 分支 3: .alive + 活 pid → running + externalInstance ──
+    it(".alive + 存活 pid → running + externalInstance=true", () => {
+      const sessionFile = writeBaseSession();
+      const recentStartedAt = Date.now() - 1000; // 1 秒前，确保未超 24h
+      const marker: AliveMarker = { pid: process.pid, id: SESSION_ID, startedAt: recentStartedAt };
+      writeAliveMarker(sessionFile, marker);
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
+      expect(found?.status).toBe("running");
+      expect(found?.externalInstance).toEqual(marker);
+    });
+
+    // ── 分支 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("running");
+      expect(found?.externalInstance).toBeUndefined();
+    });
+
+    // ── 分支 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("running");
+    });
+
+    // ── 分支 4: >24h 软超时 → running（SP-2：跨重启可恢复，无视探活）──
+    it(">24h 软超时 → running（SP-2，即使 pid 存活）", () => {
+      const sessionFile = writeBaseSession();
+      // startedAt 设为 25 小时前
+      const oldStartedAt = Date.now() - 25 * 60 * 60 * 1000;
+      const marker: AliveMarker = { pid: process.pid, id: SESSION_ID, startedAt: oldStartedAt };
+      writeAliveMarker(sessionFile, marker);
+
+      // 重写 session.jsonl 使 startedAt 匹配
+      fs.unlinkSync(sessionFile);
+      writeSessionJsonl(sessionFile, {
+        id: SESSION_ID, agent: "worker", mode: "background", task: "do it", startedAt: oldStartedAt,
+      });
+
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100).find((r) => r.id === SESSION_ID);
+      expect(found?.status).toBe("running");
+      expect(found?.externalInstance).toBeUndefined();
+    });
+
+    // ── 回归：.cancelled 优先于 .finalized ──
+    it(".cancelled 优先于 .finalized（即使两者共存）", () => {
+      const sessionFile = writeBaseSession();
+      writeFinalized(sessionFile);
+      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);
+      // v4 B-1：.cancelled 优先级不变，但 status 折入 closed（closedReason='cancelled'）
+      expect(found?.status).toBe("closed");
+      expect(found?.closedReason).toBe("cancelled");
+    });
+
+    // ── 回归：旧 .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("closed");
+      expect(found?.closedReason).toBe("cancelled");
+      expect(found?.error).toBe("cancelled by user");
+      expect(found?.endedAt).toBe(7000);
+    });
+  });
+
+  // ============================================================
+  // session 隔离（问题 1 修复）
+  // ============================================================
+  describe("session 隔离（rootSessionId 过滤）", () => {
+    it("磁盘源：只返回 rootSessionId 匹配的 record", () => {
+      writeSessionJsonl(path.join(tmpDir, "mine.jsonl"), {
+        id: "mine", agent: "w", mode: "background", task: "t", startedAt: 1000, rootSessionId: "sess-A",
+      });
+      writeSessionJsonl(path.join(tmpDir, "other.jsonl"), {
+        id: "other", agent: "w", mode: "background", task: "t", startedAt: 2000, rootSessionId: "sess-B",
+      });
+      const store = new RecordStore(tmpDir);
+      const ids = store.collectRecords(100, "all", "sess-A").map((r) => r.id);
+      expect(ids).toEqual(["mine"]); // other 属于 sess-B，被隔离
+    });
+
+    it("磁盘源：rootSessionId 缺失（旧文件）被排除（无法判定归属）", () => {
+      writeSessionJsonl(path.join(tmpDir, "legacy.jsonl"), {
+        id: "legacy", agent: "w", mode: "background", task: "t", startedAt: 1000, // 无 rootSessionId
+      });
+      const store = new RecordStore(tmpDir);
+      const ids = store.collectRecords(100, "all", "sess-A").map((r) => r.id);
+      expect(ids).toEqual([]); // 旧文件被排除
+    });
+
+    it("磁盘源：不传 filter（undefined）不过滤（向后兼容）", () => {
+      writeSessionJsonl(path.join(tmpDir, "legacy.jsonl"), {
+        id: "legacy", agent: "w", mode: "background", task: "t", startedAt: 1000,
+      });
+      writeSessionJsonl(path.join(tmpDir, "tagged.jsonl"), {
+        id: "tagged", agent: "w", mode: "background", task: "t", startedAt: 2000, rootSessionId: "sess-A",
+      });
+      const store = new RecordStore(tmpDir);
+      const ids = store.collectRecords(100).map((r) => r.id);
+      expect(ids.sort()).toEqual(["legacy", "tagged"]); // 全返回，不过滤
+    });
+
+    it("内存源：只返回 rootSessionId 匹配的 running record", () => {
+      const store = new RecordStore(tmpDir);
+      store.register(makeRecord({ id: "mine", startedAt: 1000, rootSessionId: "sess-A" }));
+      store.register(makeRecord({ id: "other", startedAt: 2000, rootSessionId: "sess-B" }));
+      const ids = store.collectRecords(100, "all", "sess-A").map((r) => r.id);
+      expect(ids).toEqual(["mine"]);
+    });
+
+    it("内存+磁盘混合：同时按 session 过滤", () => {
+      writeSessionJsonl(path.join(tmpDir, "disk-A.jsonl"), {
+        id: "disk-A", agent: "w", mode: "background", task: "t", startedAt: 1000, rootSessionId: "sess-A",
+      });
+      writeSessionJsonl(path.join(tmpDir, "disk-B.jsonl"), {
+        id: "disk-B", agent: "w", mode: "background", task: "t", startedAt: 2000, rootSessionId: "sess-B",
+      });
+      const store = new RecordStore(tmpDir);
+      store.register(makeRecord({ id: "mem-A", startedAt: 3000, rootSessionId: "sess-A" }));
+      store.register(makeRecord({ id: "mem-B", startedAt: 4000, rootSessionId: "sess-B" }));
+      const ids = store.collectRecords(100, "all", "sess-A").map((r) => r.id).sort();
+      expect(ids).toEqual(["disk-A", "mem-A"]);
+    });
+
+    it("重建缓存：不同 filter 共享缓存，不交叉污染", () => {
+      writeSessionJsonl(path.join(tmpDir, "a.jsonl"), {
+        id: "a", agent: "w", mode: "background", task: "t", startedAt: 1000, rootSessionId: "sess-A",
+      });
+      writeSessionJsonl(path.join(tmpDir, "b.jsonl"), {
+        id: "b", agent: "w", mode: "background", task: "t", startedAt: 2000, rootSessionId: "sess-B",
+      });
+      const store = new RecordStore(tmpDir);
+      // 先查 sess-A（建缓存）
+      expect(store.collectRecords(100, "all", "sess-A").map((r) => r.id)).toEqual(["a"]);
+      // 再查 sess-B（复用缓存基底，过滤不交叉）
+      expect(store.collectRecords(100, "all", "sess-B").map((r) => r.id)).toEqual(["b"]);
+      // 不带 filter（复用缓存，全量）
+      expect(store.collectRecords(100).map((r) => r.id).sort()).toEqual(["a", "b"]);
+    });
+  });
+
+  // ============================================================
+  // endedAt 重建（问题 2 修复：终态耗时不再随墙钟增长）
+  // ============================================================
+  describe("endedAt 重建（耗时不再无限增长）", () => {
+    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",
+        startedAt: 5000, lastTs: 9000, rootSessionId: "sess-A",
+      });
+      writeFinalized(sessionFile);
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100, "all", "sess-A").find((r) => r.id === "bg-1");
+      // [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（running, SP-2）→ endedAt 保持 undefined（非终态）", () => {
+      const sessionFile = path.join(tmpDir, "crash.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "bg-1", agent: "w", mode: "background", task: "t",
+        startedAt: 5000, lastTs: 9000, rootSessionId: "sess-A",
+      });
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100, "all", "sess-A").find((r) => r.id === "bg-1");
+      expect(found?.status).toBe("running");
+      // SP-2: running 是非终态（旧 idle 折入），endedAt 保持 undefined（待续聊）
+      expect(found?.endedAt).toBeUndefined();
+    });
+
+    it(".alive running → endedAt 保持 undefined（running 耗时继续增长是正确的）", () => {
+      const sessionFile = path.join(tmpDir, "alive.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "bg-1", agent: "w", mode: "background", task: "t",
+        startedAt: Date.now() - 1000, lastTs: Date.now(), rootSessionId: "sess-A",
+      });
+      writeAliveMarker(sessionFile, { pid: process.pid, id: "bg-1", startedAt: Date.now() - 1000 });
+      const store = new RecordStore(tmpDir);
+      const found = store.collectRecords(100, "all", "sess-A").find((r) => r.id === "bg-1");
+      expect(found?.status).toBe("running");
+      expect(found?.endedAt).toBeUndefined();
+    });
+  });
+
+  // ============================================================
+  // [BL-M1] 修复：损坏 manifest 上报 pi.appendEntry（用户可见）
+  // collectRecords 跳过 mapManifestStatus 返回 null 的 manifest 时，除 console.warn
+  // 外还需调 pi.appendEntry("subagent:manifest-invalid-status", ...) 让用户能在 session
+  // 内复盘事故——避免磁盘陈旧/损坏 manifest 被静默吞掉。
+  // ============================================================
+  describe("manifest status 越界（损坏 manifest）", () => {
+    /** 构造一个 status 越界的 manifest mock。
+     *  ManifestRecord.status union 是 4 态，运行时却可能收到陈旧 "error" / 意外 "crashed"
+     * 等越界值——isValidManifest 当前挡掉了大部分，但 manifestStore.listAllSync 与
+     *  mapManifestStatus 之间仍有防御层（[BL-M1] 修复记录）。本测试用 unknown-cast 模拟
+     *  一个越过 ManifestRecord 静态类型的对象，验证 collectRecords 反应正确。 */
+    function brokenManifest(): ManifestRecord {
+      // eslint-disable-next-line taste/no-unsafe-cast -- intentional: cast status 越界值模拟磁盘损坏 manifest（测试目的本身）
+      return {
+        id: "broken-1",
+        rootSessionId: "sess-current",
+        agentName: "worker",
+        status: "crashed", // 越界值（union 不含 "crashed"，SP-1 后 valid statuses = running/closed/cancelled）
+        createdAt: 1000,
+      } as unknown as ManifestRecord;
+    }
+
+    /** Mock ManifestStore 让测试不依赖 fs 路径 + isValidManifest 守卫。
+     *  source/target 类型不兼容是 intentional（ManifestStore 有多个方法，测试仅需 listAllSync），
+     *  `as unknown as ManifestStore` 是 vitest mock 标准 pattern。*/
+    function makeManifestStoreMock(manifests: ManifestRecord[]): ManifestStore {
+      // eslint-disable-next-line taste/no-unsafe-cast -- intentional: ManifestStore 有多个方法，测试仅需 listAllSync
+      return {
+        // 复制 manifests 防调用方意外 mutate 共享数组；vi.fn 每次调用返回独立数组
+        listAllSync: vi.fn(() => [...manifests]),
+      } as unknown as ManifestStore;
+    }
+
+    it("collectRecords 跳过越界 status 时调用 pi.appendEntry('subagent:manifest-invalid-status', ...)", () => {
+      const pi = { appendEntry: vi.fn() };
+      // Mock ManifestStore：listAllSync 返回损坏 manifest，绕开真实 fs 路径与 isValidManifest 守卫。
+      const manifestStore = makeManifestStoreMock([brokenManifest()]);
+      const store = new RecordStore(tmpDir, manifestStore, pi);
+
+      const result = store.collectRecords(100);
+
+      // 损坏 manifest 不出现在结果中（status 越界被跳过，不降级为 failed——避免误告警）
+      expect(result.find((r) => r.id === "broken-1")).toBeUndefined();
+      // appendEntry 被调用，customType + data 字段正确
+      expect(pi.appendEntry).toHaveBeenCalledTimes(1);
+      expect(pi.appendEntry).toHaveBeenCalledWith("subagent:manifest-invalid-status", {
+        id: "broken-1",
+        status: "crashed",
+        rootSessionId: "sess-current",
+        agentName: "worker",
+      });
+    });
+
+    it("pi 为 null/undefined 时不抛错（向后兼容：不注入 pi 的旧调用路径）", () => {
+      const manifestStore = makeManifestStoreMock([brokenManifest()]);
+      // 不传 pi（undefined）—— 模拟 SubagentService 构造期 session_start 未触发的场景。
+      const store = new RecordStore(tmpDir, manifestStore);
+      expect(() => store.collectRecords(100)).not.toThrow();
+      // 损坏 manifest 仍被跳过（不降级）
+      const result = store.collectRecords(100);
+      expect(result.find((r) => r.id === "broken-1")).toBeUndefined();
+    });
+
+    it("setPi() 后 appendEntry 切换到新 pi（覆盖初始 undefined）", () => {
+      const pi1 = { appendEntry: vi.fn() };
+      const pi2 = { appendEntry: vi.fn() };
+      const manifestStore = makeManifestStoreMock([brokenManifest()]);
+      const store = new RecordStore(tmpDir, manifestStore, pi1);
+      store.setPi(pi2);
+
+      store.collectRecords(100);
+
+      // 切换后只调 pi2（pi1 不再被调用）
+      expect(pi1.appendEntry).not.toHaveBeenCalled();
+      expect(pi2.appendEntry).toHaveBeenCalledTimes(1);
+      expect(pi2.appendEntry).toHaveBeenCalledWith(
+        "subagent:manifest-invalid-status",
+        expect.objectContaining({ id: "broken-1" }),
+      );
+    });
+  });
+
+  // ============================================================
+  // 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();
+    });
+  });
+});