badgr-cli 1.0.48 → 1.1.0

package/src/gpuDoctor/logClassifier.js

@@ -0,0 +1,138 @@
+// Classifies vLLM / GPU workload log text into a likely failure category.
+// Read-only: takes a string, returns a classification. Never touches the log file's source process.
+
+import { redactLine } from './redact.js';
+
+const RULES = [
+  {
+    category: 'vram_oom',
+    label: 'VRAM / model fit',
+    patterns: [/CUDA out of memory/i, /torch\.cuda\.OutOfMemoryError/i, /CUDA error: out of memory/i, /OutOfMemoryError/i],
+    fixes: [
+      'Lower --max-model-len (context length)',
+      'Reduce concurrency / batch size',
+      'Lower --gpu-memory-utilization',
+      'Use quantized weights (AWQ/GPTQ/FP8/4bit)',
+      'Use a larger GPU',
+    ],
+  },
+  {
+    category: 'nccl_distributed',
+    label: 'NCCL / distributed setup',
+    patterns: [/NCCL (timeout|error|WARN)/i, /Timeout.*(NCCL|process group)/i, /torch\.distributed.*timeout/i, /Watchdog caught collective operation timeout/i],
+    fixes: [
+      'Check NCCL_SOCKET_IFNAME / network interface configuration',
+      'Verify all GPUs/nodes can reach each other',
+      'Reduce tensor-parallel or pipeline-parallel size',
+      'Increase the NCCL timeout',
+    ],
+  },
+  {
+    category: 'cuda_pytorch_mismatch',
+    label: 'CUDA / PyTorch mismatch',
+    patterns: [/CUDA error: no kernel image/i, /CUDA driver version is insufficient/i, /Torch not compiled with CUDA/i, /illegal memory access/i, /CUDA error:/i, /CUDA initialization error/i],
+    fixes: [
+      'Verify torch was installed with a CUDA build matching the driver',
+      'Match the container CUDA image to the host driver version',
+      'Reinstall torch for the correct CUDA runtime',
+    ],
+  },
+  {
+    category: 'missing_model',
+    label: 'Missing model / weights',
+    patterns: [/Repository Not Found/i, /404 Client Error/i, /model.*not found/i, /No such file or directory.*\.(safetensors|bin|gguf|ckpt)/i, /is not a local folder and is not a valid model identifier/i],
+    fixes: [
+      'Verify the model repo ID or local path',
+      'Check the Hugging Face token / access for gated models',
+      'Confirm the weights finished downloading',
+    ],
+  },
+  {
+    category: 'missing_dependency',
+    label: 'Missing dependency',
+    patterns: [/ModuleNotFoundError/i, /ImportError/i, /No module named/i],
+    fixes: [
+      'Install the missing Python package',
+      'Verify the image/environment includes all required dependencies',
+    ],
+  },
+  {
+    category: 'health_check',
+    label: 'Health check / endpoint readiness',
+    patterns: [/health check failed/i, /readiness probe failed/i, /connection refused/i, /port .*not responding/i, /address already in use/i],
+    fixes: [
+      'Give the server more time to start (model load can take minutes)',
+      'Verify the port is exposed',
+      'Check the logs for a crash during startup',
+    ],
+  },
+  {
+    category: 'provider_pod_issue',
+    label: 'Provider / pod issue',
+    patterns: [/pod (terminated|preempted|evicted)/i, /instance (reclaimed|terminated|preempted)/i, /spot instance.*(reclaimed|terminated)/i],
+    fixes: [
+      'Retry on a non-spot / on-demand instance',
+      'Check the provider status page',
+      'Try `badgr serve` for managed provisioning with automatic failover',
+    ],
+  },
+  {
+    category: 'disk_cache',
+    label: 'Disk / cache',
+    patterns: [/No space left on device/i, /disk quota exceeded/i, /ENOSPC/],
+    fixes: [
+      'Free up disk space',
+      'Point HF_HOME to a larger volume',
+      'Clear the Hugging Face cache',
+    ],
+  },
+];
+
+// Secondary signals that corroborate a failure but aren't a category on their own.
+const ENGINE_SIGNALS = [/EngineDeadError/i, /worker died/i, /model failed to load/i];
+
+function extractLine(text, pattern) {
+  const line = text.split(/\r?\n/).find((l) => pattern.test(l));
+  return line ? redactLine(line.trim().slice(0, 200)) : null;
+}
+
+/**
+ * Classify log text into one of: vram_oom, cuda_pytorch_mismatch, missing_model,
+ * missing_dependency, nccl_distributed, health_check, provider_pod_issue,
+ * disk_cache, unknown.
+ */
+export function classifyLog(text) {
+  const matches = [];
+  for (const rule of RULES) {
+    const hitPattern = rule.patterns.find((p) => p.test(text));
+    if (hitPattern) {
+      matches.push({ category: rule.category, label: rule.label, fixes: rule.fixes, evidenceLine: extractLine(text, hitPattern) });
+    }
+  }
+
+  const engineEvidence = ENGINE_SIGNALS.map((p) => extractLine(text, p)).filter(Boolean);
+
+  if (matches.length === 0) {
+    return {
+      matched: false,
+      category: 'unknown',
+      label: 'Unknown failure',
+      fixes: ['Share the last 50 lines of the log for a closer look', 'Search the error text directly'],
+      evidenceLines: engineEvidence,
+      allCategories: [],
+    };
+  }
+
+  // VRAM/OOM is the most actionable, common failure — prefer it when present.
+  const primary = matches.find((m) => m.category === 'vram_oom') || matches[0];
+  const evidenceLines = [...new Set([primary.evidenceLine, ...engineEvidence].filter(Boolean))];
+
+  return {
+    matched: true,
+    category: primary.category,
+    label: primary.label,
+    fixes: primary.fixes,
+    evidenceLines,
+    allCategories: [...new Set(matches.map((m) => m.category))],
+  };
+}

