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();

packages/engine/src/merger.ts

@@ -5232,6 +5232,12 @@ export async function findWorktreeUser(
 }
 
 export interface MergerOptions {
+  /**
+   * When true, skip scheduler-transient status blockers (`queued`).
+   * Hard guards (paused, column, incomplete steps, in-flight merge,
+   * failed pre-merge workflow steps) still apply. Set by `ProjectEngine.onMerge`.
+   */
+  manual?: boolean;
   /** Called with agent text output */
   onAgentText?: (delta: string) => void;
   /** Called with agent tool usage */
@@ -6720,7 +6726,7 @@ export async function aiMergeTask(
       branchDeleted: false,
     };
   }
-  const mergeBlocker = getTaskMergeBlocker(task);
+  const mergeBlocker = getTaskMergeBlocker(task, { manual: options.manual === true });
   if (mergeBlocker) {
     throw new Error(`Cannot merge ${taskId}: ${mergeBlocker}`);
   }

packages/engine/src/project-engine.ts

@@ -1531,6 +1531,7 @@ export class ProjectEngine {
               this.activeMergeTaskId = taskId;
               this.mergeAbortController = new AbortController();
               return aiMergeTask(store, cwd, taskId, {
+                manual: !!manualResolver,
                 pool,
                 usageLimitPauser,
                 agentStore,