@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/orchestration/models/budget.ts

@@ -46,7 +46,7 @@ export class Budget {
   readonly maxTimeMs?: number;
   usedTokens = 0;
   usedCost = 0;
- /** 总调用计数（持久化/诊断用；execute-agent-call 每次 dispatch 后 increment）。 */
+  /** 总调用计数（持久化/诊断用；execute-agent-call 每次 dispatch 后 increment）。 */
   totalCallCount = 0;
 
   constructor(opts: {
@@ -65,7 +65,7 @@ export class Budget {
     this.totalCallCount = opts.totalCallCount ?? 0;
   }
 
- /**
+  /**
  * 累加一次 agent 调用的 usage（加权口径）。
  *
  * 四项 token 按各自权重（INPUT/CACHE_READ/CACHE_WRITE/OUTPUT_WEIGHT）折算后求和，
@@ -84,12 +84,12 @@ export class Budget {
     this.usedCost += numOrZero(usage.cost);
   }
 
- /** 累加调用计数（每次 agent dispatch 后调用；持久化快照同步）。 */
+  /** 累加调用计数（每次 agent dispatch 后调用；持久化快照同步）。 */
   incrementCallCount(): void {
     this.totalCallCount += 1;
   }
 
- /**
+  /**
  * 是否超 token / cost 预算（FR-3）。
  *
  * maxTokens===0 或 undefined 视为不限制（守卫）；
@@ -105,7 +105,7 @@ export class Budget {
     return this.maxCost !== undefined && this.maxCost > 0 && this.usedCost >= this.maxCost;
   }
 
- /**
+  /**
  * 剩余 token 预算。maxTokens 未设或 ≤0 时返回 undefined（视为不限制）。
  *
  * 嵌套 workflow() 调用时由 executeNestedWorkflow 消费：子 run 的 budgetTokens

package/src/orchestration/models/ports.ts

@@ -5,7 +5,7 @@
  * 是真需要 mock 测试的依赖（子进程/文件系统/线程）。
  *
  * 编排层共享类型（WorkerHandlers / LifecycleDeps）——打破 lifecycle ↔
- * error-recovery 循环依赖：2 个 engine 函数文件各自独立，共用同一组
+ * worker-message-pump 循环依赖：2 个 engine 函数文件各自独立，共用同一组
  * 依赖签名（D-12）。
  *
  * 层归属：Engine。零 infra 依赖（AC-1）。
@@ -71,7 +71,7 @@ export interface WorkerHost {
 
 /**
  * Worker 线程事件回调集合——WorkerHost.start 的入参，由 lifecycle
- * 构造并注入。2 个 engine 文件（lifecycle / error-recovery）共用此签名，
+ * 构造并注入。2 个 engine 文件（lifecycle / worker-message-pump）共用此签名，
  * 避免各自定义形状不一致的 handler bag（打破循环依赖）。
  *
  * 所有回调返回 Promise——允许 engine 层在回调内做 await persistState 等异步操作。
@@ -88,7 +88,7 @@ export interface WorkerHandlers {
 // ── 编排层共享类型 2: LifecycleDeps ────────────────────────────
 
 /**
- * lifecycle / error-recovery 2 个 engine 函数文件的共同依赖 bag。
+ * lifecycle / worker-message-pump 2 个 engine 函数文件的共同依赖 bag。
  *
  * 取代旧 4 个 Context factory（errorHandlerContext / agentCallContext /
  * budgetCallbacks / 旧 terminate bag，AC-2 目标）。函数签名 `(deps: LifecycleDeps, ...)`
@@ -142,7 +142,7 @@ export interface LifecycleDeps {
  * workflow() 嵌套调用回调（可选）。Worker 脚本内调 workflow(name, args) 时触发。
  *
  * 由 Interface 层 makeDeps 注入（闭包捕获 registry + deps）。Engine 层的
- * error-recovery.handleWorkerMessage 收到 workflow-call 消息后调本回调，
+ * worker-message-pump.handleWorkerMessage 收到 workflow-call 消息后调本回调，
  * 拿到子 workflow 执行结果后 postMessage(workflow-result) 回 worker。
  *
  * 不注入时 workflow() 返回 error result（向后兼容，不影响非嵌套场景）。

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

@@ -7,11 +7,11 @@
  * 职责：封装一次 running-segment 的所有技术资源（worker 线程 +
  * abort controller），统一 release 入口（AC-2：单 release 替代多 boolean flag）。
  * （旧并发门闩 gate 抽象已删——no-op，实际并发由 SubagentService ConcurrencyPool 管理；
- * 原 withSlot 的 pre-abort 检查内联到 error-recovery dispatchAgentCall。）
+ * 原 withSlot 的 pre-abort 检查内联到 worker-message-pump dispatchAgentCall。）
  *
  * 一次性生命周期（G3-001）：runtime 释放后不再复用——AbortController 一次性
  * 语义决定 controller 无法跨释放复用，所以整个 RunRuntime 重建。唯一注入路径：
- * assignRuntime（runWorkflow 创建）与 replaceRuntime（error-recovery 崩溃重试）。
+ * assignRuntime（runWorkflow 创建）与 replaceRuntime（worker-message-pump 崩溃重试）。
  *
  * 参考：domain-models.md §10、clarification.md G3-001。
  */
@@ -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,15 +145,15 @@ 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
+ * 正常运行不调用（append-only 不变式）。仅 worker-message-pump 的 discardInFlightCalls
  * （rebuildRuntime 内，F2）清理被旧 runtime abort 的在飞 call 时用——移除其 trace
  * 节点，让重跑重发 agent-call 时 append 全新节点走全新执行路径（避免 stale
  * "running" 节点残留 + trace.update 命中旧节点导致新节点 orphan）。
@@ -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/types.ts

@@ -13,7 +13,7 @@
  * 层归属：Engine（数据结构 + 不变式守卫）。
  */
 
-import type { ExecutionRecord } from "../../execution/types.ts";
+import type { ExecutionRecord, WorktreeHandle } from "../../execution/types.ts";
 
 // ── 状态机 ────────────────────────────────────────────────────
 
@@ -65,7 +65,37 @@ export function canRunTransition(from: RunStatus, to: RunStatus): boolean {
 // ── Agent 调用 ────────────────────────────────────────────────
 
 /**
- * 单次 agent 调用的输入选项。
+ * slug 最大长度（D6 合流迁入本文件，原权威定义在已删除的 execution/execute-options-mapper.ts）。
+ * 历史值 20 偏紧——描述性 slug 如 "audit-structured-output"（23）/ "fix-subagent-wf-tools"（21）
+ * 会撞上限，放宽到 35 兼顾「短到能塞进 TUI 标题行」与「容纳合理描述性 kebab-case 名」。
+ * 放本文件的原因：约束对象是 AgentCallOpts.description（slug 的源字段，见下方 slug 派生说明），
+ * 与字段同文件；worker-message-pump（live record slug 截断）与壳侧 tool schema maxLength 共享引用。
+ */
+export const SLUG_MAX_LENGTH = 35;
+
+/**
+ * 单次 agent 调用的任务声明（D6 任务形状合流后的单一形状）。
+ *
+ * [D6 合流裁决] 本类型 = 原 AgentCallOpts（workflow 调用方声明，18 字段）与原
+ * AgentTaskSpec（engine 中立任务声明，已删除）的合流形态，从模型脚本 agent() API
+ * 到 EnginePort.run 直达 pi 边界一次映射——SAR 链路上的 ExecuteOptions/AgentTaskSpec
+ * 中间态消除（设计 docs/design/subagent-dual-track-convergence.md §3.3 D6 / 终态四）。
+ *
+ * 终态命名按变化轴裁定为 AgentCallOpts，理由：
+ *   - 字段演进的首要驱动轴是「调用方要表达的任务语义」（agent() API 是唯一生产写入方，
+ *     合流字段中 prompt/description/skill/skillPath/schemaEnv/thinkingLevel 等多数派
+ *     已是调用方命名）；
+ *   - 原 AgentTaskSpec 的中立重命名层（task/slug/effort/persona）与调用方命名是
+ *     形式同构、语义同构的假差异（prompt≡task、slug=description 截断、effort≡thinkingLevel、
+ *     persona≡skillPath+appendSystemPrompt 平铺），按「消假差异」原则并入调用方命名；
+ *   - 持久化兼容反向锁定 prompt 形态：jsonl run 快照的 AgentCall.opts 与 worker 消息
+ *     opts 均以 prompt 字段落盘，改名会破坏旧快照重水合。
+ *
+ * 引擎中立字段的并入方式（可选字段，原 AgentTaskSpec 独有字段去向）：
+ *   - graceTurns / conversation / idleTimeoutMs / denyTools / permissionMode：可选并入；
+ *   - persona.agentRef：裁撤（无生产写入方、无消费者——pi 走 agent 字段解析身份）；
+ *   - requires：裁撤（P4 形状预留、无生产写入方；且并入需 import EngineCapabilities
+ *     形成 orchestration↔engine 类型环）。将来能力依赖声明下钻时在本形状上加回。
  *
  * D-12 仅重组执行编排，AgentCallOpts 形状保持兼容。
  */
@@ -101,14 +131,20 @@ export interface AgentCallOpts {
  */
   timeoutMs?: number;
  /**
- * Turn 上限（turn limiter 用）。
- *
- * [预算语义对齐] 未传或 <=0 = 不限 turn；此时也不按 turns 估算 spawn watchdog——
- * 仅当 env XYZ_SUBAGENT_SPAWN_WATCHDOG_MS 设置时才按绝对时限挂 watchdog（见
- * session-runner.resolveSpawnWatchdogMs）。mapToExecuteOptions 原样透传到
- * ExecuteOptions.maxTurns → 引擎 task-spec → runSpawn。
- */
+  * Turn 上限（turn limiter 用）。
+  *
+  * [预算语义对齐] 未传或 <=0 = 不限 turn；此时也不按 turns 估算 spawn watchdog——
+  * 仅当 env XYZ_SUBAGENT_SPAWN_WATCHDOG_MS 设置时才按绝对时限挂 watchdog（见
+  * session-runner.resolveSpawnWatchdogMs）。pi 边界直出为 ExecuteOptions.maxTurns
+  * → runSpawn（D6 合流后无中间映射层）。
+  */
   maxTurns?: number;
+ /**
+  * Turn limiter 的宽限轮数（原 AgentTaskSpec.graceTurns 并入）：超 maxTurns 后
+  * 允许继续的轮数（等待在途工具收尾）。pi 引擎消费；workflow agent() 无写入方，
+  * chat 域（ExecuteOptions.graceTurns 同名透传）经 host-task-spec 填充。
+  */
+  graceTurns?: number;
  /**
  * Skill name to load (e.g. "code-review"). Resolved to SKILL.md path
  * and injected via --skill flag in the subprocess.
@@ -129,18 +165,18 @@ export interface AgentCallOpts {
  */
   agent?: string;
  /**
- * System prompt injection CONTENT (not file paths).
- * Set by agent-opts-resolver: schema structured-output instruction string.
- * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
- * mapToExecuteOptions passes this through to ExecuteOptions.appendSystemPrompt
- * (same name/semantics, transparent passthrough).
- */
+  * System prompt injection CONTENT (not file paths).
+  * Set by agent-opts-resolver: schema structured-output instruction string.
+  * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
+  * pi 边界直出为 ExecuteOptions.appendSystemPrompt（同名同义透传，D6 合流后无中间映射层）。
+  */
   appendSystemPrompt?: string[];
  /**
- * Schema JSON for PI_WORKFLOW_SCHEMA env var.
- * Set by agent-opts-resolver when opts.schema is present; passed as env var
- * to activate the structured-output tool + hook.
- */
+  * Schema JSON for PI_WORKFLOW_SCHEMA env var.
+  * Set by agent-opts-resolver when opts.schema is present (值 = stringifySchemaCached
+  * compact，与 schema 派生等值); passed as env var to activate the structured-output
+  * tool + hook. pi 边界直出时 schema 派生优先、本字段兜底（解耦形态通道，生产不可达）。
+  */
   schemaEnv?: string;
  /**
  * Per-call 工作目录（ADR-029 决策 1）。传给 child_process.spawn 的 cwd option。
@@ -159,11 +195,36 @@ export interface AgentCallOpts {
    * agent() → execute-agent-call → SAR 路由层。
    */
   engine?: string;
-  /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
-  worktree?: boolean;
+  /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork.
+   * [D6 合流] 类型扩展为 boolean | WorktreeHandle（原 AgentTaskSpec.worktree 的超集）——
+   * WorktreeHandle 形态仅在 chat 域（复用外部已创建的 worktree）出现，workflow agent()
+   * 恒传 boolean。 */
+  worktree?: boolean | WorktreeHandle;
   /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.
-   * Worker-layer flag only — not forwarded to ExecuteOptions (mapToExecuteOptions drops it). */
+   * Worker-layer flag only — not consumed by any engine (dropped at the pi boundary). */
   returnMeta?: boolean;
+ /**
+  * 可持续对话模式（原 AgentTaskSpec.conversation 并入）：true = record 标记 chatMode，
+  * 轮次完成进 idle 态等待 message 续聊。chat 域（ExecuteOptions.conversation 同名）经
+  * host-task-spec 填充；workflow agent() 无写入方。
+  */
+  conversation?: boolean;
+ /**
+  * 空闲超时毫秒数（原 AgentTaskSpec.idleTimeoutMs 并入，仅 conversation 模式有意义）。
+  * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms；显式 0/负 = 禁用
+  * idle GC。chat 域经 host-task-spec 填充。
+  */
+  idleTimeoutMs?: number;
+ /**
+  * 工具 denylist（原 AgentTaskSpec.denyTools 并入，中立新增面）：各引擎做语法映射
+  * （zcode buildZcodeArgv 消费；pi 链路暂无对应面）。无 workflow 写入方，预留形状。
+  */
+  denyTools?: string[];
+ /**
+  * 中立权限模式（原 AgentTaskSpec.permissionMode 并入，预留形状）：映射按各引擎
+  * capabilities.permissionMode。无生产写入方/消费者。
+  */
+  permissionMode?: string;
 }
 
 /**
@@ -189,6 +250,24 @@ export interface ToolCallEntry {
   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";
+
 /**
  * 单次 agent 调用的结果（统一形态）。
  *
@@ -199,6 +278,16 @@ export interface AgentResult {
  /** Raw text output from the agent. */
   content: string;
  /**
+ * [D5-③] 失败分诊结构化标签（AgentFailureKind）。产出侧唯一识别点 =
+ * execution/engine/engines/pi/output-collector.ts（collectResult 对最终 error
+ * 分类后写入，经 agent-result-mapper / AgentOutcome 透传到本形态）；消费侧
+ * execute-agent-call 读本字段分诊，不再扫 error 文案子串。
+ *
+ * 仅在 error !== undefined 时有意义（成功时缺省）；缺省视为 unknown = 可重试
+ * （语义守恒，见 AgentFailureKind）。
+ */
+  failureKind?: AgentFailureKind;
+ /**
  * Parsed structured output.
  * Present when `schema` was provided and the output was valid JSON.
  * Source: tool_execution_end.result.details（validated data object）。

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

@@ -39,7 +39,7 @@ import { canRunTransition } from "./types.ts";
 /**
  * 聚合根级 meta（非 RunState 的一部分，不随 trace 持久化到 worker JSONL）。
  *
- * workerErrorCount/scriptErrorCount 跨 runtime 存活（C.5：error-recovery 重试计数载体），
+ * workerErrorCount/scriptErrorCount 跨 runtime 存活（C.5：worker-message-pump 重试计数载体），
  * 因为 retry 会 replaceRuntime，但计数是 run 级而非 runtime 级。
  */
 export interface WorkflowRunMeta {
@@ -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，