@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/orchestration/models/ports.ts

@@ -1,164 +0,0 @@
-/**
- * Workflow Extension — Engine Ports + 编排层共享类型
- *
- * 3 个注入 Port（AgentRunner / RunStore / WorkerHost）——Engine 定义、Infra 实现，
- * 是真需要 mock 测试的依赖（子进程/文件系统/线程）。
- *
- * 编排层共享类型（WorkerHandlers / LifecycleDeps）——打破 lifecycle ↔
- * error-recovery 循环依赖：2 个 engine 函数文件各自独立，共用同一组
- * 依赖签名（D-12）。
- *
- * 层归属：Engine。零 infra 依赖（AC-1）。
- */
-import type { StreamSink, SubagentStream } from "../../execution/stream-sink.ts";
-import type { AgentEvent } from "../../shared/agent-event.ts";
-import type { WorkerHandle } from "../worker-handle.ts";
-import type { RunSpec } from "./run-spec.ts";
-import type { AgentCallOpts, AgentResult } from "./types.ts";
-import type { WorkflowRun } from "./workflow-run.ts";
-
-// ── Port 1: AgentRunner ───────────────────────────────────────
-
-/**
- * Agent 子进程执行 port。Infra 实现：SubprocessAgentRunner。
- *
- * run 执行单次 agent 调用（委托 SubagentService.executeAndAwait），返回结构化结果。
- * signal 用于 abort 传播。
- *
- * onEvent（可选）：强类型 AgentEvent 回调，供调用方实时更新 live record 供 TUI 展示进度。
- * 不传则不回调（向后兼容；现有调用点不传不受影响）。
- *
- * D-005: onEvent 签名从 raw Record<string,unknown> 升级为 AgentEvent——委托后不再有
- * raw JSONL 中间层（executeAndAwait 直接出 AgentEvent，session-runner handleSdkEvent 出口）。
- */
-export interface AgentRunner {
-  run(opts: AgentCallOpts, signal: AbortSignal, onEvent?: (event: AgentEvent) => void, stream?: SubagentStream): Promise<AgentResult>;
-}
-
-// ── Port 2: RunStore ──────────────────────────────────────────
-
-/**
- * WorkflowRun 持久化 port。Infra 实现：JsonlRunStore。
- *
- * save 在每次状态变更后持久化整个 WorkflowRun（聚合根）；
- * loadAll 在 session_start 时重水合（D-5：JSONL 不向后兼容旧 session，旧格式返回空）。
- * stateFilePath 返回 run 状态文件的绝对路径（供 overlay/GUI 暴露给用户）。
- */
-export interface RunStore {
-  save(run: WorkflowRun): Promise<void>;
-  loadAll(): Promise<WorkflowRun[]>;
-  /** 返回 run 状态快照文件的绝对路径：<sessionDir>/workflow-state/<runId>.jsonl */
-  stateFilePath(runId: string): string;
-}
-
-// ── Port 3: WorkerHost ────────────────────────────────────────
-
-/**
- * Worker 线程启动 port。Infra 实现：WorkerHostImpl。
- *
- * start 创建一个 Worker thread 运行 workflow 脚本，返回 WorkerHandle。
- * handlers 绑定 message/error/exit 回调（见 WorkerHandlers）。
- */
-export interface WorkerHost {
-  start(
-    spec: RunSpec,
-    args: Record<string, unknown>,
-    handlers: WorkerHandlers,
-  ): WorkerHandle;
-}
-
-// ── 编排层共享类型 1: WorkerHandlers ───────────────────────────
-
-/**
- * Worker 线程事件回调集合——WorkerHost.start 的入参，由 lifecycle
- * 构造并注入。2 个 engine 文件（lifecycle / error-recovery）共用此签名，
- * 避免各自定义形状不一致的 handler bag（打破循环依赖）。
- *
- * 所有回调返回 Promise——允许 engine 层在回调内做 await persistState 等异步操作。
- */
-export interface WorkerHandlers {
- /** Worker → Main 的业务消息（agent-call / return / error / log）。 */
-  onMessage(raw: unknown): Promise<void>;
- /** Worker 线程 uncaught error。 */
-  onError(err: Error): Promise<void>;
- /** Worker 线程 exit（含 code，用于区分正常退出 vs 崩溃）。handle 用于竞态防护 G-025。 */
-  onExit(code: number, handle: WorkerHandle): Promise<void>;
-}
-
-// ── 编排层共享类型 2: LifecycleDeps ────────────────────────────
-
-/**
- * lifecycle / error-recovery 2 个 engine 函数文件的共同依赖 bag。
- *
- * 取代旧 4 个 Context factory（errorHandlerContext / agentCallContext /
- * budgetCallbacks / 旧 terminate bag，AC-2 目标）。函数签名 `(deps: LifecycleDeps, ...)`
- * 让每个 free function 自包含依赖，无需 God Facade 中介。
- *
- * - store: 持久化（RunStore port）
- * - workerHost: 启动 worker（WorkerHost port）
- * - runner: 执行 agent（AgentRunner port）
- * - runs: 内存中的活动 run 聚合根索引（runId → WorkflowRun），替代旧 6 张并行 map
- * - onRunDone?: run 到达 done 终态时的回调（C-4 修复，可选）。由 Interface 层
- * factory 注入（notifyDone —— 唤醒 parent agent 消费结果）。Engine 层不依赖
- * Pi SDK，通过 callback 把完成信号外推到 Interface 层。所有 transition("done", ...)
- * 路径（handleReturn / handleWorkerError / handleScriptError / abortRun /
- * dispatchAgentCall budget 终止）调完 transition + save 后触发本回调。
- */
-export interface LifecycleDeps {
-  store: RunStore;
-  workerHost: WorkerHost;
-  runner: AgentRunner;
-  runs: Map<string, WorkflowRun>;
- /** run 到达 done 终态时的回调（C-4 修复，可选）。Interface 层注入 notifyDone。 */
-  onRunDone?: (run: WorkflowRun) => void;
- /**
- * 跨扩展事件总线（pending-notifications register/unregister 信号灯）。
- *
- * runWorkflow 启动时 emit pending:register；所有 transition("done") 路径 emit
- * pending:unregister。两处均通过本端口（Engine 不直接依赖 Pi SDK）。可选——
- * 无 pending-notifications 扩展时 no-op（向后兼容）。
- */
-  eventBus?: { emit(channel: string, data: unknown): void };
- /**
- * 调试日志端口（Engine 不直接依赖 Pi SDK）。Interface 层注入实现。
- * 关键路径记录 run 启动、保存、pending 注册/注销，便于排查异步操作状态。
- */
-  log?: (level: "debug" | "info" | "warn" | "error", component: string, message: string, data?: unknown) => void;
- /**
- * D-12 regression fix (round-2 #2)：rebuildRuntime 重新调度 run 级墙钟预算计时器。
- *
- * worker/script 错误重试走 replaceRuntime，旧 RunRuntime 的 release 会 clearTimeout
- * 旧计时器（run-runtime.release）。新 runtime 必须重排 scheduleTimeBudget，否则带
- * budgetTimeMs 的 run 命中一次错误重试后时间预算静默失效（直到下次 pause/resume 才重排）。
- * 由 Interface 层 factory 注入——闭包捕获 deps，内部调 lifecycle.scheduleTimeBudget。
- *
- * 可选——旧测试 deps 不注入时 rebuildRuntime 不重排计时器（兼容，不影响无时间预算的 run）。
- */
-  scheduleTimeBudget?: (
-    runId: string,
-    budgetTimeMs: number,
-  ) => ReturnType<typeof setTimeout> | undefined;
- /**
- * workflow() 嵌套调用回调（可选）。Worker 脚本内调 workflow(name, args) 时触发。
- *
- * 由 Interface 层 makeDeps 注入（闭包捕获 registry + deps）。Engine 层的
- * error-recovery.handleWorkerMessage 收到 workflow-call 消息后调本回调，
- * 拿到子 workflow 执行结果后 postMessage(workflow-result) 回 worker。
- *
- * 不注入时 workflow() 返回 error result（向后兼容，不影响非嵌套场景）。
- */
-  onWorkflowCall?: (
-    name: string,
-    args: Record<string, unknown>,
-    parentRun: WorkflowRun,
-  ) => Promise<unknown>;
- /**
- * UI streaming sink（ctx.ui.setWidget），workflow agent call 创建 SubagentStream 用。
- *
- * 由 Interface 层 makeDeps 注入（从 SubagentService.getStreamSink() 取）。
- * dispatchAgentCall 用它创建 SubagentStream（widgetKey=subagent-stream-<runId>-<stepIndex>），
- * 使 workflow agent call 的 text_delta 走与 background subagent 相同的 streaming 链路。
- * 可选——无 UI 模式（TUI/RPC 无 setWidget）时为 undefined，dispatchAgentCall 不创建 stream。
- */
-  streamSink?: StreamSink;
-}

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

