@zhushanwen/pi-plan 0.5.2 → 1.1.0

package/src/__tests__/index.test.ts

@@ -1,31 +1,25 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-// index.ts 只做装配：mock 掉子模块注册函数，只捕获 pi.on 的 hook 与 controllers 注册表
+// index.ts 只做装配：mock 掉子模块注册函数，只捕获 pi.on 的 hook 与 planCtx 注册表
 vi.mock("../tool.js", () => ({
   registerPlanTool: vi.fn(
-    (_pi: unknown, _sessions: unknown, controllers: Map<string, AbortController>) => {
-      captured.controllers = controllers;
+    (_pi: unknown, planCtx: { controllers: Map<string, AbortController> }) => {
+      captured.planCtx = planCtx;
     },
   ),
-  PLAN_MODE_TOOLS: ["read", "bash", "grep", "find", "ls", "plan"],
+  PLAN_MODE_TOOLS: ["read", "bash", "grep", "find", "ls", "plan", "ask_user"],
+  // E3 宿主分流（F-W3-1）依赖：与 tool.ts 实装同源的一行 env 读（受 vi.stubEnv 控制）
+  isTaijiHost: () => process.env.TAIJI_AGENT_EXT_LOG === "1",
 }));
 vi.mock("../command.js", () => ({ registerPlanCommand: vi.fn() }));
-vi.mock("../compact.js", () => ({ registerPlanEventHandlers: vi.fn() }));
 vi.mock("../widget.js", () => ({ updatePlanWidget: vi.fn() }));
 
-// MF-1-8：注入失败日志必须走 extension-logger（stderr 仅 logger 自身抛错的内层兜底）——
-// 捕获 warn spy 断言落盘通道
-const { loggerWarn } = vi.hoisted(() => ({ loggerWarn: vi.fn() }));
-vi.mock("@zhushanwen/pi-extension-logger", () => ({
-  getLogger: () => ({ warn: loggerWarn, error: vi.fn() }),
-}));
-
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import planExtension from "../index.js";
 import { PLAN_CONTEXT_CUSTOM_TYPE } from "../state.js";
 
-const captured: { controllers?: Map<string, AbortController> } = {};
+const captured: { planCtx?: { controllers: Map<string, AbortController> } } = {};
 
 type Handler = (event: unknown, ctx: ExtensionContext) => Promise<unknown> | unknown;
 
@@ -44,10 +38,12 @@ function setup() {
   return { handlers, pi };
 }
 
-function makeCtx(entries: unknown[]): ExtensionContext {
+function makeCtx(entries: unknown[], mode?: string): ExtensionContext {
   return {
+    mode,
     sessionManager: {
       getSessionId: () => "test-session",
+      getLeafId: () => null,
       getEntries: () => entries,
     },
     ui: { setWidget: vi.fn(), setStatus: vi.fn(), theme: { fg: (_t: string, text: string) => text } },
@@ -60,7 +56,7 @@ function planStateEntry(data: Record<string, unknown>) {
 
 beforeEach(() => {
   vi.clearAllMocks();
-  captured.controllers = undefined;
+  captured.planCtx = undefined;
   vi.stubEnv("TAIJI_AGENT_EXT_LOG", "");
 });
 
@@ -68,8 +64,8 @@ afterEach(() => {
   vi.unstubAllEnvs();
 });
 
-describe("session_start hook（E3：awaiting 重挂提醒）", () => {
-  it("awaiting + no live select → steers the agent to re-call submit-review (pi 懒重生之后跑)", async () => {
+describe("session_start hook（E3：按 state 查表恢复）", () => {
+  it("reviewing + no live select → steers the agent to re-call submit-review with 上轮 selfReview 全文（D9④）", async () => {
     const { handlers, pi } = setup();
     const ctx = makeCtx([
       planStateEntry({
@@ -79,13 +75,14 @@ describe("session_start hook（E3：awaiting 重挂提醒）", () => {
         templateName: "",
         skills: ["tech-design"],
         docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "tech-design", version: 1 }],
-        reviewState: "awaiting",
+        state: "reviewing",
+        selfReview: "3 requirements covered; 2 assumptions verified.",
       }),
     ]);
 
     await handlers.get("session_start")!({ type: "session_start" }, ctx);
 
-    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
+    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan", "ask_user"]);
     // custom message 三要素 + streaming steer options 断言（A6）
     expect(pi.sendMessage).toHaveBeenCalledWith(
       {
@@ -95,11 +92,104 @@ describe("session_start hook（E3：awaiting 重挂提醒）", () => {
       },
       { deliverAs: "steer", triggerTurn: true },
     );
-    // E3 重挂即落盘（§3.4 降级两源：该处曾只发 steer 不落盘——不落盘则 renderer 冷启动
-    // 扫描的 View 恒无 source、恒渲染通用文案）
+    // D9④：steer 携带上轮 selfReview 全文 + 原样回传指令（豁免只在「自审内容」，过门义务不豁免）
+    const steerContent = (pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0].content as string;
+    expect(steerContent).toContain("3 requirements covered; 2 assumptions verified.");
+    expect(steerContent).toContain("VERBATIM");
+    expect(steerContent).toContain("selfReview");
+    // E3 重挂即落盘（§3.4 降级两源）：resumeHint='resubmit'（旧 reviewStateSource 语义取代）
+    expect(pi.appendEntry).toHaveBeenCalledWith(
+      "plan-state",
+      expect.objectContaining({ isActive: true, state: "reviewing", resumeHint: "resubmit" }),
+    );
+  });
+
+  it("旧 entry（reviewState='awaiting' 无 state 字段）经映射同样落 reviewing 重挂分支（D2 读方①）", async () => {
+    const { handlers, pi } = setup();
+    const ctx = makeCtx([
+      planStateEntry({
+        isActive: true,
+        planFilePath: "/p/plan.md",
+        requirement: "r",
+        templateName: "",
+        skills: [],
+        docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "", version: 1 }],
+        reviewState: "awaiting",
+      }),
+    ]);
+
+    await handlers.get("session_start")!({ type: "session_start" }, ctx);
+
+    expect(pi.sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ content: expect.stringContaining("submit-review") }),
+      expect.anything(),
+    );
+    expect(pi.appendEntry).toHaveBeenCalledWith(
+      "plan-state",
+      expect.objectContaining({ state: "reviewing", resumeHint: "resubmit" }),
+    );
+  });
+
+  it("taiji GUI 宿主（signal=1 + mode=rpc）reviewing → 不自动 steer 重挂（F-W3-1 审批条复活拦截），只落 resumeHint 交 degraded 按钮恢复", async () => {
+    vi.stubEnv("TAIJI_AGENT_EXT_LOG", "1");
+    const { handlers, pi } = setup();
+    const ctx = makeCtx(
+      [
+        planStateEntry({
+          isActive: true,
+          planFilePath: "/p/plan.md",
+          requirement: "r",
+          templateName: "",
+          skills: [],
+          docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "", version: 1 }],
+          state: "reviewing",
+          selfReview: "carried conclusions",
+        }),
+      ],
+      "rpc",
+    );
+
+    await handlers.get("session_start")!({ type: "session_start" }, ctx);
+
+    // 审批条不自动复活：E3 不得无人值守重提审批（steer triggerTurn = 自动重提通道）
+    expect(pi.sendMessage).not.toHaveBeenCalled();
+    // 工具集收拢照常（E3 的非交互恢复职责保留）
+    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan", "ask_user"]);
+    // resumeHint 落盘：renderer degraded 分支（reviewing ∧ 无挂起）据此呈现
+    // 「审批提问已随会话重启失效 + 重新提交审批」按钮——恢复触发权归用户
+    expect(pi.appendEntry).toHaveBeenCalledWith(
+      "plan-state",
+      expect.objectContaining({ isActive: true, state: "reviewing", resumeHint: "resubmit" }),
+    );
+  });
+
+  it("taiji 宿主 env 泄漏到非 rpc 形态（signal=1 + mode=tui）→ steer 照旧（与 executeSubmitReview 的 E8 分流对齐）", async () => {
+    vi.stubEnv("TAIJI_AGENT_EXT_LOG", "1");
+    const { handlers, pi } = setup();
+    const ctx = makeCtx(
+      [
+        planStateEntry({
+          isActive: true,
+          planFilePath: "/p/plan.md",
+          requirement: "r",
+          templateName: "",
+          skills: [],
+          docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "", version: 1 }],
+          state: "reviewing",
+        }),
+      ],
+      "tui",
+    );
+
+    await handlers.get("session_start")!({ type: "session_start" }, ctx);
+
+    expect(pi.sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ content: expect.stringContaining("submit-review") }),
+      { deliverAs: "steer", triggerTurn: true },
+    );
     expect(pi.appendEntry).toHaveBeenCalledWith(
       "plan-state",
-      expect.objectContaining({ isActive: true, reviewState: "awaiting", reviewStateSource: "resubmit" }),
+      expect.objectContaining({ state: "reviewing", resumeHint: "resubmit" }),
     );
   });
 
@@ -113,13 +203,13 @@ describe("session_start hook（E3：awaiting 重挂提醒）", () => {
         templateName: "",
         skills: ["tech-design"],
         docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "tech-design", version: 1 }],
-        reviewState: "revising",
+        state: "revising",
       }),
     ]);
 
     await handlers.get("session_start")!({ type: "session_start" }, ctx);
 
