@zhushanwen/subagent-engine-sdk 0.2.0

package/src/journal-replay.ts

@@ -0,0 +1,432 @@
+// src/journal-replay.ts
+//
+// journal → SessionView 的纯投影（引擎侧原语，自 core
+// execution/engine/common/journal-replay.ts + execution-record.ts reducer 核心 +
+// common/session-view-projection.ts 迁入 @zhushanwen/subagent-engine-sdk）。
+// 迁移处置（impl-plan §2.1 journal-replay 行）：**纯投影部分（entry → record 的
+// reducer）下沉 SDK，journal I/O 与②级降级链留 core**——
+//   - SDK 版 = eventsToSessionView（事件流 → SessionView，live/replay 共用 reducer
+//     语义）+ reducer 本体（updateFromEvent 及其私有 handler）+ Turn → ReplayedTurn
+//     投影 / usage 聚合（原 core session-view-projection.ts 同名函数逐字等价，
+//     R6 收口后本模块为唯一实现，双活副本已删）；
+//   - 留 core = replayJournal（journal 文件 I/O）+ replayJournalToSessionView（read
+//     第②级降级编排）——core 侧引用切换已完成（core 依赖 SDK 方向合法）。
+//
+// record 形态：SDK 侧 reducer 操作 ReplayRecordView（turns/turnCount/totalTokens/
+// lastError 四字段视图）——core ExecutionRecord 留 core（类型闭包表裁决），其结构
+// 满足本视图（W2 双向可赋值断言验证）。重放场景不需要 identity 字段（agent/model/
+// task 等只服务投影与持久化，reducer 不触碰），不搬 createRecord 全量 identity。
+//
+// 设计权威源：docs/architecture/subagent-engine-abstraction.md D6 + §3.3.6「重放等价性」
+// ——journal 重放与 live 通路共用同一 reducer（updateFromEvent 范式），不引入第二套
+// 解析器；conformance C5 断言重放 turns 与 live 一致。
+//
+// CJS 多 entry 内联副本的实例分裂影响 = runningToolIndex WeakMap（按 record 实例
+// 隔离）各自为政，无跨实例语义。
+
+import type {
+  AgentEvent,
+  AgentUsage,
+  AgentUsageTotal,
+  InternalToolCall,
+  ReplayedTurn,
+  SessionView,
+  ToolCall,
+  Turn,
+  EngineHandleData,
+} from "./protocol/contract-types.ts";
+
+/**
+ * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。
+ * core ExecutionRecord 满足本视图（W2 断言挂靠点）；SDK 内自持 createReplayRecord 产出。
+ */
+export interface ReplayRecordView {
+  turns: Turn[];
+  turnCount: number;
+  totalTokens: number;
+  lastError: string | undefined;
+}
+
+// ============================================================
+// usage 累积（core execution-record.ts 私有 helper 逐字等价）
+// ============================================================
+
+/** usage 单字段求和（undefined 视为 0——与旧 `(a ?? 0) + (b ?? 0)` 内联式逐字等价）。 */
+function sumUsageField(a: number | undefined, b: number | undefined): number {
+  return (a ?? 0) + (b ?? 0);
+}
+
+/** prev 为空时 next 的规范化拷贝（cost 保留原值，可能 undefined——与旧首条分支逐字等价）。 */
+function usageFromNext(next: AgentUsage): AgentUsage {
+  return {
+    input: next.input ?? 0,
+    output: next.output ?? 0,
+    cacheRead: next.cacheRead ?? 0,
+    cacheWrite: next.cacheWrite ?? 0,
+    cost: next.cost,
+  };
+}
+
+/**
+ * 累加两个 AgentUsage（field-wise）。prev 为空时返回 next 的拷贝。
+ * 供 message_end 把 usage 增量并入 turn.usageDelta。
+ */
+function addUsage(prev: AgentUsage | undefined, next: AgentUsage): AgentUsage {
+  if (prev === undefined) return usageFromNext(next);
+  return {
+    input: sumUsageField(prev.input, next.input),
+    output: sumUsageField(prev.output, next.output),
+    cacheRead: sumUsageField(prev.cacheRead, next.cacheRead),
+    cacheWrite: sumUsageField(prev.cacheWrite, next.cacheWrite),
+    cost: sumUsageField(prev.cost, next.cost),
+  };
+}
+
+// ============================================================
+// 创建（重放场景的 record 构造）
+// ============================================================
+
+/** 创建一个空 turn（text/thinking 空，无 toolCalls，未闭合）。 */
+function emptyTurn(): Turn {
+  return { text: "", thinking: "", toolCalls: [], usageDelta: undefined, closed: false };
+}
+
+/** 重放场景的 record 构造（对齐 core eventsToSessionView 内 createRecord 后的 reducer 视图）。 */
+export function createReplayRecord(): ReplayRecordView {
+  return {
+    // turns[] 初始化为 [空 turn]——第一个 turn 从创建即存在，
+    // updateFromEvent 直接往 turns[last] 累积，无需「无 turn」分支判断。
+    turns: [emptyTurn()],
+    turnCount: 0,
+    totalTokens: 0,
+    lastError: undefined,
+  };
+}
+
+// ============================================================
+// 事件更新（唯一更新点；core updateFromEvent 私有结构逐字等价）
+// ============================================================
+
+/**
+ * 取当前正在进行（未 closed）的 turn；若全部 closed 则开新 turn。
+ * 保证调用后返回的 turn 一定 closed===false，可安全累积内容。
+ */
+function currentTurn(record: ReplayRecordView): Turn {
+  const last = record.turns[record.turns.length - 1];
+  if (last !== undefined && !last.closed) return last;
+  const fresh = emptyTurn();
+  record.turns.push(fresh);
+  return fresh;
+}
+
+/**
+ * 在 record.turns[] 范围内倒序找最后一个同名且仍 running 的 toolCall。
+ *
+ * 扫描所有 turn（非仅当前 turn）——SDK 在 turn_end 后仍可能补发滞后的 tool_end，
+ * 仅扫当前 turn 会漏配对、误 push 幽灵 ToolCall。跨 turn 扫描兜底滞后事件。
+ *
+ * 返回 [turn, index]；未找到返回 undefined。
+ */
+function findRunningToolCall(
+  record: ReplayRecordView,
+  toolName: string,
+): readonly [Turn, number] | undefined {
+  for (let t = record.turns.length - 1; t >= 0; t--) {
+    const turn = record.turns[t];
+    if (turn === undefined) continue;
+    for (let i = turn.toolCalls.length - 1; i >= 0; i--) {
+      const tc = turn.toolCalls[i];
+      if (tc?._status === "running" && tc.toolName === toolName) {
+        return [turn, i] as const;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * [perf] running toolCall 倒序索引：tool_start push 位置入索引，tool_end 弹尾定位
+ *（尾部 = 最后 push 的同名项，与 findRunningToolCall 倒序全扫的语义等价），把每次
+ * tool_end 的 O(所有 turns × toolCalls) 扫描降为 O(1)。WeakMap 按 record 实例隔离
+ *（createRecord 新实例从空索引开始，不影响旧实例）。
+ * 索引 miss（重建 record 的历史 running toolCall / 外部注入工具无 tool_start）
+ * 回退 findRunningToolCall 全扫兜底——正确性不依赖索引完整性。
+ */
+const runningToolIndex = new WeakMap<ReplayRecordView, Map<string, Array<{ turn: Turn; idx: number }>>>();
+
+function indexToolStart(record: ReplayRecordView, turn: Turn, toolName: string): void {
+  let byName = runningToolIndex.get(record);
+  if (byName === undefined) {
+    byName = new Map();
+    runningToolIndex.set(record, byName);
+  }
+  const arr = byName.get(toolName);
+  if (arr === undefined) {
+    byName.set(toolName, [{ turn, idx: turn.toolCalls.length - 1 }]);
+  } else {
+    arr.push({ turn, idx: turn.toolCalls.length - 1 });
+  }
+}
+
+// ── 各事件处理器（updateFromEvent 按 case 分发，每个处理器单一职责）──
+
+/** text_delta：流式累积进当前 turn 的 text（完整内容，非切片）。 */
+function applyTextDelta(
+  record: ReplayRecordView,
+  event: Extract<AgentEvent, { type: "text_delta" }>,
+): void {
+  currentTurn(record).text += event.delta;
+}
+
+/** thinking_delta：流式累积进当前 turn 的 thinking（完整内容）。 */
+function applyThinkingDelta(
+  record: ReplayRecordView,
+  event: Extract<AgentEvent, { type: "thinking_delta" }>,
+): void {
+  currentTurn(record).thinking += event.delta;
+}
+
+/** tool_start：push 一个 running 的 InternalToolCall（带 startedTs）+ 弹尾索引入册。 */
+function applyToolStart(
+  record: ReplayRecordView,
+  event: Extract<AgentEvent, { type: "tool_start" }>,
+): void {
+  const tc: InternalToolCall = {
+    toolName: event.toolName,
+    args: event.args,
+    result: undefined,
+    isError: false,
+    _status: "running",
+    startedTs: Date.now(),
+  };
+  const turn = currentTurn(record);
+  turn.toolCalls.push(tc);
+  indexToolStart(record, turn, event.toolName);
+}
+
+/**
+ * tool_end 定位：索引弹尾 O(1) 命中 running 同名 toolCall；索引 miss（无记录 / 槽位
+ * 已非 running）回退 findRunningToolCall 跨 turn 倒序全扫兜底。
+ * 返回 [turn, index]；两路都 miss 返回 undefined。
+ */
+function matchRunningToolCall(
+  record: ReplayRecordView,
+  toolName: string,
+): readonly [Turn, number] | undefined {
+  const byName = runningToolIndex.get(record);
+  const arr = byName?.get(toolName);
+  if (arr !== undefined && arr.length > 0) {
+    const item = arr[arr.length - 1];
+    arr.pop();
+    const tc = item.turn.toolCalls[item.idx];
+    if (tc !== undefined && tc._status === "running") {
+      return [item.turn, item.idx] as const;
+    }
+  }
+  // 兜底：重建 record 的历史 running toolCall（索引未覆盖）、索引项被外部路径
+  // 置非 running 等场景——保持与旧实现一致的跨 turn 倒序全扫。
+  return findRunningToolCall(record, toolName);
+}
+
+/**
+ * tool_end：命中则回填 result/isError/_status；未命中（SDK 发了 tool_end 但无对应
+ * tool_start，如外部注入的工具）直接 push 一个已完成的 InternalToolCall，避免数据丢失。
+ */
+function applyToolEnd(
+  record: ReplayRecordView,
+  event: Extract<AgentEvent, { type: "tool_end" }>,
+): void {
+  const matched = matchRunningToolCall(record, event.toolName);
+  if (matched !== undefined) {
+    const [turn, i] = matched;
+    const tc = turn.toolCalls[i]!;
+    tc.args = event.args ?? tc.args;
+    tc.result = event.result;
+    tc.isError = event.isError ?? false;
+    tc._status = event.isError ? "failed" : "done";
+    return;
+  }
+  currentTurn(record).toolCalls.push({
+    toolName: event.toolName,
+    args: event.args,
+    result: event.result,
+    isError: event.isError ?? false,
+    _status: event.isError ? "failed" : "done",
+    startedTs: Date.now(),
+  });
+}
+
+/**
+ * turn_end：闭合当前 turn，记 closedTs（真实墙钟），turnCount++，清 lastError。
+ * 正常闭合清 lastError：瞬态 error 恢复后不应误判 success=false
+ * （若 turn_end 后 message_end 报 error，会在 message_end 处理器重新写回）。
+ */
+function applyTurnEnd(record: ReplayRecordView): void {
+  const turn = currentTurn(record);
+  turn.closed = true;
+  turn.closedTs = Date.now();
+  record.turnCount += 1;
+  record.lastError = undefined;
+}
+
+/**
+ * message_end：usage 增量存进末 turn.usageDelta（直接写末 turn，不开新 turn）；
+ * totalTokens 累加；error（stopReason=error）记进 lastError。
+ *
+ * usageDelta 按 message_end **累加**（非覆盖）——同一 turn 内若多次 message_end
+ * 到达（或 turn_end 后的滞后 message_end 落到 currentTurn 开的新 turn），
+ * 累加保证不丢 usage。getTotalUsage 扁平求和所有 turn，归属 turn 的精确性
+ * 不影响最终 total（无消费方读单 turn usage）。
+ */
+function applyMessageEnd(
+  record: ReplayRecordView,
+  event: Extract<AgentEvent, { type: "message_end" }>,
+): void {
+  if (event.usage) {
+    const turn = currentTurn(record);
+    turn.usageDelta = addUsage(turn.usageDelta, event.usage);
+    // totalTokens 累加四项之和（保留旧语义，投影直接读）
+    record.totalTokens +=
+      (event.usage.input ?? 0) + (event.usage.output ?? 0) +
+      (event.usage.cacheRead ?? 0) + (event.usage.cacheWrite ?? 0);
+  }
+  if (event.error) {
+    record.lastError = event.error;
+  }
+}
+
+/** error：存 record.lastError（getEventLog 派生 error 条目用）。 */
+function applyErrorEvent(
+  record: ReplayRecordView,
+  event: Extract<AgentEvent, { type: "error" }>,
+): void {
+  record.lastError = event.message;
+}
+
+/**
+ * 从 AgentEvent 更新 record。所有数据收口进 record.turns[]。
+ *   - text/thinking：流式累积进 currentTurn()（完整内容，非切片）
+ *   - tool_start/end：push 进 currentTurn().toolCalls（含完整 result）
+ *     tool_end 跨 turn 扫描找 running 同名 toolCall（兜底滞后事件）
+ *   - turn_end：闭合当前 turn，记 closedTs（真实墙钟，供 getEventLog）；
+ *     正常闭合清 lastError（瞬态 error 恢复后不应误判 success=false）
+ *   - message_end：usage 增量存进末 turn.usageDelta（直接写末 turn，不开新 turn）；
+ *     totalTokens 累加
+ *   - error：存 record.lastError（getEventLog 派生 error 条目用）
+ *
+ * 唯一写点——replay 与 live 共用（重放等价性的实现体）。
+ *
+ * 穷尽性：switch 覆盖 AgentEvent 全部 variant；default 的 `never` 断言保证
+ * 新增 variant 时编译期报错（而非静默 no-op）。
+ */
+export function updateFromEvent(record: ReplayRecordView, event: AgentEvent): void {
+  switch (event.type) {
+    // ── text / thinking：流式累积进当前 turn ──
+    case "text_delta":
+      return applyTextDelta(record, event);
+    case "thinking_delta":
+      return applyThinkingDelta(record, event);
+
+    // ── tool_start/end：push 进 currentTurn().toolCalls（含完整 result）──
+    case "tool_start":
+      return applyToolStart(record, event);
+    case "tool_end":
+      return applyToolEnd(record, event);
+
+    // ── turn_end：闭合当前 turn ──
+    case "turn_end":
+      return applyTurnEnd(record);
+
+    // ── message_end：usage 增量累加 + totalTokens 累加 ──
+    case "message_end":
+      return applyMessageEnd(record, event);
+
+    // ── error：存 record.lastError ──
+    case "error":
+      return applyErrorEvent(record, event);
+
+    // ── compaction：不产生数据（不变）──
+    case "compaction":
+      return;
+
+    default: {
+      // 穷尽性检查：新增 AgentEvent variant 时编译期报错
+      const _exhaustive: never = event;
+      return _exhaustive;
+    }
+  }
+}
+
+// ============================================================
+// Turn → ReplayedTurn 投影 + usage 聚合
+// （原 core session-view-projection.ts 逐字等价，R6 收口后本模块为唯一实现：
+//   投影语义唯一——strip 内部态 + closed 恒 true + usageDelta 聚合，实现也唯一）
+// ============================================================
+
+/** InternalToolCall → ToolCall（导出纯净形状，不泄漏 running/done/failed 内部状态机）。 */
+function toExportedToolCall(tc: InternalToolCall): ToolCall {
+  return {
+    toolName: tc.toolName,
+    ...(tc.args !== undefined ? { args: tc.args } : {}),
+    ...(tc.result !== undefined ? { result: tc.result } : {}),
+    ...(tc.isError !== undefined ? { isError: tc.isError } : {}),
+  };
+}
+
+/** Turn → ReplayedTurn：剥离内部态（closed 恒 true——重放物无进行时语义，§3.3.6）。 */
+export function toReplayedTurn(turn: Turn): ReplayedTurn {
+  return {
+    text: turn.text,
+    thinking: turn.thinking,
+    toolCalls: turn.toolCalls.map(toExportedToolCall),
+    closed: true,
+  };
+}
+
+/** 各 turn usageDelta 聚合为 AgentUsageTotal（无任何 usage 数据时 undefined）。 */
+export function aggregateUsage(turns: readonly Turn[]): AgentUsageTotal | undefined {
+  let acc: AgentUsageTotal | undefined;
+  for (const turn of turns) {
+    const d = turn.usageDelta;
+    if (!d) continue;
+    if (!acc) acc = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, total: 0 };
+    acc.input += d.input;
+    acc.output += d.output;
+    acc.cacheRead += d.cacheRead;
+    acc.cacheWrite += d.cacheWrite;
+    acc.cost += d.cost ?? 0;
+  }
+  if (acc) acc.total = acc.input + acc.output + acc.cacheRead + acc.cacheWrite;
+  return acc;
+}
+
+// ============================================================
+// 事件流 → SessionView（纯投影出口）
+// ============================================================
+
+/**
+ * 事件流 → SessionView（live reducer 累积 turns——重放等价性的实现体）。
+ * journal I/O（replayJournal）不在此层——read 第②级降级编排（core 版
+ * replayJournalToSessionView）留 core，引擎侧按需自读 journal 后调本函数。
+ */
+export function eventsToSessionView(
+  events: readonly AgentEvent[],
+  engineId: string,
+  sessionId?: string,
+): SessionView {
+  const record = createReplayRecord();
+  for (const ev of events) updateFromEvent(record, ev);
+  return {
+    engineId,
+    ...(sessionId !== undefined ? { sessionId } : {}),
+    turns: record.turns.map(toReplayedTurn),
+    usage: aggregateUsage(record.turns),
+    source: "journal",
+  };
+}
+
+/** handle.sessionRef 的 sessionId 提取（引擎自定义键，运行时 guard）。 */
+export function sessionIdFromHandle(handle: EngineHandleData): string | undefined {
+  const v = handle.sessionRef["sessionId"];
+  return typeof v === "string" ? v : undefined;
+}

package/src/kill-chain.ts

@@ -0,0 +1,265 @@
+// src/kill-chain.ts
+//
+// 超时杀链与 abort 两级中断（引擎侧原语，自 core execution/engine/common/kill-chain.ts
+// 迁入 @zhushanwen/subagent-engine-sdk，实现体逐字等价）。迁移处置（impl-plan §2.1
+// kill-chain 行，逐项落地）：
+//   - 契约类型随 SDK 下沉：AgentCallOpts（引擎面子集）/ AgentOutcome 改自
+//     src/protocol/contract-types.ts（结构等价，零 core import）；
+//   - DEFAULT_ENGINE_ID 改参数注入：synthesizeTimeoutOutcome 的 engineId 必填，
+//     不再携带 core registry 缺省值（调用方显式传自己的引擎 id）；
+//   - logger 走 SDK facade（src/logger.ts）；
+//   - engineTimeoutDetail / STDOUT_TAIL_ECHO_CHARS 自持（src/protocol/error-codes.ts，
+//     文案与 core errors.ts 逐字等价）；toErrorMessage 改用 SDK 单源
+//     src/error-message.ts（round1-reuse R11 收编原内联副本）。
+//
+// 设计权威源：docs/architecture/subagent-engine-abstraction.md D1（abort 分级：引擎原生
+// 中断 → 公共杀链兜底；CLI-only 引擎直接杀链，杀死后宿主合成终态）+ §3.3.3
+// engine_timeout / engine_run_failed 行 + 附录 A「CLI 超时」行。
+
+import { getLogger } from "./logger.ts";
+import { toErrorMessage } from "./error-message.ts";
+import { engineTimeoutDetail, STDOUT_TAIL_ECHO_CHARS } from "./protocol/error-codes.ts";
+import type { AgentCallOpts, AgentOutcome } from "./protocol/contract-types.ts";
+
+const logger = getLogger("subagents");
+
+/** STDOUT_TAIL_ECHO_CHARS re-export（core 版同款导出面，调用方免跨模块 import）。 */
+export { STDOUT_TAIL_ECHO_CHARS };
+
+// ============================================================
+// 杀链（SIGTERM → grace → SIGKILL）
+// ============================================================
+
+/**
+ * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。
+ * 用结构接口而非 ChildProcess 类型：测试可注入 fake（ChildProcess 全字段构造过重），
+ * 且未来 driver host 的常驻进程句柄只要满足此形状即可复用杀链。
+ */
+export interface KillableChild {
+  /** 非 null = 进程已退出（自然退出码）。 */
+  readonly exitCode: number | null;
+  /** 非 null = 进程被信号杀死。exitCode/signalCode 任一非 null 即已退出。 */
+  readonly signalCode: string | null;
+  /** 发信号。返回 false = 进程已不存在（kill no-op）。 */
+  kill(signal?: NodeJS.Signals | number): boolean;
+  once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+}
+
+// 毫秒→秒换算（SIGKILL 升级 warn 日志的秒数显示）。文件内私有定义：工程内 MS_PER_SECOND
+// 惯例是各使用文件私有常量（execution-record / lifecycle-manager / session-file-gc /
+// session-runner 四处先例），无共享导出源可 import，保持同惯例不另立导出点。
+const MS_PER_SECOND = 1_000;
+
+/** SIGTERM 优雅窗口默认值（ms）。实测校准点：设计 §5 待验证检查点⑤（zcode 对 SIGTERM 的响应时序）。 */
+export const DEFAULT_KILL_GRACE_MS = 5_000;
+
+/** SIGKILL 发出后的收尸等待上限（ms）——SIGKILL 后进程必死（D 状态罕见），有界等待防挂死。 */
+const SIGKILL_REAP_TIMEOUT_MS = 10_000;
+
+/**
+ * 宿主超时 abort 的 signal.reason 标记（对齐点④）。mergeTimeoutSignal（SAR 侧超时
+ * 合并链）产出；引擎 abort 合成终态时判别「超时 vs 用户 cancel」——超时统一走
+ * synthesizeTimeoutOutcome（engine_timeout），cancel 维持中止标记（engine_run_failed）。
+ */
+export const HOST_TIMEOUT_ABORT_REASON = "agent-call-timeout";
+
+/** killChain 的参数形状。 */
+export interface KillChainOptions {
+  /**
+   * SIGTERM 优雅窗口（ms）。grace 窗口按引擎参数化（D3-① 杀链合一）：pi 传 30s
+   * （[race-F4] 现状值）、zcode 传 5s（ZCODE_KILL_GRACE_MS）——两引擎现状逐字节保持。
+   */
+  graceMs: number;
+  /**
+   * [D3-①] 内部 timer unref。pi 路径现状 = 升级 timer unref（不阻止主进程退出，dispose
+   * killAll 兜底）；zcode 现状 = ref'd（timer 挂起时进程等待收尸）——各引擎按现状传。
+   */
+  unrefTimers?: boolean;
+  /**
+   * SIGKILL 升级时的 warn 留痕载体（如 `child sa-xxx (source: spawn watchdog)`）。
+   * 不传则升级静默（zcode 现状）——pi 侧现状有 warn，由调用方组装完整语境。
+   */
+  escalationNote?: string;
+}
+
+/**
+ * 杀链：SIGTERM → 等待 graceMs → 仍存活则 SIGKILL。
+ *
+ * @returns 'terminated' = SIGTERM 优雅退出（或进程已自行退出）；'killed' = 走了 SIGKILL。
+ */
+export async function killChain(
+  child: KillableChild,
+  opts: KillChainOptions,
+): Promise<"terminated" | "killed"> {
+  // 已退出（自然/已被杀）→ 无需发信号，按优雅终止口径返回
+  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
+
+  const exited = waitForExit(child);
+  safeKill(child, "SIGTERM");
+
+  const graceful = await raceTimeout(exited, opts.graceMs, opts.unrefTimers === true);
+  if (graceful === "settled") return "terminated";
+  // grace 超时后进程可能恰好在检查前一刻退出——复核退出态，避免误杀已死进程
+  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
+
+  if (opts.escalationNote !== undefined) {
+    logger.warn(
+      `[kill-chain] ${opts.escalationNote} still alive ${opts.graceMs / MS_PER_SECOND}s after SIGTERM, escalating to SIGKILL`,
+    );
+  }
+  safeKill(child, "SIGKILL");
+  // 有界收尸：无论等到与否都返回 'killed'（信号已发出，返回值表达「走了 SIGKILL」）
+  await raceTimeout(exited, SIGKILL_REAP_TIMEOUT_MS, opts.unrefTimers === true);
+  return "killed";
+}
+
+/**
+ * 发信号兜底包裹：进程恰在退出态检查与 kill 之间自退时，ChildProcess.kill 可能抛
+ * （zsub 实测经验）——幂等吞掉并 debug 留痕，不阻断杀链语义（对已退进程信号本就是
+ * no-op）。收口自 zcode launcher 的内联实现（对齐点②：单一权威）。
+ */
+function safeKill(child: KillableChild, signal: NodeJS.Signals): void {
+  try {
+    child.kill(signal);
+  } catch (err) {
+    logger.debug(
+      `[kill-chain] ${signal} on exited process: ${toErrorMessage(err)}`,
+    );
+  }
+}
+
+// ============================================================
+// 超时终态合成
+// ============================================================
+
+/**
+ * 合成 engine_timeout 终态（宿主超时杀链走完后的 AgentOutcome）。
+ * 含 stdout 尾部 2000 字 + 恢复指引（§3.3.3 第 6 行）；exitCode: null = 被信号杀死
+ * （AgentOutcome 的杀链判据，§3.3.5）。
+ *
+ * engineId 参数注入（原 core 版缺省 DEFAULT_ENGINE_ID——SDK 不感知宿主路由缺省值，
+ * 调用方必须显式传实际引擎 id）。
+ */
+export function synthesizeTimeoutOutcome(
+  task: AgentCallOpts,
+  stdoutTail: string,
+  engineId: string,
+): AgentOutcome {
+  return {
+    content: "",
+    // slug 进错误信息：单看 outcome（record 之外）也能定位是哪个任务超时
+    error: `engine_timeout: [slug=${task.description ?? "unknown"}] ${engineTimeoutDetail(stdoutTail)}`,
+    // 被信号杀死：退出码语义为 null（§3.3.5 AgentOutcome.exitCode 注释）
+    exitCode: null,
+    engineId,
+  };
+}
+
+// ============================================================
+// abort 两级编排
+// ============================================================
+
+/** 原生中断后的宽限窗口默认值（ms）：中断指令送达 → 引擎自行收尾的等待上限。 */
+export const DEFAULT_NATIVE_INTERRUPT_GRACE_MS = 3_000;
+
+/**
+ * abort 两级编排 helper（D1 abort 分级的公共实现）：
+ * signal abort 时 ①先调引擎原生中断（tryNativeInterrupt，若有）并给宽限窗口，
+ * 窗口内未停（或无原生中断——CLI-only 引擎）则 ②走杀链兜底。
+ *
+ * 进程自然退出时以 'terminated' settle（挂在 exit 事件上，杀链对已退进程是 no-op），
+ * 调用方可安全 await；signal 永不 abort 且进程已退时也会 settle，不悬挂。
+ */
+export function abortWithFallback(
+  child: KillableChild,
+  signal: AbortSignal,
+  tryNativeInterrupt?: () => Promise<void>,
+  opts?: { graceMs?: number; nativeGraceMs?: number },
+): Promise<"terminated" | "killed"> {
+  const graceMs = opts?.graceMs ?? DEFAULT_KILL_GRACE_MS;
+  const nativeGraceMs = opts?.nativeGraceMs ?? DEFAULT_NATIVE_INTERRUPT_GRACE_MS;
+
+  return new Promise<"terminated" | "killed">((resolve) => {
+    let settled = false;
+    // 三个 handler 互相引用（finish 移除 onAbort / onAbort 触发 runChain / runChain
+    // 兜底 finish），用函数声明 + 提升消解声明环，避免 use-before-define。
+    function finish(result: "terminated" | "killed"): void {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", onAbort);
+      resolve(result);
+    }
+
+    function onExit(): void {
+      finish("terminated");
+    }
+
+    function runChain(): void {
+      void (async () => {
+        if (tryNativeInterrupt) {
+          try {
+            await tryNativeInterrupt();
+          } catch (err) {
+            // 原生中断失败（协议错/管道断）→ 直接落杀链，中断失败不阻断兜底。
+            // debug 级留诊断线索：这不是错误终态，只是该引擎优雅中断不可用
+            logger.debug(
+              `[kill-chain] native interrupt failed, falling back to kill chain: ${
+                toErrorMessage(err)
+              }`,
+            );
+          }
+          const stopped = await raceTimeout(waitForExit(child), nativeGraceMs);
+          if (stopped === "settled" || settled) return; // 原生中断生效，进程已停
+        }
+        finish(await killChain(child, { graceMs }));
+      })();
+    }
+
+    function onAbort(): void {
+      runChain();
+    }
+
+    // 进程自然退出（含原生中断生效）→ 优雅终止口径。
+    // once listener 不显式移除：触发时 finish 已幂等，单 child 单 listener 无堆积。
+    child.once("exit", onExit);
+    if (child.exitCode !== null || child.signalCode !== null) {
+      finish("terminated");
+      return;
+    }
+
+    if (signal.aborted) runChain();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// ── 内部工具 ────────────────────────────────────────────────────
+
+/** 等 child 退出（已退出立即 settle；否则挂一次性 exit listener）。 */
+function waitForExit(child: KillableChild): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve();
+      return;
+    }
+    child.once("exit", () => resolve());
+  });
+}
+
+/** promise vs 超时：超时先到返回 'timeout'（promise 继续但被放弃等待）。unref 见 KillChainOptions。 */
+function raceTimeout(p: Promise<void>, ms: number, unref = false): Promise<"settled" | "timeout"> {
+  return new Promise<"settled" | "timeout">((resolve) => {
+    const timer = setTimeout(() => resolve("timeout"), ms);
+    if (unref) timer.unref();
+    p.then(
+      () => {
+        clearTimeout(timer);
+        resolve("settled");
+      },
+      () => {
+        // 被 await 的 exit promise 不会 reject；防御分支保持语义完整（超时口径胜出前出错按 settled 处理）
+        clearTimeout(timer);
+        resolve("settled");
+      },
+    );
+  });
+}