@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/orchestration/launcher.ts

@@ -17,7 +17,7 @@
  * 3. script.toExecutable → 可执行源
  * 4. 构建 RunSpec + runWorkflow(spec, deps, signal)
  * 5. 轮询至 done（间隔 STATUS_POLL_INTERVAL_MS）
- * 6. timeout → abortRun + transition done,time_limited
+ * 6. 显式 timeoutMs 到期 → abortRun + transition done,time_limited（未传不限时）
  * 7. signal.aborted → abortRun + reason=aborted
  *
  * 层归属：Engine。依赖 registry + runWorkflow/abortRun + LifecycleDeps。
@@ -32,15 +32,35 @@ import type { RunSpec } from "./models/run-spec.ts";
 import type { DoneReason } from "./models/types.ts";
 import type { WorkflowRun } from "./models/workflow-run.ts";
 import type { WorkflowScriptRegistry } from "./models/workflow-script-registry.ts";
+import { assertSafeTimerDelay } from "../shared/timer-delay.ts";
 
 // ── 常量 ─────────────────────────────────────────────────────
 
-/** 默认 runAndWait 超时（10 分钟）。 */
-const DEFAULT_RUNANDWAIT_TIMEOUT_MS = 600_000;
-
 /** 轮询间隔（500ms）。 */
 const STATUS_POLL_INTERVAL_MS = 500;
 
