badgr-cli 1.0.43 → 1.0.44

package/README.md

@@ -72,7 +72,19 @@ badgr down <deployment-id>
 | `badgr transcribe <audio>` | Whisper transcription, print transcript |
 | `badgr embed <model> <input>` | Text embeddings, output JSONL |
 
-`badgr serve --list-aliases` lists the blessed vLLM model shortcuts (`qwen-7b`, `llama-8b`, `qwen-coder-7b`) that can be used in place of a full model ID.
+`badgr serve --list-aliases` lists the tested vLLM model routes (`qwen-7b`, `llama-8b`, `qwen-coder-7b`) that can be used in place of a full model ID.
+
+### Model support levels
+
+`badgr serve qwen-7b` is the happy path — a tested route with no extra setup. `badgr serve` also accepts any other model ID or a custom container, with the CLI honest (but brief) about what that means:
+
+| Level | What it means |
+|-------|---------------|
+| **Tested route** (`badgr serve qwen-7b`) | One of the aliases above — tested and officially supported. No extra caveats printed. |
+| **Best-effort Hugging Face model** (`badgr serve <org>/<model>`) | Any other Hugging Face model ID. Badgr will try a compatible route — not a guarantee every model works. |
+| **Custom container** (`badgr serve --image ...`) | You own the server behavior; Badgr manages runtime, logs, spend caps, teardown, and the receipt. |
+
+Gated Hugging Face models (e.g. Llama, Gemma) may need `--env HF_TOKEN=$HF_TOKEN`. Badgr doesn't warn about this up front — it only prints the hint if the deployment actually fails to start, so tested and working launches stay short.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "badgr-cli",
-  "version": "1.0.43",
+  "version": "1.0.44",
   "description": "Badgr — run or serve GPU workloads from one command",
   "type": "module",
   "bin": {

package/src/catalog.js

@@ -471,6 +471,21 @@ export const BLESSED_VLLM_MODELS = {
   },
 };
 
