@zhushanwen/subagent-core 0.2.0

package/src/execution/__tests__/format-schema-instruction.test.ts

@@ -0,0 +1,169 @@
+// src/execution/__tests__/format-schema-instruction.test.ts
+//
+// 锁定 formatSchemaInstruction 契约：构造 schema enforcement 的 MANDATORY 指令。
+// [审查项#2] 注入链变更：指令仅经 agent-opts-resolver 进 appendSystemPrompt
+// （ASP 单点），runSpawn 的 task + instruction 后缀拼接已删除——本测试随之改锁
+// resolver 导出的同名函数。一旦漏掉 "structured-output" 关键词或 JSON 序列化漂移，
+// schema 模式会静默失效——agent 可能直接把 JSON 写进文本响应。
+//
+// [审查项#4] 锁定 AP 告知句：注入侧校验用 additionalProperties:false 收窄后的
+// parameters，指令必须前置告知「schema 外字段被拒」，否则拒绝显得凭空。
+//
+// 纯函数测试：不依赖 Pi 运行时、不 spawn 进程、不 mock。只 import 被测函数。
+import { describe, expect, it } from "vitest";
+
+import { formatSchemaInstruction } from "../../orchestration/agent-opts-resolver.ts";
+
+describe("formatSchemaInstruction", () => {
+  // ── 指令文本契约 ──────────────────────────────────────────────
+
+  it("contains the structured-output tool keyword", () => {
+    const out = formatSchemaInstruction({ type: "object" });
+    expect(out).toContain("structured-output");
+  });
+
+  it("emits a MANDATORY structured-output directive (not free-form JSON)", () => {
+    const out = formatSchemaInstruction({ type: "object" });
+    expect(out).toContain("MANDATORY");
+    expect(out).toContain("must be calling the `structured-output` tool");
+    expect(out).toContain("Do NOT output JSON in your text response");
+  });
+
+  it("announces that fields outside the schema are rejected (AP 告知，审查项#4)", () => {
+    const out = formatSchemaInstruction({ type: "object" });
+    expect(out).toContain("Fields not defined in this schema are rejected");
+    expect(out).toContain("do not add extra fields");
+  });
+
+  it("author-declared additionalProperties → weak wording (AP 条件化：声明时作者 schema 管辖额外字段)", () => {
+    // D4 只在「未声明」时注入 false；作者显式声明 true 时额外字段实际放行——
+    // 无条件「一律拒绝」强承诺与参数层行为不符，改用弱承诺措辞。
+    const out = formatSchemaInstruction({ type: "object", additionalProperties: true });
+    expect(out).not.toContain("Fields not defined in this schema are rejected");
+    expect(out).toContain("follow this schema's own additionalProperties declaration");
+  });
+
+  // ── schema 序列化（compact：与 schemaEnv 复用同串，IF7 #13）───────
+
+  it("embeds the schema as compact JSON inside a fenced block", () => {
+    const schema: Record<string, unknown> = {
+      type: "object",
+      properties: { name: { type: "string" } },
+    };
+    const out = formatSchemaInstruction(schema);
+    // 必须包含 JSON.stringify(schema) 的完整结果（compact，无缩进）
+    expect(out).toContain(JSON.stringify(schema));
+    expect(out).toContain("```json");
+    expect(out).toContain("```");
+  });
+
+  it("locks the full output structure for a minimal schema", () => {
+    const out = formatSchemaInstruction({ type: "object" });
+    // 完整结构快照——任何指令措辞/顺序/序列化漂移都会被捕获。
+    // [HISTORICAL] runner task 后缀双重注入删除后，本函数迁至 resolver 成为唯一
+    // 文案源；JSON 从 pretty（indent=2）改为 compact（与 schemaEnv 同串复用）。
+    expect(out).toBe(
+      [
+        "## MANDATORY: Structured Output Requirement",
+        "",
+        "This task requires structured output.",
+        "Your FINAL action must be calling the `structured-output` tool.",
+        "",
+        "Your call arguments ARE the result data itself — the tool's parameter schema IS the required shape of your result.",
+        "Your result must conform to this schema:",
+        "```json",
+        '{"type":"object"}',
+        "```",
+        "",
+        "Rules:",
+        "- Call the structured-output tool with your result data as its arguments. The system validates them against the schema above automatically.",
+        "- Do NOT output JSON in your text response — use the structured-output tool.",
+        "- Do NOT skip this step. The structured-output call IS your result.",
+        "- Complete all other work FIRST, then call structured-output as the last action.",
+        "- Fields not defined in this schema are rejected — do not add extra fields.",
+      ].join("\n"),
+    );
+  });
+
+  it("locks the single-parameter wording: arguments ARE the data coexists with the mandatory tool call", () => {
+    const out = formatSchemaInstruction({ type: "object" });
+    // 新口径双支柱必须共存：① 参数即数据（arguments ARE the data）② 必须调用工具
+    expect(out).toContain("arguments ARE the result data itself");
+    expect(out).toContain("parameter schema IS the required shape of your result");
+    expect(out).toContain("must be calling the `structured-output` tool");
+    // 旧双参数警告语义不得回流（工具已是单参数形态，警告失去对象）
+    expect(out).not.toMatch(/do NOT pass a .schema. parameter/i);
+    expect(out).not.toContain("ONLY the `data` parameter");
+    expect(out).not.toContain("enforced by the system");
+  });
+
+  // ── 特殊字符转义（注入风险路径）──────────────────────────────
+
+  it("escapes double quotes inside schema string values", () => {
+    const schema: Record<string, unknown> = { prompt: 'say "hi"' };
+    const out = formatSchemaInstruction(schema);
+    // JSON.stringify 会把内层 " 转义为 \"
+    expect(out).toContain('say \\"hi\\"');
+    // 原始未转义形式（含成对字面双引号）绝不能回流进 JSON 体内
+    expect(out).not.toContain('say "hi"');
+  });
+
+  it("escapes newlines inside schema string values", () => {
+    const schema: Record<string, unknown> = { text: "line1\nline2" };
+    const out = formatSchemaInstruction(schema);
+    // 换行被序列化为字面反斜杠-n，不能是真实换行符
+    expect(out).toContain("line1\\nline2");
+    expect(out).not.toContain("line1\nline2");
+  });
+
+  it("escapes backslashes inside schema string values", () => {
+    const schema: Record<string, unknown> = { path: "C:\\Users\\x" };
+    const out = formatSchemaInstruction(schema);
+    // 单反斜杠被序列化为 \\，避免后续解析误把转义序列当指令
+    expect(out).toContain("C:\\\\Users\\\\x");
+    expect(out).not.toContain("C:\\Users\\x");
+  });
+
+  // ── 边界值 ────────────────────────────────────────────────────
+
+  it("handles empty schema object", () => {
+    const out = formatSchemaInstruction({});
+    expect(out).toContain("structured-output");
+    expect(out).toContain("{}");
+  });
+
+  it("preserves null values in schema", () => {
+    const schema: Record<string, unknown> = { default: null };
+    const out = formatSchemaInstruction(schema);
+    // JSON.stringify 对 null 保留字面 "null"（不会 omit 键，也不会变字符串）。
+    // compact 序列化无空格：'"default":null'
+    expect(out).toContain('"default":null');
+  });
+
+  it("serializes nested objects and arrays", () => {
+    const schema: Record<string, unknown> = {
+      type: "object",
+      required: ["name", "age"],
+      properties: {
+        name: { type: "string" },
+        age: { type: "integer", minimum: 0 },
+      },
+    };
+    const out = formatSchemaInstruction(schema);
+    expect(out).toContain(JSON.stringify(schema));
+  });
+
+  // ── 确定性 ────────────────────────────────────────────────────
+
+  it("is deterministic — same schema produces identical output", () => {
+    const schema: Record<string, unknown> = { a: 1, b: [2, 3] };
+    expect(formatSchemaInstruction(schema)).toBe(formatSchemaInstruction(schema));
+  });
+
+  it("is deterministic across different object key insertion (value-equal schemas)", () => {
+    // JSON.stringify 按对象自身属性顺序序列化；同序构造的等价 schema 应产出相同指令
+    const a: Record<string, unknown> = { x: 1, y: 2 };
+    const b: Record<string, unknown> = { x: 1, y: 2 };
+    expect(formatSchemaInstruction(a)).toBe(formatSchemaInstruction(b));
+  });
+});

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

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

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

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

