@zhushanwen/pi-subagent-workflow 8.5.0 → 8.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.5.0",
+  "version": "8.6.0",
   "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.",
@@ -61,9 +61,9 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "yaml": "^2.9.0",
-    "@xyz-agent/session-delivery": "0.2.0",
-    "@zhushanwen/pi-extension-logger": "0.3.0",
     "@xyz-agent/extension-protocol": "0.7.0",
+    "@xyz-agent/session-delivery": "0.3.0",
+    "@zhushanwen/pi-extension-logger": "0.3.0",
     "@zhushanwen/pi-file-lock": "0.1.2"
   },
   "peerDependencies": {
@@ -71,8 +71,8 @@
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@earendil-works/pi-tui": "^0.84.1",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.4.0",
-    "@zhushanwen/pi-structured-output": "5.0.2"
+    "@zhushanwen/pi-pending-notifications": "0.5.0",
+    "@zhushanwen/pi-structured-output": "5.1.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -89,6 +89,7 @@
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:isolated": "env $(env | grep -o '^PI_SUBAGENT_[A-Z_]*' | sed 's/^/-u /' | tr '\n' ' ') vitest run"
   }
 }

package/src/execution/__tests__/bg-notify-render.test.ts

@@ -128,6 +128,79 @@ describe("renderBgNotifyMessage", () => {
     expect(comp!.render(80).join("\n")).toContain("cancelled");
   });
 
