@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/__tests__/chat-engine-routing.test.ts

@@ -65,10 +65,10 @@ import { spawn } from "node:child_process";
 import type { EnginePort, RunContext } from "../engine/port.ts";
 import { resolveJournalPath } from "../engine/paths.ts";
 import { clearEngines, registerEngine } from "../engine/registry.ts";
+import type { AgentCallOpts } from "../../orchestration/models/types.ts";
 import type {
   AgentEvent,
   AgentOutcome,
-  AgentTaskSpec,
   EngineCapabilities,
   EngineHandle,
   ProbeReport,
@@ -76,7 +76,7 @@ import type {
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
 import { toSubagentRecordEntry } from "../record-entry.ts";
-import { getChildByRecord } from "../session-runner.ts";
+import { getChildByRecord } from "../engine/engines/pi/session-runner.ts";
 import { SubagentService } from "../subagent-service.ts";
 import type { ExecuteOptions } from "../types.ts";
 
@@ -86,7 +86,7 @@ const mockSpawn = vi.mocked(spawn);
 // 假引擎（EnginePort 最小实现；run 行为由每个用例注入）
 // ============================================================
 
-/** zcode 形态 capabilities（conversation/steer unsupported、sandbox none）。 */
+/** zcode 形态 capabilities（conversation/steer unsupported、sandbox none、maxTurns false）。 */
 const ZCODE_LIKE_CAPS: EngineCapabilities = {
   schemaEnforcement: "emulated",
   steer: "unsupported",
@@ -98,10 +98,11 @@ const ZCODE_LIKE_CAPS: EngineCapabilities = {
   resume: "cold",
   interrupt: "kill-only",
   permissionMode: "native",
+  maxTurns: false,
 };
 
 interface CapturedRun {
-  task: AgentTaskSpec;
+  task: AgentCallOpts;
   ctx: RunContext;
 }
 
@@ -111,7 +112,7 @@ class FakeEngine implements EnginePort {
   /** U2：probe 结果注入（路由期 routeEngine 消费；缺省 ok——probe 通过的常态）。 */
   probeFailed = false;
   /** run 实现注入（缺省：挂起不 resolve——record 保持 running 便于内存断言）。 */
-  runImpl: (task: AgentTaskSpec, ctx: RunContext) => Promise<{ handle: EngineHandle; outcome: AgentOutcome }>;
+  runImpl: (task: AgentCallOpts, ctx: RunContext) => Promise<{ handle: EngineHandle; outcome: AgentOutcome }>;
 
   constructor(id: string) {
     this.id = id;
@@ -132,7 +133,7 @@ class FakeEngine implements EnginePort {
         }
       : { ok: true, engineVersion: "fake", checks: [{ name: "bin", ok: true }] };
   }
-  async run(task: AgentTaskSpec, ctx: RunContext): Promise<{ handle: EngineHandle; outcome: AgentOutcome }> {
+  async run(task: AgentCallOpts, ctx: RunContext): Promise<{ handle: EngineHandle; outcome: AgentOutcome }> {
     this.runs.push({ task, ctx });
     return this.runImpl(task, ctx);
   }
@@ -222,7 +223,7 @@ function baseOpts(agentDir: string, extra: Partial<ExecuteOptions> = {}): Execut
 
 /** 挂起 run 的引擎路径下取内存 running record 的 engine 盖章（collectRecords 内存源投影）。 */
 function runningEngineTag(service: SubagentService, id: string): string | undefined {
-  const rec = service.collectRecords(10, "running").find((r) => r.id === id);
+  const rec = service.queries.collectRecords(10, "running").find((r) => r.id === id);
   return rec?.engine;
 }
 
@@ -242,7 +243,7 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     // registry 是 globalThis 进程单例——必须清空，防假引擎泄漏进其他测试文件
     clearEngines();
     resetCoreForTests();
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     vi.clearAllMocks();
   });
 
@@ -308,7 +309,7 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     const handle = await service.execute(baseOpts(agentDir));
     await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
 
-    const rec = service.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
+    const rec = service.queries.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
     expect(rec).toBeDefined();
     expect(rec?.engine).toBeUndefined();
     expect(JSON.stringify(toSubagentRecordEntry(rec!))).not.toContain("engine");
@@ -320,10 +321,10 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
 
     expect(zcode.runs.length).toBe(0);
-    // piEngine 只是注册表占位——pi 缺省路径不查注册表（上一用例已验证零注册场景），
-    // 此处断言 piEngine 也未被消费（pi 原路径不走 EnginePort）
+    // piEngine 只是注册表占位——D2 单轨后 pi chat 走 Service 内部 DI 的 PiEngine 实例
+    //（chatPiEngine，经 EnginePort 交接轮次），registry 占位实例仍未被 chat 域消费
     expect(piEngine.runs.length).toBe(0);
-    const rec = service.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
+    const rec = service.queries.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
     expect(rec?.engine).toBeUndefined();
   });
 
@@ -342,7 +343,7 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     expect((err as { recovery?: string }).recovery).toContain("engine: pi");
     expect((err as { recovery?: string }).recovery).toContain("不传该参数");
     expect(zcode.runs.length).toBe(0);
-    expect(service.collectRecords(10, "all")).toHaveLength(0);
+    expect(service.queries.collectRecords(10, "all")).toHaveLength(0);
   });
 
   it("[预检] fork:true / worktree:true 同步拒绝", async () => {
@@ -354,7 +355,39 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
       /engine_capability_unsupported/,
     );
     expect(zcode.runs.length).toBe(0);
-    expect(service.collectRecords(10, "all")).toHaveLength(0);
+    expect(service.queries.collectRecords(10, "all")).toHaveLength(0);
+  });
+
+  it("[D3-④] zcode + maxTurns → 同步拒绝（record 创建前，不产生孤儿 record）——旧形态的 engine.run 内异步拒绝废弃", async () => {
+    // 旧形态：Service 层预检不查 maxTurns → record 创建 + kickOffEngineRun →
+    // zcode run 内硬编码 shape 检查 throw → failed record（异步化）。
+    // D3-④ 检查点钉死后：capabilities.maxTurns 位驱动，record 创建前同步 throw。
+    const { service, zcode } = setup(agentDir);
+    const err = await service
+      .execute(baseOpts(agentDir, { engine: "zcode", maxTurns: 5 }))
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain("engine_capability_unsupported");
+    expect((err as Error).message).toContain("maxTurns");
+    expect((err as { recovery?: string }).recovery).toContain("engine: pi");
+    // 「不产生孤儿 record」断言落点（V4④）：store 无新增条目、引擎未被触达
+    expect(zcode.runs.length).toBe(0);
+    expect(service.queries.collectRecords(10, "all")).toHaveLength(0);
+  });
+
+  it("[V4⑤ 反向] pi + maxTurns/fork/conversation/worktree → 零拦截（pi 既有合法能力无回归）", async () => {
+    const { service, zcode } = setup(agentDir);
+    // maxTurns=3（V4⑤ 场景原样）：正常进入 pi 轮次（spawn 被调），无同步拒绝
+    const handle = await service.execute(baseOpts(agentDir, { maxTurns: 3 }));
+    await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
+    expect(zcode.runs.length).toBe(0);
+    expect(service.queries.collectRecords(10, "running").find((r) => r.id === handle.subagentId)).toBeDefined();
+    // fork / conversation 组合同样直通（第二次 spawn 被调，无 engine_capability_unsupported）
+    await service.execute(baseOpts(agentDir, { fork: true, conversation: true }));
+    await vi.waitFor(() => expect(mockSpawn.mock.calls.length).toBeGreaterThanOrEqual(2));
+    // pi + worktree：预检放行（caps.sandbox='emulated'）——execute 不因能力被拒而
+    // reject（worktree 创建成败是另一维度，与拦截无关）
+    await expect(service.execute(baseOpts(agentDir, { worktree: true }))).resolves.toBeTypeOf("object");
   });
 
   // ============================================================