@@ -1,89 +0,0 @@
-/**
- * Workflow Extension — Run Runtime
- *
- * 聚合内运行时资源（仅 status==="running" 时存在）。技术资源聚合，
- * Engine 层类型，持 WorkerHandle / ConcurrencyGate 具体类（D-12 不造 interface）。
- *
- * 职责：封装一次 running-segment 的所有技术资源（worker 线程 + 并发信号量 +
- * abort controller），统一 release 入口（AC-2：单 release 替代多 boolean flag）。
- *
- * 一次性生命周期（G3-001）：runtime 释放后不再复用——AbortController 一次性
- * 语义决定 controller 无法跨释放复用，gate 队列也在 worker 重跑脚本 +
- * callCache replay 时清空无影响，所以整个 RunRuntime 重建。唯一注入路径：
- * assignRuntime（runWorkflow 创建）与 replaceRuntime（error-recovery 崩溃重试）。
- *
- * 参考：domain-models.md §10、clarification.md G3-001。
- */
-
-import { ConcurrencyGate } from "../concurrency-gate.ts";
-import { WorkerHandle } from "../worker-handle.ts";
-
-/**
- * release mode 枚举——调用方表达意图。
- *
- * 一次性生命周期后唯一语义：terminal（终局释放，worker + controller 全释放，
- * runtime 即被调用方丢弃）。原 "pause" 值已随 pause/resume 生命周期删除（F8）
- * ——release 后不存在「保留待恢复」的中间形态。
- */
-export type ReleaseMode = "terminal";
-
-// ── RunRuntime ───────────────────────────────────────────────
-
-export class RunRuntime {
- /** Worker 线程句柄。 */
-  readonly worker: WorkerHandle;
- /** 并发信号量。 */
-  readonly gate: ConcurrencyGate;
- /** per-running-segment AbortController（一次性，无法复用——G3-001）。 */
-  readonly controller: AbortController;
- /** Run 级墙钟时间预算计时器（spec.budgetTimeMs > 0 时由 lifecycle 调度，
-   * 到期 abortRun time_limited）。release 时清理，避免 abort/replaceRuntime
-   * 后孤儿计时器仍触发（rebuildRuntime 会重排一个全新的计时器，旧的不应残留）。 */
-  readonly timeBudgetTimer?: ReturnType<typeof setTimeout>;
- /** 防止 release 重复执行（幂等）。 */
-  private released = false;
-
-  constructor(
-    worker: WorkerHandle,
-    gate: ConcurrencyGate,
-    controller: AbortController,
-    timeBudgetTimer?: ReturnType<typeof setTimeout>,
-  ) {
-    this.worker = worker;
-    this.gate = gate;
-    this.controller = controller;
-    this.timeBudgetTimer = timeBudgetTimer;
-  }
-
- /**
- * 释放所有资源：terminate worker + abort controller。
- *
- * 幂等——重复调用安全（第二次起 no-op，released flag 守卫）。
- * 调用后此 RunRuntime 应被调用方丢弃（WorkflowRun.runtime = undefined），
- * 崩溃重试时由 replaceRuntime 注入新实例（G3-001）。
- *
- * worker.terminate 本身幂等，controller.abort 本身幂等
- * （重复 abort 无副作用），但 released flag 让本方法语义更明确：
- * 「释放过一次的 runtime 不再释放第二次」。
- *
- * @param mode terminal —— 终局释放（唯一值，保留参数为调用方语义显式化）
- */
-  release(_mode: ReleaseMode): void {
-    if (this.released) return;
-    this.released = true;
- // 清理 run 级时间预算计时器——abort/terminate/replaceRuntime 后它不应再触发
- // （rebuildRuntime 会重排全新计时器；孤儿触发会把已终态的 run 误转 done）。
-    if (this.timeBudgetTimer) clearTimeout(this.timeBudgetTimer);
- // worker.terminate 异步但幂等——不 await（release 是同步签名，调用方
- // 不应被底层线程关闭阻塞；worker 收到 terminate 后自行清理）。
-    void this.worker.terminate();
- // controller.abort 触发 listener（kill agent subprocess、中止在飞调用）。
- // 一次性语义——已 aborted 的 controller 重复 abort 无副作用。
-    this.controller.abort();
-  }
-
- /** 是否已 release（测试 + 诊断用）。 */
-  get isReleased(): boolean {
-    return this.released;
-  }
-}

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