-    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
+    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan", "ask_user"]);
     expect(pi.sendMessage).toHaveBeenCalledWith(
       {
         customType: PLAN_CONTEXT_CUSTOM_TYPE,
@@ -128,24 +218,56 @@ describe("session_start hook（E3：awaiting 重挂提醒）", () => {
       },
       { deliverAs: "steer", triggerTurn: true },
     );
-    // revising 恢复不落 source 标记（'resubmit' 只描述 awaiting 降级等待；revising 由
+    // revising 恢复不落 resumeHint（'resubmit' 只描述 reviewing 降级等待；revising 由
     // steer triggerTurn 立即开轮接续，恢复期间显示的 revising 是真实进行中）
     expect(pi.appendEntry).not.toHaveBeenCalled();
   });
 
+  it("dispatching + no live select → review_aborted 边落 approved + steer 重调 complete（D5 E3 新支）", async () => {
+    const { handlers, pi } = setup();
+    const ctx = makeCtx([
+      planStateEntry({
+        isActive: true,
+        planFilePath: "/p/plan.md",
+        requirement: "r",
+        templateName: "",
+        skills: [],
+        docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "", version: 1 }],
+        state: "dispatching",
+      }),
+    ]);
+
+    await handlers.get("session_start")!({ type: "session_start" }, ctx);
+
+    // 崩溃消散的表单 = 无选择解散极端形态：dispatching --review_aborted--> approved 落盘
+    //（批准事实保留，且使重调 complete 的 approve 边合法）
+    expect(pi.appendEntry).toHaveBeenCalledWith(
+      "plan-state",
+      expect.objectContaining({ state: "approved", isActive: true }),
+    );
+    expect(pi.sendMessage).toHaveBeenCalledWith(
+      {
+        customType: PLAN_CONTEXT_CUSTOM_TYPE,
+        content: expect.stringContaining("plan(action='complete')"),
+        display: false,
+      },
+      { deliverAs: "steer", triggerTurn: true },
+    );
+  });
+
   it("stale controllers are cleared on session rebuild (禁复用已 abort 的 controller)", async () => {
     const { handlers } = setup();
     const ctx = makeCtx([]);
     // 同进程 reload 场景：注册表里残留旧 controller——hook 重建 session 时必须清掉
     // （残留的已 abort controller 禁止复用：发起新挂起 select 会 fresh 新建，此处是防御清理）
-    captured.controllers!.set("test-session", new AbortController());
+    captured.planCtx!.controllers.set("test-session", new AbortController());
 
     await handlers.get("session_start")!({ type: "session_start" }, ctx);
 
-    expect(captured.controllers!.has("test-session")).toBe(false);
+    expect(captured.planCtx!.controllers.has("test-session")).toBe(false);
   });
 