package/src/gpuDoctor/modelFit.js

@@ -0,0 +1,107 @@
+// Simple known-model/size heuristics — not perfect introspection.
+// All numbers here are estimates; callers should present them as
+// "likely" / "estimated" / "recommended", never as guarantees.
+
+const BYTES_PER_PARAM = {
+  fp16: 2,
+  bf16: 2,
+  fp8: 1,
+  awq: 0.6,
+  gptq: 0.6,
+  '4bit': 0.55,
+  gguf: 0.6,
+};
+
+export function estimateModelParamsB(model) {
+  const m = String(model).match(/(\d+(?:\.\d+)?)\s*[bB](?:[-_]|$)/);
+  return m ? Number(m[1]) : null;
+}
+
+export function detectQuantization(model) {
+  const s = String(model);
+  if (/awq/i.test(s)) return 'awq';
+  if (/gptq/i.test(s)) return 'gptq';
+  if (/fp8/i.test(s)) return 'fp8';
+  if (/gguf/i.test(s)) return 'gguf';
+  if (/(^|[-_./])4bit|int4|[-_]q4/i.test(s)) return '4bit';
+  return null;
+}
+
+export function sizeClassLabel(paramsB) {
+  if (paramsB == null) return 'unknown';
+  if (paramsB >= 65) return '70B-class';
+  if (paramsB >= 28) return '32B-class';
+  if (paramsB >= 13) return '14B-class';
+  if (paramsB >= 7.5) return '8B-class';
+  if (paramsB >= 5) return '7B-class';
+  return `${paramsB}B-class`;
+}
+
+export function recommendedGpuClassForVram(vramGb) {
+  if (vramGb == null) return 'unknown — could not estimate required VRAM';
+  if (vramGb <= 16) return '16GB+ class (e.g. RTX 4080, L4)';
+  if (vramGb <= 24) return '24GB+ class (e.g. RTX 4090, RTX 3090)';
+  if (vramGb <= 48) return '48GB class (e.g. L40S, A6000)';
+  if (vramGb <= 80) return '80GB class (e.g. A100 80GB, H100)';
+  return '80GB+ class or multi-GPU tensor-parallel route';
+}
+
+/**
+ * Rough VRAM range estimate for a model label. Not exact — parameter count
+ * is inferred from the name, weights are sized by quantization, and a
+ * generous KV-cache/runtime overhead is layered on top.
+ *
+ * `gpuCount` models a tensor-parallel split across N GPUs: weights are
+ * assumed to shard evenly, while the KV-cache/context overhead is charged
+ * per GPU (every rank still needs its own activation/KV headroom). Returns
+ * both the per-GPU figures (what a single card in the group needs — use
+ * this to compare against one GPU's free VRAM) and the total across all
+ * GPUs (for reporting the whole group's footprint).
+ */
+export function estimateModelFit(model, { contextLen = 8192, gpuCount = 1 } = {}) {
+  const paramsB = estimateModelParamsB(model);
+  const quant = detectQuantization(model);
+  const bytesPerParam = quant ? BYTES_PER_PARAM[quant] : BYTES_PER_PARAM.fp16;
+  const safeGpuCount = Math.max(1, Math.round(gpuCount) || 1);
+
+  if (paramsB == null) {
+    return {
+      paramsB: null,
+      quant,
+      sizeClass: 'unknown',
+      gpuCount: safeGpuCount,
+      vramMinGb: null,
+      vramMaxGb: null,
+      perGpuVramMinGb: null,
+      perGpuVramMaxGb: null,
+      recommendedGpuClass: recommendedGpuClassForVram(null),
+      quantSuggestion: 'could not infer parameter count from the model name — pass --vram-gb to size it manually',
+    };
+  }
+
+  const weightsGb = paramsB * bytesPerParam;
+  const contextOverheadGb = (contextLen / 8192) * 1.5;
+  const vramMinGb = Math.ceil(weightsGb * 1.15);
+  const vramMaxGb = Math.ceil(weightsGb * 1.45 + contextOverheadGb);
+  const perGpuVramMinGb = Math.ceil(weightsGb * 1.15 / safeGpuCount);
+  const perGpuVramMaxGb = Math.ceil((weightsGb * 1.45) / safeGpuCount + contextOverheadGb);
+
+  const quantSuggestion = quant
+    ? `already quantized (${quant})`
+    : perGpuVramMaxGb > 24
+      ? 'quantized weights (AWQ/GPTQ/FP8/4bit) would reduce the footprint'
+      : 'quantization optional at this size';
+
+  return {
+    paramsB,
+    quant,
+    sizeClass: sizeClassLabel(paramsB),
+    gpuCount: safeGpuCount,
+    vramMinGb,
+    vramMaxGb,
+    perGpuVramMinGb,
+    perGpuVramMaxGb,
+    recommendedGpuClass: recommendedGpuClassForVram(perGpuVramMaxGb),
+    quantSuggestion,
+  };
+}