@@ -1,83 +0,0 @@
-/**
- * Workflow Extension — RunSpec 值对象
- *
- * 单次 workflow run 的不可变规格（domain-models.md §2）。
- *
- * 设计：
- * - 全部字段 readonly——run 一旦创建，规格不可改（状态变化走 RunState）
- * - scriptSource 是已 strip `export const meta` 的可执行源（WorkflowScript.toExecutable）
- * - budgetTokens/budgetTimeMs 是上限（可选，未设 = 不限制）
- *
- * 层归属：Engine。
- *
- * 参考：domain-models.md §2。
- */
-
-import type { Budget } from "./budget.ts";
-
-/**
- * RunSpec——一次 workflow run 的不可变输入规格。
- *
- * 作为 RunStore 持久化的一部分（WorkflowRun.spec），崩溃恢复重水合后
- * 需要 scriptSource/args 重建 worker（G3-001）。
- */
-export interface RunSpec {
- /** 已 strip export 的可执行源（WorkflowScript.toExecutable 产物）。 */
-  readonly scriptSource: string;
- /**
- * 参数契约（JSON Schema draft-07，来自 script.meta.parameters 整对象透传，m3 DM2）。
- *
- * undefined = 不校验（安全退化——漏拷 parameters 退化是「不校验」非「校验错」）。
- * 由调用方（actionRun/runAndWait/executeNestedWorkflow）从 script.meta.parameters 拷贝。
- * lifecycle.runWorkflow 首行经 validateRunArgs 校验 spec.args（coerceTypes 原地规范化
- * args 对象内容，字段引用不变；worker 启动与崩溃重建共用同一对象）。
- */
-  readonly parameters?: Record<string, unknown>;
-  /** 调用方传入的参数（worker 内通过 $ARGS 访问）。 */
-  readonly args: Record<string, unknown>;
- /**
- * Run 级 model override（Option B：经 workerData → worker global $MODEL → agent() fallback）。
- *
- * undefined = 继承主 agent 模型（零配置默认）。设置时该 run 内所有 agent() 调用默认继承
- * （除非 per-call 显式指定 model）。注意：不 merge 进 args（对称单路径注入），
- * 而是经 worker-script-builder 注入为 $MODEL worker global。
- */
-  readonly model?: string;
- /**
- * Run 级 thinkingLevel override（Option B：经 workerData → worker global $THINKING_LEVEL）。
- *
- * undefined = 继承主 agent thinkingLevel。取值范围由 THINKING_ORDER SSOT 派生（含 max）。
- */
-  readonly thinkingLevel?: string;
- /** Token 预算上限（未设或 0 = 不限制，见 Budget 守卫）。 */
-  readonly budgetTokens?: number;
- /** 时间预算上限（ms，wall-clock，由 lifecycle.scheduleTimeBudget 调度）。 */
-  readonly budgetTimeMs?: number;
- /**
- * 父 Budget 共享引用（嵌套 workflow() 时由 executeNestedWorkflow 传入）。
- *
- * 设置时 lifecycle.runWorkflow 直接复用此 Budget 实例，而非 new 一个独立 Budget——
- * 子 run 的 consume 直接反映到父 Budget，消除并行嵌套下的超支窗口（F-7 方案 B）。
- * 顶层 run 无此字段（budgetTokens 走独立 Budget 构造）。
- */
-  readonly budgetRef?: Budget;
- /** 脚本名（meta.name 或文件名 stem）。 */
-  readonly scriptName: string;
- /**
- * Run 级简短标签（≤20 字符），区别于 scriptName（脚本身份名）。
- * 区分同脚本的不同 run 实例（如 'migrate-users-batch1' vs 'migrate-users-batch2'）。
- * 旧持久化 run 缺失时为 undefined，渲染时回落 scriptName。
- */
-  readonly slug?: string;
- /** 脚本文件绝对路径（用于诊断/日志）。 */
-  readonly scriptPath: string;
- /** 人类可读描述（meta.description）。 */
-  readonly description?: string;
- /**
- * 父 workflow 调用链（嵌套 workflow() 时自动填充，循环检测用）。
- *
- * 顶层 run 无此字段。子 run 的 chain = [...parentChain, parentScriptName]。
- * executeNestedWorkflow 检查目标 name 是否已在 chain 中，防止 A→B→A 死循环。
- */
-  readonly parentWorkflowChain?: readonly string[];
-}

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

