@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/execution/__tests__/run-spawn-stdout-callback-throw.test.ts

@@ -0,0 +1,199 @@
+// src/execution/__tests__/run-spawn-stdout-callback-throw.test.ts
+//
+// [F-R2] stdout data 同步回调链内 fail-fast throw 不逃逸（不升级为 uncaughtException 崩宿主）。
+//
+// 背景：session-runner 的两处 timer 安全校验调用位于 child.stdout.on("data") 同步回调链内：
+//   ① agent_end keep-alive 分支的 resolveSpawnWatchdogMs（→ assertSafeTimerDelay fail-fast）
+//   ② chatMode agent_settled 分支的 armIdleTimer（→ assertSafeTimerDelay fail-fast）
+// 旧实现任一处 throw 都会逃出事件回调 = Node uncaughtException 崩宿主进程。
+// 修复：调用点包 try/catch 降级（不挂 timer），错误经 bestEffort("error") 可见。
+//
+// mock 结构与 run-spawn-chatmode-settled.test.ts 一致（FakeChild + lifecycle-manager 真实模块）。
+// logger 整体 mock（loggerMock spy）断言错误可见——「fail-fast 语义保留（错误可见、行为明确）
+// 但不升级为进程崩溃」。
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// logger mock：bestEffort / session-runner 共享同一 loggerMock（断言错误可见性）。
+// vi.hoisted：vi.mock 工厂被提升到顶层 const 之前执行，loggerMock 必须经 vi.hoisted 创建。
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({ getLogger: () => loggerMock }));
+
+vi.mock("node:child_process", async () => {
+  const { FakeChild } = await import("./helpers/spawn-mock.ts");
+  return {
+    spawn: vi.fn(() => new FakeChild()),
+    // buildEnvBlock 的 git branch 调用（execFile 异步）：默认 err-first 兜底 → catch → branch=""
+    execFile: vi.fn(
+      (
+        _cmd: string,
+        _args: readonly string[],
+        _opts: unknown,
+        cb: (err: Error | null, stdout?: string, stderr?: string) => void,
+      ) => cb(new Error("execFile not configured in this test")),
+    ),
+  };
+});
+
+vi.mock("node:fs", async () => {
+  const actual = await import("node:fs");
+  return {
+    default: {
+      ...actual,
+      mkdirSync: vi.fn(),
+      existsSync: vi.fn(() => false),
+      appendFileSync: vi.fn(),
+      writeFileSync: vi.fn(),
+      readdirSync: vi.fn(() => []),
+    },
+    mkdirSync: vi.fn(),
+    existsSync: vi.fn(() => false),
+    appendFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+    promises: actual.promises,
+  };
+});
+
+vi.mock("../alive-store.ts", () => ({
+  writeAliveMarker: vi.fn(),
+}));
+
+// 场景 ① 依赖 keep-alive 分支命中：count=1（有活跃后代 → 不 kill → 重挂 watchdog）
+vi.mock("../session-pending.ts", () => ({
+  readActivePendingFromSessionFile: vi.fn(() => ({ count: 1 })),
+}));
+
+vi.mock("../temp-prompt.ts", () => ({
+  writePromptToTempFile: vi.fn(async (agent: string) => {
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { runSpawn, SPAWN_WATCHDOG_ENV } from "../session-runner.ts";
+import type { SessionRunnerContext } from "../session-runner.ts";
+import { hasIdleTimer, _resetLifecycleState } from "../lifecycle-manager.ts";
+import { createRecord } from "../execution-record.ts";
+import type { ExecutionRecord } from "../types.ts";
+import {
+  emitStdoutLine,
+  type FakeChild,
+  lastSpawnedChild as lastSpawnedChildOf,
+  makeCtx,
+  makeOpts,
+  makeRecord,
+  sessionHeader,
+  waitForSpawn as waitForSpawnOf,
+} from "./helpers/spawn-mock.ts";
+
+const mockSpawn = vi.mocked(spawn);
+
+const lastSpawnedChild = (): FakeChild => lastSpawnedChildOf(mockSpawn);
+const waitForSpawn = (timeoutMs = 1000): Promise<void> => waitForSpawnOf(mockSpawn, timeoutMs);
+
+/** 构造 chatMode record（idleTimeoutMs 设为超出 setTimeout 安全域的值 → assertSafeTimerDelay throw）。 */
+function makeChatModeRecord(id = "sa-f2-idle"): ExecutionRecord {
+  return createRecord(id, {
+    agent: "general-purpose",
+    model: "test-model",
+    mode: "sync",
+    task: "chat task",
+    slug: "chat",
+    startedAt: 1_000_000,
+    rootSessionId: "root-session",
+    parentRecordId: undefined,
+    depth: 0,
+    chatMode: true,
+    // > 2^31-1：Node setTimeout 溢出域，assertSafeTimerDelay fail-fast
+    idleTimeoutMs: Number.MAX_SAFE_INTEGER,
+  });
+}
+
+describe("[F-R2] stdout 回调链内 fail-fast throw 不逃逸", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    _resetLifecycleState();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    _resetLifecycleState();
+  });
+
+  it("① agent_end keep-alive 分支 resolveSpawnWatchdogMs throw → 降级不 re-arm，run 正常收尾，error 可见", async () => {
+    const record = makeRecord();
+    const promise = runSpawn(record, "Task: keepalive", makeOpts(), makeCtx());
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    emitStdoutLine(child, sessionHeader("sess-fr2a"));
+    // 初始 watchdog 解析在 spawn 后同步块内已完成（env 未设 → 不挂）。
+    // 此刻设非法 env：agent_end keep-alive 分支再读 env → assertSafeTimerDelay throw。
+    process.env[SPAWN_WATCHDOG_ENV] = String(Number.MAX_SAFE_INTEGER);
+    try {
+      emitStdoutLine(child, { type: "agent_end", willRetry: false });
+      // 给 stream flush 留一个 tick（对齐 chatmode 测试模式）：throw 若逃逸回调，
+      // vitest 会以 unhandled error 判本测试失败——能走到断言即「未崩宿主」。
+      await new Promise((r) => setTimeout(r, 20));
+
+      // 降级语义：不 re-arm（无 timer 可直接观察的是——子进程未被 kill、run 未被中断）
+      expect(child.killed).toBe(false);
+
+      // 错误可见（fail-fast 语义保留）：bestEffort("error") 经 logger.error 落日志
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        expect.stringContaining("resolveSpawnWatchdogMs"),
+        expect.objectContaining({ detail: expect.stringContaining("exceeds the Node setTimeout limit") }),
+      );
+
+      // 收尾：run 正常完成（未被回调异常打断）
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0);
+      const result = await promise;
+      expect(result.success).toBe(true);
+    } finally {
+      delete process.env[SPAWN_WATCHDOG_ENV];
+    }
+  });
+
+  it("② chatMode agent_settled armIdleTimer throw → 降级不挂 idle timer，onRoundSettled 照常、提前 resolve", async () => {
+    const record = makeChatModeRecord("sa-f2-idle");
+    const onRoundSettled = vi.fn();
+    const ctx: Partial<SessionRunnerContext> = { onRoundSettled };
+    const promise = runSpawn(record, "Task: idle", makeOpts(), makeCtx(ctx as SessionRunnerContext));
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    emitStdoutLine(child, sessionHeader("sess-fr2b"));
+    emitStdoutLine(child, { type: "agent_settled" });
+    await new Promise((r) => setTimeout(r, 20));
+
+    // 降级语义：idle timer 未挂（throw 发生在 arm 入口校验，先于 setTimeout）
+    expect(hasIdleTimer(record.id)).toBe(false);
+    expect(child.killed).toBe(false);
+
+    // catch 后续语句照常执行：本轮完成通知不因 GC timer 故障丢失
+    expect(onRoundSettled).toHaveBeenCalledTimes(1);
+
+    // 错误可见
+    expect(loggerMock.error).toHaveBeenCalledWith(
+      expect.stringContaining("armIdleTimer"),
+      expect.objectContaining({ detail: expect.stringContaining("exceeds the Node setTimeout limit") }),
+    );
+
+    // 收尾：chatMode 首轮 agent_settled 已 resolveRun(0)，close 后 runSpawn 正常返回
+    child.stdout.end();
+    child.stderr.end();
+    child.emit("close", 0);
+    const result = await promise;
+    expect(result.success).toBe(true);
+  });
+});

