@blackbelt-technology/pi-agent-dashboard 0.2.1 → 0.2.3

package/packages/server/src/__tests__/known-servers-routes.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { writeConfigPartial } from "../config-api.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { DiscoveredServer } from "@blackbelt-technology/pi-dashboard-shared/mdns-discovery.js";
+
+describe("known-servers CRUD", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(os.tmpdir(), `test-known-servers-${Date.now()}`);
+    fs.mkdirSync(path.join(testDir, ".pi", "dashboard"), { recursive: true });
+    configFile = path.join(testDir, ".pi", "dashboard", "config.json");
+    fs.writeFileSync(configFile, JSON.stringify({}));
+    origHome = process.env.HOME!;
+    process.env.HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("should default to empty knownServers", () => {
+    const config = loadConfig();
+    expect(config.knownServers).toEqual([]);
+  });
+
+  it("should add a known server", () => {
+    const server = { host: "office-mac", port: 8000, label: "Office", addedAt: new Date().toISOString() };
+    writeConfigPartial({ knownServers: [server] });
+    const config = loadConfig();
+    expect(config.knownServers).toHaveLength(1);
+    expect(config.knownServers[0].host).toBe("office-mac");
+    expect(config.knownServers[0].port).toBe(8000);
+    expect(config.knownServers[0].label).toBe("Office");
+  });
+
+  it("should update label on duplicate host:port", () => {
+    const servers = [
+      { host: "office-mac", port: 8000, label: "Old Label", addedAt: new Date().toISOString() },
+    ];
+    writeConfigPartial({ knownServers: servers });
+
+    // Simulate "add duplicate" by reading, updating, writing
+    const config = loadConfig();
+    const existing = config.knownServers;
+    const idx = existing.findIndex((s) => s.host === "office-mac" && s.port === 8000);
+    expect(idx).toBe(0);
+    existing[idx] = { ...existing[idx], label: "New Label" };
+    writeConfigPartial({ knownServers: existing });
+
+    const updated = loadConfig();
+    expect(updated.knownServers).toHaveLength(1);
+    expect(updated.knownServers[0].label).toBe("New Label");
+  });
+
+  it("should remove a known server", () => {
+    const servers = [
+      { host: "office-mac", port: 8000, label: "Office", addedAt: new Date().toISOString() },
+      { host: "build-server", port: 8000, label: "Build", addedAt: new Date().toISOString() },
+    ];
+    writeConfigPartial({ knownServers: servers });
+
+    const config = loadConfig();
+    const filtered = config.knownServers.filter((s) => !(s.host === "office-mac" && s.port === 8000));
+    writeConfigPartial({ knownServers: filtered });
+
+    const updated = loadConfig();
+    expect(updated.knownServers).toHaveLength(1);
+    expect(updated.knownServers[0].host).toBe("build-server");
+  });
+
+  it("should be idempotent when removing non-existent server", () => {
+    const servers = [
+      { host: "office-mac", port: 8000, label: "Office", addedAt: new Date().toISOString() },
+    ];
+    writeConfigPartial({ knownServers: servers });
+
+    const config = loadConfig();
+    const filtered = config.knownServers.filter((s) => !(s.host === "nonexistent" && s.port === 9999));
+    writeConfigPartial({ knownServers: filtered });
+
+    const updated = loadConfig();
+    expect(updated.knownServers).toHaveLength(1);
+  });
+
+  it("should list known servers from config", () => {
+    const servers = [
+      { host: "a", port: 8000, addedAt: "2024-01-01T00:00:00Z" },
+      { host: "b", port: 9000, label: "B Server", addedAt: "2024-01-02T00:00:00Z" },
+    ];
+    writeConfigPartial({ knownServers: servers });
+
+    const config = loadConfig();
+    expect(config.knownServers).toHaveLength(2);
+    expect(config.knownServers[0].host).toBe("a");
+    expect(config.knownServers[1].label).toBe("B Server");
+  });
+
+  it("should handle entries without label", () => {
+    const servers = [{ host: "no-label", port: 8000, addedAt: "2024-01-01T00:00:00Z" }];
+    writeConfigPartial({ knownServers: servers });
+
+    const config = loadConfig();
+    expect(config.knownServers[0].label).toBeUndefined();
+  });
+
+  it("should ignore invalid entries in knownServers", () => {
+    // Write raw JSON with invalid entries
+    fs.writeFileSync(configFile, JSON.stringify({
+      knownServers: [
+        { host: "valid", port: 8000, addedAt: "2024-01-01T00:00:00Z" },
+        { host: "no-port" }, // missing port
+        "invalid-string",
+        null,
+        { port: 8000 }, // missing host
+      ],
+    }));
+
+    const config = loadConfig();
+    expect(config.knownServers).toHaveLength(1);
+    expect(config.knownServers[0].host).toBe("valid");
+  });
+});