@@ -1,44 +0,0 @@
-/**
- * Workflow Extension — RunState 值对象
- *
- * 单次 workflow run 的可持久化状态（domain-models.md §3）。
- *
- * 设计：
- * - status/reason/budget/calls/trace/errorLogs 是可变字段（运行中持续更新）
- * - error/scriptResult 仅终态有值（done 时）
- * - 与 RunSpec 的区别：RunSpec 不可变（输入），RunState 可变（执行快照）
- *
- * 层归属：Engine。
- *
- * 参考：domain-models.md §3。
- */
-
-import type { AgentCall } from "./agent-call.ts";
-import type { Budget } from "./budget.ts";
-import type { Trace } from "./trace.ts";
-import type { DoneReason, RunStatus, WorkerLogEntry } from "./types.ts";
-
-/**
- * RunState——一次 run 的可持久化执行状态。
- *
- * 持久化由 RunStore.save(WorkflowRun) 触发（WorkflowRun 持 RunState）。
- * 跨进程重启时 RunState 从 JSONL 重水合（callCache 保留，worker 由崩溃恢复重建）。
- */
-export interface RunState {
- /** 当前状态（running/done）。 */
-  status: RunStatus;
- /** 终态原因（done 时必有）。 */
-  reason?: DoneReason;
- /** Token/cost 预算（含 usedTokens/usedCost 累积）。 */
-  budget: Budget;
- /** 按 callId 索引的 agent 调用集合（含 result，跨 runtime 重建存活——callCache replay）。 */
-  calls: Map<number, AgentCall>;
- /** 执行追踪事件流（唯一来源 D-10）。 */
-  trace: Trace;
- /** Worker console.* 捕获条目（run 级诊断，仅展示在 TUI widget）。 */
-  errorLogs: WorkerLogEntry[];
- /** done && reason !== completed 时可有（失败/中止/预算超限的原因）。 */
-  error?: string;
- /** done && reason === completed 时有（脚本 execute 返回值）。 */
-  scriptResult?: unknown;
-}

