Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

99.5 KB
Raw Blame
import { invalidateModelObservation } from './modelObservation.js';
/**
 * Ollama Manager Service
 *
 * Manages a local Ollama install over its native HTTP API (default
 * http://localhost:11434). Mirrors lmStudioManager.js so server/services/
 * localLlm.js can treat both backends through one shape: availability probe,
 * installed-model listing, streaming pulls, and deletes.
 *
 * Ollama's REST surface (not OpenAI-compatible):
 *   GET    /api/version  → { version }
 *   GET    /api/tags     → { models: [{ name, size, details, modified_at }] }
 *   GET    /api/ps       → { models: [...] }  (loaded into memory)
 *   POST   /api/pull     → NDJSON stream { status, total?, completed? }
 *   DELETE /api/delete   → { name }
 */

import { homedir, tmpdir } from 'os'
import { join, dirname } from 'path'
import { createWriteStream } from 'fs'
import { readdir, stat, link, unlink } from 'fs/promises'
import { createHash } from 'crypto'
import { Readable, Transform } from 'stream'
import { pipeline } from 'stream/promises'
import { execFile, spawn } from '../lib/childProcess.js';import { promisify } from 'util'
import { fetchWithTimeout } from '../lib/fetchWithTimeout.js'
import { readResponseJson } from '../lib/readResponseJson.js'
import { describeFetchError } from '../lib/fetchErrorChain.js'
import { readJSONFile, sha256File, safeJSONParse, ensureDir, atomicWrite, sleep } from '../lib/fileUtils.js'
import {
  parseOllamaManifest, parseOllamaModelRef, ollamaManifestRelPath, digestToBlobFilename, buildModelfile,
  manifestBlobRefs, huggingFaceRegistryBase
} from '../lib/localLlmDisk.js'
import { buildHfAuthHeaders, buildHfResolveUrl, HF_API } from '../lib/huggingfaceLora.js'
import { isEmbeddingModel } from '../lib/localModelHeuristics.js'
import { commandExists } from '../lib/commandExists.js'
import {
  OLLAMA_AGENT_MIN_CONTEXT, OLLAMA_CONTEXT_ENV_VAR, managedOllamaBaseUrl, normalizeOllamaBaseUrl, resolveOllamaContextLength, withOllamaContextEnv
} from '../lib/ollamaContext.js'
import { compareSemver } from '../lib/versionUtils.js'
import { createSingleFlight } from '../lib/singleFlight.js'
import { isSafeHfRepoRelativePath } from '../lib/hfCache.js'
import { assessDownloadPreflight, diskInsufficientError, DOWNLOAD_VERDICTS } from '../lib/downloadPreflight.js'

const execFileAsync = promisify(execFile)
const AVAILABILITY_CACHE_TTL_MS = 30_000
const DEFAULT_REQUEST_TIMEOUT_MS = 10_000
// A pull streams progress as NDJSON; a transient network failure between Ollama
// and the registry/CDN surfaces mid-stream as an `{"error":"EOF"}` frame (or the
// response read rejecting outright). The `ollama` CLI silently retries these and
// the pull is resumable — partial blobs are kept — so a retry continues rather
// than restarts. Total attempts (1 initial + retries) and a linear backoff base.
const PULL_MAX_ATTEMPTS = 3
const PULL_RETRY_BASE_DELAY_MS = 1_000
// Hugging Face can be pathologically slow serving the tiny (≈500 byte) *config*
// blob of a large GGUF repo — a cold CDN miss regularly takes 50-60s, well past
// Ollama's internal per-request deadline. The weight layers all reach 100%, then
// the pull dies with "context deadline exceeded" and no manifest is written, so
// the model vanishes even though ~30GB of verified blobs are on disk. Ollama
// itself doesn't resume that step, and every retry re-races the same deadline.
// So when a pull fails that way we finish it ourselves: fetch the manifest +
// missing blobs with a generous timeout, verify each digest, and write the
// manifest Ollama would have written. See isPullDeadlineError().
const HF_FINALIZE_TIMEOUT_MS = 180_000
// Only complete blobs small enough to hold in memory and hash in one shot — the
// config/params/template layers this recovery exists for are bytes-to-kilobytes.
// A missing multi-GB weight layer is a real download, not a stalled hiccup, so
// we bail and let the error surface rather than silently re-downloading it here.
const HF_FINALIZE_MAX_BLOB_BYTES = 4 * 1024 * 1024
// Short probe — degrade to "no Ollama" fast rather than block on a cold check.
const AVAILABILITY_PROBE_TIMEOUT_MS = 5_000
const START_TIMEOUT_MS = 12_000
const STOP_TIMEOUT_MS = 8_000
const SERVICE_COMMAND_TIMEOUT_MS = 20_000
const PROCESS_IDENTITY_TIMEOUT_MS = 2_000
const HF_IMPORT_METADATA_TIMEOUT_MS = 180_000
// Model ids with a Safetensors import running in this process.
const activeImports = new Set()

const DEFAULT_CONFIG = {
  // Ollama uses OLLAMA_HOST (host:port, no scheme) by convention; also accept
  // an explicit OLLAMA_URL. Normalize to a scheme + no trailing slash + no /v1.
  baseUrl: normalizeOllamaBaseUrl(managedOllamaBaseUrl()),
  timeout: DEFAULT_REQUEST_TIMEOUT_MS
}


let config = { ...DEFAULT_CONFIG }
let isAvailable = null
// null = not yet fetched; an array (even empty) = a cached fetch result. Using a
// null sentinel (not `.length`) lets a genuine "0 models installed" result cache
// too — otherwise the catalog-overlay path re-hits /api/tags on every keystroke.
let installedModels = null
let lastLoadedModelsError = null
// Why /api/tags last returned nothing. `getInstalledModels` deliberately caches
// an empty list on failure (see its comment), so `[]` alone cannot distinguish
// "Ollama has no models installed" from "the list could not be read" — callers
// that must not present a failed read as an empty backend consult this.
// Mirrors lmStudioManager's `getLastListError`.
let lastInstalledModelsError = null
let lastCheckAt = null
let _managedProcess = null
let managedProcessPid = null
// Starts never overlap: two racing launches of one daemon kill or orphan each other.
const startFlight = createSingleFlight({ exclusive: true })
const ensureFlight = createSingleFlight({ exclusive: true })
// What PortOS knows about the Ollama daemon that is up RIGHT NOW. Every field
// describes ONE live process, so the whole record is written by `recordDaemon`
// and dropped by `forgetDaemon` — "which env" and "which process" can never
// describe two different daemons.
//
// `known` is the record's only sentinel, and the one thing a reader tests before
// trusting the rest: "do we know the launch env this daemon holds?".
// `recordDaemon` is the sole writer, so it cannot drift from `envSignature`.
//
// - `envSignature` — the FULL launch env the live daemon was started with, so a
//   second request for the same tuning is a no-op instead of another restart. A
//   sweep measures every model under one tuning; without this it would stop,
//   start, and cold-load the daemon once per model, and every first sample would
//   time a fresh page-in rather than the model. `''` is a real value ("this
//   daemon holds nothing"), which is why the sentinel is `known` rather than a
//   null signature.
// - `contextLength` — the OLLAMA_CONTEXT_LENGTH PortOS handed this daemon. It is
//   what stops `ensureContextWindow` from restarting in a loop: Ollama is free to
//   load a model at less than the requested window (it fits the KV cache to
//   VRAM), and re-reading a smaller `/api/ps` value as "not applied yet" would
//   bounce the daemon before every single agent spawn. Once a window has been
//   handed over, that request is done.
// - `identity` — PID set for the daemon that received that handoff. See
//   `daemonStillLatched` for why a missing identity is "no evidence".
let daemon = { known: false, envSignature: null, contextLength: null, identity: null }

// The launch env PortOS has put in front of Ollama and has NOT taken back yet.
// Deliberately OUTSIDE `daemon` because it outlives it: `daemon` answers "does
// the daemon that is up right now hold this env?", so losing sight of the daemon
// drops it, while this answers "what has PortOS put in front of Ollama that has
// not been cleared yet?" — which a clear needs even when the daemon it was
// applied to is gone. Only a NAMED env replaces it; nothing clears it.
// `null` = PortOS has recorded no env. The clear list is this object's KEYS,
// read off it rather than tracked separately where the two could disagree.
let appliedEnv = null

// The subset of those names that went into the launchd DOMAIN via
// `launchctl setenv` (the homebrew launch-at-login path). Tracked separately
// because a domain variable outlives every daemon: every job started afterwards
// inherits it, so clearing means unsetting it BY NAME. Omitting it from the next
// start does nothing. Emptied only by a successful unset.
let exportedLaunchdKeys = []

// The outstanding assessment tuning: `{ baselineEnv }` while one is active,
// where `baselineEnv` is the launch env the daemon carried BEFORE it went on;
// `null` when none is outstanding. Read through `activeBaselineEnv`.
//
// The baseline an untuned assessment restores is what THIS INSTALL runs by
// default, not an empty environment — `ensureContextWindow` puts the user's
// configured agent context window on the same `OLLAMA_CONTEXT_LENGTH` a tuning
// uses, and stripping it in the name of measuring "backend defaults" would
// silently undo a setting the user chose on the LLMs page. Same rule as
// `llamaServerManager`'s `preTuningConfig`, for the same reason.
//
// Named `activeTuning`, not `tuning`, so `restartWithEnv`'s `{ tuning }` option
// cannot shadow it — a shadowed assignment there would silently write the
// parameter instead of the module's record.
let activeTuning = null

const envSignature = (env) => Object.entries(env || {})
  .sort(([a], [b]) => a.localeCompare(b))
  .map(([k, v]) => `${k}=${v}`)
  .join(',')

/**
 * Record what PortOS knows about the daemon that is up right now.
 *
 * `identity` is the process identity to latch against — a spawned child's PID,
 * or the probed identity of a service PortOS restarted.
 *
 * A `null` env means "a daemon is up, but PortOS cannot name its launch env":
 * the record stops being `known`, and `appliedEnv` is deliberately left alone.
 * Not knowing which daemon is up says nothing about whether the variables PortOS
 * exported are still in front of Ollama, and forgetting them would strand a
 * tuning nothing can clear.
 */
function recordDaemon(env, identity) {
  daemon = {
    known: Boolean(env),
    envSignature: env ? envSignature(env) : null,
    // A restart that named no window leaves Ollama on its VRAM-based auto-pick,
    // which is not a window PortOS can claim — so the context latch is dropped
    // rather than crediting the new process with the old one's window.
    contextLength: resolveOllamaContextLength(null, env || {}),
    identity: identity || null
  }
  if (env) appliedEnv = { ...env }
}

/** The daemon we knew about is gone; whatever comes up next has to be re-checked. */
const forgetDaemon = () => recordDaemon(null, null)

/** A copy of what PortOS has in front of Ollama, or `{}` when it has recorded none. */
const appliedEnvCopy = () => (appliedEnv ? { ...appliedEnv } : {})

/**
 * The launch env an outstanding tuning displaced, or `fallback` when no tuning
 * is outstanding.
 *
 * The fallback belongs to the CALLER rather than to this function, because the
 * two sites ask different questions of the same record and one expression
 * cannot answer both: `restartWithEnv` asks "what is this tuning about to
 * displace?" (an unknown daemon displaces `{}` — PortOS knows of no env to put
 * back), while `clearLaunchEnv` asks "is there anything to undo at all?"
 * (`null` = nothing, and it returns without bouncing the daemon). What they must
 * NOT disagree on is that an active tuning's baseline wins, and that lives here.
 */
const activeBaselineEnv = (fallback) => (activeTuning ? activeTuning.baselineEnv : fallback)

/** `null` clears the tuning; any env records it as the baseline to restore. */
const setTuning = (baselineEnv) => { activeTuning = baselineEnv ? { baselineEnv } : null }

/**
 * Whether the daemon PortOS latched against is still the one answering.
 *
 * Availability alone cannot identify an Ollama process — an external restart can
 * become reachable before PortOS observes a failed probe — so only a CHANGED
 * process identity invalidates a latch. An unreadable identity is not evidence
 * of replacement, and an empty /api/ps response is normal after model eviction
 * and immediately after a restart, so model absence cannot invalidate it either.
 * Treating either as "no evidence" is what keeps an unavailable process probe
 * from creating a restart loop.
 *
 * A mismatch IS positive evidence the daemon was replaced behind PortOS's back,
 * so the record describing the old one is dropped here rather than at each of
 * the two call sites.
 */
