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/dashboard/app/App.tsx

@@ -18,6 +18,7 @@ function AppInner() {
   const [maxConcurrent, setMaxConcurrent] = useState(2);
   const [autoMerge, setAutoMerge] = useState(false);
   const [globalPaused, setGlobalPaused] = useState(false);
+  const [enginePaused, setEnginePaused] = useState(false);
   const { tasks, createTask, moveTask, deleteTask, mergeTask, retryTask } = useTasks();
 
   useEffect(() => {
@@ -28,6 +29,7 @@ function AppInner() {
       .then((s) => {
         setAutoMerge(!!s.autoMerge);
         setGlobalPaused(!!s.globalPause);
+        setEnginePaused(!!s.enginePaused);
       })
       .catch(() => {/* keep default */});
     fetchAuthStatus()
@@ -73,6 +75,16 @@ function AppInner() {
     }
   }, [globalPaused]);
 
+  const handleToggleEnginePause = useCallback(async () => {
+    const next = !enginePaused;
+    setEnginePaused(next);
+    try {
+      await updateSettings({ enginePaused: next });
+    } catch {
+      setEnginePaused(!next); // revert on failure
+    }
+  }, [enginePaused]);
+
   const handleDetailOpen = useCallback((task: TaskDetail) => {
     setDetailTask(task);
   }, []);
@@ -84,7 +96,9 @@ function AppInner() {
       <Header
         onOpenSettings={() => setSettingsOpen(true)}
         globalPaused={globalPaused}
+        enginePaused={enginePaused}
         onToggleGlobalPause={handleToggleGlobalPause}
+        onToggleEnginePause={handleToggleEnginePause}
       />
       <Board
         tasks={tasks}

packages/dashboard/app/components/Header.tsx

@@ -1,12 +1,20 @@
-import { Settings, Pause, Play } from "lucide-react";
+import { Settings, Pause, Play, Square } from "lucide-react";
 
 interface HeaderProps {
   onOpenSettings?: () => void;
   globalPaused?: boolean;
+  enginePaused?: boolean;
   onToggleGlobalPause?: () => void;
+  onToggleEnginePause?: () => void;
 }
 
-export function Header({ onOpenSettings, globalPaused, onToggleGlobalPause }: HeaderProps) {
+export function Header({
+  onOpenSettings,
+  globalPaused,
+  enginePaused,
+  onToggleGlobalPause,
+  onToggleEnginePause,
+}: HeaderProps) {
   return (
     <header className="header">
       <div className="header-left">
@@ -15,12 +23,22 @@ export function Header({ onOpenSettings, globalPaused, onToggleGlobalPause }: He
         <span className="logo-sub">board</span>
       </div>
       <div className="header-actions">
+        {/* Pause button (soft pause): stops new work, lets agents finish */}
         <button
-          className={`btn-icon${globalPaused ? " btn-icon--paused" : ""}`}
-          onClick={onToggleGlobalPause}
-          title={globalPaused ? "Resume AI engine" : "Pause AI engine"}
+          className={`btn-icon${enginePaused ? " btn-icon--paused" : ""}`}
+          onClick={onToggleEnginePause}
+          title={enginePaused ? "Resume AI engine" : "Pause AI engine"}
+          disabled={!!globalPaused}
         >
-          {globalPaused ? <Play size={16} /> : <Pause size={16} />}
+          {enginePaused ? <Play size={16} /> : <Pause size={16} />}
+        </button>
+        {/* Stop button (hard stop): kills all agents immediately */}
+        <button
+          className={`btn-icon${globalPaused ? " btn-icon--stopped" : ""}`}
+          onClick={onToggleGlobalPause}
+          title={globalPaused ? "Start AI engine" : "Stop AI engine"}
+        >
+          {globalPaused ? <Play size={16} /> : <Square size={16} />}
         </button>
         <button className="btn-icon" onClick={onOpenSettings} title="Settings">
           <Settings size={16} />

packages/dashboard/app/components/__tests__/App.test.tsx

@@ -133,7 +133,7 @@ describe("App auto-open Settings on unauthenticated", () => {
   });
 });
 
-describe("App global pause", () => {
+describe("App global pause (hard stop)", () => {
   it("initializes global pause state from fetchSettings", async () => {
     (fetchSettings as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
       ...defaultSettings,
@@ -142,13 +142,13 @@ describe("App global pause", () => {
 
     render(<App />);
 
-    // When globally paused, the button should show "Resume AI engine"
+    // When globally paused, the stop button should show "Start AI engine"
     await waitFor(() => {
-      expect(screen.getByTitle("Resume AI engine")).toBeTruthy();
+      expect(screen.getByTitle("Start AI engine")).toBeTruthy();
     });
   });
 
-  it("shows Pause button when globalPause is false", async () => {
+  it("shows Stop button when globalPause is false", async () => {
     (fetchSettings as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
       ...defaultSettings,
       globalPause: false,
@@ -157,7 +157,7 @@ describe("App global pause", () => {
     render(<App />);
 
     await waitFor(() => {
-      expect(screen.getByTitle("Pause AI engine")).toBeTruthy();
+      expect(screen.getByTitle("Stop AI engine")).toBeTruthy();
     });
   });
 
@@ -171,15 +171,15 @@ describe("App global pause", () => {
 
     // Wait for initial render
     await waitFor(() => {
-      expect(screen.getByTitle("Pause AI engine")).toBeTruthy();
+      expect(screen.getByTitle("Stop AI engine")).toBeTruthy();
     });
 
-    // Click the pause button
-    fireEvent.click(screen.getByTitle("Pause AI engine"));
+    // Click the stop button
+    fireEvent.click(screen.getByTitle("Stop AI engine"));
 
-    // Should optimistically switch to "Resume" state
+    // Should optimistically switch to "Start" state
     await waitFor(() => {
-      expect(screen.getByTitle("Resume AI engine")).toBeTruthy();
+      expect(screen.getByTitle("Start AI engine")).toBeTruthy();
     });
 
     // Should call updateSettings with globalPause: true
@@ -196,15 +196,68 @@ describe("App global pause", () => {
     render(<App />);
 
     await waitFor(() => {
-      expect(screen.getByTitle("Pause AI engine")).toBeTruthy();
+      expect(screen.getByTitle("Stop AI engine")).toBeTruthy();
     });
 
-    // Click the pause button — will fail
-    fireEvent.click(screen.getByTitle("Pause AI engine"));
+    // Click the stop button — will fail
+    fireEvent.click(screen.getByTitle("Stop AI engine"));
+
+    // Should revert back to "Stop" state after failure
+    await waitFor(() => {
+      expect(screen.getByTitle("Stop AI engine")).toBeTruthy();
+    });
+  });
+});
+
+describe("App engine pause (soft pause)", () => {
+  it("initializes engine pause state from fetchSettings", async () => {
+    (fetchSettings as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ...defaultSettings,
+      enginePaused: true,
+    });
+
+    render(<App />);
+
+    // When engine is paused, the pause button should show "Resume AI engine"
+    await waitFor(() => {
+      expect(screen.getByTitle("Resume AI engine")).toBeTruthy();
+    });
+  });
+
+  it("shows Pause button when enginePaused is false", async () => {
+    (fetchSettings as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ...defaultSettings,
+      enginePaused: false,
+    });
+
+    render(<App />);
 
-    // Should revert back to "Pause" state after failure
     await waitFor(() => {
       expect(screen.getByTitle("Pause AI engine")).toBeTruthy();
     });
   });
+
+  it("toggles engine pause state and calls updateSettings", async () => {
+    (fetchSettings as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ...defaultSettings,
+      enginePaused: false,
+    });
+
+    render(<App />);
+
+    await waitFor(() => {
+      expect(screen.getByTitle("Pause AI engine")).toBeTruthy();
+    });
+
+    // Click the pause button
+    fireEvent.click(screen.getByTitle("Pause AI engine"));
+
+    // Should optimistically switch to "Resume" state
+    await waitFor(() => {
+      expect(screen.getByTitle("Resume AI engine")).toBeTruthy();
+    });
+
+    // Should call updateSettings with enginePaused: true
+    expect(updateSettings).toHaveBeenCalledWith({ enginePaused: true });
+  });
 });

packages/dashboard/app/components/__tests__/Header.test.tsx

@@ -26,35 +26,91 @@ describe("Header", () => {
     expect(btn).toBeDefined();
   });
 
+  // ── Pause button (soft pause) ────────────────────────────────────
+
   it("renders pause button with 'Pause AI engine' title when not paused", () => {
-    render(<Header globalPaused={false} />);
+    render(<Header enginePaused={false} />);
     const btn = screen.getByTitle("Pause AI engine");
     expect(btn).toBeDefined();
   });
 
-  it("renders play button with 'Resume AI engine' title when paused", () => {
-    render(<Header globalPaused={true} />);
+  it("renders play button with 'Resume AI engine' title when engine is paused", () => {
+    render(<Header enginePaused={true} />);
     const btn = screen.getByTitle("Resume AI engine");
     expect(btn).toBeDefined();
   });
 
-  it("calls onToggleGlobalPause when pause button is clicked", () => {
+  it("calls onToggleEnginePause when pause button is clicked", () => {
     const onToggle = vi.fn();
-    render(<Header globalPaused={false} onToggleGlobalPause={onToggle} />);
+    render(<Header enginePaused={false} onToggleEnginePause={onToggle} />);
     const btn = screen.getByTitle("Pause AI engine");
     fireEvent.click(btn);
     expect(onToggle).toHaveBeenCalledOnce();
   });
 
-  it("applies btn-icon--paused class when paused", () => {
-    render(<Header globalPaused={true} />);
+  it("applies btn-icon--paused class when engine is paused", () => {
+    render(<Header enginePaused={true} />);
     const btn = screen.getByTitle("Resume AI engine");
     expect(btn.className).toContain("btn-icon--paused");
   });
 
-  it("does not apply btn-icon--paused class when not paused", () => {
-    render(<Header globalPaused={false} />);
+  it("does not apply btn-icon--paused class when engine is not paused", () => {
+    render(<Header enginePaused={false} />);
     const btn = screen.getByTitle("Pause AI engine");
     expect(btn.className).not.toContain("btn-icon--paused");
   });
+
+  it("pause button is disabled when globalPaused is true", () => {
+    render(<Header globalPaused={true} enginePaused={false} />);
+    const btn = screen.getByTitle("Pause AI engine");
+    expect((btn as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it("pause button is enabled when globalPaused is false", () => {
+    render(<Header globalPaused={false} enginePaused={false} />);
+    const btn = screen.getByTitle("Pause AI engine");
+    expect((btn as HTMLButtonElement).disabled).toBe(false);
+  });
+
+  // ── Stop button (hard stop) ──────────────────────────────────────
+
+  it("renders stop button with 'Stop AI engine' title when not stopped", () => {
+    render(<Header globalPaused={false} />);
+    const btn = screen.getByTitle("Stop AI engine");
+    expect(btn).toBeDefined();
+  });
+
+  it("renders play button with 'Start AI engine' title when stopped", () => {
+    render(<Header globalPaused={true} />);
+    const btn = screen.getByTitle("Start AI engine");
+    expect(btn).toBeDefined();
+  });
+
+  it("calls onToggleGlobalPause when stop button is clicked", () => {
+    const onToggle = vi.fn();
+    render(<Header globalPaused={false} onToggleGlobalPause={onToggle} />);
+    const btn = screen.getByTitle("Stop AI engine");
+    fireEvent.click(btn);
+    expect(onToggle).toHaveBeenCalledOnce();
+  });
+
+  it("applies btn-icon--stopped class when globally paused", () => {
+    render(<Header globalPaused={true} />);
+    const btn = screen.getByTitle("Start AI engine");
+    expect(btn.className).toContain("btn-icon--stopped");
+  });
+
+  it("does not apply btn-icon--stopped class when not globally paused", () => {
+    render(<Header globalPaused={false} />);
+    const btn = screen.getByTitle("Stop AI engine");
+    expect(btn.className).not.toContain("btn-icon--stopped");
+  });
+
+  it("stop button shows Play icon when globalPaused is true", () => {
+    render(<Header globalPaused={true} />);
+    const btn = screen.getByTitle("Start AI engine");
+    // The Play icon from lucide-react renders an SVG
+    const svg = btn.querySelector("svg");
+    expect(svg).toBeDefined();
+  });
 });

packages/dashboard/app/styles.css

@@ -64,6 +64,18 @@ html, body {
   color: var(--text);
   background: var(--border);
 }
+.btn-icon--paused {
+  color: var(--triage);
+}
+.btn-icon--paused:hover {
+  color: var(--triage);
+}
+.btn-icon--stopped {
+  color: var(--color-error);
+}
+.btn-icon--stopped:hover {
+  color: var(--color-error);
+}
 .logo { font-size: 20px; font-weight: 700; letter-spacing: -0.5px; }
 .logo-sub { font-size: 13px; color: var(--text-muted); font-weight: 400; }