fix(ports): auto-fallback for the gateway (7878) and media (7879) ports

Increment 3+4 of the free-port work. The gateway and loopback media
server now scan upward from their preferred port when a second Off Grid
instance already holds it, matching the llama engine (8439) fallback.

- model-server: startModelServer picks a free gateway port via
  pickFreePort; getGatewayPort() exposes the live bound port; async now,
  so fire-and-forget callers (ipc, index) use void.
- setup: health pings read the LIVE ports (llm.getPort() /
  getGatewayPort()), never the fixed constants.
- media-server: listenOnFreePort scans from MEDIA_PORT; urlFor already
  serves the live boundPort.
- wiring guards extended for gateway + setup live-port reads; media
  fallback integration test.

Author: alichherawalla

src/main/__tests__/media-server.integration.test.ts

@@ -90,3 +90,24 @@ describe('loopback media server integration', () => {
     await expect(server.urlFor(path.join(profile, 'captures', 'missing.png'))).resolves.toBeNull()
   })
 })
+
+describe('LoopbackMediaServer — free-port fallback', () => {
+  it('binds a DIFFERENT free port when the preferred one is already taken', async () => {
+    const net = await import('node:net')
+    // Occupy a port, then ask the media server to use THAT preferred port.
+    const blocker = net.createServer()
+    await new Promise<void>((r) => blocker.listen(0, '127.0.0.1', r))
+    const taken = (blocker.address() as import('node:net').AddressInfo).port
+    const media = new LoopbackMediaServer({ roots: localMediaRoots(profile), port: taken, token: 't' })
+    try {
+      await media.start()
+      // Fell back: bound a real, DIFFERENT port (not the occupied one) — and urlFor serves it.
+      const url = await media.urlFor(fixturePath('image'))
+      expect(url).toContain('http://127.0.0.1:')
+      expect(url).not.toContain(`:${taken}/`)
+    } finally {
+      await media.close()
+      await new Promise<void>((r) => blocker.close(() => r()))
+    }
+  })
+})

src/main/__tests__/model-port-ownership.integration.test.ts

@@ -1,11 +1,13 @@
 /**
- * RELEASE_TEST_CHECKLIST #146 - fixed model ports are single-owner.
+ * RELEASE_TEST_CHECKLIST #146 - a held model port never dead-ends the app.
  *
  * The first owner is either the already-running healthy production llama-server or a separate
  * process launching the only fake: a behaviour-faithful native llama-server boundary on the real
- * production port. The contender is the production LLMService. Real lsof/ps parent ownership,
- * loopback HTTP, GGUF validation, model resolution, startup refusal, error classification, and
- * chat-health presentation remain real. Cleanup only owns processes this test spawned.
+ * production port. The contender is the production LLMService, which - rather than refusing when
+ * the preferred port is taken - scans upward for a free port and starts its own engine there, so
+ * the app works even when something else holds :8439. Real lsof/ps parent ownership, loopback
+ * HTTP, GGUF validation, model resolution, free-port fallback, and chat-health presentation
+ * remain real. Cleanup only owns processes this test spawned.
  */
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
 import { execSync, spawn, type ChildProcess } from 'node:child_process'