package/src/gpuDoctor/probeCache.js

@@ -0,0 +1,38 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+// Short-lived, best-effort cache for the expensive nvidia-smi / python-torch
+// probes so repeated `badgr doctor` runs (e.g. while iterating on a fix)
+// don't re-pay a multi-second `python -c "import torch"` cost every time.
+// Never required for correctness: any read/write failure degrades silently
+// to "just run the probe again".
+
+const DEFAULT_CACHE_PATH = path.join(os.tmpdir(), 'badgr-doctor-probe-cache.json');
+const DEFAULT_TTL_MS = 10_000;
+
+export function readProbeCache(key, { ttlMs = DEFAULT_TTL_MS, cachePath = DEFAULT_CACHE_PATH, fsImpl = fs } = {}) {
+  try {
+    const store = JSON.parse(fsImpl.readFileSync(cachePath, 'utf8'));
+    const entry = store[key];
+    if (entry && Date.now() - entry.ts < ttlMs) return entry.value;
+  } catch {
+    // no cache file yet, corrupt contents, or unreadable — treat as a miss
+  }
+  return undefined;
+}
+
+export function writeProbeCache(key, value, { cachePath = DEFAULT_CACHE_PATH, fsImpl = fs } = {}) {
+  let store = {};
+  try {
+    store = JSON.parse(fsImpl.readFileSync(cachePath, 'utf8'));
+  } catch {
+    // start a fresh store
+  }
+  store[key] = { ts: Date.now(), value };
+  try {
+    fsImpl.writeFileSync(cachePath, JSON.stringify(store));
+  } catch {
+    // best-effort — a failed cache write must never break a diagnosis
+  }
+}

package/src/gpuDoctor/redact.js

