ethagent 2.4.0 → 3.0.0

package/src/models/ModelPicker.tsx

@@ -7,10 +7,10 @@ import { Surface } from '../ui/Surface.js'
 import { ProgressBar } from '../ui/ProgressBar.js'
 import { theme } from '../ui/theme.js'
 import {
-  buildLlamaCppRunner,
   DEFAULT_LLAMA_HOST,
   detectLlamaCpp,
   installLlamaCppRunner,
+  killRogueLlamaProcesses,
   setLlamaCppServerPath,
   startLlamaCppServer,
   stopLlamaCppServer,
@@ -80,6 +80,7 @@ type ModelPickerProps = {
   currentModel: string
   contextFit?: ModelPickerContextFit | null
   featuredHfRepo?: string
+  localOnly?: boolean
   onPick: (selection: ModelPickerSelection) => void
   onCancel: () => void
 }
@@ -126,12 +127,20 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
   currentModel,
   contextFit,
   featuredHfRepo,
+  localOnly = false,
   onPick,
   onCancel,
 }) => {
   const [state, setState] = useState<State>({ kind: 'loading' })
   const hfAbortRef = useRef<AbortController | null>(null)
   const oauthServiceRef = useRef<OpenAIOAuthService | null>(null)
+  const dismissToList = (data: LoadedData) => () => {
+    if (localOnly) {
+      onCancel()
+    } else {
+      setState({ kind: 'list', data })
+    }
+  }
 
   useEffect(() => {
     let cancelled = false
@@ -193,8 +202,20 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
 
   if (state.kind === 'loading') {
     return (
-      <Surface title={contextFit ? 'Switch to Larger-Context Model' : 'Switch Provider · Model'} subtitle="Loading providers and models.">
-        <Spinner label="loading providers..." />
+      <Surface
+        title={localOnly ? 'Local Model' : (contextFit ? 'Switch to Larger-Context Model' : 'Switch Provider · Model')}
+        subtitle="Loading providers and models."
+        footer="esc back"
+      >
+        <Spinner label={localOnly ? 'loading local models...' : 'loading providers...'} />
+        <Box marginTop={1}>
+          <Select<'cancel'>
+            options={[{ value: 'cancel', label: 'Back', hint: 'Return to the previous screen', role: 'utility' }]}
+            hintLayout="inline"
+            onSubmit={() => onCancel()}
+            onCancel={() => onCancel()}
+          />
+        </Box>
       </Surface>
     )
   }
@@ -210,7 +231,7 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
           label="Model Link"
           placeholder={LOCAL_MODEL_LINK_HINT}
           onSubmit={value => void inspectHfInput(state, value, setState)}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
         {state.error ? <Text color={theme.accentError}>{state.error}</Text> : null}
       </Surface>
@@ -273,10 +294,12 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
         </Box>
         <Select<'download' | 'downloadWithMmproj' | 'pick' | 'cancel'>
           options={[
+            { value: 'download', role: 'section', label: 'Download' },
             ...(mmproj ? [{ value: 'downloadWithMmproj' as const, label: `Download Model + Vision Encoder (+${formatBytes(mmproj.sizeBytes)}) · recommended`, disabled: !canDownload }] : []),
             { value: 'download', label: mmproj ? 'Download Without Vision Encoder' : 'Download This Model', disabled: !canDownload },
+            { value: 'pick', role: 'section', label: 'Navigation' },
             { value: 'pick', label: 'Pick Another File' },
-            { value: 'cancel', label: 'Cancel' },
+            { value: 'cancel', label: 'Cancel', role: 'utility' },
           ]}
           onSubmit={choice => {
             if (choice === 'download') void startHfDownload(state, setState, hfAbortRef, onPick)
@@ -284,9 +307,9 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
               void startHfDownload({ ...state, plan: { ...plan, includeMmproj: true } }, setState, hfAbortRef, onPick)
             }
             else if (choice === 'pick') void inspectHfInput({ kind: 'hfInput', data: state.data }, plan.repoId, setState)
-            else setState({ kind: 'list', data: state.data })
+            else dismissToList(state.data)()
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -326,9 +349,9 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
           onSubmit={choice => {
             if (choice === 'add') void downloadMmprojAndContinue(state, setState, onPick)
             else if (choice === 'skip') void startAndPickHfModel({ ...state.model, mmprojAvailable: false }, state, setState, onPick)
-            else setState({ kind: 'list', data: state.data })
+            else dismissToList(state.data)()
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -359,9 +382,9 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
           onSubmit={choice => {
             if (choice === 'retry') setState({ kind: 'mmprojOffer', data: state.data, model: state.model })
             else if (choice === 'skip') void startAndPickHfModel({ ...state.model, mmprojAvailable: false }, state, setState, onPick)
-            else setState({ kind: 'list', data: state.data })
+            else dismissToList(state.data)()
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -381,9 +404,9 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
           ]}
           onSubmit={choice => {
             if (choice === 'use') void startAndPickHfModel(state.model, state, setState, onPick)
-            else setState({ kind: 'list', data: state.data })
+            else dismissToList(state.data)()
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -399,9 +422,9 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
           ]}
           onSubmit={choice => {
             if (choice === 'retry') setState({ kind: 'hfInput', data: state.data, error: state.input ? undefined : state.message })
-            else setState({ kind: 'list', data: state.data })
+            else dismissToList(state.data)()
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -431,7 +454,7 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
               const target = targets.find(item => `${item.kind}:${item.id}` === value)
               if (target) setState({ kind: 'localUninstallConfirm', data: state.data, target })
             }}
-            onCancel={() => setState({ kind: 'list', data: state.data })}
+            onCancel={dismissToList(state.data)}
           />
         )}
       </Surface>
@@ -477,8 +500,8 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
       <Surface title="Local Model Uninstalled" subtitle={state.modelName} footer="enter back to picker · esc close">
         <Select<'back'>
           options={[{ value: 'back', label: 'Back To Picker' }]}
-          onSubmit={() => setState({ kind: 'list', data: state.data })}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onSubmit={dismissToList(state.data)}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -494,9 +517,9 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
           ]}
           onSubmit={choice => {
             if (choice === 'retry') void uninstallLocalModel({ kind: 'localUninstallConfirm', data: state.data, target: state.target }, setState)
-            else setState({ kind: 'list', data: state.data })
+            else dismissToList(state.data)()
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -525,9 +548,9 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
             if (choice === 'download') setState({ kind: 'hfInput', data: state.data })
             else if (choice === 'install') void installRunnerAndStart(state, setState, onPick)
             else if (choice === 'path') setState({ kind: 'localRunnerPathEntry', data: state.data, model: state.model, submitting: false })
-            else setState({ kind: 'list', data: state.data })
+            else dismissToList(state.data)()
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -546,15 +569,20 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
     const options = buildRunnerRecoveryOptions(state.result)
     return (
       <Surface title="Runner Setup Needs Attention" subtitle={state.result.message} tone="error" footer="enter select · esc back">
-        <Select<'retry' | 'build' | 'path' | 'back'>
+        <Select<'stop-and-retry' | 'path' | 'back'>
           options={options}
+          hintLayout="inline"
           onSubmit={choice => {
-            if (choice === 'retry') void installRunnerAndStart({ kind: 'localRunnerSetup', data: state.data, model: state.model }, setState, onPick)
-            else if (choice === 'build') void buildRunnerAndStart({ kind: 'localRunnerSetup', data: state.data, model: state.model }, setState, onPick)
+            if (choice === 'stop-and-retry') {
+              void (async () => {
+                await killRogueLlamaProcesses()
+                await installRunnerAndStart({ kind: 'localRunnerSetup', data: state.data, model: state.model }, setState, onPick)
+              })()
+            }
             else if (choice === 'path') setState({ kind: 'localRunnerPathEntry', data: state.data, model: state.model, submitting: false })
-            else setState({ kind: 'list', data: state.data })
+            else dismissToList(state.data)()
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -604,9 +632,9 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
             if (choice === 'retry') void startAndPickHfModel(state.model, { kind: 'hfDone', data: state.data, model: state.model }, setState, onPick)
             else if (choice === 'path') setState({ kind: 'localRunnerPathEntry', data: state.data, model: state.model, submitting: false })
             else if (choice === 'install') void installRunnerAndStart({ kind: 'localRunnerSetup', data: state.data, model: state.model }, setState, onPick)
-            else setState({ kind: 'list', data: state.data })
+            else dismissToList(state.data)()
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -630,7 +658,7 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
             placeholder={providerKeyPlaceholder(provider)}
             isSecret
             onSubmit={(value) => void submitKey(state, value, currentConfig, setState)}
-            onCancel={() => setState({ kind: 'list', data: state.data })}
+            onCancel={dismissToList(state.data)}
           />
         )}
         {error ? <Text color={theme.accentError}>{error}</Text> : null}
@@ -652,9 +680,11 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
         ) : (
           <Select
             options={[
+              { value: 'edit', role: 'section', label: 'Credential' },
               { value: 'edit', label: 'Replace Stored API Key' },
               { value: 'delete', label: 'Remove Stored API Key' },
-              { value: 'cancel', label: 'Back' },
+              { value: 'cancel', role: 'section', label: 'Navigation' },
+              { value: 'cancel', label: 'Back', role: 'utility' },
             ]}
             onSubmit={(value) => {
               if (value === 'edit') {
@@ -667,7 +697,7 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
               }
               void deleteKey(state, currentConfig, setState, onPick, currentProvider)
             }}
-            onCancel={() => setState({ kind: 'list', data: state.data })}
+            onCancel={dismissToList(state.data)}
           />
         )}
         {error ? <Text color={theme.accentError}>{error}</Text> : null}
@@ -705,7 +735,7 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
               }
               void signOutOAuth(state, currentConfig, setState, onPick, currentProvider)
             }}
