@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/execution/__tests__/format.test.ts

@@ -70,15 +70,11 @@ describe("statusGlyph", () => {
   });
 
   it("done → checkmark, success", () => {
-    expect(statusGlyph("done")).toEqual({ icon: "✓", color: "success" });
+    expect(statusGlyph("closed")).toEqual({ icon: "✓", color: "success" });
   });
 
-  it("failed → cross, error", () => {
-    expect(statusGlyph("failed")).toEqual({ icon: "✗", color: "error" });
-  });
-
-  it("cancelled → square, muted", () => {
-    expect(statusGlyph("cancelled")).toEqual({ icon: "■", color: "muted" });
+  it("closed → checkmark, success", () => {
+    expect(statusGlyph("closed")).toEqual({ icon: "✓", color: "success" });
   });
 });
 
@@ -260,6 +256,134 @@ describe("truncLine", () => {
   });
 });
 
+// ============================================================
+// truncLine — legacy 对拍（indexOf 化重构的逐字节等价锚定）
+// ============================================================
+
+/**
+ * 旧实现参照：改造前的 per-char 版本，逐字取自 git 历史（093e28fe3~1 的
+ * format.ts truncLine）。现行实现（indexOf("\\x1b") 段跳过）必须与其逐字节
+ * 等价——本函数即对拍 oracle，与 helpers-bounded-serialize.test.ts 的
+ * legacySerialize 同形态（参照物随测试落盘，防「验证只存在于改造当时」）。
+ */
+const legacySegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+function legacyTruncLine(text: string, maxWidth: number): string {
+  if (maxWidth <= 0) return "";
+  const flat = text.replace(/[\r\n]+/g, " ");
+  if (visibleWidth(flat) <= maxWidth) return flat;
+
+  const targetWidth = Math.max(0, maxWidth - 1);
+  let result = "";
+  let currentWidth = 0;
+  let activeStyles: string[] = [];
+  let i = 0;
+
+  while (i < flat.length) {
+    // 捕获 ANSI SGR 序列
+    const ansiMatch = flat.slice(i).match(/^\x1b\[[0-9;]*m/);
+    if (ansiMatch) {
+      const code = ansiMatch[0];
+      result += code;
+
+      if (code === "\x1b[0m" || code === "\x1b[m") {
+        activeStyles = []; // reset → 清空栈
+      } else {
+        activeStyles.push(code);
+      }
+      i += code.length;
+      continue;
+    }
+
+    // 找到下一段纯文本(非 ANSI)的边界
+    let end = i;
+    while (end < flat.length && !flat.slice(end).match(/^\x1b\[[0-9;]*m/)) {
+      end++;
+    }
+
+    // 按 grapheme 迭代这段文本,累加到 targetWidth
+    const textPortion = flat.slice(i, end);
+    for (const seg of legacySegmenter.segment(textPortion)) {
+      const grapheme = seg.segment;
+      const graphemeWidth = visibleWidth(grapheme);
+
+      if (currentWidth + graphemeWidth > targetWidth) {
+        return result + activeStyles.join("") + "…" + (activeStyles.length ? "\x1b[0m" : "");
+      }
+
+      result += grapheme;
+      currentWidth += graphemeWidth;
+    }
+    i = end;
+  }
+
+  // 理论上 visibleWidth 检查已提前返回,此行兜底
+  return result + activeStyles.join("") + "…" + (activeStyles.length ? "\x1b[0m" : "");
+}
+
+/** 确定性 PRNG（mulberry32）：fuzz 用例固定 seed 生成，失败可按 case 编号 + seed 复现。 */
+function mulberry32(seed: number): () => number {
+  let s = seed | 0;
+  return () => {
+    s = (s + 0x6d2b79f5) | 0;
+    let t = Math.imul(s ^ (s >>> 15), 1 | s);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** 定向混排片段池：ASCII / CJK / emoji（含肤色修饰与 ZWJ 组合）/ SGR / 非 SGR ESC（OSC、CSI-K、裸 ESC）/ 换行。 */
+const FUZZ_PIECES = [
+  "plain", " ", "a", "0", "MiXeD-Case_123",
+  "你好世界", "汉字宽度测试", "日本語テキスト",
+  "😀", "😁😂🤣", "👍🏽", "👨‍👩‍👧‍👦", "é", "é",
+  "\x1b[31m", "\x1b[0m", "\x1b[m", "\x1b[1;32m", "\x1b[38;5;196m",
+  "\x1b[K", "\x1b]0;title\x07", "\x1bZ", "\x1b",
+  "\n", "\r\n",
+];
+
+function genFuzzText(rand: () => number): string {
+  const pieceCount = Math.floor(rand() * 40);
+  let out = "";
+  for (let p = 0; p < pieceCount; p++) {
+    out += FUZZ_PIECES[Math.floor(rand() * FUZZ_PIECES.length)];
+  }
+  return out;
+}
+
+describe("truncLine — legacy 对拍（per-char 参照逐字节等价）", () => {
+  it("定向 fuzz：300 随机 ESC/SGR/CJK/emoji 混排用例（固定 seed 可复现）与旧实现逐字节一致", () => {
+    const rand = mulberry32(20260815);
+    let truncated = 0;
+    for (let i = 0; i < 300; i++) {
+      const text = genFuzzText(rand);
+      const maxWidth = Math.floor(rand() * 61); // 0..60，含 0/1 边界
+      const actual = truncLine(text, maxWidth);
+      expect(
+        actual,
+        `case #${i} text=${JSON.stringify(text)} maxWidth=${maxWidth}`,
+      ).toBe(legacyTruncLine(text, maxWidth));
+      if (actual.endsWith("…")) truncated++;
+    }
+    // 前置有效性：fuzz 确实命中了截断路径（否则对拍只测了「宽度内原样返回」早退分支）
+    expect(truncated).toBeGreaterThan(100);
+  });
+
+  it("手工对抗用例：SGR 重叠 / OSC 内截断 / CSI-K 混排 / 串尾裸 ESC", () => {
+    const cases: Array<[string, number]> = [
+      ["\x1b[31m红\x1b[32m绿\x1b[1;4m加粗下划线尾巴超宽截断点", 9],
+      ["AB\x1b]0;title\x07CDEFGHIJKLMNOP", 10],
+      ["\x1b[31mred\x1b[K\x1b[32mgreen tail past width", 10],
+      ["text almost at width limit\x1b", 22],
+      ["before \x1bZ after bare esc tail", 12],
+      ["\x1b[m你\x1b[0m好\x1b[38;5;196m世👨‍👩‍👧‍👦界".repeat(3), 14],
+    ];
+    for (const [text, maxWidth] of cases) {
+      expect(truncLine(text, maxWidth)).toBe(legacyTruncLine(text, maxWidth));
+    }
+  });
+});
+
 // ============================================================
 // wrapText
 // ============================================================

package/src/execution/__tests__/gc-timer.test.ts

@@ -0,0 +1,184 @@
+// src/execution/__tests__/gc-timer.test.ts
+//
+// [M8] idle record GC 定时器测试（subagent-service.ts startGcTimer，L485-507）。
+//
+// 背景：GC 定时器（1h interval 扫描 + isResumable && idleSince 30 天 TTL + store.archive）
+// 此前零测试覆盖——所有相关测试把 startGcTimer mock 成 no-op（index-session-start /
+// crash-recovery / stream-sink-guard / session-start-reaper / index-session-start-identity）。
+// 误判 isResumable/idleSince 会把可续聊 record 从内存错误归档（用户数据路径），
+// 或永不触发（内存驻留失效）——两个方向都无回归拦截。
+//
+// 本文件用真实 SubagentService + 真实 startGcTimer（不 mock GC 逻辑本身），仅 mock
+// session-runner（import 链依赖 + isResumable 的 hasLiveProcessHandle 查询点）与 logger。
+// timer 全部 vi.useFakeTimers，不真实等待。
+
+import type { ChildProcess } from "node:child_process";
+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";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn(), info: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({ getLogger: () => loggerMock }));
+
+// mock session-runner：runSpawn/killAllSpawnedChildren 占位（import 链需要），
+// getChildByRecord 默认返回 undefined（无活进程 → isResumable=true），用例内按需覆盖。
+vi.mock("../session-runner.ts", () => ({
+  runSpawn: vi.fn(),
+  killAllSpawnedChildren: vi.fn(),
+  getChildByRecord: vi.fn(() => undefined),
+  spawnedChildren: new Map(),
+}));
+
+import { getChildByRecord } from "../session-runner.ts";
+import { createRecord } from "../execution-record.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import { RecordStore } from "../record-store.ts";
+import { SubagentService } from "../subagent-service.ts";
+import type { ExecutionRecord } from "../types.ts";
+
+const mockGetChildByRecord = vi.mocked(getChildByRecord);
+
+/** 与 startGcTimer 内部常量一致（1h 扫描 / 30 天 TTL）。 */
+const GC_INTERVAL_MS = 60 * 60 * 1000;
+const IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** initSession 注入的最小 pi duck-type（同 subagent-service PiLike 形状，结构匹配即可）。 */
+interface PiStub {
+  appendEntry(customType: string, data?: unknown): void;
+  events: { emit(channel: string, data: unknown): void };
+  sendMessage(
+    message: { customType: string; content: string; display: boolean; details?: unknown },
+    options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+  ): void;
+}
+
+function makePi(): PiStub {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  };
+}
+
+/** 构造 running + 无活进程 + 指定 idleSince 的 record（GC 扫描的目标态）。
+ *  listAllActive 只返回 status==="running"（createRecord 初始即 running）。 */
+function makeIdleRecord(id: string, idleSince: number): ExecutionRecord {
+  const record = createRecord(id, {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "background",
+    task: "test",
+    slug: "test",
+    startedAt: idleSince,
+    rootSessionId: "root-session",
+    chatMode: true,
+    controller: new AbortController(),
+  });
+  record.idleSince = idleSince;
+  return record;
+}
+
+/** 暴露私有字段供测试读取 store。 */
+interface ServiceInternals {
+  store: RecordStore;
+}
+
+describe("[M8] idle record GC 定时器（startGcTimer）", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "gc-timer-"));
+    const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
+    service = new SubagentService({ cwd: agentDir, modelService });
+    service.initSession({ pi: makePi(), sessionId: "root-session" });
+    store = (service as unknown as ServiceInternals).store;
+    mockGetChildByRecord.mockReset();
+    // 默认无活进程（isResumable=true）——Path B：进程已回收、可冷路径 resume 的等待续聊态
+    mockGetChildByRecord.mockImplementation(() => undefined);
+    loggerMock.warn.mockClear();
+  });
+
+  afterEach(() => {
+    service.dispose();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+    vi.useRealTimers();
+  });
+
+  it("TTL 边界：超 1ms 归档、差 1ms 不归档（同一轮扫描）", () => {
+    // idleSince 相对 interval 首次触发时刻（fake clock + 1h）构造：
+    //   over  = fireAt - TTL - 1 → 扫描时 age = TTL + 1 > TTL → archive
+    //   under = fireAt - TTL + 1 → 扫描时 age = TTL - 1 ≤ TTL → 留内存
+    const fireAt = Date.now() + GC_INTERVAL_MS;
+    store.register(makeIdleRecord("sa-over", fireAt - IDLE_TTL_MS - 1));
+    store.register(makeIdleRecord("sa-under", fireAt - IDLE_TTL_MS + 1));
+
+    service.startGcTimer();
+    vi.advanceTimersByTime(GC_INTERVAL_MS);
+
+    expect(store.getMutable("sa-over")).toBeUndefined(); // archive 从内存移除
+    expect(store.getMutable("sa-under")).toBeDefined(); // 未超 TTL 留内存
+    expect(loggerMock.warn).toHaveBeenCalledTimes(1);
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining("GC: archiving idle record sa-over"),
+    );
+  });
+
+  it("有活进程的 record 不归档（isResumable=false，即使 idleSince 超 TTL）", () => {
+    const fireAt = Date.now() + GC_INTERVAL_MS;
+    // Path A：进程保活等待续聊（idle timer armed、child 未 kill）——归档会让活进程失管
+    store.register(makeIdleRecord("sa-live", fireAt - IDLE_TTL_MS - 1));
+    mockGetChildByRecord.mockImplementation(
+      (id: string): ChildProcess | undefined =>
+        id === "sa-live" ? ({ killed: false } as unknown as ChildProcess) : undefined,
+    );
+
+    service.startGcTimer();
+    vi.advanceTimersByTime(GC_INTERVAL_MS);
+
+    expect(store.getMutable("sa-live")).toBeDefined(); // 有活进程 → 不归档
+    expect(loggerMock.warn).not.toHaveBeenCalled();
+  });
+
+  it("每小时重复扫描：上一轮差 1ms 的 record 下一轮超龄被归档", () => {
+    const fireAt = Date.now() + GC_INTERVAL_MS;
+    store.register(makeIdleRecord("sa-late", fireAt - IDLE_TTL_MS + 1));
+
+    service.startGcTimer();
+    vi.advanceTimersByTime(GC_INTERVAL_MS);
+    expect(store.getMutable("sa-late")).toBeDefined(); // 第一轮：age = TTL - 1，未到
+
+    vi.advanceTimersByTime(GC_INTERVAL_MS); // 第二轮：age = TTL + 1h - 1 > TTL
+    expect(store.getMutable("sa-late")).toBeUndefined();
+  });
+
+  it("startGcTimer 幂等：重复调用不产生第二个 interval", () => {
+    const fireAt = Date.now() + GC_INTERVAL_MS;
+    store.register(makeIdleRecord("sa-over", fireAt - IDLE_TTL_MS - 1));
+
+    service.startGcTimer();
+    service.startGcTimer(); // 已有 timer 直接 return（防重复 interval）
+    vi.advanceTimersByTime(GC_INTERVAL_MS);
+
+    // 同一 record 一轮只扫一次（重复 interval 会对同一 record 产生第二条 GC warn）
+    expect(loggerMock.warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("dispose 后 interval 停止：超 TTL record 不再被归档", () => {
+    service.startGcTimer();
+    vi.advanceTimersByTime(GC_INTERVAL_MS); // 第一轮正常触发
+    service.dispose(); // stopGcTimer + disposeAllRecords
+
+    // dispose 后塞入超 TTL record，interval 已停 → 无论推进多久都不归档
+    store.register(makeIdleRecord("sa-after-dispose", Date.now() - IDLE_TTL_MS - 1));
+    vi.advanceTimersByTime(GC_INTERVAL_MS * 10);
+
+    expect(store.getMutable("sa-after-dispose")).toBeDefined();
+  });
+});

package/src/execution/__tests__/get-record-for-action-restart.test.ts

@@ -0,0 +1,254 @@
+// src/execution/__tests__/get-record-for-action-restart.test.ts
+//
+// [M10] getRecordForAction 跨重启磁盘重建分支测试（subagent-service.ts L933-951）。
+//
+// 背景：内存 miss → collectRecords(1000,"all",undefined).find(status==="running") →
+// createRecord({chatMode: true}) → register → 回填 sessionFile/round。代码注释
+// （L946-949）自设强制约束「改动此处必须带 S3 回归场景（跨重启 message 续聊验证）」
+// ——该 S3 场景此前不存在，分支零测试。该分支含多个仅此处独有的决策：
+//   - 无条件 chatMode: true（v4 A-3 跨重启恢复入口，V3 方案 A 方向）
+//   - rootSessionFilter 传 undefined 后置校验（异树仍 throw not owned）
+//   - sessionFile/round 从磁盘重建结果回填（round 无磁盘持久化 → undefined）
+//
+// fixture 构造参照 record-store.test.ts 的 writeSessionJsonl（真实 .jsonl 文件，
+// identity custom entry + assistant message；无 .alive sidecar → record-store
+// sidecar 矩阵分支 4 → status="running" 跨重启可续聊态）。
+
+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";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn(), info: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({ getLogger: () => loggerMock }));
+
+// mock session-runner：import 链需要（getRecordForAction 本身不调 spawn，仅守卫读
+// hasLiveProcessHandle——默认无活进程，与跨重启场景一致）。
+vi.mock("../session-runner.ts", () => ({
+  runSpawn: vi.fn(),
+  killAllSpawnedChildren: vi.fn(),
+  getChildByRecord: vi.fn(() => undefined),
+  spawnedChildren: new Map(),
+}));
+
+import { writeFinalized } from "../finalized-marker.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import { getSubagentSessionDir } from "../path-encoding.ts";
+import { RecordStore } from "../record-store.ts";
+import { SubagentService } from "../subagent-service.ts";
+
+// 身份 env 名（与 subagent-service.ts 常量一致；beforeEach/afterEach 清理防泄漏——
+// 测试进程可能继承 subagent env，会污染 rootCwd 编码目录与 sessionRootId 基线）。
+const IDENTITY_ENV_KEYS = [
+  "PI_SUBAGENT_ROOT_SESSION_ID",
+  "PI_SUBAGENT_SELF_RECORD_ID",
+  "PI_SUBAGENT_DEPTH",
+  "PI_SUBAGENT_ROOT_CWD",
+  "PI_SUBAGENT_FORK_DEPTH",
+] as const;
+
+/** initSession 注入的最小 pi duck-type（同 subagent-service PiLike 形状，结构匹配即可）。 */
+interface PiStub {
+  appendEntry(customType: string, data?: unknown): void;
+  events: { emit(channel: string, data: unknown): void };
+  sendMessage(
+    message: { customType: string; content: string; display: boolean; details?: unknown },
+    options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+  ): void;
+}
+
+function makePi(): PiStub {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  };
+}
+
+/** 写一个最小合法 session.jsonl（session header + identity entry + 1 条 assistant message）。
+ *  不写任何 sidecar（.alive/.cancelled/.finalized）→ sidecar 矩阵分支 4 → running。 */
+function writeSessionJsonl(
+  sessionsDir: string,
+  identity: {
+    id: string;
+    rootSessionId: string;
+    parentRecordId?: string;
+    depth?: number;
+    chatMode?: boolean;
+    worktree?: boolean;
+  },
+): string {
+  const file = path.join(sessionsDir, `${identity.id}.jsonl`);
+  const startedAt = 1_700_000_000_000;
+  const lines = [
+    JSON.stringify({
+      type: "session",
+      version: 3,
+      id: "sess-uuid",
+      timestamp: new Date(startedAt).toISOString(),
+      cwd: "/tmp",
+    }),
+    JSON.stringify({
+      type: "custom",
+      id: "id-1",
+      parentId: null,
+      timestamp: new Date(startedAt).toISOString(),
+      customType: "subagent-identity",
+      data: {
+        id: identity.id,
+        agent: "general-purpose",
+        mode: "background",
+        task: "restart recovery task",
+        slug: "restart-test",
+        startedAt,
+        rootSessionId: identity.rootSessionId,
+        ...(identity.parentRecordId !== undefined ? { parentRecordId: identity.parentRecordId } : {}),
+        ...(identity.depth !== undefined ? { depth: identity.depth } : {}),
+        ...(identity.chatMode !== undefined ? { chatMode: identity.chatMode } : {}),
+        ...(identity.worktree !== undefined ? { worktree: identity.worktree } : {}),
+      },
+    }),
+    JSON.stringify({
+      type: "message",
+      id: "msg-1",
+      parentId: "id-1",
+      timestamp: new Date(startedAt + 1000).toISOString(),
+      message: {
+        role: "assistant",
+        content: [{ type: "text", text: "first round done" }],
+        usage: { input: 10, output: 20, cacheRead: 0, cacheWrite: 0 },
+        stopReason: "stop",
+        timestamp: startedAt + 1000,
+      },
+    }),
+  ];
+  fs.writeFileSync(file, `${lines.join("\n")}\n`, "utf-8");
+  return file;
+}
+
+/** 暴露私有 store 供断言 register 副作用。 */
+interface ServiceInternals {
+  store: RecordStore;
+}
+
+describe("[M10] getRecordForAction 跨重启磁盘重建（S3 回归场景）", () => {
+  let agentDir: string;
+  let sessionsDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+
+  beforeEach(() => {
+    for (const k of IDENTITY_ENV_KEYS) delete process.env[k];
+    agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "restart-recon-"));
+    sessionsDir = getSubagentSessionDir(agentDir, agentDir);
+    fs.mkdirSync(sessionsDir, { recursive: true });
+
+    const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
+    service = new SubagentService({ cwd: agentDir, modelService });
+    // 根进程身份：无 env → sessionRootId = sessionId（自己是 root）、execCtxBaseline = null
+    service.initSession({ pi: makePi(), sessionId: "root-session" });
+    store = (service as unknown as ServiceInternals).store;
+  });
+
+  afterEach(() => {
+    service.dispose();
+    // maxRetries：collectRecords 触发的 fire-and-forget sessions-index 写可能与删除
+    // 并发（ENOTEMPTY 竞态，全量并行跑时机器负载高会放大窗口）
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+    for (const k of IDENTITY_ENV_KEYS) delete process.env[k];
+  });
+
+  it("内存 miss + 磁盘 running（无 .alive）→ 重建 record：chatMode 无条件 true、sessionFile 回填、register 进内存", () => {
+    // identity entry 故意不带 chatMode 字段——证明重建分支的无条件 chatMode:true
+    //（不依赖磁盘是否记录过对话模式标志）
+    const file = writeSessionJsonl(sessionsDir, { id: "sa-restart-1", rootSessionId: "root-session" });
+    expect(store.getMutable("sa-restart-1")).toBeUndefined(); // 前置：内存确无
+
+    const record = service.getRecordForAction("sa-restart-1");
+
+    // [v4 A-3] 无条件 chatMode=true（跨重启恢复入口）
+    expect(record.chatMode).toBe(true);
+    // sessionFile 从磁盘重建结果回填
+    expect(record.sessionFile).toBe(file);
+    // round 从 found 回填：light 磁盘重建无 round（内存态字段，跨重启不恢复）→ undefined
+    expect(record.round).toBeUndefined();
+    // 身份字段从磁盘 identity entry 回填
+    expect(record.agent).toBe("general-purpose");
+    expect(record.task).toBe("restart recovery task");
+    expect(record.slug).toBe("restart-test");
+    expect(record.rootSessionId).toBe("root-session");
+    expect(record.parentRecordId).toBeUndefined();
+    expect(record.status).toBe("running");
+    // register 生效：进内存，二次调用走内存命中（同一引用）
+    expect(store.getMutable("sa-restart-1")).toBe(record);
+    expect(service.getRecordForAction("sa-restart-1")).toBe(record);
+  });
+
+  it("rootSessionId 校验仍生效：异树 record（other-session）→ throw not found or not owned", () => {
+    // rootSessionFilter 传 undefined（扫全量磁盘），异树 record 会被 find 命中并重建，
+    // 但后置校验 record.rootSessionId !== this.sessionRootId 必须拦截
+    writeSessionJsonl(sessionsDir, { id: "sa-foreign", rootSessionId: "other-session" });
+
+    expect(() => service.getRecordForAction("sa-foreign")).toThrow(/not found or not owned/);
+  });
+
+  it("直接父校验仍生效：孙级 record（parentRecordId=sa-parent）→ 主进程 throw direct parent", () => {
+    writeSessionJsonl(sessionsDir, {
+      id: "sa-grand",
+      rootSessionId: "root-session",
+      parentRecordId: "sa-parent",
+      depth: 2,
+    });
+
+    // 重建后 parentRecordId=sa-parent ≠ 主进程 baseline(undefined) → cross-layer 守卫拦截
+    expect(() => service.getRecordForAction("sa-grand")).toThrow(/direct parent/);
+  });
+
+  it(".finalized sidecar（closed 终态）不重建 → throw not found or not owned", () => {
+    const file = writeSessionJsonl(sessionsDir, { id: "sa-fin", rootSessionId: "root-session" });
+    writeFinalized(file); // sidecar 矩阵分支 2 → status=closed → find(status==="running") miss
+
+    expect(() => service.getRecordForAction("sa-fin")).toThrow(/not found or not owned/);
+    expect(store.getMutable("sa-fin")).toBeUndefined(); // 未重建注册
+  });
+
+  // ============================================================
+  // [review round2] 跨重启 worktree 绑定丢失防护
+  // ============================================================
+  // 场景：worktree:true + conversation:true 的 subagent 在父进程重启后续聊。WorktreeHandle
+  // 不可序列化、重建后恒缺失，若无守卫 → 冷路径 resume 的 spawn cwd 静默回落主 repo
+  //（隔离失效，正是 worktree 要防的并发写冲突场景）。
+  it("[review round2] worktree record 跨重启重建 → hadWorktree 标记 + 续聊被拒（行动语言）", async () => {
+    writeSessionJsonl(sessionsDir, {
+      id: "sa-wt",
+      rootSessionId: "root-session",
+      worktree: true,
+    });
+
+    const record = service.getRecordForAction("sa-wt");
+    // hadWorktree 从磁盘 identity entry 的 worktree 标志恢复
+    expect(record.hadWorktree).toBe(true);
+    // handle 无法恢复（不可序列化）
+    expect(record.worktreeHandle).toBeUndefined();
+
+    // 冷路径续聊（无活进程）→ resumeRound 守卫拒绝，不 spawn 回落主 repo
+    await expect(service.deliverMessage(record, "resume after restart", false)).rejects.toThrow(
+      /worktree isolation.*lost when the parent process restarted/,
+    );
+  });
+
+  it("[review round2] 非 worktree record 跨重启重建 → 续聊不受 worktree 守卫拦截（向后兼容）", async () => {
+    // identity entry 无 worktree 字段（旧文件）→ found.worktree undefined → hadWorktree false
+    writeSessionJsonl(sessionsDir, { id: "sa-nowt", rootSessionId: "root-session" });
+
+    const record = service.getRecordForAction("sa-nowt");
+    expect(record.hadWorktree).toBe(false);
+
+    // deliverMessage 冷路径不被 worktree 守卫拦截（resume 正常发起；后续 spawn 编排
+    // 超出本用例关注点——runSpawn 在本文件是 no-op mock）
+    await expect(service.deliverMessage(record, "resume normal", false)).resolves.toBeUndefined();
+  });
+});

