@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/__tests__/session-reconstructor.test.ts

@@ -13,10 +13,16 @@ import * as path from "node:path";
 
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
-import { IDENTITY_CUSTOM_TYPE, reconstructFromFile } from "../session-reconstructor.ts";
+import {
+  IDENTITY_CUSTOM_TYPE,
+  readIdentityAnywhere,
+  readIdentityHeader,
+  readIdentityTail,
+  reconstructFromFile,
+} from "../session-reconstructor.ts";
 
 /** 写一行到文件（JSON.stringify + 换行）。 */
-function writeLine(file: number | fs.PathOrFileDescriptor, obj: unknown): void {
+function writeLine(file: number, obj: unknown): void {
   fs.writeSync(file, `${JSON.stringify(obj)}\n`);
 }
 
@@ -77,7 +83,7 @@ describe("reconstructFromFile", () => {
     filePath = path.join(tmpDir, "test.jsonl");
   });
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   function writeJsonl(lines: unknown[]): void {
@@ -113,7 +119,7 @@ describe("reconstructFromFile", () => {
     it("thinking block 累积进 turn.thinking", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
         assistantEntry([
           { type: "thinking", thinking: "let me think" },
           { type: "text", text: "answer" },
@@ -127,7 +133,7 @@ describe("reconstructFromFile", () => {
     it("多 assistant message → 多 turn，result 用空行拼接", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
         assistantEntry([{ type: "text", text: "first" }], { ts: 1000 }),
         assistantEntry([{ type: "text", text: "second" }], { ts: 2000, parentId: undefined }),
       ]);
@@ -190,7 +196,7 @@ describe("reconstructFromFile", () => {
     it("读出 identity 里的 parentRecordId/depth（递归层级）", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "run-2", agent: "w", mode: "sync", task: "t", startedAt: 100, rootSessionId: "sess-A", parentRecordId: "run-1", depth: 2 }),
+        identityEntry({ id: "run-2", agent: "w", mode: "background", task: "t", startedAt: 100, rootSessionId: "sess-A", parentRecordId: "run-1", depth: 2 }),
         assistantEntry([{ type: "text", text: "ok" }]),
       ]);
       const rec = reconstructFromFile(filePath);
@@ -228,7 +234,7 @@ describe("reconstructFromFile", () => {
     it("toolCall + toolResult → InternalToolCall done", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
         assistantEntry([
           { type: "toolCall", id: "call-1", name: "read", arguments: { path: "/x.ts" } },
         ]),
@@ -245,7 +251,7 @@ describe("reconstructFromFile", () => {
     it("toolResult isError → InternalToolCall failed", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
         assistantEntry([
           { type: "toolCall", id: "call-1", name: "bash", arguments: { command: "false" } },
         ]),
@@ -259,7 +265,7 @@ describe("reconstructFromFile", () => {
     it("孤儿 toolResult（无匹配 toolCall）→ 丢弃，不崩", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
         assistantEntry([{ type: "text", text: "ok" }]),
         toolResultEntry("nonexistent", "read"),
       ]);
@@ -276,7 +282,7 @@ describe("reconstructFromFile", () => {
     it("stopReason=error → lastError + error 字段", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
         assistantEntry([{ type: "text", text: "partial" }], {
           stopReason: "error", errorMessage: "API timeout",
         }),
@@ -290,7 +296,7 @@ describe("reconstructFromFile", () => {
     it("stopReason=aborted 无 errorMessage → lastError = 'aborted'", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
         assistantEntry([{ type: "text", text: "" }], { stopReason: "aborted" }),
       ]);
       const rec = reconstructFromFile(filePath);
@@ -301,7 +307,7 @@ describe("reconstructFromFile", () => {
     it("前序 error 但最后 stop → lastError 清除（镜像 turn_end 语义），status=done", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
         assistantEntry([{ type: "text", text: "oops" }], {
           stopReason: "error", errorMessage: "transient", ts: 1000,
         }),
@@ -321,7 +327,7 @@ describe("reconstructFromFile", () => {
     it("tool_start + tool_end + turn_end 条目", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
         assistantEntry([
           { type: "toolCall", id: "c1", name: "read", arguments: { path: "/x.ts" } },
         ]),
@@ -359,7 +365,7 @@ describe("reconstructFromFile", () => {
     it("有 identity 但无 assistant message → undefined", () => {
       writeJsonl([
         headerLine(),
-        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
       ]);
       expect(reconstructFromFile(filePath)).toBeUndefined();
     });
@@ -368,7 +374,7 @@ describe("reconstructFromFile", () => {
       const fd = fs.openSync(filePath, "w");
       fs.writeSync(fd, `${JSON.stringify(headerLine())}\n`);
       fs.writeSync(fd, "THIS IS NOT JSON\n");
-      fs.writeSync(fd, `${JSON.stringify(identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }))}\n`);
+      fs.writeSync(fd, `${JSON.stringify(identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }))}\n`);
       fs.writeSync(fd, `${JSON.stringify(assistantEntry([{ type: "text", text: "survived" }]))}\n`);
       fs.closeSync(fd);
       const rec = reconstructFromFile(filePath);
@@ -376,4 +382,349 @@ describe("reconstructFromFile", () => {
       expect(rec!.result).toBe("survived");
     });
   });
+
+  // ============================================================
+  // 分支覆盖补充（特征锚定，守护行为保持重构）
+  // ============================================================
+  describe("分支覆盖补充（特征锚定）", () => {
+    it("无 session header（第 1 行非 header）→ 该行仍按普通 entry 解析，正常重建", () => {
+      writeJsonl([
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "no header" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec).toBeDefined();
+      expect(rec!.result).toBe("no header");
+    });
+
+    it("首行（header 位）损坏 JSON → 跳过该行，后续行仍解析", () => {
+      const fd = fs.openSync(filePath, "w");
+      fs.writeSync(fd, "CORRUPTED FIRST LINE\n");
+      fs.writeSync(fd, `${JSON.stringify(identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }))}\n`);
+      fs.writeSync(fd, `${JSON.stringify(assistantEntry([{ type: "text", text: "after corrupt header" }]))}\n`);
+      fs.closeSync(fd);
+      const rec = reconstructFromFile(filePath);
+      expect(rec).toBeDefined();
+      expect(rec!.result).toBe("after corrupt header");
+    });
+
+    it("文件只有空白行 → undefined（entries 为空）", () => {
+      fs.writeFileSync(filePath, "\n\n   \n", "utf-8");
+      expect(reconstructFromFile(filePath)).toBeUndefined();
+    });
+
+    it("identity custom entry 的 data 非法（缺 task）→ undefined", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", startedAt: 100 }), // 缺 task
+        assistantEntry([{ type: "text", text: "orphan identity" }]),
+      ]);
+      expect(reconstructFromFile(filePath)).toBeUndefined();
+    });
+
+    it("model_change → model = provider/modelId（多次出现时后写覆盖）", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        { type: "model_change", provider: "p1", modelId: "m1", timestamp: new Date(500).toISOString() },
+        assistantEntry([{ type: "text", text: "first" }], { ts: 1000 }),
+        { type: "model_change", provider: "p2", modelId: "m2", timestamp: new Date(1500).toISOString() },
+        assistantEntry([{ type: "text", text: "second" }], { ts: 2000 }),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.model).toBe("p2/m2");
+    });
+
+    it("model_change 字段非字符串（provider 缺失）→ model 保持空串", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        { type: "model_change", provider: 42, modelId: "m1", timestamp: new Date(500).toISOString() },
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.model).toBe("");
+    });
+
+    it("thinking_level_change → thinkingLevel 恢复；无该 entry → undefined", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        { type: "thinking_level_change", thinkingLevel: "high", timestamp: new Date(500).toISOString() },
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const withLevel = reconstructFromFile(filePath);
+      expect(withLevel!.thinkingLevel).toBe("high");
+
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const withoutLevel = reconstructFromFile(filePath);
+      expect(withoutLevel!.thinkingLevel).toBeUndefined();
+    });
+
+    it("entry.timestamp 非法（Date.parse NaN）→ endedAt 回落 message.timestamp", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        { ...(assistantEntry([{ type: "text", text: "bad ts" }], { ts: 7777 }) as Record<string, unknown>), timestamp: "not-a-date" },
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.endedAt).toBe(7777);
+    });
+
+    it("assistant message 无 content（非数组）→ 空 turn，usage 与 stopReason 均被跳过", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        {
+          type: "message",
+          timestamp: new Date(3000).toISOString(),
+          message: {
+            role: "assistant",
+            content: "not-an-array",
+            usage: { input: 100, output: 100 },
+            stopReason: "error",
+            errorMessage: "boom",
+            timestamp: 3000,
+          },
+        },
+      ]);
+      const rec = reconstructFromFile(filePath);
+      // turn 在 content 校验前已创建 → record 存在
+      expect(rec).toBeDefined();
+      expect(rec!.turnCount).toBe(1);
+      expect(rec!.turns[0].text).toBe("");
+      expect(rec!.totalTokens).toBe(0); // usage 被 continue 跳过
+      expect(rec!.lastError).toBeUndefined(); // stopReason=error 也被跳过
+      expect(rec!.error).toBeUndefined();
+      expect(rec!.endedAt).toBe(3000);
+    });
+
+    it("assistant message content 合法但无 usage → totalTokens 0，正常重建", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        {
+          type: "message",
+          timestamp: new Date(1000).toISOString(),
+          message: {
+            role: "assistant",
+            content: [{ type: "text", text: "no usage" }],
+            stopReason: "stop",
+            timestamp: 1000,
+          },
+        },
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.result).toBe("no usage");
+      expect(rec!.totalTokens).toBe(0);
+    });
+
+    it("孤儿 toolCall（toolResult 未到达）→ toolCalls 空，turn_end label 兜底 'turn'", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "toolCall", id: "c1", name: "read", arguments: { path: "/x" } }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec).toBeDefined();
+      expect(rec!.turns[0].toolCalls).toHaveLength(0);
+      const turnEnd = rec!.eventLog.find((e) => e.type === "turn_end");
+      expect(turnEnd?.label).toBe("turn"); // 空 text turn 的摘要兜底
+    });
+
+    it("stopReason 非 error/aborted/stop（如 length）→ lastError 保持前值不清除", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "oops" }], {
+          stopReason: "error", errorMessage: "transient", ts: 1000,
+        }),
+        assistantEntry([{ type: "text", text: "truncated" }], { stopReason: "length", ts: 2000 }),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.lastError).toBe("transient");
+      expect(rec!.error).toBe("transient");
+    });
+
+    it("toolResult 配对 → result.content/details 透传，startedTs 取 assistant timestamp", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "toolCall", id: "c9", name: "bash", arguments: { command: "ls" } }]),
+        toolResultEntry("c9", "bash", { text: "file1\nfile2" }),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      const tc = rec!.turns[0].toolCalls[0];
+      expect(tc.result).toEqual({ content: [{ type: "text", text: "file1\nfile2" }], details: undefined });
+      expect(tc.startedTs).toBe(1000);
+    });
+
+    it("identity 的 chatMode/worktree/forkDepth 经展开透传到 record", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "background", task: "t", startedAt: 100, chatMode: true, worktree: true, forkDepth: 2 }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.chatMode).toBe(true);
+      expect(rec!.worktree).toBe(true);
+      expect(rec!.forkDepth).toBe(2);
+    });
+  });
+});
+
+// ============================================================
+// 轻量 identity 扫描（readIdentityHeader / readIdentityTail / readIdentityAnywhere）
+// ============================================================
+// 直测三入口（parseIdentityFromText 的宿主）：头/尾窗口命中、预筛、从后往前、
+// 归一化 fallback、损坏行跳过。
+describe("轻量 identity 扫描（readIdentityHeader / readIdentityTail / readIdentityAnywhere）", () => {
+  let tmpDir: string;
+  let filePath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sr-identity-scan-"));
+    filePath = path.join(tmpDir, "scan.jsonl");
+  });
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  /** 写原始文本行（不经 JSON.stringify——填充行/截断行构造用）。 */
+  function writeRaw(lines: string[]): void {
+    fs.writeFileSync(filePath, lines.map((l) => `${l}\n`).join(""), "utf-8");
+  }
+
+  /** >64KB 的无特征填充行（预筛跳过，永不被 JSON.parse）。 */
+  const fillerLine = "F".repeat(70 * 1024);
+
+  it("identity 在头部 → 读出身份 + identity 之前途经的 model/thinkingLevel", () => {
+    writeRaw([
+      JSON.stringify(headerLine()),
+      JSON.stringify({ type: "model_change", provider: "p1", modelId: "m1", timestamp: new Date(500).toISOString() }),
+      JSON.stringify({ type: "thinking_level_change", thinkingLevel: "high", timestamp: new Date(600).toISOString() }),
+      JSON.stringify(identityEntry({
+        id: "bg-9", agent: "worker", mode: "sync", task: "scan", startedAt: 42,
+        slug: "s9", rootSessionId: "sess-R", depth: 1, forkDepth: 0,
+      })),
+    ]);
+    expect(readIdentityHeader(filePath)).toEqual({
+      id: "bg-9",
+      agent: "worker",
+      mode: "sync",
+      task: "scan",
+      slug: "s9",
+      startedAt: 42,
+      rootSessionId: "sess-R",
+      parentRecordId: undefined,
+      depth: 1,
+      forkDepth: 0,
+      chatMode: undefined,
+      worktree: undefined,
+      model: "p1/m1",
+      thinkingLevel: "high",
+      sessionFile: filePath,
+    });
+  });
+
+  it("identity 之后的 model_change 不捕获（找到即停）", () => {
+    writeRaw([
+      JSON.stringify(headerLine()),
+      JSON.stringify(identityEntry({ id: "bg-8", agent: "w", mode: "background", task: "t", startedAt: 1 })),
+      JSON.stringify({ type: "model_change", provider: "late", modelId: "m", timestamp: new Date(900).toISOString() }),
+    ]);
+    expect(readIdentityHeader(filePath)?.model).toBe("");
+  });
+
+  it("头部无 identity → readIdentityHeader undefined", () => {
+    writeRaw([JSON.stringify(headerLine()), JSON.stringify({ type: "model_change", provider: "p", modelId: "m" })]);
+    expect(readIdentityHeader(filePath)).toBeUndefined();
+  });
+
+  it("文件缺失 → 三入口均 undefined（不抛）", () => {
+    const missing = path.join(tmpDir, "nope.jsonl");
+    expect(readIdentityHeader(missing)).toBeUndefined();
+    expect(readIdentityTail(missing)).toBeUndefined();
+    expect(readIdentityAnywhere(missing)).toBeUndefined();
+  });
+
+  it("identity 仅在尾部（>64KB 填充）→ header miss / tail 命中 / anywhere 命中", () => {
+    writeRaw([
+      JSON.stringify(headerLine()),
+      fillerLine,
+      JSON.stringify(identityEntry({ id: "bg-tail", agent: "w", mode: "background", task: "t", startedAt: 7 })),
+    ]);
+    expect(readIdentityHeader(filePath)).toBeUndefined();
+    const tail = readIdentityTail(filePath);
+    expect(tail?.id).toBe("bg-tail");
+    // model/thinkingLevel 在尾部窗口外 → best-effort 空/undefined
+    expect(tail?.model).toBe("");
+    expect(tail?.thinkingLevel).toBeUndefined();
+    expect(readIdentityAnywhere(filePath)?.id).toBe("bg-tail");
+  });
+
+  it("尾部多轮 identity → tail/anywhere 从后往前取最后一条（最新鲜）", () => {
+    writeRaw([
+      JSON.stringify(headerLine()),
+      fillerLine,
+      JSON.stringify(identityEntry({ id: "bg-old", agent: "w", mode: "background", task: "t", startedAt: 1 })),
+      JSON.stringify(identityEntry({ id: "bg-new", agent: "w", mode: "background", task: "t2", startedAt: 2 })),
+    ]);
+    expect(readIdentityTail(filePath)?.id).toBe("bg-new");
+    expect(readIdentityAnywhere(filePath)?.id).toBe("bg-new");
+  });
+
+  it("尾部块首行残缺（含特征串的截断 JSON）→ 跳过该行，后续行仍命中", () => {
+    writeRaw([
+      JSON.stringify(headerLine()),
+      fillerLine,
+      '{"type":"custom","customType":"subagent-identity","data":{"id":"trunc"', // 截断行
+      JSON.stringify(identityEntry({ id: "bg-after-trunc", agent: "w", mode: "background", task: "t", startedAt: 3 })),
+    ]);
+    expect(readIdentityTail(filePath)?.id).toBe("bg-after-trunc");
+  });
+
+  it("旧 identity（parentSessionId、无 slug/depth）→ rootSessionId fallback + slug 兜底空串 + depth 0", () => {
+    writeRaw([
+      JSON.stringify(headerLine()),
+      JSON.stringify(identityEntry({ id: "bg-old", agent: "w", mode: "background", task: "t", startedAt: 1, parentSessionId: "sess-legacy" })),
+    ]);
+    expect(readIdentityHeader(filePath)).toMatchObject({
+      id: "bg-old",
+      slug: "",
+      rootSessionId: "sess-legacy",
+      depth: 0,
+      forkDepth: undefined,
+    });
+  });
+
+  it("identity 的 chatMode/worktree 透传到轻量 recon", () => {
+    writeRaw([
+      JSON.stringify(headerLine()),
+      JSON.stringify(identityEntry({ id: "bg-chat", agent: "w", mode: "background", task: "t", startedAt: 1, chatMode: true, worktree: true })),
+    ]);
+    expect(readIdentityHeader(filePath)).toMatchObject({ chatMode: true, worktree: true });
+  });
+
+  it("identity data 非法（缺 task）→ 各入口 undefined", () => {
+    writeRaw([
+      JSON.stringify(headerLine()),
+      JSON.stringify(identityEntry({ id: "bg-bad", agent: "w", mode: "background", startedAt: 1 })), // 缺 task
+    ]);
+    expect(readIdentityHeader(filePath)).toBeUndefined();
+    expect(readIdentityTail(filePath)).toBeUndefined();
+    expect(readIdentityAnywhere(filePath)).toBeUndefined();
+  });
+
+  it("损坏行（无特征串）预筛跳过，identity 行仍命中", () => {
+    writeRaw([
+      "THIS IS NOT JSON",
+      JSON.stringify(identityEntry({ id: "bg-prefilter", agent: "w", mode: "background", task: "t", startedAt: 5 })),
+    ]);
+    expect(readIdentityHeader(filePath)?.id).toBe("bg-prefilter");
+  });
 });

