@zhushanwen/pi-subagent-workflow 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",

package/src/execution/__tests__/execute-options-mapper.test.ts

@@ -22,6 +22,25 @@ describe("mapToExecuteOptions (D-A2)", () => {
     skillPath: "/path/to/skill.md",
   };
 
+  it("T3.10 slug 截断: description > SLUG_MAX_LENGTH(35) → 截断到 35", () => {
+    const opts: AgentCallOpts = { ...baseOpts, description: "a".repeat(36) };
+    const result = mapToExecuteOptions(opts);
+    expect(result.slug).toHaveLength(35);
+    expect(result.slug).toBe("a".repeat(35));
+  });
+
+  it("T3.10 slug 边界: description = 35 → 不截断", () => {
+    const opts: AgentCallOpts = { ...baseOpts, description: "a".repeat(35) };
+    const result = mapToExecuteOptions(opts);
+    expect(result.slug).toHaveLength(35);
+    expect(result.slug).toBe("a".repeat(35));
+  });
+
+  it("T3.10 slug 回落: 无 description → agentName", () => {
+    const result = mapToExecuteOptions(baseOpts);
+    expect(result.slug).toBe("worker");
+  });
+
   it("T3.4 基本映射: prompt→task, agent→agent, cwd→cwd", () => {
     const result = mapToExecuteOptions(baseOpts);
     expect(result.task).toBe("test task");
@@ -37,12 +56,12 @@ describe("mapToExecuteOptions (D-A2)", () => {
   it("T3.9 schemaEnv 透传 (D-A6 bridge)", () => {
     const opts: AgentCallOpts = { ...baseOpts, schemaEnv: '{"type":"object"}' };
     const result = mapToExecuteOptions(opts);
-    expect((result as unknown as { schemaEnv?: string }).schemaEnv).toBe('{"type":"object"}');
+    expect(result.schemaEnv).toBe('{"type":"object"}');
   });
 
   it("T3.9 schemaEnv 不传 → schemaEnv undefined", () => {
     const result = mapToExecuteOptions(baseOpts);
-    expect((result as unknown as { schemaEnv?: string }).schemaEnv).toBeUndefined();
+    expect(result.schemaEnv).toBeUndefined();
   });
 
   it("T3.5 model: opts.model 优先（显式 override 透传，不与 ctxModel 混合）", () => {

package/src/execution/__tests__/run-spawn-integration.test.ts

@@ -828,4 +828,84 @@ describe("runSpawn", () => {
 
   // 注：C1（orphan 进程兜底）与 M8（stdout 边界）describe 块已移至 run-spawn-edges.test.ts，
   // 拆分以保持本文件 < 1000 行（pre-commit hook 限制）。两文件各自独立声明文件级 mock。
+
+  // ============================================================
+  // E2E：runSpawn 从主进程 process.argv 镜像 extension/approve flag 到子进程
+  // 验证完整链路：runSpawn 真实执行 → 读 process.argv → buildSpawnArgs 拼参 →
+  // spawn 收到的 args 含镜像 flag。spawn 被 mock（FakeChild），但 runSpawn 体内逻辑
+  // 全真实跑，process.argv 用真实进程变量（测试中临时覆写 + 还原）。
+  // ============================================================
+  describe("E2E: 镜像主进程 argv flag 到子进程 spawn args", () => {
+    const originalArgv = process.argv;
+
+    afterEach(() => {
+      process.argv = originalArgv;
+    });
+
+    it("主进程 argv 含 --extension/--no-extensions/--approve → 子进程 spawn args 全部镜像", async () => {
+      // 模拟主 pi 进程启动参数（xyz-agent runtime 启动 pi 的真实形态）
+      process.argv = [
+        "bun", "/path/to/pi",
+        "--mode", "rpc",
+        "--no-extensions",
+        "--approve",
+        "--extension", "/exts/goal",
+        "--extension", "/exts/todo",
+        "--session-dir", "/sessions",
+      ];
+
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task", makeOpts(), makeCtx());
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+      mockSessionFileExists(
+        "/tmp/test/agents/subagents/--tmp-test--/sessions/2026-07-03T12-00-00-000Z_sess-mirror.jsonl",
+      );
+      emitStdoutLine(child, sessionHeader("sess-mirror"));
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0);
+      await promise;
+
+      // 断言 spawn 收到的调用参数含全部镜像 flag
+      const spawnCall = mockSpawn.mock.calls[0];
+      // spawn(command, args, options) → args 是第二个参数
+      const spawnArgs = spawnCall[1] as string[];
+
+      expect(spawnArgs).toContain("--no-extensions");
+      expect(spawnArgs).toContain("--approve");
+      // 两个 extension 路径都镜像，顺序保留
+      const extIdxs = spawnArgs
+        .map((a, i) => (a === "--extension" ? i : -1))
+        .filter((i) => i >= 0);
+      expect(extIdxs).toHaveLength(2);
+      expect(spawnArgs[extIdxs[0] + 1]).toBe("/exts/goal");
+      expect(spawnArgs[extIdxs[1] + 1]).toBe("/exts/todo");
+    });
+
+    it("主进程 argv 无目标 flag → 子进程 spawn args 不含镜像 flag（向后兼容）", async () => {
+      // 模拟纯 pi CLI 直接跑（无 extension/approve 配置）
+      process.argv = ["bun", "/path/to/pi", "--mode", "rpc"];
+
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task", makeOpts(), makeCtx());
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+      mockSessionFileExists(
+        "/tmp/test/agents/subagents/--tmp-test--/sessions/2026-07-03T12-00-00-000Zsess-noflag.jsonl",
+      );
+      emitStdoutLine(child, sessionHeader("sess-noflag"));
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0);
+      await promise;
+
+      const spawnCall = mockSpawn.mock.calls[0];
+      const spawnArgs = spawnCall[1] as string[];
+
+      expect(spawnArgs).not.toContain("--no-extensions");
+      expect(spawnArgs).not.toContain("--approve");
+      expect(spawnArgs).not.toContain("--extension");
+    });
+  });
 });

package/src/execution/__tests__/spawn-args.test.ts

@@ -7,6 +7,7 @@ import * as path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { MAX_FORK_DEPTH } from "../session-context-resolver.ts";
+import { mirrorMainProcessFlags } from "../argv-mirror.ts";
 import { buildEnvBlock, buildSpawnArgs } from "../session-runner.ts";
 
 describe("buildSpawnArgs", () => {
@@ -131,6 +132,105 @@ describe("buildSpawnArgs", () => {
     );
     expect(args).not.toContain("--tools");
   });
+
+  // ============================================================
+  // mirrorFlags 透传：子进程镜像主进程 extension/approve flag
+  // ============================================================
+
+  it("mirrorFlags 透传：noExtensions+approve+extensionPaths 全量 push（TC5）", () => {
+    const args = buildSpawnArgs({
+      ...baseParams,
+      mirrorFlags: { noExtensions: true, approve: true, extensionPaths: ["/e1", "/e2"] },
+    });
+    expect(args).toContain("--no-extensions");
+    expect(args).toContain("--approve");
+    // 每个 extension 独立 token，顺序保留
+    const extIdxs = args.map((a, i) => (a === "--extension" ? i : -1)).filter((i) => i >= 0);
+    expect(extIdxs).toHaveLength(2);
+    expect(args[extIdxs[0] + 1]).toBe("/e1");
+    expect(args[extIdxs[1] + 1]).toBe("/e2");
+  });
+
+  it("mirrorFlags 全 false/空 → 不追加任何目标 flag（TC6）", () => {
+    const args = buildSpawnArgs({
+      ...baseParams,
+      mirrorFlags: { noExtensions: false, approve: false, extensionPaths: [] },
+    });
+    expect(args).not.toContain("--no-extensions");
+    expect(args).not.toContain("--approve");
+    expect(args).not.toContain("--extension");
+    // 仅基础参数
+    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir"]);
+  });
+
+  it("mirrorFlags undefined → 行为等同旧版（TC7）", () => {
+    const args = buildSpawnArgs(baseParams);
+    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir"]);
+    expect(args).not.toContain("--extension");
+    expect(args).not.toContain("--no-extensions");
+    expect(args).not.toContain("--approve");
+  });
+});
+
+// ============================================================
+// mirrorMainProcessFlags：从主进程 argv 解析可镜像的 flag
+// ============================================================
+
+describe("mirrorMainProcessFlags", () => {
+  it("--extension 多次出现（空格分隔）+ 布尔 flag（TC1）", () => {
+    const r = mirrorMainProcessFlags([
+      "bun", "/pi", "--mode", "rpc", "--no-extensions", "--approve",
+      "--extension", "/a", "--extension", "/b",
+    ]);
+    expect(r).toEqual({ noExtensions: true, approve: true, extensionPaths: ["/a", "/b"] });
+  });
+
+  it("--extension=path 等号形式 + 短形式 -e/-ne/-a（TC2）", () => {
+    const r = mirrorMainProcessFlags([
+      "bun", "/pi", "--extension=/x", "-ne", "-a",
+    ]);
+    expect(r).toEqual({ noExtensions: true, approve: true, extensionPaths: ["/x"] });
+  });
+
+  it("混合形式（空格 + 等号），顺序保留（TC3）", () => {
+    const r = mirrorMainProcessFlags([
+      "bun", "/pi", "--extension", "/a", "--extension=/b", "--extension", "/c",
+    ]);
+    expect(r.extensionPaths).toEqual(["/a", "/b", "/c"]);
+    expect(r.noExtensions).toBe(false);
+    expect(r.approve).toBe(false);
+  });
+
+  it("无目标 flag → 全空/全 false（向后兼容，TC4）", () => {
+    const r = mirrorMainProcessFlags(["bun", "/pi", "--mode", "rpc"]);
+    expect(r).toEqual({ noExtensions: false, approve: false, extensionPaths: [] });
+  });
+
+  it("不误吃其他 flag 值与 positional 参数（TC8）", () => {
+    const r = mirrorMainProcessFlags([
+      "bun", "/pi", "--no-extensions", "--skill", "/sk", "some prompt text",
+    ]);
+    expect(r.noExtensions).toBe(true);
+    expect(r.extensionPaths).toEqual([]);
+    // --skill 的 /sk 不混入 extensionPaths；positional prompt 被忽略
+  });
+
+  it("空 argv / 仅前导两项 → 全空", () => {
+    expect(mirrorMainProcessFlags([])).toEqual({ noExtensions: false, approve: false, extensionPaths: [] });
+    expect(mirrorMainProcessFlags(["bun", "/pi"])).toEqual({
+      noExtensions: false, approve: false, extensionPaths: [],
+    });
+  });
+
+  it("--extension 末尾无值 → 跳过（不越界、不误吃下一个 token）", () => {
+    const r = mirrorMainProcessFlags(["bun", "/pi", "--extension"]);
+    expect(r.extensionPaths).toEqual([]);
+  });
+
+  it("-e 短形式多次 + 等号混用", () => {
+    const r = mirrorMainProcessFlags(["bun", "/pi", "-e", "/a", "-e=/b", "-e", "/c"]);
+    expect(r.extensionPaths).toEqual(["/a", "/b", "/c"]);
+  });
 });
 
 // ============================================================

package/src/execution/__tests__/tool-action.test.ts

@@ -89,11 +89,11 @@ describe("startHandler", () => {
     await expect(startHandler(svc, { task: "ok", slug: "   " }, undefined)).rejects.toThrow(/slug is required/);
   });
 
-  it("slug 超 20 字符 → throw", async () => {
+  it("slug 超 35 字符 → throw", async () => {
     const svc = makeService();
     await expect(
-      startHandler(svc, { task: "ok", slug: "a".repeat(21) }, undefined),
-    ).rejects.toThrow(/≤20 chars/);
+      startHandler(svc, { task: "ok", slug: "a".repeat(36) }, undefined),
+    ).rejects.toThrow(/≤35 chars/);
   });
 
   it("background 启动 → kind=bg + bgResponse.message 含 detached", async () => {

package/src/execution/argv-mirror.ts

@@ -0,0 +1,90 @@
+/**
+ * 从主进程 argv 解析可镜像给子进程的 flag。
+ *
+ * 独立模块：argv 解析是独立职责，从 session-runner.ts 拆出避免该文件超行数上限。
+ */
+
+/**
+ * 镜像 flag 集合：从主进程 argv 解析出的可透传给子进程的 flag。
+ * 面向 buildSpawnArgs 的入参形态（解析后）。undefined 字段语义与解析为空一致。
+ */
+export interface MirrorFlags {
+  noExtensions: boolean;
+  approve: boolean;
+  extensionPaths: string[];
+}
+
+/**
+ * 有值 flag 的解析规则表：成员是「后跟一个值」的 flag 名（含长短形式）。
+ * 用于 mirrorMainProcessFlags 跳过其他 flag 的值时不误吃。
+ */
+const VALUED_FLAGS = new Set<string>([
+  "--extension", "-e",
+  "--skill",
+  "--model", "--system-prompt", "--append-system-prompt",
+  "--tools", "-t", "--exclude-tools", "-xt",
+  "--fork", "--session-dir", "--mode",
+  "--thinking", "--models",
+]);
+
+/** argv 中 flag 的起始索引：argv[0]=runtime, argv[1]=binary 路径。 */
+const ARGV_FLAG_START = 2;
+
+/**
+ * 从主进程 argv 解析可镜像的 flag（--no-extensions/--approve/--extension）。
+ *
+ * 数据源是主 pi 进程的 process.argv：子进程 spawn 的父就是主进程，
+ * 主进程 argv 完整保留启动时收到的全部 flag（已运行时验证）。这让子进程
+ * extension/approve 加载行为与主进程一致，且对任意 pi 宿主通用（不止 xyz-agent）。
+ *
+ * 解析规则：
+ * - --no-extensions / -ne、--approve / -a：布尔 flag
+ * - --extension / -e：支持 `--extension <path>`（空格）与 `--extension=<path>`（等号）
+ * - 其他 flag（在 VALUED_FLAGS 中）的值不被误当 extension 路径
+ * - positional 参数被忽略
+ * - argv[0]/argv[1] 是 bun/pi binary 路径，从 argv[2:] 开始扫
+ */
+export function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags {
+  let hasNoExtensions = false;
+  let hasApprove = false;
+  const extensionPaths: string[] = [];
+
+  // argv[0]=runtime(bun), argv[1]=pi binary 路径；flag 从 argv[2] 起
+  const flagArgs = argv.length > ARGV_FLAG_START ? argv.slice(ARGV_FLAG_START) : [];
+
+  for (let i = 0; i < flagArgs.length; i++) {
+    const tok = flagArgs[i];
+    if (tok === "--no-extensions" || tok === "-ne") {
+      hasNoExtensions = true;
+      continue;
+    }
+    if (tok === "--approve" || tok === "-a") {
+      hasApprove = true;
+      continue;
+    }
+    // 等号形式 --extension=path / -e=path
+    const eqMatch = /^(--extension|-e)=(.*)$/.exec(tok);
+    if (eqMatch) {
+      const val = eqMatch[2];
+      if (val) extensionPaths.push(val);
+      continue;
+    }
+    // 空格形式 --extension <path> / -e <path>：值在下一个 token
+    if (tok === "--extension" || tok === "-e") {
+      const next = flagArgs[i + 1];
+      if (next !== undefined && !next.startsWith("-") && next.length > 0) {
+        extensionPaths.push(next);
+        i++; // 跳过值
+      }
+      continue;
+    }
+    // 其他有值 flag：跳过其值，避免误吃（如 --skill /a 的 /a）
+    if (VALUED_FLAGS.has(tok)) {
+      i++;
+      continue;
+    }
+    // 其他情况（未知 flag、--flag=val 形式、positional）忽略
+  }
+
+  return { noExtensions: hasNoExtensions, approve: hasApprove, extensionPaths };
+}

package/src/execution/execute-options-mapper.ts

@@ -11,9 +11,11 @@ import type { ExecuteOptions } from "./types.ts";
 
 /**
  * slug 最大长度（字符）。subagent/workflow 创建时 slug 超过此值会被截断。
- * 与 subagent tool schema 的 maxLength: 20 保持一致。
+ * subagent/workflow tool schema 的 maxLength 引用此常量（单一真相，勿再硬编码）。
+ * 历史值 20 偏紧——描述性 slug 如 "audit-structured-output"（23）/"fix-subagent-wf-tools"（21）
+ * 会撞上限，放宽到 35 兼顾「短到能塞进 TUI 标题行」与「容纳合理描述性 kebab-case 名」。
  */
-export const SLUG_MAX_LENGTH = 20;
+export const SLUG_MAX_LENGTH = 35;
 
 /**
  * D-A2: AgentCallOpts → ExecuteOptions 映射。
@@ -23,7 +25,7 @@ export const SLUG_MAX_LENGTH = 20;
  *
  * 映射规则：
  *   prompt          → task
- *   description     → slug（≤20 字符，超长截断。缺失时回落 agent 名）
+ *   description     → slug（≤35 字符，超长截断。缺失时回落 agent 名）
  *   agent           → agent
  *   schema          → schema
  *   schemaEnv       → schemaEnv（D-A6 bridge）

package/src/execution/session-runner.ts

@@ -11,6 +11,7 @@ import * as fs from "node:fs";
 
 import type { ExtensionMode } from "@mariozechner/pi-coding-agent";
 
+import { type MirrorFlags, mirrorMainProcessFlags } from "./argv-mirror.ts";
 import { writeAliveMarker } from "./alive-store.ts";
 import { type DialogGlobalQueue, type UiRequestHandler } from "./dialog-queue.ts";
 import { updateFromEvent } from "./execution-record.ts";
@@ -422,6 +423,11 @@ export function buildSpawnArgs(
     sessionDir: string;
     forkSource: string | undefined;
     skillPaths: string[] | undefined;
+    /**
+     * 镜像自主进程 argv 的 flag（--no-extensions/--approve/--extension）。
+     * undefined 或全空/全 false 时行为不变（向后兼容）。
+     */
+    mirrorFlags?: MirrorFlags;
   },
 ): string[] {
   // task 不通过命令行传——pi 的 runRpcMode 只消费 stdin RpcCommand，
@@ -451,6 +457,16 @@ export function buildSpawnArgs(
       args.push("--skill", sp);
     }
   }
+  // 镜像主进程的 extension/approve flag：让子进程 extension 加载行为与主进程一致。
+  // undefined/空值时不追加（向后兼容）。顺序紧跟 skill 之后，注入类 flag 集中。
+  const mf = params.mirrorFlags;
+  if (mf) {
+    if (mf.noExtensions) args.push("--no-extensions");
+    if (mf.approve) args.push("--approve");
+    for (const ep of mf.extensionPaths) {
+      args.push("--extension", ep);
+    }
+  }
   return args;
 }
 
@@ -625,6 +641,8 @@ export async function runSpawn(
       sessionDir,
       forkSource,
       skillPaths: skillPaths.length > 0 ? skillPaths : undefined,
+      // 镜像主进程 argv 的 extension/approve flag，让子进程加载行为对齐主进程
+      mirrorFlags: mirrorMainProcessFlags(process.argv),
     },
   );
   const invocation = getPiInvocation(spawnArgs);

package/src/execution/types.ts

@@ -307,7 +307,7 @@ export interface ExecutionRecord {
   readonly mode: ExecutionMode;
   readonly task: string;
   /**
-   * 人类可读的短标签（≤20 字符），简述本次 subagent「在做什么」。
+   * 人类可读的短标签（≤35 字符），简述本次 subagent「在做什么」。
    * 区别于 agent（类型名）/ task（完整 prompt）。旧持久化 record 反序列化时缺失兜底空串。
    */
   readonly slug: string;
@@ -367,7 +367,7 @@ export interface SubagentToolDetails {
   agent: string;
   model: string;
   thinkingLevel: string | undefined;
-  /** 短标签（≤20 字符），来自 record.slug。旧 record 反序列化时为空串。 */
+  /** 短标签（≤35 字符），来自 record.slug。旧 record 反序列化时为空串。 */
   slug: string;
   turns: number;
   totalTokens: number;
@@ -395,7 +395,7 @@ export interface SubagentToolDetails {
 export interface ExecuteOptions {
   task: string;
   /**
-   * 短标签（≤20 字符），简述本次执行用途，展示在 TUI。必填。
+   * 短标签（≤35 字符），简述本次执行用途，展示在 TUI。必填。
    * workflow 内 agent() 调用时从 AgentCallOpts.description 透传而来。
    */
   slug: string;
@@ -448,7 +448,7 @@ export type ExecutionHandle = {
 export interface SubagentListItem {
   subagentId: string;
   agent: string;
-  /** 短标签（≤20 字符），来自 record.slug。旧 record 反序列化时为空串。 */
+  /** 短标签（≤35 字符），来自 record.slug。旧 record 反序列化时为空串。 */
   slug: string;
   status: ExecutionStatus;
   mode: ExecutionMode;
@@ -503,7 +503,7 @@ export interface SubagentRecord {
   agent: string;
   /** 任务提示词（详情面板置顶展示）。磁盘/内存源均有。 */
   task: string;
-  /** 短标签（≤20 字符）。磁盘重建源旧文件可能缺失→兜底空串。 */
+  /** 短标签（≤35 字符）。磁盘重建源旧文件可能缺失→兜底空串。 */
   slug: string;
   status: ExecutionStatus;
   mode: ExecutionMode;
@@ -570,7 +570,7 @@ export interface RecordSnapshot {
   readonly thinkingLevel: string | undefined;
   readonly mode: ExecutionMode;
   readonly task: string;
-  /** 短标签（≤20 字符）。来自 record.slug。 */
+  /** 短标签（≤35 字符）。来自 record.slug。 */
   readonly slug: string;
   readonly status: ExecutionStatus;
   readonly turns: number;

package/src/interface/__tests__/detectors.test.ts

@@ -0,0 +1,76 @@
+// Behavioral tests for weak-model parameter-misuse detectors.
+//
+// Complements the source-text prompt-quality tests (subagent-tool-prompt.test.ts /
+// workflow-tool-prompt.test.ts): those lock that the Correct examples / anti-pattern
+// STRINGS exist in source; these lock the actual trigger/no-trigger LOGIC, so a
+// refactor that inverts a condition or swaps keys cannot pass just by keeping the
+// literal string alive.
+//
+// Covers the detectors added in the weak-model-robustness PR:
+//   - subagent hasFlattenedStartFields (startParam envelope missing)
+//   - workflow findFlattenedArgKeys (args sub-fields flattened to top level — P0)
+
+import { describe, expect, it } from "vitest";
+
+import { hasFlattenedStartFields } from "../subagent-tool";
+import { findFlattenedArgKeys } from "../tool-workflow";
+
+describe("hasFlattenedStartFields (subagent startParam flatten detector)", () => {
+  it("triggers when task/slug flattened to top level (the original failure mode)", () => {
+    expect(hasFlattenedStartFields({ action: "start", task: "x", slug: "s" })).toBe(true);
+    expect(hasFlattenedStartFields({ action: "start", task: "x" })).toBe(true);
+    expect(hasFlattenedStartFields({ action: "start", slug: "s" })).toBe(true);
+  });
+
+  it("does NOT trigger when startParam envelope is present (correct nesting)", () => {
+    expect(
+      hasFlattenedStartFields({ action: "start", startParam: { task: "x", slug: "s" } }),
+    ).toBe(false);
+  });
+
+  it("does NOT trigger when neither task nor slug is present", () => {
+    expect(hasFlattenedStartFields({ action: "start" })).toBe(false);
+    expect(hasFlattenedStartFields({ action: "list" })).toBe(false);
+  });
+
+  it("returns false for non-object input", () => {
+    expect(hasFlattenedStartFields(null)).toBe(false);
+    expect(hasFlattenedStartFields(undefined)).toBe(false);
+    expect(hasFlattenedStartFields("start")).toBe(false);
+    expect(hasFlattenedStartFields(42)).toBe(false);
+  });
+});
+
+describe("findFlattenedArgKeys (workflow args flatten detector — P0)", () => {
+  it("triggers when args sub-fields flattened to top level", () => {
+    expect(findFlattenedArgKeys({ action: "run", name: "chain", task: "x" })).toEqual(["task"]);
+    expect(findFlattenedArgKeys({ action: "run", name: "x", items: ["a"] })).toEqual(["items"]);
+    expect(
+      findFlattenedArgKeys({ action: "run", name: "x", task: "t", perspectives: ["p"] }),
+    ).toEqual(["task", "perspectives"]);
+  });
+
+  it("does NOT trigger when fields correctly nested in args", () => {
+    expect(
+      findFlattenedArgKeys({ action: "run", name: "x", args: { task: "x", items: ["a"] } }),
+    ).toEqual([]);
+  });
+
+  it("edge: key present at BOTH top-level and inside args is NOT flagged", () => {
+    // 同时传 args.task 和顶层 task：args 已提供，顶层冗余被忽略，不算平铺。
+    // 这是 reviewer 点名的 untested edge。
+    expect(
+      findFlattenedArgKeys({ action: "run", name: "x", args: { task: "x" }, task: "y" }),
+    ).toEqual([]);
+  });
+
+  it("does NOT trigger when no known arg keys present", () => {
+    expect(findFlattenedArgKeys({ action: "run", name: "x", args: {} })).toEqual([]);
+    expect(findFlattenedArgKeys({ action: "status" })).toEqual([]);
+  });
+
+  it("returns [] for non-object input", () => {
+    expect(findFlattenedArgKeys(null)).toEqual([]);
+    expect(findFlattenedArgKeys(undefined)).toEqual([]);
+  });
+});

package/src/interface/__tests__/subagent-tool-prompt.test.ts

@@ -9,11 +9,12 @@
 // 删掉或弱化。读源码而非 import，避免 mock 链（subagent-tool.ts 依赖 pi-ai/
 // typebox/pi-tui/ExtensionAPI 等值导入）。
 
-import { describe, expect, it } from "vitest";
 import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { dirname,join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { describe, expect, it } from "vitest";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SUBAGENT_TOOL_SRC = readFileSync(
   join(__dirname, "../subagent-tool.ts"),
@@ -30,10 +31,12 @@ function extractDescription(src: string): string {
 const DESCRIPTION = extractDescription(SUBAGENT_TOOL_SRC);
 
 describe("subagent tool description — 行为约束器（非功能说明书）", () => {
-  it("词数 ≤ 400（高风险 description 密度上限）", () => {
+  it("词数 ≤ 550（高风险 description 密度上限）", () => {
     // 高风险 tool 的 description 应聚焦约束而非功能铺陈；过长会稀释信号。
+    // 上限从 400 放宽到 550：补了 JSON 调用正例段（start/list/cancel 三 action 完整 JSON），
+    // 正例对弱模型首次调用用对参数的价值 > 节省这点 description 预算。
     const words = DESCRIPTION.trim().split(/\s+/).filter(Boolean).length;
-    expect(words).toBeLessThanOrEqual(400);
+    expect(words).toBeLessThanOrEqual(550);
   });
 
   it("含 'When to delegate' 调用条件段（何时委派 vs 自己做）", () => {
@@ -81,4 +84,24 @@ describe("subagent tool description — 行为约束器（非功能说明书）"
     expect(DESCRIPTION).toMatch(/sequential/);
     expect(DESCRIPTION).toMatch(/SAME message/i);
   });
+
+  it("Examples 段含完整 JSON 正例（含 startParam 嵌套结构）", () => {
+    // 弱模型信任 schema 结构信号 > 文本信号，容易把 task/slug 平铺到顶层。
+    // description 必须有完整 JSON 正例，让模型能直接照抄 startParam 嵌套结构。
+    expect(DESCRIPTION).toContain('{"action":"start","startParam"');
+  });
+
+  it("Anti-patterns 段含参数结构反例（top level 平铺 task/slug）", () => {
+    // 显式说明 task/slug 不能平铺到顶层，必须嵌在 startParam 里。
+    expect(DESCRIPTION).toContain("top level");
+  });
+});
+
+describe("subagent tool runtime handler — 错误文案含纠正正例", () => {
+  // 读源码文本断言 executeSubagent 的平铺检测 throw 含 Correct 正例，
+  // 让弱模型撞错后第二次能直接照抄正确形态。
+  it("subagent-tool.ts 含 runtime 平铺检测 throw + Correct 纠正正例", () => {
+    expect(SUBAGENT_TOOL_SRC).toContain("Correct:");
+    expect(SUBAGENT_TOOL_SRC).toContain("params.action === \"start\" && !params.startParam");
+  });
 });

package/src/interface/__tests__/workflow-tool-prompt.test.ts

@@ -7,11 +7,12 @@
 // 本测试用源码断言（读 .ts 文件文本）验证提示词内容，避免 import 重 mock 链
 // （tool-workflow.ts 依赖 pi-ai/typebox/pi-tui/lifecycle 等值导入）。
 
-import { describe, expect, it } from "vitest";
 import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { dirname,join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { describe, expect, it } from "vitest";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TOOL_WORKFLOW_SRC = readFileSync(
   join(__dirname, "../tool-workflow.ts"),
@@ -43,6 +44,27 @@ describe("U1: workflow tool prompt mentions built-in workflows", () => {
     expect(TOOL_WORKFLOW_SRC).toMatch(/workflow run .+--args/i);
   });
 
+  it("promptGuidelines 含 JSON 调用正例（run/status/lifecycle/retry-node）", () => {
+    // 弱模型信任 schema 结构信号 > 文本信号，容易把 args 子字段平铺到顶层。
+    // promptGuidelines 必须有完整 JSON 调用正例，让模型能直接照抄 {"action":"run",...} 嵌套结构。
+    expect(TOOL_WORKFLOW_SRC).toContain('{"action":"run"');
+    expect(TOOL_WORKFLOW_SRC).toContain("Call shapes (JSON)");
+  });
+
+  it("promptGuidelines 含参数结构反例（args 平铺到顶层）", () => {
+    // 显式说明 args 子字段不能平铺到顶层，必须嵌在 args 里。
+    expect(TOOL_WORKFLOW_SRC).toContain("args");
+    expect(TOOL_WORKFLOW_SRC).toContain("Anti-patterns");
+    expect(TOOL_WORKFLOW_SRC).toContain("top level");
+  });
+
+  it("runtime handler 错误文案含 Correct 纠正正例 + 平铺检测", () => {
+    // 读源码文本断言 actionRun/必填校验的错误文案含 Correct 正例，
+    // 让弱模型撞错后第二次能直接照抄正确形态。KNOWN_ARG_KEYS 证明平铺检测存在。
+    expect(TOOL_WORKFLOW_SRC).toContain("Correct:");
+    expect(TOOL_WORKFLOW_SRC).toContain("KNOWN_ARG_KEYS");
+  });
+
   it("tool-workflow-script.ts list action 的 promptGuidelines 含 workflow run 交叉引用", () => {
     // 反向交叉引用：list 的指引里要提到用 workflow tool 的 run action 启动脚本。
     expect(TOOL_WORKFLOW_SCRIPT_SRC).toMatch(/workflow.*tool.*run|run.*workflow.*tool/i);

package/src/interface/subagent-actions.ts

@@ -9,6 +9,12 @@
 // content（JSON 字符串）给 LLM，details（SubagentToolResult）给 renderResult，同源同处生成。
 
 import type { AgentToolResult } from "@mariozechner/pi-coding-agent";
+import {
+  guiComponent,
+  type GuiContext,
+  guiResult,
+  isGuiCapable,
+} from "@xyz-agent/extension-protocol";
 
 import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
 import { computeElapsedSeconds } from "../execution/execution-record.ts";
@@ -22,12 +28,6 @@ import type {
   SubagentRecord,
   SubagentToolResult,
 } from "../execution/types.ts";
-import {
-  guiComponent,
-  type GuiContext,
-  guiResult,
-  isGuiCapable,
-} from "@xyz-agent/extension-protocol";
 import { mapRunIcon, mapRunStatus } from "./gui-mappers.ts";
 
 // ============================================================
@@ -42,6 +42,9 @@ const MAX_LIST_LIMIT = 100;
 /** background 启动提示文案（spec FR-3 bgResponse.message）。 */
 const BG_MESSAGE = "detached, will notify on completion (auto-injected message, do not poll)";
 
+/** subagentId（UUID）在 GUI header 的截断显示长度。 */
+const SUBAGENT_ID_PREVIEW = 8;
+
 // ============================================================
 // 入参 / 出参类型
 // ============================================================
@@ -49,7 +52,7 @@ const BG_MESSAGE = "detached, will notify on completion (auto-injected message,
 /** start 入参（从 tool params.startParam 来，task + slug 必填）。 */
 export interface StartHandlerInput {
   task?: string;
-  /** 短标签（≤20 字符），必填。 */
+  /** 短标签（≤35 字符，kebab-case），必填。 */
   slug?: string;
   agent?: string;
   model?: string;
@@ -141,7 +144,7 @@ export async function startHandler(
   // slug 必填 + 空白校验 + 长度校验（≤ SLUG_MAX_LENGTH 字符）
   const slug = input.slug?.trim();
   if (!slug) throw new Error("startParam.slug is required (and must not be whitespace-only)");
-  if (slug.length > SLUG_MAX_LENGTH) throw new Error(`startParam.slug must be ≤${SLUG_MAX_LENGTH} chars (got ${slug.length})`);
+  if (slug.length > SLUG_MAX_LENGTH) throw new Error(`startParam.slug must be ≤${SLUG_MAX_LENGTH} chars (got ${slug.length}). Shorten to a kebab-case label, e.g. "fix-login", "extract-urls".`);
 
   const handle = await service.execute({
     task,
@@ -291,7 +294,7 @@ export function buildGuiComponent(
     // 利用 input.domain 的身份信息，让并发 subagent 可区分。
     const d = input.domain as StartHandlerResult;
     return guiComponent("card", {
-      header: d.slug ? `${d.slug}` : d.subagentId.slice(0, 8),
+      header: d.slug ? `${d.slug}` : d.subagentId.slice(0, SUBAGENT_ID_PREVIEW),
       body: [guiComponent("stats-line", {
         items: [{ value: "running", severity: "ok" }],
       })],

package/src/interface/subagent-tool.ts

@@ -14,6 +14,7 @@ import { StringEnum } from "@mariozechner/pi-ai";
 import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 
+import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
 import { getSubagentService } from "../execution/subagent-service.ts";
 import type { SubagentToolResult } from "../execution/types.ts";
 import { extractAgentName } from "./format.ts";
@@ -32,7 +33,7 @@ import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./t
  */
 interface StartParam {
   task: string;
-  /** 短标签（≤20 字符），必填。展示在 TUI 标题行/列表。 */
+  /** 短标签（≤35 字符，kebab-case），必填。展示在 TUI 标题行/列表。 */
   slug: string;
   agent?: string;
   model?: string;
@@ -107,9 +108,9 @@ const SubagentParams = Type.Object({
     }),
     slug: Type.String({
       description:
-        "REQUIRED for action:'start'. Short label (≤20 chars) for this subagent, e.g. 'fix-login', 'extract-urls'. " +
+        "REQUIRED for action:'start'. Short label (≤35 chars) for this subagent, e.g. 'fix-login', 'extract-urls'. " +
         "Shown in TUI to distinguish concurrent subagents.",
-      maxLength: 20,
+      maxLength: SLUG_MAX_LENGTH,
     }),
     agent: Type.Optional(Type.String({
       description: 'Agent name (system prompt + tools). If omitted, defaults to "general-purpose" — a generic agent that inherits the main agent\'s model and project context. Available: general-purpose (default fallback), worker, researcher, explorer, planner, reviewer, oracle, context-builder. Custom agents configurable.',
@@ -175,6 +176,16 @@ function hasStartParam(a: unknown): a is { startParam?: unknown } {
   return typeof a === "object" && a !== null && "startParam" in a;
 }
 
+/** action:'start' 入参是否把 task/slug 平铺到顶层（弱模型常见误用：缺 startParam 嵌套）。 */
+/**
+ * action:'start' 入参是否把 task/slug 平铺到顶层（弱模型常见误用：缺 startParam 嵌套）。
+ * export 供 behavioral 测试（trigger/no-trigger），不改变运行时行为。
+ */
+export function hasFlattenedStartFields(a: unknown): boolean {
+  if (typeof a !== "object" || a === null) return false;
+  return "task" in a || "slug" in a;
+}
+
 /** 从 unknown args 安全提取 model/thinkingLevel override（传给 resolveModel）。 */
 function extractModelOverride(args: unknown): { model?: string; thinkingLevel?: string } | undefined {
   if (!isModelOverrideObj(args)) return undefined;
@@ -207,6 +218,15 @@ Delegate when the task needs a distinct role (researcher/worker), context isolat
 - action:"list" — list subagents. Pass listParam: { includeFinished?, limit? } (all optional). Read an item's sessionFile for full detail.
 - action:"cancel" — cancel a background subagent. REQUIRED cancelParam: { subagentId }.
 
+## Examples
+
+\`\`\`
+{"action":"start","startParam":{"task":"<your task>","slug":"<kebab-case>"}}
+{"action":"start","startParam":{"task":"...","slug":"fix-login","agent":"worker","model":"anthropic/claude-3.5-sonnet","fork":true}}
+{"action":"list","listParam":{"includeFinished":false,"limit":20}}
+{"action":"cancel","cancelParam":{"subagentId":"sa_abc123"}}
+\`\`\`
+
 ## After launching — do NOT wait
 
 Completion auto-notifies you (steer wakes next turn, even mid-poll). So:
@@ -217,6 +237,7 @@ Completion auto-notifies you (steer wakes next turn, even mid-poll). So:
 
 ## Anti-patterns
 
+- Putting task/slug at the top level instead of inside startParam — the tool reads startParam.task, not a top-level task.
 - Launching background, then sleeping/polling instead of working or stopping.
 - Treating subagent results as authoritative without verification.
 - Delegating trivial tasks you could do faster yourself.
@@ -311,6 +332,17 @@ const executeSubagent: SubagentExecuteCb = async (
   const service = getSubagentService();
   if (!service) throw new Error("subagents runtime not initialized");
 
+  // 弱模型常见误用：action:'start' 时把 task/slug 平铺到顶层（缺 startParam 嵌套层）。
+  // schema 用 Type.Optional 表达条件必填（flat JSON Schema 无法表达），弱模型信任
+  // 结构信号 > 文本信号，倾向省略嵌套层。这里在进 startHandler 之前拦截平铺形态，
+  // throw 带 Correct 正例，让弱模型撞错后第二次能直接照抄。
+  if (params.action === "start" && !params.startParam && hasFlattenedStartFields(params)) {
+    throw new Error(
+      "startParam is required for action:'start' — wrap task/slug inside startParam. " +
+      "Correct: {\"action\":\"start\",\"startParam\":{\"task\":\"<your task>\",\"slug\":\"<kebab-case>\"}}",
+    );
+  }
+
   switch (params.action) {
     case "start":
       return adapter({ action: "start", domain: await startHandler(service, params.startParam, signal, _ctx?.model) }, toGuiCtx(_ctx));

package/src/interface/tool-workflow.ts

@@ -22,13 +22,6 @@
 import { StringEnum } from "@mariozechner/pi-ai";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
-import { type Static, Type } from "typebox";
-
-import type { LauncherDeps } from "../orchestration/launcher.ts";
-import { abortRun, pauseRun, resumeRun, runWorkflow } from "../orchestration/lifecycle.ts";
-import type { RunStore } from "../orchestration/models/ports.ts";
-import type { WorkflowRun } from "../orchestration/models/workflow-run.ts";
-import { retryNode, skipNode } from "../orchestration/node-ops.ts";
 import {
   guiComponent,
   type GuiContext,
@@ -36,6 +29,14 @@ import {
   guiResult,
   isGuiCapable,
 } from "@xyz-agent/extension-protocol";
+import { type Static, Type } from "typebox";
+
+import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
+import type { LauncherDeps } from "../orchestration/launcher.ts";
+import { abortRun, pauseRun, resumeRun, runWorkflow } from "../orchestration/lifecycle.ts";
+import type { RunStore } from "../orchestration/models/ports.ts";
+import type { WorkflowRun } from "../orchestration/models/workflow-run.ts";
+import { retryNode, skipNode } from "../orchestration/node-ops.ts";
 import { mapRunIcon, mapRunStatus, toGuiCtx } from "./gui-mappers.ts";
 import {
   acquireReentryGuard,
@@ -75,9 +76,9 @@ const WorkflowParams = Type.Object({
   slug: Type.Optional(
     Type.String({
       description:
-        "Short label (max 20 chars) for this run, shown in the TUI to distinguish concurrent runs. " +
+        "Short label (max 35 chars) for this run, shown in the TUI to distinguish concurrent runs. " +
         "If omitted, defaults to the script name.",
-      maxLength: 20,
+      maxLength: SLUG_MAX_LENGTH,
     }),
   ),
   runId: Type.Optional(
@@ -105,6 +106,23 @@ type WorkflowToolParams = Static<typeof WorkflowParams>;
 /** runId 截断长度（显示用）。 */
 const RUNID_SHORT = 8;
 
+/** 已知 workflow args 子字段——run action 的 args 顶层键。弱模型常把 task/items 等
+ *  平铺到 workflow params 顶层（缺 args 嵌套），actionRun 静默 args={} 启动缺参 run（P0）。
+ *  用此清单检测平铺形态，报错带 Correct 正例纠正。 */
+const KNOWN_ARG_KEYS = ["task", "target", "perspectives", "items", "itemsJson", "operation"];
+
+/**
+ * 检测弱模型把 args 子字段平铺到 workflow params 顶层（P0 静默失败防护）。
+ * 返回被平铺的键名列表（空 = 未平铺）。export 供 behavioral 测试（trigger/no-trigger/edge）。
+ * 参数取 unknown 以便测试构造任意对象、并解耦 WorkflowToolParams 的 index-signature 限制。
+ */
+export function findFlattenedArgKeys(params: unknown): string[] {
+  if (typeof params !== "object" || params === null) return [];
+  const p = params as Record<string, unknown>;
+  const args = typeof p.args === "object" && p.args !== null ? p.args : undefined;
+  return KNOWN_ARG_KEYS.filter((k) => k in p && !(args !== undefined && k in args));
+}
+
 // ── Types ────────────────────────────────────────────────────
 
 interface RunSummary {
@@ -170,7 +188,7 @@ export function buildWorkflowGui(details: WorkflowToolDetails) {
     const statusStr = details.status;
     return guiComponent("list-tree", {
       items: [{
-        label: [details.name, details.slug, details.runId.slice(0, 8)].filter(Boolean).join(" "),
+        label: [details.name, details.slug, details.runId.slice(0, RUNID_SHORT)].filter(Boolean).join(" "),
         status: mapRunStatus(statusStr),
         icon: mapRunIcon(statusStr),
       }],
@@ -181,7 +199,7 @@ export function buildWorkflowGui(details: WorkflowToolDetails) {
       items: details.runs.map((r) => {
         const statusStr = r.reason ? `${r.status} (${r.reason})` : r.status;
         return {
-          label: [r.name, r.slug, r.runId.slice(0, 8)].filter(Boolean).join(" "),
+          label: [r.name, r.slug, r.runId.slice(0, RUNID_SHORT)].filter(Boolean).join(" "),
           status: mapRunStatus(statusStr),
           icon: mapRunIcon(statusStr),
         };
@@ -194,7 +212,7 @@ export function buildWorkflowGui(details: WorkflowToolDetails) {
   return guiComponent("stats-line", {
     items: [{
       label: details.action,
-      value: details.runId.slice(0, 8),
+      value: details.runId.slice(0, RUNID_SHORT),
       severity,
     }],
   });
@@ -245,6 +263,12 @@ export function registerWorkflowTool(
       "retry-node only re-runs the call and refreshes the trace — the workflow script has " +
       "already moved past the failed call, so the new result does NOT feed back into the " +
       "script flow. Use retry-node for diagnostics, not to resume the workflow.",
+      "Call shapes (JSON): " +
+      "- run: {\"action\":\"run\",\"name\":\"<script>\",\"args\":{...},\"tokens\":N,\"time\":N}. " +
+      "- status: {\"action\":\"status\"}. " +
+      "- pause/resume/abort: {\"action\":\"pause\",\"runId\":\"<id>\"} (abort optional: ,\"error\":\"<reason>\"}). " +
+      "- retry-node/skip-node: {\"action\":\"retry-node\",\"runId\":\"<id>\",\"callId\":N}.",
+      "Anti-patterns: Flattening args sub-fields (task/items/...) to the top level — they belong inside args. Calling {\"action\":\"run\"} without name.",
     ],
     parameters: WorkflowParams,
 
@@ -340,7 +364,25 @@ async function actionRun(
 ): Promise<ToolResult> {
   const name = params.name;
   if (!name) {
-    return textResult("run requires 'name' parameter", true);
+    return textResult("run requires 'name' parameter. Correct: {\"action\":\"run\",\"name\":\"<script>\",\"args\":{...}}", true);
+  }
+  // 弱模型常见误用（P0 静默失败）：把 task/items 等 args 子字段平铺到 workflow params
+  // 顶层（缺 args 嵌套）。下面 args ?? {} 会静默 args={}，启动缺参 run 不报错——比 subagent
+  // 平铺事故更严重。这里检测顶层平铺，报错带 Correct 正例纠正。
+  const flattened = findFlattenedArgKeys(params);
+  if (flattened.length > 0) {
+    return textResult(
+      `Detected ${flattened.join(", ")} at top level — they belong inside 'args'. ` +
+      `Correct: {"action":"run","name":"${name}","args":{${flattened.map((k) => `"${k}": "<value>"`).join(", ")}}}`,
+      true,
+    );
+  }
+  // slug 运行时护栏（与 subagent startHandler 对称的纵深防御；schema maxLength 是第一道关卡）
+  if (params.slug !== undefined && params.slug.length > SLUG_MAX_LENGTH) {
+    return textResult(
+      `slug exceeds ${SLUG_MAX_LENGTH} chars (got ${params.slug.length}). Shorten to a kebab-case label, e.g. "fix-login", "extract-urls".`,
+      true,
+    );
   }
   const args = params.args ?? {};
   const tokens = params.tokens;
@@ -426,7 +468,7 @@ async function actionLifecycle(
 ): Promise<ToolResult> {
   const runId = params.runId;
   if (!runId) {
-    return textResult(`'runId' is required for ${action}`, true);
+    return textResult(`'runId' is required for ${action}. Correct: {"action":"${action}","runId":"<id>"} (use action:"status" to find runId)`, true);
   }
   const run = deps.runs.get(runId);
   if (!run) {
@@ -467,7 +509,7 @@ async function actionRetryNode(params: WorkflowToolParams, deps: LauncherDeps):
   const runId = params.runId;
   const callId = params.callId;
   if (!runId || callId === undefined) {
-    return textResult("retry-node requires 'runId' and 'callId'", true);
+    return textResult("retry-node requires 'runId' and 'callId'. Correct: {\"action\":\"retry-node\",\"runId\":\"<id>\",\"callId\":<number>}", true);
   }
   const run = deps.runs.get(runId);
   if (!run) {
@@ -494,7 +536,7 @@ async function actionSkipNode(params: WorkflowToolParams, deps: LauncherDeps): P
   const runId = params.runId;
   const callId = params.callId;
   if (!runId || callId === undefined) {
-    return textResult("skip-node requires 'runId' and 'callId'", true);
+    return textResult("skip-node requires 'runId' and 'callId'. Correct: {\"action\":\"skip-node\",\"runId\":\"<id>\",\"callId\":<number>}", true);
   }
   const run = deps.runs.get(runId);
   if (!run) {