feat(net): llama-server falls back to a free port when :8439 is taken (increment 2)

prepareModelPort used to THROW a hard conflict when another live app owned :8439 (LM Studio, a 2nd
instance) — dead-ending the engine. Now it scans upward (pickFreePort) and binds the next free port;
it only surfaces the conflict if the whole window is occupied. llm.getPort() exposes the LIVE port,
and the gateway (model-server) now proxies to llm.getPort() per-request instead of a fixed
UPSTREAM_PORT const — so an engine that moved to 8440 still gets its traffic. The app talks to
this.port directly, so it follows automatically.

Tests: free-port behavioral (selection + real socket probe, 7); port-fallback-wiring source guards
(fallback-not-throw + this.port=free + getPort + gateway reads llm.getPort(), no stale const) (5).
llm.ts/model-server.ts are coverage-excluded native shells — pure logic lives in free-port (tested).

Author: alichherawalla

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

@@ -0,0 +1,44 @@
+// @vitest-environment node
+// llm.ts and model-server.ts are coverage-excluded native/spawn/IPC shells; the selection logic is
+// behaviorally tested in free-port.test.ts. These source guards lock the WIRING so it can't silently
+// regress: (1) a port conflict falls back to a free port instead of throwing; (2) the gateway proxies
+// to the LIVE engine port, never a fixed constant.
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const read = (rel: string): string => readFileSync(join(__dirname, '..', rel), 'utf8')
+
+describe('llm.ts — port conflict falls back to a free port', () => {
+  const src = read('llm.ts')
+
+  it('scans for a free port with pickFreePort when another app owns the preferred one', () => {
+    expect(src).toMatch(/pickFreePort\(this\.port/)
+    // The chosen free port becomes the live port.
+    expect(src).toMatch(/this\.port = free/)
+  })
+
+  it('only surfaces the hard conflict when NO free port is found (not on first collision)', () => {
+    // The throw is gated behind `free === null`, not fired unconditionally on liveOwners.
+    expect(src).toMatch(/if \(free === null\)[\s\S]*?throw new Error/)
+  })
+
+  it('exposes the live port via getPort()', () => {
+    expect(src).toMatch(/getPort\(\): number\s*{\s*return this\.port/)
+  })
+})
+
+describe('model-server.ts — gateway proxies to the LIVE engine port', () => {
+  const src = read('model-server.ts')
+
+  it('reads llm.getPort() for the upstream, not a fixed constant', () => {
+    expect(src).toMatch(/upstreamPort = \(\): number => llm\.getPort\(\)/)
+    // No lingering fixed-constant upstream.
+    expect(src).not.toMatch(/const UPSTREAM_PORT = LLAMA_SERVER_PORT/)
+  })
+
+  it('every upstream request targets upstreamPort(), never a stale UPSTREAM_PORT', () => {
+    expect(src).not.toMatch(/\bUPSTREAM_PORT\b/)
+    expect(src).toMatch(/port: upstreamPort\(\)/)
+  })
+})

src/main/llm.ts

@@ -29,6 +29,7 @@ import {
 import { buildMessages, imageMime, thinkingPayload, type DecodedImage } from './llm/chat-payload'
 import { isValidGgufFile } from './models/gguf'
 import { readGgufContextLength } from './models/gguf-metadata'
+import { pickFreePort, isPortFree } from './free-port'
 import { postCompletionOnce } from './llm/http-post'
 import { streamCompletion, type StreamResult } from './llm/stream'
 import {
@@ -205,6 +206,13 @@ export class LLMService {
     return this.trainedContext()
   }
 
+  /** The port llama-server is actually on. Usually LLAMA_SERVER_PORT, but prepareModelPort moves it
+   *  to a free port when another app owns the preferred one — so consumers (the gateway upstream)
+   *  must read this LIVE value, never the constant. */
+  getPort(): number {
+    return this.port
+  }
+
   private safeCtxSize(requestedRaw: number): number {
     // First cap to the model's trained window (pure), THEN clamp to what RAM can hold.
     const trained = this.trainedContext()
@@ -785,9 +793,21 @@ export class LLMService {
   private async prepareModelPort(): Promise<void> {
     const ownership = this.reapOrphansOnPort(this.port)
     if (ownership.liveOwners.length > 0) {
-      this.lastErrorMsg = modelPortConflictReason(this.port)
-      console.error(`[LLMService] ${this.lastErrorMsg}`)
-      throw new Error(this.lastErrorMsg)
+      // Another LIVE app owns our preferred port (LM Studio on :8439, a second Off Grid instance).
+      // Don't fight it or dead-end — scan upward for the next free port and move there. The gateway
+      // proxies to llm.getPort() (live), and the app talks to this.port directly, so both follow.
+      const free = await pickFreePort(this.port, (p) => isPortFree(p))
+      if (free === null) {
+        this.lastErrorMsg = modelPortConflictReason(this.port)
+        console.error(`[LLMService] ${this.lastErrorMsg}`)
+        throw new Error(this.lastErrorMsg)
+      }
+      console.warn(
+        `[LLMService] port ${this.port} is owned by another app — falling back to free port ${free}`
+      )
+      this.port = free
+      this.lastErrorMsg = null
+      return
     }
     if (ownership.killed > 0) {
       await new Promise((resolve) => setTimeout(resolve, 400))

src/main/model-server.ts

@@ -34,7 +34,7 @@ import { embeddings } from './embeddings'
 import { docsText, docsHtml, openApiSpec } from './api-docs'
 import { handleMcpRequest } from './mcp-server'
 import { llm, type LlmSettings } from './llm'
-import { LLAMA_SERVER_PORT, GATEWAY_HOST, GATEWAY_PORT } from '../shared/ports'
+import { GATEWAY_HOST, GATEWAY_PORT } from '../shared/ports'
 import { retryWithDeadline } from './lib/retry'
 import { resolveDims } from './model-server/dimensions'
 import { guardProxyStreams } from './stream-guards'
@@ -56,7 +56,10 @@ import { safeProxyResponse } from './model-server/proxy-response'
 import { writeDiagnosticLog } from './diagnostics-log'
 
 const UPSTREAM_HOST = '127.0.0.1'
-const UPSTREAM_PORT = LLAMA_SERVER_PORT // bundled llama-server (see llm.ts)
+// The upstream llama-server port is LIVE, not fixed: llm.getPort() moves off LLAMA_SERVER_PORT when
+// another app owns it (see llm.prepareModelPort). Read it per-request so the gateway always proxies
+// to wherever the engine actually bound. (LLAMA_SERVER_PORT stays the PREFERRED default in llm.)
+const upstreamPort = (): number => llm.getPort()
 const MAX_UPLOAD = 200 * 1024 * 1024 // 200MB upload cap (audio / init image)
 
 let server: http.Server | null = null
@@ -197,7 +200,7 @@ function proxyToLlama(
   bodyOverride?: Buffer,
   retryUntil = 0
 ): void {
-  const headers = { ...req.headers, host: `${UPSTREAM_HOST}:${UPSTREAM_PORT}` }
+  const headers = { ...req.headers, host: `${UPSTREAM_HOST}:${upstreamPort()}` }
   if (bodyOverride) {
     headers['content-length'] = String(bodyOverride.length)
     delete headers['transfer-encoding']
@@ -209,7 +212,7 @@ function proxyToLlama(
       const proxyReq = http.request(
         {
           hostname: UPSTREAM_HOST,
-          port: UPSTREAM_PORT,
+          port: upstreamPort(),
           path: req.url,
           method: req.method,
           headers
@@ -381,7 +384,7 @@ function callLlamaJson(bodyObj: Record<string, unknown>, retryUntil: number): Pr
       const upstream = http.request(
         {
           hostname: UPSTREAM_HOST,
-          port: UPSTREAM_PORT,
+          port: upstreamPort(),
           path: '/v1/chat/completions',
           method: 'POST',
           headers: { 'content-type': 'application/json', 'content-length': String(payload.length) }
@@ -535,7 +538,7 @@ async function handleEmbeddings(
 function fetchUpstreamModels(): Promise<Record<string, unknown>> {
   return new Promise((resolve) => {
     const r = http.request(
-      { hostname: UPSTREAM_HOST, port: UPSTREAM_PORT, path: '/v1/models', method: 'GET' },
+      { hostname: UPSTREAM_HOST, port: upstreamPort(), path: '/v1/models', method: 'GET' },
       (pr) => {
         let b = ''
         pr.on('data', (d) => (b += d))