-            onCancel={() => setState({ kind: 'list', data: state.data })}
+            onCancel={dismissToList(state.data)}
           />
         )}
         {error ? <Text color={theme.accentError}>{error}</Text> : null}
@@ -731,9 +761,9 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
             onSubmit={choice => {
               if (choice === 'retry') void startOpenAIOAuthFlow(state.data, currentConfig, setState, oauthServiceRef, onPick)
               else if (choice === 'apikey') setState({ kind: 'keyEntry', provider: 'openai', action: 'set', data: state.data, submitting: false })
-              else setState({ kind: 'list', data: state.data })
+              else dismissToList(state.data)()
             }}
-            onCancel={() => setState({ kind: 'list', data: state.data })}
+            onCancel={dismissToList(state.data)}
           />
         </Surface>
       )
@@ -795,11 +825,12 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
           options={options}
           initialIndex={initialIndex === -1 ? 0 : initialIndex}
           maxVisible={12}
+          hintLayout="inline"
           onSubmit={(value) => {
             const parsed = parseFullCatalogValue(value)
             if (parsed) onPick({ kind: 'cloud', provider: parsed.provider, model: parsed.model, keyJustSet: false })
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -825,9 +856,9 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
           onSubmit={choice => {
             if (choice === 'retry') void openLocalCatalog(state.data, setState)
             else if (choice === 'paste') setState({ kind: 'hfInput', data: state.data })
-            else setState({ kind: 'list', data: state.data })
+            else dismissToList(state.data)()
           }}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
@@ -846,28 +877,30 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
           options={options}
           initialIndex={initialIndex === -1 ? 0 : initialIndex}
           maxVisible={12}
-          onSubmit={(value) => handleSubmit(value, state, setState, onPick, onCancel, currentConfig, oauthServiceRef)}
-          onCancel={() => setState({ kind: 'list', data: state.data })}
+          hintLayout="inline"
+          onSubmit={(value) => handleSubmit(value, state, setState, onPick, onCancel, currentConfig, oauthServiceRef, localOnly)}
+          onCancel={dismissToList(state.data)}
         />
       </Surface>
     )
   }
 
   const { data } = state
