fix(billing): surface the upgrade gate on codex billing denials

The codex adapter resolved every non-retried fatal error as a silent
refusal, so a free-tier org's gateway 403/429 died with a warning badge and
no explanation. A fatal error that classifies as a gateway billing denial
now rejects the prompt with the gateway's message, which the host already
classifies into the upgrade modal.

Generated-By: PostHog Code
Task-Id: 1039ea23-9930-44e2-9888-b05cf8b129ec

Author: adboio

packages/agent/src/adapters/codex-app-server/codex-app-server-agent.test.ts

@@ -1596,6 +1596,32 @@ describe("CodexAppServerAgent", () => {
     expect((await done).stopReason).toBe("refusal");
   });
 
+  it("rejects the prompt when the fatal error is a gateway billing denial", async () => {
+    // A silent refusal would hide the free-tier gate: the host only shows the
+    // upgrade modal when the prompt rejects with the gateway's message.
+    const stub = makeStubRpc({ "thread/start": { thread: { id: "t" } } });
+    const { client } = makeFakeClient();
+    const agent = new CodexAppServerAgent(client, {
+      processOptions: { binaryPath: "/x/codex" },
+      rpcFactory: stub.factory,
+    });
+
+    await agent.newSession({ cwd: "/r" } as unknown as NewSessionRequest);
+    const done = agent.prompt({
+      sessionId: "t",
+      prompt: [{ type: "text", text: "go" }],
+    } as unknown as PromptRequest);
+    stub.emit("error", {
+      willRetry: false,
+      error: {
+        message:
+          "unexpected status 403 Forbidden: Model 'gpt-5.5' needs a paid PostHog plan. Models available on the free tier: @cf/zai-org/glm-5.2. (rate_limit)",
+      },
+    });
+
+    await expect(done).rejects.toThrow("needs a paid PostHog plan");
+  });
+
   it("ends the turn without turn/start when no prompt block is usable", async () => {
     const stub = makeStubRpc({ "thread/start": { thread: { id: "t" } } });
     const { client } = makeFakeClient();

packages/agent/src/adapters/codex-app-server/codex-app-server-agent.ts

@@ -19,7 +19,11 @@ import type {
   SetSessionConfigOptionResponse,
   StopReason,
 } from "@agentclientprotocol/sdk";
-import { mcpToolKey, posthogToolMeta } from "@posthog/shared";
+import {
+  classifyGatewayLimitError,
+  mcpToolKey,
+  posthogToolMeta,
+} from "@posthog/shared";
 import {
   type NativeGoalState,
   POSTHOG_NOTIFICATIONS,
@@ -1245,11 +1249,25 @@ export class CodexAppServerAgent extends BaseAcpAgent {
 
     if (method === APP_SERVER_NOTIFICATIONS.ERROR) {
       // A non-retried fatal error: resolve the turn so prompt() returns rather than hangs.
-      const willRetry = (params as { willRetry?: boolean })?.willRetry;
+      const { willRetry, error } = (params ?? {}) as {
+        willRetry?: boolean;
+        error?: { message?: string };
+      };
       if (willRetry === false) {
         this.logger.warn("codex app-server fatal error notification", {
           params,
         });
+        const message = error?.message ?? "";
+        // A gateway billing denial rejects the prompt so the host classifies
+        // it and shows the upgrade gate; a silent refusal would hide it.
+        if (classifyGatewayLimitError(message) !== null) {
+          if (this.compactionActive) {
+            this.compactionActive = false;
+            this.emitCompactionBoundary();
+          }
+          this.turns.fail(new Error(message));
+          return;
+        }
         void this.finalizeTurn("refusal");
       }
     }