@zhushanwen/pi-subagent-workflow 5.0.2 → 7.0.0

package/src/orchestration/args-validator.ts

@@ -0,0 +1,127 @@
+// src/orchestration/args-validator.ts
+//
+// m3：参数校验单一 chokepoint（IF3 validateRunArgs + IF4 ArgsValidationError）。
+// lifecycle.runWorkflow 首行调用——§5.3 fail-fast：参数错误在 worker 启动前返回，
+// 带「read 脚本重看」指引。
+//
+// 设计决策（m3 design-review 探针实证）：
+// - ajv 选项钉死 { coerceTypes:true, strictSchema:false, allErrors:true, useDefaults:false }：
+//   coerceTypes 原地规范化弱 LLM 的字符串参数（'false'→false、'10'→10，m2 MAJOR-1 闭环）；
+//   strictSchema:false 容忍用户 workflow 的自定义关键字/format（默认 strict:true 会误判畸形）；
+//   useDefaults:false 不注入 schema default（脚本 fallback 语义不变）。
+// - 无缓存：ajv.compile 实测 0.006ms/次（[P-compile]），v5 §6.5 的 Map 缓存被探针证据推翻。
+// - null-scan + required 空串复查：coerceTypes 下 {target:null} 会被 coerce 成 "" 放行
+//   required（required 只查属性存在性）——null 视为缺失、必填字符串空串视为失败，
+//   与 review-fix-loop 脚本的 !target 语义对齐，保住「启动前 fail-fast」承诺。
+
+import Ajv from "ajv";
+
+import type { RunSpec } from "./models/run-spec.ts";
+
+/** 参数校验失败（§5.3）。三调用方各自 catch 并映射到返回类型。 */
+export class ArgsValidationError extends Error {
+  readonly workflowName: string;
+  /** ajv 校验错误数组（畸形 schema 时为 undefined）。 */
+  readonly errors?: readonly unknown[];
+
+  constructor(workflowName: string, message: string, errors?: readonly unknown[]) {
+    super(message);
+    this.name = "ArgsValidationError";
+    this.workflowName = workflowName;
+    this.errors = errors;
+  }
+}
+
+const ajv = new Ajv({
+  coerceTypes: true,
+  strictSchema: false,
+  allErrors: true,
+  useDefaults: false,
+});
+
+/** §5.3 错误文案：workflow 名 + errors 摘要 + info 指引。 */
+function formatMessage(name: string, errors: readonly unknown[]): string {
+  const lines = errors.map((e) => {
+    let path = "/";
+    let msg = "invalid";
+    if (e !== null && typeof e === "object") {
+      const err = e as Record<string, unknown>;
+      if (typeof err.instancePath === "string" && err.instancePath) path = err.instancePath;
+      if (typeof err.message === "string") msg = err.message;
+    }
+    return `- ${path}: ${msg}`;
+  });
+  return (
+    `Invalid args for workflow '${name}': ${errors.length} error(s)\n` +
+    `${lines.join("\n")}\n` +
+    `Read the workflow script file (location from <available_workflows>) for the parameter schema and usage.`
+  );
+}
+
+/**
+ * 校验 spec.parameters（JSON Schema draft-07）对 spec.args 的约束。
+ *
+ * - spec.parameters === undefined → 跳过（安全退化：漏拷 parameters 退化是「不校验」非「校验错」）
+ * - coerceTypes 原地规范化 spec.args（worker 启动 + pause/resume 重建共用同一对象，
+ *   run.spec === spec，保证恢复路径参数一致）
+ * - 失败 throw ArgsValidationError（非原始 ajv 错误）
+ *
+ * @throws ArgsValidationError 参数不合法或 schema 无效
+ */
+export function validateRunArgs(spec: RunSpec): void {
+  const { parameters, args, scriptName } = spec;
+  if (parameters === undefined) return;
+
+  if (parameters === null || typeof parameters !== "object" || Array.isArray(parameters)) {
+    throw new ArgsValidationError(
+      scriptName,
+      `Workflow '${scriptName}' has an invalid parameter schema (expected object). Read the workflow script file (location from <available_workflows>) to inspect it.`,
+    );
+  }
+
+  // null-scan：null 值视为缺失（coerceTypes 会把 null→"" 放行 required，绕过 fail-fast）。
+  // 只删 schema 未声明 nullable 的键——type 含 "null"（如 ["string","null"]）的合法 null
+  // 输入保留（m3 exec-review M1 探针实证：全键删除会拒掉 nullable required 的合法值）。
+  const schema = parameters as Record<string, unknown>;
+  const properties =
+    schema.properties !== null && typeof schema.properties === "object"
+      ? (schema.properties as Record<string, unknown>)
+      : {};
+  for (const key of Object.keys(args)) {
+    if (args[key] !== null) continue;
+    const prop = properties[key];
+    let isNullable = false;
+    if (prop !== null && typeof prop === "object") {
+      const propType = (prop as Record<string, unknown>).type;
+      isNullable = Array.isArray(propType)
+        ? (propType as unknown[]).includes("null")
+        : propType === "null";
+    }
+    if (!isNullable) delete args[key];
+  }
+
+  let validate: ReturnType<Ajv["compile"]>;
+  try {
+    validate = ajv.compile(parameters);
+  } catch (err) {
+    // 真畸形 schema（如 type:'not-a-type'）→ 结构化 ArgsValidationError，不泄漏原始 throw
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new ArgsValidationError(
+      scriptName,
+      `Workflow '${scriptName}' has an invalid parameter schema: ${detail}. Read the workflow script file (location from <available_workflows>) to inspect it.`,
+    );
+  }
+
+  if (!validate(args)) {
+    throw new ArgsValidationError(
+      scriptName,
+      formatMessage(scriptName, validate.errors ?? []),
+      validate.errors ?? undefined,
+    );
+  }
+  // 注：非空约束由 schema 声明（minLength/pattern），chokepoint 不发明约束——
+  // m3 exec-review M2：硬编码 trim 空串复查与 schema 显式语义（enum 含 ''/minLength:0）
+  // 矛盾。review-fix-loop 的 target 用 { minLength: 1, pattern: '\\S' } 表达。
+  // 校验失败时 spec.args 可能已被 null-scan/coerce 部分 mutate（文档化行为：失败后
+  // 调用方不应复用该 args 对象）。
+}