package/src/execution/__tests__/helpers/mock-extension-api.ts

@@ -0,0 +1,30 @@
+/**
+ * 创建一个结构兼容的 ExtensionAPI mock，供 sdk-contract / 注册契约测试用。
+ *
+ * ExtensionAPI 有 ~30 个必需方法（on/registerTool/registerCommand/...），逐个手写
+ * 不现实。本 helper 用 Proxy 把所有未显式 override 的方法/属性短路为 no-op 函数，
+ * 让对象**结构兼容** ExtensionAPI——避免 `as unknown as ExtensionAPI` 双重断言
+ * （taste/no-unsafe-cast 规则禁止）。测试只需 override 关心的方法：
+ *
+ *   const pi = mockExtensionApi({
+ *     registerCommand: (name) => { capturedName = name; },
+ *   });
+ *
+ * Proxy 的 trap 对所有属性访问返回 override 值或 no-op 函数，运行时安全
+ * （注册 handler 只调用被 override 的方法，其余方法测试不触及）。
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export function mockExtensionApi(
+  overrides: Record<string, unknown> = {},
+): ExtensionAPI {
+  const noop = (): void => { /* test mock: method not invoked by this test */ };
+  // Proxy<T> 泛型参数决定返回类型——直接声明为 ExtensionAPI，
+  // TS 接受（Proxy handler 对 target 的类型不约束 T）。
+  return new Proxy<ExtensionAPI>(overrides as ExtensionAPI, {
+    get(target, prop: string | symbol): unknown {
+      if (prop in target) return target[prop as keyof ExtensionAPI];
+      return noop;
+    },
+  });
+}