package/src/execution/__tests__/session-runner-branch-cache-lru.test.ts

@@ -0,0 +1,110 @@
+// src/execution/__tests__/session-runner-branch-cache-lru.test.ts
+//
+// [LC-8/T6③] branchCache LRU 上界。
+//
+// 背景（设计 §4.3 LC-8）：缓存 key=cwd，worktree 路径每次唯一 → 模块级 Map 永不淘汰，
+// 条目按 path 永久累积（长寿命 orchestrator 内存无界，实锤·轻微）。T6③ 加 LRU 上限
+// BRANCH_CACHE_MAX_ENTRIES=64（常量导出）。
+//
+// 覆盖（验收：65 个路径插入后规模 64，最旧被淘汰）：
+//   - 65 次 miss 插入 → size 封顶 64，execFile 恰 65 次；
+//   - 最旧条目已被淘汰（再查重新 spawn git），次旧条目仍在（LRU 只淘汰最旧）；
+//   - get 命中刷新 LRU 序（touch 后不再是淘汰候选）；
+//   - 常量导出值 = 64。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// buildEnvBlock 用 execFile 异步取 git branch：按 opts.cwd 回填可区分的 branch 名。
+const { execFileMock } = vi.hoisted(() => ({ execFileMock: vi.fn() }));
+vi.mock("node:child_process", async () => {
+  const actual = await import("node:child_process");
+  return { ...actual, execFile: execFileMock };
+});
+
+// Mock 共享 logger（buildEnvBlock 的 git 失败 debug 留痕不落真实日志盘）。
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+import {
+  BRANCH_CACHE_MAX_ENTRIES,
+  _getBranchCacheSizeForTest,
+  _resetBranchCacheForTest,
+  buildEnvBlock,
+} from "../engine/engines/pi/session-runner.ts";
+
+/** execFile mock 回填 br-<cwd>（branch 与 cwd 一一对应，淘汰行为可断言）。 */
+function stubGitBranchSuccess(): void {
+  execFileMock.mockImplementation(
+    (
+      _cmd: string,
+      _args: readonly string[],
+      opts: { cwd?: string },
+      cb: (err: Error | null, stdout?: string, stderr?: string) => void,
+    ) => cb(null, `br-${opts?.cwd ?? "unknown"}`, ""),
+  );
+}
+
+beforeEach(() => {
+  _resetBranchCacheForTest();
+  stubGitBranchSuccess();
+});
+
+afterEach(() => {
+  _resetBranchCacheForTest();
+  execFileMock.mockReset();
+  loggerMock.debug.mockClear();
+});
+
+describe("[LC-8] branchCache LRU 上界", () => {
+  it("常量导出 BRANCH_CACHE_MAX_ENTRIES = 64", () => {
+    expect(BRANCH_CACHE_MAX_ENTRIES).toBe(64);
+  });
+
+  it("65 个路径插入后规模封顶 64，最旧被淘汰（重新 spawn git）", async () => {
+    const cwds = Array.from({ length: BRANCH_CACHE_MAX_ENTRIES + 1 }, (_, i) => `/tmp/lru-cwd-${i}`);
+    for (const cwd of cwds) {
+      const block = await buildEnvBlock(cwd);
+      expect(block).toContain(`Git branch: br-${cwd}`);
+    }
+    // 65 次 miss 插入，第 65 次插入时淘汰最旧（cwd-0）→ execFile 恰 65 次、规模 64
+    expect(execFileMock).toHaveBeenCalledTimes(BRANCH_CACHE_MAX_ENTRIES + 1);
+    expect(_getBranchCacheSizeForTest()).toBe(BRANCH_CACHE_MAX_ENTRIES);
+
+    // 最旧（cwd-0）已被 LRU 淘汰 → 再次查询重新 spawn git（66 次）；重插后淘汰次旧
+    //（cwd-1），更近插入的 cwd-2 不受影响
+    const block0 = await buildEnvBlock("/tmp/lru-cwd-0");
+    expect(block0).toContain("Git branch: br-/tmp/lru-cwd-0");
+    expect(execFileMock).toHaveBeenCalledTimes(BRANCH_CACHE_MAX_ENTRIES + 2);
+
+    // cwd-2（仍近插入序）仍在缓存 → 查询不再 spawn（仍 66 次）
+    await buildEnvBlock("/tmp/lru-cwd-2");
+    expect(execFileMock).toHaveBeenCalledTimes(BRANCH_CACHE_MAX_ENTRIES + 2);
+  });
+
+  it("get 命中刷新 LRU 序：被 touch 的条目不再是最旧淘汰候选", async () => {
+    const cwdA = "/tmp/lru-touch-a";
+    const cwdB = "/tmp/lru-touch-b";
+    await buildEnvBlock(cwdA); // A 先插
+    await buildEnvBlock(cwdB); // B 后插
+    expect(execFileMock).toHaveBeenCalledTimes(2);
+
+    await buildEnvBlock(cwdA); // 命中并 touch → A 变最新，B 变最旧；零 spawn
+    expect(execFileMock).toHaveBeenCalledTimes(2);
+
+    // 再插 63 个新条目挤爆缓存（2 + 63 = 65 → 淘汰恰 1 个最旧）：B（最旧）被淘汰、
+    // A（被 touch 过，次新）存活
+    for (let i = 0; i < BRANCH_CACHE_MAX_ENTRIES - 1; i++) {
+      await buildEnvBlock(`/tmp/lru-flood-${i}`);
+    }
+    expect(_getBranchCacheSizeForTest()).toBe(BRANCH_CACHE_MAX_ENTRIES);
+    const spawnsAfterFlood = execFileMock.mock.calls.length;
+
+    await buildEnvBlock(cwdA); // A 被 touch 过 → 仍在缓存
+    expect(execFileMock).toHaveBeenCalledTimes(spawnsAfterFlood);
+
+    await buildEnvBlock(cwdB); // B 最早未 touch → 已被淘汰，重新 spawn
+    expect(execFileMock).toHaveBeenCalledTimes(spawnsAfterFlood + 1);
+  });
+});