blastproof 0.2.2 → 0.4.0

package/dist/cli.js

@@ -26,6 +26,9 @@ llm:
 
 browser:
   headless: true
+  # How long to wait for an element to appear (self-healing resolution) as well as
+  # for the action performed on it and for navigation. Raising it makes a slow app
+  # wait longer to succeed, and a genuinely missing element take longer to fail.
   timeout_ms: 30000
 
 # Budget of self-healing retries per step (element re-resolution via accessibility tree).
@@ -152,23 +155,110 @@ function formatInitGuidance(result) {
   lines.push(
     "",
     "Next steps:",
-    "  1. Set your LLM API key:  export ANTHROPIC_API_KEY=...   (or OPENAI_API_KEY; ollama needs no key)",
-    "  2. Start your app, then point base_url at it in .blastproof/config.yaml",
-    "  3. Run your tests:        blastproof run",
+    // Deliberately keyless first. A first-time-user trial found that following
+    // the old order — key, app, run — meant hitting the missing-key error and
+    // then a browser-launch failure with nothing successful behind you, which
+    // reads as "this is broken" rather than "one leg needs setting up". Seeing
+    // real output first reframes both.
+    "  1. Point base_url at your app in .blastproof/config.yaml",
+    "  2. Check the setup:       blastproof run --dry-run    (no API key or browser needed)",
+    "  3. Set your LLM API key:  export ANTHROPIC_API_KEY=...   (or OPENAI_API_KEY; ollama needs no key)",
+    "  4. Install the browser:   npx playwright install chromium",
+    "  5. Run your tests:        blastproof run",
     "",
-    "First time with Playwright? Install the browser:  npx playwright install chromium"
+    "Without a key or a browser you can still map a diff to routes and gate on",
+    "coverage:  blastproof run --impacted --fail-on-unmapped --dry-run"
   );
   return lines.join("\n");
 }
 
 // src/commands/plan.ts
 import path10 from "path";
-import { chromium as chromium2 } from "playwright";
 
 // src/auth.ts
 import { readFile, writeFile as writeFile2, mkdir as mkdir3 } from "fs/promises";
 import path3 from "path";
 
