@zhushanwen/subagent-core 0.4.0 → 0.5.1

package/src/execution/cold-resurrect.ts

@@ -0,0 +1,199 @@
+// [D4-③ 冷路径复活职责轴] message action 冷查/复活链（原 SubagentService 私有的
+// findColdLookupCandidate / assertReconnectAllowed / resurrectColdRecord /
+// coldLookupForAction + isReconnectableClosed 判定）整体搬移至 record-store 邻接处
+// （行为逐字节等价：搬移 + 依赖注入，不重写逻辑）。变化轴：改跨重启重建 /
+// 透明重生回边 / 可重连守卫语义，只改本文件；Service 的 getRecordForAction 保留
+// 归属校验编排（内存未命中分支委托 coldLookupForAction）。
+
+import * as fs from "node:fs";
+
+import { findForeignLiveInstance, writeAliveMarker } from "./alive-store.ts";
+import { createRecord, resurrectClosed } from "./execution-record.ts";
+import type { StatusFilter } from "./record-store.ts";
+import type { ExecutionRecord, SubagentRecord } from "./types.ts";
+import { isReconnectableFinalReason, ResurrectDeniedError } from "./types.ts";
+
+/** SP-2 冷路径按 id 查 record 的 collectRecords 扫描上限（全扫兜底的容量 cap）。
+ *  原定义于 subagent-service.ts，随冷查链搬移；Service.lookupRecordAnyState
+ *  （全态查询）同样消费本常量。 */
+export const COLD_LOOKUP_SCAN_LIMIT = 1000;
+
+/** 冷查/复活的依赖注入（Service 侧供给，store 查询 + 归属上下文）。 */
+export interface ColdResurrectDeps {
+  /** store 的 idToFile 索引直查（light 快照）。 */
+  findLightById: (id: string) => SubagentRecord | undefined;
+  /** store 的磁盘全扫（内存未命中 / 索引未热时兜底）。rootFilter 恒 undefined
+   *  （冷查不做 root 过滤——归属校验在候选定位之后，见 coldLookupForAction）。 */
+  collectRecords: (limit: number, statusFilter: StatusFilter, rootFilter: undefined) => SubagentRecord[];
+  /** 重建 record 注册进内存 store。 */
+  register: (record: ExecutionRecord) => void;
+  /** 重建后的 transition entry 上报（live ≡ reload 等价性）。 */
+  reportRecordTransition: (record: ExecutionRecord) => void;
+  /** 当前所属根 session id（归属校验用，运行时可变——initSession 建立）。 */
+  getSessionRootId: () => string | null;
+  /** 本进程嵌套基线 recordId（直接父校验用；根进程 undefined）。 */
+  getBaselineRecordId: () => string | undefined;
+}
+
+/** 冷查候选定位（coldLookupForAction 步骤 1）：idToFile 索引直查 running 命中，
+ *  未命中再全目录 collectRecords 兜底（running，或 allowReconnect 且可重连 closed）。
+ *
+ *  [T5③ / PS-7b] running 候选异进程活实例守卫：冷查 running 候选（跨重启 / 内存重建）
+ *  此前不经任何探针直接 resurrect + resume spawn——若其 .alive marker 仍指向活着的
+ *  异进程实例（父进程重启后旧子进程尚存的窗口），resume 会 spawn 第二个 pi 子进程
+ *  写同一 session JSONL（本代码最忌惮的双写者形态，v4 A-5/P7 事故模式）。closed 候选
+ *  的同款守卫已在 assertReconnectAllowed（v8.5 D）；本守卫闭合 running 候选的防御
+ *  不对称。marker 的 pid 是子进程 pi 的 pid（非父进程），本进程持有的 running record
+ *  恒在内存（archive 才移出），可达本冷查分支的 running 候选必然来自磁盘重建——
+ *  探针命中即拒绝（ResurrectDeniedError，与 closed 候选守卫同异常类型，错误含 pid
+ *  与恢复指引）。 */
+function findColdLookupCandidate(
+  deps: ColdResurrectDeps,
+  id: string,
+  allowReconnect: boolean,
+): SubagentRecord | undefined {
+  const direct = deps.findLightById(id);
+  const found =
+    (direct?.status === "running" ? direct : undefined) ??
+    deps
+      .collectRecords(COLD_LOOKUP_SCAN_LIMIT, "all", undefined)
+      .find((r) => r.id === id && (r.status === "running" || (allowReconnect && isReconnectableClosed(r))));
+  if (found?.status === "running" && found.sessionFile) {
+    const foreign = findForeignLiveInstance(found.sessionFile);
+    if (foreign) {
+      throw new ResurrectDeniedError(
+        `subagent ${id} is currently running in another process instance (pid ${foreign.pid}, ` +
+          `startedAt=${new Date(foreign.startedAt).toISOString()}); resuming here would double-write ${found.sessionFile}. ` +
+          `Recovery: retry once that process exits; if it never exits, action:'close' this subagent, then action:'start' a fresh one.`,
+      );
+    }
+  }
+  return found;
+}
+
+/** [v8.5 D] 冷查候选过滤：closed 且死因落在可重连集。判定源 = closedReason（buildRecord
+ *  归一化后的对外字段：A 档真实死因直通、旧空 sidecar 兑底 disconnected——SubagentRecord
+ *  不暴露 raw finalizedReason）；cancelled/user-close/gc 等主动关闭与自然完成死因天然不在集合内。
+ *  防线在集合本身而非调用点。 */
+function isReconnectableClosed(r: SubagentRecord): boolean {
+  return isReconnectableFinalReason(r.closedReason);
+}
+
+/** 可重连守卫（coldLookupForAction 步骤 2，[v8.5 D]）：先于任何状态突变与注册。
+ *  worktree 绑定丢失 / 异进程活实例以 ResurrectDeniedError 抛出（endedMessageGuard
+ *  必须原样透传，不得改写为 fork-from 指引误导 agent 走已被判死的通道）；拒绝时
+ *  内存不得残留该记录（findRecord 契约）。 */
+function assertReconnectAllowed(found: SubagentRecord, id: string): void {
+  if (found.status !== "closed") return;
+  if (found.worktree === true) {
+    throw new ResurrectDeniedError(
+      `subagent ${id} cannot be transparently resumed: it was created with worktree isolation, ` +
+        `and its worktree checkout no longer exists after restart (resuming in place would make spawn cwd fall back to the main repo). ` +
+        `Recovery: action:'start' a fresh subagent (with a new worktree if isolation is still needed); ` +
+        `its conversation history remains intact at ${found.sessionFile}.`,
+    );
+  }
+  const foreign = found.sessionFile ? findForeignLiveInstance(found.sessionFile) : undefined;
+  if (foreign) {
+    throw new ResurrectDeniedError(
+      `subagent ${id} is not transparently resumable: its previous instance still finishing in another process ` +
+        `(pid ${foreign.pid}, startedAt=${new Date(foreign.startedAt).toISOString()}). ` +
+        `Resuming in place would double-write ${found.sessionFile}. ` +
+        `Recovery: retry once that process exits; if it never exits, action:'start' a fresh subagent and treat the history at ${found.sessionFile} as read-only reference.`,
+    );
+  }
+}
+
+/** 磁盘候选重建为可变 record 并 register + 上报（coldLookupForAction 步骤 4）。 */
+function resurrectColdRecord(
+  deps: ColdResurrectDeps,
+  found: SubagentRecord,
+  id: string,
+): ExecutionRecord {
+  const record = createRecord(id, {
+    agent: found.agent,
+    model: found.model,
+    thinkingLevel: found.thinkingLevel,
+    mode: found.mode,
+    task: found.task,
+    slug: found.slug,
+    startedAt: found.startedAt,
+    rootSessionId: found.rootSessionId,
+    parentRecordId: found.parentRecordId,
+    depth: found.depth,
+    // [v4 A-3] 跨重启恢复入口——message 路径磁盘重建无条件置 chatMode=true（现状机制，
+    // V3 方案 A 方向兑现）。改动此处必须带 S3 回归场景（跨重启 message 续聊验证）。
+    // V3 SP-5 探针定案：机制已存在，本注释即定案，不再悬置。
+    chatMode: true,
+    controller: new AbortController(),
+  });
+  record.sessionFile = found.sessionFile;
+  record.round = found.round;
+  // [review round2] 跨重启 worktree 绑定丢失防护：原 record 创建时启用了 worktree 隔离
+  //（session entry 的 worktree 标志），但 WorktreeHandle 不可序列化、重建后恒缺失。
+  // 标记 hadWorktree，冷路径续轮守卫据此拒绝续聊（防 spawn cwd 静默回落主 repo 破坏
+  // 隔离——正是 worktree 要防的并发写冲突场景）。close 不受影响（closeChatIdle 走
+  // doFinalizeRecord，泄漏的 worktree 由 reaper 兜底回收）。
+  record.hadWorktree = found.worktree === true;
+  // [v8.5 D] 透明重生回边：独立函数不走 tryTransition 单向语义（closed 单向性对正常
+  // 执行流完整保留）；准入唯一依据 = A 档 sidecar 真实死因 ∈ 可重连集。死亡语义位由
+  // resurrectClosed 清除；register 后立刻上报 transition entry，live/reload 视图同步
+  // 翻回 running（等价性由 applyEntry reducer 保证，对齐 SP-2 重建即报告先例）。
+  const wasClosed = found.status !== "running";
+  if (wasClosed) {
+    // [review MF-8] 磁盘终态位同步翻转：record-store buildRecord 分支 2（.finalized
+    // 存在 → closed）优先级高于 .alive 活态分支 3，重生若不删 sidecar，任何磁盘扫描
+    // （异进程 / reload / session-reader）都会把本进程内存里 running 的 record 报成
+    // closed/disconnected——破坏 live ≡ reload，且为跨进程二次 resurrect 开门。
+    // best-effort 对齐 BC-4 语义；.alive 刷新为当前进程（后续 resume spawn 会覆盖写）。
+    if (record.sessionFile) {
+      try {
+        fs.rmSync(`${record.sessionFile}.finalized`, { force: true });
+        writeAliveMarker(record.sessionFile, { pid: process.pid, id, startedAt: Date.now() });
+      } catch (_e) {
+        void _e; // best-effort：sidecar 翻转失败不阻断重生主流程
+      }
+    }
+    resurrectClosed(record);
+  }
+  deps.register(record);
+  if (wasClosed) {
+    deps.reportRecordTransition(record);
+  }
+  return record;
+}
+
+/** [D4-③] 冷查编排（原 Service.coldLookupForAction）：getRecordForAction 内存未命中
+ *  分支——候选定位 → 可重连守卫 → 归属/直接父校验 → 重建注册。
+ *  @returns 重建的 record；磁盘也无则 undefined
+ *  @throws ResurrectDeniedError 可重连候选被 worktree/异进程活实例守卫拦截
+ *  @throws Error parentRecordId 跨层不匹配（direct parent 错误，与外层校验同文案） */
+export function coldLookupForAction(
+  deps: ColdResurrectDeps,
+  id: string,
+  allowReconnect: boolean,
+): ExecutionRecord | undefined {
+  const found = findColdLookupCandidate(deps, id, allowReconnect);
+  if (!found) return undefined;
+  // [v8.5 D] 可重连候选的守卫先于任何状态突变与注册（细节见 assertReconnectAllowed）
+  assertReconnectAllowed(found, id);
+  // [review MF-9] 归属校验先于任何持久化副作用：coldLookup 是 getRecordForAction 的
+  // 内存未命中分支，若先 resurrect/register/report 再由调用方抛归属错误，会在磁盘/
+  // 内存留下幽灵 running record + running transition entry（跨进程双 resurrect 窗口）。
+  // rootSessionId 不匹配 → 返回 undefined，由 getRecordForAction 抛统一「not found or
+  // not owned」（不区分失败形态，防跨 session 探测）；parentRecordId 跨层不匹配 →
+  // 原样抛 direct parent 错误（与外层校验同文案，保留跨层导航指引）。
+  if (found.rootSessionId !== deps.getSessionRootId()) {
+    return undefined;
+  }
+  const baselineRecordId = deps.getBaselineRecordId();
+  if (found.parentRecordId !== baselineRecordId) {
+    throw new Error(
+      `subagent ${id} is owned by its direct parent; message it through that parent ` +
+        `(see /subagents list, parent=${found.parentRecordId ?? "(root layer)"}). [v4 A-5] cross-layer ` +
+        `ownership guard: this process's baseline=${baselineRecordId ?? "(root)"} is not the direct parent of ${id}; ` +
+        `operating here would race the owning child process's handle and double-write the session file.`,
+    );
+  }
+  return resurrectColdRecord(deps, found, id);
+}