+  // ── U3 C-outcome：渲染器切读 outcome ──
+
+  it("[U3] details 携带 outcome='failed' → verb 为 failed + Error 行（直读一等字段）", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      { details: { status: "closed", outcome: "failed", agent: "w", id: "bg-4", error: "kaboom" } },
+      { expanded: false },
+      theme,
+    );
+    const joined = comp!.render(80).join("\n");
+    expect(joined).toContain("failed");
+    expect(joined).toContain("Error");
+    expect(joined).toContain("kaboom");
+  });
+
+  it("[U3] details 携带 outcome='completed' → verb 为 finished，结果行可见", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      { details: { status: "closed", outcome: "completed", agent: "w", id: "bg-5", result: "ok" } },
+      { expanded: false },
+      theme,
+    );
+    const joined = comp!.render(80).join("\n");
+    expect(joined).toContain("finished");
+    expect(joined).toContain("ok");
+  });
+
+  it("[U3] outcome 优先于 closedReason（一等字段胜出）", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      {
+        details: {
+          status: "closed", outcome: "cancelled", closedReason: "gc", agent: "w", id: "bg-6",
+        },
+      },
+      { expanded: false },
+      theme,
+    );
+    const joined = comp!.render(80).join("\n");
+    expect(joined).toContain("cancelled");
+  });
+
+  it("[U3] 升级前旧消息重放（details 无 outcome，仅 closedReason+error）→ deriveOutcome 兑底不崩溃", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      {
+        details: {
+          status: "closed", closedReason: "gc", error: "legacy boom", agent: "w", id: "bg-7",
+        },
+      },
+      { expanded: false },
+      theme,
+    );
+    const joined = comp!.render(80).join("\n");
+    expect(joined).toContain("failed");
+    expect(joined).toContain("legacy boom");
+  });
+
+  it("[U3] 非法 outcome 值按缺失处理（防御性收窄，不崩溃，兑底派生）", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      {
+        details: {
+          status: "closed", outcome: "bogus", closedReason: "gc", result: "fine", agent: "w", id: "bg-8",
+        },
+      },
+      { expanded: false },
+      theme,
+    );
+    const joined = comp!.render(80).join("\n");
+    expect(joined).toContain("finished");
+  });
+
   it("details 缺失/结构不全 → undefined（走 Pi 默认渲染兜底）", () => {
     const { theme } = makeTheme();
     expect(renderBgNotifyMessage({ details: undefined }, { expanded: false }, theme)).toBeUndefined();

package/src/execution/__tests__/chat-engine-routing.test.ts

@@ -176,10 +176,14 @@ const CTX_MODEL: ModelInfo = { id: "m", name: "M", provider: "p", reasoning: fal
 
 /** registry：可解析 "zcode/glm"（taskSpec 字段用例的显式 model），其余未配置。 */
 function fakeRegistry(): ModelRegistryLike {
+  // [U1] getAvailable 与 find 必须同源：assertCanonicalModelRef 以 getAvailable 为
+  // 全等/孪生扫描面（D1④ 孪生守卫需复扫 registry 全集）。旧 mock 只在 find 特判、
+  // getAvailable 返回空，与真实 registry 契约（find 可命中 ⇔ getAvailable 列出）不符。
+  const AVAILABLE: ModelInfo[] = [{ id: "glm", name: "GLM", provider: "zcode", reasoning: true }];
   return {
-    getAvailable: () => [],
+    getAvailable: () => AVAILABLE,
     find: (provider: string, id: string) =>
-      provider === "zcode" && id === "glm" ? { id: "glm", name: "GLM", provider: "zcode", reasoning: true } : undefined,
+      AVAILABLE.find((m) => m.provider === provider && m.id === id),
     hasConfiguredAuth: () => true,
   };
 }

package/src/execution/__tests__/delivery-methods.test.ts

@@ -96,7 +96,9 @@ function makeIdleRecord(id = "sa-chat"): ExecutionRecord {
 
 /** PassThrough child（可读出 stdin 字节验证 deliverToRunning 写入）。 */
 function makeStreamChild(): ChildProcess {
-  return { stdin: new PassThrough() } as unknown as ChildProcess;
+  // exitCode/signalCode：真 ChildProcess 未退出时均为 null（deliverMessage [race-F5]
+  // 写后死进程检测读这两个字段，缺省 undefined 会被误判为已死触发 warn）。
+  return { stdin: new PassThrough(), exitCode: null, signalCode: null } as unknown as ChildProcess;
 }
 
 function readStdinLines(child: ChildProcess): unknown[] {
@@ -232,6 +234,41 @@ describe("deliverMessage (V2 决策 3 chatMode 统一投递)", () => {
     expect(record.status).toBe("running");
   });
 
+  // [race-F5] 写后死进程检测：热路径 write 同步成功（数据进内核缓冲）但子进程在读取前
+  // 已死（gate/idle kill 竞速）→ 消息将随缓冲静默丢弃。修复：写后检查 exitCode/signalCode，
+  // 已死则 warn 留证（含 runId 与消息类型），不抛错不重试（终态已由 kill 路径保证）。
+  it("[race-F5] 热路径写后子进程已死 → logger.warn 被记录（含 runId 与消息类型），不抛错", () => {
+    const child = makeStreamChild();
+    // 模拟 gate/idle kill 竞速：写 stdin 成功但子进程已死（SIGTERM 终止形态）
+    Object.assign(child, { signalCode: "SIGTERM" });
+    spawnedChildren.set(record.id, child);
+
+    expect(() => service.deliverMessage(record, "lost msg", true)).not.toThrow();
+
+    // 写入照常发生（热路径语义不变，不做二次分发）
+    const lines = readStdinLines(child);
+    expect(lines[0]).toMatchObject({ type: "prompt", message: "lost msg", streamingBehavior: "steer" });
+    // warn 留证：含 runId（record.id）与消息类型（steer）
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining(`child ${record.id} died around stdin write`),
+      expect.objectContaining({ msgType: "steer", signalCode: "SIGTERM" }),
+    );
+  });
+
+  it("[race-F5] 活进程正常投递不触发死进程 warn（守卫不误报）", () => {
+    // loggerMock 是模块级共享 mock：清历史调用后再断言（防前一用例的 warn 干扰）
+    loggerMock.warn.mockClear();
+    const child = makeStreamChild();
+    spawnedChildren.set(record.id, child);
+
+    service.deliverMessage(record, "normal", false);
+
+    expect(loggerMock.warn).not.toHaveBeenCalledWith(
+      expect.stringContaining("died around stdin write"),
+      expect.anything(),
+    );
+  });
+
   it("热路径 disarm idle timer：arm 后 deliverMessage → timer 清除（防 turn 期间误杀）", () => {
     const child = makeStreamChild();
     spawnedChildren.set(record.id, child);

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

@@ -125,6 +125,17 @@ describe("mapToExecuteOptions (D-A2)", () => {
     const result = mapToExecuteOptions(baseOpts);
     expect(result.appendSystemPrompt).toBeUndefined();
   });
+
+  it("maxTurns 透传（预算语义对齐：workflow agent() 可显式传 turn 上限）", () => {
+    const opts: AgentCallOpts = { ...baseOpts, maxTurns: 20 };
+    const result = mapToExecuteOptions(opts);
+    expect(result.maxTurns).toBe(20);
+  });
+
+  it("maxTurns 不传 → undefined（不限 turn，不挂 turns 估算 watchdog）", () => {
+    const result = mapToExecuteOptions(baseOpts);
+    expect(result.maxTurns).toBeUndefined();
+  });
 });
 
 describe("mergeTimeoutSignal (D-A9)", () => {

package/src/execution/__tests__/execution-record.test.ts

@@ -14,6 +14,8 @@ import {
   getTotalUsage,
   markReconstructedStatus,
   nextRoundBaseTurnIndex,
+  deriveOutcome,
+  projectOutcome,
   project,
   projectLiveProgress,
   snapshot,
@@ -886,6 +888,106 @@ describe("completeRecord", () => {
     completeRecord(r, failedResult, "failed");
     expect(r.error).toBe("oops");
   });
+
+  // ── U3 C-outcome：completeRecord 唯一写入点冻结 outcome ──
+
+  it("[U3] 唯一写入点冻结 outcome：completed / failed / cancelled", () => {
+    const ok = makeRecord();
+    ok.status = "closed";
+    completeRecord(ok, SAMPLE_RESULT, "closed", "gc");
+    expect(ok.outcome).toBe("completed");
+    expect(ok.closedReason).toBe("gc");
+
+    const failed = makeRecord();
+    failed.status = "closed";
+    const failedResult: AgentResult = { ...SAMPLE_RESULT, success: false, error: "oops" };
+    completeRecord(failed, failedResult, "closed", "gc");
+    expect(failed.outcome).toBe("failed");
+
+    // 取消优先于 error（abort 合成 result 可能携带 error，取消语义优先）
+    const cancelled = makeRecord();
+    cancelled.status = "closed";
+    completeRecord(
+      cancelled,
+      { ...SAMPLE_RESULT, success: false, error: "aborted by user" },
+      "closed",
+      "cancelled",
+    );
+    expect(cancelled.outcome).toBe("cancelled");
+  });
+
+  it("[U3][D6 显式取舍] parent-shutdown 合成关闭（error='closed due to ...'）→ outcome 'failed'", () => {
+    // disposeAllRecords 合成 result 恒写 success:false + error:"closed due to ${reason}"
+    // ——语义为「父进程关闭时子 agent 未完成即失败」，选定行为而非疏漏。
+    const r = makeRecord();
+    r.status = "closed";
+    completeRecord(
+      r,
+      { ...SAMPLE_RESULT, success: false, error: "closed due to parent-shutdown" },
+      "closed",
+      "parent-shutdown",
+    );
+    expect(r.outcome).toBe("failed");
+  });
+
+  it("[U3] patchFile 语义不变：completeRecord 不触碰 patchFile/result，仅新增 outcome", () => {
+    const r = makeRecord({ patchFile: "/tmp/patches/sa-x.patch" });
+    r.status = "closed";
+    completeRecord(r, SAMPLE_RESULT, "closed", "gc");
+    expect(r.patchFile).toBe("/tmp/patches/sa-x.patch");
+    expect(r.result).toBe("done");
+    expect(r.outcome).toBe("completed");
+  });
+});
+
+// ============================================================
+// deriveOutcome / projectOutcome（U3 C-outcome 单一权威派生）
+// ============================================================
+describe("deriveOutcome（单一权威终态派生）", () => {
+  it("completed：closed + 无 error（gc / user-close 正常完成）", () => {
+    expect(deriveOutcome("gc", undefined)).toBe("completed");
+    expect(deriveOutcome("user-close", undefined)).toBe("completed");
+  });
+
+  it("failed：closed + error 非空（gc 失败）", () => {
+    expect(deriveOutcome("gc", "spawn EPIPE")).toBe("failed");
+  });
+
+  it("failed：parent-shutdown/parent-fork/parent-new 合成关闭（D6 显式取舍，勿改 cancelled）", () => {
+    expect(deriveOutcome("parent-shutdown", "closed due to parent-shutdown")).toBe("failed");
+    expect(deriveOutcome("parent-fork", "closed due to parent-fork")).toBe("failed");
+    expect(deriveOutcome("parent-new", "closed due to parent-new")).toBe("failed");
+  });
+
+  it("cancelled：取消优先于 error（abort 合成 result 可能带 error）", () => {
+    expect(deriveOutcome("cancelled", undefined)).toBe("cancelled");
+    expect(deriveOutcome("cancelled", "aborted by user")).toBe("cancelled");
+  });
+
+  it("空串 error 不构成 failed（与旧三处同构的 `record.error &&` truthy 判定逐字对齐）", () => {
+    expect(deriveOutcome("gc", "")).toBe("completed");
+  });
+});
+
+describe("projectOutcome（投影唯一出口）", () => {
+  it("running → undefined（终态语义不适用活跃态；即使误带 outcome 也拦截）", () => {
+    expect(projectOutcome({ status: "running" })).toBeUndefined();
+    expect(projectOutcome({ status: "running", outcome: "completed" })).toBeUndefined();
+  });
+
+  it("closed + 一等 outcome → 直读透传", () => {
+    expect(projectOutcome({ status: "closed", outcome: "failed" })).toBe("failed");
+    expect(projectOutcome({ status: "closed", outcome: "cancelled" })).toBe("cancelled");
+  });
+
+  it("closed + 无 outcome（存量/重建 record）→ deriveOutcome(closedReason, error) 兑底", () => {
+    expect(projectOutcome({ status: "closed", closedReason: "gc", error: "boom" })).toBe("failed");
+    expect(projectOutcome({ status: "closed", closedReason: "cancelled" })).toBe("cancelled");
+    expect(projectOutcome({ status: "closed", closedReason: "gc" })).toBe("completed");
+    // 连 closedReason/error 都缺失的最旧存量：兜底为 completed（与旧 closedReason??'gc'
+    // 兑底显示语义一致）
+    expect(projectOutcome({ status: "closed" })).toBe("completed");
+  });
 });
 
 // ============================================================
@@ -928,6 +1030,14 @@ describe("projections", () => {
       expect(d.sessionFile).toBe("bg-1-abc.jsonl");
     });
 
+    it("[U3] project 投影携带 outcome：一等字段直读 / 存量兑底 / running undefined", () => {
+      const done = makeRecord({ status: "closed", outcome: "completed", closedReason: "gc" });
+      expect(project(done).outcome).toBe("completed");
+      const legacy = makeRecord({ status: "closed", closedReason: "gc", error: "boom" });
+      expect(project(legacy).outcome).toBe("failed");
+      expect(project(makeRecord({ status: "running" })).outcome).toBeUndefined();
+    });
+
     it("sessionFile is undefined when record.sessionFile unset", () => {
       const r = makeRecord();
       expect(project(r).sessionFile).toBeUndefined();

package/src/execution/__tests__/explicit-agent-ref-guard.test.ts

@@ -0,0 +1,171 @@
+// 显式 agent ref 失败必须报错（非静默降级）——三通道对称审查修复的 agent 通道验收。
+//
+// 修复背景：resolveIdentity 旧实现 getAgentConfig（loadByPath 无 require）对相对
+// 路径/裸名/文件缺失一律返回 undefined → agentConfig undefined → resolveModel 静默
+// 回落 override→主 agent model——用户点名 agent 却拿到无 systemPrompt/无工具白名单
+// 的 general-purpose 形态，零反馈。修复后显式 ref 失败抛错（require:true 语义，
+// 错误含 <available_subagents> 恢复指引，对齐 workflow name not found 反馈风格）。
+//
+// 本文件锁住：
+//   1. 裸名/相对路径 agent ref → execute 同步 reject（Invalid agent ref），无 spawn、
+//      无子 session、record 不落盘（buildSpawnArgs/spawn/appendEntry 零触达）
+//   2. 绝对路径但文件不存在 → reject（not found or unreadable）
+//   3. 对照：不传 agent（默认 general-purpose）与合法绝对路径 ref 均不误伤
+//
+// harness 复用 start-sync-model-guard.test.ts（真实 SubagentService + tmpdir +
+// mock spawn），保证守卫位于同步裁决期、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 agent-ref rejection");
+    }),
+  };
+});
+
+// buildSpawnArgs 包装为 spy（保留真实实现）——「显式 ref 拒单不触达 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);
+
+// ── 工具（start-sync-model-guard 同款）──
+
+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,
+  };
+}
+
+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("显式 agent ref 失败报错（非静默降级 general-purpose）", () => {
+  let tmpDir: string;
+  let service: SubagentService;
+  let pi: PiLike;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sw-agent-ref-guard-"));
+    const modelService = new ModelConfigService({ agentDir: tmpDir, cwd: tmpDir });
+    modelService.initModel({
+      modelRegistry: makeRegistry([makeModel()]),
+      sessionId: "agent-ref-guard-session",
+    });
+    service = new SubagentService({ cwd: tmpDir, modelService });
+    pi = makePi();
+    service.initSession({ pi, sessionId: "agent-ref-guard-session" });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // ── 拒绝路径：显式 ref 失败 → 同步 reject + spawn 链路零触达 ──
+
+  it("裸名 agent ref（'worker'）→ execute 同步 reject（Invalid agent ref + 恢复指引）", async () => {
+    await expect(
+      service.execute({ task: "probe task", slug: "ref-guard", agent: "worker" }),
+    ).rejects.toThrow(/Invalid agent ref: worker.*<available_subagents>/s);
+
+    // spawn 链路零触达 + record 未创建——非静默降级的结构性证据：
+    // 旧行为（静默 undefined）会继续走 record 创建（appendEntry 被调）后启动子进程。
+    expect(mockBuildSpawnArgs).not.toHaveBeenCalled();
+    expect(mockSpawn).not.toHaveBeenCalled();
+    expect(pi.appendEntry).not.toHaveBeenCalled();
+  });
+
+  it("相对路径 agent ref → 同样 reject（引用唯一形态 = 绝对路径）", async () => {
+    await expect(
+      service.execute({ task: "probe task", slug: "ref-guard", agent: "./agents/worker.md" }),
+    ).rejects.toThrow(/Invalid agent ref/);
+
+    expect(mockBuildSpawnArgs).not.toHaveBeenCalled();
+    expect(pi.appendEntry).not.toHaveBeenCalled();
+  });
+
+  it("绝对路径但文件不存在 → reject（not found or unreadable），非静默降级", async () => {
+    const missing = path.join(tmpDir, "no-such-agent.md");
+    await expect(
+      service.execute({ task: "probe task", slug: "ref-guard", agent: missing }),
+    ).rejects.toThrow(/not found or unreadable.*<available_subagents>/s);
+
+    expect(mockBuildSpawnArgs).not.toHaveBeenCalled();
+    expect(mockSpawn).not.toHaveBeenCalled();
+    expect(pi.appendEntry).not.toHaveBeenCalled();
+  });
+
+  // ── 放行对照：两类合法语义不误伤 ──
+
+  it("不传 agent（默认 general-purpose 语义）→ 不触发 agent ref 守卫", async () => {
+    const promise = service.execute({
+      task: "probe task",
+      slug: "ref-default-ok",
+      ctxModel: makeModel(),
+    });
+    // 默认语义下 identity 解析必须放行（execute 可能因 mock 环境子进程收尾而 reject，
+    // 但错误不能是 agent ref 拒绝）；record 已创建（appendEntry 发生）。
+    try {
+      await promise;
+    } catch (e) {
+      expect((e as Error).message).not.toMatch(/Invalid agent ref/);
+      expect((e as Error).message).not.toMatch(/not found or unreadable/);
+    }
+    expect(pi.appendEntry).toHaveBeenCalled();
+  });
+
+  it("显式合法绝对路径 agent .md → 守卫零误伤，identity 放行", async () => {
+    const agentFile = path.join(tmpDir, "worker.md");
+    fs.writeFileSync(agentFile, "You are a test worker agent.");
+    const promise = service.execute({
+      task: "probe task",
+      slug: "ref-valid-ok",
+      agent: agentFile,
+      ctxModel: makeModel(),
+    });
+    try {
+      await promise;
+    } catch (e) {
+      expect((e as Error).message).not.toMatch(/Invalid agent ref/);
+      expect((e as Error).message).not.toMatch(/not found or unreadable/);
+    }
+    expect(pi.appendEntry).toHaveBeenCalled();
+  });
+});