package/src/execution/__tests__/helpers/spawn-mock.ts

@@ -24,7 +24,16 @@
 //     const { FakeChild } = await import("./helpers/spawn-mock.ts");
 //     return {
 //       spawn: vi.fn(() => new FakeChild()),
-//       execFileSync: vi.fn(() => ""),
+//       // buildEnvBlock 用 execFile 异步取 git branch：默认 err-first 兜底（catch → branch=""），
+//       // 形态同 worktree-manager.test.ts 的 setupExecFile
+//       execFile: vi.fn(
+//         (
+//           _cmd: string,
+//           _args: readonly string[],
+//           _opts: unknown,
+//           cb: (err: Error | null, stdout?: string, stderr?: string) => void,
+//         ) => cb(new Error("execFile not configured in this test")),
+//       ),
 //     };
 //   });
 //   vi.mock("node:fs", async () => {
@@ -111,9 +120,17 @@ export function lastSpawnedChild<
 /**
  * 等待 runSpawn 内部调到 spawn（拿到 child 控制器）。
  *
- * runSpawn 是 async，spawn 在 mkdirSync + writePromptToTempFile 之后才调（均有微任务/
- * I/O 延迟）。用 setTimeout 轮询 mockSpawn.mock.results，比 vi.waitFor 在该 vitest 版本
- * 下更可靠（vi.waitFor 偶发过早 resolve 导致后续读取竞态）。
+ * runSpawn 是 async，spawn 在 buildEnvBlock + writePromptToTempFile 两个 await 之后才调
+ *（均为微任务级延迟）。用 setTimeout 轮询 mockSpawn.mock.results，比 vi.waitFor 在该
+ * vitest 版本下更可靠（vi.waitFor 偶发过早 resolve 导致后续读取竞态）。
+ *
+ * [快照语义] 等待的是「调用时刻之后**新发生**的一次 spawn」，而非「任意历史 spawn」。
+ * 旧实现只在 results 为空时等待（即只在文件/测试内首次 spawn 有效）：同一文件第二次
+ * runSpawn 时立即返回，而新 runSpawn 尚未跨过 await 到达 spawn → lastSpawnedChild 取回
+ * **上一次**的 child，stdout/close 事件发给已死的旧 child，当前 runSpawn 永远收不到
+ * close → 测试超时。buildEnvBlock 异步化（多一个 await 微任务）后该隐式时序假设失效，
+ * 故改为快照 baseline：等待 results.length 超过调用时的快照值，天然对「每测试/每文件
+ * N 次 spawn」都正确（调用前先记 baseline，本次 runSpawn 的 spawn 必然使 length 增长）。
  *
  * @param mockSpawn 调用方用 `vi.mocked(spawn)` 取回的 mock 引用
  */
@@ -121,7 +138,8 @@ export async function waitForSpawn<
   T extends { mock: { results: unknown[] } },
 >(mockSpawn: T, timeoutMs = 1000): Promise<void> {
   const start = Date.now();
-  while (mockSpawn.mock.results.length === 0) {
+  const baseline = mockSpawn.mock.results.length;
+  while (mockSpawn.mock.results.length <= baseline) {
     if (Date.now() - start > timeoutMs) {
       throw new Error(`spawn was not called within ${timeoutMs}ms`);
     }
@@ -159,8 +177,8 @@ export function mockSessionFileExists(
 // ── record / opts / ctx 构造（3 文件一致的最小合法形状）──
 
 /** 构造最小合法的 ExecutionRecord（runSpawn 入参）。 */
-export function makeRecord() {
-  return createRecord("run-1", {
+export function makeRecord(id = "run-1") {
+  return createRecord(id, {
     agent: "general-purpose",
     model: "test-model",
     mode: "sync",