package/src/execution/engine/__tests__/common/capability-gate.test.ts

@@ -0,0 +1,91 @@
+// capability-gate.test.ts —— [D3-④ 预检 capabilities 化] 拦截矩阵单测。
+// 设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-④（r3 裁定：
+// EngineCapabilities +maxTurns 位 pi=true/zcode=false，不保留硬编码 shape 检查）+
+// §3.4 错误规格第 1 行 + §4 V4④⑤（正反向验收）。
+//
+// 覆盖（构建者白盒 + 使用者黑盒）：
+//   1. per-engine 拦截矩阵：pi 全放行（含 maxTurns/fork/conversation/worktree——V4⑤
+//      反向守护，pi 既有合法能力零拦截）；zcode 四参数全拦（fork/conversation/
+//      maxTurns/worktree）
+//   2. 错误族：engine_capability_unsupported + recovery 含可操作指引（换参数/换引擎）
+//   3. fork 判据（借位裁定）：session 分叉通道族任一可用即放行——pi conversation=
+//      native 放行（steer 虽 unsupported 不参与否决）；通道族全缺才拦
+
+import { describe, expect, it } from "vitest";
+
+import { assertTaskShapeSupported, type TaskShapeForGate } from "../../common/capability-gate.ts";
+import { EngineError } from "../../common/errors.ts";
+import type { EngineCapabilities } from "../../types.ts";
+import { PiEngine } from "../../engines/pi/pi-engine.ts";
+import { ZcodeEngine } from "../../engines/zcode/zcode-engine.ts";
+
+/** 真实引擎的 capabilities 面单测直取（D3 声明是判据本体——pi=true/zcode=false 扩位）。 */
+const PI_CAPS = new PiEngine({ getService: () => null }).capabilities();
+const ZCODE_CAPS = new ZcodeEngine({ engineDataDir: () => "/tmp/zcode-gate" }).capabilities();
+
+/** 会话分叉通道族可用的 zcode 形态变体（fork 判据用）。 */
+const ZCODE_CAPS_WITH_CONVERSATION: EngineCapabilities = { ...ZCODE_CAPS, conversation: "native" };
+
+function gate(
+  caps: EngineCapabilities,
+  task: TaskShapeForGate,
+  engineId = "zcode",
+): void {
+  assertTaskShapeSupported(engineId, caps, task);
+}
+
+function gateError(caps: EngineCapabilities, task: TaskShapeForGate, engineId = "zcode"): EngineError {
+  try {
+    gate(caps, task, engineId);
+  } catch (err) {
+    expect(err).toBeInstanceOf(EngineError);
+    return err as EngineError;
+  }
+  throw new Error("expected assertTaskShapeSupported to throw");
+}
+
+describe("capability-gate（D3-④ 拦截矩阵）", () => {
+  it("能力位声明：pi maxTurns=true、zcode maxTurns=false（r3 扩位裁定）", () => {
+    expect(PI_CAPS.maxTurns).toBe(true);
+    expect(ZCODE_CAPS.maxTurns).toBe(false);
+  });
+
+  it("[V4⑤ 反向] pi 引擎全参数放行：maxTurns/fork/forkFromSessionFile/conversation/worktree 零拦截", () => {
+    expect(() =>
+      gate(PI_CAPS, { maxTurns: 3, fork: true, conversation: true, worktree: true }, "pi"),
+    ).not.toThrow();
+    expect(() => gate(PI_CAPS, { forkFromSessionFile: "/tmp/sess.jsonl", worktree: { path: "/tmp/wt" } }, "pi")).not.toThrow();
+  });
+
+  it("[V4④ 正向] zcode 引擎四参数全拦：fork/conversation/maxTurns/worktree → engine_capability_unsupported", () => {
+    const cases: Array<[TaskShapeForGate, RegExp]> = [
+      [{ fork: true }, /不支持 fork/],
+      [{ forkFromSessionFile: "/tmp/sess.jsonl" }, /fork-from 同为父 session 上下文继承/],
+      [{ conversation: true }, /不支持 conversation/],
+      [{ maxTurns: 10 }, /不支持 maxTurns/],
+      [{ worktree: true }, /不支持 worktree 隔离/],
+      [{ worktree: { path: "/tmp/wt" } }, /不支持 worktree 隔离/],
+    ];
+    for (const [task, pattern] of cases) {
+      const err = gateError(ZCODE_CAPS, task);
+      expect(err.code).toBe("engine_capability_unsupported");
+      expect(err.message).toMatch(pattern);
+      expect(err.message).toContain("capabilities");
+      // 错误信息可操作（§3.4）：恢复指引指向换参数/换引擎
+      expect(err.recovery).toMatch(/engine: pi|不传|去掉/);
+    }
+  });
+
+  it("zcode 放行面：无能力参数的任务全放行；maxTurns undefined（未传）不拦", () => {
+    expect(() => gate(ZCODE_CAPS, {})).not.toThrow();
+    expect(() => gate(ZCODE_CAPS, { maxTurns: undefined, fork: false, conversation: false, worktree: false })).not.toThrow();
+  });
+
+  it("fork 判据（借位裁定）：session 分叉通道族任一可用即放行——conversation=native 的引擎 fork 放行", () => {
+    // pi 的 steer 声明 unsupported（spawn 链路未接通），fork 仍放行——通道族判定不因
+    // 单一通道缺失而误拦（上面 pi 用例已覆盖）。此处补 zcode 形态 + conversation 通道
+    // 可用的对照：fork 从拦截翻为放行。
+    expect(() => gate(ZCODE_CAPS_WITH_CONVERSATION, { fork: true })).not.toThrow();
+    expect(() => gate({ ...ZCODE_CAPS, steer: "native" }, { fork: true })).not.toThrow();
+  });
+});

