@zhushanwen/subagent-engine-sdk 0.4.0 → 0.5.1

package/src/kill-chain.ts

@@ -1,265 +0,0 @@
-// 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");
-      },
-    );
-  });
-}

package/src/logger.ts

@@ -1,105 +0,0 @@
-// src/logger.ts
-//
-// 日志 facade（引擎侧原语，自 core src/core/logger.ts 迁入 @zhushanwen/subagent-engine-sdk）。
-// 迁移处置（impl-plan §2.1：「日志 facade」直接搬；kill-chain 行「logger 走 SDK facade」）：
-// core 版经 getHostServices()（configureCore 时序契约）动态解析宿主实现；SDK 进程
-// （引擎 CLI）无 configureCore 通道，同款「调用时动态解析」语义改为经可注入
-// LoggerSink——引擎 CLI 启动早期 configureLoggerSink(sink) 注入宿主形态 sink，
-// 未注入时落缺省 console 出口（对齐 core NULL_HOST.log 语义：warn/error 走 console、
-// debug no-op）。facade 代理而非绑死实现的时序契约（模块顶层 getLogger 先于配置、
-// 配置后透明切换）与 core 版逐字一致。
-//
-// CJS 多 entry 内联副本的实例分裂影响 = facadeCache 分裂（同 component 引用不同）；
-// facade 无状态、sink 解析每次调用发生，无语义后果——与 core 版同结论。
-
-/**
- * SDK 侧 logger sink（引擎 CLI 注入宿主形态日志出口；core 版对应 HostServices.log）。
- */
-export interface LoggerSink {
-  log(level: LogLevel, component: string, message: string, data?: unknown): void;
-}
-
-/** 日志级别。对齐 core logger 的 LogLevel（三值，无 info）。 */
-export type LogLevel = "debug" | "warn" | "error";
-
-/** logger 接口。与 core CoreLogger 结构兼容——迁移调用面（方法名/参数序）逐文件等价。 */
-export interface CoreLogger {
-  debug(msg: string, data?: unknown): void;
-  warn(msg: string, data?: unknown): void;
-  error(msg: string, data?: unknown): void;
-}
-
-// sink 配置态：globalThis[Symbol.for] slot（core host-services 同款范式）——模块级
-// `let` 在 dist 双形态 / CJS 多 entry 内联副本下会被分裂，slot 形态跨副本一致。
-const SINK_SLOT_KEY = Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
-
-type SinkSlot = { current: LoggerSink | undefined };
-
-function getSinkSlot(): SinkSlot {
-  let slot = Reflect.get(globalThis, SINK_SLOT_KEY) as SinkSlot | undefined;
-  if (!slot) {
-    slot = { current: undefined };
-    Reflect.set(globalThis, SINK_SLOT_KEY, slot);
-  }
-  return slot;
-}
-
-/** 缺省 console 出口（未注入 sink 时的日志不丢）。格式对齐 core NULL_HOST.log。 */
-const CONSOLE_SINK: LoggerSink = {
-  log(level, component, message, data) {
-    const line = `[${component}] ${message}`;
-    // data 作第二参数；缺省时必须省略——node console 会把显式 undefined 格式化成
-    // " undefined" 尾巴污染每行输出。
-    if (level === "error") {
-      if (data === undefined) console.error(line);
-      else console.error(line, data);
-      return;
-    }
-    if (level === "warn") {
-      if (data === undefined) console.warn(line);
-      else console.warn(line, data);
-      return;
-    }
-    // debug 缺省 no-op：对齐 core NULL_HOST 语义（未配置期多为模块加载窗口，刷屏无
-    // 诊断价值）；warn/error 不可静默。
-  },
-};
-
-function currentSink(): LoggerSink {
-  return getSinkSlot().current ?? CONSOLE_SINK;
-}
-
-/**
- * 注入日志 sink（引擎 CLI 启动早期调用；重复调用后者覆盖——测试切 sink 依赖此语义）。
- * 解析发生在每次 logger 方法调用时，模块顶层已缓存的 logger 透明切换，无加载顺序依赖。
- */
-export function configureLoggerSink(sink: LoggerSink): void {
-  getSinkSlot().current = sink;
-}
-
-/** 测试隔离专用：清空 sink 配置态（生产禁用）。 */
-export function resetLoggerSinkForTests(): void {
-  getSinkSlot().current = undefined;
-}
-
-// 与 core getLogger singleton 惯例对齐（同 component 同引用）。
-// facade 自身无状态（解析发生在方法内），缓存只为引用稳定，不影响透明切换。
-const facadeCache = new Map<string, CoreLogger>();
-
-export function getLogger(component: string): CoreLogger {
-  const existing = facadeCache.get(component);
-  if (existing) return existing;
-  const facade: CoreLogger = {
-    debug(msg, data) {
-      currentSink().log("debug", component, msg, data);
-    },
-    warn(msg, data) {
-      currentSink().log("warn", component, msg, data);
-    },
-    error(msg, data) {
-      currentSink().log("error", component, msg, data);
-    },
-  };
-  facadeCache.set(component, facade);
-  return facade;
-}

