pi-lemonade-link 1.0.2 → 2.0.0

package/index.ts

@@ -9,24 +9,30 @@
  *      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.
+ *      vary_image, upscale_image, text_to_speech (incl. voice cloning and
+ *      voice design), 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).
+ *      configuration, server discovery, and administration: a live model
+ *      browser (inline status, type-to-search, contextual actions, animated
+ *      busy markers with esc-to-detach), download-job management (terminal
+ *      jobs auto-removed), a recipe-options editor (per-model ctx/backend/
+ *      args, saved without loading), pin/unpin, model updates (check + bulk
+ *      sync or per-model pull), recipe-backend installs with live progress,
+ *      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.
+ *      messages, plus polled busy/queue, whole-box active requests + live
+ *      tok/s, 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.
+ *      no blocking 30-minute waits. Errored/cancelled jobs are removed from
+ *      the server's list when the view closes (the spec keeps them until a
+ *      client does). 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
@@ -38,7 +44,7 @@
  * 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).
+ * Endpoints confirmed against lemonade 2026.46.2 (see README for full list).
  */
 
 import * as fs from "node:fs";
@@ -81,6 +87,24 @@ interface LemonadeConfig {
   audioGenerationPath: string;
   mesh3dPath: string;
   classifyPath: string;
+  /** LEMONADE_ADMIN_API_KEY — required by /internal/* endpoints (pin, model
+   *  sync, config) on servers that set one. Empty = fall back to apiKey. */
+  adminApiKey: string;
+  /** Per-model recipe options: read/save/reset without loading. `{id}` is
+   *  replaced with the model id. */
+  modelOptionsPath: string;
+  /** Check downloaded models for newer registry commits (no download). */
+  checkUpdatesPath: string;
+  /** Pin/unpin a loaded model without reloading it (admin). */
+  pinPath: string;
+  /** Bulk model-update sync — check + download in one job (admin). */
+  modelSyncPath: string;
+  /** Install/update a recipe backend (or register a cloud provider). */
+  installPath: string;
+  /** Resolve backend install metadata without downloading. */
+  installDryRunPath: string;
+  /** Remove a backend or cloud provider registration. */
+  uninstallPath: string;
   beaconPort: number;
   chatOnly: boolean;
   defaultTranscriptionModel: string;
@@ -108,6 +132,11 @@ interface LemonadeConfig {
   // info notice, deduplicated to once per (instance, new release) — the
   // TUI always shows the live truth. Separately toggleable; default on.
   upstreamVersionCheck: boolean;
+  // Outage cache: when a probe can't reach an instance, register its last
+  // good catalog (persisted on every successful probe) instead of nothing —
+  // provenance-marked "(cached <time>)" in /model, warned at session start,
+  // and re-synced with a diff notice once the box answers again.
+  cacheOnOutage: boolean;
   discoveryTimeoutMs: number;
   beaconTimeoutMs: number;
   loadTimeoutMs: number;
@@ -126,6 +155,7 @@ 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
+  adminApiKey?: string; // falls back to the top-level adminApiKey, then the apiKey
   description?: string; // free-form context for the user's own reminder's sake
 }
 
@@ -154,8 +184,17 @@ const DEFAULT_CONFIG: LemonadeConfig = {
   audioGenerationPath: "/v1/audio/generations",
   mesh3dPath: "/v1/3d/generations",
   classifyPath: "/v1/classify",
+  adminApiKey: "", // empty = use apiKey for admin endpoints too
+  modelOptionsPath: "/v1/models/{id}/options",
+  checkUpdatesPath: "/v1/models/check-updates",
+  pinPath: "/internal/pin",
+  modelSyncPath: "/internal/models/sync",
+  installPath: "/v1/install",
+  installDryRunPath: "/v1/install/dry-run",
+  uninstallPath: "/v1/uninstall",
   beaconPort: 13305,
   chatOnly: true,
+  cacheOnOutage: false,
   defaultTranscriptionModel: "Whisper-Large-v3",
   defaultImageModel: "",
   defaultUpscaleModel: "RealESRGAN-x4plus",
@@ -309,7 +348,12 @@ function listInstances(config: LemonadeConfig): InstanceView[] {
     name: s.name,
     description: s.description ?? "",
     isDefault: i === 0,
-    config: { ...config, baseUrl: s.baseUrl, apiKey: s.apiKey || config.apiKey },
+    config: {
+      ...config,
+      baseUrl: s.baseUrl,
+      apiKey: s.apiKey || config.apiKey,
+      adminApiKey: s.adminApiKey || config.adminApiKey || s.apiKey || config.apiKey,
+    },
   }));
 }
 
@@ -323,7 +367,12 @@ function instanceView(config: LemonadeConfig, name?: string): LemonadeConfig | s
   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 };