@@ -367,14 +400,14 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     expect(err).toBeInstanceOf(Error);
     expect((err as Error).message).toContain("engine_not_found");
     expect((err as Error).message).toContain("zcode");
-    expect(service.collectRecords(10, "all")).toHaveLength(0);
+    expect(service.queries.collectRecords(10, "all")).toHaveLength(0);
   });
 
   // ============================================================
   // 5. 引擎分支骨架（D10 终止链 + 终态迁移）
   // ============================================================
 
-  it("[骨架] taskSpec 字段正确（task/cwd/model/effort/schema/persona）", async () => {
+  it("[骨架] 合流任务形状字段正确（prompt/cwd/model/thinkingLevel/schema/skillPath/appendSystemPrompt——D6 直传）", async () => {
     const { service, zcode } = setup(agentDir);
     await service.execute(
       baseOpts(agentDir, {
@@ -388,12 +421,14 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     );
     await vi.waitFor(() => expect(zcode.runs.length).toBe(1));
     const { task, ctx } = zcode.runs[0];
-    expect(task.task).toBe("do work");
-    expect(task.slug).toBe("routing-test");
+    // [D6 合流] task = AgentCallOpts（host-task-spec 从 ExecuteOptions 直译）
+    expect(task.prompt).toBe("do work");
+    expect(task.description).toBe("routing-test");
     expect(task.model).toBe("zcode/glm");
-    expect(task.effort).toBe("high");
+    expect(task.thinkingLevel).toBe("high");
     expect(task.schema).toEqual({ type: "object" });
-    expect(task.persona).toEqual({ skillPath: "/tmp/skill.md", appendSystemPrompt: ["extra"] });
+    expect(task.skillPath).toBe("/tmp/skill.md");
+    expect(task.appendSystemPrompt).toEqual(["extra"]);
     expect(ctx.poolKey).toBe("shared");
   });
 
@@ -403,7 +438,7 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     const handle = await service.execute(baseOpts(agentDir, { engine: "zcode" }));
 
     // record 终态化即 archive（无 sessionFile 不可磁盘重建）→ 内存查询落空
-    await vi.waitFor(() => expect(service.findRecord(handle.subagentId)).toBeUndefined());
+    await vi.waitFor(() => expect(service.queries.findRecord(handle.subagentId)).toBeUndefined());
     // 完成通知（chat 域宿主职责）：notifier 立即 flush（无其他 running）→ result 进 sendMessage 正文
     await vi.waitFor(() => {
       const sent = pi.sendMessage.mock.calls.some((c) => String(c[0]?.content).includes("hello result"));
@@ -417,7 +452,7 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
       Promise.resolve({ handle: fakeHandle(), outcome: { ...doneOutcome(""), error: "engine_run_failed: boom", engineId: "zcode" } });
     const handle = await service.execute(baseOpts(agentDir, { engine: "zcode" }));
 
-    await vi.waitFor(() => expect(service.findRecord(handle.subagentId)).toBeUndefined());
+    await vi.waitFor(() => expect(service.queries.findRecord(handle.subagentId)).toBeUndefined());
     await vi.waitFor(() => {
       const sent = pi.sendMessage.mock.calls.some((c) => String(c[0]?.content).includes("boom"));
       expect(sent).toBe(true);
@@ -468,7 +503,7 @@ describe("chat 引擎分支 U2：probe 兜底 / journal / engineHandle", () => {
   afterEach(() => {
     clearEngines();
     delete process.env.XYZ_AGENT_DATA_DIR;
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     vi.clearAllMocks();
   });
 
@@ -482,7 +517,7 @@ describe("chat 引擎分支 U2：probe 兜底 / journal / engineHandle", () => {
     await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
     expect(piEngine.runs.length).toBe(0);
 
-    const rec = service.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
+    const rec = service.queries.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
     expect(rec?.engine).toBe("pi");
     expect(rec?.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
     // entry（register 写点）含 engineFallback——兜底路径允许新增键（D5 只约束纯缺省路径）
@@ -498,7 +533,7 @@ describe("chat 引擎分支 U2：probe 兜底 / journal / engineHandle", () => {
     );
     expect(mockSpawn).not.toHaveBeenCalled();
     expect(zcode.runs.length).toBe(0);
-    expect(service.collectRecords(10, "all")).toHaveLength(0);
+    expect(service.queries.collectRecords(10, "all")).toHaveLength(0);
   });
 
   it("[journal] taskId=record.id + onPoolResolved retarget 落 engines/zcode/<poolKey>/，journalPath 同源回填", async () => {
@@ -522,7 +557,7 @@ describe("chat 引擎分支 U2：probe 兜底 / journal / engineHandle", () => {
       });
     };
     const handle = await service.execute(baseOpts(agentDir, { engine: "zcode" }));
-    await vi.waitFor(() => expect(service.findRecord(handle.subagentId)).toBeUndefined());
+    await vi.waitFor(() => expect(service.queries.findRecord(handle.subagentId)).toBeUndefined());
 
     // journal 文件名 = journal-<record.id>.jsonl，落在 engines/zcode/<poolKey>/ 下
     const journalPath = resolveJournalPath(agentDir, "zcode", POOL, handle.subagentId);
@@ -553,20 +588,91 @@ describe("chat 引擎分支 U2：probe 兜底 / journal / engineHandle", () => {
       });
     };
     const handle = await service.execute(baseOpts(agentDir, { engine: "zcode" }));
-    await vi.waitFor(() => expect(service.findRecord(handle.subagentId)).toBeUndefined());
+    await vi.waitFor(() => expect(service.queries.findRecord(handle.subagentId)).toBeUndefined());
 
-    const h = lastRecordEntry(pi)?.engineHandle;
+    const h = lastRecordEntry(pi)?.engineHandle as Record<string, unknown> | undefined;
     expect(h?.sessionRef).toEqual({ dbPath: "sessions.db" });
     expect(h?.poolKey).toBe(POOL);
     expect(h?.journalPath).toBe(resolveJournalPath(agentDir, "zcode", POOL, handle.subagentId));
   });
 
+  // ============================================================
+  // [R4 §3.4 不变量 3] onHandleReady 运行中回填：create 应答后立即落 entry——
+  // 运行中 GUI 经 entry 重建 record 即得 ①②级读取钥匙（不等 run resolve）
+  // ============================================================
+
+  it("[onHandleReady] create 应答后回调 → record.engineHandle 立即回填 + reportRecordTransition 落 entry（record 仍 running）", async () => {
+    process.env.XYZ_AGENT_DATA_DIR = agentDir;
+    const { service, zcode, pi } = setup(agentDir);
+    const POOL = "zcode-appserver-home";
+    let releaseRun!: (v: { handle: EngineHandle; outcome: AgentOutcome }) => void;
+    zcode.runImpl = (task, ctx) => {
+      ctx.onPoolResolved?.(POOL);
+      // create 应答后的回调时点（app-server 引擎在 session/create 应答后触发）
+      ctx.onHandleReady?.({
+        sessionRef: { dbPath: ".zcode/cli/db/db.sqlite", sessionId: "sess-live-1" },
+        poolKey: POOL,
+      });
+      return new Promise((resolve) => {
+        releaseRun = resolve; // 挂起 run——模拟运行中任务
+      });
+    };
+    const handle = await service.execute(baseOpts(agentDir, { engine: "zcode" }));
+    await vi.waitFor(() => expect(zcode.runs.length).toBe(1));
+
+    // run 尚未 resolve（record 仍 running）：engineHandle 已回填且 entry 已落盘
+    await vi.waitFor(() => {
+      const entries = pi.appendEntry.mock.calls.filter((c) => c[0] === "subagent-record");
+      const withHandle = entries.filter(
+        (c) => (c[1] as Record<string, unknown>).engineHandle !== undefined,
+      );
+      expect(withHandle.length).toBeGreaterThan(0);
+    });
+    const running = service["collectRecords"](10, "running").find((r) => r.id === handle.subagentId);
+    expect(running?.engineHandle).toEqual({
+      sessionRef: { dbPath: ".zcode/cli/db/db.sqlite", sessionId: "sess-live-1" },
+      poolKey: POOL,
+      journalPath: resolveJournalPath(agentDir, "zcode", POOL, handle.subagentId),
+    });
+    // 回填 entry 的 journalPath 与 onPoolResolved retarget 后的实际落盘路径一致（同源）
+    expect(fs.existsSync(resolveJournalPath(agentDir, "zcode", POOL, handle.subagentId))).toBe(false);
+
+    // 终态收口（防 dangling）
+    releaseRun({ handle: fakeHandle(), outcome: doneOutcome("ok") });
+    await vi.waitFor(() => expect(service["findRecord"](handle.subagentId)).toBeUndefined());
+  }, 10_000);
+
+  it("[onHandleReady] 引擎不回调（spawn 形态）时零回填——终态回填仍兜底（行为不变）", async () => {
+    process.env.XYZ_AGENT_DATA_DIR = agentDir;
+    const { service, zcode, pi } = setup(agentDir);
+    const POOL = "zcode-p-glm";
+    zcode.runImpl = (task, ctx) => {
+      ctx.onPoolResolved?.(POOL); // 只 onPoolResolved——spawn 引擎形态（无 onHandleReady）
+      return Promise.resolve({
+        handle: {
+          data: { v: 1, engineId: "zcode", sessionRef: { dbPath: "sessions.db", sessionId: "sess-1" }, poolKey: POOL, adapterVersion: "test" },
+        },
+        outcome: doneOutcome("ok"),
+      });
+    };
+    const handle = await service.execute(baseOpts(agentDir, { engine: "zcode" }));
+    await vi.waitFor(() => expect(service["findRecord"](handle.subagentId)).toBeUndefined());
+    const entries = pi.appendEntry.mock.calls.filter((c) => c[0] === "subagent-record");
+    // 运行中回填 entry 不存在（register 写点无 engineHandle；archive 终态侧才有）
+    const runningEntries = entries.slice(0, -1);
+    for (const c of runningEntries) {
+      expect((c[1] as Record<string, unknown>).engineHandle).toBeUndefined();
+    }
+    const final = entries[entries.length - 1][1] as Record<string, unknown>;
+    expect(final.engineHandle).toMatchObject({ poolKey: POOL });
+  });
+
   it("[D5 回归] pi 纯缺省路径 entry 不含 engine/engineFallback/engineHandle 键", async () => {
     const { service, pi } = setup(agentDir);
     const handle = await service.execute(baseOpts(agentDir));
     await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
 
-    const rec = service.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
+    const rec = service.queries.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
     const entryJson = JSON.stringify(toSubagentRecordEntry(rec!));
     expect(entryJson).not.toContain("engineFallback");
     expect(entryJson).not.toContain("engineHandle");
@@ -589,7 +695,7 @@ describe("chat 引擎分支 U2：probe 兜底 / journal / engineHandle", () => {
       const h = await service.execute(baseOpts(agentDir, { engine: "zcode" }));
       // 等本条终态化（record 离开内存）再发下一条——泄漏形态下第 7 条 acquire 永久
       // 排队、record 永卡 running，本 waitFor 即超时失败
-      await vi.waitFor(() => expect(service.findRecord(h.subagentId)).toBeUndefined());
+      await vi.waitFor(() => expect(service.queries.findRecord(h.subagentId)).toBeUndefined());
     }
     // 7 次引擎 run 全部真实执行（第 7 次未被泄漏槽阻塞）
     expect(zcode.runs.length).toBe(7);

package/src/execution/__tests__/chatmode-first-round-closure-spawn.test.ts

@@ -58,9 +58,10 @@ vi.mock("../alive-store.ts", () => ({ writeAliveMarker: vi.fn() }));
 // chatMode agent_end 早返回（continue），不读 session-pending；统一 count=0 防干扰。
 vi.mock("../session-pending.ts", () => ({
   readActivePendingFromSessionFile: vi.fn(() => ({ count: 0 })),
+  prunePendingCursor: vi.fn(),
 }));
 
-vi.mock("../temp-prompt.ts", () => ({
+vi.mock("../engine/engines/pi/temp-prompt.ts", () => ({
   writePromptToTempFile: vi.fn(async (agent: string) => {
     const safeName = agent.replace(/[^\w.-]+/g, "_");
     return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
@@ -68,8 +69,8 @@ vi.mock("../temp-prompt.ts", () => ({
   cleanupTempPrompt: vi.fn(async () => {}),
 }));
 
-import { runSpawn } from "../session-runner.ts";
-import type { SessionRunnerContext } from "../session-runner.ts";
+import { runSpawn } from "../engine/engines/pi/session-runner.ts";
+import type { SessionRunnerContext } from "../engine/engines/pi/session-runner.ts";
 import { _resetLifecycleState } from "../lifecycle-manager.ts";
 import { createRecord } from "../execution-record.ts";
 import type { ExecutionRecord } from "../types.ts";
@@ -94,7 +95,7 @@ function makeChatModeRecord(id = "sa-chat"): ExecutionRecord {
   return createRecord(id, {
     agent: "general-purpose",
     model: "test-model",
-    mode: "sync",
+    mode: "background",
     task: "chat task",
     slug: "chat",
     startedAt: 1_000_000,

package/src/execution/__tests__/cold-resurrect.test.ts

@@ -0,0 +1,283 @@
+// src/execution/__tests__/cold-resurrect.test.ts
+//
+// [D4-③] coldLookupForAction 单元测试（依赖注入直测）。
+//
+// 背景：cold-resurrect.ts 自 SubagentService 搬移后按 ColdResurrectDeps 依赖注入
+// 设计，此前仅有经 subagent-service 集成路径的 running 重建覆盖——closed 可重连
+// 候选的「恢复失败守卫 / 部分恢复回边」（assertReconnectAllowed / resurrectColdRecord
+// 的 wasClosed 分支）零直测。本文件锁定这些路径的可观察行为：
+//   - 恢复失败：worktree 绑定丢失 / 异进程活实例（closed 与 running 候选）→
+//     ResurrectDeniedError 且内存无残留（register 不被调用）；
+//   - 部分恢复：closed 可重连记录 → resurrectClosed 回边翻回 running + 磁盘终态位
+//     同步翻转（.finalized 删除 + .alive 刷新当前进程）+ register/transition 上报；
+//   - 恢复源缺失：sessionFile 缺失 / sidecar 翻转失败（目录不存在）均不阻断重生
+//     （best-effort 语义）。
+//
+// fixture 一律 mkdtempSync 自建自删（tmpdir），不触碰真实数据目录。
+
+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 { readAliveMarker, writeAliveMarker } from "../alive-store.ts";
+import { COLD_LOOKUP_SCAN_LIMIT, coldLookupForAction, type ColdResurrectDeps } from "../cold-resurrect.ts";
+import type { SubagentRecord } from "../types.ts";
+import { ResurrectDeniedError } from "../types.ts";
+
+/** 磁盘/索引侧候选记录（SubagentRecord 最小合法形状 + closed 可重连缺省）。 */
+function makeFound(overrides: Partial<SubagentRecord> = {}): SubagentRecord {
+  return {
+    id: "sa-cold-1",
+    agent: "general-purpose",
+    task: "cold recovery task",
+    slug: "cold-test",
+    status: "closed",
+    closedReason: "parent-shutdown",
+    mode: "background",
+    startedAt: 1_700_000_000_000,
+    rootSessionId: "root-session",
+    parentRecordId: undefined,
+    depth: 0,
+    endedAt: 1_700_000_100_000,
+    turns: 0,
+    totalTokens: 0,
+    model: "test/model-a",
+    thinkingLevel: undefined,
+    eventLog: [],
+    displayItems: [],
+    ...overrides,
+  };
+}
+
+interface DepOverrides {
+  /** findLightById（idToFile 索引直查）返回值。 */
+  direct?: SubagentRecord;
+  /** collectRecords（磁盘全扫）返回清单。 */
+  disk?: SubagentRecord[];
+  /** getSessionRootId 返回值（归属校验）。 */
+  rootId?: string;
+  /** getBaselineRecordId 返回值（直接父校验）。 */
+  baseline?: string;
+}
+
+/** 构造依赖注入桩（register / reportRecordTransition 可断言副作用）。 */
+function makeDeps(o: DepOverrides = {}): ColdResurrectDeps {
+  return {
+    findLightById: vi.fn(() => o.direct),
+    collectRecords: vi.fn(() => o.disk ?? []),
+    register: vi.fn(),
+    reportRecordTransition: vi.fn(),
+    getSessionRootId: vi.fn(() => o.rootId ?? "root-session"),
+    getBaselineRecordId: vi.fn(() => o.baseline),
+  };
+}
+
+describe("[D4-③] coldLookupForAction 冷查/复活链", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "cold-resurrect-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  /** tmpdir 下建 session 文件 + 可选 .finalized sidecar，返回 sessionFile 路径。 */
+  function writeSessionFixture(opts: { finalized?: string; aliveMarker?: string } = {}): string {
+    const sessionFile = path.join(dir, "20260901T000000-000_sa-cold-1.jsonl");
+    fs.writeFileSync(sessionFile, "{}\n", "utf-8");
+    if (opts.finalized !== undefined) {
+      fs.writeFileSync(`${sessionFile}.finalized`, opts.finalized, "utf-8");
+    }
+    if (opts.aliveMarker !== undefined) {
+      fs.writeFileSync(`${sessionFile}.alive`, opts.aliveMarker, "utf-8");
+    }
+    return sessionFile;
+  }
+
+  // ── 部分恢复（closed 可重连 → 透明重生回边）──
+
+  it("closed 可重连记录（parent-shutdown）+ allowReconnect → 重生翻回 running：终态位清除、sidecar 翻转、register + transition 上报", () => {
+    const sessionFile = writeSessionFixture({ finalized: JSON.stringify({ reason: "parent-shutdown" }) });
+    const found = makeFound({ sessionFile, round: 2 });
+    const deps = makeDeps({ disk: [found] });
+
+    const record = coldLookupForAction(deps, "sa-cold-1", true)!;
+
+    // 重生回边：closed → running，终态语义位清除
+    expect(record.status).toBe("running");
+    expect(record.closedReason).toBeUndefined();
+    expect(record.endedAt).toBeUndefined();
+    // [v4 A-3] 跨重启恢复入口：chatMode 无条件 true
+    expect(record.chatMode).toBe(true);
+    // 身份/续聊字段从磁盘候选回填
+    expect(record.sessionFile).toBe(sessionFile);
+    expect(record.round).toBe(2);
+    expect(record.model).toBe("test/model-a");
+    expect(record.hadWorktree).toBe(false);
+    // register + [v8.5 D] 重生后立刻上报 transition entry（live ≡ reload）
+    expect(vi.mocked(deps.register)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(deps.register)).toHaveBeenCalledWith(record);
+    expect(vi.mocked(deps.reportRecordTransition)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(deps.reportRecordTransition)).toHaveBeenCalledWith(record);
+    // [review MF-8] 磁盘终态位同步翻转：.finalized 删除 + .alive 刷新为当前进程
+    expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(false);
+    expect(readAliveMarker(sessionFile)).toMatchObject({ pid: process.pid, id: "sa-cold-1" });
+    // 冷查扫描契约：全目录兜底按 COLD_LOOKUP_SCAN_LIMIT 上限扫全量（无 root 过滤）
+    expect(vi.mocked(deps.collectRecords)).toHaveBeenCalledWith(COLD_LOOKUP_SCAN_LIMIT, "all", undefined);
+  });
+
+  it("idToFile 索引直查返回非 running 态 → 回退磁盘全扫兜底定位（closed 候选仍可重连）", () => {
+    const sessionFile = writeSessionFixture();
+    const found = makeFound({ sessionFile });
+    // direct 命中但 status=closed → 不直接采用，落到 collectRecords 兜底
+    const deps = makeDeps({ direct: found, disk: [found] });
+
+    const record = coldLookupForAction(deps, "sa-cold-1", true)!;
+
+    expect(record.status).toBe("running");
+    expect(vi.mocked(deps.collectRecords)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(deps.register)).toHaveBeenCalledWith(record);
+  });
+
+  it("closed disconnected（.finalized 空内容兜底死因）同样落在可重连集内", () => {
+    const sessionFile = writeSessionFixture({ finalized: "" });
+    const deps = makeDeps({ disk: [makeFound({ sessionFile, closedReason: "disconnected" })] });
+
+    const record = coldLookupForAction(deps, "sa-cold-1", true)!;
+
+    expect(record.status).toBe("running");
+    expect(vi.mocked(deps.register)).toHaveBeenCalledTimes(1);
+  });
+
+  // ── 恢复失败守卫（ResurrectDeniedError + 内存无残留）──
+
+  it("worktree 绑定丢失（跨重启 WorktreeHandle 不可序列化）→ ResurrectDeniedError 拒绝，register 不残留", () => {
+    const sessionFile = writeSessionFixture();
+    const deps = makeDeps({ disk: [makeFound({ sessionFile, worktree: true })] });
+
+    expect(() => coldLookupForAction(deps, "sa-cold-1", true)).toThrow(ResurrectDeniedError);
+    expect(() => coldLookupForAction(deps, "sa-cold-1", true)).toThrow(/worktree isolation/);
+    expect(vi.mocked(deps.register)).not.toHaveBeenCalled();
+  });
+
+  it("closed 候选仍有异进程活实例（.alive 指向活 pid）→ 拒绝双写，register 不残留", () => {
+    // 用本测试进程 pid 模拟「另一进程的活跃实例」——isProcessAlive 判活为真
+    const sessionFile = writeSessionFixture();
+    writeAliveMarker(sessionFile, { pid: process.pid, id: "sa-cold-1", startedAt: Date.now() });
+    const deps = makeDeps({ disk: [makeFound({ sessionFile })] });
+
+    expect(() => coldLookupForAction(deps, "sa-cold-1", true)).toThrow(ResurrectDeniedError);
+    expect(() => coldLookupForAction(deps, "sa-cold-1", true)).toThrow(
+      /still finishing in another process/,
+    );
+    expect(vi.mocked(deps.register)).not.toHaveBeenCalled();
+  });
+
+  it("running 候选仍有异进程活实例（父进程重启后旧子进程尚存窗口）→ 拒绝并给恢复指引", () => {
+    const sessionFile = writeSessionFixture();
+    writeAliveMarker(sessionFile, { pid: process.pid, id: "sa-cold-1", startedAt: Date.now() });
+    const deps = makeDeps({ disk: [makeFound({ sessionFile, status: "running" })] });
+
+    expect(() => coldLookupForAction(deps, "sa-cold-1", true)).toThrow(ResurrectDeniedError);
+    expect(() => coldLookupForAction(deps, "sa-cold-1", true)).toThrow(
+      /currently running in another process instance/,
+    );
+    expect(vi.mocked(deps.register)).not.toHaveBeenCalled();
+  });
+
+  it("损坏 .alive marker（无法解析）→ 视为确死放行重生，marker 被当前进程覆盖写", () => {
+    const sessionFile = writeSessionFixture({
+      finalized: JSON.stringify({ reason: "parent-shutdown" }),
+      aliveMarker: "{not valid json",
+    });
+    const deps = makeDeps({ disk: [makeFound({ sessionFile })] });
+
+    const record = coldLookupForAction(deps, "sa-cold-1", true)!;
+
+    expect(record.status).toBe("running");
+    expect(readAliveMarker(sessionFile)).toMatchObject({ pid: process.pid });
+    expect(vi.mocked(deps.register)).toHaveBeenCalledTimes(1);
+  });
+
+  // ── 候选过滤 / 归属与父层校验 ──
+
+  it.each([
+    ["自然完成死因 gc", makeFound({ closedReason: "gc" })],
+    ["用户主动 close", makeFound({ closedReason: "user-close" })],
+  ])("不可重连死因（%s）→ 磁盘也无候选，返回 undefined", (_label, found) => {
+    const deps = makeDeps({ disk: [found] });
+
+    expect(coldLookupForAction(deps, "sa-cold-1", true)).toBeUndefined();
+    expect(vi.mocked(deps.register)).not.toHaveBeenCalled();
+  });
+
+  it("allowReconnect=false：closed 候选一律不可见（running-only 查询语义）", () => {
+    const sessionFile = writeSessionFixture();
+    const deps = makeDeps({ disk: [makeFound({ sessionFile })] });
+
+    expect(coldLookupForAction(deps, "sa-cold-1", false)).toBeUndefined();
+    expect(vi.mocked(deps.register)).not.toHaveBeenCalled();
+  });
+
+  it("rootSessionId 不匹配 → 返回 undefined（不区分失败形态，防跨 session 探测）", () => {
+    const deps = makeDeps({ disk: [makeFound({ rootSessionId: "other-root" })], rootId: "root-session" });
+
+    expect(coldLookupForAction(deps, "sa-cold-1", true)).toBeUndefined();
+    expect(vi.mocked(deps.register)).not.toHaveBeenCalled();
+  });
+
+  it("parentRecordId 跨层不匹配（候选有直接父）→ 原样抛 direct parent 错误（跨层导航指引）", () => {
+    const deps = makeDeps({
+      disk: [makeFound({ status: "running", parentRecordId: "sa-parent" })],
+      baseline: undefined,
+    });
+
+    expect(() => coldLookupForAction(deps, "sa-cold-1", true)).toThrow(/is owned by its direct parent/);
+    expect(() => coldLookupForAction(deps, "sa-cold-1", true)).toThrow(/parent=sa-parent/);
+    expect(vi.mocked(deps.register)).not.toHaveBeenCalled();
+  });
+
+  it("顶层候选（parentRecordId 缺失）遇嵌套进程 baseline → direct parent 错误带 (root layer) 回显", () => {
+    const deps = makeDeps({
+      disk: [makeFound({ status: "running", parentRecordId: undefined })],
+      baseline: "rec-baseline-child",
+    });
+
+    expect(() => coldLookupForAction(deps, "sa-cold-1", true)).toThrow(
+      /parent=\(root layer\)/,
+    );
+    expect(vi.mocked(deps.register)).not.toHaveBeenCalled();
+  });
+
+  // ── 恢复源缺失（best-effort 不阻断重生主流程）──
+
+  it("sessionFile 缺失的 closed 候选 → 跳过 sidecar 翻转，重生照常完成（register + transition 上报）", () => {
+    const deps = makeDeps({ disk: [makeFound({ sessionFile: undefined })] });
+
+    const record = coldLookupForAction(deps, "sa-cold-1", true)!;
+
+    expect(record.status).toBe("running");
+    expect(record.sessionFile).toBeUndefined();
+    expect(vi.mocked(deps.register)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(deps.reportRecordTransition)).toHaveBeenCalledTimes(1);
+  });
+
+  it("sidecar 翻转失败（sessionFile 所在目录不存在，writeAliveMarker ENOENT）→ best-effort 吞错，重生不中断", () => {
+    // 恢复源缺失形态：sessionFile 指向已消失的目录（推导路径过期 / 目录被清理）
+    const sessionFile = path.join(dir, "vanished-dir", "20260901T000000-000_sa-cold-1.jsonl");
+    const deps = makeDeps({ disk: [makeFound({ sessionFile })] });
+
+    const record = coldLookupForAction(deps, "sa-cold-1", true)!;
+
+    // best-effort：sidecar 翻转失败不阻断重生主流程（状态回边与注册照常）
+    expect(record.status).toBe("running");
+    expect(vi.mocked(deps.register)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(deps.reportRecordTransition)).toHaveBeenCalledTimes(1);
+    // marker 写入确实失败（目录不存在，未落盘）
+    expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
+  });
+});