offgrid-ai 0.1.2

package/src/config.mjs

@@ -0,0 +1,102 @@
+import { mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+
+// ── Base directories ──────────────────────────────────────────────────────
+
+export const DATA_DIR = process.env.OFFGRID_DIR || join(homedir(), ".offgrid-ai");
+export const PROFILE_DIR = join(DATA_DIR, "profiles");
+export const LOG_DIR = join(DATA_DIR, "logs");
+export const RUN_DIR = join(DATA_DIR, "run");
+
+// ── Default scan directories ──────────────────────────────────────────────
+
+export const DEFAULT_MODEL_DIRS = [
+  join(homedir(), ".lmstudio", "models"),
+  join(homedir(), ".cache", "huggingface", "hub"),
+];
+
+// ── External config paths ─────────────────────────────────────────────────
+
+export const PI_CONFIG = join(homedir(), ".pi", "agent", "models.json");
+
+// ── Ensure data directories exist ─────────────────────────────────────────
+
+export async function ensureDirs() {
+  await mkdir(PROFILE_DIR, { recursive: true });
+  await mkdir(LOG_DIR, { recursive: true });
+  await mkdir(RUN_DIR, { recursive: true });
+}
+
+// ── User config ───────────────────────────────────────────────────────────
+
+const CONFIG_PATH = join(DATA_DIR, "config.json");
+
+const DEFAULT_CONFIG = {
+  modelScanDirs: [],
+  benchmarkRepoPath: null,
+  binaryOverrides: {},
+};
+
+export async function loadConfig() {
+  try {
+    const raw = await readFile(CONFIG_PATH, "utf8");
+    return { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+export async function saveConfig(config) {
+  await mkdir(dirname(CONFIG_PATH), { recursive: true });
+  await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+// ── Model scan directories ────────────────────────────────────────────────
+
+export async function getModelScanDirs() {
+  const config = await loadConfig();
+  return [...DEFAULT_MODEL_DIRS, ...config.modelScanDirs];
+}
+
+// ── Binary discovery ──────────────────────────────────────────────────────
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export async function findLlamaServer() {
+  // 1. Env override
+  if (process.env.LLAMA_SERVER_BINARY && existsSync(process.env.LLAMA_SERVER_BINARY)) {
+    return process.env.LLAMA_SERVER_BINARY;
+  }
+
+  // 2. which/where
+  try {
+    const { stdout } = await execFileAsync("which", ["llama-server"]);
+    const path = stdout.trim();
+    if (path && existsSync(path)) return path;
+  } catch { /* not on PATH */ }
+
+  // 3. Homebrew
+  try {
+    const { stdout } = await execFileAsync("brew", ["--prefix", "llama.cpp"]);
+    const prefix = stdout.trim();
+    const candidate = join(prefix, "bin", "llama-server");
+    if (existsSync(candidate)) return candidate;
+  } catch { /* Homebrew not installed or llama.cpp not brewed */ }
+
+  return null;
+}
+
+export async function hasHomebrew() {
+  try {
+    await execFileAsync("which", ["brew"]);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/estimate.mjs

@@ -0,0 +1,113 @@
+import { existsSync, statSync } from "node:fs";
+import { readGgufMetadata } from "./gguf.mjs";
+import pc from "picocolors";
+
+export function estimateMemory(modelPath, mmprojPath, draftModelPath, flags) {
+  const modelBytes = statSync(modelPath).size;
+  const mmprojBytes = mmprojPath && existsSync(mmprojPath) ? statSync(mmprojPath).size : 0;
+  const draftBytes = draftModelPath && existsSync(draftModelPath) ? statSync(draftModelPath).size : 0;
+  const metadata = readGgufMetadata(modelPath);
+  const architecture = metadata["general.architecture"];
+  const prefix = typeof architecture === "string" ? architecture : null;
+  const layers = numberMeta(metadata, prefix && `${prefix}.block_count`);
+  const headKv = numberOrArrayMeta(metadata, prefix && `${prefix}.attention.head_count_kv`);
+  const keyLength = numberOrArrayMeta(metadata, prefix && `${prefix}.attention.key_length`);
+  const valueLength = numberOrArrayMeta(metadata, prefix && `${prefix}.attention.value_length`);
+  const slidingWindow = numberMeta(metadata, prefix && `${prefix}.attention.sliding_window`);
+  const slidingWindowPattern = booleanArrayMeta(metadata, prefix && `${prefix}.attention.sliding_window_pattern`);
+  const keyLengthSwa = numberMeta(metadata, prefix && `${prefix}.attention.key_length_swa`);
+  const valueLengthSwa = numberMeta(metadata, prefix && `${prefix}.attention.value_length_swa`);
+  const bytesK = bytesForCacheType(flags.cacheTypeK);
+  const bytesV = bytesForCacheType(flags.cacheTypeV);
+  const kv = estimateKvBytes({
+    ctxSize: flags.ctxSize,
+    parallel: flags.parallel ?? 1,
+    layers,
+    headKv,
+    keyLength,
+    valueLength,
+    slidingWindow,
+    slidingWindowPattern,
+    keyLengthSwa,
+    valueLengthSwa,
+    bytesK,
+    bytesV,
+  });
+  const overheadBytes = 1024 ** 3;
+  return {
+    modelBytes,
+    mmprojBytes,
+    draftBytes,
+    kvBytes: kv.bytes,
+    overheadBytes,
+    totalBytes: modelBytes + mmprojBytes + draftBytes + kv.bytes + overheadBytes,
+    note: kv.note,
+  };
+}
+
+function estimateKvBytes(input) {
+  const { ctxSize, parallel, layers, bytesK, bytesV } = input;
+  if (!layers || !ctxSize || !bytesK || !bytesV) {
+    return { bytes: 0, note: "KV estimate unavailable: missing GGUF architecture metadata.", mode: "unknown" };
+  }
+
+  const canLayer = input.headKv && input.keyLength && input.valueLength;
+  if (!canLayer) return { bytes: 0, note: "KV estimate unavailable: missing GGUF architecture metadata.", mode: "unknown" };
+
+  if (Array.isArray(input.headKv) || Array.isArray(input.keyLength) || Array.isArray(input.valueLength) || input.slidingWindowPattern?.length) {
+    let total = 0;
+    for (let i = 0; i < layers; i++) {
+      const headKv = valueForLayer(input.headKv, i);
+      let keyLength = valueForLayer(input.keyLength, i);
+      let valueLength = valueForLayer(input.valueLength, i);
+      let layerCtx = ctxSize;
+      if (input.slidingWindowPattern?.[i] && input.slidingWindow) {
+        layerCtx = Math.min(ctxSize, input.slidingWindow);
+        keyLength = input.keyLengthSwa ?? keyLength;
+        valueLength = input.valueLengthSwa ?? valueLength;
+      }
+      if (!headKv || !keyLength || !valueLength) {
+        return { bytes: 0, note: "KV estimate unavailable: incomplete layer-specific GGUF metadata.", mode: "unknown" };
+      }
+      total += layerCtx * parallel * headKv * ((keyLength * bytesK) + (valueLength * bytesV));
+    }
+    return { bytes: total, note: "", mode: input.slidingWindowPattern?.length ? "layered-swa" : "layered" };
+  }
+
+  return {
+    bytes: ctxSize * parallel * layers * input.headKv * ((input.keyLength * bytesK) + (input.valueLength * bytesV)),
+    note: "",
+    mode: "simple",
+  };
+}
+
+function valueForLayer(value, index) {
+  return Array.isArray(value) ? value[index] : value;
+}
+
+function numberMeta(meta, key) {
+  const value = key ? meta[key] : undefined;
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function numberOrArrayMeta(meta, key) {
+  const value = key ? meta[key] : undefined;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (Array.isArray(value) && value.every((item) => typeof item === "number" && Number.isFinite(item))) return value;
+  return undefined;
+}
+
+function booleanArrayMeta(meta, key) {
+  const value = key ? meta[key] : undefined;
+  return Array.isArray(value) && value.every((item) => typeof item === "boolean") ? value : undefined;
+}
+
+function bytesForCacheType(type) {
+  const normalized = String(type ?? "").toLowerCase();
+  if (normalized === "f32") return 4;
+  if (normalized === "f16" || normalized === "bf16") return 2;
+  if (normalized === "q8_0") return 1;
+  if (["q4_0", "q4_1", "iq4_nl"].includes(normalized)) return 0.5;
+  if (["q5_0", "q5_1"].includes(normalized)) return 0.625;
+  return undefined;
+}

package/src/gguf.mjs

@@ -0,0 +1,70 @@
+import { openSync, readSync, closeSync, statSync } from "node:fs";
+
+export function readGgufMetadata(path) {
+  const buffer = readFilePrefix(path, 64 * 1024 * 1024);
+  let offset = 0;
+  if (buffer.toString("utf8", 0, 4) !== "GGUF") return {};
+  offset += 4;
+  offset += 4; // version
+  offset += 8; // tensor count
+  const kvCount = Number(buffer.readBigUInt64LE(offset));
+  offset += 8;
+  const meta = {};
+  for (let i = 0; i < kvCount; i++) {
+    const keyLen = Number(buffer.readBigUInt64LE(offset));
+    offset += 8;
+    const key = buffer.toString("utf8", offset, offset + keyLen);
+    offset += keyLen;
+    const type = buffer.readUInt32LE(offset);
+    offset += 4;
+    const read = readValue(buffer, offset, type);
+    offset = read.offset;
+    meta[key] = read.value;
+  }
+  return meta;
+}
+
+function readFilePrefix(path, maxBytes) {
+  const fd = openSync(path, "r");
+  try {
+    const size = Math.min(statSync(path).size, maxBytes);
+    const buffer = Buffer.alloc(size);
+    readSync(fd, buffer, 0, size, 0);
+    return buffer;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function readValue(buffer, offset, type) {
+  if (type === 0) return { value: buffer.readUInt8(offset), offset: offset + 1 };
+  if (type === 1) return { value: buffer.readInt8(offset), offset: offset + 1 };
+  if (type === 2) return { value: buffer.readUInt16LE(offset), offset: offset + 2 };
+  if (type === 3) return { value: buffer.readInt16LE(offset), offset: offset + 2 };
+  if (type === 4) return { value: buffer.readUInt32LE(offset), offset: offset + 4 };
+  if (type === 5) return { value: buffer.readInt32LE(offset), offset: offset + 4 };
+  if (type === 6) return { value: buffer.readFloatLE(offset), offset: offset + 4 };
+  if (type === 7) return { value: Boolean(buffer.readUInt8(offset)), offset: offset + 1 };
+  if (type === 8) {
+    const len = Number(buffer.readBigUInt64LE(offset));
+    offset += 8;
+    return { value: buffer.toString("utf8", offset, offset + len), offset: offset + len };
+  }
+  if (type === 9) {
+    const itemType = buffer.readUInt32LE(offset);
+    offset += 4;
+    const len = Number(buffer.readBigUInt64LE(offset));
+    offset += 8;
+    const values = [];
+    for (let i = 0; i < len; i++) {
+      const item = readValue(buffer, offset, itemType);
+      offset = item.offset;
+      if (i < 32) values.push(item.value);
+    }
+    return { value: values, offset };
+  }
+  if (type === 10) return { value: Number(buffer.readBigUInt64LE(offset)), offset: offset + 8 };
+  if (type === 11) return { value: Number(buffer.readBigInt64LE(offset)), offset: offset + 8 };
+  if (type === 12) return { value: buffer.readDoubleLE(offset), offset: offset + 8 };
+  throw new Error(`Unsupported GGUF metadata value type ${type}`);
+}

package/src/harness-pi.mjs

@@ -0,0 +1,140 @@
+import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { PI_CONFIG } from "./config.mjs";
+import { loadProfiles } from "./profiles.mjs";
+import { readJson, writeJson } from "./json.mjs";
+import pc from "picocolors";
+
+// ── Sync Pi config ─────────────────────────────────────────────────────────
+
+export async function syncPiConfig(profile) {
+  const profiles = await activeProviderProfiles(profile);
+  const config = await readJson(PI_CONFIG, { providers: {} });
+  config.providers ??= {};
+  config.providers[profile.providerId] = {
+    baseUrl: profile.baseUrl,
+    api: "openai-completions",
+    apiKey: piApiKey(profile.providerId),
+    compat: providerCompat(profile.providerId),
+    models: profiles.map(piModelConfig),
+  };
+  await writeJson(PI_CONFIG, config);
+  console.log(pc.green(`Synced Pi config: ${PI_CONFIG} (${profiles.length} model${profiles.length === 1 ? "" : "s"})`));
+}
+
+// ── Remove from Pi config ──────────────────────────────────────────────────
+
+export async function removeFromPiConfig(profile) {
+  const config = await readJson(PI_CONFIG, { providers: {} });
+  config.providers ??= {};
+  const provider = config.providers[profile.providerId];
+  if (!provider?.models) return { cleaned: false, reason: `no ${profile.providerId} provider in Pi config` };
+  const before = provider.models.length;
+  provider.models = provider.models.filter((m) => m.id !== profile.modelAlias);
+  if (provider.models.length === 0) delete config.providers[profile.providerId];
+  if (before > provider.models.length) {
+    await writeJson(PI_CONFIG, config);
+    return { cleaned: true, removed: before - provider.models.length };
+  }
+  return { cleaned: false, reason: `${profile.modelAlias} not in Pi config` };
+}
+
+// ── Check if Pi has the model ──────────────────────────────────────────────
+
+export async function hasPiModel(profile) {
+  const config = await readJson(PI_CONFIG, null);
+  return Boolean(config?.providers?.[profile.providerId]?.models?.some?.((m) => m.id === profile.modelAlias));
+}
+
+// ── Launch Pi ──────────────────────────────────────────────────────────────
+
+export async function launchPi(profile) {
+  const model = profile.harnesses?.pi?.model ?? `${profile.providerId}/${profile.modelAlias}`;
+  console.log(pc.bold(`[pi] pi --model ${model}`));
+  await runForeground("pi", ["--model", model]);
+}
+
+// ── Check if Pi is installed ───────────────────────────────────────────────
+
+export async function hasPi() {
+  try {
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    await promisify(execFile)("which", ["pi"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Internals ──────────────────────────────────────────────────────────────
+
+async function activeProviderProfiles(currentProfile) {
+  const allProfiles = await loadProfiles().catch(() => []);
+  const byAlias = new Map();
+  for (const item of [...allProfiles, currentProfile]) {
+    if (item.providerId !== currentProfile.providerId) continue;
+    if (item.backend !== "llama-cpp" && item.backend !== "llama-cpp-mtp") {
+      byAlias.set(item.modelAlias, item);
+      continue;
+    }
+    if (!item.modelPath || !existsSync(item.modelPath)) continue;
+    byAlias.set(item.modelAlias, item);
+  }
+  return Array.from(byAlias.values()).sort((a, b) => a.modelAlias.localeCompare(b.modelAlias));
+}
+
+function piModelConfig(profile) {
+  const compat = modelCompat(profile);
+  const reasoning = modelReasoning(profile);
+  return {
+    id: profile.modelAlias,
+    name: profile.label,
+    input: modelInput(profile),
+    ...(reasoning === undefined ? {} : { reasoning }),
+    ...(compat ? { compat } : {}),
+    ...(profile.flags?.ctxSize ? { contextWindow: profile.flags.ctxSize } : {}),
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  };
+}
+
+function modelInput(profile) {
+  return profile.mmprojPath && existsSync(profile.mmprojPath) ? ["text", "image"] : ["text"];
+}
+
+function modelCompat(profile) {
+  if (profile.compat) return profile.compat;
+  const family = modelFamily(profile);
+  if (family.includes("qwen") || family.includes("gemma-4") || family.includes("gemma 4")) {
+    return { thinkingFormat: "qwen-chat-template" };
+  }
+  return null;
+}
+
+function modelReasoning(profile) {
+  if (profile.reasoning !== undefined) return Boolean(profile.reasoning);
+  const family = modelFamily(profile);
+  if (family.includes("qwen") || family.includes("gemma-4") || family.includes("gemma 4")) return true;
+  return undefined;
+}
+
+function modelFamily(profile) {
+  return [profile.id, profile.label, profile.modelAlias, profile.modelPath, profile.ollamaModel, profile.omlxModel].filter(Boolean).join(" ").toLowerCase();
+}
+
+function piApiKey(providerId) {
+  return providerId === "ollama" ? "ollama" : "none";
+}
+
+function providerCompat(providerId) {
+  if (providerId === "ollama") return { supportsDeveloperRole: true, supportsReasoningEffort: false };
+  return { supportsDeveloperRole: false, supportsReasoningEffort: false };
+}
+
+function runForeground(cmd, argv) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, argv, { stdio: "inherit" });
+    child.on("error", reject);
+    child.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`${cmd} exited with code ${code}`)));
+  });
+}

package/src/json.mjs

@@ -0,0 +1,16 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export async function readJson(path, fallback) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return fallback;
+    throw error;
+  }
+}
+
+export async function writeJson(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(value, null, 2) + "\n", "utf8");
+}

package/src/logs.mjs

@@ -0,0 +1,42 @@
+import { existsSync, statSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import pc from "picocolors";
+
+export function tailFriendly(rawLogPath, friendlyLogPath) {
+  let offset = existsSync(rawLogPath) ? statSync(rawLogPath).size : 0;
+  let stopped = false;
+  const seen = new Set();
+  const timer = setInterval(async () => {
+    try {
+      if (stopped || !existsSync(rawLogPath)) return;
+      const size = statSync(rawLogPath).size;
+      if (size <= offset) return;
+      const stream = createReadStream(rawLogPath, { start: offset, end: size - 1, encoding: "utf8" });
+      offset = size;
+      let text = "";
+      for await (const chunk of stream) text += chunk;
+      for (const line of text.split(/\r?\n/).filter(Boolean)) {
+        const friendly = friendlyLine(line);
+        if (!friendly || seen.has(friendly)) continue;
+        seen.add(friendly);
+        console.log(friendly);
+        await appendFile(friendlyLogPath, pc.strip(friendly) + "\n", "utf8");
+      }
+    } catch { /* friendly logging must never crash */ }
+  }, 300);
+  return { stop() { stopped = true; clearInterval(timer); } };
+}
+
+function friendlyLine(line) {
+  const lower = line.toLowerCase();
+  const trimmed = line.trim();
+  if (lower.includes("error") || lower.includes("failed")) return pc.red(`[error] ${trimmed}`);
+  if (lower.includes("listening") || lower.includes("http server")) return pc.green(`[server] ${trimmed}`);
+  if (lower.includes("llm_load") || lower.includes("load_model") || lower.includes("loading model")) return pc.cyan(`[load] ${trimmed}`);
+  if (lower.includes("mmproj")) return pc.cyan(`[vision] ${trimmed}`);
+  if (lower.includes("prompt eval") || lower.includes("prompt eval time")) return pc.green(`[timing] ${trimmed}`);
+  if (lower.includes("eval time") || lower.includes("generation")) return pc.green(`[timing] ${trimmed}`);
+  if (lower.includes("slot") && lower.includes("launch_slot")) return pc.cyan(`[request] ${trimmed}`);
+  return null;
+}

package/src/process.mjs

@@ -0,0 +1,175 @@
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, openSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { LOG_DIR } from "./config.mjs";
+import { writeState, readState } from "./profiles.mjs";
+import { backendFor, backendBinaryFor } from "./backends.mjs";
+
+const execFileAsync = promisify(execFile);
+
+// ── Start server ───────────────────────────────────────────────────────────
+
+export async function startServer(profile) {
+  const backend = backendFor(profile.backend);
+  if (backend.type === "managed-server") {
+    return startManagedServer(profile, backend);
+  }
+  return startLocalServer(profile);
+}
+
+async function startLocalServer(profile) {
+  const binary = await backendBinaryFor(profile.backend);
+  if (!binary) {
+    throw new Error("llama-server not found. Install it via Homebrew: brew install llama.cpp");
+  }
+
+  const timestamp = timestampForFile();
+  const rawLogPath = join(LOG_DIR, `${profile.id}-${timestamp}.raw.log`);
+  const friendlyLogPath = join(LOG_DIR, `${profile.id}-${timestamp}.friendly.log`);
+  const commandJson = profile.commandArgv ?? [];
+
+  await writeFile(rawLogPath, `[offgrid-ai] ${new Date().toISOString()}\n[binary] ${binary}\n[argv]\n${commandJson.join(" ")}\n`, "utf8");
+  await writeFile(friendlyLogPath, `[launch] starting llama-server for ${profile.label}\n`, "utf8");
+
+  // Build argv: binary + command.json args
+  const argv = [...commandJson];
+
+  const rawFd = openSync(rawLogPath, "a");
+  const child = spawn(binary, argv, { detached: true, stdio: ["ignore", rawFd, rawFd] });
+  child.unref();
+
+  const state = {
+    pid: child.pid,
+    profileId: profile.id,
+    baseUrl: profile.baseUrl,
+    binary,
+    rawLogPath,
+    friendlyLogPath,
+    startedAt: new Date().toISOString(),
+  };
+  await writeState(profile.id, state);
+  return state;
+}
+
+async function startManagedServer(profile, backend) {
+  const ready = await serverReady(profile.baseUrl);
+  if (ready) {
+    // Already running
+  } else {
+    for (let i = 0; i < 60; i++) {
+      await sleep(2000);
+      if (await serverReady(profile.baseUrl)) break;
+      process.stdout.write(".");
+    }
+    if (!(await serverReady(profile.baseUrl))) {
+      throw new Error(`${backend.label} is not responding at ${profile.baseUrl}. Start it and try again.`);
+    }
+  }
+  const state = {
+    pid: null,
+    profileId: profile.id,
+    baseUrl: profile.baseUrl,
+    managedBy: backend.id,
+    startedAt: new Date().toISOString(),
+  };
+  await writeState(profile.id, state);
+  return state;
+}
+
+// ── Stop server ────────────────────────────────────────────────────────────
+
+export async function stopProfile(profile) {
+  const backend = backendFor(profile.backend);
+  if (backend.type === "managed-server") {
+    return { stopped: false, message: `${backend.label} is a managed service — offgrid-ai does not stop it.` };
+  }
+  const state = await readState(profile.id);
+  if (!state?.pid) return { stopped: false, message: `No tracked pid for ${profile.id}.` };
+  if (!pidAlive(state.pid)) {
+    await writeState(profile.id, { ...state, pid: null, stoppedAt: new Date().toISOString(), stopReason: "pid-not-running" });
+    return { stopped: false, message: `${profile.id} pid ${state.pid} is no longer running.` };
+  }
+  try {
+    try {
+      process.kill(-state.pid, "SIGTERM");
+    } catch {
+      process.kill(state.pid, "SIGTERM");
+    }
+    await writeState(profile.id, { ...state, pid: null, stoppedAt: new Date().toISOString(), stopSignal: "SIGTERM" });
+    return { stopped: true, message: `Stopped ${profile.id} pid ${state.pid}` };
+  } catch (error) {
+    return { stopped: false, message: `Could not stop pid ${state.pid}: ${error.message}` };
+  }
+}
+
+// ── Status checks ──────────────────────────────────────────────────────────
+
+export async function isProfileRunning(profile) {
+  const backend = backendFor(profile.backend);
+  if (backend.type === "managed-server") return await serverReady(profile.baseUrl);
+  const state = await readState(profile.id);
+  return Boolean(state?.pid && pidAlive(state.pid));
+}
+
+export async function profileRuntimeStatus(profile) {
+  const backend = backendFor(profile.backend);
+  if (backend.type === "managed-server") {
+    const ready = await serverReady(profile.baseUrl);
+    return { state: null, pid: null, running: ready, ready, rssBytes: null, startedAt: null };
+  }
+  const state = await readState(profile.id);
+  const running = Boolean(state?.pid && pidAlive(state.pid));
+  const [ready, rssBytes] = await Promise.all([
+    serverReady(profile.baseUrl),
+    running ? pidRssBytes(state.pid) : Promise.resolve(null),
+  ]);
+  return { state, pid: state?.pid ?? null, running, ready, rssBytes, startedAt: state?.startedAt ? new Date(state.startedAt) : null };
+}
+
+export async function serverReady(baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/$/, "")}/models`, { signal: AbortSignal.timeout(1000) });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function waitForReady(profile, pid, rawLogPath) {
+  const backend = backendFor(profile.backend);
+  if (backend.type === "managed-server") return;
+  for (let i = 0; i < 180; i++) {
+    if (await serverReady(profile.baseUrl)) return;
+    if (pid && !pidAlive(pid)) {
+      const tail = await readFile(rawLogPath, "utf8").catch(() => "");
+      throw new Error(`llama-server exited early. Last log lines:\n${tail.split(/\r?\n/).slice(-20).join("\n")}`);
+    }
+    await sleep(1000);
+  }
+  throw new Error(`Timed out waiting for ${profile.baseUrl}/models`);
+}
+
+// ── Internals ──────────────────────────────────────────────────────────────
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch { return false; }
+}
+
+async function pidRssBytes(pid) {
+  try {
+    const { stdout } = await execFileAsync("ps", ["-o", "rss=", "-p", String(pid)]);
+    const rssKb = Number(stdout.trim().split(/\s+/)[0]);
+    return Number.isFinite(rssKb) ? rssKb * 1024 : null;
+  } catch { return null; }
+}
+
+function timestampForFile() {
+  return new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}