feat(KB-145): add global pause button to halt all AI engine activity

- Add globalPause setting to core Settings type with default false
- Guard scheduler, triage, and auto-merge queue to skip work when globalPause is active
- Add pause/play toggle button in dashboard Header with optimistic UI and rollback on failure
- Add tests for scheduler, triage, Header, and App global pause behavior
- Include minor changeset for the new feature

.changeset/global-pause-button.md

@@ -0,0 +1,5 @@
+---
+"@dustinbyrne/kb": minor
+---
+
+Add global pause button to stop all automated agents and scheduling

packages/cli/src/commands/dashboard.ts

@@ -92,8 +92,12 @@ export async function runDashboard(port: number, opts: { open?: boolean } = {})
       while (mergeQueue.length > 0) {
         const taskId = mergeQueue.shift()!;
         try {
-          // Re-check autoMerge before each merge (setting may have been toggled)
+          // 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`);
+            continue;
+          }
           if (!settings.autoMerge) {
             console.log(`[auto-merge] Skipping ${taskId} — autoMerge disabled`);
             continue;
@@ -128,6 +132,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.autoMerge) return;
       enqueueMerge(task.id);
     } catch { /* ignore settings read errors */ }
@@ -203,7 +208,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.autoMerge) {
+          if (!s.globalPause && s.autoMerge) {
             const tasks = await store.listTasks();
             for (const t of tasks) {
               if (t.column === "in-review" && !t.paused) {

packages/core/src/types.ts

@@ -95,6 +95,10 @@ export interface TaskCreateInput {
 }
 
 export interface Settings {
+  /** When true, all automated agent activity is halted — triage specification,
+   *  task scheduling, execution, and auto-merge. Acts as a global emergency stop
+   *  for the entire AI engine. Individual per-task pause flags are unaffected. */
+  globalPause?: boolean;
   /** Maximum number of concurrent AI agents across all activity types
    *  (triage specification, task execution, and merge operations). */
   maxConcurrent: number;
@@ -137,6 +141,7 @@ export interface Settings {
 }
 
 export const DEFAULT_SETTINGS: Settings = {
+  globalPause: false,
   maxConcurrent: 2,
   maxWorktrees: 4,
   pollIntervalMs: 15000,

packages/dashboard/app/App.tsx

@@ -17,6 +17,7 @@ function AppInner() {
   const [settingsInitialSection, setSettingsInitialSection] = useState<SectionId | undefined>(undefined);
   const [maxConcurrent, setMaxConcurrent] = useState(2);
   const [autoMerge, setAutoMerge] = useState(false);
+  const [globalPaused, setGlobalPaused] = useState(false);
   const { tasks, createTask, moveTask, deleteTask, mergeTask, retryTask } = useTasks();
 
   useEffect(() => {
@@ -24,7 +25,10 @@ function AppInner() {
       .then((cfg) => setMaxConcurrent(cfg.maxConcurrent))
       .catch(() => {/* keep default */});
     fetchSettings()
-      .then((s) => setAutoMerge(!!s.autoMerge))
+      .then((s) => {
+        setAutoMerge(!!s.autoMerge);
+        setGlobalPaused(!!s.globalPause);
+      })
       .catch(() => {/* keep default */});
     fetchAuthStatus()
       .then(({ providers }) => {
@@ -59,6 +63,16 @@ function AppInner() {
     }
   }, [autoMerge]);
 
+  const handleToggleGlobalPause = useCallback(async () => {
+    const next = !globalPaused;
+    setGlobalPaused(next);
+    try {
+      await updateSettings({ globalPause: next });
+    } catch {
+      setGlobalPaused(!next); // revert on failure
+    }
+  }, [globalPaused]);
+
   const handleDetailOpen = useCallback((task: TaskDetail) => {
     setDetailTask(task);
   }, []);
@@ -67,7 +81,11 @@ function AppInner() {
 
   return (
     <>
-      <Header onOpenSettings={() => setSettingsOpen(true)} />
+      <Header
+        onOpenSettings={() => setSettingsOpen(true)}
+        globalPaused={globalPaused}
+        onToggleGlobalPause={handleToggleGlobalPause}
+      />
       <Board
         tasks={tasks}
         maxConcurrent={maxConcurrent}

packages/dashboard/app/components/Header.tsx

@@ -1,10 +1,12 @@
-import { Settings } from "lucide-react";
+import { Settings, Pause, Play } from "lucide-react";
 
 interface HeaderProps {
   onOpenSettings?: () => void;
+  globalPaused?: boolean;
+  onToggleGlobalPause?: () => void;
 }
 
-export function Header({ onOpenSettings }: HeaderProps) {
+export function Header({ onOpenSettings, globalPaused, onToggleGlobalPause }: HeaderProps) {
   return (
     <header className="header">
       <div className="header-left">
@@ -13,6 +15,13 @@ export function Header({ onOpenSettings }: HeaderProps) {
         <span className="logo-sub">board</span>
       </div>
       <div className="header-actions">
+        <button
+          className={`btn-icon${globalPaused ? " btn-icon--paused" : ""}`}
+          onClick={onToggleGlobalPause}
+          title={globalPaused ? "Resume AI engine" : "Pause AI engine"}
+        >
+          {globalPaused ? <Play size={16} /> : <Pause size={16} />}
+        </button>
         <button className="btn-icon" onClick={onOpenSettings} title="Settings">
           <Settings size={16} />
         </button>

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

@@ -44,7 +44,7 @@ vi.mock("../../hooks/useTasks", () => ({
   }),
 }));
 
-import { fetchAuthStatus, fetchSettings } from "../../api";
+import { fetchAuthStatus, fetchSettings, updateSettings } from "../../api";
 
 beforeEach(() => {
   vi.clearAllMocks();
@@ -132,3 +132,79 @@ describe("App auto-open Settings on unauthenticated", () => {
     expect(screen.queryByText("Anthropic")).toBeNull();
   });
 });
+
+describe("App global pause", () => {
+  it("initializes global pause state from fetchSettings", async () => {
+    (fetchSettings as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ...defaultSettings,
+      globalPause: true,
+    });
+
+    render(<App />);
+
+    // When globally paused, the button should show "Resume AI engine"
+    await waitFor(() => {
+      expect(screen.getByTitle("Resume AI engine")).toBeTruthy();
+    });
+  });
+
+  it("shows Pause button when globalPause is false", async () => {
+    (fetchSettings as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ...defaultSettings,
+      globalPause: false,
+    });
+
+    render(<App />);
+
+    await waitFor(() => {
+      expect(screen.getByTitle("Pause AI engine")).toBeTruthy();
+    });
+  });
+
+  it("toggles global pause state and calls updateSettings", async () => {
+    (fetchSettings as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ...defaultSettings,
+      globalPause: false,
+    });
+
+    render(<App />);
+
+    // Wait for initial render
+    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 globalPause: true
+    expect(updateSettings).toHaveBeenCalledWith({ globalPause: true });
+  });
+
+  it("reverts global pause state on updateSettings failure", async () => {
+    (fetchSettings as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ...defaultSettings,
+      globalPause: false,
+    });
+    (updateSettings as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error("Network error"));
+
+    render(<App />);
+
+    await waitFor(() => {
+      expect(screen.getByTitle("Pause AI engine")).toBeTruthy();
+    });
+
+    // Click the pause button — will fail
+    fireEvent.click(screen.getByTitle("Pause AI engine"));
+
+    // Should revert back to "Pause" state after failure
+    await waitFor(() => {
+      expect(screen.getByTitle("Pause AI engine")).toBeTruthy();
+    });
+  });
+});

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

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { render, screen, fireEvent } from "@testing-library/react";
 import { Header } from "../Header";
 
 describe("Header", () => {
@@ -25,4 +25,36 @@ describe("Header", () => {
     const btn = screen.getByTitle("Settings");
     expect(btn).toBeDefined();
   });
+
+  it("renders pause button with 'Pause AI engine' title when not paused", () => {
+    render(<Header globalPaused={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} />);
+    const btn = screen.getByTitle("Resume AI engine");
+    expect(btn).toBeDefined();
+  });
+
+  it("calls onToggleGlobalPause when pause button is clicked", () => {
+    const onToggle = vi.fn();
+    render(<Header globalPaused={false} onToggleGlobalPause={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} />);
+    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} />);
+    const btn = screen.getByTitle("Pause AI engine");
+    expect(btn.className).not.toContain("btn-icon--paused");
+  });
 });

packages/engine/src/scheduler.test.ts

@@ -788,6 +788,99 @@ describe("Scheduler worktree limit logging", () => {
   });
 });
 
+describe("Scheduler globalPause", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  async function runSchedule(scheduler: Scheduler): Promise<void> {
+    (scheduler as any).running = true;
+    await scheduler.schedule();
+  }
+
+  it("does not move any tasks when globalPause is true", async () => {
+    const tasks = [
+      makeTask({ id: "KB-001", column: "todo" }),
+      makeTask({ id: "KB-002", column: "todo" }),
+    ];
+    const store = createMockStore(tasks);
+    store.getSettings.mockResolvedValue({
+      maxConcurrent: 2,
+      maxWorktrees: 4,
+      pollIntervalMs: 15000,
+      groupOverlappingFiles: false,
+      autoMerge: false,
+      globalPause: true,
+    });
+    const scheduler = new Scheduler(store, { maxConcurrent: 2 });
+
+    await runSchedule(scheduler);
+
+    expect(store.moveTask).not.toHaveBeenCalled();
+    expect(store.updateTask).not.toHaveBeenCalled();
+  });
+
+  it("resumes scheduling when globalPause is toggled back to false", async () => {
+    const tasks = [
+      makeTask({ id: "KB-001", column: "todo" }),
+    ];
+    const store = createMockStore(tasks);
+    store.getSettings.mockResolvedValue({
+      maxConcurrent: 2,
+      maxWorktrees: 4,
+      pollIntervalMs: 15000,
+      groupOverlappingFiles: false,
+      autoMerge: false,
+      globalPause: true,
+    });
+    const scheduler = new Scheduler(store, { maxConcurrent: 2 });
+
+    await runSchedule(scheduler);
+    expect(store.moveTask).not.toHaveBeenCalled();
+
+    // Toggle globalPause off
+    store.getSettings.mockResolvedValue({
+      maxConcurrent: 2,
+      maxWorktrees: 4,
+      pollIntervalMs: 15000,
+      groupOverlappingFiles: false,
+      autoMerge: false,
+      globalPause: false,
+    });
+
+    await runSchedule(scheduler);
+    expect(store.moveTask).toHaveBeenCalledWith("KB-001", "in-progress");
+  });
+
+  it("logs once when entering global pause state", async () => {
+    const tasks = [makeTask({ id: "KB-001", column: "todo" })];
+    const store = createMockStore(tasks);
+    store.getSettings.mockResolvedValue({
+      maxConcurrent: 2,
+      maxWorktrees: 4,
+      pollIntervalMs: 15000,
+      groupOverlappingFiles: false,
+      autoMerge: false,
+      globalPause: true,
+    });
+    const scheduler = new Scheduler(store, { maxConcurrent: 2 });
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await runSchedule(scheduler);
+    await runSchedule(scheduler);
+    await runSchedule(scheduler);
+
+    const pauseMessages = logSpy.mock.calls.filter(
+      (args) =>
+        typeof args[0] === "string" &&
+        args[0].includes("Global pause active"),
+    );
+    expect(pauseMessages).toHaveLength(1);
+    logSpy.mockRestore();
+  });
+});
+
 describe("Scheduler in-review worktrees do not count against maxWorktrees", () => {
   beforeEach(() => {
     vi.clearAllMocks();

packages/engine/src/scheduler.ts

@@ -75,6 +75,7 @@ export class Scheduler {
   private running = false;
   private scheduling = false;
   private wasWorktreeLimited = false;
+  private wasGlobalPaused = false;
   private pollInterval: ReturnType<typeof setInterval> | null = null;
   /** The interval (ms) of the currently active `setInterval` timer. */
   private activePollMs: number | null = null;
@@ -181,6 +182,16 @@ export class Scheduler {
       // Refresh the poll interval if the persisted setting has changed
       this.refreshPollInterval(settings.pollIntervalMs);
 
+      // Global pause: halt all scheduling activity
+      if (settings.globalPause) {
+        if (!this.wasGlobalPaused) {
+          schedulerLog.log("Global pause active — scheduling halted");
+          this.wasGlobalPaused = true;
+        }
+        return;
+      }
+      this.wasGlobalPaused = false;
+
       // Count only in-progress tasks toward the worktree limit.
       // In-review tasks with worktrees are idle (waiting to merge) and
       // should not block new tasks from starting.

packages/engine/src/triage.test.ts

@@ -291,6 +291,132 @@ describe("TriageProcessor paused tasks", () => {
   });
 });
 
+describe("TriageProcessor globalPause", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("does not specify any tasks when globalPause is true", async () => {
+    const triageTask = {
+      id: "KB-001",
+      title: "Test",
+      description: "Test task",
+      column: "triage" as const,
+      dependencies: [],
+      steps: [],
+      currentStep: 0,
+      log: [],
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    const store = createMockStore([triageTask]);
+    store.getSettings.mockResolvedValue({
+      maxConcurrent: 2,
+      maxWorktrees: 4,
+      pollIntervalMs: 15000,
+      groupOverlappingFiles: false,
+      autoMerge: false,
+      globalPause: true,
+    });
+
+    mockedCreateHaiAgent.mockResolvedValue({
+      session: {
+        prompt: vi.fn().mockResolvedValue(undefined),
+        dispose: vi.fn(),
+      },
+    } as any);
+
+    const triage = new TriageProcessor(store, "/tmp/test");
+    (triage as any).running = true;
+    await (triage as any).poll();
+
+    // Agent should never be created when globally paused
+    expect(mockedCreateHaiAgent).not.toHaveBeenCalled();
+    expect(store.updateTask).not.toHaveBeenCalled();
+  });
+
+  it("resumes triage when globalPause is toggled back to false", async () => {
+    const triageTask = {
+      id: "KB-002",
+      title: "Normal",
+      description: "Normal task",
+      column: "triage" as const,
+      dependencies: [],
+      steps: [],
+      currentStep: 0,
+      log: [],
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    const store = createMockStore([triageTask]);
+    store.getSettings.mockResolvedValue({
+      maxConcurrent: 2,
+      maxWorktrees: 4,
+      pollIntervalMs: 15000,
+      groupOverlappingFiles: false,
+      autoMerge: false,
+      globalPause: true,
+    });
+
+    mockedCreateHaiAgent.mockResolvedValue({
+      session: {
+        prompt: vi.fn().mockResolvedValue(undefined),
+        dispose: vi.fn(),
+      },
+    } as any);
+
+    const triage = new TriageProcessor(store, "/tmp/test");
+    (triage as any).running = true;
+
+    // First poll — paused, nothing happens
+    await (triage as any).poll();
+    expect(mockedCreateHaiAgent).not.toHaveBeenCalled();
+
+    // Toggle globalPause off
+    store.getSettings.mockResolvedValue({
+      maxConcurrent: 2,
+      maxWorktrees: 4,
+      pollIntervalMs: 15000,
+      groupOverlappingFiles: false,
+      autoMerge: false,
+      globalPause: false,
+    });
+
+    // Second poll — should process tasks
+    await (triage as any).poll();
+    expect(store.updateTask).toHaveBeenCalledWith("KB-002", { status: "specifying" });
+  });
+
+  it("logs once when entering global pause state", async () => {
+    const store = createMockStore([]);
+    store.getSettings.mockResolvedValue({
+      maxConcurrent: 2,
+      maxWorktrees: 4,
+      pollIntervalMs: 15000,
+      groupOverlappingFiles: false,
+      autoMerge: false,
+      globalPause: true,
+    });
+
+    const triage = new TriageProcessor(store, "/tmp/test");
+    (triage as any).running = true;
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await (triage as any).poll();
+    await (triage as any).poll();
+    await (triage as any).poll();
+
+    const pauseMessages = logSpy.mock.calls.filter(
+      (args) =>
+        typeof args[0] === "string" &&
+        args[0].includes("Global pause active"),
+    );
+    expect(pauseMessages).toHaveLength(1);
+    logSpy.mockRestore();
+  });
+});
+
 describe("buildSpecificationPrompt", () => {
   it("includes project commands when testCommand is set", () => {
     const task = createMockTaskDetail();

packages/engine/src/triage.ts

@@ -179,6 +179,7 @@ export class TriageProcessor {
   /** The interval (ms) of the currently active `setInterval` timer. */
   private activePollMs: number | null = null;
   private processing = new Set<string>();
+  private wasGlobalPaused = false;
 
   constructor(
     private store: TaskStore,
@@ -230,6 +231,16 @@ export class TriageProcessor {
       const settings = await this.store.getSettings();
       this.refreshPollInterval(settings.pollIntervalMs);
 
+      // Global pause: halt all triage activity
+      if (settings.globalPause) {
+        if (!this.wasGlobalPaused) {
+          triageLog.log("Global pause active — triage halted");
+          this.wasGlobalPaused = true;
+        }
+        return;
+      }
+      this.wasGlobalPaused = false;
+
       const tasks = await this.store.listTasks();
       const triageTasks = tasks.filter(
         (t) => t.column === "triage" && !this.processing.has(t.id) && !t.paused,