@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/__tests__/execution-runtime-face.test.ts

@@ -0,0 +1,272 @@
+// src/execution/__tests__/execution-runtime-face.test.ts
+//
+// U10① execution 运行时面导出形态测试 = 第三宿主最小构造示例（验收证据）。
+//
+// 示例语义（设计 docs/design/subagent-core-sink-design.md §3.3 D6 / §4 S5）：第三宿主
+// 仅凭模块导出面（不看 core 内部实现）完成——
+//   1. createSubagentService({cwd, modelService, ...}) 参数注入构造（无全局查找）；
+//   2. record 状态查询面调用（SubagentService.lookupRecordAnyState 按 id 全态查询 +
+//      RecordStore 按状态枚举 listRunning/collectRecords 与按 id findLightById/getFullRecord）；
+//   3. 错误类型族 instanceof 分流。
+//
+// 构造先例同 subagent-service.test.ts：真实 ModelConfigService 指向 tmpdir 空目录
+// （loadGlobalConfig 对不存在文件返回默认配置，AgentRegistry 空目录安全），不 mock
+// service 内核；pi 仅在 initSession 场景以最小 duck-typed mock 注入。
+
+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";
+
+// MF-4：barrel 可达性用例的命名空间导入——「仅凭 src/index.ts 导入」的字面载体
+//（不经深路径），证明第三宿主按文档用法可构造。
+import * as subagentCore from "../../index.ts";
+import { EngineError } from "../engine/common/errors.ts";
+import { EngineNotFoundError } from "../engine/registry.ts";
+import { ZcodePrepareError } from "../engine/engines/zcode/preparer.ts";
+import { ZcodeReaderError } from "../engine/engines/zcode/reader.ts";
+import { ZcodeTaskShapeError } from "../engine/engines/zcode/zcode-engine.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import {
+  SUBAGENT_RECORD_CUSTOM_TYPE,
+  toSubagentRecordEntry,
+} from "../record-entry.ts";
+import { RecordStore } from "../record-store.ts";
+import { createSubagentService, getSubagentService } from "../subagent-service.ts";
+import {
+  DirtyWorktreeError,
+  ForkDepthExceededError,
+  ResurrectDeniedError,
+} from "../types.ts";
+import { GitRunError as WorktreeManagerGitRunError } from "../worktree-manager.ts";
+import { GitRunError as WorktreeGitOpsGitRunError } from "../worktree-git-ops.ts";
+
+// ── 工具：tmpdir agentDir + 真实 ModelConfigService（第三宿主自备的最小依赖集）──
+
+function makeAgentDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "exec-runtime-face-"));
+}
+
+function makeModelService(agentDir: string): ModelConfigService {
+  // cwd 为 ModelConfigServiceInit 必填键（与 agentDir 同指 tmp 目录；构造期仅消费 agentDir）
+  return new ModelConfigService({ agentDir, cwd: agentDir });
+}
+
+/** 最小 PiLike duck-type（initSession 场景用；本文件不触发真实 pi 调用）。 */
+function makePi() {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  };
+}
+
+describe("execution 运行时面（U10① D6）", () => {
+  let agentDir: string;
+
+  beforeEach(() => {
+    agentDir = makeAgentDir();
+  });
+
+  afterEach(() => {
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  // ============================================================
+  // ① createSubagentService 工厂：参数注入构造（第三宿主最小构造示例主体）
+  // ============================================================
+  describe("createSubagentService 工厂（参数注入构造）", () => {
+    it("仅凭参数注入构造成功，不读写全局单例槽位（无全局查找）", () => {
+      // 前置：全局槽位为空（工厂与 getSubagentService/setSubagentService 单例流程解耦）
+      expect(getSubagentService()).toBeNull();
+
+      const service = createSubagentService({
+        cwd: agentDir,
+        modelService: makeModelService(agentDir),
+      });
+
+      // 构造产物可用（实例方法存在）且未被登记进全局单例槽位——
+      // session_start 单例流程行为零改动，宿主自持实例。
+      expect(typeof service["lookupRecordAnyState"]).toBe("function");
+      expect(getSubagentService()).toBeNull();
+    });
+
+    it("构造后即可调用按 id 全态查询面：空 store 返回 undefined（未 initSession 按「不存在」处理）", () => {
+      const service = createSubagentService({
+        cwd: agentDir,
+        modelService: makeModelService(agentDir),
+      });
+
+      // lookupRecordAnyState 契约：未初始化/disposed 时 assertReady 抛错 → 按「不存在」处理返回 undefined
+      expect(service["lookupRecordAnyState"]("no-such-record")).toBeUndefined();
+    });
+
+    it("initSession（宿主注入最小 pi mock）后查询面同型可用", () => {
+      const service = createSubagentService({
+        cwd: agentDir,
+        modelService: makeModelService(agentDir),
+      });
+      service.initSession({ pi: makePi(), sessionId: "s1" });
+
+      expect(service["lookupRecordAnyState"]("no-such-record")).toBeUndefined();
+      service.dispose();
+    });
+  });
+
+  // ============================================================
+  // ② record 状态查询面：按状态枚举 / 按 id（RecordStore 公共构造）
+  // ============================================================
+  describe("record 状态查询面（RecordStore）", () => {
+    it("按状态枚举查询：空 store 下 listRunning 与 collectRecords 返回空数组", () => {
+      const sessionsDir = path.join(agentDir, "sessions");
+      fs.mkdirSync(sessionsDir, { recursive: true });
+      const store = new RecordStore(sessionsDir);
+
+      expect(store.listRunning()).toEqual([]);
+      expect(store.collectRecords(10, "all", undefined)).toEqual([]);
+      expect(store.collectRecords(10, "running", undefined)).toEqual([]);
+    });
+
+    it("按 id 查询：findLightById / getFullRecord / getMutable 对缺失 id 均返回 undefined", () => {
+      const sessionsDir = path.join(agentDir, "sessions");
+      fs.mkdirSync(sessionsDir, { recursive: true });
+      const store = new RecordStore(sessionsDir);
+
+      expect(store.findLightById("missing-id")).toBeUndefined();
+      expect(store.getFullRecord("missing-id")).toBeUndefined();
+      expect(store.getMutable("missing-id")).toBeUndefined();
+    });
+  });
+
+  // ============================================================
+  // ③ 错误类型族：instanceof 分流（导出形态 = 宿主可程序化判别）
+  // ============================================================
+  describe("错误类型族 instanceof", () => {
+    it("EngineError：code 前缀 message + 结构化投影", () => {
+      const err = new EngineError("model_not_available", "no provider", "pick another model");
+      expect(err).toBeInstanceOf(Error);
+      expect(err).toBeInstanceOf(EngineError);
+      expect(err.message).toBe("model_not_available: no provider");
+      expect(err.toStructured()).toEqual({
+        code: "model_not_available",
+        message: "model_not_available: no provider",
+        recovery: "pick another model",
+      });
+    });
+
+    it("EngineNotFoundError：携带 engineId / registered / source 供分流", () => {
+      const err = new EngineNotFoundError("nope", ["pi", "zcode"], "agent.md");
+      expect(err).toBeInstanceOf(Error);
+      expect(err).toBeInstanceOf(EngineNotFoundError);
+      expect(err.code).toBe("engine_not_found");
+      expect(err.engineId).toBe("nope");
+      expect(err.registered).toEqual(["pi", "zcode"]);
+      expect(err.source).toBe("agent.md");
+    });
+
+    it("zcode 引擎错误族：ZcodePrepareError / ZcodeReaderError / ZcodeTaskShapeError", () => {
+      const prepare = new ZcodePrepareError("model_not_available", "model gone");
+      expect(prepare).toBeInstanceOf(Error);
+      expect(prepare).toBeInstanceOf(ZcodePrepareError);
+      expect(prepare.code).toBe("model_not_available");
+
+      const reader = new ZcodeReaderError("db missing", "check journal");
+      expect(reader).toBeInstanceOf(Error);
+      expect(reader).toBeInstanceOf(ZcodeReaderError);
+
+      // [U10①] 原 class 未导出（仅内部 throw），本断言钉住 export 补齐后宿主可 instanceof
+      const shape = new ZcodeTaskShapeError("capability_unsupported", "no schema");
+      expect(shape).toBeInstanceOf(Error);
+      expect(shape).toBeInstanceOf(ZcodeTaskShapeError);
+      expect(shape.code).toBe("capability_unsupported");
+      expect(shape.name).toBe("ZcodeTaskShapeError");
+    });
+
+    it("执行守卫错误族：ResurrectDeniedError / ForkDepthExceededError / DirtyWorktreeError", () => {
+      const resurrect = new ResurrectDeniedError();
+      expect(resurrect).toBeInstanceOf(Error);
+      expect(resurrect).toBeInstanceOf(ResurrectDeniedError);
+
+      const forkDepth = new ForkDepthExceededError("depth > max");
+      expect(forkDepth).toBeInstanceOf(Error);
+      expect(forkDepth).toBeInstanceOf(ForkDepthExceededError);
+
+      const dirty = new DirtyWorktreeError("uncommitted changes");
+      expect(dirty).toBeInstanceOf(Error);
+      expect(dirty).toBeInstanceOf(DirtyWorktreeError);
+    });
+
+    it("GitRunError 两处同名列（worktree-manager / worktree-git-ops）各自可 instanceof", () => {
+      const fromManager = new WorktreeManagerGitRunError("git fail", { exitCode: 1 });
+      expect(fromManager).toBeInstanceOf(Error);
+      expect(fromManager).toBeInstanceOf(WorktreeManagerGitRunError);
+      expect(fromManager).not.toBeInstanceOf(WorktreeGitOpsGitRunError);
+
+      const fromGitOps = new WorktreeGitOpsGitRunError("git fail", { exitCode: 128 });
+      expect(fromGitOps).toBeInstanceOf(Error);
+      expect(fromGitOps).toBeInstanceOf(WorktreeGitOpsGitRunError);
+      expect(fromGitOps).not.toBeInstanceOf(WorktreeManagerGitRunError);
+    });
+  });
+
+  // ============================================================
+  // ④ record-entry 自描述 entry 面（导出形态确认；投影逐字段等值由
+  //    execution-record.test.ts 钉住，此处不重复）
+  // ============================================================
+  describe("record-entry 面", () => {
+    it("SUBAGENT_RECORD_CUSTOM_TYPE 值契约：'subagent-record'", () => {
+      expect(SUBAGENT_RECORD_CUSTOM_TYPE).toBe("subagent-record");
+    });
+
+    it("toSubagentRecordEntry 可达且对最小 SubagentRecord 投影出 v===1", () => {
+      const entry = toSubagentRecordEntry({
+        id: "r1",
+        agent: "a.md",
+        task: "t",
+        slug: "s",
+        status: "running",
+        mode: "background",
+        startedAt: 1,
+        rootSessionId: undefined,
+        parentRecordId: undefined,
+        depth: 0,
+        endedAt: undefined,
+        turns: 0,
+        totalTokens: 0,
+        model: "m",
+        thinkingLevel: undefined,
+        eventLog: [],
+        displayItems: [],
+      });
+      expect(entry.v).toBe(1);
+      expect(entry.id).toBe("r1");
+    });
+  });
+
+  // ============================================================
+  // ⑤ barrel 可达性（MF-4）：仅凭 src/index.ts 导入完成第三宿主构造
+  //    （SubagentServiceInit.modelService: ModelConfigService——构造依赖
+  //    与 jsdoc 示例引用的访问器必须全部从 barrel 可达）
+  // ============================================================
+  describe("barrel 可达性（仅凭 src/index.ts 导入，MF-4）", () => {
+    it("ModelConfigService / getModelConfigService / createSubagentService 从 barrel 可达并可构造", () => {
+      // 符号面：类与访问器均为函数（导出存在性）
+      expect(typeof subagentCore.ModelConfigService).toBe("function");
+      expect(typeof subagentCore.getModelConfigService).toBe("function");
+
+      // 进程单例槽位未被本文件写入（同 ① 的全局查找断言口径）
+      expect(subagentCore.getModelConfigService()).toBeNull();
+
+      // 运行时可达：仅凭 barrel 符号完成参数注入构造（ModelConfigServiceInit
+      // = { cwd, agentDir }，指向 tmp 目录——loadGlobalConfig 对不存在文件
+      // 返回默认配置，AgentRegistry 空目录安全，同文件头既有 stub 口径）
+      const modelService = new subagentCore.ModelConfigService({ cwd: agentDir, agentDir });
+      const service = subagentCore.createSubagentService({ cwd: agentDir, modelService });
+
+      // 构造产物可用（实例方法存在），且不写进程单例槽位（第三宿主自持实例）
+      expect(typeof service["lookupRecordAnyState"]).toBe("function");
+      expect(subagentCore.getModelConfigService()).toBeNull();
+    });
+  });
+});

package/src/execution/__tests__/explicit-agent-ref-guard.test.ts

@@ -33,14 +33,14 @@ vi.mock("node:child_process", async () => {
 });
 
 // buildSpawnArgs 包装为 spy（保留真实实现）——「显式 ref 拒单不触达 spawn 参数组装」的承重断言。
-vi.mock("../session-runner.ts", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../session-runner.ts")>();
+vi.mock("../engine/engines/pi/session-runner.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../engine/engines/pi/session-runner.ts")>();
   return { ...actual, buildSpawnArgs: vi.fn(actual.buildSpawnArgs) };
 });
 
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
-import { buildSpawnArgs } from "../session-runner.ts";
+import { buildSpawnArgs } from "../engine/engines/pi/session-runner.ts";
 import type { PiLike } from "../subagent-service.ts";
 import { SubagentService } from "../subagent-service.ts";
 

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

@@ -26,7 +26,8 @@ vi.mock("../../core/logger.ts", () => ({
 
 import { doFinalizeRecord, doFinalizeRoundToIdle } from "../finalize-record.ts";
 import { ManifestStore } from "../manifest-store.ts";
-import type { AgentResult, ExecutionRecord } from "../types.ts";
+import { getSubagentSessionDir } from "../path-encoding.ts";
+import type { AgentResult, ExecutionRecord, WorktreeHandle } from "../types.ts";
 
 function makeMinimalRecord(overrides: Partial<ExecutionRecord> = {}): ExecutionRecord {
   return {
@@ -36,7 +37,6 @@ function makeMinimalRecord(overrides: Partial<ExecutionRecord> = {}): ExecutionR
     thinkingLevel: undefined,
     mode: "background",
     task: "test",
-    slug: "test",
     startedAt: 1000,
     rootSessionId: "session-main",
     parentRecordId: undefined,
@@ -77,19 +77,19 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
   });
 
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   /** 构造最小 FinalizeDeps：record 无 sessionFile/worktreeHandle,跳过 Step 0/3 文件操作。 */
-  function makeDeps() {
+  function makeDeps(): Parameters<typeof doFinalizeRecord>[0] {
     return {
       manifestStore,
-      worktreeManager: {} as never,
-      store: { archive: vi.fn(), reportRecordTransition: vi.fn() } as never,
-      modelService: {} as never,
+      worktreeManager: {},
+      store: { archive: vi.fn(), reportRecordTransition: vi.fn() },
+      modelService: {},
       pi: { appendEntry: vi.fn() },
       emitUnregister: vi.fn(),
-    };
+    } as unknown as Parameters<typeof doFinalizeRecord>[0];
   }
 
   it("status=closed + cancelled reason → manifest 写 closed（v4 B-1：cancelled 折入 closed）", async () => {
@@ -165,7 +165,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     expect(errMsg).toContain("disk full");
 
     // ── 核心 claim 6：pi.appendEntry 记录 "subagent:manifest-write-failed" 事件 ──
-    expect(deps.pi.appendEntry).toHaveBeenCalledWith(
+    expect(deps.pi!.appendEntry).toHaveBeenCalledWith(
       "subagent:manifest-write-failed",
       expect.objectContaining({ id: "rec-cleanup-first", error: "disk full" }),
     );
@@ -181,6 +181,252 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     // 清理 mock 调用记录防污染
     loggerMock.error.mockClear();
   });
+
+  // ── [T1/PS-9] sessionFile 缺失 → sessionDir 反查后 marker/alive 清理仍落地 ──
+  //
+  // PS-9：finalize 的 tombstone/finalized sidecar 与 removeAliveMarker 全部 gated on
+  // record.sessionFile——RC-1（握手失败）+ LC-4（收尾反查未命中）的残余形态下，
+  // 「sessionFile 缺失 → 终态原因丢失 + alive marker 残留」。修复：sessionFile 缺失时
+  // 用 deps.sessionDir 按 identity（record.id）反查真实 session 文件作依据。
+  // 真实 fs + tmp 目录（与文件既有策略一致）：session JSONL 写入 identity custom entry
+  //（子进程 session_start hook 的写入形态），readIdentityHeader/readIdentityTail 真实解析。
+  describe("[T1/PS-9] sessionFile 缺失 sessionDir 反查", () => {
+    let sessionDir: string;
+
+    beforeEach(() => {
+      sessionDir = fs.mkdtempSync(path.join(os.tmpdir(), "finalize-ps9-sessions-"));
+    });
+
+    afterEach(() => {
+      fs.rmSync(sessionDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+    });
+
+    /** 在 sessionDir 写入带 identity 的 session 文件（1 行 identity entry，位于头部）。 */
+    function writeSessionFileWithIdentity(fileName: string, recordId: string): string {
+      const sessionFile = path.join(sessionDir, fileName);
+      const identityEntry = JSON.stringify({
+        type: "custom",
+        customType: "subagent-identity",
+        data: { id: recordId, agent: "worker", mode: "background", task: "t", startedAt: 1000 },
+      });
+      fs.writeFileSync(sessionFile, `${identityEntry}\n`, "utf-8");
+      return sessionFile;
+    }
+
+    it("sessionFile 缺失 + 反查命中 → .finalized 落盘 + .alive 清理 + record/manifest 回填", async () => {
+      const sessionFile = writeSessionFileWithIdentity("20260901T12000000_ps9.jsonl", "rec-ps9");
+      // 预写 .alive 残留（模拟 running 期崩溃恢复窗口的 marker）
+      fs.writeFileSync(
+        `${sessionFile}.alive`,
+        `${JSON.stringify({ pid: 99999, id: "rec-ps9", startedAt: 1000 })}\n`,
+        "utf-8",
+      );
+      const record = makeMinimalRecord({ id: "rec-ps9", sessionFile: undefined });
+      const deps = { ...makeDeps(), sessionDir };
+
+      await doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "gc");
+
+      // 反查回填 record.sessionFile
+      expect(record.sessionFile).toBe(sessionFile);
+      // 终态原因持久化不再丢失（closedReason gc 写入 .finalized 内容）
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+      expect(fs.readFileSync(`${sessionFile}.finalized`, "utf-8")).toBe("gc");
+      // alive marker 不再残留
+      expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
+      // manifest 拿到真实 sessionFile（诊断/重建源不再失真）
+      const manifest = await manifestStore.readManifest("rec-ps9");
+      expect(manifest?.sessionFile).toBe(sessionFile);
+    });
+
+    it("cancelled + 反查命中 → tombstone 写到反查路径（cancelled 语义不因 sessionFile 缺失丢失）", async () => {
+      const sessionFile = writeSessionFileWithIdentity("20260901T12000001_ps9c.jsonl", "rec-ps9c");
+      const record = makeMinimalRecord({ id: "rec-ps9c", sessionFile: undefined });
+      const deps = { ...makeDeps(), sessionDir };
+
+      await doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "cancelled");
+
+      expect(record.sessionFile).toBe(sessionFile);
+      expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(true);
+      const tomb = JSON.parse(
+        fs.readFileSync(`${sessionFile}.cancelled`, "utf-8"),
+      ) as { id: string; status: string };
+      expect(tomb.id).toBe("rec-ps9c");
+      expect(tomb.status).toBe("cancelled");
+    });
+
+    it("反查未命中（目录无 identity 匹配文件）→ 不抛、sessionFile 保持缺失、无 marker（行为退回修复前）", async () => {
+      // sessionDir 存在但内容与 record 不匹配
+      writeSessionFileWithIdentity("20260901T12000000_other.jsonl", "rec-someone-else");
+      const record = makeMinimalRecord({ id: "rec-ps9-miss", sessionFile: undefined });
+      const deps = { ...makeDeps(), sessionDir };
+
+      await expect(
+        doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "gc"),
+      ).resolves.toBeUndefined();
+
+      expect(record.sessionFile).toBeUndefined();
+      // manifest sessionFile 同步保持 undefined
+      const manifest = await manifestStore.readManifest("rec-ps9-miss");
+      expect(manifest?.sessionFile).toBeUndefined();
+      loggerMock.error.mockClear();
+    });
+  });
+
+  // ── Step 3a 判别 wiring：closedReason → tombstone vs finalized（MF-1 fix / v4 B-1）──
+  //
+  // record 带 sessionFile 直接命中 writeFinalizedOrTombstone 的核心判别分支：
+  //   cancelled → writeCancelledTombstone（防重建丢失 cancelled 语义）
+  //   其余 reason → writeFinalized（真实 reason 进 sidecar 内容，磁盘重建还原 closedReason）
+  // 两路 sidecar 互斥（BC-4）：断言「写了哪个 + 没写哪个」双向锁定。
+  describe("writeFinalizedOrTombstone 判别 wiring（closedReason → tombstone vs finalized）", () => {
+    it("closedReason=cancelled → tombstone sidecar 携带 id/status/agent/startedAt/endedAt 且不写 .finalized", async () => {
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      const record = makeMinimalRecord({
+        id: "rec-wire-cancelled",
+        sessionFile,
+        // 预设 endedAt 会被 Step 1 completeRecord 冻结值覆盖（见下方 endedAt 断言注释）
+        endedAt: 5678,
+      });
+
+      await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", "cancelled");
+
+      // tombstone 写出且内容为完整 CancelledTombstone（经 readCancelledTombstone 形态校验的
+      // 字段逐项断言，不用 objectContaining 放宽——重建链路靠这些字段还原）
+      expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(true);
+      const tomb = JSON.parse(fs.readFileSync(`${sessionFile}.cancelled`, "utf-8")) as {
+        id: string;
+        status: string;
+        agent: string;
+        startedAt: number;
+        endedAt: number;
+      };
+      expect(tomb.id).toBe("rec-wire-cancelled");
+      expect(tomb.status).toBe("cancelled");
+      expect(tomb.agent).toBe("worker");
+      expect(tomb.startedAt).toBe(1000);
+      // endedAt 来自 completeRecord 冻结后的 record.endedAt（Step 1 先于 Step 3a，
+      // record 预设的 endedAt 会被冻结值覆盖）——tombstone 携带真实收尾时间戳
+      expect(tomb.endedAt).toBe(record.endedAt);
+      expect(typeof tomb.endedAt).toBe("number");
+      // 互斥：cancelled 路径绝不写 finalized（否则重建判「正常结束」，cancelled 语义丢失）
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(false);
+    });
+
+    it.each(["user-close", "gc"] as const)(
+      "closedReason=%s → .finalized 内容携带真实 reason 且不写 tombstone",
+      async (reason) => {
+        const sessionFile = path.join(tmpDir, "session.jsonl");
+        const record = makeMinimalRecord({ id: `rec-wire-${reason}`, sessionFile });
+
+        await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", reason);
+
+        // finalized sidecar 写出且内容 = 真实 reason（磁盘重建用它还原 closedReason，
+        // 不再一律硬编码 gc）
+        expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+        expect(fs.readFileSync(`${sessionFile}.finalized`, "utf-8")).toBe(reason);
+        // 互斥：非 cancelled 路径不写 tombstone
+        expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(false);
+      },
+    );
+  });
+
+  // ── Step 0 collectPatch wiring：worktreeHandle 置位 → patch 收集 + patchFile 回填 ──
+  //
+  // [MF#3] patchFile 必须写到 worktree 之外（sessionsDir/<branch>.patch），避免被
+  // cleanup 删除；仅 patch.written=true（diff 非空且写盘成功）才回填 record.patchFile，
+  // 避免悬空路径让 `git apply` 打不存在的文件。
+  describe("collectPatchIfWorktree wiring（worktreeHandle 置位 + patch.written 回填）", () => {
+    // agentDir 是真实写目标：finalize-record Step 0 对 sessionsDir 做 mkdirSync(recursive)，
+    // 会在 agentDir 下创建整棵 subagents/<enc>/sessions 树。必须 mkdtemp 自建 + afterEach
+    // 清理（测试红线），禁止硬编码真实 /tmp 路径。mainCwd / handle.path 仅作编码键与
+    // startsWith 断言，源码不落盘，保持字面量即可。
+    let agentDir: string;
+
+    beforeEach(() => {
+      agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "collect-patch-agent-"));
+    });
+
+    afterEach(() => {
+      fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+    });
+
+    const mainCwd = "/tmp/collect-patch-main-repo";
+    const branch = "subagent-b1";
+    const handle: WorktreeHandle = {
+      path: "/tmp/collect-patch-checkout",
+      branch,
+      baseCommit: "abc123",
+      mainCwd,
+    };
+
+    function makeWorktreeDeps(
+      collectPatch: ReturnType<typeof vi.fn>,
+    ): ReturnType<typeof makeDeps> & { agentDir: string } {
+      // 覆写 worktreeManager / modelService 为 stub（与外层 makeDeps 同款 unknown 断言——
+      // FinalizeDeps 的 ModelConfigService/WorktreeManager 是宽接口，stub 只需覆盖本次路径）
+      return {
+        ...makeDeps(),
+        modelService: { getAgentDir: () => agentDir },
+        worktreeManager: { collectPatch, cleanup: vi.fn() },
+        agentDir,
+      } as unknown as ReturnType<typeof makeDeps> & { agentDir: string };
+    }
+
+    it("patch.written=true → collectPatch 收到 handle + sessionsDir/<branch>.patch，record.patchFile 回填", async () => {
+      const { agentDir, ...deps } = makeWorktreeDeps(vi.fn().mockResolvedValue({
+        patchFile: "/ignored/collector-picked-path.patch",
+        failed: false,
+        written: true,
+      }));
+      const sessionsDir = getSubagentSessionDir(agentDir, mainCwd);
+      const expectedPatchFile = path.join(sessionsDir, `${branch}.patch`);
+      const record = makeMinimalRecord({ id: "rec-patch", worktreeHandle: handle });
+
+      await doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "gc");
+
+      // collectPatch 被调用，patchFile 由 finalize-record 拼装（sessionsDir/<branch>.patch）
+      expect(deps.worktreeManager.collectPatch).toHaveBeenCalledTimes(1);
+      expect(deps.worktreeManager.collectPatch).toHaveBeenCalledWith(handle, expectedPatchFile);
+      // sessionsDir 已 mkdir（recursive）——patchFile 的父目录真实存在
+      expect(fs.existsSync(sessionsDir)).toBe(true);
+      // [MF#3] patchFile 落在 worktree 之外（不会被 Step 3 cleanup 连带删除）
+      expect(expectedPatchFile.startsWith(handle.path)).toBe(false);
+      // patch.written=true → record.patchFile 回填为 finalize-record 拼装的路径
+      expect(record.patchFile).toBe(expectedPatchFile);
+    });
+
+    it("patch.written=false（空 diff / 写失败）→ record.patchFile 不回填（避免悬空路径）", async () => {
+      const { agentDir, ...deps } = makeWorktreeDeps(vi.fn().mockResolvedValue({
+        patchFile: "/ignored/never-written.patch",
+        failed: false,
+        written: false,
+      }));
+      const record = makeMinimalRecord({ id: "rec-patch-empty", worktreeHandle: handle });
+
+      await doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "gc");
+
+      expect(deps.worktreeManager.collectPatch).toHaveBeenCalledTimes(1);
+      expect(record.patchFile).toBeUndefined();
+    });
+
+    it("collectPatch 抛错 → best-effort 不阻断 finalize 链（manifest 照写、cleanup 照执行）", async () => {
+      const { agentDir, ...deps } = makeWorktreeDeps(vi.fn().mockRejectedValue(new Error("git died")));
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      const record = makeMinimalRecord({ id: "rec-patch-err", sessionFile, worktreeHandle: handle });
+
+      await expect(
+        doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "gc"),
+      ).resolves.toBeUndefined();
+
+      // Step 0 失败不影响后续步骤：finalized sidecar 与 manifest 照常落地
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+      const manifest = await manifestStore.readManifest("rec-patch-err");
+      expect(manifest?.status).toBe("closed");
+      expect(deps.worktreeManager.cleanup).toHaveBeenCalledTimes(1);
+      expect(record.patchFile).toBeUndefined();
+      loggerMock.error.mockClear();
+    });
+  });
 });
 
 // ============================================================