-  const options = buildModelPickerOptions(data, { currentProvider, currentModel, contextFit })
+  const options = buildModelPickerOptions(data, { currentProvider, currentModel, contextFit }, { localOnly })
   const initialIndex = localOrCloudOptionIndex(options, currentProvider, currentModel)
 
   return (
     <Surface
-      title={contextFit ? 'Switch to Larger-Context Model' : 'Switch Provider · Model'}
-      subtitle={contextFit ? contextFitSubtitle(contextFit) : 'Downloaded GGUF files · cloud providers'}
-      footer="enter select · esc close · /models lists installed models"
+      title={localOnly ? 'Local Model' : (contextFit ? 'Switch to Larger-Context Model' : 'Switch Provider · Model')}
+      subtitle={localOnly ? 'Downloaded GGUF files and curated catalog' : (contextFit ? contextFitSubtitle(contextFit) : 'Downloaded GGUF files · cloud providers')}
+      footer={localOnly ? 'enter select · esc back' : 'enter select · esc close · /models lists installed models'}
     >
       <Select
         options={options}
         initialIndex={initialIndex === -1 ? 0 : initialIndex}
         maxVisible={10}
-        onSubmit={(value) => handleSubmit(value, state, setState, onPick, onCancel, currentConfig, oauthServiceRef)}
+        hintLayout="inline"
+        onSubmit={(value) => handleSubmit(value, state, setState, onPick, onCancel, currentConfig, oauthServiceRef, localOnly)}
         onCancel={onCancel}
       />
     </Surface>
@@ -882,6 +915,7 @@ function handleSubmit(
   onCancel: () => void,
   currentConfig: EthagentConfig,
   oauthServiceRef: React.MutableRefObject<OpenAIOAuthService | null>,
+  localOnly: boolean = false,
 ): void {
   if (value.startsWith('hdr:')) return
   if (value === 'cancel') {
@@ -889,7 +923,8 @@ function handleSubmit(
     return
   }
   if (value === 'back' && state.kind === 'localCatalog') {
-    setState({ kind: 'list', data: state.data })
+    if (localOnly) onCancel()
+    else setState({ kind: 'list', data: state.data })
     return
   }
   if (value.startsWith('hf:')) {
@@ -1304,24 +1339,13 @@ export function buildHfFileOptions(
 }
 
 function buildRunnerRecoveryOptions(
-  result: Extract<LlamaCppInstallResult, { ok: false }>,
-): SelectOption<'retry' | 'build' | 'path' | 'back'>[] {
-  const options: SelectOption<'retry' | 'build' | 'path' | 'back'>[] = []
-  if (result.recovery.includes('source-build')) {
-    options.push({
-      value: 'build',
-      label: 'Build Local Runner',
-      hint: 'Uses git and CMake if installed',
-    })
-  }
-  if (result.recovery.includes('runner-path')) {
-    options.push({ value: 'path', label: 'Use Existing Runner Path' })
-  }
-  if (result.recovery.includes('retry-install')) {
-    options.push({ value: 'retry', label: 'Retry Automatic Install' })
-  }
-  options.push({ value: 'back', label: 'Back To Picker' })
-  return options
+  _result: Extract<LlamaCppInstallResult, { ok: false }>,
+): SelectOption<'stop-and-retry' | 'path' | 'back'>[] {
+  return [
+    { value: 'stop-and-retry', label: 'Stop and Retry', hint: 'Stop background runners and try the install again' },
+    { value: 'path', label: 'Use Existing Runner Path' },
+    { value: 'back', label: 'Back To Picker' },
+  ]
 }
 
 function localRunnerStartFailureSubtitle(result: Extract<LlamaCppStartResult, { ok: false }>): string {
@@ -1338,8 +1362,6 @@ function localRunnerStartFailureSubtitle(result: Extract<LlamaCppStartResult, {
       return result.message
     case 'runner-not-installed':
       return 'this machine still needs a local runner'
-    case 'untracked-server':
-      return result.message
   }
 }
 
@@ -1554,16 +1576,7 @@ async function downloadMmprojAndContinue(
     setState({ kind: 'mmprojError', data: state.data, model: state.model, message: 'projector downloaded but path was not persisted' })
     return
   }
-  const stopResult = await stopLlamaCppServer().catch(() => null)
-  if (stopResult && stopResult.ok && stopResult.reason === 'untracked-server') {
-    setState({
-      kind: 'mmprojError',
-      data: state.data,
-      model: updated,
-      message: 'Vision encoder downloaded, but a llama-server is already running and ethagent did not launch it. Quit ethagent, stop the external llama-server (taskkill /F /IM llama-server.exe on Windows, pkill llama-server on macOS or Linux), then reopen ethagent to load the projector.',
-    })
-    return
-  }
+  await stopLlamaCppServer().catch(() => null)
   const data = { ...state.data, hfModels: await loadHfPickerModels() }
   await startAndPickHfModel(updated, { kind: 'mmprojOffer', data, model: updated }, setState, onPick)
 }
@@ -1617,14 +1630,6 @@ async function installRunnerAndStart(
   await runRunnerSetup(state, setState, onPick, installLlamaCppRunner)
 }
 
-async function buildRunnerAndStart(
-  state: Extract<State, { kind: 'localRunnerSetup' }>,
-  setState: (s: State) => void,
-  onPick: (sel: ModelPickerSelection) => void,
-): Promise<void> {
-  await runRunnerSetup(state, setState, onPick, buildLlamaCppRunner)
-}
-
 async function runRunnerSetup(
   state: Extract<State, { kind: 'localRunnerSetup' }>,
   setState: (s: State) => void,

package/src/models/llamacpp.ts

@@ -50,7 +50,6 @@ export type LlamaCppStartFailureCode =
   | 'spawn-failed'
   | 'runner-exited'
   | 'readiness-timeout'
-  | 'untracked-server'
 
 export type LlamaCppStartResult =
   | { ok: true; alreadyRunning: boolean }
@@ -73,6 +72,9 @@ type LlamaCppStartDeps = {
   access?: typeof fs.access
   binaryPath?: string
   spawnImpl?: (command: string, args: readonly string[], options: NonNullable<Parameters<typeof spawn>[2]>) => ReturnType<typeof spawn>
+  killRogue?: (host: string) => Promise<KillRogueResult>
+  rogueDrainTimeoutMs?: number
+  rogueDrainPollMs?: number
 }
 
 export type LocalRunnerConfig = {
@@ -369,16 +371,22 @@ export async function startLlamaCppServer(args: {
   deps?: LlamaCppStartDeps
 }): Promise<LlamaCppStartResult> {
   const host = args.host ?? DEFAULT_LLAMA_HOST
-  const initialStatus = await servedModelStatus(host, args.modelAlias)
-  if (initialStatus.state === 'ready') {
-    if (args.mmprojPath) {
-      const pid = await readPidFile()
-      if (!pid) {
-        return startFailure('untracked-server', {
-          detail: 'A llama-server is already serving this alias but ethagent did not launch it, so we cannot apply the vision projector. Stop the external process and reopen ethagent.',
+  let initialStatus = await servedModelStatus(host, args.modelAlias)
+  if (initialStatus.state === 'ready' && args.mmprojPath) {
+    const pid = await readPidFile()
+    if (!pid) {
+      await (args.deps?.killRogue ?? killRogueLlamaProcesses)(host).catch(() => null)
+      const drained = await waitForHostDown(host, args.deps?.rogueDrainTimeoutMs ?? 6000, args.deps?.rogueDrainPollMs ?? 200)
+      if (!drained) {
+        return startFailure('different-model-running', {
+          servedModels: initialStatus.models,
+          detail: 'another process is holding the local model port and could not be stopped automatically',
         })
       }
+      initialStatus = await servedModelStatus(host, args.modelAlias)
     }
+  }
+  if (initialStatus.state === 'ready') {
     return { ok: true, alreadyRunning: true }
   }
   if (initialStatus.state === 'different') {
@@ -561,6 +569,17 @@ export async function stopLlamaCppServer(args: {
   return { ok: true, stopped: true }
 }
 
+async function waitForHostDown(host: string, timeoutMs: number, pollMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const { up } = await fetchServedModels(host, 800)
+    if (!up) return true
+    await new Promise<void>(resolve => setTimeout(resolve, pollMs))
+  }
+  const { up } = await fetchServedModels(host, 800)
+  return !up
+}
+
 async function servedModelStatus(host: string, modelAlias: string): Promise<
   | { state: 'not-up'; models: string[] }
   | { state: 'ready'; models: string[] }
@@ -572,6 +591,136 @@ async function servedModelStatus(host: string, modelAlias: string): Promise<
   return { state: 'different', models }
 }
 
+export type KillRogueResult = { killed: number; errors: string[] }
+
+export async function killRogueLlamaProcesses(host?: string): Promise<KillRogueResult> {
+  const result: KillRogueResult = { killed: 0, errors: [] }
+  try {
+    await stopLlamaCppServer({ timeoutMs: 1500 })
+  } catch (err: unknown) {
+    result.errors.push(`tracked stop failed: ${(err as Error).message}`)
+  }
+  const platform = os.platform()
+  const portOutcome = await killProcessOnPort(platform, host ?? DEFAULT_LLAMA_HOST)
+  result.killed += portOutcome.killed
+  if (portOutcome.error) result.errors.push(portOutcome.error)
+  const targets = platform === 'win32'
+    ? ['llama-server.exe', 'llama-cli.exe']
+    : ['llama-server', 'llama-cli']
+  for (const target of targets) {
+    const outcome = await runKillCommand(platform, target)
+    result.killed += outcome.killed
+    if (outcome.error) result.errors.push(outcome.error)
+  }
+  await clearPidFile()
+  return result
+}
+
+export async function killProcessOnPort(
+  platform: NodeJS.Platform,
+  host: string,
+): Promise<{ killed: number; error?: string }> {
+  const port = extractHostPort(host)
+  if (!port) return { killed: 0, error: 'no port to scan' }
+  const pids = await listListeningPids(platform, port)
+  if (pids.length === 0) return { killed: 0 }
+  let killed = 0
+  const errors: string[] = []
+  for (const pid of pids) {
+    const outcome = await killByPid(platform, pid)
+    if (outcome.killed) killed++
+    if (outcome.error) errors.push(outcome.error)
+  }
+  return errors.length > 0 ? { killed, error: errors.join('; ') } : { killed }
+}
+
+function extractHostPort(host: string): number | null {
+  try {
+    const url = new URL(host)
+    if (url.port) return Number.parseInt(url.port, 10)
+    return url.protocol === 'https:' ? 443 : 80
+  } catch {
+    return null
+  }
+}
+
+async function listListeningPids(platform: NodeJS.Platform, port: number): Promise<number[]> {
+  if (platform === 'win32') {
+    const result = await runCommand('netstat', ['-ano', '-p', 'tcp'], 4000)
+    if (!result) return []
+    return parseNetstatPids(result.stdout, port)
+  }
+  const result = await runCommand('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], 4000)
+  if (!result || result.code !== 0) return []
+  return result.stdout.split(/\r?\n/).map(line => Number.parseInt(line.trim(), 10)).filter(n => Number.isInteger(n) && n > 0)
+}
+
+export function parseNetstatPids(output: string, port: number): number[] {
+  const pids: number[] = []
+  const seen = new Set<number>()
+  const portSuffix = `:${port}`
+  for (const raw of output.split(/\r?\n/)) {
+    const line = raw.trim()
+    if (!line || !line.toUpperCase().includes('LISTENING')) continue
+    const cols = line.split(/\s+/)
+    if (cols.length < 5) continue
+    const local = cols[1] ?? ''
+    if (!local.endsWith(portSuffix)) continue
+    const pid = Number.parseInt(cols[cols.length - 1] ?? '', 10)
+    if (!Number.isInteger(pid) || pid <= 0) continue
+    if (pid === process.pid) continue
+    if (seen.has(pid)) continue
+    seen.add(pid)
+    pids.push(pid)
+  }
+  return pids
+}
+
+async function killByPid(platform: NodeJS.Platform, pid: number): Promise<{ killed: boolean; error?: string }> {
+  return new Promise(resolve => {
+    const cmd = platform === 'win32' ? 'taskkill' : 'kill'
+    const args = platform === 'win32' ? ['/F', '/T', '/PID', String(pid)] : ['-9', String(pid)]
+    const child = spawn(cmd, args, { stdio: 'ignore' })
+    child.on('error', err => resolve({ killed: false, error: `${cmd} ${pid}: ${err.message}` }))
+    child.on('close', code => {
+      if (code === 0) {
+        resolve({ killed: true })
+        return
+      }
+      resolve({ killed: false, error: `${cmd} ${pid} exited ${code}` })
+    })
+  })
+}
+
+async function runKillCommand(
+  platform: NodeJS.Platform,
+  target: string,
+): Promise<{ killed: number; error?: string }> {
+  return new Promise(resolve => {
+    const cmd = platform === 'win32' ? 'taskkill' : 'pkill'
+    const args = platform === 'win32'
+      ? ['/F', '/T', '/IM', target]
+      : ['-f', target]
+    const child = spawn(cmd, args, { stdio: 'ignore' })
+    child.on('error', err => resolve({ killed: 0, error: `${cmd} ${target}: ${err.message}` }))
+    child.on('close', code => {
+      if (code === 0) {
+        resolve({ killed: 1 })
+        return
+      }
+      if (platform === 'win32' && code === 128) {
+        resolve({ killed: 0 })
+        return
+      }
+      if (platform !== 'win32' && code === 1) {
+        resolve({ killed: 0 })
+        return
+      }
+      resolve({ killed: 0, error: `${cmd} ${target} exited ${code}` })
+    })
+  })
+}
+
 function startFailure(
   code: LlamaCppStartFailureCode,
   options: { detail?: string; servedModels?: string[] } = {},
@@ -593,15 +742,15 @@ function startFailureMessage(code: LlamaCppStartFailureCode, servedModels: strin
     case 'model-file-missing':
       return detail ? `model file not found: ${detail}` : 'model file was not found'
     case 'different-model-running':
-      return `a different local model is already running (${servedModels.join(', ')}); stop it before switching models`
+      return servedModels.length > 0
+        ? `a different local model is already running (${servedModels.join(', ')}); stop it before switching models`
+        : detail ?? 'a different local model is already running; stop it before switching models'
     case 'spawn-failed':
       return 'local runner could not be started'
     case 'runner-exited':
       return 'local runner closed before becoming ready'
     case 'readiness-timeout':
       return 'local runner is still loading or did not answer in time'
-    case 'untracked-server':
-      return detail ?? 'a llama-server is already running and ethagent did not launch it; cannot apply the vision encoder until that process is stopped'
   }
 }