async function daemonStillLatched() {
  const currentIdentity = await getOllamaProcessIdentity()
  if (!daemon.identity || !currentIdentity || currentIdentity === daemon.identity) return true
  forgetDaemon()
  return false
}

const status = { lastError: null, lastSuccessAt: null, consecutiveErrors: 0 }

// Whether brew/systemctl exists does not change under a running server, so the
// probe (a `brew --version` spawn) runs once per platform per process.
let serviceControllerProbe = null

function getServiceController() {
  if (serviceControllerProbe?.platform !== process.platform) {
    serviceControllerProbe = { platform: process.platform, promise: probeServiceController() }
  }
  return serviceControllerProbe.promise
}

async function probeServiceController() {
  if (process.platform === 'darwin' && await commandExists('brew', ['--version'])) {
    return {
      supported: true,
      manager: 'homebrew',
      start: ['brew', ['services', 'start', 'ollama']],
      stop: ['brew', ['services', 'stop', 'ollama']],
      restart: ['brew', ['services', 'restart', 'ollama']],
      list: ['brew', ['services', 'list']]
    }
  }
  if (process.platform === 'linux' && await commandExists('systemctl', ['--version'])) {
    return {
      supported: true,
      manager: 'systemd',
      start: ['systemctl', ['enable', '--now', 'ollama']],
      stop: ['systemctl', ['disable', '--now', 'ollama']],
      active: ['systemctl', ['is-active', 'ollama']],
      enabled: ['systemctl', ['is-enabled', 'ollama']]
    }
  }
  return { supported: false, manager: null }
}

// `brew services list` costs ~0.45 s, and a service's state only changes when
// PortOS runs start/stop/restart (which invalidate this) or the user runs brew
// themselves, so a short TTL keeps the status endpoint cheap.
const SERVICE_STATUS_TTL_MS = 10_000
let serviceStatusCache = null // { at, value } | { inflight, generation }
let serviceStatusGeneration = 0

function invalidateServiceStatus() {
  serviceStatusGeneration++
  serviceStatusCache = null
}

function getServiceStatus(forceRefresh = false) {
  const cached = serviceStatusCache
  if (!forceRefresh && cached) {
    if (cached.inflight) return cached.inflight
    if (Date.now() - cached.at < SERVICE_STATUS_TTL_MS) return Promise.resolve(cached.value)
  }
  const generation = serviceStatusGeneration
  const inflight = readServiceStatus().then((value) => {
    // A mutation that landed while this read was in flight makes it stale.
    if (generation === serviceStatusGeneration) serviceStatusCache = { at: Date.now(), value }
    return value
  }, (err) => {
    if (serviceStatusCache?.inflight === inflight) serviceStatusCache = null
    throw err
  })
  if (generation === serviceStatusGeneration) serviceStatusCache = { inflight }
  return inflight
}

async function readServiceStatus() {
  const controller = await getServiceController()
  if (!controller.supported) {
    return { supported: false, manager: null, running: false, runAtStartup: false, status: null }
  }

  if (controller.manager === 'homebrew') {
    const [cmd, args] = controller.list
    const { stdout } = await execFileAsync(cmd, args, { timeout: SERVICE_COMMAND_TIMEOUT_MS }).catch(() => ({ stdout: '' }))
    const line = stdout.split('\n').find((entry) => entry.trim().startsWith('ollama '))
    const serviceStatus = line?.trim().split(/\s+/)[1] || 'none'
    const running = serviceStatus === 'started'
    return {
      supported: true,
      manager: 'homebrew',
      running,
      runAtStartup: running,
      status: serviceStatus
    }
  }

  if (controller.manager === 'systemd') {
    const [activeCmd, activeArgs] = controller.active
    const [enabledCmd, enabledArgs] = controller.enabled
    const [{ stdout: activeOut }, { stdout: enabledOut }] = await Promise.all([
      execFileAsync(activeCmd, activeArgs, { timeout: SERVICE_COMMAND_TIMEOUT_MS }).catch(() => ({ stdout: '' })),
      execFileAsync(enabledCmd, enabledArgs, { timeout: SERVICE_COMMAND_TIMEOUT_MS }).catch(() => ({ stdout: '' })),
    ])
    const activeStatus = activeOut.trim() || 'inactive'
    const enabledStatus = enabledOut.trim() || 'disabled'
    const running = activeStatus === 'active'
    const runAtStartup = enabledStatus === 'enabled'
    return {
      supported: true,
      manager: 'systemd',
      running,
      runAtStartup,
      status: activeStatus,
      enabledStatus
    }
  }

  return { supported: false, manager: null, running: false, runAtStartup: false, status: null }
}

async function ollamaRequestAt(baseUrl, endpoint, options = {}) {
  const { timeout, headers, ...rest } = options
  const response = await fetchWithTimeout(`${normalizeOllamaBaseUrl(baseUrl)}${endpoint}`, {
    ...rest,
    headers: { 'Content-Type': 'application/json', ...headers }
  }, timeout ?? config.timeout)
  if (!response.ok) {
    const body = await response.text().catch(() => '')
    throw new Error(`Ollama API error: ${response.status} ${response.statusText}${body ? ` — ${body.slice(0, 200)}` : ''}`)
  }
  return readResponseJson(response)
}

async function ollamaRequest(endpoint, options = {}) {
  return ollamaRequestAt(config.baseUrl, endpoint, options)
}

/**
 * Check if Ollama is reachable (cached for AVAILABILITY_CACHE_TTL_MS).
 */
async function checkOllamaAvailable(forceRefresh = false) {
  const now = Date.now()
  if (!forceRefresh && lastCheckAt && now - lastCheckAt < AVAILABILITY_CACHE_TTL_MS && isAvailable !== null) {
    return isAvailable
  }
  try {
    await ollamaRequest('/api/version', { timeout: AVAILABILITY_PROBE_TIMEOUT_MS })
    isAvailable = true
    status.lastSuccessAt = now
    status.consecutiveErrors = 0
    status.lastError = null
    lastCheckAt = now
    return true
  } catch (err) {
    isAvailable = false
    // The daemon we handed a window to is gone; whatever comes up next has to
    // be re-checked rather than credited with that window or that launch env.
    forgetDaemon()
    status.lastError = err.message
    status.consecutiveErrors++
    lastCheckAt = now
    return false
  }
}

function resetAvailabilityCache() {
  isAvailable = null
  lastCheckAt = null
  installedModels = null
  lastLoadedModelsError = null
}

async function waitForAvailability(expected, timeoutMs, shouldAbort = () => false) {
  const deadline = Date.now() + timeoutMs
  while (Date.now() < deadline && !shouldAbort()) {
    if ((await checkOllamaAvailable(true)) === expected) return true
    if (!shouldAbort()) await sleep(400)
  }
  return !shouldAbort() && (await checkOllamaAvailable(true)) === expected
}

function rememberManagedProcess(child) {
  _managedProcess = child
  managedProcessPid = child.pid
  child.on('exit', () => {
    if (managedProcessPid === child.pid) {
      _managedProcess = null
      managedProcessPid = null
    }
  })
}

async function terminateManagedProcess() {
  const pid = managedProcessPid
  if (!pid) return false
  try {
    process.kill(-pid, 'SIGTERM')
  } catch {
    try { process.kill(pid, 'SIGTERM') } catch { return false }
  }
  return true
}

/**
 * Start the Ollama HTTP server via the local CLI.
 *
 * `env` carries every launch-time knob PortOS can hand the daemon —
 * `OLLAMA_CONTEXT_LENGTH`, `OLLAMA_FLASH_ATTENTION`, `OLLAMA_KV_CACHE_TYPE`, … —
 * because the process environment is the ONLY lever that reaches them. Claude
 * Code and OpenCode talk to Ollama directly, and its OpenAI-compatible endpoint
 * drops unknown body fields, so PortOS cannot attach a per-request `num_ctx` the
 * way the toolkit runner does for `api` providers. There is deliberately no
 * second, context-only parameter: two spellings of one variable would need a
 * precedence rule, and the latches below would have to read both.
 *
 * Single-flight per launch env: concurrent callers asking for the same env
 * share one spawn and one result. Two racing `ollama serve` children left the
 * loser to fail its bind and exit, and its exit cleared `managedProcessPid`,
 * leaving the surviving daemon untracked and unstoppable on Windows. A caller
 * asking for a DIFFERENT env waits for the in-flight start, then runs its own,
 * which sees the daemon up and reports `alreadyRunning` exactly as a
 * sequential call would, instead of claiming a start under an env it never got.
 *
 * @param {{ env?: Record<string, string> }} [options]
 * @returns {Promise<{ success: boolean, running?: boolean, alreadyRunning?: boolean, pid?: number, error?: string }>}
 */
function startServer({ env = null } = {}) {
  return startFlight.run(envSignature(env), () => spawnServer(env))
}

async function spawnServer(env) {
  if (await checkOllamaAvailable(true)) {
    return { success: true, running: true, alreadyRunning: true }
  }

  const contextLength = resolveOllamaContextLength(null, env || {})
  let spawnError = null
  let notifySpawnFailure = null
  // `spawn()` reports a missing executable asynchronously. Waiting only for the
  // HTTP probe in that case turns an immediate ENOENT into a 12-second startup
  // timeout, obscuring the one useful diagnosis and needlessly delaying a
  // fallback. Keep the probe for a real daemon startup, but let a spawn failure
  // settle this attempt as soon as Node reports it.
  const spawnFailed = new Promise((resolve) => { notifySpawnFailure = resolve })
  const stderr = []
  const child = spawn('ollama', ['serve'], {
    detached: true,
    stdio: ['ignore', 'ignore', 'pipe'],
    env: { ...process.env, ...(env || {}) }
  })
  rememberManagedProcess(child)
  child.stderr?.on('data', (chunk) => {
    stderr.push(chunk.toString())
    if (stderr.join('').length > 2000) stderr.shift()
  })
  child.on('error', (err) => {
    spawnError = err
    notifySpawnFailure(err)
  })
  child.unref()

  const startup = await Promise.race([
    waitForAvailability(true, START_TIMEOUT_MS, () => spawnError !== null).then((running) => ({ running, error: null })),
    spawnFailed.then((error) => ({ running: false, error })),
  ])
  const running = startup.running
  if (running) {
    // A daemon PortOS just started carries exactly `env` and nothing else, so
    // there is no earlier tuning left to undo. `restartWithEnv` re-asserts its
    // own baseline after this returns — see the note there. Mirrors
    // `llamaServerManager`'s `startLlamaServer`.
    setTuning(null)
    recordDaemon(env, String(child.pid))
    const window = contextLength ? ` (context ${contextLength})` : ''
    console.log(`▶️ Started Ollama server (pid ${child.pid})${window}`)
    return { success: true, running: true, pid: child.pid }
  }

  const detail = startup.error?.code === 'ENOENT'
    ? 'Ollama CLI is not installed or is not on PortOS\'s PATH. Install Ollama from https://ollama.com/download, then restart PortOS.'
    : spawnError?.message || stderr.join('').trim()
  return {
    success: false,
    running: false,
    error: `Ollama did not become reachable${detail ? `: ${detail}` : ''}`
  }
}

/**
 * `brew services start` shells out to `launchctl bootstrap gui/<uid> …plist`,
 * which fails with `Bootstrap failed: 5: Input/output error` when a service is
 * already bootstrapped in that domain — a stale launchd registration left over
 * from a prior `ollama serve`, an interrupted start, or a Homebrew upgrade. The
 * job is loaded but `start` refuses to re-bootstrap it. Booting it out
 * (`brew services stop`, i.e. `launchctl bootout`) clears the registration so
 * the retry can bootstrap cleanly.
 */
function isBootstrapConflictError(message) {
  const m = String(message || '').toLowerCase()
  // "already loaded/bootstrapped" unambiguously means a stale registration.
  if (/already (?:loaded|bootstrapped)/.test(m)) return true
  // Otherwise require the failure to actually be about a launchctl *bootstrap*
  // before trusting the EIO / exit-5 signal — so an unrelated brew failure that
  // merely mentions "input/output error" (a disk EIO, a permissions error)
  // can't trip the bootout-and-retry recovery. The two real-world shapes both
  // name bootstrap: launchctl's own "Bootstrap failed: 5: Input/output error"
  // and brew's wrapper "…launchctl bootstrap … exited with 5".
  if (!/bootstrap/.test(m)) return false
  return /bootstrap failed: 5\b/.test(m) ||
    /\binput\/output error\b/.test(m) ||
    /exited with 5\b/.test(m) ||
    /\bbootstrap failed\b/.test(m)
}

