@zhushanwen/pi-plan 0.4.5 → 0.4.7

package/src/__tests__/templates.test.ts

@@ -1,21 +1,26 @@
 import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
 
 import { describe, expect, it } from "vitest";
 
+import { extractPlanSteps } from "../compact.js";
 import { getBuiltinTemplateDir, listTemplates, loadTemplate } from "../templates.js";
 
-describe("Template system", () => {
-  it("listTemplates returns builtin templates", () => {
+const BUILTIN_TEMPLATE_NAMES = [
+  "feature-plan",
+  "bugfix-plan",
+  "refactor-plan",
+  "research-plan",
+  "implementation-plan",
+];
+
+describe("Template system (builtin single source, D3)", () => {
+  it("listTemplates returns exactly the 5 builtin templates with no source field", () => {
     const templates = listTemplates();
-    expect(templates.length).toBeGreaterThanOrEqual(5);
-    const names = templates.map((t) => t.name);
-    expect(names).toContain("feature-plan");
-    expect(names).toContain("bugfix-plan");
-    expect(names).toContain("refactor-plan");
-    expect(names).toContain("research-plan");
-    expect(names).toContain("implementation-plan");
+    expect(templates.map((t) => t.name).sort()).toEqual([...BUILTIN_TEMPLATE_NAMES].sort());
+    // 单源化后 TemplateInfo 只有 name/path —— source 等多源残留字段即红
+    for (const t of templates) {
+      expect(t).toEqual({ name: t.name, path: t.path });
+    }
   });
 
   it("loadTemplate returns content for existing builtin template", () => {
@@ -33,28 +38,23 @@ describe("Template system", () => {
     const dir = getBuiltinTemplateDir();
     expect(fs.existsSync(dir)).toBe(true);
   });
+});
 
-  it("TC8: PI_CODING_AGENT_DIR 隔离目录下扫到全局模板（getAgentDir 派生，不依赖 ~/.pi/agent）", () => {
-    const origEnv = process.env.PI_CODING_AGENT_DIR;
-    const isolated = fs.mkdtempSync(path.join(os.tmpdir(), "plan-tpl-"));
-    try {
-      process.env.PI_CODING_AGENT_DIR = isolated;
-      fs.mkdirSync(path.join(isolated, "plan-templates"), { recursive: true });
-      fs.writeFileSync(path.join(isolated, "plan-templates", "isolated-template.md"), "# t");
-
-      const templates = listTemplates();
-      const names = templates.map((t) => t.name);
-      expect(names).toContain("isolated-template");
-      // 隔离目录模板 source 为 global（getAgentDir 直接返回 PI_CODING_AGENT_DIR 值，无 .pi/agent 嵌套）
-      const tpl = templates.find((t) => t.name === "isolated-template");
-      expect(tpl?.source).toBe("global");
-      expect(tpl?.path.startsWith(isolated)).toBe(true);
-      // 仍能扫到 builtin 模板（最低优先级）
-      expect(names).toContain("feature-plan");
-    } finally {
-      if (origEnv === undefined) delete process.env.PI_CODING_AGENT_DIR;
-      else process.env.PI_CODING_AGENT_DIR = origEnv;
-      fs.rmSync(isolated, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
-    }
+describe("template ↔ extractPlanSteps alignment guard (D4)", () => {
+  // 守卫对象：模板生成端的步骤节标题与解析端正则同仓同测，漂移即红——
+  // ① 模板标题改名 → 恰一节断言失败；
+  // ② 解析正则与标题脱节 → 提取退化到 fallback 收进其他节的噪音项 → toEqual 失败。
+  it.each(BUILTIN_TEMPLATE_NAMES)("template '%s' has exactly one '## Implementation Steps' section that extractPlanSteps consumes", (name) => {
+    const content = loadTemplate(name);
+    expect(content).not.toBeNull();
+
+    expect(content!.match(/^## Implementation Steps$/gm)).toHaveLength(1);
+
+    const plan = content!
+      // 在第一个非步骤节标题后放噪音编号项（模拟 Requirements 等节含编号列表）
+      .replace(/^(## (?!Implementation Steps).+)$/m, "$1\n1. noise-from-other-section")
+      // 在步骤节标题后填编号步骤（模拟 AI 按模板写 plan.md）
+      .replace(/^## Implementation Steps$/m, "## Implementation Steps\n1. Real step A\n2. Real step B");
+    expect(extractPlanSteps(plan)).toEqual(["Real step A", "Real step B"]);
   });
 });

package/src/__tests__/tool.test.ts

@@ -14,26 +14,23 @@ vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: readonly string[]) => ({ type: "string", enum: [...values] }),
 }));
 
-// Mock compact.js (dynamically imported by complete action)
-vi.mock("../compact.js", () => ({
-  handlePlanComplete: vi.fn(),
-  detectGoalCapability: vi.fn(() => false),
-}));
+// Mock compact.js (statically imported since 06-u1)
+vi.mock("../compact.js", async () => {
+  // GOAL_FAILURE_RECOVERY 与真实实现同文案——completeResultText 在 failure 断言里消费它
+  const { GOAL_FAILURE_RECOVERY } = await vi.importActual<typeof import("../compact.js")>("../compact.js");
+  return {
+    handlePlanComplete: vi.fn(),
+    detectGoalCapability: vi.fn(() => false),
+    GOAL_FAILURE_RECOVERY,
+  };
+});
 
 // Mock widget (imported by abort)
 vi.mock("../widget.js", () => ({
   updatePlanWidget: vi.fn(),
 }));
 
-// Mock node:fs — ESM namespace isn't configurable, so we use vi.mock
-vi.mock("node:fs", async () => {
-  const actual = await vi.importActual<typeof import("node:fs")>("node:fs");
-  return { ...actual, mkdirSync: vi.fn(), writeFileSync: vi.fn() };
-});
-
-import * as fs from "node:fs";
-
-import { handlePlanComplete } from "../compact.js";
+import { detectGoalCapability, handlePlanComplete } from "../compact.js";
 import { PLAN_ACTIONS, registerPlanTool, validateAction } from "../tool.js";
 import { updatePlanWidget } from "../widget.js";
 
@@ -78,6 +75,19 @@ describe("registerPlanTool", () => {
       expect(res.details.action).toBe("list-template");
       expect(Array.isArray(res.details.templates)).toBe(true);
     });
+
+    it("returns exactly the 5 builtin templates with no source field (D3 / V4)", async () => {
+      const { exec } = setup();
+      const res = await exec({ action: "list-template" });
+      const templates = res.details.templates as Array<{ name: string; source?: string; path: string }>;
+      expect(templates.map((t) => t.name).sort()).toEqual(
+        ["feature-plan", "bugfix-plan", "refactor-plan", "research-plan", "implementation-plan"].sort(),
+      );
+      for (const t of templates) {
+        expect(t.source).toBeUndefined();
+        expect(t).toEqual({ name: t.name, path: t.path });
+      }
+    });
   });
 
   // --- select-template ---
@@ -92,7 +102,7 @@ describe("registerPlanTool", () => {
       await expect(exec({ action: "select-template", templateName: "nonexistent" })).rejects.toThrow("Template not found");
     });
 
-    it("sets phase to writing and persists", async () => {
+    it("sets templateName and persists (D6：无 phase 写入)", async () => {
       const { exec, pi, sessions } = setup();
       // Use a builtin template name — find one first
       const listRes = await exec({ action: "list-template" });
@@ -103,39 +113,46 @@ describe("registerPlanTool", () => {
       const res = await exec({ action: "select-template", templateName: name });
       expect(res.details.templateName).toBe(name);
       expect(res.details.action).toBe("select-template");
-      expect(pi.appendEntry).toHaveBeenCalled();
-      const state = sessions.get("test-session");
-      expect(state?.phase).toBe("writing");
+      expect(pi.appendEntry).toHaveBeenCalledWith("plan-state", expect.objectContaining({ templateName: name }));
+      const state = sessions.get("test-session") as { templateName?: string; isActive?: boolean };
       expect(state?.templateName).toBe(name);
     });
   });
 
-  // --- create-template ---
-  describe("create-template", () => {
-    beforeEach(() => { (fs.mkdirSync as ReturnType<typeof vi.fn>).mockClear(); (fs.writeFileSync as ReturnType<typeof vi.fn>).mockClear(); });
-
-    it("throws when parameters are missing", async () => {
+  // --- removed action (D3) ---
+  describe("create-template removal", () => {
+    it("rejects plan(action='create-template') as an unknown action (D3 / V4)", async () => {
       const { exec } = setup();
-      await expect(exec({ action: "create-template" })).rejects.toThrow("templateName and templateContent are required");
+      await expect(
+        exec({ action: "create-template", templateName: "my-plan", templateContent: "# hello" }),
+      ).rejects.toThrow(
+        "Unknown plan action: create-template. Valid actions: list-template, select-template, complete, abort",
+      );
     });
+  });
 
-    it("throws when name sanitizes to empty", async () => {
-      const { exec } = setup();
-      await expect(exec({ action: "create-template", templateName: "!!!", templateContent: "x" }))
-        .rejects.toThrow("Invalid template name");
+  // --- complete ---
+  describe("complete", () => {
+    beforeEach(() => {
+      // 默认桥不可达（与真实 pi 0.84.4 现状一致）；goal 档用例显式 mock 桥可达
+      (detectGoalCapability as ReturnType<typeof vi.fn>).mockReturnValue(false);
+      (handlePlanComplete as ReturnType<typeof vi.fn>).mockReset();
     });
 
-    it("writes file with sanitized name", async () => {
-      const { exec } = setup();
-      const res = await exec({ action: "create-template", templateName: "My Plan v2!", templateContent: "# hello" });
-      expect(res.details.templateName).toBe("MyPlanv2");
-      expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/test-project/.pi/plan-templates", { recursive: true });
-      expect(fs.writeFileSync).toHaveBeenCalledWith("/tmp/test-project/.pi/plan-templates/MyPlanv2.md", "# hello");
+    /** 注册时捕获的工具定义（schema 检查用）。 */
+    function registeredTool(pi: { registerTool: unknown }): Record<string, unknown> {
+      return ((pi.registerTool as ReturnType<typeof vi.fn>).mock.calls[0][0]) as Record<string, unknown>;
+    }
+
+    it("rejects isolation='tree' at the schema level: enum is exactly compact|direct (D1 / V3①)", async () => {
+      const { pi } = setup();
+      const parameters = registeredTool(pi).parameters as {
+        properties: { isolation: { enum: string[] } };
+      };
+      expect(parameters.properties.isolation.enum).toEqual(["compact", "direct"]);
+      expect(parameters.properties.isolation.enum).not.toContain("tree");
     });
-  });
 
-  // --- complete ---
-  describe("complete", () => {
     it("does not advance when user cancels", async () => {
       const { exec, ctx, pi } = setup();
       (ctx.ui.select as ReturnType<typeof vi.fn>).mockResolvedValue("Modify the plan first");
@@ -154,6 +171,74 @@ describe("registerPlanTool", () => {
       expect(handlePlanComplete).toHaveBeenCalled();
       expect(res.details.planFilePath).toBeDefined();
     });
+
+    it("dialog options exclude the goal tier when the bridge is unavailable", async () => {
+      const { exec, ctx } = setup();
+      (ctx.ui.select as ReturnType<typeof vi.fn>).mockResolvedValue("Single-agent (current session)");
+      await exec({ action: "complete" });
+      const options = (ctx.ui.select as ReturnType<typeof vi.fn>).mock.calls[0][1] as string[];
+      expect(options).not.toContain("Goal-driven execution (/goal)");
+      expect(options).toEqual([
+        "Subagent-driven execution",
+        "Single-agent (current session)",
+        "Modify the plan first",
+        "Save for later",
+      ]);
+    });
+
+    it("dialog options include the goal tier when the bridge is reachable (mocked goalInit slot world)", async () => {
+      const { exec, ctx } = setup();
+      (detectGoalCapability as ReturnType<typeof vi.fn>).mockReturnValue(true);
+      (ctx.ui.select as ReturnType<typeof vi.fn>).mockResolvedValue("Goal-driven execution (/goal)");
+      const res = await exec({ action: "complete" });
+      const options = (ctx.ui.select as ReturnType<typeof vi.fn>).mock.calls[0][1] as string[];
+      expect(options).toEqual([
+        "Subagent-driven execution",
+        "Goal-driven execution (/goal)",
+        "Single-agent (current session)",
+        "Modify the plan first",
+        "Save for later",
+      ]);
+      expect(res.details.execMode).toBe("goal"); // EXEC_MODE_OPTIONS 查表映射（发现 8）
+    });
+
+    it("maps 'Single-agent (current session)' choice to execMode single-agent", async () => {
+      const { exec, ctx } = setup();
+      (ctx.ui.select as ReturnType<typeof vi.fn>).mockResolvedValue("Single-agent (current session)");
+      const res = await exec({ action: "complete" });
+      expect(res.details.execMode).toBe("single-agent");
+    });
+
+    it("direct tier carries the goal outcome into result content and details (D2)", async () => {
+      const { exec, ctx } = setup();
+      (ctx.ui.select as ReturnType<typeof vi.fn>).mockResolvedValue("Goal-driven execution (/goal)");
+      (handlePlanComplete as ReturnType<typeof vi.fn>).mockReturnValue({ started: false, reason: "no-steps" });
+      const res = await exec({ action: "complete", isolation: "direct" });
+      expect(handlePlanComplete).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.anything(), "direct", "goal");
+      expect(res.content[0].text).toContain("Goal execution was not started (no-steps)");
+      expect(res.content[0].text).toContain("Implementation Steps"); // 恢复动作
+      expect(res.details.goalOutcome).toEqual({ started: false, reason: "no-steps" });
+    });
+
+    it("successful goal outcome appends the started line", async () => {
+      const { exec, ctx } = setup();
+      (ctx.ui.select as ReturnType<typeof vi.fn>).mockResolvedValue("Goal-driven execution (/goal)");
+      (handlePlanComplete as ReturnType<typeof vi.fn>).mockReturnValue({ started: true });
+      const res = await exec({ action: "complete", isolation: "direct" });
+      expect(res.content[0].text).toContain("Goal execution started via /goal");
+      expect(res.details.goalOutcome).toEqual({ started: true });
+    });
+
+    it("compact tier outcome is deferred (undefined): result keeps the plain approved line", async () => {
+      const { exec, ctx } = setup();
+      (ctx.ui.select as ReturnType<typeof vi.fn>).mockResolvedValue("Subagent-driven execution");
+      (handlePlanComplete as ReturnType<typeof vi.fn>).mockReturnValue(undefined);
+      const res = await exec({ action: "complete", isolation: "compact" });
+      expect(res.content[0].text).toMatch(/^Plan approved\. File: /);
+      expect(res.content[0].text).not.toContain("Goal execution");
+      expect(res.details.goalOutcome).toBeUndefined();
+      expect(res.details.isolation).toBe("compact");
+    });
   });
 
   // --- abort ---
@@ -161,7 +246,7 @@ describe("registerPlanTool", () => {
     it("resets state and cleans up session", async () => {
       const { exec, pi, sessions } = setup();
       // Pre-populate a session
-      sessions.set("test-session", { isActive: true, phase: "writing", planFilePath: "/tmp/plan.md", requirement: "test", templateName: "t" });
+      sessions.set("test-session", { isActive: true, planFilePath: "/tmp/plan.md", requirement: "test", templateName: "t" });
       const res = await exec({ action: "abort" });
       expect(res.details.action).toBe("abort");
       expect(pi.setActiveTools).toHaveBeenCalledWith(ALL_TOOL_NAMES);
@@ -178,4 +263,7 @@ describe("validateAction", () => {
   it("rejects invalid", () => {
     expect(validateAction("bogus")).toBe(false);
   });
+  it("action list no longer contains create-template (D3)", () => {
+    expect(PLAN_ACTIONS).not.toContain("create-template");
+  });
 });

package/src/command.ts

@@ -58,10 +58,10 @@ export function registerPlanCommand(
         return;
       }
 
-      // Reentry: check for existing plan files in .xyz-harness/
+      // Reentry: check for existing plan files in .taiji-harness/
       if (!state.isActive && !trimmed) {
         const projectDir = ctx.cwd;
-        const harnessDir = path.join(projectDir, ".xyz-harness");
+        const harnessDir = path.join(projectDir, ".taiji-harness");
         const existingPlans = findExistingPlans(harnessDir);
         if (existingPlans.length > 0) {
           pi.sendUserMessage(
@@ -111,12 +111,12 @@ function handleStatus(
     return;
   }
   ctx.ui.notify(
-    `Plan Mode: ${state.phase}\nPlan: ${state.planFilePath}\nTemplate: ${state.templateName || "(not selected)"}`,
+    `Plan: ${state.planFilePath}\nTemplate: ${state.templateName || "(not selected)"}`,
     "info",
   );
 }
 
-/** Find existing plan.md files in .xyz-harness/ subdirectories */
+/** Find existing plan.md files in .taiji-harness/ subdirectories */
 function findExistingPlans(harnessDir: string): string[] {
   try {
     return fs.readdirSync(harnessDir)
@@ -144,12 +144,11 @@ function handleEnterPlanMode(
     : "untitled";
 
   const projectDir = ctx.cwd;
-  const planDir = path.join(projectDir, ".xyz-harness", slug);
+  const planDir = path.join(projectDir, ".taiji-harness", slug);
   fs.mkdirSync(planDir, { recursive: true });
   const planFilePath = path.join(planDir, "plan.md");
 
   state.isActive = true;
-  state.phase = "brainstorming";
   state.planFilePath = planFilePath;
   state.requirement = requirement;
   state.templateName = "";
@@ -182,7 +181,7 @@ function handleEnterPlanMode(
     `4. Write all chapters in one turn, then ask user to review.\n\n` +
     `## Phase D: Completion\n` +
     `1. Ask user to review the complete plan.\n` +
-    `2. Call plan tool (complete) with isolation method (compact/tree/direct).\n` +
+    `2. Call plan tool (complete) with isolation method (compact/direct).\n` +
     `3. After plan complete: the user picks an execution path (subagent-driven / goal-driven / single-agent) via the completion dialog.`,
   );
 }

package/src/compact.ts

@@ -25,18 +25,16 @@ export function registerPlanEventHandlers(
     // Read plan file content for recovery after compact
     const planContent = readPlanFileSafe(state.planFilePath);
 
-    // Include phase info for non-complete phases
-    const phaseNote = state.phase !== "complete"
-      ? `\nPhase: ${state.phase}. Plan was in progress — review and continue.`
-      : "\nAwaiting user decision on execution. Do NOT auto-proceed.";
+    // handler 已有 isActive 门——能走到这里的 plan 必然进行中（D6：phase 删除，原 phase="complete" 分支为死状态）
+    const progressNote = "\nPlan was in progress — review and continue.";
 
     return {
       compaction: {
         summary:
-          `Plan mode active (${state.phase}). Plan file: ${state.planFilePath}\n\n` +
+          `Plan mode active. Plan file: ${state.planFilePath}\n\n` +
           `## Plan Content\n${planContent}\n\n` +
           `Requirement: ${state.requirement}` +
-          phaseNote,
+          progressNote,
         firstKeptEntryId: prep?.firstKeptEntryId,
         tokensBefore: prep?.tokensBefore,
       },
@@ -53,7 +51,7 @@ export function registerPlanEventHandlers(
     return {
       summary: {
         summary:
-          `Plan mode active (${state.phase}). Plan file: ${state.planFilePath}\n\n` +
+          `Plan mode active. Plan file: ${state.planFilePath}\n\n` +
           `## Plan Content\n${planContent}\n\n` +
           `Read the plan file and execute the implementation.`,
       },
@@ -61,24 +59,45 @@ export function registerPlanEventHandlers(
   });
 }
 
-/** Read plan file, return content or error message */
-function readPlanFileSafe(planFilePath: string): string {
+/** Read plan file: ok=false 是显式信号（GoalBridgeOutcome 的 plan-unreadable 出口消费），消除哨兵字符串比较 */
+type PlanFileContent = { ok: true; content: string } | { ok: false };
+
+function readPlanFile(planFilePath: string): PlanFileContent {
   try {
-    return fs.readFileSync(planFilePath, "utf-8");
+    return { ok: true, content: fs.readFileSync(planFilePath, "utf-8") };
   } catch {
-    return "(plan file could not be read)";
+    return { ok: false };
   }
 }
 
+/** Read plan file, return content or human-readable marker (for prompt embedding) */
+function readPlanFileSafe(planFilePath: string): string {
+  const result = readPlanFile(planFilePath);
+  return result.ok ? result.content : "(plan file could not be read)";
+}
+
+/**
+ * goalInit slot key——goal 扩展的跨扩展编程式入口（goal-bridge-cross-extension.md）。
+ * ⚠️ 必须与 `extensions/universal/goal/src/index.ts` 的 GOAL_INIT_SLOT_KEY 字符串完全一致：
+ * 两侧不共享运行时模块（pi-goal 是 optional peer），靠同一字符串拿到同一 globalThis slot。
+ * 改名必须两侧同步。
+ */
+const GOAL_INIT_SLOT_KEY = Symbol.for("@zhushanwen/pi-goal.goalInit");
+
+/**
+ * goal 桥的单一断言点：goal 扩展挂在 globalThis slot 上的编程式接口（发现 7——
+ * 此前 detectGoalCapability / tryGoalInit 两处 inline 断言收敛于此；
+ * 桥通道从 pi API 对象挂载迁到 slot：pi 0.84.4 per-extension API 隔离使
+ * pi.__goalInit 形态跨扩展恒不可见，slot 是 C-ext-06 惯例的进程级共享形态）。
+ */
+function getGoalInit(): GoalInitFn | undefined {
+  const fn = Reflect.get(globalThis, GOAL_INIT_SLOT_KEY);
+  return typeof fn === "function" ? (fn as GoalInitFn) : undefined;
+}
+
 /** Detect whether goal extension is available via its programming interface */
-export function detectGoalCapability(pi: ExtensionAPI): boolean {
-  try {
-    // 交叉类型单步断言（ExtensionAPI 可赋给 ExtensionAPI & { __goalInit? }）
-    const api = pi as ExtensionAPI & { __goalInit?: GoalInitFn };
-    return typeof api.__goalInit === "function";
-  } catch {
-    return false;
-  }
+export function detectGoalCapability(): boolean {
+  return getGoalInit() !== undefined;
 }
 
 /**
@@ -128,29 +147,56 @@ export function buildPlanSuccessCriteria(planFilePath: string, tasks: string[]):
   return items;
 }
 
-/** Try to initialize goal via programming interface */
-function tryGoalInit(pi: ExtensionAPI, planFilePath: string, ctx: ExtensionContext): boolean {
+// ── goal 桥 outcome（D2：失败显式化）───────────────────────────────
+
+/** goalInit 失败原因——五值与 tryGoalInit 的 5 个失败出口一一对应（设计 §6.2 D2）。 */
+export type GoalBridgeFailureReason =
+  | "goal-unavailable" // goal 未加载（slot 不存在/值非函数——桥修复后是真实可达的防御分支：goal 档仅在 detectGoalCapability 通过时出现，但 slot 残留 fn 失效等窗口仍可能触发）
+  | "plan-unreadable" // plan 文件读取失败
+  | "no-steps" // plan 内容提取到 0 条步骤
+  | "init-refused" // goalInit 返回 false（已有 active goal / ctx 缺失）
+  | "internal-error"; // goalInit 抛出意外异常（catch 出口，含 slot 残留 fn 调用失效）
+
+/** tryGoalInit 的结构化结果：失败分支携带 reason（+ internal-error 的异常文本）。 */
+export type GoalBridgeOutcome =
+  | { started: true }
+  | { started: false; reason: GoalBridgeFailureReason; detail?: string };
+
+/** 每个 reason 指向一个具体恢复动作（不做纯日志字符串，设计 §4.2）。 */
+export const GOAL_FAILURE_RECOVERY: Record<GoalBridgeFailureReason, string> = {
+  "goal-unavailable": "The goal extension is not loaded — choose another execution method.",
+  "plan-unreadable": "Check that the plan file exists and is readable, then call plan(action='complete') again.",
+  "no-steps": "Add numbered steps under a '## Implementation Steps' section in the plan file, then call plan(action='complete') again.",
+  "init-refused": "An active goal already exists — run /goal clear first, or continue with the existing goal.",
+  "internal-error": "goalInit threw an unexpected exception (details in the warning notification and logs) — falling back to step-by-step execution.",
+};
+
+/** Try to initialize goal via programming interface; never throws (catch 出口 → internal-error). */
+function tryGoalInit(planFilePath: string, ctx: ExtensionContext): GoalBridgeOutcome {
   try {
-    const api = pi as ExtensionAPI & { __goalInit?: GoalInitFn };
-    const goalInit = api.__goalInit;
-    if (typeof goalInit !== "function") return false;
+    const goalInit = getGoalInit();
+    if (!goalInit) return { started: false, reason: "goal-unavailable" };
 
-    const planContent = readPlanFileSafe(planFilePath);
-    if (planContent.startsWith("(")) return false; // read failed
+    const planFile = readPlanFile(planFilePath);
+    if (!planFile.ok) return { started: false, reason: "plan-unreadable" };
 
     const objective = `Execute plan: ${planFilePath}`;
-    const tasks = extractPlanSteps(planContent);
-    if (tasks.length === 0) return false;
+    const tasks = extractPlanSteps(planFile.content);
+    if (tasks.length === 0) return { started: false, reason: "no-steps" };
 
-    return goalInit(
+    const started = goalInit(
       objective,
       undefined,
       ctx,
       buildPlanSlug(planFilePath),
       buildPlanSuccessCriteria(planFilePath, tasks),
     );
-  } catch {
-    return false;
+    return started
+      ? { started: true }
+      : { started: false, reason: "init-refused" };
+  } catch (error) {
+    logger.warn("plan: goalInit threw unexpectedly", { error: toErrorMessage(error) });
+    return { started: false, reason: "internal-error", detail: toErrorMessage(error) };
   }
 }
 
@@ -194,22 +240,36 @@ export function extractPlanSteps(planContent: string): string[] {
 }
 
 
-export function handlePlanComplete(
+/**
+ * 投递 complete 后的执行通知（D2：goal 档先 goalInit、后按结果选 steer）。
+ * 成功发 goal steer——「Execute via /goal」只在 goal 真实创建成功时说出；失败发
+ * 含 reason 与恢复动作的降级 steer + warning notify。非 goal 档无 goalInit，按
+ * execMode 组 steer。返回 goalInit 的 outcome（非 goal 档为 undefined）。
+ */
+function deliverExecutionNotice(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
-  state: PlanState,
-  isolation: string,
+  planFilePath: string,
   execMode: string,
-): void {
-  const planFilePath = state.planFilePath;
+): GoalBridgeOutcome | undefined {
+  const outcome = execMode === "goal" ? tryGoalInit(planFilePath, ctx) : undefined;
 
-  // Build mode-specific steer
   const modeMessages: Record<string, string> = {
     subagent: "Execute via subagent-driven development: delegate each task to an independent subagent for parallel execution.",
     goal: "Execute via /goal: set up tracked task decomposition with budget control using the goal extension.",
     "single-agent": "Execute step by step in the current session.",
   };
-  const modeHint = modeMessages[execMode] ?? modeMessages["single-agent"];
+
+  let modeHint: string;
+  if (outcome === undefined) {
+    modeHint = modeMessages[execMode] ?? modeMessages["single-agent"];
+  } else if (outcome.started) {
+    modeHint = modeMessages.goal;
+  } else {
+    modeHint = `Goal execution was not started (${outcome.reason}). ${GOAL_FAILURE_RECOVERY[outcome.reason]} Execute step by step in the current session.`;
+    const detail = outcome.detail ? ` (${outcome.detail})` : "";
+    ctx.ui.notify(`Goal execution was not started (${outcome.reason})${detail}. ${GOAL_FAILURE_RECOVERY[outcome.reason]}`, "warning");
+  }
 
   const executeMessage =
     `Plan approved by user. Plan file: ${planFilePath}\n\n` +
@@ -217,6 +277,28 @@ export function handlePlanComplete(
     `${modeHint}\n\n` +
     `Read the plan file and start implementing.`;
 
+  pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
+  return outcome;
+}
+
+/**
+ * complete 的 isolation 分发（D1 后仅 compact | direct，两档都投递执行通知）。
+ *
+ * 返回值：execMode=goal 且 isolation=direct 时同步返回 goalInit 的 outcome
+ * （executeComplete 写进 result content 与 details）；其余情形返回 undefined——
+ * 非 goal 档无 goalInit，compact 档 goalInit 在 onComplete 回调内执行（goal 状态
+ * entry 须在压缩后的世界里创建，提前到 compact 前有被压缩边界丢弃的风险，时序
+ * 不动——设计 §6.2 D2），该档 result 已返回，失败报告走 steer + notify 通道。
+ */
+export function handlePlanComplete(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  state: PlanState,
+  isolation: string,
+  execMode: string,
+): GoalBridgeOutcome | undefined {
+  const planFilePath = state.planFilePath;
+
   switch (isolation) {
     case "compact": {
       ctx.compact({
@@ -229,8 +311,7 @@ export function handlePlanComplete(
         // 守卫的 stale 文案兜底（D1 降级语义声明的合法形态）。
         onComplete: () => {
           guardStaleCtx(() => {
-            pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
-            tryGoalInit(pi, planFilePath, ctx);
+            deliverExecutionNotice(pi, ctx, planFilePath, execMode);
           }, {
             label: "plan:compact-onComplete",
             onStale: (error) => logger.warn("plan execution notice delivery skipped (stale ctx)", { error: toErrorMessage(error) }),
@@ -239,27 +320,19 @@ export function handlePlanComplete(
         onError: (_error: Error) => {
           guardStaleCtx(() => {
             ctx.ui.notify("Compact failed, continuing without isolation.", "warning");
-            pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
-            tryGoalInit(pi, planFilePath, ctx);
+            deliverExecutionNotice(pi, ctx, planFilePath, execMode);
           }, {
             label: "plan:compact-onError",
             onStale: (error) => logger.warn("plan execution notice delivery skipped (stale ctx)", { error: toErrorMessage(error) }),
           });
         },
       });
-      break;
-    }
-
-    case "tree": {
-      ctx.ui.notify("Use /tree to manually navigate back. Plan file: " + planFilePath, "info");
-      break;
+      return undefined;
     }
 
     case "direct":
     default: {
-      pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
-      tryGoalInit(pi, planFilePath, ctx);
-      break;
+      return deliverExecutionNotice(pi, ctx, planFilePath, execMode);
     }
   }
 }