badgr-cli 1.0.32 → 1.0.34

package/src/errors.js

@@ -0,0 +1,299 @@
+/**
+ * Unified CLI error catalog — single source of truth for all user-facing errors.
+ *
+ * Each entry defines:
+ *   message  — what happened (user-safe, no provider/host details)
+ *   billing  — whether billing started, stopped, or is uncertain
+ *   retried  — whether Badgr automatically retried before surfacing this error
+ *   hint     — concrete next step(s) for the user
+ *   severity — P1/P2/P3/P4 for backend incident tracking
+ *
+ * Use formatCliError() to render entries as multiline CLI output.
+ * Pass internal-only fields (provider names, raw errors) via the `internal`
+ * argument — they are only shown when BADGR_DEBUG=1.
+ */
+
+export const CATALOG = {
+  // ── Capacity ──────────────────────────────────────────────────────────────
+
+  NO_CAPACITY: {
+    message: (ctx) =>
+      `No ${ctx.gpu || 'GPU'} available${ctx.region ? ` in ${ctx.region}` : ''} right now.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: (ctx) => [
+      ...(ctx.alternatives?.length
+        ? [`Closest available: ${ctx.alternatives.slice(0, 2).map(a => a.gpu).join(', ')}`]
+        : []),
+      ctx.region ? 'Remove --region to search globally.' : null,
+      'Run `badgr capacity` to see live availability.',
+    ].filter(Boolean),
+    severity: 'P3',
+  },
+
+  STALE_CAPACITY: {
+    message: () => 'A GPU slot appeared available but could not be reserved (stale capacity).',
+    billing:  'never_started',
+    retried:  true,
+    hint: () => ['Please try again shortly.'],
+    severity: 'P3',
+  },
+
+  PROVISIONING_TIMEOUT: {
+    message: () => 'GPU provisioning timed out.',
+    billing:  'never_started',
+    retried:  false,
+    hint: () => [
+      'Please try again.',
+      'If this repeats, try a different --gpu type or --region.',
+    ],
+    severity: 'P2',
+  },
+
+  PROVISIONING_FAILED: {
+    message: (ctx) =>
+      ctx.failure_category === 'compat_failure'
+        ? 'GPU/CUDA driver incompatibility — the container requires a CUDA version this GPU does not support.'
+        : 'GPU was reserved but the container failed to start.',
+    billing:  'never_started',
+    retried:  true,
+    hint: (ctx) =>
+      ctx.failure_category === 'compat_failure'
+        ? ['Try a different base image or a different --gpu type.']
+        : ['Badgr retried once. Please try again, or try a different --gpu type.'],
+    severity: 'P2',
+  },
+
+  // ── Auth / billing ────────────────────────────────────────────────────────
+
+  AUTH_FAILED: {
+    message: () => 'Invalid or expired API key.',
+    billing:  'never_started',
+    retried:  false,
+    hint: () => ['Run `badgr login` to set a new key.'],
+    severity: 'P3',
+  },
+
+  BILLING_INSUFFICIENT: {
+    message: (ctx) => {
+      let msg = 'Insufficient balance.';
+      if (ctx.balance_usd != null) msg += ` Balance: $${Number(ctx.balance_usd).toFixed(2)}.`;
+      if (ctx.required_usd != null) msg += ` Required: $${Number(ctx.required_usd).toFixed(2)}.`;
+      return msg;
+    },
+    billing:  'never_started',
+    retried:  false,
+    hint: (ctx) => [`Add balance: ${ctx.topup_url || 'https://aibadgr.com/dashboard#billing'}`],
+    severity: 'P3',
+  },
+
+  // ── Input validation ──────────────────────────────────────────────────────
+
+  INVALID_GPU: {
+    message: (ctx) => `GPU type '${ctx.gpu || 'unknown'}' is not recognized.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => ['Run `badgr gpus` to see available GPU types.'],
+    severity: 'P4',
+  },
+
+  MAX_COST_TOO_LOW: {
+    message: (ctx) =>
+      `--max-cost $${Number(ctx.maxCost || 0).toFixed(2)} is too low to start a job.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => [
+      'GPU jobs accrue cost from the moment a machine is reserved.',
+      'Use --max-cost 1.00 or higher.',
+    ],
+    severity: 'P4',
+  },
+
+  INVALID_MODEL: {
+    message: (ctx) =>
+      ctx.server_message ||
+      `Model '${ctx.model || 'unknown'}' not found or inaccessible on HuggingFace.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => [
+      'Check the model ID at huggingface.co.',
+      'For private or gated models, set HF_TOKEN in your environment.',
+    ],
+    severity: 'P4',
+  },
+
+  INSUFFICIENT_VRAM: {
+    message: (ctx) =>
+      ctx.server_message ||
+      `GPU '${ctx.gpu || 'unknown'}' does not have enough VRAM for this model.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => ['Try --gpu L40S, --gpu A100, or --gpu H100 for larger models.'],
+    severity: 'P4',
+  },
+
+  // ── Job / execution ───────────────────────────────────────────────────────
+
+  JOB_FAILED: {
+    message: (ctx) => `Job exited with code ${ctx.exitCode ?? 'unknown'}.`,
+    billing:  'stopped',
+    retried:  false,
+    hint: (ctx) => [`Check logs: badgr logs ${ctx.deploymentId || '<id>'}`],
+    severity: 'P4',
+  },
+
+  JOB_INFRASTRUCTURE_FAILURE: {
+    message: () => 'Container failed to start (infrastructure error — not your code).',
+    billing:  'never_started',
+    retried:  false,
+    hint: (ctx) => [
+      'The backend retried automatically. All attempts failed.',
+      'Contact support with your receipt ID for a refund.',
+      `Receipt: ${ctx.receiptId || 'run `badgr receipts`'}`,
+    ],
+    severity: 'P2',
+  },
+
+  HEARTBEAT_LOST: {
+    message: () => 'Lost connection to the running job — cloud machine became unresponsive.',
+    billing:  'stopped',
+    retried:  false,
+    hint: (ctx) => [
+      'The job was stopped and billing ended.',
+      `Receipt: ${ctx.receiptId || 'run `badgr receipts`'} — contact support if you were charged unexpectedly.`,
+    ],
+    severity: 'P2',
+  },
+
+  // ── Serve / endpoint ──────────────────────────────────────────────────────
+
+  HEALTH_CHECK_FAILED: {
+    message: (ctx) =>
+      `Endpoint at '${ctx.healthPath || '/models'}' did not become healthy.`,
+    billing:  'stopped',
+    retried:  false,
+    hint: (ctx) => [
+      'The endpoint was terminated to stop billing.',
+      ctx.deploymentId ? `Logs: badgr logs ${ctx.deploymentId}` : null,
+      'Check your model config or container startup behaviour.',
+    ].filter(Boolean),
+    severity: 'P3',
+  },
+
+  HEALTH_CHECK_DEPLOY_FAILED: {
+    message: (ctx) =>
+      `Deployment failed during startup: ${ctx.failReason || 'unknown error'}.`,
+    billing:  'stopped',
+    retried:  false,
+    hint: (ctx) => [
+      ctx.deploymentId ? `Logs: badgr logs ${ctx.deploymentId}` : null,
+    ].filter(Boolean),
+    severity: 'P3',
+  },
+
+  // ── Teardown / receipt ────────────────────────────────────────────────────
+
+  TEARDOWN_FAILED: {
+    message: () => 'Could not stop the job — billing may still be running.',
+    billing:  'check_receipt',
+    retried:  true,  // terminateDeployment already retries 3×
+    hint: (ctx) => [
+      `Run: badgr down ${ctx.deploymentId || '<dep-id>'}`,
+      'Or visit your dashboard to stop billing manually.',
+      `Receipt: ${ctx.receiptId || 'run `badgr receipts`'}`,
+    ],
+    severity: 'P1',
+  },
+
+  RECEIPT_FAILED: {
+    message: () => 'Could not record a local receipt for this job.',
+    billing:  'check_receipt',
+    retried:  false,
+    hint: () => ['Check `badgr receipts` or your dashboard for billing details.'],
+    severity: 'P3',
+  },
+
+  // ── Network / connection ──────────────────────────────────────────────────
+
+  NETWORK_ERROR: {
+    message: (ctx) =>
+      `Could not reach the Badgr API (${ctx.url || ctx.baseUrl || 'unknown URL'}).`,
+    billing:  'never_started',
+    retried:  false,
+    hint: (ctx) => [
+      'Check your internet connection.',
+      'Run `badgr config` to verify the API URL.',
+      ctx.baseUrl ? `Test: curl ${ctx.baseUrl}/health` : null,
+    ].filter(Boolean),
+    severity: 'P4',
+  },
+
+  CONNECTION_REFUSED: {
+    message: (ctx) => `Connection refused at ${ctx.baseUrl || 'the API'}.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => ['Is the server running? Run `badgr config` to check the API URL.'],
+    severity: 'P4',
+  },
+
+  DNS_FAILED: {
+    message: (ctx) => `DNS lookup failed for ${ctx.baseUrl || 'the API'}.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => [
+      'Check your internet connection.',
+      'Run `badgr config` to verify the API URL is correct.',
+    ],
+    severity: 'P4',
+  },
+};
+
+// Human-readable billing status labels.
+const _BILLING_LABEL = {
+  never_started: 'Billing: never started.',
+  stopped:       'Billing: stopped.',
+  check_receipt: 'Billing: check your receipt or dashboard.',
+  charged:       'Billing: you were charged.',
+};
+
+/**
+ * Render a structured error as a multiline CLI string ready for console.error().
+ *
+ * @param {string} code         - Key from CATALOG
+ * @param {object} ctx          - Context passed to message/hint templates
+ * @param {object} chalk        - chalk instance (or passthrough mock in tests)
+ * @param {object} [internal]   - Internal-only fields shown only with BADGR_DEBUG=1
+ * @returns {string}
+ */
+export function formatCliError(code, ctx = {}, chalk, internal = {}) {
+  const entry = CATALOG[code];
+  if (!entry) {
+    return chalk.red(`\n  ✗ ${code} — An unexpected error occurred.\n`) +
+           chalk.dim('  Run BADGR_DEBUG=1 … for a full trace.\n');
+  }
+
+  const msg    = typeof entry.message === 'function' ? entry.message(ctx) : entry.message;
+  const hints  = (typeof entry.hint === 'function' ? entry.hint(ctx) : entry.hint) ?? [];
+  const billing = _BILLING_LABEL[entry.billing] ?? '';
+  const debug   = process.env.BADGR_DEBUG === '1' || process.env.BADGR_DEBUG === 'true';
+
+  const lines = [chalk.red(`\n  ✗ ${code} — ${msg}`)];
+  if (entry.retried) lines.push(chalk.dim('  Badgr retried automatically.'));
+  if (billing)       lines.push(chalk.dim(`  ${billing}`));
+
+  if (hints.length) {
+    lines.push('');
+    for (const h of hints) lines.push(chalk.dim(`  → ${h}`));
+  }
+
+  if (debug && Object.keys(internal).length > 0) {
+    lines.push('');
+    lines.push(chalk.dim('  [debug]'));
+    for (const [k, v] of Object.entries(internal)) {
+      if (v != null) lines.push(chalk.dim(`    ${k}: ${String(v)}`));
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}

package/src/fallback.js

@@ -1,4 +1,5 @@
 import readline from 'readline';
+import { CATALOG, formatCliError } from './errors.js';
 
 // ── Shared routing helpers ────────────────────────────────────────────────────
 
@@ -43,52 +44,91 @@ export async function callWithFallback(endpoint, callOpts, buildBody, effectiveT
   const cmd   = labels?.cmd   ?? 'badgr run';
   const allowTier2Fallback = opts.allowTier2Fallback !== false; // default true
 
+  // 75s: backend provisioning runs up to 55s and returns PROVISIONING_TIMEOUT;
+  // the extra headroom ensures the CLI always sees the real response.
   async function attempt(body) {
-    return callApi(endpoint, { method: 'POST', ...callOpts, body, timeoutMs: 30_000 });
+    return callApi(endpoint, { method: 'POST', ...callOpts, body, timeoutMs: 75_000 });
   }
 
+  // Map server error codes → catalog keys and extract context for templates.
   function buildCapacityError(err, isFallback) {
-    const d = err.errorData;
-    let msg;
-    if (d?.code === 'NO_CAPACITY_MATCH') {
-      msg = chalk.red('\n  ✗ No suitable GPU capacity available right now.\n') +
-            chalk.dim('  Try `badgr capacity` to see what\'s available, or try again shortly.');
-    } else if (d?.code === 'PROVISIONING_FAILED' || d?.code === 'PROVIDER_ADAPTER_ERROR') {
-      if (d?.low_cost_provider_failed) {
-        msg = chalk.red(`\n  ✗ No suitable capacity available right now. Try again shortly.\n`);
-      } else {
-        msg = chalk.red(`\n  ✗ Capacity found but ${thing} failed to start. Please try again.\n`);
-        if (process.env.BADGR_DEBUG === '1' || process.env.BADGR_DEBUG === 'true') {
-          if (d?.debug_error) msg += chalk.dim(`  Detail: ${d.debug_error}`);
-        } else {
-          msg += chalk.dim(`  Run BADGR_DEBUG=1 ${cmd} … for a full trace.\n`);
-        }
-      }
-    } else {
-      msg = chalk.red(`\n  ✗ Could not start ${thing}: ${err.message}\n`) +
-            chalk.dim(`  Run BADGR_DEBUG=1 ${cmd} … for a full trace.`);
-      if (!isFallback) msg += '\n' + chalk.dim(`  Check config: badgr config\n`);
+    const d    = err.errorData ?? {};
+    const code = d.code ?? '';
+
+    // Internal fields: shown only with BADGR_DEBUG=1
+    const internal = {
+      ...(d.debug_error ? { detail: d.debug_error } : {}),
+      ...(d.filters     ? { filters: JSON.stringify(d.filters) } : {}),
+    };
+
+    // Map server codes → catalog keys + context
+    const serverToKey = {
+      NO_CAPACITY:           'NO_CAPACITY',
+      NO_CAPACITY_MATCH:     'NO_CAPACITY',
+      PROVISIONING_TIMEOUT:  'PROVISIONING_TIMEOUT',
+      PROVISIONING_FAILED:   'PROVISIONING_FAILED',
+      PROVIDER_ADAPTER_ERROR:'PROVISIONING_FAILED',
+      INVALID_GPU:           'INVALID_GPU',
+      INVALID_MODEL:         'INVALID_MODEL',
+      INSUFFICIENT_VRAM:     'INSUFFICIENT_VRAM',
+      MAX_COST_TOO_LOW:      'MAX_COST_TOO_LOW',
+    };
+
+    const key = serverToKey[code];
+    if (key) {
+      const ctx = {
+        gpu:              d.filters?.gpu ?? d.gpu,
+        region:           d.filters?.region,
+        failure_category: d.failure_category,
+        low_cost_failed:  d.low_cost_provider_failed,
+        server_message:   d.message,
+        alternatives:     d.alternatives,
+      };
+      return new CapacityError(formatCliError(key, ctx, chalk, internal));
     }
-    return new CapacityError(msg);
+
+    // Unknown / generic error — safe fallback with no internal details exposed
+    const fallbackMsg =
+      chalk.red(`\n  ✗ Could not start ${thing}: ${err.message}\n`) +
+      chalk.dim(`  Run BADGR_DEBUG=1 ${cmd} … for a full trace.`) +
+      (!isFallback ? '\n' + chalk.dim('  Check config: badgr config\n') : '');
+    return new CapacityError(fallbackMsg);
   }
 
+  // First attempt
+  let firstErr;
   try {
     return await attempt(buildBody());
   } catch (err) {
-    const d = err.errorData;
-
-    if (d?.code === 'NO_CAPACITY_MATCH' && effectiveTier !== '2' && allowTier2Fallback) {
-      console.log(chalk.dim('\n  Primary capacity unavailable — expanding search...\n'));
-      try {
-        return await attempt(buildBody('2'));
-      } catch (err2) {
-        throw buildCapacityError(err2, true);
-      }
+    if (err.isPaymentRequired) throw err;
+    firstErr = err;
+  }
+
+  const d = firstErr.errorData;
+
+  // Stale-capacity retry: PROVISIONING_FAILED means a GPU slot appeared available but
+  // couldn't launch. Retry once immediately to pick up a fresh slot before escalating.
+  if (d?.code === 'PROVISIONING_FAILED' || d?.code === 'PROVIDER_ADAPTER_ERROR') {
+    console.log(chalk.dim('\n  Provisioning failed — retrying with fresh capacity...\n'));
+    try {
+      return await attempt(buildBody());
+    } catch (retryErr) {
+      if (retryErr.isPaymentRequired) throw retryErr;
+      firstErr = retryErr;
     }
+  }
 
-    if (err.isPaymentRequired) throw err; // let caller handle payment errors
-    throw buildCapacityError(err, false);
+  // Tier-2 expansion: try budget-tier providers when primary has no capacity
+  if (firstErr.errorData?.code === 'NO_CAPACITY_MATCH' && effectiveTier !== '2' && allowTier2Fallback) {
+    console.log(chalk.dim('\n  Primary capacity unavailable — expanding search...\n'));
+    try {
+      return await attempt(buildBody('2'));
+    } catch (err2) {
+      throw buildCapacityError(err2, true);
+    }
   }
+
+  throw buildCapacityError(firstErr, false);
 }
 
 // ── GPU fallback prompt ───────────────────────────────────────────────────────

package/src/router.js

@@ -11,9 +11,10 @@
 export const GPU_CATALOG = [
   { id: 'rtx-3080',  canonical: 'RTX_3080',  name: 'NVIDIA RTX 3080',   vramGb: 10, ratePerHour: 0.35, tags: ['inference', 'dev'] },
   { id: 'rtx-3090',  canonical: 'RTX_3090',  name: 'NVIDIA RTX 3090',   vramGb: 24, ratePerHour: 0.60, tags: ['inference', 'dev'] },
-  { id: 'rtx-4090',  canonical: 'RTX_4090',  name: 'NVIDIA RTX 4090',   vramGb: 24, ratePerHour: 1.10, tags: ['inference', 'training', 'dev'] },
   { id: 'a4000',     canonical: 'A4000',      name: 'NVIDIA RTX A4000',  vramGb: 16, ratePerHour: 0.50, tags: ['inference', 'dev'] },
   { id: 'a5000',     canonical: 'A5000',      name: 'NVIDIA RTX A5000',  vramGb: 24, ratePerHour: 0.70, tags: ['inference', 'dev'] },
+  { id: 'rtx-4080',  canonical: 'RTX_4080',  name: 'NVIDIA RTX 4080',   vramGb: 16, ratePerHour: 0.75, tags: ['inference', 'dev'] },
+  { id: 'rtx-4090',  canonical: 'RTX_4090',  name: 'NVIDIA RTX 4090',   vramGb: 24, ratePerHour: 1.10, tags: ['inference', 'training', 'dev'] },
   { id: 'l40s',      canonical: 'L40S',       name: 'NVIDIA L40S',       vramGb: 48, ratePerHour: 1.40, tags: ['inference', 'training'] },
   { id: 'a6000',     canonical: 'A6000',      name: 'NVIDIA RTX A6000',  vramGb: 48, ratePerHour: 1.60, tags: ['inference', 'training'] },
   { id: 'a100-40gb', canonical: 'A100',       name: 'NVIDIA A100 40GB',  vramGb: 40, ratePerHour: 1.80, tags: ['training', 'inference'] },

package/tests/commands.test.js

@@ -82,6 +82,18 @@ describe('parseRunArgs', () => {
     const { flags } = parseRunArgs(['python', 'train.py']);
     expect(flags.tier).toBeUndefined();
   });
+
+  it('parses --min-vram flag', () => {
+    const { flags } = parseRunArgs(['python', 'job.py', '--min-vram', '24']);
+    expect(flags.minVram).toBe(24);
+    expect(flags.gpu).toBeUndefined();
+  });
+
+  it('--min-vram and --gpu can be combined', () => {
+    const { flags } = parseRunArgs(['python', 'job.py', '--gpu', 'A100', '--min-vram', '40']);
+    expect(flags.gpu).toBe('A100');
+    expect(flags.minVram).toBe(40);
+  });
 });
 
 describe('classifyFailure', () => {

package/tests/errors.test.js

@@ -0,0 +1,130 @@
+/**
+ * Tests for the unified error catalog (errors.js).
+ * Verifies that every catalog entry produces output matching the four CLI guarantees:
+ *   1. What happened   (code + message in output)
+ *   2. Retry status    (retried note when entry.retried === true)
+ *   3. Billing status  (billing label in output)
+ *   4. Next step       (at least one → hint in output)
+ */
+import { describe, it, expect } from 'vitest';
+import { CATALOG, formatCliError } from '../src/errors.js';
+
+// Passthrough chalk mock — identical to what the lifecycle test suite uses.
+const chalk = new Proxy({}, {
+  get: () => (s) => s,
+});
+
+describe('CATALOG completeness', () => {
+  const REQUIRED_FIELDS = ['message', 'billing', 'retried', 'hint', 'severity'];
+  const VALID_BILLING   = ['never_started', 'stopped', 'check_receipt', 'charged'];
+  const VALID_SEVERITY  = ['P1', 'P2', 'P3', 'P4'];
+
+  for (const [code, entry] of Object.entries(CATALOG)) {
+    it(`${code} has all required fields`, () => {
+      for (const f of REQUIRED_FIELDS) {
+        expect(entry, `${code} missing field: ${f}`).toHaveProperty(f);
+      }
+      expect(VALID_BILLING, `${code}.billing invalid`).toContain(entry.billing);
+      expect(VALID_SEVERITY, `${code}.severity invalid`).toContain(entry.severity);
+    });
+  }
+});
+
+describe('formatCliError', () => {
+  it('includes the error code in the output', () => {
+    const out = formatCliError('NO_CAPACITY', {}, chalk);
+    expect(out).toContain('NO_CAPACITY');
+  });
+
+  it('includes billing label in output', () => {
+    const out = formatCliError('NO_CAPACITY', {}, chalk);
+    expect(out).toContain('Billing: never started');
+  });
+
+  it('includes a → hint line', () => {
+    const out = formatCliError('NO_CAPACITY', {}, chalk);
+    expect(out).toContain('→');
+  });
+
+  it('shows "Badgr retried automatically" only for retried=true entries', () => {
+    const retried = formatCliError('PROVISIONING_FAILED', {}, chalk);
+    expect(retried).toContain('Badgr retried automatically');
+
+    const notRetried = formatCliError('NO_CAPACITY', {}, chalk);
+    expect(notRetried).not.toContain('Badgr retried automatically');
+  });
+
+  it('does not expose internal fields by default', () => {
+    const out = formatCliError('PROVISIONING_FAILED', {}, chalk, { detail: 'SECRET_PROVIDER_URL' });
+    expect(out).not.toContain('SECRET_PROVIDER_URL');
+  });
+
+  it('exposes internal fields when BADGR_DEBUG=1', () => {
+    process.env.BADGR_DEBUG = '1';
+    try {
+      const out = formatCliError('PROVISIONING_FAILED', {}, chalk, { detail: 'SECRET_PROVIDER_URL' });
+      expect(out).toContain('SECRET_PROVIDER_URL');
+    } finally {
+      delete process.env.BADGR_DEBUG;
+    }
+  });
+
+  it('falls back gracefully for unknown codes', () => {
+    const out = formatCliError('TOTALLY_UNKNOWN_CODE', {}, chalk);
+    expect(out).toContain('TOTALLY_UNKNOWN_CODE');
+    expect(out).toContain('unexpected error');
+  });
+
+  // ── Specific catalog entries ──────────────────────────────────────────────
+
+  it('PROVISIONING_FAILED compat_failure contains incompatib and GPU type/image', () => {
+    const out = formatCliError('PROVISIONING_FAILED', { failure_category: 'compat_failure' }, chalk);
+    expect(out).toContain('incompatib');
+    expect(out).toMatch(/GPU type|image/i);
+  });
+
+  it('PROVISIONING_FAILED generic contains "failed to start" and "try again"', () => {
+    const out = formatCliError('PROVISIONING_FAILED', {}, chalk);
+    expect(out).toContain('failed to start');
+    expect(out).toMatch(/try again/i);
+    expect(out).not.toContain('incompatib');
+  });
+
+  it('NO_CAPACITY output contains "capacity" (satisfies /capacity/i test)', () => {
+    const out = formatCliError('NO_CAPACITY', {}, chalk);
+    expect(out).toMatch(/capacity/i);
+  });
+
+  it('TEARDOWN_FAILED is P1 severity', () => {
+    expect(CATALOG.TEARDOWN_FAILED.severity).toBe('P1');
+  });
+
+  it('TEARDOWN_FAILED billing is check_receipt', () => {
+    expect(CATALOG.TEARDOWN_FAILED.billing).toBe('check_receipt');
+  });
+
+  it('TEARDOWN_FAILED output contains billing warning', () => {
+    const out = formatCliError('TEARDOWN_FAILED', { deploymentId: 'dep-123', receiptId: 'rcpt-456' }, chalk);
+    expect(out).toContain('check your receipt');
+    expect(out).toContain('dep-123');
+  });
+
+  it('JOB_INFRASTRUCTURE_FAILURE billing is never_started', () => {
+    expect(CATALOG.JOB_INFRASTRUCTURE_FAILURE.billing).toBe('never_started');
+  });
+
+  it('HEALTH_CHECK_FAILED billing is stopped', () => {
+    expect(CATALOG.HEALTH_CHECK_FAILED.billing).toBe('stopped');
+  });
+
+  it('BILLING_INSUFFICIENT shows balance and required when provided', () => {
+    const out = formatCliError('BILLING_INSUFFICIENT', {
+      balance_usd: 1.23,
+      required_usd: 5.00,
+      topup_url: 'https://example.com/billing',
+    }, chalk);
+    expect(out).toContain('1.23');
+    expect(out).toContain('5.00');
+    expect(out).toContain('example.com/billing');
+  });
+});