package/packages/server/src/__tests__/process-manager.test.ts

@@ -168,7 +168,10 @@ describe("Process Manager", () => {
     it("should not duplicate managed bin if already present", () => {
       const managedBin = require("path").join(require("os").homedir(), ".pi-dashboard", "node_modules", ".bin");
       const env = buildSpawnEnv({ PATH: `${managedBin}:/usr/bin` });
-      expect(env.PATH).toBe(`${managedBin}:/usr/bin`);
+      // Managed bin should appear exactly once
+      const parts = env.PATH!.split(":");
+      const managedCount = parts.filter(p => p === managedBin).length;
+      expect(managedCount).toBe(1);
     });
   });
 

package/packages/server/src/__tests__/session-lifecycle-logging.test.ts

@@ -43,7 +43,7 @@ describe("Session lifecycle logging", () => {
     }));
     await delay(100);
 
-    const logs = errorSpy.mock.calls.map((c) => c[0]);
+    const logs = errorSpy.mock.calls.map((c: any) => c[0]);
     expect(logs).toContainEqual(expect.stringContaining("[gateway] session registered: log-reg cwd=/tmp/test"));
     ws.close();
   }, 10000);
@@ -64,7 +64,7 @@ describe("Session lifecycle logging", () => {
     ws.send(JSON.stringify({ type: "session_unregister", sessionId: "log-unreg" }));
     await delay(100);
 
-    const logs = errorSpy.mock.calls.map((c) => c[0]);
+    const logs = errorSpy.mock.calls.map((c: any) => c[0]);
     expect(logs).toContainEqual(expect.stringContaining("[gateway] session unregistered: log-unreg (explicit)"));
     ws.close();
   }, 10000);
@@ -87,7 +87,7 @@ describe("Session lifecycle logging", () => {
     ws.close();
     await delay(SHORT_HB + 300);
 
-    const logs = errorSpy.mock.calls.map((c) => c[0]);
+    const logs = errorSpy.mock.calls.map((c: any) => c[0]);
     expect(logs).toContainEqual(expect.stringContaining("[gateway] session timed out: log-timeout (no heartbeat for"));
   }, 10000);
 
@@ -107,7 +107,7 @@ describe("Session lifecycle logging", () => {
     ws.close();
     await delay(200);
 
-    const logs = errorSpy.mock.calls.map((c) => c[0]);
+    const logs = errorSpy.mock.calls.map((c: any) => c[0]);
     expect(logs).toContainEqual(expect.stringContaining("[gateway] connection closed: log-close"));
   }, 10000);
 
@@ -132,7 +132,7 @@ describe("Session lifecycle logging", () => {
     (ws as any)._socket?.pause();
     await delay(200 * 4);
 
-    const logs = errorSpy.mock.calls.map((c) => c[0]);
+    const logs = errorSpy.mock.calls.map((c: any) => c[0]);
     expect(logs).toContainEqual(expect.stringContaining("[gateway] connection dead (ping timeout, 2 misses): log-ping"));
   }, 10000);
 });

