fix(runner): stop reading a spend-limit refusal as retryable

Author: JAllen2022

docs/exit-codes.md

@@ -11,6 +11,7 @@ CI consumers depend on consistent exit codes. The CLI commits to the following c
 | `4`  | `network`     | Apex unreachable, GCS download failure, registry unreachable, or a runner that could not serve the request now (unreachable, or its screen not yet up).                                                                                                                                            |
 | `5`  | `config`      | `qawolf.config.ts` invalid, file collision during `init`, or a run file that could not be read.                                                                                                                                                                                                    |
 | `6`  | `timeout`     | A `--follow` reached its `--timeout`: `runner run` before its run settled (the run may still be going), or `runner events`.                                                                                                                                                                        |
+| `7`  | `payment`     | The QA Wolf API refused the request with HTTP 402: billing prevented it — the organization is over its monthly spend limit or has no valid payment method.                                                                                                                                         |
 
 ## Using the helper
 

src/core/messages/auth.ts

@@ -44,6 +44,8 @@ export const authMessages = {
     request: {
       rejected401: (noun: string | undefined) =>
         `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 401). Check your API key.`,
+      rejected402: (noun: string | undefined) =>
+        `QA Wolf API refused the${noun ? ` ${noun}` : ""} request (HTTP 402): billing prevented it.`,
       rejected403: (noun: string | undefined) =>
         `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 403). Check that your API key has access to this environment.`,
       notFound404: (noun: string | undefined) =>

src/domains/interactiveRunner/evaluateSnippet.spendLimit.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "bun:test";
+
+import { handleRunnerExec } from "./evaluateSnippet.js";
+import { makeAuthCtx, makeTestDeps } from "./deps.testUtils.js";
+
+describe("handleRunnerExec spend limit", () => {
+  it("keeps the payment exit code on a spend-limit refusal", async () => {
+    const { callPublicApi, ctx } = makeAuthCtx();
+    callPublicApi.mockResolvedValue({
+      error:
+        "QA Wolf API refused the runner.evaluateSnippet request (HTTP 402): billing prevented it.",
+      errorBody:
+        "You have reached your monthly limit of $50.00 for runner usage.",
+      exitCode: 7,
+      ok: false,
+    });
+
+    const result = await handleRunnerExec(
+      ctx,
+      { contextFile: undefined, runner: "ci", source: "flow.ts" },
+      makeTestDeps(),
+    );
+
+    expect(result?.errorBody).toContain("monthly limit");
+    expect(result?.exitCode).toBe(7);
+  });
+});

src/domains/interactiveRunner/evaluateSnippet.ts

@@ -111,7 +111,10 @@ export async function handleRunnerExec(
     runnerCallOptions,
   );
   if (!result.ok) {
-    return { ...failureFields(result), exitCode: exitCodes.network };
+    return {
+      ...failureFields(result),
+      exitCode: result.exitCode ?? exitCodes.network,
+    };
   }
 
   if (result.value.outcome === "failure") {

src/domains/interactiveRunner/importPackage.test.ts

@@ -149,4 +149,25 @@ describe("handleRunnerImportPackage", () => {
     expect(result?.error).toContain("Retry");
     expect(result?.exitCode).toBe(4);
   });
+
+  it("keeps the payment exit code on a spend-limit refusal", async () => {
+    const { callPublicApi, ctx } = makeAuthCtx();
+    callPublicApi.mockResolvedValue({
+      error:
+        "QA Wolf API refused the runner.importPackage request (HTTP 402): billing prevented it.",
+      errorBody:
+        "You have reached your monthly limit of $50.00 for runner usage.",
+      exitCode: 7,
+      ok: false,
+    });
+
+    const result = await handleRunnerImportPackage(
+      ctx,
+      { name: "dayjs", runner: "ci", version: undefined },
+      depsWithManifest(),
+    );
+
+    expect(result?.errorBody).toContain("monthly limit");
+    expect(result?.exitCode).toBe(7);
+  });
 });

src/domains/interactiveRunner/importPackage.ts

@@ -81,7 +81,10 @@ export async function handleRunnerImportPackage(
     runnerCallOptions,
   );
   if (!result.ok) {
-    return { ...failureFields(result), exitCode: exitCodes.network };
+    return {
+      ...failureFields(result),
+      exitCode: result.exitCode ?? exitCodes.network,
+    };
   }
 
   if (result.value.outcome === "failure") {

src/domains/interactiveRunner/launchAndRemember.ts

@@ -36,7 +36,7 @@ async function launchRunner(
   if (!result.ok) {
     return {
       ...failureFields(result),
-      exitCode: exitCodes.network,
+      exitCode: result.exitCode ?? exitCodes.network,
       mayHaveArrived: result.mayHaveArrived ?? false,
       ok: false,
     };

src/domains/interactiveRunner/sendRunFlowRequest.ts

@@ -60,7 +60,10 @@ export async function sendRunFlowRequest(
   );
   if (!result.ok) {
     return {
-      failure: { ...failureFields(result), exitCode: exitCodes.network },
+      failure: {
+        ...failureFields(result),
+        exitCode: result.exitCode ?? exitCodes.network,
+      },
       type: "failed",
     };
   }

src/shell/exit.test.ts

@@ -59,6 +59,7 @@ describe("exit", () => {
       network: 4,
       config: 5,
       timeout: 6,
+      payment: 7,
     });
   });
 });

src/shell/exit.ts

@@ -6,6 +6,7 @@ export const exitCodes = {
   network: 4,
   config: 5,
   timeout: 6,
+  payment: 7,
 } as const;
 
 type ExitCode = (typeof exitCodes)[keyof typeof exitCodes];