async function runServiceStart(controller) {
  const [cmd, args] = controller.start
  return execFileAsync(cmd, args, { timeout: SERVICE_COMMAND_TIMEOUT_MS })
    .then(() => ({ success: true }))
    .catch((err) => ({ success: false, error: err.stderr?.trim() || err.stdout?.trim() || err.message }))
}

async function startPersistentService() {
  const controller = await getServiceController()
  if (!controller.supported) {
    // `unsupported` marks an expected platform capability gap (Windows ships no
    // brew/systemd; so does a Linux box without systemd) rather than a failed
    // start attempt, so `ensureRunning` can fall back to a foreground
    // `ollama serve` quietly instead of warning on every boot.
    return { success: false, unsupported: true, running: await checkOllamaAvailable(true), error: 'No supported Ollama background service manager found.' }
  }

  resetAvailabilityCache()
  let result = await runServiceStart(controller)

  // Recover from a stale launchd registration: bootstrap reported the job is
  // already loaded, so boot it out and retry once. systemd's `enable --now` is
  // idempotent and never hits this, so the recovery is homebrew-only.
  if (!result.success && controller.manager === 'homebrew' && isBootstrapConflictError(result.error)) {
    console.warn(`♻️ Ollama service start hit a stale launchd registration (${result.error}); booting out and retrying`)
    const [stopCmd, stopArgs] = controller.stop
    await execFileAsync(stopCmd, stopArgs, { timeout: SERVICE_COMMAND_TIMEOUT_MS }).catch(() => {})
    result = await runServiceStart(controller)
  }

  const running = await waitForAvailability(true, START_TIMEOUT_MS)
  invalidateServiceStatus()
  const service = await getServiceStatus().catch(() => ({
    supported: true,
    manager: controller.manager,
    running,
    runAtStartup: running,
    status: running ? 'started' : 'unknown'
  }))

  if (result.success && running) {
    console.log(`▶️ Started Ollama via ${controller.manager} service`)
    return { success: true, running: true, persistent: true, service }
  }

  return {
    success: false,
    running,
    persistent: false,
    service,
    error: result.error || 'Ollama service started, but the API did not become reachable.'
  }
}

async function stopPersistentService() {
  const controller = await getServiceController()
  if (!controller.supported) {
    // Mirrors startPersistentService — same capability gap, same flag, so a
    // caller can tell "nothing to stop on this platform" from a real failure.
    return { success: false, unsupported: true, running: await checkOllamaAvailable(true), error: 'No supported Ollama background service manager found.' }
  }

  const [cmd, args] = controller.stop
  const result = await execFileAsync(cmd, args, { timeout: SERVICE_COMMAND_TIMEOUT_MS })
    .then(() => ({ success: true }))
    .catch((err) => ({ success: false, error: err.stderr?.trim() || err.stdout?.trim() || err.message }))

  const stopped = await waitForAvailability(false, STOP_TIMEOUT_MS)
  if (stopped) resetAvailabilityCache()
  invalidateServiceStatus()
  const service = await getServiceStatus().catch(() => ({
    supported: true,
    manager: controller.manager,
    running: !stopped,
    runAtStartup: !stopped,
    status: stopped ? 'stopped' : 'unknown'
  }))

  if (result.success && stopped) {
    console.log(`⏹️ Stopped Ollama ${controller.manager} service`)
    return { success: true, running: false, persistent: false, service }
  }

  return {
    success: false,
    running: !stopped,
    persistent: service.runAtStartup,
    service,
    error: result.error || 'Ollama service stopped, but the API still appears reachable.'
  }
}

// Single-flight like `startServer`: concurrent `brew services start` calls
// trip the bootstrap-conflict recovery, whose bootout stops the daemon the
// other caller just started.
function ensureRunning({ preferPersistent = false } = {}) {
  const persistent = Boolean(preferPersistent)
  return ensureFlight.run(persistent, () => bringUp(persistent))
}

async function bringUp(preferPersistent) {
  if (await checkOllamaAvailable(true)) {
    return { success: true, running: true, alreadyRunning: true, service: await getServiceStatus().catch(() => null) }
  }
  if (preferPersistent) {
    const serviceResult = await startPersistentService()
    if (serviceResult.success) return serviceResult
    // Only a real start FAILURE deserves a warning. `unsupported` just means
    // this platform has no service manager to try — the normal case on Windows,
    // where warning made every boot look broken. The `startServer()` fallback
    // below is the intended path there, not a degraded one.
    if (!serviceResult.unsupported) {
      console.warn(`⚠️ Failed to start Ollama as a background service: ${serviceResult.error}`)
    }
  }
  return startServer()
}

/**
 * Identify the live Ollama server process without using model residency as a
 * proxy for daemon identity. `ps` is available on macOS/Linux; tasklist gives
 * us the equivalent PID set on Windows. A failed/unsupported probe returns
 * null, which is intentionally treated as no evidence by the context latch.
 */
async function getOllamaProcessIdentity() {
  if (process.platform === 'win32') {
    const { stdout } = await execFileAsync(
      'tasklist',
      ['/FI', 'IMAGENAME eq ollama.exe', '/FO', 'CSV', '/NH'],
      { timeout: PROCESS_IDENTITY_TIMEOUT_MS },
    ).catch(() => ({ stdout: '' }))
    const pids = stdout.split('\n')
      .map((line) => {
        const fields = [...line.matchAll(/"([^"]*)"/g)].map((match) => match[1])
        return fields[1] ? Number(fields[1]) : null
      })
      .filter((pid) => Number.isInteger(pid) && pid > 0)
      .sort((a, b) => a - b)
    return pids.length ? pids.join(',') : null
  }

  const { stdout } = await execFileAsync(
    'ps',
    ['-Ao', 'pid=,command='],
    { timeout: PROCESS_IDENTITY_TIMEOUT_MS },
  ).catch(() => ({ stdout: '' }))
  const pids = stdout.split('\n')
    .map((line) => {
      const match = line.match(/^\s*(\d+)\s+(.+)$/)
      return match && /\bollama(?:\.exe)?\s+serve\b/i.test(match[2]) ? Number(match[1]) : null
    })
    .filter((pid) => Number.isInteger(pid) && pid > 0)
    .sort((a, b) => a - b)
  return pids.length ? pids.join(',') : null
}

async function getRuntimeModels() {
  if (!(await checkOllamaAvailable())) return null
  const data = await ollamaRequest('/api/ps').catch(() => null)
  return Array.isArray(data?.models) ? data.models : []
}

const modelNames = (model) => [model?.name, model?.model]
  .filter((name) => typeof name === 'string' && name.trim())
  .map((name) => name.trim())

/**
 * The context window the daemon actually loaded at, read from `/api/ps`.
 * Ollama reports it per resident model. When a model is selected, only that
 * model is considered; without a selection, the smallest resident window is
 * used so a large sibling model cannot hide a smaller model's limit.
 *
 * If a selected model is not resident yet, the fallback is the smallest window
 * among all resident models: every relevant resident model must meet the target
 * before the daemon can be treated as safe. `null` means no model is resident.
 * @param {string|null} [selectedModel]
 * @returns {Promise<number|null>}
 */
async function getRuntimeContextLength(selectedModel = null) {
  const models = await getRuntimeModels()
  if (models == null) return null
  const wanted = typeof selectedModel === 'string' ? selectedModel.trim() : ''
  const selected = wanted
    ? models.filter((model) => modelNames(model).includes(wanted))
    : []
  const resident = selected.length ? selected : models
  const windows = resident
    .map((model) => Number(model?.context_length))
    .filter((n) => Number.isFinite(n) && n > 0)
  return windows.length ? Math.min(...windows) : null
}

/**
 * Hold the Ollama daemon at (at least) `contextLength` tokens, reloading it with
 * that window when it is running at a smaller one.
 *
 * Reloading a daemon is disruptive, so it happens at most once per daemon per
 * window (the `daemon.contextLength` latch) and never when a resident model is
 * already at or above the target. It DOES happen when nothing is resident: an
 * idle daemon has not committed to a window yet, and the one it will pick is
 * the VRAM-based default `numCtx` exists to override.
 *
 * @param {number|null} contextLength
 * @param {string|null} [selectedModel] - model the next request will use
 * @returns {Promise<{ applied: boolean, reason: string, contextLength: number|null, runtimeContextLength?: number|null, error?: string }>}
 */
async function ensureContextWindow(contextLength, selectedModel = null) {
  const target = Number(contextLength) > 0 ? Math.floor(Number(contextLength)) : null
  if (!target) return { applied: false, reason: 'not-configured', contextLength: null }

  // Compose the context-window env ON TOP OF the currently applied launch env
  // instead of replacing it, so a reload preserves knobs (e.g.
  // OLLAMA_FLASH_ATTENTION, OLLAMA_KV_CACHE_TYPE) that are not about the window.
  // `appliedEnv` outlives the `daemon` record specifically to answer "what has
  // PortOS put in front of Ollama that has not been cleared yet", so an active
  // tuning is preserved even if the daemon was temporarily down.
  // When a tuning is active mid-sweep, preserving its knobs keeps the sweep's
  // measurements comparable rather than demoting the daemon to untuned
  // mid-sweep, while allowing the context window to expand for the harness.
  const env = withOllamaContextEnv(appliedEnvCopy(), target)

  if (!(await checkOllamaAvailable(true))) {
    return { ...(await restartWithEnv(env, { tuning: false })), contextLength: target }
  }

  if (Number(daemon.contextLength) >= target && await daemonStillLatched()) {
    return { applied: false, reason: 'already-applied', contextLength: target, runtimeContextLength: daemon.contextLength }
  }

  // `runtime == null` means nothing is resident, which is the NORMAL idle state
  // between runs — not a reason to skip. The window Ollama will pick when the
  // harness loads its model is its VRAM-based default, i.e. exactly the one the
  // user set `numCtx` to override, so leaving it alone here would make the
  // setting a no-op in the common case. Apply it; the `daemon.contextLength`
  // latch keeps this to one reload per daemon.
  const runtime = await getRuntimeContextLength(selectedModel)
  if (runtime != null && runtime >= target) {
    return { applied: false, reason: 'already-large-enough', contextLength: target, runtimeContextLength: runtime }
  }

  console.log(`🪟 Reloading Ollama at a ${target}-token context window (was ${runtime ?? 'unknown'})`)

  // The restart ladder itself — including the rule that a launch-at-login daemon
  // is restarted in place rather than un-registered — lives in `restartWithEnv`.
  // The checks ABOVE are what is specific to a context window: a resident model
  // already big enough, and the >= latch that keeps an agent spawn from bouncing
  // the daemon. Everything below was the same ladder written twice.
  return { ...(await restartWithEnv(env, { tuning: false })), contextLength: target, runtimeContextLength: runtime }
}

/**
 * Restart a launch-at-login-registered Ollama carrying `env`, WITHOUT
 * un-registering it.
 *
 * macOS: `launchctl setenv` writes into the user's launchd domain, which every
 * job launched afterwards inherits — so setting the variables and then
 * `brew services restart ollama` carries them into a plist PortOS cannot edit
 * (Homebrew regenerates it from the formula on every start). The variables are
 * scoped to Ollama's behavior, so exporting them session-wide is harmless.
 *
 * Linux: the equivalent is a `systemctl edit ollama` drop-in, which needs root.
 * PortOS reports what to do rather than tearing the unit down to work around it.
 *
 * @param {{ manager: string }} service
 * @param {Record<string, string>} env - never empty; `restartWithEnv` routes an
 *   empty env to `clearLaunchEnv` instead, which UNSETS what was set.
 */
