@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/orchestration/models/run-runtime.ts

@@ -30,15 +30,15 @@ export type ReleaseMode = "terminal";
 // ── RunRuntime ───────────────────────────────────────────────
 
 export class RunRuntime {
- /** Worker 线程句柄。 */
+  /** Worker 线程句柄。 */
   readonly worker: WorkerHandle;
- /** per-running-segment AbortController（一次性，无法复用——G3-001）。 */
+  /** per-running-segment AbortController（一次性，无法复用——G3-001）。 */
   readonly controller: AbortController;
- /** Run 级墙钟时间预算计时器（spec.budgetTimeMs > 0 时由 lifecycle 调度，
+  /** Run 级墙钟时间预算计时器（spec.budgetTimeMs > 0 时由 lifecycle 调度，
    * 到期 abortRun time_limited）。release 时清理，避免 abort/replaceRuntime
    * 后孤儿计时器仍触发（rebuildRuntime 会重排一个全新的计时器，旧的不应残留）。 */
   readonly timeBudgetTimer?: ReturnType<typeof setTimeout>;
- /**
+  /**
  * 本 runtime 代际是否已收到 worker 的终态消息（return / error）。
  *
  * [F1] worker exit(0) 且本标记为 false = worker 静默退出、未交付任何终态——最常见根因
@@ -57,7 +57,7 @@ export class RunRuntime {
  * rebuildRuntime 构造新 RunRuntime 自然重置。
  */
   receivedTerminalMessage = false;
- /** 防止 release 重复执行（幂等）。 */
+  /** 防止 release 重复执行（幂等）。 */
   private released = false;
 
   constructor(
@@ -70,7 +70,7 @@ export class RunRuntime {
     this.timeBudgetTimer = timeBudgetTimer;
   }
 
- /**
+  /**
  * 释放所有资源：terminate worker + abort controller。
  *
  * 幂等——重复调用安全（第二次起 no-op，released flag 守卫）。
@@ -86,18 +86,18 @@ export class RunRuntime {
   release(_mode: ReleaseMode): void {
     if (this.released) return;
     this.released = true;
- // 清理 run 级时间预算计时器——abort/terminate/replaceRuntime 后它不应再触发
- // （rebuildRuntime 会重排全新计时器；孤儿触发会把已终态的 run 误转 done）。
+    // 清理 run 级时间预算计时器——abort/terminate/replaceRuntime 后它不应再触发
+    // （rebuildRuntime 会重排全新计时器；孤儿触发会把已终态的 run 误转 done）。
     if (this.timeBudgetTimer) clearTimeout(this.timeBudgetTimer);
- // worker.terminate 异步但幂等——不 await（release 是同步签名，调用方
- // 不应被底层线程关闭阻塞；worker 收到 terminate 后自行清理）。
+    // worker.terminate 异步但幂等——不 await（release 是同步签名，调用方
+    // 不应被底层线程关闭阻塞；worker 收到 terminate 后自行清理）。
     void this.worker.terminate();
- // controller.abort 触发 listener（kill agent subprocess、中止在飞调用）。
- // 一次性语义——已 aborted 的 controller 重复 abort 无副作用。
+    // controller.abort 触发 listener（kill agent subprocess、中止在飞调用）。
+    // 一次性语义——已 aborted 的 controller 重复 abort 无副作用。
     this.controller.abort();
   }
 
- /** 是否已 release（测试 + 诊断用）。 */
+  /** 是否已 release（测试 + 诊断用）。 */
   get isReleased(): boolean {
     return this.released;
   }

package/src/orchestration/models/trace.ts

@@ -75,7 +75,7 @@ export class Trace {
   /** stepIndex 倒排索引（查询加速 O(1)；值与 nodes 元素引用共享）。 */
   private readonly byIndex = new Map<number, ExecutionTraceNode>();
 
- /**
+  /**
  * 从已有节点数组重建 Trace（用于 RunStore 反序列化重水合）。
  *
  * 防御性拷贝——传入数组不被持有，外部 mutation 不影响 Trace。
@@ -96,7 +96,7 @@ export class Trace {
     return trace;
   }
 
- /**
+  /**
  * Append a trace node（append-only，不改已有节点）。
  *
  * 入口裁剪：超长 result.content 先 mutate 入参节点的 result 字段，
@@ -109,7 +109,7 @@ export class Trace {
     this.byIndex.set(node.stepIndex, node);
   }
 
- /**
+  /**
  * Update a trace node by stepIndex (callId) with a partial patch.
  *
  * 只改 patch 中提供的字段（status/result/error/completedAt/sessionId）。
@@ -129,7 +129,7 @@ export class Trace {
     if (patch.sessionFile !== undefined) node.sessionFile = patch.sessionFile;
   }
 
- /**
+  /**
  * 查找指定 stepIndex 的节点（byIndex O(1)，trace 中 stepIndex 应唯一）。
  *
  * 语义差异声明（旧线性扫 first-match → Map last-wins）：仅在破坏
@@ -145,12 +145,12 @@ export class Trace {
     return this.byIndex.get(stepIndex);
   }
 
- /** 按节点引用删除（仅用于测试或 run 重建场景；正常运行不调用）。 */
+  /** 按节点引用删除（仅用于测试或 run 重建场景；正常运行不调用）。 */
   find(stepIndex: number): ExecutionTraceNode | undefined {
     return this.findByStepIndex(stepIndex);
   }
 
- /**
+  /**
  * 按 stepIndex 移除节点（崩溃重建清理在飞 call 用）。
  *
  * 正常运行不调用（append-only 不变式）。仅 error-recovery 的 discardInFlightCalls
@@ -167,7 +167,7 @@ export class Trace {
     this.byIndex.delete(stepIndex);
   }
 
- /**
+  /**
  * readonly 视图——返回内部 nodes 数组引用（仅类型级 readonly，运行时无
  * 防御）。消费方禁止结构化 mutate（push/splice/重排/覆盖元素）：byIndex
  * 引入后外部结构化 mutate 会使 nodes 与倒排索引 desync。字段级变更走 update()。
@@ -176,7 +176,7 @@ export class Trace {
     return this.nodes;
   }
 
- /** 当前节点数。 */
+  /** 当前节点数。 */
   get length(): number {
     return this.nodes.length;
   }

package/src/orchestration/models/workflow-run.ts

@@ -62,7 +62,7 @@ export class WorkflowRun {
   runtime?: RunRuntime;
   meta: WorkflowRunMeta;
 
- /**
+  /**
  * 创建聚合根。初始状态 "running"（一次性生命周期：run 从创建起即在执行，
  * runtime 由紧随其后的 assignRuntime 注入）。也可传入 done 状态用于重水合
  * 已完成的 run（loadAll 后的只读聚合）。
@@ -82,15 +82,15 @@ export class WorkflowRun {
     this.spec = spec;
     this.state = state;
     this.meta = meta;
- // runtime 在构造时始终为 undefined——run 创建时无活 worker，loadAll 重水合
- // 时也不恢复 runtime（worker 必须由 lifecycle 重新 start）。
+    // runtime 在构造时始终为 undefined——run 创建时无活 worker，loadAll 重水合
+    // 时也不恢复 runtime（worker 必须由 lifecycle 重新 start）。
     this.runtime = undefined;
- // 构造期仅校验 I2（I1 跳过，见方法 doc）；I1 由 assignRuntime 末尾
- // validateInvariants 恢复。
+    // 构造期仅校验 I2（I1 跳过，见方法 doc）；I1 由 assignRuntime 末尾
+    // validateInvariants 恢复。
     this.validateInvariantI2();
   }
 
- /**
+  /**
  * 从持久化快照重水合聚合根。与构造函数同语义（构造期跳过 I1——持久化的
  * running 状态没有 worker，进程被杀后 worker 不可能还活着）。保留独立工厂
  * 标注重水合意图；调用方（D-4 kill-9 恢复）负责在 session_start 时把残留
@@ -102,15 +102,15 @@ export class WorkflowRun {
     return new WorkflowRun(runId, spec, state, meta);
   }
 
- // ── 不变式校验 ─────────────────────────────────────────────
+  // ── 不变式校验 ─────────────────────────────────────────────
 
- /**
+  /**
  * 校验不变式 I1 + I2。违反抛错（聚合根自我保护，fail-fast）。
  * 在每个 mutation 方法末尾调用（防御式编程 + 测试可断言）。
  */
   private validateInvariants(): void {
     this.validateInvariantI2();
- // I1: status==="running" ⟺ runtime!==undefined
+    // I1: status==="running" ⟺ runtime!==undefined
     if (this.state.status === "running" && this.runtime === undefined) {
       throw new Error(
         `WorkflowRun invariant I1 violated: status==="running" but runtime is undefined (runId=${this.runId})`,
@@ -123,7 +123,7 @@ export class WorkflowRun {
     }
   }
 
- /**
+  /**
  * 仅校验不变式 I2（done ⟹ reason）。构造期用——「创建即 running」与重水合的
  * running 快照都无 runtime（I1 构造期跳过），但 I2 必须保证（done 缺 reason 是真 bug）。
  */
@@ -135,9 +135,9 @@ export class WorkflowRun {
     }
   }
 
- // ── 状态机转换 ─────────────────────────────────────────────
+  // ── 状态机转换 ─────────────────────────────────────────────
 
- /**
+  /**
  * 状态机转换。合法转换：running→done。
  *
  * running 的进入不走 transition——构造即 running，replaceRuntime 保持 running。
@@ -151,7 +151,7 @@ export class WorkflowRun {
  * @throws 非法转换 / done 缺 reason / target==="running"
  */
   transition(target: RunStatus, reason?: DoneReason): void {
- // "running" 必须经 assignRuntime（需 runtime 参数，transition 无法提供）
+    // "running" 必须经 assignRuntime（需 runtime 参数，transition 无法提供）
     if (target === "running") {
       throw new Error(
         `WorkflowRun.transition: cannot transition to "running" directly — use assignRuntime() (runId=${this.runId})`,
@@ -164,15 +164,15 @@ export class WorkflowRun {
       );
     }
 
- // →done 需 reason（不变式 I2）
+    // →done 需 reason（不变式 I2）
     if (target === "done" && reason === undefined) {
       throw new Error(
         `WorkflowRun.transition: transition to "done" requires a reason (runId=${this.runId})`,
       );
     }
 
- // 副作用：先清理 runtime（releaseRuntime 守不变式 I1），再改 status
- // （canRunTransition 已排除 target==="running"，此处 target 恒为 "done"）
+    // 副作用：先清理 runtime（releaseRuntime 守不变式 I1），再改 status
+    // （canRunTransition 已排除 target==="running"，此处 target 恒为 "done"）
     this.releaseRuntime();
     this.state.status = target;
     this.state.reason = reason;
@@ -181,9 +181,9 @@ export class WorkflowRun {
     this.validateInvariants();
   }
 
- // ── Runtime 生命周期 ───────────────────────────────────────
+  // ── Runtime 生命周期 ───────────────────────────────────────
 
- /**
+  /**
  * 绑定 runtime（run 创建后注入执行资源）。
  *
  * 前置：status==="running" && runtime===undefined（runWorkflow 创建路径——
@@ -204,14 +204,14 @@ export class WorkflowRun {
         `WorkflowRun.assignRuntime: requires status==="running" (current: ${this.state.status}, runId=${this.runId})`,
       );
     }
- // 原子绑定：构造期 I1 处于跳过窗口（running 而 runtime undefined），设 runtime
- // 后末尾 validateInvariants 恢复 I1。调用方在 assignRuntime 后才对外注册
- // （lifecycle.runWorkflow 的 runs.set 后移），窗口外部不可见。
+    // 原子绑定：构造期 I1 处于跳过窗口（running 而 runtime undefined），设 runtime
+    // 后末尾 validateInvariants 恢复 I1。调用方在 assignRuntime 后才对外注册
+    // （lifecycle.runWorkflow 的 runs.set 后移），窗口外部不可见。
     this.runtime = rt;
     this.validateInvariants();
   }
 
- /**
+  /**
  * 解绑 runtime（done 时由 transition 调用，也可独立调用）。
  *
  * 前置：无（runtime===undefined 时 no-op，幂等）。
@@ -221,11 +221,11 @@ export class WorkflowRun {
     if (this.runtime === undefined) return;
     this.runtime.release("terminal");
     this.runtime = undefined;
- // 不改 status——调用方（transition）负责。独立调用时调用方需自行确保
- // status 一致（如 worker-error-retry 用 replaceRuntime 而非 release+assign）。
+    // 不改 status——调用方（transition）负责。独立调用时调用方需自行确保
+    // status 一致（如 worker-error-retry 用 replaceRuntime 而非 release+assign）。
   }
 
- /**
+  /**
  * 原地替换 runtime（G5-001：worker-error-retry）。
  *
  * 前置：status==="running"（G6-001：终态 run 拒绝重建）。
@@ -243,8 +243,8 @@ export class WorkflowRun {
         `WorkflowRun.replaceRuntime: requires status==="running" (current: ${this.state.status}, runId=${this.runId})`,
       );
     }
- // 原子替换：旧 runtime 释放（terminate+abort），新 runtime 绑定。
- // status 保持 "running"，runtime 全程 !== undefined，I1 不违反。
+    // 原子替换：旧 runtime 释放（terminate+abort），新 runtime 绑定。
+    // status 保持 "running"，runtime 全程 !== undefined，I1 不违反。
     if (this.runtime !== undefined) {
       this.runtime.release("terminal");
     }

package/src/orchestration/models/workflow-script.ts

@@ -60,10 +60,10 @@ export class WorkflowScript {
   readonly name: string;
   readonly source: WorkflowSource;
   readonly path: string;
- /** 原始文件内容（可编辑）。toExecutable 返回 strip 后的副本，不改本字段。 */
+  /** 原始文件内容（可编辑）。toExecutable 返回 strip 后的副本，不改本字段。 */
   sourceCode: string;
   readonly meta: WorkflowMeta;
- /** false 当 meta 提取失败（loader 不抛错，标记不可用但仍列出）。 */
+  /** false 当 meta 提取失败（loader 不抛错，标记不可用但仍列出）。 */
   available: boolean;
 
   constructor(opts: {
@@ -82,7 +82,7 @@ export class WorkflowScript {
     this.available = opts.available;
   }
 
- /**
+  /**
  * 静态检查脚本合法性。
  *
  * 委托 engine/script-lint.ts 的 lintScript——检查项含：
@@ -104,7 +104,7 @@ export class WorkflowScript {
     return result;
   }
 
- /**
+  /**
  * 返回可执行源。
  *
  * m2：不再 strip `export const meta`——meta 现为 @pi-meta 块注释（合法 JS，

package/src/orchestration/run-snapshot.ts

@@ -0,0 +1,266 @@
+// src/orchestration/run-snapshot.ts
+//
+// WorkflowRun 快照 codec（下沉收口 D4——设计件 subagent-core-sink-design.md U8）。
+//
+// 为什么需要它：WorkflowRun 的 JSONL 快照投影此前两宿主各写一份（core
+// file-run-store.ts 的 toSnapshot/fromSnapshot 与 pi 壳 jsonl-run-store.ts 的
+// serializeRun/deserializeRun）——字段集一致但语义细节分叉（live-strip、版本
+// guard、budgetRef 剔除），修一处漏一处。本模块收敛为单源 codec：字段演进
+// 单点（G2），两宿主（FileRunStore / pi JsonlRunStore）各自只保留 IO 策略
+// （rewrite/append/去抖），投影与版本衔接语义全部经此模块。
+//
+// 版本衔接三裁决（D4，含审查 MF-2）：
+// ① 版本值沿用 pi 现有字符串 "wf-run-v2"——pi 存量逐字节可读；
+// ② FileRunStore 存量行（无 v 字段）按「缺版本 = 当前版本」宽容读取，写入时
+//    补 v，不做自动迁移——「缺 v 宽容」实现于 FileRunStore 层预处理（读出的行
+//    先补缺省 v 再进 fromRunSnapshot），**不内聚进本 codec**：codec 层面缺 v
+//    即拒绝，保 pi 侧「v1 存量静默跳过」既有语义不被宽容化误读；
+// ③ guard 语义 = v 不匹配当前版本即拒（字符串版本无大小序，不引入比较逻辑）；
+//    「跳过 + warn」的可见性由宿主 store 层补（本 codec 只返回 undefined）。
+//
+// 序列化形态（键序即 JSON.stringify 输出序）逐键对齐 pi serializeRun 现网形态，
+// 使 pi 切换本 codec 后存量往返逐字节一致（⛔5）。
+
+import { AgentCall } from "./models/agent-call.ts";
+import { Budget } from "./models/budget.ts";
+import type { RunSpec } from "./models/run-spec.ts";
+import type {
+  RunStatus,
+  DoneReason,
+  WorkerLogEntry,
+  ExecutionTraceNode,
+  AgentCallOpts,
+  AgentResult,
+} from "./models/types.ts";
+import { Trace } from "./models/trace.ts";
+import { WorkflowRun } from "./models/workflow-run.ts";
+import type { WorkflowRunMeta } from "./models/workflow-run.ts";
+
+/**
+ * 快照格式版本（D4 裁决①：字符串相等比较，无大小序）。
+ *
+ * 版本历史（沿用 pi jsonl-run-store 口径）：
+ * - wf-run-v1：status 三态（含 paused）、meta 含 pausedAt（pi 旧格式，读路径拒绝）。
+ * - wf-run-v2（当前）：status 两态（running/done）、meta 无 pausedAt。
+ *
+ * 升级格式时 bump 此常量——旧版本快照经 fromRunSnapshot 返回 undefined，由
+ * 宿主 store 层决定跳过可见性（FileRunStore warn / pi 静默）。
+ */
+export const SNAPSHOT_VERSION = "wf-run-v2" as const;
+
+/** Budget 实例的可序列化投影（构造 opts 同形，重水合直接 new Budget(...)）。 */
+interface BudgetSnapshot {
+  maxTokens?: number;
+  maxCost?: number;
+  maxTimeMs?: number;
+  usedTokens: number;
+  usedCost: number;
+  totalCallCount: number;
+}
+
+/**
+ * AgentCall 实例的可序列化投影。traceNode 整体落盘（节点引用不可序列化，
+ * 落盘值拷贝；重水合后 D-10「引用共享」由 fromRunSnapshot 的 trace 回链尽力
+ * 恢复——Trace.fromArray 注释先例）。
+ */
+interface CallSnapshot {
+  id: number;
+  opts: AgentCallOpts;
+  status: "pending" | "running" | "done";
+  attempts: number;
+  result?: AgentResult;
+  sessionId?: string;
+  sessionFile?: string;
+  traceNode: ExecutionTraceNode;
+}
+
+/**
+ * WorkflowRun 的持久化快照形态（JSONL 单行，全量而非增量）。
+ *
+ * 形态与 pi 壳 jsonl-run-store.ts 的 RunSnapshot 同构（v 字段含内）——两宿主
+ * 存量互读的前提，任何字段增删必须同步两处并评估存量行。
+ */
+export interface RunSnapshot {
+  v: typeof SNAPSHOT_VERSION;
+  runId: string;
+  spec: RunSpec;
+  state: {
+    status: RunStatus;
+    reason?: DoneReason;
+    budget: BudgetSnapshot;
+    calls: CallSnapshot[];
+    trace: ExecutionTraceNode[];
+    errorLogs: WorkerLogEntry[];
+    error?: string;
+    scriptResult?: unknown;
+  };
+  meta: WorkflowRunMeta;
+}
+
+// ── 序列化 ──────────────────────────────────────────────────
+
+/**
+ * WorkflowRun → 单行快照。
+ *
+ * - 补 v 字段（D4 裁决②：写入恒带当前版本）。
+ * - strip live（防御内聚）：calls[].traceNode 与 trace 数组节点的 `live` 运行期
+ *   对象剥除——ExecutionRecord 含可变 turns[]/controller，不可序列化且跨进程
+ *   必死（重跑时由 dispatchAgentCall 重建）；strip 产出新对象，不 mutate 内存
+ *   中的 run（save 后 run 可继续跑）。
+ * - spec.budgetRef 剔除：父 Budget 共享引用是进程内优化（嵌套 workflow 预算
+ *   共享），非持久化数据；Budget 实例若混入 spec 落盘将退化为普通对象投影
+ *   （重水合后类型不符的脏字段）——重水合后 budget 从 state.budget 独立重建，
+ *   嵌套 run 的预算共享不跨进程存活。
+ * - runtime 不落盘（worker/controller/timer 不可序列化且跨进程必死——重水合
+ *   语义见 WorkflowRun.reconstruct 注释）。
+ */
+export function toRunSnapshot(run: WorkflowRun): RunSnapshot {
+  const { budgetRef: _budgetRef, ...spec } = run.spec;
+  return {
+    v: SNAPSHOT_VERSION,
+    runId: run.runId,
+    spec,
+    state: {
+      status: run.state.status,
+      reason: run.state.reason,
+      budget: {
+        maxTokens: run.state.budget.maxTokens,
+        maxCost: run.state.budget.maxCost,
+        maxTimeMs: run.state.budget.maxTimeMs,
+        usedTokens: run.state.budget.usedTokens,
+        usedCost: run.state.budget.usedCost,
+        totalCallCount: run.state.budget.totalCallCount,
+      },
+      calls: Array.from(run.state.calls.values(), (c) => {
+        // strip live（同 trace 序列化，不持久化运行期对象）
+        const { live: _live, ...traceNodeRest } = c.traceNode;
+        return {
+          id: c.id,
+          opts: c.opts,
+          status: c.status,
+          attempts: c.attempts,
+          result: c.result,
+          sessionId: c.sessionId,
+          sessionFile: c.sessionFile,
+          traceNode: traceNodeRest,
+        };
+      }),
+      // trace 节点浅拷贝时 strip live 字段
+      trace: run.state.trace.toArray().map(({ live: _live, ...rest }) => rest),
+      errorLogs: run.state.errorLogs,
+      error: run.state.error,
+      scriptResult: run.state.scriptResult,
+    },
+    meta: run.meta,
+  };
+}
+
+// ── 重水合 ──────────────────────────────────────────────────
+
+/** 「truthy 且 typeof object」——与原内联守卫 `!x || typeof x !== "object"` 拒绝集一致。 */
+function isPresentObject(v: unknown): v is object {
+  return !!v && typeof v === "object";
+}
+
+/** 通过形状校验的快照视图：顶层必填字段（v/runId/spec/state/meta）均已验存在。 */
+interface ValidatedSnapshot {
+  v: typeof SNAPSHOT_VERSION;
+  runId: string;
+  spec: RunSpec;
+  state: NonNullable<RunSnapshot["state"]>;
+  meta: WorkflowRunMeta;
+}
+
+/**
+ * 顶层形状校验（检查顺序与原内联守卫逐条一致）。
+ *
+ * 含 D4 裁决③ version guard（字符串相等，无大小序）：v 不等于当前版本即拒
+ * （含缺版本——「缺 v 宽容」是 FileRunStore 层预处理职责，不内聚进本 codec；
+ * pi 侧对 v1 存量行的静默跳过语义依赖此拒绝行为）。
+ */
+function isValidSnapshotShape(s: Partial<RunSnapshot>): s is ValidatedSnapshot {
+  if (s.v !== SNAPSHOT_VERSION) return false;
+  if (typeof s.runId !== "string" || !s.runId) return false;
+  if (!isPresentObject(s.spec)) return false;
+  const st = s.state;
+  if (!isPresentObject(st)) return false;
+  if (st.status !== "running" && st.status !== "done") return false;
+  if (!isPresentObject(st.budget)) return false;
+  if (!Array.isArray(st.calls) || !Array.isArray(st.trace)) return false;
+  if (!isPresentObject(s.meta)) return false;
+  return true;
+}
+
+/** call.traceNode → Trace 节点回链（D-10 尽力恢复，匹配不到退化为独立浅拷贝）。 */
+function linkTraceNode(c: CallSnapshot, trace: Trace): ExecutionTraceNode | undefined {
+  return (
+    trace.toArray().find((n) => n.stepIndex === c.traceNode?.stepIndex) ??
+    (c.traceNode ? { ...c.traceNode } : undefined)
+  );
+}
+
+/**
+ * 单条 CallSnapshot → AgentCall。残缺条目（非对象 / id 非数 / traceNode 缺失）
+ * 返回 undefined，由调用方跳过——不炸整个 run。
+ */
+function rehydrateCall(c: CallSnapshot, trace: Trace): AgentCall | undefined {
+  if (c === null || typeof c !== "object" || typeof c.id !== "number") return undefined;
+  const linked = linkTraceNode(c, trace);
+  if (!linked) return undefined;
+  const call = new AgentCall(c.id, c.opts, linked);
+  call.status = c.status;
+  call.attempts = c.attempts;
+  // Restore result directly — bypasses markRunning/markDone state-machine guards
+  // because we're reconstructing a known-good persisted state, not transitioning.
+  if (c.result !== undefined) call.result = c.result;
+  if (c.sessionId !== undefined) call.sessionId = c.sessionId;
+  if (c.sessionFile !== undefined) call.sessionFile = c.sessionFile;
+  return call;
+}
+
+function rehydrateCalls(snapshots: CallSnapshot[], trace: Trace): Map<number, AgentCall> {
+  const calls = new Map<number, AgentCall>();
+  for (const c of snapshots) {
+    const call = rehydrateCall(c, trace);
+    if (call) calls.set(c.id, call);
+  }
+  return calls;
+}
+
+/**
+ * 快照 → WorkflowRun 重水合。
+ *
+ * 版本 guard（D4 裁决③）：v 不等于当前版本即返回 undefined（含缺版本——
+ * 「缺 v 宽容」是 FileRunStore 层预处理职责，不内聚进本函数；pi 侧对 v1 存量
+ * 行的静默跳过语义依赖此拒绝行为）。
+ *
+ * 形状校验失败同样返回 undefined（调用方按损坏行处理，本函数不抛——唯一例外：
+ * done 快照缺 reason 触发 WorkflowRun I2 不变式抛错，属真 bug 不可吞）。
+ */
+export function fromRunSnapshot(snap: unknown): WorkflowRun | undefined {
+  if (snap === null || typeof snap !== "object") return undefined;
+  const s = snap as Partial<RunSnapshot>;
+  if (!isValidSnapshotShape(s)) return undefined;
+
+  // Trace 先重建：calls 的 traceNode 回链到 Trace 副本（D-10 尽力恢复——
+  // fromArray 拷贝节点，按 stepIndex 匹配使 call.traceNode 与 trace.nodes
+  // 共享同一副本引用；匹配不到（快照数据漂移）退化为独立浅拷贝，仅保构造不炸。
+  const trace = Trace.fromArray(s.state.trace);
+  const calls = rehydrateCalls(s.state.calls, trace);
+
+  return WorkflowRun.reconstruct(
+    s.runId,
+    s.spec,
+    {
+      status: s.state.status,
+      reason: s.state.reason,
+      budget: new Budget(s.state.budget),
+      calls,
+      trace,
+      errorLogs: Array.isArray(s.state.errorLogs) ? s.state.errorLogs : [],
+      error: s.state.error,
+      scriptResult: s.state.scriptResult,
+    },
+    s.meta,
+  );
+}