+  return {
+    ...config,
+    baseUrl: target.baseUrl,
+    apiKey: target.apiKey || config.apiKey,
+    adminApiKey: target.adminApiKey || config.adminApiKey || target.apiKey || config.apiKey,
+  };
 }
 
 /** pi provider id for an instance — uniformly `lemonade-<name>` for EVERY
@@ -343,6 +392,22 @@ interface LemonadeModel {
   size?: number;
   downloaded?: boolean;
   max_context_window?: number;
+  /** Tokens the model handles in one request: loaded/configured ctx_size,
+   *  else max_context_window; more current than max_context_window alone. */
+  context_length?: number;
+  /** Whether the model's registry has a newer commit than the local copy. */
+  update_available?: boolean;
+  /** Whether the model is recommended for general use. */
+  suggested?: boolean;
+  checkpoint?: string;
+  /** Every checkpoint by role (main, mmproj, vae, …). */
+  checkpoints?: Record<string, string>;
+  /** The model's own options: registry defaults with saved recipe_options on top. */
+  recipe_options?: Record<string, unknown>;
+  /** One entry per checkpoint slot: present/required/registry — an
+   *  optional checkpoint (npu_cache, voicegen, …) can be missing without
+   *  blocking loads. */
+  checkpoint_status?: Array<{ type?: string; present?: boolean; required?: boolean; registry?: string }>;
 }
 
 interface LoadedModelInfo {
@@ -363,6 +428,8 @@ interface LoadedModelInfo {
   slot_pool?: string;
   residency_class?: string;
   watchdog_reset?: boolean;
+  watchdog_reset_reason?: string;
+  launch_command?: Array<string | number>;
 }
 
 interface LemonadeHealth {
@@ -375,6 +442,14 @@ interface LemonadeHealth {
   pinned_models?: Record<string, number>;
   pinned_helper_models?: Record<string, number>;
   telemetry?: { enabled?: boolean; captures?: string[] };
+  /** Rises whenever the model list changes (downloaded/update_available
+   *  flip) — a polling client re-reads /v1/models when it moves. */
+  models_generation?: number;
+  /** The model sync in flight, if any (status/sync_id/completed_sync_id). */
+  model_sync?: { status?: string; sync_id?: number; completed_sync_id?: number };
+  /** Whether the startup model-update check has finished — until then,
+   *  per-model update_available flags can be incomplete. */
+  update_check_done?: boolean;
 }
 
 interface SystemStats {
@@ -383,6 +458,18 @@ interface SystemStats {
   gpu_percent?: number | null;
   vram_gb?: number | null;
   npu_percent?: number | null;
+  /** Per-GPU detail when the host reports more than one (id, name,
+   *  memory_total_gb/memory_used_gb, memory_type, vendor). */
+  gpus?: Array<{
+    id?: string;
+    name?: string;
+    gpu_percent?: number;
+    memory_total_gb?: number;
+    memory_used_gb?: number;
+    memory_type?: string;
+    vendor?: string;
+  }>;
+  primary_gpu_id?: string;
 }
 
 interface PerfStats {
@@ -391,6 +478,10 @@ interface PerfStats {
   input_tokens?: number;
   output_tokens?: number;
   prompt_tokens?: number | null;
+  /** Whole-box liveness (≥2026.46): requests in flight right now, and the
+   *  server's own live throughput estimate across ALL clients — complements
+   *  this session's own tok/s, which is timed locally from message events. */
+  live?: { active_requests?: number; estimated_tokens_per_second?: number };
   cache_tokens?: number | null;
   request_count_total?: number;
   input_tokens_total?: number;
@@ -417,13 +508,19 @@ interface SystemInfo {
   Processor?: string;
   "Physical Memory"?: string;
   "Windows Power Setting"?: string;
-  model_storage?: { path?: string; used_bytes?: number; total_bytes?: number; free_bytes?: number };
+  model_storage?: { path?: string; used_bytes?: number; total_bytes?: number; free_bytes?: number; error?: string };
   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 };
   };
+  /** Recipe → backend support matrix (lemonade ≥2026.46): every backend the
+   *  recipe can use on THIS system, with install state, tier, version. */
+  recipes?: Record<string, { default_backend?: string; backends?: Record<string, BackendInfo> }>;
+  /** Recipes whose backends are all unavailable/unsupported on this system. */
+  unavailable_recipes?: string[];
+  cloud?: { providers?: Array<Record<string, unknown>> };
 }
 
 interface DiscoveredServer {
@@ -437,6 +534,7 @@ interface DownloadJob {
   model_name?: string;
   status: string; // downloading | paused | cancelled | completed | error
   running?: boolean;
+  type?: string; // currently "model" for server-owned jobs
   file?: string;
   file_index?: number;
   total_files?: number;
@@ -444,7 +542,10 @@ interface DownloadJob {
   bytes_total?: number;
   percent?: number;
   cumulative_bytes_downloaded?: number;
+  overall_bytes_downloaded?: number;
   total_download_size?: number;
+  bytes_previously_downloaded?: number;
+  completed_files_bytes?: number;
   complete?: boolean;
   error?: string;
 }
@@ -456,6 +557,10 @@ interface RegistryResult {
   downloads?: number;
   likes?: number;
   tags?: string[];
+  has_gguf?: boolean;
+  task?: string;
+  source?: string;
+  repository_type?: string;
 }
 
 interface PullVariants {
@@ -464,6 +569,9 @@ interface PullVariants {
   suggested_name?: string;
   suggested_labels?: string[];
   mmproj_files?: string[];
+  draft_files?: string[];
+  repo_kind?: string;
+  source?: string;
   variants: Array<{ name: string; primary_file: string; files: string[]; sharded: boolean; size_bytes: number }>;
 }
 
@@ -583,10 +691,200 @@ async function deleteModel(config: LemonadeConfig, id: string): Promise<string>
   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);
+// ─── Recipe options, pinning, updates, backends (lemonade ≥2026.46) ─────────
+
+/** GET /v1/models/{id}/options — a model's recipe options by layer. */
+interface ModelOptionsLayers {
+  model_name?: string;
+  recipe?: string;
+  saved?: Record<string, unknown>;
+  effective?: Record<string, unknown>;
+  defaults?: Record<string, unknown>;
+  resolved_ctx_size?: number;
+}
+
+/** Headers for /internal/* endpoints: they demand LEMONADE_ADMIN_API_KEY
+ *  when the server sets one; otherwise the ordinary key is accepted. The
+ *  config view already resolved the fallback chain, so this is a plain
+ *  Bearer of adminApiKey. */
+function adminHeaders(config: LemonadeConfig): Record<string, string> {
+  return config.adminApiKey
+    ? { Authorization: `Bearer ${config.adminApiKey}` }
+    : authHeaders(config);
+}
+
+/** The server rejects /internal/* calls without its admin key with a plain
+ *  403-shaped body — surface that as actionable text, not a raw dump. */
+function adminKeyErrorMessage(config: LemonadeConfig, body: string): string | null {
+  return /admin API key/i.test(body)
+    ? "The server requires LEMONADE_ADMIN_API_KEY for this action, and the configured key is missing or wrong — " +
+        "set adminApiKey in ~/.pi/agent/lemonade.json (or Server settings → Admin API key), then retry."
+    : null;
+}
+
+function modelOptionsUrl(config: LemonadeConfig, id: string): string {
+  return url(config, config.modelOptionsPath.replace("{id}", encodeURIComponent(id)));
+}
+
+/** Read a model's recipe options without loading it (saved/effective/defaults). */
+async function fetchModelOptions(config: LemonadeConfig, id: string): Promise<ModelOptionsLayers> {
+  const res = await fetch(modelOptionsUrl(config, id), {
+    headers: authHeaders(config),
+    signal: AbortSignal.timeout(config.discoveryTimeoutMs),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  return (await res.json()) as ModelOptionsLayers;
+}
+
+/** Save (merge) recipe options for a model without loading it.
+ *  `dryRun: true` validates + resolves but persists nothing. */
+async function saveModelOptions(
+  config: LemonadeConfig,
+  id: string,
+  options: Record<string, unknown>,
+  dryRun = false
+): Promise<Record<string, unknown>> {
+  const res = await fetch(modelOptionsUrl(config, id), {
+    method: "POST",
+    headers: { ...authHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify({ ...options, ...(dryRun ? { dry_run: true } : {}) }),
+    signal: AbortSignal.timeout(config.discoveryTimeoutMs * 2),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  return (await res.json()) as Record<string, unknown>;
+}
+
+/** Reset a model's saved recipe options to defaults. */
+async function resetModelOptions(config: LemonadeConfig, id: string): Promise<void> {
+  const res = await fetch(modelOptionsUrl(config, id), {
+    method: "DELETE",
+    headers: authHeaders(config),
+    signal: AbortSignal.timeout(config.discoveryTimeoutMs),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+}
+
+/** POST /internal/pin — pin/unpin a loaded model in place (no reload). */
+async function setPinned(config: LemonadeConfig, id: string, pinned: boolean): Promise<void> {
+  const res = await fetch(url(config, config.pinPath), {
+    method: "POST",
+    headers: { ...adminHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify({ model_name: id, pinned }),
+    signal: AbortSignal.timeout(config.discoveryTimeoutMs),
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(adminKeyErrorMessage(config, body) ?? `HTTP ${res.status}: ${body.slice(0, 200)}`);
+  }
+}
+
+/** POST /v1/models/check-updates — report downloaded models with newer
+ *  upstream commits (no download happens). */
+interface CheckUpdatesResult {
+  status?: string;
+  updates_available?: number;
+  models?: string[];
+  failed_models?: Record<string, string>;
+}
+
+async function checkModelUpdates(config: LemonadeConfig): Promise<CheckUpdatesResult> {
+  const res = await fetch(url(config, config.checkUpdatesPath), {
+    method: "POST",
+    headers: authHeaders(config),
+    signal: AbortSignal.timeout(120_000),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  return (await res.json()) as CheckUpdatesResult;
+}
+
+/** POST /internal/models/sync — bulk update downloaded models from their
+ *  registries (admin). dryRun reports without downloading. */
+interface ModelSyncResult {
+  status?: string;
+  sync_id?: number;
+  completed_sync_id?: number;
+  already_in_progress?: boolean;
+  dry_run?: boolean;
+  models_updated?: string[];
+  models_up_to_date?: string[];
+  failed_models?: Record<string, string>;
+  checked_count?: number;
+  updated_count?: number;
+}
+
+async function syncModelUpdates(
+  config: LemonadeConfig,
+  options: { models?: string[]; dryRun?: boolean } = {}
+): Promise<ModelSyncResult> {
+  const res = await fetch(url(config, config.modelSyncPath), {
+    method: "POST",
+    headers: { ...adminHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify(options),
+    signal: AbortSignal.timeout(300_000),
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(adminKeyErrorMessage(config, body) ?? `HTTP ${res.status}: ${body.slice(0, 200)}`);
+  }
+  return (await res.json()) as ModelSyncResult;
+}
+
+/** One backend of a recipe, as system-info reports it. */
+interface BackendInfo {
+  state?: "installed" | "installable" | "unsupported" | string;
+  tier?: string;
+  format?: string;
+  version?: string;
+  message?: string;
+  action?: string;
+  can_uninstall?: boolean;
+  devices?: string[];
+  download_filename?: string;
+  release_url?: string;
+}
+
+/** Install (or update) a recipe backend as a server-owned download job —
+ *  same /v1/downloads machinery as pulls, so the same progress view tracks it. */
+async function installBackendJob(
+  config: LemonadeConfig,
+  recipe: string,
+  backend: string
+): Promise<DownloadJob> {
+  const res = await fetch(url(config, config.installPath), {
+    method: "POST",
+    headers: { ...authHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify({ recipe, backend, stream: true, subscribe: false }),
+    signal: AbortSignal.timeout(config.discoveryTimeoutMs * 4),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`);
+  return (await res.json()) as DownloadJob;
+}
+
+/** Resolve what installing a backend would fetch, without downloading. */
+async function installBackendDryRun(
+  config: LemonadeConfig,
+  recipe: string,
+  backend: string
+): Promise<Record<string, unknown>> {
+  const res = await fetch(url(config, config.installDryRunPath), {
+    method: "POST",
+    headers: { ...authHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify({ recipe, backend }),
+    signal: AbortSignal.timeout(config.discoveryTimeoutMs * 4),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`);
+  return (await res.json()) as Record<string, unknown>;
+}
+
+/** Uninstall a backend (or remove a cloud provider registration). */
+async function uninstallBackend(config: LemonadeConfig, recipe: string, backend: string): Promise<void> {
+  const res = await fetch(url(config, config.uninstallPath), {
+    method: "POST",
+    headers: { ...authHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify({ recipe, backend }),
+    signal: AbortSignal.timeout(config.discoveryTimeoutMs * 4),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`);
 }
 
 /** Parse "32k", "1m", "262144" → number of tokens. */
@@ -705,7 +1003,17 @@ async function discoverViaHttp(config: LemonadeConfig): Promise<DiscoveredServer
  *  network failure — a hygiene check must never cry wolf on offline
  *  startups: unknown ≠ out of date. */
 
-const DOCS_FILES = ["README.md", "anthropic.md", "lemonade.md", "llamacpp.md", "mcp.md", "ollama.md", "openai.md"];
+const DOCS_FILES = [
+  "README.md",
+  "anthropic.md",
+  "internal.md",
+  "lemonade.md",
+  "llamacpp.md",
+  "mcp.md",
+  "ollama.md",
+  "openai.md",
+  "router.md",
+];
 const DOCS_UPSTREAM_BASE = "https://github.com/lemonade-sdk/lemonade/blob/main/docs/api/";
 const DOCS_GH_CONTENTS = (file: string) =>
   `https://api.github.com/repos/lemonade-sdk/lemonade/contents/docs/api/${file}`;
@@ -752,6 +1060,105 @@ function saveUpstreamSnapshot(snap: UpstreamVersionSnapshot): void {
   }
 }
 
+// ─── Outage catalog cache (cacheOnOutage) ────────────────────────────────
+
+interface CatalogCacheEntry {
+  fetchedAt: number; // epoch ms of the successful probe this snapshot came from
+  catalog: LemonadeModel[];
+  health: LemonadeHealth | null;
+  /** Durable last-known-state: the most recent probe pass for this instance
+   *  FAILED. Gates instant cache-serving (hybrid SWR) at the next activation —
+   *  an instance known down serves its cached listing with zero probe wait,
+ *  then reconciles in the background. Cleared on every successful probe.
+   *  Only meaningful alongside a catalog: a snapshotless instance is never
+   *  flagged (there is nothing to serve anyway). */
+  unreachableAtLastProbe?: boolean;
+}
+
+interface CatalogCacheFile {
+  instances: Record<string, CatalogCacheEntry>;
+}
+
+function catalogCachePath(): string {
+  return path.join(getAgentDir(), "cache", "pi-lemonade-link", "catalog-cache.json");
+}
+
+/** Defensively validated load — a corrupt/absent cache is an empty cache,
+ *  never a load failure. */
+function loadCatalogCache(): CatalogCacheFile {
+  try {
+    const raw = JSON.parse(fs.readFileSync(catalogCachePath(), "utf8")) as CatalogCacheFile;
+    if (!raw || typeof raw !== "object" || typeof raw.instances !== "object" || raw.instances === null) {
+      return { instances: {} };
+    }
+    const instances: Record<string, CatalogCacheEntry> = {};
+    for (const [name, e] of Object.entries(raw.instances)) {
+      if (
+        e && typeof e === "object" && typeof e.fetchedAt === "number" && Array.isArray(e.catalog) &&
+        e.catalog.every((m) => m && typeof (m as LemonadeModel).id === "string")
+      ) {
+        instances[name] = {
+          fetchedAt: e.fetchedAt,
+          catalog: e.catalog as LemonadeModel[],
+          health: (e.health ?? null) as LemonadeHealth | null,
+          ...(e.unreachableAtLastProbe === true ? { unreachableAtLastProbe: true } : {}),
+        };
+      }
+    }
+    return { instances };
+  } catch {
+    return { instances: {} };
+  }
+}
+
+function saveCatalogCacheEntry(name: string, entry: CatalogCacheEntry): void {
+  try {
+    const cache = loadCatalogCache();
+    cache.instances[name] = entry;
+    fs.mkdirSync(path.dirname(catalogCachePath()), { recursive: true });
+    fs.writeFileSync(catalogCachePath(), JSON.stringify(cache, null, 2) + "\n");
+  } catch {
+    /* cache dir unwritable → the outage fallback simply has nothing to serve */
+  }
+}
+
+/** Mark the durable last-known-state WITHOUT touching the snapshot: the
+ *  most recent probe for this instance failed (true) / succeeded (false).
+ *  Keeps the catalog/fetchedAt/health of the last successful probe — the
+ *  flag and the snapshot age independently by design. */
+function flagCatalogCacheEntry(name: string, unreachableAtLastProbe: boolean): void {
+  try {
+    const cache = loadCatalogCache();
+    const entry = cache.instances[name];
+    if (!entry) return; // no snapshot → nothing to serve, flag would be meaningless
+    entry.unreachableAtLastProbe = unreachableAtLastProbe;
+    fs.mkdirSync(path.dirname(catalogCachePath()), { recursive: true });
+    fs.writeFileSync(catalogCachePath(), JSON.stringify(cache, null, 2) + "\n");
+  } catch {
+    /* unwritable cache — the next activation just probes live instead */
+  }
+}
+
+function clearCatalogCache(): void {
+  try {
+    fs.rmSync(catalogCachePath(), { force: true });
+  } catch {
+    /* nothing to clear / unwritable — loadCatalogCache still returns {} */
+  }
+}
+
+/** Human stamp for a cached snapshot: "14:32" same-day, "Sep 12 14:32"
+ *  older. The age IS the provenance — users discount old snapshots themselves. */
+function formatCacheStamp(ts: number): string {
+  const d = new Date(ts);
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const hms = `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+  const now = new Date();
+  const sameDay =
+    d.getFullYear() === now.getFullYear() && d.getMonth() === now.getMonth() && d.getDate() === now.getDate();
+  return sameDay ? hms : `${d.toLocaleString("en", { month: "short" })} ${d.getDate()}, ${hms}`;
+}
+
 /** The latest published lemonade version, or undefined when unreachable
  *  (unknown ≠ outdated — never cry wolf). */
 async function latestUpstreamVersion(config: LemonadeConfig): Promise<string | undefined> {
@@ -822,7 +1229,7 @@ function saveDocsSnapshot(snap: DocsSpecSnapshot): void {
  *  config: it is a property of the build — updated with each extension
  *  release after re-verification — never a user preference to move. The
  *  server's own version is probed live from /v1/health; this is the peg. */
-const EXTENSION_CONFIRMED_SERVER_VERSION = "11.7.0";
+const EXTENSION_CONFIRMED_SERVER_VERSION = "2026.46.2";
 
 /** This extension's own version, from package.json (kept beside the
  *  provider.apiVerifiedAgainst record — see the README versioning
@@ -839,11 +1246,20 @@ const PKG_VERSION = (() => {
   }
 })();
 
+/** Canonical comparable form of a lemonade version: strips dev-build
+ *  suffixes ("2026.45.0~1719.034d3f52" → "2026.45.0") so a dev build of a
+ *  release compares against that release. Lemonade switched to calendar
+ *  versioning (2026.MM.patch) after 11.7.0; both dotted forms compare. Pure. */
+function canonicalVersion(v: string): string {
+  return v.split("~")[0].trim();
+}
+
 /** Compare dotted numeric versions: >0 if a is newer than b, <0 if older,
- *  null when either side isn't dotted-numeric (no direction, just "differs"). Pure. */
+ *  null when either side isn't dotted-numeric (no direction, just "differs").
+ *  Dev-build suffixes are canonicalized away first. Pure. */
 function versionCompare(a: string, b: string): number | null {
-  const pa = a.split(".").map(Number);
-  const pb = b.split(".").map(Number);
+  const pa = canonicalVersion(a).split(".").map(Number);
+  const pb = canonicalVersion(b).split(".").map(Number);
   if (pa.some(Number.isNaN) || pb.some(Number.isNaN)) return null;
   for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
     const d = (pa[i] ?? 0) - (pb[i] ?? 0);
@@ -882,7 +1298,11 @@ const serverVersionsSeen = new Map<string, string>();
 function recordServerVersion(config: LemonadeConfig, instance: string, version: string | undefined): void {
   const i = serverVersionMismatches.findIndex((m) => m.instance === instance);
   const cmp = version ? versionCompare(version, EXTENSION_CONFIRMED_SERVER_VERSION) : null;
-  const mismatched = config.serverVersionCheck && !!version && version !== EXTENSION_CONFIRMED_SERVER_VERSION;
+  // Compare the canonical form: a dev build of the verified release
+  // ("2026.46.2~1719.034d3f52") IS that release for endpoint purposes —
+  // only a genuinely different version warns.
+  const mismatched =
+    config.serverVersionCheck && !!version && canonicalVersion(version) !== EXTENSION_CONFIRMED_SERVER_VERSION;
   if (version) serverVersionsSeen.set(instance, version);
   else serverVersionsSeen.delete(instance);
   if (mismatched && version) {
@@ -1066,59 +1486,133 @@ function registerSpecDriftWarnings(pi: ExtensionAPI, configRef: { current: Lemon
 
 // ─── 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"
-  );
+/** One instance's registration-pass probe: catalog + health fetched in
+ *  parallel (null = unreachable). Probes are fetched once per pass — all
+ *  instances at once — and shared by every consumer of that pass (provider
+ *  registration AND the tool-registration classifier hint), so a full
+ *  activation costs one network round per instance even though two
+ *  consumers need the catalog: an unreachable box stalls startup once,
+ *  not once per consumer, and a fleet of instances stalls in parallel,
+ *  not serially. */
+export interface InstanceProbe {
+  view: InstanceView;
+  catalog: LemonadeModel[] | null;
+  health: LemonadeHealth | null;
+  /** Set when catalog/health come from the on-disk outage cache rather
+   *  than a live probe (see withCacheFallback): the epoch ms of the fetch
+   *  the cache entry was written at. */
+  cachedAt?: number;
 }
 
-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 probeInstance(view: InstanceView): Promise<InstanceProbe> {
+  try {
+    const [catalog, health] = await Promise.all([
+      fetchCatalog(view.config),
+      fetchHealth(view.config),
+    ]);
+    if (view.config.cacheOnOutage) {
+      // Fresh truth — persist the snapshot the outage fallback will serve
+      // if a future probe can't reach this box, and clear the down-flag.
+      saveCatalogCacheEntry(view.name, { fetchedAt: Date.now(), catalog, health, unreachableAtLastProbe: false });
+    }
+    return { view, catalog, health };
+  } catch {
+    // Unreachable. What that means for /model depends on the outage cache
+    // (withCacheFallback decides right after) — here we only report the
+    // network truth: the box did not answer within discoveryTimeoutMs.
+    // Durable last-known-state for the hybrid SWR activation path.
+    if (view.config.cacheOnOutage) flagCatalogCacheEntry(view.name, true);
+    console.error(`[pi-lemonade-link] instance "${view.name}" unreachable at ${view.config.baseUrl}`);
+    return { view, catalog: null, health: null };
+  }
+}
+
+/** Probe every configured instance in one parallel pass. */
+function probeInstances(config: LemonadeConfig): Promise<InstanceProbe[]> {
+  return Promise.all(listInstances(config).map(probeInstance));
+}
+
+/** Outage fallback (cacheOnOutage): an unreachable instance serves its last
+ *  successfully cached catalog — provenance-marked "(cached <stamp>)" at
+ *  registration time — instead of listing nothing. Live truth always wins:
+ *  reachable instances pass through untouched, and a box with no cached
+ *  snapshot yet still lists nothing (no cache, nothing honest to serve).
+ *  Idempotent: probes that already carry a cached catalog pass through. */
+function withCacheFallback(config: LemonadeConfig, probes: InstanceProbe[]): InstanceProbe[] {
+  if (!config.cacheOnOutage) return probes;
+  const cache = loadCatalogCache();
+  return probes.map((p) => {
+    if (p.catalog) return p;
+    const entry = cache.instances[p.view.name];
+    if (!entry || !entry.catalog.length) return p;
+    return { ...p, catalog: entry.catalog, health: entry.health, cachedAt: entry.fetchedAt };
+  });
+}
+
+/** Hybrid stale-while-revalidate probe pass (cacheOnOutage): instances whose
+ *  LAST probe failed (durable flag, see flagCatalogCacheEntry) serve their
+ *  cached catalog instantly — no probe wait, no discoveryTimeoutMs stall —
+  *  while the rest probe live in one parallel pass (failures still get the
+ *  withCacheFallback safety net, so the transition INTO an outage is the
+ *  only stall left). The caller reconciles instant-served instances with a
+ *  background probe pass. Without the flag (or without a snapshot)
+ *  everything probes live: probe-first is both the honest and the fast path
+ *  when the box was up last time. */
+async function instantOrLiveProbes(config: LemonadeConfig): Promise<InstanceProbe[]> {
+  if (!config.cacheOnOutage) return await probeInstances(config);
+  const cache = loadCatalogCache();
+  const instant: InstanceProbe[] = [];
+  const live: InstanceView[] = [];
+  for (const view of listInstances(config)) {
+    const entry = cache.instances[view.name];
+    if (entry && entry.catalog.length && entry.unreachableAtLastProbe) {
+      instant.push({ view, catalog: entry.catalog, health: entry.health, cachedAt: entry.fetchedAt });
+    } else {
+      live.push(view);
+    }
+  }
+  if (!instant.length) return withCacheFallback(config, await probeInstances(config));
+  return withCacheFallback(config, [...instant, ...(await Promise.all(live.map(probeInstance)))]);
 }
 
-async function registerInstanceProvider(pi: ExtensionAPI, view: InstanceView): Promise<number> {
+/** Instances whose current /model listing is served from the outage cache
+ *  (probe failed, cache served): name → when it was cached + the listed
+ *  ids. Single source of truth: every registration pass (registerInstanceProvider
+ *  records; registerLemonadeProvider resets) — same discipline as
+ *  serverVersionMismatches. Drives the session-start warning and the
+ *  background re-sync's recovery diff. */
+const cachedServing = new Map<string, { fetchedAt: number; ids: string[] }>();
+
+/** Register one instance's provider from a probe that already ran — no
+ *  network here; the probe pass owns all registration-time I/O. */
+function registerInstanceProvider(pi: ExtensionAPI, probe: InstanceProbe): number {
+  const view = probe.view;
   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));
-    recordServerVersion(config, view.name, health?.version);
-  } 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 = [];
+  const catalog = probe.catalog ?? [];
+  const loaded = new Set((probe.health?.all_models_loaded ?? []).map((m) => m.model_name));
+  const cachedStamp = probe.cachedAt !== undefined ? formatCacheStamp(probe.cachedAt) : undefined;
+  if (cachedStamp) {
+    // Outage-cache serving: the listing is a provenance-marked snapshot, not
+    // live truth — record it so the session-start warning and the background
+    // re-sync know this instance is listed from cache.
+    console.error(
+      `[pi-lemonade-link] instance "${view.name}" unreachable — serving cached catalog from ${cachedStamp}`
+    );
+    cachedServing.set(view.name, { fetchedAt: probe.cachedAt!, ids: catalog.map((m) => m.id) });
+    recordServerVersion(config, view.name, probe.health?.version); // cached version — self-heals on re-sync
+  } else if (probe.catalog) {
+    cachedServing.delete(view.name);
+    recordServerVersion(config, view.name, probe.health?.version);
+  } else {
+    // Unreachable with no cache to serve: 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 honest tradeoff when there is no cached truth.
     console.error(
-      `[pi-lemonade-link] instance "${view.name}" unreachable at ${config.baseUrl}; registering no models`
+      `[pi-lemonade-link] instance "${view.name}" has no cached catalog — registering no models`
     );
+    cachedServing.delete(view.name);
   }
 
   const advertised = config.chatOnly ? catalog.filter(isChatModel) : catalog;
@@ -1135,12 +1629,53 @@ async function registerInstanceProvider(pi: ExtensionAPI, view: InstanceView): P
     apiKey: config.apiKey || "lemonade",
     authHeader: true,
     api: "openai-completions",
-    models: advertised.map((m) => toProviderModel(m, loaded, providerId)),
+    models: advertised.map((m) => toProviderModel(m, loaded, providerId, cachedStamp)),
   });
 
   return advertised.length;
 }
 
+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", cachedStamp?: string) {
+  const labels = m.labels ?? [];
+  // context_length is the live truth (loaded/configured ctx_size, else the
+  // metadata ceiling); max_context_window is the static ceiling alone.
+  const contextWindow = m.context_length ?? m.max_context_window ?? 128000;
+  const badges = [
+    ...(labels.includes("hot") ? ["★"] : []),
+    ...(labels.includes("tool-calling") ? ["tools"] : []),
+    ...(labels.includes("chat-transcription") ? ["audio-in-chat"] : []),
+  ];
+  const badgeText = badges.length ? ` ${badges.join(" ")}` : "";
+  return {
+    id: m.id,
+    name: cachedStamp
+      ? `${m.id}${badgeText} (${providerId}, cached ${cachedStamp})`
+      : loaded.has(m.id)
+        ? `${m.id}${badgeText} (${providerId}, loaded)`
+        : `${m.id}${badgeText} (${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,
+    },
+  };
+}
+
 /** 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
@@ -1150,22 +1685,114 @@ async function registerInstanceProvider(pi: ExtensionAPI, view: InstanceView): P
 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> {
+ *  pi provider under the uniform lemonade-<name> id. Probes are shared per
+ *  pass: pass the caller's probeInstances() result to reuse the network
+ *  round (activation does exactly that — one pass feeds both provider and
+ *  tool registration); omitted, a fresh parallel pass runs. */
+async function registerLemonadeProvider(
+  pi: ExtensionAPI,
+  config: LemonadeConfig,
+  probes?: InstanceProbe[]
+): Promise<number> {
   serverVersionMismatches.length = 0; // (re)collected per registration pass
   serverVersionsSeen.clear();
+  cachedServing.clear();
   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);
+  for (const probe of probes ?? withCacheFallback(config, await probeInstances(config))) {
+    total += registerInstanceProvider(pi, probe);
   }
   return total;
 }
 
+// ─── Outage re-sync (cacheOnOutage) ─────────────────────────────────────
+
+let resyncBusy = false;
+let lastResyncProbeAt = 0;
+
+/** Fire-and-forget outage re-sync: probe all instances and re-register.
+ *  Throttled to one probe pass per discoveryTimeoutMs window (turn_start
+ *  fires once per turn — agentic loops fire it rapidly) and a no-op while
+ *  every instance is live (cachedServing empty). Recovery is announced
+ *  only when the live catalog differs from the cached one — state-steady
+ *  means silent. force (the setup menu's Refresh connection) bypasses both
+ *  guards and always re-registers. Returns the registered model count
+ *  (−1 when a pass is already in flight). */
+async function resyncFromOutage(
+  pi: ExtensionAPI,
+  configRef: { current: LemonadeConfig },
+  notify?: (message: string) => void,
+  force = false
+): Promise<number> {
+  if (resyncBusy) return -1;
+  if (!force) {
+    if (cachedServing.size === 0) return 0;
+    if (Date.now() - lastResyncProbeAt < configRef.current.discoveryTimeoutMs) return 0;
+  }
+  resyncBusy = true;
+  lastResyncProbeAt = Date.now();
+  try {
+    const cachedBefore = new Map(cachedServing);
+    const probes = await probeInstances(configRef.current);
+    const registered = await registerLemonadeProvider(
+      pi,
+      configRef.current,
+      withCacheFallback(configRef.current, probes)
+    );
+    // Recovery notice — only for instances that answered, and only when
+    // their live catalog actually differs from the served snapshot.
+    for (const [name, before] of cachedBefore) {
+      const recovered = probes.find((p) => p.view.name === name && p.catalog && p.cachedAt === undefined);
+      if (!recovered?.catalog) continue; // still unreachable (or still cache-served)
+      const beforeIds = new Set(before.ids);
+      const afterIds = new Set(recovered.catalog.map((m) => m.id));
+      const added = recovered.catalog.filter((m) => !beforeIds.has(m.id)).map((m) => m.id);
+      const removed = before.ids.filter((id) => !afterIds.has(id));
+      if (!added.length && !removed.length) continue;
+      notify?.(
+        `pi-lemonade-link: instance "${name}" reachable again — re-synced: ` +
+          `${added.length ? `+${added.join(", ")}` : ""}${added.length && removed.length ? "; " : ""}${removed.length ? `−${removed.join(", ")}` : ""}`
+      );
+    }
+    return registered;
+  } finally {
+    resyncBusy = false;
+  }
+}
+
+/** Event wiring for the outage re-sync: prompt submit (turn_start), model
+ *  selection, and session start/resume each trigger a throttled,
+ *  cached-state-only probe pass (never blocking the turn). The status bar's
+ *  own health poll is the free continuous detector (see registerLemonadeBar's
+ *  tick). The session-start handler also warns, one line per outage-cached
+ *  instance, while the state persists — same shape as the tier-1 version
+ *  mismatch warning. */
+function registerOutageResync(pi: ExtensionAPI, configRef: { current: LemonadeConfig }): void {
+  type ExtCtx = import("@earendil-works/pi-coding-agent").ExtensionContext;
+  const trigger = (ctx: ExtCtx) => {
+    if (cachedServing.size === 0) return; // every instance live — nothing to re-sync
+    void resyncFromOutage(pi, configRef, ctx.hasUI ? (m) => ctx.ui.notify(m, "info") : undefined);
+  };
+  pi.on("turn_start", (_e, ctx) => trigger(ctx as ExtCtx));
+  pi.on("model_select", (_e, ctx) => trigger(ctx as ExtCtx));
+  pi.on("session_start", (_e, ctx) => {
+    trigger(ctx as ExtCtx);
+    if (!(ctx as ExtCtx).hasUI) return;
+    for (const [instance, served] of cachedServing) {
+      (ctx as ExtCtx).ui.notify(
+        `pi-lemonade-link: instance "${instance}" is unreachable — /model lists its cached catalog from ` +
+          `${formatCacheStamp(served.fetchedAt)}; requests to it will fail until the box answers. ` +
+          `It re-syncs automatically on the next prompt, model selection, or session start. cacheOnOutage: false disables.`,
+        "warning"
+      );
+    }
+  });
+}
+
 // ─── Multimodal agent tools ──────────────────────────────────────────────────
 
 /** Combine an operation timeout with the caller's cancel signal (if any),
@@ -1427,7 +2054,11 @@ function runFfmpeg(args: string[], timeoutMs: number): Promise<void> {
   });
 }
 
-async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Promise<void> {
+async function registerAgentTools(
+  pi: ExtensionAPI,
+  gconfig: LemonadeConfig,
+  probes?: InstanceProbe[]
+): 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
@@ -1456,19 +2087,20 @@ async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Pr
   {
     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
-        }
-      })
-    );
+    // Share the activation-pass probes when the caller has them (provider
+    // registration just fetched the same catalogs); otherwise one fresh
+    // parallel pass — never a serial per-instance round.
+    for (const probe of probes ?? withCacheFallback(gconfig, await probeInstances(gconfig))) {
+      if (!probe.catalog) {
+        continue; // instance unreachable at registration time — hint stays generic for it
+      }
+      for (const m of probe.catalog.filter(
+        (m) => m.recipe === "onnxruntime" || (m.labels ?? []).includes("classification")
+      )) {
+        ids.add(m.id);
+        if (m.downloaded !== false) pulled.add(m.id);
+      }
+    }
     if (ids.size) {
       classifierHint =
         `Classifiers on this server: ${[...ids].join(", ")}. ` +
@@ -1676,13 +2308,39 @@ async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Pr
     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.",
+      "(e.g. OpenMOSS-TTS). Supports three voice modes: a named voice, cloning " +
+      "a voice from a reference audio file, or designing one from a free-text " +
+      "description (OpenMOSS models). 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')." })),
+      voice: Type.Optional(
+        Type.String({
+          description:
+            "Voice selection. Kokoro-style models take a named voice ('alloy', " +
+            "'af_sky'); OpenMOSS models take free-text voice or style instruction, " +
+            "e.g. 'a calm, deep male narrator voice'.",
+        })
+      ),
+      reference_voice_path: Type.Optional(
+        Type.String({
+          description:
+            "Voice cloning (OpenMOSS models): path to a local WAV sample of the " +
+            "voice to clone, e.g. a few seconds of clean speech. Takes precedence " +
+            "over voice_design_description.",
+        })
+      ),
+      voice_design_description: Type.Optional(
+        Type.String({
+          description:
+            "Voice design (OpenMOSS models): describe the voice to invent, e.g. " +
+            "'a warm low female voice with a British accent'. The server renders a " +
+            "short sample in that voice and uses it as the reference. Ignored when " +
+            "reference_voice_path is given.",
+        })
+      ),
       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." })),
     }),
@@ -1698,6 +2356,22 @@ async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Pr
       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;
+      if (params.reference_voice_path) {
+        // Voice cloning: the server wants the sample inline as base64 WAV.
+        try {
+          const refPath = path.resolve(params.reference_voice_path);
+          const refBuf = await readRequiredFile(refPath);
+          body.reference_wav_b64 = refBuf.toString("base64");
+        } catch (error) {
+          return toolError(
+            `Could not read the voice sample '${params.reference_voice_path}': ${
+              error instanceof Error ? error.message : String(error)
+            }`
+          );
+        }
+      } else if (params.voice_design_description) {
+        body.voice_design_description = params.voice_design_description;
+      }
       return postJsonSaveBinary(config, config.speechPath, body, "speech", fmt === "pcm" ? "pcm" : fmt, signal, `model: ${model}`);
     },
   });
@@ -1716,6 +2390,8 @@ async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Pr
       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." })),
+      steps: Type.Optional(Type.Number({ description: "Inference steps; lower is faster, higher can improve quality." })),
+      cfg: Type.Optional(Type.Number({ description: "Classifier-free guidance strength (ThinkSound only)." })),
       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." })),
@@ -1724,12 +2400,14 @@ async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Pr
       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"]);
+      const auto = await pickModelByLabels(config, ["audio-generation", "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.steps) body.steps = params.steps;
+      if (params.cfg) body.cfg = params.cfg;
       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;
@@ -1779,12 +2457,15 @@ async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Pr
     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). " +
+      "Classify input TEXT with a classifier model on the lemonade server. Two " +
+      "kinds exist: fixed-label encoders (recipe onnxruntime — BERT-family), " +
+      "each answering exactly one question decided by its baked-in label set " +
+      "(the response's labels reveal that universe — if they don't fit the " +
+      "question, retry with a different model), and zero-shot decision models " +
+      "(e.g. LFM2 prompt routers) that REQUIRE the labels parameter to name the " +
+      "choices per request. 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.",
@@ -1794,7 +2475,19 @@ async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Pr
       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." })
+        Type.String({
+          description:
+            "Classifier model id. Omit to auto-pick (prefers pulled fixed-label " +
+            "onnxruntime classifiers). Pass a zero-shot model's id when using labels.",
+        })
+      ),
+      labels: Type.Optional(
+        Type.Array(Type.String(), {
+          description:
+            "Zero-shot models only: the labels (candidate answers) to score the " +
+            "input against, e.g. [\"phishing\", \"legitimate\"]. Required by zero-shot " +
+            "decision models; refused by fixed-label encoders — omit it for those.",
+        })
       ),
       top_k: Type.Optional(
         Type.Number({ description: "Only return the highest-scoring k labels." })
@@ -1804,16 +2497,23 @@ async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Pr
       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");
+      // Zero-shot requests (labels given) auto-pick a zero-shot decision model
+      // (LFM2 routers, llama.cpp/FLM decision models); fixed-label requests
+      // auto-pick an onnxruntime encoder. An explicit model id always wins.
+      const auto = params.labels?.length
+        ? ((await pickModelByLabels(config, ["zero-shot"])) ?? (await pickModelByRecipe(config, "onnxruntime")))
+        : 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."
+          "No classifier model found on the lemonade server (no onnxruntime " +
+            "encoder and no zero-shot decision model). Pull one first, e.g. " +
+            "Bert-Phishing-ONNX or Phishing-Email-Detection-ONNX."
         );
       }
       const body: Record<string, unknown> = { model, input: params.input };
+      if (params.labels?.length) body.labels = params.labels;
       if (params.top_k) body.top_k = params.top_k;
       const res = await toolFetch(config, config.classifyPath, {
         method: "POST",
@@ -1870,6 +2570,11 @@ interface BarMetrics {
   npuPct: number | null;
   npuSupported: boolean | null; // null = unknown yet; false = box has no NPU (segment dropped)
   vramGb: number | null;
+  /** Whole-box liveness from /v1/stats (≥2026.46): requests in flight and
+   *  the server's own live tok/s estimate across ALL clients — null until
+   *  the first poll lands (placeholder dots, same as every other segment). */
+  activeReqs: number | null;
+  serverToksPerSec: number | null;
 }
 
 /**
@@ -1883,9 +2588,10 @@ function registerLemonadeBar(pi: ExtensionAPI, configRef: { current: LemonadeCon
   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 };
+  const metrics: BarMetrics = { toksPerSec: null, cachePct: null, busy: null, cpuPct: null, gpuPct: null, npuPct: null, npuSupported: null, vramGb: null, activeReqs: null, serverToksPerSec: null };
   let activeInstance: string | null = null;
   let timer: ReturnType<typeof setInterval> | undefined;
+  let barCtx: ExtCtx | undefined; // ctx of the installed row — for re-sync notices
   let tuiRef: { requestRender(): void } | undefined;
   let msgStartAt: number | null = null;
 
@@ -1905,6 +2611,8 @@ function registerLemonadeBar(pi: ExtensionAPI, configRef: { current: LemonadeCon
     metrics.npuPct = null;
     metrics.npuSupported = null;
     metrics.vramGb = null;
+    metrics.activeReqs = null;
+    metrics.serverToksPerSec = null;
     msgStartAt = null; // a stream started under another/removed row must not leak into the next
   };
 
@@ -1920,10 +2628,11 @@ function registerLemonadeBar(pi: ExtensionAPI, configRef: { current: LemonadeCon
       tuiRef?.requestRender();
       return;
     }
-    const [health, sys, metricsBody] = await Promise.all([
+    const [health, sys, metricsBody, perf] = await Promise.all([
       fetchHealth(view),
       fetchJsonOrNull<SystemStats>(view, "/v1/system-stats"),
       fetchTextOrNull(view, "/metrics"),
+      fetchJsonOrNull<PerfStats>(view, "/v1/stats"),
     ]);
     if (activeInstance !== instance) return; // row switched while fetching: discard
     if (!health) {
@@ -1947,6 +2656,26 @@ function registerLemonadeBar(pi: ExtensionAPI, configRef: { current: LemonadeCon
         metrics.npuSupported = false; // box reported system-stats with no NPU
       }
       if (typeof sys?.vram_gb === "number") metrics.vramGb = sys.vram_gb;
+      // Whole-box liveness (≥2026.46): requests in flight and the server's own
+      // tok/s estimate across every client — the bar's own tok/s segment stays
+      // session-local; this one says whether the box is streaming for ANYONE.
+      if (perf?.live) {
+        if (typeof perf.live.active_requests === "number") metrics.activeReqs = perf.live.active_requests;
+        if (typeof perf.live.estimated_tokens_per_second === "number") {
+          metrics.serverToksPerSec = perf.live.estimated_tokens_per_second;
+        }
+      } else {
+        // Pre-2026.46 servers have no live block — drop the placeholders.
+        metrics.activeReqs = metrics.activeReqs ?? 0;
+        metrics.serverToksPerSec = metrics.serverToksPerSec ?? 0;
+      }
+      // Free liveness detector: this poll already proves the box answers —
+      // while its /model listing is served from the outage cache, trigger
+      // the throttled re-sync (throttle/in-flight guards live inside
+      // resyncFromOutage; the notice goes through barCtx while installed).
+      if (cachedServing.has(instance)) {
+        void resyncFromOutage(pi, configRef, (m) => barCtx?.ui.notify(m, "info"));
+      }
     }
     tuiRef?.requestRender();
   };
@@ -1954,6 +2683,7 @@ function registerLemonadeBar(pi: ExtensionAPI, configRef: { current: LemonadeCon
   const teardown = (ctx: ExtCtx) => {
     stopTimer();
     tuiRef = undefined;
+    barCtx = undefined;
     activeInstance = null;
     resetLocal();
     try {
@@ -1967,6 +2697,7 @@ function registerLemonadeBar(pi: ExtensionAPI, configRef: { current: LemonadeCon
     stopTimer();
     resetLocal();
     activeInstance = instance;
+    barCtx = ctx;
     ctx.ui.setWidget(
       KEY,
       (tui, theme) => {
@@ -1989,6 +2720,15 @@ function registerLemonadeBar(pi: ExtensionAPI, configRef: { current: LemonadeCon
               if (metrics.busy === null) parts.push(dim("…"));
               else if (metrics.busy === "idle") parts.push(dim("idle"));
               else parts.push(theme.fg("warning", metrics.busy));
+              // Whole-box segment (≥2026.46): in-flight requests + the server's
+              // live tok/s across all clients. 0/0 is honest quiet, not "…".
+              if (metrics.activeReqs !== null) {
+                const liveBits: string[] = [];
+                if (metrics.activeReqs > 0) liveBits.push(`${metrics.activeReqs} active`);
+                if (metrics.serverToksPerSec !== null && metrics.serverToksPerSec > 0)
+                  liveBits.push(`${metrics.serverToksPerSec.toFixed(0)} tok/s (box)`);
+                if (liveBits.length) parts.push(theme.fg("warning", liveBits.join(" · ")));
+              }
               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
@@ -2082,6 +2822,8 @@ interface MenuItem<T extends 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> {
+  // Long lists get type-to-search for free — same component, one threshold.
+  if (items.length > 12) return filterMenu(ctx, { title, items });
   return ctx.ui.custom<T | null>((tui, theme, _kb, done) => {
     const container = new Container();
     container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
@@ -2106,27 +2848,294 @@ function menu<T extends string>(ctx: UiCtx, title: string, items: MenuItem<T>[])
   });
 }
 
-/** Live-refresh wiring for the scrollable textView (status panel). */
-interface TextViewLive {
-  /** Poll interval in ms; failed/empty refetches keep the last good snapshot. */
+/** Options for filterMenu — the live, type-to-search menu. */
+interface FilterMenuOptions<T extends string> {
+  title: string;
+  items: MenuItem<T>[];
+  /** Rebuild the item list in place while the menu is open (live status).
+   *  The filter and the cursor (matched by value) survive a refresh. */
+  refetch?: () => Promise<MenuItem<T>[]>;
+  /** Refresh cadence; default 2000 ms. Ignored without refetch. */
   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;
+  /** Extra single-key actions, tried before typing/filtering; return true when
+   *  consumed. The banner line above the list is the natural status outlet. */
+  onKey?: (data: string, api: { setBanner: (t: string) => void }) => boolean;
+  /** Initial banner line (updated via onKey's setBanner). */
+  banner?: string;
+  /** Extra footer hint text. */
+  hint?: string;
+  /** maxVisible; defaults to min(items, 14). */
+  maxVisible?: number;
 }
 
-/** 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) => {
+/** A menu you can TYPE into: printable input filters items live (substring,
+ *  case-insensitive, over label + description); backspace edits; Esc clears
+ *  the filter first, then exits. Arrows/Enter go to the list. Optional
+ *  refetch keeps items live (inline statuses refresh while you scroll). */
+function filterMenu<T extends string>(ctx: UiCtx, opts: FilterMenuOptions<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)));
+    const titleText = new Text(theme.fg("accent", theme.bold(opts.title)), 1, 0);
+    container.addChild(titleText);
+    const bannerText = new Text(opts.banner ? theme.fg("muted", opts.banner) : "", 0, 0);
+    container.addChild(bannerText);
+    const filterText = new Text(theme.fg("dim", ""), 0, 0);
+    container.addChild(filterText);
+    const list = new SelectList(opts.items, opts.maxVisible ?? 14, {
+      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),
+    });
+    // The list's own confirm path — without this, Enter is a silent no-op
+    // (SelectList fires onSelect only if it exists; arrows keep working,
+    // which is exactly why a missing wire is easy to ship by accident).
+    list.onSelect = (item) => { cleanup(); done(item.value as T); };
+    list.onCancel = () => { cleanup(); done(null); };
+    container.addChild(list);
+    const footer = new Text("", 1, 0);
+    container.addChild(footer);
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+    let filter = "";
+    let items = opts.items;
+    let closed = false;
+
+    // SelectList's declared surface hides its item state (private in the
+    // .d.ts, plain fields at runtime). This narrow structural view is the
+    // minimum needed for live item swaps + substring filtering over
+    // label+description — setFilter() alone only does startsWith-on-value.
+    const listState = list as unknown as {
+      items: MenuItem<T>[];
+      filteredItems: MenuItem<T>[];
+      selectedIndex: number;
+    };
+
+    const applyFilter = (): void => {
+      const f = filter.toLowerCase();
+      const matched = f
+        ? items.filter(
+            (it) =>
+              it.label.toLowerCase().includes(f) ||
+              (it.description ?? "").toLowerCase().includes(f)
+          )
+        : items;
+      listState.filteredItems = matched;
+      list.setSelectedIndex(0);
+      filterText.setText(
+        theme.fg("dim", `filter: ${filter}${filter ? " · " : ""}${matched.length}/${items.length} — type to search, ⌫ edit`)
+      );
+      footer.setText(
+        theme.fg(
+          "dim",
+          `↑↓ navigate • enter select • esc ${filter ? "clear filter" : "back"}${opts.hint ? ` • ${opts.hint}` : ""}`
+        )
+      );
+    };
+    applyFilter();
+
+    // Live refresh: swap items in place; keep the filter and the cursor
+    // (matched by value) so nothing jumps while statuses update underneath.
+    let refreshTimer: ReturnType<typeof setInterval> | undefined;
+    const refetch = opts.refetch;
+    if (refetch) {
+      const tickRefresh = async (): Promise<void> => {
+        if (closed) return;
+        try {
+          const fresh = await refetch();
+          if (closed) return;
+          const prevValue = listState.filteredItems[listState.selectedIndex]?.value;
+          items = fresh;
+          listState.items = fresh;
+          applyFilter();
+          if (prevValue !== undefined) {
+            const idx = listState.filteredItems.findIndex((it) => it.value === prevValue);
+            if (idx >= 0) list.setSelectedIndex(idx);
+          }
+          tui.requestRender();
+        } catch {
+          /* a failed refresh keeps the last good snapshot */
+        }
+      };
+      refreshTimer = setInterval(() => void tickRefresh(), Math.max(500, opts.pollMs ?? 2000));
+      void tickRefresh(); // first refresh immediately — a 2s empty-gap on open reads as broken
+    }
+    const cleanup = (): void => {
+      closed = true;
+      if (refreshTimer !== undefined) clearInterval(refreshTimer);
+    };
+
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      dispose: cleanup,
+      handleInput: (data) => {
+        try {
+          if (matchesKey(data, Key.backspace)) {
+            filter = filter.slice(0, -1);
+            applyFilter();
+          } else if (matchesKey(data, Key.escape)) {
+            if (filter) {
+              filter = "";
+              applyFilter();
+            } else {
+              cleanup();
+              done(null);
+            }
+          } else if (
+            opts.onKey &&
+            opts.onKey(data, {
+              setBanner: (t) => {
+                bannerText.setText(t ? theme.fg("muted", t) : "");
+              },
+            })
+          ) {
+            /* consumed by the caller's key hook — hotkeys run before typing */
+          } else if (
+            // Printable input (single keypress, no ctrl/meta, not an escape
+            // sequence) feeds the filter. Space is typeable; use ctrl-combos
+            // for menu hotkeys so they never collide with search text.
+            data.length >= 1 &&
+            !/[\x00-\x1f\x7f]/.test(data) &&
+            !data.startsWith("\x1b")
+          ) {
+            filter += data;
+            applyFilter();
+          } else {
+            list.handleInput(data); // arrows, enter, page keys
+          }
+          tui.requestRender();
+        } catch {
+          /* never let a key crash the process */
+        }
+      },
+    };
+  });
+}
+
+/** Braille spinner frames for busyView. */
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Outcome of a busyView run. */
+interface BusyOutcome<T> {
+  /** The operation's result on success. */
+  result?: T;
+  /** The operation's error text on failure. */
+  error?: string;
+  /** True when the user pressed Esc and the operation was allowed to keep
+   *  running server-side (loads, pulls) — the caller returns to its menu and
+   *  live views pick up the state change from polling. */
+  detached: boolean;
+}
+
+/** A visible, animated blocking indicator: spinner + label, plus an optional
+ *  live status line polled from the server (e.g. a model's load state), and
+ *  optional Esc-to-detach for operations that safely continue server-side.
+ *  Replaces the invisible setStatus-only wait for anything that can take
+ *  more than a moment. */
+function busyView<T>(
+  ctx: UiCtx,
+  label: string,
+  op: () => Promise<T>,
+  opts: { liveStatus?: () => Promise<string | null>; livePollMs?: number; escDetach?: boolean } = {}
+): Promise<BusyOutcome<T>> {
+  return ctx.ui.custom<BusyOutcome<T>>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    const spinnerText = new Text(theme.fg("accent", `${SPINNER_FRAMES[0]} ${label}`), 1, 0);
+    container.addChild(spinnerText);
+    const liveText = new Text("", 0, 0);
+    container.addChild(liveText);
+    container.addChild(
+      new Text(theme.fg("dim", opts.escDetach ? "esc continue in background" : "esc cancel"), 1, 0)
+    );
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+    let finished = false;
+    let frame = 0;
+    const finish = (outcome: BusyOutcome<T>): void => {
+      if (finished) return;
+      finished = true;
+      clearInterval(spinTimer);
+      clearInterval(liveTimer);
+      done(outcome);
+    };
+
+    const spinTimer = setInterval(() => {
+      frame = (frame + 1) % SPINNER_FRAMES.length;
+      spinnerText.setText(theme.fg("accent", `${SPINNER_FRAMES[frame]} ${label}`));
+      tui.requestRender();
+    }, 90);
+
+    let liveTimer: ReturnType<typeof setInterval> | undefined;
+    if (opts.liveStatus) {
+      const pollLive = async (): Promise<void> => {
+        if (finished) return;
+        try {
+          const s = await opts.liveStatus!();
+          if (finished) return;
+          liveText.setText(s ? theme.fg("muted", s) : "");
+          tui.requestRender();
+        } catch {
+          /* keep the last good live line */
+        }
+      };
+      void pollLive();
+      liveTimer = setInterval(() => void pollLive(), Math.max(500, opts.livePollMs ?? 2000));
+    }
+
+    void op()
+      .then((result) => finish({ result, detached: false }))
+      .catch((error) => finish({ error: error instanceof Error ? error.message : String(error), detached: false }));
+
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      dispose: () => {
+        finished = true;
+        clearInterval(spinTimer);
+        if (liveTimer !== undefined) clearInterval(liveTimer);
+      },
+      handleInput: (data) => {
+        if (matchesKey(data, Key.escape)) {
+          if (opts.escDetach) {
+            // Leave the operation running; the server keeps its state and
+            // live views pick it up. There is no way back to this promise —
+            // the caller decides how to report the eventual outcome.
+            finish({ detached: true });
+          } else {
+            spinnerText.setText(theme.fg("warning", "⏳ working — this step can't be interrupted, please wait"));
+            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);
@@ -2356,6 +3365,15 @@ async function trackDownload(
     const finish = (v: "complete" | "cancelled" | "error") => {
       if (finished) return;
       finished = true;
+      // The server keeps errored/cancelled jobs listed until a client removes
+      // them (spec: GET /v1/downloads) — this extension is that client, so a
+      // terminal outcome here also clears the job from the registry. Partial
+      // files stay on disk; a retry resumes from them.
+      if (v === "error" || v === "cancelled") {
+        void controlDownload(config, jobId, "remove").catch(() => {
+          /* removal is best-effort cleanup, never a failure of the outcome */
+        });
+      }
       done(v);
     };
 
@@ -2651,6 +3669,14 @@ function formatStatus(
       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 (perf.live && (typeof perf.live.active_requests === "number" || typeof perf.live.estimated_tokens_per_second === "number")) {
+        lines.push(
+          `  live: ${perf.live.active_requests ?? 0} active request(s)` +
+            (typeof perf.live.estimated_tokens_per_second === "number"
+              ? ` · ${(perf.live.estimated_tokens_per_second || 0).toFixed(1)} tok/s (whole box)`
+              : "")
+        );
+      }
       if (lifetime.length) lines.push(`Lifetime: ${lifetime.join(" · ")}`);
       if (typeof perf.routing_decisions_total === "number" || typeof perf.routing_switches_total === "number") {
         lines.push(
@@ -2937,6 +3963,751 @@ async function addInstanceFlow(
   return nameInput;
 }
 
+// ─── Model browser, downloads, backends, updates (lemonade ≥2026.46 TUI) ────
+
+/** One live snapshot of everything the model browser shows. */
+interface BrowserState {
+  catalog: LemonadeModel[];
+  /** Loaded models by name, with load state (status/pinned/busy/backend). */
+  loaded: Map<string, LoadedModelInfo>;
+  /** Server-owned download jobs, or null when the box was unreachable. */
+  jobs: DownloadJob[] | null;
+  /** False when health didn't answer — the snapshot may be partial. */
+  reachable: boolean;
+}
+
+async function fetchBrowserState(config: LemonadeConfig): Promise<BrowserState> {
+  const [health, jobs, catalog] = await Promise.all([
+    fetchHealth(config),
+    listDownloads(config),
+    fetchCatalog(config, true).catch(() => [] as LemonadeModel[]),
+  ]);
+  const loaded = new Map<string, LoadedModelInfo>();
+  for (const m of health?.all_models_loaded ?? []) loaded.set(m.model_name, m);
+  return { catalog, loaded, jobs, reachable: health != null };
+}
+
+/** The download job (if any) currently downloading a model. */
+function jobForModel(state: BrowserState, id: string): DownloadJob | undefined {
+  return (state.jobs ?? []).find((j) => j.model_name === id && j.status !== "completed" && j.status !== "error" && j.status !== "cancelled");
+}
+
+/** Inline status glyph for one catalog row. */
+function modelGlyph(m: LemonadeModel, state: BrowserState): string {
+  const job = jobForModel(state, m.id);
+  if (job) return job.status === "paused" ? "⏸" : "↓";
+  if (state.loaded.has(m.id)) return "●";
+  if (m.downloaded === false) return "◌";
+  return "○";
+}
+
+const MODEL_ORDER = (m: LemonadeModel, state: BrowserState): number => {
+  const job = jobForModel(state, m.id);
+  if (job && job.status !== "paused") return 0; // actively downloading first
+  if (job) return 1; // paused
+  if (state.loaded.has(m.id)) return 2;
+  if (m.downloaded === false) return 4;
+  return 3; // downloaded, not loaded
+};
+
+/** Build the browser's live menu items from one snapshot. */
+function browserItems(state: BrowserState, downloadedOnly: boolean): MenuItem<string>[] {
+  const models = state.catalog
+    .filter((m) => !downloadedOnly || m.downloaded !== false)
+    .sort((a, b) => MODEL_ORDER(a, state) - MODEL_ORDER(b, state) || a.id.localeCompare(b.id));
+  return models.map((m) => {
+    const job = jobForModel(state, m.id);
+    const info = state.loaded.get(m.id);
+    const bits: string[] = [];
+    if (job) bits.push(`${job.status === "paused" ? "download paused" : `downloading ${typeof job.percent === "number" ? job.percent.toFixed(0) : "?"}%`}${typeof job.total_download_size === "number" ? ` of ${formatBytes(job.total_download_size)}` : ""}`);
+    if (info) {
+      bits.push(
+        `loaded (${info.status ?? "ready"}${info.backend_health && info.backend_health !== "ready" ? `, backend ${info.backend_health}` : ""})` +
+          `${info.pinned ? " · pinned" : ""}${info.is_busy || info.is_streaming ? " · busy" : ""}`
+      );
+    }
+    if (m.downloaded === false) bits.push("not downloaded");
+    if (m.update_available) bits.push("⤴ update available");
+    if ((m.labels ?? []).includes("on-demand")) bits.push("on-demand (no load — serves its endpoint directly)");
+    const ctx = m.context_length ?? m.max_context_window;
+    bits.push(
+      [
+        m.size !== undefined ? `${m.size} GB` : undefined,
+        ctx ? `ctx ${ctx.toLocaleString("en-US")}` : undefined,
+        m.recipe,
+        ...(m.labels ?? []).filter((l) => ![
+          "chat", "hot", "on-demand", "custom", "image", "edit",
+        ].includes(l)).slice(0, 4),
+      ]
+        .filter(Boolean)
+        .join(" • ")
+    );
+    return {
+      value: m.id,
+      label: `${modelGlyph(m, state)} ${m.id}${(m.labels ?? []).includes("hot") ? " ★" : ""}${m.update_available ? " ⤴" : ""}`,
+      description: bits.join(" — "),
+    };
+  });
+}
+
+/** Full model detail sheet (textView): everything the server knows. */
+async function modelDetails(ctx: UiCtx, config: LemonadeConfig, m: LemonadeModel, state: BrowserState): Promise<void> {
+  const info = state.loaded.get(m.id);
+  const job = (state.jobs ?? []).find((j) => j.model_name === m.id);
+  const lines: string[] = [
+    `Model: ${m.id}`,
+    `Recipe: ${m.recipe ?? "?"}${(m.labels ?? []).length ? `  ·  labels: ${m.labels!.join(", ")}` : ""}`,
+    `Checkpoint: ${m.checkpoint ?? "?"}`,
+    ...(Object.entries(m.checkpoints ?? {} as Record<string, string>).length
+      ? ["Checkpoints:", ...Object.entries(m.checkpoints as Record<string, string>).map(([k, v]) => `  ${k}: ${v}`)]
+      : []),
+  ];
+  if (m.checkpoint_status?.length) {
+    lines.push("Checkpoint files:");
+    for (const cs of m.checkpoint_status) {
+      lines.push(`  ${cs.type ?? "?"}: ${cs.present ? "present" : "MISSING"}${cs.required === false ? " (optional)" : ""} [${cs.registry ?? "local"}]`);
+    }
+  }
+  lines.push(
+    `Size: ${m.size !== undefined ? `${m.size} GB` : "?"}  ·  Downloaded: ${m.downloaded === false ? "no" : "yes"}` +
+      (m.update_available ? "  ·  ⤴ UPDATE AVAILABLE" : ""),
+    `Context: ${m.context_length ? `${m.context_length.toLocaleString("en-US")} (live)` : "?"}${m.max_context_window ? ` / max ${m.max_context_window.toLocaleString("en-US")}` : ""}`
+  );
+  if (Object.keys(m.recipe_options ?? {}).length) {
+    lines.push("Recipe options (saved): " + JSON.stringify(m.recipe_options));
+  }
+  if (info) {
+    lines.push(
+      "",
+      "Loaded state:",
+      `  status: ${info.status ?? "?"} · device: ${info.device ?? "?"} · backend: ${info.backend_health ?? "?"}`,
+      `  pinned: ${info.pinned ? "yes" : "no"} · busy: ${info.is_busy ? "yes" : "no"} · streaming: ${info.is_streaming ? "yes" : "no"}`,
+      ...(info.pid ? [`  pid: ${info.pid}`] : []),
+      ...(info.slot_pool ? [`  slot pool: ${info.slot_pool} (${info.residency_class ?? "standard"})`] : []),
+      ...(info.launch_command ? ["  launch: " + info.launch_command.join(" ")] : []),
+      ...(info.watchdog_reset_reason ? [`  watchdog reset: ${info.watchdog_reset_reason}`] : [])
+    );
+  }
+  if (job) {
+    lines.push(
+      "",
+      `Download job ${job.id}: ${job.status}${typeof job.percent === "number" ? ` — ${job.percent.toFixed(1)}%` : ""}`,
+      ...(job.error ? [`  error: ${job.error}`] : [])
+    );
+  }
+  await textView(ctx, `Model — ${m.id}`, lines, true);
+}
+
+/** The per-model action menu: everything you can do with a model, offered
+ *  contextually from its live state. */
+async function modelActions(
+  ctx: UiCtx,
+  pi: ExtensionAPI,
+  config: LemonadeConfig,
+  fullConfig: LemonadeConfig,
+  id: string
+): Promise<void> {
+  for (;;) {
+    const state = await fetchBrowserState(config); // fresh state per action
+    if (!state.reachable) {
+      ctx.ui.notify(`Lemonade server at ${config.baseUrl} is unreachable right now — actions need a live box.`, "error");
+      return;
+    }
+    const m = state.catalog.find((x) => x.id === id);
+    if (!m) {
+      ctx.ui.notify(`"${id}" is no longer in the catalog (deleted or renamed?).`, "warning");
+      return;
+    }
+    const info = state.loaded.get(id);
+    const job = jobForModel(state, id);
+    const labels = m.labels ?? [];
+    const onDemand = labels.includes("on-demand");
+
+    const items: MenuItem<string>[] = [
+      { value: "view", label: "View details", description: "Checkpoints, context, load state, launch command" },
+    ];
+    if (job) {
+      items.push({
+        value: "canceljob",
+        label: `Cancel download (${typeof job.percent === "number" ? `${job.percent.toFixed(0)}%` : "?"})`,
+        description: "Partial files stay on disk; a later pull resumes from them",
+      });
+    }
+    if (!info && !onDemand && m.downloaded !== false) {
+      items.push({ value: "load", label: "Load into memory", description: "May take minutes — esc continues in background" });
+    }
+    if (info) {
+      items.push({ value: "unload", label: "Unload", description: "Free its slot (evictable again)" });
+      items.push({
+        value: "pin",
+        label: info.pinned ? "Unpin" : "Pin",
+        description: info.pinned
+          ? "Pinned models are skipped by LRU eviction — unpin to make it evictable"
+          : "Skip LRU eviction while loaded (admin key)",
+      });
+    }
+    if (m.downloaded === false && !job) {
+      items.push({ value: "pull", label: "Pull (download)", description: m.size !== undefined ? `~${m.size} GB — live progress, esc cancels` : "Live progress, esc cancels" });
+    }
+    if (m.update_available) {
+      items.push({ value: "update", label: "⤴ Update to latest commit", description: "Re-pulls from the registry — live progress" });
+    }
+    items.push({ value: "options", label: "Recipe options", description: `ctx size, backend, args — saved per model (recipe: ${m.recipe ?? "?"})` });
+    if (m.downloaded !== false) {
+      items.push({ value: "delete", label: "Delete from disk", description: "Typed-phrase confirmation required" });
+    }
+    if (onDemand) {
+      items.push({ value: "ondemand", label: "Why no Load?", description: "on-demand models serve their endpoint directly, with no resident server" });
+    }
+    items.push({ value: "back", label: "Back", description: "" });
+
+    const action = await menu(ctx, `${modelGlyph(m, state)} ${id}`, items);
+    if (action === null || action === "back") return;
+
+    if (action === "view") {
+      await modelDetails(ctx, config, m, state);
+    } else if (action === "ondemand") {
+      ctx.ui.notify(
+        "on-demand models (e.g. built-in upscalers) have no resident model server: " +
+          "/v1/load is not supported. They run through their task endpoint (e.g. /v1/images/upscale) " +
+          "when a tool calls them.",
+        "info"
+      );
+    } else if (action === "canceljob" && job) {
+      const ok = await ctx.ui.confirm(`Cancel the download of ${id}?`, "Partial files stay on disk; a later pull resumes from them.");
+      if (!ok) continue;
+      const [succeeded, msg] = await withStatus(ctx, `Cancelling ${job.id}…`, () =>
+        controlDownload(config, job.id, "cancel").then(() => `Download of ${id} cancelled.`)
+      );
+      ctx.ui.notify(msg, succeeded ? "info" : "error");
+    } else if (action === "load") {
+      const outcome = await busyView(ctx, `Loading ${id}…`, () => loadModel(config, id), {
+        escDetach: true,
+        liveStatus: async () => {
+          const h = await fetchHealth(config);
+          const me = (h?.all_models_loaded ?? []).find((x) => x.model_name === id);
+          if (!me) return "server: preparing load…";
+          return `server: ${me.status ?? "loading"}${me.device ? ` on ${me.device}` : ""}${me.is_busy ? " · busy" : ""}`;
+        },
+      });
+      if (outcome.detached) {
+        ctx.ui.notify(`Load of ${id} continues in the background — the browser will show it live.`, "info");
+      } else if (outcome.error) {
+        ctx.ui.notify(`Load failed: ${outcome.error}`, "error");
+      } else {
+        ctx.ui.notify(`Loaded ${id}.`, "info");
+      }
+      await registerLemonadeProvider(pi, fullConfig);
+    } else if (action === "unload") {
+      const outcome = await busyView(ctx, `Unloading ${id}…`, () => unloadModel(config, id).then(() => "unloaded"));
+      if (outcome.error) ctx.ui.notify(`Unload failed: ${outcome.error}`, "error");
+      else {
+        ctx.ui.notify(`Unloaded ${id}.`, "info");
+        await registerLemonadeProvider(pi, fullConfig);
+      }
+    } else if (action === "pin" && info) {
+      const target = !info.pinned;
+      const outcome = await busyView(ctx, `${target ? "Pinning" : "Unpinning"} ${id}…`, () =>
+        setPinned(config, id, target).then(() => "pinned")
+      );
+      if (outcome.error) ctx.ui.notify(outcome.error, "error");
+      else ctx.ui.notify(`${id} ${target ? "pinned — LRU eviction will skip it" : "unpinned — evictable again"}.`, "info");
+    } else if (action === "pull") {
+      const ok = await ctx.ui.confirm(
+        `Pull ${id}?`,
+        m.size !== undefined ? `Downloads ~${m.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, config, id);
+      ctx.ui.notify(msg, succeeded ? "info" : "error");
+    } else if (action === "update") {
+      const ok = await ctx.ui.confirm(
+        `Update ${id}?`,
+        "Downloads the model's newer registry commit (the current copy stays until the pull lands)."
+      );
+      if (!ok) continue;
+      const [succeeded, msg] = await pullWithProgress(ctx, pi, config, id);
+      ctx.ui.notify(msg, succeeded ? "info" : "error");
+    } else if (action === "delete") {
+      const ok = await ctx.ui.confirm(
+        `Delete ${id}?`,
+        "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 ${id.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 ${id} aborted.`, "warning");
+        continue;
+      }
+      const outcome = await busyView(ctx, `Deleting ${id}…`, () => deleteModel(config, id));
+      if (outcome.error) ctx.ui.notify(`Delete failed: ${outcome.error}`, "error");
+      else {
+        ctx.ui.notify(`Deleted ${id} from disk.`, "info");
+        await registerLemonadeProvider(pi, fullConfig);
+      }
+      return; // the model is gone — leave the action loop
+    } else if (action === "options") {
+      await recipeOptionsEditor(ctx, pi, config, fullConfig, id);
+    }
+  }
+}
+
+/** Parse a typed option value the way the API expects: ""/"auto" → null
+ *  (tombstone, fall through the priority chain), numbers as numbers, booleans
+ *  as booleans, anything else as the raw string. ctx_size keeps -1 (auto). */
+function parseOptionValue(raw: string, key: string): unknown {
+  const t = raw.trim();
+  if (t === "" || t.toLowerCase() === "auto" || t.toLowerCase() === "null") return null;
+  if (key === "ctx_size" && t === "-1") return -1;
+  if (t === "true" || t === "false") return t === "true";
+  if (/^-?\d+(\.\d+)?$/.test(t)) return Number(t);
+  return t;
+}
+
+/** Per-model recipe options editor: read the saved/effective/defaults layers,
+ *  edit one key at a time (saved immediately), reset to defaults, and reload
+ *  a loaded model to apply. Works on unloaded models too — options take
+ *  effect at the next load. */
+async function recipeOptionsEditor(
+  ctx: UiCtx,
+  pi: ExtensionAPI,
+  config: LemonadeConfig,
+  fullConfig: LemonadeConfig,
+  id: string
+): Promise<void> {
+  for (;;) {
+    let layers: ModelOptionsLayers;
+    try {
+      layers = await fetchModelOptions(config, id);
+    } catch (error) {
+      ctx.ui.notify(`Could not read options for ${id}: ${error instanceof Error ? error.message : String(error)}`, "error");
+      return;
+    }
+    const saved = layers.saved ?? {};
+    const effective = layers.effective ?? {};
+    const defaults = layers.defaults ?? {};
+    const keys = Array.from(new Set([...Object.keys(defaults), ...Object.keys(effective), ...Object.keys(saved)])).sort();
+
+    const items: MenuItem<string>[] = keys.map((k) => ({
+      value: k,
+      label: k,
+      description:
+        `saved: ${k in saved ? JSON.stringify(saved[k]) : "(default)"} · effective: ${JSON.stringify(effective[k] ?? defaults[k] ?? null)}`,
+    }));
+    items.push({ value: "__reset__", label: "Reset ALL saved options", description: "DELETE every saved key — back to recipe defaults" });
+    items.push({ value: "__back__", label: "Back", description: "" });
+
+    const key = await filterMenu(ctx, {
+      title: `Recipe Options — ${id} (recipe: ${layers.recipe ?? "?"}, ${Object.keys(saved).length} saved)`,
+      items,
+      banner: `ctx_size: -1 = auto · ""/"auto" clears a key · edits save immediately`,
+      maxVisible: 12,
+    });
+    if (key === null || key === "__back__") return;
+
+    if (key === "__reset__") {
+      const ok = await ctx.ui.confirm(
+        `Reset every saved option for ${id}?`,
+        "All saved recipe options are deleted; the model falls back to its defaults."
+      );
+      if (!ok) continue;
+      const outcome = await busyView(ctx, `Resetting options for ${id}…`, () => resetModelOptions(config, id));
+      if (outcome.error) ctx.ui.notify(`Reset failed: ${outcome.error}`, "error");
+      else ctx.ui.notify(`Saved options for ${id} reset to defaults.`, "info");
+      continue;
+    }
+
+    // Value entry: backend selectors get a menu of what this system supports;
+    // ctx_size accepts 32k/1m shorthand; everything else is free text.
+    let value: unknown;
+    let cancelled = false;
+    if (/_backend$/.test(key)) {
+      let choices: string[] = [];
+      try {
+        const sysinfo = await fetchJsonOrNull<SystemInfo>(config, "/v1/system-info");
+        const recipe = layers.recipe ?? "";
+        choices = Object.keys(sysinfo?.recipes?.[recipe]?.backends ?? {});
+      } catch {
+        /* fall back to free text */
+      }
+      if (choices.length) {
+        const picked = await menu(ctx, `${id} → ${key}`, [
+          ...choices.map((b) => ({ value: b, label: b, description: `effective: ${JSON.stringify(effective[key] ?? defaults[key] ?? null)}` })),
+          { value: "__clear__", label: "(clear — use the default)", description: "" },
+        ]);
+        if (picked === null) cancelled = true;
+        else value = picked === "__clear__" ? null : picked;
+      }
+    }
+    if (!cancelled && value === undefined) {
+      const current = key in saved ? String(saved[key]) : "";
+      const input = await ctx.ui.input(
+        `${id} → ${key} (empty/auto = clear the saved value${key === "ctx_size" ? "; -1 = auto-size" : ""}):`,
+        key === "ctx_size" ? String(effective.ctx_size ?? "") : current
+      );
+      if (input === undefined) cancelled = true;
+      else if (key === "ctx_size") {
+        const parsed = input.trim() === "" ? null : parseCtxSize(input);
+        if (parsed === null) {
+          ctx.ui.notify("Invalid size — use e.g. 32k, 1m, 262144, -1 (auto), or empty to clear.", "warning");
+          continue;
+        }
+        value = parsed;
+      } else {
+        value = parseOptionValue(input, key);
+      }
+    }
+    if (cancelled) continue;
+
+    const outcome = await busyView(ctx, `Saving ${key} for ${id}…`, () =>
+      saveModelOptions(config, id, { [key]: value })
+    );
+    if (outcome.error) {
+      ctx.ui.notify(`Save failed: ${outcome.error}`, "error");
+      continue;
+    }
+    ctx.ui.notify(
+      `${key} saved for ${id}${value === null ? " (cleared — falls back to defaults)" : `: ${JSON.stringify(value)}`}.`,
+      "info"
+    );
+
+    // A loaded model keeps running with its old options — offer an apply.
+    const h = await fetchHealth(config);
+    if ((h?.all_models_loaded ?? []).some((x) => x.model_name === id)) {
+      const apply = await ctx.ui.confirm(
+        `${id} is loaded — reload it now to apply the new options?`,
+        "The server reloads a model whose load-time options changed (saved options persist either way)."
+      );
+      if (apply) {
+        const loadOutcome = await busyView(ctx, `Reloading ${id}…`, () => loadModel(config, id), { escDetach: true });
+        if (loadOutcome.detached) ctx.ui.notify(`Reload of ${id} continues in the background.`, "info");
+        else if (loadOutcome.error) ctx.ui.notify(`Reload failed: ${loadOutcome.error}`, "error");
+        else ctx.ui.notify(`Reloaded ${id} with the new options.`, "info");
+        await registerLemonadeProvider(pi, fullConfig);
+      }
+    }
+  }
+}
+
+/** Server-owned download jobs: live list with per-job actions. Terminal jobs
+ *  (errored/cancelled) linger on the server until a client removes them —
+ *  this is the view that removes them, and the retry path resumes the
+ *  partial files that stayed on disk. */
+async function downloadsManager(ctx: UiCtx, pi: ExtensionAPI, config: LemonadeConfig): Promise<void> {
+  for (;;) {
+    const picked = await filterMenu<string>(ctx, {
+      title: "Downloads (server-owned jobs)",
+      items: [], // replaced by the first refetch; also handles the empty case
+      refetch: async () => {
+        const jobs = (await listDownloads(config)) ?? [];
+        const items: MenuItem<string>[] = jobs
+          .map((j) => ({
+            value: j.id,
+            label: `${j.running ? "↓" : j.status === "error" ? "✗" : j.status === "paused" ? "⏸" : j.status === "cancelled" ? "∅" : "✓"} ${j.id} — ${j.status}${typeof j.percent === "number" ? ` ${j.percent.toFixed(0)}%` : ""}`,
+            description: [
+              j.model_name,
+              typeof j.total_download_size === "number" ? formatBytes(j.total_download_size) : undefined,
+              j.file ? `file ${j.file_index ?? "?"}/${j.total_files ?? "?"}: ${j.file}` : undefined,
+              j.error ? `error: ${j.error.slice(0, 100)}` : undefined,
+            ]
+              .filter(Boolean)
+              .join(" • "),
+          }))
+          .sort((a, b) => a.label.localeCompare(b.label));
+        items.push({ value: "__clear__", label: "✕ Remove all stopped jobs", description: "Clears errored/cancelled/completed entries from the server's list (files on disk are untouched)" });
+        items.push({ value: "__back__", label: "Back", description: "" });
+        return items;
+      },
+      pollMs: 1500,
+      hint: "live",
+    });
+    if (picked === null || picked === "__back__") return;
+
+    if (picked === "__clear__") {
+      const jobs = (await listDownloads(config)) ?? [];
+      const stopped = jobs.filter((j) => !j.running);
+      if (!stopped.length) {
+        ctx.ui.notify("No stopped jobs to remove.", "info");
+        continue;
+      }
+      const ok = await ctx.ui.confirm(
+        `Remove ${stopped.length} stopped job${stopped.length === 1 ? "" : "s"}?`,
+        "Removes them from the server's job list only — partial downloads stay on disk and resume on the next pull."
+      );
+      if (!ok) continue;
+      const outcome = await busyView(ctx, `Removing ${stopped.length} stopped job(s)…`, async () => {
+        for (const j of stopped) {
+          try {
+            await controlDownload(config, j.id, "remove");
+          } catch {
+            /* already gone — removal is idempotent */
+          }
+        }
+      });
+      if (outcome.error) ctx.ui.notify(outcome.error, "error");
+      else ctx.ui.notify(`Removed ${stopped.length} stopped job(s) from the list.`, "info");
+      continue;
+    }
+
+    // Per-job actions
+    const jobs = (await listDownloads(config)) ?? [];
+    const job = jobs.find((j) => j.id === picked);
+    if (!job) {
+      ctx.ui.notify("That job is no longer listed.", "warning");
+      continue;
+    }
+    const items: MenuItem<string>[] = [];
+    if (job.running) {
+      items.push({ value: "cancel", label: "Cancel", description: "Stop the download — partial files stay, a later pull resumes" });
+      items.push({ value: "pause", label: "Pause", description: "Stop the worker, keep the job listed as paused" });
+    } else {
+      items.push({ value: "remove", label: "Remove from list", description: "Clear the finished/failed entry (files untouched)" });
+      if (job.model_name && (job.status === "error" || job.status === "cancelled")) {
+        items.push({ value: "retry", label: "Retry pull", description: "Re-pulls — resumes from the partial files on disk" });
+      }
+    }
+    items.push({ value: "back", label: "Back", description: "" });
+    const action = await menu(ctx, `${job.id} — ${job.status}`, items);
+    if (action === null || action === "back") continue;
+
+    if (action === "cancel" || action === "pause" || action === "remove") {
+      const outcome = await busyView(ctx, `${action} ${job.id}…`, () => controlDownload(config, job.id, action));
+      if (outcome.error) ctx.ui.notify(outcome.error, "error");
+      else ctx.ui.notify(`${job.id}: ${action} sent.`, "info");
+    } else if (action === "retry" && job.model_name) {
+      const [succeeded, msg] = await pullWithProgress(ctx, pi, config, job.model_name);
+      ctx.ui.notify(msg, succeeded ? "info" : "error");
+    }
+  }
+}
+
+/** Backend browser: every recipe × backend on this system with its install
+ *  state; install (with live download progress) or uninstall from here. */
+async function backendsView(ctx: UiCtx, pi: ExtensionAPI, config: LemonadeConfig): Promise<void> {
+  const flatten = (sysinfo: SystemInfo | null): Array<{ recipe: string; backend: string; info: BackendInfo; isDefault: boolean }> => {
+    const out: Array<{ recipe: string; backend: string; info: BackendInfo; isDefault: boolean }> = [];
+    for (const [recipe, r] of Object.entries(sysinfo?.recipes ?? {})) {
+      for (const [backend, info] of Object.entries(r.backends ?? {})) {
+        out.push({ recipe, backend, info, isDefault: r.default_backend === backend });
+      }
+    }
+    const rank = (s: string | undefined): number => (s === "installed" ? 0 : s === "installable" ? 1 : 2);
+    return out.sort(
+      (a, b) => rank(a.info.state) - rank(b.info.state) || `${a.recipe}:${a.backend}`.localeCompare(`${b.recipe}:${b.backend}`)
+    );
+  };
+
+  for (;;) {
+    const picked = await filterMenu<string>(ctx, {
+      title: "Backends (recipe × backend, live from system-info)",
+      items: [],
+      refetch: async () => {
+        const sysinfo = await fetchJsonOrNull<SystemInfo>(config, "/v1/system-info");
+        const flat = flatten(sysinfo);
+        const items: MenuItem<string>[] = flat.map((b) => ({
+          value: `${b.recipe}:${b.backend}`,
+          label: `${b.info.state === "installed" ? "●" : b.info.state === "installable" ? "○" : "⊘"} ${b.recipe}:${b.backend}${b.isDefault ? " (default)" : ""}`,
+          description: [
+            b.info.state,
+            b.info.tier ? `tier: ${b.info.tier}` : undefined,
+            b.info.version ? `v: ${b.info.version}` : undefined,
+            b.info.format,
+            b.info.message || undefined,
+          ]
+            .filter(Boolean)
+            .join(" • "),
+        }));
+        items.push({ value: "__back__", label: "Back", description: "" });
+        return items;
+      },
+      pollMs: 2500,
+      hint: "live",
+      banner: "models whose recipe has only guest-tier backends stay hidden from the catalog until one is installed",
+    });
+    if (picked === null || picked === "__back__") return;
+
+    const [recipe, backend] = picked.split(":", 2);
+    const sysinfo = await fetchJsonOrNull<SystemInfo>(config, "/v1/system-info");
+    const info = sysinfo?.recipes?.[recipe]?.backends?.[backend];
+    if (!info) {
+      ctx.ui.notify("That backend disappeared from system-info — refresh and retry.", "warning");
+      continue;
+    }
+
+    const items: MenuItem<string>[] = [];
+    if (info.state === "installable") {
+      items.push({ value: "install", label: `Install ${recipe}:${backend}`, description: "Downloads + installs — live progress, esc cancels the download" });
+    }
+    if (info.state === "installed" && info.can_uninstall !== false) {
+      items.push({ value: "uninstall", label: `Uninstall ${recipe}:${backend}`, description: "Models needing it can no longer load — the files are removed" });
+    }
+    if (info.action) items.push({ value: "cli", label: "CLI equivalent", description: info.action });
+    if (!items.length) items.push({ value: "noop", label: `Not available on this system (${info.state})`, description: info.message ?? "" });
+    items.push({ value: "back", label: "Back", description: "" });
+    const action = await menu(ctx, `${recipe}:${backend} — ${info.state}${info.tier ? ` (tier: ${info.tier})` : ""}`, items);
+    if (action === null || action === "back" || action === "noop" || action === "cli") continue;
+
+    if (action === "install") {
+      let preview: Record<string, unknown> | undefined;
+      const dry = await busyView(ctx, `Resolving ${recipe}:${backend}…`, () => installBackendDryRun(config, recipe, backend));
+      if (dry.error) {
+        ctx.ui.notify(`Install dry-run failed: ${dry.error}`, "error");
+        continue;
+      }
+      preview = dry.result;
+      const ok = await ctx.ui.confirm(
+        `Install ${recipe}:${backend}?`,
+        `Downloads ${String(preview?.download_filename ?? "the backend asset")} (v ${String(preview?.version ?? "?")}) and installs it on the server.`
+      );
+      if (!ok) continue;
+      let job: DownloadJob;
+      const start = await busyView(ctx, `Starting install of ${recipe}:${backend}…`, () =>
+        installBackendJob(config, recipe, backend)
+      );
+      if (start.error) {
+        ctx.ui.notify(`Install failed to start: ${start.error}`, "error");
+        continue;
+      }
+      job = start.result!;
+      const outcome = await trackDownload(ctx, config, job.id, `${recipe}:${backend}`);
+      ctx.ui.notify(
+        outcome === "complete"
+          ? `Installed ${recipe}:${backend}.`
+          : outcome === "cancelled"
+            ? `Install of ${recipe}:${backend} cancelled.`
+            : `Install of ${recipe}:${backend} failed.`,
+        outcome === "complete" ? "info" : "error"
+      );
+    } else if (action === "uninstall") {
+      const ok = await ctx.ui.confirm(
+        `Uninstall ${recipe}:${backend}?`,
+        "Removes the backend from the server — models that need it can no longer load until it is installed again."
+      );
+      if (!ok) continue;
+      const outcome = await busyView(ctx, `Uninstalling ${recipe}:${backend}…`, () =>
+        uninstallBackend(config, recipe, backend)
+      );
+      if (outcome.error) ctx.ui.notify(`Uninstall failed: ${outcome.error}`, "error");
+      else ctx.ui.notify(`Uninstalled ${recipe}:${backend}.`, "info");
+    }
+  }
+}
+
+/** Model-update flow: check what has newer upstream commits, then bulk-sync
+ *  (admin key) or update one at a time via plain pulls. */
+async function updatesFlow(ctx: UiCtx, pi: ExtensionAPI, config: LemonadeConfig, fullConfig: LemonadeConfig): Promise<void> {
+  const check = await busyView(ctx, "Checking every downloaded model for updates…", () => checkModelUpdates(config));
+  if (check.error) {
+    ctx.ui.notify(`Update check failed: ${check.error}`, "error");
+    return;
+  }
+  const result = check.result!;
+  const models = result.models ?? [];
+  if (!models.length) {
+    ctx.ui.notify("All downloaded models are up to date.", "info");
+    return;
+  }
+  const failures = Object.entries(result.failed_models ?? {});
+  const choice = await menu(ctx, `Updates Available — ${models.length} model(s)`, [
+    ...models.map((m) => ({ value: m, label: `⤴ ${m}`, description: "newer upstream commit available" })),
+    { value: "__all__", label: `Update all ${models.length} (bulk sync — needs the admin key)`, description: "One server job checks + downloads every update" },
+    { value: "__back__", label: "Back", description: "" },
+  ]);
+  if (choice === null || choice === "__back__") return;
+
+  if (choice === "__all__") {
+    const outcome = await busyView(ctx, "Syncing model updates…", () => syncModelUpdates(config, { models }), {
+      liveStatus: async () => {
+        const h = await fetchHealth(config);
+        const sync = h?.model_sync;
+        return sync ? `server: sync ${sync.sync_id ?? "?"} — ${sync.status ?? "?"}` : null;
+      },
+    });
+    if (outcome.error) {
+      ctx.ui.notify(outcome.error, "error");
+      return;
+    }
+    const r = outcome.result!;
+    const updated = r.models_updated ?? [];
+    const failed = Object.entries(r.failed_models ?? {});
+    ctx.ui.notify(
+      `Sync ${r.status ?? "done"}: ${updated.length} updated${updated.length ? ` (${updated.join(", ")})` : ""}` +
+        (failed.length ? ` · ${failed.length} failed: ${failed.map(([k, v]) => `${k} (${String(v).slice(0, 60)})`).join(", ")}` : ""),
+      updated.length || !failed.length ? "info" : "warning"
+    );
+    await registerLemonadeProvider(pi, fullConfig);
+    return;
+  }
+
+  // Single model: plain pull (no admin key needed) with live progress.
+  const ok = await ctx.ui.confirm(
+    `Update ${choice}?`,
+    "Downloads the model's newer registry commit — live progress, esc cancels."
+  );
+  if (!ok) return;
+  const [succeeded, msg] = await pullWithProgress(ctx, pi, config, choice);
+  ctx.ui.notify(msg, succeeded ? "info" : "error");
+  if (failures.length) {
+    ctx.ui.notify(`Also failed to check: ${failures.map(([k]) => k).join(", ")}`, "warning");
+  }
+}
+
+/** The single model browser: every model on the box, live status inline,
+ *  type-to-search, ctrl+t toggles all/downloaded, actions on select. The
+ *  list refreshes underneath you every couple of seconds — loads, downloads
+ *  and state flips appear without leaving the view. */
+async function modelBrowser(
+  ctx: UiCtx,
+  pi: ExtensionAPI,
+  config: LemonadeConfig,
+  fullConfig: LemonadeConfig,
+  instanceName: string
+): Promise<void> {
+  let downloadedOnly = false;
+  for (;;) {
+    const picked = await filterMenu<string>(ctx, {
+      title: `Model Browser — ${instanceName}`,
+      // Placeholder until the first refetch lands; unreachable boxes keep
+      // the last good list (refetch throws → snapshot preserved).
+      items: [{ value: "__loading__", label: "loading catalog…", description: "" }],
+      refetch: async () => {
+        const state = await fetchBrowserState(config);
+        if (!state.reachable || (!state.catalog.length && !state.loaded.size)) throw new Error("unreachable");
+        return browserItems(state, downloadedOnly);
+      },
+      pollMs: 2000,
+      hint: "ctrl+t all/downloaded · live",
+      banner: "● loaded · ○ downloaded · ○ not on disk · ↓ downloading · ⤴ update · ctrl+t toggles all ⇄ downloaded",
+      onKey: (data, api) => {
+        if (matchesKey(data, Key.ctrl("t"))) {
+          downloadedOnly = !downloadedOnly;
+          api.setBanner(
+            downloadedOnly
+              ? "showing: DOWNLOADED models only — ctrl+t shows every catalog entry again"
+              : "● loaded · ○ downloaded · ○ not on disk · ↓ downloading · ⤴ update · ctrl+t toggles all ⇄ downloaded"
+          );
+          return true;
+        }
+        return false;
+      },
+    });
+    if (picked === null) return; // Esc/back
+    if (picked === "__loading__") continue;
+    await modelActions(ctx, pi, config, fullConfig, picked);
+  }
+}
+
 function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeConfig }): void {
   pi.registerCommand("lemonade-setup", {
     description: "Lemonade server: status, discovery, endpoints, models, tools, transcription",
@@ -2996,16 +4767,94 @@ function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeCo
         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: "server", label: "Server settings", description: "Discover, base URL, API/admin keys, instances, connection test" },
+          { value: "models", label: "Model management", description: `Model browser (live status, type-to-search, actions), downloads, HF install, updates — active instance: ${activeInstance}` },
+          { value: "backends", label: "Backends", description: "Recipe × backend inventory — install/uninstall with live progress" },
           { 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: "spec", label: "Spec & version check", description: "Docs drift + live server-version drift — status, re-check, re-sync, toggles" },
+          { value: "refresh", label: "Refresh connection", description: "Force a re-probe of every instance now and re-register (bypasses the outage-resync throttle)" },
+          { value: "cache", label: "Catalog cache", description: `Outage listings (cacheOnOutage: ${config.cacheOnOutage ? "on" : "off"}) — cached catalog snapshots: status, toggle, clear` },
           { 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;
 
+        // ── Refresh connection (manual outage re-sync) ──────────────────
+        if (choice === "refresh") {
+          const [ok, msg] = await withStatus(ctx, "Probing instances…", async () => {
+            const n = await resyncFromOutage(pi, configRef, undefined, true);
+            if (n < 0) return "A re-sync is already in flight — try again in a moment.";
+            return cachedServing.size
+              ? `Refreshed — ${n} model(s) registered; ${cachedServing.size} instance(s) unreachable, serving cached catalogs.`
+              : `Refreshed — ${n} model(s) registered.`;
+          });
+          ctx.ui.notify(msg, ok ? "info" : "error");
+          continue;
+        }
+
+        // ── Catalog cache (outage listings) ─────────────────────
+        if (choice === "cache") {
+          for (;;) {
+            const config = configRef.current;
+            const cache = loadCatalogCache();
+            const entries = Object.entries(cache.instances).sort(([a], [b]) => a.localeCompare(b));
+            const state = !config.cacheOnOutage
+              ? "disabled (cacheOnOutage: false) — catalogs are neither cached nor served"
+              : entries.length
+                ? entries.map(([name, e]) => `${name}: ${e.catalog.length} model(s) cached ${formatCacheStamp(e.fetchedAt)}`).join(" · ")
+                : "enabled — no snapshots yet (written on every successful probe)";
+            const sub = await menu(ctx, "Catalog Cache — Outage Listings", [
+              { value: "status", label: "Status", description: state },
+              {
+                value: "toggle",
+                label: `Toggle outage cache: ${config.cacheOnOutage ? "on → off" : "off → on"}`,
+                description: `cacheOnOutage (currently ${config.cacheOnOutage ? "on" : "off"}) — when a probe fails, list the instance's last good catalog, provenance-marked "(cached …)"`,
+              },
+              {
+                value: "clear",
+                label: "Clear cached catalogs",
+                description: "Drop the on-disk snapshots — unreachable instances then list nothing",
+              },
+              { value: "back", label: "Back", description: "" },
+            ]);
+            if (sub === null || sub === "back") break;
+
+            if (sub === "toggle") {
+              config.cacheOnOutage = !config.cacheOnOutage;
+              saveConfig(config);
+              ctx.ui.notify(
+                `Outage cache ${config.cacheOnOutage ? "on" : "off"} — takes effect at the next registration (Refresh connection applies it now).`,
+                "info"
+              );
+              continue;
+            }
+            if (sub === "clear") {
+              clearCatalogCache();
+              ctx.ui.notify(
+                "Cached catalogs cleared — unreachable instances will list nothing from the next registration on (Refresh connection applies it now).",
+                "info"
+              );
+              continue;
+            }
+            if (sub === "status") {
+              await textView(ctx, "Catalog Cache — Status", [
+                `cacheOnOutage: ${config.cacheOnOutage ? "on" : "off"}`,
+                `Snapshot path: ${catalogCachePath()}`,
+                "",
+                entries.length ? "Cached catalogs on disk:" : "No cached catalogs on disk.",
+                ...entries.map(([name, e]) => `  ${name} — ${e.catalog.length} model(s), fetched ${formatCacheStamp(e.fetchedAt)}${e.unreachableAtLastProbe ? " — LAST PROBE FAILED (instant-served at startup)" : ""}`),
+                "",
+                "Instances currently listed from cache in /model:",
+                ...(cachedServing.size
+                  ? [...cachedServing].map(([name, s]) => `  ${name} — serving cache from ${formatCacheStamp(s.fetchedAt)}`)
+                  : ["  (none — every instance is live or lists nothing)"]),
+              ]);
+            }
+          }
+          continue;
+        }
+
         // ── Spec & version check ───────────────────────────────────────
         if (choice === "spec") {
           for (;;) {
@@ -3221,6 +5070,11 @@ function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeCo
               { 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: "adminkey",
+                label: "Edit admin API key",
+                description: `${config.adminApiKey ? "••••• (set)" : "(not set — /internal/* uses the API key)"} — LEMONADE_ADMIN_API_KEY for pin, model sync, config`,
+              },
               { value: "test", label: "Test connection", description: "Ping the health endpoint" },
               { value: "back", label: "Back", description: "" },
             ]);
@@ -3459,6 +5313,21 @@ function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeCo
                 saveConfig(config);
                 ctx.ui.notify("API key saved.", "info");
               }
+            } else if (sub === "adminkey") {
+              const input = await ctx.ui.input(
+                "Admin API key (LEMONADE_ADMIN_API_KEY — pin, model sync, config; empty = use the API key):",
+                config.adminApiKey
+              );
+              if (input !== undefined) {
+                config.adminApiKey = input.trim();
+                saveConfig(config);
+                ctx.ui.notify(
+                  config.adminApiKey
+                    ? "Admin key saved — /internal/* endpoints (pin, model sync) will use it."
+                    : "Admin key cleared — /internal/* falls back to the API key.",
+                  "info"
+                );
+              }
             } else if (sub === "test") {
               const h = await fetchHealth(iconfig);
               ctx.ui.notify(
@@ -3476,13 +5345,10 @@ function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeCo
         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: "browser", label: "Model browser", description: `Every model, live status inline — type to search, actions on select (${activeInstance})` },
+              { value: "downloads", label: "Downloads", description: "Server-owned download jobs — live list, cancel/pause/remove/retry" },
               { 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: "updates", label: "Check for model updates", description: "Report — and update — models with newer upstream commits" },
               {
                 value: "chatonly",
                 label: "Toggle chat-only filter",
@@ -3493,11 +5359,22 @@ function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeCo
             ]);
             if (sub === null || sub === "back") break;
 
+            if (sub === "browser") {
+              await modelBrowser(ctx, pi, iconfig, config, activeInstance);
+              continue;
+            }
+            if (sub === "downloads") {
+              await downloadsManager(ctx, pi, iconfig);
+              continue;
+            }
             if (sub === "installhf") {
               await installFromHuggingFace(ctx, pi, iconfig);
               continue;
             }
-
+            if (sub === "updates") {
+              await updatesFlow(ctx, pi, iconfig, config);
+              continue;
+            }
             if (sub === "chatonly") {
               config.chatOnly = !config.chatOnly;
               saveConfig(config);
@@ -3514,183 +5391,16 @@ function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeCo
               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;
         }
 
+        // ── Backends (recipe × backend inventory + install/uninstall) ──────
+        if (choice === "backends") {
+          await backendsView(ctx, pi, iconfig);
+          continue;
+        }
+
         // ── Transcription settings ────────────────────────────────────────
         if (choice === "transcription") {
           for (;;) {
@@ -3787,11 +5497,33 @@ export default async function piLemonadeLink(pi: ExtensionAPI): Promise<void> {
   // 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);
+  // One shared parallel probe pass feeds both consumers: an unreachable or
+  // slow box stalls startup once (not once per consumer, not once per
+  // instance) — bounded by a single discoveryTimeoutMs window. With
+  // cacheOnOutage, instances the probe can't reach are listed from their
+  // last good cached catalog, provenance-marked — see withCacheFallback.
+  //
+  // Hybrid SWR: instances whose LAST probe failed (durable flag) are served
+  // from cache instantly — zero probe wait — and reconciled by a background
+  // probe pass; instances last known reachable still probe first, so a
+  // healthy box never flashes stale data. Net: the down-box stall only ever
+  // bites once per outage, at the transition into it.
+  const probes = await instantOrLiveProbes(configRef.current);
+  await registerLemonadeProvider(pi, configRef.current, probes);
+  await registerAgentTools(pi, configRef.current, probes);
+  lastResyncProbeAt = Date.now(); // the activation pass IS a probe pass — throttle the session_start re-sync trigger
+  if (probes.some((p) => p.cachedAt !== undefined)) {
+    // Background reconcile for instant-served instances: probes everything
+    // again (cheap for instances that just answered) and re-registers with
+    // live truth when the box is back. Diff notices are silent here —
+    // activation has no ui ctx, and the session_start cached warning has
+    // already told the user the state; the suffix flips are visible in /model.
+    void resyncFromOutage(pi, configRef, undefined, true);
+  }
   registerLemonadeBar(pi, configRef);
   registerSetupCommand(pi, configRef);
   registerSpecDriftWarnings(pi, configRef);
+  registerOutageResync(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