@zhushanwen/pi-plan 0.5.2 → 1.1.0

package/src/__tests__/skills.test.ts

@@ -18,7 +18,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 
 import { parsePlanArgs, registerPlanCommand } from "../command.js";
 import { resolveSkills } from "../enter.js";
-import { PLAN_CONTEXT_CUSTOM_TYPE } from "../state.js";
+import { createPlanCtx, PLAN_CONTEXT_CUSTOM_TYPE } from "../state.js";
 
 const ALL_TOOL_NAMES = ["read", "bash", "grep", "find", "ls", "plan", "write", "edit"];
 
@@ -132,13 +132,22 @@ describe("resolveSkills（E1 技能枚举比对，双向剥 skill: 前缀归一
       expect(resolution.missing).toEqual(["tech-desig"]);
     }
   });
+
+  it("empty request = 同族 fail-fast：ok:false + 全量 available + 空 missing（空 --skills 报错材料复用本函数产出）", () => {
+    const resolution = resolveSkills(pi, []);
+    expect(resolution.ok).toBe(false);
+    if (!resolution.ok) {
+      // missing 空 → 报错器走「no skill names followed it」文案分支；available 同源枚举
+      expect(resolution.missing).toEqual([]);
+      expect(resolution.available).toEqual(["skill:tech-design", "skill:dev-flow", "skill:code review"]);
+    }
+  });
 });
 
 describe("E1 fail-fast via /plan handler", () => {
   let pi: ExtensionAPI;
   let ctx: ExtensionContext;
   let handler: (args: string, ctx: ExtensionContext) => Promise<void>;
-  let controllers: Map<string, AbortController>;
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -157,6 +166,7 @@ describe("E1 fail-fast via /plan handler", () => {
       cwd: "/tmp/test-project",
       sessionManager: {
         getSessionId: () => "test-session",
+        getLeafId: () => null,
         getEntries: () => [] as unknown[],
       },
       ui: {
@@ -166,8 +176,7 @@ describe("E1 fail-fast via /plan handler", () => {
         theme: { fg: (_t: string, text: string) => text },
       },
     } as unknown as ExtensionContext;
-    controllers = new Map();
-    registerPlanCommand(pi, new Map(), controllers);
+    registerPlanCommand(pi, createPlanCtx());
     handler = capturedHandler!;
   });
 
@@ -221,7 +230,7 @@ describe("E1 fail-fast via /plan handler", () => {
   it("valid skills: enters plan mode, persists skills and injects skill paths in the prompt", async () => {
     await handler("重构 auth --skills tech-design,code review", ctx);
 
-    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
+    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan", "ask_user"]);
     // slug 只保留 [a-z0-9]：「重构 auth」→ "auth"
     expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/test-project/.tmp/plans/auth", { recursive: true });
     expect(pi.appendEntry).toHaveBeenCalledWith(

package/src/__tests__/state.test.ts

@@ -3,12 +3,13 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { PLAN_SELF_REVIEW_MAX_BYTES } from "@zhushanwen/extension-protocol";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import {
   capPlanRequirement,
   DEFAULT_PLAN_STATE,
-  freshAbortController,
+  freshPendingSelect,
   getPlanState,
   MAX_PLAN_REQUIREMENT_LENGTH,
   persistPlanState,
@@ -17,6 +18,8 @@ import {
   type PlanState,
   reconstructPlanState,
   resetPlanState,
+  clearRoundFields,
+  createPlanCtx,
 } from "../state.js";
 
 describe("PlanState", () => {
@@ -27,8 +30,10 @@ describe("PlanState", () => {
     expect(DEFAULT_PLAN_STATE.templateName).toBe("");
     expect(DEFAULT_PLAN_STATE.skills).toEqual([]);
     expect(DEFAULT_PLAN_STATE.docs).toEqual([]);
-    expect(DEFAULT_PLAN_STATE.reviewState).toBeUndefined();
-    expect(DEFAULT_PLAN_STATE.reviewStateSource).toBeUndefined();
+    // D1/D2：缺省态 = 生命周期 'idle'（无 plan）；selfReview/resumeHint 无值
+    expect(DEFAULT_PLAN_STATE.state).toBe("idle");
+    expect(DEFAULT_PLAN_STATE.selfReview).toBeUndefined();
+    expect(DEFAULT_PLAN_STATE.resumeHint).toBeUndefined();
   });
 
   it("getPlanState returns cached state if exists", () => {
@@ -37,7 +42,7 @@ describe("PlanState", () => {
     sessions.set("session-1", cached);
 
     const mockCtx = {
-      sessionManager: { getEntries: () => [] },
+      sessionManager: { getLeafId: () => null, getEntries: () => [] },
     } as unknown as ExtensionContext;
 
     const result = getPlanState(sessions, "session-1", mockCtx);
@@ -48,6 +53,7 @@ describe("PlanState", () => {
     const sessions: PlanSessionMap = new Map();
     const mockCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
           {
             type: "custom",
@@ -65,7 +71,7 @@ describe("PlanState", () => {
 });
 
 describe("State persistence", () => {
-  it("persistPlanState calls appendEntry with the full schema (no phase field — D6)", () => {
+  it("persistPlanState calls appendEntry with the full schema (state/selfReview/resumeHint 取代式 — D2；无 phase — D6)", () => {
     const mockPi = { appendEntry: vi.fn() } as unknown as ExtensionAPI;
     const state: PlanState = {
       isActive: true,
@@ -74,39 +80,48 @@ describe("State persistence", () => {
       templateName: "feature-plan",
       skills: ["tech-design"],
       docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "tech-design", version: 2 }],
-      reviewState: "awaiting",
+      state: "reviewing",
+      selfReview: "covered all 3 requirements",
+      resumeHint: "resubmit",
     };
 
     persistPlanState(mockPi, state);
 
-    // 精确匹配：新写的 plan-state entry 为全字段 schema（D1：四现状 + skills/docs/reviewState
-    // + reviewStateSource + lastSubmitReviewDocsFingerprint）；无值 optional 字段为 undefined
+    // 精确匹配：新写 entry 全字段 schema（D2 取代式——只落 state/resumeHint/selfReview，
+    // reviewState/reviewStateSource 停写）；无值 optional 字段为 undefined
     // （JSON 序列化自然消失——D4）
     expect(mockPi.appendEntry).toHaveBeenCalledWith("plan-state", {
       isActive: true,
       planFilePath: ".tmp/plans/test/plan.md",
       requirement: "test requirement",
       templateName: "feature-plan",
+      templateProvided: undefined,
       skills: ["tech-design"],
       docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "tech-design", version: 2 }],
-      reviewState: "awaiting",
-      reviewStateSource: undefined,
+      state: "reviewing",
+      selfReview: "covered all 3 requirements",
+      resumeHint: "resubmit",
       lastSubmitReviewDocsFingerprint: undefined,
     });
+    // 停写断言（取代式演进，D2）：旧键不得回写
+    const entry = (mockPi.appendEntry as ReturnType<typeof vi.fn>).mock.calls[0][1] as Record<string, unknown>;
+    expect("reviewState" in entry).toBe(false);
+    expect("reviewStateSource" in entry).toBe(false);
   });
 
   it("reconstructPlanState returns DEFAULT_PLAN_STATE when no entries", () => {
     const mockCtx = {
-      sessionManager: { getEntries: () => [] },
+      sessionManager: { getLeafId: () => null, getEntries: () => [] },
     } as unknown as ExtensionContext;
 
     const state = reconstructPlanState(mockCtx);
     expect(state).toEqual(DEFAULT_PLAN_STATE);
   });
 
-  it("reconstructPlanState restores the full new-schema state from entries (D1)", () => {
+  it("reconstructPlanState restores state/selfReview/resumeHint from new-schema entries (D1/D2)", () => {
     const mockCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
           {
             type: "custom",
@@ -118,7 +133,9 @@ describe("State persistence", () => {
               templateName: "",
               skills: ["tech-design", "dev-flow"],
               docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "tech-design", version: 1 }],
-              reviewState: "awaiting",
+              state: "dispatching",
+              selfReview: "all covered",
+              resumeHint: "resubmit",
             },
           },
         ],
@@ -131,12 +148,38 @@ describe("State persistence", () => {
     expect(state.docs).toEqual([
       { fileName: "design.md", absPath: "/p/design.md", sourceSkill: "tech-design", version: 1 },
     ]);
-    expect(state.reviewState).toBe("awaiting");
+    expect(state.state).toBe("dispatching");
+    expect(state.selfReview).toBe("all covered");
+    expect(state.resumeHint).toBe("resubmit");
+  });
+
+  it("旧 entry 无 state：reviewState 映射（awaiting→reviewing / revising→revising）+ reviewStateSource→resumeHint 同义映射（D2 读方①）", () => {
+    const entryFor = (data: Record<string, unknown>) => ({
+      sessionManager: {
+        getEntries: () => [{ type: "custom", customType: "plan-state", data }],
+      },
+    }) as unknown as ExtensionContext;
+
+    expect(
+      reconstructPlanState(entryFor({ isActive: true, planFilePath: "/p/plan.md", requirement: "r", templateName: "", reviewState: "awaiting" })).state,
+    ).toBe("reviewing");
+    expect(
+      reconstructPlanState(entryFor({ isActive: true, planFilePath: "/p/plan.md", requirement: "r", templateName: "", reviewState: "revising" })).state,
+    ).toBe("revising");
+    // reviewStateSource:'resubmit' → resumeHint:'resubmit'（同义映射，consumers.md 二①）
+    expect(
+      reconstructPlanState(entryFor({ isActive: true, planFilePath: "/p/plan.md", requirement: "r", templateName: "", reviewState: "awaiting", reviewStateSource: "resubmit" })).resumeHint,
+    ).toBe("resubmit");
+    // 新字段优先于旧字段映射（混装过渡格：同 entry 双写形态也取新值）
+    expect(
+      reconstructPlanState(entryFor({ isActive: true, planFilePath: "/p/plan.md", requirement: "r", templateName: "", state: "approved", reviewState: "awaiting" })).state,
+    ).toBe("approved");
   });
 
   it("old four-field entries (no new fields) reconstruct with field-level fallback (D4 兼容读)", () => {
     const mockCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
           {
             type: "custom",
@@ -159,12 +202,14 @@ describe("State persistence", () => {
     // 新字段降级为空清单/无值（前端据此显示「（未指定）」+ 单文件形态）
     expect(state.skills).toEqual([]);
     expect(state.docs).toEqual([]);
-    expect(state.reviewState).toBeUndefined();
+    // D2 读方①：无 state 无 reviewState → 按 isActive 推断（isActive=true → planning）
+    expect(state.state).toBe("planning");
   });
 
   it("malformed new-field values are dropped, not propagated (垃圾数据不进内存态)", () => {
     const mockCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
           {
             type: "custom",
@@ -176,6 +221,9 @@ describe("State persistence", () => {
               templateName: "",
               skills: ["ok", 42, null],
               docs: [{ fileName: "good.md", absPath: "/p/good.md", sourceSkill: "", version: 1 }, "junk", { bad: true }],
+              state: "bogus-state",
+              selfReview: 42,
+              resumeHint: "explain",
               reviewState: "corrupted",
             },
           },
@@ -188,13 +236,18 @@ describe("State persistence", () => {
     expect(state.docs).toEqual([
       { fileName: "good.md", absPath: "/p/good.md", sourceSkill: "", version: 1 },
     ]);
-    expect(state.reviewState).toBeUndefined();
+    // state 值域外垃圾按缺失处理 → 落旧字段映射（reviewState 也坏）→ 按 isActive 推断
+    expect(state.state).toBe("planning");
+    expect(state.selfReview).toBeUndefined();
+    // resumeHint 值域守卫：'resubmit' 之外（含旧 'explain' 存量值）按无值处理
+    expect(state.resumeHint).toBeUndefined();
   });
 
   it("reconstructPlanState ignores the legacy phase field in old entries (D6 兼容读 — V5②)", () => {
     // 旧版（含 phase）写的 entry：重开后 plan mode 重建正常，phase 被白名单式读取自然忽略
     const mockCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
           {
             type: "custom",
@@ -212,7 +265,9 @@ describe("State persistence", () => {
     } as unknown as ExtensionContext;
 
     const state = reconstructPlanState(mockCtx);
-    expect(Object.keys(state).sort()).toEqual(["docs", "isActive", "lastSubmitReviewDocsFingerprint", "planFilePath", "requirement", "reviewState", "reviewStateSource", "skills", "templateName", "templateProvidedPath"]);
+    // D2/D9：重建产物键集 = 四现状 + state/selfReview/resumeHint + skills/docs + 指纹
+    //（reviewState/reviewStateSource 不再是内存态字段，仅映射读）
+    expect(Object.keys(state).sort()).toEqual(["docs", "isActive", "lastSubmitReviewDocsFingerprint", "planFilePath", "requirement", "resumeHint", "selfReview", "skills", "state", "templateName", "templateProvided"]);
     expect(state.isActive).toBe(true);
   });
 
@@ -225,7 +280,7 @@ describe("State persistence", () => {
       templateName: "",
       skills: [],
       docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "", version: 1 }],
-      reviewState: "awaiting",
+      state: "reviewing",
       lastSubmitReviewDocsFingerprint: "design.md:1",
     };
 
@@ -235,13 +290,14 @@ describe("State persistence", () => {
     // 重提交无变化检测仍能比对到上次基线）
     const persisted = (mockPi.appendEntry as ReturnType<typeof vi.fn>).mock.calls[0][1];
     const reopenCtx = {
-      sessionManager: { getEntries: () => [{ type: "custom", customType: "plan-state", data: persisted }] },
+      sessionManager: { getLeafId: () => null, getEntries: () => [{ type: "custom", customType: "plan-state", data: persisted }] },
     } as unknown as ExtensionContext;
     expect(reconstructPlanState(reopenCtx).lastSubmitReviewDocsFingerprint).toBe("design.md:1");
 
     // 垃圾数据不进内存态：非 string 指纹按无既往提交处理（不警告语义）
     const badCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
           {
             type: "custom",
@@ -254,7 +310,7 @@ describe("State persistence", () => {
     expect(reconstructPlanState(badCtx).lastSubmitReviewDocsFingerprint).toBeUndefined();
   });
 
-  it("reviewStateSource persists and reconstructs；旧 entry 无字段 / 非法值 / 旧 'explain' 存量值按无值处理（D4 兼容读）", () => {
+  it("resumeHint persists and reconstructs（D2）；旧 reviewStateSource 同义映射 / 垃圾值按无值处理", () => {
     const mockPi = { appendEntry: vi.fn() } as unknown as ExtensionAPI;
     const state: PlanState = {
       isActive: true,
@@ -263,8 +319,8 @@ describe("State persistence", () => {
       templateName: "",
       skills: [],
       docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "", version: 1 }],
-      reviewState: "awaiting",
-      reviewStateSource: "resubmit",
+      state: "reviewing",
+      resumeHint: "resubmit",
     };
 
     persistPlanState(mockPi, state);
@@ -272,13 +328,14 @@ describe("State persistence", () => {
     // 持久化 entry 走冷启动重建：resubmit 等待态跨重开可恢复（E3 重挂同款受益）
     const persisted = (mockPi.appendEntry as ReturnType<typeof vi.fn>).mock.calls[0][1];
     const reopenCtx = {
-      sessionManager: { getEntries: () => [{ type: "custom", customType: "plan-state", data: persisted }] },
+      sessionManager: { getLeafId: () => null, getEntries: () => [{ type: "custom", customType: "plan-state", data: persisted }] },
     } as unknown as ExtensionContext;
-    expect(reconstructPlanState(reopenCtx).reviewStateSource).toBe("resubmit");
+    expect(reconstructPlanState(reopenCtx).resumeHint).toBe("resubmit");
 
-    // 旧 entry（升级前落盘）无该字段：reviewState 有值但无来源 → 无值（renderer 渲染通用降级文案）
+    // 旧 entry（升级前落盘）无该字段且无旧 reviewStateSource → 无值（renderer 渲染通用降级文案）
     const legacyCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
           {
             type: "custom",
@@ -288,27 +345,114 @@ describe("State persistence", () => {
         ],
       },
     } as unknown as ExtensionContext;
-    expect(reconstructPlanState(legacyCtx).reviewStateSource).toBeUndefined();
+    expect(reconstructPlanState(legacyCtx).resumeHint).toBeUndefined();
 
     // 旧版 'explain' 存量值（explain 交互已删）与垃圾值一并按无值处理（值域守卫白名单只认 'resubmit'）
     const explainCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
-          { type: "custom", customType: "plan-state", data: { ...persisted, reviewStateSource: "explain" } },
+          { type: "custom", customType: "plan-state", data: { ...persisted, resumeHint: "explain" } },
         ],
       },
     } as unknown as ExtensionContext;
-    expect(reconstructPlanState(explainCtx).reviewStateSource).toBeUndefined();
+    expect(reconstructPlanState(explainCtx).resumeHint).toBeUndefined();
 
-    // 值域守卫：'resubmit' 之外的垃圾值按无值处理（与 readReviewState 同风格）
+    // 值域守卫：'resubmit' 之外的垃圾值按无值处理（与 readResumeHint 同风格）
     const badCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
-          { type: "custom", customType: "plan-state", data: { ...persisted, reviewStateSource: "bogus" } },
+          { type: "custom", customType: "plan-state", data: { ...persisted, resumeHint: "bogus" } },
         ],
       },
     } as unknown as ExtensionContext;
-    expect(reconstructPlanState(badCtx).reviewStateSource).toBeUndefined();
+    expect(reconstructPlanState(badCtx).resumeHint).toBeUndefined();
+  });
+
+  it("templateProvided 直传标记：新字段直读 + 旧 templateProvidedPath 映射（双字段合并后 entry 级旧字段映射——select-template 直传防御行为等价）", () => {
+    const entryFor = (data: Record<string, unknown>) => ({
+      sessionManager: {
+        getEntries: () => [{ type: "custom", customType: "plan-state", data }],
+      },
+    }) as unknown as ExtensionContext;
+
+    // 新形态直读：templateProvided=true → 直传格（防御拦截源）
+    expect(
+      reconstructPlanState(entryFor({ isActive: true, planFilePath: "/p/plan.md", requirement: "r", templateName: "t", templateProvided: true })).templateProvided,
+    ).toBe(true);
+    // 模板流程格：字段缺失
+    expect(
+      reconstructPlanState(entryFor({ isActive: true, planFilePath: "/p/plan.md", requirement: "r", templateName: "" })).templateProvided,
+    ).toBeUndefined();
+    // 旧双字段形态重放：templateProvidedPath 存在即直传（值不保留——路径无消费方）
+    expect(
+      reconstructPlanState(entryFor({ isActive: true, planFilePath: "/p/plan.md", requirement: "r", templateName: "t", templateProvidedPath: "/x/t.md" })).templateProvided,
+    ).toBe(true);
+    // 垃圾值不进内存态：非 true 直读值与旧字段非 string 一并按模板流程处理
+    expect(
+      reconstructPlanState(entryFor({ isActive: true, planFilePath: "/p/plan.md", requirement: "r", templateName: "", templateProvided: "yes", templateProvidedPath: 42 })).templateProvided,
+    ).toBeUndefined();
+  });
+
+  it("selfReview 重建读侧 4KB 截断防御（D9③/R3：超长旧 entry 不整段进内存态，E3 回传恒有界）", () => {
+    const oversized = "s".repeat(PLAN_SELF_REVIEW_MAX_BYTES + 100);
+    const mockCtx = {
+      sessionManager: {
+        getEntries: () => [
+          { type: "custom", customType: "plan-state", data: { isActive: true, state: "reviewing", selfReview: oversized } },
+        ],
+      },
+    } as unknown as ExtensionContext;
+    const restored = reconstructPlanState(mockCtx).selfReview;
+    expect(restored).toBeDefined();
+    expect(restored!.length).toBeLessThan(oversized.length);
+    expect(PLAN_SELF_REVIEW_MAX_BYTES - restored!.length).toBeLessThan(4);
+  });
+});
+
+describe("clearRoundFields（D4 per-round 字段清理单函数出口）", () => {
+  /** 构造带全部 per-round 字段残留的状态（上一轮 submit-review + E3 重挂后的形态）。 */
+  function stateWithRoundResidue(): PlanState {
+    return {
+      ...DEFAULT_PLAN_STATE,
+      isActive: true,
+      state: "reviewing",
+      selfReview: "上一轮的 selfReview",
+      resumeHint: "resubmit",
+      lastSubmitReviewDocsFingerprint: "design.md:2",
+      docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "tech-design", version: 2 }],
+    };
+  }
+
+  it("三字段（selfReview/resumeHint/指纹）一并清除——单出口锚：per-round 字段集只在本函数表达", () => {
+    const state = stateWithRoundResidue();
+    clearRoundFields(state);
+    expect(state.selfReview).toBeUndefined();
+    expect(state.resumeHint).toBeUndefined();
+    expect(state.lastSubmitReviewDocsFingerprint).toBeUndefined();
+  });
+
+  it("非本轮字段不动：isActive/state/docs 等跨轮字段保持原值", () => {
+    const state = stateWithRoundResidue();
+    clearRoundFields(state);
+    expect(state.isActive).toBe(true);
+    expect(state.state).toBe("reviewing");
+    expect(state.docs).toEqual([
+      { fileName: "design.md", absPath: "/p/design.md", sourceSkill: "tech-design", version: 2 },
+    ]);
+  });
+
+  it("幂等：无残留状态上重复调用不抛错、不引入新值", () => {
+    const state = stateWithRoundResidue();
+    clearRoundFields(state);
+    clearRoundFields(state);
+    expect(state.resumeHint).toBeUndefined();
+    // delete 移除键本身（与 persistPlanState 序列化时 undefined 值键自然消失同形态）：
+    // 清理后键集 = 跨轮字段集，per-round 三键不残留
+    expect(Object.keys(state).sort()).toEqual(
+      ["docs", "isActive", "planFilePath", "requirement", "skills", "state", "templateName"],
+    );
   });
 });
 
@@ -316,7 +460,7 @@ describe("resetPlanState 终态矩阵（D5/E10）", () => {
   function setupActiveSession() {
     const sessions: PlanSessionMap = new Map();
     const mockCtx = {
-      sessionManager: { getEntries: () => [] },
+      sessionManager: { getLeafId: () => null, getEntries: () => [] },
     } as unknown as ExtensionContext;
     sessions.set("session-1", {
       isActive: true,
@@ -325,19 +469,26 @@ describe("resetPlanState 终态矩阵（D5/E10）", () => {
       templateName: "feature-plan",
       skills: ["tech-design", "dev-flow"],
       docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "tech-design", version: 2 }],
-      reviewState: "awaiting",
+      state: "reviewing",
+      selfReview: "prev self-review",
+      resumeHint: "resubmit",
+      lastSubmitReviewDocsFingerprint: "design.md:2",
     });
     const mockPi = { appendEntry: vi.fn() } as unknown as ExtensionAPI;
     return { sessions, mockCtx, mockPi };
   }
 
-  it("isActive=false + reviewState cleared + skills cleared + docs KEPT", () => {
+  it("isActive=false + state=terminal(exited) + selfReview/resumeHint/指纹 cleared + skills cleared + docs KEPT", () => {
     const { sessions, mockCtx, mockPi } = setupActiveSession();
 
     const state = resetPlanState(mockPi, sessions, "session-1", mockCtx);
 
     expect(state.isActive).toBe(false);
-    expect(state.reviewState).toBeUndefined();
+    // 终态矩阵（D3 连带段）：默认 terminal='exited'
+    expect(state.state).toBe("exited");
+    // selfReview/resumeHint 随退出失效（clearRoundFields 单函数出口的 reset 调用点，S15 断言）
+    expect(state.selfReview).toBeUndefined();
+    expect(state.resumeHint).toBeUndefined();
     expect(state.skills).toEqual([]);
     // docs 保留：产物 tab 与 isActive 解耦，执行期/退出后都可回看产物
     expect(state.docs).toEqual([
@@ -355,9 +506,13 @@ describe("resetPlanState 终态矩阵（D5/E10）", () => {
       planFilePath: "",
       requirement: "",
       templateName: "",
+      templateProvided: undefined,
       skills: [],
       docs: [{ fileName: "design.md", absPath: "/p/design.md", sourceSkill: "tech-design", version: 2 }],
-      reviewState: undefined,
+      state: "exited",
+      selfReview: undefined,
+      resumeHint: undefined,
+      lastSubmitReviewDocsFingerprint: undefined,
     });
     expect(sessions.has("session-1")).toBe(false);
   });
@@ -369,7 +524,7 @@ describe("resetPlanState 终态矩阵（D5/E10）", () => {
     // 模拟重开：用 reset 落盘的 entry 数据走冷启动重建
     const persisted = (mockPi.appendEntry as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[1];
     const reopenCtx = {
-      sessionManager: { getEntries: () => [{ type: "custom", customType: "plan-state", data: persisted }] },
+      sessionManager: { getLeafId: () => null, getEntries: () => [{ type: "custom", customType: "plan-state", data: persisted }] },
     } as unknown as ExtensionContext;
 
     const state = reconstructPlanState(reopenCtx);
@@ -393,19 +548,14 @@ describe("resetPlanState 终态矩阵（D5/E10）", () => {
     expect(state.lastSubmitReviewDocsFingerprint).toBeUndefined();
     expect(state.docs).toHaveLength(1);
   });
-  it("reviewStateSource is cleared on reset (跨 plan run 残留防护，C-U2 同型缺陷)", () => {
+  it("terminal 参数（D3 连带段）：complete 终局传 'completed' 不被 reset 覆写为 'exited'", () => {
     const { sessions, mockCtx, mockPi } = setupActiveSession();
-    const active = sessions.get("session-1");
-    if (!active) throw new Error("setupActiveSession must seed session-1");
-    active.reviewStateSource = "resubmit";
 
-    const state = resetPlanState(mockPi, sessions, "session-1", mockCtx);
+    const state = resetPlanState(mockPi, sessions, "session-1", mockCtx, "completed");
 
-    // 来源标记与 reviewState 同生命周期随退出失效；reset entry 落盘同样无该键
-    // （undefined JSON 序列化自然消失——D4）
-    expect(state.reviewStateSource).toBeUndefined();
+    expect(state.state).toBe("completed");
     const lastEntry = (mockPi.appendEntry as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[1] as PlanState;
-    expect(lastEntry.reviewStateSource).toBeUndefined();
+    expect(lastEntry.state).toBe("completed");
   });
 
   describe("空 slug 目录清理（P3-10）", () => {
@@ -431,7 +581,7 @@ describe("resetPlanState 终态矩阵（D5/E10）", () => {
       const planFilePath = makePlanRoot(false);
       const slugDir = join(planFilePath, "..");
       const sessions: PlanSessionMap = new Map();
-      const mockCtx = { sessionManager: { getEntries: () => [] } } as unknown as ExtensionContext;
+      const mockCtx = { sessionManager: { getLeafId: () => null, getEntries: () => [] } } as unknown as ExtensionContext;
       sessions.set("s1", { ...DEFAULT_PLAN_STATE, isActive: true, planFilePath, requirement: "r", templateName: "", skills: [], docs: [] });
       const mockPi = { appendEntry: vi.fn() } as unknown as ExtensionAPI;
 
@@ -444,7 +594,7 @@ describe("resetPlanState 终态矩阵（D5/E10）", () => {
       const planFilePath = makePlanRoot(true);
       const slugDir = join(planFilePath, "..");
       const sessions: PlanSessionMap = new Map();
-      const mockCtx = { sessionManager: { getEntries: () => [] } } as unknown as ExtensionContext;
+      const mockCtx = { sessionManager: { getLeafId: () => null, getEntries: () => [] } } as unknown as ExtensionContext;
       sessions.set("s1", { ...DEFAULT_PLAN_STATE, isActive: true, planFilePath, requirement: "r", templateName: "", skills: [], docs: [] });
       const mockPi = { appendEntry: vi.fn() } as unknown as ExtensionAPI;
 
@@ -455,18 +605,68 @@ describe("resetPlanState 终态矩阵（D5/E10）", () => {
   });
 });
 
-describe("freshAbortController（E10 生命周期）", () => {
-  it("registers the controller per session and creates a fresh one on each call", () => {
+describe("freshPendingSelect（E10 生命周期 + D-B1-2 dissolvedBy 直传原语）", () => {
+  it("registers the pending select per session and creates a fresh one on each call", () => {
     const controllers: PlanAbortControllers = new Map();
 
-    const first = freshAbortController(controllers, "s1");
+    const first = freshPendingSelect(controllers, "s1");
     expect(controllers.get("s1")).toBe(first);
 
     // 禁复用：第二次调用必须新建（复用已 abort 的 controller 会让 select 瞬时静默取消）
-    const second = freshAbortController(controllers, "s1");
+    const second = freshPendingSelect(controllers, "s1");
     expect(second).not.toBe(first);
     expect(controllers.get("s1")).toBe(second);
   });
+
+  it("dissolvedBy 缺省 undefined（外部解散不打标——等待处按「非 'self' 即外部」分派）", () => {
+    const controllers: PlanAbortControllers = new Map();
+    const pending = freshPendingSelect(controllers, "s1");
+    expect(pending.dissolvedBy).toBeUndefined();
+  });
+
+  it("markDissolved('self') 一次置位且对同一闭包可读（来源随挂起闭包直达等待处）", () => {
+    const controllers: PlanAbortControllers = new Map();
+    const pending = freshPendingSelect(controllers, "s1");
+    pending.markDissolved("self");
+    expect(pending.dissolvedBy).toBe("self");
+    // 闭包身份天然携带轮次记忆：另一个挂起（新轮次）的来源变量独立，不受前轮打标污染
+    const next = freshPendingSelect(controllers, "s1");
+    expect(next.dissolvedBy).toBeUndefined();
+  });
+});
+
+describe("createPlanCtx / dissolveAll（D-B4-3 单 ctx 对象：两表收敛 + 解散方法承载 exitPlanMode 入口动作）", () => {
+  it("两表为空 Map 且独立：states / controllers 各自可读写", () => {
+    const planCtx = createPlanCtx();
+    expect(planCtx.states.size).toBe(0);
+    expect(planCtx.controllers.size).toBe(0);
+    const pending = freshPendingSelect(planCtx.controllers, "s1");
+    expect(planCtx.controllers.get("s1")).toBe(pending);
+  });
+
+  it("dissolveAll：全部挂起 markDissolved 打标 + controller.abort + 注册表清空（exitPlanMode ① 的承载）", () => {
+    const planCtx = createPlanCtx();
+    const abortSpy = vi.fn();
+    const first = freshPendingSelect(planCtx.controllers, "s1");
+    const second = freshPendingSelect(planCtx.controllers, "s2");
+    vi.spyOn(first.controller, "abort").mockImplementation(abortSpy);
+    vi.spyOn(second.controller, "abort").mockImplementation(abortSpy);
+
+    planCtx.dissolveAll("self");
+
+    // 来源随闭包直达等待处（D-B1-2）：打标先于 abort 不可在此直接断言（同步序列），
+    // 但两挂起都必须置位 + 中止；注册表不留已 dissolved 条目
+    expect(first.dissolvedBy).toBe("self");
+    expect(second.dissolvedBy).toBe("self");
+    expect(abortSpy).toHaveBeenCalledTimes(2);
+    expect(planCtx.controllers.size).toBe(0);
+  });
+
+  it("dissolveAll 无挂起时为 no-op（无挂起退出的幂等形态）", () => {
+    const planCtx = createPlanCtx();
+    expect(() => planCtx.dissolveAll("self")).not.toThrow();
+    expect(planCtx.controllers.size).toBe(0);
+  });
 });
 
 describe("requirement 长度封顶（MF-1-3：session.planState 帧不登记 LARGE_FIELD_REGISTRY 的有界前提代码化）", () => {
@@ -490,6 +690,7 @@ describe("requirement 长度封顶（MF-1-3：session.planState 帧不登记 LAR
     const oversized = "z".repeat(MAX_PLAN_REQUIREMENT_LENGTH * 2);
     const mockCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
           { type: "custom", customType: "plan-state", data: { isActive: true, requirement: oversized } },
         ],
@@ -504,6 +705,7 @@ describe("requirement 长度封顶（MF-1-3：session.planState 帧不登记 LAR
   it("非 string requirement（含缺失）仍归空串（白名单读取语义不变）", () => {
     const mockCtx = {
       sessionManager: {
+        getLeafId: () => null,
         getEntries: () => [
           { type: "custom", customType: "plan-state", data: { isActive: false, requirement: 123 } },
         ],