fix(code-reviews): billing error classification (#1332)

## Summary

Billing errors from code reviews were being misclassified in two ways:
v1 billing errors arrived as `interrupted` and got normalized to
`cancelled` (hiding them from billing analytics), and v2 billing errors
had the real error message discarded by the wrapper, storing the generic
string `session.error` instead. This PR adds a `terminal_reason` column
to track failure categories, fixes both classification paths, posts
billing notices on PRs/MRs, and backfills ~13k historical rows.

Three layers of fixes:
- **Wrapper** (`cloud-agent-next`): passes the real billing error text
from `properties.error` instead of discarding it and forwarding just the
event type string.
- **normalizePayload** (status callback handler): detects billing
patterns in error messages when no explicit `terminalReason` is set,
reclassifying `cancelled` billing errors as `failed` with
`terminalReason: 'billing'`.
- **Orchestrator**: catches 402 billing errors from
`prepareSession`/`initiateSession`/`sendMessageV2`, tags them with
`terminalReason: 'billing'`, and prevents the sendMessage fallback from
retrying billing failures.

Also adds billing PR/MR comment notices, admin dashboard improvements
for billing vs. non-billing failure separation, and three backfill
migrations for historical data.

## Verification

- [x] `pnpm jest 'code-review-status.*route\.test'` — 17 tests pass (4
new: interrupted billing reclassification, failed billing inference,
non-billing interrupted preserved, explicit terminalReason preserved)
- [x] `pnpm typecheck` — passes across all workspace packages including
cloud-agent-next wrapper
- [x] Pre-push hooks passed (format, lint, typecheck)

## Visual Changes

N/A

## Reviewer Notes

- The v2 backfill migration (0057) uses exact `error_message =
'session.error'` matching rather than ILIKE patterns to avoid false
positives from branch names containing billing keywords.
- Migration 0056 already backfilled v1 `failed` billing rows (23,711
rows). Migration 0057 covers the remaining gaps: v1 `cancelled` billing
rows (~12,461) and v2 `session.error` rows (742).
- Deployment order matters: deploy the normalizePayload fix (Next.js)
first so it's ready to handle callbacks, then apply the backfill
migration, then deploy the wrapper fix (cloud-agent-next Worker).
- The `!terminalReason` guard in normalizePayload ensures the billing
inference only fires when no explicit reason was provided —
orchestrator-path billing errors (which already send `terminalReason:
'billing'`) are not double-handled.

Author: alex-alecu

cloud-agent-next/wrapper/src/connection.ts

@@ -273,6 +273,28 @@ export function createConnectionManager(
     return false;
   }
 
+  function getTerminalErrorText(eventType: string, properties: Record<string, unknown>): string {
+    const error = properties.error;
+    if (typeof error === 'string') {
+      return error;
+    }
+
+    if (isRecord(error)) {
+      if (typeof error.message === 'string') {
+        return error.message;
+      }
+
+      const data = error.data;
+      if (isRecord(data) && typeof data.message === 'string') {
+        return data.message;
+      }
+
+      return JSON.stringify(error);
+    }
+
+    return `Insufficient credits: ${eventType}`;
+  }
+
   /**
    * Start the SDK event subscription. Runs in the background.
    * Replaces the old SSE consumer with a typed event stream from the SDK.
@@ -367,7 +389,7 @@ export function createConnectionManager(
 
           // Terminal error detection
           if (isTerminalError(eventType, properties)) {
-            callbacks.onTerminalError(eventType);
+            callbacks.onTerminalError(getTerminalErrorText(eventType, properties));
             return;
           }
 

packages/db/src/migrations/0057_backfill_billing_misclassified.sql

@@ -0,0 +1,23 @@
+-- v1: cancelled billing reviews should be failed with terminal_reason='billing'
+-- These are from the cloud-agent callback path where payment_required_prompt
+-- was reported as 'interrupted' → normalized to 'cancelled'.
+UPDATE cloud_agent_code_reviews
+SET status = 'failed', terminal_reason = 'billing'
+WHERE status = 'cancelled'
+  AND terminal_reason IS NULL
+  AND (
+    COALESCE(error_message, '') ILIKE '%Insufficient credits%'
+    OR COALESCE(error_message, '') ILIKE '%paid model%'
+    OR COALESCE(error_message, '') ILIKE '%add credits%'
+    OR COALESCE(error_message, '') ILIKE '%Credits Required%'
+  );
+
+-- v2: wrapper terminal error path stored generic event type as error_message.
+-- The only path that produces error_message='session.error' is isTerminalError()
+-- in the wrapper, which exclusively triggers for billing/payment events.
+UPDATE cloud_agent_code_reviews
+SET terminal_reason = 'billing'
+WHERE status = 'failed'
+  AND terminal_reason IS NULL
+  AND agent_version = 'v2'
+  AND error_message = 'session.error';