feat(KB-157): add soft-pause (enginePaused) alongside hard-stop (globalPause)

- Add enginePaused field to Settings type with soft-pause semantics (drain queue, don't kill agents)
- Gate scheduler, triage, auto-merge, and periodic merge retry on enginePaused
- Add Pause and Stop buttons to dashboard Header replacing single toggle
- Wire enginePaused state through App with optimistic toggle and unpause resume logic
- Add tests for scheduler, triage, dashboard CLI, Header, and App covering pause behavior

packages/cli/src/commands/__tests__/dashboard.test.ts

@@ -76,6 +76,8 @@ vi.mock("@kb/engine", async (importOriginal) => {
       stop: vi.fn(),
     })),
     aiMergeTask: vi.fn().mockResolvedValue({ merged: true }),
+    scanIdleWorktrees: vi.fn().mockResolvedValue([]),
+    cleanupOrphanedWorktrees: vi.fn().mockResolvedValue(0),
   };
 });
 

packages/cli/src/commands/dashboard.test.ts

@@ -86,6 +86,8 @@ vi.mock("@kb/engine", async (importOriginal) => {
       stop: vi.fn(),
     })),
     aiMergeTask: vi.fn().mockImplementation(() => Promise.resolve({ merged: true })),
+    scanIdleWorktrees: vi.fn().mockResolvedValue([]),
+    cleanupOrphanedWorktrees: vi.fn().mockResolvedValue(0),
   };
 });
 
@@ -456,3 +458,116 @@ describe("runDashboard — port fallback on EADDRINUSE", () => {
     );
   });
 });
+
+describe("runDashboard — enginePaused (soft pause)", () => {
+  let mockStore: ReturnType<typeof makeMockStore>;
+
+  beforeEach(async () => {
+    capturedExecutorOpts = undefined;
+    vi.clearAllMocks();
+    mockStore = makeMockStore();
+    const { TaskStore } = await import("@kb/core");
+    (TaskStore as ReturnType<typeof vi.fn>).mockImplementation(() => mockStore);
+    const engine = await import("@kb/engine");
+    (engine.aiMergeTask as ReturnType<typeof vi.fn>).mockImplementation(() =>
+      Promise.resolve({ merged: true }),
+    );
+    (engine.TaskExecutor as unknown as ReturnType<typeof vi.fn>).mockImplementation(
+      (_store: unknown, _cwd: unknown, opts: unknown) => {
+        capturedExecutorOpts = opts as Record<string, unknown>;
+        return { resumeOrphaned: vi.fn().mockResolvedValue(undefined) };
+      },
+    );
+  });
+
+  it("does not enqueue tasks for auto-merge when enginePaused on task:moved", async () => {
+    mockStore.getSettings.mockResolvedValue({
+      maxConcurrent: 1,
+      maxWorktrees: 2,
+      autoMerge: true,
+      pollIntervalMs: 60_000,
+      enginePaused: true,
+    });
+
+    await runDashboard(0, { open: false });
+
+    const { aiMergeTask } = await import("@kb/engine");
+
+    // Emit task:moved
+    mockStore.emit("task:moved", {
+      task: { id: "KB-EP1", column: "in-review", paused: false },
+      from: "in-progress",
+      to: "in-review",
+    });
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(aiMergeTask).not.toHaveBeenCalled();
+  });
+
+  it("calls executor.resumeOrphaned() when enginePaused transitions true → false", async () => {
+    const { TaskExecutor } = await import("@kb/engine");
+    const resumeOrphaned = vi.fn().mockResolvedValue(undefined);
+    (TaskExecutor as unknown as ReturnType<typeof vi.fn>).mockImplementation(
+      (_store: unknown, _cwd: unknown, opts: unknown) => {
+        capturedExecutorOpts = opts as Record<string, unknown>;
+        return { resumeOrphaned };
+      },
+    );
+
+    await runDashboard(0, { open: false });
+
+    // Clear the startup call
+    resumeOrphaned.mockClear();
+
+    // Trigger engine unpause event
+    mockStore.emit("settings:updated", {
+      settings: { enginePaused: false, maxConcurrent: 1, autoMerge: false },
+      previous: { enginePaused: true },
+    });
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(resumeOrphaned).toHaveBeenCalled();
+  });
+
+  it("sweeps merge queue on engine unpause when autoMerge is enabled", async () => {
+    mockStore.getSettings.mockResolvedValue({
+      maxConcurrent: 1,
+      maxWorktrees: 2,
+      autoMerge: true,
+      pollIntervalMs: 60_000,
+      enginePaused: false,
+      globalPause: false,
+    });
+    mockStore.listTasks.mockResolvedValue([
+      { id: "KB-EP2", column: "in-review", paused: false },
+    ]);
+    mockStore.getTask = vi.fn().mockImplementation(async (id: string) => ({
+      id,
+      column: "in-review",
+      paused: false,
+    }));
+
+    const { aiMergeTask } = await import("@kb/engine");
+    (aiMergeTask as ReturnType<typeof vi.fn>).mockImplementation(() =>
+      Promise.resolve({ merged: true }),
+    );
+
+    await runDashboard(0, { open: false });
+
+    (aiMergeTask as ReturnType<typeof vi.fn>).mockClear();
+
+    mockStore.emit("settings:updated", {
+      settings: { enginePaused: false, maxConcurrent: 1, autoMerge: true },
+      previous: { enginePaused: true },
+    });
+
+    await new Promise((r) => setTimeout(r, 200));
+
+    const mergedIds = (aiMergeTask as ReturnType<typeof vi.fn>).mock.calls.map(
+      (call: any[]) => call[2],
+    );
+    expect(mergedIds).toContain("KB-EP2");
+  });
+});