@@ -73,10 +75,14 @@ const server = http.createServer((req, res) => {
 server.listen(port, '127.0.0.1', () => {
     const address = server.address()
     const actualPort = typeof address === 'object' && address ? address.port : port
-    fs.appendFileSync(
-      process.env.OFFGRID_TEST_ENGINE_LOG,
-      String(process.pid) + ':' + String(actualPort) + '\\n'
-    )
+    // Only the test-spawned FIRST owner sets this log; the production LLMService spawning the
+    // same binary on its fallback port does NOT, so it must not crash on a missing log path.
+    if (process.env.OFFGRID_TEST_ENGINE_LOG) {
+      fs.appendFileSync(
+        process.env.OFFGRID_TEST_ENGINE_LOG,
+        String(process.pid) + ':' + String(actualPort) + '\\n'
+      )
+    }
 })
 process.on('SIGTERM', () => server.close(() => process.exit(0)))
 `
@@ -233,19 +239,24 @@ afterAll(async () => {
 })
 
 describe('model port ownership', () => {
-  it('preserves the first live engine and explains the second-instance conflict (#146)', async () => {
+  it('preserves the first live engine and falls back to a free port for the second (#146)', async () => {
     const [{ llm }, { getSystemHealth }, { modelPortConflictReason }] = await Promise.all([
       import('../llm'),
       import('../setup'),
       import('../llama-error')
     ])
     const conflict = modelPortConflictReason(LLAMA_SERVER_PORT)
 
-    await expect(llm.init()).rejects.toThrow(conflict)
-    expect(llm.isReady()).toBe(false)
-    expect(llm.isStarting()).toBe(false)
-    expect(llm.lastError()).toBe(conflict)
+    // The preferred port is held by the first live engine. Rather than dead-ending on a
+    // single-owner conflict, the second instance scans upward and starts its own engine on a
+    // free port — the app just works even when something else holds :8439.
+    await llm.init()
+    expect(llm.isReady()).toBe(true)
+    expect(llm.getPort()).not.toBe(LLAMA_SERVER_PORT)
+    // The conflict reason is NOT surfaced — we moved instead of refusing.
+    expect(llm.lastError()).not.toBe(conflict)
 
+    // The FIRST engine is untouched: still alive, still the sole owner of the preferred port.
     expect(processIsAlive(enginePid)).toBe(true)
     expect(await engineIsReady()).toBe(true)
     if (liveOwner) {
@@ -254,9 +265,14 @@ describe('model port ownership', () => {
       ])
     }
 
+    // Chat health reports UP, on the fallback port — not down with a port-conflict detail.
     const chatHealth = (await getSystemHealth()).components.find(
       (component) => component.id === 'chat'
     )
-    expect(chatHealth).toMatchObject({ status: 'down', detail: conflict, port: LLAMA_SERVER_PORT })
+    expect(chatHealth).toMatchObject({ status: 'ready', port: llm.getPort() })
+    expect(chatHealth?.detail).not.toBe(conflict)
+
+    // Tear down the second engine this test started (the first owner is cleaned up in afterAll).
+    await llm.unload()
   })
 })

src/main/__tests__/port-fallback-wiring.test.ts

@@ -42,3 +42,30 @@ describe('model-server.ts — gateway proxies to the LIVE engine port', () => {
     expect(src).toMatch(/port: upstreamPort\(\)/)
   })
 })
+
+describe('model-server.ts — the gateway itself falls back off a held port', () => {
+  const src = read('model-server.ts')
+
+  it('scans for a free gateway port with pickFreePort before listening', () => {
+    expect(src).toMatch(/boundGatewayPort = \(await pickFreePort\(port\)\)/)
+    // It binds the LIVE chosen port, not the fixed GATEWAY_PORT constant.
+    expect(src).toMatch(/server\.listen\(boundGatewayPort/)
+  })
+
+  it('exposes the live gateway port via getGatewayPort()', () => {
+    expect(src).toMatch(/getGatewayPort\(\): number\s*{\s*return boundGatewayPort/)
+  })
+})
+
+describe('setup.ts — health pings read the LIVE ports, never fixed constants', () => {
+  const src = read('setup.ts')
+
+  it('pings the live llama engine port via llm.getPort()', () => {
+    expect(src).toMatch(/pingJson\(llm\.getPort\(\)\)/)
+  })
+
+  it('pings the live gateway port via getGatewayPort(), not a GATEWAY_PORT constant', () => {
+    expect(src).toMatch(/pingJson\(getGatewayPort\(\)\)/)
+    expect(src).not.toMatch(/\bLLAMA_PORT\b/)
+  })
+})

src/main/index.ts

@@ -199,7 +199,7 @@ app.whenReady().then(() => {
       }
     }
     try {
-      startModelServer()
+      void startModelServer()
     } catch (e) {
       console.error('[gateway] start failed', e)
     }
@@ -329,7 +329,7 @@ app.whenReady().then(() => {
     setupIPC()
     setupRagIPC()
     setupMcpIpc() // basic MCP connectors (management + chat tool extension)
-    startModelServer() // one OpenAI-compatible local gateway on :7878 (LLM + STT)
+    void startModelServer() // one OpenAI-compatible local gateway (LLM + STT); auto-picks a free port
     startMediaServer() // loopback HTTP for seekable local media (meeting videos)
     // Heal a stale active-model.json whose model gained a vision projector after it was
     // activated (e.g. Gemma 4 E2B) — turns vision on at launch if the projector is now

src/main/ipc.ts

@@ -1652,7 +1652,7 @@ export function setupIPC() {
       } catch {
         /* not running */
       }
-      startModelServer() // re-listens; if the port is held by a non-Off-Grid process it logs and no-ops
+      void startModelServer() // re-listens; falls back to a free port if the preferred one is held
       return { success: true }
     }
     return { success: false, error: `cannot restart "${id}"` }

src/main/media-server.ts

@@ -18,6 +18,7 @@ import { randomUUID } from 'crypto'
 import { app } from 'electron'
 import { parseRange, isPathAllowed } from './media-range'
 import { MEDIA_PORT } from '../shared/ports'
+import { pickFreePort } from './free-port'
 import { mimeForExt } from './mime'
 import { localMediaRoots } from './media-roots'
 
@@ -62,10 +63,21 @@ export class LoopbackMediaServer {
   start(): Promise<void> {
     if (this.boundPort > 0) return Promise.resolve()
     if (this.startPromise) return this.startPromise
+    this.startPromise = this.listenOnFreePort()
+    return this.startPromise
+  }
 
+  private async listenOnFreePort(): Promise<void> {
+    // The preferred media port (MEDIA_PORT) may be taken by another Off Grid instance; scan upward
+    // for a free one. requestedPort 0 = let the OS assign (tests) — inherently free. urlFor() serves
+    // the LIVE boundPort, so downstream links follow wherever it bound.
+    const target =
+      this.requestedPort > 0
+        ? ((await pickFreePort(this.requestedPort)) ?? this.requestedPort)
+        : 0
     const candidate = http.createServer((req, res) => this.handle(req, res))
     this.server = candidate
-    this.startPromise = new Promise<void>((resolve, reject) => {
+    await new Promise<void>((resolve, reject) => {
       const fail = (error: Error): void => {
         if (this.server === candidate) {
           this.server = null
@@ -75,7 +87,7 @@ export class LoopbackMediaServer {
         reject(error)
       }
       candidate.once('error', fail)
-      candidate.listen(this.requestedPort, '127.0.0.1', () => {
+      candidate.listen(target, '127.0.0.1', () => {
         candidate.off('error', fail)
         candidate.on('error', (error) => console.error('[media-server]', error))
         const address = candidate.address()
@@ -89,7 +101,6 @@ export class LoopbackMediaServer {
         resolve()
       })
     })
-    return this.startPromise
   }
 
   async urlFor(absPath: string): Promise<string | null> {

src/main/model-server.ts

@@ -35,6 +35,7 @@ import { docsText, docsHtml, openApiSpec } from './api-docs'
 import { handleMcpRequest } from './mcp-server'
 import { llm, type LlmSettings } from './llm'
 import { GATEWAY_HOST, GATEWAY_PORT } from '../shared/ports'
+import { pickFreePort } from './free-port'
 import { retryWithDeadline } from './lib/retry'
 import { resolveDims } from './model-server/dimensions'
 import { guardProxyStreams } from './stream-guards'
@@ -929,9 +930,20 @@ async function handleImageEdit(
 }
 
 // ─── Server ──────────────────────────────────────────────────────────────────
-/** Start the unified local model gateway. Bound to loopback (local-only). */
-export function startModelServer(port = GATEWAY_PORT): void {
-  if (server) return
+/** The port the gateway actually bound. Falls back off GATEWAY_PORT when it's taken (a 2nd Off Grid
+ *  instance); consumers (setup health ping, the Gateway UI) must read this LIVE value. */
+let boundGatewayPort = GATEWAY_PORT
+export function getGatewayPort(): number {
+  return boundGatewayPort
+}
+let startingGateway = false
+
+/** Start the unified local model gateway. Bound to loopback (local-only). Async because it scans
+ *  for a free port when the preferred one is taken. */
+export async function startModelServer(port = GATEWAY_PORT): Promise<void> {
+  if (server || startingGateway) return
+  startingGateway = true
+  boundGatewayPort = (await pickFreePort(port)) ?? port
 
   server = http.createServer(async (req, res) => {
     res.setHeader('Access-Control-Allow-Origin', '*')
@@ -1211,9 +1223,10 @@ export function startModelServer(port = GATEWAY_PORT): void {
   server.on('error', (e) => console.error('[model-server]', e))
   // The gateway has no authentication. Bind the socket itself to loopback so no
   // route can become LAN-accessible through a missing per-handler authorization check.
-  server.listen(port, GATEWAY_HOST, () => {
-    console.log(`[model-server] multimodal gateway at http://${GATEWAY_HOST}:${port}/v1`)
+  server.listen(boundGatewayPort, GATEWAY_HOST, () => {
+    console.log(`[model-server] multimodal gateway at http://${GATEWAY_HOST}:${boundGatewayPort}/v1`)
   })
+  startingGateway = false
 }
 
 export function stopModelServer(): void {

src/main/setup.ts

@@ -17,7 +17,7 @@ import {
   setActiveModel,
   setActiveModalChoice
 } from './models-manager'
-import { LLAMA_SERVER_PORT, GATEWAY_PORT } from '../shared/ports'
+import { getGatewayPort } from './model-server'
 import { deviceNoun } from '../shared/device'
 import type {
   SystemHealthComponentContract,
@@ -50,7 +50,6 @@ export interface SetupProgress {
 }
 export type SetupProgressCb = (p: SetupProgress) => void
 
-const LLAMA_PORT = LLAMA_SERVER_PORT
 
 /** GET a localhost endpoint, parse JSON, with a short timeout. null on any failure. */
 function pingJson(port: number, path = '/health', timeoutMs = 1500): Promise<unknown | null> {
@@ -92,8 +91,8 @@ export async function getSystemHealth(): Promise<SystemHealth> {
 
   // Live probes (run in parallel): the chat server and the gateway.
   const [llamaHealth, gatewayHealth] = await Promise.all([
-    pingJson(LLAMA_PORT),
-    pingJson(GATEWAY_PORT)
+    pingJson(llm.getPort()),
+    pingJson(getGatewayPort())
   ])
 
   // Image generation is checked in-process (no HTTP) so it works even if the
@@ -134,15 +133,15 @@ export async function getSystemHealth(): Promise<SystemHealth> {
       label: 'Chat model (llama-server)',
       status: chat,
       detail: chatDetail,
-      port: LLAMA_PORT,
+      port: llm.getPort(),
       canRestart: modelsExist
     },
     {
       id: 'gateway',
       label: 'Local gateway',
       status: gatewayHealth ? 'ready' : 'down',
       detail: gatewayHealth ? 'OpenAI-compatible API' : 'Not responding',
-      port: GATEWAY_PORT,
+      port: getGatewayPort(),
       canRestart: true
     },
     {
@@ -403,7 +402,7 @@ export async function autoConfigure(
   }
 
   emit({ phase: 'verify', message: 'Verifying…', modelId: model.id, modelName: model.name })
-  const ok = !!(await pingJson(LLAMA_PORT, '/health', 3000))
+  const ok = !!(await pingJson(llm.getPort(), '/health', 3000))
 
   // Chat is live — now set up the rest of the baseline (speech-to-text, text-to-
   // speech, and image outside Conservative). These are best-effort: a failure here