@zhushanwen/subagent-core 0.8.0 → 0.9.0

package/src/execution/__tests__/run-orchestration.test.ts

@@ -0,0 +1,199 @@
+// src/execution/__tests__/run-orchestration.test.ts
+//
+// [H3/R5 测试归位] run 域执行编排聚合（execution/service/run-orchestration.ts）的
+// 同名域测试文件。本文件用例自 subagent-service.test.ts「execute() worktree 路径」
+// 块整块迁入（用例名与断言零改动，纯移动）；壳级生命周期/查询/emit 面用例留在
+// subagent-service.test.ts。同域姊妹文件：conversation-continuation.test.ts（Continuation
+// 协作面）/ chat-engine-routing.test.ts（引擎编排分叉）/ execute-nesting.test.ts /
+// execute-and-await-worktree.test.ts / delivery-methods.test.ts /
+// stream-sink-retirement.test.ts / explicit-agent-ref-guard.test.ts /
+// subagent-service-notify-gate.test.ts / workflow-agent-dispatch.test.ts（派发链 × run 域协作面）。
+//
+// 覆盖（execute 入口 = RunOrchestration.execute，worktree 与 fork 解耦后）：
+//   1. worktree:true + fork:false → 解耦后正常（不抛 requires fork）
+//   2. worktree:true + fork:true  → 创建 worktree 路径（不抛 requires fork）
+//   3. worktree:false + fork:false → 默认路径（不创建 worktree）
+//   4. create-await 竞态守卫：create 的 await 窗口内 dispose 抢先 → cleanup 被调 +
+//      early-failed 返回（不 kickOff）——「赋值 worktreeHandle → 终态检查 → 轮次
+//      kick-off 同一同步段」不变量的回归锚点。
+//
+// 策略：真实 ModelConfigService 指向 os.tmpdir() 空目录，mock PiLike；本文件不 mock
+// spawn（与 subagent-service.test.ts 文件头约定一致——execute 的 spawn 集成测试在
+// execute-nesting / execute-integration）。
+
+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 { ModelConfigService } from "../model-config-service.ts";
+import type { PiLike } from "../subagent-service.ts";
+import { SubagentService } from "../subagent-service.ts";
+import type { WorktreeManager } from "../worktree-manager.ts";
+
+// ── 工具:建临时 agentDir + 真实 ModelConfigService（自 subagent-service.test.ts 迁移段自持副本）──
+
+function makeTmpAgentDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "subagents-test-"));
+  // agentDir/subagents/ 子目录(config 默认路径会用,空即可)
+  return dir;
+}
+
+function makeModelService(agentDir: string): ModelConfigService {
+  return new ModelConfigService({ agentDir, cwd: agentDir });
+}
+
+function makePi(): PiLike & {
+  appendEntry: ReturnType<typeof vi.fn<(customType: string, data?: unknown) => void>>;
+  events: { emit: ReturnType<typeof vi.fn<(channel: string, data: unknown) => void>> };
+  sendMessage: ReturnType<typeof vi.fn<(message: Parameters<PiLike["sendMessage"]>[0], options?: Parameters<PiLike["sendMessage"]>[1]) => void>>;
+} {
+  return {
+    appendEntry: vi.fn((customType: string, data?: unknown) => {}),
+    events: { emit: vi.fn((channel: string, data: unknown) => {}) },
+    sendMessage: vi.fn(() => {}),
+  };
+}
+
+describe("execute() worktree 路径（worktree 与 fork 解耦）", () => {
+  let agentDir: string;
+  let modelService: ModelConfigService;
+
+  beforeEach(() => {
+    agentDir = makeTmpAgentDir();
+    modelService = makeModelService(agentDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  // ============================================================
+  // worktree（文件隔离）与 fork（上下文继承）已解耦：worktree:true 可独立于 fork 工作
+  // （worktreeManager.create 只看 opts.worktree，不读 fork）。此组验证三种 fork/worktree
+  // 组合下 worktree 路径的行为（均不应抛 'requires fork'——该 guard 已移除）：
+  //   1. worktree:true + fork:false → 解耦后正常（创建 worktree 路径，不抛 requires fork）
+  //   2. worktree:true + fork:true  → 创建 worktree 路径（测试环境 git 失败，抛非 requires fork 错）
+  //   3. worktree:false + fork:false → 默认路径（不创建 worktree）
+  //
+  // 本文件不 mock spawn（保持与源文件头声明一致——execute 集成测试在 execute-nesting /
+  // run-spawn-integration），因此 case 验证「不抛 requires fork」而非「执行完成」：
+  // 执行越过 worktree 创建后在后续步骤（worktreeManager.create 调 git / runSpawn 调
+  // spawn）抛与 fork/worktree 无关的错。用 try/catch 断言抛出的不是 requires fork。
+  // ============================================================
+
+  /** 构造已就绪的 service（initSession + initModel 注入 ctxModel，使 resolveIdentity 不因 model 拗错）。 */
+  function makeReadyService(): SubagentService {
+    const service = new SubagentService({ cwd: agentDir, modelService });
+    service.initSession({ pi: makePi(), sessionId: "s1" });
+    // 注入 modelRegistry + ctxModel：让 resolveIdentity 越过 resolveModel，
+    // 使 guard 之后的失败点稳定在 worktreeManager.create（git）或 runSpawn（spawn），
+    // 而非 modelService.resolveModel——避免与 guard 无关的 model 错误掩盖被测点。
+    modelService.initModel({
+      modelRegistry: {
+        getAvailable: () => [],
+        find: () => undefined,
+        hasConfiguredAuth: () => false,
+      },
+      sessionId: "s1",
+      ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
+    });
+    return service;
+  }
+
+  it("worktree:true + fork:false → 解耦后不抛 'requires fork'（worktree 独立于 fork）", async () => {
+    const service = makeReadyService();
+    // 解耦后 worktree:true+fork:false 不再 throw requires fork（worktreeManager.create 只看 worktree）
+    try {
+      await service.execute({
+        task: "worktree without fork (decoupled)",
+        slug: "test",
+        worktree: true,
+        fork: false,
+        ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
+      });
+    } catch (err) {
+      // 解耦后绝不抛 requires fork（执行继续到 worktreeManager.create/spawn 才可能抛其他错）
+      expect((err as Error).message).not.toMatch(/requires fork/);
+    }
+  });
+
+  it("worktree:true + fork:true → 创建 worktree 路径（不抛 'requires fork'）", async () => {
+    const service = makeReadyService();
+    // 执行继续：先创建 record，然后 worktreeManager.create 调 git（测试环境无 repo → 抛与 fork 无关的错）
+    try {
+      await service.execute({
+        task: "worktree with fork",
+        slug: "test",
+        worktree: true,
+        fork: true,
+        ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
+      });
+      // 若未抛（理论上 worktreeManager.create 在某些环境成功）也 OK——重点是没命中 guard
+    } catch (err) {
+      // guard 放行：抛出的错误绝不能是 "requires fork"
+      expect((err as Error).message).not.toMatch(/requires fork/);
+    }
+  });
+
+  it("worktree:false + fork:false → 默认路径（不创建 worktree，不抛 'requires fork'）", async () => {
+    const service = makeReadyService();
+    // 默认路径：runSpawn 调 child_process.spawn（测试环境无真实 pi → 抛与 fork 无关的错）
+    try {
+      await service.execute({
+        task: "default path",
+        slug: "test",
+        worktree: false,
+        fork: false,
+        ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
+      });
+    } catch (err) {
+      // guard 放行：抛出的错误绝不能是 "requires fork"
+      expect((err as Error).message).not.toMatch(/requires fork/);
+    }
+  });
+
+  // ============================================================
+  // create-await 竞态守卫（Phase 2）：create 的 await 窗口内 dispose/cancel
+  // 可把 record CAS 成 closed——守卫须主动 cleanup + early-failed 返回，不 kickOff。
+  // 实现约束固化：「赋值 record.worktreeHandle → 终态检查 → 轮次 kick-off」
+  // 必须同一同步段（中间禁止 await），本用例即该不变量的回归锚点。
+  // ============================================================
+  it("守卫：create await 窗口内 dispose 抢先 → cleanup 被调 + early-failed 返回（不 kickOff）", async () => {
+    const service = makeReadyService();
+    const wtm = Reflect.get(service, "worktreeManager") as WorktreeManager;
+    const handle = Object.freeze({
+      path: "/tmp/wt-guard",
+      branch: "pi-sub-guard",
+      baseCommit: "abc123",
+      mainCwd: "/repo",
+    }) as Parameters<WorktreeManager["cleanup"]>[0];
+    let resolveCreate!: (h: unknown) => void;
+    vi.spyOn(wtm, "create").mockImplementation(
+      () => new Promise<unknown>((r) => { resolveCreate = r; }) as ReturnType<WorktreeManager["create"]>,
+    );
+    const cleanupSpy = vi.spyOn(wtm, "cleanup").mockResolvedValue(undefined);
+
+    const execP = service.execute({
+      task: "guard test",
+      slug: "test",
+      worktree: true,
+      fork: false,
+      ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
+    });
+    // 微任务推进：record 已建 + execute 挂在 pending create 上
+    await new Promise((r) => { setTimeout(r, 0); });
+    // dispose 抢先（无需 record id）：CAS running → closed，此时 worktreeHandle 仍
+    // undefined（dispose 的 fire-and-forget cleanup 跳过）——守卫是唯一的清理点
+    service.disposeAllRecords("parent-shutdown");
+    resolveCreate(handle);
+
+    const ret = await execP;
+    // 守卫生效：handle 被主动清理（不等 60s reaper）
+    expect(cleanupSpy).toHaveBeenCalledWith(handle);
+    // 返回 early-failed 形态（details.status 已 closed），而非 kickOff 的 running 形态
+    expect(ret.mode).toBe("background");
+    expect(ret.details).toMatchObject({ status: "closed" });
+  });
+});

package/src/execution/__tests__/session-file-gc.test.ts

@@ -154,7 +154,35 @@ describe("maybeCleanupExpiredSessionFiles", () => {
     expect(() => maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd")).not.toThrow();
   });
 
-  // ---- .finalized sidecar 清理 ----
+  // ---- 终态 .state sidecar 清理（L4 合并后新名）+ 兼容期旧名保留清理 ----
+
+  it("deletes .state sidecar along with expired .jsonl", () => {
+    forceCleanupTrigger();
+    const jsonl = createSessionFile("sess-state.jsonl", 31);
+    const state = `${jsonl}.state`;
+    fs.writeFileSync(state, JSON.stringify({ status: "finalized", reason: "gc" }), "utf-8");
+    const targetTime = Date.now() / 1000 - 31 * 86400;
+    fs.utimesSync(state, targetTime, targetTime);
+
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+
+    expect(fs.existsSync(jsonl)).toBe(false);
+    expect(fs.existsSync(state)).toBe(false);
+  });
+
+  it("cleans orphan .state sidecar when .jsonl already gone", () => {
+    forceCleanupTrigger();
+    const subagentsDir = path.join(tmpAgentDir, "subagents");
+    fs.mkdirSync(subagentsDir, { recursive: true });
+    const orphan = path.join(subagentsDir, "dead-session.jsonl.state");
+    fs.writeFileSync(orphan, JSON.stringify({ status: "cancelled", endedAt: 1 }), "utf-8");
+    const targetTime = Date.now() / 1000 - 31 * 86400;
+    fs.utimesSync(orphan, targetTime, targetTime);
+
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+
+    expect(fs.existsSync(orphan)).toBe(false);
+  });
 
   it("deletes .finalized sidecar along with expired .jsonl", () => {
     forceCleanupTrigger();
@@ -230,12 +258,14 @@ describe("maybeCleanupExpiredSessionFiles", () => {
     expect(fs.existsSync(orphan)).toBe(false);
   });
 
-  it("deletes .jsonl + all sidecars (.cancelled, .finalized, .alive) together", () => {
+  it("deletes .jsonl + all sidecars (.state, 兼容期 .cancelled/.finalized, .alive) together", () => {
     forceCleanupTrigger();
     const jsonl = createSessionFile("sess-all-sidecars.jsonl", 31);
+    const state = `${jsonl}.state`;
     const cancelled = `${jsonl}.cancelled`;
     const finalized = `${jsonl}.finalized`;
     const alive = `${jsonl}.alive`;
+    fs.writeFileSync(state, JSON.stringify({ status: "finalized", reason: "gc" }), "utf-8");
     fs.writeFileSync(cancelled, "", "utf-8");
     fs.writeFileSync(finalized, "", "utf-8");
     fs.writeFileSync(alive, JSON.stringify({ pid: 99999, id: "s4", startedAt: Date.now() }), "utf-8");
@@ -246,6 +276,7 @@ describe("maybeCleanupExpiredSessionFiles", () => {
     maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
 
     expect(fs.existsSync(jsonl)).toBe(false);
+    expect(fs.existsSync(state)).toBe(false);
     expect(fs.existsSync(cancelled)).toBe(false);
     expect(fs.existsSync(finalized)).toBe(false);
     expect(fs.existsSync(alive)).toBe(false);
@@ -286,8 +317,8 @@ describe("maybeCleanupExpiredSessionFiles", () => {
     expect(fs.existsSync(worktrees)).toBe(true);
   });
 
-  it("[F2] preserves .json.tmp.* inside records/ (recoverTmpFiles owns them)", () => {
-    // 跳过 .tmp.：session_start 的 recoverTmpFiles 同步处理 tmp，GC 不重复。
+  it("[F2] preserves .json.tmp.* inside records/ (sweepTmpFiles owns them)", () => {
+    // 跳过 .tmp.：session_start 的 sweepTmpFiles 同步处理 tmp，GC 不重复。
     forceCleanupTrigger();
     const tmp = createSessionFile(
       path.join("--Users-x-proj--", "records", "rec-2.json.tmp.123"),

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

@@ -728,3 +728,81 @@ describe("轻量 identity 扫描（readIdentityHeader / readIdentityTail / readI
     expect(readIdentityHeader(filePath)?.id).toBe("bg-prefilter");
   });
 });
+
+// ============================================================
+// [H2 S3] identity 面 origin/parentRunId 透传（写 → 读 → 重建往返保真）
+// ============================================================
+//
+// Gate B S3 FAIL 根因的 identity entry 侧防线：identity custom entry 携带
+// origin/parentRunId 时，reconstructFromFile（全量重建面）与 readIdentityHeader
+// （light 列表面）必须透传；缺省/非法值守卫归一 undefined（= "tool" 语义），
+// 对齐 readEntryOriginFields 主 entry 重建侧守卫。
+describe("[H2 S3] identity 面 origin/parentRunId 透传", () => {
+  let tmpDir: string;
+  let filePath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sr-origin-"));
+    filePath = path.join(tmpDir, "origin.jsonl");
+  });
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  function writeOriginJsonl(identity: object): void {
+    const fd = fs.openSync(filePath, "w");
+    writeLine(fd, headerLine());
+    writeLine(fd, identityEntry(identity));
+    writeLine(fd, assistantEntry([{ type: "text", text: "done" }]));
+    fs.closeSync(fd);
+  }
+
+  it("往返保真：identity(origin=workflow, parentRunId) → 全量重建 + 轻量扫描均透传", () => {
+    writeOriginJsonl({
+      id: "bg-wf", agent: "worker", mode: "background", task: "wf task", startedAt: 10,
+      origin: "workflow", parentRunId: "wf-run-9",
+    });
+
+    const full = reconstructFromFile(filePath);
+    expect(full).toBeDefined();
+    expect(full!.origin).toBe("workflow");
+    expect(full!.parentRunId).toBe("wf-run-9");
+
+    const light = readIdentityHeader(filePath);
+    expect(light).toBeDefined();
+    expect(light!.origin).toBe("workflow");
+    expect(light!.parentRunId).toBe("wf-run-9");
+  });
+
+  it("缺省负向：旧 identity（无 origin/parentRunId）→ 重建两字段 undefined（= tool 语义）", () => {
+    writeOriginJsonl({ id: "bg-old", agent: "w", mode: "background", task: "t", startedAt: 1 });
+
+    expect(reconstructFromFile(filePath)!.origin).toBeUndefined();
+    expect(reconstructFromFile(filePath)!.parentRunId).toBeUndefined();
+    expect(readIdentityHeader(filePath)!.origin).toBeUndefined();
+    expect(readIdentityHeader(filePath)!.parentRunId).toBeUndefined();
+  });
+
+  it("非法值守卫：origin 非白名单 / parentRunId 非 string → 守卫归一 undefined（不抛）", () => {
+    writeOriginJsonl({
+      id: "bg-bad", agent: "w", mode: "background", task: "t", startedAt: 1,
+      origin: "bogus", parentRunId: 42,
+    });
+
+    const full = reconstructFromFile(filePath);
+    expect(full!.origin).toBeUndefined();
+    expect(full!.parentRunId).toBeUndefined();
+    const light = readIdentityHeader(filePath)!;
+    expect(light.origin).toBeUndefined();
+    expect(light.parentRunId).toBeUndefined();
+  });
+
+  it("origin=tool 显式值 → 透传保留（负向判定 `!== \"workflow\"` 依赖真实值）", () => {
+    writeOriginJsonl({
+      id: "bg-tool", agent: "w", mode: "background", task: "t", startedAt: 1,
+      origin: "tool",
+    });
+    expect(reconstructFromFile(filePath)!.origin).toBe("tool");
+    expect(readIdentityHeader(filePath)!.origin).toBe("tool");
+  });
+});

package/src/execution/__tests__/state-marker.test.ts

@@ -0,0 +1,288 @@
+// src/execution/__tests__/state-marker.test.ts
+//
+// state-marker 专属测试（L4 合并：finalized-marker + tombstone-store 两模块收编）。
+//
+// 覆盖四层：
+//   1. 写侧（.state 单一权威）：finalized/cancelled 往返、旧名残留清理；
+//   2. 写侧响亮重试（U1 A3 / §3.4）：3 次指数退避（100ms 起）+ 仍失败 logger.error
+//      响亮暴露返回 false（旧 best-effort 静默语义退役）；
+//   3. 读侧（兼容读）：.state 优先、旧 .finalized / .cancelled 归一、旧名共存优先级
+//   （.cancelled > .finalized，对齐合并前判定分支序）、损坏降级边界；
+//   4. statStateStamp（缓存校验戳）：三文件合并戳的存在性/变化语义。
+
+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";
+
+// [U1 A3] 响亮重试断言需要 error 级日志可观察（对齐 record-store.test.ts mock 模式）。
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({
+  getLogger: () => loggerMock,
+}));
+
+// fs partial mock：writeFileSync 可注错（暂时/持久失败注入），其余转发真实实现
+// （模式对齐 manifest-store-tmp-recovery.test.ts）。ESM namespace 不可 spyOn，
+// 注错必须走模块 mock；真实实现引用收进 hoisted holder（vi.mock factory 先于
+// 模块级 let 初始化执行，裸 let 会 TDZ）。
+type WriteFileSyncFn = typeof import("node:fs").writeFileSync;
+const { writeFileSyncMock, actualWriteRef } = vi.hoisted(() => ({
+  writeFileSyncMock: vi.fn(),
+  actualWriteRef: { current: undefined as WriteFileSyncFn | undefined },
+}));
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  actualWriteRef.current = actual.writeFileSync;
+  return {
+    ...actual,
+    writeFileSync: writeFileSyncMock,
+    default: { ...actual, writeFileSync: writeFileSyncMock },
+  };
+});
+
+import {
+  _setStateMarkerSleepForTest,
+  readStateMarker,
+  statStateStamp,
+  writeCancelledState,
+  writeFinalizedState,
+} from "../state-marker.ts";
+import { writeLegacyCancelledSidecar, writeLegacyFinalizedSidecar } from "./helpers/legacy-sidecar.ts";
+
+describe("state-marker", () => {
+  let tmpDir: string;
+  let sessionFile: string;
+  /** 退避替身记录的延迟序列（fake sleep——免真实等待，可断言指数退避）。 */
+  let sleepDelays: number[];
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "state-marker-test-"));
+    sessionFile = path.join(tmpDir, "2026-01-01_uuid.jsonl");
+    sleepDelays = [];
+    _setStateMarkerSleepForTest((ms) => {
+      sleepDelays.push(ms);
+    });
+    loggerMock.error.mockClear();
+    // 基线 = 真实写（个别用例以 mockImplementationOnce/Implementation 注错覆盖）。
+    if (actualWriteRef.current === undefined) throw new Error("node:fs mock not initialized");
+    writeFileSyncMock.mockReset().mockImplementation(actualWriteRef.current);
+  });
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+    _setStateMarkerSleepForTest(undefined); // 恢复实装同步等待
+    vi.restoreAllMocks();
+  });
+
+  const readStateRaw = (): { status?: unknown; reason?: unknown; endedAt?: unknown } =>
+    JSON.parse(fs.readFileSync(`${sessionFile}.state`, "utf-8")) as Record<string, unknown>;
+
+  // ============================================================
+  // 写侧
+  // ============================================================
+  describe("写侧 .state", () => {
+    it("writeFinalizedState 带 reason → .state {status:finalized, reason}", () => {
+      writeFinalizedState(sessionFile, "user-close");
+      expect(readStateRaw()).toEqual({ status: "finalized", reason: "user-close" });
+      expect(readStateMarker(sessionFile)).toEqual({ status: "finalized", reason: "user-close" });
+    });
+
+    it("writeFinalizedState 无 reason → .state {status:finalized}（死因不可考语义）", () => {
+      writeFinalizedState(sessionFile);
+      expect(readStateRaw()).toEqual({ status: "finalized" });
+      expect(readStateMarker(sessionFile)).toEqual({ status: "finalized" });
+    });
+
+    it("writeCancelledState → .state {status:cancelled, endedAt}", () => {
+      writeCancelledState(sessionFile, 7000);
+      expect(readStateRaw()).toEqual({ status: "cancelled", endedAt: 7000 });
+      expect(readStateMarker(sessionFile)).toEqual({ status: "cancelled", endedAt: 7000 });
+    });
+
+    it("覆盖写：后写的 status 取代前者（单文件单状态，构造性互斥）", () => {
+      writeFinalizedState(sessionFile, "gc");
+      writeCancelledState(sessionFile, 8000);
+      expect(readStateMarker(sessionFile)).toEqual({ status: "cancelled", endedAt: 8000 });
+    });
+
+    it("写 .state 时清理存量旧名 sidecar（.finalized / .cancelled 一并删）", () => {
+      writeLegacyFinalizedSidecar(sessionFile, "gc");
+      writeLegacyCancelledSidecar(sessionFile, {
+        id: "bg-1", status: "cancelled", agent: "w", startedAt: 1, endedAt: 2,
+      });
+
+      writeFinalizedState(sessionFile, "user-close");
+
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(false);
+      expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(false);
+      expect(readStateMarker(sessionFile)).toEqual({ status: "finalized", reason: "user-close" });
+    });
+
+    it("[§3.4] 写路径父目录不存在 → 重试耗尽不抛出、未写入、响亮暴露 + 返回 false", () => {
+      const badPath = path.join(tmpDir, "nonexistent-sub", "session.jsonl");
+      expect(writeFinalizedState(badPath)).toBe(false);
+      expect(writeCancelledState(badPath, 1)).toBe(false);
+      expect(readStateMarker(badPath)).toBeUndefined();
+      // 响亮暴露：每次写函数调用各产出一条 error（终态权威未落必须可见）。
+      expect(loggerMock.error).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  // ============================================================
+  // 写侧响亮重试（U1 A3 / §3.4：3 次指数退避 100ms 起 + 仍失败 logger.error）
+  // ============================================================
+  describe("写侧响亮重试", () => {
+    it("暂时性失败 → 指数退避重试后成功：返回 true，无 error 日志", () => {
+      writeFileSyncMock
+        .mockImplementationOnce(() => {
+          throw new Error("transient EBUSY");
+        })
+        .mockImplementationOnce(() => {
+          throw new Error("transient EACCES");
+        });
+
+      expect(writeFinalizedState(sessionFile, "user-close")).toBe(true);
+      expect(writeFileSyncMock).toHaveBeenCalledTimes(3); // 初始尝试 + 2 次重试后成功
+      expect(sleepDelays).toEqual([100, 200]); // 指数退避：100ms 起
+      expect(loggerMock.error).not.toHaveBeenCalled();
+      expect(readStateMarker(sessionFile)).toEqual({ status: "finalized", reason: "user-close" });
+    });
+
+    it("持久失败 → 4 次尝试（1+3 重试）后返回 false + logger.error 响亮暴露（含恢复指引）", () => {
+      writeFileSyncMock.mockImplementation(() => {
+        throw new Error("ENOSPC: no space left");
+      });
+
+      expect(writeCancelledState(sessionFile, 7000)).toBe(false);
+      expect(writeFileSyncMock).toHaveBeenCalledTimes(4); // 初始 + 3 次重试
+      expect(sleepDelays).toEqual([100, 200, 400]); // 完整指数退避序列
+      expect(loggerMock.error).toHaveBeenCalledTimes(1);
+      const msg = String(loggerMock.error.mock.calls[0]?.[0]);
+      expect(msg).toMatch(/terminal state marker write failed after retries/);
+      expect(msg).toMatch(/record stays running/); // §3.4：不因写失败翻终态的处置指引
+      // 磁盘确无终态位（record 留 running 形态的构造前提）。
+      expect(fs.existsSync(`${sessionFile}.state`)).toBe(false);
+    });
+
+    it("writeCancelledState 同款重试语义（终态二态共用 writeStateMarker）", () => {
+      writeFileSyncMock.mockImplementationOnce(() => {
+        throw new Error("transient");
+      });
+
+      expect(writeCancelledState(sessionFile, 9000)).toBe(true);
+      expect(sleepDelays).toEqual([100]);
+      expect(readStateMarker(sessionFile)).toEqual({ status: "cancelled", endedAt: 9000 });
+    });
+  });
+
+  // ============================================================
+  // 读侧：无 sidecar / .state 边界
+  // ============================================================
+  describe("读侧 .state", () => {
+    it("无任何 sidecar → undefined（未终态化）", () => {
+      expect(readStateMarker(sessionFile)).toBeUndefined();
+    });
+
+    it(".state JSON 损坏 → {status:finalized}（存在性即信号；不误判 cancelled）", () => {
+      fs.writeFileSync(`${sessionFile}.state`, "not-json", "utf-8");
+      expect(readStateMarker(sessionFile)).toEqual({ status: "finalized" });
+    });
+
+    it(".state status 非枚举值 → {status:finalized}（结构不合法降级）", () => {
+      fs.writeFileSync(`${sessionFile}.state`, JSON.stringify({ status: "bogus" }), "utf-8");
+      expect(readStateMarker(sessionFile)).toEqual({ status: "finalized" });
+    });
+
+    it(".state finalized 且 reason 非字符串 → 忽略 reason 字段（不抛）", () => {
+      fs.writeFileSync(`${sessionFile}.state`, JSON.stringify({ status: "finalized", reason: 42 }), "utf-8");
+      expect(readStateMarker(sessionFile)).toEqual({ status: "finalized" });
+    });
+
+    it(".state cancelled 缺 endedAt → {status:cancelled}（endedAt undefined，重建回落 mtime）", () => {
+      fs.writeFileSync(`${sessionFile}.state`, JSON.stringify({ status: "cancelled" }), "utf-8");
+      expect(readStateMarker(sessionFile)).toEqual({ status: "cancelled" });
+    });
+  });
+
+  // ============================================================
+  // 读侧：兼容旧名（存量文件不迁移）
+  // ============================================================
+  describe("读侧兼容旧名", () => {
+    it("旧 .finalized 带内容 → {status:finalized, reason}", () => {
+      writeLegacyFinalizedSidecar(sessionFile, "parent-shutdown");
+      expect(readStateMarker(sessionFile)).toEqual({ status: "finalized", reason: "parent-shutdown" });
+    });
+
+    it("旧 .finalized 空文件（v8.5 前格式）→ reason 空串（= 死因不可考）", () => {
+      writeLegacyFinalizedSidecar(sessionFile);
+      expect(readStateMarker(sessionFile)).toEqual({ status: "finalized", reason: "" });
+    });
+
+    it("旧 .cancelled 完整 tombstone → {status:cancelled, endedAt}", () => {
+      writeLegacyCancelledSidecar(sessionFile, {
+        id: "bg-1", status: "cancelled", agent: "w", startedAt: 100, endedAt: 200,
+      });
+      expect(readStateMarker(sessionFile)).toEqual({ status: "cancelled", endedAt: 200 });
+    });
+
+    it("旧 .cancelled JSON 损坏 → undefined（不认 cancelled，对齐合并前降级）", () => {
+      fs.writeFileSync(`${sessionFile}.cancelled`, "{broken", "utf-8");
+      expect(readStateMarker(sessionFile)).toBeUndefined();
+    });
+
+    it("旧 .cancelled status 非 cancelled → undefined（结构不合法降级）", () => {
+      fs.writeFileSync(`${sessionFile}.cancelled`, JSON.stringify({ status: "other", endedAt: 1 }), "utf-8");
+      expect(readStateMarker(sessionFile)).toBeUndefined();
+    });
+
+    it("旧名共存（.cancelled + .finalized）→ cancelled 胜出（优先级对齐合并前分支序）", () => {
+      writeLegacyFinalizedSidecar(sessionFile, "gc");
+      writeLegacyCancelledSidecar(sessionFile, {
+        id: "bg-1", status: "cancelled", agent: "w", startedAt: 100, endedAt: 200,
+      });
+      expect(readStateMarker(sessionFile)).toEqual({ status: "cancelled", endedAt: 200 });
+    });
+
+    it(".state 优先于存量旧名（新写侧权威）", () => {
+      writeLegacyCancelledSidecar(sessionFile, {
+        id: "bg-1", status: "cancelled", agent: "w", startedAt: 100, endedAt: 200,
+      });
+      writeFinalizedState(sessionFile, "user-close");
+      expect(readStateMarker(sessionFile)).toEqual({ status: "finalized", reason: "user-close" });
+    });
+  });
+
+  // ============================================================
+  // statStateStamp（缓存校验）
+  // ============================================================
+  describe("statStateStamp", () => {
+    it("三者皆无 → null（未终态化，缓存校验 null 语义）", () => {
+      expect(statStateStamp(sessionFile)).toBeNull();
+    });
+
+    it(".state 存在 → 非 null；重写改变戳（mtime/size 至少一项变化）", () => {
+      writeFinalizedState(sessionFile, "gc");
+      const first = statStateStamp(sessionFile);
+      expect(first).not.toBeNull();
+
+      writeFinalizedState(sessionFile, "a-much-longer-reason-string");
+      const second = statStateStamp(sessionFile);
+      expect(second).not.toBeNull();
+      expect(second).not.toEqual(first); // size 变化即戳变化
+    });
+
+    it("仅旧名存在 → 非 null（合并戳覆盖兼容读面）", () => {
+      writeLegacyFinalizedSidecar(sessionFile, "gc");
+      expect(statStateStamp(sessionFile)).not.toBeNull();
+    });
+
+    it("旧名删除后戳变化（GC 清理旧侧车 → 缓存正确失效）", () => {
+      writeLegacyFinalizedSidecar(sessionFile, "gc");
+      const withLegacy = statStateStamp(sessionFile);
+      fs.rmSync(`${sessionFile}.finalized`, { force: true });
+      expect(statStateStamp(sessionFile)).not.toEqual(withLegacy);
+    });
+  });
+});