feat(FN-5438): add manual merge blocker bypass mode for queued tasks

Adds a manual merge blocker mode (FN-5438) that prevents automatic merging and provides a bypass mechanism to resume, wired through the merger, project engine, and task workflow API routes. Includes tests across core, engine route registration, and project engine layers, plus a changeset and documen

Fusion-Task-Id: FN-5438

packages/engine/src/__tests__/manual-merge-bypass.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import type { Task, TaskStore } from "@fusion/core";
+import { aiMergeTask } from "../merger.js";
+
+const sentinel = new Error("sentinel-getSettings");
+
+function createTask(status: Task["status"]): Task {
+  return {
+    id: "FN-5438",
+    title: "Manual merge queued bypass",
+    description: "",
+    column: "in-review",
+    status,
+    paused: false,
+    steps: [],
+    currentStep: 0,
+    log: [],
+    workflowStepResults: [],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    dependencies: [],
+  } as unknown as Task;
+}
+
+function createStore(task: Task): TaskStore {
+  return {
+    getTask: async () => task,
+    getSettings: async () => {
+      throw sentinel;
+    },
+  } as unknown as TaskStore;
+}
+
+describe("aiMergeTask manual queued bypass", () => {
+  it("blocks queued status for auto merge", async () => {
+    const store = createStore(createTask("queued"));
+    await expect(aiMergeTask(store, process.cwd(), "FN-5438")).rejects.toThrow(
+      "Cannot merge FN-5438: task is marked 'queued'",
+    );
+  });
+
+  it("bypasses queued status for manual merge", async () => {
+    const store = createStore(createTask("queued"));
+    await expect(aiMergeTask(store, process.cwd(), "FN-5438", { manual: true })).rejects.toBe(sentinel);
+  });
+});

packages/engine/src/__tests__/project-engine.test.ts

@@ -1127,6 +1127,39 @@ describe("ProjectEngine shutdown merge handling", () => {
   });
 });
 
+describe("ProjectEngine manual merge plumbing", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    const mockStore = createMockStore({ ...baseSettings, autoMerge: true });
+    mockStore.store.getTask.mockResolvedValue({
+      id: "FN-5438",
+      column: "in-review",
+      paused: false,
+      mergeRetries: 0,
+      status: "queued",
+    } as any);
+    mocks.currentStore = mockStore.store;
+  });
+
+  it("passes manual=true to aiMergeTask for onMerge requests", async () => {
+    mocks.aiMergeTask.mockResolvedValue({ merged: true, task: { id: "FN-5438" } } as any);
+
+    const engine = createEngine();
+    await engine.start();
+
+    await engine.onMerge("FN-5438");
+
+    expect(mocks.aiMergeTask).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.any(String),
+      "FN-5438",
+      expect.objectContaining({ manual: true }),
+    );
+
+    await engine.stop();
+  });
+});
+
 describe("ProjectEngine merge queue priority ordering", () => {
   beforeEach(() => {
     vi.clearAllMocks();