@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/execution/__tests__/epipe-fallback.test.ts

@@ -27,6 +27,8 @@ vi.mock("../session-runner.ts", () => {
   return {
     runSpawn: vi.fn(),
     killAllSpawnedChildren: vi.fn(),
+    registerSpawnedChildForRecord: vi.fn(),
+    killRecordChildWithEscalation: vi.fn(),
     spawnedChildren,
     getChildByRecord: (id: string): unknown => spawnedChildren.get(id),
   };

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 });
+  });
+
+  // ============================================================
+  // ① 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__/finalize-record.test.ts

@@ -181,6 +181,96 @@ 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 });
+    });
+
+    /** 在 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();
+    });
+  });
 });
 
 // ============================================================
@@ -317,6 +407,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";

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

@@ -30,6 +30,8 @@ vi.mock("../session-runner.ts", () => ({
   runSpawn: vi.fn(),
   killAllSpawnedChildren: vi.fn(),
   getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  killRecordChildWithEscalation: vi.fn(),
   spawnedChildren: new Map(),
 }));
 

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

@@ -31,6 +31,8 @@ vi.mock("../session-runner.ts", () => ({
   runSpawn: vi.fn(),
   killAllSpawnedChildren: vi.fn(),
   getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  killRecordChildWithEscalation: vi.fn(),
   spawnedChildren: new Map(),
 }));
 

package/src/execution/__tests__/get-state-handshake.test.ts

@@ -0,0 +1,127 @@
+// src/execution/__tests__/get-state-handshake.test.ts
+//
+// [T1/RC-1] requestGetStateOnce 单测：agent_end 决策点惰性回补用的单次 get_state 请求辅助。
+//
+// 契约锚点（与 performGetStateHandshake 共用消息构造 sendGetStateCommand + 字段提取
+// extractGetStateFields，但不做重试循环）：
+//   1. response 到达 → resolve 提取后的 GetStateResult（无条件 finish，单次语义无重试）；
+//   2. 超时 → resolve 空对象（调用方走保守分支）；
+//   3. stdin 同步写失败（EPIPE 形态）→ resolve 空对象、永不 reject（fire-and-forget 契约）；
+//   4. 自清理：finish 后从监听表注销本请求 resolver（消费注册器返回的注销函数）；
+//      注册器不返回注销函数时退化为 no-op（与握手同形态）。
+//
+// performGetStateHandshake 既有行为由 run-spawn-rpc-mode.test.ts 集成覆盖，此处不重复。
+
+import { describe, expect, it, vi } from "vitest";
+
+import { requestGetStateOnce } from "../get-state-handshake.ts";
+import type { ChildProcess } from "node:child_process";
+
+/** 最小 FakeChild：只需 stdin.write 行为（成功 / 可注入同步 throw）。 */
+function makeFakeStdin(behavior?: { throwOnWrite?: Error }): { child: ChildProcess; writes: string[] } {
+  const writes: string[] = [];
+  const child = {
+    stdin: {
+      write(line: string): boolean {
+        if (behavior?.throwOnWrite) throw behavior.throwOnWrite;
+        writes.push(line);
+        return true;
+      },
+    },
+  } as unknown as ChildProcess;
+  return { child, writes };
+}
+
+/** 可控的监听表：模拟 stdout pump 的 get_stateListeners（注册返回注销函数）。 */
+function makeListenerRegistry() {
+  const resolvers = new Map<string, (data: unknown) => void>();
+  const removed: string[] = [];
+  const add = (id: string, resolver: (data: unknown) => void) => {
+    resolvers.set(id, resolver);
+    return () => {
+      if (resolvers.get(id) === resolver) resolvers.delete(id);
+      removed.push(id);
+    };
+  };
+  return { resolvers, removed, add };
+}
+
+describe("requestGetStateOnce（[T1/RC-1] 惰性回补单次请求）", () => {
+  it("response 到达 → resolve 提取的 sessionFile/sessionId，并从监听表注销", async () => {
+    const { child, writes } = makeFakeStdin();
+    const reg = makeListenerRegistry();
+
+    const promise = requestGetStateOnce(child, reg.add, 1000);
+    // 消息构造：单行 JSON {id, type:"get_state"}（与 performGetStateHandshake 同一 sendGetStateCommand）
+    expect(writes).toHaveLength(1);
+    const sent = JSON.parse(writes[0]!) as { id: string; type: string };
+    expect(sent.type).toBe("get_state");
+    expect(reg.resolvers.has(sent.id)).toBe(true);
+
+    // response 到达（含空串 sessionFile 应被过滤的字段形态覆盖提取规则）
+    reg.resolvers.get(sent.id)?.({
+      sessionFile: "/tmp/sessions/abc.jsonl",
+      sessionId: "sess-1",
+    });
+
+    await expect(promise).resolves.toEqual({
+      sessionFile: "/tmp/sessions/abc.jsonl",
+      sessionId: "sess-1",
+    });
+    // 自清理：finish 后从监听表移除本请求 resolver
+    expect(reg.resolvers.has(sent.id)).toBe(false);
+    expect(reg.removed).toEqual([sent.id]);
+  });
+
+  it("response 只含部分字段（仅 sessionId）→ resolve 已提取部分（单次语义：到达即 finish，不等重试）", async () => {
+    const { child } = makeFakeStdin();
+    const reg = makeListenerRegistry();
+
+    const promise = requestGetStateOnce(child, reg.add, 1000);
+    const id = reg.resolvers.keys().next().value as string;
+    reg.resolvers.get(id)?.({ sessionId: "only-id" });
+
+    await expect(promise).resolves.toEqual({ sessionId: "only-id" });
+  });
+
+  it("超时无 response → resolve 空对象（不 reject，不调注销前的 resolver）", async () => {
+    vi.useFakeTimers();
+    try {
+      const { child } = makeFakeStdin();
+      const reg = makeListenerRegistry();
+
+      const promise = requestGetStateOnce(child, reg.add, 1000);
+      await vi.advanceTimersByTimeAsync(1000);
+
+      await expect(promise).resolves.toEqual({});
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("stdin 同步写失败（EPIPE code，writeStdinLine rethrow 路径）→ 立即 resolve 空对象、永不 reject", async () => {
+    // writeStdinLine 只对 code 为 EPIPE / ERR_STREAM_DESTROYED 的错误 rethrow（[R3]），
+    // requestGetStateOnce 的 catch 捕获后按「回补失败」resolve 空对象（同超时语义）。
+    const epipeErr = Object.assign(new Error("write after end"), { code: "EPIPE" });
+    const { child } = makeFakeStdin({ throwOnWrite: epipeErr });
+    const reg = makeListenerRegistry();
+
+    await expect(requestGetStateOnce(child, reg.add, 1000)).resolves.toEqual({});
+    // 写失败路径不注册监听（未发出请求）
+    expect(reg.resolvers.size).toBe(0);
+  });
+
+  it("注册器不返回注销函数（void 形态，对齐旧握手调用方）→ 正常 resolve 不抛", async () => {
+    const { child } = makeFakeStdin();
+    const resolvers = new Map<string, (data: unknown) => void>();
+    const addVoid = (id: string, resolver: (data: unknown) => void): void => {
+      resolvers.set(id, resolver);
+    };
+
+    const promise = requestGetStateOnce(child, addVoid, 1000);
+    const id = resolvers.keys().next().value as string;
+    resolvers.get(id)?.({ sessionFile: "/tmp/x.jsonl" });
+
+    await expect(promise).resolves.toEqual({ sessionFile: "/tmp/x.jsonl" });
+  });
+});