@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/orchestration/models/trace.ts

@@ -14,7 +14,51 @@
  *
  * 参考：domain-models.md §6（字段/不变式）。
  */
-import type { ExecutionTraceNode, TracePatch } from "./types.ts";
+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）。
@@ -22,28 +66,47 @@ import type { ExecutionTraceNode, TracePatch } from "./types.ts";
  * 不变式：
  * - 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) {
-      trace.nodes.push({ ...node });
+      const copy = { ...node };
+      trace.nodes.push(copy);
+      trace.byIndex.set(copy.stepIndex, copy); // 重复 stepIndex last-wins
     }
     return trace;
   }
 
- /** Append a trace node（append-only，不改已有节点）。 */
+ /**
+ * 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);
   }
 
  /**
@@ -57,19 +120,29 @@ export class Trace {
     if (!node) return; // no-op: 不存在不抛错（D-10 防御性）
 
     if (patch.status !== undefined) node.status = patch.status;
-    if (patch.result !== undefined) node.result = patch.result;
+    // 入口裁剪：节点持裁剪副本，与 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 的节点（首个匹配，trace 中 stepIndex 应唯一）。 */
+ /**
+ * 查找指定 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 {
-    for (const node of this.nodes) {
-      if (node.stepIndex === stepIndex) return node;
-    }
-    return undefined;
+    return this.byIndex.get(stepIndex);
   }
 
  /** 按节点引用删除（仅用于测试或 run 重建场景；正常运行不调用）。 */
@@ -78,20 +151,27 @@ export class Trace {
   }
 
  /**
- * 按 stepIndex 移除节点（仅 pause 清理在飞 call 用）。
+ * 按 stepIndex 移除节点（崩溃重建清理在飞 call 用）。
  *
- * 正常运行不调用（append-only 不变式）。仅 lifecycle.pauseRun 清理被 abort 的
- * 在飞 call 时用——移除其 trace 节点，让 resume 重发 agent-call 时 append 全新
- * 节点走全新执行路径（避免 stale "running" 节点残留 + trace.update 命中旧节点
- * 导致新节点 orphan）。stepIndex 不存在时 no-op（防御性）。
+ * 正常运行不调用（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 视图——外部不应直接 mutate（不变式保护）。 */
+ /**
+ * readonly 视图——返回内部 nodes 数组引用（仅类型级 readonly，运行时无
+ * 防御）。消费方禁止结构化 mutate（push/splice/重排/覆盖元素）：byIndex
+ * 引入后外部结构化 mutate 会使 nodes 与倒排索引 desync。字段级变更走 update()。
+ */
   toArray(): readonly ExecutionTraceNode[] {
     return this.nodes;
   }

package/src/orchestration/models/types.ts

@@ -5,7 +5,7 @@
  * 可独立编译测试（D-12 三层架构，AC-1）。
  *
  * 核心内容：
- * - 状态机：RunStatus = "running" | "paused" | "done"（3 态，FR-3）
+ * - 状态机：RunStatus = "running" | "done"（2 态，一次性生命周期，FR-3）
  * + DoneReason（completed/failed/aborted/budget_limited/time_limited）
  * - AgentCallOpts / AgentResult / AgentUsage（单次 agent 调用的输入/输出）
  * - ExecutionTraceNode / TracePatch / ToolCallEntry / WorkerLogEntry（trace 数据）
@@ -18,13 +18,13 @@ import type { ExecutionRecord } from "../../execution/types.ts";
 // ── 状态机 ────────────────────────────────────────────────────
 
 /**
- * 状态机：3 态（D-12 / FR-3）。
+ * 状态机：2 态（D-12 / FR-3，一次性生命周期——run 不可挂起）。
  *
- * running ↔ paused → done
+ * running → done
  *
  * `done` 是唯一终态，具体原因由 DoneReason 区分。
  */
-export type RunStatus = "running" | "paused" | "done";
+export type RunStatus = "running" | "done";
 
 /** 终态原因。done 时必有（WorkflowRun 不变式）。 */
 export type DoneReason =