package/src/orchestration/config-loader.ts

@@ -2,19 +2,30 @@
  * Workflow Config Loader — 统一资源发现版（ADR-031）
  *
  * 扫描逻辑委托给 shared/resource-discovery（与 agent 发现共享同一套扫描源）。
- * 本文件只保留 workflow 专属的 meta 提取（regex）+ 60s TTL 缓存。
+ * 本文件只保留 workflow 专属的 meta 提取（经 shared/meta-parser.ts IF1 统一 parser）+ 60s TTL 缓存。
+ *
+ * m2 收敛：删 extractMetaViaRegex + safeEvalObject(new Function)，改调 parseResourceMeta
+ * （真实 YAML 解析 @pi-meta 块注释，发现期不执行作者代码，v5 原则 6 no-eval）。
+ * toCachedMeta 整对象透传（...meta），不再 {name,description,phases} 解构——消灭第 1 处重映射。
  *
  * Failed imports are marked available=false — the loader never throws.
  */
 
-import { readFile } from "node:fs/promises";
+
 import { resolve } from "node:path";
 
-// WorkflowMeta / WorkflowSource 的规范来源是 engine/models/workflow-script.ts
-import type { WorkflowMeta, WorkflowSource } from "./models/workflow-script.ts";
+// WorkflowMeta 规范来源是 shared/resource-meta.ts（m1 DM1）；WorkflowSource 来自 workflow-script
+import type { WorkflowSource } from "./models/workflow-script.ts";
+import type { WorkflowMeta } from "../shared/resource-meta.ts";
+import { getCachedFile, getCachedFileContent, clearFileCache } from "../shared/resource-discovery.ts";
+import { parseResourceMeta } from "../shared/meta-parser.ts";
+import { normalizeRef, WORKFLOW_REF_EXT } from "../shared/agent-ref.ts";
 export type { WorkflowMeta, WorkflowSource };
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("config-loader");
 
 import {
   discoverResources,
@@ -36,20 +47,15 @@ export interface CachedWorkflowMeta extends WorkflowMeta {
 
 // ── Internal types ────────────────────────────────────────────
 
-interface WorkerResult {
-  success: boolean;
-  meta?: WorkflowMeta;
-  error?: string;
-}
-
 interface CacheEntry {
   meta: CachedWorkflowMeta;
-  cachedAt: number;
+  /** 文件 mtime（m5：mtime 键控判失效——删 60s TTL，mtime 未变即命中）。 */
+  mtimeMs: number;
 }
 
 // ── Constants ─────────────────────────────────────────────────
 
-const CACHE_TTL_MS = 60_000;
+// m5：删 60s TTL——mtime 键控判失效（TTL 只服务 getWorkflow 且造成 60s 陈旧窗口）。
 
 // ── Cache ─────────────────────────────────────────────────────
 
@@ -66,7 +72,9 @@ function getCacheBucket(workspaceRoot: string): Map<string, CacheEntry> {
 }
 
 function isCacheValid(entry: CacheEntry): boolean {
-  return Date.now() - entry.cachedAt < CACHE_TTL_MS;
+  // m5：mtime 判变——文件 mtime 未变即命中（删 TTL 后文件变更立即反映）
+  const file = getCachedFile(entry.meta.path);
+  return file !== null && file.mtimeMs === entry.mtimeMs;
 }
 
 // ── Helpers ───────────────────────────────────────────────────
@@ -78,71 +86,6 @@ function stem(filePath: string): string {
   return dot > 0 ? base.slice(0, dot) : base;
 }
 
-// ── Regex-based meta extraction ─────────────────────────────
-
-/**
- * Extract the `meta` object from a workflow script using regex.
- *
- * This avoids executing user code (no Worker/import/require), so it works
- * regardless of whether the script uses CJS, ESM, top-level await, or
- * references runtime globals like `agent` or `$ARGS`.
- *
- * Supports both `const meta = { ... }` and `export const meta = { ... }`.
- */
-async function extractMetaViaRegex(scriptPath: string): Promise<WorkerResult> {
-  try {
-    const content = await readFile(scriptPath, "utf-8");
-
-    const metaPattern = /(?:export\s+)?const\s+meta\s*=\s*(\{[^]*?\});?\s*$/m;
-    const match = metaPattern.exec(content);
-    if (!match) {
-      return { success: false, error: "No 'const meta = { ... }' declaration found" };
-    }
-
-    const metaObj = safeEvalObject(match[1]);
-    if (!metaObj || typeof metaObj !== "object") {
-      return { success: false, error: "Failed to parse meta object" };
-    }
-
-    if (typeof metaObj.name !== "string") {
-      return { success: false, error: "meta.name must be a string" };
-    }
-
-    return {
-      success: true,
-      meta: {
-        name: metaObj.name,
-        description: typeof metaObj.description === "string" ? metaObj.description : "",
-        phases: Array.isArray(metaObj.phases)
-          ? metaObj.phases.filter(
-              (p: unknown) => typeof p === "string" || (typeof p === "object" && p !== null && "title" in p),
-            ) as (string | { title: string; detail?: string })[]
-          : [],
-      },
-    };
-  } catch (err) {
-    return { success: false, error: err instanceof Error ? err.message : String(err) };
-  }
-}
-
-/**
- * Safely evaluate a simple object literal string.
- * Uses `new Function` to avoid eval while still supporting basic JS
- * literal syntax (strings, numbers, arrays, nested objects).
- */
-function safeEvalObject(literal: string): Record<string, unknown> | undefined {
-  try {
-    const fn = new Function(`return (${literal});`);
-    const result = fn();
-    if (typeof result === "object" && result !== null && !Array.isArray(result)) {
-      return result as Record<string, unknown>;
-    }
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 // ── ResourceSource → WorkflowSource 映射 ─────────────────────
 
 /** 统一模块的 ResourceSource 映射为 workflow 的 saved/tmp 语义 */
@@ -150,29 +93,40 @@ function toWorkflowSource(source: ResourceSource): WorkflowSource {
   return source === "project-pi-tmp" ? "tmp" : "saved";
 }
 
-// ── 单文件 → CachedWorkflowMeta ───────────────────────────────
+// ── 单文件 → CachedWorkflowMeta（IF1 parseResourceMeta + 整对象透传）──
 
-/** 提取单个文件的 meta，失败时标 available=false（与原行为一致） */
+/**
+ * 提取单个文件的 meta（经 IF1 parseResourceMeta），失败时标 available=false（fail-safe 不抛）。
+ *
+ * m2：整对象透传（...meta），不再 {name,description,phases} 解构——消灭第 1 处重映射，
+ * parameters/usage/when/notFor 一路流到 script.meta。仅认 @pi-meta 新格式（D1 无 adapter）。
+ */
 async function toCachedMeta(
   filePath: string,
   source: ResourceSource,
 ): Promise<CachedWorkflowMeta> {
   const fallbackName = stem(filePath);
-  const result = await extractMetaViaRegex(filePath);
   const wfSource = toWorkflowSource(source);
-
-  if (result.success && result.meta) {
-    return {
-      name: result.meta.name,
-      description: result.meta.description,
-      phases: result.meta.phases,
-      path: filePath,
-      available: true,
-      source: wfSource,
-    };
+  try {
+    const content = getCachedFileContent(filePath); // m5：统一 mtime 缓存层
+    if (content === null) throw new Error("file not readable");
+    const meta = parseResourceMeta(content, "workflow");
+    if (meta && meta.kind === "workflow") {
+      return { ...meta, path: filePath, available: true, source: wfSource };
+    }
+    // m2 exec-review MINOR-4：文件可读但 meta=null → 旧 const meta 格式或格式错误，
+    // 静默 available=false（D1 无 adapter）。warn 帮助用户定位需迁移到 @pi-meta 的存量 workflow。
+    logger.warn(
+      `[config-loader] ${filePath}: 未解析到 @pi-meta 元数据（旧 const meta 格式需迁移）→ available=false`,
+    );
+  } catch (err) {
+    // 读失败 → available=false（fail-safe 不抛，与原行为一致）
+    logger.debug(`[config-loader] skip unreadable workflow file ${filePath}`, {
+      reason: err instanceof Error ? err.message : String(err),
+    });
   }
-
   return {
+    kind: "workflow",
     name: fallbackName,
     description: "",
     phases: [],
@@ -268,9 +222,9 @@ export async function discoverWorkflows(
 
   // Update cache (scoped to current workspace root)
   const bucket = getCacheBucket(workspaceRoot);
-  const now = Date.now();
   for (const wf of merged) {
-    bucket.set(wf.name, { meta: wf, cachedAt: now });
+    const file = getCachedFile(wf.path);
+    bucket.set(wf.name, { meta: wf, mtimeMs: file?.mtimeMs ?? 0 });
   }
 
   return merged;
@@ -304,10 +258,25 @@ export async function getWorkflow(name: string): Promise<CachedWorkflowMeta | un
   return workflows.find((wf) => wf.name === name);
 }
 
+/**
+ * 按绝对路径加载单个 workflow（workflowRef 统一解析入口——S2 路径统一）。
+ *
+ * - ~/ 前缀展开；相对路径/非 .js 引用返回 undefined（引用唯一形态 = 绝对路径）
+ * - 任意路径（不限扫描源）：内置包内脚本、用户任意位置脚本均可执行
+ * - meta 提取失败/文件不可读 → available=false（fail-safe，不抛）
+ */
+export async function getWorkflowByPath(ref: string): Promise<CachedWorkflowMeta | undefined> {
+  const filePath = normalizeRef(ref, WORKFLOW_REF_EXT);
+  if (filePath === null) return undefined;
+  return toCachedMeta(filePath, "user-pi");
+}
+
 /**
  * Invalidate the internal meta cache.
  * The next call to loadWorkflows or getWorkflow will re-scan directories.
  */
 export function invalidateCache(): void {
+  // m5：清统一 mtime 缓存层 + bucket（测试隔离 + mtime 漏判场景手动刷新兜底）
+  clearFileCache();
   cache.clear();
 }

package/src/orchestration/error-recovery.ts

@@ -279,15 +279,12 @@ function dispatchAgentCall(
         : undefined,
   };
 
- // BL-1：解析 agent/skill/schema → systemPromptFiles / skillPath / schemaEnv。
- // D-12 重构误删 resolveAgentOpts，导致 inline override 静默失效。此处从
- // LifecycleDeps 取 agentRegistry/sessionDir/activeTempFiles（per-session，由
- // Interface 层 session_start 注入），调 resolveAgentOpts 解析 inline override。
- // 解析失败（agent/skill 未找到、临时文件写入错）走 error 路径，不发 slot、不 spawn。
-  const hasResolverDeps = deps.agentRegistry && deps.sessionDir && deps.activeTempFiles;
-  const resolved = hasResolverDeps
-    ? resolveAgentOpts(opts, deps.agentRegistry!, deps.sessionDir!, deps.activeTempFiles!)
-    : { opts };
+ // BL-1：解析 skill/schema → skillPath / schemaEnv / appendSystemPrompt。
+ // M2 修正后 resolveAgentOpts 单参数，只处理 schema SO 指令（内容直传）+ skill。
+ // agent ref 处理（systemPrompt/model/thinkingLevel）交 resolveIdentity（经
+ // getAgentConfig + resolveModel 完整覆盖），消除双重注入与 model 层级混乱。
+ // 解析失败（skill 未找到）走 error 路径，不发 slot、不 spawn。
+  const resolved = resolveAgentOpts(opts);
   if (resolved.error) {
     const call = new AgentCall(msg.callId, opts, node);
     call.markRunning();

package/src/orchestration/launcher.ts

@@ -25,6 +25,7 @@
  * 参考：domain-models.md §D-8（WorkflowRunResult 签名）、clarification.md C.7。
  */
 
+import { ArgsValidationError } from "./args-validator.ts";
 import { abortRun, runWorkflow } from "./lifecycle.ts";
 import type { LifecycleDeps } from "./models/ports.ts";
 import type { RunSpec } from "./models/run-spec.ts";
@@ -177,8 +178,8 @@ export async function runAndWait(
   signal?: AbortSignal,
   timeoutMs: number = DEFAULT_RUNANDWAIT_TIMEOUT_MS,
 ): Promise<WorkflowRunResult> {
- // 1. registry 查找脚本
-  const script = await deps.registry.get(name);
+ // 1. registry 查找脚本（workflowRef = 绝对路径，S2 路径统一）
+  const script = await deps.registry.getPath(name);
   if (!script) {
     return {
       status: "done",
@@ -210,12 +211,31 @@ export async function runAndWait(
     scriptName: script.name,
     scriptPath: script.path,
     description: script.meta.description,
+    parameters: script.meta.parameters,
   };
 
  // 4. 启动 workflow + 5. 轮询至 done（含 6. timeout → abortRun，C.7）
  // pending-notification 的 register/unregister 由 runWorkflow（启动注册）+
  // transition("done") 路径（完成注销）统一处理，runAndWait 不再重复 emit。
-  const runId = await runWorkflow(spec, deps, signal);
+ // m3：chokepoint 校验失败（ArgsValidationError）→ 返回 invalid_args 结果（run 从未
+ // 创建，runId 恒 ''），非 ArgsValidationError 保持传播。
+  let runId: string;
+  try {
+    runId = await runWorkflow(spec, deps, signal);
+  } catch (err) {
+    if (err instanceof ArgsValidationError) {
+      // 注：WorkflowRunResult.reason 是 pi.__workflowRun 的跨扩展公开类型——新增
+      // 'invalid_args' 成员是对外部消费方的契约变更（m3 exec-review m5）；该 reason
+      // 永不进 run.state.reason（run 从未创建），仅存在于本合成返回值。
+      return {
+        status: "done",
+        reason: "invalid_args",
+        runId: "",
+        error: err.message,
+      };
+    }
+    throw err;
+  }
   return pollRunToResult(runId, deps, signal, timeoutMs, "Aborted by signal");
 }
 
@@ -293,47 +313,56 @@ export async function executeNestedWorkflow(
     }
   }
 
- // Step 3: registry 查找 + lint（失败返回 error result，不抛错）
-  const script = await deps.registry.get(name);
-  if (!script) {
-    return { content: "", error: `Workflow '${name}' not found` };
-  }
-  const lintResult = script.validate();
-  if (!lintResult.valid) {
-    const errors = lintResult.findings
-      .filter((f) => f.severity === "error")
-      .map((f) => `L${f.line}: ${f.message}`)
-      .join("; ");
-    return {
-      content: "",
-      error: `Workflow script '${name}' has lint errors: ${errors}`,
-    };
-  }
+ // Step 3+：registry 查找 + lint + RunSpec + runWorkflow + poll 全程 try（m3 E8——
+ // try 起点提到 Step 2 的 listener 注册之后，覆盖 Step 3-6。runWorkflow throw
+ // （含 chokepoint ArgsValidationError）与 not found/lint 早返回均走 finally 移除
+ // parentSignal listener——修复原 try 外 runWorkflow 的泄漏路径）。
+  try {
+    // Step 3: registry 查找 + lint（失败返回 error result，不抛错）
+    const script = await deps.registry.getPath(name);
+    if (!script) {
+      return { content: "", error: `Workflow '${name}' not found` };
+    }
+    const lintResult = script.validate();
+    if (!lintResult.valid) {
+      const errors = lintResult.findings
+        .filter((f) => f.severity === "error")
+        .map((f) => `L${f.line}: ${f.message}`)
+        .join("; ");
+      return {
+        content: "",
+        error: `Workflow script '${name}' has lint errors: ${errors}`,
+      };
+    }
 
- // Step 4: 构建 RunSpec（共享父 Budget + 循环链）+ 启动子 workflow
- // budget 共享（F-7 方案 B）：子 run 直接复用父 Budget 引用（budgetRef），consume 实时
- // 累加到父 Budget，消除并行嵌套下的超支窗口，无需 Step 6 的 sync-back。
-  const spec: RunSpec = {
-    scriptSource: script.toExecutable(),
-    args,
-    budgetRef: parentRun.state.budget,
-    scriptName: script.name,
-    scriptPath: script.path,
-    description: script.meta.description,
-    parentWorkflowChain: chain,
-  };
-  const runId = await runWorkflow(spec, deps, childController.signal);
+    // Step 4: 构建 RunSpec（共享父 Budget + 循环链）+ 启动子 workflow
+    // budget 共享（F-7 方案 B）：子 run 直接复用父 Budget 引用（budgetRef），consume 实时
+    // 累加到父 Budget，消除并行嵌套下的超支窗口，无需 Step 6 的 sync-back。
+    const spec: RunSpec = {
+      scriptSource: script.toExecutable(),
+      args,
+      budgetRef: parentRun.state.budget,
+      // Run-level override 传播（与父 run 对齐）：子 run 继承父 run 的 model/thinkingLevel，
+      // 否则嵌套 workflow 丢失父 run 的模型指定，回落主 agent 模型。
+      model: parentRun.spec.model,
+      thinkingLevel: parentRun.spec.thinkingLevel,
+      scriptName: script.name,
+      scriptPath: script.path,
+      description: script.meta.description,
+      parameters: script.meta.parameters,
+      parentWorkflowChain: chain,
+    };
+    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。
- //  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;
+    // Step 5: 轮询至 done（复用 runAndWait 的轮询逻辑）
+    // [H-1] 嵌套 workflow timeout 从父 run 继承：父 spec.budgetTimeMs 存在时取
+    //  min(父 budget, DEFAULT)，让子 run 不超出父 run 的剩余时间预算；否则用 DEFAULT。
+    //  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;
 
-  try {
     const result = await pollRunToResult(
       runId,
       deps,
@@ -360,6 +389,13 @@ export async function executeNestedWorkflow(
       content: "",
       error: result.error ?? `Workflow '${name}' ended: ${result.reason}`,
     };
+  } catch (err) {
+    // m3：chokepoint 校验失败 → {error}（§5.3 指引文案），非 ArgsValidationError 保持传播
+    // （dispatchWorkflowCall 的 .catch 兜底转 postResult，worker 不崩）。
+    if (err instanceof ArgsValidationError) {
+      return { content: "", error: err.message };
+    }
+    throw err;
   } finally {
     // [L-2] 子 run done 后移除 parentSignal listener，避免累积（{ once: true } 在
     //  正常完成路径下不会自动触发，listener 残留；多次嵌套调用会泄漏到 parentSignal）。

package/src/orchestration/lifecycle.ts

@@ -32,6 +32,7 @@
 
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
+import { validateRunArgs } from "./args-validator.ts";
 import { ConcurrencyGate, DEFAULT_CONCURRENCY } from "./concurrency-gate.ts";
 import {
   handleWorkerError,
@@ -147,6 +148,12 @@ export async function runWorkflow(
   deps: LifecycleDeps,
   signal?: AbortSignal,
 ): Promise<string> {
+  // m3 E9：参数校验单一 chokepoint，钉在所有副作用前（generateRunId/log/signal
+  // listener/runs.set/workerHost.start/store.save/pending:register）。校验失败时
+  // zero side effects。coerceTypes 原地规范化 spec.args——worker 启动与 pause/resume
+  // 重建共用同一对象（run.spec === spec），恢复路径参数一致。
+  validateRunArgs(spec);
+
   const runId = generateRunId();
   deps.log?.("debug", "workflow:lifecycle", "runWorkflow start", { runId, scriptName: spec.scriptName });
 

package/src/orchestration/models/ports.ts

@@ -10,7 +10,6 @@
  *
  * 层归属：Engine。零 infra 依赖（AC-1）。
  */
-import type { AgentRegistry } from "../../execution/agent-registry.ts";
 import type { StreamSink, SubagentStream } from "../../execution/stream-sink.ts";
 import type { AgentEvent } from "../../shared/agent-event.ts";
 import type { WorkerHandle } from "../worker-handle.ts";
@@ -126,19 +125,6 @@ export interface LifecycleDeps {
  */
   log?: (level: "debug" | "info" | "warn" | "error", component: string, message: string, data?: unknown) => void;
  /**
- * BL-1：agent/skill/schema 解析依赖（per-session，可选）。
- *
- * Interface 层 factory 在 session_start 注入：agentRegistry（扫描 .agents/agents 等
- * 7 路径）、sessionDir（临时文件根）、activeTempFiles（session_shutdown 回收集合）。
- * error-recovery.dispatchAgentCall 用这 3 项调 resolveAgentOpts，把
- * `agent({agent,skill,schema})` 的 inline override 解析成 systemPromptFiles /
- * skillPath / schemaEnv，否则 pi 子进程只收到原始 prompt（D-12 重构误删导致回归）。
- * 全部可选——测试 makeDeps 工厂无需改。
- */
-  agentRegistry?: AgentRegistry;
-  sessionDir?: string;
-  activeTempFiles?: Set<string>;
- /**
  * D-12 regression fix (round-2 #2)：rebuildRuntime 重新调度 run 级墙钟预算计时器。
  *
  * worker/script 错误重试走 replaceRuntime，旧 RunRuntime 的 release 会 clearTimeout

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

@@ -24,8 +24,31 @@ import type { Budget } from "./budget.ts";
 export interface RunSpec {
  /** 已 strip export 的可执行源（WorkflowScript.toExecutable 产物）。 */
   readonly scriptSource: string;
- /** 调用方传入的参数（worker 内通过 $ARGS 访问）。 */
+ /**
+ * 参数契约（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 启动与 pause/resume 重建共用同一对象）。
+ */
+  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 调度）。 */