async function restartServiceWithEnv(service, env) {
  const entries = Object.entries(env || {})

  if (service.manager !== 'homebrew') {
    const lines = entries.map(([k, v]) => `Environment="${k}=${v}"`).join(' ')
    return {
      applied: false,
      reason: 'service-managed',
      error: `Ollama runs as a ${service.manager} service, which PortOS can't hand launch settings. ` +
        `Add them with: sudo systemctl edit ollama → [Service] ${lines}, then restart it.`
    }
  }

  for (const [key, value] of entries) {
    const setenv = await runLaunchctl(['setenv', key, String(value)])
    // A key PortOS did NOT manage to set is not PortOS's to unset — the name may
    // belong to a variable the user exported themselves. Only a successful
    // setenv makes it ours.
    if (!setenv.success) return { applied: false, reason: 'setenv-failed', error: setenv.error }
    // Recorded as we go, not after the restart: it is already in the domain, and
    // a bounce that fails later must not leave it untracked and unclearable.
    if (!exportedLaunchdKeys.includes(key)) exportedLaunchdKeys.push(key)
  }

  const bounced = await bounceService()
  if (!bounced.ok) return bounced.failure
  recordDaemon(env, await getOllamaProcessIdentity())
  console.log(`▶️ Restarted the Ollama ${service.manager} service with ${entries.map(([k, v]) => `${k}=${v}`).join(', ')}`)
  return { applied: true, reason: 'service-restarted' }
}

const runLaunchctl = (args) => execFileAsync('launchctl', args, { timeout: SERVICE_COMMAND_TIMEOUT_MS })
  .then(() => ({ success: true }))
  .catch((err) => ({ success: false, error: err.stderr?.trim() || err.message }))

/**
 * Take variables back OUT of the launchd domain, by name.
 *
 * Reached only for keys `restartServiceWithEnv` put there, so `launchctl` is
 * always the right tool — the domain exists on macOS and nowhere else.
 */
async function unsetLaunchdKeys(keys) {
  for (const key of keys) {
    const unsetenv = await runLaunchctl(['unsetenv', key])
    if (!unsetenv.success) return { success: false, error: unsetenv.error }
  }
  return { success: true }
}

/**
 * Restart the service controller's Ollama and wait for the API to come back.
 * `{ ok: false, failure }` carries the caller's return value verbatim, so the
 * set and clear paths above cannot drift on how a bounce failure is reported.
 */
async function bounceService() {
  const controller = await getServiceController()
  resetAvailabilityCache()
  const [cmd, args] = controller.restart
  const restarted = await execFileAsync(cmd, args, { timeout: SERVICE_COMMAND_TIMEOUT_MS })
    .then(() => ({ success: true }))
    .catch((err) => ({ success: false, error: err.stderr?.trim() || err.stdout?.trim() || err.message }))
  invalidateServiceStatus()
  if (!restarted.success) return { ok: false, failure: { applied: false, reason: 'restart-failed', error: restarted.error } }

  if (!(await waitForAvailability(true, START_TIMEOUT_MS))) {
    return {
      ok: false,
      failure: { applied: false, reason: 'restart-unreachable', error: 'Ollama restarted, but the API did not become reachable.' }
    }
  }
  return { ok: true }
}

/**
 * Restart the local Ollama daemon so it picks up `env` — the launch-time knobs
 * (`OLLAMA_FLASH_ATTENTION`, `OLLAMA_KV_CACHE_TYPE`, `OLLAMA_CONTEXT_LENGTH`, …)
 * that reach Ollama ONLY through its process environment.
 *
 * Ollama's OpenAI-compatible endpoint silently drops unknown body fields, so
 * there is no per-request spelling of any of these: a tuned measurement either
 * restarts the daemon or is measuring the previous configuration. This resolves
 * rather than throws, and reports `applied: false` with a reason when it could
 * not — the caller records that instead of filing the reading under a tuning
 * that never took effect.
 *
 * An EMPTY `env` is the opposite request: drop a tuning PortOS applied earlier
 * and put the daemon back on the env it had before. An untuned assessment needs
 * that — otherwise it samples the previous sweep's tuning and the reading is
 * filed as "Backend defaults". When no tuning is outstanding, nothing restarts.
 *
 * @param {Record<string, string>} env
 * @param {{ tuning?: boolean }} [options] `tuning: false` marks a restart that
 *   changes the install's REAL configuration (`ensureContextWindow` handing the
 *   daemon the user's agent context window) rather than a temporary assessment
 *   tuning. It is not undoable, and it becomes the baseline a later clear
 *   restores — without it, measuring "backend defaults" would strip a setting
 *   the user chose on the LLMs page.
 * @returns {Promise<{ applied: boolean|null, reason: string, error?: string }>}
 *   `applied: null` means nothing needed to change — not a refusal.
 */
async function restartWithEnv(env, { tuning = true } = {}) {
  const entries = Object.entries(env || {})
  if (entries.length === 0) {
    return tuning ? clearLaunchEnv() : { applied: false, reason: 'nothing-to-apply' }
  }

  // A TUNING is temporary and has to be undoable, so the first one records the
  // env it displaces; a second must not overwrite that with the first one's.
  // An unknown daemon (`!daemon.known`) displaces `{}` — PortOS knows of no env
  // to put back — never a stale record of some earlier daemon's.
  const before = activeBaselineEnv(null)
  const captured = activeBaselineEnv(daemon.known ? appliedEnvCopy() : {})

  const result = await applyLaunchEnv(env, entries)
  // Asserted AFTER the restart, never before: `startServer`/`stopServer` drop
  // the baseline as a matter of course (a daemon PortOS just started is untuned
  // by construction), so anything written up front would be wiped mid-call.
  //
  // A restart that did not happen changed nothing, so the bookkeeping must not
  // move either.
  //
  // When a non-tuning restart (`tuning: false`, e.g. `ensureContextWindow`) occurs
  // while a tuning is active (`before !== null`), preserve the pre-tuning undo
  // baseline rather than clearing it, but update its context window so that a
  // later `clearLaunchEnv()` restores the untuned daemon with the new context
  // length rather than reverting it. If no tuning was active (`before === null`),
  // no tuning is outstanding afterwards either.
  if (result.applied === false) {
    setTuning(before)
  } else if (tuning) {
    setTuning(captured)
  } else if (before) {
    setTuning(withOllamaContextEnv(before, env[OLLAMA_CONTEXT_ENV_VAR]))
  } else {
    setTuning(null)
  }
  return result
}

// The restart itself, with `restartWithEnv` owning the baseline bookkeeping
// around it so no exit below has to remember to unwind it.
async function applyLaunchEnv(env, entries) {
  // The daemon that is up may already BE this tuning — a sweep measures every
  // model under one knob set, and restarting per model would cold-load each one
  // and time the page-in as if it were the model's throughput. Same evidence
  // rule as the context latch, and for the same reason — see
  // `daemonStillLatched`.
  if (daemon.known && daemon.envSignature === envSignature(env) && await checkOllamaAvailable(true) && await daemonStillLatched()) {
    return { applied: true, reason: 'already-applied' }
  }

  // A key the PREVIOUS env exported into the launchd domain and this one does
  // not name is STILL set, and every job started afterwards inherits it — so the
  // daemon would come back carrying half the old configuration. Omitting a
  // variable is not clearing it. Done here rather than in the service path
  // alone, because a spawned daemon started while a service is registered
  // inherits the same domain.
  const stale = exportedLaunchdKeys.filter((key) => !(key in env))
  if (stale.length) {
    const cleared = await unsetLaunchdKeys(stale)
    if (!cleared.success) return { applied: false, reason: 'unsetenv-failed', error: cleared.error }
    exportedLaunchdKeys = exportedLaunchdKeys.filter((key) => key in env)
  }

  console.log(`🔧 Restarting Ollama with ${entries.map(([k, v]) => `${k}=${v}`).join(', ')}`)

  if (!(await checkOllamaAvailable(true))) {
    const started = await startServer({ env })
    return started.success
      ? { applied: true, reason: 'started' }
      : { applied: false, reason: 'start-failed', error: started.error }
  }

  // A daemon the user registered to launch at login must keep that registration:
  // `stopServer` would route through `brew services stop` / `systemctl disable`,
  // which un-registers it. Restart it in place instead.
  const service = await getServiceStatus().catch(() => null)
  if (service?.runAtStartup) return restartServiceWithEnv(service, env)

  const stopped = await stopServer()
  if (!stopped.success) return { applied: false, reason: 'stop-failed', error: stopped.error }
  const started = await startServer({ env })
  return started.success
    ? { applied: true, reason: 'restarted' }
    : { applied: false, reason: 'start-failed', error: started.error }
}

/**
 * Put the daemon back on the env it carried before PortOS tuned it.
 *
 * This is the half of the tuning contract that keeps a BASELINE measurement
 * honest. An untuned assessment records `tuningKey: ''` and renders as "Backend
 * defaults"; if the daemon is still carrying the last sweep's
 * `OLLAMA_FLASH_ATTENTION=1`, that label describes a configuration that never
 * ran, and `compareTunings` then ranks every real tuning against it.
 *
 * "Before PortOS tuned it" is the active tuning's baseline, NOT an empty
 * environment — see the note on `activeTuning`. Only when that baseline is
 * itself empty does this tear the launch env down to nothing.
 */
async function clearLaunchEnv() {
  // Variables PortOS exported are outstanding even when no tuning reached the
  // daemon — a `setenv` that landed before its restart failed. They sit in the
  // launchd domain, so the daemon that came up NEXT inherited them and is tuned
  // however this record reads. Taking them out is not enough: that daemon holds
  // them in its own process environment and has to be restarted too, which is
  // exactly what an empty baseline already means here.
  const baseline = activeBaselineEnv(exportedLaunchdKeys.length ? {} : null)
  // Nothing outstanding at all. `null` — not `false` — because no request was
  // refused: the daemon already serves the configuration being asked for.
  if (baseline === null) return { applied: null, reason: 'already-untuned' }

  const keys = [...new Set([...Object.keys(appliedEnv ?? {}), ...exportedLaunchdKeys])]
  console.log(`🔧 Clearing the Ollama tuning PortOS applied (${keys.join(', ')})`)
  setTuning(null)

  // A non-empty baseline is just "restart under this env", which the normal
  // path already does — including taking the tuning's leftover launchd
  // variables back out of the domain. It is not an APPLICATION though: the run
  // asked for no tuning, so a success records `null`.
  if (Object.keys(baseline).length > 0) {
    const restored = await restartWithEnv(baseline, { tuning: false })
    if (restored.applied === false) {
      setTuning(baseline)
      return restored
    }
    return { ...restored, applied: null }
  }

  const exported = exportedLaunchdKeys
  // Domain variables come out FIRST, and regardless of whether a daemon is up:
  // they outlive the process that read them, so a login-launched Ollama would
  // otherwise come back tuned long after this run recorded "backend defaults".
  if (exported.length) {
    const unset = await unsetLaunchdKeys(exported)
    if (!unset.success) {
      setTuning(baseline)
      return { applied: false, reason: 'unsetenv-failed', error: unset.error }
    }
    exportedLaunchdKeys = []
  }

  const running = await checkOllamaAvailable(true)
  const service = await getServiceStatus().catch(() => null)

  // Nothing to restart. The domain is already clear and a daemon PortOS spawns
  // inherits the PortOS process environment, so whatever comes up next is
  // untuned either way.
  if (!running) {
    recordDaemon({}, null)
    return { applied: null, reason: 'not-running' }
  }

  // Every failure below leaves the daemon still tuned, so the baseline goes back
  // on the books for a later run to retry.
  const failed = (result) => {
    setTuning(baseline)
    return result
  }

  // A daemon the user registered to launch at login must keep that
  // registration: `stopServer` would un-register it. Restart it in place.
  if (service?.runAtStartup) {
    if (service.manager !== 'homebrew') {
      return failed({
        applied: false,
        reason: 'service-managed',
        error: `Ollama runs as a ${service.manager} service, which PortOS can't hand launch settings. ` +
          `Remove them with: sudo systemctl edit ollama → delete the Environment= lines for ${keys.join(', ')}, then restart it.`
      })
    }
    const bounced = await bounceService()
    if (!bounced.ok) return failed(bounced.failure)
    recordDaemon({}, await getOllamaProcessIdentity())
    console.log(`▶️ Ollama no longer carries ${keys.join(', ')}`)
    return { applied: null, reason: 'service-restarted-untuned' }
  }

  const stopped = await stopServer()
  if (!stopped.success) return failed({ applied: false, reason: 'stop-failed', error: stopped.error })
  // `env: {}`, not an omitted `env` — `startServer` records the env it launched
  // with, and an empty object is the positive statement "this daemon holds no
  // PortOS tuning". Omitting it records nothing, and the NEXT untuned run would
  // bounce the daemon again to clear a tuning that is already gone.
  const started = await startServer({ env: {} })
  return started.success
    ? { applied: null, reason: 'restarted-untuned' }
    : failed({ applied: false, reason: 'start-failed', error: started.error })
}