packages/cli/src/commands/dashboard.ts

@@ -142,8 +142,8 @@ export async function runDashboard(port: number, opts: { open?: boolean } = {})
         try {
           // Re-check autoMerge and globalPause before each merge (setting may have been toggled)
           const settings = await store.getSettings();
-          if (settings.globalPause) {
-            console.log(`[auto-merge] Skipping ${taskId} — global pause active`);
+          if (settings.globalPause || settings.enginePaused) {
+            console.log(`[auto-merge] Skipping ${taskId} — ${settings.globalPause ? "global pause" : "engine paused"} active`);
             continue;
           }
           if (!settings.autoMerge) {
@@ -180,7 +180,7 @@ export async function runDashboard(port: number, opts: { open?: boolean } = {})
     if (task.paused) return;
     try {
       const settings = await store.getSettings();
-      if (settings.globalPause) return;
+      if (settings.globalPause || settings.enginePaused) return;
       if (!settings.autoMerge) return;
       enqueueMerge(task.id);
     } catch { /* ignore settings read errors */ }
@@ -273,6 +273,31 @@ export async function runDashboard(port: number, opts: { open?: boolean } = {})
       }
     });
 
+    // ── Immediate engine-unpause: resume orphans + merge sweep ────────
+    // When enginePaused transitions from true → false, same resume logic
+    // as globalPause unpause: pick up orphaned tasks and sweep merge queue.
+    store.on("settings:updated", async ({ settings: s, previous: prev }) => {
+      if (prev.enginePaused && !s.enginePaused) {
+        console.log("[engine] Engine unpaused — resuming agentic activity");
+        cachedMaxConcurrent = s.maxConcurrent ?? cachedMaxConcurrent;
+
+        executor.resumeOrphaned().catch((err) =>
+          console.error("[engine] Failed to resume orphaned tasks on engine unpause:", err),
+        );
+
+        if (s.autoMerge) {
+          try {
+            const tasks = await store.listTasks();
+            for (const t of tasks) {
+              if (t.column === "in-review" && !t.paused) {
+                enqueueMerge(t.id);
+              }
+            }
+          } catch { /* ignore errors in unpause sweep */ }
+        }
+      }
+    });
+
     // ── Periodic retry: catch failed merges on each poll cycle ────────
     // Uses a setTimeout chain so the interval dynamically follows
     // settings.pollIntervalMs without requiring an engine restart.
@@ -285,7 +310,7 @@ export async function runDashboard(port: number, opts: { open?: boolean } = {})
           const s = await store.getSettings();
           // Refresh the cached limit so the semaphore picks up live changes
           cachedMaxConcurrent = s.maxConcurrent;
-          if (!s.globalPause && s.autoMerge) {
+          if (!s.globalPause && !s.enginePaused && s.autoMerge) {
             const tasks = await store.listTasks();
             for (const t of tasks) {
               if (t.column === "in-review" && !t.paused) {