@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/orchestration/__tests__/__fixtures__/worker-template.snapshot.txt

@@ -88,6 +88,8 @@ function _safePost(msg, context) {
       const pending = _pendingCalls.get(msg.callId);
       if (pending) {
         _pendingCalls.delete(msg.callId);
+        // [OR-3] 结果已到，清除 per-call 超时 timer（有 timer 才清，防御旧 pending 无该字段）
+        if (pending.timer) { clearTimeout(pending.timer); }
         if (typeof msg.result !== "undefined") {
           _callCache.set(msg.callId, msg.result);
         }
@@ -124,11 +126,16 @@ function _safePost(msg, context) {
       const pending = _pendingCalls.get(msg.callId);
       if (pending) {
         _pendingCalls.delete(msg.callId);
+        // [OR-3] 结果已到，清除 per-call 超时 timer（workflow() 当前不挂 timer，防御性对称清理）
+        if (pending.timer) { clearTimeout(pending.timer); }
         pending.resolve(msg.result);
       }
     } else if (msg.type === "abort") {
+      // [OR-3] 主线程 abortRun/terminateRunningRuns 的优雅解阻广播：全部 pending
+      // reject（脚本 catch WorkflowAbortedError 可感知取消）+ 清理 timer + 清 Map。
+      // 后续迟到结果命中空 Map（no-op），不产主线程 unhandledRejection。
       const err = new WorkflowAbortedError(msg.reason);
-      _pendingCalls.forEach((p) => { p.reject(err); });
+      _pendingCalls.forEach((p) => { if (p.timer) { clearTimeout(p.timer); } p.reject(err); });
       _pendingCalls.clear();
     } else if (msg.type === "budget-update" && msg.budget) {
       _budgetData._spentTokens = msg.budget.usedTokens ?? _budgetData._spentTokens;
@@ -141,7 +148,11 @@ function _safePost(msg, context) {
   function phase(name) { _currentPhase = String(name); }
 
   function log(msg) {
-    try { parentPort.postMessage({ type: "log", phase: _currentPhase, message: String(msg) }); } catch(e) { /* swallow */ }
+    var _logText = String(msg);
+    // [B-3] 单通路：只发独立 {type:"log"} 消息，主线程 handleWorkerLog 即时消费
+    //（push 进 errorLogs）。不再同时记入 _workerLogs——旧双通路让同一日志随
+    // return/error 的 workerLogs 再带回一份，errorLogs 占两格、TUI 双份。
+    try { parentPort.postMessage({ type: "log", phase: _currentPhase, message: _logText }); } catch(e) { /* swallow */ }
   }
 
   async function agent(firstArg, secondArg) {
@@ -158,6 +169,9 @@ function _safePost(msg, context) {
         // step 级 turn 上限（turn limiter；显式 0/负 = 显式不限，压过 spawn watchdog env 兑底，SP-6）
         // ?? 语义保真：仅 null/undefined 归 undefined（走 env 兑底），显式 0 保留（U5 参数 > env）
         maxTurns: (secondArg && typeof secondArg === "object" ? secondArg.maxTurns : undefined) ?? undefined,
+        // [OR-3] per-call timeoutMs 透传（string 分支此前丢弃该字段——对象分支已有；
+        // worker pending 消息层超时依赖它流到 agent-call 消息）
+        timeoutMs: (secondArg && typeof secondArg === "object" ? secondArg.timeoutMs : undefined),
         // P4 D9③：step 级 engine 显式指定（仅限必须某引擎独有能力的场景）
         engine: (secondArg && typeof secondArg === "object" && secondArg.engine) || undefined,
       };
@@ -233,7 +247,32 @@ function _safePost(msg, context) {
       return Promise.reject(new Error("postMessage failed for agent-call (callId=" + callId + "): see workerLogs"));
     }
     return new Promise((resolve, reject) => {
-      _pendingCalls.set(callId, { resolve, reject, returnMeta: opts.returnMeta === true });
+      const _pending = { resolve: resolve, reject: reject, returnMeta: opts.returnMeta === true, timer: undefined };
+      // [OR-3] per-call timeoutMs：消息层自己的超时——主线程对 agent-call 永不回话
+      //（畸形消息丢弃 / postMessage 双重失败 / runner 不 settle）时 pending 不再永挂
+      //（旧实现零超时 → agent() 永挂 → worker 不退出 → run 永久 running）。
+      // 超时以错误 resolve（对齐 agent-result 失败容错策略：不 reject、不把单点超时
+      // 放大成脚本 error → rebuild），并记入 _workerLogs 留诊断。仅显式 timeoutMs > 0
+      // 启用（缺省不限，与 runner 侧 per-call timeout 语义一致）。timer unref：脚本
+      // 已 return 时残留 timer 不延迟 worker 自然退出。
+      if (typeof opts.timeoutMs === "number" && opts.timeoutMs > 0) {
+        _pending.timer = setTimeout(() => {
+          if (!_pendingCalls.delete(callId)) { return; }
+          const _timeoutMsg = "agent call timed out after " + opts.timeoutMs + "ms (callId=" + callId + ") — no agent-result received from main thread";
+          _pushWorkerLog("warn", ["[workflow] " + _timeoutMsg]);
+          if (opts.returnMeta === true) {
+            _pending.resolve({ value: "", error: _timeoutMsg });
+          } else {
+            // [B-5] 非 returnMeta 超时 resolve 单值错误消息字符串（对齐 agent-result
+            // 失败路径 resolve 单值 _value = parsedOutput ?? content 的形态）——
+            // 旧实现 resolve {content:"", error} 对象，字符串消费型脚本（r.trim() 类）
+            // 在超时路径 TypeError。
+            _pending.resolve(_timeoutMsg);
+          }
+        }, opts.timeoutMs);
+        if (_pending.timer && typeof _pending.timer.unref === "function") { _pending.timer.unref(); }
+      }
+      _pendingCalls.set(callId, _pending);
     });
   }
 

package/src/orchestration/__tests__/agent-call-catch-fallback.test.ts

@@ -12,11 +12,12 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import { handleWorkerMessage } from "../error-recovery.ts";
+import { handleWorkerMessage } from "../worker-message-pump.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
 import { Trace } from "../models/trace.ts";
 import type { WorkflowRun } from "../models/workflow-run.ts";
 import type { AgentResult } from "../models/types.ts";
+import { flushMicrotasks } from "./helpers/flush-microtasks.ts";
 
 // ── helpers ──────────────────────────────────────────────────
 
@@ -189,10 +190,7 @@ describe("U7b: AbortError 不回发 agent-result", () => {
       // 先 flush 微任务队列（多次确保 withSlot promise 已 settle），
       // 再断言断言期内无 agent-result。vi.waitFor 用反向断言会一满足就 return，
       // 故采用：跑若干 microtask tick 后静态断言。
-      for (let i = 0; i < 5; i++) {
-        // eslint-disable-next-line no-await-in-loop -- 排空微任务队列的固定 tick 循环（vi.waitFor 反向断言会一满足即返回，不适用），非逐项等待
-        await Promise.resolve();
-      }
+      await flushMicrotasks(5);
       const posted = findAgentResultPost(postMessage, 3);
       expect(posted).toBeUndefined();
     } finally {

package/src/orchestration/__tests__/agent-call-stream.test.ts

@@ -8,7 +8,7 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import { handleWorkerMessage } from "../error-recovery.ts";
+import { handleWorkerMessage } from "../worker-message-pump.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
 import { Trace } from "../models/trace.ts";
 import type { WorkflowRun } from "../models/workflow-run.ts";
@@ -122,7 +122,7 @@ describe("U5: widgetKey 格式", () => {
       expect(setWidget.mock.calls.length).toBeGreaterThanOrEqual(1);
     });
 
-    const widgetKey = setWidget.mock.calls[0][0] as string;
+    const widgetKey = setWidget.mock.calls[0]![0] as string;
     expect(widgetKey).toBe("subagent-stream-wf-test-123-2");
   });
 });

package/src/orchestration/__tests__/args-meta.test.ts

@@ -0,0 +1,358 @@
+// src/orchestration/__tests__/args-meta.test.ts
+//
+// U9（args-meta）单元测试。fixture = 既有 workflow 资产 @pi-meta parameters
+// （packages/subagent-core/workflows/，经 core 自有 parseResourceMeta 解析——与
+// pi-sw detectors.test.ts 同源同解析器，防 fixture 漂移）。
+//
+// 等值对照：PI_TOOL_TOP_LEVEL 注入后复刻 pi-sw detectors.test.ts TC3a-TC3i 场景
+// （u-core-args 验收条款②「pi-sw 既有 findFlattenedArgKeys 行为等值」的锚定面）。
+// 对照锚常量抄自 extensions/universal/subagent-workflow/src/interface/tool-workflow.ts
+// TOOL_TOP_LEVEL（m6 定稿值）——pi-sw 侧若演进，对照测试同步刷新即暴露语义分叉。
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { parseResourceMeta } from "../../shared/meta-parser.ts";
+import {
+  argKeysFromMeta,
+  findFlattenedArgKeys,
+  normalizeArgsByMeta,
+} from "../args-meta.ts";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const WORKFLOWS_DIR = join(here, "..", "..", "..", "workflows");
+
+/** 解析既有 workflow 资产的 @pi-meta parameters（真实资产 fixture，禁合成替代）。 */
+function loadWorkflowParameters(name: string): Record<string, unknown> {
+  const src = readFileSync(join(WORKFLOWS_DIR, `${name}.js`), "utf8");
+  const meta = parseResourceMeta(src, "workflow");
+  if (!meta || meta.kind !== "workflow" || !meta.parameters) {
+    throw new Error(`fixture 损坏：${name} 无 workflow meta 或无 parameters`);
+  }
+  return meta.parameters;
+}
+
+const CHAIN_PARAMS = loadWorkflowParameters("chain");
+const RFL_PARAMS = loadWorkflowParameters("review-fix-loop");
+const MAP_REDUCE_PARAMS = loadWorkflowParameters("map-reduce");
+
+/**
+ * pi workflow tool 顶层键集（对照锚，抄自 pi-sw tool-workflow.ts TOOL_TOP_LEVEL，
+ * 含 model/thinkingLevel 升格注释）——reservedKeys 宿主注入形态的等值对照基准。
+ */
+const PI_TOOL_TOP_LEVEL = new Set([
+  "action",
+  "name",
+  "slug",
+  "runId",
+  "args",
+  "tokens",
+  "time",
+  "error",
+  "model",
+  "thinkingLevel",
+]);
+
+/** pi 等值形态：reservedKeys 注入 pi TOOL_TOP_LEVEL 后的平铺检测（宿主注入消费位）。 */
+function piFindFlattened(params: unknown, meta: Record<string, unknown>): string[] {
+  return findFlattenedArgKeys(params, meta, { reservedKeys: PI_TOOL_TOP_LEVEL });
+}
+
+describe("argKeysFromMeta（schema → 已知参数键集）", () => {
+  it("真实资产 chain.js：exact = properties 键集（task/agents）", () => {
+    const { exact, patterns } = argKeysFromMeta(CHAIN_PARAMS);
+    expect([...exact].sort()).toEqual(["agents", "task"]);
+    expect(patterns).toEqual([]);
+  });
+
+  it("真实资产 review-fix-loop.js：exact 16 键 + patternProperties 正则（^batch\\d+$）", () => {
+    const { exact, patterns } = argKeysFromMeta(RFL_PARAMS);
+    // properties 键（schema 定义序）
+    expect([...exact]).toEqual([
+      "targetType",
+      "target",
+      "autoCommit",
+      "maxRounds",
+      "stuckThreshold",
+      "skipCleanAgents",
+      "recheckAfterFix",
+      "fixAgent",
+      "maxFixAttempts",
+      "convergeNewIssues",
+      "convergeRounds",
+      "aggregatorModel",
+      "reviewPrompt",
+      "fixPrompt",
+      "fallowScan",
+      "agents",
+      "batchNames",
+    ]);
+    expect(patterns).toHaveLength(1);
+    expect(patterns[0].source).toBe("^batch\\d+$");
+    // pattern 语义：数字后缀命中、拼错不命中（m6 评审 C-1）
+    expect(patterns[0].test("batch1")).toBe(true);
+    expect(patterns[0].test("batch12")).toBe(true);
+    expect(patterns[0].test("batchl")).toBe(false);
+  });
+
+  it("空 meta（undefined / null / 非对象）→ 空键集（legacy const-meta 检测跳过）", () => {
+    expect(argKeysFromMeta(undefined)).toEqual({ exact: new Set(), patterns: [] });
+    expect(argKeysFromMeta(null)).toEqual({ exact: new Set(), patterns: [] });
+    expect(argKeysFromMeta("not-an-object" as unknown as Record<string, unknown>)).toEqual({
+      exact: new Set(),
+      patterns: [],
+    });
+  });
+
+  it("meta 无 properties/patternProperties（如仅 type:object）→ 空键集", () => {
+    const { exact, patterns } = argKeysFromMeta({ type: "object" });
+    expect(exact.size).toBe(0);
+    expect(patterns).toEqual([]);
+  });
+
+  it("reservedKeys 注入：撞名参数键从 exact 排除（m6 评审 M-3 撞名保护）", () => {
+    const synthetic = {
+      type: "object",
+      properties: { name: { type: "string" }, task: { type: "string" } },
+      required: ["name"],
+    };
+    const keys = argKeysFromMeta(synthetic, { reservedKeys: PI_TOOL_TOP_LEVEL });
+    expect(keys.exact.has("task")).toBe(true);
+    expect(keys.exact.has("name")).toBe(false); // pi TOOL_TOP_LEVEL 排除（M-3 真回归锁定）
+    // 缺省（无 reservedKeys）不排除——core 中性形态
+    const bare = argKeysFromMeta(synthetic);
+    expect(bare.exact.has("name")).toBe(true);
+  });
+
+  it("能命中 reservedKeys 的 pattern 整条跳过（m6 exec-review S1：^run.*$ 不误伤 runId）", () => {
+    const synthetic = {
+      type: "object",
+      properties: { task: { type: "string" } },
+      patternProperties: { "^run.*$": { type: "string" }, "^batch\\d+$": { type: "string" } },
+    };
+    const keys = argKeysFromMeta(synthetic, { reservedKeys: PI_TOOL_TOP_LEVEL });
+    expect(keys.patterns).toHaveLength(1);
+    expect(keys.patterns[0].source).toBe("^batch\\d+$");
+  });
+
+  it("非法 pattern 跳过不抛（双保险通路，与 pi logger.warn+跳过等值）", () => {
+    const synthetic = {
+      type: "object",
+      patternProperties: { "([": { type: "string" }, "^ok\\d+$": { type: "string" } },
+    };
+    const keys = argKeysFromMeta(synthetic);
+    expect(keys.patterns).toHaveLength(1);
+    expect(keys.patterns[0].source).toBe("^ok\\d+$");
+  });
+});
+
+describe("findFlattenedArgKeys（args 平铺检测——pi-sw 行为等值对照）", () => {
+  it("TC3a: trigger——chain 参数集平铺 task 被识别；跨 workflow 区分（items 非 chain 参数不触发）", () => {
+    expect(piFindFlattened({ action: "run", name: "chain", task: "x" }, CHAIN_PARAMS)).toEqual(["task"]);
+    expect(piFindFlattened({ action: "run", name: "chain", items: ["a"] }, CHAIN_PARAMS)).toEqual([]);
+  });
+
+  it("TC3b: 嵌套 args 不触发", () => {
+    expect(
+      piFindFlattened({ action: "run", name: "x", args: { task: "x", items: ["a"] } }, CHAIN_PARAMS),
+    ).toEqual([]);
+  });
+
+  it("TC3c: 顶层 + args 内共存不触发（args-排除保留）", () => {
+    expect(
+      piFindFlattened({ action: "run", name: "x", args: { task: "x" }, task: "y" }, CHAIN_PARAMS),
+    ).toEqual([]);
+  });
+
+  it("TC3d: 无已知键不触发；空集不触发", () => {
+    expect(piFindFlattened({ action: "run", name: "x", args: {} }, CHAIN_PARAMS)).toEqual([]);
+    expect(findFlattenedArgKeys({ action: "status" }, undefined)).toEqual([]);
+  });
+
+  it("TC3e: review-fix-loop fixAgent 平铺被识别（动态集 exact）", () => {
+    expect(
+      piFindFlattened({ action: "run", name: "review-fix-loop", fixAgent: "worker" }, RFL_PARAMS),
+    ).toEqual(["fixAgent"]);
+    expect(
+      piFindFlattened({ action: "run", name: "review-fix-loop", args: { fixAgent: "worker" } }, RFL_PARAMS),
+    ).toEqual([]);
+  });
+
+  it("TC3f: batchN 经 pattern 触发 + batchl 拼错不触发（数字后缀语义）", () => {
+    expect(
+      piFindFlattened({ action: "run", name: "review-fix-loop", targetType: "git-diff", target: "main" }, RFL_PARAMS),
+    ).toEqual(["targetType", "target"]);
+    expect(
+      piFindFlattened({ action: "run", name: "review-fix-loop", batch1: "reviewer", autoCommit: true }, RFL_PARAMS),
+    ).toEqual(["batch1", "autoCommit"]);
+    expect(
+      piFindFlattened({ action: "run", name: "review-fix-loop", args: { targetType: "git-diff", target: "main" } }, RFL_PARAMS),
+    ).toEqual([]);
+    expect(piFindFlattened({ action: "run", name: "x", batchl: "reviewer" }, RFL_PARAMS)).toEqual([]);
+  });
+
+  it("TC3g: 收敛参数平铺被识别（model 升格 TOOL_TOP_LEVEL 后排除）", () => {
+    expect(
+      piFindFlattened(
+        { action: "run", name: "review-fix-loop", model: "ds-flash", maxFixAttempts: 3, convergeNewIssues: 2, convergeRounds: 3 },
+        RFL_PARAMS,
+      ),
+    ).toEqual(["maxFixAttempts", "convergeNewIssues", "convergeRounds"]);
+    expect(
+      piFindFlattened(
+        { action: "run", name: "review-fix-loop", args: { model: "ds-flash", maxFixAttempts: 3 }, convergeRounds: 3 },
+        RFL_PARAMS,
+      ),
+    ).toEqual(["convergeRounds"]);
+  });
+
+  it("TC3h: non-object 输入返回 []", () => {
+    expect(findFlattenedArgKeys(null, undefined)).toEqual([]);
+    expect(findFlattenedArgKeys(undefined, undefined)).toEqual([]);
+  });
+
+  it("TC3i: tool 顶层键不误报（M-3 回归——合成 parameters 直测 reservedKeys 排除）", () => {
+    const synthetic = {
+      type: "object",
+      properties: { name: { type: "string" }, task: { type: "string" } },
+      required: ["name"],
+    };
+    expect(
+      piFindFlattened({ action: "run", name: "mywf", args: { name: "x" } }, synthetic),
+    ).toEqual([]);
+    // 真实 meta 不含 name（探针口径）——附加验证
+    expect(argKeysFromMeta(RFL_PARAMS, { reservedKeys: PI_TOOL_TOP_LEVEL }).exact.has("name")).toBe(false);
+  });
+
+  it("args 为非对象标量时 args-排除失效（顶层已知键全报——与 pi 谓词等值）", () => {
+    expect(
+      piFindFlattened({ action: "run", name: "chain", args: "oops", task: "x" }, CHAIN_PARAMS),
+    ).toEqual(["task"]);
+  });
+});
+
+describe("normalizeArgsByMeta（归一组装 + 警告收集）", () => {
+  it("正常嵌套：args 原样归一、无警告（chain 真实契约）", () => {
+    const r = normalizeArgsByMeta(
+      { action: "run", name: "chain", args: { task: "x", agents: "/a.md" } },
+      CHAIN_PARAMS,
+      { reservedKeys: PI_TOOL_TOP_LEVEL },
+    );
+    expect(r.args).toEqual({ task: "x", agents: "/a.md" });
+    expect(r.warnings).toEqual([]);
+  });
+
+  it("args 缺省归一为空对象（params.args ?? {}——pi actionRun 等值）", () => {
+    const r = normalizeArgsByMeta(
+      { action: "run", name: "chain" },
+      CHAIN_PARAMS,
+      { reservedKeys: PI_TOOL_TOP_LEVEL },
+    );
+    expect(r.args).toEqual({});
+    expect(r.warnings).toEqual([]);
+  });
+
+  it("平铺误用：flattened_args 警告含键名列表（机读 keys + 中立 message）", () => {
+    const r = normalizeArgsByMeta(
+      { action: "run", name: "chain", task: "x" },
+      CHAIN_PARAMS,
+      { reservedKeys: PI_TOOL_TOP_LEVEL },
+    );
+    expect(r.args).toEqual({}); // 平铺键不静默收编（pi 现行为是 throw，修复动作留宿主）
+    expect(r.warnings).toEqual([
+      {
+        code: "flattened_args",
+        message: "Detected task at top level — they belong inside 'args'.",
+        keys: ["task"],
+      },
+    ]);
+  });
+
+  it("平铺 + args 共存：args-排除生效，无警告（与 pi TC3c 对齐）", () => {
+    const r = normalizeArgsByMeta(
+      { action: "run", name: "x", args: { task: "x" }, task: "y" },
+      CHAIN_PARAMS,
+      { reservedKeys: PI_TOOL_TOP_LEVEL },
+    );
+    expect(r.args).toEqual({ task: "x" });
+    expect(r.warnings).toEqual([]);
+  });
+
+  it("未知键：不产生警告（检测只对已知键——类型错误归 args-validator）", () => {
+    const r = normalizeArgsByMeta(
+      { action: "run", name: "chain", unknownKey: "v" },
+      CHAIN_PARAMS,
+      { reservedKeys: PI_TOOL_TOP_LEVEL },
+    );
+    expect(r.args).toEqual({});
+    expect(r.warnings).toEqual([]);
+  });
+
+  it("空 meta：no_parameter_contract 警告 + args 仍归一（M-2 显式信号）", () => {
+    const r = normalizeArgsByMeta({ action: "run", name: "legacy", args: { task: "x" } }, undefined);
+    expect(r.args).toEqual({ task: "x" });
+    expect(r.warnings).toEqual([
+      { code: "no_parameter_contract", message: "未声明参数契约（或解析为空）——平铺检测跳过，args 不校验" },
+    ]);
+  });
+
+  it("pattern 键平铺：batch1 经 pattern 命中进警告（review-fix-loop 真实契约）", () => {
+    const r = normalizeArgsByMeta(
+      { action: "run", name: "review-fix-loop", batch1: "reviewer" },
+      RFL_PARAMS,
+      { reservedKeys: PI_TOOL_TOP_LEVEL },
+    );
+    expect(r.warnings).toEqual([
+      {
+        code: "flattened_args",
+        message: "Detected batch1 at top level — they belong inside 'args'.",
+        keys: ["batch1"],
+      },
+    ]);
+  });
+
+  it("reservedKeys 撞名：workflow 声明 model 参数时顶层 model 不误报（宿主键集注入生效）", () => {
+    const synthetic = {
+      type: "object",
+      properties: { model: { type: "string" }, task: { type: "string" } },
+    };
+    const withReserved = normalizeArgsByMeta(
+      { action: "run", model: "ds-flash", task: "x" },
+      synthetic,
+      { reservedKeys: PI_TOOL_TOP_LEVEL },
+    );
+    expect(withReserved.warnings[0]).toMatchObject({ code: "flattened_args", keys: ["task"] });
+    // 不注入 reservedKeys（core 中性形态）：model 是已知参数 → 平铺报 model+task
+    const bare = normalizeArgsByMeta({ action: "run", model: "ds-flash", task: "x" }, synthetic);
+    expect(bare.warnings[0]).toMatchObject({ code: "flattened_args", keys: ["model", "task"] });
+  });
+
+  it("多键平铺按 Object.keys 序产出（与 pi throw 文案键序一致）", () => {
+    const r = normalizeArgsByMeta(
+      { action: "run", name: "review-fix-loop", targetType: "git-diff", target: "main" },
+      RFL_PARAMS,
+      { reservedKeys: PI_TOOL_TOP_LEVEL },
+    );
+    expect(r.warnings[0]).toMatchObject({ code: "flattened_args", keys: ["targetType", "target"] });
+    expect((r.warnings[0] as { message: string }).message).toBe(
+      "Detected targetType, target at top level — they belong inside 'args'.",
+    );
+  });
+
+  it("params 非对象：args = {}，无警告（防御分支，不抛）", () => {
+    expect(normalizeArgsByMeta(null, CHAIN_PARAMS)).toEqual({ args: {}, warnings: [] });
+    expect(normalizeArgsByMeta(undefined, CHAIN_PARAMS)).toEqual({ args: {}, warnings: [] });
+  });
+
+  it("args 为非对象标量：原样透传（类型校验责任在 args-validator，不发明约束）", () => {
+    const r = normalizeArgsByMeta({ action: "run", name: "chain", args: "oops" }, CHAIN_PARAMS);
+    expect(r.args).toBe("oops");
+  });
+
+  it("map-reduce oneOf 契约：oneOf 不参与键集（properties 才是键集来源——与 pi 等值）", () => {
+    const { exact } = argKeysFromMeta(MAP_REDUCE_PARAMS);
+    expect([...exact].sort()).toEqual(["agents", "items", "itemsJson", "operation"]);
+  });
+});

package/src/orchestration/__tests__/args-validator.test.ts

@@ -123,6 +123,20 @@ describe("validateRunArgs — 校验语义", () => {
     }
   });
 
+  it("TC6c: parameters 非 object（数组）→ ArgsValidationError「expected object」", () => {
+    // 锚定 schema 形状守卫分支：数组 parameters 在 null-scan/compile 之前 fail-fast
+    const spec = makeSpec([{ target: "string" }] as unknown as Record<string, unknown>, { a: 1 });
+    try {
+      validateRunArgs(spec);
+      expect.unreachable("should throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(ArgsValidationError);
+      expect((err as ArgsValidationError).message).toContain(
+        "invalid parameter schema (expected object)",
+      );
+    }
+  });
+
   it("TC6b: strictSchema:false 容忍自定义关键字与 format（design-review major-3 回归）", () => {
     const spec = makeSpec(
       { type: "object", properties: { target: { type: "string", format: "uri" } }, required: ["target"], "x-custom": true },