function isOllamaProvider(provider) {
  const endpoint = String(provider?.endpoint || '')
  return provider?.id === 'ollama' ||
    /ollama/i.test(provider?.name || '') ||
    /(^|[/:])(?:localhost|127\.0\.0\.1|\[::1\]):11434\b/i.test(endpoint)
}

async function ensureProviderReady(provider, options = {}) {
  if (!isOllamaProvider(provider)) return { success: true, skipped: true }
  return ensureRunning({ preferPersistent: options.preferPersistent !== false })
}

/**
 * Stop the Ollama HTTP server. Prefer the PortOS-managed process when we
 * started it; otherwise terminate the local `ollama` process by executable name.
 */
async function stopServer() {
  const stopped = await stopOllamaProcess()
  // Whatever spawn-time env the daemon carried left with it, whichever of the
  // three ways it went down — so there is no longer a tuning to undo. (Anything
  // PortOS put in the launchd DOMAIN outlives the process and is tracked
  // separately, by `exportedLaunchdKeys`.) Done in one place rather than at each
  // success return, where a fourth stop path would silently miss it.
  if (stopped.success) setTuning(null)
  return stopped
}

async function stopOllamaProcess() {
  if (!(await checkOllamaAvailable(true))) {
    return { success: true, running: false, alreadyStopped: true }
  }

  const service = await getServiceStatus().catch(() => null)
  if (service?.runAtStartup) {
    const stoppedService = await stopPersistentService()
    if (stoppedService.success || !(await checkOllamaAvailable(true))) return stoppedService
  }

  await terminateManagedProcess()
  if (await waitForAvailability(false, STOP_TIMEOUT_MS)) {
    resetAvailabilityCache()
    console.log('⏹️ Stopped PortOS-managed Ollama server')
    return { success: true, running: false }
  }

  if (process.platform === 'darwin' || process.platform === 'linux') {
    const killed = await execFileAsync('pkill', ['-TERM', '-x', 'ollama'], { timeout: 5_000 })
      .then(() => true)
      .catch(() => false)
    if (killed && await waitForAvailability(false, STOP_TIMEOUT_MS)) {
      resetAvailabilityCache()
      console.log('⏹️ Stopped Ollama server')
      return { success: true, running: false }
    }
  }

  return {
    success: false,
    running: true,
    error: 'Ollama is running, but PortOS could not stop the local process automatically.'
  }
}

/**
 * List installed models from /api/tags.
 * @returns {Promise<Array<{ id, name, size, family, params, quantization, modifiedAt }>>}
 */
async function getInstalledModels(forceRefresh = false) {
  if (!forceRefresh && installedModels !== null) return installedModels
  if (!(await checkOllamaAvailable())) {
    lastInstalledModelsError = status.lastError || 'Ollama is unavailable'
    return []
  }

  const data = await ollamaRequest('/api/tags').catch(() => null)
  if (!data?.models) {
    // Cache the empty result so a /api/tags failure while Ollama stays up for
    // /api/version (the availability probe) doesn't re-hit on every catalog
    // keystroke; a forceRefresh (status refresh / pull / delete) recovers it.
    lastInstalledModelsError = 'Ollama model list (/api/tags) returned no data'
    installedModels = []
    return installedModels
  }
  lastInstalledModelsError = null

  installedModels = data.models.map((m) => ({
    id: m.name || m.model,
    name: m.name || m.model,
    size: m.size ?? null,
    family: m.details?.family || null,
    params: m.details?.parameter_size || null,
    quantization: m.details?.quantization_level || null,
    modifiedAt: m.modified_at || null
  }))
  return installedModels
}

/**
 * Ollama's reported version, or `null` when it isn't answering. Exported so the
 * assessment store can record WHICH backend build a measurement was taken
 * against — a backend update is one of the things that makes a stored reading
 * stale, and there is no other way to notice it after the fact.
 */
export async function getVersion() {
  const data = await ollamaRequest('/api/version', { timeout: AVAILABILITY_PROBE_TIMEOUT_MS }).catch(() => null)
  return data?.version || null
}

// A model's native context length and capability set are immutable for a given
// build, but Ollama's /api/tags listing carries neither — only /api/show does
// (one POST per model). Cache name → { contextLength, capabilities } so
// enriching the model list on every status poll doesn't re-hit /api/show.
// Busted alongside installedModels on delete (a deleted name shouldn't linger),
// but a re-pull of the same name yields the same details so we don't bust on pull.
const modelDetailsCache = new Map() // name -> { contextLength: number|null, capabilities: string[]|null }

/**
 * Fetch a model's native details (max context length + capability set) via
 * /api/show. Ollama nests context under `model_info["<arch>.context_length"]`
 * (the arch prefix varies by family so we scan for the suffix) and reports a
 * top-level `capabilities` array (`["completion","vision","tools",…]`). Cached;
 * returns nulls/null when the request fails, and nulls/empty when the daemon
 * answers without reporting a field. The distinction keeps a transient probe
 * failure from looking like an authoritative empty capability set.
 * @param {string} name
 * @returns {Promise<{ contextLength: number|null, capabilities: string[]|null }>}
 */
async function getModelDetails(name, requestOptions = {}) {
  const miss = { contextLength: null, capabilities: null }
  if (!name) return miss
  if (modelDetailsCache.has(name)) return modelDetailsCache.get(name)
  // /api/show documents the id under `model`; current Ollama also accepts the
  // legacy `name`, so send both (extra fields are ignored) for cross-version safety.
  const data = await ollamaRequest('/api/show', { ...requestOptions, method: 'POST', body: JSON.stringify({ model: name, name }) }).catch(() => null)
  // A transient /api/show failure must NOT be cached — that would pin the model
  // with no context label / wrong vision flag until restart. Only cache when the
  // daemon actually answered; a present-but-missing field legitimately caches
  // its empty default. Mirrors the null-vs-empty sentinel rule used by the
  // installed-model caches.
  if (!data) return miss
  let contextLength = null
  for (const [key, value] of Object.entries(data.model_info || {})) {
    if (key.endsWith('.context_length') && Number.isFinite(value)) { contextLength = value; break }
  }
  const details = {
    contextLength,
    capabilities: Array.isArray(data.capabilities) ? data.capabilities : []
  }
  modelDetailsCache.set(name, details)
  return details
}

/**
 * A model's capability set (`["completion","vision","tools",…]`) from /api/show.
 * Lets vision detection see capabilities that the /api/tags id can't reveal —
 * e.g. a vision-capable MoE like `qwen3.6:35b` whose id has no `vl`/`vision`
 * token. Cached; returns `null` when the per-model probe fails and `[]` when
 * the daemon answers without reporting capabilities.
 * @param {string} name
 * @returns {Promise<string[]|null>}
 */
async function getModelCapabilities(name, requestOptions = {}) {
  return (await getModelDetails(name, requestOptions)).capabilities
}

/** Add `contextLength` + `capabilities` to each model (parallel, cached). */
async function enrichWithModelDetails(models) {
  return Promise.all(models.map(async (m) => {
    const { contextLength, capabilities } = await getModelDetails(m.id || m.name)
    return { ...m, contextLength, capabilities }
  }))
}

/**
 * Get embeddings for `text` from a loaded Ollama model.
 *
 * Mirrors lmStudioManager.getEmbeddings shape — returns
 * `{ success, embedding, model, dimensions }` so server/services/embeddings.js
 * can route either backend through one interface.
 *
 * Ollama 0.2+ exposes `POST /api/embed` with `{ model, input }` → `{ embeddings: [[...]] }`.
 * Older daemons only have `POST /api/embeddings` with `{ model, prompt }` → `{ embedding: [...] }`.
 * We try the modern endpoint first, fall back on a 404/400.
 *
 * Auto-discovery: when `options.model` is omitted, scan installed models
 * for a name matching a known embedding-model heuristic (embed/bge/nomic/mxbai)
 * since Ollama tags don't carry a "type=embedding" flag.
 */
