@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/orchestration/__tests__/workflow-files.test.ts

@@ -43,7 +43,7 @@ describe("saveWorkflow 目录注入（非 .pi 布局）", () => {
       expect(existsSync(join(tmpDir, "alpha.js"))).toBe(false);
       expect(readFileSync(join(savedDir, "alpha.js"), "utf-8")).toBe("// alpha body");
     } finally {
-      rmSync(root, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -56,7 +56,7 @@ describe("saveWorkflow 目录注入（非 .pi 布局）", () => {
       expect(existsSync(join(savedDir, "alpha.js"))).toBe(false);
       expect(existsSync(join(savedDir, "beta.js"))).toBe(true);
     } finally {
-      rmSync(root, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -72,7 +72,7 @@ describe("saveWorkflow 目录注入（非 .pi 布局）", () => {
       // 原文件不动
       expect(existsSync(join(tmpDir, "alpha.js"))).toBe(true);
     } finally {
-      rmSync(root, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -83,7 +83,7 @@ describe("saveWorkflow 目录注入（非 .pi 布局）", () => {
         "Temporary workflow 'ghost' not found",
       );
     } finally {
-      rmSync(root, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 });
@@ -104,7 +104,7 @@ describe("deleteWorkflow 目录注入（非 .pi 布局）", () => {
       expect(existsSync(join(tmpDir, "dup.js"))).toBe(false);
       expect(existsSync(join(savedDir, "dup.js"))).toBe(true);
     } finally {
-      rmSync(root, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -117,7 +117,7 @@ describe("deleteWorkflow 目录注入（非 .pi 布局）", () => {
       expect(msg).toBe(`Deleted workflow 'gamma' (${join(savedDir, "gamma.js")})`);
       expect(existsSync(join(savedDir, "gamma.js"))).toBe(false);
     } finally {
-      rmSync(root, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -130,7 +130,7 @@ describe("deleteWorkflow 目录注入（非 .pi 布局）", () => {
       ).toThrow("Cannot delete 'busy': workflow is currently running. Abort it first.");
       expect(existsSync(join(tmpDir, "busy.js"))).toBe(true);
     } finally {
-      rmSync(root, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -141,7 +141,7 @@ describe("deleteWorkflow 目录注入（非 .pi 布局）", () => {
         "Workflow file 'void' not found",
       );
     } finally {
-      rmSync(root, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 });
@@ -164,7 +164,7 @@ describe("缺省目录 = pi 布局（向后兼容回归）", () => {
       expect(existsSync(join(fakeCwd, ".pi", "workflows", "pi-wf.js"))).toBe(true);
     } finally {
       cwdSpy.mockRestore();
-      rmSync(fakeCwd, { recursive: true, force: true });
+      rmSync(fakeCwd, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -180,7 +180,7 @@ describe("缺省目录 = pi 布局（向后兼容回归）", () => {
       expect(existsSync(join(savedDir, "saved-only.js"))).toBe(false);
     } finally {
       cwdSpy.mockRestore();
-      rmSync(fakeCwd, { recursive: true, force: true });
+      rmSync(fakeCwd, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 });

package/src/orchestration/__tests__/workflow-script-registry-impl.test.ts

@@ -59,7 +59,7 @@ describe("loadWorkflowScriptByPath / WorkflowScript 导出形态（U1）", () =>
   afterEach(async () => {
     invalidateCache();
     for (const dir of tempDirs) {
-      await rm(dir, { recursive: true, force: true });
+      await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 

package/src/orchestration/execute-agent-call.ts

@@ -14,7 +14,7 @@
  * - 成功：consume usage + incrementCallCount + markDone + trace.update(completed)
  *
  * [D5-③ 结构化分诊] 失败分诊读 AgentResult.failureKind 字段（产出侧唯一识别点 =
- * execution/engine/engines/pi/output-collector.ts 的 classifyFailureKind，词表归属
+ * execution/engine/inproc pi 引擎目录/output-collector.ts 的 classifyFailureKind，词表归属
  * 见其文件头）。本模块不再扫 error 文案子串——**语义守恒（r1 MF4）**：unknown
  * （含字段缺省）= 可重试，保持收敛前的默认重试语义；仅 stale_context（不重试、
  * 换参重发场景由调用方编排）与 schema_deterministic 维持特判。

package/src/orchestration/file-run-store.ts

@@ -19,6 +19,7 @@
 // workflow run 快照是宿主编排状态，语义归属宿主数据根本身，宿主 configureCore
 // 注入什么就落什么，不引入第二条 env 覆盖链。
 
+import { readFileSync } from "node:fs";
 import { appendFile, mkdir, readdir, readFile, stat, unlink } from "node:fs/promises";
 import { join } from "node:path";
 
@@ -71,6 +72,13 @@ export interface FileRunStoreOptions {
    * {@link DEFAULT_SAVE_MIN_INTERVAL_MS}。测试经此注入小窗口（fake timers 推进）。
    */
   saveMinIntervalMs?: number;
+  /**
+   * [F-1 修复] run 状态目录覆盖。缺省 = `<dataRoot>/workflow-state`（zcode 宿主布局，
+   * 见 stateDir()）；pi 宿主的读侧装配点（round-supervisor sweep / idle-gc）必须传
+   * resolvePiWorkflowStateDir()（execution/workflow-state-root.ts）——pi 宿主 run state
+   * 由 JsonlRunStore 落 `<sessionDir>/workflow-state/`，与缺省根不相交。
+   */
+  stateDir?: string;
 }
 
 /** Node fs 错误 code 判定（ENOENT = 路径不存在，并发删除场景；对齐 pi isEnoentError）。 */
@@ -87,6 +95,77 @@ function isEnoentError(err: unknown): boolean {
 // 匹配 warn 可见性」在此实现——不内聚进 codec，保 pi 侧「v1 存量静默跳过」
 // 语义不被宽容化误读。
 
+// ── 磁盘保留原语（C1，两宿主单源）──────────────────────────
+//
+// pruneStateFilesBeyondCap 主体是宿主无关的目录裁剪原语（S4-A7 收口为导出单源）：
+// pi 宿主（subagent-workflow 扩展的 jsonl-run-store）此前持有一份逐段同构的私有实现，
+// retention 语义（glob 命中才删 / mtime 升序裁最旧 / 任何失败不抛）双份各自演化是
+// 漂移隐患——现在两宿主消费同一实现，日志与错误字符串化经 deps 注入（宿主各自的
+// logger tag / error 工具保持自治，行为差异仅 log tag 文案）。
+
+/** pruneStateFilesBeyondCap 的宿主注入依赖（日志与错误字符串化——tag 前缀由注入方决定）。 */
+export interface PruneStateDeps {
+  /** warn 通道（readdir / unlink 失败留证；清理是旁路维护，失败不抛） */
+  warn: (msg: string) => void;
+  /** debug 通道（成功裁剪记录） */
+  debug: (msg: string) => void;
+  /** error → 可读字符串（core 侧 err.message 兜底 String，宿主可用自有 error 工具） */
+  toMsg: (err: unknown) => string;
+}
+
+/**
+ * 把 state 目录裁剪到 cap 个最新 state 文件（mtime 升序删最旧，C1）。
+ *
+ * 语义（OR-5，两宿主单源）：
+ * - 只删目录内命中 {@link STATE_FILE_GLOB} 的文件；任何失败都不抛（清理是旁路
+ *   维护，不能拖垮持久化主链路）：readdir 失败静默放弃本轮（ENOENT = 从未持久化，
+ *   正常态），单个 unlink 失败（非 ENOENT）warn 留证后继续删其余——ENOENT 视为
+ *   并发删除竞态下的已达成目标，不告警；
+ * - stat 全集取 mtime，allSettled 部分降级——单文件 stat 失败（并发删除 ENOENT
+ *   等）静默跳过该文件，不阻断本轮裁剪。
+ *
+ * cap 解析（env 通道等）归调用方：FileRunStore 方法含 envName 通道超集；
+ * pi 宿主 jsonl-run-store 经 getEnvStateMaxRuns 解析后直传。
+ */
+export async function pruneStateFilesBeyondCap(
+  stateDir: string,
+  cap: number,
+  deps: PruneStateDeps,
+): Promise<void> {
+  let names: string[];
+  try {
+    names = await readdir(stateDir);
+  } catch (err) {
+    if (!isEnoentError(err)) {
+      deps.warn(`state retention: readdir ${stateDir} failed: ${deps.toMsg(err)}`);
+    }
+    return;
+  }
+  const stateFiles = names.filter((n) => STATE_FILE_GLOB.test(n)).sort();
+  if (stateFiles.length <= cap) return;
+
+  // stat 全集取 mtime；allSettled 部分降级（单文件失败静默跳过，不阻断本轮）
+  const settled = await Promise.allSettled(
+    stateFiles.map(async (name) => {
+      const full = join(stateDir, name);
+      return { full, mtimeMs: (await stat(full)).mtimeMs };
+    }),
+  );
+  const byMtimeAsc = settled
+    .flatMap((r) => (r.status === "fulfilled" ? [r.value] : []))
+    .sort((a, b) => a.mtimeMs - b.mtimeMs);
+  const victims = byMtimeAsc.slice(0, byMtimeAsc.length - cap);
+  for (const victim of victims) {
+    try {
+      await unlink(victim.full);
+      deps.debug(`state retention: pruned ${victim.full}`);
+    } catch (err) {
+      if (isEnoentError(err)) continue; // 并发删除已达成目标
+      deps.warn(`state retention: failed to delete ${victim.full}: ${deps.toMsg(err)}`);
+    }
+  }
+}
+
 // ── FileRunStore ────────────────────────────────────────────
 
 /**
@@ -101,18 +180,25 @@ function isEnoentError(err: unknown): boolean {
  *   warn——单行损坏不拖垮整个 run 的恢复（与 pi 壳 kill-9 恢复同容忍度）。
  *   版本衔接（快照 codec 归 run-snapshot.ts 单源，D4）：存量无 v 行按当前版本
  *   宽容读、写入恒补 v、v 不匹配跳过 + warn（三裁决明细见 parseLine 注释）。
- * - stateFilePath：纯路径计算（<dataRoot>/workflow-state/<runId>.jsonl），不建目录。
+ * - stateFilePath：纯路径计算（<状态目录>/<runId>.jsonl），不建目录。状态目录 =
+ *   构造注入的 stateDir 覆盖，或缺省 <dataRoot>/workflow-state（pi 宿主读侧装配点
+ *   必须传 resolvePiWorkflowStateDir()——见 FileRunStoreOptions.stateDir 与
+ *   execution/workflow-state-root.ts 的同源布局论证）。
  *
  * 未 configureCore 即 save/loadAll 会抛 core_host_not_configured（dataRoot 端口
  * 语义，host-services.ts §3.4）——宿主壳必须在初始化最早期注入。
  */
 export class FileRunStore implements RunStore {
-  /** run 状态目录绝对路径（dataRoot 每次现取——宿主覆盖配置即刻生效，对齐
-   *  data-dir.ts「不缓存路径防测试/宿主切换读到旧值」先例）。 */
+  /** run 状态目录绝对路径（显式覆盖优先——pi 宿主读侧装配点；缺省 dataRoot 每次现取
+   *  ——宿主覆盖配置即刻生效，对齐 data-dir.ts「不缓存路径防测试/宿主切换读到旧值」
+   *  先例）。 */
   private stateDir(): string {
-    return join(getHostServices().dataRoot(), STATE_DIR_NAME);
+    return this.stateDirOverride ?? join(getHostServices().dataRoot(), STATE_DIR_NAME);
   }
 
+  /** 显式状态目录覆盖（构造注入；见 FileRunStoreOptions.stateDir）。 */
+  private readonly stateDirOverride: string | undefined;
+
   /** save 节流最小间隔（ms），0 = 禁用。 */
   private readonly saveMinIntervalMs: number;
   /**
@@ -125,6 +211,7 @@ export class FileRunStore implements RunStore {
 
   constructor(opts?: FileRunStoreOptions) {
     this.saveMinIntervalMs = Math.max(0, opts?.saveMinIntervalMs ?? DEFAULT_SAVE_MIN_INTERVAL_MS);
+    this.stateDirOverride = opts?.stateDir;
   }
 
   stateFilePath(runId: string): string {
@@ -181,6 +268,41 @@ export class FileRunStore implements RunStore {
     return runs;
   }
 
+  /**
+   * [W4 sweep 判据，F2] 按 runId 同步查 run 状态（注册对账 sweep 的 workflow 收口
+   * 判据）。同步形态：sweep 在 session_start 同步链内运行（runReconcileSweep 同步
+   * 契约），不能 await loadAll——对单 runId 做同步文件读（对齐 sweep 自身的 sync fs
+   * 读先例），逐行解析复用 parseLine（版本衔接 + 形状校验与 loadLatestValidLine
+   * 单源，同步只读不触碰 lastSavedAt 节流记账）。
+   *
+   * 判定（宁挂账不失明——误注销活跃 run 是事故方向，判据保守侧取「不可判定」）：
+   * - state 文件不存在 → missing（设计判据「已归档/不存在视同终态」——run 从未
+   *   落盘或已被清理，注册是死亡窗口残留）；
+   * - 末条有效快照 status = running → running（活跃，sweep 跳过）；
+   * - 末条有效快照 status ≠ running（done）→ terminal + reason（I2：done ⟹ reason
+   *   有值；reason 作 pending unregister 的 status 语义源）；
+   * - 文件存在但全部行损坏（无有效快照）→ running（读不出 ≠ 不存在，不补注销）。
+   */
+  findStateByIdSync(runId: string): { kind: "running" } | { kind: "terminal"; reason: string | undefined } | { kind: "missing" } {
+    let content: string;
+    try {
+      content = readFileSync(this.stateFilePath(runId), "utf8");
+    } catch {
+      return { kind: "missing" }; // ENOENT（未落盘/已清理）等不可读形态同视——见头注判定
+    }
+    const lines = content.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (line === "") continue; // 尾部空行（末行 \n 产物）静默跳过
+      const run = this.parseLine(line, `${runId}.jsonl`, i);
+      if (run === undefined) continue; // 损坏行继续向前找——最后一条有效行可能早于文件尾部
+      if (run.state.status === "running") return { kind: "running" };
+      return { kind: "terminal", reason: run.state.reason };
+    }
+    // 全部行损坏：读不出 ≠ 不存在——保守按活跃处理（宁挂账不误注销）
+    return { kind: "running" };
+  }
+
   /** 单文件从尾向头取第一条有效快照行；整文件无有效行返回 undefined（warn）。 */
   private async loadLatestValidLine(absPath: string, display: string): Promise<WorkflowRun | undefined> {
     let content: string;
@@ -247,15 +369,12 @@ export class FileRunStore implements RunStore {
 
   /**
    * 把 workflow-state 目录裁剪到上限个最新 state 文件（mtime 升序删最旧，C1）。
-   *
-   * 语义对齐 pi jsonl-run-store.pruneStateFilesBeyondCap（逐段同构）：
-   * - 只删本目录内命中 {@link STATE_FILE_GLOB} 的文件；任何失败都不抛（清理是
-   *   旁路维护，不能拖垮持久化主链路）：readdir 失败静默放弃本轮（ENOENT =
-   *   从未持久化，正常态），单个 unlink 失败（非 ENOENT）warn 留证后继续删
-   *   其余——ENOENT 视为并发删除竞态下的已达成目标，不告警；
-   * - stat 全集取 mtime，allSettled 部分降级——单文件 stat 失败（并发删除
-   *   ENOENT 等）静默跳过该文件，不阻断本轮裁剪。
-   *
+ *
+ * 主体委托导出单源 {@link pruneStateFilesBeyondCap}（retention 语义两宿主单源，
+ * S4-A7；日志经 deps 注入本模块 logger + `[file-run-store]` tag，行为与收口前
+ * 逐字一致）。磁盘裁剪不动内存 runs Map（内存侧淘汰归
+ * lifecycle.evictDoneRunsBeyondCap，两域独立）。
+ *
  * 上限解析（envName 通道，OR-5 ⑥b 默认开；显式非法值 opt-out 对齐 pi 解析风格）：
  * - `envName` 提供 → env 通道：`process.env[envName]` 未设/空 → 按默认上限
  *   {@link DEFAULT_STATE_MAX_RUNS} 裁剪（**默认开**——OR-5 修复前的 opt-in
@@ -265,19 +384,16 @@ export class FileRunStore implements RunStore {
  *   宿主如需自管保留可设足够大的正数值）；
  * - `envName` 缺省 → 无 env 通道，直接按 `max` 参数裁剪（上限 = max，调用方
  *   自管启用时机）。
-   *
-   * 本方法只做磁盘裁剪，不动内存 runs Map（内存侧淘汰归
-   * lifecycle.evictDoneRunsBeyondCap，两域独立）。
-   *
-   * @param max 上限（envName 缺省时生效；env 通道启用时被 env 值覆盖）
-   * @param envName opt-in 开关 + 上限覆盖 env 变量名（可选；pi 先例
-   *   `XYZ_SUBAGENT_STATE_MAX_RUNS`）
-   */
+ *
+ * @param max 上限（envName 缺省时生效；env 通道启用时被 env 值覆盖）
+ * @param envName opt-in 开关 + 上限覆盖 env 变量名（可选；pi 先例
+ *   `XYZ_SUBAGENT_STATE_MAX_RUNS`）
+ */
   async pruneStateFilesBeyondCap(max: number, envName?: string): Promise<void> {
     let cap = max;
     if (envName !== undefined) {
-      // 未设/空 → 默认开（OR-5 ⑥b：DEFAULT_STATE_MAX_RUNS）；非法/≤0 → 不清理
-      // （显式 opt-out 通道，见方法注释）；有效正数 → env 值覆盖
+    // 未设/空 → 默认开（OR-5 ⑥b：DEFAULT_STATE_MAX_RUNS）；非法/≤0 → 不清理
+    // （显式 opt-out 通道，见方法注释）；有效正数 → env 值覆盖
       const raw = process.env[envName];
       if (raw === undefined || raw === "") {
         cap = DEFAULT_STATE_MAX_RUNS;
@@ -287,41 +403,10 @@ export class FileRunStore implements RunStore {
         cap = parsed;
       }
     }
-
-    const stateDir = this.stateDir();
-    let names: string[];
-    try {
-      names = await readdir(stateDir);
-    } catch (err) {
-      if (!isEnoentError(err)) {
-        const reason = err instanceof Error ? err.message : String(err);
-        logger.warn(`[file-run-store] state retention: readdir ${stateDir} failed: ${reason}`);
-      }
-      return;
-    }
-    const stateFiles = names.filter((n) => STATE_FILE_GLOB.test(n)).sort();
-    if (stateFiles.length <= cap) return;
-
-    // stat 全集取 mtime；allSettled 部分降级（单文件失败静默跳过，不阻断本轮）
-    const settled = await Promise.allSettled(
-      stateFiles.map(async (name) => {
-        const full = join(stateDir, name);
-        return { full, mtimeMs: (await stat(full)).mtimeMs };
-      }),
-    );
-    const byMtimeAsc = settled
-      .flatMap((r) => (r.status === "fulfilled" ? [r.value] : []))
-      .sort((a, b) => a.mtimeMs - b.mtimeMs);
-    const victims = byMtimeAsc.slice(0, byMtimeAsc.length - cap);
-    for (const victim of victims) {
-      try {
-        await unlink(victim.full);
-        logger.debug(`[file-run-store] state retention: pruned ${victim.full}`);
-      } catch (err) {
-        if (isEnoentError(err)) continue; // 并发删除已达成目标
-        const reason = err instanceof Error ? err.message : String(err);
-        logger.warn(`[file-run-store] state retention: failed to delete ${victim.full}: ${reason}`);
-      }
-    }
+    await pruneStateFilesBeyondCap(this.stateDir(), cap, {
+      warn: (msg) => logger.warn(`[file-run-store] ${msg}`),
+      debug: (msg) => logger.debug(`[file-run-store] ${msg}`),
+      toMsg: (err) => (err instanceof Error ? err.message : String(err)),
+    });
   }
 }

package/src/orchestration/models/types.ts

@@ -7,12 +7,19 @@
  * 核心内容：
  * - 状态机：RunStatus = "running" | "done"（2 态，一次性生命周期，FR-3）
  * + DoneReason（completed/failed/aborted/budget_limited/time_limited）
- * - AgentCallOpts / AgentResult / AgentUsage（单次 agent 调用的输入/输出）
+ * - AgentCallOpts / AgentResult（单次 agent 调用的输入/输出，宿主面 SSOT 留守本地）
+ * + AgentUsage / ToolCallEntry / AgentFailureKind（自 SDK re-export，S4 簇 3 收编）
  * - ExecutionTraceNode / TracePatch / ToolCallEntry / WorkerLogEntry（trace 数据）
  *
  * 层归属：Engine（数据结构 + 不变式守卫）。
  */
 
+import type {
+  AgentFailureKind,
+  AgentOutcomeUsage as AgentUsage,
+  ToolCallEntry,
+} from "@zhushanwen/subagent-engine-sdk";
+
 import type { ExecutionRecord, WorktreeHandle } from "../../execution/types.ts";
 
 // ── 状态机 ────────────────────────────────────────────────────
@@ -188,6 +195,14 @@ export interface AgentCallOpts {
   cwd?: string;
   /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
   fork?: boolean;
+  /**
+   * fork-from 显式分叉源 session 文件（fork-from 断联恢复通道的唯一 lossless 载体）。
+   * 来源 = ExecuteOptions.forkFromSessionFile（host-task-spec 映射时的唯一改名点——
+   * 本形状起与 SDK 协议字段、引擎侧 SpawnRunParams.forkSource 三层同名，降低跨层
+   * 双名漂移面）。区别于 fork:true（主 session 作分叉源）：本字段点名任意已有
+   * session 文件。chat 域唯一写入方 = fork-from action。
+   */
+  forkSource?: string;
   /**
    * 执行引擎 id（P4 D9 三层优先级的第一层：调用参数级，workflow step 显式指定）。
    * 仅限「必须某引擎独有能力」的场景使用并注释原因（D9③ workflow 脚本不写死
@@ -227,46 +242,32 @@ export interface AgentCallOpts {
   permissionMode?: string;
 }
 
-/**
- * 单次 agent 调用的资源用量（FR-7 跨 turn 累积）。
- */
-export interface AgentUsage {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  cost: number;
-  contextTokens: number;
-  turns: number;
-}
-
-/**
- * 单次 tool 调用记录（FR-7 从 agent JSONL 流采）。
- */
-export interface ToolCallEntry {
- /** Tool name. */
-  name: string;
- /** Args preview string. */
-  input: string;
-}
-
-/**
- * 失败分诊结构化标签（D5-③，r1 MF4 钉正语义）。
- *
- * - stale_context：pi session context 被 compact/cancel/替换——重试无意义（同 call
- *   再次失败），不重试。
- * - schema_deterministic：确定性 schema 失败（SO tool 从未调用 / gate 终止 /
- *   不可满足 schema）——同 schema 重试必同结果，不重试。
- * - unknown：其余一切失败（瞬态 provider 错误、spawn 失败等）——**默认可重试**。
- *
- * **语义守恒（最高优先约束）**：unknown（含字段缺省）= 可重试——保持收敛前的
- * 默认重试语义；仅 stale_context 与 schema_deterministic 两态维持不重试特判。
- * 词表归属（产出侧单点识别）：stale_context / schema_deterministic 的识别词表
- * （stale 词表与确定性 schema 失败标记前缀）保留在产出侧
- * execution/engine/engines/pi/output-collector.ts 包内——词表漂移的失效模式是
- * failureKind=unknown → 保守重试（安全默认），不再是静默漏诊。
- */
-export type AgentFailureKind = "stale_context" | "schema_deterministic" | "unknown";
+// [S4 簇 3 收编] 以下三个契约类型本地定义已删除，自 @zhushanwen/subagent-engine-sdk
+// re-export（type-only，import 方路径零改动，结构等价由 protocol-closure.test.ts
+// 断言族守卫）：
+//   - AgentUsage ← SDK AgentOutcomeUsage（SDK 改名消歧：core 的两个同名 AgentUsage
+//     分属 execution 与 orchestration 域，本处锚定 orchestration 域——AgentResult.usage
+//     字段型，FR-7 跨 turn 累积）；
+//   - ToolCallEntry（单次 tool 调用记录，FR-7 从 agent JSONL 流采）；
+//   - AgentFailureKind（失败分诊结构化标签，D5-③）。
+// AgentCallOpts / AgentResult 留守本地（宿主面 SSOT——SDK 版 AgentCallOpts 是引擎面
+// 子集，字段裁决见 SDK contract-types 注释）。
+//
+// AgentFailureKind 语义守恒（最高优先约束，core 侧权威说明——SDK 侧为简版）：
+// - stale_context：pi session context 被 compact/cancel/替换——重试无意义（同 call
+//   再次失败），不重试。
+// - schema_deterministic：确定性 schema 失败（SO tool 从未调用 / gate 终止 /
+//   不可满足 schema）——同 schema 重试必同结果，不重试。
+// - unknown：其余一切失败（瞬态 provider 错误、spawn 失败等）——**默认可重试**。
+//   unknown（含字段缺省）= 可重试；仅 stale_context 与 schema_deterministic 两态
+//   维持不重试特判。词表归属（产出侧单点识别）：识别词表保留在产出侧
+//   execution/engine/inproc pi 引擎目录/output-collector.ts 包内——词表漂移的失效模式
+//   是 failureKind=unknown → 保守重试（安全默认），不再是静默漏诊。
+export type {
+  AgentFailureKind,
+  AgentOutcomeUsage as AgentUsage,
+  ToolCallEntry,
+} from "@zhushanwen/subagent-engine-sdk";
 
 /**
  * 单次 agent 调用的结果（统一形态）。
@@ -279,7 +280,7 @@ export interface AgentResult {
   content: string;
  /**
  * [D5-③] 失败分诊结构化标签（AgentFailureKind）。产出侧唯一识别点 =
- * execution/engine/engines/pi/output-collector.ts（collectResult 对最终 error
+ * execution/engine/inproc pi 引擎目录/output-collector.ts（collectResult 对最终 error
  * 分类后写入，经 agent-result-mapper / AgentOutcome 透传到本形态）；消费侧
  * execute-agent-call 读本字段分诊，不再扫 error 文案子串。
  *

package/src/shared/__tests__/atomic-write.test.ts

@@ -40,7 +40,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  rmSync(dir, { recursive: true, force: true });
+  rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 /** 目录内约定形态 tmp 残留计数（断言「无残留」用）。 */

package/src/shared/__tests__/resource-discovery-host-roots.test.ts

@@ -74,7 +74,7 @@ describe("C2 W2①: async 链 realpath 去重", () => {
     ws = tmpWorkspace();
   });
   afterEach(() => {
-    fs.rmSync(ws, { recursive: true, force: true });
+    fs.rmSync(ws, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("多链同文件（a.md 本体 + b.md symlink → a.md）清单只留 1 条", async () => {
@@ -171,7 +171,7 @@ describe("C2 W2④: hostRoots 同标签多根语义", () => {
     agentDir = path.join(ws, ".fake-agent");
   });
   afterEach(() => {
-    fs.rmSync(ws, { recursive: true, force: true });
+    fs.rmSync(ws, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("同标签两条 user-pi 根都被扫描（非靠后者整体覆盖）", async () => {
@@ -300,7 +300,7 @@ describe("C2 W2②: project-host 槽位序位", () => {
     hostRoot = path.join(ws, ".zcode", "agents");
   });
   afterEach(() => {
-    fs.rmSync(ws, { recursive: true, force: true });
+    fs.rmSync(ws, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("project-host 同名被 project-agents 遮蔽（project-agents 是项目级最高逃生门）", async () => {
@@ -364,7 +364,7 @@ describe("C2 红线 3: 单层扫描维持", () => {
     agentDir = path.join(ws, ".fake-agent");
   });
   afterEach(() => {
-    fs.rmSync(ws, { recursive: true, force: true });
+    fs.rmSync(ws, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("子目录不递归（nested/deep.md 不入清单）", async () => {
@@ -410,7 +410,7 @@ describe("C2 回归红线: pi 单条目形态快照", () => {
     agentDir = path.join(ws, ".fake-agent");
   });
   afterEach(() => {
-    fs.rmSync(ws, { recursive: true, force: true });
+    fs.rmSync(ws, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("与 pi 真实 agentDir 同构 fixture——source 标签与胜出路径逐项稳定", async () => {

package/src/shared/zcode-model-ref.ts

@@ -0,0 +1,31 @@
+// src/shared/zcode-model-ref.ts
+//
+// zcode 模型引用切分原语（U1 契约面批件）——[W11/H2] 随 engines/zcode 内建目录删除
+// 从 engines/zcode/{preparer,constants}.ts 迁出的宿主侧原语（barrel 原四件导出面
+// 不变：splitZcodeModelRef / hasApiKey / DEFAULT_PROVIDER_ID / ZCODE_FALLBACK_
+// DEFAULT_MODEL）。引擎侧等价物在 @zhushanwen/zcode-subagent-cli（两处单源各自
+// 演进，协议面不共享该常量——宿主只做引用切分，不做凭据校验）。
+
+/** provider 条目（v2 config.provider.<id>）的最小消费面（索引签名形态）。 */
+export interface ZcodeProviderEntryLike {
+  options?: { apiKey?: unknown };
+}
+
+/** 短名（无 provider 前缀）解析的默认 provider（zsub DEFAULT_PROVIDER_ID 同构）。 */
+export const DEFAULT_PROVIDER_ID = "builtin:bigmodel-coding-plan";
+
+/** zsub 同构的兜底缺省模型（v2 config 无 model.main 且 task 未指定时）。 */
+export const ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
+
+/** [R4] 规范化全名 provider/model → create 参数的 per-session model 拆分。 */
+export function splitZcodeModelRef(
+  modelRef: string,
+): { providerId: string; modelId: string } {
+  const slash = modelRef.lastIndexOf("/");
+  return { providerId: modelRef.slice(0, slash), modelId: modelRef.slice(slash + 1) };
+}
+
+export function hasApiKey(entry: ZcodeProviderEntryLike): boolean {
+  const key = entry.options?.apiKey;
+  return typeof key === "string" && key !== "";
+}