@@ -0,0 +1,29 @@
+// Best-effort redaction for evidence lines pulled from user logs/URLs before
+// they're echoed back in the report. Not a guarantee — callers should still
+// avoid piping untrusted logs to shared output — but it strips the common
+// cases: API tokens, Authorization headers, credentials embedded in URLs,
+// home directory usernames, and email addresses.
+
+const PATTERNS = [
+  [/\bhf_[A-Za-z0-9]{10,}\b/g, 'hf_[REDACTED]'],
+  [/\bsk-[A-Za-z0-9]{10,}\b/g, 'sk-[REDACTED]'],
+  [/\bghp_[A-Za-z0-9]{10,}\b/g, 'ghp_[REDACTED]'],
+  [/\bAKIA[0-9A-Z]{12,}\b/g, 'AKIA[REDACTED]'],
+  [/Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi, 'Bearer [REDACTED]'],
+  [/(Authorization:\s*)\S+/gi, '$1[REDACTED]'],
+  [/(api[_-]?key["'=:\s]+)[A-Za-z0-9\-._]{8,}/gi, '$1[REDACTED]'],
+  [/(token["'=:\s]+)[A-Za-z0-9\-._]{8,}/gi, '$1[REDACTED]'],
+  [/(password["'=:\s]+)\S+/gi, '$1[REDACTED]'],
+  [/:\/\/([^:@/\s]+):([^:@/\s]+)@/g, '://[REDACTED]:[REDACTED]@'],
+  [/\/(home|Users)\/([^/\s]+)/g, '/$1/[user]'],
+  [/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '[email]'],
+];
+
+export function redactLine(line) {
+  if (typeof line !== 'string' || !line) return line;
+  let out = line;
+  for (const [pattern, replacement] of PATTERNS) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}

package/src/gpuDoctor/torchInfo.js

@@ -0,0 +1,61 @@
+import { execFileSync } from 'child_process';
+
+// Read-only probe script: imports torch (if present) and reports what it sees.
+// Never writes, downloads, or mutates anything.
+const PROBE = `
+import json
+result = {"torchInstalled": False, "cudaAvailable": False, "cudaVersion": None, "deviceName": None, "deviceCount": 0, "freeVramGb": None, "totalVramGb": None, "error": None}
+try:
+    import torch
+    result["torchInstalled"] = True
+    result["cudaAvailable"] = bool(torch.cuda.is_available())
+    result["cudaVersion"] = torch.version.cuda
+    if result["cudaAvailable"]:
+        result["deviceCount"] = torch.cuda.device_count()
+        if result["deviceCount"] > 0:
+            result["deviceName"] = torch.cuda.get_device_name(0)
+            try:
+                free_b, total_b = torch.cuda.mem_get_info(0)
+                result["freeVramGb"] = round(free_b / (1024 ** 3), 1)
+                result["totalVramGb"] = round(total_b / (1024 ** 3), 1)
+            except Exception:
+                pass
+except Exception as e:
+    result["error"] = str(e)
+print(json.dumps(result))
+`;
+
+/**
+ * Read-only python/torch probe. Never installs or downloads anything.
+ */
+export function detectTorch(execImpl = execFileSync) {
+  let pythonAvailable = false;
+  for (const bin of ['python3', 'python']) {
+    let out;
+    try {
+      out = execImpl(bin, ['-c', PROBE], { encoding: 'utf8', timeout: 15000 });
+    } catch (err) {
+      if (err && err.code === 'ENOENT') continue;
+      pythonAvailable = true;
+      continue;
+    }
+    pythonAvailable = true;
+    try {
+      const lastLine = out.trim().split(/\r?\n/).pop();
+      const parsed = JSON.parse(lastLine);
+      return { pythonAvailable: true, pythonBinary: bin, ...parsed };
+    } catch {
+      continue;
+    }
+  }
+  return {
+    pythonAvailable,
+    pythonBinary: null,
+    torchInstalled: false,
+    cudaAvailable: false,
+    cudaVersion: null,
+    deviceName: null,
+    deviceCount: 0,
+    error: pythonAvailable ? 'could not read torch probe output' : 'python not found',
+  };
+}

package/src/gpuDoctor/workflowDoctor.js

@@ -0,0 +1,96 @@
+// Parses a ComfyUI workflow JSON (API-export or UI-export format) just
+// enough to surface model references, non-core custom nodes, and a rough
+// workload class / VRAM bucket. Read-only — never touches the Comfy install.
+
+const KNOWN_BASE_CLASSES = new Set([
+  'CheckpointLoaderSimple', 'CheckpointLoader', 'CLIPTextEncode', 'KSampler', 'KSamplerAdvanced',
+  'VAEDecode', 'VAEEncode', 'EmptyLatentImage', 'SaveImage', 'LoadImage', 'LoraLoader',
+  'LoraLoaderModelOnly', 'ControlNetLoader', 'ControlNetApply', 'ControlNetApplyAdvanced',
+  'UpscaleModelLoader', 'ImageUpscaleWithModel', 'VAELoader', 'CLIPLoader', 'DualCLIPLoader',
+  'UNETLoader', 'ConditioningCombine', 'ConditioningZeroOut', 'ImageScale', 'PreviewImage',
+  'LatentUpscale', 'CLIPSetLastLayer', 'CLIPVisionLoader', 'CLIPVisionEncode', 'StyleModelLoader',
+  'GLIGENLoader', 'DiffControlNetLoader', 'ImagePadForOutpaint', 'LatentComposite', 'LatentBlend',
+  'Note', 'Reroute', 'PrimitiveNode',
+]);
+
+const MODEL_FIELD_KEYS = ['ckpt_name', 'vae_name', 'lora_name', 'unet_name', 'clip_name', 'control_net_name', 'model_name', 'style_model_name'];
+const MODEL_FILE_PATTERN = /\.(safetensors|ckpt|pt|bin|gguf|pth)$/i;
+
+function iterNodes(workflow) {
+  if (Array.isArray(workflow?.nodes)) {
+    // UI-export format: { nodes: [{ type, widgets_values }], ... }
+    return workflow.nodes.map((n) => ({ classType: n.type, inputs: n.widgets_values }));
+  }
+  if (workflow && typeof workflow === 'object') {
+    // API-export format: { "1": { class_type, inputs }, "2": {...}, ... }
+    return Object.values(workflow)
+      .filter((n) => n && typeof n === 'object' && n.class_type)
+      .map((n) => ({ classType: n.class_type, inputs: n.inputs }));
+  }
+  return [];
+}
+
+export function parseWorkflowFile(raw) {
+  return JSON.parse(raw);
+}
+
+/**
+ * Best-effort ComfyUI workflow diagnosis. Not a full parser or node
+ * validator — just enough signal to name a likely workload class and
+ * flag anything that might be a missing model or custom node.
+ */
+export function diagnoseWorkflow(workflow) {
+  const nodes = iterNodes(workflow);
+  const models = new Set();
+  const customNodes = new Set();
+  const classTypes = new Set();
+
+  for (const node of nodes) {
+    if (!node.classType) continue;
+    classTypes.add(node.classType);
+    if (!KNOWN_BASE_CLASSES.has(node.classType)) customNodes.add(node.classType);
+
+    if (node.inputs && typeof node.inputs === 'object' && !Array.isArray(node.inputs)) {
+      for (const key of MODEL_FIELD_KEYS) {
+        const val = node.inputs[key];
+        if (typeof val === 'string' && val.trim()) models.add(val.trim());
+      }
+    } else if (Array.isArray(node.inputs)) {
+      for (const val of node.inputs) {
+        if (typeof val === 'string' && MODEL_FILE_PATTERN.test(val)) models.add(val.trim());
+      }
+    }
+  }
+
+  const signalText = [...models, ...classTypes].join(' ').toLowerCase();
+  let likelyClass = 'unknown';
+  let vramBucket = '8–12GB+ (rough estimate)';
+
+  if (/flux/.test(signalText)) {
+    likelyClass = 'Flux';
+    vramBucket = '24GB+ (Flux dev/schnell)';
+  } else if (/hunyuan/.test(signalText)) {
+    likelyClass = 'Hunyuan Video';
+    vramBucket = '24–48GB+ (video)';
+  } else if (/\b(wan2?|ltx|svd|animatediff)\b/.test(signalText) || /video/.test(signalText)) {
+    likelyClass = 'video workflow';
+    vramBucket = '16–24GB+ (video)';
+  } else if (/xl|sdxl/.test(signalText)) {
+    likelyClass = 'SDXL';
+    vramBucket = '12–16GB+';
+  } else if (/sd[-_]?(1\.5|15)|v1-5/.test(signalText)) {
+    likelyClass = 'SD 1.5';
+    vramBucket = '6–8GB+';
+  } else if (nodes.length === 0) {
+    likelyClass = 'unrecognized (no nodes parsed)';
+    vramBucket = 'unknown';
+  }
+
+  return {
+    nodeCount: nodes.length,
+    likelyClass,
+    vramBucket,
+    models: [...models],
+    customNodes: [...customNodes],
+  };
+}

package/src/onboarding.js

@@ -0,0 +1,124 @@
+import { callApi } from './api.js';
+import { saveConfig, requireApiKey } from './config.js';
+import { openBrowser } from './browser.js';
+
+/**
+ * Just-in-time login + funding — the first meaningful action a new user
+ * takes should be `badgr launch ...` (or `badgr comfyui`/`badgr serve`/etc.),
+ * not a separate `badgr login`/`badgr billing add` onboarding ritual.
+ *
+ * `ensureBadgrReady(config, chalk)` is the shared pre-flight check every
+ * provisioning command should call before uploading anything or hitting the
+ * API: if not logged in, it opens a browser to a one-time login link and
+ * polls until the CLI is authorized; if logged in with a $0 balance, it
+ * opens the billing checkout and polls until funded. Returns the (possibly
+ * updated) config to use for the rest of the command.
+ *
+ * Non-interactive environments (CI, no TTY) skip straight to the old
+ * hard-fail behavior (`requireApiKey`) instead of opening a browser that
+ * will never be clicked — there is no useful "wait for a human" story there.
+ */
+
+const POLL_INTERVAL_MS = 2000;
+const SESSION_POLL_TIMEOUT_MS = 10 * 60 * 1000; // matches the backend session TTL
+const BILLING_POLL_TIMEOUT_MS = 10 * 60 * 1000;
+const BILLING_URL = 'https://aibadgr.com/dashboard#billing';
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function apiBase(config) {
+  return config.baseUrl.replace(/\/v1\/?$/, '').replace(/\/api\/v1\/?$/, '');
+}
+
+async function pollCliSession(config, sessionId) {
+  const start = Date.now();
+  while (Date.now() - start < SESSION_POLL_TIMEOUT_MS) {
+    await sleep(POLL_INTERVAL_MS);
+    let status;
+    try {
+      status = await callApi(`/cli/session/${sessionId}`, { apiKey: '', baseUrl: config.baseUrl });
+    } catch {
+      continue; // transient network hiccup — keep polling until the timeout
+    }
+    if (status.status === 'complete') return status;
+    if (status.status === 'expired') {
+      throw new Error('Login link expired before it was completed. Run `badgr launch ...` again, or `badgr login` directly.');
+    }
+  }
+  throw new Error('Timed out waiting for login in the browser. Run `badgr login` directly.');
+}
+
+async function ensureLoggedIn(config, chalk) {
+  console.log(chalk.dim("\n  You're not logged in to Badgr."));
+  console.log(chalk.dim('  Badgr uses prepaid credits to pay for the VM and model usage.\n'));
+
+  let session;
+  try {
+    session = await callApi('/cli/session', { method: 'POST', apiKey: '', baseUrl: config.baseUrl });
+  } catch (err) {
+    console.error(chalk.red(`\n  ✗ Could not start login: ${err.message}\n`));
+    requireApiKey(config); // falls through to the standard "Run: badgr login" error
+    return config;
+  }
+
+  console.log(chalk.dim(`  Opening ${session.login_url} ...`));
+  openBrowser(session.login_url);
+
+  const result = await pollCliSession(config, session.session_id);
+  const updated = saveConfig({ apiKey: result.api_key });
+  console.log(chalk.green('\n  ✓ CLI connected'));
+  console.log(chalk.green(`  ✓ Balance: $${(result.credits ?? 0).toFixed(2)}\n`));
+  return updated;
+}
+
+async function pollBalance(config) {
+  const start = Date.now();
+  while (Date.now() - start < BILLING_POLL_TIMEOUT_MS) {
+    await sleep(POLL_INTERVAL_MS);
+    try {
+      const me = await callApi('/api/me', { apiKey: config.apiKey, baseUrl: apiBase(config) });
+      if ((me.credits ?? 0) > 0) return;
+    } catch {
+      continue;
+    }
+  }
+  throw new Error('Timed out waiting for payment. Run `badgr billing add 10` directly.');
+}
+
+async function ensureFunded(config, chalk) {
+  let me;
+  try {
+    me = await callApi('/api/me', { apiKey: config.apiKey, baseUrl: apiBase(config) });
+  } catch {
+    // Best-effort UX nicety, not the spend-cap enforcement point — the
+    // per-request insufficient_balance error path still protects spend if
+    // this check itself can't reach the API.
+    return;
+  }
+  if ((me.credits ?? 0) > 0) return;
+
+  console.log(chalk.yellow('\n  Your Badgr balance is $0.00.'));
+  console.log(chalk.dim('  Credits pay for: the disposable VM, Badgr model usage, artifact storage and transfer.\n'));
+  console.log(chalk.dim(`  Opening ${BILLING_URL} ...`));
+  openBrowser(BILLING_URL);
+
+  await pollBalance(config);
+  console.log(chalk.green('\n  ✓ Payment confirmed\n'));
+}
+
+export async function ensureBadgrReady(config, chalk) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    // No human to click a browser link — fail fast with the existing message.
+    requireApiKey(config);
+    return config;
+  }
+
+  let cfg = config;
+  if (!cfg.apiKey) {
+    cfg = await ensureLoggedIn(cfg, chalk);
+  }
+  await ensureFunded(cfg, chalk);
+  return cfg;
+}