package/src/execution/__tests__/session-runner-schema-env.test.ts

@@ -94,8 +94,10 @@ import {
   applySchemaEnvToChildEnv,
   type RunOptions,
   runSpawn,
+  SCHEMA_ENV_MAX_BYTES,
   type SessionRunnerContext,
 } from "../session-runner.ts";
+import { schemaEnvByteLength } from "../../shared/schema-env.ts";
 
 const mockSpawn = vi.mocked(spawn);
 const mockExistsSync = vi.mocked(fs.existsSync);
@@ -225,6 +227,43 @@ describe("applySchemaEnvToChildEnv (T3.9/T3.11/T3.16)", () => {
     expect(childEnv.HOME).toBe("/home/user");
     expect(childEnv.PI_WORKFLOW_SCHEMA).toBe('{"x":1}');
   });
+
+  // [SO-DATA-4] 边界内通过：255KB（< 256KiB 上限）正常注入，行为不变
+  it("[SO-DATA-4] 255KB schema 正常注入（上限内不误拒）", () => {
+    const childEnv: Record<string, string | undefined> = {};
+    // ASCII 串 byteLength === length，构造 255KB 纯 JSON body（外层再包一层合法 JSON）
+    const padding = "x".repeat(255 * 1024);
+    const schemaJson = JSON.stringify({ type: "object", properties: { pad: { const: padding } } });
+    expect(schemaEnvByteLength(schemaJson)).toBeLessThanOrEqual(SCHEMA_ENV_MAX_BYTES);
+    applySchemaEnvToChildEnv(childEnv, schemaJson);
+    expect(childEnv.PI_WORKFLOW_SCHEMA).toBe(schemaJson);
+  });
+
+  // [SO-DATA-4] 超限 fail-fast：257KB 拒绝，错误消息含实际大小 + 精简/拆分指引 + E2BIG 归因
+  it("[SO-DATA-4] 257KB schema fail-fast 拒绝（错误含实际大小与恢复指引）", () => {
+    const childEnv: Record<string, string | undefined> = {};
+    const padding = "x".repeat(257 * 1024);
+    const schemaJson = JSON.stringify({ type: "object", properties: { pad: { const: padding } } });
+    expect(schemaEnvByteLength(schemaJson)).toBeGreaterThan(SCHEMA_ENV_MAX_BYTES);
+    expect(() => applySchemaEnvToChildEnv(childEnv, schemaJson)).toThrow(
+      expect.objectContaining({
+        message: expect.stringContaining("bytes exceeds"),
+      }),
+    );
+    // 错误消息含实际大小、上限、精简/拆分指引与 E2BIG 归因（可操作性验收）
+    try {
+      applySchemaEnvToChildEnv(childEnv, schemaJson);
+      throw new Error("expected applySchemaEnvToChildEnv to throw");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      expect(msg).toContain(String(schemaEnvByteLength(schemaJson))); // 实际大小
+      expect(msg).toContain(String(SCHEMA_ENV_MAX_BYTES)); // 上限值
+      expect(msg).toContain("simplify the schema"); // 精简指引
+      expect(msg).toContain("E2BIG"); // ARG_MAX/E2BIG 约束说明
+    }
+    // fail-fast：不写入半截值
+    expect(childEnv.PI_WORKFLOW_SCHEMA).toBeUndefined();
+  });
 });
 
 // ── runSpawn 集成测试：schemaEnv 经 RunOptions → childEnv ──

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