async function getEmbeddings(text, options = {}) {
  const available = await checkOllamaAvailable()
  if (!available) {
    return { success: false, error: 'Ollama not available' }
  }

  let model = options.model
  if (!model) {
    const models = await getInstalledModels()
    const guess = models.find((m) => isEmbeddingModel(m.id || m.name || ''))
    if (!guess) {
      return { success: false, error: 'No embedding model installed in Ollama' }
    }
    model = guess.id || guess.name
  }

  const tryEndpoint = async (endpoint, body) => {
    const response = await fetchWithTimeout(`${config.baseUrl}${endpoint}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }, options.timeout ?? 30_000).catch((err) => ({ _err: err.message }))
    if (response._err) return { ok: false, error: response._err }
    if (!response.ok) {
      const errBody = await response.text().catch(() => '')
      return { ok: false, status: response.status, error: errBody.slice(0, 200) }
    }
    return { ok: true, data: await readResponseJson(response) }
  }

  // Modern endpoint: `/api/embed` returns `{ embeddings: [[...]] }`
  let result = await tryEndpoint('/api/embed', { model, input: text })
  let embedding = result.ok ? (result.data?.embeddings?.[0] || []) : null

  // Fallback for older Ollama: `/api/embeddings` returns `{ embedding: [...] }`
  if (!result.ok || !embedding?.length) {
    const fallback = await tryEndpoint('/api/embeddings', { model, prompt: text })
    if (!fallback.ok) {
      return { success: false, error: result.error || fallback.error, model }
    }
    embedding = fallback.data?.embedding || []
  }

  return {
    success: true,
    embedding,
    model,
    dimensions: embedding.length
  }
}

/**
 * Read residency from a specific provider endpoint without touching the global
 * manager's availability cache or error state.
 * @returns {Promise<{models:Array<{id,name,size,sizeVram,expiresAt}>,error:string|null}>}
 */
async function getLoadedModelsAt(baseUrl, options = {}) {
  const data = await ollamaRequestAt(baseUrl, '/api/ps', options).catch((err) => ({ _err: err.message }))
  if (!Array.isArray(data?.models)) {
    return { models: [], error: data?._err || 'Ollama residency endpoint returned no model list' }
  }
  return {
    models: data.models.map((m) => ({
      id: m.name || m.model,
      name: m.name || m.model,
      size: m.size ?? null,
      sizeVram: m.size_vram ?? null,
      expiresAt: m.expires_at || null
    })),
    error: null
  }
}

/**
 * List models currently loaded into VRAM/unified memory on the configured
 * Ollama daemon. Distinct from getInstalledModels(): a model on disk doesn't
 * occupy memory until it's referenced by a request.
 * @returns {Promise<Array<{ id, name, size, sizeVram, expiresAt }>>}
 */
async function getLoadedModels(options = {}) {
  if (!(await checkOllamaAvailable())) {
    lastLoadedModelsError = status.lastError || 'Ollama is unavailable'
    return []
  }
  const result = await getLoadedModelsAt(config.baseUrl, options)
  lastLoadedModelsError = result.error
  return result.models
}

/** Last `/api/tags` error (null only after a trustworthy installed list). */
function getLastInstalledModelsError() {
  return lastInstalledModelsError
}

/** Last `/api/ps` error (null only after a trustworthy residency list). */
function getLastLoadedModelsError() {
  return lastLoadedModelsError
}

/**
 * Force Ollama to evict a specific model from memory immediately.
 * Uses the documented `keep_alive: 0` trick — issuing any generate/chat
 * request with keep_alive=0 expires the model the moment the request
 * resolves. We send an empty prompt so no tokens are generated.
 *
 * Precondition: only fires the evict when the model is currently resident
 * per `/api/ps`. Without the check, `/api/generate` against a non-loaded
 * model triggers Ollama to LOAD it from disk (potentially many GB) just
 * to immediately evict — a thrash/DoS-amplification footgun reachable
 * from any LAN client once `/api/local-llm/unload` is wired.
 * @returns {Promise<{ unloaded: true, model: string } | { unloaded: false, reason: string }>}
 */
async function unloadModel(modelName) {
  if (typeof modelName !== 'string' || modelName.length === 0) {
    return { unloaded: false, reason: 'missing model name' }
  }
  if (!(await checkOllamaAvailable())) {
    return { unloaded: false, reason: 'Ollama unreachable' }
  }
  const loaded = await getLoadedModels()
  if (getLastLoadedModelsError()) {
    return { unloaded: false, reason: 'Could not verify whether the model is loaded' }
  }
  if (!loaded.some((m) => m.id === modelName || m.name === modelName)) {
    return { unloaded: false, reason: 'not loaded' }
  }
  // Native fetch does NOT auto-stringify object bodies — pass JSON.stringify
  // so the wire body is valid JSON, not "[object Object]".
  const body = JSON.stringify({ model: modelName, prompt: '', keep_alive: 0, stream: false })
  const result = await ollamaRequest('/api/generate', { method: 'POST', body }).catch((err) => ({ _err: err }))
  if (result && result._err) {
    return { unloaded: false, reason: result._err.message || 'request failed' }
  }
  console.log(`🧹 ollama: unloaded ${modelName} (keep_alive=0)`)
  invalidateModelObservation('loaded-models')
  return { unloaded: true, model: modelName }
}

/**
 * Make `modelName` resident so the next request doesn't pay a cold load.
 * The inverse of `unloadModel`: an empty-prompt `/api/generate` with a
 * non-zero `keep_alive` loads the weights and returns without generating
 * tokens (Ollama answers with `done_reason: "load"`).
 *
 * Unlike the unload path there is deliberately NO "already resident" guard
 * here — the caller checks `/api/ps` first because re-warming is merely
 * wasteful, whereas an unguarded UNLOAD-shaped request against a cold model
 * would load many GB just to evict it.
 * @returns {Promise<{ warmed: true, model: string } | { warmed: false, reason: string }>}
 */
async function warmModel(modelName, keepAlive = '30m') {
  if (typeof modelName !== 'string' || modelName.length === 0) {
    return { warmed: false, reason: 'missing model name' }
  }
  if (!(await checkOllamaAvailable())) {
    return { warmed: false, reason: 'Ollama unreachable' }
  }
  const body = JSON.stringify({ model: modelName, prompt: '', keep_alive: keepAlive, stream: false })
  const result = await ollamaRequest('/api/generate', { method: 'POST', body }).catch((err) => ({ _err: err }))
  if (result && result._err) {
    return { warmed: false, reason: result._err.message || 'request failed' }
  }
  return { warmed: true, model: modelName }
}

/**
 * Pull a model, streaming progress. Resolves once the pull finishes.
 * Non-percent frames carry a reason flag so the UI can show why the banner is
 * paused instead of stalling: `retrying: true` during a transient-error backoff,
 * `finalizing: true` while PortOS completes an install Ollama abandoned (see
 * finalizeHuggingFacePull). A success that went through that recovery is flagged
 * `recovered: true`.
 * @param {string} modelId
 * @param {(p: { status: string, percent: number|null, completed?: number, total?: number, retrying?: boolean, finalizing?: boolean }) => void} [onProgress]
 * @returns {Promise<{ success: boolean, modelId: string, error?: string, recovered?: boolean }>}
 */
async function pullModel(modelId, onProgress) {
  if (!(await checkOllamaAvailable())) {
    return { success: false, error: 'Ollama not available', modelId }
  }
  console.log(`📥 Ollama pull: ${modelId}`)

  let lastError = null
  for (let attempt = 1; attempt <= PULL_MAX_ATTEMPTS; attempt++) {
    const result = await attemptOllamaPull(modelId, onProgress)
    if (result.success) {
      installedModels = null  // bust cache so the new model shows on next list
      console.log(`✅ Ollama pull complete: ${modelId}${attempt > 1 ? ` (after ${attempt} attempts)` : ''}`)
      return { success: true, modelId }
    }
    lastError = result.error
    // Bad model name / missing manifest etc. won't fix themselves — only retry
    // the transient network class, and only while attempts remain.
    if (attempt >= PULL_MAX_ATTEMPTS || !isTransientPullError(lastError)) break
    const delayMs = PULL_RETRY_BASE_DELAY_MS * attempt
    console.log(`🔁 Ollama pull ${modelId} hit transient error "${lastError}" (attempt ${attempt}/${PULL_MAX_ATTEMPTS}); retrying in ${delayMs}ms`)
    if (typeof onProgress === 'function') onProgress({ status: 'retrying after network error', percent: null, retrying: true })
    await sleep(delayMs)
  }

  // The weights may all be on disk and only Ollama's manifest write missing —
  // retrying just re-races the same deadline, so finish the pull ourselves.
  // Gated on the ref being one we can actually finish, so a deadline against a
  // non-HF registry doesn't flash a "finishing install…" banner for a recovery
  // that has nowhere to fetch from.
  if (isPullDeadlineError(lastError) && huggingFaceRegistryBase(parseOllamaModelRef(modelId))) {
    if (typeof onProgress === 'function') {
      onProgress({ status: 'finishing install from downloaded files…', percent: null, finalizing: true })
    }
    const recovered = await finalizeHuggingFacePull(modelId).catch((err) => ({ success: false, error: err.message }))
    if (recovered.success) {
      installedModels = null  // bust cache so the recovered model shows on next list
      return { success: true, modelId, recovered: true }
    }
    console.warn(`⚠️ Ollama pull recovery declined for ${modelId}: ${recovered.error}`)
  }

  console.error(`⚠️ Ollama pull failed for ${modelId}: ${lastError}`)
  const code = isShardedGgufError(lastError) ? 'SHARDED_GGUF'
    : isOllamaOutdatedError(lastError) ? 'OLLAMA_OUTDATED'
      : undefined
  return { success: false, error: lastError, modelId, ...(code ? { code } : {}) }
}

function hfImportError(status, statusText) {
  if (status === 401 || status === 403) {
    return 'Hugging Face denied access. Accept the repository terms, then configure a Hugging Face token in Settings.'
  }
  return `Hugging Face request failed: ${status} ${statusText}`
}

async function downloadHfImportFile({ repo, remotePath, destination, headers, progress }) {
  const url = buildHfResolveUrl(repo, 'main', remotePath)
  try {
    const response = await fetchWithTimeout(url, { headers }, 0)
    if (!response.ok || !response.body) throw new Error(hfImportError(response.status, response.statusText))
    await ensureDir(dirname(destination))
    const tracker = new Transform({
      transform(chunk, _encoding, callback) {
        progress(chunk.length)
        callback(null, chunk)
      }
    })
    await pipeline(Readable.fromWeb(response.body), tracker, createWriteStream(destination))
  } catch (err) {
    if (!(err instanceof TypeError) || !/^(fetch failed|terminated)$/.test(err.message)) throw err
    throw new Error('Hugging Face checkpoint download was interrupted. Check the connection and retry the installation.', { cause: err })
  }
}

/**
 * Download a curated Hugging Face Safetensors subdirectory and import it through
 * Ollama's supported `ollama create` path. The caller supplies only catalog-owned
 * recipes; arbitrary free-text ids continue through pullModel instead.
 *
 * The create step is supervised (see ollamaSafetensorsImport.js): a silent
 * create resolves `OLLAMA_IMPORT_STALLED`, or `OLLAMA_IMPORT_HELD` with
 * `stagingRetained: true` when PortOS cannot prove nothing still reads the
 * staged checkpoint — a retry then reuses that staging.
 *
 * @param {{ modelId: string, repo: string, subdir: string, minVersion?: string }} spec
 * @param {(p: { status: string, percent: number|null, completed?: number, total?: number, importing?: boolean }) => void} [onProgress]
 */
async function importModelFromHfSafetensors(spec, onProgress) {
  const { modelId } = spec
  // One import per model at a time: a second would mistake the first's live
  // staging for one left behind. Checked before any network round-trip.
  if (activeImports.has(modelId)) {
    return { success: false, error: `${modelId} is already being imported.`, modelId, code: 'OLLAMA_IMPORT_IN_PROGRESS' }
  }
  activeImports.add(modelId)
  try {
    return await prepareSafetensorsImport(spec, onProgress)
  } finally {
    activeImports.delete(modelId)
  }
}

async function prepareSafetensorsImport(spec, onProgress) {
  const { modelId, repo, subdir, minVersion = '0.19.0' } = spec
  if (!(await checkOllamaAvailable())) {
    return { success: false, error: 'Ollama not available', modelId }
  }
  const version = await getVersion()
  if (!version || compareSemver(version.replace(/^v/, ''), minVersion.replace(/^v/, '')) < 0) {
    return {
      success: false,
      error: `This MLX import requires Ollama ${minVersion} or newer${version ? ` (installed: ${version})` : ''}.`,
      modelId,
      code: 'OLLAMA_OUTDATED'
    }
  }
  const { getHfToken } = await import('./hfToken.js')
  const token = await getHfToken()
  if (!token) {
    return {
      success: false,
      error: 'This gated model requires a Hugging Face token. Accept the repository terms, then configure a token in Settings.',
      modelId,
      code: 'HF_TOKEN_REQUIRED'
    }
  }
  if (!(await commandExists('ollama', ['--version']))) {
    return { success: false, error: 'The Ollama CLI is required to import Safetensors models.', modelId }
  }

  const headers = buildHfAuthHeaders(token)
  const metadataUrl = `${HF_API}/${repo}?blobs=true`
  const metadataResponse = await fetchWithTimeout(metadataUrl, { headers }, HF_IMPORT_METADATA_TIMEOUT_MS)
    .catch((err) => ({ _err: describeFetchError(err) }))
  if (metadataResponse._err) return { success: false, error: metadataResponse._err, modelId }
  if (!metadataResponse.ok) {
    return { success: false, error: hfImportError(metadataResponse.status, metadataResponse.statusText), modelId }
  }
  const metadata = await metadataResponse.json().catch(() => null)
  const prefix = `${subdir.replace(/\/+$/, '')}/`
  const files = (metadata?.siblings || [])
    .filter((file) => typeof file.rfilename === 'string' && file.rfilename.startsWith(prefix))
    .map((file) => ({
      remotePath: file.rfilename,
      relativePath: file.rfilename.slice(prefix.length),
      size: Number(file.lfs?.size ?? file.size) || 0
    }))
    .filter((file) => isSafeHfRepoRelativePath(file.relativePath))
  if (!files.some((file) => file.relativePath.endsWith('.safetensors')) || !files.some((file) => file.relativePath === 'config.json')) {
    return { success: false, error: `The ${subdir} checkpoint is incomplete or unavailable on Hugging Face.`, modelId }
  }

  // Resolve-not-throw, like every other failure here. A staging write that
  // throws leaves its marker behind; the next attempt reuses or retires it.
  return runSafetensorsImport({ modelId, repo, subdir, files, headers, onProgress })
    .catch((err) => ({ success: false, error: err.message, modelId }))
}

const heldImportResult = (modelId, error, reason) => ({
  success: false,
  modelId,
  code: 'OLLAMA_IMPORT_HELD',
  stagingRetained: true,
  error: `${error} Ollama may still be reading the downloaded checkpoint (${reason}), so PortOS kept it instead of deleting it. Retry the installation to reuse it without downloading again.`
})

async function runSafetensorsImport({ modelId, repo, subdir, files, headers, onProgress }) {
  // Ordinary daemon and model reads need none of the staged-import lifecycle.
  const {
    awaitStagingRelease, blobStoreSignature, createImportStaging, findImportStaging, removeImportStaging,
    runSupervisedOllamaCreate, stagedFilesComplete, sweepImportStaging, updateImportStaging
  } = await import('./ollamaSafetensorsImport.js')
  let tempRoot = null
  let reuse = false
  // A staging directory from an earlier attempt (a stalled create, or a
  // PortOS restart mid-import) is reused when it holds the whole checkpoint;
  // an incomplete one is retired only once nothing holds it open.
  await sweepImportStaging({ modelId, activeModelIds: activeImports })
    .catch((err) => console.error(`❌ Safetensors staging sweep failed: ${err.message}`))
  const retained = await findImportStaging(modelId)
  if (retained) {
    // Equal file sizes alone could pass a checkpoint from another repo or
    // subdir off as this one; a marker that cannot name its source is retired.
    const sameSource = retained.marker.repo === repo && retained.marker.subdir === subdir
    const complete = sameSource && await stagedFilesComplete(join(retained.tempRoot, 'model'), files)
    if (complete) {
      // Reusing is non-destructive, but stacking a second create on one the
      // daemon is still running is not; wait only for a holder we can see.
      const release = await awaitStagingRelease(retained.tempRoot, { attempts: 1 })
      if (release.pids?.length) {
        return heldImportResult(modelId, `A previous import of ${modelId} is still running.`, release.reason)
      }
      tempRoot = retained.tempRoot
      reuse = true
      console.log(`♻️ Reusing retained Safetensors staging for ${modelId}`)
    } else if (retained.marker.phase === 'downloading') {
      // `ollama create` never started, so no other process ever read it.
      await removeImportStaging(retained.tempRoot)
    } else {
      const release = await awaitStagingRelease(retained.tempRoot, { attempts: 1 })
      if (!release.free) {
        return heldImportResult(modelId, `A previous import of ${modelId} left a checkpoint it cannot reuse.`, release.reason)
      }
      await removeImportStaging(retained.tempRoot)
    }
  }

  // This import writes the checkpoint TWICE — once staged under `tmpdir()`,
  // once more when `ollama create` below lands it in the models dir — on
  // volumes that can differ (a temp partition, or OLLAMA_MODELS pointed at
  // external storage). The outer installModel() preflight only checked one
  // copy against one of those volumes using a catalog-string size estimate;
  // this uses the real per-file bytes this import already fetched from HF.
  const total = files.reduce((sum, file) => sum + file.size, 0)
  if (!reuse) {
    const stagingPreflight = await assessDownloadPreflight({ destPath: tmpdir(), expectedBytes: total })
    if (stagingPreflight.verdict === DOWNLOAD_VERDICTS.INSUFFICIENT) {
      return { success: false, error: diskInsufficientError(stagingPreflight).message, modelId, code: 'DISK_INSUFFICIENT' }
    }
  }
  const modelsDirPreflight = await assessDownloadPreflight({ destPath: getModelsDir(), expectedBytes: total })
  if (modelsDirPreflight.verdict === DOWNLOAD_VERDICTS.INSUFFICIENT) {
    return { success: false, error: diskInsufficientError(modelsDirPreflight).message, modelId, code: 'DISK_INSUFFICIENT' }
  }

  if (!tempRoot) tempRoot = await createImportStaging({ modelId, repo, subdir })
  const modelDir = join(tempRoot, 'model')
  if (!reuse) {
    let completed = 0
    let lastPercent = -1
    const reportBytes = (bytes) => {
      completed += bytes
      const percent = total > 0 ? Math.min(100, Math.floor((completed / total) * 100)) : null
      if (percent === lastPercent) return
      lastPercent = percent
      if (typeof onProgress === 'function') onProgress({ status: 'downloading MLX checkpoint', percent, completed, total })
    }
    const downloadError = await (async () => {
      for (const file of files) {
        await downloadHfImportFile({
          repo,
          remotePath: file.remotePath,
          destination: join(modelDir, ...file.relativePath.split('/')),
          headers,
          progress: reportBytes
        })
      }
    })().then(() => null, (err) => err)
    if (downloadError) {
      await removeImportStaging(tempRoot)
      return { success: false, error: downloadError.message, modelId }
    }
  }

  const modelfile = join(tempRoot, 'Modelfile')
  await atomicWrite(modelfile, `FROM ${modelDir}\n`)
  await updateImportStaging(tempRoot, { phase: 'creating' })
  const report = (status) => {
    if (typeof onProgress === 'function') onProgress({ status, percent: null, importing: true })
  }
  report('importing checkpoint into Ollama')
  const outcome = await runSupervisedOllamaCreate({
    modelId,
    modelfile,
    onStatus: (line) => report(`importing: ${line}`),
    probeProgress: () => blobStoreSignature(getModelsDir())
  })
  if (outcome.status === 'completed') {
    // A clean CLI exit means the daemon answered the whole create request.
    await removeImportStaging(tempRoot)
    installedModels = null
    console.log(`✅ Ollama Safetensors import complete: ${modelId}`)
    return { success: true, modelId }
  }

  const release = outcome.exited === false
    ? { free: false, reason: 'the ollama create process did not exit after being stopped' }
    : await awaitStagingRelease(tempRoot)
  if (release.free) {
    await removeImportStaging(tempRoot)
    return { success: false, error: outcome.error, modelId, ...(outcome.status === 'stalled' ? { code: 'OLLAMA_IMPORT_STALLED' } : {}) }
  }
  await updateImportStaging(tempRoot, { phase: 'retained', retainedAt: new Date().toISOString(), reason: release.reason })
  console.log(`⏭️ Kept Safetensors staging for ${modelId}: ${release.reason}`)
  return heldImportResult(modelId, outcome.error, release.reason)
}

/**
 * Detect the Go-runtime deadline Ollama reports when a registry request outlives
 * its internal per-request budget: `context deadline exceeded`. Distinctive
 * because it lands AFTER the weight layers hit 100% — the blobs are downloaded
 * and verified, only the manifest write is missing — which is what makes the
 * local-completion recovery in finalizeHuggingFacePull() safe to attempt.
 *
 * Deliberately NOT part of isTransientPullError: retrying re-races the same slow
 * endpoint against the same deadline and fails identically every time.
 * @param {string|null|undefined} error
 */
function isPullDeadlineError(error) {
  return /context deadline exceeded/i.test(String(error ?? ''))
}

/**
 * Detect Ollama's refusal to pull a multi-part (sharded) GGUF. The HF passthrough
 * registry returns a 400 whose message names "sharded GGUF" and links the tracking
 * issue (ollama/ollama#5245). The catalog already flags sharded quants so the UI
 * disables Install — this classifier is defense-in-depth for the pull-by-name path
 * (a raw `hf.co/<repo>:<quant>` typed into the search box) so the caller can show
 * an actionable message instead of the raw 400. Match the phrase plus the 400 so
 * an unrelated 400 can't slip through.
 * @param {string|null|undefined} error
 */
function isShardedGgufError(error) {
  if (!error) return false
  const str = String(error)
  return /\b400\b/.test(str) && /sharded gguf/i.test(str)
}

/**
 * Detect Ollama's "model requires a newer version" 412 response surfaced in the
 * NDJSON stream. The registry returns it when a new model format (e.g. a fresh
 * GGUF feature) lands before the local Ollama binary supports it; the fix is to
 * upgrade the Ollama install. The error string we see looks like:
 *   "pull model manifest: 412: The model you are attempting to pull requires
 *    a newer version of Ollama. Please download the latest version at: …"
 * Match on the "newer version of Ollama" phrase plus the 412 status code so a
 * benign 412 from an unrelated path can't slip through.
 * @param {string|null|undefined} error
 */
function isOllamaOutdatedError(error) {
  if (!error) return false
  const str = String(error)
  return /\b412\b/.test(str) && /newer version of ollama/i.test(str)
}

/**
 * A single pull attempt. Returns `{ success }` or `{ success: false, error }`.
 * A read that rejects mid-stream (dropped connection) is caught and returned as
 * an error string so the caller's retry loop can classify it like an `{error}`
 * frame rather than letting it throw out of the request lifecycle.
 * @param {string} modelId
 * @param {(p: object) => void} [onProgress]
 * @returns {Promise<{ success: boolean, error?: string }>}
 */
async function attemptOllamaPull(modelId, onProgress) {
  // No timeout — multi-GB pulls take minutes; the stream is the lifecycle.
  const response = await fetchWithTimeout(`${config.baseUrl}/api/pull`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: modelId, stream: true })
  }, 0).catch((err) => ({ _err: describeFetchError(err) }))

  if (response._err || !response.ok || !response.body) {
    return { success: false, error: response._err || `pull failed: ${response.status} ${response.statusText}` }
  }

  const lastError = await streamNdjson(response, (frame) => {
    if (typeof onProgress === 'function') {
      const percent = frame.total > 0 && frame.completed >= 0
        ? Math.round((frame.completed / frame.total) * 100)
        : null
      onProgress({ status: frame.status || '', percent, completed: frame.completed, total: frame.total })
    }
  }).catch((err) => err?.message || String(err))

  return lastError ? { success: false, error: lastError } : { success: true }
}

/**
 * Classify a pull/stream error string as a transient network failure worth
 * retrying (Ollama↔registry EOF, connection reset, undici "terminated", etc.).
 * Non-transient errors — invalid model name, "file does not exist" — return
 * false so the retry loop gives up immediately.
 * @param {string|null|undefined} error
 * @returns {boolean}
 */
function isTransientPullError(error) {
  if (!error) return false
  return /\beof\b|connection reset|reset by peer|broken pipe|socket hang up|other side closed|terminated|i\/o timeout|\btimeout\b|tls handshake|temporary failure|network is unreachable|connection refused|econnreset|etimedout|epipe/i.test(String(error))
}

/**
 * Consume an Ollama NDJSON progress stream (used by /api/pull and /api/create).
 * Returns the last `{ error }` seen, or null on a clean stream. Reads via
 * getReader() to match the codebase's streaming convention; try/finally releases
 * the reader even if a read rejects mid-stream (avoids leaking the connection).
 * Flushes the decoder + trailing buffer so a final frame that wasn't newline-
 * terminated (notably a terminal `{"error":...}`) isn't silently dropped.
 * @param {Response} response - a fetch Response with a readable body
 * @param {(frame: object) => void} [onFrame]
 * @returns {Promise<string|null>} last error message, or null
 */
async function streamNdjson(response, onFrame) {
  const reader = response.body.getReader()
  const decoder = new TextDecoder()
  let buffer = ''
  let lastError = null

  const handleFrame = (line) => {
    const trimmed = line.trim()
    if (!trimmed) return
    const frame = safeParse(trimmed)
    if (!frame) return
    if (frame.error) lastError = frame.error
    if (typeof onFrame === 'function') onFrame(frame)
  }

  try {
    while (true) {
      const { value, done } = await reader.read()
      if (done) break
      buffer += decoder.decode(value, { stream: true })
      let nl
      while ((nl = buffer.indexOf('\n')) !== -1) {
        handleFrame(buffer.slice(0, nl))
        buffer = buffer.slice(nl + 1)
      }
    }
    buffer += decoder.decode()
    handleFrame(buffer)
  } finally {
    reader.releaseLock()
  }
  return lastError
}

// safeJSONParse imported from fileUtils provides identical null-on-failure semantics.
const safeParse = (line) => safeJSONParse(line, null);

/**
 * Delete an installed model (DELETE /api/delete).
 */
async function deleteModel(modelId) {
  if (!(await checkOllamaAvailable())) {
    return { success: false, error: 'Ollama not available', modelId }
  }
  const result = await ollamaRequest('/api/delete', {
    method: 'DELETE',
    body: JSON.stringify({ name: modelId }),
    timeout: 15_000
  }).then(() => ({ ok: true })).catch((err) => ({ _err: err.message }))

  if (result._err) {
    return { success: false, error: result._err, modelId }
  }
  installedModels = null
  modelDetailsCache.delete(modelId)
  console.log(`🗑️ Ollama deleted: ${modelId}`)
  return { success: true, modelId }
}

// ---- local-disk introspection / import (migrate fast-path) ------------------

/** Ollama's models root: `$OLLAMA_MODELS` or `~/.ollama/models`. */
function getModelsDir() {
  return process.env.OLLAMA_MODELS || join(homedir(), '.ollama', 'models')
}

/**
 * Enumerate Ollama manifests directly from disk so a stopped daemon does not
 * erase downloaded inventory. A corrupt or unreadable manifest rejects the
 * scan: counted UI must not turn unreadable state into a trustworthy empty.
 */
async function listStoredModels() {
  const manifestsDir = join(getModelsDir(), 'manifests')
  const root = await stat(manifestsDir).then((entry) => entry.isDirectory(), (err) => {
    if (err?.code === 'ENOENT') return false
    throw err
  })
  if (!root) return []

  const registries = (await readdir(manifestsDir, { withFileTypes: true }))
    .filter((entry) => entry.isDirectory())
  const models = []
  for (const registry of registries) {
    const registryDir = join(manifestsDir, registry.name)
    const namespaces = (await readdir(registryDir, { withFileTypes: true }))
      .filter((entry) => entry.isDirectory())
    for (const namespace of namespaces) {
      const namespaceDir = join(registryDir, namespace.name)
      const names = (await readdir(namespaceDir, { withFileTypes: true }))
        .filter((entry) => entry.isDirectory())
      for (const name of names) {
        const nameDir = join(namespaceDir, name.name)
        const tags = (await readdir(nameDir, { withFileTypes: true }))
          .filter((entry) => entry.isFile())
        for (const tag of tags) {
          const manifest = await readJSONFile(join(nameDir, tag.name), null, { logError: false, strict: true })
          if (!manifest) throw new Error(`Ollama manifest disappeared during inventory: ${tag.name}`)
          const sizes = manifestBlobRefs(manifest).map((blob) => blob.size)
          const size = sizes.length > 0 && sizes.every(Number.isFinite)
            ? sizes.reduce((sum, value) => sum + value, 0)
            : null
          const localRegistry = registry.name === 'registry.ollama.ai'
          const localNamespace = namespace.name === 'library'
          const base = localRegistry && localNamespace
            ? name.name
            : localRegistry
              ? `${namespace.name}/${name.name}`
              : `${registry.name}/${namespace.name}/${name.name}`
          const id = `${base}:${tag.name}`
          models.push({ id, name: id, size })
        }
      }
    }
  }
  return models.sort((a, b) => (b.size || 0) - (a.size || 0))
}

const fileExists = (p) => stat(p).then((s) => s.isFile()).catch(() => false)
const readManifest = (p) => readJSONFile(p, null, { logError: false })
// One expression for the canonical manifest path, so the recovery writer and
// findManifest's reader can't drift apart.
const manifestPathFor = (modelsDir, ref) => join(modelsDir, ...ollamaManifestRelPath(ref).split('/'))

// The canonical manifest path covers registry-pulled models; fall back to a
// shallow scan of manifests/<registry>/<namespace>/<name>/<tag> for custom
// registries/namespaces we didn't guess.
async function findManifest(modelsDir, ref) {
  const direct = await readManifest(manifestPathFor(modelsDir, ref))
  if (direct) return direct
  const manifestsDir = join(modelsDir, 'manifests')
  const registries = await readdir(manifestsDir).catch(() => [])
  for (const registry of registries) {
    const namespaces = await readdir(join(manifestsDir, registry)).catch(() => [])
    for (const ns of namespaces) {
      const candidate = join(manifestsDir, registry, ns, ref.name, ref.tag)
      const m = await readManifest(candidate)
      if (m) return m
    }
  }
  return null
}

/**
 * Fetch a Hugging Face registry document (manifest or blob) as a Buffer, with a
 * timeout generous enough for HF's slow cold-CDN small-blob path (the very thing
 * Ollama's own deadline gives up on). Carries the user's HF token when they have
 * one, so a gated repo Ollama could pull is recoverable too.
 * @returns {Promise<{ buffer: Buffer }|{ error: string }>}
 */
async function fetchHuggingFaceDocument(url, headers) {
  return fetchWithTimeout(url, { headers }, HF_FINALIZE_TIMEOUT_MS)
    .then(async (response) => (response.ok
      ? { buffer: Buffer.from(await response.arrayBuffer()) }
      : { error: `${response.status} ${response.statusText}` }))
    .catch((err) => ({ error: describeFetchError(err) }))
}

/**
 * Finish a Hugging Face pull that downloaded its weights but died before Ollama
 * wrote the manifest (see HF_FINALIZE_TIMEOUT_MS). Re-fetches the manifest, then
 * for each blob it references: keeps an on-disk blob whose size already matches,
 * and downloads + digest-verifies any small missing one. Only when EVERY blob is
 * present and correct does it write the manifest — a half-written manifest would
 * leave `ollama run` failing on a missing blob, which is worse than no model.
 *
 * Digest verification is the whole safety story here: we are hand-placing files
 * into Ollama's content-addressed store, so a byte we didn't verify is a corrupt
 * model that reports as installed.
 *
 * Pure disk + network: the caller owns the `installedModels` cache bust, so this
 * stays safe to call from a future "repair this install" action.
 *
 * @param {string} modelId e.g. `hf.co/<owner>/<repo>:Q8_0`
 * @returns {Promise<{ success: boolean, error?: string }>}
 */
async function finalizeHuggingFacePull(modelId) {
  const ref = parseOllamaModelRef(modelId)
  const base = huggingFaceRegistryBase(ref)
  if (!base) return { success: false, error: 'not a Hugging Face model ref' }

  const modelsDir = getModelsDir()
  const blobsDir = join(modelsDir, 'blobs')
  // Imported lazily: hfToken.js reaches settings.js, which resolves its file
  // path from PATHS at module load — a static import would drag that (and
  // everything settings pulls in) into every consumer of this module.
  const { getHfToken } = await import('./hfToken.js')
  const headers = buildHfAuthHeaders(await getHfToken())
  const fetched = await fetchHuggingFaceDocument(`${base}/manifests/${ref.tag}`, headers)
  if (fetched.error) return { success: false, error: `manifest fetch failed: ${fetched.error}` }

  const manifestText = fetched.buffer.toString('utf8')
  const refs = manifestBlobRefs(safeJSONParse(manifestText, null))
  if (refs.length === 0) return { success: false, error: 'manifest listed no blobs' }

  for (const blob of refs) {
    const blobPath = join(blobsDir, blob.filename)
    const existing = await stat(blobPath).then((s) => s.size, () => null)
    // Ollama already verified anything it finished writing, so a size match is
    // enough to accept it — re-hashing a 30GB weight layer would take minutes.
    if (existing !== null && existing === blob.size) continue
    if (blob.size === null || blob.size > HF_FINALIZE_MAX_BLOB_BYTES) {
      return { success: false, error: `blob ${blob.filename} (${blob.size ?? 'unknown'} bytes) is missing and too large to recover` }
    }
    const got = await fetchHuggingFaceDocument(`${base}/blobs/${blob.digest}`, headers)
    if (got.error) return { success: false, error: `blob ${blob.filename} fetch failed: ${got.error}` }
    const hex = createHash('sha256').update(got.buffer).digest('hex')
    if (hex !== blob.hex) return { success: false, error: `blob ${blob.filename} failed digest verification` }
    await atomicWrite(blobPath, got.buffer)
    console.log(`🧩 Ollama pull recovery: restored blob ${blob.filename.slice(0, 19)} (${got.buffer.length}B) for ${modelId}`)
  }

  // Ollama leaves `<blob>-partial*` scratch files behind for the download it
  // abandoned; they'd shadow the completed blobs on a future resume attempt. One
  // pass over the (potentially large) blobs dir clears every blob's leftovers.
  const scratch = await readdir(blobsDir).catch(() => [])
  await Promise.all(scratch
    .filter((name) => refs.some((blob) => name.startsWith(`${blob.filename}-partial`)))
    .map((name) => unlink(join(blobsDir, name)).catch(() => {})))

  // Write the manifest byte-for-byte as the registry served it so the digest
  // Ollama derives from it matches the registry's.
  await atomicWrite(manifestPathFor(modelsDir, ref), manifestText)
  console.log(`✅ Ollama pull recovery: wrote manifest for ${modelId} (${refs.length} blobs verified)`)
  return { success: true }
}

/**
 * Locate an installed Ollama model's weight files on disk (no network).
 * @returns {Promise<{ ggufPath: string, projectorPath: string|null, isMlx: false, isSharded: false }|null>}
 */
async function resolveLocalModel(modelId) {
  const modelsDir = getModelsDir()
  const manifest = await findManifest(modelsDir, parseOllamaModelRef(modelId))
  if (!manifest) return null
  const { modelDigest, projectorDigest } = parseOllamaManifest(manifest)
  if (!modelDigest) return null
  const ggufPath = join(modelsDir, 'blobs', digestToBlobFilename(modelDigest))
  if (!(await fileExists(ggufPath))) return null
  // Only report a projector the manifest references AND that's actually on disk
  // — a missing/corrupt projector blob shouldn't flag the model multimodal (and
  // block the fast path) or fail an LM Studio copy mid-way.
  let projectorPath = projectorDigest ? join(modelsDir, 'blobs', digestToBlobFilename(projectorDigest)) : null
  if (projectorPath && !(await fileExists(projectorPath))) projectorPath = null
  return { ggufPath, projectorPath, isMlx: false, isSharded: false }
}

/**
 * Pre-place the source GGUF as a hardlink at `blobs/sha256-<hash>` so the
 * subsequent `/api/create` reuses the existing (content-addressed) blob instead
 * of copying the multi-GB weights — zero extra disk, the file is shared with the
 * source backend's copy. Best-effort: a cross-filesystem hardlink (EXDEV) or any
 * error returns false and the caller's `/api/create` just copies as usual.
 * @returns {Promise<boolean>} whether the blob is now hardlinked
 */
async function prelinkBlob(ggufPath) {
  const hex = await sha256File(ggufPath)
  const blobPath = join(getModelsDir(), 'blobs', digestToBlobFilename(`sha256:${hex}`))
  if (await fileExists(blobPath)) return true // already present (content-addressed dedup)
  await ensureDir(dirname(blobPath))
  await link(ggufPath, blobPath)
  return true
}

/**
 * Register a local GGUF file as an Ollama model via `/api/create` (no download).
 * In `link` mode the blob is hardlinked into Ollama's store first so create
 * dedups against it (shared on disk); `copy` mode lets create copy the blob.
 * @param {{ name: string, ggufPath: string, mode?: 'link'|'copy' }} args
 * @returns {Promise<{ success: boolean, modelId?: string, linked?: boolean, error?: string }>}
 */
async function importModelFromGguf({ name, ggufPath, mode = 'copy' }) {
  if (!(await checkOllamaAvailable())) {
    return { success: false, error: 'Ollama not available' }
  }
  const linked = mode === 'link' ? await prelinkBlob(ggufPath).catch(() => false) : false
  console.log(`📦 Ollama import (${linked ? 'hardlink' : 'copy'}): ${name} ← ${ggufPath}`)
  // No timeout — create may copy the (multi-GB) blob into the store (skipped
  // when we pre-hardlinked a matching blob above).
  const response = await fetchWithTimeout(`${config.baseUrl}/api/create`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name, modelfile: buildModelfile(ggufPath), stream: true })
  }, 0).catch((err) => ({ _err: describeFetchError(err) }))

  if (response._err || !response.ok || !response.body) {
    const error = response._err || `create failed: ${response.status} ${response.statusText}`
    return { success: false, error }
  }
  const lastError = await streamNdjson(response)
  if (lastError) return { success: false, error: lastError }
  installedModels = null
  console.log(`✅ Ollama import complete: ${name}${linked ? ' (hardlinked blob — no extra disk)' : ''}`)
  return { success: true, modelId: name, linked }
}

/**
 * Live base URL — reflects runtime config patches, not just startup env.
 * Used by sibling services (e.g. the local code-review endpoint) so the
 * catalog UI and the code-review path can't desync.
 */
function getBaseUrl() {
  return config.baseUrl
}

/**
 * Aggregate status for the unified local-LLM UI.
 */
async function getStatus(forceRefresh = false) {
  const available = await checkOllamaAvailable(forceRefresh)
  const baseModels = available ? await getInstalledModels(true) : []
  // Enrich with native context length + capabilities (cached /api/show per
  // model) so the model cards + selector dropdowns can show each model's window
  // and so vision-capable models are detected from their reported capabilities.
  const models = available ? await enrichWithModelDetails(baseModels) : baseModels
  const service = await getServiceStatus().catch(() => ({ supported: false, manager: null, running: false, runAtStartup: false, status: null }))
  return {
    available,
    baseUrl: config.baseUrl,
    version: available ? await getVersion() : null,
    modelCount: models.length,
    models,
    service,
    // The window resident models were actually loaded at (null when nothing is
    // resident — Ollama has not committed to one yet), plus the window PortOS
    // handed this daemon. Surfaced so the Local LLM page can show why an agent
    // harness overflowed at 32K on a 256K-capable model.
    contextLength: {
      runtime: available ? await getRuntimeContextLength().catch(() => null) : null,
      applied: available ? daemon.contextLength : null,
      agentMinimum: OLLAMA_AGENT_MIN_CONTEXT
    },
    lastError: status.lastError,
    consecutiveErrors: status.consecutiveErrors
  }
}

export {
  getInstalledModels,
  getModelCapabilities,
  getLoadedModels,
  getLoadedModelsAt,
  getLastInstalledModelsError,
  getLastLoadedModelsError,
  unloadModel,
  warmModel,
  pullModel,
  importModelFromHfSafetensors,
  deleteModel,
  getStatus,
  getBaseUrl,
  resolveLocalModel,
  importModelFromGguf,
  startServer,
  stopServer,
  ensureContextWindow,
  restartWithEnv,
  getRuntimeContextLength,
  startPersistentService,
  stopPersistentService,
  ensureRunning,
  ensureProviderReady,
  isOllamaProvider,
  getServiceStatus,
  invalidateServiceStatus,
  getModelsDir,
  listStoredModels,
  getEmbeddings,
  isBootstrapConflictError,
  isPullDeadlineError,
  finalizeHuggingFacePull
}