@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/engine/engines/zcode/parser.ts

@@ -1,107 +1,27 @@
 // src/execution/engine/engines/zcode/parser.ts
 //
-// ZcodeEngine parser（P3）：stdout 有界收集 → 终 JSON 解析 → 合成 coarse AgentEvent
-// 流（设计 §3.3.7「批量引擎进程退出后一次性 emit 合成事件」形态）。TS 重写自 zsub
-// driver.js 的 createBoundedLineBuffer / parseStdoutJson，机制保留：
-//   - 有界双缓冲（头 4K + 尾 64K）：zcode response 可达数十 KB，无上限累加在长任务
-//     下爆内存；超限以「行」为单位丢弃，头尾各自保持可读。代价：单行 JSON 超过尾部
-//     窗口时无法完整解析——按错误路径处理（错误信息带尾部），内存安全优先。
-//   - 容错解析：正常是单个 JSON 文档；混入日志行则截取首尾大括号间内容。
+// ZcodeEngine usage 映射与 coarse 事件件（2026-09 收缩）：CLI stdout 有界收集/
+// 终 JSON 解析/buildRunFailedMessage 随 spawn 链删除（app-server 路径的终态来自
+// session-channel 的 read 兜底帧，不经 stdout 解析）。保留件：
+//   - ZcodeRawUsage / mapZcodeUsage / mapZcodeOutcomeUsage：原生 usage 形状 →
+//     事件层（execution）与终态层（orchestration）AgentUsage（spawn 时代实测形状，
+//     app-server 收尾帧 usage 同形——session-channel 消费）；
+//   - ZcodeTerminalPayload：app-server 轮成功态的载荷形态（turnResultToPayload 组装）；
+//   - synthesizeCoarseEvents：终态合成最小事件序列（不变量：turn_end 最后、其前
+//     至少一个 message_end）。
 //
 // 事件产出不变量（设计 §3.3.7，coarse 口径）：turn_end 前至少一个 message_end；
 // message_end.usage 出现时为完整 AgentUsage 形状（缺数据给显式 0，不给残缺对象）。
 
-import type { Readable } from "node:stream";
-
 import type { AgentUsage as ExecutionAgentUsage } from "../../../types.ts";
 import type { AgentUsage as OutcomeAgentUsage } from "../../../../orchestration/models/types.ts";
 import type { AgentEvent } from "../../types.ts";
-import { ZCODE_ERROR_TAIL_CHARS } from "./constants.ts";
-import type { ZcodeLaunchedProcess } from "./launcher.ts";
 
 // ============================================================
-// 有界行缓冲（zsub createBoundedLineBuffer 移植）
+// usage 映射（含运行时 guard——禁 any）
 // ============================================================
 