package/src/execution/engine/__tests__/common/data-dir.test.ts

@@ -49,7 +49,7 @@ describe("getEngineDataDir", () => {
 
   it("缺 env → 回退宿主数据根（HostServices.dataRoot()，假宿主值）并 warn 一次", () => {
     const warnings: string[] = [];
-    const warn = (m: string): void => warnings.push(m);
+    const warn = (m: string): void => { warnings.push(m); };
     const dir1 = getEngineDataDir({}, warn);
     expect(dir1).toBe(FAKE_DATA_ROOT);
     expect(warnings.length).toBe(1);

package/src/execution/engine/__tests__/common/journal-wiring.test.ts

@@ -0,0 +1,84 @@
+// journal-wiring.test.ts —— [D3-③ journal 接线合一] host helper 单测（两域共用的
+// 唯一实现：writer 创建 + retarget + journaling onEvent + handle 回填 + close）。
+// 设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-③ + 双轨清单 #6。
+//
+// 覆盖：①占位池 key 初始路径与 retarget 后路径权威（getter 反映 retarget）；②先落盘
+// 再转发（forwardEvents）；③handle 回填写终态路径；④close 幂等不抛。
+
+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 { JOURNAL_INITIAL_POOL_KEY, wireEventJournal } from "../../common/journal-wiring.ts";
+import { resolveJournalPath } from "../../paths.ts";
+import type { AgentEvent } from "../../types.ts";
+import type { EngineHandle } from "../../types.ts";
+
+let dataRoot: string;
+const PREV_DATA_DIR = process.env["XYZ_AGENT_DATA_DIR"];
+
+beforeEach(() => {
+  dataRoot = fs.mkdtempSync(path.join(os.tmpdir(), "journal-wiring-"));
+  process.env["XYZ_AGENT_DATA_DIR"] = dataRoot;
+});
+
+afterEach(() => {
+  if (PREV_DATA_DIR === undefined) delete process.env["XYZ_AGENT_DATA_DIR"];
+  else process.env["XYZ_AGENT_DATA_DIR"] = PREV_DATA_DIR;
+  fs.rmSync(dataRoot, { recursive: true, force: true });
+});
+
+function makeHandle(): EngineHandle {
+  return { data: { v: 1, engineId: "zcode", sessionRef: {}, poolKey: "p-m1", adapterVersion: "t" } };
+}
+
+describe("wireEventJournal（D3-③ host helper 唯一实现）", () => {
+  it("初始路径用占位池 key；onPoolResolved retarget 后 path getter 反映实际池 key（路径权威 = writer）", () => {
+    const wiring = wireEventJournal({ engineId: "zcode", taskId: "sa-1" });
+    expect(JOURNAL_INITIAL_POOL_KEY).toBe("shared");
+    expect(wiring.path).toBe(resolveJournalPath(dataRoot, "zcode", "shared", "sa-1"));
+    wiring.onPoolResolved("home-p-m1");
+    expect(wiring.path).toBe(resolveJournalPath(dataRoot, "zcode", "home-p-m1", "sa-1"));
+  });
+
+  it("journaling onEvent：先落盘再转发（forwardEvents 收到同一事件）", async () => {
+    const forwarded: AgentEvent[] = [];
+    const wiring = wireEventJournal({ engineId: "zcode", taskId: "sa-2", forwardEvents: (e) => forwarded.push(e) });
+    wiring.onEvent({ type: "turn_end" });
+    wiring.onEvent({ type: "message_end", usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 } });
+    await wiring.close();
+    expect(forwarded.map((e) => e.type)).toEqual(["turn_end", "message_end"]);
+    // 落盘真实发生（close flush 后文件存在且行数吻合——先落盘语义由文件内容见证）
+    const lines = fs.readFileSync(wiring.path, "utf8").trim().split("\n");
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0]).taskId).toBe("sa-2");
+    expect(JSON.parse(lines[0]).engineId).toBe("zcode");
+  });
+
+  it("chat 域形态（无 forwardEvents）：事件只进 journal，不抛", async () => {
+    const wiring = wireEventJournal({ engineId: "zcode", taskId: "sa-3" });
+    wiring.onEvent({ type: "turn_end" });
+    await wiring.close();
+    expect(fs.existsSync(wiring.path)).toBe(true);
+  });
+
+  it("handle 回填：backfillHandle 写 retarget 后的终态路径（read ②级自描述定位符）", async () => {
+    const wiring = wireEventJournal({ engineId: "zcode", taskId: "sa-4" });
+    wiring.onPoolResolved("home-p-m1");
+    wiring.onEvent({ type: "turn_end" });
+    const handle = makeHandle();
+    wiring.backfillHandle(handle);
+    expect(handle.data.journalPath).toBe(resolveJournalPath(dataRoot, "zcode", "home-p-m1", "sa-4"));
+    await wiring.close();
+    expect(fs.existsSync(handle.data.journalPath!)).toBe(true);
+  });
+
+  it("close 幂等（重复调用不抛）；无事件任务不产生空 journal 文件", async () => {
+    const wiring = wireEventJournal({ engineId: "zcode", taskId: "sa-5" });
+    await wiring.close();
+    await expect(wiring.close()).resolves.toBeUndefined();
+    expect(fs.existsSync(wiring.path)).toBe(false);
+  });
+});

