llm-tuner 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-tuner",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Detects your hardware and finds the fastest configuration to run local LLMs with LM Studio or Ollama.",
   "keywords": [
     "llm",

package/src/cli/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { select, input, confirm, search } from '@inquirer/prompts';
-import { detectHardware, detectEngines, Tuner, installPlans, runInstall, listPresets, presetsDir, fmtBytes, readSettings, writeSettings, THEMES, PROFILES, DEFAULT_PROFILE, TunerError } from '../core/index.js';
+import { detectHardware, detectEngines, Tuner, installPlans, runInstall, listPresets, presetsDir, fmtBytes, readSettings, writeSettings, THEMES, PROFILES, DEFAULT_PROFILE, TunerError, checkUpdate, CURRENT_VERSION } from '../core/index.js';
 import { t as translate, LOCALES, errorText } from '../i18n/index.js';
-import { profileChoices, profileNotes, profileSwitchNote, profileEventLines, shouldAskProfile } from './profile.js';
+import { profileChoices, profileNotes, profileSwitchNote, profileEventLines, shouldAskProfile, parseContext } from './profile.js';
 
 const args = parseArgs(process.argv.slice(2));
 let { lang, theme } = await readSettings();
@@ -34,12 +34,18 @@ const isLight = () => theme === 'light';
 const c = {
   b: (s) => `\x1b[1m${s}\x1b[0m`,
   dim: (s) => isLight() ? `\x1b[90m${s}\x1b[0m` : `\x1b[2m${s}\x1b[0m`,
-  g: (s) => isLight() ? `\x1b[32m${s}\x1b[0m` : `\x1b[92m${s}\x1b[0m`,
+  g: (s) => isLight() ? `\x1b[38;2;40;138;0m${s}\x1b[0m` : `\x1b[38;2;101;255;0m${s}\x1b[0m`,
   y: (s) => isLight() ? `\x1b[33m${s}\x1b[0m` : `\x1b[93m${s}\x1b[0m`,
-  r: (s) => isLight() ? `\x1b[31m${s}\x1b[0m` : `\x1b[91m${s}\x1b[0m`,
-  cyan: (s) => isLight() ? `\x1b[36m${s}\x1b[0m` : `\x1b[96m${s}\x1b[0m`,
+  r: (s) => isLight() ? `\x1b[38;2;214;21;0m${s}\x1b[0m` : `\x1b[38;2;255;26;0m${s}\x1b[0m`,
+  cyan: (s) => isLight() ? `\x1b[38;2;0;124;153m${s}\x1b[0m` : `\x1b[38;2;0;229;255m${s}\x1b[0m`,
+  purple: (s) => isLight() ? `\x1b[38;2;120;0;199m${s}\x1b[0m` : `\x1b[38;2;154;0;255m${s}\x1b[0m`,
 };
 
+if (args.version) {
+  console.log(CURRENT_VERSION);
+  process.exit(0);
+}
+
 if (args.help) {
   console.log(t('cli.help', { presetsDir: presetsDir() }));
   process.exit(0);
@@ -114,7 +120,46 @@ async function settingsFlow() {
 }
 
 async function main() {
-  const out = (...a) => { if (!args.json) console.log(...a); };
+  const updatePromise = checkUpdate().catch(() => null);
+  const isTTY = Boolean(process.stdout.isTTY && !args.json);
+  let lastProgress = null;
+  let lastTelemetry = null;
+  let liveActive = false;
+
+  const clearLive = () => {
+    if (isTTY && liveActive) {
+      process.stdout.write('\r\x1b[K');
+      liveActive = false;
+    }
+  };
+
+  const renderLive = () => {
+    if (!isTTY || !lastProgress) return;
+    const pct = Math.min(100, Math.max(0, lastProgress.pct ?? 0));
+    const barLen = 16;
+    const filled = Math.round((pct / 100) * barLen);
+    const bar = c.cyan('━'.repeat(filled)) + c.dim('─'.repeat(barLen - filled));
+
+    let telem = '';
+    if (lastTelemetry) {
+      if (lastTelemetry.cpu) telem += ` · CPU ${lastTelemetry.cpu.percent}%`;
+      if (lastTelemetry.ram) {
+        telem += ` · RAM ${(lastTelemetry.ram.usedBytes / 1024 ** 3).toFixed(1)}/${(lastTelemetry.ram.totalBytes / 1024 ** 3).toFixed(1)} GB`;
+      }
+      if (lastTelemetry.gpus?.length) {
+        telem += ' · ' + lastTelemetry.gpus.map((g) => `GPU${g.index} ${(g.usedBytes / 1024 ** 3).toFixed(1)}/${(g.totalBytes / 1024 ** 3).toFixed(1)} GB`).join(' ');
+      }
+    }
+
+    process.stdout.write(`\r\x1b[K  [${bar}] ${String(pct).padStart(3)}%${telem}`);
+    liveActive = true;
+  };
+
+  const out = (...a) => {
+    if (args.json) return;
+    clearLive();
+    console.log(...a);
+  };
   out([
     '',
     `  ${c.cyan('  ╭───')}${c.dim('╷ ╷ ╷')}${c.cyan('───╮')}`,
@@ -125,6 +170,12 @@ async function main() {
     '',
   ].join('\n'));
 
+  const updateInfo = await updatePromise;
+  if (updateInfo?.updateAvailable) {
+    out(c.y(`  ▲ ${t('cli.updateAvailable', { current: updateInfo.currentVersion, latest: updateInfo.latestVersion })}`));
+    out(c.dim(`    ${t('cli.updateCommand', { cmd: 'npm install -g llm-tuner' })}\n`));
+  }
+
   const hw = await detectHardware();
   out(c.dim(`  ${hw.cpu.brand} · ${fmtBytes(hw.ram.totalBytes)} RAM`));
   for (const g of hw.gpus) out(c.dim(`  GPU${g.index} ${g.name} · ${fmtBytes(g.totalBytes)}${g.pcieGen ? ` · PCIe ${g.pcieGen}.0 x${g.pcieWidth}` : ''}${g.displayAttached ? t('cli.display') : ''}`));
@@ -168,7 +219,7 @@ async function main() {
   });
 
   // 3. Context
-  let ctx = Number(args.ctx) || null;
+  let ctx = parseContext(args.ctx);
   if (!ctx) {
     const presets = await listPresets({ engine: engineId, modelKey });
     const preview = await tuner.plan(modelKey, 8192);
@@ -176,11 +227,12 @@ async function main() {
     const list = Object.entries(preview.maxContext).map(([k, v]) => `KV ${k} ${v ? Math.floor(v / 1024) + 'K' : '—'}`).join(' · ');
     out(c.dim(`  ${t('cli.maxFullGpu', { list, train: Math.floor(limit / 1024) })}`));
     if (presets.length) out(c.dim(`  ${t('cli.tunedContexts', { list: presets.map((p) => `${p.ctx / 1024}K (${p.shortTps} t/s)`).join(', ') })}`));
-    ctx = Number(await input({
+    const answer = await input({
       message: t('cli.context'),
       default: String(presets.at(-1)?.ctx || Math.min(16384, limit)),
-      validate: (v) => (Number(v) >= 512 && Number(v) <= limit) || t('cli.contextRange', { limit }),
-    }));
+      validate: (v) => parseContext(v, limit) !== null || t('cli.contextRange', { limit }),
+    });
+    ctx = parseContext(answer, limit);
   }
 
   // 4. Profile
@@ -214,6 +266,14 @@ async function main() {
   let previous = null;
   tuner.on('progress', (e) => {
     if (args.json) return;
+    if (e.type === 'telemetry') {
+      lastTelemetry = e;
+      renderLive();
+      return;
+    }
+    if (e.progress) {
+      lastProgress = e.progress;
+    }
     if (e.type === 'variant-picked' || e.type === 'profile-fallback') {
       for (const line of profileEventLines(e, previous, t, advisedByWizard ? null : tuner.engine.name)) {
         out((line.level === 'warn' ? c.y : c.dim)(`  ${line.text}`));
@@ -229,26 +289,34 @@ async function main() {
       out(b.ok ? `      ${c.g('✓')} ${t('cli.benchShort', { tps: c.b(b.short.genTps + ' t/s') })}${b.deep ? t('cli.benchDeep', { tps: c.b(b.deep.genTps + ' t/s'), tokens: b.deep.promptTokens }) : ''} · CPU ${b.cpu.avg}% · VRAM ${vramStr(b.vramPeakBytes)}` : c.r(`      ✗ ${benchErrorText(b)}`));
     }
     if (e.type === 'preset-saved') out(c.g(`\n✓ ${t('common.presetSaved', { file: e.file })}`));
-  });
 
-  const result = await tuner.load(modelKey, ctx, {
-    profile,
-    force: !!args.force,
-    dryRun: !!args['dry-run'],
-    maxCandidates: Number(args.candidates) || 3,
-    confirmApply: async (preview) => {
-      out(c.b(`\n${t('cli.changes')}`));
-      if (engineId === 'lmstudio') {
-        preview.files.forEach((f) => out(`  ${f}`));
-        if (preview.restartsApp) out(c.y(`  ${t('cli.lmsRestart')}`));
-      } else {
-        out(`  ${t('cli.ollamaNewModel', { name: c.b(preview.tunedModel) })}`);
-        out(`  ${t('cli.ollamaServer', { env: Object.entries(preview.env).map(([k, v]) => `${k}=${v}`).join(' ') })}`);
-      }
-      return args.yes || confirm({ message: t('cli.confirmApply'), default: true });
-    },
+    renderLive();
   });
 
+  let result;
+  try {
+    result = await tuner.load(modelKey, ctx, {
+      profile,
+      force: !!args.force,
+      dryRun: !!args['dry-run'],
+      maxCandidates: Number(args.candidates) || 3,
+      confirmApply: async (preview) => {
+        clearLive();
+        out(c.b(`\n${t('cli.changes')}`));
+        if (engineId === 'lmstudio') {
+          preview.files.forEach((f) => out(`  ${f}`));
+          if (preview.restartsApp) out(c.y(`  ${t('cli.lmsRestart')}`));
+        } else {
+          out(`  ${t('cli.ollamaNewModel', { name: c.b(preview.tunedModel) })}`);
+          out(`  ${t('cli.ollamaServer', { env: Object.entries(preview.env).map(([k, v]) => `${k}=${v}`).join(' ') })}`);
+        }
+        return args.yes || confirm({ message: t('cli.confirmApply'), default: true });
+      },
+    });
+  } finally {
+    clearLive();
+  }
+
   if (args['dry-run']) out(c.y(`\n${t('cli.dryRun')}`));
   if (result.applied?.backups?.length) out(c.dim(`  ${t('common.backups', { list: result.applied.backups.join(', ') })}`));
   if (result.applied?.pendingCommands?.length) {
@@ -288,11 +356,12 @@ function vramStr(peaks = {}) {
 }
 
 function parseArgs(argv) {
-  const flags = new Set(['help', 'yes', 'dry-run', 'json', 'force', 'presets', 'settings']);
+  const flags = new Set(['help', 'version', 'yes', 'dry-run', 'json', 'force', 'presets', 'settings']);
   const o = {};
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '-h') o.help = true;
+    if (a === '-v') o.version = true;
     if (a === '/settings' || a === '/setting' || a === 'settings') o.settings = true;
     if (!a.startsWith('--')) continue;
     const k = a.slice(2);

package/src/cli/profile.js

@@ -4,11 +4,24 @@ import { PROFILES, fmtBytes } from '../core/index.js';
 // Reasons of a `variant-picked` event that mean the profile could not be honoured: the core flags them with a `profile-fallback` event right after.
 export const FALLBACK_REASONS = new Set(['profile.variant.noFullGpu']);
 
+/** Parses a context string (e.g. "8192", "8k", "16K") into tokens, or null if invalid or outside [512, limit]. */
+export function parseContext(v, limit = Infinity) {
+  if (v == null) return null;
+  const str = String(v).trim().toLowerCase();
+  const m = str.match(/^(\d+(?:\.\d+)?)\s*(k|m)?$/);
+  if (!m) return null;
+  const num = Number(m[1]);
+  if (!Number.isFinite(num)) return null;
+  const multiplier = m[2] === 'k' ? 1024 : m[2] === 'm' ? 1024 * 1024 : 1;
+  const val = Math.round(num * multiplier);
+  return val >= 512 && val <= limit ? val : null;
+}
+
 /** True when the CLI has to ask for the load profile; `args` are the parsed flags. */
 export function shouldAskProfile(args) {
   if (args.profile || args.yes || args.json) return false;
   // Engine, model and context all from flags: a scripted run that asked nothing before the profiles existed, so it stays prompt-free.
-  const flagged = Boolean(args.engine && args.model && Number(args.ctx));
+  const flagged = Boolean(args.engine && args.model && parseContext(args.ctx ?? args.context));
   return !flagged;
 }
 

package/src/core/engines/lmstudio.js

@@ -78,7 +78,8 @@ export const lmstudio = {
     try { list = JSON.parse(r.stdout); } catch { return []; }
     return list
       .filter((m) => m.type === 'llm' && m.format === 'gguf')
-      .map((m) => ({ key: m.modelKey || m.path, name: m.displayName, sizeBytes: m.sizeBytes, arch: m.architecture, quant: m.quantization?.name, maxContext: m.maxContextLength, moe: /A\d+B/i.test(m.paramsString || '') }));
+      .map((m) => ({ key: m.modelKey || m.path, name: m.displayName, sizeBytes: m.sizeBytes, arch: m.architecture, quant: m.quantization?.name, maxContext: m.maxContextLength, moe: /A\d+B/i.test(m.paramsString || '') }))
+      .sort((a, b) => (a.sizeBytes ?? 0) - (b.sizeBytes ?? 0) || (a.name || '').localeCompare(b.name || ''));
   },
 
   /** Resolve the GGUF file behind a model key using LM Studio's model index. */

package/src/core/engines/ollama.js

@@ -149,7 +149,8 @@ export const ollama = {
     const r = await fetchJson(`${ctx.detection.apiUrl}/api/tags`);
     return (r?.json?.models || [])
       .filter((m) => !/embed/i.test(m.name) && !/bert/i.test(m.details?.family || ''))
-      .map((m) => ({ key: m.name, name: m.name, sizeBytes: m.size, arch: m.details?.family, quant: m.details?.quantization_level, maxContext: null }));
+      .map((m) => ({ key: m.name, name: m.name, sizeBytes: m.size, arch: m.details?.family, quant: m.details?.quantization_level, maxContext: null }))
+      .sort((a, b) => (a.sizeBytes ?? 0) - (b.sizeBytes ?? 0) || (a.name || '').localeCompare(b.name || ''));
   },
 
   /** Downloaded variants (tags) of a model: [{ key, quant, sizeBytes, selected }]. */

package/src/core/index.js

@@ -8,3 +8,5 @@ export { fmtBytes, configDir } from './util.js';
 export { findPreset, savePreset, listPresets, presetsDir, presetPath, variantsSignature, hardwareFingerprint } from './presets.js';
 export { readSettings, writeSettings, settingsPath, THEMES, DEFAULT_THEME, normalizeTheme } from './settings.js';
 export { TunerError, benchError } from './errors.js';
+export { sampleRam, sampleGpus, startTelemetrySampler } from './telemetry.js';
+export { checkUpdate, isNewerVersion, CURRENT_VERSION } from './updater.js';

package/src/core/telemetry.js

@@ -0,0 +1,73 @@
+import os from 'node:os';
+import { nvidiaGpus } from './hardware.js';
+import { cpuSnapshot, cpuBusyPercent } from './util.js';
+
+/**
+ * Sample RAM usage information.
+ * @returns {{ totalBytes: number, freeBytes: number, usedBytes: number, percent: number }}
+ */
+export function sampleRam() {
+  const totalBytes = os.totalmem();
+  const freeBytes = os.freemem();
+  const usedBytes = totalBytes - freeBytes;
+  const percent = totalBytes > 0 ? +(100 * (1 - freeBytes / totalBytes)).toFixed(1) : 0;
+  return { totalBytes, freeBytes, usedBytes, percent };
+}
+
+/**
+ * Sample GPU usage information.
+ * @returns {Promise<Array<{ index: number, name: string, totalBytes: number, usedBytes: number, freeBytes: number, percent: number }>>}
+ */
+export async function sampleGpus() {
+  const gpus = await nvidiaGpus();
+  return gpus.map((g) => ({
+    index: g.index,
+    name: g.name,
+    totalBytes: g.totalBytes,
+    usedBytes: g.usedBytes,
+    freeBytes: g.freeBytes,
+    percent: g.totalBytes > 0 ? +(100 * (g.usedBytes / g.totalBytes)).toFixed(1) : 0,
+  }));
+}
+
+/**
+ * Start telemetry sampling at regular intervals.
+ * @param {Function} onSample - Callback function to receive sample data
+ * @param {number} intervalMs - Sampling interval in milliseconds (default: 500)
+ * @returns {{ stop: () => void }} Object with stop method to cancel the sampler
+ */
+export function startTelemetrySampler(onSample, intervalMs = 500) {
+  let timerId = null;
+  let prevCpu = cpuSnapshot();
+  let sampling = false;
+  let stopped = false;
+
+  const tick = async () => {
+    if (sampling || stopped) return;
+    sampling = true;
+    try {
+      const nowCpu = cpuSnapshot();
+      const cpuPct = +(cpuBusyPercent(prevCpu, nowCpu)).toFixed(1);
+      prevCpu = nowCpu;
+      const ram = sampleRam();
+      const gpus = await sampleGpus();
+      if (!stopped) onSample({ cpu: { percent: cpuPct }, ram, gpus });
+    } catch {
+      // Ignore transient sampling errors
+    } finally {
+      sampling = false;
+    }
+  };
+
+  timerId = setInterval(tick, intervalMs);
+
+  return {
+    stop() {
+      stopped = true;
+      if (timerId) {
+        clearInterval(timerId);
+        timerId = null;
+      }
+    },
+  };
+}

package/src/core/tuner.js

@@ -6,6 +6,7 @@ import { PROFILES, DEFAULT_PROFILE, normalizeProfile, kvTypesFor, meetsQuality,
 import { lmstudio } from './engines/lmstudio.js';
 import { ollama } from './engines/ollama.js';
 import { TunerError, benchError } from './errors.js';
+import { startTelemetrySampler } from './telemetry.js';
 
 export { pickBest };
 export const ENGINES = { lmstudio, ollama };
@@ -57,7 +58,23 @@ export class Tuner extends EventEmitter {
 
   log(type, data = {}) { this.emit('progress', { type, ...data, at: Date.now() }); }
 
-  listModels() { return this.engine.listModels(this.ctx); }
+  withTelemetry(fn) {
+    if (this._telemetryActive) return fn();
+    this._telemetryActive = true;
+    const sampler = startTelemetrySampler((sample) => this.log('telemetry', sample));
+    return Promise.resolve()
+      .then(fn)
+      .finally(() => {
+        this._telemetryActive = false;
+        sampler.stop();
+      });
+  }
+
+
+  async listModels() {
+    const list = (await this.engine.listModels?.(this.ctx)) || [];
+    return list.slice().sort((a, b) => (a.sizeBytes ?? 0) - (b.sizeBytes ?? 0) || (a.name || '').localeCompare(b.name || ''));
+  }
 
   async modelInfo(key) {
     const meta = await this.engine.modelMeta(this.ctx, key);
@@ -200,34 +217,50 @@ export class Tuner extends EventEmitter {
 
   /** Estimate, benchmark the top candidates for real, and return a report. The profile decides the winner. */
   async run(key, ctx, { maxCandidates = 3, depthFraction = 0.5, genTokens = 200, profile: requested = DEFAULT_PROFILE } = {}) {
-    const profile = normalizeProfile(requested);
-    this.log('status', { code: 'status.engine', params: { name: this.engine.name } });
-    const { model, candidates, maxContext } = await this.plan(key, ctx, { unload: true, profile });
-    const model2 = { key, meta: model.meta };
-    const toTest = candidates.slice(0, maxCandidates);
-    this.log('plan', { candidates: toTest.map(slim), maxContext });
+    return this.withTelemetry(async () => {
+      const profile = normalizeProfile(requested);
+      this.log('status', { code: 'status.engine', params: { name: this.engine.name }, progress: { pct: 5, phase: 'plan' } });
+      const { model, candidates, maxContext } = await this.plan(key, ctx, { unload: true, profile });
+      const model2 = { key, meta: model.meta };
+      const toTest = candidates.slice(0, maxCandidates);
+      this.log('plan', { candidates: toTest.map(slim), maxContext, progress: { pct: 10, phase: 'plan' } });
 
-    const depthTokens = Math.floor(ctx * depthFraction);
-    const results = [];
-    for (const [i, c] of toTest.entries()) {
-      this.log('candidate-start', { index: i, total: toTest.length, candidate: slim(c) });
-      let bench;
-      try {
-        bench = await this.engine.benchmark(this.ctx, model2, c, {
-          depthTokens, genTokens,
-          onProgress: (p) => this.log('bench-progress', { index: i, ...p }),
+      const depthTokens = Math.floor(ctx * depthFraction);
+      const results = [];
+      for (const [i, c] of toTest.entries()) {
+        this.log('candidate-start', {
+          index: i,
+          total: toTest.length,
+          candidate: slim(c),
+          progress: { pct: 10 + Math.round((i / toTest.length) * 70), phase: 'bench', current: i + 1, total: toTest.length },
+        });
+        let bench;
+        try {
+          bench = await this.engine.benchmark(this.ctx, model2, c, {
+            depthTokens, genTokens,
+            onProgress: (p) => this.log('bench-progress', {
+              index: i,
+              ...p,
+              progress: { pct: 10 + Math.round(((i + (p.phase === 'deep' ? 0.6 : 0.2)) / toTest.length) * 70), phase: 'bench', current: i + 1, total: toTest.length },
+            }),
+          });
+        } catch (err) {
+          bench = err?.name === 'TunerError' ? benchError(err.code, err.params) : { ok: false, error: String(err.message || err) };
+        }
+        results.push({ candidate: c, bench });
+        this.log('candidate-done', {
+          index: i,
+          candidate: slim(c),
+          bench,
+          progress: { pct: 10 + Math.round(((i + 1) / toTest.length) * 70), phase: 'bench', current: i + 1, total: toTest.length },
         });
-      } catch (err) {
-        bench = err?.name === 'TunerError' ? benchError(err.code, err.params) : { ok: false, error: String(err.message || err) };
       }
-      results.push({ candidate: c, bench });
-      this.log('candidate-done', { index: i, candidate: slim(c), bench });
-    }
-    const best = pickBest(results, profile);
-    const report = { engine: this.engine.id, model: key, ctx, profile, hw: this.hw, maxContext, results: results.map((r) => ({ candidate: slim(r.candidate), bench: r.bench })), best: best ? { candidate: best.candidate, bench: best.bench } : null };
-    this.log('done', { best: report.best && { candidate: slim(best.candidate), bench: best.bench } });
-    this.lastReport = { ...report, modelObj: model2 };
-    return report;
+      const best = pickBest(results, profile);
+      const report = { engine: this.engine.id, model: key, ctx, profile, hw: this.hw, maxContext, results: results.map((r) => ({ candidate: slim(r.candidate), bench: r.bench })), best: best ? { candidate: best.candidate, bench: best.bench } : null };
+      this.log('done', { best: report.best && { candidate: slim(best.candidate), bench: best.bench }, progress: { pct: 82, phase: 'bench' } });
+      this.lastReport = { ...report, modelObj: model2 };
+      return report;
+    });
   }
 
   /**
@@ -238,63 +271,65 @@ export class Tuner extends EventEmitter {
    * the preset, or pick one once the VRAM is free.
    */
   async load(key, ctx, { force = false, dryRun = false, maxCandidates = 3, depthFraction = 0.5, measure = true, confirmApply = async () => true, profile: requested = DEFAULT_PROFILE } = {}) {
-    const profile = normalizeProfile(requested);
-    const model = await this.modelInfo(key);
-    const modelBytes = model.meta.fileBytes;
-    // Listing the variants of a non-balanced profile needs no hardware; picking one does, so the pick waits.
-    const variants = profile === DEFAULT_PROFILE ? null : await this.variants(key);
-    const listed = variants?.map((v) => ({ key: v.key, sizeBytes: v.sizeBytes, selected: v.selected }));
-    // A profile preset is keyed by the key the user chose plus the profile, and goes stale with the variant list or its selected entry.
-    const keyed = variants ? { profile, variants: listed } : {};
-    let target = null;
-    let source = 'preset';
-    let candidate;
-    let report = null;
-    let found = force ? { preset: null, reason: 'forced' } : await findPreset({ engine: this.engine.id, modelKey: key, ctx, hw: this.hw, modelBytes, ...keyed });
+    return this.withTelemetry(async () => {
+      const profile = normalizeProfile(requested);
+      const model = await this.modelInfo(key);
+      const modelBytes = model.meta.fileBytes;
+      // Listing the variants of a non-balanced profile needs no hardware; picking one does, so the pick waits.
+      const variants = profile === DEFAULT_PROFILE ? null : await this.variants(key);
+      const listed = variants?.map((v) => ({ key: v.key, sizeBytes: v.sizeBytes, selected: v.selected }));
+      // A profile preset is keyed by the key the user chose plus the profile, and goes stale with the variant list or its selected entry.
+      const keyed = variants ? { profile, variants: listed } : {};
+      let target = null;
+      let source = 'preset';
+      let candidate;
+      let report = null;
+      let found = force ? { preset: null, reason: 'forced' } : await findPreset({ engine: this.engine.id, modelKey: key, ctx, hw: this.hw, modelBytes, ...keyed });
 
-    if (found.preset) {
-      candidate = found.preset.candidate;
-      this.log('preset-hit', { preset: found.preset, file: presetPath(this.engine.id, key, ctx, profile) });
-      // The preset remembers which variant it measured: nothing is picked and no VRAM is freed.
-      if (variants) target = this.presetTarget(key, profile, model, found.preset);
-    } else {
-      source = 'benchmark';
-      const code = { none: 'status.searchNone', hardware: 'status.searchHardware', model: 'status.searchModel', forced: 'status.searchForced', variants: 'status.searchVariants' }[found.reason];
-      this.log('status', { code });
-      if (variants) {
-        // The pick depends on the free VRAM, so the engine's models are unloaded before it.
-        await this.freeVram();
-        target = this.profileTarget(key, ctx, profile, model, variants);
+      if (found.preset) {
+        candidate = found.preset.candidate;
+        this.log('preset-hit', { preset: found.preset, file: presetPath(this.engine.id, key, ctx, profile), progress: { pct: 30, phase: 'preset' } });
+        // The preset remembers which variant it measured: nothing is picked and no VRAM is freed.
+        if (variants) target = this.presetTarget(key, profile, model, found.preset);
+      } else {
+        source = 'benchmark';
+        const code = { none: 'status.searchNone', hardware: 'status.searchHardware', model: 'status.searchModel', forced: 'status.searchForced', variants: 'status.searchVariants' }[found.reason];
+        this.log('status', { code, progress: { pct: 5, phase: 'plan' } });
+        if (variants) {
+          // The pick depends on the free VRAM, so the engine's models are unloaded before it.
+          await this.freeVram();
+          target = this.profileTarget(key, ctx, profile, model, variants);
+        }
+        report = await this.run(target?.key ?? key, ctx, { maxCandidates, depthFraction, profile });
+        if (!report.best) throw new TunerError('errors.noConfigWorked');
+        candidate = report.best.candidate;
+        // Quality found no configuration that keeps its promise: say so once.
+        if (profile === 'quality' && !target.fallback && !meetsQuality(candidate)) this.log('profile-fallback', { profile, reasonCode: 'profile.fallback.noFullGpuConfig', variant: target.picked });
+        if (!dryRun) {
+          const saved = await savePreset({ engine: this.engine.id, modelKey: key, ctx, hw: this.hw, modelBytes, best: report.best, results: this.lastReport.results, ...(target ? { profile, variant: target.variant, variants: listed } : {}) });
+          this.log('preset-saved', { file: saved.file, preset: saved.preset, progress: { pct: 85, phase: 'save' } });
+        }
       }
-      report = await this.run(target?.key ?? key, ctx, { maxCandidates, depthFraction, profile });
-      if (!report.best) throw new TunerError('errors.noConfigWorked');
-      candidate = report.best.candidate;
-      // Quality found no configuration that keeps its promise: say so once.
-      if (profile === 'quality' && !target.fallback && !meetsQuality(candidate)) this.log('profile-fallback', { profile, reasonCode: 'profile.fallback.noFullGpuConfig', variant: target.picked });
-      if (!dryRun) {
-        const saved = await savePreset({ engine: this.engine.id, modelKey: key, ctx, hw: this.hw, modelBytes, best: report.best, results: this.lastReport.results, ...(target ? { profile, variant: target.variant, variants: listed } : {}) });
-        this.log('preset-saved', { file: saved.file, preset: saved.preset });
-      }
-    }
 
-    // The variant a profile picked is applied and loaded with its own metadata.
-    const loadKey = target?.key ?? key;
-    const meta = loadKey === key ? model.meta : variants?.find((v) => v.key === loadKey)?.meta ?? (await this.modelInfo(loadKey)).meta;
-    const modelObj = { key: loadKey, meta };
-    const preview = await this.engine.apply(this.ctx, modelObj, candidate, { dryRun: true });
-    if (dryRun) return { source, candidate: slim(candidate), report, preview, profile, variant: loadKey };
-    if (!(await confirmApply(preview))) return { source, candidate: slim(candidate), report, preview, applied: false, profile, variant: loadKey };
+      // The variant a profile picked is applied and loaded with its own metadata.
+      const loadKey = target?.key ?? key;
+      const meta = loadKey === key ? model.meta : variants?.find((v) => v.key === loadKey)?.meta ?? (await this.modelInfo(loadKey)).meta;
+      const modelObj = { key: loadKey, meta };
+      const preview = await this.engine.apply(this.ctx, modelObj, candidate, { dryRun: true });
+      if (dryRun) return { source, candidate: slim(candidate), report, preview, profile, variant: loadKey };
+      if (!(await confirmApply(preview))) return { source, candidate: slim(candidate), report, preview, applied: false, profile, variant: loadKey };
 
-    this.log('status', { code: 'status.applying' });
-    const applied = await this.engine.apply(this.ctx, modelObj, candidate, { useSudo: true, skipIfApplied: source === 'preset' });
-    this.log('applied', { result: applied });
-    if (applied.pendingCommands?.length) return { source, candidate: slim(candidate), report, applied, loaded: null, profile, variant: loadKey };
+      this.log('status', { code: 'status.applying', progress: { pct: 88, phase: 'apply' } });
+      const applied = await this.engine.apply(this.ctx, modelObj, candidate, { useSudo: true, skipIfApplied: source === 'preset' });
+      this.log('applied', { result: applied, progress: { pct: 92, phase: 'apply' } });
+      if (applied.pendingCommands?.length) return { source, candidate: slim(candidate), report, applied, loaded: null, profile, variant: loadKey };
 
-    this.log('status', { code: 'status.loading' });
-    this.ctx.detection = await this.engine.detect();
-    const loaded = await this.engine.load(this.ctx, modelObj, { candidate, depthTokens: 0, genTokens: measure ? 200 : 1, onProgress: (p) => this.log('bench-progress', p) });
-    this.log('loaded', { bench: loaded });
-    return { source, candidate: slim(candidate), report, applied, loaded, profile, variant: loadKey };
+      this.log('status', { code: 'status.loading', progress: { pct: 95, phase: 'load' } });
+      this.ctx.detection = await this.engine.detect();
+      const loaded = await this.engine.load(this.ctx, modelObj, { candidate, depthTokens: 0, genTokens: measure ? 200 : 1, onProgress: (p) => this.log('bench-progress', { ...p, progress: { pct: 98, phase: 'load' } }) });
+      this.log('loaded', { bench: loaded, progress: { pct: 100, phase: 'done' } });
+      return { source, candidate: slim(candidate), report, applied, loaded, profile, variant: loadKey };
+    });
   }
 }