feat(FN-1733): add dedicated pause/resume APIs for projects

- Add pauseProject() and resumeProject() methods to ProjectEngineManager
- Wire pause and resume routes to engineManager with proper error handling
- Update frontend useProjectActions hook to use dedicated pause/resume APIs
- Add comprehensive tests for pause/resume in ProjectEngineManager
- Add route tests for project pause/resume with engineManager mocks
- Fix mock stubs for getProject/updateProject/updateProjectHealth

packages/dashboard/app/hooks/__tests__/useProjectActions.test.ts

@@ -5,10 +5,14 @@ import * as api from "../../api";
 import type { ProjectInfo } from "../../api";
 
 vi.mock("../../api", () => ({
+  pauseProject: vi.fn(),
+  resumeProject: vi.fn(),
   updateProject: vi.fn(),
   unregisterProject: vi.fn(),
 }));
 
+const mockPauseProject = vi.mocked(api.pauseProject);
+const mockResumeProject = vi.mocked(api.resumeProject);
 const mockUpdateProject = vi.mocked(api.updateProject);
 const mockUnregisterProject = vi.mocked(api.unregisterProject);
 
@@ -43,6 +47,8 @@ function createOptions(overrides: Partial<Parameters<typeof useProjectActions>[0
 describe("useProjectActions", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    mockPauseProject.mockResolvedValue(PROJECT);
+    mockResumeProject.mockResolvedValue(PROJECT);
     mockUpdateProject.mockResolvedValue(PROJECT);
     mockUnregisterProject.mockResolvedValue(undefined);
   });
@@ -86,7 +92,7 @@ describe("useProjectActions", () => {
     expect(options.refreshProjects).toHaveBeenCalledTimes(1);
   });
 
-  it("handlePauseProject calls updateProject and shows success toast", async () => {
+  it("handlePauseProject calls pauseProject and shows success toast", async () => {
     const options = createOptions();
     const { result } = renderHook(() => useProjectActions(options));
 
@@ -94,12 +100,12 @@ describe("useProjectActions", () => {
       await result.current.handlePauseProject(PROJECT);
     });
 
-    expect(mockUpdateProject).toHaveBeenCalledWith(PROJECT.id, { status: "paused" });
+    expect(mockPauseProject).toHaveBeenCalledWith(PROJECT.id);
     expect(options.addToast).toHaveBeenCalledWith("Project Demo paused", "success");
     expect(options.refreshProjects).toHaveBeenCalledTimes(1);
   });
 
-  it("handleResumeProject calls updateProject and shows success toast", async () => {
+  it("handleResumeProject calls resumeProject and shows success toast", async () => {
     const options = createOptions();
     const { result } = renderHook(() => useProjectActions(options));
 
@@ -107,7 +113,7 @@ describe("useProjectActions", () => {
       await result.current.handleResumeProject(PROJECT);
     });
 
-    expect(mockUpdateProject).toHaveBeenCalledWith(PROJECT.id, { status: "active" });
+    expect(mockResumeProject).toHaveBeenCalledWith(PROJECT.id);
     expect(options.addToast).toHaveBeenCalledWith("Project Demo resumed", "success");
     expect(options.refreshProjects).toHaveBeenCalledTimes(1);
   });

packages/dashboard/app/hooks/useProjectActions.ts

@@ -1,5 +1,5 @@
 import { useCallback } from "react";
-import { updateProject, unregisterProject } from "../api";
+import { pauseProject, resumeProject, unregisterProject } from "../api";
 import type { ProjectInfo } from "../api";
 import type { ViewMode } from "./useViewState";
 import type { ToastType } from "./useToast";
@@ -81,7 +81,7 @@ export function useProjectActions(options: UseProjectActionsOptions): UseProject
 
   const handlePauseProject = useCallback(async (project: ProjectInfo) => {
     try {
-      await updateProject(project.id, { status: "paused" });
+      await pauseProject(project.id);
       addToast(`Project ${project.name} paused`, "success");
       await refreshProjects();
     } catch {
@@ -91,7 +91,7 @@ export function useProjectActions(options: UseProjectActionsOptions): UseProject
 
   const handleResumeProject = useCallback(async (project: ProjectInfo) => {
     try {
-      await updateProject(project.id, { status: "active" });
+      await resumeProject(project.id);
       addToast(`Project ${project.name} resumed`, "success");
       await refreshProjects();
     } catch {

packages/dashboard/src/__tests__/project-pause-resume-routes.test.ts

@@ -0,0 +1,192 @@
+// @vitest-environment node
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import express from "express";
+import { createApiRoutes } from "../routes.js";
+import { request } from "../test-request.js";
+import type { TaskStore } from "@fusion/core";
+
+// Mock @fusion/core
+const mockCentralListProjects = vi.fn().mockResolvedValue([]);
+const mockCentralInit = vi.fn().mockResolvedValue(undefined);
+const mockCentralClose = vi.fn().mockResolvedValue(undefined);
+const mockCentralReconcileProjectStatuses = vi.fn().mockResolvedValue(undefined);
+const mockCentralGetProject = vi.fn().mockResolvedValue(null);
+const mockCentralUpdateProject = vi.fn().mockResolvedValue(undefined);
+const mockCentralUpdateProjectHealth = vi.fn().mockResolvedValue(undefined);
+
+vi.mock("@fusion/core", async () => {
+  const actual = await vi.importActual<typeof import("@fusion/core")>("@fusion/core");
+  return {
+    ...actual,
+    isGhAuthenticated: vi.fn(),
+    CentralCore: vi.fn().mockImplementation(() => ({
+      init: mockCentralInit,
+      close: mockCentralClose,
+      listProjects: mockCentralListProjects,
+      reconcileProjectStatuses: mockCentralReconcileProjectStatuses,
+      getProject: mockCentralGetProject,
+      updateProject: mockCentralUpdateProject,
+      updateProjectHealth: mockCentralUpdateProjectHealth,
+    })),
+  };
+});
+
+vi.mock("@fusion/engine", () => ({
+  createKbAgent: vi.fn(async () => ({
+    session: {
+      state: { messages: [] as Array<{ role: string; content: string }> },
+      prompt: vi.fn(async function (this: { state?: { messages?: Array<{ role: string; content: string }> } }, message: string) {
+        const messages = this.state?.messages ?? [];
+        messages.push({ role: "user", content: message });
+        messages.push({ role: "assistant", content: JSON.stringify({ subtasks: [] }) });
+      }),
+      dispose: vi.fn(),
+    },
+  })),
+  AgentReflectionService: class {
+    async generateReflection(): Promise<never> { throw new Error("Reflection service unavailable"); }
+    async buildReflectionContext(): Promise<never> { throw new Error("Reflection service unavailable"); }
+  },
+}));
+
+function createMockStore(overrides: Partial<TaskStore> = {}): TaskStore {
+  return {
+    getTask: vi.fn(),
+    listTasks: vi.fn().mockResolvedValue([]),
+    searchTasks: vi.fn().mockResolvedValue([]),
+    createTask: vi.fn(),
+    moveTask: vi.fn(),
+    updateTask: vi.fn(),
+    deleteTask: vi.fn(),
+    mergeTask: vi.fn(),
+    getTaskByBranch: vi.fn(),
+    getTaskByWorktree: vi.fn(),
+    checkoutTask: vi.fn(),
+    releaseTask: vi.fn(),
+    listAgents: vi.fn().mockResolvedValue([]),
+    createAgent: vi.fn(),
+    updateAgent: vi.fn(),
+    deleteAgent: vi.fn(),
+    getAgent: vi.fn(),
+    logAgentEvent: vi.fn(),
+    logEntry: vi.fn(),
+    addComment: vi.fn(),
+    getComments: vi.fn().mockResolvedValue([]),
+    updateSettings: vi.fn(),
+    getSettings: vi.fn().mockResolvedValue({}),
+    getRootDir: vi.fn().mockReturnValue("/tmp/test"),
+    getFusionDir: vi.fn().mockReturnValue("/tmp/test/.fusion"),
+    getPluginStore: vi.fn().mockReturnValue({
+      listPlugins: vi.fn().mockResolvedValue([]),
+      getPlugin: vi.fn(),
+      registerPlugin: vi.fn(),
+      updatePlugin: vi.fn(),
+      unregisterPlugin: vi.fn(),
+    }),
+    getMissionStore: vi.fn().mockReturnValue({
+      listMissions: vi.fn().mockResolvedValue([]),
+    }),
+    getRoutineStore: vi.fn().mockReturnValue({
+      listRoutines: vi.fn().mockResolvedValue([]),
+    }),
+    getAutomationStore: vi.fn().mockReturnValue({
+      listScheduledTasks: vi.fn().mockResolvedValue([]),
+    }),
+    ...overrides,
+  } as unknown as TaskStore;
+}
+
+const mockProjectData = {
+  id: "proj_test",
+  name: "Test Project",
+  path: "/tmp/test",
+  status: "active",
+  isolationMode: "in-process" as const,
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+};
+
+describe("Project pause/resume routes", () => {
+  let store: TaskStore;
+
+  const mockEngineManager = {
+    pauseProject: vi.fn().mockResolvedValue(undefined),
+    resumeProject: vi.fn().mockResolvedValue(undefined),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    store = createMockStore();
+    // Set up mock return values
+    mockCentralGetProject.mockResolvedValue(mockProjectData);
+    mockCentralUpdateProject.mockResolvedValue(undefined);
+    mockCentralUpdateProjectHealth.mockResolvedValue(undefined);
+    mockCentralInit.mockResolvedValue(undefined);
+    mockCentralClose.mockResolvedValue(undefined);
+  });
+
+  describe("with engineManager", () => {
+    function buildApp() {
+      const app = express();
+      app.use(express.json());
+      app.use("/api", createApiRoutes(store, { engineManager: mockEngineManager as any }));
+      return app;
+    }
+
+    it("POST /projects/:id/pause — calls engineManager.pauseProject and returns updated project", async () => {
+      const pausedProject = { ...mockProjectData, status: "paused" };
+      mockCentralGetProject.mockResolvedValue(pausedProject);
+
+      const res = await request(buildApp(), "POST", "/api/projects/proj_test/pause");
+
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe("paused");
+      expect(mockEngineManager.pauseProject).toHaveBeenCalledWith("proj_test");
+    });
+
+    it("POST /projects/:id/resume — calls engineManager.resumeProject and returns updated project", async () => {
+      const activeProject = { ...mockProjectData, status: "active" };
+      mockCentralGetProject.mockResolvedValue(activeProject);
+
+      const res = await request(buildApp(), "POST", "/api/projects/proj_test/resume");
+
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe("active");
+      expect(mockEngineManager.resumeProject).toHaveBeenCalledWith("proj_test");
+    });
+  });
+
+  describe("without engineManager (dev mode fallback)", () => {
+    function buildApp() {
+      const app = express();
+      app.use(express.json());
+      app.use("/api", createApiRoutes(store));
+      return app;
+    }
+
+    it("POST /projects/:id/pause — falls back to CentralCore when engineManager is absent", async () => {
+      const pausedProject = { ...mockProjectData, status: "paused" };
+      mockCentralGetProject.mockResolvedValue(pausedProject);
+
+      const res = await request(buildApp(), "POST", "/api/projects/proj_test/pause");
+
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe("paused");
+      expect(mockCentralUpdateProject).toHaveBeenCalledWith("proj_test", { status: "paused" });
+      expect(mockCentralUpdateProjectHealth).toHaveBeenCalledWith("proj_test", { status: "paused" });
+    });
+
+    it("POST /projects/:id/resume — falls back to CentralCore when engineManager is absent", async () => {
+      const activeProject = { ...mockProjectData, status: "active" };
+      mockCentralGetProject.mockResolvedValue(activeProject);
+
+      const res = await request(buildApp(), "POST", "/api/projects/proj_test/resume");
+
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe("active");
+      expect(mockCentralUpdateProject).toHaveBeenCalledWith("proj_test", { status: "active" });
+      expect(mockCentralUpdateProjectHealth).toHaveBeenCalledWith("proj_test", { status: "active" });
+    });
+  });
+});

packages/dashboard/src/routes.test.ts

@@ -14262,3 +14262,6 @@ describe("POST /api/ai/refine-text with projectId scoping", () => {
     expect(res.body.error).toContain("not exceed 2000 characters");
   });
 });
+
+// Note: Project pause/resume route tests are in src/__tests__/project-pause-resume-routes.test.ts
+// to avoid test isolation issues with vi.restoreAllMocks() from other tests in routes.test.ts

packages/dashboard/src/routes.ts

@@ -13290,14 +13290,32 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
    */
   router.post("/projects/:id/pause", async (req, res) => {
     try {
-      const { CentralCore } = await import("@fusion/core");
-      const central = new CentralCore();
+      const projectId = req.params.id;
+
+      // Use engineManager if available (production mode)
+      if (options?.engineManager) {
+        await options.engineManager.pauseProject(projectId);
+      } else {
+        // Fallback: update CentralCore directly (dev mode)
+        const { CentralCore } = await import("@fusion/core");
+        const central = new CentralCore();
+        await central.init();
+        await central.updateProject(projectId, { status: "paused" });
+        await central.updateProjectHealth(projectId, { status: "paused" });
+        await central.close();
+      }
+
+      // Fetch and return the updated project
+      const { CentralCore: CentralCore2 } = await import("@fusion/core");
+      const central = new CentralCore2();
       await central.init();
-      
-      const project = await central.updateProject(req.params.id, { status: "paused" });
-      await central.updateProjectHealth(req.params.id, { status: "paused" });
+      const project = await central.getProject(projectId);
       await central.close();
-      
+
+      if (!project) {
+        throw new ApiError(404, `Project ${projectId} not found`);
+      }
+
       res.json(project);
     } catch (err: any) {
       if (err instanceof ApiError) {
@@ -13314,14 +13332,32 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
    */
   router.post("/projects/:id/resume", async (req, res) => {
     try {
-      const { CentralCore } = await import("@fusion/core");
-      const central = new CentralCore();
+      const projectId = req.params.id;
+
+      // Use engineManager if available (production mode)
+      if (options?.engineManager) {
+        await options.engineManager.resumeProject(projectId);
+      } else {
+        // Fallback: update CentralCore directly (dev mode)
+        const { CentralCore } = await import("@fusion/core");
+        const central = new CentralCore();
+        await central.init();
+        await central.updateProject(projectId, { status: "active" });
+        await central.updateProjectHealth(projectId, { status: "active" });
+        await central.close();
+      }
+
+      // Fetch and return the updated project
+      const { CentralCore: CentralCore2 } = await import("@fusion/core");
+      const central = new CentralCore2();
       await central.init();
-      
-      const project = await central.updateProject(req.params.id, { status: "active" });
-      await central.updateProjectHealth(req.params.id, { status: "active" });
+      const project = await central.getProject(projectId);
       await central.close();
-      
+
+      if (!project) {
+        throw new ApiError(404, `Project ${projectId} not found`);
+      }
+
       res.json(project);
     } catch (err: any) {
       if (err instanceof ApiError) {

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

@@ -38,6 +38,8 @@ function createMockCentralCore(projects: RegisteredProject[]): CentralCore {
     getProjectByPath: vi.fn().mockImplementation((path: string) =>
       Promise.resolve(projects.find((p) => p.path === path) ?? null),
     ),
+    updateProject: vi.fn().mockResolvedValue(undefined),
+    updateProjectHealth: vi.fn().mockResolvedValue(undefined),
   } as unknown as CentralCore;
 }
 
@@ -291,6 +293,100 @@ describe("ProjectEngineManager", () => {
     });
   });
 
+  describe("pauseProject", () => {
+    it("calls updateProject and updateProjectHealth with 'paused'", async () => {
+      const manager = new ProjectEngineManager(centralCore);
+      await manager.pauseProject("proj_aaa");
+
+      expect(centralCore.updateProject).toHaveBeenCalledWith("proj_aaa", { status: "paused" });
+      expect(centralCore.updateProjectHealth).toHaveBeenCalledWith("proj_aaa", { status: "paused" });
+    });
+
+    it("stops engine if running and removes it from getEngine", async () => {
+      const manager = new ProjectEngineManager(centralCore);
+      const engine = await manager.ensureEngine("proj_aaa");
+
+      await manager.pauseProject("proj_aaa");
+
+      expect(engine.stop).toHaveBeenCalledOnce();
+      expect(manager.getEngine("proj_aaa")).toBeUndefined();
+    });
+
+    it("removes from starting set to prevent stalled starts from completing", async () => {
+      const manager = new ProjectEngineManager(centralCore);
+
+      // Start an engine (await it to ensure it's in the starting map)
+      const enginePromise = manager.ensureEngine("proj_aaa");
+      
+      // Wait for the engine to be added to starting set
+      await vi.waitFor(() => {
+        expect(manager.has("proj_aaa")).toBe(true);
+      });
+      
+      // Now pause - this should remove from starting set
+      await manager.pauseProject("proj_aaa");
+
+      // The engine should not be running
+      expect(manager.getEngine("proj_aaa")).toBeUndefined();
+      expect(manager.has("proj_aaa")).toBe(false);
+
+      // The pending promise should resolve but engine should not exist
+      await enginePromise.catch(() => {});
+    });
+
+    it("throws if manager is stopped", async () => {
+      const manager = new ProjectEngineManager(centralCore);
+      await manager.stopAll();
+
+      await expect(manager.pauseProject("proj_aaa")).rejects.toThrow(
+        "ProjectEngineManager is stopped",
+      );
+    });
+  });
+
+  describe("resumeProject", () => {
+    it("calls updateProject and updateProjectHealth with 'active'", async () => {
+      const manager = new ProjectEngineManager(centralCore);
+      await manager.resumeProject("proj_aaa");
+
+      expect(centralCore.updateProject).toHaveBeenCalledWith("proj_aaa", { status: "active" });
+      expect(centralCore.updateProjectHealth).toHaveBeenCalledWith("proj_aaa", { status: "active" });
+    });
+
+    it("starts engine via ensureEngine", async () => {
+      const manager = new ProjectEngineManager(centralCore);
+      await manager.resumeProject("proj_aaa");
+
+      expect(manager.getEngine("proj_aaa")).toBeDefined();
+      expect(ProjectEngine).toHaveBeenCalledTimes(1);
+    });
+
+    it("throws if manager is stopped", async () => {
+      const manager = new ProjectEngineManager(centralCore);
+      await manager.stopAll();
+
+      await expect(manager.resumeProject("proj_aaa")).rejects.toThrow(
+        "ProjectEngineManager is stopped",
+      );
+    });
+  });
+
+  describe("ensureEngine with paused projects", () => {
+    it("rejects when project status is 'paused'", async () => {
+      const manager = new ProjectEngineManager(centralCore);
+
+      // Mock getProject to return a paused project
+      (centralCore.getProject as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+        ...projectA,
+        status: "paused",
+      });
+
+      await expect(manager.ensureEngine("proj_aaa")).rejects.toThrow(
+        "Project proj_aaa is paused",
+      );
+    });
+  });
+
   describe("onProjectAccessed", () => {
     it("starts engine in background for unknown project", async () => {
       const manager = new ProjectEngineManager(centralCore);
@@ -392,6 +488,41 @@ describe("ProjectEngineManager", () => {
       manager.stopReconciliation();
     });
 
+    it("skips paused projects during reconciliation", async () => {
+      const manager = new ProjectEngineManager(centralCore);
+
+      // Make projectA paused
+      const pausedProjectA = { ...projectA, status: "paused" as const };
+      
+      // Mock getProject to return paused status for projectA
+      (centralCore.getProject as ReturnType<typeof vi.fn>).mockImplementation((id: string) => {
+        if (id === "proj_aaa") {
+          return Promise.resolve(pausedProjectA);
+        }
+        return Promise.resolve([projectA, projectB, projectC].find((p) => p.id === id) ?? null);
+      });
+      
+      // Mock listProjects to return all projects including the paused one
+      (centralCore.listProjects as ReturnType<typeof vi.fn>).mockResolvedValueOnce([
+        pausedProjectA,
+        projectB,
+        projectC,
+      ]);
+
+      manager.startReconciliation(1000);
+
+      // Advance time to trigger reconciliation
+      await vi.advanceTimersByTimeAsync(1000);
+
+      // projectA should NOT have an engine (it's paused)
+      expect(manager.getEngine("proj_aaa")).toBeUndefined();
+      // projectB and projectC should have engines (they're active)
+      expect(manager.getEngine("proj_bbb")).toBeDefined();
+      expect(manager.getEngine("proj_ccc")).toBeDefined();
+
+      manager.stopReconciliation();
+    });
+
     it("retries failed project starts on subsequent reconciliation ticks", async () => {
       // Track how many times start() is called to fail only the FIRST set
       let startCallCount = 0;

packages/engine/src/project-engine-manager.ts

@@ -110,6 +110,49 @@ export class ProjectEngineManager {
     return this.engines.has(projectId) || this.starting.has(projectId);
   }
 
+  // ── Pause / Resume ────────────────────────────────────────────────────
+
+  /**
+   * Pause a project: update its status in CentralCore and stop its engine.
+   * This prevents the reconciliation loop from restarting the engine.
+   */
+  async pauseProject(projectId: string): Promise<void> {
+    if (this.stopped) throw new Error("ProjectEngineManager is stopped");
+
+    runtimeLog.log(`Pausing project ${projectId}`);
+
+    // Update CentralCore status
+    await this.centralCore.updateProject(projectId, { status: "paused" });
+    await this.centralCore.updateProjectHealth(projectId, { status: "paused" });
+
+    // Stop the engine if running
+    const engine = this.engines.get(projectId);
+    if (engine) {
+      await engine.stop();
+      this.engines.delete(projectId);
+      runtimeLog.log(`Stopped engine for paused project ${projectId}`);
+    }
+
+    // Remove from starting set to prevent a stalled start from completing
+    this.starting.delete(projectId);
+  }
+
+  /**
+   * Resume a paused project: update its status in CentralCore and start its engine.
+   */
+  async resumeProject(projectId: string): Promise<void> {
+    if (this.stopped) throw new Error("ProjectEngineManager is stopped");
+
+    runtimeLog.log(`Resuming project ${projectId}`);
+
+    // Update CentralCore status
+    await this.centralCore.updateProject(projectId, { status: "active" });
+    await this.centralCore.updateProjectHealth(projectId, { status: "active" });
+
+    // Start the engine
+    await this.ensureEngine(projectId);
+  }
+
   // ── Lifecycle ──
 
   /**
@@ -123,6 +166,12 @@ export class ProjectEngineManager {
   ): Promise<ProjectEngine> {
     if (this.stopped) throw new Error("ProjectEngineManager is stopped");
 
+    // Check if the project is paused before starting
+    const project = await this.centralCore.getProject(projectId);
+    if (project && (project.status as string) === "paused") {
+      throw new Error(`Project ${projectId} is paused`);
+    }
+
     const existing = this.engines.get(projectId);
     if (existing) return existing;
 
@@ -283,8 +332,11 @@ export class ProjectEngineManager {
       const projects = await this.centralCore.listProjects();
       if (projects.length === 0) return;
 
+      // Filter out paused projects — they should not have engines started
+      const activeProjects = projects.filter((p) => (p.status as string) !== "paused");
+
       // Find projects that don't have running or pending engines
-      const missing = projects.filter((p) => !this.has(p.id));
+      const missing = activeProjects.filter((p) => !this.has(p.id));
       if (missing.length === 0) return;
 
       runtimeLog.log(
@@ -318,6 +370,11 @@ export class ProjectEngineManager {
       throw new Error(`Project ${projectId} not found in CentralCore`);
     }
 
+    // Prevent starting engines for paused projects
+    if ((project.status as string) === "paused") {
+      throw new Error(`Project ${projectId} is paused`);
+    }
+
     const runtimeConfig = this.buildRuntimeConfig(project);
     const engineOptions = this.buildEngineOptions(project, overrides);