package/src/execution/engine/__tests__/common/kill-chain.test.ts

@@ -37,8 +37,8 @@ function makeFakeChild(): {
     child,
     signals,
     emitExit(code, signal) {
-      child.exitCode = code;
-      child.signalCode = signal;
+      (child as { exitCode: number | null }).exitCode = code;
+      (child as { signalCode: string | null }).signalCode = signal;
       for (const l of listeners.splice(0)) l(code, signal);
     },
   };
@@ -88,13 +88,40 @@ describe("killChain", () => {
   });
 });
 
+describe("killChain grace 参数化（D3-① 杀链合一：pi=30s / zcode=5s，现状语义逐字节保持）", () => {
+  it("pi 参数形态（graceMs=30s + unrefTimers + escalationNote）：29s 未升级，越 30s 窗口 SIGKILL", async () => {
+    const { child, signals } = makeFakeChild();
+    const p = killChain(child, {
+      graceMs: 30_000,
+      unrefTimers: true,
+      escalationNote: "child sa-x (source: spawn watchdog)",
+    });
+    expect(signals).toEqual(["SIGTERM"]); // SIGTERM 同步发出（信号序不变）
+    await vi.advanceTimersByTimeAsync(29_000);
+    expect(signals).toEqual(["SIGTERM"]); // 窗口内不升级（非贴边断言）
+    await vi.advanceTimersByTimeAsync(1_100); // 越过 30s 优雅窗口
+    expect(signals).toEqual(["SIGTERM", "SIGKILL"]); // 升级 SIGKILL（race-F4 语义）
+    await vi.advanceTimersByTimeAsync(10_000); // 有界收尸窗口
+    expect(await p).toBe("killed");
+  });
+
+  it("escalationNote 缺省（zcode 现状形态）：graceMs=5s 越窗 SIGKILL，升级路径同构", async () => {
+    const { child, signals } = makeFakeChild();
+    const p = killChain(child, { graceMs: 5_000 });
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(signals).toEqual(["SIGTERM", "SIGKILL"]);
+    await vi.advanceTimersByTimeAsync(10_000);
+    expect(await p).toBe("killed");
+  });
+});
+
 describe("synthesizeTimeoutOutcome", () => {
   it("合成 engine_timeout 终态：error 含 slug + stdout 尾部 + engine: pi 重跑建议；exitCode=null", () => {
     const outcome = synthesizeTimeoutOutcome(
-      { task: "review files", slug: "review-files" },
+      { prompt: "review files", description: "review-files" },
       "last stdout lines...",
     );
-    expect(outcome.error).toContain("engine_timeout");
+    expect(outcome.error!).toContain("engine_timeout");
     expect(outcome.error).toContain("review-files");
     expect(outcome.error).toContain("last stdout lines...");
     expect(outcome.error).toMatch(/`engine: pi`/);
@@ -105,13 +132,13 @@ describe("synthesizeTimeoutOutcome", () => {
 
   it("stdout 尾部超 2000 字截断；engineId 可指定", () => {
     const outcome = synthesizeTimeoutOutcome(
-      { task: "t", slug: "s" },
+      { prompt: "t", description: "s" },
       "y".repeat(3_000),
       "zcode",
     );
     expect(outcome.engineId).toBe("zcode");
-    expect(outcome.error).toContain("...");
-    expect(outcome.error.length).toBeLessThan(3_000);
+    expect(outcome.error!).toContain("...");
+    expect(outcome.error!.length).toBeLessThan(3_000);
   });
 });
 

package/src/execution/engine/__tests__/common/persona-router.test.ts

@@ -17,13 +17,14 @@ import type { EngineCapabilities } from "../../types.ts";
 const CAPS_FILE: EngineCapabilities = {
   schemaEnforcement: "emulated", steer: "unsupported", conversation: "unsupported",
   personaInjection: "file", eventGranularity: "coarse", sandbox: "none",
-  sessionRead: "partial", resume: "cold", interrupt: "kill-only", permissionMode: "native",
+  sessionRead: "partial", resume: "cold", interrupt: "kill-only", permissionMode: "native", maxTurns: false,
 };
 const CAPS_FLAG: EngineCapabilities = { ...CAPS_FILE, personaInjection: "flag" };
 const CAPS_PROMPT: EngineCapabilities = { ...CAPS_FILE, personaInjection: "prompt" };
 
+// [D6 合流] PersonaSpec 收拢层删除后，路由入参是 PersonaContent（结构子集：
+// appendSystemPrompt 正文 + skillPath 引用行；agentRef 已裁撤）
 const persona = {
-  agentRef: "reviewer",
   skillPath: "/skills/review.md",
   appendSystemPrompt: ["You are a careful code reviewer.", "Be terse."],
 };
@@ -34,7 +35,6 @@ describe("applyPersona 三策略路由", () => {
     expect(routing.promptSegment).toBe("");
     expect(routing.fileCandidate).toBeDefined();
     expect(routing.fileCandidate?.suggestedPath).toBe("persona.md");
-    expect(routing.fileCandidate?.content).toContain("# Agent: reviewer");
     expect(routing.fileCandidate?.content).toContain("/skills/review.md");
     expect(routing.fileCandidate?.content).toContain("You are a careful code reviewer.");
   });
@@ -51,7 +51,6 @@ describe("applyPersona 三策略路由", () => {
   it("prompt 策略：promptSegment 为带结构头的人设段（拼进最终 prompt）", () => {
     const routing = applyPersona(persona, CAPS_PROMPT);
     expect(routing.promptSegment.startsWith("## Persona")).toBe(true);
-    expect(routing.promptSegment).toContain("# Agent: reviewer");
     expect(routing.promptSegment).toContain("You are a careful code reviewer.");
   });
 
@@ -61,7 +60,7 @@ describe("applyPersona 三策略路由", () => {
     expect(applyPersona({}, CAPS_PROMPT)).toEqual({ promptSegment: "" });
   });
 
-  it("仅 appendSystemPrompt：file 通道照常落文件（agentRef/skillPath 头部行缺省）", () => {
+  it("仅 appendSystemPrompt：file 通道照常落文件（skillPath 头部行缺省）", () => {
     const routing = applyPersona({ appendSystemPrompt: ["only body"] }, CAPS_FILE);
     expect(routing.fileCandidate?.content).toBe("only body");
   });