@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/execution/engine/common/event-journal.ts

@@ -1,254 +0,0 @@
-// src/execution/engine/common/event-journal.ts
-//
-// 宿主 event journal（P2 公共降级层）。设计权威源：
-// docs/architecture/subagent-engine-abstraction.md D6（第②级归属宿主——host 统一落盘
-// 则全引擎免费获得、格式唯一）+ §3.3.6 event journal 格式（JSONL 中立 v1）。
-//
-// 为什么 host 落盘而非各 adapter 缓存：adapter 各自缓存会演变出六种格式；host 消费
-// onEvent 统一落盘，read 第②级（journal 重放）与探针 golden 语料共用同一份产物。
-//
-// 写入纪律（§3.3.6）：onEvent 回调内追加写（有界缓冲 + 批量 flush），run 终态后
-// flush 并 fsync 一次。journal 不随池删（D5），生命周期跟随 record。
-//
-// 失败语义：journal 是降级链第②级（尽力而为的数据源）——写失败不炸主流程：
-// warn 一次 + 置 failed，后续 append 丢弃、close 立即返回（不静默：warn 有留痕）。
-
-import { appendFile, mkdir, open } from "node:fs/promises";
-import { readFileSync } from "node:fs";
-import { dirname } from "node:path";
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import type { AgentEvent } from "../../types.ts";
-
-const logger = getLogger("subagents");
-
-// ============================================================
-// 中立行格式（§3.3.6 v1）
-// ============================================================
-
-/** journal 单行（JSONL）。seq 是 host 侧单调递增序号——重放顺序权威。 */
-export interface JournalLine {
-  v: 1;
-  /** host 落盘时刻（Date.now()，ms）。 */
-  ts: number;
-  /** = RunContext.taskId = record.id（journal 文件名与池引用计数 key）。 */
-  taskId: string;
-  engineId: string;
-  seq: number;
-  /** AgentEvent 原样（onEvent 回调对象的 JSON.stringify 直接产物，无二次变换）。 */
-  event: AgentEvent;
-}
-
-// ============================================================
-// JournalWriter
-// ============================================================
-
-/** flush 触发的缓冲阈值：行数与字节数任一到达即批量落盘（有界缓冲）。 */
-const FLUSH_THRESHOLD_LINES = 64;
-// eslint-disable-next-line no-magic-numbers -- 32KB = 32 * 1024 bytes 缓冲字节换算常数
-const FLUSH_THRESHOLD_BYTES = 32 * 1024;
-
-/** FileHandle 的结构子集（close 期 fsync 用；注入 fake 可测）。 */
-export interface FileHandleLike {
-  sync(): Promise<void>;
-  close(): Promise<void>;
-}
-
-/** writer 的文件系统依赖面（结构接口：测试注入 fake，免 vi.mock 整个 fs 模块）。 */
-export interface JournalFsDeps {
-  mkdir(path: string, opts: { recursive: boolean }): Promise<unknown>;
-  appendFile(path: string, data: string): Promise<void>;
-  open(path: string, flags: string): Promise<FileHandleLike>;
-}
-
-const defaultFs: JournalFsDeps = {
-  mkdir: (p, o) => mkdir(p, o),
-  appendFile: (p, d) => appendFile(p, d, "utf8"),
-  open: (p, f) => open(p, f),
-};
-
-/** JournalWriter 构造参数。 */
-export interface JournalWriterOpts {
-  /** journal 文件绝对路径（经 paths.ts resolveJournalPath 派生，禁自拼）。 */
-  path: string;
-  taskId: string;
-  engineId: string;
-}
-
-/**
- * 追加写 writer：append 同步入队（onEvent 是同步回调，不阻塞事件流），批量异步
- * flush；close = flush 全部 + fsync 一次（§3.3.6 写入纪律）。
- *
- * 文件惰性创建：首个 flush 才 mkdir + appendFile——无事件的任务不产生空 journal。
- */
-export class JournalWriter {
-  private readonly opts: JournalWriterOpts;
-  private readonly fs: JournalFsDeps;
-  private readonly warn: (msg: string) => void;
-
-  private buffer: string[] = [];
-  private bufferedBytes = 0;
-  private seq = 0;
-  /** 串行化异步写（promise 链），防交错 append。 */
-  private chain: Promise<void> = Promise.resolve();
-  private failed = false;
-  private closed = false;
-  /** 是否成功落过盘——close 的 fsync 只对已存在的文件做（无事件任务不产生空文件）。 */
-  private wrote = false;
-
-  constructor(opts: JournalWriterOpts, fs: JournalFsDeps = defaultFs, warn: (msg: string) => void = defaultWarn) {
-    this.opts = opts;
-    this.fs = fs;
-    this.warn = warn;
-  }
-
-  /** 追加一个事件（同步入队；缓冲达阈值自动排队 flush）。closed/failed 后丢弃。 */
-  append(event: AgentEvent): void {
-    if (this.failed || this.closed) return;
-    const line: JournalLine = {
-      v: 1,
-      ts: Date.now(),
-      taskId: this.opts.taskId,
-      engineId: this.opts.engineId,
-      seq: this.seq++,
-      event,
-    };
-    const serialized = JSON.stringify(line);
-    this.buffer.push(serialized);
-    this.bufferedBytes += serialized.length;
-    if (this.buffer.length >= FLUSH_THRESHOLD_LINES || this.bufferedBytes >= FLUSH_THRESHOLD_BYTES) {
-      void this.flush();
-    }
-  }
-
-  /** 把缓冲写入磁盘（串行排队；等待此前所有排队写完成）。 */
-  flush(): Promise<void> {
-    if (this.failed || this.buffer.length === 0) return this.chain;
-    const chunk = `${this.buffer.join("\n")}\n`;
-    this.buffer = [];
-    this.bufferedBytes = 0;
-    this.chain = this.chain.then(() => this.writeChunk(chunk));
-    return this.chain;
-  }
-
-  /** run 终态后调用：flush 全部 + fsync 一次 + 关闭（幂等）。 */
-  async close(): Promise<void> {
-    if (this.closed) return;
-    this.closed = true;
-    await this.flush();
-    if (this.failed || !this.wrote) return;
-    // fsync 一次（§3.3.6）：进程崩溃后已 flush 的行不丢——record 读第②级的一致性依据
-    this.chain = this.chain.then(async () => {
-      const fh = await this.fs.open(this.opts.path, "r");
-      try {
-        await fh.sync();
-      } finally {
-        await fh.close();
-      }
-    });
-    await this.chain;
-  }
-
-  /** 是否已写失败（降级诊断用；failed 后 journal 不可作为②级数据源）。 */
-  get isFailed(): boolean {
-    return this.failed;
-  }
-
-  /**
-   * 重定向落盘路径（对齐点③：journal 路径权威 = 引擎声明的池 key）。
-   * 仅在尚未落盘（wrote=false）时允许——已 flush 过的文件搬家会制造两份半截 journal，
-   * 重放语义破坏；已落盘时 warn 拒绝（不静默）。事件在重定向前到达的场景由调用方
-   * 契约保证（RunContext.onPoolResolved 注释：引擎须在首个事件 emit 前回调）。
-   */
-  retarget(path: string): void {
-    if (this.closed || this.failed) return;
-    if (this.wrote) {
-      this.warn(
-        `[event-journal] retarget ignored for task ${this.opts.taskId}: journal already flushed to ` +
-          `${this.opts.path} (events must not precede onPoolResolved)`,
-      );
-      return;
-    }
-    this.opts.path = path;
-  }
-
-  /** 当前落盘路径（handle.journalPath 回填数据源）。 */
-  get path(): string {
-    return this.opts.path;
-  }
-
-  private async writeChunk(chunk: string): Promise<void> {
-    try {
-      await this.fs.mkdir(dirname(this.opts.path), { recursive: true });
-      await this.fs.appendFile(this.opts.path, chunk);
-      this.wrote = true;
-    } catch (err) {
-      // 尽力而为语义：一次写失败即永久放弃（重试追写会产生乱序行），warn 留痕不静默
-      this.failed = true;
-      this.buffer = [];
-      this.warn(
-        `[event-journal] write failed, journal for task ${this.opts.taskId} is unavailable ` +
-          `(read falls back to lower tiers): ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-  }
-}
-
-function defaultWarn(msg: string): void {
-  logger.warn(msg);
-}
-
-// ============================================================
-// 重放
-// ============================================================
-
-/**
- * 重放 journal：读取路径下全部事件，重放即得 AgentEvent 流（read 第②级）。
- *
- * - 文件不存在 → []（降级链语义：②级不可达不算错误，调用方落 ③级）；
- * - 损坏行跳过（追加写产物末行可能截断；跳过优于整体失败——设计 C5「三级都不 throw」）；
- * - 按 seq 稳定排序后返回（重放顺序权威是 seq，不依赖文件行序的隐式保证，§3.3.6）。
- */
-export function replayJournal(path: string): AgentEvent[] {
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return [];
-  }
-  const lines: JournalLine[] = [];
-  for (const row of raw.split("\n")) {
-    const trimmed = row.trim();
-    if (trimmed === "") continue;
-    const parsed = parseLine(trimmed);
-    if (parsed !== undefined) lines.push(parsed);
-  }
-  lines.sort((a, b) => a.seq - b.seq);
-  return lines.map((l) => l.event);
-}
-
-/** 单行 parse + 结构 guard（v=1 + event 形状最小判别：object 且 type 为 string）。 */
-function parseLine(trimmed: string): JournalLine | undefined {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch {
-    return undefined;
-  }
-  if (typeof parsed !== "object" || parsed === null) return undefined;
-  const rec = parsed as Record<string, unknown>;
-  const event = rec.event;
-  if (rec.v !== 1 || typeof rec.ts !== "number" || typeof rec.seq !== "number") return undefined;
-  if (typeof event !== "object" || event === null || typeof (event as Record<string, unknown>).type !== "string") {
-    return undefined;
-  }
-  return {
-    v: 1,
-    ts: rec.ts,
-    taskId: typeof rec.taskId === "string" ? rec.taskId : "",
-    engineId: typeof rec.engineId === "string" ? rec.engineId : "",
-    seq: rec.seq,
-    event: event as AgentEvent,
-  };
-}

package/src/execution/engine/common/journal-replay.ts

@@ -1,62 +0,0 @@
-// src/execution/engine/common/journal-replay.ts
-//
-// read 第②级（宿主 event journal 重放）的公共实现（P4，对齐点①接线）。设计权威源：
-// docs/architecture/subagent-engine-abstraction.md D6 + §3.3.6「重放等价性」——
-// journal 重放与 live 通路共用同一 reducer（updateFromEvent 范式），不引入第二套
-// 解析器；conformance C5 断言重放 turns 与 live 一致。
-//
-// 为什么放 common：zcode/pi 的 read() ②级降级是同一段逻辑（replayJournal 拿事件流 →
-// live reducer 累积 turns → 投影 SessionView）——放引擎各自实现会漂移出两份形状。
-
-import { createRecord, updateFromEvent } from "../../execution-record.ts";
-import type { AgentEvent } from "../../types.ts";
-import type { EngineHandle, SessionView } from "../types.ts";
-import { replayJournal } from "./event-journal.ts";
-import { aggregateUsage, toReplayedTurn } from "./session-view-projection.ts";
-
-/**
- * journal → SessionView（read 第②级）。
- * 返回 undefined = ②级不可达（journal 路径缺省 / 文件不存在 / 无事件），调用方落 ③级。
- * coarse 引擎（zcode）journal 只含合成事件，重放退化为摘要级——D6 已声明的保真度
- * 下限，非缺陷。
- */
-export function replayJournalToSessionView(
-  handle: EngineHandle,
-  engineId: string,
-): SessionView | undefined {
-  const journalPath = handle.data.journalPath;
-  if (journalPath === undefined) return undefined;
-  const events = replayJournal(journalPath);
-  if (events.length === 0) return undefined;
-  return eventsToSessionView(events, engineId, sessionIdFromHandle(handle));
-}
-
-/** 事件流 → SessionView（live reducer 累积 turns——重放等价性的实现体）。 */
-export function eventsToSessionView(
-  events: readonly AgentEvent[],
-  engineId: string,
-  sessionId?: string,
-): SessionView {
-  const record = createRecord("journal-replay", {
-    agent: "journal-replay",
-    model: "",
-    mode: "background",
-    task: "",
-    slug: "",
-    startedAt: 0,
-  });
-  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）。 */
-function sessionIdFromHandle(handle: EngineHandle): string | undefined {
-  const v = handle.data.sessionRef["sessionId"];
-  return typeof v === "string" ? v : undefined;
-}

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

@@ -1,221 +0,0 @@
-// src/execution/engine/common/kill-chain.ts
-//
-// 超时杀链与 abort 两级中断（P2 公共降级层）。设计权威源：
-// docs/architecture/subagent-engine-abstraction.md D1（abort 分级：引擎原生中断 →
-// 公共杀链兜底；CLI-only 引擎直接杀链，杀死后宿主合成终态）+ §3.3.3 engine_timeout /
-// engine_run_failed 行 + 附录 A「CLI 超时」行（6/6 引擎全缺 → 宿主公共层全补）。
-//
-// 为什么放公共层：没有任何引擎有 CLI 级超时（§2.2 表），杀链写一次全引擎复用（D4）。
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import { engineTimeoutDetail } from "./errors.ts";
-import type { AgentOutcome, AgentTaskSpec } from "../types.ts";
-import { DEFAULT_ENGINE_ID } from "../registry.ts";
-
-const logger = getLogger("subagents");
-
-// ============================================================
-// 杀链（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;
-}
-
-/** 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";
-
-/**
- * 杀链：SIGTERM → 等待 graceMs → 仍存活则 SIGKILL。
- *
- * @returns 'terminated' = SIGTERM 优雅退出（或进程已自行退出）；'killed' = 走了 SIGKILL。
- */
-export async function killChain(
-  child: KillableChild,
-  opts: { graceMs: number },
-): 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);
-  if (graceful === "settled") return "terminated";
-  // grace 超时后进程可能恰好在检查前一刻退出——复核退出态，避免误杀已死进程
-  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
-
-  safeKill(child, "SIGKILL");
-  // 有界收尸：无论等到与否都返回 'killed'（信号已发出，返回值表达「走了 SIGKILL」）
-  await raceTimeout(exited, SIGKILL_REAP_TIMEOUT_MS);
-  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: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-}
-
-// ============================================================
-// 超时终态合成
-// ============================================================
-
-/**
- * 合成 engine_timeout 终态（宿主超时杀链走完后的 AgentOutcome）。
- * 含 stdout 尾部 2000 字 + 「可用 engine: pi 重跑」建议（§3.3.3 第 6 行）；
- * exitCode: null = 被信号杀死（AgentOutcome 的杀链判据，§3.3.5）。
- */
-export function synthesizeTimeoutOutcome(
-  task: AgentTaskSpec,
-  stdoutTail: string,
-  engineId: string = DEFAULT_ENGINE_ID,
-): AgentOutcome {
-  return {
-    content: "",
-    // slug 进错误信息：单看 outcome（record 之外）也能定位是哪个任务超时
-    error: `engine_timeout: [slug=${task.slug}] ${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: ${
-                err instanceof Error ? err.message : String(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 继续但被放弃等待）。 */
-function raceTimeout(p: Promise<void>, ms: number): Promise<"settled" | "timeout"> {
-  return new Promise<"settled" | "timeout">((resolve) => {
-    const timer = setTimeout(() => resolve("timeout"), ms);
-    p.then(
-      () => {
-        clearTimeout(timer);
-        resolve("settled");
-      },
-      () => {
-        // 被 await 的 exit promise 不会 reject；防御分支保持语义完整（超时口径胜出前出错按 settled 处理）
-        clearTimeout(timer);
-        resolve("settled");
-      },
-    );
-  });
-}

package/src/execution/engine/common/nesting-guard.ts

@@ -1,50 +0,0 @@
-// src/execution/engine/common/nesting-guard.ts
-//
-// 嵌套防护（P2 公共降级层）。设计权威源：
-// 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 必达。
-
-import { nestedSpawnRejectedError } from "./errors.ts";
-
-/** 统一嵌套标记 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>;
-
-/**
- * 构造子代理 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）抛
- * EngineError(nested_spawn_rejected)——文案说明防护规则、指向 task 内自行完成。
- * 调用点：subagent 工具入口（进程创建前拒绝，D11 处置三级）。
- */
-export function assertNotNestedSpawn(env: SpawnEnv): void {
-  if (env[NESTED_SPAWN_ENV] === "1") {
-    throw nestedSpawnRejectedError();
-  }
-}