package/src/execution/__tests__/format-schema-instruction.test.ts

@@ -1,14 +1,18 @@
-// src/__tests__/format-schema-instruction.test.ts
+// src/execution/__tests__/format-schema-instruction.test.ts
 //
 // 锁定 formatSchemaInstruction 契约：构造 schema enforcement 的 MANDATORY 指令。
-// 该字符串被拼入 task 末尾（runSpawn 的 fullTask = task + instruction），且 steer
-// reminder 复用同一文本。一旦漏掉 "MUST call structured-output" 关键词或 JSON
-// 序列化漂移，schema 模式会静默失效——agent 可能直接把 JSON 写进文本响应。
+// [审查项#2] 注入链变更：指令仅经 agent-opts-resolver 进 appendSystemPrompt
+// （ASP 单点），runSpawn 的 task + instruction 后缀拼接已删除——本测试随之改锁
+// resolver 导出的同名函数。一旦漏掉 "structured-output" 关键词或 JSON 序列化漂移，
+// schema 模式会静默失效——agent 可能直接把 JSON 写进文本响应。
+//
+// [审查项#4] 锁定 AP 告知句：注入侧校验用 additionalProperties:false 收窄后的
+// parameters，指令必须前置告知「schema 外字段被拒」，否则拒绝显得凭空。
 //
 // 纯函数测试：不依赖 Pi 运行时、不 spawn 进程、不 mock。只 import 被测函数。
 import { describe, expect, it } from "vitest";
 
