feat(FN-1073): add desktop CLI workflow and packaging support

- Add new `fn desktop` CLI command with argument handling and comprehensive command/bin tests
- Implement desktop build and hot-reload dev scripts and wire package scripts/dependencies for Electron workflows
- Add electron-builder configuration and desktop main-process/integration test coverage to stabilize packaging behavior
- Document desktop development and usage in README files and include a changeset for the published CLI package

packages/cli/src/__tests__/bin.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 
 const runTaskCreate = vi.fn();
 const runTaskList = vi.fn();
+const runDesktop = vi.fn();
 const runTaskPlan = vi.fn();
 const runTaskImportFromGitHub = vi.fn();
 const runSettingsShow = vi.fn();
@@ -36,6 +37,10 @@ vi.mock("../commands/dashboard.js", () => ({
   runDashboard: vi.fn(),
 }));
 
+vi.mock("../commands/desktop.js", () => ({
+  runDesktop,
+}));
+
 vi.mock("../commands/task.js", () => ({
   runTaskCreate,
   runTaskList,
@@ -272,6 +277,16 @@ describe("bin", () => {
     expect(errorSpy).toHaveBeenCalledWith("Unknown subcommand: node wat");
   });
 
+  it("routes desktop command flags", async () => {
+    await runBin(["desktop", "--dev", "--paused", "--interactive"]);
+
+    expect(runDesktop).toHaveBeenCalledWith({
+      paused: true,
+      dev: true,
+      interactive: true,
+    });
+  });
+
   it("rejects duplicate --project flags", async () => {
     await expect(runBin(["task", "list", "--project", "one", "-P", "two"]))
       .rejects.toThrow("Duplicate --project flag. Specify a project only once.");

packages/cli/src/bin.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const commandMocks = vi.hoisted(() => ({
   runDashboard: vi.fn(),
+  runDesktop: vi.fn(),
   runTaskCreate: vi.fn(),
   runTaskList: vi.fn(),
   runTaskMove: vi.fn(),
@@ -52,6 +53,7 @@ const commandMocks = vi.hoisted(() => ({
 }));
 
 vi.mock("./commands/dashboard.js", () => ({ runDashboard: commandMocks.runDashboard }));
+vi.mock("./commands/desktop.js", () => ({ runDesktop: commandMocks.runDesktop }));
 vi.mock("./commands/task.js", () => ({
   runTaskCreate: commandMocks.runTaskCreate,
   runTaskList: commandMocks.runTaskList,
@@ -129,8 +131,10 @@ async function runBin(args: string[]) {
     await import("./bin.ts?test=3");
   } else if (importCounter === 4) {
     await import("./bin.ts?test=4");
-  } else {
+  } else if (importCounter === 5) {
     await import("./bin.ts?test=5");
+  } else {
+    await import("./bin.ts?test=6");
   }
 }
 
@@ -182,4 +186,13 @@ describe("bin mission command integration", () => {
     await runBin(["mission", "activate-slice", "SL-001"]);
     expect(commandMocks.runMissionActivateSlice).toHaveBeenCalledWith("SL-001", undefined);
   });
+
+  it("routes desktop flags to runDesktop", async () => {
+    await runBin(["desktop", "--dev", "--paused", "--interactive"]);
+    expect(commandMocks.runDesktop).toHaveBeenCalledWith({
+      paused: true,
+      dev: true,
+      interactive: true,
+    });
+  });
 });

packages/cli/src/bin.ts

@@ -39,6 +39,7 @@ if (isBunBinary) {
 
 // Dynamic imports so the pi-coding-agent config module sees PI_PACKAGE_DIR
 const { runDashboard } = await import("./commands/dashboard.js");
+const { runDesktop } = await import("./commands/desktop.js");
 const { runTaskCreate, runTaskList, runTaskMove, runTaskMerge, runTaskUpdate, runTaskLog, runTaskLogs, runTaskShow, runTaskAttach, runTaskPause, runTaskUnpause, runTaskImportFromGitHub, runTaskDuplicate, runTaskArchive, runTaskUnarchive, runTaskRefine, runTaskPlan, runTaskDelete, runTaskRetry, runTaskComment, runTaskComments, runTaskSteer, runTaskPrCreate } = await import("./commands/task.js");
 const { runSettingsShow, runSettingsSet } = await import("./commands/settings.js");
 const { runSettingsExport } = await import("./commands/settings-export.js");
@@ -62,6 +63,9 @@ Usage:
   fn dashboard --paused               Start with automation paused
   fn dashboard --dev                  Start web UI only (no AI engine)
   fn dashboard --interactive          Start with interactive port selection
+  fn desktop                          Launch the Fusion desktop app (Electron)
+  fn desktop --dev                    Launch with hot-reload (connects to Vite dev server)
+  fn desktop --paused                 Launch with automation paused
   fn task create [desc] [opts]         Create a new task (goes to triage)
   fn task plan [description] [opts]    Create task via AI-guided planning
   fn task list                        List all tasks
@@ -295,6 +299,14 @@ async function main() {
         break;
       }
 
+      case "desktop": {
+        const paused = args.includes("--paused");
+        const dev = args.includes("--dev");
+        const interactive = args.includes("--interactive");
+        await runDesktop({ paused, dev, interactive });
+        break;
+      }
+
       case "project": {
         const subcommand = args[1];
         switch (subcommand) {

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

@@ -0,0 +1,263 @@
+import { beforeEach, afterEach, describe, expect, it, vi } from "vitest";
+
+type Listener = (...args: any[]) => void;
+
+interface MockEmitter {
+  on(event: string, listener: Listener): MockEmitter;
+  once(event: string, listener: Listener): MockEmitter;
+  off(event: string, listener: Listener): MockEmitter;
+  emit(event: string, ...args: any[]): boolean;
+}
+
+interface MockChild extends MockEmitter {
+  kill: ReturnType<typeof vi.fn>;
+  killed: boolean;
+}
+
+const mocks = vi.hoisted(() => {
+  function createEmitter(): MockEmitter {
+    const listeners = new Map<string, Set<Listener>>();
+
+    const add = (event: string, listener: Listener) => {
+      const eventListeners = listeners.get(event) ?? new Set<Listener>();
+      eventListeners.add(listener);
+      listeners.set(event, eventListeners);
+    };
+
+    const remove = (event: string, listener: Listener) => {
+      const eventListeners = listeners.get(event);
+      if (!eventListeners) return;
+      eventListeners.delete(listener);
+      if (eventListeners.size === 0) {
+        listeners.delete(event);
+      }
+    };
+
+    return {
+      on(event: string, listener: Listener) {
+        add(event, listener);
+        return this;
+      },
+      once(event: string, listener: Listener) {
+        const wrapped: Listener = (...args: any[]) => {
+          remove(event, wrapped);
+          listener(...args);
+        };
+        add(event, wrapped);
+        return this;
+      },
+      off(event: string, listener: Listener) {
+        remove(event, listener);
+        return this;
+      },
+      emit(event: string, ...args: any[]) {
+        const eventListeners = listeners.get(event);
+        if (!eventListeners || eventListeners.size === 0) {
+          return false;
+        }
+
+        for (const listener of [...eventListeners]) {
+          listener(...args);
+        }
+
+        return true;
+      },
+    };
+  }
+
+  function createMockChild(): MockChild {
+    const emitter = createEmitter();
+    const child = emitter as MockChild;
+    child.killed = false;
+    child.kill = vi.fn((() => {
+      child.killed = true;
+      return true;
+    }) as unknown as MockChild["kill"]);
+    return child;
+  }
+
+  const state = {
+    buildChild: createMockChild(),
+    electronChild: createMockChild(),
+  };
+
+  const store = {
+    init: vi.fn().mockResolvedValue(undefined),
+    watch: vi.fn().mockResolvedValue(undefined),
+    updateSettings: vi.fn().mockResolvedValue(undefined),
+    close: vi.fn(),
+  };
+
+  const server = Object.assign(createEmitter(), {
+    address: vi.fn(() => ({ port: 4545 })),
+    close: vi.fn((callback?: () => void) => {
+      callback?.();
+    }),
+  });
+
+  const app = {
+    listen: vi.fn(() => {
+      queueMicrotask(() => {
+        server.emit("listening");
+      });
+      return server;
+    }),
+  };
+
+  const spawn = vi.fn((command: string) => {
+    if (command === "pnpm") {
+      queueMicrotask(() => {
+        state.buildChild.emit("exit", 0);
+      });
+      return state.buildChild;
+    }
+
+    return state.electronChild;
+  });
+
+  return {
+    state,
+    createMockChild,
+    store,
+    server,
+    app,
+    spawn,
+    taskStoreCtor: vi.fn(() => store),
+    createServer: vi.fn(() => app),
+  };
+});
+
+vi.mock("node:child_process", () => ({
+  spawn: mocks.spawn,
+}));
+
+vi.mock("@fusion/core", () => ({
+  TaskStore: mocks.taskStoreCtor,
+}));
+
+vi.mock("@fusion/dashboard", () => ({
+  createServer: mocks.createServer,
+}));
+
+import { runDesktop } from "./desktop.js";
+
+describe("runDesktop", () => {
+  const originalCwd = process.cwd;
+  const originalExit = process.exit;
+  const originalElectronBinary = process.env.FUSION_ELECTRON_BINARY;
+  const originalDashboardUrl = process.env.FUSION_DASHBOARD_URL;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    process.env.FUSION_ELECTRON_BINARY = "electron-bin";
+    delete process.env.FUSION_DASHBOARD_URL;
+
+    mocks.state.buildChild = mocks.createMockChild();
+    mocks.state.electronChild = mocks.createMockChild();
+
+    mocks.server.address.mockReturnValue({ port: 4545 });
+    mocks.app.listen.mockImplementation(() => {
+      queueMicrotask(() => {
+        mocks.server.emit("listening");
+      });
+      return mocks.server;
+    });
+    mocks.server.close.mockImplementation((callback?: () => void) => {
+      callback?.();
+    });
+
+    vi.spyOn(process, "cwd").mockReturnValue("/repo");
+    process.exit = vi.fn() as never;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    process.cwd = originalCwd;
+    process.exit = originalExit;
+    if (originalElectronBinary === undefined) {
+      delete process.env.FUSION_ELECTRON_BINARY;
+    } else {
+      process.env.FUSION_ELECTRON_BINARY = originalElectronBinary;
+    }
+    if (originalDashboardUrl === undefined) {
+      delete process.env.FUSION_DASHBOARD_URL;
+    } else {
+      process.env.FUSION_DASHBOARD_URL = originalDashboardUrl;
+    }
+  });
+
+  it("builds desktop app, starts dashboard on random port, and launches Electron", async () => {
+    await runDesktop({ paused: true });
+
+    expect(mocks.spawn).toHaveBeenCalledWith(
+      "pnpm",
+      ["--filter", "@fusion/desktop", "build"],
+      expect.objectContaining({ cwd: "/repo" }),
+    );
+    expect(mocks.taskStoreCtor).toHaveBeenCalledWith("/repo");
+    expect(mocks.store.updateSettings).toHaveBeenCalledWith({ enginePaused: true });
+    expect(mocks.app.listen).toHaveBeenCalledWith(0);
+
+    expect(mocks.spawn).toHaveBeenCalledWith(
+      "electron-bin",
+      ["--enable-source-maps", "/repo/packages/desktop/dist/main.js"],
+      expect.objectContaining({
+        cwd: "/repo",
+        env: expect.objectContaining({
+          FUSION_DASHBOARD_URL: "http://localhost:4545",
+          FUSION_SERVER_PORT: "4545",
+        }),
+      }),
+    );
+
+    mocks.state.electronChild.emit("exit", 0);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
+  it("supports --dev mode by skipping build and pointing at Vite URL", async () => {
+    process.env.FUSION_DASHBOARD_URL = "http://localhost:5173";
+
+    await runDesktop({ dev: true });
+
+    const buildCalls = mocks.spawn.mock.calls.filter(([command]) => command === "pnpm");
+    expect(buildCalls).toHaveLength(0);
+
+    expect(mocks.spawn).toHaveBeenCalledWith(
+      "electron-bin",
+      ["--enable-source-maps", "/repo/packages/desktop/dist/main.js", "--dev"],
+      expect.objectContaining({
+        env: expect.objectContaining({
+          NODE_ENV: "development",
+          FUSION_DASHBOARD_URL: "http://localhost:5173",
+        }),
+      }),
+    );
+
+    mocks.state.electronChild.emit("exit", 0);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
+  it("cleans up dashboard runtime when Electron exits", async () => {
+    await runDesktop();
+
+    mocks.state.electronChild.emit("exit", 7);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(mocks.server.close).toHaveBeenCalledTimes(1);
+    expect(mocks.store.close).toHaveBeenCalledTimes(1);
+    expect(process.exit).toHaveBeenCalledWith(7);
+  });
+
+  it("handles SIGINT by terminating Electron and shutting down services", async () => {
+    await runDesktop();
+
+    process.emit("SIGINT");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(mocks.state.electronChild.kill).toHaveBeenCalledWith("SIGTERM");
+    expect(mocks.server.close).toHaveBeenCalledTimes(1);
+    expect(mocks.store.close).toHaveBeenCalledTimes(1);
+    expect(process.exit).toHaveBeenCalledWith(0);
+  });
+});

packages/cli/src/commands/desktop.ts

@@ -0,0 +1,170 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { once } from "node:events";
+import { join } from "node:path";
+import type { AddressInfo } from "node:net";
+import { createRequire } from "node:module";
+import { TaskStore } from "@fusion/core";
+import { createServer } from "@fusion/dashboard";
+
+const require = createRequire(import.meta.url);
+
+export interface RunDesktopOptions {
+  dev?: boolean;
+  paused?: boolean;
+  interactive?: boolean;
+}
+
+interface DashboardRuntime {
+  store: TaskStore;
+  server: import("node:http").Server;
+  port: number;
+}
+
+function runCommand(command: string, args: string[], cwd: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: "inherit",
+      env: process.env,
+    });
+
+    child.on("error", (error) => reject(error));
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(new Error(`${command} ${args.join(" ")} exited with code ${code ?? "unknown"}`));
+    });
+  });
+}
+
+async function buildDesktopArtifacts(rootDir: string): Promise<void> {
+  await runCommand("pnpm", ["--filter", "@fusion/desktop", "build"], rootDir);
+}
+
+async function startDashboardRuntime(rootDir: string, paused: boolean): Promise<DashboardRuntime> {
+  const store = new TaskStore(rootDir);
+  await store.init();
+  await store.watch();
+
+  if (paused) {
+    await store.updateSettings({ enginePaused: true });
+  }
+
+  const app = createServer(store);
+  const server = app.listen(0);
+
+  try {
+    await Promise.race([
+      once(server, "listening"),
+      once(server, "error").then(([error]) => {
+        throw error;
+      }),
+    ]);
+  } catch (error) {
+    store.close();
+    throw error;
+  }
+
+  const address = server.address() as AddressInfo | null;
+  if (!address?.port) {
+    server.close();
+    store.close();
+    throw new Error("Failed to determine dashboard server port");
+  }
+
+  return {
+    store,
+    server,
+    port: address.port,
+  };
+}
+
+async function closeDashboardRuntime(runtime: DashboardRuntime): Promise<void> {
+  await new Promise<void>((resolve) => {
+    runtime.server.close(() => resolve());
+  });
+  runtime.store.close();
+}
+
+function resolveElectronBinary(): string {
+  if (process.env.FUSION_ELECTRON_BINARY) {
+    return process.env.FUSION_ELECTRON_BINARY;
+  }
+
+  return require("electron") as string;
+}
+
+function terminateProcess(child: ChildProcess | null, signal: NodeJS.Signals = "SIGTERM"): void {
+  if (!child || child.killed) {
+    return;
+  }
+
+  child.kill(signal);
+}
+
+export async function runDesktop(options: RunDesktopOptions = {}): Promise<void> {
+  const rootDir = process.cwd();
+
+  if (!options.dev) {
+    await buildDesktopArtifacts(rootDir);
+  }
+
+  const runtime = await startDashboardRuntime(rootDir, Boolean(options.paused));
+  const rendererUrl = options.dev
+    ? process.env.FUSION_DASHBOARD_URL ?? "http://localhost:5173"
+    : `http://localhost:${runtime.port}`;
+
+  const electronBinary = resolveElectronBinary();
+  const desktopEntry = join(rootDir, "packages", "desktop", "dist", "main.js");
+  const electronArgs = ["--enable-source-maps", desktopEntry, ...(options.dev ? ["--dev"] : [])];
+
+  const electronProcess = spawn(electronBinary, electronArgs, {
+    cwd: rootDir,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      FUSION_DASHBOARD_URL: rendererUrl,
+      FUSION_SERVER_PORT: String(runtime.port),
+      ...(options.dev ? { NODE_ENV: "development" } : {}),
+    },
+  });
+
+  let isShuttingDown = false;
+
+  const shutdown = async (exitCode: number): Promise<void> => {
+    if (isShuttingDown) {
+      return;
+    }
+    isShuttingDown = true;
+
+    process.off("SIGINT", onSigint);
+    process.off("SIGTERM", onSigterm);
+
+    terminateProcess(electronProcess);
+    await closeDashboardRuntime(runtime);
+    process.exit(exitCode);
+  };
+
+  const onSigint = () => {
+    void shutdown(0);
+  };
+
+  const onSigterm = () => {
+    void shutdown(0);
+  };
+
+  process.on("SIGINT", onSigint);
+  process.on("SIGTERM", onSigterm);
+
+  electronProcess.on("error", (error) => {
+    console.error(`Failed to launch Electron: ${(error as Error).message}`);
+    void shutdown(1);
+  });
+
+  electronProcess.on("exit", (code) => {
+    void shutdown(code ?? 0);
+  });
+}

packages/cli/vitest.config.ts

@@ -6,7 +6,9 @@ export default defineConfig({
   test: {
     include: ["src/**/*.test.ts"],
     maxWorkers,
-    fileParallelism: true,
+    // build-exe and build-exe-cross suites both operate on packages/cli/dist/
+    // and can race when run in parallel workers.
+    fileParallelism: false,
     coverage: {
       enabled: false,
       reporter: ["text", "html", "json"],