badgr-cli 1.0.48 → 1.1.0

package/src/commands/down.js

@@ -53,6 +53,12 @@ export async function downCommand(config, args, chalk) {
   const runtimeHr   = (stoppedAt - startedAt) / 3600;
   const finalCost   = (dep.cost_per_hour || 0) * runtimeHr;
 
+  // dep.teardown_ok reflects whether the provider resource was actually
+  // confirmed gone (not just that the DELETE call didn't throw) — a 200
+  // response here can still carry teardown_ok: "failed" if the underlying
+  // instance is locked/protected or deletion couldn't be confirmed.
+  const teardownConfirmed = dep.teardown_ok === 'ok';
+
   const rcptId = generateReceiptId();
   addReceipt({
     receiptId:      rcptId,
@@ -61,14 +67,19 @@ export async function downCommand(config, args, chalk) {
     gpu:            dep.gpu_type,
     runtimeSeconds: Math.round(stoppedAt - startedAt),
     finalCost,
-    status:         'terminated',
+    status:         teardownConfirmed ? 'terminated' : 'teardown_unconfirmed',
     createdAt:      new Date().toISOString(),
   });
 
   removeDeployment(idOrName);
 
-  console.log(chalk.green('\n✓ Stopped'));
-  console.log(chalk.green('  Billing ended\n'));
+  if (teardownConfirmed) {
+    console.log(chalk.green('\n✓ Stopped'));
+    console.log(chalk.green('  Billing ended\n'));
+  } else {
+    console.log(chalk.yellow('\n⚠ Stop requested but not confirmed'));
+    console.log(chalk.yellow(`  Resource may still be billing — check \`badgr status\` and retry \`badgr down ${deploymentId}\`\n`));
+  }
   console.log(`  ${chalk.bold('Runtime:')}    ${formatRuntime(runtimeMin)}`);
   if (finalCost > 0) console.log(`  ${chalk.bold('Final cost:')} $${finalCost.toFixed(4)}`);
   console.log(`  ${chalk.bold('Receipt:')}    ${chalk.dim(rcptId)}\n`);
@@ -117,6 +128,7 @@ async function _downAll(config, chalk, skipConfirm) {
   }
 
   let stoppedCount = 0;
+  let unconfirmedCount = 0;
   let totalCost = 0;
 
   for (const dep of active) {
@@ -127,8 +139,16 @@ async function _downAll(config, chalk, skipConfirm) {
       const startedAt = stopped.started_at ?? stoppedAt;
       const cost      = (stopped.cost_per_hour || 0) * (stoppedAt - startedAt) / 3600;
       totalCost += cost;
-      process.stdout.write(chalk.green(' done\n'));
-      stoppedCount++;
+      // See the single-deployment path above — a 200 response only means
+      // deletion was requested, not confirmed.
+      const teardownConfirmed = stopped.teardown_ok === 'ok';
+      if (teardownConfirmed) {
+        process.stdout.write(chalk.green(' done\n'));
+        stoppedCount++;
+      } else {
+        process.stdout.write(chalk.yellow(' not confirmed — may still be billing\n'));
+        unconfirmedCount++;
+      }
       removeDeployment(dep.deployment_id);
       const rcptId = generateReceiptId();
       addReceipt({
@@ -138,7 +158,7 @@ async function _downAll(config, chalk, skipConfirm) {
         gpu:            dep.gpu_type,
         runtimeSeconds: Math.round(stoppedAt - startedAt),
         finalCost:      cost,
-        status:         'terminated',
+        status:         teardownConfirmed ? 'terminated' : 'teardown_unconfirmed',
         createdAt:      new Date().toISOString(),
       });
     } catch (err) {
@@ -147,6 +167,9 @@ async function _downAll(config, chalk, skipConfirm) {
   }
 
   console.log(chalk.green(`\n✓ Stopped ${stoppedCount}/${active.length} deployment(s)`));
+  if (unconfirmedCount > 0) {
+    console.log(chalk.yellow(`  ${unconfirmedCount} deployment(s) not confirmed stopped — may still be billing, check \`badgr status\`\n`));
+  }
   if (totalCost > 0) console.log(`  Estimated total: $${totalCost.toFixed(4)}`);
   console.log(chalk.green('  Billing ended\n'));
 }

package/src/commands/launch.js

@@ -0,0 +1,431 @@
+import { runCommand, parseRunArgs } from './run.js';
+import { getCredential, setCredential, PROVIDER_ENV_KEYS } from '../credentials.js';
+import { VM_CLASSES, LAUNCH_VM_SIZES, vmClassForWorkload } from '../spec.js';
+
+// Phase 1 supports these coding/testing workloads via shorthand. Do not add
+// more here without a real prepared image behind them — see
+// docs/badgr-execution-roadmap.md. Anything else still works through the
+// explicit `badgr launch <source> -- <command>` form (kept as the advanced
+// escape hatch), including --image for a fully custom runtime.
+//
+// `cline` is the Badgr-native default: no user credential required, since
+// Badgr mints a short-lived, job-scoped token pointing at its own
+// OpenAI-compatible coding-model endpoint (see backend jobs_routes.py's
+// `_cline_model_token` / `_build_worker_command`). `claude`/`codex` are
+// bring-your-own-provider lanes — if no credential is stored yet, an
+// interactive terminal prompts for one inline and stores it via `badgr
+// connect`'s own storage, so a missing credential doesn't force a second,
+// separate command; non-interactive contexts still hard-fail with
+// instructions to run `badgr connect` first.
+//
+// `cline`'s real npm CLI binary is `clite`, with no `task` subcommand (the
+// prompt is a positional arg) — verified against the published @cline/cli
+// package. Its build command actually invokes badgr-cline-run, a wrapper
+// script baked into the image (images/badgr-agent-cline/badgr-cline-run)
+// that runs `clite auth openai -b <OPENAI_BASE_URL> ...` first, since a
+// custom OpenAI-compatible endpoint can only be configured that way, then
+// execs `clite "<task>"` — see that script for why a single BADGR_CMD
+// invocation can't just chain the two calls itself. `codex` similarly needs
+// badgr-codex-run (login + --skip-git-repo-check) — see
+// images/badgr-agent-codex/badgr-codex-run.
+//
+// Images live at ghcr.io/michaelmanly/badgr-agent-* — a live smoke test found
+// the previously-hardcoded ghcr.io/aibadgr/* referenced a GitHub org that
+// doesn't exist (confirmed via the GitHub API: 404), so no agent image could
+// ever have been pulled by any of these launches. Override with
+// BADGR_AGENT_IMAGE_<NAME> (or --image) once these move to a permanent home.
+//
+// buildCmd returns an argument array — never a shell string. The task is
+// always exactly one array element, so it reaches the agent unchanged
+// regardless of spaces, quotes, punctuation, or shell metacharacters: there
+// is no shell-string layer left to round-trip it through (see
+// command_argv on the backend and BADGR_COMMAND_JSON in
+// images/badgr-job-runner/entrypoint.py, which subprocess.run executes
+// directly with shell=False — no shlex.split() involved for this path).
+const AGENT_WORKLOADS = {
+  cline:  { image: process.env.BADGR_AGENT_IMAGE_CLINE  || 'ghcr.io/michaelmanly/badgr-agent-cline:latest',  buildCmd: task => ['badgr-cline-run', task], provider: null },
+  claude: { image: process.env.BADGR_AGENT_IMAGE_CLAUDE || 'ghcr.io/michaelmanly/badgr-agent-claude:latest', buildCmd: task => ['claude', '-p', task],  provider: 'anthropic' },
+  codex:  { image: process.env.BADGR_AGENT_IMAGE_CODEX   || 'ghcr.io/michaelmanly/badgr-agent-codex:latest',  buildCmd: task => ['badgr-codex-run', task], provider: 'openai' },
+};
+
+// Non-agent workloads: no LLM credential, and the task string (if given) is
+// a display label only — Playwright has no natural-language interface, so
+// unlike the agent workloads above, the task text does not change what
+// command actually runs. `badgr launch playwright` (no task) is equally
+// valid. Declares its own report/results dirs as artifacts automatically
+// unless the user already passed --artifacts explicitly.
+const DIRECT_WORKLOADS = {
+  playwright: {
+    image: process.env.BADGR_AGENT_IMAGE_PLAYWRIGHT || 'ghcr.io/michaelmanly/badgr-agent-playwright:latest',
+    // Explicit reporter + CLI-forced trace mode make output deterministic —
+    // a successful test run does not by itself guarantee a report or traces
+    // exist unless something asks for them. --reporter=line,html always
+    // writes an HTML report (to PLAYWRIGHT_HTML_OUTPUT_DIR, set via env
+    // below); --trace is a real Playwright CLI override (unlike
+    // screenshot/video, which are use:{} config-only in the target repo's
+    // own playwright.config.ts — not something Badgr can force without
+    // editing the user's own code, so those are left alone).
+    buildCmd: () => ['npx', 'playwright', 'test', '--reporter=line,html', '--trace=retain-on-failure'],
+    autoArtifacts: ['playwright-report', 'test-results'],
+    autoEnv: ['PLAYWRIGHT_HTML_OUTPUT_DIR=playwright-report'],
+  },
+};
+
+export const KNOWN_WORKLOADS = new Set([...Object.keys(AGENT_WORKLOADS), ...Object.keys(DIRECT_WORKLOADS)]);
+
+// No `--max-cost` required for the frictionless workload flow — this default
+// caps spend automatically instead of forcing a flag or an interactive prompt.
+export const DEFAULT_LAUNCH_MAX_COST = 2;
+
+// Human-readable display only (dry-run/live banners) — never re-parsed by
+// anything. The real transport is the argv array itself (see buildCmd
+// above and opts.cmdArgv in run.js), not this string.
+function displayCmd(argv) {
+  return argv.join(' ');
+}
+
+// Flags recognized when parsing `badgr launch <workload> [flags] <task>`.
+// Flags must appear BEFORE the task text; the first token that isn't one of
+// these ends flag-parsing and everything from there to the end (verbatim,
+// space-joined) is the task — it is never re-parsed as a flag. This is what
+// guarantees a task like "Fix the --output bug" reaches the agent whole
+// instead of having "--output bug" silently stolen as a Badgr flag.
+const _BOOL_FLAGS = {
+  '--dry-run': 'dryRun', '--detach': 'detach', '--no-detach': 'noDetach',
+  '--no-fallback': 'noFallback', '--retry-safe': 'retrySafe',
+};
+const _VALUE_FLAGS = {
+  '--image': 'image', '--count': 'count', '--region': 'region', '--tier': 'tier',
+  '--max-price': 'maxPrice', '--name': 'name', '--fallback': 'fallback',
+  '--max-runtime': 'maxRuntime', '--max-cost': 'maxCost', '--save': 'save',
+  '--workspace': 'workspace', '--output': 'output', '--checkpoint': 'checkpoint',
+  '--resume-cmd': 'resumeCmd', '--size': 'size',
+};
+const _REPEATABLE_FLAGS = { '--env': 'env', '--artifacts': 'artifacts' };
+
+const _PASSTHROUGH_FLAGS = [
+  ['--image', 'image'], ['--count', 'count'], ['--region', 'region'],
+  ['--tier', 'tier'], ['--max-price', 'maxPrice'], ['--name', 'name'],
+  ['--fallback', 'fallback'], ['--max-runtime', 'maxRuntime'],
+  ['--max-cost', 'maxCost'], ['--dry-run', 'dryRun'], ['--save', 'save'],
+  ['--workspace', 'workspace'], ['--output', 'output'],
+  ['--checkpoint', 'checkpoint'], ['--retry-safe', 'retrySafe'],
+  ['--resume-cmd', 'resumeCmd'], ['--no-fallback', 'noFallback'],
+  ['--detach', 'detach'], ['--no-detach', 'noDetach'], ['--size', 'size'],
+];
+
+// Re-serializes parsed `flags` into a flat argv for `runCommand` (which
+// reparses it via parseRunArgs) — shared by both the agent-workload
+// shorthand and the explicit `<source> -- <command>` form below.
+function buildTranslatedArgs(source, flags) {
+  const translatedArgs = [source];
+  if (flags.cmd) translatedArgs.push('--cmd', flags.cmd);
+  if (flags.agentName) translatedArgs.push('--agent-name', flags.agentName);
+  for (const [flag, key] of _PASSTHROUGH_FLAGS) {
+    const value = flags[key];
+    if (value === undefined) continue;
+    if (value === true) translatedArgs.push(flag);
+    else translatedArgs.push(flag, String(value));
+  }
+  if (flags.env) for (const kv of flags.env) translatedArgs.push('--env', kv);
+  if (flags.artifacts) for (const p of flags.artifacts) translatedArgs.push('--artifacts', p);
+  return translatedArgs;
+}
+
+function parseWorkloadShorthandArgs(rawArgs) {
+  const flags = {};
+  let i = 0;
+  while (i < rawArgs.length) {
+    const tok = rawArgs[i];
+    if (tok === '--gpu') return { flags, task: null, gpuRejected: true };
+    if (tok in _BOOL_FLAGS) { flags[_BOOL_FLAGS[tok]] = true; i += 1; continue; }
+    if (tok in _VALUE_FLAGS) { flags[_VALUE_FLAGS[tok]] = rawArgs[i + 1]; i += 2; continue; }
+    if (tok in _REPEATABLE_FLAGS) {
+      const key = _REPEATABLE_FLAGS[tok];
+      if (!flags[key]) flags[key] = [];
+      flags[key].push(rawArgs[i + 1]);
+      i += 2;
+      continue;
+    }
+    break; // first non-flag token — task starts here, verbatim, to the end
+  }
+  const task = rawArgs.slice(i).join(' ').trim();
+  return { flags, task, gpuRejected: false };
+}
+
+const _ALL_FLAG_NAMES = new Set([
+  ...Object.keys(_BOOL_FLAGS), ...Object.keys(_VALUE_FLAGS), ...Object.keys(_REPEATABLE_FLAGS), '--gpu',
+]);
+
+// The task must never be reinterpreted as a Badgr flag (see
+// parseWorkloadShorthandArgs above) — but a flag typed AFTER the task
+// instead of before it (e.g. `badgr launch cline "task" --dry-run`) silently
+// becomes part of the task text with no error, which can launch for real
+// when the user meant a dry run. This is a non-blocking heads-up, not a
+// block: a genuine task might legitimately contain a token that happens to
+// match a flag name, and the spec requires the task always reach the agent
+// unchanged — so we warn, but never alter or drop anything from it.
+function warnIfTaskMayHaveSwallowedAFlag(task, chalk) {
+  const tokens = task.split(' ');
+  const suspect = tokens.filter(t => _ALL_FLAG_NAMES.has(t));
+  if (suspect.length === 0) return;
+  console.error(chalk.yellow(`\n  ⚠ "${suspect.join(', ')}" appears inside the task text, not before it — it was sent to the agent as part of the task, not applied as a Badgr flag.`));
+  console.error(chalk.dim('    Badgr flags must come before the task: badgr launch <agent> [--flags] "<task>"\n'));
+}
+
+/**
+ * badgr launch cline "<task>"       — Badgr-hosted model, no credential needed
+ * badgr launch claude "<task>"      — prompts inline for an Anthropic key if not connected
+ * badgr launch codex "<task>"       — prompts inline for an OpenAI key if not connected
+ * badgr launch playwright ["<task>"] — no credential; task is a display label only
+ * badgr launch <source> -- <command> — explicit form / advanced escape hatch
+ * badgr launch <source> --cmd "<command>"
+ *
+ * The Phase 1 CPU entry point: runs a coding/testing workload (or, via the
+ * explicit form, any other command) on a disposable cloud CPU VM, reusing
+ * `badgr run`'s upload/fallback/receipts plumbing under the hood.
+ */
+export async function launchCommand(config, args, chalk) {
+  const firstArg = args[0] ?? null;
+
+  if (firstArg === null) {
+    console.error(chalk.red('\nUsage:'));
+    console.error(chalk.dim('  badgr launch cline "Fix the checkout bug"'));
+    console.error(chalk.dim('  badgr launch claude "Fix the checkout bug"'));
+    console.error(chalk.dim('  badgr launch codex "Fix the checkout bug"'));
+    console.error(chalk.dim('  badgr launch playwright "Test the checkout flow"'));
+    console.error(chalk.dim('  badgr launch . --max-cost 1 -- npm test   (explicit escape hatch)'));
+    console.error('');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Note: a local directory literally named e.g. "cline" or "playwright"
+  // (without a `./` prefix) is shadowed by the shorthand below — use
+  // `./cline` explicitly to launch such a directory as a source instead.
+  if (firstArg in AGENT_WORKLOADS) {
+    return launchAgentWorkload(config, firstArg, args.slice(1), chalk);
+  }
+  if (firstArg in DIRECT_WORKLOADS) {
+    return launchDirectWorkload(config, firstArg, args.slice(1), chalk);
+  }
+
+  return launchExplicitForm(config, args, chalk);
+}
+
+// Validates an explicit `--size`, or applies the deterministic
+// workload → VM class default (see spec.js's vmClassForWorkload) when the
+// user didn't give one. Returns false (after printing an error) for an
+// unknown size, so the caller can bail out before calling the API.
+function resolveVmSize(flags, workloadName, chalk) {
+  if (flags.size === undefined) {
+    flags.size = vmClassForWorkload(workloadName);
+    return true;
+  }
+  if (!LAUNCH_VM_SIZES.includes(flags.size)) {
+    console.error(chalk.red(`\n  ✗ Unknown --size "${flags.size}". Must be one of: ${LAUNCH_VM_SIZES.join(', ')}\n`));
+    return false;
+  }
+  return true;
+}
+
+async function resolveMissingCredential(provider, chalk) {
+  const providerLabel = provider === 'anthropic' ? 'Anthropic' : 'OpenAI';
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error(chalk.red(`\n  ✗ No ${provider} credential found.\n`));
+    console.error(chalk.dim(`  Run: badgr connect ${provider}\n`));
+    return null;
+  }
+
+  console.log(chalk.yellow(`\n  ${providerLabel} is not connected.`));
+  console.log(chalk.dim(`  ${providerLabel === 'Anthropic' ? 'Claude Code' : 'Codex'} uses your ${providerLabel} account for model usage.`));
+  console.log(chalk.dim('  Badgr credits still pay for the disposable VM.\n'));
+
+  try {
+    const { password } = await import('@inquirer/prompts');
+    const key = await password({
+      message: `Enter your ${providerLabel} API key:`,
+      validate: v => v.trim() ? true : 'API key is required',
+    });
+    const trimmed = key.trim();
+    if (!trimmed) return null;
+    setCredential(provider, trimmed);
+    console.log(chalk.green(`  ✓ ${providerLabel} connected\n`));
+    return trimmed;
+  } catch {
+    // Ctrl+C or a non-interactive stdin that lied about isTTY.
+    return null;
+  }
+}
+
+async function launchAgentWorkload(config, agentName, rawArgs, chalk) {
+  const { flags, task, gpuRejected } = parseWorkloadShorthandArgs(rawArgs);
+
+  if (gpuRejected) {
+    console.error(chalk.red('\n  ✗ badgr launch runs on a CPU VM and does not accept --gpu.\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!task) {
+    console.error(chalk.red(`\n  ✗ ${agentName} needs a task: badgr launch ${agentName} "Fix the checkout bug"\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  warnIfTaskMayHaveSwallowedAFlag(task, chalk);
+
+  if (!resolveVmSize(flags, agentName, chalk)) {
+    process.exitCode = 1;
+    return;
+  }
+
+  const spec = AGENT_WORKLOADS[agentName];
+
+  if (spec.provider) {
+    const envKey = PROVIDER_ENV_KEYS[spec.provider];
+    const userSuppliedKey = flags.env?.some(kv => kv.startsWith(`${envKey}=`));
+    let credential = userSuppliedKey ? null : getCredential(spec.provider);
+    if (!credential && !userSuppliedKey) {
+      // Missing credential no longer forces a separate `badgr connect` +
+      // rerun in an interactive terminal — prompt inline and continue the
+      // same launch. Non-interactive contexts still hard-fail as before.
+      credential = await resolveMissingCredential(spec.provider, chalk);
+      if (!credential) {
+        process.exitCode = 1;
+        return;
+      }
+    }
+    // An explicit --env always wins over the stored credential — never
+    // append the injected default alongside a user-supplied value for the
+    // same key (the last --env wins downstream, so appending here would
+    // silently override what the user typed).
+    if (credential && !userSuppliedKey) {
+      if (!flags.env) flags.env = [];
+      flags.env.push(`${envKey}=${credential}`);
+    }
+  }
+  // cline has no `provider` — Badgr mints and injects its own short-lived
+  // job-scoped model token server-side (see backend jobs_routes.py); the
+  // CLI never handles or displays that token.
+
+  const cmdArgv = spec.buildCmd(task);
+  flags.cmd = displayCmd(cmdArgv);
+  if (!flags.image) flags.image = spec.image;
+  flags.agentName = agentName;
+
+  if (flags.maxCost === undefined) {
+    flags.maxCost = DEFAULT_LAUNCH_MAX_COST;
+    flags.maxCostIsDefault = true;
+  }
+
+  const translatedArgs = buildTranslatedArgs('.', flags);
+  return runCommand(config, translatedArgs, chalk, { isLaunch: true, maxCostIsDefault: flags.maxCostIsDefault === true, cmdArgv });
+}
+
+async function launchDirectWorkload(config, workloadName, rawArgs, chalk) {
+  const { flags, gpuRejected } = parseWorkloadShorthandArgs(rawArgs);
+  // The task text (if any) is a display label only for these workloads —
+  // there's no natural-language interface to hand it to, unlike the agent
+  // workloads above. Read but intentionally not passed to buildCmd().
+
+  if (gpuRejected) {
+    console.error(chalk.red('\n  ✗ badgr launch runs on a CPU VM and does not accept --gpu.\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!resolveVmSize(flags, workloadName, chalk)) {
+    process.exitCode = 1;
+    return;
+  }
+
+  const spec = DIRECT_WORKLOADS[workloadName];
+  const cmdArgv = spec.buildCmd();
+  flags.cmd = displayCmd(cmdArgv);
+  if (!flags.image) flags.image = spec.image;
+  if (!flags.artifacts && spec.autoArtifacts) flags.artifacts = [...spec.autoArtifacts];
+  if (spec.autoEnv) {
+    if (!flags.env) flags.env = [];
+    const existingKeys = new Set(flags.env.map(kv => kv.split('=')[0]));
+    for (const kv of spec.autoEnv) {
+      if (!existingKeys.has(kv.split('=')[0])) flags.env.push(kv);
+    }
+  }
+  flags.agentName = workloadName;
+
+  if (flags.maxCost === undefined) {
+    flags.maxCost = DEFAULT_LAUNCH_MAX_COST;
+    flags.maxCostIsDefault = true;
+  }
+
+  const translatedArgs = buildTranslatedArgs('.', flags);
+  return runCommand(config, translatedArgs, chalk, { isLaunch: true, maxCostIsDefault: flags.maxCostIsDefault === true, cmdArgv });
+}
+
+/**
+ * badgr launch <source> -- <command>   (advanced escape hatch)
+ * badgr launch <source> --cmd "<command>"
+ */
+async function launchExplicitForm(config, args, chalk) {
+  const { flags, positional, commandArgv } = parseRunArgs(args);
+
+  if (positional.length === 0 && commandArgv === null) {
+    console.error(chalk.red('\nUsage:'));
+    console.error(chalk.dim('  badgr launch . --max-cost 1 -- npm test'));
+    console.error(chalk.dim('  badgr launch https://github.com/user/repo --max-cost 1 -- python eval.py'));
+    console.error('');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flags.gpu) {
+    console.error(chalk.red('\n  ✗ badgr launch runs on a CPU VM and does not accept --gpu.\n'));
+    console.error(chalk.dim('  Use `badgr run` for GPU jobs.\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  let cmdArgv;
+  if (commandArgv !== null) {
+    if (commandArgv.length === 0) {
+      console.error(chalk.red('\n  ✗ No command after --. Provide a command to launch.\n'));
+      console.error(chalk.dim('  Example: badgr launch . -- npm test\n'));
+      process.exitCode = 1;
+      return;
+    }
+    if (flags.cmd) {
+      console.error(chalk.red('\n  ✗ Use either `-- <command>` or --cmd, not both.\n'));
+      process.exitCode = 1;
+      return;
+    }
+    // Pass the array straight through as the real transport — joining it
+    // into a string here and sending it via the legacy --cmd path would
+    // throw away the exact bug this form exists to avoid (a multi-word
+    // argument like a quoted task getting torn apart on every space).
+    cmdArgv = commandArgv;
+    flags.cmd = displayCmd(commandArgv);
+  }
+
+  if (flags.maxCost === undefined) {
+    flags.maxCost = DEFAULT_LAUNCH_MAX_COST;
+    flags.maxCostIsDefault = true;
+  }
+
+  if (!resolveVmSize(flags, null, chalk)) {
+    process.exitCode = 1;
+    return;
+  }
+
+  const source = positional[0];
+  const rest = positional.slice(1);
+  if (rest.length > 0) {
+    console.error(chalk.red(`\n  ✗ Unexpected extra arguments: ${rest.join(', ')}\n`));
+    console.error(chalk.dim('  Put the command after `--`, e.g.: badgr launch . -- npm test\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const translatedArgs = buildTranslatedArgs(source, flags);
+  return runCommand(config, translatedArgs, chalk, { isLaunch: true, maxCostIsDefault: flags.maxCostIsDefault === true, cmdArgv });
+}

package/src/commands/pull.js

@@ -0,0 +1,137 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { requireApiKey } from '../config.js';
+import { downloadAndExtractArtifact } from '../artifactDownload.js';
+
+function runGit(args, options = {}) {
+  return spawnSync('git', args, { encoding: 'utf8', ...options });
+}
+
+export function parsePullArgs(args) {
+  const flags = { branch: false, diffOnly: false, yes: false };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--branch') { flags.branch = true; continue; }
+    if (a === '--diff-only') { flags.diffOnly = true; continue; }
+    if (a === '--yes' || a === '-y') { flags.yes = true; continue; }
+    positional.push(a);
+  }
+  return { deploymentId: positional[0], flags };
+}
+
+export function changedFilesFromPatch(patchText) {
+  const files = new Set();
+  for (const line of patchText.split('\n')) {
+    if (line.startsWith('+++ b/')) files.add(line.slice('+++ b/'.length));
+    if (line.startsWith('--- a/')) files.add(line.slice('--- a/'.length));
+  }
+  files.delete('/dev/null');
+  return [...files].sort();
+}
+
+export function localChangedFiles(git = runGit) {
+  const res = git(['status', '--porcelain']);
+  if (res.status !== 0) throw new Error(res.stderr || 'git status failed');
+  // Porcelain lines are a fixed-width "XY " status prefix (2 status chars,
+  // often a literal space, + 1 separator space) followed by the path —
+  // trim()ing the line first eats that leading status space and shifts the
+  // slice(3), corrupting the filename. Only strip a trailing \r/\n.
+  return res.stdout
+    .split('\n')
+    .map(l => l.replace(/\r$/, ''))
+    .filter(l => l.length > 0)
+    .map(l => l.slice(3).split(' -> ').pop())
+    .filter(Boolean)
+    .sort();
+}
+
+export function intersectFiles(a, b) {
+  const right = new Set(b);
+  return a.filter(x => right.has(x));
+}
+
+function findPatchFile(dir) {
+  const candidates = [];
+  function walk(p) {
+    for (const entry of fs.readdirSync(p, { withFileTypes: true })) {
+      const full = path.join(p, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith('.patch')) candidates.push(full);
+    }
+  }
+  walk(dir);
+  return candidates.find(p => path.basename(p) === 'badgr-agent.patch') || candidates[0] || null;
+}
+
+export async function pullCommand(config, args, chalk) {
+  requireApiKey(config);
+  const { deploymentId, flags } = parsePullArgs(args);
+  if (!deploymentId) {
+    console.error(chalk.red('\n  Usage: badgr pull <deployment-id> [--diff-only|--branch|--yes]\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const inside = runGit(['rev-parse', '--is-inside-work-tree']);
+  if (inside.status !== 0 || inside.stdout.trim() !== 'true') {
+    console.error(chalk.red('\n  ✗ badgr pull must be run inside a git worktree.\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), `badgr-pull-${deploymentId}-`));
+  try {
+    await downloadAndExtractArtifact(config, deploymentId, tmp);
+    const patchFile = findPatchFile(tmp);
+    if (!patchFile) {
+      // Not every run changes code — a test/eval command with --artifacts
+      // paths (or no output capture at all) has nothing for `pull` to apply.
+      console.log(chalk.dim(`\n  No code-patch artifact for ${deploymentId} — nothing to apply.`));
+      console.log(chalk.dim('  This is normal for a run that only produced logs or --artifacts output (test reports, screenshots, etc).'));
+      console.log(chalk.dim(`  Run \`badgr artifacts ${deploymentId}\` to download any non-patch output instead.\n`));
+      return;
+    }
+    const patch = fs.readFileSync(patchFile, 'utf8');
+    const cloudFiles = changedFilesFromPatch(patch);
+    const localFiles = localChangedFiles();
+    const conflicts = intersectFiles(cloudFiles, localFiles);
+
+    if (flags.diffOnly) {
+      process.stdout.write(patch);
+      return;
+    }
+
+    if (conflicts.length > 0 && !flags.branch) {
+      console.error(chalk.yellow(`\n  Cloud changes touch ${cloudFiles.length} file(s); ${conflicts.length} conflict with local edits.`));
+      for (const f of conflicts) console.error(chalk.yellow(`  - ${f}`));
+      console.error(chalk.dim('\n  No files were changed. Re-run with --branch to apply on a new local branch, or --diff-only to inspect.\n'));
+      process.exitCode = 1;
+      return;
+    }
+
+    if (flags.branch) {
+      const branch = `badgr/${deploymentId}`;
+      const checkout = runGit(['checkout', '-b', branch]);
+      if (checkout.status !== 0) throw new Error(checkout.stderr || `could not create branch ${branch}`);
+      console.log(chalk.dim(`  Created branch ${branch}`));
+    }
+
+    const check = runGit(['apply', '--check', patchFile]);
+    if (check.status !== 0) throw new Error(check.stderr || 'patch does not apply cleanly');
+    const apply = runGit(['apply', patchFile]);
+    if (apply.status !== 0) throw new Error(apply.stderr || 'patch apply failed');
+
+    console.log(chalk.green(`\n  Applied cloud changes from ${deploymentId}.`));
+    console.log(`  Files changed: ${cloudFiles.length}`);
+    for (const f of cloudFiles) console.log(`  - ${f}`);
+    console.log();
+  } catch (err) {
+    console.error(chalk.red(`\n  ✗ Could not pull ${deploymentId}: ${err.message}\n`));
+    process.exitCode = 1;
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}