-  it("active without awaiting (in progress) → no reminder", async () => {
+  it("active without pending review (in progress) → no reminder", async () => {
     const { handlers, pi } = setup();
     const ctx = makeCtx([
       planStateEntry({
@@ -162,67 +284,45 @@ describe("session_start hook（E3：awaiting 重挂提醒）", () => {
 
     expect(pi.setActiveTools).toHaveBeenCalled();
     expect(pi.sendMessage).not.toHaveBeenCalled();
-    // 非 awaiting 不落盘：E3 source 标记只在 awaiting 重挂分支写
+    // 非 reviewing/dispatching 不落盘：E3 resumeHint 只在 reviewing 重挂分支写
     expect(pi.appendEntry).not.toHaveBeenCalled();
   });
 
-  it("inactive plan → no reminder, no tool restriction", async () => {
+  it("approved（later 后重开）不打扰：无 E3 重挂（S16「重开 session 无 E3 重挂打扰」）", async () => {
     const { handlers, pi } = setup();
-    const ctx = makeCtx([]);
+    const ctx = makeCtx([
+      planStateEntry({
+        isActive: true,
+        planFilePath: "/p/plan.md",
+        requirement: "r",
+        templateName: "",
+        skills: [],
+        docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "", version: 1 }],
+        state: "approved",
+      }),
+    ]);
 
     await handlers.get("session_start")!({ type: "session_start" }, ctx);
 
-    expect(pi.setActiveTools).not.toHaveBeenCalled();
+    expect(pi.setActiveTools).toHaveBeenCalled();
     expect(pi.sendMessage).not.toHaveBeenCalled();
+    expect(pi.appendEntry).not.toHaveBeenCalled();
   });
-});
 
-describe("before_agent_start hook（D9：taiji 形态引导注入）", () => {
-  const basePrompt = "You are a helpful coding agent.";
+  it("inactive plan → no reminder, no tool restriction", async () => {
+    const { handlers, pi } = setup();
+    const ctx = makeCtx([]);
 
-  it("no host signal (standalone pi) → undefined, prompt untouched", () => {
-    const { handlers } = setup();
-    const result = handlers.get("before_agent_start")!(
-      { type: "before_agent_start", prompt: "hi", systemPrompt: basePrompt },
-      makeCtx([]),
-    );
-    expect(result).toBeUndefined();
-  });
+    await handlers.get("session_start")!({ type: "session_start" }, ctx);
 
-  it("TAIJI_AGENT_EXT_LOG=1 → appends the plan-mode suggestion (not TAIJI_RUNTIME_TOKEN — 出站 deny list 剥除)", () => {
-    vi.stubEnv("TAIJI_AGENT_EXT_LOG", "1");
-    const { handlers } = setup();
-    const result = handlers.get("before_agent_start")!(
-      { type: "before_agent_start", prompt: "hi", systemPrompt: basePrompt },
-      makeCtx([]),
-    ) as { systemPrompt?: string } | undefined;
-
-    expect(result?.systemPrompt).toContain(basePrompt);
-    // agent 自助进入引导在场（enter action + 无需确认）
-    expect(result?.systemPrompt).toContain("plan(action='enter'");
-    expect(result?.systemPrompt).toContain("Do not ask for permission to enter");
-    // 旧的「建议 + 需确认」措辞已移除（enter 是 tool action，无需确认闸门）
-    expect(result?.systemPrompt).not.toContain("Do NOT enter plan mode without the user's confirmation");
+    expect(pi.setActiveTools).not.toHaveBeenCalled();
+    expect(pi.sendMessage).not.toHaveBeenCalled();
   });
+});
 
-  it("注入失败（systemPrompt 读取抛错）→ logger.warn 落盘 + 返回 undefined，不阻塞 agent loop（MF-1-8）", () => {
-    vi.stubEnv("TAIJI_AGENT_EXT_LOG", "1");
+describe("进入引导单源（systemPrompt 注入面已收敛到 tool promptSnippet）", () => {
+  it("before_agent_start 钩子不注册：taiji 宿主注入面与 tool 描述面不再同时含进入引导（C1 行为变更组锚）", () => {
     const { handlers } = setup();
-    const evilEvent = {
-      type: "before_agent_start",
-      get systemPrompt(): string {
-        throw new Error("boom");
-      },
-    };
-
-    const result = handlers.get("before_agent_start")!(evilEvent, makeCtx([]));
-
-    // Never block the agent loop：吞错返回 undefined
-    expect(result).toBeUndefined();
-    // 日志走 extension-logger 文件通道（~/.pi/agent/logs/），不再 stderr 直写
-    expect(loggerWarn).toHaveBeenCalledWith(
-      "plan: before_agent_start injection failed",
-      expect.objectContaining({ error: expect.stringContaining("boom") }),
-    );
+    expect(handlers.has("before_agent_start")).toBe(false);
   });
 });

package/src/__tests__/prompts.test.ts

@@ -72,3 +72,69 @@ describe("注入段项目级模板源锚点 = PlanPromptInput.projectRoot（ctx.
     expect(prompt).not.toContain(`<location>${join(trapDir, `${trapName}.md`)}</location>`);
   });
 });
+
+describe("Phase D 段注入 buildPlanModePrompt（对齐测试的装配面锚）", () => {
+  it("Phase D 段的两个注入分支（模板流程 / --template 直传）都携带该段（若装配漏注入，exec-options-alignment 的散文锚测不到）", () => {
+    const projectRoot = mkTmpDir("plan-prompt-phased-");
+    const base = {
+      requirement: "add dark mode",
+      planFilePath: join(projectRoot, ".tmp", "plans", "add-dark-mode", "plan.md"),
+      projectRoot,
+      skills: [],
+    };
+
+    // 分支一：无 --skills 的模板流程（prompts.ts else-if 注入腿）
+    const templateFlow = buildPlanModePrompt(base);
+    expect(templateFlow).toContain("Phase D: Completion");
+    expect(templateFlow).toContain("picks an execution method in the completion dialog");
+
+    // 分支二：--template 直传变体（prompts.ts if 注入腿；技能流程分支无 Phase D 属设计现状，不锚定）
+    const directFlow = buildPlanModePrompt({
+      ...base,
+      template: { absPath: "/tmp/plans-templates/feature.md", content: "# Feature\n## Implementation Steps\n1. Do it" },
+    });
+    expect(directFlow).toContain("Phase D: Completion");
+    expect(directFlow).toContain("Template (via --template)");
+  });
+});
+
+describe("Phase C.5 自审清单 + D8 重挂请求纪律 + selfReview 必带（D9②/D8）", () => {
+  it("模板流程：C.5 四项清单在产物纪律段之后注入，submit-review 指引必带 selfReview，重挂请求直接重提", () => {
+    const projectRoot = mkTmpDir("plan-prompt-c5-");
+    const prompt = buildPlanModePrompt({
+      requirement: "add dark mode",
+      planFilePath: join(projectRoot, ".tmp", "plans", "add-dark-mode", "plan.md"),
+      projectRoot,
+      skills: [],
+    });
+
+    // Phase C.5 自审清单（D9②）：四项 + 先修文档再提交
+    expect(prompt).toContain("Phase C.5: Self-Review Before Submission");
+    expect(prompt).toContain("Requirement coverage");
+    expect(prompt).toContain("Assumption audit");
+    expect(prompt).toContain("[UNVERIFIED]");
+    expect(prompt).toContain("Chapter completeness");
+    expect(prompt).toContain("Acceptance realism");
+    // C.5 段落在产物纪律段之后（D9② 注入位钉死）
+    expect(prompt.indexOf("## Deliverable Discipline")).toBeLessThan(prompt.indexOf("Phase C.5"));
+    // 自审硬门的提示词面：submit-review 必带 selfReview（无豁免）
+    expect(prompt).toContain("selfReview is REQUIRED every time");
+    expect(prompt).toContain("plan(action='submit-review', selfReview=");
+    // D8 提示词纪律：收到重挂请求直接 submit-review（不再让用户猜/让 agent 无指令）
+    expect(prompt).toContain("asks to re-submit the plan review");
+    expect(prompt).toContain("IMMEDIATELY");
+  });
+
+  it("技能流程同样注入 C.5（自审硬门对每次 submit-review 生效，不随模板/技能流程分叉）", () => {
+    const projectRoot = mkTmpDir("plan-prompt-c5s-");
+    const prompt = buildPlanModePrompt({
+      requirement: "refactor auth",
+      planFilePath: join(projectRoot, ".tmp", "plans", "refactor-auth", "plan.md"),
+      projectRoot,
+      skills: [{ name: "tech-design", skillPath: "/skills/tech-design/SKILL.md" }],
+    });
+
+    expect(prompt).toContain("Phase C.5: Self-Review Before Submission");
+    expect(prompt).toContain("selfReview is REQUIRED every time");
+  });
+});

package/src/__tests__/review-contract-boundary.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock typebox / pi-ai before importing tool（形态照 review.test.ts）
+vi.mock("typebox", () => ({
+  Type: {
+    Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
+    String: (opts?: Record<string, unknown>) => ({ type: "string", ...opts }),
+    Optional: (schema: unknown) => schema,
+    Array: (item: unknown, opts?: Record<string, unknown>) => ({ type: "array", items: item, ...opts }),
+  },
+  Static: class {},
+}));
+
+vi.mock("@earendil-works/pi-ai", () => ({
+  StringEnum: (values: readonly string[]) => ({ type: "string", enum: [...values] }),
+}));
+
+vi.mock("../execution-notice.js", async () => {
+  const { GOAL_FAILURE_RECOVERY } = await vi.importActual<typeof import("../execution-notice.js")>("../execution-notice.js");
+  return {
+    handlePlanComplete: vi.fn(),
+    GOAL_FAILURE_RECOVERY,
+  };
+});
+
+vi.mock("../widget.js", () => ({ updatePlanWidget: vi.fn() }));
+// importActual 展开：只覆写 detectExecSkills（不扫真实目录），其余导出（含 enter.ts
+// re-export 的 resolveSkills 执行门禁）走真实现——mock 罩全模块会把它一并变 undefined
+vi.mock("@zhushanwen/pi-exec-skills", async () => {
+  const actual = await vi.importActual<typeof import("@zhushanwen/pi-exec-skills")>(
+    "@zhushanwen/pi-exec-skills",
+  );
+  return { ...actual, detectExecSkills: vi.fn(() => []) };
+});
+
+import {
+  isPlanReviewRequest,
+  PLAN_REVIEW_MARKER,
+  PLAN_SELF_REVIEW_MAX_BYTES,
+} from "@zhushanwen/extension-protocol";
+
+import type { PlanState } from "../state.js";
+import { createPlanCtx, DEFAULT_PLAN_STATE } from "../state.js";
+import { registerPlanTool } from "../tool.js";
+
+const ALL_TOOL_NAMES = ["read", "bash", "grep", "find", "ls", "plan", "ask_user", "write", "edit"];
+
+function planningState(): PlanState {
+  return {
+    ...DEFAULT_PLAN_STATE,
+    isActive: true,
+    planFilePath: "/tmp/test-project/.tmp/plans/auth/plan.md",
+    requirement: "refactor auth",
+    docs: [{ fileName: "design.md", absPath: "/tmp/test-project/.tmp/plans/auth/design.md", sourceSkill: "", version: 1 }],
+    state: "planning",
+  };
+}
+
+function setup() {
+  const planCtx = createPlanCtx();
+  let executeFn: (id: string, p: Record<string, unknown>, sig?: AbortSignal, upd?: unknown, ctx?: unknown) => Promise<unknown>;
+  const pi = {
+    registerTool: vi.fn((tool) => { executeFn = tool.execute; }),
+    appendEntry: vi.fn(),
+    setActiveTools: vi.fn(),
+    sendMessage: vi.fn(),
+    getCommands: vi.fn(() => []),
+    getAllTools: vi.fn(() => ALL_TOOL_NAMES.map((n) => ({ name: n }))),
+  } as unknown as Parameters<typeof registerPlanTool>[0];
+  registerPlanTool(pi, planCtx);
+
+  const ctx = {
+    sessionId: "test-session",
+    cwd: "/tmp/test-project",
+    hasUI: true,
+    mode: "rpc" as const,
+    isProjectTrusted: () => true,
+    sessionManager: { getSessionId: () => "test-session", getEntries: () => [] },
+    ui: { select: vi.fn(), notify: vi.fn() },
+  };
+  planCtx.states.set("test-session", planningState());
+
+  const exec = (params: Record<string, unknown>) => executeFn!("tc0", params, undefined, undefined, ctx);
+  return { pi, ctx, exec };
+}
+
+/** 取 marker payload（submit-review select options[0] 解析结果） */
+function markerPayload(ctx: { ui: { select: unknown } }): unknown {
+  const calls = (ctx.ui.select as ReturnType<typeof vi.fn>).mock.calls;
+  const markerCall = calls.find((c) => c[0] === PLAN_REVIEW_MARKER);
+  return JSON.parse((markerCall![1] as string[])[0]);
+}
+
+beforeEach(() => {
+  vi.stubEnv("TAIJI_AGENT_EXT_LOG", "1");
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+// ── 契约纯函数（error envelope / boundary 帧 / truncateSelfReview）的 canonical 测试
+// 在 packages/extension-protocol/src/extensions/plan/review-contract.test.ts（更强版本：
+// 键剥除结构断言 / 4KB 字节界精确锚 / 刁钻样本超集）——本文件只保留经 tool 消费面的
+// 接线契约，不重复测共享逻辑。──
+
+// ── 经 tool 消费面的契约落地（consumers.md ①③：payload 构造单点 + 双分源降级）──
+
+describe("契约经 executeSubmitReview 消费面落地", () => {
+  it("超限 selfReview：payload 构造单点截断（写侧 4KB），且产出 payload 过入站守卫（boundary 帧合法）", async () => {
+    const { ctx, exec } = setup();
+    const oversized = "自审".repeat(PLAN_SELF_REVIEW_MAX_BYTES); // 远超 4KB
+    (ctx.ui.select as ReturnType<typeof vi.fn>).mockResolvedValue(JSON.stringify({ decision: "dismiss" }));
+
+    await exec({ action: "submit-review", selfReview: oversized });
+
+    const payload = markerPayload(ctx) as { selfReview: string };
+    expect(Buffer.byteLength(payload.selfReview, "utf8")).toBeLessThanOrEqual(PLAN_SELF_REVIEW_MAX_BYTES);
+    // 截断后仍是合法 boundary 帧（消费侧守卫必过）
+    expect(isPlanReviewRequest(payload)).toBe(true);
+  });
+
+});