@@ -197,19 +443,19 @@ describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () =>
   });
 
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   /** 构造 FinalizeDeps：worktreeManager.cleanup / store.archive 为 vi.fn 以断言「不调」。 */
-  function makeDeps() {
+  function makeDeps(): Parameters<typeof doFinalizeRoundToIdle>[0] {
     return {
       manifestStore,
-      worktreeManager: { cleanup: vi.fn(), collectPatch: vi.fn() } as never,
-      store: { archive: vi.fn(), reportRecordTransition: vi.fn() } as never,
-      modelService: {} as never,
-      pi: { appendEntry: vi.fn() } as never,
+      worktreeManager: { cleanup: vi.fn(), collectPatch: vi.fn() },
+      store: { archive: vi.fn(), reportRecordTransition: vi.fn() },
+      modelService: {},
+      pi: { appendEntry: vi.fn() },
       emitUnregister: vi.fn(),
-    };
+    } as unknown as Parameters<typeof doFinalizeRoundToIdle>[0];
   }
 
   it("record 带 sessionFile → 删 .alive + record.status=running + round 0→1", async () => {
@@ -317,6 +563,22 @@ describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () =>
     expect(record.result).toBe("round did not complete: spawn timeout");
   });
 
+  it("T2-③/LC-1: 失败轮 text 与 error 并存时 error 优先——collectResult 恒带 getFullText 正文，text 优先会覆盖恢复指引（S-B-1 首轮 settled watchdog 实测）", async () => {
+    const record = makeMinimalRecord({ id: "rec-result-err-text", chatMode: true });
+    record.status = "closed";
+    const result = makeMinimalResult();
+    // runSpawn settledWatchdogFired 分支的 collectResult 形态：正文（T1 回补采集）与
+    // watchdog 错误并存
+    result.text = "DONE";
+    result.success = false;
+    result.error =
+      "subagent did not reach agent_settled within 10 min (settled watchdog); the process was terminated to bound the wait. Recovery: check state with subagents action:'list', then re-send your message to continue.";
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // 失败的 record.result（= 通知正文）必须携带失败原因与恢复指引，不得回显轮内旧正文
+    expect(record.result).toBe(`round did not complete: ${result.error}`);
+    expect(record.result).not.toBe("DONE");
+  });
+
   it("C1TC10: chatMode 空增量轮占位——record.result 固定 (no output this round)，不含上一轮文本（D5）", async () => {
     const record = makeMinimalRecord({ id: "rec-increment-empty", chatMode: true });
     record.status = "closed";