@@ -38,12 +38,11 @@ export type DoneReason =
 
 /** 合法的状态转换。空数组 = 无出边（done 终态）。 */
 export const VALID_RUN_TRANSITIONS: Record<RunStatus, readonly RunStatus[]> = {
-  running: ["paused", "done"] as const,
-  paused: ["running", "done"] as const,
+  running: ["done"] as const,
   done: [] as const,
 };
 
-export const ALL_RUN_STATUSES: readonly RunStatus[] = ["running", "paused", "done"] as const;
+export const ALL_RUN_STATUSES: readonly RunStatus[] = ["running", "done"] as const;
 
 export const ALL_DONE_REASONS: readonly DoneReason[] = [
   "completed",
@@ -247,7 +246,7 @@ export interface ExecutionTraceNode {
   sessionId?: string;
  /**
  * Session JSONL 绝对路径。finalizeCall 从 result.sessionFile 透传。
- * 持久化到快照（serializeRun），pause/resume + 跨 session 重水合后保留。
+ * 持久化到快照（serializeRun），跨 session 重水合后保留。
  */
   sessionFile?: string;
  /**
@@ -255,7 +254,7 @@ export interface ExecutionTraceNode {
  *
  * 挂在 node 上（D-10 单源延伸：AgentCall.traceNode 与 Trace.nodes 共享同一引用）。
  * TUI 通过 trace.toArray() 读 node.live，派生 getEventLog/getCurrentActivity 实时展示。
- * 不持久化（pause/resume 时为 undefined，重跑时重建）。
+ * 不持久化（序列化时 strip；重跑时由 dispatchAgentCall 重建）。
  */
   live?: ExecutionRecord;
 }

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

@@ -11,22 +11,19 @@
  * I1: state.status === "running" ⟺ runtime !== undefined
  * I2: state.status === "done" ⟹ state.reason !== undefined
  *
- * 状态机（FR-3，3 态）：
- * paused ──assignRuntime──→ running
- * running ──transition("paused")──→ paused (releaseRuntime, G3-001)
+ * 状态机（一次性生命周期，2 态）：
+ * 构造（status="running"，I1 构造期跳过——runtime 由 assignRuntime 注入）
  * running ──transition("done", reason)──→ done (releaseRuntime + completedAt)
- * paused ──transition("done", reason)──→ done (completedAt)
  * done ──(no out edges, zombie)
  *
- * pause/resume 生命周期（G3-001）：
- * - transition("paused") 调 releaseRuntime，整个 RunRuntime 被丢弃
- * （runtime=undefined）。AbortController 一次性无法复用。
- * - resume 走 assignRuntime(new RunRuntime(...))，重建 worker/gate/controller。
+ * 「创建即 running」与 I1 的协调（F4）：构造瞬间 running 而 runtime 尚未注入，
+ * I1 在构造期跳过（仅查 I2），完整校验由 assignRuntime/transition/replaceRuntime
+ * 末尾的 validateInvariants 维持；构造到 assignRuntime 的 I1 窗口由调用方
+ * （lifecycle.runWorkflow 在 assignRuntime 之后才 runs.set）保证对外不可见。
  *
  * worker-error-retry（G5-001 + G6-001）：
  * - replaceRuntime(newRt): 前置 status==="running"（G6-001），原子释放前一个 runtime
  * + 绑定新 runtime，全程保持不变式 I1（中间不经过 runtime===undefined 的可见状态）。
- * - paused 状态下 retry 被拒（要 retry 先 resume）。
  *
  * 参考：domain-models.md §1（聚合根定义）、clarification.md G3-001/G5-001/G6-001。
  */
@@ -50,8 +47,6 @@ export interface WorkflowRunMeta {
   startedAt: string;
  /** ISO 时间戳，transition("done") 时设置。 */
   completedAt?: string;
- /** ISO 时间戳，transition("paused") 时设置（最近一次 pause）。 */
-  pausedAt?: string;
  /** Worker 线程错误计数（C.5：跨 runtime 存活，重试计数载体）。 */
   workerErrorCount?: number;
  /** 脚本错误计数（C.5：跨 runtime 存活）。 */
@@ -68,52 +63,43 @@ export class WorkflowRun {
   meta: WorkflowRunMeta;
 
  /**
- * 创建聚合根。初始状态通常为 "paused"（runtime=undefined，符合不变式 I1），
- * 随后 assignRuntime 进入 "running"。也可传入 done 状态用于 reconstruct
+ * 创建聚合根。初始状态 "running"（一次性生命周期：run 从创建起即在执行，
+ * runtime 由紧随其后的 assignRuntime 注入）。也可传入 done 状态用于重水合
  * 已完成的 run（loadAll 后的只读聚合）。
  *
- * 不变式 I1 由构造函数校验——**不可用于 reconstruct 持久化的 running 快照**
- *（持久化的 running run 没有 worker，违反 I1；进程被杀后 worker 不可能还活着）。
- * 重水合用 `WorkflowRun.reconstruct`，它跳过 I1 校验（快照是可信状态）。
- *
- * @param reconstructMode 内部用——true 时跳过 I1 校验（仅校验 I2）。
- * 调用方用 `WorkflowRun.reconstruct` 静态工厂，不直接传此 flag。
+ * 不变式 I1 构造期跳过——「创建即 running」要求构造瞬间 runtime===undefined
+ * 合法（runtime 必须由 assignRuntime 注入，构造函数无从持有）；重水合的
+ * running 快照同样无 worker。I1 的运行时校验在 assignRuntime/transition/
+ * replaceRuntime 末尾的 validateInvariants 处生效。
  */
   constructor(
     runId: string,
     spec: RunSpec,
     state: RunState,
     meta: WorkflowRunMeta,
-    reconstructMode = false,
   ) {
     this.runId = runId;
     this.spec = spec;
     this.state = state;
     this.meta = meta;
- // runtime 在构造时始终为 undefined——run 创建时无活 worker，resume/loadAll
- // 时也不重水合 runtime（worker 必须由 lifecycle 重新 start）。
+ // runtime 在构造时始终为 undefined——run 创建时无活 worker，loadAll 重水合
+ // 时也不恢复 runtime（worker 必须由 lifecycle 重新 start）。
     this.runtime = undefined;
-    if (reconstructMode) {
- // 重水合：仅校验 I2（done ⟹ reason）。I1 跳过——持久化的 running 状态没有
- // worker，违反 I1；调用方（D-4 kill-9 恢复）负责恢复 I1。
-      this.validateInvariantI2();
-    } else {
-      this.validateInvariants();
-    }
+ // 构造期仅校验 I2（I1 跳过，见方法 doc）；I1 由 assignRuntime 末尾
+ // validateInvariants 恢复。
+    this.validateInvariantI2();
   }
 
  /**
- * 从持久化快照重水合聚合根。跳过 I1 校验——持久化的 running 状态没有 worker
- * （进程被杀后 worker 不可能还活着），违反 I1。调用方（D-4 kill-9 恢复）负责
- * 在 session_start 时把残留 running 转 done,failed，恢复 I1。
- *
- * 与 `new WorkflowRun(...)` 的区别：constructor 校验 I1（适合 live 创建），
- * reconstruct 跳过（适合可信快照重水合）。
+ * 从持久化快照重水合聚合根。与构造函数同语义（构造期跳过 I1——持久化的
+ * running 状态没有 worker，进程被杀后 worker 不可能还活着）。保留独立工厂
+ * 标注重水合意图；调用方（D-4 kill-9 恢复）负责在 session_start 时把残留
+ * running 转 done,failed，恢复 I1。
  *
  * @throws I2 违反（done 快照缺 reason 仍是 bug，不可跳过）
  */
   static reconstruct(runId: string, spec: RunSpec, state: RunState, meta: WorkflowRunMeta): WorkflowRun {
-    return new WorkflowRun(runId, spec, state, meta, true);
+    return new WorkflowRun(runId, spec, state, meta);
   }
 
  // ── 不变式校验 ─────────────────────────────────────────────
@@ -138,8 +124,8 @@ export class WorkflowRun {
   }
 
  /**
- * 仅校验不变式 I2（done ⟹ reason）。reconstruct 时用——持久化的 running 快照
- * 违反 I1（无 worker），但 I2 必须保证（done 快照缺 reason 是真 bug）。
+ * 仅校验不变式 I2（done ⟹ reason）。构造期用——「创建即 running」与重水合的
+ * running 快照都无 runtime（I1 构造期跳过），但 I2 必须保证（done 缺 reason 是真 bug）。
  */
   private validateInvariantI2(): void {
     if (this.state.status === "done" && this.state.reason === undefined) {
@@ -152,17 +138,16 @@ export class WorkflowRun {
  // ── 状态机转换 ─────────────────────────────────────────────
 
  /**
- * 状态机转换。合法转换：running→{paused,done}, paused→done。
+ * 状态机转换。合法转换：running→done。
  *
- * paused→running 不走 transition——用 assignRuntime（需注入 runtime）。
- * 调用 transition("running") 抛错，引导调用方用 assignRuntime。
+ * running 的进入不走 transition——构造即 running，replaceRuntime 保持 running。
+ * 调用 transition("running") 抛错，防止绕过 runtime 注入直接改状态。
  *
  * 副作用：
- * - →paused: releaseRuntime（G3-001 丢弃 runtime）+ 设 meta.pausedAt
  * - →done: releaseRuntime + 设 state.reason + meta.completedAt
  *
- * @param target 目标状态（不允许 "running"——用 assignRuntime）
- * @param reason →done 时必填（done ⟹ reason，不变式 I2）；→paused 时忽略
+ * @param target 目标状态（不允许 "running"——runtime 注入只走 assignRuntime/replaceRuntime）
+ * @param reason →done 时必填（done ⟹ reason，不变式 I2）
  * @throws 非法转换 / done 缺 reason / target==="running"
  */
   transition(target: RunStatus, reason?: DoneReason): void {
@@ -187,18 +172,11 @@ export class WorkflowRun {
     }
 
  // 副作用：先清理 runtime（releaseRuntime 守不变式 I1），再改 status
-    if (target === "paused" || target === "done") {
-      this.releaseRuntime();
-    }
-
+ // （canRunTransition 已排除 target==="running"，此处 target 恒为 "done"）
+    this.releaseRuntime();
     this.state.status = target;
-    if (target === "paused") {
-      this.meta.pausedAt = new Date().toISOString();
-    }
-    if (target === "done") {
-      this.state.reason = reason;
-      this.meta.completedAt = new Date().toISOString();
-    }
+    this.state.reason = reason;
+    this.meta.completedAt = new Date().toISOString();
 
     this.validateInvariants();
   }
@@ -206,12 +184,14 @@ export class WorkflowRun {
  // ── Runtime 生命周期 ───────────────────────────────────────
 
  /**
- * 绑定 runtime 并进入 running 状态。
+ * 绑定 runtime（run 创建后注入执行资源）。
  *
- * 前置：status==="paused" && runtime===undefined（首次启动或 resume）。
- * 原子地：设 runtime + status="running"，保持不变式 I1 全程不违反。
+ * 前置：status==="running" && runtime===undefined（runWorkflow 创建路径——
+ * 构造即 running 但 runtime 延迟到此处注入）。
+ * 原子地：设 runtime 后末尾 validateInvariants，恢复构造期跳过的 I1
+ * （running ⟺ runtime!==undefined）。
  *
- * @throws runtime 已定义 / status 不是 "paused"
+ * @throws runtime 已定义 / status 不是 "running"（done 僵尸不可复活）
  */
   assignRuntime(rt: RunRuntime): void {
     if (this.runtime !== undefined) {
@@ -219,28 +199,27 @@ export class WorkflowRun {
         `WorkflowRun.assignRuntime: runtime already defined (runId=${this.runId})`,
       );
     }
-    if (this.state.status !== "paused") {
+    if (this.state.status !== "running") {
       throw new Error(
-        `WorkflowRun.assignRuntime: requires status==="paused" (current: ${this.state.status}, runId=${this.runId})`,
+        `WorkflowRun.assignRuntime: requires status==="running" (current: ${this.state.status}, runId=${this.runId})`,
       );
     }
- // 原子绑定：先设 runtime（I1 暂时违反：status!=="running" 但 runtime!==undefined），
- // 紧接着设 status="running"，末尾 validateInvariants 通过。
- // 两条赋值间无 await/外部观察点，外部不可见中间状态。
+ // 原子绑定：构造期 I1 处于跳过窗口（running 而 runtime undefined），设 runtime
+ // 后末尾 validateInvariants 恢复 I1。调用方在 assignRuntime 后才对外注册
+ // （lifecycle.runWorkflow 的 runs.set 后移），窗口外部不可见。
     this.runtime = rt;
-    this.state.status = "running";
     this.validateInvariants();
   }
 
  /**
- * 解绑 runtime（pause/done 时由 transition 调用，也可独立调用）。
+ * 解绑 runtime（done 时由 transition 调用，也可独立调用）。
  *
  * 前置：无（runtime===undefined 时 no-op，幂等）。
- * 副作用：调 runtime.release("pause") 释放 worker/controller，置 runtime=undefined。
+ * 副作用：调 runtime.release("terminal") 释放 worker/controller，置 runtime=undefined。
  */
   releaseRuntime(): void {
     if (this.runtime === undefined) return;
-    this.runtime.release("pause");
+    this.runtime.release("terminal");
     this.runtime = undefined;
  // 不改 status——调用方（transition）负责。独立调用时调用方需自行确保
  // status 一致（如 worker-error-retry 用 replaceRuntime 而非 release+assign）。
@@ -249,12 +228,12 @@ export class WorkflowRun {
  /**
  * 原地替换 runtime（G5-001：worker-error-retry）。
  *
- * 前置：status==="running"（G6-001：paused 下拒绝，要 retry 先 resume）。
+ * 前置：status==="running"（G6-001：终态 run 拒绝重建）。
  * 原子地：释放旧 runtime（worker.terminate + abort）+ 绑定新 runtime，
  * 全程 status 保持 "running"，不变式 I1 不违反（中间无 runtime===undefined 可见态）。
  *
- * 与 release+assign 的区别：replaceRuntime 不改 status（避免经过 paused 中间态），
- * 中间同步完成，外部观察不到违反不变式的瞬间。
+ * 与 release+assign 的区别：replaceRuntime 不改 status，中间同步完成，
+ * 外部观察不到违反不变式的瞬间。
  *
  * @throws status!=="running"
  */

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

@@ -23,6 +23,28 @@ import { type LintResult,lintScript } from "../script-lint.ts";
 import type { WorkflowMeta } from "../../shared/resource-meta.ts";
 export type { WorkflowMeta };
 
+// ── validate lint memo（IF9/#15，TC9/DM2）─────────────────────
+
+/**
+ * 模块级 lint 结果缓存：key = path，命中条件 = sourceCode 与缓存 srcRef 相等
+ *（`===`——JS 字符串比较是**值相等**，设计原文的「引用相等」前提在 JS 不可实现，
+ * 实测等值异字面量同样命中；lintScript 是 source 的纯函数，值相等 ⟹ 结果必然
+ * 相同，故值键 memo 语义严格正确，且是引用键意图的超集：registry 重建实例传等值
+ * 内容也命中）。
+ *
+ * 重复点：registry.getPath/get 每次 new WorkflowScript（workflow-script-registry-impl），
+ * launcher.ts runAndWait / executeNestedWorkflow（每 nested call）各 validate 一次，
+ * 同脚本 N 次嵌套 = N 次全量正则 lint。失效语义：文件变更 → 内容值不等 → miss →
+ * 重 lint 并覆写条目。等长前缀不同的内容比较在 V8 走指针/长度快路径 + memcmp，
+ * 成本远低于正则 lint（TC9 alternatives 中「值键成本≈重 lint」的量级判断不成立）。
+ */
+const lintMemo = new Map<string, { srcRef: string; result: LintResult }>();
+
+/** 清空 validate lint 缓存（config-loader.invalidateCache 追加调用，测试隔离用）。 */
+export function clearLintMemo(): void {
+  lintMemo.clear();
+}
+
 /** 脚本来源：saved（.pi/workflows/ 固定）或 tmp（.pi/workflows/.tmp/ 临时）。 */
 export type WorkflowSource = "saved" | "tmp";
 
@@ -68,9 +90,18 @@ export class WorkflowScript {
  * - agent 选项 outputSchema → schema
  * - result.output/parsedOutput/content 不存在
  * - 文件传状态警告
+ *
+ * IF9（#15）：同 path 且 sourceCode 引用相等 → 返回缓存 lint 结果（launcher 嵌套
+ * 场景下 registry 重建实例的重复全量 lint 消除）；否则 lint + 覆写条目。
  */
   validate(): LintResult {
-    return lintScript(this.sourceCode);
+    const memoized = lintMemo.get(this.path);
+    if (memoized && memoized.srcRef === this.sourceCode) {
+      return memoized.result;
+    }
+    const result = lintScript(this.sourceCode);
+    lintMemo.set(this.path, { srcRef: this.sourceCode, result });
+    return result;
   }
 
  /**

package/src/orchestration/skill-discovery.ts

@@ -37,8 +37,35 @@ function getNpmSkillCandidates(npmSkillsDir: string): string[] {
  *    PI_CODING_AGENT_DIR 场景读隔离目录，不碰 ~/.pi/agent）
  * 3. npm packages: <agentDir>/npm/node_modules/<pkg>/skills/<name>/
  * Returns the directory path if found, undefined otherwise.
+ *
+ * IF8(#14)：结果按 skillName 缓存（含未命中 undefined 也缓存，DM3）——调用点
+ * agent-opts-resolver 每次 agent({skill}) call 一次，同 skill 名重复的逐候选
+ * existsSync 全部消重。缓存生命周期 = session：index.ts 在 session_start 调
+ * clearSkillPathCache 失效两级缓存（对齐同包 subagent-list-injector 的 session
+ * 生命周期缓存模式）。不做进程级缓存的原因：pi 同一进程可能有多个 session
+ * （TUI /new、/fork 同进程换 session），运行中安装的 skill（写入 project/user/npm
+ * 任一源）需要对新 session 可见——进程级缓存会让曾 miss 的 skill 名（含缓存了
+ * undefined 的未命中条目）在同进程后续 session 中永久不可见。session 内复用是
+ * IF8/DM3 的主要收益（同一次 run 内同 skill 名重复调用消重），保持不变。
+ */
+const skillMemo = new Map<string, string | undefined>();
+
+/**
+ * 清空 resolveSkillPath 两级缓存（skillMemo 结果缓存 + npm 候选列表缓存）。
+ * 两个消费点：测试隔离（beforeEach）与 index.ts session_start（session 生命周期
+ * 失效——npm 源新装包产生的候选目录也要重新可见）。
  */
+export function clearSkillPathCache(): void {
+  skillMemo.clear();
+  skillCandidatesCache.clear();
+}
+
 export function resolveSkillPath(skillName: string): string | undefined {
+  // has 先行区分「缓存了未命中(undefined)」与「无条目」——未命中也缓存（DM3）
+  if (skillMemo.has(skillName)) {
+    return skillMemo.get(skillName);
+  }
+
   const candidates = [
  // Project-level
     path.resolve(process.cwd(), ".agents/skills", skillName),
@@ -54,9 +81,12 @@ export function resolveSkillPath(skillName: string): string | undefined {
 
   for (const dir of candidates) {
     if (fs.existsSync(dir)) {
+      skillMemo.set(skillName, dir);
       return dir;
     }
   }
 
+  // 未命中也缓存：防止不存在的 skill 名反复全候选 existsSync（DM3）
+  skillMemo.set(skillName, undefined);
   return undefined;
 }

package/src/orchestration/worker-handle.ts

@@ -6,7 +6,7 @@
  *
  * 核心职责：竞态防护（G-025）。
  *
- * 背景：一个 run 可经历多个 WorkerHandle（pause/resume/retry 各换一个）。
+ * 背景：一个 run 可经历多个 WorkerHandle（终止/重试各换一个）。
  * 需防止「terminate(old) → start(new) → old exit fires」竞态——
  * WorkerHandle 把守卫内化：terminate 后 isCurrent=false，
  * 已终止 handle 的 onMessage/onError/onExit 回调自动 no-op（无需调用方比对引用）。

package/src/orchestration/worker-host.ts

@@ -40,7 +40,7 @@ export class WorkerHostImpl implements WorkerHost {
  * handle.isCurrent 做竞态防护，G-025）
  *
  * 返回的 WorkerHandle 由调用方（lifecycle）保存到 RunRuntime.worker。
- * 终止/pause/resume 时由 RunRuntime.release 接管。
+ * 终止/崩溃重建（rebuild）时由 RunRuntime.release 接管。
  */
   start(
     spec: RunSpec,