-import { formatSchemaInstruction } from "../session-runner.ts";
+import { formatSchemaInstruction } from "../../orchestration/agent-opts-resolver.ts";
 
 describe("formatSchemaInstruction", () => {
   // ── 指令文本契约 ──────────────────────────────────────────────
@@ -21,49 +25,78 @@ describe("formatSchemaInstruction", () => {
   it("emits a MANDATORY structured-output directive (not free-form JSON)", () => {
     const out = formatSchemaInstruction({ type: "object" });
     expect(out).toContain("MANDATORY");
-    expect(out).toContain("MUST");
-    expect(out).toContain("MUST call the `structured-output` tool");
-    expect(out).toContain("Do NOT output the JSON directly");
+    expect(out).toContain("must be calling the `structured-output` tool");
+    expect(out).toContain("Do NOT output JSON in your text response");
   });
 
-  // ── schema 序列化 ─────────────────────────────────────────────
+  it("announces that fields outside the schema are rejected (AP 告知，审查项#4)", () => {
+    const out = formatSchemaInstruction({ type: "object" });
+    expect(out).toContain("Fields not defined in this schema are rejected");
+    expect(out).toContain("do not add extra fields");
+  });
+
+  it("author-declared additionalProperties → weak wording (AP 条件化：声明时作者 schema 管辖额外字段)", () => {
+    // D4 只在「未声明」时注入 false；作者显式声明 true 时额外字段实际放行——
+    // 无条件「一律拒绝」强承诺与参数层行为不符，改用弱承诺措辞。
+    const out = formatSchemaInstruction({ type: "object", additionalProperties: true });
+    expect(out).not.toContain("Fields not defined in this schema are rejected");
+    expect(out).toContain("follow this schema's own additionalProperties declaration");
+  });
 
-  it("embeds the schema as pretty-printed JSON (indent=2) inside a fenced block", () => {
+  // ── schema 序列化（compact：与 schemaEnv 复用同串，IF7 #13）───────
+
+  it("embeds the schema as compact JSON inside a fenced block", () => {
     const schema: Record<string, unknown> = {
       type: "object",
       properties: { name: { type: "string" } },
     };
     const out = formatSchemaInstruction(schema);
-    // 必须包含 JSON.stringify(schema, null, 2) 的完整结果
-    expect(out).toContain(JSON.stringify(schema, null, 2));
+    // 必须包含 JSON.stringify(schema) 的完整结果（compact，无缩进）
+    expect(out).toContain(JSON.stringify(schema));
     expect(out).toContain("```json");
     expect(out).toContain("```");
-    // indent=2 的可观察证据：属性键前有恰好两个空格（object 第一层缩进）
-    expect(out).toContain('\n  "type": "object"');
   });
 
   it("locks the full output structure for a minimal schema", () => {
     const out = formatSchemaInstruction({ type: "object" });
-    // 完整结构快照——任何指令措辞/顺序/缩进漂移都会被捕获。
-    // 注意第三行末尾的 em-dash（—），防止有人把它替换成普通连字符。
-    // [HISTORICAL] 方案 A 后文案更新：告知 LLM schema 由系统注入，只需传 data。
+    // 完整结构快照——任何指令措辞/顺序/序列化漂移都会被捕获。
+    // [HISTORICAL] runner task 后缀双重注入删除后，本函数迁至 resolver 成为唯一
+    // 文案源；JSON 从 pretty（indent=2）改为 compact（与 schemaEnv 同串复用）。
     expect(out).toBe(
       [
-        "MANDATORY: Structured Output Requirement",
-        "You MUST call the `structured-output` tool with your final answer.",
-        "Do NOT output the JSON directly in your text response — you MUST use the structured-output tool.",
-        "The schema is enforced by the system — call structured-output with ONLY the `data` parameter.",
-        "Do NOT pass a `schema` parameter; the system validates `data` against the authoritative schema automatically.",
-        "The schema for your `data` is:",
+        "## MANDATORY: Structured Output Requirement",
+        "",
+        "This task requires structured output.",
+        "Your FINAL action must be calling the `structured-output` tool.",
+        "",
+        "Your call arguments ARE the result data itself — the tool's parameter schema IS the required shape of your result.",
+        "Your result must conform to this schema:",
         "```json",
-        '{',
-        '  "type": "object"',
-        '}',
+        '{"type":"object"}',
         "```",
+        "",
+        "Rules:",
+        "- Call the structured-output tool with your result data as its arguments. The system validates them against the schema above automatically.",
+        "- Do NOT output JSON in your text response — use the structured-output tool.",
+        "- Do NOT skip this step. The structured-output call IS your result.",
+        "- Complete all other work FIRST, then call structured-output as the last action.",
+        "- Fields not defined in this schema are rejected — do not add extra fields.",
       ].join("\n"),
     );
   });
 
+  it("locks the single-parameter wording: arguments ARE the data coexists with the mandatory tool call", () => {
+    const out = formatSchemaInstruction({ type: "object" });
+    // 新口径双支柱必须共存：① 参数即数据（arguments ARE the data）② 必须调用工具
+    expect(out).toContain("arguments ARE the result data itself");
+    expect(out).toContain("parameter schema IS the required shape of your result");
+    expect(out).toContain("must be calling the `structured-output` tool");
+    // 旧双参数警告语义不得回流（工具已是单参数形态，警告失去对象）
+    expect(out).not.toMatch(/do NOT pass a .schema. parameter/i);
+    expect(out).not.toContain("ONLY the `data` parameter");
+    expect(out).not.toContain("enforced by the system");
+  });
+
   // ── 特殊字符转义（注入风险路径）──────────────────────────────
 
   it("escapes double quotes inside schema string values", () => {
@@ -102,8 +135,9 @@ describe("formatSchemaInstruction", () => {
   it("preserves null values in schema", () => {
     const schema: Record<string, unknown> = { default: null };
     const out = formatSchemaInstruction(schema);
-    // JSON.stringify 对 null 保留字面 "null"（不会 omit 键，也不会变字符串）
-    expect(out).toContain('"default": null');
+    // JSON.stringify 对 null 保留字面 "null"（不会 omit 键，也不会变字符串）。
+    // compact 序列化无空格：'"default":null'
+    expect(out).toContain('"default":null');
   });
 
   it("serializes nested objects and arrays", () => {
@@ -116,10 +150,7 @@ describe("formatSchemaInstruction", () => {
       },
     };
     const out = formatSchemaInstruction(schema);
-    expect(out).toContain(JSON.stringify(schema, null, 2));
-    // 嵌套结构 indent 正确（第二层 4 空格）
-    expect(out).toContain('    "name": {');
-    expect(out).toContain('      "type": "string"');
+    expect(out).toContain(JSON.stringify(schema));
   });
 
   // ── 确定性 ────────────────────────────────────────────────────