package/src/logs/stderr-rotation.ts

@@ -1,166 +0,0 @@
-// src/logs/stderr-rotation.ts
-//
-// 引擎侧 stderr tee 的实例维度文件名 + 轮转 + 过期清理（单源实现，前缀参数化——
-// 两引擎包（pi-subagent-cli / zcode-subagent-cli）各自的 logs/stderr-rotation.ts
-// 是本模块的薄包装，只绑定各自前缀常量）。
-//
-// 清理三判据（三者同时成立才删，缺一不删）：
-//   1. 同前缀（调用方绑定）；2. pid 已死（process.kill(pid,0) 跨实例探测，存活实例
-//   的文件一律不删）；3. mtime 过期（XYZ_LOG_KEEP_DAYS，缺省 7 天）。
-// 轮转参数读宿主同款 env：XYZ_LOG_MAX_BYTES（缺省 50MB）/ XYZ_LOG_KEEP_DAYS。
-
-import * as fs from "node:fs";
-import { dirname, join } from "node:path";
-
-/** 缺省轮转阈值（与宿主 logger 同源缺省：50MB）。 */
-const BYTES_PER_KB = 1024;
-const DEFAULT_MAX_FILE_MB = 50;
-const MS_PER_SECOND = 1000;
-const SECONDS_PER_MINUTE = 60;
-const MINUTES_PER_HOUR = 60;
-const HOURS_PER_DAY = 24;
-
-export const DEFAULT_STDERR_MAX_BYTES = DEFAULT_MAX_FILE_MB * BYTES_PER_KB * BYTES_PER_KB;
-
-const DAY_MS = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
-
-/** 缺省保留天数（与宿主 logger 同源缺省：7 天）。 */
-export const DEFAULT_STDERR_KEEP_DAYS = 7;
-
-/** 轮转参数（env 覆盖面 = 宿主 logger 同款 XYZ_LOG_* 两键）。 */
-export interface StderrRotationParams {
-  maxBytes: number;
-  keepDays: number;
-}
-
-function positiveIntEnv(env: NodeJS.ProcessEnv, key: string): number | undefined {
-  const raw = env[key];
-  if (raw === undefined || raw.trim() === "") return undefined;
-  const n = Number(raw);
-  return Number.isFinite(n) && n > 0 ? n : undefined;
-}
-
-/** 读 env 解析轮转参数（非法值回缺省——取证面配置不拖垮主通道）。 */
-export function stderrRotationParams(env: NodeJS.ProcessEnv): StderrRotationParams {
-  return {
-    maxBytes:
-      positiveIntEnv(env, "XYZ_LOG_MAX_BYTES") ?? DEFAULT_STDERR_MAX_BYTES,
-    keepDays:
-      positiveIntEnv(env, "XYZ_LOG_KEEP_DAYS") ?? DEFAULT_STDERR_KEEP_DAYS,
-  };
-}
-
-/** 实例维度 stderr tee 路径：<engineDataDir>/logs/<prefix><pid>.log。 */
-export function stderrLogPathFor(engineDataDir: string, pid: number, prefix: string): string {
-  return join(engineDataDir, "logs", `${prefix}${pid}.log`);
-}
-
-/** 从文件名解析实例 pid（非本前缀形态返回 undefined——调用方跳过）。 */
-export function stderrLogPidOf(fileName: string, prefix: string): number | undefined {
-  if (!fileName.startsWith(prefix)) return undefined;
-  const rest = fileName.slice(prefix.length);
-  // 兼容轮转副本形态 <pid>.log.<timestamp>
-  const pidToken = rest.split(".", 1)[0] ?? "";
-  if (!/^\d+$/.test(pidToken)) return undefined;
-  return Number(pidToken);
-}
-
-/** pid 存活探测（跨实例：ESRCH = 死；EPERM = 存活但非属主，按存活保守处理）。 */
-export function isPidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return (err as NodeJS.ErrnoException).code === "EPERM";
-  }
-}
-
-/**
- * 尺寸轮转：当前文件超过 maxBytes 时 rename 为 `<path>.<时间戳>` 副本并返回
- * true（调用方懒重开新文件继续 append）。rename 失败返回 false（继续 append 原
- * 文件——轮转是取证面优化，不是主通道）。
- */
-export function rotateStderrLogIfNeeded(
-  path: string,
-  params: StderrRotationParams,
-): boolean {
-  let size: number;
-  try {
-    size = fs.statSync(path).size;
-  } catch {
-    return false;
-  }
-  if (size <= params.maxBytes) return false;
-  const rotated = `${path}.${Date.now()}`;
-  try {
-    fs.renameSync(path, rotated);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export interface CleanupResult {
-  /** 已删除文件数。 */
-  deleted: number;
-  /** 命中前缀但跳过（pid 存活 / mtime 未过期 / 探测不确定）的文件数。 */
-  skipped: number;
-}
-
-/**
- * 过期清理：扫描 logsDir 下同前缀文件，三判据同时成立才删。目录缺失/读失败返回
- * 零删除（取证面 best-effort）。
- */
-export function cleanupStaleStderrLogs(
-  logsDir: string,
-  env: NodeJS.ProcessEnv,
-  prefix: string,
-  now: number = Date.now(),
-): CleanupResult {
-  const params = stderrRotationParams(env);
-  const expiryMs = params.keepDays * DAY_MS;
-  let deleted = 0;
-  let skipped = 0;
-  let names: string[];
-  try {
-    names = fs.readdirSync(logsDir);
-  } catch {
-    return { deleted, skipped };
-  }
-  for (const name of names) {
-    const pid = stderrLogPidOf(name, prefix);
-    if (pid === undefined) continue;
-    // 判据 2：pid 存活 → 该实例的文件（含轮转副本）一律不删
-    if (isPidAlive(pid)) {
-      skipped += 1;
-      continue;
-    }
-    // 判据 3：mtime 未过期 → 保留
-    const full = join(logsDir, name);
-    try {
-      if (fs.statSync(full).mtimeMs > now - expiryMs) {
-        skipped += 1;
-        continue;
-      }
-    } catch {
-      continue;
-    }
-    try {
-      fs.rmSync(full, { force: true });
-      deleted += 1;
-    } catch {
-      skipped += 1;
-    }
-  }
-  return { deleted, skipped };
-}
-
-/** 便捷入口：对 tee 路径所在 logs 目录做过期清理（流打开时机调用，每代一次）。 */
-export function cleanupSiblingStderrLogs(
-  logPath: string,
-  env: NodeJS.ProcessEnv,
-  prefix: string,
-  now?: number,
-): CleanupResult {
-  return cleanupStaleStderrLogs(dirname(logPath), env, prefix, now);
-}

package/src/nesting-guard.ts

@@ -1,140 +0,0 @@
-// src/nesting-guard.ts
-//
-// 嵌套防护（引擎侧原语，自 core execution/engine/common/nesting-guard.ts 迁入
-// @zhushanwen/subagent-engine-sdk，实现体逐字等价）。迁移处置：无 core 内部依赖 →
-// 直接搬（impl-plan §2.1 原语迁移处置表）；唯二差异：
-//   1. nestedSpawnRejectedError 自 core common/errors.ts 内联进本模块（errors.ts 不在
-//      迁移清单，本模块只消费它这一个构造器；文案与恢复指引逐字保留）；
-//   2. 头部注释的模块路径改为 SDK 落点。
-//
-// 设计权威源：docs/architecture/subagent-engine-abstraction.md D8（嵌套防护双层）：
-//   统一 XYZ_AGENT_SUBAGENT=1 标记（所有引擎 spawn 都注入，引擎 adapter 检测到即拒绝
-//   递归派发）+ 剥离各引擎原生标记（CC 的 CLAUDECODE / zsub 的 ZSW_NESTED / pi 的
-//   PI_SUBAGENT_*）防继承泄漏——子代理环境的旧标记会让孙代理误判自己已在嵌套层。
-//
-// 为什么 env 标记是唯一跨引擎可靠手段（被否方案见设计）：「隔离目录里不装扩展」
-// 依赖配置洁癖，且 opencode/CC 会吃项目级配置；env 由宿主显式控制，随 spawn 必达。
-//
-// [D3-⑤ 嵌套防护合一] 进程内执行嵌套上下文（原 SubagentService.execCtxAls，pi 路径
-// 私有）并入本文件——「嵌套防护」的两层机制（跨进程 env 标记 / 进程内 ALS 深度计数）
-// 单点于公共层。设计权威源：docs/design/dual-track（已删 git 可追溯）§3.3 D3-⑤
-// + 双轨清单 #10。
-
-import { AsyncLocalStorage } from "node:async_hooks";
-
-/** 统一嵌套标记 env 名（D8）。值恒 '1'。 */
-export const NESTED_SPAWN_ENV = "XYZ_AGENT_SUBAGENT";
-
-/** 需剥离的引擎原生嵌套标记（精确名）。 */
-const NATIVE_NESTED_KEYS: readonly string[] = ["CLAUDECODE", "ZSW_NESTED"];
-
-/** 需剥离的引擎原生嵌套标记前缀（pi 家族）。 */
-const NATIVE_NESTED_PREFIXES: readonly string[] = ["PI_SUBAGENT_"];
-
-/** env 对象形状（NodeJS.ProcessEnv 的结构子集，测试可传普通对象）。 */
-export type SpawnEnv = Record<string, string | undefined>;
-
-/**
- * nested_spawn_rejected 的结构化错误（自 core errors.ts 内联；code/recovery 与 core
- * 词表逐字一致，EngineError 类形态对齐 SDK protocol/error-codes.ts 的 EngineSdkError）。
- */
-export class NestedSpawnRejectedError extends Error {
-  readonly code = "nested_spawn_rejected";
-  /** 恢复指引：指向具体下一步，非安慰性文案。 */
-  readonly recovery: string;
-
-  constructor() {
-    super(
-      "nested_spawn_rejected: this process is already a subagent (XYZ_AGENT_SUBAGENT=1)",
-    );
-    this.name = "NestedSpawnRejectedError";
-    this.recovery =
-      "Subagents must not spawn further subagents (unbounded recursion guard). " +
-      "Do the work directly inside the current task instead of delegating.";
-  }
-}
-
-/**
- * 构造子代理 spawn env：注入 XYZ_AGENT_SUBAGENT=1 + 剥离引擎原生嵌套标记。
- * 返回新对象，不改入参（spawn env 组装链中的多层 spread 安全）。
- */
-export function buildNestedSpawnEnv(baseEnv: SpawnEnv): SpawnEnv {
-  const env: SpawnEnv = {};
-  for (const [key, value] of Object.entries(baseEnv)) {
-    if (NATIVE_NESTED_KEYS.includes(key)) continue;
-    if (NATIVE_NESTED_PREFIXES.some((prefix) => key.startsWith(prefix))) continue;
-    env[key] = value;
-  }
-  env[NESTED_SPAWN_ENV] = "1";
-  return env;
-}
-
-/**
- * 嵌套 spawn 防护断言：检测到统一标记（本进程已是 subagent）抛
- * nested_spawn_rejected——文案说明防护规则、指向 task 内自行完成。
- * 调用点：subagent 工具入口（进程创建前拒绝，D11 处置三级）。
- */
-export function assertNotNestedSpawn(env: SpawnEnv): void {
-  if (env[NESTED_SPAWN_ENV] === "1") {
-    throw new NestedSpawnRejectedError();
-  }
-}
-
-// ============================================================
-// [D3-⑤] 进程内执行嵌套上下文（原 SubagentService.execCtxAls 下沉）
-// ============================================================
-
-/** 执行嵌套状态：当前正在跑的 record 身份 + 递归深度（D-033 通用嵌套深度护栏的计数载体）。 */
-export interface ExecutionNestingState {
-  recordId: string | undefined;
-  depth: number;
-}
-
-/**
- * 进程内执行嵌套上下文（[D3-⑤] 从 SubagentService 的 execCtxAls 私有字段并入公共层）。
- *
- * 机制（原样迁移，行为零变化）：
- *   - ALS 按异步调用链传递当前 record 身份：B run() 期间包 this 上下文，B 内创建 C 时
- *     读到 B → C.parentRecordId=B.id、C.depth=B.depth+1；主 session 链上无 store → 顶层。
- *   - 进程级基线兜底 [ALS 断裂修复]：pi RPC mode 的 stdin JSONL 是事件回调式
- *     （attachJsonlLineReader stream.on("data")），每个命令是独立异步链，enterWith 的
- *     store 不会贯穿到后续 tool 调用事件（实测：递归第二层 parentRecordId/depth 丢失
- *     而 rootSessionId 正确）。基线 = 本进程自己的身份（initSession 从 env 读取）：
- *     读 ALS store 失败时兜底，保证「本进程派发的 subagent 都是本进程记录的孩子」。
- *
- * 实例归属：per-Service（基线随宿主进程身份而异），Service 构造时创建并持有。
- * 深度上限判据（MAX_FORK_DEPTH）留在调用方——上限常量属 execution 层
- * （session-context-resolver），公共层只提供状态存取单点。
- */
-export class ExecutionNestingContext {
-  private readonly als = new AsyncLocalStorage<ExecutionNestingState>();
-  private baselineState: ExecutionNestingState | null = null;
-
-  /** 建立进程级基线（initSession：有 env 自我标记 → env 身份；根进程 → null 顶层）。 */
-  setBaseline(state: ExecutionNestingState | null): void {
-    this.baselineState = state;
-  }
-
-  /** 读当前嵌套状态：ALS store 优先，断裂时基线兜底（顶层 = null）。 */
-  current(): ExecutionNestingState | null {
-    return this.als.getStore() ?? this.baselineState;
-  }
-
-  /**
-   * 读进程级基线（与 current() 的差异：不看 ALS store——直接父归属校验等场景要的是
-   * 「本进程自己的身份」而非「当前异步链正在跑的 record 身份」）。
-   */
-  baseline(): ExecutionNestingState | null {
-    return this.baselineState;
-  }
-
-  /** 包裹执行（B run() 期间挂 B 身份——内层创建 C 时 current() 读到 B）。 */
-  run<T>(state: ExecutionNestingState, fn: () => T): T {
-    return this.als.run(state, fn);
-  }
-
-  /** 顶层 enterWith（initSession 建立基线身份后挂入当前异步链）。 */
-  enterWith(state: ExecutionNestingState): void {
-    this.als.enterWith(state);
-  }
-}