@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/orchestration/__tests__/workflow-files.test.ts

@@ -0,0 +1,186 @@
+// src/orchestration/__tests__/workflow-files.test.ts
+//
+// C4-core-script-pipeline（convergence W4 / D-6）目录参数化测试：
+// - saveWorkflow/deleteWorkflow 注入非 .pi 目录：真实落盘 / rename 迁移 / 删除；
+// - 既有语义回归（文案逐字）：tmp 不存在拒、目标已存在拒、运行中拒、
+//   两候选路径均无拒；
+// - 缺省目录 = pi 布局（相对 cwd resolve，pi 现两参调用形态行为不变）。
+// 设计权威源：docs/design/subagent-core-convergence.md §3.2 D-6。
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { deleteWorkflow, saveWorkflow } from "../workflow-files.ts";
+
+/** 构造注入布局（非 .pi）：{root}/host-tmp + {root}/host-saved（saved 不预创建，
+ * 覆盖 saveWorkflow 内 mkdirSync recursive 自动建目录路径）。 */
+function makeHostLayout(): { root: string; tmpDir: string; savedDir: string } {
+  const root = mkdtempSync(join(tmpdir(), "subagent-core-wf-"));
+  const tmpDir = join(root, "host-tmp");
+  const savedDir = join(root, "host-saved");
+  mkdirSync(tmpDir, { recursive: true });
+  return { root, tmpDir, savedDir };
+}
+
+function seedTmp(tmpDir: string, name: string, body = "// tmp body"): void {
+  writeFileSync(join(tmpDir, `${name}.js`), body);
+}
+
+// ============================================================
+// saveWorkflow（目录注入）
+// ============================================================
+
+describe("saveWorkflow 目录注入（非 .pi 布局）", () => {
+  it("注入 tmpDir/savedDir：tmp 落盘 → rename 迁移，savedDir 自动创建", async () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      seedTmp(tmpDir, "alpha", "// alpha body");
+      const msg = await saveWorkflow("alpha", undefined, { tmpDir, savedDir });
+      expect(msg).toBe(`Saved 'alpha' → 'alpha' (${join(savedDir, "alpha.js")})`);
+      // rename 语义：tmp 文件保存后消失
+      expect(existsSync(join(tmpDir, "alpha.js"))).toBe(false);
+      expect(readFileSync(join(savedDir, "alpha.js"), "utf-8")).toBe("// alpha body");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("newName 改名：tmp/alpha.js → saved/beta.js", async () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      seedTmp(tmpDir, "alpha", "// renamed body");
+      const msg = await saveWorkflow("alpha", "beta", { tmpDir, savedDir });
+      expect(msg).toBe(`Saved 'alpha' → 'beta' (${join(savedDir, "beta.js")})`);
+      expect(existsSync(join(savedDir, "alpha.js"))).toBe(false);
+      expect(existsSync(join(savedDir, "beta.js"))).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("目标已存在 → 拒（文案逐字）", async () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      seedTmp(tmpDir, "alpha");
+      mkdirSync(savedDir, { recursive: true });
+      writeFileSync(join(savedDir, "beta.js"), "// existing");
+      await expect(saveWorkflow("alpha", "beta", { tmpDir, savedDir })).rejects.toThrow(
+        "'beta' already exists in saved workflows. Use a different name.",
+      );
+      // 原文件不动
+      expect(existsSync(join(tmpDir, "alpha.js"))).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("tmp 不存在 → 拒（文案逐字）", async () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      await expect(saveWorkflow("ghost", undefined, { tmpDir, savedDir })).rejects.toThrow(
+        "Temporary workflow 'ghost' not found",
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+// ============================================================
+// deleteWorkflow（目录注入）
+// ============================================================
+
+describe("deleteWorkflow 目录注入（非 .pi 布局）", () => {
+  it("注入目录：tmp 候选优先删除", () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      seedTmp(tmpDir, "dup", "// tmp copy");
+      mkdirSync(savedDir, { recursive: true });
+      writeFileSync(join(savedDir, "dup.js"), "// saved copy");
+      const msg = deleteWorkflow("dup", () => false, { tmpDir, savedDir });
+      expect(msg).toBe(`Deleted workflow 'dup' (${join(tmpDir, "dup.js")})`);
+      expect(existsSync(join(tmpDir, "dup.js"))).toBe(false);
+      expect(existsSync(join(savedDir, "dup.js"))).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("注入目录：tmp 无 → saved 候选删除", () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      mkdirSync(savedDir, { recursive: true });
+      writeFileSync(join(savedDir, "gamma.js"), "// saved body");
+      const msg = deleteWorkflow("gamma", () => false, { tmpDir, savedDir });
+      expect(msg).toBe(`Deleted workflow 'gamma' (${join(savedDir, "gamma.js")})`);
+      expect(existsSync(join(savedDir, "gamma.js"))).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("运行中 → 拒（文案逐字，防删运行中脚本）", () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      seedTmp(tmpDir, "busy");
+      expect(() =>
+        deleteWorkflow("busy", (name) => name === "busy", { tmpDir, savedDir }),
+      ).toThrow("Cannot delete 'busy': workflow is currently running. Abort it first.");
+      expect(existsSync(join(tmpDir, "busy.js"))).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("两候选均无 → 拒（文案逐字）", () => {
+    const { root, tmpDir, savedDir } = makeHostLayout();
+    try {
+      expect(() => deleteWorkflow("void", () => false, { tmpDir, savedDir })).toThrow(
+        "Workflow file 'void' not found",
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+// ============================================================
+// 缺省目录（pi 布局回归——向后兼容：pi 现两参调用形态行为不变）
+// ============================================================
+
+describe("缺省目录 = pi 布局（向后兼容回归）", () => {
+  it("save 缺省：<cwd>/.pi/workflows/.tmp → <cwd>/.pi/workflows", async () => {
+    const fakeCwd = mkdtempSync(join(tmpdir(), "subagent-core-cwd-"));
+    const cwdSpy = vi.spyOn(process, "cwd").mockReturnValue(fakeCwd);
+    try {
+      const tmpDir = join(fakeCwd, ".pi", "workflows", ".tmp");
+      mkdirSync(tmpDir, { recursive: true });
+      seedTmp(tmpDir, "pi-wf", "// pi layout");
+      const msg = await saveWorkflow("pi-wf");
+      expect(msg).toBe(`Saved 'pi-wf' → 'pi-wf' (${join(fakeCwd, ".pi", "workflows", "pi-wf.js")})`);
+      expect(existsSync(join(tmpDir, "pi-wf.js"))).toBe(false);
+      expect(existsSync(join(fakeCwd, ".pi", "workflows", "pi-wf.js"))).toBe(true);
+    } finally {
+      cwdSpy.mockRestore();
+      rmSync(fakeCwd, { recursive: true, force: true });
+    }
+  });
+
+  it("delete 缺省：两候选 = .pi/workflows/.tmp 与 .pi/workflows", () => {
+    const fakeCwd = mkdtempSync(join(tmpdir(), "subagent-core-cwd-"));
+    const cwdSpy = vi.spyOn(process, "cwd").mockReturnValue(fakeCwd);
+    try {
+      const savedDir = join(fakeCwd, ".pi", "workflows");
+      mkdirSync(savedDir, { recursive: true });
+      writeFileSync(join(savedDir, "saved-only.js"), "// body");
+      const msg = deleteWorkflow("saved-only", () => false);
+      expect(msg).toBe(`Deleted workflow 'saved-only' (${join(savedDir, "saved-only.js")})`);
+      expect(existsSync(join(savedDir, "saved-only.js"))).toBe(false);
+    } finally {
+      cwdSpy.mockRestore();
+      rmSync(fakeCwd, { recursive: true, force: true });
+    }
+  });
+});

package/src/orchestration/__tests__/workflow-nesting-e2e.test.ts

@@ -24,7 +24,7 @@ vi.mock("../lifecycle.ts", () => ({
   scheduleTimeBudget: vi.fn(() => undefined),
 }));
 
-import { handleWorkerMessage } from "../error-recovery.ts";
+import { handleWorkerMessage } from "../worker-message-pump.ts";
 import { executeNestedWorkflow, type LauncherDeps } from "../launcher.ts";
 import { runWorkflow } from "../lifecycle.ts";
 import { Budget } from "../models/budget.ts";

package/src/orchestration/__tests__/workflow-run-summary.test.ts

@@ -0,0 +1,119 @@
+// workflow-run-summary.test.ts —— runSummary 投影 + isScriptRunning 判定测试（U7/B5/D8）。
+//
+// 覆盖（验收条款③）：
+// - runSummary：字段投影全断言（running / done 两形态；slug/error/completedAt 缺省透传）
+// - isScriptRunning：真（同名 running）/ 假（同名 done、异名 running、空 Map）两分支
+import { describe, expect, it } from "vitest";
+
+import { isScriptRunning, runSummary } from "../workflow-run-summary.ts";
+import { Budget } from "../models/budget.ts";
+import type { RunSpec } from "../models/run-spec.ts";
+import { Trace } from "../models/trace.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+
+function makeSpec(scriptName: string, slug?: string): RunSpec {
+  return {
+    scriptSource: "execute() {}",
+    args: {},
+    scriptName,
+    ...(slug !== undefined ? { slug } : {}),
+    scriptPath: "/fake/test.js",
+  };
+}
+
+function makeRun(
+  runId: string,
+  opts: {
+    status?: "running" | "done";
+    scriptName?: string;
+    slug?: string;
+    reason?: "completed" | "failed" | "aborted" | "time_limited";
+    error?: string;
+    startedAt?: string;
+    completedAt?: string;
+  } = {},
+): WorkflowRun {
+  const status = opts.status ?? "running";
+  return WorkflowRun.reconstruct(
+    runId,
+    makeSpec(opts.scriptName ?? "deploy-site", opts.slug),
+    {
+      status,
+      ...(status === "done" ? { reason: opts.reason ?? "completed" } : {}),
+      budget: new Budget({ maxTokens: 1000 }),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+      ...(opts.error !== undefined ? { error: opts.error } : {}),
+    },
+    {
+      startedAt: opts.startedAt ?? "2026-08-30T00:00:00.000Z",
+      ...(opts.completedAt !== undefined ? { completedAt: opts.completedAt } : {}),
+    },
+  );
+}
+
+describe("runSummary — 字段投影（字段以 core WorkflowRun 为准）", () => {
+  it("running run：name=scriptName、slug、status、startedAt 投影；completedAt/reason 为 undefined", () => {
+    const run = makeRun("wf-r1", { status: "running", scriptName: "deploy-site", slug: "deploy" });
+
+    expect(runSummary(run)).toEqual({
+      runId: "wf-r1",
+      name: "deploy-site",
+      slug: "deploy",
+      status: "running",
+      reason: undefined,
+      startedAt: "2026-08-30T00:00:00.000Z",
+      completedAt: undefined,
+      error: undefined,
+    });
+  });
+
+  it("done run：reason/completedAt/error 投影（对齐 pi toRunSummary 字段集）", () => {
+    const run = makeRun("wf-d1", {
+      status: "done",
+      reason: "failed",
+      error: "agent timeout",
+      startedAt: "2026-08-30T10:00:00.000Z",
+      completedAt: "2026-08-30T10:05:00.000Z",
+    });
+
+    expect(runSummary(run)).toEqual({
+      runId: "wf-d1",
+      name: "deploy-site",
+      slug: undefined,
+      status: "done",
+      reason: "failed",
+      startedAt: "2026-08-30T10:00:00.000Z",
+      completedAt: "2026-08-30T10:05:00.000Z",
+      error: "agent timeout",
+    });
+  });
+});
+
+describe("isScriptRunning — 真假两分支", () => {
+  it("真：同名 script 仍在 running", () => {
+    const runs = new Map<string, WorkflowRun>([
+      ["wf-1", makeRun("wf-1", { status: "done", scriptName: "other-wf" })],
+      ["wf-2", makeRun("wf-2", { status: "running", scriptName: "deploy-site" })],
+    ]);
+
+    expect(isScriptRunning(runs, "deploy-site")).toBe(true);
+  });
+
+  it("假：同名但已 done（running 状态白名单）", () => {
+    const runs = new Map<string, WorkflowRun>([
+      ["wf-1", makeRun("wf-1", { status: "done", scriptName: "deploy-site" })],
+    ]);
+
+    expect(isScriptRunning(runs, "deploy-site")).toBe(false);
+  });
+
+  it("假：异名 running / 空 Map", () => {
+    const runs = new Map<string, WorkflowRun>([
+      ["wf-1", makeRun("wf-1", { status: "running", scriptName: "other-wf" })],
+    ]);
+    expect(isScriptRunning(runs, "deploy-site")).toBe(false);
+    expect(isScriptRunning(new Map(), "deploy-site")).toBe(false);
+  });
+});

package/src/orchestration/__tests__/workflow-script-registry-impl.test.ts

@@ -0,0 +1,124 @@
+/**
+ * workflow-script-registry-impl 测试：sink 设计 U1 导出形态。
+ *
+ * 覆盖：WorkflowScript 类 re-export 可用性 + loadWorkflowScriptByPath 工厂加载
+ * （真实临时脚本文件）、非法引用拒绝（含 ⛔2 `..` 段收紧对工厂生效）、
+ * available=false stub 语义。
+ *
+ * 策略对齐 config-loader.test.ts：真实临时目录 + 真实脚本文件（meta 提取走真实
+ * 文件读取），只 mock findWorkspaceRoot（缓存桶 key，耦合 process.cwd 难隔离）与
+ * homedir（`~/` 引用展开锚点）。
+ */
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("node:os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:os")>();
+  return { ...actual, homedir: vi.fn(() => "/nonexistent-home-for-tests") };
+});
+
+vi.mock("../../shared/resource-discovery.ts", async (importOriginal) => {
+  const actual = await importOriginal<
+    typeof import("../../shared/resource-discovery.ts")
+  >();
+  return {
+    ...actual,
+    findWorkspaceRoot: vi.fn(() => "/unused-by-default"),
+  };
+});
+
+import { invalidateCache } from "../config-loader.ts";
+import { loadWorkflowScriptByPath, WorkflowScript } from "../workflow-script-registry-impl.ts";
+import { homedir } from "node:os";
+
+const mockedHomedir = vi.mocked(homedir);
+
+/** 有效 workflow 脚本内容（@pi-meta 块注释 + agent 入口，同 config-loader.test 范式；phases 须 YAML 数组）。 */
+const SCRIPT_SOURCE =
+  "/* @pi-meta\nname: factory-wf\ndescription: factory test\nphases: []\n*/\nagent({ prompt: \"x\" });\n";
+
+async function writeScript(content: string, fileName = "factory-wf.js"): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "wf-registry-impl-test-"));
+  const p = join(dir, fileName);
+  await writeFile(p, content, "utf-8");
+  return p;
+}
+
+describe("loadWorkflowScriptByPath / WorkflowScript 导出形态（U1）", () => {
+  let tempDirs: string[] = [];
+
+  beforeEach(() => {
+    invalidateCache();
+    // 重置 `~/` 用例留下的 homedir mock 残留（mockReturnValue 跨测试持续）
+    mockedHomedir.mockReturnValue("/nonexistent-home-for-tests");
+    tempDirs = [];
+  });
+
+  afterEach(async () => {
+    invalidateCache();
+    for (const dir of tempDirs) {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  async function trackedWrite(content: string, fileName?: string): Promise<string> {
+    const p = await writeScript(content, fileName);
+    tempDirs.push(join(p, ".."));
+    return p;
+  }
+
+  it("按绝对路径加载：返回 WorkflowScript 实例（meta/sourceCode 填充，available=true）", async () => {
+    const p = await trackedWrite(SCRIPT_SOURCE);
+    const script = await loadWorkflowScriptByPath(p);
+    expect(script).toBeInstanceOf(WorkflowScript);
+    expect(script!.name).toBe("factory-wf");
+    expect(script!.available).toBe(true);
+    expect(script!.path).toBe(p);
+    expect(script!.sourceCode).toBe(SCRIPT_SOURCE);
+    expect(script!.meta.description).toBe("factory test");
+  });
+
+  it("re-export 的 WorkflowScript 类与实例同源：validate/toExecutable 实体操作可用", async () => {
+    const p = await trackedWrite(SCRIPT_SOURCE);
+    const script = await loadWorkflowScriptByPath(p);
+    expect(script).toBeInstanceOf(WorkflowScript);
+    // 实体操作（validate 委托 lintScript / toExecutable 返回可执行源）经导出类实例可用
+    const lint = script!.validate();
+    expect(lint.valid).toBe(true);
+    expect(Array.isArray(lint.findings)).toBe(true);
+    expect(script!.toExecutable()).toBe(SCRIPT_SOURCE);
+  });
+
+  it("文件不可读/不存在：available=false 的 stub（非 undefined——loader never throws）", async () => {
+    const p = await trackedWrite(SCRIPT_SOURCE, "gone.js");
+    await rm(p);
+    const script = await loadWorkflowScriptByPath(p);
+    expect(script).toBeDefined();
+    expect(script!.available).toBe(false);
+  });
+
+  it("非法引用返回 undefined：相对路径 / 非 .js 扩展名", async () => {
+    await trackedWrite(SCRIPT_SOURCE);
+    expect(await loadWorkflowScriptByPath("relative/wf.js")).toBeUndefined();
+    expect(await loadWorkflowScriptByPath("/proj/wf.txt")).toBeUndefined();
+  });
+
+  it("⛔2：含 .. 段的路径引用被拒（undefined——收紧对工厂消费面生效）", async () => {
+    await trackedWrite(SCRIPT_SOURCE);
+    expect(await loadWorkflowScriptByPath("/x/../factory-wf.js")).toBeUndefined();
+  });
+
+  it("~/ 前缀引用：展开 homedir 后加载（barrel 消费面的合法引用形态）", async () => {
+    const fakeHome = await mkdtemp(join(tmpdir(), "wf-registry-impl-home-"));
+    tempDirs.push(fakeHome);
+    mockedHomedir.mockReturnValue(fakeHome);
+    const p = join(fakeHome, "home-wf.js");
+    await writeFile(p, SCRIPT_SOURCE, "utf-8");
+    const script = await loadWorkflowScriptByPath("~/home-wf.js");
+    expect(script).toBeInstanceOf(WorkflowScript);
+    expect(script!.name).toBe("factory-wf");
+    expect(script!.path).toBe(p);
+  });
+});

package/src/orchestration/agent-opts-resolver.ts

@@ -10,7 +10,7 @@
  * agent ref 处理（systemPrompt/model/thinkingLevel）已移交 resolveIdentity（execution 层，
  * 经 getAgentConfig + resolveModel 完整覆盖），消除双重注入与 model 层级混乱。
  *
- * 调用方：engine/error-recovery.ts dispatchAgentCall（每次 agent-call 消息）。
+ * 调用方：engine/worker-message-pump.ts dispatchAgentCall（每次 agent-call 消息）。
  * - skill → resolveSkillPath → skillPath（--skill）
  * - schema → 结构化输出指令内容直传 appendSystemPrompt（--append-system-prompt）+ schemaEnv（PI_WORKFLOW_SCHEMA）
  *
@@ -145,7 +145,7 @@ export function formatSchemaInstruction(schema: Record<string, unknown>): string
 export function resolveAgentOpts(opts: AgentCallOpts): ResolveResult {
   const appendSystemPrompt: string[] = [];
 
- // Resolve skill name to SKILL.md path
+  // Resolve skill name to SKILL.md path
   if (opts.skill) {
     const skillPath = resolveSkillPath(opts.skill);
     if (!skillPath) {
@@ -154,17 +154,17 @@ export function resolveAgentOpts(opts: AgentCallOpts): ResolveResult {
     opts = { ...opts, skillPath };
   }
 
- // Inject schema as structured-output instruction into appendSystemPrompt (content,
- // not temp file) and set environment variable for conditional tool + hook activation.
- // M2 fix: previously wrote the instruction to a temp file and pushed the FILE PATH,
- // which got concatenated into the final append file as path garbage — the SO instruction
- // never reached the subprocess. Now the instruction content is pushed directly.
+  // Inject schema as structured-output instruction into appendSystemPrompt (content,
+  // not temp file) and set environment variable for conditional tool + hook activation.
+  // M2 fix: previously wrote the instruction to a temp file and pushed the FILE PATH,
+  // which got concatenated into the final append file as path garbage — the SO instruction
+  // never reached the subprocess. Now the instruction content is pushed directly.
   if (opts.schema) {
     // IF7(#13)：formatSchemaInstruction 与 schemaEnv 对同一 schema 对象引用共享
     // WeakMap 缓存条目（compact stringify 整个 dispatch 只发生一次）
     appendSystemPrompt.push(formatSchemaInstruction(opts.schema));
 
- // Set env var for structured-output extension to activate tool + hook
+    // Set env var for structured-output extension to activate tool + hook
     opts = { ...opts, schemaEnv: stringifySchemaCached(opts.schema, "compact") };
   }
 

package/src/orchestration/args-meta.ts

@@ -0,0 +1,198 @@
+// src/orchestration/args-meta.ts
+//
+// U9（D9 / B3 / B4）：workflow @pi-meta parameters（JSON Schema）→ 已知参数键集、
+// args 平铺检测、参数归一组装。平移自 pi-sw tool-workflow.ts:136-196（m6「schema 即
+// SSOT」——替代 21 键硬编码 KNOWN_ARG_KEYS，消除与参数定义的漂移面）。
+//
+// 相对 pi-sw 原实现的两处平台耦合剥离（行为等值，见实施计划偏差登记表）：
+// - TOOL_TOP_LEVEL（pi workflow tool 顶层键集，pi 侧 schema 事实）→ 参数化 reservedKeys
+//   由宿主注入（同 U1 knownNames / D7 queuePolicy 的宿主差异参数化先例）；core 引擎
+//   无关，不内嵌任何宿主 tool schema。pi-sw 消费改造时传自己的 TOOL_TOP_LEVEL 即得
+//   等值行为。
+// - @zhushanwen/pi-extension-logger → core logger facade（同语义 warn，平台中立）。
+//
+// 平铺检测语义（m6 定稿，勿改）：弱模型把 args 子字段平铺到 params 顶层是 P0 级
+// 静默失败（args ?? {} 会静默空启动），检测命中必须显式暴露——core 以 warnings 数据
+// 承载，是否升级为 fatal 由宿主裁决（pi 现行为是 throw，消费改造时 adapter 对
+// flattened_args 警告 throw 即等值）。
+
+import { getLogger } from "../core/logger.ts";
+
+const logger = getLogger("args-meta");
+
+const EMPTY_RESERVED_KEYS: ReadonlySet<string> = new Set<string>();
+
+/** 已知参数键集：exact = properties 精确键；patterns = patternProperties 原样转正则。 */
+export interface ArgKeySet {
+  readonly exact: ReadonlySet<string>;
+  readonly patterns: readonly RegExp[];
+}
+
+/** 键集构建选项（宿主差异注入点）。 */
+export interface ArgMetaOptions {
+  /**
+   * 宿主调用信封顶层保留键（如 pi workflow tool 的 action/name/slug/args/model/...）。
+   * workflow 参数名与保留键撞名时，顶层同名键是信封参数而非平铺（m6 评审 M-3）：
+   * exact 构建排除保留键；能命中任一保留键的 pattern 整条跳过（^run.*$ 类会误伤
+   * runId/name 等合法调用，m6 exec-review S1）。缺省空集（core 中性形态）。
+   */
+  readonly reservedKeys?: ReadonlySet<string>;
+}
+
+/**
+ * properties → exact 精确键集（排除 reservedKeys——workflow 参数名与保留键撞名时，
+ * 顶层同名键是信封参数而非平铺，m6 评审 M-3）。非对象形状（含 undefined/null）
+ * 返回空集。
+ */
+function collectExactKeys(props: unknown, reserved: ReadonlySet<string>): Set<string> {
+  const exact = new Set<string>();
+  if (props === null || typeof props !== "object") return exact;
+  for (const k of Object.keys(props as Record<string, unknown>)) {
+    if (!reserved.has(k)) exact.add(k);
+  }
+  return exact;
+}
+
+/**
+ * patternProperties → 正则数组（schema pattern 已是正则源码，直接 new RegExp；
+ * 自动兼容 \d{2} 等变体）。跳过能命中保留键的 pattern——否则 ^run.*$ 类 pattern
+ * 会匹配 runId/name 等信封键，合法调用恒误报（m6 exec-review S1）。非法 pattern
+ * （schema 校验 m3 已保证合法，双保险）跳过并 warn。
+ */
+function compilePatterns(pp: unknown, reserved: ReadonlySet<string>): RegExp[] {
+  const patterns: RegExp[] = [];
+  if (pp === null || typeof pp !== "object") return patterns;
+  for (const p of Object.keys(pp as Record<string, unknown>)) {
+    try {
+      const re = new RegExp(p);
+      if ([...reserved].some((tk) => re.test(tk))) continue;
+      patterns.push(re);
+    } catch (err) {
+      logger.warn(`[args-meta] patternProperties 非法正则跳过: ${p}`, {
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  return patterns;
+}
+
+/**
+ * 从 workflow 参数 schema（@pi-meta parameters）动态构建平铺检测的已知键集。
+ *
+ * - exact：properties keys（精确匹配，排除 reservedKeys）
+ * - patterns：patternProperties 原样转正则数组（schema pattern 已是正则源码，
+ *   直接 new RegExp；自动兼容 \d{2} 等变体）
+ * - meta 缺失/非对象 → 空键集（legacy const-meta 类无参数契约，检测跳过）
+ */
+export function argKeysFromMeta(
+  meta: Record<string, unknown> | undefined | null,
+  options?: ArgMetaOptions,
+): ArgKeySet {
+  const reserved = options?.reservedKeys ?? EMPTY_RESERVED_KEYS;
+  if (meta === undefined || meta === null || typeof meta !== "object") {
+    return { exact: new Set<string>(), patterns: [] };
+  }
+  const schema = meta as Record<string, unknown>;
+  return {
+    exact: collectExactKeys(schema.properties, reserved),
+    patterns: compilePatterns(schema.patternProperties, reserved),
+  };
+}
+
+/**
+ * 平铺检测内部谓词（接收已构建键集）——normalizeArgsByMeta 复用以避免二次构建
+ * 键集触发重复 warn；公开入口 findFlattenedArgKeys(params, meta) 按设计签名接收
+ * meta 并内联构建。两路径谓词逐字同源，行为必然一致。
+ */
+function filterFlattenedKeys(p: Record<string, unknown>, keys: ArgKeySet): string[] {
+  const args = typeof p.args === "object" && p.args !== null ? p.args : undefined;
+  const isKnownKey = (k: string) =>
+    keys.exact.has(k) || keys.patterns.some((re) => re.test(k));
+  // hasOwnProperty.call 而非 in（原型链——constructor/toString 类参数名不被继承键掩盖）
+  return Object.keys(p).filter(
+    (k) =>
+      isKnownKey(k) &&
+      !(args !== undefined && Object.prototype.hasOwnProperty.call(args, k)),
+  );
+}
+
+/**
+ * 检测弱模型把 args 子字段平铺到 params 顶层（P0 静默失败防护）。
+ * 返回被平铺的键名列表（空 = 未平铺）。匹配谓词：exact 命中 || pattern 命中
+ * （pattern 自带数字后缀语义——loose startsWith 会误报 batchl/target1）；args 内
+ * 已存在的键不算平铺（顶层 + args 共存不算平铺）。
+ *
+ * 参数取 unknown 以解耦宿主 params 类型限制、便于测试构造任意对象。
+ */
+export function findFlattenedArgKeys(
+  params: unknown,
+  meta: Record<string, unknown> | undefined | null,
+  options?: ArgMetaOptions,
+): string[] {
+  if (typeof params !== "object" || params === null) return [];
+  const keys = argKeysFromMeta(meta, options);
+  return filterFlattenedKeys(params as Record<string, unknown>, keys);
+}
+
+/** 组装层警告（结构化承载，宿主决定展示/日志/fatal 升级）。 */
+export type ArgMetaWarning =
+  | {
+      /** 无参数契约（meta 未声明或解析为空）——平铺检测跳过，args 不校验（m6 M-2 显式信号）。 */
+      code: "no_parameter_contract";
+      message: string;
+    }
+  | {
+      /** args 子字段被平铺到顶层——修正动作留宿主（pi 现行为是带 Correct 正例 throw）。 */
+      code: "flattened_args";
+      message: string;
+      keys: readonly string[];
+    };
+
+/** normalizeArgsByMeta 产物。 */
+export interface NormalizedArgs {
+  /**
+   * 归一后的 args：params.args ?? {}（params 非对象时为 {}）。args 字段为非对象
+   * 标量时原样透传——类型校验责任在 args-validator（schema chokepoint），本函数
+   * 不发明约束（与 m3 exec-review M2 裁决一致）。
+   */
+  readonly args: unknown;
+  readonly warnings: readonly ArgMetaWarning[];
+}
+
+/**
+ * 组装函数：按 meta 归一 params 为 { args, warnings }（pi actionRun 参数处理段的
+ * 纯函数化——argKeysFromMeta + 空契约信号 + 平铺检测 + args 归一四步单点收口）。
+ *
+ * 警告语义与 pi 现行为对位：
+ * - no_parameter_contract ↔ pi logger.warn「未声明参数契约——平铺检测跳过」（M-2）
+ * - flattened_args ↔ pi throw「Detected ... they belong inside 'args'」（Correct
+ *   正例含宿主 tool 键 action/name——平台事实留宿主拼接，core 文案保持中立）
+ */
+export function normalizeArgsByMeta(
+  params: unknown,
+  meta: Record<string, unknown> | undefined | null,
+  options?: ArgMetaOptions,
+): NormalizedArgs {
+  const keys = argKeysFromMeta(meta, options);
+  const warnings: ArgMetaWarning[] = [];
+  if (keys.exact.size === 0 && keys.patterns.length === 0) {
+    // m6 exec-review M1：无参数契约（未声明/解析空）→ 显式警告——静默退化变显式
+    warnings.push({
+      code: "no_parameter_contract",
+      message: "未声明参数契约（或解析为空）——平铺检测跳过，args 不校验",
+    });
+  }
+  if (typeof params === "object" && params !== null) {
+    const p = params as Record<string, unknown>;
+    const flattened = filterFlattenedKeys(p, keys);
+    if (flattened.length > 0) {
+      warnings.push({
+        code: "flattened_args",
+        keys: flattened,
+        message: `Detected ${flattened.join(", ")} at top level — they belong inside 'args'.`,
+      });
+    }
+    return { args: p.args ?? {}, warnings };
+  }
+  return { args: {}, warnings };
+}