pi-lemonade-link 1.0.0

package/index.ts

@@ -0,0 +1,3245 @@
+/**
+ * pi-lemonade-link — unified pi extension for a self-hosted Lemonade server
+ *
+ * One extension, four capabilities:
+ *
+ *   1. Dynamic chat-model discovery — queries the server's model catalog and
+ *      health endpoints at every pi startup, registers one
+ *      lemonade-<instance-name> provider per configured instance
+ *      with capability metadata (reasoning / vision / context window) and
+ *      live loaded-state annotations. Chat-capable models only, by default.
+ *   2. Multimodal agent tools — transcribe_audio, generate_image, edit_image,
+ *      vary_image, upscale_image, text_to_speech, generate_audio, and
+ *      generate_3d_model, all backed by lemonade's OpenAI-compatible and
+ *      Lemonade-specific endpoints. Unloaded models auto-load on demand;
+ *      container audio formats are converted to wav via ffmpeg first.
+ *   3. /lemonade-setup — a navigable TUI menu for live status, endpoint
+ *      configuration, server discovery, model management (load, unload,
+ *      pull with live progress + cancel, delete with typed-phrase
+ *      confirmation, change-ctx, Hugging Face search & install, filter,
+ *      refresh).
+ *   4. A lemonade status bar — while a lemonade model is active, an extra
+ *      below-editor row appears (never touching the footer): instance name,
+ *      tok/s and prefix-cache hit % derived locally from the session's own
+ *      messages, plus polled busy/queue, CPU/GPU/NPU and VRAM from the active
+ *      instance.
+ *      Switching to a non-lemonade model removes the row.
+ *   5. Pulls use lemonade's server-owned download jobs (stream + subscribe:
+ *      false + GET /v1/downloads) with a live progress view, Esc to cancel —
+ *      no blocking 30-minute waits. Blocking pull is kept as a fallback.
+ *
+ * Nothing is hardcoded: every endpoint lives in ~/.pi/agent/lemonade.json,
+ * editable at runtime via /lemonade-setup (changes re-register the provider
+ * immediately; no restart or /reload needed). On first run a missing config
+ * is auto-created as a minimal blank (zero servers) — an info notice points
+ * at /lemonade-setup, which opens a first-run wizard (discover or manual
+ * entry) instead of blocking. A config that exists but is unparseable or
+ * invalid still fails loudly and registers nothing. JSONC-style comments
+ * are allowed in the config file; note that /lemonade-setup rewrites strip
+ * them.
+ *
+ * Endpoints confirmed against lemonade 11.7.0 (see README for full list).
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import dgram from "node:dgram";
+import { spawn } from "node:child_process";
+import { Type } from "typebox";
+import { DynamicBorder, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Container, Key, matchesKey, SelectList, Text, truncateToWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// ─── Configuration ──────────────────────────────────────────────────────────
+
+interface LemonadeConfig {
+  /** Resolved per-instance on views produced by listInstances()/instanceView()
+   *  (from servers[].baseUrl). Empty on the raw config — the only instance
+   *  store is servers[], and servers[0] is the default instance. */
+  baseUrl: string;
+  apiKey: string; // shared fallback; a server entry without apiKey inherits it
+  chatPath: string; // OpenAI-compat chat completions base
+  modelsPath: string;
+  healthPath: string;
+  loadPath: string;
+  unloadPath: string;
+  pullPath: string;
+  deletePath: string;
+  downloadsPath: string;
+  downloadsControlPath: string;
+  registrySearchPath: string;
+  pullVariantsPath: string;
+  transcriptionPath: string;
+  imageGenerationPath: string;
+  imageEditPath: string;
+  imageVariationPath: string;
+  imageUpscalePath: string;
+  speechPath: string;
+  audioGenerationPath: string;
+  mesh3dPath: string;
+  classifyPath: string;
+  beaconPort: number;
+  chatOnly: boolean;
+  defaultTranscriptionModel: string;
+  defaultImageModel: string; // "" = auto-pick first image-labeled catalog model
+  defaultUpscaleModel: string;
+  defaultClassifierModel: string; // "" = auto-pick first classification model
+  outputDir: string; // "" = process cwd
+  statusPollMs: number; // status-panel live-refresh interval while viewing
+  statusBar: boolean; // belowEditor bar shown while a lemonade model is active
+  barPollMs: number; // bar server-poll cadence; 0 = local metrics only (tok/s, cache, instance)
+  discoveryTimeoutMs: number;
+  beaconTimeoutMs: number;
+  loadTimeoutMs: number;
+  pullTimeoutMs: number; // blocking-pull fallback cap only
+  transcriptionTimeoutMs: number;
+  generationTimeoutMs: number; // images, speech, audio gen, 3D
+  /** ALL lemonade instances — the only instance store. REQUIRED (at least
+   *  one entry); the FIRST entry is the default instance (the one tools
+   *  target when the `server` argument is omitted). There is no separate
+   *  default: servers[0] IS the default, and reordering the array changes
+   *  which instance that is. */
+  servers: ServerEntry[];
+}
+
+export interface ServerEntry {
+  name: string; // lowercase alnum + hyphens; "default" and duplicate names are reserved
+  baseUrl: string;
+  apiKey?: string; // falls back to the top-level (shared) apiKey when omitted
+  description?: string; // free-form context for the user's own reminder's sake
+}
+
+const CONFIG_PATH = path.join(getAgentDir(), "lemonade.json");
+
+const DEFAULT_CONFIG: LemonadeConfig = {
+  baseUrl: "", // views resolve this from servers[]; empty on the raw config
+  apiKey: "lemonade",
+  chatPath: "/api/v1",
+  modelsPath: "/v1/models",
+  healthPath: "/v1/health",
+  loadPath: "/v1/load",
+  unloadPath: "/v1/unload",
+  pullPath: "/v1/pull",
+  deletePath: "/v1/delete",
+  downloadsPath: "/v1/downloads",
+  downloadsControlPath: "/v1/downloads/control",
+  registrySearchPath: "/v1/registry/search",
+  pullVariantsPath: "/v1/pull/variants",
+  transcriptionPath: "/v1/audio/transcriptions",
+  imageGenerationPath: "/v1/images/generations",
+  imageEditPath: "/v1/images/edits",
+  imageVariationPath: "/v1/images/variations",
+  imageUpscalePath: "/v1/images/upscale",
+  speechPath: "/v1/audio/speech",
+  audioGenerationPath: "/v1/audio/generations",
+  mesh3dPath: "/v1/3d/generations",
+  classifyPath: "/v1/classify",
+  beaconPort: 13305,
+  chatOnly: true,
+  defaultTranscriptionModel: "Whisper-Large-v3",
+  defaultImageModel: "",
+  defaultUpscaleModel: "RealESRGAN-x4plus",
+  defaultClassifierModel: "",
+  outputDir: "",
+  statusPollMs: 2000,
+  statusBar: true,
+  barPollMs: 5000,
+  discoveryTimeoutMs: 5000,
+  beaconTimeoutMs: 3000,
+  loadTimeoutMs: 300_000,
+  pullTimeoutMs: 30 * 60 * 1000,
+  transcriptionTimeoutMs: 300_000,
+  generationTimeoutMs: 600_000,
+  servers: [],
+};
+
+/** Strip JSONC comments — // line comments and block comments — so the
+ *  config file can be annotated by hand. String-aware: // inside quoted
+ *  values (URLs like http://...) is preserved. */
+function stripJsonComments(text: string): string {
+  let out = "";
+  let inString = false;
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (inString) {
+      out += c;
+      if (c === "\\" && i + 1 < text.length) {
+        out += text[i + 1];
+        i += 2;
+        continue;
+      }
+      if (c === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && text[i + 1] === "*") {
+      i += 2;
+      while (i + 1 < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+/** Load the required config file. Missing or unparseable config is a hard
+ *  failure — never a silent fallback to defaults, which would point at a
+ *  server that may not be yours. The loud failure lives in piLemonadeLink()
+ *  at the bottom of this file; this function just throws with a reason. */
+/** Create a minimal, commented starter config if none exists yet.
+ *  Returns true when the file was created (first run). A blank config has
+ *  zero servers, which is legal: the extension registers nothing, and
+ *  /lemonade-setup opens a first-run wizard to discover or add a box. */
+function ensureConfigFile(p: string = CONFIG_PATH): boolean {
+  if (fs.existsSync(p)) return false;
+  const starter = `{
+  // Your lemonade server instances — this file was created automatically on
+  // first run. Nothing is registered until you add one. Easiest path:
+  // run /lemonade-setup (it offers discovery and guided entry), or edit this
+  // file and restart pi (or /reload).
+  // Each entry: { "name": "my-box", "baseUrl": "http://host:13305" }
+  // The FIRST entry is the default instance tools target when their 'server'
+  // argument is omitted. Every other setting has a built-in default — see
+  // lemonade.example.json beside the extension for the fully-commented
+  // reference.
+  "servers": []
+}
+`;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, starter);
+  return true;
+}
+
+function loadConfig(p: string = CONFIG_PATH): LemonadeConfig {
+  if (!fs.existsSync(p)) {
+    throw new Error(
+      `${p} does not exist. Copy the fully-commented example from the extension folder ` +
+        `(lemonade.example.json) to your pi agent dir, edit "baseUrl" for your server, and restart pi.`
+    );
+  }
+  const raw = JSON.parse(stripJsonComments(fs.readFileSync(p, "utf8")));
+  if (typeof raw !== "object" || !raw || Array.isArray(raw)) {
+    throw new Error(`${p} must contain a JSON object.`);
+  }
+  // servers[] is the ONLY instance store — validate it hard, loudly, up front.
+  // It MAY be empty (a fresh install bootstraps with zero instances; the
+  // first /lemonade-setup run offers a wizard to add one).
+  if (!Array.isArray(raw.servers)) {
+    throw new Error(
+      `${p} must define a "servers" array (it may be empty on a fresh install). Minimal example: ` +
+        `{ "servers": [{ "name": "main", "baseUrl": "http://your-lemonade-server:13305" }] }`
+    );
+  }
+  const seen = new Set<string>();
+  for (const [i, s] of (raw.servers as Array<Record<string, unknown>>).entries()) {
+    if (!s || typeof s !== "object") throw new Error(`${p}: servers[${i}] must be an object.`);
+    if (typeof s.name !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(s.name) || s.name === "default") {
+      throw new Error(
+        `${p}: servers[${i}].name must be lowercase letters/numbers/hyphens ("default" is reserved).`
+      );
+    }
+    if (seen.has(s.name)) throw new Error(`${p}: duplicate instance name "${s.name}".`);
+    seen.add(s.name);
+    if (typeof s.baseUrl !== "string" || !/^https?:\/\//.test(s.baseUrl)) {
+      throw new Error(`${p}: servers[${i}].baseUrl must be an http(s) URL.`);
+    }
+  }
+  return { ...DEFAULT_CONFIG, ...raw };
+}
+
+function saveConfig(config: LemonadeConfig): void {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
+}
+
+// ─── Multi-instance support ─────────────────────────────────────────────────
+
+/** A resolved instance: its name plus a config *view* — same shared settings,
+ *  but baseUrl/apiKey swapped for that instance. Because every existing helper
+ *  (fetchCatalog, tools, TUI actions, discovery) takes a LemonadeConfig, an
+ *  instance view flows through all of them unchanged. This is the one place
+ *  instance semantics are defined; everything else inherits it. servers[0]
+ *  is the default instance — position, not a flag, decides defaultness. */
+export interface InstanceView {
+  name: string;
+  description: string;
+  isDefault: boolean;
+  config: LemonadeConfig;
+}
+
+function listInstances(config: LemonadeConfig): InstanceView[] {
+  return config.servers.map((s, i) => ({
+    name: s.name,
+    description: s.description ?? "",
+    isDefault: i === 0,
+    config: { ...config, baseUrl: s.baseUrl, apiKey: s.apiKey || config.apiKey },
+  }));
+}
+
+/** Resolve a config view for the named instance. Returns the default view
+ *  (servers[0]) when name is omitted; returns an error string for unknown
+ *  names, so callers surface actionable text instead of dialing a wrong box. */
+function instanceView(config: LemonadeConfig, name?: string): LemonadeConfig | string {
+  // "default" stays a reserved alias for servers[0], so old muscle memory
+  // and scripts keep working.
+  const target = !name || name === "default" ? config.servers[0] : config.servers.find((s) => s.name === name);
+  if (!target) {
+    return `Unknown lemonade instance "${name}". Available instances: ${config.servers.map((s) => s.name).join(", ")}.`;
+  }
+  return { ...config, baseUrl: target.baseUrl, apiKey: target.apiKey || config.apiKey };
+}
+
+/** pi provider id for an instance — uniformly `lemonade-<name>` for EVERY
+ *  instance, without prejudice. Model addresses follow: lemonade-main/
+ *  <model>. Renaming an instance changes its id (and re-registers it); old
+ *  references (pinned sessions, --model scripts) must follow the rename. */
+function instanceProviderId(view: InstanceView): string {
+  return `lemonade-${view.name}`;
+}
+
+// ─── Lemonade API types & helpers ───────────────────────────────────────────
+
+interface LemonadeModel {
+  id: string;
+  labels?: string[];
+  recipe?: string;
+  size?: number;
+  downloaded?: boolean;
+  max_context_window?: number;
+}
+
+interface LoadedModelInfo {
+  model_name: string;
+  type: string;
+  status: string;
+  device?: string;
+  pinned?: boolean;
+  max_context_window?: number;
+  checkpoint?: string;
+  recipe?: string;
+  is_busy?: boolean;
+  is_streaming?: boolean;
+  backend_health?: string;
+  backend_alive?: boolean;
+  pid?: number;
+  last_use?: number;
+  slot_pool?: string;
+  residency_class?: string;
+  watchdog_reset?: boolean;
+}
+
+interface LemonadeHealth {
+  status?: string;
+  version?: string;
+  model_loaded?: string | null;
+  all_models_loaded?: LoadedModelInfo[];
+  websocket_port?: number;
+  max_models?: Record<string, number>;
+  pinned_models?: Record<string, number>;
+  pinned_helper_models?: Record<string, number>;
+  telemetry?: { enabled?: boolean; captures?: string[] };
+}
+
+interface SystemStats {
+  cpu_percent?: number | null;
+  memory_gb?: number | null;
+  gpu_percent?: number | null;
+  vram_gb?: number | null;
+  npu_percent?: number | null;
+}
+
+interface PerfStats {
+  time_to_first_token?: number;
+  tokens_per_second?: number;
+  input_tokens?: number;
+  output_tokens?: number;
+  prompt_tokens?: number | null;
+  cache_tokens?: number | null;
+  request_count_total?: number;
+  input_tokens_total?: number;
+  output_tokens_total?: number;
+  prompt_tokens_total?: number;
+  cache_tokens_total?: number;
+  routing_decisions_total?: number;
+  routing_switches_total?: number;
+}
+
+/** GPU device entry — shared shape (amd_gpu carries virtual_mem_gb, nvidia_gpu carries vram_gb). */
+interface GpuInfo {
+  name?: string;
+  family?: string;
+  integrated?: boolean;
+  virtual_mem_gb?: number;
+  vram_gb?: number;
+  available?: boolean;
+}
+
+/** Hardware inventory from GET /v1/system-info (fields are platform-dependent). */
+interface SystemInfo {
+  "OS Version"?: string;
+  Processor?: string;
+  "Physical Memory"?: string;
+  "Windows Power Setting"?: string;
+  model_storage?: { path?: string; used_bytes?: number; total_bytes?: number; free_bytes?: number };
+  devices?: {
+    cpu?: { name?: string; cores?: number; threads?: number; available?: boolean };
+    amd_gpu?: GpuInfo[];
+    nvidia_gpu?: GpuInfo[];
+    amd_npu?: { name?: string; family?: string; power_mode?: string; tops_max_int?: number; utilization?: number; available?: boolean };
+  };
+}
+
+interface DiscoveredServer {
+  hostname: string;
+  baseUrl: string;
+}
+
+/** Server-owned download job snapshot (GET /v1/downloads). */
+interface DownloadJob {
+  id: string;
+  model_name?: string;
+  status: string; // downloading | paused | cancelled | completed | error
+  running?: boolean;
+  file?: string;
+  file_index?: number;
+  total_files?: number;
+  bytes_downloaded?: number;
+  bytes_total?: number;
+  percent?: number;
+  cumulative_bytes_downloaded?: number;
+  total_download_size?: number;
+  complete?: boolean;
+  error?: string;
+}
+
+interface RegistryResult {
+  repository_id: string;
+  display_name?: string;
+  description?: string;
+  downloads?: number;
+  likes?: number;
+  tags?: string[];
+}
+
+interface PullVariants {
+  checkpoint: string;
+  recipe?: string;
+  suggested_name?: string;
+  suggested_labels?: string[];
+  mmproj_files?: string[];
+  variants: Array<{ name: string; primary_file: string; files: string[]; sharded: boolean; size_bytes: number }>;
+}
+
+function url(config: LemonadeConfig, p: string): string {
+  return `${config.baseUrl.replace(/\/+$/, "")}${p}`;
+}
+
+function authHeaders(config: LemonadeConfig): Record<string, string> {
+  return config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {};
+}
+
+async function postJson(fullUrl: string, config: LemonadeConfig, body: unknown, timeoutMs: number): Promise<Response> {
+  const res = await fetch(fullUrl, {
+    method: "POST",
+    headers: { ...authHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`);
+  }
+  return res;
+}
+
+async function fetchCatalog(config: LemonadeConfig, showAll = false): Promise<LemonadeModel[]> {
+  const res = await fetch(url(config, `${config.modelsPath}${showAll ? "?show_all=true" : ""}`), {
+    headers: authHeaders(config),
+    signal: AbortSignal.timeout(config.discoveryTimeoutMs),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  const payload = (await res.json()) as { data?: LemonadeModel[] };
+  return payload.data ?? [];
+}
+
+async function fetchJsonOrNull<T>(config: LemonadeConfig, p: string): Promise<T | null> {
+  try {
+    const res = await fetch(url(config, p), {
+      headers: authHeaders(config),
+      signal: AbortSignal.timeout(config.discoveryTimeoutMs),
+    });
+    return res.ok ? ((await res.json()) as T) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Fetch a plain-text endpoint (e.g. Prometheus /metrics); null when unreachable. */
+async function fetchTextOrNull(config: LemonadeConfig, p: string): Promise<string | null> {
+  try {
+    const res = await fetch(url(config, p), {
+      headers: authHeaders(config),
+      signal: AbortSignal.timeout(config.discoveryTimeoutMs),
+    });
+    return res.ok ? await res.text() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Parse Prometheus text exposition into a name → value map (last sample wins). */
+function parsePrometheus(body: string): Map<string, number> {
+  const values = new Map<string, number>();
+  for (const raw of body.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = line.match(/^([a-zA-Z_:][a-zA-Z0-9_:]*)(?:\{[^}]*\})?\s+(-?[\d.]+(?:[eE][+-]?\d+)?)/);
+    if (m) values.set(m[1], parseFloat(m[2]));
+  }
+  return values;
+}
+
+async function fetchHealth(config: LemonadeConfig): Promise<LemonadeHealth | null> {
+  return fetchJsonOrNull<LemonadeHealth>(config, config.healthPath);
+}
+
+async function loadModel(config: LemonadeConfig, id: string, ctxSize?: number): Promise<string> {
+  const body: Record<string, unknown> = { model_name: id };
+  if (ctxSize) {
+    body.ctx_size = ctxSize;
+    body.save_options = true;
+  }
+  await postJson(url(config, config.loadPath), config, body, config.loadTimeoutMs);
+  return ctxSize ? `Loaded ${id} with ctx_size ${ctxSize}.` : `Loaded ${id}.`;
+}
+
+async function unloadModel(config: LemonadeConfig, id: string): Promise<void> {
+  await postJson(url(config, config.unloadPath), config, { model_name: id }, config.discoveryTimeoutMs);
+}
+
+/** Start a server-owned download job; returns the initial snapshot. */
+async function startPullJob(config: LemonadeConfig, id: string, extra?: Record<string, unknown>): Promise<DownloadJob> {
+  const res = await postJson(url(config, config.pullPath), config, {
+    model_name: id,
+    stream: true,
+    subscribe: false,
+    ...(extra ?? {}),
+  }, config.discoveryTimeoutMs);
+  return (await res.json()) as DownloadJob;
+}
+
+async function listDownloads(config: LemonadeConfig): Promise<DownloadJob[] | null> {
+  return fetchJsonOrNull<DownloadJob[]>(config, config.downloadsPath);
+}
+
+async function controlDownload(config: LemonadeConfig, jobId: string, action: "pause" | "cancel" | "remove"): Promise<void> {
+  await postJson(url(config, config.downloadsControlPath), config, { id: jobId, action }, config.discoveryTimeoutMs);
+}
+
+/** Blocking fallback for servers without download-job support. */
+async function pullModelBlocking(config: LemonadeConfig, id: string): Promise<string> {
+  await postJson(url(config, config.pullPath), config, { model_name: id }, config.pullTimeoutMs);
+  return `Pulled ${id} (downloaded to disk).`;
+}
+
+async function deleteModel(config: LemonadeConfig, id: string): Promise<string> {
+  await postJson(url(config, config.deletePath), config, { model_name: id }, config.pullTimeoutMs);
+  return `Deleted ${id} from disk.`;
+}
+
+/** Change ctx for a loaded model: unload → reload with new ctx_size + save_options. */
+async function changeModelContext(config: LemonadeConfig, id: string, ctxSize: number): Promise<string> {
+  await unloadModel(config, id);
+  return loadModel(config, id, ctxSize);
+}
+
+/** Parse "32k", "1m", "262144" → number of tokens. */
+function parseCtxSize(input: string): number | null {
+  const m = input.trim().toLowerCase().match(/^(\d+(?:\.\d+)?)(k|m)?$/);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  return m[2] === "k" ? Math.round(n * 1024) : m[2] === "m" ? Math.round(n * 1024 * 1024) : Math.round(n);
+}
+
+function formatBytes(bytes?: number): string {
+  if (!bytes || bytes <= 0) return "—";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+  return `${(bytes / 1024 ** i).toFixed(1)} ${units[i]}`;
+}
+
+// ─── Server discovery (UDP beacon + HTTP fallback) ──────────────────────────
+
+function normalizeBaseUrl(raw: string): string {
+  return raw.trim().replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+}
+
+function discoverViaBeacon(config: LemonadeConfig, timeoutMs: number): Promise<DiscoveredServer[]> {
+  return new Promise((resolve) => {
+    const found = new Map<string, DiscoveredServer>();
+    let sock: ReturnType<typeof dgram.createSocket> | null = null;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const finish = () => {
+      if (timer) clearTimeout(timer);
+      if (sock) {
+        try { sock.close(); } catch { /* ignore */ }
+        sock = null;
+      }
+      resolve([...found.values()]);
+    };
+
+    try {
+      sock = dgram.createSocket({ type: "udp4", reuseAddr: true });
+      sock.on("error", finish);
+      sock.on("message", (msg: Buffer, rinfo: { address: string }) => {
+        try {
+          const beacon = JSON.parse(msg.toString());
+          if (beacon?.service !== "lemonade") return;
+          const base = normalizeBaseUrl(String(beacon.url ?? ""));
+          if (!base) return;
+          if (!found.has(base)) {
+            found.set(base, { hostname: String(beacon.hostname ?? rinfo.address), baseUrl: base });
+          }
+        } catch { /* not our beacon */ }
+      });
+      sock.bind(config.beaconPort);
+    } catch {
+      finish();
+      return;
+    }
+    timer = setTimeout(finish, timeoutMs);
+  });
+}
+
+async function discoverViaHttp(config: LemonadeConfig): Promise<DiscoveredServer[]> {
+  const candidateHosts = new Set(["localhost"]);
+  // Probe every configured instance's host, not just one: the raw config has
+  // no single baseUrl anymore — servers[] is the only instance store.
+  for (const s of config.servers) {
+    try {
+      candidateHosts.add(new URL(s.baseUrl).hostname);
+    } catch { /* skip malformed */ }
+  }
+  const ports = [13305, 8000, 1234, 9000, 8080];
+
+  const probes = [...candidateHosts].flatMap((host) =>
+    ports.map(async (port) => {
+      try {
+        const res = await fetch(`http://${host}:${port}${config.healthPath}`, {
+          signal: AbortSignal.timeout(1500),
+        });
+        if (!res.ok) return null;
+        const body = (await res.json()) as { status?: string; version?: string };
+        if (typeof body.status !== "string") return null;
+        return { hostname: host, baseUrl: `http://${host}:${port}` } as DiscoveredServer;
+      } catch {
+        return null;
+      }
+    })
+  );
+  const results = await Promise.all(probes);
+  const seen = new Map<string, DiscoveredServer>();
+  for (const r of results) if (r && !seen.has(r.baseUrl)) seen.set(r.baseUrl, r);
+  return [...seen.values()];
+}
+
+// ─── Provider registration ──────────────────────────────────────────────────
+
+function isChatModel(m: LemonadeModel): boolean {
+  return (
+    (m.labels ?? []).includes("chat") ||
+    m.recipe === "llamacpp" ||
+    // Omni collections bundle a chat LLM with server-side tools (image gen,
+    // TTS) and are driven through chat completions like any chat model.
+    m.recipe === "collection.omni"
+  );
+}
+
+function toProviderModel(m: LemonadeModel, loaded: Set<string>, providerId = "lemonade") {
+  const labels = m.labels ?? [];
+  const contextWindow = m.max_context_window ?? 128000;
+  return {
+    id: m.id,
+    name: loaded.has(m.id)
+      ? `${m.id} (${providerId}, loaded)`
+      : `${m.id} (${providerId}, on-demand)`,
+    reasoning: labels.includes("reasoning"),
+    input: labels.includes("vision") ? (["text", "image"] as ("text" | "image")[]) : (["text"] as ("text" | "image")[]),
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow,
+    maxTokens: Math.min(contextWindow, 32768),
+    compat: {
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: "max_tokens" as const,
+    },
+  };
+}
+
+async function registerInstanceProvider(pi: ExtensionAPI, view: InstanceView): Promise<number> {
+  const config = view.config;
+  const providerId = instanceProviderId(view);
+  let catalog: LemonadeModel[];
+  let loaded = new Set<string>();
+  try {
+    const [catalogRes, health] = await Promise.all([
+      fetchCatalog(config),
+      fetchHealth(config),
+    ]);
+    catalog = catalogRes;
+    loaded = new Set((health?.all_models_loaded ?? []).map((m) => m.model_name));
+  } catch {
+    // Unreachable => contribute nothing to /model. No placeholders: an
+    // unreachable model is not listable. Sessions pinned to a lemonade model
+    // will hard-fail model resolution until the box is reachable again —
+    // the accepted tradeoff of "fully automated, fully honest" listings.
+    catalog = [];
+    console.error(
+      `[pi-lemonade-link] instance "${view.name}" unreachable at ${config.baseUrl}; registering no models`
+    );
+  }
+
+  const advertised = config.chatOnly ? catalog.filter(isChatModel) : catalog;
+
+  try {
+    pi.unregisterProvider(providerId);
+  } catch {
+    // not previously registered
+  }
+
+  pi.registerProvider(providerId, {
+    name: `Lemonade ${view.name} (self-hosted)`,
+    baseUrl: url(config, config.chatPath),
+    apiKey: config.apiKey || "lemonade",
+    authHeader: true,
+    api: "openai-completions",
+    models: advertised.map((m) => toProviderModel(m, loaded, providerId)),
+  });
+
+  return advertised.length;
+}
+
+/** Provider ids used by past versions of this extension. unregisterProvider
+ *  only works within the running pi process, and ids changed over the
+ *  extension's evolution, so a long-lived session (or /reload after an
+ *  upgrade) can accumulate ghost providers registered by old code. Each
+ *  registration pass sweeps them; anything not in this list and not a
+ *  current instance id persists until the pi process restarts. */
+const LEGACY_PROVIDER_IDS = ["lemonade", "lemonade-undefined"];
+
+/** Register (or re-register) every configured instance. Each becomes its own
+ *  pi provider under the uniform lemonade-<name> id. */
+async function registerLemonadeProvider(pi: ExtensionAPI, config: LemonadeConfig): Promise<number> {
+  for (const staleId of LEGACY_PROVIDER_IDS) {
+    try {
+      pi.unregisterProvider(staleId);
+    } catch { /* never registered; fine */ }
+  }
+  let total = 0;
+  for (const view of listInstances(config)) {
+    total += await registerInstanceProvider(pi, view);
+  }
+  return total;
+}
+
+// ─── Multimodal agent tools ──────────────────────────────────────────────────
+
+/** Combine an operation timeout with the caller's cancel signal (if any),
+ *  so long-running requests are both bounded and user-cancellable. */
+function boundedSignal(timeoutMs: number, signal?: AbortSignal): AbortSignal {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([timeout, signal]) : timeout;
+}
+
+function readRequiredFile(resolved: string): Promise<Buffer> {
+  return fs.promises.readFile(resolved);
+}
+
+/** whisper.cpp's backend ingests raw wav only; every other format (mp3, mp4,
+ *  ogg, flac, ...) is converted to 16 kHz mono pcm_s16le wav via ffmpeg on
+ *  pi's machine first (the official API documents wav as the only input). */
+const WHISPER_NATIVE_EXT = new Set([".wav", ".wave"]);
+
+async function prepareAudioForWhisper(config: LemonadeConfig, resolved: string): Promise<string> {
+  if (WHISPER_NATIVE_EXT.has(path.extname(resolved).toLowerCase())) return resolved;
+  const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-whisper-"));
+  const converted = path.join(tmpDir, "converted.wav");
+  await runFfmpeg(
+    ["-i", resolved, "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", converted],
+    config.transcriptionTimeoutMs
+  );
+  return converted;
+}
+
+/** Transcribe one file through the server's Whisper endpoint — shared by the
+ *  transcribe_audio tool and the setup menu's smoke test, so both stay in
+ *  lockstep on conversion, model resolution and error wording. Throws Errors
+ *  with user-facing text; tool callers convert them to toolError() results
+ *  (rethrowing AbortError so user cancels stay cancels). */
+async function transcribeViaServer(
+  config: LemonadeConfig,
+  filePath: string,
+  language?: string,
+  signal?: AbortSignal
+): Promise<{ text: string; model: string; file: string }> {
+  const resolved = path.resolve(filePath);
+  let fileToSend: string;
+  let data: Buffer;
+  try {
+    fileToSend = await prepareAudioForWhisper(config, resolved);
+    data = await readRequiredFile(fileToSend);
+  } catch (error) {
+    throw new Error(`Could not prepare '${resolved}': ${error instanceof Error ? error.message : String(error)}`);
+  }
+  try {
+    const model = config.defaultTranscriptionModel || (await pickModelByLabels(config, ["transcription", "whisper"]));
+    if (!model) {
+      throw new Error(
+        "No transcription model found on the lemonade server. Set defaultTranscriptionModel in ~/.pi/agent/lemonade.json, or pull one first (e.g. Whisper-Large-v3)."
+      );
+    }
+    const form = new FormData();
+    form.append("file", new File([data], path.basename(fileToSend)));
+    form.append("model", model);
+    if (language) form.append("language", language);
+    const response = await toolFetch(config, config.transcriptionPath, {
+      method: "POST",
+      headers: authHeaders(config),
+      body: form,
+      signal: boundedSignal(config.transcriptionTimeoutMs, signal),
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${(await response.text()).slice(0, 400)}`);
+    }
+    const payload = (await response.json()) as { text?: string };
+    return { text: payload.text ?? "", model, file: resolved };
+  } finally {
+    // Converted intermediates are disposable — remove the temp dir best-effort.
+    if (fileToSend !== resolved) {
+      await fs.promises.rm(path.dirname(fileToSend), { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+/** Find a sensible default model for a tool, from the live catalog.
+ *
+ * Returns: the picked model id, undefined if no catalog model matches, or
+ * null if the server is unreachable — callers must surface that distinctly,
+ * because "nothing matches" and "no route to the server" need different advice.
+ */
+async function pickModel(
+  config: LemonadeConfig,
+  matches: (m: LemonadeModel) => boolean
+): Promise<string | null | undefined> {
+  try {
+    const hits = (await fetchCatalog(config)).filter(matches);
+    const downloaded = hits.find((m) => m.downloaded !== false) ?? hits[0];
+    return downloaded?.id;
+  } catch {
+    return null; // unreachable
+  }
+}
+
+/** Auto-pick by label (e.g. ["image"], ["tts"]). */
+function pickModelByLabels(
+  config: LemonadeConfig,
+  labelCandidates: string[]
+): Promise<string | null | undefined> {
+  return pickModel(config, (m) => (m.labels ?? []).some((l) => labelCandidates.includes(l)));
+}
+
+/** Auto-pick by recipe (e.g. onnxruntime classifiers). */
+function pickModelByRecipe(
+  config: LemonadeConfig,
+  recipe: string
+): Promise<string | null | undefined> {
+  return pickModel(config, (m) => m.recipe === recipe);
+}
+
+function toolError(message: string): { content: Array<{ type: "text"; text: string }>; details: {} } {
+  return { content: [{ type: "text", text: `Error: ${message}` }], details: {} };
+}
+
+function unreachableMessage(config: LemonadeConfig): string {
+  return (
+    `Lemonade server at ${config.baseUrl} is unreachable from this network — ` +
+    "there is probably no route back to the lemonade LAN. Reconnect to a network " +
+    "with access, or point the extension at a reachable instance: /lemonade-setup → " +
+    "Server settings → Manage instances (or Discover servers)."
+  );
+}
+
+/** fetch() for tool paths: converts raw network rejections (the cryptic
+ *  "fetch failed") into a descriptive, actionable error. Abort/cancel passes
+ *  through untouched. */
+async function toolFetch(config: LemonadeConfig, p: string, init: RequestInit): Promise<Response> {
+  try {
+    return await fetch(url(config, p), init);
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") throw error;
+    throw new Error(unreachableMessage(config));
+  }
+}
+
+/** POST JSON, save binary response body to a file. */
+async function postJsonSaveBinary(
+  config: LemonadeConfig,
+  p: string,
+  body: Record<string, unknown>,
+  kind: string,
+  ext: string,
+  signal?: AbortSignal,
+  extra?: string
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }> {
+  const res = await toolFetch(config, p, {
+    method: "POST",
+    headers: { ...authHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: boundedSignal(config.generationTimeoutMs, signal),
+  });
+  if (!res.ok) {
+    return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  const file = outputFilePath(config, kind, ext);
+  await fs.promises.writeFile(file, buf);
+  return {
+    content: [{
+      type: "text",
+      text: `Saved ${file} (${formatBytes(buf.length)}${extra ? `, ${extra}` : ""}).`,
+    }],
+    details: { file },
+  };
+}
+
+/** Shared response handling for the image endpoints: an OpenAI-style JSON
+ *  payload with b64_json data, or a raw binary body. Saves the PNG and
+ *  returns the standard tool result. */
+async function saveImageResponse(
+  config: LemonadeConfig,
+  res: Response,
+  kind: string,
+  extra?: string
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }> {
+  const contentType = res.headers.get("content-type") ?? "";
+  const file = outputFilePath(config, kind, "png");
+  if (contentType.includes("application/json")) {
+    const payload = (await res.json()) as { data?: Array<{ b64_json?: string }> };
+    const b64 = payload.data?.[0]?.b64_json;
+    if (!b64) return toolError("Server response contained no image data.");
+    await fs.promises.writeFile(file, Buffer.from(b64, "base64"));
+  } else {
+    await fs.promises.writeFile(file, Buffer.from(await res.arrayBuffer()));
+  }
+  return {
+    content: [{ type: "text", text: `Saved ${file}${extra ? ` (${extra})` : ""}.` }],
+    details: { file },
+  };
+}
+
+/** POST multipart, save the response's b64_json / raw binary to a PNG file. */
+async function postFormSaveImage(
+  config: LemonadeConfig,
+  p: string,
+  form: FormData,
+  kind: string,
+  signal?: AbortSignal
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }> {
+  const res = await toolFetch(config, p, {
+    method: "POST",
+    headers: authHeaders(config),
+    body: form,
+    signal: boundedSignal(config.generationTimeoutMs, signal),
+  });
+  if (!res.ok) {
+    return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+  }
+  return saveImageResponse(config, res, kind);
+}
+
+/** POST JSON, save the response's b64_json / raw binary to a PNG file. */
+async function postJsonSaveImage(
+  config: LemonadeConfig,
+  p: string,
+  body: Record<string, unknown>,
+  kind: string,
+  signal?: AbortSignal,
+  extra?: string
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }> {
+  const res = await toolFetch(config, p, {
+    method: "POST",
+    headers: { ...authHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: boundedSignal(config.generationTimeoutMs, signal),
+  });
+  if (!res.ok) {
+    return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+  }
+  return saveImageResponse(config, res, kind, extra);
+}
+
+function outputDir(config: LemonadeConfig): string {
+  return config.outputDir ? path.resolve(config.outputDir) : process.cwd();
+}
+
+function outputFilePath(config: LemonadeConfig, kind: string, ext: string): string {
+  // Millisecond precision: second-resolution stamps silently overwrite when
+  // two outputs land in the same second (e.g. batch generation).
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 23);
+  return path.join(outputDir(config), `lemonade-${kind}-${stamp}.${ext}`);
+}
+
+function runFfmpeg(args: string[], timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", ...args]);
+    let stderr = "";
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", (e) => { clearTimeout(timer); reject(e); });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      code === 0 ? resolve() : reject(new Error(`ffmpeg exited ${code}: ${stderr.slice(0, 300)}`));
+    });
+  });
+}
+
+async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Promise<void> {
+  // Harness-level self-awareness: these lines are merged into the Guidelines
+  // section of every chat's system prompt, so even a virgin chat knows where
+  // its lemonade machinery lives without having to hunt for it. (pi dedupes
+  // guideline strings, so attaching once is enough.)
+  const instanceList = listInstances(gconfig)
+    .map((v) => `${v.name}${v.isDefault ? " (default)" : ""} (${v.config.baseUrl})`)
+    .join("; ");
+  const AWARENESS = [
+    "Self-hosted Lemonade server: base URL, endpoint paths, and defaults live in ~/.pi/agent/lemonade.json; full documentation (tools, endpoints, behavior reference, official API spec) is at ~/.pi/agent/extensions/pi-lemonade-link/README.md and docs/ beside it.",
+    "For questions about the lemonade server (loaded models, catalog, health, host resources), query its HTTP API directly with bash + curl using the config; for interactive management, tell the user to run the /lemonade-setup command.",
+    `Lemonade instances available to tools: ${
+      instanceList ||
+      "(none configured yet — add one via /lemonade-setup or ~/.pi/agent/lemonade.json)"
+    }. Tools accept an optional server argument naming an instance; omit it for the default.`,
+  ];
+
+  const SERVER_PARAM_DESC =
+    "Instance name for multi-server setups (omit for the default instance; see guidelines for the available names).";
+
+  // Enumerate the classifiers actually present on the configured instances, so
+  // the tool's advertisement reflects reality each session. The label universe
+  // of each classifier is baked into the model itself and is revealed at
+  // runtime by the response's labels — the description can only hint via
+  // model ids.
+  let classifierHint = "";
+  {
+    const ids = new Set<string>();
+    const pulled = new Set<string>();
+    await Promise.all(
+      listInstances(gconfig).map(async (v) => {
+        try {
+          const catalog = await fetchCatalog(v.config);
+          for (const m of catalog.filter((m) => m.recipe === "onnxruntime")) {
+            ids.add(m.id);
+            if (m.downloaded !== false) pulled.add(m.id);
+          }
+        } catch {
+          // instance unreachable at registration time — hint stays generic for it
+        }
+      })
+    );
+    if (ids.size) {
+      classifierHint =
+        `Classifiers on this server: ${[...ids].join(", ")}. ` +
+        (pulled.size ? `Pulled and ready: ${[...pulled].join(", ")}.` : "None pulled yet — pull via /lemonade-setup.");
+    }
+  }
+
+  // ── transcribe_audio ────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "transcribe_audio",
+    label: "Transcribe Audio",
+    description:
+      "Transcribe an audio or video file (wav, mp3, mp4, m4a, webm, flac, ...) to text " +
+      "using a Whisper model on the self-hosted lemonade server. Any format other " +
+      "than raw wav is converted to 16 kHz mono wav with ffmpeg automatically. Returns the transcript.",
+    promptSnippet: "[lemonade] Transcribe audio or video files (wav, mp3, mp4, m4a, webm, ...) to text with Whisper",
+    promptGuidelines: AWARENESS,
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      file_path: Type.String({ description: "Path to the audio/video file to transcribe." }),
+      language: Type.Optional(
+        Type.String({ description: "Optional ISO-639-1 language hint (e.g. 'en')." })
+      ),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const resolved = path.resolve(params.file_path);
+      try {
+        const { text, model } = await transcribeViaServer(config, resolved, params.language, signal);
+        return {
+          content: [{ type: "text", text }],
+          details: { file: resolved, model },
+        };
+      } catch (error) {
+        // User cancels stay cancels; everything else becomes a readable error.
+        if (error instanceof Error && error.name === "AbortError") throw error;
+        return toolError(error instanceof Error ? error.message : String(error));
+      }
+    },
+  });
+
+  // ── generate_image ──────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "generate_image",
+    label: "Generate Image",
+    description:
+      "Generate an image from a text prompt using an image model on the lemonade server " +
+      "(e.g. Flux, Z-Image, SD-Turbo). Saves the PNG to disk and returns its path. " +
+      "If no model is specified, the first image model in the catalog is used. " +
+      "Image generation can take a while on first use (model auto-loads).",
+    promptSnippet: "[lemonade] Generate images from text prompts with the local Flux/SD models (saves PNG to disk)",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      prompt: Type.String({ description: "Text description of the image to generate." }),
+      model: Type.Optional(Type.String({ description: "Image model id. Omit to auto-pick." })),
+      size: Type.Optional(Type.String({ description: "Output size as WIDTHxHEIGHT, e.g. 512x512." })),
+      steps: Type.Optional(Type.Number({ description: "Inference steps. Turbo models work well with 4." })),
+      cfg_scale: Type.Optional(Type.Number({ description: "Classifier-free guidance scale. Turbo ~1.0, standard ~7.5." })),
+      seed: Type.Optional(Type.Number({ description: "Random seed for reproducibility." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const auto = await pickModelByLabels(config, ["image"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || config.defaultImageModel || auto;
+      if (!model) return toolError("No image model found on the lemonade server. Pull one first (e.g. Z-Image-Turbo).");
+      const body: Record<string, unknown> = { model, prompt: params.prompt, response_format: "b64_json" };
+      if (params.size) body.size = params.size;
+      if (params.steps) body.steps = params.steps;
+      if (params.cfg_scale) body.cfg_scale = params.cfg_scale;
+      if (params.seed !== undefined) body.seed = params.seed;
+      return postJsonSaveImage(config, config.imageGenerationPath, body, "image", signal, `model: ${model}`);
+    },
+  });
+
+  // ── edit_image ──────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "edit_image",
+    label: "Edit Image",
+    description:
+      "Edit an image with a text prompt (e.g. 'add a red barn, photorealistic') using an " +
+      "edit-capable image model on the lemonade server. Saves the edited PNG and returns its path.",
+    promptSnippet: "[lemonade] Edit local images with text prompts (add/remove/change things), saves result PNG",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      image_path: Type.String({ description: "Path to the source image (PNG)." }),
+      prompt: Type.String({ description: "Description of the desired edit." }),
+      model: Type.Optional(Type.String({ description: "Edit-capable model id (e.g. Flux-2-Klein-9B-GGUF). Omit to auto-pick." })),
+      mask_path: Type.Optional(Type.String({ description: "Optional mask PNG: white = edit, black = preserve." })),
+      size: Type.Optional(Type.String({ description: "Output size WIDTHxHEIGHT, e.g. 512x512." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const resolved = path.resolve(params.image_path);
+      let buf: Buffer;
+      try {
+        buf = await readRequiredFile(resolved);
+      } catch (error) {
+        return toolError(`Could not read '${resolved}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const auto = await pickModelByLabels(config, ["edit", "image"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || config.defaultImageModel || auto;
+      if (!model) return toolError("No edit-capable image model found on the lemonade server.");
+      const form = new FormData();
+      form.append("model", model);
+      form.append("prompt", params.prompt);
+      form.append("response_format", "b64_json");
+      if (params.size) form.append("size", params.size);
+      form.append("image", new File([buf], path.basename(resolved), { type: "image/png" }));
+      if (params.mask_path) {
+        try {
+          const mask = await readRequiredFile(path.resolve(params.mask_path));
+          form.append("mask", new File([mask], path.basename(params.mask_path!), { type: "image/png" }));
+        } catch { /* mask is optional */ }
+      }
+      const result = await postFormSaveImage(config, config.imageEditPath, form, "image-edit", signal);
+      return result;
+    },
+  });
+
+  // ── vary_image ──────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "vary_image",
+    label: "Vary Image",
+    description:
+      "Generate a variation of an image using the lemonade server's image models. " +
+      "Saves the variation PNG and returns its path.",
+    promptSnippet: "[lemonade] Generate variations of local images",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      image_path: Type.String({ description: "Path to the source image (PNG)." }),
+      model: Type.Optional(Type.String({ description: "Image model id. Omit to auto-pick." })),
+      size: Type.Optional(Type.String({ description: "Output size WIDTHxHEIGHT." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const resolved = path.resolve(params.image_path);
+      let buf: Buffer;
+      try {
+        buf = await readRequiredFile(resolved);
+      } catch (error) {
+        return toolError(`Could not read '${resolved}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const auto = await pickModelByLabels(config, ["edit", "image"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || config.defaultImageModel || auto;
+      if (!model) return toolError("No image model found on the lemonade server.");
+      const form = new FormData();
+      form.append("model", model);
+      form.append("response_format", "b64_json");
+      if (params.size) form.append("size", params.size);
+      form.append("image", new File([buf], path.basename(resolved), { type: "image/png" }));
+      return postFormSaveImage(config, config.imageVariationPath, form, "image-variation", signal);
+    },
+  });
+
+  // ── upscale_image ───────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "upscale_image",
+    label: "Upscale Image",
+    description:
+      "Upscale an image 4x with Real-ESRGAN on the lemonade server " +
+      "(models: RealESRGAN-x4plus, RealESRGAN-x4plus-anime). Saves the upscaled PNG and returns its path.",
+    promptSnippet: "[lemonade] Upscale images 4x with Real-ESRGAN",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      image_path: Type.String({ description: "Path to the image to upscale (PNG)." }),
+      model: Type.Optional(Type.String({ description: `Upscale model id. Default: ${DEFAULT_CONFIG.defaultUpscaleModel}.` })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const resolved = path.resolve(params.image_path);
+      let buf: Buffer;
+      try {
+        buf = await readRequiredFile(resolved);
+      } catch (error) {
+        return toolError(`Could not read '${resolved}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const model = params.model ?? config.defaultUpscaleModel;
+      return postJsonSaveImage(
+        config,
+        config.imageUpscalePath,
+        { image: buf.toString("base64"), model },
+        "image-upscaled",
+        signal,
+        `model: ${model}`
+      );
+    },
+  });
+
+  // ── text_to_speech ──────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "text_to_speech",
+    label: "Text to Speech",
+    description:
+      "Convert text to spoken audio using a TTS model on the lemonade server " +
+      "(e.g. OpenMOSS-TTS). Saves the audio file and returns its path.",
+    promptSnippet: "[lemonade] Convert text to spoken audio (TTS), saves mp3/wav to disk",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      text: Type.String({ description: "The text to speak." }),
+      model: Type.Optional(Type.String({ description: "TTS model id. Omit to auto-pick from catalog." })),
+      voice: Type.Optional(Type.String({ description: "Voice name (e.g. 'alloy', 'af_sky')." })),
+      speed: Type.Optional(Type.Number({ description: "Speaking speed (default 1.0)." })),
+      response_format: Type.Optional(Type.String({ description: "Output format: mp3 (default), wav, opus, pcm." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const auto = await pickModelByLabels(config, ["tts"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || auto;
+      if (!model) return toolError("No TTS model found on the lemonade server. Pull one first (e.g. OpenMOSS-TTS).");
+      const fmt = params.response_format ?? "mp3";
+      const body: Record<string, unknown> = { model, input: params.text, response_format: fmt };
+      if (params.voice) body.voice = params.voice;
+      if (params.speed) body.speed = params.speed;
+      return postJsonSaveBinary(config, config.speechPath, body, "speech", fmt === "pcm" ? "pcm" : fmt, signal, `model: ${model}`);
+    },
+  });
+
+  // ── generate_audio (music / sound effects) ─────────────────────────────
+  pi.registerTool({
+    name: "generate_audio",
+    label: "Generate Audio",
+    description:
+      "Generate music or sound effects from a text prompt using audio-generation models on " +
+      "the lemonade server (e.g. ACE-Step-Music, ThinkSound-SFX). For music with vocals, " +
+      "pass lyrics with section tags like [verse] and [chorus]. Saves a wav file and returns its path.",
+    promptSnippet: "[lemonade] Generate music or sound effects from text prompts (ACE-Step / ThinkSound), saves wav",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      prompt: Type.String({ description: "Style description: genre, mood, tempo, instruments, voice character." }),
+      model: Type.Optional(Type.String({ description: "Audio model id (e.g. ThinkSound-SFX, ACE-Step-Music). Omit to auto-pick." })),
+      duration: Type.Optional(Type.Number({ description: "Clip length in seconds." })),
+      lyrics: Type.Optional(Type.String({ description: "Lyrics to sing (music models only). Omit for instrumental." })),
+      vocal_language: Type.Optional(Type.String({ description: "BCP-47 language of lyrics, e.g. 'en' (music models only)." })),
+      seed: Type.Optional(Type.Number({ description: "Random seed for reproducibility." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const auto = await pickModelByLabels(config, ["music", "sfx", "audio", "tts-audio"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || auto;
+      if (!model) return toolError("No audio-generation model found on the lemonade server. Pull one first (e.g. ThinkSound-SFX).");
+      const body: Record<string, unknown> = { model, prompt: params.prompt, response_format: "wav" };
+      if (params.duration) body.duration = params.duration;
+      if (params.lyrics) body.lyrics = params.lyrics;
+      if (params.vocal_language) body.vocal_language = params.vocal_language;
+      if (params.seed !== undefined) body.seed = params.seed;
+      return postJsonSaveBinary(config, config.audioGenerationPath, body, "audio-gen", "wav", signal, `model: ${model}`);
+    },
+  });
+
+  // ── generate_3d_model ──────────────────────────────────────────────────
+  pi.registerTool({
+    name: "generate_3d_model",
+    label: "Generate 3D Model",
+    description:
+      "Generate a textured 3D mesh (.glb) from an image using the TRELLIS-3D model on the " +
+      "lemonade server. Saves the .glb file and returns its path. Can take minutes.",
+    promptSnippet: "[lemonade] Generate textured 3D meshes (.glb) from images with TRELLIS",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      image_path: Type.String({ description: "Path to the input image (PNG/JPEG/BMP/GIF)." }),
+      model: Type.Optional(Type.String({ description: "3D model id, e.g. TRELLIS-3D. Omit to auto-pick." })),
+      resolution: Type.Optional(Type.Number({ description: "Cascade resolution: 512 (default), 1024, or 1536." })),
+      seed: Type.Optional(Type.Number({ description: "Random seed for reproducibility." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const resolved = path.resolve(params.image_path);
+      let buf: Buffer;
+      try {
+        buf = await readRequiredFile(resolved);
+      } catch (error) {
+        return toolError(`Could not read '${resolved}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const auto = await pickModelByLabels(config, ["3d"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || auto;
+      if (!model) return toolError("No 3D-generation model found on the lemonade server. Pull one first (e.g. TRELLIS-3D).");
+      const body: Record<string, unknown> = { model, image: `data:image/png;base64,${buf.toString("base64")}` };
+      if (params.resolution) body.resolution = params.resolution;
+      if (params.seed !== undefined) body.seed = params.seed;
+      return postJsonSaveBinary(config, config.mesh3dPath, body, "mesh3d", "glb", signal);
+    },
+  });
+
+  // ── classify_text ────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "classify_text",
+    label: "Classify Text",
+    description:
+      "Classify input TEXT with an encoder-classifier model on the lemonade server " +
+      "(recipe: onnxruntime). Each classifier answers exactly one question, decided by " +
+      "its baked-in label set, and the response's labels reveal that universe — if they " +
+      "don't fit the question, retry with a different model. Text-only by architecture: " +
+      "image questions go to vision-capable chat models (read the image), audio must be " +
+      "transcribed first (transcribe_audio). " +
+      (classifierHint ||
+        "Common classifier types: phishing/PII/prompt-injection detection. Pull via /lemonade-setup.") +
+      " Returns all labels with confidence scores, ranked highest to lowest.",
+    promptSnippet:
+      "[lemonade] Classify text through safety/phishing/PII-style classifier models — ranked label confidences",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      input: Type.String({ description: "The text to classify." }),
+      model: Type.Optional(
+        Type.String({ description: "Classifier model id (recipe onnxruntime). Omit to auto-pick." })
+      ),
+      top_k: Type.Optional(
+        Type.Number({ description: "Only return the highest-scoring k labels." })
+      ),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const auto = await pickModelByRecipe(config, "onnxruntime");
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || config.defaultClassifierModel || auto;
+      if (!model) {
+        return toolError(
+          "No classifier model (onnxruntime recipe) found on the lemonade server. " +
+            "Pull one first, e.g. Bert-Phishing-ONNX or Phishing-Email-Detection-ONNX."
+        );
+      }
+      const body: Record<string, unknown> = { model, input: params.input };
+      if (params.top_k) body.top_k = params.top_k;
+      const res = await toolFetch(config, config.classifyPath, {
+        method: "POST",
+        headers: { ...authHeaders(config), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+      });
+      if (!res.ok) {
+        return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+      }
+      const payload = (await res.json()) as Record<string, unknown> & {
+        labels?: Record<string, number>;
+        model?: string;
+      };
+      const ranked = Object.entries(payload.labels ?? {})
+        .sort((a, b) => b[1] - a[1])
+        .map(([label, score]) => `${(score * 100).toFixed(3).padStart(7)}%  ${label}`);
+      // Some classifiers (token-classification, e.g. PII span detection) return
+      // extra structure beyond the flat label map — pass it through verbatim.
+      const extras = Object.keys(payload).filter((k) => !["labels", "model", "object"].includes(k));
+      const extraText = extras.length
+        ? "\n" + JSON.stringify(Object.fromEntries(extras.map((k) => [k, payload[k]])), null, 2)
+        : "";
+      const text =
+        `Classification by ${payload.model ?? model}:\n` +
+        (ranked.length ? ranked.join("\n") : "(no labels returned)") +
+        extraText;
+      return { content: [{ type: "text", text }], details: { model } };
+    },
+  });
+}
+
+// ─── Lemonade status bar (belowEditor widget) ──────────────────────────────
+
+/** Lemonade instance from a pi model: provider "lemonade-<instance>" → "<instance>".
+ *  The picker address "lemonade-<instance>/<model>" is display-only — the
+ *  Model object keeps provider and id in separate fields. */
+function instanceFromModel(model: { id?: string; provider?: string } | undefined): string | null {
+  if (typeof model?.provider !== "string" || !model.provider.startsWith("lemonade-")) return null;
+  const instance = model.provider.slice("lemonade-".length);
+  return instance || null;
+}
+
+/** Metrics behind the bar. tok/s + cache % are session-local (derived from
+ *  pi's own message events); busy/queue, CPU/GPU and VRAM are polled from the
+ *  instance. Segments never appear or vanish — every segment is permanent and
+ *  shows a "…" placeholder until its first value lands. */
+interface BarMetrics {
+  toksPerSec: number | null; // last completed assistant message, locally timed
+  cachePct: number | null; // its prefix-cache hit rate (usage.cacheRead / prompt)
+  busy: string | null; // "idle" | "busy" | "busy ·Nq" | "offline"
+  cpuPct: number | null;
+  gpuPct: number | null;
+  npuPct: number | null;
+  npuSupported: boolean | null; // null = unknown yet; false = box has no NPU (segment dropped)
+  vramGb: number | null;
+}
+
+/**
+ * Below-editor status bar, shown ONLY while a lemonade model is active.
+ * Appears as its own row (ctx.ui.setWidget, placement "belowEditor") — the
+ * built-in footer and any other extension's custom footer are untouched.
+ * `model_select`/`session_start` add or remove the row as the active model
+ * changes; the instance name comes from the model id itself.
+ */
+function registerLemonadeBar(pi: ExtensionAPI, configRef: { current: LemonadeConfig }): void {
+  const KEY = "lemonade-status-bar";
+  type ExtCtx = import("@earendil-works/pi-coding-agent").ExtensionContext;
+
+  const metrics: BarMetrics = { toksPerSec: null, cachePct: null, busy: null, cpuPct: null, gpuPct: null, npuPct: null, npuSupported: null, vramGb: null };
+  let activeInstance: string | null = null;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let tuiRef: { requestRender(): void } | undefined;
+  let msgStartAt: number | null = null;
+
+  const stopTimer = () => {
+    if (timer !== undefined) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+  };
+
+  const resetLocal = () => {
+    metrics.toksPerSec = null;
+    metrics.cachePct = null;
+    metrics.busy = null;
+    metrics.cpuPct = null;
+    metrics.gpuPct = null;
+    metrics.npuPct = null;
+    metrics.npuSupported = null;
+    metrics.vramGb = null;
+    msgStartAt = null; // a stream started under another/removed row must not leak into the next
+  };
+
+  /** One poll of the active instance: busy/queue, CPU/GPU, VRAM. Transient
+   *  failures mark the box "offline" but keep the last-known gauge values —
+   *  segments never vanish. Results are discarded if the row switched
+   *  instances mid-fetch. */
+  const tick = async (instance: string): Promise<void> => {
+    if (activeInstance !== instance) return; // switched away before we started
+    const view = instanceView(configRef.current, instance);
+    if (typeof view === "string") {
+      if (activeInstance === instance) metrics.busy = "offline"; // instance vanished mid-session
+      tuiRef?.requestRender();
+      return;
+    }
+    const [health, sys, metricsBody] = await Promise.all([
+      fetchHealth(view),
+      fetchJsonOrNull<SystemStats>(view, "/v1/system-stats"),
+      fetchTextOrNull(view, "/metrics"),
+    ]);
+    if (activeInstance !== instance) return; // row switched while fetching: discard
+    if (!health) {
+      metrics.busy = "offline"; // gauges keep their last-known values
+    } else {
+      let queue = 0;
+      if (metricsBody) {
+        const pm = parsePrometheus(metricsBody);
+        queue =
+          (pm.get("lemonade_llamacpp_requests_processing") ?? 0) +
+          (pm.get("lemonade_llamacpp_requests_deferred") ?? 0);
+      }
+      const busyModel = (health.all_models_loaded ?? []).some((m) => m.is_busy || m.is_streaming);
+      metrics.busy = busyModel ? (queue > 1 ? `busy ·${queue}q` : "busy") : "idle";
+      if (typeof sys?.cpu_percent === "number") metrics.cpuPct = sys.cpu_percent;
+      if (typeof sys?.gpu_percent === "number") metrics.gpuPct = sys.gpu_percent;
+      if (typeof sys?.npu_percent === "number") {
+        metrics.npuPct = sys.npu_percent;
+        metrics.npuSupported = true;
+      } else if (sys) {
+        metrics.npuSupported = false; // box reported system-stats with no NPU
+      }
+      if (typeof sys?.vram_gb === "number") metrics.vramGb = sys.vram_gb;
+    }
+    tuiRef?.requestRender();
+  };
+
+  const teardown = (ctx: ExtCtx) => {
+    stopTimer();
+    tuiRef = undefined;
+    activeInstance = null;
+    resetLocal();
+    try {
+      ctx.ui.setWidget(KEY, undefined);
+    } catch {
+      /* widget never installed */
+    }
+  };
+
+  const install = (ctx: ExtCtx, instance: string) => {
+    stopTimer();
+    resetLocal();
+    activeInstance = instance;
+    ctx.ui.setWidget(
+      KEY,
+      (tui, theme) => {
+        tuiRef = tui;
+        const component = {
+          render: (width: number) => {
+            const dim = (s: string) => theme.fg("dim", s);
+            // Fixed segment layout — segments never appear or vanish, only
+            // their values change. Polled segments are omitted entirely only
+            // when polling is disabled (barPollMs: 0), not while pending.
+            const polls = configRef.current.barPollMs > 0;
+            const parts = [theme.fg("accent", `🍋 ${instance}`)];
+            parts.push(
+              dim(metrics.toksPerSec !== null ? `${metrics.toksPerSec.toFixed(1)} tok/s` : "… tok/s")
+            );
+            parts.push(
+              dim(metrics.cachePct !== null ? `cache-hit ${metrics.cachePct.toFixed(0)}%` : "cache-hit …%")
+            );
+            if (polls) {
+              if (metrics.busy === null) parts.push(dim("…"));
+              else if (metrics.busy === "idle") parts.push(dim("idle"));
+              else parts.push(theme.fg("warning", metrics.busy));
+              parts.push(dim(`CPU ${metrics.cpuPct !== null ? `${metrics.cpuPct.toFixed(0)}%` : "…"}`));
+              parts.push(dim(`GPU ${metrics.gpuPct !== null ? `${metrics.gpuPct.toFixed(0)}%` : "…"}`));
+              // Boxes without an NPU report npu_percent: null — the segment is
+              // dropped permanently on first sight, never flickering.
+              if (metrics.npuSupported !== false)
+                parts.push(
+                  dim(`NPU ${metrics.npuPct !== null ? `${metrics.npuPct.toFixed(0)}%` : "…"}`)
+                );
+              parts.push(dim(`VRAM ${metrics.vramGb !== null ? `${metrics.vramGb.toFixed(1)}G` : "…"}`));
+            }
+            return [truncateToWidth(parts.join(theme.fg("dim", " · ")), width)];
+          },
+          invalidate: () => {},
+          dispose: () => {
+            stopTimer();
+            tuiRef = undefined;
+          },
+        };
+        const pollMs = configRef.current.barPollMs;
+        if (pollMs > 0) {
+          void tick(instance); // prime immediately, then on the interval
+          timer = setInterval(() => void tick(instance), Math.max(1000, pollMs));
+        }
+        return component;
+      },
+      { placement: "belowEditor" }
+    );
+  };
+
+  /** Add, swap, or remove the row to match the active model. The model comes
+   *  from the event when it carries one (model_select), else from ctx. */
+  const sync = (ctx: ExtCtx, model?: { id?: string; provider?: string }) => {
+    if (!ctx.hasUI) return;
+    const instance = instanceFromModel(model ?? ctx.model);
+    if (!instance || !configRef.current.statusBar) {
+      if (activeInstance !== null) teardown(ctx);
+      return;
+    }
+    if (activeInstance === instance) return; // already showing this instance
+    install(ctx, instance);
+  };
+
+  pi.on("session_start", (_e, ctx) => sync(ctx));
+  pi.on("model_select", (e, ctx) =>
+    sync(ctx, (e as { model?: { id?: string; provider?: string } }).model)
+  );
+  // Safety net: if ctx.model wasn't resolvable at session_start, the first
+  // turn re-checks. sync() is idempotent — it early-returns when unchanged.
+  pi.on("turn_start", (_e, ctx) => sync(ctx));
+
+  // Session-local metrics: tok/s is timed from message_start → message_end and
+  // divided by usage.output; cache hit % is usage.cacheRead / (cacheRead + input)
+  // — pi-ai maps llama.cpp prefix-cache hits onto usage.cacheRead, so this is
+  // always the session's own request, never the server's last-client stats.
+  pi.on("message_start", (e) => {
+    if (activeInstance !== null && (e as { message?: { role?: string } }).message?.role === "assistant")
+      msgStartAt = Date.now();
+  });
+  pi.on("message_end", (e) => {
+    if (activeInstance === null) return;
+    const m = e as {
+      message?: { role?: string; usage?: { input?: number; output?: number; cacheRead?: number } };
+    };
+    if (m.message?.role !== "assistant") return;
+    const u = m.message.usage;
+    if (msgStartAt !== null && u && typeof u.output === "number" && u.output > 0) {
+      const secs = (Date.now() - msgStartAt) / 1000;
+      if (secs > 0.1) metrics.toksPerSec = u.output / secs;
+    }
+    if (u) {
+      const prompt = (u.cacheRead ?? 0) + (u.input ?? 0);
+      metrics.cachePct = prompt > 0 ? ((u.cacheRead ?? 0) / prompt) * 100 : null;
+    }
+    msgStartAt = null;
+    tuiRef?.requestRender();
+  });
+}
+
+// ─── /lemonade-setup TUI ────────────────────────────────────────────────────
+
+type UiCtx = { ui: import("@earendil-works/pi-coding-agent").ExtensionContext["ui"] };
+
+/** Menu item for the SelectList-based menus. pi-tui's SelectItem is
+ *  string-valued; this local shape restores a typed `value` so menu<T>()
+ *  callers get literal-union results instead of bare strings. */
+interface MenuItem<T extends string> {
+  value: T;
+  label: string;
+  description?: string;
+}
+
+/** Show a SelectList menu framed with DynamicBorder. Returns chosen value or null on Esc. */
+function menu<T extends string>(ctx: UiCtx, title: string, items: MenuItem<T>[]): Promise<T | null> {
+  return ctx.ui.custom<T | null>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+    const list = new SelectList(items, Math.min(items.length, 12), {
+      selectedPrefix: (t) => theme.fg("accent", t),
+      selectedText: (t) => theme.fg("accent", t),
+      description: (t) => theme.fg("muted", t),
+      scrollInfo: (t) => theme.fg("dim", t),
+      noMatch: (t) => theme.fg("warning", t),
+    });
+    list.onSelect = (item) => done(item.value as T);
+    list.onCancel = () => done(null);
+    container.addChild(list);
+    container.addChild(new Text(theme.fg("dim", "↑↓ navigate • enter select • esc back"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data) => { list.handleInput(data); tui.requestRender(); },
+    };
+  });
+}
+
+/** Live-refresh wiring for the scrollable textView (status panel). */
+interface TextViewLive {
+  /** Poll interval in ms; failed/empty refetches keep the last good snapshot. */
+  pollMs?: number;
+  refetch?: () => Promise<string[]>;
+  /** Extra footer key hint (e.g. "n/p instance"), shown when multiple targets exist. */
+  extraHint?: string;
+  /** Hook for keys beyond scroll/quit; return true when the key was consumed. */
+  onKey?: (data: string, api: { setTitle: (t: string) => void }) => boolean;
+}
+
+/** Full-screen framed text view; any key returns. `scrollable` adds keyboard
+ *  paging; `live` adds polling + a key hook (scrollable mode only). */
+async function textView(
+  ctx: UiCtx,
+  title: string,
+  lines: string[],
+  scrollable = false,
+  live?: TextViewLive
+): Promise<void> {
+  await ctx.ui.custom<null>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    const titleText = new Text(theme.fg("accent", theme.bold(title)), 1, 0);
+    container.addChild(titleText);
+    if (!scrollable) {
+      for (const line of lines) container.addChild(new Text(line, 0, 0));
+      const footer = new Text(theme.fg("dim", "press any key to return"), 1, 0);
+      container.addChild(footer);
+      container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+      return {
+        render: (w) => container.render(w),
+        invalidate: () => container.invalidate(),
+        handleInput: () => { done(null); tui.requestRender(); },
+      };
+    }
+
+    // Scrollable: render only a terminal-height window of the lines, with a
+    // live position indicator. The main screen has no layout engine for this
+    // custom view, so ScrollView is inert here — the window is sliced by hand.
+    // The slice is wrap-aware: lines longer than the terminal width occupy
+    // more than one rendered row, so the window is filled by *rows*, not by
+    // line count (otherwise long lines push the footer off-screen on narrow
+    // terminals and scrolling can stop short of the real end).
+    const body = new Text("", 0, 0);
+    container.addChild(body);
+    const footer = new Text("", 1, 0);
+    container.addChild(footer);
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+    let cur = lines; // swapped in place by live refetches
+
+    // top border + title + footer + bottom border = 4 lines; keep one spare
+    // row so word-wrap loss (wrap estimates are a lower bound) never pushes
+    // the bottom border off-screen.
+    const overhead = 5;
+    const viewport = () => Math.max(3, tui.terminal.rows - overhead);
+    const rowsOf = (l: string) => Math.max(1, Math.ceil(l.length / Math.max(10, tui.terminal.columns)));
+
+    // Row offset of each line's first rendered row; offsets[cur.length] = total rows.
+    const rowOffsets = (): number[] => {
+      const off: number[] = [];
+      let acc = 0;
+      for (const l of cur) {
+        off.push(acc);
+        acc += rowsOf(l);
+      }
+      off.push(acc);
+      return off;
+    };
+
+    let top = 0;
+    /** Largest line index that still leaves a full viewport of rows below. */
+    const maxTop = () => {
+      const off = rowOffsets();
+      const vh = viewport();
+      let i = cur.length - 1;
+      while (i > 0 && off[cur.length] - off[i] < vh) i--;
+      return i;
+    };
+    /** Line index `byRows` rendered rows down/up from `top`. */
+    const advance = (byRows: number): number => {
+      const off = rowOffsets();
+      const target = off[top] + byRows;
+      let i = top;
+      while (i < cur.length - 1 && off[i] < target) i++;
+      return i;
+    };
+    const retreat = (byRows: number): number => {
+      const off = rowOffsets();
+      const target = Math.max(0, off[top] - byRows);
+      let i = top;
+      while (i > 0 && off[i] > target) i--;
+      return i;
+    };
+
+    const refresh = () => {
+      const off = rowOffsets();
+      const vh = viewport();
+      top = Math.min(top, maxTop());
+      const slice: string[] = [];
+      let used = 0;
+      let j = top;
+      while (j < cur.length) {
+        const r = rowsOf(cur[j]);
+        if (used + r > vh && slice.length) break; // always show at least the top line
+        used += r;
+        slice.push(cur[j]);
+        j++;
+      }
+      body.setText(slice.join("\n"));
+      // Hint ladder: the full hint (scroll keys + instance keys + quit keys +
+      // position) is ~80 chars and wraps on 80-col terminals, so progressively
+      // shorter variants are tried until one fits the usable width. Keys are
+      // unaffected — the hint is best-effort documentation.
+      const base = [...(live?.extraHint ? [live.extraHint] : []), "q/esc/enter return"].join(" · ");
+      const pos = `lines ${top + 1}–${top + slice.length} of ${cur.length}`;
+      const scrollableNow = off[cur.length] > vh;
+      const candidates = scrollableNow
+        ? [
+            `↑↓/jk/pgup·pgdn/home/end · ${base} · ${pos}`,
+            `↑↓/jk/pgup·pgdn · ${base} · ${pos}`,
+            `↑↓/jk · ${base}`,
+            base,
+          ]
+        : [base, "q/esc return"];
+      const budget = Math.max(10, tui.terminal.columns) - 2; // Text paddingX 1 each side
+      const hint = candidates.find((c) => c.length <= budget) ?? candidates[candidates.length - 1];
+      footer.setText(theme.fg("dim", hint));
+    };
+    refresh();
+
+    // Live polling: swap in fresh lines on each tick. Transient fetch failures
+    // keep the last good snapshot on screen; the timer dies with the view.
+    // Ticks coalesce with a trailing edge: a tick requested while one is in
+    // flight (fast n/p cycling) runs once after it, with the latest target.
+    let inFlight = false;
+    let pending = false;
+    const tick = async (): Promise<void> => {
+      if (!live?.refetch) return;
+      if (inFlight) {
+        pending = true;
+        return;
+      }
+      inFlight = true;
+      try {
+        const next = await live.refetch();
+        if (next && next.length) {
+          cur = next;
+          refresh();
+          tui.requestRender();
+        }
+      } catch {
+        /* keep showing the last good snapshot */
+      } finally {
+        inFlight = false;
+        if (pending) {
+          pending = false;
+          void tick();
+        }
+      }
+    };
+    let timer: ReturnType<typeof setInterval> | undefined;
+    if (live?.refetch) timer = setInterval(() => void tick(), Math.max(250, live.pollMs ?? 2000));
+    const cleanup = () => {
+      if (timer !== undefined) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+    };
+
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data) => {
+        // Letters have no Key.* members (Key only covers special/symbol keys);
+        // "j"/"k"/"q" are valid bare KeyIds. Never let an input error become an
+        // uncaught exception — it would take down the whole pi process.
+        try {
+          const page = () => Math.max(1, viewport() - 1);
+          if (matchesKey(data, Key.up) || matchesKey(data, "k")) top = retreat(1);
+          else if (matchesKey(data, Key.down) || matchesKey(data, "j")) top = Math.min(maxTop(), advance(1));
+          else if (matchesKey(data, Key.pageUp)) top = retreat(page());
+          else if (matchesKey(data, Key.pageDown)) top = Math.min(maxTop(), advance(page()));
+          else if (matchesKey(data, Key.home)) top = 0;
+          else if (matchesKey(data, Key.end)) top = maxTop();
+          else if (
+            matchesKey(data, Key.escape) ||
+            matchesKey(data, Key.enter) ||
+            matchesKey(data, "q")
+          ) {
+            cleanup();
+            done(null);
+            tui.requestRender();
+            return;
+          } else if (
+            live?.onKey &&
+            live.onKey(data, {
+              setTitle: (t: string) => titleText.setText(theme.fg("accent", theme.bold(t))),
+            })
+          ) {
+            void tick(); // target changed — refresh immediately, poll continues on it
+          }
+          refresh();
+          tui.requestRender();
+        } catch {
+          // A failed key match must not kill the process — swallow and continue.
+        }
+      },
+      dispose: cleanup,
+      handleMouse: (event: TuiMouseEvent): TuiMouseEventResult | undefined => {
+        if (event.type !== "wheel" || !event.wheelDelta) return undefined;
+        top =
+          event.wheelDelta > 0
+            ? Math.min(maxTop(), advance(event.wheelDelta))
+            : retreat(-event.wheelDelta);
+        refresh();
+        tui.requestRender();
+        return { handled: true };
+      },
+    };
+  });
+}
+
+/**
+ * Live download-progress view over a server-owned download job.
+ * Polls GET /v1/downloads once per second; Esc sends a cancel via
+ * /v1/downloads/control. Resolves when the job completes, errors,
+ * disappears (treated as completed), or the user cancels.
+ */
+async function trackDownload(
+  ctx: UiCtx,
+  config: LemonadeConfig,
+  jobId: string,
+  label: string
+): Promise<"complete" | "cancelled" | "error"> {
+  const outcome = await ctx.ui.custom<"complete" | "cancelled" | "error">((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(`Downloading ${label}`)), 1, 0));
+    const statusLine = new Text("starting…", 0, 0);
+    container.addChild(statusLine);
+    container.addChild(new Text(theme.fg("dim", "esc cancel • progress updates every second"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+    let finished = false;
+    let seen = false;
+    const finish = (v: "complete" | "cancelled" | "error") => {
+      if (finished) return;
+      finished = true;
+      done(v);
+    };
+
+    void (async () => {
+      while (!finished) {
+        const jobs = await listDownloads(config);
+        const job = (jobs ?? []).find((j) => j.id === jobId);
+        if (job) {
+          seen = true;
+          const pct = typeof job.percent === "number" ? `${job.percent.toFixed(1)}%` : "?";
+          const bytes = `${formatBytes(job.cumulative_bytes_downloaded ?? job.bytes_downloaded)} / ${formatBytes(job.total_download_size ?? job.bytes_total)}`;
+          statusLine.setText(
+            `${job.status} — ${pct} (${bytes})${job.file ? ` — ${job.file}` : ""}` +
+              `${job.file_index && job.total_files ? ` [file ${job.file_index}/${job.total_files}]` : ""}` +
+              (job.error ? `\nerror: ${job.error.slice(0, 120)}` : "")
+          );
+          tui.requestRender();
+          if (job.complete || job.status === "completed") return finish("complete");
+          if (job.status === "error") return finish("error");
+          if (job.status === "cancelled") return finish("cancelled");
+        } else if (seen) {
+          // Completed jobs are removed from the list after a short delay.
+          return finish("complete");
+        } else if (jobs !== null) {
+          // Job not registered yet (server hasn't picked it up) — keep polling.
+        } else {
+          statusLine.setText("cannot reach server — press esc to cancel");
+          tui.requestRender();
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+      }
+    })();
+
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data) => {
+        if (matchesKey(data, Key.escape)) {
+          statusLine.setText("cancelling…");
+          tui.requestRender();
+          void controlDownload(config, jobId, "cancel").catch(() => {});
+          finish("cancelled");
+        }
+      },
+    };
+  });
+  return outcome;
+}
+
+/** Live server log viewer: subscribes to ws://host:{wsPort}/logs/stream, shows
+ *  the snapshot backlog then live entries; Esc closes. */
+async function liveLogsView(ctx: UiCtx, config: LemonadeConfig): Promise<void> {
+  ctx.ui.setStatus("lemonade-setup", "Finding websocket port…");
+  const health = await fetchHealth(config);
+  ctx.ui.setStatus("lemonade-setup", undefined);
+  const wsPort = health?.websocket_port;
+  if (!wsPort) {
+    ctx.ui.notify("Server unreachable, or no websocket port advertised — cannot stream logs.", "error");
+    return;
+  }
+  let host = "localhost";
+  try {
+    host = new URL(config.baseUrl).hostname;
+  } catch { /* keep localhost */ }
+  const wsUrl = `ws://${host}:${wsPort}/logs/stream`;
+
+  await ctx.ui.custom<null>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(`Live Server Logs`)), 1, 0));
+    container.addChild(new Text(theme.fg("dim", wsUrl), 0, 0));
+    const logText = new Text("connecting…", 0, 0);
+    container.addChild(logText);
+    container.addChild(new Text(theme.fg("dim", "esc to close • newest 40 lines shown"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+    const lines: string[] = [];
+    let closed = false;
+    const push = (line: string) => {
+      if (closed) return;
+      lines.push(line.slice(0, 200));
+      if (lines.length > 5000) lines.splice(0, lines.length - 5000);
+      logText.setText(lines.slice(-40).join("\n"));
+      tui.requestRender();
+    };
+
+    let ws: { close: () => void } | null = null;
+    try {
+      const WS = (globalThis as { WebSocket?: new (url: string) => WebSocket }).WebSocket;
+      if (!WS) throw new Error("no WebSocket global in this runtime");
+      const sock = new WS(wsUrl) as WebSocket & {
+        onopen: (() => void) | null;
+        onmessage: ((ev: { data: unknown }) => void) | null;
+        onclose: (() => void) | null;
+        onerror: (() => void) | null;
+        send: (data: string) => void;
+      };
+      ws = { close: () => { try { sock.close(); } catch { /* ignore */ } } };
+      sock.onopen = () => {
+        sock.send(JSON.stringify({ type: "logs.subscribe", after_seq: null }));
+        push("— subscribed —");
+      };
+      sock.onmessage = (ev) => {
+        try {
+          const msg = JSON.parse(String(ev.data)) as {
+            type?: string;
+            entries?: Array<{ timestamp?: string; line?: string }>;
+            entry?: { timestamp?: string; line?: string };
+          };
+          if (msg.type === "logs.snapshot") {
+            for (const e of msg.entries ?? []) push(`${e.timestamp ?? ""} ${e.line ?? ""}`);
+            if (!(msg.entries ?? []).length) push("(no backlog entries)");
+          } else if (msg.type === "logs.entry") {
+            const e = msg.entry ?? {};
+            push(`${e.timestamp ?? ""} ${e.line ?? ""}`);
+          }
+        } catch { /* non-JSON frame */ }
+      };
+      sock.onclose = () => push("— connection closed —");
+      sock.onerror = () => push("— connection error —");
+    } catch (error) {
+      push(`connect failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data) => {
+        if (matchesKey(data, Key.escape)) {
+          closed = true;
+          ws?.close();
+          done(null);
+          tui.requestRender();
+        }
+      },
+    };
+  });
+}
+
+/** Format a metric family section title, e.g. "── /v1/stats ────────────". */
+function sectionTitle(name: string): string {
+  const label = ` ${name} `;
+  return `──${label}${"─".repeat(Math.max(2, 44 - label.length))}`;
+}
+
+/** Compact token counts: 15,231,250 → "15.2M", 243,182 stays locale-grouped. */
+function fmtTokens(n: number): string {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(2)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  return Math.round(n).toLocaleString("en-US");
+}
+
+/** Byte counts → human-readable storage sizes. */
+function fmtBytes(n: number): string {
+  if (n >= 1e12) return `${(n / 1e12).toFixed(1)} TB`;
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)} GB`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)} MB`;
+  return `${Math.round(n / 1e3)} kB`;
+}
+
+/** Parse "125.07 GB"-style totals from system-info into a GiB number. */
+function parseGbTotal(s?: string): number | null {
+  if (!s) return null;
+  const m = s.match(/([\d.]+)\s*GB/i);
+  return m ? parseFloat(m[1]) : null;
+}
+
+/**
+ * Full status panel: every metric family the server exposes, grouped under
+ * a title naming the endpoint it came from. Each section degrades to an
+ * "(unreachable)" line when its endpoint fails — one dead endpoint never
+ * blanks the rest of the panel.
+ */
+function formatStatus(
+  config: LemonadeConfig,
+  health: LemonadeHealth | null,
+  sys: SystemStats | null,
+  perf: PerfStats | null,
+  sysinfo: SystemInfo | null,
+  metrics: Map<string, number> | null,
+  updated?: Date
+): string[] {
+  if (!health) {
+    return [
+      `Unreachable: ${url(config, config.healthPath)}`,
+      "",
+      "Check that the lemonade server is running, then verify the baseUrl",
+      "under Server settings (or run Discover servers).",
+    ];
+  }
+
+  const lines: string[] = [];
+  const telemetry = health.telemetry?.enabled
+    ? `on${health.telemetry.captures?.length ? ` (${health.telemetry.captures.join(", ")})` : ""}`
+    : "off";
+
+  // Header
+  lines.push(
+    `Status: ${health.status ?? "?"}   Lemonade v${health.version ?? "?"}   Telemetry: ${telemetry}` +
+      (updated ? `   · updated ${updated.toTimeString().slice(0, 8)}` : ""),
+    `Endpoint: ${config.baseUrl}   WebSocket port: ${health.websocket_port ?? "?"}`,
+    ""
+  );
+
+  // ── /v1/health ───────────────────────────────────────────────────────
+  lines.push(sectionTitle(config.healthPath));
+  lines.push(`Loaded models (${health.all_models_loaded?.length ?? 0}):`);
+  for (const m of health.all_models_loaded ?? []) {
+    lines.push(
+      `  • ${m.model_name} — ${m.type}, ${m.status}, ${m.device ?? "?"}${m.pinned ? ", pinned" : ""}` +
+        `, ctx ${m.max_context_window ?? "?"}`
+    );
+    const live: string[] = [];
+    live.push(m.is_busy ? "busy" : "idle");
+    if (m.is_streaming) live.push("streaming");
+    live.push(
+      `backend ${m.backend_health ?? "?"}${m.backend_alive === false ? " (backend not responding!)" : ""}`
+    );
+    if (m.watchdog_reset) live.push("watchdog reset");
+    lines.push(`      ${live.join("  ")}`);
+    const meta: string[] = [];
+    if (m.recipe) meta.push(m.recipe);
+    if (m.checkpoint) meta.push(m.checkpoint);
+    if (m.slot_pool) meta.push(`pool ${m.slot_pool}`);
+    if (m.residency_class) meta.push(m.residency_class);
+    if (typeof m.pid === "number") meta.push(`pid ${m.pid}`);
+    if (typeof m.last_use === "number") meta.push(`last use ${m.last_use}`);
+    if (meta.length) lines.push(`      ${meta.join("  ")}`);
+  }
+  if (!health.all_models_loaded?.length) lines.push("  (none)");
+  const slots = Object.entries(health.max_models ?? {})
+    .map(([k, v]) => `${k}:${v}`)
+    .join("  ");
+  if (slots) lines.push(`Slot limits: ${slots}`);
+  const pinned = Object.entries(health.pinned_models ?? {})
+    .filter(([, v]) => v > 0)
+    .map(([k, v]) => `${k}:${v}`)
+    .join("  ");
+  const helpers = Object.values(health.pinned_helper_models ?? {}).reduce((a, b) => a + b, 0);
+  if (pinned) lines.push(`Pinned: ${pinned}${helpers ? `  (+${helpers} pinned helper${helpers > 1 ? "s" : ""})` : ""}`);
+  lines.push("");
+
+  // ── /v1/system-stats ─────────────────────────────────────────────────
+  lines.push(sectionTitle("/v1/system-stats"));
+  if (sys) {
+    const pct = (v?: number | null) => (typeof v === "number" ? `${v.toFixed(0)}%` : "?");
+    const gb = (v?: number | null) => (typeof v === "number" ? `${v.toFixed(1)} GB` : "?");
+    const totalRam = parseGbTotal(sysinfo?.["Physical Memory"]);
+    const ramPart =
+      typeof sys.memory_gb === "number"
+        ? totalRam
+          ? `RAM ${sys.memory_gb.toFixed(1)}/${totalRam.toFixed(1)} GB (${((sys.memory_gb / totalRam) * 100).toFixed(0)}%)`
+          : `RAM ${sys.memory_gb.toFixed(1)} GB`
+        : "RAM ?";
+    lines.push(
+      `CPU ${pct(sys.cpu_percent)}   ${ramPart}   GPU ${pct(sys.gpu_percent)}   VRAM ${gb(sys.vram_gb)}` +
+        (sys.npu_percent !== undefined && sys.npu_percent !== null ? `   NPU ${pct(sys.npu_percent)}` : "")
+    );
+  } else {
+    lines.push("  (unreachable)");
+  }
+  lines.push("");
+
+  // ── /v1/stats ─────────────────────────────────────────────────────────
+  lines.push(sectionTitle("/v1/stats"));
+  if (perf) {
+    if (typeof perf.tokens_per_second === "number") {
+      const num = (v: number | null | undefined, digits = 0) =>
+        typeof v === "number" ? v.toLocaleString("en-US", { maximumFractionDigits: digits }) : "?";
+      lines.push(
+        `Last request: ${perf.tokens_per_second.toFixed(1)} tok/s, TTFT ${
+          typeof perf.time_to_first_token === "number" ? perf.time_to_first_token.toFixed(2) : "?"
+        }s (in ${num(perf.input_tokens)} / out ${num(perf.output_tokens)} tokens)`
+      );
+      if (typeof perf.prompt_tokens === "number") {
+        const cachePart =
+          typeof perf.cache_tokens === "number"
+            ? perf.prompt_tokens > 0
+              ? `, ${num(perf.cache_tokens)} from prefix cache (${((perf.cache_tokens / perf.prompt_tokens) * 100).toFixed(1)}%)`
+              : `, ${num(perf.cache_tokens)} from prefix cache`
+            : "";
+        lines.push(`  prompt ${num(perf.prompt_tokens)} tokens${cachePart}`);
+      }
+      const lifetime: string[] = [];
+      if (typeof perf.request_count_total === "number") lifetime.push(`${num(perf.request_count_total)} requests`);
+      if (typeof perf.input_tokens_total === "number") lifetime.push(`in ${fmtTokens(perf.input_tokens_total)}`);
+      if (typeof perf.output_tokens_total === "number") lifetime.push(`out ${fmtTokens(perf.output_tokens_total)}`);
+      if (typeof perf.prompt_tokens_total === "number") lifetime.push(`prompt ${fmtTokens(perf.prompt_tokens_total)}`);
+      if (typeof perf.cache_tokens_total === "number") lifetime.push(`cache ${fmtTokens(perf.cache_tokens_total)}`);
+      if (lifetime.length) lines.push(`Lifetime: ${lifetime.join(" · ")}`);
+      if (typeof perf.routing_decisions_total === "number" || typeof perf.routing_switches_total === "number") {
+        lines.push(
+          `Routing: ${num(perf.routing_decisions_total)} decisions, ${num(perf.routing_switches_total)} switches`
+        );
+      }
+    } else {
+      lines.push("No requests served since server start.");
+    }
+  } else {
+    lines.push("  (unreachable)");
+  }
+  lines.push("");
+
+  // ── /v1/system-info ──────────────────────────────────────────────────
+  lines.push(sectionTitle("/v1/system-info"));
+  if (sysinfo) {
+    const cpu = sysinfo.devices?.cpu;
+    if (sysinfo.Processor || cpu?.cores) {
+      const coresPart = cpu?.cores ? ` (${cpu.cores}c/${cpu.threads ?? "?"}t)` : "";
+      lines.push(`CPU: ${sysinfo.Processor ?? cpu?.name ?? "?"}${coresPart}`);
+    }
+    if (sysinfo["OS Version"]) lines.push(`OS: ${sysinfo["OS Version"]}`);
+    const gpu = sysinfo.devices?.amd_gpu?.find((g) => g.available !== false) ?? sysinfo.devices?.nvidia_gpu?.find((g) => g.available !== false);
+    if (gpu) {
+      // On Linux the amd_gpu "name" can be a raw device id (e.g. "110501");
+      // fall back to the family in that case.
+      const gpuName = gpu.name && !/^\d+$/.test(gpu.name) ? gpu.name : gpu.family || "?";
+      const gpuParts: string[] = [];
+      if (typeof gpu.integrated === "boolean") gpuParts.push(gpu.integrated ? "integrated" : "discrete");
+      if (gpu.family && gpuName !== gpu.family) gpuParts.push(gpu.family);
+      if (typeof gpu.virtual_mem_gb === "number") gpuParts.push(`virtual mem ${gpu.virtual_mem_gb.toFixed(1)} GB`);
+      else if (typeof gpu.vram_gb === "number" && gpu.vram_gb > 0) gpuParts.push(`VRAM ${gpu.vram_gb.toFixed(1)} GB`);
+      lines.push(`GPU: ${gpuName}${gpuParts.length ? ` — ${gpuParts.join(", ")}` : ""}`);
+    }
+    const npu = sysinfo.devices?.amd_npu;
+    if (npu && npu.available !== false) {
+      const npuParts: string[] = [];
+      if (npu.power_mode) npuParts.push(`power mode ${npu.power_mode}`);
+      if (typeof npu.tops_max_int === "number") npuParts.push(`${npu.tops_max_int} TOPS`);
+      if (npuParts.length || npu.name || npu.family) {
+        lines.push(`NPU: ${npu.name || "?"}${npu.family ? ` (${npu.family})` : ""}${npuParts.length ? ` — ${npuParts.join(", ")}` : ""}`);
+      }
+    }
+    if (sysinfo["Windows Power Setting"]) lines.push(`Power plan: ${sysinfo["Windows Power Setting"]}`);
+    const store = sysinfo.model_storage;
+    if (store && typeof store.total_bytes === "number") {
+      const free = typeof store.free_bytes === "number" ? ` (${fmtBytes(store.free_bytes)} free)` : "";
+      lines.push(
+        `Model storage: ${fmtBytes(store.used_bytes ?? 0)} used / ${fmtBytes(store.total_bytes)} total${free}`
+      );
+      if (store.path) lines.push(`  ${store.path}`);
+    }
+  } else {
+    lines.push("  (unreachable)");
+  }
+  lines.push("");
+
+  // ── /metrics ──────────────────────────────────────────────────────────
+  lines.push(sectionTitle("/metrics (llama.cpp backend)"));
+  if (metrics && metrics.size) {
+    const proc = metrics.get("lemonade_llamacpp_requests_processing");
+    const deferred = metrics.get("lemonade_llamacpp_requests_deferred");
+    const busy = metrics.get("lemonade_llamacpp_n_busy_slots_per_decode");
+    const peak = metrics.get("lemonade_llamacpp_n_tokens_max");
+    if (proc === undefined && deferred === undefined && peak === undefined) {
+      lines.push("  (no llamacpp backend metrics — no llama.cpp model loaded)");
+    } else {
+      lines.push(
+        `Queue: ${proc ?? 0} processing, ${deferred ?? 0} deferred` +
+          (busy !== undefined ? `   Busy slots/decode: ${busy.toFixed(2)}` : "")
+      );
+      if (peak !== undefined) lines.push(`Peak sequence: ${fmtTokens(peak)} tokens (largest prompt+generation observed)`);
+    }
+  } else {
+    lines.push("  (unreachable)");
+  }
+
+  return lines;
+}
+
+/** Fetch all five status endpoints and format the panel, timestamped "now". */
+async function fetchStatusLines(config: LemonadeConfig): Promise<string[]> {
+  const [h, sys, perf, info, metricsBody] = await Promise.all([
+    fetchHealth(config),
+    fetchJsonOrNull<SystemStats>(config, "/v1/system-stats"),
+    fetchJsonOrNull<PerfStats>(config, "/v1/stats"),
+    fetchJsonOrNull<SystemInfo>(config, "/v1/system-info"),
+    fetchTextOrNull(config, "/metrics"),
+  ]);
+  const metrics = metricsBody ? parsePrometheus(metricsBody) : null;
+  return formatStatus(config, h, sys, perf, info, metrics, new Date());
+}
+
+/** Run an async op with a status indicator. Returns [true, result] or
+ *  [false, error message] — a discriminated tuple, so callers can narrow. */
+async function withStatus<T>(
+  ctx: UiCtx,
+  label: string,
+  op: () => Promise<T>
+): Promise<[true, T] | [false, string]> {
+  ctx.ui.setStatus("lemonade-setup", label);
+  try {
+    return [true, await op()];
+  } catch (error) {
+    return [false, error instanceof Error ? error.message : String(error)];
+  } finally {
+    ctx.ui.setStatus("lemonade-setup", undefined);
+  }
+}
+
+/**
+ * Pull a model with live progress: server-owned download job + progress view.
+ * Falls back to a blocking pull on servers without job support.
+ */
+async function pullWithProgress(
+  ctx: UiCtx,
+  pi: ExtensionAPI,
+  config: LemonadeConfig,
+  id: string,
+  extra?: Record<string, unknown>
+): Promise<[boolean, string]> {
+  let job: DownloadJob | null = null;
+  try {
+    job = await startPullJob(config, id, extra);
+  } catch {
+    // Fallback: blocking pull (older server without download jobs)
+    return withStatus(ctx, `Pulling ${id} (blocking)…`, () => pullModelBlocking(config, id));
+  }
+  const outcome = await trackDownload(ctx, config, job.id, id);
+  if (outcome === "complete") {
+    await registerLemonadeProvider(pi, config); // model now in catalog
+    return [true, `Pulled ${id}.`];
+  }
+  if (outcome === "cancelled") {
+    return [false, `Pull of ${id} cancelled.`];
+  }
+  return [false, `Pull of ${id} failed.`];
+}
+
+/** Search Hugging Face via the lemonade server and install a model as user.* */
+async function installFromHuggingFace(ctx: UiCtx, pi: ExtensionAPI, config: LemonadeConfig): Promise<void> {
+  const query = (await ctx.ui.input("Search Hugging Face (GGUF repos):", ""))?.trim();
+  if (!query || query.length < 3) {
+    if (query) ctx.ui.notify("Search query must be at least 3 characters.", "warning");
+    return;
+  }
+
+  ctx.ui.setStatus("lemonade-setup", `Searching Hugging Face for "${query}"…`);
+  const res = await fetch(
+    url(config, `${config.registrySearchPath}?query=${encodeURIComponent(query)}&format=gguf&limit=12`),
+    { headers: authHeaders(config), signal: AbortSignal.timeout(config.discoveryTimeoutMs * 3) }
+  );
+  ctx.ui.setStatus("lemonade-setup", undefined);
+  if (!res.ok) {
+    ctx.ui.notify(`Registry search failed (HTTP ${res.status}).`, "error");
+    return;
+  }
+  const payload = (await res.json()) as { results?: RegistryResult[] };
+  const results = payload.results ?? [];
+  if (!results.length) {
+    ctx.ui.notify("No matching repositories found.", "warning");
+    return;
+  }
+
+  const repo = await menu(
+    ctx,
+    "Search Results",
+    results.map((r) => ({
+      value: r.repository_id,
+      label: r.repository_id,
+      description: [
+        r.downloads !== undefined ? `${(r.downloads / 1000).toFixed(0)}k downloads` : undefined,
+        r.likes !== undefined ? `${r.likes} likes` : undefined,
+        (r.tags ?? []).slice(0, 3).join(", "),
+      ].filter(Boolean).join(" • "),
+    }))
+  );
+  if (!repo) return;
+
+  ctx.ui.setStatus("lemonade-setup", `Inspecting ${repo}…`);
+  const varRes = await fetch(
+    url(config, `${config.pullVariantsPath}?checkpoint=${encodeURIComponent(repo)}`),
+    { headers: authHeaders(config), signal: AbortSignal.timeout(config.discoveryTimeoutMs * 4) }
+  );
+  ctx.ui.setStatus("lemonade-setup", undefined);
+  if (!varRes.ok) {
+    ctx.ui.notify(`Could not inspect variants (HTTP ${varRes.status}).`, "error");
+    return;
+  }
+  const variants = (await varRes.json()) as PullVariants;
+  if (!variants.variants?.length) {
+    ctx.ui.notify("No installable variants found for this repository.", "warning");
+    return;
+  }
+
+  const variant = await menu(
+    ctx,
+    `Variants of ${repo}`,
+    variants.variants.map((v) => ({
+      value: v.name,
+      label: v.name,
+      description: `${formatBytes(v.size_bytes)}${v.sharded ? " • sharded" : ""}`,
+    }))
+  );
+  if (!variant) return;
+  const chosen = variants.variants.find((v) => v.name === variant)!;
+
+  const modelName = `user.${variants.suggested_name ?? repo.split("/")[1]}`;
+  const vision = (variants.suggested_labels ?? []).includes("vision");
+  const ok = await ctx.ui.confirm(
+    `Install as ${modelName}?`,
+    `${repo}:${chosen.primary_file} (${formatBytes(chosen.size_bytes)})` +
+      (vision ? " • vision model (mmproj included)" : "")
+  );
+  if (!ok) return;
+
+  const extra: Record<string, unknown> = {
+    checkpoint: `${repo}:${chosen.primary_file}`,
+    recipe: variants.recipe ?? "llamacpp",
+  };
+  if (vision && variants.mmproj_files?.[0]) {
+    extra.mmproj = variants.mmproj_files[0];
+    extra.vision = true;
+  }
+
+  const [succeeded, msg] = await pullWithProgress(ctx, pi, config, modelName, extra);
+  ctx.ui.notify(msg, succeeded ? "info" : "error");
+}
+
+
+/** Interactive flow to register a new lemonade instance. Returns its name on
+ *  success, undefined otherwise. Validates the name, verifies reachability,
+ *  persists to config.servers, and registers the new provider immediately. */
+async function addInstanceFlow(
+  ctx: UiCtx,
+  pi: ExtensionAPI,
+  config: LemonadeConfig,
+  presetUrl?: string
+): Promise<string | undefined> {
+  const nameInput = (await ctx.ui.input("Instance name (lowercase letters, numbers, hyphens):", ""))?.trim();
+  if (!nameInput) return undefined;
+  if (
+    nameInput === "default" ||
+    config.servers.some((s) => s.name === nameInput) ||
+    !/^[a-z0-9][a-z0-9-]*$/.test(nameInput)
+  ) {
+    ctx.ui.notify(
+      'Invalid name — use lowercase letters/numbers/hyphens; "default" and existing instance names are reserved.',
+      "warning"
+    );
+    return undefined;
+  }
+  const urlInput = presetUrl ?? (await ctx.ui.input("Lemonade base URL:", "http://"));
+  if (urlInput === undefined) return undefined; // Esc = cancel, not "invalid URL"
+  const base = normalizeBaseUrl(urlInput.trim());
+  if (!/^https?:\/\/.+/.test(base)) {
+    ctx.ui.notify("Invalid URL.", "warning");
+    return undefined;
+  }
+  const description = (await ctx.ui.input("Description (optional, your own reminder):", ""))?.trim() ?? "";
+  const view: InstanceView = {
+    name: nameInput,
+    description,
+    isDefault: false,
+    config: { ...config, baseUrl: base },
+  };
+  ctx.ui.setStatus("lemonade-setup", `Verifying ${base}…`);
+  const health = await fetchHealth(view.config);
+  ctx.ui.setStatus("lemonade-setup", undefined);
+  if (!health) {
+    const ok = await ctx.ui.confirm(
+      "Server unreachable — add anyway?",
+      `${base} did not respond to a health check. The provider will register with an empty model list until it is reachable.`
+    );
+    if (!ok) return undefined;
+  }
+  config.servers.push({ name: nameInput, baseUrl: base, description: description || undefined });
+  saveConfig(config);
+  const [, msg] = await withStatus(ctx, "Registering providers…", () =>
+    registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered across all instances.`)
+  );
+  void msg;
+  return nameInput;
+}
+
+function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeConfig }): void {
+  pi.registerCommand("lemonade-setup", {
+    description: "Lemonade server: status, discovery, endpoints, models, tools, transcription",
+    handler: async (_args, ctx) => {
+      let activeInstance: string | null = null; // resolved at loop top (servers may be empty)
+      for (;;) {
+        const config = configRef.current;
+
+        // ── First-run wizard: no instances yet — nothing to manage. Offer
+        //    discovery or manual entry; the normal menu takes over once at
+        //    least one instance exists.
+        if (config.servers.length === 0) {
+          const pick = await menu(ctx, "🍋 Lemonade Setup — first run", [
+            { value: "discover", label: "Discover servers", description: "UDP beacon scan + HTTP fallback — finds lemonade boxes on the LAN" },
+            { value: "manual", label: "Add instance manually", description: "Pick a name, type the base URL (e.g. http://10.1.1.75:13305)" },
+            { value: "exit", label: "Exit", description: "Leave empty for now — this wizard reappears next time" },
+          ]);
+          if (!pick || pick === "exit") break; // falsy = cancelled/exit — never fall through to discover
+          if (pick === "manual") {
+            await addInstanceFlow(ctx, pi, config);
+          } else {
+            ctx.ui.setStatus("lemonade-setup", `Scanning UDP beacons (${config.beaconTimeoutMs / 1000}s)…`);
+            let servers = await discoverViaBeacon(config, config.beaconTimeoutMs);
+            ctx.ui.setStatus("lemonade-setup", undefined);
+            if (!servers.length) {
+              ctx.ui.setStatus("lemonade-setup", "No beacons — probing known hosts/ports…");
+              servers = await discoverViaHttp(config);
+              ctx.ui.setStatus("lemonade-setup", undefined);
+            }
+            if (!servers.length) {
+              ctx.ui.notify(
+                "No lemonade servers found. Note: UDP broadcasts don't reach into WSL2 — add the instance manually, " +
+                  "or run discovery from the Windows side.",
+                "warning"
+              );
+              continue;
+            }
+            const picked = await menu(
+              ctx,
+              "Discovered Servers",
+              servers.map((s) => ({ value: s.baseUrl, label: `${s.hostname} — ${s.baseUrl}` }))
+            );
+            if (picked) await addInstanceFlow(ctx, pi, config, picked);
+          }
+          continue;
+        }
+
+        if (activeInstance === null || !config.servers.some((s) => s.name === activeInstance)) {
+          activeInstance = config.servers[0].name; // servers[0] IS the default
+        }
+        // Config view of the active instance — status/models/logs act on it.
+        const viewOrErr = instanceView(config, activeInstance);
+        if (typeof viewOrErr === "string") {
+          activeInstance = configRef.current.servers[0].name; // instance was removed/renamed mid-session
+          continue;
+        }
+        const iconfig = viewOrErr;
+        const choice = await menu(ctx, "🍋 Lemonade Setup", [
+          { value: "status", label: "Server status", description: `Live health + host + perf from ${iconfig.baseUrl}` },
+          { value: "server", label: "Server settings", description: "Discover, base URL, API key, instances, connection test" },
+          { value: "models", label: "Model management", description: `List, load, unload, pull (progress+cancel), delete, change-ctx, HF install, filter, refresh — active instance: ${activeInstance}` },
+          { value: "transcription", label: "Transcription settings", description: "Whisper model, paths, smoke test" },
+          { value: "logs", label: "Live server logs", description: "Stream the server's log over websocket" },
+          { value: "instance", label: "Switch instance", description: `Current: ${activeInstance} — pick which box status/models/logs act on` },
+          { value: "exit", label: "Exit", description: "Close the setup menu" },
+        ]);
+        if (choice === null || choice === "exit") break;
+
+        // ── Switch instance ─────────────────────────────────────────────
+        if (choice === "instance") {
+          const picked = await menu(
+            ctx,
+            "Active Instance",
+            listInstances(config).map((v) => ({
+              value: v.name,
+              label: `${v.name}${v.isDefault ? " (default)" : ""}`,
+              description: [v.config.baseUrl, v.description].filter(Boolean).join(" — "),
+            }))
+          );
+          if (picked) activeInstance = picked;
+          continue;
+        }
+
+        // ── Live logs ────────────────────────────────────────────────
+        if (choice === "logs") {
+          await liveLogsView(ctx, iconfig);
+          continue;
+        }
+
+        // ── Status ────────────────────────────────────────────────────────
+        // Live panel: polls every statusPollMs while open, and n/p cycles
+        // through every configured instance without leaving the view.
+        if (choice === "status") {
+          const instances = config.servers;
+          let idx = Math.max(0, instances.findIndex((s) => s.name === activeInstance));
+          const cfgFor = (): LemonadeConfig => {
+            const view = instanceView(configRef.current, instances[idx]?.name ?? activeInstance);
+            return typeof view === "string" ? iconfig : view; // stale name → keep the menu's view
+          };
+          ctx.ui.setStatus("lemonade-setup", "Contacting server…");
+          const first = await fetchStatusLines(cfgFor());
+          ctx.ui.setStatus("lemonade-setup", undefined);
+          await textView(
+            ctx,
+            `Server Status — ${instances[idx]?.name ?? activeInstance}`,
+            first,
+            true,
+            {
+              pollMs: config.statusPollMs,
+              refetch: config.statusPollMs > 0 ? () => fetchStatusLines(cfgFor()) : undefined,
+              extraHint: instances.length > 1 ? "n/p instance" : undefined,
+              onKey:
+                instances.length > 1
+                  ? (data, api) => {
+                      if (matchesKey(data, "n")) idx = (idx + 1) % instances.length;
+                      else if (matchesKey(data, "p")) idx = (idx - 1 + instances.length) % instances.length;
+                      else return false;
+                      const name = instances[idx]?.name ?? activeInstance;
+                      api.setTitle(`Server Status — ${name}`);
+                      return true;
+                    }
+                  : undefined,
+            }
+          );
+          // The panel was the last thing the user looked at — the menu follows it.
+          const lastName = instances[idx]?.name;
+          if (lastName) activeInstance = lastName;
+          continue;
+        }
+
+        // ── Server settings ──────────────────────────────────────────────
+        if (choice === "server") {
+          for (;;) {
+            const sub = await menu(ctx, "Server Settings", [
+              { value: "discover", label: "Discover servers", description: "UDP beacon scan + HTTP fallback" },
+              { value: "instances", label: "Manage instances", description: `${config.servers.length} instance(s) — servers[0] is the default` },
+              { value: "baseurl", label: "Edit default instance base URL", description: `Current: ${config.servers[0].baseUrl}` },
+              { value: "apikey", label: "Edit shared API key", description: `Fallback for instances without their own — ${config.apiKey ? "••••• (set)" : "(none)"}` },
+              { value: "test", label: "Test connection", description: "Ping the health endpoint" },
+              { value: "back", label: "Back", description: "" },
+            ]);
+            if (sub === null || sub === "back") break;
+
+            if (sub === "discover") {
+              ctx.ui.setStatus("lemonade-setup", `Scanning UDP beacons (${config.beaconTimeoutMs / 1000}s)…`);
+              let servers = await discoverViaBeacon(config, config.beaconTimeoutMs);
+              ctx.ui.setStatus("lemonade-setup", undefined);
+              if (!servers.length) {
+                ctx.ui.setStatus("lemonade-setup", "No beacons — probing known hosts/ports…");
+                servers = await discoverViaHttp(config);
+                ctx.ui.setStatus("lemonade-setup", undefined);
+              }
+              if (!servers.length) {
+                ctx.ui.notify(
+                  "No lemonade servers found. Note: UDP LAN broadcasts don't reach into WSL2 — " +
+                    "set the URL manually, or run discovery on the Windows side.",
+                  "warning"
+                );
+                continue;
+              }
+              const picked = await menu(
+                ctx,
+                "Discovered Servers",
+                servers.map((s) => ({
+                  value: s.baseUrl,
+                  label: `${s.hostname} — ${s.baseUrl}`,
+                }))
+              );
+              if (picked) {
+                if (picked === config.servers[0].baseUrl) {
+                  ctx.ui.notify("That is already the default instance.", "info");
+                  continue;
+                }
+                const use = await menu(
+                  ctx,
+                  `Use ${picked}`,
+                  [
+                    { value: "default", label: "Set as default instance", description: "Replaces the current default" },
+                    { value: "instance", label: "Add as named instance", description: "Keeps the default; registers as lemonade-<name>" },
+                    { value: "back", label: "Cancel", description: "" },
+                  ]
+                );
+                if (use === "default") {
+                  config.servers[0].baseUrl = picked;
+                  saveConfig(config);
+                  const [ok, msg] = await withStatus(ctx, "Re-registering providers…", () =>
+                    registerLemonadeProvider(pi, config).then((n) => `Connected — ${n} model(s) registered.`)
+                  );
+                  ctx.ui.notify(msg, ok ? "info" : "error");
+                } else if (use === "instance") {
+                  const added = await addInstanceFlow(ctx, pi, config, picked);
+                  if (added) ctx.ui.notify(`Instance "${added}" added — provider lemonade-${added} registered.`, "info");
+                }
+              }
+            } else if (sub === "instances") {
+              for (;;) {
+                const op = await menu(ctx, "Manage Instances", [
+                  { value: "list", label: "List instances", description: "Names, URLs, descriptions, live reachability" },
+                  { value: "edit", label: "Edit instance", description: "Rename, re-describe, re-point, or re-key an instance" },
+                  { value: "add", label: "Add instance", description: "Register another lemonade box as lemonade-<name>" },
+                  ...(config.servers.length > 1
+                    ? [
+                        { value: "makedefault", label: "Make default", description: "Move an instance to the front — servers[0] is the default" },
+                        { value: "remove", label: "Remove instance", description: "Unregister an instance (the last one cannot be removed)" },
+                      ]
+                    : []),
+                  { value: "back", label: "Back", description: "" },
+                ]);
+                if (op === null || op === "back") break;
+
+                if (op === "list") {
+                  const lines: string[] = [];
+                  for (const v of listInstances(config)) {
+                    const h = await fetchHealth(v.config);
+                    lines.push(
+                      `${v.name}${v.isDefault ? " (default)" : ""} — ${v.config.baseUrl} — ` +
+                        (h ? `ok (v${h.version ?? "?"}, ${h.all_models_loaded?.length ?? 0} loaded)` : "unreachable")
+                    );
+                    if (v.description) lines.push(`    ${v.description}`);
+                  }
+                  await textView(ctx, "Instances", lines, true);
+                } else if (op === "edit") {
+                  const views = listInstances(config);
+                  const target = await menu(
+                    ctx,
+                    "Edit Instance",
+                    views.map((v) => ({
+                      value: v.name,
+                      label: `${v.name}${v.isDefault ? " (default)" : ""}`,
+                      description: [v.config.baseUrl, v.description].filter(Boolean).join(" — "),
+                    }))
+                  );
+                  if (!target) continue;
+                  const view = views.find((v) => v.name === target)!;
+                  const entry = config.servers.find((x) => x.name === target)!;
+
+                  for (;;) {
+                    const field = await menu(ctx, `Edit ${target}`, [
+                      { value: "description", label: "Edit description", description: view.description ? `Current: ${view.description.slice(0, 60)}` : "(none set)" },
+                      { value: "name", label: "Edit name", description: `Current: ${view.name}` },
+                      { value: "url", label: "Edit base URL", description: `Current: ${entry.baseUrl}` },
+                      { value: "apikey", label: "Edit API key", description: entry.apiKey ? "Current: ••••• (own key)" : "Current: (inherits the shared key)" },
+                      { value: "back", label: "Back", description: "" },
+                    ]);
+                    if (field === null || field === "back") break;
+
+                    if (field === "description") {
+                      const input = await ctx.ui.input(
+                        "Description (your own reminder's sake, shown in this menu):",
+                        view.description
+                      );
+                      if (input !== undefined) {
+                        entry.description = input.trim() || undefined;
+                        saveConfig(config);
+                        ctx.ui.notify("Description saved.", "info");
+                      }
+                    } else if (field === "name") {
+                      const input = (await ctx.ui.input("New name (lowercase letters, numbers, hyphens):", view.name))?.trim();
+                      if (!input || input === view.name) continue;
+                      const others = [
+                        "default",
+                        ...config.servers.filter((x) => x.name !== target).map((x) => x.name),
+                      ];
+                      if (others.includes(input) || !/^[a-z0-9][a-z0-9-]*$/.test(input)) {
+                        ctx.ui.notify("Invalid or duplicate name.", "warning");
+                        continue;
+                      }
+                      // Uniform ids: renaming changes the provider id too —
+                      // unregister the old one before re-registering.
+                      try {
+                        pi.unregisterProvider(`lemonade-${target}`);
+                      } catch { /* not registered */ }
+                      entry.name = input;
+                      if (activeInstance === target) activeInstance = input;
+                      saveConfig(config);
+                      const [, msg] = await withStatus(ctx, "Re-registering providers…", () =>
+                        registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered.`)
+                      );
+                      void msg;
+                      ctx.ui.notify(`Renamed to "${input}".`, "info");
+                      break; // menu keys changed; leave the edit loop
+                    } else if (field === "url") {
+                      const input = (await ctx.ui.input("New base URL:", entry.baseUrl))?.trim();
+                      const base = normalizeBaseUrl(input ?? "");
+                      if (!/^https?:\/\//.test(base)) {
+                        ctx.ui.notify("Invalid URL.", "warning");
+                        continue;
+                      }
+                      entry.baseUrl = base;
+                      saveConfig(config);
+                      const [, msg] = await withStatus(ctx, "Re-registering providers…", () =>
+                        registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered.`)
+                      );
+                      void msg;
+                      ctx.ui.notify("URL saved.", "info");
+                    } else if (field === "apikey") {
+                      const input = (await ctx.ui.input("Instance API key (empty = inherit the shared key):", entry.apiKey ?? ""))?.trim();
+                      if (input !== undefined) {
+                        entry.apiKey = input || undefined;
+                        saveConfig(config);
+                        const [, msg] = await withStatus(ctx, "Re-registering providers…", () =>
+                          registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered.`)
+                        );
+                        void msg;
+                        ctx.ui.notify(input ? "API key saved." : "API key cleared — instance inherits the shared key.", "info");
+                      }
+                    }
+                  }
+                } else if (op === "add") {
+                  const added = await addInstanceFlow(ctx, pi, config);
+                  if (added) ctx.ui.notify(`Instance "${added}" added — provider lemonade-${added} registered.`, "info");
+                } else if (op === "remove") {
+                  const victim = await menu(
+                    ctx,
+                    "Remove Instance",
+                    config.servers.map((s) => ({
+                      value: s.name,
+                      label: `${s.name}${s.name === config.servers[0].name ? " (default)" : ""}`,
+                      description: s.baseUrl,
+                    }))
+                  );
+                  if (!victim) continue;
+                  const wasDefault = victim === config.servers[0].name;
+                  const ok = await ctx.ui.confirm(
+                    `Remove instance ${victim}?`,
+                    `Unregisters the lemonade-${victim} provider. Files on that box are untouched.` +
+                      (wasDefault ? " It is the DEFAULT — the next instance in the list becomes the default." : "")
+                  );
+                  if (!ok) continue;
+                  config.servers = config.servers.filter((x) => x.name !== victim);
+                  saveConfig(config);
+                  if (activeInstance === victim) activeInstance = config.servers[0].name;
+                  try {
+                    pi.unregisterProvider(`lemonade-${victim}`);
+                  } catch { /* not registered */ }
+                  const [rok, rmsg] = await withStatus(ctx, "Re-registering providers…", () =>
+                    registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered.`)
+                  );
+                  ctx.ui.notify(rmsg, rok ? "info" : "error");
+                } else if (op === "makedefault") {
+                  const pick = await menu(
+                    ctx,
+                    "Make Default",
+                    config.servers.slice(1).map((s) => ({
+                      value: s.name,
+                      label: s.name,
+                      description: [s.baseUrl, s.description].filter(Boolean).join(" — "),
+                    }))
+                  );
+                  if (!pick) continue;
+                  const idx = config.servers.findIndex((x) => x.name === pick);
+                  const [entry] = config.servers.splice(idx, 1);
+                  config.servers.unshift(entry);
+                  saveConfig(config);
+                  // Provider ids are lemonade-<name>, unchanged by reordering —
+                  // no re-registration needed; only defaultness moved.
+                  ctx.ui.notify(`"${pick}" is now the default instance (servers[0]).`, "info");
+                }
+              }
+            } else if (sub === "baseurl") {
+              const input = await ctx.ui.input("Default instance base URL:", config.servers[0].baseUrl);
+              if (input !== undefined && input.trim()) {
+                config.servers[0].baseUrl = normalizeBaseUrl(input);
+                saveConfig(config);
+                const [ok, msg] = await withStatus(ctx, "Re-registering provider…", () =>
+                  registerLemonadeProvider(pi, config).then((n) => `Saved — ${n} model(s) registered.`)
+                );
+                ctx.ui.notify(msg, ok ? "info" : "error");
+              }
+            } else if (sub === "apikey") {
+              const input = await ctx.ui.input("Shared API key (instances without their own inherit it; empty for none):", config.apiKey);
+              if (input !== undefined) {
+                config.apiKey = input.trim();
+                saveConfig(config);
+                ctx.ui.notify("API key saved.", "info");
+              }
+            } else if (sub === "test") {
+              const h = await fetchHealth(iconfig);
+              ctx.ui.notify(
+                h
+                  ? `OK — ${h.status ?? "?"} v${h.version ?? "?"}, ${h.all_models_loaded?.length ?? 0} model(s) loaded`
+                  : `Failed to reach ${iconfig.baseUrl}`,
+                h ? "info" : "error"
+              );
+            }
+          }
+          continue;
+        }
+
+        // ── Model management ──────────────────────────────────────────────
+        if (choice === "models") {
+          for (;;) {
+            const sub = await menu(ctx, "Model Management", [
+              { value: "list", label: "List catalog", description: "All advertised models + live state" },
+              { value: "load", label: "Load a model", description: "Load into memory (may take minutes)" },
+              { value: "unload", label: "Unload a model", description: "Free its slot" },
+              { value: "pull", label: "Pull (download) a model", description: "Live progress, esc to cancel" },
+              { value: "installhf", label: "Install from Hugging Face", description: "Search HF, pick a variant, install as user.*" },
+              { value: "delete", label: "Delete a model", description: "Typed-phrase confirmation required" },
+              { value: "changectx", label: "Change context size", description: "Unload → reload with new ctx (saved)" },
+              {
+                value: "chatonly",
+                label: "Toggle chat-only filter",
+                description: `Currently: ${config.chatOnly ? "chat models only" : "all models"}`,
+              },
+              { value: "refresh", label: "Refresh provider", description: "Re-discover and re-register in /model" },
+              { value: "back", label: "Back", description: "" },
+            ]);
+            if (sub === null || sub === "back") break;
+
+            if (sub === "installhf") {
+              await installFromHuggingFace(ctx, pi, iconfig);
+              continue;
+            }
+
+            if (sub === "chatonly") {
+              config.chatOnly = !config.chatOnly;
+              saveConfig(config);
+              const [ok, msg] = await withStatus(ctx, "Re-registering…", () =>
+                registerLemonadeProvider(pi, config).then((n) => `Filter ${config.chatOnly ? "on" : "off"} — ${n} model(s) registered.`)
+              );
+              ctx.ui.notify(msg, ok ? "info" : "error");
+              continue;
+            }
+            if (sub === "refresh") {
+              const [ok, msg] = await withStatus(ctx, "Refreshing…", () =>
+                registerLemonadeProvider(pi, config).then((n) => `Provider refreshed — ${n} model(s) registered.`)
+              );
+              ctx.ui.notify(msg, ok ? "info" : "error");
+              continue;
+            }
+
+            // Everything else needs the live catalog. show_all=true includes
+            // not-yet-downloaded registry entries (pull candidates).
+            let catalog: LemonadeModel[];
+            let loadedIds = new Set<string>();
+            let loadedCtx = new Map<string, number>();
+            try {
+              const health = await fetchHealth(iconfig);
+              loadedIds = new Set((health?.all_models_loaded ?? []).map((m) => m.model_name));
+              for (const m of health?.all_models_loaded ?? []) {
+                if (m.max_context_window) loadedCtx.set(m.model_name, m.max_context_window);
+              }
+              catalog = await fetchCatalog(iconfig, true);
+            } catch (error) {
+              ctx.ui.notify(`Could not reach server: ${error instanceof Error ? error.message : error}`, "error");
+              continue;
+            }
+
+            if (sub === "list") {
+              const lines: string[] = [`Catalog: ${catalog.length} model(s), ${loadedIds.size} loaded`, ""];
+              for (const m of catalog) {
+                const state = loadedIds.has(m.id) ? "● loaded" : "○ on-demand";
+                lines.push(
+                  `${state}  ${m.id}` +
+                    (m.labels?.length ? `  [${m.labels.join(", ")}]` : "") +
+                    (m.downloaded === false ? "  (not downloaded)" : "") +
+                    (m.max_context_window ? `  ctx ${m.max_context_window}` : "") +
+                    (m.size ? `  ${m.size} GB` : "")
+                );
+              }
+              await textView(ctx, "Model Catalog", lines, true);
+              continue;
+            }
+
+            if (sub === "changectx") {
+              if (!loadedIds.size) {
+                ctx.ui.notify("Nothing is loaded — load a model first.", "warning");
+                continue;
+              }
+              const picked = await menu(ctx, "Change Context Size (pick model)", [...loadedIds].map((id) => ({
+                value: id,
+                label: id,
+              })));
+              if (!picked) continue;
+              const currentCtx =
+                loadedCtx.get(picked) ??
+                catalog.find((m) => m.id === picked)?.max_context_window ??
+                32768;
+              const input = await ctx.ui.input(
+                `New context size (current: ${currentCtx}; e.g. 32k, 1m, or raw tokens):`,
+                String(currentCtx)
+              );
+              const ctxSize = input ? parseCtxSize(input) : null;
+              if (!ctxSize) {
+                ctx.ui.notify("Invalid size — use e.g. 32k, 1m, or 262144.", "warning");
+                continue;
+              }
+              const ok = await ctx.ui.confirm(
+                "Unload and reload?",
+                `${picked} will be unloaded and reloaded with ctx ${ctxSize} (saved for future loads).`
+              );
+              if (!ok) continue;
+              const [succeeded, msg] = await withStatus(ctx, `Reloading ${picked} with ctx ${ctxSize}…`, () =>
+                changeModelContext(iconfig, picked, ctxSize)
+              );
+              ctx.ui.notify(msg, succeeded ? "info" : "error");
+              if (succeeded) await registerLemonadeProvider(pi, config);
+              continue;
+            }
+
+            if (sub === "pull" || sub === "delete") {
+              const predicate = sub === "delete"
+                ? (m: LemonadeModel) => m.downloaded !== false
+                : (m: LemonadeModel) => m.downloaded === false;
+              const candidates = catalog.filter(predicate);
+
+              let picked: string | null = null;
+              if (candidates.length) {
+                picked = await menu(
+                  ctx,
+                  sub === "pull" ? "Pull (download)" : "Delete from disk",
+                  candidates.map((m) => ({
+                    value: m.id,
+                    label: m.id,
+                    description: [
+                      loadedIds.has(m.id) ? "loaded" : undefined,
+                      m.size ? `${m.size} GB` : undefined,
+                      m.recipe,
+                    ].filter(Boolean).join(" • "),
+                  }))
+                );
+              } else {
+                const input = await ctx.ui.input(
+                  sub === "pull"
+                    ? "No undownloaded models in catalog. Enter a model id to pull:"
+                    : "Enter a model id to delete:",
+                  ""
+                );
+                picked = input?.trim() || null;
+              }
+              if (!picked) continue;
+
+              if (sub === "pull") {
+                const size = catalog.find((m) => m.id === picked)?.size;
+                const ok = await ctx.ui.confirm(
+                  `Pull ${picked}?`,
+                  size ? `Downloads ~${size} GB to the server's disk.` : "Downloads the model to the server's disk."
+                );
+                if (!ok) continue;
+                const [succeeded, msg] = await pullWithProgress(ctx, pi, iconfig, picked!);
+                ctx.ui.notify(msg, succeeded ? "info" : "error");
+                continue;
+              }
+
+              // delete: confirm + typed phrase, 3 attempts
+              const ok = await ctx.ui.confirm(
+                `Delete ${picked}?`,
+                "This permanently removes the model files from the server's disk. Load state and cache are also lost."
+              );
+              if (!ok) continue;
+              const phrase = `i want to delete ${picked.toLowerCase()}`;
+              let confirmed = false;
+              for (let attempt = 1; attempt <= 3 && !confirmed; attempt++) {
+                const chancesLeft = 4 - attempt;
+                const typed = await ctx.ui.input(
+                  `Type "${phrase}" (${chancesLeft} chance${chancesLeft === 1 ? "" : "s"} left):`,
+                  ""
+                );
+                if (typed === undefined) break; // Esc = abort immediately
+                if (typed.trim().toLowerCase().replace(/\s+/g, " ") === phrase) {
+                  confirmed = true;
+                } else if (attempt < 3) {
+                  ctx.ui.notify("Phrase did not match.", "warning");
+                }
+              }
+              if (!confirmed) {
+                ctx.ui.notify(`Deletion of ${picked} aborted.`, "warning");
+                continue;
+              }
+              const [succeeded, msg] = await withStatus(ctx, `Deleting ${picked}…`, () =>
+                deleteModel(iconfig, picked!)
+              );
+              ctx.ui.notify(msg, succeeded ? "info" : "error");
+              if (succeeded) await registerLemonadeProvider(pi, config);
+              continue;
+            }
+
+            // load / unload
+            {
+              const candidates =
+                sub === "unload"
+                  ? [...loadedIds]
+                  : catalog.map((m) => m.id).filter((id) => !loadedIds.has(id));
+              if (!candidates.length) {
+                ctx.ui.notify(sub === "unload" ? "Nothing is loaded." : "Everything is already loaded.", "warning");
+                continue;
+              }
+              const picked = await menu(
+                ctx,
+                sub === "load" ? "Load model" : "Unload model",
+                candidates.map((id) => ({
+                  value: id,
+                  label: id,
+                  description: loadedIds.has(id) ? "loaded" : "on-demand",
+                }))
+              );
+              if (!picked) continue;
+              const [succeeded, msg] = await withStatus(ctx, `${sub === "load" ? "Loading" : "Unloading"} ${picked}…`, () =>
+                sub === "load" ? loadModel(iconfig, picked) : unloadModel(iconfig, picked).then(() => `Unloaded ${picked}.`)
+              );
+              ctx.ui.notify(msg, succeeded ? "info" : "error");
+              if (succeeded) await registerLemonadeProvider(pi, config);
+            }
+          }
+          continue;
+        }
+
+        // ── Transcription settings ────────────────────────────────────────
+        if (choice === "transcription") {
+          for (;;) {
+            const sub = await menu(ctx, "Transcription Settings", [
+              {
+                value: "model",
+                label: "Default transcription model",
+                description: `Current: ${config.defaultTranscriptionModel}`,
+              },
+              {
+                value: "transpath",
+                label: "Transcription endpoint path",
+                description: `Current: ${config.transcriptionPath}`,
+              },
+              { value: "test", label: "Smoke test", description: "Transcribe a file of your choosing" },
+              { value: "back", label: "Back", description: "" },
+            ]);
+            if (sub === null || sub === "back") break;
+
+            if (sub === "model" || sub === "transpath") {
+              const input = await ctx.ui.input(
+                sub === "model" ? "Transcription model id:" : "Transcription endpoint path:",
+                sub === "model" ? config.defaultTranscriptionModel : config.transcriptionPath
+              );
+              if (input !== undefined && input.trim()) {
+                if (sub === "model") config.defaultTranscriptionModel = input.trim();
+                else config.transcriptionPath = input.trim();
+                saveConfig(config);
+                ctx.ui.notify("Saved.", "info");
+              }
+            } else if (sub === "test") {
+              const file = await ctx.ui.input("Path to an audio/video file:", "");
+              if (!file?.trim()) continue;
+              const resolved = path.resolve(file.trim());
+              // Same code path as the transcribe_audio tool (transcribeViaServer),
+              // acting on the menu's active instance.
+              const [succeeded, result] = await withStatus(ctx, `Transcribing ${path.basename(resolved)}…`, () =>
+                transcribeViaServer(iconfig, resolved)
+              );
+              if (!succeeded) {
+                ctx.ui.notify(result, "error");
+              } else {
+                await textView(
+                  ctx,
+                  "Transcription Result",
+                  [`File: ${resolved}`, `Model: ${result.model}`, "", result.text || "(empty)"],
+                  true
+                );
+              }
+            }
+          }
+        }
+      }
+    },
+  });
+}
+
+// ─── Extension entry ────────────────────────────────────────────────────────
+
+export default async function piLemonadeLink(pi: ExtensionAPI): Promise<void> {
+  // The config file is REQUIRED — nothing is hardcoded, not even a default
+  // server, because a config-less run would silently target a server that
+  // isn't yours. On failure we do two things, belt and braces: register a
+  // session_start handler that shows a red error banner in the chat window,
+  // and throw so pi logs the extension load failure. (The throw is in case
+  // pi drops handlers registered by an extension that fails during load;
+  // if it keeps them, the user sees the reason twice — loudly, both times.)
+  let config: LemonadeConfig;
+  try {
+    ensureConfigFile(); // first run: create a blank starter config instead of blocking
+    config = loadConfig();
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    const failure = [
+      "pi-lemonade-link did NOT load — no lemonade providers, tools, or /lemonade-setup are registered.",
+      "",
+      `Reason: ${reason}`,
+      "",
+      `Everything (base URL, endpoints, defaults) is config-driven from ${CONFIG_PATH} — nothing is hardcoded.`,
+      "To set it up, copy the fully-commented example into your pi agent dir and edit it for your server:",
+      "",
+      "  cp ~/.pi/agent/extensions/pi-lemonade-link/lemonade.example.json ~/.pi/agent/lemonade.json",
+      "",
+      'A minimal config is enough to start:  { "servers": [{ "name": "main", "baseUrl": "http://your-lemonade-server:13305" }] }',
+    ].join("\n");
+    pi.on("session_start", async (_event, ctx) => {
+      if (ctx.hasUI) ctx.ui.notify(failure, "error");
+    });
+    throw new Error(failure);
+  }
+  const configRef = { current: config };
+  // No startup save: the config file is user-authored and may carry JSONC
+  // comments, and rewriting it here would strip them. Missing keys are
+  // merged from DEFAULT_CONFIG in memory; /lemonade-setup persists the full
+  // normalized object when the user actually changes something.
+
+  await registerLemonadeProvider(pi, configRef.current);
+  await registerAgentTools(pi, configRef.current);
+  registerLemonadeBar(pi, configRef);
+  registerSetupCommand(pi, configRef);
+
+  // Fresh install (or a hand-emptied config): nothing is registered yet —
+  // point the user at the wizard instead of leaving them wondering why
+  // /model has no lemonade entries.
+  if (configRef.current.servers.length === 0) {
+    pi.on("session_start", (_event, ctx) => {
+      if (ctx.hasUI)
+        ctx.ui.notify(
+          "pi-lemonade-link: no servers configured yet — run /lemonade-setup to discover or add your lemonade box " +
+            "(or edit ~/.pi/agent/lemonade.json and /reload).",
+          "info"
+        );
+    });
+  }
+}