fix(FN-branch-group): add engine.promoteBranchGroup bridge method (U4)

The dashboard promote route called engine.promoteBranchGroup(groupId) as a
method that never existed — only a standalone coordinator function did — so
the route was dead, masked by a vi.fn mock in the test. Add the real method on
ProjectEngine delegating to the coordinator (resolving store/cwd/settings like
attemptBranchGroupPromotion), and de-mock the test so it now fails if the
method goes missing. No PR-creation behavior yet (U5).

packages/engine/src/__tests__/group-merge-coordinator.test.ts

@@ -11,6 +11,7 @@ import {
   promoteBranchGroup,
   resolveBranchGroupMergeRouting,
 } from "../group-merge-coordinator.js";
+import { ProjectEngine } from "../project-engine.js";
 
 const dirs: string[] = [];
 
@@ -336,6 +337,102 @@ describe("promoteBranchGroup", () => {
   });
 });
 
+describe("ProjectEngine.promoteBranchGroup (U4 bridge method)", () => {
+  // The dashboard promote route calls engine.promoteBranchGroup AS A METHOD.
+  // These tests invoke the REAL method body bound to a minimal engine-shaped
+  // context, proving it resolves store/rootDir/settings and delegates to the
+  // standalone coordinator — without standing up a full ProjectEngine.
+  const realPromote = ProjectEngine.prototype.promoteBranchGroup;
+
+  function makeGroup(overrides?: Partial<any>) {
+    return {
+      id: "BG-1",
+      sourceType: "planning",
+      sourceId: "planning:x",
+      branchName: "fusion/groups/planning-x",
+      autoMerge: true,
+      prState: "none",
+      status: "open",
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      ...overrides,
+    };
+  }
+
+  const landedMember = (id: string, branchName: string) => ({
+    id,
+    column: "done" as const,
+    mergeDetails: {
+      mergeConfirmed: true,
+      mergeTargetSource: "branch-group-integration",
+      mergeTargetBranch: branchName,
+    },
+  });
+
+  function makeEngineContext(rootDir: string, store: unknown, settings: Record<string, unknown>) {
+    const getSettingsCalls = { count: 0 };
+    const fullStore = {
+      ...(store as Record<string, unknown>),
+      getSettings: async () => {
+        getSettingsCalls.count += 1;
+        return settings;
+      },
+      recordRunAuditEvent: async () => {},
+    };
+    return {
+      context: {
+        runtime: { getTaskStore: () => fullStore },
+        config: { workingDirectory: rootDir },
+      },
+      getSettingsCalls,
+    };
+  }
+
+  it("resolves settings via the store and delegates to the coordinator (promotes a complete group)", async () => {
+    const rootDir = makeRepo();
+    execSync("git checkout -b fusion/groups/planning-x", { cwd: rootDir });
+    execSync("echo promoted > group.txt", { cwd: rootDir, shell: "/bin/bash" });
+    execSync("git add group.txt && git commit -m group", { cwd: rootDir, shell: "/bin/bash" });
+    execSync("git checkout main", { cwd: rootDir });
+
+    let group = makeGroup();
+    const { context, getSettingsCalls } = makeEngineContext(rootDir, {
+      getBranchGroup: () => group,
+      listTasksByBranchGroup: async () => [landedMember("FN-A", group.branchName)],
+      updateBranchGroup: (_id: string, patch: Partial<typeof group>) => {
+        group = { ...group, ...patch };
+        return group;
+      },
+    }, { autoMerge: true, globalPause: false, enginePaused: false, mergeStrategy: "direct", baseBranch: "main" });
+
+    const result = await realPromote.call(context as any, "BG-1");
+
+    expect(getSettingsCalls.count).toBe(1);
+    expect(result.promoted).toBe(true);
+    expect(result.reason).toBe("promoted");
+    expect(group.status).toBe("finalized");
+    expect(execSync("git show main:group.txt", { cwd: rootDir, encoding: "utf8" })).toContain("promoted");
+  });
+
+  it("rejects an incomplete group at the coordinator completion gate", async () => {
+    const rootDir = makeRepo();
+    const group = makeGroup();
+    const { context } = makeEngineContext(rootDir, {
+      getBranchGroup: () => group,
+      listTasksByBranchGroup: async () => [{ id: "FN-A", column: "todo" }],
+      updateBranchGroup: () => {
+        throw new Error("should not update an incomplete group");
+      },
+    }, { autoMerge: true, globalPause: false, enginePaused: false, mergeStrategy: "direct", baseBranch: "main" });
+
+    const result = await realPromote.call(context as any, "BG-1");
+
+    expect(result.reason).toBe("incomplete");
+    expect(result.promoted).toBe(false);
+    expect(() => execSync("git show main:group.txt", { cwd: rootDir })).toThrow();
+  });
+});
+
 describe("resolveBranchGroupMergeRouting", () => {
   it("returns null for non-shared tasks", async () => {
     const routing = await resolveBranchGroupMergeRouting({

packages/engine/src/project-engine.ts

@@ -27,7 +27,7 @@ import { CronRunner, createAiPromptExecutor } from "./cron-runner.js";
 import type { RoutineRunner } from "./routine-runner.js";
 import { aiMergeTask, sweepStaleAutostashes, VerificationError } from "./merger.js";
 import { runAiMerge } from "./merger-ai.js";
-import { promoteBranchGroup } from "./group-merge-coordinator.js";
+import { promoteBranchGroup, type BranchGroupPromotionResult } from "./group-merge-coordinator.js";
 import { PRIORITY_MERGE } from "./concurrency.js";
 import { runtimeLog } from "./logger.js";
 import type { HeartbeatTriggerScheduler } from "./agent-heartbeat.js";
@@ -924,6 +924,45 @@ export class ProjectEngine {
     return this.internalEnqueueMerge(taskId);
   }
 
+  /**
+   * Promote a shared branch group: merge the group branch into the integration
+   * branch and reconcile `prState` (completion-gated, idempotent).
+   *
+   * This is the single engine bridge method (KTD5) that the dashboard promote
+   * route reaches via the `promoteBranchGroup` option callback in
+   * `register-integrated-routers.ts`. It resolves the same store / rootDir /
+   * settings context the internal auto-promotion path (`attemptBranchGroupPromotion`)
+   * uses and delegates to the standalone coordinator function — no logic is
+   * duplicated here.
+   */
+  async promoteBranchGroup(groupId: string): Promise<BranchGroupPromotionResult> {
+    const store = this.runtime.getTaskStore();
+    const cwd = this.config.workingDirectory;
+    const settings = await store.getSettings();
+    const promotionSettings = {
+      autoMerge: settings.autoMerge,
+      globalPause: settings.globalPause,
+      enginePaused: settings.enginePaused,
+      mergeStrategy: settings.mergeStrategy,
+      integrationBranch: settings.integrationBranch,
+      baseBranch: settings.baseBranch,
+    };
+    return await promoteBranchGroup({
+      store,
+      rootDir: cwd,
+      groupId,
+      settings: promotionSettings,
+      recordAudit: async (event) => {
+        await store.recordRunAuditEvent({
+          domain: event.domain as any,
+          mutationType: event.mutationType,
+          target: event.target,
+          metadata: event.metadata,
+        } as any);
+      },
+    });
+  }
+
   /**
    * Perform an AI-powered merge for a task, serialized through the merge queue.
    * This is the manual "merge now" path — it shares the same queue as auto-merge