@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/orchestration/__tests__/worker-exit-without-result.test.ts

@@ -0,0 +1,368 @@
+/**
+ * [F1] worker exit 无终态消息 → run failed（非悬挂）+ [SW-DATA-3] store.save 抛错不产生
+ * unhandledRejection 的 handler 级回归测试。
+ *
+ * F1 背景：execute() 返回不可克隆值（function/Symbol/循环引用）→ worker 侧 _safePost 吞掉
+ * DataCloneError → return 消息从未发出 → worker exit(0)。旧实现 handleWorkerExit 对
+ * code===0 no-op → run 永久 running、runAndWait 无限挂起。
+ *
+ * 修复语义（本文件锚定）：
+ * - exit(0) 且本 runtime 代际未收到 return/error 消息 → transition done,failed +
+ *   WORKER_EXITED_WITHOUT_RESULT_MSG 归因 + pending:unregister + onRunDone
+ * - exit(0) 但已收到终态消息（script-error 重试退避窗口）→ no-op（rebuild 即将发生）
+ * - handleWorkerMessage 的 return/error 分支必须标记 receivedTerminalMessage（判定的依据）
+ * - 非零 exit 行为不变（委托 handleWorkerError 重试矩阵）
+ *
+ * SW-DATA-3 背景：handleReturn / handleWorkerError / handleScriptError 的
+ * `await deps.store.save(run)` 未捕获——ENOSPC 等落盘失败时 rejection 经 worker-host 的
+ * `void handlers.onXxx(...)` 无人接 → unhandledRejection + pending:unregister / onRunDone
+ * 不执行（pending 通知幽灵注销）。修复后 save 失败仅 logger.error，状态机继续推进。
+ *
+ * mock 构建参考 error-recovery-handlers.test.ts（plain-object WorkflowRun mock）。
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  handleWorkerExit,
+  handleWorkerMessage,
+  handleScriptError,
+  handleWorkerError,
+} from "../error-recovery.ts";
+import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
+import type { WorkflowRun } from "../models/workflow-run.ts";
+import type { WorkerHandle } from "../worker-handle.ts";
+
+/** [F1] 归因文案——与 error-recovery.ts 常量一致（不直接 import 常量以锚定对外文案）。 */
+const EXITED_WITHOUT_RESULT_MSG =
+  "worker exited before delivering a result (return value may not be structured-cloneable)";
+
+// ── helpers（对齐 error-recovery-handlers.test.ts）─────────────────
+
+interface RunMockOpts {
+  workerErrorCount?: number;
+  scriptErrorCount?: number;
+  /** 预置 receivedTerminalMessage（模拟 return/error 消息已送达）。 */
+  receivedTerminalMessage?: boolean;
+}
+
+/** 构造一个 status="running" 的 mock WorkflowRun。 */
+function makeRunningRun(opts: RunMockOpts = {}): WorkflowRun {
+  return {
+    runId: "wf-test",
+    state: {
+      status: "running",
+      budget: { usedTokens: 0, usedCost: 0, isExceeded: () => false },
+      errorLogs: [],
+      calls: new Map(),
+      trace: { removeByStepIndex: vi.fn(), append: vi.fn(), update: vi.fn() },
+    },
+    meta: {
+      startedAt: new Date().toISOString(),
+      workerErrorCount: opts.workerErrorCount,
+      scriptErrorCount: opts.scriptErrorCount,
+    },
+    spec: {
+      scriptName: "test-wf",
+      scriptSource: "execute() {}",
+      args: {},
+    },
+    runtime: {
+      worker: { postMessage: vi.fn() },
+      receivedTerminalMessage: opts.receivedTerminalMessage,
+    },
+    transition(target: string, reason?: string): void {
+      this.state.status = target;
+      if (target === "done") this.state.reason = reason;
+    },
+    replaceRuntime(rt: unknown): void {
+      this.runtime = rt;
+    },
+  } as unknown as WorkflowRun;
+}
+
+/** LifecycleDeps mock：store/workerHost/eventBus/onRunDone 可观察。 */
+function makeDeps(): LifecycleDeps & {
+  store: { save: ReturnType<typeof vi.fn> };
+  eventBus: { emit: ReturnType<typeof vi.fn> };
+  onRunDone: ReturnType<typeof vi.fn>;
+} {
+  return {
+    store: { save: vi.fn(async () => {}) },
+    workerHost: { start: vi.fn(() => ({ postMessage: vi.fn() })) },
+    runner: { run: vi.fn(async () => ({})) },
+    runs: new Map(),
+    eventBus: { emit: vi.fn() },
+    onRunDone: vi.fn(),
+    log: vi.fn(),
+  } as unknown as ReturnType<typeof makeDeps>;
+}
+
+function makeHandlers(): WorkerHandlers {
+  return {
+    onMessage: vi.fn(async () => {}),
+    onError: vi.fn(async () => {}),
+    onExit: vi.fn(async () => {}),
+  } as unknown as WorkerHandlers;
+}
+
+function makeHandle(isCurrent = true): WorkerHandle {
+  return { isCurrent } as unknown as WorkerHandle;
+}
+
+// ── [F1] handleWorkerExit：exit(0) 无终态消息 → failed ──────────────
+
+describe("handleWorkerExit — [F1] exit(0) 无终态消息", () => {
+  it("exit(0) 且未收到 return/error → run 转 done,failed，归因 structured-cloneable，unregister + onRunDone", async () => {
+    const run = makeRunningRun();
+    const deps = makeDeps();
+
+    await handleWorkerExit(run, 0, makeHandle(), deps, makeHandlers());
+
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("failed");
+    expect(run.state.error).toBe(EXITED_WITHOUT_RESULT_MSG);
+    expect(deps.eventBus.emit).toHaveBeenCalledWith(
+      "pending:unregister",
+      expect.objectContaining({ id: "wf-test", reason: "failed" }),
+    );
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+    expect(deps.store.save).toHaveBeenCalledTimes(1);
+  });
+
+  it("exit(0) 但已收到终态消息（script-error 重试退避窗口）→ no-op，不被误判 failed", async () => {
+    const run = makeRunningRun({ receivedTerminalMessage: true });
+    const deps = makeDeps();
+
+    await handleWorkerExit(run, 0, makeHandle(), deps, makeHandlers());
+
+    expect(run.state.status).toBe("running");
+    expect(deps.store.save).not.toHaveBeenCalled();
+    expect(deps.eventBus.emit).not.toHaveBeenCalled();
+    expect(deps.onRunDone).not.toHaveBeenCalled();
+  });
+
+  it("stale handle（isCurrent=false）仍被丢弃——修复不破坏 G-025", async () => {
+    const run = makeRunningRun();
+    const deps = makeDeps();
+
+    await handleWorkerExit(run, 0, makeHandle(false), deps, makeHandlers());
+
+    expect(run.state.status).toBe("running");
+    expect(deps.onRunDone).not.toHaveBeenCalled();
+  });
+
+  it("已终态（done）的 run 不受影响", async () => {
+    const run = makeRunningRun();
+    run.transition("done", "completed");
+    const deps = makeDeps();
+
+    await handleWorkerExit(run, 0, makeHandle(), deps, makeHandlers());
+
+    expect(run.state.reason).toBe("completed");
+    expect(deps.onRunDone).not.toHaveBeenCalled();
+  });
+
+  it("非零 exit 行为不变：委托 handleWorkerError（未超限 → 退避后 rebuild 重试，不直接 failed）", async () => {
+    // fake timers 跳过 scheduleRebuild 的真实 1s 退避
+    vi.useFakeTimers();
+    try {
+      const run = makeRunningRun();
+      const deps = makeDeps();
+      const handlers = makeHandlers();
+
+      const pending = handleWorkerExit(run, 1, makeHandle(), deps, handlers);
+      await vi.advanceTimersByTimeAsync(1000); // 退避 1s → 触发 rebuildRuntime
+      await pending;
+
+      // 未超限 → rebuild（workerHost.start 重建），run 保持 running、不判 failed
+      expect(run.state.status).toBe("running");
+      expect(run.meta.workerErrorCount).toBe(1);
+      expect(deps.workerHost.start).toHaveBeenCalledTimes(1);
+      expect(deps.onRunDone).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+// ── [R4-F1] handleWorkerError：error + exit(1) 同代际双派发只计一次 ────
+
+describe("handleWorkerError — [R4-F1] 同代际双事件幂等", () => {
+  it("worker 崩溃：error 事件先到（退避窗口内）+ exit(1) 委托二次到达 → 只计一次、只 rebuild 一次", async () => {
+    // 真实时序：worker 崩溃 → onError 与 exit 几乎同时触发。handleWorkerError 进入
+    // scheduleRebuild 的退避 delay（未完成）时 exit(1) 到达 handleWorkerExit → 委托
+    // handleWorkerError 二次进入。旧实现在此处重复计数 + 第二个 scheduleRebuild
+    //（单次崩溃 workerErrorCount +2、双 rebuild 交错）。
+    vi.useFakeTimers();
+    try {
+      const run = makeRunningRun();
+      const deps = makeDeps();
+      const handlers = makeHandlers();
+
+      // 第一次：uncaught error 事件（进入退避 delay，不 await 完成）
+      const p1 = handleWorkerError(run, new Error("worker crashed"), deps, handlers);
+      // 第二次：exit(1) 在退避窗口内到达（runtime 尚未被 replace，同代际）
+      const p2 = handleWorkerExit(run, 1, makeHandle(), deps, handlers);
+      await vi.advanceTimersByTimeAsync(1000); // 跳过退避 → 第一个事件的 rebuild 执行
+      await Promise.all([p1, p2]);
+
+      // 双事件只处理一次：计数 +1（非 +2）、单次 rebuild、run 保持 running
+      expect(run.meta.workerErrorCount).toBe(1);
+      expect(deps.workerHost.start).toHaveBeenCalledTimes(1);
+      expect(run.state.status).toBe("running");
+      expect(deps.onRunDone).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("幂等守卫不误伤新代际：rebuild 后新 worker 的 error 正常处理（计数/重建各自 +1）", async () => {
+    vi.useFakeTimers();
+    try {
+      const run = makeRunningRun();
+      const deps = makeDeps();
+      const handlers = makeHandlers();
+
+      // 第一代：error → 标记本代际 → 退避 → rebuild（新 RunRuntime，标志重置 false）
+      const p1 = handleWorkerError(run, new Error("crash gen-1"), deps, handlers);
+      await vi.advanceTimersByTimeAsync(1000);
+      await p1;
+      expect(deps.workerHost.start).toHaveBeenCalledTimes(1);
+
+      // 新代际（rebuildRuntime 构造的真 RunRuntime 实例）标志为 false
+      expect((run.runtime as { receivedTerminalMessage?: boolean }).receivedTerminalMessage).toBe(false);
+
+      // 新代际再崩 → 正常走重试矩阵（计数 2、第二次 rebuild）
+      const p2 = handleWorkerError(run, new Error("crash gen-2"), deps, handlers);
+      // 第二次重试退避是指数值 backoffDelay(2) = 1000×2 = 2000ms，非 1000
+      await vi.advanceTimersByTimeAsync(2000);
+      await p2;
+
+      expect(run.meta.workerErrorCount).toBe(2);
+      expect(deps.workerHost.start).toHaveBeenCalledTimes(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("超限路径同样幂等：error + exit(1) 双到达只转一次 done,failed（onRunDone 只调一次）", async () => {
+    vi.useFakeTimers();
+    try {
+      // 预置 workerErrorCount = MAX（3）：本次 error 计数到 4 → 超限 → done,failed
+      const run = makeRunningRun({ workerErrorCount: 3 });
+      const deps = makeDeps();
+      const handlers = makeHandlers();
+
+      const p1 = handleWorkerError(run, new Error("worker crashed"), deps, handlers);
+      const p2 = handleWorkerExit(run, 1, makeHandle(), deps, handlers);
+      await Promise.all([p1, p2]);
+
+      expect(run.meta.workerErrorCount).toBe(4); // 只 +1
+      expect(run.state.status).toBe("done");
+      expect(run.state.reason).toBe("failed");
+      expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+      expect(deps.eventBus.emit).toHaveBeenCalledTimes(1); // 单次 unregister，无重复
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+// ── [F1] handleWorkerMessage：return/error 标记 receivedTerminalMessage ────
+
+describe("handleWorkerMessage — [F1] 终态消息标记", () => {
+  it("return 消息将 runtime.receivedTerminalMessage 置 true，随后正常 transition done,completed", async () => {
+    const run = makeRunningRun();
+    const deps = makeDeps();
+
+    await handleWorkerMessage(run, { type: "return", result: { ok: 1 } }, deps, makeHandlers());
+
+    expect((run.runtime as { receivedTerminalMessage?: boolean }).receivedTerminalMessage).toBe(true);
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("completed");
+  });
+
+  it("error 消息同样置 true——在 rebuild 前的退避窗口内捕获（replaceRuntime 前 start 时刻）", async () => {
+    // 断言时机说明：标记的生命周期是「本 runtime 代际」。await 整个 handleWorkerMessage
+    // 后 scheduleRebuild 已完成 replaceRuntime，runtime 已换新代际（flag=false 属正确语义）。
+    // 真正需要标记保护的窗口是退避期间（旧 worker exit(0) 到达、run.runtime 仍指向旧代际），
+    // 故在 rebuildRuntime 调 workerHost.start 的时刻（replaceRuntime 之前）捕获。
+    vi.useFakeTimers();
+    try {
+      const run = makeRunningRun();
+      const deps = makeDeps();
+      let flagAtRebuildStart: boolean | undefined;
+      (deps.workerHost.start as ReturnType<typeof vi.fn>).mockImplementation(() => {
+        flagAtRebuildStart = (run.runtime as { receivedTerminalMessage?: boolean }).receivedTerminalMessage;
+        return { postMessage: vi.fn() };
+      });
+
+      const pending = handleWorkerMessage(run, { type: "error", error: "boom" }, deps, makeHandlers());
+      await vi.advanceTimersByTimeAsync(1000); // 跳过 scheduleRebuild 真实 1s 退避
+      await pending;
+
+      expect(flagAtRebuildStart).toBe(true);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+// ── [SW-DATA-3] store.save 抛错 → 不产生 unhandledRejection，状态机继续 ────
+
+describe("store.save 抛错（ENOSPC 等）— [SW-DATA-3] 不阻断终态推进", () => {
+  it("handleReturn（经 handleWorkerMessage return 分支）：save reject 被吸收，unregister + onRunDone 照常", async () => {
+    const run = makeRunningRun();
+    const deps = makeDeps();
+    deps.store.save.mockRejectedValue(new Error("ENOSPC: no space left on device"));
+
+    // 旧实现：await 裸抛 → handleWorkerMessage reject（worker-host 侧 void 掉）→
+    // unhandledRejection + 幽灵注销。修复后必须正常 resolve。
+    await expect(
+      handleWorkerMessage(run, { type: "return", result: { ok: 1 } }, deps, makeHandlers()),
+    ).resolves.toBeUndefined();
+
+    expect(run.state.status).toBe("done");
+    expect(deps.eventBus.emit).toHaveBeenCalledWith(
+      "pending:unregister",
+      expect.objectContaining({ id: "wf-test" }),
+    );
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+  });
+
+  it("handleWorkerError 重试超限：save reject 被吸收，终态 + 通知照常", async () => {
+    const run = makeRunningRun({ workerErrorCount: 3 });
+    const deps = makeDeps();
+    deps.store.save.mockRejectedValue(new Error("ENOSPC: no space left on device"));
+
+    await expect(
+      handleWorkerError(run, new Error("worker crash"), deps, makeHandlers()),
+    ).resolves.toBeUndefined();
+
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("failed");
+    expect(deps.eventBus.emit).toHaveBeenCalledWith(
+      "pending:unregister",
+      expect.objectContaining({ id: "wf-test", reason: "failed" }),
+    );
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+  });
+
+  it("handleScriptError 重试超限：save reject 被吸收，终态 + 通知照常", async () => {
+    const run = makeRunningRun({ scriptErrorCount: 3 });
+    const deps = makeDeps();
+    deps.store.save.mockRejectedValue(new Error("ENOSPC: no space left on device"));
+
+    await expect(
+      handleScriptError(run, "script boom", [], deps, makeHandlers()),
+    ).resolves.toBeUndefined();
+
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("failed");
+    expect(deps.eventBus.emit).toHaveBeenCalledWith(
+      "pending:unregister",
+      expect.objectContaining({ id: "wf-test", reason: "failed" }),
+    );
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+  });
+});

package/src/orchestration/__tests__/worker-script-builder-runtime.test.ts

@@ -280,6 +280,28 @@ describe("buildWorkerScript runtime — _safePost scope regression (exit code 1
     expect(res.returnValue).toEqual({ count: 2, ok: true });
     expect(res.exitCode).not.toBe(1);
   });
+
+  it("[F1] execute() 返回不可克隆值 → 回发可克隆 error 消息（不再静默 exit(0)），DataCloneError 详情在 workerLogs", async () => {
+    // 修复前：return 值含 function → _safePost 吞掉 DataCloneError 返回 false → 无任何
+    // 消息发出 → worker 静默 exit(0) → 主线程 handleWorkerExit(0) no-op → run 永久
+    // running、runAndWait 悬挂（runWorker 会 2s 超时 reject，即本测试修复前会红）。
+    // 修复后：.then 检测 _safePost 失败，回发可克隆 error 消息接管。
+    const script = `return { ok: true, fn: () => 1 };`;
+    const res = await runWorker(script);
+    expect(res.workerError).toBeUndefined();
+    expect(res.returnValue).toBeUndefined(); // return 消息未发出（被 DataCloneError 拦下）
+    expect(res.errorMessage).toMatch(/structured-clone failed/);
+    // DataCloneError 详情由 _safePost 记入 workerLogs 随 error 消息带回（诊断不丢）
+    expect((res.errorWorkerLogs ?? []).length).toBeGreaterThan(0);
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("[F1] 不可克隆 Symbol 成员同样回发 error 消息（循环引用同理，同一 _safePost 失败路径）", async () => {
+    const script = `return { sym: Symbol("no-clone") };`;
+    const res = await runWorker(script);
+    expect(res.errorMessage).toMatch(/structured-clone failed/);
+    expect(res.exitCode).not.toBe(1);
+  });
 });
 
 // ── S4-S7：覆盖此前缺失的运行时路径 ──────────────────────────────────
@@ -518,3 +540,24 @@ describe("buildWorkerScript runtime — P3/P4 run-level model/thinkingLevel over
   });
 });
 
+describe("buildWorkerScript runtime — string 分支 maxTurns ?? 语义保真（F-2）", () => {
+  // 旧实现 `(cond && secondArg.maxTurns) || undefined` 把显式 0 抹成 undefined →
+  // 落 runSpawn 的 env 兑底（SPAWN_WATCHDOG env 设置时误挂 watchdog），与对象分支
+  // （直接透传保真）语义分裂。锁定运行时行为：string 分支传 0 → postMessage
+  // opts.maxTurns === 0。
+  it("agent(str, { maxTurns: 0 }) → postMessage opts.maxTurns === 0（不被抹成 undefined）", async () => {
+    const script = `await agent("p", { maxTurns: 0 }); return {};`;
+    const res = await runWorker(script);
+    expect(res.agentCalls).toHaveLength(1);
+    expect(res.agentCalls[0]!.opts.maxTurns).toBe(0);
+    expect(res.workerError).toBeUndefined();
+  });
+
+  it("agent(str, { maxTurns: 8 }) → 8；不传 → undefined（其余语义不变）", async () => {
+    const resA = await runWorker(`await agent("p", { maxTurns: 8 }); return {};`);
+    expect(resA.agentCalls[0]!.opts.maxTurns).toBe(8);
+    const resB = await runWorker(`await agent("p"); return {};`);
+    expect(resB.agentCalls[0]!.opts.maxTurns).toBeUndefined();
+  });
+});
+

package/src/orchestration/__tests__/worker-script-template-snapshot.test.ts

@@ -100,11 +100,30 @@ describe("buildWorkerScript — _KNOWN_FIELDS module scope 提升（IF6）", ()
     expect(agentBody).toContain("_KNOWN_FIELDS.has(k)");
   });
 
-  it("字段集合内容逐字段一致（16 known fields 不丢失）", () => {
+  it("字段集合内容逐字段一致（18 known fields 不丢失——P4 增 engine，预算语义对齐增 maxTurns）", () => {
     expect(script).toContain(
-      'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);',
+      'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "maxTurns", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel", "engine"]);',
     );
     // unknown-fields 警告文案不变（known 列表仍全量）
-    expect(script).toMatch(/Known fields:.*returnMeta.*thinkingLevel/);
+    expect(script).toMatch(/Known fields:.*returnMeta.*thinkingLevel.*engine/);
+  });
+
+  it("agent() 各分支均透传 maxTurns（预算语义对齐：脚本作者可显式传 turn 上限）", () => {
+    // task/agent shortcut 分支：显式转发
+    expect(script).toContain("maxTurns: firstArg.maxTurns,");
+    // string+secondArg 分支：显式转发（?? 语义保真：显式 0 不被抹成 undefined，F-2/U5）
+    expect(script).toContain(
+      'maxTurns: (secondArg && typeof secondArg === "object" ? secondArg.maxTurns : undefined) ?? undefined,',
+    );
+    // opts = firstArg 直传分支无需处理（整对象透传）
+  });
+
+  // [F-2 maxTurns:0 吞没修复] 旧字符串分支 `&& maxTurns) || undefined` 把显式 0
+  // 抹成 undefined → runSpawn 落 env 兑底（SPAWN_WATCHDOG env 设置时误挂 watchdog），
+  // 与对象分支保真语义分裂。锁定生成源为 ?? 形态（0/null/undefined 区分处理）。
+  it("string 分支 maxTurns 用 ?? 语义（显式 0 不抹成 undefined，F-2）", () => {
+    const out = buildWorkerScript("// noop");
+    expect(out).not.toContain('secondArg.maxTurns) || undefined');
+    expect(out).toContain("?? undefined");
   });
 });

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

@@ -28,6 +28,106 @@ export interface ResolveResult {
   error?: string;
 }
 
+// ── 根类型判定（与 structured-output 同源，本地副本） ──────────────
+
+/** plain object 判定（isPlainObject，与 @zhushanwen/pi-structured-output schema-guards.ts 同语义）。 */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * [U3 本地副本·同源锚定] 判定权威 schema 的根数据形态是否为 object。
+ *
+ * 与 @zhushanwen/pi-structured-output `src/execute.ts` 的 `isObjectRootSchema`
+ * 逐语义一致（该函数是 structured-output 工具 parameters {value} 包装/解包的唯一
+ * 判定源）。两包是独立 npm 包不能直接 import——optional peer 依赖在独立安装场景
+ * （pi 用户单独装本包）不保证存在，顶层值 import 会让整个 extension 加载崩溃；
+ * 且 builtin esbuild bundle 会把 import 的包内联成双实例（先例：session-runner.ts
+ * 的 PI_WORKFLOW_SCHEMA env 契约注释）。故本地复制，任一端改动判定逻辑必须同步
+ * 另一端（两端 docstring 互相锚定）。
+ *
+ * draft-07 语义：无 type 时类型关键字按值形态适用——properties/required 等
+ * object 特有关键字的存在意味着作者在描述 object 输出，算 object 根；组合根
+ * （anyOf/oneOf/allOf/$ref/enum）可能接受非 object 值，保真起见一律按非 object
+ * （{value} 包装可容纳任意成员类型）。
+ */
+function isObjectRootSchema(schema: unknown): schema is Record<string, unknown> {
+  if (!isPlainObject(schema)) return false;
+  if (schema.type === "object") return true;
+  if (Array.isArray(schema.type) && schema.type.includes("object")) return true;
+  const OBJECT_ONLY_KEYS = [
+    "properties",
+    "required",
+    "patternProperties",
+    "additionalProperties",
+    "minProperties",
+    "maxProperties",
+    "dependencies",
+    "dependentRequired",
+    "propertyNames",
+  ];
+  return OBJECT_ONLY_KEYS.some((k) => k in schema);
+}
+
+/**
+ * 构造 schema structured-output 指令——resolver 单点注入的唯一文案源。
+ *
+ * [审查项#2] 消费链：resolveAgentOpts → appendSystemPrompt（ASP 稳定前缀区）。
+ * 此前 session-runner 有一份措辞相近的同名函数并把指令拼进 task 末尾，形成
+ * ASP + task 双重静态注入；task 后缀已删（task 每 agent 变化不可缓存，工具
+ * parameters 是 pi 必然注入的权威展示——注册工具 schema 随每次请求下发进
+ * provider 请求体，机制登记 PS-21：pi-ai dist/api/anthropic-messages.js
+ * convertTools :1000/:1008 → :1017 input_schema、openai-completions.js :1099
+ * parameters——schema 全文不必在 task 重复，文本重复浪费 ~730 tokens/子进程）。
+ *
+ * [审查项#4] AP 告知：注入侧校验用 additionalProperties:false 收窄后的
+ * parameters，模型自带 schema 外字段会被拒——不前置告知，拒绝显得凭空。
+ *
+ * JSON 序列化用 compact（stringifySchemaCached），与 schemaEnv 复用同串（IF7 #13）。
+ */
+export function formatSchemaInstruction(schema: Record<string, unknown>): string {
+  const schemaJson = stringifySchemaCached(schema, "compact");
+  // [U3] 根类型条件化：判定与 structured-output 的工具 parameters {value} 包装/解包
+  // 同源（上方 isObjectRootSchema 本地副本）。object 根 arguments 即 data；非 object
+  // 根参数层实为 {value} 包装——ASP 文案必须与工具 description 同语汇告知包装契约
+  // （{value: <data>} + value. 错误路径前缀），否则模型直传裸值必首调失败。
+  const isObjectRoot = isObjectRootSchema(schema);
+  const argsContractLine = isObjectRoot
+    ? "Your call arguments ARE the result data itself — the tool's parameter schema IS the required shape of your result."
+    : "The tool's single argument must be an object `{value: <data>}` — put the result itself in `value`, and it must conform to the schema below. " +
+      "Validation errors may reference paths starting with `value.` (e.g. `value.0`, `value.name`): " +
+      "that prefix addresses the wrapper, not your data.";
+  const rulesCallLine = isObjectRoot
+    ? "- Call the structured-output tool with your result data as its arguments. The system validates them against the schema above automatically."
+    : "- Call the structured-output tool with `{value: <your result data>}`. The system validates the `value` field against the schema above automatically.";
+  // [AP 告知条件化] 根级 additionalProperties 未声明时 D4 注入 false（见
+  // structured-output tool-definition）——额外字段恒拒绝，强承诺成立；作者显式声明
+  // true / 子 schema 时 injection 侧尊重不动，额外字段按作者声明放行，无条件
+  // 「一律拒绝」文案与参数层行为不符（保守方向误导：模型不敢传合法字段）。
+  const apLine = schema.additionalProperties === undefined
+    ? "- Fields not defined in this schema are rejected — do not add extra fields."
+    : "- Extra fields follow this schema's own additionalProperties declaration.";
+  return [
+    "## MANDATORY: Structured Output Requirement",
+    "",
+    "This task requires structured output.",
+    "Your FINAL action must be calling the `structured-output` tool.",
+    "",
+    argsContractLine,
+    `Your result must conform to this schema:`,
+    "```json",
+    schemaJson,
+    "```",
+    "",
+    "Rules:",
+    rulesCallLine,
+    "- 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.",
+    apLine,
+  ].join("\n");
+}
+
 /**
  * Resolve skill and schema into appendSystemPrompt (content array) + skillPath + schemaEnv.
  *
@@ -60,31 +160,12 @@ export function resolveAgentOpts(opts: AgentCallOpts): ResolveResult {
  // 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)：同 schema 对象引用的 compact stringify 走 WeakMap 缓存
-    // （与 session-runner formatSchemaInstruction 的 pretty 版共享缓存条目）
-    const schemaJson = stringifySchemaCached(opts.schema, "compact");
-    const content = [
-      "## MANDATORY: Structured Output Requirement",
-      "",
-      "This task requires structured output.",
-      "Your FINAL action must be calling the `structured-output` tool.",
-      "",
-      "The schema is enforced by the system (PI_WORKFLOW_SCHEMA). You only pass `data` — do NOT pass a `schema` parameter.",
-      `Your \`data\` must conform to this schema:`,
-      "```json",
-      schemaJson,
-      "```",
-      "",
-      "Rules:",
-      "- Call structured-output with ONLY the `data` parameter. The system validates it 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.",
-    ].join("\n");
-    appendSystemPrompt.push(content);
+    // 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
-    opts = { ...opts, schemaEnv: schemaJson };
+    opts = { ...opts, schemaEnv: stringifySchemaCached(opts.schema, "compact") };
   }
 
   return {