package/src/orchestration/models/trace.ts

@@ -1,183 +0,0 @@
-/**
- * Workflow Extension — Trace 值对象
- *
- * 执行追踪事件流（D-10 单一来源）。纯 append-only + 单字段 update。
- *
- * 设计：
- * - trace 节点存储 + 变更逻辑收敛为值对象（外部不能直接打洞 nodes 数组）。
- * - update 只改单个 node 的 status/result/error/completedAt/sessionId（TracePatch）。
- * - callId 不存在时 update no-op（防御性，避免 race 下抛错）。
- * - 持久化（appendEntry）与事件通知（emit）不在本值对象内——它们由 engine 函数
- * 在调用 update 前后负责（值对象只管数据形状，不管 IO）。
- *
- * 层归属：Engine。
- *
- * 参考：domain-models.md §6（字段/不变式）。
- */
-import type { AgentResult, ExecutionTraceNode, TracePatch } from "./types.ts";
-
-// ── result.content 裁剪 ────────────────────────────────────────
-
-/**
- * trace 节点 result.content 裁剪上限（严格大于才裁）。
- *
- * export 供测试边界构造（对齐 budget.ts export 常量先例）。
- * 只裁 trace 节点侧——AgentCall.result 不裁（markDone 存全量在前，
- * worker cached replay 数据源保真）。
- */
-export const TRACE_RESULT_MAX_CHARS = 8000;
-
-/**
- * 裁剪保留的头/尾长度（各半）。
- *
- * 耦合声明：TRIM_HEAD_CHARS + TRIM_TAIL_CHARS === TRACE_RESULT_MAX_CHARS
- * （各半相等）是 doc 示例「8001 → 裁后 8000+标记 ≈ 8057」的前提
- * （rt-w1-design.json W1C2 / trimTraceResult 注释同款表述）——改 MAX 时
- * 需同步检查 head/tail 是否仍各半，及上述注释/文档示例数字。
- * 比例钉死在 trace.test.ts 断言中；变更需复查 detail-content.ts
- * 尾 5 行消费点（TUI 尾部预览依赖 tail 段）。
- */
-const TRIM_HEAD_CHARS = 4000;
-const TRIM_TAIL_CHARS = 4000;
-
-/**
- * 裁剪 trace result 的 content（Trace 私有纯函数）。
- *
- * - undefined 透传；未超限原引用透传（零拷贝，不超限路径行为与无裁剪时一致）。
- * - 超限返回新对象：head + 含原始长度的标记 + tail（只裁 content，
- *   result 其他字段浅拷贝保留）。节点持裁剪副本，与传入对象脱钩。
- * - 边界附近（如 8001 字符）裁后总长 8000 + 标记长度 > 原始长度属
- *   既定语义（head/tail 固定比例下净增长有界），禁止自行缩短 head/tail。
- */
-function trimTraceResult(result: AgentResult | undefined): AgentResult | undefined {
-  if (result === undefined) return result;
-  const { content } = result;
-  if (content.length <= TRACE_RESULT_MAX_CHARS) return result;
-  const trimmed =
-    content.slice(0, TRIM_HEAD_CHARS) +
-    `\n…[trace result truncated, original ${content.length} chars]…\n` +
-    content.slice(-TRIM_TAIL_CHARS);
-  return { ...result, content: trimmed };
-}
-
-/**
- * Trace 值对象（事件流，唯一来源 D-10）。
- *
- * 不变式：
- * - nodes 只增不改索引顺序（append-only）
- * - update 只改单个 node 的 status/result/error/completedAt/sessionId
- * - byIndex 与 nodes 恒一致（每个 append/remove 同步维护，无惰性重建）；
- *   Map 值与数组元素引用共享（非拷贝），nodes 仍是持久化与 TUI 投影 SSOT
- * - 不含 verifyStrategy（G-020 删除，不迁移）
- */
-export class Trace {
-  private readonly nodes: ExecutionTraceNode[] = [];
-  /** stepIndex 倒排索引（查询加速 O(1)；值与 nodes 元素引用共享）。 */
-  private readonly byIndex = new Map<number, ExecutionTraceNode>();
-
- /**
- * 从已有节点数组重建 Trace（用于 RunStore 反序列化重水合）。
- *
- * 防御性拷贝——传入数组不被持有，外部 mutation 不影响 Trace。
- * 不验证节点顺序/唯一性（调用方保证快照来源可信）。
- * 不做裁剪——落盘快照已是 write 路径裁剪后形态，旧版本未裁剪长
- * content 重水合保持原样（read 路径无二次信息损失）。
- * 重水合后 call.traceNode（来自快照 calls[].traceNode，
- * jsonl-run-store.ts:156 直接传入）与 Trace.nodes 副本非同引用——
- * D-10 引用共享仅 live append 路径成立。
- */
-  static fromArray(nodes: readonly ExecutionTraceNode[]): Trace {
-    const trace = new Trace();
-    for (const node of nodes) {
-      const copy = { ...node };
-      trace.nodes.push(copy);
-      trace.byIndex.set(copy.stepIndex, copy); // 重复 stepIndex last-wins
-    }
-    return trace;
-  }
-
- /**
- * Append a trace node（append-only，不改已有节点）。
- *
- * 入口裁剪：超长 result.content 先 mutate 入参节点的 result 字段，
- * 再 push 原节点引用（禁止 push 副本——保持 AgentCall.traceNode 与
- * Trace.nodes 共享同一引用的 D-10 不变式）。
- */
-  append(node: ExecutionTraceNode): void {
-    node.result = trimTraceResult(node.result);
-    this.nodes.push(node);
-    this.byIndex.set(node.stepIndex, node);
-  }
-
- /**
- * Update a trace node by stepIndex (callId) with a partial patch.
- *
- * 只改 patch 中提供的字段（status/result/error/completedAt/sessionId）。
- * stepIndex 不存在时 no-op（防御性——agent 完成/失败回调可能晚于 run 终止到达）。
- */
-  update(stepIndex: number, patch: TracePatch): void {
-    const node = this.findByStepIndex(stepIndex);
-    if (!node) return; // no-op: 不存在不抛错（D-10 防御性）
-
-    if (patch.status !== undefined) node.status = patch.status;
-    // 入口裁剪：节点持裁剪副本，与 patch.result 脱钩为两个对象
-    // （call.result 保留全量——replay 数据源保真）。patch.result 未提供不动。
-    if (patch.result !== undefined) node.result = trimTraceResult(patch.result);
-    if (patch.error !== undefined) node.error = patch.error;
-    if (patch.completedAt !== undefined) node.completedAt = patch.completedAt;
-    if (patch.sessionId !== undefined) node.sessionId = patch.sessionId;
-    if (patch.sessionFile !== undefined) node.sessionFile = patch.sessionFile;
-  }
-
- /**
- * 查找指定 stepIndex 的节点（byIndex O(1)，trace 中 stepIndex 应唯一）。
- *
- * 语义差异声明（旧线性扫 first-match → Map last-wins）：仅在破坏
- * stepIndex 唯一性的违规使用下可见，两组场景——
- * 1. 重复 append 同 stepIndex 且未 remove：返回最后一个节点（last-wins；
- *    旧线性扫 first-match 会返回第一个）。
- * 2. 重复 append 后 removeByStepIndex：remove 的 findIndex 命中首个旧节点
- *    splice，而 byIndex.delete 把整个 stepIndex 键删掉——nodes 残留第二个
- *    节点成为孤儿（find/update 不可达，length/toArray 仍可见）。
- * 合法路径无差异：唯一性由 discard 先 remove 再 append 保证（W1TC12 锚定）。
- */
-  private findByStepIndex(stepIndex: number): ExecutionTraceNode | undefined {
-    return this.byIndex.get(stepIndex);
-  }
-
- /** 按节点引用删除（仅用于测试或 run 重建场景；正常运行不调用）。 */
-  find(stepIndex: number): ExecutionTraceNode | undefined {
-    return this.findByStepIndex(stepIndex);
-  }
-
- /**
- * 按 stepIndex 移除节点（崩溃重建清理在飞 call 用）。
- *
- * 正常运行不调用（append-only 不变式）。仅 error-recovery 的 discardInFlightCalls
- * （rebuildRuntime 内，F2）清理被旧 runtime abort 的在飞 call 时用——移除其 trace
- * 节点，让重跑重发 agent-call 时 append 全新节点走全新执行路径（避免 stale
- * "running" 节点残留 + trace.update 命中旧节点导致新节点 orphan）。
- * stepIndex 不存在时 no-op（防御性）。
- */
-  removeByStepIndex(stepIndex: number): void {
-    // 先 findIndex 判存在再删，避免 byIndex 与 nodes 漂移
-    const idx = this.nodes.findIndex((n) => n.stepIndex === stepIndex);
-    if (idx === -1) return;
-    this.nodes.splice(idx, 1);
-    this.byIndex.delete(stepIndex);
-  }
-
- /**
- * readonly 视图——返回内部 nodes 数组引用（仅类型级 readonly，运行时无
- * 防御）。消费方禁止结构化 mutate（push/splice/重排/覆盖元素）：byIndex
- * 引入后外部结构化 mutate 会使 nodes 与倒排索引 desync。字段级变更走 update()。
- */
-  toArray(): readonly ExecutionTraceNode[] {
-    return this.nodes;
-  }
-
- /** 当前节点数。 */
-  get length(): number {
-    return this.nodes.length;
-  }
-}