@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/src/index.ts

@@ -2,8 +2,8 @@
  * @zhushanwen/subagent-core — 公共 API barrel（D5 定稿 + post-convergence B-2 扩面）
  *
  * 公共 API 面 = 本文件导出 + package.json exports 的语义子入口
- * （./engines/zcode/reader、./engines/zcode/constants、./engine/paths、./relay-env）
- * + ./workflows/* 资产子入口。exports 面即 semver 契约（D5）：收窄不放宽——
+ * （./engine/paths、./engine/engine-discovery-scan、./relay-env——[W11/H3] 引擎
+ * 子入口 ./engines/zcode/* 已随内建引擎删除）+ ./workflows/* 资产子入口。exports 面即 semver 契约（D5）：收窄不放宽——
  * 新增导出走 minor，本文件刻意不使用 `export *`，逐名列出以使 diff 可审。
  * 内部实现细节（error-recovery / execute-agent-call / worker-script-builder 等
  * engine 编排件）不经 barrel 导出；host-surface 扩面（zsw 回接 U0，2026-08-30）
@@ -24,7 +24,7 @@
 // 0.4.0 = 首个公开发布的收敛收口面（0.3.0 为 2026-08-30 裁决的跳号占位，永不单独
 // 发布；+ minor changeset 收口面落本号）；与 package.json version 的一致性由
 // src/__tests__/smoke.test.ts 动态守护，改版本须两处同步。
-export const CORE_PACKAGE_VERSION = "0.6.0";
+export const CORE_PACKAGE_VERSION = "0.7.0";
 
 // ── 宿主端口接线面（core/）────────────────────────────────────
 // HostServices：dataRoot / log / discoveryRoots 端口 + configureCore 注入；
@@ -88,34 +88,54 @@ export {
   type EngineRoutingInput,
   type EngineRoutingSource,
 } from "./execution/engine/routing.ts";
+// [W8 补扫接线面] setEngineDiscoveryRescanOptions：宿主登记 hasEngineWithRescan 的
+// 补扫发现参数（与 session_start 发现扫描同源）；壳消费 = runtime
+// subagent-engine-history 的 ensureRuntimeEngineWiring。
+export { setEngineDiscoveryRescanOptions } from "./execution/engine/routing.ts";
 
 // ── 引擎注册 / 发现与进程面（execution/engine）────────────────
 // 组合根 index.ts 接线消费（registerXxx 引擎注册、syncEnginesFile engines 文件
 // 同步、killAllSpawnedChildren session 派生进程兜底清理）。
 export { syncEnginesFile } from "./execution/engine/engine-discovery.ts";
-export { registerPiEngine } from "./execution/engine/engines/pi/registration.ts";
-export { killAllSpawnedChildren } from "./execution/engine/engines/pi/session-runner.ts";
-export { registerZcodeEngine } from "./execution/engine/engines/zcode/registration.ts";
+// [W11/DoD#5] registerPiEngine（inproc 'pi' 注册）已删；[W3 chat 域收口] chat 域 inproc
+// 引擎（inproc pi 引擎目录）与 SubagentService 自持 DI 实例一并删除——registry 'pi' 由三级发现
+// 装载 cli descriptor，chat 轮次与 run 域同路经协议客户端发往 pi-subagent-cli 引擎进程
+// （G1：pi 引擎单一 CLI 形态，core 壳侧零内建引擎）。
+// [W8 D8 薄壳] killAllSpawnedChildren：扩展 index.ts / zsw runner-core.js 的业务调用点
+// 零改动。语义（[F-7 注释纠偏，如实口径]）= **仅镜像记账**——core 侧 spawnedChildren
+// 镜像整体清空（engine/host/spawned-children.ts 公共面），不发任何进程信号；
+// 子进程活在引擎进程内，其回收链 = ① stdin-EOF 自灭（宿主退出 / EngineClient 销毁
+// → 引擎进程 stdin 断源自灭，正常路径）；② disposeEngines()（registry）显式触发全部
+// 已实例化引擎 dispose（cli 形态 = RemoteEngine.dispose → EngineClient 有界收口）——
+// 该入口为宿主 shutdown 链预留，现无生产接线。subagent-workflow 扩展的
+// reapSpawnedChildrenOnShutdown（process hook 调本函数）因此同为镜像置死 no-op，
+// 不构成真实收割（现状登记，workflow 包生产码不动）。
+export { killAllSpawnedChildren } from "./execution/engine/host/spawned-children.ts";
+
+// [W8 D8 兼容公共面薄壳]（设计 §3.6 D8 表）：registerZcodeEngine 确保cli descriptor
+// 注册（vendored 相对定位，失败回退 inproc 过渡）+ engineDataDir 记入；createZcodeEngine
+// 返回 RemoteEngine('zcode')（deps → 协议客户端映射，sources 不跨进程）。实现见
+// execution/engine/d8-compat.ts——engines/zcode/registration.ts 的同名符号不再经
+// barrel 导出（inproc 实现保留至 W11，仅内部测试/过渡消费）。
+export {
+  createZcodeEngine,
+  registerZcodeEngine,
+  type D8CompatZcodeEngineDeps,
+} from "./execution/engine/d8-compat.ts";
 
-// pi session-runner 内核件（merge 裁决：dev 侧旧深路径 execution/session-runner.ts
-// 终态已不存在，符号随 u-2a 迁移至 engine/engines/pi/session-runner.ts）：
 // maxTurnsToWatchdogMs 为 maxTurns→watchdog 毫秒换算（U3/U4 / D7，floor 语义
-// 文档化——两宿主预算一致性 S2 的函数级锚点）；killRecordChildWithEscalation 为
-// 单 record 子进程升级回收（session 派生进程清理的细粒度入口）。
+// 文档化——两宿主预算一致性 S2 的函数级锚点；[W3] 定义收敛在 pi-host-binding，
+// 原 inproc session-runner（已删） 定义随删件消亡）；killRecordChildWithEscalation 为
+// 单 record 子进程终止的镜像记账入口（[W3] 实际终止在引擎进程内经协议承载）。
 export {
   killRecordChildWithEscalation,
-  maxTurnsToWatchdogMs,
-} from "./execution/engine/engines/pi/session-runner.ts";
+} from "./execution/engine/host/spawned-children.ts";
+export { maxTurnsToWatchdogMs } from "./execution/engine/host/pi-host-binding.ts";
 
-// zcode 引擎注册面：registerZcodeEngine 把 'zcode' 引擎登记进 registry（组合根
-// 职责，幂等，上方已导出）；createZcodeEngine 为 DI 工厂（测试/宿主注入 deps）。
-// ZcodeEngineDeps 经 registration.ts 的 re-export 导出（避免与 zcode-engine.ts 双源）。
-export { createZcodeEngine } from "./execution/engine/engines/zcode/registration.ts";
-export type { ZcodeEngineDeps } from "./execution/engine/engines/zcode/registration.ts";
-
-// ZcodeTaskShapeError：zcode 任务形状错误类（instanceof 分流用）——
-// execution-runtime-face.test.ts:29 消费，barrel 保留导出（engines 域 A1 裁决）。
-export { ZcodeTaskShapeError } from "./execution/engine/engines/zcode/zcode-engine.ts";
+// zcode 引擎注册面（[W8 D8 薄壳] createZcodeEngine 已上移 d8-compat——上方导出）。
+// [W11 收口] ZcodeEngineDeps 与 D8CompatZcodeEngineDeps 合并为别名（zsw 调用面的
+// deps 形状契约保持）；barrel 不导出引擎错误类（引擎错误归各引擎包自持）。
+export type { ZcodeEngineDeps } from "./execution/engine/d8-compat.ts";
 
 // 引擎注册表原语 + 引擎感知提示面：engine-awareness injector 消费。
 export {
@@ -132,6 +152,11 @@ export {
 // 子入口（D9：每条子入口 bundle 多一份 host-services 副本）。
 export { parseEngineHandle } from "./execution/engine/common/session-view-types.ts";
 export { readSubagentHistoryMessages } from "./execution/engine/common/session-view-service.ts";
+// [W8] registerNativeSessionReader：runtime 成为协议客户端的①级接入点——宿主把
+// 「协议 read」注册为引擎原生 reader，core 三级降级链（①协议 read → ②journal →
+// ③outcome）自动编排（含投影），宿主零投影代码。壳消费 = runtime
+// subagent-engine-history 的协议 reader 注册。
+export { registerNativeSessionReader } from "./execution/engine/common/session-view-service.ts";
 
 // ── 执行域（execution/）──────────────────────────────────────
 // types.ts 领域类型族：record / 响应 / 列表项等 subagent 域公共契约（壳消费最高频面，
@@ -262,7 +287,7 @@ export {
 
 // 错误类型族（error-recovery.ts 计划路径实测不存在，实测散布于下列源文件）：
 // resurrect/fork-depth/dirty-worktree 为动作层守卫抛出点（types.ts），
-// GitRunError 见 worktree 内核组裁决，ZcodeTaskShapeError 见引擎注册面。
+// GitRunError 见 worktree 内核组裁决。
 export {
   DirtyWorktreeError,
   ForkDepthExceededError,
@@ -313,14 +338,14 @@ export {
 } from "./execution/concurrency-pool.ts";
 
 // 模型引用切分原语（U1 契约面批件）：provider/model 引用切分与缺省值（两宿主
-// maxTurns/model 换算同源）；实现体内聚 zcode preparer/constants 不挪文件，
-// barrel re-export（§5.3）。
+// maxTurns/model 换算同源）。[W11/H2] 实现体随 engines/zcode 删除迁至
+// shared/zcode-model-ref.ts（宿主侧原语，与引擎包各自单源）。
 export {
   DEFAULT_PROVIDER_ID,
   hasApiKey,
   splitZcodeModelRef,
-} from "./execution/engine/engines/zcode/preparer.ts";
-export { ZCODE_FALLBACK_DEFAULT_MODEL } from "./execution/engine/engines/zcode/constants.ts";
+  ZCODE_FALLBACK_DEFAULT_MODEL,
+} from "./shared/zcode-model-ref.ts";
 
 // ── worktree git 内核（U5 / D5）───────────────────────────────
 // git 语义纯函数单源：保真读（gitRun）、SafeId 校验、dirty 谓词、
@@ -484,10 +509,14 @@ export type {
 // LifecycleDeps.store 用；pi 壳继续用 session 锚定的 JsonlRunStore。
 // DEFAULT_* 两常量：壳 jsonl-run-store.ts 生产消费（D3 判定进 barrel），
 // u-2c 删 ./* 通配后深路径仅测试侧 vitest alias 可解析，生产消费必须走 barrel。
+// pruneStateFilesBeyondCap：磁盘 retention 裁剪单源（S4-A7）——壳 jsonl-run-store
+// 的同构私有实现已删，改 import 本函数并注入自身 logger tag / toErrorMessage。
 export {
   DEFAULT_SAVE_MIN_INTERVAL_MS,
   DEFAULT_STATE_MAX_RUNS,
   FileRunStore,
+  pruneStateFilesBeyondCap,
+  type PruneStateDeps,
 } from "./orchestration/file-run-store.ts";
 
 // ── 快照 codec（U8 / D4）──────────────────────────────────────

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

@@ -12,7 +12,7 @@ import {
   isDeterministicSchemaFailureMsg,
   isStaleContextErrorMsg,
   STALE_CONTEXT_PATTERNS,
-} from "../../execution/engine/engines/pi/output-collector.ts";
+} from "@zhushanwen/pi-subagent-cli";
 import { executeAgentCall } from "../execute-agent-call.ts";
 import { AgentCall } from "../models/agent-call.ts";
 import { Budget } from "../models/budget.ts";

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/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 !== "";
+}