@harness-engineering/orchestrator 0.11.2 → 0.12.0

package/dist/index.js

@@ -83,6 +83,7 @@ __export(index_exports, {
   defaultFetchModels: () => defaultFetchModels,
   deriveSeedPaths: () => deriveSeedPaths,
   detectScopeTier: () => detectScopeTier,
+  discoverCandidates: () => import_local_models6.discoverCandidates,
   discoverSkillCatalog: () => discoverSkillCatalog,
   discoverSkillCatalogNames: () => discoverSkillCatalogNames,
   emitProposalApproved: () => emitProposalApproved,
@@ -3882,8 +3883,19 @@ var AgentRunner = class {
 
 // src/agent/local-model-resolver.ts
 var import_local_models = require("@harness-engineering/local-models");
+function useCaseToProfile(useCase) {
+  switch (useCase.kind) {
+    case "tier":
+      return useCase.tier === "diagnostic" ? "reasoning" : "coding";
+    default:
+      return "general";
+  }
+}
 var DEFAULT_PROBE_INTERVAL_MS = 3e4;
 var MIN_PROBE_INTERVAL_MS = 1e3;
+var REFRESH_DEBOUNCE_MS = 250;
+var DEFAULT_BREAKER_THRESHOLD = 3;
+var DEFAULT_BREAKER_COOLDOWN_MS = 6e4;
 var DEFAULT_API_KEY = "lm-studio";
 var DEFAULT_FETCH_TIMEOUT_MS = 5e3;
 function normalizeLocalModel(input) {
@@ -3934,6 +3946,44 @@ async function defaultFetchModels(endpoint, apiKey, timeoutMs = DEFAULT_FETCH_TI
   }
   return ids;
 }
+async function defaultWarmModel(endpoint, ollamaName, apiKey, keepAlive = "10m", timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) {
+  const base = endpoint.replace(/\/v1\/?$/, "").replace(/\/$/, "");
+  const url = `${base}/api/generate`;
+  try {
+    await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey ?? DEFAULT_API_KEY}`
+      },
+      // Empty prompt + keep_alive loads the model into VRAM without generating.
+      body: JSON.stringify({ model: ollamaName, prompt: "", keep_alive: keepAlive }),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  } catch {
+  }
+}
+async function defaultWarmModelViaCompletion(endpoint, model, apiKey, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) {
+  const url = `${endpoint.replace(/\/$/, "")}/chat/completions`;
+  try {
+    await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey ?? DEFAULT_API_KEY}`
+      },
+      // Minimal request: one token is enough to force the server to load the
+      // model. The generated content is discarded — we only want the load.
+      body: JSON.stringify({
+        model,
+        max_tokens: 1,
+        messages: [{ role: "user", content: "warm" }]
+      }),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  } catch {
+  }
+}
 var LocalModelResolver = class {
   endpoint;
   apiKey;
@@ -3941,8 +3991,21 @@ var LocalModelResolver = class {
   poolState;
   probeIntervalMs;
   fetchModels;
+  warmModel;
   logger;
   timer = null;
+  /** Debounce handle for event-driven {@link refresh}; coalesces a burst into one probe. */
+  refreshTimer = null;
+  /** Test seam for the refresh debounce delay (0 in tests → next-tick probe). */
+  refreshDebounceMs;
+  /** Consumption Phase 3 (T10): circuit-breaker config + per-model failure/trip state. */
+  breakerThreshold;
+  breakerCooldownMs;
+  now;
+  /** Consecutive inference failures per model since its last success. */
+  consecutiveFailures = /* @__PURE__ */ new Map();
+  /** Epoch-ms at which a tripped model becomes eligible again (cooldown expiry). */
+  trippedUntil = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
   /**
    * Tracks an in-flight probe so concurrent invocations (interval tick while a
@@ -3972,12 +4035,28 @@ var LocalModelResolver = class {
     }
     const interval = opts.probeIntervalMs ?? DEFAULT_PROBE_INTERVAL_MS;
     this.probeIntervalMs = Math.max(MIN_PROBE_INTERVAL_MS, interval);
+    this.refreshDebounceMs = Math.max(0, opts.refreshDebounceMs ?? REFRESH_DEBOUNCE_MS);
+    this.breakerThreshold = Math.max(1, opts.breakerThreshold ?? DEFAULT_BREAKER_THRESHOLD);
+    this.breakerCooldownMs = Math.max(0, opts.breakerCooldownMs ?? DEFAULT_BREAKER_COOLDOWN_MS);
+    this.now = opts.now ?? (() => Date.now());
     const timeoutMs = opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
     this.fetchModels = opts.fetchModels ?? ((endpoint, apiKey) => defaultFetchModels(endpoint, apiKey, timeoutMs));
+    if (opts.warmModel !== void 0) this.warmModel = opts.warmModel;
     this.logger = opts.logger ?? noopLogger;
   }
-  resolveModel() {
-    return this.resolved;
+  /**
+   * The model to dispatch to. With no `useCase`, returns the cached composite
+   * resolution from the last probe (byte-identical to the pre-Phase-4 resolver).
+   * With a `useCase`, orders the (pool-derived) candidates by that use-case's
+   * task profile and picks the best loaded, breaker-healthy one — so a
+   * coding-tagged dispatch prefers the coding specialist. A `general`-mapped
+   * use-case returns the cached composite resolution unchanged.
+   */
+  resolveModel(useCase) {
+    if (useCase === void 0) return this.resolved;
+    const profile = useCaseToProfile(useCase);
+    if (profile === "general") return this.resolved;
+    return this.selectMatch(this.candidates(profile), this.detected);
   }
   getStatus() {
     return {
@@ -3995,8 +4074,8 @@ var LocalModelResolver = class {
    * from pool entries (currentScore desc → ollamaName); otherwise the static
    * `configured` list is returned unchanged (byte-identical to pre-Phase-4).
    */
-  candidates() {
-    return this.poolState ? (0, import_local_models.poolStateToCandidates)(this.poolState.snapshot()) : [...this.configured];
+  candidates(profile) {
+    return this.poolState ? (0, import_local_models.poolStateToCandidates)(this.poolState.snapshot(), profile) : [...this.configured];
   }
   onStatusChange(handler) {
     this.listeners.add(handler);
@@ -4016,13 +4095,14 @@ var LocalModelResolver = class {
   }
   async runProbe() {
     const before = this.snapshotForDiff();
+    const prevResolved = this.resolved;
     try {
       const detected = await this.fetchModels(this.endpoint, this.apiKey);
       this.detected = [...detected];
       this.lastError = null;
       this.lastProbeAt = (/* @__PURE__ */ new Date()).toISOString();
       const candidates = this.candidates();
-      const match = candidates.find((id) => detected.includes(id)) ?? null;
+      const match = this.selectMatch(candidates, detected);
       this.resolved = match;
       this.available = match !== null;
       this.warnings = match ? [] : [
@@ -4052,8 +4132,92 @@ var LocalModelResolver = class {
         }
       }
     }
+    if (this.resolved !== null && this.resolved !== prevResolved) {
+      this.warm(this.resolved);
+    }
     return status;
   }
+  /** Best-effort warm-hook invocation — a throwing warm never breaks a probe. */
+  warm(ollamaName) {
+    if (!this.warmModel) return;
+    try {
+      this.warmModel(ollamaName);
+    } catch (err) {
+      this.logger.warn("local-model-resolver warm hook threw", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  /**
+   * Consumption Phase 3 (T10): pick the resolved model from the candidates that
+   * are actually loaded, preferring ones whose circuit breaker is not tripped.
+   * Candidate order (score-desc from the pool) is preserved within each tier, so
+   * a tripped top pick sinks below a healthy lower pick but still resolves as a
+   * last resort when every loaded candidate is tripped (better a flaky model than
+   * none). Returns null when no candidate is loaded.
+   */
+  selectMatch(candidates, detected) {
+    const detectedSet = new Set(detected);
+    const available = candidates.filter((id) => detectedSet.has(id));
+    if (available.length === 0) return null;
+    const healthy = available.filter((id) => !this.isTripped(id));
+    return healthy[0] ?? available[0] ?? null;
+  }
+  /**
+   * Whether `model`'s circuit breaker is currently tripped. Lazily clears the
+   * trip once its cooldown has elapsed so the model becomes eligible again on the
+   * next resolution without needing a separate timer.
+   */
+  isTripped(model) {
+    const until = this.trippedUntil.get(model);
+    if (until === void 0) return false;
+    if (this.now() >= until) {
+      this.trippedUntil.delete(model);
+      this.consecutiveFailures.delete(model);
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Record a successful inference on `model`: clears its failure count and any
+   * active trip so a recovered model is immediately re-preferred.
+   */
+  recordSuccess(model) {
+    if (!model) return;
+    const hadState = this.consecutiveFailures.has(model) || this.trippedUntil.has(model);
+    this.consecutiveFailures.delete(model);
+    this.trippedUntil.delete(model);
+    if (hadState) this.refresh();
+  }
+  /**
+   * Record a failed inference on `model`. On the Nth consecutive failure the
+   * breaker trips (deprioritizing the model for `breakerCooldownMs`) and a
+   * re-probe is scheduled so the resolver rolls to a healthy alternative.
+   */
+  recordFailure(model) {
+    if (!model) return;
+    const next = (this.consecutiveFailures.get(model) ?? 0) + 1;
+    this.consecutiveFailures.set(model, next);
+    if (next >= this.breakerThreshold) {
+      this.trippedUntil.set(model, this.now() + this.breakerCooldownMs);
+      this.refresh();
+    }
+  }
+  /**
+   * Event-driven refresh: schedule a debounced re-probe. Called when a
+   * `local-models:pool` mutation fires so a just-installed/swapped model becomes
+   * usable within a debounce window instead of waiting up to `probeIntervalMs`.
+   * A burst of frames coalesces into one probe (the timer is only armed once).
+   */
+  refresh() {
+    if (this.refreshTimer !== null) return;
+    this.refreshTimer = setTimeout(() => {
+      this.refreshTimer = null;
+      void this.probe();
+    }, this.refreshDebounceMs);
+    const handle = this.refreshTimer;
+    handle.unref?.();
+  }
   async start() {
     if (this.timer !== null) {
       return;
@@ -4070,6 +4234,10 @@ var LocalModelResolver = class {
       clearInterval(this.timer);
       this.timer = null;
     }
+    if (this.refreshTimer !== null) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
   }
   snapshotForDiff() {
     return JSON.stringify({
@@ -4087,6 +4255,215 @@ var LocalModelResolver = class {
 var import_local_models5 = require("@harness-engineering/local-models");
 var import_core18 = require("@harness-engineering/core");
 
+// src/proposals/model-handlers.ts
+function isInUse(deps, ollamaName) {
+  return deps.isModelInUse ? deps.isModelInUse(ollamaName) : false;
+}
+var MODEL_PROPOSAL_TOPIC = "local-models:proposal";
+var MODEL_POOL_TOPIC = "local-models:pool";
+var MODEL_INSTALL_TOPIC = "local-models:install";
+function makeInstallProgressForwarder(bus, base) {
+  const emit4 = (phase, patch = {}) => {
+    const frame = { ...base, ...patch, phase };
+    bus.emit(MODEL_INSTALL_TOPIC, frame);
+  };
+  const onInstallEvent = (event) => {
+    if (event.kind === "progress") {
+      emit4("progress", {
+        completedBytes: event.completedBytes,
+        totalBytes: event.totalBytes,
+        ...event.message !== void 0 ? { message: event.message } : {}
+      });
+    } else if (event.kind === "pulling") {
+      emit4("progress", { message: event.message });
+    }
+  };
+  return { emit: emit4, onInstallEvent };
+}
+function decisionOf(deps, action, reason) {
+  return {
+    decidedAt: (deps.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+    decidedBy: deps.decidedBy ?? "orchestrator",
+    action,
+    ...reason !== void 0 ? { reason } : {}
+  };
+}
+function emitApproved(deps, proposal) {
+  deps.bus.emit(MODEL_PROPOSAL_TOPIC, {
+    id: proposal.id,
+    status: "approved",
+    action: proposal.model.action,
+    target: proposal.model.target.ollamaName
+  });
+}
+async function deferEviction(deps, proposal, deferredName, event, evicted) {
+  deps.pool.markPendingEviction(deferredName);
+  const updated = await deps.updateProposal(proposal.id, {
+    status: "approved",
+    decision: decisionOf(deps, "approved")
+  });
+  deps.bus.emit(MODEL_POOL_TOPIC, event);
+  emitApproved(deps, proposal);
+  return { status: "approved", proposal: updated, evicted };
+}
+async function onApproveModelProposal(deps, proposal) {
+  const { model } = proposal;
+  if (model.action === "evict") {
+    return applyEvictOnly(deps, proposal);
+  }
+  await deps.updateProposal(proposal.id, { status: "installing" });
+  const installResult = await deps.pool.install({
+    hfRepoId: model.target.hfRepoId,
+    ollamaName: model.target.ollamaName,
+    ...model.replaces !== void 0 ? { replaces: model.replaces.ollamaName } : {},
+    ...model.diskImpactGb > 0 ? { sizeOnDiskGb: model.diskImpactGb } : {},
+    ...model.targetScore !== void 0 ? { initialScore: model.targetScore } : {},
+    ...deps.onInstallEvent ? { onEvent: deps.onInstallEvent } : {}
+  });
+  if (installResult.status === "error") {
+    if (installResult.code === "failed_target_missing") {
+      const updated2 = await deps.updateProposal(proposal.id, {
+        status: "failed_target_missing"
+      });
+      deps.bus.emit(MODEL_PROPOSAL_TOPIC, {
+        id: proposal.id,
+        status: "failed_target_missing",
+        action: model.action,
+        target: model.target.ollamaName
+      });
+      return { status: "failed_target_missing", proposal: updated2 };
+    }
+    await deps.updateProposal(proposal.id, { status: "open" });
+    return { status: "error", code: installResult.code, message: installResult.message };
+  }
+  const evicted = [...installResult.evicted];
+  if (model.action === "swap" && model.replaces !== void 0) {
+    const replacesName = model.replaces.ollamaName;
+    if (isInUse(deps, replacesName)) {
+      return deferEviction(
+        deps,
+        proposal,
+        replacesName,
+        {
+          id: proposal.id,
+          action: model.action,
+          installed: model.target.ollamaName,
+          phase: "evict_deferred",
+          deferred: replacesName,
+          ...installResult.evicted.length > 0 ? { evicted: installResult.evicted.map((e) => e.ollamaName) } : {}
+        },
+        evicted
+      );
+    }
+    const evictResult = await deps.pool.evict({ ollamaName: replacesName });
+    if (evictResult.status === "error") {
+      deps.bus.emit(MODEL_POOL_TOPIC, {
+        id: proposal.id,
+        action: model.action,
+        installed: model.target.ollamaName,
+        phase: "swap_evict_failed"
+      });
+      await deps.updateProposal(proposal.id, { status: "open" });
+      return { status: "error", code: evictResult.code, message: evictResult.message };
+    }
+    if (evictResult.removed !== null) {
+      evicted.push(evictResult.removed);
+    }
+  }
+  const updated = await deps.updateProposal(proposal.id, {
+    status: "approved",
+    decision: decisionOf(deps, "approved")
+  });
+  const evictedNames = [
+    ...installResult.evicted.map((e) => e.ollamaName),
+    ...model.replaces !== void 0 ? [model.replaces.ollamaName] : []
+  ];
+  deps.bus.emit(MODEL_POOL_TOPIC, {
+    id: proposal.id,
+    action: model.action,
+    installed: model.target.ollamaName,
+    ...evictedNames.length > 0 ? { evicted: evictedNames } : {}
+  });
+  emitApproved(deps, proposal);
+  return { status: "approved", proposal: updated, evicted };
+}
+async function applyEvictOnly(deps, proposal) {
+  const targetName = proposal.model.target.ollamaName;
+  if (isInUse(deps, targetName)) {
+    return deferEviction(
+      deps,
+      proposal,
+      targetName,
+      { id: proposal.id, action: "evict", phase: "evict_deferred", deferred: targetName },
+      []
+    );
+  }
+  const evictResult = await deps.pool.evict({ ollamaName: targetName });
+  if (evictResult.status === "error") {
+    return { status: "error", code: evictResult.code, message: evictResult.message };
+  }
+  const updated = await deps.updateProposal(proposal.id, {
+    status: "approved",
+    decision: decisionOf(deps, "approved")
+  });
+  deps.bus.emit(MODEL_POOL_TOPIC, {
+    id: proposal.id,
+    action: "evict",
+    // XP-2: `evicted` is string[] at EVERY local-models:pool emit site (swap/add
+    // list multiple removals) — the evict-only path wraps its single removal in
+    // an array too, so consumers never branch on string-vs-array.
+    evicted: [proposal.model.target.ollamaName]
+  });
+  emitApproved(deps, proposal);
+  return {
+    status: "approved",
+    proposal: updated,
+    evicted: evictResult.removed !== null && evictResult.removed !== void 0 ? [evictResult.removed] : []
+  };
+}
+async function onRejectModelProposal(deps, proposal, reason) {
+  const updated = await deps.updateProposal(proposal.id, {
+    status: "rejected",
+    decision: decisionOf(deps, "rejected", reason)
+  });
+  deps.bus.emit(MODEL_PROPOSAL_TOPIC, {
+    id: proposal.id,
+    status: "rejected",
+    target: proposal.model.target.ollamaName,
+    replaces: proposal.model.replaces?.ollamaName,
+    reason
+  });
+  return updated;
+}
+async function redriveInstallingProposals(deps, proposals, opts = {}) {
+  for (const proposal of proposals) {
+    if (proposal.status !== "installing") continue;
+    if (proposal.model.action === "evict") continue;
+    const { emit: emit4, onInstallEvent } = makeInstallProgressForwarder(deps.bus, {
+      proposalId: proposal.id,
+      hfRepoId: proposal.model.target.hfRepoId,
+      ollamaName: proposal.model.target.ollamaName
+    });
+    emit4("started");
+    try {
+      const outcome = await onApproveModelProposal({ ...deps, onInstallEvent }, proposal);
+      if (outcome.status === "approved") {
+        emit4("complete");
+      } else if (outcome.status === "failed_target_missing") {
+        emit4("error", {
+          code: "failed_target_missing",
+          message: `${proposal.model.target.hfRepoId} is no longer available on HuggingFace`
+        });
+      } else {
+        emit4("error", { code: outcome.code, message: outcome.message });
+      }
+    } catch (err) {
+      opts.onWarn?.("re-drive of interrupted install failed", err);
+      emit4("error", { message: err instanceof Error ? err.message : String(err) });
+    }
+  }
+}
+
 // src/agent/config-migration.ts
 var MIGRATION_GUIDE = "docs/guides/multi-backend-routing.md";
 var CASE1_ALWAYS_SUPPRESS = /* @__PURE__ */ new Set(["agent.backend"]);
@@ -5129,6 +5506,8 @@ var LocalBackend = class {
   name = "local";
   config;
   getModel;
+  onModelUsed;
+  onModelFailed;
   client;
   constructor(config = {}) {
     this.config = {
@@ -5138,6 +5517,8 @@ var LocalBackend = class {
       timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS
     };
     this.getModel = config.getModel;
+    this.onModelUsed = config.onModelUsed;
+    this.onModelFailed = config.onModelFailed;
     this.client = new import_openai2.default({
       apiKey: this.config.apiKey,
       baseURL: this.config.endpoint,
@@ -5204,6 +5585,7 @@ var LocalBackend = class {
       }
     } catch (err) {
       const errorMessage2 = err instanceof Error ? err.message : "Local backend request failed";
+      this.notify(this.onModelFailed, localSession.resolvedModel);
       yield {
         type: "error",
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -5217,6 +5599,7 @@ var LocalBackend = class {
         error: errorMessage2
       };
     }
+    this.notify(this.onModelUsed, localSession.resolvedModel);
     const usage = { inputTokens, outputTokens, totalTokens };
     yield {
       type: "usage",
@@ -5230,6 +5613,14 @@ var LocalBackend = class {
       usage
     };
   }
+  /** Best-effort telemetry hook invocation — a throwing hook never breaks a turn. */
+  notify(hook, model) {
+    if (!hook) return;
+    try {
+      hook(model);
+    } catch {
+    }
+  }
   async stopSession(_session) {
     return (0, import_types14.Ok)(void 0);
   }
@@ -5391,7 +5782,8 @@ var PiBackend = class {
         backendName: this.name,
         startedAt: (/* @__PURE__ */ new Date()).toISOString(),
         piSession,
-        unsubscribe: null
+        unsubscribe: null,
+        ...resolvedModelName !== void 0 && { resolvedModel: resolvedModelName }
       };
       return (0, import_types15.Ok)(session);
     } catch (err) {
@@ -5483,7 +5875,9 @@ var PiBackend = class {
       }
     }
     const totalTokens = inputTokens + outputTokens;
+    const resolvedModel = session.resolvedModel;
     if (promptErrorMsg) {
+      if (resolvedModel !== void 0) this.notify(this.config.onModelFailed, resolvedModel);
       return {
         success: false,
         sessionId: session.sessionId,
@@ -5491,12 +5885,21 @@ var PiBackend = class {
         usage: { inputTokens, outputTokens, totalTokens }
       };
     }
+    if (resolvedModel !== void 0) this.notify(this.config.onModelUsed, resolvedModel);
     return {
       success: true,
       sessionId: session.sessionId,
       usage: { inputTokens, outputTokens, totalTokens }
     };
   }
+  /** Best-effort telemetry hook invocation — a throwing hook never breaks a turn. */
+  notify(hook, model) {
+    if (!hook) return;
+    try {
+      hook(model);
+    } catch {
+    }
+  }
   /**
    * Consume events from the queue, yielding mapped AgentEvents until agent_end or prompt completion.
    */
@@ -6598,8 +7001,9 @@ var OrchestratorBackendFactory = class {
     let backend;
     const createOpts = this.opts.cacheMetrics ? { cacheMetrics: this.opts.cacheMetrics } : {};
     if ((def.type === "local" || def.type === "pi") && this.opts.getResolverModelFor) {
-      const getModel = this.opts.getResolverModelFor(name);
-      backend = getModel ? this.buildLocalLikeWithResolver(def, getModel) : createBackend(def, createOpts);
+      const getModel = this.opts.getResolverModelFor(name, useCase);
+      const usageHooks = this.opts.getModelUsageHooksFor?.(name);
+      backend = getModel ? this.buildLocalLikeWithResolver(def, getModel, usageHooks) : createBackend(def, createOpts);
     } else {
       backend = createBackend(def, createOpts);
     }
@@ -6613,13 +7017,15 @@ var OrchestratorBackendFactory = class {
    * mirroring `createBackend`'s local/pi branches but substituting the
    * head-of-array placeholder with the orchestrator-owned resolver.
    */
-  buildLocalLikeWithResolver(def, getModel) {
+  buildLocalLikeWithResolver(def, getModel, usageHooks) {
     if (def.type === "local") {
       return new LocalBackend({
         endpoint: def.endpoint,
         getModel,
         ...def.apiKey !== void 0 ? { apiKey: def.apiKey } : {},
-        ...def.timeoutMs !== void 0 ? { timeoutMs: def.timeoutMs } : {}
+        ...def.timeoutMs !== void 0 ? { timeoutMs: def.timeoutMs } : {},
+        ...usageHooks?.onModelUsed !== void 0 ? { onModelUsed: usageHooks.onModelUsed } : {},
+        ...usageHooks?.onModelFailed !== void 0 ? { onModelFailed: usageHooks.onModelFailed } : {}
       });
     }
     if (def.type === "pi") {
@@ -6627,7 +7033,9 @@ var OrchestratorBackendFactory = class {
         endpoint: def.endpoint,
         getModel,
         ...def.apiKey !== void 0 ? { apiKey: def.apiKey } : {},
-        ...def.timeoutMs !== void 0 ? { timeoutMs: def.timeoutMs } : {}
+        ...def.timeoutMs !== void 0 ? { timeoutMs: def.timeoutMs } : {},
+        ...usageHooks?.onModelUsed !== void 0 ? { onModelUsed: usageHooks.onModelUsed } : {},
+        ...usageHooks?.onModelFailed !== void 0 ? { onModelFailed: usageHooks.onModelFailed } : {}
       });
     }
     throw new Error(
@@ -6792,6 +7200,9 @@ function buildLocalLikeProvider(def, args, layerModel) {
     apiKey,
     baseUrl: def.endpoint,
     ...model !== void 0 && { defaultModel: model },
+    ...layerModel === void 0 && {
+      getModel: () => getResolverStatusSnapshot()?.resolved ?? void 0
+    },
     ...intelligence?.requestTimeoutMs !== void 0 && {
       timeoutMs: intelligence.requestTimeoutMs
     },
@@ -8608,163 +9019,6 @@ function emitProposalRejected(bus, proposal) {
   emit3(bus, "proposal.rejected", data);
 }
 
-// src/proposals/model-handlers.ts
-function isInUse(deps, ollamaName) {
-  return deps.isModelInUse ? deps.isModelInUse(ollamaName) : false;
-}
-var MODEL_PROPOSAL_TOPIC = "local-models:proposal";
-var MODEL_POOL_TOPIC = "local-models:pool";
-function decisionOf(deps, action, reason) {
-  return {
-    decidedAt: (deps.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
-    decidedBy: deps.decidedBy ?? "orchestrator",
-    action,
-    ...reason !== void 0 ? { reason } : {}
-  };
-}
-function emitApproved(deps, proposal) {
-  deps.bus.emit(MODEL_PROPOSAL_TOPIC, {
-    id: proposal.id,
-    status: "approved",
-    action: proposal.model.action,
-    target: proposal.model.target.ollamaName
-  });
-}
-async function deferEviction(deps, proposal, deferredName, event, evicted) {
-  deps.pool.markPendingEviction(deferredName);
-  const updated = await deps.updateProposal(proposal.id, {
-    status: "approved",
-    decision: decisionOf(deps, "approved")
-  });
-  deps.bus.emit(MODEL_POOL_TOPIC, event);
-  emitApproved(deps, proposal);
-  return { status: "approved", proposal: updated, evicted };
-}
-async function onApproveModelProposal(deps, proposal) {
-  const { model } = proposal;
-  if (model.action === "evict") {
-    return applyEvictOnly(deps, proposal);
-  }
-  const installResult = await deps.pool.install({
-    hfRepoId: model.target.hfRepoId,
-    ollamaName: model.target.ollamaName,
-    ...model.replaces !== void 0 ? { replaces: model.replaces.ollamaName } : {},
-    ...model.diskImpactGb > 0 ? { sizeOnDiskGb: model.diskImpactGb } : {}
-  });
-  if (installResult.status === "error") {
-    if (installResult.code === "failed_target_missing") {
-      const updated2 = await deps.updateProposal(proposal.id, {
-        status: "failed_target_missing"
-      });
-      deps.bus.emit(MODEL_PROPOSAL_TOPIC, {
-        id: proposal.id,
-        status: "failed_target_missing",
-        action: model.action,
-        target: model.target.ollamaName
-      });
-      return { status: "failed_target_missing", proposal: updated2 };
-    }
-    return { status: "error", code: installResult.code, message: installResult.message };
-  }
-  const evicted = [...installResult.evicted];
-  if (model.action === "swap" && model.replaces !== void 0) {
-    const replacesName = model.replaces.ollamaName;
-    if (isInUse(deps, replacesName)) {
-      return deferEviction(
-        deps,
-        proposal,
-        replacesName,
-        {
-          id: proposal.id,
-          action: model.action,
-          installed: model.target.ollamaName,
-          phase: "evict_deferred",
-          deferred: replacesName,
-          ...installResult.evicted.length > 0 ? { evicted: installResult.evicted.map((e) => e.ollamaName) } : {}
-        },
-        evicted
-      );
-    }
-    const evictResult = await deps.pool.evict({ ollamaName: replacesName });
-    if (evictResult.status === "error") {
-      deps.bus.emit(MODEL_POOL_TOPIC, {
-        id: proposal.id,
-        action: model.action,
-        installed: model.target.ollamaName,
-        phase: "swap_evict_failed"
-      });
-      return { status: "error", code: evictResult.code, message: evictResult.message };
-    }
-    if (evictResult.removed !== null) {
-      evicted.push(evictResult.removed);
-    }
-  }
-  const updated = await deps.updateProposal(proposal.id, {
-    status: "approved",
-    decision: decisionOf(deps, "approved")
-  });
-  const evictedNames = [
-    ...installResult.evicted.map((e) => e.ollamaName),
-    ...model.replaces !== void 0 ? [model.replaces.ollamaName] : []
-  ];
-  deps.bus.emit(MODEL_POOL_TOPIC, {
-    id: proposal.id,
-    action: model.action,
-    installed: model.target.ollamaName,
-    ...evictedNames.length > 0 ? { evicted: evictedNames } : {}
-  });
-  emitApproved(deps, proposal);
-  return { status: "approved", proposal: updated, evicted };
-}
-async function applyEvictOnly(deps, proposal) {
-  const targetName = proposal.model.target.ollamaName;
-  if (isInUse(deps, targetName)) {
-    return deferEviction(
-      deps,
-      proposal,
-      targetName,
-      { id: proposal.id, action: "evict", phase: "evict_deferred", deferred: targetName },
-      []
-    );
-  }
-  const evictResult = await deps.pool.evict({ ollamaName: targetName });
-  if (evictResult.status === "error") {
-    return { status: "error", code: evictResult.code, message: evictResult.message };
-  }
-  const updated = await deps.updateProposal(proposal.id, {
-    status: "approved",
-    decision: decisionOf(deps, "approved")
-  });
-  deps.bus.emit(MODEL_POOL_TOPIC, {
-    id: proposal.id,
-    action: "evict",
-    // XP-2: `evicted` is string[] at EVERY local-models:pool emit site (swap/add
-    // list multiple removals) — the evict-only path wraps its single removal in
-    // an array too, so consumers never branch on string-vs-array.
-    evicted: [proposal.model.target.ollamaName]
-  });
-  emitApproved(deps, proposal);
-  return {
-    status: "approved",
-    proposal: updated,
-    evicted: evictResult.removed !== null && evictResult.removed !== void 0 ? [evictResult.removed] : []
-  };
-}
-async function onRejectModelProposal(deps, proposal, reason) {
-  const updated = await deps.updateProposal(proposal.id, {
-    status: "rejected",
-    decision: decisionOf(deps, "rejected", reason)
-  });
-  deps.bus.emit(MODEL_PROPOSAL_TOPIC, {
-    id: proposal.id,
-    status: "rejected",
-    target: proposal.model.target.ollamaName,
-    replaces: proposal.model.replaces?.ollamaName,
-    reason
-  });
-  return updated;
-}
-
 // src/server/routes/v1/proposals.ts
 var LIST_RE = /^\/api\/v1\/proposals(?:\?.*)?$/;
 var SINGLE_RE = /^\/api\/v1\/proposals\/([^/?]+)(?:\?.*)?$/;
@@ -8858,12 +9112,38 @@ async function handleApprove(req, res, deps, id) {
       sendJSON8(res, 501, { error: "model proposal handlers not configured" });
       return;
     }
-    if (existing.status === "approved" || existing.status === "rejected" || existing.status === "failed_target_missing") {
+    if (existing.status === "approved" || existing.status === "rejected" || existing.status === "failed_target_missing" || existing.status === "installing") {
       sendJSON8(res, 409, {
         error: `proposal already ${existing.status}; cannot approve`
       });
       return;
     }
+    const action = existing.model.action;
+    if (action === "add" || action === "swap") {
+      const { emit: emit4, onInstallEvent } = makeInstallProgressForwarder(deps.bus, {
+        proposalId: existing.id,
+        hfRepoId: existing.model.target.hfRepoId,
+        ollamaName: existing.model.target.ollamaName
+      });
+      const handler = { ...modelHandlerDeps(deps, req), onInstallEvent };
+      emit4("started");
+      void onApproveModelProposal(handler, existing).then((outcome2) => {
+        if (outcome2.status === "approved") {
+          emit4("complete");
+        } else if (outcome2.status === "failed_target_missing") {
+          emit4("error", {
+            code: "failed_target_missing",
+            message: `${existing.model.target.hfRepoId} is no longer available on HuggingFace`
+          });
+        } else {
+          emit4("error", { code: outcome2.code, message: outcome2.message });
+        }
+      }).catch((err) => {
+        emit4("error", { message: err instanceof Error ? err.message : String(err) });
+      });
+      sendJSON8(res, 202, { disposition: "installing", proposalId: existing.id });
+      return;
+    }
     const outcome = await onApproveModelProposal(modelHandlerDeps(deps, req), existing);
     sendJSON8(res, outcome.status === "error" ? 422 : 200, outcome);
     return;
@@ -9047,6 +9327,7 @@ function handleV1ProposalsRoute(req, res, deps) {
 // src/server/routes/v1/local-models.ts
 var import_local_models2 = require("@harness-engineering/local-models");
 var REFRESH_RE = /^\/api\/v1\/local-models\/refresh(?:\?.*)?$/;
+var CANDIDATES_REFRESH_RE = /^\/api\/v1\/local-models\/candidates\/refresh(?:\?.*)?$/;
 var HARDWARE_RE = /^\/api\/v1\/local-models\/hardware(?:\?.*)?$/;
 var POOL_RE = /^\/api\/v1\/local-models\/pool(?:\?.*)?$/;
 var RECS_RE = /^\/api\/v1\/local-models\/recommendations(?:\?.*)?$/;
@@ -9078,7 +9359,17 @@ function handleV1LocalModelsRoute(req, res, deps) {
     }
     return false;
   }
-  if (method !== "POST" || !REFRESH_RE.test(url)) return false;
+  if (method !== "POST") return false;
+  if (CANDIDATES_REFRESH_RE.test(url)) {
+    const refresh = deps.getRefreshCandidates?.() ?? null;
+    if (refresh === null) {
+      sendJSON9(res, 503, { error: "LMLM disabled" });
+      return true;
+    }
+    void runCandidatesRefresh(res, refresh);
+    return true;
+  }
+  if (!REFRESH_RE.test(url)) return false;
   const scheduler = deps.getRefreshScheduler();
   if (scheduler === null) {
     sendJSON9(res, 503, { error: "LMLM disabled" });
@@ -9087,6 +9378,16 @@ function handleV1LocalModelsRoute(req, res, deps) {
   void runForceRefresh(res, scheduler, deps);
   return true;
 }
+async function runCandidatesRefresh(res, refresh) {
+  try {
+    sendJSON9(res, 200, await refresh());
+  } catch (err) {
+    sendJSON9(res, 500, {
+      error: "candidate refresh failed",
+      detail: err instanceof Error ? err.message : "unknown"
+    });
+  }
+}
 async function runGet(res, handler) {
   try {
     await handler();
@@ -9247,6 +9548,11 @@ async function handleInstall(req, res, deps) {
     action: "add",
     target: { hfRepoId: match.hfRepoId, ollamaName: match.ollamaName },
     scoreDelta: match.score,
+    // Consumption Phase 2 (T7): carry the absolute ranked score so the new pool
+    // entry seeds `currentScore` at its real rank instead of 0 — an
+    // operator-initiated install is usable immediately, not buried until the
+    // scheduler's next re-rank.
+    targetScore: match.score,
     justification: {
       summary: `Operator-initiated install of ${match.ollamaName} (${match.quant}).`,
       benchmarkBasis: [],
@@ -9269,27 +9575,37 @@ async function handleInstall(req, res, deps) {
   const record = await (0, import_core11.createModelProposal)(deps.projectPath, content, {
     proposedBy: decidedByOf(deps, req)
   });
-  const outcome = await onApproveModelProposal(handlerDeps(deps, req, pool), record);
-  if (outcome.status === "approved") {
-    const result = {
-      disposition: "installed",
-      proposalId: record.id,
-      evicted: outcome.evicted.map((e) => e.ollamaName)
-    };
-    return sendJSON10(res, 200, result);
-  }
-  if (outcome.status === "failed_target_missing") {
-    return sendJSON10(res, 404, {
-      error: `${hfRepoId} is no longer available on HuggingFace`,
-      proposalId: record.id
-    });
-  }
-  const status = outcome.code === "not_allowed" || outcome.code === "budget_exceeded" ? 409 : 502;
-  return sendJSON10(res, status, {
-    error: outcome.message,
-    code: outcome.code,
-    proposalId: record.id
+  const ollamaName = match.ollamaName;
+  const { emit: emit4, onInstallEvent } = makeInstallProgressForwarder(deps.bus, {
+    proposalId: record.id,
+    hfRepoId: match.hfRepoId,
+    ollamaName
+  });
+  const handler = { ...handlerDeps(deps, req, pool), onInstallEvent };
+  emit4("started");
+  void onApproveModelProposal(handler, record).then((outcome) => {
+    if (outcome.status === "approved") {
+      emit4("complete", {});
+      return;
+    }
+    if (outcome.status === "failed_target_missing") {
+      emit4("error", {
+        code: "failed_target_missing",
+        message: `${hfRepoId} is no longer available on HuggingFace`
+      });
+      return;
+    }
+    emit4("error", { code: outcome.code, message: outcome.message });
+  }).catch((err) => {
+    emit4("error", { message: err instanceof Error ? err.message : String(err) });
   });
+  const result = {
+    disposition: "installing",
+    proposalId: record.id,
+    evicted: [],
+    message: `installing ${ollamaName} \u2014 progress streams on the local-models:install channel`
+  };
+  return sendJSON10(res, 202, result);
 }
 async function handleRemove(req, res, deps) {
   const pool = deps.getModelPool();
@@ -10235,6 +10551,12 @@ var V1_BRIDGE_ROUTES = [
     scope: "manage-proposals",
     description: "Force a background-scheduler refresh tick and return emitted proposals (O4)."
   },
+  {
+    method: "POST",
+    pattern: /^\/api\/v1\/local-models\/candidates\/refresh(?:\?.*)?$/,
+    scope: "manage-proposals",
+    description: "Re-discover candidates live from HuggingFace, re-seed the recommender, re-rank."
+  },
   // ── LMLM dashboard pool mutation — operator-initiated install/remove ──
   // Modeled as auto-approved model proposals, so the same `manage-proposals`
   // write scope that governs approve/reject governs these too.
@@ -10425,6 +10747,7 @@ var OrchestratorServer = class {
   // LMLM Phase 6 — live model pool + refresh scheduler accessors.
   getModelPoolFn = null;
   getRefreshSchedulerFn = null;
+  getRefreshCandidatesFn = null;
   // LMLM Phase 7 — hardware / recommendations / model-proposal read accessors.
   getHardwareProfileFn = null;
   getRecommendationsFn = null;
@@ -10435,6 +10758,8 @@ var OrchestratorServer = class {
   // LMLM Phase 7 — bus→WS fan-out listeners for the model proposal/pool topics.
   modelProposalListener = null;
   modelPoolListener = null;
+  // LMLM Phase 10 — bus→WS fan-out for byte-level install progress (D3 async install).
+  modelInstallListener = null;
   recorder = null;
   planWatcher = null;
   tokenStore;
@@ -10481,6 +10806,7 @@ var OrchestratorServer = class {
     this.getBackendsFn = deps?.getBackends ?? null;
     this.getModelPoolFn = deps?.getModelPool ?? null;
     this.getRefreshSchedulerFn = deps?.getRefreshScheduler ?? null;
+    this.getRefreshCandidatesFn = deps?.getRefreshCandidates ?? null;
     this.getHardwareProfileFn = deps?.getHardwareProfile ?? null;
     this.getRecommendationsFn = deps?.getRecommendations ?? null;
     this.listModelProposalsFn = deps?.listModelProposals ?? null;
@@ -10503,8 +10829,10 @@ var OrchestratorServer = class {
     }
     this.modelProposalListener = (data) => this.broadcaster.broadcast(MODEL_PROPOSAL_TOPIC, data);
     this.modelPoolListener = (data) => this.broadcaster.broadcast(MODEL_POOL_TOPIC, data);
+    this.modelInstallListener = (data) => this.broadcaster.broadcast(MODEL_INSTALL_TOPIC, data);
     this.orchestrator.on(MODEL_PROPOSAL_TOPIC, this.modelProposalListener);
     this.orchestrator.on(MODEL_POOL_TOPIC, this.modelPoolListener);
+    this.orchestrator.on(MODEL_INSTALL_TOPIC, this.modelInstallListener);
   }
   /**
    * Broadcast a new interaction to all WebSocket clients.
@@ -10701,6 +11029,7 @@ var OrchestratorServer = class {
       // only when configured so absent ones surface as 503 (LMLM disabled).
       (req, res) => handleV1LocalModelsRoute(req, res, {
         getRefreshScheduler: this.getRefreshSchedulerFn ?? (() => null),
+        ...this.getRefreshCandidatesFn ? { getRefreshCandidates: this.getRefreshCandidatesFn } : {},
         getModelPool: () => this.getModelPoolFn?.() ?? null,
         ...this.getHardwareProfileFn ? { getHardwareProfile: this.getHardwareProfileFn } : {},
         ...this.getRecommendationsFn ? { getRecommendations: this.getRecommendationsFn } : {},
@@ -10816,6 +11145,10 @@ var OrchestratorServer = class {
       this.orchestrator.removeListener(MODEL_POOL_TOPIC, this.modelPoolListener);
       this.modelPoolListener = null;
     }
+    if (this.modelInstallListener) {
+      this.orchestrator.removeListener(MODEL_INSTALL_TOPIC, this.modelInstallListener);
+      this.modelInstallListener = null;
+    }
     if (this.planWatcher) {
       this.planWatcher.stop();
       this.planWatcher = null;
@@ -13908,6 +14241,13 @@ var Orchestrator = class extends import_node_events.EventEmitter {
    * so this map is the single source of truth post-migration.
    */
   localResolvers = /* @__PURE__ */ new Map();
+  /**
+   * Consumption Phase 1 (T2): bus listener that debounce-refreshes every local
+   * resolver when a `local-models:pool` mutation fires, so a just-installed or
+   * swapped model becomes usable within the refresh window instead of waiting up
+   * to `probeIntervalMs` for the next poll. Held for removal in {@link stop}.
+   */
+  poolRefreshListener = null;
   /** Phase 4 (D5): pool-state port shared by all local/pi resolvers. Null when LMLM disabled. */
   poolStateProvider = null;
   poolStateStore = null;
@@ -13945,6 +14285,13 @@ var Orchestrator = class extends import_node_events.EventEmitter {
    * see the Phase 2 candidate-parser gap noted on `startRefreshScheduler`.
    */
   modelRecommender = null;
+  /** Live HF candidate discovery (injectable for tests so startup makes no network calls). */
+  discoverCandidatesFn;
+  /** Snapshot of the last candidate seeding, surfaced to the refresh route. */
+  candidateSourceState = {
+    source: "frozen",
+    count: 0
+  };
   /** Test seam: injected timer/clock for the scheduler so no real 24h timer runs. */
   schedulerTimerOverride;
   /**
@@ -14038,6 +14385,7 @@ var Orchestrator = class extends import_node_events.EventEmitter {
   constructor(config, promptTemplate, overrides) {
     super();
     this.schedulerTimerOverride = overrides?.schedulerTimer ?? null;
+    this.discoverCandidatesFn = overrides?.discoverCandidates ?? (async () => ({ candidates: [], warnings: [] }));
     this.setMaxListeners(50);
     this.config = config;
     this.promptTemplate = promptTemplate;
@@ -14106,6 +14454,17 @@ var Orchestrator = class extends import_node_events.EventEmitter {
         if (def.apiKey !== void 0) resolverOpts.apiKey = def.apiKey;
         if (def.probeIntervalMs !== void 0) resolverOpts.probeIntervalMs = def.probeIntervalMs;
         if (this.poolStateProvider !== null) resolverOpts.poolState = this.poolStateProvider;
+        const endpoint = def.endpoint;
+        const apiKey = def.apiKey;
+        if (def.type === "local") {
+          resolverOpts.warmModel = (ollamaName) => {
+            void defaultWarmModel(endpoint, ollamaName, apiKey);
+          };
+        } else {
+          resolverOpts.warmModel = (model) => {
+            void defaultWarmModelViaCompletion(endpoint, model, apiKey);
+          };
+        }
         this.localResolvers.set(name, new LocalModelResolver(resolverOpts));
       }
     }
@@ -14128,9 +14487,27 @@ var Orchestrator = class extends import_node_events.EventEmitter {
         ...this.config.agent.secrets !== void 0 ? { secrets: this.config.agent.secrets } : {},
         cacheMetrics: this.cacheMetrics,
         decisionBus: this.routingDecisionBus,
-        getResolverModelFor: (name) => {
+        getResolverModelFor: (name, useCase) => {
+          const resolver = this.localResolvers.get(name);
+          return resolver ? () => resolver.resolveModel(useCase) : void 0;
+        },
+        // Consumption Phase 3 (T11): bind per-backend runtime feedback. A
+        // successful turn stamps `lastUsedAt` (LRU) via the pool and clears the
+        // resolver's circuit breaker; a failed turn feeds the breaker so a
+        // repeatedly-failing model is deprioritized. `modelPool` is read lazily
+        // (per dispatch) because it loads in start(), after this constructor.
+        getModelUsageHooksFor: (name) => {
           const resolver = this.localResolvers.get(name);
-          return resolver ? () => resolver.resolveModel() : void 0;
+          if (!resolver) return void 0;
+          return {
+            onModelUsed: (model) => {
+              resolver.recordSuccess(model);
+              void this.modelPool?.markUsed(model);
+            },
+            onModelFailed: (model) => {
+              resolver.recordFailure(model);
+            }
+          };
         }
       });
     } else {
@@ -14227,6 +14604,9 @@ var Orchestrator = class extends import_node_events.EventEmitter {
         isModelInUse: (ollamaName) => this.isLocalModelInUse(ollamaName),
         // LMLM Phase 6: expose the refresh scheduler for POST /local-models/refresh.
         getRefreshScheduler: () => this.refreshScheduler,
+        // Live candidate refresh for POST /local-models/candidates/refresh (the
+        // "Refresh" button). Null when LMLM is disabled → route 503s.
+        getRefreshCandidates: () => this.modelPool ? () => this.refreshCandidatesLive() : null,
         // LMLM Phase 7 read surface — hardware / recommendations / model proposals.
         // Each returns null/[] when LMLM is disabled so the route renders 503/[].
         getHardwareProfile: () => this.modelPool ? this.detectLmlmHardware() : null,
@@ -15294,10 +15674,51 @@ ${messages}`);
     const installerCfg = this.config.localModels?.installer;
     this.modelInstaller = new import_local_models5.OllamaInstallAdapter({
       baseUrl: installerCfg?.ollamaEndpoint ?? "http://localhost:11434",
-      onWarn
+      onWarn,
+      // Survive transient `/api/pull` drops (most often the host sleeping mid
+      // multi-GB download): ollama resumes from cached blobs, and any forward
+      // progress resets the budget, so an install nibbled through across several
+      // sleep cycles still completes instead of dead-ending in an error.
+      maxPullRetries: 5
     });
     this.modelPool = new import_local_models5.PoolManager({ store, installer: this.modelInstaller, onWarn });
   }
+  /**
+   * Resume installs interrupted by a restart. A proposal left `installing` had
+   * its background `ollama pull` cut short when the orchestrator went down; the
+   * pull is idempotent (ollama resumes from cached blobs), so we re-drive it.
+   * Fire-and-forget with its own error isolation — a resumed multi-GB download
+   * must not block startup, and a re-drive failure only logs.
+   */
+  redriveInterruptedInstalls() {
+    const pool = this.modelPool;
+    if (pool === null) return;
+    void (async () => {
+      try {
+        const modelProposals = await (0, import_core18.listProposals)(this.projectRoot, {
+          kind: "model"
+        });
+        const installing = modelProposals.filter((p) => p.status === "installing");
+        if (installing.length === 0) return;
+        this.logger.info(`Resuming ${installing.length} model install(s) interrupted by a restart`);
+        await redriveInstallingProposals(
+          {
+            pool,
+            bus: this,
+            updateProposal: (id, patch) => (0, import_core18.updateProposal)(this.projectRoot, id, patch),
+            decidedBy: "orchestrator",
+            isModelInUse: (name) => this.isLocalModelInUse(name)
+          },
+          installing,
+          {
+            onWarn: (message, cause) => this.logger.warn(message, cause !== void 0 ? { cause } : void 0)
+          }
+        );
+      } catch (err) {
+        this.logger.warn("interrupted-install re-drive failed", { cause: err });
+      }
+    })();
+  }
   /**
    * LMLM Phase 7 wiring: apply the operator's configured pool bounds (disk
    * budget + org/family allowlist) from `localModels.pool` to the live pool.
@@ -15343,8 +15764,8 @@ ${messages}`);
         allowedOrgs: this.config.localModels?.pool?.allowedOrgs ?? []
       });
     }
-    const recommend = (0, import_local_models5.createNativeRecommender)({ candidates });
-    this.modelRecommender = recommend;
+    this.seedRecommender(candidates, "frozen");
+    const recommend = (hardware) => this.modelRecommender(hardware);
     this.refreshScheduler = new import_local_models5.RefreshScheduler({
       runTick: () => (0, import_local_models5.runRefreshTick)({
         detectHardware: () => this.detectLmlmHardware(),
@@ -15374,6 +15795,55 @@ ${messages}`);
     });
     this.refreshScheduler.start();
   }
+  /** (Re)build the recommender over `candidates` and record the seeding source. */
+  seedRecommender(candidates, source) {
+    this.modelRecommender = (0, import_local_models5.createNativeRecommender)({ candidates });
+    this.candidateSourceState = { source, count: candidates.length };
+  }
+  /**
+   * Refresh ranking candidates live from HuggingFace, merge the curated
+   * `ollamaName`/`family` tags from the frozen snapshot (so results stay
+   * installable — decision A), and re-seed the recommender. Fail-closed: on any
+   * error or an empty installable result, the current candidates stand. Runs a
+   * `forceRefresh` tick so recommendations + proposals reflect the fresh set.
+   * Used by both the startup background refresh and the operator "Refresh" button.
+   */
+  async refreshCandidatesLive(signal) {
+    const poolCfg = this.config.localModels?.pool;
+    const orgs = poolCfg?.allowedOrgs ?? [];
+    if (orgs.length === 0) return this.candidateSourceState;
+    const curation = (0, import_local_models5.curationFromCandidates)((0, import_local_models5.loadFrozenCandidates)().candidates);
+    let result;
+    try {
+      result = await this.discoverCandidatesFn({
+        orgs,
+        curation,
+        ...signal ? { signal } : {},
+        onWarn: (m, cause) => this.logger.warn(m, cause !== void 0 ? { cause } : void 0)
+      });
+    } catch (err) {
+      this.logger.warn("LMLM live candidate discovery failed; keeping current candidates", {
+        cause: err
+      });
+      return this.candidateSourceState;
+    }
+    const selected = (0, import_local_models5.selectCandidates)(result.candidates, poolCfg);
+    if (selected.length === 0) {
+      this.logger.warn("LMLM live discovery yielded no installable candidates; keeping current", {
+        warnings: result.warnings
+      });
+      return this.candidateSourceState;
+    }
+    this.seedRecommender(selected, "live");
+    this.logger.info("LMLM candidates refreshed from HuggingFace", { count: selected.length });
+    await this.refreshScheduler?.forceRefresh();
+    this.emit("local-models:pool", {
+      phase: "candidates_refreshed",
+      source: "live",
+      count: selected.length
+    });
+    return this.candidateSourceState;
+  }
   /** Resolve the hardware profile for a refresh tick (operator override wins). */
   async detectLmlmHardware() {
     const override = this.config.localModels?.hardware?.override;
@@ -15421,12 +15891,27 @@ ${messages}`);
       if (this.poolStateStore !== null) {
         await this.poolStateStore.load();
         await this.applyConfiguredPoolBounds();
+        this.redriveInterruptedInstalls();
       }
       for (const resolver of this.localResolvers.values()) {
         await resolver.start();
       }
+      if (this.poolRefreshListener === null && this.localResolvers.size > 0) {
+        const listener = () => {
+          for (const resolver of this.localResolvers.values()) {
+            resolver.refresh();
+          }
+        };
+        this.poolRefreshListener = listener;
+        this.on("local-models:pool", listener);
+      }
     }
     this.startRefreshScheduler();
+    if (this.modelPool !== null) {
+      void this.refreshCandidatesLive().catch(
+        (err) => this.logger.warn("LMLM startup candidate refresh failed", { cause: err })
+      );
+    }
     this.pipeline = this.createIntelligencePipeline();
     this.server?.setPipeline(this.pipeline);
   }
@@ -15499,6 +15984,10 @@ ${messages}`);
     this.localModelStatusUnsubscribes = [];
     this.routingDecisionBus?.clearListeners();
     this.routingDecisionBus = null;
+    if (this.poolRefreshListener !== null) {
+      this.removeListener("local-models:pool", this.poolRefreshListener);
+      this.poolRefreshListener = null;
+    }
     for (const resolver of this.localResolvers.values()) {
       resolver.stop();
     }
@@ -16491,6 +16980,9 @@ function buildArchiveHooks(opts) {
     }
   };
 }
+
+// src/index.ts
+var import_local_models6 = require("@harness-engineering/local-models");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AnalysisArchive,
@@ -16546,6 +17038,7 @@ function buildArchiveHooks(opts) {
   defaultFetchModels,
   deriveSeedPaths,
   detectScopeTier,
+  discoverCandidates,
   discoverSkillCatalog,
   discoverSkillCatalogNames,
   emitProposalApproved,