+// src/runner/budget.ts
+function describeLimit(limit, observed, configured) {
+  switch (limit) {
+    case "calls":
+      return `model call budget exhausted: reached the configured maximum of ${configured} call(s)`;
+    case "tokens":
+      return `token budget exhausted: reached the configured maximum of ${configured} token(s) (observed ${observed})`;
+    case "duration":
+      return `deadline exceeded: reached the configured maximum of ${(configured / 1e3).toFixed(0)}s (elapsed ${(observed / 1e3).toFixed(1)}s)`;
+  }
+}
+var BudgetExhaustedError = class extends Error {
+  limit;
+  observed;
+  configured;
+  constructor(limit, observed, configured) {
+    super(describeLimit(limit, observed, configured));
+    this.name = "BudgetExhaustedError";
+    this.limit = limit;
+    this.observed = observed;
+    this.configured = configured;
+  }
+};
+var RunBudget = class {
+  maxCalls;
+  maxTokens;
+  maxDurationMs;
+  now;
+  startedAt;
+  calls = 0;
+  tokens = 0;
+  constructor(options = {}) {
+    this.maxCalls = options.maxCalls;
+    this.maxTokens = options.maxTokens;
+    this.maxDurationMs = options.maxDurationMs;
+    this.now = options.now ?? Date.now;
+    this.startedAt = this.now();
+  }
+  /** Model calls recorded so far. */
+  get callCount() {
+    return this.calls;
+  }
+  /** Tokens recorded so far, summed across every completed call. */
+  get tokenCount() {
+    return this.tokens;
+  }
+  /**
+   * Throws {@link BudgetExhaustedError} when the next unit of work could exceed a
+   * configured limit. Called before spending anything, never after — so an
+   * over-budget call is never issued and then rejected (spec: "the call is not
+   * made").
+   */
+  check() {
+    if (this.maxCalls !== void 0 && this.calls >= this.maxCalls) {
+      throw new BudgetExhaustedError("calls", this.calls, this.maxCalls);
+    }
+    if (this.maxTokens !== void 0 && this.tokens >= this.maxTokens) {
+      throw new BudgetExhaustedError("tokens", this.tokens, this.maxTokens);
+    }
+    if (this.maxDurationMs !== void 0) {
+      const elapsed = this.now() - this.startedAt;
+      if (elapsed >= this.maxDurationMs) {
+        throw new BudgetExhaustedError("duration", elapsed, this.maxDurationMs);
+      }
+    }
+  }
+  /** Records what a completed model call spent. */
+  record(usage) {
+    this.calls += 1;
+    if (usage?.totalTokens !== void 0) this.tokens += usage.totalTokens;
+  }
+};
+function estimateMaxModelCalls(tests, maxIterationsPerStep, maxRetriesPerStep) {
+  const totalSteps = tests.reduce(
+    (sum, test) => sum + (test.setup?.length ?? 0) + test.steps.length,
+    0
+  );
+  return totalSteps * (maxIterationsPerStep + maxRetriesPerStep);
+}
+
 // src/runner/env.ts
 var ENV_PLACEHOLDER = /\{\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
 var MissingEnvError = class extends Error {
@@ -307,7 +397,7 @@ async function performAction(page, action, ctx) {
       const value = resolve(requireValue(action), ctx);
       const url = new URL(value, ctx.baseUrl);
       assertAllowedOrigin(url, ctx);
-      await page.goto(url.toString(), { timeout: 3e4 });
+      await page.goto(url.toString(), { timeout: ctx.resolveTimeoutMs ?? 3e4 });
       return `ok: navigated to ${url.toString()}`;
     }
     case "click": {
@@ -348,9 +438,10 @@ async function performAction(page, action, ctx) {
 }
 
 // src/runner/executor.ts
-async function defaultSnapshot(page) {
+var DEFAULT_MAX_ITERATIONS_PER_STEP = 15;
+async function defaultSnapshot(page, maxLines) {
   const { captureSnapshot } = await import("./snapshot-CAIB2OHX.js");
-  return captureSnapshot(page);
+  return captureSnapshot(page, { maxLines });
 }
 function slugify(text) {
   const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
@@ -366,12 +457,15 @@ async function executeTest(page, test, options) {
     allowedOrigins,
     resolveValue,
     maxRetries = 3,
-    maxIterationsPerStep = 15,
+    maxIterationsPerStep = DEFAULT_MAX_ITERATIONS_PER_STEP,
+    timeoutMs,
     mask = (s) => s,
-    snapshot = defaultSnapshot,
+    snapshot,
+    maxSnapshotLines,
     onEvent = () => {
     }
   } = options;
+  const takeSnapshot = snapshot ?? ((page2) => defaultSnapshot(page2, maxSnapshotLines));
   const startedAt = Date.now();
   const stepResults = [];
   const allSteps = [
@@ -402,7 +496,7 @@ async function executeTest(page, test, options) {
         if (iterations >= maxIterationsPerStep) {
           throw new StepFailure(`step exceeded ${maxIterationsPerStep} actions without completing`);
         }
-        const snap = await snapshot(page);
+        const snap = await takeSnapshot(page);
         let action;
         try {
           action = await brain.nextAction({
@@ -414,6 +508,7 @@ async function executeTest(page, test, options) {
             iterationsLeft: maxIterationsPerStep - iterations
           });
         } catch (error) {
+          if (error instanceof BudgetExhaustedError) throw error;
           failedAttempts++;
           lastResult = `error: ${error instanceof Error ? error.message : String(error)}`;
           if (failedAttempts >= maxRetries) {
@@ -437,7 +532,7 @@ async function executeTest(page, test, options) {
           emitAction(index, action, result);
           if (judgment.pass) {
             lastResult = result;
-            continue;
+            break;
           }
           failedAttempts++;
           lastResult = result;
@@ -447,7 +542,12 @@ async function executeTest(page, test, options) {
           continue;
         }
         try {
-          const result = await performAction(page, action, { baseUrl, allowedOrigins, resolveValue });
+          const result = await performAction(page, action, {
+            baseUrl,
+            allowedOrigins,
+            resolveValue,
+            resolveTimeoutMs: timeoutMs
+          });
           lastResult = result;
           emitAction(index, action, result);
         } catch (error) {
@@ -460,6 +560,7 @@ async function executeTest(page, test, options) {
         }
       }
     } catch (error) {
+      if (error instanceof BudgetExhaustedError) throw error;
       stepFailedReason = mask(error instanceof Error ? error.message : String(error));
     }
     const status = stepFailedReason ? "failed" : "passed";
@@ -560,14 +661,16 @@ async function runJourney(...args) {
   try {
     return await executeTest(...args);
   } catch (error) {
+    if (error instanceof BudgetExhaustedError) throw error;
     throw new AuthError(
       `Authentication could not run: ${error instanceof Error ? error.message : String(error)}`
     );
   }
 }
 async function fromSteps(options) {
-  const { auth, baseUrl, browser, brain, maxRetries, snapshot = defaultSnapshot, onEvent, mask } = options;
+  const { auth, baseUrl, browser, brain, maxRetries, snapshot, timeoutMs, maxSnapshotLines, onEvent, mask } = options;
   const steps = auth.steps;
+  const takeSnapshot = snapshot ?? ((page) => defaultSnapshot(page, maxSnapshotLines));
   const context = await browser.newContext();
   try {
     const page = await context.newPage();
@@ -589,8 +692,9 @@ async function fromSteps(options) {
         allowedOrigins: options.allowedOrigins,
         resolveValue: (value) => substituteEnv(value),
         maxRetries,
+        timeoutMs,
         mask: (text) => mask.mask(text),
-        snapshot,
+        snapshot: takeSnapshot,
         onEvent
       }
     );
@@ -600,7 +704,7 @@ async function fromSteps(options) {
       );
     }
     if (auth.verify) {
-      const judgment = await brain.judge(auth.verify, mask.mask(await snapshot(page)));
+      const judgment = await brain.judge(auth.verify, mask.mask(await takeSnapshot(page)));
       if (!judgment.pass) {
         throw new AuthError(`Authentication could not be verified: ${mask.mask(judgment.reason)}`);
       }
@@ -661,7 +765,25 @@ var llmSchema = z.object({
 });
 var browserSchema = z.object({
   headless: z.boolean().default(true),
-  timeout_ms: z.number().int().positive().default(3e4)
+  /**
+   * Bounds every wait: resolving a target element on the accessibility tree, and
+   * navigating. An explicit per-call Playwright timeout always overrides
+   * `page.setDefaultTimeout()`, so this must be threaded through the action
+   * context rather than relied on ambiently (design D2, runner/actions.ts).
+   */
+  timeout_ms: z.number().int().positive().default(3e4),
+  /**
+   * Caps accessibility-tree lines sent to the model per snapshot. Optional:
+   * undefined lets `runner/snapshot.ts`'s own default (200) apply, so a config
+   * that never mentions this behaves exactly as before it existed.
+   */
+  max_snapshot_lines: z.number().int().positive().optional()
+});
+var budgetSchema = z.object({
+  max_llm_calls: z.coerce.number().int().positive().optional(),
+  max_tokens: z.coerce.number().int().positive().optional(),
+  /** Seconds, not milliseconds, to match how a human would set a deadline. */
+  max_duration_s: z.coerce.number().positive().optional()
 });
 var cookieSchema = z.object({
   name: z.string().min(1),
@@ -712,14 +834,18 @@ var configSchema = z.object({
    */
   allowed_origins: z.array(z.string().url()).optional(),
   auth: authSchema.optional(),
-  max_retries_per_step: z.number().int().min(1).default(3)
+  max_retries_per_step: z.number().int().min(1).default(3),
+  budget: budgetSchema.optional()
 });
 var ENV_OVERRIDES = {
   BLASTPROOF_BASE_URL: ["base_url"],
   BLASTPROOF_LLM_PROVIDER: ["llm", "provider"],
   BLASTPROOF_LLM_MODEL: ["llm", "model"],
   BLASTPROOF_LLM_BASE_URL: ["llm", "base_url"],
-  BLASTPROOF_LLM_API_KEY_ENV: ["llm", "api_key_env"]
+  BLASTPROOF_LLM_API_KEY_ENV: ["llm", "api_key_env"],
+  BLASTPROOF_MAX_LLM_CALLS: ["budget", "max_llm_calls"],
+  BLASTPROOF_MAX_TOKENS: ["budget", "max_tokens"],
+  BLASTPROOF_MAX_DURATION_S: ["budget", "max_duration_s"]
 };
 function applyEnvOverrides(data, env = process.env) {
   const merged = data && typeof data === "object" ? { ...data } : {};
@@ -750,6 +876,37 @@ var ConfigError = class extends Error {
 function formatIssues(error) {
   return error.issues.map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
 }
+function unwrapToObjectSchema(schema) {
+  let current = schema;
+  for (; ; ) {
+    if (current instanceof z.ZodOptional || current instanceof z.ZodNullable) {
+      current = current.unwrap();
+    } else if (current instanceof z.ZodDefault) {
+      current = current.removeDefault();
+    } else if (current instanceof z.ZodEffects) {
+      current = current.innerType();
+    } else {
+      break;
+    }
+  }
+  return current instanceof z.ZodObject ? current : void 0;
+}
+function findUnknownConfigKeys(data, schema = configSchema, path11 = []) {
+  const object = unwrapToObjectSchema(schema);
+  if (!object || data === null || typeof data !== "object" || Array.isArray(data)) return [];
+  const shape = object.shape;
+  const warnings = [];
+  for (const key of Object.keys(data)) {
+    const fieldPath = [...path11, key];
+    const fieldSchema = shape[key];
+    if (!fieldSchema) {
+      warnings.push(fieldPath.join("."));
+      continue;
+    }
+    warnings.push(...findUnknownConfigKeys(data[key], fieldSchema, fieldPath));
+  }
+  return warnings;
+}
 async function loadConfig(cwd = process.cwd(), env = process.env) {
   const configPath = path4.join(cwd, CONFIG_RELATIVE_PATH);
   let raw;
@@ -769,12 +926,17 @@ async function loadConfig(cwd = process.cwd(), env = process.env) {
     );
   }
   const { data: merged, applied } = applyEnvOverrides(data ?? {}, env);
+  const source = applied.length > 0 ? `${CONFIG_RELATIVE_PATH} (with overrides from ${applied.join(", ")})` : CONFIG_RELATIVE_PATH;
   const result = configSchema.safeParse(merged);
   if (!result.success) {
-    const source = applied.length > 0 ? `${CONFIG_RELATIVE_PATH} (with overrides from ${applied.join(", ")})` : CONFIG_RELATIVE_PATH;
     throw new ConfigError(`Invalid ${source}:
 ${formatIssues(result.error)}`);
   }
+  for (const key of findUnknownConfigKeys(merged)) {
+    console.warn(
+      `warning: unknown config key '${key}' in ${source} \u2014 this version of blastproof does not recognise it, so it has no effect.`
+    );
+  }
   return result.data;
 }
 
@@ -967,10 +1129,16 @@ var MalformedModelOutputError = class extends Error {
     this.name = "MalformedModelOutputError";
   }
 };
-function createBrain(model, generate = generateObject) {
+async function countedGenerate(generate, budget, options) {
+  budget.check();
+  const result = await generate(options);
+  budget.record(result.usage);
+  return result;
+}
+function createBrain(model, generate = generateObject, budget) {
   return {
     async nextAction(input) {
-      const result = await generate({
+      const result = await countedGenerate(generate, budget, {
         model,
         schema: agentActionSchema,
         system: agentSystemPrompt(),
@@ -985,7 +1153,7 @@ function createBrain(model, generate = generateObject) {
       return parsed.data;
     },
     async judge(expectation, snapshot) {
-      const result = await generate({
+      const result = await countedGenerate(generate, budget, {
         model,
         schema: assertJudgmentSchema,
         system: assertSystemPrompt(),
@@ -1001,10 +1169,10 @@ function createBrain(model, generate = generateObject) {
     }
   };
 }
-function createPlanner(model, generate = generateObject) {
+function createPlanner(model, generate = generateObject, budget) {
   return {
     async planTest(input) {
-      const result = await generate({
+      const result = await countedGenerate(generate, budget, {
         model,
         schema: generatedTestSchema,
         system: plannerSystemPrompt(),
@@ -1177,10 +1345,11 @@ function renderTestYaml(draft, meta) {
   });
 }
 async function generateForRoute(page, options) {
-  const { route, baseUrl, changedFiles, brain, mask, snapshot = defaultSnapshot } = options;
+  const { route, baseUrl, changedFiles, brain, mask, snapshot, maxSnapshotLines, timeoutMs } = options;
+  const takeSnapshot = snapshot ?? ((p) => defaultSnapshot(p, maxSnapshotLines));
   const url = new URL(route, baseUrl).toString();
   try {
-    await page.goto(url, { timeout: 3e4 });
+    await page.goto(url, { timeout: timeoutMs });
   } catch (error) {
     throw new PlannerError(
       `Cannot load ${url}: ${error instanceof Error ? error.message : String(error)}`
@@ -1188,7 +1357,7 @@ async function generateForRoute(page, options) {
   }
   const generated = await brain.planTest({
     route,
-    snapshot: mask(await snapshot(page)),
+    snapshot: mask(await takeSnapshot(page)),
     changedFiles
   });
   const leaked = findSecretLiterals(generated.steps);
@@ -1217,9 +1386,120 @@ function coveredRoutes(tests) {
   return new Set(tests.flatMap((test) => test.routes));
 }
 
+// src/runner/browser.ts
+import { chromium } from "playwright";
+var BrowserLaunchError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BrowserLaunchError";
+  }
+};
+var MISSING_LIBRARY_PATTERN = /([^\s:]+\.so(?:\.\d+)*): cannot open shared object file/;
+var MISSING_EXECUTABLE_PATTERN = /executable doesn't exist/i;
+function stripCommandLine(message) {
+  return message.split("\n").filter((line) => (line.match(/\s--[\w-]+/g)?.length ?? 0) < 3).join("\n").trim();
+}
+async function launchBrowser(options) {
+  try {
+    return await chromium.launch(options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (MISSING_EXECUTABLE_PATTERN.test(message)) {
+      throw new BrowserLaunchError(
+        "The browser is not installed. Run `npx playwright install chromium` to download it."
+      );
+    }
+    const missingLibrary = message.match(MISSING_LIBRARY_PATTERN);
+    if (missingLibrary) {
+      throw new BrowserLaunchError(
+        `The browser could not start because a system library is missing: ${missingLibrary[1]}. Run \`npx playwright install-deps chromium\` to install it \u2014 this needs root/administrator privileges (sudo, or an elevated shell on Windows). Without them, blastproof run --dry-run and blastproof plan --dry-run need neither a browser nor a key.`
+      );
+    }
+    throw new BrowserLaunchError(stripCommandLine(message));
+  }
+}
+
+// src/preflight.ts
+var REACHABILITY_TIMEOUT_MS = 15e3;
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function isTimeout(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+async function probe(url, fetchImpl) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REACHABILITY_TIMEOUT_MS);
+  try {
+    await fetchImpl(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function providerBaseUrl(llm) {
+  if (llm.base_url) return llm.base_url;
+  switch (llm.provider) {
+    case "anthropic":
+      return "https://api.anthropic.com";
+    case "openai":
+      return "https://api.openai.com";
+    case "ollama":
+      return DEFAULT_OLLAMA_BASE_URL;
+  }
+}
+async function checkModel(llm, fetchImpl) {
+  const url = providerBaseUrl(llm);
+  try {
+    await probe(url, fetchImpl);
+    return void 0;
+  } catch (error) {
+    if (isTimeout(error)) {
+      return `Cannot reach the ${llm.provider} provider at ${url}: it did not respond within ${REACHABILITY_TIMEOUT_MS / 1e3}s. It may be temporarily slow or overloaded rather than down \u2014 try again in a moment, or check llm.base_url in .blastproof/config.yaml.`;
+    }
+    return `Cannot reach the ${llm.provider} provider at ${url} (${messageOf(error)}). Check your network connection` + (llm.provider === "ollama" ? ", that Ollama is running (`ollama serve`)," : "") + " or llm.base_url in .blastproof/config.yaml.";
+  }
+}
+async function checkBaseUrl(baseUrl, fetchImpl) {
+  try {
+    await probe(baseUrl, fetchImpl);
+    return void 0;
+  } catch (error) {
+    if (isTimeout(error)) {
+      return `The application at ${baseUrl} did not respond within ${REACHABILITY_TIMEOUT_MS / 1e3}s. It may still be starting (a dev server compiling a route on first request, a cold-starting container) rather than down \u2014 try again in a moment.`;
+    }
+    return `The application at ${baseUrl} is not responding (${messageOf(error)}). Start it, or point --url / base_url in .blastproof/config.yaml at the right address.`;
+  }
+}
+async function checkBrowser(headless) {
+  try {
+    const browser = await launchBrowser({ headless });
+    return { browser };
+  } catch (error) {
+    return { failure: error instanceof BrowserLaunchError ? error.message : messageOf(error) };
+  }
+}
+async function runPreflight(needs, config, fetchImpl = fetch) {
+  const [browserResult, modelFailure, baseUrlFailure] = await Promise.all([
+    needs.browser ? checkBrowser(config.browser.headless) : Promise.resolve({}),
+    needs.model ? checkModel(config.llm, fetchImpl) : Promise.resolve(void 0),
+    needs.baseUrl ? checkBaseUrl(config.base_url, fetchImpl) : Promise.resolve(void 0)
+  ]);
+  const failures = [browserResult.failure, modelFailure, baseUrlFailure].filter(
+    (value) => value !== void 0
+  );
+  if (failures.length > 0) {
+    if (browserResult.browser) await browserResult.browser.close();
+    return { ok: false, failures };
+  }
+  return { ok: true, browser: browserResult.browser };
+}
+function printPreflightFailures(failures) {
+  console.error(`error: ${failures.length} unmet prerequisite(s):`);
+  for (const failure of failures) console.error(`  - ${failure}`);
+}
+
 // src/commands/run.ts
 import path9 from "path";
-import { chromium } from "playwright";
 
 // src/report/html.ts
 import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
@@ -1262,6 +1542,8 @@ h1 { font-size:1.35rem; margin:0 0 .25rem; }
 .verdict { font-weight:600; }
 .verdict.pass { color:var(--pass); } .verdict.fail { color:var(--fail); }
 .counts { color:var(--muted); font-size:.9rem; }
+.incomplete { padding:1rem 1.25rem; border:1px solid var(--fail); border-radius:10px;
+  background:color-mix(in srgb, var(--fail) 10%, transparent); margin-bottom:1.5rem; font-weight:600; }
 table { width:100%; border-collapse:collapse; margin-bottom:1.5rem; }
 th, td { text-align:left; padding:.5rem .6rem; border-bottom:1px solid var(--line);
   font-size:.9rem; vertical-align:top; }
@@ -1298,10 +1580,13 @@ function renderSteps(steps) {
 }
 async function renderTest(result, cwd) {
   const failed = result.status === "failed";
+  const notRun = result.status === "not-run";
+  const tagClass = failed ? "fail" : notRun ? "skip" : "pass";
+  const label = failed ? "FAIL" : notRun ? "NOT RUN" : "PASS";
   const file = cwd ? path7.relative(cwd, result.file) : result.file;
   const parts = [
-    `    <details${failed ? " open" : ""}>`,
-    `      <summary><span class="tag ${failed ? "fail" : "pass"}">${failed ? "FAIL" : "PASS"}</span> ${escapeHtml(result.summary)} <span class="note">${escapeHtml(result.priority)} \xB7 ${escapeHtml(file)}</span></summary>`
+    `    <details${failed || notRun ? " open" : ""}>`,
+    `      <summary><span class="tag ${tagClass}">${label}</span> ${escapeHtml(result.summary)} <span class="note">${escapeHtml(result.priority)} \xB7 ${escapeHtml(file)}</span></summary>`
   ];
   if (failed) {
     if (result.failedStep) {
@@ -1311,6 +1596,9 @@ async function renderTest(result, cwd) {
       parts.push(`      <p class="reason">${escapeHtml(result.reason)}</p>`);
     }
   }
+  if (notRun && result.reason) {
+    parts.push(`      <p class="note">${escapeHtml(result.reason)}</p>`);
+  }
   parts.push(`      ${renderSteps(result.steps)}`);
   if (failed && result.screenshot) {
     const embedded = await embedScreenshot(result.screenshot);
@@ -1324,13 +1612,20 @@ async function renderTest(result, cwd) {
 async function renderHtml(results, skipped, meta) {
   const passed = results.filter((r) => r.status === "passed").length;
   const failures = results.filter((r) => r.status === "failed");
+  const notRun = results.filter((r) => r.status === "not-run");
   const generatedAt = (meta.generatedAt ?? /* @__PURE__ */ new Date()).toISOString();
-  const ordered = [...failures, ...results.filter((r) => r.status === "passed")];
+  const ordered = [...failures, ...notRun, ...results.filter((r) => r.status === "passed")];
   const detail = (await Promise.all(ordered.map((r) => renderTest(r, meta.cwd)))).join("\n");
   const verdict = meta.minScore === void 0 ? "" : meta.score >= meta.minScore ? `<span class="verdict pass">min-score ${meta.minScore}: pass</span>` : `<span class="verdict fail">min-score ${meta.minScore}: FAIL</span>`;
+  const banner = meta.incomplete === void 0 ? "" : `  <section class="incomplete">Run stopped: ${escapeHtml(meta.incomplete)}</section>
+
+`;
   const rows = results.map((r) => {
     const file = meta.cwd ? path7.relative(meta.cwd, r.file) : r.file;
-    return `      <tr><td><span class="tag ${r.status === "failed" ? "fail" : "pass"}">${r.status === "failed" ? "FAIL" : "PASS"}</span></td><td>${escapeHtml(r.priority)}</td><td>${escapeHtml(r.summary)}</td><td>${escapeHtml(file)}</td><td class="num">${seconds(r.durationMs)}</td></tr>`;
+    const tagClass = r.status === "failed" ? "fail" : r.status === "not-run" ? "skip" : "pass";
+    const label = r.status === "failed" ? "FAIL" : r.status === "not-run" ? "NOT RUN" : "PASS";
+    const time = r.status === "not-run" ? "\u2014" : seconds(r.durationMs);
+    return `      <tr><td><span class="tag ${tagClass}">${label}</span></td><td>${escapeHtml(r.priority)}</td><td>${escapeHtml(r.summary)}</td><td>${escapeHtml(file)}</td><td class="num">${time}</td></tr>`;
   }).join("\n");
   const skippedRows = skipped.map((s) => {
     const file = meta.cwd ? path7.relative(meta.cwd, s.path) : s.path;
@@ -1349,10 +1644,10 @@ async function renderHtml(results, skipped, meta) {
   <h1>blastproof report</h1>
   <p class="sub">${escapeHtml(generatedAt)} \xB7 ${seconds(meta.durationMs)}</p>
 
-  <section class="score">
+${banner}  <section class="score">
     <b>${meta.score}</b>
     ${verdict}
-    <span class="counts">${passed} passed \xB7 ${failures.length} failed${skipped.length > 0 ? ` \xB7 ${skipped.length} skipped` : ""}</span>
+    <span class="counts">${passed} passed \xB7 ${failures.length} failed${notRun.length > 0 ? ` \xB7 ${notRun.length} not run` : ""}${skipped.length > 0 ? ` \xB7 ${skipped.length} skipped` : ""}</span>
   </section>
 
   <table>
@@ -1395,14 +1690,27 @@ function seconds2(ms) {
 function renderJUnit(results, skipped, meta) {
   const relative = (file) => meta.cwd ? path8.relative(meta.cwd, file) : file;
   const failures = results.filter((result) => result.status === "failed").length;
+  const notRun = results.filter((result) => result.status === "not-run");
   const lines = [
     '<?xml version="1.0" encoding="UTF-8"?>',
-    `<testsuite name="blastproof" tests="${results.length + skipped.length}" failures="${failures}" skipped="${skipped.length}" time="${seconds2(meta.durationMs)}">`,
+    `<testsuite name="blastproof" tests="${results.length + skipped.length}" failures="${failures}" skipped="${skipped.length + notRun.length}" time="${seconds2(meta.durationMs)}">`,
     "  <properties>",
     `    <property name="score" value="${meta.score}"/>`,
+    ...meta.incomplete !== void 0 ? [
+      '    <property name="incomplete" value="true"/>',
+      `    <property name="incomplete_reason" value="${escapeXml(meta.incomplete)}"/>`
+    ] : [],
     "  </properties>"
   ];
   for (const result of results) {
+    if (result.status === "not-run") {
+      lines.push(
+        `  <testcase classname="${escapeXml(relative(result.file))}" name="${escapeXml(result.summary)}" time="0.000">`,
+        `    <skipped message="${escapeXml(result.reason ?? "not run: the run stopped before this test executed")}"/>`,
+        "  </testcase>"
+      );
+      continue;
+    }
     const open = `  <testcase classname="${escapeXml(relative(result.file))}" name="${escapeXml(result.summary)}" time="${seconds2(result.durationMs)}"`;
     if (result.status === "passed") {
       lines.push(`${open}/>`);
@@ -1438,6 +1746,7 @@ function computeScore(results) {
   let total = 0;
   let passed = 0;
   for (const result of results) {
+    if (result.status === "not-run") continue;
     const weight = WEIGHTS[result.priority] ?? DEFAULT_WEIGHT;
     total += weight;
     if (result.status === "passed") passed += weight;
@@ -1453,6 +1762,10 @@ function formatScoreLine(score, results, threshold) {
   if (threshold === void 0) return `Score: ${score}`;
   return score >= threshold ? `Score: ${score} \u2014 min-score ${threshold}: pass` : `Score: ${score} \u2014 min-score ${threshold}: FAIL (below threshold)`;
 }
+function formatIncompleteLine(score, reason) {
+  return `Run incomplete: ${reason}
+Score over executed tests: ${score} (not a verdict \u2014 exit code 1 regardless of --min-score)`;
+}
 
 // src/runner/selection.ts
 function matchesFilters(test, filters) {
@@ -1492,6 +1805,14 @@ function selectImpactedTests(tests, affectedRoutes, filters = { tags: [] }) {
 var EXIT_OK = 0;
 var EXIT_FAILED = 1;
 var EXIT_USAGE = 2;
+function resolveBudgetOptions(config, options) {
+  const maxDurationSeconds = options.maxDuration ?? config.budget?.max_duration_s;
+  return {
+    maxCalls: options.maxLlmCalls ?? config.budget?.max_llm_calls,
+    maxTokens: options.maxTokens ?? config.budget?.max_tokens,
+    maxDurationMs: maxDurationSeconds === void 0 ? void 0 : maxDurationSeconds * 1e3
+  };
+}
 function sessionId() {
   return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 }
@@ -1522,6 +1843,18 @@ function resolveSecretsAndSteps(test) {
   }
   return { test };
 }
+function notRunResults(tests, reason) {
+  return tests.map((test) => ({
+    file: test.path,
+    summary: test.summary,
+    priority: test.priority,
+    tags: test.tags,
+    status: "not-run",
+    steps: [],
+    reason,
+    durationMs: 0
+  }));
+}
 function printEvent(event) {
   switch (event.type) {
     case "step-start":
@@ -1541,12 +1874,18 @@ function printEvent(event) {
       break;
   }
 }
+function statusLabel(status) {
+  if (status === "passed") return "PASS";
+  if (status === "failed") return "FAIL";
+  return "NOT RUN";
+}
 function printSummary(results) {
   const passed = results.filter((r) => r.status === "passed");
   const failed = results.filter((r) => r.status === "failed");
+  const notRun = results.filter((r) => r.status === "not-run");
   console.log("\n--- Summary ---------------------------------------------------");
   const rows = results.map((r) => ({
-    status: r.status === "passed" ? "PASS" : "FAIL",
+    status: statusLabel(r.status),
     priority: r.priority,
     summary: r.summary,
     duration: `${(r.durationMs / 1e3).toFixed(1)}s`
@@ -1559,7 +1898,9 @@ function printSummary(results) {
     );
   }
   console.log("---------------------------------------------------------------");
-  console.log(`${passed.length} passed, ${failed.length} failed, ${results.length} total`);
+  console.log(
+    notRun.length > 0 ? `${passed.length} passed, ${failed.length} failed, ${notRun.length} not run, ${results.length} total` : `${passed.length} passed, ${failed.length} failed, ${results.length} total`
+  );
   for (const r of failed) {
     console.log(`
 X ${r.summary} (${r.file})`);
@@ -1567,9 +1908,14 @@ X ${r.summary} (${r.file})`);
     if (r.reason) console.log(`  reason: ${r.reason}`);
     if (r.screenshot) console.log(`  screenshot: ${r.screenshot}`);
   }
+  if (notRun.length > 0) {
+    console.log(`
+${notRun.length} test(s) not run (run stopped by its budget or deadline):`);
+    for (const r of notRun) console.log(`  - ${r.summary} (${r.file})`);
+  }
 }
-async function runOne(browser, test, config, sessionDir, session, runMask) {
-  const brain = createBrain(createModel(config.llm).model);
+async function runOne(browser, test, config, sessionDir, session, runMask, budget) {
+  const brain = createBrain(createModel(config.llm).model, void 0, budget);
   let resolved;
   const mask = runMask;
   try {
@@ -1600,6 +1946,8 @@ async function runOne(browser, test, config, sessionDir, session, runMask) {
       allowedOrigins: config.allowed_origins,
       resolveValue: (value) => substituteEnv(value),
       maxRetries: config.max_retries_per_step,
+      timeoutMs: config.browser.timeout_ms,
+      maxSnapshotLines: config.browser.max_snapshot_lines,
       mask: (text) => mask.mask(text),
       onEvent: printEvent
     });
@@ -1632,13 +1980,20 @@ function printImpactReport(impact, selection, cwd) {
   }
   console.log("---------------------------------------------------------------");
 }
-async function finalize(results, skipped, options, sessionDir, durationMs, impact) {
+async function finalize(results, skipped, options, sessionDir, durationMs, impact, incomplete) {
   if (results.length > 0) printSummary(results);
   const score = computeScore(results);
-  console.log(formatScoreLine(score, results, options.minScore));
+  console.log(
+    incomplete ? formatIncompleteLine(score, incomplete.message) : formatScoreLine(score, results, options.minScore)
+  );
   if (options.junit) {
     const target = typeof options.junit === "string" ? path9.resolve(options.cwd, options.junit) : path9.join(sessionDir, "junit.xml");
-    const xml = renderJUnit(results, skipped, { score, durationMs, cwd: options.cwd });
+    const xml = renderJUnit(results, skipped, {
+      score,
+      durationMs,
+      cwd: options.cwd,
+      incomplete: incomplete?.message
+    });
     await writeJUnit(target, xml);
     console.log(`JUnit report: ${path9.relative(options.cwd, target)}`);
   }
@@ -1648,11 +2003,13 @@ async function finalize(results, skipped, options, sessionDir, durationMs, impac
       score,
       durationMs,
       minScore: options.minScore,
-      cwd: options.cwd
+      cwd: options.cwd,
+      incomplete: incomplete?.message
     });
     await writeHtml(target, html);
     console.log(`HTML report: ${path9.relative(options.cwd, target)}`);
   }
+  if (incomplete) return EXIT_FAILED;
   if (reportUnclassified(options, impact)) return EXIT_FAILED;
   if (options.minScore !== void 0) {
     return score >= options.minScore ? EXIT_OK : EXIT_FAILED;
@@ -1671,12 +2028,23 @@ function reportUnclassified(options, impact) {
   );
   return true;
 }
-function printDryRun(selected, baseUrl, cwd) {
+function printDryRun(selected, config, cwd) {
   console.log(`
-Dry run: ${selected.length} test(s) selected, base_url=${baseUrl}`);
+Dry run: ${selected.length} test(s) selected, base_url=${config.base_url}`);
   for (const test of selected) {
     console.log(`  ${test.summary} [${test.priority}] (${path9.relative(cwd, test.path)})`);
   }
+  const authSteps = config.auth?.steps ?? [];
+  const withAuth = authSteps.length > 0 ? [...selected, { steps: authSteps }] : selected;
+  const ceiling = estimateMaxModelCalls(
+    withAuth,
+    DEFAULT_MAX_ITERATIONS_PER_STEP,
+    config.max_retries_per_step
+  );
+  const authNote = authSteps.length > 0 ? ", including the login journey" : "";
+  console.log(
+    `Worst case: up to ${ceiling} model call(s) for this selection${authNote} (a maximum, not a prediction).`
+  );
   console.log("Dry run: no browser launched, no LLM calls made.");
 }
 async function runCommand(options) {
@@ -1752,7 +2120,7 @@ async function runCommand(options) {
     printImpactReport(impact, selection, options.cwd);
   }
   if (options.dryRun) {
-    printDryRun(selected, config.base_url, options.cwd);
+    printDryRun(selected, config, options.cwd);
     if (results.length > 0) {
       console.error(`
 ${results.length} test file(s) could not be parsed:`);
@@ -1783,7 +2151,14 @@ ${results.length} test file(s) could not be parsed:`);
     `blastproof run: ${selected.length} test(s), provider=${provider} model=${modelId}, base_url=${config.base_url}`
   );
   const runMask = buildRunMask(config, parsed);
-  const browser = await chromium.launch({ headless: config.browser.headless });
+  const budget = options.budget ?? new RunBudget(resolveBudgetOptions(config, options));
+  const preflight = await runPreflight({ browser: true, model: true, baseUrl: true }, config);
+  if (!preflight.ok) {
+    printPreflightFailures(preflight.failures);
+    return EXIT_USAGE;
+  }
+  const browser = preflight.browser;
+  let incomplete;
   try {
     let session;
     if (config.auth) {
@@ -1795,28 +2170,56 @@ ${results.length} test file(s) could not be parsed:`);
           baseUrl: config.base_url,
           allowedOrigins: config.allowed_origins,
           browser,
-          brain: createBrain(createModel(config.llm).model),
+          brain: createBrain(createModel(config.llm).model, void 0, budget),
           maxRetries: config.max_retries_per_step,
+          timeoutMs: config.browser.timeout_ms,
+          maxSnapshotLines: config.browser.max_snapshot_lines,
           mask: runMask,
           onEvent: printEvent
         });
       } catch (error) {
-        if (error instanceof AuthError) {
+        if (error instanceof BudgetExhaustedError) {
+          incomplete = error;
+        } else if (error instanceof AuthError) {
           console.error(`error: ${error.message}`);
           return EXIT_USAGE;
+        } else {
+          throw error;
         }
-        throw error;
       }
     }
-    for (const test of selected) {
-      console.log(`
+    if (incomplete) {
+      results.push(...notRunResults(selected, incomplete.message));
+    } else {
+      for (let i = 0; i < selected.length; i++) {
+        const test = selected[i];
+        console.log(`
 > ${test.summary} [${test.priority}] (${path9.relative(options.cwd, test.path)})`);
-      results.push(await runOne(browser, test, config, sessionDir, session, runMask));
+        try {
+          budget.check();
+          results.push(await runOne(browser, test, config, sessionDir, session, runMask, budget));
+        } catch (error) {
+          if (error instanceof BudgetExhaustedError) {
+            incomplete = error;
+            results.push(...notRunResults(selected.slice(i), error.message));
+            break;
+          }
+          throw error;
+        }
+      }
     }
   } finally {
     await browser.close();
   }
-  return finalize(results, selection.unroutedSkipped, options, sessionDir, Date.now() - startedAt, impact);
+  return finalize(
+    results,
+    selection.unroutedSkipped,
+    options,
+    sessionDir,
+    Date.now() - startedAt,
+    impact,
+    incomplete
+  );
 }
 
 // src/commands/plan.ts
@@ -1897,6 +2300,16 @@ async function planCommand(options) {
     console.log("Already covered (skipped):");
     for (const route of alreadyCovered) console.log(`  ${route}`);
   }
+  if (options.dryRun) {
+    if (work.length === 0) {
+      console.log("Nothing to generate: no affected route is missing coverage.");
+    } else {
+      console.log(`Dry run: ${work.length} route(s) would generate a draft for:`);
+      for (const { route } of work) console.log(`  ${route}`);
+    }
+    console.log("Dry run: no browser launched, no LLM calls made.");
+    return EXIT_OK;
+  }
   if (work.length === 0) {
     console.log("Nothing to generate: no affected route is missing coverage.");
     return EXIT_OK;
@@ -1911,7 +2324,8 @@ async function planCommand(options) {
     throw error;
   }
   const { model, provider, modelId } = createModel(config.llm);
-  const brain = createPlanner(model);
+  const budget = options.budget ?? new RunBudget(resolveBudgetOptions(config, options));
+  const brain = createPlanner(model, void 0, budget);
   const base = options.routes && options.routes.length > 0 ? void 0 : options.base ?? "main";
   console.log(
     `blastproof plan: ${work.length} route(s), provider=${provider} model=${modelId}, base_url=${config.base_url}`
@@ -1926,7 +2340,13 @@ async function planCommand(options) {
   const generated = [];
   const written = [];
   const failed = [];
-  const browser = await chromium2.launch({ headless: config.browser.headless });
+  let incomplete;
+  const preflight = await runPreflight({ browser: true, model: true, baseUrl: true }, config);
+  if (!preflight.ok) {
+    printPreflightFailures(preflight.failures);
+    return EXIT_USAGE;
+  }
+  const browser = preflight.browser;
   try {
     let session;
     if (config.auth) {
@@ -1938,20 +2358,25 @@ async function planCommand(options) {
           baseUrl: config.base_url,
           allowedOrigins: config.allowed_origins,
           browser,
-          brain: createBrain(createModel(config.llm).model),
+          brain: createBrain(createModel(config.llm).model, void 0, budget),
           maxRetries: config.max_retries_per_step,
+          timeoutMs: config.browser.timeout_ms,
+          maxSnapshotLines: config.browser.max_snapshot_lines,
           mask,
           onEvent: printAuthEvent
         });
       } catch (error) {
-        if (error instanceof AuthError) {
+        if (error instanceof BudgetExhaustedError) {
+          incomplete = error;
+        } else if (error instanceof AuthError) {
           console.error(`error: ${error.message}`);
           return EXIT_USAGE;
+        } else {
+          throw error;
         }
-        throw error;
       }
     }
-    for (const { route, changedFiles } of work) {
+    for (const { route, changedFiles } of incomplete ? [] : work) {
       console.log(`
 > ${route}`);
       let draft;
@@ -1964,9 +2389,15 @@ async function planCommand(options) {
           baseUrl: config.base_url,
           changedFiles,
           brain,
-          mask: (text) => mask.mask(text)
+          mask: (text) => mask.mask(text),
+          maxSnapshotLines: config.browser.max_snapshot_lines,
+          timeoutMs: config.browser.timeout_ms
         });
       } catch (error) {
+        if (error instanceof BudgetExhaustedError) {
+          incomplete = error;
+          break;
+        }
         failed.push({ route, reason: error instanceof Error ? error.message : String(error) });
         console.log(`  X failed: ${error instanceof Error ? error.message : String(error)}`);
         continue;
@@ -1996,6 +2427,7 @@ ${renderTestYaml(draft, { route, base })}`);
   } finally {
     await browser.close();
   }
+  const notAttempted = incomplete ? work.map((item) => item.route).filter((route) => !generated.includes(route) && !failed.some((f) => f.route === route)) : [];
   console.log("\n--- Plan -------------------------------------------------------");
   console.log(`Generated: ${generated.length > 0 ? generated.join(", ") : "none"}`);
   if (written.length > 0) {
@@ -2009,8 +2441,15 @@ ${renderTestYaml(draft, { route, base })}`);
     console.log("Failed:");
     for (const { route, reason } of failed) console.log(`  ${route}: ${reason}`);
   }
+  if (incomplete) {
+    console.log(`Stopped: ${incomplete.message}`);
+    if (notAttempted.length > 0) {
+      console.log("Not attempted (run out of budget):");
+      for (const route of notAttempted) console.log(`  ${route}`);
+    }
+  }
   console.log("---------------------------------------------------------------");
-  return failed.length > 0 ? EXIT_FAILED : EXIT_OK;
+  return incomplete || failed.length > 0 ? EXIT_FAILED : EXIT_OK;
 }
 
 // src/commands/test.ts
@@ -2019,6 +2458,17 @@ function section(title) {
 === ${title} ${"=".repeat(Math.max(0, 58 - title.length))}`);
 }
 async function testCommand(options) {
+  let config;
+  try {
+    config = applyUrlOverride(await loadConfig(options.cwd), options.url);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      console.error(`error: ${error.message}`);
+      return EXIT_USAGE;
+    }
+    throw error;
+  }
+  const budget = new RunBudget(resolveBudgetOptions(config, options));
   section("Verify: tests covering the affected routes");
   const runCode = await runCommand({
     cwd: options.cwd,
@@ -2029,7 +2479,8 @@ async function testCommand(options) {
     minScore: options.minScore,
     junit: options.junit,
     html: options.html,
-    failOnUnmapped: options.failOnUnmapped
+    failOnUnmapped: options.failOnUnmapped,
+    budget
   });
   if (runCode === EXIT_USAGE) return EXIT_USAGE;
   section("Draft: affected routes no test covers");
@@ -2037,7 +2488,8 @@ async function testCommand(options) {
     cwd: options.cwd,
     base: options.base,
     url: options.url,
-    write: options.write
+    write: options.write,
+    budget
   });
   if (planCode === EXIT_USAGE) return EXIT_USAGE;
   console.log(
@@ -2063,8 +2515,26 @@ function parseMinScore(value) {
   }
   return score;
 }
+function parsePositiveInt(flag) {
+  return (value) => {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new InvalidArgumentError(`${flag} must be a positive integer`);
+    }
+    return n;
+  };
+}
+function parsePositiveNumber(flag) {
+  return (value) => {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+      throw new InvalidArgumentError(`${flag} must be a positive number`);
+    }
+    return n;
+  };
+}
 var program = new Command();
-program.name("blastproof").description("Open-source AI testing agent: plain-English YAML tests executed agentically on a real browser.").version("0.2.2");
+program.name("blastproof").description("Open-source AI testing agent: plain-English YAML tests executed agentically on a real browser.").version("0.4.0");
 program.command("init").description("Scaffold .blastproof/ (config, tests, sample tests) in the current directory").action(async () => {
   try {
     const result = await initProject(process.cwd());
@@ -2079,7 +2549,19 @@ program.command("run").description("Discover and run all tests under .blastproof
   "--min-score <n>",
   "require a weighted score of at least n (0-100); replaces the all-must-pass rule",
   parseMinScore
-).option("--junit [path]", "write a JUnit XML report (default: .blastproof/reports/<session>/junit.xml)").option("--html [path]", "write a self-contained HTML report (default: .blastproof/reports/<session>/report.html)").option("--fail-on-unmapped", "fail when a changed file matches no routes: or ignore: glob").action(
+).option("--junit [path]", "write a JUnit XML report (default: .blastproof/reports/<session>/junit.xml)").option("--html [path]", "write a self-contained HTML report (default: .blastproof/reports/<session>/report.html)").option("--fail-on-unmapped", "fail when a changed file matches no routes: or ignore: glob").option(
+  "--max-llm-calls <n>",
+  "stop the run after this many model calls, reported as incomplete (overrides config)",
+  parsePositiveInt("--max-llm-calls")
+).option(
+  "--max-tokens <n>",
+  "stop the run after this many tokens spent across all model calls (overrides config)",
+  parsePositiveInt("--max-tokens")
+).option(
+  "--max-duration <seconds>",
+  "stop the run after this many seconds of wall-clock time (overrides config)",
+  parsePositiveNumber("--max-duration")
+).action(
   async (options) => {
     try {
       process.exitCode = await runCommand({
@@ -2094,7 +2576,10 @@ program.command("run").description("Discover and run all tests under .blastproof
         minScore: options.minScore,
         junit: options.junit,
         html: options.html,
-        failOnUnmapped: options.failOnUnmapped
+        failOnUnmapped: options.failOnUnmapped,
+        maxLlmCalls: options.maxLlmCalls,
+        maxTokens: options.maxTokens,
+        maxDuration: options.maxDuration
       });
     } catch (error) {
       console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
@@ -2102,25 +2587,58 @@ program.command("run").description("Discover and run all tests under .blastproof
     }
   }
 );
-program.command("plan").description("Generate plain-English YAML tests for affected routes no test covers yet").option("--base <ref>", "base git ref for the diff", "main").option("--url <url>", "override config base_url for this run only (config file untouched)").option("--route <route>", "generate for this route, bypassing the diff (repeatable)", collect, []).option("--write", "persist drafts under .blastproof/tests/ instead of previewing them").action(async (options) => {
-  try {
-    process.exitCode = await planCommand({
-      cwd: process.cwd(),
-      base: options.base,
-      url: options.url,
-      routes: options.route,
-      write: options.write
-    });
-  } catch (error) {
-    console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
-    process.exitCode = EXIT_USAGE;
+program.command("plan").description("Generate plain-English YAML tests for affected routes no test covers yet").option("--base <ref>", "base git ref for the diff", "main").option("--url <url>", "override config base_url for this run only (config file untouched)").option("--route <route>", "generate for this route, bypassing the diff (repeatable)", collect, []).option("--write", "persist drafts under .blastproof/tests/ instead of previewing them").option(
+  "--dry-run",
+  "print the routes that would generate drafts and exit without launching a browser or calling the LLM"
+).option(
+  "--max-llm-calls <n>",
+  "stop after this many model calls, reported as incomplete (overrides config)",
+  parsePositiveInt("--max-llm-calls")
+).option(
+  "--max-tokens <n>",
+  "stop after this many tokens spent across all model calls (overrides config)",
+  parsePositiveInt("--max-tokens")
+).option(
+  "--max-duration <seconds>",
+  "stop after this many seconds of wall-clock time (overrides config)",
+  parsePositiveNumber("--max-duration")
+).action(
+  async (options) => {
+    try {
+      process.exitCode = await planCommand({
+        cwd: process.cwd(),
+        base: options.base,
+        url: options.url,
+        routes: options.route,
+        write: options.write,
+        dryRun: options.dryRun,
+        maxLlmCalls: options.maxLlmCalls,
+        maxTokens: options.maxTokens,
+        maxDuration: options.maxDuration
+      });
+    } catch (error) {
+      console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+      process.exitCode = EXIT_USAGE;
+    }
   }
-});
+);
 program.command("test").description("Full PR pipeline: run the tests covering the diff, then draft tests for the gaps").option("--base <ref>", "base git ref for the diff", "main").option("--url <url>", "override config base_url for this run only (config file untouched)").option(
   "--min-score <n>",
   "require a weighted score of at least n (0-100); replaces the all-must-pass rule",
   parseMinScore
-).option("--junit [path]", "write a JUnit XML report (default: .blastproof/reports/<session>/junit.xml)").option("--html [path]", "write a self-contained HTML report (default: .blastproof/reports/<session>/report.html)").option("--write", "persist generated drafts under .blastproof/tests/ instead of previewing them").option("--fail-on-unmapped", "fail when a changed file matches no routes: or ignore: glob").action(
+).option("--junit [path]", "write a JUnit XML report (default: .blastproof/reports/<session>/junit.xml)").option("--html [path]", "write a self-contained HTML report (default: .blastproof/reports/<session>/report.html)").option("--write", "persist generated drafts under .blastproof/tests/ instead of previewing them").option("--fail-on-unmapped", "fail when a changed file matches no routes: or ignore: glob").option(
+  "--max-llm-calls <n>",
+  "stop the pipeline after this many model calls, shared by both phases (overrides config)",
+  parsePositiveInt("--max-llm-calls")
+).option(
+  "--max-tokens <n>",
+  "stop the pipeline after this many tokens, shared by both phases (overrides config)",
+  parsePositiveInt("--max-tokens")
+).option(
+  "--max-duration <seconds>",
+  "stop the pipeline after this many seconds of wall-clock time (overrides config)",
+  parsePositiveNumber("--max-duration")
+).action(
   async (options) => {
     try {
       process.exitCode = await testCommand({
@@ -2131,7 +2649,10 @@ program.command("test").description("Full PR pipeline: run the tests covering th
         junit: options.junit,
         html: options.html,
         write: options.write,
-        failOnUnmapped: options.failOnUnmapped
+        failOnUnmapped: options.failOnUnmapped,
+        maxLlmCalls: options.maxLlmCalls,
+        maxTokens: options.maxTokens,
+        maxDuration: options.maxDuration
       });
     } catch (error) {
       console.error(`error: ${error instanceof Error ? error.message : String(error)}`);