@zhushanwen/subagent-engine-sdk 0.5.0 → 0.5.1

package/src/protocol/schema.ts

@@ -1,185 +0,0 @@
-// src/protocol/schema.ts
-//
-// 帧校验 JSON Schema（draft-07）。设计权威源：impl-plan §2.1 W1 职责「JSON Schema
-// （帧校验用）」+ 设计 §3.10 不变量 5「凭据不过协议：协议里不出现 apiKey / token
-// 字段（schema 层禁止 + 测试断言）」。
-//
-// schema 层禁止凭据的实现口径：所有对象帧 additionalProperties:false + 属性白名单，
-// 凭据类键名（apiKey/token/credential 等）不在任何白名单内；测试侧另断言白名单全集
-// 无凭据键（src/__tests__/protocol-frames.test.ts）。params/result 的深载荷结构由
-// TS 类型承载（protocol/methods.ts / reverse-channels.ts / contract-types.ts），
-// 帧级 schema 只定形状骨架（id/method/params/result/error 的存在性与类型）——
-// 帧校验的目的是行解析器快速拒格式坏帧，不做深校验（深校验成本高于收益，坏载荷
-// 由消费方结构化报错）。
-
-import { REVERSE_CHANNELS } from "./reverse-channels.ts";
-import { PROTOCOL_METHODS } from "./methods.ts";
-
-/** 任意 JSON 值（draft-07 空约束）。 */
-const ANY_JSON = {} as const;
-
-/** 协议错误对象 schema。 */
-export const protocolErrorSchema = {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  title: "EngineProtocolError",
-  type: "object",
-  additionalProperties: false,
-  required: ["code", "message", "recovery"],
-  properties: {
-    code: { type: "string", pattern: "^engine_" },
-    message: { type: "string" },
-    recovery: { type: "string" },
-    data: { type: "object" },
-  },
-} as const;
-
-/** ① 请求帧（core → 引擎）。 */
-export const requestFrameSchema = {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  title: "EngineProtocolRequestFrame",
-  type: "object",
-  additionalProperties: false,
-  required: ["id", "method", "params"],
-  properties: {
-    id: { type: "number" },
-    method: { type: "string", enum: [...PROTOCOL_METHODS] },
-    params: ANY_JSON,
-  },
-} as const;
-
-/** ② 应答帧（引擎 → core；result 与 error 互斥）。 */
-export const successResponseFrameSchema = {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  title: "EngineProtocolSuccessResponseFrame",
-  type: "object",
-  additionalProperties: false,
-  required: ["id", "result"],
-  properties: {
-    id: { type: ["number", "string"] },
-    result: ANY_JSON,
-  },
-} as const;
-
-export const errorResponseFrameSchema = {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  title: "EngineProtocolErrorResponseFrame",
-  type: "object",
-  additionalProperties: false,
-  required: ["id", "error"],
-  properties: {
-    id: { type: ["number", "string"] },
-    error: protocolErrorSchema,
-  },
-} as const;
-
-/** ③ 通知帧（引擎 → core，无 id；method 恒 "event"）。 */
-export const notificationFrameSchema = {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  title: "EngineProtocolNotificationFrame",
-  type: "object",
-  additionalProperties: false,
-  required: ["method", "params"],
-  properties: {
-    method: { type: "string", const: "event" },
-    params: {
-      type: "object",
-      additionalProperties: false,
-      required: ["runId", "seq", "event"],
-      properties: {
-        runId: { type: "string" },
-        seq: { type: "number" },
-        event: {
-          type: "object",
-          required: ["type"],
-          properties: {
-            type: {
-              type: "string",
-              enum: [
-                "tool_start",
-                "tool_end",
-                "text_delta",
-                "thinking_delta",
-                "turn_end",
-                "message_end",
-                "compaction",
-                "activity",
-                "error",
-              ],
-            },
-          },
-        },
-      },
-    },
-  },
-} as const;
-
-/** ④ 反向请求帧（引擎 → core，必须应答；method 恒 host/*）。 */
-export const reverseRequestFrameSchema = {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  title: "EngineProtocolReverseRequestFrame",
-  type: "object",
-  additionalProperties: false,
-  required: ["id", "method", "params"],
-  properties: {
-    id: { type: "string" },
-    method: { type: "string", enum: [...REVERSE_CHANNELS] },
-    params: ANY_JSON,
-  },
-} as const;
-
-/** 帧型 → schema 索引（校验入口按帧型取用）。 */
-export const ENGINE_PROTOCOL_SCHEMAS = {
-  request: requestFrameSchema,
-  successResponse: successResponseFrameSchema,
-  errorResponse: errorResponseFrameSchema,
-  notification: notificationFrameSchema,
-  reverseRequest: reverseRequestFrameSchema,
-  protocolError: protocolErrorSchema,
-} as const;
-
-/**
- * 协议面凭据禁区键名（不变量 5 的测试断言依据）：帧 schema 与深载荷 TS 类型面
- * 不得出现。词表覆盖常见拼写（子串匹配，非精确枚举）。
- */
-export const FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS = [
-  "apikey",
-  "api_key",
-  "token",
-  "credential",
-  "password",
-  "secret",
-] as const;
-
-// ============================================================
-// [H1] run 会话形态参数载荷 schema（resume 单键校验权威）
-// ============================================================
-
-/**
- * run.params 的会话形态参数载荷 schema（draft-07 深载荷片段）。设计权威源：
- * docs/architecture/subagent-chat-run-unification.md §3.3 D3 + §5 U1/U6 行。
- *
- * [H1 U6 已切换] 键切换单批完成后本 schema 面向唯一键 `resume`（RunResumeParams：
- * recordId + 可选 ResumeAnchor），形状不变。帧级 schema（requestFrameSchema.params）
- * 刻意不做深校验（见本文件头注释），本片段供消费方（引擎读端结构化报错 / 测试正负
- * 样本）按需深校验。
- */
-export const runSessionParamsSchema = {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  title: "EngineRunSessionParams",
-  type: "object",
-  additionalProperties: false,
-  required: ["recordId"],
-  properties: {
-    recordId: { type: "string" },
-    resume: {
-      type: "object",
-      additionalProperties: false,
-      required: ["sessionRef"],
-      properties: {
-        // ResumeAnchor.sessionRef = Record<string, string>（引擎定位键值对）
-        sessionRef: { type: "object", additionalProperties: { type: "string" } },
-        journalPath: { type: "string" },
-      },
-    },
-  },
-} as const;