package/packages/server/src/__tests__/tunnel.test.ts

@@ -7,7 +7,7 @@ vi.mock("node:fs", async (importOriginal) => {
   return {
     ...actual,
     default: {
-      ...actual.default,
+      ...(actual as any).default,
       existsSync: vi.fn(),
       readFileSync: vi.fn(),
       writeFileSync: vi.fn(),
@@ -25,7 +25,7 @@ vi.mock("node:os", async (importOriginal) => {
   const actual = await importOriginal<typeof import("node:os")>();
   return {
     ...actual,
-    default: { ...actual.default, homedir: vi.fn(() => "/home/testuser") },
+    default: { ...(actual as any).default, homedir: vi.fn(() => "/home/testuser") },
     homedir: vi.fn(() => "/home/testuser"),
   };
 });

package/packages/server/src/browser-gateway.ts

@@ -41,6 +41,10 @@ export interface BrowserGateway {
   trackUiRequest(sessionId: string, requestId: string, method: string, params: Record<string, unknown>): boolean | void;
   /** Clear a pending interactive UI request (resolved or cancelled) */
   clearUiRequest(sessionId: string, requestId: string): void;
+  /** Track a pending PromptBus request for replay on browser refresh */
+  trackPromptRequest(sessionId: string, msg: Record<string, unknown>): void;
+  /** Clear a pending PromptBus request (dismissed or cancelled) */
+  clearPromptRequest(sessionId: string, promptId: string): void;
   /** Tell browser subscribers to reset accumulated state for a session (bridge reconnected) */
   broadcastSessionStateReset(sessionId: string): void;
   /** Shut down all tracked headless child processes */
@@ -83,6 +87,9 @@ export function createBrowserGateway(
   // Track pending interactive UI requests per session for replay on reconnect
   const pendingUiRequests = new Map<string, Map<string, { requestId: string; method: string; params: Record<string, unknown> }>>();
 
+  // Track pending PromptBus requests per session for replay on browser refresh
+  const pendingPromptRequests = new Map<string, Map<string, Record<string, unknown>>>();
+
   // Track pending auto-resume prompts for ended sessions
   const pendingResumeRegistry = createPendingResumeRegistry({
     onTimeout(oldSessionId) {
@@ -95,15 +102,23 @@ export function createBrowserGateway(
   /** Send any pending interactive UI requests to a specific browser socket */
   function replayPendingUiRequests(ws: WebSocket, sessionId: string) {
     const sessionPending = pendingUiRequests.get(sessionId);
-    if (!sessionPending) return;
-    for (const req of sessionPending.values()) {
-      sendTo(ws, {
-        type: "extension_ui_request",
-        sessionId,
-        requestId: req.requestId,
-        method: req.method,
-        params: req.params,
-      });
+    if (sessionPending) {
+      for (const req of sessionPending.values()) {
+        sendTo(ws, {
+          type: "extension_ui_request",
+          sessionId,
+          requestId: req.requestId,
+          method: req.method,
+          params: req.params,
+        });
+      }
+    }
+    // Also replay pending PromptBus requests
+    const sessionPrompts = pendingPromptRequests.get(sessionId);
+    if (sessionPrompts) {
+      for (const msg of sessionPrompts.values()) {
+        sendTo(ws, msg as any);
+      }
     }
   }
 
@@ -125,6 +140,26 @@ export function createBrowserGateway(
     return true;
   }
 
+  function trackPromptRequest(sessionId: string, msg: Record<string, unknown>): void {
+    let sessionMap = pendingPromptRequests.get(sessionId);
+    if (!sessionMap) {
+      sessionMap = new Map();
+      pendingPromptRequests.set(sessionId, sessionMap);
+    }
+    const promptId = msg.promptId as string;
+    if (promptId) {
+      sessionMap.set(promptId, msg);
+    }
+  }
+
+  function clearPromptRequest(sessionId: string, promptId: string): void {
+    const sessionMap = pendingPromptRequests.get(sessionId);
+    if (sessionMap) {
+      sessionMap.delete(promptId);
+      if (sessionMap.size === 0) pendingPromptRequests.delete(sessionId);
+    }
+  }
+
   function getSubscribers(sessionId: string): WebSocket[] {
     const result: WebSocket[] = [];
     for (const [ws, subs] of subscriptions) {
@@ -321,6 +356,12 @@ export function createBrowserGateway(
             break;
           }
 
+          case "prompt_response": {
+            // Route PromptBus response from browser to extension
+            ctx.piGateway.sendToSession((msg as any).sessionId, msg as any);
+            break;
+          }
+
           case "flow_management": {
             ctx.piGateway.sendToSession(msg.sessionId, {
               type: "flow_management",
@@ -333,13 +374,8 @@ export function createBrowserGateway(
             break;
           }
           case "architect_prompt_response": {
-            ctx.piGateway.sendToSession(msg.sessionId, {
-              type: "architect_prompt_response",
-              sessionId: msg.sessionId,
-              promptId: msg.promptId,
-              answer: msg.answer,
-              cancelled: msg.cancelled,
-            });
+            // Legacy: now handled by prompt_response via PromptBus.
+            // Keep case to avoid "unhandled message" warnings from old clients.
             break;
           }
           case "role_set": {
@@ -482,6 +518,9 @@ export function createBrowserGateway(
       }
     },
 
+    trackPromptRequest,
+    clearPromptRequest,
+
     shutdownHeadlessProcesses() {
       headlessPidRegistry.killAll();
     },

package/packages/server/src/cli.ts

@@ -218,7 +218,7 @@ function findPortHolders(port: number): number[] {
   try {
     const { execSync } = require("node:child_process");
     const output = execSync(`lsof -t -i :${port} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf-8" });
-    return output.trim().split("\n").map(Number).filter(n => n > 0 && n !== process.pid);
+    return output.trim().split("\n").map(Number).filter((n: number) => n > 0 && n !== process.pid);
   } catch { return []; }
 }
 

package/packages/server/src/editor-manager.ts

@@ -207,7 +207,7 @@ export function createEditorManager(options: EditorManagerOptions): EditorManage
         if (inst.status === "starting") {
           // Wait for it to become ready
           const ready = await waitForPort(inst.port);
-          if (ready && inst.status !== "stopped") {
+          if (ready && (inst.status as string) !== "stopped") {
             setStatus(inst, "ready");
             startIdleTimer(inst);
           }

package/packages/server/src/event-status-extraction.ts

@@ -117,6 +117,13 @@ export function extractSessionUpdates(event: DashboardEvent): SessionUpdates | n
       };
     }
 
+    case "flow_summary_dismissed": {
+      return {
+        activeFlowName: null,
+        flowStatus: null,
+      };
+    }
+
     case "architect_complete":
     case "architect_cancelled": {
       return {

package/packages/server/src/event-wiring.ts

@@ -85,7 +85,7 @@ export function wireEvents(deps: EventWiringDeps): void {
             const session = sessionManager.get(sessionId);
             updates.flowAgentsDone = (session?.flowAgentsDone ?? 0) + 1;
           }
-          sessionManager.update(sessionId, updates);
+          sessionManager.update(sessionId, updates as Partial<DashboardSession>);
         }
         // Skip insert + broadcast — events are already in store
         // Still need to continue to the rest of the handler for openspec/stats
@@ -105,7 +105,7 @@ export function wireEvents(deps: EventWiringDeps): void {
           const session = sessionManager.get(sessionId);
           updates.flowAgentsDone = (session?.flowAgentsDone ?? 0) + 1;
         }
-        sessionManager.update(sessionId, updates);
+        sessionManager.update(sessionId, updates as Partial<DashboardSession>);
         // During replay, accumulate in sessionManager but don't broadcast
         // to avoid rapid status flickers on the session card
         if (!replayingSessions.has(sessionId)) {
@@ -135,10 +135,11 @@ export function wireEvents(deps: EventWiringDeps): void {
           if (changed) {
             sessionManager.update(sessionId, activityUpdates);
             const updatedSession = sessionManager.get(sessionId);
-            // Auto-attach proposal when changeName is detected (phase is optional —
-            // skills loaded via prompt templates don't emit a SKILL.md read event)
+            // Auto-attach proposal when changeName is detected via active operations
+            // (write/CLI). Reads are passive (browsing/analysis) and don't trigger attach.
+            // Phase is optional — skills loaded via prompt templates don't emit a SKILL.md read event.
             const attachUpdates: Partial<DashboardSession> = {};
-            if (updatedSession?.openspecChange && !updatedSession.attachedProposal) {
+            if (updatedSession?.openspecChange && !updatedSession.attachedProposal && detected.isActive) {
               attachUpdates.attachedProposal = updatedSession.openspecChange;
               if (!updatedSession.name?.trim()) {
                 attachUpdates.name = updatedSession.openspecChange;
@@ -504,25 +505,22 @@ export function wireEvents(deps: EventWiringDeps): void {
       browserGateway.broadcastSessionUpdated(sessionId, modelUpdates);
     }
 
-    if (msg.type === "extension_ui_request") {
-      const tracked = browserGateway.trackUiRequest(sessionId, msg.requestId, msg.method, msg.params);
-      if (tracked !== false) {
-        browserGateway.sendToSubscribers(sessionId, {
-          type: "extension_ui_request",
-          sessionId,
-          requestId: msg.requestId,
-          method: msg.method,
-          params: msg.params,
-        });
-      }
+    // Legacy extension_ui_request/dismiss removed — replaced by PromptBus protocol.
+
+    // ── PromptBus protocol messages (extension → browser) ──
+    if (msg.type === "prompt_request") {
+      browserGateway.trackPromptRequest(sessionId, msg as any);
+      browserGateway.sendToSubscribers(sessionId, msg as any);
     }
 
-    if (msg.type === "extension_ui_dismiss") {
-      browserGateway.sendToSubscribers(sessionId, {
-        type: "ui_dismiss",
-        sessionId,
-        requestId: msg.requestId,
-      });
+    if (msg.type === "prompt_dismiss") {
+      browserGateway.clearPromptRequest(sessionId, (msg as any).promptId);
+      browserGateway.sendToSubscribers(sessionId, msg as any);
+    }
+
+    if (msg.type === "prompt_cancel") {
+      browserGateway.clearPromptRequest(sessionId, (msg as any).promptId);
+      browserGateway.sendToSubscribers(sessionId, msg as any);
     }
 
     if (msg.type === "session_name_update") {

package/packages/server/src/package-manager-wrapper.ts

@@ -23,7 +23,7 @@ async function loadPiPackageManager() {
 
   // Try direct import first (works if installed as a dependency)
   try {
-    const mod = await import("@mariozechner/pi-coding-agent");
+    const mod = await import("@mariozechner/pi-coding-agent") as any;
     if (mod.DefaultPackageManager) {
       piModuleCache = { DefaultPackageManager: mod.DefaultPackageManager, SettingsManager: mod.SettingsManager };
       return piModuleCache;

package/packages/server/src/process-manager.ts

@@ -6,53 +6,17 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import type { SpawnStrategy } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { MANAGED_BIN } from "@blackbelt-technology/pi-dashboard-shared/managed-paths.js";
+import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/tool-resolver.js";
 
-/** Path to managed install bin directory */
-const MANAGED_BIN = path.join(os.homedir(), ".pi-dashboard", "node_modules", ".bin");
-
-/** Common user bin directories that may not be on PATH when launched from
- *  a desktop .desktop file or Electron app (shell profiles not sourced). */
-function getUserBinDirs(): string[] {
-  const home = os.homedir();
-  const dirs = [
-    path.join(home, ".local", "bin"),           // pip, install.sh scripts
-    path.join(home, ".npm-global", "bin"),       // npm config prefix
-    "/usr/local/bin",                            // brew, manual installs
-  ];
-  return dirs.filter(d => existsSync(d));
-}
+/** Server-side resolver — knows the current process node binary. */
+const resolver = new ToolResolver({ processExecPath: process.execPath });
 
 /** Build env with managed install bin + current node binary dir prepended to PATH.
- *  Ensures `pi`, `node`, and user-installed tools (code-server) are findable.
- *  This is critical when launched from Electron (no shell profile sourced).
+ *  Delegates to ToolResolver.buildSpawnEnv().
  */
 export function buildSpawnEnv(baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  const currentPath = baseEnv.PATH || "";
-  const parts: string[] = [];
-
-  // Always ensure managed bin is on PATH (for pi, openspec, tsx)
-  if (!currentPath.includes(MANAGED_BIN)) {
-    parts.push(MANAGED_BIN);
-  }
-
-  // Always ensure the current node binary's directory is on PATH.
-  // Handles bundled Node.js (e.g., /usr/lib/pi-dashboard/resources/node/bin/node)
-  // where spawned scripts use #!/usr/bin/env node.
-  const nodeBinDir = path.dirname(process.execPath);
-  if (!currentPath.includes(nodeBinDir)) {
-    parts.push(nodeBinDir);
-  }
-
-  // Add common user bin directories that Electron apps miss
-  // (desktop launchers don't source ~/.bashrc / ~/.profile)
-  for (const dir of getUserBinDirs()) {
-    if (!currentPath.includes(dir)) {
-      parts.push(dir);
-    }
-  }
-
-  if (parts.length === 0) return baseEnv;
-  return { ...baseEnv, PATH: `${parts.join(path.delimiter)}${path.delimiter}${currentPath}` };
+  return resolver.buildSpawnEnv(baseEnv);
 }
 
 export interface PlatformInfo {
@@ -134,35 +98,10 @@ export function buildHeadlessArgs(options?: SessionOptions): string[] {
 }
 
 /** Resolve the pi command as [command, ...prefixArgs].
- *  On Unix: returns ["path/to/pi"]
- *  On Windows: returns ["path/to/node.exe", "path/to/pi/dist/cli.mjs"] to avoid .cmd
+ *  Delegates to ToolResolver.resolvePi().
  */
 function resolvePiCommand(): string[] | null {
-  if (process.platform === "win32") {
-    // Try to resolve pi's CLI entry point directly (avoids .cmd → no cmd window)
-    const piCli = path.join(MANAGED_BIN, "..", "@mariozechner", "pi-coding-agent", "dist", "cli.js");
-    if (existsSync(piCli)) {
-      // Find node.exe: process.execPath is the current node binary
-      return [process.execPath, piCli];
-    }
-    // Fallback to .cmd
-    const managed = path.join(MANAGED_BIN, "pi.cmd");
-    if (existsSync(managed)) return [managed];
-  } else {
-    const managed = path.join(MANAGED_BIN, "pi");
-    if (existsSync(managed)) return [managed];
-  }
-  // System PATH
-  try {
-    const whichCmd = process.platform === "win32" ? "where" : "which";
-    const result = execSync(`${whichCmd} pi`, {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      env: buildSpawnEnv(),
-    }).trim();
-    if (result) return [result.split("\n")[0]];
-  } catch { /* not found */ }
-  return null;
+  return resolver.resolvePi();
 }
 
 function spawnHeadless(cwd: string, options?: SessionOptions): SpawnResult {

package/packages/server/src/routes/known-servers-routes.ts

@@ -0,0 +1,110 @@
+/**
+ * REST routes for known servers management and network discovery.
+ */
+import type { FastifyInstance } from "fastify";
+import type { NetworkGuard } from "./route-deps.js";
+import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { KnownServer } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import type { DiscoveredServer } from "@blackbelt-technology/pi-dashboard-shared/mdns-discovery.js";
+import type {
+  AddKnownServerRequest,
+  RemoveKnownServerRequest,
+  DiscoveredServerInfo,
+} from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { writeConfigPartial } from "../config-api.js";
+
+export function registerKnownServersRoutes(
+  fastify: FastifyInstance,
+  deps: {
+    networkGuard: NetworkGuard;
+    getPeerServers: () => Map<string, DiscoveredServer>;
+  },
+) {
+  const { networkGuard, getPeerServers } = deps;
+
+  // List known servers from config
+  fastify.get(
+    "/api/known-servers",
+    { preHandler: networkGuard },
+    async (): Promise<ApiResponse<KnownServer[]>> => {
+      const config = loadConfig();
+      return { success: true, data: config.knownServers };
+    },
+  );
+
+  // Add or update a known server
+  fastify.post<{ Body: AddKnownServerRequest }>(
+    "/api/known-servers",
+    { preHandler: networkGuard },
+    async (request): Promise<ApiResponse> => {
+      const { host, port, label } = request.body;
+      if (!host || typeof port !== "number") {
+        return { success: false, error: "host and port are required" };
+      }
+
+      const config = loadConfig();
+      const existing = config.knownServers;
+      const idx = existing.findIndex((s) => s.host === host && s.port === port);
+
+      if (idx >= 0) {
+        // Update label on duplicate
+        existing[idx] = { ...existing[idx], ...(label !== undefined ? { label } : {}) };
+      } else {
+        existing.push({
+          host,
+          port,
+          ...(label ? { label } : {}),
+          addedAt: new Date().toISOString(),
+        });
+      }
+
+      const result = writeConfigPartial({ knownServers: existing });
+      if (!result.success) {
+        return { success: false, error: result.error };
+      }
+      return { success: true };
+    },
+  );
+
+  // Remove a known server
+  fastify.delete<{ Body: RemoveKnownServerRequest }>(
+    "/api/known-servers",
+    { preHandler: networkGuard },
+    async (request): Promise<ApiResponse> => {
+      const { host, port } = request.body;
+      if (!host || typeof port !== "number") {
+        return { success: false, error: "host and port are required" };
+      }
+
+      const config = loadConfig();
+      const filtered = config.knownServers.filter(
+        (s) => !(s.host === host && s.port === port),
+      );
+
+      const result = writeConfigPartial({ knownServers: filtered });
+      if (!result.success) {
+        return { success: false, error: result.error };
+      }
+      return { success: true };
+    },
+  );
+
+  // On-demand network discovery — returns current mDNS peers
+  fastify.post(
+    "/api/discover-servers",
+    { preHandler: networkGuard },
+    async (): Promise<ApiResponse<DiscoveredServerInfo[]>> => {
+      const peers = getPeerServers();
+      const data: DiscoveredServerInfo[] = Array.from(peers.values()).map((s) => ({
+        host: s.host,
+        port: s.port,
+        piPort: s.piPort,
+        version: s.version,
+        pid: s.pid,
+        isLocal: s.isLocal,
+      }));
+      return { success: true, data };
+    },
+  );
+}

package/packages/server/src/routes/system-routes.ts

@@ -26,9 +26,10 @@ export function registerSystemRoutes(
     metaPersistence: MetaPersistence;
     config: ServerConfig;
     networkGuard: NetworkGuard;
+    version?: string;
   },
 ) {
-  const { sessionManager, preferencesStore, metaPersistence, config, networkGuard } = deps;
+  const { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version } = deps;
   const serverStartTime = Date.now();
 
   // Editor detection endpoint
@@ -164,6 +165,7 @@ export function registerSystemRoutes(
     return {
       ok: true,
       pid: process.pid,
+      version: version ?? "unknown",
       uptime: Math.floor((Date.now() - serverStartTime) / 1000),
       mode: config.dev ? "dev" : "production",
       server: {