-export interface BoundedLineBuffer {
-  push(chunk: string): void;
-  flush(): void;
-  text(): string;
-  tail(n: number): string;
-}
-
-const DEFAULT_HEAD_BYTES = 4096;
-// eslint-disable-next-line no-magic-numbers -- 64KB = 64 * 1024 bytes
-const DEFAULT_TAIL_BYTES = 64 * 1024;
-
-export function createBoundedLineBuffer(opts: { headLimit?: number; tailLimit?: number } = {}): BoundedLineBuffer {
-  const headLimit = opts.headLimit ?? DEFAULT_HEAD_BYTES;
-  const tailLimit = opts.tailLimit ?? DEFAULT_TAIL_BYTES;
-  let pending = "";
-  let head = "";
-  let headFull = false;
-  const tailLines: string[] = [];
-  let tailBytes = 0;
-  let droppedBytes = 0;
-
-  function addLine(line: string): void {
-    if (!headFull) {
-      if (head.length + line.length <= headLimit) {
-        head += line;
-        return;
-      }
-      headFull = true;
-    }
-    tailLines.push(line);
-    tailBytes += line.length;
-    // 超出尾部窗口：从最旧的行开始丢
-    while (tailBytes > tailLimit && tailLines.length > 1) {
-      const dropped = tailLines.shift()!;
-      tailBytes -= dropped.length;
-      droppedBytes += dropped.length;
-    }
-    // 单行超过整个尾部窗口：只保留该行结尾（JSON 的错误信息通常在末尾）
-    if (tailBytes > tailLimit && tailLines.length === 1) {
-      const over = tailBytes - tailLimit;
-      tailLines[0] = tailLines[0]!.slice(over);
-      tailBytes -= over;
-      droppedBytes += over;
-    }
-  }
-
-  return {
-    push(chunk: string): void {
-      pending += chunk;
-      let nl: number;
-      while ((nl = pending.indexOf("\n")) >= 0) {
-        addLine(pending.slice(0, nl + 1));
-        pending = pending.slice(nl + 1);
-      }
-    },
-    flush(): void {
-      if (pending !== "") {
-        addLine(pending);
-        pending = "";
-      }
-    },
-    text(): string {
-      this.flush();
-      const mid =
-        droppedBytes > 0 ? `\n[zcode-engine] 输出过长，头尾之间已丢弃 ${droppedBytes} 字节\n` : "";
-      return head + mid + tailLines.join("");
-    },
-    tail(n: number): string {
-      const t = this.text();
-      return t.length > n ? t.slice(t.length - n) : t;
-    },
-  };
-}
-
-// ============================================================
-// 终 JSON 解析（含运行时 guard——禁 any）
-// ============================================================
-
-/** stdout 里的原生 usage 形状（2026-08-25 实测 0.16.5，字段名带 Tokens 后缀）。 */
+/** 原生 usage 形状（2026-08-25 实测 0.16.5，字段名带 Tokens 后缀；app-server 收尾帧同形）。 */
 export interface ZcodeRawUsage {
   source?: unknown;
   modelRequestCount?: unknown;
@@ -113,27 +33,6 @@ export interface ZcodeRawUsage {
   reasoningTokens?: unknown;
 }
 
-/** 容错解析 stdout：直接 JSON.parse；失败则截取首尾大括号间内容再试。 */
-export function parseZcodeStdoutJson(stdout: string): unknown {
-  const trimmed = stdout.trim();
-  try {
-    return JSON.parse(trimmed);
-  } catch (err) {
-    // 混入日志行等形态——吞掉异常继续首尾大括号容错提取（malformed 是降级输入不是错误态）
-    void err;
-  }
-  const first = trimmed.indexOf("{");
-  const last = trimmed.lastIndexOf("}");
-  if (first >= 0 && last > first) {
-    try {
-      return JSON.parse(trimmed.slice(first, last + 1));
-    } catch {
-      return null;
-    }
-  }
-  return null;
-}
-
 function finiteOr(v: unknown, fallback: number): number {
   const n = typeof v === "number" ? v : Number(v);
   return Number.isFinite(n) ? n : fallback;
@@ -177,7 +76,7 @@ function firstFinite(...vals: unknown[]): number {
   return 0;
 }
 
-/** 终 JSON 的解析产物（引擎消费面——response 必须是 string 才算合法终态）。 */
+/** 轮成功态的载荷形态（app-server 路径由 turnResultToPayload 组装：response 必 string）。 */
 export interface ZcodeTerminalPayload {
   sessionId?: string;
   response: string;
@@ -189,111 +88,6 @@ export interface ZcodeTerminalPayload {
   turnCount?: number;
 }
 
-export type ZcodeTerminalParse =
-  | { ok: true; payload: ZcodeTerminalPayload }
-  | { ok: false; reason: string };
-
-/** 解析终 JSON 并做形状校验（sessionId/usage/turnCount 逐字段 guard）。 */
-export function parseZcodeTerminal(stdout: string): ZcodeTerminalParse {
-  const parsed = parseZcodeStdoutJson(stdout);
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    return { ok: false, reason: "stdout 不是 JSON 对象" };
-  }
-  const obj = parsed as Record<string, unknown>;
-  if (typeof obj.response !== "string") {
-    return { ok: false, reason: "终 JSON 缺 string 型 response 字段（zcode 格式漂移嫌疑）" };
-  }
-  const usage = mapZcodeUsage(obj.usage);
-  const projection =
-    typeof obj.projection === "object" && obj.projection !== null
-      ? (obj.projection as Record<string, unknown>)
-      : undefined;
-  const outcomeUsage = mapZcodeOutcomeUsage(obj.usage, projection);
-  const turnCountRaw = projection?.turnCount;
-  return {
-    ok: true,
-    payload: {
-      response: obj.response,
-      ...(typeof obj.sessionId === "string" ? { sessionId: obj.sessionId } : {}),
-      ...(usage !== undefined ? { usage } : {}),
-      ...(outcomeUsage !== undefined ? { outcomeUsage } : {}),
-      ...(typeof turnCountRaw === "number" && Number.isFinite(turnCountRaw) ? { turnCount: turnCountRaw } : {}),
-    },
-  };
-}
-
-// ============================================================
-// 输出收集（进程退出 + 有界缓冲终态）
-// ============================================================
-
-export interface ZcodeCollectedOutput {
-  exitCode: number | null;
-  signal?: string;
-  /** 有界 stdout 全文（头 4K + 尾 64K，中间丢弃段有标记行）。 */
-  stdoutText: string;
-  /** stderr 尾部（有界 4K）。 */
-  stderrTail: string;
-}
-
-/**
- * 等待可读流终止（end/close/error 任一，1s 超时兜底）。
- * 为什么不能只 await 进程退出：宿主在微任务上下文里续跑时（vitest / async 编排链），
- * 进程 exited 的 promise 续跑可能先于流 data/end 事件的 nextTick 冲刷——直接读缓冲
- * 会拿到空串。等流终止事件是确定性的「数据已收完」判据；超时兜底防流异常挂起。
- */
-/** 流终止等待超时（兜底挂起流；比杀链 grace 短一个量级即可）。 */
-const DRAIN_TIMEOUT_MS = 1_000;
-
-function drainReadable(stream: Readable): Promise<void> {
-  return new Promise((resolve) => {
-    if (stream.readableEnded || stream.destroyed) {
-      resolve();
-      return;
-    }
-    let settled = false;
-    const finish = (): void => {
-      if (settled) return;
-      settled = true;
-      stream.removeListener("end", finish);
-      stream.removeListener("close", finish);
-      stream.removeListener("error", finish);
-      clearTimeout(timer);
-      resolve();
-    };
-    stream.once("end", finish);
-    stream.once("close", finish);
-    stream.once("error", finish);
-    const timer = setTimeout(finish, DRAIN_TIMEOUT_MS);
-    if (typeof timer.unref === "function") timer.unref();
-  });
-}
-
-/** 消费进程输出直到退出（事件 emit 前的收集段——终态解析素材）。 */
-export async function collectZcodeOutput(
-  proc: Pick<ZcodeLaunchedProcess, "stdout" | "stderr" | "exited">,
-): Promise<ZcodeCollectedOutput> {
-  const outBuf = createBoundedLineBuffer();
-  // stderr 只做诊断：不进解析路径，尾部 4K 足够
-  const errBuf = createBoundedLineBuffer({ headLimit: 0, tailLimit: DEFAULT_TAIL_BYTES });
-  proc.stdout.on("data", (d: Buffer | string) => {
-    outBuf.push(typeof d === "string" ? d : d.toString("utf8"));
-  });
-  proc.stderr.on("data", (d: Buffer | string) => {
-    errBuf.push(typeof d === "string" ? d : d.toString("utf8"));
-  });
-  const { code, signal } = await proc.exited;
-  await drainReadable(proc.stdout);
-  await drainReadable(proc.stderr);
-  outBuf.flush();
-  errBuf.flush();
-  return {
-    exitCode: code,
-    ...(signal !== undefined ? { signal } : {}),
-    stdoutText: outBuf.text(),
-    stderrTail: errBuf.text(),
-  };
-}
-
 // ============================================================
 // coarse 事件合成（不变量：turn_end 最后、其前至少一个 message_end）
 // ============================================================
@@ -306,131 +100,3 @@ export function synthesizeCoarseEvents(response: string, usage?: ExecutionAgentU
     { type: "turn_end" },
   ] as AgentEvent[];
 }
-
-// ============================================================
-// engine_run_failed 错误文案（设计 §3.3.3 错误规格行）
-// ============================================================
-
-/**
- * 运行中失败的结构化文案：stdout 尾部 2000 字 + exit code + 恢复指引。
- *
- * 指引按 stderr 特征归因（2026-08-25 真机教训：LLM 端点不可达导致的
- * AI_APICallError 曾套用「查版本/重跑探针/补 golden」指引，误导排查方向）：
- *   - LLM API 调用失败（stderr 含 AI_APICallError）：CLI 本体与输出解析正常，
- *     指向池内 provider 的 baseURL/apiKey 排查；
- *   - 其余（spawn 成功但格式漂移/解析失败）：保留 probe/golden 指引。
- */
-/** 错误文案里 stderr 尾部回显长度（stdout 有专用 2000 常量，stderr 更短防刷屏）。 */
-const STDERR_TAIL_IN_MSG_CHARS = 500;
-
-/** vercel.ai SDK 的 API 调用错误类名——zcode CLI 内部 LLM 调用失败的稳定特征。 */
-const LLM_API_FAILURE_SIGNATURE = "APICallError";
-
-/**
- * LLM/turn 级失败判定。两种实测形态（2026-08-25 真机）：
- *   - 无响应形态（端点不可达）：stderr 含 AI_APICallError 类名 + Symbol 行；
- *   - 有响应形态（如 HTTP 401）：stderr 打印 response headers + responseStatus/
- *     statusCode，类名行被截断不在尾部——靠 `Turn execution failed`（zcode CLI
- *     turn 失败统一尾巴）兜住。
- */
-function isLlmTurnFailure(stderrTail: string | undefined): boolean {
-  if (stderrTail === undefined) return false;
-  return (
-    stderrTail.includes(LLM_API_FAILURE_SIGNATURE) ||
-    stderrTail.includes("Turn execution failed")
-  );
-}
-
-/** stderr 中提取 HTTP 状态码（有响应形态），用于凭据/限流/上游错误的定向指引。 */
-function extractHttpStatus(stderrTail: string | undefined): string {
-  if (stderrTail === undefined) return "";
-  const m = stderrTail.match(/statusCode:\s*(\d{3})/);
-  if (m === null) return "";
-  const code = m[1]!;
-  const meaning: Record<string, string> = {
-    "401": "——凭据无效或过期（apiKey 被上游拒绝）",
-    "403": "——凭据无权限（apiKey 有效但无该模型/资源权限）",
-    "404": "——模型或路径不存在（核对模型名与 baseURL）",
-    "429": "——限流/配额耗尽",
-  };
-  return `，HTTP ${code}${meaning[code] ?? ""}`;
-}
-
-/**
- * 折叠 stderr 里 console.log 浅序列化产生的 "[Object]" 噪音行
- * （真实堆栈里常出现连续十余行 `[Object], [Object], …`，折叠后保留计数）。
- */
-function compactStderrObjectNoise(tail: string): string {
-  const OBJECT_LINE = /^(\[Object\][,\s]*)+$/;
-  const lines = tail.split("\n");
-  const out: string[] = [];
-  let run = 0;
-  const flush = (): void => {
-    if (run > 0) {
-      out.push(`[Object]×${run}`);
-      run = 0;
-    }
-  };
-  for (const line of lines) {
-    if (OBJECT_LINE.test(line.trim())) {
-      run++;
-      continue;
-    }
-    flush();
-    out.push(line);
-  }
-  flush();
-  return out.join("\n");
-}
-
-export function buildRunFailedMessage(opts: {
-  /** 实际使用的 CLI 路径（用户可经 XYZ_ZCODE_CLI 覆盖——文案必须引用真路径，不硬编码缺省值）。 */
-  cliPath: string;
-  exitCode: number | null;
-  stdoutTail: string;
-  stderrTail?: string;
-  parseReason?: string;
-  /** 本次任务解析出的模型全名（provider/model）——LLM 失败归因时点名排查对象。 */
-  modelRef?: string;
-  /** 池内 config.json 绝对路径——LLM 失败归因时给出 baseURL/apiKey 核对位置。 */
-  configPath?: string;
-}): string {
-  const parts: string[] = [];
-  if (opts.parseReason !== undefined) {
-    parts.push(`解析失败：${opts.parseReason}。`);
-  }
-  parts.push(`exit code: ${opts.exitCode ?? "null（被信号杀死）"}。`);
-  if (opts.stderrTail !== undefined && opts.stderrTail.trim() !== "") {
-    const compacted = compactStderrObjectNoise(opts.stderrTail);
-    parts.push(`stderr 尾部: ${compacted.slice(-STDERR_TAIL_IN_MSG_CHARS)}`);
-  }
-  // stdout 空段跳过（与 stderr 同判）——turn 0 即失败时 stdout 恒空，保留空 part
-  // 只会制造「stdout 尾部: <指引段>」的视觉嵌套误读（2026-08-25 真机复盘）
-  if (opts.stdoutTail.trim() !== "") {
-    parts.push(`stdout 尾部: ${opts.stdoutTail.slice(-ZCODE_ERROR_TAIL_CHARS)}`);
-  }
-
-  if (isLlmTurnFailure(opts.stderrTail)) {
-    const statusHint = extractHttpStatus(opts.stderrTail);
-    const modelHint =
-      opts.modelRef !== undefined ? `（本任务模型 '${opts.modelRef}'）` : "";
-    const configHint =
-      opts.configPath !== undefined
-        ? `① 核对池内 provider 的 baseURL 可达性与 apiKey 有效性（\`${opts.configPath}\`）${statusHint.includes("401") || statusHint.includes("403") ? "——apiKey 大概率无效或过期，需在凭据来源（ZCode 桌面或自建网关）更新" : ""}；`
-        : `① 核对 zcode 池内 provider 的 baseURL 可达性与 apiKey 有效性${statusHint}；`;
-    parts.push(
-      `恢复指引：模型 API 调用失败${statusHint}——CLI 本体与输出解析正常，问题在模型端点或凭据${modelHint}。` +
-        configHint +
-        "② 修复后直接重跑本任务（probe 缓存不受影响——运行期失败不缓存）；" +
-        "③ 或任务显式指定其他可用模型（provider/model 全名）；" +
-        "④ 或改用 engine: pi 重跑本任务。",
-    );
-  } else {
-    parts.push(
-      `恢复指引：跑 \`node ${opts.cliPath} --version\` 确认版本后重跑探针（probe）——` +
-        "若为格式漂移，把新 stdout 样本补录进 golden 库（\`__tests__/__fixtures__/zcode-golden-spawn.json\`）并更新 parser；" +
-        "或改用 engine: pi 重跑本任务。详见 docs/research/agent-engine-zcode.md。",
-    );
-  }
-  return `engine_run_failed: zcode CLI 运行失败。${parts.join(" ")}`;
-}

package/src/execution/engine/engines/zcode/preparer.ts

@@ -1,36 +1,21 @@
 // src/execution/engine/engines/zcode/preparer.ts
 //
-// ZcodeEngine preparer（P3）：spawn 前唯一副作用模块（设计 §3.3.7）——隔离 HOME 池化
-// + 池内 config.json 引导（凭据 + model.main）。TS 重写自 zsub 的
-// bootstrapIsolatedHome / model-router.js（真机验证过的机制），差异点：
+// ZcodeEngine prepare 期模型解析件（P3 起源，2026-09 收缩）：隔离 HOME 池化与
+// 池内 config 引导随 CLI spawn 链删除（共享宿主 HOME——app-server 的凭据经
+// appserver-launcher fs 拦截注入 v2 provider，本文件只剩 v2 单源的模型引用
+// 解析/校验/清单：
 //   - **凭据源 = v2 config 单源（2026-08-25 用户拍板）**：只读 `~/.zcode/v2/config.json`
 //     （ZCode 桌面登录态落点，GUI 管理面）。曾泛化过「v2 + cli config 双源合并」，
 //     但 `~/.zcode/cli/config.json` 不在 GUI 管理面、可能残留历史验证配置
 //     （8/24 zsub 开发残留把默认模型劫持到失效 router 端点的 401 事故），撤掉依赖；
-//   - 池目录必须经 resolvePoolDir（paths.ts SSOT，禁自拼——池布局要与 journal/refs
-//     共享同一形状，设计 §3.3.9）；
 //   - 凭据缺失/模型不可解析抛结构化 ZcodePrepareError（错误码对齐设计 §3.3.3：
 //     engine_credential_missing / model_not_available），一律先于进程创建。
-//
-// 为什么池按 provider+model 隔离（与设计 §3.3.9「agent 名池」不同）：并发 run 指向
-// 同一 HOME 但模型不同时，config.json 的 model.main 会出现「后写覆盖先写」的串池——
-// zsub 的 per-model HOME 池正是防这个；本引擎以 provider+model 为隔离粒度，agent 维度
-// 的池化留给宿主 refs.json（W3 对齐点）。
-//
-// [R4 D7] app-server 常驻 HOME 语义（锁/派生/pidfile 孤儿回收/allProviders 引导/
-// 凭据内容 hash 刷新）拆至同目录 appserver-home.ts——单一关注点分立。
 
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { resolvePoolDir } from "../../paths.ts";
-import { writeAtomicFileSync } from "../../../../shared/atomic-write.ts";
-import {
-  ZCODE_FALLBACK_DEFAULT_MODEL,
-  ZCODE_POOL_CONFIG_SUFFIX,
-  ZCODE_V2_CONFIG_PATH_SUFFIX,
-} from "./constants.ts";
+import { ZCODE_FALLBACK_DEFAULT_MODEL, ZCODE_V2_CONFIG_PATH_SUFFIX } from "./constants.ts";
 
 // ============================================================
 // 结构化错误（prepare 期——进程创建前 reject 的载体）
@@ -66,22 +51,20 @@ export interface ZcodeProviderEntry {
 interface SourceConfig {
   /** provider 注册表（来自 v2 config，逐条运行时 guard）。 */
   providers: Map<string, ZcodeProviderEntry>;
-  /** 源文件 mtime（池 config 免重写的比对基准；不可读 = 0）。 */
-  mtimeMs: number;
 }
 
 /** unknown 的 Record 窄化 guard（替代 as 全可选断言——taste/no-unsafe-cast）。 */
-export function isRecord(v: unknown): v is Record<string, unknown> {
+function isRecord(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
 /** provider 条目一律按 ZcodeProviderEntry 消费（索引签名形态，无需逐键校验）。 */
-export function isProviderEntry(v: unknown): v is ZcodeProviderEntry {
+function isProviderEntry(v: unknown): v is ZcodeProviderEntry {
   return isRecord(v);
 }
 
-export function readSourceConfig(absPath: string): SourceConfig {
-  const empty: SourceConfig = { providers: new Map(), mtimeMs: 0 };
+function readSourceConfig(absPath: string): SourceConfig {
+  const empty: SourceConfig = { providers: new Map() };
   let raw: string;
   try {
     raw = fs.readFileSync(absPath, "utf8");
@@ -95,19 +78,13 @@ export function readSourceConfig(absPath: string): SourceConfig {
     return empty;
   }
   if (!isRecord(parsed)) return empty;
-  const conf: SourceConfig = { providers: new Map(), mtimeMs: 0 };
+  const conf: SourceConfig = { providers: new Map() };
   const provider = parsed["provider"];
   if (isRecord(provider)) {
     for (const [id, entry] of Object.entries(provider)) {
       if (isProviderEntry(entry)) conf.providers.set(id, entry);
     }
   }
-  try {
-    conf.mtimeMs = fs.statSync(absPath).mtimeMs;
-  } catch {
-    // 源被并发删除等场景：mtime 取 0（比对恒不触发重写，池内完好配置继续用）
-    conf.mtimeMs = 0;
-  }
   return conf;
 }
 
@@ -253,114 +230,6 @@ export function listZcodeModels(sources?: ZcodeSourcePaths): Array<{ id: string;
 }
 
 // ============================================================
-// 池 key 与目录
+// 池 key 与目录（2026-09 删除：HOME 池化随 CLI spawn 链一并退役——共享宿主 HOME
+// 后无隔离池、无 config 引导，本文件只剩 v2 单源的模型解析/清单校验件）
 // ============================================================
-
-/** provider id 安全化（builtin:bigmodel → builtin-bigmodel；zsub providerDirName 同构）。 */
-function sanitizeProviderDirName(p: string): string {
-  return p.replace(/[^A-Za-z0-9._-]/g, "-");
-}
-
-/**
- * 池 key：`home-<provider>-<modelShort>`（zsub homePoolDir 同构——provider+model 维度
- * 隔离防并发串池，见文件头注释）。model 短名只清洗路径敌对字符（分隔符/空白），
- * 保留点号（GLM-5.3 / mimo-v2.5-pro 原样——zsub 同判）；进入文件系统时由
- * resolvePoolDir 的 sanitizeSeg 再做一层统一编码。
- */
-export function computeZcodePoolKey(modelRef: string): string {
-  const provider = providerOf(modelRef);
-  const short = modelShort(modelRef).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-  return `home-${sanitizeProviderDirName(provider)}-${short.length > 0 ? short : "default"}`;
-}
-
-// ============================================================
-// 隔离 HOME 引导（bootstrapIsolatedHome TS 重写）
-// ============================================================
-
-export interface ZcodePreparedHome {
-  /** 规范化模型全名 provider/model。 */
-  modelRef: string;
-  /** 池 key（handle.poolKey 数据源）。 */
-  poolKey: string;
-  /** 池目录绝对路径 = 隔离 HOME。 */
-  homeDir: string;
-  /** 池内 config.json 绝对路径。 */
-  configPath: string;
-  /** 本次是否实际重写了 config（mtime 免重写命中时 false——resume/复用轮零开销）。 */
-  wroteConfig: boolean;
-}
-
-/**
- * 池 config 是否需要重写（zsub homeNeedsBootstrap 同构）：
- *   1. 池目录或池内 config.json 不存在（首次建池）；
- *   2. 池内 config.json 损坏（torn write 防线：mtime 看似新但内容不完整）；
- *   3. 任一「实际被用到的」源 config 的 mtime 比池内 config 新（凭据/模型清单刷新过）。
- * 源不可读但池配置完好：保留池现状——没有更好依据时不破坏可用状态。
- */
-function homeNeedsBootstrap(configPath: string, sourceMtimeMs: number): boolean {
-  if (!fs.existsSync(configPath)) return true;
-  let poolMtimeMs = 0;
-  try {
-    JSON.parse(fs.readFileSync(configPath, "utf8"));
-    poolMtimeMs = fs.statSync(configPath).mtimeMs;
-  } catch {
-    return true;
-  }
-  return sourceMtimeMs > poolMtimeMs;
-}
-
-/** 池 config.json 缩进（人读友好——与 zsub 产出的文件形态一致）。 */
-export const CONFIG_INDENT_SPACES = 2;
-
-/**
- * 引导隔离 HOME 的 provider 配置（spawn 前调用）。
- *
- * - 只写 {model, provider}，刻意不含 plugins 块：第二重门禁——subagent 进程在隔离
- *   HOME 下不加载宿主插件（含 subagent-workflow 自身），物理隔断递归派发。
- * - tmp+rename 原子写：跨进程并发 bootstrap 下读者永远看到完整文件。进程内无需
- *   zsub 的互斥链——本实现全同步 fs（无 await 让出点），单线程事件循环天然不交错。
- * - 只写目标 provider 一个条目（spawn 池每池单 provider 单模型，凭据落盘面最小）。
- */
-export function prepareZcodeHome(opts: {
-  engineDataDir: string;
-  modelRef: string;
-  sources?: ZcodeSourcePaths;
-}): ZcodePreparedHome {
-  const { engineDataDir, modelRef } = opts;
-  const poolKey = computeZcodePoolKey(modelRef);
-  const homeDir = resolvePoolDir(engineDataDir, "zcode", poolKey);
-  const configPath = path.join(homeDir, ...ZCODE_POOL_CONFIG_SUFFIX);
-
-  const v2Path = opts.sources?.v2ConfigPath ?? defaultV2ConfigPath();
-  const v2 = readSourceConfig(v2Path);
-  const provider = providerOf(modelRef);
-  const entry = v2.providers.get(provider);
-  if (entry === undefined) {
-    // provider 不在 v2 注册表：模型引用不可解释（resolve 期漏网或直接调用）
-    throw new ZcodePrepareError(
-      "model_not_available",
-      `未知 provider "${provider}"（v2 config 无该条目：${v2Path}）。` +
-        `恢复指引：先经 resolveZcodeModelRef 校验模型引用，或先在 ZCode 桌面端配置该 provider 后重试。`,
-    );
-  }
-  if (!hasApiKey(entry)) {
-    // provider 存在但无凭据：resolve 与 bootstrap 之间凭据被撤（并发改动）
-    throw new ZcodePrepareError(
-      "engine_credential_missing",
-      `provider "${provider}" 存在但未配置 apiKey（${v2Path} 重读无凭据）。` +
-        `恢复指引：确认 ZCode 桌面端登录态有效后重试；凭据配置说明见 docs/research/agent-engine-zcode.md。`,
-    );
-  }
-
-  const hitSourceMtime = v2.mtimeMs;
-  let wroteConfig = false;
-  if (homeNeedsBootstrap(configPath, hitSourceMtime)) {
-    const payload = JSON.stringify({ model: { main: modelRef }, provider: { [provider]: entry } }, null, CONFIG_INDENT_SPACES);
-    // tmp+rename 原子写（shared/atomic-write 统一原语，U6b 迁移——rename 失败时
-    // 原语清残留 tmp，避免污染 HOME 目录；tmp 文件不参与读取，best-effort 语义不变）
-    writeAtomicFileSync(configPath, payload);
-    wroteConfig = true;
-  }
-  return { modelRef, poolKey, homeDir, configPath, wroteConfig };
-}
-