+// Hugging Face org/model prefixes that are known to gate access behind a license
+// click-through. Used only to print a helpful HF_TOKEN hint — not exhaustive.
+const GATED_MODEL_PREFIXES = [
+  'meta-llama/',
+  'google/gemma',
+  'mistralai/Mistral-Large',
+  'mistralai/Mixtral-8x22B',
+];
+
+/** Best-effort heuristic: is this HF model ID likely to require HF_TOKEN? */
+export function isLikelyGatedModel(modelId) {
+  if (!modelId) return false;
+  return GATED_MODEL_PREFIXES.some(prefix => modelId.startsWith(prefix));
+}
+
 /** Blessed ComfyUI workflows accepted by `POST /v1/jobs` comfy.batch. */
 export const BLESSED_COMFY_WORKFLOWS = {
   'sdxl-basic': {

package/src/commands/run.js

@@ -8,6 +8,7 @@ import { addReceipt, updateReceipt, generateReceiptId } from '../store.js';
 import { normalizeTier, callWithFallback, HIGH_RATE_THRESHOLD } from '../fallback.js';
 import { formatCliError } from '../errors.js';
 import { TEMPLATE_MAP, buildTemplateFlags, parseTemplateOverrides } from '../catalog.js';
+import { stage as _stage, stageDone as _stageDone, writeBlock as _writeBlock, clearBlock as _clearBlock, renderLiveBlock as _renderLiveBlock } from '../progress.js';
 
 /**
  * Flow 1 — local project (primary):
@@ -105,6 +106,20 @@ const HEARTBEAT_WARN_POLLS  = 3;
 const HEARTBEAT_KILL_POLLS  = 15;
 const STARTUP_STATES = new Set(['queued', 'provisioning', 'starting']);
 
+// Shared closing block for every terminal path (success, failure, cap, heartbeat loss) —
+// always states exit code (when known), whether teardown/billing succeeded, and how to
+// pull the receipt, so the user is never left guessing what happened.
+function _printFinalInfo(chalk, { exitCode = undefined, teardownOk, jobId, rcptId, logsAvailable = true }) {
+  if (exitCode !== null && exitCode !== undefined) {
+    console.log(`  ${chalk.bold('Exit code:')} ${exitCode !== 0 ? chalk.red(exitCode) : chalk.green(exitCode)}`);
+  }
+  console.log(`  ${chalk.bold('Teardown:')}  ${teardownOk ? chalk.green('succeeded') : chalk.red(`failed — run: badgr down ${jobId}`)}`);
+  console.log(`  ${chalk.bold('Billing:')}   ${teardownOk ? 'stopped' : 'unconfirmed — check receipt'}`);
+  if (logsAvailable) console.log(`  ${chalk.bold('Logs:')}      badgr logs ${jobId}`);
+  console.log(`  ${chalk.bold('Job ID:')}    ${jobId}`);
+  console.log(`  ${chalk.bold('Receipt:')}   badgr receipts ${rcptId}`);
+}
+
 export function classifyFailure(finalStatus, exitCode) {
   if (finalStatus === 'failed' && (exitCode === null || exitCode === undefined)) return 'infrastructure';
   if (exitCode !== null && exitCode !== undefined && exitCode !== 0) return 'customer_code';
@@ -128,24 +143,6 @@ function parseProviderLine(line) {
   };
 }
 
-function renderStatusBar(chalk, { elapsedMs, ratePerHour, gpuUtil, cpuUtil, maxRuntimeMs, maxCost }) {
-  const spent = ratePerHour * (elapsedMs / 3_600_000);
-  const parts = [`⏱ ${fmtRuntime(elapsedMs)}`];
-  if (ratePerHour > 0) parts.push(`$${spent.toFixed(4)} spent`);
-  if (gpuUtil !== null) parts.push(`GPU ${gpuUtil.toFixed(0)}%`);
-  if (cpuUtil !== null) parts.push(`CPU ${cpuUtil.toFixed(0)}%`);
-  if (maxRuntimeMs) {
-    const left = Math.max(0, maxRuntimeMs - elapsedMs);
-    parts.push(`${fmtRuntime(left)} left`);
-  }
-  if (maxCost && ratePerHour > 0) {
-    const budgetLeft = Math.max(0, maxCost - spent);
-    parts.push(`$${budgetLeft.toFixed(4)} budget left`);
-  }
-  parts.push('Ctrl+C to stop');
-  return chalk.dim('  ' + parts.join('  •  '));
-}
-
 // Wait for status to leave 'starting'/'queued'/'provisioning'.
 // Returns the dep once it leaves startup states (or the last known state on timeout).
 async function waitForRunning(config, depId, chalk) {
@@ -200,7 +197,7 @@ async function waitForRunning(config, depId, chalk) {
   });
 }
 
-async function attachToJob(config, depId, { chalk, maxRuntimeMs = null, maxCost = null, ratePerHour = 0, onTeardown, isShuttingDown }) {
+async function attachToJob(config, depId, { chalk, maxRuntimeMs = null, maxCost = null, ratePerHour = 0, onTeardown, isShuttingDown, stageLine }) {
   const TERMINAL = new Set(['stopped', 'failed', 'completed', 'succeeded']);
   const POLL_MS  = 4000;
   let seenContent     = new Set();
@@ -209,7 +206,8 @@ async function attachToJob(config, depId, { chalk, maxRuntimeMs = null, maxCost
   let gpuUtil         = null;
   let cpuUtil         = null;
   let sshShown        = false;
-  let statusBarActive = false;
+  let statusWord      = 'running';
+  let blockLines      = 0;
   const startMs       = Date.now();
 
   // tearing: guards against double-teardown for cap/heartbeat paths within this function.
@@ -218,17 +216,17 @@ async function attachToJob(config, depId, { chalk, maxRuntimeMs = null, maxCost
   let tickerInterval = null;
   const startTicker = () => {
     if (tickerInterval) return;
-    statusBarActive = true;
     tickerInterval = setInterval(() => {
-      const bar = renderStatusBar(chalk, {
-        elapsedMs: Date.now() - startMs, ratePerHour, gpuUtil, cpuUtil, maxRuntimeMs, maxCost,
-      });
-      process.stdout.write(`\r${bar}   `);
+      const elapsedSec = Math.round((Date.now() - startMs) / 1000);
+      const spend = ratePerHour * (elapsedSec / 3600);
+      blockLines = _writeBlock(blockLines, _renderLiveBlock(chalk, {
+        stageLine, elapsedSec, statusWord, spend, id: depId,
+      }));
     }, 1000);
   };
   const stopTicker = () => {
     if (tickerInterval) { clearInterval(tickerInterval); tickerInterval = null; }
-    if (statusBarActive) { process.stdout.write('\r\x1b[2K'); statusBarActive = false; }
+    if (blockLines > 0) { _clearBlock(blockLines); blockLines = 0; }
   };
 
   try {
@@ -271,6 +269,7 @@ async function attachToJob(config, depId, { chalk, maxRuntimeMs = null, maxCost
         consecutiveErrs++;
         if (lastStatus === 'running') {
           const lostSec = Math.round((consecutiveErrs * POLL_MS) / 1000);
+          if (consecutiveErrs >= HEARTBEAT_WARN_POLLS) statusWord = 'stuck';
           if (consecutiveErrs === HEARTBEAT_WARN_POLLS) {
             stopTicker();
             console.log(chalk.yellow(`\n  ⚠ No heartbeat for ${lostSec}s — cloud machine may be unresponsive`));
@@ -293,6 +292,7 @@ async function attachToJob(config, depId, { chalk, maxRuntimeMs = null, maxCost
         }
         lastStatus = status;
       }
+      if (status === 'running') statusWord = seenContent.size === 0 ? 'no logs yet' : 'running';
 
       try {
         const logData = await callApi(`/deployments/${depId}/logs`, {
@@ -605,14 +605,14 @@ export async function runCommand(config, args, chalk) {
   if (flags.cmd)    console.log(`  ${chalk.bold('Command:')}  ${flags.cmd}`);
   if (command)      console.log(`  ${chalk.bold('Command:')}  ${command.join(' ')}`);
   if (image)        console.log(`  ${chalk.bold('Image:')}    ${image}`);
-  if (gpu)          console.log(`  ${chalk.bold('GPU:')}      ${gpu}`);
-  else              console.log(`  ${chalk.bold('GPU:')}      ${chalk.dim('auto')}`);
+  if (flags.gpu)    console.log(`  ${chalk.bold('GPU:')}      ${gpu}`);
   if (flags.minVram)  console.log(`  ${chalk.bold('Min VRAM:')}   ${flags.minVram} GB`);
   const runtimeLabel = isDefaultRuntime
-    ? `${effectiveMaxRuntime}min ${chalk.dim('(default — use --max-runtime N to override)')}`
-    : `${effectiveMaxRuntime}min`;
+    ? `${effectiveMaxRuntime} min ${chalk.dim('(default — use --max-runtime N to override)')}`
+    : `${effectiveMaxRuntime} min`;
+  console.log(`  ${chalk.bold('Max cost:')}    ${maxCost ? `$${maxCost.toFixed(2)}` : chalk.dim('none')}`);
   console.log(`  ${chalk.bold('Max runtime:')} ${runtimeLabel}`);
-  if (maxCost)        console.log(`  ${chalk.bold('Max cost:')}    $${maxCost.toFixed(2)}`);
+  console.log(`  ${chalk.bold('Auto-stop:')}   ${maxCost ? 'enabled' : chalk.yellow('disabled — stop manually with badgr down')}`);
   if (flags.maxPrice) console.log(`  ${chalk.bold('Max price:')}   $${flags.maxPrice.toFixed(2)}/hr`);
   if (detach)         console.log(`  ${chalk.dim('(detached — returns immediately)')}`);
   if (flags.env?.length) console.log(`  ${chalk.bold('Env:')}      ${flags.env.join(', ')}`);
@@ -636,6 +636,10 @@ export async function runCommand(config, args, chalk) {
     }
   }
 
+  // Total stages: local-path runs get a "Preparing upload" stage the others don't.
+  const STAGE_TOTAL = isLocalPath ? 5 : 4;
+  let stageN = 1;
+
   // ── Upload local project zip (Flow 1) ─────────────────────────────────────
   let codeUri = null;
   if (isLocalPath) {
@@ -646,9 +650,10 @@ export async function runCommand(config, args, chalk) {
       process.exitCode = 1;
       return;
     }
+    console.log(chalk.dim(_stageDone(stageN, STAGE_TOTAL, 'Preparing upload...')));
+    stageN++;
   }
 
-  console.log(chalk.dim('  Finding suitable capacity...'));
   if (process.env.BADGR_DEBUG === '1' || process.env.BADGR_DEBUG === 'true') {
     console.log(chalk.dim(`  API: ${config.baseUrl}`));
   }
@@ -717,12 +722,10 @@ export async function runCommand(config, args, chalk) {
 
   const rate = dep.cost_per_hour || 0;
 
-  console.log(chalk.dim('  Capacity found.\n'));
-  console.log(chalk.bold(`  Job ID:    ${chalk.cyan(dep.deployment_id)}`));
-  console.log(`  ${chalk.bold('GPU:')}      ${dep.gpu_type} × ${dep.gpu_count}`);
-  if (rate > 0) console.log(`  ${chalk.bold('Rate:')}     $${rate.toFixed(2)}/hr`);
-  if (maxCost)  console.log(`  ${chalk.bold('Max cost:')} $${maxCost.toFixed(2)}`);
-  console.log(`  ${chalk.bold('Receipt:')}  ${chalk.dim(rcptId)}`);
+  console.log(chalk.dim(_stageDone(stageN, STAGE_TOTAL, 'Finding a working route...')));
+  stageN++;
+  console.log(chalk.dim(_stageDone(stageN, STAGE_TOTAL, 'Starting runtime...')));
+  stageN++;
 
   if (rate > HIGH_RATE_THRESHOLD && !maxCost) {
     console.log(chalk.yellow(`\n  Selected capacity rate: $${rate.toFixed(2)}/hr`));
@@ -745,30 +748,34 @@ export async function runCommand(config, args, chalk) {
     if (teardownCalled) return;
     teardownCalled = true;
 
-    const labels = {
-      'max-runtime':    chalk.yellow('\n  ⏱ Max runtime reached — stopping job...'),
-      'max-cost':       chalk.yellow('\n  💰 Spend cap reached — stopping job...'),
-      'heartbeat-lost': chalk.red('\n  ✗ No response from machine — stopping job...'),
-      'interrupted':    chalk.yellow('\n  Stopping job...'),
+    const stageLabels = {
+      'max-runtime':    'Stopped — runtime cap reached',
+      'max-cost':       'Stopped — spend cap reached',
+      'heartbeat-lost': 'Failed — lost connection to machine',
+      'interrupted':    'Stopped',
     };
-    console.log(labels[reason] ?? chalk.yellow('\n  Stopping job...'));
 
+    let teardownOk = true;
     try {
       await terminateDeployment(config, dep.deployment_id);
     } catch {
       // terminateDeployment retries 3×; best-effort if all fail
+      teardownOk = false;
     }
 
     const runtimeMs = Date.now() - attachStart;
     const finalCost = ratePerHour * (runtimeMs / 3_600_000);
     updateReceipt(rcptId, {
       status: reason,
-      teardownStatus: 'terminated',
+      teardownStatus: teardownOk ? 'terminated' : 'failed',
       runtimeSeconds: Math.round(runtimeMs / 1000),
       finalCost,
     });
-    console.log(chalk.dim(`  Runtime: ${fmtRuntime(runtimeMs)}  •  Est. cost: $${finalCost.toFixed(4)}`));
-    console.log(chalk.dim('  Job stopped. Billing ended.\n'));
+    console.log();
+    console.log(chalk.dim(_stage(STAGE_TOTAL, STAGE_TOTAL, stageLabels[reason] ?? 'Stopped')));
+    console.log(chalk.dim(`  Runtime: ${fmtRuntime(runtimeMs)}  •  Estimated cost: ~$${finalCost.toFixed(2)}`));
+    _printFinalInfo(chalk, { exitCode: null, teardownOk, jobId: dep.deployment_id, rcptId });
+    console.log();
   }
 
   // ── SIGINT handler — installed immediately after we have a deployment ID ───
@@ -802,7 +809,8 @@ export async function runCommand(config, args, chalk) {
     return;
   }
 
-  console.log(chalk.dim('\n  ── Running command (Ctrl+C to stop) ────────────────────────────\n'));
+  const runStageLine = _stage(stageN, STAGE_TOTAL, 'Running command...');
+  console.log(chalk.dim(`\n  [${stageN}/${STAGE_TOTAL}] Running command (Ctrl+C to stop)`));
 
   attachStart = Date.now();
   const { status: finalStatus, exitCode, runtimeMs, failureType } = await attachToJob(config, dep.deployment_id, {
@@ -812,6 +820,7 @@ export async function runCommand(config, args, chalk) {
     ratePerHour,
     onTeardown: teardown,
     isShuttingDown: () => shuttingDown,
+    stageLine: runStageLine,
   });
 
   // Remove SIGINT handler — job is done (or SIGINT was handled)
@@ -820,7 +829,11 @@ export async function runCommand(config, args, chalk) {
   // 'interrupted' = SIGINT handler is managing teardown + exit — don't duplicate
   if (finalStatus === 'interrupted') return;
 
-  console.log();
+  // 'capped' = max-runtime or max-cost path; teardown() already printed the full summary
+  if (finalStatus === 'capped') {
+    process.exitCode = 1;
+    return;
+  }
 
   const finalCost = ratePerHour * (runtimeMs / 3_600_000);
   updateReceipt(rcptId, {
@@ -832,20 +845,7 @@ export async function runCommand(config, args, chalk) {
     teardownStatus: (finalStatus === 'completed' || finalStatus === 'succeeded') ? 'terminated' : 'failed',
   });
 
-  console.log(`  ${chalk.bold('Runtime:')}  ${fmtRuntime(runtimeMs)}`);
-  if (ratePerHour > 0) {
-    console.log(`  ${chalk.bold('Cost:')}     $${finalCost.toFixed(4)}  (${chalk.dim(`$${ratePerHour.toFixed(2)}/hr`)})`);
-  }
-  if (exitCode !== null && exitCode !== undefined) {
-    console.log(`  ${chalk.bold('Exit code:')} ${exitCode !== 0 ? chalk.red(exitCode) : chalk.green(exitCode)}`);
-  }
-  console.log(`  ${chalk.bold('Receipt:')}  ${chalk.dim(rcptId)}`);
-
-  // 'capped' = max-runtime or max-cost path; teardown message already printed
-  if (finalStatus === 'capped') {
-    process.exitCode = 1;
-    return;
-  }
+  console.log();
 
   if (finalStatus === 'failed' || (exitCode !== null && exitCode !== 0)) {
     if (failureType === 'infrastructure') {
@@ -853,16 +853,23 @@ export async function runCommand(config, args, chalk) {
     } else {
       console.error(formatCliError('JOB_FAILED', { exitCode, deploymentId: dep.deployment_id }, chalk));
     }
+    console.log(chalk.dim(_stage(STAGE_TOTAL, STAGE_TOTAL, 'Failed')));
+    console.log(chalk.dim(`  Runtime: ${fmtRuntime(runtimeMs)}  •  Estimated cost: ~$${finalCost.toFixed(2)}`));
+    // The container already reached a terminal state on the provider side by the
+    // time we observe it here, so billing is already stopped — no extra teardown call needed.
+    _printFinalInfo(chalk, { exitCode, teardownOk: true, jobId: dep.deployment_id, rcptId });
     process.exitCode = exitCode ?? 1;
     return;
   }
 
   if ((finalStatus === 'completed' || finalStatus === 'succeeded') && (exitCode === 0 || exitCode === null)) {
+    let teardownOk = true;
     try {
       await terminateDeployment(config, dep.deployment_id);
-    } catch { /* already stopped */ }
-    console.log(chalk.green(`\n  ✓ Complete`));
-    console.log(chalk.dim(`  Billing ended`));
+    } catch { teardownOk = false; /* already stopped, or best-effort */ }
+    console.log(chalk.green(_stage(STAGE_TOTAL, STAGE_TOTAL, 'Complete')));
+    console.log(chalk.dim(`  Runtime: ${fmtRuntime(runtimeMs)}  •  Estimated cost: ~$${finalCost.toFixed(2)}`));
+    _printFinalInfo(chalk, { exitCode, teardownOk, jobId: dep.deployment_id, rcptId });
 
     if (flags.save && config.apiKey) {
       try {

package/src/commands/serve.js

@@ -1,9 +1,10 @@
 import { requireApiKey } from '../config.js';
 import { callApi, listDeployments } from '../api.js';
 import { addDeployment, addReceipt, updateReceipt, generateReceiptId } from '../store.js';
-import { normalizeTier, callWithFallback, HIGH_RATE_THRESHOLD } from '../fallback.js';
+import { normalizeTier, callWithFallback } from '../fallback.js';
 import { formatCliError } from '../errors.js';
-import { TEMPLATE_MAP, buildTemplateFlags, parseTemplateOverrides, BLESSED_VLLM_MODELS } from '../catalog.js';
+import { TEMPLATE_MAP, buildTemplateFlags, parseTemplateOverrides, BLESSED_VLLM_MODELS, isLikelyGatedModel } from '../catalog.js';
+import { stage as _stage, stageDone as _stageDone, writeBlock as _writeBlock, clearBlock as _clearBlock, renderLiveBlock as _renderLiveBlock } from '../progress.js';
 
 const LLAMA_CPP_IMAGE = 'michaelmanleyx/llama-cpp:server-cuda';
 
@@ -64,18 +65,36 @@ function parseEnvFlag(envList) {
   return obj;
 }
 
+function envObjHasHfToken(envList) {
+  return (envList || []).some(kv => kv.startsWith('HF_TOKEN='));
+}
+
+// Extract a parameter-count-in-billions hint from a model/file name, e.g.
+// "Qwen2.5-0.5B-Instruct" → 0.5, "Llama-3.1-8B-Instruct" → 8, "Mixtral-8x7B" → 56.
+// Splits into delimiter-bounded segments first so a version number like "2.5"
+// in "Qwen2.5-0.5B" is never mistaken for the param count — only a segment that
+// IS entirely "<digits>b" or "<digits>x<digits>b" counts as a size hint.
+function _extractParamsB(name) {
+  const s = name.toLowerCase();
+  const segments = s.split(/[^a-z0-9.]+/).filter(Boolean);
+  for (const seg of segments) {
+    const moe = seg.match(/^(\d+)x(\d+)b$/);
+    if (moe) return parseInt(moe[1], 10) * parseInt(moe[2], 10);
+  }
+  for (const seg of segments) {
+    const m = seg.match(/^(\d+(?:\.\d+)?)b$/);
+    if (m) return parseFloat(m[1]);
+  }
+  return null;
+}
+
 // Mirror of backend workload_profile.py infer_profile_from_model — for pre-flight display.
+// Sizing is only asserted when a param-count hint is found in the name; unknown
+// sizing falls back to the 7B–8B/24GB+ default rather than guessing small or large.
 function _inferServeProfile(modelName) {
-  const s = modelName.toLowerCase();
-  const moe = s.match(/(\d+)x(\d+)b/);
-  let paramsB;
-  if (moe) {
-    paramsB = parseInt(moe[1]) * parseInt(moe[2]);
-  } else {
-    const m = s.match(/(\d+)b/);
-    paramsB = m ? parseInt(m[1]) : null;
-  }
+  const paramsB = _extractParamsB(modelName);
   if (paramsB === null) return { label: 'inference (7B–8B model)', vram: '24+ GB', gpus: ['RTX 4090', 'A6000', 'L40S'] };
+  if (paramsB <= 3)    return { label: 'inference (≤3B model)',    vram: '8+ GB',  gpus: ['RTX 3090', 'RTX 4090', 'L4'] };
   if (paramsB <= 9)    return { label: 'inference (7B–8B model)', vram: '24+ GB', gpus: ['RTX 4090', 'A6000', 'L40S'] };
   if (paramsB <= 35)   return { label: 'inference (30B–34B model)', vram: '40+ GB', gpus: ['A6000', 'L40S', 'A100'] };
   return                      { label: 'inference (70B+ model)',    vram: '80+ GB', gpus: ['H100', 'A100'] };
@@ -84,32 +103,16 @@ function _inferServeProfile(modelName) {
 // Mirror of backend workload_profile.py infer_profile_from_gguf.
 // Accepts the --hf-file filename; looks for param-count hints like "35B" or "8x7B".
 function _inferGgufProfile(ggufPath) {
-  const s = ggufPath.toLowerCase();
-  const moe = s.match(/(\d+)x(\d+)b/);
-  let paramsB;
-  if (moe) {
-    paramsB = parseInt(moe[1]) * parseInt(moe[2]);
-  } else {
-    const m = s.match(/(\d+)b/);
-    paramsB = m ? parseInt(m[1]) : null;
-  }
+  const paramsB = _extractParamsB(ggufPath);
   if (paramsB === null || paramsB <= 9) return { label: 'GGUF inference (≤9B, llama.cpp)',      vram: '8+ GB',  gpus: ['RTX 4090', 'RTX 3090', 'A6000'] };
   if (paramsB <= 35)                   return { label: 'GGUF inference (10B–35B, llama.cpp)',   vram: '24+ GB', gpus: ['RTX 4090', 'A6000', 'L40S'] };
   return                                      { label: 'GGUF inference (36B+, llama.cpp)',      vram: '48+ GB', gpus: ['A6000', 'L40S', 'A100'] };
 }
 
-// Label derived from the backend's real readiness signal (readiness_reason),
-// not a fixed timer — the timer only breaks ties when we have no signal yet.
-function _serveStageLabel(elapsedSec, healthPath, readinessReason) {
-  switch (readinessReason) {
-    case 'port_unreachable': return 'Waiting for container to start…';
-    case 'http_404':         return 'Model loading — waiting for the API to come up…';
-    case 'http_error':       return `Waiting for ${healthPath || 'endpoint'} (non-200 response)…`;
-    default: break;
-  }
-  if (elapsedSec < 30) return 'Starting container…';
-  return `Waiting for ${healthPath || 'endpoint'}…`;
-}
+// If the readiness reason hasn't changed for this long, the status word
+// flips from "starting" to "stuck" so a silent stall never looks identical
+// to normal progress.
+const SERVE_STUCK_THRESHOLD_MS = 90_000;
 
 function _detectHealthPath(image) {
   if (!image) return null;
@@ -129,10 +132,15 @@ function _detectHealthPath(image) {
 // vLLM cold start (model download + load) often exceeds 5 min on first boot.
 const VLLM_SERVE_WAIT_MS = 15 * 60 * 1000;
 
-async function waitForEndpoint(deploymentId, config, timeoutMs = VLLM_SERVE_WAIT_MS, chalk, healthPath = '/models') {
+async function waitForEndpoint(deploymentId, config, timeoutMs = VLLM_SERVE_WAIT_MS, chalk, healthPath = '/models', costCtx = {}) {
+  const { costPerHour = 0, maxCost = null, stageLine = '' } = costCtx;
   const startMs  = Date.now();
   const deadline = startMs + timeoutMs;
 
+  let lastReason     = null;
+  let reasonSinceMs  = startMs;
+  let blockLines     = 0;
+
   while (Date.now() < deadline) {
     try {
       const dep = await callApi(`/deployments/${deploymentId}`, {
@@ -141,24 +149,30 @@ async function waitForEndpoint(deploymentId, config, timeoutMs = VLLM_SERVE_WAIT
         timeoutMs: 10_000,
       });
       if (['failed', 'terminated', 'error', 'stopped'].includes(dep.status)) {
-        process.stdout.write('\n');
+        if (blockLines > 0) { _clearBlock(blockLines); blockLines = 0; }
         return { ready: false, timedOut: false, depFailed: true, failReason: dep.fix_hint || dep.error || dep.status };
       }
       if (dep.endpoint_ready) {
-        process.stdout.write('\n');
+        if (blockLines > 0) { _clearBlock(blockLines); blockLines = 0; }
         return { ready: true, timedOut: false, depFailed: false };
       }
-      const elapsed = Math.round((Date.now() - startMs) / 1000);
-      process.stdout.write(
-        `\r  ${chalk.dim(_serveStageLabel(elapsed, dep.health_path || healthPath, dep.readiness_reason) + ` (${elapsed}s)`)}   `
-      );
+
+      const now     = Date.now();
+      const elapsed = Math.round((now - startMs) / 1000);
+      const reason  = dep.readiness_reason || 'starting';
+      if (reason !== lastReason) { lastReason = reason; reasonSinceMs = now; }
+      const statusWord = (now - reasonSinceMs) >= SERVE_STUCK_THRESHOLD_MS ? 'stuck' : 'still starting';
+      const spend   = costPerHour * (elapsed / 3600);
+
+      blockLines = _writeBlock(blockLines, _renderLiveBlock(chalk, {
+        stageLine, elapsedSec: elapsed, statusWord, spend, id: deploymentId,
+      }));
     } catch {
       // status check failed (transient network/API issue) — retry next tick
     }
     await new Promise(r => setTimeout(r, 8000));
   }
 
-  process.stdout.write('\n');
   return { ready: false, timedOut: true, depFailed: false };
 }
 
@@ -217,13 +231,14 @@ export async function serveCommand(config, args, chalk) {
   }
 
   if (args.includes('--list-aliases')) {
-    console.log(chalk.bold('\n⚡ Blessed vLLM aliases\n'));
-    console.log(chalk.dim('  Use any of these in place of a full model ID: badgr serve <alias>\n'));
-    for (const [alias, spec] of Object.entries(BLESSED_VLLM_MODELS)) {
-      console.log(`  ${chalk.cyan(alias.padEnd(16))}  ${spec.model_id}`);
-      console.log(`  ${''.padEnd(16)}  ${chalk.dim(spec.description)}`);
+    console.log(chalk.bold('\nTested model routes:\n'));
+    for (const alias of Object.keys(BLESSED_VLLM_MODELS)) {
+      console.log(`  - ${chalk.cyan(alias)}`);
     }
     console.log();
+    console.log(chalk.dim('You can also try a Hugging Face model ID:'));
+    console.log(chalk.dim('  badgr serve Qwen/Qwen2.5-7B-Instruct --max-cost 10'));
+    console.log();
     return;
   }
 
@@ -314,50 +329,60 @@ export async function serveCommand(config, args, chalk) {
 
   const effectiveTier = normalizeTier(flags.tier);
 
+  // Header fields + trailing note (shown after Max cost) per serve mode.
+  // Built as [label, value] pairs so every mode renders through one aligned
+  // printer instead of four hand-spaced copies.
+  let title;
+  const headerLines = [];
+  let trailingNote = null;
+  let sizeProfile = null; // { label, vram } — only shown when GPU sizing was inferred, not chosen
+
   if (isLlamaCpp) {
-    console.log(chalk.bold('\n⚡ Serving HF GGUF (llama.cpp)\n'));
-    console.log(`  ${chalk.bold('HF Repo:')}  ${flags.hfRepo}`);
-    console.log(`  ${chalk.bold('HF File:')}  ${flags.hfFile}`);
-    console.log(`  ${chalk.bold('Runtime:')}  llama.cpp`);
-    console.log(`  ${chalk.bold('GPU:')}      ${gpuLabel}`);
-    if (flags.env?.length) console.log(`  ${chalk.bold('Env:')}      ${flags.env.join(', ')}`);
-    if (gpu === 'AUTO') {
-      const prof = _inferGgufProfile(flags.hfFile);
-      console.log();
-      console.log(`  ${chalk.bold('Estimated workload:')}      ${prof.label}`);
-      console.log(`  ${chalk.bold('Estimated minimum VRAM:')}  ${prof.vram}`);
-    }
+    title = flags.hfRepo;
+    headerLines.push(['Route', 'best-effort Hugging Face model']);
+    headerLines.push(['Mode', 'OpenAI-compatible endpoint (llama.cpp)']);
+    headerLines.push(['File', flags.hfFile]);
+    trailingNote = 'Badgr will try a compatible route.';
+    if (gpu === 'AUTO') sizeProfile = _inferGgufProfile(flags.hfFile);
   } else if (customImage) {
-    console.log(chalk.bold('\n⚡ Serving custom container\n'));
-    console.log(`  ${chalk.bold('Image:')}  ${customImage}`);
-    console.log(`  ${chalk.bold('GPU:')}    ${gpuLabel}`);
-    if (flags.task) console.log(`  ${chalk.bold('Task:')}   ${flags.task}`);
-    if (flags.env?.length) console.log(`  ${chalk.bold('Env:')}    ${flags.env.join(', ')}`);
+    title = 'custom container';
+    headerLines.push(['Mode', 'custom server']);
+    trailingNote = 'Badgr manages runtime, logs, caps, teardown, and receipts.\n  Your container owns the app behavior.';
+  } else if (vllmAlias) {
+    title = model;
+    headerLines.push(['Route', 'tested']);
+    headerLines.push(['Mode', 'OpenAI-compatible endpoint']);
   } else {
-    console.log(chalk.bold('\n⚡ Serving model\n'));
-    if (vllmAlias) {
-      console.log(`  ${chalk.bold('Alias:')}  ${model}  ${chalk.dim(`→ ${effectiveModel}`)}`);
-    } else {
-      console.log(`  ${chalk.bold('Model:')}  ${effectiveModel}`);
-    }
-    console.log(`  ${chalk.bold('GPU:')}    ${gpuLabel}`);
-    if (flags.task) console.log(`  ${chalk.bold('Task:')}   ${flags.task}`);
-    if (flags.env?.length) console.log(`  ${chalk.bold('Env:')}    ${flags.env.join(', ')}`);
-
-    if (gpu === 'AUTO') {
-      const prof = _inferServeProfile(effectiveModel);
-      console.log();
-      console.log(`  ${chalk.bold('Estimated workload:')}      ${prof.label}`);
-      console.log(`  ${chalk.bold('Estimated minimum VRAM:')}  ${prof.vram}`);
-    }
+    title = effectiveModel;
+    headerLines.push(['Route', 'best-effort Hugging Face model']);
+    headerLines.push(['Mode', 'OpenAI-compatible endpoint']);
+    trailingNote = 'Badgr will try a compatible route.';
+    if (gpu === 'AUTO') sizeProfile = _inferServeProfile(effectiveModel);
   }
-  if (flags.maxCost) {
-    console.log(`  ${chalk.bold('Max cost:')}    $${flags.maxCost.toFixed(2)} (auto-stop)`);
-  } else {
-    console.log(chalk.yellow(`  ⚠  Persistent — billing until: badgr down <id>  or  badgr down --all`));
+  if (flags.gpu) headerLines.push(['GPU', gpuLabel]);
+  if (flags.task) headerLines.push(['Task', flags.task]);
+  if (flags.env?.length) headerLines.push(['Env', flags.env.join(', ')]);
+
+  console.log(chalk.bold(`\n⚡ Serving ${title}\n`));
+  const labelWidth = Math.max(...headerLines.map(([label]) => label.length)) + 1;
+  for (const [label, value] of headerLines) {
+    console.log(`  ${chalk.bold(`${label}:`.padEnd(labelWidth + 1))}${value}`);
+  }
+  if (sizeProfile) {
+    console.log();
+    console.log(`  ${chalk.bold('Estimated workload:')}      ${sizeProfile.label}`);
+    console.log(`  ${chalk.bold('Estimated minimum VRAM:')}  ${sizeProfile.vram}`);
+  }
+  console.log(`  ${chalk.bold('Max cost:')}    ${flags.maxCost ? `$${flags.maxCost.toFixed(2)}` : chalk.dim('none')}`);
+  console.log(`  ${chalk.bold('Auto-stop:')}   ${flags.maxCost ? 'enabled' : chalk.yellow('disabled — stop manually with badgr down')}`);
+  if (trailingNote) {
+    console.log();
+    console.log(chalk.dim(`  ${trailingNote}`));
   }
   console.log();
-  process.stdout.write(chalk.dim('  Finding suitable capacity...\n'));
+
+  const STAGE_TOTAL = 5;
+  let stageN = 1;
 
   // ── Duplicate check ────────────────────────────────────────────────────────
   if (config.apiKey) {
@@ -469,6 +494,11 @@ export async function serveCommand(config, args, chalk) {
     createdAt:    new Date().toISOString(),
   });
 
+  console.log(chalk.dim(_stageDone(stageN, STAGE_TOTAL, 'Finding a working route...')));
+  stageN++;
+  console.log(chalk.dim(_stageDone(stageN, STAGE_TOTAL, 'Starting runtime...')));
+  stageN++;
+
   // ── Fix 7: never fall back to config.baseUrl for endpoint health check ─────
   const endpointUrl = dep.endpoint_url || dep.openai_base_url;
   if (!endpointUrl) {
@@ -499,18 +529,47 @@ export async function serveCommand(config, args, chalk) {
     resolvedHealthPath = _detectHealthPath(customImage);  // '/system_stats' for comfyui, null otherwise
   }
 
+  // Gated-model guidance is only shown when it's actually needed — on failure —
+  // not up front, so common launches stay short and uncluttered.
+  const gatedModelId = isLlamaCpp ? flags.hfRepo : effectiveModel;
+  const gatedHintNeeded = isLikelyGatedModel(gatedModelId) && !envObjHasHfToken(flags.env);
+
+  // Shared reporting for "deployment failed to start" — hit from both the
+  // pre-poll status check and the waitForEndpoint poll loop below.
+  function reportDeployFailure(failReason) {
+    console.error(formatCliError('HEALTH_CHECK_DEPLOY_FAILED', {
+      deploymentId: dep.deployment_id,
+      failReason,
+    }, chalk));
+    if (gatedHintNeeded) {
+      const rerun = args.join(' ');
+      const retryCmd = rerun.includes('HF_TOKEN=') ? rerun : `${rerun} --env HF_TOKEN=$HF_TOKEN`;
+      console.error();
+      console.error(chalk.yellow('  This model may require Hugging Face access.'));
+      console.error(chalk.dim('  Retry:'));
+      console.error(chalk.dim(`    badgr serve ${retryCmd}`));
+    }
+    updateReceipt(rcptId, { status: 'failed', failReason });
+    process.exitCode = 1;
+  }
+
   // ── Health check ──────────────────────────────────────────────────────────
+  const loadingStageN = stageN;      // "Loading model..."
+  const healthStageN  = stageN + 1;  // "Checking endpoint health..."
+  const readyStageN   = stageN + 2;  // "Ready"
+
   let endpointReady = false;
   if (flags.noWait) {
-    console.log(chalk.yellow('\n  Skipped health check (--no-wait)\n'));
+    console.log(chalk.dim(_stage(loadingStageN, STAGE_TOTAL, 'Loading model...')) + chalk.yellow('  (skipped — --no-wait)'));
+    console.log(chalk.dim(_stage(healthStageN, STAGE_TOTAL, 'Checking endpoint health...')) + chalk.yellow('  (skipped — --no-wait)'));
+    console.log(chalk.yellow(_stage(readyStageN, STAGE_TOTAL, 'Not confirmed ready — check badgr logs') + `\n`));
   } else if (resolvedHealthPath === null) {
+    console.log(chalk.dim(_stage(loadingStageN, STAGE_TOTAL, 'Loading model...')));
     console.log(chalk.yellow(
-      '\n  Skipping health check (custom image — add --health-path /your-readiness-path to enable)\n'
+      _stage(healthStageN, STAGE_TOTAL, 'Checking endpoint health...') +
+      '  (skipped — custom image; add --health-path /your-readiness-path to enable)\n'
     ));
   } else {
-    if (resolvedHealthPath !== '/models') {
-      process.stdout.write(chalk.dim(`  Checking ${resolvedHealthPath} for readiness…\n`));
-    }
     // Check deployment status once before starting the 5-min wait
     try {
       const latest = await callApi(`/deployments/${dep.deployment_id}`, {
@@ -519,33 +578,31 @@ export async function serveCommand(config, args, chalk) {
         timeoutMs: 10_000,
       });
       if (['failed', 'terminated', 'error'].includes(latest.status)) {
-        console.error(formatCliError('HEALTH_CHECK_DEPLOY_FAILED', {
-          deploymentId: dep.deployment_id,
-          failReason:   latest.error || latest.status,
-        }, chalk));
-        updateReceipt(rcptId, { status: 'failed', failReason: latest.error || latest.status });
-        process.exitCode = 1;
+        reportDeployFailure(latest.error || latest.status);
         return;
       }
     } catch {
       // status check failed — proceed with endpoint poll anyway
     }
 
-    const healthResult = await waitForEndpoint(dep.deployment_id, config, VLLM_SERVE_WAIT_MS, chalk, resolvedHealthPath);
-    process.stdout.write('\n');
+    const loadingStageLine = _stage(loadingStageN, STAGE_TOTAL, 'Loading model...');
+    const healthResult = await waitForEndpoint(
+      dep.deployment_id, config, VLLM_SERVE_WAIT_MS, chalk, resolvedHealthPath,
+      { costPerHour: dep.cost_per_hour || 0, maxCost: flags.maxCost || null, stageLine: loadingStageLine },
+    );
 
     if (healthResult.depFailed) {
-      console.error(formatCliError('HEALTH_CHECK_DEPLOY_FAILED', {
-        deploymentId: dep.deployment_id,
-        failReason:   healthResult.failReason,
-      }, chalk));
-      updateReceipt(rcptId, { status: 'failed', failReason: healthResult.failReason });
-      process.exitCode = 1;
+      reportDeployFailure(healthResult.failReason);
       return;
     }
 
     endpointReady = healthResult.ready;
-    if (!endpointReady) updateReceipt(rcptId, { status: 'health_check_timeout' });
+    if (endpointReady) {
+      console.log(chalk.dim(_stage(healthStageN, STAGE_TOTAL, 'Checking endpoint health...')));
+      console.log(chalk.green(_stage(readyStageN, STAGE_TOTAL, 'Ready')));
+    } else {
+      updateReceipt(rcptId, { status: 'health_check_timeout' });
+    }
   }
 
   // ── Custom-node validation (ComfyUI) ─────────────────────────────────────
@@ -570,8 +627,6 @@ export async function serveCommand(config, args, chalk) {
     console.log();
   }
 
-  const serveRate = dep.cost_per_hour || 0;
-
   console.log(`  ${chalk.bold('Base URL:')}     ${chalk.cyan(endpointUrl)}`);
   if (isLlamaCpp) {
     console.log(`  ${chalk.bold('HF Repo:')}      ${flags.hfRepo}`);
@@ -579,23 +634,20 @@ export async function serveCommand(config, args, chalk) {
   }
   else if (dep.model || effectiveModel) console.log(`  ${chalk.bold('Model:')}        ${dep.model || effectiveModel}`);
   if (customImage)        console.log(`  ${chalk.bold('Image:')}        ${customImage}`);
-  console.log(`  ${chalk.bold('GPU:')}          ${dep.gpu_type} × ${dep.gpu_count}`);
-  if (serveRate > 0) console.log(`  ${chalk.bold('Rate:')}         $${serveRate.toFixed(2)}/hr`);
   if (flags.maxCost) console.log(`  ${chalk.bold('Max cost:')}     $${flags.maxCost.toFixed(2)}`);
-  console.log(`  ${chalk.bold('Receipt:')}      ${chalk.dim(rcptId)}`);
-  console.log(`  ${chalk.bold('Logs:')}         ${chalk.dim(`badgr logs ${dep.deployment_id}`)}`);
+  console.log(`  ${chalk.bold('Logs:')}         badgr logs ${dep.deployment_id}`);
   console.log(`  ${chalk.bold('Stop billing:')} ${chalk.cyan(`badgr down ${dep.deployment_id}`)}`);
+  console.log(`  ${chalk.bold('Receipt:')}      badgr receipts ${rcptId}`);
   console.log();
-
-  if (serveRate > HIGH_RATE_THRESHOLD && !flags.maxCost) {
-    console.log(chalk.yellow(`  Selected capacity rate: $${serveRate.toFixed(2)}/hr`));
-    console.log(chalk.dim('  Tip: use --max-cost to enforce a hard ceiling.\n'));
-  }
   console.log(chalk.dim('  Billing continues until you run: ') + chalk.cyan(`badgr down ${dep.deployment_id}`));
 
   if (endpointReady && !customImage) {
     const keySnip = config.apiKey?.slice(0, 4) || 'sk-...';
     const sdkModel = isLlamaCpp ? 'default' : (dep.model || effectiveModel);
+    console.log(`  ${chalk.bold('Test with curl:')}`);
+    console.log(chalk.dim(`    curl ${endpointUrl}/chat/completions \\`));
+    console.log(chalk.dim(`      -H "Authorization: Bearer ${keySnip}..." -H "Content-Type: application/json" \\`));
+    console.log(chalk.dim(`      -d '{"model":"${sdkModel}","messages":[{"role":"user","content":"Hello"}]}'`));
     console.log(`  ${chalk.bold('Use with OpenAI SDK:')}`);
     console.log(chalk.dim(`    from openai import OpenAI`));
     console.log(chalk.dim(`    client = OpenAI(base_url="${endpointUrl}", api_key="${keySnip}...")`));

package/src/progress.js

@@ -0,0 +1,42 @@
+// Shared staged-progress rendering used by `badgr serve` and `badgr run` —
+// numbered stage lines plus an in-place-redrawing status block, so neither
+// command spams repeated identical loading lines.
+
+export function stage(n, total, label) {
+  return `  [${n}/${total}] ${label}`;
+}
+
+export function stageDone(n, total, label) {
+  return `  [${n}/${total}] ${label} done`;
+}
+
+// Redraws a fixed-height status block in place instead of appending new
+// lines each tick — satisfies "no repeated identical loading lines" while
+// still showing live elapsed time. Returns the new line count to pass back
+// in as prevLineCount on the next call.
+export function writeBlock(prevLineCount, lines) {
+  if (prevLineCount > 0) process.stdout.write(`\x1b[${prevLineCount}A`);
+  for (const line of lines) process.stdout.write('\x1b[2K' + line + '\n');
+  return lines.length;
+}
+
+export function clearBlock(lineCount) {
+  if (lineCount <= 0) return;
+  process.stdout.write(`\x1b[${lineCount}A`);
+  for (let i = 0; i < lineCount; i++) process.stdout.write('\x1b[2K\n');
+  process.stdout.write(`\x1b[${lineCount}A`);
+}
+
+// The live block shown while a stage is in progress — same shape for both
+// `badgr serve` (deployment) and `badgr run` (job): elapsed time, a status
+// word, an *estimated* spend (never presented as confirmed while billing is
+// still live), and the exact commands to inspect logs or stop billing.
+export function renderLiveBlock(chalk, { stageLine, elapsedSec, statusWord, spend, id }) {
+  return [
+    chalk.dim(`${stageLine} ${elapsedSec}s elapsed`),
+    chalk.dim(`        Status: ${statusWord}`),
+    chalk.dim(`        Estimated spend: ~$${spend.toFixed(2)}`),
+    chalk.dim(`        Logs: badgr logs ${id}`),
+    chalk.dim(`        Stop billing: badgr down ${id}`),
+  ];
+}

package/tests/serve-lifecycle.test.js

@@ -510,13 +510,106 @@ describe('input validation for serve', () => {
 // ─────────────────────────────────────────────────────────────────────────────
 
 describe('--list-aliases', () => {
-  it('prints blessed aliases without requiring a model or API call', async () => {
+  it('prints tested model routes without requiring a model or API call', async () => {
     await serveCommand({ apiKey: null, baseUrl: 'https://api.test/v1' }, ['--list-aliases'], chalk);
     expect(api.callApi).not.toHaveBeenCalled();
     expect(process.exitCode).toBeFalsy();
     const logged = console.log.mock.calls.flat().join('\n');
+    expect(logged).toContain('Tested model routes:');
     expect(logged).toContain('qwen-7b');
-    expect(logged).toContain('Qwen/Qwen2.5-7B-Instruct');
+    expect(logged).toContain('You can also try a Hugging Face model ID:');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Model support-level messaging — blessed route vs best-effort HF model vs
+// custom container, plus gated-model HF_TOKEN guidance shown only on failure.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('model support-level messaging', () => {
+  it('labels a full Hugging Face model ID as best-effort, not tested', async () => {
+    api.callApi
+      .mockResolvedValueOnce(makeServeDep({ model: 'Qwen/Qwen2.5-7B-Instruct' }))
+      .mockResolvedValueOnce({ status: 'running' })
+      .mockResolvedValueOnce(readyStatus());
+
+    const p = serveCommand(config, ['Qwen/Qwen2.5-7B-Instruct', '--max-cost', '10'], chalk);
+    await vi.advanceTimersByTimeAsync(5000);
+    await p;
+
+    const logged = console.log.mock.calls.flat().join('\n');
+    expect(logged).toContain('Route: best-effort Hugging Face model');
+    expect(logged).not.toContain('Route: tested');
+  });
+
+  it('labels a blessed alias as a tested route without extra caveats', async () => {
+    api.callApi
+      .mockResolvedValueOnce(makeServeDep({ model: 'Qwen/Qwen2.5-7B-Instruct' }))
+      .mockResolvedValueOnce({ status: 'running' })
+      .mockResolvedValueOnce(readyStatus());
+
+    const p = serveCommand(config, ['qwen-7b', '--max-cost', '10'], chalk);
+    await vi.advanceTimersByTimeAsync(5000);
+    await p;
+
+    const logged = console.log.mock.calls.flat().join('\n');
+    expect(logged).toContain('Route: tested');
+    expect(logged).not.toContain('best-effort');
+  });
+
+  it('does not show HF_TOKEN guidance up front for a gated model that launches fine', async () => {
+    api.callApi
+      .mockResolvedValueOnce(makeServeDep({ model: 'meta-llama/Llama-3.1-8B-Instruct' }))
+      .mockResolvedValueOnce({ status: 'running' })
+      .mockResolvedValueOnce(readyStatus());
+
+    const p = serveCommand(config, ['meta-llama/Llama-3.1-8B-Instruct', '--max-cost', '10'], chalk);
+    await vi.advanceTimersByTimeAsync(5000);
+    await p;
+
+    const logged = console.log.mock.calls.flat().join('\n');
+    expect(logged).not.toContain('may require Hugging Face access');
+  });
+
+  it('shows HF_TOKEN guidance only once a gated model actually fails to start', async () => {
+    api.callApi
+      .mockResolvedValueOnce(makeServeDep({ model: 'meta-llama/Llama-3.1-8B-Instruct' }))
+      .mockResolvedValueOnce({ status: 'failed', error: 'gated repo — 401' });
+
+    const p = serveCommand(config, ['meta-llama/Llama-3.1-8B-Instruct', '--max-cost', '10'], chalk);
+    await p;
+
+    const logged = console.error.mock.calls.flat().join('\n');
+    expect(logged).toContain('may require Hugging Face access');
+    expect(logged).toContain('--env HF_TOKEN=$HF_TOKEN');
+    expect(process.exitCode).toBe(1);
+  });
+
+  it('omits HF_TOKEN guidance on failure when HF_TOKEN is already provided', async () => {
+    api.callApi
+      .mockResolvedValueOnce(makeServeDep({ model: 'meta-llama/Llama-3.1-8B-Instruct' }))
+      .mockResolvedValueOnce({ status: 'failed', error: 'crashed' });
+
+    const p = serveCommand(config, [
+      'meta-llama/Llama-3.1-8B-Instruct', '--max-cost', '10', '--env', 'HF_TOKEN=hf_abc123',
+    ], chalk);
+    await p;
+
+    const logged = console.error.mock.calls.flat().join('\n');
+    expect(logged).not.toContain('may require Hugging Face access');
+  });
+
+  it('labels a custom container as "custom server", not a Hugging Face model', async () => {
+    api.callApi.mockResolvedValueOnce(makeServeDep({ model: undefined, image: 'my/custom-server:latest' }));
+
+    const p = serveCommand(config, [
+      '--image', 'my/custom-server:latest', '--max-cost', '10', '--no-wait',
+    ], chalk);
+    await p;
+
+    const logged = console.log.mock.calls.flat().join('\n');
+    expect(logged).toContain('custom server');
+    expect(logged).toContain('Your container owns the app behavior.');
   });
 });