@@ -11,8 +11,9 @@ import { MAX_FORK_DEPTH } from "../session-context-resolver.ts";
 import { buildEnvBlock, buildSpawnArgs } from "../session-runner.ts";
 
 describe("buildSpawnArgs", () => {
+  // [U1 D2] modelRef 为必填（spawn 前置守卫：未经裁决的裸字符串类型层面不可达）。
   const baseParams = {
-    model: undefined as string | undefined,
+    modelRef: { provider: "openai", id: "gpt-4o" },
     thinkingLevel: undefined as string | undefined,
     agentTools: undefined as string[] | undefined,
     appendSystemPromptPath: undefined as string | undefined,
@@ -21,9 +22,11 @@ describe("buildSpawnArgs", () => {
     skillPaths: undefined as string[] | undefined,
   };
 
-  it("基础参数：--mode rpc --session-dir，不含 -p 也不含 task（task 经 stdin 传）", () => {
+  it("基础参数：--mode rpc --session-dir + --model provider/id，不含 -p 也不含 task（task 经 stdin 传）", () => {
     const args = buildSpawnArgs(baseParams);
-    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir"]);
+    expect(args).toEqual([
+      "--mode", "rpc", "--session-dir", "/sessions/dir", "--model", "openai/gpt-4o",
+    ]);
   });
 
   it("不含 -p / --print（rpc mode 下 -p 被 resolveAppMode 无视，是死代码）", () => {
@@ -32,28 +35,22 @@ describe("buildSpawnArgs", () => {
     expect(args).not.toContain("--print");
   });
 
-  it("有 model → 追加 --model provider/id", () => {
-    const args = buildSpawnArgs(
-      { ...baseParams, model: "openai/gpt-4o" },
-    );
-    expect(args).toContain("--model");
+  it("modelRef → --model 值恒为 `${provider}/${id}`（全等拼接，不重写输入）", () => {
+    // 含大小写差异的 provider/id 原样拼接（大小写敏感规则：放行即全等回显）
+    const args = buildSpawnArgs({
+      ...baseParams,
+      modelRef: { provider: "zai-coding-cn", id: "GLM-5.3-Flash" },
+    });
     const idx = args.indexOf("--model");
-    expect(args[idx + 1]).toBe("openai/gpt-4o");
+    expect(args[idx + 1]).toBe("zai-coding-cn/GLM-5.3-Flash");
   });
 
-  it("model + thinkingLevel → model 后缀 :level", () => {
+  it("modelRef + thinkingLevel → model 后缀 :level", () => {
     const args = buildSpawnArgs(
-      { ...baseParams, model: "anthropic/claude", thinkingLevel: "high" },
+      { ...baseParams, thinkingLevel: "high" },
     );
     const idx = args.indexOf("--model");
-    expect(args[idx + 1]).toBe("anthropic/claude:high");
-  });
-
-  it("thinkingLevel 无 model → 不追加（thinking 依赖 model 后缀）", () => {
-    const args = buildSpawnArgs(
-      { ...baseParams, model: undefined, thinkingLevel: "high" },
-    );
-    expect(args).not.toContain("--model");
+    expect(args[idx + 1]).toBe("openai/gpt-4o:high");
   });
 
   it("agentTools → --tools 逗号分隔", () => {
@@ -109,7 +106,7 @@ describe("buildSpawnArgs", () => {
   it("全参数组合：所有 flag 存在，不含 -p 也不含 positional task", () => {
     const args = buildSpawnArgs(
       {
-        model: "openai/gpt-4o",
+        ...baseParams,
         thinkingLevel: "low",
         agentTools: ["read"],
         appendSystemPromptPath: "/tmp/p.md",
@@ -179,12 +176,12 @@ describe("buildSpawnArgs", () => {
     expect(args).not.toContain("--extension");
     expect(args).not.toContain("--no-context-files");
     // 仅基础参数
-    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir"]);
+    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir", "--model", "openai/gpt-4o"]);
   });
 
   it("mirrorFlags undefined → 行为等同旧版（TC7）", () => {
     const args = buildSpawnArgs(baseParams);
-    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir"]);
+    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir", "--model", "openai/gpt-4o"]);
     expect(args).not.toContain("--extension");
     expect(args).not.toContain("--no-extensions");
     expect(args).not.toContain("--approve");
@@ -234,14 +231,13 @@ describe("buildSpawnArgs", () => {
   it("sessionFile undefined → 不含 --session（向后兼容）", () => {
     const args = buildSpawnArgs(baseParams);
     expect(args).not.toContain("--session");
-    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir"]);
+    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir", "--model", "openai/gpt-4o"]);
   });
 
-  it("sessionFile + model + thinkingLevel → 三者都进 args（resume 全参数）", () => {
+  it("sessionFile + modelRef + thinkingLevel → 三者都进 args（resume 全参数）", () => {
     const args = buildSpawnArgs({
       ...baseParams,
       sessionFile: "/sessions/sub/resume.jsonl",
-      model: "anthropic/claude",
       thinkingLevel: "high",
     });
     // --session <file>
@@ -251,7 +247,7 @@ describe("buildSpawnArgs", () => {
     // --model provider/id:level（thinkingLevel 作 model 后缀）
     const modelIdx = args.indexOf("--model");
     expect(modelIdx).toBeGreaterThan(-1);
-    expect(args[modelIdx + 1]).toBe("anthropic/claude:high");
+    expect(args[modelIdx + 1]).toBe("openai/gpt-4o:high");
   });
 });
 
@@ -332,6 +328,21 @@ describe("mirrorMainProcessFlags", () => {
     const r = mirrorMainProcessFlags(["bun", "/pi", "-e", "/a", "-e=/b", "-e", "/c"]);
     expect(r.extensionPaths).toEqual(["/a", "/b", "/c"]);
   });
+
+  // [MF-7a] flag 判定收窄为 startsWith("--")：单 - 开头的合法路径不被误判为 flag。
+  it("[MF-7a] - 开头的路径被当值镜像（不误判 flag）", () => {
+    const r = mirrorMainProcessFlags(["bun", "/pi", "--extension", "-weird-dir/ext.js"]);
+    expect(r.extensionPaths).toEqual(["-weird-dir/ext.js"]);
+  });
+
+  // [MF-7a] -- 开头的真 flag 仍正确跳过：--extension 后跟 --flag 时不吃值、不越界。
+  it("[MF-7a] --extension 后跟 -- 开头真 flag → 不吃值", () => {
+    const r = mirrorMainProcessFlags([
+      "bun", "/pi", "--extension", "--approve", "--extension", "/real.js",
+    ]);
+    expect(r.extensionPaths).toEqual(["/real.js"]);
+    expect(r.approve).toBe(true);
+  });
 });
 
 // ============================================================

package/src/execution/__tests__/start-sync-model-guard.test.ts

@@ -0,0 +1,150 @@
+// src/execution/__tests__/start-sync-model-guard.test.ts
+//
+// [U1 验收 3] start 同步期裁决：非全等 model 入参在 start 工具调用同步期 isError——
+// 无 spawn、无子 session、record 不落盘。
+//
+// 用真实 SubagentService（tmpdir + mock pi）走 execute 全链路，断言：
+//   1. execute 在 IDENTITY 解析（resolveModel 裁决）阶段 reject（问句式报错）；
+//   2. buildSpawnArgs 从未被调用（vi.mock spy 包装真实实现）——spawn 前置守卫的结构性证据；
+//   3. node:child_process.spawn 从未被调用——无子进程；
+//   4. pi.appendEntry 从未被调用——record 未创建（emitPendingRegister 未发生）。
+//
+// 放行路径（全等 → 裁决通过）由 model-ref.test.ts / model-resolver.test.ts 锁定，
+// 全链路放行的 spawn 行为由 run-spawn-* 契约测试覆盖。
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("node:child_process", async () => {
+  const actual = await import("node:child_process");
+  return {
+    ...actual,
+    spawn: vi.fn(() => {
+      throw new Error("spawn must not be called on sync-model rejection");
+    }),
+  };
+});
+
+// buildSpawnArgs 包装为 spy（保留真实实现）——「非全等拒单不触达 spawn 参数组装」的承重断言。
+vi.mock("../session-runner.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../session-runner.ts")>();
+  return { ...actual, buildSpawnArgs: vi.fn(actual.buildSpawnArgs) };
+});
+
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
+import { buildSpawnArgs } from "../session-runner.ts";
+import type { PiLike } from "../subagent-service.ts";
+import { SubagentService } from "../subagent-service.ts";
+
+const mockSpawn = vi.mocked(spawn);
+const mockBuildSpawnArgs = vi.mocked(buildSpawnArgs);
+
+// ── 工具 ──
+
+function makeModel(over: Partial<ModelInfo> = {}): ModelInfo {
+  return {
+    id: over.id ?? "GLM-5.3-Flash",
+    name: over.name ?? "GLM 5.3 Flash",
+    provider: over.provider ?? "zai-coding-cn",
+    reasoning: over.reasoning ?? false,
+    ...over,
+  };
+}
+
+/** registry 快照：真实形态（大小写混合 id），无孪生（P-A2 放行快照形态）。 */
+function makeRegistry(models: ModelInfo[]): ModelRegistryLike {
+  return {
+    getAvailable: () => models,
+    find: (provider, modelId) => models.find((m) => m.provider === provider && m.id === modelId),
+    hasConfiguredAuth: () => true,
+  };
+}
+
+function makePi(): PiLike {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  } as unknown as PiLike;
+}
+
+describe("start 同步期裁决（U1 验收 3：非全等 → isError 且无 spawn 无子 session）", () => {
+  let tmpDir: string;
+  let service: SubagentService;
+  let pi: PiLike;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sw-start-guard-"));
+    const modelService = new ModelConfigService({ agentDir: tmpDir, cwd: tmpDir });
+    modelService.initModel({
+      modelRegistry: makeRegistry([makeModel()]),
+      sessionId: "guard-session",
+    });
+    service = new SubagentService({ cwd: tmpDir, modelService });
+    pi = makePi();
+    service.initSession({ pi, sessionId: "guard-session" });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("小写变体入参 → execute 同步 reject（问句式报错），buildSpawnArgs/spawn/appendEntry 均未被调", async () => {
+    await expect(
+      service.execute({
+        task: "probe task",
+        slug: "guard",
+        model: "zai-coding-cn/glm-5.3-flash",
+      }),
+    ).rejects.toThrow(/is not a registry entry.*Did you mean one of these\?/s);
+
+    // spawn 链路零触达：参数组装（buildSpawnArgs）与进程创建（spawn）都未发生
+    expect(mockBuildSpawnArgs).not.toHaveBeenCalled();
+    expect(mockSpawn).not.toHaveBeenCalled();
+    // record 未创建（emitPendingRegister 未发生）→ 无子 session 前置状态
+    expect(pi.appendEntry).not.toHaveBeenCalled();
+  });
+
+  it("错误含 case variant 首位建议 + 继承指引（可直接重发的合法串）", async () => {
+    let msg = "";
+    try {
+      await service.execute({
+        task: "probe task",
+        slug: "guard",
+        model: "zai-coding-cn/glm-5.3-flash",
+      });
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toContain('zai-coding-cn/GLM-5.3-Flash   ← case variant of "glm-5.3-flash"');
+    expect(msg).toMatch(/Or omit the `model` param to inherit the main agent model\./);
+  });
+
+  it("全等入参通过裁决（reject 不发生，放行链路触达 spawn 参数组装）——守卫零误伤对照", async () => {
+    // 放行路径会进入 kickOffBackground（detached）；execute resolve 即视为裁决放行。
+    // spawn 本身由 FakeChild 缺失抛错收口——本断言只关心「越过了同步裁决」：
+    // execute 不 reject，且 buildSpawnArgs 已被调（或即将被调的 record 已创建）。
+    const promise = service.execute({
+      task: "probe task",
+      slug: "guard-exact",
+      model: "zai-coding-cn/GLM-5.3-Flash",
+    });
+    // 放行路径：裁决不抛（execute 最终可能因 mock 环境子进程收尾而 reject，
+    // 但错误不能是模型裁决错误）
+    try {
+      await promise;
+    } catch (e) {
+      expect((e as Error).message).not.toMatch(/is not a registry entry/);
+      expect((e as Error).message).not.toMatch(/ambiguous case variants/);
+    }
+    // 全等放行 → record 已创建（emitPendingRegister 发生）——与拒单路径形成对照
+    expect(pi.appendEntry).toHaveBeenCalled();
+  });
+});

package/src/execution/__tests__/startup-config-declaration.test.ts

@@ -0,0 +1,35 @@
+// src/execution/__tests__/startup-config-declaration.test.ts
+//
+// startupConfig 声明守护测试：断言 package.json `xyz-agent.startupConfig` 声明的
+// content 与代码 DEFAULT_CONFIG 常量深相等，防止两侧任一改动未同步（漂移）。
+// 机制：runtime 启动序列统一 ensure（extension-startup-config.ts），声明即首建内容。
+//
+// 运行：cd extensions/universal/subagent-workflow && npx vitest run src/execution/__tests__/startup-config-declaration.test.ts
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_CONFIG } from "../config.ts";
+
+/** package.json `xyz-agent.startupConfig` 声明条目的最小形状（守护断言用）。 */
+interface StartupConfigEntry {
+	path: string;
+	content: unknown;
+}
+
+const pkg = JSON.parse(
+	readFileSync(join(fileURLToPath(import.meta.url), "../../../../package.json"), "utf-8"),
+) as { "xyz-agent"?: { startupConfig?: StartupConfigEntry[] } };
+
+describe("startupConfig 声明守护", () => {
+	it("声明 content 与代码 DEFAULT_CONFIG 深相等", () => {
+		const entry = pkg["xyz-agent"]?.startupConfig?.find(
+			(e: StartupConfigEntry) => e.path === "subagents/config.json",
+		);
+		expect(entry).toBeDefined();
+		expect(entry?.content).toEqual(DEFAULT_CONFIG);
+	});
+});