package/src/relay-env.ts

@@ -1,60 +0,0 @@
-// src/relay-env.ts
-//
-// subagent relay 通道 env 名与协议常量 SSOT（docs/architecture/subagent-realtime-channel.md
-// §5.1/§5.2/§3.1）。跨进程契约单源：core（./relay-env 子入口）与 pi 引擎 CLI
-// 的副本（round1-reuse R9）自本模块 re-export 收编——边界合法（引擎 CLI → SDK、
-// core → SDK 均正向）。runtime 侧消费经 core 子入口间接取本单源。
-//
-// 为什么独立成模块：三方消费同一份常量——extension 侧（pi-invocation 激活判定 /
-// buildChildEnv 归属写入）、runtime 侧（env 注入与镜像校验）、代理脚本 relay.mjs
-// （零依赖脚本不能 import workspace 包，只能内嵌镜像，镜像一致性由 conformance
-// relay 变体断言锁定）。禁各处手写字符串。
-//
-// env 语义：SOCKET/NODE/SCRIPT 三者同时非空 = relay 激活（全有或全无，无中间态）；
-// SESSION_ID/RECORD_ID 是 tee 帧归属键（缺失由代理握手前自检拒绝，退出码 13）。
-
-export const RELAY_ENV_SOCKET = "XYZ_SUBAGENT_RELAY_SOCKET";
-export const RELAY_ENV_NODE = "XYZ_SUBAGENT_RELAY_NODE";
-export const RELAY_ENV_SCRIPT = "XYZ_SUBAGENT_RELAY_SCRIPT";
-export const RELAY_ENV_SESSION_ID = "XYZ_SUBAGENT_RELAY_SESSION_ID";
-export const RELAY_ENV_RECORD_ID = "XYZ_SUBAGENT_RELAY_RECORD_ID";
-
-/** relay 协议版本（握手帧 v 字段；runtime 与代理同包分发，不匹配=安装损坏）。 */
-export const RELAY_PROTOCOL_VERSION = 1;
-
-/** 代理专用退出码（extension/引擎侧表现为「子进程非零退出」→ engine_run_failed 语义）。 */
-export const RELAY_EXIT_CODES = {
-  /** 握手被拒：协议版本不匹配（安装损坏，重装应用）。 */
-  VERSION_MISMATCH: 10,
-  /** relay socket 不可达（runtime 未运行或已重启）。 */
-  SOCKET_UNREACHABLE: 11,
-  /** socket 中途断开（runtime 崩溃等）——代理生命线断即退。 */
-  SOCKET_CLOSED: 12,
-  /** 归属 env（SESSION_ID/RECORD_ID）缺失——防无归属帧污染广播。 */
-  MISSING_IDENTITY: 13,
-} as const;
-
-/** 激活判定：三 env 同时非空才走 relay，任一缺失回落直连 spawn 真实引擎（TUI/独立引擎零回归）。 */
-export function isRelayActive(env: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean {
-  return Boolean(env[RELAY_ENV_SOCKET] && env[RELAY_ENV_NODE] && env[RELAY_ENV_SCRIPT]);
-}
-
-/**
- * [W8 H12] 宿主 env → relay 连接三键的转发提取（原样转发语义的单一实现）。
- *
- * 三键同时非空（isRelayActive 同判）才返回——全有或全无，无中间态；身份键
- * SESSION_ID/RECORD_ID 不在本提取面（它们是父身份归属键，引擎子进程 env 由
- * SDK buildEngineChildEnv L1 deny 剥除、引擎按 run.params.ctx 重写，不靠 env 继承）。
- *
- * 消费方：D8 createZcodeEngine 薄壳（zsw 宿主链路的 relay 透传）；宿主 env 形态
- * 与 SDK EngineRelayEnv 结构等价（字段名 socket/node/script），TS 结构类型直接赋值。
- */
-export function readRelayForwardEnv(
-  env: NodeJS.ProcessEnv | Record<string, string | undefined>,
-): { socket: string; node: string; script: string } | undefined {
-  const socket = env[RELAY_ENV_SOCKET];
-  const node = env[RELAY_ENV_NODE];
-  const script = env[RELAY_ENV_SCRIPT];
-  if (!isRelayActive(env)) return undefined;
-  return { socket: socket as string, node: node as string, script: script as string };
-}

package/src/schema-emulation.ts

@@ -1,192 +0,0 @@
-// src/schema-emulation.ts
-//
-// schema 仿真降级（引擎侧原语，自 core execution/engine/common/schema-emulation.ts
-// 迁入 @zhushanwen/subagent-engine-sdk，实现体逐字等价）。迁移处置：无 core 内部
-// 依赖 → 直接搬（impl-plan §2.1 原语迁移处置表）。设计权威源：
-// docs/architecture/subagent-engine-abstraction.md D4（native/emulated 硬分流）+ §3.3.3
-// schema_emulation_failed 行 + §5 P2 行。
-//
-// ─── D4 硬分流（违反 = 历史事故形态） ───────────────────────────────
-// 本模块只服务 capabilities.schemaEnforcement === 'emulated' 的引擎
-// （zcode / opencode / kimi-code）。capabilities.schemaEnforcement === 'native' 的引擎
-// （pi 的 PI_WORKFLOW_SCHEMA env 注入链路、claude-code --json-schema、codex
-// --output-schema）**禁止** import 本模块做二次校验或改写其结果——宿主侧再叠一层
-// ajv 会制造第二校验权威，恰是 structured-output 方案 A [HISTORICAL]
-// （2026-08-01「校验自报 schema 致修复静默丢失」事故）的形态。
-// ajv 只允许出现在 emulated 路径（本模块），这是全仓唯一例外。
-//
-// 重试语义：本模块两个函数保持纯——校验失败/提取失败由调用方（宿主编排层）决定
-// 重试，语义与 structured-output 的 workflow-hook 对齐（重试一次、强化 prompt；
-// 仍失败报 schema_emulation_failed，错误含原始输出尾部）。
-//
-// 文案对齐：错误回显风格对齐 structured-output 的 execute.ts（"Schema validation
-// failed: ..."），但不 import 其内部模块（公共层自实现；structured-output 是
-// peer 依赖且可选，import 会造成公共层对 sibling extension 的硬依赖）。
-
-import Ajv, { type ValidateFunction } from "ajv";
-
-/** 原始输出尾部回显长度（结果对象的 tail 字段，供错误展示与重试 prompt 回灌）。 */
-export const SCHEMA_EMULATION_TAIL_CHARS = 500;
-
-// ============================================================
-// prompt 注入段
-// ============================================================
-
-/**
- * 构造 prompt 注入段：schema 声明 + 输出格式约定（emulated 引擎的 launcher 把它拼进
- * 最终 prompt，替代引擎不存在的 schema 强制通道）。
- *
- * 文案风格对齐 structured-output 的 promptGuidelines（"Do not output JSON in text"：emulated 引擎没有工具可调，JSON 必须出现在文本里）。
- */
-export function buildSchemaEmulationSegment(schema: object): string {
-  const schemaJson = JSON.stringify(schema);
-  return [
-    "## Structured Output Requirement",
-    "Your final answer MUST contain exactly one JSON value conforming to this JSON Schema (draft-07):",
-    schemaJson,
-    "Output rules:",
-    "- Output ONLY the JSON value — no prose before or after it.",
-    "- If you wrap it in a markdown code fence, use a single ```json fence.",
-    "- Do not output multiple JSON values; the first complete JSON value is extracted.",
-  ].join("\n");
-}
-
-// ============================================================
-// 三级容错提取 + ajv 校验
-// ============================================================
-
-/** 提取结果联合：ok=true 携带通过校验的 parsed；ok=false 携带 error 简述 + 原始输出尾部。 */
-export type StructuredOutputResult =
-  | { ok: true; parsed: unknown }
-  | { ok: false; error: string; tail: string };
-
-/**
- * 从模型文本输出提取并校验结构化 JSON（三级容错 → ajv）。
- *
- * 三级容错（逐级降级，任一级提取成功即进 ajv）：
- *   1. 直接 JSON.parse（trim 后整体是合法 JSON）；
- *   2. 剥 markdown code fence（```json ... ``` / ``` ... ```）取围栏内内容；
- *   3. 首尾括号扫描（首个 '{'/'[' 到末个 '}'/']' 的子串——容纳前后杂文本）。
- *
- * ajv 校验失败/三级提取失败返回 ok:false（不 throw）——重试与否是宿主编排层的
- * 决策（见文件头重试语义），本函数每次调用独立无状态。
- */
-export function extractAndValidateStructuredOutput(
-  text: string,
-  schema: object,
-): { ok: true; parsed: unknown } | { ok: false; error: string; tail: string } {
-  return extractImpl(text, schema);
-}
-
-/** 实现体（签名拆分只为让导出签名与契约声明逐字一致，见 StructuredOutputResult）。 */
-function extractImpl(text: string, schema: object): StructuredOutputResult {
-  const tail = text.length > SCHEMA_EMULATION_TAIL_CHARS
-    ? text.slice(text.length - SCHEMA_EMULATION_TAIL_CHARS)
-    : text;
-
-  const extracted = extractJsonCandidate(text);
-  if (extracted === undefined) {
-    return {
-      ok: false,
-      error:
-        "could not extract JSON from model output after 3-stage fallback " +
-        "(direct parse -> code-fence strip -> bracket scan)",
-      tail,
-    };
-  }
-
-  const validate = getOrCompileValidator(schema);
-  if (validate === undefined) {
-    return {
-      ok: false,
-      error: "host-side JSON Schema compilation failed (invalid schema object)",
-      tail,
-    };
-  }
-
-  const valid = validate(extracted);
-  if (!valid) {
-    // 错误格式对齐 structured-output："instancePath message" 逐条 join
-    const errors = validate.errors?.map((err) => `${err.instancePath} ${err.message}`).join("; ");
-    return {
-      ok: false,
-      error: `Schema validation failed: ${errors ?? "(no detail)"}`,
-      tail,
-    };
-  }
-  return { ok: true, parsed: extracted };
-}
-
-// ── 内部：三级提取 ──────────────────────────────────────────────
-
-/** 三级容错提取 JSON candidate；全部失败返回 undefined。 */
-function extractJsonCandidate(text: string): unknown {
-  // 第 1 级：整体直接 parse（最常见——严格遵守输出约定的模型）
-  const direct = tryParse(text.trim());
-  if (direct.ok) return direct.value;
-
-  // 第 2 级：markdown code fence 剥离（模型爱用 ```json 包裹）
-  const fenced = extractFirstFencedBlock(text);
-  if (fenced !== undefined) {
-    const parsed = tryParse(fenced.trim());
-    if (parsed.ok) return parsed.value;
-  }
-
-  // 第 3 级：首尾括号扫描（前后杂文本："Here is the result: {...} Hope this helps"）
-  const scanned = extractByBracketScan(text);
-  if (scanned !== undefined) {
-    const parsed = tryParse(scanned.trim());
-    if (parsed.ok) return parsed.value;
-  }
-
-  return undefined;
-}
-
-/** JSON.parse 包装：失败返回 ok:false（malformed 不是异常态，是三级降级的输入）。 */
-function tryParse(raw: string): { ok: true; value: unknown } | { ok: false } {
-  if (raw === "") return { ok: false };
-  try {
-    return { ok: true, value: JSON.parse(raw) };
-  } catch {
-    return { ok: false };
-  }
-}
-
-/** 取第一个 markdown code fence 块内容（```json / ``` 均可）；无 fence 返回 undefined。 */
-function extractFirstFencedBlock(text: string): string | undefined {
-  const match = /```(?:json)?\s*([\s\S]*?)\s*```/.exec(text);
-  return match?.[1];
-}
-
-/** 首尾括号扫描：首个 '{'/'[' 到末个 '}'/']' 的子串；边界不合法返回 undefined。 */
-function extractByBracketScan(text: string): string | undefined {
-  const objOpen = text.indexOf("{");
-  const arrOpen = text.indexOf("[");
-  const open = objOpen === -1 ? arrOpen : arrOpen === -1 ? objOpen : Math.min(objOpen, arrOpen);
-  const objClose = text.lastIndexOf("}");
-  const arrClose = text.lastIndexOf("]");
-  const close = Math.max(objClose, arrClose);
-  if (open === -1 || close === -1 || open >= close) return undefined;
-  return text.slice(open, close + 1);
-}
-
-// ── 内部：ajv 编译缓存 ──────────────────────────────────────────
-
-// WeakMap 缓存（schema 对象引用即 key，GC 友好）——模式对齐 structured-output 的
-// ajv-validator.ts（自实现，不跨包 import；见文件头依赖边界说明）。
-// CJS 多 entry 内联副本的实例分裂影响 = 缓存 miss 重新编译，无语义后果。
-const ajvCache = new WeakMap<object, ValidateFunction>();
-
-/** 编译（或取缓存）validator；schema 非法（ajv 抛错）返回 undefined 由调用方报错。 */
-function getOrCompileValidator(schema: object): ValidateFunction | undefined {
-  const cached = ajvCache.get(schema);
-  if (cached) return cached;
-  try {
-    // strict:false 对齐 structured-output 的宽容度（非标 keyword 不炸编译）
-    const validate = new Ajv({ strict: false }).compile(schema);
-    ajvCache.set(schema, validate);
-    return validate;
-  } catch {
-    return undefined;
-  }
-}

package/src/spawn.ts

@@ -1,246 +0,0 @@
-// src/spawn.ts
-//
-// 引擎子进程 spawn 原语 + 引擎侧自灭（W12，impl-plan §2.12 / §2.2 R9-4② / §7.2 R9-2）。
-//
-// spawnEngineChild 是全部引擎 CLI 任务子进程的唯一 spawn 入口（W10 静态断言目标符号）：
-// - 硬编码 POSIX/Windows detached:false（+ windowsHide:true），不暴露 detached 选项
-//   ——引擎一代子进程不脱离进程组，宿主杀组即连带收割；
-// - 不把引擎自身的 stdin fd 传给后代：子进程 stdin 恒为自有 pipe（'pipe'），
-//   禁止 'inherit'/fd 形态——否则宿主死后代仍持写端、EOF 永不到达，自灭主判据失效
-//   （R9-4②）。
-//
-// armEngineSelfDestruct 是引擎 CLI 的宿主死亡自灭守卫：主判据 stdio EOF，
-// 辅助判据 in-flight 反向请求计时超时（已 ack 的人机交互 / 两阶段长运行请求除外）。
-
-import { spawn } from "node:child_process";
-import type { ChildProcess } from "node:child_process";
-import { getLogger } from "./logger.ts";
-import type { buildEngineChildEnv } from "./env.ts";
-
-const logger = getLogger("engine-sdk/spawn");
-
-/** spawnEngineChild 的 env 必须来自 buildEngineChildEnv（三层契约终态）。 */
-export type EngineChildEnv = ReturnType<typeof buildEngineChildEnv>;
-
-/** 引擎子进程 spawn 选项（刻意不暴露 detached / stdio / stdin——形态硬编码，见文件头）。 */
-export interface SpawnEngineChildOptions {
-  command: string;
-  args: readonly string[];
-  /** 须由 buildEngineChildEnv 构建（类型即契约：三层 env 终态） */
-  env: EngineChildEnv;
-  cwd?: string;
-  /** 子进程 stdout/stderr 形态；缺省 'pipe'（协议帧走 stdout，stderr 走日志/轮转） */
-  stdout?: "pipe" | "ignore" | "inherit";
-  stderr?: "pipe" | "ignore" | "inherit";
-  /** AbortSignal 触发即 SIGTERM 杀子（缺省无） */
-  signal?: AbortSignal;
-}
-
-/** 这些键出现即拒绝：spawn 形态是本原语的契约面，不允许调用方绕过硬编码值。 */
-const FORBIDDEN_OPTION_KEYS = ["detached", "stdio", "stdin", "windowsHide"] as const;
-
-/**
- * 引擎任务子进程唯一 spawn 入口。
- *
- * 形态硬编码：detached:false、windowsHide:true、子进程 stdin 恒 'pipe'（自有 pipe，
- * 绝不继承引擎自身 stdin fd）。传入被禁止的形态键（detached/stdio/stdin/windowsHide）
- * 直接抛错——契约破坏应在配置期出声，不静默降级。
- */
-export function spawnEngineChild(opts: SpawnEngineChildOptions): ChildProcess {
-  for (const key of FORBIDDEN_OPTION_KEYS) {
-    if (key in opts) {
-      throw new Error(
-        `spawnEngineChild: option "${key}" is hardcoded by the engine spawn contract `
-          + `(detached:false / windowsHide:true / child stdin is always its own pipe); `
-          + `remove it from the call site`,
-      );
-    }
-  }
-
-  const child = spawn(opts.command, [...opts.args], {
-    cwd: opts.cwd,
-    env: opts.env,
-    detached: false,
-    windowsHide: true,
-    stdio: ["pipe", opts.stdout ?? "pipe", opts.stderr ?? "pipe"],
-  });
-
-  if (opts.signal !== undefined) {
-    opts.signal.addEventListener(
-      "abort",
-      () => {
-        child.kill("SIGTERM");
-      },
-      { once: true },
-    );
-  }
-  return child;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// 引擎侧自灭（宿主死亡检测）
-// ─────────────────────────────────────────────────────────────────────────────
-
-/** in-flight 未 ack 反向请求的计时超时缺省值（辅助判据，30s）。 */
-export const DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS = 30_000;
-
-/** 计时超时覆盖 env 名（引擎 CLI 启动时读；非法值 warn + 回落缺省）。 */
-export const ENGINE_HOST_REQUEST_TIMEOUT_ENV = "XYZ_ENGINE_HOST_REQUEST_TIMEOUT_MS";
-
-/** 计时巡检周期（ms）。仅为辅助判据的采样粒度，不构成行为契约。 */
-const SWEEP_INTERVAL_MS = 1_000;
-
-/** 反向请求计时面操作接口（消费方 = 引擎 CLI 的反向通道分发层）。 */
-export interface ReverseRequestClock {
-  /** 反向请求已发出（未 ack）——进入计时面。 */
-  started(id: string): void;
-  /**
-   * 收到 ack（两阶段第一阶段：已 ack 的 host/askUser、HostBridge.executeAndAwait
-   * 的 ack）——移出计时面但不终结（R9-2：已 ack 的等待不计入 in-flight 超时，
-   * ADR-0047 静默 ≠ 卡死）。
-   */
-  acked(id: string): void;
-  /** 请求终结（应答完成/失败/取消）——彻底移出。 */
-  settled(id: string): void;
-  /** 卸载守卫（引擎正常 shutdown 路径；自灭后幂等）。 */
-  dispose(): void;
-}
-
-export interface EngineSelfDestructOptions {
-  /** 主判据数据源：宿主→引擎的协议 stdin（EOF = 宿主死亡 → 立即自灭）。 */
-  stdin: NodeJS.ReadableStream;
-  /** 辅助判据超时（缺省 30s；显式传值优先于 env XYZ_ENGINE_HOST_REQUEST_TIMEOUT_MS）。 */
-  hostRequestTimeoutMs?: number;
-  /** 计时超时的 env 覆盖源（缺省读 process.env；测试注入用）。 */
-  timeoutEnv?: Record<string, string | undefined>;
-  /** 自灭执行器（缺省 = 杀自己进程组再杀自己；测试注入用）。 */
-  killSelf?: () => void;
-}
-
-/** 解析计时超时：显式 opt > env > 缺省；env 非法（非正整数）warn + 回落缺省。 */
-function resolveHostRequestTimeoutMs(opts: EngineSelfDestructOptions): number {
-  if (opts.hostRequestTimeoutMs !== undefined) return opts.hostRequestTimeoutMs;
-  const raw = (opts.timeoutEnv ?? process.env)[ENGINE_HOST_REQUEST_TIMEOUT_ENV];
-  if (raw === undefined || raw === "") return DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS;
-  const parsed = Number(raw);
-  if (!Number.isInteger(parsed) || parsed <= 0) {
-    logger.warn(
-      `invalid ${ENGINE_HOST_REQUEST_TIMEOUT_ENV}=${JSON.stringify(raw)}, falling back to `
-        + `${DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS}ms`,
-    );
-    return DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS;
-  }
-  return parsed;
-}
-
-/** 缺省自灭：先杀自己进程组（-pid，收割引擎 spawn 的任务子进程），失败回落杀自己。 */
-function killOwnProcessGroup(): void {
-  const pid = process.pid;
-  try {
-    process.kill(-pid, "SIGKILL");
-  } catch (err) {
-    // 进程组杀失败（非组长 / Windows 形态差异）——回落单进程杀，任务子进程由
-    // 各自的 stdio EOF / 宿主回收层兜底。
-    logger.warn(`process-group kill failed (${String(err)}), falling back to self kill`);
-    process.kill(pid, "SIGKILL");
-  }
-}
-
-/**
- * 武装引擎侧自灭守卫。返回 ReverseRequestClock 给反向通道分发层登记请求生命周期。
- *
- * 判据：
- * - 主判据 stdio EOF：stdin 'end'（数据面读尽）或 'close'（fd 关闭）→ 立即自灭
- *   （宿主死后无人再写协议帧，引擎继续跑只烧 token）；
- * - 辅助判据 in-flight 反向请求计时：未 ack 的反向请求超过 hostRequestTimeoutMs
- *   仍无 ack → 宿主大概率已死（EOF 未达或正在关闭）→ 自灭。**排除面**：已 ack 的
- *   host/askUser 与两阶段 ack 的长运行 HostBridge.executeAndAwait（ack 后等待任意
- *   时长合法，漏此项即「>30s pi 任务被自灭」turnTimeoutMs 同型事故）。
- *
- * 自灭执行 = 引擎自杀并杀自己进程组（spawnEngineChild 硬编码 detached:false，
- * 任务子进程同组连带收割）。
- */
-export function armEngineSelfDestruct(opts: EngineSelfDestructOptions): ReverseRequestClock {
-  const timeoutMs = resolveHostRequestTimeoutMs(opts);
-  const killSelf = opts.killSelf ?? killOwnProcessGroup;
-
-  // pending = 已发出未 ack（计时面）；settled/acked 请求不在面内。
-  const pending = new Map<string, number>();
-  let disposed = false;
-
-  const destroy = (reason: string): void => {
-    if (disposed) return;
-    disposed = true;
-    clearInterval(timer);
-    opts.stdin.removeAllListeners?.("end");
-    opts.stdin.removeAllListeners?.("close");
-    logger.warn(`engine self-destruct: ${reason}`);
-    killSelf();
-  };
-
-  // 主判据：stdio EOF（'end' 与 'close' 双挂——pipe 半关闭与 fd 销毁都算宿主死亡）
-  opts.stdin.once("end", () => destroy("host stdin EOF (end)"));
-  opts.stdin.once("close", () => destroy("host stdin closed"));
-
-  // 辅助判据：未 ack 反向请求计时巡检（timer 声明于 destroy 之后——destroy 仅经
-  // 事件/回调异步触发，调用时已初始化）
-  const timer = setInterval(() => {
-    const now = Date.now();
-    for (const [id, startedAt] of pending) {
-      if (now - startedAt > timeoutMs) {
-        destroy(`unacked reverse request ${id} exceeded ${timeoutMs}ms without host ack`);
-        return;
-      }
-    }
-  }, SWEEP_INTERVAL_MS);
-  timer.unref?.();
-
-  return {
-    started(id) {
-      if (!disposed) pending.set(id, Date.now());
-    },
-    acked(id) {
-      pending.delete(id);
-    },
-    settled(id) {
-      pending.delete(id);
-    },
-    dispose() {
-      if (disposed) return;
-      disposed = true;
-      clearInterval(timer);
-      opts.stdin.removeAllListeners?.("end");
-      opts.stdin.removeAllListeners?.("close");
-    },
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// NDJSON 行泵（子进程 stdout 拆行）
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * 流式 NDJSON 行泵：utf8 解码 + 缓冲累积 + "\n" 拆行循环（S4 簇 5b 收编：pi
- * spawn-run-pump 与 zcode connection 的逐字同构段单源化，实现以 pi 版为基线）。
- * 末行无换行符时滞留缓冲（NDJSON 语义：行以 \n 定界）；不监听 end/close/error——
- * 生命周期接线（close 收尾/error 兜底）由调用方自行挂接。stream 为 null/undefined
- * （无 stdio）时无操作，与原调用点 `child.stdout?.` 可选链语义等价。
- */
-export function pumpNdjsonLines(
-  stream: NodeJS.ReadableStream | null | undefined,
-  onLine: (line: string) => void,
-): void {
-  if (stream === null || stream === undefined) return;
-  stream.setEncoding("utf8");
-  let buffer = "";
-  stream.on("data", (chunk: string) => {
-    buffer += chunk;
-    let nl = buffer.indexOf("\n");
-    while (nl >= 0) {
-      const line = buffer.slice(0, nl);
-      buffer = buffer.slice(nl + 1);
-      onLine(line);
-      nl = buffer.indexOf("\n");
-    }
-  });
-}