+/**
+ * [U7] XYZ_SUBAGENT_RUN_WATCHDOG_MS：无显式限时 run 的轮询绝对时限兜底 env。
+ *
+ * 与 session-runner 的 XYZ_SUBAGENT_SPAWN_WATCHDOG_MS（spawn watchdog：maxTurns 无
+ * 估算依据时的 hang 兜底）对称：未设置 = 无兜底（不限，watchdog 默认关的用户裁决不变）；
+ * 设置 = pollRunToResult 的 wall-clock 绝对时限——无显式限时的 run（顶层 runAndWait
+ * 未传 timeoutMs / 嵌套父 run 未设 budgetTimeMs）若 workflow worker hang 将永不回收，
+ * 本 env 提供显式 opt-in 的兜底回收。非法值（非有限数/<=0）视为未设。
+ * 前缀用 XYZ_SUBAGENT_*：同 SPAWN_WATCHDOG_ENV 的桌面 safe-env 白名单原因
+ * （ENV_WHITELIST_PREFIXES 只放行 XYZ_ 等，PI_ 前缀被静默丢弃）。
+ */
+export const RUN_WATCHDOG_ENV = "XYZ_SUBAGENT_RUN_WATCHDOG_MS";
+
+/** 解析 run watchdog 毫秒数；env 未设/非法返回 undefined（无兜底，不限）。 */
+function getEnvRunWatchdogMs(): number | undefined {
+  const raw = process.env[RUN_WATCHDOG_ENV];
+  if (!raw) return undefined;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+  return parsed;
+}
+
 // ── 类型 ─────────────────────────────────────────────────────
 
 /**
@@ -121,10 +141,26 @@ async function pollRunToResult(
   runId: string,
   deps: LauncherDeps,
   signal: AbortSignal | undefined,
-  timeoutMs: number,
+  timeoutMs: number | undefined,
   abortReason: string,
 ): Promise<WorkflowRunResult> {
-  const deadline = Date.now() + timeoutMs;
+  // [预算语义对齐 + U2] timeoutMs undefined 或 <=0 → 无 wall-clock deadline（不限）：
+  // 与 lifecycle.runWorkflow 的 budgetTimeMs 判定（>0 才挂 scheduleTimeBudget）同语义。
+  // 旧实现 0 → deadline=now 立即超时（"timed out after 0ms"）、负数 → "timed out
+  // after -5000ms" 类错误串；非正值与 undefined 统一为不限。
+  // [U7] 显式不限时由 XYZ_SUBAGENT_RUN_WATCHDOG_MS 提供绝对时限兜底（未设 = 不限）。
+  // env 值与显式值同域：越界（>2^31-1）fail-fast——虽 deadline 是算术比较不经
+  // setTimeout、无 1ms 陷阱，但如此量级的配置几乎必然是手误，与 spawn watchdog env
+  // 的 fail-fast 策略对称。
+  const explicitTimeoutMs =
+    timeoutMs !== undefined && timeoutMs > 0 ? timeoutMs : getEnvRunWatchdogMs();
+  if (explicitTimeoutMs !== undefined) {
+    assertSafeTimerDelay(explicitTimeoutMs, `timeoutMs / ${RUN_WATCHDOG_ENV}`);
+  }
+  // Infinity 哨兵统一 while 条件，避免循环内双重判空；Infinity 永不小于自身，循环只在
+  // 有限 deadline 到期时退出。
+  const deadline =
+    explicitTimeoutMs === undefined ? Number.POSITIVE_INFINITY : Date.now() + explicitTimeoutMs;
   while (Date.now() < deadline) {
     if (signal?.aborted) {
       const runBeforeAbort = deps.runs.get(runId);
@@ -142,14 +178,15 @@ async function pollRunToResult(
   }
   const runBeforeTimeout = deps.runs.get(runId);
   if (runBeforeTimeout?.state.status === "done") return toResult(runBeforeTimeout);
-  await safeAbort(runId, deps, `Workflow timed out after ${timeoutMs}ms`, "time_limited");
+  // 循环退出 ⇒ deadline 有限 ⇒ explicitTimeoutMs 必已定义（undefined/<=0 走 Infinity 不进此分支）
+  await safeAbort(runId, deps, `Workflow timed out after ${explicitTimeoutMs}ms`, "time_limited");
   const finalRun = deps.runs.get(runId);
   return finalRun
     ? toResult(finalRun)
     : {
         status: "done",
         reason: "time_limited",
-        error: `Workflow timed out after ${timeoutMs}ms`,
+        error: `Workflow timed out after ${explicitTimeoutMs}ms`,
         runId,
       };
 }
@@ -174,7 +211,9 @@ async function pollRunToResult(
  * @param args 调用参数（worker 内 $ARGS 访问）
  * @param deps LauncherDeps（LifecycleDeps + registry）
  * @param signal 外部 abort signal（可选）
- * @param timeoutMs 超时上限（默认 10 分钟）
+ * @param timeoutMs 超时上限（可选）。[预算语义对齐 + U2] 未传或 <=0 = 不限（轮询至 done /
+ *  abort 为止，不限时由 XYZ_SUBAGENT_RUN_WATCHDOG_MS 兜底）——旧实现默认 10 分钟会误杀长任务，
+ *  且 0/负值会落成立即超时；仅显式正数才限时。
  * @returns WorkflowRunResult（status 恒 "done"）
  */
 export async function runAndWait(
@@ -182,7 +221,7 @@ export async function runAndWait(
   args: Record<string, unknown>,
   deps: LauncherDeps,
   signal?: AbortSignal,
-  timeoutMs: number = DEFAULT_RUNANDWAIT_TIMEOUT_MS,
+  timeoutMs?: number,
 ): Promise<WorkflowRunResult> {
  // 1. registry 查找脚本（workflowRef = 绝对路径，S2 路径统一）
   const script = await deps.registry.getPath(name);
@@ -361,13 +400,19 @@ export async function executeNestedWorkflow(
     const runId = await runWorkflow(spec, deps, childController.signal);
 
     // Step 5: 轮询至 done（复用 runAndWait 的轮询逻辑）
-    // [H-1] 嵌套 workflow timeout 从父 run 继承：父 spec.budgetTimeMs 存在时取
-    //  min(父 budget, DEFAULT)，让子 run 不超出父 run 的剩余时间预算；否则用 DEFAULT。
+    // [H-1] 嵌套 workflow timeout 从父 run 完整传导：父 spec.budgetTimeMs 显式设定时
+    //  原样作为子 run 轮询 deadline（不 min(DEFAULT) 封顶——旧实现把父 time:2h 截断到
+    //  10min，违背「显式传参完整生效」语义）；父未设 → undefined，无 deadline（不限）。
     //  budgetRef（共享 Budget）已在 Step 4 透传给子 run 处理 token/cost 预算，
     //  此处的 budgetTimeMs 只服务 pollRunToResult 的轮询 deadline（wall-clock 兜底）。
-    const nestedTimeoutMs = parentRun.spec.budgetTimeMs
-      ? Math.min(parentRun.spec.budgetTimeMs, DEFAULT_RUNANDWAIT_TIMEOUT_MS)
-      : DEFAULT_RUNANDWAIT_TIMEOUT_MS;
+    // [U2] 预算语义统一：父 budgetTimeMs <=0（含 0/负）与 undefined 同义 = 不限——
+    //  与 lifecycle.runWorkflow 的 budgetTimeMs 判定（>0 才挂 scheduleTimeBudget）对齐。
+    //  旧实现 0 传导给子 run 后 deadline=now 立即超时（"timed out after 0ms"），与
+    //  lifecycle 的 0=不限 语义分裂。pollRunToResult 内亦对非正值兜底归一（双写防漂移），
+    //  此处显式归一是传导语义的文档化表达。
+    const rawNestedTimeoutMs = parentRun.spec.budgetTimeMs;
+    const nestedTimeoutMs =
+      rawNestedTimeoutMs !== undefined && rawNestedTimeoutMs > 0 ? rawNestedTimeoutMs : undefined;
 
     const result = await pollRunToResult(
       runId,

package/src/orchestration/lifecycle.ts

@@ -24,10 +24,10 @@
  * 只有两类重建——rebuildRuntime（error-recovery，崩溃重试路径，run 保持 running、
  * replaceRuntime 原子换新）与 abort/terminate 的终态释放（transition("done") 内
  * releaseRuntime，run 不再恢复）。
+ * （旧并发门闩 gate 抽象已删——no-op 无生产语义，实际并发由 SubagentService
+ * ConcurrencyPool 管理；原 D-13 maxConcurrency=4 无消费方。）
  *
- * **D-13**：maxConcurrency=4（ConcurrencyGate 默认值）。
- *
- * 层归属：Engine。依赖 LifecycleDeps + ConcurrencyGate + WorkerHost via port +
+ * 层归属：Engine。依赖 LifecycleDeps + WorkerHost via port +
  * WorkflowRun + handleWorker* 函数。
  *
  * 参考：domain-models.md §1（聚合根状态机）。
@@ -35,8 +35,8 @@
 
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
+import { assertSafeTimerDelay } from "../shared/timer-delay.ts";
 import { validateRunArgs } from "./args-validator.ts";
-import { ConcurrencyGate, DEFAULT_CONCURRENCY } from "./concurrency-gate.ts";
 import {
   handleWorkerError,
   handleWorkerExit,
@@ -121,12 +121,16 @@ function makeHandlers(run: WorkflowRun, deps: LifecycleDeps): WorkerHandlers {
  * 自动清理，避免孤儿触发。worker/script 错误重试经 rebuildRuntime 重排新计时器。
  *
  * @returns 计时器句柄（未设预算时 undefined）
+ * @throws budgetTimeMs 超出 Node setTimeout 上限（2^31-1）——溢出值会被 Node 置 1ms
+ *   立即触发（「不限时预算」变「立即超时」），fail-fast 不静默 clamp（U1）。
  */
 export function scheduleTimeBudget(
   runId: string,
   deps: LifecycleDeps,
   budgetTimeMs: number,
 ): ReturnType<typeof setTimeout> {
+  // [U1] arm 入口：值流入 setTimeout 前校验安全域（>2^31-1 会变 1ms 立即触发）。
+  assertSafeTimerDelay(budgetTimeMs, "budgetTimeMs");
   const timer = setTimeout(() => {
     void abortRun(runId, deps, "Time budget exceeded", "time_limited").catch(
       (err: unknown) => {
@@ -213,17 +217,16 @@ export async function runWorkflow(
     );
   }
 
- // 构造 handlers + runtime（worker + gate + controller）
+ // 构造 handlers + runtime（worker + controller）
   const handlers = makeHandlers(run, deps);
   const controller = new AbortController();
-  const gate = new ConcurrencyGate({ maxConcurrency: DEFAULT_CONCURRENCY });
   const worker = deps.workerHost.start(spec, spec.args, handlers);
  // C.7：run 级时间预算计时器（spec.budgetTimeMs > 0 时启用，到期 abortRun time_limited）。
   const timeBudgetTimer =
     spec.budgetTimeMs && spec.budgetTimeMs > 0
       ? scheduleTimeBudget(runId, deps, spec.budgetTimeMs)
       : undefined;
-  const runtime = new RunRuntime(worker, gate, controller, timeBudgetTimer);
+  const runtime = new RunRuntime(worker, controller, timeBudgetTimer);
 
  // assignRuntime（注入 runtime，恢复 I1：running ⟺ runtime!==undefined）
   run.assignRuntime(runtime);

package/src/orchestration/models/__tests__/budget.test.ts

@@ -9,7 +9,6 @@ import {
   CACHE_WRITE_WEIGHT,
   INPUT_WEIGHT,
   OUTPUT_WEIGHT,
-  SOFT_MAX_AGENTS_WARNING,
 } from "../budget.js";
 import type { AgentUsage } from "../types.js";
 
@@ -106,7 +105,7 @@ describe("Budget.consume 加权公式", () => {
 // ── consume：NaN 守卫（TDD，预期主 agent 同步补源码守卫）──────
 //
 // 源码 consume() 当前无守卫：undefined/NaN/Infinity 进入加权公式会产出
-// NaN/Infinity 污染 usedTokens，导致后续 isExceeded/isThresholdReached 永远命中。
+// NaN/Infinity 污染 usedTokens，导致后续 isExceeded 永远命中。
 // 以下测试断言「脏字段当 0 处理」——守卫补上前会失败，属预期临时状态。
 
 describe("Budget.consume NaN 守卫（undefined/NaN/Infinity 当 0 处理）", () => {
@@ -276,65 +275,6 @@ describe("Budget.remaining", () => {
   });
 });
 
-// ── isThresholdReached ───────────────────────────────────────
-
-describe("Budget.isThresholdReached", () => {
-  it("达到 90% 阈值（usedTokens >= maxTokens × 0.9）", () => {
-    const b = new Budget({ maxTokens: 1000 });
-    b.consume(usage({ input: 900 }));
-    expect(b.isThresholdReached(0.9)).toBe(true);
-  });
-
-  it("未达 90% 阈值", () => {
-    const b = new Budget({ maxTokens: 1000 });
-    b.consume(usage({ input: 899 }));
-    expect(b.isThresholdReached(0.9)).toBe(false);
-  });
-
-  it("边界：恰好等于阈值 → true（>= 语义）", () => {
-    const b = new Budget({ maxTokens: 1000 });
-    b.consume(usage({ input: 950 }));
-    expect(b.isThresholdReached(0.95)).toBe(true);
-  });
-
-  it("maxTokens=0 → false（守卫）", () => {
-    const b = new Budget({ maxTokens: 0 });
-    b.consume(usage({ input: 999999 }));
-    expect(b.isThresholdReached(0.9)).toBe(false);
-  });
-
-  it("maxTokens undefined → false", () => {
-    const b = new Budget();
-    b.consume(usage({ input: 999999 }));
-    expect(b.isThresholdReached(0.9)).toBe(false);
-  });
-
-  it("纯查询无状态——重复查询结果一致", () => {
-    const b = new Budget({ maxTokens: 1000 });
-    b.consume(usage({ input: 950 }));
-    expect(b.isThresholdReached(0.9)).toBe(true);
-    expect(b.isThresholdReached(0.9)).toBe(true);
-  });
-});
-
-// ── isSoftLimitReached ───────────────────────────────────────
-
-describe("Budget.isSoftLimitReached", () => {
-  it(`totalCallCount > ${SOFT_MAX_AGENTS_WARNING} 触发（> 严格语义）`, () => {
-    const b = new Budget();
-    for (let i = 0; i < SOFT_MAX_AGENTS_WARNING; i++) b.incrementCallCount();
-    expect(b.isSoftLimitReached()).toBe(false);
-    b.incrementCallCount(); // 501
-    expect(b.isSoftLimitReached()).toBe(true);
-  });
-
-  it("无状态——可重复查询（非一次性 flag）", () => {
-    const b = new Budget({ totalCallCount: SOFT_MAX_AGENTS_WARNING + 1 });
-    expect(b.isSoftLimitReached()).toBe(true);
-    expect(b.isSoftLimitReached()).toBe(true);
-  });
-});
-
 // ── 构造 ─────────────────────────────────────────────────────
 
 describe("Budget 构造", () => {

package/src/orchestration/models/budget.ts

@@ -3,11 +3,9 @@
  *
  * Token / cost 预算值对象（D-12）。纯数据 + 不变式守卫，无副作用。
  *
- * 设计：
- * - 无 onConsume 回调（值对象不应持可变回调）。
- * - soft limit 通知由 lifecycle 层 consume 后查 isSoftLimitReached 发出（职责分离）。
- * - 90% 预警用查询式 isThresholdReached（无状态，可重复查）。
- * - maxTokens===0 视为不限制（守卫，避免首个 agent 完成误判 budget_limited）。
+ * maxTokens===0 视为不限制（守卫，避免首个 agent 完成误判 budget_limited）。
+ * （预算语义对齐 2026-08：soft-limit 常量（500 调用数预警）与 90% 阈值预警方法
+ * 已删——全库无生产消费方，仅测试锁定。）
  *
  * 层归属：Engine。
  *
@@ -15,9 +13,6 @@
  */
 import type { AgentUsage } from "./types.ts";
 
-/** Soft limit：总调用数超此值发预警（FR-7，从 ConcurrencyGate 迁入）。 */
-export const SOFT_MAX_AGENTS_WARNING = 500;
-
 /**
  * Budget 加权系数（token 口径）。
  *
@@ -51,7 +46,7 @@ export class Budget {
   readonly maxTimeMs?: number;
   usedTokens = 0;
   usedCost = 0;
- /** 总调用计数（soft limit 用，从 ConcurrencyGate.totalCallCount 迁入）。 */
+ /** 总调用计数（持久化/诊断用；execute-agent-call 每次 dispatch 后 increment）。 */
   totalCallCount = 0;
 
   constructor(opts: {
@@ -89,7 +84,7 @@ export class Budget {
     this.usedCost += numOrZero(usage.cost);
   }
 
- /** 累加调用计数（每次 agent dispatch 后调用）。 */
+ /** 累加调用计数（每次 agent dispatch 后调用；持久化快照同步）。 */
   incrementCallCount(): void {
     this.totalCallCount += 1;
   }
@@ -110,17 +105,6 @@ export class Budget {
     return this.maxCost !== undefined && this.maxCost > 0 && this.usedCost >= this.maxCost;
   }
 
- /**
- * 是否达到 soft limit（FR-7）。
- *
- * totalCallCount > SOFT_MAX_AGENTS_WARNING（500）。
- * 调用方（lifecycle）在 consume/incrementCallCount 后查询，
- * 命中时发通知（无状态——可重复查询）。
- */
-  isSoftLimitReached(): boolean {
-    return this.totalCallCount > SOFT_MAX_AGENTS_WARNING;
-  }
-
  /**
  * 剩余 token 预算。maxTokens 未设或 ≤0 时返回 undefined（视为不限制）。
  *
@@ -131,18 +115,4 @@ export class Budget {
     if (this.maxTokens === undefined || this.maxTokens <= 0) return undefined;
     return Math.max(0, this.maxTokens - this.usedTokens);
   }
-
- /**
- * 是否达到 token 预算的给定比例阈值（如 0.9 = 90% 预警）。
- *
- * 纯查询，无状态——调用方负责去重（旧 _budgetWarningSent 语义由 lifecycle 层用
- * 外部 Set 或 once-listener 实现）。maxTokens 未设或为 0 时返回 false。
- */
-  isThresholdReached(ratio: number): boolean {
-    return (
-      this.maxTokens !== undefined &&
-      this.maxTokens > 0 &&
-      this.usedTokens >= this.maxTokens * ratio
-    );
-  }
 }

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

@@ -2,20 +2,20 @@
  * Workflow Extension — Run Runtime
  *
  * 聚合内运行时资源（仅 status==="running" 时存在）。技术资源聚合，
- * Engine 层类型，持 WorkerHandle / ConcurrencyGate 具体类（D-12 不造 interface）。
+ * Engine 层类型，持 WorkerHandle 具体类（D-12 不造 interface）。
  *
- * 职责：封装一次 running-segment 的所有技术资源（worker 线程 + 并发信号量 +
+ * 职责：封装一次 running-segment 的所有技术资源（worker 线程 +
  * abort controller），统一 release 入口（AC-2：单 release 替代多 boolean flag）。
+ * （旧并发门闩 gate 抽象已删——no-op，实际并发由 SubagentService ConcurrencyPool 管理；
+ * 原 withSlot 的 pre-abort 检查内联到 error-recovery dispatchAgentCall。）
  *
  * 一次性生命周期（G3-001）：runtime 释放后不再复用——AbortController 一次性
- * 语义决定 controller 无法跨释放复用，gate 队列也在 worker 重跑脚本 +
- * callCache replay 时清空无影响，所以整个 RunRuntime 重建。唯一注入路径：
+ * 语义决定 controller 无法跨释放复用，所以整个 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";
 
 /**
@@ -32,25 +32,40 @@ export type ReleaseMode = "terminal";
 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>;
+ /**
+ * 本 runtime 代际是否已收到 worker 的终态消息（return / error）。
+ *
+ * [F1] worker exit(0) 且本标记为 false = worker 静默退出、未交付任何终态——最常见根因
+ * 是 execute() 返回值不可克隆，worker 侧 _safePost 吞掉 DataCloneError 后 return 消息
+ * 根本没发出。旧实现 handleWorkerExit 对 code===0 no-op → run 永久 running、runAndWait
+ * 悬挂。handleWorkerExit 据此判定转 done,failed。
+ *
+ * 按代际归零：字段挂在 RunRuntime（每代际 new 一个实例）而非 run.meta——script-error
+ * 重试退避窗口内（error 消息已收到、run 仍 running、旧 worker exit(0)）必须 no-op 等
+ * rebuild；若挂 meta 则 rebuild 后新 worker 再静默退出时会被旧标记误放行，重新悬挂。
+ *
+ * 写点：① handleWorkerMessage 的 return/error 分支（WorkerHandle.isCurrent 守卫保证
+ * 消息必来自当前代际）；② handleWorkerError 进入处理前（[R4-F1] 同代际幂等守卫——
+ * worker 崩溃时 error + exit(1) 双事件各派发一次 handleWorkerError，第一个事件标记
+ * 本代际已处理，第二个事件命中标志跳过，消除单次崩溃计数 +2 / 双 rebuild 交错）。
+ * rebuildRuntime 构造新 RunRuntime 自然重置。
+ */
+  receivedTerminalMessage = false;
  /** 防止 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;
   }

package/src/orchestration/models/types.ts

@@ -101,6 +101,15 @@ 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。
+ */
+  maxTurns?: number;
+ /**
  * Skill name to load (e.g. "code-review"). Resolved to SKILL.md path
  * and injected via --skill flag in the subprocess.
  */
@@ -143,6 +152,13 @@ export interface AgentCallOpts {
   cwd?: string;
   /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
   fork?: boolean;
+  /**
+   * 执行引擎 id（P4 D9 三层优先级的第一层：调用参数级，workflow step 显式指定）。
+   * 仅限「必须某引擎独有能力」的场景使用并注释原因（D9③ workflow 脚本不写死
+   * engine——环境差异由 frontmatter/全局默认承载）；透传链 worker-script-builder
+   * agent() → execute-agent-call → SAR 路由层。
+   */
+  engine?: string;
   /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
   worktree?: boolean;
   /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.

package/src/orchestration/script-lint.ts

@@ -739,7 +739,7 @@ export function lintScript(source: string): LintResult {
  // 教训来源：daily-news-impact.js 用 (async function main(){...})();() 包裹整个脚本，
  // worker 外层 IIFE 不等内层 IIFE 就 postMessage("return")，主线程 transition done
  // → release runtime → controller.abort() → spawn 后 2ms SIGKILL 子进程。
- // 诊断耗时 4 轮：先后误判为 model 故障 / 工具缺失 / turn-signal abort / ConcurrencyGate 异常，
+ // 诊断耗时 4 轮：先后误判为 model 故障 / 工具缺失 / turn-signal abort / 并发门闩 gate 异常，
  // 最终靠 worker-host → handleReturn → release → abort 的调用栈定位。
   findings.push(...checkBareAsyncIIFE(source));
 

package/src/orchestration/skill-discovery.ts

@@ -60,23 +60,46 @@ export function clearSkillPathCache(): void {
   skillCandidatesCache.clear();
 }
 
+/**
+ * 把 skillName 解析到 rootDir 内的候选路径；越界（穿越）返回 undefined。
+ *
+ * 为什么需要守卫：path.resolve/path.join 会吸收 `..`（"../../x" 落到 skills 根
+ * 之外），随后的 existsSync 命中会把 skills 树外的目录当 skill 目录返回——skill 名
+ * 是名字不是路径，不该具备树外寻址能力。resolve 后与规范化 skills 根做前缀比较
+ * （startsWith(root + sep)；恰好等于根也拒绝——"." 会把根自身当 skill 目录），
+ * 越界 = 该候选不存在：全部候选越界时 resolveSkillPath 返回 undefined，调用方
+ * （agent-opts-resolver）收到 not found（与 workflow name 拒绝的反馈风格一致）。
+ *
+ * 根内归一化仍允许（"a/../b" resolve 后在根内——守卫只拒逃逸，不拒归一化）。
+ */
+function resolveWithinRoot(rootDir: string, skillName: string): string | undefined {
+  const root = path.resolve(rootDir);
+  const resolved = path.resolve(root, skillName);
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+    return undefined;
+  }
+  return resolved;
+}
+
 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),
- // Global user skills
-    path.join(getAgentDir(), "skills", skillName),
-  ];
+  const candidates: string[] = [];
+  const pushCandidate = (dir: string | undefined): void => {
+    if (dir !== undefined) candidates.push(dir);
+  };
+  // Project-level
+  pushCandidate(resolveWithinRoot(path.resolve(process.cwd(), ".agents/skills"), skillName));
+  // Global user skills
+  pushCandidate(resolveWithinRoot(path.join(getAgentDir(), "skills"), skillName));
 
- // npm package skills (cached)
+  // npm package skills (cached)
   const npmSkillsDir = path.join(getAgentDir(), "npm/node_modules");
   for (const pkgSkillsBase of getNpmSkillCandidates(npmSkillsDir)) {
-    candidates.push(path.join(pkgSkillsBase, skillName));
+    pushCandidate(resolveWithinRoot(pkgSkillsBase, skillName));
   }
 
   for (const dir of candidates) {

package/src/orchestration/worker-script-builder.ts

@@ -66,7 +66,7 @@ const WORKER_TEMPLATE_PRE = [
     'const _workerLogs = [];',
     '// IF6(#12): known agent() fields — hoisted to module scope, built once per worker',
     '// (was rebuilt inside agent() on every call; field set is call-invariant).',
-    'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);',
+    'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "maxTurns", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel", "engine"]);',
     'function _pushWorkerLog(level, args) {',
     '  try { _workerLogs.push({ level, message: args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") }); } catch (e) { /* swallow */ }',
     '}',
@@ -152,6 +152,8 @@ const WORKER_TEMPLATE_PRE = [
     '        // 让 parallel() 下的脚本容错循环（parseResult → null → skip）自然接管。',
     '        // 错误原因已由主线程 executeAgentCall → trace.update(result.error) 保留在 trace/TUI，',
     '        // 不丢失。失败 resolve 为空字符串是既定容错策略。',
+    '        // [MF-4] schema 模式下失败时 agent() 仍 resolve（content 回退、不 throw）——',
+    '        // 需要检查错误时请用 returnMeta:true（resolve 值含 error 字段）。',
     '        // parsedOutput: validated data object from structured-output execute().',
     '        // Fallback to content (raw text) when no schema was requested or on error.',
     '        // W2 改动 9(b)：returnMeta===true 时 resolve {value,sessionFile,worktreePath,error,usage,durationMs,sessionId}',
@@ -210,6 +212,11 @@ const WORKER_TEMPLATE_PRE = [
     '        scene: (secondArg && typeof secondArg === "object" && secondArg.scene) || undefined,\n' +
       '        phase: (secondArg && typeof secondArg === "object" && secondArg.phase) || undefined,',
       '        thinkingLevel: (secondArg && typeof secondArg === "object" && secondArg.thinkingLevel) || $THINKING_LEVEL,',
+      '        // step 级 turn 上限（turn limiter；显式 0/负 = 显式不限，压过 spawn watchdog env 兑底，SP-6）\n' +
+      '        // ?? 语义保真：仅 null/undefined 归 undefined（走 env 兑底），显式 0 保留（U5 参数 > env）',
+      '        maxTurns: (secondArg && typeof secondArg === "object" ? secondArg.maxTurns : undefined) ?? undefined,',
+      '        // P4 D9③：step 级 engine 显式指定（仅限必须某引擎独有能力的场景）',
+      '        engine: (secondArg && typeof secondArg === "object" && secondArg.engine) || undefined,',
     '      };',
     '    } else if (typeof firstArg === "object" && firstArg !== null) {',
     '      if (firstArg.prompt) {',
@@ -226,11 +233,13 @@ const WORKER_TEMPLATE_PRE = [
     '          scene: firstArg.scene,',
     '          skill: firstArg.skill,',
     '          timeoutMs: firstArg.timeoutMs,',
+    '          maxTurns: firstArg.maxTurns,',
     '          cwd: firstArg.cwd,',
     '          fork: firstArg.fork,',
     '          worktree: firstArg.worktree,',
     '          returnMeta: firstArg.returnMeta,',
     '          thinkingLevel: firstArg.thinkingLevel || $THINKING_LEVEL,',
+    '          engine: firstArg.engine,',
     '        };',
     '      } else {',
     '        opts = firstArg;',
@@ -247,7 +256,7 @@ const WORKER_TEMPLATE_PRE = [
     '    // Validate known agent() fields to catch API misuse early (_KNOWN_FIELDS at module scope)',
     '    const _unknownFields = Object.keys(opts).filter((k) => !_KNOWN_FIELDS.has(k));',
     '    if (_unknownFields.length > 0) {',
-    '      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel"]);',
+    '      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, maxTurns, cwd, fork, worktree, returnMeta, thinkingLevel, engine"]);',
     '    }',
     '',
     '    const callId = _callIdCounter;',
@@ -385,7 +394,14 @@ const WORKER_TEMPLATE_POST = [
     '  }',
     '})().then((result) => {',
     '  const runId = (_workerData.args && typeof _workerData.args === "object" && _workerData.args._runId) || "";',
-    '  _safePost({ type: "return", runId, result, workerLogs: _workerLogs }, "return");',
+    '  if (!_safePost({ type: "return", runId, result, workerLogs: _workerLogs }, "return")) {',
+    '    // [F1] return 值不可克隆（含 function/Symbol/循环引用 → DataCloneError）时 _safePost',
+    '    // 只能记日志返回 false——若不补救，worker 将静默 exit(0)，主线程收不到任何终态消息，',
+    '    // run 永久 running、runAndWait 悬挂。回发可克隆的 error 消息（DataCloneError 详情',
+    '    // 已由 _safePost 记入 _workerLogs 随消息带回），让主线程 handleScriptError 接管，',
+    '    // run 经既有重试矩阵收敛到终态 failed。',
+    '    _safePost({ type: "error", runId, error: "Workflow return value could not be delivered (structured-clone failed) — see workerLogs for the postMessage error", workerLogs: _workerLogs }, "error");',
+    '  }',
     '}).catch((err) => {',
     '  const runId = (_workerData.args && typeof _workerData.args === "object" && _workerData.args._runId) || "";',
     '  _safePost({ type: "error", runId, error: err.message || String(err), workerLogs: _workerLogs }, "error");',